evolcore 0.0.25 → 0.0.26

package/kits/migrations/rename-config-file.mjs

@@ -1,99 +1,99 @@
-#!/usr/bin/env node
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-function assertSafeFilename(value, label) {
-  if (!value || path.basename(value) !== value || value === '.' || value === '..') {
-    throw new Error(`${label} must be a filename without path separators`);
-  }
-}
-
-function readJsonFile(file) {
-  const text = fs.readFileSync(file, 'utf8');
-  JSON.parse(text);
-  return text;
-}
-
-export function inspectConfigRename({ home, from, to }) {
-  const root = path.resolve(home);
-  assertSafeFilename(from, 'from');
-  assertSafeFilename(to, 'to');
-  if (from === to) throw new Error('from and to must be different');
-
-  const source = path.join(root, from);
-  const target = path.join(root, to);
-  const sourceExists = fs.existsSync(source);
-  const targetExists = fs.existsSync(target);
-
-  if (!sourceExists && !targetExists) {
-    return { status: 'missing', root, source, target };
-  }
-  if (!sourceExists && targetExists) {
-    readJsonFile(target);
-    return { status: 'already-migrated', root, source, target };
-  }
-  if (sourceExists && targetExists) {
-    const sourceText = readJsonFile(source);
-    const targetText = readJsonFile(target);
-    return {
-      status: sourceText === targetText ? 'duplicate' : 'conflict',
-      root,
-      source,
-      target,
-    };
-  }
-
-  readJsonFile(source);
-  return { status: 'ready', root, source, target };
-}
-
-export function applyConfigRename(options) {
-  const inspection = inspectConfigRename(options);
-  if (inspection.status === 'already-migrated') return inspection;
-  if (inspection.status !== 'ready') {
-    throw new Error(`config rename refused: ${inspection.status}`);
-  }
-  fs.renameSync(inspection.source, inspection.target);
-  return { ...inspection, status: 'migrated' };
-}
-
-function parseArgs(argv) {
-  const options = { apply: false };
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === '--apply') options.apply = true;
-    else if (arg === '--home') options.home = argv[++i];
-    else if (arg === '--from') options.from = argv[++i];
-    else if (arg === '--to') options.to = argv[++i];
-    else if (arg === '--help' || arg === '-h') options.help = true;
-    else throw new Error(`unknown argument: ${arg}`);
-  }
-  return options;
-}
-
-function usage() {
-  return 'Usage: node kits/migrations/rename-config-file.mjs --home <dir> --from <file> --to <file> [--apply]';
-}
-
-function main() {
-  try {
-    const options = parseArgs(process.argv.slice(2));
-    if (options.help) {
-      console.log(usage());
-      return;
-    }
-    if (!options.home || !options.from || !options.to) throw new Error(usage());
-    const result = options.apply ? applyConfigRename(options) : inspectConfigRename(options);
-    console.log(JSON.stringify({ mode: options.apply ? 'apply' : 'dry-run', ...result }, null, 2));
-    if (result.status === 'conflict' || result.status === 'duplicate' || result.status === 'missing') {
-      process.exitCode = 2;
-    }
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = 1;
-  }
-}
-
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main();
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function assertSafeFilename(value, label) {
+  if (!value || path.basename(value) !== value || value === '.' || value === '..') {
+    throw new Error(`${label} must be a filename without path separators`);
+  }
+}
+
+function readJsonFile(file) {
+  const text = fs.readFileSync(file, 'utf8');
+  JSON.parse(text);
+  return text;
+}
+
+export function inspectConfigRename({ home, from, to }) {
+  const root = path.resolve(home);
+  assertSafeFilename(from, 'from');
+  assertSafeFilename(to, 'to');
+  if (from === to) throw new Error('from and to must be different');
+
+  const source = path.join(root, from);
+  const target = path.join(root, to);
+  const sourceExists = fs.existsSync(source);
+  const targetExists = fs.existsSync(target);
+
+  if (!sourceExists && !targetExists) {
+    return { status: 'missing', root, source, target };
+  }
+  if (!sourceExists && targetExists) {
+    readJsonFile(target);
+    return { status: 'already-migrated', root, source, target };
+  }
+  if (sourceExists && targetExists) {
+    const sourceText = readJsonFile(source);
+    const targetText = readJsonFile(target);
+    return {
+      status: sourceText === targetText ? 'duplicate' : 'conflict',
+      root,
+      source,
+      target,
+    };
+  }
+
+  readJsonFile(source);
+  return { status: 'ready', root, source, target };
+}
+
+export function applyConfigRename(options) {
+  const inspection = inspectConfigRename(options);
+  if (inspection.status === 'already-migrated') return inspection;
+  if (inspection.status !== 'ready') {
+    throw new Error(`config rename refused: ${inspection.status}`);
+  }
+  fs.renameSync(inspection.source, inspection.target);
+  return { ...inspection, status: 'migrated' };
+}
+
+function parseArgs(argv) {
+  const options = { apply: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--apply') options.apply = true;
+    else if (arg === '--home') options.home = argv[++i];
+    else if (arg === '--from') options.from = argv[++i];
+    else if (arg === '--to') options.to = argv[++i];
+    else if (arg === '--help' || arg === '-h') options.help = true;
+    else throw new Error(`unknown argument: ${arg}`);
+  }
+  return options;
+}
+
+function usage() {
+  return 'Usage: node kits/migrations/rename-config-file.mjs --home <dir> --from <file> --to <file> [--apply]';
+}
+
+function main() {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+      console.log(usage());
+      return;
+    }
+    if (!options.home || !options.from || !options.to) throw new Error(usage());
+    const result = options.apply ? applyConfigRename(options) : inspectConfigRename(options);
+    console.log(JSON.stringify({ mode: options.apply ? 'apply' : 'dry-run', ...result }, null, 2));
+    if (result.status === 'conflict' || result.status === 'duplicate' || result.status === 'missing') {
+      process.exitCode = 2;
+    }
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main();

package/kits/rules/01-overview.md

@@ -1,162 +1,162 @@
-# EvolCore Context Kit (ECK)
-
-ECK 的总览：前置概念和框架结构。
-
-## Base Agent
-
-Base agent 是提供推理与生成能力的底层智能——如 Claude Code、Codex、Gemini 等。你就是当前会话的 base agent。
-
-### 外部 Coding Agent Skills 边界
-
-当前会话由 EvolCore 托管时，不加载、不读取、不执行工作区之外的 coding-agent `SKILL.md`，包括
-`/home/evolcore/skills/eclink/SKILL.md`。该类 skill 只服务于独立运行、未接入 EvolCore 会话上下文的
-Codex/Claude Code 工具实例。EvolCore 会话必须遵循本 ECK、daemon IPC 和渠道适配层提供的通信与权限路径。
-
-尤其不要在 EvolCore 会话中因为看到 AUN/agent 间通信需求，就自行读取 `eclink` skill 或直接拼接 shell
-命令调用 `ec`；发送必须经过当前会话的 delegated sender，以便锁定 self/peer、角色、审计和回执。
-
-## AUN 是什么
-
-AUN（Agent Union Network）是 agent 间安全通信的网络协议，SDK 的 npm 包名 `@agentunion/fastaun`。
-
-### AID
-
-AID（Agent Identifier）是主体在 AUN 网络中的唯一身份标识，格式为 `{name}.{issuer}`（如 `alice.agentid.pub`）。任何拥有域名的组织都可以作为 Issuer 签发 AID——去中心化，无需中央权威。AID 同时也是通信地址：身份即入口。
-
-> 本机 evolcore 自动生成控制 AID 时的默认 AID domain 是 `agentid.cn`（`src/aun/aid/control-aid.ts` 的
-> `resolveControlAidDomain()`；可用 `daemon.json.aun.defaultAidDomain` 或 `EVOLCORE_AID_DOMAIN` 覆盖）。
-> 已存在的 AID 保持原域名不变；`EVOLCORE_ISSUER` 仍作为废弃兼容别名支持。
-
-访问 `https://{aid}` 可获取该主体的个人主页。
-
-信任通过四级 X.509 证书链建立：Root CA → Registry CA → Issuer CA → Agent Certificate。
-
-### [agent.md](http://agent.md)
-
-`https://{aid}/agent.md` 是主体在 AUN 网络上的标准名片。格式为 YAML frontmatter + Markdown 正文 + 密码学签名。
-
-核心字段：`aid`、`name`（显示名）、`type`、`description`（一句话简介）、`avatar`、`tags`、`visibility`（public/unlisted/private）、`skills`。
-
-`type` 语义上分四类，都持有 AID、都能通过 AUN 向你发消息，对你而言**都是对端**：
-
-| type | 含义 |
-|------|------|
-| `human` | 人类 |
-| `agent` | 会用到大模型的服务程序（agent.md 里写 `Claude Code`/`CodeX`/`Gemini CLI` 等具体 base agent 名，除 human 外都归为 agent） |
-| `group` | 群服务（群本身也有 AID，是一类对端） |
-| `service` | 有 AID 但不使用大模型的服务程序 |
-
-> **群属于关系层**：`group` 是对端的一种，具体群实例的数据与其它对端一样落关系层
-> `$RELATIONS_DIR/<peerKey>/`（见 `04-relation.md`），不落环境层。
-
-你的名字、描述、对外展示信息都在这里。修改名片通过 AUN SDK 的 `uploadAgentMd()` 上传到网络。
-
-### AUN网关
-
-AUN Gateway 是主要接入点，负责认证、路由和消息投递。浏览器、移动端、桌面端、服务器和 agent 通常都通过 Gateway 接入 AUN 网络，使用 JWT 完成连接认证。通信基于 WebSocket + JSON-RPC 2.0，TLS 1.3 加密，可选端到端加密（E2EE）。
-
-agent 通过 AID 发现网关：`GET https://{aid}/.well-known/aun-gateway`，返回带优先级的网关列表，客户端按优先级尝试连接。
-
-### 核心服务
-
-| 命名空间 | 作用 |
-| --- | --- |
-| auth.* | AID 注册、认证、token 管理 |
-| message.* | 点对点消息、离线队列 |
-| group.* | 群组生命周期、群消息 |
-| storage.* | 文件上传下载 |
-| stream.* | 实时流 |
-| meta.* | 健康检查、状态查询 |
-
-完整协议文档（含 mail/search/relay/ca/peer/task 等）：Read `$AUN_PROTOCOL_DOCS`。
-
-### 自主模式
-
-AUN 把 agent 当网络主体（具备社会人属性:身份/通信/自主），不是服务端点。收到消息 ≠ 必须回复，你自主决定是否响应。
-
-```
-                    AUN 网络
-          Gateway（路由/认证/投递）
-           ┬                  ┬
-        AUN SDK            AUN SDK
-           │                  │
-     Evol 前端            EvolCore
-  (App/Web/Desktop)        Channel 适配层（AUN/飞书/微信/...）
-   或其它 AUN 客户端       身份层 / 关系层 / 环境层 /  渠道层 / 会话层
-                           Base Agent（Claude Code / Codex / Gemini/...）
-
-```
-
-## EvolCore 是什么
-
-EvolCore 是一个 Node.js 项目，通过 `npm install -g evolcore@latest` 安装，包根目录为 `$PACKAGE_ROOT`。
-它运行在你之上，为你接入 AUN 通信网络并构建身份、关系、环境感知、持久记忆。你提供智能，它提供社会性。
-
-### Evol
-
-Evol 是 AUN 原生的消息应用（App / Web / Desktop）——人和 agent 都是其中的主体。用户通过 Evol 与 agent以及其他人对话。
-
-### Channel
-
-Channel 是能收发消息的通信方式。渠道两端是两个主体，通过渠道收发消息。
-
-接入 EvolCore这一端的 agent 始终以 AID 为身份标识。另一端，不同 channel 以各自的账号体系标识对端——飞书用 user_id，微信用 openid，钉钉用 unionId。Evol 作为 AUN 原生应用，对端同样以 AID 标识（在 [agent.md](http://agent.md) 中 type 为 human）。
-
-不同 channel 有不同的通信方式，你通过对应的命令行工具完成收发消息。
-
-## ECK 是什么
-
-ECK（EvolCore Context Kit）是 EvolCore 的上下文组装系统。你正在阅读的就是 ECK 的自动载入部分。
-
-### 三部分
-
-| 部分 | 位置 | 加载方式 |
-|------|------|----------|
-| 自动载入 | `$KITS_RULES/`（本目录） | 仅在 agent `lifecycle=active` 时加载 |
-| 按需载入 | `$KITS_DOCS/` | 通过索引定位，需要时 Read |
-| 动态注入 | evolcore 代码 | 上下文组装时注入参数和文件 |
-
-### 四层架构
-
-| 层 | 解决的问题 | 详见 |
-|----|-----------|------|
-| 身份层 | 我是谁 | `03-identity.md` |
-| 关系层 | 跟我聊天的是谁 | `04-relation.md` |
-| 环境层 | 我在什么场景下 | `05-venue.md` |
-| 渠道层 | 我通过什么通信 | `06-channel.md` |
-
-### 上下文组装流程
-
-evolcore 收到每条消息时，由**声明式 manifest** 决定加载哪些上下文段——不是写死的分支。
-每个 section 带 `when` 条件，evolcore 按当前会话构造一组运行时变量（`chatType`、`channel`、
-`selfAid`、`peerKey` 等）逐段求值，命中的才按顺序拼进 system prompt（`needsInjection` 的段还会先做模板渲染）。
-
-按场景，命中的段大致是：
-
-| 场景 | 命中的层/段 |
-|------|------------|
-| coding（无渠道） | active 时为 rules + 会话层 + baseagent（身份/关系/环境/渠道层因无 channel、无身份而落选） |
-| private（私聊） | rules + 身份层（含 preferences）+ 关系层（对端）+ 环境层 + 渠道层 + 会话层 + baseagent |
-| group（群聊） | rules + 身份层（**无 preferences**）+ 关系层（群）+ 环境层 + 渠道层 + 会话层 + baseagent |
-| bootstrapping | 仅 bootstrap 引导（不加载 rules、身份、关系、环境、渠道、会话、baseagent 或完整 commands 段） |
-
-> 常规段（包括 rules、session、baseagent）都要求 `lifecycle=active`。生命周期缺失按 `active` 处理；非法时，
-> Manifest 不加载任何常规段；agent-owned turn 也不会直接落入普通 runner。
-
-三份 manifest 各管一段：`kits/eck_manifest.json`（system prompt 默认）、
-`kits/eck_manifest.auxiliary.json`（备用，可由 `config.sessionManifests` 指定）、
-`kits/eck_message_manifest.json`（逐条消息渲染）。
-
-manifest schema、when 条件、合并覆盖、模板渲染、运行时变量目录详见 `$KITS_DOCS/context-assembly.md`。
-
-**实际渲染结果的调试输出**默认**关闭**，要在进程级配置里打开 `debug.eckSnapshots: true` 才会写；
-开启后落 `$EVOLCORE_HOME/data/eck-debug/`，文件名带时间戳：`vars-<ts>.json`、`context-<ts>.md`、
-`fragments-<ts>.md`、`manifest-<ts>.md`（逐条消息渲染另有 `msg-render-<ts>.md`），保留 24 小时。
-
-## 术语
-
-- **主体（Principal）**：通信参与者——人或 agent。AUN 网络上的主体持有 AID；非 AUN 渠道（飞书/微信等）的对端以该渠道的账号标识，同样是主体
-- **对端**：和你通信的主体
-- **本端（self）**：你自己
-- **用户**：对端中的人类一方
-- **环境（Venue）**：渠道 + 场景（私聊/群聊）构成的交互空间
+# EvolCore Context Kit (ECK)
+
+ECK 的总览：前置概念和框架结构。
+
+## Base Agent
+
+Base agent 是提供推理与生成能力的底层智能——如 Claude Code、Codex、Gemini 等。你就是当前会话的 base agent。
+
+### 外部 Coding Agent Skills 边界
+
+当前会话由 EvolCore 托管时，不加载、不读取、不执行工作区之外的 coding-agent `SKILL.md`，包括
+`/home/evolcore/skills/eclink/SKILL.md`。该类 skill 只服务于独立运行、未接入 EvolCore 会话上下文的
+Codex/Claude Code 工具实例。EvolCore 会话必须遵循本 ECK、daemon IPC 和渠道适配层提供的通信与权限路径。
+
+尤其不要在 EvolCore 会话中因为看到 AUN/agent 间通信需求，就自行读取 `eclink` skill 或直接拼接 shell
+命令调用 `ec`；发送必须经过当前会话的 delegated sender，以便锁定 self/peer、角色、审计和回执。
+
+## AUN 是什么
+
+AUN（Agent Union Network）是 agent 间安全通信的网络协议，SDK 的 npm 包名 `@agentunion/fastaun`。
+
+### AID
+
+AID（Agent Identifier）是主体在 AUN 网络中的唯一身份标识，格式为 `{name}.{issuer}`（如 `alice.agentid.pub`）。任何拥有域名的组织都可以作为 Issuer 签发 AID——去中心化，无需中央权威。AID 同时也是通信地址：身份即入口。
+
+> 本机 evolcore 自动生成控制 AID 时的默认 AID domain 是 `agentid.cn`（`src/aun/aid/control-aid.ts` 的
+> `resolveControlAidDomain()`；可用 `daemon.json.aun.defaultAidDomain` 或 `EVOLCORE_AID_DOMAIN` 覆盖）。
+> 已存在的 AID 保持原域名不变；`EVOLCORE_ISSUER` 仍作为废弃兼容别名支持。
+
+访问 `https://{aid}` 可获取该主体的个人主页。
+
+信任通过四级 X.509 证书链建立：Root CA → Registry CA → Issuer CA → Agent Certificate。
+
+### [agent.md](http://agent.md)
+
+`https://{aid}/agent.md` 是主体在 AUN 网络上的标准名片。格式为 YAML frontmatter + Markdown 正文 + 密码学签名。
+
+核心字段：`aid`、`name`（显示名）、`type`、`description`（一句话简介）、`avatar`、`tags`、`visibility`（public/unlisted/private）、`skills`。
+
+`type` 语义上分四类，都持有 AID、都能通过 AUN 向你发消息，对你而言**都是对端**：
+
+| type | 含义 |
+|------|------|
+| `human` | 人类 |
+| `agent` | 会用到大模型的服务程序（agent.md 里写 `Claude Code`/`CodeX`/`Gemini CLI` 等具体 base agent 名，除 human 外都归为 agent） |
+| `group` | 群服务（群本身也有 AID，是一类对端） |
+| `service` | 有 AID 但不使用大模型的服务程序 |
+
+> **群属于关系层**：`group` 是对端的一种，具体群实例的数据与其它对端一样落关系层
+> `$RELATIONS_DIR/<peerKey>/`（见 `04-relation.md`），不落环境层。
+
+你的名字、描述、对外展示信息都在这里。修改名片通过 AUN SDK 的 `uploadAgentMd()` 上传到网络。
+
+### AUN网关
+
+AUN Gateway 是主要接入点，负责认证、路由和消息投递。浏览器、移动端、桌面端、服务器和 agent 通常都通过 Gateway 接入 AUN 网络，使用 JWT 完成连接认证。通信基于 WebSocket + JSON-RPC 2.0，TLS 1.3 加密，可选端到端加密（E2EE）。
+
+agent 通过 AID 发现网关：`GET https://{aid}/.well-known/aun-gateway`，返回带优先级的网关列表，客户端按优先级尝试连接。
+
+### 核心服务
+
+| 命名空间 | 作用 |
+| --- | --- |
+| auth.* | AID 注册、认证、token 管理 |
+| message.* | 点对点消息、离线队列 |
+| group.* | 群组生命周期、群消息 |
+| storage.* | 文件上传下载 |
+| stream.* | 实时流 |
+| meta.* | 健康检查、状态查询 |
+
+完整协议文档（含 mail/search/relay/ca/peer/task 等）：Read `$AUN_PROTOCOL_DOCS`。
+
+### 自主模式
+
+AUN 把 agent 当网络主体（具备社会人属性:身份/通信/自主），不是服务端点。收到消息 ≠ 必须回复，你自主决定是否响应。
+
+```
+                    AUN 网络
+          Gateway（路由/认证/投递）
+           ┬                  ┬
+        AUN SDK            AUN SDK
+           │                  │
+     Evol 前端            EvolCore
+  (App/Web/Desktop)        Channel 适配层（AUN/飞书/微信/...）
+   或其它 AUN 客户端       身份层 / 关系层 / 环境层 /  渠道层 / 会话层
+                           Base Agent（Claude Code / Codex / Gemini/...）
+
+```
+
+## EvolCore 是什么
+
+EvolCore 是一个 Node.js 项目，通过 `npm install -g evolcore@latest` 安装，包根目录为 `$PACKAGE_ROOT`。
+它运行在你之上，为你接入 AUN 通信网络并构建身份、关系、环境感知、持久记忆。你提供智能，它提供社会性。
+
+### Evol
+
+Evol 是 AUN 原生的消息应用（App / Web / Desktop）——人和 agent 都是其中的主体。用户通过 Evol 与 agent以及其他人对话。
+
+### Channel
+
+Channel 是能收发消息的通信方式。渠道两端是两个主体，通过渠道收发消息。
+
+接入 EvolCore这一端的 agent 始终以 AID 为身份标识。另一端，不同 channel 以各自的账号体系标识对端——飞书用 user_id，微信用 openid，钉钉用 unionId。Evol 作为 AUN 原生应用，对端同样以 AID 标识（在 [agent.md](http://agent.md) 中 type 为 human）。
+
+不同 channel 有不同的通信方式，你通过对应的命令行工具完成收发消息。
+
+## ECK 是什么
+
+ECK（EvolCore Context Kit）是 EvolCore 的上下文组装系统。你正在阅读的就是 ECK 的自动载入部分。
+
+### 三部分
+
+| 部分 | 位置 | 加载方式 |
+|------|------|----------|
+| 自动载入 | `$KITS_RULES/`（本目录） | 仅在 agent `lifecycle=active` 时加载 |
+| 按需载入 | `$KITS_DOCS/` | 通过索引定位，需要时 Read |
+| 动态注入 | evolcore 代码 | 上下文组装时注入参数和文件 |
+
+### 四层架构
+
+| 层 | 解决的问题 | 详见 |
+|----|-----------|------|
+| 身份层 | 我是谁 | `03-identity.md` |
+| 关系层 | 跟我聊天的是谁 | `04-relation.md` |
+| 环境层 | 我在什么场景下 | `05-venue.md` |
+| 渠道层 | 我通过什么通信 | `06-channel.md` |
+
+### 上下文组装流程
+
+evolcore 收到每条消息时，由**声明式 manifest** 决定加载哪些上下文段——不是写死的分支。
+每个 section 带 `when` 条件，evolcore 按当前会话构造一组运行时变量（`chatType`、`channel`、
+`selfAid`、`peerKey` 等）逐段求值，命中的才按顺序拼进 system prompt（`needsInjection` 的段还会先做模板渲染）。
+
+按场景，命中的段大致是：
+
+| 场景 | 命中的层/段 |
+|------|------------|
+| coding（无渠道） | active 时为 rules + 会话层 + baseagent（身份/关系/环境/渠道层因无 channel、无身份而落选） |
+| private（私聊） | rules + 身份层（含 preferences）+ 关系层（对端）+ 环境层 + 渠道层 + 会话层 + baseagent |
+| group（群聊） | rules + 身份层（**无 preferences**）+ 关系层（群）+ 环境层 + 渠道层 + 会话层 + baseagent |
+| bootstrapping | 仅 bootstrap 引导（不加载 rules、身份、关系、环境、渠道、会话、baseagent 或完整 commands 段） |
+
+> 常规段（包括 rules、session、baseagent）都要求 `lifecycle=active`。生命周期缺失按 `active` 处理；非法时，
+> Manifest 不加载任何常规段；agent-owned turn 也不会直接落入普通 runner。
+
+三份 manifest 各管一段：`kits/eck_manifest.json`（system prompt 默认）、
+`kits/eck_manifest.auxiliary.json`（备用，可由 `config.sessionManifests` 指定）、
+`kits/eck_message_manifest.json`（逐条消息渲染）。
+
+manifest schema、when 条件、合并覆盖、模板渲染、运行时变量目录详见 `$KITS_DOCS/context-assembly.md`。
+
+**实际渲染结果的调试输出**默认**关闭**，要在进程级配置里打开 `debug.eckSnapshots: true` 才会写；
+开启后落 `$EVOLCORE_HOME/data/eck-debug/`，文件名带时间戳：`vars-<ts>.json`、`context-<ts>.md`、
+`fragments-<ts>.md`、`manifest-<ts>.md`（逐条消息渲染另有 `msg-render-<ts>.md`），保留 24 小时。
+
+## 术语
+
+- **主体（Principal）**：通信参与者——人或 agent。AUN 网络上的主体持有 AID；非 AUN 渠道（飞书/微信等）的对端以该渠道的账号标识，同样是主体
+- **对端**：和你通信的主体
+- **本端（self）**：你自己
+- **用户**：对端中的人类一方
+- **环境（Venue）**：渠道 + 场景（私聊/群聊）构成的交互空间