evolcore 0.0.24 → 0.0.26

package/dist/utils/evolcore-version.js

@@ -1,7 +1,11 @@
+import crypto from 'node:crypto';
 import fs from 'fs';
 import path from 'path';
 import { getPackageRoot } from '../paths.js';
 let cachedVersion;
+let cachedFlavor;
+let cachedStartStamp;
+let cachedStartedAtIso;
 export function readInstalledEvolcoreVersion() {
     if (cachedVersion !== undefined)
         return cachedVersion;
@@ -16,6 +20,131 @@ export function readInstalledEvolcoreVersion() {
     cachedVersion = version;
     return version;
 }
+/**
+ * 区分源码仓库运行与全局安装包。`package.json` 的 `files` 白名单不含 `src/`，
+ * 所以 `src/index.ts` 的存在性可以稳定区分两者：同一个版本号在 dev 下跑的是
+ * 未发布的工作副本，排查时必须能看出来。
+ */
+export function readEvolcoreRuntimeFlavor() {
+    if (cachedFlavor !== undefined)
+        return cachedFlavor;
+    let flavor;
+    try {
+        flavor = fs.existsSync(path.join(getPackageRoot(), 'src', 'index.ts')) ? 'dev' : 'install';
+    }
+    catch {
+        flavor = 'install';
+    }
+    cachedFlavor = flavor;
+    return flavor;
+}
+function pad2(n) {
+    return String(n).padStart(2, '0');
+}
+/**
+ * 本进程启动时刻。用 `process.uptime()` 反推而非模块加载时的 `Date.now()`：
+ * 后者受 import 链耗时影响，且本模块可能被惰性加载。无 syscall，只算一次。
+ */
+function resolveStartedAt() {
+    return new Date(Date.now() - Math.round(process.uptime() * 1000));
+}
+/** 本进程启动时刻的 ISO 串，供结构化字段使用。 */
+export function readEvolcoreStartedAtIso() {
+    if (cachedStartedAtIso !== undefined)
+        return cachedStartedAtIso;
+    cachedStartedAtIso = resolveStartedAt().toISOString();
+    return cachedStartedAtIso;
+}
+/**
+ * 错误标记里的启动时刻，`MMDD-HHMM` 本地时间。
+ *
+ * 用本地时间而非 UTC：读的人是对着自己的墙上时钟判断"这进程是我改完之后起的吗"。
+ * 精度到分钟——秒级对判断重启无意义，只会占长度。
+ */
+export function readEvolcoreStartStamp() {
+    if (cachedStartStamp !== undefined)
+        return cachedStartStamp;
+    const d = resolveStartedAt();
+    cachedStartStamp = `${pad2(d.getMonth() + 1)}${pad2(d.getDate())}-${pad2(d.getHours())}${pad2(d.getMinutes())}`;
+    return cachedStartStamp;
+}
+/**
+ * 用户可见错误文案的版本标记，形如 `[EC 0.0.24 dev 0915-1230]`。
+ *
+ * 带启动时刻是因为版本号不足以定位问题：dev 模式下同一个 `0.0.24` 可能是任意一份
+ * 工作副本，改完代码不重启就仍在跑旧代码——启动时刻能直接把这种情况暴露出来。
+ */
+export function evolcoreErrorTag() {
+    return `[EC ${readInstalledEvolcoreVersion()} ${readEvolcoreRuntimeFlavor()} ${readEvolcoreStartStamp()}]`;
+}
+const ERROR_TAG_PATTERN = /\[EC\s+[^\]]*\]/;
+/**
+ * 前导 emoji / 变体选择符 / 空白：标记要插在它们之后。U+FE0F 单独列出，
+ * 它跟在 emoji 之后且不属于 Extended_Pictographic，漏掉会把 `⚠️` 拆开。
+ */
+const LEADING_DECORATION = /^(?:\p{Extended_Pictographic}|️|\s)+/u;
+/**
+ * 给用户可见的错误文案打版本标记。标记走前缀而非后缀：渠道前端会截断长文案
+ * （错误卡片只显示前两行），后缀会被直接截掉。
+ *
+ * 幂等，且在整串任意位置发现既有标记就跳过——错误文案会被
+ * `formatRetryableErrorFinalMessage` 之类的包装器嵌进 `原因：…` 中段，
+ * 只检查开头会导致同一个错误被打两次标。
+ */
+export function tagErrorTextWithEvolcoreVersion(text) {
+    if (typeof text !== 'string' || !text.trim())
+        return text;
+    if (ERROR_TAG_PATTERN.test(text))
+        return text;
+    const decoration = text.match(LEADING_DECORATION)?.[0] ?? '';
+    return `${decoration}${evolcoreErrorTag()} ${text.slice(decoration.length)}`;
+}
 export function _resetInstalledEvolcoreVersionForTests() {
     cachedVersion = undefined;
+    cachedFlavor = undefined;
+    cachedStartStamp = undefined;
+    cachedStartedAtIso = undefined;
+}
+function collectFiles(root, current = root, out = []) {
+    let entries;
+    try {
+        entries = fs.readdirSync(current, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const full = path.join(current, entry.name);
+        if (entry.isDirectory())
+            collectFiles(root, full, out);
+        else if (entry.isFile())
+            out.push(path.relative(root, full));
+    }
+    return out;
+}
+/** Hash the complete compiled tree so a changed dependency module changes the ID too. */
+export function computeBuildId(distDir) {
+    if (!fs.existsSync(distDir))
+        return null;
+    try {
+        const hash = crypto.createHash('sha256');
+        for (const relative of collectFiles(distDir)) {
+            const full = path.join(distDir, relative);
+            hash.update(relative.replaceAll(path.sep, '/'));
+            hash.update('\0');
+            hash.update(fs.readFileSync(full));
+            hash.update('\0');
+        }
+        return `sha256:${hash.digest('hex').slice(0, 24)}`;
+    }
+    catch {
+        return null;
+    }
+}
+export function readBuildIdentity(distDir, version) {
+    return {
+        id: computeBuildId(distDir),
+        entry: path.join(distDir, 'index.js'),
+        ...(version ? { version } : {}),
+    };
 }

package/dist/utils/logger.js

@@ -152,7 +152,9 @@ export function normalizeStructuredLog(data) {
 export function localTimestamp() {
     const d = new Date();
     const pad = (n) => String(n).padStart(2, '0');
-    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${String(d.getMilliseconds()).padStart(3, '0')}`;
+    const offset = -d.getTimezoneOffset();
+    const zone = `${offset >= 0 ? '+' : '-'}${pad(Math.floor(Math.abs(offset) / 60))}:${pad(Math.abs(offset) % 60)}`;
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${String(d.getMilliseconds()).padStart(3, '0')}${zone}`;
 }
 function log(level, ...args) {
     if (!shouldLog(level))

package/dist/utils/model-prices.jsonl

@@ -18,6 +18,6 @@
 {"model":"glm-5","effective_from":0,"billing_fn":"per_token_v1","currency":"CNY","price_input":5,"price_output":20,"price_cache_creation":0,"price_cache_read":0,"context_window":128000,"max_input_tokens":120000,"max_output_tokens":8192}
 {"model":"glm-4.7","effective_from":0,"billing_fn":"per_token_v1","currency":"CNY","price_input":1,"price_output":5,"price_cache_creation":0,"price_cache_read":0,"context_window":128000,"max_input_tokens":120000,"max_output_tokens":8192}
 {"model":"MiniMax-M2.7","effective_from":0,"billing_fn":"per_token_v1","currency":"CNY","price_input":1,"price_output":5,"price_cache_creation":0,"price_cache_read":0,"context_window":128000,"max_input_tokens":120000,"max_output_tokens":8192}
-{"model":"claude-opus-5","effective_from":0,"context_window":1000000,"max_input_tokens":900000,"max_output_tokens":131072,"supports_cache":true,"supports_vision":true}
-{"model":"claude-sonnet-5","effective_from":0,"context_window":1000000,"max_input_tokens":900000,"max_output_tokens":131072,"supports_cache":true,"supports_vision":true}
-{"model":"claude-fable-5","effective_from":0,"context_window":1000000,"max_input_tokens":900000,"max_output_tokens":131072,"supports_cache":true,"supports_vision":true}
+{"model":"claude-opus-5","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":5,"price_output":25,"price_cache_creation":6.25,"price_cache_read":0.5,"context_window":1000000,"max_input_tokens":900000,"max_output_tokens":131072,"supports_cache":true,"supports_vision":true}
+{"model":"claude-sonnet-5","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":2,"price_output":10,"price_cache_creation":2.5,"price_cache_read":0.2,"context_window":1000000,"max_input_tokens":900000,"max_output_tokens":131072,"supports_cache":true,"supports_vision":true}
+{"model":"claude-fable-5","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":10,"price_output":50,"price_cache_creation":12.5,"price_cache_read":1,"context_window":1000000,"max_input_tokens":900000,"max_output_tokens":131072,"supports_cache":true,"supports_vision":true}

package/dist/utils/npm-ops.js

@@ -8,11 +8,119 @@
  */
 import fs from 'fs';
 import path from 'path';
-import { execFile, execSync } from 'child_process';
+import { execFile, execFileSync } from 'child_process';
 import { promisify } from 'util';
 import { getPackageRoot } from '../paths.js';
 import { isWindows } from './cross-platform.js';
 const execFileAsync = promisify(execFile);
+/** The preferred public registry for update checks. */
+export const DEFAULT_NPM_REGISTRY = 'https://registry.npmjs.org';
+function normalizeRegistry(registry = DEFAULT_NPM_REGISTRY) {
+    const value = registry.trim();
+    return (value || DEFAULT_NPM_REGISTRY).replace(/\/+$/, '');
+}
+/**
+ * Resolve npm from the same Node installation that is running EvolCore.
+ * This prevents a daemon launched by one NVM installation from querying or
+ * mutating another installation selected by the shell's PATH.
+ */
+function resolveNpmInvocation() {
+    const nodeDir = path.dirname(process.execPath);
+    const sibling = path.join(nodeDir, isWindows ? 'npm.cmd' : 'npm');
+    const cliCandidates = [
+        path.join(nodeDir, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    ];
+    if (fs.existsSync(sibling)) {
+        try {
+            const target = fs.realpathSync(sibling);
+            if (target.endsWith('.js'))
+                cliCandidates.unshift(target);
+        }
+        catch { /* fall through to the known npm layouts */ }
+    }
+    const npmCli = cliCandidates.find(candidate => fs.existsSync(candidate));
+    if (npmCli)
+        return { command: process.execPath, argsPrefix: [npmCli] };
+    if (isWindows) {
+        return {
+            command: process.env.ComSpec || path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'cmd.exe'),
+            argsPrefix: ['/c', 'npm'],
+        };
+    }
+    return { command: fs.existsSync(sibling) ? sibling : 'npm', argsPrefix: [] };
+}
+/**
+ * Read the effective registry from the npm belonging to the current Node.
+ * An empty value means npm has no explicit registry and uses the public
+ * default. A command failure is handled separately by using the public source
+ * directly, so a broken npm config cannot leave the upgrade without a retry.
+ */
+async function resolveUpgradeRegistry(signal) {
+    const npm = resolveNpmInvocation();
+    try {
+        const result = await execFileAsync(npm.command, [...npm.argsPrefix, 'config', 'get', 'registry'], {
+            timeout: 5000,
+            windowsHide: isWindows,
+            signal,
+        });
+        const value = String(result.stdout ?? '').trim();
+        if (!value || value === 'undefined' || value === 'null') {
+            return { registry: DEFAULT_NPM_REGISTRY, useNpmCli: false };
+        }
+        return { registry: normalizeRegistry(value), useNpmCli: true };
+    }
+    catch {
+        return { registry: DEFAULT_NPM_REGISTRY, useNpmCli: false };
+    }
+}
+async function checkLatestVersionViaNpm(pkg, timeoutMs, signal, registry) {
+    const npm = resolveNpmInvocation();
+    try {
+        const result = await execFileAsync(npm.command, [
+            ...npm.argsPrefix,
+            'view',
+            `${pkg}@latest`,
+            'version',
+            '--json',
+            '--registry',
+            registry,
+        ], {
+            timeout: timeoutMs ?? 10000,
+            windowsHide: isWindows,
+            signal,
+        });
+        const raw = String(result.stdout ?? '').trim();
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'string' && parsed)
+            return parsed;
+        if (Array.isArray(parsed)) {
+            const latest = parsed.at(-1);
+            return typeof latest === 'string' && latest ? latest : null;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// Registry checks can run concurrently, but two package upgrades must never
+// mutate npm's global tree at the same time. A tiny in-process queue keeps the
+// fast path parallel without changing upgrade ordering or failure semantics.
+let globalInstallTail = Promise.resolve();
+async function withGlobalInstallLock(action) {
+    const previous = globalInstallTail;
+    let release;
+    globalInstallTail = new Promise(resolve => { release = resolve; });
+    await previous;
+    try {
+        await action();
+    }
+    finally {
+        release();
+    }
+}
 // ── npm install -g (shared) ────────────────────────────────────────────────
 /**
  * Can we run sudo without a password prompt?
@@ -35,20 +143,11 @@ async function canSudoNonInteractively() {
     }
 }
 export async function npmInstallGlobal(pkg, options = {}) {
-    let cmd;
-    let args;
-    // Windows: run via cmd /c to avoid shell:true deprecation warning on Node 22.
-    // Unix: npm directly, no shell needed.
-    if (isWindows) {
-        cmd = process.env.ComSpec || path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'cmd.exe');
-        args = ['/c', 'npm', 'install', '-g', pkg];
-    }
-    else {
-        cmd = 'npm';
-        args = ['install', '-g', pkg];
-    }
+    const npm = resolveNpmInvocation();
+    const registry = options.registry ? normalizeRegistry(options.registry) : undefined;
+    const npmArgs = ['install', '-g', pkg, ...(registry ? ['--registry', registry] : [])];
     try {
-        await execFileAsync(cmd, args, {
+        await execFileAsync(npm.command, [...npm.argsPrefix, ...npmArgs], {
             timeout: options.timeoutMs ?? 180000,
             windowsHide: isWindows,
             signal: options.signal,
@@ -62,9 +161,10 @@ export async function npmInstallGlobal(pkg, options = {}) {
                 throw new Error('权限不足。请以管理员身份运行 PowerShell 或 CMD，然后重试');
             }
             if (!await canSudoNonInteractively()) {
-                throw new Error(`权限不足，且 sudo 需要密码（当前进程无法交互输入）。请手动执行: sudo npm install -g ${pkg}`);
+                const registryArg = registry ? ` --registry ${registry}` : '';
+                throw new Error(`权限不足，且 sudo 需要密码（当前进程无法交互输入）。请使用当前 Node 对应的 npm 手动执行: sudo npm install -g ${pkg}${registryArg}`);
             }
-            await execFileAsync('sudo', ['-n', 'npm', 'install', '-g', pkg], {
+            await execFileAsync('sudo', ['-n', npm.command, ...npm.argsPrefix, ...npmArgs], {
                 timeout: options.timeoutMs ?? 180000,
                 windowsHide: false,
                 signal: options.signal,
@@ -132,10 +232,8 @@ export function getLocalVersion() {
  */
 export function resolveGlobalPkg(pkgName) {
     try {
-        // 命令完全静态（npm root -g，无用户输入），用 execSync 传完整命令字符串，
-        // 避免 "args 数组 + shell:true" 组合触发 Node DeprecationWarning，且无注入风险。
-        const npmCmd = isWindows ? 'npm.cmd' : 'npm';
-        const globalRoot = execSync(`${npmCmd} root -g`, {
+        const npm = resolveNpmInvocation();
+        const globalRoot = execFileSync(npm.command, [...npm.argsPrefix, 'root', '-g'], {
             encoding: 'utf-8', timeout: 10000, windowsHide: true,
         }).trim();
         const pkgPath = path.join(globalRoot, ...pkgName.split('/'), 'package.json');
@@ -152,7 +250,7 @@ export function resolveGlobalPkg(pkgName) {
  * 使用 HTTP fetch 直接查 registry API，不依赖 npm CLI。
  * 超时 10 秒，失败返回 null。
  */
-export async function checkLatestVersion(pkg = 'evolcore', timeoutMs = 10000, signal) {
+async function fetchLatestVersion(pkg = 'evolcore', timeoutMs = 10000, signal, registry = DEFAULT_NPM_REGISTRY) {
     const controller = new AbortController();
     const abort = () => controller.abort();
     if (signal?.aborted)
@@ -161,14 +259,14 @@ export async function checkLatestVersion(pkg = 'evolcore', timeoutMs = 10000, si
         signal?.addEventListener('abort', abort, { once: true });
     const timer = setTimeout(abort, timeoutMs);
     try {
-        const res = await fetch(`https://registry.npmjs.org/${pkg}/latest`, {
+        const res = await fetch(`${normalizeRegistry(registry)}/${encodeURIComponent(pkg)}/latest`, {
             signal: controller.signal,
             headers: { 'Accept': 'application/json' },
         });
         if (!res.ok)
             return null;
         const data = await res.json();
-        return data.version || null;
+        return typeof data.version === 'string' && data.version ? data.version : null;
     }
     catch {
         return null;
@@ -178,6 +276,31 @@ export async function checkLatestVersion(pkg = 'evolcore', timeoutMs = 10000, si
         signal?.removeEventListener('abort', abort);
     }
 }
+/**
+ * Read the current npm registry first. If that read succeeds, npm itself is
+ * used for the version query so proxy/CA/auth settings are preserved. If the
+ * read fails, retry once against the official HTTP endpoint. The selected
+ * registry is returned so installation uses the same source.
+ */
+async function checkLatestVersionWithFallback(pkg, timeoutMs, signal, explicitRegistry) {
+    if (explicitRegistry) {
+        const registry = normalizeRegistry(explicitRegistry);
+        const version = await fetchLatestVersion(pkg, timeoutMs, signal, registry);
+        return version ? { version, registry } : null;
+    }
+    const selection = await resolveUpgradeRegistry(signal);
+    const version = selection.useNpmCli
+        ? await checkLatestVersionViaNpm(pkg, timeoutMs, signal, selection.registry)
+        : await fetchLatestVersion(pkg, timeoutMs, signal, selection.registry);
+    return version ? { version, registry: selection.registry } : null;
+}
+/**
+ * Query the registry selected from the running Node/npm configuration, or the
+ * official registry when that configuration cannot be read.
+ */
+export async function checkLatestVersion(pkg = 'evolcore', timeoutMs = 10000, signal, registry) {
+    return (await checkLatestVersionWithFallback(pkg, timeoutMs, signal, registry))?.version ?? null;
+}
 /**
  * 完整升级流程：检查 → 比较 → 安装（失败重试一次）
  */
@@ -188,12 +311,13 @@ export async function tryUpgrade(options = {}) {
     }
     const localVer = getLocalVersion();
     // 查询 registry
-    const remoteVer = await checkLatestVersion('evolcore', options.checkTimeoutMs, options.signal);
-    if (!remoteVer) {
+    const checked = await checkLatestVersionWithFallback('evolcore', options.checkTimeoutMs, options.signal, options.registry);
+    if (!checked) {
         return options.signal?.aborted
             ? { status: 'failed', from: localVer, error: 'Upgrade cancelled or timed out' }
             : { status: 'skipped', error: 'Failed to check remote version' };
     }
+    const { version: remoteVer, registry } = checked;
     // 版本比较
     if (compareVersions(localVer, remoteVer) >= 0) {
         return { status: 'no-update', from: localVer };
@@ -202,11 +326,19 @@ export async function tryUpgrade(options = {}) {
     let lastError;
     for (let attempt = 0; attempt < 2; attempt++) {
         try {
-            await npmInstallGlobal('evolcore@latest', {
-                timeoutMs: options.installTimeoutMs,
-                signal: options.signal,
+            let installedVer;
+            await withGlobalInstallLock(async () => {
+                await npmInstallGlobal(`evolcore@${remoteVer}`, {
+                    timeoutMs: options.installTimeoutMs,
+                    signal: options.signal,
+                    registry,
+                });
+                installedVer = getLocalVersion();
             });
-            return { status: 'upgraded', from: localVer, to: remoteVer };
+            if (!installedVer || compareVersions(installedVer, remoteVer) < 0) {
+                throw new Error(`npm install completed but evolcore is still ${installedVer ?? 'not installed'} (target ${remoteVer})`);
+            }
+            return { status: 'upgraded', from: localVer, to: installedVer };
         }
         catch (e) {
             lastError = e.stderr || e.message || String(e);
@@ -230,23 +362,32 @@ export async function tryUpgradeGlobalPkg(resolveInstalled, pkgName, options = {
         return { status: 'skipped' }; // not installed, skip
     }
     const localVer = installed.version;
-    const remoteVer = await checkLatestVersion(pkgName, options.checkTimeoutMs, options.signal);
-    if (!remoteVer) {
+    const checked = await checkLatestVersionWithFallback(pkgName, options.checkTimeoutMs, options.signal, options.registry);
+    if (!checked) {
         return options.signal?.aborted
             ? { status: 'failed', from: localVer, error: 'Upgrade cancelled or timed out' }
             : { status: 'skipped', error: 'Failed to check remote version' };
     }
+    const { version: remoteVer, registry } = checked;
     if (compareVersions(localVer, remoteVer) >= 0) {
         return { status: 'no-update', from: localVer };
     }
     let lastError;
     for (let attempt = 0; attempt < 2; attempt++) {
         try {
-            await npmInstallGlobal(`${pkgName}@latest`, {
-                timeoutMs: options.installTimeoutMs,
-                signal: options.signal,
+            let installedVer;
+            await withGlobalInstallLock(async () => {
+                await npmInstallGlobal(`${pkgName}@${remoteVer}`, {
+                    timeoutMs: options.installTimeoutMs,
+                    signal: options.signal,
+                    registry,
+                });
+                installedVer = resolveInstalled()?.version;
             });
-            return { status: 'upgraded', from: localVer, to: remoteVer };
+            if (!installedVer || compareVersions(installedVer, remoteVer) < 0) {
+                throw new Error(`npm install completed but ${pkgName} is still ${installedVer ?? 'not installed'} (target ${remoteVer})`);
+            }
+            return { status: 'upgraded', from: localVer, to: installedVer };
         }
         catch (e) {
             lastError = e.stderr || e.message || String(e);

package/kits/docs/context-assembly.md

@@ -290,6 +290,7 @@ coding 场景（无 channel/无身份）下，`chatType`、`channel`、`selfAid`
 | 10 | rules | 目录 `$KITS_RULES` | always | ✗ |
 | 20 | identity-layer | fragment | chatType≠null | ✓ |
 | 21 | persona | `$PERSONAL_DIR/persona.md` | chatType≠null | ✗ |
+| 21.5 | personal-profile | `$PERSONAL_DIR/personal.md` | chatType≠null | ✗ |
 | 22 | working-memory | `$PERSONAL_DIR/memory/working.md` | chatType≠null | ✗ |
 | 30 | relation-layer | fragment | chatType∈{private,group} | ✓ |
 | 35 | peer-profile | `$RELATIONS_DIR/{{peerKey}}/profile.md` | peerKey≠null | ✗ |

package/kits/docs/evolcore/INDEX.md

@@ -24,6 +24,8 @@
 | `ec logs` | 查看日志（`--level` `--module` `--raw` `--no-color`） | 日志/查看日志 |
 | `ec diagnose` | 诊断启动环境 | 诊断/环境诊断 |
 
+Windows 上 Codex 托管任务出现 `helper_sandbox_lock_failed`、`SetNamedSecurityInfoW ... 5`、`unelevated ... cannot enforce deny-read` 或 daemon 管道 `EPERM` 时，参见 `codex-windows-sandbox.md`。
+
 ## 对外通信 / 网络类（连 AUN，以 AID 为发送者）
 
 | 命令集 | 用途 | 触发词 | 适用场景 | 文档 |
@@ -37,7 +39,7 @@
 | `ec agent` | EvolAgent 生命周期 | 创建/启停/热重载/改配置 | 管理员（owner/admin） | `agent.md`；完整创建与 Bootstrap 见 `agent-create.md` |
 | `ec contact` | Contact Book 与访问控制 | 申请添加、拉黑/解除拉黑、查拉黑 | Agent 当前私聊可申请添加；管理写操作按角色限制 | `contact.md` |
 | `ec rpc` | 底层 AUN RPC（逃生通道） | 直接调协议方法 | 高级/兜底 | `rpc.md` |
-| `ec menu-client` | 远程 Daemon Menu 请求 | 远程诊断/daemon 日志/监控/原始配置 | 非托管 eclink/运维主机 | `menu-client.md` |
+| `ec menu-client` | 远程 Daemon Menu 请求 | 远程诊断/daemon 日志/监控/原始配置 | 运维主机或具备 `ec.menu.request` 权限的托管 Agent | `menu-client.md` |
 
 ## 会话自管理类（不连 AUN，操作当前会话）
 

package/kits/docs/evolcore/agent-create.md

@@ -1,11 +1,15 @@
 # 创建 EvolAgent：从创建到 Bootstrap 完成
 
-本手册用于创建一个能正常工作的 EvolAgent。创建者负责创建和观察状态；新 Agent 在自己的 Bootstrap 会话中完成首次设定。不要把创建流水线完成误认为 Agent 已激活。
+本手册用于创建一个能正常工作的 EvolAgent。创建可以由人类直接发起，也可以由已有 Agent 代办：已有 Agent 负责收集信息、创建配置并观察状态；新 Agent 仍在自己的 Bootstrap 会话中修改名片并执行 `ready`。不要把创建流水线完成误认为 Agent 已激活。
 
 ### AID 与 Owner 约定
 
 - AID 必须是 `{name}.{issuer}`，例如 `helper.agentid.cn`；不要使用四级域名（如 `helper.team.agentid.cn`），也不要把显示名当作 AID。
-- `--owner` 填写需求提出者或实际责任 Owner 的完整 AID，而不是默认填写当前执行者。创建者只是代办创建流程时，仍应保留需求提出者的 Owner 权限。
+- `--owner` 保留现有单个 Owner 参数。
+- `--owners` 是有序 Owner 数组；Owner AID 必须使用完整 AID。代办创建时，当前创建 Agent 必须放在第一位，再把它自己的 Owner 放在后面；第一位 Owner 接收新 Agent 的 Bootstrap 首条消息。
+- 通过托管委托创建时，创建者必须显式把原始需求 Owner 写入 `--owners`；若需要创建 Agent 继续代办 Bootstrap，应将创建 Agent 放在 `owners[0]`，原始需求 Owner 放在后续位置。代码不会自动补齐 Owner。
+- `--owner` 与 `--owners` 互斥；未指定 `--owners` 时，现有 `--owner` 行为保持不变。
+- `--handoff <上下文>` 只附着在当前创建 Agent 的任务上，用于把已收集的 Bootstrap 信息注入该 Agent 后续处理新 Agent Bootstrap 首条消息的上下文。它不是发给新 Agent 的消息，也不要求新 Agent 返回或绑定任何 handoff。
 
 ## 生命周期与完成标准
 
@@ -25,23 +29,31 @@ active
 
 多个 Agent 必须串行创建和观察。不要并行启动多个 `ec agent new`：证书、热加载和 Bootstrap 会竞争连接与资源，容易造成超时、锁等待或把失败误判为未创建。
 
-在独立终端可以使用交互模式：
+在人类直接创建时，可以使用交互模式：
 
 ```bash
 ec agent new helper.agentid.pub
 ```
 
-在 EvolCore 托管 Agent 会话等自动化环境中，必须使用非交互模式：
+在 EvolCore 托管 Agent 会话等自动化环境中，必须使用非交互模式。代办创建时，先按照 Bootstrap 要求向自己的 Owner 收集显示名 `name`、一到两句话的 `description`、3 到 6 个非空 `tags`，再把结果放入 `--handoff`：
 
 ```bash
 ec agent new helper.agentid.pub --non-interactive \
   --project /home/user/helper-project \
   --baseagent codex \
-  --owner owner.agentid.pub \
+  --owners '["helper-creator.agentid.pub","owner.agentid.pub"]' \
   --name "Helper" \
-  --description "协助处理项目开发任务"
+  --description "协助处理项目开发任务" \
+  --tags '["coding","diagnostics","logs"]' \
+  --handoff '供当前创建 Agent 使用的 Bootstrap 上下文：已向 Owner 确认 name=Helper；description=协助处理项目开发任务；tags=coding, maintenance, typescript。目标 Agent 不会看到此上下文；创建 Agent 收到其 Bootstrap 首条消息时，以这些信息作为 Owner 回复并完成验收。'
 ```
 
+Bootstrap 完成前，Owner 可选地提供 persona 内容：直接发送文本，或发送 `.md`/`.txt` 文件。新 Agent 在确认后使用 `ec agent persona --text '<内容>'` 或 `ec agent persona --file '<路径>'` 写入自己的 `$PERSONAL_DIR/persona.md`；未提供 persona 不影响 `ready`。创建者不能借此替代 Bootstrap 中对 `agent.md` 的 Owner 确认。
+
+如果新 Agent 向 Agent/AI Owner 发送 Bootstrap 消息时收到“不是联系人”或联系人准入拒绝，应只发送一次 `/request <申请说明>` 申请添加联系人，说明这是新 Agent 的 Bootstrap 首次设定，并等待 Owner 审核；不要反复重试、修改全局联系人策略或联系其它对象。Owner 直接向新 Agent 发消息时，按该入站消息继续 Bootstrap。
+
+`--owners` 只用于需要多个 Owner 的创建；普通多 Owner 创建可按实际责任关系排列顺序。使用 `--handoff` 代办创建时，当前创建 Agent 必须是 `owners[0]`。`--handoff` 的内容只在创建 Agent 的当前任务中保存和注入，目标 Agent 不会看到该参数。
+
 建议先用 dry-run 检查最终参数：
 
 ```bash
@@ -61,6 +73,8 @@ ec agent get helper.agentid.pub lifecycle
 ec agent show helper.agentid.pub
 ```
 
+创建成功后，若 Owner 是本机托管 Agent，创建流程会把新 Agent AID 自动写入该 Owner 的联系人簿；远程或人类 Owner 没有本机联系人簿时跳过。创建者仍应核对首位 Owner 的联系人状态，确保 Bootstrap 回复可达。
+
 如果是 menu 创建，`accepted=true` 只表示请求已受理。继续轮询 `createProgress.status` 直到 `ready` 或 `failed`。这里的 `createProgress.status=ready` **只表示后台创建流水线结束，不等于 `lifecycle=active`**。
 
 创建者应维护一个最小状态账本（可放在当前任务记录中），每个 Agent 至少记录：`aid`、需求 Owner、项目路径、创建请求是否受理、`createProgress.status`、`lifecycle`、本地 `agent.md` 是否存在/字段是否完整、名片是否已发布、最近错误、下一步和最后检查时间。重启或超时恢复时先按账本逐项核对实际状态，再决定续做，不按“上次命令是否返回”推断结果。
@@ -75,13 +89,13 @@ ec agent show helper.agentid.pub
 
 ## 3. Owner 与新 Agent 确认名片信息
 
-以下步骤发生在**新 Agent 自己的 Bootstrap 会话**中，不由创建者代替执行。
+以下步骤发生在**新 Agent 自己的 Bootstrap 会话**中，不由创建者代替执行。若第一位 Owner 是代办创建的 Agent，它可以使用当前任务中注入的 `--handoff` 上下文代替人类回复；这不改变 Bootstrap 的确认规则。
 
 新 Agent 先读取系统注入路径指向的本地 `agent.md`，把其中格式有效的字段作为现有候选值：
 
 - `name`：简短清晰的显示名
 - `description`：一句到两句话描述职责或定位
-- `tags`：3 到 6 个非空标签
+- `tags`：3 到 6 个非空标签；每个标签只允许 Unicode 字母、数字和连字符（`-`），最长 50 字符
 
 交互规则：
 
@@ -131,8 +145,8 @@ ec agent ready helper.agentid.pub
 
 1. 将 `lifecycle` 切换为 `active`。
 2. 结束当前 Bootstrap 上下文。
-3. 创建全新的主会话。
-4. 发送正式欢迎消息。
+3. 为每位 Owner 创建全新的主会话。
+4. 向全部 Owner 发送正式欢迎消息，并为各 Owner 绑定对应的新会话。
 
 新 Agent 在 `ready` 成功后不要从旧 Bootstrap 上下文再输出一段完成说明，也不要继续处理先前夹带的普通任务；后续工作从新主会话开始。
 
@@ -147,10 +161,15 @@ ec agent show helper.agentid.pub
 
 验证其它 Agent 的生命周期、配置和创建进度统一使用 `ec agent get/show/list`；`ec aid` 只用于身份、证书和名片操作，不要用 `ec aid` 代替 Agent 状态验证。
 
+Bootstrap 首条消息只发送给 `owners[0]`；`ready` 成功后，正式欢迎消息发送给配置中的全部 Owner。
+
+使用 `--handoff` 代办创建时，创建 Agent 在与新 Agent 的会话中完成验收后，执行 `ec handoff return --content '<验收结果>'`，将结果回流至自己与原需求 Owner 的会话；该步骤不由新 Agent 执行。
+
 验收标准：
 
-- `lifecycle` 为 `active`。
+- `lifecycle` 为 `active`；`ec agent show` 的 `lifecycle` 字段也必须为 `active`。
 - `agent.md` 已成功签名发布。
+- 本地与远端 `agent.md` 的 `name`、`description`、`tags` 与 Owner 确认值一致；创建流程 skill 必须在发布后复读核验，不以初始上传响应代替。
 - 系统已创建新的主会话并发送正式欢迎消息。
 - 新 Agent 能在新主会话中处理普通任务。