@infimind-next/ai-hive-mcp 0.3.3 → 0.4.1

package/README.md

@@ -4,38 +4,80 @@
 
 ## 安装
 
-在 MCP 客户端中加入以下配置，把 `<APIKEY>` 换成你在蜂巢 AI 网页端「MCP 接入」里生成的 API Key：
+0.4.1 已发布（2026-10-23）。在 MCP 客户端中加入以下配置，把 `<APIKEY>` 换成你在蜂巢 AI 网页端「MCP 接入」里生成的 MCP 密钥：
 
 ```json
 {
   "mcpServers": {
     "ai-hive": {
       "command": "npx",
-      "args": ["-y", "@infimind-next/ai-hive-mcp@0.3.3", "--key", "<APIKEY>"]
+      "args": ["-y", "@infimind-next/ai-hive-mcp@0.4.1"],
+      "env": { "AI_HIVE_MCP_KEY": "<APIKEY>" }
     }
   }
 }
 ```
 
-要求 Node.js >= 20.19.0。默认请求超时为 300 秒，可通过 `--timeout-ms` 或 `AI_HIVE_MCP_TIMEOUT_MS` 覆盖；无效值回退为 300 秒。WorkBuddy Connector 的启动与认证命令保持引用 `@latest`，Connector 和 Skills 版本仍为 1.2.0。
+手动配置也把密钥放在 `env` 里；`--key` 仍兼容，但会出现在进程参数中，不建议继续使用。
+
+也可以在终端或 Agent 里运行下面的命令，自动检测本机客户端、写入配置并安装技能：
+
+```bash
+AI_HIVE_MCP_KEY=<APIKEY> npx -y @infimind-next/ai-hive-mcp@latest setup
+```
+
+`setup` 会检测 Claude Code、Cursor、Codex、Claude Desktop 和 OpenCode，只写入 `ai-hive` 这一项，保留你已有的 MCP 配置和已有密钥；密钥以环境变量写入配置文件，不放进启动参数。没有密钥且本机没有登录凭证时会直接失败，不会写入一份不可用的配置。Claude Code 和 Codex 会同时安装技能。重复执行是安全的。常用选项：
+
+- `--client cursor,codex`：只处理指定客户端。
+- `--dry-run`：只预览，不写文件。
+- `--skip-skills`：只写 MCP 配置，不安装技能。
+
+要求 Node.js >= 20.19.0。默认请求超时为 300 秒，可通过 `--timeout-ms` 或 `AI_HIVE_MCP_TIMEOUT_MS` 覆盖；无效值回退为 300 秒。WorkBuddy Connector 的启动与认证命令保持引用 `@latest`，Connector 和 Skills 版本仍为 1.2.1。
 
 本包通过标准 MCP stdio 与客户端通信，仅保证与支持 MCP 的客户端配合使用。
 
+## 命令行
+
+没有 MCP 宿主时，也可以用同一个 MCP 密钥直接调用。`run` 会先读取所选线路的报价再提交，金额单位是蜂蜜；只有充值实付金额才是元。输出默认适合人读，加 `--json` 返回原始结构：
+
+```bash
+ai-hive-mcp models --type IMAGE --json     # 列模型与售价
+ai-hive-mcp model <模型 ID> --json          # 查参数契约
+ai-hive-mcp usage --json                    # 查积分与账单汇总
+ai-hive-mcp run <模型 ID> "写一句欢迎语"      # 付费文字调用
+```
+
+`run` 是付费调用，每次都会生成新的 `clientRequestId`；需要重试同一次请求时改用 MCP 的 `chat_text` 并复用原标识。
+
 ## 工具
 
-- `get_user_info`：查询当前用户和普通蜂蜜余额
+- `get_user_info`：查询当前用户和普通蜂蜜积分
 
-专属蜂蜜由服务端按实际模型自动选择抵扣，无需新增调用参数。不能仅凭普通蜂蜜余额为 0 拒绝模型调用；只有实际调用返回余额不足时，才使用 `rechargeUrl` 引导充值并重试。
+专属蜂蜜由服务端按实际模型自动选择抵扣，无需新增调用参数。不能仅凭普通蜂蜜积分为 0 拒绝模型调用；只有实际调用返回积分不足时，才使用 `rechargeUrl` 引导充值并重试。
 
 - `list_models`：按 TEXT、IMAGE 或 VIDEO 查询可用模型与公开价格
 - `get_model`：查询单个模型的参数 schema、媒体要求、计费因素和调用示例
-- `upload_media_from_path`：上传本地图片、视频或音频，返回 mediaId
+- `upload_media_from_path`：上传本地图片、视频、音频或文档，返回 mediaId
 - `chat_text`：文本对话
 - `generate_image`：图片预检或正式生成
 - `generate_video`：视频预检或正式生成
 - `get_material_mode`：查询认证资格和网页授权入口（可选）
 - `quote_video_materials`：获取素材报价（可选）
-- `get_generation_task`：查询生成任务进度和结果
+- `list_generation_tasks`：查询当前账号全部入口的图片、视频任务摘要，最新优先
+- `get_generation_task`：按任务 ID 查询状态、结果和费用
+- `get_billing_summary`：查询当前账户全部入口的账单汇总
+- `list_billing_records`：分页查询账单记录
+- `get_billing_record`：按记录 ID 查询账单详情
+
+### 账单查询
+
+3 个账单工具均为只读，需要所连接服务端支持。查询当前账户在网页、API、MCP 等全部入口的记录，不接受手机号或其他用户 ID。现有模型、任务和账户工具的调用方式不变；本地包版本和发布状态不因本次代码变更而改变。
+
+账单单位为 HONEY（蜂蜜虚拟积分），积分数值沿用服务端的 micros 整数字符串，避免精度损失。消费仅指实际结算，预占、释放分别展示，不计入消费。查询某批生成任务时，传入该批的 `taskIds`，不要用前后积分之差推断批次费用；尚未结算的任务不能当作免费。
+
+`get_billing_summary` 和 `list_billing_records` 支持可选 `from`、`to`、`taskIds`、`publicModelId`、`invocationSource`。不传时间时由服务端使用北京时间今日；指定时间须成对传入含时区的 ISO 8601 字符串，按左闭右开区间 `[from,to)` 查询。`taskIds` 传 1～100 个非空任务 ID。`invocationSource` 可选 `UNKNOWN`、`WEB`、`MCP`、`WORKBUDDY`、`QWENWORK`、`DOUBAO_WORK`、`MIAOSHOU`、`OPENAPI`。
+
+`list_billing_records` 的 `pageSize` 默认 20、最多 100，后续分页原样传回 `cursor`。`get_billing_record` 接收列表返回的 `recordId`，例如 `charge:<id>` 或 `reservation:<id>`。这些工具不请求活动或公告通知。
 
 ### 认证素材模式
 
@@ -53,14 +95,20 @@
 
 1. 用 `list_models` 选择模型，记录 `publicModelId`。
 2. 用 `get_model` 查看参数契约，`params` 的字段名、类型、枚举值和默认值逐项来自返回的 `paramsSchema`。
-3. 调用 `generate_image` 或 `generate_video` 时传 `dryRun: true` 预检，核对返回的 `estimatedReservationMicros` 估价（单位：人民币 micros，1 元 = 1,000,000 micros）。
+3. 调用 `generate_image` 或 `generate_video` 时传 `dryRun: true` 预检，核对返回的 `estimatedReservationMicros` 估价（单位：蜂蜜 micros，1,000,000 micros = 1 蜂蜜；只有充值实付金额使用元）。
 4. 确认费用后去掉 `dryRun` 正式生成，`params` 替换为预检返回的 `resolvedParams`，并传入预检返回的 `pricingSnapshot` 和本次调用稳定唯一的 `clientRequestId`。
-5. 用 `get_generation_task` 查询任务进度和结果，不重复创建任务。
+5. 用 `get_generation_task` 查询任务进度、结果和费用，不重复创建任务。
+
+需要找回近期任务时，使用 `list_generation_tasks`。可选 `publicModelId` 筛选模型，`page` 默认 1，`pageSize` 默认 20、最多 50。返回 `{tasks,total,page,pageSize}`，按创建时间和任务 ID 倒序；列表仅含任务与子任务 ID、模型、类型、创建时间、批量数量、160 字符以内提示词摘要、状态和进度，完整参数、结果地址及费用见详情。列表是只读工具，不返回公告或消耗通知额度。
+
+详情默认包含 `billing`：金额单位为蜂蜜，`currency=CNY` 仅为历史兼容编码，不作为展示币种；公开价格快照、预估金额 `estimatedReservationMicros`、已入账金额 `settledChargeMicros` 和 `settlementComplete`。金额为 micros 字符串；结算未完成时已入账金额尚非最终费用，不能把 0 当免费。`billing:null` 表示费用暂不可读，任务结果仍可用。关闭通知不影响费用。钱包继续用 `get_user_info`。
+
+远程 MCP 随服务端部署获得列表能力，本地 MCP 需升级到 0.3.4。新版客户端连接旧服务端不支持的列表端点时，会提示继续按任务 ID 查询。已发布的旧客户端无需修改详情调用即可透传 `billing`；严格拒绝新增响应字段的自定义消费者需更新响应校验规则。
 
 ## 重试与价格变化
 
 - 传输中断或超时后重试：复用同一个 `clientRequestId` 和相同业务参数，不会重复扣费。
-- 修正参数、余额或媒体问题后重试：必须使用新的 `clientRequestId`。
+- 修正参数、积分或媒体问题后重试：必须使用新的 `clientRequestId`。
 - 正式生成提示价格已更新：保持业务参数和原 `clientRequestId` 不变，重新预检获取最新 `pricingSnapshot` 后重试。
 - 返回 `REQUEST_OUTCOME_UNKNOWN`：停止自动重试，联系管理员核查。
 
@@ -68,13 +116,23 @@
 
 用户提供普通素材即可，后台自动处理认证。使用对应认证模型与当前价格快照，先 dryRun 预检资格、素材和费用；通过后沿用标准版提交格式，认证字段和专用报价工具都可省略。收到任务 ID 后只查询原任务。
 
-仅缺少授权、充值资格或余额时向用户说明必要操作，并提供[认证与充值入口](https://ai-hive.iclip.cn/certified-materials#guide)；不擅自换模型提交。费用变化时重新确认，预检通过不代表内容审核通过。
+仅缺少授权、充值资格或积分时向用户说明必要操作，并提供[认证与充值入口](https://ai-hive.iclip.cn/certified-materials#guide)；不擅自换模型提交。费用变化时重新确认，预检通过不代表内容审核通过。
 
 更新信息仅在用户询问或与当前任务有关时介绍，不向用户转述内部参数、错误码、报价与重试机制。客户端可选升级提示默认静默，仅开启 `--verbose` 时输出维护诊断。技术维护记录见仓库 `docs/openapi/technical-changelog.md`。
 
 `recoveryAction` 是给调用端的恢复指引，不要逐字转成用户待办。响应中断用原 `clientRequestId` 和相同参数恢复；明确失败后再次生成，或改变报价/输入时，使用新请求标识。结果未知时先核查，不自动重建付费任务。
 
-当前客户端版本为 0.3.2，已于 2026-10-08 发布。发布物、兼容验证与服务端验收边界见 [0.3.2 发布记录](../../docs/release/mcp-0.3.2-runbook.md)。
+0.4.1 已发布（2026-10-23），registry 最新版本为 0.4.1。发布物、兼容验证与服务端验收边界见 [0.3.2 发布记录](../../docs/release/mcp-0.3.2-runbook.md)。
+
+### 0.4.1：修正发布说明
+
+0.4.1 仅修正 npm 首页的 README 发布状态文案，功能与 0.4.0 相同。
+
+### 0.4.0：一条命令接入
+
+新增 `setup` 命令：检测本机客户端、写入 MCP 配置、安装随包发布的 5 个技能，并用 `user-info` 验证连接。新增 `models`、`model`、`usage`、`run` 四个命令行子命令，让没有 MCP 宿主的 Agent 也能选型、试跑和查账。`setup` 写入的配置统一走 `AI_HIVE_MCP_KEY`，MCP 服务的启动参数里不再带密钥。0.4.0 与 0.4.1 均已发布，`@latest` 指向 0.4.1。
+
+向下兼容：0.3.3 的 12 个工具名称、入参和返回保持不变，0.4.0 只新增 4 个只读工具；`server`、`auth`、`status`、`logout` 的行为不变。旧服务端不接受 `detail` 参数时，`list_models` 会自动去掉它重试一次。账单工具需要服务端已部署账单接口，未部署时会提示到控制台查看，不影响其他工具。
 
 ### 0.3.2：通知协商与直接上传
 
@@ -88,3 +146,11 @@
 兼容模式（COMPAT）下，账户 GET 和 POST 常驻返回进行中的旧充值活动，不占用模型调用的每日活动通知次数。原有付费请求仍按用户每天首次成功调用返回活动；重放、恢复与 dryRun 不重复通知。管理员启用通知管理（MANAGED）后按入口设置返回；旧客户端保留 `activePromotion` 结构，功能公告通过支持新扩展的客户端返回。
 
 0.3.2 中，CLI login/status 的凭证检查使用账户 GET 并明确发送 `X-AI-Hive-Announcements: 0`，完整验证凭证后仅返回账户核心字段、`activePromotion: null`，不写通知台账、共享次数或最短间隔状态。SDK 的 POST 404/405 后默认 GET 回退仍返回兼容活动。
+
+### 0.3.3：简化提示与报价对象兼容
+
+工具说明精简为用途和必要输入；充值活动仅说明优惠、截止时间和入口。未拥有专属蜂蜜的账户不介绍相关信息。报价支持嵌套对象与 JSON 字符串，沿用服务端校验与原有支付规则。
+
+### 0.3.4：任务列表与详情费用（随 0.4.0 发布）
+
+新增 `list_generation_tasks`；现有详情调用默认返回费用，API 与 MCP 使用相同口径。推送、服务端部署和 npm 发布需另行授权。

package/dist/api-client.d.ts

@@ -1,3 +1,4 @@
+import type { BillingQueryInput, ListBillingRecordsInput } from "./schemas.js";
 import type { BearerTokenProvider } from "./auth-token-provider.js";
 import { type McpClientInfo } from "./client-info.js";
 import { type UpdateNotifier } from "./update-notifier.js";
@@ -12,6 +13,7 @@ type AiHiveApiClientInput = {
     fetchImpl?: FetchImpl;
     clientInfoProvider?: () => McpClientInfo | undefined;
     updateNotifier?: UpdateNotifier;
+    clientKind?: "codex-launcher";
 };
 export declare class AiHiveApiError extends Error {
     readonly status: number | undefined;
@@ -39,6 +41,7 @@ export declare class AiHiveApiClient {
     private readonly fetchImpl;
     private readonly clientInfoProvider?;
     private readonly updateNotifier?;
+    private readonly clientKind?;
     constructor(input: AiHiveApiClientInput);
     private withTimeout;
     private request;
@@ -55,6 +58,18 @@ export declare class AiHiveApiClient {
     generateImage(input: unknown, options?: AnnouncementOptions): Promise<unknown>;
     generateVideo(input: unknown, options?: AnnouncementOptions): Promise<unknown>;
     private requestGeneration;
+    private billingQuery;
+    getBillingSummary(input: BillingQueryInput): Promise<unknown>;
+    listBillingRecords(input: ListBillingRecordsInput): Promise<unknown>;
+    getBillingRecord(input: {
+        recordId: string;
+    }): Promise<unknown>;
+    private withBillingSupport;
+    listGenerationTasks(input: {
+        publicModelId?: string;
+        page?: number;
+        pageSize?: number;
+    }): Promise<unknown>;
     getGenerationTask(input: {
         taskId: string;
     }, options?: AnnouncementOptions): Promise<unknown>;

package/dist/api-client.js

@@ -15,8 +15,8 @@ export class AiHiveApiError extends Error {
         this.name = "AiHiveApiError";
     }
 }
-const GET_MODEL_UNSUPPORTED_MESSAGE = "当前 AI-HIVE 服务端版本不支持 get_model，请先升级服务端后再试";
-const DRY_RUN_UNSUPPORTED_MESSAGE = "当前 AI-HIVE 服务端版本不支持 dryRun，请先升级服务端后再试";
+const GET_MODEL_UNSUPPORTED_MESSAGE = "当前接入暂时无法读取模型详情（get_model），请确认 API 地址和模型 ID；如果仍有问题，请联系技术支持。";
+const DRY_RUN_UNSUPPORTED_MESSAGE = "当前接入暂不支持 dryRun，请联系技术支持确认预检方式；不要用正式生成代替预检。";
 function formatIssue(value) {
     if (typeof value === "string") {
         return value;
@@ -93,6 +93,7 @@ export class AiHiveApiClient {
     fetchImpl;
     clientInfoProvider;
     updateNotifier;
+    clientKind;
     constructor(input) {
         this.endpoint = input.endpoint.replace(/\/+$/, "");
         this.tokenProvider = input.tokenProvider;
@@ -100,6 +101,7 @@ export class AiHiveApiClient {
         this.fetchImpl = input.fetchImpl ?? fetch;
         this.clientInfoProvider = input.clientInfoProvider;
         this.updateNotifier = input.updateNotifier;
+        this.clientKind = input.clientKind;
     }
     async withTimeout(operation) {
         const controller = new AbortController();
@@ -157,6 +159,7 @@ export class AiHiveApiClient {
             signal,
             headers: {
                 Authorization: `Bearer ${token}`,
+                ...(this.clientKind ? { "x-ai-hive-client": this.clientKind } : {}),
                 ...(encodedClientInfo
                     ? { [MCP_CLIENT_INFO_HEADER]: encodedClientInfo }
                     : {}),
@@ -220,15 +223,33 @@ export class AiHiveApiClient {
         });
     }
     async listModels(input, options) {
-        const query = new URLSearchParams();
-        if (typeof input.modelType === "string") {
-            query.set("modelType", input.modelType);
+        const buildPath = (withDetail) => {
+            const query = new URLSearchParams();
+            if (typeof input.modelType === "string") {
+                query.set("modelType", input.modelType);
+            }
+            if (withDetail && typeof input.detail === "string") {
+                query.set("detail", input.detail);
+            }
+            const serialized = query.toString();
+            return `/mcp/models${serialized ? `?${serialized}` : ""}`;
+        };
+        try {
+            return redactInternalPricing(await this.request(buildPath(true), {
+                headers: announcementHeaders(options),
+            }));
         }
-        if (typeof input.detail === "string") {
-            query.set("detail", input.detail);
+        catch (error) {
+            // 旧服务端的严格入参不认识 detail; 去掉它重试一次, 让新客户端的选型命令继续可用.
+            if (typeof input.detail === "string" &&
+                error instanceof AiHiveApiError &&
+                (error.status === 400 || error.status === 404)) {
+                return redactInternalPricing(await this.request(buildPath(false), {
+                    headers: announcementHeaders(options),
+                }));
+            }
+            throw error;
         }
-        const serialized = query.toString();
-        return redactInternalPricing(await this.request(`/mcp/models${serialized ? `?${serialized}` : ""}`, { headers: announcementHeaders(options) }));
     }
     // getModel 与 listModels 的 detail 参数依赖服务端新部署; 旧服务端会 404 或被
     // strict 入参校验拒绝, 所以 npm 0.3.0 必须在服务端升级之后发布.
@@ -303,6 +324,65 @@ export class AiHiveApiClient {
             throw error;
         }
     }
+    billingQuery(input) {
+        const query = new URLSearchParams();
+        if (input.from !== undefined)
+            query.set("from", input.from);
+        if (input.to !== undefined)
+            query.set("to", input.to);
+        for (const taskId of input.taskIds ?? [])
+            query.append("taskIds", taskId);
+        if (input.publicModelId !== undefined)
+            query.set("publicModelId", input.publicModelId);
+        if (input.invocationSource !== undefined)
+            query.set("invocationSource", input.invocationSource);
+        if (input.pageSize !== undefined)
+            query.set("pageSize", String(input.pageSize));
+        if (input.cursor !== undefined)
+            query.set("cursor", input.cursor);
+        return query.size ? `?${query}` : "";
+    }
+    getBillingSummary(input) {
+        return this.withBillingSupport("账单查询", () => this.request(`/mcp/billing/summary${this.billingQuery(input)}`));
+    }
+    listBillingRecords(input) {
+        return this.withBillingSupport("账单查询", () => this.request(`/mcp/billing/records${this.billingQuery(input)}`));
+    }
+    getBillingRecord(input) {
+        return this.withBillingSupport("账单详情", () => this.request(`/mcp/billing/records/${encodeURIComponent(input.recordId)}`), "账单记录不存在，或当前服务端暂不支持账单查询；请到控制台核对。");
+    }
+    // 0.4.0 会通过 @latest 自动升级到还没有账单接口的旧服务端, 不能把 404 原样抛给用户.
+    async withBillingSupport(feature, request, notFoundMessage = `当前服务端暂不支持${feature}，请到控制台查看积分与消费。`) {
+        try {
+            return await request();
+        }
+        catch (error) {
+            if (error instanceof AiHiveApiError &&
+                (error.status === 404 || error.status === 405)) {
+                throw new Error(notFoundMessage);
+            }
+            throw error;
+        }
+    }
+    async listGenerationTasks(input) {
+        const query = new URLSearchParams();
+        if (input.publicModelId !== undefined)
+            query.set("publicModelId", input.publicModelId);
+        if (input.page !== undefined)
+            query.set("page", String(input.page));
+        if (input.pageSize !== undefined)
+            query.set("pageSize", String(input.pageSize));
+        try {
+            return await this.request(`/mcp/generation/tasks${query.size ? `?${query}` : ""}`);
+        }
+        catch (error) {
+            if (error instanceof AiHiveApiError &&
+                [404, 405].includes(error.status ?? 0)) {
+                throw new Error("当前服务端暂不支持近期任务列表，请先按任务 ID 查询已有任务");
+            }
+            throw error;
+        }
+    }
     getGenerationTask(input, options) {
         return this.request(`/mcp/generation/tasks/${encodeURIComponent(input.taskId)}?include=user-notices`, { headers: announcementHeaders(options) });
     }

package/dist/cli.d.ts

@@ -3,6 +3,7 @@ import { runServer as runMcpServer } from "./server.js";
 import { WorkBuddyCredentialStore } from "./workbuddy-credentials.js";
 import { WorkBuddyOAuthClient } from "./workbuddy-oauth-client.js";
 import { listenForWorkBuddyCallback, type WorkBuddyResultRedirects } from "./workbuddy-loopback.js";
+import { runManagedServer } from "./managed-server.js";
 export type CliDependencies = {
     stdout(line: string): void;
     stderr(line: string): void;
@@ -10,6 +11,9 @@ export type CliDependencies = {
     createOAuthClient(endpoint: string): WorkBuddyOAuthClient;
     listenForCallback: typeof listenForWorkBuddyCallback;
     runServer: typeof runMcpServer;
+    runManagedServer: typeof runManagedServer;
+    runSetup(config: McpClientConfig): Promise<number>;
+    runRestCommand(config: McpClientConfig): Promise<number>;
 };
 export declare function runCli(config: McpClientConfig, dependencies?: Partial<CliDependencies>): Promise<number>;
 export declare function createWorkBuddyResultRedirects(webOrigin: string): WorkBuddyResultRedirects;

package/dist/cli.js

@@ -1,9 +1,15 @@
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
 import { normalizeApiEndpoint } from "./auth-token-provider.js";
 import { resolveServerAuth, runServer as runMcpServer } from "./server.js";
+import { defaultRestCommandDependencies, runRestCommand, } from "./rest-commands.js";
+import { runSetup } from "./setup/run-setup.js";
 import { WorkBuddyCredentialStore, } from "./workbuddy-credentials.js";
 import { WorkBuddyOAuthClient } from "./workbuddy-oauth-client.js";
 import { listenForWorkBuddyCallback, } from "./workbuddy-loopback.js";
 import { createPkcePair } from "./workbuddy-pkce.js";
+import { loadManagedConfig } from "./managed-config.js";
+import { runManagedServer } from "./managed-server.js";
 const AUTH_URL_DEADLINE_MS = 10_000;
 const AUTH_CALLBACK_DEADLINE_MS = 5 * 60_000;
 const STATUS_DEADLINE_MS = 8_000;
@@ -28,6 +34,13 @@ export async function runCli(config, dependencies) {
             return runLogout(config, resolved);
         case "server":
             return runMcp(config, resolved);
+        case "setup":
+            return resolved.runSetup(config);
+        case "models":
+        case "model":
+        case "usage":
+        case "run":
+            return resolved.runRestCommand(config);
     }
 }
 function resolveDependencies(config, overrides) {
@@ -46,6 +59,19 @@ function resolveDependencies(config, overrides) {
             : createOAuthClientWithTimeout,
         listenForCallback: overrides?.listenForCallback ?? listenForWorkBuddyCallback,
         runServer: overrides?.runServer ?? runMcpServer,
+        runManagedServer: overrides?.runManagedServer ?? runManagedServer,
+        runSetup: overrides?.runSetup ??
+            ((setupConfig) => runSetup(setupConfig, {
+                home: homedir(),
+                platform: process.platform,
+                env: process.env,
+                // 编译产物在 dist/cli.js, 包根目录的同级 skills 随之发布.
+                skillsRoot: fileURLToPath(new URL("../skills", import.meta.url)),
+                stdout: overrides?.stdout ?? ((line) => console.log(line)),
+                stderr: overrides?.stderr ?? ((line) => console.error(line)),
+            })),
+        runRestCommand: overrides?.runRestCommand ??
+            ((restConfig) => runRestCommand(restConfig, defaultRestCommandDependencies)),
     };
 }
 async function runAuth(config, dependencies) {
@@ -296,6 +322,14 @@ async function revokeAndClear(config, dependencies, store, deadlineAt) {
 }
 async function runMcp(config, dependencies) {
     try {
+        if (config.managedConfig) {
+            await dependencies.runManagedServer({
+                config: await loadManagedConfig(config.managedConfig),
+                managedConfigPath: config.managedConfig,
+                timeoutMs: config.timeoutMs,
+            });
+            return 0;
+        }
         const resolved = await resolveServerAuth(config, dependencies.createStore(config.credentialsFile));
         await dependencies.runServer({
             ...(config.verbose ? { verbose: true } : {}),

package/dist/config.d.ts

@@ -1,13 +1,31 @@
-export type CliCommand = "server" | "auth" | "status" | "logout";
+export type CliCommand = "server" | "auth" | "status" | "logout" | "setup" | "models" | "model" | "usage" | "run";
+export type SetupClientId = "claude-code" | "cursor" | "codex" | "claude-desktop" | "opencode";
+export declare const SETUP_CLIENT_IDS: readonly SetupClientId[];
+export type SetupOptions = {
+    clients: SetupClientId[] | null;
+    dryRun: boolean;
+    skipSkills: boolean;
+};
+export type ModelType = "TEXT" | "IMAGE" | "VIDEO";
 export type McpClientConfig = {
     command: CliCommand;
     endpoint: string;
     endpointExplicit: boolean;
     webOrigin: string;
+    webOriginExplicit?: boolean;
     key: string | null;
     credentialsFile: string;
     timeoutMs: number;
     verbose: boolean;
+    managedConfig?: string;
+    positionals?: string[];
+    json?: boolean;
+    modelId?: string;
+    prompt?: string;
+    modelType?: ModelType;
+    detail?: "lite" | "full";
+    routingMode?: string;
+    setup?: SetupOptions;
 };
 export declare function parseConfig(input: {
     argv: string[];

package/dist/config.js

@@ -1,4 +1,12 @@
 import { resolveWorkBuddyCredentialsFile } from "./workbuddy-credentials.js";
+import { isAbsolute } from "node:path";
+export const SETUP_CLIENT_IDS = [
+    "claude-code",
+    "cursor",
+    "codex",
+    "claude-desktop",
+    "opencode",
+];
 const DEFAULT_ENDPOINT = "https://ai-hive.iclip.cn/api";
 const DEFAULT_WEB_ORIGIN = "https://ai-hive.iclip.cn";
 // 文本对话由上游同步返回, 长推理模型实测可达 157s+ (gpt-6/claude-sonnet 系列).
@@ -10,29 +18,74 @@ const CLI_COMMANDS = new Set([
     "auth",
     "status",
     "logout",
+    "setup",
+    "models",
+    "model",
+    "usage",
+    "run",
 ]);
-const FLAG_OPTIONS = new Set(["verbose"]);
+// setup 的目标由检测结果决定, 不接受位置参数, 避免误把路径当成客户端名.
+const POSITIONAL_COMMANDS = new Set([
+    "models",
+    "model",
+    "usage",
+    "run",
+]);
+const FLAG_OPTIONS = new Set(["verbose", "dry-run", "skip-skills", "json"]);
 const VALUE_OPTIONS = new Set([
     "endpoint",
     "web-origin",
     "key",
     "timeout-ms",
     "credentials-file",
+    "managed-config",
+    "client",
+    "model",
+    "prompt",
+    "type",
+    "detail",
+    "routing-mode",
 ]);
+function parseClientIds(value) {
+    const ids = value
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+    if (ids.length === 0) {
+        throw new Error("选项缺少值");
+    }
+    for (const id of ids) {
+        if (!SETUP_CLIENT_IDS.includes(id)) {
+            throw new Error("未知客户端");
+        }
+    }
+    return ids;
+}
 export function parseConfig(input) {
     const args = input.argv.slice(2);
     const values = new Map();
     const flags = new Set();
+    const positionals = [];
     let command = "server";
     let commandSeen = false;
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
-        if (!arg?.startsWith("--")) {
-            if (commandSeen || !CLI_COMMANDS.has(arg)) {
-                throw new Error("未知命令");
+        if (arg === undefined) {
+            break;
+        }
+        if (!arg.startsWith("--")) {
+            if (!commandSeen) {
+                if (!CLI_COMMANDS.has(arg)) {
+                    throw new Error("未知命令");
+                }
+                command = arg;
+                commandSeen = true;
+                continue;
             }
-            command = arg;
-            commandSeen = true;
+            if (!POSITIONAL_COMMANDS.has(command)) {
+                throw new Error("未知参数");
+            }
+            positionals.push(arg);
             continue;
         }
         const name = arg.slice(2);
@@ -54,13 +107,22 @@ export function parseConfig(input) {
         input.env.AI_HIVE_MCP_TIMEOUT_MS ??
         String(DEFAULT_TIMEOUT_MS), 10);
     const endpointOverride = values.get("endpoint") ?? input.env.AI_HIVE_API_ENDPOINT;
-    return {
+    const managedConfig = values.get("managed-config");
+    if (managedConfig &&
+        (!isAbsolute(managedConfig) ||
+            command !== "server" ||
+            ["key", "endpoint", "credentials-file", "web-origin"].some((name) => values.has(name)))) {
+        throw new Error("受管图片工具需要独立配置，请从 AI-HIVE 启动器打开");
+    }
+    const webOriginExplicit = values.has("web-origin") || input.env.AI_HIVE_WEB_ORIGIN !== undefined;
+    const config = {
         command,
         endpoint: endpointOverride ?? DEFAULT_ENDPOINT,
         endpointExplicit: endpointOverride !== undefined,
         webOrigin: values.get("web-origin") ??
             input.env.AI_HIVE_WEB_ORIGIN ??
             DEFAULT_WEB_ORIGIN,
+        ...(webOriginExplicit ? { webOriginExplicit: true } : {}),
         key: values.get("key") ?? input.env.AI_HIVE_MCP_KEY ?? null,
         credentialsFile: values.get("credentials-file") ??
             resolveWorkBuddyCredentialsFile(input.env),
@@ -68,5 +130,40 @@ export function parseConfig(input) {
             ? timeoutMs
             : DEFAULT_TIMEOUT_MS,
         verbose: flags.has("verbose") || input.env.AI_HIVE_MCP_VERBOSE === "true",
+        ...(managedConfig ? { managedConfig } : {}),
     };
+    if (POSITIONAL_COMMANDS.has(command)) {
+        config.positionals = positionals;
+        config.json = flags.has("json");
+    }
+    if (command === "setup") {
+        const clientValue = values.get("client");
+        config.setup = {
+            clients: clientValue ? parseClientIds(clientValue) : null,
+            dryRun: flags.has("dry-run"),
+            skipSkills: flags.has("skip-skills"),
+        };
+    }
+    if (command === "models") {
+        const type = values.get("type");
+        if (type && !["TEXT", "IMAGE", "VIDEO"].includes(type)) {
+            throw new Error("参数无效");
+        }
+        config.modelType = type;
+        const detail = values.get("detail");
+        if (detail && !["lite", "full"].includes(detail)) {
+            throw new Error("参数无效");
+        }
+        config.detail = detail;
+    }
+    if (command === "model") {
+        config.modelId = values.get("model") ?? positionals[0];
+        config.routingMode = values.get("routing-mode");
+    }
+    if (command === "run") {
+        config.modelId = values.get("model") ?? positionals[0];
+        config.prompt = values.get("prompt") ?? positionals.slice(1).join(" ");
+        config.routingMode = values.get("routing-mode");
+    }
+    return config;
 }

package/dist/index.js

@@ -3,7 +3,15 @@ import { runCli } from "./cli.js";
 import { parseConfig } from "./config.js";
 function safeTopLevelMessage(error) {
     if (error instanceof Error &&
-        ["未知命令", "未知选项", "选项缺少值"].includes(error.message)) {
+        [
+            "未知命令",
+            "未知选项",
+            "选项缺少值",
+            "未知参数",
+            "未知客户端",
+            "参数无效",
+            "受管图片工具需要独立配置，请从 AI-HIVE 启动器打开",
+        ].includes(error.message)) {
         return error.message;
     }
     return "命令执行失败";