@infimind-next/ai-hive-mcp 0.4.2 → 0.5.0

package/dist/model-response.js

@@ -0,0 +1,296 @@
+import { z } from "zod";
+import { noticeSchema } from "./user-notices.js";
+const routingMode = z.enum(["COST_FIRST", "SPEED_FIRST", "SUCCESS_FIRST"]);
+const reasoningEffort = z.enum([
+    "none",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+]);
+const routingReasoning = z
+    .object({
+    routingMode,
+    reasoningEfforts: z
+        .array(reasoningEffort)
+        .min(1)
+        .refine((levels) => new Set(levels).size === levels.length, {
+        message: "思考档位不能重复",
+    }),
+    defaultReasoningEffort: reasoningEffort.optional(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    if (value.defaultReasoningEffort !== undefined &&
+        !value.reasoningEfforts.includes(value.defaultReasoningEffort)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["defaultReasoningEffort"],
+            message: "默认思考档位不在可用档位中",
+        });
+    }
+});
+const version = z.union([z.literal(1), z.literal(2)]).optional();
+export const modelSectionSchema = z.enum(["parameters", "pricing", "examples"]);
+export const listModelsReadShape = {
+    schemaVersion: version.describe("2 为分页轻目录，不传 detail；1 为旧格式。"),
+    modelType: z.enum(["TEXT", "IMAGE", "VIDEO"]).optional(),
+    detail: z
+        .enum(["lite", "full"])
+        .optional()
+        .describe("仅旧格式使用（schemaVersion=1 或不传版本）；不能与 schemaVersion=2 同传。"),
+    query: z.string().max(200).optional(),
+    routingMode: routingMode.optional(),
+    cursor: z.string().min(1).max(4096).optional(),
+    limit: z.number().int().min(1).max(50).optional(),
+};
+export const getModelReadShape = {
+    schemaVersion: version.describe("2 为分章节详情；1 为旧格式。"),
+    publicModelId: z
+        .string()
+        .min(1)
+        .refine((value) => value.trim().length > 0)
+        .describe("使用 list_models 返回或已确认的 publicModelId，不按模型名称拼接。"),
+    routingMode: routingMode
+        .optional()
+        .describe("未知可用线路时先省略，从详情返回的 routingModes 中选择。"),
+    sections: z.array(modelSectionSchema).max(3).optional(),
+};
+function clean(input) {
+    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+}
+export function parseModelListInput(raw, defaultVersion = 2) {
+    const input = z.object(listModelsReadShape).strict().parse(raw);
+    const selected = input.schemaVersion ?? (input.detail !== undefined ? 1 : defaultVersion);
+    if (selected === 2 && input.detail !== undefined)
+        throw new Error("新版模型查询不能同时使用 detail，请选择查询版本");
+    if (selected === 1 &&
+        [input.query, input.routingMode, input.cursor, input.limit].some((value) => value !== undefined))
+        throw new Error("筛选与分页需要新版模型查询，请选择 schemaVersion=2");
+    return clean({
+        ...input,
+        ...(selected === 2 ? { schemaVersion: 2 } : {}),
+    });
+}
+export function parseModelDetailInput(raw, defaultVersion = 2) {
+    const input = z.object(getModelReadShape).strict().parse(raw);
+    const selected = input.schemaVersion ?? defaultVersion;
+    if (selected !== 2 && input.sections !== undefined)
+        throw new Error("分章节读取需要新版模型查询，请选择 schemaVersion=2");
+    if (input.sections && new Set(input.sections).size !== input.sections.length)
+        throw new Error("模型查询章节不能重复");
+    return clean({
+        ...input,
+        ...(selected === 2 ? { schemaVersion: 2 } : {}),
+    });
+}
+const fileConfig = {
+    enabled: z.boolean(),
+    maxFileSizeBytes: z.number().int().positive(),
+    supportedMimeTypes: z.array(z.string().min(1)).min(1),
+};
+const textConfig = z
+    .object({
+    outputsThinking: z.boolean(),
+    showsThinkingToggle: z.boolean(),
+    attachments: z
+        .object({
+        textExtraction: z
+            .object({
+            ...fileConfig,
+            maxFilesPerMessage: z.number().int().positive().max(5),
+        })
+            .strict(),
+        imageInput: z.object(fileConfig).strict(),
+    })
+        .strict(),
+})
+    .strict();
+// 独立发布的客户端只验证公开传输契约, 完整计费规则仍由服务端校验; 不重写规则或转换价格数值.
+const billingRule = z
+    .object({
+    version: z.union([z.literal(1), z.literal(2), z.literal(3)]),
+    kind: z.enum(["TEXT_TOKEN", "IMAGE_GENERATION", "VIDEO_GENERATION"]),
+    rules: z.array(z.record(z.unknown())).optional(),
+    tiers: z.array(z.record(z.unknown())).optional(),
+})
+    .passthrough()
+    .superRefine((value, ctx) => {
+    if (!(value.rules?.length || value.tiers?.length))
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "缺少完整价格规则",
+        });
+    const inspect = (node, path) => {
+        if (Array.isArray(node))
+            node.forEach((item, index) => inspect(item, [...path, index]));
+        else if (node && typeof node === "object")
+            for (const [key, item] of Object.entries(node)) {
+                if (key === "saleMicros" &&
+                    (typeof item !== "string" || !/^\d+$/.test(item)))
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: [...path, key],
+                        message: "价格必须保留整数文本",
+                    });
+                inspect(item, [...path, key]);
+            }
+    };
+    inspect(value, []);
+});
+const snapshot = z
+    .object({
+    publicModelId: z.string().min(1),
+    routingMode,
+    billingRuleSnapshot: billingRule,
+})
+    .strict();
+const baseModel = {
+    publicModelId: z
+        .string()
+        .min(1)
+        .refine((value) => value.trim().length > 0),
+    displayName: z.string(),
+    description: z.string(),
+    modelType: z.enum(["TEXT", "IMAGE", "VIDEO"]),
+    materialMode: z.enum(["standard", "certified"]),
+    routingModes: z.array(routingMode).min(1),
+    textConfig: textConfig.optional(),
+    reasoningLevels: z.array(routingReasoning).min(1).optional(),
+};
+const listModel = z
+    .object({
+    publicModelId: baseModel.publicModelId,
+    displayName: baseModel.displayName,
+    modelType: baseModel.modelType,
+    materialMode: baseModel.materialMode,
+})
+    .strict();
+const detailModel = z
+    .object({
+    ...baseModel,
+    pricingSnapshot: z.array(snapshot).min(1).optional(),
+    promptSchema: z.record(z.unknown()).optional(),
+    paramsSchema: z.record(z.unknown()).optional(),
+    mediaRequirements: z.array(z.record(z.unknown())).optional(),
+    examples: z
+        .array(z
+        .object({
+        kind: z.string(),
+        label: z.string(),
+        input: z.record(z.unknown()),
+    })
+        .strict())
+        .optional(),
+})
+    .strict();
+function modelIssues(value, pricing, ctx, path) {
+    if (value.modelType === "TEXT" && !value.textConfig)
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: [...path, "textConfig"],
+            message: "缺少文字能力摘要",
+        });
+    if (new Set(value.routingModes).size !== value.routingModes.length)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path, message: "线路重复" });
+    if (value.reasoningLevels !== undefined) {
+        const modes = new Set();
+        for (const [index, level] of value.reasoningLevels.entries()) {
+            if (value.modelType !== "TEXT" ||
+                !value.routingModes.includes(level.routingMode) ||
+                modes.has(level.routingMode)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [...path, "reasoningLevels", index],
+                    message: "思考档位与文字模型或线路不一致",
+                });
+            }
+            modes.add(level.routingMode);
+        }
+    }
+    if (!pricing)
+        return;
+    const snapshots = value.pricingSnapshot ?? [];
+    if (snapshots.length !== value.routingModes.length ||
+        new Set(snapshots.map((item) => item.routingMode)).size !==
+            snapshots.length ||
+        snapshots.some((item) => item.publicModelId !== value.publicModelId ||
+            !value.routingModes.includes(item.routingMode)))
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: [...path, "pricingSnapshot"],
+            message: "价格快照与模型线路不匹配",
+        });
+}
+const listResponse = z
+    .object({
+    schemaVersion: z.literal(2),
+    models: z.array(listModel),
+    nextCursor: z.string().min(1).max(4096).nullable(),
+    notices: z.array(noticeSchema),
+})
+    .strict();
+const detailResponse = z
+    .object({
+    schemaVersion: z.literal(2),
+    model: detailModel,
+    includedSections: z.array(modelSectionSchema).max(3),
+    notices: z.array(noticeSchema),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const sections = new Set(value.includedSections);
+    if (sections.size !== value.includedSections.length)
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["includedSections"],
+            message: "章节重复",
+        });
+    modelIssues(value.model, sections.has("pricing"), ctx, ["model"]);
+    const model = value.model;
+    if (sections.has("pricing") !== (model.pricingSnapshot !== undefined))
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["model", "pricingSnapshot"],
+            message: "价格章节不完整",
+        });
+    if (sections.has("examples") !== (model.examples !== undefined))
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["model", "examples"],
+            message: "示例章节不完整",
+        });
+    if (sections.has("parameters") &&
+        model.modelType !== "TEXT" &&
+        (!model.paramsSchema || !model.mediaRequirements))
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["model"],
+            message: "参数章节不完整",
+        });
+    if (!sections.has("parameters") &&
+        [model.promptSchema, model.paramsSchema, model.mediaRequirements].some((item) => item !== undefined))
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["model"],
+            message: "返回了未选择的参数章节",
+        });
+});
+const V2_RESPONSE_ERROR = "当前接入未返回完整的新版模型响应，请确认服务端已升级或显式选择旧版查询";
+export function parseModelListResponseV2(value) {
+    const parsed = listResponse.safeParse(value);
+    if (!parsed.success)
+        throw new Error(V2_RESPONSE_ERROR);
+    return parsed.data;
+}
+export function parseModelDetailResponseV2(value, publicModelId, sections = ["parameters", "pricing"]) {
+    const parsed = detailResponse.safeParse(value);
+    if (!parsed.success ||
+        parsed.data.model.publicModelId !== publicModelId ||
+        parsed.data.includedSections.length !== sections.length ||
+        sections.some((section) => !parsed.data.includedSections.includes(section)))
+        throw new Error(V2_RESPONSE_ERROR);
+    return parsed.data;
+}

package/dist/package-version.d.ts

@@ -0,0 +1 @@
+export declare const MCP_PACKAGE_VERSION = "0.5.0";

package/dist/package-version.js

@@ -0,0 +1 @@
+export const MCP_PACKAGE_VERSION = "0.5.0";

package/dist/rest-commands.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { AiHiveApiClient, AiHiveApiError } from "./api-client.js";
 import { StaticBearerTokenProvider } from "./auth-token-provider.js";
 import { SERVER_VERSION } from "./server.js";
+import { parseModelListInput, parseModelDetailInput, parseModelListResponseV2, } from "./model-response.js";
 // 这些命令让没有 MCP 宿主的 Agent(纯 shell)也能完成选型、试跑和查账;
 // 走的是同一个 /mcp 门面, 因此 MCP 密钥即可用, 不需要再申请 API 密钥.
 export async function runRestCommand(config, dependencies) {
@@ -34,33 +35,42 @@ export async function runRestCommand(config, dependencies) {
     }
 }
 async function runModels(config, client, dependencies) {
-    const result = await client.listModels({
+    const input = parseModelListInput({
         ...(config.modelType ? { modelType: config.modelType } : {}),
-        detail: config.detail ?? "lite",
-    });
+        detail: config.detail,
+        schemaVersion: config.schemaVersion,
+        query: config.query,
+        cursor: config.cursor,
+        limit: config.limit,
+        routingMode: config.routingMode,
+    }, 2);
+    const result = await client.listModels(input);
     if (config.json) {
         dependencies.stdout(JSON.stringify(result, null, 2));
         return 0;
     }
-    const models = Array.isArray(result) ? result : [];
+    const page = input.schemaVersion === 2 ? parseModelListResponseV2(result) : undefined;
+    const models = page?.models ?? (Array.isArray(result) ? result : []);
     if (models.length === 0) {
+        if (page?.nextCursor) {
+            dependencies.stdout(`当前页没有匹配模型，继续读取：models --cursor ${JSON.stringify(page.nextCursor)}（保留原筛选条件）`);
+            return 0;
+        }
         dependencies.stderr("没有可用的模型，请到控制台确认模型状态。");
         return 1;
     }
-    dependencies.stdout("模型 ID\t名称\t类型\t线路");
+    dependencies.stdout("模型 ID\t名称\t类型\t素材模式");
     for (const model of models) {
         dependencies.stdout([
             text(model.publicModelId),
             text(model.displayName),
             text(model.modelType),
-            Array.isArray(model.routingModes)
-                ? model.routingModes
-                    .filter((mode) => typeof mode === "string")
-                    .join(",")
-                : "",
+            text("materialMode" in model ? model.materialMode : undefined),
         ].join("\t"));
     }
-    dependencies.stdout("价格与参数用 models --json 或 model <模型 ID> 查看。");
+    dependencies.stdout("找到候选即可用 model <模型 ID> 读取参数与价格；已知 ID 可直接查询。");
+    if (page?.nextCursor)
+        dependencies.stdout(`还有下一页：models --cursor ${JSON.stringify(page.nextCursor)}（保留原筛选条件）`);
     return 0;
 }
 async function runModel(config, client, dependencies) {
@@ -68,8 +78,16 @@ async function runModel(config, client, dependencies) {
         dependencies.stderr("请提供模型 ID，例如：ai-hive-mcp model doubao-seed-1-6");
         return 1;
     }
+    const input = parseModelDetailInput({
+        publicModelId: config.modelId,
+        routingMode: config.routingMode,
+        schemaVersion: config.schemaVersion,
+        sections: config.sections,
+    }, 2);
     const result = await client.getModel(config.modelId, config.routingMode, {
         announcements: false,
+        schemaVersion: input.schemaVersion,
+        ...(input.sections !== undefined ? { sections: input.sections } : {}),
     });
     dependencies.stdout(JSON.stringify(result, null, 2));
     return 0;
@@ -86,9 +104,12 @@ async function runPrompt(config, client, dependencies) {
     }
     const routingMode = config.routingMode ?? "COST_FIRST";
     // /mcp/chat/text 的严格入参要求 pricingSnapshot, CLI 没有宿主代为补全, 必须自己取一次.
-    const model = (await client.getModel(config.modelId, routingMode, {
+    const detail = (await client.getModel(config.modelId, routingMode, {
+        schemaVersion: 2,
         announcements: false,
+        purpose: "SNAPSHOT_RESOLUTION",
     }));
+    const model = detail.model;
     const pricingSnapshot = Array.isArray(model.pricingSnapshot)
         ? model.pricingSnapshot.find((snapshot) => typeof snapshot === "object" &&
             snapshot !== null &&

package/dist/schemas.d.ts

@@ -19,6 +19,7 @@ export declare const mcpCreateMediaUploadOutputSchema: z.ZodObject<{
     }>;
     expiresAt: z.ZodString;
 }, "strict", z.ZodTypeAny, {
+    expiresAt: string;
     mediaId: string;
     mediaType: "IMAGE" | "VIDEO" | "AUDIO" | "DOCUMENT";
     mimeType: string;
@@ -28,8 +29,8 @@ export declare const mcpCreateMediaUploadOutputSchema: z.ZodObject<{
         method: "PUT";
         headers: Record<string, string>;
     };
-    expiresAt: string;
 }, {
+    expiresAt: string;
     mediaId: string;
     mediaType: "IMAGE" | "VIDEO" | "AUDIO" | "DOCUMENT";
     mimeType: string;
@@ -39,7 +40,6 @@ export declare const mcpCreateMediaUploadOutputSchema: z.ZodObject<{
         method: "PUT";
         headers: Record<string, string>;
     };
-    expiresAt: string;
 }>;
 export declare const mcpUploadMediaFromPathInputSchema: z.ZodObject<{
     path: z.ZodEffects<z.ZodString, string, string>;
@@ -55,12 +55,19 @@ export declare const mcpUploadMediaFromPathInputSchema: z.ZodObject<{
     contentType?: string | undefined;
 }>;
 export declare const listModelsShape: {
+    schemaVersion: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
     modelType: z.ZodOptional<z.ZodEnum<["TEXT", "IMAGE", "VIDEO"]>>;
     detail: z.ZodOptional<z.ZodEnum<["lite", "full"]>>;
+    query: z.ZodOptional<z.ZodString>;
+    routingMode: z.ZodOptional<z.ZodEnum<["COST_FIRST", "SPEED_FIRST", "SUCCESS_FIRST"]>>;
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
 };
 export declare const getModelShape: {
-    publicModelId: z.ZodString;
+    schemaVersion: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+    publicModelId: z.ZodEffects<z.ZodString, string, string>;
     routingMode: z.ZodOptional<z.ZodEnum<["COST_FIRST", "SPEED_FIRST", "SUCCESS_FIRST"]>>;
+    sections: z.ZodOptional<z.ZodArray<z.ZodEnum<["parameters", "pricing", "examples"]>, "many">>;
 };
 export declare const chatTextShape: {
     publicModelId: z.ZodString;
@@ -183,36 +190,36 @@ export declare const listBillingRecordsInputSchema: z.ZodEffects<z.ZodObject<{
     invocationSource: z.ZodOptional<z.ZodEnum<["UNKNOWN", "WEB", "MCP", "WORKBUDDY", "QWENWORK", "DOUBAO_WORK", "MIAOSHOU", "OPENAPI"]>>;
 }, "strict", z.ZodTypeAny, {
     pageSize: number;
+    cursor?: string | undefined;
     publicModelId?: string | undefined;
     from?: string | undefined;
     to?: string | undefined;
     taskIds?: string[] | undefined;
     invocationSource?: "UNKNOWN" | "WEB" | "MCP" | "WORKBUDDY" | "QWENWORK" | "DOUBAO_WORK" | "MIAOSHOU" | "OPENAPI" | undefined;
-    cursor?: string | undefined;
 }, {
+    cursor?: string | undefined;
     publicModelId?: string | undefined;
     pageSize?: number | undefined;
     from?: string | undefined;
     to?: string | undefined;
     taskIds?: string[] | undefined;
     invocationSource?: "UNKNOWN" | "WEB" | "MCP" | "WORKBUDDY" | "QWENWORK" | "DOUBAO_WORK" | "MIAOSHOU" | "OPENAPI" | undefined;
-    cursor?: string | undefined;
 }>, {
     pageSize: number;
+    cursor?: string | undefined;
     publicModelId?: string | undefined;
     from?: string | undefined;
     to?: string | undefined;
     taskIds?: string[] | undefined;
     invocationSource?: "UNKNOWN" | "WEB" | "MCP" | "WORKBUDDY" | "QWENWORK" | "DOUBAO_WORK" | "MIAOSHOU" | "OPENAPI" | undefined;
-    cursor?: string | undefined;
 }, {
+    cursor?: string | undefined;
     publicModelId?: string | undefined;
     pageSize?: number | undefined;
     from?: string | undefined;
     to?: string | undefined;
     taskIds?: string[] | undefined;
     invocationSource?: "UNKNOWN" | "WEB" | "MCP" | "WORKBUDDY" | "QWENWORK" | "DOUBAO_WORK" | "MIAOSHOU" | "OPENAPI" | undefined;
-    cursor?: string | undefined;
 }>;
 export declare const getBillingRecordInputSchema: z.ZodObject<{
     recordId: z.ZodString;

package/dist/schemas.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { getModelReadShape, listModelsReadShape } from "./model-response.js";
 const nonBlankStringSchema = z
     .string()
     .refine((value) => value.trim().length > 0, {
@@ -70,14 +71,8 @@ const clientRequestIdSchema = z
     message: "Expected non-blank string",
 })
     .optional();
-export const listModelsShape = {
-    modelType: z.enum(["TEXT", "IMAGE", "VIDEO"]).optional(),
-    detail: z.enum(["lite", "full"]).optional(),
-};
-export const getModelShape = {
-    publicModelId: z.string().min(1),
-    routingMode: routingModeSchema.optional(),
-};
+export const listModelsShape = listModelsReadShape;
+export const getModelShape = getModelReadShape;
 export const chatTextShape = {
     publicModelId: z.string().min(1),
     routingMode: routingModeSchema,

package/dist/server.d.ts

@@ -5,7 +5,7 @@ import { AiHiveApiClient } from "./api-client.js";
 import { type BearerTokenProvider } from "./auth-token-provider.js";
 import type { McpClientConfig } from "./config.js";
 import { WorkBuddyCredentialStore } from "./workbuddy-credentials.js";
-export declare const SERVER_VERSION = "0.4.2";
+export declare const SERVER_VERSION = "0.5.0";
 declare function content(value: unknown): {
     content: {
         type: "text";

package/dist/server.js

@@ -3,17 +3,19 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { billingQueryInputSchema, listBillingRecordsInputSchema, getBillingRecordInputSchema, billingQueryShape, listBillingRecordsShape, getBillingRecordShape, chatTextShape, generateImageShape, generateVideoShape, getGenerationTaskShape, getModelShape, listModelsShape, listGenerationTasksShape, } from "./schemas.js";
 import { z } from "zod";
+import { MCP_PACKAGE_VERSION } from "./package-version.js";
+import { parseModelListInput, parseModelDetailInput, } from "./model-response.js";
 import { AiHiveApiClient, AiHiveApiError } from "./api-client.js";
 import { normalizeApiEndpoint, StaticBearerTokenProvider, WorkBuddyTokenProvider, } from "./auth-token-provider.js";
 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.4.2";
+export const SERVER_VERSION = MCP_PACKAGE_VERSION;
 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 返回的对应快照对象，或省略该字段由客户端自动获取";
-const SNAPSHOT_IDENTITY_MISMATCH_MESSAGE = "pricingSnapshot 的 publicModelId 或 routingMode 与请求不一致，请传入 list_models 返回的对应快照对象，或省略该字段由客户端自动获取";
+const SNAPSHOT_PARSE_FAILURE_MESSAGE = "pricingSnapshot 格式不正确，应为 get_model 返回的快照对象，也可以省略该字段由客户端自动获取";
+const SNAPSHOT_ARRAY_MISMATCH_MESSAGE = "pricingSnapshot 数组中没有匹配当前模型和 routingMode 的快照，请传入 get_model 返回的对应快照对象，或省略该字段由客户端自动获取";
+const SNAPSHOT_IDENTITY_MISMATCH_MESSAGE = "pricingSnapshot 的 publicModelId 或 routingMode 与请求不一致，请传入 get_model 返回的对应快照对象，或省略该字段由客户端自动获取";
 const MODEL_UNAVAILABLE_MESSAGE = "模型当前不可用或不支持该路由模式，请重新调用 list_models 获取最新模型信息";
 // 此文案与 @ai-hive/contracts 的 USER_INFO_TOOL_* 常量保持一致; 独立发布的客户端不引入运行依赖.
 const USER_INFO_TOOL_TITLE = "查看蜂巢账户信息";
@@ -49,7 +51,7 @@ function pickSnapshotForRequest(snapshots, publicModelId, routingMode) {
 }
 // LLM 回传 pricingSnapshot 时经常漏传或变形(数组/JSON 字符串/null), 由客户端代为归一化,
 // 保证进入付费 API 的请求一定携带服务端期望的单个快照对象.
-async function resolvePricingSnapshot(client, modelType, args) {
+async function resolvePricingSnapshot(client, _modelType, args) {
     const requestArgs = { ...args };
     if (requestArgs.dryRun === false) {
         delete requestArgs.dryRun;
@@ -62,10 +64,12 @@ async function resolvePricingSnapshot(client, modelType, args) {
         return request;
     };
     const resolveCurrentSnapshot = async () => {
-        const models = await client().listModels({ modelType }, { announcements: false });
-        const model = Array.isArray(models)
-            ? models.find((item) => isPlainObject(item) && item.publicModelId === args.publicModelId)
-            : undefined;
+        const result = await client().getModel(String(args.publicModelId), args.routingMode, {
+            schemaVersion: 2,
+            announcements: false,
+            purpose: "SNAPSHOT_RESOLUTION",
+        });
+        const model = isPlainObject(result) ? result.model : undefined;
         const snapshots = isPlainObject(model) ? model.pricingSnapshot : undefined;
         const matched = Array.isArray(snapshots)
             ? pickSnapshotForRequest(snapshots, args.publicModelId, args.routingMode)
@@ -130,21 +134,29 @@ export function createToolDefinitions(client) {
         },
         {
             name: "list_models",
-            title: "查询可用模型与价格",
-            description: "按 TEXT、IMAGE 或 VIDEO 查询可用模型与价格，售价单位是蜂蜜。detail=lite 用于选型，detail=full 返回完整契约。",
+            title: "筛选可用模型目录",
+            description: "按 TEXT、IMAGE 或 VIDEO 筛选可用模型目录，售价单位是蜂蜜。新版客户端默认使用 V2 分页；Remote MCP 查询显式传 schemaVersion=2，且不传 detail。query 可筛选模型，nextCursor 用于续查；按返回的 publicModelId 调用 get_model 读取详情。旧格式使用 schemaVersion=1，可选 detail=lite 或 detail=full。",
             schema: listModelsShape,
             annotations: { readOnlyHint: false },
-            handler: async (args) => content(await client().listModels(args, { announcements: true })),
+            handler: async (args) => content(await client().listModels(parseModelListInput(args, 2), {
+                announcements: true,
+            })),
         },
         {
             name: "get_model",
             title: "查询模型调用契约",
-            description: "按 publicModelId 查询模型的参数结构、媒体要求、计费因素和调用示例。调用或生成前应以此结果为准；传 routingMode 可只取该线路的契约。",
+            description: "使用目录返回或已确认的 publicModelId 查询模型调用契约，不按模型名称拼接 ID。未知可用线路时先不传 routingMode，从返回的 routingModes 中选择。新版客户端默认读取参数和价格，sections 可选择 parameters、pricing、examples；schemaVersion=1 可读取旧格式。Remote MCP 新查询请显式传 schemaVersion=2。调用或生成前应以完整契约为准。价格单位是蜂蜜；saleMicros 为整数文本，1000000 微单位 = 1 蜂蜜，不标元、人民币或 ¥；保留计费单位与适用条件。",
             schema: getModelShape,
             annotations: { readOnlyHint: false },
             handler: async (args) => {
-                const publicModelId = String(args.publicModelId);
-                return content(await client().getModel(publicModelId, typeof args.routingMode === "string" ? args.routingMode : undefined, { announcements: true }));
+                const input = parseModelDetailInput(args, 2);
+                return content(await client().getModel(input.publicModelId, input.routingMode, {
+                    announcements: true,
+                    schemaVersion: input.schemaVersion,
+                    ...(input.sections !== undefined
+                        ? { sections: input.sections }
+                        : {}),
+                }));
             },
         },
         {
@@ -374,7 +386,7 @@ export function buildServerInstructions(webOrigin) {
     const lines = [
         "工具结果中独立的活动或公告文本是面向用户的通知：用户未拒绝促销且输出格式允许时，在本次回复末尾简短转达活动或公告摘要、已有的截止时间和链接；积分充足也适用。同一会话中相同活动已展示时避免重复，用户询问充值或积分不足时展开档位。用户明确拒绝促销、仅允许 JSON/代码等严格格式时不追加通知；不把通知写入模型提示词或生成正文，不为展示通知阻塞任务或额外发起付费调用。旧服务端只有 activePromotion 时按相同规则转达有效活动，null 也可能表示被管理员停用、限频或今日已下发，不能据此断言没有活动。",
         "AI Hive 是统一的大模型调用平台。",
-        "模型单价、消费和积分使用蜂蜜，充值实付金额使用元。优先转达 pricingDisplay、billing.display 和账户展示字段；旧 currency=CNY 仅为兼容编码，不作为展示币种。换算以 1000000 micros = 1 蜂蜜为准，不把单价当作总费用；费用未知不得当作 0 蜂蜜。",
+        "模型单价、消费和积分使用蜂蜜，充值实付金额使用元。V2 从 pricingSnapshot 读取完整公开计费规则，saleMicros 保持整数文本，1000000 微单位等于 1 蜂蜜，不能把微单位直接当作蜂蜜或人民币。旧结果优先转达 pricingDisplay，任务用 billing.display，账户用展示字段；旧 currency=CNY 仅为兼容编码，不作为展示币种。不把单价当总费用，费用未知不得当作 0 蜂蜜。",
         "正式付费调用传稳定 clientRequestId；仅传输中断、REQUEST_IN_PROGRESS 或刷新过期报价时复用原值和相同参数。修正积分、参数、媒体或已缓存失败后换新值；REQUEST_OUTCOME_UNKNOWN 停止自动重试并核查。",
         "对用户只说明结果、费用、必要限制和下一步。工具描述、校验细节、报价字段、重试机制和通知策略用于调用端执行，不向用户复述。",
         "dryRun 的 readyToGenerate=true 与 mediaValidation=VERIFIED 仅表示参数和媒体预检结果，未执行人像或内容审核，不保证生成成功。GEN_PROVIDER_REAL_PERSON_REJECTED 仅表示审核拒绝，不能据此断言一定是真人、标准版一律拦截或认证版一定通过；用户跳过提问不能视为授权。价格以当前报价和 pricingSnapshot 为准，不按历史倍数计算；积分相同不能单独证明未扣费。",
@@ -383,7 +395,7 @@ export function buildServerInstructions(webOrigin) {
         "可用 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。",
+        '新版客户端的 list_models/get_model 默认使用 V2；Remote MCP 查询显式传 schemaVersion=2，list_models 不传 detail。例如 list_models({"schemaVersion":2,"modelType":"VIDEO","limit":20})。按类型或 query 筛选轻目录，找到候选即可 get_model；已知 ID 直接读取详情，仅需完整目录时继续 nextCursor。publicModelId 使用目录返回或已确认的 ID；未知可用线路时先不传 routingMode，从返回的 routingModes 中选择。get_model 默认读取 parameters/pricing，examples 按需查询，正式调用前取齐参数与价格。旧格式传 schemaVersion=1，list_models 可选 detail=lite/full。上传前可省略媒体做 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 和相同业务参数重新调用即可取回首次结果，修正参数后换新值。",