knowledge-distiller

Knowledge Distiller

用于把“代码里的隐性知识”提炼成可读、可维护、可复用的知识文档。

适用场景

• 用户说“帮我理解这个模块/流程/架构为什么这么设计”
• 用户说“沉淀某个功能的实现规律、约束和演进思路”
• 用户说“生成知识库文档，不要贴代码实现细节”

目标产物

在 /docs/kb/ 生成一个或多个 Markdown 文档，核心内容是：

• 事实（Facts）: 可验证、可定位的客观信息
• 模式（Patterns）: 重复出现的实现方式、组织方式、协作方式
• 决策链条（Decision Chain）: 背景 -> 约束 -> 选择 -> 取舍 -> 结果

文档必须以自然语言表达，不输出大段代码。

工作流

1. 明确提炼范围

   • 从用户需求中提取主题、边界、受众
   • 定义输出粒度：总览文档或专题文档集合

2. 检索代码证据

   • 优先读取：README.md、CLAUDE.md、配置文件、入口文件、关键模块目录
   • 使用搜索定位：模块名、命令名、技能名、配置键、流程关键词
   • 每个关键结论至少关联 1 个证据来源文件

3. 提炼知识结构

   • 事实：谁在做什么、放在哪里、如何触发
   • 模式：可复用实践、统一约定、命名/分层/流程习惯
   • 决策链条：为什么采用当前方案、替代方案为何未选

4. 生成知识文档

   • 写入 /docs/kb/，命名建议：
     • topic-overview.md
     • topic-patterns.md
     • topic-decision-chain.md
   • 同步更新 /docs/kb/README.md 索引

5. 质量校验

   • 不贴实现代码，避免变成源码复制
   • 结论可追溯：每个章节都能映射到证据文件
   • 语言面向人类读者，强调“可理解”和“可行动”

推荐文档模板

# <主题名称>

## 1. 背景与范围

## 2. 关键事实
- 事实 1
- 事实 2

## 3. 稳定模式
- 模式 1
- 模式 2

## 4. 决策链条
1. 背景
2. 约束
3. 备选方案
4. 最终选择
5. 结果与影响

## 5. 实践建议

## 6. 证据来源
- path/to/fileA
- path/to/fileB

输出规则

• 输出内容以中文自然语言为主
• 文件统一放在 /docs/kb/
• 允许一次生成多篇文档，但必须有清晰索引
• 若证据不足，先标注“待确认”，不得臆断

示例指令

• “提炼插件架构知识，输出 1 篇总览 + 1 篇决策链文档”
• “分析 hooks 机制，提取模式和风险，沉淀到 docs/kb”
• “围绕 skills 目录做知识地图，不要包含代码片段”