u1s1-cli-cn 0.0.0-stage → 1.15.2

package/dist/agent-setup.js

@@ -0,0 +1,724 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { activeSite, agentDir, CUSTOM_ENDPOINTS, ENDPOINT_ID_RE, effectiveContextWindow, endpointKeyEnvName, MODELS, readCompactionBudgetSetting, PROVIDER_ID, UNKNOWN_MODEL_COST, VERSION, } from "./config.js";
+import { tr } from "./i18n.js";
+import { migrateLegacyMcpConfig } from "./mcp/config.js";
+import { LEGACY_UI_TEXT_EXTENSION_FILE } from "./pi-ui-text.js";
+/**
+ * 系统提示里的品牌人设。中国站面向编程新手、兜底语言中文(保持原文一字不差);
+ * 国际站面向开发者、兜底语言英文。按站点而不是界面语言判定,用时求值(配置可能晚于 import 才读)。
+ */
+export function brandAppend(site = activeSite()) {
+    if (site.id === "intl") {
+        return `## u1s1
+
+You are u1s1 — a plain-spoken AI coding assistant:
+- When introducing yourself or asked "who are you", say you are u1s1, never "pi"; only mention the underlying pi engine if the user explicitly asks about internals.
+- Reply in the language of the user's latest request by default. If that is ambiguous, follow the conversation language, then the UI locale when available, and otherwise use English. Never infer language from IP or location. Keep code, commands, and verbatim error messages in English.
+- Explain problems in plain, direct language and skip needless jargon; use a one-sentence analogy when helpful.
+- Before making changes, briefly state what you plan to do; afterwards summarize what changed in one or two sentences.
+- If the user's request is vague, assume the most likely intent and confirm it instead of asking a long list of questions.
+`;
+    }
+    return `## u1s1
+
+You are u1s1 — a plain-spoken AI coding buddy for programming beginners. Most users are unfamiliar with jargon:
+- When introducing yourself or asked "who are you", say you are u1s1, never "pi"; only mention the underlying pi engine if the user explicitly asks about internals.
+- Reply in the language of the user's latest request by default. If that is ambiguous, follow the conversation language, then the UI locale when available, and otherwise use Chinese. Never infer language from IP or location. Keep code, commands, and verbatim error messages in English.
+- Explain problems in plain language without jargon; use a one-sentence analogy when helpful.
+- Before making changes, briefly state what you plan to do; afterwards summarize what changed in one or two sentences.
+- If the user's request is vague, assume the most likely intent and confirm it instead of asking a long list of questions.
+`;
+}
+const EXEC_RULES = `
+## Command execution
+
+- Run any command yourself with the bash tool and show its output; never ask the user to run it manually.
+- Only hand a command to the user when it needs admin rights, interactive input (logins, installing system components), or a new terminal window — and always give the full command ready to paste.
+`;
+/**
+ * pi 的系统提示不含任何 OS/平台信息,模型只能拿 uname 之类盲探,Windows 上
+ * 第一步就撞墙。这里按 shell 体检结果告诉模型:系统是什么、命令实际跑在哪、
+ * 坏了该怎么引导用户修(而不是反复重试)。
+ */
+function envSection(shell) {
+    if (shell.status === "posix") {
+        return `\n## Environment\n\n- Operating system: ${process.platform === "darwin" ? "macOS" : "Linux"}.\n`;
+    }
+    const lines = ["", "## Environment", "", "- Operating system: Windows. Trust this section over probing; do not detect the OS with uname."];
+    switch (shell.status) {
+        case "bash":
+            lines.push(`- Commands run through bash (${shell.shellPath}); POSIX tools like ls/grep/curl are available.`, 'To inspect native Windows state or launch Windows programs, use cmd.exe /c "..." or powershell.exe -NoProfile -Command "...".', "- Work on Windows itself by default; only consider WSL when the user asks or the task truly requires Linux.");
+            break;
+        case "wsl":
+            lines.push("- Note: commands run through WSL's bash, so they execute inside a Linux distro, not on Windows itself.", "- Access Windows files via /mnt/c/... paths; invoke Windows programs by their .exe names (cmd.exe, powershell.exe).", '- When appropriate, suggest the user install Git for Windows (run winget install --id Git.Git in PowerShell) and restart u1s1 so commands run natively on Windows again.');
+            break;
+        case "none":
+            lines.push("- Critical: no usable bash exists — every bash tool call will fail immediately, and retrying is pointless.", '- Top priority is guiding the user to fix it: have them run winget install --id Git.Git in PowerShell to install Git for Windows, then restart u1s1.', "- Until then, only help the user with other tools such as file read/write.");
+            break;
+        case "unknown":
+            break;
+    }
+    return lines.join("\n") + "\n";
+}
+/** pi auto-appends <agentDir>/APPEND_SYSTEM.md to its system prompt — our branding hook. */
+export function ensureBrandPrompt(shell) {
+    mkdirSync(agentDir, { recursive: true });
+    const content = brandAppend() + envSection(shell) + EXEC_RULES;
+    const p = join(agentDir, "APPEND_SYSTEM.md");
+    if (!existsSync(p) || readFileSync(p, "utf8") !== content) {
+        writeFileSync(p, content);
+    }
+}
+/**
+ * 当前捆绑的 pi 引擎版本号。pi 的包 exports 只有 "import" 条目,
+ * require.resolve 会报 ERR_PACKAGE_PATH_NOT_EXPORTED,必须走
+ * import.meta.resolve;拿到入口文件(dist/index.js)后向上一级找包根。
+ */
+function bundledPiVersion() {
+    try {
+        const entry = fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"));
+        const pkg = JSON.parse(readFileSync(join(dirname(entry), "..", "package.json"), "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const THINKING_DEFAULTS_MARKER = "u1s1ModelThinkingDefaults";
+const CODEMODE_DEFAULT_MARKER = "u1s1CodemodeDefault";
+const LLAMA_DISABLED_MARKER = "u1s1LlamaDisabledDefault";
+const NATIVE_UI_MARKER = "u1s1NativeUiRestored";
+function recordValue(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/**
+ * Seed per-model defaults without overwriting a user's Ctrl+S choice. The
+ * marker records values managed by u1s1, so a later Gateway default can update
+ * them while a diverged user value becomes user-owned.
+ */
+export function applyModelThinkingDefaults(settings, models) {
+    const defaults = models.filter((model) => model.thinking !== undefined);
+    if (defaults.length === 0)
+        return false;
+    const levels = { ...recordValue(settings["modelThinkingLevels"]) };
+    const managed = { ...recordValue(settings[THINKING_DEFAULTS_MARKER]) };
+    let changed = false;
+    for (const model of defaults) {
+        const key = `${PROVIDER_ID}/${model.id}`;
+        const next = model.thinking.defaultLevel;
+        const current = levels[key];
+        const previousManaged = managed[key];
+        if (current === undefined || current === previousManaged) {
+            if (current !== next) {
+                levels[key] = next;
+                changed = true;
+            }
+            if (previousManaged !== next) {
+                managed[key] = next;
+                changed = true;
+            }
+        }
+        else if (previousManaged !== undefined) {
+            delete managed[key];
+            changed = true;
+        }
+    }
+    if (changed) {
+        settings["modelThinkingLevels"] = levels;
+        settings[THINKING_DEFAULTS_MARKER] = managed;
+    }
+    return changed;
+}
+/** pi 1.0 的 DEFAULT_TOOL_NAMES(未导出,测试里对过 pi 源码)。 */
+export const PI_DEFAULT_TOOL_NAMES = ["read", "bash", "edit", "write"];
+function isToolModifier(entry) {
+    return entry.startsWith("+") || entry.startsWith("-");
+}
+/** 与 pi 1.0 resolveDefaultTools 同算法:纯名字替换默认集,再按顺序应用 +name / -name。 */
+function resolveDefaultTools(entries) {
+    const plain = entries.filter((entry) => !isToolModifier(entry));
+    const tools = plain.length > 0 || entries.length === 0 ? plain : [...PI_DEFAULT_TOOL_NAMES];
+    for (const entry of entries) {
+        if (!isToolModifier(entry))
+            continue;
+        const name = entry.slice(1);
+        const index = tools.indexOf(name);
+        if (entry.startsWith("+") && index === -1 && name)
+            tools.push(name);
+        else if (entry.startsWith("-") && index !== -1)
+            tools.splice(index, 1);
+    }
+    return tools;
+}
+function stringList(value) {
+    return Array.isArray(value) ? value.filter((t) => typeof t === "string") : undefined;
+}
+/**
+ * pi 内置 codemode 默认不开,u1s1 给每个用户开一次。标记写下后不再碰:用户删掉
+ * codemode 都算用户的选择。写成完整工具名列表而不是 `+codemode`,原因见
+ * normalizeDefaultTools。
+ */
+export function applyCodemodeDefault(settings) {
+    if (settings[CODEMODE_DEFAULT_MARKER] === true)
+        return false;
+    const tools = stringList(settings["defaultTools"]);
+    if (!tools?.some((t) => t.replace(/^[+-]/, "") === "codemode")) {
+        // 没写过 defaultTools 是 pi 默认集;空列表是用户明确不开工具,两者不同
+        const current = tools === undefined ? [...PI_DEFAULT_TOOL_NAMES] : resolveDefaultTools(tools);
+        settings["defaultTools"] = [...current, "codemode"];
+    }
+    settings[CODEMODE_DEFAULT_MARKER] = true;
+    return true;
+}
+/**
+ * 每次启动把 defaultTools 里的 `+name` / `-name` 按 pi 1.0 的规则展开成完整工具名列表。
+ * Desktop App ≤0.1.23 内置的 pi 0.87.1 和 CLI 共用这份 settings.json,它不认增减写法,
+ * 会把 `["+codemode"]` 当成「只开一个叫 +codemode 的工具」,结果旧对话一个工具都没有。
+ * 展开后 pi 1.0 解析结果不变(项目级的 +/- 照样叠在上面),旧版也能读懂;
+ * 1.13.0 写下的 `["+codemode"]` 由此修复。
+ */
+export function normalizeDefaultTools(settings) {
+    const tools = stringList(settings["defaultTools"]);
+    if (!tools?.some(isToolModifier))
+        return false;
+    settings["defaultTools"] = resolveDefaultTools(tools);
+    return true;
+}
+/**
+ * pi 1.0 内置 llama.cpp 扩展(本地模型 provider + /llama),u1s1 走网关用不上,默认关一次。
+ * 用户在 extensions 里自己写过 builtin:llama.cpp 的任何开关就不动;标记写下后同样不再碰。
+ */
+export function applyLlamaDisabledDefault(settings) {
+    if (settings[LLAMA_DISABLED_MARKER] === true)
+        return false;
+    const entries = Array.isArray(settings["extensions"])
+        ? settings["extensions"].filter((e) => typeof e === "string")
+        : [];
+    if (!entries.some((e) => e.replace(/^[+!-]/, "") === "builtin:llama.cpp")) {
+        settings["extensions"] = [...entries, "-builtin:llama.cpp"];
+    }
+    settings[LLAMA_DISABLED_MARKER] = true;
+    return true;
+}
+/**
+ * 恢复 Pi 默认界面:早先版本替用户写下 hideThinkingBlock=true(隐藏思考块)和
+ * clearOnShrink=true(精简 UI 配套),并用扩展把内置工具行渲染成 0 行。现在不再覆盖,
+ * 老用户 settings.json 里残留的这两个值要清一次,否则升级后仍看不到思考块。
+ * 无法区分「u1s1 写的」和「用户后来自己选的」,所以全员只重置这一次;标记写下后
+ * 用户再在 /settings 里选的值就不会被动了。
+ */
+export function applyNativeUiRestore(settings) {
+    if (settings[NATIVE_UI_MARKER] === true)
+        return false;
+    delete settings["hideThinkingBlock"];
+    delete settings["clearOnShrink"];
+    const terminal = recordValue(settings["terminal"]);
+    if (terminal && "clearOnShrink" in terminal) {
+        delete terminal["clearOnShrink"];
+        if (Object.keys(terminal).length === 0)
+            delete settings["terminal"];
+    }
+    settings[NATIVE_UI_MARKER] = true;
+    return true;
+}
+/** Defaults that don't overwrite values the user already set. */
+export function ensureDefaultSettings(models = []) {
+    mkdirSync(agentDir, { recursive: true });
+    const p = join(agentDir, "settings.json");
+    let settings = {};
+    if (existsSync(p)) {
+        try {
+            settings = JSON.parse(readFileSync(p, "utf8"));
+        }
+        catch {
+            return;
+        }
+    }
+    let changed = false;
+    // Pi default is one-at-a-time (one queued message per turn). u1s1 delivers
+    // all queued messages together so burst typing isn't split across turns.
+    // Only fill in missing keys so an explicit /settings choice still sticks.
+    for (const key of ["steeringMode", "followUpMode"]) {
+        if (!(key in settings)) {
+            settings[key] = "all";
+            changed = true;
+        }
+    }
+    // 启动时是否显示品牌横幅(logo + 版本号/目录/提示)
+    if (!("showStartupBanner" in settings)) {
+        settings["showStartupBanner"] = true;
+        changed = true;
+    }
+    // 静默启动:不打印 [Context]/[Skills]/[Extensions] 等资源加载信息
+    if (!("quietStartup" in settings)) {
+        settings["quietStartup"] = true;
+        changed = true;
+    }
+    // 启动时自动检查并更新新版
+    if (!("autoUpdate" in settings)) {
+        settings["autoUpdate"] = true;
+        changed = true;
+    }
+    // pi 1.0 起默认全屏;u1s1 的精简 UI 与滚动习惯按常规模式调的,未选过的用户保持常规
+    if (!("tuiMode" in settings)) {
+        settings["tuiMode"] = "regular";
+        changed = true;
+    }
+    if (applyNativeUiRestore(settings))
+        changed = true;
+    if (applyCodemodeDefault(settings))
+        changed = true;
+    if (normalizeDefaultTools(settings))
+        changed = true;
+    if (applyLlamaDisabledDefault(settings))
+        changed = true;
+    if (applyModelThinkingDefaults(settings, models))
+        changed = true;
+    // ≤0.4.0 shipped branded themes and forced them as default; the files are
+    // gone now, so a settings.json still pointing at them must fall back to
+    // pi's default theme.
+    if (typeof settings.theme === "string" && settings.theme.includes("u1s1-")) {
+        delete settings.theme;
+        changed = true;
+    }
+    // 屏蔽 pi 引擎的启动更新日志(What's New):那是上游英文 changelog,且 pi 的
+    // 版本号体系(0.84.x)和 u1s1(0.19.x)完全对不上——settings 里「上次看到的
+    // 版本」一旦缺失或偏旧,升级后启动会一次性灌出几十条英文更新说明。
+    // u1s1 的版本动态走公告横幅和 u1s1 update,这里每次启动都把该记录钉死在
+    // 当前捆绑的引擎版本上,保证启动时永不弹 changelog。
+    const piVersion = bundledPiVersion();
+    if (piVersion && settings["lastChangelogVersion"] !== piVersion) {
+        settings["lastChangelogVersion"] = piVersion;
+        changed = true;
+    }
+    if (changed)
+        writeFileSync(p, JSON.stringify(settings, null, 2) + "\n");
+}
+/** ≤0.4.0 wrote u1s1-dark/u1s1-light into the pi themes dir; remove them. */
+export function cleanupBrandThemes() {
+    for (const name of ["u1s1-dark", "u1s1-light"]) {
+        rmSync(join(agentDir, "themes", `${name}.json`), { force: true });
+    }
+}
+/**
+ * u1s1 provider for SDK-based frontends (Desktop App): pi composes
+ * <agentDir>/models.json above registered providers, so this exposes the same
+ * models as the TUI's in-process extension without patching the frontend.
+ * apiKey stays an env reference — the launcher sets U1S1_API_KEY, the file
+ * itself holds no secret. Rewritten on every launch so baseUrl/model changes
+ * propagate; other providers a user may have added are preserved.
+ */
+/**
+ * 联网工具经 <agentDir>/extensions 投影:pi 的资源加载器对 TUI 和 Desktop App
+ * 都会扫描这个目录,两个前端从此共用同一份工具注册,不用各接一遍。
+ * 文件每次启动重写(baseUrl/服务端开关变化随之生效);apiKey 走 U1S1_API_KEY
+ * 环境变量,文件里不落密钥。U1S1_TOOLS_VIA_EXTENSION 守卫:旧版 CLI 仍在
+ * 进程内注册工具且不设该变量,残留的本文件在旧版下自动空转,避免双重注册。
+ */
+export function writeWebToolsExtension(cfg, features) {
+    const dir = join(agentDir, "extensions");
+    mkdirSync(dir, { recursive: true });
+    const toolsUrl = new URL("./tools.js", import.meta.url).href;
+    const searchLine = features.webSearch
+        ? `  pi.registerTool(tools.createSearchTool({ baseUrl, apiKey: process.env.U1S1_API_KEY }));\n`
+        : "";
+    const imageLine = features.imageGen
+        ? `  pi.registerTool(tools.createImageTool({ baseUrl, apiKey: process.env.U1S1_API_KEY }));\n`
+        : "";
+    // spawn_subagent 只给主会话注册;子 agent 环境里跳过,杜绝孙 agent 递归 spawn
+    const subagentBlock = `  if (process.env.U1S1_IN_SUBAGENT !== "1") {\n` +
+        `    let getParentModel = () => undefined;\n` +
+        `    pi.on("session_start", (_event, ctx) => {\n` +
+        `      const m = ctx.model;\n` +
+        `      if (m && typeof m.provider === "string" && typeof m.id === "string") {\n` +
+        `        getParentModel = () => ({ provider: m.provider, id: m.id });\n` +
+        `      }\n` +
+        `    });\n` +
+        `    pi.registerTool(tools.createSubagentTool(getParentModel));\n` +
+        `  }\n`;
+    // 密钥剥离守卫也从这里装:Desktop App 的 pi 跑在 pi-web-ui 子进程里,没有
+    // 启动器代码,只有扩展能替它把 U1S1_API_KEY / U1S1_EP_KEY_* 挡在子进程之外
+    const secretEnvUrl = new URL("./secret-env.js", import.meta.url).href;
+    // 提示文案在生成时按当前界面语言定好,扩展文件里只是字面量
+    const toolsLoadFailed = tr("联网工具本次未能加载(程序文件可能正在更新),重启 u1s1 即可恢复", "Web tools couldn't load this time (program files may be updating). Restart u1s1 to restore them.");
+    writeFileSync(join(dir, "u1s1-tools.js"), `// 由 u1s1 每次启动自动生成,请勿手改\n` +
+        `export default async function (pi) {\n` +
+        `  (await import(${JSON.stringify(secretEnvUrl)})).installChildEnvGuard();\n` +
+        `  if (process.env.U1S1_TOOLS_VIA_EXTENSION !== "1") return;\n` +
+        `  const baseUrl = process.env.U1S1_SIGNING_PROXY_URL || ${JSON.stringify(cfg.baseUrl)};\n` +
+        // 升级半途 / 权限问题导致 CLI dist 不可读时,宁可这一会话没有联网工具,
+        // 也不能让扩展加载失败刷英文堆栈(审计 B4);只在 UI 里提示一句人话
+        `  let tools;\n` +
+        `  try {\n` +
+        `    tools = await import(${JSON.stringify(toolsUrl)});\n` +
+        `  } catch {\n` +
+        `    pi.on("session_start", (_event, ctx) => {\n` +
+        `      try { if (ctx.hasUI) ctx.ui.notify(${JSON.stringify(toolsLoadFailed)}, "warning"); } catch {}\n` +
+        `    });\n` +
+        `    return;\n` +
+        `  }\n` +
+        searchLine +
+        `  pi.registerTool(tools.createFetchTool({ baseUrl, apiKey: process.env.U1S1_API_KEY, renderFallback: ${features.webFetchRender} }));\n` +
+        imageLine +
+        subagentBlock +
+        `}\n`);
+}
+/**
+ * 生成「错误信息人话化」扩展到 <agentDir>/extensions/u1s1-error-humanize.js:
+ * 把「429: {json}」形态的模型调用错误翻成中文正文 + 状态码尾巴,TUI 和
+ * Desktop App 共用(同 compact-ui 的投影机制)。实现见 error-humanize.ts,
+ * 分类兼容性(重试/配额/上下文超长)的约束也写在那里。
+ * import 失败时静默跳过——Desktop 独立运行时若指向的 CLI dist 已不存在,
+ * 宁可回到原始错误文本,也不能让扩展报错刷英文堆栈。
+ */
+export function writeErrorHumanizeExtension() {
+    const dir = join(agentDir, "extensions");
+    mkdirSync(dir, { recursive: true });
+    const url = new URL("./error-humanize.js", import.meta.url).href;
+    const traceUrl = new URL("./request-trace.js", import.meta.url).href;
+    writeFileSync(join(dir, "u1s1-error-humanize.js"), `// 由 u1s1 每次启动自动生成,请勿手改\n` +
+        `export default async function (pi) {\n` +
+        `  let humanize, extractRequestId, rememberRequestId;\n` +
+        `  try {\n` +
+        `    ({ humanizeModelError: humanize, extractRequestId } = await import(${JSON.stringify(url)}));\n` +
+        `    ({ rememberRequestId } = await import(${JSON.stringify(traceUrl)}));\n` +
+        `  } catch {\n` +
+        `    return;\n` +
+        `  }\n` +
+        `  pi.on("message_end", (event) => {\n` +
+        `    const msg = event.message;\n` +
+        `    if (msg.role !== "assistant" || msg.stopReason !== "error" || !msg.errorMessage) return;\n` +
+        `    // 记下最近一次报错的请求编号,u1s1 feedback / /feedback 建工单时附上\n` +
+        `    rememberRequestId(extractRequestId(msg.errorMessage));\n` +
+        `    const friendly = humanize(msg.errorMessage);\n` +
+        `    if (!friendly) return;\n` +
+        `    return { message: { ...msg, errorMessage: friendly } };\n` +
+        `  });\n` +
+        `}\n`);
+}
+/**
+ * 生成「会话内公告触达」扩展到 <agentDir>/extensions/u1s1-announcements.js:
+ * 启动横幅只渲染一次公告,维护窗口里挂着会话的用户只会撞裸错误(审计 F14)。
+ * 轮询逻辑在 announcements-poll.ts(5 分钟一次、首拉只建基线不打扰);
+ * 公告变化时 appendEntry 进会话 + 尽力弹 notify。TUI 和 Desktop App 共用。
+ * print/json 一次性模式不起轮询;import 失败静默跳过(同 error-humanize)。
+ */
+export function writeAnnouncementsExtension() {
+    const dir = join(agentDir, "extensions");
+    mkdirSync(dir, { recursive: true });
+    const url = new URL("./announcements-poll.js", import.meta.url).href;
+    writeFileSync(join(dir, "u1s1-announcements.js"), `// 由 u1s1 每次启动自动生成,请勿手改\n` +
+        `export default async function (pi) {\n` +
+        `  let startAnnouncementPoll;\n` +
+        `  try {\n` +
+        `    startAnnouncementPoll = (await import(${JSON.stringify(url)})).startAnnouncementPoll;\n` +
+        `  } catch {\n` +
+        `    return;\n` +
+        `  }\n` +
+        `  let Text;\n` +
+        `  try {\n` +
+        `    Text = (await import("@earendil-works/pi-tui")).Text;\n` +
+        `  } catch {\n` +
+        `    return;\n` +
+        `  }\n` +
+        `  pi.registerEntryRenderer("u1s1-announcement", (entry, _opts, theme) => {\n` +
+        `    const d = entry.data ?? {};\n` +
+        `    let text = theme.fg("text", theme.bold("📢 " + String(d.text ?? "")));\n` +
+        `    if (d.url) text += "\\n" + theme.fg("dim", String(d.url));\n` +
+        `    return new Text(text, 1, 0);\n` +
+        `  });\n` +
+        `  let ui;\n` +
+        `  let started = false;\n` +
+        `  pi.on("session_start", (_event, ctx) => {\n` +
+        `    if (ctx.hasUI) ui = ctx.ui;\n` +
+        `    if (started || ctx.mode === "print" || ctx.mode === "json") return;\n` +
+        `    started = true;\n` +
+        `    startAnnouncementPoll({\n` +
+        `      onNew: (a) => {\n` +
+        `        pi.appendEntry("u1s1-announcement", { text: a.text, url: a.url });\n` +
+        `        try {\n` +
+        `          ui?.notify("📢 " + a.text, "info");\n` +
+        `        } catch {}\n` +
+        `      },\n` +
+        `    });\n` +
+        `  });\n` +
+        `}\n`);
+}
+/**
+ * 生成「自定义 MCP 服务」扩展到 <agentDir>/extensions/u1s1-mcp.js,只给没有内置 MCP 的
+ * 旧引擎用(Desktop App 的 pi-web-ui 还是 0.83):读 agent/mcp.json,把工具注册成
+ * mcp_<服务>_<工具>,逻辑在 mcp/extension.ts。pi ≥0.99 有 pi.registerMcpServer,说明内置
+ * MCP 会读同一份配置,扩展直接让位。投影前先把 ≤1.12 的 ~/.u1s1/mcp.json 迁过去。
+ * 子会话(spawn_subagent)里不挂 MCP 工具:避免每个子进程都拉起一份服务。
+ */
+export function writeMcpExtension() {
+    try {
+        migrateLegacyMcpConfig();
+    }
+    catch {
+        // 迁移失败不挡启动:旧文件还在,下次再试
+    }
+    const dir = join(agentDir, "extensions");
+    mkdirSync(dir, { recursive: true });
+    const url = new URL("./mcp/extension.js", import.meta.url).href;
+    const mcpLoadFailed = tr("MCP 服务加载失败:", "Failed to load MCP servers: ");
+    writeFileSync(join(dir, "u1s1-mcp.js"), `// 由 u1s1 每次启动自动生成,请勿手改\n` +
+        `export default async function (pi) {\n` +
+        `  if (process.env.U1S1_IN_SUBAGENT === "1") return;\n` +
+        `  if (typeof pi.registerMcpServer === "function") return;\n` +
+        `  let registerMcpServers;\n` +
+        `  try {\n` +
+        `    registerMcpServers = (await import(${JSON.stringify(url)})).registerMcpServers;\n` +
+        `  } catch {\n` +
+        `    return;\n` +
+        `  }\n` +
+        `  try {\n` +
+        `    await registerMcpServers(pi);\n` +
+        `  } catch (err) {\n` +
+        `    const msg = err instanceof Error ? err.message : String(err);\n` +
+        `    pi.on("session_start", (_event, ctx) => {\n` +
+        `      if (ctx.hasUI) ctx.ui.notify(${JSON.stringify(mcpLoadFailed)} + msg, "warning");\n` +
+        `    });\n` +
+        `  }\n` +
+        `}\n`);
+}
+/**
+ * 生成「OpenRouter 应用归因」扩展到 <agentDir>/extensions/u1s1-attribution.js。
+ * 用户自己配 OPENROUTER_API_KEY 直连时，pi 内置的归因头归到 pi.dev 名下（且受遥测
+ * 开关控制）；这里用 before_provider_headers 钩子覆盖为 u1s1，让这部分流量也计入
+ * u1s1 的 OpenRouter 公开排行与数据分析（openrouter.ai/docs/app-attribution）。
+ * 只在请求目标确认为 OpenRouter 时才改头，其它供应商不加多余头。
+ */
+export function writeAttributionExtension(site = activeSite()) {
+    const dir = join(agentDir, "extensions");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "u1s1-attribution.js"), `// 由 u1s1 每次启动自动生成，请勿手改\n` +
+        `export default async function (pi) {\n` +
+        `  pi.on("before_provider_headers", (event, ctx) => {\n` +
+        `    const m = ctx.model;\n` +
+        `    if (!m || !(m.provider === "openrouter" || String(m.baseUrl ?? "").includes("openrouter.ai"))) return;\n` +
+        `    event.headers["HTTP-Referer"] = ${JSON.stringify(site.origin)};\n` +
+        `    event.headers["X-OpenRouter-Title"] = "u1s1";\n` +
+        `    event.headers["X-OpenRouter-Categories"] = "cli-agent";\n` +
+        `  });\n` +
+        `}\n`);
+}
+/**
+ * 「精简 UI」扩展(u1s1-compact-ui.js)已下线:界面回到 Pi 默认——内置工具调用、思考块都按原样显示。
+ * 旧版本每次启动都把它写进 <agentDir>/extensions,Pi 会照单加载并继续隐藏工具行,
+ * 所以启动时要把残留文件删掉(Desktop App 共用同一个 agentDir,同样受益)。
+ */
+export function removeLegacyCompactUiExtension(outputDir) {
+    const dir = outputDir ?? join(agentDir, "extensions");
+    try {
+        rmSync(join(dir, "u1s1-compact-ui.js"), { force: true });
+    }
+    catch { }
+}
+/**
+ * 「界面文案」(斜杠命令补全描述、思考中提示)上一版投影成 <agentDir>/extensions/u1s1-ui-text.js,
+ * 用户带 --no-extensions 或在设置里禁用它时就失效;现在改由 pi.ts 的进程内扩展调用
+ * pi-ui-text.ts 的 registerUiText。启动时删掉残留文件,免得和进程内扩展各包一层
+ * (两层同时生效结果也正确,只是多余);Desktop App 共用 agentDir,它那里本来就是空转。
+ */
+export function removeLegacyUiTextExtension(outputDir) {
+    const dir = outputDir ?? join(agentDir, "extensions");
+    try {
+        rmSync(join(dir, LEGACY_UI_TEXT_EXTENSION_FILE), { force: true });
+    }
+    catch { }
+}
+/**
+ * pi-web-ui 的就绪检测只认 <agentDir>/auth.json 里有没有凭据条目(models.json
+ * 的 apiKey 它不看),空 {} 会在网页里弹「未检测到 pi agent 配置」引导装 pi。
+ * 这里补一条 u1s1 的 api_key 记录 —— key 用 $U1S1_API_KEY 环境变量引用,
+ * pi 的 resolveConfigValue 读取时才解析,文件本身不落密钥,和 models.json 同款。
+ * 其他 provider 的凭据原样保留;文件损坏时不动它,交给 SDK 自己报错。
+ */
+export function ensureAuthCredential() {
+    mkdirSync(agentDir, { recursive: true });
+    const p = join(agentDir, "auth.json");
+    let root = {};
+    if (existsSync(p)) {
+        try {
+            root = JSON.parse(readFileSync(p, "utf8"));
+        }
+        catch {
+            return;
+        }
+        if (typeof root !== "object" || root === null || Array.isArray(root))
+            return;
+    }
+    const entry = root[PROVIDER_ID];
+    if (entry?.["type"] === "api_key" && entry["key"] === "$U1S1_API_KEY")
+        return;
+    root[PROVIDER_ID] = { type: "api_key", key: "$U1S1_API_KEY" };
+    writeFileSync(p, JSON.stringify(root, null, 2) + "\n", { mode: 0o600 });
+}
+/**
+ * pi provider 条目里的模型形状(models.json 与 registerProvider 共用)。
+ * contextWindow 不是模型真实窗口而是自动压缩预算(见 effectiveContextWindow):
+ * options.maxContextTokens 显式传 undefined 表示「用户没设」(测试用),不传则读 settings.json。
+ */
+export function toProviderModels(models, options = { maxContextTokens: readCompactionBudgetSetting() }) {
+    return models.map((m) => {
+        let thinkingLevelMap;
+        let compat;
+        if (m.thinking) {
+            const supported = new Set(m.thinking.levels);
+            thinkingLevelMap = {};
+            for (const level of ["off", "minimal", "low", "medium", "high", "xhigh", "max"]) {
+                thinkingLevelMap[level] = supported.has(level) ? (m.thinking.levelMap[level] ?? level) : null;
+            }
+            compat = {
+                supportsReasoningEffort: true,
+                thinkingFormat: m.thinking.requestFormat,
+                ...(m.thinking.requestFormat === "deepseek"
+                    ? {
+                        supportsStore: false,
+                        supportsDeveloperRole: false,
+                        maxTokensField: "max_tokens",
+                        requiresReasoningContentOnAssistantMessages: true,
+                    }
+                    : {}),
+            };
+        }
+        return {
+            id: m.id,
+            // 选择器只渲染 name 一行,把「免费/几倍」提示拼进去,切模型前就能看到
+            name: m.note ? `${m.name} · ${m.note}` : m.name,
+            reasoning: m.reasoning,
+            thinkingLevelMap,
+            input: m.vision ? ["text", "image"] : ["text"],
+            cost: m.cost ?? UNKNOWN_MODEL_COST,
+            contextWindow: effectiveContextWindow(m, options.maxContextTokens),
+            maxTokens: m.maxTokens,
+            compat,
+        };
+    });
+}
+/**
+ * 自定义端点 → pi provider 条目。密钥走环境变量引用(启动器已 set,见
+ * endpointKeyEnv),文件里不落明文;没配密钥的端点(本机 Ollama 等)写
+ * 字面量 "local" —— pi 没有凭据会直接拒启("No API key found"),
+ * 这是 pi 自带 llama provider 的同款兜底,本地服务会忽略 Authorization 头。
+ */
+export function endpointProviderEntry(ep, options = {}) {
+    // 进程内 registerProvider 可以直接给字面量(不落文件);写 models.json 时仍走 $VAR 引用
+    const envRef = `$${endpointKeyEnvName(ep.id)}`;
+    return {
+        name: ep.name,
+        baseUrl: ep.baseUrl,
+        api: ep.api,
+        apiKey: ep.apiKey ? (options.literalKey ? ep.apiKey : envRef) : "local",
+        models: toProviderModels(ep.models),
+    };
+}
+/** run_workflow 已下线:清掉旧版本每次启动写入的 /workflow 提示词模板,免得它引导模型调用不存在的工具。 */
+export function removeLegacyWorkflowPromptTemplate() {
+    try {
+        rmSync(join(agentDir, "prompts", "workflow.md"), { force: true });
+    }
+    catch { }
+}
+/**
+ * pi 会把环境里的厂商密钥(ANTHROPIC_API_KEY 等)当作「已配置的 provider」,
+ * /model 里冒出一大串没在用的模型(u1s1 又拦了 /login,配了也没法管理)。
+ * u1s1 的口径是:官方模型 + 自定义端点,所以启动 pi 前把这批**纯 LLM 厂商**
+ * 密钥从 pi 进程环境里剔掉。名单来自 pi-ai env-api-keys.ts;刻意保留
+ * AWS_WEB_IDENTITY_TOKEN_FILE / HF_TOKEN / GOOGLE_CLOUD_API_KEY /
+ * CLOUDFLARE_API_KEY 这类通用凭据 —— agent 终端里的其他工具还要用。
+ * 注意 agent 的 Bash 子进程也继承不到被剔的变量;项目 .env 文件不受影响。
+ */
+const FOREIGN_PROVIDER_ENV_KEYS = [
+    "AI_GATEWAY_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+    "ANTHROPIC_OAUTH_TOKEN",
+    "ANT_LING_API_KEY",
+    "AWS_BEARER_TOKEN_BEDROCK",
+    "AZURE_OPENAI_API_KEY",
+    "BASETEN_API_KEY",
+    "CEREBRAS_API_KEY",
+    "COPILOT_GITHUB_TOKEN",
+    "DEEPSEEK_API_KEY",
+    "FIREWORKS_API_KEY",
+    "GEMINI_API_KEY",
+    "GROQ_API_KEY",
+    "KIMI_API_KEY",
+    "MINIMAX_API_KEY",
+    "MINIMAX_CN_API_KEY",
+    "MISTRAL_API_KEY",
+    "MOONSHOT_API_KEY",
+    "NVIDIA_API_KEY",
+    "OPENAI_API_KEY",
+    "OPENCODE_API_KEY",
+    "OPENROUTER_API_KEY",
+    "QWEN_TOKEN_PLAN_API_KEY",
+    "QWEN_TOKEN_PLAN_CN_API_KEY",
+    "RADIUS_API_KEY",
+    "TOGETHER_API_KEY",
+    "XAI_API_KEY",
+    "XIAOMI_API_KEY",
+    "XIAOMI_TOKEN_PLAN_AMS_API_KEY",
+    "XIAOMI_TOKEN_PLAN_CN_API_KEY",
+    "XIAOMI_TOKEN_PLAN_SGP_API_KEY",
+    "ZAI_API_KEY",
+    "ZAI_CODING_CN_API_KEY",
+];
+export function scrubForeignProviderEnv() {
+    for (const key of FOREIGN_PROVIDER_ENV_KEYS) {
+        delete process.env[key];
+    }
+}
+/** 把各端点密钥放进环境(TUI 直接 process.env;web 传给子进程)。 */
+export function endpointKeyEnv() {
+    const env = {};
+    for (const ep of CUSTOM_ENDPOINTS) {
+        if (ep.apiKey)
+            env[endpointKeyEnvName(ep.id)] = ep.apiKey;
+    }
+    return env;
+}
+export function ensureProviderModels(cfg, options = {}) {
+    const outputPath = options.outputPath ?? join(agentDir, "models.json");
+    const sourcePath = options.sourcePath ?? outputPath;
+    mkdirSync(dirname(outputPath), { recursive: true });
+    let root = {};
+    if (existsSync(sourcePath)) {
+        try {
+            root = JSON.parse(readFileSync(sourcePath, "utf8"));
+        }
+        catch {
+            root = {};
+        }
+    }
+    const providers = typeof root["providers"] === "object" && root["providers"] !== null
+        ? root["providers"]
+        : {};
+    providers[PROVIDER_ID] = {
+        name: "u1s1",
+        baseUrl: cfg.baseUrl,
+        api: "openai-completions",
+        apiKey: "$U1S1_API_KEY",
+        // 网关按这个头识别客户端版本;不带头的旧版会在会话首轮被追加升级提示
+        headers: { "x-u1s1-version": VERSION },
+        models: toProviderModels(MODELS),
+    };
+    // 自定义端点:先清掉我们此前写入、如今已删除的条目(键形状 ep+32hex,
+    // 用户手工加的其他 provider 不受影响),再写当前列表
+    for (const key of Object.keys(providers)) {
+        if (ENDPOINT_ID_RE.test(key) && !CUSTOM_ENDPOINTS.some((e) => e.id === key)) {
+            delete providers[key];
+        }
+    }
+    for (const ep of CUSTOM_ENDPOINTS) {
+        providers[ep.id] = endpointProviderEntry(ep);
+    }
+    root["providers"] = providers;
+    writeFileSync(outputPath, JSON.stringify(root, null, 2) + "\n", { mode: 0o600 });
+}