Aapastech Session Backlog：不再遺失任何任務
長時間工作階段與多任務提示常使 AI 助手遺漏工作。早期的請求和稍後的深入細節往往被忽略。此技能透過一個存放於使用者本機電腦的待辦清單來解決這個問題。對話記憶並非事實來源；待辦清單才是。不在待辦清單中的任務不存在，而在待辦清單中的任務必須標記為「完成」或「放棄」才算結束。
此技能適用於任何能在使用者電腦上執行 shell 命令或呼叫 MCP 工具的助手或代理。在同一台電腦上的所有工作階段，無論使用何種工具或模型，都共用同一個待辦清單。
隱私規則： 任務資料保留在執行工作的設備上。切勿將待辦清單複製到雲端服務、託管頁面、連接器或共用文件中。若無法存取使用者設備，請改用離線模式（第 9 節）。
1. 尋找待辦清單並執行引擎
如果您的工具清單中有 backlog_* 工具（即 MCP 伺服器，參閱第 11 節），請使用它們。這些工具與下列命令一一對應，並自動處理資料夾、編碼和升級事宜。請跳過本節其餘內容。
否則，待辦清單是一個包含 bl.py（引擎）、config.json、tasks/（每個任務一個 JSON 檔案）、sessions/、board.html 和 BOARD.md 的資料夾。請按以下順序尋找：
- 使用者已告知您的位置，無論是在其偏好設定、記憶或專案指示中。
- 若已設定
BACKLOG_DIR環境變數。 ~/Documents/Aapastech-Backlog（預設位置）。~/Documents/Claude-Backlog（v3 之前使用的資料夾名稱；如果使用者的任務存放在那裡，請繼續使用）。
執行它。 在此文件中 bl <command> 是簡寫。請始終鍵入完整命令；切勿將其儲存在 shell 變數中（$BL … 在 zsh（macOS 預設 shell）中會失敗）。
| Shell | 命令 |
|---|---|
| macOS / Linux (bash, zsh) | python3 ~/Documents/Aapastech-Backlog/bl.py <command> … |
| Windows PowerShell | py -3 "$HOME\Documents\Aapastech-Backlog\bl.py" <command> …（若 py 不存在，請嘗試 python） |
| Windows cmd | py -3 "%USERPROFILE%\Documents\Aapastech-Backlog\bl.py" <command> … |
| Git Bash (Windows) | py -3 ~/Documents/Aapastech-Backlog/bl.py <command> … |
bl where 會列印所使用的資料夾和引擎版本。在 Windows 上，Documents 常被移至 OneDrive（%USERPROFILE%\OneDrive\Documents）。如果 ~\Documents 不存在，請查看該位置，並提議設定 BACKLOG_DIR，以便每個工作階段都能找到同一個資料夾。
Python。 引擎需要 Python 3.8 以上版本，且無需其他依賴。
- macOS：首次呼叫
python3時，全新的 Mac 可能會跳出 Apple 的「安裝命令列開發者工具」對話框。請告知使用者這是預期行為，可以安全接受，或從 python.org 安裝 Python。 - Windows：Python 通常未安裝。如果
py -3和python都失敗，請要求使用者從 python.org 安裝 Python 3，並勾選「Add python.exe to PATH」，或使用winget install Python.Python.3.12。切勿回退到其他方案。
2. 首次在設備上執行（引導程序）
如果尚無待辦清單：
- 建立資料夾
~/Documents/Aapastech-Backlog（或使用者選擇的位置）。 - 從此技能自己的資料夾將
scripts/bl.py複製到其中。這是一個僅使用標準庫的單一 Python 檔案，內建看板功能。 - 向使用者提出一個簡短問題：要以什麼名稱顯示待處理的任務（等待使用者），以及他們的工作涵蓋哪些領域（3–8 個領域，例如客戶、產品、行政、個人）。根據您對他們的了解來建議領域。然後執行：
bl init --owner "<名稱>" --areas "領域1,領域2,…,個人,AI-Ops"如果他們想要自訂看板名稱，請加上--title "<看板標題>"（預設為「Aapastech Backlog」）。 - 告知看板位置：
file://…/Aapastech-Backlog/board.html。提議開啟它（bl board --open），並建議將其固定到分頁。 - 建議他們將此技能設為永遠啟用，例如在助手的個人偏好設定或指示檔案中：「始終在每次工作階段開始時及執行包含工作的任務前，載入 session-backlog 技能。」
升級： 如果 bl version 顯示的版本低於此技能中 scripts/bl.py 的版本（尋找 VERSION = "…"），請將新的 bl.py 覆蓋舊的。任務資料和設定保持不變。
3. 工作階段識別（每次工作階段一次）
選擇一個穩定的工作階段 ID 並在每次呼叫中重複使用：
- 如果您的平台為工作階段提供了 URL 或 ID，請使用它，並將 URL 作為
--url傳遞。 - 否則：
<表面>-<YYYYMMDD-HHMM>使用工作階段開始時間，例如desktop-20261018-1652、code-20261018-0910、api-20261018-1200、sched-20261019-0600。
bl session --id <SID> --label "<表面> · <主要主題>" --surface code|desktop|cloud|api|scheduled [--url <連結>]
這會列印該工作階段的未完成任務，以及其他工作階段中未認領或過期的任務。用一行提及過期或等待使用者的任務。不要傾印整個清單。
4. 回合迴圈（每回合包含工作時）
A. 先重新讀取。 在首次之後的每個回合開始時，執行 bl open --session <SID>。當提示是深入探討某個子任務時，尤其要這麼做。此步驟是確保其他工作不被遺忘的關鍵。切勿跳過。
B. 在工作前捕捉。 每一項新的請求和旁白（例如「還有…」、「提醒我…」、「之後…」、「別忘了…」）都會在開始任何工作前被批量捕捉。將此批次寫入一個 JSON 檔案（使用您的檔案寫入工具），然後傳遞該路徑。使用檔案可在所有 shell 中正常運作；透過 echo 將 JSON 序列傳輸到管道在 Windows shell 中會失敗，並會破壞非 ASCII 文字。
[
{"title":"重新設計定價頁面","area":"產品","eta":"1h","priority":"P1",
"source":"提示 16:52: 重做定價頁面","next":"取得目前版本",
"children":[{"title":"審核目前版本","eta":"10m"},
{"title":"草擬 2 種版面","eta":"30m"},
{"title":"發布所選版面","eta":"20m"}]},
{"title":"回覆供應商","area":"行政","eta":"15m","status":"waiting_user","next":"使用者確認數量"}
]
bl batch --session <SID> <檔案路徑.json>（將此檔案放在您的暫存或暫用資料夾中，而非使用者的專案中）。
以一行簡潔的方式回放捕捉到的內容，以便使用者修正：
已捕捉：T-0042 定價頁面 (1h) → T-0043 審核 (10m)、T-0044 版面 (30m)、T-0045 發布 (20m)；T-0046 供應商回覆（等待您）。
請先檢查 bl list，並更新現有任務，而非建立重複項。加入 "parent":"T-0042"（或在 bl add 後加上 --parent T-0042）即可將子任務置於現有任務下。
C. 認領，然後開始工作。 在開始每個任務前執行 bl claim <ID> --session <SID> [--eta 20m]。如果認領被拒絕（因為另一個活躍工作階段擁有它），請不要處理該任務。認領是鎖定的，因此兩個工作階段不可能同時贏得同一個任務。盡可能平行工作。協調工作階段會為其子代理更新待辦清單，並將各自的任務 ID 傳遞給每個子代理。
D. 邊做邊更新。
bl update <ID> --session <SID> --log "決策 / 發現" [--next "…"] [--output <路徑或連結>] [--status blocked|waiting_user|ready]
- 以使用者自己的話記錄下他們的決策。
- 您產生的每個檔案或連結都應放入
--output中。 - 等待使用者時使用
--status waiting_user --next "<您確切需要什麼>"。
E. 誠實關閉。 只有在您驗證結果後，才執行 bl done <ID> --session <SID> --log "已交付 …" --output …。當父任務仍有開啟的子任務時，無法關閉。若要放棄任務，請執行 bl drop <ID> --session <SID> --reason "…"。切勿刪除任何內容。
F. 頁尾。 在每個涉及工作的回覆結尾，加上 bl footer --session <SID> [--exclude <剛回報的 IDs>] 的單行輸出。
5. 領域
每個頂層任務都會從 config.json 獲得一個領域（bl areas 可列出所有領域）。子任務會繼承其父任務的領域。選擇最接近的。僅在明顯出現新的持續性工作類別時，才新增一個領域（bl areas --add "名稱"），並在新增時告知使用者。bl areas --rename OLD NEW 可以在設定和所有任務上重新命名領域。
6. 預估工時（每個任務都有）
- 預估工時是助手在平行工作假設下的時鐘時間。通常為 5–60 分鐘，有時數小時，極少數情況下為天。格式：
10m、45m、2h、1h30m、1d。 - 包含驗證結果的時間。
- 倒數計時從認領或建立時開始。看板會以紅色標記過期的任務。
- 當您預估會超時時，請立即重新估算：
--eta 1h --eta-reason "…"。切勿讓任務默默過期。 - 對於
waiting_user任務，預估工時是指使用者回覆後完成所需的時間。
7. 跨工作階段規則
- 認領在其工作階段持續更新任務的期間保持有效。超過 24 小時未觸碰的任務即為過期，任何工作階段都可以接管（接管行為會被記錄）。
- 未經使用者同意，切勿對有效的認領使用
--force。 - 在長時間工作結束前，請為每個已認領的任務留下一個新工作階段可以冷啟動的
--next。使用--status ready --log "已釋放：<狀態>"釋放未完成的工作。 - 對於「有哪些未完成」、「我們到哪裡了」或「另一個工作階段做了什麼」等問題，請從
bl list（--all、--area X、--session Y）回答，而非從對話記憶中回答。 - 待辦清單屬於一個設備。其他設備或雲端上的工作階段僅能透過連接到該設備的方式使用它。
- 如果某個命令回報任務忙碌中，表示另一個工作階段正在此刻寫入它。請稍後重試一次。
8. 何時跳過捕捉
僅對在同一次回覆中完全回答的一次性問題跳過捕捉。捕捉所有其他內容：任何具有可交付成果的事項、任何跨越超過一個回合的事項，以及任何已延遲的事項。如有疑問，請捕捉它。
9. 離線模式（無法連接使用者設備）
- 將任務鏡像到您平台自身的任務清單（如果有），否則鏡像到您回覆中的核取清單。
- 將每個預定的
bl.py操作排成佇列，每個操作一行 JSON 物件，存放在您的暫用空間中的backlog-pending.jsonl（切勿放在使用者專案中）：{"cmd":"add","args":{…},"at":"<iso>"}。 - 一次性告知使用者：「無法連接您的電腦，因此待辦清單更新已排入佇列，並將在恢復連線時同步。」
- 每回合重試連接設備。一旦可連接，按順序重播佇列並執行
bl open。 - 如果工作階段在同步前結束，最後的回覆必須完整列出未同步的任務。
10. 看板
board.html 在每次寫入時重新產生，並每 30 秒自動重新整理。它顯示：
- 按領域劃分的游泳道，包含欄位：待辦 / 進行中 / 受阻 / 等待 <擁有者> / 完成
- 每張卡片上的預估工時與倒數計時，過期任務以紅色標記
- 哪個工作階段建立了、處理了和完成了每個任務
- 可點擊查看完整日誌與輸出
BOARD.md 是相同看板的文字版本。
當使用者要求查看時（例如「顯示我的待辦清單」、「開啟看板」、「有什麼未完成？」）：
- 在持有待辦清單的電腦上，執行
bl board --open以在預設瀏覽器中開啟。 - 如果該電腦上的瀏覽器無法存取（例如透過手機聊天），則從
bl list貼上按領域分組的簡短摘要，並先列出過期和等待使用者的任務。 - 看板是本機檔案。絕不發布、上傳或分享。
11. 平台備註
- MCP 用戶端（任何助手或代理框架）。
scripts/backlog_mcp.py是一個基於 stdio 的標準函式庫 MCP 伺服器，公開了backlog_session、backlog_open、backlog_add、backlog_claim、backlog_update、backlog_done、backlog_drop、backlog_list、backlog_show、backlog_footer、backlog_board、backlog_init和backlog_where。使用命令python3（Windows 使用py，引數-3 <路徑>）和引數<backlog_mcp.py 的路徑>註冊，可選環境變數BACKLOG_DIR。它執行相同的bl.py，因此 shell 和 MCP 路由共用同一個待辦清單。 - API 驅動的代理。 透過 API 呼叫的模型本身無法存取使用者檔案。開發人員在擁有待辦清單的機器上執行 MCP 伺服器（或在其自己的工具背後執行
bl.py），並為模型提供這些工具。託管的程式碼沙箱是暫時的，因此當沙箱結束時，其中的待辦清單會遺失；請勿將其保留在那裡。 - 連結到使用者電腦的 Claude Desktop / 雲端 / 手機工作階段（設備工具，例如
device_bash、device_request_folder_access、device_commit_files；如果它們被延遲載入，請透過您的工具搜尋來載入）。待辦清單資料夾或其父資料夾（例如~/Documents）必須是已連接的資料夾；如果不是，請呼叫device_request_folder_access一次，並附上原因「為了在此電腦上保留您的任務待辦清單」。然後使用已連接的路徑（例如python3 $HOME/mnt/Documents/Aapastech-Backlog/bl.py …）透過device_bash執行命令。若要透過橋接器安裝bl.py，請暫存該檔案並將其提交到設備（device_commit_files）。 - Claude Code / Codex / Cursor / 其他編碼代理 根據第 1 節的表格，直接在其 shell 中執行引擎。
命令參考
bl init [--owner NAME] [--areas "A,B,C"] [--title T] 首次設定 / 更改擁有者、領域或看板標題
bl version 引擎版本
bl where 待辦清單資料夾、引擎版本、看板連結
bl areas [--add NAME …] [--rename OLD NEW] 列出 / 新增 / 重新命名領域
bl session --id SID --label L --surface S [--url U] 註冊工作階段；列印未完成任務
bl open --session SID 此工作階段的未完成任務 + 未認領的任務
bl batch --session SID file.json|- 新增多個任務（巢狀 "children" = 子任務）
bl add --session SID --title T --area A --eta 20m [--parent ID] [--status S] [--next N] [--priority P1]
bl claim ID --session SID [--eta 20m] [--force]
bl update ID --session SID [--status S] [--eta E --eta-reason R] [--next N] [--log L] [--output O] [--area A] [--title T]
bl done ID --session SID [--log L] [--output O] [--force]
bl drop ID --session SID --reason R
bl list [--all] [--area A] [--session SID] [--json]
bl show ID
bl footer --session SID [--exclude IDS]
bl board [--open]