benchgo-plugin 0.0.0-stage → 0.0.2

package/src/session-routes.mjs

@@ -0,0 +1,89 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, lstat, chmod } from 'node:fs/promises';
+import { resolve, join, dirname, parse } from 'node:path';
+import { validateQuickSettings, quickSettingsPatches } from '../shared/tool-quick-settings.mjs';
+import { assertProviderToolAccess } from './provider-access.mjs';
+
+const supported = new Set(['codex', 'claude']);
+export const sessionRouteSupport = tool => supported.has(tool) ? { supported: true } : { supported: false, reason: '此工具尚未验证会话配置与历史隔离，请使用原生配置模式。' };
+const fail = message => { const error = new Error(message); error.code = 'SESSION_ROUTE'; throw error; };
+const text = (value, label) => { if (typeof value !== 'string' || !value.trim() || value.length > 1024 || /[\u0000-\u001f]/u.test(value)) fail('无效的' + label); return value.trim(); };
+const endpoint = value => { let url; try { url = new URL(value); } catch { fail('供应商地址无效'); } if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) fail('供应商地址无效'); return url.href.replace(/\/$/u, ''); };
+const fingerprint = route => createHash('sha256').update(JSON.stringify([route.tool, route.providerId, route.model, route.baseURL, route.protocol, route.sourceProtocol ?? null, route.credentialRef ?? null, ...(route.mode === 'subscription' ? ['subscription'] : []), ...(route.quickSettings && Object.keys(route.quickSettings).length ? [route.quickSettings] : [])])).digest('hex');
+const configArgs = config => {
+  const flatten = (value, path = []) => Object.entries(value).flatMap(([key, child]) => child && typeof child === 'object' ? flatten(child, [...path, key]) : [[...path, key].join('.') + '=' + JSON.stringify(child)]);
+  return flatten(config).flatMap(value => ['-c', value]);
+};
+async function privateDirectory(directory) {
+  const target = resolve(directory); let part = target;
+  while (part !== parse(part).root) { try { if ((await lstat(part)).isSymbolicLink()) fail('隔离目录不能经过符号链接'); } catch (error) { if (error.code !== 'ENOENT') throw error; } part = dirname(part); }
+  await mkdir(target, { recursive: true, mode: 0o700 }); await chmod(target, 0o700); return target;
+}
+export function createSessionRoutes({ directory, providers, profiles } = {}) {
+  if (!directory || !providers?.resolve) throw new TypeError('directory and providers.resolve are required');
+  const describe = async providerId => { try { return await (providers.describeRoute ? providers.describeRoute(providerId) : providers.resolve(providerId)); } catch { fail('无法读取绑定供应商，请检查供应商配置。'); } };
+  const checkBinding = async (tool, providerId) => {
+    const access = await providers.describeAccess?.(providerId);
+    assertProviderToolAccess(access, tool);
+    if (profiles?.list) {
+      const { bindings } = await profiles.list({ includeNative: false });
+      if (bindings?.[providerId] && !bindings[providerId].includes(tool)) fail('此供应商未授权用于当前工具。');
+    }
+    return access;
+  };
+  const descriptor = (tool, providerId, model, value, requestedProtocol) => {
+    const protocol = tool === 'codex' ? 'responses' : 'anthropic';
+    const aliases = { 'openai-responses': 'responses', 'anthropic-messages': 'anthropic' };
+    if (requestedProtocol && (aliases[requestedProtocol] || requestedProtocol) !== protocol) fail('所选协议不适用于此工具。');
+    return { version: 1, mode: 'managed', tool, providerId, model, baseURL: endpoint(value.baseURL), protocol, ...(value.protocol ? { sourceProtocol: text(value.protocol, '供应商协议') } : {}), ...(value.credentialRef ? { credentialRef: text(value.credentialRef, '凭据引用') } : {}) };
+  };
+  return {
+    supports: sessionRouteSupport,
+    async capture({ tool, providerId, model, protocol, overrides, quickSettings } = {}) {
+      if (!sessionRouteSupport(tool).supported) fail(sessionRouteSupport(tool).reason);
+      if (overrides && Object.keys(overrides).length) fail('会话隔离暂不支持高级配置覆盖；请移除覆盖项后重试。');
+      providerId = text(providerId, '供应商'); model = text(model, '模型');
+      const access = await checkBinding(tool, providerId);
+      if (access?.authMode === 'subscription' && access.configured !== true) fail('请先完成对应供应商及 Harness 工具的订阅登录。');
+      const route = access?.authMode === 'subscription'
+        ? { version: 1, mode: 'subscription', tool, providerId, model }
+        : descriptor(tool, providerId, model, await describe(providerId), protocol);
+      const settings = validateQuickSettings(tool, quickSettings);
+      if (Object.keys(settings).length) route.quickSettings = settings;
+      return { ...route, revision: randomUUID(), fingerprint: fingerprint(route) };
+    },
+    async launch({ tool, route, sessionId } = {}) {
+      if (!sessionRouteSupport(tool).supported) fail(sessionRouteSupport(tool).reason);
+      if (!route || route.tool !== tool || !['managed', 'subscription'].includes(route.mode) || route.version !== 1 || fingerprint(route) !== route.fingerprint || !/^[a-f0-9-]{36}$/iu.test(sessionId || '')) fail('会话绑定无效，拒绝使用当前默认配置替代。');
+      const access = await checkBinding(tool, route.providerId);
+      if (route.mode === 'subscription') {
+        if (access?.authMode !== 'subscription' || access.configured !== true) fail('绑定供应商的订阅登录已失效，请重新登录。');
+        const quick = quickSettingsPatches(tool, route.quickSettings), managedProfile = { configured: true, isolated: false, subscription: true, providerId: route.providerId, model: route.model };
+        if (tool === 'codex') return { managedProfile, commandArgs: [...configArgs({ ...quick.config, model: route.model, model_provider: 'openai', force_login_method: 'chatgpt' }), '-c', 'model_providers.openai={name="OpenAI",base_url="https://api.openai.com/v1",wire_api="responses",requires_openai_auth=true}'], env: { OPENAI_API_KEY: undefined, OPENAI_BASE_URL: undefined, CODEX_API_KEY: undefined, BENCHGO_SESSION_API_KEY: undefined } };
+        const env = { ANTHROPIC_BASE_URL: undefined, ANTHROPIC_AUTH_TOKEN: undefined, ANTHROPIC_API_KEY: undefined, ANTHROPIC_MODEL: route.model, ANTHROPIC_DEFAULT_SONNET_MODEL: undefined, ANTHROPIC_DEFAULT_OPUS_MODEL: undefined, ANTHROPIC_DEFAULT_HAIKU_MODEL: undefined, CLAUDE_CODE_SUBAGENT_MODEL: undefined, CLAUDE_CODE_OAUTH_TOKEN: undefined, CLAUDE_CODE_USE_BEDROCK: undefined, CLAUDE_CODE_USE_VERTEX: undefined, CLAUDE_CODE_USE_FOUNDRY: undefined, ...quick.settings?.env };
+        return { managedProfile, env, settings: { ...quick.settings, forceLoginMethod: 'claudeai', model: route.model, env }, settingSources: [] };
+      }
+      const value = await describe(route.providerId), current = descriptor(tool, route.providerId, route.model, value);
+      if (route.quickSettings && Object.keys(route.quickSettings).length) current.quickSettings = validateQuickSettings(tool, route.quickSettings);
+      if (fingerprint(current) !== route.fingerprint) fail('绑定供应商的地址、协议或凭据引用已更改，请新建会话或恢复原配置。');
+      if (typeof value.apiKey !== 'string' || !value.apiKey || /[\r\n\u0000]/u.test(value.apiKey)) fail('绑定供应商没有可用密钥。');
+      const quick = quickSettingsPatches(tool, route.quickSettings);
+      const root = await privateDirectory(join(directory, 'managed-runs')), run = await privateDirectory(join(root, sessionId));
+      const managedProfile = { configured: true, isolated: true, providerId: route.providerId, model: route.model, directory: run };
+      if (tool === 'codex') {
+        const home = await privateDirectory(join(run, 'codex'));
+        const providerId = 'benchgo_' + sessionId.replaceAll('-', '');
+        const providerConfig = '{name="BenchGo Session",base_url=' + JSON.stringify(route.baseURL) + ',wire_api="responses",env_key="BENCHGO_SESSION_API_KEY",requires_openai_auth=false}';
+        const overrides = { model: route.model, model_provider: providerId };
+        const quickArgs = configArgs(quick.config || {});
+        const commandArgs = [...quickArgs, ...Object.entries(overrides).flatMap(([key, value]) => ['-c', key + '=' + JSON.stringify(value)]), '-c', 'model_providers.' + providerId + '=' + providerConfig];
+        return { env: { CODEX_HOME: home, BENCHGO_SESSION_API_KEY: value.apiKey }, commandArgs, managedProfile };
+      }
+      const home = await privateDirectory(join(run, 'claude'));
+      const env = { CLAUDE_CONFIG_DIR: home, CLAUDE_CODE_USE_BEDROCK: undefined, CLAUDE_CODE_USE_VERTEX: undefined, CLAUDE_CODE_USE_FOUNDRY: undefined, CLAUDE_CODE_OAUTH_TOKEN: undefined, CLAUDE_CODE_API_KEY_HELPER_TTL_MS: undefined, ANTHROPIC_BASE_URL: route.baseURL, ANTHROPIC_AUTH_TOKEN: value.apiKey, ANTHROPIC_API_KEY: value.apiKey, ANTHROPIC_MODEL: route.model, ANTHROPIC_DEFAULT_SONNET_MODEL: route.model, ANTHROPIC_DEFAULT_OPUS_MODEL: route.model, ANTHROPIC_DEFAULT_HAIKU_MODEL: route.model, CLAUDE_CODE_SUBAGENT_MODEL: route.model };
+      Object.assign(env, quick.settings?.env);
+      const settings = { ...quick.settings, env, model: route.model };
+      return { env, settings, settingSources: [], managedProfile };
+    },
+  };
+}

package/src/store.mjs

@@ -0,0 +1,98 @@
+import { lstat, mkdir, open, readFile, rename, rm, stat } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { withFileLock } from '@deepseek-ai/dsh-atomic-write';
+
+const failure = (code, message, cause) => Object.assign(new Error(message, { cause }), { code });
+
+export class Store {
+  constructor(directory) { this.directory = directory; this.writes = Promise.resolve(); }
+
+  async open() {
+    if (this.lock) throw failure('BENCHGO_DATA_LOCKED', 'BenchGo store is already open');
+    await mkdir(this.directory, { recursive: true, mode: 0o700 });
+    this.lockPath = join(this.directory, 'owner.lock');
+    this.guardPath = join(this.directory, 'owner-guard');
+    // The short-lived official writer lock serializes recovery with acquisition
+    // and release, so competing recoverers cannot remove a successor's lock.
+    await withFileLock(this.guardPath, async () => {
+      let existing;
+      try {
+        const metadata = await lstat(this.lockPath);
+        if (!metadata.isFile() || metadata.isSymbolicLink()) throw failure('BENCHGO_LOCK_UNREADABLE', 'BenchGo owner lock is not a regular file; existing data was preserved');
+        existing = await readFile(this.lockPath, 'utf8');
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+      }
+      if (existing !== undefined) {
+        let owner;
+        try { owner = JSON.parse(existing); }
+        catch (cause) { throw failure('BENCHGO_LOCK_UNREADABLE', 'BenchGo owner lock is unreadable; existing data was preserved', cause); }
+        if (!owner || typeof owner !== 'object' || !Number.isInteger(owner.pid) || owner.pid <= 0 || owner.pid > 2147483647 || typeof owner.host !== 'string' || !owner.host) {
+          throw failure('BENCHGO_LOCK_UNREADABLE', 'BenchGo owner lock has an invalid PID or host; existing data was preserved');
+        }
+        if (owner.host !== hostname()) throw failure('BENCHGO_LOCK_OTHER_HOST', 'BenchGo data directory is owned by another host');
+        let exited = false;
+        try { process.kill(owner.pid, 0); }
+        catch (cause) {
+          if (cause.code === 'ESRCH') exited = true;
+          else throw failure('BENCHGO_LOCK_PROBE_FAILED', 'BenchGo cannot verify the owner process; existing lock was preserved', cause);
+        }
+        if (!exited) throw failure('BENCHGO_DATA_LOCKED', 'BenchGo data directory is already in use');
+        await rm(this.lockPath);
+      }
+      const lock = await open(this.lockPath, 'wx', 0o600);
+      const record = JSON.stringify({ pid: process.pid, host: hostname(), token: randomUUID() });
+      try { await lock.writeFile(record); }
+      catch (error) { await lock.close(); await rm(this.lockPath, { force: true }); throw error; }
+      this.lock = lock;
+      this.lockRecord = record;
+    });
+    try {
+      return JSON.parse(await readFile(join(this.directory, 'sessions.json'), 'utf8'));
+    } catch (error) {
+      if (error.code === 'ENOENT') return { version: 1, sessions: [] };
+      await this.close();
+      throw error;
+    }
+  }
+
+  save(sessions) {
+    const payload = JSON.stringify({ version: 1, sessions }, null, 2);
+    const write = this.writes.then(async () => {
+      const target = join(this.directory, 'sessions.json');
+      const temp = `${target}.${randomUUID()}.tmp`;
+      const file = await open(temp, 'wx', 0o600);
+      try { await file.writeFile(payload); await file.sync(); } finally { await file.close(); }
+      try { await rename(temp, target); } finally { await rm(temp, { force: true }); }
+      if (process.platform !== 'win32') {
+        const directory = await open(this.directory, 'r');
+        try { await directory.sync(); } finally { await directory.close(); }
+      }
+    });
+    this.writes = write.catch(() => {});
+    return write;
+  }
+
+  async close() {
+    await this.writes;
+    if (!this.lock) return;
+    await withFileLock(this.guardPath, async () => {
+      if (!this.lock) return;
+      await this.lock.close(); this.lock = undefined;
+      let record;
+      try { record = await readFile(this.lockPath, 'utf8'); }
+      catch (error) { if (error.code === 'ENOENT') return; throw error; }
+      if (record !== this.lockRecord) throw failure('BENCHGO_LOCK_OWNERSHIP_CHANGED', 'BenchGo owner lock changed; successor lock was preserved');
+      await rm(this.lockPath);
+    });
+  }
+}
+
+export async function workingDirectory(value) {
+  const { resolve } = await import('node:path');
+  const cwd = resolve(value ?? process.cwd());
+  if (!(await stat(cwd)).isDirectory()) throw new Error('cwd must be a directory');
+  return cwd;
+}

package/src/tool-catalog.mjs

@@ -0,0 +1,22 @@
+/** Fixed sources audited against CC Switch 51ac86f. */
+const npm = (id, name, packageName, command = id, extra = {}) => ({ id, name, command, packageName, installer: 'npm', platforms: ['linux', 'darwin', 'win32'], configSupported: true, chatSupported: ['claude', 'codex', 'pi', 'opencode', 'gemini', 'hermes', 'grok', 'mcode'].includes(id), ...extra });
+export const TOOL_CATALOG = Object.freeze([
+  npm('claude', 'Claude Code', '@anthropic-ai/claude-code', 'claude', { installArgs: ['--ignore-scripts=false', '--allow-scripts=@anthropic-ai/claude-code'] }),
+  { id: 'claude-desktop', name: 'Claude Desktop', command: null, installer: null, platforms: ['darwin', 'win32'], configSupported: true, chatSupported: false, installReason: 'Claude Desktop 使用官方图形安装器；当前不提供自动安装或卸载。' },
+  npm('codex', 'Codex', '@openai/codex'),
+  npm('gemini', 'Gemini CLI', '@google/gemini-cli'),
+  npm('grok', 'Grok Build', '@xai-official/grok'),
+  npm('opencode', 'OpenCode', 'opencode-ai'),
+  npm('openclaw', 'OpenClaw', 'openclaw'),
+  { id: 'hermes', name: 'Hermes', command: 'hermes', installer: 'uv', platforms: ['linux', 'darwin'], configSupported: true, chatSupported: true, source: 'git+https://github.com/NousResearch/hermes-agent.git' },
+  npm('pi', 'Pi', '@earendil-works/pi-coding-agent'),
+  npm('mcode', 'MiniMax Code', '@minimax-ai/code', 'mcode', { configSupported: true, installArgs: ['--ignore-scripts=false', '--allow-scripts=@minimax-ai/code,better-sqlite3'] }),
+].map(tool => Object.freeze({ ...tool, platforms: Object.freeze([...tool.platforms]), installArgs: Object.freeze([...(tool.installArgs ?? [])]) })));
+const aliases = { grokbuild: 'grok', 'grok-build': 'grok', minimax: 'mcode', 'minimax-code': 'mcode', 'claude-code': 'claude' };
+export function normalizeToolId(value) {
+  if (typeof value !== 'string') throw new Error('Invalid tool id');
+  const id = Object.hasOwn(aliases, value) ? aliases[value] : value;
+  if (!TOOL_CATALOG.some(tool => tool.id === id)) throw new Error('Unknown tool: ' + String(value).slice(0, 80));
+  return id;
+}
+export function getTool(value) { return TOOL_CATALOG.find(tool => tool.id === normalizeToolId(value)); }

package/src/tool-config.mjs

@@ -0,0 +1,94 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import * as TOML from 'smol-toml';
+import { parseDocument } from 'yaml';
+import { parse as parseJsonc, modify, applyEdits } from 'jsonc-parser';
+import JSON5 from 'json5';
+import { quickSettingsPatches } from '../shared/tool-quick-settings.mjs';
+
+export class ToolConfigError extends Error { constructor(message, status = 400) { super(message); this.status = status; } }
+export const TOOL_IDS = ['claude', 'claude-desktop', 'codex', 'gemini', 'grok', 'opencode', 'openclaw', 'hermes', 'pi', 'mcode'];
+const protocols = { claude: ['anthropic'], 'claude-desktop': ['anthropic'], codex: ['responses'], gemini: ['gemini'], grok: ['responses', 'openai'], opencode: ['openai', 'anthropic', 'responses'], openclaw: ['openai', 'anthropic', 'responses'], hermes: ['openai', 'anthropic', 'responses'], pi: ['openai', 'anthropic', 'responses'], mcode: ['anthropic', 'openai', 'responses'] };
+export const toolCapabilities = () => TOOL_IDS.map(tool => ({ tool, configSupported: true, sessionSupported: ['claude', 'codex', 'pi', 'opencode', 'gemini', 'hermes', 'grok', 'mcode'].includes(tool), protocols: protocols[tool], modelSelection: tool !== 'mcode' }));
+export function toolId(value) { const id = ({ grokbuild: 'grok', 'grok-build': 'grok', minimax: 'mcode', 'minimax-code': 'mcode', claudecode: 'claude' })[value] || value; if (!TOOL_IDS.includes(id)) throw new ToolConfigError('不支持的工具'); return id; }
+const plain = x => x && typeof x === 'object' && !Array.isArray(x);
+export function validateObject(value, { overrides = false } = {}, depth = 0) {
+  if (depth > 24) throw new ToolConfigError('配置嵌套过深');
+  if (Array.isArray(value)) { for (const x of value) validateObject(x, { overrides }, depth + 1); return; }
+  if (!plain(value)) return;
+  for (const [key, child] of Object.entries(value)) {
+    if (['__proto__', 'prototype', 'constructor'].includes(key)) throw new ToolConfigError('配置含不安全字段');
+    if (overrides && /(?:api.?key|(?:auth|access|bearer|refresh|id)[_-]?token|^token$|secret|password|authorization|credential|base.?url|endpoint|url|headers|^env$|command|executable)/iu.test(key)) throw new ToolConfigError('高级配置不能保存密钥、端点或执行入口，请引用官方供应商');
+    validateObject(child, { overrides }, depth + 1);
+  }
+}
+export function mergeConfig(target, patch) {
+  validateObject(patch);
+  for (const [key, value] of Object.entries(patch)) {
+    if (plain(value)) { if (target[key] !== undefined && !plain(target[key])) throw new ToolConfigError('配置结构冲突，请检查高级配置'); target[key] ??= {}; mergeConfig(target[key], value); }
+    else if (Array.isArray(value) && Array.isArray(target[key]) && value.every(item => plain(item) && typeof item.id === 'string')) {
+      const previous = target[key]; target[key] = previous.map(item => structuredClone(item));
+      for (const item of value) { const index = target[key].findIndex(old => old?.id === item.id); if (index < 0) target[key].push(structuredClone(item)); else mergeConfig(target[key][index], item); }
+    } else target[key] = structuredClone(value);
+  }
+  return target;
+}
+const file = (role, path, format) => ({ role, path, format });
+export function nativeConfigFiles(tool, { home = homedir(), env = process.env, platform = process.platform } = {}) {
+  tool = toolId(tool); const config = env.XDG_CONFIG_HOME || join(home, '.config');
+  switch (tool) {
+    case 'claude': return [file('settings', join(env.CLAUDE_CONFIG_DIR || join(home, '.claude'), 'settings.json'), 'jsonc')];
+    case 'codex': return [file('config', join(env.CODEX_HOME || join(home, '.codex'), 'config.toml'), 'toml')];
+    case 'gemini': { const dir = env.GEMINI_CLI_HOME ? join(env.GEMINI_CLI_HOME, '.gemini') : join(home, '.gemini'); return [file('settings', join(dir, 'settings.json'), 'jsonc'), file('env', join(dir, '.env'), 'env')]; }
+    case 'grok': return [file('config', join(env.GROK_HOME || join(home, '.grok'), 'config.toml'), 'toml')];
+    case 'opencode': { const dir = env.OPENCODE_CONFIG_DIR || join(config, 'opencode'); return [file('config', env.OPENCODE_CONFIG || join(dir, existsSync(join(dir, 'opencode.jsonc')) ? 'opencode.jsonc' : 'opencode.json'), 'jsonc')]; }
+    case 'openclaw': return [file('config', env.OPENCLAW_CONFIG_PATH || join(env.OPENCLAW_STATE_DIR || join(home, '.openclaw'), 'openclaw.json'), 'json5')];
+    case 'hermes': return [file('config', join(env.HERMES_HOME?.trim() || (platform === 'win32' ? join(env.LOCALAPPDATA || join(home, 'AppData', 'Local'), 'hermes') : join(home, '.hermes')), 'config.yaml'), 'yaml')];
+    case 'pi': { const dir = env.PI_CODING_AGENT_DIR || join(home, '.pi', 'agent'); return [file('config', join(dir, 'models.json'), 'jsonc'), file('settings', join(dir, 'settings.json'), 'jsonc')]; }
+    case 'mcode': return [file('config', join(env.MINIMAX_DATA_DIR || env.MAVIS_DATA_DIR || join(home, '.minimax'), 'config.yaml'), 'yaml')];
+    case 'claude-desktop': { const root = platform === 'darwin' ? join(home, 'Library', 'Application Support') : platform === 'win32' ? env.LOCALAPPDATA || join(home, 'AppData', 'Local') : config; const dir = join(root, 'Claude-3p', 'configLibrary'); return [file('settings', join(root, 'Claude', 'claude_desktop_config.json'), 'jsonc'), file('config', join(root, 'Claude-3p', 'claude_desktop_config.json'), 'jsonc'), file('profile', join(dir, '36da542a-1436-49c2-8426-66287831dc66.json'), 'jsonc'), file('meta', join(dir, '_meta.json'), 'jsonc')]; }
+  }
+}
+const api = protocol => ({ openai: 'openai-completions', responses: 'openai-responses', anthropic: 'anthropic-messages' })[protocol];
+export function nativePatches(profile, provider, current = {}) {
+  const tool = toolId(profile.tool), protocol = profile.protocol || protocols[tool][0];
+  if (!protocols[tool].includes(protocol)) throw new ToolConfigError('工具不支持此 API 协议');
+  const { baseURL, apiKey } = provider, model = profile.model, id = 'benchgo', node = { id: model, name: model }; let patches;
+  switch (tool) {
+    case 'claude': patches = { settings: { env: { ANTHROPIC_BASE_URL: baseURL, ANTHROPIC_AUTH_TOKEN: apiKey, ANTHROPIC_API_KEY: apiKey, ANTHROPIC_MODEL: model } } }; break;
+    case 'codex': patches = { config: { model, model_provider: id, model_providers: { [id]: { name: 'BenchGo', base_url: baseURL, wire_api: 'responses', requires_openai_auth: false, experimental_bearer_token: apiKey } } } }; break;
+    case 'gemini': patches = { settings: { security: { auth: { selectedType: 'gemini-api-key' } }, model: { name: model } }, env: { GEMINI_API_KEY: apiKey, GOOGLE_GEMINI_BASE_URL: baseURL, GEMINI_MODEL: model } }; break;
+    case 'grok': patches = { config: { models: { default: id }, model: { [id]: { model, name: model, base_url: baseURL, api_key: apiKey, api_backend: protocol === 'openai' ? 'chat_completions' : 'responses', context_window: profile.contextWindow || 500000 } } } }; break;
+    case 'opencode': patches = { config: { model: id + '/' + model, provider: { [id]: { npm: protocol === 'anthropic' ? '@ai-sdk/anthropic' : protocol === 'responses' ? '@ai-sdk/openai' : '@ai-sdk/openai-compatible', name: 'BenchGo', options: { baseURL, apiKey }, models: { [model]: { name: model } } } } } }; break;
+    case 'openclaw': patches = { config: { models: { mode: 'merge', providers: { [id]: { baseUrl: baseURL, apiKey, api: api(protocol), models: [node] } } }, agents: { defaults: { model: { primary: id + '/' + model } } } } }; break;
+    case 'hermes': { const providers = current.config?.custom_providers || []; if (!Array.isArray(providers)) throw new ToolConfigError('Hermes custom_providers 应为数组'); const entry = mergeConfig(structuredClone(providers.find(x => x.name === id) || {}), { name: id, base_url: baseURL, api_key: apiKey, model, models: { [model]: {} }, api_mode: protocol === 'responses' ? 'codex_responses' : protocol === 'anthropic' ? 'anthropic_messages' : 'chat_completions' }); patches = { config: { model: { provider: id, default: model, base_url: baseURL }, custom_providers: [...providers.filter(x => x.name !== id), entry] } }; break; }
+    case 'pi': patches = { config: { providers: { [id]: { baseUrl: baseURL, apiKey, api: api(protocol), models: [node] } } }, settings: { defaultProvider: id, defaultModel: model } }; break;
+    case 'mcode': patches = { config: { custom_provider: { [id]: { kind: 'custom', name: 'BenchGo', api: api(protocol), options: { baseURL, apiKey }, models: { [model]: { name: model } } } } } }; break;
+    case 'claude-desktop': { const profileId = '36da542a-1436-49c2-8426-66287831dc66', entries = current.meta?.entries || []; if (!Array.isArray(entries)) throw new ToolConfigError('Desktop entries 应为数组'); patches = { settings: { deploymentMode: '3p' }, config: { deploymentMode: '3p' }, profile: { inferenceGatewayApiKey: apiKey, inferenceGatewayAuthScheme: 'bearer', inferenceGatewayBaseUrl: baseURL, inferenceProvider: 'gateway', inferenceModels: [{ name: model }] }, meta: { entries: [...entries.filter(x => x.id !== profileId), mergeConfig(structuredClone(entries.find(x => x.id === profileId) || {}), { id: profileId, name: 'BenchGo' })], appliedId: profileId } }; break; }
+  }
+  for (const [role, patch] of Object.entries(profile.overrides || {})) { if (!patches[role]) throw new ToolConfigError('无效的配置文件角色'); mergeConfig(patches[role], patch); }
+  for (const [role, patch] of Object.entries(quickSettingsPatches(tool, profile.quickSettings))) mergeConfig(patches[role] ??= {}, patch);
+  return patches;
+}
+export function parseConfig(raw, format) {
+  try { let value;
+    if (format === 'toml') value = TOML.parse(raw);
+    else if (format === 'yaml') { const doc = parseDocument(raw, { uniqueKeys: true }); if (doc.errors.length) throw Error(); value = doc.toJS({ maxAliasCount: 50 }) ?? {}; }
+    else if (format === 'jsonc') { const errors = []; value = raw.trim() ? parseJsonc(raw, errors, { allowTrailingComma: true }) : {}; if (errors.length) throw Error(); }
+    else if (format === 'json5') value = raw.trim() ? JSON5.parse(raw) : {};
+    else return {};
+    if (!plain(value)) throw Error(); validateObject(value); return value;
+  } catch { throw new ToolConfigError('原生配置格式无效，请先修复文件', 409); }
+}
+export function renderConfig(raw, format, patch) {
+  const current = parseConfig(raw, format), merged = mergeConfig(structuredClone(current), patch);
+  const preserveArrays = (value, before) => { for (const [key, child] of Object.entries(value)) { if (Array.isArray(child)) value[key] = mergedValue(before, key, child); else if (plain(child)) preserveArrays(child, before?.[key]); } };
+  const mergedValue = (before, key, child) => Array.isArray(child) && child.every(item => plain(item) && typeof item.id === 'string') ? mergeConfig({ value: structuredClone(before?.[key] || []) }, { value: child }).value : child;
+  patch = structuredClone(patch); preserveArrays(patch, current);
+  if (format === 'env') { const remaining = { ...patch }, lines = raw.split(/\r?\n/u).map(line => { const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/u); if (!match || !Object.hasOwn(patch, match[1])) return line; delete remaining[match[1]]; return match[1] + '=' + JSON.stringify(String(patch[match[1]])); }); for (const [key, value] of Object.entries(remaining)) { if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(key) || typeof value === 'object') throw new ToolConfigError('无效的环境配置'); lines.push(key + '=' + JSON.stringify(String(value))); } return lines.join('\n').replace(/\n*$/u, '\n'); }
+  if (format === 'toml') return TOML.stringify(merged);
+  if (format === 'json5') return JSON.stringify(merged, null, 2) + String.fromCharCode(10);
+  if (format === 'yaml') { const doc = parseDocument(raw || '{}\n', { uniqueKeys: true }); const visit = (value, path = []) => { for (const [key, child] of Object.entries(value)) { const next = [...path, key]; if (plain(child)) { if (!Object.keys(child).length && !doc.hasIn(next)) doc.setIn(next, {}); else visit(child, next); } else doc.setIn(next, child); } }; visit(patch); return doc.toString(); }
+  let result = raw.trim() ? raw : '{}\n'; const visit = (value, path = []) => { for (const [key, child] of Object.entries(value)) { const next = [...path, key]; if (plain(child) && Object.keys(child).length) visit(child, next); else result = applyEdits(result, modify(result, next, child, { formattingOptions: { insertSpaces: true, tabSize: 2 } })); } }; visit(patch); parseConfig(result, format); return result;
+}

package/src/tool-install.mjs

@@ -0,0 +1,31 @@
+import { EventEmitter } from 'node:events';
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { access, realpath } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, resolve } from 'node:path';
+import { TOOL_CATALOG, getTool, normalizeToolId } from './tool-catalog.mjs';
+const finished = new Set(['succeeded', 'failed', 'cancelled']); const clone = v => JSON.parse(JSON.stringify(v));
+export function redactToolOutput(value, env = process.env) { let text = String(value).replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, ''); for (const [key, secret] of Object.entries(env)) if (/(?:key|token|secret|password|authorization|credential)/i.test(key) && typeof secret === 'string' && secret.length >= 4) text = text.split(secret).join('[REDACTED]'); return text.replace(/(https?:\/\/)[^\s/@:]+:[^\s/@]+@/gi, '$1[REDACTED]@').replace(/\b(?:sk|dg|api)[_-][A-Za-z0-9_-]{12,}\b/g, '[REDACTED]').replace(/((?:api[_-]?key|access[_-]?token|authorization|password|secret)\s*[=:]\s*)(?:Bearer\s+)?[^\s,;]+/gi, '$1[REDACTED]'); }
+export function executeToolCommand(command, args, { env = process.env, cwd, signal, onOutput } = {}) { return new Promise((resolvePromise, reject) => { if (signal?.aborted) return reject(new Error('Operation cancelled')); const child = spawn(command, args, { env, cwd, shell: false, windowsHide: true, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] }); let tail = ''; const kill = () => { try { process.platform === 'win32' ? child.kill() : process.kill(-child.pid, 'SIGTERM'); } catch {} }; const cleanup = () => signal?.removeEventListener('abort', kill); const data = c => { const v = c.toString(); tail = (tail + v).slice(-8192); onOutput?.(v); }; child.stdout.on('data', data); child.stderr.on('data', data); signal?.addEventListener('abort', kill, { once: true }); child.once('error', e => { cleanup(); reject(e); }); child.once('close', code => { cleanup(); if (signal?.aborted) reject(new Error('Operation cancelled')); else if (code) reject(new Error('Command exited with code ' + code + ': ' + tail)); else resolvePromise({ code, stdout: tail }); }); }); }
+export class ToolInstaller extends EventEmitter {
+  constructor({ platform = process.platform, env = process.env, executor = executeToolCommand, isRunning = () => false, maxConcurrent = 2, timeoutMs = 15 * 60_000 } = {}) { super(); this.platform = platform; this.env = { ...env }; this.executor = executor; this.isRunning = isRunning; this.maxConcurrent = maxConcurrent; this.timeoutMs = timeoutMs; this.records = new Map(); this.controllers = new Map(); this.pending = []; this.active = 0; this.tasks = new Set(); this.closed = false; }
+  async usable(path) { try { await access(path, this.platform === 'win32' ? constants.F_OK : constants.X_OK); return true; } catch { return false; } }
+  async findExecutables(command) { if (!command) return []; const dirs = String(this.env.PATH ?? this.env.Path ?? '').split(this.platform === 'win32' ? ';' : delimiter).filter(Boolean); dirs.push(resolve(homedir(), '.local/bin'), resolve(homedir(), '.npm-global/bin')); const suffixes = this.platform === 'win32' ? ['', '.exe', '.cmd', '.bat'] : ['']; const found = []; for (const dir of dirs) for (const suffix of suffixes) { const path = resolve(dir, command + suffix); if (await this.usable(path)) { const rp = await realpath(path).catch(() => path); if (!found.some(item => item.realpath === rp)) found.push({ path, realpath: rp }); } } return found; }
+  async systemExecutable(id) { return (await this.findExecutables(getTool(id).command))[0]?.path ?? null; }
+  async resolveExecutable(id) { return this.systemExecutable(id); }
+  async resolveLaunch(id) { const command = await this.systemExecutable(id); return command ? { command, args: [] } : null; }
+  async version(command) { try { const r = await this.executor(command, ['--version'], { env: this.env }); return r.stdout.match(/\b\d+\.\d+(?:\.\d+)?\b/)?.[0] ?? null; } catch { return null; } }
+  sourceFor(path, tool) { if (!path) return 'none'; const p = path.replaceAll('\\', '/'); if (p.includes('/homebrew/') || p.includes('/Cellar/')) return 'homebrew'; if (p.includes('/node_modules/.bin/') || p.includes('/npm/')) return 'npm'; if (tool.installer === 'uv' || p.includes('/.local/bin/')) return 'uv'; return 'unknown'; }
+  async npmRoot() { try { return (await this.executor('npm', ['root', '--global'], { env: this.env })).stdout.trim().replace(/[\\/]+$/, ''); } catch { return null; } }
+  async list() { return Promise.all(TOOL_CATALOG.map(async tool => { const installations = (await this.findExecutables(tool.command)).map(item => ({ ...item, source: this.sourceFor(item.realpath, tool), version: null })); for (const i of installations) { i.version = await this.version(i.path); if (i.source === 'npm') { const root = await this.npmRoot(); i.sourceVerified = !!root && i.realpath.startsWith(root + '/'); } } const job = [...this.records.values()].find(v => v.toolId === tool.id && !finished.has(v.status)); const running = await this.isRunning(tool.id); const locked = running ? '工具正在运行，请先结束会话。' : job ? '工具已有进行中的任务。' : null; const i = installations[0], source = i?.source ?? 'none'; const sourceSafe = source !== 'unknown' && (source !== 'npm' || i?.sourceVerified); return { ...tool, installations, installed: !!i, executable: i?.path ?? null, version: i?.version ?? null, source, systemExecutable: i?.path ?? null, canInstall: !!tool.installer && !i && !locked, canUpdate: !!i && sourceSafe && !locked, canReinstall: !!i && sourceSafe && !locked, canUninstall: !!i && sourceSafe && !locked, updateReason: !sourceSafe ? '安装来源未验证，无法自动更新。' : locked, uninstallReason: !sourceSafe ? '安装来源未验证，无法自动卸载。' : locked, ...(job ? { job: clone(job) } : {}) }; })); }
+  async previewUninstall(id) { const tool = getTool(id); const target = (await this.findExecutables(tool.command))[0]; if (!target) return { available: false, reason: '未找到系统安装。' }; const source = this.sourceFor(target.realpath, tool); const command = source === 'homebrew' ? 'brew uninstall' : source === 'uv' ? 'uv tool uninstall' : source === 'npm' ? 'npm uninstall --global' : null; return { available: !!command, path: target.path, realpath: target.realpath, source, version: await this.version(target.path), command, description: command ? `将使用 ${command} 移除该安装` : '安装来源未知，无法自动卸载。', snapshot: target.realpath }; }
+  install(id, options) { return this.enqueue(id, 'install', options); } updateTool(id, options) { return this.enqueue(id, 'update', options); } reinstall(id, options) { return this.enqueue(id, 'reinstall', options); } uninstall(id, options = {}) { return this.enqueue(id, 'uninstall', options); }
+  enqueue(id, action, options = {}) { id = normalizeToolId(id); if ([...this.records.values()].some(j => j.toolId === id && !finished.has(j.status))) throw new Error('工具已有进行中的任务。'); const job = { id: randomUUID(), toolId: id, action, source: options.source ?? null, snapshot: options.snapshot ?? null, status: 'queued', message: '等待执行', logs: [], error: null, createdAt: new Date().toISOString(), startedAt: null, finishedAt: null }; this.records.set(job.id, job); this.pending.push(job.id); this.emit('job', clone(job)); queueMicrotask(() => this.drain()); return clone(job); }
+  jobs() { return [...this.records.values()].map(clone); } job(id) { const j = this.records.get(id); if (!j) throw new Error('Unknown installation job'); return clone(j); }
+  cancel(id) { const j = this.records.get(id); if (!j) throw new Error('Unknown installation job'); if (!finished.has(j.status)) { this.controllers.get(id)?.abort(); Object.assign(j, { status: 'cancelled', message: '已取消', finishedAt: new Date().toISOString() }); this.emit('job', clone(j)); } return clone(j); }
+  drain() { while (!this.closed && this.active < this.maxConcurrent && this.pending.length) { const j = this.records.get(this.pending.shift()); if (!j || finished.has(j.status)) continue; this.active++; const task = this.run(j).finally(() => { this.active--; this.tasks.delete(task); this.drain(); }); this.tasks.add(task); } }
+  async run(job) { const controller = new AbortController(); this.controllers.set(job.id, controller); const timer = setTimeout(() => controller.abort(new Error('任务超时。')), this.timeoutMs); timer.unref(); const log = c => { job.logs = [...job.logs, ...String(c).split(/[\r\n]+/).filter(Boolean).map(x => redactToolOutput(x, this.env).slice(0, 1000))].slice(-80); this.emit('job', clone(job)); }; try { Object.assign(job, { status: 'running', message: '正在执行', startedAt: new Date().toISOString() }); const tool = getTool(job.toolId); if (await this.isRunning(tool.id)) throw new Error('工具正在运行，请先结束会话后重试。'); const target = (await this.findExecutables(tool.command))[0]; if (job.action === 'uninstall') { if (!target || (job.snapshot && job.snapshot !== target.realpath)) throw new Error('工具安装位置已变化，请刷新后重新确认。'); const source = this.sourceFor(target.realpath, tool); if (source === 'unknown') throw new Error('安装来源未知，拒绝自动卸载。'); await this.executor(source === 'homebrew' ? 'brew' : tool.installer === 'uv' ? 'uv' : 'npm', source === 'homebrew' ? ['uninstall', tool.packageName ?? tool.id] : tool.installer === 'uv' ? ['tool', 'uninstall', tool.packageName ?? tool.id] : ['uninstall', '--global', tool.packageName], { env: this.env, signal: controller.signal, onOutput: log }); } else { if (!tool.installer) throw new Error(tool.installReason ?? '该工具不支持自动安装。'); let command = tool.installer === 'uv' ? 'uv' : 'npm'; let args = tool.installer === 'uv' ? ['tool', 'install', '--force', ...(job.action === 'update' ? ['--upgrade'] : []), tool.source] : ['install', '--global', ...(job.action === 'update' ? ['--force'] : []), tool.packageName + '@latest']; if (job.action === 'update' && target && this.sourceFor(target.realpath, tool) === 'homebrew') { command = 'brew'; args = ['upgrade', tool.packageName ?? tool.id]; } await this.executor(command, args, { env: this.env, signal: controller.signal, onOutput: log }); if (!(await this.systemExecutable(tool.id))) throw new Error('操作完成但未发现系统工具入口。'); } if (!controller.signal.aborted) Object.assign(job, { status: 'succeeded', message: '操作完成，已重新探测系统安装', finishedAt: new Date().toISOString() }); } catch (e) { if (job.status !== 'cancelled') Object.assign(job, { status: 'failed', message: '操作失败', error: redactToolOutput(controller.signal.aborted ? controller.signal.reason?.message ?? '任务已中止' : e.message, this.env).slice(0, 1200), finishedAt: new Date().toISOString() }); } finally { clearTimeout(timer); this.controllers.delete(job.id); this.emit('job', clone(job)); } }
+  async close() { this.closed = true; for (const j of this.records.values()) if (!finished.has(j.status)) this.cancel(j.id); await Promise.allSettled([...this.tasks]); }
+}

package/src/tool-profiles.mjs

@@ -0,0 +1,114 @@
+import { mkdir, open, readFile, rename, rm, lstat, chmod } from 'node:fs/promises';
+import { join, dirname, resolve, parse } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { ToolConfigError, TOOL_IDS, toolId, toolCapabilities, nativeConfigFiles, nativePatches, parseConfig, renderConfig, validateObject } from './tool-config.mjs';
+
+import { validateQuickSettings } from '../shared/tool-quick-settings.mjs';
+import { assertProviderToolAccess } from './provider-access.mjs';
+
+const hash = value => createHash('sha256').update(value).digest('hex');
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+const text = (value, label) => { if (typeof value !== 'string' || !value.trim() || value.length > 512 || /[\u0000-\u001f]/u.test(value)) throw new ToolConfigError('无效的' + label); return value.trim(); };
+async function safePath(path) { let part = resolve(path); while (part !== parse(part).root) { try { const info = await lstat(part); if (info.isSymbolicLink()) throw new ToolConfigError('配置路径不能经过符号链接', 409); } catch (e) { if (e.code !== 'ENOENT') throw e; } part = dirname(part); } }
+async function read(path) { await safePath(path); try { const info = await lstat(path); if (!info.isFile() || info.size > 8 * 1024 * 1024) throw new ToolConfigError('配置文件类型或大小不受支持', 409); return await readFile(path, 'utf8'); } catch (e) { if (e.code === 'ENOENT') return null; throw e; } }
+async function atomic(path, value) {
+  await safePath(path); await mkdir(dirname(path), { recursive: true, mode: 0o700 }); const temporary = path + '.' + randomUUID() + '.tmp'; let handle;
+  try { handle = await open(temporary, 'wx', 0o600); await handle.writeFile(value); await handle.sync(); await handle.close(); handle = null; await safePath(path); await rename(temporary, path); await chmod(path, 0o600); }
+  finally { await handle?.close(); await rm(temporary, { force: true }); }
+}
+export function createToolProfiles({ directory, providers, ...paths }) {
+  if (!directory || !providers?.resolve) throw new TypeError('directory and official provider resolver are required');
+  const storePath = join(directory, 'tool-profiles.json'), backupDir = join(directory, 'tool-config-backups'); let queue = Promise.resolve();
+  const exclusive = operation => { const result = queue.then(async () => { await mkdir(directory, { recursive: true, mode: 0o700 }); const lock = join(directory, '.tool-profiles.lock'); try { await mkdir(lock, { mode: 0o700 }); } catch (e) { if (e.code === 'EEXIST') throw new ToolConfigError('工具配置正在由其他操作更新，请稍后重试', 409); throw e; } try { return await operation(); } finally { await rm(lock, { recursive: true, force: true }); } }); queue = result.catch(() => {}); return result; };
+  const state = async () => { const raw = await read(storePath); if (!raw) return { version: 1, profiles: {}, bindings: {}, backups: [] }; try { const data = JSON.parse(raw); if (data.version !== 1 || !object(data.profiles) || !object(data.bindings) || !Array.isArray(data.backups)) throw Error(); validateObject(data); return data; } catch { throw new ToolConfigError('工具配置存储损坏，原文件已保留', 409); } };
+  const persist = data => atomic(storePath, JSON.stringify(data, null, 2) + '\n');
+  const checkAccess = async (providerId, tool) => assertProviderToolAccess(await providers.describeAccess?.(providerId), tool);
+  const nativeStatus = async data => Promise.all(TOOL_IDS.map(async tool => {
+    const applied = data.applied?.[tool];
+    const files = await Promise.all(nativeConfigFiles(tool, paths).map(async spec => {
+      try { await safePath(spec.path); const info = await lstat(spec.path); const exists = info.isFile(); const checksum = exists ? hash(await readFile(spec.path, 'utf8')) : null; return { ...spec, exists, ...(applied?.nativeChecksums ? { externalChanged: (applied.nativeChecksums[spec.path] ?? null) !== checksum } : {}) }; }
+      catch (error) { return { ...spec, exists: false, ...(applied?.nativeChecksums ? { externalChanged: (applied.nativeChecksums[spec.path] ?? null) !== null } : {}), ...(error.code !== 'ENOENT' ? { unavailable: true } : {}) }; }
+    }));
+    return { tool, files, hasConfiguration: files.some(file => file.exists), ...(applied?.lastSyncAt ? { lastSyncAt: applied.lastSyncAt } : {}) };
+  }));
+  const sanitize = profile => profile ? structuredClone(profile) : null;
+  const build = async (input, data) => {
+    const tool = toolId(input.tool), profile = data.profiles[tool]; if (!profile) throw new ToolConfigError('请先保存工具配置', 409);
+    if (input.revision && input.revision !== profile.revision) throw new ToolConfigError('工具方案已变更，请重新预览', 409);
+    if (data.bindings[profile.providerId] && !data.bindings[profile.providerId].includes(tool)) throw new ToolConfigError('此供应商未绑定当前工具', 409);
+    await checkAccess(profile.providerId, tool);
+    const provider = await providers.resolve(profile.providerId);
+    let address; try { address = new URL(provider.baseURL); } catch { throw new ToolConfigError('供应商地址无效'); }
+    if (!['http:', 'https:'].includes(address.protocol) || address.username || address.password || address.search || address.hash || typeof provider.apiKey !== 'string' || !provider.apiKey || /[\r\n\u0000]/u.test(provider.apiKey)) throw new ToolConfigError('供应商连接配置无效');
+    if (JSON.stringify(profile.overrides).includes(provider.apiKey)) throw new ToolConfigError('高级配置不能包含供应商密钥');
+    const files = [], current = {};
+    for (const spec of nativeConfigFiles(tool, paths)) { const before = await read(spec.path); current[spec.role] = parseConfig(before || '', spec.format); files.push({ ...spec, before }); }
+    const patches = nativePatches(profile, provider, current);
+    for (const item of files) { item.after = renderConfig(item.before || '', item.format, patches[item.role]); item.checksum = item.before === null ? null : hash(item.before); }
+    return { tool, profile, files, warnings: [tool === 'mcode' ? 'MiniMax 的当前模型由原生工具选择；这里只登记供应商和模型。' : '正在运行的原生工具可能需要重启才能读取新配置。', ...(files.some(x => ['toml', 'json5'].includes(x.format)) ? ['TOML/JSON5 保留所有配置字段，格式与注释可能重排。'] : []), ...(tool === 'claude-desktop' ? ['需要支持第三方 gateway profile 的 Claude Desktop 版本。'] : [])] };
+  };
+  const publicFiles = files => files.map(x => ({ role: x.role, path: x.path, exists: x.before !== null, checksum: x.checksum, changed: x.before !== x.after }));
+  async function transact(data, tool, files, restoreOf, appliedProfile) {
+    const changed = files.filter(x => x.before !== x.after); if (!changed.length) { data.applied ??= {}; if (appliedProfile) data.applied[tool] = { ...structuredClone(appliedProfile), nativeChecksums: { ...(data.applied[tool]?.nativeChecksums || {}), ...Object.fromEntries(files.map(x => [x.path, x.after === null ? null : hash(x.after)])) }, lastSyncAt: new Date().toISOString() }; else delete data.applied[tool]; await persist(data); return { tool, backupId: null, files: files.map(x => ({ path: x.path, checksum: x.before === null ? null : hash(x.before) })), warnings: [] }; }
+    const id = randomUUID(), createdAt = new Date().toISOString(), backup = { version: 1, id, tool, appliedProfile: data.applied?.[tool] || null, files: changed.map(x => ({ path: x.path, before: x.before, afterChecksum: x.after === null ? null : hash(x.after) })) };
+    await atomic(join(backupDir, id + '.json'), JSON.stringify(backup));
+    const written = [];
+    try {
+      for (const item of changed) {
+        const actual = await read(item.path); if (actual !== item.before) throw new ToolConfigError('原生配置被其他程序修改，请重新预览', 409);
+        if (item.after === null) await rm(item.path); else await atomic(item.path, item.after); written.push(item);
+      }
+      data.applied ??= {}; if (appliedProfile) data.applied[tool] = { ...structuredClone(appliedProfile), nativeChecksums: { ...(data.applied[tool]?.nativeChecksums || {}), ...Object.fromEntries(files.map(x => [x.path, x.after === null ? null : hash(x.after)])) }, lastSyncAt: createdAt }; else delete data.applied[tool];
+      data.backups.push({ id, tool, createdAt, files: changed.map(x => x.path), ...(restoreOf ? { restoreOf } : {}) }); await persist(data);
+    } catch (error) {
+      let conflict = false;
+      for (const item of written.reverse()) { if (await read(item.path) !== item.after) { conflict = true; continue; } if (item.before === null) await rm(item.path, { force: true }); else await atomic(item.path, item.before); }
+      if (conflict) throw new ToolConfigError('写入失败且配置随后被外部修改，已保留备份供人工恢复', 409); throw error;
+    }
+    return { tool, backupId: id, files: files.map(x => ({ path: x.path, checksum: x.after === null ? null : hash(x.after) })), warnings: [] };
+  }
+  return {
+    async list({ includeNative = true } = {}) { const data = await state(); return { profiles: Object.values(data.profiles).map(sanitize), applied: Object.values(data.applied || {}).map(sanitize), backups: data.backups.map(x => structuredClone(x)), capabilities: toolCapabilities(), ...(includeNative ? { native: await nativeStatus(data) } : {}), bindings: structuredClone(data.bindings), defaults: Object.values(data.defaults || {}).map(sanitize) }; },
+    async get(tool) { return sanitize((await state()).profiles[toolId(tool)]); },
+    async runtime(tool) {
+      tool = toolId(tool); const data = await state(), profile = data.applied?.[tool]; if (!profile) return { configured: false, env: {} };
+      if (data.bindings[profile.providerId] && !data.bindings[profile.providerId].includes(tool)) throw new ToolConfigError('此供应商未绑定当前工具', 409);
+      await checkAccess(profile.providerId, tool);
+      const { baseURL, apiKey } = await providers.resolve(profile.providerId);
+      const env = tool === 'claude' ? { ANTHROPIC_BASE_URL: baseURL, ANTHROPIC_API_KEY: apiKey, ANTHROPIC_AUTH_TOKEN: apiKey, ANTHROPIC_MODEL: profile.model } : tool === 'gemini' ? { GEMINI_API_KEY: apiKey, GOOGLE_GEMINI_BASE_URL: baseURL, GEMINI_MODEL: profile.model } : {};
+      return { configured: true, providerId: profile.providerId, model: profile.model, provider: ['pi', 'opencode'].includes(tool) ? 'benchgo' : undefined, env };
+    },
+    setBindings(input) { return exclusive(async () => { const data = await state(), providerId = text(input.providerId, '供应商'); if (!Array.isArray(input.tools) || input.tools.length > TOOL_IDS.length + 1) throw new ToolConfigError('无效的工具绑定'); const tools = [...new Set(input.tools.map(id => id === 'harness' ? id : toolId(id)))]; for (const tool of tools) await checkAccess(providerId, tool); if (!providers.describeAccess) await providers.resolve(providerId); else await providers.describeAccess(providerId); data.bindings[providerId] = tools; await persist(data); return { bindings: structuredClone(data.bindings) }; }); },
+    save(input) { return exclusive(async () => {
+      const data = await state(), tool = toolId(input.tool), providerId = text(input.providerId, '供应商'), model = text(input.model, '模型'), overrides = input.overrides || {};
+      if (!object(overrides) || JSON.stringify(overrides).length > 256 * 1024) throw new ToolConfigError('高级配置须为 JSON 对象且不超过 256 KiB'); validateObject(overrides, { overrides: true });
+      if (input.expectedRevision && input.expectedRevision !== data.profiles[tool]?.revision) throw new ToolConfigError('工具方案被修改，请刷新', 409);
+      const capability = toolCapabilities().find(x => x.tool === tool), protocol = input.protocol || capability.protocols[0]; if (!capability.protocols.includes(protocol)) throw new ToolConfigError('工具不支持此协议');
+      if (input.contextWindow !== undefined && (!Number.isSafeInteger(input.contextWindow) || input.contextWindow <= 0)) throw new ToolConfigError('上下文窗口须为正整数');
+      await checkAccess(providerId, tool);
+      const quickSettings = validateQuickSettings(tool, input.quickSettings ?? data.profiles[tool]?.quickSettings ?? {});
+      const provider = await providers.resolve(providerId); if (JSON.stringify(overrides).includes(provider.apiKey)) throw new ToolConfigError('高级配置不能包含供应商密钥');
+      if (data.bindings[providerId] && !data.bindings[providerId].includes(tool)) throw new ToolConfigError('此供应商未绑定当前工具', 409);
+      const profile = { tool, providerId, model, protocol, quickSettings, overrides: structuredClone(overrides), ...(input.contextWindow ? { contextWindow: input.contextWindow } : {}), revision: randomUUID(), updatedAt: new Date().toISOString() };
+      data.profiles[tool] = profile; await persist(data); return sanitize(profile);
+    }); },
+    setDefault(input) { return exclusive(async () => {
+      const data = await state(), tool = toolId(input.tool), profile = data.profiles[tool];
+      if (!profile || input.revision !== profile.revision) throw new ToolConfigError('工具方案已变更，请刷新后保存默认', 409);
+      if (data.bindings[profile.providerId] && !data.bindings[profile.providerId].includes(tool)) throw new ToolConfigError('此供应商未绑定当前工具', 409);
+      await checkAccess(profile.providerId, tool);
+      await providers.resolve(profile.providerId);
+      data.defaults ??= {}; data.defaults[tool] = structuredClone(profile); await persist(data);
+      return { profile: sanitize(profile) };
+    }); },
+    async preview(input) { const result = await build(input, await state()); return { tool: result.tool, revision: result.profile.revision, files: publicFiles(result.files), warnings: result.warnings }; },
+    apply(input) { return exclusive(async () => { if (input.confirmNativeWrite !== true) throw new ToolConfigError('同步本机配置需要显式确认', 409); if (!input.revision || !object(input.checksums)) throw new ToolConfigError('请先预览并确认配置文件版本', 409); const data = await state(), result = await build(input, data); if (input.checksums) for (const item of result.files) if (!Object.hasOwn(input.checksums, item.path) || input.checksums[item.path] !== item.checksum) throw new ToolConfigError('原生配置已变更，请重新预览', 409); const applied = await transact(data, result.tool, result.files, undefined, result.profile); return { ...applied, warnings: result.warnings }; }); },
+    restore(input) { return exclusive(async () => {
+      if (input.confirmNativeWrite !== true) throw new ToolConfigError('恢复本机配置需要显式确认', 409);
+      const data = await state(), info = data.backups.find(x => x.id === input.backupId); if (!info || !/^[a-f0-9-]{36}$/u.test(info.id)) throw new ToolConfigError('备份不存在', 404);
+      const backup = JSON.parse(await read(join(backupDir, info.id + '.json'))), allowed = new Set(nativeConfigFiles(info.tool, paths).map(x => x.path)), files = [];
+      for (const item of backup.files) { if (!allowed.has(item.path)) throw new ToolConfigError('备份目标与当前工具路径不一致', 409); const before = await read(item.path), checksum = before === null ? null : hash(before); if (checksum !== item.afterChecksum || input.checksums && input.checksums[item.path] !== checksum) throw new ToolConfigError('原生配置在备份后已变更，拒绝覆盖；请先另存并手动合并', 409); files.push({ path: item.path, before, after: item.before }); }
+      return transact(data, info.tool, files, info.id, backup.appliedProfile);
+    }); },
+  };
+}

package/src/tooling.mjs

@@ -0,0 +1,90 @@
+import { ToolInstaller } from './tool-install.mjs';
+import { createToolProfiles } from './tool-profiles.mjs';
+import { createSessionRoutes } from './session-routes.mjs';
+import { createPickerCatalog } from './picker-catalog.mjs';
+import { assertProviderToolAccess } from './provider-access.mjs';
+import { createNativeAuth } from './native-auth.mjs';
+import { assertSameOrigin } from '../voice/src/web.mjs';
+import { readLimited } from '../voice/src/media.mjs';
+
+/** Owner-only management surface; credentials are resolved only inside adapters. */
+export async function mountTooling(ctx, commander, providers, options = {}) {
+  const busy = tool => [...commander.sessions.values()].some(session => session.provider === tool &&
+    (commander.drivers.has(session.id) || commander.connecting.has(session.id) || ['running', 'connecting', 'waiting'].includes(session.status)));
+  const installer = options.installer ?? new ToolInstaller({ isRunning: busy });
+  providers.setNativeAuth?.(createNativeAuth({ installer }));
+  const profiles = options.profiles ?? createToolProfiles({ directory: commander.store.directory, providers });
+  commander.toolInstaller = installer; commander.toolProfiles = profiles;
+  const routeService = createSessionRoutes({ directory: commander.store.directory, providers, profiles });
+  const pickerCatalog = createPickerCatalog({ commander, installer, profiles, providers, routeService, llm: ctx.llm });
+  commander.routeService = routeService; commander.pickerCatalog = pickerCatalog;
+  // Direct official provider selections must obey the same subscription boundary
+  // as opaque native routes, including auxiliary requests and stored selections.
+  if (ctx.on && providers.describeAccess) ctx.on('llm/stream', async function* (options, next) {
+    if (!options.provider?.startsWith('commander-') && ctx.llm?.listConfigurableProviders?.().some(entry => entry.provider === options.provider)) {
+      const access = await providers.describeAccess(options.provider);
+      try { assertProviderToolAccess(access, 'harness'); }
+      catch (error) {
+        yield { type: 'finish', reason: { kind: 'error', failure: { code: error.code, message: error.message + ' 请在模型菜单中选择对应的 Harness 工具。' } } };
+        return;
+      }
+    }
+    yield* next();
+  });
+  const dispatch = async (input, signal) => {
+    switch (input.action) {
+      case 'pickerCatalog': return pickerCatalog.list();
+      case 'catalog': return { tools: (await installer.list()).map(tool => ({ ...tool, routeSupported: routeService.supports(tool.id).supported, routeReason: routeService.supports(tool.id).reason })), ...await profiles.list(), providerAccess: await providers.accessList?.() ?? [] };
+      case 'profiles': return profiles.list();
+      case 'providers': return { providers: await providers.list() };
+      case 'models': return { models: await providers.models(input.providerId, signal) };
+      case 'job': return { job: installer.job(input.id) };
+      case 'install': return { job: installer.install(input.tool) };
+      case 'update': return { job: installer.updateTool(input.tool) };
+      case 'reinstall': return { job: installer.reinstall(input.tool) };
+      case 'uninstall': return { job: installer.uninstall(input.tool, { snapshot: input.snapshot }) };
+      case 'uninstallPreview': return { preview: await installer.previewUninstall(input.tool) };
+      case 'cancel': return { job: installer.cancel(input.id) };
+      case 'setDefault': {
+        const profile = (await profiles.list()).profiles?.find(item => item.tool === input.tool);
+        if (!profile || profile.revision !== input.revision) throw Object.assign(Error('工具方案已变更，请刷新'), { status: 409 });
+        await routeService.capture({ ...profile, tool: input.tool });
+        return profiles.setDefault(input);
+      }
+      case 'saveProfile': return { profile: await profiles.save(input) };
+      case 'setBindings': return profiles.setBindings(input);
+      case 'preview': return { preview: await profiles.preview(input) };
+      case 'apply': {
+        if (input.confirmNativeWrite !== true) throw Object.assign(Error('同步本机配置需要显式确认；设置新会话默认不会修改本机配置'), { status: 409 });
+        if (busy(input.tool)) throw Object.assign(Error('工具仍有连接中的会话，请先断开再应用配置'), { status: 409 });
+        if (!input.revision || !input.checksums || typeof input.checksums !== 'object' || Array.isArray(input.checksums)) throw Error('请先预览并确认配置文件版本');
+        return { result: await profiles.apply(input) };
+      }
+      case 'restore': {
+        if (input.confirmNativeWrite !== true) throw Object.assign(Error('恢复本机配置需要显式确认'), { status: 409 });
+        const { backups } = await profiles.list(), backup = backups.find(row => row.id === input.backupId);
+        if (backup && busy(backup.tool)) throw Object.assign(Error('工具仍有连接中的会话，请先断开再恢复'), { status: 409 });
+        return { result: await profiles.restore(input) };
+      }
+      default: throw Error('未知工具管理操作');
+    }
+  };
+  const fetch = async request => {
+    try {
+      assertSameOrigin(request);
+      if (!request.headers.get('content-type')?.toLowerCase().startsWith('application/json')) throw Object.assign(Error('Expected application/json'), { status: 415 });
+      const input = JSON.parse(new TextDecoder().decode(await readLimited(request, 300 * 1024)));
+      if (!input || typeof input !== 'object' || Array.isArray(input)) throw Error('请求必须为 JSON 对象');
+      return Response.json(await dispatch(input, request.signal), { headers: { 'cache-control': 'no-store' } });
+    } catch (error) {
+      // Provider/installer failures carry controlled messages; never serialize options or resolved secrets.
+      return Response.json({ error: error.message }, { status: Number.isInteger(error.status) ? error.status : 400, headers: { 'cache-control': 'no-store' } });
+    }
+  };
+  ctx.effect(() => ctx.connection.fetch.register({ path: '/api/commander/tooling', methods: ['POST'], requestBody: 'buffered', fetch }));
+  ctx.effect(() => async () => {
+    if (commander.toolInstaller === installer) { commander.toolInstaller = undefined; commander.toolProfiles = undefined; if (commander.routeService === routeService) commander.routeService = undefined; if (commander.pickerCatalog === pickerCatalog) commander.pickerCatalog = undefined; }
+    await installer.close();
+  });
+  return { installer, profiles, fetch };
+}