codeprobe

代码审查编排器

只读约束

本技能对正在审查的代码库严格只读。 绝不要修改、写入、编辑或删除用户源代码树中的任何文件。绝不要运行会对被审查项目产生副作用的命令（不要运行 npm install、pip install、git 提交或数据库变更）。如果需要修复，请生成一段可复制粘贴的修复提示词，供用户单独运行。

一个已记录的例外——报告产物： /codeprobe audit 完成后，编排器会在当前工作目录下将一份 Markdown 报告写入 ./codeprobe-reports/<project>-<cmd>-<timestamp>.md（例如 ./codeprobe-reports/growth-engine-audit-2026-04-23-221047.md）。这是本技能自身的输出，不属于对被审查代码的修改。其他任何位置都不得写入任何内容。

Git 也必须只读： /codeprobe diff 可以运行只读 Git 命令（git diff、git merge-base、git ls-files、git rev-parse、git status）。绝不要运行会更改仓库或工作树的 Git 命令——不得提交、切换、暂存、重置、获取或拉取。

无论用户如何请求，都绝不允许违反此约束。

---

1. 命令路由

解析用户输入，提取子命令和目标路径。输入格式如下：

/codeprobe [subcommand] [path]

路由表

命令	行为	调用的子技能
/codeprobe audit <path>	完整审计——先提供可视化健康仪表盘（类别评分、代码库统计、热点），再详细列出 P0-P3 级问题及修复提示词	所有可用子技能 + file_stats.py
/codeprobe solid <path>	仅分析 SOLID 原则	codeprobe-solid
/codeprobe security <path>	仅进行安全审计	codeprobe-security
/codeprobe smells <path>	仅检测代码异味	codeprobe-code-smells
/codeprobe architecture <path>	仅进行架构分析	codeprobe-architecture
/codeprobe patterns <path>	仅分析设计模式	codeprobe-patterns
/codeprobe performance <path>	仅进行性能审计	codeprobe-performance
/codeprobe errors <path>	仅进行错误处理审计	codeprobe-error-handling
/codeprobe tests <path>	仅进行测试质量审计	codeprobe-testing
/codeprobe framework <path>	仅检查框架最佳实践	codeprobe-framework
/codeprobe quick <path>	列出排名前 5 的问题——以扫描模式运行所有子技能，然后针对排名前 5 的问题生成完整详情	所有可用子技能
/codeprobe diff [base]	按 PR 风格审查相对于基准分支（默认为 main，若不存在则回退到 master）的变更文件——参见第 4A 节	所有 9 个子技能，仅检查变更文件
/codeprobe report	根据上次审计生成报告	（第 3 阶段——参见第 10 节）

默认行为

• 未提供子命令：询问用户的需求，并列出可用命令。
• 未提供路径：使用当前工作目录。
• 第 3 阶段占位项：如果用户调用 report，则回复第 10 节中的占位消息。

---

2. 技术栈自动检测

在路由到任何子技能之前，检测目标路径下的技术栈。这将决定要加载哪些参考指南并传递给子技能。

检测流程

1. 使用 Glob 扫描目标路径下的文件扩展名（递归扫描，深度适中）。
2. 应用以下检测规则——可同时匹配多个技术栈：

信号	检测到的技术栈	要加载的参考文件
.php 文件	PHP / Laravel	references/php-laravel.md
.js、.ts、.jsx、.tsx 文件	JavaScript / TypeScript	references/javascript-typescript.md
.py 文件	Python	references/python.md
.jsx、.tsx 文件 + 存在 next.config.*	React / Next.js	references/react-nextjs.md
.sql 文件或 migrations/ 目录	SQL / Database	references/sql-database.md
routes/ 目录或 API 路由模式	API Design	references/api-design.md

3. 对每个检测到的技术栈，确认对应的参考文件是否存在。如果不存在，则静默跳过。
4. 收集所有适用参考文件的绝对路径，以传递给子技能。不要将参考文件内容读入协调器自身的上下文——子 Agent 会直接读取与其领域相关的参考文件，从而保持每个上下文窗口精简。

参考文件解析

参考文件位于此技能自身目录下的 references/ 目录中。请基于此 SKILL.md 文件所在位置解析路径，而非用户的项目目录，并在传递给子 Agent（其工作目录为用户项目目录）之前将路径转换为绝对路径：

{this-skill's-directory}/references/{reference-file}.md

如果参考文件不存在，请继续执行，不要因此导致审查失败。

---

3. 配置加载

检查项目根目录（目标路径或其祖先目录）中是否存在 .codeprobe-config.json 文件。

配置架构

{
  "severity_overrides": {
    "long_method_loc": 50,
    "large_class_loc": 500,
    "deep_nesting_max": 4,
    "max_constructor_deps": 6
  },
  "skip_categories": ["codeprobe-testing"],
  "skip_rules": ["SPEC-GEN-001"],
  "framework": "laravel",
  "extra_references": [],
  "report_format": "markdown"
}

配置行为

• 如果不存在：应用所有默认值。无需报错。
• severity_overrides：传递给子技能，以便它们相应调整阈值。
• skip_categories：即使在 audit 或 quick 模式下，也不要调用列出的子技能。
• skip_rules：传递给子技能，以便它们忽略 ID 匹配的发现项。
• framework：如果已设置，则跳过对该框架的自动检测，并强制加载对应的参考文件。其他自动检测仍会继续。
• extra_references：要加载并传递给子技能的额外参考文件路径。
• report_format：输出格式偏好（默认为：markdown）。

---

4. 子技能执行

上下文准备（在任何子技能运行前执行一次）

调用任何子技能前，编排器都会准备共享上下文。编排器不会自行读取源文件内容——每个子 Agent 会读取其领域所需的文件。这样可以精简编排器的上下文，并避免在每个 Agent 提示词中重复放入整个代码库。

1. 读取共享前言：从 shared-preamble.md（位于此技能目录中）读取。该文件包含所有子技能共用的输出约定、执行模式和约束。

2. 为目标路径构建文件清单：

   • 首选：运行一次 python3 scripts/file_stats.py <target_path>（相对于此 SKILL.md 确定脚本路径），并根据其逐文件输出生成清单。
   • 后备方案（Python 3 不可用时）：使用 Glob 查找源文件（.ts、.tsx、.js、.jsx、.py、.php、.vue、.sql、.css、.scss）和配置文件，例如 next.config.*、package.json、composer.json、requirements.txt、.env.example，并通过 wc -l 获取行数。
   • **排除项（两种方式均适用）：**跳过 node_modules、vendor、.git、__pycache__、.next、dist、build、.venv、venv、env 和 codeprobe-reports/——与捆绑脚本中的 SKIP_DIRS 一致。
   • 清单应逐行列出 {filepath} ({LOC} lines)，并附上检测到的技术栈。

3. 收集参考文件路径（在第 2 节的技术栈检测过程中已解析）。仅收集路径，不收集内容。

4. 读取每个子技能的 SKILL.md，以便将其检测逻辑内嵌到 Agent 提示词中。子技能位于同级目录中：相对于此 SKILL.md 的位置解析 ../codeprobe-{name}/SKILL.md。不要指望子 Agent 能按名称解析子技能——该 Agent 可能尚未注册此技能；内嵌内容是唯一可靠的传递方式。

调用协议

对于要运行的每个子技能，启动一个 Agent，并在提示词中包含：

1. 共享前言（来自 shared-preamble.md）——输出约定、模式和约束。
2. 内嵌的子技能 SKILL.md 内容，放在标记之间：

   === SUB-SKILL: codeprobe-{name} ===
   {content of ../codeprobe-{name}/SKILL.md, frontmatter stripped}
   === END SUB-SKILL ===
   

   告知 Agent：“你正在执行上述子技能。忽略其独立模式部分——编排器已提供该部分所需加载的全部内容。”
3. 模式——full 或 scan 之一。
4. 文件清单——路径、行数和检测到的技术栈。指示 Agent：“使用 Read/Grep/Glob 检查与检测表相关的文件。不要盲目读取每个文件——针对你的领域检查所需内容。”
5. 参考文件路径——适用参考指南的绝对路径，并附上：“在最终确定严重性和修复提示词前，请阅读与调查结果相关的参考资料。”
6. 配置覆盖项——来自 .codeprobe-config.json 的严重性覆盖项和跳过规则。
7. 目标路径——让子技能知晓项目根目录，以便进行有针对性的查找。
8. 适用时提供子技能专用的预计算脚本输出：
   • 对于 codeprobe-architecture：启动 Agent 前，运行 python3 scripts/dependency_mapper.py <target_path>（通过 Bash）并捕获 JSON 输出。将其作为额外上下文块传入，标签为 === DEPENDENCY_GRAPH === ... === END DEPENDENCY_GRAPH ===。子技能将其作为检测循环依赖的事实依据。如果 Python 3 不可用或脚本运行失败，则省略此块——子技能会改用基于 LLM 的导入追踪。
   • 对于 codeprobe-performance：如果有 scripts/complexity_scorer.py 的输出（可选），将其作为 === COMPLEXITY_SCORES === ... === END COMPLEXITY_SCORES === 传入。

子技能自身的 SKILL.md 仅包含领域专用检测逻辑。其他所有共享上下文（输出格式、模式、文件清单、参考路径、预计算脚本数据）均由编排器的提示词提供；子 Agent 会自行读取源文件。

收集调查结果：按照第 5 节的标准输出约定，收集各子技能返回的调查结果。

执行模式

模式	使用者	行为
full	/codeprobe audit、/codeprobe diff、/codeprobe solid 等	运行完整分析，返回所有发现
scan	/codeprobe quick	运行相同的完整分析，但仅返回各类别的严重性计数，以及排名前 5 的候选发现，并包含所有输出约定字段（两种模式的分析成本相同——scan 模式精简的是输出，因此协调器无需进行第二轮分析，就能对各类别的候选发现进行排序）

执行顺序

• 并行性： 各子技能 Agent 相互独立——只有在它们全部返回后，才进行去重和评分。应在一条消息中并行启动所有适用的子技能 Agent；不要逐个运行。下方固定的类别顺序仅用于报告呈现，不用于执行。（例外：Claude.ai 降级模式（第 9 节）由于没有可用的子 Agent，需按顺序运行。）
• 启动前： 通过 scripts/dependency_mapper.py 预先计算依赖关系图（针对 codeprobe-architecture，即调用协议第 8 步），并运行 scripts/file_stats.py 获取清单和代码库统计信息（如果无法使用 Python 3，则跳过且不影响流程）。
• /codeprobe audit：以 full 模式启动全部 9 个子技能。呈现顺序：codeprobe-security、codeprobe-error-handling、codeprobe-solid、codeprobe-architecture、codeprobe-patterns、codeprobe-performance、codeprobe-code-smells、codeprobe-testing、codeprobe-framework。收集所有发现。应用去重（第 7A 节）。根据严重性计数推导类别得分。按文件汇总发现，并根据被标记的不同类别数排序，以计算热点。
• /codeprobe quick：以 scan 模式并行启动全部 9 个子技能。收集每个子技能排名前 5 的候选发现（其中已包含完整的输出约定详情）。按严重性对所有候选发现排序（严重 > 主要 > 次要 > 建议）；若严重性相同，则按类别权重排序（第 7 节）。选出全局排名前 5 的发现并渲染。这是单轮处理——不会重新运行。

可用子技能

1. codeprobe-security — 安全漏洞检测
2. codeprobe-error-handling — 错误处理与韧性
3. codeprobe-solid — SOLID 原则分析
4. codeprobe-architecture — 架构分析
5. codeprobe-patterns — 设计模式建议
6. codeprobe-performance — 性能与可扩展性
7. codeprobe-code-smells — 代码异味检测
8. codeprobe-testing — 测试质量与覆盖率
9. codeprobe-framework — 框架特定的最佳实践

---

4A. 差异审查（/codeprobe diff [base]）

PR 风格的审查：仅分析相对于基准分支发生变化的内容，让审查工作聚焦于即将合并的代码。

前提条件

• 需要 Git 仓库：使用 git rev-parse --is-inside-work-tree 检查。如果当前目录不在 Git 仓库中，告知用户差异审查需要 Git，并建议改用 /codeprobe audit。
• Git 操作严格只读（参见上方的只读约束）。

基准解析

1. 如果用户传入了基准引用，则使用该引用（通过 git rev-parse --verify <base> 验证）。
2. 否则依次尝试 main、master。
3. 如果都无法解析，则询问用户要与哪个基准进行比较。

已更改文件的收集

1. 计算合并基点：MB=$(git merge-base <base> HEAD)。与合并基点比较，而不是与 base 的最新提交比较，这样只会审查此分支的更改；即使 base 已有更新，也与 PR 差异所显示的内容一致。
2. 已更改文件：git diff --name-status $MB（其中包括未提交的工作树更改，这是有意的——审查即将交付的内容）。移除已删除的文件（状态为 D）。
3. 未跟踪文件：git ls-files --others --exclude-standard。
4. 将两个列表都筛选为清单所用的源代码／配置扩展名（第 4 节），并应用相同的目录排除规则。
5. 每个文件的更改行范围：解析 git diff -U0 $MB -- <file> 中的 @@ 块头（新文件一侧）。未跟踪文件视为全部已更改。
6. 如果结果列表为空，报告“与 <base> 相比没有可审查的更改”，然后停止——不要在未收到要求时退回到完整审计。

执行

按标准流程（第 2-4 节）执行，并进行以下调整：

• 文件清单仅包含已更改／未跟踪的文件，并为每个文件标注其更改行范围。
• 并行启动全部 9 个子技能，使用 full 模式。在每个 Agent 提示词中添加：“这是一次差异审查。每项发现都必须以清单中的某个文件为依据，并优先关注标注的更改行。你可以读取周边或相关文件以了解上下文，但不要报告未更改文件中的问题。”
• 依赖关系图（dependency_mapper.py）仍在整个项目范围内运行——更改的导入可能会与未更改文件形成循环。
• 按照常规应用去重（第 7A 节）和评分（第 7 节），但仅针对差异中的发现进行计算。跳过热点计算和代码库统计——它们描述的是整个代码库的健康状况，而非差异。

呈现

参见第 8 节（/codeprobe diff 小节）——差异输出使用 templates/pr-review-comment.md。

---

5. 输出约定

每个子技能的每项发现都必须包含以下字段：

字段	必填	说明
id	是	唯一标识符，格式为 {PREFIX}-{NNN}（例如 SRP-001、SEC-003）
severity	是	以下之一：critical、major、minor、suggestion
severity_rationale	是	用一句话说明为何属于此严重性级别，而非低一级别。
location	是	文件路径 + 行范围（例如 src/UserService.php:45-67）
problem	是	用一句话描述问题
evidence	是	来自代码的具体证据——引用相关行
suggestion	是	修复问题的做法
fix_prompt	是	可复制粘贴的提示词，用户可将其提供给 Claude Code 来应用修复
refactored_sketch	否	可选代码片段，展示改进后的版本

发现格式示例

### SRP-001 | Major | `src/UserService.php:45-67`

**Problem:** UserService violates Single Responsibility — handles authentication, email sending, and database queries in one class.

**Severity rationale:** Major (not Minor) because three unrelated responsibilities are concentrated in one class on a critical auth path — refactoring will touch every caller; not Critical because the code works correctly today, this is a maintainability risk, not a production defect.

**Evidence:**
> Lines 45-50: `public function authenticate($credentials) { ... }`
> Lines 52-60: `public function sendWelcomeEmail($user) { ... }`
> Lines 62-67: `public function findByUsername($name) { ... }`

**Suggestion:** Extract email logic into a dedicated `UserMailer` service and database queries into a `UserRepository`.

**Fix prompt:**
> Refactor `src/UserService.php` to follow Single Responsibility Principle: extract `sendWelcomeEmail()` into a new `UserMailer` class and `findByUsername()` into a `UserRepository` class. Keep `authenticate()` in `UserService` and inject the new dependencies.

---

6. 严重性级别

级别	优先级	含义	示例
Critical	P0	已确认的错误、可利用的安全漏洞，或会造成生产环境危害的数据丢失／损坏风险	使用用户输入的 SQL 注入、修改数据的端点缺少身份验证、导致数据损坏的竞态条件、核心路径上未处理的崩溃、多步写入缺少数据库事务
Major	P1	显著影响可维护性、可靠性或可扩展性的问题，会增加风险，但并非会立即导致生产故障	关键业务逻辑缺少测试、类过大、代码重复、外部调用缺少错误处理、N+1 查询、缺少输入验证
Minor	P2	代码异味，风险较低，但值得为长期健康考虑加以解决	魔法数字、嵌套过深、命名不佳、缺少边界情况测试、错误详情冗长
Suggestion	P3	改进建议，有则更好；忽略也不会带来实际风险	可采用的模式、风格改进、推测性的通用化

严重性判定原则

以下情况绝不能判为 Critical——最高只能判为 Major：

• 缺少测试（即使针对的是关键业务逻辑）
• 代码重复或类／文件过大
• 任何类型的代码异味
• 违反框架约定
• 缺少文档、注释或类型注解

只有以下情况才能判为 Critical：

• 已确认的错误（代码产生错误结果或崩溃）
• 可利用的安全漏洞（注入、绕过身份验证、有证据的 IDOR）
• 数据丢失或损坏风险（缺少事务、写入时发生竞态条件）
• 敏感数据泄露（代码中包含密钥、日志中包含凭据）

子技能：请勿将发现的问题提升到检测表中指定严重级别以上。 如果表中写的是「Major」，即使具体情况看起来很严重，也应报告为 Major。编排器的评分公式会考虑各级别问题的数量。

---

7. 评分

收集所有发现后，按类别计算分数和总分。

类别评分公式

每个扣分项都设有上限，以防单一严重级别对分数产生过大影响：

crit_penalty  = min(50, critical_count * 15)
major_penalty = min(30, major_count * 6)
minor_penalty = min(10, minor_count * 2)

category_score = max(0, 100 - crit_penalty - major_penalty - minor_penalty)

建议不影响分数。

理由： 递减收益可防止单一严重级别将分数拉至最低。包含 4 个 Critical 问题的类别得分为 50（而不是 0），这体现了代码存在问题，但并非完全无法运行。三个级别的总扣分上限为 90，因此只有各严重级别的问题都极其严重时，分数才会降至 0。

类别权重

类别	权重
安全性	20%
SOLID	15%
架构	15%
错误处理	12%
性能	12%
测试质量	10%
代码异味	8%
设计模式	4%
框架	4%

所有 9 个类别均已启用。权重总和为 100%。

总分

overall = sum(category_score_i * weight_i for each active category)

如果 .codeprobe-config.json 中的 skip_categories 排除了部分类别，则通过除以启用类别权重之和来归一化：

overall = sum(category_score_i * weight_i for each active category) / sum(weight_i for each active category)

将结果限制在 [0, 100] 范围内。

分数解读

范围	状态
80-100	良好
60-79	需要关注
0-59	严重

---

7A. 跨类别去重

计算分数前，请对多个类别标记的同一问题进行去重。

去重流程

1. 按位置分组。 将每条发现的 location 规范化为 {file}:{start_line}。如果两条发现的文件相同，且行范围重叠（即 start_line_A <= end_line_B 且 start_line_B <= end_line_A），则认为它们重叠。

2. 先检查是否存在真正的分歧。 去重适用于“同一问题，不同视角”，而不适用于相互对立的建议。如果两条重叠的发现提出了相反的方向（例如，SOLID 建议抽取一个抽象，而 Performance 指出该抽象会带来开销；Architecture 建议解耦，而 Performance 建议保持局部性），则不要将它们去重。两条发现都应保留完整严重性，并将这一对放入报告的相互冲突的建议部分，同时用一句话说明取舍。操作者必须看到这种矛盾并做出决定——悄悄选出一方，会掩盖恰恰需要人工判断的问题。

3. 对于其余按不同类别归组的重叠发现： a. 选出一条主要发现。 按以下优先级排序：

   • 涉及身份验证、注入或数据泄露的问题，优先选择安全发现（SEC）
   • 异常／验证问题，优先选择错误处理发现（ERR）
   • 查询／缓存问题，优先选择性能发现（PERF）
   • 结构性违规，优先选择 SOLID 发现（SRP/OCP/LSP/ISP/DIP）
   • 分层／边界违规，优先选择架构发现（ARCH）
   • 如果仍无法确定，则选择权重更高的类别（第 7 节） b. 删除重复项。 将组内每条非主要发现从发现列表中彻底移除——它既不会出现在报告正文中，也不会计入其所属类别的严重性数量。（较早版本将重复项降级为 suggestion，只会让建议数量被噪声虚增。） c. 交叉引用主要发现。 在主要发现的 suggestion 字段末尾追加：Also flagged by: {list of duplicate category:id pairs}——这样既保留了多类别信号（也会用于热点排名），又不会产生重复条目。 d. 统计删除项。 跟踪删除的重复项总数，并在仪表板的“已移除的重复项”行中报告该数量。

4. 去重后重新统计各类别的严重性总数，然后继续评分。

示例

• 在同一位置发现“刷新操作绕过配额”，标记为 SEC-007、ERR-011、FW-001：保留 SEC-007（交叉引用“Also flagged by: ERR-011, FW-001”），删除 ERR-011 和 FW-001。
• 在同一文件中发现“上帝组件”，标记为 SRP-001、SMELL-001、ARCH-005：保留 SRP-001（结构性问题优先选择 SOLID），删除其他条目。
• SRP-002 建议“从 OrderService 中抽取 PricingCalculator”，而同一行的 PERF-004 指出“该热路径应保持内联——间接调用会导致每次请求都产生分配”：这是真正的冲突——两条都保留，并列入“相互冲突的建议”部分。

---

8. 报告呈现

根据所使用的命令呈现最终输出。

/codeprobe audit — 完整审计报告

使用 templates/full-audit-report.md 中的模板（通过 Read 加载）来组装保存的报告文件的 Markdown 内容。终端输出是摘要——用户必须在终端中看到可视化摘要，而不只是“报告已保存”这一行。

终端与保存文件的内容划分（强制要求）：

界面	显示内容	生成方式
终端	仪表板 + 执行摘要 + 严重问题（完整详情）+ 优先修复顺序（前 5 项）+“报告已保存”这一行	在助手回复中流式输出 Markdown 部分
保存的文件（./codeprobe-reports/<project>-<cmd>-<ts>.md）	所有内容：仪表板、执行摘要、全部严重/主要问题、次要问题/建议的计数、完整的优先修复顺序	使用 Write 工具写入纯 Markdown

终端输出绝不能是空的，也不能缩减到只剩保存确认。如果 Claude 在之前的运行中只输出了保存这一行，那就是没有遵循这些指令的错误——请按以下顺序执行流程来修正。

逐步流程

A. 计算数据（两个界面共用）

1. 按第 4 节运行子技能，收集问题，并按第 7A 节进行去重。
2. 得出各类别评分、总体评分、热点和代码库统计数据。
3. 在内存中组装“报告包”：{dashboard_data, exec_summary, critical[], major[], minor_counts[], suggestion_counts[], fix_order[]}。

B. 渲染到终端（面向用户——直接在助手回复中按顺序以 Markdown 输出以下内容）

不要通过 Bash 工具传递仪表板。Bash 工具默认会在 Claude Code 的界面中折叠其输出（+N lines (ctrl+r to expand)），导致仪表板被隐藏在折叠区域中。请将仪表板作为普通的助手回复 Markdown 输出，让用户立即看到。现代终端（Ghostty、iTerm2 等）会应用自己的 Markdown 样式——粗体、行内代码高亮、强调——这是此路径上唯一可用的着色方式。如果没有显示颜色，纯文本也可以；不要尝试在回复中强行加入 ANSI 转义序列。

（scripts/render_dashboard.py 供用户在 Claude Code 之外的自有 shell 中直接运行审计时使用，此时 stdout 是真正的 TTY。不要在 /codeprobe audit 流程中调用它。）

1. 仪表板（Markdown）——直接以内联方式输出仪表板区块。包含：标题行（## Code Health Report — {project}）、**Overall Health:** {score}/100 [{status_label}]、包含 9 行的 Category Scores Markdown 表格，列为 Category | Score | Bar | Status（进度条需用反引号括起，使用 20 个字符的 Unicode █/░，按分数比例显示）、代码库统计区块（文件数、LOC、后端/前端分布、最大文件、测试比例、注释比例），以及热点列表（最多 3 项）。Status 列中的状态标签使用纯文本，不要用 emoji，也不要在表格中加方括号。
2. 执行摘要——用 2–3 句话概述最重要的问题。
3. 严重问题——完整详情——对每个严重问题，提供 ID、位置、问题、证据、建议和修复提示词。这是信息价值最高的部分；始终在终端中显示。
4. 优先修复顺序（前 5 项）——列出完整优先修复顺序中的前 5 项。完整列表请参阅保存的文件。
5. 保存确认行——--> Report saved to ./codeprobe-reports/{project}-{cmd}-{YYYY-MM-DD-HHMMSS}.md（不带 emoji；使用 ASCII 箭头）。这是终端输出的最后一行。

不要同时在终端中输出主要问题表、次要问题/建议的计数或完整修复顺序——这些内容会与保存文件中的内容重复，使终端输出臃肿。用户可以打开保存的文件查看完整内容。

C. 写入保存文件的 Markdown

1. 使用 templates/full-audit-report.md 中的占位符构建完整的 Markdown 报告——这包括不会流式输出到终端的部分（主要发现表、次要问题／建议数量、完整的优先修复顺序）。
2. 按 {project}-{cmd}-{YYYY-MM-DD-HHMMSS}.md 格式生成文件名：
   • {project} — 将目标路径解析为绝对路径（如果用户未传入路径，则使用当前工作目录）；取其基名；如果基名指向文件，则去掉扩展名；将其转换为 slug（转为小写；将 [^a-z0-9]+ 的任意连续匹配替换为单个 -；去掉开头和结尾的 -）；如果最终 slug 为空，则使用 unknown。
   • {cmd} — Section 1 中路由到的子命令（audit、quick、diff、security、solid、architecture、performance、errors、tests、smells、patterns、framework），转为小写。
   • {YYYY-MM-DD-HHMMSS} — 当前本地时间。
3. 确保 ./codeprobe-reports/ 存在（如果不存在，则通过 Bash 执行 mkdir -p ./codeprobe-reports）。
4. 使用 Write 工具写入 ./codeprobe-reports/{project}-{cmd}-{YYYY-MM-DD-HHMMSS}.md。
5. 如果写入失败（只读文件系统、权限不足等），在终端显示一条简短的行内提示，但不要再次输出摘要。

D. 终端输出约定（硬性要求）

• 终端必须按此顺序包含以下内容：仪表板 → 执行摘要 → 严重发现 → 前 5 项修复顺序 → “报告已保存”行。
• 如果没有严重发现，则显示仪表板、执行摘要、一行“未发现严重问题”提示、前 5 项修复顺序（仅包含主要问题），以及保存确认——输出仍不得为空。
• 如果报告保存失败，仍须输出完整的终端摘要——不得因文件写入而阻止摘要输出。
• 如果模板文件缺失，则按相同的章节顺序内联生成内容；仍须执行 C 中的保存步骤。

状态阈值（适用于整体健康度和各类别评分）：

• 80–100 = “健康”
• 60–79 = “需要关注”
• 0–59 = “严重”

Token 预算指南： 对于约有 100 个发现的代码库，分层发现布局（主要问题以表格呈现，次要问题／建议仅显示数量——全部内容保存在文件中）旨在将磁盘上的报告控制在 8,000–12,000 个 token 左右（若所有发现都完整呈现，则约为 40,000 个 token）。终端摘要则精简得多，因为其中仅流式输出仪表板、执行摘要、严重发现和前 5 项修复顺序。用户可通过 /codeprobe security . 等命令深入查看特定类别的完整详情。

/codeprobe quick — 快速审查摘要

使用 templates/quick-review-summary.md 中的模板（通过 Read 加载）。如果模板尚不存在，则内联生成：

1. 标题：项目名称、“快速审查 — 前 5 个问题”。
2. 前 5 项发现：影响最大的 5 个问题的完整详情，每项都附带修复提示词。
3. 汇总数量：所有类别中按严重程度划分的发现问题总数。
4. 后续步骤：建议运行 /codeprobe audit 以获得完整情况。

/codeprobe diff — PR 风格审查

使用 templates/pr-review-comment.md 中的模板（通过 Read 加载）。将 {branch} 替换为当前分支（git rev-parse --abbrev-ref HEAD），将 {base_branch} 替换为已解析的基准分支，将 {changed_files} 替换为已审查文件的数量，并将 {overall_score} 替换为依据 diff 发现问题、按标准公式（Section 7）计算出的结果。将 {version} 替换为此文件的 frontmatter 中的 metadata.version。

• 终端：将填充后的模板直接作为助手回复 Markdown 输出（内容足够精简，可以完整流式输出），然后输出保存确认行（格式与 Section 8B 步骤 5 相同）。
• 保存的文件：相同的 Markdown，按照 Section 8C 中的文件名和写入规则，写入 ./codeprobe-reports/{project}-diff-{YYYY-MM-DD-HHMMSS}.md。
• 渲染出的 Markdown 专为可直接粘贴到 GitHub PR 评论而设计——内容应自成一体，不要在正文中提及“已保存的文件”。

9. Claude.ai 降级模式

检测是否可以访问文件系统。如果用户粘贴或上传了代码，而非提供文件路径，或者 Read/Glob/Grep 工具不可用：

1. 切换到降级模式：仅分析上下文中提供的代码。
2. 按顺序执行子技能，分析粘贴的代码（不使用并行 Agent）。
3. 跳过 file_stats.py、dependency_mapper.py 和所有依赖脚本的步骤（子技能改用仅基于大模型的分析——架构分析将失去确定性循环检测能力）。
4. 跳过 /codeprobe diff、/codeprobe report、审计仪表板中的 Codebase Stats 行，以及报告保存步骤（无法写入文件系统）。仍需在终端中输出评分、热点和发现。
5. 告知用户：“正在 Claude.ai 模式下运行——代码库统计、差异审查和多文件分析等部分功能不可用。正在直接分析提供的代码。”
6. 仍需按标准输出约定格式生成发现。
7. 仍需根据可用子技能的发现计算评分。

---

10. 第 3 阶段占位功能

当用户调用路由到尚未构建功能的命令时，回复：

暂不可用。 此功能将在第 3 阶段推出。目前可用的命令：

• /codeprobe audit <path> — 完整代码审计
• /codeprobe diff [base] — 对比基础分支，进行 PR 风格的变更文件审查
• /codeprobe solid <path> — SOLID 原则检查
• /codeprobe security <path> — 安全审计
• /codeprobe smells <path> — 代码异味检测
• /codeprobe architecture <path> — 架构分析
• /codeprobe patterns <path> — 设计模式分析
• /codeprobe performance <path> — 性能审计
• /codeprobe errors <path> — 错误处理审计
• /codeprobe tests <path> — 测试质量审计
• /codeprobe framework <path> — 框架最佳实践
• /codeprobe quick <path> — 排名前 5 的问题

此规则适用于：report。

---

11. 执行流程摘要

调用 /codeprobe 时，按以下顺序执行：

1. 解析命令：从用户输入中提取子命令和目标路径。
2. 验证命令：检查路由表。如果是第 3 阶段占位功能，则回复占位功能消息。
3. 解析目标路径：使用提供的路径，或默认为当前工作目录。对于 diff：改为根据第 4A 节解析基础引用，并收集变更文件及对应行范围——清单仅限于这些文件。
4. 加载配置：检查项目根目录下是否存在 .codeprobe-config.json。若不存在，则应用默认值。
5. 自动检测技术栈：扫描目标路径中的技术信号。加载匹配的参考资料。
6. 应用配置覆盖项：如果配置中设置了 framework，则调整检测结果。应用 skip_categories 和 skip_rules。
7. 执行子技能：准备共享上下文（第 4 节），然后以适当模式并行启动所有适用的子技能 Agent。
8. 收集发现：按输出约定格式汇总所有发现。
9. 去重发现：应用跨类别去重流程（第 7A 节）——将真正的冲突移至“冲突建议”部分，删除重复项，并按类别重新统计严重性总数。
10. 计算评分：使用去重后的严重性计数和第 7 节中的公式，计算各类别及总体评分。
11. 生成报告：使用适当的模板或内联格式整理输出。对 /codeprobe audit 使用分层输出格式。
12. 向用户展示：显示最终报告。

请记住：整个流程均为只读操作。任何时候都不会修改用户的文件。