evolcore 0.0.35 → 0.0.37

package/kits/docs/evolcore/msg.md

@@ -1,6 +1,6 @@
 # ec msg — 私聊消息命令
 
-私聊场景下收发消息的命令集。触发词：回复/发消息/拉取/撤回/查在线。
+私聊场景下收发消息的命令集。触发词：回复/发消息/拉取/撤回/查在线/能力调用/请求等待/结果查询。
 
 ## Agent 会话中的 Shell 调用边界
 
@@ -36,8 +36,20 @@ ec msg send <from> <to> --link <url> [--title '<title>'] [--description '<desc>'
 
 # 自定义 payload（JSON）
 ec msg send <from> <to> --payload '<json>'
+
+# 发送自定义 payload 并等待关联结果
+ec msg send <from> <to> --payload '<json>' --return required --timeout 60s --format json
+
+# 单向发送，不建立结果关联
+ec msg send <from> <to> --payload '<json>' --return none
 ```
 
+`--payload` 优先按 JSON 对象解析；为兼容 Windows 命令包装器，也接受“一层 JSON 字符串包裹 JSON 对象”的形式。
+最多额外解包一层，最终值必须是 JSON 对象；数组、普通字符串、数字、布尔值和 `null` 均会被拒绝。
+在当前 Windows PowerShell 托管环境中，调用 `ec.cmd` 时使用单引号包裹 JSON，并在 JSON 内每个
+双引号前加一个反斜杠，例如 `--payload '{\"type\":\"query\"}'`。反斜杠只用于命令行参数传递，
+`ec` 收到的最终值仍必须是合法 JSON；工具协议所需的 JSON 转义由工具调用层完成。
+
 每一行都必须单独执行，且是该次 shell 调用中的唯一命令。
 
 发送相关选项：
@@ -49,10 +61,15 @@ ec msg send <from> <to> --payload '<json>'
 - `--content-type <mime>` — 显式覆盖 MIME（仅 `--file`）
 - `--text <说>` — 附件说明文字（仅 `--file`）
 - `--transcript <text>` — 语音转写（仅 `--as voice`）
+- `--return none|required` — 是否建立通用请求/响应关联；`required` 会等待结果，默认不要求结果
+- `--timeout <duration>` — `--return required` 的本地等待时间及 AUN volatile TTL，如 `30s`、`60s`、`2m`；未指定时默认 60 秒，最大 3600 秒
+- `--format json` — 输出结构化发送回执和响应
 
 未指定 `--content-type` 时，附件 MIME 由 SDK 按实际字节识别、后缀回退，附件描述沿用上传后的类型。
 `--as` 控制消息展示类型，与 MIME 独立。
 
+托管会话中的附件源文件必须位于当前项目目录或当前会话 `$TMPDIR` 内；符号链接、硬链接、路径穿越和受保护路径会被拒绝。
+
 托管 Agent 通过 daemon 发送时，若发送方使用 `policyMode: contacts`，私聊普通出站只允许 Owner 或实际 `active` 联系人。无条目、`pending`、`declined` 会拒绝发送并提示：
 
 ```bash
@@ -67,10 +84,55 @@ ec contact unblock <target-aid> --self <self-aid>
 
 非托管环境的 `ec msg send` 是独立 AUN CLI 发送，不读取或要求 `agents/<aid>/config.json`，因此不会触发这套 Agent 联系人准入判断。
 
-在 EvolCore 会话内，发送会经过当前 session 的 self/peer/role 鉴权。`visitor` 或 `member` 默认只允许回复当前对端；要联系当前对端以外的对象，必须通过话题路由：先 `ec thread list <对方AID>` 选话题（没有就 `ec thread create`），再用 `ec msg send '<text>' --thread <threadId> --check-every <时长>` 发送；from/to 由话题推断，无需手写。不带 `--thread` 直接改目标会被拒绝。完整话题路由操作序列见 `[memory-and-thread]` 段。没有成功 JSON 回执（含 `message_id`/`status`）不得声称已发送。
+在 EvolCore 会话内，发送会经过当前 session 的 self/peer/role 鉴权。`visitor` 或 `member` 默认只允许回复当前对端；要联系当前对端以外的对象，必须通过话题路由：先 `ec thread list <对方AID>` 选话题（没有就 `ec thread create`），再用 `ec msg send '<text>' --thread <threadId> --check-every <时长>` 发送；from/to 由话题推断，无需手写。不带 `--thread` 直接改目标会被拒绝。`--check-every` 到期后，系统会向**目标话题**投递一条【跨话题复查】通知（不新建会话），由目标话题侧的 agent 在自己的上下文里决定结束、调整周期或继续。完整话题路由操作序列见 `[memory-and-thread]` 段。没有成功 JSON 回执（含 `message_id`/`status`）不得声称已发送。
 
 成功输出：`✓ 已发送 <message_id> seq=<n> status=<status>`
 
+## 请求/响应等待与异步查询
+
+`message_id` 和传输 `status` 只表示 AUN/daemon 接受了消息，不表示对端能力已经执行。
+需要业务结果时使用 `--return required`。返回 `request_state=completed` 且带 `response` 才表示
+已经收到关联结果；`failed` 表示传输失败；`pending` 或 `unknown` 表示本地无法在 deadline
+内确认执行状态，不能据此推断能力没有执行，也不能自动重发副作用消息。
+
+如果关联业务结果先到、传输失败回执后到，已完成结果保持成功并返回 response；迟到的传输诊断保留在 transport_error，且 retryable=false，不能因此重复执行请求。
+
+`--return required` 不按普通持久消息发送。EvolCore 会把本地等待时间转换为顶层
+`message.send.ttl`（秒，向上取整；默认 60 秒），因此 AUN 消息服务使用 volatile 内存通道，
+不写数据库/WAL，也不分配持久 `seq`。AUN volatile TTL 最大为 3600 秒，所以 required 请求的
+`--timeout` 也不能超过 3600 秒。这个顶层传输 TTL 不会写入或改动业务 payload。
+
+EvolCore 本地仍会保存请求关联记录，供 `ec msg request get` 查询迟到结果；这是调用方本地的
+请求索引，不是 AUN 服务端对消息正文的持久化。
+
+对于 `type=ability`，对端可能先返回 `role=ack`/`execution_state=pending`。这只会记录
+应用层已受理，等待不会结束；后续匹配同一 `call_id` 的 `role=result` 才会把请求置为
+`completed`。AUN transport ACK 与 Ability ACK 都不是最终业务结果。
+
+Ability payload 已有 `call_id` 时，EvolCore 使用它作为通用 transport request ID；不会无条件
+注入新的 `request_id`。只有普通请求既没有 `request_id` 也没有 `call_id` 时，才会生成并注入
+`request_id`。`operation_id` 始终由业务协议管理。
+
+发送超时或返回 `pending` 后，可以使用 request ID 查询持久化状态：
+
+```bash
+ec msg request get <self-aid> <request-id> --format json
+```
+
+查询必须由原始托管会话提供有效的 sessionId 和 delegationToken，且本端、关系、来源话题与请求登记上下文一致；跨话题目标仍须通过既有目标授权。知道 request ID 不代表有权查询，独立终端及缺少来源授权的旧记录不返回请求详情。查询是只读操作，不会重新发送消息，可以稍后重复查询。`--return none` 不建立请求记录，
+不能使用此命令查询其结果。发送命令在顶层返回 `request_id` / `request_state` / `response`；
+查询命令返回 `{ ok, request }`，状态和响应分别位于 `request.state` / `request.responsePayload`。
+
+`pending` 是本地等待超时，不是终态，迟到结果仍可置为 `completed`；迟到 transport ACK 不得将已完成、失败或超时状态改回 `sent`。同一本端的 request_id/call_id 不能覆盖已登记的请求或别名，重复时返回 `REQUEST_ID_CONFLICT`，应使用新的关联 ID。
+
+同步等待依赖 daemon 的长连接入站订阅，因此当前只在 EvolCore 托管会话中可用。独立终端的
+短连接发送若指定 `--return required` 会返回 `REQUEST_WAIT_REQUIRES_DAEMON`，不会静默降级成
+单向发送；需要单向发送时显式使用 `--return none` 或省略 `--return`。
+
+若托管命令审批与 daemon 一次性授权未能绑定，JSON 输出会包含
+`code=INVALID_DELEGATION`、`detail_code=APPROVED_COMMAND_UNAVAILABLE`、`retryable=false`、
+`sent=false`。这表示 AUN 消息尚未发出，应停止并报告授权链路问题；不要提权、改身份或自动重发。
+
 > 正文写法：含空格/换行/特殊字符时用引号包起来；纯短词可不包，但多空格会被压成一个。
 > 正文恰好以 `--` 开头：带空格的（如 `"--file 是正文"`）会被正确识别为正文；
 > 若正文**精确等于**某个 flag 名（如要发送文本 `--encrypt`），用 `--` 分隔：

package/kits/docs/evolcore/skill.md

@@ -0,0 +1,86 @@
+# ec skill — 技能管理
+
+EC 技能系统允许 agent 通过 SKILL.md 文件扩展自身能力。
+
+## 加载技能（最常用）
+
+```bash
+ec skill load <技能名>                  # 输出 SKILL.md 正文 + 技能根目录绝对路径
+ec skill load <技能名> --with-frontmatter  # 同上，附带 frontmatter 元数据
+ec skill load <技能名> --source builtin    # 指定来源（builtin|local），同名冲突时用
+```
+
+技能未启用时报错：`技能未启用: <name>`，需先 `ec skill enable <name>` 再加载。
+
+输出末尾会附带：
+```
+---
+skillDir: <技能目录绝对路径>
+```
+脚本路径、references/ 等资源均以此为根。
+
+## 查路径
+
+```bash
+ec skill path <技能名>   # 输出 SKILL.md 完整绝对路径（含状态和时间戳）
+```
+
+同名技能（本机覆盖内置）时两行都输出，并标注建议路径。
+
+## 技能列表与详情
+
+```bash
+ec skill list [--all] [--filter '<kw1,kw2>']... [--page <n>] [--limit <n>] [--json]
+                                   # 默认仅列启用；--all 全部；
+                                   # --filter 匹配技能名+描述（大小写不敏感），可多次出现，
+                                   #   组内逗号分隔为 OR，多组之间为 AND；
+                                   # --json 默认返回全部匹配项，显式给 --page/--limit 才分页；
+                                   # 超出 limit 条自动分页（默认 20），页脚给出翻页命令和 filter 提示
+ec skill info <name> [--json]      # 单个技能详情：路径、状态、三级开关、描述
+ec skill where                     # 打印三级根目录（内置/本机/Agent）
+```
+
+## 启用与禁用
+
+```bash
+ec skill enable <name> [--level agent|local]   # 启用（默认 agent 级）
+ec skill disable <name> [--level agent|local]  # 禁用（默认 agent 级）
+```
+
+- agent 级开关仅影响本 agent，需本 agent 的 owner 或 admin 权限
+- local 级开关影响整机所有 agent，需 daemonowner 权限
+- 群聊中一律拒绝写操作
+
+## 安装与删除
+
+```bash
+ec skill install <目录|.zip|.md> [--force] [--enable]   # 安装到本机级（默认禁用）
+ec skill remove <name>                                    # 删除本机级技能
+ec skill create <name> [--desc '...'] [--enable]         # 新建骨架（默认禁用）
+```
+
+内置技能（随包发布）不可删除，只能 disable。
+
+## 校验与刷新
+
+```bash
+ec skill validate <name|路径>    # 校验 SKILL.md 是否合规（name/description/kebab-case）
+ec skill refresh <aid>           # 重建该 agent 的技能索引（改完开关后执行）
+```
+
+## 三级结构
+
+| 级别 | 位置 | 写权限 |
+|------|------|--------|
+| 内置级 | `$PACKAGE_ROOT/kits/skills/` | 只读，随包发布 |
+| 本机级 | `$EVOLCORE_HOME/skills/` | daemonowner |
+| Agent 级 | `$AGENT_DIR/skills/` | 本 agent 的 owner/admin |
+
+Agent 级只放 `.switches.json`（开关），SKILL.md 在内置级或本机级。
+同名技能本机级覆盖内置级。
+
+## 权限边界
+
+- 群聊中所有写操作一律拒绝（含 enable/disable/install/remove/create）
+- `/skill` 斜杠命令（只读+refresh）：群聊仅 admin+ 可用，refresh 私聊也需 admin+
+- `ec skill load`/`path`/`list`/`info`/`where`：所有角色可用

package/kits/docs/evolcore/stats.md

@@ -64,6 +64,12 @@ ec stats --session <session-id> --last
 ec stats --rebuild
 ```
 
+`--task-calls` and `--session-calls` show runner-reported model usage rows. For Codex, a row is a
+degraded per-turn or subagent-thread aggregate, not an exact provider request count. When Codex
+reports child-thread usage, it is included in the task token total and shown as a separate `subagent` row.
+
+子代理按已观察到的累计计数差额计入当前任务，不把历史 total 与 last 重复相加；无法取得累计基线时仅使用本次明确上报的 last，可能低估未观察到的早期调用。各行保留真实 provider thread 和已知模型，未知模型标为 unknown，不套用父模型价格。含子代理的 usage_events 按模型分别写入和计价，不再额外写一次父子总计；父任务完成回执等待子代理结束后生成。未知模型费用保持未知。
+
 ## 直接 SQL 查询
 
 ```bash

package/kits/docs/evolcore/task.md

@@ -9,6 +9,8 @@ ec task resume <sessionId> --format json
 
 暂停任务会释放原有的工具门控。异常中断任务会把内部恢复提示排入同一会话，并继续原 baseagent 会话。命令只确认恢复请求已被可靠接纳，不会等待模型运行结束。
 
+`__task-recovery` 自动恢复要求原错误事件和持久终态都明确为 `recoverable: true`；`false` 或缺失不自动重试。依赖缺失、权限或配置问题需先修复，之后可人工执行本命令；人工恢复不受该布尔字段限制，但仍遵守会话绑定、待审批、任务代际和取消等安全检查。
+
 恢复任务继承原任务的审批交互策略，而非因为自动恢复使用 Trigger 就禁止审批。普通会话（包括 Agent 间和群聊的 proactive 模式）允许申请审批；无人值守 Trigger 禁止申请审批。Handoff 回流同样继承发起任务的策略。继承策略不等于复用旧审批，新的待审批操作仍须发起新请求；缺少历史策略时，自动恢复和 Handoff 回流默认禁止审批，手动恢复默认允许申请。
 
 以下情况会安全结束而不创建新会话：任务已完成或正在运行、任务等待必要输入/审批、会话已删除、原 provider 会话文件不存在、渠道不可用，或任务状态已被更新。

package/kits/docs/evolcore/thread-chain.md

@@ -2,7 +2,7 @@
 
 话题（Thread）是在私聊或群聊关系里切出的独立对话分支。一组对话可以同时推进多个话题，每个话题有自己的上下文、历史和生命周期，互不干扰。话题链（Thread Chain）则是跨会话、跨 agent 的协作机制：A 可以把一条任务"分支"到 B 的某个话题，B 也可以在自己的话题里继续工作，两者通过 `ec msg send --thread` 和 thread-inbox 上下文注入关联起来。
 
-触发词：话题/thread/跨会话/委托/ec thread/话题链/summary/删除话题/thread-inbox/跨会话上下文。
+触发词：话题/thread/跨话题/委托/ec thread/话题链/summary/删除话题/thread-inbox/跨话题上下文/跨话题复查。
 
 ## 标准工作流
 
@@ -22,12 +22,12 @@ ec thread list <peer> --self <selfAid>
 ec thread list <peer> --self <selfAid> --page 2 --limit 10 --sort recent
 
 # 第五步：查看某话题的历史消息
-ec thread history <peer>/<threadId> --self <selfAid> --limit 20
+ec thread history <threadId> --self <selfAid> --limit 20
 
 # 第六步：查看/写入 summary
-ec thread summary show <peer>/<threadId> --self <selfAid>
+ec thread summary show <threadId> --self <selfAid>
 # 写入时必须带 --name（同时设标题）；不想改名传 -（详见「话题摘要」一节）
-ec thread summary set <peer>/<threadId> '<摘要内容>' --name '<新标题>' --self <selfAid>
+ec thread summary set <threadId> '<摘要内容>' --name '<新标题>' --self <selfAid>
 ```
 
 ## 什么时候用
@@ -38,7 +38,7 @@ ec thread summary set <peer>/<threadId> '<摘要内容>' --name '<新标题>' --
 - 想保存话题摘要（summary），供下次激活时快速恢复上下文
 - 整理完成或废弃的话题时（删除话题）
 
-主会话（主对话，无 threadId）不能删除。话题是主会话之外额外创建的分支。
+主话题（该关系默认的对话，id 形如 `main:<aidA>:<aidB>`）不能删除。话题是主话题之外额外创建的分支。
 
 ## 基础操作
 
@@ -59,19 +59,19 @@ ec thread list <peer> --format json
 ### 查看话题详情
 
 ```bash
-ec thread show <peer>/<threadId>
+ec thread show <threadId>
 ec thread show current          # 当前任务所在话题
-ec thread show <peer>           # 该对端的主会话
+ec thread show main:<aidA>:<aidB>   # 该对端的主话题（id 来自 ec thread list）
 ```
 
 ### 读取话题历史消息
 
 ```bash
-ec thread history <peer>/<threadId>
-ec thread history <peer>/<threadId> --limit 100
-ec thread history <peer>/<threadId> --after 1700000000000
-ec thread history <peer>/<threadId> --before 1700000000000
-ec thread history <peer>/<threadId> --format json
+ec thread history <threadId>
+ec thread history <threadId> --limit 100
+ec thread history <threadId> --after 1700000000000
+ec thread history <threadId> --before 1700000000000
+ec thread history <threadId> --format json
 ```
 
 托管会话中可以直接用 `ec msg history --thread <id>`，from/to 会自动从运行时上下文推断：
@@ -94,17 +94,17 @@ ec thread create <peer> --name '项目A' --label 项目A --status in_progress
 ### 修改话题
 
 ```bash
-ec thread rename <peer>/<threadId> '新名称'
-ec thread rename <peer> '新名称'                # 裸 peer 指主会话；等价于 <peer>/main
-ec thread label <peer>/<threadId> 重要
-ec thread label <peer>/<threadId> --clear       # 清除标签
-ec thread status <peer>/<threadId> completed    # pending|in_progress|completed|archived
+ec thread rename <threadId> '新名称'
+ec thread rename main:<aidA>:<aidB> '新名称'    # 主话题改名
+ec thread label <threadId> 重要
+ec thread label <threadId> --clear       # 清除标签
+ec thread status <threadId> completed    # pending|in_progress|completed|archived
 ```
 
-主会话可以改名（落在会话存档的 `name` 字段），但**不能**打标签或改状态——label/status 只对子话题生效。
-`ec thread list` / `show` 里主会话的名称带 `[主会话] ` 前缀，该前缀只在展示层加，不是真实名字。
+主话题可以改名（落在会话存档的 `name` 字段），但**不能**打标签或改状态——label/status 只对话题生效。
+`ec thread list` / `show` 里主话题的名称带 `[主话题] ` 前缀，该前缀只在展示层加，不是真实名字。
 
-`summary set ... --name` 对主会话同样生效，改名走与 `ec thread rename` 相同的路径。
+`summary set ... --name` 对主话题同样生效，改名走与 `ec thread rename` 相同的路径。
 
 #### 名称长度
 
@@ -121,14 +121,14 @@ ec thread status <peer>/<threadId> completed    # pending|in_progress|completed|
 ### 删除话题
 
 ```bash
-ec thread delete <peer>/<threadId>    # 软删除：session 文件移入 _trash/，索引条目删除
+ec thread delete <threadId>    # 软删除：session 文件移入 _trash/，索引条目删除
 ```
 
-删除后话题从索引中消失，`ec thread list` 不再显示。底层 session 文件通过 `unbindSession` 机制移入 `chatDir/_trash/`，与系统其他删除行为一致。不能删除正在处理中（busy）的话题，也不能删除主会话。
+删除后话题从索引中消失，`ec thread list` 不再显示。底层 session 文件通过 `unbindSession` 机制移入 `chatDir/_trash/`，与系统其他删除行为一致。不能删除正在处理中（busy）的话题，也不能删除主话题。
 
 删除时会自动取消该话题的所有关联 Trigger，防止 ghost wakeup。
 
-删除后历史仍可通过 `ec thread history <peer>/<threadId>` 读取（直接读 messages.jsonl，不依赖索引）。
+删除后历史仍可通过 `ec thread history <threadId>` 读取（直接读 messages.jsonl，不依赖索引）。
 
 ## 跨会话发送（话题链核心）
 
@@ -141,21 +141,34 @@ ec msg send <from> <to> '<消息内容>' --thread <threadId>
 # 托管会话简化形式（from/to 自动从运行时上下文推断）
 ec msg send '<消息内容>' --thread <threadId>
 
-# 附带复查 Trigger（跨话题时必填；每 30m 唤醒本端回查）
+# 附带跨话题复查（跨话题时必填；每 30m 向目标话题投递一次复查通知）
 ec msg send '<消息内容>' --thread <threadId> --check-every 30m
 ```
 
 注意事项：
 
-- `--thread` 指定的话题必须已存在于本端索引（`ec thread list` 可见），否则返回 `TOPIC_NOT_FOUND`
+- `--thread` 必须是本端已存在的话题：话题查索引，主话题（`main:<selfAid>:<peerAid>`）查该关系的 active session。都不存在时返回 `TOPIC_NOT_FOUND`
+- **主话题可以作为跨话题发送的目标**。例如：
+  ```bash
+  # A 向 B 的主会话发送消息（从 A 的某个话题跨过去）
+  ec msg send '请在主会话查看这个报告' --thread 'main:bob.aid:alice.aid'
+  ```
+  主话题的 ID 可以从 `ec thread list <peer>` 的输出中获取（第一行就是主话题）
 - **跨话题发送时 `--check-every` 为必填项**，不指定会直接报错。取值如 `5m` / `30m` / `2h` / `1d`
 - 跨话题发送成功后，系统会在**本端**写一条 thread-inbox 记录。目标话题下次被唤醒时，
-  这条记录会以「⟵ 跨会话上下文 · 来源话题:xxx」的形式注入一次，然后删除
-- `--check-every` 会创建周期复查 Trigger（名称 `check-<目标>-from-<来源>-<唯一后缀>`，`kind=thread-check`），
-  每隔指定时长唤醒本端话题，提示回查目标话题与来源话题，直到显式
-  `ec trigger cancel <triggerId>` 结束。**每次发送都新建一个 Trigger**，取消/调整用
-  返回的 `trigger_id`（形如 `trig_…`）——`ec trigger` 的定位标识是 **id 不是名称**
-- `--trigger-prompt "<text>"` 可选，用于替换复查 prompt 中的自定义段（默认给出通用的检查/决策指引）
+  这条记录会以「‹跨话题上下文 · 来源话题:xxx›」的形式注入一次，然后删除
+- `--check-every` 会创建**跨话题复查**（名称 `check-<目标>-from-<来源>-<唯一后缀>`，
+  `kind=cross-thread-review`，执行类型 `target_session`）。到期时**不新建会话**，
+  而是向**目标话题**投递一条【跨话题复查】通知，由目标话题侧的 agent 在它自己的上下文里
+  决定：结束复查、调整周期、或继续等待
+  - 通知内容：复查次数、来源话题（名称 + threadId）、当前话题、发送时间、已过时长、
+    复查周期、Trigger id、原消息正文
+  - 结束/调整用返回的 `trigger_id`（形如 `trig_…`）——`ec trigger` 的定位标识是 **id 不是名称**
+  - **结束复查用 `ec trigger delete <id>`，不要用 `ec trigger cancel`**：cancel 只是 disable，
+    定义和调度状态仍留在磁盘上，复查这种用完即弃的 Trigger 会积压成大量永不触发的死定义
+  - **每次发送都新建一个复查**；要延长周期请用 `ec trigger update <id> --every <时长>`，
+    不要重发一条带 `--check-every` 的消息
+- `--trigger-prompt "<text>"` 可选，用于替换通知正文中的用户段
 
 ### 跨会话委托的完整流程
 
@@ -166,19 +179,40 @@ ec msg send '<消息内容>' --thread <threadId> --check-every 30m
 ec msg send '请处理项目A的数据清洗' --thread thread-T2-xxxx --check-every 2h
 ```
 
-**B 接收时感知来源上下文：**
+**A 收到 B 的回复时感知来源上下文：**
 
-B 的目标话题下次被唤醒时，prompt 开头会注入一条跨会话上下文，格式如下：
+inbox 记录在发送方 A 本端。A 的目标话题 T2 下次被唤醒时（通常是 B 回复），prompt 开头会注入一条跨话题上下文，格式如下：
 
 ```
-‹跨会话上下文 · 来源话题:thread-T1-xxxx · 对端:alice.agentid.cn · 发送于:2026-10-10 10:00›
-⚠️ 来源话题在发送后已有 3 条新消息（10:01 - 10:15）—— 处理前建议先回查该话题的空洞期消息。
-🔔 复查 Trigger:trig_1791765199642_5371c8ff（尚未触发/待处理）
+‹【跨话题上下文】来源话题:thread-T1-xxxx · 对端:alice.agentid.cn · 发送于:2026-10-10 10:00:00 +08:00 · 复查:trig_1791765199642_5371c8ff → self:bob.agentid.cn›
+⚠️ 来源话题在发送后已有 3 条新消息（2026-10-10 10:01:00 +08:00 - 2026-10-10 10:15:00 +08:00）—— 处理前建议先回查该话题的空洞期消息。
 【原消息内容】
 ```
 
-注入只发生一次。之后 B 靠自身上下文记住"我从哪个话题跨过来的"，可随时用
-`ec thread history <来源peer>/<来源话题>` 回查空洞期消息。
+信封头的 `复查:` 字段恒出现：有复查 Trigger 时是它的 id，没建成时显示 `无`。
+
+注入只发生一次。之后 A 靠自身上下文记住"我从哪个话题跨过来的"，可随时用
+`ec thread history <来源话题 id>` 回查空洞期消息（主话题的 id 是 `main:<a>:<b>`，
+通知里的「来源话题 ID」字段可直接使用）。
+
+**复查通知到达时（目标话题内）：**
+
+```
+‹【跨话题复查】来源话题:thread-1792370100339-5976-0a5c · 对端:alice.agentid.cn · 发送于:2026-10-19 08:18:42 +08:00 · 复查:trig_1792369122624_aa1c9068 → self:bob.agentid.cn›
+【跨话题复查】第 2 次
+
+来源话题：A 的项目讨论（对端 alice.agentid.cn）
+来源话题 ID：thread-1792370100339-5976-0a5c
+当前话题：C 的进度查询（对端 carol.agentid.cn）
+发送于：2026-10-19 08:18:42
+已过：5 分钟
+复查周期：5m（每 5m 提醒一次，直到处理）
+
+Trigger：trig_1792369122624_aa1c9068
+
+原消息：
+项目当前进度如何？
+```
 
 ## 话题摘要（Summary）
 
@@ -187,21 +221,21 @@ daemon 不自动总结，需要 agent 主动写入。
 
 ```bash
 # 查看当前摘要（同时打印 coveredThroughTs 覆盖游标）
-ec thread summary show <peer>/<threadId>
+ec thread summary show <threadId>
 
 # 写入摘要 —— --name 必填：同时把话题改成这个标题
-ec thread summary set <peer>/<threadId> '项目A需求已确认，正在开发登录模块' --name '项目A登录模块'
+ec thread summary set <threadId> '项目A需求已确认，正在开发登录模块' --name '项目A登录模块'
 # 不想改话题名就显式传 -
-ec thread summary set <peer>/<threadId> '<摘要内容>' --name -
+ec thread summary set <threadId> '<摘要内容>' --name -
 
 # 支持 CAS（乐观锁），防止并发覆盖
-ec thread summary set <peer>/<threadId> '新内容' --name - --if-rev 3
+ec thread summary set <threadId> '新内容' --name - --if-rev 3
 
 # 查看历史版本
-ec thread summary log <peer>/<threadId>
+ec thread summary log <threadId>
 
 # 清空当前摘要（历史版本保留）
-ec thread summary clear <peer>/<threadId>
+ec thread summary clear <threadId>
 ```
 
 ### 覆盖游标与增量总结
@@ -213,16 +247,16 @@ ec thread summary clear <peer>/<threadId>
 
 ```bash
 # 1. 拿覆盖游标
-ec thread summary show <peer>/<threadId>          # 输出中的 coveredThroughTs
+ec thread summary show <threadId>          # 输出中的 coveredThroughTs
 
 # 2. 读游标之后的增量（首次总结无游标时省略 --after，全量读）
-ec thread history <peer>/<threadId> --after <coveredThroughTs> --limit 50
+ec thread history <threadId> --after <coveredThroughTs> --limit 50
 
 # 3. 增量较多时往回翻页（history 支持 before 逆序分页）
-ec thread history <peer>/<threadId> --before <本页最早一条的ts> --limit 50
+ec thread history <threadId> --before <本页最早一条的ts> --limit 50
 
 # 4. 读完增量后写摘要，游标自动推进到当前最新一条
-ec thread summary set <peer>/<threadId> '新摘要' --name -
+ec thread summary set <threadId> '新摘要' --name -
 ```
 
 **约束**：`summary set` 把游标设为**写入时刻话题的最新一条**，所以跨话题总结必须**先把增量读完再写**——
@@ -242,7 +276,7 @@ CAS 说明：`--if-rev <n>` 指定当前已知的版本号；若实际版本不
 data/threads/
 ├── index.json      话题索引
 ├── summaries/      话题摘要（<sessionId>.summary.jsonl）
-└── inbox/          跨会话上下文收件箱
+└── inbox/          跨话题上下文收件箱
 ```
 
 ```bash
@@ -259,8 +293,15 @@ ec thread check-index                   # 同 rebuild-index --check
 | 格式 | 含义 |
 |---|---|
 | `current` | 当前任务所在话题 |
-| `<peer>` | 该对端的主会话 |
-| `<peer>/<threadId>` | 指定话题，如 `bob.agentid.cn/thread-xxx-0001-aaaa` |
+| `<threadId>` | 话题，如 `thread-1791028341906-0000-136a` |
+| `main:<selfAid>:<peerAid>` | 主话题，**规范格式**，两端 AID 顺序可互换 |
+
+`ec thread list` 打印的第一列就是可用的话题 ID，可直接复制进任何接受 `<ref>` 的参数。
+
+**主话题说明**：
+- 主话题不在话题索引中，但可以作为 `threadId` 参数使用
+- 规范格式是 `main:<selfAid>:<peerAid>`（两端 AID 哪个在前都行，系统会自动识别）
+- 主话题 id 只有在**当前本端是其中一端**时才能解析；它不跨本端传播——拿到别人的主话题 id 会失败，而不是猜一个对端
 
 ## 话题状态值
 
@@ -281,3 +322,56 @@ ec thread check-index                   # 同 rebuild-index --check
 | `SUMMARY_CAS_CONFLICT` | 摘要版本冲突 | 重新 `show` 获取最新 rev，再重试 |
 | `INVALID_NAME` | 话题名称不合法 | 名称不能为空 |
 | `NAME_TOO_LONG` | 话题名称超过 83 字符（正文 80 + 省略号） | 按报错里的当前长度缩写后重试 |
+
+## Trigger 配置中的话题 ID
+
+在 Trigger 配置的 `origin` 字段中，可以用 `threadId` 指定投递目标话题（包括主话题）。系统会根据 `threadId` 的格式**自动推导** `origin.session` 的值，无需手动填写。
+
+### 配置示例
+
+**投递到主会话**：
+
+```json
+{
+  "$schema_version": 4,
+  "agentAid": "bob.agentid.pub",
+  "name": "每日同步",
+  "source": {
+    "type": "cron",
+    "cron": "0 9 * * *"
+  },
+  "origin": {
+    "channel": "aun",
+    "peerId": "alice.agentid.cn",
+    "threadId": "main:bob.agentid.pub:alice.agentid.cn"
+  },
+  "execution": {
+    "agentSessionId": "compact-start",
+    "prompt": "今日同步报告"
+  }
+}
+```
+
+**投递到指定话题**：
+
+```json
+{
+  "origin": {
+    "channel": "aun",
+    "peerId": "alice.agentid.cn",
+    "threadId": "thread-1792370100339-5976-0a5c"
+  }
+}
+```
+
+### 自动推导规则
+
+| `threadId` 格式 | 自动推导的 `session` | 说明 |
+|---|---|---|
+| `main:<a>:<b>` | `'main'` | 主会话 |
+| `thread-...` | `'thread'` | 话题会话 |
+| 空/未填 | `'main'` | 默认主会话 |
+
+如果手动填写了 `origin.session` 字段，系统会校验它是否与推导结果一致。不一致时配置解析会报错。
+
+**推荐做法**：只填 `threadId`，让系统自动推导 `session` 字段。

package/kits/docs/evolcore/trigger.md

@@ -10,7 +10,7 @@
 
 文件输入限制为 4 MiB，拒绝符号链接、junction、硬链接、路径逃逸、其他会话临时目录、密钥及其他 Agent 私有数据。普通定义导入必须属于当前 Agent；脚本只上传 `execution.script.path` 指定的单个文件，不允许覆盖 `trigger.json`、`active.json` 等管理状态。绝对 `--script-path` 会上传脚本内容并保存 Agent 内相对路径，不保留宿主绝对路径。`--help` / `-h` 在鉴权和文件读取前返回。
 
-普通脚本 Trigger 按每次执行重新核验的 Agent 授权运行，复用主会话的权限模式与 H/L 路径保护：`readonly` 项目只读且禁止读取 L 类路径，`auto/request` 项目可写、L 类路径只读；认证 `owner + bypass` 关闭项目写入沙箱，但仍遮蔽 H 类路径并保护 L 类路径。网络默认开放，不需要网络权限配置；保留宿主 HOME、Git/SSH 与代理环境，清除 daemon 凭据、任务 delegation 和代码注入变量。`request` 的非交互脚本不能申请额外权限，越界操作直接失败，不自动升级。脚本使用只读快照和独立临时工作目录；快照位置不同于持久化 Trigger 目录，需要项目资源时按工作目录定位。Node `.js` 保留原 package 的模块类型。
+普通脚本 Trigger 按每次执行重新核验的 Agent 授权运行，复用主话题的权限模式与 H/L 路径保护：`readonly` 项目只读且禁止读取 L 类路径，`auto/request` 项目可写、L 类路径只读；认证 `owner + bypass` 关闭项目写入沙箱，但仍遮蔽 H 类路径并保护 L 类路径。网络默认开放，不需要网络权限配置；保留宿主 HOME、Git/SSH 与代理环境，清除 daemon 凭据、任务 delegation 和代码注入变量。`request` 的非交互脚本不能申请额外权限，越界操作直接失败，不自动升级。脚本使用只读快照和独立临时工作目录；快照位置不同于持久化 Trigger 目录，需要项目资源时按工作目录定位。Node `.js` 保留原 package 的模块类型。
 
 - Linux：需要可用的 `bubblewrap`，复用会话权限运行时的进程隔离和 H/L 路径保护，不隔离网络命名空间；受限模式将宿主根目录只读映射，按权限开放项目和当前 run 临时目录，完整保留系统依赖及 `/etc/alternatives` 链接。
 - Windows：需要支持受限读取策略的原生 Codex CLI，以及宿主已准备好的 elevated sandbox。每次启动前先用同一个临时 canary 验证“显式授权可读、撤回授权后拒绝读取”和当前 run 可写；只有权限拒绝才算通过，文件不存在、探针超时或取消均失败关闭。旧初始化、不支持的运行时或无法证明读取隔离时返回 `SCRIPT_SANDBOX_UNAVAILABLE`，不会启动用户脚本；托管任务不会自动提权、初始化沙箱或降级为宿主执行。
@@ -119,7 +119,7 @@ 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`。
+`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 秒基础设施时限，不计为任务执行超时。
 
@@ -135,8 +135,37 @@ Trigger V3 第二阶段使用 `execution.type` 区分执行位置：
 
 省略 `--trigger-thread` 时默认使用 `by-trigger`，同一个 trigger 复用同一条 trigger 会话；只有显式指定 `--trigger-thread per-run` 时，每次 run 才使用独立 trigger 会话。
 
-`script` 执行随 trigger 一起保存的脚本：
+### 跨话题复查（kind=cross-thread-review）
+
+`ec msg send --thread <T2> --check-every 5m` 创建的复查用 `target_session` 执行：
+到期时**不创建 trigger 会话**，而是把渲染好的通知作为一条入站消息投进目标话题 T2
+的本地会话队列，由 T2 侧的 agent 在 T2 自己的上下文里决策。
+
+```json
+{
+  "labels": {
+    "kind": "cross-thread-review",
+    "originThreadId": "<来源话题 threadId>",
+    "targetThreadId": "<目标话题 threadId>",
+    "checkEvery": "5m",
+    "firstSentAt": "<首次发送时间戳>",
+    "originalText": "<原消息正文>"
+  },
+  "execution": { "type": "target_session", "prompt": "<通知模板>", "onError": "retry", "noopSentinel": "[[NOOP]]" },
+  "feedback": {
+    "strategy": "target",
+    "target": { "channelKey": "<channelKey>", "channelId": "<目标对端>", "session": "thread", "threadId": "<T2>", "chatType": "private" }
+  }
+}
+```
+
+- 通知模板在触发时由 `renderTemplate` 渲染，可用 `{{run.number}}`（第几次）、
+  `{{run.elapsed}}`（已过多久）、`{{trigger.labels.*}}` 等变量。
+- 这类投递在消息上带 `triggerMeta.reviewKind = 'cross-thread-review'`，执行身份取
+  **目标话题会话自身的对端**，而不是 `originPeerId`（来源话题的对端）。
+- 设计见 `docs/thread-chain/cross-thread-review-design.md`。
 
+`script` 执行随 trigger 一起保存的脚本：
 ```bash
 --exec script \
 --script-path scripts/check.js \
@@ -254,6 +283,19 @@ ec trigger rm <triggerId>       # delete 的兼容别名
 
 `delete` 不需要先执行 `disable/cancel`；它内部会先清理 timer/event/schedule，再删除定义。
 
+> **用完即弃的 Trigger（如跨话题复查）结束时应使用 `delete` 而不是 `cancel`**：`cancel` 只写
+> `enabled: false`，定义会一直留在 `$EVOLCORE_HOME/agents/<aid>/triggers/` 下，长期积累成
+> 大量永不触发的死定义。
+
+## 谁可以操作一条 Trigger
+
+操作主体由定义的 `operatorPeers` 决定：创建时写入 **origin 对端 + feedback 目标对端**，
+两者都能 `show / list / update / cancel / delete / enable / disable`。旧定义没有该字段时
+按同样规则现算，不需要迁移。
+
+身份口径：私聊取对端 AID（`peerId`），群聊取**群 AID**（`channelId`，即 `group_id`）。
+群会话里 `origin.peerId` 记录的是群内发言人，不作为操作主体身份。
+
 ## 局部更新
 
 `update` 是 patch 语义，只提交需要修改的字段；未指定字段（包括长 prompt）保持不变。`--prompt-file <path>` 只更新非 script trigger 的 prompt，不接受完整 definition。已有 script trigger 使用 `--script-file <path>` 原地替换脚本内容；脚本路径、runtime、args 和调度配置保持不变：
@@ -461,6 +503,8 @@ daemon 启动时会自动维护一个名为 `__task-recovery` 的系统 Trigger
 
 系统 Trigger 直接调用内部 task recovery service，复用异常任务的原 `sessionId`、Agent AID、provider 会话、task generation 及原对话路由。它不会发送一条伪造的“继续”消息，不创建替代会话，也不会因为 daemon-owned 而把目标 Agent 的普通会话权限提升为操作系统权限。手动 `/resume` 和 `ec task resume <sessionId>` 仍然是同一恢复入口的人工调用方式。
 
+自动恢复仅接受 `recoverable: true` 的 `task:error`；`false` 或缺失均不触发。该标记由报错端基于原始错误统一判定，同时写入错误消息、事件和任务终态，不按 sandbox/socat 文本在恢复层另设黑名单。恢复执行自身的失败也传递该标记，只有明确可重试时才使用有界退避；不可重试的失败保留失败审计但不继续重跑。历史终态缺少该字段时不自动恢复，修复环境后仍可人工 `/resume`。
+
 下面的 Trigger 覆盖当前 Agent 的所有会话；`agentAid` 过滤避免其它 Agent 的事件进入本 Trigger，`originTriggerId` 排除自身产生的恢复错误，避免递归触发：
 
 ```json
@@ -475,6 +519,7 @@ daemon 启动时会自动维护一个名为 `__task-recovery` 的系统 Trigger
     "filter": {
       "match": {
         "agentAid": "<aid>",
+        "recoverable": true,
         "originTriggerId": { "$exists": false }
       }
     }