@steerable/agent-shell 0.6.15

package/dist/local-backend/llm-diagnose.js

@@ -0,0 +1,284 @@
+/**
+ * W-llm-diagnose: LLM link diagnosis orchestration.
+ *
+ * The settings page's "诊断" button runs a battery of probes against the
+ * configured provider: DNS resolution, TCP connect, TLS handshake, HTTP
+ * GET /models, and a minimal chat completion. Each probe is timed and
+ * classified so the UI can render a per-step verdict.
+ *
+ * The diagnosis runs in the host process (not the sidecar) because it
+ * needs to observe the *host's* network path — the sidecar's sandboxed
+ * view would hide proxy misconfigurations that the user needs to see.
+ */
+import { lookup } from 'node:dns/promises';
+import { connect } from 'node:net';
+import { request as httpsRequest } from 'node:https';
+import { request as httpRequest } from 'node:http';
+import { collectAmbientProxyEndpoints } from '../sidecar/proxy-detect.js';
+import { egressFailureHint } from '../sidecar/egress-hint.js';
+/**
+ * Run the full diagnosis battery against `baseUrl` with `apiKey`.
+ * `model` is used for the chat-completion probe; when omitted the
+ * battery stops after the HTTP probe.
+ */
+export async function diagnoseLlmConnection(options) {
+    const { baseUrl, apiKey, model, timeoutMs = 15_000 } = options;
+    const steps = [];
+    const ambientProxies = await collectAmbientProxyEndpoints();
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        return {
+            ok: false,
+            steps: [
+                {
+                    name: 'parse-url',
+                    ok: false,
+                    durationMs: 0,
+                    detail: `无法解析 baseUrl: ${baseUrl}`,
+                },
+            ],
+            ambientProxies,
+            hint: 'baseUrl 格式不正确，请检查是否包含协议（http:// 或 https://）。',
+        };
+    }
+    const host = url.hostname;
+    const port = url.port ? Number(url.port) : url.protocol === 'https:' ? 443 : 80;
+    const isHttps = url.protocol === 'https:';
+    // Step 1: DNS resolution
+    const dnsStart = Date.now();
+    try {
+        const addresses = await lookup(host, { all: true });
+        steps.push({
+            name: 'dns',
+            ok: true,
+            durationMs: Date.now() - dnsStart,
+            detail: `解析到 ${addresses.length} 个地址: ${addresses.map((a) => a.address).join(', ')}`,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        steps.push({
+            name: 'dns',
+            ok: false,
+            durationMs: Date.now() - dnsStart,
+            detail: `DNS 解析失败: ${message}`,
+        });
+        return {
+            ok: false,
+            steps,
+            ambientProxies,
+            hint: '域名解析失败，请检查 baseUrl 域名是否正确，或检查 DNS 配置。',
+        };
+    }
+    // Step 2: TCP connect
+    const tcpStart = Date.now();
+    try {
+        await new Promise((resolve, reject) => {
+            const socket = connect(port, host, () => {
+                socket.destroy();
+                resolve();
+            });
+            socket.once('error', reject);
+            socket.setTimeout(timeoutMs, () => {
+                socket.destroy();
+                reject(new Error('ETIMEDOUT'));
+            });
+        });
+        steps.push({
+            name: 'tcp',
+            ok: true,
+            durationMs: Date.now() - tcpStart,
+            detail: `TCP 连接 ${host}:${port} 成功`,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        steps.push({
+            name: 'tcp',
+            ok: false,
+            durationMs: Date.now() - tcpStart,
+            detail: `TCP 连接失败: ${message}`,
+        });
+        return {
+            ok: false,
+            steps,
+            ambientProxies,
+            hint: egressFailureHint(message) ?? '无法连接到模型服务，请检查网络或防火墙配置。',
+        };
+    }
+    // Step 3: TLS handshake (https only)
+    if (isHttps) {
+        const tlsStart = Date.now();
+        try {
+            await new Promise((resolve, reject) => {
+                const req = httpsRequest({
+                    host,
+                    port,
+                    method: 'HEAD',
+                    path: '/',
+                    timeout: timeoutMs,
+                    rejectUnauthorized: false, // diagnosis only — we want to see the cert, not enforce it
+                }, (res) => {
+                    res.resume();
+                    resolve();
+                });
+                req.once('error', reject);
+                req.once('timeout', () => {
+                    req.destroy();
+                    reject(new Error('ETIMEDOUT'));
+                });
+                req.end();
+            });
+            steps.push({
+                name: 'tls',
+                ok: true,
+                durationMs: Date.now() - tlsStart,
+                detail: 'TLS 握手成功',
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            steps.push({
+                name: 'tls',
+                ok: false,
+                durationMs: Date.now() - tlsStart,
+                detail: `TLS 握手失败: ${message}`,
+            });
+            return {
+                ok: false,
+                steps,
+                ambientProxies,
+                hint: 'TLS 握手失败，可能是证书问题或代理拦截。请检查系统代理设置，或尝试 HTTP 直连（如果服务支持）。',
+            };
+        }
+    }
+    // Step 4: HTTP GET /models
+    const httpStart = Date.now();
+    const modelsPath = url.pathname.replace(/\/$/, '') + '/models';
+    try {
+        const status = await new Promise((resolve, reject) => {
+            const requestFn = isHttps ? httpsRequest : httpRequest;
+            const req = requestFn({
+                host,
+                port,
+                method: 'GET',
+                path: modelsPath,
+                timeout: timeoutMs,
+                rejectUnauthorized: false,
+                headers: {
+                    ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+                    Accept: 'application/json',
+                },
+            }, (res) => {
+                res.resume();
+                resolve(res.statusCode ?? 0);
+            });
+            req.once('error', reject);
+            req.once('timeout', () => {
+                req.destroy();
+                reject(new Error('ETIMEDOUT'));
+            });
+            req.end();
+        });
+        const ok = status >= 200 && status < 500; // 4xx means the endpoint is reachable but auth/model is wrong
+        steps.push({
+            name: 'http-models',
+            ok,
+            durationMs: Date.now() - httpStart,
+            detail: `GET ${modelsPath} → HTTP ${status}`,
+        });
+        if (!ok) {
+            return {
+                ok: false,
+                steps,
+                ambientProxies,
+                hint: `模型服务返回 HTTP ${status}，请检查 baseUrl 与 API Key 配置。`,
+            };
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        steps.push({
+            name: 'http-models',
+            ok: false,
+            durationMs: Date.now() - httpStart,
+            detail: `GET ${modelsPath} 失败: ${message}`,
+        });
+        return {
+            ok: false,
+            steps,
+            ambientProxies,
+            hint: egressFailureHint(message) ?? '无法访问模型服务，请检查网络或代理配置。',
+        };
+    }
+    // Step 5: chat completion (optional)
+    if (model) {
+        const chatStart = Date.now();
+        const chatPath = url.pathname.replace(/\/$/, '') + '/chat/completions';
+        try {
+            const status = await new Promise((resolve, reject) => {
+                const requestFn = isHttps ? httpsRequest : httpRequest;
+                const req = requestFn({
+                    host,
+                    port,
+                    method: 'POST',
+                    path: chatPath,
+                    timeout: timeoutMs,
+                    rejectUnauthorized: false,
+                    headers: {
+                        'Content-Type': 'application/json',
+                        ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+                    },
+                }, (res) => {
+                    res.resume();
+                    resolve(res.statusCode ?? 0);
+                });
+                req.once('error', reject);
+                req.once('timeout', () => {
+                    req.destroy();
+                    reject(new Error('ETIMEDOUT'));
+                });
+                req.write(JSON.stringify({
+                    model,
+                    messages: [{ role: 'user', content: 'ping' }],
+                    max_tokens: 1,
+                }));
+                req.end();
+            });
+            const ok = status >= 200 && status < 500;
+            steps.push({
+                name: 'chat-completion',
+                ok,
+                durationMs: Date.now() - chatStart,
+                detail: `POST ${chatPath} → HTTP ${status}`,
+            });
+            if (!ok) {
+                return {
+                    ok: false,
+                    steps,
+                    ambientProxies,
+                    hint: `模型服务返回 HTTP ${status}，请检查模型名与 API Key 配置。`,
+                };
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            steps.push({
+                name: 'chat-completion',
+                ok: false,
+                durationMs: Date.now() - chatStart,
+                detail: `POST ${chatPath} 失败: ${message}`,
+            });
+            return {
+                ok: false,
+                steps,
+                ambientProxies,
+                hint: egressFailureHint(message) ?? '无法调用模型服务，请检查网络或代理配置。',
+            };
+        }
+    }
+    return { ok: true, steps, ambientProxies, hint: null };
+}

package/dist/local-backend/message-triggers.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 用户消息里的 "/" 显式触发解析（本地技能 + MCP 工具）。
+ *
+ * 从 router.ts 的 cleanUserMessage 抽出的纯函数，便于单测。支持两类触发：
+ *
+ *   /skillName 其余问题…        → forcedSkillName（指定本地技能）
+ *   /mcp__srv__tool 其余问题…   → forcedMcpToolToken（指定 MCP 工具）
+ *
+ * 行首 token 信任选择器（技能不校验存在性；MCP token 经 resolver 规范大小写）。
+ * 句中 token 必须精确命中一个已安装技能或已注册 MCP 工具才生效，避免把
+ * 路径（/mnt/c）、URL、分数（1 /2）里的斜杠误判成触发。
+ */
+export interface MessageTriggers {
+    cleanText: string;
+    skillName?: string;
+    mcpToolToken?: string;
+}
+export interface TriggerResolvers {
+    /** 名字是否对应一个已安装技能（大小写不敏感，含 displayName）。 */
+    isKnownSkill(name: string): boolean;
+    /**
+     * 把用户输入的 mcp token 规范成注册表里的精确 token（tool_call 必须用
+     * 规范名，用户手敲可能大小写不符）；未启用 / 不存在返回 null。
+     */
+    resolveMcpToolToken(token: string): string | null;
+}
+export declare function parseUserMessageTriggers(content: string, resolvers: TriggerResolvers): MessageTriggers;

package/dist/local-backend/message-triggers.js

@@ -0,0 +1,67 @@
+/**
+ * 用户消息里的 "/" 显式触发解析（本地技能 + MCP 工具）。
+ *
+ * 从 router.ts 的 cleanUserMessage 抽出的纯函数，便于单测。支持两类触发：
+ *
+ *   /skillName 其余问题…        → forcedSkillName（指定本地技能）
+ *   /mcp__srv__tool 其余问题…   → forcedMcpToolToken（指定 MCP 工具）
+ *
+ * 行首 token 信任选择器（技能不校验存在性；MCP token 经 resolver 规范大小写）。
+ * 句中 token 必须精确命中一个已安装技能或已注册 MCP 工具才生效，避免把
+ * 路径（/mnt/c）、URL、分数（1 /2）里的斜杠误判成触发。
+ */
+const MCP_TOKEN_PATTERN = /^mcp__/i;
+export function parseUserMessageTriggers(content, resolvers) {
+    const trimmed = content.trim();
+    if (trimmed.startsWith('/')) {
+        const spaceIndex = trimmed.indexOf(' ');
+        const rawToken = spaceIndex !== -1 ? trimmed.slice(1, spaceIndex).trim() : trimmed.slice(1).trim();
+        const remainText = spaceIndex !== -1 ? trimmed.slice(spaceIndex + 1).trim() : '';
+        // MCP 工具触发优先于技能：token 命名空间 mcp__* 与技能名天然隔离。
+        if (MCP_TOKEN_PATTERN.test(rawToken)) {
+            const token = resolvers.resolveMcpToolToken(rawToken) ?? rawToken;
+            const cleanText = remainText
+                ? `【指定MCP工具: ${token}】${remainText}`
+                : `【指定MCP工具: ${token}】请调用该工具并展示其返回结果。`;
+            return { cleanText, mcpToolToken: token };
+        }
+        if (spaceIndex !== -1) {
+            const cleanText = `【指定本地技能: ${rawToken}】${remainText}`;
+            return { cleanText, skillName: rawToken };
+        }
+        const cleanText = `【指定本地技能: ${rawToken}】请启用并展示技能「${rawToken}」的作用。`;
+        return { cleanText, skillName: rawToken };
+    }
+    const match = trimmed.match(/(?:^|\s)\/([^\s/]+)/);
+    if (match && typeof match.index === 'number' && match[1]) {
+        const matchIndex = match.index;
+        const matchedText = match[0];
+        const typed = match[1];
+        if (MCP_TOKEN_PATTERN.test(typed)) {
+            const token = resolvers.resolveMcpToolToken(typed);
+            if (token) {
+                return buildMidMessageResult(trimmed, matchIndex, matchedText, typed, (remainText) => remainText
+                    ? `【指定MCP工具: ${token}】${remainText}`
+                    : `【指定MCP工具: ${token}】请调用该工具并展示其返回结果。`, { mcpToolToken: token });
+            }
+        }
+        else {
+            const candidate = typed.toLowerCase();
+            if (resolvers.isKnownSkill(candidate)) {
+                return buildMidMessageResult(trimmed, matchIndex, matchedText, typed, (remainText) => remainText
+                    ? `【指定本地技能: ${candidate}】${remainText}`
+                    : `【指定本地技能: ${candidate}】请启用并展示技能「${candidate}」的作用。`, { skillName: candidate });
+            }
+        }
+    }
+    return { cleanText: trimmed };
+}
+/** 句中 token：从原文里抠掉 token 后构造 cleanText，并合并触发字段。 */
+function buildMidMessageResult(trimmed, matchIndex, matchedText, typedToken, buildCleanText, trigger) {
+    const tokenStart = matchIndex + matchedText.indexOf('/');
+    const tokenEnd = tokenStart + 1 + typedToken.length;
+    const remainText = (trimmed.slice(0, tokenStart) + trimmed.slice(tokenEnd))
+        .replace(/\s{2,}/g, ' ')
+        .trim();
+    return { cleanText: buildCleanText(remainText), ...trigger };
+}

package/dist/local-backend/pack-backend-routes.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 场景包 local-backend 路由注册表（1.2）。
+ *
+ * 与 `host/http-routes.ts`（BS 宿主 `/host/<packId>/*`）不同：本注册表管
+ * `/api/v2/*` 命名空间下的包路由——CS/BS 双宿主都经 LocalBackendRouter
+ * 服务这一命名空间（CS 走 localBackend.request IPC 桥，BS 走 HTTP），所以
+ * 包的业务路由必须挂在这里才能双宿主可达。
+ *
+ * 命名空间纪律：每次注册调用声明一个路径前缀（如 '/api/v2/<pack>-<feature>/'），
+ * 该批路由必须全部落在前缀下；匹配发生在宿主自带路由之后、fallback 之前，
+ * 包不能遮蔽宿主路由。
+ */
+import type { PackBackendRoute, PackBackendRouteRequest, PackBackendRouteResponse } from '@steerable/pack-sdk';
+export type { PackBackendRoute, PackBackendRouteRequest, PackBackendRouteResponse };
+interface RegisteredPackBackendRoute extends PackBackendRoute {
+    readonly packId: string;
+}
+/**
+ * 注册一批包路由；`pathPrefix` 是本批路由的命名空间前缀（必须以
+ * '/api/v2/' 开头），越出前缀的路由在组装期直接抛错。
+ */
+export declare function registerPackBackendRoutes(packId: string, pathPrefix: string, routes: readonly PackBackendRoute[]): void;
+/** 测试钩子：清空注册表。 */
+export declare function resetPackBackendRoutes(): void;
+/**
+ * 匹配已注册的包路由。段参数（`:id`）逐段捕获进 params；无匹配返回 null。
+ */
+export declare function matchPackBackendRoute(method: string, pathname: string): {
+    route: RegisteredPackBackendRoute;
+    params: Record<string, string>;
+} | null;

package/dist/local-backend/pack-backend-routes.js

@@ -0,0 +1,62 @@
+/**
+ * 场景包 local-backend 路由注册表（1.2）。
+ *
+ * 与 `host/http-routes.ts`（BS 宿主 `/host/<packId>/*`）不同：本注册表管
+ * `/api/v2/*` 命名空间下的包路由——CS/BS 双宿主都经 LocalBackendRouter
+ * 服务这一命名空间（CS 走 localBackend.request IPC 桥，BS 走 HTTP），所以
+ * 包的业务路由必须挂在这里才能双宿主可达。
+ *
+ * 命名空间纪律：每次注册调用声明一个路径前缀（如 '/api/v2/<pack>-<feature>/'），
+ * 该批路由必须全部落在前缀下；匹配发生在宿主自带路由之后、fallback 之前，
+ * 包不能遮蔽宿主路由。
+ */
+const packBackendRoutes = [];
+/**
+ * 注册一批包路由；`pathPrefix` 是本批路由的命名空间前缀（必须以
+ * '/api/v2/' 开头），越出前缀的路由在组装期直接抛错。
+ */
+export function registerPackBackendRoutes(packId, pathPrefix, routes) {
+    if (!pathPrefix.startsWith('/api/v2/')) {
+        throw new Error(`[packs] local-backend 路由前缀 "${pathPrefix}" 不合规：包 "${packId}" 的前缀必须在 /api/v2/ 命名空间下`);
+    }
+    for (const route of routes) {
+        if (!route.path.startsWith(pathPrefix)) {
+            throw new Error(`[packs] local-backend 路由 "${route.path}" 不合规：包 "${packId}" 该批路由必须在 ${pathPrefix} 前缀下`);
+        }
+        packBackendRoutes.push({ ...route, packId });
+    }
+}
+/** 测试钩子：清空注册表。 */
+export function resetPackBackendRoutes() {
+    packBackendRoutes.length = 0;
+}
+/**
+ * 匹配已注册的包路由。段参数（`:id`）逐段捕获进 params；无匹配返回 null。
+ */
+export function matchPackBackendRoute(method, pathname) {
+    for (const route of packBackendRoutes) {
+        if (route.method !== method)
+            continue;
+        const params = matchPath(route.path, pathname);
+        if (params)
+            return { route, params };
+    }
+    return null;
+}
+function matchPath(pattern, pathname) {
+    const patternSegs = pattern.split('/');
+    const pathSegs = pathname.split('/');
+    if (patternSegs.length !== pathSegs.length)
+        return null;
+    const params = {};
+    for (let i = 0; i < patternSegs.length; i += 1) {
+        const seg = patternSegs[i];
+        if (seg.startsWith(':')) {
+            params[seg.slice(1)] = decodeURIComponent(pathSegs[i]);
+        }
+        else if (seg !== pathSegs[i]) {
+            return null;
+        }
+    }
+    return params;
+}

package/dist/local-backend/pack-turn-hooks.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 场景包的「回合级」钩子注册表（1.2 新增）。
+ *
+ * 包的路由/服务可以完全挂在注册表上，但有一类扩展发生在**每一条正在
+ * 流式的 CoreLoop 回合内部**。现存四个钩子位（以「文档预览包」为典型
+ * 用例）：
+ *
+ *  1. `execWritableRoots`：包要把产物写进每会话的工作区，该目录在项目
+ *     根之外，必须随回合的 exec 沙箱放行（写，不是只读根）；
+ *  2. `worldState`：把工作区路径喂给模型的 world-state，catalog 路径下
+ *     模型据此找到工作区；
+ *  3. `forcedSkillVars`：显式召唤包技能时把技能正文里的占位符渲染出
+ *     工作区路径；
+ *  4. `beginTurn` 返回的回合观察器：识别「本轮真的调用了包技能」
+ *     （onToolStart），在工具落定后扫描工作区并向渲染层广播产物更新
+ *     （onToolSettled）——替代前端轮询。
+ *
+ * 钩子按包注册、按回合拼装；未注册任何钩子的产品走零开销路径
+ * （空数组/undefined 合并，行为与注册前逐字节一致）。
+ */
+import type { PackTurnHooks, PackTurnObserver } from '@steerable/pack-sdk';
+export type { PackTurnHooks, PackTurnObserver };
+/** 注册包的回合钩子（重复注册同包后者覆盖——测试隔离靠 reset）。 */
+export declare function registerPackTurnHooks(packId: string, hooks: PackTurnHooks): void;
+/** 清空全部注册（测试用）。 */
+export declare function resetPackTurnHooks(): void;
+/** 全部激活包的 exec 可写根（按注册序拼接）。 */
+export declare function collectPackExecWritableRoots(chatId: string): string[];
+/** 全部激活包的 world-state 附加字段（后者覆盖同名键——包前缀命名避免碰撞）。 */
+export declare function collectPackWorldState(chatId: string): Record<string, unknown>;
+/** 全部激活包的强制技能变量（后者覆盖同名键）。 */
+export declare function collectPackForcedSkillVars(chatId: string): Record<string, string>;
+/** 回合开始：收集所有包的观察器（无注册时返回空数组，调用方零分支）。 */
+export declare function beginPackTurnObservers(ctx: {
+    chatId: string;
+    broadcast: ((channel: string, payload: unknown) => void) | undefined;
+}): PackTurnObserver[];

package/dist/local-backend/pack-turn-hooks.js

@@ -0,0 +1,67 @@
+/**
+ * 场景包的「回合级」钩子注册表（1.2 新增）。
+ *
+ * 包的路由/服务可以完全挂在注册表上，但有一类扩展发生在**每一条正在
+ * 流式的 CoreLoop 回合内部**。现存四个钩子位（以「文档预览包」为典型
+ * 用例）：
+ *
+ *  1. `execWritableRoots`：包要把产物写进每会话的工作区，该目录在项目
+ *     根之外，必须随回合的 exec 沙箱放行（写，不是只读根）；
+ *  2. `worldState`：把工作区路径喂给模型的 world-state，catalog 路径下
+ *     模型据此找到工作区；
+ *  3. `forcedSkillVars`：显式召唤包技能时把技能正文里的占位符渲染出
+ *     工作区路径；
+ *  4. `beginTurn` 返回的回合观察器：识别「本轮真的调用了包技能」
+ *     （onToolStart），在工具落定后扫描工作区并向渲染层广播产物更新
+ *     （onToolSettled）——替代前端轮询。
+ *
+ * 钩子按包注册、按回合拼装；未注册任何钩子的产品走零开销路径
+ * （空数组/undefined 合并，行为与注册前逐字节一致）。
+ */
+const hooksByPack = new Map();
+/** 注册包的回合钩子（重复注册同包后者覆盖——测试隔离靠 reset）。 */
+export function registerPackTurnHooks(packId, hooks) {
+    hooksByPack.set(packId, hooks);
+}
+/** 清空全部注册（测试用）。 */
+export function resetPackTurnHooks() {
+    hooksByPack.clear();
+}
+/** 全部激活包的 exec 可写根（按注册序拼接）。 */
+export function collectPackExecWritableRoots(chatId) {
+    const roots = [];
+    for (const hooks of hooksByPack.values()) {
+        roots.push(...(hooks.execWritableRoots?.(chatId) ?? []));
+    }
+    return roots;
+}
+/** 全部激活包的 world-state 附加字段（后者覆盖同名键——包前缀命名避免碰撞）。 */
+export function collectPackWorldState(chatId) {
+    let merged = {};
+    for (const hooks of hooksByPack.values()) {
+        const extra = hooks.worldState?.(chatId);
+        if (extra)
+            merged = { ...merged, ...extra };
+    }
+    return merged;
+}
+/** 全部激活包的强制技能变量（后者覆盖同名键）。 */
+export function collectPackForcedSkillVars(chatId) {
+    let merged = {};
+    for (const hooks of hooksByPack.values()) {
+        const extra = hooks.forcedSkillVars?.(chatId);
+        if (extra)
+            merged = { ...merged, ...extra };
+    }
+    return merged;
+}
+/** 回合开始：收集所有包的观察器（无注册时返回空数组，调用方零分支）。 */
+export function beginPackTurnObservers(ctx) {
+    const observers = [];
+    for (const hooks of hooksByPack.values()) {
+        const observer = hooks.beginTurn?.(ctx);
+        if (observer)
+            observers.push(observer);
+    }
+    return observers;
+}

package/dist/local-backend/prompt-builder.d.ts

@@ -0,0 +1,101 @@
+/**
+ * SystemPromptBuilder for the local desktop agent.
+ *
+ * Assembles a system prompt by loading skill modules from
+ * `src/local-backend/skills/<dir>/SKILL.md` and concatenating their bodies
+ * in directory-name order. Skills can be filtered by runtime conditions
+ * (e.g. `tool:<tool_name>`) and trimmed by character budget when too
+ * large (lowest-priority skills are dropped first).
+ *
+ * This is the TS counterpart of
+ * 上游 Python 服务的 SystemPromptBuilder。
+ */
+import { type SkillModule } from './skill-loader.js';
+export interface BuildPromptOptions {
+    /** Runtime conditions e.g. `tool:<tool_name>`, `has-tools`. */
+    conditions?: Iterable<string>;
+    /** Per-tool names available this turn; auto-derives `tool:<name>` conditions. */
+    toolNames?: Iterable<string>;
+    /** Optional persona preamble (`AgentProfile.role_prompt`). Rendered first. */
+    personaPreamble?: string | null;
+    /** Optional per-chat custom system prompt; rendered after persona. */
+    chatSystemPrompt?: string | null;
+    /** Optional realityCheck suffix (e.g. "本轮可用工具…"). Rendered last. */
+    realityCheckSuffix?: string;
+    /** Character budget (rough proxy for tokens). Defaults to {@link DEFAULT_CHAR_BUDGET}. */
+    charBudget?: number;
+    /** Inject `has-tools` automatically when toolNames is non-empty. Default true. */
+    autoHasTools?: boolean;
+    /**
+     * 用户通过 "/mcp__srv__tool" 显式指定的 MCP 工具。渲染为末尾指令模块，
+     * 配合首轮 tool_choice='required' 保证真的发起调用。
+     */
+    forcedMcpTool?: ForcedMcpTool;
+    /** Override skills directory (mainly for tests; bypasses built-in + user dirs). */
+    skillsDir?: string;
+    /** Ignore all loading conditions and load all skills. */
+    ignoreConditions?: boolean;
+    /** Skill names to always drop, even under `ignoreConditions`. */
+    excludeSkillNames?: Iterable<string>;
+    /**
+     * A6 分层披露:true 时只注入 eager 层技能正文;catalog 层由 sidecar 以
+     * 「目录 + skill 工具按需加载」提供。CoreLoop 路径恒为 true。
+     */
+    eagerOnly?: boolean;
+    /**
+     * 智能体勾选的技能别名（`skillIds`）。命中的技能正文无条件进系统提示词:
+     * 既绕过触发条件,也绕过 `eagerOnly` 的 catalog 层过滤。`excludeSkillNames`
+     * 仍然优先——模式级排除（plan 模式的执行类技能）不因勾选而失效。
+     */
+    pinnedSkillNames?: Iterable<string>;
+}
+export interface BuiltPrompt {
+    prompt: string;
+    modules: SkillModule[];
+    droppedModules: string[];
+    conditions: string[];
+}
+/** 显式指定的 MCP 工具（"/" 选择器 → cleanUserMessage → 此处）。 */
+export interface ForcedMcpTool {
+    /** 完整一等工具名，如 mcp__demo_local__add。 */
+    token: string;
+    toolName: string;
+    serverName: string;
+    description: string;
+    /** false = 服务未启用/未连接或工具不存在——渲染"不可用"指令而非强制调用。 */
+    available: boolean;
+}
+/**
+ * Derive condition strings from the set of tool names available this turn.
+ *
+ *   ['some_pack_tool', 'local_exec_shell']
+ *   →  ['tool:some_pack_tool', 'tool:local_exec_shell']
+ */
+export declare function conditionsFromTools(toolNames: Iterable<string>, autoHasTools?: boolean): Set<string>;
+/**
+ * Assemble the final system prompt:
+ *
+ *   [persona preamble]?       (agent role / DSL)
+ *   [chat-level prompt]?      (per-chat custom override)
+ *   [skill 1 body]
+ *   ...
+ *   [skill N body]
+ *   [reality check]?          (turn-specific tool list / pollution warning)
+ */
+export declare function buildSystemPrompt(options?: BuildPromptOptions): Promise<BuiltPrompt>;
+/**
+ * 品牌占位符变量：技能正文里的 `{agentName}` / `{brandDisplayName}` /
+ * `{brandTagline}` 渲染为当前产品注入的品牌（brand.ts；未注入 = shell
+ * 中性默认）。eager 系统提示词路径统一注入；包技能同理可用。
+ */
+export declare function brandSkillVars(): Record<string, string>;
+/** 技能正文渲染:把 `{scripts}` 及额外占位符解析为绝对路径。 */
+export declare function renderSkillContent(m: SkillModule, vars?: Record<string, string>): string;
+/** 用户显式指定技能的优先级指令头，渲染在该技能内容之前。 */
+export declare function buildForcedSkillHeader(m: SkillModule): string;
+/**
+ * "/技能名" 触发的一次性注入文本(A6):指令头 + 技能正文,由 router 并入
+ * 本轮最后一条用户消息——不再塞系统提示词尾部(系统提示词保持稳定,是
+ * prompt cache 的净收益;历史消息里也不会残留技能正文)。
+ */
+export declare function buildForcedSkillMessage(m: SkillModule, vars?: Record<string, string>): string;