evolcore 0.0.23 → 0.0.25

package/kits/docs/evolcore/codex-windows-sandbox.md

@@ -0,0 +1,146 @@
+# Windows 上的 Codex Sandbox 权限排障
+
+本文适用于 EvolCore 在 Windows 上调用 Codex 时，任务在启动阶段因 sandbox 权限失败的情况。目标运行方式是：Codex Desktop、EvolCore daemon 和 `ec` CLI 均以普通用户运行；只有 Codex sandbox 的安装或修复过程临时通过 UAC 提权。
+
+不要为了绕过 sandbox 错误而长期以管理员身份运行全部组件。这样不仅扩大权限，还可能使高完整性 daemon 创建的命名管道拒绝普通权限 `ec` CLI 连接。
+
+## 典型错误
+
+### `.sandbox-bin` 无法锁定
+
+```text
+helper_sandbox_lock_failed: lock sandbox bin dir C:\Users\<user>\.codex\.sandbox-bin failed:
+SetNamedSecurityInfoW sandbox dir failed: 5
+```
+
+错误码 5 是 Windows `ACCESS_DENIED`。常见原因是 `.sandbox-bin` 归 `BUILTIN\Administrators` 所有，而当前普通用户只有 `Modify`，没有修改 DACL 所需的 `WRITE_DAC`。Codex 的日常 sandbox refresh 不会请求 UAC，因此无法自行修复这个状态。
+
+### `unelevated` 无法执行 deny-read
+
+```text
+windows unelevated restricted-token sandbox cannot enforce deny-read restrictions directly;
+refusing to run unsandboxed
+```
+
+这不是同一个错误。EvolCore 会为托管 Agent 注入 deny-read 限制；Windows 的 `unelevated` backend 无法实施这些限制并会 fail closed。因此不要把下面的配置当作修复：
+
+```toml
+[windows]
+sandbox = "unelevated"
+```
+
+需要 deny-read 时应继续使用：
+
+```toml
+[windows]
+sandbox = "elevated"
+```
+
+这里的 `elevated` 指 sandbox provisioning 能通过 UAC 建立受限账户和 ACL，不表示 Desktop 或 EvolCore 必须一直以管理员运行。
+
+## 先确认错误属于哪一层
+
+在普通 PowerShell 中执行：
+
+```powershell
+codex --version
+codex doctor --json
+whoami /groups
+
+$sandboxBin = Join-Path $env:USERPROFILE '.codex\.sandbox-bin'
+Get-Item -LiteralPath $sandboxBin -Force |
+  Select-Object FullName, Attributes, LinkType
+Get-Acl -LiteralPath $sandboxBin |
+  Select-Object Owner, AreAccessRulesProtected, Sddl
+```
+
+同时检查：
+
+```powershell
+Get-Content (Join-Path $env:USERPROFILE '.codex\.sandbox\setup_error.json')
+Get-Content (Join-Path $env:USERPROFILE '.codex\.sandbox\setup_marker.json')
+Get-Content (Join-Path $env:USERPROFILE '.codex\.sandbox\sandbox.*.log') -Tail 80
+```
+
+注意以下边界：
+
+| 现象 | 所属层 | 处理方向 |
+|------|--------|----------|
+| `helper_sandbox_lock_failed` / `SetNamedSecurityInfoW ... 5` | Codex sandbox ACL | 重新 provisioning 或修复 `.sandbox-bin` owner |
+| `unelevated ... cannot enforce deny-read` | Codex sandbox 模式 | 使用 `windows.sandbox = "elevated"` |
+| `connect EPERM \\.\pipe\daemon-*` | EvolCore IPC | 让 daemon 与 CLI 使用相同用户和完整性级别 |
+| sandbox 已启动，随后出现 `POLICY_DENIED` | EvolCore 角色/权限策略 | 检查任务发起者角色和 permission mode |
+
+共享同一个项目目录或同一个 `CODEX_HOME` 本身不是错误。关键是宿主进程的完整性级别一致，以及 sandbox 基础 ACL 已正确 provisioning。
+
+## 推荐修复：重新执行 elevated provisioning
+
+1. 结束正在启动的 Codex Agent 任务，保留 Codex Desktop 和 EvolCore 的普通权限运行方式。
+2. 将 Codex Desktop 与独立安装的 Codex CLI 更新到兼容版本，避免两个版本交替刷新同一 `CODEX_HOME`。
+3. 在 Codex Desktop 的 Windows Sandbox 设置中执行 setup/repair，选择 elevated backend，并接受一次 UAC 提示。对应的 app-server 操作为 `windowsSandbox/setupStart`，模式为 `elevated`；普通用户不应自行拼接内部 RPC。
+4. provisioning 完成后关闭管理员窗口。后续 Desktop、EvolCore daemon 和 `ec` CLI 均以普通用户运行。
+5. 在普通 PowerShell 中执行验证命令。
+
+```powershell
+codex doctor --json
+codex sandbox -- cmd /c whoami
+```
+
+验收结果应满足：
+
+- `codex doctor` 中 sandbox backend 为 `elevated`，provisioning 为 `complete`，没有 `helper_sandbox_lock_failed`。
+- `codex sandbox -- cmd /c whoami` 成功，身份是专用 sandbox 用户（例如 `CodexSandboxOffline` 或 `CodexSandboxOnline`），而不是当前桌面用户。
+- 普通权限 EvolCore 任务可以进入模型执行阶段。
+
+如果 setup/repair 仍反复失败，优先使用 Codex 的修复或重新安装流程。不要先清空整个 `.codex`，其中包含会话、认证和其他用户数据。
+
+## 已验证的定向 workaround
+
+仅当官方 repair 无法完成、错误明确为 `.sandbox-bin` owner/DACL 不一致时使用。此方法只修复目录 owner，不递归改文件权限，也不删除或放宽现有 DACL。
+
+先在普通 PowerShell 中确认目标是实体目录而非重解析点：
+
+```powershell
+$sandboxBin = Join-Path $env:USERPROFILE '.codex\.sandbox-bin'
+$item = Get-Item -LiteralPath $sandboxBin -Force
+if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) {
+  throw "$sandboxBin is a reparse point; stop and inspect it manually"
+}
+Get-Acl -LiteralPath $sandboxBin | Format-List Owner, Sddl
+```
+
+然后只为下面一次操作打开管理员 PowerShell：
+
+```powershell
+$sandboxBin = Join-Path $env:USERPROFILE '.codex\.sandbox-bin'
+$currentUser = [Security.Principal.WindowsIdentity]::GetCurrent().Name
+$acl = Get-Acl -LiteralPath $sandboxBin
+$acl.SetOwner([Security.Principal.NTAccount]::new($currentUser))
+Set-Acl -LiteralPath $sandboxBin -AclObject $acl
+```
+
+关闭管理员 PowerShell，在普通 PowerShell 中重新运行：
+
+```powershell
+codex sandbox -- cmd /c whoami
+codex doctor --json
+```
+
+本 workaround 已验证可以让普通权限 refresh 越过 `SetNamedSecurityInfoW ... 5`，但它不是替代官方 provisioning 的长期安装流程。Codex 更新或 repair 可能重新设置 owner；若问题复发，应保留 `doctor` 输出和 sandbox 日志并反馈给 Codex，而不是持续扩大 ACL。
+
+## 禁止采用的规避方式
+
+- 不要给 `Everyone`、`Users` 或 `CodexSandboxUsers` 授予 `FullControl`、`WRITE_DAC` 或 `WRITE_OWNER`。
+- 不要删除 `.codex` 父目录上的 deny ACL；这些规则可能正是 deny-read 隔离的一部分。
+- 不要关闭 sandbox 或使用危险绕过参数来运行不受信任的 Agent 任务。
+- 不要让 EvolCore daemon 长期管理员运行而 CLI 保持普通权限；这会造成命名管道 `EPERM`。
+- 不要仅凭 `ec status` 中 PID 存活判断系统健康；还要确认 IPC 和实际 Agent 任务都能运行。
+
+## EvolCore 侧最终验证
+
+```powershell
+ec status
+ec agent reload <agent-aid> --format json
+```
+
+然后从一个普通 AID 向目标 Agent 发送最小测试任务。观察 daemon 日志时，正确顺序应是：sandbox 初始化成功、Codex thread 启动、任务进入工具/模型执行。若此后出现 `POLICY_DENIED`，说明 sandbox 已恢复，下一步应修复 EvolCore 的角色或任务权限，而不是继续修改 Windows ACL。

package/kits/docs/evolcore/config.md

@@ -1,195 +1,195 @@
-# ec config — 配置体系底层入口
-
-按作用域读写所有配置参数 + 配置快照/回滚/启动历史。触发词：看配置/改配置/查字段/列配置/校验配置/快照/回滚/历史/对比版本/启动记录。
-
-> `ec config` 是配置读写的统一 CLI 入口；模型交互由 menu 协议和 slash `/model` 提供。
-> 字段由共享 field policy 决定路由、值类型和访问级别；同一套规则用于 CLI、Menu 和 agent-tool。
-
-## 参数读写
-
-```bash
-# 读 effective 值（显示覆盖链来源）；可一次传多个字段批量读取（共享同一 selector/--format）
-ec config get <field> [<field> ...] [--self <aid>] [--peer <X>] [--default] [--process]
-#   单字段输出不变；多字段时 text 每行一条、json 返回 { ok, results: [...] }，任一字段失败退出码为 1
-
-# 写参数：scope 由 selector 推断
-ec config set <field> <value> [--self <aid>] [--peer <X>] [--default] [--process]
-
-# 删除某层显式设置，回落下一层
-ec config unset <field> [--self <aid>] [--peer <X>]
-
-# 查看某一层文件原始内容（不合并，凭证显示 ${VAR} 不展开）
-ec config show [--self <aid>] [--peer <X>] [--default] [--process]
-
-# 打印合并后的全部生效配置
-ec config effective [--self <aid>] [--peer <X>]
-
-# 列出某作用域可设字段（类型/枚举值，来源 schema）
-ec config fields [--self <aid>] [--default] [--process]
-
-# 列出所有配置文件
-ec config list
-
-# 按 schema 校验配置文件
-ec config validate [--self <aid>] [--peer <X>] [--default] [--process]
-
-# 按 schema 物化骨架文件（仅人）
-ec config init [--self <aid>] [--peer <X>] [--default] [--process]
-```
-
-## 快照 / 回滚
-
-总开关直接保存在 `$EVOLCORE_HOME/daemon.json` 顶层，默认 `true`：
-
-```bash
-ec config set configSnapshots true --process
-ec config set configSnapshots false --process
-```
-
-开启时首次成功启动创建全量基线，后续成功启动检测到配置变化后自动建立新版本。关闭时不写快照、启动日志，也不执行自检回落。
-
-```bash
-# 立即创建快照（与当前版本比对，不一致才建；--full 强制新全量）（仅人）
-ec config snapshot [--full] [--desc "说明"]
-
-# 列出快照版本（版本号/类型/触发/时间/说明）
-ec config history
-
-# 对比两版本差异
-ec config diff <v1> <v2>
-
-# 恢复到指定版本：展开到工作目录 + 更新 current.json（先 pre-restore 快照）（仅人）
-ec config restore <version>
-
-# 显示 current.json 选定版本（上次启动回落时给出告警）
-ec config current
-
-# 查看启动历史（含回落标记）
-ec config boots [-n N]
-
-# 清理旧快照（默认 dry-run，--yes 真删；拒删被依赖全量 / current 指向版本）（仅人）
-ec config prune [--keep-full N] [--keep-delta N] [--yes]
-```
-
-## Schema 查看
-
-查看随包分发的配置 schema **定义本身**（`kits/schemas/*.schema.*.json`）——不是读写配置值，而是查「某作用域有哪些字段、类型/枚举/默认、schema 有几个版本」。纯只读，人和 agent 均可。
-
-```bash
-# 概览：列出全部逻辑 schema 及各自当前版本
-ec config schema
-
-# 列出某 schema 磁盘上的所有版本（* 标当前版本，附日期/说明）
-ec config schema <name> --list
-
-# 查看某 schema 的原始定义（缺省版本号 = 当前版本）
-ec config schema <name> [version]
-```
-
-逻辑 schema 名（`<name>`）：`daemon` / `defaults` / `agent-config` / `relation-config` /
-`contact-book` / `role-registry` / `role-config`。
-
-三种输出模式：
-
-| 调用形式 | mode | 输出 |
-|----------|------|------|
-| `config schema` | overview | 全部 schema + 各自当前版本号 |
-| `config schema <name> --list` | versions | 该 schema 所有磁盘版本，`*` 标当前，附 date/description |
-| `config schema <name> [version]` | content | 指定版本（缺省=当前）的完整 schema JSON |
-
-约定与报错：
-- `--list` 与 version 参数互斥（`INVALID_CONFIG_COMMAND`）
-- `--list` 或指定 version 时必须带 `<name>`（`MISSING_ARG`）
-- version 须为非负整数；未知 name → `UNKNOWN_SCHEMA`；版本不存在 → `SCHEMA_VERSION_NOT_FOUND`（错误信息列出可用版本）
-
-> 用途：写配置前先 `ec config fields` 看字段可设值，或 `ec config schema <name>` 看该层 schema 的完整字段约束与 `x-merge` 合并语义；排查「字段为何被拒/怎么合并」时定位 schema 版本。
-
-## 作用域 selector
-
-| 参数 | 作用域 | 落盘 |
-|------|--------|------|
-| `--self <aid>` | agent 级 | `agents/<aid>/config.json` |
-| `--self <aid> --peer <X>` | 关系级 | `agents/<aid>/relations/<peerKey>/config.json` |
-| `--default` | 全局默认 | `agents/defaults.json` |
-| `--process` | 进程级 | `~/.evolcore/daemon.json` |
-| 写操作三者全无 | — | **拒绝**（防误写全局） |
-
-`--peer` 取 `channelType#channelId` 或裸 aid（裸 aid 视为 `aun#<aid>`）。配置提交后开始处理的新
-turn 使用新值；提交前已经开始的 turn 不被打断。
-
-## 覆盖链
-
-```
-defaults → agent/config → relation/config
-```
-
-ConfigManager 只合并上述物理层并返回物理来源。角色策略不进入配置合并链：`permissionMode` 和 `baseagents.*.model` 由消费方按当前角色单独应用。
-
-### Agent 消息准入策略
-
-消息准入策略保存在 `agents/<aid>/config.json` 的 `access` 字段，但它是 Agent 自身的安全边界，
-不参与 defaults/relation 有效覆盖：
-
-```json
-{
-  "access": {
-    "policyMode": "contacts",
-    "requestLimit": { "maxTimes": 600, "coolDown": 3600 }
-  }
-}
-```
-
-`policyMode` 为 `open | contacts | owners`；`open` 对所有已配置渠道的私聊和群聊入站开放，`contacts`
-将 Agent 已加入并接收到的群聊视为授权，`owners` 仅 Owner 消息开放；群聊成员不按 Contact Book 联系人
-状态逐一过滤。`requestLimit` 只限制准入控制消息的自动回复、申请和绑定码提示，不是渠道准入开关；`coolDown`
-单位为秒。该对象由 Connect 的访问设置入口修改，不通过通用 relation/defaults 覆盖链放宽。
-
-### AUN 群规则加载策略
-
-`groupRules.mode` 可设为 `load` 或 `ignore`，缺省为 `load`。该字段仅存在于 Agent 和 relation
-层，relation 可覆盖 Agent 默认值，`--default` 不支持。
-
-```bash
-# Agent 默认值
-ec config set groupRules.mode ignore --self bot.agentid.pub
-
-# 当前群覆盖
-ec config set groupRules.mode load \
-  --self bot.agentid.pub --peer aun#g-team.agentid.pub
-
-# 查看有效值和来源 / 删除群覆盖
-ec config get groupRules.mode \
-  --self bot.agentid.pub --peer aun#g-team.agentid.pub --format json
-ec config unset groupRules.mode \
-  --self bot.agentid.pub --peer aun#g-team.agentid.pub
-```
-
-`ignore` 表示运行时不访问远端群规则、不读本地物化文件、不注入规则正文，但不删除缓存，也不影响
-`ec group rules` 的远端管理命令。配置切换不会自动创建或清空会话。Claude/Codex 从后续新 turn
-按当前值重新组装上下文；其他 runner 的 Menu 写入结果会提示新建或清空群会话后生效。
-
-## 权限控制
-
-**写权限**（API 层判定）：
-- **通用可写字段**：active_baseagent / baseagents / chatmode / show_activities / flush_delay / debounce / render
-- **角色专用入口**：`roles/index.json` 与 `roles/{roleId}.json` 由角色服务维护；relation 的
-  `role` 由角色分配服务维护；`permissionMode` 仅在角色策略中维护
-- **兼容字段**：`enable_rich_content` 仍可读取旧值，但已废弃且不再产生运行时效果
-- **群规则策略**：`groupRules.mode` 仅当前 Agent 的实际 owner 可 set/unset；DaemonOwner 不继承群或 relation 写权限，其他角色可读取当前 relation 的有效值
-- **源码诊断白名单**：`readonlySourceDiagnostics` 默认关闭；开启后只读会话仅可在项目源码目录执行受限、可证明只读查询，配置/证书/快照/session/锁文件仍禁止访问
-- **仅人可写**：channels / owners / admins / 凭证 / aid / enabled / projects / aun / models.allowed
-- Agent 托管环境写仅人字段被拒
-
-**操作权限**：
-- 读操作（get/show/list/effective/fields/schema/history/diff/current/boots/validate）：人和 agent 均可
-- 快照管理（snapshot/restore/init/prune）：仅人可执行
-
-**凭证安全**：
-- 凭证一律 `${VAR}` 引用，CLI 读命令永不展开、不泄露明文
-- `.env` 全程禁读写
-
-## 通用约定
-
-- `--format json` — 所有子命令通用
-- 本命令操作本地配置，不连 AUN 网络
-- 单文件内 list 字段 `set` = 追加去重；删单个元素请直接编辑文件（角色/owner 链只增不减）
+# ec config — 配置体系底层入口
+
+按作用域读写所有配置参数 + 配置快照/回滚/启动历史。触发词：看配置/改配置/查字段/列配置/校验配置/快照/回滚/历史/对比版本/启动记录。
+
+> `ec config` 是配置读写的统一 CLI 入口；模型交互由 menu 协议和 slash `/model` 提供。
+> 字段由共享 field policy 决定路由、值类型和访问级别；同一套规则用于 CLI、Menu 和 agent-tool。
+
+## 参数读写
+
+```bash
+# 读 effective 值（显示覆盖链来源）；可一次传多个字段批量读取（共享同一 selector/--format）
+ec config get <field> [<field> ...] [--self <aid>] [--peer <X>] [--default] [--process]
+#   单字段输出不变；多字段时 text 每行一条、json 返回 { ok, results: [...] }，任一字段失败退出码为 1
+
+# 写参数：scope 由 selector 推断
+ec config set <field> <value> [--self <aid>] [--peer <X>] [--default] [--process]
+
+# 删除某层显式设置，回落下一层
+ec config unset <field> [--self <aid>] [--peer <X>]
+
+# 查看某一层文件原始内容（不合并，凭证显示 ${VAR} 不展开）
+ec config show [--self <aid>] [--peer <X>] [--default] [--process]
+
+# 打印合并后的全部生效配置
+ec config effective [--self <aid>] [--peer <X>]
+
+# 列出某作用域可设字段（类型/枚举值，来源 schema）
+ec config fields [--self <aid>] [--default] [--process]
+
+# 列出所有配置文件
+ec config list
+
+# 按 schema 校验配置文件
+ec config validate [--self <aid>] [--peer <X>] [--default] [--process]
+
+# 按 schema 物化骨架文件（仅人）
+ec config init [--self <aid>] [--peer <X>] [--default] [--process]
+```
+
+## 快照 / 回滚
+
+总开关直接保存在 `$EVOLCORE_HOME/daemon.json` 顶层，默认 `true`：
+
+```bash
+ec config set configSnapshots true --process
+ec config set configSnapshots false --process
+```
+
+开启时首次成功启动创建全量基线，后续成功启动检测到配置变化后自动建立新版本。关闭时不写快照、启动日志，也不执行自检回落。
+
+```bash
+# 立即创建快照（与当前版本比对，不一致才建；--full 强制新全量）（仅人）
+ec config snapshot [--full] [--desc "说明"]
+
+# 列出快照版本（版本号/类型/触发/时间/说明）
+ec config history
+
+# 对比两版本差异
+ec config diff <v1> <v2>
+
+# 恢复到指定版本：展开到工作目录 + 更新 current.json（先 pre-restore 快照）（仅人）
+ec config restore <version>
+
+# 显示 current.json 选定版本（上次启动回落时给出告警）
+ec config current
+
+# 查看启动历史（含回落标记）
+ec config boots [-n N]
+
+# 清理旧快照（默认 dry-run，--yes 真删；拒删被依赖全量 / current 指向版本）（仅人）
+ec config prune [--keep-full N] [--keep-delta N] [--yes]
+```
+
+## Schema 查看
+
+查看随包分发的配置 schema **定义本身**（`kits/schemas/*.schema.*.json`）——不是读写配置值，而是查「某作用域有哪些字段、类型/枚举/默认、schema 有几个版本」。纯只读，人和 agent 均可。
+
+```bash
+# 概览：列出全部逻辑 schema 及各自当前版本
+ec config schema
+
+# 列出某 schema 磁盘上的所有版本（* 标当前版本，附日期/说明）
+ec config schema <name> --list
+
+# 查看某 schema 的原始定义（缺省版本号 = 当前版本）
+ec config schema <name> [version]
+```
+
+逻辑 schema 名（`<name>`）：`daemon` / `defaults` / `agent-config` / `relation-config` /
+`contact-book` / `role-registry` / `role-config`。
+
+三种输出模式：
+
+| 调用形式 | mode | 输出 |
+|----------|------|------|
+| `config schema` | overview | 全部 schema + 各自当前版本号 |
+| `config schema <name> --list` | versions | 该 schema 所有磁盘版本，`*` 标当前，附 date/description |
+| `config schema <name> [version]` | content | 指定版本（缺省=当前）的完整 schema JSON |
+
+约定与报错：
+- `--list` 与 version 参数互斥（`INVALID_CONFIG_COMMAND`）
+- `--list` 或指定 version 时必须带 `<name>`（`MISSING_ARG`）
+- version 须为非负整数；未知 name → `UNKNOWN_SCHEMA`；版本不存在 → `SCHEMA_VERSION_NOT_FOUND`（错误信息列出可用版本）
+
+> 用途：写配置前先 `ec config fields` 看字段可设值，或 `ec config schema <name>` 看该层 schema 的完整字段约束与 `x-merge` 合并语义；排查「字段为何被拒/怎么合并」时定位 schema 版本。
+
+## 作用域 selector
+
+| 参数 | 作用域 | 落盘 |
+|------|--------|------|
+| `--self <aid>` | agent 级 | `agents/<aid>/config.json` |
+| `--self <aid> --peer <X>` | 关系级 | `agents/<aid>/relations/<peerKey>/config.json` |
+| `--default` | 全局默认 | `agents/defaults.json` |
+| `--process` | 进程级 | `~/.evolcore/daemon.json` |
+| 写操作三者全无 | — | **拒绝**（防误写全局） |
+
+`--peer` 取 `channelType#channelId` 或裸 aid（裸 aid 视为 `aun#<aid>`）。配置提交后开始处理的新
+turn 使用新值；提交前已经开始的 turn 不被打断。
+
+## 覆盖链
+
+```
+defaults → agent/config → relation/config
+```
+
+ConfigManager 只合并上述物理层并返回物理来源。角色策略不进入配置合并链：`permissionMode` 和 `baseagents.*.model` 由消费方按当前角色单独应用。
+
+### Agent 消息准入策略
+
+消息准入策略保存在 `agents/<aid>/config.json` 的 `access` 字段，但它是 Agent 自身的安全边界，
+不参与 defaults/relation 有效覆盖：
+
+```json
+{
+  "access": {
+    "policyMode": "contacts",
+    "requestLimit": { "maxTimes": 600, "coolDown": 3600 }
+  }
+}
+```
+
+`policyMode` 为 `open | contacts | owners`；`open` 对所有已配置渠道的私聊和群聊入站开放，`contacts`
+将 Agent 已加入并接收到的群聊视为授权，`owners` 仅 Owner 消息开放；群聊成员不按 Contact Book 联系人
+状态逐一过滤。`requestLimit` 只限制准入控制消息的自动回复、申请和绑定码提示，不是渠道准入开关；`coolDown`
+单位为秒。该对象由 Connect 的访问设置入口修改，不通过通用 relation/defaults 覆盖链放宽。
+
+### AUN 群规则加载策略
+
+`groupRules.mode` 可设为 `load` 或 `ignore`，缺省为 `load`。该字段仅存在于 Agent 和 relation
+层，relation 可覆盖 Agent 默认值，`--default` 不支持。
+
+```bash
+# Agent 默认值
+ec config set groupRules.mode ignore --self bot.agentid.pub
+
+# 当前群覆盖
+ec config set groupRules.mode load \
+  --self bot.agentid.pub --peer aun#g-team.agentid.pub
+
+# 查看有效值和来源 / 删除群覆盖
+ec config get groupRules.mode \
+  --self bot.agentid.pub --peer aun#g-team.agentid.pub --format json
+ec config unset groupRules.mode \
+  --self bot.agentid.pub --peer aun#g-team.agentid.pub
+```
+
+`ignore` 表示运行时不访问远端群规则、不读本地物化文件、不注入规则正文，但不删除缓存，也不影响
+`ec group rules` 的远端管理命令。配置切换不会自动创建或清空会话。Claude/Codex 从后续新 turn
+按当前值重新组装上下文；其他 runner 的 Menu 写入结果会提示新建或清空群会话后生效。
+
+## 权限控制
+
+**写权限**（API 层判定）：
+- **通用可写字段**：active_baseagent / baseagents / chatmode / show_activities / flush_delay / debounce / render
+- **角色专用入口**：`roles/index.json` 与 `roles/{roleId}.json` 由角色服务维护；relation 的
+  `role` 由角色分配服务维护；`permissionMode` 仅在角色策略中维护
+- **兼容字段**：`enable_rich_content` 仍可读取旧值，但已废弃且不再产生运行时效果
+- **群规则策略**：`groupRules.mode` 仅当前 Agent 的实际 owner 可 set/unset；DaemonOwner 不继承群或 relation 写权限，其他角色可读取当前 relation 的有效值
+- **源码诊断白名单**：`readonlySourceDiagnostics` 默认关闭；开启后只读会话仅可在项目源码目录执行受限、可证明只读查询，配置/证书/快照/session/锁文件仍禁止访问
+- **仅人可写**：channels / owners / admins / 凭证 / aid / enabled / projects / aun / models.allowed
+- Agent 托管环境写仅人字段被拒
+
+**操作权限**：
+- 读操作（get/show/list/effective/fields/schema/history/diff/current/boots/validate）：人和 agent 均可
+- 快照管理（snapshot/restore/init/prune）：仅人可执行
+
+**凭证安全**：
+- 凭证一律 `${VAR}` 引用，CLI 读命令永不展开、不泄露明文
+- `.env` 全程禁读写
+
+## 通用约定
+
+- `--format json` — 所有子命令通用
+- 本命令操作本地配置，不连 AUN 网络
+- 单文件内 list 字段 `set` = 追加去重；删单个元素请直接编辑文件（角色/owner 链只增不减）