evolcore 0.0.1 → 0.0.2

package/kits/docs/evolcore/config.md

@@ -0,0 +1,149 @@
+# ec config — 配置体系底层入口
+
+按作用域读写所有配置参数 + 配置快照/回滚/启动历史。触发词：看配置/改配置/查字段/列配置/校验配置/快照/回滚/历史/对比版本/启动记录。
+
+> `ec config` 是配置读写的统一 CLI 入口；模型交互由 menu 协议和 slash `/model` 提供。
+> 字段按 owner 路由：H 字段写 daemon/defaults/config，HA 行为字段写行为配置。
+
+## 参数读写
+
+```bash
+# 读 effective 值（显示覆盖链来源）；可一次传多个字段批量读取（共享同一 selector/--format）
+ec config get <field> [<field> ...] [--self <aid>] [--peer <X>] [--default] [--process]
+#   单字段输出不变；多字段时 text 每行一条、json 返回 { ok, results: [...] }，任一字段失败退出码为 1
+
+# 写参数：scope 由 selector 推断
+ec config set <field> <value> [--self <aid>] [--peer <X>] [--default] [--process]
+
+# 删除某层显式设置，回落下一层
+ec config unset <field> [--self <aid>] [--peer <X>]
+
+# 查看某一层文件原始内容（不合并，凭证显示 ${VAR} 不展开）
+ec config show [--self <aid>] [--peer <X>] [--default] [--process]
+
+# 打印合并后的全部生效配置
+ec config effective [--self <aid>] [--peer <X>]
+
+# 列出某作用域可设字段（类型/枚举值，来源 schema）
+ec config fields [--self <aid>] [--default] [--process]
+
+# 列出所有配置文件
+ec config list
+
+# 按 schema 校验配置文件
+ec config validate [--self <aid>] [--peer <X>] [--default] [--process]
+
+# 按 schema 物化骨架文件（仅人）
+ec config init [--self <aid>] [--peer <X>] [--default] [--process]
+```
+
+## 快照 / 回滚
+
+总开关直接保存在 `$EVOLCORE_HOME/daemon.json` 顶层，默认 `true`：
+
+```bash
+ec config set configSnapshots true --process
+ec config set configSnapshots false --process
+```
+
+开启时首次成功启动创建全量基线，后续成功启动检测到配置变化后自动建立新版本。关闭时不写快照、启动日志，也不执行自检回落。
+
+```bash
+# 立即创建快照（与当前版本比对，不一致才建；--full 强制新全量）（仅人）
+ec config snapshot [--full] [--desc "说明"]
+
+# 列出快照版本（版本号/类型/触发/时间/说明）
+ec config history
+
+# 对比两版本差异
+ec config diff <v1> <v2>
+
+# 恢复到指定版本：展开到工作目录 + 更新 current.json（先 pre-restore 快照）（仅人）
+ec config restore <version>
+
+# 显示 current.json 选定版本（上次启动回落时给出告警）
+ec config current
+
+# 查看启动历史（含回落标记）
+ec config boots [-n N]
+
+# 清理旧快照（默认 dry-run，--yes 真删；拒删被依赖全量 / current 指向版本）（仅人）
+ec config prune [--keep-full N] [--keep-delta N] [--yes]
+```
+
+## Schema 查看
+
+查看随包分发的配置 schema **定义本身**（`kits/schemas/*.schema.*.json`）——不是读写配置值，而是查「某作用域有哪些字段、类型/枚举/默认、schema 有几个版本」。纯只读，人和 agent 均可。
+
+```bash
+# 概览：列出全部逻辑 schema 及各自当前版本
+ec config schema
+
+# 列出某 schema 磁盘上的所有版本（* 标当前版本，附日期/说明）
+ec config schema <name> --list
+
+# 查看某 schema 的原始定义（缺省版本号 = 当前版本）
+ec config schema <name> [version]
+```
+
+逻辑 schema 名（`<name>`）：`daemon` / `defaults` / `agent-config` / `relation-config` /
+`contact-book` / `role-registry` / `role-config`。
+
+三种输出模式：
+
+| 调用形式 | mode | 输出 |
+|----------|------|------|
+| `config schema` | overview | 全部 schema + 各自当前版本号 |
+| `config schema <name> --list` | versions | 该 schema 所有磁盘版本，`*` 标当前，附 date/description |
+| `config schema <name> [version]` | content | 指定版本（缺省=当前）的完整 schema JSON |
+
+约定与报错：
+- `--list` 与 version 参数互斥（`INVALID_CONFIG_COMMAND`）
+- `--list` 或指定 version 时必须带 `<name>`（`MISSING_ARG`）
+- version 须为非负整数；未知 name → `UNKNOWN_SCHEMA`；版本不存在 → `SCHEMA_VERSION_NOT_FOUND`（错误信息列出可用版本）
+
+> 用途：写配置前先 `ec config fields` 看字段可设值，或 `ec config schema <name>` 看该层 schema 的完整字段约束与 `x-merge` 合并语义；排查「字段为何被拒/怎么合并」时定位 schema 版本。
+
+## 作用域 selector
+
+| 参数 | 作用域 | 落盘 |
+|------|--------|------|
+| `--self <aid>` | agent 级 | `agents/<aid>/config.json` |
+| `--self <aid> --peer <X>` | 关系级 | `agents/<aid>/relations/<peerKey>/config.json` |
+| `--default` | 全局默认 | `agents/defaults.json` |
+| `--process` | 进程级 | `~/.evolcore/daemon.json` |
+| 写操作三者全无 | — | **拒绝**（防误写全局） |
+
+`--peer` 取 `channelType#channelId` 或裸 aid（裸 aid 视为 `aun#<aid>`）。改某作用域后，对应范围所有会话的下一条消息即时生效。
+
+## 覆盖链
+
+```
+defaults → agent/config → relation/config
+```
+
+ConfigManager 只合并上述物理层并返回物理来源。角色策略不进入配置合并链：`permissionMode` 和 `baseagents.*.model` 由消费方按当前角色单独应用。
+
+## 权限控制
+
+**写权限**（API 层判定）：
+- **通用可写字段**：active_baseagent / baseagents / chatmode / show_activities / flush_delay / debounce / render
+- **角色专用入口**：`roles/index.json` 与 `roles/{roleId}.json` 由角色服务维护；relation 的
+  `role` 由角色分配服务维护；`permissionMode` 仅在角色策略中维护
+- **兼容字段**：`enable_rich_content` 仍可读取旧值，但已废弃且不再产生运行时效果
+- **仅人可写**：channels / owners / admins / 凭证 / aid / enabled / projects / aun / models.allowed
+- Agent 托管环境写仅人字段被拒
+
+**操作权限**：
+- 读操作（get/show/list/effective/fields/schema/history/diff/current/boots/validate）：人和 agent 均可
+- 快照管理（snapshot/restore/init/prune）：仅人可执行
+
+**凭证安全**：
+- 凭证一律 `${VAR}` 引用，CLI 读命令永不展开、不泄露明文
+- `.env` 全程禁读写
+
+## 通用约定
+
+- `--format json` — 所有子命令通用
+- 本命令操作本地配置，不连 AUN 网络
+- 单文件内 list 字段 `set` = 追加去重；删单个元素请直接编辑文件（角色/owner 链只增不减）

package/kits/docs/evolcore/ctl.md

@@ -0,0 +1,46 @@
+# ec ctl — 当前会话工具
+
+在**当前托管会话**中发送消息或文件、重命名、管理队列，以及查询项目路径和会话状态。
+
+> ctl 命令通过 IPC 转发给 daemon，仅在 evolcore 托管环境中可用（依赖 `EVOLCORE_SESSION_ID`）。
+
+## 查询
+
+```bash
+ec ctl status        # 查看会话状态
+ec ctl pwd           # 显示当前项目路径
+ec ctl help          # 显示帮助
+```
+
+## 会话名称
+
+```bash
+ec ctl name <新名称>
+```
+
+## 消息（兜底用）
+
+```bash
+ec ctl send "<text>"      # 主动发送文本（proactive 模式）
+ec ctl file [channel] <path>   # 发送项目内文件
+```
+
+> 发消息**首选 `ec msg send <self-aid> <peer-id> "<text>"`**（见 msg.md）。
+> `ec ctl send` 只在拿不到自己的 AID 时兜底——它自动继承当前会话的 AID 和对端。
+
+## 消息队列
+
+```bash
+ec ctl queue               # 查看当前会话队列
+ec ctl queue --full        # 显示完整预览
+ec ctl queue --clear       # 清空待处理消息
+ec ctl queue --cancel <id> # 取消指定消息
+ec ctl queue --interrupt   # 打断当前处理
+```
+
+## 相关命令集
+
+- agent 全生命周期管理（创建/启停/配置）→ `ec agent`（见 agent.md）
+- AID 身份与 agent.md 名片 → `ec aid`（见 aid.md）
+- 定时与事件触发器 → `ec trigger`（见 trigger.md）
+- 模型查看与切换通过 menu 协议或 slash `/model` 完成

package/kits/docs/evolcore/event.md

@@ -0,0 +1,216 @@
+# Trigger Event Catalog
+
+本目录用于编写 `source.type = "event"` 的 trigger 时按需查阅。最终事实源是
+`$PACKAGE_ROOT/src/core/event-bus.ts` 的 `GatewayEvent` 类型；本文只做面向 trigger
+作者的事件索引和使用约定。
+
+## Event Source 规则
+
+`source.eventPattern` 支持三种形式：
+
+| 形式 | 示例 | 含义 |
+|------|------|------|
+| 精确事件名 | `message:received` | 只监听这一种事件 |
+| 命名空间前缀 | `task:*` | 监听该命名空间下所有事件 |
+| 全量 | `*` | 监听所有 EventBus 事件，需谨慎使用 filter |
+
+`source.filter.match` 用事件 payload 的字段路径做匹配，支持：
+
+| 操作 | 示例 |
+|------|------|
+| 等值 | `{ "channel": "feishu" }` |
+| `$in` | `{ "toolName": { "$in": ["Bash", "Edit"] } }` |
+| `$regex` | `{ "content": { "$regex": "^/echo" } }` |
+| 数值比较 | `{ "durationMs": { "$gte": 30000 } }` |
+| 存在性 | `{ "userId": { "$exists": true } }` |
+
+字段路径支持点号，例如 `replyContext.threadId`。禁止使用 `__proto__`、`prototype`、
+`constructor` 路径段。
+
+## 循环防护
+
+监听 `trigger:*` 时，系统默认禁止 trigger 响应自身产生的 trigger 事件：
+当事件带有 `originTriggerId` 且等于当前 trigger id 时，该事件会被跳过。
+
+跨 trigger 的链式触发仍然允许。需要追踪链路时使用：
+
+| 字段 | 含义 |
+|------|------|
+| `runId` | 本次 trigger run 的唯一 ID |
+| `originTriggerId` | 产生当前 `trigger:*` 事件的 trigger id |
+
+## 常用事件
+
+| 事件 | 常见用途 |
+|------|----------|
+| `message:received` | 用户消息触发自动化 |
+| `task:completed` | agent 完成回复后触发后处理 |
+| `task:error` | agent 任务失败后触发诊断或告警 |
+| `permission:requested` | 观察权限请求 |
+| `permission:cancelled` | 权限请求因中断等原因被取消 |
+| `runner:model-changed` | 模型或推理强度变化后同步状态 |
+| `agent:*` | agent 生命周期、配置变化、运行态变化 |
+| `trigger:*` | trigger 编排、链式触发、审计 |
+
+## 事件目录
+
+### system
+
+| 事件 | Payload |
+|------|---------|
+| `system:started` | `{ channels, timestamp }` |
+| `system:shutdown` | `{ reason?, timestamp? }` |
+| `system:restart` | `{ channel, channelId }` |
+
+### channel
+
+| 事件 | Payload |
+|------|---------|
+| `channel:connected` | `{ channel, channelName?, timestamp? }` |
+| `channel:disconnected` | `{ channel, channelName?, reason? }` |
+| `channel:error` | `{ channel, channelName?, status, message, timestamp? }` |
+| `channel:owner-bound` | `{ channel, channelName?, userId }` |
+
+### session
+
+| 事件 | Payload |
+|------|---------|
+| `session:created` | `{ sessionId, channel, channelName?, channelId, projectPath?, name?, chatType?, threadId?, timestamp? }` |
+| `session:switched` | `{ sessionId, fromSessionId, toSessionId }` |
+| `session:deleted` | `{ sessionId }` |
+| `session:renamed` | `{ sessionId, oldName, newName }` |
+| `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? }` |
+
+### message
+
+| 事件 | Payload |
+|------|---------|
+| `message:received` | `{ sessionId, channel, channelName?, channelId, content, userId?, agentName?, timestamp? }` |
+| `message:text` | `{ sessionId, text, isFinal }` |
+| `message:thought-put` | `{ agentName, channelId, taskId?, text? }` |
+
+### task
+
+| 事件 | Payload |
+|------|---------|
+| `task:started` | `{ sessionId, agentName?, encrypt?, chatmode? }` |
+| `task:queued` | `{ channel, channelId, replyContext? }` |
+| `task:completed` | `{ sessionId, channel, channelName?, channelId, finalText?, durationMs?, terminalReason?, agentName?, numTurns?, timestamp? }` |
+| `task:error` | `{ sessionId, error, errorType, terminalReason?, agentName? }` |
+| `task:interrupted` | `{ sessionId, reason?, agentName? }` |
+
+### tool
+
+| 事件 | Payload |
+|------|---------|
+| `tool:use` | `{ sessionId, toolName, input, timestamp? }` |
+| `tool:result` | `{ sessionId, toolName, isError?, agentName?, timestamp? }` |
+
+### permission
+
+| 事件 | Payload |
+|------|---------|
+| `permission:requested` | `{ sessionId, requestId, toolName, input }` |
+| `permission:resolved` | `{ sessionId, requestId, approved }` |
+| `permission:cancelled` | `{ sessionId, requestId, toolName?, reason? }` |
+
+### runner
+
+| 事件 | Payload |
+|------|---------|
+| `runner:compact-start` | `{ sessionId }` |
+| `runner:compact-complete` | `{ sessionId, preTokens }` |
+| `runner:model-changed` | `{ sessionId?, agentName?, baseagent?, model?, effort?, timestamp? }` |
+| `runner:idle-timeout` | `{ sessionId, idleSec }` |
+| `runner:idle-notify` | `{ sessionId, idleSec, totalEvents, totalToolCalls, lastToolName? }` |
+| `runner:idle-warn` | `{ sessionId, idleSec, totalEvents, totalToolCalls, lastToolName? }` |
+| `runner:file-sent` | `{ sessionId, filePath, channel, channelName? }` |
+| `runner:state-changed` | `{ sessionId, state }` |
+| `runner:status` | `{ sessionId, subtype, message, timestamp? }` |
+
+### self-heal
+
+| 事件 | Payload |
+|------|---------|
+| `self-heal:started` | `{ reason }` |
+| `self-heal:attempt` | `{ attemptNumber, maxAttempts }` |
+| `self-heal:completed` | `{ success, attempts }` |
+
+### trigger
+
+| 事件 | Payload |
+|------|---------|
+| `trigger:registered` | `{ triggerId, name, peerId?, targetChannel?, targetChannelId?, scheduleType, scheduleValue, timestamp? }` |
+| `trigger:updated` | `{ triggerId, name, peerId?, scheduleType, scheduleValue, timestamp? }` |
+| `trigger:fired` | `{ triggerId, name, runId, originTriggerId, fireTime, targetChannel?, targetChannelId?, scheduleType, timestamp? }` |
+| `trigger:completed` | `{ triggerId, name, runId, originTriggerId, messageId, durationMs, targetChannel, targetChannelId, fireTime }` |
+| `trigger:failed` | `{ triggerId, name, runId, originTriggerId, messageId, error, targetChannel, targetChannelId, fireTime, phase }` |
+| `trigger:skipped` | `{ triggerId, name, runId, originTriggerId, reason, targetChannel, targetChannelId, fireTime? }` |
+| `trigger:cancelled` | `{ triggerId, name, by }` |
+
+### agent
+
+| 事件 | Payload |
+|------|---------|
+| `agent:created` | `{ aid, name?, baseagent?, projectPath?, owner?, timestamp? }` |
+| `agent:updated` | `{ aid, timestamp? }` |
+| `agent:reloaded` | `{ aid, timestamp? }` |
+| `agent:enabled` | `{ aid, reloaded?, timestamp? }` |
+| `agent:disabled` | `{ aid, reloaded?, timestamp? }` |
+| `agent:deleted` | `{ aid, purged?, timestamp? }` |
+| `agent:started` | `{ aid, timestamp? }` |
+| `agent:stopped` | `{ aid, timestamp? }` |
+| `agent:error` | `{ aid, action?, error, timestamp? }` |
+| `agent:baseagent-changed` | `{ aid, baseagent, previousBaseagent?, scope, timestamp? }` |
+
+## 示例
+
+监听飞书用户消息：
+
+```json
+{
+  "source": {
+    "type": "event",
+    "eventPattern": "message:received",
+    "filter": {
+      "match": {
+        "channel": "feishu",
+        "content": { "$regex": "^/echo" }
+      }
+    }
+  }
+}
+```
+
+监听非自身产生的 trigger 完成事件：
+
+```json
+{
+  "source": {
+    "type": "event",
+    "eventPattern": "trigger:completed",
+    "filter": {
+      "match": {
+        "targetChannel": { "$exists": true }
+      }
+    }
+  }
+}
+```
+
+## 不存在或已移除的事件
+
+不要使用这些历史设计稿中出现过的事件：
+
+| 事件 | 替代 |
+|------|------|
+| `message:sent-out` | 使用 `task:completed` |
+| `permission:timeout` | 当前权限不会 timeout；取消用 `permission:cancelled` |
+| `session:safe-mode-entered` / `session:safe-mode-exited` | 已移除 |
+| `project:switched` / `project:bound` | 已移除 |
+| `config:corrupted` | 已移除 |
+| `agent:create-failed` | 使用 `agent:error` 且 `action = "create"` |