幫助

工作流程 · 狀態機 · 角色分工

一句話

人寫想法 → 整理成待辦 → AI 執行 → 人驗收閉環。所有狀態與 Agent 操作都寫回同一 D1 庫。

用戶（Human） AI Agent 系統狀態

端到端工作流程

捕獲的靈感預設指派給你（出現在「我的待辦」）；完善後再指派給 AI 並設為 ready，Agent 才會拉取。實作 complete 後可進入 review（指定 AI 驗收），通過後仍由人點「驗收通過」才 done。

用戶 Agent 狀態 捕獲靈感 assignee=human 交給 AI 整理 triage + ai 轉為 AI Todo ready + assignee=ai 驗收通過 → done queue / claim assignee=ai 審視合理/可行 通過才執行 執行並 complete 寫 result_summary 可選 AI 驗收 status=review inbox triage ready in_progress review done blocked archived 留言/不通過 → ready+ai 不可行 → block + human 執行／驗收中亦可阻塞

AI complete（或 AI 驗收通過）之後的人驗收是獨立狀態 acceptance（待驗收），再由你點完成。套用 migration 0019 之前，這一步仍是 in_progress 加上結果摘要。

狀態生命週期

狀態 含義 常見下一步
inbox 剛捕獲，未整理 triage / ready / archived
triage 整理中。Human 放入後由 Agent 完善標題/描述/類型，再交回 human 分發 ready / inbox / archived
ready 可被認領（Agent 僅見 assignee=ai） in_progress / blocked / …
in_progress 執行中。AI 認領時用戶不可改內容 acceptance / review / done / blocked / ready
review AI 驗收中（assignee=ai）。通過後進入待你驗收 acceptance / ready（退回實作）
acceptance 待你驗收。AI 已交出結果，由人驗收通過或退回。套用 migration 0019 之前，這一步仍顯示為 in_progress + 人 done / ready / review
done 已完成（通常由用戶驗收確認） archived / ready（重開）
blocked 受阻。Agent 審視失敗時會 block 並指派 human，寫入 blocked_reason ready / in_progress（人工補齊後再交 AI）
archived 已關閉（不做）：原因存在結果摘要，可「重新開啟」回收件箱 inbox / ready

指派（assignee）

  • human — 出現在「我的待辦」（含捕獲的靈感、待驗收結果）
  • ai — ready 時進執行 queue（items）；triage 時進整理筐（triage_items）
  • unassigned — 未指派，Agent 不會處理

角色分工

👤 用戶（Owner）

捕獲靈感、編輯描述、拖曳排序、看板改狀態、指派 AI、驗收結果、 留言 / 提問並交回 AI、設置每日取任務時間、導出數據。

🤖 AI Agent

僅操作當前項目；先處理 triage_items（完善描述，refine 交回 human 分發）； 再拉取 ready + assignee=ai； claim → 審視合理性/可行性 → 通過則執行並 complete（交回 human 待驗收）； 不可行則 block（assignee=human + 原因）。

🔒 系統規則

AI 認領中鎖定人工編輯；項目名不可重複；刪除項目需輸入完整名稱；狀態轉換受狀態機約束。

如何使用 Agent Token

預設為全域 Agent Token（用戶級）：寫入 ~/.sparkloop/env； 實際操作的項目由工作區資料夾名對應（請求帶 ?project=資料夾名）。 不能代替用戶 session 做導出等操作。

  1. 登錄後進入 設置 → Agent Token（或工作台按鈕）。
  2. 點「輪換全域 Agent Token」並立即複製（明文只顯示一次），保存到本機 ~/.sparkloop/env。
  3. 請求時帶：Authorization: Bearer slat_…，並加 ?project=<項目名或 slug>（CLI 用倉庫資料夾名自動帶）。
  4. 常用 API：
    • GET /api/agent/queue — items=ready+ai；triage_items=整理中；回應含 schedule
    • POST /api/agent/items — 在指定項目建立任務
    • POST /api/agent/items/:id/refine — 完善整理中描述，交回 human
    • POST /api/agent/items/:id/claim — 認領 ready 工作（不可用於 triage）
    • POST /api/agent/items/:id/progress — 進度備註
    • POST /api/agent/items/:id/complete + result_summary（須已 claim 為 in_progress；交還人工驗收；須匹配 agent_kind）
    • POST /api/agent/items/:id/block + reason → blocked + human（須已 claim 為 in_progress；須匹配 agent_kind）
    • POST /api/agent/items/:id/release — 僅 in_progress / blocked 可放回 ready + ai（須匹配 agent_kind）
  5. 本地：倉庫 skill 腳本 skills/sparkloop-workflow/scripts/agent.sh queue|refine|claim|block|complete。

Agent 認領後：合理性 / 可行性審視

依 skill sparkloop-workflow，Agent 在 claim 成功之後、動手改程式之前必須審視任務，不可跳過。

審視什麼

  • 合理性 — 是否符合本產品/倉庫；是否與規格或安全策略衝突；是否重複已完成工作。
  • 可行性 — 當前工作區與工具是否做得到；驗收標準是否清楚；是否缺秘密、權限、跨倉庫或僅人類能做的步驟。
  • 範圍 — 是否對應當前項目資料夾；一輪能否完成，或需先拆分。

結果怎麼走

結果 Agent 動作 你會看到
通過 可選 progress → 實作 → complete 「我的待辦 · 待驗收」+ result_summary
不合理 / 不可行 / 需人工 block + 可執行的 reason blocked、assignee=human、「我的待辦」顯示阻塞原因
誤領 / 暫緩（仍屬 AI） release 回到 queue（ready + ai）

block 的 reason 必須可執行：說明缺什麼、衝突點、請你如何改標題/正文或補資源後再 ready + ai。不要用空原因或單字「blocked」。

寫任務給 AI 時請盡量補：目標、範圍、驗收標準、相關路徑或 GitHub URL，可減少被 block 的機會。 只有一句話時，請用「交給 AI 整理」放進整理中，不要直接丟進執行隊列。

整理中：交給 AI 完善任務描述

捕獲常常只是一句話，範圍不清楚。把單放到 triage + assignee=ai （工作台「交給 AI 整理」、捕獲指派「AI 整理」、或看板拖到整理中欄）。 Agent 只補標題／正文／類型／標籤／優先級，不實作，然後交回 assignee=human（仍在整理中）讓你分發。

  1. 人：捕獲 → 交給 AI 整理（可指定 Grok / Claude…）。
  2. Agent：queue.triage_items → POST …/refine。
  3. 人：在「我的待辦」或整理中看完善後的規格 → 「交給 AI 執行」，或自己做。

留言（Comment）與交回 AI

任務詳情視窗有留言區。適用於驗收時有疑問、或需要補充說明再讓 AI 繼續。 AI 認領執行中仍可「僅留言」（complete 會提示）；「留言並交回 AI」需等認領結束。

三種常見操作

操作 何時用 結果
僅留言 自己備註、不改指派；AI 下一次處理此任務時會讀到 寫入 item_comments（kind=note）；任務狀態不變。Agent queue 顯示 new_comments_count；claim / refine / review 回傳 new_comments
留言並交回 AI 驗收有疑問、要 AI 再改一輪；inbox 捕獲也可交回；整理中卡片維持整理中 kind=question；正文與類型不變（留言本身就是回饋，AI 從 feedback.last_rejection 讀到）；清 result_summary。inbox / ready / 待驗收 → ready + ai；整理中 → 仍為 triage + ai。完成／歸檔／驗收中不顯示此按鈕
驗收不通過 → 交回 AI 明確失敗、需重做 kind=reject；同上交回。預設「下一任 AI」為原實作者

API（需登錄 session）

  • GET /api/projects/:id/items/:itemId — 詳情含 comments 陣列
  • GET /api/projects/:id/items/:itemId/comments — 僅留言列表（時間正序）
  • POST /api/projects/:id/items/:itemId/comments { "body": "…", "kind": "note|question|reject", "return_to_ai": true|false }

交回 AI 後任務會再次出現在 agent queue。Agent 必讀回應裡的 new_comments（人類在上次 agent 動作之後的留言），並把它們視為最新指示。 資料表：D1 item_comments（migration 0008_item_comments.sql）。 AI 也可以在卡片上留言回覆你（標示為「AI:種類」），不會改變狀態。

AI 認領中的卡片

  • 進行中／驗收中且指派給 AI 時卡片鎖定，你不能編輯或改狀態。
  • 若 AI 卡住（顯示 ⏳ 超過 24 小時未更新），用「更多操作 → 強制收回到 AI 隊列／強制收回給我」，需填原因；會記錄 force_release 活動。
  • AI 完成時若有只有你能做的事（D1 migration、secret、部署），卡片會出現「需要你完成的步驟」清單；有未勾選步驟時按「驗收通過」會再確認一次。
  • AI 建立的 follow-up 卡會連到父卡；預設去向可在「設定 → AI 建立的卡片預設去向」調整（預設：交給 AI 整理）。

AI 每日取任務時間如何生效

設置頁的排程是寫在項目上的偏好，不是「到點雲端自動幫你跑 AI」的定時器。

  1. 你在 設置 → AI 每日取任務時間 保存後，資料寫入 D1（該項目）。
  2. 不會推送通知給 Agent、手機或本機腳本。
  3. Agent 下次呼叫 GET /api/agent/queue 時，從 JSON 的 schedule: { enabled, time, timezone } 讀到最新值。
  4. 若要真·每日自動處理 queue，需自行用 cron / 排程服務在該時段執行 Agent 腳本，或到時在對話裡讓 Agent 拉 queue。

技術細節見倉庫文檔 docs/agent-schedule.md （英文 SSOT 對應 docs/PRODUCT_SPEC.md §5.3）。

推薦操作路徑

  1. 工作台「捕獲」靈感 → 進入我的待辦（human）
  2. 點擊編輯，補詳細描述與驗收標準，必要時改類型為 todo
  3. 「轉為 AI Todo」或指派 ai 並設 ready
  4. Agent：queue → 先 refine 整理中 → claim → 審視 → 通過則 complete（待驗收）；不通過則 block（阻塞 + 指派你）
  5. 待驗收： 「驗收通過 → Done」； 有疑問用「留言並交回 AI」； 明確失敗用「驗收不通過 → 交回 AI」。 詳見 留言說明。 若任務被 block：讀 blocked_reason，補齊後再 ready + ai

看板可拖曳改欄位狀態；列表可拖 ⠿ 調整 Agent 執行順序。 列表與詳情顯示任務 ID（點擊可複製），方便指定 Agent 先處理哪一筆。 編輯時可依類型套用詳細描述範本。 工作台頂部「詳細」可展開捕獲表單一次寫完標題+描述；點任務會打開居中詳情視窗，用「編輯 / 交給 AI / 我來做」與「更多操作」集中處理。 任務可指定 AI 種類（Grok / Claude / Codex…）；同一台機器上多個 Agent 各自用 --agent= 拉 queue，交回時可選下一任 AI（例如 Claude 做完 → Grok 審核）。 Agent 處理中若發現超出當前任務範圍的問題或建議，應主動建立新任務跟蹤（勿只寫在完成摘要裡）。 更多規格見倉庫 docs/PRODUCT_SPEC.md、skills/sparkloop-workflow/SKILL.md 或 文檔索引。

Webhook 驗章

任務進入 ready（item.ready）、AI 完成交回待驗收（item.awaiting_acceptance）或你驗收通過（item.done，accepted: true）時，Sparkloop 會 POST JSON 到你登記的 HTTPS 端點。若登記時填了 secret，請求會帶 HMAC 簽章，請用它驗證 payload 完整性。自 v0.2.91 起不再送出明文 X-Sparkloop-Secret。 Secret 在 D1 以 AES-GCM 加密存放（金鑰由 SESSION_SECRET 派生）；列表 API 不回傳 secret。 輪換 SESSION_SECRET 會讓既有加密 secret 無法解密，需刪除並重建 webhook。

請求標頭

  • X-Sparkloop-Event — item.ready / item.awaiting_acceptance / item.done / webhook.test。AI complete 只送 item.awaiting_acceptance；item.done 只在你驗收通過時送出（accepted: true）。若端點的 events 只有 item.done，請加上 item.awaiting_acceptance，否則不會再收到 AI 完成通知。
  • X-Sparkloop-Timestamp — Unix 秒（十進位）
  • X-Sparkloop-Signature — sha256=<hex>，HMAC-SHA256(secret, timestamp + rawBody)

簽章字串是標頭時間戳直接接上原始 JSON body（中間沒有分隔符）。 請用收到的原始 bytes 計算，不要先 pretty-print。建議拒絕時間戳與現在相差超過 5 分鐘的請求以防重放。 生產環境只接受 https:// 端點；本機可用 WEBHOOK_ALLOW_HTTP=true 放行 http://。