从知识沉淀到 AI 执行:一次本地知识库工作流的 Harness 实践

本文记录了一次本地知识库工作流实践:通过知识分类、置信度、Skill、工作流和 CLI 工程化,把分散资料沉淀为 AI 可调用、可验证、可持续演进的知识底座。

1. 背景与痛点

1.1 当前的"知识"是什么?

在日常研发中,团队的知识分散在这些地方:

载体
示例
飞书文档
需求文档、技术方案、会议纪要
代码仓库
业务逻辑、接口实现、配置规则
聊天记录
口头确认的结论、临时讨论的方案
个人记忆
踩坑经验、历史决策的背景
收藏夹/笔记
零散的片段、未整理的素材

这些内容都有价值,但没有被统一治理——它们是资料,不是知识资产。

1.2 知识的痛点

1.3 核心矛盾

团队不缺资料,缺的是一套能把资料转化为知识、把知识转化为 AI 可调用能力的机制。

传统知识库解决的是"存起来"的问题,但真正需要的是:能被找到、能被信任、能被 AI 稳定调用、能持续更新。

2. 我想解决什么问题

简单来说,我不是想做一个"更好看的文档站",而是想解决七件事:统一入口、低摩擦沉淀、代码知识提炼、类型化检索、可信度判断、AI 可调用、工作流闭环。

问题
传统做法
期望做法
知识太分散怎么办?
同一个业务的知识散落在飞书文档、多个代码仓库、聊天记录、个人笔记里,没有统一入口
① 以业务为维度,统一收口到一个 Git 仓库 ② 按业务模块组织目录 ③ 条目关联到具体代码仓库/飞书文档/文件路径 ④ 一个入口查到所有相关知识
如何持续沉淀?
写方案文档才算沉淀,成本高(开文档、想标题、选目录),日常结论停留在聊天和记忆里
① 对话中"记一下"就能触发 ② AI 自动整理格式、分类、补来源 ③ 摩擦足够低,让沉淀成为日常习惯
代码中的知识如何提炼?
业务规则散落在多个仓库多个文件,代码表达的是"实现"而非"意图"
① 冷启动批量扫描代码+飞书,AI 提炼业务结论 ② 建立代码地图标注跨仓链路 ③ 一次提炼持续复用
如何分类检索?
文件夹层级 + 关键词搜索,标题不规范就搜不到
① 按知识类型路由检索 ② 问"最多操作几次"查 constraint ③ 问"怎么设计的"查 decision
如何判断可信?
搜到了不知道谁写的、什么时候写的、是否过期
① 每条带来源、置信度、验证时间、确认人 ② 过期自动降级 ③ 置信度不够时自动触发验证
如何让 AI 用?
AI 没有业务上下文,每次手动粘贴背景
① 结构化存储(YAML frontmatter + 正文) ② Skill 协议按需加载,先索引再条目 ③ 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 

之后直接用自然语言按需查询:

  1. 问"XX 模块是做什么的" → 查到 overview,了解模块全貌
  2. 问"这个流程涉及哪些仓库" → 查到 map,定位代码入口
  3. 问"有什么业务限制" → 查到 constraint,了解规则边界
  4. 问"上次那个问题怎么解决的" → 查到 debug-log,复用已有经验

从"问人→等回复→再问"变成"直接查→有来源→可验证",新人上手周期缩短,老人也不用反复解释。

4. 方案设计与实现

4.1 整体架构

核心理念:AI 负责提议和检索,人类负责事实确认。

AI 的权限止于 inbox/(草稿区),进入 stable/(正式区)必须经人类确认。这保证了知识库不会因为 AI 幻觉而逐渐腐化。

4.2 知识设计

九种知识类型

为什么是 9 类? 基于 MECE 原则(互斥且穷尽),按"这条知识回答什么类型的问题"来划分——描述整体、定义概念、记录现状、约束边界、定位代码、指导操作、记录决策、约定标准、复盘问题。

类型
回答的问题
说明
overview
这块整体是什么?
模块、业务、系统、领域的总览
glossary
这个术语是什么意思?
术语、概念、缩写、定义
fact
当前真实状态是什么?
当前配置、接口、表结构、字段定义
constraint
有什么限制/约束?
业务规则、系统限制、权限约束、数量限制
map
去哪里找?结构在哪?
代码地图、模块入口、调用链路、文档索引
runbook
遇到某场景怎么操作?
操作步骤、排查步骤、应急处理流程
decision
当时为什么这么选?
背景、方案、取舍、决策理由
convention
以后应该遵守什么标准?
规范、约定、质量标准、命名标准
debug-log
之前发生了什么问题?
故障、事故、踩坑、复盘、排查记录

分类时按决策树判断:

你要记录的知识 →
├── 描述"某个东西是什么"?
│   ├── 整体模块/系统 → overview
│   └── 单个术语/概念 → glossary
├── 描述"当前状态/数据是什么"? → fact
├── 描述"有什么限制/不能做什么"? → constraint
├── 描述"代码在哪/怎么串联"? → map
├── 描述"遇到 X 该怎么操作"? → runbook
├── 描述"当时为什么这样选"? → decision
├── 描述"团队应该遵守什么"? → convention
└── 描述
— 以上为试看内容(约 40%),开通会员后阅读全文 —