evolcore 0.0.1 → 0.0.3

package/dist/eck/manifest-engine.js

@@ -0,0 +1,446 @@
+// 声明式 manifest 渲染引擎（共享）。
+// 系统提示词渲染（kit-renderer）与消息渲染（message-renderer）共用同一套
+// when 求值、模板渲染、路径解析、manifest 加载/缓存原语，避免两套实现漂移。
+import fs from 'fs';
+import path from 'path';
+import { kitsDir, resolveRoot, getPackageRoot } from '../paths.js';
+import { logger } from '../utils/logger.js';
+import { fileCache } from '../core/daemon-file-cache.js';
+// ── 限额默认值 ──
+/** 单目录段默认最多文件数 */
+export const DIR_MAX_FILES = 20;
+/** 单目录段默认最多总字节（40KB） */
+export const DIR_MAX_BYTES = 40 * 1024;
+/** 整个清单默认最多文件数 */
+export const TOTAL_MAX_FILES = 50;
+/** 整个清单默认最多总字节（100KB） */
+export const TOTAL_MAX_BYTES = 100 * 1024;
+// ── Manifest loading / cache ──
+// manifest 定义随包发布、运行期靠 reload/重启刷新 → on-reload（group 'kits'）。
+// base + eck override 合成结果以 base 文件路径为键缓存；loader 内读两个文件。
+/** 清空所有 manifest 缓存（manifest 结构变更后调用，由 invalidateKitCache 串联）。 */
+export function invalidateManifestCache() {
+    fileCache.invalidateGroup('kits');
+}
+/**
+ * 加载并合并 manifest。基础文件在 $KITS/<filename>，
+ * 覆盖文件在 $EVOLCORE_HOME/eck/<filename>（可选）。结果按 order 升序缓存。
+ */
+export function loadManifest(filename) {
+    const kitsPath = path.join(kitsDir(), filename);
+    return fileCache.get(kitsPath, () => {
+        const sections = loadAndMergeManifest(filename);
+        logger.info(`[ManifestEngine] Loaded ${filename}: ${sections.length} sections`);
+        return sections;
+    }, { policy: 'on-reload', group: 'kits' });
+}
+function loadAndMergeManifest(filename) {
+    const kitsPath = path.join(kitsDir(), filename);
+    const eckPath = path.join(resolveRoot(), 'eck', filename);
+    let base;
+    try {
+        base = JSON.parse(fs.readFileSync(kitsPath, 'utf-8'));
+    }
+    catch (err) {
+        logger.error(`[ManifestEngine] Failed to load kits/${filename}: ${err}`);
+        return [];
+    }
+    if (!fs.existsSync(eckPath))
+        return sortSections(base.sections);
+    try {
+        const override = JSON.parse(fs.readFileSync(eckPath, 'utf-8'));
+        if (override.mode === 'replace')
+            return sortSections(override.sections);
+        const merged = new Map();
+        for (const s of base.sections)
+            merged.set(s.id, { ...s });
+        for (const s of override.sections) {
+            const existing = merged.get(s.id);
+            merged.set(s.id, existing ? { ...existing, ...s } : s);
+        }
+        return sortSections([...merged.values()]);
+    }
+    catch (err) {
+        logger.warn(`[ManifestEngine] Failed to load eck override for ${filename}, using kits only: ${err}`);
+        return sortSections(base.sections);
+    }
+}
+function sortSections(sections) {
+    return sections.slice().sort((a, b) => a.order - b.order);
+}
+/**
+ * 读取清单顶层总闸限额（base + eck override 合并，override 优先）。
+ * 与 loadManifest 分开，避免改动现有 `ManifestSection[]` 返回契约。
+ */
+export function loadManifestMeta(filename) {
+    const kitsPath = path.join(kitsDir(), filename);
+    return fileCache.get(`${kitsPath}#meta`, () => {
+        const kits = readRawManifest(kitsPath);
+        const eck = readRawManifest(path.join(resolveRoot(), 'eck', filename));
+        return {
+            totalMaxFiles: eck?.totalMaxFiles ?? kits?.totalMaxFiles ?? TOTAL_MAX_FILES,
+            totalMaxBytes: eck?.totalMaxBytes ?? kits?.totalMaxBytes ?? TOTAL_MAX_BYTES,
+        };
+    }, { policy: 'on-reload', group: 'kits' });
+}
+function readRawManifest(p) {
+    try {
+        if (!fs.existsSync(p))
+            return null;
+        return JSON.parse(fs.readFileSync(p, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 从 manifest 抽出每个 modeType 标了 isDefault 的 modeName。
+ * 供 message-renderer 在 agent config.render 未配某类型时回退。
+ * 同一 modeType 有多个 isDefault 时取 order 最小（已排序）的第一个。
+ */
+export function defaultModeNames(sections) {
+    const out = {};
+    for (const s of sections) {
+        if (s.modeType && s.isDefault && s.modeName && out[s.modeType] === undefined) {
+            out[s.modeType] = s.modeName;
+        }
+    }
+    return out;
+}
+// ── When condition evaluation ──
+export function evaluateWhen(when, vars) {
+    if (when === 'always')
+        return true;
+    // 复合条件优先：and / or 递归求值。
+    if (when.and)
+        return when.and.every(c => evaluateWhen(c, vars));
+    if (when.or)
+        return when.or.some(c => evaluateWhen(c, vars));
+    if (when.var !== undefined) {
+        const val = vars[when.var];
+        if (when.eq !== undefined) {
+            if (when.eq === null)
+                return val === null || val === undefined;
+            return val === when.eq;
+        }
+        if (when.neq !== undefined) {
+            if (when.neq === null)
+                return val !== null && val !== undefined;
+            return val !== when.neq;
+        }
+        if (when.in !== undefined)
+            return when.in.includes(val);
+        if (when.nin !== undefined)
+            return !when.nin.includes(val);
+    }
+    if (when.any)
+        return when.any.some(k => isTruthy(vars[k]));
+    if (when.all)
+        return when.all.every(k => isTruthy(vars[k]));
+    return true;
+}
+export function isTruthy(val) {
+    if (Array.isArray(val))
+        return val.length > 0; // 空数组视为假，使 {{?arr}} / {{#each}} 落空
+    return val !== undefined && val !== null && val !== false && val !== '' && val !== 0;
+}
+// ── Template rendering ──
+/**
+ * 展开 {{#each KEY}}BODY{{/each}} 循环块（在条件/变量替换之前跑）。
+ * - vars[KEY] 为非空数组才展开；每个元素构造子作用域：
+ *     对象元素 → { ...vars, ...el }（字段可用 {{field}} 访问）
+ *     标量元素 → { ...vars, '.': el }（{{.}} 访问当前元素）
+ *   另注入 {{@index}}（0 基序号）。
+ * - body 经完整 renderTemplate 递归渲染，天然支持嵌套 each / 条件。
+ * - 非数组或空数组 → 整块渲染为空串。
+ * 用深度扫描定位**最外层** each 块（正则无法平衡嵌套），从外向内展开。
+ */
+function resolveEach(template, vars, stripBlankLines) {
+    const OPEN = /\{\{#each\s+([A-Za-z_]\w*)\}\}/g;
+    let result = '';
+    let cursor = 0;
+    OPEN.lastIndex = 0;
+    let m;
+    while ((m = OPEN.exec(template)) !== null) {
+        const blockStart = m.index;
+        const key = m[1];
+        const bodyStart = OPEN.lastIndex;
+        // 从 bodyStart 起按深度找配对的 {{/each}}
+        const TOKEN = /\{\{#each\s+[A-Za-z_]\w*\}\}|\{\{\/each\}\}/g;
+        TOKEN.lastIndex = bodyStart;
+        let depth = 1;
+        let bodyEnd = -1;
+        let blockEnd = -1;
+        let t;
+        while ((t = TOKEN.exec(template)) !== null) {
+            if (t[0].startsWith('{{#each'))
+                depth++;
+            else {
+                depth--;
+                if (depth === 0) {
+                    bodyEnd = t.index;
+                    blockEnd = TOKEN.lastIndex;
+                    break;
+                }
+            }
+        }
+        if (bodyEnd === -1)
+            break; // 无配对，剩余原样输出
+        // 输出块前的原文
+        result += template.slice(cursor, blockStart);
+        const body = template.slice(bodyStart, bodyEnd);
+        const arr = vars[key];
+        if (Array.isArray(arr)) {
+            for (let i = 0; i < arr.length; i++) {
+                const el = arr[i];
+                const scope = (el && typeof el === 'object' && !Array.isArray(el))
+                    ? { ...vars, ...el, '@index': i }
+                    : { ...vars, '.': el, '@index': i };
+                result += renderTemplate(body, scope, stripBlankLines);
+            }
+        }
+        // 数组以外（含 undefined / 非数组）→ 整块跳过（不输出）
+        cursor = blockEnd;
+        OPEN.lastIndex = blockEnd;
+    }
+    result += template.slice(cursor);
+    return result;
+}
+function resolveConditions(template, vars) {
+    // 只匹配**最内层** {{?...}}...{{/}} 块（逐字符负向前瞻排除嵌套），do/while 由内向外消解。
+    const inner = /\{\{\?(\w+)(?:(!=|=)([^}]*))?\}\}((?:(?!\{\{\?)[^])*?)\{\{\/\}\}/;
+    let result = template;
+    let prev;
+    do {
+        prev = result;
+        result = result.replace(inner, (_match, key, op, value, body) => {
+            if (op === '=')
+                return String(vars[key]) === value ? body : '';
+            if (op === '!=')
+                return String(vars[key]) !== value ? body : '';
+            return isTruthy(vars[key]) ? body : '';
+        });
+    } while (result !== prev);
+    return result;
+}
+/**
+ * 渲染模板：条件块 + 变量替换。stripBlankLines=true 时删除空行（系统提示词用，
+ * 紧凑）；false 时保留空行（消息正文用，正文多段结构不能被压扁）。
+ */
+export function renderTemplate(template, vars, stripBlankLines = true) {
+    let result = resolveEach(template, vars, stripBlankLines);
+    result = resolveConditions(result, vars);
+    // 变量替换：支持普通名、当前元素 {{.}}、循环序号 {{@index}}。
+    result = result.replace(/\{\{(\.|@index|\w+)\}\}/g, (_match, key) => {
+        const val = vars[key];
+        if (!isTruthy(val) && val !== 0)
+            return ''; // 0 是有效序号/值，保留
+        if (val === 0)
+            return '0';
+        return String(val);
+    });
+    if (stripBlankLines)
+        return result.split('\n').filter(line => line.trim() !== '').join('\n');
+    return result;
+}
+/**
+ * 三段式循环渲染：wrapper 里的 `{{@loop}}` 占位处，用 childTpl 对 vars[forEach]
+ * 数组每个元素渲染并拼接后填入。复用现有 `{{#each}}` 原语（不新写循环）：
+ *   把 wrapper 的 `{{@loop}}` 替换为 `{{#each forEach}}<childTpl>{{/each}}`，整体丢给 renderTemplate。
+ * 因此 childTpl 内可再嵌套 `{{#each}}`、访问元素字段与外层 vars（子作用域已合并）。
+ *
+ * 若 wrapper 不含 `{{@loop}}`，childTpl 循环结果直接追加到 wrapper 末尾（容错）。
+ */
+/**
+ * 三段式循环渲染：对 vars[forEach] 数组每个元素渲染 childTpl，以 separator 连接，
+ * 填入 wrapperTpl 的 `{{@loop}}` 占位处。
+ *
+ * - 每个元素构造子作用域（对象元素 → { ...vars, ...el, '@index': i }；标量 → { ...vars, '.': el, '@index': i }），
+ *   因此 childTpl 内可访问元素字段、外层 vars、`{{@index}}`，也可再嵌套 `{{#each}}` / 另一个占位。
+ * - separator 默认换行；可为 ""（无分隔）、"\n\n" 等。
+ * - onElementScope 可选钩子：在渲染每个元素前修改其子作用域（供 message-renderer 做 content 哨兵化）。
+ * - wrapper 不含 `{{@loop}}` 时，循环结果追加到 wrapper 末尾（容错）。
+ * - 空数组 / 非数组 → 循环结果为空串。
+ */
+export function renderLoopSection(wrapperTpl, childTpl, forEach, vars, stripBlankLines = true, separator = '\n', onElementScope) {
+    const arr = vars[forEach];
+    const parts = [];
+    if (Array.isArray(arr)) {
+        for (let i = 0; i < arr.length; i++) {
+            const el = arr[i];
+            const scope = (el && typeof el === 'object' && !Array.isArray(el))
+                ? { ...vars, ...el, '@index': i }
+                : { ...vars, '.': el, '@index': i };
+            if (onElementScope)
+                onElementScope(scope, i);
+            parts.push(renderTemplate(childTpl, scope, stripBlankLines));
+        }
+    }
+    const loopResult = parts.join(separator);
+    // wrapper 用哨兵占位 {{@loop}} → 先渲染 wrapper 外层变量，再字面量替换回 loopResult，
+    // 避免已渲染的 loopResult（可能含元素文本里的 {{}}）被二次解析。
+    const LOOP_SENTINEL = '\x00ECLOOP\x00';
+    const wrapperWithSentinel = wrapperTpl.includes('{{@loop}}')
+        ? wrapperTpl.split('{{@loop}}').join(LOOP_SENTINEL)
+        : wrapperTpl + '\n' + LOOP_SENTINEL;
+    const renderedWrapper = renderTemplate(wrapperWithSentinel, vars, stripBlankLines);
+    return renderedWrapper.split(LOOP_SENTINEL).join(loopResult);
+}
+export function resolvePathWithDiag(rawPath, vars) {
+    const unresolved = [];
+    let resolved = rawPath.replace(/\$([A-Z_]+)/g, (_m, name) => {
+        const val = vars[name];
+        if (val === undefined || val === null || val === false || val === '') {
+            unresolved.push(`$${name}`);
+            return '';
+        }
+        return String(val);
+    });
+    resolved = resolved.replace(/\{\{(\w+)\}\}/g, (_m, key) => {
+        const val = vars[key];
+        if (val === undefined || val === null || val === false || val === '') {
+            unresolved.push(`{{${key}}}`);
+            return '';
+        }
+        return String(val);
+    });
+    if (!resolved || resolved.includes('$') || resolved.includes('{{')) {
+        return { resolved: resolved || null, status: 'unresolved-vars', unresolvedTokens: unresolved };
+    }
+    if (unresolved.length > 0) {
+        return { resolved, status: 'unresolved-vars', unresolvedTokens: unresolved };
+    }
+    // 路径规范化：模板里 ../ 等相对片段折叠成真实路径。
+    // 不再在此 existsSync——存在性由随后经 fileCache 的内容读取顺带得到（file
+    // section 读出 null 即不存在），避免每 section 每消息一次 syscall。
+    resolved = path.normalize(resolved);
+    return { resolved, status: 'ok', unresolvedTokens: unresolved };
+}
+function resolvePath(rawPath, vars) {
+    const r = resolvePathWithDiag(rawPath, vars);
+    return r.status === 'ok' ? r.resolved : null;
+}
+/** 加载 loop 的 child 子模板文件内容（路径解析 + fileCache）。找不到返回 null。 */
+export function loadChildTemplate(childFile, vars) {
+    const resolved = resolvePath(childFile, vars);
+    if (!resolved)
+        return null;
+    return fileCache.getText(resolved, { policy: 'on-reload', group: 'kits' });
+}
+/**
+ * 返回 [filePath, rawContent][]；按 sessionId 缓存已读文件内容。
+ * 若传入 overflowOut 且目录段触发单目录限额（maxFiles/maxBytes），
+ * 会把溢出信息写入 overflowOut.value（不传则不启用限额收集，行为同旧版但仍应用默认上限）。
+ */
+export function loadSectionFiles(section, vars, sessionCache, overflowOut) {
+    if (section.type === 'file' && section.file) {
+        const result = loadFileSection(section.file, vars, sessionCache);
+        return result ? [result] : [];
+    }
+    if (section.type === 'directory' && section.path) {
+        const resolved = resolvePath(section.path, vars);
+        if (!resolved)
+            return [];
+        const maxFiles = section.maxFiles ?? DIR_MAX_FILES;
+        const maxBytes = section.maxBytes ?? DIR_MAX_BYTES;
+        const { files, overflow } = readDirectoryFiles(resolved, section.pattern, maxFiles, maxBytes);
+        if (overflow && overflowOut)
+            overflowOut.value = overflow;
+        return files.map(([name, content]) => [path.join(resolved, name), content]);
+    }
+    return [];
+}
+function loadFileSection(filePath, vars, sessionCache) {
+    void sessionCache; // 内容跨 session 共享，改走全局 fileCache（on-reload）
+    const resolved = resolvePath(filePath, vars);
+    if (!resolved)
+        return null;
+    // 内容跨 session 共享：用全局 fileCache（on-reload，reload/重启时失效），
+    // 不再按 session 重复缓存同一文件内容。
+    const content = fileCache.getText(resolved, { policy: 'on-reload', group: 'kits' });
+    return content === null ? null : [resolved, content];
+}
+/**
+ * 读取目录下匹配文件，受单目录限额（maxFiles/maxBytes）约束。
+ * 返回已加载文件 + 溢出信息（超限时）。按 fileCache 缓存目录列表与文件内容。
+ */
+function readDirectoryFiles(dirPath, pattern, maxFiles, maxBytes) {
+    const glob = pattern || '*.md';
+    // 目录列表 + 各文件内容均走 fileCache（on-reload）。目录列表以 "<dir>|<glob>"
+    // 为键缓存文件名数组；各文件内容走 fileCache.getText 共享。
+    const names = fileCache.get(`${dirPath} ${glob}`, () => {
+        try {
+            return fs.readdirSync(dirPath).filter(f => matchGlob(f, glob)).sort();
+        }
+        catch {
+            return [];
+        }
+    }, { policy: 'on-reload', group: 'kits' });
+    const out = [];
+    let usedBytes = 0;
+    let overflow;
+    for (let i = 0; i < names.length; i++) {
+        const f = names[i];
+        // 文件数限额
+        if (out.length >= maxFiles) {
+            overflow = { droppedFiles: names.length - out.length, reason: 'files', limit: maxFiles };
+            break;
+        }
+        const fp = path.join(dirPath, f);
+        const content = fileCache.getText(fp, { policy: 'on-reload', group: 'kits' });
+        if (content === null)
+            continue;
+        // 字节限额（至少加载一个文件，避免单个超大文件导致空目录）
+        const size = Buffer.byteLength(content, 'utf-8');
+        if (out.length > 0 && usedBytes + size > maxBytes) {
+            overflow = { droppedFiles: names.length - out.length, reason: 'bytes', limit: maxBytes };
+            break;
+        }
+        usedBytes += size;
+        out.push([f, content]);
+    }
+    return { files: out, overflow };
+}
+function matchGlob(filename, pattern) {
+    const regex = pattern
+        .replace(/\./g, '\\.')
+        .replace(/\*/g, '.*')
+        .replace(/\{([^}]+)\}/g, (_, alts) => `(${alts.split(',').join('|')})`);
+    return new RegExp(`^${regex}$`).test(filename);
+}
+export function buildPathMappings(vars) {
+    const pkgRoot = getPackageRoot();
+    const evolHome = String(vars['EVOLCORE_HOME'] || resolveRoot());
+    const selfAid = vars['selfAid'] ? String(vars['selfAid']) : '';
+    const currentProject = vars['CURRENT_PROJECT'] ? String(vars['CURRENT_PROJECT']) : '';
+    const mappings = [
+        { prefix: path.join(pkgRoot, 'kits', 'rules'), alias: '$KITS_RULES' },
+        { prefix: path.join(pkgRoot, 'kits', 'templates', 'system-fragments'), alias: '$KITS_FRAGMENTS' },
+        { prefix: path.join(pkgRoot, 'kits', 'templates', 'message-fragments'), alias: '$KITS_MESSAGE_FRAGMENTS' },
+        { prefix: path.join(pkgRoot, 'kits', 'templates'), alias: '$KITS_TEMPLATES' },
+        { prefix: path.join(pkgRoot, 'kits', 'docs'), alias: '$KITS_DOCS' },
+        { prefix: path.join(pkgRoot, 'kits'), alias: '$KITS' },
+        { prefix: pkgRoot, alias: '$PACKAGE_ROOT' },
+    ];
+    if (selfAid) {
+        mappings.push({ prefix: path.join(evolHome, 'agents', selfAid, 'personal'), alias: '$PERSONAL_DIR' });
+        mappings.push({ prefix: path.join(evolHome, 'agents', selfAid, 'relations'), alias: '$RELATIONS_DIR' });
+        mappings.push({ prefix: path.join(evolHome, 'agents', selfAid, 'venues'), alias: '$VENUES_DIR' });
+        mappings.push({ prefix: path.join(evolHome, 'agents', selfAid), alias: '$AGENT_DIR' });
+    }
+    mappings.push({ prefix: evolHome, alias: '$EVOLCORE_HOME' });
+    if (currentProject)
+        mappings.push({ prefix: currentProject, alias: '$CURRENT_PROJECT' });
+    mappings.sort((a, b) => b.prefix.length - a.prefix.length);
+    return mappings;
+}
+export function shortenPath(filePath, mappings) {
+    const normalized = filePath.replace(/\\/g, '/');
+    for (const { prefix, alias } of mappings) {
+        const normalizedPrefix = prefix.replace(/\\/g, '/');
+        if (normalized.startsWith(normalizedPrefix)) {
+            return alias + normalized.slice(normalizedPrefix.length);
+        }
+    }
+    return filePath;
+}

package/dist/eck/message-renderer.js

@@ -0,0 +1,199 @@
+// Message rendering layer: render a batch of sub-messages one-by-one through the
+// message manifest, then assemble the final body fed to the base agent. Shares the
+// manifest-engine primitives with system-prompt rendering, with two key differences:
+//   1. The raw message text {{content}} is injected as a LITERAL in the final step,
+//      never going through template parsing again (otherwise {{...}} inside a user
+//      message would be treated as a template -- garbled at best, injection at worst).
+//   2. Blank lines are preserved (multi-paragraph message bodies must not be squashed).
+import fs from 'fs';
+import path from 'path';
+import { randomUUID } from 'crypto';
+import { isEckSnapshotsEnabled } from '../config-store.js';
+import { eckDebugDir } from '../paths.js';
+import { logger } from '../utils/logger.js';
+import { loadManifest, evaluateWhen, renderTemplate, loadSectionFiles, defaultModeNames, } from './manifest-engine.js';
+const MESSAGE_MANIFEST_FILE = 'eck_message_manifest.json';
+// ── time formatting (per IANA timezone) ──
+function timeParts(epochMs, timeZone, opts) {
+    const d = new Date(epochMs);
+    const p = new Intl.DateTimeFormat('en-US', { ...(timeZone ? { timeZone } : {}), ...opts }).formatToParts(d);
+    const out = {};
+    for (const part of p)
+        out[part.type] = part.value;
+    return out;
+}
+/** "2026-06-04 21:33:07 +08:00" */
+export function formatLocalTime(epochMs, timeZone) {
+    const g = timeParts(epochMs, timeZone, {
+        year: 'numeric', month: '2-digit', day: '2-digit',
+        hour: '2-digit', minute: '2-digit', second: '2-digit', hour12: false,
+    });
+    const hour = g.hour === '24' ? '00' : g.hour; // hour12:false may yield "24" at midnight
+    const off = timeParts(epochMs, timeZone, { timeZoneName: 'longOffset' }).timeZoneName || '';
+    const offset = off.replace(/^GMT/, '') || '+00:00';
+    return `${g.year}-${g.month}-${g.day} ${hour}:${g.minute}:${g.second} ${offset}`;
+}
+// ── single item render ──
+function renderOneItem(item, sessionVars, sessionCache, contentSentinel) {
+    const sections = loadManifest(MESSAGE_MANIFEST_FILE);
+    // 各 modeType 当前激活的 modeName：agent config.render（经 sessionVars.renderModes 透传）
+    // 覆盖 manifest 里标 isDefault 的缺省。详见 docs/observer-insert-design.md 第二部分。
+    const defaults = defaultModeNames(sections);
+    const configured = (sessionVars.renderModes && typeof sessionVars.renderModes === 'object' && !Array.isArray(sessionVars.renderModes))
+        ? sessionVars.renderModes
+        : {};
+    const activeMode = (type) => {
+        const c = configured[type];
+        if (typeof c === 'string' && c)
+            return c;
+        return defaults[type];
+    };
+    const isOwnerHint = item.kind === 'owner-hint';
+    const isHandoff = item.kind === 'handoff';
+    const handoffPreviousSentinel = `\x00ECMSG-HANDOFF-PREV-${randomUUID()}\x00`;
+    // item-level vars: session vars overlaid with this message's own sender/timestamp.
+    const itemVars = {
+        ...sessionVars,
+        peerId: item.peerId ?? sessionVars.peerId,
+        peerName: item.peerName ?? sessionVars.peerName,
+        peerType: item.peerType ?? sessionVars.peerType,
+        peerRole: item.peerRole ?? sessionVars.peerRole,
+        sameDevice: item.sameDevice ?? sessionVars.sameDevice,
+        sameNetwork: item.sameNetwork ?? sessionVars.sameNetwork,
+        sameEgressIp: item.sameEgressIp ?? sessionVars.sameEgressIp,
+        // 入站加密态（仅 aun 有意义；非 aun 渠道为 undefined）。透传原始布尔：
+        // 模板 {{?encrypted=true}}→🔒密文、{{?encrypted=false}}→✉️明文、undefined 两者均落空。
+        // 注意：必须传原始布尔（含 false），不能折成 true|undefined，否则 false 分支永不命中。
+        encrypted: item.encrypted,
+        // 模板引擎不支持数组循环：被 @ 的 AID 预先 join 成串，空则 undefined 使 {{?mentionAids}} 落空。
+        mentionAids: (item.mentionAids && item.mentionAids.length > 0) ? item.mentionAids.join(',') : undefined,
+        now: formatLocalTime(item.timestamp ?? Date.now(), sessionVars.timezone ? String(sessionVars.timezone) : undefined),
+        // 渲染模式命中变量（manifest section 的 when 用它选中唯一模式）
+        renderMode_private: activeMode('private'),
+        renderMode_group: activeMode('group'),
+        renderMode_inject: activeMode('inject'),
+        // owner 插话提示标记 + 信封头字段
+        isOwnerHint,
+        ownerAid: isOwnerHint ? (item.ownerAid ?? undefined) : undefined,
+        injectTime: isOwnerHint
+            ? formatLocalTime(item.injectTime ?? item.timestamp ?? Date.now(), sessionVars.timezone ? String(sessionVars.timezone) : undefined)
+            : undefined,
+        // msg send 跨会话一次性上下文
+        isHandoff,
+        handoffKind: item.handoff?.kind,
+        handoffId: item.handoff?.handoffId,
+        handoffOriginChannel: item.handoff?.origin?.channel,
+        handoffOriginPeerId: item.handoff?.origin?.peerId,
+        handoffOriginThreadId: item.handoff?.origin?.threadId,
+        handoffOriginPeerName: item.handoff?.origin?.peerName,
+        handoffOriginPeerType: item.handoff?.origin?.peerType,
+        handoffOriginRole: item.handoff?.origin?.role,
+        handoffPreviousMessageId: item.handoff?.previousMessageId ?? undefined,
+        handoffPreviousContent: item.handoff ? handoffPreviousSentinel : undefined,
+        handoffReturnPolicy: item.handoff?.returnPolicy,
+        // content held as a per-call random sentinel, swapped back post-render.
+        // Using a UUID means no real message can collide with it.
+        content: contentSentinel,
+    };
+    const out = [];
+    for (const section of sections) {
+        if (section.enabled === false)
+            continue;
+        if (section.loop)
+            continue; // loop 段是批次级包裹，由 renderMessageBody 处理，不参与逐条
+        if (!evaluateWhen(section.when, itemVars))
+            continue;
+        const files = loadSectionFiles(section, itemVars, sessionCache);
+        for (const [, rawContent] of files) {
+            const rendered = section.needsInjection
+                ? renderTemplate(rawContent, itemVars, /* stripBlankLines */ false)
+                : rawContent;
+            // swap the sentinel back to the real message text (literal replace, no parsing).
+            const withContent = rendered
+                .split(contentSentinel).join(item.content)
+                .split(handoffPreviousSentinel).join(item.handoff?.previousContent ?? '');
+            if (withContent.trim())
+                out.push(withContent.replace(/\s+$/, ''));
+        }
+    }
+    // if the manifest produced nothing, fall back to raw text -- never drop a message.
+    return out.length > 0 ? out.join('\n') : item.content;
+}
+/**
+ * Render each sub-message then assemble the final message body.
+ * Also collects all images across items in order, preserving per-item attribution.
+ *
+ * One item -> single render; many (group batch / same-peer merge) -> each carries
+ * its own sender and timestamp.
+ */
+export function renderMessageBody(items, sessionVars, sessionId) {
+    if (!items || items.length === 0)
+        return { body: '', images: [] };
+    // One random sentinel per renderMessageBody call -- impossible for user text to match.
+    const contentSentinel = `\x00ECMSG-${randomUUID()}\x00`;
+    const sessionCache = new Map(); // render-local cache (template files are small & fixed)
+    const allImages = [];
+    for (const item of items) {
+        if (item.images && item.images.length > 0)
+            allImages.push(...item.images);
+    }
+    // 逐条渲染每个 item（自带哨兵，防用户文本里的 {{}} 被二次解析）。
+    const renderedParts = items.map(item => renderOneItem(item, sessionVars, sessionCache, contentSentinel));
+    // 批次包裹层：message manifest 里若有 loop 段（wrapper file + 批次 vars），
+    // 用它包裹逐条结果——wrapper 渲染批次 vars（如 remainingInQueue，从 sessionVars 透传），
+    // {{@loop}} 处字面量填入逐条结果（已渲染完成，不再过模板 → 哨兵天然生效）。
+    const body = wrapBatch(renderedParts, sessionVars, sessionCache) ?? renderedParts.join('\n\n');
+    writeMessageDebug(sessionId, items, body);
+    return { body, images: allImages };
+}
+/**
+ * 若 message manifest 含 loop 段，用其 wrapper 包裹逐条渲染结果。返回包裹后 body，
+ * 无 loop 段则返回 null（调用方回退到 join）。
+ * 逐条结果 renderedParts 已是最终文本，作为字面量填入 wrapper 的 {{@loop}}，不二次解析。
+ */
+function wrapBatch(renderedParts, sessionVars, sessionCache) {
+    const sections = loadManifest(MESSAGE_MANIFEST_FILE);
+    const loopSection = sections.find(s => s.loop && s.enabled !== false && evaluateWhen(s.when, sessionVars));
+    if (!loopSection || !loopSection.loop || !loopSection.file)
+        return null;
+    const wrapperFiles = loadSectionFiles(loopSection, sessionVars, sessionCache);
+    if (wrapperFiles.length === 0)
+        return null;
+    const wrapperTpl = wrapperFiles[0][1];
+    const sep = loopSection.loop.separator ?? '\n\n';
+    const loopResult = renderedParts.join(sep);
+    // wrapper 渲染批次 vars，{{@loop}} 用哨兵占位后字面量替换回 loopResult（避免逐条结果被二次解析）。
+    const LOOP_SENTINEL = '\x00ECLOOP\x00';
+    const wrapperWithSentinel = wrapperTpl.includes('{{@loop}}')
+        ? wrapperTpl.split('{{@loop}}').join(LOOP_SENTINEL)
+        : wrapperTpl + '\n' + LOOP_SENTINEL;
+    const rendered = renderTemplate(wrapperWithSentinel, sessionVars, /* stripBlankLines */ false);
+    return rendered.split(LOOP_SENTINEL).join(loopResult);
+}
+// ── Debug ──
+function writeMessageDebug(sessionId, items, body) {
+    if (!isEckSnapshotsEnabled())
+        return;
+    try {
+        const ts = new Date().toISOString().replace(/[T:.]/g, '-').slice(0, 19);
+        const dir = eckDebugDir();
+        fs.mkdirSync(dir, { recursive: true });
+        const out = [
+            `# Message Render`,
+            `- sessionId: ${sessionId}`,
+            `- items: ${items.length}`,
+            `- images: ${items.reduce((n, i) => n + (i.images?.length ?? 0), 0)}`,
+            ``,
+            `## Rendered body`,
+            ``,
+            body,
+        ].join('\n');
+        fs.writeFile(path.join(dir, `msg-render-${ts}.md`), out, (error) => {
+            if (error)
+                logger.debug(`[MessageRenderer] debug write failed: ${error.message}`);
+        });
+    }
+    catch (e) {
+        logger.debug(`[MessageRenderer] debug write failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}

package/dist/eck/rules-loader.js

@@ -0,0 +1,28 @@
+import fs from 'fs';
+import path from 'path';
+import { kitsRulesDir } from '../paths.js';
+let _cachedRules = null;
+export function loadRulesForInjection() {
+    if (_cachedRules !== null)
+        return _cachedRules;
+    const rulesDir = kitsRulesDir();
+    if (!fs.existsSync(rulesDir)) {
+        _cachedRules = '';
+        return '';
+    }
+    const files = fs.readdirSync(rulesDir)
+        .filter(f => f.endsWith('.md'))
+        .sort();
+    const parts = [];
+    for (const file of files) {
+        try {
+            parts.push(fs.readFileSync(path.join(rulesDir, file), 'utf-8'));
+        }
+        catch { /* skip unreadable files */ }
+    }
+    _cachedRules = parts.join('\n\n');
+    return _cachedRules;
+}
+export function invalidateRulesCache() {
+    _cachedRules = null;
+}