evolcore 0.0.25 → 0.0.27

package/kits/docs/evolcore/group.md

@@ -1,152 +1,267 @@
-# 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
+
+# 查询本地群历史（不调用 Gateway，不推进 group pull/ack 游标）
+ec group history <from> <group-id> --unread [--limit <N>] [--thread <id>] [--format json]
+ec group history <from> <group-id> --all [--limit <N>] [--thread <id>] [--format json]
+
+# 拉取群消息（建议带 --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`
+
+## 本地群历史
+
+`history` 读取本机的 `messages.jsonl`，不连接 Gateway，不改变 `group pull/ack` 游标。
+这里的自动已读只记录本地历史查询进度；`group pull` / `group ack` 仍是独立的 Gateway 消费游标命令，二者互不替代。
+查询必须显式指定 `--unread` 或 `--all`；首次没有日志时返回空结果，不创建模型会话。
+
+| 选项 | 含义 |
+|---|---|
+| `--unread` | 最早的未读群背景，按本地记录顺序输出，并自动记录本页已读 |
+| `--all` | 最近的群会话历史，包含没有未读标记的旧日志及出站消息 |
+| `--limit N` | 默认 50，范围 1–500；单页另有 24 KiB 消息预算 |
+| `--thread main\|all\|id` | 无话题、整个群或指定话题；当前群任务默认继承当前话题，其他调用默认 all |
+| `--direction in\|out\|all` | 方向过滤，默认 all |
+| `--before/--after time` | 接收时间开区间，支持 epoch 毫秒和 ISO 时间 |
+| `--format text\|json` | 默认 text |
+| `--message msg-id` | 配合 --all 查询指定消息正文，不改变已读状态 |
+| `--offset bytes` | 配合 --message 从返回的 next_offset 继续读取长正文 |
+
+`--unread` 会把本次返回的消息自动记为已读，再次执行即可取得下一页，无需额外确认。
+查询期间新到的消息、未返回条目及其他筛选范围的消息不会被清除。`--all` 始终只浏览、不改变已读状态。
+`has_more` 表示本次还有匹配内容，普通 `--all` 可用时间/话题进一步缩小范围。
+
+长正文以 `content_truncated` 标识；预览返回后该消息也记为已读，需要完整内容时使用
+`--all --message <msg-id> --offset <next_offset>` 继续读取。偏移为 UTF-8 字节边界，每段最多 8 KiB。
+附件返回已有类型、名称或转写摘要，不自动下载。已读不会删除历史，随时可用 `--all` 回看。
+
+受管执行通过 `group.op` 和 delegation 授权；member 限当前 Agent 的当前 AUN 群，
+owner/admin 按 Agent 管理范围查询其他群；visitor 默认拒绝。读取时的已读记录由服务内部维护。
+不支持 `--app`、`--aun-path` 或自选历史文件路径。
+
+旧记录仍可用 `--all` 查询；精确未读统计从新增的本地过滤标记开始，不根据缺少 sessionId 猜测。
+已读状态独立存储，重启、renew、切模型不会清空；历史只包含本机收到并记录的会话内容。
+
+## 群管理
+
+```bash
+# 创建群
+ec group create <from> "<name>" [--visibility public|private] [--description "<desc>"] [--join-mode <mode>] [--group-id <aid>]
+
+# 不指定 --group-id 时，默认名称为 g- 加五位随机数字（10000–99999）
+# 例如返回 g-12345.agentid.cn；issuer 以群服务实际返回为准
+ec group create <from> "研讨群" --visibility private
+
+# 自定义群 AID；g- 若出现，是名称的一部分，会完整保留
+ec group create <from> "本体研讨" --group-id ontology.agentid.cn
+
+# 列出我加入的群
+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` 子命令。
+
+## 收到群邀请：Owner 审核
+
+Agent 的 AUN 主渠道收到定向邀请后，由 daemon 查询待处理邀请并向当前 `owners[]` 的每位 Owner
+发送加密私聊卡片。卡片提供“接受入群”和“拒绝邀请”；收到邀请不会自动加入，也不启动模型。
+接受/拒绝操作先记录决定，再查询当前邀请并调用 SDK，最终结果另行通知 Owner。
+
+Owner 可以在与该 Agent 的 AUN 私聊中直接输入以下命令（不经过模型）：
+
+```text
+/invites
+/invites 2
+/invites <审核编号> open
+/invites <审核编号> accept
+/invites <审核编号> reject
+```
+
+列表每页 10 条，显示审核编号和状态。`open` 重新发送当前 Owner 的卡片；审核编号由列表返回，
+不同于 Gateway 的 invite ID。卡片默认有效 24 小时；忽略、关闭或过期均不拒绝邀请。
+多 Owner 同时操作时，第一个成功落盘的决定锁定本轮；其余点击不能提交相反决定。
+
+邀请、决定与投递记录持久化。重启后旧卡失效，对账仍为待审核时发新卡；没有 Owner 或发送失败时
+保留邀请。请求超时后保留原决定并核实结果，期间不开放相反操作。未加入事实无法确认时显示“正在核实结果”，
+不能仅因邀请从列表消失就断言已拒绝。
+
+也可使用邀请 RPC 命令：
+
+```bash
+ec group invites <from> [--page N] [--size N]
+ec group accept-invite <from> <invite-id>
+ec group reject-invite <from> <invite-id>
+ec group revoke-invite <from> <invite-id>
+```
+
+托管会话的 `accept-invite/reject-invite` 仅允许当前 Agent Owner 在 AUN 私聊中执行，并进入同一持久化审核服务；
+admin、普通成员或仅具 daemon-owner 身份者不能代替该 Agent Owner。宿主直接运行的独立 CLI 保留原 RPC 路径，
+外部客户端造成的状态变化通过后续对账识别。`revoke-invite` 是原邀请者撤回自己发出的邀请。
+
+接受后沿用 SDK 的成员/密钥同步，以及现有群消息、群规则和 mentionMode 策略；不自动发送入群欢迎消息。
+
+## 成员
+
+```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>
+
+# 屏蔽成员接收群消息；member-aid 填 from 即屏蔽自己
+ec group block <from> <group-id> <member-aid> [--reason "<reason>"]
+
+# 取消屏蔽
+ec group unblock <from> <group-id> <member-aid>
+
+# 查看屏蔽列表（群管理员）
+ec group blocklist <from> <group-id>
+
+# 显式上报自己的群内状态；两项均必填，值为字符串
+ec group report-status <from> <group-id> --online-status online --work-status busy
+
+# 查看群成员上报状态（包括未上报的成员）
+ec group member-statuses <from> <group-id>
+```
+
+屏蔽与封禁互相独立：`block` 停止接收实时/离线 Push、Pull 和 E2EE wrap，但不影响发送；
+`ban` 禁止发送但不影响接收。群成员可屏蔽/取消屏蔽自己；群 owner/admin 可在其权限范围内操作其他成员并查看屏蔽列表。
+
+`report-status` 只更新 `<from>` 自己在指定群内的状态，不接受其他成员参数；不会启动定时心跳。
+`member-statuses` 返回群成员主动上报的状态，`online` 仍查询 Gateway 在线连接索引。
+服务端维护的更新时间、最后发言时间与 payload 类型保留在 `--format json` 结果中。
+
+托管任务还须通过 Core 关系权限：member 只能在当前 AUN 群中操作当前 Agent 的自身屏蔽/状态及查询成员状态；
+操作他人和查询屏蔽列表需要 Core owner/admin，随后仍由 Gateway 校验该 Agent 的群内权限。
+visitor 不开放这五个命令；托管调用不允许替换 `<from>`、`--app` 或 `--aun-path`。
+
+## 入群与公告
+
+当前 CLI 封装了 `join` 和 `rules`。审批申请、邀请码、公告等高级管理能力第一批暂不提供单独命令。
+
+## 通用约定
+
+- `<from>` 必须是合法 AID（入口统一校验，格式错直接报错）
+- `--format json` — 对支持结构化结果的子命令输出 JSON
+- `--app <name>` — 仅 `pull` / `ack` 指定独立消费 slot
+- `--aun-path <path>` — 指定 AUN keystore 根
+- `--encrypt` — 仅 send，启用端到端加密（群聊默认明文）
+- `create` 会通过 SDK 自动生成并导入群 `group_aid` 身份。
+- 默认群名遇到明确的身份占用错误时最多尝试 5 次；显式指定的名称不会自动更换，超时或身份导入失败也不会换名重建。
+- 创建结果以服务端返回的 `group_aid` 为准；与请求不一致时输出提示，JSON 结果包含 `warning` 和 `requested_group_aid`。
+- `owner` 会走 SDK 的群主转让授权签名流程，需要本机有该群 `group_aid` 的私钥；若网关返回 `pending_rekey`，CLI 会在本机存在新群主私钥时自动调用完成步骤，否则输出“已发起，等待新群主完成 rekey”。
+
+## Group ID
+
+AUN 群 AID 使用 `{base}.{issuer}`，例如 `ontology.agentid.cn`、`g-12345.agentid.cn`、`11824.agentid.pub`。base 为 4–64 位，首字符为小写字母或数字，后续可包含小写字母、数字、下划线和连字符。`g-` 是 EvolCore 默认建群的命名约定，不是判断一个 AID 是否属于群的协议标志。
+
+群命令支持完整 AID 和本域 base 简写；简写按发送方 AID 的 issuer 补全。完整 AID 中的 issuer 和 base 会保留（统一小写），不会删除 `g-`。`group.{issuer}/{base}` 已停止支持，不会自动转换；`base@issuer` 也不支持，两者均明确报错。请直接使用群服务返回的 `{base}.{issuer}`。群文件路径应提供完整群 AID，如 `ontology.agentid.cn:/rules.md`。
+
+普通主体与群的 AID 格式可以相同。格式校验只检查参数是否合法，当前群限制、身份和权限校验仍由托管会话与服务端执行。
+
+## 自主回复策略
+
+群聊中默认被 @ 才响应，可通过 venue policy 配置其他触发条件。

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

@@ -1,34 +1,58 @@
-# 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 不能换取新配对码。
+- 配对码有效期为 10 分钟，成功兑换一次即失效；并发兑换最多一次成功。再次获取会生成新码，已签发 token 不受影响。
+- 未消费的码由各入口共享，重复获取不延长有效期。发放来源记录在运行时 `data/instance/control-access-tokens.json` 的 `pairingIssuances`：`host-cli` 为宿主机 CLI，`pair` 为 `/pair`，`menu` 为 AUN Menu，`ecweb-local` 为本地 ECWeb。`pair` / `menu` 同时记录已认证 daemon owner 的 `authorizedBy` AID；同一码经多个入口发放时保留全部不同来源与 owner，而不覆盖旧记录。
+- 发放记录包含 `pairingId`、发放/到期时间、`issuers` 和成功兑换时间 `redeemedAt`，保留 30 天；不保存配对码或其哈希。成功兑换的 token 同时保存 `pairingId` / `pairingIssuers`，后续续期与 daemon 重启不丢失来源。旧 token 缺少来源时不补造历史。
+- `--ecweb-token <token>` 是 `--remote-token` 的兼容别名。
+- Menu 请求和响应使用 `message.send` 顶层 `ttl: 60`，接收响应时应支持 volatile 游标和无持久 `seq`；响应若带 `sender_device_id`，服务端会用 `to_device_id` 定向回原设备。
+- `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":"baseagents-1","name":"baseagents"}
+{"type":"menu.query","id":"subtasks-1","name":"session","args":{"view":"subtasks"}}
+{"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 参数，不要在适配器中另建一套协议字段。
+
+`name=baseagents` 查询返回 `{ active, baseagents: [{ id, label, configured, detected, loaded, active, model, effort, version }] }`。
+控制 AID / EC Web 沿用进程管理鉴权，返回 defaults 配置、主机检测、全局已加载 runner；
+发往 Agent AID 时沿用 `agent.baseagent.list` 权限，仅返回当前 Agent 的配置及 runner，`detected=null` 表示未探测主机。
+`menu.options name=baseagent` 仍只提供可切换的已加载后端。
+
+子任务示例需发往目标 Agent 的会话；话题可用 `name=topic args={"target":"<threadId>","view":"subtasks"}`。
+返回 `{ scope: "retained-history", tasks: [...] }`。普通 session/topic 状态另带 `subtasks`、`subtasksScope`；
+`/status` 单列“已记录子任务数”，不把它加到主会话轮数中。历史来自现有 `events*.log`，
+受 `EVENT_LOG` 开关和日志保留期限制（当前归档保留 48 小时）；无记录不能据此推断从未执行过子任务。

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 探测。