从“可用脚本”到“可治理系统”：我的 AI Agent 子系统升级方法论

这是一篇实践笔记。
它不是抽象架构设计，也不是照搬某个框架的官方文档，而是我在连续完成 Skill 子系统与 Memory 子系统升级后，总结出来的一套可复用方法论。

---

1. 背景：为什么要沉淀这套方法论

在搭建一个长期运行的 AI Agent 系统时，最开始我们很容易关注“能不能跑”。

比如：

• 能不能查到一个 Skill？
• 能不能写入一条记忆？
• 能不能根据用户问题检索专家？
• 能不能在飞书里完成一次调用？

这些当然重要，但当系统不断变复杂以后，仅仅“能跑”是不够的。

因为一个长期运行的 Agent 系统真正需要解决的是：

• 能不能稳定被发现？
• 能不能被正确调用？
• 能不能知道是否可用？
• 能不能审计它有没有异常？
• 能不能在变更后安全收口？
• 能不能通过黑盒测试证明链路真实跑通？
• 能不能避免规则散落在多个文件里，最后没人知道哪个才是准的？

这也是我在连续升级 Skill 子系统和 Memory 子系统后最大的体会：

一个子系统真正成熟的标志，不是“脚本能跑”，而是“它具备注册、路由、审计、追溯、验收和持续治理能力”。

---

2. 核心结论

经过 Skill 子系统和 Memory 子系统两轮实践验证，我总结出一套升级路径：

从：

• 单个脚本
• 手工判断
• 临时规则
• 靠模型理解
• 靠前端回复判断是否成功

升级为：

• 有注册表
• 有策略配置
• 有 Router
• 有 Auditor
• 有日志
• 有报告
• 有后端链路验收
• 有 Change Guard 收口
• 有总控调度接入

这套方法可以概括为：

子系统 V2 升级方法论：把一个“能用的能力”，升级成一个“可治理的系统”。

---

3. 标准架构：一个成熟子系统应该具备什么

一个较成熟的 Agent 子系统，至少应该包含以下层次。

3.1 Registry：注册表层

注册表负责回答：

• 这个子系统有哪些组件？
• 每个组件负责什么？
• 有哪些能力类型？
• 哪些文件是核心文件？
• 哪些内容属于这个子系统，哪些不属于？

例如：

• Skill 子系统有 SKILL_REGISTRY.md
• Memory 子系统有 MEMORY_REGISTRY.md
• 专家子系统未来可以有 EXPERT_REGISTRY.md

注册表不应该记录任务进展，也不应该承担执行逻辑。

它的作用是：

让系统结构可解释，让人和 Agent 都知道这个子系统由什么组成。

---

3.2 Policy：策略配置层

策略配置负责把可调整规则从代码中抽离出来。

它通常是 JSON 或类似格式，例如：

• memory_policy.json
• skill rules json
• expert_policy.json

它适合放：

• 默认召回数量
• 是否读取归档
• 允许的类型
• 过期判断天数
• 审计检查项
• Router 支持的动作
• Auditor 必须检查的文件和目录

策略层的核心价值是：

以后改规则，不一定要改代码。

---

3.3 Router：路由层

Router 是自然语言请求到具体动作之间的桥。

它负责：

• 判断用户意图
• 识别是 query、write、task、status、validate 还是其他动作
• 生成标准命令
• 必要时执行底层 Engine
• 记录 route 和 execute 日志

Router 的价值在于：

不再让模型临场猜“应该调用哪个脚本”，而是把自然语言入口标准化。

在 Memory 子系统里，Router 解决了这个问题：

• 用户说“查一下之前……”
• 用户说“记一下……”
• 用户说“下一步是什么？”
• 用户说“检查记忆系统”

这些请求都先进入 Memory Router，再由 Router 分发给 Engine。

---

3.4 Engine / Core：执行层

Engine 是真正干活的底层执行器。

它负责：

• 读
• 写
• 查询
• 索引
• 摘要
• 基础校验

但是 Engine 不应该直接承担自然语言判断。

一个关键原则是：

Router 负责判断意图，Engine 负责执行动作。

这样可以避免底层脚本越来越重，也避免模型绕过路由直接调用底层能力。

---

3.5 Auditor：审计层

Auditor 不负责写入，也不负责业务执行。

它只回答一个问题：

这个子系统现在是否健康？

它应该检查：

• 必要文件是否存在
• 必要目录是否存在
• index 是否合法
• policy 是否合法
• registry 是否完整
• 是否存在旧称呼残留
• 是否存在规则漂移
• 是否存在过期任务
• 是否能生成审计报告

Auditor 的价值在于：

让“是否可用”不再靠感觉判断，而是靠结构化验收结果判断。

---

3.6 Logs：运行日志层

日志不是为了好看，而是为了定位真实链路。

尤其在飞书、企业微信、钉钉这类前端交互场景里，只看前端回复远远不够。

因为前端只能证明：

• Agent 回复了

但不能证明：

• 它有没有走 Router
• 有没有调用 Engine
• 有没有写入文件
• 有没有生成报告
• 有没有绕过规则

所以必须有日志。

例如：

• router.log 记录 route / execute
• engine.log 记录 query / write / task
• auditor.log 记录 verify / report

---

3.7 Reports：报告层

报告用于保存审计结果和验收结果。

它的作用是：

• 可追溯
• 可复查
• 可对比
• 可证明某次验收确实发生过

例如：

• memory/reports/memory-audit-YYYYMMDD-HHMMSS.json
• skill_registry/reports/audit-skill-verify-*.json

报告层让一次验收从“口头说通过”变成“有文件可查”。

---

3.8 Index：索引层

当一个子系统的数据开始增多时，不能每次都全文读取。

索引用来解决：

• 快速查询
• Top-K 检索
• 降低上下文成本
• 避免大文件全文注入

Skill 子系统有 SKILL_INDEX.json。

Memory 子系统有 memory/index.json。

专家子系统未来也应该有 EXPERT_INDEX.json 或更严格的专家索引结构。

索引层的核心原则是：

给机器查，不给人硬读；由脚本维护，不靠手工乱改。

---

3.9 AGENTS.md：总控接入层

子系统自己跑通还不够，必须接入总控调度。

AGENTS.md 负责告诉 Agent：

• 什么情况下触发该子系统
• 默认入口是什么
• 哪些行为禁止
• 结果如何解释
• 失败时如何处理

这里最重要的原则是：

AGENTS.md 只放触发协议和调度边界，不放子系统的完整实现细节。

如果 AGENTS.md 写得太重，系统会膨胀。

如果 AGENTS.md 写得太轻，Agent 不知道什么时候调用子系统。

所以总控层应该保持“短、硬、准”。

---

3.10 Change Guard：变更守卫层

任何核心子系统升级，都必须有变更守卫闭环。

标准流程是：

1. 修改前明确意图
2. 修改后 scan
3. 根据 scan 生成同步计划
4. validate
5. 必要时更新记忆、索引、任务
6. checkpoint 记录新基线

它解决的问题是：

• 改了哪些文件？
• 风险等级是什么？
• 是否需要同步其他文件？
• 是否需要重建索引？
• 是否需要重启？
• 当前 workspace 是否干净？

Change Guard 的价值是：

让配置变更从“手工感觉”变成“有扫描、有校验、有基线”的工程流程。

---

4. 标准升级流程

基于两轮实践，我把子系统升级流程总结为 10 步。

---

第一步：确认子系统边界

先回答：

• 这个子系统解决什么问题？
• 它不解决什么问题？
• 哪些文件属于它？
• 哪些文件不应该被它承担？
• 它和 AGENTS.md、TOOLS.md、MEMORY.md 的关系是什么？

这一步非常重要。

很多系统混乱，不是因为代码写错，而是因为文件职责不清。

---

第二步：保留稳定执行层

如果原来已经有能跑的脚本，不要急着推倒重来。

正确做法是：

• 先保留执行层
• 明确它的职责
• 不让它继续膨胀
• 后续在外面补 Router、Auditor、Policy

例如 Memory 子系统中，zhiwei_memory_engine.py 原本已经能读写查询，所以没有推倒重写，而是保留为 Engine 层。

---

第三步：补注册表

新增或完善 Registry 文件。

它应该写：

• 组件清单
• 存储分层
• 类型定义
• 职责边界
• 默认读取边界
• 默认写入边界

它不应该写：

• 当前项目进展
• 临时任务
• 流水账
• 大段执行命令

注册表要清晰、克制、稳定。

---

第四步：补策略配置

把可调整规则外置。

例如：

• 默认 top_k
• 是否读 archive
• 支持哪些 action
• 审计检查哪些文件
• stale task 天数
• legacy terms 清单

这样后续调规则时，不必每次都改 Python 逻辑。

---

第五步：补 Router

Router 是自然语言入口。

它应该做到：

• 能识别意图
• 能生成 action
• 能生成 engine_args
• 能可选 execute
• 能记录 route 日志
• 能本地 verify

关键是：

Router 不应该自己承担复杂执行逻辑，而是分发给 Engine。

---

第六步：补 Auditor

Auditor 是健康检查入口。

它应该做到：

• 能检查结构
• 能检查 policy
• 能检查 index
• 能检查 registry
• 能检查旧规则残留
• 能生成报告
• 能返回 ok / warnings / errors

关键是：

Auditor 只检查，不修改核心内容。

---

第七步：本地 CLI 验收

先不要上飞书。

本地先跑通：

• Router verify
• Auditor verify
• Engine validate
• Engine rebuild-index
• Router route --execute
• Query 测试
• Write 测试

本地过不了，前端一定不稳定。

---

第八步：黑盒链路验收

飞书这类前端测试不能只看回复内容。

必须看后端日志：

• Router 是否有 route
• Router 是否有 execute
• Engine 是否有 query / write
• MEMORY.md 是否真实写入
• index 是否更新
• Auditor 是否生成 report

黑盒测试要用唯一标识，避免历史日志干扰。

例如：

• MR-COMPARE-NL-20260507
• MR-COMPARE-WRITE-20260507
• SKILL-AUDIT-TEST-xxxx

这样 grep 日志时能判断是不是本轮触发。

---

第九步：接入 AGENTS.md

接入总控时要注意：

• 只写默认入口
• 不重复暴露底层命令
• 不把完整实现细节写进去
• 明确 MUST / NEVER 规则
• 明确失败处理方式
• 避免总控文件越来越长

一个重要经验是：

如果 AGENTS.md 同时暴露 Router 和 Engine，模型可能绕过 Router 直接调用 Engine。

所以总控层要避免给模型多条冲突路径。

---

第十步：Change Guard 收口

所有修改完成后必须收口：

• scan
• validate
• rebuild-index
• checkpoint
• 再 scan 确认 changed_count = 0

只有 workspace 干净，才算升级完成。

---

5. 实践中验证出来的关键经验

5.1 不要相信前端回复，要看后端日志

前端回复“已记录”，不等于真的写入。

前端回复“链路正常”，不等于真的走了 Router。

必须看：

• router.log
• engine.log
• auditor.log
• MEMORY.md
• index.json
• Change Guard scan

---

5.2 测试用例必须带唯一标识

重复使用同一个测试句，会污染判断。

因为它可能已经存在于：

• MEMORY.md
• index.json
• router.log
• engine.log
• 飞书上下文
• 当前对话上下文

所以每轮测试都应该使用唯一标识。

---

5.3 不要一开始就改核心脚本

如果核心脚本已经验收通过，不要因为前端表现异常就马上改代码。

先判断问题发生在哪一层：

• AGENTS.md 是否注入？
• Router CLI 是否正常？
• 飞书是否能执行指定命令？
• 自然语言是否触发正确入口？
• 后端日志有没有证据？

只有定位到脚本层问题，再改代码。

---

5.4 规则写进 AGENTS.md 不等于模型一定执行

这点非常重要。

模型可能“知道规则”，但执行时仍然走旧路径。

所以要通过测试拆分判断：

1. 它是否知道规则？
2. 它是否能说出正确命令？
3. 它显式执行命令时是否能走通？
4. 普通自然语言时是否也能走通？
5. 后端日志是否证明链路真实发生？

---

5.5 Router 和 Engine 不要同时作为常规入口暴露

如果总控文件里既写：

• Router 是默认入口

又列出：

• Engine current
• Engine query
• Engine write

模型就可能直接拿 Engine 命令执行。

所以更好的方式是：

• AGENTS.md 只暴露 Router
• Engine 命令放在 TOOLS.md 或 Registry 里
• Engine 只作为故障排查和底层执行层

---

5.6 Auditor 不能替代 Router

Auditor 负责判断系统是否健康。

Router 负责处理自然语言请求。

两者不能混用。

常见区分：

• 用户问“记忆系统是否正常？” → Auditor
• 用户问“查一下之前……” → Router
• 用户说“记一下……” → Router
• 用户问“这个 Skill 是否可用？” → Skill Auditor
• 用户问“我该用哪个 Skill？” → Skill Router

---

6. 常见失败模式

6.1 文件结构搭好了，但内容逻辑没升级

只建目录和空文件不代表系统升级完成。

必须补齐：

• Registry 内容
• Policy 内容
• Router 逻辑
• Auditor 逻辑
• 日志
• 验收报告

---

6.2 Router 本地可用，但总控没接入

Router CLI 能跑，不代表飞书会用它。

必须接入 AGENTS.md，并做飞书黑盒测试。

---

6.3 总控接入了，但模型仍绕过 Router

这种情况通常是因为：

• AGENTS.md 仍暴露 Engine 命令
• MEMORY.md / MEMORY_RULES.md 有旧入口
• 上下文里有旧操作惯性
• 测试用例重复导致误判
• 没有后端日志验证

---

6.4 只看前端，不看后端

这是最容易误判的地方。

前端回答“已完成”，但后端可能是：

• 直接 Engine
• 没有 Router
• 没有写入
• 没有重建索引
• 没有审计报告

---

6.5 改动后没有 checkpoint

只要没有 checkpoint，系统就处于未收口状态。

Change Guard 的最终目标不是 scan 出问题，而是让每次核心变更都有新基线。

---

7. 方法论在 Skill 子系统中的验证

Skill 子系统升级验证了：

• Skill Registry 可以统一管理 Skill 元信息
• Skill Router 可以完成能力选择和查询
• Skill Auditor 可以判断 Skill 是否安装成功、是否 ready、是否可用
• 测试不能只依赖目录或 openclaw skills list
• 必须用 Auditor 作为验收入口
• AGENTS.md 必须强制 Skill 验收问题先走 Auditor

Skill 子系统验证出的关键经验是：

能看到 Skill 文件，不代表 Skill 可用；必须有 Auditor 做结构化验收。

---

8. 方法论在 Memory 子系统中的验证

Memory 子系统升级验证了：

• Memory Engine 适合作为执行层
• Memory Router 适合作为自然语言入口
• Memory Auditor 适合作为健康检查入口
• MEMORY.md 需要清晰的长期事件追加区
• index.json 必须由脚本维护
• 飞书前端回复不能作为唯一判断依据
• 必须通过 router.log / engine.log / MEMORY.md 验证真实链路

Memory 子系统验证出的关键经验是：

记忆系统不是“写入文件”，而是“判断、沉淀、召回、审计、收口”的完整链路。

---

9. 这套方法如何迁移到专家子系统

专家子系统升级时，可以直接套用这套方法。

建议结构如下：

• EXPERT_REGISTRY.md：专家注册表
• EXPERT_RULES.md：专家治理规则
• expert_policy.json：专家策略配置
• EXPERT_INDEX.json：专家索引
• search_experts.py：专家检索执行层
• zhiwei_expert_router.py：专家自然语言路由层
• zhiwei_expert_auditor.py：专家审计层
• experts/logs/：专家路由与审计日志
• experts/reports/：专家审计报告

专家子系统的关键问题不是“能不能检索专家”，而是：

• 什么时候应该调专家？
• 调哪类专家？
• Top-K 是否合理？
• 专家结果是否需要融合？
• 是否存在专家漂移？
• 是否存在过度调用专家？
• 是否能证明专家路由链路真实发生？

所以专家子系统不应该只升级 search_experts.py，而应该升级成完整的 Expert System V2。

---

10. 我的最终方法论总结

这套方法论可以总结为一句话：

任何 AI Agent 子系统，只要从“单脚本能力”走向“长期运行能力”，就必须补齐 Registry、Policy、Router、Engine、Auditor、Logs、Reports、Index、AGENTS 接入和 Change Guard 收口。

更短一点：

先让能力可用，再让能力可治理。

Skill 子系统和 Memory 子系统已经证明了这条路径是可行的。

接下来升级专家子系统时，不应该重新摸索，而应该沿用这套经过实践验证的方法论。

---

11. 给未来自己的提醒

1. 不要急着写代码，先确认职责边界。
2. 不要把所有规则塞进 AGENTS.md。
3. 不要让模型在多个入口之间自由选择。
4. 不要只看前端回复，要看后端日志。
5. 不要重复使用同一测试标识。
6. 不要在没有定位清楚前修改核心脚本。
7. 不要忘记 Change Guard checkpoint。
8. 一个系统真正完成，不是它能跑，而是它能被验收、被追溯、被安全迭代。

---

12. 标准升级清单

每次升级一个子系统前，可以按下面清单自查：

• 是否明确了子系统边界？
• 是否保留了稳定执行层？
• 是否有 Registry？
• 是否有 Policy？
• 是否有 Router？
• 是否有 Auditor？
• 是否有 Logs？
• 是否有 Reports？
• 是否有 Index？
• 是否完成本地 CLI 验收？
• 是否完成前端黑盒测试？
• 是否完成后端日志验证？
• 是否接入 AGENTS.md？
• 是否避免 AGENTS.md 暴露多个冲突入口？
• 是否完成 Change Guard scan？
• 是否完成 validate？
• 是否完成 checkpoint？
• checkpoint 后 scan 是否为 changed_count = 0？

如果这些都完成，才可以认为一个子系统真正进入 V2 可治理状态。