codebase-audit

代码库审计 — 自适应深度分析

全面审计代码库，根据项目技术栈自适应调整 Agent 配置，强制生成结构化审查结果，在纳入报告前对严重/高危问题进行对抗式验证，与上次审计台账进行差异比对（已解决／仍未解决／新增），并输出按严重程度排序的报告和分阶段修复路线图。

核心原则

1. 只读 — 审计 Agent 绝不能在目标中创建、修改或删除文件。每个 Agent 提示词都以 references/agent-prompts.md 中的只读前置说明开头。
2. 继承会话模型 — 所有 Agent 都省略 model 参数，以继承会话模型（通常是当前可用能力最强的模型）。只有在会话模型明显不擅长跨文件推理时，才向上覆盖。绝不要在此技能中硬编码特定模型名称。
3. 深度优先于广度 — 与其使用许多浅层 Agent，不如使用数量较少、范围合并更广的 Agent。每个 Agent 都会跨文件追踪问题。
4. 自适应 — Agent 数量和审查维度会因技术栈和模式而异。
5. 经过验证的审查结果 — 严重/高危问题必须通过对抗式验证。中危问题会保留，但在报告中标记为 unverified。

操作约定

• 直接操作：只读检查、本地依赖审计、在目标目录下撰写报告，以及在用户调用此技能后更新 <target>/.audit/ 下的台账。
• 以下操作前须升级处理：编辑已审计项目的源文件、依赖清单、.gitignore、CI 配置、远程问题、PR 状态，或任何超出所请求的审计／报告范围的内容。
• 机密证据：保留文件路径、行号及周边代码，但在审查结果、报告和台账条目中将凭据值替换为 [REDACTED]；绝不复现原始内容。此脱敏代码片段符合代码证据要求。
• 基于证据进行质疑：只有在有文件证据、依赖审计输出、验证器结果或台账抽查结果的情况下，才质疑“未发现问题”或“已解决”的说法。
• 反馈循环：将反复漏检的问题纳入提示词更新、台账匹配规则或测试用例，而不是仅作为本次会话的备注。

注意事项

• 依赖审计命令必须在 {TARGET_DIR} 下运行，而不是在助手碰巧所在的当前工作目录下运行。
• 审计植入漏洞的测试夹具时，发现 Agent 不得读取 evals/expected-findings.json 或 eval README 文件。
• 上次台账未记录某问题，并不能证明该问题已解决；将旧问题标记为 resolved 前，必须抽查对应文件。

模式

模式	触发条件	Agent	验证环节	台账
full（默认）	直接调用、“全面审查”	按技术栈配置 3–5 个（可添加可选维度）	是	是
quick	参数中包含“quick”、“快速体检”	2 个（静默降级与安全；数据完整性与注册表）	否 — 所有审查结果均标记为 unverified	是

可选维度（仅限 full 模式，仅在用户要求或代码库明显需要时启用）：

• tests — 测试质量：断言强度、跳过标记、关键路径覆盖率（Agent 6）
• concurrency — 竞态、异步代码中的阻塞调用、泄漏的任务／goroutine（Agent 7）

工作流

阶段 0：检测与准备

1. 技术栈检测：package.json/tsconfig.json → TS/JS；pyproject.toml/requirements.txt → Python；Cargo.toml → Rust；go.mod → Go；存在多种文件 → 全栈。
2. 规模估算：运行 tokei <target>（备用方案：find <target> -name '*.<ext>' | xargs wc -l），排除供应商提供的代码和生成代码。如果有效规模 ≥ 400K LOC，则按顶层目录划分每个 Agent 的范围，并在报告中注明划分方式。
3. 排除项（始终包含在每个 Agent 提示词中）：node_modules/、vendor/、target/、dist/、build/、.git/、锁文件、生成代码。
4. 台账：如果 <target>/.audit/findings.json 存在，则读取它——这是先前审计的基线（格式：references/ledger-format.md）。
5. 确定性依赖审计：从 {TARGET_DIR}（绝不能使用助手偶然所在的当前工作目录）运行每个匹配的工具，并将原始输出传递给错误处理与安全提示词：
   • Rust：cargo audit
   • Node：npm audit
   • Python 元数据（pyproject.toml / setup.py）：pip-audit .
   • Python requirements（requirements.txt）：pip-audit -r requirements.txt
   • 无项目文件时的 Python 备用方案：pip-audit .
   • Go：govulncheck ./... 如果所需工具不可用，报告必须注明 依赖审计降级跳过: <tool>；绝不能默默省略降级情况。

阶段 1：组装维度

根据检测到的技术栈选择配置。完整提示词模板见 references/agent-prompts.md；在每个模板前添加只读前导语，并注入 {TARGET_DIR} / {STACK_INFO}。

全栈（5 个 Agent）——同时包含前端和后端：

#	维度	范围（合并后）
1	前后端契约	类型一致性 + 渲染流水线 + 序列化边界。读取前后端双方。
2	数据完整性与流转	端到端流水线追踪、字段丢失、声明与执行之间的差距、注册表覆盖范围对齐。
3	错误处理与安全	静默降级、异常模式、机密信息、注入、不安全的反序列化。
4	架构与代码质量	分层违规、上帝对象、重复与偏移、扩展成本、注册表交叉引用。
5	配置与持久化	配置完整性、缓存键/完整性、数据库架构、临时文件、状态持久化。

仅后端（4 个 Agent）：将第 1 项替换为“API 契约与数据完整性”（吸收第 2 项的数据流/注册表范围——不要再派发第 2 项）；保留第 3–5 项。 仅前端（3 个 Agent）：组件架构与渲染；错误处理与代码质量；配置与构建。 快速模式（2 个 Agent）：静默降级与安全（= 第 3 项）；数据完整性与注册表（= 第 2 项核心）。

备用路径下的 Agent 类型（使用 Agent 工具而非 Workflow 时）：Agent 是否可用取决于具体环境——检查当前会话中可见的子 Agent 注册表，并且只能使用其中出现的类型名称。绝不要编造别名（不存在通用的 reviewer 类型）。如果没有匹配的专用类型，则每个维度都使用 general-purpose（或环境默认的通用类型）；提示词本身已包含完整说明。示例映射见 references/agent-prompts.md。

阶段 2：编排

首选——Workflow 工具（调用技能需由用户选择启用）：使用 references/workflow-template.md 中的脚本。它会强制将每个发现者的输出规范为结构化发现，然后将每个维度的严重/高危发现直接传递给对抗式验证 Agent（无需等待——验证会在其他维度仍在扫描时开始）。

备用——Agent 工具（Workflow 不可用时）：在一条消息中启动所有发现者 Agent；提示词已要求输出相同的 JSON。它们返回后，在一条消息中批量启动每条严重/高危发现对应的一个验证 Agent，并使用 references/workflow-template.md 中的验证提示词。

阶段 3：去重与台账差异

去重：

• 同一文件 + 同一行 → 合并。
• 多个 Agent 发现同一根本原因 → 保留最详细的一项，并注明已获得其他 Agent 确认（提高置信度）。
• 严重性存在冲突 → 采用最高级别。

验证结果：

• confirmed=false 的发现不进入主报告；将其列入附录“已被验证否定”，并注明否定理由（确保工作可审计）。
• 验证器失败或缺失 → 保留该发现，并标记为 unverified。

台账差异（没有上一份台账时跳过——所有发现均为 new）：

• 按 （类别、文件、根本原因摘要） 匹配上一份与当前发现——绝不能按行号匹配（行号可能变化）。
• 上一份台账中的发现若在当前结果中没有匹配项 → 打开文件并进行抽查，然后再标记为 resolved；如果问题仍然存在但此前被漏掉，则重新添加为 still-open。
• 将当前每项发现分类为：new / still-open。
• 将更新后的台账写入 <target>/.audit/findings.json。如果仓库处于版本控制中且 .audit/ 未被忽略，建议将其添加到 .gitignore（不要自行编辑 .gitignore）。

阶段 4：报告

将完整报告写入 <target>/audit-report-YYYY-MM-DD.md，然后发布聊天摘要：各严重级别的数量、最重要的 Critical 问题、台账变化（N 项已解决 / N 项仍未解决 / N 项新发现）、依赖项审计状态以及路线图。

报告正文要求：

• 问题描述、影响分析和修复建议使用中文；代码标识符、路径和错误消息保留原文。
• 将每项发现分别写成事实 / 推断 / 建议：发现本身是事实，并注明 file:line；影响是推断，并注明置信度；修复建议是建议，并注明假设。
• 仅基于推断的发现，严重性不得高于 Medium，除非验证器确认其对用户可见或具有安全影响。

报告结构：

# [Project] Codebase Audit Report
> Date / Target / Stack / Mode / Agents / Dependency audit / Previous audit: date or "none"

## Summary
| Level | Count | Verified | Key Areas |

## Delta vs Previous Audit   (omit if first audit)
Resolved: N (list) | Still-open: N | New: N

## Critical (Fix Immediately)
Per finding: file:line, code snippet, risk, fix suggestion, verify status.

## High / P1 (Fix This Week)     — grouped by category
## Medium / P2 (Plan to Fix)     — labeled unverified where applicable

## Refuted by Verification       — appendix: finding + refutation reason

## Repair Roadmap
| Phase | Scope | Est. Files |

严重性分类

级别	标准
Critical	数据丢失、渲染失败、安全漏洞、导致用户当前无法使用的功能完全失效
High/P1	无提示的功能降级（用户看到错误或不完整的输出）、导致数据截断的类型不匹配、导致输出为空的配置缺失、阻碍开发的架构违规
Medium/P2	代码重复、模式不一致、错误处理不够完善、拖慢开发但不会导致功能失效的技术债务

参考资料

• references/agent-prompts.md — 只读前言 + 提示词模板（Agent 1–7）
• references/stack-patterns.md — 各技术栈的搜索模式
• references/workflow-template.md — 工作流脚本、发现项/判定结果的架构、验证提示词
• references/ledger-format.md — 台账 JSON 架构和匹配规则
• evals/ — 预置缺陷的测试样本；评估用于衡量相对于 evals/expected-findings.json 的召回率