Herdsman Skill

本目录不是单一脚本，而是一套给其他 agent 平台复用的接入包，目标是让外部 agent 稳定访问 Herdsman 本地模型引擎。

适用场景

• 其他 agent 平台需要把 Herdsman 当作 OpenAI 兼容后端使用
• 平台希望以 Anthropic Messages 兼容方式访问 Herdsman
• 平台本身支持 AG-UI 协议，需要对接 /agui
• 需要稳定调用文本、图片、OCR、向量、语音等能力，且不希望在 shell 中手写长 JSON

默认连接信息

• 服务地址：http://127.0.0.1:8080
• OpenAI 兼容根路径：http://127.0.0.1:8080/v1
• Anthropic 兼容入口：http://127.0.0.1:8080/v1/anthropic/messages
• AGUI 入口：http://127.0.0.1:8080/agui
• API Key：默认可为空；如已配置，请使用 Authorization: Bearer

强制调用规则

1. 不要直接拼接复杂 curl

复杂 prompt、tools、base64 图片、长超时任务都不要直接在 shell 拼接。优先复用 scripts/ 下的 Python 脚本，或按同样模式生成临时 Python 文件再执行。

2. 先做模型探测

调用任何模型前，优先执行：

python headsman-skill/scripts/check_model.py

如果只知道模型名，也可以：

python headsman-skill/scripts/check_model.py "<model_id>"

3. 长任务必须显式加长超时

• 图片生成、图片编辑、图生图：建议 timeout >= 120
• OCR 识别：建议 timeout >= 120
• 语音合成、语音识别、流式语音：建议 timeout >= 120
• 文本对话：建议 timeout >= 60

4. 图片结果要落盘

如果结果会在后续对话中继续使用，优先保存到 outputs/，并向用户返回绝对路径或缓存 URL。

协议优先级

OpenAI 兼容

优先用于：

• 聊天补全
• 工具调用
• 向量嵌入
• 重排序（Rerank）
• 图片生成 / 编辑 / 图生图
• OCR 文本识别
• 语音识别 / 合成 / 流式识别

核心接口：

• GET /v1/models
• POST /v1/chat/completions
• POST /v1/embeddings
• POST /v1/rerank
• POST /v1/images/generations
• POST /v1/images/edits
• POST /v1/images/img2img
• GET /v1/images/cache/:filename
• POST /v1/ocr
• POST /v1/audio/transcriptions
• GET /v1/audio/transcriptions/stream?model=（WebSocket）
• POST /v1/audio/speech
• GET /v1/audio/speech/stream/:token
• GET /v1/audio/info?model=

聊天补全额外参数（OpenAI Chat Completions 兼容扩展）：

| 参数 | 类型 | 说明 |

|------|------|------|

| reasoning_effort | string | 推理级别：low / medium / high；本地 llama.cpp 会映射到模板参数 |

| thinking_enabled | boolean | 为支持的模型启用或关闭思考模式；本地 llama.cpp 映射为 enable_thinking |

| thinking_tokens | number | 思考 token 预算；本地 llama.cpp 映射为 reasoning_budget |

Anthropic 兼容

适用于只能走 Anthropic Messages 风格请求的平台，入口为：

• POST /v1/anthropic/messages

因此：

• 若平台支持自定义完整 endpoint，可直接接入
• 若 SDK 固定写死 /v1/messages，应在平台侧加一层轻量代理或改用原始 HTTP 请求

AGUI

适用于支持 AG-UI 协议事件流的平台：

• POST /agui

AGUI 更适合协议客户端或 SDK，不建议手写裸 HTTP。当前运行状态中，state 至少应提供 model，可选附带 webSearch、tools、task_type、pass_through。

推荐脚本

• scripts/herdsman_client.py：通用 HTTP 调用封装
• scripts/check_model.py：模型发现与筛选
• scripts/chat_completion.py：OpenAI 聊天补全（支持 reasoning_effort / thinking）
• scripts/generate_image.py：文生图并可自动下载结果
• scripts/edit_image.py：图片编辑，支持本地文件、URL、mask 和额外参考图
• scripts/img2img.py：图生图（风格迁移、重绘）
• scripts/ocr.py：OCR 文本识别，支持本地图片直接识别
• scripts/transcribe_audio.py：语音转写，支持本地文件、URL 和 data URL
• scripts/audio_speech.py：语音合成（TTS），支持 VoiceDesign、VoiceClone 与流式
• scripts/anthropic_messages.py：Anthropic Messages 兼容调用

目录说明

• references/api-examples.md：按能力分类的调用示例
• references/platform-integration.md：OpenAI / Anthropic / AGUI 接入说明
• references/error-codes.md：常见错误和 agent 侧处理策略
• references/model-capabilities.md：模型能力与接口映射
• outputs/：建议保存图片等产物的位置

最佳实践

1. 先用 check_model.py 获取已安装模型
2. 再按平台协议选择 OpenAI、Anthropic 或 AGUI
3. 对长任务统一走 Python 脚本而不是 shell 拼接
4. 对图片结果保存文件或缓存 URL，避免只返回大段 base64
5. 遇到 model_not_found、model_not_installed、invalid_model_capability 时先重新做模型探测
6. 语音转写支持 JSON body（audio 字段）与 multipart/form-data（file 字段）两种方式
7. OCR 识别前建议先用 check_model.py 确认 paddleocr-ppocrv5-server 或其他 OCR 模型已安装

语音扩展：TTS 语音克隆 + ASR 独立转写

以下三个脚本是绑定 Herdsman 的高阶语音工具，支持从音频转换→ASR 转写→语音克隆的完整工作流。

脚本概览

| 脚本 | 功能 | 外部依赖 |

|------|------|---------|

| scripts/convert_audio.py | 音频格式转换（任意格式→16kHz WAV） | ffmpeg |

| scripts/transcribe_standalone.py | ASR 语音转写（纯 urllib，无需 herdsman_client） | Herdsman ASR 模型 |

| scripts/tts_voice_clone.py | 语音克隆 TTS 合成 | Herdsman qwen3-tts-voiceclone |

convert_audio.py

将任意格式音频（MP3/M4A/OGG 等）转为 16kHz 单声道 WAV。不依赖 Herdsman。

uv run python scripts/convert_audio.py <输入路径> [输出路径]

参数：

• 输入路径 — 参考音频文件路径
• 输出路径 — 可选，默认输入文件同目录 .wav

示例：

uv run python scripts/convert_audio.py ref.mp3
uv run python scripts/convert_audio.py ref.mp3 ref.wav

transcribe_standalone.py

独立 ASR 语音转写脚本（纯 urllib，不依赖 herdsman_client.py）。模型动态选择，支持输出绝对路径。

uv run python scripts/transcribe_standalone.py <音频路径> --model <模型ID> [--language <语言>] [--output <绝对路径>]

参数：

• 音频路径 — 输入音频文件路径（.wav/.mp3/.m4a 等）
• --model — ASR 模型 ID（必填，动态选择）
• --language — 语言代码（可选，默认自动检测）
• --output / -o — 输出文件绝对路径，同时写入 .txt + .json（可选，不指定仅打印）
• --timeout — 超时秒数（默认 300）

实测模型推荐：

| 模型 | 推荐 | 特点 |

|------|------|------|

| sherpa-onnx-paraformer-zh-small | ⭐ 首选 | 简体中文，语气词保留，~5s 速度最快 |

| whisper-base | 备选 | 通用高精度，繁体输出 |

| funasr | ⚠️ | 仅 WebSocket 流式，HTTP 不支持 |

| sherpa-onnx-streaming-zipformer-zh-14m | ⚠️ | 仅流式，HTTP 不支持完整转写 |

示例：

# 推荐
uv run python scripts/transcribe_standalone.py audio.wav --model sherpa-onnx-paraformer-zh-small --output "D:/result.txt"
# 仅打印
uv run python scripts/transcribe_standalone.py audio.wav --model whisper-base

tts_voice_clone.py

使用 qwen3-tts-voiceclone 进行语音克隆 TTS 合成。三个动态传参：参考音频 WAV、原文文本、目标文稿。

uv run python scripts/tts_voice_clone.py <参考音频WAV> <原文文本> <目标文稿> [--output <路径>]

参数：

• 参考音频WAV — 16kHz 单声道 WAV 路径
• 原文文本 — 参考音频对应的原文文本
• 目标文稿 — 需要克隆朗读的目标文本
• --output / -o — 输出音频路径（默认 ripple_tts_cloned.wav）
• --timeout — 超时秒数（默认 180）

示例：

uv run python scripts/tts_voice_clone.py ref.wav "原文内容" "目标合成文本" -o output.wav

完整工作流

# 1. 转 WAV
uv run python scripts/convert_audio.py source.mp3 ref.wav

# 2. ASR 转写（提取音频文字，与原文对照）
uv run python scripts/transcribe_standalone.py ref.wav --model sherpa-onnx-paraformer-zh-small --output "D:/transcribed.txt"

# 3. 语音克隆合成
uv run python scripts/tts_voice_clone.py ref.wav "原文文本" "目标合成文稿" -o final.wav

注意事项

• 参考音频建议 10-60 秒，背景噪声少，语速自然
• 原文文本要与音频内容严格一致，否则克隆效果受影响
• ASR 转写可通过 --output 指定绝对路径，方便跨目录使用
• 错误信息输出到 stderr，正常结果输出到 stdout