best-geo-test 0.1.0

package/dist/commands/auth.js

@@ -0,0 +1,246 @@
+import { execFile } from "node:child_process";
+import { callApi, isServerVerdict } from "../api.js";
+import { COMMAND_NAME, CLI_VERSION } from "../config.js";
+import { clearCredentials, clearPending, loadActive, loadApiKey, loadPending, promotePending, savePending, } from "../credentials.js";
+import { deviceInfo } from "../device.js";
+import { emit, fail, ok } from "../envelope.js";
+import { startKeyIntake } from "../local-server/index.js";
+import { configPath } from "../store.js";
+/**
+ * 收敛可能存在的 pending 凭据（设计文档 §6.2 第 11 步）。
+ *
+ * 进程如果在「claim 已经成功、但还没提升为 active」之间被中断，本机就留下一个 pending：
+ * 服务端那边新密钥其实已经生效并顶替了旧密钥，本机却还在用旧的。
+ * 所以**任何用到凭据的命令都要先跑这里**，用同一个设备 ID 幂等重试 claim：
+ * 成功就提升为 active；确认失败（过期、换绑到别的设备）就清掉 pending，旧 active 继续可用
+ * —— claim 失败意味着服务端那次顶替没有发生。
+ */
+export async function settlePendingCredential() {
+    const pending = loadPending();
+    if (!pending) {
+        return null;
+    }
+    const result = await claim(pending.apiKey);
+    if (result.ok) {
+        promotePending({
+            userId: result.data.user.id,
+            agentId: result.data.agentId,
+            companyIds: result.data.companyIds,
+        });
+        return null;
+    }
+    if (!isServerVerdict(result)) {
+        // 没拿到服务端的终局裁决就**不能**动 pending：服务端那边可能已经绑好并撤销了旧密钥，
+        // 删掉 pending 等于把唯一的恢复依据丢了。这次命令直接失败，让调用方稍后重试。
+        // 判据是「是不是裁决」而不是「是不是网络错误」—— 服务端 500 同样什么都没告诉我们。
+        return fail("SERVER_ERROR", `本机有一份待确认的授权，暂时无法与服务端确认：${result.message}`, {
+            requestId: result.requestId,
+            nextAction: {
+                type: "ask_user",
+                message: "网络恢复后重试同一条命令即可自动收敛；在此之前不要重新登录，也不要删除本机配置文件。",
+            },
+        });
+    }
+    // 服务端明确拒绝（过期、已绑到别的设备等）：这把 pending 永远不会生效，清掉。
+    // 旧 active 仍然有效 —— claim 失败意味着服务端那次顶替根本没发生
+    clearPending();
+    return null;
+}
+/**
+ * 打开本地页面录入密钥并完成设备绑定。
+ *
+ * 顺序上有两条不能变：
+ * 1. **先做本机预检，再让用户录入**。配置目录读写不通就直接返回权限申请，
+ *    否则用户白粘贴一次密钥，最后还是存不下来。
+ * 2. **先 claim 成功，再把 pending 提升为 active**。反过来的话，
+ *    一把不可用的密钥会把原来能用的凭据覆盖掉，用户两头落空。
+ */
+export async function authLogin() {
+    // 预检：这行会读配置、必要时生成并原子写入设备 ID。权限有问题会在这里抛出，
+    // 由 index.ts 统一翻译成 HOST_PERMISSION_REQUIRED —— 此时页面还没开，用户也还没录入
+    const info = deviceInfo();
+    const unsettled = await settlePendingCredential();
+    if (unsettled) {
+        emit(unsettled);
+        return;
+    }
+    const existing = loadApiKey();
+    let session;
+    try {
+        session = await startKeyIntake();
+    }
+    catch (error) {
+        // 起不来本地服务最常见的原因就是沙箱不让绑回环端口。
+        // 这是宿主能授权解决的事,所以给 request_host_approval 而不是笼统的 SERVER_ERROR
+        emit(fail("HOST_PERMISSION_REQUIRED", `无法在本机启动录入服务：${errorMessage(error)}`, {
+            nextAction: {
+                type: "request_host_approval",
+                message: "Best GEO 需要在 127.0.0.1 上监听一个随机端口来接收用户粘贴的密钥（不对外暴露）。" +
+                    "请用当前工具的权限确认机制授权本机回环端口监听后重试同一条命令。",
+                capability: "loopback_port",
+                command: `${COMMAND_NAME} auth login`,
+            },
+        }));
+        return;
+    }
+    openBrowser(session.url);
+    // stderr 的第一段是写给调用方（大模型）的运行说明，不是给人看的提示。
+    // 不写清楚的话，模型看到命令迟迟不返回，会以为卡住而中断进程，或者干脆把命令甩给用户自己去终端执行 ——
+    // 后者等于把本机绑定这一步丢了，登录永远完不成。
+    const tag = `[${COMMAND_NAME}]`;
+    process.stderr.write(`${tag} auth login 已启动本机录入服务，会阻塞等待用户粘贴密钥，最长 5 分钟。\n` +
+        `${tag} 调用方请保持本进程运行直到它自行退出，不要中断、不要转交给用户在别处执行；\n` +
+        `${tag} 进程退出时 stdout 会给出唯一一个 JSON 结果，那时再向用户汇报成败。\n` +
+        `${tag} 现在请把下面这个地址转达给用户，让他在浏览器里打开并粘贴密钥（密钥不要经过你）：\n`);
+    process.stderr.write(`${tag} 本地页面：${session.url}\n`);
+    // 本机已有凭据时先说清楚会发生什么。真正的撤销由服务端在 claim 事务里做，
+    // 而且只在新密钥验完之后
+    if (existing) {
+        process.stderr.write(`${tag} 本机已有一份授权，录入新密钥会替换它。\n`);
+    }
+    let key;
+    try {
+        key = await session.waitForKey;
+    }
+    catch {
+        session.close();
+        emit(fail("AUTH_REQUIRED", "本地录入超时或被取消", {
+            nextAction: {
+                type: "auth_login",
+                message: "用户在 5 分钟内没有完成粘贴。先问清他是否已经拿到密钥，再由你重新执行 command，" +
+                    "并把新的本地页面地址转达给他。",
+                command: `${COMMAND_NAME} auth login`,
+            },
+        }));
+        return;
+    }
+    // 密钥已到手，本机录入服务在这一刻自行关闭（见 local-server/index.ts）。
+    // 这条日志的作用是让模型知道「等待阶段结束了、进程正在收尾」，而不是以为它又挂住了。
+    process.stderr.write(`${tag} 已收到密钥，本机录入服务已关闭，正在向服务端校验并绑定本机，请继续等待本进程退出。\n`);
+    // 先落地为 pending 再 claim：claim 成功后进程若被中断，下一条命令还能靠 pending 幂等收敛。
+    // 写失败就别调 claim 了 —— 服务端把密钥绑到本设备、本机却存不下来，是最难解释的一种状态
+    savePending(key);
+    const result = await claim(key);
+    if (!result.ok) {
+        // 和 settlePendingCredential 同一把尺子：只有服务端明确裁定这把密钥不可用才清掉它。
+        // 无条件清的话，服务端「已绑定但响应丢了」的情况下，用户刚粘贴的密钥会彻底消失，
+        // 而旧密钥可能已经被那次绑定撤销了 —— 两头落空，只能回网页重建
+        if (isServerVerdict(result)) {
+            clearPending();
+        }
+        else {
+            process.stderr.write(`${tag} 未能确认绑定结果，已保留这把待确认的密钥。网络恢复后执行任意 ${COMMAND_NAME} 命令即可自动收敛。\n`);
+        }
+        emit(result);
+        return;
+    }
+    const active = promotePending({
+        userId: result.data.user.id,
+        agentId: result.data.agentId,
+        companyIds: result.data.companyIds,
+    });
+    emit(ok({
+        user: result.data.user,
+        device: result.data.device,
+        companyIds: active?.companyIds ?? result.data.companyIds,
+        replacedPreviousAuthorization: result.data.replacedPreviousAuthorization,
+        configPath: configPath(),
+    }, result.requestId));
+}
+export async function authStatus() {
+    const unsettled = await settlePendingCredential();
+    if (unsettled) {
+        emit(unsettled);
+        return;
+    }
+    const key = loadApiKey();
+    if (!key) {
+        emit(notLoggedIn());
+        return;
+    }
+    // 用一次真实查询确认凭据仍然有效：本机存着密钥不代表服务端还认它
+    const result = await callApi("/companies", { apiKey: key, query: { page: 1, limit: 100 } });
+    if (!result.ok) {
+        emit(result);
+        return;
+    }
+    const info = deviceInfo();
+    emit(ok({
+        loggedIn: true,
+        device: { deviceId: info.deviceId, deviceName: info.deviceName, platform: info.platform },
+        user: loadActive() ? { id: loadActive().userId, agentId: loadActive().agentId } : null,
+        companies: result.data.data.map((item) => ({ id: item.id, name: item.name })),
+        configPath: configPath(),
+    }, result.requestId));
+}
+/**
+ * 退出登录：**先让服务端撤销密钥，再清本机**。
+ *
+ * 顺序反过来（先清本机）会让撤销失败时无从补救：本机已经没有密钥了，
+ * 而服务端那把仍然有效、仍然绑着这台设备，用户以为退了、其实没退。
+ */
+export async function authLogout() {
+    const unsettled = await settlePendingCredential();
+    if (unsettled) {
+        emit(unsettled);
+        return;
+    }
+    const key = loadApiKey();
+    if (!key) {
+        emit(notLoggedIn());
+        return;
+    }
+    const result = await callApi("/auth/logout", {
+        method: "POST",
+        apiKey: key,
+    });
+    if (!result.ok) {
+        // 不清本机、也不谎报成功：让模型如实告诉用户「服务端还没撤销」
+        emit(result);
+        return;
+    }
+    clearCredentials();
+    emit(ok({
+        loggedOut: true,
+        revoked: result.data,
+        note: "服务端密钥已撤销，本机凭据已清除。设备身份保留，重新登录会复用同一台设备。",
+    }, result.requestId));
+}
+function notLoggedIn() {
+    // type 用 auth_login 而不是 ask_user：ask_user 的语义是「把话转达给用户」，
+    // 模型照做的结果就是让用户自己去终端敲命令，本机绑定这一步永远走不到。
+    // 登录必须由持有本进程的调用方亲自执行并等它自行退出。
+    return fail("AUTH_REQUIRED", "本机还没有可用的授权", {
+        nextAction: {
+            type: "auth_login",
+            message: "先让用户到所属 SaaS 网页的密钥管理里创建「AI 助手密钥」并选好授权公司；" +
+                "然后由你直接执行 command，它会阻塞最长 5 分钟等待用户在本机页面粘贴密钥。" +
+                "执行期间把 stderr 里的本地页面地址转达给用户，保持进程运行直到它自行退出，不要中断，也不要让用户在别处执行。",
+            command: `${COMMAND_NAME} auth login`,
+        },
+    });
+}
+/** claim 用的固定入参：设备 ID 必须取本机持久化的那一个，不能临时生成 */
+function claim(apiKey) {
+    const info = deviceInfo();
+    return callApi("/auth/claim", {
+        method: "POST",
+        apiKey,
+        body: { ...info, cliVersion: CLI_VERSION },
+    });
+}
+/** 打开失败不是致命错误：地址已经写到 stderr，用户可以自己复制 */
+function openBrowser(url) {
+    // headless / CI 环境下别去拉起浏览器，地址已经在 stderr 里
+    if (process.env.BEST_GEO_NO_BROWSER === "1") {
+        return;
+    }
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    execFile(command, args, () => {
+        /* 忽略：用户可以手动打开 stderr 里的地址 */
+    });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/commands/call.js

@@ -0,0 +1,50 @@
+import { callApi } from "../api.js";
+import { requireApiKey } from "./session.js";
+import { emit, fail } from "../envelope.js";
+/** 能力名 → 请求方式。这里只有查询：写操作一律走 plan/apply，不给 call 留后门 */
+const ROUTES = {
+    "companies.list": (input) => ({ path: "/companies", query: input }),
+    "companies.get": (input) => ({ path: `/companies/${Number(input.id)}` }),
+    "products.list": (input) => ({ path: "/products", query: input }),
+    "products.get": (input) => ({ path: `/products/${Number(input.id)}` }),
+    "questions.list": (input) => ({ path: "/questions", query: input }),
+    "questions.get": (input) => ({ path: `/questions/${Number(input.id)}` }),
+};
+export function knownCapabilities() {
+    return Object.keys(ROUTES);
+}
+export async function runCall(capability, rawInput) {
+    const route = ROUTES[capability];
+    if (!route) {
+        emit(fail("VALIDATION_FAILED", `未知能力：${capability}`, {
+            data: { available: knownCapabilities() },
+            nextAction: { type: "ask_user", message: "先执行 best-geo capabilities 查看可用能力" },
+        }));
+        return;
+    }
+    let input = {};
+    if (rawInput) {
+        try {
+            input = JSON.parse(rawInput);
+        }
+        catch {
+            emit(fail("VALIDATION_FAILED", "--input 不是合法 JSON"));
+            return;
+        }
+    }
+    // 只认真正的正整数：Number(true)=1、Number("")=0、Number([])=0、Number("1e3")=1000
+    // 都会骗过 Number.isInteger，本机拦截的意义就是别浪费一次请求
+    const needsId = capability.endsWith(".get");
+    if (needsId && !(typeof input.id === "number" && Number.isInteger(input.id) && input.id > 0)) {
+        emit(fail("VALIDATION_FAILED", `${capability} 需要数字类型的 id`));
+        return;
+    }
+    const session = await requireApiKey();
+    if (!session.ok) {
+        emit(session.envelope);
+        return;
+    }
+    const { path, query } = route(input);
+    // 服务端返回的就是同一套信封，原样透传
+    emit(await callApi(path, { apiKey: session.apiKey, query }));
+}

package/dist/commands/plan.js

@@ -0,0 +1,68 @@
+import { callApi } from "../api.js";
+import { requireApiKey } from "./session.js";
+import { emit, fail } from "../envelope.js";
+/**
+ * 写操作的两步协议（设计文档 §十）。
+ *
+ * 为什么不做成一步:大模型可能把用户的目标理解偏,而写入不可逆。
+ * plan 让服务端重新读一遍真实数据、算出变更前后摘要,由**用户**看过之后才 apply。
+ * 用户最初提的目标不等于对最终摘要的确认 —— 这一点在 SKILL 和 Guide 里都写死了。
+ */
+/** 第二期开放的写能力。和服务端注册表一一对应,拼错能力名要在本机就报错,别到服务端才发现 */
+const WRITE_OPERATIONS = [
+    "companies.create",
+    "companies.update",
+    "products.create",
+    "products.update",
+    "questions.create",
+    "questions.update",
+];
+export async function runPlan(operation, rawInput, positional) {
+    if (!operation || !WRITE_OPERATIONS.includes(operation)) {
+        emit(fail("VALIDATION_FAILED", `未知的写操作：${operation ?? "(空)"}`, {
+            data: { available: WRITE_OPERATIONS },
+            nextAction: { type: "ask_user", message: "先执行 best-geo capabilities 查看可用能力和它们的入参" },
+        }));
+        return;
+    }
+    // 漏写 --input 时给明确提示。不提示的话它会被当成空输入，
+    // 报出来的是「xxx 必须是正整数」这种看起来像参数错、实际是命令写法错的信息
+    if (!rawInput && positional?.trim().startsWith("{")) {
+        emit(fail("VALIDATION_FAILED", "入参要放在 --input 后面", {
+            nextAction: {
+                type: "ask_user",
+                message: `正确写法：best-geo plan ${operation} --input '<JSON>'`,
+            },
+        }));
+        return;
+    }
+    let input;
+    try {
+        input = rawInput ? JSON.parse(rawInput) : {};
+    }
+    catch {
+        emit(fail("VALIDATION_FAILED", "--input 不是合法 JSON"));
+        return;
+    }
+    const session = await requireApiKey();
+    if (!session.ok) {
+        emit(session.envelope);
+        return;
+    }
+    // 服务端返回的就是同一套信封，原样透传
+    emit(await callApi("/plans", { method: "POST", apiKey: session.apiKey, body: { operation, input } }));
+}
+export async function runApply(planId) {
+    if (!planId) {
+        emit(fail("VALIDATION_FAILED", "缺少 planId", {
+            nextAction: { type: "ask_user", message: "先执行 best-geo plan <operation> 生成计划，把摘要给用户确认后再执行" },
+        }));
+        return;
+    }
+    const session = await requireApiKey();
+    if (!session.ok) {
+        emit(session.envelope);
+        return;
+    }
+    emit(await callApi(`/plans/${encodeURIComponent(planId)}/apply`, { method: "POST", apiKey: session.apiKey }));
+}

package/dist/commands/session.js

@@ -0,0 +1,25 @@
+import { COMMAND_NAME } from "../config.js";
+import { loadApiKey } from "../credentials.js";
+import { settlePendingCredential } from "./auth.js";
+import { fail } from "../envelope.js";
+export async function requireApiKey() {
+    const unsettled = await settlePendingCredential();
+    if (unsettled) {
+        return { ok: false, envelope: unsettled };
+    }
+    const apiKey = loadApiKey();
+    if (!apiKey) {
+        return {
+            ok: false,
+            envelope: fail("AUTH_REQUIRED", "本机还没有可用的授权", {
+                nextAction: {
+                    type: "auth_login",
+                    message: "先让用户到所属 SaaS 网页的密钥管理里创建「AI 助手密钥」并选好授权公司；" +
+                        "然后由你直接执行 command，它会阻塞最长 5 分钟等待用户在本机页面粘贴密钥。",
+                    command: `${COMMAND_NAME} auth login`,
+                },
+            }),
+        };
+    }
+    return { ok: true, apiKey };
+}

package/dist/commands/simple.js

@@ -0,0 +1,145 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { callApi } from "../api.js";
+import { API_BASE, BEST_GEO_ENV, COMMAND_NAME, CLI_VERSION, PACKAGE_NAME, PROTOCOL_VERSION } from "../config.js";
+import { emit, fail, ok } from "../envelope.js";
+/** 包根目录。编译产物在 dist/commands/，所以要往上两级 */
+function packageRoot() {
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+}
+function readPackageFile(...segments) {
+    return readFileSync(join(packageRoot(), ...segments), "utf8");
+}
+export function showHelp() {
+    emit(ok({
+        package: PACKAGE_NAME,
+        version: CLI_VERSION,
+        protocolVersion: PROTOCOL_VERSION,
+        commands: [
+            { command: `${COMMAND_NAME} version --check`, description: "检查版本是否需要升级" },
+            { command: `${COMMAND_NAME} capabilities`, description: "列出可用能力及其输入 schema" },
+            {
+                command: `${COMMAND_NAME} skill get --raw > <你的 skill 目录>/best-geo/SKILL.md`,
+                description: "直接把 Skill 写成文件（推荐；--raw 输出 markdown 原文，不是 JSON）",
+            },
+            { command: `${COMMAND_NAME} skill get`, description: "以 JSON 信封返回 Skill 内容和 revision" },
+            { command: `${COMMAND_NAME} guide list`, description: "列出业务指南" },
+            { command: `${COMMAND_NAME} guide get <name>`, description: "读取一份业务指南" },
+            { command: `${COMMAND_NAME} auth login`, description: "打开本地页面录入密钥并绑定本机" },
+            { command: `${COMMAND_NAME} auth status`, description: "查看当前授权状态" },
+            { command: `${COMMAND_NAME} auth logout`, description: "撤销服务端密钥并清除本机凭据" },
+            { command: `${COMMAND_NAME} call <capability> --input '<JSON>'`, description: "调用一个查询能力" },
+            {
+                command: `${COMMAND_NAME} plan <operation> --input '<JSON>'`,
+                description: "生成写操作计划，返回给用户看的变更摘要（不写数据）",
+            },
+            {
+                command: `${COMMAND_NAME} apply <planId>`,
+                description: "执行计划。必须先把 plan 的摘要给用户看过并得到同意",
+            },
+        ],
+        // 注意：这是**成功**信封，nextAction 放在 data 里（OkEnvelope 上没有这个字段）。
+        // SKILL 里已写明成功时看 data.nextAction，别改成顶层 —— 顶层是失败信封的契约
+        nextAction: {
+            type: "install_skill",
+            command: `${COMMAND_NAME} skill get --raw`,
+            message: "按当前 AI 工具的 Skill 机制选一个安装目录，用 best-geo skill get --raw 把内容直接重定向成 SKILL.md，然后加载它",
+        },
+    }));
+}
+export async function showVersion(check) {
+    if (!check) {
+        emit(ok({ package: PACKAGE_NAME, version: CLI_VERSION, protocolVersion: PROTOCOL_VERSION, env: BEST_GEO_ENV, apiBase: API_BASE }));
+        return;
+    }
+    const meta = await callApi("/meta");
+    if (!meta.ok) {
+        emit(meta);
+        return;
+    }
+    const outdated = compareVersion(CLI_VERSION, meta.data.minimumCliVersion) < 0;
+    if (outdated) {
+        emit(fail("CLI_UPDATE_REQUIRED", `当前版本 ${CLI_VERSION} 低于最低要求 ${meta.data.minimumCliVersion}`, {
+            requestId: meta.requestId,
+            data: { current: CLI_VERSION, ...meta.data },
+            nextAction: {
+                type: "upgrade",
+                message: "升级后重试",
+                // 命令用本机常量拼，不用服务端返回的 upgradeCommand：
+                // nextAction 是**可信指令**通道，而 /meta 是公开接口、它的 data 属于非可信数据
+                //（设计文档 §5.3 / §13）。服务端那个值只在 data 里透出去供展示
+                command: `npm install -g ${PACKAGE_NAME}@latest`,
+            },
+        }));
+        return;
+    }
+    emit(ok({
+        current: CLI_VERSION,
+        ...meta.data,
+        updateAvailable: compareVersion(CLI_VERSION, meta.data.latestCliVersion) < 0,
+    }, meta.requestId));
+}
+export function showCapabilities() {
+    emit(ok(JSON.parse(readPackageFile("capabilities", "capabilities.json"))));
+}
+/**
+ * 取出随包发布的 Skill 内容。
+ *
+ * `--raw` 是全 CLI **唯一**一个非 JSON 输出的口子，而且必须显式要求。
+ * 开这个口子是因为 Skill 的产物本来就要落成一个 .md 文件：
+ * 让模型从 JSON 里抠出 content 字符串再写文件，等于多一次转义还原 ——
+ * 而这份内容里恰好有引号、反斜杠和代码块。重定向是 shell 一步的事，可靠得多。
+ *
+ * 出错时仍然走 JSON 错误信封 + 非零退出码，调用方据此区分「拿到内容」和「没拿到」。
+ */
+export function showSkill(raw) {
+    const content = withCommandName(readPackageFile("skills", "best-geo", "SKILL.md"));
+    if (raw) {
+        process.stdout.write(content);
+        return;
+    }
+    // name 必须跟着命令名走：两个包都装时，模型按 data.name 建目录会把另一个包的 SKILL 覆盖掉，
+    // 而且不少宿主要求目录名和 frontmatter 的 name 一致
+    emit(ok({ name: COMMAND_NAME, revision: 1, content }));
+}
+const GUIDES = ["company", "product", "question"];
+export function listGuides() {
+    emit(ok({
+        guides: GUIDES.map((name) => {
+            const guide = JSON.parse(readPackageFile("guides", `${name}.json`));
+            return { name: guide.name, title: guide.title, whenToUse: guide.whenToUse };
+        }),
+    }));
+}
+export function getGuide(name) {
+    if (!GUIDES.includes(name)) {
+        emit(fail("GUIDE_NOT_FOUND", `没有名为 ${name} 的指南`, {
+            data: { available: GUIDES },
+        }));
+        return;
+    }
+    // Guide 里也有命令示例，同样要跟着当前命令名走
+    emit(ok(JSON.parse(withCommandName(readPackageFile("guides", `${name}.json`)))));
+}
+/** 语义化版本比较，只比较数字段，够用且不引依赖 */
+export function compareVersion(a, b) {
+    const pa = a.split(".").map((x) => Number.parseInt(x, 10) || 0);
+    const pb = b.split(".").map((x) => Number.parseInt(x, 10) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+        const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (diff !== 0)
+            return diff < 0 ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * 把随包分发的静态内容（SKILL、Guide）里的命令名换成当前命令名。
+ *
+ * 测试包的命令叫 best-geo-test，而 SKILL.md 和 guides/*.json 里写死的是 best-geo。
+ * 不换的话，模型会照抄一条这台机器上根本不存在的命令。
+ * 用 (?!-) 排除 best-geo-test 自身，避免替出 best-geo-test-test。
+ */
+function withCommandName(text) {
+    return COMMAND_NAME === "best-geo" ? text : text.replace(/\bbest-geo\b(?!-)/g, COMMAND_NAME);
+}

package/dist/config.js

@@ -0,0 +1,60 @@
+import { BUILD_API_BASE, BUILD_COMMAND_NAME, BUILD_DEVICE_PREFIX, BUILD_ENV, BUILD_PACKAGE_NAME, BUILD_VERSION, } from "./build-env.js";
+/** CLI 侧的固定常量 */
+/** 协议版本，与服务端 /v1/agent-cli/meta 的 protocolVersion 对齐 */
+export const PROTOCOL_VERSION = 1;
+/** 版本号唯一来源是 package.json，构建时烙进来 —— 两处维护迟早对不上 */
+export const CLI_VERSION = BUILD_VERSION;
+/** npm 包名。和命令名分开：正式包两者同名，测试包是 best-geo-test 装出 best-geo-test 命令，含义仍不同 */
+export const PACKAGE_NAME = BUILD_PACKAGE_NAME;
+/** 命令名。测试包叫 best-geo-test，输出里的命令示例必须跟着变，否则用户照抄会敲错 */
+export const COMMAND_NAME = BUILD_COMMAND_NAME;
+/** 构建时确定的环境档位，只用于回显。切环境靠重新构建，不靠运行期变量 */
+export const BEST_GEO_ENV = BUILD_ENV;
+/**
+ * 服务端地址。
+ *
+ * **地址表不在这里**（见 scripts/stamp-env.mjs）：三档地址一起编译进 dist 的话，
+ * 发给客户的正式包里就带着我们测试环境的域名，而且任何人设个环境变量就能把客户端指过去。
+ * 这里只认构建时烙进来的那一个地址。
+ *
+ * `BEST_GEO_API_BASE` 是给联调用的裸地址覆盖，属于运维行为 —— **不根据用户输入切换**，
+ * 让本地录入页能指定服务端，等于把密钥送到任意主机。
+ *
+ * 尾斜杠必须去掉：拼接时是 `${API_BASE}/v1/agent-cli...`，
+ * 配成 `https://x.com/` 会拼出 `https://x.com//v1/...`，有的网关直接 404。
+ */
+export const API_BASE = stripTrailingSlash(resolveApiBase());
+/**
+ * 正式构建**不读** `BEST_GEO_API_BASE`。
+ *
+ * 这个 CLI 的调用方是大模型，而环境变量恰恰是它拉起子进程时完全控制的东西 ——
+ * 比「用户输入」更容易被提示注入污染。留着这个口子，模型不用读任何文件，
+ * 只要换一个 API base 就能让 CLI 自己把密钥发到任意主机，
+ * 「密钥不经过模型」这条核心约定当场作废。
+ *
+ * 联调需要指别处时用 `npm run build:loc` / `build:dev` 重新构建 —— 那是构建期行为，模型碰不到。
+ */
+function resolveApiBase() {
+    if (BUILD_ENV === "prod") {
+        return BUILD_API_BASE;
+    }
+    return process.env.BEST_GEO_API_BASE ?? BUILD_API_BASE;
+}
+/**
+ * 设备 ID 前缀。跟着包走 —— 两个包必须生成各自的设备身份，
+ * 否则一台机器上装了两个包，dev 的设备 ID 会被拿去 claim prod。
+ * 长度上限（前缀 + UUID ≤ 50）由 stamp-env.mjs 在构建期校验。
+ */
+export const DEVICE_ID_PREFIX = BUILD_DEVICE_PREFIX;
+/** 本地录入页的存活上限 */
+export const LOCAL_SERVER_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * 单次服务端请求的超时。
+ *
+ * 必须有：SKILL 明确要求模型「保持进程运行、等它自己退出」，
+ * 服务端半开连接时没有超时就是永久挂起 —— 模型会照着指令一直等下去。
+ */
+export const REQUEST_TIMEOUT_MS = 30 * 1000;
+function stripTrailingSlash(url) {
+    return url.replace(/\/+$/, "");
+}

package/dist/credentials.js

@@ -0,0 +1,54 @@
+import { readConfig, updateConfig } from "./store.js";
+/**
+ * 凭据读写（设计文档 §6.4）。
+ *
+ * 只有两种状态：
+ * - `active`：服务端已确认绑定本机，业务请求用它；
+ * - `pending`：刚录入、还没被 claim 确认，**不允许用于任何业务请求**。
+ *
+ * 分两态是为了让「新密钥没验通过」和「进程崩在中间」都有确定的收敛路径：
+ * 直接覆盖 active 的话，claim 一失败用户就两头落空 —— 新的没生效，旧的也没了。
+ */
+/** 业务请求可用的密钥。pending 永远不从这里返回 */
+export function loadApiKey() {
+    return readConfig()?.activeCredential?.apiKey ?? null;
+}
+export function loadActive() {
+    return readConfig()?.activeCredential ?? null;
+}
+export function loadPending() {
+    return readConfig()?.pendingCredential ?? null;
+}
+/** 保存待确认密钥。**保留已有 active**：claim 失败时旧授权要原样可用 */
+export function savePending(apiKey) {
+    updateConfig((config) => ({
+        ...config,
+        pendingCredential: { apiKey, startedAt: new Date().toISOString() },
+    }));
+}
+export function clearPending() {
+    updateConfig((config) => ({ ...config, pendingCredential: null }));
+}
+/**
+ * 服务端确认之后，把 pending 原子提升为 active 并清掉旧 active。
+ *
+ * 一次写完，不能拆成「先清 active 再写 active」两步 ——
+ * 崩在中间就是本机既没有旧授权也没有新授权。
+ */
+export function promotePending(summary) {
+    return updateConfig((config) => {
+        const pending = config.pendingCredential;
+        if (!pending) {
+            return config;
+        }
+        return {
+            ...config,
+            activeCredential: { apiKey: pending.apiKey, ...summary },
+            pendingCredential: null,
+        };
+    }).activeCredential;
+}
+/** 清空本机凭据，但保留设备 ID：重新登录要复用同一台设备，不能每次退出都多一台 */
+export function clearCredentials() {
+    updateConfig((config) => ({ ...config, activeCredential: null, pendingCredential: null }));
+}