evolcore 0.0.32 → 0.0.33

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

@@ -0,0 +1,267 @@
+# ec thread — 话题链命令
+
+话题（Thread）是在私聊或群聊关系里切出的独立对话分支。一组对话可以同时推进多个话题，每个话题有自己的上下文、历史和生命周期，互不干扰。话题链（Thread Chain）则是跨会话、跨 agent 的协作机制：A 可以把一条任务"分支"到 B 的某个话题，B 也可以在自己的话题里继续工作，两者通过 `ec msg send --thread` 和 thread-inbox 上下文注入关联起来。
+
+触发词：话题/thread/跨会话/委托/ec thread/话题链/summary/删除话题/thread-inbox/跨会话上下文。
+
+## 标准工作流
+
+话题是对端级别的操作，先找到 agent 和对端，再操作话题：
+
+```bash
+# 第一步：列出本机所有 agent（找到目标 selfAid）
+ec agent list
+
+# 第二步：列出该 agent 有话题记录的所有对端
+ec thread peers --self <selfAid>
+
+# 第三步：列出与某对端的所有话题（默认每页10条）
+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
+
+# 第六步：查看/写入 summary
+ec thread summary show <peer>/<threadId> --self <selfAid>
+# 写入时必须带 --name（同时设标题）；不想改名传 -（详见「话题摘要」一节）
+ec thread summary set <peer>/<threadId> "摘要内容" --name "<新标题>" --self <selfAid>
+```
+
+## 什么时候用
+
+- 同一对端有多条并行任务线（项目 A、项目 B 分开管理）
+- 跨 agent 委托：A 向 B 发起一个话题，B 接收后在自己的话题里处理
+- 需要给某段对话贴标签、跟踪状态（pending / in_progress / completed / archived）
+- 想保存话题摘要（summary），供下次激活时快速恢复上下文
+- 整理完成或废弃的话题时（删除话题）
+
+主会话（主对话，无 threadId）不能删除。话题是主会话之外额外创建的分支。
+
+## 基础操作
+
+### 列出话题
+
+```bash
+ec thread peers                     # 列出该 agent 有话题的所有对端
+ec thread list <peer>
+ec thread list <peer> --status in_progress
+ec thread list <peer> --label 项目A
+ec thread list <peer> --unlabeled
+ec thread list <peer> --sort recent --limit 20
+ec thread list <peer> --format json
+```
+
+`ec thread list` 必须带 `<peer>` 参数，不带 peer 会报错并提示用 `ec thread peers` 查找对端。每条话题显示消息(24h/总计)统计、最后一条消息截断（50字）和当前摘要（未设置时显示"未总结"）。
+
+### 查看话题详情
+
+```bash
+ec thread show <peer>/<threadId>
+ec thread show current          # 当前任务所在话题
+ec thread show <peer>           # 该对端的主会话
+```
+
+### 读取话题历史消息
+
+```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 msg history --thread <id>`，from/to 会自动从运行时上下文推断：
+
+```bash
+ec msg history --thread <threadId>
+```
+
+`ec thread history` 是推荐用法。
+
+### 新建话题
+
+```bash
+ec thread create <peer> --name "项目A需求讨论"
+ec thread create <peer> --name "项目A" --label 项目A --status in_progress
+```
+
+创建成功后返回 `threadId`，格式为 `thread-<ms>-<seq4>-<rand4>`（如 `thread-1791028341906-0000-136a`）。创建时会自动向对端发一条系统消息通知。
+
+### 修改话题
+
+```bash
+ec thread rename <peer>/<threadId> "新名称"
+ec thread label <peer>/<threadId> 重要
+ec thread label <peer>/<threadId> --clear       # 清除标签
+ec thread status <peer>/<threadId> completed    # pending|in_progress|completed|archived
+```
+
+`/name` 和 `/rename` 也会同步更新话题索引。
+
+### 删除话题
+
+```bash
+ec thread delete <peer>/<threadId>    # 软删除：session 文件移入 _trash/，索引条目删除
+```
+
+删除后话题从索引中消失，`ec thread list` 不再显示。底层 session 文件通过 `unbindSession` 机制移入 `chatDir/_trash/`，与系统其他删除行为一致。不能删除正在处理中（busy）的话题，也不能删除主会话。
+
+删除时会自动取消该话题的所有关联 Trigger，防止 ghost wakeup。
+
+删除后历史仍可通过 `ec thread history <peer>/<threadId>` 读取（直接读 messages.jsonl，不依赖索引）。
+
+## 跨会话发送（话题链核心）
+
+在托管会话中，`ec msg send` 支持 `--thread` 参数直接路由到某个话题：
+
+```bash
+# 完整形式
+ec msg send <from> <to> "消息内容" --thread <threadId>
+
+# 托管会话简化形式（from/to 自动从运行时上下文推断）
+ec msg send "消息内容" --thread <threadId>
+
+# 附带复查 Trigger（跨话题时必填；每 30m 唤醒本端回查）
+ec msg send "消息内容" --thread <threadId> --check-every 30m
+```
+
+注意事项：
+
+- `--thread` 指定的话题必须已存在于本端索引（`ec thread list` 可见），否则返回 `TOPIC_NOT_FOUND`
+- **跨话题发送时 `--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 中的自定义段（默认给出通用的检查/决策指引）
+
+### 跨会话委托的完整流程
+
+**A 委托 B 处理某个任务：**
+
+```bash
+# A 向 B 的话题 T2 发送任务，并设置周期复查
+ec msg send "请处理项目A的数据清洗" --thread thread-T2-xxxx --check-every 2h
+```
+
+**B 接收时感知来源上下文：**
+
+B 的目标话题下次被唤醒时，prompt 开头会注入一条跨会话上下文，格式如下：
+
+```
+‹跨会话上下文 · 来源话题:thread-T1-xxxx · 对端:alice.agentid.cn · 发送于:2026-10-10 10:00›
+⚠️ 来源话题在发送后已有 3 条新消息（10:01 - 10:15）—— 处理前建议先回查该话题的空洞期消息。
+🔔 复查 Trigger:trig_1791765199642_5371c8ff（尚未触发/待处理）
+【原消息内容】
+```
+
+注入只发生一次。之后 B 靠自身上下文记住"我从哪个话题跨过来的"，可随时用
+`ec thread history <来源peer>/<来源话题>` 回查空洞期消息。
+
+## 话题摘要（Summary）
+
+摘要用于跨会话保留话题的核心信息，在下次激活或委托时快速恢复上下文。
+daemon 不自动总结，需要 agent 主动写入。
+
+```bash
+# 查看当前摘要（同时打印 coveredThroughTs 覆盖游标）
+ec thread summary show <peer>/<threadId>
+
+# 写入摘要 —— --name 必填：同时把话题改成这个标题
+ec thread summary set <peer>/<threadId> "项目A需求已确认，正在开发登录模块" --name "项目A登录模块"
+# 不想改话题名就显式传 -
+ec thread summary set <peer>/<threadId> "摘要内容" --name -
+
+# 支持 CAS（乐观锁），防止并发覆盖
+ec thread summary set <peer>/<threadId> "新内容" --name - --if-rev 3
+
+# 查看历史版本
+ec thread summary log <peer>/<threadId>
+
+# 清空当前摘要（历史版本保留）
+ec thread summary clear <peer>/<threadId>
+```
+
+### 覆盖游标与增量总结
+
+`summary set` 会在写入时自动记录 `coveredThroughTs`——**当时该话题最后一条消息的时间戳**，
+表示"这条摘要覆盖到哪"。`summary show` 会把它打印出来。
+
+下次总结时用它作起点，只读增量（不必拍脑袋定 `--limit`）：
+
+```bash
+# 1. 拿覆盖游标
+ec thread summary show <peer>/<threadId>          # 输出中的 coveredThroughTs
+
+# 2. 读游标之后的增量（首次总结无游标时省略 --after，全量读）
+ec thread history <peer>/<threadId> --after <coveredThroughTs> --limit 50
+
+# 3. 增量较多时往回翻页（history 支持 before 逆序分页）
+ec thread history <peer>/<threadId> --before <本页最早一条的ts> --limit 50
+
+# 4. 读完增量后写摘要，游标自动推进到当前最新一条
+ec thread summary set <peer>/<threadId> "新摘要" --name -
+```
+
+**约束**：`summary set` 把游标设为**写入时刻话题的最新一条**，所以跨话题总结必须**先把增量读完再写**——
+没读完就写，游标会越过未读的那段，它们下次不会再被返回。
+
+存储位置：`~/.evolcore/agents/<selfAid>/data/threads/summaries/<sessionId>.summary.jsonl`。
+
+CAS 说明：`--if-rev <n>` 指定当前已知的版本号；若实际版本不匹配，写入失败并返回 `SUMMARY_CAS_CONFLICT`。先用 `show` 拿到当前 rev，再带上 `--if-rev` 写入，可防止并发覆盖。
+
+## 重建索引
+
+话题索引损坏或和 session 文件不同步时，可以重建。
+
+索引与摘要、跨会话收件箱统一收在 `~/.evolcore/agents/<selfAid>/data/threads/` 下：
+
+```
+data/threads/
+├── index.json      话题索引
+├── summaries/      话题摘要（<sessionId>.summary.jsonl）
+└── inbox/          跨会话上下文收件箱
+```
+
+```bash
+ec thread rebuild-index
+ec thread rebuild-index --agent <aid>   # 跨身份操作
+ec thread rebuild-index --check         # 只检查不写盘
+ec thread check-index                   # 同 rebuild-index --check
+```
+
+## 引用格式（\<ref\>）
+
+命令里的 `<ref>` 参数支持三种格式：
+
+| 格式 | 含义 |
+|---|---|
+| `current` | 当前任务所在话题 |
+| `<peer>` | 该对端的主会话 |
+| `<peer>/<threadId>` | 指定话题，如 `bob.agentid.cn/thread-xxx-0001-aaaa` |
+
+## 话题状态值
+
+| 值 | 含义 |
+|---|---|
+| `pending` | 待开始（默认） |
+| `in_progress` | 进行中 |
+| `completed` | 已完成 |
+| `archived` | 已归档 |
+
+## 常见错误码
+
+| 错误码 | 含义 | 处理建议 |
+|---|---|---|
+| `TOPIC_NOT_FOUND` | 话题不存在或 threadId 错误 | 用 `ec thread list <peer>` 确认 threadId |
+| `TOPIC_CONFLICT` | 同名话题已存在 | 改名或用现有话题 |
+| `TOPIC_BUSY` | 话题正在处理中 | 等待处理完成后再删除 |
+| `SUMMARY_CAS_CONFLICT` | 摘要版本冲突 | 重新 `show` 获取最新 rev，再重试 |
+| `INVALID_NAME` | 话题名称不合法 | 名称不能为空，不超过 80 字符 |
+| `NAME_TOO_LONG` | 话题名称超过 80 字符 | 缩短名称 |

package/kits/docs/prompt-loading-architecture.md

@@ -117,6 +117,7 @@
 | 55 | commands | channel≠null | ✓ | 命令集能力卡 |
 | 60 | session | always | ✓ | 会话层 fragment（含 localDate/weekday） |
 | 70 | baseagent | baseAgent≠null | ✓ | base agent 配置 fragment |
+| 80 | managed-runtime-notice | lifecycle=active | ✓ | 托管运行时提示（勿重复读 $KITS_RULES/ 与 CLAUDE.md 指令） |
 
 ### 输出结构
 

package/kits/eck_manifest.json

@@ -45,6 +45,32 @@
       },
       "description": "身份层：我是谁"
     },
+    {
+      "id": "skills-builtin",
+      "type": "file",
+      "file": "$AGENT_DIR/skills/.index-builtin.md",
+      "order": 20.5,
+      "needsInjection": false,
+      "optional": true,
+      "when": {
+        "var": "lifecycle",
+        "eq": "active"
+      },
+      "description": "内置技能索引"
+    },
+    {
+      "id": "skills-local",
+      "type": "file",
+      "file": "$AGENT_DIR/skills/.index-local.md",
+      "order": 20.6,
+      "needsInjection": false,
+      "optional": true,
+      "when": {
+        "var": "lifecycle",
+        "eq": "active"
+      },
+      "description": "本机技能索引"
+    },
     {
       "id": "persona",
       "type": "file",
@@ -85,32 +111,6 @@
       },
       "description": "个人资料（personal.md）"
     },
-    {
-      "id": "skills-builtin",
-      "type": "file",
-      "file": "$AGENT_DIR/skills/.index-builtin.md",
-      "order": 20.5,
-      "needsInjection": false,
-      "optional": true,
-      "when": {
-        "var": "lifecycle",
-        "eq": "active"
-      },
-      "description": "内置技能索引"
-    },
-    {
-      "id": "skills-local",
-      "type": "file",
-      "file": "$AGENT_DIR/skills/.index-local.md",
-      "order": 20.6,
-      "needsInjection": false,
-      "optional": true,
-      "when": {
-        "var": "lifecycle",
-        "eq": "active"
-      },
-      "description": "本机技能索引"
-    },
     {
       "id": "relation-layer",
       "type": "file",
@@ -346,6 +346,29 @@
       },
       "description": "客户端环境文档"
     },
+    {
+      "id": "memory-and-thread",
+      "type": "file",
+      "file": "$KITS_RULES/07-memory-and-thread.md",
+      "order": 46,
+      "needsInjection": false,
+      "when": {
+        "and": [
+          {
+            "var": "chatType",
+            "in": [
+              "private",
+              "group"
+            ]
+          },
+          {
+            "var": "lifecycle",
+            "eq": "active"
+          }
+        ]
+      },
+      "description": "记忆与话题：持久化上下文的两套机制（memory + thread）"
+    },
     {
       "id": "reply-contract",
       "type": "file",
@@ -440,6 +463,18 @@
         ]
       },
       "description": "Base Agent 特定配置"
+    },
+    {
+      "id": "managed-runtime-notice",
+      "type": "file",
+      "file": "$KITS_FRAGMENTS/managed-runtime.md",
+      "order": 80,
+      "needsInjection": true,
+      "when": {
+        "var": "lifecycle",
+        "eq": "active"
+      },
+      "description": "托管运行时提示：上下文已就绪，勿重复读取"
     }
   ]
 }

package/kits/eck_message_manifest.json

@@ -10,7 +10,18 @@
       "modeType": "inject",
       "modeName": "default",
       "isDefault": true,
-      "when": { "and": [ { "var": "isOwnerHint", "eq": true }, { "var": "renderMode_inject", "eq": "default" } ] },
+      "when": {
+        "and": [
+          {
+            "var": "isOwnerHint",
+            "eq": true
+          },
+          {
+            "var": "renderMode_inject",
+            "eq": "default"
+          }
+        ]
+      },
       "description": "观察者插话提示渲染（owner 信封头·default 模式）"
     },
     {
@@ -21,8 +32,23 @@
       "needsInjection": true,
       "modeType": "handoff",
       "modeName": "request_to_target",
-      "when": { "and": [ { "var": "isHandoff", "eq": true }, { "var": "handoffKind", "eq": "request_to_target" }, { "var": "handoffReturnPolicy", "eq": "required" } ] },
-      "description": "msg send 跨会话请求回复上下文渲染"
+      "when": {
+        "and": [
+          {
+            "var": "isHandoff",
+            "eq": true
+          },
+          {
+            "var": "handoffKind",
+            "eq": "request_to_target"
+          },
+          {
+            "var": "handoffReturnPolicy",
+            "eq": "required"
+          }
+        ]
+      },
+      "description": "[DEPRECATED] msg send 跨会话请求回复上下文渲染（handoff 已被 Thread Context 取代，见 docs/thread-chain/handoff-deprecation.md）"
     },
     {
       "id": "msg-handoff-context-to-target",
@@ -32,8 +58,23 @@
       "needsInjection": true,
       "modeType": "handoff",
       "modeName": "request_to_target",
-      "when": { "and": [ { "var": "isHandoff", "eq": true }, { "var": "handoffKind", "eq": "request_to_target" }, { "var": "handoffReturnPolicy", "eq": "none" } ] },
-      "description": "msg send 跨会话单次本地上下文渲染"
+      "when": {
+        "and": [
+          {
+            "var": "isHandoff",
+            "eq": true
+          },
+          {
+            "var": "handoffKind",
+            "eq": "request_to_target"
+          },
+          {
+            "var": "handoffReturnPolicy",
+            "eq": "none"
+          }
+        ]
+      },
+      "description": "[DEPRECATED] msg send 跨会话单次本地上下文渲染（handoff 已被 Thread Context 取代，见 docs/thread-chain/handoff-deprecation.md）"
     },
     {
       "id": "msg-handoff-response-to-origin",
@@ -43,8 +84,80 @@
       "needsInjection": true,
       "modeType": "handoff",
       "modeName": "response_to_origin",
-      "when": { "and": [ { "var": "isHandoff", "eq": true }, { "var": "handoffKind", "eq": "response_to_origin" } ] },
-      "description": "msg send 跨会话结果回流上下文渲染"
+      "when": {
+        "and": [
+          {
+            "var": "isHandoff",
+            "eq": true
+          },
+          {
+            "var": "handoffKind",
+            "eq": "response_to_origin"
+          }
+        ]
+      },
+      "description": "[DEPRECATED] msg send 跨会话结果回流上下文渲染（handoff 已被 Thread Context 取代，见 docs/thread-chain/handoff-deprecation.md）"
+    },
+    {
+      "id": "msg-trigger-thread-check",
+      "type": "file",
+      "file": "$KITS_MESSAGE_FRAGMENTS/trigger-thread-check.md",
+      "order": 5,
+      "needsInjection": true,
+      "modeType": "trigger-thread-check",
+      "modeName": "default",
+      "isDefault": true,
+      "when": {
+        "and": [
+          {
+            "var": "isTriggerMsg",
+            "eq": true
+          },
+          {
+            "var": "triggerMsgKind",
+            "eq": "thread-check"
+          }
+        ]
+      },
+      "description": "跨话题复查 Trigger 专属渲染（kind=thread-check：来源话题 + 目标话题 + 周期）"
+    },
+    {
+      "id": "msg-trigger-session",
+      "type": "file",
+      "file": "$KITS_MESSAGE_FRAGMENTS/trigger-session.md",
+      "order": 6,
+      "needsInjection": true,
+      "modeType": "trigger-session",
+      "modeName": "default",
+      "isDefault": true,
+      "when": {
+        "and": [
+          {
+            "var": "isTriggerMsg",
+            "eq": true
+          },
+          {
+            "var": "triggerMsgKind",
+            "neq": "thread-check"
+          }
+        ]
+      },
+      "description": "Trigger 唤醒消息渲染（trigger 信封头 + 触发时间 + 正文）"
+    },
+    {
+      "id": "msg-thread-context",
+      "type": "file",
+      "file": "$KITS_MESSAGE_FRAGMENTS/thread-context.md",
+      "order": 8,
+      "needsInjection": true,
+      "modeType": "thread-context",
+      "modeName": "default",
+      "isDefault": true,
+      "when": {
+        "var": "isThreadContext",
+        "eq": true
+      },
+      "description": "跨会话上下文注入（来源话题 + 空洞提示 + 复查 Trigger）"
     },
     {
       "id": "msg-private-default",
@@ -55,7 +168,30 @@
       "modeType": "private",
       "modeName": "default",
       "isDefault": true,
-      "when": { "and": [ { "var": "isOwnerHint", "neq": true }, { "var": "chatType", "neq": "group" }, { "var": "renderMode_private", "eq": "default" } ] },
+      "when": {
+        "and": [
+          {
+            "var": "isOwnerHint",
+            "neq": true
+          },
+          {
+            "var": "isThreadContext",
+            "neq": true
+          },
+          {
+            "var": "isTriggerMsg",
+            "neq": true
+          },
+          {
+            "var": "chatType",
+            "neq": "group"
+          },
+          {
+            "var": "renderMode_private",
+            "eq": "default"
+          }
+        ]
+      },
       "description": "对端私聊消息渲染（default 模式；chatType 非 group 的非插话消息，含 handoff/coding/null 兜底）"
     },
     {
@@ -67,8 +203,31 @@
       "modeType": "group",
       "modeName": "default",
       "isDefault": true,
-      "when": { "and": [ { "var": "isOwnerHint", "neq": true }, { "var": "chatType", "eq": "group" }, { "var": "renderMode_group", "eq": "default" } ] },
+      "when": {
+        "and": [
+          {
+            "var": "isOwnerHint",
+            "neq": true
+          },
+          {
+            "var": "isThreadContext",
+            "neq": true
+          },
+          {
+            "var": "isTriggerMsg",
+            "neq": true
+          },
+          {
+            "var": "chatType",
+            "eq": "group"
+          },
+          {
+            "var": "renderMode_group",
+            "eq": "default"
+          }
+        ]
+      },
       "description": "群聊消息渲染（default 模式）"
     }
   ]
-}
+}

package/kits/rules/05-venue.md

@@ -29,7 +29,7 @@
 
 | 位置 | 内容 |
 |------|------|
-| `$KITS_DOCS/venues/` | 环境层场景文档（只读，按需加载）：`private.md` `group.md` `<channel>-<chatType>.md` `client-*.md` |
+| `$KITS_DOCS/venues/` | 环境层场景文档（只读，按需加载）：`private.md` `<channel>-<chatType>.md` `client-*.md`。群聊场景的完整指引已抽离为内置技能 `ec-group`，不再有 `venues/group.md` |
 | `$VENUES_DIR`（`$AGENT_DIR/venues/`） | **目前是死目录**：会被创建（含 `_index/` `_trash/`），但源码里 `agentVenuesDir()` 零调用点，无人读写 |
 
 > `venues/` 下若有 `aun#<group-aid>` 之类的实例目录，是已删除模块 `group-venue-sync.ts` 的历史残留，