evolcore 0.0.26 → 0.0.28

package/dist/utils/welcome.js

@@ -8,10 +8,154 @@
  * - 所有 IM 渠道（Feishu/WeChat/DingTalk/QQBot/WeCom）：首次交互时发送给交互用户（被动响应）
  */
 import fs from 'fs';
-import { channelStatePath } from '../paths.js';
+import path from 'path';
+import { createHash } from 'crypto';
+import { parseDocument } from 'yaml';
+import { agentWelcomePath, channelStatePath, resolveRoot } from '../paths.js';
+import { isValidAid } from '../aun/aid/validation.js';
 import { loadAgent, saveAgent } from '../config-store.js';
 import { resolveAgentLifecycle, withLifecycleForWrite } from '../config/lifecycle.js';
+import { renderTemplate } from '../eck/manifest-engine.js';
+import { atomicWriteText } from './atomic-write.js';
 import { logger } from './logger.js';
+export const MAX_WELCOME_TEMPLATE_BYTES = 4 * 1024;
+export const MAX_RENDERED_WELCOME_BYTES = 8 * 1024;
+const WELCOME_TEMPLATE_VARS = new Set([
+    'agentName', 'agentDescription', 'agentAid', 'agentTags', 'agentTagsText',
+    'ownerName', 'ownerAid', 'channel',
+]);
+/** Validate the small, data-only template language used by Bootstrap welcome text. */
+export function validateWelcomeTemplate(template) {
+    const errors = [];
+    if (typeof template !== 'string' || !template.trim()) {
+        return { valid: false, errors: ['welcome template must be non-empty'] };
+    }
+    if (template.includes('\0') || Buffer.from(template, 'utf8').toString('utf8') !== template) {
+        errors.push('welcome template must contain valid UTF-8 text only');
+    }
+    if (Buffer.byteLength(template, 'utf8') > MAX_WELCOME_TEMPLATE_BYTES) {
+        return { valid: false, errors: [`welcome template must be at most ${MAX_WELCOME_TEMPLATE_BYTES} bytes`] };
+    }
+    const stack = [];
+    const tokenPattern = /\{\{|\}\}/g;
+    let match;
+    while ((match = tokenPattern.exec(template)) !== null) {
+        const end = template.indexOf('}}', tokenPattern.lastIndex);
+        if (match[0] !== '{{' || end < 0) {
+            errors.push('unmatched template delimiter');
+            break;
+        }
+        const token = template.slice(tokenPattern.lastIndex, end);
+        tokenPattern.lastIndex = end + 2;
+        if (token === '#each agentTags') {
+            if (stack.includes('each'))
+                errors.push('nested tag loops are not supported');
+            stack.push('each');
+        }
+        else if (token === '/each' || token === '/') {
+            const expected = token === '/each' ? 'each' : 'condition';
+            if (stack.pop() !== expected)
+                errors.push(`unexpected {{${token}}}`);
+        }
+        else if (/^\?\w+$/.test(token) && WELCOME_TEMPLATE_VARS.has(token.slice(1))) {
+            stack.push('condition');
+        }
+        else if ((token === '.' || token === '@index') && stack.includes('each')) {
+            // Loop-local variables are valid only inside the tag loop.
+        }
+        else if (!WELCOME_TEMPLATE_VARS.has(token)) {
+            errors.push(`unsupported template variable or block: ${token}`);
+        }
+        if (stack.length > 8) {
+            errors.push('template blocks are nested too deeply');
+            break;
+        }
+    }
+    if (stack.includes('each'))
+        errors.push('unclosed {{#each}} block');
+    if (stack.includes('condition'))
+        errors.push('unclosed condition block');
+    return { valid: errors.length === 0, errors };
+}
+function checkedWelcomePath(aid) {
+    if (!isValidAid(aid))
+        throw new Error('invalid Agent AID');
+    const target = agentWelcomePath(aid);
+    const root = path.resolve(resolveRoot());
+    for (let cursor = path.resolve(target); cursor !== root; cursor = path.dirname(cursor)) {
+        try {
+            if (fs.lstatSync(cursor).isSymbolicLink())
+                throw new Error('welcome path must not contain symbolic links');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    return target;
+}
+export function saveAgentWelcomeTemplate(aid, template) {
+    const validation = validateWelcomeTemplate(template);
+    if (!validation.valid)
+        throw new Error(`invalid welcome template: ${validation.errors.join('; ')}`);
+    const target = checkedWelcomePath(aid);
+    const staging = target + '.tmp.' + process.pid;
+    try {
+        if (fs.lstatSync(staging).isSymbolicLink())
+            throw new Error('invalid welcome staging path');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    try {
+        atomicWriteText(target, template);
+    }
+    finally {
+        fs.rmSync(staging, { force: true });
+    }
+    return { path: target, bytes: Buffer.byteLength(template, 'utf8'), sha256: createHash('sha256').update(template).digest('hex') };
+}
+export function readAgentWelcomeTemplate(aid) {
+    const target = checkedWelcomePath(aid);
+    let stat;
+    try {
+        stat = fs.lstatSync(target);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    if (!stat.isFile() || stat.size > MAX_WELCOME_TEMPLATE_BYTES)
+        throw new Error('invalid welcome template file');
+    const template = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(target));
+    const validation = validateWelcomeTemplate(template);
+    if (!validation.valid)
+        throw new Error(`invalid welcome template at ${target}: ${validation.errors.join('; ')}`);
+    return template;
+}
+export function parseAgentWelcomeMetadata(content) {
+    const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
+    if (!frontmatter)
+        return { tags: [] };
+    try {
+        const document = parseDocument(frontmatter);
+        if (document.errors.length)
+            return { tags: [] };
+        const value = document.toJS();
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return { tags: [] };
+        return {
+            name: typeof value.name === 'string' ? value.name.trim() : undefined,
+            description: typeof value.description === 'string' ? value.description.trim() : undefined,
+            tags: Array.isArray(value.tags) ? value.tags.filter((tag) => typeof tag === 'string').map(tag => tag.trim()) : [],
+        };
+    }
+    catch {
+        return { tags: [] };
+    }
+}
 // ============================================================================
 // 欢迎消息生成
 // ============================================================================
@@ -50,6 +194,35 @@ ${agentIntro}${channelInfo}
 
 现在就可以开始工作了！`;
 }
+export function renderPostBootstrapWelcomeMessage(options) {
+    const validation = validateWelcomeTemplate(options.template);
+    if (!validation.valid)
+        throw new Error(`invalid welcome template: ${validation.errors.join('; ')}`);
+    // ECK renders loop bodies recursively. Mask data so names/descriptions containing
+    // template syntax remain literal even when inserted inside a loop or condition.
+    const values = [];
+    const literal = (value) => {
+        if (!value)
+            return '';
+        values.push(value);
+        return `\0WELCOME${values.length - 1}\0`;
+    };
+    const rendered = renderTemplate(options.template, {
+        agentName: literal(options.agentName),
+        agentDescription: literal(options.agentDescription),
+        agentAid: literal(options.agentAid),
+        agentTags: (options.agentTags ?? []).map(literal),
+        agentTagsText: literal((options.agentTags ?? []).join(', ')),
+        ownerName: literal(options.ownerName),
+        ownerAid: literal(options.ownerAid),
+        channel: literal('aun'),
+    }, false).replace(/\0WELCOME(\d+)\0/g, (_match, index) => values[Number(index)]);
+    if (!rendered.trim())
+        throw new Error('welcome template rendered to an empty message');
+    if (Buffer.byteLength(rendered, 'utf8') > MAX_RENDERED_WELCOME_BYTES)
+        throw new Error('rendered welcome exceeds 8192 bytes');
+    return rendered;
+}
 /**
  * 生成简化版欢迎消息（用于快速场景）
  */

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

@@ -36,6 +36,10 @@ export function isTrustedShellSignature(kind, evidence) {
 function windowsSystemRoot() {
     return process.env.SystemRoot || process.env.WINDIR || 'C:\\Windows';
 }
+/** Return the only cmd.exe that EvolCore is willing to use as a shell carrier. */
+export function windowsSystemCmdPath() {
+    return path.win32.join(windowsSystemRoot(), 'System32', 'cmd.exe');
+}
 function systemPowerShellPath() {
     return path.win32.join(windowsSystemRoot(), 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
 }
@@ -195,6 +199,39 @@ export function isTrustedWindowsShellExecutable(executable, kind) {
     }
     return trusted;
 }
+/**
+ * Resolve an inherited ComSpec to the system cmd.exe and authenticate it.
+ * npm shims are not signed Microsoft binaries, so this helper intentionally
+ * validates only the interpreter and never the `.cmd`/`.bat` target.
+ */
+export function resolveTrustedWindowsCmdPath(comSpec) {
+    if (process.platform !== 'win32')
+        return comSpec || 'cmd.exe';
+    const systemCmd = windowsSystemCmdPath();
+    const candidate = (comSpec || process.env.ComSpec || process.env.COMSPEC || systemCmd).trim();
+    if (!candidate)
+        return undefined;
+    let candidatePath = candidate;
+    if (!isAbsoluteWindowsPath(candidatePath)) {
+        if (/^cmd(?:\.exe)?$/i.test(candidatePath))
+            candidatePath = systemCmd;
+        else
+            return undefined;
+    }
+    let candidateReal;
+    let systemReal;
+    try {
+        candidateReal = fs.realpathSync.native(candidatePath);
+        systemReal = fs.realpathSync.native(systemCmd);
+    }
+    catch {
+        return undefined;
+    }
+    if (path.win32.normalize(candidateReal).toLowerCase() !== path.win32.normalize(systemReal).toLowerCase()) {
+        return undefined;
+    }
+    return isTrustedWindowsShellExecutable(systemReal, 'cmd') ? systemReal : undefined;
+}
 /** Test hook: clear cached signature decisions after a fixture is replaced. */
 export function clearWindowsShellTrustCache() {
     signatureCache.clear();

package/ecagent/dist/harness/agent-harness.js

@@ -412,6 +412,9 @@ export class AgentHarness {
     }
     async handleAgentEvent(event, signal) {
         if (event.type === "message_end") {
+            // Persist the same multimodal message that was sent to the provider.
+            // Provider rollouts (Claude/Codex) retain image bytes in their own
+            // session files, so ecagent must do the same for resumable context.
             await this.session.appendMessage(event.message);
             await this.emitAny(event, signal);
             return;

package/ecagent/dist/harness/session/jsonl-storage.js

@@ -1,6 +1,25 @@
 import { SessionError, toError } from "../types.js";
 import { getFileSystemResultOrThrow } from "./repo-utils.js";
 import { uuidv7 } from "./uuid.js";
+// Multiple harness instances can briefly reference the same session during a
+// replacement turn. Node's appendFile does not guarantee that large writes
+// from separate calls stay contiguous, so serialize appends per physical file.
+const appendQueues = new Map();
+async function appendSerialized(fs, filePath, content) {
+    const previous = appendQueues.get(filePath) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve) => { release = resolve; });
+    appendQueues.set(filePath, current);
+    try {
+        await previous.catch(() => undefined);
+        getFileSystemResultOrThrow(await fs.appendFile(filePath, content), `Failed to append session entry ${filePath}`);
+    }
+    finally {
+        release();
+        if (appendQueues.get(filePath) === current)
+            appendQueues.delete(filePath);
+    }
+}
 function updateLabelCache(labelsById, entry) {
     if (entry.type !== "label")
         return;
@@ -185,7 +204,7 @@ export class JsonlSessionStorage {
             timestamp: new Date().toISOString(),
             targetId: leafId,
         };
-        getFileSystemResultOrThrow(await this.fs.appendFile(this.filePath, `${JSON.stringify(entry)}\n`), `Failed to append session leaf ${entry.id}`);
+        await appendSerialized(this.fs, this.filePath, `${JSON.stringify(entry)}\n`);
         this.entries.push(entry);
         this.byId.set(entry.id, entry);
         this.currentLeafId = leafId;
@@ -194,7 +213,7 @@ export class JsonlSessionStorage {
         return generateEntryId(this.byId);
     }
     async appendEntry(entry) {
-        getFileSystemResultOrThrow(await this.fs.appendFile(this.filePath, `${JSON.stringify(entry)}\n`), `Failed to append session entry ${entry.id}`);
+        await appendSerialized(this.fs, this.filePath, `${JSON.stringify(entry)}\n`);
         this.entries.push(entry);
         this.byId.set(entry.id, entry);
         updateLabelCache(this.labelsById, entry);

package/kits/docs/INDEX.md

@@ -58,9 +58,3 @@
 | 路径注册表模板 | `eck_templates/path-registry.template.md` | 路径实例模板 |
 | 索引模板 | `eck_templates/INDEX.template.md` | agent 级索引模板 |
 | 指南模板 | `eck_templates/GUIDE.template.md` | agent 级查阅指南模板 |
-
-## Base Agent
-
-| 文档 | 路径 | 说明 |
-|------|------|------|
-| Claude Code 日志 | `baseagent/cc-logs.md` | CC 会话日志查阅（找完整对话/工具调用/注入） |

package/kits/docs/channels/aun.md

@@ -1,7 +1,7 @@
 # AUN 渠道
 
 > 知识性文档：AUN 渠道的配置、参数与特有机制。**不依赖当前会话渠道**——任意会话都可按需 Read。
-> 运行时"怎么发消息"由注入的 `[channel]` 段决定（aun 渠道用 `ec msg send` / `ec group send`），不在本文。
+> 运行时回复方式由共用 `[reply]` 段按实际 chatMode 决定；active 的 `[channel]` 补充文件、链接、@ 等能力。AUN 主动发送使用托管的 `ec msg send` / `ec group send`。
 > 群聊使用 `evolcore/group.md`；群文件使用 `evolcore/fs.md`。
 
 ## 概述
@@ -51,6 +51,27 @@ AUN keystore seed 由 EvolCore 使用固定应用值管理，不再提供配置
   - 关系层另存一份**派生**的精简身份 `relations/<peerKey>/peer-identity.json`（type/isAgent/name），由 evolcore 从 agent.md 提取，不是 agent.md 本体。
 - **E2EE 加密**：可选端到端加密，回复默认跟随对端消息加密状态（密文回密文，明文回明文）；keystore seed 由 EvolCore 固定管理。
 - **断线重连**：SDK 内置退避策略自动重连。实时连接状态用 `ec watch aid` 查看（`ec aid` 是身份/证书管理，不显示连接状态）。
-- **群 ID 格式**：当前协议规范使用 `g-{slug}.issuer-domain` canonical 形式，输入也可接受本域简写 `g-{slug}` 或兼容形式 `g-{slug}@issuer-domain`。历史会话里可能仍出现 `group.{issuer}/{group_no}` 一类旧格式，运行时需兼容读取。
+- **群 ID 格式**：使用 `{base}.{issuer}`，如 `ontology.agentid.cn` 或 `g-12345.agentid.cn`。EvolCore 默认创建 `g-` 加五位数字（10000–99999）的名称，issuer 以群服务返回为准。群命令支持 base 简写；不再支持或转换 `group.{issuer}/{base}`，也不支持 `base@issuer`。`g-` 是名称的一部分，不应剥离，也不能仅凭群 AID 的格式判断主体类型。
 - **群 @ 处理策略**：`mention_mode=disabled|mention-only` 是群级配置，只决定哪些群消息进入 Agent LLM 上下文，不影响 AUN 协议层投递；被过滤消息仍应本地存档。
 - **身份体系**：对端以 AID 标识，关系层 peerKey 形如 `aun#alice.aid.pub`。
+
+### 私聊最终回复标题
+
+AUN 私聊中，`result.text` 的 `isFinal=true` 会在 `payload.text` 正文前添加 `✅ 最终回复:`。AUN 文本客户端按正文展示，标题随 outbox 上下文持久化，断线恢复发送时仍保留。群聊、中间文本、命令回执及错误消息不自动添加该标题。
+
+Interactive 私聊的最终正文保留到本轮结束后统一发送，避免定时 flush 提前当作中间文本发出。Codex 明确标记的 commentary 可按原定时窗口发送；没有阶段标记的正文等到下一文本块、工具调用或本轮结束后确定发送方式。标题和正文之间留一个空行，正文已经以同一标题开头时不重复添加，也不额外发送 `payload.title`。
+
+标题仅表示最终回复的展示信息，任务完成或失败仍由 `task.status` 表达。
+
+### 出站关注状态
+
+AUN runner 状态和 action card 可携带顶层 `attention`，值只能是以下四种之一：
+
+| 值 | 语义 |
+|---|---|
+| `completed` | 正常终态，任务已完成并交付结果 |
+| `failed` | 异常终态，任务无法继续完成 |
+| `required` | 需要人处理，例如授权确认或补充输入 |
+| `interrupted` | runner 被用户、新消息或基础设施中断 |
+
+普通持久化业务消息（含最终文本、错误正文、Activity、命令回执）不携带 `terminal` 或 `attention`。`task.status` 的 completed/error/timeout/interrupted 成对携带终态字段，requires_action 携带 `false/required`，其他过程状态两字段都省略。所有 action card 固定携带 `terminal:false` 和 `attention:"required"`；卡片投递本身不会创建 runner 等待状态。可恢复 system.error 投影为 `notice + severity:warn`。线上值按类型和状态统一生成，显式旧值不覆盖该规则。

package/kits/docs/channels/feishu.md

@@ -1,7 +1,7 @@
 # 飞书渠道
 
 > 知识性文档：飞书渠道的配置、参数与特有机制。**不依赖当前会话渠道**——任意会话都可按需 Read（在 aun 会话里也可查飞书）。
-> 运行时"怎么发消息"由注入的 `[channel]` 段决定（飞书是 evolcore 自动回复，agent 不调 CLI），不在本文。
+> 运行时回复方式由共用 `[reply]` 段按实际 chatMode 决定：interactive 由 evolcore 自动投递普通输出，proactive 用 `ec ctl send` 正式回复；active 的 `[channel]` 补充文件等能力。
 
 ## 概述
 

package/kits/docs/context-assembly.md

@@ -263,6 +263,7 @@ vars 由 evolcore 在 `message-processor.ts` 按当前会话构造。分两类
 | `chatType` | `private` / `group` / `null`(coding) |
 | `channel` | 渠道类型（aun/feishu/...）|
 | `mentionMode` | 群 @ 处理模式（mention-only/disabled） |
+| `groupHistoryAvailable` | 当前 AUN 群是否允许读取本地群历史 |
 | `clientType` | 客户端类型（desktop/web/mobile） |
 | `permissionMode` / `readonly` | 权限模式 / 是否只读 |
 | `capabilities` | 当前渠道能力（图片输入/输出、文件发送） |
@@ -285,25 +286,36 @@ coding 场景（无 channel/无身份）下，`chatType`、`channel`、`selfAid`
 
 ## 默认 manifest 的段（按 order）
 
+常规段均要求 `lifecycle=active`，下表的其它条件在此基础上叠加；Bootstrap 引导与共用回复段单独列出完整条件。
+
 | order | id | 类型 | 加载条件（when） | inject |
 |-------|----|----|------------------|--------|
-| 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 | ✗ |
-| 40 | venue-fragment | fragment | chatType≠null | ✓ |
-| 41 | venue-chattype | `$KITS_DOCS/venues/{{chatType}}.md` | chatType≠null | ✗ |
-| 42 | venue-channel-chattype | `$KITS_DOCS/venues/{{channel}}-{{chatType}}.md` | chatType≠null | ✗ |
-| 44 | venue-client | `$KITS_DOCS/venues/client-{{clientType}}.md` | clientType≠null | ✗ |
-| 50 | channel-layer | fragment | channel≠null | ✓ |
-| 55 | commands | fragment | channel≠null | ✓ |
-| 60 | session | fragment | always | ✓ |
-| 70 | baseagent | fragment | baseAgent≠null | ✓ |
-
-> 注意：`session`(60) 是 `always`，`baseagent`(70) 只看 `baseAgent` 是否注入——这两段**与 chatType 无关**，coding 场景也会加载。所谓"coding 仅 rules"是近似说法：精确地说 coding 场景命中的是 rules + session + baseagent（其余因 chatType/channel 为空而落选）。
+| 10 | rules | 目录 `$KITS_RULES` | active | ✗ |
+| 15 | bootstrap-guide | `bootstrap.md` | lifecycle=bootstrapping | ✓ |
+| 20 | identity-layer | fragment | active 且 chatType≠null | ✓ |
+| 21 | persona | `$PERSONAL_DIR/persona.md` | active 且 chatType≠null | ✗ |
+| 21.5 | personal-profile | `$PERSONAL_DIR/personal.md` | active 且 chatType≠null | ✗ |
+| 22 | working-memory | `$PERSONAL_DIR/memory/working.md` | active 且 chatType≠null | ✗ |
+| 23 | preferences | `$PERSONAL_DIR/preferences/active-preferences.md` | active 且 chatType=private | ✗ |
+| 30 | relation-layer | fragment | active 且 chatType∈{private,group} | ✓ |
+| 35 | peer-profile | `$RELATIONS_DIR/{{peerKey}}/profile.md` | active 且 peerKey≠null | ✗ |
+| 40 | venue-fragment | fragment | active 且 chatType≠null | ✓ |
+| 41 | venue-chattype | `$KITS_DOCS/venues/{{chatType}}.md` | active 且 chatType≠null | ✗ |
+| 42 | venue-channel-chattype | `$KITS_DOCS/venues/{{channel}}-{{chatType}}.md` | active 且 chatType≠null | ✗ |
+| 43.2 | relation-group-rules | `$RELATIONS_DIR/{{peerKey}}/rules.md` | active 且 groupRulesPath≠null | ✗ |
+| 44 | venue-client | `$KITS_DOCS/venues/client-{{clientType}}.md` | active 且 clientType≠null | ✗ |
+| 49 | reply-contract | `reply.md` | channel≠null 且 lifecycle∈{active,bootstrapping} | ✓ |
+| 50 | channel-layer | fragment | active 且 channel≠null | ✓ |
+| 55 | commands | fragment | active 且 channel≠null | ✓ |
+| 60 | session | fragment | active | ✓ |
+| 70 | baseagent | fragment | active 且 baseAgent≠null | ✓ |
+
+Bootstrap 只加载引导与有渠道时的最小通信上下文 `[reply]`，不加载完整身份/关系/渠道能力、个人记忆或普通任务命令。
+`[reply]` 展示 selfAid、peerId、peerType、channel、chatType、chatMode；未知身份显示 unknown，回复方式只取运行时已解析的 chatMode，不从身份或私聊场景重新推断。命令经当前会话 delegated sender / daemon IPC 发送，遵守现有身份、目标、话题与加密约束。
+`needsInjection` 仅是是否进行模板渲染的布尔开关，不是变量白名单；上述变量原本已存在于运行时 vars。
+
+`session` 与 `baseagent` 不依赖 chatType，因此 active 的 coding 场景仍命中 rules + session + baseagent；无渠道时不加载共用回复段。
+生命周期缺失兼容 active；created 与显式非法生命周期不命中主 manifest 的引导、回复或常规段。
 
 ## 环境层文档目录结构
 

package/kits/docs/evolcore/INDEX.md

@@ -5,7 +5,7 @@
 注入一张精简能力卡，指向本目录下对应文档；需要完整用法时 Read 对应文档。
 
 > 对外通信命令以自己的 AID 为发送者；当前渠道是否需要 CLI 回复，以运行时注入的
-> `channel` 规则为准。参数不是全局通用的：`--format json` 仅用于对应帮助中明确支持的命令，
+> `[reply]` 规则为准，active 的 `[channel]` 补充扩展能力。参数不是全局通用的：`--format json` 仅用于对应帮助中明确支持的命令，
 > `--app <name>` 仅用于消息 pull/ack、消费类 RPC 和明确支持 app slot 的文件操作。
 
 ## 如何使用本索引
@@ -14,12 +14,14 @@
 2. **不确定有没有命令**时，直接 `ec <猜测的子命令> --help` 试一下（如 `ec stats --help`）
 3. **已知场景需求**（如"要给对端发消息"）→ 看下方分类表 → 定位到对应命令集
 
+托管 Agent 任务禁止调用 `ec start`、`ec stop`、`ec restart` 或 `ec restart-monitor`。这些进程生命周期命令只能由宿主终端执行；源码改动后 Agent 只应完成构建并报告需要宿主重启。
+
 ## 服务运维类（本地，无需 AUN）
 
 | 命令 | 用途 | 触发词 |
 |------|------|--------|
 | `ec --version` / `-v` / `-V` | 查看版本号 | 版本 |
-| `ec restart` | 重启服务（含自动升级检查） | 重启 |
+| `ec restart` | 宿主终端重启服务（托管 Agent 禁止调用） | 重启 |
 | `ec status` | 查看运行状态、进程、会话、渠道连接 | 状态/查看状态 |
 | `ec logs` | 查看日志（`--level` `--module` `--raw` `--no-color`） | 日志/查看日志 |
 | `ec diagnose` | 诊断启动环境 | 诊断/环境诊断 |
@@ -31,9 +33,11 @@ Windows 上 Codex 托管任务出现 `helper_sandbox_lock_failed`、`SetNamedSec
 | 命令集 | 用途 | 触发词 | 适用场景 | 文档 |
 |--------|------|--------|----------|------|
 | `ec msg` | 私聊收发消息 | 回复/发消息/拉取/撤回/查在线 | 有对端（peerId） | `msg.md` |
-| `ec group` | 群聊收发与群管理 | 群发/建群/邀请/踢人/退群/群成员/角色/封禁/规则/协作 | 群聊（groupId） | `group.md`；完整协作流程见 `group-collaboration.md` |
+| `ec group` | 群聊收发与群管理 | 群发/建群/本地群历史/邀请/踢人/退群/群成员/角色/封禁/屏蔽/成员状态/规则/协作 | 群聊（groupId） | `group.md`；完整协作流程见 `group-collaboration.md` |
+| `/invites` / `ec group invites` | 收到群邀请、Owner 卡片审核与恢复 | 入群邀请/接受邀请/拒绝邀请/审核卡片/待处理邀请 | 当前 Agent Owner 的 AUN 私聊 | `group.md` |
 | `ec group rules` | 群规则文件发布与上下文注入 | 群规则/工作流程/职责分工/rules.md/发布规则 | AUN 群聊（groupId） | `group-rules.md` |
 | `ec aid` | AID 身份管理 | 身份/证书/名片/探测对端 | 任意有渠道场景 | `aid.md` |
+| `ec aid` | AID 身份、名片与头像管理 | 身份/证书/名片/头像/换头像/探测对端 | 任意有渠道场景 | `aid.md` |
 | `ec fs` | AUN 文件系统统一入口 | 上传/下载/看文件/列目录/删文件/配额/群空间 | 任意有渠道场景 | `fs.md` |
 | `ec storage` | 文件存储底层调试入口 | storage 调试/旧命令/底层上传下载 | 任意有渠道场景 | `storage.md` |
 | `ec agent` | EvolAgent 生命周期 | 创建/启停/热重载/改配置 | 管理员（owner/admin） | `agent.md`；完整创建与 Bootstrap 见 `agent-create.md` |
@@ -57,6 +61,7 @@ Windows 上 Codex 托管任务出现 `helper_sandbox_lock_failed`、`SetNamedSec
 | `ec stats` | Token 用量与费用统计 | 用量/费用/统计/预算/token/cost | `stats.md` |
 | `ec trigger` | 定时与事件触发器管理（创建用 `create`，`set` 为兼容别名） | 触发器/定时任务/cron/提醒/定时检查/自动执行/巡检/禁用 trigger/删除 trigger | `trigger.md` |
 | `ec trigger event` | EventBus 事件目录 | 事件触发/事件目录/EventBus/source.type=event/filter.match | `event.md` |
+| `ec task` | 恢复暂停或异常中断的会话任务 | 任务恢复/异常中断/继续任务/resume | `task.md` |
 
 ## 开发者工具（非 agent 会话能力）
 

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

@@ -27,6 +27,25 @@ active
 
 ## 1. 创建者创建 Agent
 
+### 一次性初始化模式
+
+如果创建者已经明确确认最终名片字段和人格，可以使用 `--initialize` 一次完成创建与激活：
+
+```bash
+ec agent new helper.agentid.pub --initialize \
+  --project /home/user/helper-project --baseagent codex \
+  --owner owner.agentid.pub --name "Helper" \
+  --description "协助处理项目开发任务" \
+  --tags '["coding","maintenance","typescript"]' \
+  --persona-file /home/user/helper-project/persona.md
+```
+
+`--initialize` 自动包含 `--non-interactive`。它要求 `name`、`description`、`tags` 和 Owner 显式提供，由 daemon 写入 persona、签名发布最终 `agent.md`、热加载并完成欢迎消息及 lifecycle `active`。它不启动目标 Agent 的确认对话，也不要求创建者成为新 Agent 的 Owner。默认等待 60 秒，可用 `--wait 0..300` 调整；超时返回可查询的初始化操作，不代表失败。
+
+初始化期间不处理目标 Agent 的普通入站消息。初始化失败或 daemon 重启后，使用 `ec agent initialize <aid> --resume` 恢复原操作；不要重复 `new` 或使用 `--force` 覆盖。`ec agent show <aid>` 会显示初始化阶段、错误和下一步，但不会暴露 persona 正文。
+
+没有得到创建者明确最终字段时，继续使用下方的普通非交互式创建，让目标 Agent 自己完成 Bootstrap。
+
 多个 Agent 必须串行创建和观察。不要并行启动多个 `ec agent new`：证书、热加载和 Bootstrap 会竞争连接与资源，容易造成超时、锁等待或把失败误判为未创建。
 
 在人类直接创建时，可以使用交互模式：
@@ -85,7 +104,7 @@ ec agent show helper.agentid.pub
 
 部分 channel 不能在连接时主动定位 Owner。这种情况下 Agent 会保持 `created`；Owner 需要先在该 channel 向新 Agent 发送一条消息，系统获得回复上下文后再启动 Bootstrap。
 
-`created` 状态下 Base Agent 不处理普通消息。`bootstrapping` 状态下只加载 Bootstrap 专属提示词，不加载正常的 ECK 规则、人格、记忆或命令能力卡。
+`created` 状态下 Base Agent 不处理普通消息。`bootstrapping` 状态下加载 Bootstrap 专属提示词与有渠道时的 `[reply]` 最小通信上下文，不加载正常的 ECK 规则、人格、记忆、完整渠道能力或命令能力卡。回复方式遵循实际 chatMode，不根据 Owner 是人类还是 AI 推断。
 
 ## 3. Owner 与新 Agent 确认名片信息
 
@@ -115,7 +134,7 @@ ec agent show helper.agentid.pub
 
 Bootstrap 完成前，新 Agent 不处理普通任务，也不执行与本流程无关的工具或命令。如果 Owner 要求跳过、先工作或同时交办普通任务，新 Agent 应说明必须先完成首次设定，并继续确认缺失字段。
 
-## 4. 新 Agent 修改并发布自己的 agent.md
+## 4. 新 Agent 修改自己的 agent.md
 
 Owner 明确确认最终值后，新 Agent 才能编辑系统提示词中 `agentMdPath` 指向的本地文件，并且：
 
@@ -123,15 +142,27 @@ Owner 明确确认最终值后，新 Agent 才能编辑系统提示词中 `agent
 - 保留其他 frontmatter 字段、Markdown 正文和文件结构。
 - 修改后检查 YAML 合法，且三个字段满足上述格式要求。
 
-然后由新 Agent 使用自己的 AID 签名并发布：
+## 5. 生成并确认 Bootstrap Welcome
+
+名片字段确认后，新 Agent 在当前 Bootstrap 对话中直接输出完整的个性化 welcome 文案，并请求 Owner 明确确认。
+Owner 要求修改时，重新输出完整文案并再次确认；未确认的文本不写入文件，也不创建草稿。Owner 明确确认后执行：
+
+```bash
+ec agent welcome --text '<最后展示且确认的完整文案>'
+```
+
+该命令固定保存到 `$PERSONAL_DIR/welcome.md`。保存成功后才能继续发布名片和执行 `ready`。如果 Bootstrap 会话在确认前中断，下一次继续时重新生成并确认。
+
+随后由新 Agent 使用自己的 AID 签名并发布名片：
 
 ```bash
 ec aid agentmd put helper.agentid.pub
 ```
 
-只有命令明确成功后才能继续。若发布失败，不得执行 `ready`；应向 Owner 说明具体错误，修正后再继续，不要盲目重复。
+只有命令明确成功后才能继续。发布失败时保留已经确认的 welcome，修正发布问题后续做，不重复生成。
+多 Owner 共用该模板；需要称呼时保留 `{{ownerName}}` / `{{ownerAid}}` 供逐人渲染。投递文本不再追加未确认内容。
 
-## 5. 新 Agent 完成 Bootstrap
+## 6. 新 Agent 完成 Bootstrap
 
 发布成功后，新 Agent 执行整个 Bootstrap 的最后一个操作：
 
@@ -150,7 +181,7 @@ ec agent ready helper.agentid.pub
 
 新 Agent 在 `ready` 成功后不要从旧 Bootstrap 上下文再输出一段完成说明，也不要继续处理先前夹带的普通任务；后续工作从新主会话开始。
 
-## 6. 创建者验收
+## 7. 创建者验收
 
 ```bash
 ec agent get helper.agentid.pub lifecycle
@@ -170,9 +201,10 @@ Bootstrap 首条消息只发送给 `owners[0]`；`ready` 成功后，正式欢
 - `lifecycle` 为 `active`；`ec agent show` 的 `lifecycle` 字段也必须为 `active`。
 - `agent.md` 已成功签名发布。
 - 本地与远端 `agent.md` 的 `name`、`description`、`tags` 与 Owner 确认值一致；创建流程 skill 必须在发布后复读核验，不以初始上传响应代替。
+- `personal/welcome.md` 是当前 Bootstrap 对话最后展示并经 Owner 确认的全文，未确认文案没有另存草稿。
 - 系统已创建新的主会话并发送正式欢迎消息。
 - 新 Agent 能在新主会话中处理普通任务。
 
 如果仍为 `created`，检查 channel 是否已能联系 Owner，必要时由 Owner 主动发送首条消息。如果仍为 `bootstrapping`，回到新 Agent 的 Bootstrap 会话完成字段确认、名片发布和 `ready`，不要由创建者直接绕过引导。
 
-失败重试前必须先执行状态检查：若本地 `agent.md` 已存在且远端名片已发布，只向该 Agent 发送 `ready`/续做指令，让它在自己的 Bootstrap 会话中完成收尾；不要重复创建、重复改名片或重复发布。仅在确认创建记录不存在且名片未发布时，才重新发起创建。
+失败重试前必须先执行状态检查：若名片已发布且 welcome 已保存，只续做 `ready`；若 welcome 尚未确认保存，则由新 Agent 在自己的 Bootstrap 对话中补做全文生成和确认。不要重复创建、改名片或发布。仅在确认创建记录不存在且名片未发布时，才重新发起创建。

package/kits/docs/evolcore/agent.md

@@ -23,6 +23,16 @@ ec agent new <aid> --non-interactive \
   [--tags '<json-array>'] \
   [--dry-run] [--force]
 
+# 创建并一次性完成首次设定（隐含 --non-interactive）
+ec agent new <aid> --initialize \
+  --project <路径> --baseagent <claude|codex|gemini|ecagent> \
+  --owner <aid> --name "<显示名>" --description "<text>" \
+  --tags '<json-array>' [--persona-file <path> | --persona-text <text>] \
+  [--wait <seconds>] [--dry-run]
+
+# 恢复一次性初始化
+ec agent initialize <aid> --resume [--wait <seconds>]
+
 # 启用 / 停用
 ec agent enable <aid>
 ec agent disable <aid>
@@ -36,6 +46,10 @@ ec agent persona show
 ec agent persona --text <text>
 ec agent persona --file <path>
 
+# 读取或保存 Bootstrap 中经 Owner 确认的 welcome 文案
+ec agent welcome show
+ec agent welcome --text '<完整 Markdown 文案>'
+
 # 修改 agent.md 显示名称
 ec agent rename <aid> "<name>"
 
@@ -59,8 +73,13 @@ ec agent delete <aid> [--purge]
 - `--dry-run` 只输出最终创建计划，不注册 AID、不写配置、不上传 `agent.md`。
 - `--force` 覆盖已有 `config.json`；AID 密钥保留。
 - `--tags` 接受 3 到 6 个标签的 JSON 数组；每个标签只允许 Unicode 字母、数字和连字符（`-`），最长 50 字符。
+- `--initialize` 要求显式提供 `--name`、`--description`、`--tags` 和 Owner；它不从项目元数据推断名片，成功条件是目标 Agent 已进入 `active`。`--initialize` 自动包含 `--non-interactive`，不需要同时填写后者。
+- `--persona-file` / `--persona-text` 可选；两者互斥。初始化失败可用 `ec agent initialize <aid> --resume` 按原计划恢复，不能用普通 `new --force` 覆盖。
 - `ec agent persona show` 读取当前 Agent 的 `$PERSONAL_DIR/persona.md`；`--text` 或 `--file <path>` 可由当前 Agent 的 owner 写入。文件内容限制为 UTF-8 文本，`--file` 仅接受 `.md`/`.txt`。
+- `ec agent welcome --text <text>` 只用于 Bootstrap 中 Owner 已明确确认的完整文案；命令固定写入当前 Agent 的 `$PERSONAL_DIR/welcome.md`，不接受自定义路径，也不保存未确认草稿。`welcome show` 读取该文件。
+- welcome 托管写入要求当前 Agent 私聊 Owner；admin 仅可读。模板上限 4 KiB，渲染上限 8 KiB；变量为 `agentName`、`agentDescription`、`agentAid`、`agentTags`、`agentTagsText`、`ownerName`、`ownerAid`、`channel`，支持标签循环和真值条件。写入保留原始文本，投递不附加额外文案。
 - `agent show <target-aid>` 与 `agent get <target-aid> <key>` 的跨 Agent 读取对 owner/admin 开放，但普通 Agent 角色只获得安全摘要；敏感配置值和物理路径仅对 DaemonOwner 返回原值。跨 Agent 写入、启停、删除和 reload 仍遵循各自的目标与 DaemonOwner 权限边界。
+- Agent 配置可包含 `fullaccess.enabled`（默认关闭），仅可通过已认证的 EC Web Agent 设置修改。该开关受 `daemon.json.fullaccess.enabled` 总开关约束；daemon 关闭时 EC Web 隐藏该设置项。实际运行时，只有同时属于该 AgentOwner 和当前 daemonOwner 的直接私聊任务才会按调用使用宿主级 fullaccess；群聊、普通 Owner、跨 Agent 和 Trigger 不会因该开关自动提权。daemon 总开关也控制 `/fa`、`/fullaccess` 和 Fullaccess Trigger。
 
 ## 创建 Agent
 
@@ -68,6 +87,19 @@ ec agent delete <aid> [--purge]
 
 完整的创建、Bootstrap、名片发布和验收示例见：`$KITS_DOCS/evolcore/agent-create.md`。
 
+## Bootstrap 通知状态与重试
+
+交互式 Bootstrap 的 `ready` 要求有效的 `personal/welcome.md`：缺失返回 `WELCOME_REQUIRED`，损坏返回 `WELCOME_INVALID`，均保持 Bootstrap 状态。已准备 completion outbox 后修改文案返回 `WELCOME_FROZEN`。已有 active Agent 和独立的 `--initialize` 流程不需要补做此确认。
+
+`ready` 成功表示 Agent 已进入 `active`；欢迎消息单独返回在 `welcome.deliveries`，每位 Owner 一项：
+
+- `sent`：网关已接受，带 `messageId`。后续送达由网关保障。
+- `queued`：已持久化到发件箱，带 `outboxId`；临时故障自动重试，重启后继续恢复。
+- `failed`：永久失败，带错误原因和代码；普通重连或重复 `ready` 不会重新发送。
+- `not_prepared`：没有找到投递记录，不能当作发送成功。
+
+24 小时提示窗口从成功发送计算，待发提示不会因超过窗口而被删除。完成引导后取消尚未发送的首次提示。
+
 ## 头像更新
 
 头像上传通过 menu 协议或 `ec aid avatar` 暴露：
@@ -86,7 +118,7 @@ ec agent delete <aid> [--purge]
 
 约束：
 - 规范入口使用 `args.data`（data URL）或 `args.url`（HTTPS URL）二选一；控制面可用顶层 `agent` 或 `args.aid` 选择目标，Agent channel 只能修改当前 self AID。
-- 头像参数只属于 `name=aid action=avatar`，不属于 `name=agent action=update` 的 config patch；后者提交 `avatar` 或 `avatar_url` 会返回 `UNSUPPORTED_FIELD`。
+- 新客户端使用 `name=aid action=avatar`。兼容旧版 App 的 `name=agent action=update` + `args.patch.avatar=<data URL>`：头像必须单独提交，复用相同图片校验、上传和名片发布流程，不写入 config.json，成功后同样发布头像更新事件。`patch.avatar_url` 仍不支持。
 - 支持真实 MIME 为 PNG/JPEG/WebP 的图片；大小不超过 500KB，分辨率为 128–2048 像素，宽高比为 0.8–1.25。
 - 成功后头像上传到该 agent 自己的 AUN storage，`agent.md` frontmatter 写入 AID 风格 URL，并重新签名发布。
 - 托管会话中的 CLI 形式为 `ec aid avatar <当前 self AID> (--file <path> | --url <https-url>)`；仅允许 owner 在 `request`/`bypass` 模式下执行。`--file` 只能从项目目录或当前会话 `$TMPDIR` 读取，`--url` 由 daemon 下载并做 SSRF、重定向和大小校验。