@steerable/agent-shell 0.6.20 → 0.6.22

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/prompt-builder.d.ts

@@ -48,6 +48,11 @@ export interface BuildPromptOptions {
      * 仍然优先——模式级排除（plan 模式的执行类技能）不因勾选而失效。
      */
     pinnedSkillNames?: Iterable<string>;
+    /**
+     * 本轮自称。有绑定智能体时用智能体显示名，渲染技能正文 `{agentName}`；
+     * 未传则回落产品品牌 `brand.agentName`。
+     */
+    identityName?: string | null;
 }
 export interface BuiltPrompt {
     prompt: string;
@@ -84,11 +89,12 @@ export declare function conditionsFromTools(toolNames: Iterable<string>, autoHas
  */
 export declare function buildSystemPrompt(options?: BuildPromptOptions): Promise<BuiltPrompt>;
 /**
- * 品牌占位符变量：技能正文里的 `{agentName}` / `{brandDisplayName}` /
- * `{brandTagline}` 渲染为当前产品注入的品牌（brand.ts；未注入 = shell
- * 中性默认）。eager 系统提示词路径统一注入；包技能同理可用。
+ * 品牌/身份占位符：`{brandDisplayName}` / `{brandTagline}` 始终是产品品牌；
+ * `{agentName}` 有本轮智能体时用智能体显示名，否则回落 `brand.agentName`。
  */
-export declare function brandSkillVars(): Record<string, string>;
+export declare function brandSkillVars(options?: {
+    identityName?: string | null;
+}): Record<string, string>;
 /** 技能正文渲染:把 `{scripts}` 及额外占位符解析为绝对路径。 */
 export declare function renderSkillContent(m: SkillModule, vars?: Record<string, string>): string;
 /** 用户显式指定技能的优先级指令头，渲染在该技能内容之前。 */

package/dist/local-backend/prompt-builder.js

@@ -14,16 +14,17 @@ import path from 'node:path';
 import { loadSkills } from './skill-loader.js';
 import { isSkillPinned } from './agent-capability.js';
 import { getBrand } from '../brand.js';
-const FALLBACK_PROMPT = (() => {
+function fallbackPrompt(identityName) {
     const brand = getBrand();
+    const name = identityName?.trim() || brand.agentName;
     return [
         '# 角色',
         '',
-        `你是 ${brand.agentName}，${brand.tagline}，运行在用户自己的 Windows / macOS / Linux 机器上。`,
+        `你是 ${name}，${brand.tagline}，运行在用户自己的 Windows / macOS / Linux 机器上。`,
         '通过工具直接操作用户的本地环境（shell、文件、当前产品安装的场景工具等）。用中文回复。',
         '不要凭空编造任何工具返回值。',
     ].join('\n');
-})();
+}
 const DEFAULT_CHAR_BUDGET = 60_000;
 /**
  * Derive condition strings from the set of tool names available this turn.
@@ -99,7 +100,7 @@ export async function buildSystemPrompt(options = {}) {
             prompt: assembleFinal({
                 personaPreamble: options.personaPreamble ?? '',
                 chatSystemPrompt: options.chatSystemPrompt ?? '',
-                body: FALLBACK_PROMPT,
+                body: fallbackPrompt(options.identityName),
                 realityCheckSuffix: options.realityCheckSuffix ?? '',
             }),
             modules,
@@ -116,9 +117,10 @@ export async function buildSystemPrompt(options = {}) {
     if (options.forcedMcpTool) {
         modules.push(buildForcedMcpToolModule(options.forcedMcpTool));
     }
-    // 品牌占位符（{agentName} 等）由产品注入的品牌渲染——shell 技能正文
-    // 保持产品中立（3.2 中性化，见 skills/00-identity）。
-    const body = modules.map((m) => renderSkillContent(m, brandSkillVars())).join('\n\n');
+    // `{agentName}` 优先用本轮智能体显示名，没有绑定智能体时才用产品品牌。
+    const body = modules
+        .map((m) => renderSkillContent(m, brandSkillVars({ identityName: options.identityName })))
+        .join('\n\n');
     return {
         prompt: assembleFinal({
             personaPreamble: options.personaPreamble ?? '',
@@ -169,14 +171,13 @@ function buildForcedMcpToolModule(t) {
     };
 }
 /**
- * 品牌占位符变量：技能正文里的 `{agentName}` / `{brandDisplayName}` /
- * `{brandTagline}` 渲染为当前产品注入的品牌（brand.ts；未注入 = shell
- * 中性默认）。eager 系统提示词路径统一注入；包技能同理可用。
+ * 品牌/身份占位符：`{brandDisplayName}` / `{brandTagline}` 始终是产品品牌；
+ * `{agentName}` 有本轮智能体时用智能体显示名，否则回落 `brand.agentName`。
  */
-export function brandSkillVars() {
+export function brandSkillVars(options = {}) {
     const brand = getBrand();
     return {
-        agentName: brand.agentName,
+        agentName: options.identityName?.trim() || brand.agentName,
         brandDisplayName: brand.displayName,
         brandTagline: brand.tagline,
     };

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

@@ -1,9 +1,13 @@
+import type { ScopedStore } from '../storage/scoped-store.js';
 import { ToolRouter } from '../tool-router.js';
 import type { TaskService } from './task-service.js';
+import { type Principal } from '../auth/index.js';
 export interface LocalBackendRequest {
     method: string;
     path: string;
     body?: unknown;
+    /** Authenticated identity supplied by the BS HTTP layer. */
+    principal?: Principal;
 }
 export interface LocalBackendResponse<T = unknown> {
     status: number;
@@ -39,14 +43,23 @@ export interface StreamOptions {
 export type LocalBackendBroadcast = (eventName: string, payload: unknown) => void;
 export declare class LocalBackendRouter {
     private readonly toolRouter;
+    private readonly defaultStore;
+    private readonly storeContext;
+    private readonly resolveStore;
     private readonly broadcast;
     /** 4.6a/4.6c：任务面板的路由入口（列表 + 合并/丢弃）。未注入时任务路由 503。 */
     private readonly taskService;
-    constructor(toolRouter: ToolRouter, options?: {
+    constructor(toolRouter: ToolRouter, options: {
+        store: ScopedStore;
+        resolveStore?: (principal?: Principal) => ScopedStore;
         broadcast?: LocalBackendBroadcast;
         taskService?: TaskService;
     });
+    private get store();
+    /** Store selected for the active request, or the host default outside one. */
+    get activeStore(): ScopedStore;
     handle(request: LocalBackendRequest): Promise<LocalBackendResponse>;
+    private handleScoped;
     /**
      * 对未显式实现的路由做"温柔降级"：GET 返回空集合/空对象，不让 UI 因 404 抛错跳到
      * not-found；其他方法返回 success:true 让前端流程继续。所有兜底都在主进程终端
@@ -62,10 +75,12 @@ 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]` 串。
      */
     handleStream(request: LocalBackendRequest, emit: StreamEmit, options?: StreamOptions): Promise<StreamResult>;
+    private handleStreamScoped;
     /**
      * 后台异步生成 chat 标题。**完全 fire-and-forget**——不阻塞 `[DONE]`，
      * 调用方只要 `void this.runTitleGenInBackground(...)` 就行。
@@ -88,10 +103,10 @@ export declare class LocalBackendRouter {
      * Public: main.ts 的反向通道（reverse-tools.ts）经它给 CoreLoop 路径的
      * 工具调用补上 projectRoot 围栏。
      */
-    resolveChatProject(chatId: string): {
+    resolveChatProject(chatId: string): Promise<{
         name: string;
         folderPath: string;
-    } | null;
+    } | null>;
     /**
      * 解析本轮生效的智能体：人设前言、技能勾选、工具策略同源于这一次解析。
      *
@@ -105,7 +120,7 @@ export declare class LocalBackendRouter {
      *
      * @param chatId 当前对话 id。
      * @param payload 前端提交的流请求体。
-     * @returns 本轮的智能体顺序、人设智能体，以及合并后的能力面。
+     * @returns 本轮的智能体顺序、人设智能体、自称，以及合并后的能力面。
      */
     private resolveTurnAgents;
     private buildConversationMessages;
@@ -158,6 +173,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 字段路由。