WeirdSky924/project-change-router-skill

Project Change Router Skill

中文默认版。英文版见 README.en.md。

project-change-router 是一个面向大型仓库的 AI coding skill，可用于 Codex、Claude Code 和 DeepSeek Harness。它的目标不是让 agent 更大胆地猜架构，而是让 agent 更少乱猜：在真正修改代码之前，先用仓库本地的路由 bundle 获取能力归属、canonical root、owner、读写边界、复用风险和处理倾向。

它解决的核心问题是大型项目开发中常见的结构漂移：

• agent 上下文有限，不可能每次完整读取大型全栈项目。
• agent 注意力会漂移，容易只根据局部文件和名字相似做判断。
• 可复用能力可能被重复实现，形成第二套平行中心。
• 本该进入底层共享能力的代码可能被写到 facade、API、UI 或临时目录里。
• 空仓、早期仓和重构仓的边界不稳定，自动推断很容易把临时结构当成长期架构事实。

这个 skill 提供的是一个低 token、可验证、可校准的“项目变更方向索引与边界护栏”。它不替代 agent 的详细工程分析，也不替用户做最终架构决策；它负责在动手前给出路线、证据、强约束、风险原因和后续校准方向。

核心理念

这个项目的设计原则是：

• 少乱猜优先于更聪明地猜。证据不足时宁可保留 unknown 并让 execution_gate=blocked，不要伪装成确定结论。
• profile 优先于纯启发式。真实 owner、public entry、capability 边界和 path pattern 应逐步写入 .project-change-router.yaml。
• 结构证据优先于名字相似。路径、owner、public API、依赖关系、测试绑定比语义相似更可靠。
• 早期仓库默认保守。seed / emerging 阶段不应轻易自动 extend 或 extract。
• review 不是失败，也不是写入门禁；它是 action 建议层的调查方向。真正决定当前是否可写的是 execution_gate。
• 路由输出是一体化契约。execution_gate、安全信封和 typed findings 必须遵守，action 和解阻建议用于辅助判断，不能替代源码分析。
• 结果必须能持续变准。人工 override、误判、profile 修正和真实案例应沉淀到 feedback 与 evaluation。

两层使用模型

PCR 的输出分为两层，使用时不要混在一起理解。

必须执行层：

• 必须先读 execution_gate.state：pass、conditional、blocked 是唯一权威写入状态。
• 必须尊重 allowed_write_paths、forbidden_write_paths 和 must_read_before_edit。
• 必须识别并保护已有 owner、public entry、canonical root 和依赖方向。
• 不能在已有能力可能存在时新建第二套平行实现中心。
• blocked 时禁止产品代码写入；conditional 时必须先执行 required_commands 并限制在给定 envelope；pass 也不能越过 envelope。
• veto_reasons、unknown evidence、生命周期、高风险重叠和 provisional 边界必须追溯到 typed finding 与 policy rule，不能忽略或仅凭 action 覆盖。

参考建议层：

• action 是当前证据下的处理倾向，不是最终工程命令。
• recommended_next_steps、safe_next_steps、analysis_directions、why_not_actions 和 profile_repair_hints 是解阻方向和调查提示。
• action=review 不等于永远不能做，也不自动等于 blocked；它表示应优先补证据、补 profile、读源码或协调确认，最终仍以 execution_gate 为准。
• 最终实现方案仍必须来自真实源码分析、依赖追踪、测试和用户确认。

能力范围

这个 skill 可以：

• 为目标仓库生成本地 project-change-router/ bundle。
• 识别仓库模块、capability、owner、public entry、路径归属和依赖方向。
• 根据请求和 changed paths 输出 route report，包含强约束和建议动作。
• 用统一 run_change_flow.py 编排 route、freshness、dependency、public API、structure、governance 和 reuse 检查，默认只返回 compact 安全信封并把完整证据保存为内容寻址 artifact。
• 把所有门禁证据规范化为可追溯 typed findings，并以单一版本化规则表确定 execution_gate。
• 基于 changed-path 的正反向依赖闭包增量复用可信全局快照，而不是停止全局不变量检查。
• 将 reuse 拆为 capability 内、跨 capability 和 new/extract/lifecycle 扩展扫描三条独立覆盖通道。
• 对重复实现、错误边界、public API 绕过、反向依赖和 runtime cycle 做 guardrail 检查；TypeScript type-only edge 不会被误算成 runtime edge。
• 用 commit、内容结构摘要、索引路径、stale entry 和实际 changed paths 校验 freshness。
• 用 exact baseline 阻止中央文件、800/1200 行文件、禁用实现根和第二 canonical owner 的新增净增长。
• 通过 path-to-capability-map.yaml 暴露路径归属、共享归属和未覆盖模块。
• 用 schema 校验 bundle 与报告。
• 用 evaluation set 检查路由质量是否退化。
• 用 governance audit 检查 profile/catalog 同步、ownership 颗粒度、contract 质量、forbidden density、evaluation 覆盖和 capability 生命周期。
• 在 Codex / Claude Code 安装时追加提示块，并通过 DeepSeek Harness skill catalog 暴露触发描述，让 agent 更容易在功能级 create / modify / delete 前主动触发该 skill。