# 知识编写规范

> 本文档定义 security-analysis 体系的知识库编写质量标准。
> 不依赖主 prompt 上下文即可理解。

---

## 1. 知识库的目的

知识库的目的是**让 AI 下次遇到同类情况时，不需要从零摸索**。

判断一条知识是否有价值，唯一的标尺是：**如果知识库中没有这条知识，AI 会不会卡住？**

- 会卡住（花了多轮对话才找到方向）→ 高价值，必须沉淀
- 不会卡住（AI 自己就能推理出来）→ 不需要沉淀

---

## 2. 知识编写原则

### 2.1 写给使用者，不是写给作者

**禁止**：
- ❌ "经验来源: SnailNet CTF" — 这是写给作者的备忘，使用者不关心
- ❌ "详细分析见 docs/解题报告/Web/xxx-writeup.md" — 知识库不应依赖外部文件路径
- ❌ 按时间顺序记录分析过程 — 知识库不是分析日志

**应该**：
- ✅ 写"什么场景、怎么识别、怎么利用"
- ✅ 自包含：不依赖主 prompt 上下文或其他文件即可理解
- ✅ 按主题组织（攻击技术、防御方法、检查流程），不按时间线

### 2.2 具体胜过抽象

**禁止**：
- ❌ "可以利用 PHP 配置绕过 CSP" — 太抽象，无法操作
- ❌ "发送大量参数触发错误" — 多少算大量？什么错误？

**应该**：
- ✅ "PHP `max_input_vars` 默认 1000，发送 >1000 个参数触发 WARNING"
- ✅ 附带具体的参数计数公式：`总参数 = GET + POST + Cookie`
- ✅ 附带可操作的检查步骤和 payload 示例

### 2.3 场景驱动，不是知识驱动

每条知识必须回答三个问题：
1. **什么时候用？**（触发条件）
2. **怎么检查？**（识别/验证方法）
3. **怎么利用？**（具体操作步骤或 payload）

如果写不出"什么时候用"，这条知识就不应该沉淀——它在等待一个还不存在的场景。

### 2.4 不重复已有知识

沉淀前检查：
- 同一技术是否已在其他知识库文件中描述？
- 如果是，是补充新角度还是纯重复？
- 引用已有内容（`详见 $AGENT_DIR/knowledge-base/xxx.md`），不重写

---

## 3. 知识质量检查清单

每条新增知识必须通过以下检查：

### 3.1 准确性

- [ ] 技术描述是否正确？（不是"大概对"，而是精确）
- [ ] 代码/payload 示例是否可执行？（不能有语法错误）
- [ ] 默认值、版本号等具体数据是否准确？
- [ ] 是否有遗漏的前提条件？

### 3.2 完整性

- [ ] 读者能否仅凭这条知识完成操作？（不需要再去搜索）
- [ ] 是否涵盖了主要变体和边界情况？
- [ ] 是否列出了常见的失败原因和对应的排查方向？

### 3.3 一致性

- [ ] 术语是否与现有知识库一致？
- [ ] 跨文件引用路径是否使用 `$AGENT_DIR` / `$SHARED_DIR` 变量？
- [ ] 不会与已有知识产生矛盾？

### 3.4 可操作性

- [ ] 检查步骤是否具体到可以直接执行？
- [ ] payload 是否完整、可直接使用？
- [ ] 是否说明了"成功时看到什么 / 失败时看到什么"？

---

## 4. 知识组织结构

### 4.1 知识库文件的定位

| 文件类型 | 定位 | 读者何时读它 |
|---------|------|-------------|
| 方法论（如 web-methodology.md） | "什么时候做什么" — 分析流程和决策树 | 分析规划阶段 |
| 漏洞模式（如 web-vulnerabilities.md） | "有什么漏洞、怎么识别、怎么利用" — 速查表 | 识别到潜在漏洞时 |
| 专题深度（如 csp-bypass.md、cache-poisoning.md） | "某个技术领域的完整参考" — 深度指南 | 遇到特定技术障碍时 |
| 工具参考（如 idapython-conventions.md） | "怎么用某个工具" — 编码规范和 API | 编写脚本时 |

### 4.2 知识归属判定

- **通用 vs 专属**：如果多个 agent 都可能用到 → 放 `$SHARED_DIR/knowledge-base/`；只有特定场景 → 放 `$AGENT_DIR/knowledge-base/`
- **新文件 vs 补充现有文件**：新主题且预估 >80 行 → 新文件；现有主题的补充 → 追加到现有文件的对应章节
- **不确定时先放现有文件**：不要轻易创建新文件，文件数膨胀会增加索引维护成本

### 4.3 文件内结构

每个知识库文件应包含：

```
# 标题 — 一句话定位

> 一句话说明这是什么、什么时候用。不依赖主 prompt 上下文即可理解。

---

## 1. [主题 1]
### [子主题]
- 场景 / 触发条件
- 检查方法（可操作步骤）
- 利用方法（附带 payload 示例）
- 常见失败原因

## 2. [主题 2]
...
```

---

## 5. 常见错误模式

以下是知识沉淀中容易犯的错误，每次写完后对照检查：

| 错误 | 正确做法 |
|------|---------|
| 写"经验来源"或引用解题报告路径 | 写技术内容本身，不标注来源 |
| 只写结论不写过程（"可以绕过 CSP"） | 写具体的操作步骤和 payload |
| 照搬 writeup 的叙述顺序 | 按主题重组：场景 → 检查 → 利用 → 排错 |
| 一个知识点散布在多个文件中 | 收口到一个文件，其他文件引用 |
| 写了只有特定 CTF 题才适用的知识 | 提炼通用模式，去掉题目特有细节 |
| 代码示例有语法错误或用错函数 | 写完后验证代码示例可执行 |
| 只写"是什么"不写"怎么用" | 每条知识必须有可操作的检查/利用步骤 |
| 知识过于偏科（只基于一道题） | 沉淀后检查覆盖度：是否遗漏其他常见场景？ |
