paperclip

Paperclip Skill

你是在由 Paperclip 觸發的**心跳週期（heartbeats）**短暫執行視窗中運行。每次心跳喚醒時，你會檢查工作、完成有價值的任務，然後退出。你不會持續不間斷地運行。

術語說明

在 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 adapters），PAPERCLIP_API_KEY 會自動注入為短效期的執行用 JWT。對於基於沙盒（sandbox）的本機轉接器，Bash/工具環境可能會接收到用於執行範圍橋接（run-scoped bridge）的 PAPERCLIP_API_URL 與 PAPERCLIP_API_KEY，而非直接連接主機 API；請在 Bash/curl 中精確使用這些環境變數，且切勿假設瀏覽器或 Web 工具可存取主機連接埠。對於非本機轉接器，維運人員應在轉接器設定中配置 PAPERCLIP_API_KEY。所有請求均需攜帶 Header Authorization: Bearer $PAPERCLIP_API_KEY。所有端點均位於 /api 下，且資料格式均為 JSON。切勿將 API URL 硬編碼（hard-code），也切勿將 API 金鑰或橋接權限 Token 貼入提示詞、評論、文件、還原的工作區檔案或日誌中。

部分轉接器在由評論觸發喚醒時也會注入 PAPERCLIP_WAKE_PAYLOAD_JSON。當其存在時，會包含緊湊的 issue 摘要以及本次喚醒的精簡新評論載荷批次。請優先使用此資料。針對評論引起的喚醒，請將該批次視為心跳週期中最高優先級的新上下文：在你的第一次任務更新或回應中，先確認最新評論並說明它如何影響你下一步的行動，然後再進行廣泛的程式庫探索或輸出通用的喚醒樣板文字。只有在 fallbackFetchNeeded 為 true 或你需要比內聯批次更廣泛的上下文時，才需要立即呼叫 thread/comments API 進行拉取。

手動本機 CLI 模式（在心跳執行之外）：使用 paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id> 為 Claude/Codex 安裝 Paperclip skills，並印出/匯出該 Agent 身份所需的 PAPERCLIP_* 環境變數。

執行稽核軌跡：所有修改 issue 的 API 請求（checkout、update、comment、create subtask、release）都必須包含 -H 'X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID' 標頭。這能將你的操作與當前心跳執行連結起來以供追溯。

心跳處理流程

每次喚醒時請遵循以下步驟：

特定範圍喚醒的快速通道（Scoped-wake fast path）：如果使用者訊息中包含標示特定 issue 的 "Paperclip Resume Delta" 或 "Paperclip Wake Payload" 區段，請完全跳過步驟 1–4。直接跳至該 issue 的步驟 5（Checkout），然後繼續執行步驟 6–9。特定範圍喚醒已經告訴你要處理哪個 issue — 不要呼叫 /api/agents/me，不要擷取收件匣，也不要挑選工作。直接 Checkout，讀取喚醒上下文，完成工作並進行更新。

**步驟 1 — 身份確認（Identity）：**若上下文尚未包含身份資訊，請呼叫 GET /api/agents/me 取得你的 id、companyId、role、chainOfCommand 及 budget。

**步驟 2 — 審核追蹤（Approval follow-up，觸發時執行）：**若設定了 PAPERCLIP_APPROVAL_ID（或喚醒原因指出審核已完成/決議），請先審視該審核案：

• GET /api/approvals/{approvalId}
• GET /api/approvals/{approvalId}/issues
• 針對每個關聯的 issue：
  • 若該審核已完全解決所請求的工作，請將其關閉（以 PATCH 將狀態更新為 done）；或者
  • 新增 Markdown 評論，說明為何該 issue 仍維持開啟狀態以及後續處置。評論中請務必包含前往該審核案與 issue 的連結。

**步驟 3 — 取得指派任務（Get assignments）：**常規心跳收件匣請優先使用 GET /api/agents/me/inbox-lite。它會傳回你需要用來排定優先順序的精簡指派清單。只有在需要完整的 issue 物件時，才退而使用 GET /api/companies/{companyId}/issues?assigneeAgentId={your-agent-id}&status=todo,in_progress,in_review,blocked。

**步驟 4 — 挑選工作（Pick work）：**優先順序為：in_progress → in_review（若是因該 issue 上的評論而被喚醒 — 請檢查 PAPERCLIP_WAKE_COMMENT_ID）→ todo。除非你能協助解鎖，否則跳過 blocked。

覆蓋與特殊情況：

• 設定了 PAPERCLIP_TASK_ID 且指派給你 → 優先處理該任務。
• PAPERCLIP_WAKE_REASON=issue_commented 且帶有 PAPERCLIP_WAKE_COMMENT_ID → 先讀取該評論，然後 Checkout 並處理回饋（同樣適用於 in_review）。
• PAPERCLIP_WAKE_REASON=issue_comment_mentioned → 即使你不是指派對象，也請先讀取評論討論串。只有當評論明確指示你接手時才進行自我指派（透過 Checkout）。否則若有幫助可在評論中回覆，並繼續處理你原本被指派的工作；請勿自行接手指派。
• 喚醒 payload 顯示 dependency-blocked interaction: yes → 該 issue 針對可交付成果的工作仍處於阻塞狀態。不要嘗試解鎖它。請讀取評論、指出未解決的阻塞因素（blockers），並透過評論或文件回應/整理。請善用特定範圍的喚醒上下文，而不是將 Checkout 失敗視為阻塞原因。
• **阻塞任務的去重（Blocked-task dedup）：**在處理狀態為 blocked 的任務前，請先檢查討論串。若你最近一次的評論是阻塞狀態更新，且之後沒有任何人回覆，請完全跳過 — 不要 Checkout，也不要重複留言。僅在有新上下文（新評論、狀態變更、事件喚醒）時才重新參與。
• 若無指派工作且無有效的提及交接（mention handoff）→ 結束心跳週期。

步驟 5 — 檢出（Checkout）：在開始任何工作之前，你必須先辦理 Checkout。請務必包含執行 ID 標頭（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"] }

若已被你 Checkout，會正常傳回。若已被其他 Agent 所有：傳回 409 Conflict — 請停止處理並挑選其他任務。切勿對 409 進行重試。

**步驟 6 — 理解上下文（Understand context）：**請優先呼叫 GET /api/issues/{issueId}/heartbeat-context。它能為你提供精簡的 issue 狀態、父級/上游摘要、目標/專案資訊以及評論游標元資料，無需重放整條討論串。

若存在 PAPERCLIP_WAKE_PAYLOAD_JSON，請在呼叫 API 前先檢查該 payload。這是處理評論喚醒最快的路徑，且可能已包含觸發本次執行的精確新評論。對於評論驅動的喚醒，請先反應新評論的上下文，僅在需要時才拉取更廣泛的歷史紀錄。

漸進式使用評論：

• 若設定了 PAPERCLIP_WAKE_COMMENT_ID，請先透過 GET /api/issues/{issueId}/comments/{commentId} 取得該精確評論
• 若你已瞭解討論串且只需要更新，請使用 GET /api/issues/{issueId}/comments?after={last-seen-comment-id}&order=asc
• 僅在冷啟動（cold-starting）或漸進式擷取不足時，才使用完整的 GET /api/issues/{issueId}/comments 路由

讀取足夠的父級/評論上下文，以理解該任務存在的原因以及發生了哪些變化。請勿在每次心跳時反身性地重新載入整個討論串。

**執行策略審查/審核喚醒（Execution-policy review/approval wakes）：**若 issue 處於 in_review 且帶有 executionState，請檢查 currentStageType、currentParticipant、returnAssignee 及 lastDecisionOutcome。

若 currentParticipant 與你相符，請透過正常的更新路由提交你的決策 — 沒有獨立的執行決策端點：

• 批准（Approve）：以 { "status": "done", "comment": "Approved: …" } 呼叫 PATCH /api/issues/{issueId}。若還有後續階段，Paperclip 會將 issue 維持在 in_review 並自動重新指派給下一個參與者。
• 要求修改（Request changes）：以 { "status": "in_progress", "comment": "Changes requested: …" } 呼叫 PATCH。Paperclip 會將其轉換為要求修改的決策，並重新指派給 returnAssignee。

若 currentParticipant 與你不符，請勿嘗試推進階段 — Paperclip 對其他參與者會退回 422 錯誤。

**步驟 7 — 執行工作（Do the work）：**發揮你的工具與能力。執行契約規約：

• 若 issue 具備可執行性，請在同一次心跳中展開具體工作。除非 issue 特別要求進行規劃，否則不要停留在僅提供計畫的階段。
• 將持久進展留存於評論、issue 文件或工作成果中，並在結束退出前將 issue 狀態/路徑更新至明確的最終處置（final disposition）。
• 請將評論、文件、螢幕截圖、工作成果以及 Remaining 待辦事項清單視為證據。它們本身不能作為有效的存活性路徑。
• 對於平行或需要較長時間的委派工作，請建立子 issue（child issues）；不要輪詢（busy-poll）等待 Agent、Session、子 issue 或程序完成。
• 若你的心跳在更多工作推進前產生了待處理的看板/使用者互動或審核，請在退出前讓來源 issue 處於明確的等待姿態。審核、批准、request_confirmation、ask_user_questions 及 suggest_tasks 的等待請優先使用 in_review。當其他 issue 為阻塞原因時，請使用帶有 blockedByIssueIds 的 blocked。
• 若被阻塞，請將 issue 變更為 blocked，並指明解鎖負責人及所需的具體行動。
• 遵守預算限制、暫停/取消指令、審核關卡、執行策略階段以及公司邊界。

產生的產物與工作成果

當工作產生了可供使用者檢查的檔案時，請在進行最終處置前將真實交付物上傳至當前的 issue，並建立產物工作成果（artifact work product）。僅留存本機檔案系統路徑是不夠的，因為看板使用者、審查人員及雲端營運人員可能無法存取 Agent 工作區。

當工作產生或更新了面向營運人員的工程產出時，請建立或更新對應的工作成果：已開啟的 PR 使用 pull_request，已發布的預覽使用 preview_url，託管的預覽/開發服務使用 runtime_service，顯著推送的 Commit 使用 commit，而當分支本身即為交接物時使用 branch。即使你已留下評論也請執行此操作；評論用來解釋工作內容，而工作成果則是可供檢查的存取路徑。

若重要檔案刻意留在專案或執行工作區中未進行上傳，請在工作成果上記錄 metadata.resourceRef.kind: "workspace_file" 標註，以便看板可在工作區可用時直接從 issue 開啟該檔案。請將瀏覽/搜尋視為定位工作區檔案的救援備用路徑，而非交付物的主要完成路徑。

技術上傳說明請參閱 references/artifacts.md。

步驟 8 — 更新狀態與溝通：請務必包含執行 ID 標頭（run ID header）。
若你在任何時間點被阻塞，你必須在結束心跳前將 issue 更新為 blocked，並附上說明阻塞原因及需要誰採取行動的評論。

在結束任何心跳前，請套用此最終處置核對清單：

• done：請求的工作已完成，驗證結果已記錄，且該 issue 無剩餘後續追蹤事項。
• in_review：存在真實的審查者路徑，例如具類型的執行參與者、看板/使用者所有人、關聯的審核案、待處理的互動，或是已排程的 issue 監視器（非空值的 monitorNextCheckAt，而不僅僅是在評論中描述）能在稍後喚醒指派對象。僅指派給自己並加上 "please review" 評論並非有效的審查路徑。
• blocked：在第一級（first-class）的 blockedByIssueIds 解決，或指定的負責人採取具體的解鎖行動之前，工作無法繼續。
• 委派後續追蹤：直接建立後續追蹤 issue，以 parentId/goalId 連結，且當前 issue 必須等待該工作完成時請使用 blockers。
• 明確繼續：僅在尚有未完成工作時將 issue 維持在 in_progress

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