evolcore 0.0.35 → 0.0.36

package/kits/docs/evolcore/agent.md

@@ -28,17 +28,20 @@ ec agent show <aid>
 # 简写，等价于 show
 ec agent <aid>
 
-# 创建 agent（交互式）
-ec agent new [aid]
+# 创建并一次性完成首次设定（默认模式）
+ec agent new <aid> [--initialize] ...
 
-# 创建 agent（非交互式，自动化场景）
-ec agent new <aid> --non-interactive \
+# 创建 agent 并进入 Bootstrap
+ec agent new <aid> --bootstrap [--non-interactive] \
   [--project <路径>] [--baseagent claude|codex|gemini|ecagent] \
   [--owner <aid>] [--name "<显示名>"] [--description "<text>"] \
   [--tags '<json-array>'] \
   [--dry-run] [--force]
 
-# 创建并一次性完成首次设定（隐含 --non-interactive）
+# `--non-interactive` 仍可单独使用；不指定模式时默认等同于 `--initialize`
+ec agent new <aid> --non-interactive ...
+
+# 显式指定一次性初始化（隐含 --non-interactive）
 ec agent new <aid> --initialize \
   --project <路径> --baseagent <claude|codex|gemini|ecagent> \
   --owner <aid> --name "<显示名>" --description "<text>" \
@@ -78,21 +81,26 @@ ec agent reload [aid]
 ec agent delete <aid> [--purge]
 ```
 
-## 非交互创建必填项
+## 创建模式与参数
+
+`welcome --text`、`persona --text`、创建时的 `--description` / `--persona-text` 按一次 `\n` / `\r` / `\t` / `\\` 解码；已传入的物理换行保留。不要使用 PowerShell 反引号换行转义；Windows PowerShell 中直接使用命令名，不要用批处理入口传物理多行。文件、路径、`--tags` JSON 不解码；`--name` / `rename` 名称不允许换行。
 
-`welcome --text`、`persona --text`、创建时的 `--description` / `--persona-text` / `--handoff` 按一次 `\n` / `\r` / `\t` / `\\` 解码；已传入的物理换行保留。不要使用 PowerShell 反引号换行转义；Windows PowerShell 中直接使用命令名，不要用批处理入口传物理多行。文件、路径、`--tags` JSON 不解码；`--name` / `rename` 名称不允许换行。
+`ec agent new <aid>` 默认使用 `--initialize`，要求显式提供 `--owner`、`--name`、`--description` 和 `--tags`。显式选择 `--bootstrap` 才进入对话式首次设定；两者互斥，且均隐含非交互创建。`--non-interactive` 继续保留，单独使用时不改变默认的初始化模式。
 
-`ec agent new <aid> --non-interactive` 时，只有 `<aid>` 必填：
+两种模式的参数约定：
 - `--project` 缺省为当前目录，并自动转为绝对路径。
 - `--baseagent` 优先使用 `agents/defaults.json`，否则检测本机可用基座。
-- `--owner` 缺省使用 `daemon.json` 的第一个 owner；未配置时省略。
-- `--name` / `--description` 缺省读取当前项目 `package.json`，再回退到目录名 / 空描述。
+- `--owner` 必填，表示初始 Ownership 绑定目标；实际 Owner 以协议共识为准。
+- `--name` / `--description` 在初始化模式中必填；Bootstrap 模式缺省读取当前项目 `package.json`，再回退到目录名 / 默认描述。
 - `--dry-run` 只输出最终创建计划，不注册 AID、不写配置、不上传 `agent.md`。
-- `--force` 覆盖已有 `config.json`；AID 密钥保留。
+- `--force` 仅 Bootstrap 模式支持，覆盖已有 `config.json`；AID 密钥保留。
 - `--tags` 接受 3 到 6 个标签的 JSON 数组；每个标签只允许 Unicode 字母、数字和连字符（`-`），最长 50 字符。
 - `ec agent new` 支持 `--avatar-file <path>`（托管当前对端附件可用 `attachment:<id>`）或 `--avatar-url <https-url>`；创建流程沿用 `ec aid avatar` 的公共头像管线。未提供头像时跳过；已明确提供但无法规范化或上传时，创建返回可恢复错误。
-- `--initialize` 要求显式提供 `--name`、`--description`、`--tags` 和 Owner；它不从项目元数据推断名片，成功条件是目标 Agent 已进入 `active`。`--initialize` 自动包含 `--non-interactive`，不需要同时填写后者。
-- `--persona-file` / `--persona-text` 可选；两者互斥。初始化失败可用 `ec agent initialize <aid> --resume` 按原计划恢复，不能用普通 `new --force` 覆盖。
+- `--initialize` 是默认创建模式，要求显式提供 `--name`、`--description`、`--tags` 和 Owner；它不从项目元数据推断名片，成功条件是目标 Agent 已进入 `active`。它自动包含 `--non-interactive`，不需要同时填写后者。
+- `--bootstrap` 与 `--initialize` 互斥，进入原 Bootstrap 流程并隐含 `--non-interactive`。
+- `--non-interactive` 继续保留；单独使用时等同于默认的 `--initialize`。
+- `--wait <seconds>` 仅初始化模式有效，取值 0–300，默认 60。超时返回 `INITIALIZE_PENDING`，**CLI 退出码为 2**；普通失败退出码为 1；初始化完成但运行时未连接返回 `INITIALIZE_NOT_USABLE`。
+- `--persona-file` / `--persona-text` 可选；两者互斥。初始化失败可用 `ec agent initialize <aid> --resume` 按原计划恢复，不能用普通 `new --force` 覆盖。`--force` 只对 `--bootstrap` 有效。
 - `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 中 Agent 自主准备的完整正式文案，不要求 Owner 起草、审稿或确认；命令固定写入当前 Agent 的 `$PERSONAL_DIR/welcome.md`，不接受自定义路径。`welcome show` 读取该文件。
 - welcome 托管写入要求当前 Agent 私聊 Owner；admin 仅可读。模板上限 4 KiB，渲染上限 8 KiB；变量为 `agentName`、`agentDescription`、`agentAid`、`agentTags`、`agentTagsText`、`ownerName`、`ownerAid`、`channel`，支持标签循环和真值条件。写入保留原始文本，投递不附加额外文案。
@@ -101,13 +109,27 @@ ec agent delete <aid> [--purge]
 
 ## 创建 Agent
 
-`ec agent new` 成功不代表新 Agent 已能处理普通任务。新 Agent 还必须完成 Bootstrap，并由自身执行 `ec agent ready <aid>` 进入 `active`。
+默认初始化模式以新 Agent 已进入 `active` 为成功条件；初始化缺项或失败不会自动退回 Bootstrap。使用 `--bootstrap` 时，创建成功后还须完成首次设定，并由新 Agent 自身执行 `ec agent ready <aid>` 进入 `active`。
+
+EC Web 有两个独立入口：`action: create` 沿用 Bootstrap 流程（与 `--bootstrap` 同一条流水线），`action: initialize` 走一次性初始化。两者都是受理即返回，要轮询进度再判断状态。
+
+创建者侧的模式选择、创建、恢复和验收使用内置技能 `ec-agent-create`（`ec skill load ec-agent-create`）。
+生命周期机制及新 Agent 的 Bootstrap 流程参考见：`$KITS_DOCS/evolcore/agent-create.md`。
 
-完整的创建、Bootstrap、名片发布和验收示例见：`$KITS_DOCS/evolcore/agent-create.md`。
+## 初始化进度与恢复
+
+`--initialize` 的进度落在 `ec agent show <aid>` 的 `initialization` 字段：`status`、`phase`、`code`、`nextStep`、`agentmd.published`、`persona.provided`、`avatar.uploaded`。persona 正文不会出现。
+
+恢复方式：
+- 状态为 `failed` 时执行 `ec agent initialize <aid> --resume`，按原计划续跑；计划被改动返回 `INITIALIZE_PLAN_CONFLICT`。
+- daemon 启动时会自动续跑所有 `in_progress` 记录；停在 `ownerpending` 的记录在 Ownership 共识到达时自动恢复。
+- 带初始化记录的目标不能被再次 `agent new` 覆盖（`INITIALIZE_TARGET_EXISTS`），也不能触发 Bootstrap。
 
 ## Bootstrap 通知状态与重试
 
-交互式 Bootstrap 的 `ready` 要求有效的 `personal/welcome.md`：缺失返回 `WELCOME_REQUIRED`，损坏返回 `WELCOME_INVALID`，均保持 Bootstrap 状态。已准备 completion outbox 后修改文案返回 `WELCOME_FROZEN`。已有 active Agent 和独立的 `--initialize` 流程不需要补做此准备步骤。
+交互式 Bootstrap 的 `ready` 要求有效的 `personal/welcome.md`：缺失返回 `WELCOME_REQUIRED`，损坏返回 `WELCOME_INVALID`，均保持 Bootstrap 状态。已准备 completion outbox 后修改文案返回 `WELCOME_FROZEN`。
+
+`--initialize` 模式不产生也不需要 `welcome.md`：它的欢迎文案由 daemon 用内置模板按最终名片渲染，`ec agent welcome --text` 在这种目标上会返回 `INVALID_LIFECYCLE`。
 
 `ready` 成功表示 Agent 已进入 `active`；欢迎消息单独返回在 `welcome.deliveries`，每位 Owner 一项：
 

package/kits/docs/evolcore/aid.md

@@ -24,6 +24,40 @@ ec aid avatar <当前 self AID> (--file <path> | --url <https-url>) [--format js
 
 `agentmd get --format json` 返回 `verification`、来源 `source`（`remote` / `local-cache`）、内容 SHA-256 和 `localState`；有远端版本响应头时还返回 ETag / Last-Modified。`agentmd put/set --format json` 返回发布后版本信息、是否执行了版本预检，以及 `atomicVersionCheck: false`。当前 fastaun upload API 不支持条件 PUT / If-Match，因此版本预检和进程内锁**不是原子远端 CAS**：多客户端并发更新仍可能在预检后覆盖；在网关或 SDK 支持条件写入前，不应将其视为完整并发锁。
 
+## 控制 AID 的非交互注册邀约
+
+`ec init --non-interactive --owner <aid> --format json` 首先按普通 host 类型注册控制 AID，
+完成主机名片和配置落盘后，通过独立 CLI slot 的一次性长连接连接控制 AID，
+再调用与 `ec agent create` 相同的 Owner 绑定服务显式发起邀约。
+init 不等待人工审批、不启动 daemon，也不把该目标写入 `daemon.json.owner/owners`。
+容器入口随后启动 daemon，由 SDK 恢复同一任务，审批事件触发新鲜共识核验后才产生协议 Owner 权限。
+
+`bindingStatus` 为 `submitted` 仅表示 SDK 已确认邀约 `message.send` 回执；它不代表 Owner 已审批。
+`already_bound` 必须经过当前共识核验。旧版本留下的注册意图会由 SDK 恢复原任务，
+初始化复用原 `operation_id`，不重新注册身份或创建第二个绑定任务。
+提交超时返回 `unknown`，错误结果中的 `initialized: true` 表示配置和控制身份仍然保留；
+部署方应解析结果并按恢复策略启动 daemon，不能仅用 `init && start` 处理部分成功。
+相同注册意图复用原 operation_id，不同目标返回冲突，`--force` 不覆盖协议 Owner。
+实现与验证说明见 `docs/init-control-aid-owner-registration.md`。
+
+## Ownership 共识缓存
+
+Agent 的首个配置 Owner 可在该 Agent 的 AUN 私聊中发送纯 `/bind`，由 Agent
+以发送者 AID 发起协议 ownership 绑定。带参数的 `/bind feishu [实例名]` 等仍是外部渠道联系人绑定，
+不会修改 ownership；其它配置 Owner 不能使用纯 `/bind` 代替手动绑定。
+
+Ownership 共识不再每 15 秒轮询。普通消息、控制消息、查询和路由读取复用最长 30 分钟的共识结果；敏感授权、审批授权兑现、初始化激活及高权限执行使用同一结果，但要求核验时间不超过 5 分钟。读取不会延长缓存有效期，到期本身不会发请求；需要结果的异步调用在过期后等待刷新。控制通道的配对和诊断命令按敏感操作使用 5 分钟窗口。
+
+Ownership 任务事件、修改本地 Owner 配置、相关名片或 Owner 关系材料变更立即失效缓存并触发一次复核；连接首次就绪或断线后恢复也复核一次。相同任务事件和连接通知去重，无关对端、普通文件变更不触发。远端 Owner 的 Storage 事件只在本机确实收到时生效，不能假定事件完整覆盖远端变化。Owner 绑定提交前及修改 Owner 的授权不复用缓存；其它敏感操作接受最长 5 分钟的协议状态陈旧窗口。
+
+SDK 临时断线只更新连接状态，不清除已核验且仍在有效期内的共识缓存；普通读取仍按 30 分钟、敏感授权仍按 5 分钟窗口使用，断线不会延长有效期。断线前尚未完成的查询结果丢弃；缓存到期后若仍无法复核，不继续授权。客户端解绑或替换仍立即失效缓存。
+
+同一 subject 的并发刷新复用进行中的请求；事件发生前启动的旧查询不能覆盖事件后的结果。刷新失败不使用旧协议 Owner 授权，下次调用再重试，不启动后台周期重试；本地配置 Owner 和已认证 ECWeb 等独立授权来源不受此缓存替代。单次请求超时仍为 8 秒，不是 5 分钟或 30 分钟。
+
+关系快照与授权状态分离：`relation` 保留进程内最后一次确认的关系（Owner、核验时间、关系版本或已解除/未绑定状态），缓存过期、断线、事件失效或复核失败不会删除它。授权缓存仅在上述有效期和失效规则内可用，历史关系快照不用于补足已失效的授权。确认转移后替换 Owner，确认解除或未绑定后清除当前关系中的 Owner；仅凭超时、验签失败或单边声明不推断关系已经解除。历史快照不落盘，进程启动后重新确认。
+
+Agent 展示通过 `knownOwner/knownOwners` 读取关系快照，详情另返回 `ownership.authorizationStatus`（`verified` / `expired` / `unavailable`），表示协议 Owner 的五分钟授权核验状态，不代表本地配置 Owner 等独立授权来源。`owner/owners/isOwner` 等原有授权读取不回退到历史快照；依赖 AUN Owner 身份启动任务、自动压缩和重试前也检查五分钟授权，失败不启动高权限执行。欢迎消息、Bootstrap 和审批等敏感路由仍要求有效核验，不向历史 Owner 补发敏感材料。
+
 ## 更换头像
 
 `ec aid avatar <当前 self AID> --file <图片路径>` 从本地文件上传；`ec aid avatar <当前 self AID> --url <HTTPS 图片地址>` 下载图片后上传。两种来源必须二选一，可在末尾加 `--format json` 获取头像 URL、SHA-256、MIME 和尺寸。

package/kits/docs/evolcore/config.md

@@ -45,6 +45,25 @@ ec config validate [--self <aid>] [--peer <X>] [--default] [--process]
 ec config init [--self <aid>] [--peer <X>] [--default] [--process]
 ```
 
+## Provider 环境变量引用
+
+`providers.json` 的 `providers.<id>.common.baseUrl` 和 `common.apiKey` 支持整字段环境变量引用：
+
+```json
+{
+  "common": {
+    "baseUrl": "${PROVIDER_BASE_URL}",
+    "apiKey": "$PROVIDER_API_KEY"
+  }
+}
+```
+
+- 运行时从实际执行连接的进程 `process.env` 读取；Docker 容器启动参数注入的环境变量可直接使用，EC Web 只保存/转发引用，不需要额外 `.env` 转发。
+- 只支持完整字段的 `$VAR` 或 `${VAR}`；不支持拼接、插值、默认值、递归展开或 `$ENV:NAME`。
+- 配置读取、快照和 EC Web 管理响应保留引用原文，不展开也不返回环境变量值。
+- 实际连接时，变量未设置或为空会报错；`baseUrl` 解析后仍必须是 HTTP(S) URL，服务路径仍必须保持在公共 origin 内。
+- 使用变量 `baseUrl` 时不会根据 hostname 自动命名或按 hostname 自动合并 Provider；请显式填写 `name`。
+
 ## 快照 / 回滚
 
 总开关直接保存在 `$EVOLCORE_HOME/daemon.json` 顶层，默认 `true`：
@@ -231,7 +250,7 @@ Menu 批量请求遇到真实权限拒绝仍整体拒绝并停止执行，不会
 - 快照管理（snapshot/restore/init/prune）：仅人可执行
 
 **凭证安全**：
-- 凭证一律 `${VAR}` 引用，CLI 读命令永不展开、不泄露明文
+- 通用凭证配置按各自字段规则处理；Provider 的 `common.baseUrl` / `common.apiKey` 支持上述整字段 `$VAR` / `${VAR}` 引用，CLI 读命令永不展开、不泄露环境变量值
 - `.env` 全程禁读写
 
 ## 通用约定

package/kits/docs/evolcore/event.md

@@ -82,8 +82,7 @@
 | `session:forked` | `{ sessionId, sourceSessionId, name? }` |
 | `session:rewind` | `{ sessionId, turnNum, mode }` |
 | `session:imported` | `{ sessionId, agentSessionId, projectPath }` |
-| `session:chat-mode-changed` | `{ sessionId, mode, timestamp? }` |
-| `session:dispatch-mode-changed` | `{ sessionId, mode, timestamp? }` |
+| `session:idle` | `{ sessionId, agentAid, channel, channelName?, channelId, chatType?, threadId?, peerId?, encrypted?, idleMs, lastEndedAt, timestamp }` |
 
 ### message
 
@@ -211,6 +210,7 @@
 | `message:sent-out` | 使用 `task:completed` |
 | `permission:timeout` | 当前权限不会 timeout；取消用 `permission:cancelled` |
 | `session:safe-mode-entered` / `session:safe-mode-exited` | 已移除 |
+| `session:chat-mode-changed` / `session:dispatch-mode-changed` | 从未实现（仅出现在早期设计稿），当前没有替代事件；需要感知模式变化请轮询会话状态 |
 | `project:switched` / `project:bound` | 已移除 |
 | `config:corrupted` | 已移除 |
 | `agent:create-failed` | 使用 `agent:error` 且 `action = "create"` |

package/kits/docs/evolcore/fs.md

@@ -14,7 +14,7 @@
 
 ```bash
 ec fs ls  <AID>:<path>            # 列目录
-ec fs cat <AID>:<path>            # 输出文本文件；二进制/大文件返回头部摘要
+ec fs cat <AID>:<path>            # 预算内输出文本或二进制头部摘要；超出预算报错
 ec fs cp  <local> <AID>:<path>    # 上传
 ec fs cp  <AID>:<path> <local>    # 下载
 ec fs cp  <AID>:<path> <AID>:<path> # 远程复制（同后端）
@@ -50,7 +50,7 @@ ec fs umount <AID>:<path>         # 卸载挂载点
 - `--token <token>`：读取 personal storage 时携带访问 token
 - `--content-type <mime>`：上传时指定 MIME
 - `--public`：上传后公开可读（personal storage）
-- `--max-bytes <n>`：`cat` 最大直接输出字节数，默认 1MB
+- `--max-bytes <n>`：`cat` 单次读取预算，默认及最高 128 KiB（131072 字节）；托管和非托管一致，超限报 `FS_CAT_TOO_LARGE`，不返回截断正文
 - `--head-bytes <n>`：`cat` 二进制头部字节数，默认 256
 - `--visibility public|private`：`chmod` 可见性
 - `--allow-roles <roles>`：`chmod` 角色约束，写法固定为单引号包住、逗号分隔，如 `--allow-roles 'owner,admin'`
@@ -99,6 +99,22 @@ CLI 读取目标 AID 的 `agent.md`：
 
 权限由后端判断。CLI 只携带操作者、目标 AID、路径和操作。
 
+### 托管会话边界
+
+在 AUN 私聊的托管 Agent 会话中，可以直接读取当前对端 personal storage 中公开或 ACL 授权的
+文本文件：
+
+```bash
+ec fs cat <current-peer-aid>:/ability/index.json
+```
+
+这个跨 AID 入口仅限 `cat`、仅限当前私聊关系，不允许 `ls/stat/find`、写操作或切换到其他对端；
+后端 public/ACL 鉴权仍是最终依据。`cat` 单次读取最多 128 KiB，可用 `--max-bytes` 调低预算。
+个人存储内联读取携带预算加一字节的探测范围；HTTP 下载逐块计数，超限立即中止，
+单次 HTTP 读取最多等待 30 秒。文件大小元数据不能替代实际读取校验；非文本内容只返回有界摘要。
+需要更大文件时使用 `ec fs cp` 下载，不将大文件直接塞入会话上下文。
+它适合 Ability 的 L1/L3 契约读取；不满足这些条件时使用 `ec storage download` 回退。
+
 ## 能力边界
 
 - `ln -s` 只在 personal storage 创建软链；group fs facade 暂无 symlink 接口。

package/kits/docs/evolcore/group-collaboration.md

@@ -1,254 +1,21 @@
-# 创建群聊协作：从建群到交付
+# 群聊协作技能入口
 
-本手册用于发起一次可追踪的 AUN Agent 群聊协作。它不是命令全集，而是一条推荐工作流：明确目标、创建群、邀请协作者、写入群规则、分派任务、共享产物、汇总验收。
-
-本文的“协作”指群聊中的任务协同，不是版本控制式的多人文档编辑；文件交换使用当前已实现的 `ec fs` 群空间能力。
-
-## 先区分四类操作
-
-一次群聊协作通常同时涉及四个层次，不要混用：
-
-| 层次 | 用途 | 主要命令 |
-|------|------|----------|
-| 群生命周期 | 创建、邀请、角色和群状态 | `ec group create/invite/role/info/members` |
-| 入群规则 | 控制谁可以加入 | `ec group rules ... --mode ...` |
-| 协作规则文件 | 定义分工、交付格式和升级路径 | `ec group rules ... set/get` |
-| 协作消息与文件 | 分派任务、汇报进度、交换产物 | `ec group send`、`ec fs` |
-
-`/rules.md` 是群的稳定入口规则，不是任务记录，也不是知识库。任务细节放在群消息或群空间文件中。
-
-## 角色与命令边界
-
-- `<self-aid>` 是当前 Agent 的 AID。托管 Agent 会话必须使用自己的 AID，不能代替其他 Agent 发起管理操作。
-- 创建群的 Agent 自动成为群 owner。
-- 需求发起者应设置为群 admin（若需求发起者就是创建者，则其已是 owner，无需另设）。
-- owner/admin 负责邀请成员、设置角色、修改入群规则和发布 `/rules.md`。
-- 普通 member 可以读取当前群信息、读取规则并参与协作；需要管理群成员或设置时，应请 owner/admin 操作。
-- `dissolve` 和 `owner` 转让属于 owner 级操作，临时协作结束通常不需要解散群。
-
-托管 Agent 执行群命令时不要传 `--aun-path` 或 `--app`；这些参数属于独立终端的消费/调试场景。所有群管理命令的 `<from>` 都必须是当前 self AID。
-
-## 1. 明确协作目标
-
-在创建群之前，先确定：
-
-- 目标：要解决什么问题，最终交付什么。
-- 参与者：每个协作者的 AID 和能力边界。
-- 分工：谁负责协调、执行、复核和最终决策。
-- 验收：完成条件、截止时间、交付路径和汇报频率。
-
-使用 Owner 明确提供或已经可靠取得的完整 AID；AID 必须是 `{name}.{issuer}`，例如 `coordinator.agentid.cn`，不要使用四级域名或从显示名猜测 AID，也不要邀请尚未确认的对象。如果参与者、可见性或入群方式不明确，先向 Owner 补齐这些信息再创建群。
-
-如果已经有合适的群，先用 `ec group list` 和 `ec group info` 检查，不要为每个任务重复建群。
-
-## 2. 创建私有协作群
-
-群名称必填。创建前根据群名称确定一个简短、唯一的 group AID（同样使用 `{name}.{issuer}`，不要四级域名），并给出一句群简介；名称、AID 和简介应能体现协作目标。推荐默认使用私有群和 `invite_only`，先建群再按名单邀请：
-
-```bash
-ec group create coordinator.agentid.pub 'Project Alpha 协作' \
-  --visibility private \
-  --description "Project Alpha 的设计、实现和复核协作群" \
-  --join-mode invite_only
-```
-
-创建成功后，以响应中的 `group.group_aid`（兼容字段为 `group.group_id`）作为后续唯一群 AID。不要根据显示名称猜测群 AID。默认创建的名称为 `g-` 加五位数字，例如 `g-12345.agentid.cn`；自定义的 `ontology.agentid.cn` 也是合法群 AID。若返回 `warning`，仍使用实际返回的群 AID。
-
-立即检查群详情：
-
-```bash
-ec group info coordinator.agentid.pub <group-id>
-ec group members coordinator.agentid.pub <group-id>
-ec group rules coordinator.agentid.pub <group-id> --format json
-```
-
-## 3. 邀请成员并设置角色
-
-先确认所有待协作 Agent 的 `lifecycle` 都是 `active`（使用 `ec agent get/show`，不要用 `ec aid`）。在此之前不要邀请成员，也不要发送或分派任务；Bootstrap 未完成的 Agent 不能稳定接收协作工作。
-
-一次邀请多个成员：
-
-```bash
-ec group invite coordinator.agentid.pub <group-id> \
-  implementer.agentid.pub reviewer.agentid.pub researcher.agentid.pub
-```
-
-邀请后重新检查成员列表和在线状态：
-
-```bash
-ec group members coordinator.agentid.pub <group-id>
-ec group online coordinator.agentid.pub <group-id>
-```
-
-需要长期协助管理群的成员才提升为 admin；执行单个任务的协作者保持 member：
-
-```bash
-ec group role coordinator.agentid.pub <group-id> reviewer.agentid.pub admin
-```
-
-角色不是职责说明。职责、交付格式和升级路径应写入下一步的 `/rules.md`。
-
-## 4. 配置入群规则和协作规则
-
-### 4.1 设置入群策略
-
-`--mode` 控制谁能加入，和 `/rules.md` 是两回事。协作群通常使用 `invite_only` 或 `approval`：
-
-```bash
-ec group rules coordinator.agentid.pub <group-id> \
-  --mode invite_only
-```
-
-可选模式：`open`、`approval`、`invite_only`、`closed`。需要申请人说明职责时使用 `approval` 并附 `--question`；设置为 `closed` 后，新的 join 请求会被关闭，但已邀请成员不受影响。
-
-### 4.2 编写并发布 `/rules.md`
-
-团队群必须先发布一份最小 `/rules.md`。至少明确四类职责：协调（拆解任务、同步状态、最终汇总）、侦察（收集资料和事实）、分析（比较方案、识别风险）、策略（做出取舍和升级决策）。可再补充具体成员映射、交付格式和升级路径。
-
-在当前项目中准备一个不超过 4KB 的 UTF-8 Markdown 文件，例如 `project-alpha-rules.md`：
-
-```markdown
-# Project Alpha 协作规则
-
-## 目标
-- 在 2026-09-30 前完成 API 重构并通过回归测试。
-
-## 分工
-- coordinator.agentid.pub：拆解任务、同步状态、最终验收。
-- implementer.agentid.pub：实现代码并报告测试结果。
-- reviewer.agentid.pub：检查设计、风险和兼容性。
-
-## 任务格式
-- 每个任务必须包含编号、负责人、输入、交付物和验收条件。
-- 进度变化、阻塞和完成都要在群里汇报。
-
-## 交付
-- 代码和报告放入群空间 `/collab/` 下对应任务目录。
-- 未完成验证时必须明确标注，不得把草稿当成最终结果。
-
-## 升级
-- 权限不足、需求冲突或无法按期完成时，@coordinator.agentid.pub。
-```
-
-使用 `set` 会上传并立即发布，推荐直接使用：
-
-```bash
-ec group rules coordinator.agentid.pub <group-id> \
-  set ./project-alpha-rules.md
-```
-
-发布后验证有效性：
-
-```bash
-ec group rules coordinator.agentid.pub <group-id> get --format json
-```
-
-只有返回 `status: "ok"` 才表示当前 `/rules.md` 已成为有效群规则。若先用 `ec fs cp` 写入 `<group-id>:/rules.md`，还必须显式执行 `publish`；仅复制文件不会更新已签名规则索引。
-
-## 5. 发布协作任务
-
-先在群里发送一条总任务说明，再分别 @ 负责人。跨会话发送无需指定返回策略（运行时默认 `none`，不要求把群里的回答回流到当前私聊任务）：
-
-```bash
-ec group send coordinator.agentid.pub <group-id> \
-  '[A-001] API 重构协作启动。目标：完成 /collab/A-001/ 下的实现和回归报告。负责人：implementer；复核：reviewer；截止：2026-09-30 18:00。请先回复 ACK，再按规则汇报。' \
-  --mention 'implementer.agentid.pub,reviewer.agentid.pub'
-```
-
-每个任务至少包含：
-
-1. 稳定任务编号，例如 `A-001`。
-2. 唯一负责人和复核人。
-3. 明确输入、交付物、验收条件和截止时间。
-4. 约定的群空间路径或消息线程。
-
-不要只发送“大家看一下”这类无法验收的请求，也不要在没有 @ 负责人的情况下假定所有成员都会执行。
-
-## 6. 共享文件和交付物
-
-群空间使用统一的 `ec fs`，目标写成 `<group-id>:<path>`。先为任务建立目录，再上传产物：
-
-```bash
-ec fs mkdir -p <group-id>:/collab/A-001/
-ec fs cp ./api-refactor.patch <group-id>:/collab/A-001/api-refactor.patch
-ec fs cp ./regression-report.md <group-id>:/collab/A-001/regression-report.md
-```
-
-成员查看和下载：
+从明确目标、建群、邀请、发布规则，到分派任务、共享产物和验收收尾的完整流程，
+已迁移到内置 EC 技能 `ec-group-collaboration`：
 
 ```bash
-ec fs ls <group-id>:/collab/A-001/
-ec fs stat <group-id>:/collab/A-001/regression-report.md
-ec fs cat <group-id>:/collab/A-001/regression-report.md
+ec skill load ec-group-collaboration
 ```
 
-群文件权限由后端按群成员角色判断。遇到权限错误时，先确认成员已加入目标群且角色正确；不要用个人 storage 的 `chmod`、token 或其他路径操作绕过群权限，也不要改写其他 Agent 的个人路径。
-
-## 7. 进度同步与结果汇总
-
-协作者每次状态变化都应在群里汇报，推荐使用固定格式：
-
-```text
-[A-001][implementer][IN_PROGRESS]
-已完成：...
-当前阻塞：无 / ...
-下一步：...
-预计完成：...
-```
-
-负责人汇总时先读取群消息和交付目录：
-
-```bash
-ec group pull coordinator.agentid.pub <group-id> --after-seq <last-seq> --limit 100
-ec fs ls <group-id>:/collab/A-001/
-```
-
-处理完拉取结果后，用返回的序号确认已读：
-
-```bash
-ec group ack coordinator.agentid.pub <group-id> <seq>
-```
-
-如果当前已经在该群会话中，优先使用会话收到的消息；`pull` 适合补齐断线或漏读的消息，不要反复拉取同一段并重复执行任务。
-
-## 8. 验收与收尾
-
-验收前逐项核对：
-
-- 所有任务都有 `DONE` 或明确的 `BLOCKED` 状态。
-- 交付文件位于约定目录，文件名和任务编号一致。
-- 复核人已经给出结论，测试结果可复现。
-- 未解决风险、后续工作和责任人已经在群里写明。
-
-向群里发送最终汇总，明确是否通过验收：
-
-```bash
-ec group send coordinator.agentid.pub <group-id> \
-  "[A-001][DONE] 验收通过。交付：/collab/A-001/api-refactor.patch、/collab/A-001/regression-report.md。复核：reviewer.agentid.pub。遗留风险：无。" \
-  --mention-all
-```
-
-临时群是否保留由 owner 决定。只有确认不再需要历史消息和群空间时才执行：
-
-```bash
-ec group dissolve coordinator.agentid.pub <group-id>
-```
-
-解散是不可逆的管理动作；通常保留群比解散更适合持续协作。
-
-## 常见失败与处理
+技能正文位于 `$KITS/skills/ec-group-collaboration/SKILL.md`。
+适用于私聊发起和已有 AUN 群中的任务协作；普通群内响应与发言使用 `ec-group`，
+联系当前对端或群以外的对象同时使用 `thread-ops`。
 
-| 现象 | 原因 | 处理 |
-|------|------|------|
-| 群创建成功但后续命令报群不存在 | 使用了猜测的群 ID，或创建尚未完成 | 使用创建响应中的 `group_id`，再 `group info` |
-| `ROLE_ACCESS_DENIED` | 当前身份不是 owner/admin，或不在目标群 | 请 owner/admin 执行管理命令；先检查 `members` |
-| `file_mismatch` | `/rules.md` 被 `ec fs cp` 修改但未发布 | 执行 `ec group rules <from> <group-id> publish` |
-| `too_large` / 编码错误 | 规则文件超过 4KB 或不是有效 UTF-8 | 缩短入口规则，详细资料移到其他群文件 |
-| 成员收不到任务 | 未邀请、未入群、AID 错误或没有 @ | `members` 检查成员，重新邀请并使用 `--mention` |
+本页保留旧文档入口，协作流程只在技能中维护，避免命令示例随时间分叉。
 
-## 与现有手册的关系
+## 参考资料
 
-- 命令参数和完整子命令列表：`group.md`
-- `/rules.md` 的签名、加载和发布机制：`group-rules.md`
-- 群空间文件操作：`fs.md`
-- 本文只描述如何把这些能力组织成一次完整的群聊协作。
+- `group.md`：群消息、管理命令、邀请审核和只读本地历史。
+- `group-rules.md`：`/rules.md` 签名、发布、验证与上下文加载。
+- `fs.md`：个人空间和群空间的统一文件入口。
+- `thread-chain.md`：话题路由、跨话题上下文与复查。

package/kits/docs/evolcore/group.md

@@ -6,7 +6,8 @@
 
 本命令覆盖常用消息、基础生命周期、成员操作、角色/群主管理、封禁、屏蔽、成员状态、暂停/恢复和群规则。生产环境 agent 优先使用本页列出的 `ec group` 命令。
 
-需要发起一次完整的 Agent 群聊协作时，按场景流程阅读 `group-collaboration.md`；本文只作为命令参数参考。
+需要发起一次完整的 Agent 群聊协作时，加载内置技能 `ec-group-collaboration`
+（`ec skill load ec-group-collaboration`）；旧文档入口保留在 `group-collaboration.md`。本文只作为命令参数参考。
 
 ## 消息
 

package/kits/docs/evolcore/memory-consolidation-batches.md

@@ -128,6 +128,6 @@ artifacts/
 | 任务书 | `<批次目录>/context.md` | 整理会话的起点文件 |
 | 操作流水 | `<批次目录>/ops.jsonl` | 所有 ec memory 调用记录 |
 | 话题快照目录 | `<批次目录>/threads/` | 按 threadId 切分的对话历史 |
-| 主话题快照 | `<批次目录>/threads/main.md` | 无 threadId 的消息 |
+| 主话题快照 | `<批次目录>/threads/main.md` | 主话题消息（`threadId` 为 `null`/空串，或规范 id `main:<a>:<b>`——三者归入同一快照） |
 | 分话题快照 | `<批次目录>/threads/<threadId>.md` | 某个 thread 的消息 |
 | 产物目录 | `<批次目录>/artifacts/` | 本次整理产出的记忆文件（调试用） |

package/kits/docs/evolcore/menu-protocol.md

@@ -120,7 +120,7 @@ Menu Protocol 是 EvolCore 在 AUN `message.send` 之上建立的**应用层协
 ```
 
 `name="session"` 且 `args.resource="loop"` 时，`value` 必须是 JSON boolean：
-`true` 开启当前可信主会话或话题的一次闲置触发，`false` 关闭；开启时可在
+`true` 开启当前可信主话题或话题的一次闲置触发，`false` 关闭；开启时可在
 `args.idleSeconds` 指定 30–86400 的整数，省略时使用 300 秒。目标由当前关系和可信
 `thread_id` 自动选择，不接受 `sessionId`、`threadId` 或跨关系目标；关闭时不能携带
 `idleSeconds`。查询使用 `menu.query`、`name="session"`、`args.view="loop"`，返回值会标明
@@ -158,6 +158,70 @@ Menu Protocol 是 EvolCore 在 AUN `message.send` 之上建立的**应用层协
 | `/system` | `check` | `system.status` | 检查系统状态 |
 | `/gateway` | 各 action | `gateway.write` | 网关管理（需 daemon-owner） |
 | `cli` | `exec` | — | 执行任意 `ec` CLI 命令（`args.argv` 是完整 argv 数组） |
+| `file` | `search` | `file.search` | 当前项目内递归搜索文件，仅目标 Agent AID 入口 |
+
+### 项目文件搜索：`file/search`
+
+搜索请求必须发送到当前目标 Agent AID，不支持 Host/control 或 `rootId` 数据根。项目由当前可信话题会话解析，
+无话题会话时使用当前会话或 Agent 项目；客户端不能通过参数指定其他 Agent 或项目根。
+
+```json
+{
+  "type": "menu.action",
+  "id": "search-001",
+  "name": "file",
+  "action": "search",
+  "args": {
+    "path": ".",
+    "recursive": true,
+    "filename": "config",
+    "content": "timeout",
+    "extensions": ["ts", "json", "yaml"],
+    "caseSensitive": false,
+    "limit": 100
+  }
+}
+```
+
+- `path` 缺省为项目根目录，可指定项目内子目录或绝对目录；拒绝 `..`、项目外路径及符号链接，即使调用者是 owner。
+- `recursive` 缺省为 `true`。只返回普通文件，不跟随符号链接，默认跳过 `.git`、`node_modules` 子目录。
+- 隐藏配置文件（如 `.env`）可搜索，不自动应用 `.gitignore`。
+- `filename` 对文件名做普通字符串包含匹配，不匹配目录路径；`content` 对 UTF-8 文本做普通字符串匹配。
+- `caseSensitive` 缺省为 `false`，比较时统一小写，返回的摘要保留原文；不解释正则或通配符。
+- `extensions` 为最多 64 个最后扩展名，接受 `ts` / `.ts`，不区分大小写，内部为 OR；单点隐藏文件 `.env` 可用 `env` 筛选。
+- 文件名、内容、扩展名三类条件为 AND，至少提供一个有效条件。文件名及内容条件各最多 1024 字符。
+- `limit` 缺省为 100，取值 1–500；不提供分页、全文索引或精确总数。
+- 需要 `file.search` 和 `file.list` 权限；有内容条件时还需要 `file.fetch`。读取前逐文件复查路径约束，不能绕过已有权限禁用。
+
+成功的 `menu.response.data` 示例：
+
+```json
+{
+  "path": ".",
+  "entries": [{
+    "path": "src/config.ts",
+    "name": "config.ts",
+    "size": 4096,
+    "mtime": 1792494000000,
+    "matches": [{ "line": 42, "text": "const timeout = 5000;" }]
+  }],
+  "count": 1,
+  "scannedFiles": 12,
+  "truncated": false,
+  "truncatedReason": null,
+  "skipped": { "binary": 0, "unsupportedEncoding": 0, "tooLarge": 0, "unreadable": 0, "symlink": 0 }
+}
+```
+
+路径始终相对项目根目录并使用 `/`；`size` 单位为字节，`mtime` 为 Unix 毫秒时间戳。
+同一文件只返回一次，内容命中最多 3 行，每行摘要最多 200 字符；无内容条件时 `matches` 为空数组。
+支持 UTF-8 BOM，普通跨行字符串统一 CRLF/CR 为 LF 后匹配，行号指命中起始行。
+无效 UTF-8、含 NUL 或明显二进制内容会跳过；不解析 PDF、Office、压缩包，也不按扩展名白名单排除文本。
+
+内容按固定大小缓冲块读取，单文件上限 2 MiB；文件名/扩展名搜索不受内容大小限制。
+单次扫描预算 5 秒、最多访问 10000 个目录项，搜索响应数据预留元信息后限制在 64 KiB 内。
+提前停止时 `truncated=true`，`truncatedReason` 为 `time_limit`、`file_limit`、`result_limit` 或 `response_limit`。
+`truncated` 仅表示没有完成遍历，不保证还有其他匹配；跳过数量只反映已访问条目，不返回权限拒绝的文件清单或专门的拒绝计数。
 
 ---