u1s1-cli 1.14.6 → 1.15.1

package/dist/mcp-server.js

@@ -0,0 +1,449 @@
+/**
+ * `u1s1 mcp-server`:标准输入输出(stdio)的 MCP 工具服务,给启动器带起的官方 Claude Code / Codex
+ * 补上 Pi 里已有的三样工具:联网搜索、读取网页、生成图片。
+ *
+ * 由客户端按 MCP 配置拉起(启动器每次启动时注入,见 agents/claude.ts、agents/codex.ts),是启动器的
+ * 孙进程。它拿不到设备凭证:环境里只有
+ *   U1S1_MCP_PROXY   本机签名代理地址 http://127.0.0.1:<端口>/v1(只认回环地址)
+ *   U1S1_MCP_TOKEN   这次启动有效的本地 token(与客户端自己用的那个相同,启动器退出即作废)
+ *   U1S1_MCP_TOOLS   网关开了哪些能力(web_search、web_fetch_render、generate_image,逗号分隔)
+ * 到网关的请求全部经签名代理(代理负责 DPoP 签名、客户端证明和声明头),而且只走回环直连,
+ * 不经用户的 HTTP(S)_PROXY;读网页的直连抓取和下载生成的图片照常按用户的代理设置走(与 Pi 相同)。
+ *
+ * 工具的名字、参数、执行逻辑和报错文案直接复用 Pi 的实现(tools.ts),只有描述按站点语言重写、
+ * 生图结果的说明改成终端客户端适用的写法。
+ *
+ * 协议:手写的最小实现(不引 SDK),按 MCP 规范 2025-06-18 的 stdio 传输:每行一条 JSON-RPC 消息,
+ * stdout 只写协议消息,日志走 stderr。只提供 tools 能力。
+ */
+import { appendFileSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { Agent, getGlobalDispatcher, setGlobalDispatcher } from "undici";
+import { VERSION } from "./config.js";
+import { tr } from "./i18n.js";
+export const MCP_SERVER_NAME = "u1s1";
+export const MCP_PROXY_ENV = "U1S1_MCP_PROXY";
+export const MCP_TOKEN_ENV = "U1S1_MCP_TOKEN";
+export const MCP_TOOLS_ENV = "U1S1_MCP_TOOLS";
+/** 关闭开关:U1S1_MCP=0(或 off / false / no)时启动器不注入 MCP 服务。 */
+export const MCP_SWITCH_ENV = "U1S1_MCP";
+/** 排查用:设成一个文件路径时,服务把收发的每条协议消息和启动信息(不含 token)追加写进去。 */
+export const MCP_TRACE_ENV = "U1S1_MCP_TRACE";
+/** 启动器写进客户端环境、再由客户端转给 MCP 服务的变量(客户端配置里只引用名字,不写值)。 */
+export const MCP_ENV_NAMES = [MCP_PROXY_ENV, MCP_TOKEN_ENV, MCP_TOOLS_ENV, "U1S1_LANG"];
+/** 我们支持的协议版本,新的在前。客户端要的版本在列表里就原样回,否则回第一个(规范的版本协商)。 */
+export const MCP_PROTOCOL_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+const FALLBACK_PROTOCOL_VERSION = "2025-06-18";
+// ---------------------------------------------------------------- launcher side
+/** 用户用环境变量关掉了注入。 */
+export function mcpInjectionDisabled(env = process.env) {
+    const v = env[MCP_SWITCH_ENV]?.trim().toLowerCase();
+    return v === "0" || v === "off" || v === "false" || v === "no";
+}
+/**
+ * 网关能力 → U1S1_MCP_TOOLS。缺省值与 Pi 相同(web.ts / agents/pi.ts):搜索缺字段按开、
+ * 云端渲染和生图缺字段按关;拿不到 /v1/models 时(features 为 undefined)同样处理。
+ */
+export function mcpToolFlags(features) {
+    const flags = [];
+    if (features?.web_search !== false)
+        flags.push("web_search");
+    if (features?.web_fetch_render === true)
+        flags.push("web_fetch_render");
+    if (features?.image_gen === true)
+        flags.push("generate_image");
+    return flags.join(",");
+}
+/** 客户端拉起服务用的命令:同一个 node、同一份 CLI(dist/index.js),子命令 mcp-server。 */
+export function mcpServerCommand() {
+    return { command: process.execPath, args: [fileURLToPath(new URL("./index.js", import.meta.url)), "mcp-server"] };
+}
+export function mcpLaunchEnv(input) {
+    if (!isLoopbackProxyUrl(input.proxyBaseUrl)) {
+        throw new Error(`MCP proxy must be the local signing proxy: ${input.proxyBaseUrl}`);
+    }
+    return {
+        [MCP_PROXY_ENV]: input.proxyBaseUrl,
+        [MCP_TOKEN_ENV]: input.localToken,
+        [MCP_TOOLS_ENV]: mcpToolFlags(input.features),
+        U1S1_LANG: input.lang,
+    };
+}
+export function isLoopbackProxyUrl(url) {
+    return /^http:\/\/127\.0\.0\.1:\d{1,5}\/v1$/.test(url);
+}
+/** TypeBox 对象本身就是 JSON Schema;序列化一遍去掉它的 symbol 键,得到纯 JSON。 */
+function plainSchema(schema) {
+    return JSON.parse(JSON.stringify(schema));
+}
+function textOnly(result) {
+    return result.content
+        .filter((c) => c.type === "text" && typeof c.text === "string")
+        .map((c) => ({ type: "text", text: c.text }));
+}
+function toolDescriptions() {
+    return {
+        web_search: {
+            title: tr("联网搜索", "Web search"),
+            description: tr("联网搜索最新信息:文档、报错、版本号、近期事件等仓库里没有或可能过时的内容。返回简短答案和带链接、摘要的结果列表;" +
+                "要读全文再用 web_fetch。每次搜索按次计费(从用户的 u1s1 余额扣),优先用一个具体的查询,不要连发相近的查询。" +
+                "搜索只读查询的前 100 个字符,关键词尽量短。", "Search the web for current information: docs, error messages, latest versions, recent events, anything newer than " +
+                "your knowledge or outside the repository. Returns a short answer plus ranked results with URLs and snippets; use " +
+                "web_fetch to read a result in full. Each search is billed per query to the user's u1s1 balance, so prefer one " +
+                "focused query over several near-duplicates. Only the first 100 characters of the query are used; keep it short."),
+        },
+        web_fetch: {
+            title: tr("读取网页", "Fetch page"),
+            description: tr("读取一个网址并返回可读的正文(HTML 转成纯文本,JSON 和纯文本原样返回)。用来读 web_search 找到的页面或用户给的链接。" +
+                "先从本机直接访问(不计费);打不开或页面要靠 JavaScript 渲染时,如果服务端开了云端浏览器渲染,会自动改用它重试" +
+                "(这一次按次计费)。长页面按 30000 字符分段返回,结果末尾说被截断时,用同一个 url 和它给出的 offset 再调用一次读下一段。", "Fetch a URL and return its readable text (HTML is stripped to text; JSON and plain text are returned as-is). Use it " +
+                "to read a page found via web_search or a URL the user gave you. The page is fetched directly from this machine " +
+                "(free); if that fails or the page needs JavaScript and cloud rendering is enabled, it retries through a cloud " +
+                "browser (billed per render). Long pages come back in 30,000-character windows: when a result says it was " +
+                "truncated, call again with the same url and the offset it gives."),
+        },
+        generate_image: {
+            title: tr("生成图片", "Generate image"),
+            description: tr("根据文字描述生成图片,或在已有图片上修改、合成(images 里传本地路径或 http(s) 链接,最多 10 张)。结果保存为本地图片文件," +
+                "返回文件路径。每次调用生成一张图并按次计费(从用户的 u1s1 余额扣):先把描述写清楚,不要反复重新生成;" +
+                "报错里说图片可能已经生成、或让你不要再调用时,立即停止,不要重试。中英文描述都可以,写清主体、风格、构图、颜色和要出现的文字。", "Generate an image from a text prompt, or edit/compose existing images (pass local paths or http(s) URLs in " +
+                "`images`, up to 10). The result is saved as a local image file and its path is returned. Each call generates one " +
+                "image and is billed to the user's u1s1 balance: refine the prompt instead of regenerating repeatedly, and if an " +
+                "error says the image may already have been generated or not to call generate_image again, stop immediately and " +
+                "do not retry. Prompts work in Chinese or English; describe subject, style, composition, colors and any text to render."),
+        },
+    };
+}
+export function parseMcpToolsConfig(env) {
+    const proxy = env[MCP_PROXY_ENV]?.trim();
+    const token = env[MCP_TOKEN_ENV]?.trim();
+    const usable = !!proxy && !!token && isLoopbackProxyUrl(proxy);
+    return {
+        proxyBaseUrl: usable ? proxy : undefined,
+        localToken: usable ? token : undefined,
+        flags: new Set((env[MCP_TOOLS_ENV] ?? "").split(",").map((s) => s.trim()).filter(Boolean)),
+    };
+}
+/**
+ * 按配置建工具。执行逻辑来自 Pi 的 tools.ts(动态引入:它会带进 Pi 的模块,只在这里用)。
+ * cfg 里只有代理地址和本地 token;没有设备凭证,api.ts 会以 Bearer <本地 token> 访问代理。
+ */
+export async function buildMcpTools(config) {
+    const piTools = await import("./tools.js");
+    const text = toolDescriptions();
+    const gateway = config.proxyBaseUrl && config.localToken
+        ? { baseUrl: config.proxyBaseUrl, apiKey: config.localToken }
+        : undefined;
+    const tools = [];
+    let seq = 0;
+    const wrap = (name, tool, annotations, format = textOnly) => {
+        tools.push({
+            name,
+            ...text[name],
+            inputSchema: plainSchema(tool.parameters),
+            annotations: { title: text[name].title, ...annotations },
+            async run(args, signal) {
+                const result = await tool.execute(`mcp-${++seq}`, args, signal);
+                return { content: format(result) };
+            },
+        });
+    };
+    if (gateway && config.flags.has("web_search")) {
+        wrap("web_search", piTools.createSearchTool(gateway), {
+            readOnlyHint: true,
+            openWorldHint: true,
+        });
+    }
+    // 直连抓取不需要网关;云端渲染回退要网关开了且有代理
+    wrap("web_fetch", piTools.createFetchTool({
+        baseUrl: gateway?.baseUrl ?? "http://127.0.0.1:0/v1",
+        apiKey: gateway?.apiKey,
+        renderFallback: !!gateway && config.flags.has("web_fetch_render"),
+    }), { readOnlyHint: true, openWorldHint: true });
+    if (gateway && config.flags.has("generate_image")) {
+        wrap("generate_image", piTools.createImageTool(gateway), { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, (result) => {
+            const d = (result.details ?? {});
+            if (typeof d.path !== "string")
+                return textOnly(result);
+            const size = typeof d.size === "string" && d.size ? ` (${d.size})` : "";
+            // Pi 的文案是「已在对话中展示」;终端客户端不显示图片,改成给路径
+            return [{
+                    type: "text",
+                    text: tr(`图片已生成并保存到: ${d.path}${size}\n终端里不会直接显示图片;需要查看时告诉用户这个文件路径。不要再次调用 generate_image 来「显示」它。`, `Image generated and saved to: ${d.path}${size}\nThe terminal can't display images; give the user this file path to open it. Don't call generate_image again just to show it.`),
+                }];
+        });
+    }
+    return tools;
+}
+// ---------------------------------------------------------------- argument check
+/** 只做 inputSchema 里用到的那几种检查(必填、类型、数值范围、数组元素为字符串),出错给模型能看懂的一句话。 */
+export function checkArguments(schema, args) {
+    if (!args || typeof args !== "object" || Array.isArray(args))
+        return "arguments must be an object";
+    const value = args;
+    const props = (schema["properties"] ?? {});
+    for (const key of (schema["required"] ?? [])) {
+        if (value[key] === undefined || value[key] === null)
+            return `missing required argument: ${key}`;
+    }
+    for (const [key, v] of Object.entries(value)) {
+        const p = props[key];
+        if (!p || v === undefined || v === null)
+            continue;
+        const type = p["type"];
+        if (type === "string" && typeof v !== "string")
+            return `${key} must be a string`;
+        if (type === "number" || type === "integer") {
+            if (typeof v !== "number" || !Number.isFinite(v))
+                return `${key} must be a number`;
+            if (typeof p["minimum"] === "number" && v < p["minimum"])
+                return `${key} must be >= ${p["minimum"]}`;
+            if (typeof p["maximum"] === "number" && v > p["maximum"])
+                return `${key} must be <= ${p["maximum"]}`;
+        }
+        if (type === "array") {
+            if (!Array.isArray(v))
+                return `${key} must be an array`;
+            const items = p["items"];
+            if (items?.["type"] === "string" && v.some((x) => typeof x !== "string"))
+                return `${key} must be an array of strings`;
+        }
+    }
+    return null;
+}
+const PARSE_ERROR = -32700;
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+/**
+ * 协议核心:喂进一行,按需回一行。与传输无关,测试直接驱动它。
+ * 请求并发处理;notifications/cancelled 中止对应的 tools/call,之后不再回结果(规范要求)。
+ */
+export class McpServer {
+    options;
+    inflight = new Map();
+    toolsPromise;
+    constructor(options) {
+        this.options = options;
+    }
+    tools() {
+        const t = this.options.tools;
+        this.toolsPromise ??= Array.isArray(t) ? Promise.resolve(t) : t();
+        return this.toolsPromise;
+    }
+    reply(id, payload) {
+        this.options.send(JSON.stringify({ jsonrpc: "2.0", id, ...payload }));
+    }
+    /** 处理一行输入。返回的 Promise 在这条消息处理完(含工具执行)后落定。 */
+    async handleLine(line) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            this.reply(null, { error: { code: PARSE_ERROR, message: "Parse error" } });
+            return;
+        }
+        if (Array.isArray(parsed)) {
+            // 2025-06-18 起不再支持批量;老版本的批量逐条处理
+            await Promise.all(parsed.map((m) => this.handleMessage(m)));
+            return;
+        }
+        await this.handleMessage(parsed);
+    }
+    /** 关闭:中止所有在执行的工具调用。 */
+    abortAll() {
+        for (const c of this.inflight.values())
+            c.abort(new Error("MCP server shutting down"));
+        this.inflight.clear();
+    }
+    async handleMessage(raw) {
+        if (!raw || typeof raw !== "object") {
+            this.reply(null, { error: { code: INVALID_REQUEST, message: "Invalid Request" } });
+            return;
+        }
+        const msg = raw;
+        const isRequest = msg.id !== undefined && msg.id !== null;
+        if (typeof msg.method !== "string") {
+            // 客户端发来的响应(我们不发请求,所以不会有)或无效消息
+            if (isRequest && !("result" in msg) && !("error" in msg)) {
+                this.reply(msg.id, { error: { code: INVALID_REQUEST, message: "Invalid Request" } });
+            }
+            return;
+        }
+        if (!isRequest) {
+            this.handleNotification(msg.method, msg.params);
+            return;
+        }
+        const id = msg.id;
+        try {
+            switch (msg.method) {
+                case "initialize":
+                    this.reply(id, { result: this.initializeResult(msg.params) });
+                    return;
+                case "ping":
+                    this.reply(id, { result: {} });
+                    return;
+                case "tools/list": {
+                    const tools = await this.tools();
+                    this.reply(id, {
+                        result: {
+                            tools: tools.map((t) => ({
+                                name: t.name,
+                                title: t.title,
+                                description: t.description,
+                                inputSchema: t.inputSchema,
+                                annotations: t.annotations,
+                            })),
+                        },
+                    });
+                    return;
+                }
+                case "tools/call":
+                    await this.callTool(id, msg.params);
+                    return;
+                default:
+                    this.reply(id, { error: { code: METHOD_NOT_FOUND, message: `Method not found: ${msg.method}` } });
+            }
+        }
+        catch (e) {
+            this.options.log?.(`mcp-server: ${msg.method} failed: ${e.stack ?? String(e)}`);
+            this.reply(id, { error: { code: -32603, message: e.message || "Internal error" } });
+        }
+    }
+    handleNotification(method, params) {
+        if (method === "notifications/cancelled") {
+            const requestId = params?.requestId;
+            if (requestId === undefined)
+                return;
+            const controller = this.inflight.get(requestId);
+            if (controller) {
+                this.inflight.delete(requestId);
+                controller.abort(new Error("cancelled by client"));
+            }
+        }
+        // notifications/initialized 等其余通知:无需处理
+    }
+    initializeResult(params) {
+        const requested = params?.protocolVersion;
+        const protocolVersion = typeof requested === "string" && MCP_PROTOCOL_VERSIONS.includes(requested)
+            ? requested
+            : FALLBACK_PROTOCOL_VERSION;
+        return {
+            protocolVersion,
+            capabilities: { tools: { listChanged: false } },
+            serverInfo: { name: MCP_SERVER_NAME, title: "u1s1", version: VERSION },
+        };
+    }
+    async callTool(id, params) {
+        const p = (params ?? {});
+        const tools = await this.tools();
+        const tool = tools.find((t) => t.name === p.name);
+        if (!tool) {
+            this.reply(id, { error: { code: INVALID_PARAMS, message: `Unknown tool: ${String(p.name)}` } });
+            return;
+        }
+        const args = p.arguments ?? {};
+        const invalid = checkArguments(tool.inputSchema, args);
+        if (invalid) {
+            // 参数问题按工具执行错误回(isError),模型能看到原因并改正后重试
+            this.reply(id, { result: { content: [{ type: "text", text: `Invalid arguments for ${tool.name}: ${invalid}` }], isError: true } });
+            return;
+        }
+        const controller = new AbortController();
+        this.inflight.set(id, controller);
+        let result;
+        try {
+            result = await tool.run(args, controller.signal);
+        }
+        catch (e) {
+            result = { content: [{ type: "text", text: e?.message || String(e) }], isError: true };
+        }
+        if (controller.signal.aborted)
+            return; // 已取消:不回结果
+        this.inflight.delete(id);
+        this.reply(id, { result });
+    }
+}
+// ---------------------------------------------------------------- transport & entry
+function isLoopbackOrigin(origin) {
+    try {
+        const host = new URL(String(origin)).hostname;
+        return host === "127.0.0.1" || host === "localhost" || host === "[::1]";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 本进程的全局 dispatcher:发往回环地址(签名代理)的请求直连,其余照旧交给原来的 dispatcher
+ * (按用户的 HTTP(S)_PROXY 走)。tools.ts / api.ts 用全局 fetch,这样不用改它们。
+ */
+export function installLoopbackDirectDispatcher() {
+    const fallback = getGlobalDispatcher();
+    const direct = new Agent();
+    const routed = fallback.compose((dispatch) => (opts, handler) => isLoopbackOrigin(opts.origin) ? direct.dispatch(opts, handler) : dispatch(opts, handler));
+    setGlobalDispatcher(routed);
+}
+/** `u1s1 mcp-server` 入口:stdin 一行一条消息,stdout 只写协议消息。stdin 关闭即退出。 */
+export async function runMcpServer() {
+    // 任何模块往 stdout 打印都会弄坏协议:把 console 的 stdout 输出改到 stderr
+    const toStderr = (...args) => console.error(...args);
+    console.log = toStderr;
+    console.info = toStderr;
+    console.debug = toStderr;
+    installLoopbackDirectDispatcher();
+    if (process.stdin.isTTY) {
+        console.error(tr("u1s1 mcp-server 是给 Claude Code / Codex 用的 MCP 工具服务,由 u1s1 claude / u1s1 codex 自动配置,不用手动运行。按 Ctrl+D 退出。", "u1s1 mcp-server is the MCP tool server for Claude Code / Codex; u1s1 claude / u1s1 codex configure it automatically, so there's no need to run it by hand. Press Ctrl+D to exit."));
+    }
+    const config = parseMcpToolsConfig(process.env);
+    const tracePath = process.env[MCP_TRACE_ENV]?.trim();
+    const trace = tracePath
+        ? (dir, line) => {
+            try {
+                appendFileSync(tracePath, `${JSON.stringify({ at: new Date().toISOString(), pid: process.pid, dir, line })}\n`, { mode: 0o600 });
+            }
+            catch {
+                // 排查文件写不进去不影响服务
+            }
+        }
+        : undefined;
+    trace?.("info", JSON.stringify({
+        cwd: process.cwd(),
+        proxy: config.proxyBaseUrl ?? null,
+        token: config.localToken ? "present" : "missing",
+        flags: [...config.flags],
+        lang: process.env["U1S1_LANG"] ?? null,
+        envKeys: Object.keys(process.env).sort(),
+    }));
+    // 环境里只该有本地 token;即使有人手工设了设备凭证变量,也别留给工具代码
+    for (const key of ["U1S1_DEVICE_TOKEN", "U1S1_DEVICE_PRIVATE_JWK", "U1S1_API_KEY"])
+        delete process.env[key];
+    delete process.env[MCP_TOKEN_ENV];
+    const server = new McpServer({
+        tools: () => buildMcpTools(config),
+        send: (line) => {
+            trace?.("out", line);
+            process.stdout.write(`${line}\n`);
+        },
+        log: (line) => process.stderr.write(`${line}\n`),
+    });
+    const pending = new Set();
+    const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+    rl.on("line", (line) => {
+        trace?.("in", line);
+        const p = server.handleLine(line).catch((e) => {
+            process.stderr.write(`mcp-server: ${String(e)}\n`);
+        });
+        pending.add(p);
+        void p.finally(() => pending.delete(p));
+    });
+    await new Promise((resolve) => rl.once("close", resolve));
+    // 客户端关了输入:不再有人接结果,停掉在跑的调用
+    server.abortAll();
+    await Promise.race([Promise.allSettled(pending), new Promise((r) => setTimeout(r, 1_000).unref())]);
+}

package/dist/pi-ui-text.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Pi 内置斜杠命令的补全描述、「思考中」提示的 u1s1 文案(中英),以及把它们装进 Pi 的扩展逻辑。
+ *
+ * 以前这 26 处是改 Pi 源码的补丁(patch-pi.js 的 SLASH_COMMANDS 24 条、WORKING 2 条)。现在改用
+ * Pi 公开的扩展 API,由 agents/pi.ts 的进程内扩展(main 的 extensionFactories)调用 registerUiText:
+ * - 进程内扩展不受 --no-extensions、设置里禁用 agentDir 扩展影响,跟以前的补丁一样总是生效;
+ *   Desktop App 也不会加载它(它只读 agentDir 里的扩展文件)。
+ * - session_start 时 ctx.ui.setWorkingMessage / setHiddenThinkingLabel;/reload、换会话前 Pi 会
+ *   resetExtensionUI 清掉这些设置,随后的 session_start 再设一遍。
+ * - ctx.ui.addAutocompleteProvider 包一层补全:内置命令的描述按 U1S1_LANG 换成下表文案,并去掉 /bug。
+ *   只改补全列表;手动输入 /bug 仍由补丁 BUG_REPORT[0] 拦截。
+ *
+ * 文案必须与原补丁逐字相同(test/pi-ui-text.test.ts 对照删补丁前的快照)。上游新增或改名内置
+ * 命令时,同一测试会对照已安装 Pi 的 BUILTIN_SLASH_COMMANDS 失败,提醒补表。
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem, AutocompleteProvider } from "@earendil-works/pi-tui";
+/**
+ * 上一版(P5-B)投影到 <agentDir>/extensions 下的扩展文件名。现在改为进程内扩展,
+ * agent-setup.ts 的 removeLegacyUiTextExtension 启动时删掉这个残留文件。
+ */
+export declare const LEGACY_UI_TEXT_EXTENSION_FILE = "u1s1-ui-text.js";
+/** 描述里的应用名占位:/quit 的上游原文是 `Quit ${APP_NAME}`,运行时从现有描述里取回实际名字。 */
+export declare const APP_NAME_PLACEHOLDER = "{app}";
+export interface BuiltinCommandText {
+    name: string;
+    argumentHint?: string;
+    /** Pi 上游英文原文 */
+    upstream: string;
+    /** 中国站文案 */
+    zh?: string;
+    /** 国际站文案;不写就是上游原文 */
+    en?: string;
+    /** 从补全里去掉(/bug:诊断会上传给 Pi 上游,u1s1 用户的问题走 /feedback) */
+    hide?: true;
+}
+/** 顺序与 Pi 1.2.0 的 BUILTIN_SLASH_COMMANDS 相同。 */
+export declare const BUILTIN_COMMAND_TEXT: readonly BuiltinCommandText[];
+/** 流式回复时的工作提示(Pi 默认 "Working")。 */
+export declare const WORKING_MESSAGE: {
+    readonly zh: "思考中…";
+    readonly en: "Working";
+};
+/** 隐藏思考块时的占位标签(Pi 默认 "Thinking...")。 */
+export declare const HIDDEN_THINKING_LABEL: {
+    readonly zh: "思考中…";
+    readonly en: "Thinking...";
+};
+/** 把补全项里的内置命令描述换成当前语言的文案、去掉隐藏的命令;没有改动时返回原数组。 */
+export declare function localizeSlashItems(items: AutocompleteItem[], en: boolean): AutocompleteItem[];
+/** 包一层补全 provider:只处理「/命令名」的补全,参数补全、文件补全原样返回。 */
+export declare function wrapAutocompleteProvider(current: AutocompleteProvider): AutocompleteProvider;
+/**
+ * 注册到 Pi 扩展上:session_start 时设工作提示、隐藏思考标签,包一层补全。
+ * 只在 TUI 生效:print/json 没有界面,rpc 的 ctx.ui 这三个方法都是空实现。
+ */
+export declare function registerUiText(pi: Pick<ExtensionAPI, "on">): void;

package/dist/pi-ui-text.js

@@ -0,0 +1,148 @@
+/**
+ * Pi 内置斜杠命令的补全描述、「思考中」提示的 u1s1 文案(中英),以及把它们装进 Pi 的扩展逻辑。
+ *
+ * 以前这 26 处是改 Pi 源码的补丁(patch-pi.js 的 SLASH_COMMANDS 24 条、WORKING 2 条)。现在改用
+ * Pi 公开的扩展 API,由 agents/pi.ts 的进程内扩展(main 的 extensionFactories)调用 registerUiText:
+ * - 进程内扩展不受 --no-extensions、设置里禁用 agentDir 扩展影响,跟以前的补丁一样总是生效;
+ *   Desktop App 也不会加载它(它只读 agentDir 里的扩展文件)。
+ * - session_start 时 ctx.ui.setWorkingMessage / setHiddenThinkingLabel;/reload、换会话前 Pi 会
+ *   resetExtensionUI 清掉这些设置,随后的 session_start 再设一遍。
+ * - ctx.ui.addAutocompleteProvider 包一层补全:内置命令的描述按 U1S1_LANG 换成下表文案,并去掉 /bug。
+ *   只改补全列表;手动输入 /bug 仍由补丁 BUG_REPORT[0] 拦截。
+ *
+ * 文案必须与原补丁逐字相同(test/pi-ui-text.test.ts 对照删补丁前的快照)。上游新增或改名内置
+ * 命令时,同一测试会对照已安装 Pi 的 BUILTIN_SLASH_COMMANDS 失败,提醒补表。
+ */
+/**
+ * 上一版(P5-B)投影到 <agentDir>/extensions 下的扩展文件名。现在改为进程内扩展,
+ * agent-setup.ts 的 removeLegacyUiTextExtension 启动时删掉这个残留文件。
+ */
+export const LEGACY_UI_TEXT_EXTENSION_FILE = "u1s1-ui-text.js";
+/** 描述里的应用名占位:/quit 的上游原文是 `Quit ${APP_NAME}`,运行时从现有描述里取回实际名字。 */
+export const APP_NAME_PLACEHOLDER = "{app}";
+/** 顺序与 Pi 1.2.0 的 BUILTIN_SLASH_COMMANDS 相同。 */
+export const BUILTIN_COMMAND_TEXT = [
+    { name: "settings", upstream: "Open settings menu", zh: "打开设置菜单" },
+    { name: "model", argumentHint: "<provider/model>", upstream: "Select model (opens selector UI)", zh: "切换模型(列表里有免费/价格提示)" },
+    { name: "tree", upstream: "Navigate session tree (switch branches)", zh: "查看会话分支树,切换分支" },
+    { name: "thinking", argumentHint: "<level>", upstream: "Set thinking level", zh: "调整思考强度(想得越深越费额度)" },
+    { name: "scoped-models", upstream: "Enable/disable models for Ctrl+P cycling", zh: "设置 Ctrl+P 轮换的模型范围" },
+    { name: "export", upstream: "Export session (HTML default, or specify path: .html/.jsonl)", zh: "导出会话(默认 HTML,也可指定 .html/.jsonl 路径)" },
+    { name: "import", upstream: "Import and resume a session from a JSONL file", zh: "从 JSONL 文件导入并继续会话" },
+    { name: "share", upstream: "Share session as a secret GitHub gist", zh: "把会话分享为 GitHub 私密 gist" },
+    { name: "bug", argumentHint: "<description>", upstream: "Report a bug to the Pi developers", hide: true },
+    { name: "copy", upstream: "Copy last agent message to clipboard", zh: "复制上一条回复到剪贴板" },
+    { name: "name", upstream: "Set session display name", zh: "给当前会话起个名字" },
+    { name: "session", upstream: "Show session info and stats", zh: "查看会话信息与统计" },
+    { name: "changelog", upstream: "Show changelog entries", zh: "查看引擎更新日志(英文)" },
+    { name: "hotkeys", upstream: "Show all keyboard shortcuts", zh: "查看全部快捷键" },
+    { name: "fork", upstream: "Create a new fork from a previous user message", zh: "从之前某条消息分叉出一个新会话" },
+    { name: "clone", upstream: "Duplicate the current session at the current position", zh: "复制当前会话再继续" },
+    { name: "trust", upstream: "Save project trust decision for future sessions", zh: "记住对这个项目目录的信任选择" },
+    // /login /logout 管的是 Pi 自己的渠道登录,u1s1 账号要退出 TUI 用 u1s1 login/logout,英文也照这个意思写
+    {
+        name: "login",
+        argumentHint: "<provider>",
+        upstream: "Configure provider authentication",
+        zh: "换 u1s1 账号请先 /exit,再运行 u1s1 login",
+        en: "To switch u1s1 accounts, /exit and run u1s1 login",
+    },
+    {
+        name: "logout",
+        upstream: "Remove provider authentication",
+        zh: "退出登录请先 /exit,再运行 u1s1 logout",
+        en: "To sign out, /exit and run u1s1 logout",
+    },
+    { name: "new", upstream: "Start a new session", zh: "开始新会话" },
+    { name: "compact", upstream: "Manually compact the session context", zh: "压缩会话上下文,腾出空间继续聊" },
+    { name: "resume", upstream: "Resume a different session", zh: "恢复或切换到其他会话" },
+    { name: "reload", upstream: "Reload keybindings, extensions, skills, prompts, themes, and context files", zh: "重新加载扩展、技能、主题等资源" },
+    { name: "quit", upstream: `Quit ${APP_NAME_PLACEHOLDER}`, zh: `退出 ${APP_NAME_PLACEHOLDER}` },
+];
+/** 流式回复时的工作提示(Pi 默认 "Working")。 */
+export const WORKING_MESSAGE = { zh: "思考中…", en: "Working" };
+/** 隐藏思考块时的占位标签(Pi 默认 "Thinking...")。 */
+export const HIDDEN_THINKING_LABEL = { zh: "思考中…", en: "Thinking..." };
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** 与 pi-tui CombinedAutocompleteProvider 拼补全描述的方式相同 */
+const withHint = (hint, text) => (hint ? (text ? `${hint} — ${text}` : hint) : text);
+// 每条命令认三种现有描述:上游原文,以及旧版 u1s1 补丁打过的中文、英文(从旧版原地升级时
+// node_modules 里的 Pi 可能还带着那份补丁;上一版投影的 u1s1-ui-text.js 还在时它已先换过一遍)。
+// 都换成当前语言的文案,不叠加、不混语言。
+const RULES = new Map(BUILTIN_COMMAND_TEXT.map((c) => {
+    const en = c.en ?? c.upstream;
+    const patterns = [c.upstream, c.zh, en]
+        .filter((t) => typeof t === "string")
+        .map((t) => new RegExp(`^${escapeRe(withHint(c.argumentHint, t)).split(escapeRe(APP_NAME_PLACEHOLDER)).join("(.+)")}$`));
+    return [c.name, { argumentHint: c.argumentHint, zh: c.zh ?? en, en, hide: c.hide === true, patterns }];
+}));
+/** 把补全项里的内置命令描述换成当前语言的文案、去掉隐藏的命令;没有改动时返回原数组。 */
+export function localizeSlashItems(items, en) {
+    let changed = false;
+    const out = [];
+    for (const item of items) {
+        // 内置命令的补全项 value 与 label 都是命令名;同名的提示词模板描述不同,匹配不上,原样保留
+        const rule = item && item.label === item.value ? RULES.get(item.value) : undefined;
+        let match = null;
+        for (const re of rule?.patterns ?? []) {
+            match = re.exec(item.description ?? "");
+            if (match)
+                break;
+        }
+        if (!rule || !match) {
+            out.push(item);
+            continue;
+        }
+        changed = true;
+        if (rule.hide)
+            continue;
+        const text = (en ? rule.en : rule.zh).split(APP_NAME_PLACEHOLDER).join(match[1] ?? "");
+        out.push({ ...item, description: withHint(rule.argumentHint, text) });
+    }
+    return changed ? out : items;
+}
+/** 包一层补全 provider:只处理「/命令名」的补全,参数补全、文件补全原样返回。 */
+export function wrapAutocompleteProvider(current) {
+    return {
+        // Pi 会给最外层 provider 赋值 triggerCharacters,这里必须是可写的数据属性
+        triggerCharacters: current.triggerCharacters,
+        async getSuggestions(lines, cursorLine, cursorCol, options) {
+            const result = await current.getSuggestions(lines, cursorLine, cursorCol, options);
+            if (!result || !Array.isArray(result.items) || typeof result.prefix !== "string" || !result.prefix.startsWith("/")) {
+                return result;
+            }
+            // 语言在运行时读 U1S1_LANG(pi.ts 在加载 Pi 前写好),与原补丁的求值方式相同
+            const items = localizeSlashItems(result.items, process.env["U1S1_LANG"] === "en");
+            if (items === result.items)
+                return result;
+            return items.length > 0 ? { ...result, items } : null;
+        },
+        applyCompletion: (...args) => current.applyCompletion(...args),
+        shouldTriggerFileCompletion: current.shouldTriggerFileCompletion
+            ? (...args) => current.shouldTriggerFileCompletion(...args)
+            : undefined,
+    };
+}
+/**
+ * 注册到 Pi 扩展上:session_start 时设工作提示、隐藏思考标签,包一层补全。
+ * 只在 TUI 生效:print/json 没有界面,rpc 的 ctx.ui 这三个方法都是空实现。
+ */
+export function registerUiText(pi) {
+    pi.on("session_start", (_event, ctx) => {
+        if (ctx.mode !== "tui" || !ctx.hasUI)
+            return;
+        const en = process.env["U1S1_LANG"] === "en";
+        try {
+            ctx.ui.setWorkingMessage(en ? WORKING_MESSAGE.en : WORKING_MESSAGE.zh);
+        }
+        catch { }
+        try {
+            ctx.ui.setHiddenThinkingLabel(en ? HIDDEN_THINKING_LABEL.en : HIDDEN_THINKING_LABEL.zh);
+        }
+        catch { }
+        try {
+            ctx.ui.addAutocompleteProvider(wrapAutocompleteProvider);
+        }
+        catch { }
+    });
+}