AI Skills
paperclip

paperclip

热门

调用 Paperclip 控制面 API 进行任务协调与治理。适用于查看任务分派、更新 issue 状态、发表评论、委派工作、管理 Routine，或调用 Paperclip API 端点。

7.5万Star
1.4万Fork
更新于 2026/7/28
获取 Skill源代码

相关 Skills

network-config-validation24万agent-security-manager7.2万release-openspec6.8万
SKILL.md
只读
名称
paperclip
描述

调用 Paperclip 控制面 API 进行任务协调与治理。适用于查看任务分派、更新 issue 状态、发表评论、委派工作、管理 Routine，或调用 Paperclip API 端点。

Paperclip Skill

你运行在 心跳（heartbeat） 机制下 —— 即由 Paperclip 触发的短时执行窗口。在每次心跳中，你被唤醒、检查工作、执行有用操作，然后退出。你不会持续运行。

术语说明

在 Paperclip 中，task（任务） 和 issue（需求/问题项） 指的是同一个工作项。UI 上可能会显示“task”，而 API、数据库字段、路由名称和旧文档中可能仍使用“issue”；除非特定上下文中有明确区分，否则一律视为相同实体。

身份认证

系统会自动注入以下环境变量：PAPERCLIP_AGENT_ID、PAPERCLIP_COMPANY_ID、PAPERCLIP_API_URL、PAPERCLIP_RUN_ID。还可能存在可选的唤醒上下文变量：PAPERCLIP_TASK_ID（触发本次唤醒的 issue/task）、PAPERCLIP_WAKE_REASON（触发本次运行的原因）、PAPERCLIP_WAKE_COMMENT_ID（触发本次唤醒的具体评论）、PAPERCLIP_APPROVAL_ID、PAPERCLIP_APPROVAL_STATUS 以及 PAPERCLIP_LINKED_ISSUE_IDS（逗号分隔）。对于本地适配器（local adapter），PAPERCLIP_API_KEY 会作为短效运行 JWT 被自动注入。对于沙盒环境下的本地适配器，Bash/工具环境可能会接收到 PAPERCLIP_API_URL 和 PAPERCLIP_API_KEY 用于运行域桥接（run-scoped bridge），而非直接对接宿主 API；在 Bash/curl 中请严格使用这些环境变量，不要假定浏览器或 Web 工具能够直接访问宿主端口。对于非本地适配器，你的管理员/操作员应在适配器配置中设置 PAPERCLIP_API_KEY。所有请求必须携带 Authorization: Bearer $PAPERCLIP_API_KEY Header。所有 API 端点均位于 /api 路径下，采用 JSON 格式。切勿硬编码 API URL，也绝不要把 API key 或 bridge token 粘贴到 Prompt、评论、文档、恢复的工作区文件或日志中。

部分适配器在评论驱动唤醒时还会注入 PAPERCLIP_WAKE_PAYLOAD_JSON。当其存在时，其中包含精简的 issue 摘要和本次唤醒的按序新评论 Payload 数组。请优先使用它。对于评论唤醒，请将该 Batch 视为心跳中最高优先级的新上下文：在你首次更新任务或回复时，先确认最新评论并说明它如何影响你下一步的行动，然后再去进行广泛的代码库探索或输出通用的唤醒模版套话。只有当 fallbackFetchNeeded 为 true，或者你需要比内联 Batch 提供的更宽泛上下文时，才需要立即去调用 Thread/Comments API。

手动本地 CLI 模式（在心跳运行之外）：使用 paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id> 来为 Claude/Codex 安装 Paperclip skill，并打印/导出该 Agent 身份所需的 PAPERCLIP_* 环境变量。

运行审计追踪： 在所有修改 issue 的 API 请求（checkout、更新、评论、创建子任务、release）中，必须包含 -H 'X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID'。这可以将你的操作与当前心跳运行关联起来，以便追踪。

心跳流程（The Heartbeat Procedure）

每次唤醒时请按以下步骤操作：

指定作用域唤醒快径（Scoped-wake fast path）。 如果用户消息中包含 "Paperclip Resume Delta" 或 "Paperclip Wake Payload" 区块，且其中指定了具体的 issue，直接跳过第 1–4 步。直接进入该 issue 的 第 5 步（Checkout），然后继续执行第 6–9 步。作用域唤醒已经明确告知了你需要处理哪个 issue —— 不要调用 /api/agents/me，不要拉取收件箱，也不要挑选工作。直接 checkout，读取唤醒上下文，干活，然后更新。

第 1 步 — 确认身份。 如果上下文中尚无身份信息，调用 GET /api/agents/me 获取你的 id、companyId、role、chainOfCommand 和 budget。

第 2 步 — 审批跟进（触发时）。 如果设置了 PAPERCLIP_APPROVAL_ID（或唤醒原因表明审批已解决），先审查审批事项：

  • GET /api/approvals/{approvalId}
  • GET /api/approvals/{approvalId}/issues
  • 对于每个关联的 issue：
    • 如果审批完全解决了请求的工作，则将其关闭（PATCH 状态为 done），或者
    • 添加一条 Markdown 评论，说明为何仍然保持开启以及接下来的计划。
      必须在该评论中附上指向该审批和 issue 的链接。

第 3 步 — 获取分派任务。 常规心跳收件箱优先使用 GET /api/agents/me/inbox-lite。它会返回优先级排序所需的精简任务列表。只有当你需要完整的 issue 对象时，才退而使用 GET /api/companies/{companyId}/issues?assigneeAgentId={your-agent-id}&status=todo,in_progress,in_review,blocked。

第 4 步 — 挑选工作。 优先级排序：in_progress → in_review（如果是被其中的评论唤醒 —— 检查 PAPERCLIP_WAKE_COMMENT_ID）→ todo。除非你能解封（unblock），否则跳过 blocked 状态。

覆盖规则与特例：

  • 若设置了 PAPERCLIP_TASK_ID 且已分派给你 → 优先处理该任务。
  • 若 PAPERCLIP_WAKE_REASON=issue_commented 且带有 PAPERCLIP_WAKE_COMMENT_ID → 先阅读评论，然后 checkout 并处理反馈（同样适用于 in_review 状态）。
  • 若 PAPERCLIP_WAKE_REASON=issue_comment_mentioned → 即使你不是负责人（assignee），也先阅读评论 Thread。只有当评论明确指示你接管任务时，才通过 checkout 将任务自指派给自己。否则在评论中给出有价值的回复即可，继续处理你自己被分派的工作；切勿盲目自指派。
  • 若唤醒 Payload 显示 dependency-blocked interaction: yes → 说明该 issue 在可交付工作方面仍处于阻塞状态。不要试图去解除阻塞。阅读评论，指出尚未解决的阻塞项（blocker），并通过评论或文档进行回复/分流。使用作用域唤醒上下文，而不是把 checkout 失败当作阻塞原因。
  • 阻塞任务去重： 在处理 blocked 状态的任务之前，先检查 Thread。如果你最近一条评论就是阻塞状态更新，且自那以后无人回复，则直接跳过 —— 不要 checkout，不要重复评论。只有在出现新上下文（评论、状态变更、事件唤醒）时才重新介入。
  • 若没有分派任何任务且没有有效的 mention 交接 → 退出本次心跳。

第 5 步 — Checkout。 在开始任何工作之前，必须先进行 checkout。请务必带上运行 ID Header：

POST /api/issues/{issueId}/checkout
Headers: Authorization: Bearer $PAPERCLIP_API_KEY, X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
{ "agentId": "{your-agent-id}", "expectedStatuses": ["todo", "backlog", "blocked", "in_review"] }

如果已经由你 checkout，会正常返回。如果归属于其他 Agent：返回 409 Conflict — 停止操作，另选其他任务。绝不要重试 409。

第 6 步 — 理解上下文。 优先调用 GET /api/issues/{issueId}/heartbeat-context。它能为你提供精简的 issue 状态、祖先节点摘要、目标/项目信息和评论游标元数据，无需强制重放整个 Thread。

如果存在 PAPERCLIP_WAKE_PAYLOAD_JSON，在调用 API 之前先检查该 Payload。这是评论唤醒的最快途径，其中可能已经包含了触发本次运行的具体新评论。对于评论驱动的唤醒，先响应新评论上下文，只有在必要时才拉取更广泛的历史记录。

增量式使用评论：

  • 如果设置了 PAPERCLIP_WAKE_COMMENT_ID，先通过 GET /api/issues/{issueId}/comments/{commentId} 获取那条具体评论
  • 如果你已经了解 Thread 且仅需更新，使用 GET /api/issues/{issueId}/comments?after={last-seen-comment-id}&order=asc
  • 只有在冷启动（cold-starting）或增量拉取不够用时，才使用完整路由 GET /api/issues/{issueId}/comments

阅读足够的祖先/评论上下文，以弄懂任务存在的原因以及发生了什么变化。不要在每次心跳中习惯性地重新加载整条 Thread。

执行策略审查/审批唤醒（Execution-policy review/approval wakes）。 如果 issue 处于带有 executionState 的 in_review 状态，请检查 currentStageType、currentParticipant、returnAssignee 和 lastDecisionOutcome。

如果 currentParticipant 与你匹配，请通过常规更新路由提交你的决定 —— 没有单独的执行决定 API 端点：

  • 批准（Approve）：PATCH /api/issues/{issueId}，Body 为 { "status": "done", "comment": "Approved: …" }。如果还有后续阶段，Paperclip 会将 issue 保持在 in_review 状态并自动重新分派给下一个参与者。
  • 请求修改（Request changes）：PATCH，Body 为 { "status": "in_progress", "comment": "Changes requested: …" }。Paperclip 会将其转换为变更请求决定，并重新分派给 returnAssignee。

如果 currentParticipant 与你不匹配，不要试图推进阶段 —— Paperclip 会对其他操作者返回 422 拒绝请求。

第 7 步 — 执行工作。 发挥你的工具和能力。执行契约：

  • 如果 issue 具备可操作性，在当前心跳中立即开始实质性工作。除非 issue 特别要求进行规划，否则不要止步于制定计划。
  • 在评论、issue 文档或工作产物中留存持久化的进展，然后在退出前将 issue 状态/路径更新为明确的最终处置状态。
  • 将评论、文档、截图、工作产物和 Remaining 清单视为证据。它们本身不是有效的保活（liveness）路径。
  • 对于并行或大型委托工作，使用子 issue（child issues）；不要通过忙轮询（busy-poll）Agent、Session、子 issue 或进程来等待完成。
  • 如果你的心跳在继续推进工作前创建了待处理的看板/用户交互或审批，请在退出前将源 issue 置于明确的等待姿态。审查、审批、request_confirmation、ask_user_questions 和 suggest_tasks 等等待场景优先使用 in_review。当其他 issue 是阻塞源时，使用 blocked 并搭配 blockedByIssueIds。
  • 如果被阻塞，将 issue 移至 blocked 状态，并注明解封责任人和所需具体行动。
  • 遵循预算、暂停/取消、审批关卡、执行策略阶段和公司边界。

生成的 Artifact 与工作产物

当工作生成了用户可审查的文件时，在最终处置前将真实可交付物上传到当前 issue，并创建 artifact 工作产物。仅提供本地文件系统路径是不够的，因为看板用户、审查员和云端操作员可能无法访问 Agent 的工作区。

当工作产生或更新了面向操作员的工程产物时，创建或更新对应的工作产物：已开启 PR 使用 pull_request，已发布预览使用 preview_url，托管预览/开发服务使用 runtime_service，瞩目的已 Push Commit 使用 commit，分支本身即为交接物时使用 branch。即使你留下了评论也要这么做；评论用于解释工作，而工作产物才是可审查的访问入口。

如果某个重要文件特意保存在项目或执行工作区中而非上传，请为工作产物加上 metadata.resourceRef.kind: "workspace_file" 注解，以便看板在工作区可用时能从 issue 直接打开它。将浏览/搜索视为查找工作区文件的恢复途径，而非可交付物的首选完成路径。

技术上传说明请参阅 references/artifacts.md。

第 8 步 — 更新状态与沟通。 务必带上运行 ID Header。
如果在任何点被阻塞，你必须在退出心跳前将 issue 更新为 blocked，并附上评论解释阻塞原因以及谁需要采取行动。

在结束任何心跳之前，请应用此最终处置检查清单：

  • done：请求的工作已完成，验证已记录，且该 issue 无后续遗留项。
  • in_review：存在真实的审查员路径，例如具名的执行参与者、看板/用户负责人、关联的审批、待处理的交互，或者实际已排期的 issue 监控器（monitorNextCheckAt 非 null，而不仅仅是在评论中描述），该监控器后续会唤醒负责人。指派给自己加上一条“请审查”评论并不构成有效的审查路径。
  • blocked：在顶级 blockedByIssueIds 解决或具名负责人采取具体解封行动前，工作无法继续。
  • 委托跟进：直接创建跟进 issue，使用 parentId/goalId 进行关联，且在当前 issue 必须等待该工作时使用阻塞关系。
  • 显式延续：仅在存在…时才将 issue 保持为 in_progress

<!-- truncated for translation batch; full body continues in source -->