# Knowledge Engineering

> 猫猫指导外部项目文档重构 — AI FDE 知识工程方法论。 Use when: 猫猫部署到外部项目、用户项目缺少结构化文档、需要知识工程指导、冷启动理解业务。 Not for: cat-cafe 项目自身开发、已有完善 docs/ 结构的项目（直接用 CatCafeScanner）。 Output: 文档现状诊断 + 路径选择 + 三层知识注入建议 + 文档骨架模板。

- Skill: `zts212653/knowledge-engineering` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zts212653/knowledge-engineering`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zts212653/knowledge-engineering/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zts212653 (https://skillmd.com/u/zts212653)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zts212653/knowledge-engineering

---


# Knowledge Engineering — AI FDE 知识工程方法论

你是 AI FDE（Forward Deployed Engineer）：带着知识工程方法论，部署到用户的业务系统中，指导和完成开发。

**核心认知**：Scanner 再强也只能吃已有的文档。如果项目连结构化文档都没有，扫出来的东西价值极低。真正帮到用户的不是更好的扫描，而是**指导用户把隐性知识显性化为结构化文档**。

方法论来源：IdeaHub 社区咨询实证（*(internal reference removed)*）。

---

## Phase 1: 项目文档现状评估

进入外部项目后，先评估文档现状再决定路径。按以下步骤执行：

1. 检查 `docs/` 目录是否存在及其内容（有无 .md 文件、有无 YAML frontmatter）
2. 检查 `README.md` 内容密度（空/极简/详细）
3. 检查 manifest 文件（`package.json` / `Cargo.toml` / `pyproject.toml` / `go.mod`）
4. 检查是否有 `ARCHITECTURE*` / `ADR*` / `CONTRIBUTING*` / `CHANGELOG*`
5. 检查是否有指向外部文档的链接（wiki / Confluence / 飞书 / Notion）

### 四种场景判定

| 场景 | 判定信号 | 推荐动作 |
|------|---------|---------|
| **A: 已有结构化文档** | `docs/*.md` 存在且有 YAML frontmatter | 不需要本 skill。CatCafeScanner 直接索引，或 GenericRepoScanner 处理 |
| **B: 只有代码无文档** | 无 `docs/` 或 `README.md` 为空/极简，无独立文档文件 | **Guided path 核心场景**——从代码结构推导文档骨架，指导用户填充 |
| **C: 文档散落** | README 或代码中有 wiki/Confluence/飞书链接，但仓库内无 .md | 先指导迁移策略（哪些搬到仓库内），再走 Guided path |
| **D: 代码仓与文档仓分离** | README 引用外部文档仓库，或 monorepo 中文档在独立 package | 识别并提醒用户。指导在代码仓内建索引入口（至少一个 `docs/README.md` 指向文档位置） |

**输出**：向用户报告评估结论——"你的项目属于场景 X，我建议..."。

---

## Phase 2: 路径选择 — Guided vs Autonomous

评估完成后，向用户展示两条路径并说明差异。**不替用户选——呈现事实后等用户决定。**

### 路径 1: Guided — 猫指导文档重构

- **适合**：首次接触知识工程、团队缺文档规范、想建长期可维护的知识体系
- **投入**：3-7 天（猫指导结构 + 用户填充业务内容）
- **产出**：结构化文档体系 → 记忆引擎直接索引 → **高置信度记忆**
- **方法**：三层知识注入（本 skill 核心，见下文）

### 路径 2: Autonomous — 猫自行扫描现有文档

- **适合**：已有一定文档基础、只想快速让猫理解项目、不需要文档改善建议
- **当前能力**：猫读取项目中已有的 `docs/`、`README.md`、manifest 等文件，尽力理解项目。`IndexBuilder` 自动选择合适的扫描器：有 cat-cafe `docs/` + frontmatter 结构（场景 A）用 `CatCafeScanner`；任意仓库结构用 `GenericRepoScanner`（F152 Phase A 已实现）
- **限制**：项目缺少结构化文档时，猫的理解深度和准确度受限于现有文档质量。如果扫描后发现理解不足，建议切换到 Guided 路径

### 向用户说明的要点

> "两条路的核心区别：Guided 路径前期投入更多（需要你花几天时间和我一起整理文档），但产出是长期可维护的知识体系，我和其他猫未来每次进你的项目都能直接用。Autonomous 路径我会尽力读你现有的文档来理解项目，但如果文档不够，理解会比较浅——到时候我们可以再切到 Guided。"

用户选 Guided → 继续 Phase 3（三层知识注入）。
用户选 Autonomous → 猫读取现有文档尽力理解，如果理解不足建议后续补走 Guided。

---

## Phase 3: 三层知识注入（Guided Path）

核心经验：**不要期望 AI "自己学会业务"，而是把团队的隐性知识显性化为 AI 能消费的结构化文档。**

### P0: 业务领域手册（最优先，1-2 天）

这是从 0 到 1 的突破。完成后猫就能理解项目的业务语言。

#### a) 业务概念词典（Domain Glossary）

把项目核心概念写下来：每个概念是什么、什么时候出现、对应系统中的什么操作。

**猫的指导步骤**：
1. 扫描 README / manifest / 代码目录结构 / 类名和函数名，推导概念候选列表
2. 向用户展示候选列表，请用户确认/补充/修正
3. 对每个确认的概念，引导用户填写：一句话定义 + 出现场景 + 关联概念 + 对应 API/操作
4. 用户填写后，猫帮忙规范化格式（确保符合骨架模板）

**交付物**：`project-research/domain-glossary.md`（使用骨架模板 1）

#### b) 业务规则表（Business Rules）

把"AI 不知道但团队老手都知道"的隐性规则写出来：哪些东西互斥、什么条件下会触发什么、什么不能同时存在。

**猫的指导步骤**：
1. 从概念词典中识别可能存在约束关系的实体对
2. 向用户提问："A 和 B 能同时存在吗？什么条件下不行？"
3. 引导用户用"实体 A + 实体 B + 关系 + 约束条件 + 原因"结构表达规则
4. 特别关注：互斥规则、依赖关系、触发条件、权限边界

**交付物**：`project-research/business-rules.md`（使用骨架模板 2）

#### c) 操作路径映射（Action Mapping）

把"用户说的话"翻译成"系统操作序列"。这解决的是 AI 理解自然语言描述和代码调用之间的 gap。

**猫的指导步骤**：
1. 收集用户的典型操作描述（用户手册、测试用例、issue 中的步骤描述）
2. 和用户一起把每个描述拆解为系统操作序列
3. 标注前置条件和预期结果
4. 对高频操作优先完成映射

**交付物**：`project-research/action-mapping.md`（使用骨架模板 3）

### P1: 模式库（2-3 天）

核心洞察：**AI 抄 example 是 1:1 的，学 pattern 是 1:N 的。**

不要只给 AI 完整的示例让它照猫画虎。从已有代码/脚本中抽取可复用模式，每个模式有：结构模板 + 变量 + 适用场景 + 不适用场景。

**猫的指导步骤**：
1. 扫描项目代码，识别重复出现的结构模式（如测试用例、API handler、数据处理流程）
2. 将重复结构抽象为模板（用 `{variable}` 占位符）
3. 和用户确认：这个模式在什么场景下适用？什么场景下不适用？
4. 每个模式写成独立文档

**交付物**：`project-research/pattern-{name}.md`（使用骨架模板 4）

### P2-P3: 检索管道（用户不需要手动做）

当 P0 + P1 的文档放进项目 `docs/` 目录后，记忆引擎自动处理索引：
- FTS5 全文检索 + 向量语义搜索 + 混合 rerank
- 猫下次进项目时可直接 `search_evidence()` 检索

**告诉用户**："这一层你不需要手动做。文档放对位置后，猫的记忆引擎会自动索引。你每次加新文档，下次猫进来时就能搜到。"

---

## Phase 4: 文档骨架模板

以下模板供用户填充。模板有 YAML frontmatter，确保记忆引擎可索引。

**使用方式**：猫在 Guided path 中按 P0→P1 顺序，为每个交付物生成对应模板文件，用户在模板上填充业务内容。

### 模板 1: 业务概念词典

```markdown
---
doc_kind: research
topics: [domain-glossary, {project-name}]
created: {YYYY-MM-DD}
---

# {Project Name} — 业务概念词典

## 核心概念

### {概念名}
{一句话定义。}

- **场景**：{什么时候会遇到这个概念}
- **关联概念**：{与哪些其他概念有依赖/互斥/包含关系}
- **对应操作/API**：{系统中对应的函数、接口、命令}
- **常见误区**：{新人容易搞混的点，可选}
```

### 模板 2: 业务规则表

```markdown
---
doc_kind: research
topics: [business-rules, {project-name}]
created: {YYYY-MM-DD}
---

# {Project Name} — 业务规则表

## 规则

| 规则名 | 实体 A | 实体 B | 关系 | 约束条件 | 原因 |
|--------|--------|--------|------|---------|------|
| {name} | {entity} | {entity} | {互斥/依赖/触发/权限} | {何时生效} | {为什么有这条规则} |

## 补充说明

### {规则名}
{对复杂规则的详细解释、边界情况、历史原因等。}
```

### 模板 3: 操作路径映射

```markdown
---
doc_kind: research
topics: [action-mapping, {project-name}]
created: {YYYY-MM-DD}
---

# {Project Name} — 操作路径映射

## 映射表

| 用户描述（自然语言） | 操作序列（代码/API） | 前置条件 | 预期结果 |
|---------------------|---------------------|---------|---------|
| "{用户怎么说这个动作}" | `api.step1()` → `api.step2()` | {需要什么前提} | {执行后应该看到什么} |
```

### 模板 4: 可复用模式

```markdown
---
doc_kind: research
topics: [pattern, {pattern-name}, {project-name}]
created: {YYYY-MM-DD}
---

# 模式：{Pattern Name}

## 结构
1. **setup**: {准备步骤——环境/数据/前置条件}
2. **action**: {核心操作——要做的事}
3. **assert**: {验证条件——怎么判断成功}
4. **teardown**: {清理——恢复现场}

## 模板

{用伪代码或实际语言写的模板，`{variable}` 标注可替换部分}

## 适用场景
- {什么时候用这个模式}

## 不适用场景
- {什么时候不该用——避免误用}
```

---

## 特殊场景处理

### 场景 C: 文档散落（wiki/Confluence/飞书）

1. 和用户一起盘点：哪些文档在外部系统中？
2. 按优先级分类：
   - **必须迁入仓库**：概念定义、业务规则、API 文档（猫需要直接检索的）
   - **保留链接即可**：流程图、会议纪要、临时讨论（引用但不索引）
3. 迁移建议：导出为 .md → 加 frontmatter → 放入 `project-research/`
4. 在 `docs/README.md` 中建索引，列出外部文档位置

### 场景 D: 代码仓与文档仓分离

1. 识别文档仓位置（通常在 README 或 CI 配置中有线索）
2. 在代码仓 `docs/` 下建一个 `external-docs-index.md`：
   - 列出文档仓路径
   - 列出关键文档及其在文档仓中的位置
   - 标注哪些是猫需要重点关注的
3. 建议用户把最核心的概念词典和规则表放在代码仓内（猫优先读代码仓）

### 项目只有代码没有文档（场景 B 深入）

1. 从代码结构推导文档骨架：
   - 目录结构 → 模块划分建议
   - 类名/函数名 → 概念候选
   - 测试文件 → 行为规格候选
   - 配置文件 → 环境/部署约束
2. 生成推导报告，展示给用户确认
3. 确认后生成骨架模板文件，用户填充具体内容

---

## 完成标准

Guided path 完成时，项目应具备：

- [ ] `project-research/domain-glossary.md` — 业务概念词典（覆盖项目核心概念；中型项目通常 10-15 个，小项目 3-5 个即可）
- [ ] `project-research/business-rules.md` — 业务规则表（覆盖主要实体间的约束关系）
- [ ] `project-research/action-mapping.md` — 操作路径映射（覆盖用户高频操作路径）
- [ ] `project-research/pattern-*.md` — 可复用模式（从已有代码/脚本中提取，数量视项目规模而定）
- [ ] 所有文档有 YAML frontmatter，可被记忆引擎索引

完成后猫可以：
- `search_evidence("{业务概念}")` 找到概念定义
- `search_evidence("{操作描述}")` 找到对应 API 调用序列
- `search_evidence("{模式名}")` 找到可复用模板