@xiaobuyu/nodesign 0.0.1

package/server/runtime/capabilities.js

@@ -0,0 +1,153 @@
+/**
+ * server/runtime/capabilities.js — 本机能力位：外部二进制 / 外部服务钥匙 / 本地产线，启动时探一遍，
+ * 工具注册与界面都问它（一份表，两个读者）。
+ *
+ * 为什么需要它（08-22 盘点）：仓库里同一件事有三种写法——ffmpeg 有 hasFfmpeg() 探针并降级、rembg 有
+ * isAvailable() 返回可操作的装法、playwright 20 个调用点里只有 2 个接住了「Executable doesn't exist」，
+ * 其余是 500 或一条裸的工具错误。本地分发版装在别人的机器上，缺依赖是常态不是事故：
+ *   - 工具层：engine/mcp/capability-gate.js 按这里的结果给工具描述加「⛔ 不可用 + 装法」、调用期直接拦
+ *   - 界面层：GET /api/local/status 带 capabilities，配置页画成一张表
+ *   - 日志层：platform.dump 之后打一行汇总
+ *
+ * 探测只在启动做一次（二进制装好了要重启；配置页的「重启」按钮就是干这个的）。
+ * 探不到 ≠ 不存在：whichBinary 按 PATH + 几个已知安装位置找，找不到就如实说 detail，别替用户猜。
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { isAvailable as rembgAvailable, REMBG_SETUP_HINT } from '../engine/mcp/tools/helpers/rembg.js';
+
+const isWin = process.platform === 'win32';
+
+/** 跨平台 which：PATH（Windows 连 PATHEXT）+ 调用方给的额外目录。找不到返回 null */
+export function whichBinary(name, extraDirs = []) {
+  if (!name) return null;
+  if (path.isAbsolute(name)) return fs.existsSync(name) ? name : null;
+  const dirs = [...(process.env.PATH || '').split(path.delimiter).filter(Boolean), ...extraDirs];
+  const exts = isWin ? (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';').map((e) => e.toLowerCase()) : [''];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, isWin && !name.toLowerCase().endsWith(ext) ? name + ext : name);
+      try {
+        const st = fs.statSync(candidate);
+        if (st.isFile()) return candidate;
+      } catch { /* 下一个 */ }
+    }
+  }
+  return null;
+}
+
+const home = os.homedir();
+const LO_DIRS = isWin
+  ? ['C:\\Program Files\\LibreOffice\\program', 'C:\\Program Files (x86)\\LibreOffice\\program']
+  : process.platform === 'darwin'
+    ? ['/Applications/LibreOffice.app/Contents/MacOS', path.join(home, 'Applications/LibreOffice.app/Contents/MacOS')]
+    : ['/usr/lib/libreoffice/program', '/opt/libreoffice/program', '/snap/bin'];
+const BREW_DIRS = process.platform === 'darwin' ? ['/opt/homebrew/bin', '/usr/local/bin'] : [];
+
+/**
+ * 能力表。kind：binary | key | service。level：'required'（没有就跑不起来）| 'feature'（少一块功能）。
+ * fix 写给人看：装法一句话。probe 返回 { available, detail, path? }。
+ */
+export const CAPABILITY_DEFS = Object.freeze([
+  { id: 'git', kind: 'binary', level: 'required', label: 'git', uses: '项目工作区的版本历史（建项目就要用）',
+    fix: isWin ? '装 Git for Windows（git-scm.com），装完重开终端' : 'apt/brew install git',
+    probe: () => bin('git') },
+  { id: 'chromium', kind: 'binary', level: 'feature', label: 'Chromium（playwright）', uses: '截图自检 / 页面感知 / 浏览器工具 / PDF·PPTX 导出 / 封面',
+    fix: 'npx playwright install chromium',
+    probe: async () => {
+      let pw;
+      try { pw = await import('playwright'); } catch (err) { return { available: false, detail: `playwright 包加载失败：${err.message}` }; }
+      let p = null;
+      try { p = pw.chromium.executablePath(); } catch (err) { return { available: false, detail: `executablePath: ${err.message}` }; }
+      return p && fs.existsSync(p) ? { available: true, detail: p, path: p } : { available: false, detail: `浏览器未下载（期望在 ${p || '?'}）` };
+    } },
+  { id: 'libreoffice', kind: 'binary', level: 'feature', label: 'LibreOffice（soffice）', uses: 'Word/docx 形态：渲页图、缩略图、导出 PDF、build_docx 的页图体检',
+    fix: isWin ? '官网装 LibreOffice（默认装到 C:\\Program Files\\LibreOffice）' : process.platform === 'darwin' ? 'brew install --cask libreoffice' : 'apt install libreoffice',
+    probe: () => bin('soffice', LO_DIRS) },
+  { id: 'poppler', kind: 'binary', level: 'feature', label: 'poppler（pdftoppm）', uses: 'docx 页图（PDF → PNG）',
+    fix: isWin ? '装 poppler for Windows 并把 bin 目录加进 PATH' : process.platform === 'darwin' ? 'brew install poppler' : 'apt install poppler-utils',
+    probe: () => bin('pdftoppm', BREW_DIRS) },
+  { id: 'ffmpeg', kind: 'binary', level: 'feature', label: 'ffmpeg', uses: '视频转码（没有就发原片）',
+    fix: isWin ? '装 ffmpeg 并加进 PATH' : process.platform === 'darwin' ? 'brew install ffmpeg' : 'apt install ffmpeg',
+    probe: () => bin('ffmpeg', BREW_DIRS) },
+  { id: 'rembg', kind: 'service', level: 'feature', label: 'rembg 抠图环境', uses: 'remove_background',
+    fix: `${REMBG_SETUP_HINT}（见 server/services/rembg-launcher.js）`,
+    probe: async () => { const r = await rembgAvailable(); return { available: r.available, detail: r.available ? `mode=${r.mode}` : r.reason }; } },
+  { id: 'imageGen', kind: 'service', level: 'feature', label: '生图通道', uses: 'generate_image',
+    fix: '默认走 codex CLI：npm i -g @openai/codex && codex login；或 NODESIGN_IMAGE_PROVIDER=gateway + NODESIGN_GATEWAY_KEY',
+    probe: () => {
+      const provider = (process.env.NODESIGN_IMAGE_PROVIDER || 'codex').toLowerCase();
+      if (provider === 'gateway') return { available: !!process.env.NODESIGN_GATEWAY_KEY, detail: process.env.NODESIGN_GATEWAY_KEY ? 'gateway（NODESIGN_GATEWAY_KEY 已配）' : 'NODESIGN_GATEWAY_KEY 为空' };
+      const r = bin(process.env.NODESIGN_CODEX_BIN || 'codex');
+      return { ...r, detail: r.available ? `codex：${r.detail}（是否已 codex login 这里探不到）` : `codex CLI 不在 PATH（${r.detail}）` };
+    } },
+  { id: 'webSearch', kind: 'key', level: 'feature', label: '联网搜索钥匙', uses: 'web_search',
+    fix: '.env 里配 NODESIGN_TAVILY_KEY / NODESIGN_EXA_KEY / NODESIGN_BAIDU_QIANFAN_KEY / NODESIGN_ZHIPU_KEY 任一',
+    probe: () => anyEnv(['NODESIGN_TAVILY_KEY', 'NODESIGN_EXA_KEY', 'NODESIGN_BAIDU_QIANFAN_KEY', 'NODESIGN_ZHIPU_KEY']) },
+  { id: 'publish', kind: 'key', level: 'feature', label: 'Cloudflare Pages 发布', uses: 'publish_site（一键上线四级域名）',
+    fix: '.env 里配 CLOUDFLARE_API_TOKEN + NODESIGN_PUBLISH_DOMAIN（+ NODESIGN_CF_ACCOUNT_ID），并装 wrangler（npm i -g wrangler）',
+    probe: () => {
+      const missing = ['CLOUDFLARE_API_TOKEN', 'NODESIGN_PUBLISH_DOMAIN'].filter((k) => !process.env[k]);
+      if (missing.length) return { available: false, detail: `${missing.join(', ')} 为空` };
+      const w = bin('wrangler', [path.dirname(process.execPath)]);
+      return w.available ? { available: true, detail: `wrangler：${w.detail}`, path: w.path } : { available: false, detail: 'wrangler 不在 PATH 也不在 node 同目录' };
+    } },
+  { id: 'localBox', kind: 'service', level: 'feature', label: '本地 GPU 盒子（paint_still / roll_film）', uses: '自部署生图 / 文生视频',
+    fix: 'NODESIGN_LOCAL_BOX=on + NODESIGN_H3BOX_SSH（站主自己的 5090 盒子；一般用户用不上）',
+    probe: () => (process.env.NODESIGN_LOCAL_BOX === 'on' && process.env.NODESIGN_H3BOX_SSH
+      ? { available: true, detail: process.env.NODESIGN_H3BOX_SSH } : { available: false, detail: process.env.NODESIGN_LOCAL_BOX === 'on' ? 'NODESIGN_H3BOX_SSH 为空' : 'NODESIGN_LOCAL_BOX 未开' }) },
+]);
+
+function bin(name, extra = []) {
+  const p = whichBinary(name, extra);
+  return p ? { available: true, detail: p, path: p } : { available: false, detail: `${name} 不在 PATH${extra.length ? '（也不在常见安装位置）' : ''}` };
+}
+function anyEnv(names) {
+  const hit = names.find((n) => !!process.env[n]);
+  return hit ? { available: true, detail: `${hit} 已配` } : { available: false, detail: `${names.join(' / ')} 都为空` };
+}
+
+/** id → { id, kind, level, label, uses, fix, available, detail, path? }。probeCapabilities 之前是空的 */
+const state = new Map();
+let probed = null;
+
+export async function probeCapabilities({ force = false } = {}) {
+  if (probed && !force) return probed;
+  probed = (async () => {
+    for (const def of CAPABILITY_DEFS) {
+      let r;
+      try { r = await def.probe(); } catch (err) { r = { available: false, detail: `探测出错：${err.message}` }; }
+      const { probe: _p, ...meta } = def;
+      state.set(def.id, Object.freeze({ ...meta, available: !!r.available, detail: r.detail || '', ...(r.path ? { path: r.path } : {}) }));
+    }
+    return capabilitySnapshot();
+  })();
+  return probed;
+}
+
+export function capabilitySnapshot() {
+  return CAPABILITY_DEFS.map((d) => state.get(d.id)).filter(Boolean);
+}
+
+/** 没探过（单测 / 脚本直接 import 工具）→ null，调用方当「不知道」= 不拦 */
+export function capabilityState(id) {
+  return state.get(id) || null;
+}
+
+/** 给 spawn 用的可执行路径：探到了就用绝对路径（Mac/Win 的 LibreOffice 不在 PATH），没探或没探到就原名（让 ENOENT 原样报） */
+export function resolveBinary(capId, fallbackName) {
+  const s = state.get(capId);
+  return s?.available && s.path ? s.path : fallbackName;
+}
+
+/** 启动日志一行汇总 */
+export function summarizeCapabilities() {
+  const snap = capabilitySnapshot();
+  const ok = snap.filter((c) => c.available).map((c) => c.id);
+  const missing = snap.filter((c) => !c.available);
+  const lines = [`[capabilities] 可用 ${ok.length}/${snap.length}：${ok.join(' ') || '(无)'}`];
+  for (const c of missing) lines.push(`  ${c.level === 'required' ? '⛔' : '○'} ${c.id}（${c.label}）：${c.detail} → ${c.fix}`);
+  return lines.join('\n');
+}

package/server/runtime/local-config.js

@@ -0,0 +1,177 @@
+/**
+ * server/runtime/local-config.js — 用户自己的模型插槽（本地分发版）。
+ *
+ * 文件：<dataRoot>/config.json（local profile；hosted 下不读，除非 NODESIGN_MODELS_CONFIG 指了路径——给测试用）。
+ * 形状故意跟 model-table.js 的内置行**同一套字段名**：一个事实一种写法，配置页的表单、内置表的注释、
+ * 这里的 schema 三处说的是同一个东西。
+ *
+ *   {
+ *     "upstreams": {
+ *       "myrelay": { "label": "我的中转站", "baseUrl": "https://api.example.com", "protocol": "anthropic" | "openai-chat",
+ *                    "authStyle": "x-api-key" | "bearer" | "none", "key": "sk-..."（或 "keyEnv": "MY_KEY"）, "countTokens": false }
+ *     },
+ *     "models": [
+ *       { "id": "kimi-k2", "label": "Kimi K2", "desc": "…", "window": 262144, "upstream": "myrelay", "wireModel": "kimi-k2-0905",
+ *         "thinking": "strip", "reasoningEffort": "high", "maxOutput": 32000, "prices": { "input": 0.6, "output": 2.5 },
+ *         "emptyRetries": 2, "retryBudgetMs": 120000, "fastModel": "kimi-k2", "brand": "custom" }
+ *     ]
+ *   }
+ *
+ * 分级校验（用户拍板「断言降级」）：内置表的错仍然在 model-context.js 加载时炸；外部行的错**不炸进程**，
+ * 整条丢掉并把原因收进 errors（启动日志 + GET /api/local/config 都能看到），别的行照常可用。
+ * 配置页保存时走同一个 validate，所以用户看到的红字和启动时日志里的是同一句话。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { profile } from './profile.js';
+import { BRANDS, UPSTREAMS_BUILTIN, MODELS_BUILTIN } from '../engine/agent/model-table.js';
+
+export const PROTOCOLS = Object.freeze(['anthropic', 'openai-chat']);
+export const AUTH_STYLES = Object.freeze(['x-api-key', 'bearer', 'none']);
+export const THINKING_MODES = Object.freeze(['strip', 'enabled8k', 'passthrough']);
+export const REASONING_EFFORTS = Object.freeze(['low', 'medium', 'high', 'max']);
+/** 预算上限：CLI 流式请求总超时 600s − 单发最长挂起 185s（upstream-truncation.test.js 钉的同一条线），留余量取 400s */
+export const MAX_RETRY_BUDGET_MS = 400_000;
+
+const ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+const RESERVED_UPSTREAMS = new Set(Object.keys(UPSTREAMS_BUILTIN));
+const RESERVED_MODELS = new Set(MODELS_BUILTIN.map((m) => m.id));
+
+const PricesSchema = z.object({
+  input: z.number().min(0), output: z.number().min(0),
+  cacheRead: z.number().min(0).optional(), cacheWrite: z.number().min(0).optional(),
+}).strict();
+
+const UpstreamSchema = z.object({
+  label: z.string().trim().min(1).max(80).optional(),
+  baseUrl: z.string().trim().url().refine((u) => /^https?:\/\//.test(u), 'baseUrl 必须是 http(s)://'),
+  protocol: z.enum(PROTOCOLS).default('anthropic'),
+  authStyle: z.enum(AUTH_STYLES).optional(),
+  key: z.string().trim().min(1).optional(),
+  keyEnv: z.string().trim().regex(/^[A-Z][A-Z0-9_]*$/, 'keyEnv 必须是大写 env 变量名').optional(),
+  countTokens: z.boolean().default(false),
+  imageFormats: z.array(z.string()).optional(),
+}).strict();
+
+const ModelSchema = z.object({
+  id: z.string().trim().regex(ID_RE, 'id 只能是字母数字 . _ -，64 字以内'),
+  label: z.string().trim().min(1).max(60),
+  desc: z.string().trim().max(200).default(''),
+  brand: z.enum(BRANDS).default('custom'),
+  window: z.number().int().min(8_000).max(10_000_000),
+  upstream: z.string().trim().min(1),
+  wireModel: z.string().trim().min(1),
+  fastModel: z.string().trim().min(1).optional(),
+  thinking: z.enum(THINKING_MODES).default('strip'),
+  reasoningEffort: z.enum(REASONING_EFFORTS).optional(),
+  helperReasoningEffort: z.enum(REASONING_EFFORTS).optional(),
+  maxOutput: z.number().int().min(256).max(1_000_000).optional(),
+  liftImages: z.boolean().default(false),
+  prices: PricesSchema.optional(),
+  emptyRetries: z.number().int().min(0).max(10).optional(),
+  retryBudgetMs: z.number().int().min(0).max(MAX_RETRY_BUDGET_MS).optional(),
+  uncensored: z.boolean().default(false),
+}).strict();
+
+export const ConfigSchema = z.object({
+  upstreams: z.record(z.string(), UpstreamSchema).default({}),
+  models: z.array(ModelSchema).default([]),
+}).strict();
+
+/** 给配置页用的字段清单（表单按它生成，不再手写第二份） */
+export const CONFIG_ENUMS = Object.freeze({ PROTOCOLS, AUTH_STYLES, THINKING_MODES, REASONING_EFFORTS, BRANDS, MAX_RETRY_BUDGET_MS });
+
+function issueText(issue) {
+  return `${issue.path.join('.') || '(根)'}: ${issue.message}`;
+}
+
+/**
+ * 纯校验 + 归一化。不读文件、不看 profile，所以配置页保存和启动加载用的是同一个判据。
+ * @returns {{ upstreams: Record<string, object>, models: object[], errors: {where: string, message: string}[] }}
+ *   upstreams 值已是 UPSTREAMS 条目形状（label/baseUrl/keyEnv/key/authStyle/protocol/countTokens/imageFormats/external）
+ *   models 值是归一化后的配置条目（还不是表行；转表行在 model-context.js toExternalRow）
+ */
+export function validateLocalConfig(raw) {
+  const errors = [];
+  const out = { upstreams: {}, models: [], errors };
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    errors.push({ where: '(根)', message: '配置必须是一个对象 { upstreams, models }' });
+    return out;
+  }
+  // 顶层形状：分别校验每个 upstream / model，一个坏了不连坐别的
+  const top = z.object({ upstreams: z.record(z.string(), z.unknown()).default({}), models: z.array(z.unknown()).default([]) }).strict().safeParse(raw);
+  if (!top.success) {
+    for (const i of top.error.issues) errors.push({ where: '(根)', message: issueText(i) });
+    return out;
+  }
+  for (const [id, u] of Object.entries(top.data.upstreams)) {
+    const where = `upstreams.${id}`;
+    if (!ID_RE.test(id)) { errors.push({ where, message: 'upstream id 只能是字母数字 . _ -' }); continue; }
+    if (RESERVED_UPSTREAMS.has(id)) { errors.push({ where, message: `'${id}' 是内置上游名，换一个` }); continue; }
+    const r = UpstreamSchema.safeParse(u);
+    if (!r.success) { for (const i of r.error.issues) errors.push({ where, message: issueText(i) }); continue; }
+    const d = r.data;
+    const authStyle = d.authStyle || (d.protocol === 'openai-chat' ? 'bearer' : 'x-api-key');
+    if (authStyle !== 'none' && !d.key && !d.keyEnv) { errors.push({ where, message: 'key 或 keyEnv 至少填一个（authStyle 不是 none）' }); continue; }
+    out.upstreams[id] = Object.freeze({
+      label: d.label || id, baseUrl: d.baseUrl.replace(/\/+$/, ''), protocol: d.protocol, authStyle,
+      key: d.key || null, keyEnv: d.keyEnv || null, countTokens: d.countTokens,
+      ...(d.imageFormats ? { imageFormats: Object.freeze(d.imageFormats) } : {}),
+      external: true,
+    });
+  }
+  const seen = new Set();
+  top.data.models.forEach((m, i) => {
+    const where = `models[${i}]${m && typeof m === 'object' && m.id ? ` (${m.id})` : ''}`;
+    const r = ModelSchema.safeParse(m);
+    if (!r.success) { for (const iss of r.error.issues) errors.push({ where, message: issueText(iss) }); return; }
+    const d = r.data;
+    if (RESERVED_MODELS.has(d.id)) { errors.push({ where, message: `'${d.id}' 是内置模型名，换一个` }); return; }
+    if (seen.has(d.id)) { errors.push({ where, message: `id '${d.id}' 重复` }); return; }
+    if (!out.upstreams[d.upstream]) { errors.push({ where, message: `upstream '${d.upstream}' 不存在或没通过校验（外部模型只能指向本文件里的 upstream）` }); return; }
+    if (d.emptyRetries === 0 && d.retryBudgetMs) { errors.push({ where, message: 'emptyRetries=0 时 retryBudgetMs 没有意义' }); return; }
+    seen.add(d.id);
+    out.models.push(Object.freeze(d));
+  });
+  // fastModel 指向：只能是本文件里通过校验的模型（或自己）。在这里查而不是留给 model-context 的断言，
+  // 让用户在配置页就看见，而不是重启后日志里一行丢行
+  out.models = out.models.filter((d) => {
+    if (d.fastModel && !seen.has(d.fastModel)) { errors.push({ where: `models (${d.id})`, message: `fastModel '${d.fastModel}' 不是本文件里的模型` }); return false; }
+    return true;
+  });
+  return out;
+}
+
+export const configPath = process.env.NODESIGN_MODELS_CONFIG
+  ? path.resolve(process.env.NODESIGN_MODELS_CONFIG)
+  : (profile.isLocal ? path.join(profile.dataRoot, 'config.json') : null);
+
+/** 读文件 + 校验。文件不存在 = 空配置（不是错）；JSON 坏 = 一条错、当空配置（进程照起，别让一个逗号把整站拉下来） */
+export function loadLocalConfig() {
+  const empty = { upstreams: {}, models: [], errors: [], path: configPath, exists: false, raw: null };
+  if (!configPath) return empty;
+  let text;
+  try { text = fs.readFileSync(configPath, 'utf8'); } catch (err) {
+    if (err.code === 'ENOENT') return empty;
+    return { ...empty, errors: [{ where: '(文件)', message: `读不了 ${configPath}: ${err.message}` }] };
+  }
+  let raw;
+  try { raw = JSON.parse(text); } catch (err) {
+    return { ...empty, exists: true, errors: [{ where: '(文件)', message: `${configPath} 不是合法 JSON: ${err.message}` }] };
+  }
+  const v = validateLocalConfig(raw);
+  return { ...v, path: configPath, exists: true, raw };
+}
+
+/** 配置页保存：先校验（错了也照存——用户在编辑半成品，但返回 errors 让页面标红），原子写 */
+export function saveLocalConfig(raw) {
+  if (!configPath) throw new Error('hosted profile 没有本地配置文件');
+  const v = validateLocalConfig(raw);
+  const tmp = `${configPath}.tmp-${process.pid}`;
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(tmp, JSON.stringify(raw, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(tmp, configPath);
+  return { ...v, path: configPath, exists: true, raw };
+}

package/server/runtime/local-env.js

@@ -0,0 +1,88 @@
+/**
+ * server/runtime/local-env.js — 本地分发版的钥匙与开关（<dataRoot>/.env）读写，白名单制。
+ *
+ * 配置页「钥匙」那一栏的后端：只暴露 ENV_KEYS 里列的键（搜索 / 生图 / 发布 / Anthropic 直连 / 沙盒开关），
+ * 值在 GET 时打码（只报配没配 + 末四位），PUT 时改文件并同步进 process.env（web_search 这类调用时读 env 的
+ * 工具立刻生效；能力表由调用方 probeCapabilities({force:true}) 重探）。.env 里不在白名单的行原样保留。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { profile } from './profile.js';
+
+export const ENV_KEYS = Object.freeze([
+  { key: 'ANTHROPIC_API_KEY', group: '模型', label: 'API Key', secret: true, hint: '不填也行：本机 claude login 过就用那份登录态。别家服务商的钥匙不填这里，在「自定义接入」里配' },
+  { key: 'ANTHROPIC_BASE_URL', group: '模型', label: '接口地址（可选）', secret: false, hint: '不填 = Anthropic 官方；用 Anthropic 格式的中转站就填它给的地址，Claude 行直接打到那里' },
+  { key: 'NODESIGN_TAVILY_KEY', group: '联网搜索', label: 'Tavily', secret: true, hint: 'web_search 四家任一即可；英文检索优先用它' },
+  { key: 'NODESIGN_EXA_KEY', group: '联网搜索', label: 'Exa', secret: true },
+  { key: 'NODESIGN_BAIDU_QIANFAN_KEY', group: '联网搜索', label: '百度千帆', secret: true, hint: '中文检索自动路由到它' },
+  { key: 'NODESIGN_ZHIPU_KEY', group: '联网搜索', label: '智谱', secret: true },
+  // 生图通道：选哪个就只露哪个的配置项（showIf 表驱动，前端按它显隐；optionHints 是选中该项时的说明）
+  { key: 'NODESIGN_IMAGE_PROVIDER', group: '生图', label: '生图通道', secret: false, options: ['codex', 'gateway'], default: 'codex',
+    optionHints: { codex: '走本机的 OpenAI codex CLI（用你的 ChatGPT 账号）。装法：npm i -g @openai/codex，然后终端里 codex login 一次。装好后点右上角「重启」重探', gateway: '走一个兼容 OpenAI Images 接口的网关（中转站）：填它给的钥匙和地址' } },
+  { key: 'NODESIGN_GATEWAY_KEY', group: '生图', label: '网关 Key', secret: true, showIf: { NODESIGN_IMAGE_PROVIDER: 'gateway' } },
+  { key: 'NODESIGN_GATEWAY_URL', group: '生图', label: '网关 URL', secret: false, showIf: { NODESIGN_IMAGE_PROVIDER: 'gateway' }, hint: '如 https://api.example.com/v1' },
+  { key: 'NODESIGN_CODEX_BIN', group: '生图', label: 'codex 可执行路径（可选）', secret: false, showIf: { NODESIGN_IMAGE_PROVIDER: 'codex' }, hint: '装了但不在 PATH 时填绝对路径；在 PATH 里就留空' },
+  { key: 'CLOUDFLARE_API_TOKEN', group: '发布', label: 'Cloudflare API Token', secret: true, hint: 'publish_site 一键上线；还要装 wrangler' },
+  { key: 'NODESIGN_PUBLISH_DOMAIN', group: '发布', label: '发布域名后缀', secret: false, hint: '如 share.example.com；站点发到 <slug>.<这个>' },
+  { key: 'NODESIGN_CF_ACCOUNT_ID', group: '发布', label: 'Cloudflare Account ID', secret: false },
+  { key: 'NODESIGN_SANDBOX', group: '运行', label: '沙盒（Bash 隔离）', secret: false, options: ['', 'on'], hint: 'Linux bwrap / macOS sandbox-exec；Windows 没有。默认关（本地版靠 CLI 自己的权限模式）' },
+  { key: 'NODESIGN_PERMISSION_MODE', group: '运行', label: '权限模式', secret: false, options: ['', 'auto'], hint: "空 = bypassPermissions（全放）；auto = 模型分类器判每次工具调用，多花 15~20 秒/轮" },
+]);
+const ALLOWED = new Set(ENV_KEYS.map((k) => k.key));
+
+export const envPath = profile.isLocal ? path.join(profile.dataRoot, '.env') : null;
+
+function mask(v) {
+  if (!v) return '';
+  return v.length <= 8 ? '••••' : `••••${v.slice(-4)}`;
+}
+
+/** 配置页视图：每个白名单键配没配 + 打码预览（真值不出门） */
+export function envView() {
+  return ENV_KEYS.map((k) => {
+    const v = process.env[k.key] || '';
+    return { ...k, set: !!v, preview: k.secret ? mask(v) : v };
+  });
+}
+
+function parseLine(line) {
+  const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
+  return m ? m[1] : null;
+}
+
+/**
+ * 写 .env：只动白名单键；null/'' = 删行；其它行（注释、别的键）原样。同步 process.env。
+ * @param {Record<string, string|null>} values
+ * @returns {{ changed: string[] }}
+ */
+export function setEnvValues(values) {
+  if (!envPath) throw new Error('hosted profile 不在这里改 .env');
+  const changed = [];
+  for (const [k, v] of Object.entries(values || {})) {
+    if (!ALLOWED.has(k)) throw new Error(`不允许改 ${k}（不在白名单）`);
+    if (v != null && typeof v !== 'string') throw new Error(`${k} 的值必须是字符串`);
+    if (v && /[\r\n]/.test(v)) throw new Error(`${k} 的值不能含换行`);
+    const def = ENV_KEYS.find((d) => d.key === k);
+    if (def.options && v && !def.options.includes(v)) throw new Error(`${k} 只能是 ${def.options.filter(Boolean).join(' | ')} 或留空`);
+  }
+  let lines = [];
+  try { lines = fs.readFileSync(envPath, 'utf8').split('\n'); if (lines.at(-1) === '') lines.pop(); } catch (err) { if (err.code !== 'ENOENT') throw err; }
+  for (const [k, vRaw] of Object.entries(values || {})) {
+    const v = vRaw ? vRaw.trim() : '';
+    const idx = lines.findIndex((l) => parseLine(l) === k);
+    const rendered = `${k}=${/[\s#"']/.test(v) ? JSON.stringify(v) : v}`;
+    if (!v) {
+      if (idx !== -1) { lines.splice(idx, 1); changed.push(k); }
+      delete process.env[k];
+    } else {
+      if (idx !== -1) { if (lines[idx] !== rendered) { lines[idx] = rendered; changed.push(k); } } else { lines.push(rendered); changed.push(k); }
+      process.env[k] = v;
+    }
+  }
+  fs.mkdirSync(path.dirname(envPath), { recursive: true });
+  const tmp = `${envPath}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, lines.join('\n') + (lines.length ? '\n' : ''), { mode: 0o600 });
+  fs.renameSync(tmp, envPath);
+  return { changed };
+}