Herdsman 多协议接入包

要解决什么问题

很多 Agent 平台默认只认 OpenAI Chat Completions、Anthropic Messages，或自家的 AG-UI 事件流；而 Herdsman 是跑在本机的模型引擎，能力横跨对话、工具、向量、重排序、文生图/编辑/图生图、OCR、文档解析和语音 ASR/TTS。若在 shell 里手写带 tools、base64 图片或长超时的 curl，既难维护也容易超时失败。

本技能不是单脚本，而是一套可复用的接入包：约定默认端点（如 http://127.0.0.1:8080/v1）、强制调用规则，以及 scripts/ 下的 Python 封装。

如何工作

协议选择：优先 OpenAI 兼容（GET /v1/models、POST /v1/chat/completions、embeddings、rerank、images、POST /v1/ocr、documents、audio）；仅支持 Anthropic 风格时用 POST /v1/anthropic/messages；支持 AG-UI 时用 POST /agui（建议走 SDK，不要裸拼 HTTP）。

推荐流程：

1. 用 scripts/check_model.py 做模型探测，再按能力选模型。
2. 长任务走脚本（如 generate_image.py、ocr.py、parse_document.py、transcribe_stream.py），并显式加长 timeout（OCR/图像常 ≥120s，文档解析可 ≥300s）。
3. 需在后续轮次复用的图片等产物写入 outputs/，返回绝对路径或缓存 URL，避免只吐大段 base64。

聊天补全还可传扩展参数：reasoning_effort、thinking_enabled、thinking_tokens（本地 llama.cpp 会映射到对应模板参数）。语音侧另有 convert_audio.py → transcribe_standalone.py → tts_voice_clone.py 的克隆工作流。

边界与注意

• 遇到 model_not_found / model_not_installed / invalid_model_capability 时应重新探测模型；OCR 前确认如 paddleocr-ppocrv5-server 已安装。
• Anthropic SDK 若写死 /v1/messages，需在平台侧代理或改用原始 HTTP 指向 /v1/anthropic/messages。
• 部分 ASR 模型仅支持 WebSocket 流式，HTTP 整段转写不可用；funasr 等需选对脚本与协议。
• API Key 默认可空；若已配置，请求头使用 Authorization: Bearer <key>。