evolclaw 3.1.4 → 3.1.6

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

@@ -23,7 +23,7 @@ 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: "selfPeerId#type#name" → "type#selfPeerId#name"
+            // 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);
@@ -52,7 +52,7 @@ export class TriggerManager {
         }
     }
     /**
-     * Detect and fix old format "selfPeerId#type#name" → current "type#selfPeerId#name".
+     * Detect and fix old format "selfAID#type#name" → current "type#selfAID#name".
      * Old format: first segment contains '.' (AID like "evolai.agentid.pub").
      */
     migrateChannelKey(key) {
@@ -63,7 +63,7 @@ export class TriggerManager {
             return key;
         const [first, second, third] = parts;
         if (first.includes('.') && !second.includes('.')) {
-            return formatChannelKey({ type: second, selfPeerId: first, name: third });
+            return formatChannelKey({ type: second, selfAID: first, name: third });
         }
         return key;
     }

package/dist/core/trigger/parser.js

@@ -127,8 +127,8 @@ export function parseTriggerUpdate(args) {
     }
     if (flags.has('session')) {
         const sv = flags.get('session');
-        if (sv !== 'latest' && sv !== 'silent')
-            return { ok: false, error: '--session 只接受 latest 或 silent' };
+        if (sv !== 'latest' && sv !== 'current' && sv !== 'thread')
+            return { ok: false, error: '--session 只接受 latest、current 或 thread' };
         result.targetSessionStrategy = sv;
     }
     if (flags.has('agent')) {
@@ -216,8 +216,8 @@ export function parseTriggerSet(args) {
     let targetSessionStrategy = 'latest';
     if (hasSession) {
         const sv = flags.get('session');
-        if (sv !== 'latest' && sv !== 'silent') {
-            return { ok: false, error: '--session 只接受 latest 或 silent' };
+        if (sv !== 'latest' && sv !== 'current' && sv !== 'thread') {
+            return { ok: false, error: '--session 只接受 latest、current 或 thread' };
         }
         targetSessionStrategy = sv;
     }

package/dist/core/trigger/scheduler.js

@@ -209,11 +209,12 @@ export class TriggerScheduler {
         this.inflightCron.delete(triggerId);
     }
     buildSyntheticMessage(trigger, messageId) {
-        return {
+        const base = {
             channel: trigger.targetChannel,
+            channelType: trigger.targetChannelType,
             channelId: trigger.targetChannelId,
-            selfId: this.aid,
-            threadId: trigger.targetThreadId ?? '',
+            selfAID: this.aid,
+            threadId: '',
             agentId: trigger.agentId,
             chatType: 'private',
             peerId: `__trigger__:${trigger.id}`, // unique per trigger to prevent greedy merge
@@ -221,10 +222,24 @@ export class TriggerScheduler {
             messageId,
             timestamp: Date.now(),
             source: 'trigger',
-            triggerMeta: {
-                triggerId: trigger.id,
-                silent: trigger.targetSessionStrategy === 'silent',
-            },
         };
+        if (trigger.targetSessionStrategy === 'current') {
+            base.triggerMeta = { triggerId: trigger.id, boundSessionId: trigger.boundSessionId };
+        }
+        else if (trigger.targetSessionStrategy === 'thread') {
+            if (trigger.threadKind === 'feishu' && trigger.pendingThread) {
+                base.triggerMeta = { triggerId: trigger.id, pendingThread: true, rootMessageId: trigger.rootMessageId };
+                // threadId intentionally empty — first fire builds the thread via reply_in_thread
+            }
+            else {
+                base.threadId = trigger.targetThreadId ?? '';
+                base.triggerMeta = { triggerId: trigger.id };
+            }
+        }
+        else {
+            // latest
+            base.triggerMeta = { triggerId: trigger.id };
+        }
+        return base;
     }
 }

package/dist/index.js

@@ -26,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';
@@ -452,11 +452,58 @@ async function main() {
             continue;
         const scheduler = agent.triggerScheduler;
         const primaryProjectPath = agent.config.projects?.defaultPath ?? primaryAgent.projectPath;
+        function scheduleRetryWhenIdle(boundId, msg, trigger) {
+            let done = false;
+            const handler = (ev) => {
+                if (ev.sessionId !== boundId || done)
+                    return;
+                done = true;
+                clearTimeout(timer);
+                eventBus.unsubscribe('task:completed', handler);
+                retry();
+            };
+            const timer = setTimeout(() => {
+                if (done)
+                    return;
+                done = true;
+                eventBus.unsubscribe('task:completed', handler);
+                retry();
+            }, 30_000);
+            eventBus.subscribe('task:completed', handler);
+            function retry() {
+                if (messageQueue.isProcessing(boundId)) {
+                    scheduleRetryWhenIdle(boundId, msg, trigger);
+                    return;
+                }
+                sessionManager.getSessionById(boundId).then(bound => {
+                    if (!bound) {
+                        logger.warn(`[Trigger] Bound session ${boundId} deleted, aborting`);
+                        return;
+                    }
+                    messageQueue.enqueue(boundId, msg, bound.projectPath, { interruptible: false })
+                        .catch(err => logger.error(`[Trigger] Retry failed ${trigger.id}: ${err}`));
+                });
+            }
+        }
         scheduler.setFireCallback((msg, trigger) => {
-            const sessionKey = `${msg.channel}:${msg.channelId}`;
-            messageQueue.enqueue(sessionKey, msg, primaryProjectPath, { interruptible: false }).catch(err => {
-                logger.error(`[Trigger] Failed to enqueue trigger ${trigger.id}: ${err}`);
-            });
+            if (trigger.targetSessionStrategy === 'current' && trigger.boundSessionId) {
+                const boundId = trigger.boundSessionId;
+                if (messageQueue.isProcessing(boundId)) {
+                    scheduleRetryWhenIdle(boundId, msg, trigger);
+                    return;
+                }
+                sessionManager.getSessionById(boundId).then(bound => {
+                    if (!bound) {
+                        logger.warn(`[Trigger] Bound session ${boundId} not found`);
+                        return;
+                    }
+                    messageQueue.enqueue(boundId, msg, bound.projectPath, { interruptible: false })
+                        .catch(err => logger.error(`[Trigger] Enqueue failed ${trigger.id}: ${err}`));
+                });
+                return;
+            }
+            messageQueue.enqueue(`${msg.channel}:${msg.channelId}`, msg, primaryProjectPath, { interruptible: false })
+                .catch(err => logger.error(`[Trigger] Enqueue failed ${trigger.id}: ${err}`));
         });
         // Subscribe to trigger:completed/failed/skipped to update cron inflight state
         eventBus.subscribe('trigger:completed', (ev) => scheduler.onTriggerComplete(ev.triggerId, 'completed'));
@@ -504,7 +551,7 @@ async function main() {
                     nextFireAt: calcNextFireAt('cron', cronExpr),
                     targetChannel: firstChannel,
                     targetChannelId: '__system__',
-                    targetSessionStrategy: 'silent',
+                    targetSessionStrategy: 'latest',
                     prompt: '检查 evolclaw 是否有新版本可用。执行 `npm view evolclaw version` 获取最新版本，与当前版本（执行 `evolclaw --version`）对比。如果有新版本，执行 /restart 进行升级。如果已是最新版本，无需任何操作。',
                     createdByPeerId: '__system__',
                     createdByChannel: '__system__',
@@ -553,7 +600,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);
@@ -755,8 +803,11 @@ async function main() {
                 continue;
             }
             logger.info(`[Resume] Resuming session: ${session.id} (agent: ${evolName}::${baseagentName})`);
+            const parsedResumeKey = tryParseChannelKey(session.channel);
             const resumeMessage = {
                 channel: session.channel,
+                channelType: session.channelType || parsedResumeKey?.type,
+                selfAID: parsedResumeKey?.selfAID,
                 channelId: session.channelId,
                 content: '服务已重启，请继续之前未完成的任务。',
                 timestamp: Date.now(),
@@ -866,6 +917,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)) {
@@ -88,7 +93,7 @@ export class IpcServer {
             case 'status':
                 return this.getStatus();
             case 'ping':
-                return { pong: true, pid: process.pid };
+                return { pong: true, pid: process.pid, protocolVersion: 1 };
             case 'aun-aids': {
                 const aids = this.aunAidProvider ? this.aunAidProvider() : [];
                 return { ok: true, aids };
@@ -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/utils/error-utils.js

@@ -10,6 +10,7 @@ export var ErrorType;
     ErrorType["FILE_CORRUPT"] = "file_corrupt";
     ErrorType["STREAM_ERROR"] = "stream_error";
     ErrorType["CONTEXT_TOO_LONG"] = "context_too_long";
+    ErrorType["MODEL_UNAVAILABLE"] = "model_unavailable";
     ErrorType["UNKNOWN"] = "unknown";
 })(ErrorType || (ErrorType = {}));
 /**
@@ -210,6 +211,11 @@ export function classifyError(error) {
         || msg.includes('上下文过长')) {
         return ErrorType.CONTEXT_TOO_LONG;
     }
+    if (msg.includes('invalid_model') || msg.includes('model_not_found')
+        || msg.includes('no such model') || msg.includes('unknown model')
+        || /api error: 404\b/.test(msg)) {
+        return ErrorType.MODEL_UNAVAILABLE;
+    }
     if (msg.includes('401') || msg.includes('authentication_error')) {
         return ErrorType.AUTH_ERROR;
     }

package/dist/utils/process-introspect.js

@@ -51,18 +51,20 @@ function getStartTimeLinux(pid) {
     const starttimeJiffies = parseInt(fields[19], 10);
     if (isNaN(starttimeJiffies))
         return null;
-    let uptimeSec;
+    let btimeSec;
     try {
-        uptimeSec = parseFloat(fs.readFileSync('/proc/uptime', 'utf-8').split(' ')[0]);
+        const m = fs.readFileSync('/proc/stat', 'utf-8').match(/^btime (\d+)/m);
+        if (!m)
+            return null;
+        btimeSec = parseInt(m[1], 10);
     }
     catch {
         return null;
     }
-    if (isNaN(uptimeSec))
+    if (isNaN(btimeSec))
         return null;
     const clkTck = 100;
-    const bootTimeMs = Date.now() - uptimeSec * 1000;
-    return bootTimeMs + (starttimeJiffies / clkTck) * 1000;
+    return (btimeSec + starttimeJiffies / clkTck) * 1000;
 }
 // ── macOS ──
 function getStartTimeMacOS(pid) {

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 协议
 
@@ -18,13 +19,12 @@
 
 ## EvolClaw 命令
 
+所有 `ec` 命令集的专属目录（用途/触发词/适用场景/文档）见 `evolclaw/INDEX.md`。
+运行时由 `commands` fragment 按场景注入精简能力卡。
+
 | 文档 | 路径 | 说明 |
 |------|------|------|
-| Agent 命令 | `evolclaw/AGENT_CMD.md` | agent 全生命周期管理命令 |
-| 运行时工具 | `evolclaw/tools.md` | ctl 命令集 |
-| 自我总结 | `evolclaw/self-summary.md` | 自我总结流程指南 |
-| 私聊消息 | `evolclaw/MSG_PRIVATE.md` | 私聊消息命令 |
-| 群聊消息 | `evolclaw/MSG_GROUP.md` | 群聊消息命令 |
+| 命令集目录 | `evolclaw/INDEX.md` | msg/group/agent/aid/storage/ctl/rpc/model/bench 全集索引 |
 
 ## 身份
 
@@ -35,12 +35,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`。