evolcore 0.0.1 → 0.0.3

package/kits/migrations/migrate-role-config-v5.mjs

@@ -0,0 +1,346 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import Ajv from 'ajv';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_DIR = path.resolve(SCRIPT_DIR, '..', 'schemas');
+const BUILTIN_ROLES = ['owner', 'admin', 'member', 'visitor'];
+const MANAGEMENT_ROLES = new Set(['owner', 'admin']);
+
+function parseArgs(argv) {
+  const options = { apply: false, json: false, home: undefined };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--apply') options.apply = true;
+    else if (arg === '--json') options.json = true;
+    else if (arg === '--home') options.home = argv[++i];
+    else if (arg === '--help' || arg === '-h') options.help = true;
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+  return options;
+}
+
+function resolveHome(explicit) {
+  return path.resolve(explicit || process.env.EVOLCORE_HOME || path.join(os.homedir(), '.evolcore'));
+}
+
+function loadValidators() {
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  const load = name => JSON.parse(fs.readFileSync(path.join(SCHEMA_DIR, name), 'utf8'));
+  return {
+    agent: ajv.compile(load('agent-config.schema.5.json')),
+    registry: ajv.compile(load('role-registry.schema.1.json')),
+    role: ajv.compile(load('role-config.schema.1.json')),
+  };
+}
+
+function readJson(file) {
+  const text = fs.readFileSync(file, 'utf8');
+  return { value: JSON.parse(text), text };
+}
+
+function isRecord(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isValidAid(name) {
+  const labels = name.split('.');
+  return labels.length >= 3 && labels.every(label => /^[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/.test(label));
+}
+
+function validateOrThrow(validate, value, file) {
+  if (validate(value)) return;
+  const detail = (validate.errors ?? []).map(error => `${error.instancePath || '/'} ${error.message}`).join('; ');
+  throw new Error(`${file}: ${detail}`);
+}
+
+function validateRoleOrThrow(validate, value, file) {
+  validateOrThrow(validate, value, file);
+  for (const [field, permission] of Object.entries(value.permissions ?? {})) {
+    if (!isRecord(permission)) continue;
+    if (Array.isArray(permission.allowedValues) && !permission.allowedValues.includes(permission.default)) {
+      throw new Error(`${file}: permissions.${field}.default must be included in allowedValues`);
+    }
+    if (Array.isArray(permission.allowedModels)
+      && typeof permission.default === 'string'
+      && !permission.allowedModels.some(pattern => wildcardMatch(pattern, permission.default))) {
+      throw new Error(`${file}: permissions.${field}.default must be allowed by allowedModels`);
+    }
+  }
+}
+
+function wildcardMatch(pattern, value) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+  return new RegExp(`^${escaped}$`).test(value);
+}
+
+function change(file, kind, before, value) {
+  const after = `${JSON.stringify(value, null, 2)}\n`;
+  return before === after ? null : { file, kind, before, after };
+}
+
+function appendChange(changes, file, kind, before, value) {
+  const item = change(file, kind, before, value);
+  if (!item) return false;
+  changes.push(item);
+  return true;
+}
+
+function planMigration(home) {
+  const validators = loadValidators();
+  const agentsRoot = path.join(home, 'agents');
+  if (!fs.existsSync(agentsRoot)) return { home, changes: [], summary: { agentsScanned: 0, agentsMigrated: 0, rolesWritten: 0 } };
+  const changes = [];
+  const summary = { agentsScanned: 0, agentsMigrated: 0, rolesWritten: 0 };
+
+  for (const entry of fs.readdirSync(agentsRoot, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory() || !isValidAid(entry.name)) continue;
+    const agentFile = path.join(agentsRoot, entry.name, 'config.json');
+    if (!fs.existsSync(agentFile)) continue;
+    summary.agentsScanned += 1;
+    const { value: input, text: agentText } = readJson(agentFile);
+    if (!isRecord(input)) throw new Error(`${agentFile}: Agent config must be an object`);
+    if (typeof input.$schema_version === 'number' && input.$schema_version > 5) {
+      throw new Error(`${agentFile}: unsupported future Agent schema version ${input.$schema_version}`);
+    }
+
+    const rolesDir = path.join(agentsRoot, entry.name, 'roles');
+    const registryFile = path.join(rolesDir, 'index.json');
+    if (fs.existsSync(registryFile) && input.roles !== undefined) {
+      throw new Error(`${agentFile}: both config.roles and roles/index.json exist; resolve the ambiguous role source before migration`);
+    }
+    if (input.$schema_version === 5 && input.roles === undefined && fs.existsSync(registryFile)) continue;
+
+    const policy = isRecord(input.roles) ? input.roles : {};
+    const definitions = isRecord(policy.definitions) ? policy.definitions : {};
+    for (const roleId of Object.keys(definitions)) {
+      if (!/^[a-z0-9_-]+$/.test(roleId) || MANAGEMENT_ROLES.has(roleId)) {
+        throw new Error(`${agentFile}: invalid role id ${JSON.stringify(roleId)}`);
+      }
+    }
+    const roleIds = [...new Set([...BUILTIN_ROLES, ...Object.keys(definitions)])];
+    const defaultRoles = {
+      private: policy.defaultRoles?.private ?? null,
+      group: policy.defaultRoles?.group ?? null,
+    };
+    for (const scene of ['private', 'group']) {
+      const selected = defaultRoles[scene];
+      if (selected !== null && (MANAGEMENT_ROLES.has(selected) || !roleIds.includes(selected))) {
+        throw new Error(`${agentFile}: roles.defaultRoles.${scene} references an invalid role`);
+      }
+    }
+    const registry = { $schema_version: 1, roles: roleIds, defaultRoles };
+    validateOrThrow(validators.registry, registry, registryFile);
+
+    const relationsDir = path.join(agentsRoot, entry.name, 'relations');
+    if (fs.existsSync(relationsDir)) {
+      const visit = dir => {
+        for (const relationEntry of fs.readdirSync(dir, { withFileTypes: true })) {
+          const full = path.join(dir, relationEntry.name);
+          if (relationEntry.isDirectory()) visit(full);
+          else if (relationEntry.isFile() && relationEntry.name === 'config.json') {
+            const relation = readJson(full).value;
+            if (relation.role !== undefined && relation.role !== null
+              && (MANAGEMENT_ROLES.has(relation.role) || !roleIds.includes(relation.role))) {
+              throw new Error(`${full}: role references an invalid or unregistered role`);
+            }
+          }
+        }
+      };
+      visit(relationsDir);
+    }
+
+    const existingRegistry = fs.existsSync(registryFile) ? fs.readFileSync(registryFile, 'utf8') : null;
+    appendChange(changes, registryFile, 'role-registry', existingRegistry, registry);
+    for (const [roleId, definition] of Object.entries(definitions)) {
+      const roleFile = path.join(rolesDir, `${roleId}.json`);
+      const roleValue = { $schema_version: 1, ...definition };
+      validateRoleOrThrow(validators.role, roleValue, roleFile);
+      if (appendChange(changes, roleFile, 'role-config', fs.existsSync(roleFile) ? fs.readFileSync(roleFile, 'utf8') : null, roleValue)) {
+        summary.rolesWritten += 1;
+      }
+    }
+
+    const output = { ...input, $schema_version: 5 };
+    delete output.roles;
+    validateOrThrow(validators.agent, output, agentFile);
+    appendChange(changes, agentFile, 'agent', agentText, output);
+    summary.agentsMigrated += 1;
+  }
+  return { home, changes, summary };
+}
+
+function assertDaemonStopped(home) {
+  const candidates = [];
+  const pidFile = path.join(home, 'daemon.pid');
+  if (fs.existsSync(pidFile)) {
+    candidates.push({ pid: Number(fs.readFileSync(pidFile, 'utf8').trim()), source: pidFile });
+  }
+  const instanceDir = path.join(home, 'data', 'instance');
+  if (fs.existsSync(instanceDir)) {
+    for (const name of fs.readdirSync(instanceDir)) {
+      if (!/^main-\d+\.json$/.test(name)) continue;
+      const file = path.join(instanceDir, name);
+      try { candidates.push({ pid: Number(JSON.parse(fs.readFileSync(file, 'utf8'))?.pid), source: file }); } catch {}
+    }
+  }
+  for (const { pid, source } of candidates) {
+    if (!Number.isInteger(pid) || pid <= 0) continue;
+    try { process.kill(pid, 0); } catch (error) {
+      if (error?.code === 'ESRCH') continue;
+      if (error?.code !== 'EPERM') throw error;
+    }
+    throw new Error(`EvolCore daemon appears to be running (pid=${pid}, record=${source}); stop it before migration`);
+  }
+}
+
+function acquireMigrationLock(home) {
+  const lockDir = path.join(home, 'data', 'role-v5-migration.lock');
+  const ownerFile = path.join(lockDir, 'owner.json');
+  fs.mkdirSync(path.dirname(lockDir), { recursive: true });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      fs.mkdirSync(lockDir);
+      fs.writeFileSync(ownerFile, `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }, null, 2)}\n`);
+      return () => fs.rmSync(lockDir, { recursive: true, force: true });
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      let ownerPid;
+      try { ownerPid = Number(JSON.parse(fs.readFileSync(ownerFile, 'utf8'))?.pid); }
+      catch { throw new Error(`Role config migration lock is unreadable: ${lockDir}`); }
+      if (Number.isInteger(ownerPid) && ownerPid > 0) {
+        try {
+          process.kill(ownerPid, 0);
+          throw new Error(`Another role config migration is already running (pid=${ownerPid})`);
+        } catch (ownerError) {
+          if (ownerError?.code === 'EPERM') throw new Error(`Another role config migration is already running (pid=${ownerPid})`);
+          if (ownerError?.code !== 'ESRCH') throw ownerError;
+        }
+      }
+      fs.rmSync(lockDir, { recursive: true, force: true });
+    }
+  }
+  throw new Error(`Unable to acquire role config migration lock: ${lockDir}`);
+}
+
+function atomicWrite(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const mode = fs.existsSync(file) ? fs.statSync(file).mode & 0o777 : 0o600;
+  const temp = `${file}.role-v5-${process.pid}-${Math.random().toString(16).slice(2)}.tmp`;
+  fs.writeFileSync(temp, content, { mode });
+  fs.renameSync(temp, file);
+}
+
+function migrationJournalPath(home) {
+  return path.join(home, 'data', 'role-v5-migration.json');
+}
+
+function writeMigrationJournal(plan, state) {
+  atomicWrite(migrationJournalPath(plan.home), `${JSON.stringify({
+    schemaVersion: 1,
+    state,
+    home: plan.home,
+    changes: plan.changes,
+  }, null, 2)}\n`);
+}
+
+function removeMigrationJournal(home) {
+  fs.rmSync(migrationJournalPath(home), { force: true });
+}
+
+function recoverMigrationJournal(home) {
+  const file = migrationJournalPath(home);
+  if (!fs.existsSync(file)) return;
+  let journal;
+  try { journal = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch { throw new Error(`Role config v5 migration journal is unreadable: ${file}`); }
+  if (journal?.schemaVersion !== 1
+    || !['prepared', 'committed'].includes(journal.state)
+    || path.resolve(journal.home) !== home
+    || !Array.isArray(journal.changes)) {
+    throw new Error(`Role config v5 migration journal is invalid: ${file}`);
+  }
+  const rootPrefix = home + path.sep;
+  for (const item of journal.changes) {
+    const target = path.resolve(item?.file || '');
+    if (!target.startsWith(rootPrefix)
+      || (item.before !== null && typeof item.before !== 'string')
+      || typeof item.after !== 'string') {
+      throw new Error(`Role config v5 migration journal contains an unsafe change: ${file}`);
+    }
+  }
+  if (journal.state === 'prepared') {
+    for (const item of [...journal.changes].reverse()) {
+      if (item.before === null) fs.rmSync(item.file, { force: true });
+      else atomicWrite(item.file, item.before);
+    }
+  }
+  removeMigrationJournal(home);
+}
+
+function applyMigration(plan) {
+  if (!plan.changes.length) return null;
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backup = path.join(plan.home, 'backups', 'role-v5-migration', stamp);
+  fs.mkdirSync(backup, { recursive: true });
+  for (const item of plan.changes) {
+    if (item.before === null) continue;
+    const dest = path.join(backup, 'files', path.relative(plan.home, item.file));
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, item.before);
+  }
+  fs.writeFileSync(path.join(backup, 'manifest.json'), `${JSON.stringify({
+    schemaVersion: 1,
+    createdAt: new Date().toISOString(),
+    summary: plan.summary,
+    files: plan.changes.map(item => ({ path: path.relative(plan.home, item.file), kind: item.kind })),
+  }, null, 2)}\n`);
+  writeMigrationJournal(plan, 'prepared');
+  try {
+    for (const item of plan.changes) {
+      atomicWrite(item.file, item.after);
+    }
+    writeMigrationJournal(plan, 'committed');
+    removeMigrationJournal(plan.home);
+  } catch (error) {
+    recoverMigrationJournal(plan.home);
+    throw error;
+  }
+  return backup;
+}
+
+export function runMigration(options = {}) {
+  const home = resolveHome(options.home);
+  const releaseLock = acquireMigrationLock(home);
+  try {
+    assertDaemonStopped(home);
+    recoverMigrationJournal(home);
+    const plan = planMigration(home);
+    const backup = options.apply ? applyMigration(plan) : null;
+    return { ok: true, mode: options.apply ? 'applied' : 'dry-run', home, changedFiles: plan.changes.length, backup, summary: plan.summary };
+  } finally {
+    releaseLock();
+  }
+}
+
+async function main() {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+      console.log('Usage: node kits/migrations/migrate-role-config-v5.mjs [--apply] [--home <path>] [--json]');
+      return;
+    }
+    const result = runMigration(options);
+    if (options.json) console.log(JSON.stringify(result));
+    else console.log(`Role config v5 migration (${result.mode}): ${result.changedFiles} file(s)`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (process.argv.includes('--json')) console.log(JSON.stringify({ ok: false, error: message }));
+    else console.error(`Migration failed: ${message}`);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

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

@@ -0,0 +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();

package/kits/rules/01-overview.md

@@ -0,0 +1,142 @@
+# EvolCore Context Kit (ECK)
+
+ECK 的总览：前置概念和框架结构。
+
+## Base Agent
+
+Base agent 是提供推理与生成能力的底层智能——如 Claude Code、Codex、Gemini 等。你就是当前会话的 base agent。
+
+## AUN 是什么
+
+AUN（Agent Union Network）是 agent 间安全通信的网络协议，SDK 的 npm 包名 `@agentunion/fastaun`。
+
+### AID
+
+AID（Agent Identifier）是主体在 AUN 网络中的唯一身份标识，格式为 `{name}.{issuer}`（如 `alice.aid.pub`）。任何拥有域名的组织都可以作为 Issuer 签发 AID——去中心化，无需中央权威。AID 同时也是通信地址：身份即入口。
+
+访问 `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/`（本目录） | 全量加载到每个会话 |
+| 按需载入 | `$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（无渠道） | rules + 会话层 + baseagent（身份/关系/环境/渠道层因无 channel、无身份而落选） |
+| private（私聊） | rules + 身份层 + 关系层（对端）+ 环境层 + 渠道层 + 会话层 + baseagent |
+| group（群聊） | rules + 身份层 + 关系层（群）+ 环境层 + 渠道层 + 会话层 + baseagent |
+
+> 会话层（session fragment）是 `when:always`、baseagent 段只要注入了 base agent 信息就加载——
+> 二者与 chatType 无关，每个场景都在；所以 coding 并非"仅 rules"。
+
+manifest schema、when 条件、合并覆盖、模板渲染、运行时变量目录，以及**实际渲染结果的调试输出**
+（`$EVOLCORE_HOME/data/eck-debug/` 下的 vars / context / fragments / manifest 四个文件）：
+详见 `$KITS_DOCS/context-assembly.md`。
+
+## 术语
+
+- **主体（Principal）**：通信参与者——人或 agent。AUN 网络上的主体持有 AID；非 AUN 渠道（飞书/微信等）的对端以该渠道的账号标识，同样是主体
+- **对端**：和你通信的主体
+- **本端（self）**：你自己
+- **用户**：对端中的人类一方
+- **环境（Venue）**：渠道 + 场景（私聊/群聊）构成的交互空间

package/kits/rules/02-navigation.md

@@ -0,0 +1,76 @@
+# 导航：怎么找到我需要的信息
+
+## 路径体系
+
+### 三个基础路径
+
+| 路径 | 含义 |
+|------|------|
+| `$EVOLCORE_HOME` | 用户数据根（默认 `~/.evolcore`） |
+| `$PACKAGE_ROOT` | evolcore 包根目录 |
+| `$CURRENT_PROJECT` | 当前工作目录 |
+
+### 派生路径
+
+| 名称 | 派生自 | 含义 |
+|------|--------|------|
+| `$KITS` | `$PACKAGE_ROOT/kits` | ECK 知识包根 |
+| `$KITS_RULES` | `$KITS/rules` | 自动载入部分（本目录） |
+| `$KITS_DOCS` | `$KITS/docs` | 按需载入文档 |
+| `$KITS_TEMPLATES` | `$KITS/templates` | prompt 模板 |
+| `$KITS_FRAGMENTS` | `$KITS_TEMPLATES/system-fragments` | ECK 动态注入 fragment 模板 |
+| `$ECK` | `$EVOLCORE_HOME/eck` | 运行时配置 |
+| `$AGENTS_DIR` | `$EVOLCORE_HOME/agents` | per-agent 数据根 |
+| `$AGENT_DIR` | `$AGENTS_DIR/<self-aid>` | 当前 agent 根 |
+| `$SELF_DIR` | `$AGENT_DIR/personal` | 个人数据层（身份层） |
+| `$RELATIONS_DIR` | `$AGENT_DIR/relations` | 关系层 |
+| `$VENUES_DIR` | `$AGENT_DIR/venues` | 环境层 |
+| `$AGENT_INDEX` | `$AGENT_DIR/index` | agent 级文档索引 |
+
+会话级动态注入：`$PEER_DIR` → 当前对端的关系目录。
+
+## 路径注册表机制
+
+路径用 `$名称` 引用，不写死实际路径。
+
+### 三层结构
+
+| 层 | 位置 | 性质 | 内容 |
+|----|------|------|------|
+| 机制描述 | 本文件 | 只读 | 语法、规则 |
+| 路径定义 | `$KITS_DOCS/path-registry.md` | 只读，按需加载 | 所有路径的派生规则或寻找规则 |
+| 路径实例 | `$ECK/path-registry.md` | 可变，按需加载 | 已解析的真实值 + 用户自定义路径 |
+
+### 两类路径
+
+- **可直接派生**：从基础路径按固定规则算出（如 `$KITS = $PACKAGE_ROOT/kits`）
+- **不可直接派生**：需按寻找规则搜索，找到后写入实例文件。例如：
+  - `$AUN_SDK`：寻找规则 `npm list -g @agentunion/fastaun --parseable`
+  - `$AUN_PROTOCOL_DOCS`：`$AUN_SDK/docs/protocol`（AUN 协议详细文档）
+
+### 按需加载时机
+
+路径定义和实例文件**不自动加载**，仅在以下场景 Read：
+- 需要访问某个 `$名称` 但当前上下文中没有真实值
+- 需要寻找外部依赖位置
+- 用户要求注册或查看路径
+
+## 索引机制
+
+| 层 | 位置 | 维护者 | 写入权限 |
+|----|------|--------|----------|
+| evolcore 级 | `$KITS_DOCS/INDEX.md` | 开发时维护 | 只读，过时时呈报用户 |
+| agent 级 | `$AGENT_INDEX/INDEX.md` | agent 会话 | 可写，直接更新 |
+
+agent 级索引范围：`$CURRENT_PROJECT` + `$AGENT_DIR`。
+
+触发时机：上述范围内有文档新增或较大幅度修改时，主动重建索引。
+
+## Bootstrap（独立使用 ECK 时）
+
+无 evolcore 动态注入时，路径确定顺序：
+1. `$EVOLCORE_HOME`：环境变量 → 默认 `~/.evolcore`
+2. 读取 `$ECK/runtime.md` 获取基础路径和运行时参数
+3. 按派生规则构造其余路径
+
+参数加载优先级：evolcore 动态注入 > 环境变量 > `$ECK/runtime.md` > 硬编码默认值。