best-geo-test 0.1.0

package/capabilities/capabilities.json

@@ -0,0 +1,362 @@
+{
+  "protocolVersion": 1,
+  "capabilities": [
+    {
+      "name": "companies.list",
+      "mode": "read",
+      "guide": "company",
+      "requiresPlan": false,
+      "description": "列出当前密钥被授权的公司。不传 companyId 就是全部授权公司。",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "number",
+            "description": "只看某一家公司"
+          },
+          "name": {
+            "type": "string",
+            "description": "按名称模糊匹配"
+          },
+          "search": {
+            "type": "string",
+            "description": "同时按名称和 ID 搜索"
+          },
+          "page": {
+            "type": "number",
+            "default": 1
+          },
+          "limit": {
+            "type": "number",
+            "default": 20,
+            "maximum": 100
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "companies.get",
+      "mode": "read",
+      "guide": "company",
+      "requiresPlan": false,
+      "description": "按 ID 读取一家公司。ID 必须在授权范围内。",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "companies.create",
+      "mode": "write",
+      "guide": "company",
+      "requiresPlan": true,
+      "description": "新建公司。创建成功后这家公司会自动加入当前密钥的授权范围。",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "公司名称"
+          },
+          "description": {
+            "type": "string",
+            "description": "公司描述"
+          },
+          "aliases": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "公司别名/关键词"
+          }
+        },
+        "required": [
+          "name",
+          "description"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "companies.update",
+      "mode": "write",
+      "guide": "company",
+      "requiresPlan": true,
+      "description": "修改公司。只改传进来的字段，没传的保持不变；数组字段是整体覆盖。",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "companyId": {
+            "type": "number"
+          },
+          "name": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "aliases": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "整体覆盖，不是追加"
+          }
+        },
+        "required": [
+          "companyId"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "products.list",
+      "mode": "read",
+      "guide": "product",
+      "requiresPlan": false,
+      "description": "列出 GEO 项目。传 companyId 可限定到某家公司。",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "companyId": {
+            "type": "number"
+          },
+          "name": {
+            "type": "string"
+          },
+          "search": {
+            "type": "string"
+          },
+          "page": {
+            "type": "number",
+            "default": 1
+          },
+          "limit": {
+            "type": "number",
+            "default": 20,
+            "maximum": 100
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "products.get",
+      "mode": "read",
+      "guide": "product",
+      "requiresPlan": false,
+      "description": "按 ID 读取一个 GEO 项目。",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "products.create",
+      "mode": "write",
+      "guide": "product",
+      "requiresPlan": true,
+      "description": "在指定公司下新建 GEO 项目。",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "companyId": {
+            "type": "number"
+          },
+          "name": {
+            "type": "string"
+          },
+          "keyword": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "关键词"
+          },
+          "targetWord": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "目标词"
+          }
+        },
+        "required": [
+          "companyId",
+          "name",
+          "keyword",
+          "targetWord"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "products.update",
+      "mode": "write",
+      "guide": "product",
+      "requiresPlan": true,
+      "description": "修改 GEO 项目。只改传进来的字段；数组字段是整体覆盖。",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "productId": {
+            "type": "number"
+          },
+          "name": {
+            "type": "string"
+          },
+          "keyword": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "整体覆盖，不是追加"
+          },
+          "targetWord": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "整体覆盖，不是追加"
+          }
+        },
+        "required": [
+          "productId"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "questions.list",
+      "mode": "read",
+      "guide": "question",
+      "requiresPlan": false,
+      "description": "列出搜索问题。可按公司或 GEO 项目限定。",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "companyId": {
+            "type": "number"
+          },
+          "productId": {
+            "type": "number"
+          },
+          "topic": {
+            "type": "string",
+            "description": "按问题文本模糊匹配"
+          },
+          "page": {
+            "type": "number",
+            "default": 1
+          },
+          "limit": {
+            "type": "number",
+            "default": 20,
+            "maximum": 100
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "questions.get",
+      "mode": "read",
+      "guide": "question",
+      "requiresPlan": false,
+      "description": "按 ID 读取一个搜索问题。",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "questions.create",
+      "mode": "write",
+      "guide": "question",
+      "requiresPlan": true,
+      "description": "给 GEO 项目批量新增搜索问题。一次最多 100 条；已存在的、重复的和空值会被跳过，计划摘要里会分别列出。",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "productId": {
+            "type": "number"
+          },
+          "questions": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "maxItems": 100,
+            "description": "问题文本数组，不是换行字符串"
+          },
+          "tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "required": [
+          "productId",
+          "questions"
+        ],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "questions.update",
+      "mode": "write",
+      "guide": "question",
+      "requiresPlan": true,
+      "description": "修改一条搜索问题。",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "questionId": {
+            "type": "number"
+          },
+          "topic": {
+            "type": "string",
+            "description": "问题文本"
+          },
+          "tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "整体覆盖，不是追加"
+          }
+        },
+        "required": [
+          "questionId"
+        ],
+        "additionalProperties": false
+      }
+    }
+  ]
+}

package/dist/api.js

@@ -0,0 +1,111 @@
+import { API_BASE, CLI_VERSION, PROTOCOL_VERSION, REQUEST_TIMEOUT_MS } from "./config.js";
+import { peekDeviceId } from "./device.js";
+import { fail } from "./envelope.js";
+/**
+ * 服务端调用。
+ *
+ * 服务端的 /v1/agent-cli/** 已经返回同一套信封（成功和失败都是），
+ * 所以这里**原样透传**，不重新包装 —— 中间多一层转换就多一处口径漂移的机会。
+ * 只有网络层自身出错时才由 CLI 生成信封。
+ */
+export async function callApi(path, options = {}) {
+    const url = new URL(`${API_BASE}/v1/agent-cli${path}`);
+    for (const [key, value] of Object.entries(options.query ?? {})) {
+        if (value == null)
+            continue;
+        for (const item of Array.isArray(value) ? value : [value]) {
+            url.searchParams.append(key, String(item));
+        }
+    }
+    const headers = {
+        "X-GEO-CLI-Version": CLI_VERSION,
+        "X-GEO-Protocol-Version": String(PROTOCOL_VERSION),
+    };
+    // 设备 ID 只在已经有的时候带上，绝不在这里顺手创建：
+    // 真正需要建它的是 auth login（那条路径显式调 deviceInfo()）。
+    // 在这里创建会让 version --check 这种无授权调用也去写用户目录
+    // 读不出来就不带这个头：version --check 这类无授权命令不该被本机文件状态卡死。
+    // 真正需要设备身份的是 auth login，那条路径显式调 deviceInfo()，权限问题会在那里如实报出来
+    let deviceId = null;
+    try {
+        deviceId = peekDeviceId();
+    }
+    catch {
+        /* 本机配置有问题时照常发请求，由需要它的命令去报错 */
+    }
+    if (deviceId) {
+        headers["X-Device-ID"] = deviceId;
+    }
+    if (options.apiKey) {
+        headers.Authorization = `Bearer ${options.apiKey}`;
+    }
+    if (options.body != null) {
+        headers["Content-Type"] = "application/json";
+    }
+    try {
+        const response = await fetch(url, {
+            method: options.method ?? "GET",
+            headers,
+            body: options.body == null ? undefined : JSON.stringify(options.body),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        const text = await response.text();
+        try {
+            const parsed = JSON.parse(text);
+            // 必须校验形状，不能只 cast。守卫、限流、全局异常过滤器、网关都可能在进我们的模块之前
+            // 返回自己的 JSON（`{"statusCode":401,...}`），那是合法 JSON 但不是信封 ——
+            // 直接透传等于让 stdout 上出现一个没有 code / nextAction 的对象，模型读到的是 undefined。
+            // body 是字面量 null 时更糟：emit 里读 .ok 抛 TypeError，被兜底再 emit 一次，stdout 出现两行
+            if (!isEnvelope(parsed)) {
+                return fail("SERVER_ERROR", `服务端返回了非预期内容（HTTP ${response.status}）`, {
+                    // 这不是服务端的终局裁决，只是「没拿到裁决」，pending 不能因此被清掉
+                    data: { transportFailure: true },
+                });
+            }
+            return parsed;
+        }
+        catch {
+            // 服务端没按信封返回（网关错误页、502 之类）。不把原文透出去：
+            // 里面可能有内部地址和堆栈，而模型会拿它当特征去匹配
+            return fail("SERVER_ERROR", `服务端返回了非预期内容（HTTP ${response.status}）`, {
+                data: { transportFailure: true },
+            });
+        }
+    }
+    catch (error) {
+        return fail("SERVER_ERROR", `无法连接服务端：${error instanceof Error ? error.message : String(error)}`, {
+            data: { transportFailure: true },
+            nextAction: { type: "ask_user", message: "请确认网络可用，以及服务端地址配置正确" },
+        });
+    }
+}
+/** 是不是一个合法信封。只认 ok 和 code 两个字段 —— 它们是模型判断时真正依赖的东西 */
+function isEnvelope(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return typeof candidate.ok === "boolean" && typeof candidate.code === "string";
+}
+/**
+ * 这次失败是「没拿到服务端裁决」，而不是「服务端裁定失败」。
+ *
+ * 两者必须分开：撤销 pending、放弃重试这类不可逆动作，只能建立在服务端真的给了结论上。
+ * 网络不通时把它当成「服务端拒绝」，会把本机唯一的恢复依据删掉。
+ */
+export function isTransportFailure(envelope) {
+    return !envelope.ok && envelope.data?.transportFailure === true;
+}
+/**
+ * 这次失败是不是**服务端的终局裁决**。
+ *
+ * 只有终局裁决才能用来做「撤销 pending」这类不可逆动作。
+ * SERVER_ERROR / RATE_LIMITED / CLI_UPDATE_REQUIRED 都不是裁决 ——
+ * 服务端 500 时,那次绑定到底成没成功谁也不知道,按「拒绝」处理就会把用户刚粘的密钥删掉。
+ */
+export function isServerVerdict(envelope) {
+    if (envelope.ok || isTransportFailure(envelope)) {
+        return false;
+    }
+    return ["AUTH_EXPIRED", "DEVICE_MISMATCH", "ACCESS_DENIED", "AUTH_REQUIRED", "VALIDATION_FAILED"].includes(envelope.code);
+}

package/dist/args.js

@@ -0,0 +1,24 @@
+/**
+ * 极简参数解析：只认 `--key value` 和 `--flag`。
+ *
+ * 不引 commander 之类的库 —— 这个包被全局安装在用户机器上，
+ * 依赖越少，安装越快、供应链面越小。
+ */
+export function parseFlags(argv) {
+    const flags = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (!token.startsWith("--"))
+            continue;
+        const name = token.slice(2);
+        const next = argv[i + 1];
+        if (next && !next.startsWith("--")) {
+            flags[name] = next;
+            i += 1;
+        }
+        else {
+            flags[name] = true;
+        }
+    }
+    return flags;
+}

package/dist/build-env.js

@@ -0,0 +1,7 @@
+/** 由 scripts/stamp-env.mjs 在构建时生成。不要手改，也不要提交 */
+export const BUILD_ENV = "dev";
+export const BUILD_API_BASE = "https://nbgeo.aimusiclj.com";
+export const BUILD_COMMAND_NAME = "best-geo-test";
+export const BUILD_PACKAGE_NAME = "best-geo-test";
+export const BUILD_DEVICE_PREFIX = "bg-test-cli-";
+export const BUILD_VERSION = "0.1.0";