前言¶

在大型倉庫裏使用 AI coding agent 時，常見問題不是“寫不出代碼”，而是容易在局部上下文裏猜錯方向：重複實現已有能力、把共享邏輯寫進臨時目錄或 facade、繞過 public API、形成反向依賴，或者把早期臨時結構當成穩定架構。

DeepSeek Harness（DSH）強調“一切皆插件”，其社區目錄是獨立站點，與 DeepSeek / 幻方無官方從屬關係。WeirdSky924/project-change-router-skill 就是面向這類場景的 DSH 插件：在 agent 修改代碼之前，先讓 agent 讀取項目本地的路由 bundle、route report 和 execution gate，再決定如何進入實現。

下面介紹它的定位、核心能力、安裝方式和典型用法。

這是什麼¶

WeirdSky924/project-change-router-skill 是一個面向大型倉庫的 AI coding skill，可用於 Codex、Claude Code 和 DeepSeek Harness。它由 WeirdSky924 維護，許可證爲 MIT。

它的一句話定位是：

Project-level direction, boundary, and reuse governance for AI coding agents.

它不是替代詳細代碼閱讀、依賴追蹤、測試設計和架構分析，而是在編碼前提供一組可驗證的項目級約束：

• 爲目標倉庫生成本地 project-change-router/ bundle。
• 識別倉庫模塊、capability、owner、public entry、路徑歸屬和依賴方向。
• 根據請求和 changed paths 輸出 route report，包含強約束和建議動作。
• 將門禁證據規範化爲可追溯的 typed findings，並以版本化規則表確定 execution_gate。

這裏有一個關鍵邊界：action 是處理建議和調查方向，不是最終架構命令。寫入狀態必須讀取 execution_gate.state；action=review 本身不授予也不撤銷寫權限。

核心能力¶

路由與門禁¶

這個插件把“路由建議”和“是否可寫”分開處理。

它可以用 run_change_flow.py 編排以下檢查：

• route
• freshness
• dependency
• public API
• structure
• governance
• reuse

門禁狀態通過 execution_gate 表達。根據已覈實事實，需要重點區分三種狀態：

• blocked：存在阻塞項時禁止產品代碼寫入。
• conditional：必須先執行 required_commands，並限制在給定 envelope 內寫入。
• pass：可以寫入，但也不能越過 envelope。

compact 輸出中會保留安全信封字段，包括：

execution_gate
veto_reasons
allowed_write_paths
forbidden_write_paths
unknown_evidence
artifact_path
artifact_digest
output_complete

這些字段用於表達當前請求是否可以繼續寫入、哪些路徑允許、哪些路徑禁止，以及證據是否完整。

檢查與證據¶

插件會對多個容易引發結構漂移的問題做 guardrail 檢查，包括：

• 重複實現
• 錯誤邊界
• public API 繞過
• 反向依賴
• runtime cycle

它還會用以下材料校驗 freshness：

• commit
• 內容結構摘要
• 索引路徑
• stale entry
• 實際 changed paths

對於倉庫結構增長，它會用 exact baseline 阻止以下類型的新增淨增長：

• 中央文件
• 800/1200 行文件
• 禁用實現根
• 第二 canonical owner

它還提供以下輔助檢查：

• 用 schema 校驗 bundle 與報告。
• 用 evaluation set 檢查路由質量是否退化。
• 用 governance audit 檢查 profile/catalog 同步、ownership 顆粒度、contract 質量、forbidden density、evaluation 覆蓋和 capability 生命週期。
• 通過 path-to-capability-map.yaml 暴露路徑歸屬、共享歸屬和未覆蓋模塊。

輸出與集成¶

默認情況下，插件支持 compact 安全信封輸出，並把完整證據保存爲內容尋址 artifact。這樣可以在 token 成本較低的情況下，保留可追溯的完整證據。

它也支持以下輸出控制：

• --format full-json：返回完整報告。
• --format artifact-reference：返回最小引用。
• --field：只能增加普通字段。
• --exclude-field：不能隱藏安全字段。

在 agent 集成方面，它支持：

• 在 Codex 和 Claude Code 安裝時追加提示塊。
• 通過 DeepSeek Harness skill catalog 暴露觸發描述。

安裝與啓用¶

Python 要求：

Python >= 3.10

DeepSeek Harness 插件驗證遵循 Harness 當前 Node 要求：

^22.19.0 || >=24.0.0

僅安裝 filesystem skill 不額外啓動 Node 進程。

先安裝依賴：

pip install -r requirements.txt

或使用開發模式安裝：

pip install -e .[dev]

然後同時安裝到 Codex、Claude Code 和 DeepSeek Harness：

python scripts/install_skill.py --target all --inject-hints

安裝路徑如下：

• Codex：%USERPROFILE%\.codex\skills\project-change-router
• Claude Code：%USERPROFILE%\.claude\skills\project-change-router
• DeepSeek Harness：$DSH_HOME/skills/project-change-router
• 未設置 DSH_HOME 時，DeepSeek Harness 默認爲：~/.dsh/skills/project-change-router

--inject-hints 只爲需要規則入口提示的 Codex 和 Claude Code 追加標記塊，不會重寫整個文件。

典型用法¶

下面用一次請求和一條 changed path 跑 change flow：

python scripts/run_change_flow.py --repo <repo-root> --request "Add invoice refund support" --changed-path services/billing/refund.py --format compact-json

這條命令會根據請求和已修改路徑生成 route report。默認 compact 輸出會保留安全信封字段：

execution_gate
veto_reasons
allowed_write_paths
forbidden_write_paths
unknown_evidence
artifact_path
artifact_digest
output_complete

如果需要查看完整報告，可以使用：

--format full-json

如果只需要最小引用，可以使用：

--format artifact-reference

如果使用 --field 或 --exclude-field，需要注意：

• --field 只能增加普通字段。
• --exclude-field 不能隱藏安全字段。

實際處理時，建議先看 execution_gate.state，再判斷是否可以繼續寫入：

• blocked 時禁止產品代碼寫入。
• conditional 時必須先執行 required_commands，並限制在給定 envelope 內。
• pass 時也不能越過 envelope。

適用場景與注意¶

這個插件更適合以下場景：

• 大型倉庫中，agent 無法每次完整讀取整個項目。
• 倉庫中存在多個模塊、capability、owner 和 public entry。
• 需要防止重複實現、錯誤邊界、public API 繞過、反向依賴和 runtime cycle。
• 需要在 Codex、Claude Code 或 DeepSeek Harness 中給 agent 增加變更前的路由檢查。

需要注意：

• 它不替代詳細代碼閱讀、依賴追蹤、測試設計和架構分析。
• 它輸出的是路由建議、強約束和證據，不是最終架構命令。
• action=review 本身不授予也不撤銷寫權限；寫入狀態必須讀取 execution_gate.state。
• DSH 插件會隨當前 dsh 進程權限運行，因此安裝前應檢查源碼、腳本行爲和 MIT 許可證。

結語¶

WeirdSky924/project-change-router-skill 的價值在於給 AI coding agent 增加一層項目級變更約束：在寫代碼之前，先確認 capability 歸屬、路徑邊界、依賴方向、複用風險和寫入門禁。對於大型倉庫，這有助於把“先改了再說”變成“先看證據，再決定寫入”。

相關頁面：

• 目錄頁：https://www.skillhub.cn/plugins/WeirdSky924/project-change-router-skill
• GitHub：https://github.com/WeirdSky924/project-change-router-skill