ultrastiching-cli 0.0.0-stage → 0.2.0

package/registry/marketdb-datasets.json

@@ -0,0 +1,124 @@
+{
+  "datasets": {
+    "a_share_daily": {
+      "endpoint": "plasma_daily",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "adj_factor": {
+      "endpoint": "plasma_adj_factor",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "bond_daily": {
+      "endpoint": "plasma_bond_daily",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "bond_dailyprice": {
+      "endpoint": "get_bond_dailyprice",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {
+        "count_type": "1",
+        "fields": []
+      }
+    },
+    "cb_daily": {
+      "endpoint": "plasma_cb_daily",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "concept_index_daily": {
+      "endpoint": "plasma_concept_index_daily",
+      "keys": [
+        "concept_code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "fund_daily": {
+      "endpoint": "plasma_fund_daily",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "fund_dailyprice": {
+      "endpoint": "get_fund_dailyprice",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {
+        "adjust_type": "N",
+        "count_type": "1",
+        "fields": []
+      }
+    },
+    "fut_daily": {
+      "endpoint": "plasma_fut_daily",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "hk_daily": {
+      "endpoint": "plasma_hk_daily",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "index_daily": {
+      "endpoint": "plasma_index_daily",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "opt_daily": {
+      "endpoint": "plasma_opt_daily",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "sge_daily": {
+      "endpoint": "plasma_sge_daily",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "trade_cal": {
+      "endpoint": "plasma_trade_cal",
+      "keys": [
+        "exchange",
+        "calendar_date"
+      ],
+      "kwargs": {}
+    }
+  },
+  "schema_version": 1
+}

package/src/args.js

@@ -0,0 +1,31 @@
+export function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--') { positional.push(...argv.slice(i + 1)); break; }
+    if (!arg.startsWith('--') || arg === '--') { positional.push(arg); continue; }
+    const equal = arg.indexOf('=');
+    const name = arg.slice(2, equal < 0 ? undefined : equal).replaceAll('-', '_');
+    if (!name) throw new Error('Empty option name');
+    if (Object.hasOwn(flags, name)) throw new Error(`Duplicate option --${name}`);
+    if (equal >= 0) flags[name] = arg.slice(equal + 1);
+    else if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) flags[name] = argv[++i];
+    else flags[name] = true;
+  }
+  return { flags, positional };
+}
+
+export function requireValue(flags, name) {
+  if (typeof flags[name] !== 'string' || !flags[name]) throw new Error(`--${name.replaceAll('_', '-')} requires a value`);
+  return flags[name];
+}
+
+export function jsonObject(raw, label = '--args') {
+  if (raw === undefined) return {};
+  if (typeof raw !== 'string') throw new Error(`${label} requires a JSON object`);
+  let value;
+  try { value = JSON.parse(raw); } catch { throw new Error(`${label} is not valid JSON`); }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} requires a JSON object`);
+  return value;
+}

package/src/auth.js

@@ -0,0 +1,62 @@
+import { homedir } from 'node:os';
+import { resolveCredential, readCredentialFile, saveCredential, credentialsPath, ENV_KEY } from './credentials.js';
+import { hiddenKey, confirmChange } from './prompt.js';
+import { inspectEnvironment, persistEnvironment } from './environment.js';
+
+/** 只返回是否配置及来源；不进行在线鉴权，不返回秘密。 */
+export function credentialStatus(options) {
+  const credential = resolveCredential(options);
+  return { configured: !!credential.key, source: credential.source, ...(credential.path ? { path: credential.path } : {}) };
+}
+
+/** 安装与设置时把不存在或空的变量视为待同步，查询请求仍保留空 Key 报错。 */
+function configuredCredential(env, home) {
+  if (env[ENV_KEY]) return resolveCredential({ env, home });
+  const withoutEmpty = { ...env }; delete withoutEmpty[ENV_KEY];
+  return resolveCredential({ env: withoutEmpty, home });
+}
+
+/** 环境已配置则复用；没有值时自动从私有文件更新持久环境，不再次输入 Key。 */
+export function syncCredentialEnvironment({ env = process.env, home = homedir(), log = console.error, environmentOptions = {}, fromFile = false } = {}) {
+  const current = fromFile ? resolveCredential({ env: {}, home }) : configuredCredential(env, home);
+  if (!current.key) return { configured: false, source: 'missing', synchronized: false };
+  if (current.source === 'environment') return { configured: true, source: current.source, synchronized: false };
+  const result = persistEnvironment(current.key, { ...environmentOptions, env, home });
+  log('已从现有凭据文件自动同步 ULTRASTICHING_API_KEY 到持久环境；请完全退出并重启客户端。');
+  return { ...credentialStatus({ env, home }), ...result };
+}
+
+/** 已配置不重复输入；新 Key 确认一次，同时保存私有文件和持久环境。 */
+export async function configureCredential({
+  env = process.env, home = homedir(), replace = false,
+  readKey = hiddenKey, confirm = confirmChange, log = console.error, environmentOptions = {},
+} = {}) {
+  const current = configuredCredential(env, home);
+  if (current.key && !replace) {
+    log('已配置 API Key，直接复用，无需再次输入。');
+    return syncCredentialEnvironment({ env, home, log, environmentOptions });
+  }
+  const file = readCredentialFile(home);
+  const target = credentialsPath(home);
+  const expected = inspectEnvironment({ ...environmentOptions, env, home });
+  if (current.key && !await confirm(`将替换现有 API Key，同时更新 ${target} 和用户持久环境中的 ${ENV_KEY}，是否继续？`)) return { configured: true, source: current.source, cancelled: true };
+  log(`API Key 将明文保存在本机私有文件 ${target} 和用户持久环境配置；不要粘贴到 Agent 对话中。`);
+  const key = await readKey();
+  saveCredential(key, { home, expectedDigest: file?.digest });
+  let result;
+  try { result = persistEnvironment(key, { ...environmentOptions, env, home, expected }); }
+  catch (error) {
+    const diagnostic = error.toDiagnostic;
+    error.toDiagnostic = () => ({ ...(diagnostic ? diagnostic() : { message: error.message }), credentials_saved: true, credentials_path: target });
+    error.message = `凭据文件已保存，但环境同步未完成；修复下述错误后重新运行 ultrastiching auth sync --from-file，无需重新输入 Key。${error.message}`;
+    throw error;
+  }
+  log('API Key 已同步保存到凭据文件和持久环境；请完全退出并重启客户端。');
+  return { ...credentialStatus({ env, home }), ...result };
+}
+
+/** 仅由 MCP 客户端调用：标准输出为请求头 JSON；未配置 Key 时仍可浏览免费目录。 */
+export function mcpHeaders(options) {
+  const { key } = resolveCredential(options);
+  return key ? { Authorization: `Bearer ${key}` } : {};
+}

package/src/config.js

@@ -0,0 +1,33 @@
+import { homedir } from 'node:os';
+import { requireKey, resolveCredential } from './credentials.js';
+
+export const DEFAULT_BASE_URL = 'https://api.ultrastiching.com';
+
+function singleLine(label, value) {
+  if (typeof value !== 'string' || !value.trim() || value !== value.trim() || /[\r\n]/.test(value)) {
+    throw new Error(`${label} must be a non-empty single-line value without surrounding whitespace`);
+  }
+  return value;
+}
+
+export function normalizeOrigin(value, protocols = ['http:', 'https:']) {
+  const raw = singleLine('base URL', value);
+  let url;
+  try { url = new URL(raw); } catch { throw new Error('base URL must be an origin'); }
+  if (!protocols.includes(url.protocol) || url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+    throw new Error(`base URL must be a ${protocols.join('/')} origin without path, query, or credentials`);
+  }
+  return url.origin;
+}
+
+export function resolveBaseUrl(explicit, env = process.env) {
+  return normalizeOrigin(explicit !== undefined ? explicit : env.MERIDIAN_BASE_URL !== undefined ? env.MERIDIAN_BASE_URL : DEFAULT_BASE_URL);
+}
+
+/** 显式参数只影响本次调用；自动读取统一走共享凭据模块。 */
+export function resolveKey(explicit, { env = process.env, home = homedir(), optional = false } = {}) {
+  const key = explicit !== undefined ? requireKey(explicit) : resolveCredential({ env, home }).key;
+  if (key === undefined && optional) return undefined;
+  if (key === undefined) throw new Error('API Key required: run ultrastiching auth configure, set ULTRASTICHING_API_KEY, or use ~/.ultrastiching/credentials.env');
+  return key;
+}

package/src/credentials.js

@@ -0,0 +1,117 @@
+import { closeSync, fstatSync, lstatSync, openSync, readFileSync, constants, mkdirSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+
+export const ENV_KEY = 'ULTRASTICHING_API_KEY';
+export const credentialsPath = (home = homedir()) => join(home, '.ultrastiching', 'credentials.env');
+
+/** 只解析单行 Key，不执行 env 文件中的 Shell 语法。 */
+export function requireKey(value) {
+  if (typeof value !== 'string' || !value || /[\s\x00-\x1f\x7f]/u.test(value) || value === 'YOUR_ULTRASTICHING_DATA_API_KEY') {
+    throw new Error('API Key must be a non-empty single-line value without whitespace or control characters');
+  }
+  return value;
+}
+
+export function parseCredential(content, name = ENV_KEY) {
+  let found;
+  for (const source of content.split(/\r?\n/u)) {
+    let line = source.trim();
+    if (!line || line.startsWith('#')) continue;
+    if (line.startsWith('export ')) line = line.slice(7).trimStart();
+    const separator = line.indexOf('=');
+    if ((separator < 0 ? line : line.slice(0, separator)).trim() !== name) continue;
+    if (separator < 0 || found !== undefined) throw new Error(`Invalid or duplicate ${name} in credentials.env`);
+    let value = line.slice(separator + 1).trim();
+    if (value.startsWith('"') || value.startsWith("'")) {
+      if (value.length < 2 || value.at(-1) !== value[0]) throw new Error(`Invalid quoted ${name} in credentials.env`);
+      value = value.slice(1, -1);
+    }
+    found = requireKey(value);
+  }
+  return found;
+}
+
+/** Windows 使用当前用户的私有 ACL；仅允许用户、SYSTEM 与 Administrators 读取。 */
+export function windowsAcl(path, restrict = false) {
+  const literalPath = "'" + path.replaceAll("'", "''") + "'";
+  const script = `$ErrorActionPreference='Stop'; $p=${literalPath}; $sid=[System.Security.Principal.WindowsIdentity]::GetCurrent().User;
+    if ($${restrict ? 'true' : 'false'}) {
+      $acl=Get-Acl -LiteralPath $p; $acl.SetAccessRuleProtection($true,$false);
+      foreach($rule in @($acl.Access)){[void]$acl.RemoveAccessRuleSpecific($rule)};
+      $acl.SetOwner($sid);
+      if ((Get-Item -LiteralPath $p).PSIsContainer) {
+        $rule=[System.Security.AccessControl.FileSystemAccessRule]::new($sid,'FullControl','ContainerInherit,ObjectInherit','None','Allow')
+      } else {$rule=[System.Security.AccessControl.FileSystemAccessRule]::new($sid,'FullControl','Allow')};
+      $acl.AddAccessRule($rule); Set-Acl -LiteralPath $p -AclObject $acl
+    };
+    $acl=Get-Acl -LiteralPath $p;
+    if ($acl.GetOwner([System.Security.Principal.SecurityIdentifier]).Value -ne $sid.Value){throw 'credentials must be owned by current user'};
+    foreach($rule in $acl.GetAccessRules($true,$true,[System.Security.Principal.SecurityIdentifier])) {
+      if ($rule.AccessControlType -eq 'Allow' -and $rule.IdentityReference.Value -notin @($sid.Value,'S-1-5-18','S-1-5-32-544') -and ([int]$rule.FileSystemRights -band 2032127)){throw 'credentials ACL grants access to other users'}
+    }`;
+  execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], { stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true });
+}
+
+function privateDirectory(dir) {
+  let info;
+  try { info = lstatSync(dir); } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new Error(`${dir} must be a directory, not a link or file`);
+  if (process.platform === 'win32') windowsAcl(dir);
+  else if (info.uid !== process.getuid() || (info.mode & 0o022)) throw new Error(`${dir} must be an owned directory not writable by others`);
+  return true;
+}
+
+/** 读取私有文件并验证所有权、权限和类型；不存在才返回空，不吞掉权限或格式错误。 */
+export function readCredentialFile(home = homedir()) {
+  const dir = join(home, '.ultrastiching');
+  if (!privateDirectory(dir)) return undefined;
+  const path = join(dir, 'credentials.env');
+  let before;
+  try { before = lstatSync(path); } catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
+  if (!before.isFile() || before.isSymbolicLink()) throw new Error(`${path} must be a regular file, not a link`);
+  if (process.platform === 'win32') windowsAcl(path);
+  const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+  try {
+    const info = fstatSync(fd);
+    if (!info.isFile() || info.dev !== before.dev || info.ino !== before.ino || info.size > 65536) throw new Error(`${path} must be an unchanged regular file, at most 64 KiB`);
+    if (process.platform !== 'win32' && (info.uid !== process.getuid() || (info.mode & 0o077))) throw new Error(`${path} must be owned by the current user with mode 0600 or stricter`);
+    const content = readFileSync(fd, 'utf8');
+    if (Buffer.byteLength(content, 'utf8') > 65536) throw new Error(`${path} exceeds 64 KiB`);
+    return { key: parseCredential(content), digest: createHash('sha256').update(content).digest('hex'), path };
+  } finally { closeSync(fd); }
+}
+
+/** CLI、Python 和 MCP 共用环境优先约定；状态输出使用 source，不能输出 key。 */
+export function resolveCredential({ env = process.env, home = homedir() } = {}) {
+  if (Object.hasOwn(env, ENV_KEY)) return { key: requireKey(env[ENV_KEY]), source: 'environment' };
+  const file = readCredentialFile(home);
+  return file?.key ? { ...file, source: 'credentials_file' } : { source: 'missing' };
+}
+
+/** 原子保存；覆盖须携带确认前的内容摘要，并在写入前检查并发变更。 */
+export function saveCredential(key, { home = homedir(), expectedDigest } = {}) {
+  requireKey(key);
+  // 用双引号保存并不解释其中的 Shell 字符；拒绝引号避免产生歧义。
+  if (/["']/u.test(key)) throw new Error('API Key cannot contain quotes when saved to credentials.env');
+  const dir = join(home, '.ultrastiching');
+  if (!privateDirectory(dir)) {
+    mkdirSync(dir, { mode: 0o700 });
+    if (process.platform === 'win32') windowsAcl(dir, true);
+  }
+  const current = readCredentialFile(home);
+  if (current?.digest !== expectedDigest) throw new Error('credentials.env changed since confirmation; inspect it and confirm again');
+  const path = credentialsPath(home);
+  const temporary = join(dir, `.credentials-${randomUUID()}.env`);
+  try {
+    writeFileSync(temporary, `${ENV_KEY}="${key}"\n`, { mode: 0o600, flag: 'wx' });
+    if (process.platform === 'win32') windowsAcl(temporary, true);
+    if (readCredentialFile(home)?.digest !== expectedDigest) throw new Error('credentials.env changed during save; no overwrite performed');
+    renameSync(temporary, path);
+  } finally {
+    try { unlinkSync(temporary); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  return { source: 'credentials_file', path };
+}

package/src/db-cli.js

@@ -0,0 +1,50 @@
+import { jsonObject, requireValue } from './args.js';
+import { callByName } from './http.js';
+import { endpoint, parseParameter } from './registry.js';
+import { datasets, MarketDB } from './marketdb.js';
+
+const COMMON = new Set(['db', 'compact']);
+function only(flags, allowed) {
+  const extra = Object.keys(flags).filter((name) => !allowed.has(name));
+  if (extra.length) throw new Error(`Unknown db option(s): ${extra.map((x) => `--${x.replaceAll('_', '-')}`).join(', ')}`);
+}
+
+export async function dbCommand(sub, flags, { fetchImpl } = {}) {
+  const path = flags.db === undefined ? undefined : requireValue(flags, 'db');
+  const requestOptions = { key: flags.key, baseUrl: flags.base_url, timeout: flags.timeout, fetchImpl };
+  const db = new MarketDB({ path, request: callByName, requestOptions });
+  if (sub === 'init') { only(flags, COMMON); return db.init(); }
+  if (sub === 'status') { only(flags, COMMON); return db.status(); }
+  if (sub === 'validate') { only(flags, COMMON); return db.validate(); }
+  if (sub === 'sync') {
+    const name = requireValue(flags, 'dataset');
+    const spec = datasets()[name];
+    if (!spec) throw new Error(`unknown dataset: ${name}`);
+    const meta = endpoint(spec.endpoint, 'http');
+    const values = jsonObject(flags.args);
+    const extra = new Set(['dataset', 'args', 'key', 'base_url', 'timeout', 'start', 'end', ...meta.parameters, ...COMMON]);
+    only(flags, extra);
+    if (flags.start !== undefined) values.start_date = requireValue(flags, 'start');
+    if (flags.end !== undefined) values.end_date = requireValue(flags, 'end');
+    for (const name of meta.parameters) {
+      if (!Object.hasOwn(flags, name)) continue;
+      const field = meta.request?.fields?.find((item) => item.name === name) ?? { name };
+      values[name] = parseParameter(requireValue(flags, name), field);
+    }
+    return db.sync(name, values);
+  }
+  if (sub === 'repair') {
+    only(flags, new Set([...COMMON, 'dataset', 'key', 'base_url', 'timeout']));
+    return db.repair(flags.dataset === undefined ? undefined : requireValue(flags, 'dataset'));
+  }
+  if (sub === 'sql') {
+    only(flags, new Set([...COMMON, 'query', 'limit']));
+    const limit = flags.limit === undefined ? undefined : Number(requireValue(flags, 'limit'));
+    return db.sql(requireValue(flags, 'query'), limit);
+  }
+  if (sub === 'export') {
+    only(flags, new Set([...COMMON, 'table', 'path', 'format']));
+    return db.export(requireValue(flags, 'table'), requireValue(flags, 'path'), flags.format === undefined ? undefined : requireValue(flags, 'format'));
+  }
+  throw new Error('db subcommands: init, sync, status, validate, repair, sql, export');
+}

package/src/environment.js

@@ -0,0 +1,127 @@
+import { execFileSync } from 'node:child_process';
+import { lstatSync, readFileSync, mkdirSync, writeFileSync, renameSync, unlinkSync, existsSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { dirname, join, isAbsolute } from 'node:path';
+import { ENV_KEY, requireKey } from './credentials.js';
+
+const START = '# >>> UltraStiching environment >>>';
+const END = '# <<< UltraStiching environment <<<';
+const digest = content => createHash('sha256').update(content).digest('hex');
+const quote = value => "'" + value.replaceAll("'", "'\\''") + "'";
+const xml = value => value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
+
+/** 只接受当前用户拥有的普通配置文件；读取用于保留原文和复核并发修改，不执行内容。 */
+function snapshot(path) {
+  let info;
+  try { info = lstatSync(path); } catch (error) { if (error.code === 'ENOENT') return { path, digest: null, content: '' }; throw error; }
+  if (!info.isFile() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o022)) throw new Error(`${path} 必须是当前用户拥有且不能被其他用户写入的普通文件。`);
+  const content = readFileSync(path, 'utf8');
+  return { path, digest: digest(content), content, mode: info.mode & 0o777 };
+}
+
+/** 原子更新私有环境配置，保留配置文件中不属于本工具的内容。 */
+function save(entry, content) {
+  if (entry.content === content && !(entry.mode & 0o077)) return false;
+  if (snapshot(entry.path).digest !== entry.digest) throw new Error(`${entry.path} 在检查后发生变化，未覆盖。`);
+  mkdirSync(dirname(entry.path), { recursive: true, mode: 0o700 });
+  const directory = lstatSync(dirname(entry.path));
+  if (!directory.isDirectory() || directory.isSymbolicLink() || directory.uid !== process.getuid() || (directory.mode & 0o022)) throw new Error(`${dirname(entry.path)} 不是当前用户可安全写入的目录。`);
+  const temporary = join(dirname(entry.path), `.ultrastiching-${randomUUID()}`);
+  try {
+    writeFileSync(temporary, content, { mode: 0o600, flag: 'wx' });
+    if (snapshot(entry.path).digest !== entry.digest) throw new Error(`${entry.path} 在保存时发生变化，未覆盖。`);
+    renameSync(temporary, entry.path);
+  } finally { try { unlinkSync(temporary); } catch (error) { if (error.code !== 'ENOENT') throw error; } }
+  return true;
+}
+
+/** 本工具只替换自己的完整标记块；标记损坏或重复时报告根因，不猜测删除范围。 */
+function shellContent(content, key) {
+  const block = `${START}\nexport ${ENV_KEY}=${quote(key)}\n${END}`;
+  const start = content.indexOf(START), end = content.indexOf(END);
+  if (start < 0 && end < 0) return content + (content && !content.endsWith('\n') ? '\n' : '') + block + '\n';
+  if (start < 0 || end < start || content.indexOf(START, start + START.length) >= 0 || content.indexOf(END, end + END.length) >= 0) throw new Error('UltraStiching 环境配置标记损坏或重复；未覆盖 Shell 文件。');
+  return content.slice(0, start) + block + content.slice(end + END.length);
+}
+
+/** 检查持久化目标，供保存前复核；返回内容只能在本地使用，不输出到日志。 */
+export function inspectEnvironment({ home = homedir(), platform = process.platform, env = process.env } = {}) {
+  if (platform === 'win32') return [];
+  if (!['darwin', 'linux'].includes(platform)) throw new Error(`暂不支持 ${platform} 的环境变量持久化。`);
+  const shell = (env.SHELL ?? '').split('/').at(-1) || (platform === 'darwin' ? 'zsh' : 'bash');
+  if (!['bash', 'zsh', 'sh', 'dash'].includes(shell)) throw new Error(`暂不支持 ${shell} 的启动文件，请先确认该 Shell 的持久化方式。`);
+  const paths = [join(home, '.profile')];
+  if (shell === 'zsh') paths.push(join(env.ZDOTDIR && isAbsolute(env.ZDOTDIR) ? env.ZDOTDIR : home, '.zshrc'), join(env.ZDOTDIR && isAbsolute(env.ZDOTDIR) ? env.ZDOTDIR : home, '.zprofile'));
+  if (shell === 'bash') {
+    paths.push(join(home, '.bashrc'));
+    // Bash 只加载第一个存在的登录文件；不创建优先级更高的新文件来遮住用户原配置。
+    for (const name of ['.bash_profile', '.bash_login']) {
+      try { lstatSync(join(home, name)); paths.push(join(home, name)); break; }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+  }
+  if (platform === 'darwin') paths.push(join(home, 'Library', 'LaunchAgents', 'com.ultrastiching.environment.plist'));
+  else paths.push(join(env.XDG_CONFIG_HOME && isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : join(home, '.config'), 'environment.d', '90-ultrastiching.conf'));
+  return [...new Set(paths)].map(snapshot);
+}
+
+/** 原生命令的诊断保留状态与标准错误，仅过滤本次 Key，不携带秘密参数。 */
+function nativeCommand(command, args, key, options, execute) {
+  try { return execute(command, args, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 10000, windowsHide: true, ...options }); }
+  catch (original) {
+    const redact = value => String(value ?? '').replaceAll(key, '[REDACTED]');
+    const details = { command, code: original.code, status: original.status, signal: original.signal, stderr: redact(original.stderr), message: redact(original.message) };
+    const error = new Error(`环境变量同步失败：${command}，${details.stderr || details.message}`);
+    error.code = original.code; error.details = details;
+    error.toDiagnostic = () => ({ message: error.message, details });
+    throw error;
+  }
+}
+
+/** 更新系统启动环境与本进程；已运行的客户端需重启才能继承新值。 */
+export function updateSessionEnvironment(key, { platform = process.platform, env = process.env, execute = execFileSync } = {}) {
+  requireKey(key);
+  const next = { ...env, [ENV_KEY]: key };
+  if (platform === 'darwin') nativeCommand('/bin/launchctl', ['setenv', ENV_KEY, key], key, { env: next }, execute);
+  else if (platform === 'win32') {
+    const script = `$ErrorActionPreference='Stop'; $key=[Console]::In.ReadToEnd(); [Environment]::SetEnvironmentVariable('${ENV_KEY}',$key,'User')`;
+    nativeCommand('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], key, { input: key, env: next }, execute);
+  } else if (platform === 'linux') {
+    // 有桌面会话总线时更新新启动服务；纯终端环境只需本进程和启动文件。
+    if (env.DBUS_SESSION_BUS_ADDRESS || env.XDG_RUNTIME_DIR && existsSync(join(env.XDG_RUNTIME_DIR, 'bus'))) nativeCommand('dbus-update-activation-environment', ['--systemd', ENV_KEY], key, { env: next }, execute);
+  } else throw new Error(`暂不支持 ${platform} 的环境变量同步。`);
+  env[ENV_KEY] = key;
+}
+
+/** 保存 Shell 与系统持久环境，macOS 登录任务只调用原生 setenv，不转接 MCP。 */
+export function persistEnvironment(key, {
+  home = homedir(), platform = process.platform, env = process.env, execute = execFileSync,
+  expected = inspectEnvironment({ home, platform, env }),
+} = {}) {
+  requireKey(key);
+  const prepared = expected.map(entry => {
+    let content;
+    if (entry.path.endsWith('.plist')) {
+      const args = ['/bin/launchctl', 'setenv', ENV_KEY, key].map(value => `    <string>${xml(value)}</string>`).join('\n');
+      content = `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>\n  <key>Label</key><string>com.ultrastiching.environment</string>\n  <key>ProgramArguments</key><array>\n${args}\n  </array>\n  <key>RunAtLoad</key><true/>\n</dict></plist>\n`;
+    } else if (entry.path.endsWith('.conf')) {
+      // systemd environment.d 用 $$ 表示字面美元符号；其他字符按双引号规则转义。
+      const value = key.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('`', '\\`').replaceAll('$', () => '$$');
+      content = `${ENV_KEY}="${value}"\n`;
+    } else content = shellContent(entry.content, key);
+    return { entry, content };
+  });
+  for (const { entry } of prepared) if (snapshot(entry.path).digest !== entry.digest) throw new Error(`${entry.path} 在检查后发生变化，未覆盖。`);
+  const updated = [];
+  try {
+    for (const { entry, content } of prepared) if (save(entry, content)) updated.push(entry.path);
+    updateSessionEnvironment(key, { platform, env, execute });
+  } catch (error) {
+    error.updated_paths = updated;
+    const diagnostic = error.toDiagnostic;
+    error.toDiagnostic = () => ({ ...(diagnostic ? diagnostic() : { message: error.message }), updated_paths: updated });
+    throw error;
+  }
+  return { synchronized: true, updated_paths: updated, restart_required: true };
+}