evolclaw 3.1.6 → 3.1.8

package/dist/core/message/message-queue.js

@@ -184,7 +184,8 @@ export class MessageQueue {
     }
     /**
      * 合并多条同 peerId 消息：
-     * - content: \n 连接
+     * - content: \n 连接（兜底用，渲染层优先用 items）
+     * - items: 保留每条子消息（含各自 peer/timestamp），供消息渲染层逐条渲染
      * - images / mentions: 扁平合并
      * - messageId: 取最新一条的 messageId（用于 thought 锚定与中断追踪）
      * - replyContext / peerName / 其余字段: 取最后一条
@@ -193,6 +194,7 @@ export class MessageQueue {
         const contents = [];
         const allImages = [];
         const allMentions = [];
+        const subMessages = [];
         for (const item of items) {
             const m = item.message;
             contents.push(m.content);
@@ -200,6 +202,18 @@ export class MessageQueue {
                 allImages.push(...m.images);
             if (m.mentions)
                 allMentions.push(...m.mentions);
+            // 逐条保留发送者、时刻、图片；若该条已自带 items（罕见），展开保留细粒度
+            if (m.items && m.items.length > 0) {
+                subMessages.push(...m.items);
+            }
+            else {
+                subMessages.push({
+                    peerId: m.peerId, peerName: m.peerName, peerType: m.peerType,
+                    sameDevice: m.sameDevice, sameNetwork: m.sameNetwork, sameEgressIp: m.sameEgressIp,
+                    content: m.content, timestamp: m.timestamp,
+                    images: m.images && m.images.length > 0 ? m.images : undefined,
+                });
+            }
         }
         const last = items[items.length - 1];
         // 保留最新一条的 messageId（若最后一条无 ID 则回退到前面已有的 ID）
@@ -213,6 +227,7 @@ export class MessageQueue {
         const merged = {
             ...last.message,
             content: contents.join('\n'),
+            items: subMessages,
             images: allImages.length > 0 ? allImages : undefined,
             mentions: allMentions.length > 0 ? allMentions : undefined,
             messageId: latestMessageId,

package/dist/core/trigger/scheduler.js

@@ -164,15 +164,16 @@ export class TriggerScheduler {
     onFire() {
         this.timer = null;
         const now = Date.now();
-        // Fire all triggers that are due
-        while (this.heap.peek() && this.heap.peek().nextFireAt <= now + 50) {
+        // Loop guard reads a LIVE clock (not the frozen `now`): if rescheduling ever regresses
+        // and pushes an occurrence back inside the window, re-reading the clock each iteration
+        // still lets time advance past it so the loop drains and terminates.
+        while (this.heap.peek() && this.heap.peek().nextFireAt <= Date.now() + 50) {
             const trigger = this.heap.pop();
             if (trigger.scheduleType === 'cron' && this.inflightCron.has(trigger.id)) {
-                // Previous run still in flight — skip
+                // Previous run still in flight — skip this occurrence, reschedule the next one.
                 logger.warn(`[${this.aid}] Cron trigger ${trigger.name} still running, skipping`);
                 this.eventBus.publish({ type: 'trigger:skipped', triggerId: trigger.id, reason: 'overlap' });
-                // Re-schedule next cron occurrence
-                const next = calcNextFireAt('cron', trigger.scheduleValue, now);
+                const next = this.nextCronFireAt(trigger.scheduleValue, Date.now());
                 this.manager.updateNextFireAt(trigger.id, next);
                 this.heap.push({ ...trigger, nextFireAt: next });
                 continue;
@@ -181,6 +182,21 @@ export class TriggerScheduler {
         }
         this.resetTimer();
     }
+    /**
+     * Next cron occurrence strictly outside the firing window.
+     *
+     * cron-parser returns the next match at-or-after the reference instant. When the timer
+     * wakes a hair early — e.g. 08:59:59.999 for a `0 9 * * *` trigger — the "next" occurrence
+     * computes to 09:00:00.000, only ~1ms ahead and inside onFire's `<= now + 50` window. That
+     * occurrence gets popped and re-fired in the same pass, producing a tight loop. Recomputing
+     * from past the window forces the genuine next occurrence (e.g. tomorrow 09:00).
+     */
+    nextCronFireAt(scheduleValue, ref) {
+        let next = calcNextFireAt('cron', scheduleValue, ref);
+        if (next <= ref + 50)
+            next = calcNextFireAt('cron', scheduleValue, ref + 51);
+        return next;
+    }
     fireTrigger(trigger, now) {
         const messageId = `trigger:${trigger.id}:${now}`;
         const msg = this.buildSyntheticMessage(trigger, messageId);
@@ -189,8 +205,8 @@ export class TriggerScheduler {
         this.manager.updateFireStats(trigger.id, now);
         if (trigger.scheduleType === 'cron') {
             this.inflightCron.add(trigger.id);
-            // Re-schedule next occurrence
-            const next = calcNextFireAt('cron', trigger.scheduleValue, now);
+            // Re-schedule next occurrence (outside the firing window — see nextCronFireAt)
+            const next = this.nextCronFireAt(trigger.scheduleValue, now);
             this.manager.updateNextFireAt(trigger.id, next);
             this.heap.push({ ...trigger, nextFireAt: next });
         }

package/dist/index.js

@@ -522,54 +522,6 @@ async function main() {
             logger.error(`[Trigger] Scheduler init failed for ${agent.aid}: ${err}`);
         }
     }
-    // Inject primary agent's trigger scheduler as fallback (used when owning agent has no scheduler)
-    const primaryAgentForTrigger = agentRegistry.runnableAgents()[0];
-    if (primaryAgentForTrigger?.triggerScheduler && primaryAgentForTrigger?.triggerManager) {
-        cmdHandler.setTriggerScheduler(primaryAgentForTrigger.triggerScheduler, primaryAgentForTrigger.triggerManager);
-    }
-    // Seed default __upgrade-check trigger (daily at random time 3:00~3:59)
-    // 用户可通过 /trigger cancel __upgrade-check 永久禁用（不会再自动重建）
-    if (!isLinkedInstall() && primaryAgentForTrigger?.triggerManager && primaryAgentForTrigger?.triggerScheduler) {
-        const mgr = primaryAgentForTrigger.triggerManager;
-        const sched = primaryAgentForTrigger.triggerScheduler;
-        const UPGRADE_TRIGGER_NAME = '__upgrade-check';
-        if (!mgr.getByName(UPGRADE_TRIGGER_NAME)) {
-            // Check history: if user cancelled it before, respect that decision
-            const { history } = mgr.listAll();
-            const wasCancelled = history.some(h => h.name === UPGRADE_TRIGGER_NAME && h.doneReason === 'cancelled');
-            if (!wasCancelled) {
-                // Random minute in 3:00~3:59 to avoid all instances hitting registry simultaneously
-                const randomMinute = Math.floor(Math.random() * 60);
-                const cronExpr = `${randomMinute} 3 * * *`;
-                // Use first channel instance as target (command doesn't need real channelId)
-                const firstChannel = channelInstances[0]?.adapter?.channelName || 'system';
-                const trigger = {
-                    id: crypto.randomUUID(),
-                    name: UPGRADE_TRIGGER_NAME,
-                    scheduleType: 'cron',
-                    scheduleValue: cronExpr,
-                    nextFireAt: calcNextFireAt('cron', cronExpr),
-                    targetChannel: firstChannel,
-                    targetChannelId: '__system__',
-                    targetSessionStrategy: 'latest',
-                    prompt: '检查 evolclaw 是否有新版本可用。执行 `npm view evolclaw version` 获取最新版本，与当前版本（执行 `evolclaw --version`）对比。如果有新版本，执行 /restart 进行升级。如果已是最新版本，无需任何操作。',
-                    createdByPeerId: '__system__',
-                    createdByChannel: '__system__',
-                    fireCount: 0,
-                    createdAt: Date.now(),
-                    updatedAt: Date.now(),
-                };
-                try {
-                    mgr.register(trigger);
-                    sched.register(trigger);
-                    logger.info(`[Trigger] Seeded default trigger: ${UPGRADE_TRIGGER_NAME} (cron ${cronExpr})`);
-                }
-                catch (e) {
-                    logger.warn(`[Trigger] Failed to seed ${UPGRADE_TRIGGER_NAME}: ${e}`);
-                }
-            }
-        }
-    }
     // 默认策略
     const defaultPolicy = {
         canSwitchProject: (chatType, role) => chatType === 'private' ? (role === 'owner' || role === 'admin') : role === 'owner',
@@ -641,6 +593,54 @@ async function main() {
     for (const inst of channelInstances) {
         registerChannelInstance(inst);
     }
+    // Inject primary agent's trigger scheduler after all channels are registered so
+    // channelTypeMap is fully populated when setTriggerScheduler backfills old triggers.
+    // Seed __upgrade-check here too — needs channelInstances[0].channelType to be resolved.
+    const primaryAgentForTrigger = agentRegistry.runnableAgents()[0];
+    if (primaryAgentForTrigger?.triggerScheduler && primaryAgentForTrigger?.triggerManager) {
+        cmdHandler.setTriggerScheduler(primaryAgentForTrigger.triggerScheduler, primaryAgentForTrigger.triggerManager);
+    }
+    // Seed default __upgrade-check trigger (daily at random time 3:00~3:59)
+    // 用户可通过 /trigger cancel __upgrade-check 永久禁用（不会再自动重建）
+    if (!isLinkedInstall() && primaryAgentForTrigger?.triggerManager && primaryAgentForTrigger?.triggerScheduler) {
+        const mgr = primaryAgentForTrigger.triggerManager;
+        const sched = primaryAgentForTrigger.triggerScheduler;
+        const UPGRADE_TRIGGER_NAME = '__upgrade-check';
+        if (!mgr.getByName(UPGRADE_TRIGGER_NAME)) {
+            const { history } = mgr.listAll();
+            const wasCancelled = history.some(h => h.name === UPGRADE_TRIGGER_NAME && h.doneReason === 'cancelled');
+            if (!wasCancelled) {
+                const randomMinute = Math.floor(Math.random() * 60);
+                const cronExpr = `${randomMinute} 3 * * *`;
+                const firstChannelInst = channelInstances[0];
+                const firstChannel = firstChannelInst?.adapter?.channelName || 'system';
+                const trigger = {
+                    id: crypto.randomUUID(),
+                    name: UPGRADE_TRIGGER_NAME,
+                    scheduleType: 'cron',
+                    scheduleValue: cronExpr,
+                    nextFireAt: calcNextFireAt('cron', cronExpr),
+                    targetChannel: firstChannel,
+                    targetChannelId: '__system__',
+                    targetSessionStrategy: 'latest',
+                    prompt: '检查 evolclaw 是否有新版本可用。执行 `npm view evolclaw version` 获取最新版本，与当前版本（执行 `evolclaw --version`）对比。如果有新版本，执行 /restart 进行升级。如果已是最新版本，无需任何操作。',
+                    createdByPeerId: '__system__',
+                    createdByChannel: '__system__',
+                    fireCount: 0,
+                    createdAt: Date.now(),
+                    updatedAt: Date.now(),
+                };
+                try {
+                    mgr.register(trigger);
+                    sched.register(trigger);
+                    logger.info(`[Trigger] Seeded default trigger: ${UPGRADE_TRIGGER_NAME} (cron ${cronExpr})`);
+                }
+                catch (e) {
+                    logger.warn(`[Trigger] Failed to seed ${UPGRADE_TRIGGER_NAME}: ${e}`);
+                }
+            }
+        }
+    }
     // Bind adapters to their owning agents and mark running
     for (const inst of channelInstances) {
         const agent = agentRegistry.resolveByChannel(inst.adapter.channelKey);

package/kits/docs/context-assembly.md

@@ -67,6 +67,44 @@ manifest 是 `{ "$schema_version": 1, "sections": [...] }`。每个 section：
 
 合并后统一按 `order` 升序排序。改某段行为（如关掉某层、调顺序、换条件）优先用覆盖文件，不动基础 manifest。
 
+### 覆盖示例
+
+禁用某段：
+
+```json
+{ "sections": [ { "id": "venue-client", "enabled": false } ] }
+```
+
+改加载条件（仅 owner/admin 才载入对端档案）：
+
+```json
+{ "sections": [ { "id": "peer-profile", "when": { "var": "peerRole", "in": ["owner", "admin"] } } ] }
+```
+
+新增自定义段：
+
+```json
+{
+  "sections": [
+    {
+      "id": "my-custom-context",
+      "type": "file",
+      "file": "$AGENT_DIR/custom/my-rules.md",
+      "order": 25,
+      "needsInjection": false,
+      "when": "always",
+      "description": "我的自定义规则"
+    }
+  ]
+}
+```
+
+完全替换（忽略基础 manifest）：
+
+```json
+{ "$schema_version": 1, "mode": "replace", "sections": [ ... ] }
+```
+
 ## 路径与模板渲染
 
 ### 路径占位符（所有 section 的 file/path）
@@ -74,6 +112,23 @@ manifest 是 `{ "$schema_version": 1, "sections": [...] }`。每个 section：
 - `$NAME`（大写）→ 从 vars 取真值，如 `$KITS_DOCS` → 包内文档目录。
 - `{{key}}` → 从 vars 取真值，如 `{{chatType}}` → `private`，`{{peerKey}}` → `aun#alice.aid.pub`。
 
+manifest 中常用路径变量的展开值：
+
+| 变量 | 展开为 |
+|------|--------|
+| `$PACKAGE_ROOT` | evolclaw 包根 |
+| `$EVOLCLAW_HOME` | 用户数据根（默认 `~/.evolclaw`） |
+| `$KITS` | `$PACKAGE_ROOT/kits` |
+| `$KITS_RULES` | `$KITS/rules` |
+| `$KITS_DOCS` | `$KITS/docs` |
+| `$KITS_TEMPLATES` | `$KITS/templates` |
+| `$KITS_FRAGMENTS` | `$KITS_TEMPLATES/system-fragments` |
+| `$ECK` | `$EVOLCLAW_HOME/eck` |
+| `$AGENT_DIR` | `$EVOLCLAW_HOME/agents/<selfAid>` |
+| `$PERSONAL_DIR` | `$AGENT_DIR/personal` |
+| `$RELATIONS_DIR` | `$AGENT_DIR/relations` |
+| `$VENUES_DIR` | `$AGENT_DIR/venues` |
+
 任一占位符解析为空 → 该 section 视为"未解析"，跳过（调试输出标 `unresolved-vars`）。文件不存在 → 标 `not-exist`，也跳过。这是**正常机制**：很多 section 靠"路径解析不出来"自然落选（如 coding 场景没有 `$PERSONAL_DIR`）。
 
 ### 模板渲染（仅 needsInjection:true 的文件）
@@ -118,6 +173,16 @@ vars 由 evolclaw 在 `message-processor.ts` 按当前会话构造。分两类
 
 coding 场景（无 channel/无身份）下，`chatType`、`channel`、`selfAid`、`peer*` 等均为空——这正是身份/关系/环境/渠道层落选的原因。
 
+## 三种加载方式
+
+| 加载方式 | 决策者 | 驱动方式 | 例子 |
+|---------|-------|---------|------|
+| **全量加载** | manifest | `when: "always"` | rules/ 核心规则、session 参数 |
+| **按条件自动加载** | manifest | `when` 条件 + 路径存在性 | 身份层（chatType 非空时）、对端档案（peerKey 非空时） |
+| **按需加载** | agent 自主 | agent 在对话中主动 Read 文件 | 查阅 `$KITS_DOCS/` 下的详细参考文档 |
+
+前两种由 manifest 控制，第三种由 agent 根据各层文档中的"按需加载指引"自主决定。
+
 ## 默认 manifest 的段（按 order）
 
 | order | id | 类型 | 加载条件（when） | inject |
@@ -140,6 +205,27 @@ coding 场景（无 channel/无身份）下，`chatType`、`channel`、`selfAid`
 
 > 注意：`session`(60) 是 `always`，`baseagent`(70) 只看 `baseAgent` 是否注入——这两段**与 chatType 无关**，coding 场景也会加载。所谓"coding 仅 rules"是近似说法：精确地说 coding 场景命中的是 rules + session + baseagent（其余因 chatType/channel 为空而落选）。
 
+## 环境层文档目录结构
+
+venue-* 段从两棵目录树取文件——随包发布的通用文档（只读）和 agent 私有的具体环境文档（按需创建）：
+
+```
+$KITS_DOCS/venues/                  通用环境文档（随包发布，只读）
+├── private.md                      单聊场景通用指引
+├── group.md                        群聊场景通用指引
+├── aun-private.md                  AUN 单聊特有
+├── aun-group.md                    AUN 群聊特有
+├── feishu-private.md               飞书单聊特有
+├── feishu-group.md                 飞书群聊特有
+├── client-desktop.md               桌面端环境
+├── client-mobile.md                移动端环境
+└── ...
+
+$AGENT_DIR/venues/                  agent 私有环境文档（按需创建）
+└── <channel>#<urlEncode(groupId)>/
+    └── profile.md                  具体群的特别内容
+```
+
 ## 输出结构
 
 所有命中 section 的文件内容拼成一个块，注入 system prompt：

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

@@ -0,0 +1,234 @@
+# EvolClaw 提示词装载全景（Prompt Loading Architecture）
+
+> 文档范围：消息从渠道到 base agent 的完整提示词装载流程，涵盖系统提示词渲染层与消息渲染层两套机制。
+> 最后更新：2026-06-04
+
+---
+
+## 总体数据流
+
+```
+收到一条消息
+       │
+       ▼
+┌──────────────────────────────────────────────────────────┐
+│  MessageBridge                                           │
+│  • 消息预处理（去重/拦截/chatType 填充）                   │
+│  • messagePrefix 硬编码已移除（归消息渲染层）              │
+│  • 构造 Message（含 items=undefined 此时）                │
+└──────────────────────┬───────────────────────────────────┘
+                       │
+                       ▼
+┌──────────────────────────────────────────────────────────┐
+│  MessageQueue                                            │
+│  • 去重 / 单聊 interrupt / 群聊 FIFO                     │
+│  • dequeueGreedy：弹出连续同 peerId 消息                  │
+│  • mergeItems（多条时）：                                 │
+│    - content = join('\n')（兜底）                        │
+│    - items[] = 每条 SubMessage{peer,time,images,...}     │
+│    - images/mentions 扁平合并（给 runQuery 的总量）       │
+└──────────────────────┬───────────────────────────────────┘
+                       │ Message（可能带 items[]）
+                       ▼
+┌──────────────────────────────────────────────────────────┐
+│  MessageProcessor.processMessage()                       │
+│                                                          │
+│  ① wrapPrompt 准备（中断包装函数）                        │
+│     effectivePrompt = wrapPrompt(message.content) ← 兜底 │
+│                                                          │
+│  ② 构造 kitCtx.vars（~47 个变量，见下节）                 │
+│                                                          │
+│  ③ 系统提示词渲染层                                       │
+│     renderKitSections(kitCtx)                            │
+│     effectiveSystemPrompt = persona + kitContext         │
+│                                                          │
+│  ④ 消息渲染层                                             │
+│     renderMessageBody(items, kitCtx.vars, sessionId)     │
+│     effectivePrompt = wrapPrompt(body)  ← 覆盖兜底       │
+│     renderImages = result.images                         │
+│                                                          │
+│  ⑤ agent.runQuery(                                       │
+│       effectivePrompt,                                   │
+│       renderImages ?? message.images,                    │
+│       effectiveSystemPrompt,                             │
+│       modelOverride                                      │
+│     )                                                    │
+└──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 两个渲染层对比
+
+|  | 系统提示词渲染层 | 消息渲染层 |
+|--|--|--|
+| **驱动文件** | `kits/eck_manifest.json` | `kits/eck_message_manifest.json` |
+| **覆盖文件** | `$EVOLCLAW_HOME/eck/eck_manifest.json` | `$EVOLCLAW_HOME/eck/eck_message_manifest.json` |
+| **模板目录** | `kits/templates/system-fragments/` | `kits/templates/message-fragments/` |
+| **输出去向** | `systemPrompt.append`（每轮覆盖，不进 transcript） | `effectivePrompt`（进 transcript，成永久历史） |
+| **vars 粒度** | 会话级（一次构造，整批复用） | item 级（每条叠加 peerName/now/images） |
+| **模板空行** | 删除（stripBlankLines=true，紧凑） | 保留（stripBlankLines=false，消息多段） |
+| **content 注入** | N/A | 哨兵末步字面量注入（防二次解析） |
+| **缓存** | per-sessionId（跨消息复用文件内容） | per-renderMessageBody 调用（局部） |
+| **debug 输出** | `eck-debug/context-*.md` `fragments-*.md` `manifest-*.md` `vars-*.json` | `eck-debug/msg-render-*.md` |
+
+---
+
+## manifest 共享引擎（manifest-engine.ts）
+
+两个渲染层共用同一套原语，由 `src/agents/manifest-engine.ts` 提供：
+
+| 函数 | 作用 |
+|------|------|
+| `loadManifest(filename)` | 加载并合并 manifest，按文件名缓存 |
+| `evaluateWhen(when, vars)` | 求值 section 加载条件 |
+| `renderTemplate(tpl, vars, stripBlankLines)` | 条件块 + 变量替换，可选删空行 |
+| `resolvePathWithDiag(rawPath, vars)` | `$VAR` / `{{key}}` 路径展开 + 诊断 |
+| `loadSectionFiles(section, vars, cache)` | 按 section 类型加载文件内容 |
+| `buildPathMappings(vars)` / `shortenPath` | debug 输出路径别名化 |
+| `invalidateManifestCache()` | 清全部 manifest 缓存 |
+
+---
+
+## 系统提示词渲染层详解
+
+### 执行位置
+
+`src/core/message/message-processor.ts` → `renderKitSections(kitCtx)` → `src/agents/kit-renderer.ts`
+
+### manifest 默认段（按 order）
+
+| order | id | 加载条件 | needsInjection | 内容 |
+|-------|----|----|--------|------|
+| 10 | rules | always | ✗ | `$KITS_RULES/` 目录（ECK 核心规则） |
+| 20 | identity-layer | chatType≠null | ✓ | 身份层 fragment |
+| 21 | persona | chatType≠null | ✗ | `$PERSONAL_DIR/persona.md` |
+| 22 | working-memory | chatType≠null | ✗ | `$PERSONAL_DIR/memory/working.md` |
+| 30 | relation-layer | chatType∈{private,group} | ✓ | 关系层 fragment |
+| 35 | peer-profile | peerKey≠null | ✗ | 对端 profile.md |
+| 40 | venue-fragment | chatType≠null | ✓ | 环境层 fragment |
+| 41 | venue-chattype | chatType≠null | ✗ | `venues/{{chatType}}.md` |
+| 42 | venue-channel-chattype | chatType≠null | ✗ | `venues/{{channel}}-{{chatType}}.md` |
+| 43 | venue-group-profile | groupId≠null | ✗ | 群 venue profile.md |
+| 44 | venue-client | clientType≠null | ✗ | `venues/client-{{clientType}}.md` |
+| 50 | channel-layer | channel≠null | ✓ | 渠道层 fragment |
+| 55 | commands | channel≠null | ✓ | 命令集能力卡 |
+| 60 | session | always | ✓ | 会话层 fragment（含 localDate/weekday） |
+| 70 | baseagent | baseAgent≠null | ✓ | base agent 配置 fragment |
+
+### 输出结构
+
+```
+<system-reminder>
+EvolClaw Context Kit documents are shown below.
+
+Contenu de $KITS_RULES/01-overview.md (rules — ECK 核心规则):
+...（各 section 内容，按 order）
+
+IMPORTANT: Use this context when it affects the current interaction.
+</system-reminder>
+```
+
+---
+
+## 消息渲染层详解
+
+### 执行位置
+
+`src/core/message/message-processor.ts` → `renderMessageBody(items, vars, sessionId)` → `src/agents/message-renderer.ts`
+
+### 渲染流程
+
+```
+for each SubMessage in items:
+  sentinel = '\x00ECMSG-<UUID>\x00'   ← 每次调用独立，null 字节在渠道消息中不可能出现
+  itemVars = {
+    ...sessionVars,
+    peerId / peerName / peerType,      ← 本条消息自己的发送者
+    now = formatLocalTime(timestamp),  ← 本条消息自己的时刻
+    content = sentinel,                ← 占位，末步换回
+  }
+  loadManifest(eck_message_manifest) → 选段 → renderTemplate(stripBlankLines=false)
+  rendered.split(sentinel).join(item.content)  ← 字面量注入，不二次解析
+  收集 item.images
+
+join('\n\n') → { body: string, images: ImageData[] }
+```
+
+### 初始 manifest（一个段）
+
+```json
+{
+  "id": "msg-item",
+  "file": "$KITS_MESSAGE_FRAGMENTS/item.md",
+  "when": "always",
+  "needsInjection": true
+}
+```
+
+### 紧凑模板（item.md）
+
+```
+‹{{now}}{{?chatType=group}} · {{peerName}}{{/}}›
+{{content}}
+```
+
+- 私聊：`{{?chatType=group}}` 块收敛，只剩时间
+- 群聊：时间 + 发送者名
+- 改格式只动这一个文件，不动代码
+
+---
+
+## vars 时变性归属
+
+### 进系统提示词（每轮覆盖，缓存友好）
+
+| 类别 | 变量 |
+|------|------|
+| 静态（进程级） | `PACKAGE_ROOT` `KITS*` `evolclawMode` `osInfo` `baseAgent` |
+| 会话稳定 | `selfAid` `sessionId` `sessionKey` `chatType` `channel` `timezone` `tzOffset` `capabilities` `CURRENT_PROJECT` |
+| 慢变（配置驱动） | `effectiveModel` `permissionMode` `peerRole` `readonly` `chatMode` `modelFallback*` |
+| 新增（日期级） | `localDate`（YYYY-MM-DD）`weekday`（星期四），一天才变一次，缓存暖 ~24h |
+
+### 进消息渲染层（每条独立，进 transcript 永久保真）
+
+| 变量 | 说明 |
+|------|------|
+| `now` | 精确到秒的本地时间（含时区偏移），每条自己的发生时刻 |
+| `peerName` / `peerId` / `peerType` | 群聊每条消息的发送者，单聊复用会话值 |
+| `content` | 原始消息文本（字面量注入，不参与模板解析） |
+| `images` | 按条归属的图片（SubMessage.images） |
+
+---
+
+## 关键保证
+
+| 保证 | 实现方式 |
+|------|---------|
+| **模板注入防护** | 哨兵 `\x00ECMSG-<UUID>\x00`，per-call 独立，null 字节在任何渠道消息中不可能出现 |
+| **消息不丢失** | manifest 无产出或渲染抛异常均显式 fallback 到 `wrapPrompt(message.content)` |
+| **系统提示词不累积** | `systemPrompt.append` 是 SDK 每次 `query()` 的独立参数，随调用重传覆盖，不进 transcript |
+| **图片归属** | `SubMessage.images` 按条保留，`renderMessageBody` 返回按顺序收集的 images；`runQuery` 用此数组而非 flat-merge 的 `message.images` |
+| **群聊发送者保真** | 每条 SubMessage 携带自己的 peerName/peerId，进 transcript 成永久历史，模型可推理"谁说的、隔了多久" |
+| **空消息安全** | `hasContent` guard，空消息不进渲染层，不传 `runQuery` |
+
+---
+
+## 文件索引
+
+| 文件 | 角色 |
+|------|------|
+| `src/agents/manifest-engine.ts` | 共享渲染引擎原语 |
+| `src/agents/kit-renderer.ts` | 系统提示词渲染，输出 `<system-reminder>` |
+| `src/agents/message-renderer.ts` | 消息渲染层，输出 `{ body, images }` |
+| `src/core/message/message-processor.ts` | 装配点：构造 vars，调两层渲染，调 runQuery |
+| `src/core/message/message-queue.ts` | 队列合并：mergeItems 保留 items[] 和 per-item images |
+| `src/core/message/message-bridge.ts` | 消息入口：已移除 messagePrefix 硬编码 |
+| `src/types.ts` | SubMessage / Message.items 类型定义 |
+| `kits/eck_manifest.json` | 系统提示词 manifest |
+| `kits/eck_message_manifest.json` | 消息渲染 manifest |
+| `kits/templates/system-fragments/session.md` | 含 localDate/weekday |
+| `kits/templates/message-fragments/item.md` | 消息渲染紧凑模板 |
+| `$EVOLCLAW_HOME/eck/eck_manifest.json` | 系统提示词 manifest 用户覆盖（可选） |
+| `$EVOLCLAW_HOME/eck/eck_message_manifest.json` | 消息渲染 manifest 用户覆盖（可选） |
+| `$EVOLCLAW_HOME/data/eck-debug/` | 调试输出目录（保留 24h） |

package/kits/eck_message_manifest.json

@@ -0,0 +1,14 @@
+{
+  "$schema_version": 1,
+  "sections": [
+    {
+      "id": "msg-item",
+      "type": "file",
+      "file": "$KITS_MESSAGE_FRAGMENTS/item.md",
+      "order": 10,
+      "needsInjection": true,
+      "when": "always",
+      "description": "单条消息渲染（逐条）"
+    }
+  ]
+}

package/kits/templates/message-fragments/item.md

@@ -0,0 +1,2 @@
+‹{{now}}{{?chatType=group}} · {{peerName}}{{/}}{{?sameDevice}} · 📍同设备{{/}}{{?sameNetwork}} · 🌐同网络{{/}}{{?sameEgressIp}} · 🔀同出口IP{{/}}›
+{{content}}

package/kits/templates/system-fragments/session.md

@@ -9,6 +9,9 @@ sessionKey: {{sessionKey}} # 会话路由键（channelType#urlEncode(channelId)#
 sessionName: {{sessionName}}
 {{/}}
 sessionCreatedAt: {{sessionCreatedAt}}
+{{?localDate}}
+localDate: {{localDate}} {{weekday}} # 当前日期与星期（每条消息的精确时刻见消息正文前缀 ‹…›）
+{{/}}
 {{?timezone}}
 timezone: {{timezone}} # 时区 IANA 名：把消息/记忆里的 ISO 时间戳转成本地时间字符串时按此换算
 {{/}}

package/kits/templates/system-fragments/venue.md

@@ -21,10 +21,10 @@ clientType: {{clientType}} # 客户端类型：desktop / web / mobile
 groupId: {{groupId}}
 {{/}}
 {{?sameDevice}}
-sameDevice: true # 对端与你运行在同一台设备上（E2EE 消息 proximity）
+sameDevice: true # 对端与你运行在同一台设备上
 {{/}}
 {{?sameNetwork}}
-sameNetwork: true # 对端与你在同一网络内
+sameNetwork: true # 对端与你在同一网络内（同域）
 {{/}}
 {{?sameEgressIp}}
 sameEgressIp: true # 对端与你共享同一出口 IP

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolclaw",
-  "version": "3.1.6",
+  "version": "3.1.8",
   "description": "Lightweight AI Agent gateway connecting Claude Agent SDK to messaging channels (Feishu, ACP) with multi-project session management",
   "type": "module",
   "main": "dist/index.js",
@@ -12,6 +12,7 @@
     "dist/",
     "bin/",
     "assets/",
+    "!assets/wechat-group-qr.jpeg",
     "!dist/experimental/",
     "kits/",
     "!kits/.kits-version",
@@ -22,7 +23,7 @@
   ],
   "scripts": {
     "dev": "tsx watch src/index.ts",
-    "build": "tsc && node -e \"const f='dist/cli/index.js',c=require('fs').readFileSync(f,'utf8');if(!c.startsWith('#!'))require('fs').writeFileSync(f,'#!/usr/bin/env node\\n'+c)\" && node -e \"try{require('child_process').execFileSync('chmod',['+x','dist/cli/index.js'])}catch{}\" && node -e \"require('fs').mkdirSync('dist/data',{recursive:true});require('fs').copyFileSync('src/data/error-dict.json','dist/data/error-dict.json')\"",
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc && node -e \"const f='dist/cli/index.js',c=require('fs').readFileSync(f,'utf8');if(!c.startsWith('#!'))require('fs').writeFileSync(f,'#!/usr/bin/env node\\n'+c)\" && node -e \"try{require('child_process').execFileSync('chmod',['+x','dist/cli/index.js'])}catch{}\" && node -e \"require('fs').mkdirSync('dist/data',{recursive:true});require('fs').copyFileSync('src/data/error-dict.json','dist/data/error-dict.json')\"",
     "start": "node dist/index.js",
     "test": "vitest run",
     "test:watch": "vitest",

package/dist/cli/watch-web/debug-log.js

@@ -1,18 +0,0 @@
-/**
- * watch-web 调试日志 — 写入 $EVOLCLAW_HOME/logs/watch-web.log。
- *
- * cmdWatchWeb 启动时清空该文件并调用 setDebugLog 注入 writer，
- * 各 source / server 通过 dlog() 写调试信息，建立「运行→看日志→定位」的闭环。
- */
-let _writer = null;
-export function setDebugLog(writer) {
-    _writer = writer;
-}
-export function dlog(line) {
-    if (_writer) {
-        try {
-            _writer(line);
-        }
-        catch { /* ignore */ }
-    }
-}