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

package/dist/server.js

@@ -1,7 +1,7 @@
 import { toolResultContent } from "./user-notices.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { chatTextShape, generateImageShape, generateVideoShape, getGenerationTaskShape, getModelShape, listModelsShape, } from "./schemas.js";
+import { billingQueryInputSchema, listBillingRecordsInputSchema, getBillingRecordInputSchema, billingQueryShape, listBillingRecordsShape, getBillingRecordShape, chatTextShape, generateImageShape, generateVideoShape, getGenerationTaskShape, getModelShape, listModelsShape, listGenerationTasksShape, } from "./schemas.js";
 import { z } from "zod";
 import { AiHiveApiClient, AiHiveApiError } from "./api-client.js";
 import { normalizeApiEndpoint, StaticBearerTokenProvider, WorkBuddyTokenProvider, } from "./auth-token-provider.js";
@@ -9,7 +9,7 @@ import { readMcpClientInfo } from "./client-info.js";
 import { createUpdateNotifier } from "./update-notifier.js";
 import { uploadMediaFromPath } from "./local-media.js";
 import { WorkBuddyOAuthClient } from "./workbuddy-oauth-client.js";
-export const SERVER_VERSION = "0.3.3";
+export const SERVER_VERSION = "0.4.1";
 const DEPRECATED_ATTACHMENT_IDS_MESSAGE = "attachmentIds 已废弃，请使用 messages[].mediaIds";
 const SNAPSHOT_PARSE_FAILURE_MESSAGE = "pricingSnapshot 格式不正确，应为 list_models 返回的快照对象，也可以省略该字段由客户端自动获取";
 const SNAPSHOT_ARRAY_MISMATCH_MESSAGE = "pricingSnapshot 数组中没有匹配当前模型和 routingMode 的快照，请传入 list_models 返回的对应快照对象，或省略该字段由客户端自动获取";
@@ -17,7 +17,7 @@ const SNAPSHOT_IDENTITY_MISMATCH_MESSAGE = "pricingSnapshot 的 publicModelId
 const MODEL_UNAVAILABLE_MESSAGE = "模型当前不可用或不支持该路由模式，请重新调用 list_models 获取最新模型信息";
 // 此文案与 @ai-hive/contracts 的 USER_INFO_TOOL_* 常量保持一致; 独立发布的客户端不引入运行依赖.
 const USER_INFO_TOOL_TITLE = "查看蜂巢账户信息";
-const USER_INFO_TOOL_DESCRIPTION = "查看你的蜂巢账户资料、可用余额和充值入口。";
+const USER_INFO_TOOL_DESCRIPTION = "查看你的蜂巢账户资料、可用积分和充值入口。";
 function content(value) {
     const result = Array.isArray(value)
         ? { models: value }
@@ -130,14 +130,16 @@ export function createToolDefinitions(client) {
         },
         {
             name: "list_models",
-            description: "按 TEXT、IMAGE 或 VIDEO 查询可用模型及价格；detail=lite 用于选型，detail=full 返回完整信息。",
+            title: "查询可用模型与价格",
+            description: "按 TEXT、IMAGE 或 VIDEO 查询可用模型与价格，售价单位是蜂蜜。detail=lite 用于选型，detail=full 返回完整契约。",
             schema: listModelsShape,
             annotations: { readOnlyHint: false },
             handler: async (args) => content(await client().listModels(args, { announcements: true })),
         },
         {
             name: "get_model",
-            description: "按 publicModelId 查询单个模型的参数 schema、媒体要求、计费因素和示例；传 routingMode 可获取线路专属契约。",
+            title: "查询模型调用契约",
+            description: "按 publicModelId 查询模型的参数结构、媒体要求、计费因素和调用示例。调用或生成前应以此结果为准；传 routingMode 可只取该线路的契约。",
             schema: getModelShape,
             annotations: { readOnlyHint: false },
             handler: async (args) => {
@@ -147,18 +149,20 @@ export function createToolDefinitions(client) {
         },
         {
             name: "upload_media_from_path",
-            annotations: { readOnlyHint: false },
-            description: "上传本地图片、视频、音频或文档并返回 mediaId。",
+            title: "上传本地媒体",
+            description: "上传本机图片、视频、音频或文档并返回 mediaId。图片理解和生成前的素材都先走这一步。",
             schema: {
                 path: z.string().min(1),
                 filename: z.string().min(1).optional(),
                 contentType: z.string().min(1).optional(),
             },
+            annotations: { readOnlyHint: false },
             handler: async (args) => content(await uploadMediaFromPath(client(), args)),
         },
         {
             name: "create_media_upload",
-            description: "为媒体文件创建短期上传地址，按返回的 method 和 headers PUT 原始字节。",
+            title: "创建媒体上传",
+            description: "为媒体文件创建短期上传地址。传 filename、contentType、sizeBytes，再按返回的 method 和 headers 把文件原始字节 PUT 到该地址。",
             schema: {
                 filename: z.string().min(1),
                 contentType: z.string().min(1),
@@ -169,7 +173,8 @@ export function createToolDefinitions(client) {
         },
         {
             name: "complete_media_upload",
-            description: "确认媒体上传完成，返回可用于模型调用的 mediaId。",
+            title: "确认媒体上传完成",
+            description: "原始字节 PUT 完成后校验对象大小和类型，把 mediaId 标记为可用于模型调用。",
             schema: { mediaId: z.string().min(1) },
             annotations: { readOnlyHint: false },
             handler: async (args) => content(await client().completeMediaUpload(String(args.mediaId), {
@@ -178,7 +183,8 @@ export function createToolDefinitions(client) {
         },
         {
             name: "chat_text",
-            description: "使用指定模型生成文本，返回本次对话结果。",
+            title: "调用文本模型",
+            description: "用指定模型生成文本，是付费调用。",
             schema: chatTextShape,
             annotations: { readOnlyHint: false },
             handler: async (args) => {
@@ -189,7 +195,8 @@ export function createToolDefinitions(client) {
         },
         {
             name: "generate_image",
-            description: "使用指定模型生成图片；dryRun=true 可先检查输入并预估费用。",
+            title: "生成图片",
+            description: "用指定模型生成图片，是付费调用；dryRun=true 可先检查输入并查看预估费用（单位是蜂蜜）。",
             schema: generateImageShape,
             annotations: { readOnlyHint: false },
             handler: async (args) => {
@@ -199,7 +206,8 @@ export function createToolDefinitions(client) {
         },
         {
             name: "generate_video",
-            description: "使用指定模型生成视频；dryRun=true 可先检查输入并预估费用。",
+            title: "生成视频",
+            description: "用指定模型生成视频，是付费调用；dryRun=true 可先检查参数、素材和预估费用（单位是蜂蜜）。缺素材可以估价，但不能正式生成。",
             schema: generateVideoShape,
             annotations: { readOnlyHint: false },
             handler: async (args) => {
@@ -209,15 +217,16 @@ export function createToolDefinitions(client) {
         },
         {
             name: "get_material_mode",
-            annotations: { readOnlyHint: false },
-            description: "查询认证版服务状态、授权与累计充值资格。已满足条件时直接继续；仅未授权时请用户本人打开 actionUrl 阅读并同意，不得代替用户授权。累计充值资格与钱包余额分别检查。",
+            title: "查询素材认证资格",
+            description: "查询素材认证资格和授权页面。授权必须由用户本人完成；未授权时把 actionUrl 交给用户阅读并同意，不要代替用户操作。",
             schema: {},
+            annotations: { readOnlyHint: false },
             handler: async () => content(await client().getMaterialMode({ announcements: true })),
         },
         {
             name: "quote_video_materials",
-            annotations: { readOnlyHint: false },
-            description: "查询视频素材处理费用。此工具可选；费用变化时先向用户确认。",
+            title: "查询认证素材报价",
+            description: "为认证视频素材报价并冻结素材，返回的 id 作为 materialQuoteId 传给 generate_video；此工具可选，费用变化时先向用户确认。",
             schema: {
                 publicModelId: generateVideoShape.publicModelId,
                 routingMode: generateVideoShape.routingMode,
@@ -230,6 +239,7 @@ export function createToolDefinitions(client) {
                 pricingSnapshot: generateVideoShape.pricingSnapshot,
                 params: generateVideoShape.params,
             },
+            annotations: { readOnlyHint: false },
             handler: async (args) => {
                 const body = await resolvePricingSnapshot(client, "VIDEO", {
                     ...args,
@@ -239,9 +249,83 @@ export function createToolDefinitions(client) {
                 return content(await client().quoteVideoMaterials(body, { announcements: true }));
             },
         },
+        {
+            name: "get_billing_summary",
+            title: "查询账单汇总",
+            description: "查询当前账户在网页、API、MCP 等全部入口的实际结算消费，数值单位是蜂蜜；预占和释放单列，不算消费。不填时间默认北京时间今日，自选时间按 [from,to) 查询。查指定生成批次传 taskIds，并覆盖全部结算日期；积分差不能代替账单。任务缺失或结算未完成时，合计不是最终费用。",
+            schema: billingQueryShape,
+            inputSchema: z.object(billingQueryShape).strict(),
+            annotations: {
+                readOnlyHint: true,
+                idempotentHint: true,
+                destructiveHint: false,
+                openWorldHint: false,
+            },
+            handler: async (args) => {
+                const api = client();
+                if (!api.getBillingSummary)
+                    throw new Error("当前客户端暂不支持账单查询，请更新客户端后重试");
+                return content(await api.getBillingSummary(billingQueryInputSchema.parse(args)));
+            },
+        },
+        {
+            name: "list_billing_records",
+            title: "查询账单记录",
+            description: "分页查询当前账户全部入口的账单记录，数值单位是蜂蜜；实际结算消费与预占、释放分别展示，预占和释放不算消费。时间为 [from,to)，不填默认北京时间今日；用 taskIds 查指定批次，积分差不能代替账单。",
+            schema: listBillingRecordsShape,
+            inputSchema: z.object(listBillingRecordsShape).strict(),
+            annotations: {
+                readOnlyHint: true,
+                idempotentHint: true,
+                destructiveHint: false,
+                openWorldHint: false,
+            },
+            handler: async (args) => {
+                const api = client();
+                if (!api.listBillingRecords)
+                    throw new Error("当前客户端暂不支持账单查询，请更新客户端后重试");
+                return content(await api.listBillingRecords(listBillingRecordsInputSchema.parse(args)));
+            },
+        },
+        {
+            name: "get_billing_record",
+            title: "查询账单详情",
+            description: "按 recordId 查询当前账户的账单详情，数值单位是蜂蜜；区分实际结算消费与预占、释放，预占和释放不算消费。记录 ID 来自 list_billing_records。",
+            schema: getBillingRecordShape,
+            inputSchema: getBillingRecordInputSchema,
+            annotations: {
+                readOnlyHint: true,
+                idempotentHint: true,
+                destructiveHint: false,
+                openWorldHint: false,
+            },
+            handler: async (args) => {
+                const api = client();
+                if (!api.getBillingRecord)
+                    throw new Error("当前客户端暂不支持账单查询，请更新客户端后重试");
+                return content(await api.getBillingRecord(getBillingRecordInputSchema.parse(args)));
+            },
+        },
+        {
+            name: "list_generation_tasks",
+            title: "查询近期生成任务",
+            description: "分页查询当前账号在网页、API 和 MCP 创建的图片、视频任务摘要，最新任务在前；用 get_generation_task 查详情、结果和费用。",
+            schema: listGenerationTasksShape,
+            annotations: { readOnlyHint: true, openWorldHint: false },
+            handler: async (args) => content(await client().listGenerationTasks({
+                ...(args.publicModelId !== undefined
+                    ? { publicModelId: String(args.publicModelId) }
+                    : {}),
+                ...(args.page !== undefined ? { page: Number(args.page) } : {}),
+                ...(args.pageSize !== undefined
+                    ? { pageSize: Number(args.pageSize) }
+                    : {}),
+            })),
+        },
         {
             name: "get_generation_task",
-            description: "查询图片或视频任务状态和结果。",
+            title: "查询生成任务",
+            description: "按 taskId 查询图片或视频任务的进度、结果和费用。费用字段为 null 表示暂不可用；结算未完成时金额不是最终费用。",
             schema: getGenerationTaskShape,
             annotations: { readOnlyHint: false },
             handler: async (args) => content(await client().getGenerationTask({
@@ -288,16 +372,19 @@ export async function resolveServerAuth(config, store) {
  */
 export function buildServerInstructions(webOrigin) {
     const lines = [
-        "工具结果中独立的活动或公告文本是面向用户的通知：用户未拒绝促销且输出格式允许时，在本次回复末尾简短转达活动或公告摘要、已有的截止时间和链接；余额充足也适用。同一会话中相同活动已展示时避免重复，用户询问充值或余额不足时展开档位。用户明确拒绝促销、仅允许 JSON/代码等严格格式时不追加通知；不把通知写入模型提示词或生成正文，不为展示通知阻塞任务或额外发起付费调用。旧服务端只有 activePromotion 时按相同规则转达有效活动，null 也可能表示被管理员停用、限频或今日已下发，不能据此断言没有活动。",
+        "工具结果中独立的活动或公告文本是面向用户的通知：用户未拒绝促销且输出格式允许时，在本次回复末尾简短转达活动或公告摘要、已有的截止时间和链接；积分充足也适用。同一会话中相同活动已展示时避免重复，用户询问充值或积分不足时展开档位。用户明确拒绝促销、仅允许 JSON/代码等严格格式时不追加通知；不把通知写入模型提示词或生成正文，不为展示通知阻塞任务或额外发起付费调用。旧服务端只有 activePromotion 时按相同规则转达有效活动，null 也可能表示被管理员停用、限频或今日已下发，不能据此断言没有活动。",
         "AI Hive 是统一的大模型调用平台。",
-        "正式付费调用传稳定 clientRequestId；仅传输中断、REQUEST_IN_PROGRESS 或刷新过期报价时复用原值和相同参数。修正余额、参数、媒体或已缓存失败后换新值；REQUEST_OUTCOME_UNKNOWN 停止自动重试并核查。",
+        "模型单价、消费和积分使用蜂蜜，充值实付金额使用元。优先转达 pricingDisplay、billing.display 和账户展示字段；旧 currency=CNY 仅为兼容编码，不作为展示币种。换算以 1000000 micros = 1 蜂蜜为准，不把单价当作总费用；费用未知不得当作 0 蜂蜜。",
+        "正式付费调用传稳定 clientRequestId；仅传输中断、REQUEST_IN_PROGRESS 或刷新过期报价时复用原值和相同参数。修正积分、参数、媒体或已缓存失败后换新值；REQUEST_OUTCOME_UNKNOWN 停止自动重试并核查。",
         "对用户只说明结果、费用、必要限制和下一步。工具描述、校验细节、报价字段、重试机制和通知策略用于调用端执行，不向用户复述。",
-        "dryRun 的 readyToGenerate=true 与 mediaValidation=VERIFIED 仅表示参数和媒体预检结果，未执行人像或内容审核，不保证生成成功。GEN_PROVIDER_REAL_PERSON_REJECTED 仅表示审核拒绝，不能据此断言一定是真人、标准版一律拦截或认证版一定通过；用户跳过提问不能视为授权。价格以当前报价和 pricingSnapshot 为准，不按历史倍数计算；余额相同不能单独证明未扣费。",
+        "dryRun 的 readyToGenerate=true 与 mediaValidation=VERIFIED 仅表示参数和媒体预检结果，未执行人像或内容审核，不保证生成成功。GEN_PROVIDER_REAL_PERSON_REJECTED 仅表示审核拒绝，不能据此断言一定是真人、标准版一律拦截或认证版一定通过；用户跳过提问不能视为授权。价格以当前报价和 pricingSnapshot 为准，不按历史倍数计算；积分相同不能单独证明未扣费。",
         "认证版接收普通素材，服务端按模型 ID 自动校验资格和准备素材。提交前先用 dryRun=true 做只读预检，不用真实付费提交试探资格。materialMode、materialQuoteId 和专用报价工具均为可选兼容能力；正式提交使用当前 pricingSnapshot 和稳定 clientRequestId。资格不足时明确说明差额或待授权事项，并在回复中展示返回的 helpUrl 或 actionUrl 为可点击链接；未返回链接时使用 https://ai-hive.iclip.cn/certified-materials#guide。保留用户指定模型，不擅自切换模型或继续付费提交。费用变化时重新确认。收到任务 ID 后查询原任务，不重复创建。",
         "latestChange、changelog 和升级信息仅在用户主动询问或与当前任务直接相关时介绍。对用户只说明实际能力、费用、限制、结果和必要操作，不转述字段名、错误码、报价 ID、幂等机制、版本适配或内部排查过程；技术字段和 recoveryAction 供调用端处理，不能替代用户操作说明。用户明确排查接入问题时可以解释所需技术细节。",
-        "可用 get_user_info 查询蜂蜜余额、官网地址和充值入口。按 get_user_info 返回的 rechargeGuide 说明账户支付方式，不主动介绍账户未拥有的额度。不能仅凭钱包余额为 0 拒绝调用。只有实际调用返回余额不足时，才引导用户打开 rechargeUrl 充值后重试。",
-        "先用 list_models(detail=lite) 选型，再用 get_model 读取所选模型契约。上传前可省略媒体做 dryRun：缺素材不等于参数错误，估价为空时不得当作 0 元或上限。用户接受方案后上传，再带真实媒体预检；同参数同费用不重复确认，费用或条件变化才再确认。正式调用原样回传最后一次预检的 pricingSnapshot，金额保留字符串；仅 materialQuoteId 可自动准备，不能据此省略 pricingSnapshot。",
-        "充值提醒只依据本次返回的 activePromotion；有值时用 title、headline 和 promoTiers 转达本场「限时特惠 · 充值加赠」，金额沿用服务端结果，使用「距本场结束」说明 endsAt，并提供 rechargeUrl 的「立即充值」入口。模型调用返回 null 时不追加活动提醒；get_user_info 返回 null 时不推断具体原因。缓存或幂等重放中的 endsAt 已过期时，先重新查询 get_user_info，以新结果为准，不沿用旧截止时间或推算后续活动。",
+        "可用 get_user_info 查询蜂蜜积分、官网地址和充值入口。按 get_user_info 返回的 rechargeGuide 说明账户支付方式，不主动介绍账户未拥有的额度。不能仅凭钱包积分为 0 拒绝调用。只有实际调用返回积分不足时，才引导用户打开 rechargeUrl 充值后重试。",
+        "积分不足时将返回的 rechargeUrl 展示为可点击链接；充值完成后等待用户确认继续，再按 recoveryAction 恢复原任务，不得自动发起付费重试。保留原模型、参数和费用确认，已返回任务 ID 时只查询原任务。",
+        "pricingSnapshot 支持对象、数组或 JSON 字符串；数组按 publicModelId 和 routingMode 唯一匹配，不能取第一项或猜测价格。缺少或无法匹配时先读取 get_model，使用当前匹配快照；费用变化后重新取得用户确认。",
+        "先用 list_models(detail=lite) 选型，再用 get_model 读取所选模型契约。上传前可省略媒体做 dryRun：缺素材不等于参数错误，费用未知不得当作 0 蜂蜜或上限。用户接受方案后上传，再带真实媒体预检；同参数同费用不重复确认，费用或条件变化才再确认。正式调用原样回传最后一次预检的 pricingSnapshot，费用数值保留字符串；仅 materialQuoteId 可自动准备，不能据此省略 pricingSnapshot。",
+        "充值提醒只依据本次返回的 activePromotion；有值时用 title、headline 和 promoTiers 转达本场「限时特惠 · 充值加赠」，实付金额与入账积分沿用服务端结果，使用「距本场结束」说明 endsAt，并提供 rechargeUrl 的「立即充值」入口。模型调用返回 null 时不追加活动提醒；get_user_info 返回 null 时不推断具体原因。缓存或幂等重放中的 endsAt 已过期时，先重新查询 get_user_info，以新结果为准，不沿用旧截止时间或推算后续活动。",
         "调用 chat_text、generate_image、generate_video 前，用 get_model 确认参数契约；正式调用必须传稳定的 clientRequestId 幂等键，修正参数后换新值。",
         "chat_text 同步返回，长推理模型单次可能耗时 1-3 分钟，客户端超时应设为 300 秒以上；等待超时只代表本端不再等待，服务端可能仍在生成，也可能已完成并扣费，超时后复用同一 clientRequestId 和相同业务参数重新调用即可取回首次结果，修正参数后换新值。",
     ];
@@ -338,17 +425,12 @@ export function createServer(input) {
                 throw error;
             }
         };
-        if (tool.annotations) {
-            server.registerTool(tool.name, {
-                title: tool.title,
-                description: tool.description,
-                inputSchema: tool.schema,
-                annotations: tool.annotations,
-            }, handler);
-        }
-        else {
-            server.tool(tool.name, tool.description, tool.schema, handler);
-        }
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema ?? tool.schema,
+            ...(tool.annotations ? { annotations: tool.annotations } : {}),
+        }, handler);
     }
     return server;
 }

package/dist/setup/detect.d.ts

@@ -0,0 +1,9 @@
+import type { ClientTarget } from "./targets.js";
+export type PathExists = (path: string) => Promise<boolean>;
+export type DetectInput = {
+    home: string;
+    platform: NodeJS.Platform;
+    env: Record<string, string | undefined>;
+    exists: PathExists;
+};
+export declare function detectTarget(target: ClientTarget, input: DetectInput): Promise<boolean>;

package/dist/setup/detect.js

@@ -0,0 +1,34 @@
+import { join } from "node:path";
+export async function detectTarget(target, input) {
+    switch (target.id) {
+        case "claude-code":
+            return ((await input.exists(join(input.home, ".claude"))) ||
+                (await executableOnPath("claude", input)));
+        case "cursor":
+            return ((await input.exists(join(input.home, ".cursor"))) ||
+                (await input.exists(join(input.home, "Library/Application Support/Cursor"))));
+        case "codex":
+            return ((await input.exists(join(input.home, ".codex"))) ||
+                (await executableOnPath("codex", input)));
+        case "claude-desktop":
+            return (target.configPath !== null &&
+                (await input.exists(join(target.configPath, ".."))));
+        case "opencode":
+            return ((await input.exists(join(input.home, ".config/opencode"))) ||
+                (await executableOnPath("opencode", input)));
+    }
+}
+async function executableOnPath(name, input) {
+    const pathValue = input.env.PATH ?? "";
+    const extensions = input.platform === "win32" ? ["", ".cmd", ".exe", ".bat"] : [""];
+    for (const directory of pathValue.split(input.platform === "win32" ? ";" : ":")) {
+        if (!directory)
+            continue;
+        for (const extension of extensions) {
+            if (await input.exists(join(directory, `${name}${extension}`))) {
+                return true;
+            }
+        }
+    }
+    return false;
+}

package/dist/setup/merge.d.ts

@@ -0,0 +1,5 @@
+export declare function mergeJsonMcpServers(existing: string | null, name: string, server: unknown): string;
+export declare function mergeOpenCodeServer(existing: string | null, name: string, server: unknown): string;
+export declare function readJsonServerEnv(existing: string | null, field: "mcpServers" | "mcp", name: string): Record<string, string>;
+export declare function upsertCodexServer(existing: string | null, name: string, packageSpec: string, env: Record<string, string>): string;
+export declare function readCodexEnv(lines: string[], targetTable: string): Record<string, string>;

package/dist/setup/merge.js

@@ -0,0 +1,142 @@
+// 所有写入都做"读旧值 -> 只改自己的键 -> 整体写回", 避免覆盖用户已有的 MCP 配置.
+export function mergeJsonMcpServers(existing, name, server) {
+    const document = parseJsonObject(existing);
+    const servers = readRecord(document, "mcpServers");
+    return serialize({
+        ...document,
+        mcpServers: { ...servers, [name]: server },
+    });
+}
+export function mergeOpenCodeServer(existing, name, server) {
+    const document = parseJsonObject(existing);
+    const servers = readRecord(document, "mcp");
+    return serialize({
+        ...document,
+        $schema: typeof document.$schema === "string"
+            ? document.$schema
+            : "https://opencode.ai/config.json",
+        mcp: { ...servers, [name]: server },
+    });
+}
+// 重跑时无密钥也要保留用户已有的 env, 否则一次没导出环境变量的执行就会把配置降级.
+export function readJsonServerEnv(existing, field, name) {
+    const document = parseJsonObject(existing);
+    const servers = readRecord(document, field);
+    const server = servers[name];
+    if (typeof server !== "object" || server === null || Array.isArray(server)) {
+        return {};
+    }
+    const env = server[field === "mcp" ? "environment" : "env"];
+    return readStringRecord(env);
+}
+export function upsertCodexServer(existing, name, packageSpec, env) {
+    const source = existing ?? "";
+    const lines = source.split("\n");
+    const targetTable = `mcp_servers.${name}`;
+    const start = lines.findIndex((line) => tableName(line) === targetTable);
+    if (start === -1) {
+        const prefix = source.length === 0 || source.endsWith("\n") ? "" : "\n";
+        const separator = source.trim().length === 0 ? "" : "\n";
+        return `${source}${prefix}${separator}${codexBlock(name, packageSpec, env)}\n`;
+    }
+    let end = start + 1;
+    while (end < lines.length) {
+        const table = tableName(lines[end]);
+        // 只吞掉同名表及其子表; [mcp_servers.ai_hive_backup] 是另一张表, 必须保留.
+        if (table !== null &&
+            table !== targetTable &&
+            !table.startsWith(`${targetTable}.`)) {
+            break;
+        }
+        end += 1;
+    }
+    const blockLines = lines.slice(start, end);
+    const mergedEnv = {
+        ...readCodexEnv(blockLines, targetTable),
+        ...env,
+    };
+    const before = lines.slice(0, start).join("\n");
+    const after = lines.slice(end).join("\n");
+    return ([before, codexBlock(name, packageSpec, mergedEnv), after]
+        .filter((part) => part.trim().length > 0)
+        .join("\n") + "\n");
+}
+export function readCodexEnv(lines, targetTable) {
+    const envTable = `${targetTable}.env`;
+    const env = {};
+    let inside = false;
+    for (const line of lines) {
+        const table = tableName(line);
+        if (table !== null) {
+            inside = table === envTable;
+            continue;
+        }
+        if (!inside)
+            continue;
+        const match = /^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*"(.*)"\s*$/.exec(line.trim());
+        if (match) {
+            env[match[1]] = match[2].replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+        }
+    }
+    return env;
+}
+function codexBlock(name, packageSpec, env) {
+    const lines = [
+        `[mcp_servers.${name}]`,
+        'command = "npx"',
+        `args = ["-y", ${JSON.stringify(packageSpec)}]`,
+    ];
+    const entries = Object.entries(env);
+    if (entries.length > 0) {
+        lines.push("", `[mcp_servers.${name}.env]`);
+        for (const [key, value] of entries) {
+            lines.push(`${key} = ${JSON.stringify(value)}`);
+        }
+    }
+    return lines.join("\n");
+}
+// 表头可能带行尾注释; 先剥注释再比较, 避免漏掉合法写法导致追加重复表.
+function tableName(line) {
+    const stripped = line.split("#")[0].trim();
+    const match = /^\[([^\]]+)\]$/.exec(stripped);
+    return match ? match[1].trim() : null;
+}
+function readRecord(document, field) {
+    const current = document[field];
+    if (current === undefined) {
+        return {};
+    }
+    if (typeof current !== "object" ||
+        current === null ||
+        Array.isArray(current)) {
+        throw new Error(field === "mcpServers"
+            ? "配置文件里的 mcpServers 不是对象，请手动添加配置"
+            : "配置文件里的 mcp 不是对象，请手动添加配置");
+    }
+    return current;
+}
+function readStringRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(value).flatMap(([key, item]) => typeof item === "string" ? [[key, item]] : []));
+}
+function parseJsonObject(existing) {
+    if (existing === null || existing.trim().length === 0) {
+        return {};
+    }
+    let value;
+    try {
+        value = JSON.parse(existing);
+    }
+    catch {
+        throw new Error("配置文件不是有效 JSON，请手动添加配置");
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("配置文件顶层不是对象，请手动添加配置");
+    }
+    return value;
+}
+function serialize(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}

package/dist/setup/run-setup.d.ts

@@ -0,0 +1,20 @@
+import type { McpClientConfig } from "../config.js";
+export declare const MCP_SERVER_NAME = "ai-hive";
+export declare const MCP_CODEX_SERVER_NAME = "ai_hive";
+export declare const MCP_PACKAGE_SPEC = "@infimind-next/ai-hive-mcp@latest";
+type CommandRunner = (command: string, args: string[]) => Promise<{
+    ok: boolean;
+}>;
+export type SetupDependencies = {
+    home: string;
+    platform: NodeJS.Platform;
+    env: Record<string, string | undefined>;
+    skillsRoot: string;
+    stdout(line: string): void;
+    stderr(line: string): void;
+    runCommand?: CommandRunner;
+    fetchImpl?: typeof fetch;
+};
+type SetupConfig = Pick<McpClientConfig, "key" | "endpoint" | "endpointExplicit" | "webOrigin" | "webOriginExplicit" | "credentialsFile" | "timeoutMs" | "setup">;
+export declare function runSetup(config: SetupConfig, dependencies: SetupDependencies): Promise<number>;
+export {};