Skip to main contentaudit
项目代码审计 使用 agent teams 按模块并行审计模块化/健壮性/安全性/优化/完成度/调用链/设计一致性/功能完善度/前端运行时验证
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Un comando directo omite el prompt de revisión. Revisa el origen antes de ejecutarlo.
npx skills add https://github.com/Nixdorfer/ClaudeCodeTool --skill auditEl comando permanece en una sola línea. Desplázate horizontalmente para revisarlo antes de copiarlo.
¿Prefieres una copia local? Descarga los archivos que SkillsMP tiene disponibles ahora.
Ocupaciones relacionadasSOC
Basado en la clasificación ocupacional SOC
Explorador de archivos
2 archivos| name | audit |
| description | 项目代码审计 使用 agent teams 按模块并行审计模块化/健壮性/安全性/优化/完成度/调用链/设计一致性/功能完善度/前端运行时验证 |
项目代码审计
触发条件
当用户请求代码审计/code audit/代码质量检查时加载此技能
[IMPORTANT] 主 Agent 职责约束
主 Agent (与用户直接对话的 Agent) 禁止执行任何实际操作 包括但不限于:
- 禁止使用 Read/Grep/Glob 工具直接阅读或搜索代码
- 禁止使用 Edit/Write 工具修改任何文件
- 禁止直接运行构建/测试命令
主 Agent 的授权允许职责:
- 派发 - 通过 Agent 工具启动 subagent / agent teams
- 协调 - 管理 agent 之间的依赖和执行顺序
- 收集 - 接收各 agent 返回的报告
- 汇总 - 将报告整合后输出给用户
- 脚本调用 - 仅限运行
audit_checklist.py 等审计管理脚本
所有实际的代码阅读/分析/修改操作 必须委派给对应的 subagent/team-agent 执行
这样做的目的是维持主 Agent 的 context 清洁度 避免大量代码内容污染主对话上下文 确保主 Agent 能在整个审计过程中保持有效的协调能力
目录结构
.audit/
├── config.yaml # 审计配置 (排除规则/模块映射)
├── checklist.yaml # 审计进度清单 (含 sha256)
├── modules/
│ ├── {module-name}.md # 模块设计意图文档 (跨审计轮次保留)
│ ├── {module-name}-components.md # 拆分文件 (当单文件超 500 行时)
│ ├── {module-name}-api.md # 拆分文件 (按职责域拆分)
│ └── ...
模块文档行数限制
每个 .audit/modules/*.md 文件 不得超过 500 行 超过时必须按职责域拆分为多个文件:
拆分策略:
- 主文件
{module}.md 保留: 路径/职责/设计意图/对外接口/依赖关系/架构规则
- 前端组件描述拆分到
{module}-components.md (如组件数量多 可继续按页面拆分)
- 后端接口描述拆分到
{module}-api.md
- 如单个拆分文件仍超 500 行 继续按子域拆分 如
{module}-components-kag.md
拆分文件之间通过文件名前缀关联 主文件中用 ## 参见 列出所有拆分文件路径
审计流程
Phase 0: 检查审计状态
审计开始前 先检查 .audit/checklist.yaml 是否存在:
- 如果存在 运行
python ~/.claude/skills/audit/scripts/audit_checklist.py verify [root] 检查审计状态
- 如果所有文件 status 均为
audited 则告知用户: "上一轮审计已全部完成 是否开启新一轮审计?"
- 用户确认后 只删除
checklist.yaml 保留 modules/ 设计文档和 config.yaml
- 重新从 Phase 1 开始 (Explore 时更新已有的设计文档而非重写)
- 如果存在
pending 文件且 sha256 一致 → 跳过 Phase 1 直接从 Phase 2 继续审计未完成的文件
- 如果存在 sha256 不匹配的文件 运行
python ~/.claude/skills/audit/scripts/audit_checklist.py refresh [root] 自动更新状态
- 运行
python ~/.claude/skills/audit/scripts/audit_checklist.py summary [root] 输出当前进度
- 读取已有的模块设计文档 (
.audit/modules/) 作为上下文传给审计 Agent
Phase 1: Explore Agent 扫描项目结构
Step 1: 总览 Agent (1 个)
派发一个 Explore Agent 扫描项目整体结构:
扫描当前项目的目录结构和代码组织
识别所有独立模块/子系统及其边界
要求:
1. 列出所有顶层模块目录
2. 每个模块的职责 (根据目录名/文件内容推断)
3. 每个模块的大致代码量 (文件数)
4. 模块间的依赖关系 (import/require 方向)
5. 跳过 node_modules/dist/build 产物/vendor/target
输出格式:
| 模块名 | 路径 | 职责 | 文件数 | 主要依赖 |
总览完成后 执行初始化配置 (config.yaml + checklist) 确定模块列表
Step 2: 按模块并行派发 Explore Agent (每模块 1 个)
根据 config.yaml 中的 module_map 为每个模块启动一个独立的 Explore Agent 并行生成/更新设计文档
每个 Explore Agent 的 prompt:
深入扫描以下模块 生成设计意图文档
模块: {模块名}
路径: {模块路径列表 (module_map 中映射到该模块的所有目录)}
职责: {从总览结果中提取的职责}
要求:
1. 阅读该模块下所有源代码文件
2. 按照设计文档模板生成完整描述
3. 识别对外接口/依赖关系/架构规则
4. 前端模块需描述每个组件的视觉元素/交互逻辑/数据流
5. 后端模块需描述每个接口的入口/调用链/副作用
6. 将结果写入 .audit/modules/{module-name}.md
7. 单个文件不得超过 500 行 超过时按职责域拆分为多个文件
- 拆分文件命名: {module-name}-{domain}.md (如 creator-frontend-components.md)
- 主文件末尾用 ## 参见 列出所有拆分文件路径
所有模块 Explore Agent 同时启动 最大化并行度
1. 初始化审计配置
如果 .audit/config.yaml 不存在 运行:
python ~/.claude/skills/audit/scripts/audit_checklist.py init [root]
生成默认 config.yaml 然后根据 Explore 结果 编辑 config.yaml 添加项目特定的排除规则和模块映射
exclude_dirs:
- ".claude"
- ".vscode"
- "agent-prompt"
- "some-generated-dir"
exclude_files:
- "some-specific-file.js"
module_map:
"ocs/bridge": "bridge"
"ocs/core": "bridge"
"ocs/inject": "bridge"
"ocs/iframe": "bridge"
"ocs/kag": "kag"
"ocs/panel": "panel"
"creator/src-tauri": "creator-backend"
"creator/src": "creator-frontend"
2. 模块设计文档 (由 Step 2 的 Explore Agent 生成)
Step 2 的 Explore Agent 会在 .audit/modules/ 下为各自模块创建或更新设计文档
如果 .audit/modules/{module-name}.md 已存在 则在已有内容基础上更新 而非覆盖
# {模块名}
## 路径
{模块路径}
## 职责
{从 Explore 结果提取的职责描述 + 代码分析得出的详细职责}
## 设计意图
{根据代码结构/命名/导出推断的设计意图}
{为什么以这种方式组织? 解决什么问题?}
## 对外接口
{模块导出的所有接口/函数/类/常量 按用途分组}
## 依赖关系
- 依赖: {该模块依赖的其他模块 标注具体引用了哪些接口}
- 被依赖: {依赖该模块的其他模块 标注被引用了哪些接口}
## 架构规则
{从 CLAUDE.md/rules/ 中提取的与该模块相关的架构约束}
## 前端页面描述 (仅前端模块)
### 页面/组件列表
{列出每个组件}
### 每个组件的详细描述
#### {组件名}
**视觉元素:**
- 列出页面上的每一个可见元素 (标题/按钮/输入框/列表/图标/分隔线等)
- 每个元素的位置 / 样式特征 / 条件渲染逻辑
- 响应式布局行为 (不同屏幕尺寸)
**样式美化:**
- CSS 变量/主题依赖
- 动画/过渡效果
- 特殊样式处理 (暗色模式/RTL/滚动行为)
**交互逻辑:**
- 每个可交互元素 (按钮/链接/输入/拖拽) 绑定的事件处理函数
- 事件 → 处理函数 → store action → API 调用 的完整调用链
- 条件分支和不同状态下的行为
**数据流:**
- 组件 props / inject / store 依赖
- computed / watch / 响应式数据的来源和流向
- 与父组件/子组件/兄弟组件的数据通信方式
## 后端接口描述 (仅后端模块)
### 接口列表
{列出每个暴露的接口/command}
### 每个接口的详细描述
#### {接口名}
**入口:**
- 请求参数类型和验证规则
- 权限要求
**完整调用链:**
- 入口函数 → 中间处理层 → 数据访问层 → 返回 的完整路径
- 每一步的输入输出类型
- 错误处理和回滚逻辑
**副作用:**
- 数据库读写操作
- 文件系统操作
- 外部服务调用
- 事件/通知触发
3. 生成审计 checklist
python ~/.claude/skills/audit/scripts/audit_checklist.py generate [项目根目录]
脚本从 .audit/config.yaml 读取项目特定的排除规则 结合内置的通用排除规则 扫描文件并生成 checklist
python audit_checklist.py verify [root]
python audit_checklist.py refresh [root]
python audit_checklist.py mark <module|filepath> [root]
python audit_checklist.py summary [root]
python audit_checklist.py pending [module] [root]
python audit_checklist.py init [root]
created: "2026-03-19T12:00:00Z"
summary:
total: 128
audited: 0
pending: 128
stale: 0
modified: 0
modules:
bridge:
- path: "ocs/bridge/api.js"
sha256: "a1b2c3d4..."
status: pending
- path: "ocs/bridge/core.js"
sha256: "e5f6a7b8..."
status: pending
kag:
- path: "ocs/kag/adapter.js"
sha256: "c9d0e1f2..."
status: audited
pending - 未审计audited - 已审计 sha256 与当前文件一致stale - 已审计但文件已被修改 (sha256 不匹配) 需重新审计modified - 上次未完成审计且文件已变更 需重新审计
Phase 2: 派发模块审计 Agent (Agent Teams)
每个模块启动一个独立的 Agent 并行审计 这是 agent teams 模式:
- 主 Agent 负责协调和汇总
- 每个模块审计 Agent 独立运行 互不干扰
- Agent 类型: code-reviewer
- 所有模块 Agent 同时启动 最大化并行度
每个 Agent 收到的 prompt 必须包含:
- 该模块的设计意图文档 (从
.audit/modules/{module-name}.md 读取)
- 相关模块的设计意图文档 (依赖/被依赖的模块)
你是代码审计专家 对以下模块进行深度审计
模块: {模块名}
路径: {模块路径}
职责: {模块职责描述}
## 模块设计意图
{从 .audit/modules/{module-name}.md 读取的完整内容}
## 相关模块设计意图
{依赖/被依赖模块的设计文档摘要}
## 审计维度
### 1. 模块化 + 系统化 + 解耦合度
检查项:
- 模块是否有明确的单一职责
- 模块间是否通过接口/协议通信 而非直接访问内部实现
- 是否存在循环依赖或跨层依赖 (Core 依赖 UI)
- 共享逻辑是否提取到公共模块 而非重复实现
- 是否存在平行系统 (多个模块做同一件事)
- 全局可变状态的使用情况
- 导出接口是否最小化 (不暴露内部实现)
### 2. 健壮性
检查项:
- 边界条件处理 (空值/零值/溢出/越界)
- 错误传播是否完整 (是否有静默吞错误)
- 异步操作的错误处理 (未捕获的 Promise/panic)
- 资源释放 (事件监听器/定时器/连接)
- 类型安全 (any 滥用/类型断言/未检查类型转换)
- 数据校验 (反序列化/外部输入/格式转换)
- 竞态条件 (并发访问共享状态)
### 3. 安全性
检查项:
输入/输出安全:
- 注入攻击 (XSS/SQL 注入/命令注入/模板注入/原型链污染)
- 未转义的用户输入直接拼接到 HTML/SQL/Shell/eval
- 敏感数据泄露 (错误信息/日志/响应体中暴露内部路径/堆栈/凭据)
- 不安全的反序列化 (JSON.parse 未校验/pickle/yaml.load)
- SSRF (服务端请求伪造 用户可控 URL 未做白名单校验)
- 路径遍历 (用户输入拼接文件路径未规范化)
内存安全:
- 缓冲区溢出/越界读写 (Rust unsafe 块/C FFI/Wasm 边界)
- Use-after-free / double-free (手动内存管理场景)
- 未限制的内存增长 (无上限的缓存/队列/历史记录)
- 大对象未及时释放 (闭包捕获/事件监听器泄漏)
- ArrayBuffer/TypedArray 越界访问
- Wasm 线性内存与 JS 堆的交互边界检查
硬件/运行时安全:
- 侧信道攻击面 (时序攻击: 字符串比较未用恒定时间比较)
- 不安全的随机数 (Math.random 用于安全场景而非 crypto.getRandomValues)
- 加密误用 (弱哈希算法/ECB 模式/硬编码 IV/密钥)
- WebWorker/SharedArrayBuffer 的 Spectre 缓解 (COOP/COEP headers)
漏洞防御:
- 依赖链安全 (已知 CVE 的依赖版本)
- 权限最小化 (过度请求的 API 权限/文件系统权限)
- CSP/CORS 配置 (过于宽松的策略)
- iframe 沙箱逃逸 (sandbox 属性/postMessage origin 校验)
- 供应链攻击面 (动态加载的外部脚本/CDN 资源未做 SRI)
### 4. 优化程度
检查项:
- 算法复杂度 (是否存在 O(n²) 或更差的可优化算法)
- 内存分配 (不必要的拷贝/临时对象/大数组)
- 重复计算 (可缓存但未缓存的结果)
- 热路径性能 (高频调用函数的效率)
- 数据结构选择 (是否使用了合适的数据结构)
- 惰性加载 (是否有可延迟的初始化/加载)
- DOM 操作效率 (如适用: 批量更新/虚拟滚动/防抖)
### 5. 完成度
检查项:
- 未完成的功能 (空函数体/stub 实现/placeholder 返回值)
- TODO/FIXME/HACK/XXX/TEMP 标记的待办项
- 未实现的接口方法或抽象方法
- 被注释掉的代码块 (判断是遗留还是未完成)
- 声明但未使用的导出/变量/函数
- 部分实现的特性分支 (只完成了一半的逻辑)
发现问题后: 直接完成实现 而非仅报告
### 6. 调用链完整性
检查项:
- 函数/方法被声明但从未被调用 (死代码 vs 缺失调用)
- 事件注册后无对应的触发点 或触发后无对应的监听
- 回调/Promise 链中断 (未 resolve/reject/未 await/未处理返回值)
- 模块导出的接口在消费方未正确引用 (重命名后未同步)
- 数据流断裂 (上游产出的数据下游未消费 或下游期望的数据上游未提供)
- 条件分支导致的不可达代码路径
- 生命周期钩子缺失 (注册了 init 但没有对应的 destroy/cleanup)
发现问题后: 修复断裂的调用链 补全缺失的连接
### 7. 设计一致性
检查项:
- 实现是否符合 CLAUDE.md 和 rules/ 中定义的架构规则
- 同类功能是否采用一致的模式 (如错误处理/状态管理/通信方式)
- 命名约定是否统一 (同一概念在不同模块中的命名)
- API 风格是否一致 (参数顺序/返回值格式/异步模式)
- 与模块声明的职责是否匹配 (是否越权或缺位)
- 数据模型在各层之间的映射是否正确
发现问题后: 按照设计规则修正实现 使其与预期一致
### 8. 功能完善度 (设计层面)
这不是代码质量审计 而是产品/设计层面的审计 需要从用户视角审视
检查项:
- 功能缺失: 根据模块设计意图 是否有应该存在但未实现的功能
- 交互死角: 用户可能触发但没有处理的操作路径 (如空状态/边界情况/异常流程)
- 反馈缺失: 操作后是否有足够的视觉/状态反馈 (loading/success/error/empty)
- 可发现性: 功能是否能被用户自然地发现和使用 (隐藏过深/入口不明显)
- 一致性: 同类操作在不同页面/组件中的行为是否一致
- 容错性: 用户误操作时是否有确认/撤销机制
- 数据完整性: 增删改查流程是否闭环 (能创建但不能删除/能编辑但不能保存)
- 状态同步: 多视图/多组件间的数据是否保持一致 (一处修改其他处是否更新)
发现问题后: 报告缺失功能和设计问题 给出具体的改进建议 对可直接修复的问题立即修复
### 9. 前端运行时验证 (仅前端模块)
对包含 UI 组件的模块 进行运行时级别的验证:
#### 9a. 交互路径模拟
读取每个组件的模板/JSX 识别所有可交互元素:
- 按钮 (@click / onClick)
- 表单输入 (v-model / onChange)
- 链接/导航 (router-link / href)
- 下拉菜单/弹窗触发器
- 拖拽/手势操作
- 键盘快捷键
对每个交互元素:
1. 追踪其绑定的事件处理函数
2. 验证处理函数是否存在且逻辑完整
3. 检查处理函数中的条件分支是否都有对应的 UI 反馈
4. 确认异步操作有 loading/error 状态处理
#### 9b. 逻辑单元测试
为每个组件/composable 的核心逻辑构建单元测试:
- 状态管理逻辑 (store actions/mutations/getters)
- 数据转换/格式化函数
- 表单验证规则
- 条件渲染逻辑
- 计算属性/派生状态
测试要求:
- 覆盖正常路径 + 边界情况 + 错误路径
- 测试文件放在对应模块目录下的 `__tests__/` 或 `tests/`
- 使用项目已有的测试框架 (vitest / jest)
#### 9c. API 接口验证
对所有调用后端接口的代码:
1. 识别接口调用点 (fetch / axios / tauri invoke)
2. 根据代码中的参数构造和响应处理 推断接口的请求/响应格式
3. 检查请求参数构造是否完整 (必填字段是否遗漏/类型是否匹配)
4. 检查响应处理是否覆盖所有可能的状态码和数据格式:
- 成功响应的数据解析
- 错误响应的处理 (4xx/5xx)
- 网络错误/超时的处理
- 空数据/null 响应的处理
5. 如果可以访问后端 (如 Tauri commands) 构造测试数据发送请求 验证:
- 请求是否被正确接收
- 响应值是否符合前端代码的期望格式
- 错误情况下的返回值是否被前端正确处理
发现问题后: 补全缺失的错误处理/状态处理 修复接口对接问题
## 审计完成后更新 checklist
每个 Agent 审计完一个模块后 主 Agent 使用脚本更新 checklist:
```bash
python ~/.claude/skills/audit/scripts/audit_checklist.py mark <module-name> [root]
- 将该模块下所有文件的 status 改为
audited
- 重新计算 sha256 (修复型审计可能修改了文件)
- 更新 summary 区的计数
python ~/.claude/skills/audit/scripts/audit_checklist.py mark <file-path> [root]
输出格式
每个模块 Agent 按以下格式返回审计结果给主 Agent:
模块: {模块名}
模块化评分: {A/B/C/D}
健壮性评分: {A/B/C/D}
安全性评分: {A/B/C/D}
优化评分: {A/B/C/D}
完成度评分: {A/B/C/D}
调用链完整性评分: {A/B/C/D}
设计一致性评分: {A/B/C/D}
功能完善度评分: {A/B/C/D}
前端验证评分: {A/B/C/D} (仅前端模块)
需要修复的问题 (按优先级排序)
- A: 优秀 无明显问题
- B: 良好 有小问题但不影响功能
- C: 需改进 有明显问题影响质量
- D: 需重构 有严重问题
### Phase 3: 主 Agent 汇总
收集所有模块 Agent 的审计结果后:
1. 生成项目级审计总表
项目审计总览
| 模块 | 模块化 | 健壮性 | 安全性 | 优化 | 完成度 | 调用链 | 设计一致性 | 功能完善 | 前端验证 | 高优问题数 |
|---|
跨模块问题
{识别跨模块的系统性问题 如重复实现/循环依赖/不一致的模式}
建议优先修复
2. 将完整审计报告输出给用户
3. 如果所有模块所有维度均为 A 且无待修复问题 → **审计通过 流程终止**
4. 否则 → 进入 Phase 4
### Phase 4: 自动修复
汇总完成后 **无需询问用户** 立即开始修复所有发现的问题
#### 修复策略
1. 从审计结果中收集所有需要修复的问题
2. 按模块/文件分组 按严重度排序 (CRITICAL > HIGH > MEDIUM > LOW)
3. 识别问题间的依赖关系:
- 跨模块问题优先于模块内问题
- 接口变更优先于实现变更
- 基础设施变更优先于业务逻辑变更
4. 将无依赖冲突的修复任务并行派发给尽可能多的 Agent
#### 派发规则
- 每个 Agent 负责一个模块或一组相关文件的修复
- 同一文件不能被多个 Agent 同时修改
- 跨模块问题由专门的 Agent 处理 (如重构共享模块/统一接口)
- Agent 类型选择:
- 代码修复 → general-purpose Agent
- 构建错误 → build-error-resolver Agent
- 重构/去重 → refactor-cleaner Agent
#### Agent prompt 模板
模块: {模块名}
设计文档: {从 .audit/modules/{module}.md 读取}
待修复问题列表
| # | 严重度 | 维度 | 文件:行号 | 描述 | 建议 |
{该模块的问题子表}
修复要求
- 遵循项目 CLAUDE.md 中的核心原则
- 只改必要的代码 最小变更
- 修复后确保不引入新问题
- 如果修复涉及接口变更 同步更新所有调用方
#### 修复完成后
1. 运行 `python ~/.claude/skills/audit/scripts/audit_checklist.py refresh [root]` 更新修复后的文件 sha256
2. 汇总修复结果输出给用户:
修复总结 (第 N 轮)
| 模块 | 修复数 | CRITICAL | HIGH | MEDIUM | LOW | 失败 |
|---|
未能自动修复的问题
3. 如果有构建相关的修改 运行构建验证
### Phase 5: 循环审计 (审计-修复-复审 循环)
修复完成后 **自动进入下一轮审计** 无需用户确认
#### 循环流程
Phase 2 (审计) → Phase 3 (汇总) → Phase 4 (修复) → Phase 5 (复审判定)
↑ │
└───────────── 仍有问题 ←───────────────────────────────┘
#### 复审规则
1. 运行 `audit_checklist.py refresh [root]` 将修复过的文件标记为 stale
2. **仅对 stale 文件所属模块** 重新派发审计 Agent (不重审未变更的模块)
3. 复审 Agent 收到的 prompt 额外包含:
- 上一轮该模块的审计报告 (避免重复报告已知且无法修复的问题)
- 本轮修复记录 (验证修复是否正确 是否引入新问题)
4. 收集复审结果 回到 Phase 3 汇总
#### 终止条件
循环在满足 **任一** 条件时终止:
| 条件 | 说明 |
|------|------|
| 零问题 | 所有模块所有维度均为 A 且无待修复问题 |
| 修复收敛 | 连续两轮的问题列表完全相同 (修复未产生效果 剩余问题需人工介入) |
| 轮次上限 | 达到 5 轮循环 (防止无限循环) |
#### 终止时输出
审计完成
总轮次: {N}
终止原因: {零问题 / 修复收敛 / 轮次上限}
最终状态
| 模块 | 模块化 | 健壮性 | 安全性 | 优化 | 完成度 | 调用链 | 设计一致性 | 功能完善 | 前端验证 |
|---|
残留问题 (如有)
{列出所有未能自动修复的问题 标注原因和建议的人工修复方案}
## 注意事项
- 只审计源代码 跳过 node_modules/dist/build 产物/vendor/target
- 优先关注高频调用路径和核心逻辑
- 关注移动端和低端设备的性能影响
- 审计结果要具体到文件和行号 不要泛泛而谈
- 维度 5/6/7 (完成度/调用链/设计一致性) 是修复型审计: 发现问题后直接修复 而非仅报告
- 模块设计文档是审计的重要上下文 审计 Agent 必须先阅读再审计
- checklist.yaml 是审计进度的唯一真相源 每次审计前必须检查
- sha256 用于检测文件变更 确保审计结果与代码版本对应
- 修复阶段自动执行 不需要询问用户确认
- 修复 Agent 数量不限 尽可能并行以提高效率
- 设计文档跨审计轮次保留 重新审计时只更新不删除
- 排除规则分两层: 脚本内置通用规则 + `.audit/config.yaml` 项目特定规则
