OpenClaw 治理子代理设计：technical-documentation 技能中的 AGENTS/CONTRIBUTING 优先级审计与策略漂移检测

2026-09-05 10:37:25作者：史锋燃Gardner

本文以 OpenClaw 仓库中 .agents/skills/technical-documentation/agents/governance-agent.md 这份治理子代理（governance sub-agent）规格文件为核心，拆解它在技术文档审计流水线中的职责定位、模型分层与工具白名单设计、三类核心任务（规范源判定、冲突检测、命令示例验证）背后的判定规则，以及它的返回契约。读完后，你将理解如何为一个大型多代理编码仓库设计一个"只读、有界、可合并"的文档治理审计子代理，并能对照 OpenClaw 自身的 AGENTS.md/CLAUDE.md 符号链接布局验证这套治理策略。

1. 定位：technical-documentation 技能的四个子代理之一

governance-agent.md 是 technical-documentation 技能（入口文件 .agents/skills/technical-documentation/SKILL.md）内置的四个子代理之一。该技能的目的是"构建和评审对人与 AI 代理都清晰、可操作、可维护的技术文档"，包括贡献者治理文件（CONTRIBUTING.md）和代理指令文件（AGENTS.md 及其各类别名）。SKILL.md 在"Sub-agent orchestration guidance"一节中明确规定：当仓库较大或变更面较广时，优先使用子代理做有界的并行发现/评审，再把各自输出合并为一份连贯的交付物。四个子代理按分工与成本分层：

子代理	文件	思维模式 / 模型档位	职责
inventory-agent	agents/inventory-agent.md	fast / haiku	文件与配置发现、覆盖地图、缺失路径检查
governance-agent	agents/governance-agent.md	thinking / sonnet	AGENTS/CONTRIBUTING/别名的优先级、冲突与策略漂移
docs-framework-agent	agents/docs-framework-agent.md	thinking / sonnet	框架配置、相对路径基准、文件路径与 URL 路径映射检查
synthesis-agent	agents/synthesis-agent.md	long / opus	合并各子代理输出为一份去重、可执行的修复计划

governance-agent 处于这条流水线的中段：inventory-agent 先低成本枚举出"哪些治理面存在"，governance-agent 再对其中 AGENTS/CONTRIBUTING/别名 这一治理面做深度语义审计，最后 synthesis-agent 汇总。

2. 规格文件逐段解析

治理子代理的完整规格见 governance-agent.md，全文很短，但每个字段都有设计意图。

2.1 Frontmatter：模型档位、工具白名单与回合预算

---
name: governance-agent
description: Thinking-focused governance reviewer for AGENTS/CONTRIBUTING/alias precedence, conflict detection, and policy drift analysis.
model: sonnet
tools:
  - Read
  - Glob
  - Grep
permissionMode: default
maxTurns: 10
---

五个字段各自对应一种约束手段：

model: sonnet：选择"思考型"档位（Sonnet）。治理审计需要跨文件比对指令语义，比 inventory-agent 的纯枚举（haiku 档）贵，但又不需要 synthesis-agent 那种长上下文合并能力（opus 档）。从源码结构看，这套 fast/haiku、thinking/sonnet、long/opus 的三档划分在 SKILL.md 中被写成显式约定，即"能力需求决定模型成本"。
tools: Read / Glob / Grep：只读三件套——读取文件、按模式列文件、正则搜索。白名单里没有写文件类工具，意味着该子代理被架构上限制为"只报不修"：它只能产出冲突清单与建议，不能直接改动仓库。这与 SKILL.md 主流程"由主代理决定是否同趟修复"相衔接。对照 inventory-agent.md，inventory 档还多了 LS 工具（枚举目录更高效），而 synthesis-agent.md 只保留 Read（它只消费前序输出，不需要再搜索）。
permissionMode: default：四个子代理统一取默认权限模式，不额外提权或收窄，权限控制交给工具白名单本身。
maxTurns: 10：回合预算封顶。作为参考，inventory 为 6、synthesis 为 12——审计深度的预算也随职责复杂度递增。

2.2 角色、目标、任务与返回契约

正文定义了该子代理的四段式契约：

角色：You are the governance sub-agent for technical documentation（技术文档的治理子代理）。

Goals（目标）：

validate AGENTS/CONTRIBUTING/alias alignment and precedence —— 校验 AGENTS.md、CONTRIBUTING.md 与别名文件之间的一致性（alignment）与优先级（precedence）；
identify policy drift and conflicting instructions —— 识别策略漂移与相互矛盾的指令。

Tasks（任务）：

determine canonical instruction source and alias compatibility mapping —— 判定规范（canonical）指令源，并建立别名兼容性映射；
detect conflicts across nested scope files and tool-specific rule consumers —— 跨嵌套作用域文件（nested scope files）和工具特定的规则消费方（tool-specific rule consumers）检测冲突；
validate command examples against stated governance expectations —— 用文档中声明的治理期望来验证其中的命令示例。

Return（返回契约）：

precedence model —— 一份优先级模型；
conflict list with severity —— 带严重等级的冲突清单；
recommended low-risk remediations —— 建议的低风险修复措施。

"返回契约"是这个规格最值得注意的部分：它不返回自由文本，而是返回三种结构化产物，使 synthesis-agent 能够稳定地把治理审计结果与其他子代理的输出做归并、去重和排序（synthesis 的规格明确要求"normalize to one precedence model for governance decisions"，即把各代理发现归一到同一个优先级模型上，前提正是 governance-agent 先交出一份可归一的优先级模型）。

3. 职责一：规范源判定与别名兼容性映射

"哪些文件是规范源、哪些只是别名"是治理审计的第一问。该子代理的判定规则继承自技能的参考规则集 .agents/skills/technical-documentation/references/agent-and-contributing.md，其中"Canonical and alias policy"一节给出五条硬规则：

AGENTS.md 存在时即为规范源（canonical）；
不存在时，取最近（nearest）的别名文件为规范源；
兼容性面必须显式维护，涉及 AGENTS.md、AGENT.md、.cursorrules、.cursor/rules/*、.agent/、.agents/、.pi/；
使用别名时必须文档化它如何映射回规范策略（或在支持时用符号链接）；
策略保持 DRY：一份共享策略核心，通过别名/符号链接暴露，而非复制规则文本。

发现阶段还规定了具体的检索命令，即在该参考文档中给出的 rg --files 多 glob 模式，一次性枚举 AGENTS.md、CONTRIBUTING.md、CLAUDE.md、AGENT.md、.cursorrules、.agent/**、.agents/**、.pi/** 等所有治理面文件——这正是 governance-agent 拿到 Glob/Grep 工具后要执行的动作。

OpenClaw 仓库本身就是这套政策的活样本。 用 find 枚举当前仓库可见：

根目录 AGENTS.md（约 66KB、362 行）是唯一的根规范源；
根目录 CLAUDE.md 是指向它的符号链接（CLAUDE.md -> AGENTS.md），而非第二份文件；
仓库内共有 24 处嵌套作用域的 AGENTS.md（如 docs/AGENTS.md、extensions/AGENTS.md、scripts/AGENTS.md、src/plugin-sdk/AGENTS.md、test/AGENTS.md、ui/AGENTS.md、apps/android/AGENTS.md、apps/ios/AGENTS.md 等），每一处都伴随一个同路径的 CLAUDE.md 符号链接，数量与 AGENTS.md 一一对应，没有任何"实体第二份文件"；
根 AGENTS.md 第 22 行把这一布局写成了硬性治理规则："New AGENTS.md: add sibling CLAUDE.md symlink; edit AGENTS.md only."（新增 AGENTS.md 时必须加同目录 CLAUDE.md 符号链接，且只允许编辑 AGENTS.md）。

对照治理规则集，可以逐条验证当前仓库状态：规范源唯一（规则 1）成立；别名映射回规范策略（规则 4）以符号链接方式成立；策略 DRY（规则 5）成立——CLAUDE.md 不承载独立内容，Claude 系工具读到的就是 AGENTS.md 原文。若某处 CLAUDE.md 是实体文件且内容与 AGENTS.md 分叉，那正是 governance-agent 要在冲突清单里标出的典型"policy drift"案例。

3.1 符号链接状态的操作性检查清单

同一参考文档的"Symlink and compatibility operations"一节还给了可执行的符号链接校验步骤，governance-agent 的审计可以逐条落盘为检查项：

若 .agents/ 存在而 .cursor 缺失：应创建 .cursor -> .agents 符号链接（用于 Cursor 规则自动加载）；
若 .cursor 是指向其他目标的符号链接：修正目标或书面记录其必须不同的原因;
若 .cursor 是真实目录/文件：视为迁移冲突，替换前必须先询问；
规则载荷经规范目录验证：.agents/rules/*.mdc 需有合法 frontmatter（description、globs、按需 alwaysApply）；命令路由用 .agents/commands/*.md；MCP 配置为 .agents/mcp.json；
所有已应用的符号链接修复与未解决的兼容性缺口，记入 validation notes。

4. 职责二：跨嵌套作用域与工具消费方的冲突检测

governance-agent 的第二项任务"across nested scope files and tool-specific rule consumers"对应两类冲突源：

嵌套作用域冲突——根与子目录指令不一致。OpenClaw 的根 AGENTS.md 开篇即声明分层模型："Telegraph style. Root rules only. Read scoped AGENTS.md before subtree work."（电报风格，根规则只管根；子树工作前先读作用域内 AGENTS.md），其"Map"一节进一步列出了作用域指南的分布位置（extensions/、src/{plugin-sdk,channels,plugins,gateway,agents,tui}/、test/、docs/、ui/、scripts/ 及更深层子树指南），并规定"始终检查被改动路径最近的 AGENTS.md"。从源码结构看，这意味着优先级模型是自顶向下叠加、就近优先：审计时必须检查每一对"根规则 vs 作用域规则"是否存在语义矛盾（例如根规定 SQLite-only 存储而某子树指南仍推荐 JSON sidecar 这类级别的不一致）。

工具消费方冲突——不同代理平台消费规则文件的方式不同。参考规则集的"Context-awareness by agent platform"一节给出对应策略：

对 Cursor 与 Claude 风格的 glob 消费方：规则文件要窄而有界，避免引用过大的路径集导致上下文膨胀；
对 Codex 风格的工作流：偏好显式文件引用与确定性命令；
长 runbook 应移出顶层策略文件，改为链接到作用域文档；
无论哪种消费方，都要保证存在"happy path"，让 Codex、Claude 等编码代理都能走通。

这类冲突的特点是：文件本身没有语法错误，但同一策略对 A 类代理是"上下文膨胀"、对 B 类代理是"指令缺失"。这正是 governance-agent 被标注为 description: Thinking-focused 的原因——它要做的是跨消费方的语义对齐，而不是字符串比对。

4.1 高优先级缺陷的判定标准

参考规则集"Proactive issue discovery and remediation"一节把四类问题直接定义为 high-priority defects（高优先级缺陷），可作为 governance-agent 输出 severity 等级时的标尺：

被引用的文件缺失（missing referenced files）；
不存在的 setup 命令（non-existent setup commands）；
命令作用域不匹配（command scope mismatches）；
分支/提交策略冲突（branch/commit policy conflicts）。

同时它规定了审计行为的底线："Do not stop at caveat-only notes when a low-risk fix is clear"——当修复明显且低风险时，不能只留一句提醒就结束；若规范入口文件缺失（例如文档依赖的目录 README.md 不存在），应创建最小可操作文件并更新引用。这一条解释了 governance-agent 返回契约中的第三项"recommended low-risk remediations"：它虽然只读，但产出的必须是可直接执行的修复建议，而非泛泛的风险提示。

5. 职责三：命令示例与治理期望的一致性验证

第三项任务要求"validate command examples against stated governance expectations"——即把治理文档中出现的每条命令示例，与文档自己声明的工作流期望做交叉验证。参考规则集的"Discovery"一节补充了这条任务背后的工程判断：

代理偏好简单明确的终端命令，因此定义良好的 make * 或 npm run * 脚本面是理想状态；
代理能通过 shell 补全发现命令，提供 shell 补全有助于命令可发现性。

落到 OpenClaw 仓库，验证对象就是根 AGENTS.md 与 CONTRIBUTING.md 中声明的 pnpm * 脚本族（例如 pnpm docs:list、pnpm check:* 边界检查、pnpm install 等，均可在 package.json 的 scripts 段对照确认）：文档承诺的命令是否真实存在、作用域是否匹配当前工作目录（仓库根 vs worktree vs 插件子包），都属于该任务的检查范围。参考规则集同时把"CONTRIBUTING 尺寸与范围控制"纳入治理面：根 CONTRIBUTING.md 应聚焦 setup、issue 流、PR 流、测试与评审门槛，细节外链到 issue/PR 模板或文档站；文件膨胀时按域拆分并从根链接，同时为机器可读性优化（"Optimize for agent/machine readability as well as humans"）。

6. 返回契约如何被下游消费

governance-agent 的三份输出——优先级模型、带严重等级的冲突清单、低风险修复建议——最终交给 synthesis-agent.md 定义的合并环节：先阻断项后非阻断项排序、把治理决策归一到"one precedence model"、删除重复建议与互相矛盾的修复、产出执行就绪的简洁计划，并附"done vs pending"验证摘要与显式剩余缺口。SKILL.md 的最终交付物清单也随之展开：agent 指令面地图（primary file、alias files、Codex/Claude/Cursor 处理方案）、文档面覆盖地图、自动检测到的问题与已应用修复（或 report-only 发现）、子代理委派说明（委派了哪些范围、发现如何合并）。换言之，governance-agent 的"Return"段不是一份格式说明，而是与上游 inventory、下游 synthesis 之间的接口协议。

7. 可复用的设计模式总结

把 governance-agent.md 放回技能目录看，它示范了一组可迁移到任何大型多代理仓库的子代理设计模式：

职责单点化：一个子代理只守一个治理面（这里是 AGENTS/CONTRIBUTING/别名），与 inventory（覆盖枚举）、docs-framework（框架配置）严格不重叠，便于并行且输出可机械合并；
能力分层定价：枚举用 haiku（6 回合），治理评审用 sonnet（10 回合），合并用 opus（12 回合），成本与认知需求对齐；
工具白名单即权限边界：Read/Glob/Grep 的只读三件套从架构上保证"审计者不改代码"，修复权保留在主代理，天然形成 report/fix 分离；
结构化返回契约：优先级模型 + 带严重等级的冲突清单 + 低风险修复建议，三类产物都可被下游去重、排序与执行，避免自由文本报告带来的合并歧义;
策略 DRY 与别名显式化：以 AGENTS.md 为唯一规范源、CLAUDE.md 等别名一律符号链接（OpenClaw 全部 24 处均如此），使"漂移检测"从内容比对退化为"链接状态 + 唯一性"两类廉价检查。

适用前提与限制：该规格属于 OpenClaw 仓库内置的 technical-documentation 技能资产，其模型档位（haiku/sonnet/opus）与工具名（Read/Glob/Grep/LS）针对 Claude 系子代理运行时命名；移植到其他代理平台时，frontmatter 字段与工具白名单需要按目标运行时的能力做等价映射，但"只读审计 + 结构化返回 + 分层模型"的骨架可以直接复用。