evolcore 0.0.28 → 0.0.29

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

@@ -0,0 +1,213 @@
+# Menu Protocol 规范
+
+Menu Protocol 是 EvolCore 在 AUN `message.send` 之上建立的**应用层协议**，与 AUN SDK 本身无关。任何能发送 AUN 消息的客户端，只要按照本文约定的 payload 格式发送，都可以与 EvolCore daemon 交互。对应实现：`src/core/command/menu-protocol.ts`、`src/aun/menu/`。
+
+---
+
+## 一、传输层约定
+
+所有 Menu 请求通过 AUN `message.send` 点对点发送给 daemon 的 Control AID：
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| `to` | daemon control AID | 目标 daemon 的 AID |
+| `encrypt` | `true` | 必须 E2EE 加密 |
+| `ttl` | `60` | 秒，短生命周期 |
+| `payload` | menu request 对象 | 见下方消息类型 |
+| `protected_headers` | 见下方 | 身份认证信息 |
+
+响应通过 daemon 向请求方 AID 发送 `menu.response` 消息，以 `id` 字段配对。
+
+---
+
+## 二、protected_headers
+
+随每条 menu 请求携带，字段均为小写字符串：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `client_name` | `'evol'` \| `'Evol App'` \| `'ec-menu-client'` | 客户端标识；缺失视为旧版 Evol 客户端 |
+| `client_version` | string | 客户端版本号；`ec-menu-client` 时必填，格式 `X.Y.Z` |
+| `evol_version` | string | Evol App 兼容版本字段 |
+| `sdk_version` | string | fastaun SDK 版本；`>= 0.5.17` 时启用 volatile 传输与 `to_device_id` 定向回复 |
+| `auth_method` | `'daemon-owner'` \| `'remote-access-token'` \| `'ecweb-token'` | 身份验证方式；缺失视为 daemon-owner |
+| `remote_access_token` | string | daemon 签发的远程访问 token；`auth_method=remote-access-token` 时填写 |
+| `ecweb_token` | string | `remote_access_token` 的兼容别名 |
+
+**鉴权说明**：`auth_method` 字段本身只是提示，真正的 `daemon-owner` 判定依赖 AUN 连接层认证的发送方 AID 是否在 daemon 配置的 `owners` 列表里。`remote-access-token` 由 daemon 通过配对码兑换签发，权限与 daemon-owner 等同。
+
+---
+
+## 三、消息类型
+
+### `menu.token.request`
+
+获取 menu token，用于后续 menu.list / menu.query 等需要 token 的请求。
+
+```json
+{
+  "type": "menu.token.request",
+  "id": "<uuid>",
+  "args": {}
+}
+```
+
+### `menu.list`
+
+查询命令目录（catalog）或某个命令的当前值（values）。
+
+```json
+{
+  "type": "menu.list",
+  "id": "<uuid>",
+  "menu_token": "<token>",
+  "name": "<命令名>",
+  "args": { "view": "catalog", "context": { "kind": "process" } }
+}
+```
+
+`context.kind` 取值：`private_relation` / `group_relation` / `agent` / `process`。
+
+### `menu.query`
+
+查询命令的结构化数据（状态、详情等）。超时后自动重发一次（幂等操作）。
+
+```json
+{
+  "type": "menu.query",
+  "id": "<uuid>",
+  "name": "system",
+  "args": { "view": "status" }
+}
+```
+
+常用 `name` + `args.view` 组合：
+
+| name | args.view | 说明 |
+|------|-----------|------|
+| `system` | `status` | daemon 状态 |
+| `system` | `monitor` | 运行时监控 |
+| `system` | `logs` | daemon 日志（`source`/`limit` 可选） |
+| `session` | `subtasks` | 会话子任务列表 |
+| `baseagents` | —— | 已加载 baseagent 列表 |
+| `config` | `rawFile` | 原始配置文件（需 `resource` 参数） |
+
+### `menu.options`
+
+查询某命令的可选项列表（如可切换的模型列表）。超时后自动重发一次。
+
+```json
+{
+  "type": "menu.options",
+  "id": "<uuid>",
+  "name": "baseagent",
+  "args": {}
+}
+```
+
+### `menu.update`
+
+更新配置类命令（如切换模型、修改设置）。**不自动重试**。
+
+```json
+{
+  "type": "menu.update",
+  "id": "<uuid>",
+  "name": "/model",
+  "cmd": "/model",
+  "args": { "value": "claude-opus-5-5" }
+}
+```
+
+### `menu.action`
+
+触发动作类命令（如创建 agent、重启、生成配对码）。**不自动重试**。
+
+```json
+{
+  "type": "menu.action",
+  "id": "<uuid>",
+  "name": "<name>",
+  "action": "<action>",
+  "args": { "argv": ["--name", "myagent"] }
+}
+```
+
+`args.argv`（数组，推荐）优先于 `args.command`（字符串，daemon 侧分词）。
+
+常用 `name` + `action` 组合：
+
+| name | action | operation | 说明 |
+|------|--------|-----------|------|
+| `/agent` | `create` | `agent.create` | 创建 agent（需 daemon-owner） |
+| `/agent` | `initialize` | `agent.initialize` | 初始化 agent（需 daemon-owner） |
+| `/agent` | `delete` | `agent.delete` | 删除 agent（需 daemon-owner） |
+| `/agent` | `enable` | `agent.enable` | 启用 agent（需 daemon-owner） |
+| `/agent` | `disable` | `agent.disable` | 禁用 agent（需 daemon-owner） |
+| `/agent` | `reload` | `agent.reload` | 热重载 agent |
+| `/system` | `restart` | `system.restart` | 重启 daemon（需 daemon-owner） |
+| `/system` | `upgrade` | `system.upgrade` | 升级（需 daemon-owner） |
+| `/system` | `paircode` | `system.paircode` | 生成配对码（需 daemon-owner，不接受 remote token） |
+| `/system` | `check` | `system.status` | 检查系统状态 |
+| `/gateway` | 各 action | `gateway.write` | 网关管理（需 daemon-owner） |
+| `cli` | `exec` | — | 执行任意 `ec` CLI 命令（`args.argv` 是完整 argv 数组） |
+
+---
+
+## 四、menu.response 格式
+
+daemon 通过 `message.send` 回复，payload 结构：
+
+```json
+{
+  "type": "menu.response",
+  "id": "<配对的请求 id>",
+  "data": { ... },
+  "error": {
+    "code": "ROLE_ACCESS_DENIED",
+    "message": "...",
+    "data": {}
+  }
+}
+```
+
+`data` 和 `error` 互斥。`data` 存在时表示成功；`error` 存在时表示 daemon 拒绝或执行失败。对于 `cli exec`，成功时 `data = { exitCode, stdout, stderr, truncated, durationMs }`，`exitCode === 0` 才是命令本身成功。
+
+---
+
+## 五、operation 与鉴权
+
+Menu 请求进入 daemon 后，`menu-handler.ts` 将 `name` + `action`/`view` 解析为内部 `operation` 字符串（如 `agent.create`），再经过 `operation-authorizer.ts` 做角色判定：
+
+- **需要 daemon-owner 的 operation**（`agent.create` / `agent.delete` / `system.restart` 等）：发送方 AID 必须在 daemon `owners` 列表中，或持有有效的 `remote-access-token`
+- **management role 可用的 operation**（`agent.show` / `config.*` 等）：需要 agent 的 owner/admin 角色
+- **关系角色可用的 operation**（`ec.msg.send` / trigger 等）：需要 agent 与发送方之间的关系角色配置
+
+权限判定完全在 daemon 侧，客户端无法通过 `auth_method` 字段自行提升权限。
+
+---
+
+## 六、`cli exec` 路径
+
+通过 `name=cli action=exec args.argv=[...]` 可以远程执行任意 `ec` CLI 命令：
+
+```json
+{
+  "type": "menu.action",
+  "id": "exec-1",
+  "name": "cli",
+  "action": "exec",
+  "args": { "argv": ["agent", "list", "--format", "json"] }
+}
+```
+
+响应的 `data.stdout` 是命令的标准输出。Schema 相关命令详见 `$KITS/schemas/menu-exec-schema-commands.md`。
+
+---
+
+## 七、参考
+
+- 使用 `ec menu-client` 发送 menu 请求（CLI 语法、参数、退出码）：`$KITS_DOCS/evolcore/menu-client.md`
+- Schema 查询的完整命令手册：`$KITS/schemas/menu-exec-schema-commands.md`（位于 `$KITS_DOCS` 之外，不在别名解析范围内，按此物理路径 Read）
+- 实现入口：`src/core/command/menu-protocol.ts`、`src/core/command/menu-handler.ts`
+- 鉴权核心：`src/core/auth/operation-authorizer.ts`、`src/core/auth/auth-gateway.ts`

package/kits/docs/evolcore/msg.md

@@ -13,6 +13,8 @@
 
 ## 发送消息
 
+长文本内联参数统一约定：普通命令调用不变；将字面量 `\n`、`\r`、`\t`、`\\` 分别按一次解码为换行、回车、制表符、反斜杠。Shell 已传入的真实换行保持原样；不要使用 PowerShell 的反引号换行转义，它会在 CLI 之前改变 argv。Windows PowerShell 请调用命令名，不要显式调用批处理入口传物理多行。仅解码正文和文本选项（`--description`、`--text`、`--transcript`、`--handoff-context`）；文件内容、路径、`--payload` JSON、标题均不解码。审批仍按 Shell 传入的原始 argv 校验。
+
 ```bash
 # 文本（明文）
 ec msg send <from> <to> "<text>" --return none|required

package/kits/docs/evolcore/trigger.md

@@ -30,10 +30,12 @@ ec trigger history [triggerId] --limit 500 --json
 
 `show --json` 返回完整 definition、definition `revision` 和精简运行态。active run 只包含标识、阶段、时间和 `eventCount`；schedule 不返回 `sourceSignature`；recent runs 只包含状态与时间摘要；script 只返回路径、runtime、大小和 mtime，不内联脚本文本。完整运行审计使用 `history` 查询。
 
-`history` 查询 `data/triggers/<aid>/history.jsonl` 中的长期审计事件，包括定义创建、完整更新快照、启停、删除 tombstone 和 run 终态。删除 trigger 目录后，历史仍保留。
+`history` 查询 `agents/<aid>/triggers/history.jsonl` 中的长期审计事件，包括定义创建、完整更新快照、启停、删除 tombstone 和 run 终态。删除 trigger 目录后，历史仍保留。
 
 ## 创建
 
+CLI 的内联 `--prompt`（create / set / update）及 update 的 `--description` 使用相同的单次 `\n` / `\r` / `\t` / `\\` 解码；物理换行原样保留。PowerShell 不使用反引号换行转义，Windows 多行直接调用命令名，不显式调用批处理入口。`--prompt-file` 文件内容、脚本路径和标识符不解码；不强制改用文件或结构化 argv。
+
 创建操作统一使用 `create`：
 
 | 入口 | 正式命令 | 兼容别名 |
@@ -242,7 +244,7 @@ ec trigger rm <triggerId>       # delete 的兼容别名
 
 `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 不能直接读取本地脚本文件。主机 fullaccess 开关缺失时默认开启；Agent 级 `fullaccess.enabled` 不会自动升级 Trigger，Trigger 仍按自身 execution.permissionMode 规则执行。
+`--script-file` 只能通过本机受控 CLI 读取文件并提交给 daemon；脚本 trigger 属于 daemon-owner 控制面，managed Agent task 不能直接读取本地脚本文件。Agent 级 `fullaccess.enabled` 不会自动升级 Trigger，Trigger 仍按自身 execution.permissionMode 规则执行；`permissionMode=fullaccess` 由 daemon-owner 批准链控制。
 
 ```bash
 ec trigger update <triggerId> --cron '0 10 * * *'
@@ -279,9 +281,9 @@ ec trigger run <triggerId> --dry-run
 ## 审计存储
 
 ```text
-data/triggers/<aid>/<triggerId>/trigger.json
-data/triggers/<aid>/<triggerId>/active.json
-data/triggers/<aid>/history.jsonl
+agents/<aid>/triggers/<triggerId>/trigger.json
+agents/<aid>/triggers/<triggerId>/active.json
+agents/<aid>/triggers/history.jsonl
 logs/trigger-runs.log
 ```
 

package/kits/docs/path-registry.md

@@ -45,18 +45,16 @@
 | `$AGENT_INDEX` | `$AGENT_DIR/index` | agent 级索引 |
 | `$PEER_DIR` | `$RELATIONS_DIR/<peerKey>` | 当前对端的关系目录 |
 
-## 外部依赖路径（需寻找）
+## 外部依赖路径
 
-| 名称 | 寻找规则 | 说明 |
-|------|----------|------|
-| `$AUN_SDK` | `node -e "console.log(require.resolve('@agentunion/fastaun/package.json'))"` | 本机是本地依赖 `$PACKAGE_ROOT/node_modules/@agentunion/fastaun`，`npm ls -g` 查不到 |
-| `$AUN_PROTOCOL_DOCS` | `$AUN_SDK/_packed_docs/protocol` | 注意是 `_packed_docs/`，该包**没有** `docs/` 目录 |
-
-`$KITE` / `$AUN_SDK_CORE`（Kite 框架时代的 SDK 源码路径）已废弃，不再有对应实现。
+| 名称 | 路径 | 说明 |
+|------|------|------|
+| `$AUN_SDK` | npm 包 `@agentunion/fastaun` 的安装目录 | AUN SDK安装目录，本机通常在 `$PACKAGE_ROOT/node_modules/@agentunion/fastaun`，但包管理器或安装方式不同时路径会变；以包名为准，具体路径由安装环境决定 |
+| `$AUN_SDK_DOCS` | `$AUN_SDK/_packed_docs` | AUN SDK文档根目录；包内**没有** `docs/` 目录，文档统一在 `_packed_docs/`；入口索引为 `INDEX.md` |
 
 ## 路径实例文件
 
 `$ECK/path-registry.md` 和 `$ECK/runtime.md` 由 `src/eck/init.ts` **写一次就不再更新**
 （`if (fs.existsSync(file)) return`），且只渲染 `EVOLCORE_HOME` / `PACKAGE_ROOT` 两个变量——
 其余 `{{...}}` 占位符原样留在文件里；源码也**没有任何地方读回它们**。
-不要把它们当作真实路径的依据，按本文件的派生规则自己算，或直接读 `src/paths.ts`。
+不要把它们当作真实路径的依据，按本文件的派生规则自己算，或直接读 `src/paths.ts`。

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

@@ -62,7 +62,7 @@
 
 |  | 系统提示词渲染层 | 消息渲染层 |
 |--|--|--|
-| **驱动文件** | `kits/eck_manifest.json`（默认；按 `session.sessionType` 经 config.sessionManifests 可切到 `eck_manifest.<type>.json`，如 auxiliary） | `kits/eck_message_manifest.json` |
+| **驱动文件** | `kits/eck_manifest.json`（默认；按 `session.sessionType` 经内置映射切到 `eck_manifest.<type>.json`，如 memory / auxiliary；config.sessionManifests 可覆盖） | `kits/eck_message_manifest.json` |
 | **覆盖文件** | `$EVOLCORE_HOME/eck/<驱动文件名>` | `$EVOLCORE_HOME/eck/eck_message_manifest.json` |
 | **模板目录** | `kits/templates/system-fragments/` | `kits/templates/message-fragments/` |
 | **输出去向** | `systemPrompt.append`（每轮覆盖，不进 transcript） | `effectivePrompt`（进 transcript，成永久历史） |
@@ -104,9 +104,11 @@
 | 20 | identity-layer | chatType≠null | ✓ | 身份层 fragment |
 | 21 | persona | chatType≠null | ✗ | `$PERSONAL_DIR/persona.md` |
 | 21.5 | personal-profile | chatType≠null | ✗ | `$PERSONAL_DIR/personal.md` |
-| 22 | working-memory | chatType≠null | ✗ | `$PERSONAL_DIR/memory/working.md` |
 | 30 | relation-layer | chatType∈{private,group} | ✓ | 关系层 fragment |
-| 35 | peer-profile | peerKey≠null | ✗ | 对端 profile.md |
+| 35 | memory | memoryEnableRelation≠false | ✓ | 记忆系统 fragment（按 sessionType 分支） |
+| 36 | agent-memory | memoryEnableAgent≠false | ✗ | `$PERSONAL_DIR/memory/MEMORY.md` |
+| 37 | owner-memory | ownerAid≠null | ✗ | `$EVOLCORE_HOME/memory/owner/{{ownerAid}}/MEMORY.md` |
+| 38 | relation-memory | peerKey≠null | ✗ | `$RELATIONS_DIR/{{peerKey}}/memory/MEMORY.md` |
 | 40 | venue-fragment | chatType≠null | ✓ | 环境层 fragment |
 | 41 | venue-chattype | chatType≠null | ✗ | `venues/{{chatType}}.md` |
 | 42 | venue-channel-chattype | chatType≠null | ✗ | `venues/{{channel}}-{{chatType}}.md` |

package/kits/docs/venues/group.md

@@ -5,6 +5,7 @@
 ## 行为准则
 - `mentionMode: mention-only` — 仅响应明确 @ 自己的消息
 - `mentionMode: disabled` — 所有消息可见，自主判断是否参与。这不是叫你每条都回，而是你可以像真人一样：感兴趣的接话，不感兴趣的就跳过。回得短一点、快一点，让对话流动起来，不要一个人长篇大论堵住别人的空间
+- `mentionMode: auto` — 普通群消息先由轻量分类器判定是否唤醒主会话；明确 @ 直接进入主会话，未 @ 的 slash 被过滤
 - 查看关系档案（peer-profile）了解本群文化与策略
 - 如果上下文中出现“群规则”，它来自当前群资源空间的本地同步缓存；群规则优先于通用群聊指引
 - 群发言会被多人看到，谨言慎行
@@ -13,7 +14,7 @@
 ## 群聊 slash 命令
 
 群内仅保留 `/help`、`/evolhelp`、`/status`、`/check`、`/ask`、`/pause`、`/resume`、`/stop`、
-`/compact`、`/renew`，以及只读的 `/mentionmode`、`/model`、`/effort`、`/perm`、`/baseagent`。
+`/compact`、`/renew`，以及只读的 `/mention`、`/model`、`/effort`、`/perm`、`/baseagent`。
 `/model current|list|check` 也是查询；切换、重置、审批等带参写操作在群内不支持。
 `/compact`、话题内的 `/renew` 仍受原有角色与会话状态限制。别名遵循主命令策略。
 `/chatmode`、`/activity` 和其他 slash 命令在群内不支持，请通过私聊或有权限的管理入口操作。
@@ -24,9 +25,9 @@ AUN 群聊的命令查询、成功与进度反馈使用 `notice`，命令拒绝
 
 ## 可按需查询的群数据
 
-AUN 的提及模式会保留未被 @ 的会话消息。需要补充背景时使用
-`ec group history <self-aid> <group-id> --unread --format json`；
-查询与自动记录已读遵循专用 `group-unread-history` 片段及群命令文档。
+AUN 群的本地会话历史可供人工回看。需要补充背景时使用
+`ec group history <self-aid> <group-id> --limit 50 --format json`；
+查询只读，可用 `--thread`、`--before`、`--after` 和 `--direction` 缩小范围。
 历史读取不会触发对其中每一条消息的回复。
 
 群结构信息（成员名单、各成员角色、群主、管理员、在线状态等）**不预先注入上下文**，