evolcore 0.0.21 → 0.0.22

package/dist/trigger/feedback.js

@@ -251,12 +251,24 @@ export class TriggerFeedbackDispatcher {
                     };
                 }
                 if (event?.type === 'trigger:skipped') {
+                    const interruption = event.executionState === 'interrupted' && event.decisionSource === 'infrastructure'
+                        ? {
+                            reasonCode: event.reasonCode ?? event.reason,
+                            decisionSource: event.decisionSource,
+                            executionState: event.executionState,
+                            ...(event.generation !== undefined ? { generation: event.generation } : {}),
+                            ...(event.currentGeneration !== undefined ? { currentGeneration: event.currentGeneration } : {}),
+                        }
+                        : undefined;
                     return {
-                        status: 'failed',
+                        status: interruption ? 'skipped' : 'failed',
                         reason: event.reason,
+                        ...(interruption ? { interruption } : {}),
                         feedback,
                         effects: [this.inboundEffect('success', target, session.id, startedAt)],
-                        error: { code: event.reason || 'target_session_skipped', message: event.reason || 'target session skipped' },
+                        error: interruption
+                            ? null
+                            : { code: event.reason || 'target_session_skipped', message: event.reason || 'target session skipped' },
                     };
                 }
                 return {

package/dist/trigger/parser.js

@@ -2,6 +2,7 @@ import { CronExpressionParser } from 'cron-parser';
 const TRIGGER_UPDATE_FLAGS = new Set([
     'once', 'delay', 'at', 'cron', 'every', 'event', 'tz',
     'prompt', 'name',
+    'script-file',
     'model', 'effort', 'permission',
     'max-runs', 'max-duration', 'concurrency', 'missed-policy',
 ]);
@@ -552,7 +553,7 @@ export function parseTriggerUpdateArgv(nameOrId, args, opts = {}) {
     const parsedFlags = flagsFromArgv(args, 'update');
     if (!parsedFlags.ok)
         return { ok: false, error: withPromptFileHint(parsedFlags.error, args, opts) };
-    const parsed = parseTriggerUpdateFlags(nameOrId, parsedFlags.flags, opts);
+    const parsed = parseTriggerUpdateFlags(nameOrId, parsedFlags.flags, { ...opts, allowScriptFile: true });
     return parsed.ok ? parsed : { ok: false, error: withPromptFileHint(parsed.error, args, opts) };
 }
 function flagsFromArgv(args, command) {
@@ -585,6 +586,9 @@ function parseTriggerUpdateFlags(nameOrId, flags, opts = {}) {
         if (!TRIGGER_UPDATE_FLAGS.has(flag))
             return { ok: false, error: `update 不支持参数 --${flag}` };
     }
+    if (flags.has('script-file') && !opts.allowScriptFile) {
+        return { ok: false, error: '--script-file 仅支持 ec trigger update CLI；请通过受控 CLI 上传脚本文件' };
+    }
     const parsed = commonParsed(flags, { update: true, ...opts });
     if (!parsed.ok)
         return parsed;
@@ -607,6 +611,11 @@ function parseTriggerUpdateFlags(nameOrId, flags, opts = {}) {
         update.name = value.name;
     if (value.prompt !== undefined)
         update.prompt = value.prompt;
+    const scriptFile = optionalFlagString(flags, 'script-file');
+    if ('error' in scriptFile)
+        return { ok: false, error: scriptFile.error };
+    if (scriptFile.value !== undefined)
+        update.scriptFile = scriptFile.value;
     if (value.model !== undefined)
         update.model = value.model;
     if (value.effort !== undefined)

package/dist/trigger/scheduler.js

@@ -120,12 +120,12 @@ export class TriggerRuntimeScheduler {
     }
     listItems(definitions) {
         const latestRuns = this.audit.latest(definitions.map(definition => definition.id));
-        return definitions.map(definition => this.buildListItem(definition, latestRuns.get(definition.id)));
+        return definitions.map(definition => this.buildListItem(definition, latestRuns.get(definition.id), this.stats(definition.id)));
     }
     listItem(definition) {
-        return this.buildListItem(definition, this.audit.recent(definition.id, 1)[0]);
+        return this.buildListItem(definition, this.audit.recent(definition.id, 1)[0], this.stats(definition.id));
     }
-    buildListItem(definition, lastRun) {
+    buildListItem(definition, lastRun, stats = this.stats(definition.id)) {
         const schedule = this.state.readSchedule(definition.id);
         return {
             id: definition.id,
@@ -139,6 +139,10 @@ export class TriggerRuntimeScheduler {
                 ...(definition.feedback.target ? { target: definition.feedback.target } : {}),
             },
             ...(schedule ? { nextFireAt: schedule.nextFireAt } : {}),
+            fireCount: stats.fireCount,
+            failCount: stats.failCount,
+            ...(stats.lastFiredAt !== undefined ? { lastFiredAt: stats.lastFiredAt } : {}),
+            ...(stats.lastResult ? { lastResult: stats.lastResult } : {}),
             ...(lastRun ? { lastStatus: lastRun.status, lastFinishedAt: lastRun.finishedAt } : {}),
             updatedAt: definition.updatedAt,
         };
@@ -627,6 +631,7 @@ export class TriggerRuntimeScheduler {
                 effects: feedbackResult.effects,
                 error: feedbackResult.error,
                 conflictRunId: feedbackResult.conflictRunId,
+                interruption: feedbackResult.interruption,
                 causation,
             });
             if (!payload.dryRun) {
@@ -1147,6 +1152,7 @@ export class TriggerRuntimeScheduler {
                 anomalies,
                 effects: feedbackResult.effects,
                 error: feedbackResult.error,
+                interruption: feedbackResult.interruption,
                 causation,
             });
             this.audit.write(audit);
@@ -1469,6 +1475,7 @@ export class TriggerRuntimeScheduler {
             status: input.status,
             reason: input.reason,
             conflictRunId: input.conflictRunId,
+            ...(input.interruption ? { interruption: input.interruption } : {}),
             ...(activeRun?.executionSessionId ? { executionSessionId: activeRun.executionSessionId } : {}),
             ...(attempts?.length ? { attempts } : {}),
             ...(finalAttempt ? { finalAttempt: finalAttempt.attempt } : {}),
@@ -1783,6 +1790,7 @@ export class TriggerRuntimeScheduler {
                 type: 'trigger:skipped',
                 ...base,
                 reason: audit.reason ?? 'skipped',
+                ...(audit.interruption ?? {}),
             });
         }
     }
@@ -1900,6 +1908,15 @@ function errorReply(runId, durationMs, reason, text) {
 }
 function attemptSummaryFromExecution(attempt, attemptId, execution) {
     if (execution.feedbackResult) {
+        if (execution.feedbackResult.interruption) {
+            return {
+                status: 'interrupted',
+                error: {
+                    code: execution.feedbackResult.interruption.reasonCode,
+                    message: execution.feedbackResult.reason ?? execution.feedbackResult.interruption.reasonCode,
+                },
+            };
+        }
         const failed = execution.feedbackResult.status !== 'completed';
         return {
             status: failed ? 'failed' : 'completed',

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 } from '../core/permission/tool-error-code.js';
+import { classifyToolErrorCode, normalizeToolErrorCode } from '../core/permission/tool-error-code.js';
 import { normalizePermissionMode } from '../core/permission/mode.js';
 import { buildToolLifecycleEventKey } from '../core/audit/event-key.js';
 let currentLevel = process.env.LOG_LEVEL || 'INFO';
@@ -95,8 +95,8 @@ export function normalizeStructuredLog(data) {
     const isToolUse = eventType === 'tool:use' || eventType === 'tool_use';
     const isError = data.isError ?? data.is_error ?? (data.ok === false ? true : undefined)
         ?? nested?.isError ?? nested?.is_error ?? (nested?.ok === false ? true : undefined);
-    const error = data.error ?? data.errorMessage ?? nested?.error ?? nested?.errorMessage;
-    const result = data.result ?? data.content ?? nested?.result ?? nested?.content;
+    const decisionSource = data.decisionSource ?? data.decision_source
+        ?? nested?.decisionSource ?? nested?.decision_source;
     const decision = data.decision
         ?? data.status
         ?? (isToolResult && isError === true ? 'error' : undefined)
@@ -113,8 +113,11 @@ export function normalizeStructuredLog(data) {
         ?? nested?.errorCode
         ?? nested?.error_code;
     const errorCode = isToolResult && isError === true
-        ? classifyToolErrorCode({ errorCode: explicitErrorCode, error, result })
+        ? classifyToolErrorCode({ errorCode: explicitErrorCode, decisionSource })
         : explicitErrorCode;
+    const classificationMissing = isToolResult && isError === true
+        && !normalizeToolErrorCode(explicitErrorCode)
+        && decisionSource !== 'policy' && decisionSource !== 'approval';
     const lifecycleRecord = isToolUse || isToolResult;
     const lifecycleEventKey = lifecycleRecord
         ? (eventKey ?? buildToolLifecycleEventKey({
@@ -137,10 +140,12 @@ export function normalizeStructuredLog(data) {
         ...(agentName ? { agentName } : lifecycleRecord ? { agentName: 'unknown' } : {}),
         ...(permissionMode ? { permissionMode } : lifecycleRecord ? { permissionMode: 'unknown' } : {}),
         ...(toolName ? { toolName } : {}),
+        ...(decisionSource ? { decisionSource } : {}),
         ...(decision ? { decision } : {}),
         ...(executed !== undefined ? { executed } : {}),
         ...(executionState ? { executionState } : {}),
         ...(errorCode ? { errorCode } : {}),
+        ...(classificationMissing ? { classificationMissing: true } : {}),
         ...(missingContextFields.length > 0 ? { contextMissing: missingContextFields } : {}),
     };
 }

package/dist/utils/tool-summary.js

@@ -5,6 +5,65 @@
  * Edit 工具的摘要为 diff 风格预览（支持 old/new_string 与 unified diff 两种输入）。
  */
 import fs from 'fs';
+import { parseLiteralShellArgv, resolveCodexShellCarrierString, } from '../core/permission/ec-command-parser.js';
+const DISPLAY_POSIX_SHELLS = new Set(['bash', 'sh']);
+const DISPLAY_POWERSHELLS = new Set(['pwsh', 'pwsh.exe', 'powershell', 'powershell.exe']);
+const DISPLAY_CMD_SHELLS = new Set(['cmd', 'cmd.exe']);
+const DISPLAY_CMD_INERT_SWITCHES = new Set(['/d', '/s', '/q', '/a', '/u']);
+function executableBasename(value) {
+    if (typeof value !== 'string')
+        return '';
+    return value.replaceAll('\\', '/').split('/').at(-1)?.toLowerCase() ?? '';
+}
+/** Display-only fallback for valid Codex carriers installed outside standard paths. */
+function summarizeDisplayCarrierArgv(argv) {
+    if (argv.length === 3) {
+        const executable = executableBasename(argv[0]);
+        const switchName = argv[1]?.toLowerCase();
+        if (DISPLAY_POSIX_SHELLS.has(executable) && switchName === '-lc')
+            return argv[2];
+        if (DISPLAY_POWERSHELLS.has(executable) && switchName === '-command')
+            return argv[2];
+    }
+    if (argv.length >= 3 && DISPLAY_CMD_SHELLS.has(executableBasename(argv[0]))) {
+        const executeIndex = argv.slice(1, -1).findIndex(value => value.toLowerCase() === '/c');
+        if (executeIndex >= 0 && executeIndex + 1 === argv.length - 2) {
+            const switches = argv.slice(1, executeIndex + 1);
+            if (switches.every(value => DISPLAY_CMD_INERT_SWITCHES.has(value.toLowerCase()))) {
+                return argv.at(-1);
+            }
+        }
+    }
+    return undefined;
+}
+/** Remove Codex app-server's fixed shell carrier from display-only arguments. */
+function displayShellCommand(command) {
+    if (typeof command !== 'string' || !command)
+        return undefined;
+    const parsedArgv = parseLiteralShellArgv(command);
+    const display = parsedArgv ? summarizeDisplayCarrierArgv(parsedArgv) : undefined;
+    if (display !== undefined)
+        return display;
+    // The nested PowerShell body is not POSIX shell syntax and can contain
+    // quotes, variables, redirects, and statement composition. Use the strict
+    // carrier parser only for PowerShell commands that the argv projection
+    // cannot parse; ordinary `bash -c` commands must remain unchanged.
+    const carrier = resolveCodexShellCarrierString(command);
+    return carrier?.dialect === 'powershell' ? carrier.command : undefined;
+}
+/**
+ * Build the tool arguments projected into activity/thought payloads.
+ * Execution, permission checks, and audit logging keep using the original
+ * input; only the human-facing Shell command is de-wrapped here.
+ */
+export function toolInputForDisplay(toolName, input) {
+    if (!input || toolName !== 'Shell')
+        return input;
+    const command = displayShellCommand(input.command);
+    if (!command || command === input.command)
+        return input;
+    return { ...input, command };
+}
 /**
  * 工具输入摘要（提取工具调用的可读描述，供权限审批和消息展示使用）
  */

package/dist/utils/windows-shell-trust.js

@@ -0,0 +1,201 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+const MAX_CACHE_ENTRIES = 128;
+const signatureCache = new Map();
+/**
+ * The signer name is checked only after Authenticode reports a trusted chain.
+ * Keep this list deliberately small: an unsigned or unknown Bash distribution
+ * must not enter the privileged EC command path.
+ */
+const MICROSOFT_PUBLISHER_RE = /(?:^|[,;]\s*)CN=Microsoft (?:Corporation|Windows(?: [^,;]+)?)(?:[,;]|$)/i;
+const MICROSOFT_ORG_RE = /(?:^|[,;]\s*)O=Microsoft Corporation(?:[,;]|$)/i;
+const BASH_PUBLISHER_RES = [
+    /(?:^|[,;]\s*)(?:CN|O)=Git for Windows(?:[,;]|$)/i,
+    /(?:^|[,;]\s*)(?:CN|O)=The Git Development Community(?:[,;]|$)/i,
+    // Git for Windows binaries are currently signed by project maintainer
+    // Johannes Schindelin rather than a certificate named after the project.
+    /(?:^|[,;]\s*)(?:CN|O)=Johannes Schindelin(?:[,;]|$)/i,
+    /(?:^|[,;]\s*)(?:CN|O)=Red Hat,? Inc\.(?:[,;]|$)/i,
+    /(?:^|[,;]\s*)(?:CN|O)=MSYS2(?:[,;]|$)/i,
+];
+function isValidStatus(status) {
+    return typeof status === 'string' && status.trim().toLowerCase() === 'valid';
+}
+/** Pure signature policy, separately testable without a Windows host. */
+export function isTrustedShellSignature(kind, evidence) {
+    if (!isValidStatus(evidence.status) || typeof evidence.subject !== 'string')
+        return false;
+    const subject = evidence.subject.trim();
+    if (kind === 'cmd' || kind === 'powershell') {
+        return MICROSOFT_PUBLISHER_RE.test(subject) && MICROSOFT_ORG_RE.test(subject);
+    }
+    return (MICROSOFT_PUBLISHER_RE.test(subject) && MICROSOFT_ORG_RE.test(subject))
+        || BASH_PUBLISHER_RES.some(pattern => pattern.test(subject));
+}
+function windowsSystemRoot() {
+    return process.env.SystemRoot || process.env.WINDIR || 'C:\\Windows';
+}
+function systemPowerShellPath() {
+    return path.win32.join(windowsSystemRoot(), 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+}
+function systemPowerShellModulePath() {
+    return path.win32.join(windowsSystemRoot(), 'System32', 'WindowsPowerShell', 'v1.0', 'Modules');
+}
+/**
+ * Windows PowerShell 5.1 must load its own Security module. A caller's
+ * PSModulePath can put PowerShell 7's module ahead of it; that module is not
+ * compatible with 5.1 and makes Get-AuthenticodeSignature fail to load.
+ */
+function systemPowerShellEnvironment() {
+    const env = { ...process.env };
+    for (const key of Object.keys(env)) {
+        if (key.toLowerCase() === 'psmodulepath')
+            delete env[key];
+    }
+    env.PSModulePath = systemPowerShellModulePath();
+    return env;
+}
+function systemWherePath() {
+    return path.win32.join(windowsSystemRoot(), 'System32', 'where.exe');
+}
+function isAbsoluteWindowsPath(value) {
+    return path.win32.isAbsolute(value) || /^\\\\[^\\/]+[\\/][^\\/]+/.test(value);
+}
+function resolveBareShellExecutable(executable, kind) {
+    const name = executable.toLowerCase().replace(/\.exe$/i, '');
+    if (kind === 'cmd' && name === 'cmd') {
+        return path.win32.join(windowsSystemRoot(), 'System32', 'cmd.exe');
+    }
+    if (kind === 'powershell' && name === 'powershell') {
+        return systemPowerShellPath();
+    }
+    const result = spawnSync(systemWherePath(), [`${name}.exe`], {
+        encoding: 'utf8',
+        timeout: 3000,
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (result.status !== 0)
+        return undefined;
+    const first = String(result.stdout || '')
+        .split(/\r?\n/)
+        .map(line => line.trim())
+        .find(Boolean);
+    return first || undefined;
+}
+function resolveShellPath(executable, kind) {
+    if (!executable)
+        return undefined;
+    // Codex can keep its POSIX carrier spelling on Windows (for example
+    // `/bin/bash`). It is a logical shell name, not a Windows root-relative
+    // filesystem path, so resolve it through the trusted Windows PATH lookup.
+    if (executable.startsWith('/') && !executable.startsWith('//')) {
+        const basename = path.posix.basename(executable);
+        return resolveBareShellExecutable(basename, kind);
+    }
+    if (isAbsoluteWindowsPath(executable))
+        return executable;
+    return resolveBareShellExecutable(executable, kind);
+}
+function isAppExecutionAliasPath(value) {
+    return /[\\/]AppData[\\/]Local[\\/]Microsoft[\\/]WindowsApps[\\/]/i.test(value);
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+function probeAuthenticode(filePath) {
+    const script = [
+        '$ErrorActionPreference = "Stop"',
+        `$p = ${shellQuote(filePath)}`,
+        '$item = Get-Item -LiteralPath $p -Force',
+        'if ($item.PSIsContainer) { exit 17 }',
+        '$sig = Get-AuthenticodeSignature -LiteralPath $item.FullName',
+        '[pscustomobject]@{',
+        '  status = [string]$sig.Status',
+        '  subject = if ($sig.SignerCertificate) { [string]$sig.SignerCertificate.Subject } else { "" }',
+        '  issuer = if ($sig.SignerCertificate) { [string]$sig.SignerCertificate.Issuer } else { "" }',
+        '} | ConvertTo-Json -Compress',
+    ].join('\n');
+    const result = spawnSync(systemPowerShellPath(), [
+        '-NoLogo', '-NoProfile', '-NonInteractive', '-Command', script,
+    ], {
+        encoding: 'utf8',
+        env: systemPowerShellEnvironment(),
+        timeout: 5000,
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (result.status !== 0 || result.error || !String(result.stdout || '').trim())
+        return undefined;
+    try {
+        const parsed = JSON.parse(String(result.stdout));
+        return {
+            status: typeof parsed.status === 'string' ? parsed.status : undefined,
+            subject: typeof parsed.subject === 'string' ? parsed.subject : undefined,
+            issuer: typeof parsed.issuer === 'string' ? parsed.issuer : undefined,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function cacheKey(filePath) {
+    try {
+        return fs.realpathSync.native(filePath).toLowerCase();
+    }
+    catch {
+        return filePath.replaceAll('\\', '/').toLowerCase();
+    }
+}
+/**
+ * Verify the concrete executable selected by Codex. Non-Windows callers keep
+ * the existing parser behavior; only Windows enters the Authenticode path.
+ */
+export function isTrustedWindowsShellExecutable(executable, kind) {
+    if (process.platform !== 'win32')
+        return true;
+    const resolved = resolveShellPath(executable, kind);
+    if (!resolved)
+        return false;
+    let finalPath = resolved;
+    try {
+        finalPath = fs.realpathSync.native(resolved);
+    }
+    catch {
+        // Keep the original path for the signature probe; the stat/probe below
+        // will fail closed if the executable is not accessible.
+    }
+    // If realpath could not escape an App Execution Alias, do not authenticate
+    // the alias stub itself. A resolved WindowsApps package binary is allowed
+    // and is checked below like any other signed executable.
+    if (isAppExecutionAliasPath(finalPath))
+        return false;
+    let stat;
+    try {
+        stat = fs.statSync(finalPath);
+        if (!stat.isFile())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    const key = cacheKey(finalPath);
+    const previous = signatureCache.get(key);
+    if (previous && previous.size === stat.size && previous.mtimeMs === stat.mtimeMs) {
+        return previous.trusted;
+    }
+    const trusted = isTrustedShellSignature(kind, probeAuthenticode(finalPath) ?? {});
+    signatureCache.set(key, { size: stat.size, mtimeMs: stat.mtimeMs, trusted });
+    while (signatureCache.size > MAX_CACHE_ENTRIES) {
+        const oldest = signatureCache.keys().next().value;
+        if (!oldest)
+            break;
+        signatureCache.delete(oldest);
+    }
+    return trusted;
+}
+/** Test hook: clear cached signature decisions after a fixture is replaced. */
+export function clearWindowsShellTrustCache() {
+    signatureCache.clear();
+}

package/kits/docs/evolcore/INDEX.md

@@ -29,12 +29,12 @@
 | 命令集 | 用途 | 触发词 | 适用场景 | 文档 |
 |--------|------|--------|----------|------|
 | `ec msg` | 私聊收发消息 | 回复/发消息/拉取/撤回/查在线 | 有对端（peerId） | `msg.md` |
-| `ec group` | 群聊收发与群管理 | 群发/建群/邀请/踢人/退群/群成员/角色/封禁/规则 | 群聊（groupId） | `group.md` |
+| `ec group` | 群聊收发与群管理 | 群发/建群/邀请/踢人/退群/群成员/角色/封禁/规则/协作 | 群聊（groupId） | `group.md`；完整协作流程见 `group-collaboration.md` |
 | `ec group rules` | 群规则文件发布与上下文注入 | 群规则/工作流程/职责分工/rules.md/发布规则 | AUN 群聊（groupId） | `group-rules.md` |
 | `ec aid` | AID 身份管理 | 身份/证书/名片/探测对端 | 任意有渠道场景 | `aid.md` |
 | `ec fs` | AUN 文件系统统一入口 | 上传/下载/看文件/列目录/删文件/配额/群空间 | 任意有渠道场景 | `fs.md` |
 | `ec storage` | 文件存储底层调试入口 | storage 调试/旧命令/底层上传下载 | 任意有渠道场景 | `storage.md` |
-| `ec agent` | EvolAgent 生命周期 | 创建/启停/热重载/改配置 | 管理员（owner/admin） | `agent.md` |
+| `ec agent` | EvolAgent 生命周期 | 创建/启停/热重载/改配置 | 管理员（owner/admin） | `agent.md`；完整创建与 Bootstrap 见 `agent-create.md` |
 | `ec contact` | Contact Book 与访问控制 | 申请添加、拉黑/解除拉黑、查拉黑 | Agent 当前私聊可申请添加；管理写操作按角色限制 | `contact.md` |
 | `ec rpc` | 底层 AUN RPC（逃生通道） | 直接调协议方法 | 高级/兜底 | `rpc.md` |
 

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

@@ -0,0 +1,146 @@
+# 创建 EvolAgent：从创建到 Bootstrap 完成
+
+本手册用于创建一个能正常工作的 EvolAgent。创建者负责创建和观察状态；新 Agent 在自己的 Bootstrap 会话中完成首次设定。不要把创建流水线完成误认为 Agent 已激活。
+
+## 生命周期与完成标准
+
+```text
+ec agent new
+    ↓
+created
+    ↓ channel 可以联系 Owner，或 Owner 首次入站
+bootstrapping
+    ↓ 新 Agent 发布 agent.md，并执行 ec agent ready
+active
+```
+
+只有 `lifecycle=active` 才表示 Agent 已完成创建流程并可正常处理普通任务。
+
+## 1. 创建者创建 Agent
+
+在独立终端可以使用交互模式：
+
+```bash
+ec agent new helper.agentid.pub
+```
+
+在 EvolCore 托管 Agent 会话等自动化环境中，必须使用非交互模式：
+
+```bash
+ec agent new helper.agentid.pub --non-interactive \
+  --project /home/user/helper-project \
+  --baseagent codex \
+  --owner owner.agentid.pub \
+  --name "Helper" \
+  --description "协助处理项目开发任务"
+```
+
+建议先用 dry-run 检查最终参数：
+
+```bash
+ec agent new helper.agentid.pub --non-interactive \
+  --project /home/user/helper-project \
+  --baseagent codex \
+  --owner owner.agentid.pub \
+  --name "Helper" \
+  --description "协助处理项目开发任务" \
+  --dry-run --format json
+```
+
+创建时会注册 AID、写入 Agent 配置、生成并尝试发布初始 `agent.md`，然后尝试热加载。配置写盘时 `lifecycle` 初始为 `created`；channel 很快触发 Bootstrap 时，查询结果也可能已经是 `bootstrapping`：
+
+```bash
+ec agent get helper.agentid.pub lifecycle
+ec agent show helper.agentid.pub
+```
+
+如果是 menu 创建，`accepted=true` 只表示请求已受理。继续轮询 `createProgress.status` 直到 `ready` 或 `failed`。这里的 `createProgress.status=ready` **只表示后台创建流水线结束，不等于 `lifecycle=active`**。
+
+## 2. 触发 Bootstrap
+
+当任一已启用 channel 可以联系 Owner 时，系统会向 Owner 发送固定的 Bootstrap 首条消息，并把生命周期从 `created` 切换为 `bootstrapping`。
+
+部分 channel 不能在连接时主动定位 Owner。这种情况下 Agent 会保持 `created`；Owner 需要先在该 channel 向新 Agent 发送一条消息，系统获得回复上下文后再启动 Bootstrap。
+
+`created` 状态下 Base Agent 不处理普通消息。`bootstrapping` 状态下只加载 Bootstrap 专属提示词，不加载正常的 ECK 规则、人格、记忆或命令能力卡。
+
+## 3. Owner 与新 Agent 确认名片信息
+
+以下步骤发生在**新 Agent 自己的 Bootstrap 会话**中，不由创建者代替执行。
+
+新 Agent 先读取系统注入路径指向的本地 `agent.md`，把其中格式有效的字段作为现有候选值：
+
+- `name`：简短清晰的显示名
+- `description`：一句到两句话描述职责或定位
+- `tags`：3 到 6 个非空标签
+
+交互规则：
+
+1. 已有有效值时，新 Agent 简短回显并询问保持还是修改，不要求 Owner 重新输入。
+2. 空值、占位值或格式错误的字段按缺失处理；`tags` 不足 3 个或超过 6 个也不合格。
+3. 只有 Owner 明确提供、修改、选择或确认的内容才可作为最终值。不得从普通任务、示例文字或顺带提及的内容中推断。
+4. 信息缺失、冲突或含义不清时，只追问对应部分，保留此前已明确的内容。
+5. 三项齐全后，新 Agent 必须回显整组最终值，并再次请求 Owner 明确确认。
+
+例如，Owner 可以回复：
+
+```text
+名称用 Helper；简介是“协助维护和开发项目”；标签用 coding、maintenance、typescript。请按这些值设置。
+```
+
+新 Agent 应回显这三个最终值并等待确认。Owner 再明确回复“确认”后，才能修改和发布名片。
+
+Bootstrap 完成前，新 Agent 不处理普通任务，也不执行与本流程无关的工具或命令。如果 Owner 要求跳过、先工作或同时交办普通任务，新 Agent 应说明必须先完成首次设定，并继续确认缺失字段。
+
+## 4. 新 Agent 修改并发布自己的 agent.md
+
+Owner 明确确认最终值后，新 Agent 才能编辑系统提示词中 `agentMdPath` 指向的本地文件，并且：
+
+- 只修改 YAML frontmatter 中的 `name`、`description`、`tags`。
+- 保留其他 frontmatter 字段、Markdown 正文和文件结构。
+- 修改后检查 YAML 合法，且三个字段满足上述格式要求。
+
+然后由新 Agent 使用自己的 AID 签名并发布：
+
+```bash
+ec aid agentmd put helper.agentid.pub
+```
+
+只有命令明确成功后才能继续。若发布失败，不得执行 `ready`；应向 Owner 说明具体错误，修正后再继续，不要盲目重复。
+
+## 5. 新 Agent 完成 Bootstrap
+
+发布成功后，新 Agent 执行整个 Bootstrap 的最后一个操作：
+
+```bash
+ec agent ready helper.agentid.pub
+```
+
+托管任务只能对自身 AID 执行 `ready`，不能替其他 Agent 完成 Bootstrap。只有处于 `bootstrapping` 时，`ready` 才会完成状态切换；仍为 `created` 时会失败，已经是 `active` 时重复调用则保持 `active`。
+
+`ready` 成功后，系统会：
+
+1. 将 `lifecycle` 切换为 `active`。
+2. 结束当前 Bootstrap 上下文。
+3. 创建全新的主会话。
+4. 发送正式欢迎消息。
+
+新 Agent 在 `ready` 成功后不要从旧 Bootstrap 上下文再输出一段完成说明，也不要继续处理先前夹带的普通任务；后续工作从新主会话开始。
+
+## 6. 创建者验收
+
+```bash
+ec agent get helper.agentid.pub lifecycle
+# 应输出 active
+
+ec agent show helper.agentid.pub
+```
+
+验收标准：
+
+- `lifecycle` 为 `active`。
+- `agent.md` 已成功签名发布。
+- 系统已创建新的主会话并发送正式欢迎消息。
+- 新 Agent 能在新主会话中处理普通任务。
+
+如果仍为 `created`，检查 channel 是否已能联系 Owner，必要时由 Owner 主动发送首条消息。如果仍为 `bootstrapping`，回到新 Agent 的 Bootstrap 会话完成字段确认、名片发布和 `ready`，不要由创建者直接绕过引导。

package/kits/docs/evolcore/agent.md

@@ -53,6 +53,12 @@ ec agent delete <aid> [--purge]
 - `--dry-run` 只输出最终创建计划，不注册 AID、不写配置、不上传 `agent.md`。
 - `--force` 覆盖已有 `config.json`；AID 密钥保留。
 
+## 创建 Agent
+
+`ec agent new` 成功不代表新 Agent 已能处理普通任务。新 Agent 还必须完成 Bootstrap，并由自身执行 `ec agent ready <aid>` 进入 `active`。
+
+完整的创建、Bootstrap、名片发布和验收示例见：`$KITS_DOCS/evolcore/agent-create.md`。
+
 ## 头像更新
 
 头像上传通过 menu 协议暴露，不是 `ec agent` CLI 子命令：