CarryCtx 核心技能
CarryCtx 為 AI 程式碼代理提供一流的專案狀態與上下文連貫性。它讓代理能夠管理任務、追蹤細粒度進度、建立檢查點快照、維護 AST 程式碼依賴圖、執行 stdio MCP 伺服器、套用工作流程預設，並在會話重啟與 Git worktree 之間無縫保留上下文。
何時套用
請在以下情況使用 CarryCtx 指令：
- 開始新任務或會話：註冊代理身份、啟動會話、還原上下文 (
carryctx resume)。 - 管理專案任務：建立、認領、開始、完成、封鎖或取消任務 (
carryctx task ...)。 - 追蹤細粒度進度：記錄結構化的
todo、block、risk與note項目。 - 儲存狀態／建立檢查點：在結束會話或切換焦點之前，捕捉當前工作進度、git 狀態與剩餘工作。
- 程式碼圖探索：掃描 AST 模組依賴 (
carryctx graph scan)，並匯出 Mermaid/DOT/ASCII 圖表 (carryctx graph export)。 - AI 代理工具整合 (MCP)：透過模型上下文協定 stdio 伺服器，將專案上下文暴露給 Cursor / Windsurf / AGY (
carryctx mcp)。 - 標準化工作流程 (預設)：列出、檢視與套用專案工作流程藍圖、編碼規則與代理角色 (
carryctx preset ...)。 - 平行任務工作：在專屬的 Git worktree 中建立與隔離任務 (
carryctx worktree ...)。 - 診斷健康問題：執行
carryctx doctor以找出孤立任務、遺失的鉤子與資料庫問題。 - 清理舊資料：使用
carryctx project prune清理已完成的任務，保持資料庫輕量。 - 代理分析：使用
carryctx stats稽核代理會話長度、任務指標，並匯出 Markdown/CSV 報告。 - 按內容尋找先前工作：使用
carryctx search "<query>"按關鍵字尋找任務、進度項目、檢查點或決策，無需手寫 SQL 或 grep 提交訊息。
先決條件
- 安裝 CarryCtx CLI (
cargo install carryctx或預先建置的二進位檔)。 - 在專案儲存庫中初始化 CarryCtx：
carryctx init。
快速參考
| 動作 | 指令 | 目的 |
|---|---|---|
| 代理設定 | carryctx agent register --name "$(whoami)" --provider "claude-code" | 註冊代理身份 |
| 當前代理 | carryctx agent current | 顯示當前活躍的代理身份 |
| 啟動會話 | carryctx session start | 開始受追蹤的工作會話 |
| 還原上下文 | carryctx resume | 擷取當前任務、進度與下一步行動 |
| 建立任務 | carryctx task create --title "..." [--depends-on CTX-0001] | 定義新任務 |
| 認領任務 | carryctx task claim CTX-0001 | 將任務指派給當前代理 |
| 編輯任務 | carryctx task edit CTX-0001 [--title ...] [--priority ...] [--description ...] | 更新任務標題、優先級或描述 |
| 開始任務 | carryctx task start CTX-0001 | 將任務標記為進行中 |
| 追蹤進度 | `carryctx progress <todo | block |
| 檢查點 | carryctx checkpoint --done "..." --remaining "..." | 儲存語意豐富的狀態快照 |
| 掃描程式碼圖 | carryctx graph scan | 將 AST 依賴萃取至 SQLite 圖表 |
| 匯出圖表 | `carryctx graph export --type <mermaid | dot |
| MCP Stdio 伺服器 | carryctx mcp | 啟動 MCP stdio 伺服器，提供 6 項代理工具 |
| 套用預設 | carryctx preset apply <preset_name> | 注入工作流程 SOP、規則或角色 |
| Worktree | carryctx worktree create CTX-0001 | 為任務建立隔離的 git worktree |
| 結束會話 | carryctx session end | 安全結束會話並建立檢查點 |
| 診斷 | carryctx doctor | 診斷專案健康狀態 |
| 安裝鉤子 | carryctx hooks install | 在每次 git commit 時自動建立檢查點 |
| 清理資料 | carryctx project prune --older-than 30 | 清理舊的已完成任務 |
| 代理統計 | carryctx stats [--markdown] [--output file.csv] | 檢視指標並匯出效能報告 |
| 決策 | carryctx decision add --title "..." --task CTX-0001 | 記錄架構決策 |
| 交接 | carryctx handoff create --target <agent> --task CTX-0001 | 在代理之間轉移工作 |
| 會話暫停 | carryctx session pause | 暫停活躍會話的計時器 |
| 會話恢復 | carryctx session resume | 恢復暫停的會話 |
| 搜尋 | `carryctx search "" [--type task | progress |
輸出行為 (0.5.2+)
文字輸出（預設 --format text）設計上非常簡潔：實體指令每筆記錄只印一行短訊息（Task created: CTX-0321，agent current 只印出名稱，列表顯示 display_id、狀態與截短的標題／摘要），讓代理上下文保持小巧。當需要完整記錄時：
--verbose（全域標誌）或在.carryctx/config.toml中設定[output] verbose = true可還原完整的漂亮列印記錄。--fields display_id,status,summary（全域標誌）或每個指令的[output.fields]表格，可將文字與 JSON 輸出修剪為允許列表。--format json永遠回傳完整的信封。
JSON 輸出保持不變，依然是機器合約：每個成功都在 stdout 上輸出一個信封，每個錯誤都在 stderr 上輸出一個信封。
標準代理工作流程
1. 會話初始化與上下文還原
在互動開始或代理重新啟動之後：
# 註冊並設定身份（若尚未設定）
carryctx agent current || carryctx agent register --name "claude" --provider "claude-code"
# 啟動會話並載入當前上下文
carryctx session start
carryctx resume
若要暫停與恢復會話：
carryctx session pause # 暫停活躍會話（計時器停止）
carryctx session resume # 恢復暫停的會話
carryctx session end # 結束會話（可選檢查點）
carryctx session abandon # 結束會話但不建立檢查點
2. 程式碼依賴分析（圖表子系統）
在修改程式碼或重構模組之前：
# 1. 掃描程式碼庫的 AST 依賴
carryctx graph scan
# 2. 匯出以特定模組為中心的子圖
carryctx graph export --type mermaid --focus "src/application/stats.rs" --depth 2
# 3. 匯出模組層級的簡潔 ASCII 架構概覽
carryctx graph export --type ascii --compact
3. 工作流程預設與規則注入
注入標準作業程序或編碼指南：
# 列出可用的工作流程預設
carryctx preset list
# 將標準 bugfix 工作流程預設套用至當前專案
carryctx preset apply workflows/bugfix
4. 任務生命週期
# 列出開啟中的任務
carryctx task list --status ready
# 認領並開始任務
carryctx task claim CTX-0001
carryctx task start CTX-0001
# 驗證後將任務標記為完成
carryctx task complete CTX-0001
5. 細粒度進度追蹤
隨著工作進展，記錄結構化的進度項目：
carryctx progress todo "為認證中介層撰寫單元測試"
carryctx progress todo "實作 JWT token 驗證"
carryctx progress block "等待 API 端點規格確認"
carryctx progress risk "上游相依項目有重大變更"
carryctx progress note "使用 LRU 快取最佳化 token 查詢"
# 將待辦標記為已完成：
carryctx progress complete PX-0001
6. 建立檢查點
在結束會話、切換任務或交接工作之前儲存狀態：
carryctx checkpoint \
--done "完成後端認證端點" \
--remaining "前端登入表單整合" \
--blocker "無"
7. Worktree 平行處理
當同時處理獨立的任務時：
carryctx worktree create CTX-0002
# 切換至連結 CTX-0002 的隔離 worktree 目錄
7a. 記錄決策與交接
捕捉架構決策並在代理之間交接工作：
# 記錄一個與任務連結的架構決策 (ADR)
carryctx decision add --title "使用 SQLite 作為儲存" --task CTX-0001
# 列出或搜尋決策
carryctx decision list
carryctx decision search --keyword SQLite
# 將決策標記為已被較新決策取代
carryctx decision supersede DEC-0001 --by DEC-0002
# 建立交接，將工作轉移給另一個代理
carryctx handoff create --target <agent-ulid> --summary "實作 API" --task CTX-0001
# 接受、拒絕或關閉交接
carryctx handoff accept HO-0001
carryctx handoff reject HO-0001 --reason "非我的領域"
carryctx handoff close HO-0001
7b. 全文搜尋專案歷史
根據內容尋找先前的工作，無需記住是哪個分支或任務修改了它。搜尋任務標題／描述、進度項目、檢查點註記與決策，全部按相關性排序：
# 搜尋所有項目
carryctx search "markdown worker protocol"
# 限定範圍為一種實體類型
carryctx search "retry backoff" --type checkpoint
# 依所屬任務的狀態或擁有者代理縮小範圍
carryctx search "auth" --status in_progress
carryctx search "auth" --owner claude-code
每個命中結果都包含所屬任務的顯示 ID、狀態，以及（已知時）工作所在的分支——在開始相關工作之前使用此功能，以避免重複解決已經解決的問題；在交接之前使用它，以引導接收代理直接找到解釋先前選擇的檢查點或決策。
8. 結束會話與報告
# 結束工作會話
carryctx session end
# 匯出專案統計報告，用於 PR 描述或文件
carryctx stats --markdown --output /tmp/project_stats.md
9. 模型上下文協定 (MCP) 整合
要將 CarryCtx 直接掛鉤到 Cursor / Windsurf / AGY：
{
"mcpServers": {
"carryctx": {
"command": "carryctx",
"args": ["mcp"]
}
}
}
暴露的 MCP 工具：
carryctx_graph_explorer：查詢、掃描與匯出專案上下文圖carryctx_context_manager：管理持久化上下文、檢查點與狀態快照carryctx_task_manager：管理專案任務、相依關係與優先級carryctx_progress_tracker：管理任務進度、備註與封鎖項目carryctx_decision_logger：記錄與搜尋架構決策記錄carryctx_project_admin：管理專案資料庫、統計、冷儲存歸檔與設定
10. 除錯與疑難排解
啟用結構化的除錯日誌以診斷問題：
# 顯示 CarryCtx 操作的除錯日誌
export RUST_LOG=carryctx=debug
carryctx task list # 在指令結果之前查看除錯輸出
# 只顯示錯誤
export RUST_LOG=error
carryctx status
# 執行診斷
carryctx doctor # 檢查專案健康狀態
carryctx doctor --json # 機器可讀的診斷輸出
程式碼代理的最佳實踐
- 開始時一律執行
carryctx resume：立即讓代理重新定位到當前任務與進度。 - 大型重構前掃描程式碼圖：
carryctx graph scan防止破壞上游相依項目。 - 明確認領任務：防止多個代理在同一儲存庫上工作時重複執行。
- 使用結構化進度項目：在執行步驟期間持續更新
todo、done與block。 - 停止前建立檢查點：在交出控制權或完成複雜的多步驟工作之前，務必建立檢查點。
- 首次使用或升級後執行
carryctx doctor：在設定缺口導致執行階段錯誤之前及早發現。