evolclaw 3.0.0 → 3.1.1

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,72 @@
+# 私聊消息命令
+
+## 发送消息
+
+### 以指定 AID 发送（首选）
+
+```bash
+# 明文
+ec msg send <from-aid> <to-aid> "<message>"
+
+# 密文（E2EE）
+ec msg send <from-aid> <to-aid> "<message>" --encrypt
+```
+
+### 发送文件
+
+```bash
+ec msg send <from-aid> <to-aid> --file <path>
+ec msg send <from-aid> <to-aid> --file <path> --as image
+ec msg send <from-aid> <to-aid> --file <path> --encrypt
+```
+
+`--as` 可选值：`image` | `video` | `voice` | `file`（默认按扩展名推断）
+
+## 拉取消息
+
+```bash
+ec msg pull <self-aid> --app <app-name>
+ec msg pull <self-aid> --app <app-name> --after-seq <N> --limit <N>
+```
+
+## 确认消息已读
+
+```bash
+ec msg ack <self-aid> <seq> --app <app-name>
+```
+
+`--app` 必须传，否则会污染 daemon 游标。
+
+## 撤回消息
+
+```bash
+ec msg recall <self-aid> <message-id>
+```
+
+## 查询在线状态
+
+```bash
+ec msg online <self-aid> <target-aid>
+```
+
+## 自主回复策略
+
+收到消息 ≠ 必须回复。是否回复、怎么回复、何时回复由 agent 自主决定。
+
+加密策略：
+- 对端发来密文消息时，回复也应使用 `--encrypt`（保持对话加密一致性）
+- 对端发来明文消息时，默认明文回复
+
+## 在当前会话中快速回复（备选）
+
+仅当无法使用 `ec msg send` 时（如不知道自己的 AID），可用 `ec ctl send`：
+
+```bash
+# 明文
+ec ctl send "<text>"
+
+# 密文
+ec ctl send --encrypt "<text>"
+```
+
+`ec ctl send` 自动继承当前会话的 AID 和对端，无需指定。

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` > 硬编码默认值。

package/kits/rules/03-identity.md

@@ -0,0 +1,34 @@
+# 身份层：我是谁
+
+身份层包含当前 agent 的一切自我认知。动态注入的 `$SELF_AID` 和 `$SELF_NAME` 标识当前身份。
+
+## 数据位置
+
+| 位置 | 内容 |
+|------|------|
+| `$SELF_DIR`（`$AGENT_DIR/personal/`） | 个人数据（可写） |
+| `$KITS_DOCS/identity/` | 身份层详细规则（只读，按需加载） |
+
+## 数据结构
+
+| 文件 | 用途 |
+|------|------|
+| `persona.md` | 人格（行为规范、心理独白、身份认知） |
+| `memory/episodic.jsonl` | 事件性记忆（"我经历了什么"） |
+| `memory/semantic.md` | 语义性记忆（习得的事实/规律） |
+| `memory/working.md` | 当前关注（短期，每会话加载） |
+| `style.md` | 表达风格（用词偏好、句式偏好） |
+| `preferences.json` | 工具/模型/操作偏好 |
+| `skills/` | 技能清单（`_index.json` + 每技能一文件） |
+| `goals.md` | 长期目标 |
+| `journal.jsonl` | 反思日志（关键决策、自我修订） |
+
+## 行为规范加载
+
+```
+evolclaw 注入了当前 AID？
+  ├─ 是 → Read $SELF_DIR/persona.md，执行其中行为规范
+  └─ 否（coding 模式）→ 使用默认行为
+```
+
+不同 AID 可以有不同人格——切换身份即切换行为。

package/kits/rules/04-relation.md

@@ -0,0 +1,49 @@
+# 关系层：跟我聊天的是谁
+
+关系层管理你对所有对端的认知。动态注入的 `peerKey`（`<channel>#<urlEncode(peerId)>`）是对端在所有渠道中的稳定标识。`peerId` 是对端在当前渠道的原生 ID（AUN 是 AID，飞书是 user_id 等），`channel` 是当前渠道类型。
+
+## 数据位置
+
+| 位置 | 内容 |
+|------|------|
+| `$RELATIONS_DIR`（`$AGENT_DIR/relations/`） | 关系数据（可写） |
+| `$KITS_DOCS/relations/` | 关系层详细规则（只读，按需加载） |
+
+## 数据结构
+
+```
+relations/
+├── _index/                          名字反查索引
+│   └── name_<urlEncode(name)>.json    { "name": "王老板", "channel": "feishu", "peerId": "ou_xxx", "peerKey": "feishu#ou_xxx" }
+├── <channel>#<urlEncode(peerId)>/   每个对端一个目录（统一命名，不区分 contacts/_observed）
+│   ├── profile.md                     身份、关系评注、交互历史
+│   └── history.jsonl                  关系演化事件流
+└── _trash/                          merged/split 后的重定向占位
+```
+
+**例子**：
+- AUN 对端：`relations/aun#alice.aid.pub/`
+- 飞书对端：`relations/feishu#ou_xxx/`
+- 微信对端：`relations/wechat#wxid_xxx/`
+
+## 查找逻辑
+
+| 场景 | 路径 |
+|------|------|
+| 已知 channel + peerId | 直接拼路径 `relations/<channel>#<urlEncode(peerId)>/` |
+| 已知 name（如"给王老板发消息"） | 读 `_index/name_<urlEncode(name)>.json` 拿到 peerKey，再拼路径 |
+
+## 对端身份与权限
+
+| 身份 | 权限 |
+|------|------|
+| owner | 最高优先级，可改一切 |
+| admin | 可执行管理命令，不能改 owner |
+| guest | 基础对话 |
+| anonymous | 按配置决定是否响应 |
+
+兜底：无 token → coding 模式；token 残缺 → 按 anonymous 对待。
+
+## 详细规则
+
+关系层的详细规则（直接交互判定、merge/split、profile.md 完整格式）：Read `$KITS_DOCS/relations/` 中的相关文档。

package/kits/rules/05-venue.md

@@ -0,0 +1,45 @@
+# 环境层：我在什么场景下
+
+环境层决定当前会话加载哪些信息。动态注入的 `scene` 标识当前场景类型，`venueKey`（`<channel>#<urlEncode(venueId)>`）是 venue 在所有渠道中的稳定标识。
+
+## 场景判定
+
+| 场景 | 条件 | 加载的层 | 你的行为 |
+|------|------|----------|----------|
+| coding | 无 channel（无 token） | 仅 rules | 本地模式，每条消息都响应 |
+| private | 单聊 | rules + 身份层 + 关系层（对端）+ 环境层 + 渠道层 | 自主模式，通过 CLI 回复 |
+| group | 群聊 | rules + 身份层 + 关系层（群）+ 环境层 + 渠道层 | 自主模式，被 @ 才默认响应 |
+
+## 数据位置
+
+| 位置 | 内容 |
+|------|------|
+| `$VENUES_DIR`（`$AGENT_DIR/venues/`） | 环境数据（可写） |
+| `$KITS_DOCS/venues/` | 环境层详细规则（只读，按需加载） |
+
+## 数据结构
+
+```
+venues/
+├── <channel>#<urlEncode(venueId)>/  每个 venue 一个目录
+│   ├── profile.md                     定位、文化、policy
+│   └── history.jsonl                  venue 级事件
+└── _trash/
+```
+
+**例子**：
+- AUN 群组：`venues/aun#team-alpha.group.company.com/`
+- 飞书群：`venues/feishu#chat_xyz/`
+- 私聊：`venues/aun#alice.aid.pub/`（私聊的 venueId 通常是对端 ID）
+
+## Venue 类型
+
+| kind | 含义 | venueId 来源 |
+|------|------|--------------|
+| private | 一对一私聊 | 对端的渠道 ID |
+| group | 群聊 | 群的渠道 ID |
+| broadcast | 广播频道 | 频道 ID |
+
+## 详细规则
+
+环境层的详细规则（venue profile.md 完整格式、venueKey 编码、session_key）：Read `$KITS_DOCS/venues/` 中的相关文档。