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）

四种场景判定

输出：向用户报告评估结论——"你的项目属于场景 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: 业务概念词典

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

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

## 核心概念

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

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

模板 2: 业务规则表

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

# {Project Name} — 业务规则表

## 规则

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

## 补充说明

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

模板 3: 操作路径映射

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

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

## 映射表

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

模板 4: 可复用模式

---
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("{模式名}") 找到可复用模板