evolcore 0.0.2 → 0.0.4

package/kits/docs/evolcore/trigger.md

@@ -34,6 +34,16 @@ ec trigger history [triggerId] --limit 500 --json
 
 ## 创建
 
+创建操作统一使用 `create`：
+
+| 入口 | 正式命令 | 兼容别名 |
+| --- | --- | --- |
+| CLI | `ec trigger create ...` | `ec trigger set ...` |
+| Slash | `/trigger create ...` | `/trigger set ...` |
+| Menu Protocol | `menu.action name=trigger action=create` | `action=set` |
+
+新调用只使用 `create`；`set` 仅用于兼容旧脚本和旧客户端。三种入口最终都映射到内部操作 `trigger.create`。
+
 Flag 模式适合 agent 现场创建常规 trigger：
 
 ```bash
@@ -48,7 +58,23 @@ ec trigger create \
   --enable
 ```
 
-CLI flag 模式必须显式指定 `--target-channel` 和 `--target-channel-id`，并生成 `feedback.strategy=target`。需要 `origin` 或 `silent` feedback 时，用 `/trigger` 或 `--file` 导入 Trigger V3 第二阶段 JSON。
+CLI flag 模式必须显式指定 `--exec`、`--target-channel` 和 `--target-channel-id`，并生成 `feedback.strategy=target`。需要 `origin` 或 `silent` feedback 时，用 `/trigger` 或 `--exec <type> --file <trigger.json|trigger-dir>` 导入 Trigger V3 第二阶段 JSON；CLI 会校验 `--exec` 与 JSON 的 `execution.type` 一致。
+
+多行或复杂 prompt 使用 `--prompt-file <path>`，文件内容会原样作为 prompt（UTF-8 BOM 会移除）。内联 `--prompt` 最多 4096 个字符；超限时 CLI 会提示改用 `--prompt-file <path>`：
+
+```bash
+ec trigger create --cron '0 9 * * *' \
+  --exec target-session \
+  --prompt-file ./prompts/daily-summary.md \
+  --target-channel <channelKey> --target-channel-id <channelId> \
+  --name daily-summary --enable
+
+ec trigger update <triggerId> --prompt-file ./prompts/daily-summary-v2.md
+```
+
+`--file` 始终表示导入完整的 `trigger.json` 或 trigger 目录；`--prompt-file` 只表示 prompt 正文。所有 `create` 形式都必须显式指定 `--exec`；`--prompt-file` 与 `--prompt` 互斥，且不能和 `--file` 同时使用。
+
+模型通过 Bash 调用 CLI 且用双引号传递 `--prompt` 时，正文中的双引号、反引号和 Shell 变量形式的 `$` 需要分别写成 `\"`、反斜杠+反引号、`\$`。Shell 会在启动 `ec` 时去掉保护反斜杠，Trigger 中保存的仍是原始正文。
 
 支持的触发来源：
 
@@ -75,9 +101,9 @@ Trigger V3 第二阶段使用 `execution.type` 区分执行位置：
 --exec target-session
 ```
 
-`target-session` 是默认值：把 `--prompt` 当作一条 trigger 来源消息投递进目标会话队列，并等待该会话处理完成。
+`target-session` 把 `--prompt` 或 `--prompt-file` 的内容当作一条 trigger 来源消息投递进目标会话队列，并等待该会话处理完成。创建时必须显式指定 `--exec target-session`，不会再隐式选择该类型。
 
-`trigger-session` 在 daemon 内部 trigger 会话执行 prompt，再把最终结果按 feedback 投递：
+`trigger-session` 在 daemon 内部 trigger 会话执行 prompt，再把最终结果按 feedback 投递；prompt 可来自 `--prompt` 或 `--prompt-file`：
 
 ```bash
 --exec trigger-session \
@@ -97,7 +123,7 @@ Trigger V3 第二阶段使用 `execution.type` 区分执行位置：
 --script-args '{"scope":"daily"}'
 ```
 
-`script` 不使用 `--prompt`。脚本路径必须在 trigger 目录内；通过 `--file` 导入目录时，脚本文件会随 definition 一起上传。
+`script` 不使用 `--prompt` 或 `--prompt-file`；它必须使用 `--script-path` 和 `--script-runtime`。脚本路径必须在 trigger 目录内；通过 `--file` 导入目录时，脚本文件会随 definition 一起上传。已有 script trigger 的 `update --prompt-file` 也会被拒绝。
 
 ## 目标与反馈
 
@@ -147,9 +173,12 @@ script trigger 返回 `[[NOOP]]` 或 `outcome: "noop"` 时走 noop 分支；默
 ```bash
 --model <模型>
 --effort <low|medium|high|xhigh|max>
+--baseagent <claude|codex|gemini>
 ```
 
-`--model` / `--effort` 只覆盖本 trigger 执行时传给 base agent 的模型与推理强度。baseagent 不在 trigger 中指定，始终沿用该 trigger 所属 agent 当前 active baseagent；未设置时继承当前关系级 / agent 级 / 全局模型配置。
+`--model` / `--effort` 只覆盖本 trigger 执行时传给 base agent 的模型与推理强度。
+`--baseagent` 仅支持 `--exec trigger-session`，用于给该 trigger 会话单独选择 base agent；
+`script` 和 `target-session` 不接受该参数。未设置时沿用 trigger 所属 agent 当前 active baseagent。
 
 无人值守 trigger 不适合 `request`。需要写文件、git、安装升级、重启服务、管理 trigger 时应显式使用：
 
@@ -157,7 +186,7 @@ script trigger 返回 `[[NOOP]]` 或 `outcome: "noop"` 时走 noop 分支；默
 --permission bypass
 ```
 
-owner/admin 通过 `/trigger set` 创建时默认使用 `bypass`；非 admin 默认 `readonly`，不能提权到 `bypass`，也不能跨渠道或跨会话指定 target。
+owner/admin 通过 `/trigger create` 创建时默认使用 `bypass`；非 admin 默认 `readonly`，不能提权到 `bypass`，也不能跨渠道或跨会话指定 target。历史 `/trigger set` 仍是兼容别名。
 
 ## 执行边界
 
@@ -177,6 +206,8 @@ ec trigger enable <triggerId>
 ec trigger disable <triggerId>
 ec trigger cancel <triggerId>   # disable 的兼容别名
 ec trigger delete <triggerId>
+ec trigger remove <triggerId>   # delete 的兼容别名
+ec trigger rm <triggerId>       # delete 的兼容别名
 ```
 
 语义区别：
@@ -190,18 +221,19 @@ ec trigger delete <triggerId>
 
 ## 局部更新
 
-`update` 是 patch 语义，只提交需要修改的字段；未指定字段（包括长 prompt）保持不变。不接受 `--file` 或完整 definition：
+`update` 是 patch 语义，只提交需要修改的字段；未指定字段（包括长 prompt）保持不变。`--prompt-file <path>` 只更新非 script trigger 的 prompt，不接受完整 definition：
 
 ```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> --cron '0 10 * * *' --if-revision 'sha256:...'
 ```
 
 可更新参数只保留三组常用字段：
 
 - 调度：`--once`、`--delay`、`--at`、`--cron`、`--every`、`--event`、`--tz`
-- 内容：`--prompt`、`--name`
+- 内容：`--prompt` 或 `--prompt-file <path>`、`--name`
 - 执行配置：`--model`、`--effort`、`--permission`
 - 运行边界：`--max-runs`、`--max-duration`、`--concurrency`、`--missed-policy`
 
@@ -242,8 +274,8 @@ logs/trigger-runs.log
 复杂 trigger 使用 Trigger V3 第二阶段 JSON：
 
 ```bash
-ec trigger create --file ./trigger.json --enable
-ec trigger create --file ./trigger-dir --enable
+ec trigger create --exec target-session --file ./trigger.json --enable
+ec trigger create --exec script --file ./trigger-dir --enable
 ```
 
 当前产品版本是 Trigger V3 第二阶段；其持久化定义版本为 `$schema_version: 3.1`。旧 `$schema_version: 4` 文件加载时会自动规范化为 `3.1`。

package/kits/docs/path-registry.md

@@ -1,16 +1,21 @@
 # 路径定义
 
-本文件定义所有预定义路径的含义和派生规则。运行时实际值在 `$ECK/path-registry.md`。
+本文件定义所有预定义路径的含义和派生规则。真相源是 `src/paths.ts`（基础/派生路径）
+和 `src/eck/manifest-engine.ts` 的 `buildPathMappings`（ECK 认识哪些别名）。
 
 ## 基础路径（三个锚点）
 
 | 名称 | 含义 | 来源 |
 |------|------|------|
-| `$EVOLCORE_HOME` | evolcore 用户数据根 | 环境变量 `EVOLCORE_HOME` 或默认 `~/.evolcore` |
-| `$PACKAGE_ROOT` | evolcore 包根目录 | `require.resolve('evolcore')` 所在目录 |
-| `$CURRENT_PROJECT` | 当前工作目录 | `process.cwd()` |
+| `$EVOLCORE_HOME` | evolcore 用户数据根 | `resolveRoot()`：环境变量 `EVOLCORE_HOME` → cwd 下有 `agents/defaults.json` 则取 cwd → `~/.evolcore` |
+| `$PACKAGE_ROOT` | evolcore 包根目录 | `getPackageRoot()`，由 `import.meta` 推出（不是 `require.resolve`） |
+| `$CURRENT_PROJECT` | 当前工作目录 | 会话的 projectPath |
 
-## 包内路径（从 $PACKAGE_ROOT 派生）
+> dev 模式下 `$EVOLCORE_HOME` 和 `$PACKAGE_ROOT` 可能是**同一个目录**（本机就是 `/home/evolcore`）。
+
+## ECK 能解析的别名
+
+只有下面这些能出现在 manifest 的 `path` 字段里；其它写法会被判为未解析变量、整段静默丢弃。
 
 | 名称 | 派生规则 | 说明 |
 |------|----------|------|
@@ -18,26 +23,40 @@
 | `$KITS_RULES` | `$KITS/rules` | 自动加载的规则文件 |
 | `$KITS_DOCS` | `$KITS/docs` | 按需加载的文档 |
 | `$KITS_TEMPLATES` | `$KITS/templates` | 运行时 prompt 组装模板 |
-
-## 用户数据路径（从 $EVOLCORE_HOME 派生）
-
-| 名称 | 派生规则 | 说明 |
+| `$KITS_FRAGMENTS` | `$KITS_TEMPLATES/system-fragments` | system prompt fragment 模板 |
+| `$KITS_MESSAGE_FRAGMENTS` | `$KITS_TEMPLATES/message-fragments` | 逐条消息渲染的 fragment 模板 |
+| `$AGENT_DIR` | `$EVOLCORE_HOME/agents/<selfAid>` | 当前 agent 数据目录 |
+| `$PERSONAL_DIR` | `$AGENT_DIR/personal` | 身份层个人数据（旧名 `$SELF_DIR` 已废弃） |
+| `$RELATIONS_DIR` | `$AGENT_DIR/relations` | 对端关系数据（含具体群/私聊实例数据） |
+| `$VENUES_DIR` | `$AGENT_DIR/venues` | 环境层；**当前是死目录**，`agentVenuesDir()` 零调用点 |
+| `$CURRENT_PROJECT` | 会话 projectPath | — |
+| `$EVOLCORE_HOME` | 见上 | — |
+| `$PACKAGE_ROOT` | 见上 | — |
+
+`selfAid` 为空时（本地 coding 会话），`$AGENT_DIR` / `$PERSONAL_DIR` / `$RELATIONS_DIR` /
+`$VENUES_DIR` 这四个别名**不会注册**。
+
+## 仅文档书写约定（ECK 不解析）
+
+| 名称 | 实际位置 | 说明 |
 |------|----------|------|
-| `$ECK` | `$EVOLCORE_HOME/eck` | ECK 实例数据（路径注册表实例等） |
+| `$ECK` | `$EVOLCORE_HOME/eck` | ECK 实例数据，见下节告警 |
 | `$AGENTS_DIR` | `$EVOLCORE_HOME/agents` | 所有 agent 数据根 |
-| `$AGENT_DIR` | `$AGENTS_DIR/<self-aid>` | 当前 agent 数据目录 |
-| `$SELF_DIR` | `$AGENT_DIR/personal` | 自己的身份档案 |
-| `$RELATIONS_DIR` | `$AGENT_DIR/relations` | 对端关系档案（含具体群/私聊实例数据） |
-| `$VENUES_DIR` | `$AGENT_DIR/venues` | 环境层（预留，更高抽象，非实例） |
 | `$AGENT_INDEX` | `$AGENT_DIR/index` | agent 级索引 |
+| `$PEER_DIR` | `$RELATIONS_DIR/<peerKey>` | 当前对端的关系目录 |
 
 ## 外部依赖路径（需寻找）
 
 | 名称 | 寻找规则 | 说明 |
 |------|----------|------|
-| `$KITE` | 在 `$EVOLCORE_HOME/config.json` 的 `kitePath` 字段查找 | Kite 框架根 |
-| `$AUN_SDK_CORE` | `$KITE/aun-sdk-core` | AUN SDK 源码 |
+| `$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 源码路径）已废弃，不再有对应实现。
 
 ## 路径实例文件
 
-运行时实际路径值写入 `$ECK/path-registry.md`，格式见 `$KITS_DOCS/eck_templates/path-registry.template.md`。
+`$ECK/path-registry.md` 和 `$ECK/runtime.md` 由 `src/eck/init.ts` **写一次就不再更新**
+（`if (fs.existsSync(file)) return`），且只渲染 `EVOLCORE_HOME` / `PACKAGE_ROOT` 两个变量——
+其余 `{{...}}` 占位符原样留在文件里；源码也**没有任何地方读回它们**。
+不要把它们当作真实路径的依据，按本文件的派生规则自己算，或直接读 `src/paths.ts`。

package/kits/eck_manifest.json

@@ -55,6 +55,18 @@
       ] },
       "description": "当前关注（working memory）"
     },
+    {
+      "id": "preferences",
+      "type": "file",
+      "file": "$PERSONAL_DIR/preferences/active-preferences.md",
+      "order": 23,
+      "needsInjection": false,
+      "when": { "and": [
+        { "var": "chatType", "eq": "private" },
+        { "var": "lifecycle", "neq": "bootstrapping" }
+      ] },
+      "description": "用户偏好（自动记忆，仅私聊注入）"
+    },
     {
       "id": "relation-layer",
       "type": "file",

package/kits/eck_message_manifest.json

@@ -21,9 +21,20 @@
       "needsInjection": true,
       "modeType": "handoff",
       "modeName": "request_to_target",
-      "when": { "and": [ { "var": "isHandoff", "eq": true }, { "var": "handoffKind", "eq": "request_to_target" } ] },
+      "when": { "and": [ { "var": "isHandoff", "eq": true }, { "var": "handoffKind", "eq": "request_to_target" }, { "var": "handoffReturnPolicy", "eq": "required" } ] },
       "description": "msg send 跨会话请求回复上下文渲染"
     },
+    {
+      "id": "msg-handoff-context-to-target",
+      "type": "file",
+      "file": "$KITS_MESSAGE_FRAGMENTS/handoff-context-to-target.md",
+      "order": 6,
+      "needsInjection": true,
+      "modeType": "handoff",
+      "modeName": "request_to_target",
+      "when": { "and": [ { "var": "isHandoff", "eq": true }, { "var": "handoffKind", "eq": "request_to_target" }, { "var": "handoffReturnPolicy", "eq": "none" } ] },
+      "description": "msg send 跨会话单次本地上下文渲染"
+    },
     {
       "id": "msg-handoff-response-to-origin",
       "type": "file",