虾滑 OpenClaw 工作区治理（OpenClaw Workspace Governance）

🚨 高危/重要提示 (IMPORTANT WARNING) 🚨
这不是一个普通的工具型 Skill，而是针对 OpenClaw 工作区的系统级架构升级与治理方案。
在让你的 Agent 实施本指南之前，请务必对你的 Workspace 进行完整备份，并确保你理解其对文件状态和检索优先级的改变。请勿在未做快照的生产环境中盲目运行全自动治理！

This is NOT a standard tool-level skill. It is a system-level architecture upgrade and governance framework for your OpenClaw workspace.
Before allowing your Agent to implement these guidelines, you MUST take a full backup of your workspace. Do not run automated governance in a production environment without understanding how it alters document states and retrieval routing.

这是一个面向复杂 OpenClaw 工作区的治理型 skill。它不是为了制造更多流程，而是为了在复杂度已经上来之后，帮你压住漂移、明确当前事实层、缩小 live docs 面积，并让语义检索变得更可控。

系统能力详解 (System Capabilities)

本 Skill 提供了一套完整的系统级框架，赋予你的 OpenClaw 以下核心能力：

• 多 Agent 协作架构 (Multi-Agent Architecture)：建立以 Supervisor 为中心的调度机制，实现“写审分离”。明确区分代码编写、代码审查、规则审核、文档撰写等专职岗位，防止单一 Agent 越权闭环。
• 分层记忆系统 (Layered Memory System)：告别无序的长文档堆砌。建立从“原始日志 (Daily Notes)”到“主题卡片 (Topic Cards)”，再到“长期记忆 (Long-Term Memory)”的逐层蒸馏与质量门控机制。
• 语义检索与路由 (Semantic Retrieval Routing)：将系统查询分类（如：状态查询、规则边界、历史溯源等），并建立基于桥接文件 (Bridge Files)、结构化记忆与 qmd 语义搜索的精准召回优先级。
• 审批与安全治理 (Approval & Governance)：强制核心文件（如 AGENTS.md）的修改必须经过独立评审与人工授权；内置针对特定岗位的“防偷懒协议（代码交付契约）”，保障自动化任务的执行完整性。

适用场景

当你的工作区已经出现真实复杂度时，再用这份 skill。典型信号包括：

• 多个 Agent 或多角色执行路径已经出现
• 文档、记忆、状态层越来越多
• 回答“现在到底什么是真的”开始变难
• semantic search（语义搜索）有用，但不再能无脑相信
• live docs 过多、working set 不清、维护开始失控

⚠️ 这是进阶 skill，不是新手入门包，也不是 v1 的全自动 orchestrator。

非目标

这份 skill 不会替你自动拍板、自动改规则，也不会把所有旧文档都继续维持成“活文档”。它提供的是治理 playbook，不是无限自动化引擎。

它不试图做这些事：

• 发布私有角色 lore 或内部组织文化
• 打包个人记忆、日记或私有运行历史
• 自动决定审批结果
• 自动改政策或规则
• 在 v1 里做全自动多 Agent 编排
• 因为“怕以后要用”而让所有旧文档都保持 live

快速开始

先别急着改文件，先判清楚你遇到的是哪一种 drift。主线只有六步：

1. 分类问题
2. 选择治理路径
3. 找到应该回答问题的权威事实层
4. 收紧文档角色和 freshness 边界
5. 用代表性问题验证
6. 在主线足够完整时主动收口

如果工作区现在很乱，先减少歧义，不要先加流程。

核心工作流

1. 先分类问题

先判断你面对的是哪一类 drift，不要一上来就盲改文件。先分清类型，后面所有动作才不会跑偏。

你通常会遇到这些类型：

• governance drift：角色、审批、审查边界或规则正在漂
• current-state drift：现在到底什么是真的变得不清楚
• retrieval drift：semantic search、bridge files、topic cards、long-term memory 开始互相打架
• doc drift：旧文档还在假装自己代表当前事实
• maintenance drift：live docs 太多，没有 working set，也没人做 freshness checks
• phase drift：系统不停产出流程文档，却没有收口

不要先改文件，先判类型。

2. 让不同变更走对治理路径

实现改动、文档解释改动、治理/规则改动，不是一回事。复杂工作区里，最怕把所有改动都走同一条线。

把工作类型区分清楚：

• implementation change：普通实现或落地改动
• documentation/explanation change：文档措辞、状态标签、说明层改动
• governance/policy/process change：角色边界、审批规则、路由规则、维护规则改动

可使用这些通用角色：

• Coordinator：定义问题、选路径、负责收口
• Implementer：执行文件/脚本/操作改动
• Reviewer：检查实现质量，揪明显问题
• Policy Auditor：审治理、流程、规则变化
• Consensus Peer：高风险结构变更前的可选同级会审

常见部署形态：

• 2-agent：Coordinator+Implementer / Reviewer
• 3-agent：Coordinator / Implementer / Reviewer
• 4-5-agent：额外加入 Policy Auditor 和可选 Consensus Peer

基本规则：

• 高风险工作里，不要让同一角色既实现又做最终审查
• 治理/政策/流程改动要过 Policy Auditor
• 高风险结构改动前，如果单一规划者判断不够，插入 consensus-peer 会审
• 如果工作区里只有 1 个 agent，要明确写出“本来这里该有第二审”，不要假装自审等价

按需阅读：

• references/multi-agent-governance.md

v1 边界：

• 这份 skill 提供可部署的治理指导
• 它不是 v1 的全自动多 Agent 编排系统

3. 建立权威事实分层

不要把所有资料平均对待。真正的关键不是“资料多不多”，而是冲突时谁说了算。

把这些层分清楚：

• canon：规则、审批、硬边界
• bridge/current-state：回答“现在什么是真的”的短文件
• health/consistency：运行健康和一致性状态
• runtime snapshot：某一时点的运行事实
• structured memory：中等持久度的 topic/index 卡片
• long-term memory：只保留高持久事实
• historical docs：背景、旧阶段、旧计划、审计、报告

两层冲突时，不要平均；必须决定谁赢。

按需阅读：

• references/source-of-truth-layering.md
• references/query-class-routing.md

4. 先分 query class，再决定检索顺序

别抽象地问“语义搜索靠不靠谱”。真正该问的是：对哪一类问题靠谱？在什么 runtime / cache 对齐状态下靠谱？它是主裁决层还是辅助召回层？

建议的 query class：

• system-state
• governance / rule-boundary
• runtime-now
• weekly-review / approval-state
• user-preference / profile
• historical trace / evidence
• maintenance / upkeep

默认策略：

• governance → canon first
• system-state → bridge/health first
• runtime-now → snapshot first
• user-preference → curated profile/manual sources first
• historical trace → discovery + verification
• semantic search → 除非明确验证更强，否则只作为 supporting layer

按需阅读：

• references/query-class-routing.md
• references/semantic-search-diagnostics.md

5. 给文档打角色边界

旧文档最危险的不是存在，而是它还在假装自己代表 current truth。把 live docs 面积压小，系统才会稳。

常见标签与角色：

• historical-reference
• needs-refresh
• active/live maintenance docs
• special-case active safety restriction

尽量定义一个最小 live subset，其他默认降级成次级参考层。

按需阅读：

• references/live-vs-historical-docs.md

6. 建 working set 和 freshness checks

working set 不是“所有重要文件”，而是“必须持续保鲜的最小活跃集合”。不要用一个统一阈值去管所有文档。

典型 working set 包括：

• health / consistency 文件
• bridge/current-state 文件
• runtime snapshot
• entrypoint/index docs
• 只有最高价值的 topic cards

用分组阈值，不要用一个笼统阈值：

• health/bridge/runtime/entry docs 用更短阈值
• structured topic/index docs 用更长阈值

用 freshness checker 把“谁应该记得更新一下”变成可重复执行的检查。

按需阅读：

• references/freshness-discipline.md

7. 认真诊断 semantic-search runtime

语义检索出问题时，最常见的坑不是模型不行，而是 path alignment、cache/index 混线，或者 split-brain（诊断一个索引、查询另一个索引）。

诊断时建议按这条线走：

1. 先记录 before-state baseline
2. 确认 runtime config 与 cache/index context 是否对齐
3. 检查是否存在 split-brain
4. 修掉明显的 indexing/embedding 缺口
5. 用少量代表性 query classes 回归验证
6. 不要给 blanket trust label，要按 query class 标可信度

按需阅读：

• references/semantic-search-diagnostics.md

8. 用代表性问题验证，而不是只看结构

结构看起来整齐，不等于系统真的能回答问题。至少拿 system-state、governance、maintenance、historical/preference 这几类真实问题测一轮。

最低验证集：

• 一个 system-state 问题
• 一个 governance 问题
• 一个 maintenance 问题
• 一个 historical 或 preference 问题

判定结果建议只用三种：

• PASS
• PASS WITH ESCALATION
• FAIL

只有当较小的 live subset 也确实能回答日常问题时，才算成立。

9. 主动收尾，不要无限扩相

如果一个 phase 已经主线落地，就该收口进 maintenance observation（维护观察期），而不是继续生产更多流程文档。

每个 phase 都要明确：

• 什么是 landed
• 什么是 improving
• 什么是 deferred
• 主线是否已经足够完整，可以关闭

一旦主线够完整：

• 转入 maintenance observation
• 保持 live subset 尽量小
• 做小修，不要再开一轮 sprawling phase

按需阅读：

• references/completion-criteria.md

v1 推荐脚本

这些脚本覆盖 v1 最关键的三条治理检查线：freshness、semantic runtime、doc status。

• scripts/freshness-check.py
• scripts/semantic-runtime-check.sh
• scripts/doc-status-scan.py

v1 推荐参考文档

这些 references 构成 v1 的主参考集；它们负责解释治理原则，不负责替你自动执行一切。

• references/multi-agent-governance.md
• references/source-of-truth-layering.md
• references/query-class-routing.md
• references/live-vs-historical-docs.md
• references/freshness-discipline.md
• references/semantic-search-diagnostics.md
• references/completion-criteria.md

v1 推荐示例

先用这些示例建 working set、system-state index 和 health 示例，再按你的工作区实际情况收窄。

• assets/examples/working-set.example.md
• assets/examples/working-set.example.json
• assets/examples/current-health.example.json
• assets/examples/system-state-index.example.md

v1 叙事要收紧

这是一份 workspace governance tool / governance playbook。它包含多 Agent 治理指导，但它不是 roleplay 包，也不是 v1 的全自动 multi-agent orchestrator。

它最核心的承诺只有五条：

• 减少 drift
• 让 current truth 更容易识别
• 把 live docs 面积压小
• 让 semantic retrieval 更可控
• 让维护更可持续

发布与草案边界

当前正式发布内容以本目录下的 package-local 文件为准。旧的 docs/skill-draft-* 文件属于设计历史，不应继续和当前发布包竞争解释权。

Package rule

During the current release line, review the package-local files in this directory first. Treat older docs/skill-draft-* files as drafting history unless you are explicitly tracing design history.