前言¶
OpenSpec 擅長把變更拆成 proposal、tasks、archive 等規格步驟，但規格本身不執行。主會話若自行判斷「哪張票算完成」，容易與任務清單脫節，子智能體的自由文本輸出也難以當作可覈驗的成功依據。下面介紹 Lumos-789 維護的 DSH 插件 Baton：它把已批准的 OpenSpec 變更轉成可執行的 ticket/DAG，用本地 Python CLI 給出確定性動作，主會話只機械轉發，成功僅以 sealed receipt 爲準。
這是什麼¶
Baton 是覆蓋 OpenSpec 變更的 ticket / DAG / session-subagent 控制面。一句話定位：OpenSpec 是計劃面，SessionController 是唯一確定性調度器，主會話是指揮棒下的機械轉發者。 插件在 SkillHub 分類爲工作流；倉庫爲 Lumos-789/baton，DSH 包名爲 dsh-openspec-baton（與無關的 dsh-baton 區分），當前 package 版本爲 0.3.0，許可證 MIT。
它解決的核心問題是：把已批准變更 deterministically 跑完——主會話不自行決定 ticket 狀態，只按 Baton CLI 返回的 actions 原樣交給 DSH subagent，再用 sealed receipt（任務包哈希 + 乾淨 worktree 上 HEAD 前進 + 驗證命令 exit 0）對賬完成通知；無 receipt 的完成會記爲 unknown 並走 recover。Free-text 子智能體輸出不參與成功判定。
核心功能¶
三條接縫的確定性橋接¶
| 接縫 | Baton 的做法 |
|---|---|
| 依賴（章節順序 DAG → 下一步跑什麼） | SessionController.actions() 每次重算 frontier，並原子認領不同任務 |
| 併發（最多 5 個並行任務） | 每個 assignment 一個隔離 git worktree；集成由倉庫級鎖串行 |
| 狀態（子智能體完成 → 任務 resolved） | sealed receipt 是唯一成功證據；集成分支、finalize attempt、在 tasks.md 把對應項標爲 [x] |
Session-subagent 執行（唯一路徑）¶
- 確定性調度：認領、租約、worktree、receipt 校驗、集成、完成均由腳本驅動，模型不決定狀態。
- 隔離 worktree：每個 assignment 一條分支；容量滑動窗口
<=5；集成串行加鎖。 - Sealed receipts：
scripts/receipt.py的 verify / seal 是唯一接受的成功證據（本地完整性證據，非對抗性密碼學證明）。
控制面與可觀測¶
- OpenSpec 原生認知階段：「用 baton 做完 X」意味着先走項目 OpenSpec 流程（對齊 → 寫變更 → 用戶批准），再驅動執行至
complete。 - 活計劃 = 編輯 tasks.md：運行中增刪任務或章節時，下一次
actions()記錄新 plan revision 並重算 frontier；在途 Task Packet 保持不可變。 - 看板：
scripts/ticket_board.py生成純靜態 HTML Kanban（無進程、無端口），輸出在.dsh/baton/下，可用file://打開。
Bundle 主要路徑包括：skills/baton/SKILL.md（baton skill）、scripts/session_control.py（actions / bind / reconcile / status / cleanup）、持久化計劃存儲 .dsh/baton/queue.db 等。
安裝與啓用¶
Baton 是 DSH bundle：掛載 baton skill，執行經 bundled Python CLI scripts/session_control.py。需要 DSH 0.2.1-rc.2 或更新（package.json 約束爲 >=0.2.1-rc.2 <0.3.0）、提供 subagent 工具的 profile（隨附的 dsh-base 即可）、以及 Python 3.10+ 在 PATH 上（或通過 BATON_PYTHON 指定）。
官方安裝方式如下（勿自行拼接 github:owner/repo 形式）：
# 本地 checkout
dsh plugin add /path/to/baton
# 發佈後
dsh plugin add dsh-openspec-baton
自檢 bundle（僅需 python3 + git，對臨時 git 倉庫驅動真實 CLI，健康時 exit 0）：
python3 tests/cli_smoke.py
# CLI SMOKE PASS: actions dispatch, status snapshot, error exit - all green
插件以當前 DSH 進程權限運行；安裝前請閱讀倉庫源碼與 MIT 許可證，確認與你的工作流和合規要求一致。
典型用法¶
1. 準備 OpenSpec 變更與 tasks.md¶
在業務項目中按項目慣用的 openspec/AGENTS.md 流程編寫變更並獲批准，例如：
openspec/changes/<change-id>/proposal.md 與 tasks.md（未勾選的 N.M 任務）。
tasks.md 是 ticket 源：章節表示階段，任務帶 N.M id；較早章節中的任務會阻塞後續章節（同章內可並行）。最小形態示例：
# Tasks: add-login
## 1. Backend
- [x] 1.1 token endpoint
- [ ] 1.2 session persistence
## 2. Frontend
- [ ] 2.1 login form
[x] 表示已 resolved，[ ] 表示 ready；精確解析規則見倉庫 docs/ticket-format.md。
2. 在會話中驅動 Baton¶
對會話說明：
run baton on <project_path> <change-id>
Skill 會循環：actions → subagent → bind → 完成通知 → reconcile，直到 batch 返回 complete。
架構上，主會話調用例如：
session_control.py <project> <change> actions --session-id ... --capacity<=5
返回 dispatch / recover / resolve_merge / wait / blocked / complete 等動作；綁定子智能體 id 後，在 reconcile 階段用 --agent-terminal 等對賬 sealed receipt。
3. 可選：生成 ticket 看板¶
python3 scripts/ticket_board.py build-all /path/to/project
# → .dsh/baton/board-all.html
python3 scripts/ticket_board.py build /path/to/project <change-id>
# → .dsh/baton/<change-id>/board.html
項目僅有一個 change 時，build / scan 可省略 <change-id>；零個或多個 change 時會明確報錯並列出候選。
適用場景與注意¶
適合誰：已在用 OpenSpec 管理變更、且 DSH profile 具備 subagent、希望在規格與執行之間用同一粒度（約 one assignment ~ one task）做確定性編排的團隊或個人。
注意：
- 集成 merge 衝突會保留，不會自動 abort。
- 併發上限爲 5；集成始終串行。
- 同一倉庫還提供 ZCode 插件形態（
.zcode-plugin/plugin.json），掛載相同 skill 與同一 CLI；DSH 用戶以上述 bundle 安裝爲準。 - DSH 社區目錄（如 SkillHub）是獨立站點，與 DeepSeek / 幻方無官方從屬關係；星標與發佈狀態以 GitHub 與目錄頁爲準。
結尾¶
Baton 把 OpenSpec 已批准變更變成可覈驗的完工路徑：調度 deterministic、worktree 隔離、成功只看 sealed receipt。若要進一步瞭解參數與內部命令，以倉庫 README 與 docs/ 爲準。
- 目錄頁：https://www.skillhub.cn/plugins/Lumos-789/baton
- GitHub：https://github.com/Lumos-789/baton
