evolcore 0.0.1 → 0.0.3

package/kits/docs/evolcore/trigger.md

@@ -0,0 +1,539 @@
+# ec trigger - 定时与事件触发器
+
+创建、查看、启停、删除和手动运行本机 daemon 管理的 trigger。触发词：触发器/定时任务/cron/提醒/定时检查/自动执行/巡检/禁用 trigger/删除 trigger。
+
+> `ec trigger` 通过 daemon IPC 直接操作 TriggerRuntimeScheduler。agent 会话内省略 `--agent` 时，CLI 使用当前任务上下文里的 agent AID；只有跨身份操作或脱离 agent 会话执行时才需要显式传 `--agent <aid>`。
+
+## 什么时候用
+
+- 用户要求“稍后/每天/每小时/定时/周期性”执行任务
+- 需要无人值守巡检、升级检查、日报、仓库同步
+- 需要基于系统事件触发时，先读 `evolcore/event.md`
+- 需要一次性立即排队执行时，使用 `--once`
+
+不要用 trigger 代替当前会话内的即时动作；一次性马上执行直接处理当前请求。
+
+## 查询
+
+```bash
+ec trigger list
+ec trigger list --all
+ec trigger show <triggerId>
+ec trigger show <triggerId> --json
+ec trigger history [triggerId]
+ec trigger history [triggerId] --limit 500 --json
+```
+
+`list` 默认只显示 enabled trigger。排查历史、禁用项或已达到 limits 的 trigger 时加 `--all`。
+
+`list --json` 返回列表摘要，不返回完整 definition。每项只包含 `id/name/enabled/description`、精简后的 `source`、`execution.type`、`feedback.strategy/target`、`nextFireAt`、最近运行状态和 `updatedAt`。event source 只返回 `eventPattern`，不返回 `filter`；不会返回 prompt/script 参数、model、effort、permissionMode、反馈分支模板、reliability、limits 或 origin。
+
+`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 目录后，历史仍保留。
+
+## 创建
+
+创建操作统一使用 `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
+ec trigger create \
+  --cron '0 9 * * *' \
+  --exec target-session \
+  --prompt '生成昨日摘要并发送给我' \
+  --target-channel <channelKey> --target-channel-id <channelId> \
+  --target-session main \
+  --model <model> --effort high \
+  --name daily-summary \
+  --enable
+```
+
+CLI flag 模式必须显式指定 `--target-channel` 和 `--target-channel-id`，并生成 `feedback.strategy=target`。需要 `origin` 或 `silent` feedback 时，用 `/trigger` 或 `--file` 导入 Trigger V3 第二阶段 JSON。
+
+支持的触发来源：
+
+```bash
+--once
+--delay 30m
+--at 2026-06-28T09:00:00+08:00
+--cron '0 9 * * *'
+--every 4h
+--event 'message:received'
+```
+
+这些来源互斥，只能指定一个。`--cron` 表达式必须加引号，避免被 shell 拆成多个参数。`--every` 是固定间隔，`--cron` 是日历调度。`--once` 创建后立即进入一次 run，完成后自动禁用。
+
+`--event` 基于 EventBus 事件触发，事件模式支持精确事件名、命名空间前缀和全量：`message:received`、`message:*`、`*`。flag 模式只支持设置 `eventPattern`；需要按 payload 字段过滤时，使用 Trigger V3 第二阶段 JSON 的 `source.filter.match`，再通过 `--file` 导入。事件清单、payload 字段和过滤操作见 `$KITS_DOCS/evolcore/event.md`。
+
+## 执行类型
+
+Trigger V3 第二阶段使用 `execution.type` 区分执行位置：
+
+```bash
+--exec script
+--exec trigger-session
+--exec target-session
+```
+
+`target-session` 是默认值：把 `--prompt` 当作一条 trigger 来源消息投递进目标会话队列，并等待该会话处理完成。
+
+`trigger-session` 在 daemon 内部 trigger 会话执行 prompt，再把最终结果按 feedback 投递：
+
+```bash
+--exec trigger-session \
+--prompt '检查服务状态并总结异常' \
+--trigger-thread per-run
+```
+
+省略 `--trigger-thread` 时默认使用 `by-trigger`，同一个 trigger 复用同一条 trigger 会话；只有显式指定 `--trigger-thread per-run` 时，每次 run 才使用独立 trigger 会话。
+
+`script` 执行随 trigger 一起保存的脚本：
+
+```bash
+--exec script \
+--script-path scripts/check.js \
+--script-runtime node \
+--script-timeout 30s \
+--script-args '{"scope":"daily"}'
+```
+
+`script` 不使用 `--prompt`。脚本路径必须在 trigger 目录内；通过 `--file` 导入目录时，脚本文件会随 definition 一起上传。
+
+## 目标与反馈
+
+目标会话字段：
+
+```bash
+--target-channel <channelKey>
+--target-channel-id <channelId>
+--target-session main
+--target-session thread --target-thread-id <threadId>
+```
+
+AUN 渠道由 agent AID 隐式创建，不需要写入 agent 配置的 `channels[]`。CLI 和 Trigger V3.1 definition 均可将 `aun` 用作 `channelKey` 简写；保存前会按 `agentAid` 展开为 `aun#<agentAid>#main`。其他渠道仍需指定完整的实例 channel key。
+
+Trigger V3.1 feedback 是单策略：
+
+- `origin`：送回创建 trigger 的来源会话
+- `target`：送到 `feedback.target`
+- `silent`：不投递最终结果
+
+`target-session` 执行类型只支持 `origin` 或 `target`，因为它本身就是投递到一个会话执行；`script` 和 `trigger-session` 可以使用 `silent`。
+
+默认反馈文本：
+
+- success：`reply.text`
+- noop：空文本，不发送
+- failure：标准失败文本
+
+通常不要显式设置 template。只有 `script` 支持 `feedback.onReply/onNoop/onFailure` 分支模板；`trigger-session` 和 `target-session` 不支持自定义分支模板。
+
+可用占位符示例：
+
+```text
+{{reply.text}}
+{{trigger.name}}
+{{reply.meta.durationMs}}
+{{error.message}}
+{{date}} {{time}}
+```
+
+script trigger 返回 `[[NOOP]]` 或 `outcome: "noop"` 时走 noop 分支；默认 noop 静默。
+
+## 模型与权限
+
+执行模型可按 trigger 单独覆盖：
+
+```bash
+--model <模型>
+--effort <low|medium|high|xhigh|max>
+--baseagent <claude|codex|gemini>
+```
+
+`--model` / `--effort` 只覆盖本 trigger 执行时传给 base agent 的模型与推理强度。
+`--baseagent` 仅支持 `--exec trigger-session`，用于给该 trigger 会话单独选择 base agent；
+`script` 和 `target-session` 不接受该参数。未设置时沿用 trigger 所属 agent 当前 active baseagent。
+
+无人值守 trigger 不适合 `request`。需要写文件、git、安装升级、重启服务、管理 trigger 时应显式使用：
+
+```bash
+--permission bypass
+```
+
+owner/admin 通过 `/trigger create` 创建时默认使用 `bypass`；非 admin 默认 `readonly`，不能提权到 `bypass`，也不能跨渠道或跨会话指定 target。历史 `/trigger set` 仍是兼容别名。
+
+## 执行边界
+
+周期任务建议设置系统边界，避免无限运行：
+
+```bash
+--max-runs 10
+--max-duration 3d
+```
+
+任一边界命中后，scheduler 会禁用后续调度，不中断当前 run。
+
+## 管理
+
+```bash
+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 的兼容别名
+```
+
+语义区别：
+
+| 命令 | 定义文件 | 后续调度 | 当前 run | 可恢复 |
+| --- | --- | --- | --- | --- |
+| `disable` / `cancel` | 保留，写 `enabled: false` | 清理 | 不中断 | 可 `enable` |
+| `delete` | 删除整个 trigger 运行态目录，保留 history tombstone | 清理 | 不中断 | 定义不可恢复，审计可复查 |
+
+`delete` 不需要先执行 `disable/cancel`；它内部会先清理 timer/event/schedule，再删除定义。
+
+## 局部更新
+
+`update` 是 patch 语义，只提交需要修改的字段；未指定字段（包括长 prompt）保持不变。不接受 `--file` 或完整 definition：
+
+```bash
+ec trigger update <triggerId> --cron '0 10 * * *'
+ec trigger update <triggerId> --prompt '新的任务内容' --name new-name
+ec trigger update <triggerId> --cron '0 10 * * *' --if-revision 'sha256:...'
+```
+
+可更新参数只保留三组常用字段：
+
+- 调度：`--once`、`--delay`、`--at`、`--cron`、`--every`、`--event`、`--tz`
+- 内容：`--prompt`、`--name`
+- 执行配置：`--model`、`--effort`、`--permission`
+- 运行边界：`--max-runs`、`--max-duration`、`--concurrency`、`--missed-policy`
+
+脚本、投递目标、feedback、reliability、limits、event filter 或执行类型需要变化时，删除后重新创建 trigger，避免 `update` 演变成完整 definition 编辑器。
+
+`--if-revision` 是可选的乐观并发检查；值来自 `show --json` 顶层的 `revision`。revision 不一致时更新失败，不覆盖较新的 definition。
+
+`--tz` 只对 cron 有效，用 IANA 时区（如 `Asia/Shanghai`、`UTC`）解释 cron；不写时使用运行进程时区。`--concurrency` 控制上一 run 仍在执行时的行为（`forbid`/`replace`/`allow`）；`--missed-policy` 控制错过触发时间后的行为（`skip`/`run-once`/`run-all`）。
+
+`update --json` 返回更新后的列表摘要和新 revision，不回传包含长 prompt 的完整 definition。
+
+## 手动运行
+
+```bash
+ec trigger run <triggerId>
+ec trigger run <triggerId> --dry-run
+```
+
+`--dry-run` 不写 active 状态、不写正式 audit、不执行真实副作用，适合验证 prompt/template。
+
+## 审计存储
+
+```text
+data/triggers/<aid>/<triggerId>/trigger.json
+data/triggers/<aid>/<triggerId>/active.json
+data/triggers/<aid>/history.jsonl
+logs/trigger-runs.log
+```
+
+- `history.jsonl` 是长期 append-only 审计真相源，默认不自动清理。
+- 旧版 done 归档行保持可读，不会在升级时重写。
+- `trigger-runs.log` 是短期运维日志，按天轮转并保留 7 天。
+- `show` 的 recent run 摘要、运行统计和 `history` 命令读取长期历史。
+- 启动时会把仍保留的旧 `trigger-runs*.log` 幂等补导入 `history.jsonl`。
+
+## 从文件导入
+
+复杂 trigger 使用 Trigger V3 第二阶段 JSON：
+
+```bash
+ec trigger create --file ./trigger.json --enable
+ec trigger create --file ./trigger-dir --enable
+```
+
+当前产品版本是 Trigger V3 第二阶段；其持久化定义版本为 `$schema_version: 3.1`。旧 `$schema_version: 4` 文件加载时会自动规范化为 `3.1`。
+
+### target-session 示例
+
+```json
+{
+  "$schema_version": 3.1,
+  "agentAid": "<aid>",
+  "enabled": true,
+  "name": "daily-summary",
+  "source": {
+    "type": "cron",
+    "expression": "0 9 * * *",
+    "timezone": "Asia/Shanghai"
+  },
+  "execution": {
+    "type": "target_session",
+    "prompt": "生成昨日摘要并发送给我",
+    "model": "<model>",
+    "effort": "high",
+    "permissionMode": "bypass",
+    "onError": "fail",
+    "noopSentinel": "[[NOOP]]"
+  },
+  "feedback": {
+    "strategy": "target",
+    "target": {
+      "channelKey": "<channelKey>",
+      "channelId": "<channelId>",
+      "session": "main"
+    }
+  },
+  "reliability": {
+    "concurrency": "forbid",
+    "missedPolicy": "run_once",
+    "retry": {
+      "maxAttempts": 0,
+      "backoffMs": 30000
+    }
+  }
+}
+```
+
+### trigger-session 示例
+
+```json
+{
+  "$schema_version": 3.1,
+  "agentAid": "<aid>",
+  "enabled": true,
+  "name": "hourly-health-check",
+  "origin": {
+    "channelKey": "<channelKey>",
+    "channelId": "<channelId>",
+    "session": "main"
+  },
+  "source": {
+    "type": "interval",
+    "everyMs": 3600000
+  },
+  "execution": {
+    "type": "trigger_session",
+    "prompt": "检查服务状态并总结异常；无异常输出 [[NOOP]]",
+    "thread": "per_run",
+    "permissionMode": "readonly",
+    "onError": "retry",
+    "noopSentinel": "[[NOOP]]"
+  },
+  "feedback": {
+    "strategy": "origin"
+  },
+  "reliability": {
+    "concurrency": "forbid",
+    "missedPolicy": "run_once",
+    "retry": {
+      "maxAttempts": 1,
+      "backoffMs": 30000
+    }
+  }
+}
+```
+
+### script 示例
+
+```json
+{
+  "$schema_version": 3.1,
+  "agentAid": "<aid>",
+  "enabled": true,
+  "name": "script-health",
+  "source": {
+    "type": "cron",
+    "expression": "0 */4 * * *",
+    "timezone": "Asia/Shanghai"
+  },
+  "execution": {
+    "type": "script",
+    "script": {
+      "path": "scripts/health.js",
+      "runtime": "node",
+      "timeoutMs": 30000
+    },
+    "onError": "retry",
+    "noopSentinel": "[[NOOP]]"
+  },
+  "feedback": {
+    "strategy": "target",
+    "target": {
+      "channelKey": "<channelKey>",
+      "channelId": "<channelId>",
+      "session": "main"
+    },
+    "onReply": {
+      "template": "{{reply.text}}"
+    },
+    "onNoop": {
+      "template": ""
+    },
+    "onFailure": {
+      "template": "健康检查失败：{{error.message}}"
+    }
+  },
+  "reliability": {
+    "concurrency": "forbid",
+    "missedPolicy": "run_once",
+    "retry": {
+      "maxAttempts": 2,
+      "backoffMs": 30000
+    }
+  }
+}
+```
+
+## 事件触发
+
+简单事件触发可直接用 flag 模式：
+
+```bash
+ec trigger create --event 'message:received' \
+  --exec target-session \
+  --prompt '检查收到的消息是否需要自动跟进；无动作输出 [[NOOP]]' \
+  --target-channel <channelKey> --target-channel-id <channelId> \
+  --target-session main \
+  --name on-message-received --enable
+```
+
+监听某个命名空间下的所有事件：
+
+```bash
+ec trigger create --event 'task:*' \
+  --exec target-session \
+  --prompt '任务完成或失败后生成简短诊断；无动作输出 [[NOOP]]' \
+  --target-channel <channelKey> --target-channel-id <channelId> \
+  --target-session main \
+  --name on-task-events --enable
+```
+
+flag 模式不能配置过滤条件。需要根据事件 payload 过滤时，写完整的 Trigger V3 第二阶段 JSON：
+
+```json
+{
+  "$schema_version": 3.1,
+  "agentAid": "<aid>",
+  "enabled": true,
+  "name": "on-important-message",
+  "source": {
+    "type": "event",
+    "eventPattern": "message:received",
+    "filter": {
+      "match": {
+        "channel": "<channelKey>",
+        "channelId": "<channelId>",
+        "content": { "$regex": "日报|告警|失败" }
+      }
+    }
+  },
+  "execution": {
+    "type": "target_session",
+    "prompt": "根据事件内容判断是否需要处理；无动作输出 [[NOOP]]",
+    "permissionMode": "readonly",
+    "onError": "retry",
+    "noopSentinel": "[[NOOP]]"
+  },
+  "feedback": {
+    "strategy": "target",
+    "target": {
+      "channelKey": "<channelKey>",
+      "channelId": "<channelId>",
+      "session": "main"
+    }
+  },
+  "reliability": {
+    "concurrency": "forbid",
+    "missedPolicy": "run_once",
+    "retry": {
+      "maxAttempts": 0,
+      "backoffMs": 30000
+    }
+  }
+}
+```
+
+`source.filter.match` 的 key 是 payload 字段路径，支持等值、`$in`、`$regex`、数值比较和 `$exists`。例如 `message:received` 可过滤 `channel`、`channelId`、`content`、`userId`、`sessionId`；完整字段以事件目录为准。
+
+## 常用例子
+
+一次性提醒：
+
+```bash
+ec trigger create --delay 30m \
+  --exec target-session \
+  --prompt '提醒用户检查部署状态' \
+  --target-channel <channelKey> --target-channel-id <channelId> \
+  --target-session main \
+  --name deploy-reminder --enable
+```
+
+创建后立即执行一次：
+
+```bash
+ec trigger create --once \
+  --exec target-session \
+  --prompt '生成一次当前状态摘要' \
+  --target-channel <channelKey> --target-channel-id <channelId> \
+  --target-session main \
+  --name one-shot-summary --enable
+```
+
+每天巡检：
+
+```bash
+ec trigger create --cron '30 9 * * *' \
+  --exec target-session \
+  --prompt '检查服务状态并汇报异常；无异常输出 [[NOOP]]' \
+  --target-channel <channelKey> --target-channel-id <channelId> \
+  --target-session main \
+  --name daily-health-check --enable
+```
+
+复用 trigger 会话做周期跟踪：
+
+```bash
+ec trigger create --every 4h \
+  --exec trigger-session \
+  --trigger-thread by-trigger \
+  --prompt '继续跟踪升级状态并输出最新结论；无变化输出 [[NOOP]]' \
+  --target-channel <channelKey> --target-channel-id <channelId> \
+  --target-session main \
+  --name upgrade-watch --enable
+```
+
+定时尝试升级，最多 10 次或 3 天：
+
+```bash
+ec trigger create --every 4h \
+  --max-runs 10 --max-duration 3d \
+  --permission bypass \
+  --model <model> --effort high \
+  --exec target-session \
+  --prompt '尝试执行升级检查；成功后调用 ec trigger disable auto-updater；无变化输出 [[NOOP]]' \
+  --target-channel <channelKey> --target-channel-id <channelId> \
+  --target-session main \
+  --name auto-updater --enable
+```
+
+硬删除：
+
+```bash
+ec trigger delete auto-updater
+```
+
+## 相关文档
+
+- event source 可监听事件：`$KITS_DOCS/evolcore/event.md`
+- Trigger V3 第二阶段执行与反馈设计：`$PACKAGE_ROOT/docs/trigger-v3-phase2-execution-feedback-design.md`
+- limits / disable / delete 语义：`$PACKAGE_ROOT/docs/trigger-limits-feature-v2.md`

package/kits/docs/identity/AID_PROFILE_SPEC.md

@@ -0,0 +1,26 @@
+# AID 档案规范
+
+<!-- TODO: 填充 AID 档案格式规范 -->
+
+## 档案类型
+
+| 类型 | 位置 | 说明 |
+|------|------|------|
+| 自身人格 | `$SELF_DIR/persona.md` | 行为规范、人格定义 |
+| 关系档案 | `$RELATIONS_DIR/<peerKey>/profile.md` | 对端关系记录（含具体群实例） |
+
+## persona.md 结构
+
+```markdown
+# <agent-name>
+
+## 基本信息
+- AID: <aid>
+- 名称: <name>
+
+## 行为规范
+（定义称呼、语气、风格等）
+
+## 能力声明
+（对外公开的能力描述）
+```

package/kits/docs/identity/PATH_OPS.md

@@ -0,0 +1,16 @@
+# 路径运维操作
+
+<!-- TODO: 填充路径失效处理、迁移、新增路径等运维操作 -->
+
+## 路径失效处理
+
+当 `$ECK/path-registry.md` 中某路径不存在时：
+1. 检查路径是否已迁移（查 git log）
+2. 尝试按派生规则重新计算
+3. 如无法恢复，标记为 `❌` 并通知用户
+
+## 新增路径
+
+1. 在 `$KITS_DOCS/path-registry.md` 添加定义
+2. 在 `$ECK/path-registry.md` 添加实例值
+3. 更新 `$KITS_DOCS/INDEX.md`

package/kits/docs/identity/ROLE_DETAIL.md

@@ -0,0 +1,23 @@
+# 角色与场景详细规则
+
+<!-- TODO: 填充权限矩阵、场景矩阵、对端发现流程 -->
+
+## 权限矩阵
+
+| 角色 | 对话 | 配置 | 管理 | 运维 |
+|------|------|------|------|------|
+| owner | Yes | Yes | Yes | Yes |
+| admin | Yes | Yes | Yes | No |
+| member | Yes | 仅自身关系 | No | No |
+| visitor | Yes | No | No | No |
+| none | No | No | No | No |
+
+进程级 daemon owner 是最高管理者；它通过 agent channel 进入时按设计作为该 agent 的 owner 处理。
+
+## 场景矩阵
+
+| 场景 | 响应策略 | 工具可用性 |
+|------|----------|-----------|
+| coding | 每条响应 | 全部 |
+| private | 自主决定 | 全部 |
+| group | 被@响应 | 全部 |

package/kits/docs/identity/identity-tools.md

@@ -0,0 +1,26 @@
+# 身份/环境层工具用法
+
+## 身份识别
+
+当你在对话中识别出对端的真实身份时，可以调用：
+
+```bash
+ec ctl identity.identify --aid <对端AID> --name <名称> --type person --method self-declaration
+```
+
+## 查看对端信息
+
+```bash
+ec ctl identity.show <对端AID>
+```
+
+## 查看当前环境
+
+```bash
+ec ctl venue.show
+```
+
+## 注意
+
+- 身份层工具仅在身份层运行时实现后可用（当前为占位文档）
+- 对端名片通过 `https://<aid>/agent.md` 获取，由 AUN 网络提供

package/kits/docs/path-registry.md

@@ -0,0 +1,43 @@
+# 路径定义
+
+本文件定义所有预定义路径的含义和派生规则。运行时实际值在 `$ECK/path-registry.md`。
+
+## 基础路径（三个锚点）
+
+| 名称 | 含义 | 来源 |
+|------|------|------|
+| `$EVOLCORE_HOME` | evolcore 用户数据根 | 环境变量 `EVOLCORE_HOME` 或默认 `~/.evolcore` |
+| `$PACKAGE_ROOT` | evolcore 包根目录 | `require.resolve('evolcore')` 所在目录 |
+| `$CURRENT_PROJECT` | 当前工作目录 | `process.cwd()` |
+
+## 包内路径（从 $PACKAGE_ROOT 派生）
+
+| 名称 | 派生规则 | 说明 |
+|------|----------|------|
+| `$KITS` | `$PACKAGE_ROOT/kits` | kits 根目录 |
+| `$KITS_RULES` | `$KITS/rules` | 自动加载的规则文件 |
+| `$KITS_DOCS` | `$KITS/docs` | 按需加载的文档 |
+| `$KITS_TEMPLATES` | `$KITS/templates` | 运行时 prompt 组装模板 |
+
+## 用户数据路径（从 $EVOLCORE_HOME 派生）
+
+| 名称 | 派生规则 | 说明 |
+|------|----------|------|
+| `$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 级索引 |
+
+## 外部依赖路径（需寻找）
+
+| 名称 | 寻找规则 | 说明 |
+|------|----------|------|
+| `$KITE` | 在 `$EVOLCORE_HOME/config.json` 的 `kitePath` 字段查找 | Kite 框架根 |
+| `$AUN_SDK_CORE` | `$KITE/aun-sdk-core` | AUN SDK 源码 |
+
+## 路径实例文件
+
+运行时实际路径值写入 `$ECK/path-registry.md`，格式见 `$KITS_DOCS/eck_templates/path-registry.template.md`。