evolcore 0.0.25 → 0.0.26

package/kits/rules/02-navigation.md

@@ -1,96 +1,96 @@
-# 导航：怎么找到我需要的信息
-
-## 路径体系
-
-### 三个基础路径
-
-| 路径 | 含义 |
-|------|------|
-| `$EVOLCORE_HOME` | 用户数据根。解析顺序：`EVOLCORE_HOME` 环境变量 → `~/.evolcore` |
-| `$PACKAGE_ROOT` | evolcore 包根目录（由 `getPackageRoot()` 从 `import.meta` 推出） |
-| `$CURRENT_PROJECT` | 当前工作目录 |
-
-### 派生路径
-
-以下是 ECK 真正认识的别名（`src/eck/manifest-engine.ts` 的 `buildPathMappings`）：
-
-| 名称 | 派生自 | 含义 |
-|------|--------|------|
-| `$KITS` | `$PACKAGE_ROOT/kits` | ECK 知识包根 |
-| `$KITS_RULES` | `$KITS/rules` | 自动载入部分（本目录） |
-| `$KITS_DOCS` | `$KITS/docs` | 按需载入文档 |
-| `$KITS_TEMPLATES` | `$KITS/templates` | prompt 模板 |
-| `$KITS_FRAGMENTS` | `$KITS_TEMPLATES/system-fragments` | system prompt fragment 模板 |
-| `$KITS_MESSAGE_FRAGMENTS` | `$KITS_TEMPLATES/message-fragments` | 逐条消息渲染的 fragment 模板 |
-| `$PERSONAL_DIR` | `$AGENT_DIR/personal` | 个人数据层（身份层） |
-| `$RELATIONS_DIR` | `$AGENT_DIR/relations` | 关系层 |
-| `$VENUES_DIR` | `$AGENT_DIR/venues` | 环境层（当前是死目录，见 `05-venue.md`） |
-| `$AGENT_DIR` | `$EVOLCORE_HOME/agents/<selfAid>` | 当前 agent 根（`selfAid` 为空时这四个别名都不注册） |
-
-> ⚠️ **只有上表这些别名能在 manifest 的 `path` 字段里用**。写成 `$SELF_DIR`（旧名）、
-> `$PEER_DIR`、`$AGENTS_DIR`、`$AGENT_INDEX`、`$ECK` 会被判为未解析变量，**整段静默丢弃**。
-
-下面这些只是**文档里的书写约定**，不是 ECK 能解析的别名，引用时要么写全路径要么当散文读：
-
-| 名称 | 实际位置 | 含义 |
-|------|----------|------|
-| `$ECK` | `$EVOLCORE_HOME/eck` | 运行时配置实例（见下文 Bootstrap 的告警） |
-| `$AGENTS_DIR` | `$EVOLCORE_HOME/agents` | per-agent 数据根 |
-| `$AGENT_INDEX` | `$AGENT_DIR/index` | agent 级文档索引 |
-| `$PEER_DIR` | `$RELATIONS_DIR/<peerKey>` | 当前对端的关系目录 |
-
-## 路径注册表机制
-
-路径用 `$名称` 引用，不写死实际路径。
-
-### 三层结构
-
-| 层 | 位置 | 性质 | 内容 |
-|----|------|------|------|
-| 机制描述 | 本文件 | 只读 | 语法、规则 |
-| 路径定义 | `$KITS_DOCS/path-registry.md` | 只读，按需加载 | 所有路径的派生规则或寻找规则 |
-| 路径实例 | `$ECK/path-registry.md` | 可变，按需加载 | 已解析的真实值 + 用户自定义路径 |
-
-### 两类路径
-
-- **可直接派生**：从基础路径按固定规则算出（如 `$KITS = $PACKAGE_ROOT/kits`）
-- **不可直接派生**：需按寻找规则搜索。例如：
-  - `$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/` 目录**
-
-### 按需加载时机
-
-路径定义和实例文件**不自动加载**，仅在以下场景 Read：
-- 需要访问某个 `$名称` 但当前上下文中没有真实值
-- 需要寻找外部依赖位置
-- 用户要求注册或查看路径
-
-## 索引机制
-
-| 层 | 位置 | 维护者 | 写入权限 |
-|----|------|--------|----------|
-| evolcore 级 | `$KITS_DOCS/INDEX.md` | 开发时维护 | 只读，过时时呈报用户 |
-| agent 级 | `$AGENT_INDEX/INDEX.md` | agent 会话 | 可写，直接更新 |
-
-agent 级索引范围：`$CURRENT_PROJECT` + `$AGENT_DIR`。
-
-触发时机：上述范围内有文档新增或较大幅度修改时，主动重建索引。
-
-## Bootstrap（独立使用 ECK 时）
-
-无 evolcore 动态注入时，路径确定顺序：
-1. `$EVOLCORE_HOME`：环境变量 → `~/.evolcore`
-2. `$PACKAGE_ROOT`：evolcore 安装目录（dev 模式下可能与上一步同一个目录）
-3. 按上面的派生规则构造其余路径
-
-> ⚠️ **不要指望 `$ECK/runtime.md` 和 `$ECK/path-registry.md`**。这两个文件由
-> `src/eck/init.ts` **写一次就不再更新**（`if (fs.existsSync(file)) return`），而且只渲染
-> `EVOLCORE_HOME` / `PACKAGE_ROOT` 两个变量，其余 `{{...}}` 占位符会原样留在文件里；
-> 源码中也**没有任何地方读回它们**。本机这两个文件仍是 evolclaw 时代生成的，
-> 里面写着 `$EVOLCLAW_HOME | /home/evolclaw`。要真实路径就按上面 1-3 步自己算，
-> 或直接读 `src/paths.ts`。
-
-参数加载优先级：evolcore 动态注入 > 环境变量 > 硬编码默认值。
+# 导航：怎么找到我需要的信息
+
+## 路径体系
+
+### 三个基础路径
+
+| 路径 | 含义 |
+|------|------|
+| `$EVOLCORE_HOME` | 用户数据根。解析顺序：`EVOLCORE_HOME` 环境变量 → `~/.evolcore` |
+| `$PACKAGE_ROOT` | evolcore 包根目录（由 `getPackageRoot()` 从 `import.meta` 推出） |
+| `$CURRENT_PROJECT` | 当前工作目录 |
+
+### 派生路径
+
+以下是 ECK 真正认识的别名（`src/eck/manifest-engine.ts` 的 `buildPathMappings`）：
+
+| 名称 | 派生自 | 含义 |
+|------|--------|------|
+| `$KITS` | `$PACKAGE_ROOT/kits` | ECK 知识包根 |
+| `$KITS_RULES` | `$KITS/rules` | 自动载入部分（本目录） |
+| `$KITS_DOCS` | `$KITS/docs` | 按需载入文档 |
+| `$KITS_TEMPLATES` | `$KITS/templates` | prompt 模板 |
+| `$KITS_FRAGMENTS` | `$KITS_TEMPLATES/system-fragments` | system prompt fragment 模板 |
+| `$KITS_MESSAGE_FRAGMENTS` | `$KITS_TEMPLATES/message-fragments` | 逐条消息渲染的 fragment 模板 |
+| `$PERSONAL_DIR` | `$AGENT_DIR/personal` | 个人数据层（身份层） |
+| `$RELATIONS_DIR` | `$AGENT_DIR/relations` | 关系层 |
+| `$VENUES_DIR` | `$AGENT_DIR/venues` | 环境层（当前是死目录，见 `05-venue.md`） |
+| `$AGENT_DIR` | `$EVOLCORE_HOME/agents/<selfAid>` | 当前 agent 根（`selfAid` 为空时这四个别名都不注册） |
+
+> ⚠️ **只有上表这些别名能在 manifest 的 `path` 字段里用**。写成 `$SELF_DIR`（旧名）、
+> `$PEER_DIR`、`$AGENTS_DIR`、`$AGENT_INDEX`、`$ECK` 会被判为未解析变量，**整段静默丢弃**。
+
+下面这些只是**文档里的书写约定**，不是 ECK 能解析的别名，引用时要么写全路径要么当散文读：
+
+| 名称 | 实际位置 | 含义 |
+|------|----------|------|
+| `$ECK` | `$EVOLCORE_HOME/eck` | 运行时配置实例（见下文 Bootstrap 的告警） |
+| `$AGENTS_DIR` | `$EVOLCORE_HOME/agents` | per-agent 数据根 |
+| `$AGENT_INDEX` | `$AGENT_DIR/index` | agent 级文档索引 |
+| `$PEER_DIR` | `$RELATIONS_DIR/<peerKey>` | 当前对端的关系目录 |
+
+## 路径注册表机制
+
+路径用 `$名称` 引用，不写死实际路径。
+
+### 三层结构
+
+| 层 | 位置 | 性质 | 内容 |
+|----|------|------|------|
+| 机制描述 | 本文件 | 只读 | 语法、规则 |
+| 路径定义 | `$KITS_DOCS/path-registry.md` | 只读，按需加载 | 所有路径的派生规则或寻找规则 |
+| 路径实例 | `$ECK/path-registry.md` | 可变，按需加载 | 已解析的真实值 + 用户自定义路径 |
+
+### 两类路径
+
+- **可直接派生**：从基础路径按固定规则算出（如 `$KITS = $PACKAGE_ROOT/kits`）
+- **不可直接派生**：需按寻找规则搜索。例如：
+  - `$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/` 目录**
+
+### 按需加载时机
+
+路径定义和实例文件**不自动加载**，仅在以下场景 Read：
+- 需要访问某个 `$名称` 但当前上下文中没有真实值
+- 需要寻找外部依赖位置
+- 用户要求注册或查看路径
+
+## 索引机制
+
+| 层 | 位置 | 维护者 | 写入权限 |
+|----|------|--------|----------|
+| evolcore 级 | `$KITS_DOCS/INDEX.md` | 开发时维护 | 只读，过时时呈报用户 |
+| agent 级 | `$AGENT_INDEX/INDEX.md` | agent 会话 | 可写，直接更新 |
+
+agent 级索引范围：`$CURRENT_PROJECT` + `$AGENT_DIR`。
+
+触发时机：上述范围内有文档新增或较大幅度修改时，主动重建索引。
+
+## Bootstrap（独立使用 ECK 时）
+
+无 evolcore 动态注入时，路径确定顺序：
+1. `$EVOLCORE_HOME`：环境变量 → `~/.evolcore`
+2. `$PACKAGE_ROOT`：evolcore 安装目录（dev 模式下可能与上一步同一个目录）
+3. 按上面的派生规则构造其余路径
+
+> ⚠️ **不要指望 `$ECK/runtime.md` 和 `$ECK/path-registry.md`**。这两个文件由
+> `src/eck/init.ts` **写一次就不再更新**（`if (fs.existsSync(file)) return`），而且只渲染
+> `EVOLCORE_HOME` / `PACKAGE_ROOT` 两个变量，其余 `{{...}}` 占位符会原样留在文件里；
+> 源码中也**没有任何地方读回它们**。本机这两个文件仍是 evolclaw 时代生成的，
+> 里面写着 `$EVOLCLAW_HOME | /home/evolclaw`。要真实路径就按上面 1-3 步自己算，
+> 或直接读 `src/paths.ts`。
+
+参数加载优先级：evolcore 动态注入 > 环境变量 > 硬编码默认值。

package/kits/rules/03-identity.md

@@ -1,40 +1,40 @@
-# 身份层：我是谁
-
-身份层是当前 agent 的自我认知。ECK 在 identity fragment 注入 `selfAid`（当前 AID），
-并把 `$EVOLCORE_HOME/AIDs/<aid>/agent.md` frontmatter 的 `name` 投影为 `selfName`。
-`selfName` 仅用于展示，名片缺失或尚未拉取完成时可能为空；身份与授权判断必须使用 `selfAid`。
-
-## 数据位置
-
-| 位置 | 内容 |
-|------|------|
-| `$PERSONAL_DIR`（`$AGENT_DIR/personal/`） | 个人数据（可写） |
-| `$KITS_DOCS/identity/` | 身份层详细规则（只读，按需加载） |
-
-> manifest 模板里只认 `$PERSONAL_DIR` / `$RELATIONS_DIR` / `$VENUES_DIR` / `$AGENT_DIR` 这几个路径别名。
-> 写成 `$SELF_DIR` 会被判为未解析变量，**整段静默丢弃**。
-
-## 数据结构（以源码实际读写为准）
-
-| 路径 | 用途 | 实际状态 |
-|------|------|----------|
+# 身份层：我是谁
+
+身份层是当前 agent 的自我认知。ECK 在 identity fragment 注入 `selfAid`（当前 AID），
+并把 `$EVOLCORE_HOME/AIDs/<aid>/agent.md` frontmatter 的 `name` 投影为 `selfName`。
+`selfName` 仅用于展示，名片缺失或尚未拉取完成时可能为空；身份与授权判断必须使用 `selfAid`。
+
+## 数据位置
+
+| 位置 | 内容 |
+|------|------|
+| `$PERSONAL_DIR`（`$AGENT_DIR/personal/`） | 个人数据（可写） |
+| `$KITS_DOCS/identity/` | 身份层详细规则（只读，按需加载） |
+
+> manifest 模板里只认 `$PERSONAL_DIR` / `$RELATIONS_DIR` / `$VENUES_DIR` / `$AGENT_DIR` 这几个路径别名。
+> 写成 `$SELF_DIR` 会被判为未解析变量，**整段静默丢弃**。
+
+## 数据结构（以源码实际读写为准）
+
+| 路径 | 用途 | 实际状态 |
+|------|------|----------|
 | `persona.md` | 人格（行为规范、身份认知） | evolcore 自动注入；通过 `ec agent persona` 读写 |
 | `personal.md` | 个人资料与工作背景 | evolcore 自动注入；当前 Agent 在 owner 权限下可直接编辑 |
-| `memory/working.md` | 当前关注（短期） | evolcore 自动注入 |
-| `preferences/active-preferences.md` | 已确认的稳定用户偏好 | **仅私聊**注入；由用户态 trigger 维护 |
-| `preferences/stats.json`、`preferences/preferences-conflicts.md` | 偏好计分状态与冲突记录 | trigger 私有，无 schema 保证 |
-| `memory/`、`skills/` 目录 | 预留 | 会被创建，但目前无人读写 |
-
-`memory/episodic.jsonl`、`memory/semantic.md`、`style.md`、`preferences.json`、`goals.md`、`journal.jsonl`
-是早期设计稿里的约定，**源码尚未实现读写**——不要假设写了就会生效。
-
-## 人格与行为规范怎么生效
-
-- **注入条件**是 `chatType ≠ null` 且 `lifecycle = active`（即处于正常运行阶段的渠道会话），不是"有没有注入 AID"。生命周期变量缺失时按 `active` 处理；非法生命周期仍失败关闭。本地 coding 模式也不注入。
-- persona.md 由 evolcore **自动前置**进 system prompt，你不需要主动 Read。
+| `memory/working.md` | 当前关注（短期） | evolcore 自动注入 |
+| `preferences/active-preferences.md` | 已确认的稳定用户偏好 | **仅私聊**注入；由用户态 trigger 维护 |
+| `preferences/stats.json`、`preferences/preferences-conflicts.md` | 偏好计分状态与冲突记录 | trigger 私有，无 schema 保证 |
+| `memory/`、`skills/` 目录 | 预留 | 会被创建，但目前无人读写 |
+
+`memory/episodic.jsonl`、`memory/semantic.md`、`style.md`、`preferences.json`、`goals.md`、`journal.jsonl`
+是早期设计稿里的约定，**源码尚未实现读写**——不要假设写了就会生效。
+
+## 人格与行为规范怎么生效
+
+- **注入条件**是 `chatType ≠ null` 且 `lifecycle = active`（即处于正常运行阶段的渠道会话），不是"有没有注入 AID"。生命周期变量缺失时按 `active` 处理；非法生命周期仍失败关闭。本地 coding 模式也不注入。
+- persona.md 由 evolcore **自动前置**进 system prompt，你不需要主动 Read。
 - persona.md 缺失时**没有默认人格兜底**，只是这一段不出现；行为约束改由 `kits/rules/` + `roles/` 权限定义承担。
 - personal.md 缺失时跳过注入；文件位于 `$PERSONAL_DIR/personal.md`。人格文件 `persona.md` 通过 `ec agent persona show`、`ec agent persona --text <text>` 或 `ec agent persona --file <path>` 管理，修改后按 mtime 自动刷新（必要时可 `ec agent reload`）。
-- 改完 persona.md 后 `ec agent reload` 生效（mtime 门控缓存）。
-- `agents/<aid>/behavior.json` 是**已废弃**的旧配置（基座/模型/权限模式已并入 `config.json`），与人格无关。
-
-不同 AID 可以有不同 persona——切换身份即切换人格。
+- 改完 persona.md 后 `ec agent reload` 生效（mtime 门控缓存）。
+- `agents/<aid>/behavior.json` 是**已废弃**的旧配置（基座/模型/权限模式已并入 `config.json`），与人格无关。
+
+不同 AID 可以有不同 persona——切换身份即切换人格。

package/kits/rules/04-relation.md

@@ -1,75 +1,75 @@
-# 关系层：跟我聊天的是谁
-
-关系层管理你对所有对端的认知。动态注入的 `peerKey`（`<channel>#<urlEncode(peerId)>`）是对端在所有渠道中的稳定标识。`peerId` 是对端在当前渠道的原生 ID（AUN 是 AID，飞书是 user_id 等），`channel` 是当前渠道类型。
-
-**对端包括群**：AID 四类型（human/agent/group/service，见 `01-overview.md`）对你而言都是对端，数据都在关系层。
-- 私聊：`peerId` = 对端 ID，`peerKey` = `<channel>#<对端ID>`。
-- 群聊：`peerId` = **群 ID**（群本身的 AID / 渠道群 ID），群内所有发言者共用同一个 `peerKey`（群的键）。群规则、群 profile 等**具体群实例数据**落 `$RELATIONS_DIR/<peerKey>/`（如群规则物化到 `relations/<peerKey>/rules.md`）。
-
-> 为什么用 `peerId` 而非直接用 AID：非 AUN 渠道的对端（飞书群、微信）没有 AID，用 `<channel>#<peerId>` 才能统一覆盖所有渠道的对端。
-
-relation fragment 注入的全部变量：`peerKey`、`peerId`、`peerName`、`peerRole`、`peerType`，
-群聊另有 `groupId`、`groupRulesStatus`、`groupRulesError`。`groupRulesStatus=ignored` 表示本轮由
-本地 `groupRules.mode=ignore` 主动跳过，不是远端缺失、无权限或同步失败。
-
-## 数据位置
-
-关系数据（可写）在 `$RELATIONS_DIR`（= `$AGENT_DIR/relations/`）。
-
-## 数据结构（以源码实际读写为准）
-
-```
-relations/
-└── <channel>#<urlEncode(peerId)>/   每个对端一个目录
-    ├── peer-identity.json             身份快照缓存（PeerIdentityCache 唯一的写入方）
-    ├── config.json                    关系级配置——**对端角色 config.role 就存在这里**；群可覆盖 groupRules.mode
-    └── rules.md                       仅群目录：校验通过后物化的群规则字节
-```
-
-群规则加载策略按 Agent `config.json` → 当前群 relation `config.json` 覆盖，缺省为 `load`。当有效值为
-`ignore` 时，本轮不访问远端规则、不读取本地 `rules.md`、不暴露 `groupRulesPath`；旧文件保留但不
-作为回退来源。该字段仅当前 Agent 的实际 `owner` 关系角色可修改，其他角色可读取当前 relation 的有效值。
-
-**例子**：
-- AUN 对端：`relations/aun#alice.agentid.pub/`
-- 飞书对端：`relations/feishu#ou_xxx/`
-- 微信对端：`relations/wechat#wxid_xxx/`
-
-**下列条目只是设计稿，源码尚未实现——不要假设读了/写了会生效**：
-
-| 条目 | 真实状态 |
-|------|----------|
-| `<peerKey>/profile.md` | manifest 通过统一的 `peer-profile` 槽加载（缺失即跳过），群聊和私聊不再重复声明；目前**没有任何代码写它**，可以手写一份供上下文加载 |
-| `_index/name_<name>.json` 名字反查索引 | 目录会被创建，但**无任何读写代码**，磁盘上全是空目录。"已知 name 反查 peerKey" 这条路走不通 |
-| `<peerKey>/history.jsonl` | 关系层无此实现（同名文件都属于 handoff / trigger / CC 自己的历史） |
-| `_trash/` | 只创建目录，没有 merge/split 重定向逻辑 |
-| `relations/contacts/`、`relations/_observed/` | 目录骨架仍在创建这两个旧结构（`ensureAgentDirSkeleton`），但已不再使用，都是空的 |
-| `<peerKey>/behavior.json` | 旧配置残留，已并入 `config.json` |
-
-## 查找逻辑
-
-已知 channel + peerId → 直接拼 `relations/<channel>#<urlEncode(peerId)>/`。这是**唯一可用的查找路径**；
-只知道名字（"给王老板发消息"）时没有索引可查，用 `ec aid`/联系人命令或直接问用户。
-
-## 对端身份与权限
-
-四个内置角色（rank 从高到低）+ 自定义角色 + `none`：
-
-| 身份 | rank | 默认 permissionMode | 权限 |
-|------|------|--------------------|------|
-| owner | 900 | `bypass` | agent 级最高关系权限，可执行 agent 管理和 owner 审批 |
-| admin | 700 | `request` | agent 管理权限，不能修改 owner，危险操作向 owner 申请审批 |
-| member | 300 | `auto` | 任务型普通成员 |
-| visitor | 100 | `readonly` | 只读角色，且是**强制保留角色**（兜底用） |
-| 自定义角色 | 按配置 | 缺失/非法时安全兜底 **`readonly`** | 按 agent 角色模板定义 |
-| none | — | — | 无有效关系角色，拒绝访问 |
-
-角色实际存储在 `relations/<peerKey>/config.json` 的 `role` 字段。进程级 `daemon-owner` 与这里的
-Agent/relation 角色正交，不会在 auth 层提升为 `owner`；只有 Agent 自身的 owner 配置和关系解析
-结果可以授予 `owner`。DaemonOwner 仅获得明确列入进程控制面的操作权限。
-
-**兜底链**：无匹配角色 → 回落内置 `visitor`（即 `readonly`）；只有角色注册表本身缺失、
-或 `visitor` 未注册时才落到 `none` 拒绝访问。所以正常配置下几乎总是降权到只读，而不是拒绝。
-
-> permissionMode 的合法取值只有 `readonly` / `auto` / `request` / `bypass` 四个。
-> "coding" 是**场景**名（无渠道的本地会话，见 `05-venue.md`），**不是** permissionMode。
+# 关系层：跟我聊天的是谁
+
+关系层管理你对所有对端的认知。动态注入的 `peerKey`（`<channel>#<urlEncode(peerId)>`）是对端在所有渠道中的稳定标识。`peerId` 是对端在当前渠道的原生 ID（AUN 是 AID，飞书是 user_id 等），`channel` 是当前渠道类型。
+
+**对端包括群**：AID 四类型（human/agent/group/service，见 `01-overview.md`）对你而言都是对端，数据都在关系层。
+- 私聊：`peerId` = 对端 ID，`peerKey` = `<channel>#<对端ID>`。
+- 群聊：`peerId` = **群 ID**（群本身的 AID / 渠道群 ID），群内所有发言者共用同一个 `peerKey`（群的键）。群规则、群 profile 等**具体群实例数据**落 `$RELATIONS_DIR/<peerKey>/`（如群规则物化到 `relations/<peerKey>/rules.md`）。
+
+> 为什么用 `peerId` 而非直接用 AID：非 AUN 渠道的对端（飞书群、微信）没有 AID，用 `<channel>#<peerId>` 才能统一覆盖所有渠道的对端。
+
+relation fragment 注入的全部变量：`peerKey`、`peerId`、`peerName`、`peerRole`、`peerType`，
+群聊另有 `groupId`、`groupRulesStatus`、`groupRulesError`。`groupRulesStatus=ignored` 表示本轮由
+本地 `groupRules.mode=ignore` 主动跳过，不是远端缺失、无权限或同步失败。
+
+## 数据位置
+
+关系数据（可写）在 `$RELATIONS_DIR`（= `$AGENT_DIR/relations/`）。
+
+## 数据结构（以源码实际读写为准）
+
+```
+relations/
+└── <channel>#<urlEncode(peerId)>/   每个对端一个目录
+    ├── peer-identity.json             身份快照缓存（PeerIdentityCache 唯一的写入方）
+    ├── config.json                    关系级配置——**对端角色 config.role 就存在这里**；群可覆盖 groupRules.mode
+    └── rules.md                       仅群目录：校验通过后物化的群规则字节
+```
+
+群规则加载策略按 Agent `config.json` → 当前群 relation `config.json` 覆盖，缺省为 `load`。当有效值为
+`ignore` 时，本轮不访问远端规则、不读取本地 `rules.md`、不暴露 `groupRulesPath`；旧文件保留但不
+作为回退来源。该字段仅当前 Agent 的实际 `owner` 关系角色可修改，其他角色可读取当前 relation 的有效值。
+
+**例子**：
+- AUN 对端：`relations/aun#alice.agentid.pub/`
+- 飞书对端：`relations/feishu#ou_xxx/`
+- 微信对端：`relations/wechat#wxid_xxx/`
+
+**下列条目只是设计稿，源码尚未实现——不要假设读了/写了会生效**：
+
+| 条目 | 真实状态 |
+|------|----------|
+| `<peerKey>/profile.md` | manifest 通过统一的 `peer-profile` 槽加载（缺失即跳过），群聊和私聊不再重复声明；目前**没有任何代码写它**，可以手写一份供上下文加载 |
+| `_index/name_<name>.json` 名字反查索引 | 目录会被创建，但**无任何读写代码**，磁盘上全是空目录。"已知 name 反查 peerKey" 这条路走不通 |
+| `<peerKey>/history.jsonl` | 关系层无此实现（同名文件都属于 handoff / trigger / CC 自己的历史） |
+| `_trash/` | 只创建目录，没有 merge/split 重定向逻辑 |
+| `relations/contacts/`、`relations/_observed/` | 目录骨架仍在创建这两个旧结构（`ensureAgentDirSkeleton`），但已不再使用，都是空的 |
+| `<peerKey>/behavior.json` | 旧配置残留，已并入 `config.json` |
+
+## 查找逻辑
+
+已知 channel + peerId → 直接拼 `relations/<channel>#<urlEncode(peerId)>/`。这是**唯一可用的查找路径**；
+只知道名字（"给王老板发消息"）时没有索引可查，用 `ec aid`/联系人命令或直接问用户。
+
+## 对端身份与权限
+
+四个内置角色（rank 从高到低）+ 自定义角色 + `none`：
+
+| 身份 | rank | 默认 permissionMode | 权限 |
+|------|------|--------------------|------|
+| owner | 900 | `bypass` | agent 级最高关系权限，可执行 agent 管理和 owner 审批 |
+| admin | 700 | `request` | agent 管理权限，不能修改 owner，危险操作向 owner 申请审批 |
+| member | 300 | `auto` | 任务型普通成员 |
+| visitor | 100 | `readonly` | 只读角色，且是**强制保留角色**（兜底用） |
+| 自定义角色 | 按配置 | 缺失/非法时安全兜底 **`readonly`** | 按 agent 角色模板定义 |
+| none | — | — | 无有效关系角色，拒绝访问 |
+
+角色实际存储在 `relations/<peerKey>/config.json` 的 `role` 字段。进程级 `daemon-owner` 与这里的
+Agent/relation 角色正交，不会在 auth 层提升为 `owner`；只有 Agent 自身的 owner 配置和关系解析
+结果可以授予 `owner`。DaemonOwner 仅获得明确列入进程控制面的操作权限。
+
+**兜底链**：无匹配角色 → 回落内置 `visitor`（即 `readonly`）；只有角色注册表本身缺失、
+或 `visitor` 未注册时才落到 `none` 拒绝访问。所以正常配置下几乎总是降权到只读，而不是拒绝。
+
+> permissionMode 的合法取值只有 `readonly` / `auto` / `request` / `bypass` 四个。
+> "coding" 是**场景**名（无渠道的本地会话，见 `05-venue.md`），**不是** permissionMode。

package/kits/rules/05-venue.md

@@ -1,60 +1,60 @@
-# 环境层：当前对话场景
-
-环境层决定当前会话加载哪些信息。ECK 在 venue fragment 注入的环境层变量：
-
-| 变量 | 取值 | 说明 |
-|------|------|------|
-| `chatType` | `private` / `group` / null | null = 无渠道的本地 coding 会话 |
-| `mentionMode` | `mention-only` / `disabled` | 群内响应策略；取 agent/relation 配置，缺省时使用群服务器下发的 `mention_mode` |
-| `clientType` | `desktop` / `web` / `mobile` | 有值时额外加载客户端场景文档 |
-| `permissionMode` | readonly/auto/request/bypass | 当前生效权限模式 |
-| `venueUid` | 恒为 undefined | 声明了但源码固定不填，模板有 `{{?}}` 守卫所以永不渲染——**不要依赖它** |
-
-## 场景判定
-
-命中哪些段由 `kits/eck_manifest.json` 的 `when` 条件决定，不是写死的分支：
-
-| 场景 | 条件 | 加载的段 | 你的行为 |
-|------|------|----------|----------|
-| coding | `chatType = null` 且 `lifecycle = active` | rules + 会话层 + baseagent | 本地模式，每条消息都响应 |
-| private | `chatType = private` 且 `lifecycle = active` | 上述 + 身份层（含 persona/working-memory/**preferences**）+ 关系层（对端 profile）+ 环境层 + 渠道层 + commands | 自主模式，回复方式随 `chatMode` |
-| group | `chatType = group` 且 `lifecycle = active` | 同 private，但**无 preferences**；`groupId` 有值加群 profile，`groupRulesPath` 有值加群规则 | 自主模式，`mentionMode` 决定是否响应 |
-| bootstrapping | `lifecycle = bootstrapping` | 仅 bootstrap 引导（所有常规段均落选） | 初始化引导 |
-
-> coding 场景在 agent `active` 时加载 `session` 与 `baseagent`；生命周期缺失按 `active` 处理，非法时按 fail-closed 处理。
-
-## 数据位置
-
-| 位置 | 内容 |
-|------|------|
-| `$KITS_DOCS/venues/` | 环境层场景文档（只读，按需加载）：`private.md` `group.md` `<channel>-<chatType>.md` `client-*.md` |
-| `$VENUES_DIR`（`$AGENT_DIR/venues/`） | **目前是死目录**：会被创建（含 `_index/` `_trash/`），但源码里 `agentVenuesDir()` 零调用点，无人读写 |
-
-> `venues/` 下若有 `aun#<group-aid>` 之类的实例目录，是已删除模块 `group-venue-sync.ts` 的历史残留，
-> 不再有效——群规则现在走关系层（见下文）。
-
-> **重要**：环境层承载比"单个群/私聊实例"更高的抽象（如组织、类型级共性），**不为具体群/私聊实例建目录**。
-> 具体群实例的数据（如群规则 `rules.md`、群 profile）落**关系层** `$RELATIONS_DIR/<peerKey>/`。
-
-## Venue 类型抽象
-
-环境层关注的是**类型**，而非具体实例。类型只有 `private` 和 `group` 两种（即 `chatType` 的两个非空取值）——
-没有 `broadcast` 这个 venue 类型；群响应策略统一由 `mentionMode` 表达。
-
-"张三所在的 team-alpha 这个**具体群**"不属于环境层，它是关系层的对端实例，数据落 `relations/<peerKey>/`。
-
-## 群规则（关系层数据）
-
-AUN 群规则文件固定来自 `<group-aid>:/rules.md`。EvolCore 先读取 signed `rules.content`
-元信息并用远端 stat 的 `size + mtimeMs` 校验 `/rules.md`，一致后把远端字节原样物化到
-**`$RELATIONS_DIR/<peerKey>/rules.md`**（群的 peerKey = `aun#<group-aid>`）并通过 manifest 注入。
-群规则可定义本群特有的工作流程、职责分工、交付格式、禁区和升级路径；当群规则与通用规则冲突时，
-优先遵守群规则，但不能越过系统安全、权限和用户明确指令。
-
-其它群资源不预先注入，需要时用 `ec fs ls/find/stat/cat <group-aid>:/...` 查询。
-不要把本地残留的 `rules.md` 当作权威源；只有本轮校验通过并暴露 `groupRulesPath` 时才使用。
-
-本地有效配置 `groupRules.mode` 决定是否进入上述流程：relation 值覆盖 Agent 值，缺省为 `load`。
-`ignore` 时返回 `groupRulesStatus=ignored`，且不访问远端规则、不读取本地物化文件、不设置
-`groupRulesPath`，因此不会注入正文。切换配置不会自动清空或新建 base agent 会话；配置提交后开始
-处理的新 turn 使用新策略。
+# 环境层：当前对话场景
+
+环境层决定当前会话加载哪些信息。ECK 在 venue fragment 注入的环境层变量：
+
+| 变量 | 取值 | 说明 |
+|------|------|------|
+| `chatType` | `private` / `group` / null | null = 无渠道的本地 coding 会话 |
+| `mentionMode` | `mention-only` / `disabled` | 群内响应策略；取 agent/relation 配置，缺省时使用群服务器下发的 `mention_mode` |
+| `clientType` | `desktop` / `web` / `mobile` | 有值时额外加载客户端场景文档 |
+| `permissionMode` | readonly/auto/request/bypass | 当前生效权限模式 |
+| `venueUid` | 恒为 undefined | 声明了但源码固定不填，模板有 `{{?}}` 守卫所以永不渲染——**不要依赖它** |
+
+## 场景判定
+
+命中哪些段由 `kits/eck_manifest.json` 的 `when` 条件决定，不是写死的分支：
+
+| 场景 | 条件 | 加载的段 | 你的行为 |
+|------|------|----------|----------|
+| coding | `chatType = null` 且 `lifecycle = active` | rules + 会话层 + baseagent | 本地模式，每条消息都响应 |
+| private | `chatType = private` 且 `lifecycle = active` | 上述 + 身份层（含 persona/working-memory/**preferences**）+ 关系层（对端 profile）+ 环境层 + 渠道层 + commands | 自主模式，回复方式随 `chatMode` |
+| group | `chatType = group` 且 `lifecycle = active` | 同 private，但**无 preferences**；`groupId` 有值加群 profile，`groupRulesPath` 有值加群规则 | 自主模式，`mentionMode` 决定是否响应 |
+| bootstrapping | `lifecycle = bootstrapping` | 仅 bootstrap 引导（所有常规段均落选） | 初始化引导 |
+
+> coding 场景在 agent `active` 时加载 `session` 与 `baseagent`；生命周期缺失按 `active` 处理，非法时按 fail-closed 处理。
+
+## 数据位置
+
+| 位置 | 内容 |
+|------|------|
+| `$KITS_DOCS/venues/` | 环境层场景文档（只读，按需加载）：`private.md` `group.md` `<channel>-<chatType>.md` `client-*.md` |
+| `$VENUES_DIR`（`$AGENT_DIR/venues/`） | **目前是死目录**：会被创建（含 `_index/` `_trash/`），但源码里 `agentVenuesDir()` 零调用点，无人读写 |
+
+> `venues/` 下若有 `aun#<group-aid>` 之类的实例目录，是已删除模块 `group-venue-sync.ts` 的历史残留，
+> 不再有效——群规则现在走关系层（见下文）。
+
+> **重要**：环境层承载比"单个群/私聊实例"更高的抽象（如组织、类型级共性），**不为具体群/私聊实例建目录**。
+> 具体群实例的数据（如群规则 `rules.md`、群 profile）落**关系层** `$RELATIONS_DIR/<peerKey>/`。
+
+## Venue 类型抽象
+
+环境层关注的是**类型**，而非具体实例。类型只有 `private` 和 `group` 两种（即 `chatType` 的两个非空取值）——
+没有 `broadcast` 这个 venue 类型；群响应策略统一由 `mentionMode` 表达。
+
+"张三所在的 team-alpha 这个**具体群**"不属于环境层，它是关系层的对端实例，数据落 `relations/<peerKey>/`。
+
+## 群规则（关系层数据）
+
+AUN 群规则文件固定来自 `<group-aid>:/rules.md`。EvolCore 先读取 signed `rules.content`
+元信息并用远端 stat 的 `size + mtimeMs` 校验 `/rules.md`，一致后把远端字节原样物化到
+**`$RELATIONS_DIR/<peerKey>/rules.md`**（群的 peerKey = `aun#<group-aid>`）并通过 manifest 注入。
+群规则可定义本群特有的工作流程、职责分工、交付格式、禁区和升级路径；当群规则与通用规则冲突时，
+优先遵守群规则，但不能越过系统安全、权限和用户明确指令。
+
+其它群资源不预先注入，需要时用 `ec fs ls/find/stat/cat <group-aid>:/...` 查询。
+不要把本地残留的 `rules.md` 当作权威源；只有本轮校验通过并暴露 `groupRulesPath` 时才使用。
+
+本地有效配置 `groupRules.mode` 决定是否进入上述流程：relation 值覆盖 Agent 值，缺省为 `load`。
+`ignore` 时返回 `groupRulesStatus=ignored`，且不访问远端规则、不读取本地物化文件、不设置
+`groupRulesPath`，因此不会注入正文。切换配置不会自动清空或新建 base agent 会话；配置提交后开始
+处理的新 turn 使用新策略。