evolclaw 3.1.3 → 3.1.5

package/dist/core/session/session-mapper.js

@@ -1,4 +1,5 @@
 import { formatTimestamp } from './session-fs-store.js';
+import { formatSessionKey, DEFAULT_THREAD_ID } from './session-key.js';
 export function sessionToFile(session) {
     const metadata = {};
     if (session.metadata) {
@@ -15,19 +16,22 @@ export function sessionToFile(session) {
         if (session.metadata.resumeAt)
             metadata.resumeAt = session.metadata.resumeAt;
         for (const [k, v] of Object.entries(session.metadata)) {
-            if (['isActive', 'channelName', 'permissionMode', 'peerId', 'peerName', 'groupId', 'replyContext', 'agentSessions', 'resumeAt'].includes(k))
+            if (['isActive', 'channelKey', 'channelName', 'permissionMode', 'peerId', 'peerName', 'groupId', 'replyContext', 'agentSessions', 'resumeAt'].includes(k))
                 continue;
             if (v !== undefined)
                 metadata[k] = v;
         }
     }
     const now = session.updatedAt || Date.now();
+    const channelType = session.channelType || session.channel;
+    const threadId = session.threadId || DEFAULT_THREAD_ID;
     return {
         id: session.id,
         channel: session.channel,
-        channelType: session.channelType || session.channel,
+        channelType,
         channelId: session.channelId,
-        selfId: session.selfId ?? null,
+        sessionKey: formatSessionKey(channelType, session.channelId, threadId),
+        selfAID: session.selfAID,
         agentType: session.agentId || 'claude',
         threadId: session.threadId || '',
         chatType: session.chatType || 'private',
@@ -71,7 +75,8 @@ export function fileToSession(file) {
         channel: file.channel,
         channelType: file.channelType,
         channelId: file.channelId,
-        selfId: file.selfId ?? undefined,
+        sessionKey: file.sessionKey || formatSessionKey(file.channelType, file.channelId, file.threadId || DEFAULT_THREAD_ID),
+        selfAID: file.selfAID,
         agentId: file.agentType,
         threadId: file.threadId,
         chatType: file.chatType,

package/dist/core/trigger/manager.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { atomicWriteJson, appendJsonl } from '../session/session-fs-store.js';
+import { formatChannelKey } from '../channel-loader.js';
 import { logger } from '../../utils/logger.js';
 export class TriggerManager {
     aid;
@@ -22,6 +23,26 @@ export class TriggerManager {
             const raw = fs.readFileSync(this.triggersPath, 'utf8');
             const data = JSON.parse(raw);
             this.triggers = new Map(Object.entries(data.triggers ?? {}));
+            // Migrate old channel key format: "selfAID#type#name" → "type#selfAID#name"
+            let migrated = false;
+            for (const trigger of this.triggers.values()) {
+                const fixed = this.migrateChannelKey(trigger.targetChannel);
+                if (fixed !== trigger.targetChannel) {
+                    trigger.targetChannel = fixed;
+                    migrated = true;
+                }
+                if (trigger.createdByChannel) {
+                    const fixedBy = this.migrateChannelKey(trigger.createdByChannel);
+                    if (fixedBy !== trigger.createdByChannel) {
+                        trigger.createdByChannel = fixedBy;
+                        migrated = true;
+                    }
+                }
+            }
+            if (migrated) {
+                logger.info(`[TriggerManager] Migrated old channel key format`);
+                this.save();
+            }
             return [...this.triggers.values()];
         }
         catch (e) {
@@ -30,6 +51,22 @@ export class TriggerManager {
             return [];
         }
     }
+    /**
+     * Detect and fix old format "selfAID#type#name" → current "type#selfAID#name".
+     * Old format: first segment contains '.' (AID like "evolai.agentid.pub").
+     */
+    migrateChannelKey(key) {
+        if (!key || !key.includes('#'))
+            return key;
+        const parts = key.split('#');
+        if (parts.length !== 3)
+            return key;
+        const [first, second, third] = parts;
+        if (first.includes('.') && !second.includes('.')) {
+            return formatChannelKey({ type: second, selfAID: first, name: third });
+        }
+        return key;
+    }
     save() {
         const data = {
             version: 1,

package/dist/core/trigger/scheduler.js

@@ -211,8 +211,9 @@ export class TriggerScheduler {
     buildSyntheticMessage(trigger, messageId) {
         return {
             channel: trigger.targetChannel,
+            channelType: trigger.targetChannelType,
             channelId: trigger.targetChannelId,
-            selfId: this.aid,
+            selfAID: this.aid,
             threadId: trigger.targetThreadId ?? '',
             agentId: trigger.agentId,
             chatType: 'private',

package/dist/index.js

@@ -5,6 +5,7 @@ import { ensureDataDirs, resolvePaths, getPackageRoot, agentMdPath } from './pat
 import { resolveAnthropicConfig } from './agents/resolve.js';
 import { loadDefaults, autoMigrateIfNeeded, migrateIdentitiesIfNeeded } from './config-store.js';
 import { CONFIG_SCHEMA_VERSION } from './types.js';
+import dotenv from 'dotenv';
 import { SessionManager } from './core/session/session-manager.js';
 import { ClaudeAgentPlugin } from './agents/claude-runner.js';
 import { CodexAgentPlugin } from './agents/codex-runner.js';
@@ -25,7 +26,7 @@ import { StatsCollector } from './utils/stats.js';
 import { AidStatsCollector } from './utils/stats.js';
 import { PermissionGateway } from './core/permission.js';
 import { InteractionRouter } from './core/interaction-router.js';
-import { ChannelLoader } from './core/channel-loader.js';
+import { ChannelLoader, tryParseChannelKey } from './core/channel-loader.js';
 import { AgentLoader } from './core/baseagent-loader.js';
 import { EvolAgentRegistry } from './core/evolagent-registry.js';
 import { buildReloadHooks } from './core/channel-loader.js';
@@ -183,6 +184,8 @@ async function main() {
     logger.info(`EvolClaw v${readEvolclawVersion()} starting... (fastaun v${readFastaunVersion()})`);
     // 确保数据目录存在
     ensureDataDirs();
+    // 加载 $EVOLCLAW_HOME/.env 到 process.env（不覆盖已存在的变量）
+    dotenv.config({ path: path.join(resolvePaths().root, '.env') });
     // ── 单实例保护（pre-check + post-write self-check）──
     // pre-check：发现已有活 main 直接退出，避免起任何副作用
     {
@@ -313,7 +316,7 @@ async function main() {
         // 优先级：群聊 > nothuman > private
         if (chatType === 'group')
             return cm.group;
-        if (peerType && peerType !== 'human' && peerType !== 'unknown')
+        if (peerType && peerType !== 'human')
             return cm.nothuman;
         return cm.private;
     });
@@ -550,7 +553,8 @@ async function main() {
                 const owningAgent = agentRegistry.resolveByChannel(inst.adapter.channelKey);
                 const effectiveDefault = owningAgent?.projectPath
                     ?? primaryAgent.projectPath;
-                const session = await sessionManager.getOrCreateSession(inst.adapter.channelKey, channelId, effectiveDefault, undefined, undefined, undefined, undefined);
+                const parsedKey = tryParseChannelKey(inst.adapter.channelKey);
+                const session = await sessionManager.getOrCreateSession(inst.adapter.channelKey, channelId, effectiveDefault, undefined, undefined, undefined, undefined, undefined, undefined, parsedKey?.selfAID, parsedKey?.type);
                 return path.isAbsolute(session.projectPath)
                     ? session.projectPath
                     : path.resolve(process.cwd(), session.projectPath);
@@ -863,6 +867,9 @@ async function main() {
         queued: messageQueue.getQueueLengthByAgent(agentName),
     }));
     ipcServer.setAunAidStatsProvider(() => aidStatsCollector.getAllSnapshots());
+    ipcServer.setAunAidStatsRecorder((params) => {
+        aidStatsCollector.recordOutbound(params.aid, params.toPeer, Buffer.byteLength(params.text || '', 'utf-8'), params.text, false, params.encrypt, params.chatmode);
+    });
     // ── Reload hooks: enable agentRegistry.reload() to drain/disconnect/restart channels ──
     const reloadHooks = buildReloadHooks({
         channelLoader,

package/dist/ipc.js

@@ -11,6 +11,7 @@ export class IpcServer {
     agentRegistry;
     aunAidProvider;
     aunAidStatsProvider;
+    aunAidStatsRecorder;
     constructor(socketPath, getStatus, commandExecutor) {
         this.socketPath = socketPath;
         this.getStatus = getStatus;
@@ -28,6 +29,10 @@ export class IpcServer {
     setAunAidStatsProvider(provider) {
         this.aunAidStatsProvider = provider;
     }
+    /** Inject AUN AID stats recorder for aun-aid-stats-record-outbound IPC handler */
+    setAunAidStatsRecorder(recorder) {
+        this.aunAidStatsRecorder = recorder;
+    }
     start() {
         // Remove stale socket file (Unix only — named pipes auto-cleanup on process exit)
         if (!isNamedPipe(this.socketPath)) {
@@ -97,6 +102,23 @@ export class IpcServer {
                 const stats = this.aunAidStatsProvider ? this.aunAidStatsProvider() : [];
                 return { ok: true, stats };
             }
+            case 'aun-aid-stats-record-outbound': {
+                if (!this.aunAidStatsRecorder)
+                    return { ok: false, error: 'recorder not configured' };
+                try {
+                    this.aunAidStatsRecorder({
+                        aid: cmd.aid,
+                        toPeer: cmd.toPeer,
+                        text: cmd.text ?? '',
+                        encrypt: cmd.encrypt,
+                        chatmode: cmd.chatmode,
+                    });
+                    return { ok: true };
+                }
+                catch (e) {
+                    return { ok: false, error: String(e?.message || e) };
+                }
+            }
             case 'ctl': {
                 if (!this.commandExecutor)
                     return { ok: false, error: 'ctl not configured' };

package/dist/paths.js

@@ -46,6 +46,14 @@ export function resolvePaths() {
     };
 }
 // ── AID 路径（agent.md 存放在 $EVOLCLAW_HOME/AIDs/<aid>/）──
+/**
+ * AUN SDK 数据根路径（密钥/证书/AgentMDs 等）。
+ * 与 evolclaw 数据共用 $EVOLCLAW_HOME 根，避免散落到 ~/.aun。
+ * 启动时 SDK 通过 aun_path 选项指向这里；agent.md 子目录通过 setAgentMdPath(aidsDir()) 单独设置。
+ */
+export function aunPath() {
+    return resolveRoot();
+}
 export function aidsDir() {
     return path.join(resolveRoot(), 'AIDs');
 }
@@ -109,30 +117,93 @@ export function ensureDataDirs() {
     fs.mkdirSync(p.eckDir, { recursive: true });
     fs.mkdirSync(eckDebugDir(), { recursive: true });
     fs.mkdirSync(aidsDir(), { recursive: true });
-    migrateAgentMdFromAun();
+    seedConfigTemplates();
+    migrateFromAun();
 }
+const MIGRATION_MARKER = '.migrated-from-aun';
 /**
- * One-time migration: copy agent.md from ~/.aun/AIDs/<aid>/ to $EVOLCLAW_HOME/AIDs/<aid>/
- * if the new location doesn't have it yet.
+ * 一次性迁移：把 ~/.aun 下的 SDK 数据搬到 $EVOLCLAW_HOME 下。
+ * 通过标记文件判断是否已迁移，完成后写入标记，后续版本可删除此函数。
  */
-function migrateAgentMdFromAun() {
-    const aunAidsDir = path.join(os.homedir(), '.aun', 'AIDs');
-    const ecAids = aidsDir();
-    if (!fs.existsSync(aunAidsDir) || aunAidsDir === ecAids)
+function migrateFromAun() {
+    const newRoot = resolveRoot();
+    const markerPath = path.join(newRoot, MIGRATION_MARKER);
+    if (fs.existsSync(markerPath))
+        return;
+    const oldRoot = path.join(os.homedir(), '.aun');
+    if (!fs.existsSync(oldRoot) || oldRoot === newRoot) {
+        try {
+            fs.writeFileSync(markerPath, new Date().toISOString(), 'utf-8');
+        }
+        catch { }
         return;
+    }
+    const copyFileIfMissing = (src, dst) => {
+        if (!fs.existsSync(src) || fs.existsSync(dst))
+            return;
+        fs.mkdirSync(path.dirname(dst), { recursive: true });
+        fs.copyFileSync(src, dst);
+    };
+    const copyDirIfMissing = (src, dst) => {
+        if (!fs.existsSync(src))
+            return;
+        if (!fs.statSync(src).isDirectory())
+            return;
+        for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+            const s = path.join(src, entry.name);
+            const d = path.join(dst, entry.name);
+            if (entry.isDirectory()) {
+                copyDirIfMissing(s, d);
+            }
+            else if (entry.isFile()) {
+                copyFileIfMissing(s, d);
+            }
+        }
+    };
     try {
-        for (const entry of fs.readdirSync(aunAidsDir, { withFileTypes: true })) {
-            if (!entry.isDirectory())
-                continue;
-            const oldMd = path.join(aunAidsDir, entry.name, 'agent.md');
-            const newMd = path.join(ecAids, entry.name, 'agent.md');
-            if (fs.existsSync(oldMd) && !fs.existsSync(newMd)) {
-                fs.mkdirSync(path.join(ecAids, entry.name), { recursive: true });
-                fs.copyFileSync(oldMd, newMd);
+        const oldAids = path.join(oldRoot, 'AIDs');
+        const newAids = aidsDir();
+        if (fs.existsSync(oldAids)) {
+            for (const entry of fs.readdirSync(oldAids, { withFileTypes: true })) {
+                if (!entry.isDirectory())
+                    continue;
+                copyDirIfMissing(path.join(oldAids, entry.name), path.join(newAids, entry.name));
             }
         }
+        copyDirIfMissing(path.join(oldRoot, 'CA'), path.join(newRoot, 'CA'));
+        for (const f of ['.seed', '.device_id']) {
+            copyFileIfMissing(path.join(oldRoot, f), path.join(newRoot, f));
+        }
+    }
+    catch { /* best-effort */ }
+    try {
+        fs.writeFileSync(markerPath, new Date().toISOString(), 'utf-8');
+    }
+    catch { }
+}
+/**
+ * 首次运行时从 assets/ 模板拷贝 config.json 和 .env 到 $EVOLCLAW_HOME。
+ * 已存在则跳过，不覆盖用户修改。
+ */
+function seedConfigTemplates() {
+    const root = resolveRoot();
+    const assetsDir = path.join(getPackageRoot(), 'assets');
+    const templates = [
+        { src: 'config.json.template', dst: 'config.json' },
+        { src: '.env.template', dst: '.env' },
+    ];
+    for (const { src, dst } of templates) {
+        const dstPath = path.join(root, dst);
+        if (fs.existsSync(dstPath))
+            continue;
+        const srcPath = path.join(assetsDir, src);
+        if (!fs.existsSync(srcPath))
+            continue;
+        try {
+            fs.copyFileSync(srcPath, dstPath);
+        }
+        catch { /* best-effort */ }
     }
-    catch { /* best-effort migration */ }
 }
 // ── kits 路径（始终从包内读取，不复制到 EVOLCLAW_HOME）──
 export function kitsDir() {

package/dist/utils/npm-ops.js

@@ -84,19 +84,26 @@ export function getLocalVersion() {
 }
 /**
  * 查询 npm registry 上指定包的最新版本。
- * 超时 15 秒，失败返回 null。
+ * 使用 HTTP fetch 直接查 registry API，不依赖 npm CLI。
+ * 超时 10 秒，失败返回 null。
  */
-export function checkLatestVersion(pkg = 'evolclaw') {
-    return new Promise((resolve) => {
-        execFile('npm', ['view', pkg, 'version'], { timeout: 15000 }, (err, stdout) => {
-            if (err) {
-                resolve(null);
-                return;
-            }
-            const ver = stdout.trim();
-            resolve(ver || null);
+export async function checkLatestVersion(pkg = 'evolclaw') {
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 10000);
+        const res = await fetch(`https://registry.npmjs.org/${pkg}/latest`, {
+            signal: controller.signal,
+            headers: { 'Accept': 'application/json' },
         });
-    });
+        clearTimeout(timer);
+        if (!res.ok)
+            return null;
+        const data = await res.json();
+        return data.version || null;
+    }
+    catch {
+        return null;
+    }
 }
 /**
  * 完整升级流程：检查 → 比较 → 安装（失败重试一次）

package/kits/docs/GUIDE.md

@@ -2,14 +2,14 @@
 
 ## 查阅流程
 
-1. 先看 `$KITS_RULES`（自动加载的 8 个规则文件）了解机制骨架
+1. 先看 `$KITS_RULES`（自动加载的 6 个规则文件 01-06）了解机制骨架
 2. 需要详细信息时，按 `INDEX.md` 找到对应文档路径
 3. Read 对应文档
 
 ## 路径解析
 
 文档中用 `$名称` 引用路径。解析步骤：
-1. 查 `$KITS_RULES/01-entry.md` 的路径体系速查表
+1. 查 `$KITS_RULES/02-navigation.md` 的路径体系速查表
 2. 如需完整定义，Read `$KITS_DOCS/path-registry.md`
 3. 如需运行时实际值，Read `$ECK/path-registry.md`
 

package/kits/docs/INDEX.md

@@ -8,6 +8,7 @@
 |------|------|------|
 | 查阅指南 | `GUIDE.md` | 文档查阅流程 |
 | 路径定义 | `path-registry.md` | 所有预定义路径及派生规则 |
+| 上下文组装机制 | `context-assembly.md` | manifest 装配机制：when 条件/合并覆盖/模板渲染/运行时变量/调试输出 |
 
 ## AUN 协议
 
@@ -20,11 +21,14 @@
 
 | 文档 | 路径 | 说明 |
 |------|------|------|
-| Agent 命令 | `evolclaw/AGENT_CMD.md` | agent 全生命周期管理命令 |
-| 运行时工具 | `evolclaw/tools.md` | ctl 命令集 |
+| 私聊消息 | `evolclaw/msg.md` | `ec msg` 私聊收发消息 |
+| 群聊消息 | `evolclaw/group.md` | `ec group` 群聊收发与群管理 |
+| Agent 生命周期 | `evolclaw/agent.md` | `ec agent` 创建/启停/配置/热重载 |
+| AID 身份 | `evolclaw/aid.md` | `ec aid` 身份/证书/名片/探测对端 |
+| 文件存储 | `evolclaw/storage.md` | `ec storage` 上传/下载/配额 |
+| 运行时自管理 | `evolclaw/ctl.md` | `ec ctl` 切模型/推理强度/压缩/重启 |
+| 底层 RPC | `evolclaw/rpc.md` | `ec rpc` 直接调 AUN 协议方法 |
 | 自我总结 | `evolclaw/self-summary.md` | 自我总结流程指南 |
-| 私聊消息 | `evolclaw/MSG_PRIVATE.md` | 私聊消息命令 |
-| 群聊消息 | `evolclaw/MSG_GROUP.md` | 群聊消息命令 |
 
 ## 身份
 
@@ -35,12 +39,12 @@
 | AID 档案规范 | `identity/AID_PROFILE_SPEC.md` | AID 档案格式规范 |
 | 路径运维 | `identity/PATH_OPS.md` | 路径运维操作 |
 
-## 渠道
+## 渠道（知识文档·按需加载，不依赖当前渠道）
 
 | 文档 | 路径 | 说明 |
 |------|------|------|
-| AUN 渠道 | `channels/aun.md` | AUN 通信约定 |
-| 飞书渠道 | `channels/feishu.md` | 飞书渠道接入 |
+| AUN 渠道 | `channels/aun.md` | AUN 渠道配置、参数与特有机制（网关发现/E2EE/群 ID/证书链） |
+| 飞书渠道 | `channels/feishu.md` | 飞书渠道配置、参数与特有机制（appId/合并转发/卡片/user_id） |
 
 ## ECK 模板
 

package/kits/docs/channels/aun.md

@@ -1,25 +1,64 @@
-# AUN 通信约定
+# AUN 渠道
 
-## 消息收发
+> 知识性文档：AUN 渠道的配置、参数与特有机制。**不依赖当前会话渠道**——任意会话都可按需 Read。
+> 运行时"怎么发消息"由注入的 `[channel]` 段决定（aun 渠道用 `ec msg send` / `ec group send`），不在本文。
+> 底层协议方法与 RPC 逃生通道见 `evolclaw/rpc.md`。
 
-- 私聊：`message.send` / `message.receive`
-- 群聊：`group.message.send` / `group.message.receive`
-- 消息格式：纯文本 / Markdown / 文件引用
+## 概述
 
-## 身份识别
+AUN 渠道把 agent 接入 AUN（Agent Union Network），对端以 **AID** 为身份标识（既是身份也是地址）。evolclaw 通过 AUN SDK（`@agentunion/fastaun`）维护到 Gateway 的 WebSocket 长连接，支持私聊、群聊、文件、E2EE 加密。
 
-- 每条入站消息携带发送者 AID
-- 通过 `https://<aid>/agent.md` 获取对端名片
-- 名片包含：名称、能力声明、联系方式
+## 配置
 
-## 连接管理
+AUN 渠道是**隐式**的——它不写在 `channels[]` 数组里，而是从 agent 自身的 AID 自动创建。一个 agent 就是一个 AID，启动时 evolclaw 用顶层 `aid` 字段隐式构造唯一的 aun 实例（`channel-loader.ts`）。所以真实的 agent config.json 里 `channels` 数组通常是空的（飞书等非 aun 渠道才往里加）。
 
-- evolclaw 自动维护 WebSocket 长连接
-- 断线自动重连（SDK 内置退避策略）
-- 连接状态可通过 `evolclaw ctl aid` 查看
+### agent 配置（`agents/<aid>/config.json`）
 
-## 群聊
+```json
+{
+  "$schema_version": 1,
+  "aid": "myagent.agentid.pub",
+  "enabled": true,
+  "owners": ["owner.agentid.pub"],
+  "channels": [],
+  "active_baseagent": "claude"
+}
+```
 
-- 群 ID 格式：`<issuer>/<group-name>`
-- 被 @ 时才默认响应（可通过 venue policy 配置）
-- 群消息按窗口批量推送（batch_window_seconds）
+| 字段 | 说明 |
+|------|------|
+| `aid` | agent 的 AID，**即 aun 渠道身份**（隐式创建，无需在 channels[] 声明） |
+| `enabled` | agent 是否启用 |
+| `owners` | owner 的 **AID** 列表（最高权限）；首个 owner 用于首次连接发欢迎消息 |
+| `admins` | admin 的 AID 列表 |
+| `channels` | 非 aun 渠道（飞书等）的实例数组；aun 不在此 |
+
+> `owners`/`admins` 用 **AID**，不是渠道原生 ID。
+
+### 进程级配置（`$EVOLCLAW_HOME/config.json`）
+
+E2EE 加密种子是**进程级**的，所有 agent 共享，不在 agent config 里：
+
+```json
+{
+  "aun": {
+    "encryptionSeed": "<seed>"
+  }
+}
+```
+
+留空时 SDK 依次回退 `AUN_ENCRYPTION_SEED` 环境变量 → 默认 `'evol'`。
+
+> Gateway 不在配置里手填：连接时从 AID 自动发现（见下）。Keystore 默认落在 `$EVOLCLAW_HOME`。
+
+## 特有机制
+
+- **隐式创建**：aun 渠道由顶层 `aid` 派生，无独立配置实例；这是它与飞书等渠道最大的不同。
+- **网关发现**：连接前查询 `https://<aid>/.well-known/aun-gateway` 获取网关地址（AID 本身即域名）；per-agent 流程不提供手填 gateway 的入口，发现失败即连接失败。
+- **身份与信任**：每条入站消息携带发送者 AID，经四级 X.509 证书链（Root CA → Registry CA → Issuer CA → Agent）验签。
+- **agent.md 缓存**：对端名片 `https://<aid>/agent.md` 由 **AUN SDK 自动拉取并缓存**（`AgentMdManager`，带 ETag/TTL，默认 1 天内不重复探测）。缓存落在 **`$EVOLCLAW_HOME/AIDs/<aid>/`**，每个 AID 两个文件：`agent.md`（带签名正文）+ `agentmd.json`（元数据：etag/last_modified/checked_at/verify_status）。本端与对端的 agent.md 都缓存于此。
+  - 关系层另存一份**派生**的精简身份 `relations/<peerKey>/peer-identity.json`（type/isAgent/name），由 evolclaw 从 agent.md 提取，不是 agent.md 本体。
+- **E2EE 加密**：可选端到端加密，回复默认跟随对端消息加密状态（密文回密文，明文回明文）；种子由进程级 `aun.encryptionSeed` 提供。
+- **断线重连**：SDK 内置退避策略自动重连。实时连接状态用 `ec watch aid` 查看（`ec aid` 是身份/证书管理，不显示连接状态）。
+- **群 ID 格式**：`group.{issuer}/{group_name}`（新格式）或 `{group_no}.{issuer}`（数字群号，如 `11117.agentid.pub`）。
+- **身份体系**：对端以 AID 标识，关系层 peerKey 形如 `aun#alice.aid.pub`。

package/kits/docs/channels/feishu.md

@@ -1,27 +1,56 @@
 # 飞书渠道
 
-<!-- TODO: 填充飞书渠道接入文档 -->
+> 知识性文档：飞书渠道的配置、参数与特有机制。**不依赖当前会话渠道**——任意会话都可按需 Read（在 aun 会话里也可查飞书）。
+> 运行时"怎么发消息"由注入的 `[channel]` 段决定（飞书是 evolclaw 自动回复，agent 不调 CLI），不在本文。
 
 ## 概述
 
-飞书渠道通过 evolclaw 的 feishu channel 实现，支持：
-- 单聊消息收发
-- 群聊消息收发
-- 合并转发消息解析
-- 文件/图片/视频消息
+飞书渠道通过 evolclaw 的 feishu channel 插件接入，对端以飞书 `user_id`（如 `ou_xxx`）为身份标识。支持单聊/群聊收发、合并转发解析、富文本卡片、文件/图片/视频消息。
 
 ## 配置
 
-在 evolclaw 配置中启用飞书渠道：
+飞书渠道按 **per-agent** 配置，写在 `agents/<aid>/config.json` 的 `channels` 数组里。每个元素是一个独立实例，靠 `name` 区分；同一 agent 可配多个飞书实例。
 
 ```json
 {
-  "channels": {
-    "feishu": {
+  "aid": "myagent.aid.pub",
+  "channels": [
+    {
+      "type": "feishu",
+      "name": "main",
       "enabled": true,
-      "appId": "<app-id>",
-      "appSecret": "<app-secret>"
+      "appId": "cli_xxx",
+      "appSecret": "<app-secret>",
+      "owners": ["ou_owner_user_id"],
+      "admins": ["ou_admin_user_id"]
     }
-  }
+  ]
 }
 ```
+
+### 实例字段
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `type` | 是 | 固定 `"feishu"` |
+| `name` | 是（数组形式） | 该 agent 内飞书实例的本地标识，不含 `#` |
+| `enabled` | 否 | 默认启用；`false` 关闭该实例 |
+| `appId` | 是 | 飞书自建应用 App ID |
+| `appSecret` | 是 | 飞书自建应用 App Secret |
+| `owners` | 否 | owner 的飞书 `user_id` 列表（最高权限） |
+| `admins` | 否 | admin 的飞书 `user_id` 列表 |
+| `flushDelay` | 否 | flush 间隔（秒），覆盖全局值 |
+| `debounce` | 否 | 入站消息去抖间隔（秒），覆盖全局值 |
+| `showActivities` | 否 | 思考过程展示范围：`all` / `dm-only` / `owner-dm-only` / `none` |
+
+> `owners`/`admins` 用飞书原生 `user_id`，**不是 AID**。
+
+agent 级（config.json 顶层）相关开关：
+- `enable_rich_content`：启用富文本卡片渲染，默认关闭。
+
+## 特有机制
+
+- **合并转发解析**：飞书的 `merge_forward` 消息会被自动展开为文本注入上下文（含"以下是引用的原消息"包裹）。
+- **交互卡片**：富内容开启时，部分回复以飞书卡片形式发送；卡片按钮**仅发起者可操作**，他人点击返回提示。
+- **身份体系**：对端以 `user_id` 标识，关系层 peerKey 形如 `feishu#ou_xxx`。
+- **自动回复**：飞书是非 aun 渠道，回复由 evolclaw 自动完成，agent 无需调用 `ec msg send`。