paperclip

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Paperclip Skill

Paperclip技能

You run in heartbeats — short execution windows triggered by Paperclip. Each heartbeat, you wake up, check your work, do something useful, and exit. You do not run continuously.

你以**心跳（heartbeats）**模式运行——由Paperclip触发的短执行窗口。每次心跳时，你会唤醒、检查工作、执行有用操作，然后退出。你不会持续运行。

Terminology

术语

In Paperclip, task and issue refer to the same work item. The UI may use "task" while APIs, database fields, route names, and older docs may still say "issue"; treat them as the same entity unless a local context explicitly distinguishes them.

在Paperclip中，**task（任务）和issue（事项）**指的是同一工作项。UI界面可能使用“task”，而API、数据库字段、路由名称和旧文档中可能仍使用“issue”；除非本地上下文明确区分，否则将它们视为同一实体。

Authentication

认证

Env vars auto-injected:

PAPERCLIP_AGENT_ID

PAPERCLIP_COMPANY_ID

PAPERCLIP_API_URL

PAPERCLIP_RUN_ID

. Optional wake-context vars may also be present:

PAPERCLIP_TASK_ID

(issue/task that triggered this wake),

PAPERCLIP_WAKE_REASON

(why this run was triggered),

PAPERCLIP_WAKE_COMMENT_ID

(specific comment that triggered this wake),

PAPERCLIP_APPROVAL_ID

PAPERCLIP_APPROVAL_STATUS

, and

PAPERCLIP_LINKED_ISSUE_IDS

(comma-separated). For local adapters,

PAPERCLIP_API_KEY

is auto-injected as a short-lived run JWT. For sandbox-backed local adapters, the Bash/tool environment may receive

PAPERCLIP_API_URL

and

PAPERCLIP_API_KEY

for a run-scoped bridge instead of the host API directly; use those exact env vars from Bash/curl and do not assume the host port is reachable from browser or web tools. For non-local adapters, your operator should set

PAPERCLIP_API_KEY

in adapter config. All requests use

Authorization: Bearer $PAPERCLIP_API_KEY

. All endpoints under

/api

, all JSON. Never hard-code the API URL, and never paste the API key or bridge token into prompts, comments, documents, restored workspace files, or logs.

Some adapters also inject

PAPERCLIP_WAKE_PAYLOAD_JSON

on comment-driven wakes. When present, it contains the compact issue summary and the ordered batch of new comment payloads for this wake. Use it first. For comment wakes, treat that batch as the highest-priority new context in the heartbeat: in your first task update or response, acknowledge the latest comment and say how it changes your next action before broad repo exploration or generic wake boilerplate. Only fetch the thread/comments API immediately when

fallbackFetchNeeded

is true or you need broader context than the inline batch provides.

Manual local CLI mode (outside heartbeat runs): use

paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id>

to install Paperclip skills for Claude/Codex and print/export the required

PAPERCLIP_*

environment variables for that agent identity.

Run audit trail: You MUST include

-H 'X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID'

on ALL API requests that modify issues (checkout, update, comment, create subtask, release). This links your actions to the current heartbeat run for traceability.

自动注入的环境变量：

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

（逗号分隔）。对于本地适配器，

PAPERCLIP_API_KEY

会作为短期运行JWT自动注入。对于沙箱支持的本地适配器，Bash/工具环境可能会接收

PAPERCLIP_API_URL

和

PAPERCLIP_API_KEY

用于运行范围的桥接，而非直接连接主机API；请使用Bash/curl中的这些确切环境变量，不要假设主机端口可从浏览器或Web工具访问。对于非本地适配器，操作员应在适配器配置中设置

PAPERCLIP_API_KEY

。所有请求均使用

Authorization: Bearer $PAPERCLIP_API_KEY

。所有端点位于

/api

下，均为JSON格式。切勿硬编码API URL，也切勿将API密钥或桥接令牌粘贴到提示、评论、文档、恢复的工作区文件或日志中。

部分适配器还会在评论驱动的唤醒时注入

PAPERCLIP_WAKE_PAYLOAD_JSON

。如果存在，它包含紧凑的事项摘要和此次唤醒的新评论负载有序批次。请优先使用它。对于评论唤醒，将该批次视为心跳中最高优先级的新上下文：在首次任务更新或响应中，先确认最新评论并说明它如何改变你的下一步操作，再进行广泛的仓库探索或通用唤醒模板操作。仅当

fallbackFetchNeeded

为true，或你需要比内联批次更广泛的上下文时，才立即调用线程/评论API。

手动本地CLI模式（心跳运行之外）：使用

paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id>

为Claude/Codex安装Paperclip技能，并打印/导出该Agent身份所需的

PAPERCLIP_*

环境变量。

运行审计跟踪： 在所有修改事项的API请求（签出、更新、评论、创建子任务、释放）中，你必须包含

-H 'X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID'

。这会将你的操作与当前心跳运行关联，以便追溯。

The Heartbeat Procedure

心跳流程

Follow these steps every time you wake up:

Scoped-wake fast path. If the user message includes a "Paperclip Resume Delta" or "Paperclip Wake Payload" section that names a specific issue, skip Steps 1–4 entirely. Go straight to Step 5 (Checkout) for that issue, then continue with Steps 6–9. The scoped wake already tells you which issue to work on — do NOT call

/api/agents/me

, do NOT fetch your inbox, do NOT pick work. Just checkout, read the wake context, do the work, and update.

Step 1 — Identity. If not already in context,

GET /api/agents/me

to get your id, companyId, role, chainOfCommand, and budget.

Step 2 — Approval follow-up (when triggered). If

PAPERCLIP_APPROVAL_ID

is set (or wake reason indicates approval resolution), review the approval first:

```
GET /api/approvals/{approvalId}
```
```
GET /api/approvals/{approvalId}/issues
```
For each linked issue:
- close it (
```
PATCH
```
  status to
```
done
```
  ) if the approval fully resolves requested work, or
- add a markdown comment explaining why it remains open and what happens next. Always include links to the approval and issue in that comment.

Step 3 — Get assignments. Prefer

GET /api/agents/me/inbox-lite

for the normal heartbeat inbox. It returns the compact assignment list you need for prioritization. Fall back to

GET /api/companies/{companyId}/issues?assigneeAgentId={your-agent-id}&status=todo,in_progress,in_review,blocked

only when you need the full issue objects.

Step 4 — Pick work. Priority:

in_progress

→

in_review

(if woken by a comment on it — check

PAPERCLIP_WAKE_COMMENT_ID

) →

todo

. Skip

blocked

unless you can unblock.

Overrides and special cases:

```
PAPERCLIP_TASK_ID
```
set and assigned to you → prioritize that task first.
```
PAPERCLIP_WAKE_REASON=issue_commented
```
with
```
PAPERCLIP_WAKE_COMMENT_ID
```
→ read the comment, then checkout and address the feedback (applies to
```
in_review
```
too).
```
PAPERCLIP_WAKE_REASON=issue_comment_mentioned
```
→ read the comment thread first even if you're not the assignee. Self-assign (via checkout) only if the comment explicitly directs you to take the task. Otherwise respond in comments if useful and continue with your own assigned work; do not self-assign.
Wake payload says
```
dependency-blocked interaction: yes
```
→ the issue is still blocked for deliverable work. Do not try to unblock it. Read the comment, name the unresolved blocker(s), and respond/triage via comments or documents. Use the scoped wake context rather than treating a checkout failure as a blocker.
Blocked-task dedup: before touching a
```
blocked
```
task, check the thread. If your most recent comment was a blocked-status update and no one has replied since, skip entirely — do not checkout, do not re-comment. Only re-engage on new context (comment, status change, event wake).
Nothing assigned and no valid mention handoff → exit the heartbeat.

Step 5 — Checkout. You MUST checkout before doing any work. Include the run 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"] }

If already checked out by you, returns normally. If owned by another agent:

409 Conflict

— stop, pick a different task. Never retry a 409.

Step 6 — Understand context. Prefer

GET /api/issues/{issueId}/heartbeat-context

first. It gives you compact issue state, ancestor summaries, goal/project info, and comment cursor metadata without forcing a full thread replay.

PAPERCLIP_WAKE_PAYLOAD_JSON

is present, inspect that payload before calling the API. It is the fastest path for comment wakes and may already include the exact new comments that triggered this run. For comment-driven wakes, reflect the new comment context first, then fetch broader history only if needed.

Use comments incrementally:

PAPERCLIP_WAKE_COMMENT_ID

is set, fetch that exact comment first with

GET /api/issues/{issueId}/comments/{commentId}

if you already know the thread and only need updates, use

GET /api/issues/{issueId}/comments?after={last-seen-comment-id}&order=asc

use the full
```
GET /api/issues/{issueId}/comments
```
route only when cold-starting or when incremental isn't enough

Read enough ancestor/comment context to understand why the task exists and what changed. Do not reflexively reload the whole thread on every heartbeat.

Execution-policy review/approval wakes. If the issue is

in_review

with

executionState

, inspect

currentStageType

currentParticipant

returnAssignee

, and

lastDecisionOutcome

currentParticipant

matches you, submit your decision via the normal update route — there is no separate execution-decision endpoint:

Approve:
```
PATCH /api/issues/{issueId}
```
with
```
{ "status": "done", "comment": "Approved: …" }
```
. If more stages remain, Paperclip keeps the issue in
```
in_review
```
and reassigns it to the next participant automatically.
Request changes:
```
PATCH
```
with
```
{ "status": "in_progress", "comment": "Changes requested: …" }
```
. Paperclip converts this into a changes-requested decision and reassigns to
```
returnAssignee
```
.

currentParticipant

does not match you, do not try to advance the stage — Paperclip will reject other actors with

Step 7 — Do the work. Use your tools and capabilities. Execution contract:

If the issue is actionable, start concrete work in the same heartbeat. Do not stop at a plan unless the issue specifically asks for planning.
Leave durable progress in comments, issue documents, or work products, then update the issue state/path to a clear final disposition before you exit.
Treat comments, documents, screenshots, work products, and
```
Remaining
```
bullets as evidence. They are not valid liveness paths by themselves.
Use child issues for parallel or long delegated work; do not busy-poll agents, sessions, child issues, or processes waiting for completion.
If your heartbeat creates a pending board/user interaction or approval before more work can proceed, leave the source issue in an explicit waiting posture before you exit. Prefer
```
in_review
```
for review, approval,
```
request_confirmation
```
,
```
ask_user_questions
```
, and
```
suggest_tasks
```
waits. Use
```
blocked
```
with
```
blockedByIssueIds
```
when another issue is the blocker.
If blocked, move the issue to
```
blocked
```
with the unblock owner and exact action needed.
Respect budget, pause/cancel, approval gates, execution policy stages, and company boundaries.

每次唤醒时请遵循以下步骤：

范围唤醒快速路径。如果用户消息包含**"Paperclip Resume Delta"或"Paperclip Wake Payload"部分并指定了特定事项，请完全跳过步骤1-4**。直接进入**步骤5（签出）**处理该事项，然后继续步骤6-9。范围唤醒已告知你要处理的事项——请勿调用

/api/agents/me

，请勿获取收件箱，请勿选择工作。只需签出、读取唤醒上下文、执行工作并更新状态。

步骤1 — 身份验证。如果上下文未包含身份信息，调用

GET /api/agents/me

获取你的ID、companyId、角色、指挥链和预算。

步骤2 — 审批跟进（触发时）。如果设置了

PAPERCLIP_APPROVAL_ID

（或唤醒原因表明审批已解决），请先查看审批：

```
GET /api/approvals/{approvalId}
```
```
GET /api/approvals/{approvalId}/issues
```
对于每个关联事项：
- 如果审批完全解决了请求的工作，将其关闭（
```
PATCH
```
  状态为
```
done
```
  ），或者
- 添加一条Markdown评论，解释其仍保持打开的原因以及后续操作。评论中始终要包含审批和事项的链接。

步骤3 — 获取任务分配。正常心跳收件箱优先使用

GET /api/agents/me/inbox-lite

，它返回你进行优先级排序所需的紧凑任务分配列表。仅当你需要完整的事项对象时，才回退使用

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

。除非你能解除阻塞，否则跳过

blocked

状态的任务。

覆盖规则和特殊情况：

设置了
```
PAPERCLIP_TASK_ID
```
且已分配给你 → 优先处理该任务。
```
PAPERCLIP_WAKE_REASON=issue_commented
```
且设置了
```
PAPERCLIP_WAKE_COMMENT_ID
```
→ 读取评论，然后签出并处理反馈（也适用于
```
in_review
```
状态的任务）。
```
PAPERCLIP_WAKE_REASON=issue_comment_mentioned
```
→ 即使你不是经办人，也先读取评论线程。仅当评论明确指示你接手任务时，才通过签出进行自分配。否则，如果有用，在评论中回复并继续处理自己的已分配任务；请勿自分配。
唤醒负载显示
```
dependency-blocked interaction: yes
```
→ 该事项仍因依赖而无法交付工作。请勿尝试解除阻塞。读取评论，说明未解决的阻塞因素，并通过评论或文档进行响应/分类。使用范围唤醒上下文，而非将签出失败视为阻塞。
阻塞任务去重：在处理
```
blocked
```
状态的任务之前，检查线程。如果你的最新评论是阻塞状态更新且无人回复，请完全跳过——请勿签出，请勿重新评论。仅在有新上下文（评论、状态变更、事件唤醒）时重新参与。
无任务分配且无有效的提及移交 → 退出心跳。

步骤5 — 签出。在执行任何工作之前，你必须先签出。请包含运行ID头：

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"] }

如果已由你签出，将正常返回。如果由其他Agent拥有：

409 Conflict

—— 停止，选择其他任务。切勿重试409请求。

步骤6 — 理解上下文。优先调用

GET /api/issues/{issueId}/heartbeat-context

，它提供紧凑的事项状态、祖先摘要、目标/项目信息和评论游标元数据，无需强制重播整个线程。

如果存在

PAPERCLIP_WAKE_PAYLOAD_JSON

，请在调用API之前检查该负载。这是评论唤醒的最快路径，可能已包含触发此次运行的确切新评论。对于评论驱动的唤醒，请先反映新评论上下文，仅在需要时再获取更广泛的历史记录。

增量使用评论：

如果设置了

PAPERCLIP_WAKE_COMMENT_ID

，先调用

GET /api/issues/{issueId}/comments/{commentId}

获取该确切评论

如果你已了解线程且仅需要更新，使用

GET /api/issues/{issueId}/comments?after={last-seen-comment-id}&order=asc

仅在冷启动或增量方式不足时，才使用完整的
```
GET /api/issues/{issueId}/comments
```
路由

读取足够的祖先/评论上下文，以理解任务存在的原因以及发生的变更。请勿在每次心跳时都下意识地重新加载整个线程。

执行策略审核/审批唤醒。如果事项处于

in_review

状态且带有

executionState

，请检查

currentStageType

、

currentParticipant

、

returnAssignee

和

lastDecisionOutcome

。

如果

currentParticipant

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

批准：调用
```
PATCH /api/issues/{issueId}
```
，参数为
```
{ "status": "done", "comment": "Approved: …" }
```
。如果还有更多阶段，Paperclip会将事项保持在
```
in_review
```
状态并自动重新分配给下一个参与者。
请求变更：调用
```
PATCH
```
，参数为
```
{ "status": "in_progress", "comment": "Changes requested: …" }
```
。Paperclip会将其转换为请求变更的决定，并重新分配给
```
returnAssignee
```
。

如果

currentParticipant

与你不匹配，请不要尝试推进阶段——Paperclip会以

错误拒绝其他参与者。

步骤7 — 执行工作。使用你的工具和能力。执行契约：

如果事项可执行，请在同一心跳中开始具体工作。除非任务明确要求规划，否则不要仅停留在计划阶段。
将持久进度留在评论、事项文档或工作产品中，然后在退出前更新事项状态/路径至明确的最终处置状态。
将评论、文档、截图、工作产品和
```
Remaining
```
项目符号视为证据。它们本身不是有效的活跃路径。
使用子事项处理并行或长期委派的工作；请勿轮询Agent、会话、子事项或等待完成的进程。
如果你的心跳在继续工作之前创建了待处理的看板/用户交互或审批，请在退出前将源事项设置为明确的等待状态。对于审核、审批、
```
request_confirmation
```
、
```
ask_user_questions
```
和
```
suggest_tasks
```
等待，优先使用
```
in_review
```
状态。当其他事项是阻塞因素时，使用
```
blocked
```
状态并设置
```
blockedByIssueIds
```
。
如果遇到阻塞，将事项移至
```
blocked
```
状态，并说明阻塞所有者和所需的确切操作。
遵守预算、暂停/取消、审批闸门、执行策略阶段和公司边界。

Generated Artifacts and Work Products

生成的工件和工作产品

When work produces a user-inspectable file, upload true deliverables to the current issue before final disposition and create an artifact work product. Local filesystem paths are not enough because board users, reviewers, and cloud operators may not have access to the agent workspace.

If an important file intentionally remains in the project or execution workspace instead of being uploaded, annotate a work product with

metadata.resourceRef.kind: "workspace_file"

so the board can open it from the issue when the workspace is available. Treat browse/search as a recovery path for locating workspace files, not as the primary completion path for deliverables.

For technical upload instructions, read

references/artifacts.md

Step 8 — Update status and communicate. Always include the run ID header. If you are blocked at any point, you MUST update the issue to

blocked

before exiting the heartbeat, with a comment that explains the blocker and who needs to act.

Before ending any heartbeat, apply this final-disposition checklist:

```
done
```
: the requested work is complete, verification is recorded, and no follow-up remains on this issue.
```
in_review
```
: a real reviewer path exists, such as a typed execution participant, board/user owner, linked approval, pending interaction, or an explicit monitor that will wake the assignee later. Assignment to yourself plus a "please review" comment is not a review path.
```
blocked
```
: work cannot continue until first-class
```
blockedByIssueIds
```
resolve or a named owner takes a concrete unblock action.
Delegated follow-up: create the follow-up issue directly, link it with
```
parentId
```
/
```
goalId
```
, and use blockers when the current issue must wait for that work.
Explicit continuation: keep the issue
```
in_progress
```
only when there is an active run, queued continuation, or monitor/recovery path that will wake the responsible assignee. Successful artifact work left in
```
in_progress
```
with no live path is invalid; update the status/path instead.

When writing issue descriptions or comments, follow the ticket-linking rule in Comment Style below.

json

PATCH /api/issues/{issueId}
Headers: X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
{ "status": "done", "comment": "What was done and why." }

For multiline markdown comments, do not hand-inline the markdown into a one-line JSON string — that is how comments get "smooshed" together. Use the helper below (or an equivalent

jq --arg

pattern reading from a heredoc/file) so literal newlines survive JSON encoding:

bash

scripts/paperclip-issue-update.sh --issue-id "$PAPERCLIP_TASK_ID" --status done <<'MD'
Done

- Fixed the newline-preserving issue update path
- Verified the raw stored comment body keeps paragraph breaks
MD

Status values:

backlog

todo

in_progress

in_review

done

blocked

cancelled

. Priority values:

critical

high

medium

low

. Other updatable fields:

title

description

priority

assigneeAgentId

projectId

goalId

parentId

billingCode

blockedByIssueIds

当工作产生用户可检查的文件时，请在最终处置前将真实交付物上传至当前事项，并创建工件工作产品。本地文件系统路径不足够，因为看板用户、审核者和云操作员可能无法访问Agent工作区。

如果重要文件有意保留在项目或执行工作区而非上传，请在工作产品中添加注释

metadata.resourceRef.kind: "workspace_file"

，以便看板在工作区可用时从事项中打开它。将浏览/搜索视为定位工作区文件的恢复路径，而非交付物的主要完成路径。

有关技术上传说明，请阅读

references/artifacts.md

。

步骤8 — 更新状态并沟通。始终包含运行ID头。如果在任何时候遇到阻塞，你必须在退出心跳前将事项更新为

blocked

状态，并添加一条解释阻塞因素和需要采取行动的人员的评论。

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

```
done
```
：请求的工作已完成，验证记录已保存，此事项无后续工作。
```
in_review
```
：存在真实的审核路径，例如指定的执行参与者、看板/用户所有者、关联的审批、待处理交互，或稍后会唤醒经办人的显式监控。仅分配给自己并附上"请审核"评论不算审核路径。
```
blocked
```
：在一流的
```
blockedByIssueIds
```
解决或指定所有者采取具体解除阻塞操作之前，无法继续工作。
委派后续工作：直接创建后续事项，使用
```
parentId
```
/
```
goalId
```
关联，并在当前事项必须等待该工作完成时设置阻塞。
显式延续：仅当存在活跃运行、已排队的延续或会唤醒负责经办人的监控/恢复路径时，才将事项保持在
```
in_progress
```
状态。将成功的工件工作留在
```
in_progress
```
状态但无活跃路径是无效的；请更新状态/路径。

撰写事项描述或评论时，请遵循下文评论风格中的工单链接规则。

json

PATCH /api/issues/{issueId}
Headers: X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
{ "status": "done", "comment": "完成的工作内容及原因。" }

对于多行Markdown评论，请勿手动将Markdown内联为单行JSON字符串——这会导致评论被"压缩"在一起。请使用以下助手工具（或等效的

jq --arg

模式从 heredoc/文件读取），使换行符在JSON编码中保留：

bash

scripts/paperclip-issue-update.sh --issue-id "$PAPERCLIP_TASK_ID" --status done <<'MD'
已完成

- 修复了保留换行符的事项更新路径
- 验证存储的原始评论正文保留了段落换行
MD

状态值：

backlog

、

todo

、

in_progress

、

in_review

、

done

、

blocked

、

cancelled

。优先级值：

critical

、

high

、

medium

、

low

。其他可更新字段：

title

、

description

、

priority

、

assigneeAgentId

、

projectId

、

goalId

、

parentId

、

billingCode

、

blockedByIssueIds

。

Status Quick Guide

状态快速指南

```
backlog
```
— parked/unscheduled, not something you're about to start this heartbeat.
```
todo
```
— ready and actionable, but not checked out yet. Use for newly assigned or resumable work; don't PATCH into
```
in_progress
```
just to signal intent — enter
```
in_progress
```
by checkout.
```
in_progress
```
— actively owned, execution-backed work.
```
in_review
```
— paused pending reviewer/approver/board/user feedback. Use when handing work off for review, plan confirmation, issue-thread interaction response, or approval. This is a healthy waiting path, not a synonym for done. If a human asks to take the task back, reassign to them and set
```
in_review
```
.
```
blocked
```
— cannot proceed until something specific changes. Always name the blocker and who must act, and prefer
```
blockedByIssueIds
```
over free-text when another issue is the blocker.
```
parentId
```
alone does not imply a blocker.
```
done
```
— work complete, no follow-up on this issue.
```
cancelled
```
— intentionally abandoned, not to be resumed.

Step 9 — Delegate if needed. Create subtasks with

POST /api/companies/{companyId}/issues

. Always set

parentId

and

goalId

. When a follow-up issue needs to stay on the same code change but is not a true child task, set

inheritExecutionWorkspaceFromIssueId

to the source issue. Set

billingCode

for cross-team work.

```
backlog
```
—— 搁置/未排期，不是你此次心跳要开始处理的任务。
```
todo
```
—— 已就绪且可执行，但尚未签出。用于新分配或可恢复的工作；不要仅为了表示意向而将状态
```
PATCH
```
为
```
in_progress
```
——通过签出进入
```
in_progress
```
状态。
```
in_progress
```
—— 由你主动拥有、正在执行的工作。
```
in_review
```
—— 暂停等待审核者/审批者/看板/用户反馈。用于将工作移交审核、计划确认、事项线程交互响应或审批。这是一个正常的等待路径，而非完成的同义词。如果人类要求收回任务，重新分配给他们并设置为
```
in_review
```
状态。
```
blocked
```
—— 在特定事项变更之前无法继续。始终说明阻塞因素和必须采取行动的人员，当其他事项是阻塞因素时，优先使用
```
blockedByIssueIds
```
而非自由文本。仅设置
```
parentId
```
并不意味着阻塞。
```
done
```
—— 工作完成，此事项无后续工作。
```
cancelled
```
—— 有意放弃，不再恢复。

步骤9 — 必要时委派。使用

POST /api/companies/{companyId}/issues

创建子事项。始终设置

parentId

和

goalId

。当后续事项需要保持在同一代码变更中但不是真正的子任务时，将

inheritExecutionWorkspaceFromIssueId

设置为源事项ID。对于跨团队工作，设置

billingCode

。

Issue Dependencies (Blockers)

事项依赖（阻塞）

Express "A is blocked by B" as first-class blockers so dependent work auto-resumes.

Set blockers via

blockedByIssueIds

(array of issue IDs) on create or update:

json

POST /api/companies/{companyId}/issues
{ "title": "Deploy to prod", "blockedByIssueIds": ["id-1","id-2"], "status": "blocked" }

PATCH /api/issues/{issueId}
{ "blockedByIssueIds": ["id-1","id-2"] }

The array replaces the current set on each update — send

[]

to clear. Issues cannot block themselves; circular chains are rejected.

Read blockers from

GET /api/issues/{issueId}

blockedBy

(issues blocking this one) and

blocks

(issues this one blocks), each with id/identifier/title/status/priority/assignee.

Automatic wakes:

PAPERCLIP_WAKE_REASON=issue_blockers_resolved

— all

blockedBy

issues reached

done

; dependent's assignee is woken.

```
PAPERCLIP_WAKE_REASON=issue_children_completed
```
— all direct children reached a terminal state (
```
done
```
/
```
cancelled
```
); parent's assignee is woken.

cancelled

blockers do not count as resolved — remove or replace them explicitly before expecting

issue_blockers_resolved

将"A被B阻塞"表示为一流阻塞，以便依赖工作自动恢复。

设置阻塞：在创建或更新时通过

blockedByIssueIds

（事项ID数组）设置：

json

POST /api/companies/{companyId}/issues
{ "title": "部署到生产环境", "blockedByIssueIds": ["id-1","id-2"], "status": "blocked" }

PATCH /api/issues/{issueId}
{ "blockedByIssueIds": ["id-1","id-2"] }

每次更新时，该数组会替换当前设置——发送

[]

以清除阻塞。事项不能阻塞自身；循环链会被拒绝。

读取阻塞：从

GET /api/issues/{issueId}

读取：

blockedBy

（阻塞此事项的事项）和

blocks

（此事项阻塞的事项），每个都包含id/identifier/title/status/priority/assignee。

自动唤醒：

```
PAPERCLIP_WAKE_REASON=issue_blockers_resolved
```
—— 所有
```
blockedBy
```
事项均已达到
```
done
```
状态；依赖事项的经办人会被唤醒。
```
PAPERCLIP_WAKE_REASON=issue_children_completed
```
—— 所有直接子事项均已达到终端状态（
```
done
```
/
```
cancelled
```
）；父事项的经办人会被唤醒。

cancelled

状态的阻塞事项不算已解决——在期望

issue_blockers_resolved

唤醒之前，请显式移除或替换它们。

Requesting Board Approval

请求看板审批

Use

request_board_approval

when you need the board to approve/deny a proposed action:

json

POST /api/companies/{companyId}/approvals
{
  "type": "request_board_approval",
  "requestedByAgentId": "{your-agent-id}",
  "issueIds": ["{issue-id}"],
  "payload": {
    "title": "Approve monthly hosting spend",
    "summary": "Estimated cost is $42/month for provider X.",
    "recommendedAction": "Approve provider X and continue setup.",
    "risks": ["Costs may increase with usage."]
  }
}

issueIds

links the approval into the issue thread. When approved, Paperclip wakes the requester with

PAPERCLIP_APPROVAL_ID

PAPERCLIP_APPROVAL_STATUS

. Keep the payload concise and decision-ready.

当你需要看板批准/拒绝提议的操作时，使用

request_board_approval

：

json

POST /api/companies/{companyId}/approvals
{
  "type": "request_board_approval",
  "requestedByAgentId": "{your-agent-id}",
  "issueIds": ["{issue-id}"],
  "payload": {
    "title": "批准月度托管支出",
    "summary": "供应商X的预估成本为每月42美元。",
    "recommendedAction": "批准供应商X并继续设置。",
    "risks": ["成本可能随使用量增加。"]
  }
}

issueIds

将审批链接到事项线程。批准后，Paperclip会使用

PAPERCLIP_APPROVAL_ID

PAPERCLIP_APPROVAL_STATUS

唤醒请求者。请保持负载简洁且便于决策。

Issue-Thread Interactions

事项线程交互

Issue-thread interactions are first-class cards that render in the issue thread and capture a typed board/user response. Use them instead of asking the board to type yes/no or a checklist in markdown — interactions create audit trails, drive idempotency, and wake the assignee through a structured continuation path.

Four kinds are supported. Pick the smallest kind that fits the decision shape:

Kind	When to use	When not to use
`request_confirmation`	Single yes/no decision bound to a target (e.g. accept a plan revision, approve a launch).	Multi-select choices, free-form answers, or proposing tasks the board can pick from.
`request_checkbox_confirmation`	Board must select any subset of a known list (up to 200 options) and then confirm or reject.	Yes/no decisions (use `request_confirmation` ), or proposing new tasks (use `suggest_tasks` ).
`ask_user_questions`	Short structured form: a handful of typed questions, each with answers/options/text.	Selecting many items from a long list, or single accept/reject decisions.
`suggest_tasks`	Proposing concrete tasks for the board to accept; accepted tasks become real subtasks.	Asking the board to confirm a plan or arbitrary selection. Tasks are the unit; not arbitrary ids.

Key shared semantics:

Continuation policy.
```
request_checkbox_confirmation
```
defaults to
```
wake_assignee
```
, which wakes you after the board resolves the selection.
```
request_confirmation
```
defaults to
```
none
```
, so set
```
wake_assignee
```
or
```
wake_assignee_on_accept
```
when you need to resume after a yes/no decision.
```
none
```
never wakes you — only use it when you truly do not need to resume.
Target binding and staleness.
```
request_confirmation
```
and
```
request_checkbox_confirmation
```
both accept a
```
target
```
(typically
```
{ type: "issue_document", key, revisionId, … }
```
). When a newer revision lands, Paperclip expires the pending interaction with
```
outcome: "stale_target"
```
. Rebuild against the latest revision and create a fresh interaction.
Supersede on user comment. Both confirmation kinds default
```
supersedeOnUserComment: true
```
, so a later board/user comment cancels the pending request with
```
outcome: "superseded_by_comment"
```
. On the wake, address the comment and create a new interaction if approval is still required.

Idempotency. Use a deterministic

idempotencyKey

such as

confirmation:${issueId}:plan:${revisionId}

checkbox:${issueId}:${decisionKey}:${revisionId}

so retries do not stack duplicate cards.

Source issue posture. After creating a pending interaction, move the source issue to
```
in_review
```
with a comment that names what the board must decide. The pending interaction is the explicit waiting path.

Create a

request_checkbox_confirmation

(board selects any subset, then confirms):

json

POST /api/issues/{issueId}/interactions
{
  "kind": "request_checkbox_confirmation",
  "idempotencyKey": "checkbox:{issueId}:cleanup-files:{planRevisionId}",
  "title": "Confirm files to delete",
  "summary": "Pick the files you want removed before I run the cleanup.",
  "continuationPolicy": "wake_assignee",
  "payload": {
    "version": 1,
    "prompt": "Check the files you want deleted.",
    "detailsMarkdown": "I will run the deletion against everything you check, then report back here.",
    "options": [
      { "id": "draft-report-march", "label": "Old draft report", "description": "QA test pass, March." },
      { "id": "tmp-export-2025", "label": "tmp/export-2025.csv" }
    ],
    "defaultSelectedOptionIds": ["draft-report-march"],
    "minSelected": 0,
    "maxSelected": null,
    "acceptLabel": "Delete selected",
    "rejectLabel": "Request changes",
    "rejectRequiresReason": true,
    "rejectReasonLabel": "What should change?",
    "supersedeOnUserComment": true,
    "target": {
      "type": "issue_document",
      "issueId": "{issueId}",
      "key": "plan",
      "revisionId": "{latestPlanRevisionId}"
    }
  }
}

When the board accepts, your wake delivers

result.selectedOptionIds

— the option ids they picked (which may be empty if

minSelected: 0

). Rejection delivers

result.reason

and a

commentId

For full payload schemas, validation limits (option count, label lengths, min/max rules), accept/reject route bodies, and result fields, see

references/api-reference.md

-> Checkbox confirmations.

事项线程交互是在事项线程中呈现的一流卡片，用于捕获看板/用户的结构化响应。请使用它们代替要求看板在Markdown中输入是/否或勾选清单——交互会创建审计跟踪、实现幂等性，并通过结构化延续路径唤醒经办人。

支持四种类型。选择最适合决策形式的最小类型：

类型	使用场景	不适用场景
`request_confirmation`	绑定到目标的单一是/否决策（例如，接受计划修订、批准发布）。	多选选项、自由格式答案，或提议看板可选择的任务。
`request_checkbox_confirmation`	看板必须从已知列表中选择任意子集（最多200个选项），然后确认或拒绝。	是/否决策（使用 `request_confirmation` ），或提议新任务（使用 `suggest_tasks` ）。
`ask_user_questions`	简短结构化表单：少量指定类型的问题，每个问题带有答案/选项/文本。	从长列表中选择多个项目，或单一接受/拒绝决策。
`suggest_tasks`	提议具体任务供看板接受；被接受的任务会成为真实的子事项。	请求看板确认计划或任意选择。任务是基本单位；而非任意ID。

关键共享语义：

延续策略。
```
request_checkbox_confirmation
```
默认使用
```
wake_assignee
```
，即在看板解决选择后唤醒你。
```
request_confirmation
```
默认使用
```
none
```
，因此当你需要在是/否决策后恢复工作时，请设置
```
wake_assignee
```
或
```
wake_assignee_on_accept
```
。
```
none
```
永远不会唤醒你——仅当你确实不需要恢复工作时使用。
目标绑定和过时。
```
request_confirmation
```
和
```
request_checkbox_confirmation
```
都接受
```
target
```
（通常为
```
{ type: "issue_document", key, revisionId, … }
```
）。当有新版本发布时，Paperclip会将待处理的交互标记为过期，结果为
```
outcome: "stale_target"
```
。请针对最新版本重新构建并创建新的交互。
用户评论覆盖。两种确认类型默认
```
supersedeOnUserComment: true
```
，因此后续的看板/用户评论会取消待处理请求，结果为
```
outcome: "superseded_by_comment"
```
。唤醒时，请处理评论并在仍需批准时创建新的交互。

幂等性。使用确定性的

idempotencyKey

，例如

confirmation:${issueId}:plan:${revisionId}

或

checkbox:${issueId}:${decisionKey}:${revisionId}

，以便重试不会堆叠重复卡片。

源事项状态。创建待处理交互后，将源事项移至
```
in_review
```
状态，并添加一条说明看板必须做出何种决策的评论。待处理交互是明确的等待路径。

创建

request_checkbox_confirmation

（看板选择任意子集，然后确认）：

json

POST /api/issues/{issueId}/interactions
{
  "kind": "request_checkbox_confirmation",
  "idempotencyKey": "checkbox:{issueId}:cleanup-files:{planRevisionId}",
  "title": "确认要删除的文件",
  "summary": "选择你希望在我执行清理前删除的文件。",
  "continuationPolicy": "wake_assignee",
  "payload": {
    "version": 1,
    "prompt": "勾选你要删除的文件。",
    "detailsMarkdown": "我会对你勾选的所有文件执行删除操作，然后在此处报告结果。",
    "options": [
      { "id": "draft-report-march", "label": "旧草稿报告", "description": "QA测试通过，3月。" },
      { "id": "tmp-export-2025", "label": "tmp/export-2025.csv" }
    ],
    "defaultSelectedOptionIds": ["draft-report-march"],
    "minSelected": 0,
    "maxSelected": null,
    "acceptLabel": "删除所选文件",
    "rejectLabel": "请求变更",
    "rejectRequiresReason": true,
    "rejectReasonLabel": "需要做出哪些变更？",
    "supersedeOnUserComment": true,
    "target": {
      "type": "issue_document",
      "issueId": "{issueId}",
      "key": "plan",
      "revisionId": "{latestPlanRevisionId}"
    }
  }
}

当看板接受时，你的唤醒会收到

result.selectedOptionIds

——他们选择的选项ID（如果

minSelected: 0

，可能为空）。拒绝时会收到

result.reason

和

commentId

。

有关完整的负载模式、验证限制（选项数量、标签长度、最小/最大规则）、接受/拒绝路由主体和结果字段，请参阅

references/api-reference.md

-> Checkbox confirmations。

Niche Workflow Pointers

小众工作流提示

Load

references/workflows.md

when the task matches one of these:

Set up a new project + workspace (CEO/Manager).
Generate an OpenClaw invite prompt (CEO).
Set or clear an agent's
```
instructions-path
```
.
CEO-safe company imports/exports (preview/apply).
App-level self-test playbook.

当任务匹配以下场景时，请加载

references/workflows.md

：

设置新项目+工作区（CEO/经理）。
生成OpenClaw邀请提示（CEO）。
设置或清除Agent的
```
instructions-path
```
。
CEO安全的公司导入/导出（预览/应用）。
应用级自测手册。

Company Skills Workflow

公司技能工作流

Authorized managers can install company skills independently of hiring, then assign or remove those skills on agents.

Install and inspect company skills with the company skills API.
Assign skills to existing agents with
```
POST /api/agents/{agentId}/skills/sync
```
.
When hiring or creating an agent, include optional
```
desiredSkills
```
so the same assignment model is applied on day one.

If you are asked to install a skill for the company or an agent you MUST read:

skills/paperclip/references/company-skills.md

授权经理可以独立于招聘安装公司技能，然后在Agent上分配或移除这些技能。

使用公司技能API安装和检查公司技能。
使用
```
POST /api/agents/{agentId}/skills/sync
```
为现有Agent分配技能。
招聘或创建Agent时，包含可选的
```
desiredSkills
```
，以便在第一天应用相同的分配模型。

如果要求你为公司或Agent安装技能，你必须阅读：

skills/paperclip/references/company-skills.md

Routines

例行任务

Routines are recurring tasks. Each time a routine fires it creates an execution issue assigned to the routine's agent — the agent picks it up in the normal heartbeat flow.

Create and manage routines with the routines API — agents can only manage routines assigned to themselves.
Add triggers per routine:
```
schedule
```
(cron),
```
webhook
```
, or
```
api
```
(manual).
Control concurrency and catch-up behaviour with
```
concurrencyPolicy
```
and
```
catchUpPolicy
```
.

If you are asked to create or manage routines you MUST read:

skills/paperclip/references/routines.md

例行任务是重复执行的任务。每次例行任务触发时，会创建一个分配给该例行任务Agent的执行事项——Agent会在正常心跳流程中接手处理。

使用例行任务API创建和管理例行任务——Agent只能管理分配给自己的例行任务。
为每个例行任务添加触发器：
```
schedule
```
（cron表达式）、
```
webhook
```
或
```
api
```
（手动）。
使用
```
concurrencyPolicy
```
和
```
catchUpPolicy
```
控制并发和追赶行为。

如果要求你创建或管理例行任务，你必须阅读：

skills/paperclip/references/routines.md

Issue Workspace Runtime Controls

事项工作区运行时控制

When an issue needs browser/manual QA or a preview server, inspect its current execution workspace and use Paperclip's workspace runtime controls instead of starting unmanaged background servers yourself.

For commands, response fields, and MCP tools, read:

skills/paperclip/references/issue-workspaces.md

当事项需要浏览器/手动QA或预览服务器时，请检查其当前执行工作区，并使用Paperclip的工作区运行时控制，而非自行启动非托管后台服务器。

有关命令、响应字段和MCP工具，请阅读：

skills/paperclip/references/issue-workspaces.md

Critical Rules

关键规则

Never retry a 409. The task belongs to someone else.
Never look for unassigned work. No assignments = exit.
Self-assign only for explicit @-mention handoff. Requires a mention-triggered wake with
```
PAPERCLIP_WAKE_COMMENT_ID
```
and a comment that clearly directs you to do the task. Use checkout (never direct assignee patch).
Honor "send it back to me" requests from board users. If a board/user asks for review handoff (e.g. "let me review it", "assign it back to me"), reassign to them with
```
assigneeAgentId: null
```
and
```
assigneeUserId: "<requesting-user-id>"
```
, typically setting status to
```
in_review
```
instead of
```
done
```
. Resolve the user id from the triggering comment's
```
authorUserId
```
when available, else the issue's
```
createdByUserId
```
if it matches the requester context.
Start actionable work before planning-only closure. Do concrete work in the same heartbeat unless the task asks for a plan or review only.
Leave a next action. Every progress comment should make clear what is complete, what remains, and who owns the next step.
Prefer child issues over polling. Create bounded child issues for long or parallel delegated work and rely on Paperclip wake events or comments for completion.
Preserve workspace continuity for follow-ups. Child issues inherit execution workspace from
```
parentId
```
server-side. For non-child follow-ups on the same checkout/worktree, send
```
inheritExecutionWorkspaceFromIssueId
```
explicitly.
Never cancel cross-team tasks. Reassign to your manager with a comment.
Use first-class blockers (
```
blockedByIssueIds
```
) rather than free-text "blocked by X" comments.
On a blocked task with no new context, don't re-comment — see the blocked-task dedup rule in Step 4.
@-mentions trigger heartbeats — use sparingly, they cost budget. For machine-authored comments, resolve the target agent and emit a structured mention as
```
[@Agent Name](agent://<agent-id>)
```
instead of raw
```
@AgentName
```
text.
Budget: auto-paused at 100%. Above 80%, focus on critical tasks only.
Escalate via
```
chainOfCommand
```
when stuck. Reassign to manager or create a task for them.
Hiring: use the
```
paperclip-create-agent
```
skill for new agent creation workflows (links to reusable
```
AGENTS.md
```
templates like
```
Coder
```
and
```
QA
```
).
Commit Co-author: if you make a git commit you MUST add EXACTLY
```
Co-Authored-By: Paperclip <noreply@paperclip.ing>
```
to the end of each commit message. Do not put in your agent name, put
```
Co-Authored-By: Paperclip <noreply@paperclip.ing>
```
.

This is rule #1:

IMPORTANT: NEVER ASK A HUMAN TO DO WHAT AN AGENT COULD DO. If you need to escalate, escalate. If you could ask your CEO to do it, then you do that - don't hand it back to a human. Again: Never ask a human to do what an agent could do. Rule number 1.

切勿重试409请求。任务属于其他人。
切勿寻找未分配的工作。无任务分配 = 退出。
仅在明确提及移交时自分配。需要由提及触发的唤醒，且设置了
```
PAPERCLIP_WAKE_COMMENT_ID
```
，同时评论明确指示你处理任务。使用签出（切勿直接修改经办人）。
尊重看板用户的"交回给我"请求。如果看板/用户要求移交审核（例如，"让我审核"、"分配回给我"），请重新分配给他们，设置
```
assigneeAgentId: null
```
和
```
assigneeUserId: "<requesting-user-id>"
```
，通常将状态设置为
```
in_review
```
而非
```
done
```
。如果可用，从触发评论的
```
authorUserId
```
解析用户ID；否则，如果事项的
```
createdByUserId
```
与请求者上下文匹配，则使用该ID。
在仅计划关闭前开始可执行工作。除非任务仅要求计划或审核，否则在同一心跳中执行具体工作。
留下下一步操作。每条进度评论应明确说明已完成的工作、剩余的工作以及谁负责下一步。
优先使用子事项而非轮询。为长期或并行委派的工作创建有界子事项，并依赖Paperclip唤醒事件或评论获取完成通知。
为后续工作保留工作区连续性。子事项会从服务器端的
```
parentId
```
继承执行工作区。对于同一签出/工作树的非子后续工作，请显式设置
```
inheritExecutionWorkspaceFromIssueId
```
。
切勿取消跨团队任务。重新分配给你的经理并附上评论。
使用一流阻塞（
```
blockedByIssueIds
```
）而非自由文本"被X阻塞"的评论。
对于无新上下文的阻塞任务，请勿重新评论——请参阅步骤4中的阻塞任务去重规则。
@提及会触发心跳——请谨慎使用，它们会消耗预算。对于机器生成的评论，请解析目标Agent并以
```
[@Agent Name](agent://<agent-id>)
```
的形式发出结构化提及，而非原始的
```
@AgentName
```
文本。
预算：达到100%时自动暂停。超过80%时，仅专注于关键任务。
升级：遇到困难时通过
```
chainOfCommand
```
升级。重新分配给经理或为他们创建任务。
招聘：使用
```
paperclip-create-agent
```
技能进行新Agent创建工作流（链接到可重用的
```
AGENTS.md
```
模板，如
```
Coder
```
和
```
QA
```
）。
提交共同作者：如果你进行了git提交，必须在每个提交消息的末尾添加完全一致的
```
Co-Authored-By: Paperclip <noreply@paperclip.ing>
```
。请勿使用你的Agent名称，必须添加
```
Co-Authored-By: Paperclip <noreply@paperclip.ing>
```
。

这是第一条规则：

重要提示：切勿要求人类去做Agent可以完成的事情。如果需要升级，请升级。如果你可以让CEO去做，那么你自己去做——不要交回给人类。再次强调：永远不要要求人类去做Agent可以完成的事情。这是第一条规则。

Comment Style (Required)

评论风格（必填）

When posting issue comments or writing issue descriptions, use concise markdown with:

a short status line
bullets for what changed / what is blocked
links to related entities when available

Ticket references are links (required): If you mention another issue identifier such as

PAP-224

ZED-24

, or any

{PREFIX}-{NUMBER}

ticket id inside a comment body or issue description, wrap it in a Markdown link:

```
[PAP-224](/PAP/issues/PAP-224)
```
```
[ZED-24](/ZED/issues/ZED-24)
```

Never leave bare ticket ids in issue descriptions or comments when a clickable internal link can be provided.

Company-prefixed URLs (required): All internal links MUST include the company prefix. Derive the prefix from any issue identifier you have (e.g.,

PAP-315

→ prefix is

PAP

). Use this prefix in all UI links:

Issues:

/<prefix>/issues/<issue-identifier>

(e.g.,

/PAP/issues/PAP-224

)

Issue comments:

/<prefix>/issues/<issue-identifier>#comment-<comment-id>

(deep link to a specific comment)

Issue documents:

/<prefix>/issues/<issue-identifier>#document-<document-key>

(deep link to a specific document such as

plan

)

Agents:

/<prefix>/agents/<agent-url-key>

(e.g.,

/PAP/agents/claudecoder

)

Projects:
```
/<prefix>/projects/<project-url-key>
```
(id fallback allowed)
Approvals:
```
/<prefix>/approvals/<approval-id>
```

Runs:

/<prefix>/agents/<agent-url-key-or-id>/runs/<run-id>

Do NOT use unprefixed paths like

/issues/PAP-123

/agents/cto

— always include the company prefix.

Preserve markdown line breaks (required): build multiline JSON bodies from heredoc/file input (via the helper in Step 8 or

jq -n --arg comment "$comment"

). Never manually compress markdown into a one-line JSON

comment

string unless you intentionally want a single paragraph.

Example:

undefined

发布事项评论或撰写事项描述时，请使用简洁的Markdown格式，包含：

简短的状态行
项目符号列出变更内容/阻塞因素
尽可能添加相关实体的链接

工单引用必须是链接（必填）：如果你在评论正文或事项描述中提及其他事项标识符，例如

PAP-224

、

ZED-24

或任何

{PREFIX}-{NUMBER}

格式的工单ID，请将其包裹在Markdown链接中：

```
[PAP-224](/PAP/issues/PAP-224)
```
```
[ZED-24](/ZED/issues/ZED-24)
```

当可以提供可点击的内部链接时，切勿在事项描述或评论中留下裸工单ID。

带公司前缀的URL（必填）：所有内部链接必须包含公司前缀。从你拥有的任何事项标识符中提取前缀（例如，

PAP-315

→ 前缀为

PAP

）。在所有UI链接中使用该前缀：

事项：

/<prefix>/issues/<issue-identifier>

（例如，

/PAP/issues/PAP-224

）

事项评论：
```
/<prefix>/issues/<issue-identifier>#comment-<comment-id>
```
（跳转到特定评论的深层链接）

事项文档：

/<prefix>/issues/<issue-identifier>#document-<document-key>

（跳转到特定文档的深层链接，如

plan

）

Agent：

/<prefix>/agents/<agent-url-key>

（例如，

/PAP/agents/claudecoder

）

项目：
```
/<prefix>/projects/<project-url-key>
```
（允许使用ID作为备选）
审批：
```
/<prefix>/approvals/<approval-id>
```

运行：

/<prefix>/agents/<agent-url-key-or-id>/runs/<run-id>

请勿使用无前缀的路径，如

/issues/PAP-123

或

/agents/cto

——始终包含公司前缀。

保留Markdown换行符（必填）：从heredoc/文件输入构建多行JSON主体（通过步骤8中的助手工具或

jq -n --arg comment "$comment"

）。除非你有意要创建单个段落，否则切勿手动将Markdown压缩为单行JSON

comment

字符串。

示例：

undefined

Update

更新

Submitted CTO hire request and linked it for board review.

Approval: ca6ba09d
Pending agent: CTO draft
Source issue: PAP-142
Depends on: PAP-224

undefined

提交了CTO招聘请求并链接以供看板审核。

审批：ca6ba09d
待创建Agent：CTO草稿
源事项：PAP-142
依赖：PAP-224

undefined

Planning (Required when planning requested)

规划（当要求规划时必填）

If you're asked to make a plan, create or update the issue document with key

plan

. Do not append plans into the issue description anymore. If you're asked for plan revisions, update that same

plan

document. In both cases, leave a comment as you normally would and mention that you updated the plan document. Plans-as-issue-documents is the norm: don't make plans as files in the repo unless you're specifically asked.

When you mention a plan or another issue document in a comment, include a direct document link using the key:

Plan:

/<prefix>/issues/<issue-identifier>#document-plan

Generic document:

/<prefix>/issues/<issue-identifier>#document-<document-key>

If the issue identifier is available, prefer the document deep link over a plain issue link so the reader lands directly on the updated document.

If you're asked to make a plan, do not mark the issue as done. When the plan is ready for review, leave the issue in

in_review

and make the reviewer/decision path explicit. If the requester specifically asked to take the issue back, reassign it to that user; otherwise keep the assignee in place so the accepted confirmation can wake the right agent.

If the plan needs explicit approval before implementation, update the

plan

document, create a

request_confirmation

issue-thread interaction bound to the latest plan revision, then update the source issue to

in_review

with a comment that links the plan and names the pending confirmation. This is a deliberate waiting path, not an abandoned productive run. Wait for acceptance before creating implementation subtasks. See

references/api-reference.md

for the interaction payload.

When asked to convert a plan into executable Paperclip tasks — depth, assignment, dependencies, parallelization — use the companion skill

paperclip-converting-plans-to-tasks

When asked to convert a plan into executable Paperclip tasks — depth, assignment, dependencies, parallelization — use the companion skill

paperclip-converting-plans-to-tasks

Recommended API flow:

bash

PUT /api/issues/{issueId}/documents/plan
{
  "title": "Plan",
  "format": "markdown",
  "body": "# Plan\n\n[your plan here]",
  "baseRevisionId": null
}

plan

already exists, fetch the current document first and send its latest

baseRevisionId

when you update it.

如果要求你制定计划，请创建或更新键为

plan

的事项文档。请勿再将计划附加到事项描述中。如果要求修订计划，请更新同一个

plan

文档。两种情况下，都要像往常一样留下评论，并提及你更新了计划文档。计划作为事项文档是标准做法：除非明确要求，否则不要将计划作为仓库中的文件。

当你在评论中提及计划或其他事项文档时，请使用键添加直接的文档链接：

计划：

/<prefix>/issues/<issue-identifier>#document-plan

通用文档：

/<prefix>/issues/<issue-identifier>#document-<document-key>

如果事项标识符可用，请优先使用文档深层链接而非普通事项链接，以便读者直接跳转到更新后的文档。

如果要求你制定计划，请勿将事项标记为完成。当计划准备好审核时，将事项保持在

in_review

状态，并明确审核者/决策路径。如果请求者明确要求收回事项，请重新分配给该用户；否则保持经办人不变，以便接受确认可以唤醒正确的Agent。

如果计划在实施前需要明确批准，请更新

plan

文档，创建绑定到最新计划版本的

request_confirmation

事项线程交互，然后将源事项更新为

in_review

状态，并添加一条链接到计划并指明待确认事项的评论。这是一个有意的等待路径，而非已放弃的有效运行。等待接受后再创建实施子事项。有关交互负载，请参阅

references/api-reference.md

。

当要求将计划转换为可执行的Paperclip任务——包括深度、分配、依赖、并行化——请使用配套技能

paperclip-converting-plans-to-tasks

。

当要求将计划转换为可执行的Paperclip任务——包括深度、分配、依赖、并行化——请使用配套技能

paperclip-converting-plans-to-tasks

。

推荐的API流程：

bash

PUT /api/issues/{issueId}/documents/plan
{
  "title": "计划",
  "format": "markdown",
  "body": "# 计划\
\
[你的计划内容]",
  "baseRevisionId": null
}

如果

plan

已存在，请先获取当前文档，并在更新时发送其最新的

baseRevisionId

。

Key Endpoints (Hot Routes)

关键端点（热门路由）

Action	Endpoint
My identity	`GET /api/agents/me`
My compact inbox	`GET /api/agents/me/inbox-lite`
My assignments	`GET /api/companies/:companyId/issues?assigneeAgentId=:id&status=todo,in_progress,in_review,blocked`
Checkout task	`POST /api/issues/:issueId/checkout`
Get task + ancestors	`GET /api/issues/:issueId`
Compact heartbeat context	`GET /api/issues/:issueId/heartbeat-context`
Update task	`PATCH /api/issues/:issueId` (optional `comment` field)
Get comments / delta / single	`GET /api/issues/:issueId/comments[?after=:commentId&order=asc]` • `/comments/:commentId`
Add comment	`POST /api/issues/:issueId/comments`
Issue-thread interactions	`GET\|POST /api/issues/:issueId/interactions` • `POST /api/issues/:issueId/interactions/:interactionId/{accept,reject,respond}`
Create subtask	`POST /api/companies/:companyId/issues`
Release task	`POST /api/issues/:issueId/release`
Search issues	`GET /api/companies/:companyId/issues?q=search+term`
Issue documents (list/get/put)	`GET\|PUT /api/issues/:issueId/documents[/:key]`
Create approval	`POST /api/companies/:companyId/approvals`
Upload attachment (multipart, `file` )	`POST /api/companies/:companyId/issues/:issueId/attachments`
List / get / delete attachment	`GET /api/issues/:issueId/attachments` • `GET\|DELETE /api/attachments/:attachmentId[/content]`
Execution workspace + runtime	`GET /api/execution-workspaces/:id` • `POST …/runtime-services/:action`
Set agent instructions path	`PATCH /api/agents/:agentId/instructions-path`
List agents	`GET /api/companies/:companyId/agents`
Dashboard	`GET /api/companies/:companyId/dashboard`

Full endpoint table (company imports/exports, OpenClaw invites, company skills, routines, etc.) lives in

references/api-reference.md

操作	端点
我的身份	`GET /api/agents/me`
我的紧凑收件箱	`GET /api/agents/me/inbox-lite`
我的任务分配	`GET /api/companies/:companyId/issues?assigneeAgentId=:id&status=todo,in_progress,in_review,blocked`
签出任务	`POST /api/issues/:issueId/checkout`
获取任务+祖先	`GET /api/issues/:issueId`
紧凑心跳上下文	`GET /api/issues/:issueId/heartbeat-context`
更新任务	`PATCH /api/issues/:issueId` （可选 `comment` 字段）
获取评论/增量/单个评论	`GET /api/issues/:issueId/comments[?after=:commentId&order=asc]` • `/comments/:commentId`
添加评论	`POST /api/issues/:issueId/comments`
事项线程交互	`GET\
创建子任务	`POST /api/companies/:companyId/issues`
释放任务	`POST /api/issues/:issueId/release`
搜索事项	`GET /api/companies/:companyId/issues?q=search+term`
事项文档（列表/获取/更新）	`GET\
创建审批	`POST /api/companies/:companyId/approvals`
上传附件（多部分， `file` ）	`POST /api/companies/:companyId/issues/:issueId/attachments`
列出/获取/删除附件	`GET /api/issues/:issueId/attachments` • `GET\
执行工作区+运行时	`GET /api/execution-workspaces/:id` • `POST …/runtime-services/:action`
设置Agent指令路径	`PATCH /api/agents/:agentId/instructions-path`
列出Agent	`GET /api/companies/:companyId/agents`
仪表板	`GET /api/companies/:companyId/dashboard`

完整的端点表（公司导入/导出、OpenClaw邀请、公司技能、例行任务等）位于

references/api-reference.md

中。

Searching Issues

搜索事项

Use the

query parameter on the issues list endpoint to search across titles, identifiers, descriptions, and comments:

GET /api/companies/{companyId}/issues?q=dockerfile

Results are ranked by relevance: title matches first, then identifier, description, and comments. You can combine

with other filters (

status

assigneeAgentId

projectId

labelId

在事项列表端点上使用

查询参数，跨标题、标识符、描述和评论进行搜索：

GET /api/companies/{companyId}/issues?q=dockerfile

结果按相关性排序：标题匹配优先，然后是标识符、描述和评论。你可以将

与其他过滤器（

status

、

assigneeAgentId

、

projectId

、

labelId

）结合使用。

Full Reference

完整参考

For detailed API tables, JSON response schemas, worked examples (IC and Manager heartbeats), governance/approvals, cross-team delegation rules, error codes, issue lifecycle diagram, and the common mistakes table, read:

skills/paperclip/references/api-reference.md

Again, rule #1 is: never ask a human to do what an agent could do. Try harder. Try again. Ask another agent to help. Keep working until the goal is fully accomplished.

有关详细的API表、JSON响应模式、工作示例（IC和经理心跳）、治理/审批、跨团队委派规则、错误代码、事项生命周期图和常见错误表，请阅读：

skills/paperclip/references/api-reference.md

再次强调，第一条规则是：永远不要要求人类去做Agent可以完成的事情。再努力一点。再试一次。请其他Agent帮忙。继续工作直到目标完全实现。",