evolcore 0.0.25 → 0.0.27

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

@@ -1,173 +1,210 @@
-# 创建 EvolAgent：从创建到 Bootstrap 完成
-
-本手册用于创建一个能正常工作的 EvolAgent。创建可以由人类直接发起，也可以由已有 Agent 代办：已有 Agent 负责收集信息、创建配置并观察状态；新 Agent 仍在自己的 Bootstrap 会话中修改名片并执行 `ready`。不要把创建流水线完成误认为 Agent 已激活。
-
-### AID 与 Owner 约定
-
-- AID 必须是 `{name}.{issuer}`，例如 `helper.agentid.cn`；不要使用四级域名（如 `helper.team.agentid.cn`），也不要把显示名当作 AID。
-- `--owner` 保留现有单个 Owner 参数。
+# 创建 EvolAgent：从创建到 Bootstrap 完成
+
+本手册用于创建一个能正常工作的 EvolAgent。创建可以由人类直接发起，也可以由已有 Agent 代办：已有 Agent 负责收集信息、创建配置并观察状态；新 Agent 仍在自己的 Bootstrap 会话中修改名片并执行 `ready`。不要把创建流水线完成误认为 Agent 已激活。
+
+### AID 与 Owner 约定
+
+- AID 必须是 `{name}.{issuer}`，例如 `helper.agentid.cn`；不要使用四级域名（如 `helper.team.agentid.cn`），也不要把显示名当作 AID。
+- `--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。
-
-## 生命周期与完成标准
-
-```text
-ec agent new
-    ↓
-created
-    ↓ channel 可以联系 Owner，或 Owner 首次入站
-bootstrapping
-    ↓ 新 Agent 发布 agent.md，并执行 ec agent ready
-active
-```
-
-只有 `lifecycle=active` 才表示 Agent 已完成创建流程并可正常处理普通任务。
-
-## 1. 创建者创建 Agent
-
-多个 Agent 必须串行创建和观察。不要并行启动多个 `ec agent new`：证书、热加载和 Bootstrap 会竞争连接与资源，容易造成超时、锁等待或把失败误判为未创建。
-
-在人类直接创建时，可以使用交互模式：
-
-```bash
-ec agent new helper.agentid.pub
-```
-
-在 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 \
-  --owners '["helper-creator.agentid.pub","owner.agentid.pub"]' \
-  --name "Helper" \
+- `--owner` 与 `--owners` 互斥；未指定 `--owners` 时，现有 `--owner` 行为保持不变。
+- `--handoff <上下文>` 只附着在当前创建 Agent 的任务上，用于把已收集的 Bootstrap 信息注入该 Agent 后续处理新 Agent Bootstrap 首条消息的上下文。它不是发给新 Agent 的消息，也不要求新 Agent 返回或绑定任何 handoff。
+
+## 生命周期与完成标准
+
+```text
+ec agent new
+    ↓
+created
+    ↓ channel 可以联系 Owner，或 Owner 首次入站
+bootstrapping
+    ↓ 新 Agent 发布 agent.md，并执行 ec agent ready
+active
+```
+
+只有 `lifecycle=active` 才表示 Agent 已完成创建流程并可正常处理普通任务。
+
+## 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 会竞争连接与资源，容易造成超时、锁等待或把失败误判为未创建。
+
+在人类直接创建时，可以使用交互模式：
+
+```bash
+ec agent new helper.agentid.pub
+```
+
+在 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 \
+  --owners '["helper-creator.agentid.pub","owner.agentid.pub"]' \
+  --name "Helper" \
   --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 确认。
-
-`--owners` 只用于需要多个 Owner 的创建；普通多 Owner 创建可按实际责任关系排列顺序。使用 `--handoff` 代办创建时，当前创建 Agent 必须是 `owners[0]`。`--handoff` 的内容只在创建 Agent 的当前任务中保存和注入，目标 Agent 不会看到该参数。
-
-建议先用 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`**。
-
-创建者应维护一个最小状态账本（可放在当前任务记录中），每个 Agent 至少记录：`aid`、需求 Owner、项目路径、创建请求是否受理、`createProgress.status`、`lifecycle`、本地 `agent.md` 是否存在/字段是否完整、名片是否已发布、最近错误、下一步和最后检查时间。重启或超时恢复时先按账本逐项核对实际状态，再决定续做，不按“上次命令是否返回”推断结果。
-
-## 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 会话**中，不由创建者代替执行。若第一位 Owner 是代办创建的 Agent，它可以使用当前任务中注入的 `--handoff` 上下文代替人类回复；这不改变 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. 为每位 Owner 创建全新的主会话。
-4. 向全部 Owner 发送正式欢迎消息，并为各 Owner 绑定对应的新会话。
-
-新 Agent 在 `ready` 成功后不要从旧 Bootstrap 上下文再输出一段完成说明，也不要继续处理先前夹带的普通任务；后续工作从新主会话开始。
-
-## 6. 创建者验收
-
-```bash
-ec agent get helper.agentid.pub lifecycle
-# 应输出 active
-
-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`。
-- `agent.md` 已成功签名发布。
-- 系统已创建新的主会话并发送正式欢迎消息。
-- 新 Agent 能在新主会话中处理普通任务。
-
-如果仍为 `created`，检查 channel 是否已能联系 Owner，必要时由 Owner 主动发送首条消息。如果仍为 `bootstrapping`，回到新 Agent 的 Bootstrap 会话完成字段确认、名片发布和 `ready`，不要由创建者直接绕过引导。
-
-失败重试前必须先执行状态检查：若本地 `agent.md` 已存在且远端名片已发布，只向该 Agent 发送 `ready`/续做指令，让它在自己的 Bootstrap 会话中完成收尾；不要重复创建、重复改名片或重复发布。仅在确认创建记录不存在且名片未发布时，才重新发起创建。
+
+如果新 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
+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
+```
+
+创建成功后，若 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` 是否存在/字段是否完整、名片是否已发布、最近错误、下一步和最后检查时间。重启或超时恢复时先按账本逐项核对实际状态，再决定续做，不按“上次命令是否返回”推断结果。
+
+## 2. 触发 Bootstrap
+
+当任一已启用 channel 可以联系 Owner 时，系统会向 Owner 发送固定的 Bootstrap 首条消息，并把生命周期从 `created` 切换为 `bootstrapping`。
+
+部分 channel 不能在连接时主动定位 Owner。这种情况下 Agent 会保持 `created`；Owner 需要先在该 channel 向新 Agent 发送一条消息，系统获得回复上下文后再启动 Bootstrap。
+
+`created` 状态下 Base Agent 不处理普通消息。`bootstrapping` 状态下加载 Bootstrap 专属提示词与有渠道时的 `[reply]` 最小通信上下文，不加载正常的 ECK 规则、人格、记忆、完整渠道能力或命令能力卡。回复方式遵循实际 chatMode，不根据 Owner 是人类还是 AI 推断。
+
+## 3. Owner 与新 Agent 确认名片信息
+
+以下步骤发生在**新 Agent 自己的 Bootstrap 会话**中，不由创建者代替执行。若第一位 Owner 是代办创建的 Agent，它可以使用当前任务中注入的 `--handoff` 上下文代替人类回复；这不改变 Bootstrap 的确认规则。
+
+新 Agent 先读取系统注入路径指向的本地 `agent.md`，把其中格式有效的字段作为现有候选值：
+
+- `name`：简短清晰的显示名
+- `description`：一句到两句话描述职责或定位
+- `tags`：3 到 6 个非空标签；每个标签只允许 Unicode 字母、数字和连字符（`-`），最长 50 字符
+
+交互规则：
+
+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 合法，且三个字段满足上述格式要求。
+
+## 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
+```
+
+只有命令明确成功后才能继续。发布失败时保留已经确认的 welcome，修正发布问题后续做，不重复生成。
+多 Owner 共用该模板；需要称呼时保留 `{{ownerName}}` / `{{ownerAid}}` 供逐人渲染。投递文本不再追加未确认内容。
+
+## 6. 新 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. 为每位 Owner 创建全新的主会话。
+4. 向全部 Owner 发送正式欢迎消息，并为各 Owner 绑定对应的新会话。
+
+新 Agent 在 `ready` 成功后不要从旧 Bootstrap 上下文再输出一段完成说明，也不要继续处理先前夹带的普通任务；后续工作从新主会话开始。
+
+## 7. 创建者验收
+
+```bash
+ec agent get helper.agentid.pub lifecycle
+# 应输出 active
+
+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`；`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`，不要由创建者直接绕过引导。
+
+失败重试前必须先执行状态检查：若名片已发布且 welcome 已保存，只续做 `ready`；若 welcome 尚未确认保存，则由新 Agent 在自己的 Bootstrap 对话中补做全文生成和确认。不要重复创建、改名片或发布。仅在确认创建记录不存在且名片未发布时，才重新发起创建。

package/kits/docs/evolcore/agent.md

@@ -1,32 +1,42 @@
-# ec agent — EvolAgent 生命周期管理
-
-管理本机托管的 EvolAgent（创建、启停、配置、热重载）。触发词：创建/新建/列出/查看/启用/禁用/删除/热重载/改配置。
-
-## 子命令
-
-```bash
-# 列出所有 agent
-ec agent list
-
-# 查看 agent 详情（身份 + 配置 + 连接 + 会话 + 路径）
-ec agent show <aid>
-# 简写，等价于 show
-ec agent <aid>
-
-# 创建 agent（交互式）
-ec agent new [aid]
-
-# 创建 agent（非交互式，自动化场景）
-ec agent new <aid> --non-interactive \
-  [--project <路径>] [--baseagent claude|codex|gemini|ecagent] \
+# ec agent — EvolAgent 生命周期管理
+
+管理本机托管的 EvolAgent（创建、启停、配置、热重载）。触发词：创建/新建/列出/查看/启用/禁用/删除/热重载/改配置。
+
+## 子命令
+
+```bash
+# 列出所有 agent
+ec agent list
+
+# 查看 agent 详情（身份 + 配置 + 连接 + 会话 + 路径）
+ec agent show <aid>
+# 简写，等价于 show
+ec agent <aid>
+
+# 创建 agent（交互式）
+ec agent new [aid]
+
+# 创建 agent（非交互式，自动化场景）
+ec agent new <aid> --non-interactive \
+  [--project <路径>] [--baseagent claude|codex|gemini|ecagent] \
   [--owner <aid>] [--name "<显示名>"] [--description "<text>"] \
   [--tags '<json-array>'] \
   [--dry-run] [--force]
-
-# 启用 / 停用
-ec agent enable <aid>
-ec agent disable <aid>
-
+
+# 创建并一次性完成首次设定（隐含 --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>
+
 # 读 / 改单个配置字段（支持点路径，如 active_baseagent）
 ec agent get <aid> <key>
 ec agent set <aid> <key> <val>
@@ -36,45 +46,67 @@ 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>"
-
-# 标记 bootstrap 完成，进入 active 状态
-ec agent ready <aid>
-
-# 热重载配置（无参数 = 全量 resync：扫磁盘，新增上线/删除下线/修改热更新）
-ec agent reload [aid]
-
-# 删除 agent（--purge 连数据一并清除）
-ec agent delete <aid> [--purge]
-```
-
-## 非交互创建必填项
-
-`ec agent new <aid> --non-interactive` 时，只有 `<aid>` 必填：
-- `--project` 缺省为当前目录，并自动转为绝对路径。
-- `--baseagent` 优先使用 `agents/defaults.json`，否则检测本机可用基座。
-- `--owner` 缺省使用 `daemon.json` 的第一个 owner；未配置时省略。
-- `--name` / `--description` 缺省读取当前项目 `package.json`，再回退到目录名 / 空描述。
-- `--dry-run` 只输出最终创建计划，不注册 AID、不写配置、不上传 `agent.md`。
+
+# 标记 bootstrap 完成，进入 active 状态
+ec agent ready <aid>
+
+# 热重载配置（无参数 = 全量 resync：扫磁盘，新增上线/删除下线/修改热更新）
+ec agent reload [aid]
+
+# 删除 agent（--purge 连数据一并清除）
+ec agent delete <aid> [--purge]
+```
+
+## 非交互创建必填项
+
+`ec agent new <aid> --non-interactive` 时，只有 `<aid>` 必填：
+- `--project` 缺省为当前目录，并自动转为绝对路径。
+- `--baseagent` 优先使用 `agents/defaults.json`，否则检测本机可用基座。
+- `--owner` 缺省使用 `daemon.json` 的第一个 owner；未配置时省略。
+- `--name` / `--description` 缺省读取当前项目 `package.json`，再回退到目录名 / 空描述。
+- `--dry-run` 只输出最终创建计划，不注册 AID、不写配置、不上传 `agent.md`。
 - `--force` 覆盖已有 `config.json`；AID 密钥保留。
-- `--tags` 接受 3 到 6 个标签的 JSON 数组；每个标签只允许 Unicode 字母和数字，最长 50 字符。
+- `--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
-
-`ec agent new` 成功不代表新 Agent 已能处理普通任务。新 Agent 还必须完成 Bootstrap，并由自身执行 `ec agent ready <aid>` 进入 `active`。
-
-完整的创建、Bootstrap、名片发布和验收示例见：`$KITS_DOCS/evolcore/agent-create.md`。
-
-## 头像更新
-
+- 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
+
+`ec agent new` 成功不代表新 Agent 已能处理普通任务。新 Agent 还必须完成 Bootstrap，并由自身执行 `ec agent ready <aid>` 进入 `active`。
+
+完整的创建、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` 暴露：
-
-```json
-{
-  "type": "menu.action",
+
+```json
+{
+  "type": "menu.action",
   "name": "aid",
   "action": "avatar",
   "args": {
@@ -82,17 +114,17 @@ ec agent delete <aid> [--purge]
     "data": "data:image/png;base64,..."
   }
 }
-```
-
+```
+
 约束：
 - 规范入口使用 `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、重定向和大小校验。
 - 成功响应包含 `sha256`、`mime`、`width`、`height` 和 `aspectRatio`，便于调用方核对实际上传内容。
-
-## 通用约定
-
-- `--format json` — 用于 `list/show/new/enable/disable/get/set/rename/ready/reload/delete` 的结构化输出
-- `--help` / `-h` — 各子命令均支持，查看详细用法
+
+## 通用约定
+
+- `--format json` — 用于 `list/show/new/enable/disable/get/set/rename/ready/reload/delete` 的结构化输出
+- `--help` / `-h` — 各子命令均支持，查看详细用法