大模型工具集成说明

授权接口通常不直接作为大模型工具暴露，而是由 MCP Server 或 Skill 后端在调用其他 API 时自动完成令牌获取与刷新。开发者应实现令牌管理机制，确保工具调用时 Authorization 头有效。

若确需大模型代为获取令牌（如用户提供 apiid/password 场景），可定义如下工具（谨慎使用，避免泄露凭证）：

{
  "name": "get_access_token",
  "description": "使用 apiid 和密码获取 API 访问令牌。仅当用户明确提供凭证时调用。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "apiid": {"type": "string"},
      "password": {"type": "string"},
      "is_long": {"type": "integer", "enum": [0,1], "default": 0}
    },
    "required": ["apiid", "password"]
  }
}

大模型工具集成说明

在 MCP 或 Skill 实现中，建议封装令牌自动刷新逻辑，而不是将刷新接口直接暴露为大模型工具。通常的做法是：

• 在 MCP Server 内部维护 access_token 及其过期时间。
• 每次调用需要鉴权的 API 之前，检查 token 是否将过期（如剩余时间小于 5 分钟），若是则自动调用刷新接口获取新 token。
• 如果 refresh_token 也已过期，则返回明确的错误提示，引导用户重新登录。

若确实需要大模型代为刷新（例如在用户明确授权且提供 refresh_token 的场景），可定义如下工具（谨慎使用，避免泄露）：

{
  "name": "refresh_access_token",
  "description": "使用 refresh_token 获取新的 access_token。仅当用户明确提供 refresh_token 且当前 access_token 已失效时调用。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "refresh_token": {
        "type": "string",
        "description": "从登录接口获取的 refresh_token"
      }
    },
    "required": ["refresh_token"]
  }
}

大模型工具调用规范 (MCP / Skill 集成)

本 API 可作为大模型的视觉感知工具，使模型能够从现代横排文字图片中提取文本。大模型通过函数调用（Function Calling / Tool Use）触发 OCR 能力，将图像转换为文字后用于后续问答、摘要、翻译等任务。

🛠️ 工具定义（Tool Schema）

推荐的工具元数据如下，可直接用于 MCP 服务或自定义 Skill 清单：

{
  "name": "modern_ocr",
  "description": "识别现代横排文字图片（中英文、数字、标点），返回按行组织的文本及每行坐标。适用于印刷文档、截图、自然场景文字。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "image_base64": {
        "type": "string",
        "description": "图片的 Base64 编码（不含 data:image/... 前缀）"
      }
    },
    "required": ["image_base64"]
  }
}

🤖 大模型调用指引（MCP / Skill 集成场景）

• MCP Server 集成：在 MCP 服务端注册上述工具，接收 image_base64 参数后，解码为临时文件并按照 multipart/form-data 格式调用本 API。需自动填充 Authorization 头部（从环境变量或会话中获取 access_token）。
• AI Skill 插件：Skill 描述文件中声明工具，平台运行时根据用户提供的图片（或截图）提取 base64，发起请求，并将响应中的 text 字段返回给大模型。如需进一步处理（如标点、翻译），可将 text 作为后续工具的输入。
• 请求转换示例：模型生成的参数 {"image_base64": "iVBORw0KGgo..."} 将被 MCP Server 转换为 multipart 请求，响应中的 text 和行级信息可按需返回给模型。

📤 工具返回结果示例（给大模型的输出结构）

{
  "status": "success",
  "text": "古籍酷是一款专业工具\n它支持OCR、标点、翻译",
  "line_count": 2,
  "char_count": 18,
  "full_response": {
    "line_chars": [["古","籍","酷","是","一","款","专","业","工","具"], ...],
    "line_coors": [[100,50,1100,80], ...],
    "line_char_probs": [[0.99,0.98,...], ...]
  }
}

大模型接收到该结构化结果后，可向用户展示识别出的文本，或基于 text 字段进行后续处理。

⚙️ MCP 特定配置建议

• 图片预处理：对于较大图片（>10MB），建议 MCP 先进行压缩或分块，或使用图片 URL 方式直传（若 API 支持）。
• 异步/同步：OCR 任务可能耗时 3-15 秒，MCP 实现应支持异步回调或设置长超时（建议 60s）。
• 错误映射：将 API 返回的错误码（如 OCR failed）转换为大模型可理解的提示，例如“图像文字识别失败，请检查图片清晰度”。
• 行合并策略：若大模型需要段落级输出，可在 MCP 中根据行坐标或空行进行后处理合并，再返回给模型。

📌 Skill 描述片段（YAML 格式参考）

skill:
  name: "modern_ocr_tool"
  version: "1.0.0"
  description: "从横排文字图片中提取文本"
  tools:
    - name: "modern_ocr"
      method: "POST"
      endpoint: "/ocr_mod"
      headers:
        Authorization: "gjcool "
      input_type: "multipart"
      parameters:
        - name: "img"
          type: "file"
          source: "base64"
          required: true
      output_mapping: "recognized_text = response.text"

大模型工具调用规范 (MCP / Skill 集成)

本 API 通常作为后处理工具，在 OCR 识别之后调用，用于生成可检索、可存档的双层 PDF。大模型可以通过链式调用（先 OCR → 再生成 PDF）完成从图片到文档的完整工作流。

🛠️ 工具定义（Tool Schema）

推荐的工具元数据如下，可直接用于 MCP 服务或自定义 Skill 清单：

{
  "name": "create_searchable_pdf",
  "description": "将图片和OCR文字数据合成为双层PDF（图像层+可选文字层）。支持多种OCR数据格式，可控制图像压缩程度。适用于古籍数字化存档。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "image_base64": {
        "type": "string",
        "description": "原始图片的 Base64 编码（不含 data:image/... 前缀）"
      },
      "ocr_data": {
        "type": "object",
        "description": "OCR 识别结果，需符合 /ocr_pro 输出格式或标注平台导出格式"
      },
      "compression": {
        "type": "integer",
        "enum": [0, 1, 2, 3, 4, 5],
        "description": "图像压缩级别，0=不压缩，5=最大压缩。默认0。",
        "default": 0
      }
    },
    "required": ["image_base64", "ocr_data"]
  }
}

🤖 大模型调用指引（MCP / Skill 集成场景）

• 链式调用：大模型应先调用 OCR 工具（ancient_ocr 或 modern_ocr）获取识别数据，然后将返回的完整 JSON 作为 ocr_data 参数传入本工具，实现从图片到 PDF 的一键转换。
• MCP Server 集成：注册上述工具，接收 base64 图片和 JSON 数据后，解码图片并构造 multipart 请求。需自动填充 Authorization 头。建议将返回的 PDF 二进制流再进行 base64 编码返回给模型，或提供下载链接。
• AI Skill 插件：Skill 可提供组合操作，例如用户上传图片后，自动依次调用 OCR 和 PDF 生成，最终返回 PDF 文件供用户下载。

📤 工具返回结果示例（给大模型的输出结构）

{
  "status": "success",
  "message": "PDF generated successfully",
  "pdf_base64": "JVBERi0xLjQKJeLjz9MK...",   // Base64 编码的 PDF 内容
  "file_size_bytes": 245760
}

大模型可以向用户提供下载链接或直接展示 PDF（若客户端支持）。

⚙️ MCP 特定配置建议

• 大文件处理：由于生成的 PDF 可能较大（几十MB），MCP 返回 base64 时需注意上下文长度限制。可改为返回临时下载 URL，或要求模型异步处理。
• 错误处理：如果 pdf failed，可提示用户检查 OCR 数据坐标是否超出图片范围，或降低压缩级别重试。
• 格式兼容：在调用前，MCP 应验证 ocr_data 是否为已知格式（检查是否存在 line_chars 或 chars 字段），若不匹配则返回明确错误。

📌 Skill 描述片段（YAML 格式参考）

skill:
  name: "pdf_generator"
  version: "1.0.0"
  description: "将图片和OCR结果合成为可搜索PDF"
  tools:
    - name: "create_searchable_pdf"
      method: "POST"
      endpoint: "/pdf"
      headers:
        Authorization: "gjcool "
      parameters:
        - name: "img"
          type: "file"
          source: "base64"
          required: true
        - name: "data"
          type: "object"
          source: "json"
          required: true
        - name: "compression"
          type: "integer"
          required: false
      output_type: "application/pdf"
      output_conversion: "base64"

大模型工具调用规范 (MCP / Skill 集成)

本API完全兼容大模型生态的工具调用范式，可作为MCP (Model Context Protocol) 服务端工具或 AI Skill 插件使用。大模型通过函数调用（Function Calling / Tool Use）触发自动标点能力，将古籍文本处理无缝融入对话或智能体工作流。

🛠️ 工具定义（Tool Schema）

推荐的工具元数据如下，可直接用于 MCP 服务或自定义 Skill 清单：

{
  "name": "add_ancient_text_punctuation",
  "description": "为古籍原典文本添加现代标点符号（句号、逗号、感叹号等），支持多个自然段落，输入文本总长度不超过10万字。自动识别古文句读，提升可读性。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "src": {
        "type": "string",
        "description": "需要添加标点的古籍原文，支持多段落，段落之间必须使用两个换行符分隔（\\n\\n）。例如：'子曰：学而时习之\\n\\n有朋自远方来'。最大长度100000字符。"
      },
      "keep_wrap": {
        "type": "integer",
        "enum": [0, 1],
        "description": "是否保留原文中的换行符。0表示不保留（默认），1表示保留内部单换行符。一般场景推荐0以获得连贯标点输出。",
        "default": 0
      }
    },
    "required": ["src"]
  }
}

🤖 大模型调用指引（MCP / Skill 集成场景）

• MCP Server 集成：在 MCP 服务端将该工具注册为 Tool 类型，并绑定到本 API 的 POST 端点。需在工具调用处理器中自动填充 Authorization 头部（从环境变量或安全上下文中获取 access_token）。
• AI Skill 插件：Skill 描述文件中声明上述工具定义，平台运行时根据用户意图提取 src 参数，发起异步 HTTP 请求并解析 text 数组返回给大模型。
• 请求转换示例：模型生成的参数 {"src": "吾十有五而志于学。三十而立。\n\n四十而不惑。", "keep_wrap": 0} 将被映射为 multipart/form-data 请求，响应中的 text 列表按段落顺序组装为自然语言结果。

📤 工具返回结果示例（给大模型的输出结构）

{
  "status": "success",
  "punctuated_paragraphs": [
    "吾十有五而志于学。三十而立。",
    "四十而不惑。"
  ],
  "paragraph_count": 2,
  "input_length": 28
}

大模型接收到该结构化结果后，可向用户展示为：“第一段：吾十有五而志于学。三十而立。\n第二段：四十而不惑。” 提升交互友好度。

⚙️ MCP 特定配置建议

实现 MCP 工具端点时，建议遵循以下模式：

• 认证透传：从 MCP 会话元数据中读取 access_token，构造 Authorization: gjcool {token} 请求头。
• 异步/同步：由于标点任务可能耗时数秒，MCP 实现应支持异步或设置合理超时（默认 60s）。
• 错误映射：将 API 返回的错误码（如 text too long）转换为模型可理解的字符串，建议返回给大模型再处理，或直接提示用户减少文本长度。
• 限流应对：收到 wait for * seconds 时可借助重试中间件或通知模型稍后再次尝试。

📌 Skill 描述片段（YAML 格式参考）

skill:
  name: "ancient_text_punctuator"
  version: "1.0.0"
  description: "自动为古籍添加标点，适用于文言文、史书、经典文献"
  tools:
    - name: "add_ancient_text_punctuation"
      method: "POST"
      endpoint: "/api/v1/text/punctuate"
      headers:
        Authorization: "Bearer "
      parameters:
        - name: "src"
          type: "string"
          required: true
        - name: "keep_wrap"
          type: "integer"
          required: false
      output_mapping: "punctuated_paragraphs = response.text"

大模型工具调用规范 (MCP / Skill 集成)

本 API 完全兼容大模型生态的工具调用范式，可作为 MCP (Model Context Protocol) 服务端工具或 AI Skill 插件使用。大模型通过函数调用（Function Calling / Tool Use）触发古文翻译能力，将文言文转换为现代汉语，辅助古籍阅读与内容理解。

🛠️ 工具定义（Tool Schema）

推荐的工具元数据如下，可直接用于 MCP 服务或自定义 Skill 清单：

{
  "name": "translate_ancient_chinese",
  "description": "将文言文/古籍文本翻译为现代汉语。支持两种模式：整段通译（返回字符串）或逐句对照翻译（返回原文-译文对列表）。最大输入长度10000字。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "src": {
        "type": "string",
        "description": "需要翻译的古文原文，多段落建议使用两个换行符（\\n\\n）分隔。最大长度10000字符。"
      },
      "pairs": {
        "type": "integer",
        "enum": [0, 1],
        "description": "输出模式：0-整段输出（返回完整译文字符串），1-句对输出（返回逐句原文-译文对照列表）。默认为0。",
        "default": 0
      }
    },
    "required": ["src"]
  }
}

🤖 大模型调用指引（MCP / Skill 集成场景）

• MCP Server 集成：在 MCP 服务端将该工具注册为 Tool 类型，绑定到本 API 的 POST 端点。工具调用处理器中自动填充 Authorization 头部（从环境变量或安全上下文中获取 access_token）。
• AI Skill 插件：Skill 描述文件中声明上述工具定义，平台运行时根据用户意图提取 src 和可选的 pairs 参数，发起 multipart/form-data 请求，并将响应中的 text 字段返回给大模型。
• 请求转换示例：模型生成的参数 {"src": "吾十有五而志于学。三十而立。", "pairs": 1} 将被映射为请求，响应中的 text 列表包含逐句对照，模型可据此组织回答。

📤 工具返回结果示例（给大模型的输出结构）

// pairs=0 模式
{
  "status": "success",
  "translation_mode": "whole",
  "translated_text": "我十五岁立志于学习；三十岁能够自立..."
}

// pairs=1 模式
{
  "status": "success",
  "translation_mode": "pairwise",
  "segments": [
    {"original": "吾十有五而志于学。", "translation": "我十五岁立志于学习。"},
    {"original": "三十而立。", "translation": "三十岁能够自立。"}
  ],
  "segment_count": 2
}

大模型接收到结构化结果后，可向用户清晰展示：“整段译文：……” 或逐句对照表格，提升交互体验。

⚙️ MCP 特定配置建议

• 认证透传：从 MCP 会话元数据中读取 access_token，构造 Authorization: gjcool {token} 请求头。
• 异步处理：翻译任务可能耗时数秒，MCP 实现应支持异步或设置合理超时（推荐 60s）。
• 错误映射：将 API 返回的错误码（如 text too long、wenbai failed）转换为模型可理解的字符串，建议返回给大模型后由其向用户解释。
• 限流应对：收到 wait for * seconds 时可实现指数退避重试，或通知模型稍后重试。

📌 Skill 描述片段（YAML 格式参考）

skill:
  name: "ancient_to_modern_translator"
  version: "1.0.0"
  description: "将文言文翻译为现代汉语，支持整段或逐句对照输出"
  tools:
    - name: "translate_ancient_chinese"
      method: "POST"
      endpoint: "/wenbai"
      headers:
        Authorization: "gjcool "
      parameters:
        - name: "src"
          type: "string"
          required: true
        - name: "pairs"
          type: "integer"
          required: false
          default: 0
      output_mapping: |
        if pairs == 0: translated_text = response.text
        else: segments = response.text  # list of {orig, trans}

大模型工具调用规范 (MCP / Skill 集成)

本 API 完全兼容大模型生态的工具调用范式，可作为 MCP (Model Context Protocol) 服务端工具或 AI Skill 插件使用。大模型通过函数调用（Function Calling / Tool Use）触发文本对齐能力，实现原文与译文的句子级对照，辅助古籍翻译校对、多版本比较等任务。

🛠️ 工具定义（Tool Schema）

推荐的工具元数据如下，可直接用于 MCP 服务或自定义 Skill 清单：

{
  "name": "align_chinese_texts",
  "description": "将两段中文文本（如古籍原文与现代译文）进行句子级对齐，输出一一对应的句子对。支持指定语言对类型和对齐粒度。最大输入每段10000字。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "a": {
        "type": "string",
        "description": "文本 A，通常是原文或参考文本。建议使用标点符号断句。最大10000字符。"
      },
      "b": {
        "type": "string",
        "description": "文本 B，通常为译文或对照文本。建议使用标点符号断句。最大10000字符。"
      },
      "lang": {
        "type": "integer",
        "enum": [0, 1, 2, 3],
        "description": "语言对类型：0-古对古，1-古对现（默认），2-现对古，3-现对现。影响内部语义匹配策略。",
        "default": 1
      },
      "output": {
        "type": "integer",
        "enum": [0, 1, 2, 3, 4, 5],
        "description": "输出对齐形式：0-短句对短句，1-短句对句，2-句对短句，3-句对句，4-最短句，5-截断。默认为0。",
        "default": 0
      }
    },
    "required": ["a", "b"]
  }
}

🤖 大模型调用指引（MCP / Skill 集成场景）

• MCP Server 集成：在 MCP 服务端将该工具注册为 Tool 类型，绑定到本 API 的 POST 端点。工具调用处理器中自动填充 Authorization 头部（从环境变量或安全上下文中获取 access_token）。
• AI Skill 插件：Skill 描述文件中声明上述工具定义，平台运行时根据用户意图提取 a、b 以及可选的 lang、output 参数，发起 multipart/form-data 请求，并将响应中的 text 列表返回给大模型。
• 请求转换示例：模型生成的参数 {"a": "学而时习之。", "b": "学习并时常温习。", "lang": 1, "output": 3} 将被映射为请求，响应中的 text 为对齐后的句对列表。

📤 工具返回结果示例（给大模型的输出结构）

{
  "status": "success",
  "aligned_pairs": [
    {"source": "学而时习之，不亦说乎？", "target": "学习并时常温习，不是很愉快吗？"},
    {"source": "有朋自远方来，不亦乐乎？", "target": "有志同道合的人从远方来，不是很令人高兴的吗？"}
  ],
  "pair_count": 2,
  "output_mode": "句-句"
}

大模型接收到结构化结果后，可向用户清晰展示对照表格，或进一步总结对齐质量。

⚙️ MCP 特定配置建议

• 认证透传：从 MCP 会话元数据中读取 access_token，构造 Authorization: gjcool {token} 请求头。
• 异步处理：对齐任务可能耗时数秒，MCP 实现应支持异步或设置合理超时（推荐 60s）。
• 错误映射：将 API 返回的错误码（如 align failed、text too long）转换为模型可理解的字符串，建议返回给大模型由其向用户解释。
• 限流应对：收到 wait for * seconds 时可实现指数退避重试，或通知模型稍后重试。

📌 Skill 描述片段（YAML 格式参考）

skill:
  name: "chinese_text_aligner"
  version: "1.0.0"
  description: "将两段中文文本进行句子级对齐，用于古籍与译本对照"
  tools:
    - name: "align_chinese_texts"
      method: "POST"
      endpoint: "/align"
      headers:
        Authorization: "gjcool "
      parameters:
        - name: "a"
          type: "string"
          required: true
        - name: "b"
          type: "string"
          required: true
        - name: "lang"
          type: "integer"
          required: false
          default: 1
        - name: "output"
          type: "integer"
          required: false
          default: 0
      output_mapping: "aligned_pairs = response.text"