@unscientificjszhai/howto 1.0.0 → 1.0.1

package/README.CN.md

@@ -53,6 +53,10 @@ howto --init
 
 初始化程序会把用户级配置写入 `~/.howto/config.json`。
 
+初始化和占位符输入支持按完整字符退格，包括 emoji 和组合字符；Alt/Meta 快捷键不会作为文本写入配置字段。
+按键释放事件不会触发确认、取消、导航或再次删除；一次 Enter 的按下和释放不能跳过最终确认。
+终端将键盘文本与 Enter 合并送达时，输入仍按顺序处理；当前步骤结束后，同批剩余按键不能跳过下一页确认。粘贴中的换行保留为数据。
+
 > [!NOTE]
 > OpenAI API key 可以为空，以支持本地 OpenAI 兼容服务。Gemini 必须提供非空 API key。
 
@@ -68,6 +72,10 @@ howto 找到最近7天修改的文件 .
 howto use git 看看上周的提交
 ```
 
+`use` 会在处理环境变量赋值及已支持的 `sudo`/`env` 选项后，精确核对首个实际工具。例如 `sudo -u root git status` 符合 `use git`，`sudo -u git id` 则不符合。`sudo`/`env` 的未知选项或缺少选项参数、动态执行前缀及复杂 shell 结构会被拒绝。这个约束只针对首段的工具，不限制后续命令段。
+
+已声明的占位符可以出现在首工具之后，例如 `git log -n {{count}}`；工具名及其之前的前缀必须能在填写占位符前确定。模板分析不会修改最终命令原文。
+
 不进入交互 UI，只打印候选命令：
 
 ```bash
@@ -79,6 +87,7 @@ howto --print 列出最大的文件 /var/log
 ```text
 howto [options] [use <command>] <question> [<argument>...]
 howto --init
+howto --version
 ```
 
 示例：
@@ -93,6 +102,7 @@ howto --ai-provider openai --print 列出监听的端口
 参数：
 
 - `--init` - 启动交互式 provider 配置，并保存 `~/.howto/config.json`。
+- `--version` - 单独使用，输出当前包版本号并成功退出；无需配置或 TTY，不调用 AI。
 - `--print` - 打印已校验的命令候选项并退出，不执行命令。
 - `--ai-provider <openai|gemini>` - 选择 AI provider。
 - `--gemini-api-key <key>` - 提供 Gemini API key。
@@ -125,16 +135,22 @@ howto "explain this flag" -- --force
 3. `~/.howto/config.json`
 4. 内置默认值
 
+配置路径使用绝对路径形式的 `HOME`。`HOME` 缺失或为空白时，howto 从系统用户信息查询主目录；非空相对 `HOME` 或系统查询失败会在创建文件前返回配置错误。
+
 对每个配置项，优先级中第一个已配置的来源生效：
 
 - `--ai-provider` / `HOWTO_AI_PROVIDER` / `aiProvider` - `openai` 或 `gemini`；无默认值。
 - `--gemini-api-key` / `HOWTO_GEMINI_API_KEY` / `geminiApiKey` - Gemini API key；Gemini 必填。
 - `--gemini-model` / `HOWTO_GEMINI_MODEL` / `geminiModel` - Gemini 模型；默认 `gemini-3.1-flash-lite`。
-- `--openai-api-url` / `HOWTO_OPENAI_API_URL` / `openaiApiUrl` - OpenAI 兼容 base URL；默认使用 OpenAI SDK 默认值。
+- `--openai-api-url` / `HOWTO_OPENAI_API_URL` / `openaiApiUrl` - OpenAI 兼容 base URL；默认 `https://api.openai.com/v1`。
 - `--openai-api-key` / `HOWTO_OPENAI_API_KEY` / `openaiApiKey` - OpenAI API key；默认为空字符串以支持本地服务。
 - `--openai-model` / `HOWTO_OPENAI_MODEL` / `openaiModel` - OpenAI 模型；默认 `gpt-5.4-mini`。
 - `--structured-output` / `HOWTO_STRUCTURED_OUTPUT` / `structuredOutput` - 使用 provider schema 结构化输出；默认 `true`。
 
+请求地址和 Gemini API 模式由 howto 显式设置。`OPENAI_BASE_URL`、`GOOGLE_GEMINI_BASE_URL`、`GOOGLE_VERTEX_BASE_URL` 及 Google SDK 的 Vertex/Enterprise 模式环境开关不会改写它们。Gemini 使用官方 `generativelanguage.googleapis.com` 的 `v1beta` API；自定义 OpenAI 地址请使用上述 HOWTO 配置项。
+
+OpenAI 的 Authorization 使用 howto 配置的 key，空白 key 时不发送该请求头；`OPENAI_CUSTOM_HEADERS` 中的 Authorization 不会覆盖此选择。交互模式收到 OpenAI 限流或临时服务错误时直接报错，不自动重试，以保证取消后能及时退出；`--print` 保留 SDK 默认重试行为。
+
 示例：
 
 ```bash
@@ -149,14 +165,27 @@ howto --print "show current branch"
 
 - AI 响应是符合命令 schema 的有效 JSON；
 - 响应包含一到三个候选项；
-- 所有占位符使用 `{{name}}` 语法，并且声明与引用一致；
+- 所有占位符使用 `{{name}}` 语法，并且声明与引用一致；同一候选中名称只声明一次，多处引用共用一次输入；
 - `use <command>` 候选项在保守处理前缀后，明确以指定工具开头；
 - 明显危险的命令需要输入 `EXECUTE` 才能继续执行；大小写不敏感。
 
 危险命令检测当前覆盖递归破坏性 `rm`、磁盘和文件系统操作、大范围递归权限变更、下载脚本后直接交给 shell 执行、高影响包管理器操作以及服务变更等高风险模式。
 
+本地分析会处理字面引号、绝对命令路径及已支持的 `sudo`/`env` 选项，并检查各命令段。遇到未知 wrapper 选项、动态执行前缀或超出解析范围的 shell 语法时，也会要求输入 `EXECUTE`，避免把无法判断的命令直接视为安全。
+
+数字文件描述符中的续行因 shell 方言差异要求额外确认，并被 `use` 校验拒绝。风险分析会识别 `./../important` 和 `///dev/disk2` 等含冗余 `.` 或斜杠的高风险路径，不折叠 `..`，也不修改实际执行命令。
+
+`env` 赋值中的数字开头、连字符或点名称也会正确识别，继续检查后面的实际命令。npm 全局安装/卸载的正式别名（如 `i`、`add`、`un`、`unlink`）使用同样的危险确认；不能确定的等价缩写也要求额外确认。
+前导 `NAME+=value` 因 shell 方言差异要求额外确认，并被 `use` 校验拒绝；未受单引号或反斜杠保护的美元表达式保守按动态值判断。npm 的 `install-test`、`installTest`、`it` 复合安装及其缩写也纳入全局安装确认。
+
+Homebrew 的 `rm/uninstal` 卸载别名，以及 yum/dnf 的 `update/erase` 升级或卸载入口，也使用相同的危险确认。各工具的动作分别识别，`apt update`、`brew update/up` 的索引更新不按系统软件升级处理。
+
+一次交互调用中只要识别到 bracketed paste（包括自动初始化阶段），本次调用就永久改为输出最终命令供手动运行。最终确认页按 Enter 只输出命令，终端会显示说明；返回候选选择或调整终端大小都不会恢复执行权限。全程键盘输入仍使用原有的 Enter 或 `EXECUTE` 确认。
+
+跨越终端视图隐藏阶段的粘贴会整块丢弃。这些规则针对已识别的 bracketed-paste 输入；终端协议无法认证任意粘贴按键或内容中的结束标记。执行限制针对 howto 自身启动候选命令的行为。
+
 > [!WARNING]
-> 未被标记为危险并不表示命令一定安全。本地检查只会对已知高风险模式增加确认步骤，并不能证明命令安全。
+> 未被标记为危险并不表示命令一定安全。本地检查会对已知高风险模式及无法分析的语法增加确认步骤，并不能证明命令安全。
 
 ## 开发
 

package/README.md

@@ -53,6 +53,10 @@ howto --init
 
 The initializer writes a user-level config file at `~/.howto/config.json`.
 
+Initialization and placeholder input delete complete characters on Backspace, including emoji and combining sequences. Alt/Meta shortcuts are not inserted into configuration fields as text.
+Key release events never confirm, cancel, navigate, or delete; pressing and releasing Enter once cannot skip the final confirmation.
+Keyboard text and Enter are processed in order even when the terminal delivers them together. Once a step finishes, remaining keys in that batch cannot skip the next confirmation screen. Newlines inside paste remain data.
+
 > [!NOTE]
 > OpenAI API keys may be empty for local OpenAI-compatible services. Gemini requires a non-empty API key.
 
@@ -68,6 +72,10 @@ Limit candidates to a specific tool:
 howto use git "show commits from last week"
 ```
 
+`use` checks the first actual tool exactly after environment assignments and supported `sudo`/`env` options. For example, `sudo -u root git status` satisfies `use git`, while `sudo -u git id` does not. Unknown wrapper options, missing option values, dynamic executable prefixes, and complex shell structures are rejected. This constraint applies to the first command segment, not subsequent segments.
+
+Declared placeholders may appear after the first tool, as in `git log -n {{count}}`. The tool name and preceding prefixes must be identifiable before placeholder resolution. Template analysis does not change the command text.
+
 Print command candidates without entering the interactive UI:
 
 ```bash
@@ -79,6 +87,7 @@ howto --print "list the largest files" /var/log
 ```text
 howto [options] [use <command>] <question> [<argument>...]
 howto --init
+howto --version
 ```
 
 Examples:
@@ -93,6 +102,7 @@ howto --ai-provider openai --print "show listening ports"
 Options:
 
 - `--init` - start interactive provider setup and save `~/.howto/config.json`.
+- `--version` - use alone to print the current package version and exit successfully; requires no configuration or TTY and makes no AI request.
 - `--print` - print validated command candidates and exit without executing.
 - `--ai-provider <openai|gemini>` - select the AI provider.
 - `--gemini-api-key <key>` - provide a Gemini API key.
@@ -125,16 +135,22 @@ Configuration is resolved in this order:
 3. `~/.howto/config.json`
 4. Built-in defaults
 
+The config path uses `HOME` when it is an absolute path. If `HOME` is missing or blank, howto queries the operating system for the user's home directory. A non-empty relative `HOME` or a failed system lookup produces a configuration error before any file is created.
+
 For each setting, the first configured source in that order wins:
 
 - `--ai-provider` / `HOWTO_AI_PROVIDER` / `aiProvider` - `openai` or `gemini`; no default.
 - `--gemini-api-key` / `HOWTO_GEMINI_API_KEY` / `geminiApiKey` - Gemini API key; required for Gemini.
 - `--gemini-model` / `HOWTO_GEMINI_MODEL` / `geminiModel` - Gemini model; default `gemini-3.1-flash-lite`.
-- `--openai-api-url` / `HOWTO_OPENAI_API_URL` / `openaiApiUrl` - OpenAI-compatible base URL; defaults to the OpenAI SDK default.
+- `--openai-api-url` / `HOWTO_OPENAI_API_URL` / `openaiApiUrl` - OpenAI-compatible base URL; defaults to `https://api.openai.com/v1`.
 - `--openai-api-key` / `HOWTO_OPENAI_API_KEY` / `openaiApiKey` - OpenAI API key; defaults to an empty string for local services.
 - `--openai-model` / `HOWTO_OPENAI_MODEL` / `openaiModel` - OpenAI model; default `gpt-5.4-mini`.
 - `--structured-output` / `HOWTO_STRUCTURED_OUTPUT` / `structuredOutput` - use provider schema structured output; default `true`.
 
+howto sets the request endpoint and Gemini API mode explicitly. `OPENAI_BASE_URL`, `GOOGLE_GEMINI_BASE_URL`, `GOOGLE_VERTEX_BASE_URL`, and the Google SDK's Vertex/Enterprise environment switches do not override them. Gemini uses the official `generativelanguage.googleapis.com` `v1beta` API. Use the HOWTO settings above for a custom OpenAI endpoint.
+
+OpenAI Authorization uses the key configured in howto and is omitted when that key is blank. Authorization in `OPENAI_CUSTOM_HEADERS` cannot override this choice. Interactive OpenAI requests report rate limits and temporary service errors without automatic retries so cancellation can exit promptly; `--print` keeps the SDK's default retry behavior.
+
 Example:
 
 ```bash
@@ -149,14 +165,27 @@ howto --print "show current branch"
 
 - the AI response is valid JSON matching the required command schema;
 - the response contains between one and three candidates;
-- all placeholders use `{{name}}` syntax and are declared consistently;
+- all placeholders use `{{name}}` syntax and are declared consistently, with each name declared once per candidate and repeated references sharing one input value;
 - `use <command>` candidates clearly start with the requested tool after conservative prefix handling;
 - obvious dangerous patterns require typing `EXECUTE` before they can run; matching is case-insensitive.
 
 Dangerous-command detection currently covers high-risk patterns such as recursive destructive `rm`, disk and filesystem operations, broad recursive permission changes, downloaded scripts piped into a shell, high-impact package manager operations, and service changes.
 
+Local analysis handles literal quoting, absolute command paths, and supported `sudo`/`env` options, and checks each command segment. Unknown wrapper options, dynamic executable prefixes, and shell syntax outside the supported subset also require `EXECUTE`, so an inconclusive analysis does not skip the additional confirmation.
+
+Line continuations within numeric file descriptors require additional confirmation and are rejected by `use` because shells interpret them differently. Risk analysis recognizes high-risk paths with redundant dots or slashes, such as `./../important` and `///dev/disk2`, without collapsing `..` or changing the command that runs.
+
+Assignments passed to `env` can use names starting with digits or containing hyphens or dots; the actual command after them is still checked. Official npm global install/uninstall aliases such as `i`, `add`, `un`, and `unlink` receive the same additional confirmation. Inconclusive abbreviations of those actions also require confirmation.
+Leading `NAME+=value` requires additional confirmation and is rejected by `use` because its meaning differs between shells. Dollar expressions outside single quotes or backslash protection are treated conservatively as dynamic values. Compound npm installs through `install-test`, `installTest`, `it`, and their abbreviations also receive global-install checks.
+
+Homebrew uninstall aliases such as `rm/uninstal`, and yum/dnf upgrade or removal commands such as `update/erase`, receive the same additional confirmation. Actions are interpreted separately for each tool; metadata updates through `apt update` and `brew update/up` are not classified as system package upgrades.
+
+If howto detects bracketed paste during an interactive run, including automatic initialization, that run permanently switches to printing the final command for manual execution. At final confirmation, Enter prints the command without running it, and the terminal shows an explanation. Returning to selection or resizing the terminal does not restore execution. Keyboard-only runs keep the usual Enter or `EXECUTE` confirmation.
+
+Paste spanning a hidden terminal view is discarded as a whole. These rules apply to recognized bracketed-paste input; the terminal protocol cannot authenticate arbitrary pasted keystrokes or embedded end markers. The execution restriction applies to howto's own command launch.
+
 > [!WARNING]
-> A command not flagged as dangerous is not guaranteed to be safe. The local checks add friction for known high-risk patterns; they do not prove command safety.
+> A command not flagged as dangerous is not guaranteed to be safe. The local checks add confirmation for known high-risk patterns and syntax they cannot analyze; they do not prove command safety.
 
 ## Development
 

package/THIRD_PARTY_NOTICES.md

@@ -7,10 +7,11 @@ Each dependency is distributed under its own license.
 
 | Package         | Version  | License    |
 | --------------- | -------- | ---------- |
-| `@google/genai` | `2.6.0`  | Apache-2.0 |
-| `ink`           | `7.0.4`  | MIT        |
-| `openai`        | `6.39.0` | Apache-2.0 |
-| `react`         | `19.2.6` | MIT        |
+| `@google/genai` | `2.18.0` | Apache-2.0 |
+| `ink`           | `7.1.1`  | MIT        |
+| `openai`        | `7.5.0`  | Apache-2.0 |
+| `react`         | `19.2.8` | MIT        |
+| `string-width`  | `8.2.2`  | MIT        |
 
 The package versions above reflect the installed dependency set at the time this notice
 was prepared. See each package's published npm artifact for its complete license text and

package/dist/ai/errors.js

@@ -1,30 +1,14 @@
+import { sanitizeUserVisibleErrorMessage } from "../user-visible-error.js";
 export class AiProviderError extends Error {
-    constructor(provider, model, cause) {
-        super(formatProviderError(provider, model, cause));
+    provider;
+    model;
+    constructor(provider, model) {
+        super(formatProviderError(provider, model));
         this.name = "AiProviderError";
         this.provider = provider;
         this.model = model;
     }
 }
-function formatProviderError(provider, model, cause) {
-    const summary = sanitizeErrorSummary(cause);
-    return `AI provider request failed (provider: ${provider}, model: ${model}): ${summary}`;
-}
-function sanitizeErrorSummary(cause) {
-    const rawMessage = getErrorMessage(cause);
-    const singleLine = rawMessage.replace(/\s+/g, " ").trim();
-    const redacted = singleLine
-        .replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [redacted]")
-        .replace(/(api[-_ ]?key["'\s:=]+)[A-Za-z0-9._~+/=-]+/gi, "$1[redacted]")
-        .replace(/(authorization["'\s:=]+)[A-Za-z0-9._~+/=-]+/gi, "$1[redacted]");
-    return redacted.length > 220 ? `${redacted.slice(0, 217)}...` : redacted;
-}
-function getErrorMessage(cause) {
-    if (cause instanceof Error && cause.message.trim() !== "") {
-        return cause.message;
-    }
-    if (typeof cause === "string" && cause.trim() !== "") {
-        return cause;
-    }
-    return "unknown error";
+function formatProviderError(provider, model) {
+    return `AI provider request failed (provider: ${provider}, model: ${sanitizeUserVisibleErrorMessage(model)})`;
 }

package/dist/ai/gemini.js

@@ -1,40 +1,80 @@
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-import { GoogleGenAI } from "@google/genai";
+import { GoogleGenAI, } from "@google/genai";
 import { COMMAND_GENERATION_SCHEMA } from "./command-schema.js";
 import { AiProviderError } from "./errors.js";
 export class GeminiCommandProvider {
+    client;
+    model;
     constructor(config) {
         this.model = config.model;
-        this.client = new GoogleGenAI({ apiKey: config.apiKey });
+        this.client = new GoogleGenAI(buildGeminiClientOptions(config));
     }
-    generateCommands(request) {
-        return __awaiter(this, void 0, void 0, function* () {
-            try {
-                const response = yield this.client.models.generateContent(buildGeminiGenerateContentRequest(this.model, request));
-                const rawText = response.text;
-                if (rawText === undefined || rawText.trim() === "") {
-                    throw new Error("provider returned an empty response");
-                }
-                return { rawText };
-            }
-            catch (error) {
-                throw new AiProviderError("gemini", this.model, error);
-            }
-        });
+    async generateCommands(request, signal) {
+        let rawText;
+        try {
+            const response = await this.client.models.generateContent(buildGeminiGenerateContentRequest(this.model, request, signal));
+            rawText = extractGeminiResponseText(response);
+        }
+        catch {
+            throw new AiProviderError("gemini", this.model);
+        }
+        if (rawText === undefined || rawText.trim() === "") {
+            throw new AiProviderError("gemini", this.model);
+        }
+        return { rawText };
     }
 }
-export function buildGeminiGenerateContentRequest(model, request) {
+export function extractGeminiResponseText(response) {
+    // SDK 的 text getter 会记录未知字段；这里只读取首候选的已知字段。
+    const candidates = asRecord(response)?.candidates;
+    if (!Array.isArray(candidates) || candidates.length === 0)
+        return undefined;
+    const parts = asRecord(asRecord(candidates[0])?.content)?.parts;
+    if (!Array.isArray(parts) || parts.length === 0)
+        return undefined;
+    let text = "";
+    let hasText = false;
+    for (const value of parts) {
+        const part = asRecord(value);
+        if (part === undefined)
+            return undefined;
+        const thought = part.thought;
+        if (Object.hasOwn(part, "thought") && typeof thought !== "boolean")
+            return undefined;
+        if (thought === true)
+            continue;
+        if (!Object.hasOwn(part, "text"))
+            continue;
+        const partText = part.text;
+        if (typeof partText !== "string")
+            return undefined;
+        hasText = true;
+        text += partText;
+    }
+    return hasText ? text : undefined;
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+export function buildGeminiClientOptions(config) {
+    return {
+        apiKey: config.apiKey,
+        enterprise: false,
+        vertexai: false,
+        apiVersion: "v1beta",
+        httpOptions: { baseUrl: "https://generativelanguage.googleapis.com/" },
+    };
+}
+export function buildGeminiGenerateContentRequest(model, request, signal) {
     return {
         model,
         contents: request.userPrompt,
-        config: Object.assign({ systemInstruction: request.systemPrompt, responseMimeType: "application/json" }, (request.structuredOutput ? { responseJsonSchema: COMMAND_GENERATION_SCHEMA } : {})),
+        config: {
+            systemInstruction: request.systemPrompt,
+            responseMimeType: "application/json",
+            ...(signal === undefined ? {} : { abortSignal: signal }),
+            ...(request.structuredOutput ? { responseJsonSchema: COMMAND_GENERATION_SCHEMA } : {}),
+        },
     };
 }

package/dist/ai/openai.js

@@ -1,47 +1,55 @@
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
 import OpenAI from "openai";
 import { COMMAND_GENERATION_SCHEMA } from "./command-schema.js";
 import { AiProviderError } from "./errors.js";
 export class OpenAiCommandProvider {
+    client;
+    model;
     constructor(config) {
         this.model = config.model;
-        this.client = new OpenAI(buildOpenAiClientOptions(config));
+        try {
+            this.client = new OpenAI(buildOpenAiClientOptions(config));
+        }
+        catch {
+            // SDK 初始化异常可能含自定义请求头原值，与请求失败使用同一固定错误边界。
+            throw new AiProviderError("openai", this.model);
+        }
     }
-    generateCommands(request) {
-        return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
-            try {
-                const response = yield this.client.chat.completions.create(buildOpenAiChatCompletionRequest(this.model, request));
-                const rawText = (_b = (_a = response.choices[0]) === null || _a === void 0 ? void 0 : _a.message) === null || _b === void 0 ? void 0 : _b.content;
-                if (rawText === undefined || rawText === null || rawText.trim() === "") {
-                    throw new Error("provider returned an empty response");
-                }
-                return { rawText };
-            }
-            catch (error) {
-                throw new AiProviderError("openai", this.model, error);
-            }
-        });
+    async generateCommands(request, signal) {
+        let rawText;
+        try {
+            const parameters = buildOpenAiChatCompletionRequest(this.model, request);
+            // SDK 重试等待不响应取消；交互请求关闭自动重试，避免取消后残留计时器。
+            const response = signal === undefined
+                ? await this.client.chat.completions.create(parameters)
+                : await this.client.chat.completions.create(parameters, { signal, maxRetries: 0 });
+            rawText = response.choices[0]?.message?.content;
+        }
+        catch {
+            throw new AiProviderError("openai", this.model);
+        }
+        if (typeof rawText !== "string" || rawText.trim() === "") {
+            throw new AiProviderError("openai", this.model);
+        }
+        return { rawText };
     }
 }
 export function buildOpenAiClientOptions(config) {
+    const baseURL = config.baseUrl || "https://api.openai.com/v1";
     if (config.apiKey.trim() !== "") {
         return {
             apiKey: config.apiKey,
-            baseURL: config.baseUrl,
+            baseURL,
+            logLevel: "off",
+            // 最终认证头必须覆盖 SDK 隐式读取的 OPENAI_CUSTOM_HEADERS。
+            defaultHeaders: {
+                Authorization: `Bearer ${config.apiKey}`,
+            },
         };
     }
     return {
         apiKey: "howto-empty-api-key",
-        baseURL: config.baseUrl,
+        baseURL,
+        logLevel: "off",
         defaultHeaders: {
             Authorization: null,
         },

package/dist/cli.js

@@ -13,12 +13,14 @@ const VALUE_OPTIONS = new Set([
     "--openai-model",
     "--structured-output",
 ]);
-const BOOLEAN_OPTIONS = new Set(["--print", "--init"]);
+const BOOLEAN_OPTIONS = new Set(["--print", "--init", "--version"]);
 export const USAGE = `Usage: howto [options] [use <command>] <question> [<argument>...]
        howto --init
+       howto --version
 
 Options:
   --init
+  --version
   --print
   --ai-provider <openai|gemini>
   --gemini-api-key <key>
@@ -62,6 +64,12 @@ export function parseCliArgs(argv) {
         }
         positionals.push(token);
     }
+    if (options.version) {
+        if (argv.length !== 1) {
+            throw new CliParseError("--version must be used alone");
+        }
+        return { options, arguments: [] };
+    }
     return parsePositionals(options, positionals);
 }
 function readOptionValue(argv, optionIndex, optionName) {
@@ -106,6 +114,9 @@ function assignBooleanOption(options, optionName) {
         case "--init":
             options.init = true;
             return;
+        case "--version":
+            options.version = true;
+            return;
         default:
             throw new CliParseError(`unsupported option: ${optionName}`);
     }

package/dist/config-file.js

@@ -1,16 +1,6 @@
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-import { existsSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { homedir } from "node:os";
+import { mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join } from "node:path";
+import { userInfo } from "node:os";
 import { ConfigError } from "./config.js";
 const CONFIG_FILE_FIELDS = new Set([
     "aiProvider",
@@ -21,54 +11,110 @@ const CONFIG_FILE_FIELDS = new Set([
     "openaiModel",
     "structuredOutput",
 ]);
-export function getConfigFilePath(env = process.env) {
-    var _a;
-    return join((_a = env.HOME) !== null && _a !== void 0 ? _a : homedir(), ".howto", "config.json");
+export function getConfigFilePath(env = process.env, getSystemHomeDirectory = () => userInfo().homedir) {
+    const configuredHome = env.HOME;
+    let homeDirectory;
+    if (configuredHome === undefined || configuredHome.trim() === "") {
+        try {
+            homeDirectory = getSystemHomeDirectory();
+        }
+        catch {
+            throw new ConfigError("failed to resolve user home directory");
+        }
+        if (typeof homeDirectory !== "string" ||
+            homeDirectory.trim() === "" ||
+            !isAbsolute(homeDirectory)) {
+            throw new ConfigError("failed to resolve user home directory");
+        }
+    }
+    else {
+        homeDirectory = configuredHome;
+    }
+    const configDirectory = join(homeDirectory, ".howto");
+    assertAbsoluteConfigDirectory(configDirectory);
+    return join(configDirectory, "config.json");
 }
-export function readUserConfigFile() {
-    return __awaiter(this, arguments, void 0, function* (path = getConfigFilePath()) {
-        if (!existsSync(path)) {
+export async function readUserConfigFile(path = getConfigFilePath()) {
+    let contents;
+    try {
+        contents = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isFileNotFoundError(error)) {
             return {};
         }
-        let parsed;
-        try {
-            parsed = JSON.parse(yield readFile(path, "utf8"));
+        throw new ConfigError("failed to read user config file");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch {
+        throw new ConfigError("user config file is not valid JSON");
+    }
+    if (!isPlainObject(parsed)) {
+        throw new ConfigError("user config file must contain a JSON object");
+    }
+    const config = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (!CONFIG_FILE_FIELDS.has(key)) {
+            continue;
+        }
+        if (key === "structuredOutput") {
+            if (typeof value !== "string" && typeof value !== "boolean") {
+                throw new ConfigError(`config file field ${key} must be a boolean or string`);
+            }
+            config.structuredOutput = value;
+            continue;
         }
-        catch (error) {
-            throw new ConfigError(`failed to read config file ${path}: ${getParseErrorMessage(error)}`);
+        if (typeof value !== "string") {
+            throw new ConfigError(`config file field ${key} must be a string`);
         }
-        if (!isPlainObject(parsed)) {
-            throw new ConfigError(`config file ${path} must contain a JSON object`);
+        config[key] = value;
+    }
+    return config;
+}
+export async function writeUserConfigFile(config, path = getConfigFilePath()) {
+    const configDirectory = dirname(path);
+    assertAbsoluteConfigDirectory(configDirectory);
+    const serializedConfig = `${JSON.stringify(config, null, 2)}\n`;
+    let temporaryDirectory;
+    try {
+        await mkdir(configDirectory, { recursive: true });
+        temporaryDirectory = await mkdtemp(join(configDirectory, `.${basename(path)}-`));
+    }
+    catch {
+        throw new ConfigError("failed to save user config file");
+    }
+    const temporaryPath = join(temporaryDirectory, basename(path));
+    try {
+        await writeFile(temporaryPath, serializedConfig, { encoding: "utf8", mode: 0o600 });
+        await rename(temporaryPath, path);
+    }
+    catch {
+        try {
+            await rm(temporaryDirectory, { recursive: true, force: true });
         }
-        const config = {};
-        for (const [key, value] of Object.entries(parsed)) {
-            if (!CONFIG_FILE_FIELDS.has(key)) {
-                continue;
-            }
-            if (key === "structuredOutput") {
-                if (typeof value !== "string" && typeof value !== "boolean") {
-                    throw new ConfigError(`config file field ${key} must be a boolean or string`);
-                }
-                config.structuredOutput = value;
-                continue;
-            }
-            if (typeof value !== "string") {
-                throw new ConfigError(`config file field ${key} must be a string`);
-            }
-            config[key] = value;
+        catch {
+            throw new ConfigError("failed to save user config file and remove temporary config data");
         }
-        return config;
-    });
+        throw new ConfigError("failed to save user config file");
+    }
+    try {
+        await rm(temporaryDirectory, { recursive: true, force: true });
+    }
+    catch {
+        // 配置已经通过原子重命名提交；空临时目录清理失败不能把成功写入报告为失败。
+    }
 }
-export function writeUserConfigFile(config_1) {
-    return __awaiter(this, arguments, void 0, function* (config, path = getConfigFilePath()) {
-        yield mkdir(dirname(path), { recursive: true });
-        yield writeFile(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
-    });
+function assertAbsoluteConfigDirectory(path) {
+    if (!isAbsolute(path)) {
+        throw new ConfigError("config directory must be an absolute path");
+    }
 }
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function getParseErrorMessage(error) {
-    return error instanceof Error ? error.message : "invalid JSON";
+function isFileNotFoundError(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
 }