evolcore 0.0.28 → 0.0.29

package/dist/utils/logger.js

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import { resolvePaths } from '../paths.js';
 import { LogWriter } from './log-writer.js';
-import { classifyToolErrorCode, normalizeToolErrorCode } from '../core/permission/tool-error-code.js';
+import { normalizeToolErrorClassification } from '../core/permission/tool-error-code.js';
 import { normalizePermissionMode } from '../core/permission/mode.js';
 import { buildToolLifecycleEventKey, normalizeToolCorrelation } from '../core/audit/event-key.js';
 let currentLevel = process.env.LOG_LEVEL || 'INFO';
@@ -114,21 +114,40 @@ export function normalizeStructuredLog(data) {
         ?? (isToolResult && isError === true ? 'error' : undefined)
         ?? (isToolResult && isError === false ? 'allow' : undefined)
         ?? (isToolUse ? 'pending' : undefined);
-    const executed = data.executed ?? nested?.executed
+    const explicitExecuted = data.executed ?? nested?.executed;
+    const explicitExecutionState = data.executionState ?? data.execution_state
+        ?? nested?.executionState ?? nested?.execution_state;
+    const executed = explicitExecuted
         ?? (isToolResult ? true : isToolUse ? false : undefined);
-    const executionState = data.executionState ?? data.execution_state
-        ?? nested?.executionState ?? nested?.execution_state
+    const executionState = explicitExecutionState
         ?? (isToolResult ? (isError === true ? 'failed' : 'completed') : isToolUse ? 'requested' : undefined);
+    const exitCode = data.exitCode ?? data.exit_code ?? nested?.exitCode ?? nested?.exit_code;
     const explicitErrorCode = data.errorCode
         ?? data.error_code
         ?? nested?.errorCode
         ?? nested?.error_code;
-    const errorCode = isToolResult && isError === true
-        ? classifyToolErrorCode({ errorCode: explicitErrorCode, decisionSource })
-        : explicitErrorCode;
-    const classificationMissing = isToolResult && isError === true
-        && !normalizeToolErrorCode(explicitErrorCode)
-        && decisionSource !== 'policy' && decisionSource !== 'approval';
+    const explicitErrorDetailCode = data.errorDetailCode
+        ?? data.detailCode
+        ?? data.detail_code
+        ?? nested?.errorDetailCode
+        ?? nested?.detailCode
+        ?? nested?.detail_code;
+    const classification = isToolResult && isError === true
+        ? normalizeToolErrorClassification({
+            errorCode: explicitErrorCode,
+            errorDetailCode: explicitErrorDetailCode,
+            decisionSource,
+            executed: explicitExecuted,
+            executionState: explicitExecutionState,
+            exitCode,
+            policyCode: data.policyCode ?? nested?.policyCode,
+        })
+        : undefined;
+    const errorCode = classification?.errorCode ?? explicitErrorCode;
+    const errorDetailCode = classification?.errorDetailCode
+        ?? (typeof explicitErrorDetailCode === 'string' ? explicitErrorDetailCode : undefined);
+    const classificationMissing = classification?.classificationMissing || data.classificationMissing === true || nested?.classificationMissing === true;
+    const classificationConflict = classification?.classificationConflict || data.classificationConflict === true || nested?.classificationConflict === true;
     const lifecycleEventKey = lifecycleRecord
         ? (eventKey ?? buildToolLifecycleEventKey({
             sessionId,
@@ -155,7 +174,10 @@ export function normalizeStructuredLog(data) {
         ...(executed !== undefined ? { executed } : {}),
         ...(executionState ? { executionState } : {}),
         ...(errorCode ? { errorCode } : {}),
+        ...(errorDetailCode ? { errorDetailCode } : {}),
+        ...(exitCode !== undefined ? { exitCode } : {}),
         ...(classificationMissing ? { classificationMissing: true } : {}),
+        ...(classificationConflict ? { classificationConflict: true } : {}),
         ...(missingContextFields.length > 0 ? { contextMissing: missingContextFields } : {}),
     };
 }

package/dist/utils/media-cache.js

@@ -11,6 +11,9 @@ import path from 'path';
 import fs from 'fs';
 import crypto from 'crypto';
 import { logger } from './logger.js';
+import { agentRelationDir } from '../paths.js';
+import { parsePeerKey } from '../core/relation/peer-identity.js';
+import { isSameOrDescendant } from '../core/permission/protected-paths.js';
 // ── 常量 ──────────────────────────────────────────────────────────────────────
 const DEFAULT_MAX_IMAGE_SIZE = 10 * 1024 * 1024; // 10 MB
 const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024; // 100 MB
@@ -18,6 +21,14 @@ const ALLOWED_IMAGE_MIMES = new Set([
     'image/png', 'image/jpeg', 'image/gif', 'image/webp',
 ]);
 const UPLOADS_SUBDIR = '.evolcore/uploads';
+const RELATION_ATTACHMENT_ID_RE = /^[a-f0-9]{32}$/;
+const RELATION_ATTACHMENT_MAX_BYTES = DEFAULT_MAX_FILE_SIZE;
+const RELATION_ATTACHMENT_EXTENSIONS = {
+    'image/png': '.png',
+    'image/jpeg': '.jpg',
+    'image/gif': '.gif',
+    'image/webp': '.webp',
+};
 // ── SSRF 防护 ─────────────────────────────────────────────────────────────────
 /** 已知安全的 CDN 域名白名单 */
 const ALLOWED_CDN_HOSTS = new Set([
@@ -101,6 +112,79 @@ export async function validateImage(buffer, opts) {
     }
     return { mime: type.mime };
 }
+function relationAttachmentsDir(selfAid, peerKey) {
+    parsePeerKey(peerKey);
+    return path.join(agentRelationDir(selfAid, peerKey), 'attachments');
+}
+/** Save one inbound image as a stable, peer-scoped attachment owned by the daemon. */
+export function saveRelationAttachment(buffer, selfAid, peerKey, mimeType) {
+    const extension = RELATION_ATTACHMENT_EXTENSIONS[mimeType];
+    if (!extension)
+        throw new Error(`Unsupported relation attachment MIME type: ${mimeType}`);
+    if (buffer.length < 1 || buffer.length > RELATION_ATTACHMENT_MAX_BYTES) {
+        throw new Error(`Relation attachment must be between 1 byte and ${RELATION_ATTACHMENT_MAX_BYTES} bytes`);
+    }
+    const directory = relationAttachmentsDir(selfAid, peerKey);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    if (process.platform !== 'win32')
+        fs.chmodSync(directory, 0o700);
+    const attachmentId = crypto.randomBytes(16).toString('hex');
+    const filename = `${attachmentId}${extension}`;
+    const filePath = path.join(directory, filename);
+    const metadataPath = path.join(directory, `${attachmentId}.json`);
+    const sha256 = crypto.createHash('sha256').update(buffer).digest('hex');
+    const metadata = {
+        version: 1, attachmentId, selfAid, peerKey, filename, mimeType,
+        sha256, size: buffer.length, createdAt: Date.now(),
+    };
+    fs.writeFileSync(filePath, buffer, { flag: 'wx', mode: 0o600 });
+    fs.writeFileSync(metadataPath, JSON.stringify(metadata), { flag: 'wx', mode: 0o600 });
+    return { ...metadata, filePath };
+}
+/** Resolve an attachment only inside the authenticated Agent/peer relation. */
+export function readRelationAttachment(selfAid, peerKey, attachmentSource) {
+    const attachmentId = RELATION_ATTACHMENT_ID_RE.test(attachmentSource)
+        ? attachmentSource
+        : path.basename(attachmentSource, path.extname(attachmentSource));
+    if (!RELATION_ATTACHMENT_ID_RE.test(attachmentId))
+        throw new Error('Invalid attachment ID');
+    const directory = relationAttachmentsDir(selfAid, peerKey);
+    const metadataPath = path.join(directory, `${attachmentId}.json`);
+    const metadataStat = fs.lstatSync(metadataPath);
+    if (!metadataStat.isFile() || metadataStat.isSymbolicLink())
+        throw new Error('Attachment metadata must be a regular file');
+    const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+    if (metadata.version !== 1 || metadata.attachmentId !== attachmentId
+        || metadata.selfAid !== selfAid || metadata.peerKey !== peerKey
+        || RELATION_ATTACHMENT_EXTENSIONS[metadata.mimeType] === undefined
+        || metadata.filename !== `${attachmentId}${RELATION_ATTACHMENT_EXTENSIONS[metadata.mimeType]}`) {
+        throw new Error('Attachment ownership metadata mismatch');
+    }
+    const filePath = path.join(directory, metadata.filename);
+    const stat = fs.lstatSync(filePath);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size !== metadata.size
+        || stat.size < 1 || stat.size > RELATION_ATTACHMENT_MAX_BYTES) {
+        throw new Error('Attachment file is missing or invalid');
+    }
+    const realDirectory = fs.realpathSync(directory);
+    const realPath = fs.realpathSync(filePath);
+    if (!isSameOrDescendant(realPath, realDirectory))
+        throw new Error('Attachment path escaped its relation directory');
+    if (path.isAbsolute(attachmentSource) && fs.realpathSync(attachmentSource) !== realPath) {
+        throw new Error('Attachment path does not match the current relation');
+    }
+    const buffer = fs.readFileSync(filePath);
+    const sha256 = crypto.createHash('sha256').update(buffer).digest('hex');
+    if (sha256 !== metadata.sha256)
+        throw new Error('Attachment content hash mismatch');
+    return {
+        attachment: {
+            attachmentId, selfAid, peerKey, filePath: realPath,
+            mimeType: metadata.mimeType, sha256, size: buffer.length,
+        },
+        buffer,
+    };
+}
 /**
  * 把已下载的附件 Buffer 转成入站图片条目（供 baseagent 视觉通道）。
  *

package/dist/utils/msg-diag.js

@@ -0,0 +1,97 @@
+/**
+ * msg-diag: 消息生命周期诊断打点
+ * 各处理环节调用 diagLog()，写入专用 msg-diag.jsonl。
+ * ec watch diag 读取该文件，固定行实时展示各环节最新处理的消息。
+ */
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+function getLogPath() {
+    const home = process.env.EVOLCORE_HOME ?? path.join(os.homedir(), '.evolcore');
+    return path.join(home, 'logs', 'msg-diag.jsonl');
+}
+let _logPath = null;
+let _fd = null;
+const MAX_SIZE = 500 * 1024; // 500 KB
+const TRIM_SIZE = 250 * 1024; // 超限后保留最后 250 KB
+function trimIfNeeded(p) {
+    try {
+        const stat = fs.statSync(p);
+        if (stat.size <= MAX_SIZE)
+            return;
+        // 读最后 TRIM_SIZE 字节，从第一个完整行开始保留
+        const fd = fs.openSync(p, 'r');
+        const buf = Buffer.alloc(TRIM_SIZE);
+        fs.readSync(fd, buf, 0, TRIM_SIZE, stat.size - TRIM_SIZE);
+        fs.closeSync(fd);
+        const str = buf.toString('utf-8');
+        const firstNl = str.indexOf('\n');
+        const kept = firstNl >= 0 ? str.slice(firstNl + 1) : str;
+        fs.writeFileSync(p, kept, 'utf-8');
+    }
+    catch {
+        // 修剪失败不阻塞主流程
+    }
+}
+function getFd() {
+    try {
+        if (!_logPath)
+            _logPath = getLogPath();
+        const dir = path.dirname(_logPath);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        // 每次写前检查大小，超限则修剪并重新打开
+        if (_fd !== null) {
+            try {
+                const stat = fs.statSync(_logPath);
+                if (stat.size > MAX_SIZE) {
+                    fs.closeSync(_fd);
+                    _fd = null;
+                    trimIfNeeded(_logPath);
+                }
+            }
+            catch {
+                fs.closeSync(_fd);
+                _fd = null;
+            }
+        }
+        if (_fd === null) {
+            _fd = fs.openSync(_logPath, 'a');
+        }
+        return _fd;
+    }
+    catch {
+        return null;
+    }
+}
+function shortId(id) {
+    if (!id)
+        return '';
+    return id.split('.')[0];
+}
+function cut(text, n) {
+    if (!text)
+        return '';
+    const s = text.replace(/\r?\n/g, ' ').trim();
+    return s.length <= n ? s : s.slice(0, n - 1) + '…';
+}
+export function diagLog(stage, data) {
+    try {
+        const entry = {
+            stage,
+            ts: new Date().toISOString(),
+            aid: shortId(data.aid ?? ''),
+            from: shortId(data.from ?? ''),
+            to: shortId(data.to ?? ''),
+            msgId: data.msgId ?? '',
+            taskId: data.taskId,
+            preview: cut(data.text ?? '', 50),
+        };
+        const fd = getFd();
+        if (fd !== null)
+            fs.writeSync(fd, JSON.stringify(entry) + '\n');
+    }
+    catch {
+        // 诊断打点失败不影响主流程
+    }
+}

package/dist/utils/welcome.js

@@ -94,6 +94,26 @@ function checkedWelcomePath(aid) {
     }
     return target;
 }
+/**
+ * Welcome state is physically shared under data/channel-state, so the key
+ * must carry the owning Agent identity. Runtime channel instances already
+ * pass an effective key; accepting a raw instance name here keeps the helper
+ * usable in tests and embedded callers without weakening the boundary.
+ */
+function effectiveWelcomeChannelKey(channelType, agentAid, channelName) {
+    const parts = channelName.split('#');
+    if (parts.length === 3) {
+        const [type, aid, name] = parts;
+        if (type !== channelType || aid !== agentAid || !name) {
+            throw new Error(`welcome channel key does not belong to Agent ${agentAid}: ${channelName}`);
+        }
+        return channelName;
+    }
+    if (parts.length !== 1 || !channelName) {
+        throw new Error(`invalid welcome channel name: ${channelName}`);
+    }
+    return `${channelType}#${agentAid}#${channelName}`;
+}
 export function saveAgentWelcomeTemplate(aid, template) {
     const validation = validateWelcomeTemplate(template);
     if (!validation.valid)
@@ -322,6 +342,7 @@ export class FirstInteractionWelcomeManager {
     agentAid;
     channelName;
     greetedUsersFile;
+    effectiveChannelKey;
     greetedUsers = new Set();
     initializedCache = null; // 缓存 initialized 状态，避免重复 I/O
     constructor(channelType, agentAid, channelName) {
@@ -329,7 +350,8 @@ export class FirstInteractionWelcomeManager {
         this.agentAid = agentAid;
         this.channelName = channelName;
         // 每个 channel instance 独立的已欢迎用户记录
-        this.greetedUsersFile = channelStatePath(channelName, 'welcome.jsonl');
+        this.effectiveChannelKey = effectiveWelcomeChannelKey(channelType, agentAid, channelName);
+        this.greetedUsersFile = channelStatePath(this.effectiveChannelKey, 'welcome.jsonl');
         this.loadGreetedUsers();
     }
     /**
@@ -403,7 +425,7 @@ export class FirstInteractionWelcomeManager {
                 }
             }
             if (this.greetedUsers.size > 0) {
-                logger.debug(`[WelcomeManager] Loaded ${this.greetedUsers.size} greeted users for ${this.channelName}`);
+                logger.debug(`[WelcomeManager] Loaded ${this.greetedUsers.size} greeted users for ${this.effectiveChannelKey}`);
             }
         }
         catch (e) {
@@ -431,10 +453,17 @@ export function initWelcomeManager(channelType, agentAid, channelName) {
  * @returns 是否发送了欢迎消息
  */
 export async function sendWelcomeIfNeeded(welcomeManager, userId, channelId, sendMessage, channelName) {
-    void welcomeManager;
-    void userId;
-    void channelId;
-    void sendMessage;
-    void channelName;
-    return false;
+    if (!welcomeManager || !welcomeManager.shouldGreet(userId))
+        return false;
+    try {
+        const welcomeText = welcomeManager.generateWelcomeText();
+        await sendMessage(channelId, welcomeText);
+        welcomeManager.markGreeted(userId);
+        logger.info(`[${channelName}] Sent first interaction welcome to ${userId}`);
+        return true;
+    }
+    catch (error) {
+        logger.warn(`[${channelName}] Failed to send first interaction welcome to ${userId}:`, error);
+        return false;
+    }
 }

package/kits/docs/AUTHORING.md

@@ -0,0 +1,314 @@
+# ECK 文档写作与维护指南
+
+> **读者：人与 Agent 两类。** ECK 由人机共同维护——人做设计判断，Agent 做具体增改。
+> 因此本文的规则要同时满足两个要求：人看得懂判据，Agent 能按判据执行。
+>
+> 相关文档：查阅文档见 `GUIDE.md`；manifest 注入机制见 `context-assembly.md`；路径与索引机制见 `$KITS_RULES/02-navigation.md`。
+
+---
+
+## 零、原则总览
+
+| 原则 | 防什么 | 可自动排查 |
+|------|--------|:---------:|
+| §一 文件位置 | 放错目录破坏机器约定 | ❌ |
+| §二 正交性 | 同一概念多处定义、随时间漂移 | 部分（grep） |
+| §三 注入成本 | `rules/` 膨胀，每轮白烧 token | ❌ |
+| §四 命名与路径 | 引用无法解析 | 部分 |
+| §五 可发现性 | 文档存在但找不到 | ❌ |
+| §六 引用完整性 | 悬空链接 / 语义失效 | 仅悬空可查 |
+| §七 粒度阈值 | 无意义碎片化 | ❌ |
+| §八 权威裁决 | 代码改了文档没改，不知信谁 | ❌ |
+| §九 示例一致性 | 照抄示例失败 | ❌ |
+
+**真正能自动排查的只有"悬空引用"一项**，其余全靠流程纪律——这是检查清单（§十）比看起来更重要的原因。
+
+---
+
+## 一、文件放哪里
+
+`kits/` 下的目录有明确分工，放错位置会破坏约定或让文档失去可发现性：
+
+| 目录 | 内容性质 | 谁读 | 能否放文档 |
+|------|---------|------|-----------|
+| `rules/` | 自动注入的机制骨架（01-06） | 每次会话自动加载 | ❌ 只放这 6 个 |
+| `docs/` | 按需 Read 的知识文档 | Agent 按需 | ✅ **人读的文档都放这里** |
+| `schemas/` | 代码消费的 schema 数据 | `schema-registry.ts` 扫描 | ❌ 只放 `*.schema.*.json` + `_meta.json` |
+| `templates/` | prompt 组装模板 | 渲染引擎 | ❌ 只放模板 |
+| `migrations/` | 迁移数据 | 迁移逻辑 | 仅 README 例外 |
+
+**判据**：`schemas/`、`templates/` 是**机器读的数据目录**，命名和格式有程序依赖。人类阅读的说明文档一律放 `docs/` 下对应子目录。在数据目录里放 `.md` 会破坏命名约定，也让后来者误判目录职责。
+
+`migrations/README.md` 是唯一被接受的反例——README 与其描述的数据同放是通用惯例，且它在子目录内，不污染顶层命名空间。
+
+### `templates/` 下的子目录
+
+模板按**被注入的会话类型**分子目录，不要平铺：
+
+| 子目录 | 用途 | 谁引用 |
+|------|------|--------|
+| `system-fragments/` | 主会话的系统提示词片段（identity / session / commands 等）；`memory.md` 例外，主会话与整理会话共用 | `eck_manifest.json`（`memory.md` 另被 `eck_manifest.memory.json` 引用） |
+| `message-fragments/` | 消息信封渲染片段 | `eck_message_manifest.json` |
+| `memory-consolidation/` | 整理会话（`sessionType=memory`）的 prompt | `eck_manifest.memory.json` |
+
+**`memory-consolidation/` 的结构**：`workflow.md`（整理流程）+ 五份模式手册（`notes.md` / `generalize.md` / `promote.md` / `profile.md` / `forget.md`）。命令、权限、禁止事项不在这里，而在主会话与整理会话共用的 `$KITS_FRAGMENTS/memory.md`（按 `sessionType` 分支渲染）。manifest 里**逐个文件列段**，不能用目录段——`pattern` 不支持变量插值（`manifest-engine.ts` 的 `matchGlob` 只做 `*` → `.*`），目录段会把六份文件一次性全灌进去。
+
+**这些文件不进 `docs/`**：它们是**每轮注入**的 prompt，不是按需 Read 的知识文档。放 `docs/` 会让人误以为可以惰性加载，改了却发现要么不生效、要么被重复注入。人读的机制说明在 `kits/docs/evolcore/memory-consolidation.md`。
+
+---
+
+## 二、正交：一个概念只有一个事实源
+
+这是本套文档体系最核心的规则（`00-导读.md` 已声明"每个概念只有一个唯一事实源"），执行时按下面的方法落地。
+
+### 先分类，再动笔
+
+写或改文档前，先判定它在讲哪一类内容：
+
+| 类别 | 内容 | 举例 |
+|------|------|------|
+| **格式/机制** | 数据结构、字段定义、协议语义、权限模型 | `protected_headers` 有哪些字段 |
+| **工具用法** | CLI 语法、参数、退出码、连接行为 | `ec menu-client --request-file` 怎么用 |
+| **具体任务** | 某个入口/场景的完整操作步骤 | 通过 menu exec 取某个 schema |
+
+**格式类只能有一个定义处**，其余文档引用它。工具类文档**不得重复定义格式**，只能写"格式见 XX"。
+
+### 判定重叠的实际做法
+
+遇到两份文档疑似重复时，逐条列出两边的章节，标出讲同一件事的部分：
+
+```
+内容项                        A 文档   B 文档   处置
+消息类型定义                  ✅ 完整  ✅ 部分   归 A，B 删掉改引用
+CLI 参数语义                  ✅ 完整  ❌        归 B
+鉴权机制                      ❌       ✅ 完整   归 A
+```
+
+只有**明确归属给某一方**的部分才能保留，另一方改为一句引用。做不到这一条，两份文档就会随时间继续漂移。
+
+### 常见的重叠陷阱
+
+- 两份文档都写"默认值/缺省行为" → 归格式方
+- 两份文档都举 JSON 示例 → 归格式方，工具方最多留最简的可复制样例
+- 两份文档都写权限要求 → 归格式方（协议层），工具方只写"入口的 token/owner 校验"
+
+---
+
+## 三、注入成本：内容默认放 docs/
+
+ECK 的 manifest 机制决定了**不同位置的内容有不同的成本量级**。机制完整说明见 `context-assembly.md`（唯一事实源，本文不重复定义），这里只给由此得出的写作判据。
+
+### 成本模型
+
+| 位置 | 何时消耗 token | 成本量级 |
+|------|--------------|---------|
+| `rules/` | **每次对话都注入**（当前 6 文件约 18KB） | 每轮都付 |
+| `docs/` | 仅被 agent Read 时 | 按需付，多数对话为零 |
+
+### 判据
+
+> **内容默认放 `docs/`。只有"每个会话、每轮都需要，不注入就会做错事"的内容才升到 `rules/`。**
+
+写入 `rules/` 前自问：**这条信息如果不注入，agent 会在多少比例的对话里做错事？**
+
+- 每轮都需要（如"不得调用 `ec restart`"）→ 进 `rules/`
+- 偶发场景才需要（如"Menu 消息有哪些字段"）→ 留 `docs/`，靠 `INDEX.md` 触发词按需命中
+
+答不上来就别进 `rules/`。最常见的隐性浪费是把偶发查阅的内容塞进规则文件，之后每轮对话都在白烧 token。
+
+### 硬阈值
+
+来自 `context-assembly.md` 的限额机制：
+
+- 单目录段：40KB（`$KITS_RULES` 当前约 18KB，**剩余约一半**）
+- 总闸：50 文件 / 100KB（跨所有段累计）
+
+逼近阈值会触发截断——**后面的 section 直接不加载**，且只注入一行截断说明。这是静默降级，出错时不报错，只表现为"某段上下文莫名其妙没出现"。
+
+### 升到 rules/ 的代价
+
+`rules/` 段是 `directory` 类型，加载**整个目录**。所以往 `rules/` 加一份文件不只是加了那份文件的成本，而是抬高了该目录的总字节数，逼近 40KB 上限。加规则文件前先确认现有占用（渲染报告里的 `manifest-*.md` 或直接量目录大小）。
+
+---
+
+## 四、命名与路径写法
+
+### 文件名
+
+与源码对应关系优先于名字的绝对准确。例如 `menu-protocol.md` 对应 `src/core/command/menu-protocol.ts`——保持同名比改成 `menu-app-protocol.md` 更有价值，因为读者能靠文件名在代码里定位实现。
+
+### 文档内引用路径
+
+三种写法，按场景选，**同一份文档内保持一致**：
+
+| 场景 | 写法 | 示例 |
+|------|------|------|
+| 引用同目录文档 | 裸文件名 | `menu-protocol.md` |
+| 引用别名内路径（`$KITS_*` / `$AGENT_DIR` 等） | `$别名/子路径` | `$KITS_DOCS/evolcore/foo.md` |
+| 引用别名外路径 | 全限定 + 说明 | `$KITS/schemas/bar.md`（注明不在别名解析范围） |
+
+**不要用 `../` 相对路径**跨目录引用。`$KITS_DOCS` = `kits/docs`，`../schemas/` 会跑出别名体系，读者（尤其是 agent）无法用路径规则解析。
+
+**只有 `$KITS` / `$KITS_DOCS` / `$KITS_RULES` / `$KITS_TEMPLATES` / `$KITS_FRAGMENTS` / `$AGENT_DIR` / `$PERSONAL_DIR` / `$RELATIONS_DIR` / `$VENUES_DIR` 等注册别名可用于引用**。完整清单见 `$KITS_DOCS/path-registry.md`。写 `$ECK` / `$PEER_DIR` 这类未注册名，在 manifest 里会**导致整段被静默丢弃**。
+
+### 术语唯一
+
+同一个概念在整套文档里只能有一个名字。理由是**检索靠字符串匹配**——同一概念存在两种叫法，等于把一半可发现性让出去。
+
+裁决标准：**优先对齐代码里的标识符**。源码中的类型名、函数名、文件名是全系统唯一不会歧义的名字。例如"授权凭证"这种业务术语，如果有对应的源码类型名，以源码为准。
+
+---
+
+## 五、可发现性：新文档必须接进链路
+
+一份文档写完不等于能被找到。ECK 的检索链路是**单入口 + 多级 lazy Read**：
+
+```
+【自动注入】$KITS_RULES/06-channel.md
+   "遇到明确触发词 → 优先查 $KITS_DOCS/evolcore/INDEX.md"
+        │
+        ▼
+【按需 Read】INDEX.md（命令表 / 协议与集成表）
+        │
+        ▼
+【按需 Read】目标文档
+        │
+        └── 文档内回链到相邻文档（双向可达）
+```
+
+### 接入清单（新文档必做）
+
+1. **在 `INDEX.md` 注册**，选对表：
+   - 对应某个 `ec` 子命令 → 「命令表」，填**触发词列**（关键，agent 靠它命中）
+   - 描述机制/格式，无对应命令 → 「协议与集成文档」表
+2. **补触发词**。触发词要写用户/agent 可能说出的自然语言，不是文档标题的复述。对照现有条目：
+   - ✅ `远程诊断/远程 daemon 操作/daemon 日志/跨主机`
+   - ❌ `Menu 客户端命令文档`
+3. **双向回链**。相邻文档之间互相引用——A 提到 B 的地方链过去，B 的相关处链回来。
+4. **检查上游触发词**。`rules/06-channel.md` 里那句示例触发词列表如果不覆盖新话题，补上。
+
+### 反模式
+
+- **双入口**：`commands` fragment（自动注入的能力卡）只列常用命令，不必把新命令加进去。加了会造成"能力卡一份、INDEX 一份"的双份维护，且 fragment 是精简卡片，不适合承载完整清单。
+- **只加文档不加索引**：文档存在但没有任何自动注入的锚点指向它，agent 无从知晓。
+
+---
+
+## 六、引用完整性
+
+**原则：任何引用都必须在任何时刻可解析。**
+
+失效分两种，性质完全不同：
+
+| 类型 | 表现 | 可否自动排查 |
+|------|------|:-----------:|
+| **结构失效（悬空）** | 目标文件不存在、锚点不存在 | ✅ 可 |
+| **语义失效** | 目标文件存在、链接有效，但**内容已经不对了** | ❌ 不可 |
+
+### 悬空排查
+
+```bash
+# 列出所有 markdown 内链目标，逐个确认存在
+git grep -h -o '\[.*\](\./[^)]*\.md)' -- kits/docs | sort -u
+```
+
+### 语义失效的预防
+
+改了某个概念，所有引用它的文档**必须列入同一次变更**。做法：
+
+1. 改动前先查清"谁引用了它"——`git grep -n "<概念关键字>" -- kits`
+2. 把命中的文档全部纳入本次改动范围，逐一核对
+3. 查不清的（概念名在正文里以同义词出现），至少在提交信息里记录未核对的文档
+
+这是唯一能防语义失效的手段。**不要指望后来者发现**——语义失效不会报错，只会在某次对话里表现为"agent 引用了过时的说法"。
+
+---
+
+## 七、粒度阈值
+
+正交讲"该分就分"，但同样要防"不该分的分了"。
+
+> **两半内容的发现触发词不同 → 拆；触发词相同、读者相同 → 合。**
+
+判据是**触发词**，不是篇幅。举例：
+
+- `menu-client.md`（工具用法）与 `menu-protocol.md`（格式定义）**该拆**——用户说"远程看日志"和说"auth_method 是什么"是两类完全不同的需求，触发词不重叠
+- 反之，如果两份文档都靠"menu 怎么工作"这个触发词命中，拆开就是纯粹的碎片化，只让读者多跳一次
+
+篇幅长不是拆分的理由。一份 500 行的单主题文档，比三份各 150 行、读者要在其间跳转的文档更容易维护。
+
+---
+
+## 八、权威裁决：冲突时以谁为准
+
+正交管"一个概念只有一个事实源"，但没回答**冲突时以谁为准**。实际维护中这立刻会遇到：代码改了、文档没改，读者该信谁？
+
+| 冲突类型 | 以谁为准 | 说明 |
+|---------|---------|------|
+| 行为、字段、参数、错误码等**实现事实** | **代码为准** | 文档跟随代码；文档中给出源码指针，让读者可自行核对 |
+| 设计意图、取舍理由、"为什么这样" | **文档为准** | 代码是实现手段，意图只存在于文档 |
+
+### 文档之间冲突
+
+**不要简单地"以后者为准"。** 回到 §二 正交：判定该概念归属哪一份，另一份删掉改引用。只在引用处保留一句指向。
+
+简单往后覆盖文档，会让两份继续各自漂移——下次改其中一份，冲突再次出现。
+
+---
+
+## 九、示例代码必须与实现一致
+
+文档里的示例会被直接照抄执行，写错比不写更糟。
+
+**规则**：写或改示例前，**读一遍对应的源码**确认形态。特别是：
+
+- **参数类型**（对象 vs `JSON.stringify` 字符串）
+- **必填但易漏的字段**（如 Menu 消息的 `ttl: 60`）
+- **签名/字段名**（`protected_headers` 字段的大小写与拼写）
+
+本次维护中发现的典型错误：示例写成 `payload: JSON.stringify({...})`，而实现是 `payload: {...}` 对象直传（`transport.ts` 直接读 `params.payload?.type`）——照抄会直接失败。
+
+**示例后附依据**：在示例下方注明对应的源文件与行为，方便后续核对：
+
+```markdown
+- `ttl: 60` 是 Menu 消息的固定约定（`src/aun/menu/transport.ts` 的 `MENU_MESSAGE_TTL_SECONDS`）。
+```
+
+---
+
+## 十、改动前后的检查清单
+
+### 改前
+
+- [ ] 确认改动内容属于哪一类（格式 / 工具 / 具体任务）
+- [ ] 搜索该内容是否已在别处定义（`git grep -n "<关键字段名>" -- kits`）
+- [ ] 若已定义，判断归哪一方，另一方改为引用
+- [ ] 若改的是概念定义，查清所有引用方并纳入本次变更（防语义失效，见 §六）
+- [ ] 若往 `rules/` 加内容，先确认该目录当前占用（防注入成本失控，见 §三）
+
+### 改后
+
+- [ ] 无 `../` 相对路径引用
+- [ ] 无未注册别名（`$ECK` / `$PEER_DIR` / `$AGENT_INDEX` 等）
+- [ ] 所有引用的目标文件**确实存在**（悬空引用排查，见 §六）
+- [ ] 章节编号连续、锚点链接有效
+- [ ] 示例代码与源码形态一致（见 §九）
+- [ ] 新文档已注册进 `INDEX.md` 且带触发词
+- [ ] 被改动文档的相邻文档有回链
+- [ ] 改了 `ec memory` 的命令语法：`$KITS_FRAGMENTS/memory.md`、`$KITS_DOCS/evolcore/memory.md`、`src/cli/memory-command.ts` 的 `MEMORY_HELP` / `USAGE` 三处同步
+
+---
+
+## 十一、本次维护的案例（供参考）
+
+以下几处改动可作为规则的实际样本：
+
+| 问题 | 违反的规则 | 处置 |
+|------|-----------|------|
+| `menu-client.md` 与 `menu-protocol.md` 都定义消息类型 | §二 正交 | client 收敛为工具手册，格式引用 protocol |
+| `menu-protocol-cli-exec-frontend.md` 被引用但不存在 | §六 结构失效 | 改指向 `menu-protocol.md` |
+| `schemas/menu-exec-schema-commands.md` 放在数据目录 | §一 文件位置 | `git mv` 到 `docs/evolcore/` |
+| `INDEX.md` 用 `../schemas/...` | §四 路径写法 | 改为同目录裸文件名 |
+| 章节顺序 `0,1,2,3,4,6,5` | §十 编号连续 | 交换 §5/§6 并修锚点 |
+| 示例用 `JSON.stringify(payload)` | §九 示例一致性 | 改为对象直传 + 补 `ttl` |
+| `menu-protocol.md` 无触发词入口 | §五 可发现性 | 新建「协议与集成文档」表并填触发词 |

package/kits/docs/GUIDE.md

@@ -1,5 +1,7 @@
 # 文档查阅指南
 
+> 本文面向**查阅**文档的人。要**新增或修改** `kits/` 下的文档，见 `AUTHORING.md`。
+
 ## 查阅流程
 
 1. 先看 `$KITS_RULES`（自动加载的 6 个规则文件 01-06）了解机制骨架