audit

name	audit
description	项目代码审计 使用 agent teams 按模块并行审计模块化/健壮性/安全性/优化/完成度/调用链/设计一致性/功能完善度/前端运行时验证

项目代码审计

触发条件

当用户请求代码审计/code audit/代码质量检查时加载此技能

[IMPORTANT] 主 Agent 职责约束

主 Agent (与用户直接对话的 Agent) 禁止执行任何实际操作 包括但不限于:

• 禁止使用 Read/Grep/Glob 工具直接阅读或搜索代码
• 禁止使用 Edit/Write 工具修改任何文件
• 禁止直接运行构建/测试命令

主 Agent 的授权允许职责:

1. 派发 - 通过 Agent 工具启动 subagent / agent teams
2. 协调 - 管理 agent 之间的依赖和执行顺序
3. 收集 - 接收各 agent 返回的报告
4. 汇总 - 将报告整合后输出给用户
5. 脚本调用 - 仅限运行 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 是否存在:

1. 如果存在 运行 python ~/.claude/skills/audit/scripts/audit_checklist.py verify [root] 检查审计状态
2. 如果所有文件 status 均为 audited 则告知用户: "上一轮审计已全部完成 是否开启新一轮审计?"
   • 用户确认后 只删除 checklist.yaml 保留 modules/ 设计文档和 config.yaml
   • 重新从 Phase 1 开始 (Explore 时更新已有的设计文档而非重写)
3. 如果存在 pending 文件且 sha256 一致 → 跳过 Phase 1 直接从 Phase 2 继续审计未完成的文件
4. 如果存在 sha256 不匹配的文件 运行 python ~/.claude/skills/audit/scripts/audit_checklist.py refresh [root] 自动更新状态
5. 运行 python ~/.claude/skills/audit/scripts/audit_checklist.py summary [root] 输出当前进度
6. 读取已有的模块设计文档 (.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 同时启动 最大化并行度

Explore 完成后 执行以下初始化:

1. 初始化审计配置

如果 .audit/config.yaml 不存在 运行:

python ~/.claude/skills/audit/scripts/audit_checklist.py init [root]

生成默认 config.yaml 然后根据 Explore 结果 编辑 config.yaml 添加项目特定的排除规则和模块映射

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]               # 检查所有文件 sha256 是否变更
python audit_checklist.py refresh [root]               # 更新 sha256 标记 stale/modified
python audit_checklist.py mark <module|filepath> [root] # 标记模块或文件为已审计 (自动 rehash)
python audit_checklist.py summary [root]               # 显示审计进度
python audit_checklist.py pending [module] [root]       # 列出待审计文件
python audit_checklist.py init [root]                   # 生成默认 config.yaml

checklist.yaml 格式:

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

status 取值:

• 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} (仅前端模块)

{交互死角/测试覆盖/API 对接问题列表}

需要修复的问题 (按优先级排序)

#	严重度	维度	文件:行号	描述	建议

评分标准:

• A: 优秀 无明显问题
• B: 良好 有小问题但不影响功能
• C: 需改进 有明显问题影响质量
• D: 需重构 有严重问题

### Phase 3: 主 Agent 汇总

收集所有模块 Agent 的审计结果后:

1. 生成项目级审计总表

项目审计总览

模块	模块化	健壮性	安全性	优化	完成度	调用链	设计一致性	功能完善	前端验证	高优问题数

跨模块问题

{识别跨模块的系统性问题 如重复实现/循环依赖/不一致的模式}

建议优先修复

{按影响范围和严重度排序的 top 10 问题}

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` 项目特定规则