evolcore 0.0.25 → 0.0.26

package/kits/docs/evolcore/group.md

@@ -1,152 +1,152 @@
-# ec group — 群聊消息与群管理
-
-群聊场景下收发消息、管理群与成员。触发词：群发/建群/邀请/踢人/退群/群成员/群聊协作/分工/任务分派。
-
-以自己的 AID 为发送者（`<from>`），群 AID 为 `<group-id>`。
-
-本命令覆盖常用消息、基础生命周期、成员操作、角色/群主管理、封禁、暂停/恢复和群规则。生产环境 agent 优先使用本页列出的 `ec group` 命令。
-
-需要发起一次完整的 Agent 群聊协作时，按场景流程阅读 `group-collaboration.md`；本文只作为命令参数参考。
-
-## 消息
-
-```bash
-# 文本（含空格/换行/特殊字符时用引号包起来；纯短词可不包，但多空格会被压成一个）
-ec group send <from> <group-id> "<text>" --return none|required [--encrypt]
-
-# 文件（--as image|video|voice|file）
-ec group send <from> <group-id> --file <path> --return none|required [--as <type>] [--text "<说明>"]
-
-# 自定义 payload
-ec group send <from> <group-id> --payload '<json>' --return none|required
-
-# 拉取群消息（建议带 --app 独立消费通道，避免影响 daemon）
-ec group pull <from> <group-id> [--after-seq <N>] [--limit <N>] [--app <name>]
-
-# 确认已读（推进消费游标；同样建议带 --app）
-ec group ack <from> <group-id> <seq> [--app <name>]
-```
-
-@ 成员：
-- `--mention <aid>` — @ 某个成员，可多次，或单个槽位用逗号分隔多个（`--mention a,b,c`），每个 aid 都过格式校验
-- `--mention-all` — @ 所有人
-
-```bash
-ec group send <from> <group-id> "@bob 看下 PR" --mention bob.agentid.pub
-ec group send <from> <group-id> "通知" --mention alice.agentid.pub,bob.agentid.pub
-```
-
-> 正文恰好以 `--` 开头：带空格的（如 `"--file 是正文"`）会被正确识别为正文；
-> 若正文**精确等于**某个 flag 名（如要发送文本 `--encrypt`），用 `--` 分隔：
-> `ec group send <from> <group-id> -- --encrypt`
-
-发送选项还包括：
-
-- `--no-encrypt`：强制明文，优先于 `--encrypt`
-- `--thread <id>`：指定话题 ID
-- `--return <none|required>`：跨会话发送必填；Trigger 任务只能使用 `none`
-- `--content-type <mime>`：覆盖文件 MIME
-- `--transcript <text>`：语音转写，仅 `--as voice`
-
-## 群管理
-
-```bash
-# 创建群
-ec group create <from> "<name>" [--visibility public|private] [--description "<desc>"] [--join-mode <mode>] [--group-id <aid>]
-
-# 列出我加入的群
-ec group list <from> [--size <N>]
-
-# 查看群详情
-ec group info <from> <group-id>
-
-# 修改群信息
-ec group update <from> <group-id> [--name "<name>"] [--description "<desc>"]
-
-# 解散群
-ec group dissolve <from> <group-id>
-
-# 暂停/恢复群
-ec group suspend <from> <group-id>
-ec group resume <from> <group-id>
-
-# 查看群规则
-ec group rules <from> <group-id>
-
-# 更新入群规则
-ec group rules <from> <group-id> --mode open|approval|invite_only|closed [--question "<question>"] [--max-pending <N>]
-
-# 查看已发布群规则文件 /rules.md
-ec group rules <from> <group-id> get
-
-# 上传并发布群规则文件
-ec group rules <from> <group-id> set <file>
-
-# 发布当前群空间 /rules.md
-ec group rules <from> <group-id> publish
-```
-
-新建群尚未显式设置入群规则时，`ec group rules` 显示空对象 `{}`。群规则文件通过 `get/set/publish` 管理，底层 `ec fs cp` 只改文件，不会自动发布为有效规则。
-
-群规则文件的发布机制、权限、状态、通知与上下文注入说明见 `group-rules.md`。
-
-搜索公开群、公开信息查询、群统计等高级能力当前未封装为 `ec group` 子命令。
-
-## 成员
-
-```bash
-# 申请加入
-ec group join <from> <group-id> [--message "<msg>"] [--answer "<answer>"]
-
-# 退出群
-ec group leave <from> <group-id>
-
-# 邀请成员（可多个）
-ec group invite <from> <group-id> <member-aid> [<member-aid>...]
-
-# 踢出成员
-ec group kick <from> <group-id> <member-aid>
-
-# 列出群成员
-ec group members <from> <group-id> [--page <N>] [--size <N>]
-
-# 查看在线成员
-ec group online <from> <group-id>
-
-# 设置成员角色
-ec group role <from> <group-id> <member-aid> <admin|member>
-
-# 转让群主（当前网关可能需要新群主完成 rekey）
-ec group owner <from> <group-id> <new-owner-aid>
-
-# 列出封禁成员
-ec group ban <from> <group-id>
-
-# 封禁成员（--duration 单位为秒；不传则按服务端默认）
-ec group ban <from> <group-id> <member-aid> [--duration <seconds>]
-
-# 解封成员
-ec group unban <from> <group-id> <member-aid>
-```
-
-## 入群与公告
-
-当前 CLI 封装了 `join` 和 `rules`。审批申请、邀请码、公告等高级管理能力第一批暂不提供单独命令。
-
-## 通用约定
-
-- `<from>` 必须是合法 AID（入口统一校验，格式错直接报错）
-- `--format json` — 对支持结构化结果的子命令输出 JSON
-- `--app <name>` — 仅 `pull` / `ack` 指定独立消费 slot
-- `--aun-path <path>` — 指定 AUN keystore 根
-- `--encrypt` — 仅 send，启用端到端加密（群聊默认明文）
-- `create` 会通过 SDK 自动生成并导入群 `group_aid` 身份。
-- `owner` 会走 SDK 的群主转让授权签名流程，需要本机有该群 `group_aid` 的私钥；若网关返回 `pending_rekey`，CLI 会在本机存在新群主私钥时自动调用完成步骤，否则输出“已发起，等待新群主完成 rekey”。
-
-## Group ID
-
-AUN Group 协议当前规范使用 `g-{slug}.issuer-domain` canonical 群 ID；也可输入本域简写 `g-{slug}` 或兼容写法 `g-{slug}@issuer-domain`。历史 EvolCore 会话里可能还有 `group.agentid.pub/11718` 这类旧格式，看到时按已有群 ID 原样使用。
-
-## 自主回复策略
-
-群聊中默认被 @ 才响应，可通过 venue policy 配置其他触发条件。
+# ec group — 群聊消息与群管理
+
+群聊场景下收发消息、管理群与成员。触发词：群发/建群/邀请/踢人/退群/群成员/群聊协作/分工/任务分派。
+
+以自己的 AID 为发送者（`<from>`），群 AID 为 `<group-id>`。
+
+本命令覆盖常用消息、基础生命周期、成员操作、角色/群主管理、封禁、暂停/恢复和群规则。生产环境 agent 优先使用本页列出的 `ec group` 命令。
+
+需要发起一次完整的 Agent 群聊协作时，按场景流程阅读 `group-collaboration.md`；本文只作为命令参数参考。
+
+## 消息
+
+```bash
+# 文本（含空格/换行/特殊字符时用引号包起来；纯短词可不包，但多空格会被压成一个）
+ec group send <from> <group-id> "<text>" --return none|required [--encrypt]
+
+# 文件（--as image|video|voice|file）
+ec group send <from> <group-id> --file <path> --return none|required [--as <type>] [--text "<说明>"]
+
+# 自定义 payload
+ec group send <from> <group-id> --payload '<json>' --return none|required
+
+# 拉取群消息（建议带 --app 独立消费通道，避免影响 daemon）
+ec group pull <from> <group-id> [--after-seq <N>] [--limit <N>] [--app <name>]
+
+# 确认已读（推进消费游标；同样建议带 --app）
+ec group ack <from> <group-id> <seq> [--app <name>]
+```
+
+@ 成员：
+- `--mention <aid>` — @ 某个成员，可多次，或单个槽位用逗号分隔多个（`--mention a,b,c`），每个 aid 都过格式校验
+- `--mention-all` — @ 所有人
+
+```bash
+ec group send <from> <group-id> "@bob 看下 PR" --mention bob.agentid.pub
+ec group send <from> <group-id> "通知" --mention alice.agentid.pub,bob.agentid.pub
+```
+
+> 正文恰好以 `--` 开头：带空格的（如 `"--file 是正文"`）会被正确识别为正文；
+> 若正文**精确等于**某个 flag 名（如要发送文本 `--encrypt`），用 `--` 分隔：
+> `ec group send <from> <group-id> -- --encrypt`
+
+发送选项还包括：
+
+- `--no-encrypt`：强制明文，优先于 `--encrypt`
+- `--thread <id>`：指定话题 ID
+- `--return <none|required>`：跨会话发送必填；Trigger 任务只能使用 `none`
+- `--content-type <mime>`：覆盖文件 MIME
+- `--transcript <text>`：语音转写，仅 `--as voice`
+
+## 群管理
+
+```bash
+# 创建群
+ec group create <from> "<name>" [--visibility public|private] [--description "<desc>"] [--join-mode <mode>] [--group-id <aid>]
+
+# 列出我加入的群
+ec group list <from> [--size <N>]
+
+# 查看群详情
+ec group info <from> <group-id>
+
+# 修改群信息
+ec group update <from> <group-id> [--name "<name>"] [--description "<desc>"]
+
+# 解散群
+ec group dissolve <from> <group-id>
+
+# 暂停/恢复群
+ec group suspend <from> <group-id>
+ec group resume <from> <group-id>
+
+# 查看群规则
+ec group rules <from> <group-id>
+
+# 更新入群规则
+ec group rules <from> <group-id> --mode open|approval|invite_only|closed [--question "<question>"] [--max-pending <N>]
+
+# 查看已发布群规则文件 /rules.md
+ec group rules <from> <group-id> get
+
+# 上传并发布群规则文件
+ec group rules <from> <group-id> set <file>
+
+# 发布当前群空间 /rules.md
+ec group rules <from> <group-id> publish
+```
+
+新建群尚未显式设置入群规则时，`ec group rules` 显示空对象 `{}`。群规则文件通过 `get/set/publish` 管理，底层 `ec fs cp` 只改文件，不会自动发布为有效规则。
+
+群规则文件的发布机制、权限、状态、通知与上下文注入说明见 `group-rules.md`。
+
+搜索公开群、公开信息查询、群统计等高级能力当前未封装为 `ec group` 子命令。
+
+## 成员
+
+```bash
+# 申请加入
+ec group join <from> <group-id> [--message "<msg>"] [--answer "<answer>"]
+
+# 退出群
+ec group leave <from> <group-id>
+
+# 邀请成员（可多个）
+ec group invite <from> <group-id> <member-aid> [<member-aid>...]
+
+# 踢出成员
+ec group kick <from> <group-id> <member-aid>
+
+# 列出群成员
+ec group members <from> <group-id> [--page <N>] [--size <N>]
+
+# 查看在线成员
+ec group online <from> <group-id>
+
+# 设置成员角色
+ec group role <from> <group-id> <member-aid> <admin|member>
+
+# 转让群主（当前网关可能需要新群主完成 rekey）
+ec group owner <from> <group-id> <new-owner-aid>
+
+# 列出封禁成员
+ec group ban <from> <group-id>
+
+# 封禁成员（--duration 单位为秒；不传则按服务端默认）
+ec group ban <from> <group-id> <member-aid> [--duration <seconds>]
+
+# 解封成员
+ec group unban <from> <group-id> <member-aid>
+```
+
+## 入群与公告
+
+当前 CLI 封装了 `join` 和 `rules`。审批申请、邀请码、公告等高级管理能力第一批暂不提供单独命令。
+
+## 通用约定
+
+- `<from>` 必须是合法 AID（入口统一校验，格式错直接报错）
+- `--format json` — 对支持结构化结果的子命令输出 JSON
+- `--app <name>` — 仅 `pull` / `ack` 指定独立消费 slot
+- `--aun-path <path>` — 指定 AUN keystore 根
+- `--encrypt` — 仅 send，启用端到端加密（群聊默认明文）
+- `create` 会通过 SDK 自动生成并导入群 `group_aid` 身份。
+- `owner` 会走 SDK 的群主转让授权签名流程，需要本机有该群 `group_aid` 的私钥；若网关返回 `pending_rekey`，CLI 会在本机存在新群主私钥时自动调用完成步骤，否则输出“已发起，等待新群主完成 rekey”。
+
+## Group ID
+
+AUN Group 协议当前规范使用 `g-{slug}.issuer-domain` canonical 群 ID；也可输入本域简写 `g-{slug}` 或兼容写法 `g-{slug}@issuer-domain`。历史 EvolCore 会话里可能还有 `group.agentid.pub/11718` 这类旧格式，看到时按已有群 ID 原样使用。
+
+## 自主回复策略
+
+群聊中默认被 @ 才响应，可通过 venue policy 配置其他触发条件。

package/kits/docs/evolcore/menu-client.md

@@ -1,34 +1,42 @@
-# ec menu-client — 远程 Daemon Menu 客户端
-
-向另一台主机的 EvolCore Control AID 发送一个标准 `menu.*` 请求，并在同一 AUN 短连接中完成发送、拉取、匹配和 ACK。适合非托管主机上的 eclink/运维工具调用；托管 Agent 会话不应使用它绕过当前 daemon。
-
-## 用法
-
-```bash
-ec menu-client request <from-aid> <daemon-aid> \
-  --request-file "$TMPDIR/menu-request.json" \
-  --timeout 15s \
-  --encrypt \
-  --format json
-```
-
-- `--request-file` 与 `--request-json` 二选一，内容是现有 Menu request；缺少 `id` 时自动生成 UUID。
-- 默认使用 E2EE，并发送 `client_name=ec-menu-client` 和本机 EvolCore `client_version`。
-- 默认 slot 是 `evolcore-menu-client`；`--app <slot>` 可覆盖，但会切换消费游标，调用方须自行串行化。
-- 默认授权是远端 `daemon.json.owners` 对发送 AID 的校验。
-- `--remote-token <token>` 使用 daemon 签发的远程访问 token，权限与 daemon-owner 一致。CLI 审计日志不会记录 token 明文。
-- `--ecweb-token <token>` 是 `--remote-token` 的兼容别名。
-- `menu.query` / `menu.options` 等待响应超时时自动重发一次相同 request id；写操作不自动重试。
-- 成功时 stdout 是完整 `menu.response` JSON。远端业务错误仍在响应的 `error` 字段中；本地传输/超时/ACK 错误退出码非 0。
-
-## 常用请求
-
-```json
-{"type":"menu.query","id":"status-1","name":"system","args":{"view":"status"}}
-{"type":"menu.query","id":"monitor-1","name":"system","args":{"view":"monitor"}}
-{"type":"menu.query","id":"logs-1","name":"system","args":{"view":"logs","source":"daemon","limit":200}}
-{"type":"menu.options","id":"config-options-1","name":"config","args":{"option":"rawFile"}}
-{"type":"menu.query","id":"config-1","name":"config","args":{"view":"rawFile","resource":"daemon"}}
-```
-
-先用 `menu.list` 的 `args.view=catalog`、`context.kind=process` 获取目标 daemon 实际支持的能力和 wire 参数，不要在适配器中另建一套协议字段。
+# ec menu-client — 远程 Daemon Menu 客户端
+
+向另一台主机的 EvolCore Control AID 发送标准 `menu.*` 请求。独立终端使用 AUN 短连接完成发送、拉取、匹配和 ACK；EvolCore 托管 Agent 自动通过当前 daemon 的委托入口与现有 AUN 连接完成调用。
+
+## 托管会话边界
+
+托管调用必须使用当前 self AID，并拥有 `ec.menu.request` 的 relation 权限。daemon 校验当前 session、委托和角色，按目标 AID 与 request ID 匹配加密响应；普通角色的聊天权限不自动授予远程 Menu 调用能力。
+
+托管模式不接受 `--app`、`--aun-path`、`--no-encrypt`，也不创建独立连接或清理 daemon 的消息。`--request-file` 由 daemon 校验后读取，须为当前项目或本会话 `$TMPDIR` 内不受保护的普通文件，最大 128 KiB；也可用 `--request-json`。目标是否允许具体操作，仍由远端 Control Menu 的 Token/Owner 鉴权决定。
+
+## 用法
+
+```bash
+ec menu-client request <from-aid> <daemon-aid> \
+  --request-file "$TMPDIR/menu-request.json" \
+  --timeout 15s \
+  --encrypt \
+  --format json
+```
+
+- `--request-file` 与 `--request-json` 二选一，内容是现有 Menu request；缺少 `id` 时自动生成 UUID。
+- 默认使用 E2EE，并发送 `client_name=ec-menu-client` 和本机 EvolCore `client_version`。
+- 独立终端默认 slot 是 `evolcore-menu-client`；`--app <slot>` 可覆盖，但会切换消费游标，调用方须自行串行化。托管模式使用 daemon 的现有连接和 ACK 路径。
+- 默认授权是远端 `daemon.json.owners` 对发送 AID 的校验。
+- `--remote-token <token>` 使用 daemon 签发的远程访问 token，权限与 daemon-owner 一致。CLI 审计日志不会记录 token 明文。
+- `system/paircode` 例外：仅接受加密的 daemon-owner 请求，已有 remote token 不能换取新配对码。
+- `--ecweb-token <token>` 是 `--remote-token` 的兼容别名。
+- `menu.query` / `menu.options` 等待响应超时时自动重发一次相同 request id；写操作不自动重试。
+- 成功时 stdout 是完整 `menu.response` JSON。远端业务错误仍在响应的 `error` 字段中；本地传输/超时错误退出码非 0。独立终端的 ACK 错误也以非零退出码返回；托管模式由 daemon 的正常消费路径处理 ACK。
+
+## 常用请求
+
+```json
+{"type":"menu.query","id":"status-1","name":"system","args":{"view":"status"}}
+{"type":"menu.query","id":"monitor-1","name":"system","args":{"view":"monitor"}}
+{"type":"menu.query","id":"logs-1","name":"system","args":{"view":"logs","source":"daemon","limit":200}}
+{"type":"menu.action","id":"paircode-1","name":"system","action":"paircode"}
+{"type":"menu.options","id":"config-options-1","name":"config","args":{"option":"rawFile"}}
+{"type":"menu.query","id":"config-1","name":"config","args":{"view":"rawFile","resource":"daemon"}}
+```
+
+先用 `menu.list` 的 `args.view=catalog`、`context.kind=process` 获取目标 daemon 实际支持的能力和 wire 参数，不要在适配器中另建一套协议字段。

package/kits/docs/evolcore/model.md

@@ -1,50 +1,50 @@
-# ec model - 模型管理命令集
-
-按作用域查看或设置 agent 使用的模型与推理强度。`ec model` 修改持久化配置，对该作用域内所有会话的下一条消息生效；`ec ctl model` 只操作当前运行会话。
-
-## 命令
-
-```bash
-# 列出可用模型并显示当前生效模型
-ec model list [--self <aid>] [--peer <peer>] [--role <role>]
-
-# 显示生效模型、推理强度和配置来源
-ec model current [--self <aid>] [--peer <peer>] [--role <role>]
-
-# 查看单个模型详情
-ec model info <model-id> [--self <aid>]
-
-# 设置模型，可同时设置推理强度；本机终端写操作需要 --self
-ec model use <model-id> --self <aid> [--peer <peer>] [--effort <level>]
-
-# 设置推理强度：low | medium | high | xhigh | max | auto
-ec model effort <level> --self <aid> [--peer <peer>]
-
-# 清除当前作用域的模型和推理强度，回落到上一级
-ec model reset --self <aid> [--peer <peer>]
-
-# 诊断网关连通性、模型目录和模型可用性
-ec model check [--self <aid>]
-```
-
-## 作用域
-
-| 参数 | 作用域 | 配置位置 |
-|------|--------|----------|
-| 无 | 只读 catalog/defaults | 不允许写入 |
-| `--self <aid>` | agent | `agents/<aid>/config.json` |
-| `--self <aid> --role <role>` | 角色策略预览 | 只读；写入由角色策略编辑器管理 |
-| `--self <aid> --peer <peer>` | 关系 | `agents/<aid>/relations/<peerKey>/config.json` |
-
-生效优先级为关系、角色、agent、defaults。`--peer` 可使用 `channelType#channelId`；裸 AID 按 `aun#<aid>` 处理。
-
-在 EvolCore 托管会话中，省略 `--self`、`--peer`、`--role` 时，`list/current/use/effort/reset`
-会通过 `ec ctl` 作用于当前会话；显式 selector 仍按上表访问持久化作用域。本机终端不具备该隐式当前会话语义。
-
-## 输出与权限
-
-- 所有子命令支持 `--format json`。
-- 从聊天菜单或 agent 工具调用时，命令会在执行前经过 operation 鉴权；关系目标默认限制为当前 agent 和当前关系。
-- 本地终端直接运行时不伪造远端角色。显式传入 `--role` 可检查该角色的模型可见性和有效模型。
-- `use`、`effort`、`reset` 不直接修改角色策略；传入 role 写作用域会返回 `ROLE_POLICY_MANAGED`。
-- `check` 会连接已配置的模型网关并发送最小探测请求；未配置自定义网关时跳过 API 探测。
+# ec model - 模型管理命令集
+
+按作用域查看或设置 agent 使用的模型与推理强度。`ec model` 修改持久化配置，对该作用域内所有会话的下一条消息生效；`ec ctl model` 只操作当前运行会话。
+
+## 命令
+
+```bash
+# 列出可用模型并显示当前生效模型
+ec model list [--self <aid>] [--peer <peer>] [--role <role>]
+
+# 显示生效模型、推理强度和配置来源
+ec model current [--self <aid>] [--peer <peer>] [--role <role>]
+
+# 查看单个模型详情
+ec model info <model-id> [--self <aid>]
+
+# 设置模型，可同时设置推理强度；本机终端写操作需要 --self
+ec model use <model-id> --self <aid> [--peer <peer>] [--effort <level>]
+
+# 设置推理强度：low | medium | high | xhigh | max | auto
+ec model effort <level> --self <aid> [--peer <peer>]
+
+# 清除当前作用域的模型和推理强度，回落到上一级
+ec model reset --self <aid> [--peer <peer>]
+
+# 诊断网关连通性、模型目录和模型可用性
+ec model check [--self <aid>]
+```
+
+## 作用域
+
+| 参数 | 作用域 | 配置位置 |
+|------|--------|----------|
+| 无 | 只读 catalog/defaults | 不允许写入 |
+| `--self <aid>` | agent | `agents/<aid>/config.json` |
+| `--self <aid> --role <role>` | 角色策略预览 | 只读；写入由角色策略编辑器管理 |
+| `--self <aid> --peer <peer>` | 关系 | `agents/<aid>/relations/<peerKey>/config.json` |
+
+生效优先级为关系、角色、agent、defaults。`--peer` 可使用 `channelType#channelId`；裸 AID 按 `aun#<aid>` 处理。
+
+在 EvolCore 托管会话中，省略 `--self`、`--peer`、`--role` 时，`list/current/use/effort/reset`
+会通过 `ec ctl` 作用于当前会话；显式 selector 仍按上表访问持久化作用域。本机终端不具备该隐式当前会话语义。
+
+## 输出与权限
+
+- 所有子命令支持 `--format json`。
+- 从聊天菜单或 agent 工具调用时，命令会在执行前经过 operation 鉴权；关系目标默认限制为当前 agent 和当前关系。
+- 本地终端直接运行时不伪造远端角色。显式传入 `--role` 可检查该角色的模型可见性和有效模型。
+- `use`、`effort`、`reset` 不直接修改角色策略；传入 role 写作用域会返回 `ROLE_POLICY_MANAGED`。
+- `check` 会连接已配置的模型网关并发送最小探测请求；未配置自定义网关时跳过 API 探测。