evolcore 0.0.25 → 0.0.27

package/kits/docs/evolcore/config.md

@@ -1,195 +1,241 @@
-# 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: [...] }。
+#   不支持的 runner 字段会保留逐字段 UNSUPPORTED_FIELD，但不阻断同批支持字段；其它失败退出码为 1
+
+# 写参数：scope 由 selector 推断
+ec config set <field> <value> [--self <aid>] [--peer <X>] [--default] [--process]
+
+# 删除某层显式设置，回落下一层
+ec config unset <field> [--self <aid>] [--peer <X>]
+
+# 关系角色：通过 Role Assignment 服务读取、设置或撤销（仅支持 AUN private/group）
+ec config get role --self <aid> --peer <peer-aid>
+ec config set role <role-id> --self <aid> --peer <peer-aid>
+ec config unset role --self <aid> --peer <peer-aid>
+
+`role` 不走通用配置写入；设置/撤销仍执行角色目标校验、权限检查、revision CAS、原子写入和审计。
+
+# 查看某一层文件原始内容（不合并，凭证显示 ${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` 由消费方按当前角色单独应用。
+
+### Codex 用户提问
+
+`baseagents.codex.enableRequestUserInput` 已纳入 defaults → agent → relation 覆盖链，默认 `true`。
+它控制 Codex **Default 模式的阻塞式 `request_user_input`**，对应 App Server 的
+`item/tool/requestUserInput` 请求和 `default_mode_request_user_input` feature。
+新 turn 会把有效值写入原 Codex thread 的配置；不需要另建线程。
+
+```bash
+ec config get baseagents.codex.enableRequestUserInput --self bot.agentid.pub
+ec config set baseagents.codex.enableRequestUserInput true --self bot.agentid.pub
+ec config set baseagents.codex.enableRequestUserInput false \
+  --self bot.agentid.pub --peer aun#alice.agentid.pub
+```
+
+该字段不是权限审批或 `request_user_input_async` 的关闭开关。异步问题由
+`agentMessage.questions` 事件自动映射为可回答卡片，允许选择选项或自由输入；
+Agent 可继续处理不依赖答案的工作。回答通过 Codex 原生 question-reply envelope
+提交：活动 turn 使用 `turn/steer`，已结束则通过持久队列恢复同一 Session 和 Codex thread。
+问题默认保留 24 小时，重启后恢复未回答卡片；会话绑定或授权变化后拒绝旧卡片回答。
+提交结果不明时不自动重发，避免重复回答。
+
+支持卡片的客户端沿用 `action_card` / `action_card_reply`，自由输入沿用 `compose`。
+命令入口为 `/ask <问题ID> <回答>`；只有一个待回答问题时也可 `/ask <选项编号或回答>`。
+不需要新增 async 开关，也不需要把异步问题当成普通聊天文本转发给 Agent。
+
+### 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 写入结果会提示新建或清空群会话后生效。
+
+## 权限控制
+
+**指定关系读取**：Menu CLI 和托管 `config get` 中，实际 owner/admin 可显式使用
+`--self <当前 Agent> --peer <目标关系>` 读取当前 Agent 的其他关系配置。admin 的命令授权、
+字段白名单和 `currentRelationOnly` 等限制继续生效；member/visitor 仍只允许当前关系。
+该能力只放开单字段或批量 `get`，不会放开普通 `set/unset`、`show/effective`，也不允许借关系 selector 跨 Agent。
+peerKey 会规范化；读取不存在的关系仍按已有规则回落到上级配置并返回说明，不创建关系或修改授权。
+
+**批量兼容性**：未实现 runner 的行为字段（如 `baseagents.hermes.model/effort`）返回
+`{ ok: false, field, code: "UNSUPPORTED_FIELD", error }`。批量请求若只有这类兼容缺项，
+顶层 `ok=true`、退出码 0，其他有效字段照常返回；调用方应逐项检查 `results[].ok`。
+单独查询不支持字段仍失败（CLI 退出码 1，Menu 顶层错误归一化为 `NOT_SUPPORTED`）。
+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 的有效值
+- **Agent fullaccess 策略**：Agent 配置中的 `fullaccess.enabled` 缺失时关闭，仅可通过已认证的 EC Web Agent 设置修改；CLI、普通 Menu 和托管任务的 set/unset 均拒绝。该开关受 `daemon.json.fullaccess.enabled` 总开关约束；daemon 关闭时 EC Web 隐藏该项且开启请求被拒绝。双 Owner（AgentOwner + daemonOwner）条件在实际私聊任务执行时校验。
+- **源码诊断白名单**：`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 链只增不减）

package/kits/docs/evolcore/contact.md

@@ -1,68 +1,75 @@
-# ec contact — Agent 联系人与访问控制
-
-`ec contact` 管理指定 Agent 的 Contact Book v3。它只接受 AUN AID 主键；拉黑的是该 canonical AID，
-因此会拒绝它在 AUN 以及所有已绑定外部渠道中的私聊入站。角色统一由 relation `config.json role` 管理。
-
-## 命令
-
-```bash
-ec contact add <aid> --self <agent-aid>
-ec contact block <aid> --self <agent-aid>
-ec contact unblock <aid> --self <agent-aid>
-ec contact list --blocked --self <agent-aid>
-```
-
-所有命令都要求显式 `--self`，支持 `--format json`。
-
-## 约束
-
-- `<aid>` 和 `--self` 必须是合法 AID。
-- Agent 托管会话中的 `add` 只能针对当前 AUN 私聊对端；它创建/更新 `pending`，并向本 Agent Owner 发送审核卡片。
-- `add` 复用 `/request` 的联系人申请额度、过期和请求版本校验；已有 `pending`/`declined` 条目会重新走申请流程。
-- Owner 在审核卡片点击“通过”后才变为 active；`blocked` 必须先执行 `unblock`。
-- 直接从本机终端执行 `add` 属于本地管理操作，会直接创建或恢复 active 联系人；Connect `action=add` 同样是管理端直接操作。
-- 写入 Agent Owner 时，系统会自动创建该 Owner 的 active 联系人记录。
-- `block/unblock` 只接受已存在的联系人；不存在时返回 `NOT_FOUND`。
-- `block/unblock` 至少改变本 Agent 的入站接收策略；托管任务的普通私聊 `ec msg send` 对 blocked 目标也会在 daemon 侧被拒绝。非托管 AUN CLI 发送不读取本地联系人簿。不代表对端也拉黑了本 Agent。
-- Agent owner 不能被拉黑。
-- `list --blocked` 只列出当前 blocked contact，并返回 `contactRevision`。
-
-## 权限边界
-
-直接从本机终端运行时，这是本地管理命令。
-
-从 Agent 活动任务执行时，CLI 不直接写文件，而是携带当前 session delegation token 调用 daemon `contact.op`：
-
-| 操作 | owner | admin | 普通角色 |
-|---|---:|---:|---:|
-| `list --blocked` | 允许 | 允许 | 拒绝 |
-| Agent 会话 `add` 当前私聊对端 | 允许 | 允许 | 由当前关系授权，受 AUN 私聊和申请限制 |
-| `block` / `unblock` | 允许 | 拒绝 | 拒绝 |
-
-缺少、伪造、撤销或跨会话 delegation token 时失败关闭。托管调用的 `--self` 必须等于当前任务所属 Agent。
-
-角色管理使用 Role Menu relation assignment；admin 的授予和撤销必须由 owner 执行。
-
-## JSON 输出
-
-拉黑成功：
-
-```json
-{
-  "ok": true,
-  "operation": "set-blocked",
-  "selfAid": "bot.agentid.pub",
-  "primaryId": "peer.agentid.pub",
-  "blocked": true,
-  "changed": true,
-  "contactRevision": "..."
-}
-```
-
-## 拉黑后的消息行为
-
-- AUN 和已绑定外部私聊身份的入站在 MessageBridge 业务入口被拦截，不进入 menu/auth/command/session/queue/LLM。
-- 群聊不按成员的联系人状态过滤；`open` 对所有已配置渠道的群聊入站开放，`contacts` 将 Agent 已加入并
-  接收到的群聊视为授权，`owners` 仅 Owner 消息开放。
-- 对 `ai`、`bot`、`agent`、`service` 类型的私聊对端，可限频返回 `[rejection] Not accepting messages from you.`。
-- 入站正文中的 `[rejection]` 没有协议控制语义。发送者未被本 Agent 拉黑时，该文本正常进入响应式会话。
+# ec contact — Agent 联系人与访问控制
+
+`ec contact` 管理指定 Agent 的 Contact Book v3。它只接受 AUN AID 主键；拉黑的是该 canonical AID，
+因此会拒绝它在 AUN 以及所有已绑定外部渠道中的私聊入站。角色统一由 relation `config.json role` 管理。
+
+## 命令
+
+```bash
+ec contact add <aid> --self <agent-aid>
+ec contact block <aid> --self <agent-aid>
+ec contact unblock <aid> --self <agent-aid>
+ec contact list --blocked [--self <agent-aid>]
+ec contact list --pending [--self <agent-aid>]
+ec contact list --all [--self <agent-aid>]
+ec contact approve <aid> --request-id <id> [--self <agent-aid>]
+ec contact reject <aid> --request-id <id> [--self <agent-aid>]
+ec contact block-request <aid> --request-id <id> [--self <agent-aid>]
+```
+
+支持 `--format json`。本机 `list` 省略 `--self` 时聚合全部 Agent；写操作在仅有一个 Agent 时可自动推断，多 Agent 环境必须显式指定，避免误操作错误 Agent。
+
+## 约束
+
+- `<aid>` 和 `--self` 必须是合法 AID。
+- Agent 托管会话中的 `add` 只能针对当前 AUN 私聊对端；它创建/更新 `pending`，并向本 Agent Owner 发送审核卡片。
+- `add` 复用 `/request` 的联系人申请额度、过期和请求版本校验；已有 `pending`/`declined` 条目会重新走申请流程。
+- Owner 在审核卡片点击“通过”后才变为 active；`blocked` 必须先执行 `unblock`。
+- `list --pending` 可查看仍待审核的申请及其 `requestId`；卡片过期或投递失败时，Owner 可用 `approve/reject/block-request` 通过 requestId 处理当前申请，过期申请需申请方重新提交。
+- 直接从本机终端执行 `add` 属于本地管理操作，会直接创建或恢复 active 联系人；Connect `action=add` 同样是管理端直接操作。
+- 写入 Agent Owner 时，系统会自动创建该 Owner 的 active 联系人记录。
+- `block/unblock` 只接受已存在的联系人；不存在时返回 `NOT_FOUND`。
+- `block/unblock` 至少改变本 Agent 的入站接收策略；托管任务的普通私聊 `ec msg send` 对 blocked 目标也会在 daemon 侧被拒绝。非托管 AUN CLI 发送不读取本地联系人簿。不代表对端也拉黑了本 Agent。
+- Agent owner 不能被拉黑。
+- `list --blocked` 只列出 blocked contact；`list --pending` 只列出待审申请；`list --all` 列出联系人全状态。指定 `--self` 时返回该 Agent 的 `contactRevision`，本机省略 `--self` 时按 Agent 聚合。
+
+## 权限边界
+
+直接从本机终端运行时，这是本地管理命令。
+
+从 Agent 活动任务执行时，CLI 不直接写文件，而是携带当前 session delegation token 调用 daemon `contact.op`：
+
+| 操作 | owner | admin | 普通角色 |
+|---|---:|---:|---:|
+| `list --blocked/--pending/--all` | 允许 | 允许 | 拒绝 |
+| Agent 会话 `add` 当前私聊对端 | 允许 | 允许 | 由当前关系授权，受 AUN 私聊和申请限制 |
+| `block` / `unblock` | 允许 | 拒绝 | 拒绝 |
+| `approve/reject/block-request` | 允许 | 允许 | 拒绝 |
+
+缺少、伪造、撤销或跨会话 delegation token 时失败关闭。托管调用省略 `--self` 时使用 delegation 中的当前 Agent；显式 `--self` 必须等于当前任务所属 Agent。
+
+角色管理使用 Role Menu relation assignment；admin 的授予和撤销必须由 owner 执行。
+
+## JSON 输出
+
+拉黑成功：
+
+```json
+{
+  "ok": true,
+  "operation": "set-blocked",
+  "selfAid": "bot.agentid.pub",
+  "primaryId": "peer.agentid.pub",
+  "blocked": true,
+  "changed": true,
+  "contactRevision": "..."
+}
+```
+
+## 拉黑后的消息行为
+
+- AUN 和已绑定外部私聊身份的入站在 MessageBridge 业务入口被拦截，不进入 menu/auth/command/session/queue/LLM。
+- 群聊不按成员的联系人状态过滤；`open` 对所有已配置渠道的群聊入站开放，`contacts` 将 Agent 已加入并
+  接收到的群聊视为授权，`owners` 仅 Owner 消息开放。
+- 对 `ai`、`bot`、`agent`、`service` 类型的私聊对端，可限频返回 `[rejection] Not accepting messages from you.`。
+- 入站正文中的 `[rejection]` 没有协议控制语义。发送者未被本 Agent 拉黑时，该文本正常进入响应式会话。