Tools
Workspace Governance
By OpenClaw-native workspace governance plugin
Install
openclaw plugins install /path/to/prj-workspace-governanceREADME
# Workspace Governance
Workspace Governance 是一个面向 OpenClaw 的原生治理插件。
它不重写龙虾的 `MEMORY.md + memory/` 和 `skills/` 架构，只在原生结构之上补一层：
- workspace 扫描
- 结构校验
- skills / memory 摆位治理
- AI 推荐
- review 清单
- 变更前 snapshot
本项目的 spec 只维护在项目自己的 `openspec/` 下，不依赖根级 `workspace/openspec`。
## 现在已经做到的事
这版已经有三层入口：
- OpenClaw slash command：`/governance ...`
- OpenClaw 插件 CLI：`openclaw governance ...`
- 本地开发 CLI：`node ./src/cli.js ...`
当前支持的核心动作：
- `snapshot`
- 对目标 workspace 生成变更前快照
- `validate`
- 规则扫描顶层 hygiene、layer 结构、skills 摆位、memory 落点
- `summarize`
- 输出 workspace / skills / memory 摘要
- `recommend`
- 默认走 AI，为 `workspace | skills | memory | all` 生成建议
- `review`
- 汇总待确认清单
- `model show`
- 查看当前治理模型
- `models`
- 列出当前 OpenClaw 已配置模型，供 `recommend --model` 选择
## 什么场景用什么动作
可以把这些动作理解成一组可组合的治理动作：
1. 需要人工留恢复点时，手动 `snapshot`
2. 查规则问题时 `validate`
3. 需要理解现状时 `summarize`
4. 需要方向和落点时 `recommend`
5. 需要形成待办和审批时 `review`
具体场景可以这样选：
### `snapshot`
适合场景：
- 你准备整理 workspace
- 你准备批量移动目录、skills、memory
- 你明确想手动留一个恢复点
例子：
- “我要开始整理 `dom-company-ma` 的 skills，先备份一下当前 workspace”
- “我要把一批脚本从根目录下沉到项目内，先打一份快照”
命令：
```bash
/governance snapshot
node ./src/cli.js snapshot --root <workspace-root>
```
### `validate`
适合场景：
- 你想快速知道“哪里不对”
- 你不需要 AI，只要稳定的规则扫描结果
- 你在做 CI / 日常巡检 / 人工 check
例子：
- “我想知道当前顶层还有没有脏目录、runtime 漂在 root”
- “我想只查 skills 摆位，不看别的”
- “我想只查 memory 落点，不做建议”
命令：
```bash
/governance validate
/governance validate skills
/governance validate memory
node ./src/cli.js validate --root <workspace-root>
```
### `summarize`
适合场景：
- 你不是先找错误，而是先想搞清楚当前 workspace 的分布
- 你要快速看 domain / project / skills / memory 的现状
- 你想给自己或 subagent 一个结构概览
例子：
- “我现在这个 workspace 到底有哪些 domain root 和 project root”
- “当前 skills 都落在哪几层”
- “主 memory 和 domain memory 分布是什么样”
命令：
```bash
/governance summarize
/governance summarize skills
/governance summarize memory
node ./src/cli.js summarize skills --root <workspace-root>
```
### `recommend`
适合场景：
- 你不只想知道现状，而是想让 AI 告诉你更合理的摆位和结构
- 你要决定一个 skill 该留在 global、domain 还是 project
- 你要判断 memory 是继续留 root、还是只做 domain-local anchor
例子：
- “`jira` / `riplus` / `confluence-doc-analyzer` 应不应该放到 `dom-company-ma/skills`”
- “`dom-company-ma/MEMORY.md` 是否应该保留 domain-local，同时在根级 memory 做 anchor”
- “我的 workspace 下一步最适合怎么继续收敛结构”
命令：
```bash
/governance recommend skills --model openai-codex/gpt-5.4
/governance recommend memory --model minimax-cn/MiniMax-M2.5
/governance recommend all --model openai-codex/gpt-5.4
```
注意：
- `recommend` 默认走 AI
- 建议显式传 `--model`
- `raw[*].agentMeta` 能看到本次 recommendation 实际使用的模型
### `review`
适合场景：
- 你已经有扫描结果和建议，想把它们收成“待确认清单”
- 你要准备后续 `apply --dry-run` 或人工执行计划
- 你要把一轮治理输出变成可审批的 action list
例子：
- “把当前 root hygiene 和 skills/memory 建议整理成待确认项”
- “我要一份 rename / move / keep / root-anchor 的 review list”
命令：
```bash
/governance review
node ./src/cli.js review --root <workspace-root>
```
### `model show`
适合场景：
- 你要确认当前治理模型到底怎么定义 reserved names、layer prefixes、ignore 策略
- 你在调规则，不是在扫 workspace
例子：
- “我忘了现在默认把哪些目录当 native reserved”
- “我想看当前 prefix 和 root metadata 文件策略”
命令：
```bash
/governance model show
node ./src/cli.js model show
```
### `models`
适合场景：
- 你准备跑 `recommend`
- 你想先看当前 OpenClaw 已配置模型有哪些可选项
- 你想确认一个 `provider/model` key 是否存在
例子：
- “我这次要用 MiniMax 做 skills recommend，先看 key 是什么”
- “我想知道当前默认模型和 fallback 模型列表”
命令：
```bash
/governance models
node ./src/cli.js models --json
```
## 分层理念
治理目标是“严格顶层 + 原生内部结构”。
- 根目录只保留：
- 原生保留项：`AGENTS.md`、`TOOLS.md`、`MEMORY.md`、`memory/`、`skills/`
- 你的根级元信息：`SOUL.md`、`USER.md`、`IDENTITY.md`、`HEARTBEAT.md`
- 基础设施目录：`plugins/`、`openspec/`
- layer roots：`dom-*`、`prj-*`、`scr-*`、`arc-*`
- `dom-*`
- 领域工作区，放领域共享 skill、领域文档、领域长期知识
- `prj-*`
- 项目工作区，放项目代码、脚本、项目 `.env`、项目运行环境、项目记忆
- `scr-*`
- 临时实验区
- `arc-*`
- 归档区
`.env` 不是 OpenClaw workspace 的官方保留文件。默认策略是：
- 项目私有 `.env` 放 `prj-*`
- 领域共享环境放 `dom-*`
- 根级 `.env` 只在它确实属于整个主 workspace 基础设施时才保留
## Memory 和 Skills 立场
### Memory
保留龙虾原生 memory 架构：
- `MEMORY.md`
- `memory/YYYY-MM-DD.md`
当前插件只做：
- placement review
- scope summary
- AI recommendation
当前插件不做：
- 自动改写 `MEMORY.md`
- 自动迁移 memory
- 重造 memory 容器
注意：
- 主 workspace 默认 memory search 只覆盖当前 agent workspace 根的 `MEMORY.md` 和 `memory/**`
- `dom-*` / `prj-*` 下的 memory 是兼容扩展，但不会自动进入根级 memory search
### Skills
保留龙虾原生 `skills/` 架构：
- 根级 `skills/` 视为 global skills
- `dom-*/skills` 视为 domain skills
- `prj-*/skills` 视为 project skills
- 隐藏宿主目录下的 `*/skills` 默认忽略，不纳入治理 finding
当前插件只做：
- placement review
- reusable scope summary
- AI recommendation
当前插件不做：
- 自动迁移 skills
- 发明新的 skill 容器命名体系
## 安装
正式入口以 OpenClaw 插件安装为准：
```bash
openclaw plugins install /path/to/prj-workspace-governance
openclaw gateway restart
```
安装后应能在插件列表中看到：
- `workspace-governance`
- `status = loaded`
- `commands` 包含 `governance`
- `cliCommands` 包含 `governance`
## 怎么用
### 列模型
```bash
/governance models
node ./src/cli.js models --json
```
### 查看模型规则
```bash
/governance model show
node ./src/cli.js model show
```
### 做快照
```bash
/governance snapshot
node ./src/cli.js snapshot --root <workspace-root>
```
### 做规则校验
```bash
/governance validate
/governance validate skills
/governance validate memory
node ./src/cli.js validate --root <workspace-root>
```
### 做摘要
```bash
/governance summarize
/governance summarize skills
/governance summarize memory
node ./src/cli.js summarize skills --root <workspace-root>
```
### 做 AI 推荐
`recommend` 默认走 AI，建议显式传模型：
```bash
/governance recommend skills --model openai-codex/gpt-5.4
/governance recommend memory --model minimax-cn/MiniMax-M2.5
/governance recommend all --model openai-codex/gpt-5.4
```
本地 CLI：
```bash
node ./src/cli.js recommend workspace --model openai-codex/gpt-5.4 --root <workspace-root>
node ./src/cli.js recommend skills --model minimax-cn/MiniMax-M2.5 --json --root <workspace-root>
node ./src/cli.js recommend memory --model openai-codex/gpt-5.4 --json --root <workspace-root>
```
### 做 review
```bash
/governance review
node ./src/cli.js review --root <workspace-root>
```
## 输出内容
当前工具会产出：
- `findings`
- `summary`
- `recommendations`
- `reviewItems`
- `workspaceProfiles`
其中 `workspaceProfiles` 是 routing-ready 的 workspace 认知层，给主 session / agent routing 用。
recommend 的 JSON 输出会包含：
- `model`
- `recommendations[]`
- `grouped`
- `raw`
`raw[*].agentMeta` 可用于确认本次 recommendation 实际使用了哪个模型。
## 当前状态
已经验证通过的能力：
- `npm test`
- `node ./src/cli.js models --json`
- `node ./src/cli.js summarize skills --root <workspace-root>`
- `node ./src/cli.js recommend skills --model minimax-cn/MiniMax-M2.5 --json --root <workspace-root>`
- `node ./src/cli.js recommend memory --model openai-codex/gpt-5.4 --json --root <workspace-root>`
其中 `recommend skills --model minimax-cn/MiniMax-M2.5` 已实际返回：
- `agentMeta.provider = minimax-cn`
- `agentMeta.model = MiniMax-M2.5`
说明显式模型选择已经真正生效，不再是假切换。
## 已知限制
- 当前不做自动迁移 `skills/` 或 `memory`
- 当前不做 `apply approved`
- 当前 snapshot 是可选手动命令，不是默认流程，也不是每次自动备份
- 这台机器上的 `openclaw governance ...` 外层 CLI 目前受 OpenClaw 自身 Node runtime 问题影响，可能报：
- `enableCompileCache` import error
- 在这个环境里，推荐优先使用：
- `/governance ...`
- `node ./src/cli.js ...`
## 下一步
更适合继续补的方向：
- 更细的 skills placement 语义判断
- 更细的 memory scope mismatch 判断
- workspace registry 强化
- `review -> apply --dry-run`
tools
Comments
Sign in to leave a comment