@steerable/agent-shell 0.6.20 → 0.6.21

package/dist/host/runtime.js

@@ -68,7 +68,6 @@ export function createHostRuntime(options) {
     const maybeExecInTerminal = createVisibleTerminalExec({
         localExecutor,
         terminalManager,
-        broadcast,
     });
     const toolRouter = new ToolRouter(localExecutor, localScriptRegistry, async (request) => {
         const viaTerminal = await maybeExecInTerminal(request);

package/dist/host/visible-terminal-exec.d.ts

@@ -1,10 +1,8 @@
 import { type LocalExecRequest, type LocalExecResult, type LocalExecutor } from '../local-executor.js';
 import type { TerminalManager } from '../terminal-manager.js';
-export type HostBroadcast = (channel: string, payload: unknown) => void;
 export interface VisibleTerminalExecDeps {
     localExecutor: LocalExecutor;
     terminalManager: TerminalManager;
-    broadcast: HostBroadcast;
 }
 /**
  * Map a raw PTY shell binary name (e.g. `powershell.exe`, `cmd.exe`, `zsh`) to

package/dist/host/visible-terminal-exec.js

@@ -1,8 +1,7 @@
 /**
- * 可见 PTY 执行路由（Codex 式"看 agent 打字"）：shell 命令优先打进共享的
- * 可见终端，多行/heredoc 等 sentinel 抓不住的形态回退 headless。
- * Electron main 与 BS server 共用；`terminal:reveal` 等事件经注入的
- * broadcast 出口（Electron 窗口广播 / BS SSE 总线）。
+ * 可见 PTY 执行路由：shell 命令优先打进共享的可见终端，多行/heredoc 等
+ * sentinel 抓不住的形态回退 headless。Electron main 与 BS server 共用。
+ * 命令进入 PTY 时不通知 renderer 展开面板——终端只由用户手动打开。
  */
 import log from 'electron-log';
 import { GUI_LAUNCH_WAIT_MS, getConfiguredExecTimeoutMs, isGuiLaunchCommand, rewriteExeCommandIfNeeded, } from '../local-executor.js';
@@ -32,7 +31,7 @@ export function mapSessionShell(shell) {
  * process.
  */
 export function createVisibleTerminalExec(deps) {
-    const { localExecutor, terminalManager, broadcast } = deps;
+    const { localExecutor, terminalManager } = deps;
     return async function maybeExecInTerminal(req) {
         if (req.command) {
             req.command = rewriteExeCommandIfNeeded(req.command);
@@ -73,9 +72,6 @@ export function createVisibleTerminalExec(deps) {
             timeoutMs = getConfiguredExecTimeoutMs() ?? undefined;
         }
         const session = terminalManager.ensurePrimary({ cwd: req.cwd });
-        // Codex 式面板自动展开：命令进入可见 PTY 时通知 renderer 打开内嵌终端
-        // 面板。幂等——面板已打开时 renderer 端是 no-op。
-        broadcast('terminal:reveal', { sessionId: session.id });
         const resolvedShell = mapSessionShell(session.shell);
         // 项目模式（ToolRouter 会把项目根塞进 req.cwd）：可见 PTY 是共享交互
         // 会话，已有 session 不会随 ensurePrimary 改目录——显式 cd 过去。

package/dist/local-backend/ai-suggestions.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 回合结束后生成 3 条「下一轮用户输入」建议（WorkBuddy 式快捷追问）。
+ *
+ * 主路径走一次短 LLM 调用，根据本轮用户请求 + 助手回复写成用户口吻的短句。
+ * 失败时用启发式兜底（PPT / 计划 / 代码 / 通用），永不抛错。
+ *
+ * 调用方应该 fire-and-forget：先把兜底三条推上 UI，LLM 成功后再替换。
+ * 不要挂在 SSE 主流程里阻塞 `[DONE]`。
+ */
+export declare const SUGGESTED_REPLY_COUNT = 3;
+/** 单条建议清洗：去编号/引号、压空白、截断。不合格返回空串。 */
+export declare function cleanSuggestedReply(raw: string): string;
+/**
+ * 从模型原文抽出最多 3 条建议。接受 JSON 数组、markdown 代码块、或编号/项目列表。
+ */
+export declare function parseSuggestedReplies(raw: string): string[];
+/**
+ * 不调模型的启发式三条。PPT / 计划 / 代码有专用句子，其它走通用。
+ * 始终返回正好 3 条（输入全空时仍给通用三条）。
+ */
+export declare function fallbackSuggestedReplies(userText: string, assistantText: string): string[];
+export interface GenerateSuggestedRepliesResult {
+    suggestions: string[];
+    /** true = LLM 失败或输出不合格，suggestions 来自启发式兜底。 */
+    usedFallback: boolean;
+}
+/**
+ * 生成本轮 3 条追问建议。永不抛错，始终返回 3 条。
+ */
+export declare function generateSuggestedReplies(userText: string, assistantText: string, opts?: {
+    perAttemptTimeoutMs?: number;
+}): Promise<GenerateSuggestedRepliesResult>;

package/dist/local-backend/ai-suggestions.js

@@ -0,0 +1,160 @@
+/**
+ * 回合结束后生成 3 条「下一轮用户输入」建议（WorkBuddy 式快捷追问）。
+ *
+ * 主路径走一次短 LLM 调用，根据本轮用户请求 + 助手回复写成用户口吻的短句。
+ * 失败时用启发式兜底（PPT / 计划 / 代码 / 通用），永不抛错。
+ *
+ * 调用方应该 fire-and-forget：先把兜底三条推上 UI，LLM 成功后再替换。
+ * 不要挂在 SSE 主流程里阻塞 `[DONE]`。
+ */
+import { llmService } from '../llm/index.js';
+export const SUGGESTED_REPLY_COUNT = 3;
+const MAX_SUGGESTION_CHARS = 36;
+const USER_TEXT_LIMIT = 500;
+const ASSISTANT_TEXT_LIMIT = 1600;
+const SYSTEM_PROMPT = `你是对话追问建议助手。根据用户上一轮请求和助手刚刚完成的回复，生成 3 条用户可以点一下就发出去的下一轮输入。
+
+要求：
+1. 正好 3 条，彼此不重复
+2. 每条 8-28 个字，用用户口吻，像用户会打的话
+3. 紧扣刚刚完成的工作：改内容、改样式、继续深入、换方向；不要空泛的「再详细说说」
+4. 如果助手已经邀请后续操作（例如「如需修改内容或调整样式」），把那些邀请写成具体可执行的短句
+5. 不要编号、不要引号、不要解释
+6. 只输出 JSON 字符串数组，例如 ["调整封面配色","把个人简介写得更具体","再加一页项目案例"]`;
+function withTimeout(promise, timeoutMs, label) {
+    if (timeoutMs <= 0)
+        return promise;
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+function clip(text, limit) {
+    const chars = Array.from((text ?? '').trim());
+    if (chars.length <= limit)
+        return chars.join('');
+    return `${chars.slice(0, limit).join('')}…`;
+}
+/** 单条建议清洗：去编号/引号、压空白、截断。不合格返回空串。 */
+export function cleanSuggestedReply(raw) {
+    let text = (raw ?? '').trim();
+    text = text.replace(/^[\s"'“”‘’「」『』《》【】]+|[\s"'“”‘’「」『』《》【】。.！!?？，,；;:：]+$/g, '');
+    text = text.replace(/^(?:\d+[\.\)、]|[-*•])\s*/, '');
+    text = text.replace(/\s+/g, ' ').trim();
+    if (text.length < 2)
+        return '';
+    const chars = Array.from(text);
+    if (chars.length > MAX_SUGGESTION_CHARS) {
+        text = chars.slice(0, MAX_SUGGESTION_CHARS).join('').trim();
+    }
+    return text;
+}
+function uniqueThree(candidates, extras = []) {
+    const out = [];
+    const seen = new Set();
+    for (const raw of [...candidates, ...extras]) {
+        const cleaned = cleanSuggestedReply(raw);
+        if (!cleaned || seen.has(cleaned))
+            continue;
+        seen.add(cleaned);
+        out.push(cleaned);
+        if (out.length === SUGGESTED_REPLY_COUNT)
+            break;
+    }
+    return out;
+}
+/**
+ * 从模型原文抽出最多 3 条建议。接受 JSON 数组、markdown 代码块、或编号/项目列表。
+ */
+export function parseSuggestedReplies(raw) {
+    const trimmed = (raw ?? '').trim();
+    if (!trimmed)
+        return [];
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    const candidate = (fenced?.[1] ?? trimmed).trim();
+    const start = candidate.indexOf('[');
+    const end = candidate.lastIndexOf(']');
+    if (start >= 0 && end > start) {
+        try {
+            const parsed = JSON.parse(candidate.slice(start, end + 1));
+            if (Array.isArray(parsed)) {
+                return uniqueThree(parsed.filter((item) => typeof item === 'string'));
+            }
+        }
+        catch {
+            // 落到分行解析。
+        }
+    }
+    const lines = candidate
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !/^```/.test(line));
+    const listLines = lines.filter((line) => /^(?:\d+[\.\)、]|[-*•])\s+/.test(line));
+    return uniqueThree(listLines.length > 0 ? listLines : lines);
+}
+const PPT_FALLBACK = ['调整封面标题和配色', '把某一页内容写得更具体', '再加一页项目案例'];
+const PLAN_FALLBACK = ['按这个计划开始执行', '先改第 2 步再执行', '把计划写得更细一点'];
+const CODE_FALLBACK = ['解释这段实现的思路', '帮我补上测试', '再优化一下可读性'];
+const GENERIC_FALLBACK = ['继续完善这份结果', '换一种呈现方式', '告诉我下一步怎么做'];
+const PPT_OFFER_FALLBACK = ['调整幻灯片的内容和文案', '调整配色和版式', '再加一页补充材料'];
+/**
+ * 不调模型的启发式三条。PPT / 计划 / 代码有专用句子，其它走通用。
+ * 始终返回正好 3 条（输入全空时仍给通用三条）。
+ */
+export function fallbackSuggestedReplies(userText, assistantText) {
+    const blob = `${userText}\n${assistantText}`;
+    if (/\.pptx\b|幻灯片|演示文稿|\bppt\b/i.test(blob)) { // shell-neutral:allow — Office 扩展名 'ppt'/'.pptx'，不是产品品牌
+        if (/修改内容|调整样式/.test(assistantText)) {
+            return uniqueThree(PPT_OFFER_FALLBACK, PPT_FALLBACK);
+        }
+        return uniqueThree(PPT_FALLBACK, GENERIC_FALLBACK);
+    }
+    if (/标准工作流程|待办清单|\bTODO\b|先制定计划/.test(blob) || /^\s*计划已/.test(assistantText)) {
+        return uniqueThree(PLAN_FALLBACK, GENERIC_FALLBACK);
+    }
+    if (/```|单元测试|函数实现|补测试/.test(blob)) {
+        return uniqueThree(CODE_FALLBACK, GENERIC_FALLBACK);
+    }
+    return uniqueThree(GENERIC_FALLBACK);
+}
+/**
+ * 生成本轮 3 条追问建议。永不抛错，始终返回 3 条。
+ */
+export async function generateSuggestedReplies(userText, assistantText, opts = {}) {
+    const fallback = fallbackSuggestedReplies(userText, assistantText);
+    const user = clip(userText, USER_TEXT_LIMIT);
+    const assistant = clip(assistantText, ASSISTANT_TEXT_LIMIT);
+    if (!user && !assistant) {
+        return { suggestions: fallback, usedFallback: true };
+    }
+    const perAttemptTimeoutMs = opts.perAttemptTimeoutMs ?? 12_000;
+    try {
+        const result = await withTimeout(llmService.generate({
+            messages: [
+                { role: 'system', content: SYSTEM_PROMPT },
+                {
+                    role: 'user',
+                    content: `用户请求：\n${user || '（空）'}\n\n助手回复：\n${assistant || '（空）'}`,
+                },
+            ],
+            temperature: 0.6,
+        }), perAttemptTimeoutMs, 'ai-suggestions');
+        const parsed = parseSuggestedReplies(result.content ?? '');
+        const suggestions = uniqueThree(parsed, fallback);
+        if (suggestions.length === SUGGESTED_REPLY_COUNT && parsed.length > 0) {
+            return { suggestions, usedFallback: false };
+        }
+    }
+    catch (err) {
+        console.warn('[ai-suggestions] LLM 追问建议失败，用启发式兜底', err);
+    }
+    return { suggestions: fallback, usedFallback: true };
+}

package/dist/local-backend/coreloop-stream.js

@@ -99,7 +99,7 @@ export async function streamCoreLoopTurn(options) {
         streamRawChunks: options.streamRawChunks,
         // W8: advertise the sidecar-hosted ask_user tool; the desktop answers
         // `ask_user.request` reverse calls with the renderer question card
-        // (AskUserModalHost). Under toolsViaHost the sidecar intercepts
+        // (AskUserPromptProvider). Under toolsViaHost the sidecar intercepts
         // ask_user locally, so it never reaches the host's tool.invoke.
         // 4.6a: background task streams opt out (options.askUser === false).
         askUser: options.askUser ?? true,

package/dist/local-backend/mentioned-paths.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 对话正文里提到的文件路径的存在性解析（「点击打开正文里的路径」用）。
+ *
+ * 渲染层从助手回答的行内代码里挑出「看着像路径」的字面量，批量送到这里
+ * 落地成绝对路径并 stat 验证。只有真实存在的条目会回给渲染层——路径是
+ * 模型写出来的自然语言片段，猜错在所难免，靠 stat 证伪而不是靠解析可靠。
+ *
+ * 相对路径的基准目录由调用方给（绑定项目的对话用项目根，否则用 home），
+ * 与 exec 工具缺省 cwd 的回落规则一致，这样模型写 `./out.bin` 时指向的
+ * 就是它当时真正落盘的位置。
+ */
+export interface ResolvedMentionedPath {
+    /** 渲染层送来的原始字面量（用于回填到对应的行内代码节点）。 */
+    candidate: string;
+    /** 落地后的绝对路径（点击打开直接用）。 */
+    path: string;
+    /** 目录会用文件管理器打开，渲染层据此换图标。 */
+    isDirectory: boolean;
+}
+/**
+ * 批量解析候选路径，只返回真实存在的条目。`baseDir` 是相对路径的基准
+ * 目录；`homeDir` 仅测试注入用，默认 os.homedir()。
+ */
+export declare function resolveMentionedPaths(options: {
+    candidates: readonly string[];
+    baseDir: string;
+    homeDir?: string;
+}): Promise<ResolvedMentionedPath[]>;

package/dist/local-backend/mentioned-paths.js

@@ -0,0 +1,67 @@
+/**
+ * 对话正文里提到的文件路径的存在性解析（「点击打开正文里的路径」用）。
+ *
+ * 渲染层从助手回答的行内代码里挑出「看着像路径」的字面量，批量送到这里
+ * 落地成绝对路径并 stat 验证。只有真实存在的条目会回给渲染层——路径是
+ * 模型写出来的自然语言片段，猜错在所难免，靠 stat 证伪而不是靠解析可靠。
+ *
+ * 相对路径的基准目录由调用方给（绑定项目的对话用项目根，否则用 home），
+ * 与 exec 工具缺省 cwd 的回落规则一致，这样模型写 `./out.bin` 时指向的
+ * 就是它当时真正落盘的位置。
+ */
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+/** 单次请求的候选上限与单条长度上限：渲染层是不可信输入，挡住刷 stat。 */
+const MAX_CANDIDATES = 64;
+const MAX_CANDIDATE_LENGTH = 512;
+/**
+ * 批量解析候选路径，只返回真实存在的条目。`baseDir` 是相对路径的基准
+ * 目录；`homeDir` 仅测试注入用，默认 os.homedir()。
+ */
+export async function resolveMentionedPaths(options) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const out = [];
+    const seen = new Set();
+    for (const raw of options.candidates.slice(0, MAX_CANDIDATES)) {
+        if (typeof raw !== 'string')
+            continue;
+        const candidate = raw.trim();
+        if (!candidate || candidate.length > MAX_CANDIDATE_LENGTH)
+            continue;
+        // 换行/NUL 不可能是单个路径字面量，且会污染后续 stat。
+        if (/[\n\r\0]/.test(candidate))
+            continue;
+        if (seen.has(candidate))
+            continue;
+        seen.add(candidate);
+        const full = toAbsolute(candidate, options.baseDir, homeDir);
+        if (!full)
+            continue;
+        let stat;
+        try {
+            stat = await fs.stat(full);
+        }
+        catch {
+            // 不存在/无权限：模型写错或文件已被删，静默丢弃。
+            continue;
+        }
+        if (!stat.isFile() && !stat.isDirectory())
+            continue;
+        out.push({ candidate, path: full, isDirectory: stat.isDirectory() });
+    }
+    return out;
+}
+/** `~` 展开 → 绝对路径原样 → 其余按 baseDir 解析。 */
+function toAbsolute(candidate, baseDir, homeDir) {
+    if (candidate === '~')
+        return homeDir;
+    if (candidate.startsWith('~/') || candidate.startsWith('~\\')) {
+        return path.resolve(path.join(homeDir, candidate.slice(2)));
+    }
+    if (path.isAbsolute(candidate))
+        return path.resolve(candidate);
+    if (!baseDir)
+        return null;
+    return path.resolve(baseDir, candidate);
+}

package/dist/local-backend/router.d.ts

@@ -62,6 +62,7 @@ export declare class LocalBackendRouter {
      *   `accumulatedContent += parsedData.content` 一行追加渲染。
      * - 同步真实 messageId：`data: {"type":"message_id","messageId":"..."}`
      * - 工具执行结果（无需用户确认）：`data: {"type":"executed_actions","actions":[...]}`
+     * - 回合产物文件列表（仅非空时发，在 message_id 之前）：`data: {"type":"turn_files","files":[...]}`
      * - 错误：保留 `event:error` + `data: {"message":"..."}`（前端会忽略，但日志/未来 UI 用）
      * - 结束：标准 SSE `[DONE]` 串。
      */
@@ -158,6 +159,13 @@ export declare class LocalBackendRouter {
      * the reverse-channel handler registered in main.ts.
      */
     private handleCoreLoopTurn;
+    /**
+     * 回合结束后生成 3 条下一轮用户输入建议。先同步推启发式兜底（芯片立刻出现），
+     * 再 fire-and-forget 跑 LLM，成功则替换。走 broadcast 而不是 SSE：`[DONE]`
+     * 之后渲染端已经不再监听这条流。
+     */
+    private runSuggestedRepliesInBackground;
+    private publishSuggestedReplies;
     /**
      * 标准"匿名事件" SSE：不带 event 行，前端 SSEParser 会落到默认 onMessage 分支，
      * 用 parseSSEData 把 data 反序列化为 JSON 后用 type/content 字段路由。

package/dist/local-backend/router.js

@@ -2,7 +2,7 @@ import { randomUUID } from 'crypto';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import os from 'node:os';
-import { getAppRootDir } from '../runtime.js';
+import { getAppRootDir, shellOpenPath } from '../runtime.js';
 import { llmService, getSidecarSupervisor, whenSidecarSupervisor } from '../llm/index.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 import { buildWorldState, getActiveCoreLoopStreamId, streamCoreLoopTurn, } from './coreloop-stream.js';
@@ -26,6 +26,7 @@ import { parseUserMessageTriggers } from './message-triggers.js';
 import { findSkill, loadSkills, classifySkillOrigin, listSkillRoots } from './skill-loader.js';
 import { installSkillFromDirectory } from './skill-install.js';
 import { generateChatTitle } from './ai-title.js';
+import { fallbackSuggestedReplies, generateSuggestedReplies, } from './ai-suggestions.js';
 import { detectDeferredExecution } from './deferred-detector.js';
 import { formatHistoryForSummary, truncateMiddle, } from './context-compactor.js';
 import { planRegenerateTruncate, resolveRegenerateContext, resolveRegenerateForkOrdinal, } from './regenerate-helper.js';
@@ -37,6 +38,8 @@ import { loadProjectRuleFiles } from '../project-rules.js';
 import { registerLiveStream, getLiveStream, removeLiveStream } from './live-stream.js';
 import { beginPackTurnObservers, collectPackExecWritableRoots, collectPackForcedSkillVars, collectPackWorldState, } from './pack-turn-hooks.js';
 import { matchPackBackendRoute } from './pack-backend-routes.js';
+import { collectTurnFiles } from './turn-files.js';
+import { resolveMentionedPaths } from './mentioned-paths.js';
 /**
  * 把 CoreLoop/LLM 的底层错误翻译成适合直接显示在助手消息里的中文提示。
  * 原始错误仍保存在 messageMetadata.completionReason 里，便于排查。
@@ -1642,6 +1645,37 @@ export class LocalBackendRouter {
                 },
             };
         }
+        // 回合产物列表的「点击打开」：用系统默认应用打开本地路径（与 agent 的
+        // local_open_path 工具同一宿主能力，这里给渲染层一个 HTTP 入口，CS/BS
+        // 两种模式都经 localBackend.request 到达）。
+        if (method === 'POST' && pathname === '/api/v2/local/open-path') {
+            const payload = this.toRecord(request.body);
+            const target = typeof payload.path === 'string' ? payload.path.trim() : '';
+            if (!target || !path.isAbsolute(target)) {
+                return { status: 400, data: { detail: 'absolute path is required' } };
+            }
+            const openError = await shellOpenPath(target);
+            if (openError) {
+                return { status: 200, data: { success: false, error: openError } };
+            }
+            return { status: 200, data: { success: true } };
+        }
+        // 正文里提到的路径能否点击打开：渲染层把行内代码里「像路径」的字面量
+        // 批量送来，这里落地成绝对路径并 stat 验证，只有真实存在的才回。相对
+        // 路径按对话绑定的项目根解析，无项目时按 home（同 exec 缺省 cwd 的回落）。
+        if (method === 'POST' && pathname === '/api/v2/local/resolve-paths') {
+            const payload = this.toRecord(request.body);
+            const candidates = Array.isArray(payload.candidates)
+                ? payload.candidates.filter((item) => typeof item === 'string')
+                : [];
+            if (candidates.length === 0) {
+                return { status: 200, data: { resolved: [] } };
+            }
+            const chatId = typeof payload.chatId === 'string' ? payload.chatId : '';
+            const baseDir = (chatId ? this.resolveChatProject(chatId)?.folderPath : null) ?? os.homedir();
+            const resolved = await resolveMentionedPaths({ candidates, baseDir });
+            return { status: 200, data: { resolved } };
+        }
         // ─── 场景包路由（1.2：/api/v2/<包前缀>/* 由包经 pack-backend-routes
         // 注册表贡献；在宿主自带路由之后、fallback 之前匹配，包不能遮蔽宿主
         // 路由）。 ───
@@ -1696,6 +1730,7 @@ export class LocalBackendRouter {
      *   `accumulatedContent += parsedData.content` 一行追加渲染。
      * - 同步真实 messageId：`data: {"type":"message_id","messageId":"..."}`
      * - 工具执行结果（无需用户确认）：`data: {"type":"executed_actions","actions":[...]}`
+     * - 回合产物文件列表（仅非空时发，在 message_id 之前）：`data: {"type":"turn_files","files":[...]}`
      * - 错误：保留 `event:error` + `data: {"message":"..."}`（前端会忽略，但日志/未来 UI 用）
      * - 结束：标准 SSE `[DONE]` 串。
      */
@@ -2760,6 +2795,14 @@ export class LocalBackendRouter {
         const live = registerLiveStream(chatId, { executedActions, timeline, children });
         // 场景包的回合观察器（如识别包技能调用并广播产物更新）。
         const packObservers = beginPackTurnObservers({ chatId, broadcast: this.broadcast ?? undefined });
+        // 回合产物文件列表（回合收尾时收集）：扫描根与 exec 沙箱可写根同源
+        // （项目根 + 包工作区），与沙箱是否启用无关——「完整权限」下根列表只是
+        // 不再被强制，产物仍大概率落在这里；根之外的显式写由工具参数并集补。
+        const turnStartedAtMs = Date.now();
+        const turnFileRoots = [
+            ...collectPackExecWritableRoots(chatId),
+            ...(chatProject ? [chatProject.folderPath] : []),
+        ];
         try {
             const coreLoopOptions = {
                 supervisor,
@@ -3012,6 +3055,20 @@ export class LocalBackendRouter {
             }
         }
         const durationMs = turnDurationMs(localStore.getTurnActive(chatId)?.startedAt, Date.now());
+        // 回合产物文件列表（成功/失败/取消都收集——半截回合写出的文件同样是
+        // 产物）。收集失败只记日志，永远不该拖垮回合收尾。
+        let turnFiles = [];
+        try {
+            turnFiles = await collectTurnFiles({
+                roots: turnFileRoots,
+                sinceMs: turnStartedAtMs,
+                actions: executedActions,
+                projectRoot: chatProject?.folderPath ?? null,
+            });
+        }
+        catch (turnFilesErr) {
+            console.warn('[local-backend] collect turn files failed', turnFilesErr);
+        }
         const assistant = localStore.addMessage(chatId, 'assistant', assistantText, JSON.stringify({
             completionStatus,
             completionReason,
@@ -3022,6 +3079,7 @@ export class LocalBackendRouter {
             traceId: outcomeTraceId,
             ...(durationMs != null ? { durationMs } : {}),
             ...(autoContinuations > 0 ? { autoContinuations } : {}),
+            ...(turnFiles.length > 0 ? { turnFiles } : {}),
         }));
         try {
             recordInsightTurn({
@@ -3094,11 +3152,65 @@ export class LocalBackendRouter {
                 });
             }
         }
+        // 产物文件列表赶在 message_id 之前发：前端按 message_id 把本轮队列
+        // 归档到落库消息上，顺序保证产物列表随同一批次归档。
+        if (turnFiles.length > 0) {
+            emit(this.sseData({ type: 'turn_files', files: turnFiles }));
+        }
         emit(this.sseData({ type: 'message_id', messageId: assistant.id }));
         emit('data: [DONE]\n\n');
         this.runTitleGenInBackground(chatId, shouldGenerateTitle, firstUserMessageForTitle);
+        this.runSuggestedRepliesInBackground({
+            chatId,
+            messageId: assistant.id,
+            userText: firstUserMessageForTitle,
+            assistantText,
+            completionStatus,
+        });
         return { status: 200 };
     }
+    /**
+     * 回合结束后生成 3 条下一轮用户输入建议。先同步推启发式兜底（芯片立刻出现），
+     * 再 fire-and-forget 跑 LLM，成功则替换。走 broadcast 而不是 SSE：`[DONE]`
+     * 之后渲染端已经不再监听这条流。
+     */
+    runSuggestedRepliesInBackground(args) {
+        const { chatId, messageId, userText, assistantText, completionStatus } = args;
+        if (completionStatus === 'cancelled' || completionStatus === 'failed')
+            return;
+        if (!assistantText.trim())
+            return;
+        const fallback = fallbackSuggestedReplies(userText, assistantText);
+        this.publishSuggestedReplies(chatId, messageId, fallback);
+        void (async () => {
+            try {
+                const result = await generateSuggestedReplies(userText, assistantText, {
+                    perAttemptTimeoutMs: 60_000,
+                });
+                if (result.usedFallback)
+                    return;
+                const same = result.suggestions.length === fallback.length &&
+                    result.suggestions.every((item, i) => item === fallback[i]);
+                if (same)
+                    return;
+                this.publishSuggestedReplies(chatId, messageId, result.suggestions);
+            }
+            catch (err) {
+                console.warn('[local-backend] suggested-replies failed', { chatId, err });
+            }
+        })();
+    }
+    publishSuggestedReplies(chatId, messageId, suggestions) {
+        if (suggestions.length === 0)
+            return;
+        try {
+            localStore.patchMessageMetadata(chatId, messageId, { suggestedReplies: suggestions });
+        }
+        catch (err) {
+            console.warn('[local-backend] suggested-replies persist failed', { chatId, messageId, err });
+        }
+        this.broadcast?.('suggested-replies', { chatId, messageId, suggestions });
+    }
     /**
      * 标准"匿名事件" SSE：不带 event 行，前端 SSEParser 会落到默认 onMessage 分支，
      * 用 parseSSEData 把 data 反序列化为 JSON 后用 type/content 字段路由。

package/dist/local-backend/turn-files.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 回合产物文件收集（「本轮写了哪些文件」列表）。
+ *
+ * 四个来源取并集：
+ *
+ *  1. 工作区扫描（递归）：回合的可写根（项目根 + 场景包工作区，与 exec
+ *     沙箱同源）里 mtime/birthtime ≥ 回合开始时间的文件。覆盖脚本/命令
+ *     间接写出的产物（如运行脚本生成的文档、报表）——这类路径无法从
+ *     工具参数解析。
+ *  2. 显式写工具参数：local_write_file / local_edit_file 的 path。覆盖
+ *    「完整权限」模式下写到可写根之外的路径（如 ~/Downloads）。
+ *  3. exec cwd 浅扫描（仅顶层一层、跳过点文件）：local_exec_shell /
+ *     local_run_snippet 的实际工作目录（显式 cwd；缺省按 executor 规则
+ *     回落到项目根或 home）。覆盖「脚本在 cwd 落盘」——无项目对话的
+ *     exec 默认 cwd 是 home，产物（如 ~/季度报告.pdf）不在任何递归根里。
+ *  4. 命令/代码文本里的绝对路径字面量：exec 命令、snippet 代码中出现的
+ *     绝对路径（含 ~/ 前缀与引号包裹形式），stat + 时间水位线验证后并入。
+ *     覆盖脚本写到与 cwd 无关的任意位置（如 doc.save('/tmp/x/a.pdf')）。
+ *
+ * 来源 3/4 都是「猜候选、靠 stat + mtime/birthtime 水位线证伪」：命令里
+ * 提到的既有文件（ls /etc/hosts）时间戳旧、不会被误收；不存在的路径
+ * stat 即失败。因此解析不需要可靠——与沙箱围栏「命令内嵌绝对路径无法
+ * 可靠解析所以不拦」不同，展示面可以承受启发式，漏报才伤体验。
+ *
+ * 单趟末次扫描、无基线快照：kind 标签靠 birthtime（macOS/Windows/新版
+ * Linux 文件系统可用）；birthtime 不可用时降级为 'modified'，列表本身
+ * 的准确性不依赖 birthtime。
+ *
+ * 扫描是有界 best-effort：忽略依赖/构建缓存目录，深度与遍历条目数有硬顶，
+ * 超限直接截断返回已收集部分——产物列表是展示面，永远不该拖垮回合收尾。
+ */
+export interface TurnFile {
+    /** 绝对路径（点击打开直接用）。 */
+    path: string;
+    /** created = 本轮新建；modified = 已有文件被改动。 */
+    kind: 'created' | 'modified';
+    /** 字节数（展示用）。 */
+    size: number;
+}
+/** 扫描入参里只需要工具行动的这几个字段（与 router 的 executedActions 行结构对齐）。 */
+export interface TurnFileAction {
+    tool?: unknown;
+    arguments?: unknown;
+    success?: unknown;
+}
+/**
+ * 收集本轮产物文件。`sinceMs` 是回合开始的 epoch ms；`projectRoot` 用于把
+ * 写工具的相对路径参数解析成绝对路径（与 local-executor 的项目根解析一致）。
+ * `homeDir` 仅测试注入用，默认 os.homedir()——exec 缺省 cwd 的回落值。
+ */
+export declare function collectTurnFiles(options: {
+    roots: string[];
+    sinceMs: number;
+    actions?: readonly TurnFileAction[];
+    projectRoot?: string | null;
+    homeDir?: string;
+}): Promise<TurnFile[]>;

package/dist/local-backend/turn-files.js

@@ -0,0 +1,285 @@
+/**
+ * 回合产物文件收集（「本轮写了哪些文件」列表）。
+ *
+ * 四个来源取并集：
+ *
+ *  1. 工作区扫描（递归）：回合的可写根（项目根 + 场景包工作区，与 exec
+ *     沙箱同源）里 mtime/birthtime ≥ 回合开始时间的文件。覆盖脚本/命令
+ *     间接写出的产物（如运行脚本生成的文档、报表）——这类路径无法从
+ *     工具参数解析。
+ *  2. 显式写工具参数：local_write_file / local_edit_file 的 path。覆盖
+ *    「完整权限」模式下写到可写根之外的路径（如 ~/Downloads）。
+ *  3. exec cwd 浅扫描（仅顶层一层、跳过点文件）：local_exec_shell /
+ *     local_run_snippet 的实际工作目录（显式 cwd；缺省按 executor 规则
+ *     回落到项目根或 home）。覆盖「脚本在 cwd 落盘」——无项目对话的
+ *     exec 默认 cwd 是 home，产物（如 ~/季度报告.pdf）不在任何递归根里。
+ *  4. 命令/代码文本里的绝对路径字面量：exec 命令、snippet 代码中出现的
+ *     绝对路径（含 ~/ 前缀与引号包裹形式），stat + 时间水位线验证后并入。
+ *     覆盖脚本写到与 cwd 无关的任意位置（如 doc.save('/tmp/x/a.pdf')）。
+ *
+ * 来源 3/4 都是「猜候选、靠 stat + mtime/birthtime 水位线证伪」：命令里
+ * 提到的既有文件（ls /etc/hosts）时间戳旧、不会被误收；不存在的路径
+ * stat 即失败。因此解析不需要可靠——与沙箱围栏「命令内嵌绝对路径无法
+ * 可靠解析所以不拦」不同，展示面可以承受启发式，漏报才伤体验。
+ *
+ * 单趟末次扫描、无基线快照：kind 标签靠 birthtime（macOS/Windows/新版
+ * Linux 文件系统可用）；birthtime 不可用时降级为 'modified'，列表本身
+ * 的准确性不依赖 birthtime。
+ *
+ * 扫描是有界 best-effort：忽略依赖/构建缓存目录，深度与遍历条目数有硬顶，
+ * 超限直接截断返回已收集部分——产物列表是展示面，永远不该拖垮回合收尾。
+ */
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+/** 这些目录要么体量巨大（node_modules/target），要么是框架内部状态（.steerable），扫了只有噪音。 */
+const IGNORED_DIR_NAMES = new Set([
+    'node_modules',
+    '.git',
+    '.hg',
+    '.svn',
+    '__pycache__',
+    '.venv',
+    'venv',
+    '.tox',
+    '.next',
+    '.nuxt',
+    '.cache',
+    'target',
+    '.steerable',
+]);
+const IGNORED_FILE_NAMES = new Set(['.DS_Store']);
+/** 单次扫描的遍历上限：深度 10、条目 10 万、结果 100 条。 */
+const MAX_DEPTH = 10;
+const MAX_VISITED = 100_000;
+const MAX_FILES = 100;
+/** 显式写工具：参数里的 path 并入产物列表（覆盖可写根之外的写入）。 */
+const WRITE_TOOL_NAMES = new Set(['local_write_file', 'local_edit_file']);
+/** exec 类工具：cwd 浅扫描与命令文本路径字面量的来源。 */
+const EXEC_TOOL_NAMES = new Set(['local_exec_shell', 'local_run_snippet']);
+/** 每条命令/代码文本最多提取的路径字面量个数（防超长命令刷 stat）。 */
+const MAX_PATH_LITERALS_PER_ACTION = 50;
+/**
+ * Linux overlay/tmpfs 常把 mtime/birthtime 截到 1s。回合开始后立刻写出的
+ * 产物会 stat 成略早于 sinceMs，被水位线丢掉。1s 容差远小于一轮对话，
+ * 只影响展示列表，允许把回合前 1s 内的文件算进来。
+ */
+const TOUCHED_SLACK_MS = 1000;
+/**
+ * 引号包裹的绝对路径字面量：python 代码里的 doc.save('/x/a.pdf')、shell
+ * 里的 "/x/a.pdf"。要求以 /、~/ 或 Windows 盘符开头、带扩展名结尾。
+ * 贪婪匹配到闭引号再回溯到最后一个点——目录名里带点（.venv/python3.11）
+ * 不会把路径截断在中间。
+ */
+const QUOTED_PATH_PATTERN = /['"]((?:~\/|\/|[A-Za-z]:[\\/])[^'"]{1,300}\.[A-Za-z0-9]{1,10})['"]/g;
+/**
+ * 裸绝对路径字面量（无引号、无空格）：shell 重定向/参数里常见的写法。
+ * 排除引号/空白/shell 元字符；URL 的 // 开头被 (?!\/) 挡掉；同样贪婪到
+ * token 尾再回溯到最后一个点，(?![A-Za-z0-9]) 保证扩展名不被截断。
+ */
+const BARE_PATH_PATTERN = /(?:~\/|\/(?!\/))[^\s"'`<>|;,()[\]{}\\*?]{1,300}\.[A-Za-z0-9]{1,10}(?![A-Za-z0-9])|[A-Za-z]:\\[^\s"'`<>|;,*?]{1,300}\.[A-Za-z0-9]{1,10}(?![A-Za-z0-9])/g;
+/**
+ * 收集本轮产物文件。`sinceMs` 是回合开始的 epoch ms；`projectRoot` 用于把
+ * 写工具的相对路径参数解析成绝对路径（与 local-executor 的项目根解析一致）。
+ * `homeDir` 仅测试注入用，默认 os.homedir()——exec 缺省 cwd 的回落值。
+ */
+export async function collectTurnFiles(options) {
+    const { roots, sinceMs, projectRoot = null } = options;
+    const homeDir = options.homeDir ?? os.homedir();
+    const byPath = new Map();
+    for (const root of roots) {
+        await scanRoot(root, sinceMs, byPath);
+    }
+    const shallowRoots = new Set();
+    for (const action of options.actions ?? []) {
+        await collectWriteToolPath(action, sinceMs, projectRoot, byPath);
+        const cwd = execCwdOf(action, projectRoot, homeDir);
+        if (cwd && !isCoveredByRoots(cwd, roots))
+            shallowRoots.add(cwd);
+        await collectPathLiterals(action, sinceMs, homeDir, byPath);
+    }
+    for (const dir of shallowRoots) {
+        await scanShallow(dir, sinceMs, byPath);
+    }
+    return [...byPath.values()]
+        .sort((a, b) => a.path.localeCompare(b.path))
+        .slice(0, MAX_FILES);
+}
+async function scanRoot(root, sinceMs, out) {
+    const state = { visited: 0 };
+    await walk(path.resolve(root), sinceMs, 0, state, out);
+}
+async function walk(dir, sinceMs, depth, state, out) {
+    if (depth > MAX_DEPTH || state.visited >= MAX_VISITED)
+        return;
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        // 根目录被删/无权限：跳过该根，不影响其他根。
+        return;
+    }
+    for (const entry of entries) {
+        if (state.visited >= MAX_VISITED)
+            return;
+        state.visited += 1;
+        const full = path.join(dir, entry.name);
+        // 不跟随符号链接：避免链接环把扫描拖出根外。
+        if (entry.isSymbolicLink())
+            continue;
+        if (entry.isDirectory()) {
+            if (IGNORED_DIR_NAMES.has(entry.name))
+                continue;
+            await walk(full, sinceMs, depth + 1, state, out);
+            continue;
+        }
+        if (!entry.isFile() || IGNORED_FILE_NAMES.has(entry.name))
+            continue;
+        const file = await statTurnFile(full, sinceMs);
+        if (file)
+            out.set(full, file);
+    }
+}
+/** stat 一个文件，命中「本轮触碰过」则返回 TurnFile，否则 null。 */
+async function statTurnFile(full, sinceMs) {
+    let stat;
+    try {
+        stat = await fs.stat(full);
+    }
+    catch {
+        // 扫描窗口内被删掉的文件直接略过。
+        return null;
+    }
+    // 路径字面量可能指到目录（如 xxx.app 包）；产物列表只收文件。
+    if (!stat.isFile())
+        return null;
+    const touched = stat.mtimeMs + TOUCHED_SLACK_MS >= sinceMs ||
+        stat.birthtimeMs + TOUCHED_SLACK_MS >= sinceMs;
+    if (!touched)
+        return null;
+    return { path: full, kind: kindOf(stat, sinceMs), size: stat.size };
+}
+function kindOf(stat, sinceMs) {
+    // birthtime 不可用的文件系统返回 0/负值——此时无法区分新建与修改，
+    // 统一标 modified（标签降级，不漏文件）。
+    return stat.birthtimeMs >= sinceMs ? 'created' : 'modified';
+}
+async function collectWriteToolPath(action, sinceMs, projectRoot, out) {
+    if (typeof action.tool !== 'string' || !WRITE_TOOL_NAMES.has(action.tool))
+        return;
+    // success === false 的调用没写成；undefined（流中未落定）按成功处理——
+    // 文件是否真存在由下面的 stat 把关。
+    if (action.success === false)
+        return;
+    const args = action.arguments;
+    if (!args || typeof args !== 'object')
+        return;
+    const raw = args.path;
+    if (typeof raw !== 'string' || !raw.trim())
+        return;
+    const full = path.isAbsolute(raw)
+        ? path.normalize(raw)
+        : projectRoot
+            ? path.resolve(projectRoot, raw)
+            : null;
+    if (!full || out.has(full))
+        return;
+    const file = await statTurnFile(full, sinceMs);
+    if (file)
+        out.set(full, file);
+}
+/**
+ * exec 行动的实际工作目录（与 tool-router / local-executor 的解析规则对齐）：
+ * 显式 cwd 展开 ~ 后按绝对/相对解析（相对在项目模式下按项目根、否则按
+ * 进程 cwd）；缺省 cwd 回落到项目根，无项目时回落到 home——无项目对话里
+ * 脚本产物最常见的落点。
+ */
+function execCwdOf(action, projectRoot, homeDir) {
+    if (typeof action.tool !== 'string' || !EXEC_TOOL_NAMES.has(action.tool))
+        return null;
+    const args = action.arguments;
+    if (!args || typeof args !== 'object')
+        return null;
+    const raw = args.cwd;
+    const cwdArg = typeof raw === 'string' ? raw.trim() : '';
+    if (!cwdArg)
+        return projectRoot ?? homeDir;
+    const expanded = cwdArg.startsWith('~') ? path.join(homeDir, cwdArg.slice(1)) : cwdArg;
+    if (path.isAbsolute(expanded))
+        return path.normalize(expanded);
+    return projectRoot ? path.resolve(projectRoot, expanded) : path.resolve(expanded);
+}
+/** cwd 已落在某个递归根之内时无需再浅扫（递归扫描已覆盖且更深）。 */
+function isCoveredByRoots(cwd, roots) {
+    return roots.some((root) => {
+        const rel = path.relative(path.resolve(root), cwd);
+        return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+    });
+}
+/**
+ * exec cwd 的浅扫描：只看顶层一层、跳过点文件。home 顶层的变化几乎全是
+ * 工具状态（.zsh_history 之类），点文件过滤掉它们；真正的产物文档极少
+ * 以点开头。浅扫不递归——home 这种根递归起来既慢又全是无关变化。
+ */
+async function scanShallow(dir, sinceMs, out) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        // cwd 被删/无权限：跳过，不影响其他来源。
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith('.') || IGNORED_FILE_NAMES.has(entry.name))
+            continue;
+        if (entry.isSymbolicLink() || !entry.isFile())
+            continue;
+        const full = path.join(dir, entry.name);
+        if (out.has(full))
+            continue;
+        const file = await statTurnFile(full, sinceMs);
+        if (file)
+            out.set(full, file);
+    }
+}
+/**
+ * 从 exec 命令 / snippet 代码文本里提取绝对路径字面量，stat + 水位线
+ * 验证后并入。覆盖脚本写到与 cwd 无关的任意位置。local_run_script 的
+ * 脚本内容在注册表里、行动参数只有 scriptId，不在此覆盖（其 cwd 语义
+ * 与 exec_shell 相同，浅扫描已兜底常见落点）。
+ */
+async function collectPathLiterals(action, sinceMs, homeDir, out) {
+    if (typeof action.tool !== 'string' || !EXEC_TOOL_NAMES.has(action.tool))
+        return;
+    const args = action.arguments;
+    if (!args || typeof args !== 'object')
+        return;
+    const record = args;
+    const text = [record.command, record.code]
+        .filter((value) => typeof value === 'string')
+        .join('\n');
+    if (!text)
+        return;
+    const candidates = new Set();
+    for (const pattern of [QUOTED_PATH_PATTERN, BARE_PATH_PATTERN]) {
+        pattern.lastIndex = 0;
+        for (const match of text.matchAll(pattern)) {
+            if (candidates.size >= MAX_PATH_LITERALS_PER_ACTION)
+                break;
+            const literal = match[1] ?? match[0];
+            const expanded = literal.startsWith('~/')
+                ? path.join(homeDir, literal.slice(2))
+                : literal;
+            candidates.add(path.normalize(expanded));
+        }
+    }
+    for (const full of candidates) {
+        if (out.has(full))
+            continue;
+        const file = await statTurnFile(full, sinceMs);
+        if (file)
+            out.set(full, file);
+    }
+}

package/dist/main.js

@@ -64,7 +64,7 @@ const RETRY_DELAYS = [2000, 5000, 10000, 30000];
 // 导致模型退化成"假后台"）。CS 的差异只剩广播（IPC）与生命周期。
 const runtime = createHostRuntime({
     broadcast: (channel, payload) => broadcastTerminalEvent(channel, payload),
-    // LocalBackendRouter 的后台事件（目前只有 chat-title-updated）只推主窗口。
+    // LocalBackendRouter 的后台事件（chat-title-updated / suggested-replies）只推主窗口。
     // 没拿到 mainWindow 时静默丢——title 是 nice-to-have，不该让启动顺序影响功能。
     broadcastMain: (eventName, payload) => {
         if (!mainWindow || mainWindow.isDestroyed())
@@ -544,9 +544,11 @@ function setupIpcHandlers() {
     // validated and routed to the pending sidecar `approval.request` call;
     // unknown requestIds (late/stale answers) are dropped.
     ipcMain.handle('approval:decide', (_event, payload) => approvalBridge.decide(payload));
+    ipcMain.handle('approval:pending', () => approvalBridge.pending());
     // W8: the renderer's ask-user card answers here; routed to the pending
     // sidecar `ask_user.request` call (fail-open empty answers on mismatch).
     ipcMain.handle('ask-user:answer', (_event, payload) => askUserBridge.answer(payload));
+    ipcMain.handle('ask-user:pending', () => askUserBridge.pending());
     ipcMain.handle('local:update-safety-config', async (_event, config) => {
         localExecutor.updateSafetyConfig(config);
         return { success: true };

package/dist/preload.cjs

@@ -87,6 +87,25 @@ function buildPreloadApi(packContributions = {}) {
         import_electron.ipcRenderer.removeListener("chat-title-updated", handler);
       };
     },
+    /**
+     * 回合追问建议就绪。Backend 在助手回复完成后 fire-and-forget 生成 3 条
+     * 下一轮用户输入；启发式兜底会立刻推一次，LLM 成功后再替换。返回 unsubscribe。
+     */
+    onSuggestedReplies: (callback) => {
+      const handler = (_event, payload) => {
+        if (typeof payload?.chatId === "string" && typeof payload?.messageId === "string" && Array.isArray(payload.suggestions) && payload.suggestions.every((item) => typeof item === "string")) {
+          callback({
+            chatId: payload.chatId,
+            messageId: payload.messageId,
+            suggestions: payload.suggestions
+          });
+        }
+      };
+      import_electron.ipcRenderer.on("suggested-replies", handler);
+      return () => {
+        import_electron.ipcRenderer.removeListener("suggested-replies", handler);
+      };
+    },
     /**
      * 会话补建通知：Backend 在向本地不存在的 chatId 首次发送时按 URL 里的 id
      * 现场补建会话，并广播 `chat-created`（{chatId, agentId}）。返回 unsubscribe
@@ -154,9 +173,9 @@ function buildPreloadApi(packContributions = {}) {
     },
     /**
      * W4-1 审批代数：sidecar 的 ApprovalExecutor 经反向通道请示，主进程把
-     * 请求广播到 renderer（approval:request），审批弹窗应答后走
-     * approval:decide 回到主进程。订阅返回 unsubscribe；同一时刻只有一个
-     * 弹窗监听者（AgentPage 挂载的 ApprovalModalHost）。
+     * 请求广播到 renderer（approval:request），输入区审批菜单应答后走
+     * approval:decide 回到主进程。pending 供刷新后的 renderer 恢复仍在等待
+     * 的请求。
      */
     approval: {
       onRequest: (callback) => {
@@ -173,13 +192,16 @@ function buildPreloadApi(packContributions = {}) {
       },
       decide: async (decision) => {
         await import_electron.ipcRenderer.invoke("approval:decide", decision);
+      },
+      pending: async () => {
+        return await import_electron.ipcRenderer.invoke("approval:pending");
       }
     },
     /**
      * W8 结构化提问：sidecar 的 ask_user 工具经反向通道请示，主进程把
      * 请求广播到 renderer（ask-user:request），问题卡片应答后走
-     * ask-user:answer 回到主进程。订阅返回 unsubscribe；同一时刻只有一个
-     * 卡片监听者（AgentLayout 挂载的 AskUserModalHost）。
+     * ask-user:answer 回到主进程。pending 供刷新后的 renderer 恢复仍在等待
+     * 的请求。
      */
     askUser: {
       onRequest: (callback) => {
@@ -196,6 +218,9 @@ function buildPreloadApi(packContributions = {}) {
       },
       answer: async (reply) => {
         await import_electron.ipcRenderer.invoke("ask-user:answer", reply);
+      },
+      pending: async () => {
+        return await import_electron.ipcRenderer.invoke("ask-user:pending");
       }
     },
     local: {
@@ -380,11 +405,6 @@ function buildPreloadApi(packContributions = {}) {
         const fn = (_event, session) => callback(session);
         import_electron.ipcRenderer.on("terminal:spawned", fn);
         return () => import_electron.ipcRenderer.removeListener("terminal:spawned", fn);
-      },
-      onReveal: (callback) => {
-        const fn = (_event, payload) => callback(payload);
-        import_electron.ipcRenderer.on("terminal:reveal", fn);
-        return () => import_electron.ipcRenderer.removeListener("terminal:reveal", fn);
       }
     }
   };

package/dist/preload.js

@@ -103,6 +103,28 @@ export function buildPreloadApi(packContributions = {}) {
                 ipcRenderer.removeListener('chat-title-updated', handler);
             };
         },
+        /**
+         * 回合追问建议就绪。Backend 在助手回复完成后 fire-and-forget 生成 3 条
+         * 下一轮用户输入；启发式兜底会立刻推一次，LLM 成功后再替换。返回 unsubscribe。
+         */
+        onSuggestedReplies: (callback) => {
+            const handler = (_event, payload) => {
+                if (typeof payload?.chatId === 'string' &&
+                    typeof payload?.messageId === 'string' &&
+                    Array.isArray(payload.suggestions) &&
+                    payload.suggestions.every((item) => typeof item === 'string')) {
+                    callback({
+                        chatId: payload.chatId,
+                        messageId: payload.messageId,
+                        suggestions: payload.suggestions,
+                    });
+                }
+            };
+            ipcRenderer.on('suggested-replies', handler);
+            return () => {
+                ipcRenderer.removeListener('suggested-replies', handler);
+            };
+        },
         /**
          * 会话补建通知：Backend 在向本地不存在的 chatId 首次发送时按 URL 里的 id
          * 现场补建会话，并广播 `chat-created`（{chatId, agentId}）。返回 unsubscribe
@@ -171,9 +193,9 @@ export function buildPreloadApi(packContributions = {}) {
         },
         /**
          * W4-1 审批代数：sidecar 的 ApprovalExecutor 经反向通道请示，主进程把
-         * 请求广播到 renderer（approval:request），审批弹窗应答后走
-         * approval:decide 回到主进程。订阅返回 unsubscribe；同一时刻只有一个
-         * 弹窗监听者（AgentPage 挂载的 ApprovalModalHost）。
+         * 请求广播到 renderer（approval:request），输入区审批菜单应答后走
+         * approval:decide 回到主进程。pending 供刷新后的 renderer 恢复仍在等待
+         * 的请求。
          */
         approval: {
             onRequest: (callback) => {
@@ -191,12 +213,15 @@ export function buildPreloadApi(packContributions = {}) {
             decide: async (decision) => {
                 await ipcRenderer.invoke('approval:decide', decision);
             },
+            pending: async () => {
+                return await ipcRenderer.invoke('approval:pending');
+            },
         },
         /**
          * W8 结构化提问：sidecar 的 ask_user 工具经反向通道请示，主进程把
          * 请求广播到 renderer（ask-user:request），问题卡片应答后走
-         * ask-user:answer 回到主进程。订阅返回 unsubscribe；同一时刻只有一个
-         * 卡片监听者（AgentLayout 挂载的 AskUserModalHost）。
+         * ask-user:answer 回到主进程。pending 供刷新后的 renderer 恢复仍在等待
+         * 的请求。
          */
         askUser: {
             onRequest: (callback) => {
@@ -214,6 +239,9 @@ export function buildPreloadApi(packContributions = {}) {
             answer: async (reply) => {
                 await ipcRenderer.invoke('ask-user:answer', reply);
             },
+            pending: async () => {
+                return await ipcRenderer.invoke('ask-user:pending');
+            },
         },
         local: {
             selectDirectory: async (options) => {
@@ -398,11 +426,6 @@ export function buildPreloadApi(packContributions = {}) {
                 ipcRenderer.on('terminal:spawned', fn);
                 return () => ipcRenderer.removeListener('terminal:spawned', fn);
             },
-            onReveal: (callback) => {
-                const fn = (_event, payload) => callback(payload);
-                ipcRenderer.on('terminal:reveal', fn);
-                return () => ipcRenderer.removeListener('terminal:reveal', fn);
-            },
         },
     };
     contextBridge.exposeInMainWorld('electron', { ...electronAPI, ...packContributions });

package/dist/server/http-server.js

@@ -230,11 +230,19 @@ export function createBsServer(deps) {
             sendJson(res, 200, await approvalBridge.decide(body));
             return;
         }
+        if (method === 'GET' && pathname === '/host/approval/pending') {
+            sendJson(res, 200, approvalBridge.pending());
+            return;
+        }
         // ─── ask_user（对齐 ask-user:answer IPC） ───
         if (method === 'POST' && pathname === '/host/ask-user/answer') {
             sendJson(res, 200, askUserBridge.answer(body));
             return;
         }
+        if (method === 'GET' && pathname === '/host/ask-user/pending') {
+            sendJson(res, 200, askUserBridge.pending());
+            return;
+        }
         // ─── local（对齐 local:* IPC） ───
         if (method === 'POST' && pathname === '/host/local/exec-shell') {
             const request = body;

package/dist/server/sse-bus.d.ts

@@ -1,7 +1,7 @@
 /**
  * BS 模式的 SSE 事件总线：替代 Electron 的 `webContents.send(channel, payload)`
  * 广播。所有宿主事件（terminal:data、approval:request、chat-title-updated、
- * 场景包事件……）经这一条 `GET /api/v2/events` 长连接推给浏览器，
+ * suggested-replies、场景包事件……）经这一条 `GET /api/v2/events` 长连接推给浏览器，
  * channel 名与 IPC 通道保持一致，前端 http-bridge 按名分发。
  */
 import type { ServerResponse } from 'node:http';

package/dist/sidecar/reverse-approval.d.ts

@@ -43,6 +43,8 @@ export interface ApprovalBridgeDeps {
 export interface ApprovalBridge {
     /** Reverse-channel handler for the sidecar's `approval.request`. */
     handler: SidecarReverseHandler;
+    /** Requests still awaiting a renderer decision, used after page refresh. */
+    pending: () => ApprovalPromptRequest[];
     /**
      * IPC entry point for the renderer's answer (`ipcMain.handle(
      * 'approval:decide')`). Unknown requestIds are dropped (late answer to an

package/dist/sidecar/reverse-approval.js

@@ -54,7 +54,7 @@ export function createApprovalBridge(deps) {
             };
             deps.onLog?.(`approval: prompting for ${toolName} (${prompt.mode}/${prompt.category})`);
             return await new Promise((resolve) => {
-                pending.set(requestId, { resolve });
+                pending.set(requestId, { prompt, resolve });
                 try {
                     deps.broadcast('approval:request', prompt);
                 }
@@ -64,6 +64,7 @@ export function createApprovalBridge(deps) {
                 }
             });
         },
+        pending: () => Array.from(pending.values(), ({ prompt }) => prompt),
         decide: (payload) => {
             const p = (payload ?? {});
             const requestId = typeof p.requestId === 'string' ? p.requestId : '';

package/dist/sidecar/reverse-ask-user.d.ts

@@ -26,6 +26,8 @@ export interface AskUserBridgeDeps {
 export interface AskUserBridge {
     /** 注册为 sidecar 的 `ask_user.request` 反向方法处理器。 */
     handler: SidecarReverseHandler;
+    /** 返回仍在等待 renderer 应答的请求，供刷新后的页面恢复提问。 */
+    pending: () => AskUserPromptRequest[];
     /** renderer `ask-user:answer` 的入口；返回是否匹配到待应答请求。 */
     answer: (payload: unknown) => {
         ok: boolean;

package/dist/sidecar/reverse-ask-user.js

@@ -32,7 +32,7 @@ export function createAskUserBridge(deps) {
                 questions: questions,
             };
             return new Promise((resolve) => {
-                pending.set(requestId, { resolve });
+                pending.set(requestId, { prompt, resolve });
                 try {
                     deps.broadcast('ask-user:request', prompt);
                 }
@@ -43,6 +43,7 @@ export function createAskUserBridge(deps) {
                 }
             });
         },
+        pending: () => Array.from(pending.values(), ({ prompt }) => prompt),
         answer: (payload) => {
             const p = (payload ?? {});
             const entry = typeof p.requestId === 'string' ? pending.get(p.requestId) : undefined;

package/dist/storage/index.d.ts

@@ -239,6 +239,12 @@ export declare class LocalStore {
      */
     deleteMessagesFrom(chatId: string, messageId: string): number;
     addMessage(chatId: string, role: ChatMessageRecord['role'], content: string, messageMetadata?: string | null): ChatMessageRecord;
+    /**
+     * 浅合并助手消息的 JSON metadata（例如回合结束后写入 suggestedReplies）。
+     * 不碰 updated_at：这类补丁不是用户可见的会话活动。
+     * metadata 损坏或非对象时从空对象开始合。
+     */
+    patchMessageMetadata(chatId: string, messageId: string, patch: Record<string, unknown>): ChatMessageRecord | null;
     /**
      * W1.2.1: replace the chat's whole message list with a branch projection.
      * The desktop store is the UI projection of the ACTIVE framework record —

package/dist/storage/index.js

@@ -669,6 +669,33 @@ export class LocalStore {
         const row = this.db.prepare(`SELECT * FROM chat_messages WHERE id = ?`).get(id);
         return this.mapChatMessage(row);
     }
+    /**
+     * 浅合并助手消息的 JSON metadata（例如回合结束后写入 suggestedReplies）。
+     * 不碰 updated_at：这类补丁不是用户可见的会话活动。
+     * metadata 损坏或非对象时从空对象开始合。
+     */
+    patchMessageMetadata(chatId, messageId, patch) {
+        const msg = this.getMessage(chatId, messageId);
+        if (!msg)
+            return null;
+        let current = {};
+        if (msg.messageMetadata) {
+            try {
+                const parsed = JSON.parse(msg.messageMetadata);
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    current = parsed;
+                }
+            }
+            catch {
+                current = {};
+            }
+        }
+        const next = JSON.stringify({ ...current, ...patch });
+        this.db
+            .prepare(`UPDATE chat_messages SET message_metadata = ? WHERE id = ? AND chat_id = ?`)
+            .run(next, messageId, chatId);
+        return this.getMessage(chatId, messageId);
+    }
     /**
      * W1.2.1: replace the chat's whole message list with a branch projection.
      * The desktop store is the UI projection of the ACTIVE framework record —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/agent-shell",
-  "version": "0.6.20",
+  "version": "0.6.21",
   "description": "Steerable framework — product-neutral desktop/headless agent host (Tier 5). Electron main + preload + headless HTTP server (BS) sharing one storage/sidecar/tooling core; scenario packs extend it through the @steerable/pack-sdk contract and are composed at build time by the consuming product.",
   "license": "Apache-2.0",
   "homepage": "https://steerableframework.com/",
@@ -41,9 +41,9 @@
     "electron-store": "^8.1.0",
     "he": "^1.2.0",
     "node-pty": "^1.1.0",
-    "@steerable/agent-protocol": "0.6.20",
-    "@steerable/agent-harness": "0.6.20",
-    "@steerable/pack-sdk": "0.6.20"
+    "@steerable/agent-harness": "0.6.21",
+    "@steerable/agent-protocol": "0.6.21",
+    "@steerable/pack-sdk": "0.6.21"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",