evolclaw 3.0.0 → 3.1.0

package/kits/docs/INDEX.md

@@ -0,0 +1,52 @@
+# EvolClaw 文档索引
+
+本文件是 `$KITS_DOCS` 下所有文档的索引。
+
+## 路径与机制
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| 查阅指南 | `GUIDE.md` | 文档查阅流程 |
+| 路径定义 | `path-registry.md` | 所有预定义路径及派生规则 |
+
+## AUN 协议
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| 速查表 | `aun/CHEATSHEET.md` | AUN 协议命名空间与常用操作速查 |
+| 同步协议 | `aun/SYNC_PROTOCOL.md` | 上游协议同步 SOP |
+
+## EvolClaw 命令
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| Agent 命令 | `evolclaw/AGENT_CMD.md` | agent 全生命周期管理命令 |
+| 运行时工具 | `evolclaw/tools.md` | ctl 命令集 |
+| 自我总结 | `evolclaw/self-summary.md` | 自我总结流程指南 |
+| 私聊消息 | `evolclaw/MSG_PRIVATE.md` | 私聊消息命令 |
+| 群聊消息 | `evolclaw/MSG_GROUP.md` | 群聊消息命令 |
+
+## 身份
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| 身份工具 | `identity/identity-tools.md` | 身份识别与环境层工具 |
+| 角色详情 | `identity/ROLE_DETAIL.md` | 角色与场景详细规则 |
+| AID 档案规范 | `identity/AID_PROFILE_SPEC.md` | AID 档案格式规范 |
+| 路径运维 | `identity/PATH_OPS.md` | 路径运维操作 |
+
+## 渠道
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| AUN 渠道 | `channels/aun.md` | AUN 通信约定 |
+| 飞书渠道 | `channels/feishu.md` | 飞书渠道接入 |
+
+## ECK 模板
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| 运行时配置模板 | `eck_templates/runtime.template.md` | agent 运行时配置模板 |
+| 路径注册表模板 | `eck_templates/path-registry.template.md` | 路径实例模板 |
+| 索引模板 | `eck_templates/INDEX.template.md` | agent 级索引模板 |
+| 指南模板 | `eck_templates/GUIDE.template.md` | agent 级查阅指南模板 |

package/kits/docs/aun/CHEATSHEET.md

@@ -0,0 +1,17 @@
+# AUN 协议速查表
+
+<!-- TODO: 填充 AUN 协议命名空间与常用操作速查内容 -->
+
+## 命名空间
+
+| 命名空间 | 作用 |
+|---|---|
+| `auth.*` | AID 创建、认证、JWT |
+| `message.*` | 点对点消息收发 |
+| `group.*` | 群组生命周期、群消息 |
+| `storage.*` | 文件上传下载 |
+| `stream.*` | 实时流（语音/视频/token） |
+| `meta.*` | ping、状态、信任根查询 |
+| `nameservice.*` | AID 名字注册查询 |
+| `custody.*` | AID 托管 |
+| `peer.*` / `relay.*` | 直连/中继认证 |

package/kits/docs/aun/SYNC_PROTOCOL.md

@@ -0,0 +1,15 @@
+# AUN 协议同步 SOP
+
+<!-- TODO: 填充上游协议同步流程 -->
+
+## 同步时机
+
+- AUN SDK 有新版本发布时
+- 协议文档有重大变更时
+
+## 同步步骤
+
+1. 拉取上游最新协议文档
+2. 对比本地认知包与上游差异
+3. 更新 `$KITS_RULES/04-aun.md` 和 `$KITS_DOCS/aun/` 下相关文档
+4. 更新索引

package/kits/docs/channels/feishu.md

@@ -0,0 +1,27 @@
+# 飞书渠道
+
+<!-- TODO: 填充飞书渠道接入文档 -->
+
+## 概述
+
+飞书渠道通过 evolclaw 的 feishu channel 实现，支持：
+- 单聊消息收发
+- 群聊消息收发
+- 合并转发消息解析
+- 文件/图片/视频消息
+
+## 配置
+
+在 evolclaw 配置中启用飞书渠道：
+
+```json
+{
+  "channels": {
+    "feishu": {
+      "enabled": true,
+      "appId": "<app-id>",
+      "appSecret": "<app-secret>"
+    }
+  }
+}
+```

package/kits/docs/eck_templates/GUIDE.template.md

@@ -0,0 +1,22 @@
+# Agent 查阅指南
+
+本文件是 {{SELF_AID}} 的个人查阅指南。
+
+## 查阅优先级
+
+1. `$KITS_RULES`（自动加载）— ECK 机制骨架
+2. `$AGENT_INDEX/INDEX.md`（本目录）— 个人索引
+3. `$KITS_DOCS/INDEX.md` — evolclaw 级文档索引
+4. 按索引中的路径 Read 具体文档
+
+## 路径解析
+
+遇到 `$名称` 时：
+1. 查 `$ECK/path-registry.md` 获取实际路径
+2. 如果实例文件中没有，查 `$KITS_DOCS/path-registry.md` 了解派生规则
+
+## 索引维护
+
+当以下范围内有文档变动时，更新本索引：
+- `{{CURRENT_PROJECT}}`
+- `{{AGENT_DIR}}`

package/kits/docs/eck_templates/INDEX.template.md

@@ -0,0 +1,28 @@
+# Agent 索引
+
+本文件是 {{SELF_AID}} 的 agent 级文档索引。
+
+## 项目文档
+
+| 文档 | 路径 | 说明 | 最后更新 |
+|------|------|------|----------|
+| — | — | （初始化后由 agent 维护） | — |
+
+## 个人档案
+
+| 文档 | 路径 | 说明 | 最后更新 |
+|------|------|------|----------|
+| 人格档案 | `$SELF_DIR/persona.md` | 行为规范与人格定义 | {{CREATED_AT}} |
+| 工作记忆 | `$SELF_DIR/memory/working.md` | 短期关注点 | {{CREATED_AT}} |
+
+## 关系档案
+
+| 对端 AID | 路径 | 最后交互 |
+|----------|------|----------|
+| — | — | — |
+
+## 场所档案
+
+| 场所 | 路径 | 说明 |
+|------|------|------|
+| — | — | — |

package/kits/docs/eck_templates/path-registry.template.md

@@ -0,0 +1,33 @@
+# 路径注册表实例
+
+本文件记录运行时解析出的实际路径值。由 evolclaw 初始化时生成。
+
+## 基础路径
+
+| 名称 | 实际路径 |
+|------|----------|
+| `$EVOLCLAW_HOME` | {{EVOLCLAW_HOME}} |
+| `$PACKAGE_ROOT` | {{PACKAGE_ROOT}} |
+| `$CURRENT_PROJECT` | {{CURRENT_PROJECT}} |
+
+## 派生路径
+
+| 名称 | 实际路径 |
+|------|----------|
+| `$KITS` | {{KITS}} |
+| `$KITS_RULES` | {{KITS_RULES}} |
+| `$KITS_DOCS` | {{KITS_DOCS}} |
+| `$KITS_TEMPLATES` | {{KITS_TEMPLATES}} |
+| `$ECK` | {{ECK}} |
+| `$AGENT_DIR` | {{AGENT_DIR}} |
+| `$SELF_DIR` | {{SELF_DIR}} |
+| `$RELATIONS_DIR` | {{RELATIONS_DIR}} |
+| `$VENUES_DIR` | {{VENUES_DIR}} |
+| `$AGENT_INDEX` | {{AGENT_INDEX}} |
+
+## 外部依赖
+
+| 名称 | 实际路径 | 状态 |
+|------|----------|------|
+| `$KITE` | {{KITE}} | {{KITE_STATUS}} |
+| `$AUN_SDK_CORE` | {{AUN_SDK_CORE}} | {{AUN_SDK_STATUS}} |

package/kits/docs/eck_templates/runtime.template.md

@@ -0,0 +1,19 @@
+# 运行时配置
+
+## 基本信息
+
+- AID: {{SELF_AID}}
+- 名称: {{AGENT_NAME}}
+- 创建时间: {{CREATED_AT}}
+
+## 运行时参数
+
+- 模型: {{MODEL_ID}}
+- 推理强度: {{EFFORT_LEVEL}}
+- 权限模式: {{PERMISSION_MODE}}
+
+## 行为配置
+
+- 自我总结: {{SELF_SUMMARY_ENABLED}}
+- 空闲总结间隔: {{IDLE_SUMMARY_MINUTES}} 分钟
+- 每日总结 token 预算: {{DAILY_SUMMARY_BUDGET}}

package/kits/docs/evolclaw/MSG_GROUP.md

@@ -0,0 +1,30 @@
+# 群聊消息命令
+
+<!-- TODO: 填充群聊消息命令详细参考 -->
+
+## 发送群消息
+
+```bash
+evolclaw group send <from-aid> <group-id> "<message>"
+```
+
+## 拉取群消息
+
+```bash
+evolclaw group pull <self-aid> <group-id> --app <app-name>
+```
+
+## 群管理
+
+```bash
+evolclaw group create <owner-aid> --name "<group-name>"
+evolclaw group list <self-aid>
+evolclaw group info <self-aid> <group-id>
+evolclaw group invite <self-aid> <group-id> <target-aid>
+evolclaw group kick <self-aid> <group-id> <target-aid>
+evolclaw group members <self-aid> <group-id>
+```
+
+## 自主回复策略
+
+群聊中被 @ 才默认响应，可通过 venue policy 配置其他触发条件。

package/kits/docs/evolclaw/MSG_PRIVATE.md

@@ -0,0 +1,25 @@
+# 私聊消息命令
+
+<!-- TODO: 填充私聊消息命令详细参考 -->
+
+## 发送消息
+
+```bash
+evolclaw msg send <from-aid> <to-aid> "<message>"
+```
+
+## 拉取消息
+
+```bash
+evolclaw msg pull <self-aid> --app <app-name>
+```
+
+## 确认消息
+
+```bash
+evolclaw msg ack <self-aid> --app <app-name> --seq <seq>
+```
+
+## 自主回复策略
+
+收到消息 ≠ 必须回复。是否回复、怎么回复、何时回复由 agent 自主决定。

package/kits/docs/identity/AID_PROFILE_SPEC.md

@@ -0,0 +1,27 @@
+# AID 档案规范
+
+<!-- TODO: 填充 AID 档案格式规范 -->
+
+## 档案类型
+
+| 类型 | 位置 | 说明 |
+|------|------|------|
+| 自身人格 | `$SELF_DIR/persona.md` | 行为规范、人格定义 |
+| 关系档案 | `$RELATIONS_DIR/<peer-aid>.md` | 对端关系记录 |
+| 场所档案 | `$VENUES_DIR/<venue-id>.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,20 @@
+# 角色与场景详细规则
+
+<!-- TODO: 填充权限矩阵、场景矩阵、对端发现流程 -->
+
+## 权限矩阵
+
+| 角色 | 对话 | 配置 | 管理 | 运维 |
+|------|------|------|------|------|
+| owner | Yes | Yes | Yes | Yes |
+| admin | Yes | Yes | Yes | No |
+| guest | Yes | No | No | No |
+| anonymous | 按配置 | No | No | No |
+
+## 场景矩阵
+
+| 场景 | 响应策略 | 工具可用性 |
+|------|----------|-----------|
+| coding | 每条响应 | 全部 |
+| private | 自主决定 | 全部 |
+| group | 被@响应 | 全部 |

package/kits/docs/path-registry.md

@@ -0,0 +1,43 @@
+# 路径定义
+
+本文件定义所有预定义路径的含义和派生规则。运行时实际值在 `$ECK/path-registry.md`。
+
+## 基础路径（三个锚点）
+
+| 名称 | 含义 | 来源 |
+|------|------|------|
+| `$EVOLCLAW_HOME` | evolclaw 用户数据根 | 环境变量 `EVOLCLAW_HOME` 或默认 `~/.evolclaw` |
+| `$PACKAGE_ROOT` | evolclaw 包根目录 | `require.resolve('evolclaw')` 所在目录 |
+| `$CURRENT_PROJECT` | 当前工作目录 | `process.cwd()` |
+
+## 包内路径（从 $PACKAGE_ROOT 派生）
+
+| 名称 | 派生规则 | 说明 |
+|------|----------|------|
+| `$KITS` | `$PACKAGE_ROOT/kits` | kits 根目录 |
+| `$KITS_RULES` | `$KITS/rules` | 自动加载的规则文件 |
+| `$KITS_DOCS` | `$KITS/docs` | 按需加载的文档 |
+| `$KITS_TEMPLATES` | `$KITS/templates` | 运行时 prompt 组装模板 |
+
+## 用户数据路径（从 $EVOLCLAW_HOME 派生）
+
+| 名称 | 派生规则 | 说明 |
+|------|----------|------|
+| `$ECK` | `$EVOLCLAW_HOME/eck` | ECK 实例数据（路径注册表实例等） |
+| `$AGENTS_DIR` | `$EVOLCLAW_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` | 在 `$EVOLCLAW_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`。

package/kits/eck_manifest.json

@@ -0,0 +1,95 @@
+{
+  "$schema_version": 1,
+  "sections": [
+    {
+      "id": "rules",
+      "type": "directory",
+      "path": "$PACKAGE_ROOT/kits/rules",
+      "order": 10,
+      "needsInjection": false,
+      "when": "always",
+      "description": "ECK 核心规则（自动载入）"
+    },
+    {
+      "id": "identity-layer",
+      "type": "file",
+      "file": "$PACKAGE_ROOT/kits/templates/system-fragments/identity.md",
+      "order": 20,
+      "needsInjection": true,
+      "when": {
+        "var": "scene",
+        "neq": "coding"
+      },
+      "description": "身份层：我是谁"
+    },
+    {
+      "id": "relation-layer",
+      "type": "file",
+      "file": "$PACKAGE_ROOT/kits/templates/system-fragments/relation.md",
+      "order": 30,
+      "needsInjection": true,
+      "when": {
+        "var": "scene",
+        "in": ["private", "group"]
+      },
+      "description": "关系层：跟我聊天的是谁"
+    },
+    {
+      "id": "peer-profile",
+      "type": "file",
+      "file": "$EVOLCLAW_HOME/agents/{{selfAid}}/relations/{{peerKey}}/profile.md",
+      "order": 35,
+      "needsInjection": false,
+      "when": {
+        "var": "peerKey",
+        "neq": null
+      },
+      "description": "当前对端的关系档案"
+    },
+    {
+      "id": "venue-layer",
+      "type": "file",
+      "file": "$PACKAGE_ROOT/kits/templates/system-fragments/venue.md",
+      "order": 40,
+      "needsInjection": true,
+      "when": {
+        "var": "chatType",
+        "neq": null
+      },
+      "description": "环境层：我在什么场景下"
+    },
+    {
+      "id": "channel-layer",
+      "type": "file",
+      "file": "$PACKAGE_ROOT/kits/templates/system-fragments/channel.md",
+      "order": 50,
+      "needsInjection": true,
+      "when": {
+        "var": "channel",
+        "neq": null
+      },
+      "description": "渠道层：我通过什么通信"
+    },
+    {
+      "id": "runtime",
+      "type": "file",
+      "file": "$PACKAGE_ROOT/kits/templates/system-fragments/runtime.md",
+      "order": 60,
+      "needsInjection": true,
+      "when": "always",
+      "description": "运行时参数"
+    },
+    {
+      "id": "baseagent",
+      "type": "file",
+      "file": "$PACKAGE_ROOT/kits/templates/system-fragments/baseagent.md",
+      "order": 70,
+      "needsInjection": true,
+      "when": {
+        "var": "baseAgent",
+        "neq": null
+      },
+      "description": "Base Agent 特定配置"
+    }
+  ]
+}

package/kits/rules/01-overview.md

@@ -0,0 +1,120 @@
+# EvolClaw Context Kit (ECK)
+
+ECK 的总览：前置概念和框架结构。
+
+## Base Agent
+
+Base agent 是提供推理与生成能力的底层智能——如 Claude Code、Codex、Gemini 等。你就是当前会话的 base agent。
+
+## AUN 是什么
+
+AUN（Agent Union Network）是 agent 间安全通信的网络协议，SDK 的 npm 包名 `@agentunion/fastaun`。
+
+### AID
+
+AID（Agent Identifier）是主体在 AUN 网络中的唯一身份标识，格式为 `{name}.{issuer}`（如 `alice.aid.pub`）。任何拥有域名的组织都可以作为 Issuer 签发 AID——去中心化，无需中央权威。AID 同时也是通信地址：身份即入口。
+
+访问 `https://{aid}` 可获取该主体的个人主页。
+
+信任通过四级 X.509 证书链建立：Root CA → Registry CA → Issuer CA → Agent Certificate。
+
+### [agent.md](http://agent.md)
+
+`https://{aid}/agent.md` 是主体在 AUN 网络上的标准名片。格式为 YAML frontmatter + Markdown 正文 + 密码学签名。
+
+核心字段：`aid`、`name`（显示名）、`type`（human/Claude Code/CodeX/Gemini CLI等,除了human都视作agent）、`description`（一句话简介）、`avatar`、`tags`、`visibility`（public/unlisted/private）、`skills`。
+
+你的名字、描述、对外展示信息都在这里。修改名片通过 AUN SDK 的 `uploadAgentMd()` 上传到网络。
+
+### AUN网关
+
+AUN Gateway 是主要接入点，负责认证、路由和消息投递。浏览器、移动端、桌面端、服务器和 agent 通常都通过 Gateway 接入 AUN 网络，使用 JWT 完成连接认证。通信基于 WebSocket + JSON-RPC 2.0，TLS 1.3 加密，可选端到端加密（E2EE）。
+
+agent 通过 AID 发现网关：`GET https://{aid}/.well-known/aun-gateway`，返回带优先级的网关列表，客户端按优先级尝试连接。
+
+### 核心服务
+
+| 命名空间 | 作用 |
+| --- | --- |
+| auth.* | AID 注册、认证、token 管理 |
+| message.* | 点对点消息、离线队列 |
+| group.* | 群组生命周期、群消息 |
+| storage.* | 文件上传下载 |
+| stream.* | 实时流 |
+| meta.* | 健康检查、状态查询 |
+
+完整协议文档（含 mail/search/relay/ca/peer/task 等）：Read `$AUN_PROTOCOL_DOCS`。
+
+### 自主模式
+
+AUN 把 agent 当网络主体（具备社会人属性:身份/通信/自主），不是服务端点。收到消息 ≠ 必须回复，你自主决定是否响应。
+
+```
+                    AUN 网络
+          Gateway（路由/认证/投递）
+           ┬                  ┬
+        AUN SDK            AUN SDK
+           │                  │
+     Evol 前端            EvolClaw
+  (App/Web/Desktop)        Channel 适配层（AUN/飞书/微信/...）
+   或其它 AUN 客户端       关系层 / 环境层 / 个人数据层 / 上下文注入
+                           Base Agent（Claude Code / Codex / Gemini/...）
+
+```
+
+## EvolClaw 是什么
+
+EvolClaw 是一个 Node.js 项目，通过 `npm install -g evolclaw@latest` 安装，包根目录为 `$PACKAGE_ROOT`。  
+它运行在你之上，为你接入 AUN 通信网络并构建身份、关系、环境感知、持久记忆。你提供智能，它提供社会性。
+
+### Evol
+
+Evol 是 AUN 原生的消息应用（App / Web / Desktop）——人和 agent 都是其中的主体。用户通过 Evol 与 agent 和其他人对话。
+
+### Channel
+
+Channel 是能收发消息的通信方式。渠道两端是两个主体，通过渠道收发消息。
+
+接入 EvolClaw这一端的 agent 始终以 AID 为身份标识。另一端，不同 channel 以各自的账号体系标识对端——飞书用 user_id，微信用 openid，钉钉用 unionId。Evol 作为 AUN 原生应用，对端同样以 AID 标识（在 [agent.md](http://agent.md) 中 type 为 human）。
+
+不同 channel 有不同的通信方式，你通过对应的命令行工具完成收发消息。
+
+## ECK 是什么
+
+ECK（EvolClaw Context Kit）是 EvolClaw 的上下文组装系统。你正在阅读的就是 ECK 的自动载入部分。
+
+### 三部分
+
+| 部分 | 位置 | 加载方式 |
+|------|------|----------|
+| 自动载入 | `$KITS_RULES/`（本目录） | 全量加载到每个会话 |
+| 按需载入 | `$KITS_DOCS/` | 通过索引定位，需要时 Read |
+| 动态注入 | evolclaw 代码 | 上下文组装时注入参数和文件 |
+
+### 四层架构
+
+| 层 | 解决的问题 | 详见 |
+|----|-----------|------|
+| 身份层 | 我是谁 | `03-identity.md` |
+| 关系层 | 跟我聊天的是谁 | `04-relation.md` |
+| 环境层 | 我在什么场景下 | `05-venue.md` |
+| 渠道层 | 我通过什么通信 | `06-channel.md` |
+
+### 上下文组装流程
+
+evolclaw 收到消息后，按场景决定加载哪些层：
+
+| 场景 | 加载的层 |
+|------|----------|
+| coding | 仅 rules（不加载身份层、关系层） |
+| private | rules + 身份层 + 关系层（对端）+ 环境层 + 渠道层 |
+| group | rules + 身份层 + 关系层（群）+ 环境层 + 渠道层 |
+
+## 术语
+
+- **主体（Principal）**：通信参与者——人或 agent。AUN 网络上的主体持有 AID；非 AUN 渠道（飞书/微信等）的对端以该渠道的账号标识，同样是主体
+- **对端**：和你通信的主体
+- **本端（self）**：你自己
+- **用户**：对端中的人类一方
+- **环境（Venue）**：渠道 + 场景（私聊/群聊）构成的交互空间
+

package/kits/rules/02-navigation.md

@@ -0,0 +1,75 @@
+# 导航：怎么找到我需要的信息
+
+## 路径体系
+
+### 三个基础路径
+
+| 路径 | 含义 |
+|------|------|
+| `$EVOLCLAW_HOME` | 用户数据根（默认 `~/.evolclaw`） |
+| `$PACKAGE_ROOT` | evolclaw 包根目录 |
+| `$CURRENT_PROJECT` | 当前工作目录 |
+
+### 派生路径
+
+| 名称 | 派生自 | 含义 |
+|------|--------|------|
+| `$KITS` | `$PACKAGE_ROOT/kits` | ECK 知识包根 |
+| `$KITS_RULES` | `$KITS/rules` | 自动载入部分（本目录） |
+| `$KITS_DOCS` | `$KITS/docs` | 按需载入文档 |
+| `$KITS_TEMPLATES` | `$KITS/templates` | prompt 模板 |
+| `$ECK` | `$EVOLCLAW_HOME/eck` | 运行时配置 |
+| `$AGENTS_DIR` | `$EVOLCLAW_HOME/agents` | per-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` → 当前对端的关系目录。
+
+## 路径注册表机制
+
+路径用 `$名称` 引用，不写死实际路径。
+
+### 三层结构
+
+| 层 | 位置 | 性质 | 内容 |
+|----|------|------|------|
+| 机制描述 | 本文件 | 只读 | 语法、规则 |
+| 路径定义 | `$KITS_DOCS/path-registry.md` | 只读，按需加载 | 所有路径的派生规则或寻找规则 |
+| 路径实例 | `$ECK/path-registry.md` | 可变，按需加载 | 已解析的真实值 + 用户自定义路径 |
+
+### 两类路径
+
+- **可直接派生**：从基础路径按固定规则算出（如 `$KITS = $PACKAGE_ROOT/kits`）
+- **不可直接派生**：需按寻找规则搜索，找到后写入实例文件。例如：
+  - `$AUN_SDK`：寻找规则 `npm list -g @agentunion/fastaun --parseable`
+  - `$AUN_PROTOCOL_DOCS`：`$AUN_SDK/docs/protocol`（AUN 协议详细文档）
+
+### 按需加载时机
+
+路径定义和实例文件**不自动加载**，仅在以下场景 Read：
+- 需要访问某个 `$名称` 但当前上下文中没有真实值
+- 需要寻找外部依赖位置
+- 用户要求注册或查看路径
+
+## 索引机制
+
+| 层 | 位置 | 维护者 | 写入权限 |
+|----|------|--------|----------|
+| evolclaw 级 | `$KITS_DOCS/INDEX.md` | 开发时维护 | 只读，过时时呈报用户 |
+| agent 级 | `$AGENT_INDEX/INDEX.md` | agent 会话 | 可写，直接更新 |
+
+agent 级索引范围：`$CURRENT_PROJECT` + `$AGENT_DIR`。
+
+触发时机：上述范围内有文档新增或较大幅度修改时，主动重建索引。
+
+## Bootstrap（独立使用 ECK 时）
+
+无 evolclaw 动态注入时，路径确定顺序：
+1. `$EVOLCLAW_HOME`：环境变量 → 默认 `~/.evolclaw`
+2. 读取 `$ECK/runtime.md` 获取基础路径和运行时参数
+3. 按派生规则构造其余路径
+
+参数加载优先级：evolclaw 动态注入 > 环境变量 > `$ECK/runtime.md` > 硬编码默认值。