best-geo-test 0.1.0

package/dist/device.js

@@ -0,0 +1,43 @@
+import { randomUUID } from "node:crypto";
+import { hostname, platform } from "node:os";
+import { DEVICE_ID_PREFIX } from "./config.js";
+import { readConfig, updateConfig } from "./store.js";
+export { configDir } from "./store.js";
+/**
+ * 读取或生成安装实例 ID。
+ *
+ * 用随机 UUID 而不是硬件指纹（MAC、硬盘序列号）：指纹会把同一台机器的
+ * 不同用户绑成一个身份，也让用户没法通过重装来重置。
+ * 换电脑或删掉配置文件就是一个新实例，这是符合直觉的行为。
+ *
+ * 设备 ID 与凭据同在一份 config.json（设计文档 §6.4），
+ * 升级 CLI、换项目、开新对话都不变。
+ */
+/**
+ * 只读设备身份：不存在就返回 null，**不创建**。
+ *
+ * 给「不需要授权的调用」用（如 version --check）。用 deviceInfo() 的话，
+ * 一次纯粹的版本握手都会 mkdir + 写 config.json —— 在禁写用户目录的沙箱里，
+ * SKILL 的第一步就变成 HOST_PERMISSION_REQUIRED，而这一步本来根本不需要碰磁盘。
+ */
+export function peekDeviceId() {
+    const saved = readConfig()?.device;
+    return saved?.deviceId?.startsWith(DEVICE_ID_PREFIX) ? saved.deviceId : null;
+}
+export function deviceInfo() {
+    const current = {
+        // 服务端 device.name 是 varchar(50)，这里先截断，别让一个超长主机名把整次绑定弄失败
+        deviceName: hostname().slice(0, 50),
+        platform: `${platform()}-${process.arch}`,
+    };
+    const saved = readConfig()?.device;
+    if (saved?.deviceId?.startsWith(DEVICE_ID_PREFIX)) {
+        // 主机名和平台会变（改名、换架构），设备 ID 绝不能变：它变了就等于多出一台设备
+        if (saved.deviceName === current.deviceName && saved.platform === current.platform) {
+            return saved;
+        }
+        return updateConfig((config) => ({ ...config, device: { ...saved, ...current } })).device;
+    }
+    const created = { deviceId: `${DEVICE_ID_PREFIX}${randomUUID()}`, ...current };
+    return updateConfig((config) => ({ ...config, device: created })).device;
+}

package/dist/envelope.js

@@ -0,0 +1,26 @@
+/** 本地生成的 requestId，用于服务端没给时兜底 */
+export function localRequestId() {
+    return `cli_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+}
+export function ok(data, requestId = localRequestId()) {
+    return { ok: true, code: "OK", requestId, data };
+}
+export function fail(code, message, extra = {}) {
+    return {
+        ok: false,
+        code,
+        message,
+        requestId: extra.requestId ?? localRequestId(),
+        ...(extra.data == null ? {} : { data: extra.data }),
+        ...(extra.nextAction == null ? {} : { nextAction: extra.nextAction }),
+    };
+}
+/** 唯一的输出出口。任何地方都不要直接 console.log */
+export function emit(envelope) {
+    process.stdout.write(`${JSON.stringify(envelope)}\n`);
+    // 失败一律非零退出码。少了这一句，`best-geo apply x && echo 已写入` 会照常打印「已写入」——
+    // 模型和 shell 都会把一次失败当成成功
+    if (!envelope.ok) {
+        process.exitCode = 1;
+    }
+}

package/dist/host-error.js

@@ -0,0 +1,48 @@
+import { COMMAND_NAME } from "./config.js";
+import { fail } from "./envelope.js";
+import { configPath, LocalConfigError } from "./store.js";
+/**
+ * 把本机配置错误翻译成协议信封（设计文档 §6.4 / §12）。
+ *
+ * 分两类动作，不能混：
+ * - 宿主沙箱拒绝 → `request_host_approval`，让宿主用自己的机制申请**这一次**所需的最小权限；
+ * - 文件权限过宽或属主不对 → `ask_user`，这是用户机器上的状态，只有用户能修，宿主提权也没用。
+ *
+ * 两类都用 `HOST_PERMISSION_REQUIRED`：对模型来说「本机权限不对，暂时没法读写凭据」是同一件事，
+ * 该怎么做由 nextAction 决定，不靠模型去猜错误码的细分含义。
+ */
+export function toLocalConfigEnvelope(error, options) {
+    const path = configPath();
+    if (error.reason === "denied") {
+        return fail("HOST_PERMISSION_REQUIRED", `没有权限读写本机配置文件：${path}`, {
+            nextAction: {
+                type: "request_host_approval",
+                message: `Best GEO 需要读写 ${path} 来保存本机的设备身份和授权。请用当前工具自带的权限确认机制申请对该文件的读写权限后重试同一条命令，不要关闭整个沙箱，也不要让用户把密钥贴进对话。`,
+                capability: options.capability,
+                ...(options.retryCommand ? { command: options.retryCommand } : {}),
+            },
+        });
+    }
+    if (error.reason === "permissions_too_open" || error.reason === "not_owner") {
+        const fixHint = error.reason === "not_owner"
+            ? `该文件不属于当前系统用户，请让用户确认后删除或修正属主`
+            : `请让用户执行：chmod 600 ${path}`;
+        return fail("HOST_PERMISSION_REQUIRED", `本机配置文件权限不安全：${path}`, {
+            // 这里不能用 request_host_approval：宿主给再多权限也改不了文件自身的权限位
+            nextAction: { type: "ask_user", message: `${error.message}。${fixHint}，然后重试。` },
+        });
+    }
+    // corrupted 用 HOST_PERMISSION_REQUIRED 而不是 AUTH_REQUIRED：
+    // 后者在 SKILL 里的剧本是「由你自己执行 auth login」，而这里必须先删掉坏文件，
+    // 直接登录会再次读到同一个坏文件。归到「本机环境有问题，先修本机」这一类才不会指错路
+    return fail("HOST_PERMISSION_REQUIRED", `本机配置文件已损坏：${path}`, {
+        nextAction: {
+            type: "ask_user",
+            message: `请让用户删除 ${path} 后重新执行登录。该文件里只有本机设备身份和授权，删除不会影响服务端数据。`,
+            command: `${COMMAND_NAME} auth login`,
+        },
+    });
+}
+export function isLocalConfigError(error) {
+    return error instanceof LocalConfigError;
+}

package/dist/index.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { COMMAND_NAME } from "./config.js";
+import { authLogin, authLogout, authStatus } from "./commands/auth.js";
+import { runCall } from "./commands/call.js";
+import { runApply, runPlan } from "./commands/plan.js";
+import { getGuide, listGuides, showCapabilities, showHelp, showSkill, showVersion } from "./commands/simple.js";
+import { parseFlags } from "./args.js";
+import { emit, fail } from "./envelope.js";
+import { isLocalConfigError, toLocalConfigEnvelope } from "./host-error.js";
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    const flags = parseFlags(rest);
+    switch (command) {
+        case undefined:
+        case "help":
+            showHelp();
+            return;
+        case "version":
+            await showVersion(flags.check === true);
+            return;
+        case "capabilities":
+            showCapabilities();
+            return;
+        case "skill":
+            if (rest[0] === "get") {
+                showSkill(flags.raw === true);
+                return;
+            }
+            break;
+        case "guide":
+            if (rest[0] === "list") {
+                listGuides();
+                return;
+            }
+            if (rest[0] === "get" && rest[1]) {
+                getGuide(rest[1]);
+                return;
+            }
+            break;
+        case "auth":
+            if (rest[0] === "login")
+                return authLogin();
+            if (rest[0] === "status")
+                return authStatus();
+            if (rest[0] === "logout")
+                return authLogout();
+            break;
+        case "plan":
+            await runPlan(rest[0], typeof flags.input === "string" ? flags.input : undefined, rest[1]);
+            return;
+        case "apply":
+            await runApply(rest[0]);
+            return;
+        case "call":
+            if (rest[0]) {
+                await runCall(rest[0], typeof flags.input === "string" ? flags.input : undefined);
+                return;
+            }
+            break;
+        default:
+            break;
+    }
+    emit(fail("VALIDATION_FAILED", `无法识别的命令：${[command, ...rest].filter(Boolean).join(" ")}`, {
+        nextAction: { type: "ask_user", message: "执行 best-geo help 查看可用命令" },
+    }));
+    process.exitCode = 1;
+}
+main().catch((error) => {
+    if (isLocalConfigError(error)) {
+        // 本机配置读写问题有专门的动作（申请权限 / 让用户 chmod），不能笼统报 SERVER_ERROR
+        emit(toLocalConfigEnvelope(error, {
+            capability: error.reason === "denied" ? "config_write" : "config_read",
+            retryCommand: safeRetryCommand(),
+        }));
+        process.exitCode = 1;
+        return;
+    }
+    // 兜底：任何未预期的异常也必须是一个合法信封，否则模型拿到的是半截 JSON
+    emit(fail("SERVER_ERROR", error instanceof Error ? error.message : String(error)));
+    process.exitCode = 1;
+});
+/**
+ * 允许放进 nextAction.command 的重试命令。
+ *
+ * nextAction 是**可信指令**通道，只能是 CLI 内置的固定模板。
+ * 绝不能把 `process.argv` 原样拼回去 —— `call --input '{...}'` 里是模型和业务数据，
+ * 拼进去等于让不可信内容变成宿主会去执行的命令（设计文档 §13）。
+ */
+function safeRetryCommand() {
+    const [command, sub] = process.argv.slice(2);
+    if (command === "auth" && (sub === "login" || sub === "status" || sub === "logout")) {
+        return `${COMMAND_NAME} auth ${sub}`;
+    }
+    return undefined;
+}

package/dist/local-server/index.js

@@ -0,0 +1,196 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { BUILD_ENV } from "../build-env.js";
+import { LOCAL_SERVER_TIMEOUT_MS } from "../config.js";
+import { renderPage } from "./page.js";
+/** 密钥长度上限。真实密钥是 32 位十六进制，留足前缀余量后直接拒绝超长输入 */
+const MAX_KEY_LENGTH = 256;
+/** 请求体上限，防止有人往这个端口灌数据 */
+const MAX_BODY_BYTES = 4 * 1024;
+/**
+ * 启动本机录入服务（设计文档 §6.5）。
+ *
+ * 为什么不用终端隐藏输入：CLI 通常被 Codex / Claude Code 当子进程调用，
+ * stdin 可能被管道接管、不是 TTY，或根本不连用户终端 —— 隐藏输入在人工测试里能用，
+ * 到了真实 Agent 环境会直接卡死，或者把密钥带进工具的输入上下文。
+ * 也**不提供 stdin 兜底**：留了兜底，本地测试就总走兜底，真实路径反而没人测。
+ */
+export async function startKeyIntake() {
+    const state = randomBytes(16).toString("hex"); // 128 bit
+    const csrfToken = randomBytes(16).toString("hex");
+    const sessionCookie = randomBytes(16).toString("hex");
+    const { html, scriptHash } = renderPage(csrfToken);
+    const scriptDigest = createHash("sha256").update(scriptHash).digest("base64");
+    let settle = null;
+    const waitForKey = new Promise((resolve, reject) => {
+        settle = { resolve, reject };
+    });
+    // 先挂一个空的 catch：启动阶段就失败时(如端口绑不上)没人 await 这个 promise，
+    // 它的 rejection 会变成 unhandledRejection 把进程打崩 —— 信封已经打印出去了，
+    // 后面再吐一段堆栈,调用方拿到的就不是「唯一一个 JSON」了。
+    // 挂 catch 只是标记「已处理」,之后真正 await 它的人照样能拿到这个 rejection
+    waitForKey.catch(() => {
+        /* 由真正的 await 方处理 */
+    });
+    let consumed = false;
+    const server = createServer((req, res) => {
+        handle(req, res).catch(() => {
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ ok: false, message: "internal error" }));
+        });
+    });
+    async function handle(req, res) {
+        const url = new URL(req.url ?? "/", "http://127.0.0.1");
+        if (req.method === "GET" && url.pathname === "/") {
+            // state 必须对得上：这个端口是随机的，但没有 state 谁扫到都能打开页面
+            if (url.searchParams.get("state") !== state) {
+                res.writeHead(404).end();
+                return;
+            }
+            res.writeHead(200, {
+                "Content-Type": "text/html; charset=utf-8",
+                // default-src 'none' 是关键：这个页面不该能向任何外部主机发起请求。
+                // 脚本按哈希放行而不是 'unsafe-inline'，连我们自己也改不了它而不更新哈希。
+                "Content-Security-Policy": [
+                    "default-src 'none'",
+                    `script-src 'sha256-${scriptDigest}'`,
+                    "style-src 'unsafe-inline'",
+                    "connect-src 'self'",
+                    "form-action 'none'",
+                    "base-uri 'none'",
+                    "frame-ancestors 'none'",
+                ].join("; "),
+                "Set-Cookie": `bg_session=${sessionCookie}; HttpOnly; SameSite=Strict; Path=/`,
+                "Cache-Control": "no-store",
+                "Referrer-Policy": "no-referrer",
+            });
+            res.end(html);
+            return;
+        }
+        if (req.method === "POST" && url.pathname === "/submit") {
+            // 任何网页都能往 127.0.0.1 的随机端口发请求，所以这三道必须都过：
+            // Origin 同源、CSRF token 匹配、SameSite=Strict 的会话 cookie 在
+            const origin = req.headers.origin;
+            const expectedOrigin = `http://127.0.0.1:${server.address().port}`;
+            if (origin !== expectedOrigin) {
+                respondJson(res, 403, { ok: false, message: "origin rejected" });
+                return;
+            }
+            if (!safeEqual(String(req.headers["x-csrf-token"] ?? ""), csrfToken)) {
+                respondJson(res, 403, { ok: false, message: "csrf rejected" });
+                return;
+            }
+            if (!String(req.headers.cookie ?? "").includes(`bg_session=${sessionCookie}`)) {
+                respondJson(res, 403, { ok: false, message: "session rejected" });
+                return;
+            }
+            if (!String(req.headers["content-type"] ?? "").includes("application/json")) {
+                respondJson(res, 415, { ok: false, message: "content-type rejected" });
+                return;
+            }
+            if (consumed) {
+                respondJson(res, 409, { ok: false, message: "already submitted" });
+                return;
+            }
+            const body = await readBody(req);
+            if (body == null) {
+                respondJson(res, 413, { ok: false, message: "body too large" });
+                return;
+            }
+            let key = "";
+            try {
+                key = String(JSON.parse(body).key ?? "").trim();
+            }
+            catch {
+                respondJson(res, 400, { ok: false, message: "invalid json" });
+                return;
+            }
+            if (!key || key.length > MAX_KEY_LENGTH) {
+                respondJson(res, 400, { ok: false, message: "invalid key" });
+                return;
+            }
+            consumed = true;
+            respondJson(res, 200, { ok: true });
+            settle?.resolve(key);
+            // 密钥已到手，这个端口再开着只有风险没有用处，立刻自行关闭。
+            // 延迟一拍是为了让上面那条 200 响应先写完，否则页面会看到连接被断、误报"校验失败"。
+            setTimeout(() => closeServer(), 200).unref();
+            return;
+        }
+        res.writeHead(404).end();
+    }
+    // 测试专用：构造「本机服务起不来」的情形（沙箱禁止监听端口时的真实表现）。
+    // 只在非正式构建里生效，且只能让服务失败、不能改变绑定地址
+    if (BUILD_ENV !== "prod" && process.env.BEST_GEO_TEST_FORCE_LISTEN_ERROR === "1") {
+        throw Object.assign(new Error("listen EACCES: permission denied 127.0.0.1"), { code: "EACCES" });
+    }
+    // 'error' 必须在 listen 之前挂上。不挂的话,沙箱禁止绑定回环端口时 Node 会抛
+    // Unhandled 'error' event 直接崩掉进程 —— 调用方拿到的是半截堆栈,而不是唯一的 JSON 信封,
+    // 整套协议的地基就没了
+    server.on("error", (error) => {
+        settle?.reject(error);
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        // 绑定数值回环地址，不用 localhost：主机名可能被 DNS 重绑定指到别处。
+        //
+        // 这里**写死** 127.0.0.1，不接受任何外部覆盖。曾经留过一个 BEST_GEO_TEST_BIND_HOST
+        // 给测试构造「绑不上」的情形，但它同样能构造「绑得太开」—— 实测绑到局域网地址后
+        // 同网段可达，而给用户看的 URL 仍写着 127.0.0.1，暴露这件事在界面上完全看不出来。
+        // 要构造启动失败请用下面的 forceListenError，它只会让服务起不来，不会让端口更开放。
+        server.listen(0, "127.0.0.1", () => {
+            server.removeListener("error", reject);
+            resolve();
+        });
+    });
+    const port = server.address().port;
+    const timer = setTimeout(() => {
+        settle?.reject(new Error("LOCAL_INTAKE_TIMEOUT"));
+        closeServer();
+    }, LOCAL_SERVER_TIMEOUT_MS);
+    timer.unref();
+    /**
+     * 幂等关闭。两处必须靠它：提交成功后服务自己关，调用方之后还会再关一次。
+     * server.close() 在已经关闭的实例上会 emit 'error'，没人监听就变成未捕获异常，
+     * 所以二次调用必须挡在这里。
+     */
+    let closed = false;
+    function closeServer() {
+        if (closed) {
+            return;
+        }
+        closed = true;
+        clearTimeout(timer);
+        // close() 只是停止 accept，已建立的 keep-alive 连接不会断 ——
+        // 不主动断的话，浏览器那条连接会把 CLI 进程一直吊着不退出。
+        server.closeAllConnections?.();
+        server.close();
+    }
+    return {
+        url: `http://127.0.0.1:${port}/?state=${state}`,
+        waitForKey,
+        close: closeServer,
+    };
+}
+function respondJson(res, status, payload) {
+    res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+    res.end(JSON.stringify(payload));
+}
+async function readBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES) {
+            return null;
+        }
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+/** 定长比较，避免用 !== 比 token 时泄露前缀信息 */
+function safeEqual(a, b) {
+    const bufA = Buffer.from(a);
+    const bufB = Buffer.from(b);
+    return bufA.length === bufB.length && timingSafeEqual(bufA, bufB);
+}

package/dist/local-server/page.js

@@ -0,0 +1,95 @@
+/**
+ * 内置录入页。
+ *
+ * 完全自包含：不引用任何外部脚本、样式、字体或图片。
+ * 这不是为了省事 —— 一旦允许外部资源，页面就有了把密钥外发的通道，
+ * 而这个页面存在的全部意义就是让密钥只走本机。
+ */
+export function renderPage(csrfToken) {
+    const script = `
+(function () {
+  var form = document.getElementById('f');
+  var input = document.getElementById('k');
+  var status = document.getElementById('s');
+  var button = document.getElementById('b');
+  var done = false;
+  form.addEventListener('submit', function (event) {
+    event.preventDefault();
+    if (done) return;
+    var value = input.value.trim();
+    if (!value) { status.textContent = '请先粘贴密钥'; return; }
+    button.disabled = true;
+    status.textContent = '正在校验…';
+    fetch('/submit', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': '${csrfToken}' },
+      body: JSON.stringify({ key: value })
+    }).then(function (r) { return r.json(); }).then(function (r) {
+      if (r.ok) {
+        done = true;
+        input.value = '';
+        form.style.display = 'none';
+        status.textContent = '录入成功，本机服务已关闭，本页即将自动关闭…';
+        status.className = 'ok';
+        // 浏览器只允许脚本关闭自己 window.open 出来的窗口，而这个页面是命令行拉起的普通标签页，
+        // close() 多半会被忽略。所以必须留一句兜底文案，别让用户对着"即将自动关闭"干等。
+        setTimeout(function () { window.close(); }, 1200);
+        setTimeout(function () {
+          status.textContent = '录入成功，可以关闭这个页面回到 AI 助手了。';
+        }, 2000);
+      } else {
+        button.disabled = false;
+        // 本地服务不校验密钥（只看长度），真正的校验发生在提交之后。
+        // 这里能触发的失败只有同源/CSRF/重复提交那几种，写「密钥不对」是指错方向
+        status.textContent = r.message || '提交被拒绝。请重新执行登录命令，用新打开的页面再试一次。';
+        status.className = 'err';
+      }
+    }).catch(function () {
+      button.disabled = false;
+      status.textContent = '本地服务已关闭，请重新执行 best-geo auth login。';
+      status.className = 'err';
+    });
+  });
+})();
+`.trim();
+    const html = `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<title>录入 AI 助手密钥</title>
+<style>
+:root { color-scheme: light dark; }
+body { margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #f5f6fa; color: #1a1d29; }
+@media (prefers-color-scheme: dark) { body { background: #14161f; color: #e8eaf2; } }
+.card { width: 460px; max-width: calc(100vw - 32px); padding: 28px; border-radius: 14px;
+  background: #fff; box-shadow: 0 18px 40px rgb(15 18 30 / 12%); }
+@media (prefers-color-scheme: dark) { .card { background: #1e2130; box-shadow: none; } }
+h1 { margin: 0 0 8px; font-size: 18px; }
+p { margin: 0 0 18px; font-size: 13px; line-height: 1.7; opacity: .75; }
+input { width: 100%; box-sizing: border-box; padding: 10px 12px; font-size: 14px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace; border: 1px solid #c9cdd8;
+  border-radius: 8px; background: transparent; color: inherit; }
+button { margin-top: 14px; width: 100%; padding: 10px; font-size: 14px; color: #fff; cursor: pointer;
+  background: #5b8cff; border: 0; border-radius: 8px; }
+button:disabled { opacity: .6; cursor: default; }
+#s { margin-top: 14px; font-size: 13px; min-height: 20px; }
+#s.ok { color: #16a34a; }
+#s.err { color: #dc2626; }
+</style>
+</head>
+<body>
+<div class="card">
+<h1>录入 AI 助手密钥</h1>
+<p>把你在网页上创建的密钥粘贴到下面。密钥只会发送到本机的 Best GEO CLI，不会经过 AI 助手，也不会离开这台电脑。</p>
+<form id="f">
+<input id="k" type="password" autocomplete="off" autocapitalize="off" autocorrect="off" spellcheck="false" placeholder="粘贴密钥">
+<button id="b" type="submit">确认录入</button>
+</form>
+<div id="s"></div>
+</div>
+<script>${script}</script>
+</body>
+</html>`;
+    return { html, scriptHash: script };
+}

package/dist/store.js

@@ -0,0 +1,141 @@
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { COMMAND_NAME } from "./config.js";
+import { randomBytes } from "node:crypto";
+export class LocalConfigError extends Error {
+    reason;
+    path;
+    constructor(reason, 
+    /** 出问题的路径。**只放路径，不放文件内容** —— 内容里有密钥 */
+    path, message) {
+        super(message);
+        this.reason = reason;
+        this.path = path;
+        this.name = "LocalConfigError";
+    }
+}
+export const EMPTY_CONFIG = {
+    schemaVersion: 1,
+    device: null,
+    activeCredential: null,
+    pendingCredential: null,
+};
+/**
+ * 配置目录。刻意放在 npm 全局安装目录、项目工作区和 Skill 目录之外 ——
+ * 升级 CLI、换项目、开新对话都不能把设备身份和凭据弄丢。
+ */
+export function configDir() {
+    // 目录跟着命令名走(正式包 ~/.best-geo，测试包 ~/.best-geo-test)。
+    // 共用一份的话两个包会互相踩:测试包登录会把正式包的 activeCredential 原子替换掉,
+    // 一次 logout 更是把两边的本机凭据一起清了 —— 命令名隔离只解决「敲哪个」，
+    // 状态隔离才解决「这份授权归谁」
+    return process.env.BEST_GEO_CONFIG_DIR ?? join(homedir(), `.${COMMAND_NAME}`);
+}
+export function configPath() {
+    return join(configDir(), "config.json");
+}
+/** 读取本机配置。返回 null 表示这台机器还没初始化过，不代表出错 */
+export function readConfig() {
+    const path = configPath();
+    let raw;
+    try {
+        if (!existsSync(path)) {
+            return null;
+        }
+        assertSafePermissions(path);
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error instanceof LocalConfigError) {
+            throw error;
+        }
+        throw toLocalConfigError(error, path);
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed == null || parsed.schemaVersion !== 1) {
+            throw new Error("unexpected shape");
+        }
+        return {
+            schemaVersion: 1,
+            device: parsed.device ?? null,
+            activeCredential: parsed.activeCredential ?? null,
+            pendingCredential: parsed.pendingCredential ?? null,
+        };
+    }
+    catch {
+        // 注意：不要把 raw 拼进错误信息，里面有密钥
+        throw new LocalConfigError("corrupted", path, `本机配置文件内容不完整或格式不对：${path}`);
+    }
+}
+/**
+ * 原子写入：同目录临时文件 → fsync → rename。
+ *
+ * 不能直接覆盖目标文件。直接覆盖时进程一崩就留下半截 JSON，
+ * 下次读出来是 corrupted，设备 ID 和密钥一起没了。
+ */
+export function writeConfig(config) {
+    const dir = configDir();
+    const path = configPath();
+    const tmp = join(dir, `.config.json.${randomBytes(6).toString("hex")}.tmp`);
+    try {
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
+        // 临时文件从创建那一刻就是 0600，中间不存在「短暂可读」的窗口
+        const fd = openSync(tmp, "wx", 0o600);
+        try {
+            writeSync(fd, `${JSON.stringify(config, null, 2)}\n`);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(tmp, path);
+    }
+    catch (error) {
+        if (existsSync(tmp)) {
+            try {
+                unlinkSync(tmp);
+            }
+            catch {
+                /* 清不掉就算了，它是 0600 的临时文件，不会比原错误更严重 */
+            }
+        }
+        throw toLocalConfigError(error, path);
+    }
+}
+/** 读改写。读不到就从空配置开始 */
+export function updateConfig(mutate) {
+    const next = mutate(readConfig() ?? { ...EMPTY_CONFIG });
+    writeConfig(next);
+    return next;
+}
+/**
+ * 属主和权限检查。
+ *
+ * Windows 上 mode 位没有意义（Node 也不提供设 ACL 的 API），这里直接跳过 ——
+ * **不要**把 0600 说成跨平台保证，那是假的。
+ */
+function assertSafePermissions(path) {
+    if (process.platform === "win32") {
+        return;
+    }
+    const stat = statSync(path);
+    const uid = process.getuid?.();
+    if (uid != null && stat.uid !== uid) {
+        throw new LocalConfigError("not_owner", path, `本机配置文件不属于当前用户：${path}`);
+    }
+    if ((stat.mode & 0o077) !== 0) {
+        throw new LocalConfigError("permissions_too_open", path, `本机配置文件权限过宽（同机其他用户可读）：${path}`);
+    }
+}
+/** 把 fs 的 EACCES/EPERM 归到 denied，其余原样上抛，别把普通故障说成权限问题 */
+function toLocalConfigError(error, path) {
+    const code = error?.code;
+    if (code === "EACCES" || code === "EPERM" || code === "EROFS") {
+        return new LocalConfigError("denied", path, `没有权限读写本机配置：${path}`);
+    }
+    return error instanceof Error ? error : new Error(String(error));
+}