ultrastiching-cli 0.1.1 → 0.2.0

package/README.md

@@ -2,20 +2,36 @@
 
 UltraStiching 数据 API 的 Node.js 命令行入口。要求 Node.js 22.12 或更高版本。实现 `doctor`、`list`、`info`、`call`、`arrow`、`ws newsflash`、`datasets` 和 `db`。本地数据库与 Python SDK 共用 DuckDB 文件，同步与校验行为见下文。14 个预设的数据完整同步仍待服务端验证，现阶段不把单次成功响应当作完整历史。
 
-发行包名为 `ultrastiching-cli`，安装后的命令为 `ultrastiching`。内部源码目录和现有配置名称保持原样。
+发行包名为 `ultrastiching-cli`，安装后的命令为 `ultrastiching`。统一 Key 变量为 `ULTRASTICHING_API_KEY`，CLI、Python SDK 和 Claude Code 请求头助手其次读取 `~/.ultrastiching/credentials.env`。安装器自动把已有文件 Key 同步到持久环境，供 Codex 原生 HTTP MCP 使用；数据库路径与地址变量保持既有约定。
+
+## 凭据与统一安装
+
+通过 [统一安装指导](../docs/agent-setup.md) 安装时，已有 CLI 只检查更新，覆盖前确认。以下新增命令不发起业务请求：
+
+```bash
+ultrastiching --version
+ultrastiching auth status
+ultrastiching auth sync
+ultrastiching auth configure
+# 主动替换 Key，需确认：ultrastiching auth configure --replace
+```
+
+`auth status` 只输出是否配置及来源。`auth sync` 由安装器自动调用：环境变量没有值时，从已有凭据文件同步到当前进程和持久环境。`auth configure` 已有 Key 时不重复输入；缺失时在本机终端隐藏输入一次，同时保存私有文件和持久环境。`--replace` 确认一次后更换两处的 Key。macOS 更新 Shell、launchd 环境和登录恢复任务；Windows 更新用户环境；Linux 更新 Shell 和用户 environment.d，有会话总线时同步服务启动环境。含 Key 的 POSIX 配置使用 0600，Windows 凭据文件使用私有 ACL。保存后完全退出并重启客户端。不要在 Agent 对话中填写 Key。`ultrastiching mcp headers` 只供 MCP 客户端调用，stdout 含鉴权头，Agent 不应执行或打印该命令的输出。
+
+本版为 0.2.0，支持共享凭据配置和安装器自动同步。
 
 ## 安装与离线发现
 
 从 npm 安装指定版本：
 
 ```bash
-npm install -g ultrastiching-cli@0.1.1
+npm install -g ultrastiching-cli@0.2.0
 ultrastiching --help
 ultrastiching list --search 交易日历
 ultrastiching info plasma_trade_cal
 ```
 
-`list` 和 `info` 使用随包携带的目录，不需要 API Key，不发送业务请求。也可安装维护者提供的包：`npm install -g ./ultrastiching-cli-0.1.1.tgz`。源码环境使用下面的安装方式：
+`list` 和 `info` 使用随包携带的目录，不需要 API Key，不发送业务请求。也可安装维护者提供的包：`npm install -g ./ultrastiching-cli-0.2.0.tgz`。源码环境使用下面的安装方式：
 
 ```bash
 cd meridian-cli
@@ -38,7 +54,7 @@ ultrastiching db export --table concept_index_daily --path concept.csv
 
 `call` 按仓库根目录 `registry/endpoints.json` 中的真实路径和 payload 模板发起请求。参数名称与 Python SDK 方法一致：`--start-date` 和 `--start_date` 均映射到 `start_date`。`--args` 接收参数名到值的 JSON 对象；同名命令行参数覆盖 `--args` 中的值。对于请求模板中的 `symbols`，单个字符串会成为单元素数组，逗号分隔的字符串会拆为数组。其他参数依注册表中的类型解析；复杂值可直接在 `--args` 中使用 JSON 数组或对象。`info` 输出完整的字段、来源与验证标记，使用前请核对该端点的实际请求形状。
 
-API Key 优先级为 `--key`、`MERIDIAN_API_KEY`、`~/.meridian/credentials.env`。文件回退要求用户所有、权限为 `0600` 或更严，且 `~/.meridian` 不可由其他用户写入。HTTP 地址优先级为 `--base-url`、`MERIDIAN_BASE_URL`、`https://api.ultrastiching.com`。WebSocket 默认使用注册表中的 `wss://ws.ultrastiching.com`，可用 `--ws-base-url` 覆盖。`doctor` 默认只查本地 Key、注册表及 DuckDB 依赖/版本；`doctor --probe` 在有 Key 时调用一个已登记的示例端点，因而会产生真实 API 请求。
+API Key 优先级为 `--key`、`ULTRASTICHING_API_KEY`、`~/.ultrastiching/credentials.env`。文件回退要求用户所有、权限为 `0600` 或更严，且 `~/.ultrastiching` 不可由其他用户写入。HTTP 地址优先级为 `--base-url`、`MERIDIAN_BASE_URL`、`https://api.ultrastiching.com`。WebSocket 默认使用注册表中的 `wss://ws.ultrastiching.com`，可用 `--ws-base-url` 覆盖。`doctor` 默认只查本地 Key、注册表及 DuckDB 依赖/版本；`doctor --probe` 在有 Key 时调用一个已登记的示例端点，因而会产生真实 API 请求。
 
 HTTP 结果按服务端 `Content-Type` 处理：JSON 输出到终端，已知数组超过 500 行时自动写入 `meridian-out/`；Arrow IPC 原始字节写入 `--out` 指定文件，未指定时写入 `meridian-out/`。`call` 和 `arrow` 保留原始 IPC，不解码。`db sync` 使用 `apache-arrow` 解码表格，并使用 `@duckdb/node-api` 写入与 Python 相同的数据库结构；WebSocket 使用 `ws` 在握手时发送 Bearer 头；Node 内建 `fetch` 负责 HTTP。三者是包的直接依赖。`npm pack` 时 `prepack` 从仓库根复制端点及数据集注册表快照到包内；发布前必须先运行生成链并核对快照。
 
@@ -46,10 +62,10 @@ HTTP 结果按服务端 `Content-Type` 处理：JSON 输出到终端，已知数
 
 默认不自动重试。HTTP 非 2xx 错误保留状态、服务端 `error`、`X-Meridian-Request-ID` 和原始响应体；终端输出仅替换当前 API Key 的字面值。不要把含敏感信息的完整原始错误对象转存到公开日志。离线测试运行 `npm test`；设置 `MERIDIAN_TEST_PYTHON` 和可选的 `MERIDIAN_TEST_PYTHON39` 为装有本仓库 Python SDK 及 DuckDB 的解释器路径，可额外执行跨语言同文件测试。未配置时只跳过跨语言用例。尚未用测试或正式环境 Key 验收真实端点、WebSocket 和服务限制。
 
-环境变量与私有凭据文件任选一种；CLI 不会自动加载项目 `.env`，`.env.example` 只是模板。用户在 CLI 执行环境配置现有 `MERIDIAN_API_KEY`，或使用前文说明的私有凭据文件。直接调用业务接口前需要配置有效 Key：
+环境变量与私有凭据文件任选一种；CLI 不会自动加载项目 `.env`，`.env.example` 只是模板。用户在 CLI 执行环境配置现有 `ULTRASTICHING_API_KEY`，或使用前文说明的私有凭据文件。直接调用业务接口前需要配置有效 Key：
 
 ```bash
-export MERIDIAN_API_KEY='<your-api-key>'
+export ULTRASTICHING_API_KEY='<your-api-key>'
 ultrastiching call tracer_newsflash --limit 20
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultrastiching-cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "UltraStiching data API command line client",
   "type": "module",
   "bin": {

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

@@ -1,6 +1,5 @@
-import { closeSync, fstatSync, lstatSync, openSync, readFileSync, constants } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { requireKey, resolveCredential } from './credentials.js';
 
 export const DEFAULT_BASE_URL = 'https://api.ultrastiching.com';
 
@@ -25,49 +24,10 @@ export function resolveBaseUrl(explicit, env = process.env) {
   return normalizeOrigin(explicit !== undefined ? explicit : env.MERIDIAN_BASE_URL !== undefined ? env.MERIDIAN_BASE_URL : DEFAULT_BASE_URL);
 }
 
-function credentialFile(home) {
-  if (process.platform === 'win32' || typeof process.getuid !== 'function' || constants.O_NOFOLLOW === undefined) {
-    throw new Error('Credential file fallback requires POSIX ownership and no-follow file access; use --key or MERIDIAN_API_KEY');
-  }
-  const dir = join(home, '.meridian');
-  let dirInfo;
-  try { dirInfo = lstatSync(dir); } catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
-  if (!dirInfo.isDirectory() || dirInfo.uid !== process.getuid() || (dirInfo.mode & 0o022)) {
-    throw new Error('~/.meridian must be an owned directory not writable by others');
-  }
-  let fd;
-  try {
-    fd = openSync(join(dir, 'credentials.env'), constants.O_RDONLY | constants.O_NOFOLLOW | (constants.O_NONBLOCK ?? 0));
-  } catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
-  try {
-    const info = fstatSync(fd);
-    if (!info.isFile() || info.uid !== process.getuid() || (info.mode & 0o077) || info.size > 65536) {
-      throw new Error('~/.meridian/credentials.env must be an owned regular file with mode 0600 or stricter, at most 64 KiB');
-    }
-    const content = readFileSync(fd, 'utf8');
-    let found;
-    for (const source of content.split(/\r?\n/)) {
-      let line = source.trim();
-      if (!line || line.startsWith('#')) continue;
-      if (line.startsWith('export ')) line = line.slice(7).trimStart();
-      const separator = line.indexOf('=');
-      const name = separator < 0 ? line : line.slice(0, separator).trim();
-      if (name !== 'MERIDIAN_API_KEY') continue;
-      if (separator < 0 || found !== undefined) throw new Error('Invalid or duplicate MERIDIAN_API_KEY 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 MERIDIAN_API_KEY in credentials.env');
-        value = value.slice(1, -1);
-      }
-      found = value;
-    }
-    return found;
-  } finally { closeSync(fd); }
-}
-
+/** 显式参数只影响本次调用；自动读取统一走共享凭据模块。 */
 export function resolveKey(explicit, { env = process.env, home = homedir(), optional = false } = {}) {
-  const key = explicit !== undefined ? explicit : Object.hasOwn(env, 'MERIDIAN_API_KEY') ? env.MERIDIAN_API_KEY : credentialFile(home);
+  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: use --key, MERIDIAN_API_KEY, or ~/.meridian/credentials.env');
-  return singleLine('API Key', key);
+  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/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 };
+}

package/src/main.js

@@ -5,9 +5,18 @@ import { resolveBaseUrl, resolveKey } from './config.js';
 import { callByName, redactKey } from './http.js';
 import { buildPayload, endpoint, loadRegistry, parseParameter, searchEndpoints } from './registry.js';
 import { streamNewsflash } from './websocket.js';
+import { credentialStatus, configureCredential, syncCredentialEnvironment, mcpHeaders } from './auth.js';
+import { readFileSync } from 'node:fs';
+
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 
 const HELP = `ultrastiching — UltraStiching data API CLI
 
+  ultrastiching --version
+  ultrastiching auth status
+  ultrastiching auth sync [--from-file]
+  ultrastiching auth configure [--replace]
+  ultrastiching mcp headers  (MCP client only; stdout contains credentials)
   ultrastiching doctor [--probe]
   ultrastiching list [--search text] [--binary] [--verbose]
   ultrastiching info <endpoint>
@@ -70,7 +79,25 @@ function rowCount(data) {
 export async function main(argv, { write = (line) => process.stdout.write(line), fetchImpl, socketFactory } = {}) {
   const { flags, positional } = parseArgs(argv);
   const [command, name] = positional;
+  if (flags.version && !command) { assertFlags(flags, new Set(['version'])); write(`${VERSION}\n`); return; }
   if (!command || flags.help) { write(HELP); return; }
+  if (command === 'auth') {
+    if (positional.length !== 2) throw new Error('Use ultrastiching auth status|sync|configure');
+    assertFlags(flags, new Set(name === 'configure' ? ['replace', 'compact'] : name === 'sync' ? ['from_file', 'compact'] : ['compact']));
+    if (name === 'configure') {
+      if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error('请在交互式终端运行 ultrastiching auth configure；Key 不能从参数或管道传入。');
+      emit(write, await configureCredential({ replace: !!flags.replace }), flags.compact);
+    } else if (name === 'status') emit(write, credentialStatus(), flags.compact);
+    else if (name === 'sync') emit(write, syncCredentialEnvironment({ fromFile: !!flags.from_file }), flags.compact);
+    else throw new Error('Use ultrastiching auth status|sync|configure');
+    return;
+  }
+  if (command === 'mcp') {
+    assertFlags(flags, new Set());
+    if (name !== 'headers' || positional.length !== 2) throw new Error('Use ultrastiching mcp headers (MCP client only)');
+    write(`${JSON.stringify(mcpHeaders())}\n`);
+    return;
+  }
   if (command === 'list') {
     assertFlags(flags, new Set(['search', 'binary', 'verbose', 'compact']));
     const items = searchEndpoints({ search: flags.search === undefined ? '' : requireValue(flags, 'search'), binary: !!flags.binary });

package/src/prompt.js

@@ -0,0 +1,42 @@
+import { emitKeypressEvents } from "node:readline";
+
+/** 本机输入隐藏 Key；取消时恢复终端状态，凭据不进入参数或 Shell 历史。 */
+export function hiddenKey(input = process.stdin, output = process.stdout) {
+  emitKeypressEvents(input);
+  const previousRaw = input.isRaw;
+  input.setRawMode(true);
+  input.resume();
+  return new Promise((resolve, reject) => {
+    let value = "";
+    const finish = (error) => {
+      input.off("keypress", onKey); input.setRawMode(Boolean(previousRaw)); input.pause(); output.write("\n");
+      if (error) reject(error); else resolve(value.trim());
+    };
+    const onKey = (text, key = {}) => {
+      if (key.ctrl && key.name === "c") return finish(new Error("已取消，未保存。"));
+      if (key.name === "return" || key.name === "enter") return finish();
+      if (key.name === "backspace") value = Array.from(value).slice(0, -1).join("");
+      else if (text && !key.ctrl && !key.meta && !/[\x00-\x1f\x7f]/u.test(text)) value += text;
+    };
+    input.on("keypress", onKey);
+    output.write("粘贴 ultrastiching 数据 API Key（输入隐藏，Enter 确认，Ctrl+C 取消）：");
+  });
+}
+
+/** 拒绝占位、控制字符和误贴的空白；不臆测服务端 Key 的格式或长度。 */
+export function validateKey(key) {
+  if (!key || /[\s\x00-\x1f\x7f]/u.test(key) || key === "YOUR_ULTRASTICHING_DATA_API_KEY") throw new Error("请填写完整的数据 API Key，不能包含空格或换行；未保存。");
+}
+
+/** 覆盖前展示用途；默认拒绝，取消或非交互环境不会隐式接受。 */
+export async function confirmChange(message, input = process.stdin, output = process.stdout) {
+  if (!input.isTTY || !output.isTTY) throw new Error('请在交互式终端确认覆盖；Agent 应先向用户展示变更并取得确认。');
+  const { createInterface } = await import('node:readline');
+  const prompt = createInterface({ input, output });
+  const reply = await new Promise(resolve => {
+    prompt.question(message + ' [y/N] ', resolve);
+    prompt.once('SIGINT', () => resolve(''));
+  });
+  prompt.close();
+  return /^(y|yes)$/iu.test(reply.trim());
+}