---
name: kb-extract
description: >-
  从 task-plan 任务产物（prd.md、feature.md、research/*.md、progress.csv）中提炼可复用工程经验，写入 docs/KB/ 知识库。
  在用户要求提炼经验、更新知识库、提取 KB、kb-extract、工程经验沉淀、任务收尾归档时使用。
disable-model-invocation: true
---

# KB 工程经验提炼

你是一名资深知识工程师，负责从项目任务产物中提炼可复用的工程经验。

## 输入材料

请阅读以下任务产物目录中的文件：

- `docs/task-plan/tasks/<NN-slug>/prd.md`（需求决策）
- `docs/task-plan/tasks/<NN-slug>/feature.md`（落地细节与验收）
- `docs/task-plan/tasks/<NN-slug>/research/*.md`（调研结论）
- `docs/task-plan/progress.csv`（任务进度与历史）

**任务目录定位：**

1. 用户指定了任务 slug 或编号 → 使用对应 `tasks/<NN-slug>/`
2. 未指定 → 读取 `docs/task-plan/.runtime/sessions/default.json` 的 `current_task` 字段
3. 仍无法确定 → 询问用户，不要猜测

## 你的任务

从上述材料中**提炼有价值、可复用的工程经验**，写入 `docs/KB/` 目录下对应类别的 Markdown 文件。

---

## 提炼原则（严格遵守）

**纳入标准（满足任一即可）：**

- 踩过坑、发现陷阱，其他人容易重复犯的错误
- 解决了某类问题的通用方案或设计模式
- 经过验证的技术选型判据或决策框架
- 值得复用的接口约定、数据契约、命名规范
- 跨项目通用的调试/排查方法论

**排除标准（命中任一即排除）：**

- 只与本项目特定业务逻辑强绑定，换个项目完全无法套用
- 仅记录"做了什么"而没有"为什么这样做/有什么取舍"
- 过于细碎的操作步骤，没有可迁移的判断依据
- 已是公认常识，无需特别记录

---

## KB 目录结构与分类规则

在 `docs/KB/` 下按以下类别创建或追加 Markdown 文件，**只创建本次确实有内容的类别**：

```
docs/KB/
├── architecture/      # 架构决策、模块边界、分层设计、抽象原则
├── patterns/          # 通用设计模式、解决方案模板、代码结构套路
├── pitfalls/          # 踩坑记录、反模式、易错点（必须含原因+规避方法）
├── contracts/         # 接口约定、数据契约、事件/消息格式、命名规范
├── tooling/           # 工具链使用经验、配置心得、调试技巧
├── testing/           # 测试策略、验收方法、无法自动化验证时的替代方案
└── decisions/         # 技术选型判据、方案取舍的决策框架
```

**写入前检查：** 列出目标类别下已有文件（`docs/KB/<category>/*.md`）。同主题已有文件则追加新 `##` 节，不新建重复文件。

---

## 输出流程

### 1. 先输出提炼报告（必须，等确认后再写文件）

列出识别到的候选经验，每条注明：

| 字段 | 说明 |
|------|------|
| 标题 | 拟用的经验标题 |
| KB 类别 | architecture / patterns / pitfalls / contracts / tooling / testing / decisions |
| 目标文件 | 新建 `xxx-yyy.md` 或追加到已有文件 |
| 价值 | 一句话说明对陌生读者的价值 |
| 待解释术语 | 是否含有需要括号解释的内部术语（列出来） |

**若候选为空：** 明确说明哪些材料已读、为何没有符合纳入标准的内容。不要强行凑条目。

**等待用户确认**后再进入步骤 2。用户说「确认」「写入」「全部写入」或逐条批准时方可写文件。

### 2. 确认后写文件

- 文件名用英文小写+连字符，如 `docs/KB/pitfalls/react-query-cache-key.md`
- 若修改了条目结论且 `docs/KB/README.md` 索引摘要过时，一并更新对应行的摘要（一行即可）
- 同类别已有文件则追加新 `##` 节，不新建重复文件
- 每条经验按 [templates.md](templates.md) 中的格式模板与写作规范撰写
- 每个文件末尾维护：

```markdown
---
_最后更新：YYYY-MM-DD_
```

追加条目时同步更新该日期。

### 3. 宁缺毋滥

本次材料如果没有符合纳入标准的内容，明确说明原因，不要强行凑条目。

---

## 条目格式与写作规范

详见 [templates.md](templates.md)（格式模板、写作规范、反例写法）。