Cs Audit

# cs-audit 参考模板

## index.md 模板

```markdown
---
doc_type: audit-index
audit: {YYYY-MM-DD}-{slug}
scope: {审计范围一句话}
created: {YYYY-MM-DD}
status: active
total_findings: {N}
---

# {slug} 审计报告

## 范围

{扫描了哪些目录 / 文件，用户给的关键词或描述}

## 总评

{一段话总结：共发现几条、按维度分布、按严重度分布、最值得关注的是哪几条、整体代码质量印象}

## 发现清单

| # | 性质 | 严重度 | 置信度 | 标题 | 文件 |
|---|---|---|---|---|---|
| 1 | security | P0 | high | SQL 注入隐患 | [finding-01.md](finding-01.md) |
| 2 | performance | P1 | medium | 订单列表 N+1 查询 | [finding-02.md](finding-02.md) |
| ... | ... | ... | ... | ... | ... |

## 按维度分布

| 性质 | P0 | P1 | P2 | 合计 |
|---|---|---|---|---|
| bug | 0 | 2 | 1 | 3 |
| security | 1 | 0 | 0 | 1 |
| performance | 0 | 1 | 1 | 2 |
| maintainability | 0 | 0 | 3 | 3 |
| arch-drift | 0 | 1 | 0 | 1 |
| **合计** | **1** | **4** | **5** | **10** |

## 下一步建议

- **P0 立刻修**：{列表，建议开 cs-issue}
- **P1 本迭代修**：{列表}
- **P2 有空再看**：{列表}
```

---

## finding-NN.md 模板

```markdown
---
doc_type: audit-finding
audit: {YYYY-MM-DD}-{slug}
finding_id: "{nature}-{NN}"
nature: bug | security | performance | maintainability | arch-drift
severity: P0 | P1 | P2
confidence: high | medium | low
suggested_action: cs-issue | cs-refactor
status: open
---

# Finding {NN}：{一句话标题}

## 速答

{一句话描述——什么问题、在哪、什么影响}

## 关键证据

- `{file}:{line}` — {代码片段或描述} —— {为什么这构成问题}
- `{file}:{line}` — ...

## 影响

{影响范围 / 触发条件 / 影响用户数估计（如能判断）}

## 修复方向

{一句话建议修法，不展开——展开了就是抢 cs-issue / cs-refactor 的活}

## 建议动作

{`cs-issue` 或 `cs-refactor`}，因为 {一句话理由}
```

---

## 维度扫描检查项

扫描时逐项对照，不是每项都要有发现——没发现跳过。

### bug 隐患
- [ ] 空值路径：可选链缺失、null/undefined 未守卫
- [ ] 边界条件：空数组、空字符串、0、负数、极大值
- [ ] 竞态条件：异步操作顺序依赖、状态更新时序
- [ ] 错误处理：try-catch 为空、Promise rejection 未捕获、错误信息被吞
- [ ] 类型安全：类型断言无保护（`as` / `!`）、any 扩散

### 安全
- [ ] 注入：SQL/NoSQL 拼接、命令注入、XSS（innerHTML / dangerouslySetInnerHTML）
- [ ] 敏感数据：日志打印 token/密码、前端暴露密钥、响应体泄露字段
- [ ] 权限：缺少鉴权中间件、越权（资源归属未校验）
- [ ] 依赖：已知漏洞的第三方包、过期的安全敏感库

### 性能
- [ ] N+1 查询：循环内数据库调用 / API 请求
- [ ] 重复计算：未 memo 的昂贵运算、render 内创建对象/函数
- [ ] 无分页/虚拟化：全量加载大列表
- [ ] 内存泄漏：事件监听未清理、定时器未清除、闭包持有大对象
- [ ] 阻塞主线程：大文件同步读取、CPU 密集无 Web Worker

### 可维护性
- [ ] 超长函数（> 80 行）
- [ ] 高圈复杂度（> 15）
- [ ] 重复逻辑块（相同或高度相似代码出现 ≥ 3 次）
- [ ] 神秘常量（魔法数字无命名）
- [ ] 循环依赖（A → B → A）

### 架构偏离
- [ ] 分层泄漏：上层直接调下层实现细节、绕过中间层
- [ ] 模块隐式耦合：跨模块直接 import 内部文件（非公开 API）
- [ ] 与 `.codestable/architecture/` 记录不一致
- [ ] 约定违背：命名 / 目录结构 / 错误处理模式与项目约定不符


---
name: cs-audit
description: 系统审计——从代码中主动发现 bug 隐患、安全漏洞、性能问题、可维护性债务和架构偏离，产出批量发现清单。触发：用户说"审查系统"、"审计代码"、"扫描问题"、"找找 bug"、"有什么可以优化的"。
---

# cs-audit

## 启动必读

开始任何判断或动作前，先读取 `.codestable/attention.md`；缺失则视为骨架不完整，提示先补齐或运行 `cs-onboard`，不要回退到外部 AI 入口文件。

`cs-issue` 等你报 bug，`cs-refactor` 等你指优化点，`cs-explore` 等你提问题——但"我也不知道哪有问题，你先扫一遍看看"这个诉求没人接。`cs-audit` 补上这块：**在用户限定的范围内主动扫描，产出一份按严重度 × 性质交叉分类的发现清单**。

本技能只发现、不定修。修是 `cs-issue` / `cs-refactor` 的事。

---

## 文件放哪儿

```
.codestable/audits/{YYYY-MM-DD}-{slug}/
├── index.md           # 速览：范围、总评、发现清单交叉矩阵
├── finding-01.md
├── finding-02.md
└── ...
```

日期取审计当天。slug 短到一眼看出审计目标（`auth-module`、`order-flow`、`payment-security`）。

所有 audit 文档带 YAML frontmatter（`doc_type` 分别为 `audit-index` 和 `audit-finding`）便于 `search-yaml.py` 检索。

---

## 维度矩阵（交叉分类）

每个发现打两个标签：

**性质**：`bug` | `security` | `performance` | `maintainability` | `arch-drift`

**严重度**：`P0`（必须修）| `P1`（应该修）| `P2`（可以修）

交叉示例：
- `security` × `P0`：SQL 注入、明文存密码
- `bug` × `P1`：特定边界条件下空指针，实际触发概率低
- `performance` × `P2`：循环内多余的对象分配，热点路径才需要改

另外每个发现带 **置信度**（`high` / `medium` / `low`）和**建议动作**（`cs-issue` / `cs-refactor`）。

完整模板见 `reference.md`。

---

## 工作流

### Phase 1：范围收敛

审计不能全仓库盲扫——成本高、噪音大。先帮用户把范围收窄到可执行。

问用户三样（有一样就能起步）：

1. **关键词**："跟 auth / payment / upload 相关的"
2. **模块 / 目录**："`src/services/` 下面"
3. **一段话描述**："最近用户反馈订单页慢，帮我扫一下订单相关代码"

用户描述已清楚直接进 Phase 2。用户说"整个项目都扫" → 推回去——建议先扫最常改的模块或最近出过问题的区域。

收敛后给用户确认：**"扫 `src/services/order/` 和 `src/api/order.ts`，约 12 个文件，看安全 / 性能 / bug 隐患三个维度。范围 OK 吗？"**

### Phase 2：扫描

按用户圈定的维度逐维扫描（用户没指定就全扫 5 维）：

- **bug 隐患**：空值路径、边界条件缺失、竞态条件、错误处理吞异常、类型断言无保护
- **安全**：注入风险、敏感数据暴露、权限校验缺失、不安全依赖
- **性能**：N+1 查询、重复计算、无缓存热点路径、内存泄漏、无分