evolcore 0.0.23 → 0.0.25

package/kits/docs/evolcore/group-rules.md

@@ -1,251 +1,251 @@
-# ec group rules — 群规则文件
-
-管理 AUN 群空间中的 `/rules.md`。群规则文件用于定义本群特有的工作流程、职责分工、交付格式、限制条件和升级路径；发布后，EvolCore 默认会在该群的对话上下文中加载，本地 Agent 也可用 `groupRules.mode` 选择忽略。
-
-以自己的 AID 为操作者 `<from>`，群 AID 为 `<group-id>`。
-
-## 与入群规则的区别
-
-`ec group rules` 同时承载两类不同能力：
-
-| 能力 | 命令 | 用途 |
-|------|------|------|
-| 群规则文件 | `get/set/publish` | 管理注入上下文的群空间 `/rules.md` |
-| 入群规则 | 无动作或 `--mode` 等选项 | 管理 open、approval、invite_only、closed 等加入策略 |
-
-本文只说明群规则文件。入群规则的用法见 `group.md`。
-
-## 常用命令
-
-```bash
-# 查看当前已发布且有效的群规则
-ec group rules <from> <group-id> get
-
-# 上传本地文件到 /rules.md 并立即发布
-ec group rules <from> <group-id> set <file>
-
-# 发布群空间中当前已有的 /rules.md
-ec group rules <from> <group-id> publish
-```
-
-所有命令均支持 `--format json`。
-
-## 本地加载策略
-
-`ec group rules get/set/publish` 管理远端群规则；`groupRules.mode` 管理当前 Agent 是否把远端规则
-读取并注入上下文。两者互不替代。策略支持 Agent 默认值和当前群 relation 覆盖，优先级为：
-
-```text
-Agent groupRules.mode -> 当前群 relation groupRules.mode -> 缺省 load
-```
-
-```bash
-# 当前群的有效策略与来源
-ec config get groupRules.mode \
-  --self bot.agentid.pub --peer aun#g-team.agentid.pub --format json
-
-# 只忽略当前群；重新设为 load 可恢复
-ec config set groupRules.mode ignore \
-  --self bot.agentid.pub --peer aun#g-team.agentid.pub
-ec config set groupRules.mode load \
-  --self bot.agentid.pub --peer aun#g-team.agentid.pub
-
-# 删除当前群覆盖，回落 Agent 默认值或缺省 load
-ec config unset groupRules.mode \
-  --self bot.agentid.pub --peer aun#g-team.agentid.pub
-
-# 设置 Agent 默认策略；只能从允许 Agent 级写入的私聊或控制面执行
-ec config set groupRules.mode ignore --self bot.agentid.pub
-```
-
-`groupRules.mode` 只能由当前 Agent 的实际 owner 修改；DaemonOwner 不会仅因进程角色而获得该权限，
-其他角色仍可读取当前 relation 的有效值。
-在群聊中，即使 owner 也只能修改当前群 relation，不能修改 Agent 默认值。命令沿用既有
-`ec config set/unset` 的授权、selector 和输出语义，不新增 Menu 协议。
-
-`ignore` 从配置提交后开始处理的新 turn 生效，并保证不访问远端规则、不读取本地
-`rules.md`、不注入规则正文；旧物化文件会保留，但不能作为回退来源。切回 `load` 后仍须重新完成
-远端元数据校验。配置切换不会清空、新建或 fork 会话，也不会删除已进入恢复会话历史的旧内容。
-Claude/Codex 的后续 turn 会按新策略重新组装上下文；其他 runner 仍保存配置，但 Menu 成功输出会
-提示新建或清空该群会话后生效。
-
-## 更新规则
-
-日常更新直接使用 `set`：
-
-```bash
-ec group rules admin.agentid.pub g-team.agentid.pub set ./rules.md
-```
-
-成功后会依次完成：
-
-1. 检查本地文件是普通文件、有效 UTF-8，且不超过 4KB。
-2. 原样上传到 `<group-id>:/rules.md`。
-3. 读取远端文件的 `size + mtimeMs`。
-4. 更新 signed `rules.content`，使该文件版本成为当前有效群规则。
-5. 再次检查远端 `size + mtimeMs`，防止发布期间文件被并发覆盖。
-6. 由发布者发送 `group.rules.updated` 群通知。
-
-命令不会规范化换行或重写正文。
-
-## 查看规则
-
-```bash
-ec group rules bot.agentid.pub g-team.agentid.pub get
-```
-
-普通输出在校验通过后直接打印 Markdown 正文。需要查看状态和元信息时使用：
-
-```bash
-ec group rules bot.agentid.pub g-team.agentid.pub get --format json
-```
-
-示例：
-
-```json
-{
-  "ok": true,
-  "group_id": "g-team.agentid.pub",
-  "status": "ok",
-  "path": "/rules.md",
-  "metadata": {
-    "path": "/rules.md",
-    "size": 1024,
-    "mtimeMs": 1780000000000
-  },
-  "content": "# 群规则\n..."
-}
-```
-
-`get` 不是简单执行 `ec fs cat`。它会先验证 signed `rules.content`，再确认远端 `/rules.md` 的 `size + mtimeMs` 与已发布元信息一致。
-
-## 规则文件建议
-
-`/rules.md` 是入口规则文档，不是群知识库。文件上限为 4KB，建议只写需要稳定注入每轮上下文的内容：
-
-```markdown
-# 群规则
-
-## 工作流程
-- 需求先明确负责人、截止时间和验收条件。
-- 涉及生产变更时必须先给出回滚方案。
-
-## 职责分工
-- owner：最终决策与权限管理。
-- reviewer：检查风险、测试和兼容性。
-- executor：实现、验证并报告结果。
-
-## 交付要求
-- 结论先行，附关键证据。
-- 未完成验证时必须明确说明。
-
-## 升级路径
-- 权限不足或规则冲突时 @owner。
-```
-
-较大的规范、资料和附件应存放在群空间其它路径，需要时用 `ec fs ls/find/stat/cat` 查询，不要全部塞进 `/rules.md`。
-
-## 发布权限
-
-发布涉及两层权限：
-
-- 群文件权限：允许覆盖 `<group-id>:/rules.md`。
-- 群索引权限：允许通过 `updateRules` 更新当前有效版本。
-
-通常应由 owner/admin 写入和发布，普通成员只读。某人即使能覆盖文件，但不能更新群索引，该次修改也不会成为有效群规则，并会导致 `file_mismatch`。
-
-## 更新通知
-
-只有成功执行 `set` 或 `publish` 的发布者发送通知。读取方发现更新、自动同步或收到通知后刷新规则时，不会再次广播。
-
-通知 payload：
-
-```json
-{
-  "type": "notice",
-  "subtype": "group.rules.updated",
-  "text": "群规则已发布：g-team.agentid.pub:/rules.md\n操作者：admin.agentid.pub",
-  "actor_aid": "admin.agentid.pub",
-  "group_id": "g-team.agentid.pub",
-  "path": "/rules.md",
-  "group_index_etag": "\"sha256:...\"",
-  "size": 1024,
-  "mtimeMs": 1780000000000
-}
-```
-
-通知只是刷新提示。接收方仍以 signed `rules.content` 和远端文件校验结果为准。
-
-## 状态说明
-
-| status | 含义 | 是否加载 |
-|--------|------|----------|
-| `ok` | `get/set/publish` 校验或发布成功 | 是 |
-| `ignored` | 当前 Agent 的 `groupRules.mode=ignore`，本轮未访问远端或本地规则 | 否 |
-| `synced` | 运行时已刷新并物化本地规则 | 是 |
-| `cached` | 本地物化文件仍与已发布元信息一致 | 是 |
-| `missing` | 未发布规则，或 `/rules.md` 不存在 | 否 |
-| `forbidden` | 当前身份无读取或发布权限 | 否 |
-| `invalid_metadata` | signed `rules.content` 格式或签名无效 | 否 |
-| `file_mismatch` | `/rules.md` 与当前已发布元信息不一致 | 否 |
-| `too_large` | 文件超过 4KB | 否 |
-| `unreadable` | 文件、编码、网络或远端服务暂时不可读 | 否 |
-| `error` | 其它错误 | 否 |
-
-## 本地物化与上下文加载
-
-远端权威文件固定为：
-
-```text
-<group-id>:/rules.md
-```
-
-校验成功后，本地物化为：
-
-```text
-$RELATIONS_DIR/<channel>#<urlEncode(groupId)>/rules.md
-```
-
-AUN 示例：
-
-```text
-$AGENT_DIR/relations/aun#g-team.agentid.pub/rules.md
-```
-
-该本地文件属于**关系层**（群是对端的一种，见 `kits/rules/04-relation.md`），落在
-`agentRelationsDir(selfAid)/<peerKey>/rules.md`（`src/eck/group-rules-sync.ts` 的 `relationPaths`）。
-`$VENUES_DIR` 下的同名文件是已删除模块 `group-venue-sync.ts` 的历史残留，不再有效。
-它只是远端规则的物化副本，不应直接编辑。只有当前处理轮次验证通过并设置 `groupRulesPath` 时，ECK manifest 才会把它注入 system context。
-
-## 排障
-
-### `set` 提示文件过大或编码无效
-
-将入口规则压缩到 4KB 以内，并保存为 UTF-8 Markdown。详细资料移到群空间其它文件。
-
-### `get` 返回 `file_mismatch`
-
-有人通过 `ec fs` 或其它低层入口修改了 `/rules.md`，但尚未发布。由有权限的发布者执行：
-
-```bash
-ec group rules <from> <group-id> publish
-```
-
-### 收到通知但规则没有加载
-
-通知不代表文件一定有效。检查：
-
-```bash
-ec group rules <from> <group-id> get --format json
-ec fs stat <group-id>:/rules.md --format json
-```
-
-重点查看 `status`、已发布 `metadata` 和远端 `size/mtimeMs` 是否一致。
-
-### 只想查看远端原始文件
-
-```bash
-ec fs cat <group-id>:/rules.md
-```
-
-这只能查看当前文件内容，不能证明它是当前已签名发布的有效版本。判断有效性仍应使用 `ec group rules ... get`。
+# ec group rules — 群规则文件
+
+管理 AUN 群空间中的 `/rules.md`。群规则文件用于定义本群特有的工作流程、职责分工、交付格式、限制条件和升级路径；发布后，EvolCore 默认会在该群的对话上下文中加载，本地 Agent 也可用 `groupRules.mode` 选择忽略。
+
+以自己的 AID 为操作者 `<from>`，群 AID 为 `<group-id>`。
+
+## 与入群规则的区别
+
+`ec group rules` 同时承载两类不同能力：
+
+| 能力 | 命令 | 用途 |
+|------|------|------|
+| 群规则文件 | `get/set/publish` | 管理注入上下文的群空间 `/rules.md` |
+| 入群规则 | 无动作或 `--mode` 等选项 | 管理 open、approval、invite_only、closed 等加入策略 |
+
+本文只说明群规则文件。入群规则的用法见 `group.md`。
+
+## 常用命令
+
+```bash
+# 查看当前已发布且有效的群规则
+ec group rules <from> <group-id> get
+
+# 上传本地文件到 /rules.md 并立即发布
+ec group rules <from> <group-id> set <file>
+
+# 发布群空间中当前已有的 /rules.md
+ec group rules <from> <group-id> publish
+```
+
+所有命令均支持 `--format json`。
+
+## 本地加载策略
+
+`ec group rules get/set/publish` 管理远端群规则；`groupRules.mode` 管理当前 Agent 是否把远端规则
+读取并注入上下文。两者互不替代。策略支持 Agent 默认值和当前群 relation 覆盖，优先级为：
+
+```text
+Agent groupRules.mode -> 当前群 relation groupRules.mode -> 缺省 load
+```
+
+```bash
+# 当前群的有效策略与来源
+ec config get groupRules.mode \
+  --self bot.agentid.pub --peer aun#g-team.agentid.pub --format json
+
+# 只忽略当前群；重新设为 load 可恢复
+ec config set groupRules.mode ignore \
+  --self bot.agentid.pub --peer aun#g-team.agentid.pub
+ec config set groupRules.mode load \
+  --self bot.agentid.pub --peer aun#g-team.agentid.pub
+
+# 删除当前群覆盖，回落 Agent 默认值或缺省 load
+ec config unset groupRules.mode \
+  --self bot.agentid.pub --peer aun#g-team.agentid.pub
+
+# 设置 Agent 默认策略；只能从允许 Agent 级写入的私聊或控制面执行
+ec config set groupRules.mode ignore --self bot.agentid.pub
+```
+
+`groupRules.mode` 只能由当前 Agent 的实际 owner 修改；DaemonOwner 不会仅因进程角色而获得该权限，
+其他角色仍可读取当前 relation 的有效值。
+在群聊中，即使 owner 也只能修改当前群 relation，不能修改 Agent 默认值。命令沿用既有
+`ec config set/unset` 的授权、selector 和输出语义，不新增 Menu 协议。
+
+`ignore` 从配置提交后开始处理的新 turn 生效，并保证不访问远端规则、不读取本地
+`rules.md`、不注入规则正文；旧物化文件会保留，但不能作为回退来源。切回 `load` 后仍须重新完成
+远端元数据校验。配置切换不会清空、新建或 fork 会话，也不会删除已进入恢复会话历史的旧内容。
+Claude/Codex 的后续 turn 会按新策略重新组装上下文；其他 runner 仍保存配置，但 Menu 成功输出会
+提示新建或清空该群会话后生效。
+
+## 更新规则
+
+日常更新直接使用 `set`：
+
+```bash
+ec group rules admin.agentid.pub g-team.agentid.pub set ./rules.md
+```
+
+成功后会依次完成：
+
+1. 检查本地文件是普通文件、有效 UTF-8，且不超过 4KB。
+2. 原样上传到 `<group-id>:/rules.md`。
+3. 读取远端文件的 `size + mtimeMs`。
+4. 更新 signed `rules.content`，使该文件版本成为当前有效群规则。
+5. 再次检查远端 `size + mtimeMs`，防止发布期间文件被并发覆盖。
+6. 由发布者发送 `group.rules.updated` 群通知。
+
+命令不会规范化换行或重写正文。
+
+## 查看规则
+
+```bash
+ec group rules bot.agentid.pub g-team.agentid.pub get
+```
+
+普通输出在校验通过后直接打印 Markdown 正文。需要查看状态和元信息时使用：
+
+```bash
+ec group rules bot.agentid.pub g-team.agentid.pub get --format json
+```
+
+示例：
+
+```json
+{
+  "ok": true,
+  "group_id": "g-team.agentid.pub",
+  "status": "ok",
+  "path": "/rules.md",
+  "metadata": {
+    "path": "/rules.md",
+    "size": 1024,
+    "mtimeMs": 1780000000000
+  },
+  "content": "# 群规则\n..."
+}
+```
+
+`get` 不是简单执行 `ec fs cat`。它会先验证 signed `rules.content`，再确认远端 `/rules.md` 的 `size + mtimeMs` 与已发布元信息一致。
+
+## 规则文件建议
+
+`/rules.md` 是入口规则文档，不是群知识库。文件上限为 4KB，建议只写需要稳定注入每轮上下文的内容：
+
+```markdown
+# 群规则
+
+## 工作流程
+- 需求先明确负责人、截止时间和验收条件。
+- 涉及生产变更时必须先给出回滚方案。
+
+## 职责分工
+- owner：最终决策与权限管理。
+- reviewer：检查风险、测试和兼容性。
+- executor：实现、验证并报告结果。
+
+## 交付要求
+- 结论先行，附关键证据。
+- 未完成验证时必须明确说明。
+
+## 升级路径
+- 权限不足或规则冲突时 @owner。
+```
+
+较大的规范、资料和附件应存放在群空间其它路径，需要时用 `ec fs ls/find/stat/cat` 查询，不要全部塞进 `/rules.md`。
+
+## 发布权限
+
+发布涉及两层权限：
+
+- 群文件权限：允许覆盖 `<group-id>:/rules.md`。
+- 群索引权限：允许通过 `updateRules` 更新当前有效版本。
+
+通常应由 owner/admin 写入和发布，普通成员只读。某人即使能覆盖文件，但不能更新群索引，该次修改也不会成为有效群规则，并会导致 `file_mismatch`。
+
+## 更新通知
+
+只有成功执行 `set` 或 `publish` 的发布者发送通知。读取方发现更新、自动同步或收到通知后刷新规则时，不会再次广播。
+
+通知 payload：
+
+```json
+{
+  "type": "notice",
+  "subtype": "group.rules.updated",
+  "text": "群规则已发布：g-team.agentid.pub:/rules.md\n操作者：admin.agentid.pub",
+  "actor_aid": "admin.agentid.pub",
+  "group_id": "g-team.agentid.pub",
+  "path": "/rules.md",
+  "group_index_etag": "\"sha256:...\"",
+  "size": 1024,
+  "mtimeMs": 1780000000000
+}
+```
+
+通知只是刷新提示。接收方仍以 signed `rules.content` 和远端文件校验结果为准。
+
+## 状态说明
+
+| status | 含义 | 是否加载 |
+|--------|------|----------|
+| `ok` | `get/set/publish` 校验或发布成功 | 是 |
+| `ignored` | 当前 Agent 的 `groupRules.mode=ignore`，本轮未访问远端或本地规则 | 否 |
+| `synced` | 运行时已刷新并物化本地规则 | 是 |
+| `cached` | 本地物化文件仍与已发布元信息一致 | 是 |
+| `missing` | 未发布规则，或 `/rules.md` 不存在 | 否 |
+| `forbidden` | 当前身份无读取或发布权限 | 否 |
+| `invalid_metadata` | signed `rules.content` 格式或签名无效 | 否 |
+| `file_mismatch` | `/rules.md` 与当前已发布元信息不一致 | 否 |
+| `too_large` | 文件超过 4KB | 否 |
+| `unreadable` | 文件、编码、网络或远端服务暂时不可读 | 否 |
+| `error` | 其它错误 | 否 |
+
+## 本地物化与上下文加载
+
+远端权威文件固定为：
+
+```text
+<group-id>:/rules.md
+```
+
+校验成功后，本地物化为：
+
+```text
+$RELATIONS_DIR/<channel>#<urlEncode(groupId)>/rules.md
+```
+
+AUN 示例：
+
+```text
+$AGENT_DIR/relations/aun#g-team.agentid.pub/rules.md
+```
+
+该本地文件属于**关系层**（群是对端的一种，见 `kits/rules/04-relation.md`），落在
+`agentRelationsDir(selfAid)/<peerKey>/rules.md`（`src/eck/group-rules-sync.ts` 的 `relationPaths`）。
+`$VENUES_DIR` 下的同名文件是已删除模块 `group-venue-sync.ts` 的历史残留，不再有效。
+它只是远端规则的物化副本，不应直接编辑。只有当前处理轮次验证通过并设置 `groupRulesPath` 时，ECK manifest 才会把它注入 system context。
+
+## 排障
+
+### `set` 提示文件过大或编码无效
+
+将入口规则压缩到 4KB 以内，并保存为 UTF-8 Markdown。详细资料移到群空间其它文件。
+
+### `get` 返回 `file_mismatch`
+
+有人通过 `ec fs` 或其它低层入口修改了 `/rules.md`，但尚未发布。由有权限的发布者执行：
+
+```bash
+ec group rules <from> <group-id> publish
+```
+
+### 收到通知但规则没有加载
+
+通知不代表文件一定有效。检查：
+
+```bash
+ec group rules <from> <group-id> get --format json
+ec fs stat <group-id>:/rules.md --format json
+```
+
+重点查看 `status`、已发布 `metadata` 和远端 `size/mtimeMs` 是否一致。
+
+### 只想查看远端原始文件
+
+```bash
+ec fs cat <group-id>:/rules.md
+```
+
+这只能查看当前文件内容，不能证明它是当前已签名发布的有效版本。判断有效性仍应使用 `ec group rules ... get`。