前言¶

在大型仓库里使用 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