@jesonliu/lark-claudecode-bridge 0.18.1 → 0.20.0

package/dist/index.js

@@ -1,7 +1,7 @@
 // 装配主流程：消息 → 访问控制 → 命令 → 通道队列 → 执行 → 确认卡片 → 回传
 import { randomUUID } from 'node:crypto';
-import { existsSync } from 'node:fs';
-import { basename, join, resolve } from 'node:path';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { basename, join, resolve, sep } from 'node:path';
 import { CONFIG_DIR, CONFIG_PATH, DEFAULT_CONTEXT_REMIND_TOKENS, loadConfig, sameApps } from './config.js';
 import { DEFAULT_CLAUDE_DIR, resolveClaudeDir } from './claude-config.js';
 import { warnIfNoClaudeAuth } from './auth-precheck.js';
@@ -11,12 +11,14 @@ import { clearPidFile, writePidFile, stopExistingBridgeAndWait } from './web/lif
 import { AccessControl } from './access/access-control.js';
 import { FeishuGateway } from './gateway/feishu-gateway.js';
 import { ProgressCard } from './gateway/progress-card.js';
-import { DECISION_TEXT, buildPlanCards, buildPlanResultCard, buildExpiredPlanCard, PROGRESS_TAIL_CHARS, buildQuestionCard, buildQuestionResultCard, buildExpiredQuestionCard, } from './gateway/card-builder.js';
+import { DECISION_TEXT, PROGRESS_TAIL_CHARS, LONG_OUTPUT_THRESHOLD, buildLongOutputCard, buildLongOutputSettledCard, } from './gateway/card-builder.js';
 import { buildDiffSummaryCards } from './gateway/diff-card.js';
 import { runTask } from './executor/claude-executor.js';
 import { PermissionGate, DEFAULT_ALLOW_TOOLS_LIST, DEFAULT_DANGEROUS_COMMANDS, } from './executor/permission-gate.js';
 import { discoverPlugins, resolvePluginPaths } from './executor/plugin-discovery.js';
 import { createGatewaySender, createNotifyServer, NOTIFY_SERVER_NAME } from './executor/notify-server.js';
+import { BRIDGE_MCP_JSON, readMcpServersFromJsonFile } from './web/skills-mcp-api.js';
+import { FEISHU_NOTIFY_SOP_PROMPT } from './notify-sop.js';
 import { collectWorkspaceDiff } from './util/workspace-diff.js';
 import { isImageFile } from './util/file-types.js';
 import { FileTracker } from './util/file-tracker.js';
@@ -53,7 +55,31 @@ const PLAN_DECISION_TEXT = {
     'plan-approve': '✅ 计划已批准，开始执行（后续写操作免确认）',
     'plan-revise': '📝 修改意见已提交',
     'plan-reject': '❌ 计划已放弃',
+    // plan-view-file 不消费挂起项，仅 toast「正在发送方案文件…」——文案不在此出现，留口供编译期完整性
+    'plan-view-file': '',
 };
+/**
+ * 运行期文档落盘（plan 方案 / 超长回复共用）：CONFIG_DIR 下按子目录 + 时间戳 + 工作区
+ * slug 命名，返回文件路径；写盘失败返回 ''（调用方回退降级行为，不影响主流程）
+ */
+function writeRuntimeMarkdown(subDir, slugBase, content, logTag) {
+    const dir = join(CONFIG_DIR, subDir);
+    try {
+        mkdirSync(dir, { recursive: true });
+    }
+    catch { /* 已存在 */ }
+    const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const slug = (slugBase || subDir).replace(/[^\w-]+/g, '_').slice(0, 32);
+    const filePath = join(dir, `${ts}-${slug}.md`);
+    try {
+        writeFileSync(filePath, content, 'utf8');
+        return filePath;
+    }
+    catch (e) {
+        console.error(logTag, e);
+        return '';
+    }
+}
 export function createBridge(config, app, // 本 bridge 绑定的飞书应用：并发/默认工作区/Claude Code 环境/人格均 per-app
 deps, opts = {}) {
     const sem = new Semaphore(app.concurrency ?? config.concurrency);
@@ -85,10 +111,18 @@ deps, opts = {}) {
     // 用于实现「默认不发非图片文件，用户主动点名才发」的回传规则
     const fileTracker = new FileTracker();
     const confirmPending = new Map();
-    // plan 确认挂起项：requestId → 等待中的计划决策（plan-approve/revise/reject）
+    // plan 确认挂起项：requestId → 等待中的计划决策（plan-approve/revise/reject）。
+    // 嵌入主卡片后回调侧无 cardId（主卡 messageId 由 ProgressCard 内部管理），改带 channelKey 定位活跃进度卡
     const planPending = new Map();
-    // 提问挂起项：requestId → 等待中的问题答案（qa-pick 逐项收集，qa-submit 一次性 resolve）
+    // 提问挂起项：requestId → 等待中的问题答案（qa-pick 逐项收集，qa-submit 一次性 resolve）。
+    // 嵌入主卡片后无 cardId，改带 channelKey 定位活跃进度卡
     const qaPending = new Map();
+    // 长回复卡挂起项（0.20.0）：requestId → 收起卡的查看/确认/提意见上下文。与 planPending
+    // 不同——无 Promise 要 resolve（任务已结束，确认/提意见是「发起新一轮」），条目仅用于：
+    // 发起人校验（仅任务发起人可操作）、settled 防重（确认/提意见只生效一次，查看可反复）、
+    // filePath/workspaceName 上下文。条目常驻供用户回看历史卡片时再次查看全文（量级：每次
+    // 超长回复一条，几十字节；超 500 条清最老，防无界增长）
+    const outputPending = new Map();
     // 通道当前任务的进度卡：gate 的 ask/planAsk/askQuestion 闭包随 gate 通道级复用，
     // 不能捕获任务级 progress 实例（会是首个任务的旧卡）——经此间接引用每次任务的新卡
     const activeProgress = new Map();
@@ -98,18 +132,28 @@ deps, opts = {}) {
     function workspacePath(name) {
         return config.workspaces.find((w) => w.name === name)?.path ?? config.workspaces[0].path;
     }
+    /** 配置页管理的 MCP（#12）：bridge 自管 mcp/servers.json 每任务现读注入 SDK（改配置即热生效，
+     *  无须重启）。notify 名固定后展开防被用户配置同名覆盖；文件缺失/损坏返回空（配置页写坏
+     *  不应拖垮任务执行） */
+    function loadBridgeMcpServers() {
+        return readMcpServersFromJsonFile(BRIDGE_MCP_JSON).servers;
+    }
     /** 通道内串行入队（每 key 一条 Promise 链），全局并发由 Semaphore 限制。
      *  有任务在跑时新消息静默 FIFO 排队——不提示的话用户不知道消息已被接收，会反复重发或误以为丢失。
-     *  queuedCount 计「等待中」消息数：enqueue 一律自增（含首位），executeTask 启动时递减（该条离开队列） */
+     *  queuedCount 计「等待中」消息数：enqueue 一律自增（含首位），executeTask 启动时递减（该条离开队列）。
+     *  /new 通过 epoch 代际丢弃旧排队消息：enqueue 捕获当前 epoch 传入 executeTask，不匹配则 no-op */
     function enqueue(key, msg, prompt, wsName) {
         const rt = runtimes.get(key) ?? { queue: Promise.resolve() };
+        if (rt.epoch === undefined)
+            rt.epoch = 0; // 旧状态无 epoch 字段的运行期兜底
         runtimes.set(key, rt);
         rt.queuedCount = (rt.queuedCount ?? 0) + 1;
         if (rt.busy) {
             void deps.gateway.sendTextTo(msg.chatId, `⏳ 当前有任务在运行，本条消息已排队（第 ${rt.queuedCount} 位），完成后自动开始`)
                 .catch(() => { }); // 提示失败静默：不影响任务本身入队
         }
-        rt.queue = rt.queue.then(() => executeTask(key, msg, prompt, wsName)).catch((e) => {
+        const myEpoch = rt.epoch; // 闭包捕获本条消息入队时的代际；executeTask 据此判断是否被 /new 作废
+        rt.queue = rt.queue.then(() => executeTask(key, msg, prompt, wsName, myEpoch)).catch((e) => {
             console.error(tag, '[任务异常]', e);
         });
     }
@@ -152,17 +196,32 @@ deps, opts = {}) {
         // 命中后拦截不再交给 Claude Code——避免模型重复 send_file 同一文件造成轰炸
         if (await tryDeliverRequestedFiles(msg, key))
             return;
-        // 1. 访问控制：白名单外发配对码（首个配对成功者自动成为 admin，见 AccessControl）
+        // 1. 访问控制：白名单外首个使用者自动成为 admin（免配对），其后未知用户发配对码
         // 每条消息先重读 access.json：lcb pair / 运行终端等独立进程批准写盘后，
         // 长存的内存实例不 reload 会查到旧白名单 → 反复发配对码且整盘覆写抹掉新用户（死循环）
         deps.access.reload();
         // 配置热重载：lcb ws add/remove 独立进程写盘后，本实例下一条消息即读到新工作区
         opts.reloadConfig?.();
         if (!deps.access.isAllowed(msg.userId)) {
-            const code = deps.access.beginPairing(msg.userId, msg.userId);
-            console.log(`${tag}[配对] 未知用户 ${msg.userId} 请求接入，配对码：${code}（在终端输入 lcb pair ${code} 批准）`);
-            await deps.gateway.sendTextTo(msg.chatId, `🔐 首次使用需配对。\n\n请管理员在桥接器终端确认配对码：**${code}**（15 分钟内有效）`);
-            return;
+            // 首个使用者免配对直接成为 admin——按应用判定：多应用部署下 open_id 按应用隔离，
+            // 新应用的第一个使用者同样是「首个」，不应因别的应用已有用户而被配对码拦住
+            if (!deps.access.hasUsers(app.appId)) {
+                deps.access.addUser(msg.userId, msg.userId, 'admin', app.appId);
+                console.log(`${tag}[接入] 应用 ${app.appId} 首位用户 ${msg.userId} 已自动成为 admin（后续用户需配对）`);
+                await deps.gateway.sendTextTo(msg.chatId, `🎉 欢迎！你是本机器人的首位用户，已自动成为 **admin**。\n\n后续其他同事首次使用时需由你在桥接器终端批准配对（\`lcb pair <配对码>\`）。`);
+                // 不 return：欢迎语之外，本条消息照常进入命令/任务处理
+            }
+            else {
+                const code = deps.access.beginPairing(msg.userId, msg.userId, app.appId);
+                console.log(`${tag}[配对] 未知用户 ${msg.userId} 请求接入，配对码：${code}（在终端输入 lcb pair ${code} 批准）`);
+                await deps.gateway.sendTextTo(msg.chatId, `🔐 首次使用需配对。\n\n请管理员在桥接器终端确认配对码：**${code}**（15 分钟内有效）`);
+                return;
+            }
+        }
+        else {
+            // 老版本 access.json 的用户记录没有 appId：按当前来路补登，
+            // 保证 hasUsers(appId) 的按应用统计对存量用户同样成立
+            deps.access.ensureAppId(msg.userId, app.appId);
         }
         // 2. 命令：/help /new /resume /stop /status /ws
         const st = deps.store.getChannelState(key);
@@ -215,17 +274,61 @@ deps, opts = {}) {
         if (cmd.handled) {
             if (cmd.reply)
                 await deps.gateway.sendTextTo(msg.chatId, cmd.reply);
-            // /new 开启新会话：「本次会话不再询问」的授权随之失效（handleCommand 无权访问 wiring
-            // 持有的 gate，故在命令处理分支后于 wiring 侧检测并 reset）
-            if (/^\/new(?:\s|$)/.test(msg.text.trim()))
+            // /new 开启新会话：
+            // 1) 清空旧代际排队消息（epoch 自增，旧任务入 executeTask 即 no-op）
+            // 2) abort 正在执行的任务
+            // 3) 结算本用户挂起的 confirm/plan/qa 条目（按取消/拒绝处理：对话继续推进或被放弃）
+            // 4) 通道级权限闸 reset（spec：「本次会话不再询问」的记忆跨任务生效，直至 /new）
+            // 5) 汇总已取消的排队消息数（用户能看到新建会话的真实影响面）
+            // ——handleCommand 无权访问 wiring 的 runtime/pending map，统一在 wiring 侧做
+            if (/^\/new(?:\s|$)/.test(msg.text.trim())) {
+                const rt = runtimes.get(key);
+                const cancelled = rt?.queuedCount ?? 0;
+                if (rt) {
+                    rt.epoch = (rt.epoch ?? 0) + 1;
+                    rt.queuedCount = 0; // 旧代际消息在 executeTask 入口 no-op，不会再 decrement；此处一次性清零即可
+                    if (rt.abort)
+                        rt.abort.abort();
+                }
+                for (const [id, p] of confirmPending) {
+                    if (p.channelKey !== key)
+                        continue;
+                    confirmPending.delete(id);
+                    p.resolve('deny');
+                }
+                for (const [id, p] of planPending) {
+                    if (p.channelKey !== key)
+                        continue;
+                    planPending.delete(id);
+                    p.resolve({ action: 'reject' });
+                }
+                for (const [id, p] of qaPending) {
+                    if (p.channelKey !== key)
+                        continue;
+                    qaPending.delete(id);
+                    p.resolve({});
+                }
+                // 本用户在本会话的长回复卡确认/提意见按钮一并失效（保留查看全文）：新会话已无
+                // 「上一轮方案」上下文，旧确认按钮再触发只会得到脱离语境的新一轮任务
+                for (const o of outputPending.values()) {
+                    if (o.chatId === msg.chatId && o.ownerId === msg.userId)
+                        o.settled = true;
+                }
                 gates.get(key)?.reset();
+                if (cancelled > 0) {
+                    await deps.gateway.sendTextTo(msg.chatId, `🗑️ 已因新建会话取消 ${cancelled} 条排队消息`);
+                }
+            }
             return;
         }
         // 3. 普通文本：通道内串行入队（每 key 一条 Promise 链），全局并发由 Semaphore 限制
         enqueue(key, msg, cmd.taskText ?? msg.text, currentWorkspace);
     }
-    async function executeTask(key, msg, prompt, wsName) {
+    async function executeTask(key, msg, prompt, wsName, myEpoch) {
         const rt = runtimes.get(key);
+        // /new 丢弃旧代际：静默 no-op（不入队列、不 decrement、不建进度卡；汇总条数已在 /new 时回）
+        if (myEpoch !== (rt.epoch ?? 0))
+            return;
         rt.busy = true; // enqueue 据此给后续消息发「已排队」提示（sem 等待期同样算占用）
         rt.queuedCount = Math.max(0, (rt.queuedCount ?? 1) - 1); // 本条离开等待队列开始执行
         const release = await sem.acquire();
@@ -237,7 +340,18 @@ deps, opts = {}) {
             deleteCard: deps.gateway.deleteCard
                 ? (id) => deps.gateway.deleteCard(id)
                 : undefined,
-        }, `任务 · ${wsName}`);
+            sendCardEntity: deps.gateway.sendCardEntityTo
+                ? (c) => deps.gateway.sendCardEntityTo(msg.chatId, c)
+                : undefined,
+            partialUpdateCard: deps.gateway.partialUpdateCardElements
+                ? (cardId, seq, actions) => deps.gateway.partialUpdateCardElements(cardId, seq, actions)
+                : undefined,
+            replaceCard: deps.gateway.replaceCardEntity
+                ? (cardId, seq, c) => deps.gateway.replaceCardEntity(cardId, seq, c)
+                : undefined,
+        }, `任务 · ${wsName}`, 
+        // card.width 热生效：每任务现读 config（与同款「同对象 mutate 即生效」语义一致）
+        { cardWidthMode: config.card?.width ?? 'default' });
         const confirmTimeoutMs = opts.confirmTimeoutMs ?? CONFIRM_TIMEOUT_MS;
         const cardSendTimeoutMs = opts.cardSendTimeoutMs ?? CARD_SEND_TIMEOUT_MS;
         // 通道级复用：已存在则沿用（allow-session 记忆跨任务），不存在才建。
@@ -279,30 +393,30 @@ deps, opts = {}) {
                             },
                             req,
                             ownerId: msg.userId,
+                            channelKey: key,
                             onSettled: settle,
                         });
                     });
                 },
-                // plan 确认：发计划卡片组（首卡带按钮+输入框）挂起等待；超时自动放弃。
-                // chatId/userId 绑定构造时任务——通道 key = chatId+userId，同通道内固定，闭包安全
+                // plan 确认（#3+#6）：不再单独发计划卡片组。计划正文先落盘到 ~/.lark-claudecode-bridge/claude/plans/
+                // （slug + 时间戳，方便后续 review 与 SOP 要求的 plan 本地归档），然后嵌入当前任务的进度卡：
+                // 卡片正文仅露 600 字预览 + 「查看完整方案」按钮（callback send_file 发送原 md 文件，不塞卡片正文
+                // ——飞书单卡 30KB 上限与可读性都不允许长方案铺在卡片里）；批准/放弃/按意见修改三按钮与意见输入框
+                // 仍在主卡片的内嵌 form 内。超时由本闭包自管：到点 clearPlan + resolve reject
                 planAsk: async (req) => {
                     const planReq = { requestId: randomUUID(), plan: req.plan, workspaceName: req.workspaceName };
-                    const ids = [];
-                    for (const c of buildPlanCards(planReq)) {
-                        const id = await raceFallback(deps.gateway.sendCardTo(msg.chatId, c), cardSendTimeoutMs, '');
-                        if (!id) {
-                            void deps.gateway.sendTextTo(msg.chatId, '⚠️ 计划卡发送失败，本次计划已自动放弃；模型重新提交计划时会再次弹出')
-                                .catch(() => { });
-                            return { action: 'reject' };
-                        }
-                        ids.push(id);
-                    }
-                    const cardId = ids[0];
-                    void activeProgress.get(key)?.sinkToBottom();
+                    // 落盘计划原文：路径走 ensureRuntimeDirs 已建的 claude/plans 目录，文件名加时间戳避免并发冲突
+                    const planFilePath = writeRuntimeMarkdown(join('claude', 'plans'), req.workspaceName || 'plan', `# 执行计划 · ${req.workspaceName} · ${new Date().toLocaleString('zh-CN', { hour12: false })}\n\n${req.plan}\n`, `${tag}[计划落盘失败]（不影响流程，仅「查看完整方案」可能不可用）：`);
+                    const progress = activeProgress.get(key);
+                    if (!progress)
+                        return { action: 'reject' }; // 进度卡不在 = 任务已结束/被 abort，按放弃处理
+                    progress.setPlan({ requestId: planReq.requestId, plan: req.plan, workspaceName: req.workspaceName, planFilePath });
+                    // 不再 sinkToBottom：plan 区嵌入主进度卡，flush 自然 PATCH，删旧卡重发只会让用户看到计划区跳一下
                     return new Promise((resolve) => {
                         const gc = setTimeout(() => {
                             planPending.delete(planReq.requestId);
-                            void deps.gateway.updateCard(cardId, buildExpiredPlanCard(planReq, confirmTimeoutMs)).catch(() => { });
+                            progress.setPlan(undefined);
+                            progress.setStatus(`⏰ 计划确认超时（${Math.round(confirmTimeoutMs / 60000)} 分钟未确认），已自动放弃；模型重新提交计划时会再次弹出`);
                             resolve({ action: 'reject' });
                         }, confirmTimeoutMs);
                         gc.unref();
@@ -313,12 +427,14 @@ deps, opts = {}) {
                             },
                             req: planReq,
                             ownerId: msg.userId,
-                            cardId,
+                            channelKey: key,
+                            chatId: msg.chatId,
+                            planFilePath,
                         });
                     });
                 },
-                // 提问确认：AskUserQuestion 的问题选项卡（每问选项按钮 + 提交）；qa-pick 逐项
-                // 更新选中态（PATCH 重渲染），qa-submit 全部作答后一次性 resolve。超时自动跳过
+                // 提问确认（#3）：AskUserQuestion 的选项 + 提交按钮全部嵌入主进度卡（#3 决策：彻底替换独立提问卡）。
+                // qa-pick 仅 PATCH 选中态（卡片不刷新整卡，仅更新 answer map），qa-submit 一次性 resolve 并 clearQuestion
                 askQuestion: async (req) => {
                     const qaReq = {
                         requestId: randomUUID(),
@@ -326,18 +442,16 @@ deps, opts = {}) {
                         workspaceName: req.workspaceName,
                     };
                     const answers = {};
-                    // 发卡失败/超时返回空答案：gate 对空答案统一按「未作答」deny，模型自行决策或停下等待
-                    const cardId = await raceFallback(deps.gateway.sendCardTo(msg.chatId, buildQuestionCard(qaReq, answers)), cardSendTimeoutMs, '');
-                    if (!cardId) {
-                        void deps.gateway.sendTextTo(msg.chatId, '⚠️ 提问卡发送失败，已按未作答处理；模型会自行决策或停下等待你的回复')
-                            .catch(() => { });
-                        return {};
-                    }
-                    void activeProgress.get(key)?.sinkToBottom();
+                    const progress = activeProgress.get(key);
+                    if (!progress)
+                        return {}; // 进度卡不在 = 任务已结束/被 abort，按未作答处理
+                    progress.setQuestion({ requestId: qaReq.requestId, questions: req.questions, workspaceName: req.workspaceName, answers });
+                    // 不再 sinkToBottom：提问区嵌入主进度卡后，flush 自然 PATCH（理由同 planAsk 上方注释）
                     return new Promise((resolve) => {
                         const gc = setTimeout(() => {
                             qaPending.delete(qaReq.requestId);
-                            void deps.gateway.updateCard(cardId, buildExpiredQuestionCard(qaReq, confirmTimeoutMs)).catch(() => { });
+                            progress.setQuestion(undefined);
+                            progress.setStatus(`⏰ 提问超时（${Math.round(confirmTimeoutMs / 60000)} 分钟未作答），已按未作答处理；模型自行决策或停下等待你的回复`);
                             resolve({});
                         }, confirmTimeoutMs);
                         gc.unref();
@@ -348,7 +462,8 @@ deps, opts = {}) {
                             },
                             req: qaReq,
                             ownerId: msg.userId,
-                            cardId,
+                            channelKey: key,
+                            chatId: msg.chatId,
                             answers,
                         });
                     });
@@ -363,6 +478,8 @@ deps, opts = {}) {
         // lcb-notify 发送能力：chatId 硬绑定当前任务（权限闸直通的安全前提）；
         // sentPaths 记录中途已推送的文件，任务收尾的产出回传据此去重（用户已收过的不重发）。
         // 每次中途推送后进度卡沉底一次（删旧卡重发），保持「任务是否还在跑」始终可见于会话底部
+        // SOP 开关：本任务级现读 config.session.notifySop（缺省 true），决定后续 sendText 是否被强制降级
+        const sopEnabled = config.session?.notifySop !== false;
         const sentPaths = new Set();
         const sink = async () => { await activeProgress.get(key)?.sinkToBottom(); };
         const notifySender = createGatewaySender({
@@ -384,6 +501,10 @@ deps, opts = {}) {
                 await deps.gateway.uploadAndSendFile(c, p);
                 await sink();
             },
+        }, {
+            enabled: sopEnabled,
+            // #11 SOP 提示文案前缀（用户看到的「为什么自动转附件」提示）
+            sopTag: '⚠️ 推送上限',
         });
         activeProgress.set(key, progress);
         try {
@@ -405,15 +526,22 @@ deps, opts = {}) {
                 resumeSessionId: resumeId,
                 signal: abort.signal,
                 env: appEnv,
-                appendSystemPrompt: app.appendSystemPrompt,
-                // code-dev 工作区统一 plan mode：模型先出计划（ExitPlanMode → planAsk 飞书卡片），
-                // 用户批准后 SDK 自动切回可编辑模式继续执行
-                ...(config.workspaces.find((w) => w.name === wsName)?.type === 'code-dev' ? { permissionMode: 'plan' } : {}),
+                // #11 SOP 软约束：app.appendSystemPrompt 后追加 SOP 摘要（关闭时仅传 app 原有部分）
+                appendSystemPrompt: (() => {
+                    const base = app.appendSystemPrompt?.trim() ?? '';
+                    if (!sopEnabled)
+                        return base || undefined;
+                    return base ? `${base}\n\n${FEISHU_NOTIFY_SOP_PROMPT}` : FEISHU_NOTIFY_SOP_PROMPT;
+                })(),
+                // 计划模式（#6）：通道级 /plan 开关——模型先出计划（ExitPlanMode → planAsk 飞书卡片），
+                // 用户批准后 SDK 自动切回可编辑模式继续执行（替代旧工作区 code-dev 类型）
+                ...(state?.planMode ? { permissionMode: 'plan' } : {}),
                 // 通道级模型覆盖（/model 设置，每任务现读——改完下一条消息即生效）；未设 = 跟随 ~/.claude 全局
                 ...(state?.model ? { model: state.model } : {}),
                 // 进程内通知工具（send_text/send_image/send_file）：中间产物实时推给当前聊天。
-                // server 实例按任务构造，chatId 在 sender 闭包内硬绑定——模型无法选择接收者
-                mcpServers: { [NOTIFY_SERVER_NAME]: createNotifyServer(notifySender) },
+                // server 实例按任务构造，chatId 在 sender 闭包内硬绑定——模型无法选择接收者。
+                // 配置页 MCP（#12）一并注入：bridge 自管 servers.json 每任务现读（热生效），notify 后展开保名
+                mcpServers: { ...loadBridgeMcpServers(), [NOTIFY_SERVER_NAME]: createNotifyServer(notifySender) },
                 // 插件：config.yaml 显式配置（开发期指源码目录）+ Claude 配置目录已启用的 marketplace
                 // 插件自动发现，同名显式优先；SDK 对无效路径静默跳过，实际加载以 init 清单（/plugins 命令）为准。
                 // managed 模式合并发现两处目录（自管 + 本机 ~/.claude）：按绝对 installPath 传 SDK，
@@ -510,7 +638,33 @@ deps, opts = {}) {
             // 而 textTail 按序累积全部流式文本块、卡片取尾部 PROGRESS_TAIL_CHARS 字——finalText 不超上限时
             // 必然完整落在进度卡终态里，再发一条就是内容几乎逐字相同的重复消息（0.11.0 修复的双推 bug）
             if (outcome.finalText && outcome.finalText.length > PROGRESS_TAIL_CHARS) {
-                await deps.gateway.sendTextTo(msg.chatId, outcome.finalText.slice(0, 4000));
+                // 结果回传（0.20.0 三段式）：
+                // - 400 字内：进度卡终态已完整展示，不发独立消息（0.11.0 双推修复）
+                // - 400~2000 字：直接发全文卡片（旧 slice 上限对这段区间本就不触发）
+                // - >2000 字：落盘 md + 收起卡（查看全文按钮 + 确认方案/按意见修改引导，点击
+                //   即发起新一轮任务），替代旧版 4000 字硬截断——超长部分不再静默丢弃
+                const text = outcome.finalText;
+                if (text.length > LONG_OUTPUT_THRESHOLD) {
+                    const outFilePath = writeRuntimeMarkdown('outputs', wsName, `# 完整回复 · ${wsName} · ${new Date().toLocaleString('zh-CN', { hour12: false })}\n\n${text}\n`, `${tag}[长回复落盘失败，回退为截断发送]：`);
+                    if (outFilePath) {
+                        const outReq = {
+                            requestId: randomUUID(), filePath: outFilePath,
+                            charCount: text.length, workspaceName: wsName,
+                        };
+                        outputPending.set(outReq.requestId, { req: outReq, ownerId: msg.userId, chatId: msg.chatId, settled: false });
+                        if (outputPending.size > 500) {
+                            // 防无界增长：清最老的条目（Map 迭代序即插入序；被清卡片的确认按钮会提示已过期）
+                            outputPending.delete(outputPending.keys().next().value);
+                        }
+                        await deps.gateway.sendCardTo(msg.chatId, buildLongOutputCard(outReq));
+                    }
+                    else {
+                        await deps.gateway.sendTextTo(msg.chatId, text.slice(0, 4000)); // 落盘失败兜底：维持旧截断行为
+                    }
+                }
+                else {
+                    await deps.gateway.sendTextTo(msg.chatId, text);
+                }
             }
             // 图片自动发（im.image.create 通道），非图片文件不自动回传——
             // 用户从下面的文件清单里看到改了哪些文件，主动点名 basename 后由 tryDeliverRequestedFiles 处理
@@ -532,18 +686,12 @@ deps, opts = {}) {
                 await deps.gateway.sendTextTo(msg.chatId, `📁 本次修改/新增的文件（共 ${outcome.producedFiles.length} 个）：\n${list}`);
             }
             await uploadProducedImages();
-            // code-dev 工作区额外发汇总 diff 卡片（git diff 不是文件本身，不冲突）；
-            // 非 git 仓库 wsDiff===null 时只发图片、不再回退上传非图片
-            const isCodeDev = config.workspaces.find((w) => w.name === wsName)?.type === 'code-dev';
-            if (isCodeDev) {
-                const wsDiff = await collectWorkspaceDiff(workspacePath(wsName));
-                if (wsDiff === null) {
-                    console.warn(tag, `[任务收尾] 工作区 ${wsName} 不是 git 仓库，非图片文件不再自动发送（git init 后可改用汇总 diff 卡片）`);
-                }
-                else if (wsDiff.diff.trim()) {
-                    for (const c of buildDiffSummaryCards(wsDiff.diff, { workspaceName: wsName, files: wsDiff.files })) {
-                        await deps.gateway.sendCardTo(msg.chatId, c);
-                    }
+            // 汇总 diff 收尾卡片（#6 起不再依赖工作区类型）：工作区是 git 仓库且有改动才发——
+            // git 仓库即「代码工作区」的客观信号；非 git 仓库（内容生产类目录）天然跳过
+            const wsDiff = await collectWorkspaceDiff(workspacePath(wsName));
+            if (wsDiff !== null && wsDiff.diff.trim()) {
+                for (const c of buildDiffSummaryCards(wsDiff.diff, { workspaceName: wsName, files: wsDiff.files })) {
+                    await deps.gateway.sendCardTo(msg.chatId, c);
                 }
             }
         }
@@ -590,6 +738,8 @@ deps, opts = {}) {
             });
         }
         finally {
+            // SOP 降级单文件补发（#7）：任务任何结局（完成/停止/出错）都在收尾补齐完整附件
+            await notifySender.flushDowngradedFile?.().catch(() => { });
             clearTimeout(hardTimeout);
             activeProgress.delete(key);
             activeQueries.delete(key);
@@ -610,10 +760,17 @@ deps, opts = {}) {
             const plan = planPending.get(action.value.requestId);
             if (plan) {
                 if (action.operatorId !== plan.ownerId) {
-                    console.log(tag, `[卡片回调] 非发起人 ${action.operatorId} 点击计划卡 ${action.value.requestId}，已忽略`);
+                    console.log(tag, `[卡片回调] 非发起人 ${action.operatorId} 点击计划区 ${action.value.requestId}，已忽略`);
                     return { toast: { type: 'info', content: '仅任务发起人可操作计划' } };
                 }
                 const decision = action.value.decision;
+                // 「查看完整方案」（#6）：callback 触发 send_file 直接发原 md 文件，不消耗挂起项
+                if (decision === 'plan-view-file') {
+                    // 文件在 planAsk 时已落盘；这里直接 send_file（feishuGateway 走 file_type:stream，md 等任意后缀可发）
+                    void deps.gateway.uploadAndSendFile(plan.chatId, plan.planFilePath)
+                        .catch((e) => console.error('[查看方案发送失败]', action.value.requestId, e));
+                    return { toast: { type: 'info', content: '正在发送方案文件…' } };
+                }
                 if (decision !== 'plan-approve' && decision !== 'plan-revise' && decision !== 'plan-reject') {
                     return { toast: { type: 'info', content: '该计划确认已被处理或已过期' } };
                 }
@@ -626,19 +783,20 @@ deps, opts = {}) {
                 plan.resolve(decision === 'plan-approve' ? { action: 'approve' }
                     : decision === 'plan-revise' ? { action: 'revise', feedback }
                         : { action: 'reject' });
-                const resultCard = buildPlanResultCard(plan.req, decision, '任务发起人', feedback);
-                void deps.gateway.updateCard(plan.cardId, resultCard)
-                    .catch((e) => console.error('[计划卡兜底更新失败]', action.value.requestId, e));
-                return {
-                    toast: { type: 'success', content: PLAN_DECISION_TEXT[decision] },
-                    card: { type: 'raw', data: resultCard },
-                };
+                // 清除主进度卡的内嵌计划区（按钮随 setPlan(undefined) 的 flush 消失）
+                const prog = activeProgress.get(plan.channelKey);
+                if (prog) {
+                    prog.setPlan(undefined);
+                    prog.setStatus(PLAN_DECISION_TEXT[decision]);
+                }
+                return { toast: { type: 'success', content: PLAN_DECISION_TEXT[decision] } };
             }
-            // 提问回调分流：qa-pick 更新选中态（卡片 PATCH 重渲染，不消耗挂起项）；qa-submit 全部作答后 resolve
+            // 提问回调分流（#3）：qa-pick 仅 PATCH 选中态（不消耗挂起项，等所有题答完才 submit）；
+            // qa-submit 全部作答后一次性 resolve 并 clearQuestion。主进度卡的 PATCH 由 ProgressCard 内部 flush 串行化
             const qa = qaPending.get(action.value.requestId);
             if (qa) {
                 if (action.operatorId !== qa.ownerId) {
-                    console.log(tag, `[卡片回调] 非发起人 ${action.operatorId} 点击提问卡 ${action.value.requestId}，已忽略`);
+                    console.log(tag, `[卡片回调] 非发起人 ${action.operatorId} 点击提问区 ${action.value.requestId}，已忽略`);
                     return { toast: { type: 'info', content: '仅任务发起人可作答' } };
                 }
                 const { decision } = action.value;
@@ -648,38 +806,117 @@ deps, opts = {}) {
                     if (!q || !label || !q.options.some((o) => o.label === label)) {
                         return { toast: { type: 'info', content: '该选项无效' } };
                     }
-                    const cur = qa.answers[action.value.qIndex];
-                    if (q.multiSelect) {
-                        const arr = Array.isArray(cur) ? cur : cur !== undefined ? [cur] : [];
-                        qa.answers[action.value.qIndex] = arr.includes(label)
-                            ? (arr.length > 1 ? arr.filter((x) => x !== label) : arr) // 至少保留一项：全取消等于未答
-                            : [...arr, label];
-                    }
-                    else {
-                        qa.answers[action.value.qIndex] = label;
-                    }
-                    void deps.gateway.updateCard(qa.cardId, buildQuestionCard(qa.req, qa.answers)).catch(() => { });
-                    return { toast: { type: 'success', content: `已选：${label}` } };
+                    // 切换选中态由 ProgressCard.updateQuestionAnswer 唯一维护（toggle / 至少保留一项）；本处只调 PATCH
+                    const prog = activeProgress.get(qa.channelKey);
+                    const before = prog?.getQuestionAnswer(action.value.qIndex);
+                    const willUnpick = !!q.multiSelect && Array.isArray(before) && before.includes(label) && before.length > 1;
+                    prog?.updateQuestionAnswer(action.value.qIndex, label, !!q.multiSelect);
+                    // 把 progress 的最新答案同步回 qa.answers 供 submit 校验，避免双 mutate（toggle 重复计数）
+                    if (prog)
+                        qa.answers[action.value.qIndex] = prog.getQuestionAnswer(action.value.qIndex)
+                            ?? (q.multiSelect ? [] : label);
+                    return { toast: { type: 'success', content: willUnpick ? `已取消：${label}` : `已选：${label}` } };
                 }
                 if (decision === 'qa-submit') {
-                    const missing = qa.req.questions
-                        .filter((_, i) => qa.answers[i] === undefined || (Array.isArray(qa.answers[i]) && qa.answers[i].length === 0));
+                    // 0.20.0：每题答案 = 选项点选 + 表单自定义输入（formValue.custom_N）合并——
+                    // 单选：custom 非空优先覆盖选中项；多选：custom 追加进选中数组。
+                    // 已答判定放宽为「选中项或自定义输入至少一项」
+                    const fv = action.value.formValue ?? {};
+                    const result = {};
+                    const missing = [];
+                    qa.req.questions.forEach((q, i) => {
+                        const raw = fv[`custom_${i}`];
+                        const custom = typeof raw === 'string' ? raw.trim() : '';
+                        const picked = qa.answers[i];
+                        if (q.multiSelect) {
+                            const arr = Array.isArray(picked) ? [...picked] : picked !== undefined ? [picked] : [];
+                            if (custom)
+                                arr.push(custom);
+                            if (arr.length === 0) {
+                                missing.push(i);
+                                return;
+                            }
+                            result[q.question] = arr;
+                        }
+                        else {
+                            const ans = custom || (picked !== undefined ? picked : '');
+                            if (!ans) {
+                                missing.push(i);
+                                return;
+                            }
+                            result[q.question] = ans;
+                        }
+                    });
                     if (missing.length > 0) {
-                        return { toast: { type: 'warning', content: `还有 ${missing.length} 个问题未作答（多选题至少选 1 项）` } };
+                        return { toast: { type: 'warning', content: `第 ${missing.map((i) => i + 1).join('、')} 题未作答（点选项或在输入框填写均可）` } };
                     }
                     qaPending.delete(action.value.requestId);
-                    const result = {};
-                    qa.req.questions.forEach((q, i) => { result[q.question] = qa.answers[i]; });
                     qa.resolve(result);
-                    const resultCard = buildQuestionResultCard(qa.req, qa.answers, '任务发起人');
-                    void deps.gateway.updateCard(qa.cardId, resultCard)
-                        .catch((e) => console.error('[提问卡兜底更新失败]', action.value.requestId, e));
+                    // 清除主进度卡的内嵌提问区（按钮随 setQuestion(undefined) 的 flush 消失）
+                    const prog = activeProgress.get(qa.channelKey);
+                    if (prog) {
+                        prog.setQuestion(undefined);
+                        prog.setStatus('✅ 答案已提交，继续执行…');
+                    }
+                    return { toast: { type: 'success', content: '✅ 答案已提交' } };
+                }
+                return { toast: { type: 'info', content: '该提问已被处理或已过期' } };
+            }
+            // 长回复收起卡（0.20.0）：任务已结束，无 Promise 挂起——outputPending 提供发起人校验、
+            // settled 防重与文件上下文。「查看完整内容」可反复点击；「确认方案 / 按意见修改」合成
+            // 一条用户消息入队，走与真实消息完全相同的排队/resume/进度卡链路发起新一轮任务
+            const out = outputPending.get(action.value.requestId);
+            if (out) {
+                if (action.operatorId !== out.ownerId) {
+                    console.log(tag, `[卡片回调] 非发起人 ${action.operatorId} 点击长回复卡 ${action.value.requestId}，已忽略`);
+                    return { toast: { type: 'info', content: '仅任务发起人可操作' } };
+                }
+                const decision = action.value.decision;
+                if (decision === 'view-output-file') {
+                    // 白名单校验：仅允许 outputs 目录内文件（value 虽由桥接器写入卡片，纵深防御不亏）
+                    const outputsDir = join(CONFIG_DIR, 'outputs');
+                    if (!out.req.filePath.startsWith(outputsDir + sep)) {
+                        return { toast: { type: 'error', content: '文件路径校验失败，已忽略' } };
+                    }
+                    void deps.gateway.uploadAndSendFile(out.chatId, out.req.filePath)
+                        .catch((e) => console.error('[完整回复发送失败]', action.value.requestId, e));
+                    return { toast: { type: 'info', content: '正在发送完整回复…' } };
+                }
+                if (out.settled) {
+                    return { toast: { type: 'info', content: '该回复的处理已提交，无需重复操作' } };
+                }
+                if (decision === 'output-confirm' || decision === 'output-revise') {
+                    const feedback = (action.value.feedback ?? '').trim();
+                    if (decision === 'output-revise' && !feedback) {
+                        return { toast: { type: 'warning', content: '请先在输入框填写修改意见（或点「确认方案」）' } };
+                    }
+                    out.settled = true;
+                    const prompt = decision === 'output-confirm'
+                        ? '用户已在飞书点击「确认方案」，确认了上一轮的完整回复（方案），请继续按该方案推进执行。'
+                        : `用户要求按以下意见调整上一轮完整回复中的方案：\n${feedback}`;
+                    // 合成用户消息入队：新一轮会 resume 上一会话（「上一轮方案」上下文天然在场）。
+                    // 发起人必在访问白名单（能发起任务才拿得到卡片），仍做 isAllowed 纵深校验；
+                    // chatType 不参与任务链路（仅 gateway 消息解析用），合成消息固定 p2p
+                    if (deps.access.isAllowed(action.operatorId)) {
+                        const key = channelKey(out.chatId, action.operatorId);
+                        enqueue(key, {
+                            chatId: out.chatId, chatType: 'p2p', userId: action.operatorId,
+                            text: prompt, messageId: `output-${action.value.requestId}`,
+                        }, prompt, out.req.workspaceName);
+                    }
+                    else {
+                        console.warn(tag, '[长回复卡] 发起人不在访问白名单，已忽略新一轮请求：', action.operatorId);
+                    }
+                    const settledText = decision === 'output-confirm'
+                        ? '✅ 已确认该方案，正在发起新一轮任务（详情见下方新进度卡）'
+                        : '✏️ 修改意见已收到，正在发起新一轮任务（详情见下方新进度卡）';
                     return {
-                        toast: { type: 'success', content: '✅ 答案已提交' },
-                        card: { type: 'raw', data: resultCard },
+                        toast: { type: 'success', content: settledText },
+                        // 回调响应内联换卡：决策按钮区收为一行文案（查看按钮保留，全文仍可回看）
+                        card: { type: 'raw', data: buildLongOutputSettledCard(out.req, settledText) },
                     };
                 }
-                return { toast: { type: 'info', content: '该提问已被处理或已过期' } };
+                return { toast: { type: 'info', content: '该操作无效或已过期' } };
             }
             const pending = confirmPending.get(action.value.requestId);
             if (!pending) {
@@ -709,7 +946,21 @@ deps, opts = {}) {
             return { toast: { type: 'error', content: retryable ? '处理失败，请重试' : '处理出现异常，决策可能已生效，请勿盲目重试' } };
         }
     }
-    return { onMessage: handleIncoming, onCardAction: handleCardAction };
+    return {
+        onMessage: handleIncoming,
+        onCardAction: handleCardAction,
+        /**
+         * 测试/诊断入口：返回通道当前挂起的内嵌 plan / question requestId。
+         * 仅用于测试断言与生产期诊断，不影响业务流。channelKey 取 chatId + userId。
+         * 内嵌挂起项被 settle/超时清空时对应字段变 undefined
+         */
+        _pendingAsk(channelKey) {
+            const prog = activeProgress.get(channelKey);
+            if (!prog)
+                return {};
+            return prog.pendingAsk();
+        },
+    };
 }
 /**
  * 配置热重载器：lcb ws add/remove 写盘后，运行实例下一条消息即见新工作区
@@ -810,6 +1061,11 @@ export async function startBridge(configPath = CONFIG_PATH) {
                 uploadAndSendFile: (chatId, p) => gateway.uploadAndSendFile(chatId, p),
                 sendImageTo: (chatId, p, caption) => gateway.sendImage(chatId, p, caption),
                 deleteCard: (id) => gateway.deleteCard(id),
+                // 卡片实体模式（cardkit）：进度卡局部更新保 plan 表单输入；FeishuGateway 恒定实现，
+                // 权限/接口异常时 ProgressCard.start 捕获降级为普通卡片 + 整卡 PATCH
+                sendCardEntityTo: (chatId, card) => gateway.sendCardEntity(chatId, card),
+                partialUpdateCardElements: (cardId, seq, actions) => gateway.partialUpdateCardElements(cardId, seq, actions),
+                replaceCardEntity: (cardId, seq, card) => gateway.replaceCardEntity(cardId, seq, card),
             },
             access,
             store: SessionStore.load(join(CONFIG_DIR, `sessions.${app.appId}.json`)),