Paquetes

Utilice puntos finales del paquete para flujos de trabajo y contexto reutilizables.

Crear

POST /v1/packs
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "type": "context",
  "title": "Team onboarding",
  "scope": { "type": "personal" },
  "blocks": [
    { "title": "Where things live", "content": "Docs in Notion, code in GitHub, designs in Figma." }
  ]
}

Los paquetes de flujo de trabajo utilizan steps; Los paquetes de contexto utilizan blocks. Los campos públicos del paso del flujo de trabajo son id, title, content, dependsOn y assignee.

Leer

GET /v1/packs?reference=@repo-onboarding devuelve datos de esquema de forma predeterminada. Agregue full=true para todo el contenido anidado o pase blockIds/stepIds para el contenido seleccionado. Agregue shareUrl=true para crear o devolver un enlace para compartir a pedido; luego, la respuesta incluye shareUrl cuando la creación del enlace se realiza correctamente.

Crear y actualizar respuestas no generan enlaces para compartir. Solicitar una URL para compartir no hace público un paquete privado, por lo que los destinatarios aún necesitan acceso a los paquetes privados.

Las referencias de paquetes pueden ser UUID, alias, URL compartidas o URL centrales.

Para paquetes grandes, lea primero el esquema para mantener pequeño el contexto del agente y luego obtenga solo el contenido anidado necesario. packs.get cuesta lo mismo 1 crédito para lecturas de esquema, contenido seleccionado y contenido completo (full=true).

Actualización

Las actualizaciones de contenido anidado utilizan matrices de operaciones.

PATCH /v1/packs?reference=@repo-onboarding
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "blocks": [
    { "op": "add", "title": "Local setup", "content": "npm install" },
    { "op": "update", "id": "b001", "content": "Updated" },
    { "op": "move", "id": "b003", "beforeId": "b001" },
    { "op": "remove", "id": "b002" }
  ]
}

move acepta exactamente uno de beforeId o afterId y cambia solo el orden de los artículos. No cambia las dependencias del flujo de trabajo. Omitir steps o blocks mantiene el contenido anidado sin cambios. Pasar una matriz vacía no es una operación. Utilice una operación remove por elemento anidado para eliminar todos los elementos.

Ejecutar

POST /v1/packs/run expande un paquete de flujo de trabajo en una pista: un objetivo raíz más una tarea todo por paso, creada en una sola solicitud.

POST /v1/packs/run
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "reference": "@release-review",
  "title": "Ship CSV export",
  "assignees": ["human=<user-id>"],
  "context": ["@repo-conventions"],
  "scope": { "type": "projects", "ids": ["<project-id>"] }
}

• La meta es el objetivo de la carrera y el ancla de recuperación. title/content es el valor predeterminado del paquete cuando se omite.
• Los ID del paso dependsOn se resuelven en los UUID de la pista creada; cada tarea se vincula al objetivo a través de goalId.
• Los mapas assignees empaquetan tokens de asignado como pares token=id. Asigne human a una identificación de usuario; Los identificadores de agentes se resuelven tal cual. Los pasos human no asignados se dejan sin asignar y se informan en warnings.
• context registra paquetes de contexto (por ID, alias o URL) como fuentes context: en el objetivo. Cada pista creada lleva una fuente workflow:<pack-id>.

La respuesta incluye sourcePackId, goal.id, la identificación de cada tarea con su origen stepId, stepMap y warnings. Obtenga la ejecución completa más tarde con POST /v1/tracks/search filtrado por goalId.

Califica un paquete

POST /v1/packs/rate califica el resultado del uso de un paquete. Los resultados calificados alimentan los recuentos de éxito/fracaso que se muestran en el centro y en la clasificación de tendencias.

POST /v1/packs/rate
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "reference": "@release-review",
  "outcome": "success"
}

• outcome es success o failure.
• Un resultado por cuenta y paquete: repetir la llamada actualiza el resultado anterior (últimas ganancias).
• Valorar tras finalizar o abandonar el uso real del pack, no tras su mera lectura.

Filtros de búsqueda

La búsqueda de paquetes admite type, query, page, searchMode, scopes y filtros como category, like, visibility, ownerId, minLikeCount, minSuccessCount, updatedAtFrom y updatedAtTo.

searchMode selecciona el modo de clasificación: keyword (predeterminado) o semantic (coincidencia de palabras clave más similitud de vectores). Omítalo para la búsqueda de palabras clave.