evolcore 0.0.25 → 0.0.26

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

@@ -1,173 +1,178 @@
-# 创建 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
+
+多个 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 专属提示词，不加载正常的 ECK 规则、人格、记忆或命令能力卡。
+
+## 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 合法，且三个字段满足上述格式要求。
+
+然后由新 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`；`ec agent show` 的 `lifecycle` 字段也必须为 `active`。
+- `agent.md` 已成功签名发布。
+- 本地与远端 `agent.md` 的 `name`、`description`、`tags` 与 Owner 确认值一致；创建流程 skill 必须在发布后复读核验，不以初始上传响应代替。
+- 系统已创建新的主会话并发送正式欢迎消息。
+- 新 Agent 能在新主会话中处理普通任务。
+
+如果仍为 `created`，检查 channel 是否已能联系 Owner，必要时由 Owner 主动发送首条消息。如果仍为 `bootstrapping`，回到新 Agent 的 Bootstrap 会话完成字段确认、名片发布和 `ready`，不要由创建者直接绕过引导。
+
+失败重试前必须先执行状态检查：若本地 `agent.md` 已存在且远端名片已发布，只向该 Agent 发送 `ready`/续做指令，让它在自己的 Bootstrap 会话中完成收尾；不要重复创建、重复改名片或重复发布。仅在确认创建记录不存在且名片未发布时，才重新发起创建。

package/kits/docs/evolcore/agent.md

@@ -1,32 +1,32 @@
-# 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>
-
+
+# 启用 / 停用
+ec agent enable <aid>
+ec agent disable <aid>
+
 # 读 / 改单个配置字段（支持点路径，如 active_baseagent）
 ec agent get <aid> <key>
 ec agent set <aid> <key> <val>
@@ -38,43 +38,43 @@ ec agent persona --file <path>
 
 # 修改 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 字符。
 - `ec agent persona show` 读取当前 Agent 的 `$PERSONAL_DIR/persona.md`；`--text` 或 `--file <path>` 可由当前 Agent 的 owner 写入。文件内容限制为 UTF-8 文本，`--file` 仅接受 `.md`/`.txt`。
 - `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
+
+`ec agent new` 成功不代表新 Agent 已能处理普通任务。新 Agent 还必须完成 Bootstrap，并由自身执行 `ec agent ready <aid>` 进入 `active`。
+
+完整的创建、Bootstrap、名片发布和验收示例见：`$KITS_DOCS/evolcore/agent-create.md`。
+
+## 头像更新
+
 头像上传通过 menu 协议或 `ec aid avatar` 暴露：
-
-```json
-{
-  "type": "menu.action",
+
+```json
+{
+  "type": "menu.action",
   "name": "aid",
   "action": "avatar",
   "args": {
@@ -82,8 +82,8 @@ 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`。
@@ -91,8 +91,8 @@ ec agent delete <aid> [--purge]
 - 成功后头像上传到该 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` — 各子命令均支持，查看详细用法

package/kits/docs/evolcore/aid.md

@@ -1,68 +1,68 @@
-# ec aid — AID 身份管理
-
-管理本地 AID 身份（证书、私钥、agent.md 名片），以及远程探测对端 AID。触发词：身份/证书/名片/探测对端/创建身份。
-
-## 运行边界
-
-本页列出独立终端中 `ec aid` 的完整 CLI 能力。在 EvolCore 托管 Agent 会话中，为防止会话枚举、创建、删除或切换本地身份，只允许以下精确命令：
-
-```bash
-ec aid show <当前 self AID> [--format json]
-ec aid lookup <任意合法 AID> [--format json]
+# ec aid — AID 身份管理
+
+管理本地 AID 身份（证书、私钥、agent.md 名片），以及远程探测对端 AID。触发词：身份/证书/名片/探测对端/创建身份。
+
+## 运行边界
+
+本页列出独立终端中 `ec aid` 的完整 CLI 能力。在 EvolCore 托管 Agent 会话中，为防止会话枚举、创建、删除或切换本地身份，只允许以下精确命令：
+
+```bash
+ec aid show <当前 self AID> [--format json]
+ec aid lookup <任意合法 AID> [--format json]
 ec aid agentmd get <任意合法 AID> [--format json]
 # 仅 request / bypass
 ec aid agentmd put <当前 self AID> [--format json]
 ec aid avatar <当前 self AID> (--file <path> | --url <https-url>) [--format json]
-```
-
+```
+
 仅允许不带选项的基本形式，或在末尾附加一组完整的 `--format json`；不能使用 `--aun-path`、未知选项、管道、重定向或其它命令。所有 `allowAccess=true` 的已认证角色（包括 visitor、member、admin、owner 及自定义角色）均开放 `lookup` 和 `agentmd get`，目标可以是任意合法 AID。`show` 只允许当前 self AID：owner/admin 返回完整本地身份诊断，visitor/member 及其它非管理角色返回不含私钥存在性、密钥匹配和签名能力的脱敏结果。三个查询可在所有 `permissionMode` 执行。`agentmd put` 和 `avatar` 会发布远端名片，属于写操作，仅允许针对当前 self AID 的 `request`、`bypass`，`readonly`、`auto` 和未知模式均拒绝。头像支持 PNG、JPEG、WebP，大小上限 500KB，分辨率 128–2048 像素，宽高比 0.8–1.25；`--url` 仅支持 HTTPS，下载由 daemon 执行并做 SSRF/重定向校验。成功 JSON 返回 `sha256`、MIME 和尺寸元数据。`lookup` 探测指定公开 AID；`get` 下载并验签指定公开名片，同时刷新本地 AID 缓存。`list`、其它 AID 的 `show/agentmd put/avatar` 以及 `new/delete` 均拒绝。独立终端不受此托管会话限制。
-
-## 子命令
-
-```bash
-# 列出本地所有 AID（实测 sign+verify）
-ec aid list [筛选选项] [--no-verify]
-
-# 查看本地 AID 详情（证书有效期、私钥状态、签名能力）
-ec aid show <aid>
-
-# 创建新 AID 身份
-ec aid new <aid> [--force]
-
-# 远程探测 AID（是否存在 + 网关 + agent.md）
-ec aid lookup <aid>
-
-# agent.md 名片：签名上传 / 下载验签
+
+## 子命令
+
+```bash
+# 列出本地所有 AID（实测 sign+verify）
+ec aid list [筛选选项] [--no-verify]
+
+# 查看本地 AID 详情（证书有效期、私钥状态、签名能力）
+ec aid show <aid>
+
+# 创建新 AID 身份
+ec aid new <aid> [--force]
+
+# 远程探测 AID（是否存在 + 网关 + agent.md）
+ec aid lookup <aid>
+
+# agent.md 名片：签名上传 / 下载验签
 ec aid agentmd put <aid>
 ec aid agentmd get <aid>
 ec aid avatar <aid> (--file <path> | --url <https-url>)
-
-# 删除指定本地 AID（无网络注销）
-ec aid delete <aid>
-```
-
-## list 筛选选项
-
-不指定 = 列出 mine + broken + peer-cert（隐藏 no-cert）。可组合：
-- `--mine` — 仅本地可用身份（实测可签名+验签通过）
-- `--broken` — 仅有私钥但不可用（公钥不匹配 / 证书过期 / sign 失败）
-- `--peer-cert` — 仅对端 AID（无私钥，有公钥证书）
-- `--no-cert` — 仅无私钥无证书的孤儿目录
-- `--no-verify` — 跳过 sign+verify 实测，仅静态扫描（更快）
-
-输出图标：`🔑` 有私钥 · `✅` 实测可签名/验签 · `❌` 不可签名 · `⌛` 证书过期 · `📜` 有公钥证书 · `📄` 有 agent.md
-
-## delete 批量清理
-
-批量删除**默认 dry-run，加 `--yes` 才真正执行**：
-- `ec aid delete --orphan` — 清理无私钥的外部 AID 缓存
-- `ec aid delete --no-cert` — 清理无私钥也无公钥证书的孤儿目录
-- `ec aid delete --unrecoverable` — 清理云端公钥已变更、本地不可恢复的 AID
-- `--skip-pki` — 仅用于 `--unrecoverable`，跳过 PKI 探测并按本地自检结果判断；有误删风险
-
-## 通用约定
-
-- `--format json` — 对支持结构化结果的子命令输出 JSON
-- `--aun-path <path>` — 指定 AUN keystore 根；未传时可由 `AUN_HOME` 提供
-- `aid delete --orphan|--no-cert|--unrecoverable` 默认 dry-run，`--yes` 才执行删除
-- `--help` / `-h` — 各子命令均支持
+
+# 删除指定本地 AID（无网络注销）
+ec aid delete <aid>
+```
+
+## list 筛选选项
+
+不指定 = 列出 mine + broken + peer-cert（隐藏 no-cert）。可组合：
+- `--mine` — 仅本地可用身份（实测可签名+验签通过）
+- `--broken` — 仅有私钥但不可用（公钥不匹配 / 证书过期 / sign 失败）
+- `--peer-cert` — 仅对端 AID（无私钥，有公钥证书）
+- `--no-cert` — 仅无私钥无证书的孤儿目录
+- `--no-verify` — 跳过 sign+verify 实测，仅静态扫描（更快）
+
+输出图标：`🔑` 有私钥 · `✅` 实测可签名/验签 · `❌` 不可签名 · `⌛` 证书过期 · `📜` 有公钥证书 · `📄` 有 agent.md
+
+## delete 批量清理
+
+批量删除**默认 dry-run，加 `--yes` 才真正执行**：
+- `ec aid delete --orphan` — 清理无私钥的外部 AID 缓存
+- `ec aid delete --no-cert` — 清理无私钥也无公钥证书的孤儿目录
+- `ec aid delete --unrecoverable` — 清理云端公钥已变更、本地不可恢复的 AID
+- `--skip-pki` — 仅用于 `--unrecoverable`，跳过 PKI 探测并按本地自检结果判断；有误删风险
+
+## 通用约定
+
+- `--format json` — 对支持结构化结果的子命令输出 JSON
+- `--aun-path <path>` — 指定 AUN keystore 根；未传时可由 `AUN_HOME` 提供
+- `aid delete --orphan|--no-cert|--unrecoverable` 默认 dry-run，`--yes` 才执行删除
+- `--help` / `-h` — 各子命令均支持