evolcore 0.0.25 → 0.0.26

package/kits/schemas/menu-exec-schema-commands.md

@@ -1,208 +1,208 @@
-# 通过 menu action exec 获取 Schema 的命令手册
-
-> 面向前端（App / Web / Bot）通过 `menu.action name=cli action=exec` 远程执行 CLI，取回配置 schema 的**版本**与**内容**。
-> 传输层、`menu.response` 配对、错误处理等通用机制见 [menu-protocol-cli-exec-frontend.md](./menu-protocol-cli-exec-frontend.md)。
-
-对应代码：`src/cli/config.ts` · `src/config/config-operation-service.ts`（`executeSchema`）· `src/config/schema-registry.ts`
-
----
-
-## 0. 请求信封（所有命令通用）
-
-固定 `name: "cli"`、`action: "exec"`，命令通过 `args.argv` 数组传入（推荐，无注入风险）：
-
-```jsonc
-{
-  "type": "menu.action",
-  "id": "<唯一请求 id>",
-  "name": "cli",
-  "action": "exec",
-  "args": { "argv": [ /* ...见下方各命令... */ ] }
-}
-```
-
-响应通过 `menu.response.id` 配对：
-
-- 成功（命令跑完）：`data = { exitCode, stdout, stderr, truncated, durationMs }`
-  - `exitCode === 0` 才算命令成功；`--format json` 时对 `stdout` 直接 `JSON.parse`。
-- 失败（透传层拒绝，命令没跑）：`error = { code, message }`。
-
-> 逻辑 schema 名（`<name>`）：`daemon` / `defaults` / `agent-config` / `relation-config` / `contact-book` / `single-session`。各名对应哪份配置见 [§6 配置 ↔ Schema 对应表](#6-配置--schema-对应表)。
-
----
-
-## 1. 获取版本
-
-### 1.1 概览 —— 列出全部 schema 及各自当前版本
-
-```jsonc
-// args.argv
-["config", "schema", "--format", "json"]
-```
-
-`stdout`（`JSON.parse` 后）：
-
-```jsonc
-{
-  "ok": true,
-  "schemas": [
-    { "name": "daemon",          "current": 1 },
-    { "name": "defaults",        "current": 1 },
-    { "name": "agent-config",    "current": 3 },
-    { "name": "relation-config", "current": 2 },
-    { "name": "contact-book",    "current": 1 },
-    { "name": "single-session",  "current": 1 }
-  ]
-}
-```
-
-### 1.2 某个 schema 的全部磁盘版本（含当前标记 + 元信息）
-
-```jsonc
-// args.argv —— 用 --list
-["config", "schema", "agent-config", "--list", "--format", "json"]
-```
-
-`stdout`：
-
-```jsonc
-{
-  "ok": true,
-  "name": "agent-config",
-  "current": 3,                       // 当前版本号
-  "versions": [
-    { "version": 1, "current": false, "date": "2026-06-14", "description": "..." },
-    { "version": 2, "current": false, "date": "2026-06-23", "description": "..." },
-    { "version": 3, "current": true,  "date": "2026-07-08", "description": "..." }
-  ]
-}
-```
-
-> `date` / `description` 来自 schema history 元信息，可能缺省。
-
----
-
-## 2. 获取 Schema 内容
-
-### 2.1 当前版本的完整定义（缺省版本号 = 当前版本）
-
-```jsonc
-// args.argv
-["config", "schema", "agent-config", "--format", "json"]
-```
-
-### 2.2 指定版本的完整定义
-
-```jsonc
-// args.argv —— 末尾追加版本号
-["config", "schema", "agent-config", "3", "--format", "json"]
-```
-
-`stdout`（2.1 / 2.2 同结构）：
-
-```jsonc
-{
-  "ok": true,
-  "name": "agent-config",
-  "version": 3,
-  "current": true,                    // 该版本是否为当前版本
-  "content": { /* 完整 schema JSON（字段/类型/枚举/默认/x-merge 等） */ }
-}
-```
-
----
-
-## 3. 命令速查
-
-| 目的 | `args.argv` |
-|------|-------------|
-| 列出全部 schema + 当前版本 | `["config","schema","--format","json"]` |
-| 列出某 schema 的所有版本 | `["config","schema","<name>","--list","--format","json"]` |
-| 查看某 schema 当前版本内容 | `["config","schema","<name>","--format","json"]` |
-| 查看某 schema 指定版本内容 | `["config","schema","<name>","<version>","--format","json"]` |
-
-三种输出模式由参数决定：
-
-| 调用形式 | `mode` | 输出 |
-|----------|--------|------|
-| `schema` | `overview` | 全部 schema + 各自当前版本号 |
-| `schema <name> --list` | `versions` | 该 schema 所有磁盘版本，`current` 标当前，附 `date`/`description` |
-| `schema <name> [version]` | `content` | 指定版本（缺省=当前）的完整 schema JSON |
-
----
-
-## 4. 错误码
-
-命令自身失败（`data.exitCode != 0`，`stdout` 为 `{ "ok": false, "code": "...", "error": "..." }`）：
-
-| `code` | 触发场景 |
-|--------|----------|
-| `UNKNOWN_SCHEMA` | 未知 schema 名（`error` 会列出已知名） |
-| `SCHEMA_VERSION_NOT_FOUND` | 版本不存在（`error` 会列出可用版本） |
-| `INVALID_CONFIG_COMMAND` | `--list` 与 version 参数同时给出 |
-| `MISSING_ARG` | `--list` 或指定 version 却未带 `<name>` |
-| `INVALID_CONFIG_VALUE` | version 非非负整数 |
-
-透传层拒绝（`menu.response.error`，命令未执行）：`NO_PERMISSION`（非 owner）、`NOT_ALLOWED`（命令不在白名单）、`MISSING_VALUE`、`NOT_SUPPORTED`（action 非 exec）、`TIMEOUT`（>15s）、`INTERNAL`。
-
-> `config schema` 为纯只读操作，数据源为 schema-registry（读 `_meta.json` + 扫描 `kits/schemas/*.schema.*.json`），人和 agent 均可执行。
-
----
-
-## 6. 配置 ↔ Schema 对应表
-
-每份配置文件由 `ConfigTarget` 路由到唯一的 schema（`src/config/config-manager.ts` 的 `TARGET_SCHEMA`）。查某份配置有哪些字段、类型/枚举/默认，就用 §2 拉对应 `<name>` 的内容。
-
-| 配置层（scope） | ConfigTarget | 磁盘文件（相对 `$EVOLCORE_HOME`） | 逻辑 schema `<name>` | 当前版本 | 校验/说明 |
-|---|---|---|---|---|---|
-| 进程级 | `process` | `daemon.json` | `daemon` | 1 | 进程配置，启动时读取；改动需重启 daemon |
-| 全局默认 | `defaults` | `agents/defaults.json` | `defaults` | 1 | 覆盖链最底层（`models.allowed` / `projects` / `aun` 等） |
-| Agent 级 | `agent` | `agents/{aid}/config.json` | `agent-config` | 3 | 单 agent 全量参数；含 user role policy |
-| 关系级 | `relation` | `agents/{aid}/relations/{peerKey}/config.json` | `relation-config` | 2 | 覆盖链最高优先；含 user/group role 分配 |
-| 联系人簿 | `contact` | `agents/{aid}/contact.json` | `contact-book` | 1 | 跨渠道身份映射的联系人别名 |
-
-**覆盖链优先级**（低 → 高，逐字段合并）：`defaults` → `agent` → `relation`。
-
-### 响应模式桶 schema —— `single-session`
-
-`single-session` 是**特殊 schema**：它不绑定任何独立配置文件，而是描述 `agent-config` / `relation-config` 里 `responseModeParams["single-session"]` 这个**桶**的形状（schema 根标记 `x-scope: "mode"`，区别于绑文件的 `process`/`agent`/`relation` 等）。它是 interactive / proactive 两模式合并为 `single-session` 后的模式特有参数容器。
-
-- 主 config schema（`agent-config` / `relation-config`）把 `responseModeParams` 当黑箱 `{type: object}` 放行；
-- 桶内部由「模式桶 schema」逐桶校验：桶键必须是已在 `_meta.json` 登记的响应模式名（如 `single-session`），校验逻辑见 `config-manager.ts` 的 `validateResponseModeParams`。
-- 想看某响应模式桶能设哪些参数，就 `["config","schema","single-session","--format","json"]`。
-
-**桶内参数**（`additionalProperties: false`，只允许下列键；均**仅 `chatmode=proactive` 时生效**）：
-
-| 字段 | 类型 | 默认 | 作用 |
-|---|---|---|---|
-| `pre_tool_1stmsgchk` | boolean | `true` | 首工具表态检查：首个工具调用前必须先向对端发消息/文件，否则拦截 |
-| `tool_use_reminder` | boolean | `true` | 工具汇报提醒：启用队列未读提醒 + 每 10 次工具调用的汇报提醒 |
-
-- schema 里的 `default` 即**运行时出厂默认**——宿主组装 `modeConfig` 时先铺这层默认（`coordinator.schemaDefaults`），再叠用户显式桶值；flow 层不再硬编码默认。
-- `chatmode` 本身**不在此桶**：它由宿主按对端类型解析后强制注入 `modeConfig.chatmode`，与「选哪个模式」正交。
-- 写入路径：`ec response set single-session ...` 或 `ec response config set <key> <value> --mode single-session --self <aid>`。经 menu exec 时把该 argv 传入即可。
-
-> ⚠️ **存量迁移**：旧配置若把这两个键写在废弃的**顶层 `proactive` 块**下，读取时会被 `foldLegacyProactiveBlock` 就地折叠进 `responseModeParams["single-session"]` 桶（桶内已显式设的同名键优先，迁移值只补空缺），旧块随下次 write 从磁盘消失。未迁移的顶层旧键在运行时会**静默失效**——运行时只从桶里读。
-
-> 每新增一个已实现的响应模式，就会多一份同名桶 schema。用 §1.1 概览命令看当前全部逻辑 schema。
-
----
-
-## 5. 完整发送样例（AUN）
-
-```typescript
-await client.call('message.send', {
-  to: targetAid,
-  payload: JSON.stringify({
-    type: 'menu.action',
-    id: 'c-schema-1',
-    name: 'cli',
-    action: 'exec',
-    args: { argv: ['config', 'schema', 'agent-config', '--format', 'json'] },
-  }),
-  encrypt: true,
-});
-// 响应在 onMessage 里按 parsed.id 配对：
-//   parsed.data.exitCode === 0 → JSON.parse(parsed.data.stdout).content
-//   parsed.error → 透传层拒绝
-```
+# 通过 menu action exec 获取 Schema 的命令手册
+
+> 面向前端（App / Web / Bot）通过 `menu.action name=cli action=exec` 远程执行 CLI，取回配置 schema 的**版本**与**内容**。
+> 传输层、`menu.response` 配对、错误处理等通用机制见 [menu-protocol-cli-exec-frontend.md](./menu-protocol-cli-exec-frontend.md)。
+
+对应代码：`src/cli/config.ts` · `src/config/config-operation-service.ts`（`executeSchema`）· `src/config/schema-registry.ts`
+
+---
+
+## 0. 请求信封（所有命令通用）
+
+固定 `name: "cli"`、`action: "exec"`，命令通过 `args.argv` 数组传入（推荐，无注入风险）：
+
+```jsonc
+{
+  "type": "menu.action",
+  "id": "<唯一请求 id>",
+  "name": "cli",
+  "action": "exec",
+  "args": { "argv": [ /* ...见下方各命令... */ ] }
+}
+```
+
+响应通过 `menu.response.id` 配对：
+
+- 成功（命令跑完）：`data = { exitCode, stdout, stderr, truncated, durationMs }`
+  - `exitCode === 0` 才算命令成功；`--format json` 时对 `stdout` 直接 `JSON.parse`。
+- 失败（透传层拒绝，命令没跑）：`error = { code, message }`。
+
+> 逻辑 schema 名（`<name>`）：`daemon` / `defaults` / `agent-config` / `relation-config` / `contact-book` / `single-session`。各名对应哪份配置见 [§6 配置 ↔ Schema 对应表](#6-配置--schema-对应表)。
+
+---
+
+## 1. 获取版本
+
+### 1.1 概览 —— 列出全部 schema 及各自当前版本
+
+```jsonc
+// args.argv
+["config", "schema", "--format", "json"]
+```
+
+`stdout`（`JSON.parse` 后）：
+
+```jsonc
+{
+  "ok": true,
+  "schemas": [
+    { "name": "daemon",          "current": 1 },
+    { "name": "defaults",        "current": 1 },
+    { "name": "agent-config",    "current": 3 },
+    { "name": "relation-config", "current": 2 },
+    { "name": "contact-book",    "current": 1 },
+    { "name": "single-session",  "current": 1 }
+  ]
+}
+```
+
+### 1.2 某个 schema 的全部磁盘版本（含当前标记 + 元信息）
+
+```jsonc
+// args.argv —— 用 --list
+["config", "schema", "agent-config", "--list", "--format", "json"]
+```
+
+`stdout`：
+
+```jsonc
+{
+  "ok": true,
+  "name": "agent-config",
+  "current": 3,                       // 当前版本号
+  "versions": [
+    { "version": 1, "current": false, "date": "2026-06-14", "description": "..." },
+    { "version": 2, "current": false, "date": "2026-06-23", "description": "..." },
+    { "version": 3, "current": true,  "date": "2026-07-08", "description": "..." }
+  ]
+}
+```
+
+> `date` / `description` 来自 schema history 元信息，可能缺省。
+
+---
+
+## 2. 获取 Schema 内容
+
+### 2.1 当前版本的完整定义（缺省版本号 = 当前版本）
+
+```jsonc
+// args.argv
+["config", "schema", "agent-config", "--format", "json"]
+```
+
+### 2.2 指定版本的完整定义
+
+```jsonc
+// args.argv —— 末尾追加版本号
+["config", "schema", "agent-config", "3", "--format", "json"]
+```
+
+`stdout`（2.1 / 2.2 同结构）：
+
+```jsonc
+{
+  "ok": true,
+  "name": "agent-config",
+  "version": 3,
+  "current": true,                    // 该版本是否为当前版本
+  "content": { /* 完整 schema JSON（字段/类型/枚举/默认/x-merge 等） */ }
+}
+```
+
+---
+
+## 3. 命令速查
+
+| 目的 | `args.argv` |
+|------|-------------|
+| 列出全部 schema + 当前版本 | `["config","schema","--format","json"]` |
+| 列出某 schema 的所有版本 | `["config","schema","<name>","--list","--format","json"]` |
+| 查看某 schema 当前版本内容 | `["config","schema","<name>","--format","json"]` |
+| 查看某 schema 指定版本内容 | `["config","schema","<name>","<version>","--format","json"]` |
+
+三种输出模式由参数决定：
+
+| 调用形式 | `mode` | 输出 |
+|----------|--------|------|
+| `schema` | `overview` | 全部 schema + 各自当前版本号 |
+| `schema <name> --list` | `versions` | 该 schema 所有磁盘版本，`current` 标当前，附 `date`/`description` |
+| `schema <name> [version]` | `content` | 指定版本（缺省=当前）的完整 schema JSON |
+
+---
+
+## 4. 错误码
+
+命令自身失败（`data.exitCode != 0`，`stdout` 为 `{ "ok": false, "code": "...", "error": "..." }`）：
+
+| `code` | 触发场景 |
+|--------|----------|
+| `UNKNOWN_SCHEMA` | 未知 schema 名（`error` 会列出已知名） |
+| `SCHEMA_VERSION_NOT_FOUND` | 版本不存在（`error` 会列出可用版本） |
+| `INVALID_CONFIG_COMMAND` | `--list` 与 version 参数同时给出 |
+| `MISSING_ARG` | `--list` 或指定 version 却未带 `<name>` |
+| `INVALID_CONFIG_VALUE` | version 非非负整数 |
+
+透传层拒绝（`menu.response.error`，命令未执行）：`NO_PERMISSION`（非 owner）、`NOT_ALLOWED`（命令不在白名单）、`MISSING_VALUE`、`NOT_SUPPORTED`（action 非 exec）、`TIMEOUT`（>15s）、`INTERNAL`。
+
+> `config schema` 为纯只读操作，数据源为 schema-registry（读 `_meta.json` + 扫描 `kits/schemas/*.schema.*.json`），人和 agent 均可执行。
+
+---
+
+## 6. 配置 ↔ Schema 对应表
+
+每份配置文件由 `ConfigTarget` 路由到唯一的 schema（`src/config/config-manager.ts` 的 `TARGET_SCHEMA`）。查某份配置有哪些字段、类型/枚举/默认，就用 §2 拉对应 `<name>` 的内容。
+
+| 配置层（scope） | ConfigTarget | 磁盘文件（相对 `$EVOLCORE_HOME`） | 逻辑 schema `<name>` | 当前版本 | 校验/说明 |
+|---|---|---|---|---|---|
+| 进程级 | `process` | `daemon.json` | `daemon` | 1 | 进程配置，启动时读取；改动需重启 daemon |
+| 全局默认 | `defaults` | `agents/defaults.json` | `defaults` | 1 | 覆盖链最底层（`models.allowed` / `projects` / `aun` 等） |
+| Agent 级 | `agent` | `agents/{aid}/config.json` | `agent-config` | 3 | 单 agent 全量参数；含 user role policy |
+| 关系级 | `relation` | `agents/{aid}/relations/{peerKey}/config.json` | `relation-config` | 2 | 覆盖链最高优先；含 user/group role 分配 |
+| 联系人簿 | `contact` | `agents/{aid}/contact.json` | `contact-book` | 1 | 跨渠道身份映射的联系人别名 |
+
+**覆盖链优先级**（低 → 高，逐字段合并）：`defaults` → `agent` → `relation`。
+
+### 响应模式桶 schema —— `single-session`
+
+`single-session` 是**特殊 schema**：它不绑定任何独立配置文件，而是描述 `agent-config` / `relation-config` 里 `responseModeParams["single-session"]` 这个**桶**的形状（schema 根标记 `x-scope: "mode"`，区别于绑文件的 `process`/`agent`/`relation` 等）。它是 interactive / proactive 两模式合并为 `single-session` 后的模式特有参数容器。
+
+- 主 config schema（`agent-config` / `relation-config`）把 `responseModeParams` 当黑箱 `{type: object}` 放行；
+- 桶内部由「模式桶 schema」逐桶校验：桶键必须是已在 `_meta.json` 登记的响应模式名（如 `single-session`），校验逻辑见 `config-manager.ts` 的 `validateResponseModeParams`。
+- 想看某响应模式桶能设哪些参数，就 `["config","schema","single-session","--format","json"]`。
+
+**桶内参数**（`additionalProperties: false`，只允许下列键；均**仅 `chatmode=proactive` 时生效**）：
+
+| 字段 | 类型 | 默认 | 作用 |
+|---|---|---|---|
+| `pre_tool_1stmsgchk` | boolean | `true` | 首工具表态检查：首个工具调用前必须先向对端发消息/文件，否则拦截 |
+| `tool_use_reminder` | boolean | `true` | 工具汇报提醒：启用队列未读提醒 + 每 10 次工具调用的汇报提醒 |
+
+- schema 里的 `default` 即**运行时出厂默认**——宿主组装 `modeConfig` 时先铺这层默认（`coordinator.schemaDefaults`），再叠用户显式桶值；flow 层不再硬编码默认。
+- `chatmode` 本身**不在此桶**：它由宿主按对端类型解析后强制注入 `modeConfig.chatmode`，与「选哪个模式」正交。
+- 写入路径：`ec response set single-session ...` 或 `ec response config set <key> <value> --mode single-session --self <aid>`。经 menu exec 时把该 argv 传入即可。
+
+> ⚠️ **存量迁移**：旧配置若把这两个键写在废弃的**顶层 `proactive` 块**下，读取时会被 `foldLegacyProactiveBlock` 就地折叠进 `responseModeParams["single-session"]` 桶（桶内已显式设的同名键优先，迁移值只补空缺），旧块随下次 write 从磁盘消失。未迁移的顶层旧键在运行时会**静默失效**——运行时只从桶里读。
+
+> 每新增一个已实现的响应模式，就会多一份同名桶 schema。用 §1.1 概览命令看当前全部逻辑 schema。
+
+---
+
+## 5. 完整发送样例（AUN）
+
+```typescript
+await client.call('message.send', {
+  to: targetAid,
+  payload: JSON.stringify({
+    type: 'menu.action',
+    id: 'c-schema-1',
+    name: 'cli',
+    action: 'exec',
+    args: { argv: ['config', 'schema', 'agent-config', '--format', 'json'] },
+  }),
+  encrypt: true,
+});
+// 响应在 onMessage 里按 parsed.id 配对：
+//   parsed.data.exitCode === 0 → JSON.parse(parsed.data.stdout).content
+//   parsed.error → 透传层拒绝
+```

package/kits/schemas/migrations/README.md

@@ -1,30 +1,30 @@
-# Schema 版本迁移函数
-
-每次某 schema 升版（`_meta.json` 里 currentVersion 上升）必须提供配套迁移函数。
-
-## 命名
-
-```
-{schema}.{N}-to-{N+1}.ts
-```
-
-例：`agent-config.1-to-2.ts`。
-
-## 契约（整文件 in/out）
-
-```typescript
-export function migrate(old: object): object;   // 旧版本完整 JSON → 新版本完整 JSON
-```
-
-- 入参/返回都是**完整对象**——整体重写，不做字段级 patch。
-- 迁移产物直接覆盖原文件（ConfigManager 在迁移前已建 schema-migration 快照保证可回滚），写回后更新 `$schema_version`。
-- 多版本串联即函数复合：`v1→v3 = migrate_2to3(migrate_1to2(old))`，逐版本串联，不跨版本直跳。
-
-## 要求
-
-- 历史 schema 文件全部保留（`{逻辑名}.schema.{版本}.json`）。
-- 每个迁移函数 default-export `migrate`，由 ConfigManager 动态 import。
-
-当前完整配置 schema 的历史迁移仍按各自模块维护。响应模式桶的
-`single-session` v2→v3 数据迁移集中在 `src/config/schema-migration.ts`，
-扫描并更新 defaults、Agent、Relation 配置文件，并在 daemon 启动前自动执行。
+# Schema 版本迁移函数
+
+每次某 schema 升版（`_meta.json` 里 currentVersion 上升）必须提供配套迁移函数。
+
+## 命名
+
+```
+{schema}.{N}-to-{N+1}.ts
+```
+
+例：`agent-config.1-to-2.ts`。
+
+## 契约（整文件 in/out）
+
+```typescript
+export function migrate(old: object): object;   // 旧版本完整 JSON → 新版本完整 JSON
+```
+
+- 入参/返回都是**完整对象**——整体重写，不做字段级 patch。
+- 迁移产物直接覆盖原文件（ConfigManager 在迁移前已建 schema-migration 快照保证可回滚），写回后更新 `$schema_version`。
+- 多版本串联即函数复合：`v1→v3 = migrate_2to3(migrate_1to2(old))`，逐版本串联，不跨版本直跳。
+
+## 要求
+
+- 历史 schema 文件全部保留（`{逻辑名}.schema.{版本}.json`）。
+- 每个迁移函数 default-export `migrate`，由 ConfigManager 动态 import。
+
+当前完整配置 schema 的历史迁移仍按各自模块维护。响应模式桶的
+`single-session` v2→v3 数据迁移集中在 `src/config/schema-migration.ts`，
+扫描并更新 defaults、Agent、Relation 配置文件，并在 daemon 启动前自动执行。