前言¶
在 DSH 環境中開發多步驟任務時，會話中斷或上下文壓縮容易導致進度丟失。爲了解決這個問題，需要一種將規劃、狀態和復盤記錄持久化到磁盤的機制。
插件介紹¶
trailmap（軌跡地圖）是一個工作流插件，由 JohnXu22786 維護。它將任務的所有信息存儲在工作區的 .trail/ 目錄中。無論會話如何中斷，都可以通過讀取狀態繼續工作。
核心功能¶
- 狀態機驅動：步驟狀態在
todo、in progress和done之間流轉，支持取消和恢復。依賴未滿足時步驟自動標記爲“blocked”。 - 計劃模板生成器：根據任務類型（research/development/docs/blank）一鍵生成里程碑骨架，依賴關係自動 wiring。
- 依賴標註：步驟可聲明依賴，啓動步驟前校驗依賴，自動檢測循環依賴。
- 審計事件流：所有進展寫入追加日誌，復盤時自動引用。
- 復盤紀要：任務結束時自動彙總里程碑、步驟、取消情況和時間線，支持手動編寫復盤部分。
- 確定性完成門：
check命令驗證所有步驟關閉且結構正確。 - 三種接口：提供 dsh 工具（10 個
trailmap_*）、獨立 CLI（trail）和技能（SKILL.md）。
安裝與啓用¶
安裝前請確保環境滿足 Node >= 20。使用官方安裝命令：
dsh plugin --profile demo add github:JohnXu22786/file-planning
插件會通過 cordis.patch.yml 注入配置，並將工具註冊到 ctx.tools，模型可調用 trailmap_* 工具。
典型用法¶
使用 CLI 進行初始化、流轉和復盤：
# 1. 初始化計劃（使用 blank 類型以運行完整循環）
node bin/trail.js init "Add regression tests to the toolchain" --kind blank
# 2. 查看狀態
node bin/trail.js status
# 3. 啓動第一個里程碑
node bin/trail.js start m1-1
# 4. 執行工作...
# 5. 完成步驟
node bin/trail.js finish m1-1
# 6. 完成門檢查（步驟關閉且結構正確時通過）
node bin/trail.js check
# 7. 復盤並歸檔
node bin/trail.js debrief --close
也可以通過 npm link 後直接使用 trail 命令。
注意事項¶
- 目錄權限：插件以當前 DSH 進程權限運行，請確保有權限讀取和寫入
.trail/目錄。 - 版本控制：
.trail/目錄默認排除在版本控制之外，建議手動檢查.gitignore。 - 依賴：依賴
@deepseek-ai/cordis和@deepseek-ai/dsh-tools。 - 代碼審查：安裝前請檢查源碼與許可證（MIT）。
