evolcore 0.0.26 → 0.0.28

package/kits/docs/evolcore/aid.md

@@ -1,6 +1,6 @@
 # ec aid — AID 身份管理
 
-管理本地 AID 身份（证书、私钥、agent.md 名片），以及远程探测对端 AID。触发词：身份/证书/名片/探测对端/创建身份。
+管理本地 AID 身份（证书、私钥、agent.md 名片与头像），以及远程探测对端 AID。触发词：身份/证书/名片/头像/换头像/探测对端/创建身份。
 
 ## 运行边界
 
@@ -17,6 +17,14 @@ ec aid avatar <当前 self AID> (--file <path> | --url <https-url>) [--format js
 
 仅允许不带选项的基本形式，或在末尾附加一组完整的 `--format json`；不能使用 `--aun-path`、未知选项、管道、重定向或其它命令。所有 `allowAccess=true` 的已认证角色（包括 visitor、member、admin、owner 及自定义角色）均开放 `lookup` 和 `agentmd get`，目标可以是任意合法 AID。`show` 只允许当前 self AID：owner/admin 返回完整本地身份诊断，visitor/member 及其它非管理角色返回不含私钥存在性、密钥匹配和签名能力的脱敏结果。三个查询可在所有 `permissionMode` 执行。`agentmd put` 和 `avatar` 会发布远端名片，属于写操作，仅允许针对当前 self AID 的 `request`、`bypass`，`readonly`、`auto` 和未知模式均拒绝。头像支持 PNG、JPEG、WebP，大小上限 500KB，分辨率 128–2048 像素，宽高比 0.8–1.25；`--url` 仅支持 HTTPS，下载由 daemon 执行并做 SSRF/重定向校验。成功 JSON 返回 `sha256`、MIME 和尺寸元数据。`lookup` 探测指定公开 AID；`get` 下载并验签指定公开名片，同时刷新本地 AID 缓存。`list`、其它 AID 的 `show/agentmd put/avatar` 以及 `new/delete` 均拒绝。独立终端不受此托管会话限制。
 
+## 更换头像
+
+`ec aid avatar <当前 self AID> --file <图片路径>` 从本地文件上传；`ec aid avatar <当前 self AID> --url <HTTPS 图片地址>` 下载图片后上传。两种来源必须二选一，可在末尾加 `--format json` 获取头像 URL、SHA-256、MIME 和尺寸。
+
+托管会话中的本地图片必须位于当前会话项目目录或本会话的托管 `$TMPDIR`；相对路径以会话项目目录为基准。不能读取受保护的 EvolCore 路径、符号链接，或托管临时目录中的硬链接。
+
+上传复用 menu 的头像处理流程：校验图片、上传到 AUN storage、更新并发布 `agent.md` 的 `avatar` 字段，成功后发出 `agent:avatar_updated` 事件。无需手动修改名片或再次执行 `agentmd put`。托管 Agent 只能修改自身头像，仍需通过角色与命令授权检查。
+
 ## 子命令
 
 ```bash

package/kits/docs/evolcore/config.md

@@ -10,7 +10,8 @@
 ```bash
 # 读 effective 值（显示覆盖链来源）；可一次传多个字段批量读取（共享同一 selector/--format）
 ec config get <field> [<field> ...] [--self <aid>] [--peer <X>] [--default] [--process]
-#   单字段输出不变；多字段时 text 每行一条、json 返回 { ok, results: [...] }，任一字段失败退出码为 1
+#   单字段输出不变；多字段时 text 每行一条、json 返回 { ok, results: [...] }。
+#   不支持的 runner 字段会保留逐字段 UNSUPPORTED_FIELD，但不阻断同批支持字段；其它失败退出码为 1
 
 # 写参数：scope 由 selector 推断
 ec config set <field> <value> [--self <aid>] [--peer <X>] [--default] [--process]
@@ -132,6 +133,31 @@ 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 自身的安全边界，
@@ -177,12 +203,25 @@ ec config unset groupRules.mode \
 
 ## 权限控制
 
+**指定关系读取**：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 托管环境写仅人字段被拒

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

@@ -52,7 +52,7 @@ ec group create coordinator.agentid.pub "Project Alpha 协作" \
   --join-mode invite_only
 ```
 
-创建成功后，以响应中的 `group.group_id` 作为后续唯一群 ID。不要根据群名称自行猜测群 ID；规范群 ID 通常是 `g-{slug}.issuer-domain`。
+创建成功后，以响应中的 `group.group_aid`（兼容字段为 `group.group_id`）作为后续唯一群 AID。不要根据显示名称猜测群 AID。默认创建的名称为 `g-` 加五位数字，例如 `g-12345.agentid.cn`；自定义的 `ontology.agentid.cn` 也是合法群 AID。若返回 `warning`，仍使用实际返回的群 AID。
 
 立即检查群详情：
 

package/kits/docs/evolcore/group.md

@@ -4,7 +4,7 @@
 
 以自己的 AID 为发送者（`<from>`），群 AID 为 `<group-id>`。
 
-本命令覆盖常用消息、基础生命周期、成员操作、角色/群主管理、封禁、暂停/恢复和群规则。生产环境 agent 优先使用本页列出的 `ec group` 命令。
+本命令覆盖常用消息、基础生命周期、成员操作、角色/群主管理、封禁、屏蔽、成员状态、暂停/恢复和群规则。生产环境 agent 优先使用本页列出的 `ec group` 命令。
 
 需要发起一次完整的 Agent 群聊协作时，按场景流程阅读 `group-collaboration.md`；本文只作为命令参数参考。
 
@@ -20,6 +20,10 @@ ec group send <from> <group-id> --file <path> --return none|required [--as <type
 # 自定义 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>]
 
@@ -48,12 +52,52 @@ ec group send <from> <group-id> "通知" --mention alice.agentid.pub,bob.agentid
 - `--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>]
 
@@ -92,6 +136,45 @@ ec group rules <from> <group-id> publish
 
 搜索公开群、公开信息查询、群统计等高级能力当前未封装为 `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
@@ -127,8 +210,34 @@ 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`。审批申请、邀请码、公告等高级管理能力第一批暂不提供单独命令。
@@ -141,11 +250,17 @@ ec group unban <from> <group-id> <member-aid>
 - `--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 Group 协议当前规范使用 `g-{slug}.issuer-domain` canonical 群 ID；也可输入本域简写 `g-{slug}` 或兼容写法 `g-{slug}@issuer-domain`。历史 EvolCore 会话里可能还有 `group.agentid.pub/11718` 这类旧格式，看到时按已有群 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 格式可以相同。格式校验只检查参数是否合法，当前群限制、身份和权限校验仍由托管会话与服务端执行。
 
 ## 自主回复策略
 

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

@@ -24,7 +24,11 @@ ec menu-client request <from-aid> <daemon-aid> \
 - 默认授权是远端 `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。
 
@@ -32,6 +36,8 @@ ec menu-client request <from-aid> <daemon-aid> \
 
 ```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"}
@@ -40,3 +46,13 @@ ec menu-client request <from-aid> <daemon-aid> \
 ```
 
 先用 `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/msg.md

@@ -49,6 +49,9 @@ ec msg send <from> <to> --payload '<json>'
 - `--text <说>` — 附件说明文字（仅 `--file`）
 - `--transcript <text>` — 语音转写（仅 `--as voice`）
 
+未指定 `--content-type` 时，附件 MIME 由 SDK 按实际字节识别、后缀回退，附件描述沿用上传后的类型。
+`--as` 控制消息展示类型，与 MIME 独立。
+
 托管 Agent 通过 daemon 发送时，若发送方使用 `policyMode: contacts`，私聊普通出站只允许 Owner 或实际 `active` 联系人。无条目、`pending`、`declined` 会拒绝发送并提示：
 
 ```bash

package/kits/docs/evolcore/storage.md

@@ -4,6 +4,9 @@ AUN 网络上的文件存储：上传、下载、列举、删除、查配额。
 
 以自己的 AID 为操作者（`<aid>`）。
 
+上传和删除通过 SDK 文件系统执行；上传自动协商 inline、去重或 session，并统一 MIME 与请求头。
+`--public` 返回稳定的 AID 文件 URL，私有上传不返回公开 URL。日常文件操作优先使用 `ec fs`。
+
 ## 子命令
 
 ```bash

package/kits/docs/evolcore/task.md

@@ -0,0 +1,14 @@
+# ec task - 会话任务恢复
+
+`ec task resume` 统一恢复暂停任务和基础设施异常中断任务。它定位已有会话并读取会话持久化的任务、路由、加密和 baseagent 绑定；恢复时继续原 provider 会话。
+
+```text
+ec task resume <sessionId>
+ec task resume <sessionId> --format json
+```
+
+暂停任务会释放原有的工具门控。异常中断任务会把内部恢复提示排入同一会话，并继续原 baseagent 会话。命令只确认恢复请求已被可靠接纳，不会等待模型运行结束。
+
+以下情况会安全结束而不创建新会话：任务已完成或正在运行、任务等待必要输入/审批、会话已删除、原 provider 会话文件不存在、渠道不可用，或任务状态已被更新。
+
+独立 CLI 必须通过 daemon 的本地 control token。托管任务使用当前任务 delegation token，并需要 Agent 管理权限；普通 Agent 只能恢复当前 Agent 的会话，daemon scope 才能恢复其它 Agent 的会话。

package/kits/docs/evolcore/trigger.md

@@ -89,7 +89,7 @@ ec trigger update <triggerId> --prompt-file ./prompts/daily-summary-v2.md
 
 这些来源互斥，只能指定一个。`--cron` 表达式必须加引号，避免被 shell 拆成多个参数。`--every` 是固定间隔，`--cron` 是日历调度。`--once` 创建后立即进入一次 run，完成后自动禁用。
 
-`--event` 基于 EventBus 事件触发，事件模式支持精确事件名、命名空间前缀和全量：`message:received`、`message:*`、`*`。flag 模式只支持设置 `eventPattern`；需要按 payload 字段过滤时，使用 Trigger V3 第二阶段 JSON 的 `source.filter.match`，再通过 `--file` 导入。事件清单、payload 字段和过滤操作见 `$KITS_DOCS/evolcore/event.md`。
+`--event` 基于 EventBus 事件触发，事件模式支持精确事件名、命名空间前缀和全量：`message:received`、`message:*`、`*`。创建时可用 `--event-filter <JSON>` 设置事件过滤条件，例如 `--event-filter '{"match":{"sessionId":"meta-1"}}'`；它仅可与 `--event` 一起使用，对应 Trigger V3 定义的 `source.filter`。事件清单、payload 字段和过滤操作见 `$KITS_DOCS/evolcore/event.md`。
 
 ## 执行类型
 
@@ -103,6 +103,12 @@ Trigger V3 第二阶段使用 `execution.type` 区分执行位置：
 
 `target-session` 把 `--prompt` 或 `--prompt-file` 的内容当作一条 trigger 来源消息投递进目标会话队列，并等待该会话处理完成。创建时必须显式指定 `--exec target-session`，不会再隐式选择该类型。
 
+`target-session` 在主会话/话题会话执行时，默认没有额外的总执行时限，沿用普通任务的 idle watchdog 和 `idleMonitor.maxExecutionTime`；不会因运行超过 30 分钟或 4 小时而被 Trigger 强制结束。独立 `trigger-session` 默认每次 attempt 的总时限为 30 分钟。两者均可用 `--execution-timeout 2h`（definition 中为 `execution.timeoutMs`，毫秒正整数）显式设置，已有的全局任务时限仍可更早生效。`update --execution-timeout default` 清除单个 Trigger 的覆盖；script 继续使用 `--script-timeout`。
+
+目标会话每 30 秒核对一次具体 attempt 的队列、runner 与持久化终态。正常运行、排队、暂停及等待审批/回答不会仅因没有文本输出被清理；确认执行状态缺失并持续至少 120 秒后，按 `orphaned_target_session` 失败收尾。丢失的终态事件优先从持久化任务状态补齐。会话查找/创建另有 30 秒基础设施时限，不计为任务执行超时。
+
+执行超时发送 `status.timeout` 与 `result.error`；执行状态丢失发送 `status.error` 与 `result.error`。两者都保留任务关联和原因，不映射为消息撤回。`SDK_TIMEOUT` 立即结束当前 attempt，后续是否重试遵循 `onError` 和 `reliability.retry`，每个 attempt 独立计算显式时限。
+
 `trigger-session` 在 daemon 内部 trigger 会话执行 prompt，再把最终结果按 feedback 投递；prompt 可来自 `--prompt` 或 `--prompt-file`：
 
 ```bash
@@ -236,7 +242,7 @@ ec trigger rm <triggerId>       # delete 的兼容别名
 
 `update` 是 patch 语义，只提交需要修改的字段；未指定字段（包括长 prompt）保持不变。`--prompt-file <path>` 只更新非 script trigger 的 prompt，不接受完整 definition。已有 script trigger 使用 `--script-file <path>` 原地替换脚本内容；脚本路径、runtime、args 和调度配置保持不变：
 
-`--script-file` 只能通过本机受控 CLI 读取文件并提交给 daemon；脚本 trigger 属于 daemon-owner 控制面，managed Agent task 不能直接读取本地脚本文件。
+`--script-file` 只能通过本机受控 CLI 读取文件并提交给 daemon；脚本 trigger 属于 daemon-owner 控制面，managed Agent task 不能直接读取本地脚本文件。主机 fullaccess 开关缺失时默认开启；Agent 级 `fullaccess.enabled` 不会自动升级 Trigger，Trigger 仍按自身 execution.permissionMode 规则执行。
 
 ```bash
 ec trigger update <triggerId> --cron '0 10 * * *'
@@ -431,6 +437,48 @@ ec trigger create --exec script --file ./trigger-dir --enable
 
 ## 事件触发
 
+### 任务异常恢复到原会话
+
+`task:error` 可以直接把恢复请求路由到产生异常的原始会话，不需要通过 `ec msg send` 发送模拟的“继续”消息。`target_session` 执行类型配合 `event_session` feedback 时，daemon 从事件中的 `sessionId` 查找原会话，并复用其持久化的 baseagent/provider 会话。
+
+daemon 启动时会自动维护一个名为 `__task-recovery` 的系统 Trigger。这里的事件名仍然是 `task:error`；开头的 `__` 只表示 Trigger 的 ID/name 属于 EvolCore daemon 的系统定义，和 `__upgrade-check` 使用同一命名约定，不是事件命名空间。该 Trigger 的 daemon scope 覆盖同一 EvolCore daemon 管理的所有本机 Agent，跨 daemon 或远程 Agent 不在范围内。
+
+系统 Trigger 直接调用内部 task recovery service，复用异常任务的原 `sessionId`、Agent AID、provider 会话、task generation 及原对话路由。它不会发送一条伪造的“继续”消息，不创建替代会话，也不会因为 daemon-owned 而把目标 Agent 的普通会话权限提升为操作系统权限。手动 `/resume` 和 `ec task resume <sessionId>` 仍然是同一恢复入口的人工调用方式。
+
+下面的 Trigger 覆盖当前 Agent 的所有会话；`agentAid` 过滤避免其它 Agent 的事件进入本 Trigger，`originTriggerId` 排除自身产生的恢复错误，避免递归触发：
+
+```json
+{
+  "$schema_version": 3.1,
+  "agentAid": "<aid>",
+  "enabled": true,
+  "name": "resume-task-on-error",
+  "source": {
+    "type": "event",
+    "eventPattern": "task:error",
+    "filter": {
+      "match": {
+        "agentAid": "<aid>",
+        "originTriggerId": { "$exists": false }
+      }
+    }
+  },
+  "execution": {
+    "type": "target_session",
+    "prompt": "继续未完成任务",
+    "onError": "retry"
+  },
+  "feedback": { "strategy": "event_session" },
+  "reliability": {
+    "concurrency": "forbid",
+    "missedPolicy": "run_once",
+    "retry": { "maxAttempts": 2, "backoffMs": 30000 }
+  }
+}
+```
+
+`event_session` 会保留原会话的私聊/群聊、thread、对端身份和加密状态；找不到会话、会话已删除、原 provider 会话缺失或任务已正常完成时会失败关闭，不创建替代会话，也不会回退成普通消息投递。
+
 简单事件触发可直接用 flag 模式：
 
 ```bash
@@ -453,7 +501,7 @@ ec trigger create --event 'task:*' \
   --name on-task-events --enable
 ```
 
-flag 模式不能配置过滤条件。需要根据事件 payload 过滤时，写完整的 Trigger V3 第二阶段 JSON：
+需要根据事件 payload 过滤时，可在上述创建命令中加入 `--event-filter '{"match":{"sessionId":"meta-1"}}'`。过滤条件仅支持创建时配置，`update` 不接受 `--event-filter`。完整的 Trigger V3 第二阶段 JSON 也支持同样的过滤条件：
 
 ```json
 {

package/kits/docs/venues/group.md

@@ -24,6 +24,11 @@ AUN 群聊的命令查询、成功与进度反馈使用 `notice`，命令拒绝
 
 ## 可按需查询的群数据
 
+AUN 的提及模式会保留未被 @ 的会话消息。需要补充背景时使用
+`ec group history <self-aid> <group-id> --unread --format json`；
+查询与自动记录已读遵循专用 `group-unread-history` 片段及群命令文档。
+历史读取不会触发对其中每一条消息的回复。
+
 群结构信息（成员名单、各成员角色、群主、管理员、在线状态等）**不预先注入上下文**，
 需要时用 `ec group` 自行查询（完整用法 Read `$KITS_DOCS/evolcore/group.md`）：
 

package/kits/eck_manifest.json

@@ -139,6 +139,21 @@
       ] },
       "description": "渠道+场景文档（如 feishu-group）"
     },
+    {
+      "id": "group-unread-history",
+      "type": "file",
+      "file": "$KITS_FRAGMENTS/group-unread-history.md",
+      "order": 42.5,
+      "needsInjection": true,
+      "when": { "and": [
+        { "var": "channel", "eq": "aun" },
+        { "var": "chatType", "eq": "group" },
+        { "var": "mentionMode", "eq": "mention-only" },
+        { "var": "groupHistoryAvailable", "eq": true },
+        { "var": "lifecycle", "eq": "active" }
+      ] },
+      "description": "mention-only 群聊的本地未读历史读取指引"
+    },
     {
       "id": "relation-group-rules",
       "type": "file",
@@ -163,6 +178,18 @@
       ] },
       "description": "客户端环境文档"
     },
+    {
+      "id": "reply-contract",
+      "type": "file",
+      "file": "$KITS_FRAGMENTS/reply.md",
+      "order": 49,
+      "needsInjection": true,
+      "when": { "and": [
+        { "var": "channel", "neq": null },
+        { "var": "lifecycle", "in": ["active", "bootstrapping"] }
+      ] },
+      "description": "共用回复规则：当前模式、目标及托管发送边界"
+    },
     {
       "id": "channel-layer",
       "type": "file",

package/kits/rules/01-overview.md

@@ -4,13 +4,13 @@ ECK 的总览：前置概念和框架结构。
 
 ## Base Agent
 
-Base agent 是提供推理与生成能力的底层智能——如 Claude Code、Codex、Gemini 等。你就是当前会话的 base agent。
+Base agent 是提供推理与生成能力的底层智能，规范值有 `claude`（Claude Code）、`codex`（Codex）、`gemini`（Gemini CLI）、`ecagent`（EvolCore 内置基座）四类。你就是当前会话的 base agent；具体是哪一类以 `[baseagent]` 段注入的 `baseAgentName` 为准，不要默认自己是 Claude Code。
 
 ### 外部 Coding Agent Skills 边界
 
 当前会话由 EvolCore 托管时，不加载、不读取、不执行工作区之外的 coding-agent `SKILL.md`，包括
 `/home/evolcore/skills/eclink/SKILL.md`。该类 skill 只服务于独立运行、未接入 EvolCore 会话上下文的
-Codex/Claude Code 工具实例。EvolCore 会话必须遵循本 ECK、daemon IPC 和渠道适配层提供的通信与权限路径。
+Codex/Claude Code 等独立工具实例。EvolCore 会话必须遵循本 ECK、daemon IPC 和渠道适配层提供的通信与权限路径。
 
 尤其不要在 EvolCore 会话中因为看到 AUN/agent 间通信需求，就自行读取 `eclink` skill 或直接拼接 shell
 命令调用 `ec`；发送必须经过当前会话的 delegated sender，以便锁定 self/peer、角色、审计和回执。
@@ -37,14 +37,18 @@ AID（Agent Identifier）是主体在 AUN 网络中的唯一身份标识，格
 
 核心字段：`aid`、`name`（显示名）、`type`、`description`（一句话简介）、`avatar`、`tags`、`visibility`（public/unlisted/private）、`skills`。
 
-`type` 语义上分四类，都持有 AID、都能通过 AUN 向你发消息，对你而言**都是对端**：
+`type` 是可扩展字符串。EvolCore 内置以下常用类型；它们都持有 AID、都能通过 AUN 向你发消息，
+对你而言**都是对端**：
 
 | type | 含义 |
 |------|------|
 | `human` | 人类 |
-| `agent` | 会用到大模型的服务程序（agent.md 里写 `Claude Code`/`CodeX`/`Gemini CLI` 等具体 base agent 名，除 human 外都归为 agent） |
+| `agent` | 会用到大模型且没有专用主体类型的服务程序（agent.md 里可写 `Claude Code`/`Codex`/`Gemini CLI`/`ecagent` 等具体 base agent 名） |
 | `group` | 群服务（群本身也有 AID，是一类对端） |
 | `service` | 有 AID 但不使用大模型的服务程序 |
+| `device` | 设备或嵌入式节点 |
+| `org` | 组织主体 |
+| `host` | EvolCore 控制主机的 daemon AID；名称通常为 `<Win/Linux/MacOS>主机-<aid前缀>` |
 
 > **群属于关系层**：`group` 是对端的一种，具体群实例的数据与其它对端一样落关系层
 > `$RELATIONS_DIR/<peerKey>/`（见 `04-relation.md`），不落环境层。
@@ -83,7 +87,7 @@ AUN 把 agent 当网络主体（具备社会人属性:身份/通信/自主），
      Evol 前端            EvolCore
   (App/Web/Desktop)        Channel 适配层（AUN/飞书/微信/...）
    或其它 AUN 客户端       身份层 / 关系层 / 环境层 /  渠道层 / 会话层
-                           Base Agent（Claude Code / Codex / Gemini/...）
+                           Base Agent（claude / codex / gemini / ecagent）
 
 ```
 
@@ -138,9 +142,9 @@ evolcore 收到每条消息时，由**声明式 manifest** 决定加载哪些上
 | coding（无渠道） | active 时为 rules + 会话层 + baseagent（身份/关系/环境/渠道层因无 channel、无身份而落选） |
 | private（私聊） | rules + 身份层（含 preferences）+ 关系层（对端）+ 环境层 + 渠道层 + 会话层 + baseagent |
 | group（群聊） | rules + 身份层（**无 preferences**）+ 关系层（群）+ 环境层 + 渠道层 + 会话层 + baseagent |
-| bootstrapping | 仅 bootstrap 引导（不加载 rules、身份、关系、环境、渠道、会话、baseagent 或完整 commands 段） |
+| bootstrapping | bootstrap 引导 + 有渠道时的共用回复规则 `[reply]`（含最小身份、目标、chatMode）；不加载 rules、完整身份/关系/环境/渠道能力、会话、baseagent 或 commands 段 |
 
-> 常规段（包括 rules、session、baseagent）都要求 `lifecycle=active`。生命周期缺失按 `active` 处理；非法时，
+> 共用 `reply-contract` 在有渠道且 `lifecycle∈{active,bootstrapping}` 时加载；其余常规段（包括 rules、session、baseagent）都要求 `lifecycle=active`。生命周期缺失按 `active` 处理；非法时，
 > Manifest 不加载任何常规段；agent-owned turn 也不会直接落入普通 runner。
 
 三份 manifest 各管一段：`kits/eck_manifest.json`（system prompt 默认）、

package/kits/rules/04-relation.md

@@ -2,7 +2,8 @@
 
 关系层管理你对所有对端的认知。动态注入的 `peerKey`（`<channel>#<urlEncode(peerId)>`）是对端在所有渠道中的稳定标识。`peerId` 是对端在当前渠道的原生 ID（AUN 是 AID，飞书是 user_id 等），`channel` 是当前渠道类型。
 
-**对端包括群**：AID 四类型（human/agent/group/service，见 `01-overview.md`）对你而言都是对端，数据都在关系层。
+**对端包括群**：AID 类型（human/agent/group/service/device/org/host，见 `01-overview.md`）
+对你而言都是对端，数据都在关系层。
 - 私聊：`peerId` = 对端 ID，`peerKey` = `<channel>#<对端ID>`。
 - 群聊：`peerId` = **群 ID**（群本身的 AID / 渠道群 ID），群内所有发言者共用同一个 `peerKey`（群的键）。群规则、群 profile 等**具体群实例数据**落 `$RELATIONS_DIR/<peerKey>/`（如群规则物化到 `relations/<peerKey>/rules.md`）。
 

package/kits/rules/05-venue.md

@@ -19,7 +19,7 @@
 | coding | `chatType = null` 且 `lifecycle = active` | rules + 会话层 + baseagent | 本地模式，每条消息都响应 |
 | private | `chatType = private` 且 `lifecycle = active` | 上述 + 身份层（含 persona/working-memory/**preferences**）+ 关系层（对端 profile）+ 环境层 + 渠道层 + commands | 自主模式，回复方式随 `chatMode` |
 | group | `chatType = group` 且 `lifecycle = active` | 同 private，但**无 preferences**；`groupId` 有值加群 profile，`groupRulesPath` 有值加群规则 | 自主模式，`mentionMode` 决定是否响应 |
-| bootstrapping | `lifecycle = bootstrapping` | 仅 bootstrap 引导（所有常规段均落选） | 初始化引导 |
+| bootstrapping | `lifecycle = bootstrapping` | bootstrap 引导 + 有渠道时的 `[reply]` 最小通信上下文，其余常规段落选 | 仅推进首次设定，回复方式随实际 `chatMode` |
 
 > coding 场景在 agent `active` 时加载 `session` 与 `baseagent`；生命周期缺失按 `active` 处理，非法时按 fail-closed 处理。
 

package/kits/rules/06-channel.md

@@ -16,13 +16,13 @@
 
 ## 通信规则
 
-"当前这一刻怎么回复、怎么发消息"由动态注入的 `[channel]` 段决定——它能拿到 `chatMode`
-并按模式分流，是唯一的事实源。本节只讲**模式无关的恒定知识**。
+"当前这一刻怎么回复、怎么发消息"由动态注入的 `[reply]` 段决定——它展示运行时解析的 `chatMode`
+并按模式分流，是 Bootstrap 与 active 共用的回复规则。`[channel]` 仅在 active 阶段补充文件、链接、@ 等扩展能力。本节只讲**模式无关的恒定知识**。
 
 要点：
-- **回复方式随 `chatMode` 走**，以 `[channel]` 段为准：
+- **回复方式随实际 `chatMode` 走**，以 `[reply]` 段为准，不按对端类型或是否私聊推断：
   - interactive：直接输出即回复
-  - proactive：见 `[channel]` 段的机制说明（thought.put vs message.send）
+  - proactive：通过托管发送通道正式回复，见 `[reply]` 段（thought.put vs message.send）
 - **附加能力与模式无关、始终需要 CLI**：发文件/图片/语音、@某人、加密、联系第三方
 - **以自己的 AID 为发送者**；拿不到时退回 `ec ctl send "<text>"`
 
@@ -45,6 +45,8 @@
 **完整命令集目录（含分类、触发词、适用场景）**：`$KITS_DOCS/evolcore/INDEX.md`。
 单个命令集的详细用法按需 Read 对应文档。
 
+托管 Agent 任务禁止调用 `ec start`、`ec stop`、`ec restart` 或 `ec restart-monitor`。这些是宿主终端的进程生命周期命令；源码改动后 Agent 只负责构建并报告需要宿主重启，不得尝试、重试或建议 Agent 自己执行 `ec restart`。
+
 共同约定：
 - 以自己的 AID 为发送者
 - 回复方式随 `chatMode` 走（见上方通信规则）；附加能力（文件/@/加密/发第三方）任何模式下都用 CLI