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

package/dist/setup/run-setup.js

@@ -0,0 +1,332 @@
+import { spawnSync } from "node:child_process";
+import { chmod, mkdir, readFile, rename, stat, unlink, writeFile, } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { detectTarget } from "./detect.js";
+import { mergeJsonMcpServers, mergeOpenCodeServer, readJsonServerEnv, upsertCodexServer, } from "./merge.js";
+import { readBundledSkills } from "./skills.js";
+import { resolveTargets } from "./targets.js";
+export const MCP_SERVER_NAME = "ai-hive";
+export const MCP_CODEX_SERVER_NAME = "ai_hive";
+export const MCP_PACKAGE_SPEC = "@infimind-next/ai-hive-mcp@latest";
+export async function runSetup(config, dependencies) {
+    const options = config.setup ?? {
+        clients: null,
+        dryRun: false,
+        skipSkills: false,
+    };
+    const key = config.key;
+    // 无密钥又无本机登录凭证时, 写进客户端的配置无法通过鉴权; 此时成功退出等于假成功.
+    const hasStoredCredentials = key === null && (await readOptionalFile(config.credentialsFile)) !== null;
+    if (key === null && !hasStoredCredentials) {
+        dependencies.stderr("缺少 MCP 密钥。请在控制台创建后设置 AI_HIVE_MCP_KEY，或先运行 ai-hive-mcp auth 登录。");
+        return 1;
+    }
+    if (key !== null && !/^[A-Za-z0-9._~-]+$/.test(key)) {
+        dependencies.stderr("MCP 密钥格式不正确，请重新复制完整密钥。");
+        return 1;
+    }
+    const targets = resolveTargets(dependencies);
+    const requested = options.clients
+        ? new Set(options.clients)
+        : null;
+    const candidates = requested
+        ? targets.filter((target) => requested.has(target.id))
+        : targets;
+    const detected = requested !== null ? candidates : await detectAll(candidates, dependencies);
+    if (detected.length === 0) {
+        dependencies.stderr("未检测到支持的客户端。请先安装 Claude Code、Cursor、Codex、Claude Desktop 或 OpenCode；检测不到时可以用 --client 指定。");
+        return 1;
+    }
+    dependencies.stdout(`检测到：${detected.map((target) => target.label).join("、")}`);
+    const env = buildServerEnv(config, key);
+    const skills = options.skipSkills
+        ? []
+        : await readSkillsSafely(dependencies.skillsRoot, dependencies);
+    let configured = 0;
+    const errors = [];
+    for (const target of detected) {
+        const result = await configureTarget({
+            target,
+            env,
+            dryRun: options.dryRun,
+            dependencies,
+        });
+        for (const line of result.lines)
+            dependencies.stdout(line);
+        for (const error of result.errors) {
+            dependencies.stderr(error);
+            errors.push(error);
+        }
+        if (result.configured)
+            configured += 1;
+        if (result.configured && target.skillsDir && skills.length > 0) {
+            const skillErrors = await installSkills({
+                directory: target.skillsDir,
+                skills,
+                dryRun: options.dryRun,
+                label: target.label,
+                dependencies,
+            });
+            for (const error of skillErrors) {
+                dependencies.stderr(error);
+                errors.push(error);
+            }
+        }
+    }
+    if (configured === 0) {
+        dependencies.stderr("没有写入任何配置，请检查上面的提示后重试。");
+        return 1;
+    }
+    if (options.dryRun) {
+        dependencies.stdout("仅预览，未写入任何文件。去掉 --dry-run 后执行。");
+        return errors.length > 0 ? 1 : 0;
+    }
+    if (!key) {
+        dependencies.stdout("未提供 MCP 密钥：客户端会使用本机已有的登录凭证。需要重新登录时先运行 ai-hive-mcp auth。");
+        return errors.length > 0 ? 1 : 0;
+    }
+    const verified = await verifyConnection(config.endpoint, key, config.timeoutMs, dependencies);
+    if (!verified) {
+        dependencies.stderr("配置已写入，但连接验证失败。请确认 MCP 密钥有效，或重新运行 setup。");
+        return 1;
+    }
+    dependencies.stdout("连接验证通过。重启客户端后即可调用 list_models。");
+    return errors.length > 0 ? 1 : 0;
+}
+async function readSkillsSafely(skillsRoot, dependencies) {
+    try {
+        return await readBundledSkills(skillsRoot);
+    }
+    catch {
+        // 老版本发布物或从源码运行时可能没有 skills 目录; 不因此阻断 MCP 配置写入.
+        dependencies.stderr("未找到随包技能，跳过技能安装。");
+        return [];
+    }
+}
+async function detectAll(targets, dependencies) {
+    const detected = [];
+    for (const target of targets) {
+        if (await detectTarget(target, {
+            home: dependencies.home,
+            platform: dependencies.platform,
+            env: dependencies.env,
+            exists: async (path) => {
+                try {
+                    await stat(path);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            },
+        })) {
+            detected.push(target);
+        }
+    }
+    return detected;
+}
+function buildServerEnv(config, key) {
+    return {
+        ...(key ? { AI_HIVE_MCP_KEY: key } : {}),
+        ...(config.endpointExplicit
+            ? { AI_HIVE_API_ENDPOINT: config.endpoint }
+            : {}),
+        ...(config.webOriginExplicit
+            ? { AI_HIVE_WEB_ORIGIN: config.webOrigin }
+            : {}),
+    };
+}
+async function configureTarget(input) {
+    const { target, env, dryRun, dependencies } = input;
+    if (target.format === "claude-cli") {
+        return configureClaudeCode({ env, dryRun, dependencies });
+    }
+    const configPath = target.configPath;
+    if (!configPath) {
+        return {
+            configured: false,
+            lines: [],
+            errors: [`${target.label}：没有可写入的配置路径`],
+        };
+    }
+    try {
+        const existing = await readOptionalFile(configPath);
+        const next = renderConfig(target, existing, env);
+        if (next === existing) {
+            return {
+                configured: true,
+                lines: [`${target.label}：配置已是最新，跳过`],
+                errors: [],
+            };
+        }
+        if (!dryRun) {
+            await writePrivateFile(configPath, next);
+        }
+        return {
+            configured: true,
+            lines: [`${target.label}：${dryRun ? "将写入" : "已写入"} ${configPath}`],
+            errors: [],
+        };
+    }
+    catch (error) {
+        return {
+            configured: false,
+            lines: [],
+            errors: [
+                `${target.label}：${error instanceof Error ? error.message : "写入配置失败"}`,
+            ],
+        };
+    }
+}
+function renderConfig(target, existing, env) {
+    if (target.format === "json-mcpServers") {
+        const mergedEnv = {
+            ...readJsonServerEnv(existing, "mcpServers", MCP_SERVER_NAME),
+            ...env,
+        };
+        return mergeJsonMcpServers(existing, MCP_SERVER_NAME, {
+            command: "npx",
+            args: ["-y", MCP_PACKAGE_SPEC],
+            ...(Object.keys(mergedEnv).length > 0 ? { env: mergedEnv } : {}),
+        });
+    }
+    if (target.format === "json-opencode") {
+        const mergedEnv = {
+            ...readJsonServerEnv(existing, "mcp", MCP_SERVER_NAME),
+            ...env,
+        };
+        return mergeOpenCodeServer(existing, MCP_SERVER_NAME, {
+            type: "local",
+            command: ["npx", "-y", MCP_PACKAGE_SPEC],
+            enabled: true,
+            ...(Object.keys(mergedEnv).length > 0 ? { environment: mergedEnv } : {}),
+        });
+    }
+    return upsertCodexServer(existing, MCP_CODEX_SERVER_NAME, MCP_PACKAGE_SPEC, env);
+}
+// 临时文件 + rename 保证中断时不会截断用户配置; chmod 兜住已存在文件的 0644.
+async function writePrivateFile(path, content) {
+    const directory = dirname(path);
+    await mkdir(directory, { recursive: true });
+    const temp = join(directory, `.${basename(path)}.${process.pid}.${Date.now()}.tmp`);
+    await writeFile(temp, content, { mode: 0o600 });
+    try {
+        await rename(temp, path);
+    }
+    catch (error) {
+        await unlink(temp).catch(() => undefined);
+        throw error;
+    }
+    if (process.platform !== "win32") {
+        await chmod(path, 0o600);
+    }
+}
+async function configureClaudeCode(input) {
+    const args = [
+        "mcp",
+        "add",
+        MCP_SERVER_NAME,
+        "--scope",
+        "user",
+        ...Object.entries(input.env).flatMap(([name, value]) => [
+            "-e",
+            `${name}=${value}`,
+        ]),
+        "--",
+        "npx",
+        "-y",
+        MCP_PACKAGE_SPEC,
+    ];
+    if (input.dryRun) {
+        return {
+            configured: true,
+            lines: [`Claude Code：将运行 ${maskedCommand(args)}`],
+            errors: [],
+        };
+    }
+    // 重复执行时 claude 会因为同名服务器报错; 先移除再添加, 保证 setup 可重复运行.
+    const runner = input.dependencies.runCommand ?? defaultRunner;
+    await runner("claude", ["mcp", "remove", MCP_SERVER_NAME, "--scope", "user"]);
+    const result = await runner("claude", args);
+    if (!result.ok) {
+        return {
+            configured: false,
+            lines: [],
+            errors: [
+                "Claude Code：自动写入失败，请运行 claude mcp add ai-hive --scope user -e AI_HIVE_MCP_KEY=<你的 MCP 密钥> -- npx -y " +
+                    MCP_PACKAGE_SPEC +
+                    " 手动添加",
+            ],
+        };
+    }
+    return {
+        configured: true,
+        lines: ["Claude Code：已写入 MCP 配置"],
+        errors: [],
+    };
+}
+function maskedCommand(args) {
+    return ["claude", ...args]
+        .map((part) => part.startsWith("AI_HIVE_MCP_KEY=") ? "AI_HIVE_MCP_KEY=***" : part)
+        .join(" ");
+}
+async function defaultRunner(command, args) {
+    const result = spawnSync(command, args, {
+        stdio: "ignore",
+        // Windows 上 npm 安装的是 claude.cmd, Node 必须经 shell 才能执行; 参数只含常量和已校验的密钥.
+        shell: process.platform === "win32",
+        timeout: 30_000,
+    });
+    return { ok: result.status === 0 };
+}
+async function installSkills(input) {
+    const errors = [];
+    let changed = 0;
+    for (const skill of input.skills) {
+        for (const file of skill.files) {
+            const path = join(input.directory, skill.name, file.relativePath);
+            try {
+                const existing = await readOptionalFile(path);
+                if (existing === file.content)
+                    continue;
+                if (!input.dryRun) {
+                    await mkdir(dirname(path), { recursive: true });
+                    await writeFile(path, file.content, "utf8");
+                }
+                changed += 1;
+            }
+            catch {
+                errors.push(`${input.label}：安装技能 ${skill.name} 失败`);
+            }
+        }
+    }
+    if (errors.length === 0) {
+        input.dependencies.stdout(`${input.label}：${input.dryRun ? "将安装" : "已安装"} ${input.skills.length} 个技能（${changed} 个文件有更新）到 ${input.directory}`);
+    }
+    return errors;
+}
+async function verifyConnection(endpoint, key, timeoutMs, dependencies) {
+    const fetchImpl = dependencies.fetchImpl ?? fetch;
+    try {
+        const response = await fetchImpl(`${endpoint.replace(/\/+$/, "")}/mcp/user-info`, {
+            headers: {
+                Authorization: `Bearer ${key}`,
+                "X-AI-Hive-Announcements": "0",
+            },
+            signal: AbortSignal.timeout(Math.min(timeoutMs, 15_000)),
+        });
+        await response.body?.cancel();
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+async function readOptionalFile(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}

package/dist/setup/skills.d.ts

@@ -0,0 +1,8 @@
+export type BundledSkill = {
+    name: string;
+    files: {
+        relativePath: string;
+        content: string;
+    }[];
+};
+export declare function readBundledSkills(skillsRoot: string): Promise<BundledSkill[]>;

package/dist/setup/skills.js

@@ -0,0 +1,35 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+// 只收 Markdown; 技能里不放二进制, 保证包体和逐文件写入都可预期.
+export async function readBundledSkills(skillsRoot) {
+    const entries = await readdir(skillsRoot, { withFileTypes: true });
+    const skills = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const directory = join(skillsRoot, entry.name);
+        const files = await readMarkdownFiles(directory);
+        if (!files.some((file) => file.relativePath === "SKILL.md"))
+            continue;
+        skills.push({ name: entry.name, files });
+    }
+    return skills.sort((left, right) => left.name.localeCompare(right.name));
+}
+async function readMarkdownFiles(root) {
+    const entries = await readdir(root, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const path = join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await readMarkdownFiles(path)));
+            continue;
+        }
+        if (!entry.name.endsWith(".md"))
+            continue;
+        files.push({
+            relativePath: relative(root, path),
+            content: await readFile(path, "utf8"),
+        });
+    }
+    return files;
+}

package/dist/setup/targets.d.ts

@@ -0,0 +1,14 @@
+import type { SetupClientId } from "../config.js";
+export type ClientFormat = "claude-cli" | "json-mcpServers" | "toml-mcp-servers" | "json-opencode";
+export type ClientTarget = {
+    id: SetupClientId;
+    label: string;
+    format: ClientFormat;
+    configPath: string | null;
+    skillsDir: string | null;
+};
+export declare function resolveTargets(input: {
+    home: string;
+    platform: NodeJS.Platform;
+    env: Record<string, string | undefined>;
+}): ClientTarget[];

package/dist/setup/targets.js

@@ -0,0 +1,46 @@
+import { join } from "node:path";
+export function resolveTargets(input) {
+    const { home, platform, env } = input;
+    const claudeDesktopConfig = platform === "darwin"
+        ? join(home, "Library/Application Support/Claude/claude_desktop_config.json")
+        : platform === "win32"
+            ? join(env.APPDATA ?? join(home, "AppData/Roaming"), "Claude/claude_desktop_config.json")
+            : join(home, ".config/Claude/claude_desktop_config.json");
+    return [
+        {
+            id: "claude-code",
+            label: "Claude Code",
+            format: "claude-cli",
+            configPath: null,
+            skillsDir: join(home, ".claude/skills"),
+        },
+        {
+            id: "cursor",
+            label: "Cursor",
+            format: "json-mcpServers",
+            configPath: join(home, ".cursor/mcp.json"),
+            skillsDir: null,
+        },
+        {
+            id: "codex",
+            label: "Codex",
+            format: "toml-mcp-servers",
+            configPath: join(home, ".codex/config.toml"),
+            skillsDir: join(home, ".codex/skills"),
+        },
+        {
+            id: "claude-desktop",
+            label: "Claude Desktop",
+            format: "json-mcpServers",
+            configPath: claudeDesktopConfig,
+            skillsDir: null,
+        },
+        {
+            id: "opencode",
+            label: "OpenCode",
+            format: "json-opencode",
+            configPath: join(home, ".config/opencode/opencode.json"),
+            skillsDir: null,
+        },
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infimind-next/ai-hive-mcp",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "private": false,
   "type": "module",
   "engines": {
@@ -10,8 +10,16 @@
     "ai-hive-mcp": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
+    "lint": "eslint \"src/**/*.ts\"",
+    "prepack": "pnpm run build",
+    "test": "vitest run"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "file-type": "^21.3.4",
@@ -22,11 +30,5 @@
     "typescript": "^5.0.0",
     "typescript-eslint": "^8.0.0",
     "vitest": "^3.0.0"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
-    "lint": "eslint \"src/**/*.ts\"",
-    "test": "vitest run"
   }
-}
+}

package/skills/ai-hive-billing/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: ai-hive-billing
+description: 查询蜂巢账户的积分、消费和账单明细。用户问"还剩多少""这次花了多少""今天用了多少""为什么扣费"时使用。只读，不会产生费用。
+---
+
+# 查积分与账单
+
+## 命令
+
+```
+ai-hive-mcp usage --json
+```
+
+如果返回"当前服务端暂不支持账单查询"，直接引导用户去控制台查看积分与消费，不要重试或改用其他工具猜测金额。
+
+MCP 工具：`get_billing_summary`、`list_billing_records`、`get_billing_record`。
+
+## 回答用户时
+
+1. 积分和消费统一换算成蜂蜜（微单位除以 1,000,000），最多保留 6 位小数。只有充值实付金额才是元。
+2. 说明时间范围。不传时间时默认是北京时间今日，跨天要显式传 `from` / `to`。
+3. 用户问单次调用时，用 `list_billing_records` 按 `publicModelId` 或任务 ID 过滤，再用 `get_billing_record` 看明细。
+4. 积分不足时给出充值入口，不要把积分不足说成调用失败。
+
+## 注意
+
+- 账单记录包含结算、预占、释放三类；预占和释放不算消费，解释时区分清楚。
+- 不要暴露内部成本价、上游供应商名称或渠道信息。
+- 不要根据本地估算回答消费问题，一律以接口返回为准。
+
+## 账户信息
+
+需要账户资料或充值入口时用 `get_user_info`。该工具同时返回当前活动，有活动时可以把活动信息转达给用户。

package/skills/ai-hive-image-video-generation/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: ai-hive-image-video-generation
+description: 用蜂巢生成图片或视频。用户要出图、图生图、文生视频、图生视频或首尾帧视频时使用。必须先 dryRun 预检报价，确认后再正式生成，并轮询任务直到完成或失败。
+---
+
+# 生成图片与视频
+
+## 强制流程
+
+1. 选型：见 `ai-hive-model-selection`。
+2. 预检：`generate_image` 或 `generate_video`，传 `dryRun: true`。
+3. 把预检返回的预计费用告诉用户。费用超出用户预期时先确认，不要直接正式生成。
+4. 正式生成：同一组参数、同一个 `clientRequestId`，去掉 `dryRun`。
+5. 轮询：用 `get_generation_task` 查 `taskId`，看 `items[].status`，直到 `COMPLETED` 或 `FAILED`。
+
+## 参数
+
+- 图片：`publicModelId`、`routingMode`、`prompt`，可选 `batchSize`、`imageMediaIds`、`params`。
+- 视频：`publicModelId`、`routingMode`、`prompt`，可选 `imageMediaIds`、`videoMediaIds`、`audioMediaIds`、`firstFrameMediaId`、`lastFrameMediaId`、`params`。
+- `params` 必须以 `get_model` 返回的 schema 为准。
+
+## 认证素材（仅视频）
+
+用户要用认证素材时：
+
+1. `get_material_mode` 确认当前账户是否有资格。
+2. `quote_video_materials` 冻结素材，返回的字段名是 `id`。
+3. `generate_video` 传 `materialMode: "certified"`，并把上一步的 `id` 作为 `materialQuoteId` 传入。
+
+没有资格时如实说明，不要改用普通素材冒充。
+
+## 失败与重试
+
+- `FAILED`：读取 `errorMessage`，转述可执行的下一步；不要用相同参数无限重试。
+- 超时且服务端仍在处理：用任务 ID 继续查，不要重新提交。
+- 正式生成请求超时又查不到任务时，复用同一个 `clientRequestId` 重新提交，由服务端幂等去重。
+
+## 回复用户
+
+- 成功：给结果链接或 mediaId，并说明本次消费（单位是蜂蜜，充值实付才是元）。
+- 失败：说明失败原因和用户能做什么，不展示上游响应体。

package/skills/ai-hive-media-upload/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: ai-hive-media-upload
+description: 把本机图片、视频、音频或文档传给蜂巢，换取可复用的 mediaId。图片理解、图生图、图生视频、首尾帧和参考素材之前都要用。包含本机直传和"创建上传地址再 PUT"两种方式和大小限制处理。
+---
+
+# 上传媒体
+
+## 选哪种方式
+
+- Agent 能读本机文件：用 `upload_media_from_path`，一步完成。
+- 只能拿到字节流或远程文件：先 `create_media_upload`，再按返回的 `method` 和 `headers` 把原始字节 PUT 到 `upload.url`，最后 `complete_media_upload`。
+
+## 步骤（本机文件）
+
+```
+工具：upload_media_from_path
+参数：{ "path": "/绝对路径/图片.png" }
+```
+
+返回 `mediaId`，后续放进 `messages[].mediaIds` 或 `imageMediaIds`、`videoMediaIds`、`firstFrameMediaId`、`lastFrameMediaId`。
+
+## 步骤（创建上传地址）
+
+1. `create_media_upload`，必须传 `filename`、`contentType`、`sizeBytes`（原始字节数），缺一个都会被拒绝。
+2. PUT 文件原始字节到返回的 `upload.url`，请求头使用返回的 `upload.headers`，不要改成 multipart。
+3. `complete_media_upload`，传 `mediaId`。成功后该 `mediaId` 才可用。
+
+## 注意
+
+- 上传地址有有效期，超时后重新创建，不要复用。
+- `complete_media_upload` 失败时不要直接拿去生成，先重试确认或重新上传。
+- 单文件大小和格式限制以 `get_model` 返回的媒体要求为准。
+- 不要把文件内容贴进对话文本，必须走上传换取 `mediaId`。

package/skills/ai-hive-model-selection/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: ai-hive-model-selection
+description: 在蜂巢 AI 开放平台选择模型。用户要调用文字、图片或视频模型，但还没指定模型时使用；先列出可用模型和售价，再读取目标模型的参数契约，避免按记忆猜参数。也可用于比较同类模型的价格和线路。
+---
+
+# 选择模型
+
+## 何时用
+
+- 用户说"用蜂巢生成一张图/一段视频/写一段文字"，但没有给模型 ID。
+- 需要在多个模型之间比价格、比能力、比线路。
+
+不要跳过这一步直接调用生成工具。模型 ID、参数和线路必须以当前账户可见的契约返回值为准。
+
+## 步骤
+
+1. 列出候选模型（`detail=lite` 只返回选型需要的字段）：
+
+   ```
+   ai-hive-mcp models --type IMAGE --json
+   ```
+
+   已连接 MCP 时调用 `list_models`，参数相同。
+
+2. 按任务筛选：
+   - 文字：`TEXT`
+   - 图片：`IMAGE`
+   - 视频：`VIDEO`
+
+3. 比较 `pricingSummary` 里的 `saleMicros`。这是客户实际结算价，单位是蜂蜜微单位（1,000,000 微单位 = 1 蜂蜜），不要引用 `originalMicros`。只有充值实付金额才是元。
+4. 用 `get_model` / `ai-hive-mcp model <模型 ID> --json` 读取：
+   - 支持的 `routingModes`
+   - 参数 schema
+   - 媒体要求
+   - 计费因素
+5. 把选中的 `publicModelId` 和 `routingMode` 交给下一步技能。
+
+## 线路怎么选
+
+- `COST_FIRST`：默认，价格优先。
+- `SPEED_FIRST`：速度优先。
+- `SUCCESS_FIRST`：成功率优先。
+
+用户没有偏好时用 `COST_FIRST`，并在回复里说明选择的线路。
+
+## 失败处理
+
+- 返回"模型不存在或当前不可用"：重新列一遍模型，不要重试同一个 ID。
+- 返回没有价格：该模型暂不可售，换一个模型。
+- 不要猜测参数名。`get_model` 没有给出的字段一律不要传。

package/skills/ai-hive-text-generation/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: ai-hive-text-generation
+description: 用蜂巢的 Hive Chat API 发起一次付费文字调用。用户要写文案、总结、翻译、问答，且已经确定模型时使用。包含幂等键、报价快照和超时恢复规则，避免重复扣费。
+---
+
+# 文字生成
+
+## 前置
+
+先按 `ai-hive-model-selection` 确定 `publicModelId` 和 `routingMode`。
+
+## 调用
+
+MCP 工具：`chat_text`
+
+```
+ai-hive-mcp run <模型 ID> "你的提示词" --json
+```
+
+## 必须遵守
+
+1. **每次付费调用都带 `clientRequestId`**，同一次业务请求重试必须复用同一个值。改参数后必须换新值，否则会被当成同一次请求去重。
+2. `pricingSnapshot` 可选。省略时客户端会自动向服务端取当前快照；手动传时必须是 `list_models` 返回的对应对象，且 `publicModelId`、`routingMode` 一致。
+3. 多轮对话时把历史消息按 `system` / `user` / `assistant` 顺序传入。
+4. 图片理解：先把图片上传为 `mediaId`（见 `ai-hive-media-upload`），再放进 `messages[].mediaIds`。
+
+## 超时怎么办
+
+返回"等待响应超时，服务端可能仍在生成，也可能已完成并扣费"时：
+
+- 复用同一个 `clientRequestId` 和完全相同的参数重新调用；
+- 不要换参数重发，那会被当成新请求再次扣费；
+- 不要为了"确认结果"而重复提交。
+
+## 回复用户
+
+- 给出生成结果。
+- 结果里包含 `chargeMicros` 时，换算成蜂蜜（除以 1,000,000）告诉用户本次消费；只有充值实付金额才是元。
+- 不要展示内部错误码或上游响应体。