从知识沉淀到 AI 执行:一次本地知识库工作流的 Harness 实践
本文记录了一次本地知识库工作流实践:通过知识分类、置信度、Skill、工作流和 CLI 工程化,把分散资料沉淀为 AI 可调用、可验证、可持续演进的知识底座。
1. 背景与痛点
1.1 当前的"知识"是什么?
在日常研发中,团队的知识分散在这些地方:
这些内容都有价值,但没有被统一治理——它们是资料,不是知识资产。
1.2 知识的痛点
1.3 核心矛盾
团队不缺资料,缺的是一套能把资料转化为知识、把知识转化为 AI 可调用能力的机制。
传统知识库解决的是"存起来"的问题,但真正需要的是:能被找到、能被信任、能被 AI 稳定调用、能持续更新。
2. 我想解决什么问题
简单来说,我不是想做一个"更好看的文档站",而是想解决七件事:统一入口、低摩擦沉淀、代码知识提炼、类型化检索、可信度判断、AI 可调用、工作流闭环。
| 知识太分散怎么办? | ||
| 如何持续沉淀? | ||
| 代码中的知识如何提炼? | ||
| 如何分类检索? | ||
| 如何判断可信? | ||
| 如何让 AI 用? | ||
| 如何进入工作流? |
3. 知识库初识
3.1 知识库长什么样
KBFlow 的知识库就是一个普通的 Git 仓库——不是网站、不是 wiki、不是数据库。仓库里包含正式区(stable/)、草稿区(inbox/)、全局索引、业务配置,每条知识是一个带 YAML frontmatter 的 markdown 文件。
my-kb/
├── stable/ # 正式区,经人工 review 入库
│ ├── seed/ # 按业务模块分目录
│ │ ├── overview.md
│ │ └── constraints/
│ └── water/
├── inbox/ # 草稿区,AI 自由写入
├── INDEX.md # 全局索引
├── kb.config.yaml # 业务配置
选 Git 仓库形态的好处:直接复用版本控制、MR Review、权限管理;本地文件让 AI 工具(Cursor / Claude Code)零延迟读取;通过 kbf link 可以把它 clone 进任意业务仓库当上下文。
3.2 知识库工作流
核心概念速览:
init:初始化知识库仓库骨架
bootstrap:冷启动,从飞书文档+代码仓库批量提炼第一批知识草稿
capture:日常沉淀,随时"记一下"写入草稿区
review:对草稿做格式+事实验证
promote:审查通过后,将知识从草稿区迁入正式区
query:查询业务知识,AI 按置信度决定是否深入验证
revise:修正过期或错误的知识
3.3 典型场景:创建知识库
步骤 1:创建仓库
步骤 2:安装 CLI(示例)
npm install -g @kbflow --registry=http://registry.npm.oa.com/
步骤 3:拉取知识库
git clone 3.4 典型场景:新人快速了解业务
新人接手业务时,不需要逐个翻飞书文档和代码仓库,几步就能开始查询业务知识:
步骤 1:安装 CLI(示例)
npm install -g @kbflow --registry=http://registry.npm.oa.com/
步骤 2:拉取知识库
git clone 之后直接用自然语言按需查询:
- 问"XX 模块是做什么的" → 查到 overview,了解模块全貌
- 问"这个流程涉及哪些仓库" → 查到 map,定位代码入口
- 问"有什么业务限制" → 查到 constraint,了解规则边界
- 问"上次那个问题怎么解决的" → 查到 debug-log,复用已有经验
从"问人→等回复→再问"变成"直接查→有来源→可验证",新人上手周期缩短,老人也不用反复解释。
4. 方案设计与实现
4.1 整体架构
核心理念:AI 负责提议和检索,人类负责事实确认。
AI 的权限止于 inbox/(草稿区),进入 stable/(正式区)必须经人类确认。这保证了知识库不会因为 AI 幻觉而逐渐腐化。
4.2 知识设计
九种知识类型
为什么是 9 类? 基于 MECE 原则(互斥且穷尽),按"这条知识回答什么类型的问题"来划分——描述整体、定义概念、记录现状、约束边界、定位代码、指导操作、记录决策、约定标准、复盘问题。
分类时按决策树判断:
你要记录的知识 →
├── 描述"某个东西是什么"?
│ ├── 整体模块/系统 → overview
│ └── 单个术语/概念 → glossary
├── 描述"当前状态/数据是什么"? → fact
├── 描述"有什么限制/不能做什么"? → constraint
├── 描述"代码在哪/怎么串联"? → map
├── 描述"遇到 X 该怎么操作"? → runbook
├── 描述"当时为什么这样选"? → decision
├── 描述"团队应该遵守什么"? → convention
└── 描述