Harness不是目的，知识才是护城河 —— 一个AI工程交付团队的知识沉淀实践¶

Ch04.025 Harness不是目的，知识才是护城河 —— 一个AI工程交付团队的知识沉淀实践¶

📊 Level ⭐⭐ | 34.4KB | entities/harness不是目的知识才是护城河-一个ai工程交付团队的知识沉淀实践.md

核心论点¶

本文的核心论断是：Harness Engineering 的最终目的不是工作流本身，而是团队知识的沉淀。工作流是管道，知识是流过管道的活水。模型会迭代，工具链会更新，工作流会重构，但团队在特定业务领域积累的领域模型、架构决策、最佳实践、已知陷阱、业务流程——这些知识是永恒的护城河。

Skill、Agent、工具链会随模型迭代更新，但领域知识是永恒的。

Harness Engineering 三支柱与知识的位置¶

Harness Engineering 的理论框架可归结为三个支柱：上下文工程、架构约束、持续治理。其中"上下文工程"包含知识检索注入和长/短期记忆，"持续治理"包含知识生命周期和自动衰减。这意味着知识管理本身就是 Harness Engineering 的核心能力，而不是附属品。三大标志性实践的对比： | 实践方 | 核心关注 | 关键动作 | |---|---|---| | OpenAI — Codex | 人机交互协议 | 零手写代码，通过精确的指令协议驾驭 Agent | | Cursor — Self-Driving | 多 Agent 协同 | 背景 Agent 自动检测冲突并运行测试 | | Anthropic — Claude Code | 长时运行稳定性 | 多层记忆系统 + CLAUDE.md 约束 |

核心认知：为什么知识沉淀比工作流更重要¶

3.1 工作流是"可替换的"，知识是"可累积的"¶

今天用 16 阶段状态机编排工作流，明天可能用图结构 DAG 编排。Agent 的调度模式从串行到并行到分层级联，变化很快。但团队积累的知识——比如"广告预算扣减在高并发下会超扣，需用 Redis+Lua 保证原子性"——这条知识不管工作流怎么变，都是有价值的。

3.2 没有知识沉淀的工作流是"一次性"的¶

团队搭了很复杂的 Agent 工作流，每次需求都跑一遍全流程，但每次都是从零开始。上一次踩过的坑，下一次照踩不误。这就是没有知识闭环的工作流——投入了工程成本搭建工具链，却没有让工具链变得越来越聪明。

3.3 知识是团队的"复利资产"¶

知识分为三类：散点型知识（孤立的事实）、因果型知识（A 导致 B 的推理链）、时空型知识（特定场景和时间窗口下才成立的经验）。越是高阶的知识，越难以从模型中获得，越依赖团队的实践积累。当知识库有成百上千条 proven（经过多项目验证）的知识条目时，新来的成员、新启动的项目，都能"站在前人肩上"。这就是知识的复利效应。

知识分层架构：五层存储 × 五种类型 × 三级成熟度¶

4.1 知识体系的三个维度¶

维度	回答的问题	定义
存储层（在哪）	知识存在哪里？	Layer 0-P 0-T 1 2 3 — 从个人到团队到项目
知识类型（是什么）	知识描述的是什么？	model decision guideline pitfall process
成熟度（多可信）	知识经过多少验证？	draft → verified → proven

4.2 五层存储架构¶

层级	说明	特性
Layer 0-P	个人偏好 (~/.ai-team/)	纯本地，不共享
Layer 0-T	团队约定 (team-conventions/)	团队级，Git 共享
Layer 1	技术知识 (tech-wiki/)	团队级，跨项目
Layer 2	业务知识 (biz-wiki/{domain}/)	团队级，按领域
Layer 3	项目知识 (docs/knowledge/)	项目级，随项目走
关键设计：知识可以"向上提升"。Layer 3 的项目知识，如果被判定为跨项目通用，会自动提升到 Layer 1 或 Layer 2。

4.3 五种知识类型¶

遵循 MECE（互斥且完全穷尽）原则： | 类型 | 定义 | 示例 | |---|---|---| | model | 实体定义、数据结构、关系图 | "广告计划包含预算/出价/投放时段三个核心字段" | | decision | 技术选型、架构决策及理由 | "选择事件驱动而非 RPC 同步" | | guideline | 推荐做法 (recommend) 或禁止做法 (avoid) | recommend: "公共模块变更后的兼容性检查清单" | | pitfall | 已知风险、故障模式、排查步骤 | "广告预算扣减在高并发下会超扣" | | process | 业务流程、状态机、操作步骤 | "广告审核：提交→机审→人审→上线" |

4.4 三级成熟度 + 自动衰减¶

知识有生命周期：

draft（新提取，单一来源）
verified（单项目验证）——在 1 个工作流中被成功引用
proven（成熟/可信赖）——在 ≥2 个不同项目中被验证 自动衰减机制： | 触发条件 | 衰减动作 | |---|---| | proven 条目 12 个月未被引用 | 降级为 verified | | verified 条目 6 个月未被引用 | 降级为 draft | | draft 条目持续未引用 + Lint 标记 | 归档，移出活跃索引 |

团队知识库：独立 Git 仓库与共建共享¶

5.1 独立 Git 仓库 —— 知识的"单一事实来源"¶

团队知识库是一个独立的 Git 仓库，不寄生于任何业务项目。这带来了三个关键优势：跨项目共享（同一个团队的多个项目连接同一个知识仓库）、生命周期独立（业务项目可能归档或重构，但知识不应该跟着项目消失）、权限独立（知识库的贡献和消费权限可以独立于代码仓库管理）。仓库结构：

team-knowledge.git
├── knowledge-catalog.md          ← 全景目录（Agent 查询入口）
├── .knowledge-config.yaml         ← 团队配置（成员、冲突策略）
├── team-conventions/              ← Layer 0-T: 团队约定
├── tech-wiki/                     ← Layer 1: 技术知识
├── biz-wiki/{domain}/             ← Layer 2: 业务知识
├── project-profiles/              ← 项目画像
└── contributions/                 ← 贡献暂存区

5.2 三种团队角色¶

角色	权限	适用人群
maintainer	裁决内容冲突、审批 proven 提升、管理成员	团队负责人、资深工程师
contributor	通过工作流自动贡献（创建/验证/标记矛盾）	正式团队成员
reader	只消费知识（查询/注入），不贡献	新成员试用期

5.3 贡献模式："贡献暂存 + 异步合并"¶

借鉴区块链的三个核心思想：

不可篡改的追加日志：log.md 只追加不修改
贡献可溯源：evidence.contributors[] 记录贡献者
共识机制：maturity 多人验证提升（draft→verified: 1 人验证; verified→proven: ≥2 人 + ≥2 项目）

5.4 冲突解决策略¶

冲突类型	处理方式
纯新增（不同条目）	自动合并，两条都保留
证据追加（同条目验证）	自动合并，evidence 数组合并去重
成熟度提升	自动合并
内容矛盾	写入 `contributions/conflicts/`，通知 maintainer 裁决
成熟度冲突（一升一降）	保留较低成熟度 + 标记 contradiction
大多数情况可以自动处理，只有真正的内容矛盾才需要人工介入。

工作流如何服务于知识沉淀¶

6.1 知识的完整生命周期：三通道沉淀¶

工作流的 16 阶段状态机与知识流动紧密关联： 1. INIT 阶段（知识注入）：工作流启动时，自动 git pull 团队知识仓库，将知识全景目录注入 Agent 的查询入口。 2. 各阶段执行中（知识消费）：Agent 在决策点按需查询知识库。 3. ARCHIVE 阶段（知识提取）：工作流完成后，@archiver 自动从全流程产物中提取知识条目，提取后执行提升判定。

6.2 各阶段查询预算¶

阶段	查询焦点	重点知识类型
ANALYSE_PRODUCT	业务知识 + 历史需求	model, process, pitfall
ANALYSE_TECH	技术知识 + 归档索引	decision, guideline(avoid), pitfall
ARCHITECT	架构模式 + 实体关系	decision, model
IMPLEMENT	编码实践 + 团队约定	guideline, pitfall
BUILD_VERIFY	反模式库	pitfall, guideline(avoid)
通过预算控制，让知识消费"精准"而非"贪婪"，避免上下文膨胀。

6.3 冷启动导入 —— `/flow-import`¶

对于历史项目，通过 3 个 Agent 的管道实现冷启动：

@doc-collector → 多源资料收集（Git/TAPD/iwiki/本地文档/口述）
@codebase-profiler → 代码画像（技术栈/模块/依赖/模式，60次搜索预算）
@knowledge-builder → 知识标准化（4维基线 + ≤13条知识条目 + 归档总结）

知识的按需消费：三级索引 + 查询预算¶

7.1 从"推送"到"主动查询"的范式转变¶

传统做法是在 Agent 启动时推送一堆知识，存在两个问题：信息过载（Agent 被淹没）和不精准（预先推送的知识不一定是当前决策点需要的）。我们的设计理念是：Agent 不被动接收固定数量的知识推荐，而是通过三级渐进式索引主动按需查阅。

7.2 三级渐进式索引¶

借鉴 Karpathy 的 LLM Wiki Pattern： | 层级 | 文件 | 大小 | 作用 | |---|---|---|---| | Layer A: 全景目录 | knowledge-catalog.md | ~50 行 | "知识库有什么？"——分类统计 + 按阶段推荐查阅路径 | | Layer B: 分类清单 | 各目录下的 catalog.md | ~100-300 行 | "这个分类有哪些条目？"——每条一行摘要 | | Layer C: 完整条目 | TK-*.md / BK-*.md | ~50-200 行 | "这条知识说了什么？"——完整内容 + 背景 + 适用场景 | Agent 可以用 ~50 行的成本了解知识库全貌，用 ~300 行的成本定位到相关条目，只在真正需要时才读取完整内容。

7.3 知识引用追踪闭环¶

Agent 查询知识后，在输出产物中记录 knowledgeReferences。ARCHIVE 阶段会批量更新 evidence.last_referenced 字段。这形成了自动化的引用追踪闭环——被引用的知识 maturity 会自动提升，长期未引用的会自动衰减。

突破人机交互瓶颈：随时随地保障工作流流转¶

8.1 问题：Harness 工作流的"在场依赖"¶

传统的 Agent 工作流有一个隐含假设：操作者坐在电脑前，IDE 打开着，随时可以响应 Agent 的请求。但现实是一天 8 小时工作，真正能"坐在工位操控 Agent"的时间可能不到 4 小时。那些"碎片时间"——会议间隙的 5 分钟、通勤路上的 30 分钟——恰恰是 Agent 需要确认的黄金窗口。

8.2 解法：远程操控 + 跨设备接管¶

引入 Hapi 内网版来解决这个问题：

在办公网下（不需要开启 IOA 远程工作，微信或企微均可直接打开），用手机远程接管运行在开发机上的 AI 编程会话。核心能力矩阵： | 能力 | 说明 | 对 Harness 工作流的意义 | |---|---|---| | 跨设备会话接管 | 手机/平板/电脑均可接管同一 Agent 会话 | 工作流不因设备切换而中断 | | 24 小时待机 | 开发机上的 Agent 持续运行 | 工作流可以 7×24 小时流转 | | PWA 原生体验 | 安装到桌面后像原生 App | 降低远程操控的使用门槛 | | 多助手切换 | 支持 Codebuddy/Codex/Gemini 等 | 适配不同 Agent 引擎的工作流 | | 自主模式 | YOLO 模式让 Agent 自主执行 | 减少人工确认频率 |

8.3 与知识沉淀闭环的结合¶

远程操控能力保障了知识沉淀闭环的完整性。暂停过久带来的真正问题是： 1. 交付周期拉长：从 1 天交付变成 3 天交付 2. 知识沉淀的时效性下降：ARCHIVE 阶段的知识提取依赖工作流完整走完 3. 碎片时间浪费：会议间隙、通勤路上这些本可推进工作流的时间白白流失

8.4 工程架构设计启示¶

好的 Harness 工程不仅要设计"Agent 怎么跑"，还要设计"人怎么随时参与"。 具体到架构层面：

状态持久化：工作流的状态必须是持久化的（文件系统即状态机）
断点恢复：每个阶段的入口和出口都有明确的持久化产物，支持从任意断点恢复
异步审批：人工确认节点应设计为异步模式
通知触达：关键节点应通过企业微信等渠道主动推送

落地经验与思考¶

9.1 历史项目引入：从 0 到 1 的冷启动挑战¶

最大的挑战不是设计架构，而是让已有项目的隐性知识显性化。做法：多源收集（Git 仓库扫描、TAPD 需求拉取、iWiki 文档导入等）、渐进导入（初始 maturity 为 draft，通过后续工作流逐步验证提升）、断点恢复（import-state.json 持久化进度）。

9.2 知识膨胀治理：Lint 机制¶

借鉴 Karpathy 的 LLM Wiki 的 Lint 操作： | 检查项 | 处理方式 | |---|---| | 孤儿条目（无引用、无验证） | 降级为 draft | | 矛盾检测（同主题相反结论） | 标记冲突，等待 maintainer 裁决 | | 过时检测（6 月未引用的 draft） | 自动归档 | | 成熟度衰减 | 按规则自动降级 |

9.3 Big Model vs Big Harness —— 务实立场¶

这不是非此即彼的选择，而是要找到适合你团队的平衡点：

模型能力提升是大势所趋，投在知识工程上的架构应该对模型能力的提升保持开放
但模型能力提升不能替代领域知识，再强的模型也不知道你的业务系统里有哪些隐藏的坑
知识工程的投入是确定性回报：每沉淀一条 proven 知识，所有后续工作流都受益

9.4 从"文件即状态"到"知识即资产"¶

AI Team 的设计哲学：文件系统即状态机。所有状态、产物、知识都以文件形式存在，没有数据库、没有独立平台。这是刻意选择：可见性（Markdown 文件人可直接阅读）、可版本化（Git 管理）、可迁移性（不依赖特定平台）、IDE 原生（.codebuddy/ 目录驱动）。

深度分析¶

知识工程与 Harness Engineering 的互补关系¶

从这篇文章可以清晰看到，知识沉淀不是 Harness Engineering 的副产品，而是其核心目标之一。文章揭示了一个重要事实：当前业界对 Harness Engineering 的关注过度集中在"工作流怎么编排"和"Agent 怎么协同"这些显性的工程话题上，而忽略了底层的知识基础设施。这种偏向导致许多团队搭建了复杂的 Agent 工作流，却没有形成知识闭环，最终每次都是从零开始。文章提出的"工作流是管道，知识是活水"这个比喻极具启发性。它提醒我们：Harness 工作流的设计不应该以工作流本身为目的，而应该以知识沉淀为目标。一个好的 Harness 系统，应该让每次工作流的执行都自动产生知识积累，让下一个工作流能够站在前人的肩上。

三级成熟度机制的创新价值¶

文章提出的 draft → verified → proven 三级成熟度体系，以及自动衰减机制，是这套知识工程系统的核心创新。这个设计的精妙之处在于：它用工程化的方式解决了知识质量控制的难题。传统的知识库往往"只进不出"——随着时间推移，过时的、未经验证的、重复的知识不断累积，导致知识库的噪声越来越大，最终失去参考价值。而这篇文章提出的自动衰减机制（proven 12 个月未引用→降级，verified 6 个月未引用→降级，draft 长期未引用→归档），让知识库拥有了"新陈代谢"能力，自动保持健康和活力。同时，三级成熟度的设计让知识有了可信度的分层。Agent 在查询时可以基于成熟度调整对知识的信任程度——proven 知识可以大胆引用，draft 知识需要谨慎验证，这有效避免了低质量知识对工作流的误导。

"文件系统即状态机"的工程哲学¶

文章提到的"文件系统即状态机"是一个非常有价值的工程哲学。这个设计的核心洞察是：在 AI Agent 系统中，状态应该持久化在文件系统而非内存中。这带来了几个关键优势： 1. 跨设备一致性：无论从手机、平板还是电脑接入，看到的都是同一个状态 2. 断点恢复能力：可以在任意时刻暂停和恢复工作流，不丢失进度 3. 无需数据库依赖：降低了系统复杂度，减少了运维负担 4. 人机协作的异步化：人工确认节点可以设计为异步模式，人类在任意时间审批后 Agent 继续执行这个设计哲学与文章强调的"远程操控 + 跨设备接管"能力形成完美配合——正是因为状态都持久化在文件中，远程操控才能真正实现"随时随地接管工作流"的目标。

从"知识推送"到"知识按需查询"的范式转变¶

文章批判了传统的"知识推送"模式（Agent 启动时推送大量知识），并提出"三级渐进式索引"的按需查询模式。这个转变的意义在于：它解决了上下文膨胀与知识利用之间的根本矛盾。传统模式下，为了让 Agent 有足够的知识，往往一次性推送大量知识，导致上下文膨胀严重。而文章提出的三级索引——全景目录（~50行）→ 分类清单（~100-300行）→ 完整条目（~50-200行）——让 Agent 可以先用极低的成本了解知识库全貌，再根据当前决策点按需深入读取具体条目。这种渐进式披露策略，让上下文成本从"一次性 5000-10000 行"降低到"按需 50-300 行"，效率提升了一个数量级。结合各阶段的查询预算控制（ANALYZE_PRODUCT 查询 model/process/pitfall，ANALYZE_TECH 查询 decision/guideline/pitfall 等），让知识消费变得"精准"而非"贪婪"，这是 Harness Engineering 在知识管理领域的重要实践创新。

实践启示¶

启示一：知识工程应该先于工作流设计¶

这篇文章提醒我们，在搭建 Harness 工作流之前，应该先思考"知识从哪里来，到哪里去"。很多团队犯的错误是：先花大量时间设计复杂的工作流，却没有考虑知识如何沉淀。最终工作流跑了很多次，但团队并没有因此变得更有经验。正确的做法应该是：以知识沉淀为目标，设计工作流的每个阶段。在 INIT 阶段设计知识注入，在执行阶段设计知识查询，在 ARCHIVE 阶段设计知识提取。工作流的设计应该围绕知识的流动展开，而非反过来。对于计划搭建 Harness 系统的团队，建议先问自己三个问题： 1. 这套工作流跑完，会产生哪些知识？ 2. 这些知识应该以什么形式存在？ 3. 下一个工作流如何复用这些知识？如果答案不清晰，说明工作流的设计还没有真正以知识为中心。

启示二：知识库应该是独立的 Git 仓库¶

文章特别强调团队知识库应该是"独立的 Git 仓库"，不寄生于任何业务项目。这个设计决策背后有三个关键考量：跨项目共享、生命周期独立、权限独立。对于正在建设知识体系的团队，这个设计值得借鉴。如果知识库寄生在某个业务项目里，当这个项目归档或重构时，知识也会随之消失。而独立的知识仓库可以跨越项目生命周期存在，成为团队的"永久记忆"。同时，独立的仓库也使得知识库的贡献和消费权限可以独立于代码仓库管理——新成员可以只有 reader 权限（消费但不贡献），而资深工程师可以有 contributor 或 maintainer 权限。这种精细的权限设计，是知识库健康运转的重要保障。

启示三：知识需要"新陈代谢"机制¶

文章提出的自动衰减机制和 Lint 机制，揭示了一个重要的实践原则：知识库不能只进不出。没有新陈代谢的知识库，最终会变成一个充满过时、重复、矛盾知识的"知识沼泽"。建议团队在建设知识库时，从一开始就设计好衰减规则：

proven 知识 12 个月未引用 → 降级为 verified
verified 知识 6 个月未引用 → 降级为 draft
draft 知识长期未引用 → 归档移出活跃索引同时，建立定期的 Lint 检查机制，识别孤儿条目、矛盾检测、过时检测等问题。知识库的维护成本虽然不低，但这是保持知识质量的必要投入。

启示四：人机交互设计是 Harness 系统的重要组成部分¶

文章用了整整一个章节讨论"突破人机交互瓶颈"的问题，这是一个被普遍忽视的话题。传统的 Agent 工作流设计假设操作者一直在场，但现实中人的注意力是稀缺的——会议、通勤、用餐都会导致工作流卡在人工确认节点。文章的解决方案是：远程操控 + 跨设备接管 + 异步审批。这个方案的核心洞察是：好的 Harness 系统不仅要设计 Agent 怎么跑，还要设计人怎么随时参与。具体到架构设计，应该做到： 1. 状态持久化：工作流状态存文件而非内存，支持从任意设备接入 2. 断点恢复：每个阶段有明确的入口/出口产物，支持从任意断点恢复 3. 异步审批：人工确认节点设计为异步模式，不要求人在场 4. 通知触达：关键节点通过企业微信等渠道主动推送，而非被动等待这些设计让工作流可以 7×24 小时流转，大幅提升团队的生产效率。

启示五：知识工程投入是确定性回报¶

文章在结尾处指出了一个重要观点：知识工程的投入是确定性回报，而模型能力提升的回报是概率性的。每沉淀一条 proven 知识，所有后续工作流都会受益；但下一代模型在你的特定场景上是否真的更好，是不确定的。这个观点对于资源分配决策有重要参考价值。在"投大模型"和"投知识工程"之间做选择时，不应该盲目追逐最新的模型热点，而应该评估知识工程的投入产出比。对于业务逻辑复杂、领域知识要求高的场景，知识工程的投入往往能带来更稳定、更可累积的回报。特别是对于已经运行了较长时间的团队，历史积累的领域知识是宝贵的资产。这些知识——"这个接口在高并发下有 race condition""那个业务流程需要特别注意 XX 情况"——是模型无法从公开资料中学到的，属于团队的私域护城河。 → 原文存档