evolcore 0.0.1 → 0.0.3

package/kits/docs/prompt-loading-architecture.md

@@ -0,0 +1,266 @@
+# EvolCore 提示词装载全景（Prompt Loading Architecture）
+
+> 文档范围：消息从渠道到 base agent 的完整提示词装载流程，涵盖系统提示词渲染层与消息渲染层两套机制。
+> 最后更新：2026-06-04
+
+---
+
+## 总体数据流
+
+```
+收到一条消息
+       │
+       ▼
+┌──────────────────────────────────────────────────────────┐
+│  MessageBridge                                           │
+│  • 消息预处理（去重/拦截/chatType 填充）                   │
+│  • messagePrefix 硬编码已移除（归消息渲染层）              │
+│  • 构造 Message（含 items=undefined 此时）                │
+└──────────────────────┬───────────────────────────────────┘
+                       │
+                       ▼
+┌──────────────────────────────────────────────────────────┐
+│  MessageQueue                                            │
+│  • 去重 / 单聊 interrupt / 群聊 FIFO                     │
+│  • dequeueGreedy：弹出连续同 peerId 消息                  │
+│  • mergeItems（多条时）：                                 │
+│    - content = join('\n')（兜底）                        │
+│    - items[] = 每条 SubMessage{peer,time,images,...}     │
+│    - images/mentions 扁平合并（给 runQuery 的总量）       │
+└──────────────────────┬───────────────────────────────────┘
+                       │ Message（可能带 items[]）
+                       ▼
+┌──────────────────────────────────────────────────────────┐
+│  MessageProcessor.processMessage()                       │
+│                                                          │
+│  ① wrapPrompt 准备（中断包装函数）                        │
+│     effectivePrompt = wrapPrompt(message.content) ← 兜底 │
+│                                                          │
+│  ② 构造 kitCtx.vars（~47 个变量，见下节）                 │
+│                                                          │
+│  ③ 系统提示词渲染层                                       │
+│     renderKitSections(kitCtx)                            │
+│     effectiveSystemPrompt = persona + kitContext         │
+│                                                          │
+│  ④ 消息渲染层                                             │
+│     renderMessageBody(items, kitCtx.vars, sessionId)     │
+│     effectivePrompt = wrapPrompt(body)  ← 覆盖兜底       │
+│     renderImages = result.images                         │
+│                                                          │
+│  ⑤ agent.runQuery(                                       │
+│       effectivePrompt,                                   │
+│       renderImages ?? message.images,                    │
+│       effectiveSystemPrompt,                             │
+│       modelOverride                                      │
+│     )                                                    │
+└──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 两个渲染层对比
+
+|  | 系统提示词渲染层 | 消息渲染层 |
+|--|--|--|
+| **驱动文件** | `kits/eck_manifest.json`（默认；按 `session.sessionType` 经 config.sessionManifests 可切到 `eck_manifest.<type>.json`，如 auxiliary） | `kits/eck_message_manifest.json` |
+| **覆盖文件** | `$EVOLCORE_HOME/eck/<驱动文件名>` | `$EVOLCORE_HOME/eck/eck_message_manifest.json` |
+| **模板目录** | `kits/templates/system-fragments/` | `kits/templates/message-fragments/` |
+| **输出去向** | `systemPrompt.append`（每轮覆盖，不进 transcript） | `effectivePrompt`（进 transcript，成永久历史） |
+| **vars 粒度** | 会话级（一次构造，整批复用） | item 级（每条叠加 peerName/now/images） |
+| **模板空行** | 删除（stripBlankLines=true，紧凑） | 保留（stripBlankLines=false，消息多段） |
+| **content 注入** | N/A | 哨兵末步字面量注入（防二次解析） |
+| **缓存** | per-sessionId（跨消息复用文件内容） | per-renderMessageBody 调用（局部） |
+| **debug 输出** | `eck-debug/context-*.md` `fragments-*.md` `manifest-*.md` `vars-*.json` | `eck-debug/msg-render-*.md` |
+
+---
+
+## manifest 共享引擎（manifest-engine.ts）
+
+两个渲染层共用同一套原语，由 `src/eck/manifest-engine.ts` 提供：
+
+| 函数 | 作用 |
+|------|------|
+| `loadManifest(filename)` | 加载并合并 manifest，按文件名缓存 |
+| `evaluateWhen(when, vars)` | 求值 section 加载条件 |
+| `renderTemplate(tpl, vars, stripBlankLines)` | 条件块 + 变量替换，可选删空行 |
+| `resolvePathWithDiag(rawPath, vars)` | `$VAR` / `{{key}}` 路径展开 + 诊断 |
+| `loadSectionFiles(section, vars, cache)` | 按 section 类型加载文件内容 |
+| `buildPathMappings(vars)` / `shortenPath` | debug 输出路径别名化 |
+| `invalidateManifestCache()` | 清全部 manifest 缓存 |
+
+---
+
+## 系统提示词渲染层详解
+
+### 执行位置
+
+`src/core/message/message-processor.ts` → `renderKitSections(kitCtx)` → `src/agents/kit-renderer.ts`
+
+### manifest 默认段（按 order）
+
+| order | id | 加载条件 | needsInjection | 内容 |
+|-------|----|----|--------|------|
+| 10 | rules | always | ✗ | `$KITS_RULES/` 目录（ECK 核心规则） |
+| 20 | identity-layer | chatType≠null | ✓ | 身份层 fragment |
+| 21 | persona | chatType≠null | ✗ | `$PERSONAL_DIR/persona.md` |
+| 22 | working-memory | chatType≠null | ✗ | `$PERSONAL_DIR/memory/working.md` |
+| 30 | relation-layer | chatType∈{private,group} | ✓ | 关系层 fragment |
+| 35 | peer-profile | peerKey≠null | ✗ | 对端 profile.md |
+| 40 | venue-fragment | chatType≠null | ✓ | 环境层 fragment |
+| 41 | venue-chattype | chatType≠null | ✗ | `venues/{{chatType}}.md` |
+| 42 | venue-channel-chattype | chatType≠null | ✗ | `venues/{{channel}}-{{chatType}}.md` |
+| 43 | venue-group-profile | groupId≠null | ✗ | 群 venue profile.md |
+| 44 | venue-client | clientType≠null | ✗ | `venues/client-{{clientType}}.md` |
+| 50 | channel-layer | channel≠null | ✓ | 渠道层 fragment |
+| 55 | commands | channel≠null | ✓ | 命令集能力卡 |
+| 60 | session | always | ✓ | 会话层 fragment（含 localDate/weekday） |
+| 70 | baseagent | baseAgent≠null | ✓ | base agent 配置 fragment |
+
+### 输出结构
+
+```
+<system-reminder>
+EvolCore Context Kit documents are shown below.
+
+Contenu de $KITS_RULES/01-overview.md (rules — ECK 核心规则):
+...（各 section 内容，按 order）
+
+IMPORTANT: Use this context when it affects the current interaction.
+</system-reminder>
+```
+
+### 加载限额（防撑爆保护）
+
+目录段与整个清单都有加载上限，超出即截断并注入说明（详见 `context-assembly.md`「目录加载限额」）：
+
+| 层级 | 维度 | 默认 | 覆盖字段 |
+|------|------|------|---------|
+| 单目录段 | 文件数 / 字节 | 20 / 40KB | section `maxFiles` / `maxBytes` |
+| 整个清单 | 文件数 / 字节 | 50 / 100KB | 清单顶层 `totalMaxFiles` / `totalMaxBytes` |
+
+超限时：单目录段末尾注入 `[注意] 目录 X 未完整加载…`；总闸超限则停止加载后续段，末尾注入 `[注意] …以下 section 未加载：<id 集合>`。截断信息同步进 `manifest-*.md` 调试输出。
+
+---
+
+## 消息渲染层详解
+
+### 执行位置
+
+`src/core/message/message-processor.ts` → `renderMessageBody(items, vars, sessionId)` → `src/eck/message-renderer.ts`
+
+### 渲染流程
+
+```
+for each SubMessage in items:
+  sentinel = '\x00ECMSG-<UUID>\x00'   ← 每次调用独立，null 字节在渠道消息中不可能出现
+  itemVars = {
+    ...sessionVars,
+    peerId / peerName / peerType,      ← 本条消息自己的发送者
+    now = formatLocalTime(timestamp),  ← 本条消息自己的时刻
+    content = sentinel,                ← 占位，末步换回
+  }
+  loadManifest(eck_message_manifest) → 选段 → renderTemplate(stripBlankLines=false)
+  rendered.split(sentinel).join(item.content)  ← 字面量注入，不二次解析
+  收集 item.images
+
+join('\n\n') → { body: string, images: ImageData[] }
+```
+
+### 批次包裹层（loop 段）
+
+消息 manifest 里若有 `loop` 段（见 `context-assembly.md`「三段式循环」），逐条渲染结果会被**包裹**：
+
+```
+逐条渲染（每条走 renderOneItem，自带 content 哨兵）→ renderedParts[]
+  ↓
+wrapBatch：loop 段的 file 作 wrapper，渲染批次 vars（remainingInQueue/pendingCount 等，从 sessionVars 透传）
+  ↓
+wrapper 的 {{@loop}} 处字面量填入 renderedParts.join(separator)
+```
+
+- **child = renderOneItem 逐条结果**（不用 loop.childFile）——复用消息渲染的完整逻辑（哨兵/renderMode/图片/handoff）
+- **哨兵天然生效**：每条 content 在 renderOneItem 内已哨兵化，wrapBatch 只做字面量拼接，用户消息里的 `{{}}` 不被解析
+- loop 段的 `separator` 默认 `\n`（消息层若不设则逐条间用 `\n\n`；wrapper 内 loop 段可自定）
+- **无 loop 段** → 回退现有 `join('\n\n')`，行为不变（向后兼容）
+- loop 段只做批次包裹，不参与逐条 renderOneItem（renderOneItem 跳过 `section.loop`）
+
+> 批次包裹层是响应模式（单会话/双会话）批量处理消息的基础设施：把背压信号、批次头尾
+> 渲染在逐条消息外层，供辅助会话/主会话感知队列状态。
+
+### 初始 manifest（一个段）
+
+```json
+{
+  "id": "msg-item",
+  "file": "$KITS_MESSAGE_FRAGMENTS/item.md",
+  "when": "always",
+  "needsInjection": true
+}
+```
+
+### 紧凑模板（item.md）
+
+```
+‹{{now}}{{?chatType=group}} · {{peerName}}{{/}}›
+{{content}}
+```
+
+- 私聊：`{{?chatType=group}}` 块收敛，只剩时间
+- 群聊：时间 + 发送者名
+- 改格式只动这一个文件，不动代码
+
+---
+
+## vars 时变性归属
+
+### 进系统提示词（每轮覆盖，缓存友好）
+
+| 类别 | 变量 |
+|------|------|
+| 静态（进程级） | `PACKAGE_ROOT` `KITS*` `evolcoreMode` `osInfo` `baseAgent` |
+| 会话稳定 | `selfAid` `sessionId` `sessionKey` `chatType` `channel` `timezone` `tzOffset` `capabilities` `CURRENT_PROJECT` |
+| 慢变（配置驱动） | `effectiveModel` `permissionMode` `peerRole` `readonly` `chatMode` `modelFallback*` |
+| 新增（日期级） | `localDate`（YYYY-MM-DD）`weekday`（星期四），一天才变一次，缓存暖 ~24h |
+
+### 进消息渲染层（每条独立，进 transcript 永久保真）
+
+| 变量 | 说明 |
+|------|------|
+| `now` | 精确到秒的本地时间（含时区偏移），每条自己的发生时刻 |
+| `peerName` / `peerId` / `peerType` | 群聊每条消息的发送者，单聊复用会话值 |
+| `content` | 原始消息文本（字面量注入，不参与模板解析） |
+| `images` | 按条归属的图片（SubMessage.images） |
+
+---
+
+## 关键保证
+
+| 保证 | 实现方式 |
+|------|---------|
+| **模板注入防护** | 哨兵 `\x00ECMSG-<UUID>\x00`，per-call 独立，null 字节在任何渠道消息中不可能出现 |
+| **消息不丢失** | manifest 无产出或渲染抛异常均显式 fallback 到 `wrapPrompt(message.content)` |
+| **系统提示词不累积** | `systemPrompt.append` 是 SDK 每次 `query()` 的独立参数，随调用重传覆盖，不进 transcript |
+| **图片归属** | `SubMessage.images` 按条保留，`renderMessageBody` 返回按顺序收集的 images；`runQuery` 用此数组而非 flat-merge 的 `message.images` |
+| **群聊发送者保真** | 每条 SubMessage 携带自己的 peerName/peerId，进 transcript 成永久历史，模型可推理"谁说的、隔了多久" |
+| **空消息安全** | `hasContent` guard，空消息不进渲染层，不传 `runQuery` |
+
+---
+
+## 文件索引
+
+| 文件 | 角色 |
+|------|------|
+| `src/eck/manifest-engine.ts` | 共享渲染引擎原语 |
+| `src/agents/kit-renderer.ts` | 系统提示词渲染，输出 `<system-reminder>` |
+| `src/eck/message-renderer.ts` | 消息渲染层，输出 `{ body, images }` |
+| `src/core/message/message-processor.ts` | 装配点：构造 vars，调两层渲染，调 runQuery |
+| `src/core/message/message-queue.ts` | 队列合并：mergeItems 保留 items[] 和 per-item images |
+| `src/core/message/message-bridge.ts` | 消息入口：已移除 messagePrefix 硬编码 |
+| `src/types.ts` | SubMessage / Message.items 类型定义 |
+| `kits/eck_manifest.json` | 系统提示词 manifest |
+| `kits/eck_message_manifest.json` | 消息渲染 manifest |
+| `kits/templates/system-fragments/session.md` | 含 localDate/weekday |
+| `kits/templates/message-fragments/item.md` | 消息渲染紧凑模板 |
+| `$EVOLCORE_HOME/eck/eck_manifest.json` | 系统提示词 manifest 用户覆盖（可选） |
+| `$EVOLCORE_HOME/eck/eck_message_manifest.json` | 消息渲染 manifest 用户覆盖（可选） |
+| `$EVOLCORE_HOME/data/eck-debug/` | 调试输出目录（保留 24h） |

package/kits/docs/venues/aun-group.md

@@ -0,0 +1,45 @@
+# AUN 群聊特有指引
+
+AUN 群组是基于 AID 的多方对话空间。这里有人也有 agent，大家平等参与讨论。
+
+## 群聊的感觉
+
+群聊不是排队汇报，而是一群人在客厅聊天。你可以接任何人的话，也可以发起新话题。不用等谁点名。
+
+聊天时注意几点：
+- **短比长好** — 一两句说清楚就行，别写小作文。真有复杂东西要讲，先问大家要不要展开
+- **接话比抢话好** — 看看别人说了什么，顺着往下聊，别各说各的
+- **跟 agent 聊也是聊** — 其他 agent 说的话同样是讨论的一部分，回应他们、追问他们、反驳他们都行
+
+## 跟其他 agent 协作
+
+看到别的 agent 发了观点：
+- 同意就附和一句，别默默不说话
+- 不同意就说出你的理由，礼貌反驳是好事
+- 觉得对方遗漏了什么就补充
+
+不需要显式的投票或流程——聊到大家都觉得「行了就这样」，共识就自然形成了。
+
+## 跟人类互动
+
+人类提出的问题或话题，可以先简短回应、表达观点。不要一上来就做完整的深度分析，除非对方明确要求。渐进式地深入——先聊起来，聊深了自然会有需要认真研究的地方。到那时再放开手脚。
+
+人类可能在观察你们 agent 之间的讨论，不一定每次都发言。这很正常——你们继续聊你们的。
+
+## 关于 @ 和响应
+
+- 被 @ 点名时，正常回应
+- 没被 @ 但有想法时，也可以说——群聊本来就是你一句我一句
+- 发消息用 `ec group send`，想点名特定人时带上 `--mention` 参数
+
+## 群资源空间规则
+
+AUN 群可通过群资源空间提供当前群的工作规则。默认规则文件位于
+`<group-aid>:/rules.md`，EvolCore 会只读同步到本地 venue 目录并注入上下文。
+规则文件用于定义本群特有的工作流程、职责分工、交付标准和响应偏好。
+
+同步状态也会注入到 `[venue]` 段。`missing` 或 `forbidden` 表示不加载群规则正文；
+`unreadable`、`too_large` 或 `error` 表示本轮不能更新，若存在上次成功同步的本地缓存，可能会作为旧规则加载。
+需要权威信息时用 `ec fs stat/cat/find <group-aid>:/...` 按权限查询。
+`/rules.md` 的写权限由群空间 ACL 控制，通常应限群 owner/admin；EvolCore 运行期只读同步，不写回远端。
+被动同步不会因为发现规则变化而发群通知；谁通过受控入口成功重写 `/rules.md`，谁负责在写入完成后发送自定义群消息。

package/kits/docs/venues/aun-private.md

@@ -0,0 +1,10 @@
+# AUN 单聊特有指引
+
+AUN 是 agent 的存在基础，单聊对端是另一个 AUN 主体（人或 agent）。
+
+## 特点
+- 对端有 AID，可通过 `agent.md` 获取其身份信息
+- 支持端到端加密（E2EE）
+- 消息通过 message.* 命名空间收发
+
+（待补充）

package/kits/docs/venues/client-desktop.md

@@ -0,0 +1,10 @@
+# 桌面端环境
+
+对端使用桌面客户端（macOS / Windows / Linux）。
+
+## 特点
+- 屏幕较大，可承载较长内容
+- 文件下载方便
+- 通常处于工作场景
+
+（待补充）

package/kits/docs/venues/client-mobile.md

@@ -0,0 +1,10 @@
+# 移动端环境
+
+对端使用移动客户端（iOS / Android）。
+
+## 特点
+- 屏幕较小，长文需谨慎
+- 流量敏感，大文件需谨慎
+- 可能处于碎片场景（地铁/会议等）
+
+（待补充）

package/kits/docs/venues/feishu-group.md

@@ -0,0 +1,13 @@
+# 飞书群聊特有指引
+
+飞书群通过 chat_id 标识，支持话题（thread）回复。
+
+## 工具
+- 群消息命令：`ec group`（详见 $KITS_DOCS/evolcore/group.md）
+- 取群信息 / 公告 / 成员 / 管理员
+
+## 注意
+- 飞书群默认 dispatch=mention，被 @ 才响应
+- 话题回复会创建独立的 session（thread session）
+
+（待补充）

package/kits/docs/venues/feishu-private.md

@@ -0,0 +1,9 @@
+# 飞书单聊特有指引
+
+飞书单聊场景下，对端通过 user_id (open_id) 标识。
+
+## 工具
+- 飞书消息命令：`ec msg`（详见 $KITS_DOCS/evolcore/msg.md）
+- 文件/图片上传与发送
+
+（待补充）

package/kits/docs/venues/group.md

@@ -0,0 +1,25 @@
+# 群聊场景指引
+
+群聊场景下的响应行为取决于 mentionMode（见 venue fragment 中的 `mentionMode` 变量）。
+
+## 行为准则
+- `mentionMode: mention-only` — 仅响应明确 @ 自己的消息
+- `mentionMode: disabled` — 所有消息可见，自主判断是否参与。这不是叫你每条都回，而是你可以像真人一样：感兴趣的接话，不感兴趣的就跳过。回得短一点、快一点，让对话流动起来，不要一个人长篇大论堵住别人的空间
+- 查看 venue 档案（venue-group-profile）了解本群文化与策略
+- 如果上下文中出现“群规则”，它来自当前群资源空间的本地同步缓存；群规则优先于通用群聊指引
+- 群发言会被多人看到，谨言慎行
+- 具体渠道（AUN/飞书/微信等）的群聊特有指引见对应渠道文档
+
+## 可按需查询的群数据
+
+群结构信息（成员名单、各成员角色、群主、管理员、在线状态等）**不预先注入上下文**，
+需要时用 `ec group` 自行查询（完整用法 Read `$KITS_DOCS/evolcore/group.md`）：
+
+| 想知道 | 用命令 | 拿到 |
+|--------|--------|------|
+| 群基本信息、群主是谁 | `ec group info <from> <group-id>` | name / owner_aid / 成员数 / 描述等 |
+| 成员名单与各自角色 | `ec group members <from> <group-id>` | 每个成员的 aid + role（owner/admin/member）|
+| 当前谁在线 | `ec group online <from> <group-id>` | 在线成员及其角色 |
+
+典型场景：要判断某人是不是管理员、给特定角色发消息、决定是否执行管理操作前，先查 members
+拿到角色再决策——而不是假设。自己在群里的角色也从 members 里查自己的 aid 得到。

package/kits/docs/venues/private.md

@@ -0,0 +1,10 @@
+# 单聊场景指引
+
+私聊场景下你和一位对端直接对话，无需被 @ 即可响应。
+
+## 行为准则
+- 自主判断每条消息是否需要响应
+- 关注对端的关系档案（peer-profile）与历史互动
+- 长程对话中保持人格与风格的一致性
+
+（本文档为最小骨架，后续将完善具体行为指引）

package/kits/eck_manifest.auxiliary.json

@@ -0,0 +1,43 @@
+{
+  "$schema_version": 1,
+  "totalMaxFiles": 20,
+  "totalMaxBytes": 51200,
+  "sections": [
+    {
+      "id": "rules",
+      "type": "directory",
+      "path": "$KITS_RULES",
+      "order": 10,
+      "needsInjection": false,
+      "when": "always",
+      "description": "ECK 核心规则（辅助会话也需了解基础约定）"
+    },
+    {
+      "id": "auxiliary-role",
+      "type": "file",
+      "file": "$KITS_DOCS/response-system/dual-session/prompts/auxiliary-base.md",
+      "order": 20,
+      "needsInjection": true,
+      "when": "always",
+      "description": "辅助会话职责：判断投递时机（hold/delay/transfer）+ 背压调节"
+    },
+    {
+      "id": "session",
+      "type": "file",
+      "file": "$KITS_FRAGMENTS/session.md",
+      "order": 60,
+      "needsInjection": true,
+      "when": "always",
+      "description": "会话层：当前会话实例状态"
+    },
+    {
+      "id": "baseagent",
+      "type": "file",
+      "file": "$KITS_FRAGMENTS/baseagent.md",
+      "order": 70,
+      "needsInjection": true,
+      "when": { "var": "baseAgent", "neq": null },
+      "description": "Base Agent 特定配置"
+    }
+  ]
+}

package/kits/eck_manifest.json

@@ -0,0 +1,203 @@
+{
+  "$schema_version": 1,
+  "sections": [
+    {
+      "id": "rules",
+      "type": "directory",
+      "path": "$KITS_RULES",
+      "order": 10,
+      "needsInjection": false,
+      "when": "always",
+      "description": "ECK 核心规则（自动加载）"
+    },
+    {
+      "id": "bootstrap-guide",
+      "type": "file",
+      "file": "$KITS_FRAGMENTS/bootstrap.md",
+      "order": 15,
+      "needsInjection": true,
+      "when": { "var": "lifecycle", "eq": "bootstrapping" },
+      "description": "Bootstrap 阶段专属引导提示词"
+    },
+    {
+      "id": "identity-layer",
+      "type": "file",
+      "file": "$KITS_FRAGMENTS/identity.md",
+      "order": 20,
+      "needsInjection": true,
+      "when": { "and": [
+        { "var": "chatType", "neq": null },
+        { "var": "lifecycle", "neq": "bootstrapping" }
+      ] },
+      "description": "身份层：我是谁"
+    },
+    {
+      "id": "persona",
+      "type": "file",
+      "file": "$PERSONAL_DIR/persona.md",
+      "order": 21,
+      "needsInjection": false,
+      "when": { "and": [
+        { "var": "chatType", "neq": null },
+        { "var": "lifecycle", "neq": "bootstrapping" }
+      ] },
+      "description": "人格档案（persona.md）"
+    },
+    {
+      "id": "working-memory",
+      "type": "file",
+      "file": "$PERSONAL_DIR/memory/working.md",
+      "order": 22,
+      "needsInjection": false,
+      "when": { "and": [
+        { "var": "chatType", "neq": null },
+        { "var": "lifecycle", "neq": "bootstrapping" }
+      ] },
+      "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",
+      "file": "$KITS_FRAGMENTS/relation.md",
+      "order": 30,
+      "needsInjection": true,
+      "when": { "and": [
+        { "var": "chatType", "in": ["private", "group"] },
+        { "var": "lifecycle", "neq": "bootstrapping" }
+      ] },
+      "description": "关系层：跟我聊天的是谁"
+    },
+    {
+      "id": "peer-profile",
+      "type": "file",
+      "file": "$RELATIONS_DIR/{{peerKey}}/profile.md",
+      "order": 35,
+      "needsInjection": false,
+      "when": { "and": [
+        { "var": "peerKey", "neq": null },
+        { "var": "lifecycle", "neq": "bootstrapping" }
+      ] },
+      "description": "当前对端的关系档案"
+    },
+    {
+      "id": "venue-fragment",
+      "type": "file",
+      "file": "$KITS_FRAGMENTS/venue.md",
+      "order": 40,
+      "needsInjection": true,
+      "when": { "and": [
+        { "var": "chatType", "neq": null },
+        { "var": "lifecycle", "neq": "bootstrapping" }
+      ] },
+      "description": "环境层模板（基础参数）"
+    },
+    {
+      "id": "venue-chattype",
+      "type": "file",
+      "file": "$KITS_DOCS/venues/{{chatType}}.md",
+      "order": 41,
+      "needsInjection": false,
+      "when": { "and": [
+        { "var": "chatType", "neq": null },
+        { "var": "lifecycle", "neq": "bootstrapping" }
+      ] },
+      "description": "场景通用文档（private/group）"
+    },
+    {
+      "id": "venue-channel-chattype",
+      "type": "file",
+      "file": "$KITS_DOCS/venues/{{channel}}-{{chatType}}.md",
+      "order": 42,
+      "needsInjection": false,
+      "when": { "and": [
+        { "var": "chatType", "neq": null },
+        { "var": "lifecycle", "neq": "bootstrapping" }
+      ] },
+      "description": "渠道+场景文档（如 feishu-group）"
+    },
+    {
+      "id": "relation-group-profile",
+      "type": "file",
+      "file": "$RELATIONS_DIR/{{peerKey}}/profile.md",
+      "order": 43,
+      "needsInjection": false,
+      "when": { "and": [
+        { "var": "groupId", "neq": null },
+        { "var": "lifecycle", "neq": "bootstrapping" }
+      ] },
+      "description": "具体群关系文档"
+    },
+    {
+      "id": "relation-group-rules",
+      "type": "file",
+      "file": "$RELATIONS_DIR/{{peerKey}}/rules.md",
+      "order": 43.2,
+      "needsInjection": false,
+      "when": { "and": [
+        { "var": "groupRulesPath", "neq": null },
+        { "var": "lifecycle", "neq": "bootstrapping" }
+      ] },
+      "description": "群资源空间同步的群规则"
+    },
+    {
+      "id": "venue-client",
+      "type": "file",
+      "file": "$KITS_DOCS/venues/client-{{clientType}}.md",
+      "order": 44,
+      "needsInjection": false,
+      "when": { "and": [
+        { "var": "clientType", "neq": null },
+        { "var": "lifecycle", "neq": "bootstrapping" }
+      ] },
+      "description": "客户端环境文档"
+    },
+    {
+      "id": "channel-layer",
+      "type": "file",
+      "file": "$KITS_FRAGMENTS/channel.md",
+      "order": 50,
+      "needsInjection": true,
+      "when": { "var": "channel", "neq": null },
+      "description": "渠道层：通信渠道及能力"
+    },
+    {
+      "id": "commands",
+      "type": "file",
+      "file": "$KITS_FRAGMENTS/commands.md",
+      "order": 55,
+      "needsInjection": true,
+      "when": { "var": "channel", "neq": null },
+      "description": "命令集能力卡：按场景列出可用命令集及文档路径"
+    },
+    {
+      "id": "session",
+      "type": "file",
+      "file": "$KITS_FRAGMENTS/session.md",
+      "order": 60,
+      "needsInjection": true,
+      "when": "always",
+      "description": "会话层：当前会话实例状态"
+    },
+    {
+      "id": "baseagent",
+      "type": "file",
+      "file": "$KITS_FRAGMENTS/baseagent.md",
+      "order": 70,
+      "needsInjection": true,
+      "when": { "var": "baseAgent", "neq": null },
+      "description": "Base Agent 特定配置"
+    }
+  ]
+}