Nixdorfer 项目代码审计
触发条件
当用户请求代码审计/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 同时启动 最大化并行度
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` 项目特定规则