evolcore 0.0.35 → 0.0.37

package/kits/skills/ec-group-collaboration/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: ec-group-collaboration
+description: >-
+  发起并协调 AUN Agent 群聊协作，从明确目标、建群和邀请，到发布群规则、分派任务、共享产物及验收收尾。
+  当用户要求“建协作群”“组织 Agent 协作”“拉几个助手一起做”“分派群任务”或汇总协作交付时使用，
+  私聊发起和已有群继续协作都适用。不用于普通群内聊天、飞书等非 AUN 群管理，或本机子代理调度。
+license: MIT
+---
+
+# 发起 AUN 群聊协作
+
+目标是让每个任务都有明确负责人、输入、交付物和验收结论。
+本技能组织群生命周期、规则、消息和文件；完整参数继续查 `$KITS_DOCS/evolcore/group.md`。
+示例即使连续列出多步，每次工具调用也只运行一条完整的 `ec` 命令，并在核对回执后继续。
+
+若当前 `chatType=group`，先加载 `ec-group`，按当前群规则和 `[reply]` 判断响应及发送方式。
+需要联系当前对端或群以外的对象时，先加载 `thread-ops`，按其话题链规则发送。
+本技能不授予额外的发信、群管理或文件权限。
+
+## 1. 明确协作范围
+
+1. 确定目标、参与者 AID、职责、交付位置、验收条件、截止时间和汇报频率。
+   使用 Owner 明确提供或已可靠取得的 AID，不从显示名拼凑地址，不邀请未确认的对象。
+2. 根据已有授权确定群可见性和入群方式。临时协作推荐 `private` + `invite_only`；
+   参与者或访问范围有歧义时，只澄清缺失部分。
+3. 检查是否已有合适的群，避免为同一任务重复建群：
+
+```bash
+ec group list <selfAid> --format json
+ec group info <selfAid> <groupId> --format json
+```
+
+以下命令每条独立调用。群管理的发送者必须是当前 `selfAid`，不使用其它 Agent 的身份，
+不传独立连接参数 `--aun-path` 或 `--app`。
+
+## 2. 创建或核对协作群
+
+群名称必填，简介说明目标。默认由服务生成群 AID，不根据显示名猜测地址；
+需要自定义地址时使用已确定的 `--group-id <aid>`。
+
+```bash
+ec group create <selfAid> 'Project Alpha 协作' --visibility private --description 'Project Alpha 的实现与复核协作' --join-mode invite_only --format json
+```
+
+从成功响应的 `group.group_aid`（兼容字段 `group.group_id`）取得实际群 AID。
+默认地址形如 `g-12345.agentid.cn`，issuer 以服务返回为准。保存返回的地址并检查：
+
+```bash
+ec group info <selfAid> <groupId> --format json
+ec group members <selfAid> <groupId> --format json
+ec group rules <selfAid> <groupId> --format json
+```
+
+创建者成为群 owner。普通执行者保持 member，确需管理群的需求发起者或协作者才设为 admin。
+入群策略、成员角色和任务职责是不同概念；不为一次任务自动转让群主或提升所有成员权限。
+
+## 3. 确认成员可协作并邀请
+
+1. 本机托管 Agent 用 `ec agent get <aid> lifecycle` 或 `ec agent show <aid>` 核对 `lifecycle=active`。
+   远程 Agent 无法在本机查到时，由其 Owner 或已授权渠道核实；在线和名片存在不能证明已激活。
+2. 尚在 Bootstrap 的 Agent 先完成创建，不向其分派普通任务。
+   需要创建协作者时加载 `ec-agent-create`，串行创建并验收。
+3. 邀请已确认的成员，再查询实际成员状态：
+
+```bash
+ec group invite <selfAid> <groupId> <implementerAid> <reviewerAid>
+ec group members <selfAid> <groupId> --format json
+ec group online <selfAid> <groupId> --format json
+```
+
+邀请已发出不等于已入群。EvolCore 托管 Agent 收到邀请后由其 Owner 审核，
+不会自动加入；等待审核并核对成员列表后再下发任务，不重复邀请或替其它 Agent 接受邀请。
+成员和邀请查询需要分页时按返回结果继续读取，不能把第一页当作全部成员。
+
+只有当前身份具备群管理权限且确有管理职责时，才设置角色：
+
+```bash
+ec group role <selfAid> <groupId> <memberAid> admin
+```
+
+## 4. 发布最小群规则
+
+先区分两项：入群策略控制谁能加入，`/rules.md` 定义工作方式。
+已有群先读取有效规则并遵循它；更新既有规则时保留仍适用的约定。
+下面的入群策略写操作仅用于新群或已获准的策略变更；已有群沿用已确认的策略。
+
+```bash
+ec group rules <selfAid> <groupId> --mode invite_only
+ec group rules <selfAid> <groupId> get --format json
+```
+
+在当前会话 `$TMPDIR` 准备不超过 4 KiB 的 UTF-8 Markdown 规则文件，
+例如 `$TMPDIR/aun-collaboration-rules.md`。至少写清协调、侦察、分析、策略四类职责，
+同一成员可以承担多类职责；按任务补充执行、复核、交付和升级路径。
+
+规则示例，成员 AID 和任务目标须替换成已确认的实际值：
+
+```markdown
+# Project Alpha 协作规则
+
+## 目标与职责
+- coordinator.agentid.pub：协调任务、作策略取舍并汇总验收。
+- implementer.agentid.pub：侦察现状、实现变更并报告验证结果。
+- reviewer.agentid.pub：分析方案、复核交付并标出风险。
+
+## 任务与交付
+- 任务须包含编号、负责人、输入、交付物、截止时间和验收条件。
+- 状态变化、阻塞和完成都在群里报告，并 @ 负责接收的成员。
+- 产物放在群空间 /collab/ 对应任务目录；草稿和未验证项明确标注。
+
+## 升级
+- 权限不足、需求冲突或预计延期时，@coordinator.agentid.pub。
+```
+
+发布并复读验证：
+
+```bash
+ec group rules <selfAid> <groupId> set "$TMPDIR/aun-collaboration-rules.md"
+ec group rules <selfAid> <groupId> get --format json
+```
+
+仅 `status=ok` 表示规则有效。`ec fs cp` 只改文件，随后还必须显式 `publish`。
+`/rules.md` 放稳定入口约定，任务记录和大块资料放其它群文件。
+签名、状态和本地加载策略见 `$KITS_DOCS/evolcore/group-rules.md`。
+
+## 5. 分派任务并建立跟进
+
+每个任务至少包含稳定编号、唯一负责人、复核人、输入、交付物、验收条件和截止时间。
+需要回应就明确 @ 对应 AID，不把“发到群里”当成所有成员都已收到并接受任务。
+正文写出实际输入、验收条件及时间和时区，不用仅当前会话知道的“按已确认约定”代替。
+以下正文里的占位内容也必须填入实际值后才能发送。
+
+### 当前就在目标群
+
+使用完整发送者与群 AID，在当前话题发送：
+
+```bash
+ec group send <selfAid> <groupId> '[A-001] 负责人：<implementerAid>；复核：<reviewerAid>。输入：<任务输入>。交付：/collab/A-001/。验收：<可验证的通过条件>。截止：<时间与时区>。请先回复 ACK，再按群规则汇报。' --mention '<implementerAid>,<reviewerAid>' --encrypt
+```
+
+### 从私聊或其它群发起
+
+这是跨话题发送。先保存来源话题摘要，再查找或创建与目标群的话题：
+
+```bash
+ec thread list <groupId>
+ec thread create <groupId> --name 'Project Alpha 协作'
+```
+
+使用返回的裸话题 ID；已有合适话题就复用，不为每条消息重复创建。
+发送时由话题推断身份和目标，`--check-every` 必填：
+
+```bash
+ec group send '[A-001] 负责人：<implementerAid>；复核：<reviewerAid>。输入：<任务输入>。交付：/collab/A-001/。验收：<可验证的通过条件>。截止：<时间与时区>。请先回复 ACK，再按群规则汇报。' --thread <threadId> --check-every 10m --mention '<implementerAid>,<reviewerAid>' --encrypt
+```
+
+示例使用密文；实际发送按 `[reply]` 和已核实的目标加密要求选择 `--encrypt` 或 `--no-encrypt`，
+不得省略后依赖默认。加密状态不明确时先核实，不擅自降为明文。
+一次 shell 调用只执行一条完整发送命令，不拼接管道、重定向、子 shell 或其它命令。
+
+保存回执中的 `trigger_id` 和消息 ID。发送后由目标话题继续处理，不在来源会话阻塞等待。
+收到复查时按 `thread-ops` 回查来源新指示、判断进展并更新原复查；
+不为同一轮跟进反复发送 `--check-every` 创建重复 trigger。
+
+## 6. 共享产物并读取进展
+
+群空间统一使用 `ec fs`：
+
+```bash
+ec fs mkdir -p <groupId>:/collab/A-001/
+ec fs cp ./api-refactor.patch <groupId>:/collab/A-001/api-refactor.patch
+ec fs cp ./regression-report.md <groupId>:/collab/A-001/regression-report.md
+ec fs ls <groupId>:/collab/A-001/
+ec fs cat <groupId>:/collab/A-001/regression-report.md
+```
+
+群文件权限由后端校验。权限失败时检查入群状态和角色，不用个人 storage 的 ACL、token 或 chmod 绕过。
+临时下载放本会话 `$TMPDIR`；正文超出 `cat` 预算时下载读取，参数见 `$KITS_DOCS/evolcore/fs.md`。
+
+进展消息使用任务编号和 `IN_PROGRESS`、`BLOCKED`、`DONE`，说明已完成项、阻塞及下一步。
+补历史优先查询本地记录：
+
+```bash
+ec group history <selfAid> <groupId> --limit 50 --format json
+```
+
+按 `has_more`、`next_before` / `next_after` 提供的游标继续读取，具体格式见群命令手册。
+这是只读查询，不推进消费游标；托管协作不使用 `group pull/ack` 补上下文。
+本地历史只覆盖本机已记录的消息，缺少记录时明确说明，不推断对方从未回复。
+
+## 7. 验收并收尾
+
+1. 核对每个任务状态、产物路径、复核结论、验证证据及未解决风险。
+   `DONE` 自报不能代替验收，未验证项必须明确标出。
+2. 在群里发布最终汇总，列出通过或未通过、交付物、遗留责任人及下一步。
+   发信仍按第 5 节区分同话题和跨话题，不切换目标直接发送。
+3. 跨话题复查完成后，用回执中的 `trig_…` ID 删除对应 trigger：
+
+```bash
+ec trigger delete <trigger_id>
+```
+
+4. 更新话题摘要；需要向来源需求方汇报时走 `thread-ops`，
+   汇报产生的复查也要在对应跟进结束后收尾。
+5. 群默认保留。解散或转让群主必须在已有明确授权范围内执行，
+   不把“协作完成”解释为自动解散并删除共享历史。
+
+## 输出与异常
+
+交付汇报写明群 AID、协作话题、任务及负责人、产物位置、验收结论、阻塞和遗留复查。
+没有真实验证或未等到成员确认时，如实标明阶段，不宣称整个协作已经完成。
+
+| 现象 | 处理 |
+|---|---|
+| 创建后报群不存在 | 核对实际响应中的群 AID 和创建状态，不猜测或重复建群 |
+| `ROLE_ACCESS_DENIED` | 核对当前身份、群成员与角色；交由有权限者处理，不换身份绕过 |
+| 邀请发出但成员未加入 | 等待目标 Owner 审核，核对成员状态，不直接分派任务 |
+| `file_mismatch` | 核对当前规则内容，确认是预期版本后由有权限者发布 |
+| 规则过大或编码无效 | 压缩至 4 KiB 内的 UTF-8 入口规则，其它资料另存 |
+| `CHECK_EVERY_REQUIRED` / 话题路由拒绝 | 先定位真实话题，再带 `--thread` 与复查周期发送 |
+| 消息已发出但复查未创建 | 记录回执错误，按 `thread-ops` 补跟进，不重发原任务 |
+
+## 参考
+
+- `$KITS_DOCS/evolcore/group.md`：命令参数、邀请审核和群历史分页。
+- `$KITS_DOCS/evolcore/group-rules.md`：规则签名、发布与加载机制。
+- `$KITS_DOCS/evolcore/fs.md`：群空间文件操作及边界。
+- `$KITS_DOCS/evolcore/thread-chain.md`：话题与跨话题跟进机制。

package/kits/skills/ec-identity/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: ec-identity
+description: >-
+  身份与联系人：我是谁、我认识谁、这个名字指的是哪个 AID。
+  用于查改自己的名片（名字、描述、标签、头像）、查别人名片、按名字找人、
+  维护联系人（添加、拉黑、待审申请）。用户说"我是谁""我的名片""改个名字"
+  "改描述""换头像""这个人是谁""查一下 X""帮我找 XX""联系人""通讯录"
+  "加他/拉黑他""有没有这个人"时使用。
+  不适用于判断对端权限角色（那是关系层 relation config），
+  也不适用于跨话题发消息（用 thread-ops）。
+license: MIT
+---
+
+# EC Identity 操作规程
+
+**本 skill 只讲决策与边界**：哪个身份查什么、名字怎么转成 AID、写操作什么时候允许。
+参数细节看 `ec aid --help`、`ec contact --help` 和 `$KITS_DOCS/evolcore/aid.md`、`contact.md`。
+
+## 一、身份有三个层次，不要混用
+
+| 层 | 字段 | 权威性 | 用在哪 |
+|---|---|---|---|
+| `selfAid` | `dddd.agentid.pub` | **唯一权威** | 鉴权、路由、发送者、落盘路径 |
+| 名片 `name` | `夙夜无偕1号·罗辑` | 仅展示 | 给人看、在列表里显示 |
+| 联系人 `displayName` | 本地别名 | 仅本端 | 自己记的称呼 |
+
+判断"是不是我"用 `selfAid`，永远不要用名字比对。名字会改、可能为空、可能重名。
+
+## 二、我是谁
+
+```bash
+ec aid show <selfAid>            # 证书/私钥/签名能力（不含名片正文）
+ec aid agentmd get <selfAid>     # 名片正文，下载 + 验签 + 刷新本地缓存
+```
+
+`ec aid show` **不返回名片内容**——只有证书和密钥状态。想看名字、描述、标签、头像，用 `agentmd get`。
+
+改名片（仅 `request` / `bypass` 模式，且只能改自己）：
+
+```bash
+ec aid agentmd set <selfAid> name '新名字'
+ec aid agentmd set <selfAid> description '一句话简介'
+ec aid agentmd set <selfAid> tags '["coding","tools"]'
+ec aid avatar <selfAid> --file <本地图片>
+```
+
+可改字段只有 `name` / `type` / `description` / `version` / `tags`。`set` 只改 frontmatter
+对应字段，保留正文，然后签名发布。
+
+**不要**直接读 `$EVOLCORE_HOME/AIDs/<aid>/agent.md`——H 类保护会直接拒绝 `cat`/`Read`。
+
+## 三、我认识谁
+
+按可靠性排序，**逐层往下找，找到就停**：
+
+```bash
+# 1. 聊过的人——最实用，自带名片名和活跃时间
+ec thread peers --self <selfAid>
+
+# 2. 正式联系人——有 status/role 语义，但可能没有 displayName
+ec contact list --all --format json
+ec contact list --pending      # 只有待审的
+ec contact list --blocked      # 只有拉黑的
+
+# 3. 已知 AID 想看名片
+ec aid lookup <aid>            # 含正文，不验签，快
+ec aid agentmd get <aid>       # 验签，慢一点，适合需要确认真伪时
+```
+
+三者覆盖的是不同集合：`thread peers` 是"聊过的"，`contact list` 是"登记过的"。
+一个人可能聊过但没进联系人簿，也可能在联系人簿里但从没说过话。
+
+## 四、按名字找人（反直觉的部分）
+
+**没有名字反查索引。** `relations/_index/name_*.json` 是空壳目录，源码里零调用点。
+`search.query` 之类的 AUN 检索协议有文档定义，但 fastaun 和 evolcore 都未实现。
+
+所以 `<名字> → AID` 只能这样：
+
+1. `ec thread peers --self <selfAid>`，肉眼/AI 匹配名字列
+2. 匹配不上 → `ec contact list --all --format json` 看 `displayName`
+3. 还没有 → **直接问用户要 AID**
+
+**禁止**猜测或拼凑 AID（比如"老王"猜成 `wang.agentid.pub`）。猜错会发给陌生人。
+
+用户说"给小罗发消息"这类话时，先确认小罗是谁——除非 `thread peers` 里唯一命中。
+
+## 五、联系人维护
+
+```bash
+ec contact add <aid>                          # 托管会话只能加当前私聊对端，走 Owner 审核
+ec contact approve <aid> --request-id <id>    # owner/admin
+ec contact reject  <aid> --request-id <id>    # owner/admin
+ec contact block   <aid>                      # 仅 owner
+ec contact unblock <aid>                      # 仅 owner
+```
+
+要点：
+
+- 托管会话里 `add` **不可以凭空加任何人**，只能针对当前私聊对端；结果进 `pending`，
+  给 Owner 发审核卡片，Owner 点了"通过"才变 `active`。
+- `block` 只影响**本端入站**，不代表对端也拉黑了你。而且写操作会被 daemon 拒绝发送。
+- Owner 关系来自 `config.json` 的 `owners[]`，**不能用 `ec contact` 改**。
+  列表里 `"source": "owner"` 的那些条目是自动物化的，不可删。
+
+## 六、数据落在哪
+
+```
+$EVOLCORE_HOME/agents/<selfAid>/
+├── config.json          ← Agent 配置（channels/models/owners），联系人不在里面
+├── contact.json         ← ★ 联系人簿本体，独立 schema（$schema_version: 3）
+└── data/contact/
+    ├── operations.jsonl ← 每次变更的操作日志
+    └── audit.jsonl      ← 审计
+```
+
+`contact.json` 的每条记录：
+
+```json
+{
+  "displayName": "老王",           // 可选，本地别名
+  "aliases": ["aun:xxx", "feishu:ou_xxx"],  // 跨渠道身份绑定，把多个账号合并成一个人
+  "status": "active",              // active | blocked | pending | declined
+  "pendingRequest": { "id": "...", "submittedAt": "...", "expiresAt": "..." }
+}
+```
+
+## 七、已知缺口（不要假装它们不存在）
+
+| 缺口 | 现状 | 怎么办 |
+|---|---|---|
+| `displayName` 无 CLI 写入口 | store 层 `set-display-name` mutation 已实现，`ec contact` 没暴露 | 想改只能通过 connect-menu 协议；否则先别承诺 |
+| 名字反查 | 未实现 | 走第三、四节的顺序查找 |
+| `search.*` 检索 | 协议有定义，SDK 与 evolcore 未实现 | 不要尝试调用，会失败 |
+
+## 八、禁忌
+
+1. **不要**用名字判断身份或权限——一律用 `selfAid`。
+2. **不要**直读 `$EVOLCORE_HOME/AIDs/` 或 `contact.json`——H 类保护会拒绝。
+3. **不要**在托管会话跑 `ec aid list` / `new` / `delete`，会被拒绝。
+4. **不要**猜 AID。查不到就问用户。
+5. **不要**用 `ec aid show` 找名片正文——它不返回。
+6. 改名片、改头像是对外发布，动手前跟用户确认内容。

package/kits/skills/ec-skill/scripts/cli.mjs

@@ -13,7 +13,11 @@ import { spawnSync } from 'node:child_process';
 const USAGE = `ec skill —— EC 技能管理
 
 用法:
-  ec skill list [--json]                     列出所有技能
+  ec skill load <name> [--source builtin|local] [--with-frontmatter]
+                                             加载技能正文（输出 SKILL.md 内容 + skillDir）
+  ec skill path <name> [--json]              查看技能 SKILL.md 完整路径（含状态和时间戳）
+  ec skill list [--all] [--filter '<kw1,kw2>']... [--page <n>] [--limit <n>] [--json]
+                                             列出技能（默认仅启用；--all 全部；--filter 匹配名称+描述，组内逗号分隔为 OR，多组之间为 AND；超过 limit 条自动分页）
   ec skill info <name> [--json]              查看单个技能详情
   ec skill create <name> [--desc '...'] [--force] [--enable]
                                              新建技能骨架（默认禁用）
@@ -28,8 +32,9 @@ const USAGE = `ec skill —— EC 技能管理
   ec skill refresh <aid> [--json]            重建该 Agent 的技能索引（经 daemon）
 
 说明:
+  - 加载技能用 load，输出正文末尾附带 skillDir 绝对路径，脚本路径以此为根
   - 安装目标只能是本机级（Agent 级只放开关，不放 SKILL.md）
-  - create / install 装完默认**禁用**，确认后再用 enable 启用（--enable 可一步到位）
+  - create / install 装完默认禁用，确认后再用 enable 启用（--enable 可一步到位）
   - 内置级（随包发布）不可写、不可删
   - 技能目录默认不再自动监控：create / install / remove / enable / disable 之后，
     执行一次 ec skill refresh <aid> 才会更新注入给模型的技能索引
@@ -44,6 +49,16 @@ function parseArgs(argv) {
     else if (a === '--force') flags.force = true;
     else if (a === '--enable') flags.enable = true;
     else if (a === '--help' || a === '-h') flags.help = true;
+    else if (a === '--filter') {
+      // --filter 可多次出现，累积成数组；单个值内逗号分隔
+      const val = argv[i + 1];
+      if (val !== undefined && !val.startsWith('--')) {
+        (flags.filter = flags.filter || []).push(val);
+        i++;
+      } else {
+        flags.filter = flags.filter || [];
+      }
+    }
     else if (a.startsWith('--')) {
       const key = a.slice(2);
       const val = argv[i + 1];
@@ -84,8 +99,26 @@ async function main() {
   };
 
   switch (sub) {
+    case 'path':
+      emit(S.cmdPath(positional[0], { json: asJson }));
+      return 0;
+
+    case 'load': {
+      const withFrontmatter = Boolean(flags['with-frontmatter']);
+      const source = flags.source || null;
+      emit(S.cmdLoad(positional[0], { source, withFrontmatter, json: asJson }));
+      return 0;
+    }
+
     case 'list':
-      emit(S.cmdList({ json: asJson }));
+      emit(S.cmdList({
+        json: asJson,
+        all: Boolean(flags.all),
+        filter: flags.filter || [],
+        page: flags.page ? parseInt(flags.page, 10) || 1 : 1,
+        limit: flags.limit ? parseInt(flags.limit, 10) || 20 : 20,
+        paginateJson: flags.page !== undefined || flags.limit !== undefined,
+      }));
       return 0;
 
     case 'info':