evolcore 0.0.3 → 0.0.5

package/dist/utils/process-introspect.js

@@ -8,8 +8,25 @@
  */
 import fs from 'fs';
 import { spawnSync } from 'child_process';
-import { isWindows } from './cross-platform.js';
+const isWindows = process.platform === 'win32';
 const isMacOS = process.platform === 'darwin';
+function readLinuxClockTicks() {
+    if (process.platform !== 'linux')
+        return 100;
+    try {
+        const result = spawnSync('getconf', ['CLK_TCK'], {
+            encoding: 'utf-8',
+            timeout: 1000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const value = Number.parseInt(result.stdout?.trim() || '', 10);
+        return value > 0 ? value : 100;
+    }
+    catch {
+        return 100;
+    }
+}
+const linuxClockTicks = readLinuxClockTicks();
 /** 容差：2 秒（覆盖 macOS 秒级精度 + 时钟漂移） */
 export const START_TIME_TOLERANCE_MS = 2000;
 /**
@@ -72,8 +89,7 @@ function getStartTimeLinux(pid) {
     }
     if (isNaN(btimeSec))
         return null;
-    const clkTck = 100;
-    return (btimeSec + starttimeJiffies / clkTck) * 1000;
+    return (btimeSec + starttimeJiffies / linuxClockTicks) * 1000;
 }
 // ── macOS ──
 function getStartTimeMacOS(pid) {

package/dist/utils/stable-semver.js

@@ -0,0 +1,21 @@
+const STABLE_SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+export function parseStableSemver(value) {
+    if (typeof value !== 'string')
+        return null;
+    const match = STABLE_SEMVER.exec(value);
+    if (!match)
+        return null;
+    const parsed = [Number(match[1]), Number(match[2]), Number(match[3])];
+    if (parsed.some(part => !Number.isSafeInteger(part)))
+        return null;
+    return parsed;
+}
+export function compareStableSemver(left, right) {
+    for (let index = 0; index < 3; index += 1) {
+        if (left[index] < right[index])
+            return -1;
+        if (left[index] > right[index])
+            return 1;
+    }
+    return 0;
+}

package/dist/utils/stats.js

@@ -1,3 +1,4 @@
+import { formatPeerKey } from '../core/relation/peer-identity.js';
 export class StatsCollector {
     events = [];
     recentErrors = [];
@@ -136,6 +137,7 @@ export class StatsCollector {
 }
 export class AidStatsCollector {
     entries = new Map();
+    routePeers = new Map();
     queueStatsProvider;
     /** sessionId → 当前正在跑该 session 的 agent，task:started 写入，task:completed/error 清除 */
     sessionToAgent = new Map();
@@ -233,10 +235,12 @@ export class AidStatsCollector {
                 lastReceivedFrom: null,
                 lastReceivedEncrypt: null,
                 lastReceivedChatmode: null,
+                lastReceivedChannel: null,
                 lastSentText: null,
                 lastSentTo: null,
                 lastSentEncrypt: null,
                 lastSentChatmode: null,
+                lastSentChannel: null,
                 lastReceivedKind: null,
                 lastSentKind: null,
                 uniquePeers: new Set(),
@@ -256,6 +260,9 @@ export class AidStatsCollector {
         }
         return entry;
     }
+    routePeerKey(aid, channel, routeId) {
+        return `${aid}\u001f${channel}\u001f${routeId}`;
+    }
     onTaskStart(aid, encrypt, chatmode) {
         const entry = this.getOrCreate(aid);
         entry.currentTaskStartAt = Date.now();
@@ -298,25 +305,31 @@ export class AidStatsCollector {
         const entry = this.getOrCreate(aid);
         entry.selfName = name;
     }
-    recordInbound(aid, fromPeer, byteLength, text, isSystem = false, encrypt, chatmode, kind = 'send') {
+    recordInbound(aid, fromPeer, byteLength, text, isSystem = false, encrypt, chatmode, kind = 'send', ctx) {
         const entry = this.getOrCreate(aid);
+        const channel = ctx?.channelType || 'aun';
+        const peerLabel = ctx?.peerLabel || fromPeer;
+        if (ctx?.routeId && fromPeer) {
+            this.routePeers.set(this.routePeerKey(aid, channel, ctx.routeId), { peerId: fromPeer, peerLabel });
+        }
         if (isSystem) {
             entry.systemReceived++;
         }
         else {
             entry.messagesReceived++;
             entry.lastReceivedAt = Date.now();
-            entry.lastReceivedFrom = fromPeer;
+            entry.lastReceivedFrom = peerLabel;
             if (text)
                 entry.lastReceivedText = text.length > 100 ? text.slice(0, 100) + '…' : text;
             if (encrypt != null)
                 entry.lastReceivedEncrypt = encrypt;
             if (chatmode)
                 entry.lastReceivedChatmode = chatmode;
+            entry.lastReceivedChannel = channel;
             entry.lastReceivedKind = kind;
             // ring buffer：最近 10 轮
             if (text) {
-                entry.recentMessages.unshift({ dir: 'in', peer: fromPeer, text: text.slice(0, 100), ts: Date.now(), kind, encrypt: encrypt ?? null, chatmode: chatmode ?? null });
+                entry.recentMessages.unshift({ dir: 'in', peer: peerLabel, text: text.slice(0, 100), ts: Date.now(), kind, encrypt: encrypt ?? null, chatmode: chatmode ?? null, channel });
                 if (entry.recentMessages.length > 10)
                     entry.recentMessages.pop();
             }
@@ -325,30 +338,39 @@ export class AidStatsCollector {
         entry.uniquePeers.add(fromPeer);
         // 持久化
         this.onMessage?.({
-            ts: Date.now(), agent_aid: aid, peer_key: `aun#${fromPeer}`,
+            ts: Date.now(), agent_aid: aid, peer_key: formatPeerKey(channel, fromPeer),
             direction: 'in', msg_type: isSystem ? 'system' : 'private',
             bytes: byteLength, encrypted: encrypt, chatmode,
         });
     }
-    recordOutbound(aid, toPeer, byteLength, text, isSystem = false, encrypt, chatmode, kind = 'send') {
+    recordOutbound(aid, toPeer, byteLength, text, isSystem = false, encrypt, chatmode, kind = 'send', ctx) {
         const entry = this.getOrCreate(aid);
+        const channel = ctx?.channelType || 'aun';
+        const routePeer = ctx?.routeId
+            ? this.routePeers.get(this.routePeerKey(aid, channel, ctx.routeId))
+            : undefined;
+        const stablePeer = routePeer?.peerId || toPeer;
+        const peerLabel = ctx?.peerLabel && ctx.peerLabel !== toPeer
+            ? ctx.peerLabel
+            : routePeer?.peerLabel || ctx?.peerLabel || toPeer;
         if (isSystem) {
             entry.systemSent++;
         }
         else {
             entry.messagesSent++;
             entry.lastSentAt = Date.now();
-            entry.lastSentTo = toPeer;
+            entry.lastSentTo = peerLabel;
             if (text)
                 entry.lastSentText = text.length > 100 ? text.slice(0, 100) + '…' : text;
             if (encrypt != null)
                 entry.lastSentEncrypt = encrypt;
             if (chatmode)
                 entry.lastSentChatmode = chatmode;
+            entry.lastSentChannel = channel;
             entry.lastSentKind = kind;
             // ring buffer：最近 10 轮
             if (text) {
-                entry.recentMessages.unshift({ dir: 'out', peer: toPeer, text: text.slice(0, 100), ts: Date.now(), kind, encrypt: encrypt ?? null, chatmode: chatmode ?? null });
+                entry.recentMessages.unshift({ dir: 'out', peer: peerLabel, text: text.slice(0, 100), ts: Date.now(), kind, encrypt: encrypt ?? null, chatmode: chatmode ?? null, channel });
                 if (entry.recentMessages.length > 10)
                     entry.recentMessages.pop();
             }
@@ -362,10 +384,10 @@ export class AidStatsCollector {
             }
         }
         entry.bytesSent += byteLength;
-        entry.uniquePeers.add(toPeer);
+        entry.uniquePeers.add(stablePeer);
         // 持久化
         this.onMessage?.({
-            ts: Date.now(), agent_aid: aid, peer_key: `aun#${toPeer}`,
+            ts: Date.now(), agent_aid: aid, peer_key: formatPeerKey(channel, stablePeer),
             direction: 'out', msg_type: isSystem ? 'system' : 'private',
             bytes: byteLength, encrypted: encrypt, chatmode,
         });
@@ -391,10 +413,12 @@ export class AidStatsCollector {
                 lastReceivedFrom: entry.lastReceivedFrom,
                 lastReceivedEncrypt: entry.lastReceivedEncrypt,
                 lastReceivedChatmode: entry.lastReceivedChatmode,
+                lastReceivedChannel: entry.lastReceivedChannel,
                 lastSentText: entry.lastSentText,
                 lastSentTo: entry.lastSentTo,
                 lastSentEncrypt: entry.lastSentEncrypt,
                 lastSentChatmode: entry.lastSentChatmode,
+                lastSentChannel: entry.lastSentChannel,
                 lastReceivedKind: entry.lastReceivedKind,
                 lastSentKind: entry.lastSentKind,
                 uniquePeerCount: entry.uniquePeers.size,

package/kits/docs/channels/aun.md

@@ -35,19 +35,10 @@ AUN 渠道是**隐式**的——它不写在 `channels[]` 数组里，而是从
 
 > `owners`/`admins` 用 **AID**，不是渠道原生 ID。
 
-### 进程级配置（`$EVOLCORE_HOME/config.json`）
+### AUN keystore seed
 
-E2EE 加密种子是**进程级**的，所有 agent 共享，不在 agent config 里：
-
-```json
-{
-  "aun": {
-    "encryptionSeed": "<seed>"
-  }
-}
-```
-
-留空时 SDK 依次回退 `AUN_ENCRYPTION_SEED` 环境变量 → 默认 `'evol'`。
+AUN keystore seed 由 EvolCore 使用固定应用值管理，不再提供配置项或环境变量入口。
+检测到历史自定义值时 daemon 会拒绝启动并提示联系管理人员，避免用错误值加载现有身份。
 
 > Gateway 不在配置里手填：连接时从 AID 自动发现（见下）。Keystore 默认落在 `$EVOLCORE_HOME`。
 
@@ -58,7 +49,7 @@ E2EE 加密种子是**进程级**的，所有 agent 共享，不在 agent config
 - **身份与信任**：每条入站消息携带发送者 AID，经四级 X.509 证书链（Root CA → Registry CA → Issuer CA → Agent）验签。
 - **agent.md 缓存**：对端名片 `https://<aid>/agent.md` 由 **AUN SDK 自动拉取并缓存**（`AgentMdManager`，带 ETag/TTL，默认 1 天内不重复探测）。缓存落在 **`$EVOLCORE_HOME/AIDs/<aid>/`**，每个 AID 两个文件：`agent.md`（带签名正文）+ `agentmd.json`（元数据：etag/last_modified/checked_at/verify_status）。本端与对端的 agent.md 都缓存于此。
   - 关系层另存一份**派生**的精简身份 `relations/<peerKey>/peer-identity.json`（type/isAgent/name），由 evolcore 从 agent.md 提取，不是 agent.md 本体。
-- **E2EE 加密**：可选端到端加密，回复默认跟随对端消息加密状态（密文回密文，明文回明文）；种子由进程级 `aun.encryptionSeed` 提供。
+- **E2EE 加密**：可选端到端加密，回复默认跟随对端消息加密状态（密文回密文，明文回明文）；keystore seed 由 EvolCore 固定管理。
 - **断线重连**：SDK 内置退避策略自动重连。实时连接状态用 `ec watch aid` 查看（`ec aid` 是身份/证书管理，不显示连接状态）。
 - **群 ID 格式**：当前协议规范使用 `g-{slug}.issuer-domain` canonical 形式，输入也可接受本域简写 `g-{slug}` 或兼容形式 `g-{slug}@issuer-domain`。历史会话里可能仍出现 `group.{issuer}/{group_no}` 一类旧格式，运行时需兼容读取。
 - **群分发模式**：`dispatch_mode=broadcast|mention` 是群级配置，只决定哪些群消息进入 Agent LLM 上下文，不影响 AUN 协议层投递；被过滤消息仍应本地存档。

package/kits/docs/evolcore/INDEX.md

@@ -35,7 +35,7 @@
 | `ec fs` | AUN 文件系统统一入口 | 上传/下载/看文件/列目录/删文件/配额/群空间 | 任意有渠道场景 | `fs.md` |
 | `ec storage` | 文件存储底层调试入口 | storage 调试/旧命令/底层上传下载 | 任意有渠道场景 | `storage.md` |
 | `ec agent` | EvolAgent 生命周期 | 创建/启停/热重载/改配置 | 管理员（owner/admin） | `agent.md` |
-| `ec contact` | Contact Book 与访问控制 | 拉黑/解除拉黑/查拉黑 | Agent owner/admin | `contact.md` |
+| `ec contact` | Contact Book 与访问控制 | 拉黑/解除拉黑/查拉黑 | 读 owner/admin；写仅 owner | `contact.md` |
 | `ec rpc` | 底层 AUN RPC（逃生通道） | 直接调协议方法 | 高级/兜底 | `rpc.md` |
 
 ## 会话自管理类（不连 AUN，操作当前会话）

package/kits/docs/evolcore/config.md

@@ -3,7 +3,7 @@
 按作用域读写所有配置参数 + 配置快照/回滚/启动历史。触发词：看配置/改配置/查字段/列配置/校验配置/快照/回滚/历史/对比版本/启动记录。
 
 > `ec config` 是配置读写的统一 CLI 入口；模型交互由 menu 协议和 slash `/model` 提供。
-> 字段按 owner 路由：H 字段写 daemon/defaults/config，HA 行为字段写行为配置。
+> 字段由共享 field policy 决定路由、值类型和访问级别；同一套规则用于 CLI、Menu 和 agent-tool。
 
 ## 参数读写
 
@@ -114,7 +114,8 @@ ec config schema <name> [version]
 | `--process` | 进程级 | `~/.evolcore/daemon.json` |
 | 写操作三者全无 | — | **拒绝**（防误写全局） |
 
-`--peer` 取 `channelType#channelId` 或裸 aid（裸 aid 视为 `aun#<aid>`）。改某作用域后，对应范围所有会话的下一条消息即时生效。
+`--peer` 取 `channelType#channelId` 或裸 aid（裸 aid 视为 `aun#<aid>`）。配置提交后开始处理的新
+turn 使用新值；提交前已经开始的 turn 不被打断。
 
 ## 覆盖链
 
@@ -124,6 +125,49 @@ defaults → agent/config → relation/config
 
 ConfigManager 只合并上述物理层并返回物理来源。角色策略不进入配置合并链：`permissionMode` 和 `baseagents.*.model` 由消费方按当前角色单独应用。
 
+### Agent 消息准入策略
+
+消息准入策略保存在 `agents/<aid>/config.json` 的 `access` 字段，但它是 Agent 自身的安全边界，
+不参与 defaults/relation 有效覆盖：
+
+```json
+{
+  "access": {
+    "policyMode": "contacts",
+    "requestLimit": { "maxTimes": 600, "coolDown": 3600 }
+  }
+}
+```
+
+`policyMode` 为 `open | contacts | owners`；`open` 对所有已配置渠道的私聊和群聊入站开放，`contacts`
+将 Agent 已加入并接收到的群聊视为授权，`owners` 仅 Owner 消息开放；群聊成员不按 Contact Book 联系人
+状态逐一过滤。`requestLimit` 只限制准入控制消息的自动回复、申请和绑定码提示，不是渠道准入开关；`coolDown`
+单位为秒。该对象由 Connect 的访问设置入口修改，不通过通用 relation/defaults 覆盖链放宽。
+
+### AUN 群规则加载策略
+
+`groupRules.mode` 可设为 `load` 或 `ignore`，缺省为 `load`。该字段仅存在于 Agent 和 relation
+层，relation 可覆盖 Agent 默认值，`--default` 不支持。
+
+```bash
+# Agent 默认值
+ec config set groupRules.mode ignore --self bot.agentid.pub
+
+# 当前群覆盖
+ec config set groupRules.mode load \
+  --self bot.agentid.pub --peer aun#g-team.agentid.pub
+
+# 查看有效值和来源 / 删除群覆盖
+ec config get groupRules.mode \
+  --self bot.agentid.pub --peer aun#g-team.agentid.pub --format json
+ec config unset groupRules.mode \
+  --self bot.agentid.pub --peer aun#g-team.agentid.pub
+```
+
+`ignore` 表示运行时不访问远端群规则、不读本地物化文件、不注入规则正文，但不删除缓存，也不影响
+`ec group rules` 的远端管理命令。配置切换不会自动创建或清空会话。Claude/Codex 从后续新 turn
+按当前值重新组装上下文；其他 runner 的 Menu 写入结果会提示新建或清空群会话后生效。
+
 ## 权限控制
 
 **写权限**（API 层判定）：
@@ -131,6 +175,7 @@ ConfigManager 只合并上述物理层并返回物理来源。角色策略不进
 - **角色专用入口**：`roles/index.json` 与 `roles/{roleId}.json` 由角色服务维护；relation 的
   `role` 由角色分配服务维护；`permissionMode` 仅在角色策略中维护
 - **兼容字段**：`enable_rich_content` 仍可读取旧值，但已废弃且不再产生运行时效果
+- **群规则策略**：`groupRules.mode` 仅 Agent owner 或 daemon owner 可 set/unset；其他角色可读取当前 relation 的有效值
 - **仅人可写**：channels / owners / admins / 凭证 / aid / enabled / projects / aun / models.allowed
 - Agent 托管环境写仅人字段被拒
 

package/kits/docs/evolcore/contact.md

@@ -1,6 +1,7 @@
 # ec contact — Agent 联系人与访问控制
 
-`ec contact` 管理指定 Agent 的 Contact Book v2。它只接受 AUN AID 主键，并只负责 AUN 私聊拉黑状态；角色统一由 relation `config.json role` 管理。
+`ec contact` 管理指定 Agent 的 Contact Book v3。它只接受 AUN AID 主键；拉黑的是该 canonical AID，
+因此会拒绝它在 AUN 以及所有已绑定外部渠道中的私聊入站。角色统一由 relation `config.json role` 管理。
 
 ## 命令
 
@@ -15,6 +16,8 @@ ec contact list --blocked --self <agent-aid>
 ## 约束
 
 - `<aid>` 和 `--self` 必须是合法 AID。
+- 写入 Agent Owner 时，系统会自动创建该 Owner 的 active 联系人记录。
+- `block/unblock` 只接受已存在的联系人；不存在时返回 `NOT_FOUND`。
 - `block/unblock` 只改变本 Agent 的入站接收策略，不代表对端也拉黑了本 Agent。
 - Agent owner 不能被拉黑。
 - `list --blocked` 只列出当前 blocked contact，并返回 `contactRevision`。
@@ -28,7 +31,7 @@ ec contact list --blocked --self <agent-aid>
 | 操作 | owner | admin | 普通角色 |
 |---|---:|---:|---:|
 | `list --blocked` | 允许 | 允许 | 拒绝 |
-| `block` / `unblock` | 允许 | 允许 | 拒绝 |
+| `block` / `unblock` | 允许 | 拒绝 | 拒绝 |
 
 缺少、伪造、撤销或跨会话 delegation token 时失败关闭。托管调用的 `--self` 必须等于当前任务所属 Agent。
 
@@ -52,6 +55,8 @@ ec contact list --blocked --self <agent-aid>
 
 ## 拉黑后的消息行为
 
-- AUN 外部入站在 MessageBridge 的业务入口被拦截，不进入 menu/auth/command/session/queue/LLM。
+- AUN 和已绑定外部私聊身份的入站在 MessageBridge 业务入口被拦截，不进入 menu/auth/command/session/queue/LLM。
+- 群聊不按成员的联系人状态过滤；`open` 对所有已配置渠道的群聊入站开放，`contacts` 将 Agent 已加入并
+  接收到的群聊视为授权，`owners` 仅 Owner 消息开放。
 - 对 `ai`、`bot`、`agent`、`service` 类型的私聊对端，可限频返回 `[rejection] Not accepting messages from you.`。
 - 入站正文中的 `[rejection]` 没有协议控制语义。发送者未被本 Agent 拉黑时，该文本正常进入响应式会话。

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

@@ -1,6 +1,6 @@
 # ec group rules — 群规则文件
 
-管理 AUN 群空间中的 `/rules.md`。群规则文件用于定义本群特有的工作流程、职责分工、交付格式、限制条件和升级路径；发布后，EvolCore 会在该群的对话上下文中自动加载。
+管理 AUN 群空间中的 `/rules.md`。群规则文件用于定义本群特有的工作流程、职责分工、交付格式、限制条件和升级路径；发布后，EvolCore 默认会在该群的对话上下文中加载，本地 Agent 也可用 `groupRules.mode` 选择忽略。
 
 以自己的 AID 为操作者 `<from>`，群 AID 为 `<group-id>`。
 
@@ -30,6 +30,44 @@ ec group rules <from> <group-id> publish
 
 所有命令均支持 `--format json`。
 
+## 本地加载策略
+
+`ec group rules get/set/publish` 管理远端群规则；`groupRules.mode` 管理当前 Agent 是否把远端规则
+读取并注入上下文。两者互不替代。策略支持 Agent 默认值和当前群 relation 覆盖，优先级为：
+
+```text
+Agent groupRules.mode -> 当前群 relation groupRules.mode -> 缺省 load
+```
+
+```bash
+# 当前群的有效策略与来源
+ec config get groupRules.mode \
+  --self bot.agentid.pub --peer aun#g-team.agentid.pub --format json
+
+# 只忽略当前群；重新设为 load 可恢复
+ec config set groupRules.mode ignore \
+  --self bot.agentid.pub --peer aun#g-team.agentid.pub
+ec config set groupRules.mode load \
+  --self bot.agentid.pub --peer aun#g-team.agentid.pub
+
+# 删除当前群覆盖，回落 Agent 默认值或缺省 load
+ec config unset groupRules.mode \
+  --self bot.agentid.pub --peer aun#g-team.agentid.pub
+
+# 设置 Agent 默认策略；只能从允许 Agent 级写入的私聊或控制面执行
+ec config set groupRules.mode ignore --self bot.agentid.pub
+```
+
+`groupRules.mode` 只能由 Agent owner 或 daemon owner 修改，其他角色仍可读取当前 relation 的有效值。
+在群聊中，即使 owner 也只能修改当前群 relation，不能修改 Agent 默认值。命令沿用既有
+`ec config set/unset` 的授权、selector 和输出语义，不新增 Menu 协议。
+
+`ignore` 从配置提交后开始处理的新 turn 生效，并保证不访问远端规则、不读取本地
+`rules.md`、不注入规则正文；旧物化文件会保留，但不能作为回退来源。切回 `load` 后仍须重新完成
+远端元数据校验。配置切换不会清空、新建或 fork 会话，也不会删除已进入恢复会话历史的旧内容。
+Claude/Codex 的后续 turn 会按新策略重新组装上下文；其他 runner 仍保存配置，但 Menu 成功输出会
+提示新建或清空该群会话后生效。
+
 ## 推荐流程
 
 日常更新直接使用 `set`：
@@ -160,6 +198,7 @@ ec group rules bot.agentid.pub g-team.agentid.pub get --format json
 | status | 含义 | 是否加载 |
 |--------|------|----------|
 | `ok` | `get/set/publish` 校验或发布成功 | 是 |
+| `ignored` | 当前 Agent 的 `groupRules.mode=ignore`，本轮未访问远端或本地规则 | 否 |
 | `synced` | 运行时已刷新并物化本地规则 | 是 |
 | `cached` | 本地物化文件仍与已发布元信息一致 | 是 |
 | `missing` | 未发布规则，或 `/rules.md` 不存在 | 否 |
@@ -181,16 +220,19 @@ ec group rules bot.agentid.pub g-team.agentid.pub get --format json
 校验成功后，本地物化为：
 
 ```text
-$VENUES_DIR/<channel>#<urlEncode(groupId)>/rules.md
+$RELATIONS_DIR/<channel>#<urlEncode(groupId)>/rules.md
 ```
 
 AUN 示例：
 
 ```text
-$AGENT_DIR/venues/aun#g-team.agentid.pub/rules.md
+$AGENT_DIR/relations/aun#g-team.agentid.pub/rules.md
 ```
 
-该本地文件属于群环境层，而不是关系层。它只是远端规则的物化副本，不应直接编辑。只有当前处理轮次验证通过并设置 `groupRulesPath` 时，ECK manifest 才会把它注入 system context。
+该本地文件属于**关系层**（群是对端的一种，见 `kits/rules/04-relation.md`），落在
+`agentRelationsDir(selfAid)/<peerKey>/rules.md`（`src/eck/group-rules-sync.ts` 的 `relationPaths`）。
+`$VENUES_DIR` 下的同名文件是已删除模块 `group-venue-sync.ts` 的历史残留，不再有效。
+它只是远端规则的物化副本，不应直接编辑。只有当前处理轮次验证通过并设置 `groupRulesPath` 时，ECK manifest 才会把它注入 system context。
 
 ## 排障
 

package/kits/docs/evolcore/group.md

@@ -10,13 +10,13 @@
 
 ```bash
 # 文本（含空格/换行/特殊字符时用引号包起来；纯短词可不包，但多空格会被压成一个）
-ec group send <from> <group-id> "<text>" [--encrypt]
+ec group send <from> <group-id> "<text>" --return none|required [--encrypt]
 
 # 文件（--as image|video|voice|file）
-ec group send <from> <group-id> --file <path> [--as <type>] [--text "<说明>"]
+ec group send <from> <group-id> --file <path> --return none|required [--as <type>] [--text "<说明>"]
 
 # 自定义 payload
-ec group send <from> <group-id> --payload '<json>'
+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>]
@@ -42,7 +42,7 @@ ec group send <from> <group-id> "通知" --mention alice.agentid.pub,bob.agentid
 
 - `--no-encrypt`：强制明文，优先于 `--encrypt`
 - `--thread <id>`：指定话题 ID
-- `--return <required|none>`：跨会话回流策略
+- `--return <none|required>`：跨会话发送必填；Trigger 任务只能使用 `none`
 - `--content-type <mime>`：覆盖文件 MIME
 - `--transcript <text>`：语音转写，仅 `--as voice`
 

package/kits/docs/evolcore/msg.md

@@ -8,16 +8,16 @@
 
 ```bash
 # 文本（明文）
-ec msg send <from> <to> "<text>"
+ec msg send <from> <to> "<text>" --return none|required
 
 # 从文件读取文本内容（用于超长消息或避免 Shell 转义）
-ec msg send <from> <to> --text-from-file <path>
+ec msg send <from> <to> --text-from-file <path> --return none|required
 
 # 文本（密文 E2EE）
-ec msg send <from> <to> "<text>" --encrypt
+ec msg send <from> <to> "<text>" --encrypt --return none|required
 
 # 强制明文（同时出现时优先于 --encrypt）
-ec msg send <from> <to> "<text>" --no-encrypt
+ec msg send <from> <to> "<text>" --no-encrypt --return none|required
 
 # 文件：--as 可选 image|video|voice|file（默认按扩展名推断）
 ec msg send <from> <to> --file <path> [--as <type>]
@@ -34,7 +34,7 @@ ec msg send <from> <to> --payload '<json>'
 - `--encrypt` — 端到端加密
 - `--no-encrypt` — 强制明文发送，优先于 `--encrypt`
 - `--thread <id>` — 指定话题 ID（多话题路由）
-- `--return <required|none>` — 跨会话回流策略；跨会话默认 `required`
+- `--return <none|required>` — 跨会话发送必填；`none` 仅补充目标上下文，`required` 将回答回流来源。Trigger 任务只能使用 `none`
 - `--content-type <mime>` — 显式覆盖 MIME（仅 `--file`）
 - `--text <说>` — 附件说明文字（仅 `--file`）
 - `--transcript <text>` — 语音转写（仅 `--as voice`）

package/kits/docs/evolcore/trigger.md

@@ -58,7 +58,23 @@ ec trigger create \
   --enable
 ```
 
-CLI flag 模式必须显式指定 `--target-channel` 和 `--target-channel-id`，并生成 `feedback.strategy=target`。需要 `origin` 或 `silent` feedback 时，用 `/trigger` 或 `--file` 导入 Trigger V3 第二阶段 JSON。
+CLI flag 模式必须显式指定 `--exec`、`--target-channel` 和 `--target-channel-id`，并生成 `feedback.strategy=target`。需要 `origin` 或 `silent` feedback 时，用 `/trigger` 或 `--exec <type> --file <trigger.json|trigger-dir>` 导入 Trigger V3 第二阶段 JSON；CLI 会校验 `--exec` 与 JSON 的 `execution.type` 一致。
+
+多行或复杂 prompt 使用 `--prompt-file <path>`，文件内容会原样作为 prompt（UTF-8 BOM 会移除）。内联 `--prompt` 最多 4096 个字符；超限时 CLI 会提示改用 `--prompt-file <path>`：
+
+```bash
+ec trigger create --cron '0 9 * * *' \
+  --exec target-session \
+  --prompt-file ./prompts/daily-summary.md \
+  --target-channel <channelKey> --target-channel-id <channelId> \
+  --name daily-summary --enable
+
+ec trigger update <triggerId> --prompt-file ./prompts/daily-summary-v2.md
+```
+
+`--file` 始终表示导入完整的 `trigger.json` 或 trigger 目录；`--prompt-file` 只表示 prompt 正文。所有 `create` 形式都必须显式指定 `--exec`；`--prompt-file` 与 `--prompt` 互斥，且不能和 `--file` 同时使用。
+
+模型通过 Bash 调用 CLI 且用双引号传递 `--prompt` 时，正文中的双引号、反引号和 Shell 变量形式的 `$` 需要分别写成 `\"`、反斜杠+反引号、`\$`。Shell 会在启动 `ec` 时去掉保护反斜杠，Trigger 中保存的仍是原始正文。
 
 支持的触发来源：
 
@@ -85,9 +101,9 @@ Trigger V3 第二阶段使用 `execution.type` 区分执行位置：
 --exec target-session
 ```
 
-`target-session` 是默认值：把 `--prompt` 当作一条 trigger 来源消息投递进目标会话队列，并等待该会话处理完成。
+`target-session` 把 `--prompt` 或 `--prompt-file` 的内容当作一条 trigger 来源消息投递进目标会话队列，并等待该会话处理完成。创建时必须显式指定 `--exec target-session`，不会再隐式选择该类型。
 
-`trigger-session` 在 daemon 内部 trigger 会话执行 prompt，再把最终结果按 feedback 投递：
+`trigger-session` 在 daemon 内部 trigger 会话执行 prompt，再把最终结果按 feedback 投递；prompt 可来自 `--prompt` 或 `--prompt-file`：
 
 ```bash
 --exec trigger-session \
@@ -107,7 +123,7 @@ Trigger V3 第二阶段使用 `execution.type` 区分执行位置：
 --script-args '{"scope":"daily"}'
 ```
 
-`script` 不使用 `--prompt`。脚本路径必须在 trigger 目录内；通过 `--file` 导入目录时，脚本文件会随 definition 一起上传。
+`script` 不使用 `--prompt` 或 `--prompt-file`；它必须使用 `--script-path` 和 `--script-runtime`。脚本路径必须在 trigger 目录内；通过 `--file` 导入目录时，脚本文件会随 definition 一起上传。已有 script trigger 的 `update --prompt-file` 也会被拒绝。
 
 ## 目标与反馈
 
@@ -205,18 +221,19 @@ ec trigger rm <triggerId>       # delete 的兼容别名
 
 ## 局部更新
 
-`update` 是 patch 语义，只提交需要修改的字段；未指定字段（包括长 prompt）保持不变。不接受 `--file` 或完整 definition：
+`update` 是 patch 语义，只提交需要修改的字段；未指定字段（包括长 prompt）保持不变。`--prompt-file <path>` 只更新非 script trigger 的 prompt，不接受完整 definition：
 
 ```bash
 ec trigger update <triggerId> --cron '0 10 * * *'
 ec trigger update <triggerId> --prompt '新的任务内容' --name new-name
+ec trigger update <triggerId> --prompt-file ./prompts/new-task.md
 ec trigger update <triggerId> --cron '0 10 * * *' --if-revision 'sha256:...'
 ```
 
 可更新参数只保留三组常用字段：
 
 - 调度：`--once`、`--delay`、`--at`、`--cron`、`--every`、`--event`、`--tz`
-- 内容：`--prompt`、`--name`
+- 内容：`--prompt` 或 `--prompt-file <path>`、`--name`
 - 执行配置：`--model`、`--effort`、`--permission`
 - 运行边界：`--max-runs`、`--max-duration`、`--concurrency`、`--missed-policy`
 
@@ -257,8 +274,8 @@ logs/trigger-runs.log
 复杂 trigger 使用 Trigger V3 第二阶段 JSON：
 
 ```bash
-ec trigger create --file ./trigger.json --enable
-ec trigger create --file ./trigger-dir --enable
+ec trigger create --exec target-session --file ./trigger.json --enable
+ec trigger create --exec script --file ./trigger-dir --enable
 ```
 
 当前产品版本是 Trigger V3 第二阶段；其持久化定义版本为 `$schema_version: 3.1`。旧 `$schema_version: 4` 文件加载时会自动规范化为 `3.1`。