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 的详细工程分析，也不替用户做最终架构决策；它负责在动手前给出路线、证据、强约束、风险原因和后续校准方向。

Project Change Router overview

核心理念

这个项目的设计原则是：

少乱猜优先于更聪明地猜。证据不足时宁可保留 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。

它不应该：

替代详细代码阅读、依赖追踪、测试设计和架构分析。
把 action 当成无需分析即可执行的最终命令。
把 action=review 本身当作放行或阻塞依据；写入状态必须读取 execution_gate。
把 generated-only bundle 当作成熟架构事实。
因为名字相似就强行复用或扩展已有 capability。
在没有确认 canonical root 时创建第二套实现中心。

路由动作

resolve_entry.py 会输出五类动作。这些动作是处理建议和调查方向，不是最终架构命令：

reuse：使用已有 capability，不修改核心实现。
extend：在已有共享 capability 或兼容扩展点上增加行为。
extract：先把重复逻辑抽到共享 capability，再让调用方复用。
new：没有合适复用目标，应建立新的隔离 capability 边界。
review：优先补证据、补 profile、做跨能力协调或请求人工确认；它描述调查方向，不授予也不撤销写权限。

review 需要特别理解：它不是“系统没用”，也不是永久阻塞，更不是门禁状态。在空仓或早期仓里，可能出现：

{
  "action": "review",
  "routing_confidence": 0.0,
  "routing_confidence_level": "low",
  "decision_confidence": 0.95,
  "decision_confidence_level": "high"
}

这表示：系统对“应该落到哪个 capability”没有把握，但对当前 action 建议很有把握。是否可以写产品代码必须另读 execution_gate.state；例如相关路径未索引时会是 blocked，而只有无关且不扩大的可信历史债务时可为 conditional。

仓库阶段策略

router 会根据仓库成熟度推断 repo_stage：

seed：空仓或极早期仓，默认只允许明显的新边界或 review。
emerging：已有少量结构，但 capability 边界仍保守，provisional 不自动成为强复用目标。
structured：模块边界较稳定，可以更完整地使用 reuse、extend、extract。
governed：以 profile、owner、public entry、evaluation 和 guardrail 为主要依据。

capability 自身也有阶段：

provisional
candidate
stable
governed-capability
deprecated

早期仓库不要过早固化 generated capability。推荐先写最小 ownership/profile，再随着真实开发逐步补 capability、public entry、contract、test binding 和 evaluation case。

一体化路由报告

route report 不是只给一个 action。它是一个完整路由契约，核心字段包括：

action
decision_basis
routing_confidence
routing_confidence_level
decision_confidence
decision_confidence_level
primary_capability
primary_capability_stage
secondary_capabilities
candidate_capabilities
required_reads
required_checks
recommended_next_action
recommended_next_steps
why_not_actions
confidence_reasons
veto_reasons
positive_signals
negative_signals
risk_signals
authorization_context
route_fingerprint
runtime_identity
typed_findings
execution_gate
gate_shadow
must_read_targets
inventory_targets
unresolved_read_targets
authorization_request

七类治理输出也是同一个 route report 的一等字段，不是外挂能力：

review 后处理：block_reason、missing_evidence、analysis_directions、safe_next_steps、suggested_questions、override_requirements
写入约束：allowed_write_paths、forbidden_write_paths、must_read_before_edit
profile 修复方向：profile_repair_hints，治理审计报告中还有 repair_suggestions
变更后收口：post_change_closeout
删除、合并、废弃能力治理：capability_lifecycle_action
跨栈复合路由：composite_route
真实回归沉淀：evaluation_regression_hints

详细契约见 references/governance-outputs.md。

Integrated route contract

0.4 执行门禁与证据模型

PCR 0.4 把“路由建议”和“是否可写”彻底拆开：

字段	作用
`action`	`reuse / extend / extract / new / review`，只提供工程调查与处理方向
`execution_gate.state=pass`	相关证据完整且没有任务相关阻塞项；仍须遵守读写 envelope
`execution_gate.state=conditional`	只剩已证明无关或不扩大的可信历史债务；必须执行前置命令并保持有界写入
`execution_gate.state=blocked`	存在 unknown/incomplete、任务相关 P0/P1、owner/canonical/public API/lifecycle/高风险问题或硬不变量冲突

门禁不重新扫描仓库，也不做第二套路由推理。所有结果都由一个版本化 policy table 对 schema-valid typed findings 做确定性归约。每条 finding 包含稳定 finding_id、来源、严重级、全局/闭包/局部不变量分类、delta、task relevance、evidence status、policy rule、路径/能力、相关性链路与证据摘要。

gate_shadow 仅保留旧门禁与新门禁的对照诊断；0.4 中 execution_gate.authoritative=true，旧门禁不再决定写入。output_complete=false 或无法满足新版精度的 schema-v1 输入必须形成 unknown/incomplete finding 并阻塞，不能用乐观默认值补齐。

统一入口：

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

默认 compact 输出始终保留不可投影的安全信封：execution_gate、veto_reasons、allowed_write_paths、forbidden_write_paths、unknown_evidence、artifact_path、artifact_digest、output_complete。完整 route、checks、findings、cache/baseline 证据写入内容寻址 artifact；--format full-json 返回完整报告，--format artifact-reference 返回最小引用，--field 只能增加普通字段，--exclude-field 不能隐藏安全字段。

安装

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 时默认 ~/.dsh/skills/project-change-router

--inject-hints 只为需要规则入口提示的 Codex 和 Claude Code 追加标记块，不会重写整个文件：

Codex：追加到 ~/.codex/AGENTS.md
Claude Code：追加到 ~/.claude/CLAUDE.md

这是一种“伪强制”提醒，用于让 agent 在功能级 create / modify / delete 前主动触发 skill。它不是后台守护进程，也不会绕过对话触发机制。

DeepSeek Harness 通过 skill catalog 的 name 和 description 自动向模型暴露 PCR，并支持在用户消息中用 /project-change-router 显式触发，因此不需要修改 Harness 的全局提示文档。

兼容说明：--target both 继续保持旧语义，只安装 Codex 和 Claude Code；--target deepseek 只安装 Harness；--target all 安装三端。项目级 Harness 安装可以把 .dsh 目录作为 home：

python scripts/install_skill.py --target deepseek --dsh-home <repo-root>/.dsh

Harness 原生 filesystem provider 会发现 <repo-root>/.dsh/skills/project-change-router/SKILL.md。它也兼容 <repo-root>/.agents/skills、~/.agents/skills 和自定义 skill roots，但本安装器默认写入官方 DSH_HOME 路径。

作为 DeepSeek Harness GitHub 插件安装

仓库根 package.json 声明了 dsh.bundle，其 Cordis provider 从根 SKILL.md 读取同一份 skill 内容和资源目录，不维护第二套提示词。建议固定提交 SHA 安装：

dsh plugin --profile <profile-name> add github:WeirdSky924/project-change-router-skill#<commit-sha>
dsh --profile <profile-name> --dump-config

这个 bundle 使用原生 ESM，没有 TypeScript 构建、prepare 脚本或安装期代码执行许可。项目级 .dsh/skills 和用户级 filesystem skill 的 rank 高于 bundled provider，因此可按 Harness 官方优先级覆盖插件版本。

卸载 profile 插件：

dsh plugin --profile <profile-name> remove project-change-router-skill

Harness 官方社区发现以公开 GitHub 仓库的 dsh-plugin topic 为入口；发布前应为仓库设置 dsh-plugin、deepseek-harness、agent-skills 和 coding-agent 等检索 topic。DeepSeek Harness 当前仍是 developer preview，升级 Harness preview 版本后应重新运行本仓库的 provider smoke 和安装验证。

安装器使用 staging、完整载荷递归哈希、递归 Python 编译、治理 API probe 和原子替换。只有新副本完整通过校验后才替换旧 skill；失败时会恢复旧安装，避免顶层脚本、router_support、schemas、文档或 DSH provider 出现跨版本混装。

源码 checkout 和安装目标必须是不同路径。如果当前 Git checkout 已位于任一目标的 skills/project-change-router，不要用安装器覆盖它；需要同时安装多个目标时使用独立 checkout，或只安装其他目标。--verify-only 必须读取原子安装建立的可信 manifest；没有该 manifest 的旧副本需要先原子重装一次，之后哈希验证才有来源完整性意义。

从旧版安全升级

全局 skill 和项目 bundle 是两个独立层次：

全局 skill 位于 ~/.codex/skills/project-change-router、~/.claude/skills/project-change-router 或 ~/.dsh/skills/project-change-router，保存脚本和工作流。
项目 bundle 位于 <repo-root>/project-change-router/，保存该项目长期校准的 capability、owner、path map、feedback 和 evaluation 数据。

更新全局 skill 不需要、也不应该自动重建项目 bundle。安全升级步骤如下：

在本 skill 源码仓库更新到准备使用的版本。
运行原子安装命令：

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

验证 Codex、Claude Code 和 DeepSeek Harness 安装副本的文件哈希及复用扫描 API：

python scripts/install_skill.py --target all --verify-only

对一个已经长期使用 PCR 的项目，只做只读兼容检查：

python <new-skill-root>\scripts\validate_router_bundle.py --repo <existing-repo> --format json
python <new-skill-root>\scripts\check_bundle_governance.py --repo <existing-repo> --format json
python <new-skill-root>\scripts\check_index_freshness.py --repo <existing-repo> --changed-path <known-path> --comparison-commit <trusted-base-commit> --format json
python <new-skill-root>\scripts\check_deps.py --repo <existing-repo> --comparison-commit <trusted-base-commit> --format json
python <new-skill-root>\scripts\check_public_api.py --repo <existing-repo> --comparison-commit <trusted-base-commit> --format json
python <new-skill-root>\scripts\check_structure.py --repo <existing-repo> --comparison-commit <trusted-base-commit> --format json
python <new-skill-root>\scripts\run_evaluation.py --repo <existing-repo> --format json
python <new-skill-root>\scripts\check_reuse.py --repo <existing-repo> --changed-path <known-path> --strict-completeness --format json
python <new-skill-root>\scripts\run_change_flow.py --repo <existing-repo> --request "Compatibility check only" --changed-path <known-path> --format compact-json

验证通过后直接继续使用原 bundle。不要仅仅因为升级 skill 就运行 bootstrap_router.py 或 rebuild_index.py。

兼容保证：

新版本继续读取 schema v1 bundle。
0.4 使用架构治理 API v2、typed finding / gate / change flow / authorization API v1，并保持 reuse engine API v2。
所有新版报告带统一 runtime_identity，绑定 skill version、Git commit（可用时）、安装载荷摘要、schema/API/policy/parser 版本。缓存、baseline、finding、授权与 artifact 都绑定该身份。
schema v1 的新增 evaluation 字段保持 optional；runtime 使用安全默认值且不写回旧 YAML，缺少或显式关闭 evaluation enforcement 都保持 review_only，不能授予写入权限。
schema v1 无法提供 typed finding、relevance closure 或 trusted baseline 所需精度时，0.4 输出 unknown 并让 execution gate 保持 blocked；它不会伪造精确度，也不会把新字段写回旧 bundle。
normal 只接受至少 30 个带 curated_case_ids 的真实案例、完整六类校准矩阵、明确 capability 期望以及合法 attestation；阈值只能收紧，生成案例和缺少 provenance 的旧案例始终保持 review_only。
旧 bundle 没有 reuse_scan_scope、reuse_scan_runtime 或 reuse_scan_retention 时，代码使用新默认值，但不会写回或改动 YAML。
新 fingerprint、checkpoint、canonical、diagnostic、flow artifact、baseline 和 authorization manifest 默认写到用户缓存目录，不写入目标仓库，也不要求修改目标仓库 .gitignore。
安装器不会搜索任何项目目录，不会修改已有 profile、manual feedback、evaluation case、owner 或 lifecycle 数据。
旧 bundle 中错误的仓库级 ** -> concrete capability 映射，在存在更具体映射时不会扩大 reuse 扫描范围；治理审计仍会提示修正元数据。
“旧 bundle 可读”不表示历史报告永远满足新版输出 schema；需要作为当前样例或 CI fixture 使用的报告应按当前报告契约重新生成。

只有在项目结构、owner、public entry 或 capability 边界确实发生变化时才执行 rebuild。执行前应先把直接写在生成 YAML 中的人工真值迁移到 .project-change-router.yaml，并保留 manual feedback、curated evaluation 和 lifecycle 数据。可使用旧 bundle 更新提示词让 agent 做这次受控刷新。

安装器成功输出中的：

repository_bundles_modified=0

表示本次升级没有触碰任何项目内 bundle。

安装校验

校验 skill 结构：

python <codex-home>\skills\.system\skill-creator\scripts\quick_validate.py <codex-home>\skills\project-change-router

期望输出：

Skill is valid!

本仓库完整 smoke：

python -m pytest tests/test_router_core.py -q
python scripts/bootstrap_router.py --repo . --format json
python scripts/rebuild_index.py --repo . --format json
python scripts/validate_router_bundle.py --repo . --format json
python scripts/check_bundle_governance.py --repo . --format json
python scripts/check_index_freshness.py --repo . --format json
python scripts/check_deps.py --repo . --format json
python scripts/check_public_api.py --repo . --format json
python scripts/check_structure.py --repo . --format json
python scripts/run_evaluation.py --repo . --format json
python scripts/check_reuse.py --repo . --changed-path scripts/router_support/owner_identity.py --strict-completeness --format json
python scripts/install_skill.py --target codex --codex-home <temporary-codex-home>
python scripts/install_skill.py --target codex --codex-home <temporary-codex-home> --verify-only

全新 bootstrap 会有意让 PCR 保持 review_only，直到 evaluation set 具备足量真实案例、完整校准矩阵和当前 attestation。因此在这条 smoke 流程中，run_evaluation.py 会以退出码 1 返回 status=fail、enforcement_mode=review_only 和 evaluation_cases_not_curated 原因。CI 会显式断言这一安全结果，而不是降低阈值，或把生成的种子案例冒充生产校准证据。

在目标仓库接入

首次接入目标仓库：

python <skill-root>\scripts\bootstrap_router.py --repo <repo-root> --format json

这会在目标仓库生成：

<repo-root>/project-change-router/

bundle 包含：

router-config.yaml
references/capability-catalog.yaml
references/module-map.yaml
references/ownership.yaml
references/path-to-capability-map.yaml
references/change-rules.yaml
references/exception-registry.yaml
references/evaluation-set.yaml
schemas/
reports/

bootstrap 会自动把下面这行加入目标仓库 .gitignore：

project-change-router/

目标仓库根目录可放 profile 覆盖文件：

.project-change-router.yaml
.project-change-router.yml
project-change-router.profile.yaml
project-change-router.profile.yml

这些名称按 canonical、legacy、skill fallback 的优先级选择，不会合并。同一优先级只能存在一份；.yaml 与 .yml 并存会 fail-closed，必须先确定唯一真值源。

profile 可声明：

capability 到路径的映射
ownership rules
显式 capability ownership，包括一个真实 primary owner 和不同的 reviewers
module overrides
public entries
contracts
forbidden patterns
lifecycle metadata
evaluation cases
risk rules

最小 profile 模板见 examples/profiles/README.md。

日常使用

Codex 中可以显式触发：

Use $project-change-router to resolve the correct capability entry for this change.

Claude Code 中可以显式触发：

/project-change-router resolve the correct capability entry for this change

DeepSeek Harness 中也使用 whitespace-bounded slash invocation；或者让模型根据 skill catalog 的描述主动加载：

/project-change-router resolve the correct capability entry for this 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

也可以从请求文件读取；需要单独排查路由时仍可使用兼容的 resolve_entry.py：

python scripts/run_change_flow.py --repo <repo-root> --request-file request.md --changed-path services/billing/refund.py --format artifact-reference --output flow-report.json
python scripts/resolve_entry.py --repo <repo-root> --request-file request.md --changed-path services/billing/refund.py --format json --output route-report.json

解析后执行规则：

如果 execution_gate.state=blocked：禁止产品代码写入；按 decisive finding、unknown evidence 和 required commands 补证据或进入有来源的授权流程。
如果 execution_gate.state=conditional：先执行全部 required commands，只在返回的 allowed paths 内写入；它只适用于已证明无关或不扩大的可信历史债务。
如果 execution_gate.state=pass：完成精确 must-read 后在 envelope 内推进。
action=review 只表示优先调查、补 profile 或协调，不自行阻塞；下面所有 action 也都不能覆盖 gate。
如果 action=reuse：把它当成复用倾向；优先读取 must_read_before_edit 和 required_reads，不要改核心实现。
如果 action=extend：把它当成扩展倾向；只在 allowed_write_paths 内扩展，避免绕过 public entry。
如果 action=extract：把它当成抽取倾向；先确认重复面、调用方和测试，再抽共享能力。
如果 action=new：把它当成新边界倾向；先命名隔离边界，不要在已有 capability 旁边生成第二套平行中心。

Codex / Claude Code / DeepSeek Harness 提示词

建议在无人值守计划或长期任务中加入：

Before any feature-level create, modify, delete, merge, deprecate, or migration work, invoke project-change-router and run run_change_flow.py for the target repository. Use PCR as a direction index and guardrail system, not as an automatic architecture decision engine.

Read execution_gate before action. execution_gate.state is the authoritative write decision. For blocked, do not write product code. For conditional, run every required_command and keep writes inside the bounded envelope. For pass, still obey the envelope and precise must-read targets.

Treat action, including action=review, as advisory direction only. Use recommended_next_steps, safe_next_steps, analysis_directions, profile_repair_hints, and why_not_actions for source analysis and user-confirmed decisions; never turn action into a second gate.

Never ignore veto_reasons, unknown_evidence, canonical owner/root, public entry, lifecycle findings, duplicate risk, or unresolved closure evidence. Trace them to typed findings and policy rules. Bounded or incomplete evidence cannot prove absence.

Do not create a second implementation center when an existing capability or canonical root may exist. If routing evidence is weak, repair the profile or ask for confirmation instead of guessing.

Use must_read_targets by path, symbol, and content digest. Treat directories only as inventory_targets. Run unresolved_read_targets queries and keep the target unresolved until a unique implementation is proven.

For an override, create an authorization_request and require explicit user confirmation before creating a grant. Bind it to task, paths, owner, route, pre-change snapshot, mutation envelope, runtime/policy identity, expiry, and use count. Never revive a consumed or invalidated grant.

After routed changes, execute post_change_closeout, rerun the affected flow/checks, and record feedback/evaluation cases after review, override, lifecycle change, false route, or routing correction.

Keep full diagnostics in the content-addressed artifact. In the main context retain the compact safety envelope, decisive delta, exact reads, and next command. Never hide a safety-envelope field through projection.

更完整的可复制版本见 examples/agent-workflows/unattended-plan-prompt.md。

升级 skill 后不需要自动刷新旧 bundle。只有只读兼容检查证明索引确实陈旧，或者仓库边界已经变化时，才使用 examples/agent-workflows/update-existing-router-bundle-prompt.md 做受控刷新；该流程必须保留人工 profile、反馈、评估样例和生命周期信息。

生命周期命令表

场景	命令
初次接入仓库	`python scripts/bootstrap_router.py --repo <repo-root> --format json`
仓库结构大改后	`python scripts/rebuild_index.py --repo <repo-root> --format json`
统一路由、检查与收口计划	`python scripts/run_change_flow.py --repo <repo-root> --request "<request>" --changed-path <path> --format compact-json`
修改前解析路由	`python scripts/resolve_entry.py --repo <repo-root> --request "<request>" --changed-path <path> --format json`
创建/授予/消费授权	`python scripts/manage_authorization.py --repo <request
提交前校验 bundle	`python scripts/validate_router_bundle.py --repo <repo-root> --format json`
检查重复实现	`python scripts/check_reuse.py --repo <repo-root> --changed-path <path> --format json`
检查依赖方向	`python scripts/check_deps.py --repo <repo-root> --format json`
检查 public API 边界	`python scripts/check_public_api.py --repo <repo-root> --format json`
检查中央增长、文件规模和唯一 owner	`python scripts/check_structure.py --repo <repo-root> --format json`
检查索引新鲜度	`python scripts/check_index_freshness.py --repo <repo-root> --format json`
路由治理健康检查	`python scripts/check_bundle_governance.py --repo <repo-root> --format json`
路由质量回归评估	`python scripts/run_evaluation.py --repo <repo-root> --format json`
人工反馈回写	`python scripts/sync_feedback.py --repo <repo-root> --feedback-file feedback.json --format json`

架构治理

PCR 0.4 在原有可回归 guardrail 上增加 typed findings、增量全局证据、可信 baseline 和权威 execution gate：

Python 和 TypeScript/JavaScript import graph 区分 runtime 与 type-only edge，并报告 runtime cycle、解析诊断和依赖方向。
architecture_baseline 只登记精确旧债；已登记问题可以告警，新问题或净增长失败。它不是 wildcard 豁免。
central_growth_baseline 阻止 composition root、global gateway、顶层 controller 等中央 owner 继续吸收领域实现。
forbidden_implementation_roots 阻止在 legacy、compat、generated 或非 canonical 根新增正式实现。
exclusive_source_owners 阻止 profile 明确声明的受保护实现 token 出现在 canonical owner 之外；不同标识符的 raw transport、cache/store 或 DTO 重复仍需项目级 import、identifier 或 AST 门。
generated_output_baseline 仅用于 canonical profile 迁移期的七个固定 PCR reference 产物，并绑定仓库唯一启用的 .project-change-router.yaml 或 .project-change-router.yml。规则源和每个非空 artifact provenance 都必须是该仓库对象格式的完整不可变 SHA；artifact 可以早于规则源，但必须是规则源与当前 rebuild source 的祖先，null 模式必须保持 null。固定摘要只投影掉顶层 generated_at、source_commit 和 capability catalog 中明确列出的 generator clock。path_to_capability_map.path_index[*].code_file_count 不从固定摘要中移除；它只在相同 path_pattern 且新旧值均为合法非负整数时作为 comparison-only rebuild volatile，以免仓库代码文件数量的正常变化造成假阳性。实际 pinned count 仍受摘要、canonical UTF-8 字节和行数约束，缺失、类型漂移或产物篡改仍会失败。普通 rebuild_index.py 验证成功后保留七个 tracked refs，只刷新 router-config.yaml、schemas 和 latest.json；失败时不写任何 bundle/report。evaluation attestation 会针对实际持久化的“新 config + pinned refs”重算。首次建立 pin 必须向 check_structure.py 或 rebuild_index.py 传入 --initialize-generated-output-baseline <fingerprint>；profile 文字不能自行授权。pin 启用、格式错误或尚未提交移除时，bootstrap_router.py 禁止清空正式 refs。
stable capability 必须有唯一 capability_ownership 记录、真实 primary owner、不同 reviewer、lifecycle、contract/test binding 和 evaluation 覆盖；自动生成的 owner 标签、UNKNOWN、unassigned、缺失、重复或 provisional owner 都不提供自动写入授权。
freshness 同时校验 commit、内容结构摘要、stale entries、索引路径、报告字段形状和 changed-path coverage。全局报告继续暴露所有债务；route gate 再按当前 capability 的正反向依赖闭包把 delta 分为 task_local_new、baseline_unchanged、unknown。相关变化和无法证明无关的变化继续阻塞，已证明属于其他 capability 的不变旧债不会把局部安全变更改成全仓 forbidden=["**"]。canonical config、七个 refs 与 schemas 即使被 bundle ignore_paths 命中也必须进入摘要，只有自引用的 latest.json 例外；显式 --changed-path 始终与从索引 source 到 HEAD、staged、unstaged、untracked、deleted 的真实路径取并集。
每个 route report 都带 authorization_context 和 route_fingerprint，绑定源提交、结构摘要、路由真值、changed paths、capability、action、override 条件与读写 envelope。人工反馈必须回传原始 fingerprint；输入或报告改变后授权自动失效，manifest 不能自行恢复已消费授权。
evaluation attestation 或阈值不满足时保持 review_only，不能因为 capability 命中正确就假定 action 和写入授权也可靠。

现有债务应先建立精确 baseline 来阻止新增，再由后续治理包持续降低 baseline；不能通过扩大 ignore、弱化规则或伪造 evaluation case 获得通过。字段、退出条件和 CI 组合见 references/architecture-governance.md。

flow 中的 evidence baseline 还有更严格的来源约束：首次扫描、脏工作树、bounded/incomplete 结果只能成为 candidate_snapshot 或 unknown。只有干净 commit 上的完整候选、可信 CI 快照，或用户明确接受的精确 fingerprint 才能晋升为 trusted_baseline。baseline 绑定 commit、profile、bundle、structure、indexed paths、scope、tool/runtime、policy 和 evidence digest；后续身份变化会失效，旧版本保存在 history 中而不是被覆盖。delta 会明确报告 new、expanded、unchanged、reduced 和 resolved。

Reuse 扫描运行时

check_reuse.py 现在是 capability-scoped 的有界扫描器，不是全仓语义搜索器。一次 changed-path 检查按下面的顺序执行：

changed paths
  -> path map / owner / key files / related tests / test bindings
  -> primary + dependency capability scope
  -> native fingerprint 候选召回
  -> 文件对去重与 Top-K
  -> 隔离 worker 精确比较
  -> canonical / checkpoint / diagnostic 报告

关键行为：

changed path 即使不在 modules[].path 中，只要它是 key file、index source、related test、test binding 或精确 path-map 项，也会直接进入候选集。
无法解析 capability 时返回 completion_status=incomplete，不会静默回退全仓扫描。
有具体 path mapping 时，旧 bundle 中的仓库级 ** -> concrete capability 不参与扩展范围。
精确 path-map owner 优先于宽 module owner；只有同一精确路径显式声明 shared owner 时才保留第二 owner。
dependency scope 只沿已解析的 runtime import edge 双向扩张一跳；TypeScript type-only edge 和传递依赖不会扩张扫描范围。
import parser/resolver diagnostic 会令 evidence incomplete，不会被当成干净依赖图。
test path 优先使用同 capability 的 related tests、test bindings 和 owner surface，不默认比较所有产品模块。
相同文件对只计算一次；多个 capability 命中同一重复对时合并 capability 列表和最高严重度。
超过全文比较大小限制但 fingerprint 高度相似的文件会输出 P2 duplicate-fingerprint-candidate，要求 agent 做定向源码分析；它不是精确重复结论。
每次 flow 还会独立统计 intra_capability、cross_capability 和 extended 三条通道。new、extract、lifecycle 请求必须运行 extended；shared/canonical surface 仍会触发跨 capability 检查。
每条通道独立携带 scope digest、coverage、预算、完成状态、跳过原因和 evidence digest。任一 required channel 为 bounded/incomplete 时，全局重复结论只能是 not_proven。

Fingerprint 缓存

缓存使用 Python 原生 sqlite3 和 hashlib，保存文件身份、大小、归一化长度、token sketch、内容摘要和算法版本，不保存完整归一化源码。第二次扫描可直接复用未变化 owner 文件的 fingerprint，只对 Top-K 精确候选读取全文。

默认运行时目录不在项目仓库中：

Windows：%LOCALAPPDATA%\project-change-router\repositories\<repo-key>\
Linux/macOS：$XDG_CACHE_HOME/project-change-router/repositories/<repo-key>/，未设置时使用 ~/.cache/...

缓存模式：auto、read-only、off、rebuild。可通过 --cache-mode 或 profile/change-rules 配置。

Timeout 与取消

CLI 在隔离子进程中运行扫描：

soft timeout 停止派发新比较并写 checkpoint。
hard timeout 终止仍卡在单次全文相似度计算中的 worker。
Ctrl+C 走相同的取消、终止和 canonical 报告收口流程。
hard timeout 至少比 soft timeout 多一秒，确保有收口窗口。

命令行覆盖优先级高于 profile/change-rules：

python scripts/check_reuse.py --repo <repo-root> --changed-path <path> `
  --timeout-seconds 60 --hard-timeout-seconds 75 `
  --cache-mode auto --diagnostics auto --format json

数量预算仍可使用：--max-candidate-files、--max-owner-files、--max-comparisons、--max-file-bytes、--top-k-owner-files。

报告分级

canonical：agent/CI 使用的最终机器契约；完成、受预算限制、超时、取消和错误都会生成。
checkpoint：可恢复的过程状态；完整完成后删除，非完整扫描短期保留，不能作为最终结论。
diagnostic：scope、缓存命中、阶段耗时和淘汰原因；auto 只为慢扫描或非完整扫描保留。

必须同时读取：

result_status      = pass | warn | fail
completion_status  = complete | bounded | incomplete | timeout | cancelled | error
evidence_complete  = true | false

典型含义：

场景	result_status	completion_status
已完成目标 scope，未发现阻断	`pass`	`complete`
已完成目标 scope，发现 P1 重复	`fail`	`complete`
没有 P0/P1，但达到预算或大文件限制	`warn`	`bounded`
changed path 无法完整归属	`warn`	`incomplete`
worker 超过截止时间	`warn`	`timeout`
取消前已经发现 P1	`fail`	`cancelled`

只有 completion_status=complete 且 evidence_complete=true 才能说明“已完成目标 capability scope 的重复检查”。这仍不代表扫描了无关 capability，也不替代 agent 对候选文件的源码分析。

changed-path 报告身份只使用路由真值、目标内容和实际参与扫描的 owner/candidate source_fingerprint_digest。无关 worktree 文件不会破坏 canonical report 去重，但任何参与判断的源文件变化都会使摘要失效。

自动保留与清理

canonical 结果按输入、scope、证据、预算和 findings 做语义去重；P0/P1 报告自动 pin。默认保留 90 天/500 个 canonical、7 天 checkpoint、3 天/200 个 diagnostic，fingerprint 最多 50000 条，单仓运行时上限 512 MiB。

清理只删除 SQLite manifest 登记且位于解析后 runtime root 内的文件，不会 glob 删除仓库内容。可单独运行：

python scripts/check_reuse.py --repo <repo-root> --cleanup-only --format json

默认退出码兼容旧自动化：无 P0/P1 时仍为 0；P0/P1 为 1；timeout/error 为 2；取消为 130。使用 --strict-completeness 时，bounded 和 incomplete 也返回 2。自动化应优先读取 JSON 字段，不要只看退出码。

完整配置与行为契约见 references/reuse-scan-runtime.md。

治理审计

check_bundle_governance.py 用于检查 bundle 是否只是“能跑”，还是具备长期路由治理质量。

它会检查：

profile 声明的 capability 是否进入 catalog。
change rules 是否引用未知 capability。
generated-only capability 是否过多。
path-to-capability map 是否存在未覆盖模块或多能力冲突路径。
ownership rules 是否过宽或过细。
contracts 是否缺失、过短或过长。
大能力的 forbidden patterns 密度是否过低。
dependency priority 是否覆盖所有 capability。
evaluation set 是否覆盖 profile-backed capability。
deprecated capability 是否具备 superseded_by、deprecation_date、migration_note。
stable capability 是否具备非 provisional owner、reviewer、lifecycle、正例与边界 evaluation 覆盖。

默认退出码：

P0：失败。
P1：默认 warn，--strict 下失败。
P2：维护建议，不阻塞。

人工反馈与持续校准

有界授权 manifest

authorization_request 只是对当前 task/path/owner/route/pre-change snapshot/mutation envelope 的请求草案，不能创造权限。用户明确确认后，使用 manage_authorization.py grant 记录 grant；默认单次使用、24 小时过期，可显式授权最多 100 次且最长 30 天。每次状态变化进入摘要链 audit event，任何上下文、runtime/policy 或 mutation 变化都会失效；已 consumed、expired、invalidated 或 rejected 的 grant 不能因输入相同而恢复。

python scripts/manage_authorization.py --repo <repo-root> request --route-report <full-flow-report.json>
python scripts/manage_authorization.py --repo <repo-root> grant --request-id <request-id> --authorization-source user --confirmation "<exact confirmation>"
python scripts/manage_authorization.py --repo <repo-root> consume --grant-id <grant-id> --route-report <current-full-flow-report.json>
python scripts/manage_authorization.py --repo <repo-root> inspect --grant-id <grant-id>

Continuous router calibration loop

当发生人工确认、override、误判、能力合并、废弃或 profile 修正时，应记录反馈：

python scripts/sync_feedback.py --repo <repo-root> --feedback-file feedback.json --format json

示例：

{
  "decision_id": "route-...",
  "final_action": "review",
  "final_capability": "billing",
  "confirmed_public_entry": "services/billing/__init__.py",
  "confirmed_owner": "billing-team",
  "profile_update_recommended": true,
  "notes": "Human-confirmed correction"
}

推荐把真实误判沉淀为 evaluation case。不要只修规则而不加回归样例。

可复制样例：

真实仓校准参考

匿名真实结构参考见：

这些样例用于说明大型全栈项目如何把真实模块、owner、public entry、route case 和反馈沉淀为可复用治理数据。

示例文件

Agent 工作流示例：

Profile 模板：

反馈与评估样例：

Bundle 样例：

输出样例：

参考文档：

脚本列表

scripts/install_skill.py
scripts/bootstrap_router.py
scripts/resolve_entry.py
scripts/rebuild_index.py
scripts/check_reuse.py
scripts/reuse_runtime.py
scripts/check_deps.py
scripts/check_public_api.py
scripts/check_structure.py
scripts/check_index_freshness.py
scripts/check_bundle_governance.py
scripts/run_evaluation.py
scripts/run_change_flow.py
scripts/manage_authorization.py
scripts/sync_feedback.py
scripts/validate_router_bundle.py

DeepSeek Harness 接入文件：

package.json
integrations/deepseek-harness/index.js
integrations/deepseek-harness/cordis.patch.yml

CI

GitHub Actions workflow 位于 .github/workflows/ci.yml，会执行：

安装依赖。
校验 skill 结构。
校验 DeepSeek Harness provider 语法和注册/加载 smoke。
用 npm pack --dry-run 校验 DSH 发布包不包含 __pycache__、.pyc 或其他本地运行时产物。
运行单元测试。
bootstrap 自仓库 bundle。
validate bundle。
governance audit。
freshness check。
dependency direction、runtime cycle 与 public API check。
central growth、800/1200 文件规模、forbidden root 与 exclusive owner structure check。
route evaluation。
capability-scoped reuse scan、隔离 worker 和严格完整性检查。
typed finding schema、execution gate replay、可信 baseline、增量缓存、三通道 reuse、compact flow 与 authorization 状态机回归。
临时目录中的原子安装与 --verify-only 完整载荷校验。

边界与风险

需要明确：

首次 bootstrap 只是 first pass。
没有 profile 时，结果会偏保守。
generated-only evaluation 只能说明系统自洽，不代表架构成熟。
capability 命中正确不代表 action、secondary contract 或写入授权可靠；evaluation 未达阈值时仍为 review_only。
只有 execution_gate.state 决定当前写入状态；action=review、review_required 和 confidence 都不是独立门禁。
decision_confidence=high 只说明 action/decision basis 稳定，不提供写权限。
action 是建议动作，不是最终工程命令；execution gate、安全信封、typed findings、owner、canonical root 和生命周期约束优先级更高。
check_reuse 的 result_status=pass 只有在 completion_status=complete 且 evidence_complete=true 时才表示目标 scope 已完成；bounded、timeout 和 incomplete 只能作为定向分析证据。
生命周期操作，例如 delete、merge、deprecate、replace、migrate，会产生强制 lifecycle evidence/gate；review 只是建议的调查方向。
这个 skill 给方向、证据和约束，最终实现方案仍应来自真实代码分析、测试和用户确认。

许可证

见 LICENSE。

项目变更路由

Project Change Router Skill

核心理念

两层使用模型

能力范围

路由动作

仓库阶段策略

一体化路由报告

0.4 执行门禁与证据模型

安装

作为 DeepSeek Harness GitHub 插件安装

从旧版安全升级

安装校验

在目标仓库接入

日常使用

Codex / Claude Code / DeepSeek Harness 提示词

生命周期命令表

架构治理

Reuse 扫描运行时

Fingerprint 缓存

Timeout 与取消

报告分级

自动保留与清理

治理审计

人工反馈与持续校准

有界授权 manifest

真实仓校准参考

示例文件

脚本列表

CI

边界与风险

许可证

セキュリティとインストールエビデンス

项目变更路由

Project Change Router Skill

核心理念

两层使用模型

能力范围

路由动作

仓库阶段策略

一体化路由报告

0.4 执行门禁与证据模型

安装

作为 DeepSeek Harness GitHub 插件安装

从旧版安全升级

安装校验

在目标仓库接入

日常使用

Codex / Claude Code / DeepSeek Harness 提示词

生命周期命令表

架构治理

Reuse 扫描运行时

Fingerprint 缓存

Timeout 与取消

报告分级

自动保留与清理

治理审计

人工反馈与持续校准

有界授权 manifest

真实仓校准参考

示例文件

脚本列表

CI

边界与风险

许可证

セキュリティとインストールエビデンス

関連プラグイン

Aegis

原生能力指南

工具故障注入

Graph Memory