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

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

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

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

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

1.2 知识的痛点

1.3 核心矛盾

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

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

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

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.1 整体架构

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

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

4.2 知识设计

九种知识类型

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

分类时按决策树判断：

你要记录的知识 →
├── 描述"某个东西是什么"？
│   ├── 整体模块/系统 → overview
│   └── 单个术语/概念 → glossary
├── 描述"当前状态/数据是什么"？ → fact
├── 描述"有什么限制/不能做什么"？ → constraint
├── 描述"代码在哪/怎么串联"？ → map
├── 描述"遇到 X 该怎么操作"？ → runbook
├── 描述"当时为什么这样选"？ → decision
├── 描述"团队应该遵守什么"？ → convention
└── 描述"之前出过什么问题"？ → debug-log

类型不只是标签，而是检索的路由依据。 用户问"每天最多操作几次"，AI 优先检索 constraint 类型条目，而不是全文搜索碰运气。

结构化元数据

每条知识都有 YAML frontmatter，记录来源、置信度、验证时间、确认人：

---
id: BIZ-CST-042
title: 每日购买商品次数上限为 3 次
entry_type: constraint
confidence: high
last_verified: 2025-05-10
confirmed_by: @zhangsan
sources:
  - type: gitlab
    repo: rewards-service
    path: src/rules/water.go:47
  - type: feishu
    url: https://xxx.feishu.cn/docx/xxx
tags: [seed, water, limit]
---

置信度三档

置信度不是静态的——超过 stale_after_days 未重新验证会自动降级，查询时触发重新验证后可恢复。

4.3 工作流与 Skill 设计：Harness Engineering

设计思想

这套工作流的设计思想来自 Harness Engineering。

什么是 Harness？ 不改 AI 本身，而是给 AI 搭建一套外部运行环境——包括知识、规则、流程、模板、约束。Harness一词来自马具——缰绳、马鞍、嚼子——这是一套引导强大但不可预测的动物的完整装备。驾驭工程不是去削弱 AI 的能力，而是为它打造一套黄金缰绳，让它跑得又快又稳。

参考：https://www.runoob.com/ai-agent/harness-engineering.html

核心思路：AI 的能力上限取决于你给它的支架质量。

传统做法是写一段 prompt 然后期望 AI 表现好——这相当于"裸跑"。Harness Engineering 的做法是把知识、规则、流程、约束都外化成文件，AI 按协议加载和执行。Prompt 会漂移，但文件协议是稳定的。

具体到 本工作流，Harness 由五层组成：

七大工作流

有了这套支架，七大工作流形成闭环——知识越用越完善：

关键设计：query 时如果置信度是 medium/low，AI 会自动执行 fallback（读代码、拉飞书文档验证），而不是丢一句"建议你去看一下代码"。这是和传统知识库最大的区别。

Skill：工作流的执行单元

每个工作流通过一个 Skill 文件（skills/）来实现。Skill 是从临时 Prompt 升级而来的稳定执行规则——Prompt 每次写法不同容易漂移，Skill 是固定协议，产出稳定。

每个 Skill 遵循统一模板结构：

Purpose        - 这个 Skill 做什么
Inputs         - 需要什么输入（用户输入 + 配置 + 知识）
Preconditions  - 执行前必须满足什么条件
Invariants     - 执行过程中不能违反的约束
Flow           - 具体步骤（核心）
Outputs        - 产出什么、写到哪里
Failure Modes  - 遇到异常怎么处理
Completion     - 怎么判断做完了

同时有一个总入口 Skill（SKILL.md）负责统一调度：接收用户意图 → 路由到对应工作流 Skill → 约束全局行为（权限边界、反幻觉、来源要求）。

4.4 工程化处理

通过 CLI 工具 kbf 实现框架的分发和维护。

安装：

# 全局安装（推荐）（示例）
npm install -g @kbflow --registry=http://registry.npm.oa.com/

# 或通过 npx 直接使用（无需安装）
npx --registry=http://registry.npm.oa.com/ @kbflow init

命令列表：

kbf init      # 在 git 仓库初始化 KB 结构
kbf setup     # 全局安装框架到 ~/.kbf/，含 IDE 适配器
kbf link# 在业务仓库引入知识库（clone 到 .knowledge/）
kbf validate  # 检查 KB 健康状态
kbf upgrade   # 一键升级到最新版

kbf link跨仓共享：在业务代码仓库执行 kbf link，将团队知识库 clone 到 .knowledge/ 目录。写代码时可以直接询问业务规则，AI 会优先结合 .knowledge/ 中的知识库上下文进行回答。多个业务仓库可 link 同一个 KB，知识统一管理。

CLI 与 AI 的职责边界：

设计理由：机器做确定性工作，AI 做需要判断的工作。两者通过文件协议（kb.config.yaml、SKILL.md、conventions.md）对接。

5.1 从 Prompt 到 Harness：把 AI 能力工程化

与其花精力调 prompt 期望 AI 表现好，不如把精力放在搭建 AI 运行的外部环境。

关键洞察：Prompt 会漂移，文件协议是稳定的。 规则外化成文件后，AI 每次加载同一套协议，产出一致性大幅提升。这就是 Harness Engineering 的核心——不是让 AI 更聪明，而是让 AI 跑在更好的轨道上。

5.2 从全文搜索到渐进式加载：降低上下文噪音

传统做法是把整个文档丢给 AI；KBFlow 的做法是按需逐层深入，像漏斗一样过滤：

好处：节省 token、按需验证、发现缺口时自动建议沉淀。不是一次性灌全量，而是逐层确认够用了就停。

5.3 从静态文档到置信度机制：让知识可被信任

传统文档没有"保质期"概念；KBFlow 给每条知识加上证据状态，并且让它动态流转：

核心区别：medium/low 时 AI 自动执行验证，而不是推给用户。 不确定时自动深入验证，这是"执行型知识库"和"展示型知识库"的根本分界线。

5.4 从 AI 生成到人类确认：避免知识库被幻觉污染

AI 可以高效产出，但不能无限制地写入正式知识。KBFlow 设计了四道质量关卡：

同时 AI 在回答业务问题前必须过自检清单：信息是从 KB 读到的还是编的？代码是真的读了还是只给了路径？来源填全了吗？过期了吗？没找到来源就说"KB 暂无确认条目"，不编。

5.5 从一次性沉淀到闭环演进：让知识越用越完善

知识库最怕"写完就死了"。KBFlow 的七大工作流形成飞轮——每次使用都可能让知识库变得更好：

这套系统不是先画完架构图再实现，而是从一个最小可验证能力开始：先让 AI 能稳定沉淀一条知识，再逐步扩展到查询、审查、入库和工程化分发。

核心方法论：先跑通一个点，再连成一条线。

具体过程：

1. 先搭建单个 Skill：从 capture-flow 开始，定义"沉淀一条知识"的完整规则
2. 用 Skill 产出内容：真的去沉淀几条业务知识，看 AI 输出是否符合预期
3. 通过真实结果验证：如果 AI 写出的条目缺来源、格式不对、幻觉严重，就修改 Skill 规则
4. 稳定后迁移到工作流：capture 稳定后，再搭 query、review、promote，逐步串联
5. 最后 CLI 工程化：当工作流验证通过，才做 npm 包、分发、IDE 适配器

关键心得：不要一开始设计全套系统。 先解决一个具体问题（"怎么让 AI 帮我记一条知识"），验证有效后再扩展。

7.1 价值

搭建这套知识工作流后带来的核心收益：

7.2 总结

知识库不是终点，能被 AI 稳定调用和执行，才是知识真正进入工作流的开始。

AI 工作流的稳定性，不只取决于模型本身，更取决于外部上下文、执行规则、质量门槛和反馈机制。知识库真正有价值的地方，不是把内容存起来，而是让它成为 AI 每次执行时可依赖的底座。

一套好的知识工作流做到的事情是：让下次遇到同样问题的人，能因此节省 30 分钟。