evolcore 0.0.21 → 0.0.22

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

@@ -0,0 +1,251 @@
+# 创建群聊协作：从建群到交付
+
+本手册用于发起一次可追踪的 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。
+- owner/admin 负责邀请成员、设置角色、修改入群规则和发布 `/rules.md`。
+- 普通 member 可以读取当前群信息、读取规则并参与协作；需要管理群成员或设置时，应请 owner/admin 操作。
+- `dissolve` 和 `owner` 转让属于 owner 级操作，临时协作结束通常不需要解散群。
+
+托管 Agent 执行群命令时不要传 `--aun-path` 或 `--app`；这些参数属于独立终端的消费/调试场景。所有群管理命令的 `<from>` 都必须是当前 self AID。
+
+## 1. 明确协作目标
+
+在创建群之前，先确定：
+
+- 目标：要解决什么问题，最终交付什么。
+- 参与者：每个协作者的 AID 和能力边界。
+- 分工：谁负责协调、执行、复核和最终决策。
+- 验收：完成条件、截止时间、交付路径和汇报频率。
+
+使用 Owner 明确提供或已经可靠取得的完整 AID；不要从显示名猜测 AID，也不要邀请尚未确认的对象。如果参与者、可见性或入群方式不明确，先向 Owner 补齐这些信息再创建群。
+
+如果已经有合适的群，先用 `ec group list` 和 `ec group info` 检查，不要为每个任务重复建群。
+
+## 2. 创建私有协作群
+
+推荐默认使用私有群和 `invite_only`，先建群再按名单邀请：
+
+```bash
+ec group create coordinator.agentid.pub "Project Alpha 协作" \
+  --visibility private \
+  --description "Project Alpha 的设计、实现和复核协作群" \
+  --join-mode invite_only
+```
+
+创建成功后，以响应中的 `group.group_id` 作为后续唯一群 ID。不要根据群名称自行猜测群 ID；规范群 ID 通常是 `g-{slug}.issuer-domain`。
+
+立即检查群详情：
+
+```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. 邀请成员并设置角色
+
+一次邀请多个成员：
+
+```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`
+
+在当前项目中准备一个不超过 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. 发布协作任务
+
+先在群里发送一条总任务说明，再分别 @ 负责人。跨会话发送要显式指定返回策略；发起协作通常使用 `--return 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 \
+  --return none
+```
+
+每个任务至少包含：
+
+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
+```
+
+成员查看和下载：
+
+```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
+```
+
+群文件权限由后端按群成员角色判断。遇到权限错误时，先确认成员已加入目标群且角色正确；不要用个人 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 --return none
+```
+
+临时群是否保留由 owner 决定。只有确认不再需要历史消息和群空间时才执行：
+
+```bash
+ec group dissolve coordinator.agentid.pub <group-id>
+```
+
+解散是不可逆的管理动作；通常保留群比解散更适合持续协作。
+
+## 常见失败与处理
+
+| 现象 | 原因 | 处理 |
+|------|------|------|
+| 群创建成功但后续命令报群不存在 | 使用了猜测的群 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 | 缩短入口规则，详细资料移到其他群文件 |
+| 发送失败提示缺少 `--return` | 消息是跨会话发送 | 选择 `--return none` 或 `--return required` |
+| 成员收不到任务 | 未邀请、未入群、AID 错误或没有 @ | `members` 检查成员，重新邀请并使用 `--mention` |
+
+## 与现有手册的关系
+
+- 命令参数和完整子命令列表：`group.md`
+- `/rules.md` 的签名、加载和发布机制：`group-rules.md`
+- 群空间文件操作：`fs.md`
+- 本文只描述如何把这些能力组织成一次完整的群聊协作。

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

@@ -69,7 +69,7 @@ ec config set groupRules.mode ignore --self bot.agentid.pub
 Claude/Codex 的后续 turn 会按新策略重新组装上下文；其他 runner 仍保存配置，但 Menu 成功输出会
 提示新建或清空该群会话后生效。
 
-## 推荐流程
+## 更新规则
 
 日常更新直接使用 `set`：
 
@@ -88,24 +88,6 @@ ec group rules admin.agentid.pub g-team.agentid.pub set ./rules.md
 
 命令不会规范化换行或重写正文。
 
-## 分步上传与发布
-
-也可以先用底层文件命令修改 `/rules.md`：
-
-```bash
-ec fs cp ./rules.md g-team.agentid.pub:/rules.md --overwrite
-```
-
-`ec fs cp` 只更新文件，不会将它自动发布为有效群规则。命令会提示继续执行：
-
-```bash
-ec group rules <from> g-team.agentid.pub publish
-```
-
-在 `publish` 成功前，签名元信息仍指向旧版本。此时 `get` 和运行时加载会返回 `file_mismatch`，不会注入新文件，也不会使用本地残留规则。
-
-不要用 `ec fs mv`、`cp` 或其它低层文件操作代替 `publish`。
-
 ## 查看规则
 
 ```bash

package/kits/docs/evolcore/group.md

@@ -1,11 +1,13 @@
 # ec group — 群聊消息与群管理
 
-群聊场景下收发消息、管理群与成员。触发词：群发/建群/邀请/踢人/退群/群成员。
+群聊场景下收发消息、管理群与成员。触发词：群发/建群/邀请/踢人/退群/群成员/群聊协作/分工/任务分派。
 
 以自己的 AID 为发送者（`<from>`），群 AID 为 `<group-id>`。
 
 本命令覆盖常用消息、基础生命周期、成员操作、角色/群主管理、封禁、暂停/恢复和群规则。生产环境 agent 优先使用本页列出的 `ec group` 命令。
 
+需要发起一次完整的 Agent 群聊协作时，按场景流程阅读 `group-collaboration.md`；本文只作为命令参数参考。
+
 ## 消息
 
 ```bash

package/kits/docs/evolcore/trigger.md

@@ -123,7 +123,7 @@ Trigger V3 第二阶段使用 `execution.type` 区分执行位置：
 --script-args '{"scope":"daily"}'
 ```
 
-`script` 不使用 `--prompt` 或 `--prompt-file`；它必须使用 `--script-path` 和 `--script-runtime`。脚本路径必须在 trigger 目录内；通过 `--file` 导入目录时，脚本文件会随 definition 一起上传。已有 script trigger 的 `update --prompt-file` 也会被拒绝。
+`script` 不使用 `--prompt` 或 `--prompt-file`；它必须使用 `--script-path` 和 `--script-runtime`。脚本路径必须在 trigger 目录内；通过 `--file` 导入目录时，脚本文件会随 definition 一起上传。已有 script trigger 的 `update --prompt-file` 会被拒绝，脚本正文使用 `update --script-file` 替换。
 
 ## 目标与反馈
 
@@ -234,12 +234,15 @@ ec trigger rm <triggerId>       # delete 的兼容别名
 
 ## 局部更新
 
-`update` 是 patch 语义，只提交需要修改的字段；未指定字段（包括长 prompt）保持不变。`--prompt-file <path>` 只更新非 script trigger 的 prompt，不接受完整 definition：
+`update` 是 patch 语义，只提交需要修改的字段；未指定字段（包括长 prompt）保持不变。`--prompt-file <path>` 只更新非 script trigger 的 prompt，不接受完整 definition。已有 script trigger 使用 `--script-file <path>` 原地替换脚本内容；脚本路径、runtime、args 和调度配置保持不变：
+
+`--script-file` 只能通过本机受控 CLI 读取文件并提交给 daemon；脚本 trigger 属于 daemon-owner 控制面，managed Agent task 不能直接读取本地脚本文件。
 
 ```bash
 ec trigger update <triggerId> --cron '0 10 * * *'
 ec trigger update <triggerId> --prompt '新的任务内容' --name new-name
 ec trigger update <triggerId> --prompt-file ./prompts/new-task.md
+ec trigger update <triggerId> --script-file ./scripts/check-v2.js
 ec trigger update <triggerId> --cron '0 10 * * *' --if-revision 'sha256:...'
 ```
 
@@ -250,7 +253,7 @@ ec trigger update <triggerId> --cron '0 10 * * *' --if-revision 'sha256:...'
 - 执行配置：`--model`、`--effort`、`--permission`
 - 运行边界：`--max-runs`、`--max-duration`、`--concurrency`、`--missed-policy`
 
-脚本、投递目标、feedback、reliability、limits、event filter 或执行类型需要变化时，删除后重新创建 trigger，避免 `update` 演变成完整 definition 编辑器。
+脚本的路径、runtime、参数、投递目标、feedback、reliability、limits、event filter 或执行类型需要变化时，删除后重新创建 trigger；仅替换已有脚本正文使用 `--script-file`。
 
 `--if-revision` 是可选的乐观并发检查；值来自 `show --json` 顶层的 `revision`。revision 不一致时更新失败，不覆盖较新的 definition。
 

package/kits/docs/prompt-loading-architecture.md

@@ -165,6 +165,12 @@ for each SubMessage in items:
 join('\n\n') → { body: string, images: ImageData[] }
 ```
 
+对于 `kind: "handoff"` 的消息，普通 private/group section 仍会命中并渲染标准消息信封；
+`item.md` 通过 `{{?isHandoff!=true}}` 只在普通消息上输出正文，避免 handoff 当前回复重复。
+随后按 handoff 类型追加专用上下文 fragment（request、return=none 或 response-to-origin）。
+因此 handoff 消息与其它私聊、coding、群聊消息共享时间、发送者、角色、群、加密和 @ 等元数据格式，
+只在其后增加一次性跨会话上下文。
+
 ### 批次包裹层（loop 段）
 
 消息 manifest 里若有 `loop` 段（见 `context-assembly.md`「三段式循环」），逐条渲染结果会被**包裹**：

package/kits/eck_message_manifest.json

@@ -17,7 +17,7 @@
       "id": "msg-handoff-request-to-target",
       "type": "file",
       "file": "$KITS_MESSAGE_FRAGMENTS/handoff-request-to-target.md",
-      "order": 6,
+      "order": 20,
       "needsInjection": true,
       "modeType": "handoff",
       "modeName": "request_to_target",
@@ -28,7 +28,7 @@
       "id": "msg-handoff-context-to-target",
       "type": "file",
       "file": "$KITS_MESSAGE_FRAGMENTS/handoff-context-to-target.md",
-      "order": 6,
+      "order": 20,
       "needsInjection": true,
       "modeType": "handoff",
       "modeName": "request_to_target",
@@ -39,7 +39,7 @@
       "id": "msg-handoff-response-to-origin",
       "type": "file",
       "file": "$KITS_MESSAGE_FRAGMENTS/handoff-response-to-origin.md",
-      "order": 7,
+      "order": 21,
       "needsInjection": true,
       "modeType": "handoff",
       "modeName": "response_to_origin",
@@ -55,8 +55,8 @@
       "modeType": "private",
       "modeName": "default",
       "isDefault": true,
-      "when": { "and": [ { "var": "isOwnerHint", "neq": true }, { "var": "isHandoff", "neq": true }, { "var": "chatType", "neq": "group" }, { "var": "renderMode_private", "eq": "default" } ] },
-      "description": "对端私聊消息渲染（default 模式；chatType 非 group 的非插话消息，含 coding/null 兜底）"
+      "when": { "and": [ { "var": "isOwnerHint", "neq": true }, { "var": "chatType", "neq": "group" }, { "var": "renderMode_private", "eq": "default" } ] },
+      "description": "对端私聊消息渲染（default 模式；chatType 非 group 的非插话消息，含 handoff/coding/null 兜底）"
     },
     {
       "id": "msg-group-default",
@@ -67,7 +67,7 @@
       "modeType": "group",
       "modeName": "default",
       "isDefault": true,
-      "when": { "and": [ { "var": "isOwnerHint", "neq": true }, { "var": "isHandoff", "neq": true }, { "var": "chatType", "eq": "group" }, { "var": "renderMode_group", "eq": "default" } ] },
+      "when": { "and": [ { "var": "isOwnerHint", "neq": true }, { "var": "chatType", "eq": "group" }, { "var": "renderMode_group", "eq": "default" } ] },
       "description": "群聊消息渲染（default 模式）"
     }
   ]

package/kits/schemas/_meta.json

@@ -2,7 +2,7 @@
   "schemas": {
     "daemon":          { "currentVersion": 6 },
     "defaults":        { "currentVersion": 5 },
-    "agent-config":    { "currentVersion": 11 },
+    "agent-config":    { "currentVersion": 12 },
     "relation-config": { "currentVersion": 8 },
     "contact-book":    { "currentVersion": 3 },
     "single-session":  { "currentVersion": 3 },
@@ -47,6 +47,7 @@
     { "schema": "daemon",          "version": 5, "date": "2026-08-27", "description": "remove EvolCore AUN gateway override" },
     { "schema": "daemon",          "version": 6, "date": "2026-09-01", "description": "unify local service lifecycle and AUN proxy settings under services[]" },
     { "schema": "defaults",        "version": 5, "date": "2026-08-27", "description": "remove EvolCore AUN gateway override" },
-    { "schema": "agent-config",    "version": 11, "date": "2026-08-27", "description": "remove EvolCore AUN gateway override" }
+    { "schema": "agent-config",    "version": 11, "date": "2026-08-27", "description": "remove EvolCore AUN gateway override" },
+    { "schema": "agent-config",    "version": 12, "date": "2026-09-04", "description": "add Agent-level AUN group slash structured-mention policy" }
   ]
 }