dsh-ptc-discipline：PTC 模式下的硬目標與待辦閘門\n\n# 前言\n\nDSH 的 PTC 模式已經把模型直接調用擋到 run_code 後面，其餘工具通過生成的 SDK 訪問。這個方向減少了模型直接亂調工具的空間，但沒有解決另一個常見問題：模型可能在沒有目標、沒有任務拆解的情況下就開始執行。\n\n下面介紹 yuan-source-666 維護的 dsh-ptc-discipline。它是一個 DSH agent preset，在 PTC 模式之上再加一道硬閘門：會話裏沒有 active goal、沒有非空 todo、也沒有 in_progress todo 時，工具調用會被直接拒絕。它和“寫進系統提示詞請先做計劃”的區別是，這裏的拒絕由 ctx.tools.guard() 執行，不是靠模型自覺。\n\n# 這是什麼\n\n- 插件名：dsh-ptc-discipline\n- 維護者：yuan-source-666\n- 目錄分類：工作流\n- 形式：DSH agent preset\n- 版本：package.json 中爲 1.1.0\n- 許可證：MIT\n\n它解決的問題不是 PTC 本身，而是在 PTC 下補一個前置紀律：先建立可驗收目標，再建立完整待辦，然後才允許寫文件、執行 bash 等操作。\n\n# 核心機制\n\nPTC 的呈現方式沿用 @deepseek-ai/dsh-agent-tool-presentation 的 mode: ptc：模型只能直接調用 run_code，其餘工具通過生成的 SDK 訪問。\n\n閘門掛在 ctx.tools.guard() 上，覆蓋所有工具調用，包括 run_code 內部的 await tools.xxx() 子調用。放行條件是：\n\n1. 存在 active 的 goal。\n2. todo 列表非空。\n3. 至少一條 todo 的狀態是 in_progress。\n\n固定順序爲 create_goal → todo_write → 其餘一切。被拒時返回原因，例如：\n\n\nDiscipline gate: no goal (call create_goal with the verifiable end condition); no todo list\n(call todo_write with the complete task list). Seed it from inside run_code first — create_goal,\nthen todo_write, then call \"write\".\n\n\n閘門規則對應如下：\n\n| 條件 | 不滿足時 |\n| — | — |\n| 存在 active goal | no goal (call create_goal …) 或 goal is \"paused\" (…) |\n| todo 列表非空 | no todo list (call todo_write …) |\n| 至少一條 in_progress | no todo is in_progress … 或 every todo is completed … |\n\n# 實現位置\n\nctx.tools.guard() 掛在本 preset 的 preset scope 上。preset scope 是每個加入該 preset 的 agent scope 的祖先，guardReason 沿 scope chain 由遠及近求值，所以它精確覆蓋該 preset 的所有 agent，不外溢到其他 preset，也不需要全局狀態。\n\n守衛在 tools/pre-execute waterfall 之後執行。任何守衛都不能強制放行另一個守衛的拒絕。PTC 的 SDK 子調用走 scheduler.prepare → prepareExecution → preExecute → guardReason，和原生調用同一條管道，因此 await tools.write(...) 同樣過閘。\n\n# 豁免與 fail-open\n\n三類調用不在閘門內：\n\n- run_code 本身：它是 PTC 的唯一直接入口，攔住它會直接死鎖。\n- 引導工具：create_goal、get_goal、update_goal、todo_write、ask_user_question、skill、present。不建紀律的工具不應被紀律攔住。\n- 非 root agent：create_goal 要求 root agent 當前 turn 有真人消息，子 agent 滿足不了；不豁免會讓所有 subagent 立刻死鎖。\n\ngoal / sessionProjections 服務不可用時，閘門 fail-open，即不攔截。這樣在沒裝 goal、todo 相關插件的組合裏，不會把 agent 徹底鎖死。\n\n# 兼容性\n\n插件面向 DSH 0.2.2+，並跟隨官方 ptc preset 做對齊。README 列出三處變化：dsh-tool-subagent-control/list-agents 子路徑已從 exports 移除，modelSelectionSettings 更名爲 modelSelection 並新增 modelDiscovery，官方新增的 dsh-tool-executor-ptc 一併加入。閘門邏輯未改動。\n\n注意：如果刪掉 dsh-tool-subagent-control 整行（而不只是 list-agents 子路徑），子 agent 的 send_message / interrupt_agent 控制工具會一併消失，子 agent 只能一次性返回結果、無法再追問或中斷。\n\n# 安裝與啓用\n\n安裝命令來自 README：\n\nsh\nnpx dsh plugin add yuan-source-666/dsh-ptc-discipline\n\n\n在支持 bundle 的應用裏也可以用 plugin_manager：\n\njsonc\n{ \"action\": \"install_bundle\", \"target\": \"yuan-source-666/dsh-ptc-discipline\" }\n\n\n卸載：\n\njsonc\n{ \"action\": \"remove_bundle\", \"target\": \"dsh-ptc-discipline\" }\n\n\n裝好後，在新建會話裏選擇 PTC 紀律 preset 即可生效。\n\n# 配置\n\nREADME 給出如下配置骨架：\n\nyaml\n- id: ptc-discipline\n name: 'dsh-ptc-discipline'\n config:\n requireGoal: true # 默認 true\n requireTodo: true # 默認 true\n requireActiveTodo: true # 默認 true；關掉只要求列表非空\n bootstrapTools: [ ... ] # 默認見上表\n sectionText: ... # 替換寫進系統提示詞的那段紀律說明\n\n\nrequireActiveTodo 關閉後，閘門只要求 todo 列表非空，不再要求存在 in_progress。\n\n# 典型用法\n\n1、按上面命令安裝插件。\n2、新建 DSH 會話，選擇 PTC 紀律 preset。\n3、發起一個任務。如果會話裏還沒有 goal / todo，第一個工具調用會被拒，報錯會提示先執行 create_goal 和 todo_write。\n4、在 run_code 裏補上紀律。順序是：先 create_goal，再 todo_write，最後才調用真正要執行的工具。\n5、後續工具調用通過閘門後繼續執行。\n\nREADME 的已知邊界提到，todo 每個新 turn 會清空（todos projection 在 turn/start 重置），goal 跨 turn 存活。所以第二個請求開始時，閘門會再次要求 todo_write。\n\n驗證可以運行：\n\nsh\nnpm test\n\n\ntest/gate.test.mjs 用假 Cordis 上下文覆蓋 10 個場景，包括空會話拒絕、goal active 但無 todo 拒絕、有一條 in_progress 放行、goal paused 拒絕、subagent 豁免、服務缺失 fail-open 等。\n\n# 適用場景與注意\n\n適合已經在 PTC 模式下工作、希望每次執行都強制先有目標和任務拆解的場景。也適合想驗證 ctx.tools.guard() 這類 scope 級硬約束如何不外溢到其他 preset 的人。\n\n使用前注意幾點：\n\n- 插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證。本項目 package.json 標註 MIT。\n- 只有 run_code 一個直接入口，被拒後模型必須再寫一個 run_code 程序把紀律補上。\n- plan 模式會和 requireTodo 打架：plan-mode 的 guidance 建議規劃階段別用 todo_write，但閘門此時仍要求 todo。在 plan 下應給這個 preset 關掉 requireTodo，或先建一個寫計劃的 todo。\n- 單測只覆蓋閘門邏輯，不覆蓋真實會話裏的完整鏈路。\n- 社區目錄是獨立站點，與 DeepSeek / 幻方無官方從屬關係；本插件也不是官方應用商店中的預置項。\n\n# 結尾\n\ndsh-ptc-discipline 的價值在於把目標與 todo 檢查從提示詞建議升級爲工具調用前的硬約束，並用 fail-open 和三類豁免避免死鎖。目錄頁與源碼如下：\n\n- 目錄頁：https://www.skillhub.cn/plugins/yuan-source-666/dsh-ptc-discipline\n- GitHub：https://github.com/yuan-source-666/dsh-ptc-discipline\n¶