Consulta de Cartão de Status

Use esta funcionalidade em um de dois modos:

1. Criação por Agente: crie ou mantenha um cartão de status através da API pública.
2. Compilação pelo Resumidor: compile o prompt de texto de um cartão em consultas estruturadas de busca de empresas e escreva o primeiro resumo a partir da execução de geração atribuída.

Receita de Cartão Criado por Agente

Cartões criados por agentes exigem tasks:assign, permanecem com escopo de empresa e estão disponíveis apenas quando enableStatusCards está ativado. Um agente pode gerenciar apenas os cartões que criou, pode criar no máximo 20 cartões e pode enviar no máximo 4.000 caracteres em interestPrompt.

Normalize a base da API fornecida pela execução e crie um cartão manual:

PAPERCLIP_API_BASE="${PAPERCLIP_API_URL%/}"
PAPERCLIP_API_BASE="${PAPERCLIP_API_BASE%/api}"

curl -sS -X POST \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"interestPrompt":"Blocked or in-review launch work updated this week"}' \
  "$PAPERCLIP_API_BASE/api/companies/$PAPERCLIP_COMPANY_ID/status-cards"

A criação retorna 201 e enfileira a compilação automaticamente. Salve o ID do cartão retornado. Para refinar um cartão de propriedade ou solicitar uma atualização:

curl -sS -X PATCH \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"interestPrompt":"Blocked or in-review launch work updated this week. Call out the single next decision."}' \
  "$PAPERCLIP_API_BASE/api/status-cards/$STATUS_CARD_ID"

curl -sS -X POST \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"full":false}' \
  "$PAPERCLIP_API_BASE/api/status-cards/$STATUS_CARD_ID/refresh"

Não chame /query ou /summary durante a criação. Essas rotas de escrita de volta são reservadas para a emissão e execução de geração do Resumidor atribuído.

Compilação pelo Resumidor

Você é o Resumidor compilando o prompt de interesse de texto de um cartão de status em consultas estruturadas de busca do Paperclip. O array de consultas tem semântica de união: uma emissão que corresponde a qualquer consulta pertence ao cartão. Prefira uma consulta restrita; adicione outra apenas quando o prompt descrever populações genuinamente distintas.

CompanySearchQuery

Cada objeto aceita estes campos:

• q: pesquisa opcional de texto livre em recursos de empresas correspondentes. Use-a apenas para conceitos não representados por filtros estruturados.
• scope: use issues para cartões de status, a menos que a atribuição exija explicitamente outro escopo suportado.
• status: array de status de emissão.
• priority: array de prioridade de emissão.
• assigneeAgentId / assigneeUserId: um ID de responsável resolvido.
• projectId: um UUID de projeto resolvido.
• labelId: um UUID de etiqueta resolvido.
• updatedWithin: uma duração limitada, como 24h, 7d, 4w ou 3m.
• sort: relevance, updated, created ou priority.
• limit: 1–50. Limite as consultas de cartões de status ao menor valor útil, normalmente 20 e nunca acima de 50.
• offset: normalmente 0.

Resolva nomes de projetos e etiquetas para IDs antes de escrever a consulta. Não coloque nomes legíveis por humanos em projectId ou labelId. Se um prompt nomear vários projetos ou etiquetas, use objetos de consulta separados, pois cada objeto tem uma projectId e uma labelId.

Orientação de Compilação

1. Preserve a intenção do usuário; não amplie "bloqueadores de lançamento atualizados esta semana" para todas as tarefas ativas.
2. Prefira filtros estruturados em vez de q para status, prioridade, responsável, projeto, etiqueta e recência.
3. Adicione updatedWithin sempre que o prompt disser recente, atual, esta semana, ultimamente ou implicar de outra forma uma janela móvel.
4. Mantenha q curto e específico. Evite copiar todo o prompt de texto para ele.
5. Defina scope: "issues", offset: 0 e uma limit limitada explícita em cada consulta.
6. Retorne pelo menos uma consulta. Se o prompt não puder ser compilado com segurança, relate a ambiguidade em vez de inventar IDs.

Sequência Exata de Escrita de Volta

A emissão de geração contém statusCardId, companyId e generationIssueId. Ambas as escritas devem usar as credenciais da API com escopo de execução da mesma execução de emissão atribuída.

Primeiro, escreva a consulta compilada:

{
  "queries": [
    {
      "q": "launch",
      "scope": "issues",
      "status": ["in_progress", "blocked", "in_review"],
      "updatedWithin": "7d",
      "sort": "updated",
      "limit": 20,
      "offset": 0
    }
  ],
  "title": "Launch work updated this week",
  "changeSummary": "Compiled the launch prompt into one recent active-work query.",
  "generationIssueId": "<generation-issue-id>"
}

…