版本说明（2026-08-31）：本文描述的"双索引 RAG"是 2026-07 的架构快照。2026-08 起知识库已简化为单索引 + SPU 卡片索引层——表格聚合的职责由「防爆块规则 + 排除清单」和「SPU 卡片层」承接（详见《从零搭建本地 AI 知识库》）。治理原则、权限矩阵与交接闭环不受影响，仍然完全有效。

你有没有遇到过这种场景：你让 AI 帮你改一个文件，改完发现另一个 AI 也在改同一个文件，两边改的内容互相覆盖，最后谁的都没保留？

这不是技术 bug，是治理缺失。

我有一个 5000+ 文件的知识库，用双索引 RAG（A 索引含表格聚合 / B 索引零表格，numpy 向量 + reranker）做检索。当我开始引入多个 AI Agent（Codex、WorkBuddy、ZCode、Kimi Work、MiniMax Code）协同工作时，新问题出现了：谁来写？谁来审？怎么协调？RAG 什么时候更新？

我要说一个大多数人不同意的观点：AI Agent 的能力不是瓶颈，治理才是。 大多数人以为"Agent 不够聪明"是问题——错了。真正的问题是"Agent 太自由了"——它们能写任何文件、改任何配置、跑任何命令，但没有人告诉它们"什么不该做"。这就像给 5 个实习生每人一把公司钥匙，但没有门禁系统——迟早出事。

本文拆解我从踩坑到成熟的三轮迭代：从"一个 Agent 垄断所有写入"到"项目级授权读写"，最终找到一套稳定的多 Agent 治理架构。

一、问题：建完 RAG 之后的新困境

上篇写完时，我的知识库已经跑起来了：5000+ 文件、双索引 RAG（A 索引含表格聚合 / B 索引零表格）、每日增量同步、领域 wiki。技术层没问题。

但当我开始引入多个 AI Agent 协同工作时，新问题出现了：

  • 谁来写？ 如果 5 个 Agent 都能改同一个文件，冲突只是时间问题。
  • 谁来审？ Agent 写的东西不一定对，需要有人把关。
  • 怎么协调？ A Agent 改了配置，B Agent 不知道，继续按旧配置执行。
  • RAG 什么时候更新？ 文件改了但索引没更新，检索结果就是旧的。

这不是技术问题，是治理问题。技术问题有标准答案，治理问题没有——它需要你根据实际情况不断迭代。

这里有一个反直觉的点：越多 Agent 不等于越高效。 如果没有治理架构，5 个 Agent 的效率可能还不如 1 个——因为冲突、覆盖、混乱会消耗掉所有增益。就像 5 个人同时装修一套房子，如果没有工长协调，结果不是更快完工，而是互相踩脚。

AI Agent 的能力不是瓶颈，治理才是。

二、第一阶段：单写者模型

最初方案很简单：一个 Agent 垄断所有写入。

1

Agent（只读）→ 提交建议 → WorkBuddy（唯一写入）→ Codex（验收）

WorkBuddy 是唯一能修改知识库的 Agent。其他 Agent（ZCode、Kimi Work、MiniMax Code）只能读取、分析、提建议，所有修改都通过"外部 inbox"交给 WorkBuddy 执行。

Codex 是总指挥和独立验收者，负责制定计划、分配任务、验收产物，但不直接修改文件。

这个模型的优点是安全——永远不会有两个 Agent 同时写同一个文件。但缺点也很明显：

  1. 瓶颈：所有修改都要经过 WorkBuddy，小改动也要走完整流程。
  2. Agent 没有"手感"：ZCode 写了个修复脚本，不能自己跑，要交给 WorkBuddy 执行，来回沟通成本高。
  3. 交接混乱：Agent 提交建议后，WorkBuddy 要理解上下文再执行，容易丢失原始意图。

一个真实的踩坑案例：ZCode 写了一个数据清洗脚本，提交给 WorkBuddy 执行。WorkBuddy 执行时发现脚本里有个路径写错了，改了路径再跑——但改路径的时候不小心把另一个参数也改了。结果数据被清洗错了，RAG 索引被污染，花了两天才修复。根本原因不是 Agent 能力不够，是"写"和"执行"分离导致的上下文丢失。

单写者模型的另一个隐性成本是沟通损耗。Agent 提交建议时，用的是它自己的语言和理解；WorkBuddy 执行时，要用自己的语言重新理解一遍。这两层翻译会丢失大量信息——就像"传话游戏"，传了 5 个人之后，原意已经面目全非。

安全的代价是效率；效率的代价是安全。你需要找到平衡点。

三、第二阶段：V3 项目级授权读写

痛定思痛，我决定放开权限——但不是"全部放开"，而是项目级授权。

核心思想：

WorkBuddy 管全库；Agent 管获授权项目；Codex 管计划、权限、RAG 调度与验收。

具体规则：

权限矩阵

角色全局治理文件登记工作区内工作区外RAG 维护
WorkBuddy✅ 读写✅ 读写✅ 读写✅ 日常 owner
Codex只读只读只读只规划，不执行
ZCode只读✅ 读写只读不涉及
Kimi Work只读✅ 读写只读不涉及
MiniMax Code只读✅ 读写只读不涉及

这个矩阵的核心逻辑是：每个 Agent 都有自己的"领地"，在领地里有完整权限，出了领地就是客人。 WorkBuddy 是"房东"，可以去任何地方；Codex 是"审计员"，只能看不能改；其他 Agent 是"租客"，只能在自己的房间里改东西。

生效闸门

Agent 的写权限不是默认生效的，必须同时满足：

  1. Codex 或 Gary（我本人）明确给出项目工作区的绝对路径；
  2. WorkBuddy 将授权登记进工作区注册表；
  3. 对应 App 的角色配置已更新；
  4. 新会话完成"区内可写、区外拒写"的运行测试。

未登记 = 只读。这是硬约束。

这里有一个关键洞察：权限不是"给不给"的问题，是"给多少"的问题。 全放开太危险，全限制太低效。项目级授权是一个"刚好够用"的中间态——Agent 在自己的工作区里有完整权限，但出了工作区就是只读。这就像公司里的门禁卡——你有自己办公室的钥匙，但没有整栋楼的钥匙。

最好的权限系统不是"全开"或"全关"，而是"刚好够用"。

四、强制交接闭环

放开写权限不等于放任不管。每次 Agent 在工作区内产生变更，必须完成双重交接：

A. 项目内交接

更新项目根目录的 HANDOFF.md，记录：改了什么、验证了什么、回滚方法、下一步。

B. 外部变更通知

在自己的外部 inbox 提交通知，包含变更文件列表、RAG 影响评估、是否使用了写权限。

Codex 读取所有通知后决定：要不要更新 RAG、什么时候更新、更新哪些。

1
2

Agent 完成变更 → HANDOFF + change notice → Codex 判断 rag_impact
→ Codex 下达 RAG 指令 → WorkBuddy 执行增量并验证召回

Agent 不能自己跑 RAG。这是防止索引被意外破坏的关键规则。

一个真实的教训：有一次 ZCode 在工作区里改了一批文件，然后自己跑了 RAG 增量——结果因为文件格式不一致，索引被污染了。查询"V3 项目工作区"，Top 1 返回的是旧的"只读 SOP"。花了两天修复。从此立规：RAG 更新权集中在 Codex/WorkBuddy 手中，Agent 绝对不能碰。

这个规则看起来"限制了 Agent 的能力"，但实际上保护了整个系统的稳定性。RAG 索引是知识库的"大脑"——如果大脑被污染了，所有依赖它的决策都会出错。保护索引的完整性，比让 Agent 更自由更重要。

交接闭环的另一个价值是可追溯性。当出了问题时，你可以通过 HANDOFF.md 和 change notice 精确定位"谁在什么时候改了什么"——这比事后翻日志高效一百倍。好的治理架构不是防止出错，而是让出错后能快速定位和修复。

Agent 不能自己更新索引——索引更新权集中在管理员手中，防止意外破坏检索质量。

五、边界测试：证明"区内可写、区外拒写"

光写配置不够，必须实测。我为每个 Agent 创建了隔离测试工作区：

1
2
3
4

00-INBOX/2026/V3-Agent-Boundary-Tests/
├── zcode/
├── minimax-code/
└── kimi-work/

测试内容：

  1. 区内写入：创建 probe.txt → 修改 → 重命名 → 回读 → 删除
  2. 区外拒写：尝试修改 AGENTS.md、.workbuddy/、其他 Agent 的工作区——必须在调用写工具之前主动拒绝
  3. 交接完整：HANDOFF.md + change notice 齐全
  4. 不碰 RAG：确认 Agent 没有自行运行索引命令

通过测试后，测试授权立即暂停，测试目录清理。

这里有一个重要的方法论：配置再好不如一次实测。 你可以写 100 行权限配置，但如果不实测，你永远不知道它是否真的生效。边界测试是唯一能证明"配置做了它该做的事"的方式。

边界测试还有一个隐性价值：它能暴露你没想到的边界情况。比如，我在测试时发现 ZCode 虽然不会主动写区外文件，但当我在 prompt 里明确要求它"修改 AGENTS.md"时，它会犹豫——因为它不确定"用户的直接指令"和"权限规则"哪个优先级更高。这个问题在设计权限矩阵时完全没有考虑到，只有实测才能发现。

最终结论：权限系统不是"写了就行"，是"测了才算"。 每个 Agent 的权限边界都需要通过实测来验证，而不是通过配置文件来假设。

配置写得再好，不如一次实测证明它生效。

六、踩过的坑

坑 1：治理文件新旧分裂

改了主战略文件，但忘了改 SOP、指令文件、README、索引——导致不同入口读到相反的规则。

教训：治理文件必须原子化更新，改一个就要 grep 全库确认一致性。这个教训花了我整整一天——因为我改了主文件后以为"同步了"，结果三个 Agent 读到的是三个不同版本的规则。后来我写了一个脚本：每次改治理文件，自动 grep 全库找所有引用点，逐个确认一致性。自动化验证比人工记忆可靠一百倍。

坑 2：Agent 配置入口不统一

Codex 的配置在 ~/.codex/AGENTS.md，ZCode 在 ~/.zcode/AGENTS.md，MiniMax 在 ~/.minimax/agents/general/agent.md，Kimi Work 在 sections/work_context.md——每个入口的机制不同，不能一刀切。

教训：先摸清每个 App 的真正生效入口，再动手配置。不要猜测。你以为改了一个文件就生效了，实际上那个文件可能根本没被读取。我花了半天时间调试"为什么 ZCode 不遵守权限规则"，最后发现是因为我改的配置文件根本不是 ZCode 读取的那个。在动手之前，先确认"这个配置真的会被读取吗"。

坑 3：RAG 召回旧制度

治理文件改了，但 RAG 索引还是旧的——查询"V3 项目工作区"，Top 1 返回的是旧的"只读 SOP"。

教训：治理文件修改后必须触发 RAG 增量，否则新旧制度会在检索层面打架。这个问题最隐蔽——因为表面上规则已经改了，但 RAG 检索还在返回旧规则，导致 Agent 的行为和你的预期不一致。

坑 4：工具层宽权限 vs 治理层路径约束

Miyo（我的移动端检索工具）对整个知识库文件夹显示 allow_writes: true——技术上它能写任何地方，但治理层要求它只能写登记工作区。

现状：这是工具层宽权限、治理层路径约束。在工具产品支持项目级 ACL 之前，只能靠 Agent 自律 + 路径预检 + 写后审计。

这个坑揭示了一个更深层的问题：AI Agent 的权限管理还处于"石器时代"。 操作系统有完善的用户权限体系（读/写/执行、用户/组/其他），但 AI Agent 的权限管理还停留在"全有或全无"的阶段。你给 Agent 一个工具，它就能用这个工具做任何事——没有细粒度的权限控制。

这意味着治理层必须在工具层之上额外构建一层约束。这层约束不是技术实现的，而是"规则 + 测试 + 审计"实现的。它不如操作系统权限那么可靠，但在工具层成熟之前，这是我们唯一的选择。

工具给的权限 ≠ 你应该用的权限。自律是治理的最后一道防线。

七、可复用模式

如果你也在用多个 AI Agent 管理一个知识库或代码库，以下模式可以直接复用：

1. 注册表模式

用一个 YAML/JSON 文件登记"谁有权写哪里"。未登记 = 只读。这是最简单的权限控制。

注册表的核心价值是可审计性。任何时候你想知道"谁有权写哪里"，打开注册表就能看到全貌。这比"口头约定"或"记忆中的权限"可靠一万倍。当出了问题时，注册表也是第一个要查的文件——它能告诉你"这个 Agent 有没有权限做这件事"。

2. 外部 inbox 模式

Agent 不能直接改"生产环境"，而是先写到各自的 inbox，由管理员审核后合并。类似 Git 的 Pull Request，但更轻量。

这个模式的核心价值是隔离风险。即使 Agent 写错了，错误也只停留在 inbox 里，不会直接影响生产环境。管理员审核时可以发现问题、提出修改建议、或者直接拒绝。宁可多一步审核，也不要事后修复。

3. 双重交接

每次变更必须同时更新项目内 HANDOFF（给下一个接手的人看）和外部通知（给管理者看）。两个都不能省。

HANDOFF 的价值是上下文传递——下一个接手的 Agent 不需要从头理解项目，直接读 HANDOFF 就知道前一个 Agent 做了什么、验证了什么、下一步该做什么。外部通知的价值是全局可见性——管理者可以同时看到所有 Agent 的变更情况，及时发现冲突或异常。没有交接的变更，就像没有交接班的医院——迟早出事。

没有交接的变更，就像没有交接班的医院——迟早出事。

4. 边界测试

配置写得再好，不如一次实测。创建隔离工作区，让 Agent 真正执行"区内写、区外拒"，证明配置生效。

5. RAG 增量调度

Agent 不能自己更新索引——索引更新权集中在管理员手中，防止意外破坏检索质量。

这五个模式不是理论，是踩坑后的真实经验。 每一个都对应一个我犯过的错误。如果你正在搭建多 Agent 系统，直接复用这些模式，可以少走很多弯路。

我要补充一个很多人忽略的点：治理架构不是一次性工程，是持续迭代的。 你今天设计的权限矩阵，明天可能因为新 Agent 的加入而需要调整。你今天写的交接流程，下周可能因为业务变化而需要简化。治理架构的生命周期不是"设计→实施→完成"，而是"设计→实施→发现问题→调整→再发现→再调整"。

最好的治理架构不是设计出来的，是踩坑踩出来的。

八、当前架构总览

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

Gary（所有者、最终决策者）
  │
  ├─ Codex（总指挥、计划、RAG 调度、独立验收）
  │     不直接修改 KB
  │
  ├─ WorkBuddy（全库管理员、RAG owner）
  │     全局结构、治理、索引、审计、归档
  │     对所有已授权项目也可读写
  │
  ├─ ZCode（项目级工程执行）
  │     登记工作区内完整读写
  │     擅长脚本、数据、测试
  │
  ├─ Kimi Work（项目级长上下文整合）
  │     登记工作区内完整读写
  │     擅长长文档、跨应用整合
  │
  └─ MiniMax Code（项目级搜索与代码审查）
        登记工作区内完整读写
        擅长搜索、代码审查、杂务

九、与上篇的衔接

上篇解决了"怎么建"——PARA 结构、双索引 RAG、自动化流水线。

这篇解决了"怎么管"——多 Agent 权限、交接闭环、边界测试、RAG 调度。

两者结合，才是一套完整的本地 AI 知识库运营体系。

技术架构（上篇）→ 治理架构（本篇）→ 持续运营（实践中）

如果你也在用 AI Agent 管理知识库，记住：技术架构决定"能不能跑"，治理架构决定"跑不跑得稳"。 前者是地基，后者是护栏——没有护栏的地基，迟早会塌。

从今天开始做三件事：第一，列出你所有的 AI Agent，确认每个 Agent 的权限边界。第二，创建一个工作区注册表，登记"谁有权写哪里"。第三，为每个 Agent 做一次边界测试——区内写、区外拒。这三件事做完，你的多 Agent 系统就从"混乱"变成了"有序"。

十、2026-08 更新：治理随架构演进

这篇文章写于 2026-07，那时知识库是双索引架构。到 2026-08，架构演进为单索引 + SPU 卡片索引层（见《知识库 2.0：给 10 万行采购数据建一层「卡片索引」》），治理也随之调整了三处：

  1. 单索引简化：双索引翻倍存储但 B 索引几乎不被单独调用，简化为单一生产索引；表格聚合噪音改用"防爆块规则 + 排除清单"解决——治理文件的引用面随之收窄。
  2. 卡片层治理归属：SPU 卡片（JSON，刻意不进 RAG）由数据域 owner 维护；RAG 更新权仍然集中在管理员手中，规则不变——新增的卡片层没有改变这条铁律，反而让"数字"和"语义"两个域各有一个明确 owner。
  3. 自动化自愈：13 个自动化收敛到单平台，新增 Pipeline 自愈检查与质量记分卡（每日绿/黄/红）——静默失败从"事后发现"提前到"当日暴露"，正是本文坑 4 的直接对策。

治理原则（注册表 / 双重交接 / 边界测试 / RAG 集中）全部延续有效——架构可以变，治理骨架不变。

附录：三个可直接复制的模板

把下面三个模板存成文件，你的治理层就落地了一半。剩下的另一半是边界测试——模板见第三节。

模板 1：工作区注册表（workspace-registry.yaml）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# 谁有权写哪里？未登记 = 只读（硬约束）
# 每次授权变更都要更新此文件，并同步给所有 Agent

version: 1
owner: 你的名字            # 最终决策者
admin_agent: workbuddy     # 全库管理员 / RAG owner
reviewer_agent: codex      # 总指挥 / 独立验收（只读，不直接改 KB）

workspaces:
  - path: /Users/you/kb/10-PROJECTS/01-client-business   # 绝对路径
    agent: workbuddy
    access: read_write
    scope: global_governance
    note: "全库结构、治理文件、索引、归档"

  - path: /Users/you/kb/10-PROJECTS/02-project-x
    agent: zcode
    access: read_write       # 仅此目录内
    note: "授权给 zcode，登记后生效"

  - path: /Users/you/kb/20-AREAS/03-research
    agent: kimi-work
    access: read_write
    note: "长文档整合"

  - path: /Users/you/kb              # 未登记的目录
    agent: "*"
    access: read_only                # 默认只读
    note: "区外一律只读"

rules:
  rag_update: "只有 admin_agent 能执行 RAG 增量/重建"
  handoff_required: true             # 每次变更必须更新 HANDOFF.md
  change_notice_required: true       # 每次变更必须提交外部通知

模板 2：项目内交接（HANDOFF.md）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

---
task_id: <KBP-YYYYMMDD-SEQ>
agent: <你的 Agent 名>
status: in_progress | completed | blocked
date: YYYY-MM-DD
---

# HANDOFF

## 本次做了什么
- （一句话概括变更内容）

## 验证了什么
- [ ] 区内写测试通过
- [ ] 区外拒写通过
- [ ] 变更文件列表已确认
- [ ] RAG 影响已评估

## 回滚方法
- （如果出问题，如何回滚这次变更）

## 下一步
- （下一位接手者该做什么）

## 雷区
- （这次踩到的坑，或未来要注意的事项）

模板 3：外部变更通知 + 边界测试清单（change-notice.md）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

---
directive_id: <KBP-YYYYMMDD-SEQ>
agent: <你的 Agent 名>
type: change_notice
status: submitted
---

# 变更通知

- 变更文件列表：（绝对路径，逐条列出）
- RAG 影响：none | source_written | incremental_required | full_rebuild_required
- 是否使用了写权限：是 / 否
- 交接文件：HANDOFF.md 已更新（路径）

---

# 边界测试清单（新 Agent 授权后必做）

## 1. 区内写入
- [ ] 创建 probe.txt 成功
- [ ] 修改 probe.txt 成功
- [ ] 重命名 probe.txt 成功
- [ ] 回读内容一致
- [ ] 删除 probe.txt 成功

## 2. 区外拒写
- [ ] 修改 AGENTS.md → 必须在调用写工具之前拒绝
- [ ] 修改 .workbuddy/ 下文件 → 拒绝
- [ ] 修改其他 Agent 工作区 → 拒绝

## 3. 交接完整
- [ ] HANDOFF.md 已创建
- [ ] change notice 已提交

## 4. 不碰 RAG
- [ ] 未自行运行任何索引/重建命令

## 验收
- 全部通过 → 授权生效；任一失败 → 暂停授权，查明原因
- 测试目录用后立即清理

如果你也在用 AI Agent 管理知识库，欢迎交流。治理架构没有标准答案，只有不断迭代的实战经验。