evolcore 0.0.2 → 0.0.3

package/dist/trigger/scheduler.js

@@ -729,7 +729,9 @@ export class TriggerRuntimeScheduler {
             return { branch: branchFromReply(reply), script: null, processing, reply };
         }
         try {
-            const runtimeBaseagent = this.runtime.getBaseagent?.() || this.runtime.baseagent;
+            const runtimeBaseagent = definition.execution.baseagent
+                ?? this.runtime.getBaseagent?.()
+                ?? this.runtime.baseagent;
             const originPath = causation.trigger?.path ?? [];
             logger.info(`[Trigger] execution context triggerId=${definition.id}`
                 + ` triggerRunId=${runId}`

package/dist/trigger/validation.js

@@ -360,6 +360,7 @@ function normalizeExecution(value, _opts) {
         prompt: type === 'script' ? optionalString(raw.prompt) : requiredString(raw.prompt, 'execution.prompt'),
         script: type === 'script' ? normalizeScript(raw.script) : undefined,
         thread: type === 'trigger_session' ? (thread ?? 'by_trigger') : thread,
+        baseagent: normalizeExecutionBaseagent(raw.baseagent),
         model: optionalString(raw.model),
         effort: normalizeEffort(raw.effort),
         permissionMode: normalizeTriggerPermissionMode(raw.permissionMode),
@@ -368,6 +369,14 @@ function normalizeExecution(value, _opts) {
     };
     return execution;
 }
+function normalizeExecutionBaseagent(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new Error('execution.baseagent must be a non-empty string');
+    }
+    return value.trim();
+}
 function normalizeExecutionThread(value) {
     const thread = optionalString(value);
     if (thread === undefined)
@@ -533,6 +542,8 @@ function validateTriggerSemantics(definition) {
             throw new Error('execution.prompt is not allowed when execution.type=script');
         if (execution.thread !== undefined)
             throw new Error('execution.thread is not allowed when execution.type=script');
+        if (execution.baseagent !== undefined)
+            throw new Error('execution.baseagent is only allowed when execution.type=trigger_session');
     }
     if (execution.type === 'trigger_session') {
         if (!execution.prompt)
@@ -547,6 +558,8 @@ function validateTriggerSemantics(definition) {
             throw new Error('execution.script is not allowed when execution.type=target_session');
         if (execution.thread !== undefined)
             throw new Error('execution.thread is not allowed when execution.type=target_session');
+        if (execution.baseagent !== undefined)
+            throw new Error('execution.baseagent is only allowed when execution.type=trigger_session');
         if (definition.feedback.strategy === 'silent')
             throw new Error('feedback.strategy=silent is not allowed when execution.type=target_session');
     }

package/dist/utils/aid-bind.js

@@ -133,56 +133,70 @@ export class BindService {
             return fail('TASK_NOT_FOUND', 'binding task not found');
         if (payload.bindType !== task.bindType)
             return fail('BIND_TYPE_MISMATCH', 'bindType mismatch');
-        if (Date.now() > task.expiresAt) {
+        if (!fromAid)
+            return fail('INTERNAL_ERROR', 'missing AUN sender');
+        if (task.status === 'pending' && Date.now() > task.expiresAt) {
             task.status = 'expired';
             task.finishedAt ??= task.expiresAt;
             return fail('TASK_EXPIRED', 'binding task expired');
         }
-        if (task.status === 'bound')
+        if (task.status === 'bound') {
+            // The owner write and task transition necessarily happen before the caller
+            // can send bind.response. If that send fails, the App retries the same
+            // authenticated request. Replay the original success only to the AID that
+            // completed the bind; other senders must not receive daemonInfo.
+            if (task.boundAid === fromAid && task.boundResponse)
+                return task.boundResponse;
             return fail('ALREADY_BOUND', 'binding task already completed');
+        }
         if (task.status !== 'pending')
             return fail('TASK_NOT_FOUND', 'binding task is not pending');
         if (!timingSafeTokenEqual(payload.token, task.tokenHash)) {
             return fail('INVALID_TOKEN', 'invalid token');
         }
-        if (!fromAid)
-            return fail('INTERNAL_ERROR', 'missing AUN sender');
         try {
+            // Build and retain the exact response before committing the bind so a
+            // post-commit transport failure can be recovered by an idempotent retry.
+            const response = this.buildSuccessResponse(task);
             this.applyOwnerBinding(task, fromAid);
             task.status = 'bound';
             task.boundAid = fromAid;
             task.boundName = payload.clientName;
+            task.boundResponse = response;
             task.finishedAt = Date.now();
-            const details = task.bindType === 'agent' ? this.buildAgentBindDetails(task) : null;
-            return {
-                type: 'bind.response',
-                bindType: task.bindType,
-                success: true,
-                daemonInfo: {
-                    daemonAid: task.receiverAid,
-                    ...(task.bindType === 'agent' ? { agentAid: task.targetAid } : {}),
-                    bindType: task.bindType,
-                    ...(task.bindType === 'daemon'
-                        ? {
-                            version: readEvolcoreVersion(),
-                            platform: getPlatform(),
-                            uptime: this.opts.getUptimeSeconds(),
-                            baseagents: this.opts.getAvailableBaseagents(),
-                        }
-                        : {
-                            active_baseagent: details.baseagent.active_baseagent,
-                            model: details.baseagent.model,
-                            effort: details.baseagent.effort,
-                            channels: details.channels,
-                            agentName: task.agentName,
-                        }),
-                },
-            };
+            return response;
         }
         catch (e) {
             return fail('INTERNAL_ERROR', e?.message || String(e));
         }
     }
+    buildSuccessResponse(task) {
+        const details = task.bindType === 'agent' ? this.buildAgentBindDetails(task) : null;
+        return {
+            type: 'bind.response',
+            bindType: task.bindType,
+            success: true,
+            daemonInfo: {
+                daemonAid: task.receiverAid,
+                ...(task.bindType === 'agent' ? { agentAid: task.targetAid } : {}),
+                bindType: task.bindType,
+                ...(task.bindType === 'daemon'
+                    ? {
+                        version: readEvolcoreVersion(),
+                        platform: getPlatform(),
+                        uptime: this.opts.getUptimeSeconds(),
+                        baseagents: this.opts.getAvailableBaseagents(),
+                    }
+                    : {
+                        active_baseagent: details.baseagent.active_baseagent,
+                        model: details.baseagent.model,
+                        effort: details.baseagent.effort,
+                        channels: details.channels,
+                        agentName: task.agentName,
+                    }),
+            },
+        };
+    }
     buildAgentBindDetails(task) {
         const agent = loadAgent(task.targetAid);
         const config = resolveEffective({ self: task.targetAid }, { expand: true });

package/dist/utils/instance-registry.js

@@ -14,6 +14,7 @@ import { spawnSync } from 'child_process';
 import { resolvePaths } from '../paths.js';
 import { isProcessRunning, killProcess, isWindows, findProcesses } from './cross-platform.js';
 import { getProcessStartTime, startTimeMatches } from './process-introspect.js';
+import { isConfirmedLeakedTestDaemon, runtimeHomeFromEnv } from './restart-safety.js';
 // ── Helpers ──
 function instanceDir() {
     return resolvePaths().instanceDir;
@@ -339,10 +340,11 @@ function killPid(pid) {
  * 用途：检测跨 HOME 残留的 evolcore 主进程（例如测试套件 spawn 后未清理、
  * 旧版本 pidfile 模式遗留等），由 cmdStart/cmdRestart 在启动前提示用户。
  *
- * Linux 下额外读取 /proc/<pid>/environ 提取 EVOLCORE_HOME 用于展示。
+ * Linux 下额外读取 /proc/<pid>/environ 提取 EVOLCORE_HOME，
+ * 并对 Vitest 泄漏的 restart-monitor daemon 做严格标记。
  * Windows / macOS 取不到环境变量时 evolcoreHome 为 null。
  *
- * 不会主动 kill——清理由调用方决定（cmdRestart --kill-orphans 才执行）。
+ * 不会主动 kill——清理由调用方决定。
  */
 export function findOrphanProcesses() {
     // 1. 已登记 PID（自己 HOME 下的 main + 自己进程）
@@ -367,10 +369,12 @@ export function findOrphanProcesses() {
         // 三次验证：排除 ecweb（/ecweb/dist/index.js）
         if (/[\\/]ecweb[\\/]dist[\\/]index\.js/.test(cmdline))
             continue;
+        const processEnv = readProcessEnvironment(pid);
         orphans.push({
             pid,
-            evolcoreHome: readEvolcoreHome(pid),
+            evolcoreHome: processEnv ? runtimeHomeFromEnv(processEnv) : null,
             cmdline,
+            confirmedTestDaemon: processEnv ? isConfirmedLeakedTestDaemon(processEnv) : false,
         });
     }
     return orphans;
@@ -418,16 +422,19 @@ function readCmdline(pid) {
         }
     }
 }
-function readEvolcoreHome(pid) {
+function readProcessEnvironment(pid) {
     // Linux: /proc/<pid>/environ
     if (!isWindows && process.platform !== 'darwin') {
         try {
             const env = fs.readFileSync(`/proc/${pid}/environ`, 'utf-8');
+            const result = {};
             for (const entry of env.split('\0')) {
-                if (entry.startsWith('EVOLCORE_HOME='))
-                    return entry.slice('EVOLCORE_HOME='.length);
+                const separator = entry.indexOf('=');
+                if (separator <= 0)
+                    continue;
+                result[entry.slice(0, separator)] = entry.slice(separator + 1);
             }
-            return null;
+            return result;
         }
         catch {
             return null;

package/dist/utils/log-writer.js

@@ -24,6 +24,52 @@ import path from 'path';
 import { clearInterval as clearNativeInterval, clearTimeout as clearNativeTimeout, setInterval as setNativeInterval, setTimeout as setNativeTimeout, } from 'node:timers';
 const HOUR_MS = 60 * 60 * 1000;
 const DAY_MS = 24 * HOUR_MS;
+/**
+ * Rotate the daemon's redirected stdout before a launcher opens it for append.
+ * stdout is owned by the launcher rather than LogWriter, so both start and
+ * restart paths must call this after the previous daemon has exited.
+ */
+export function rotateStdoutLog(logDir, options = {}) {
+    const maxSize = options.maxSize ?? 10 * 1024 * 1024;
+    const retentionMs = options.retentionMs ?? 7 * DAY_MS;
+    const now = options.now ?? Date.now();
+    const stdoutLog = path.join(logDir, 'stdout.log');
+    let rotatedPath = null;
+    try {
+        if (fs.statSync(stdoutLog).size > maxSize) {
+            const timestamp = new Date(now).toISOString().replace(/[:.]/g, '').slice(0, 15);
+            const baseArchive = `${stdoutLog}.${timestamp}`;
+            let archive = baseArchive;
+            let suffix = 1;
+            while (fs.existsSync(archive))
+                archive = `${baseArchive}.${suffix++}`;
+            fs.renameSync(stdoutLog, archive);
+            rotatedPath = archive;
+        }
+    }
+    catch {
+        // Missing/unreadable stdout must not prevent the daemon from starting.
+    }
+    const removedArchives = [];
+    const cutoff = now - retentionMs;
+    try {
+        for (const name of fs.readdirSync(logDir)) {
+            if (!name.startsWith('stdout.log.'))
+                continue;
+            const full = path.join(logDir, name);
+            try {
+                const stat = fs.lstatSync(full);
+                if (stat.isSymbolicLink() || stat.mtimeMs < cutoff) {
+                    fs.unlinkSync(full);
+                    removedArchives.push(full);
+                }
+            }
+            catch { }
+        }
+    }
+    catch { }
+    return { rotatedPath, removedArchives };
+}
 export class LogWriter {
     baseName;
     logDir;

package/dist/utils/media-cache.js

@@ -183,7 +183,10 @@ export async function safeFetch(url, opts) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeout);
     try {
-        const res = await fetch(url, { signal: controller.signal });
+        const res = await fetch(url, {
+            signal: controller.signal,
+            redirect: opts?.rejectRedirects ? 'error' : 'follow',
+        });
         if (!res.ok)
             throw new Error(`Download failed: ${res.status} ${res.statusText}`);
         // 检查 Content-Length（如果可用）

package/dist/utils/model-prices.jsonl

@@ -3,9 +3,12 @@
 {"model":"claude-opus-4-6","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":15,"price_output":75,"price_cache_creation":18.75,"price_cache_read":1.5}
 {"model":"claude-sonnet-4-6","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":3,"price_output":15,"price_cache_creation":3.75,"price_cache_read":0.3}
 {"model":"claude-haiku-4-5-20251001","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":0.8,"price_output":4,"price_cache_creation":1,"price_cache_read":0.08}
-{"model":"gpt-5.5","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":2,"price_output":10,"price_cache_creation":0,"price_cache_read":0}
-{"model":"gpt-5.4","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":2,"price_output":10,"price_cache_creation":0,"price_cache_read":0}
-{"model":"gpt-5.3-codex","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":2,"price_output":10,"price_cache_creation":0,"price_cache_read":0}
+{"model":"gpt-5.6-sol","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":5,"price_output":30,"price_cache_creation":6.25,"price_cache_read":0.5,"tiers":[{"up_to_input_tokens":272000,"price_input":5,"price_output":30,"price_cache_creation":6.25,"price_cache_read":0.5},{"up_to_input_tokens":null,"price_input":10,"price_output":45,"price_cache_creation":12.5,"price_cache_read":1}]}
+{"model":"gpt-5.6-terra","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":2.5,"price_output":15,"price_cache_creation":3.125,"price_cache_read":0.25,"tiers":[{"up_to_input_tokens":272000,"price_input":2.5,"price_output":15,"price_cache_creation":3.125,"price_cache_read":0.25},{"up_to_input_tokens":null,"price_input":5,"price_output":22.5,"price_cache_creation":6.25,"price_cache_read":0.5}]}
+{"model":"gpt-5.6-luna","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":1,"price_output":6,"price_cache_creation":1.25,"price_cache_read":0.1,"tiers":[{"up_to_input_tokens":272000,"price_input":1,"price_output":6,"price_cache_creation":1.25,"price_cache_read":0.1},{"up_to_input_tokens":null,"price_input":2,"price_output":9,"price_cache_creation":2.5,"price_cache_read":0.2}]}
+{"model":"gpt-5.5","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":5,"price_output":30,"price_cache_creation":0,"price_cache_read":0.5,"tiers":[{"up_to_input_tokens":272000,"price_input":5,"price_output":30,"price_cache_creation":0,"price_cache_read":0.5},{"up_to_input_tokens":null,"price_input":10,"price_output":45,"price_cache_creation":0,"price_cache_read":1}]}
+{"model":"gpt-5.4","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":2.5,"price_output":15,"price_cache_creation":0,"price_cache_read":0.25,"tiers":[{"up_to_input_tokens":272000,"price_input":2.5,"price_output":15,"price_cache_creation":0,"price_cache_read":0.25},{"up_to_input_tokens":null,"price_input":5,"price_output":22.5,"price_cache_creation":0,"price_cache_read":0.5}]}
+{"model":"gpt-5.3-codex","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":1.75,"price_output":14,"price_cache_creation":0,"price_cache_read":0.175}
 {"model":"deepseek-v4-pro","effective_from":0,"billing_fn":"per_token_deepseek_v1","currency":"CNY","price_cache_hit":0.5,"price_cache_miss":2,"price_output":8}
 {"model":"deepseek-v4-flash","effective_from":0,"billing_fn":"per_token_deepseek_v1","currency":"CNY","price_cache_hit":0.1,"price_cache_miss":0.5,"price_output":2}
 {"model":"deepseek-v3.2","effective_from":0,"billing_fn":"per_token_deepseek_v1","currency":"CNY","price_cache_hit":0.5,"price_cache_miss":2,"price_output":8}

package/dist/utils/restart-safety.js

@@ -0,0 +1,31 @@
+const REAL_RESTART_TEST_OVERRIDE = 'EVOLCORE_ALLOW_REAL_RESTART_IN_TEST';
+export function isRestartTestRuntime(env = process.env) {
+    return env.VITEST === 'true'
+        || env.EVOLCORE_TEST === '1';
+}
+/**
+ * Unit tests must never detach a real restart-monitor/daemon pair by accident.
+ * Dedicated process-level integration tests can opt in explicitly.
+ */
+export function shouldSuppressRealRestart(env = process.env) {
+    return isRestartTestRuntime(env) && env[REAL_RESTART_TEST_OVERRIDE] !== '1';
+}
+export function runtimeHomeFromEnv(env) {
+    return env.EVOLCORE_HOME || null;
+}
+/**
+ * Strict classifier used before automatically killing leaked test daemons.
+ * All markers must agree so a legitimate secondary runtime is never mistaken
+ * for a disposable test process.
+ */
+export function isConfirmedLeakedTestDaemon(env) {
+    const home = runtimeHomeFromEnv(env);
+    if (!home || !/[\\/]evolcore-test-[^\\/]+$/.test(home))
+        return false;
+    const launchedBy = env.EVOLCORE_LAUNCHED_BY;
+    const testRuntime = env.VITEST === 'true'
+        || env.EVOLCORE_TEST === '1';
+    return testRuntime
+        && env.NODE_ENV === 'test'
+        && launchedBy === 'restart-monitor';
+}

package/dist/utils/system-memory.js

@@ -0,0 +1,62 @@
+import fs from 'fs';
+import os from 'os';
+function readNumber(filePath) {
+    try {
+        const value = Number(fs.readFileSync(filePath, 'utf8').trim());
+        return Number.isFinite(value) && value >= 0 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function parseCgroupV2MemoryStat(input) {
+    const values = new Map();
+    for (const line of input.split('\n')) {
+        const [key, raw] = line.trim().split(/\s+/, 2);
+        const value = Number(raw);
+        if (key && Number.isFinite(value) && value >= 0)
+            values.set(key, value);
+    }
+    return values;
+}
+/**
+ * System memory for the current container/host namespace.
+ *
+ * Linux cgroup v2 uses memory.current - memory.stat:file so the value matches
+ * common host/container dashboards: anonymous + kernel memory, excluding
+ * reclaimable filesystem page cache. Other environments fall back to the
+ * portable total - available calculation exposed by Node.js.
+ */
+export function readSystemMemoryUsage(cgroupRoot = '/sys/fs/cgroup') {
+    const memTotal = os.totalmem();
+    const memAvailable = os.freemem();
+    if (process.platform === 'linux') {
+        const current = readNumber(`${cgroupRoot}/memory.current`);
+        if (current !== null) {
+            try {
+                const stat = parseCgroupV2MemoryStat(fs.readFileSync(`${cgroupRoot}/memory.stat`, 'utf8'));
+                const fileCache = stat.get('file');
+                if (fileCache !== undefined) {
+                    const memUsed = Math.max(0, current - fileCache);
+                    return {
+                        memTotal,
+                        memUsed,
+                        memFree: Math.max(0, memTotal - memUsed),
+                        memAvailable,
+                        memorySource: 'cgroup-v2-current-minus-file',
+                        cgroupCurrent: current,
+                        fileCache,
+                    };
+                }
+            }
+            catch { /* fall through to portable OS metrics */ }
+        }
+    }
+    return {
+        memTotal,
+        memUsed: Math.max(0, memTotal - memAvailable),
+        memFree: memAvailable,
+        memAvailable,
+        memorySource: 'os-total-minus-available',
+    };
+}

package/kits/docs/INDEX.md

@@ -25,6 +25,7 @@
 | 文档 | 路径 | 说明 |
 |------|------|------|
 | 命令集目录 | `evolcore/INDEX.md` | msg/group/agent/aid/storage/ctl/rpc/bench 全集索引 |
+| 联系人命令 | `evolcore/contact.md` | Contact Book 拉黑与托管会话权限边界 |
 
 ## 身份
 
@@ -46,7 +47,7 @@
 
 | 文档 | 路径 | 说明 |
 |------|------|------|
-| Trigger 命令手册 | `evolcore/trigger.md` | 创建、管理、运行定时与事件 trigger |
+| Trigger 命令手册 | `evolcore/trigger.md` | 使用 `create` 创建并管理、运行定时与事件 trigger；`set` 为兼容别名 |
 | EventBus 事件目录 | `evolcore/event.md` | event source 可监听事件、payload、filter 与循环防护规则 |
 
 ## ECK 模板

package/kits/docs/evolcore/INDEX.md

@@ -4,8 +4,9 @@
 运行时 evolcore 会通过 `commands` fragment 按当前场景（有无 peer/group、对端角色）
 注入一张精简能力卡，指向本目录下对应文档；需要完整用法时 Read 对应文档。
 
-> 命令通用约定：以自己 AID 为发送者；必须走 CLI，不在会话里直接输出对外消息；
-> `--format json` 所有命令通用；`--app <name>` 指定应用 slot（独立消费通道）。
+> 对外通信命令以自己的 AID 为发送者；当前渠道是否需要 CLI 回复，以运行时注入的
+> `channel` 规则为准。参数不是全局通用的：`--format json` 仅用于对应帮助中明确支持的命令，
+> `--app <name>` 仅用于消息 pull/ack、消费类 RPC 和明确支持 app slot 的文件操作。
 
 ## 如何使用本索引
 
@@ -34,6 +35,7 @@
 | `ec fs` | AUN 文件系统统一入口 | 上传/下载/看文件/列目录/删文件/配额/群空间 | 任意有渠道场景 | `fs.md` |
 | `ec storage` | 文件存储底层调试入口 | storage 调试/旧命令/底层上传下载 | 任意有渠道场景 | `storage.md` |
 | `ec agent` | EvolAgent 生命周期 | 创建/启停/热重载/改配置 | 管理员（owner/admin） | `agent.md` |
+| `ec contact` | Contact Book 与访问控制 | 拉黑/解除拉黑/查拉黑 | Agent owner/admin | `contact.md` |
 | `ec rpc` | 底层 AUN RPC（逃生通道） | 直接调协议方法 | 高级/兜底 | `rpc.md` |
 
 ## 会话自管理类（不连 AUN，操作当前会话）
@@ -50,7 +52,7 @@
 | `ec response` | 响应模式管理（按作用域持久化） | 切换响应模式/列响应模式/看当前模式/改响应配置 | `response.md` |
 | `ec config` | 配置体系底层入口（读写/快照/回滚） | 看配置/改配置/查字段/查schema/校验/快照/回滚/历史/启动记录 | `config.md` |
 | `ec stats` | Token 用量与费用统计 | 用量/费用/统计/预算/token/cost | `stats.md` |
-| `ec trigger` | 定时与事件触发器管理 | 触发器/定时任务/cron/提醒/定时检查/自动执行/巡检/禁用 trigger/删除 trigger | `trigger.md` |
+| `ec trigger` | 定时与事件触发器管理（创建用 `create`，`set` 为兼容别名） | 触发器/定时任务/cron/提醒/定时检查/自动执行/巡检/禁用 trigger/删除 trigger | `trigger.md` |
 | `ec trigger event` | EventBus 事件目录 | 事件触发/事件目录/EventBus/source.type=event/filter.match | `event.md` |
 
 ## 开发者工具（非 agent 会话能力）

package/kits/docs/evolcore/agent.md

@@ -10,6 +10,8 @@ ec agent list
 
 # 查看 agent 详情（身份 + 配置 + 连接 + 会话 + 路径）
 ec agent show <aid>
+# 简写，等价于 show
+ec agent <aid>
 
 # 创建 agent（交互式）
 ec agent new [aid]
@@ -27,6 +29,12 @@ ec agent disable <aid>
 ec agent get <aid> <key>
 ec agent set <aid> <key> <val>
 
+# 修改 agent.md 显示名称
+ec agent rename <aid> "<name>"
+
+# 标记 bootstrap 完成，进入 active 状态
+ec agent ready <aid>
+
 # 热重载配置（无参数 = 全量 resync：扫磁盘，新增上线/删除下线/修改热更新）
 ec agent reload [aid]
 
@@ -65,5 +73,5 @@ ec agent delete <aid> [--purge]
 
 ## 通用约定
 
-- `--format json` — 输出 JSON
+- `--format json` — 用于 `list/show/new/enable/disable/get/set/rename/ready/reload/delete` 的结构化输出
 - `--help` / `-h` — 各子命令均支持，查看详细用法

package/kits/docs/evolcore/aid.md

@@ -12,7 +12,7 @@ ec aid list [筛选选项] [--no-verify]
 ec aid show <aid>
 
 # 创建新 AID 身份
-ec aid new <aid>
+ec aid new <aid> [--force]
 
 # 远程探测 AID（是否存在 + 网关 + agent.md）
 ec aid lookup <aid>
@@ -42,8 +42,11 @@ ec aid delete <aid>
 - `ec aid delete --orphan` — 清理无私钥的外部 AID 缓存
 - `ec aid delete --no-cert` — 清理无私钥也无公钥证书的孤儿目录
 - `ec aid delete --unrecoverable` — 清理云端公钥已变更、本地不可恢复的 AID
+- `--skip-pki` — 仅用于 `--unrecoverable`，跳过 PKI 探测并按本地自检结果判断；有误删风险
 
 ## 通用约定
 
-- `--format json` — 输出 JSON
+- `--format json` — 对支持结构化结果的子命令输出 JSON
+- `--aun-path <path>` — 指定 AUN keystore 根；未传时可由 `AUN_HOME` 提供
+- `aid delete --orphan|--no-cert|--unrecoverable` 默认 dry-run，`--yes` 才执行删除
 - `--help` / `-h` — 各子命令均支持

package/kits/docs/evolcore/contact.md

@@ -0,0 +1,57 @@
+# ec contact — Agent 联系人与访问控制
+
+`ec contact` 管理指定 Agent 的 Contact Book v2。它只接受 AUN AID 主键，并只负责 AUN 私聊拉黑状态；角色统一由 relation `config.json role` 管理。
+
+## 命令
+
+```bash
+ec contact block <aid> --self <agent-aid>
+ec contact unblock <aid> --self <agent-aid>
+ec contact list --blocked --self <agent-aid>
+```
+
+所有命令都要求显式 `--self`，支持 `--format json`。
+
+## 约束
+
+- `<aid>` 和 `--self` 必须是合法 AID。
+- `block/unblock` 只改变本 Agent 的入站接收策略，不代表对端也拉黑了本 Agent。
+- Agent owner 不能被拉黑。
+- `list --blocked` 只列出当前 blocked contact，并返回 `contactRevision`。
+
+## 权限边界
+
+直接从本机终端运行时，这是本地管理命令。
+
+从 Agent 活动任务执行时，CLI 不直接写文件，而是携带当前 session delegation token 调用 daemon `contact.op`：
+
+| 操作 | owner | admin | 普通角色 |
+|---|---:|---:|---:|
+| `list --blocked` | 允许 | 允许 | 拒绝 |
+| `block` / `unblock` | 允许 | 允许 | 拒绝 |
+
+缺少、伪造、撤销或跨会话 delegation token 时失败关闭。托管调用的 `--self` 必须等于当前任务所属 Agent。
+
+角色管理使用 Role Menu relation assignment；admin 的授予和撤销必须由 owner 执行。
+
+## JSON 输出
+
+拉黑成功：
+
+```json
+{
+  "ok": true,
+  "operation": "set-blocked",
+  "selfAid": "bot.agentid.pub",
+  "primaryId": "peer.agentid.pub",
+  "blocked": true,
+  "changed": true,
+  "contactRevision": "..."
+}
+```
+
+## 拉黑后的消息行为
+
+- AUN 外部入站在 MessageBridge 的业务入口被拦截，不进入 menu/auth/command/session/queue/LLM。
+- 对 `ai`、`bot`、`agent`、`service` 类型的私聊对端，可限频返回 `[rejection] Not accepting messages from you.`。
+- 入站正文中的 `[rejection]` 没有协议控制语义。发送者未被本 Agent 拉黑时，该文本正常进入响应式会话。

package/kits/docs/evolcore/fs.md

@@ -41,12 +41,15 @@ ec fs umount <AID>:<path>         # 卸载挂载点
 
 - `--format json`：结构化输出
 - `--as <aid>`：显式指定操作者
+- `--aun-path <path>`：指定 AUN keystore 根
+- `--app <name>`：指定 AUN app slot
 - `--overwrite` / `--force`：`cp/mv/ln` 覆盖目标；`rm` 强制删除
 - `-r` / `--recursive`：`rm/cp` 递归
 - `-p` / `--parents`：`mkdir` 自动创建父目录
 - `-L` / `--follow`：`stat` 跟随末级软链
 - `--token <token>`：读取 personal storage 时携带访问 token
 - `--content-type <mime>`：上传时指定 MIME
+- `--public`：上传后公开可读（personal storage）
 - `--max-bytes <n>`：`cat` 最大直接输出字节数，默认 1MB
 - `--head-bytes <n>`：`cat` 二进制头部字节数，默认 256
 - `--visibility public|private`：`chmod` 可见性
@@ -54,6 +57,12 @@ ec fs umount <AID>:<path>         # 卸载挂载点
 - `-m aid:<aid>:<perms>` / `-x aid:<aid>`：`setfacl` 增删 ACL
 - `--source <AID>:<path>` / `--volume <id>`：`mount` 来源
 - `--expires <time>`：`mount/token/ACL` 过期时间，Unix 秒或 ISO 日期
+- `--require-approval`：挂载需要来源 owner 审批
+- `--max-uses <n>`：ACL 最大使用次数
+- `--max-reads <n>`：访问 token 最大读取次数
+- `--readonly` / `--readwrite`：挂载为只读或读写
+- `--name <glob>` / `--type <f|d|l>`：`find` 名称或类型过滤
+- `--size <expr>` / `--mtime <expr>`：`find` 大小或修改时间过滤
 
 ## 示例
 

package/kits/docs/evolcore/group.md

@@ -38,11 +38,19 @@ ec group send <from> <group-id> "通知" --mention alice.agentid.pub,bob.agentid
 > 若正文**精确等于**某个 flag 名（如要发送文本 `--encrypt`），用 `--` 分隔：
 > `ec group send <from> <group-id> -- --encrypt`
 
+发送选项还包括：
+
+- `--no-encrypt`：强制明文，优先于 `--encrypt`
+- `--thread <id>`：指定话题 ID
+- `--return <required|none>`：跨会话回流策略
+- `--content-type <mime>`：覆盖文件 MIME
+- `--transcript <text>`：语音转写，仅 `--as voice`
+
 ## 群管理
 
 ```bash
 # 创建群
-ec group create <from> "<name>" [--visibility public|private] [--description "<desc>"] [--join-mode <mode>]
+ec group create <from> "<name>" [--visibility public|private] [--description "<desc>"] [--join-mode <mode>] [--group-id <aid>]
 
 # 列出我加入的群
 ec group list <from> [--size <N>]
@@ -126,8 +134,9 @@ ec group unban <from> <group-id> <member-aid>
 ## 通用约定
 
 - `<from>` 必须是合法 AID（入口统一校验，格式错直接报错）
-- `--format json` — 所有子命令通用
-- `--app <name>` — 指应用 slot（独立消费通道，不影响 daemon）
+- `--format json` — 对支持结构化结果的子命令输出 JSON
+- `--app <name>` — 仅 `pull` / `ack` 指定独立消费 slot
+- `--aun-path <path>` — 指定 AUN keystore 根
 - `--encrypt` — 仅 send，启用端到端加密（群聊默认明文）
 - `create` 会通过 SDK 自动生成并导入群 `group_aid` 身份。
 - `owner` 会走 SDK 的群主转让授权签名流程，需要本机有该群 `group_aid` 的私钥；若网关返回 `pending_rekey`，CLI 会在本机存在新群主私钥时自动调用完成步骤，否则输出“已发起，等待新群主完成 rekey”。

package/kits/docs/evolcore/model.md

@@ -14,7 +14,7 @@ ec model current [--self <aid>] [--peer <peer>] [--role <role>]
 # 查看单个模型详情
 ec model info <model-id> [--self <aid>]
 
-# 设置模型，可同时设置推理强度
+# 设置模型，可同时设置推理强度；本机终端写操作需要 --self
 ec model use <model-id> --self <aid> [--peer <peer>] [--effort <level>]
 
 # 设置推理强度：low | medium | high | xhigh | max | auto
@@ -38,6 +38,9 @@ ec model check [--self <aid>]
 
 生效优先级为关系、角色、agent、defaults。`--peer` 可使用 `channelType#channelId`；裸 AID 按 `aun#<aid>` 处理。
 
+在 EvolCore 托管会话中，省略 `--self`、`--peer`、`--role` 时，`list/current/use/effort/reset`
+会通过 `ec ctl` 作用于当前会话；显式 selector 仍按上表访问持久化作用域。本机终端不具备该隐式当前会话语义。
+
 ## 输出与权限
 
 - 所有子命令支持 `--format json`。