better-dsh 0.2.5 → 0.3.0

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/developer-guide/trajectory-format.md

@@ -1,222 +0,0 @@
-# 轨迹格式
-
-Hermes Agent 以 ShareGPT 兼容的 JSONL 格式保存对话轨迹，用于训练数据、调试产物和强化学习数据集。
-
-源文件：`agent/trajectory.py`、`run_agent.py`（搜索 `_save_trajectory`）、`batch_runner.py`
-
-
-## 文件命名规范
-
-轨迹写入当前工作目录下的文件：
-
-| 文件 | 时机 |
-|------|------|
-| `trajectory_samples.jsonl` | 成功完成的对话（`completed=True`） |
-| `failed_trajectories.jsonl` | 失败或被中断的对话（`completed=False`） |
-
-批量运行器（`batch_runner.py`）按批次写入自定义输出文件
-（例如 `batch_001_output.jsonl`），并附带额外的元数据字段。
-
-可通过 `save_trajectory()` 的 `filename` 参数覆盖文件名。
-
-
-## JSONL 条目格式
-
-文件中每一行是一个独立的 JSON 对象。共有两种变体：
-
-### CLI/交互式格式（来自 `_save_trajectory`）
-
-```json
-{
-  "conversations": [ ... ],
-  "timestamp": "2026-03-30T14:22:31.456789",
-  "model": "anthropic/claude-sonnet-4.6",
-  "completed": true
-}
-```
-
-### 批量运行器格式（来自 `batch_runner.py`）
-
-```json
-{
-  "prompt_index": 42,
-  "conversations": [ ... ],
-  "metadata": { "prompt_source": "gsm8k", "difficulty": "hard" },
-  "completed": true,
-  "partial": false,
-  "api_calls": 7,
-  "toolsets_used": ["code_tools", "file_tools"],
-  "tool_stats": {
-    "terminal": {"count": 3, "success": 3, "failure": 0},
-    "read_file": {"count": 2, "success": 2, "failure": 0},
-    "write_file": {"count": 0, "success": 0, "failure": 0}
-  },
-  "tool_error_counts": {
-    "terminal": 0,
-    "read_file": 0,
-    "write_file": 0
-  }
-}
-```
-
-`tool_stats` 和 `tool_error_counts` 字典已规范化，包含所有可能的工具
-（来自 `model_tools.TOOL_TO_TOOLSET_MAP`），缺省值为零，
-确保各条目的 schema 一致，便于 HuggingFace 数据集加载。
-
-
-## conversations 数组（ShareGPT 格式）
-
-`conversations` 数组使用 ShareGPT 角色约定：
-
-| API 角色 | ShareGPT `from` |
-|----------|-----------------|
-| system | `"system"` |
-| user | `"human"` |
-| assistant | `"gpt"` |
-| tool | `"tool"` |
-
-### 完整示例
-
-```json
-{
-  "conversations": [
-    {
-      "from": "system",
-      "value": "You are a function calling AI model. You are provided with function signatures within <tools> </tools> XML tags. You may call one or more functions to assist with the user query. If available tools are not relevant in assisting with user query, just respond in natural conversational language. Don't make assumptions about what values to plug into functions. After calling & executing the functions, you will be provided with function results within <tool_response> </tool_response> XML tags. Here are the available tools:\n<tools>\n[{\"name\": \"terminal\", \"description\": \"Execute shell commands\", \"parameters\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}}, \"required\": null}]\n</tools>\nFor each function call return a JSON object, with the following pydantic model json schema for each:\n{'title': 'FunctionCall', 'type': 'object', 'properties': {'name': {'title': 'Name', 'type': 'string'}, 'arguments': {'title': 'Arguments', 'type': 'object'}}, 'required': ['name', 'arguments']}\nEach function call should be enclosed within <tool_call> </tool_call> XML tags.\nExample:\n<tool_call>\n{'name': <function-name>,'arguments': <args-dict>}\n</tool_call>"
-    },
-    {
-      "from": "human",
-      "value": "What Python version is installed?"
-    },
-    {
-      "from": "gpt",
-      "value": "<think>\nThe user wants to know the Python version. I should run python3 --version.\n</think>\n<tool_call>\n{\"name\": \"terminal\", \"arguments\": {\"command\": \"python3 --version\"}}\n</tool_call>"
-    },
-    {
-      "from": "tool",
-      "value": "<tool_response>\n{\"tool_call_id\": \"call_abc123\", \"name\": \"terminal\", \"content\": \"Python 3.11.6\"}\n</tool_response>"
-    },
-    {
-      "from": "gpt",
-      "value": "<think>\nGot the version. I can now answer the user.\n</think>\nPython 3.11.6 is installed on this system."
-    }
-  ],
-  "timestamp": "2026-03-30T14:22:31.456789",
-  "model": "anthropic/claude-sonnet-4.6",
-  "completed": true
-}
-```
-
-
-## 规范化规则
-
-### 推理内容标记
-
-轨迹转换器将所有推理内容统一规范化为 `<think>` 标签，无论模型最初以何种方式生成：
-
-1. **原生思考 token**（来自 Anthropic、OpenAI o 系列等提供商的 `msg["reasoning"]` 字段）：
-   包装为 `<think>\n{reasoning}\n</think>\n` 并置于内容之前。
-
-2. **REASONING_SCRATCHPAD XML**（禁用原生思考时，模型通过系统提示指令的 XML 进行推理）：
-   `<REASONING_SCRATCHPAD>` 标签通过 `convert_scratchpad_to_think()` 转换为 `<think>`。
-
-3. **空 think 块**：每个 `gpt` 轮次都保证包含一个 `<think>` 块。若未产生任何推理内容，
-   则插入空块：`<think>\n</think>\n`——确保训练数据格式一致。
-
-### 工具调用规范化
-
-API 格式的工具调用（含 `tool_call_id`、函数名、JSON 字符串形式的参数）
-转换为 XML 包裹的 JSON：
-
-```
-<tool_call>
-{"name": "terminal", "arguments": {"command": "ls -la"}}
-</tool_call>
-```
-
-- 参数从 JSON 字符串解析回对象（不进行二次编码）
-- 若 JSON 解析失败（正常情况下不应发生——对话期间已验证），
-  则使用空 `{}` 并记录警告日志
-- 一个助手轮次中的多个工具调用，在单条 `gpt` 消息中生成多个 `<tool_call>` 块
-
-### 工具响应规范化
-
-跟随助手消息的所有工具结果，合并为单条 `tool` 轮次，以 XML 包裹的 JSON 响应呈现：
-
-```
-<tool_response>
-{"tool_call_id": "call_abc123", "name": "terminal", "content": "output here"}
-</tool_response>
-```
-
-- 若工具内容看起来像 JSON（以 `{` 或 `[` 开头），则解析后 content 字段包含 JSON 对象/数组，而非字符串
-- 多个工具结果以换行符连接，合并为一条消息
-- 工具名称按位置与父助手消息的 `tool_calls` 数组匹配
-
-### 系统消息
-
-系统消息在保存时生成（不取自对话内容），遵循 Hermes 函数调用 prompt 模板，包含：
-
-- 说明函数调用协议的前言
-- 包含 JSON 工具定义的 `<tools>` XML 块
-- `FunctionCall` 对象的 schema 参考
-- `<tool_call>` 示例
-
-工具定义包含 `name`、`description`、`parameters` 和 `required`
-（设为 `null` 以匹配规范格式）。
-
-
-## 加载轨迹
-
-轨迹为标准 JSONL 格式——可用任意 JSON lines 读取器加载：
-
-```python
-import json
-
-def load_trajectories(path: str):
-    """Load trajectory entries from a JSONL file."""
-    entries = []
-    with open(path, "r", encoding="utf-8") as f:
-        for line in f:
-            line = line.strip()
-            if line:
-                entries.append(json.loads(line))
-    return entries
-
-# Filter to successful completions only
-successful = [e for e in load_trajectories("trajectory_samples.jsonl")
-              if e.get("completed")]
-
-# Extract just the conversations for training
-training_data = [e["conversations"] for e in successful]
-```
-
-### 加载至 HuggingFace Datasets
-
-```python
-from datasets import load_dataset
-
-ds = load_dataset("json", data_files="trajectory_samples.jsonl")
-```
-
-规范化的 `tool_stats` schema 确保所有条目具有相同的列，
-防止数据集加载时出现 Arrow schema 不匹配错误。
-
-
-## 控制轨迹保存
-
-在 CLI 中，轨迹保存通过以下方式控制：
-
-```yaml
-# config.yaml
-agent:
-  save_trajectories: true  # default: false
-```
-
-或通过 `--save-trajectories` 标志。当 agent 以 `save_trajectories=True` 初始化时，
-`_save_trajectory()` 方法在每次对话轮次结束时调用。
-
-批量运行器始终保存轨迹（这是其主要用途）。
-
-所有轮次中推理内容为零的样本，将被批量运行器自动丢弃，
-以避免非推理示例污染训练数据。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/developer-guide/video-gen-provider-plugin.md

@@ -1,231 +0,0 @@
----
-sidebar_position: 12
-title: "视频生成 Provider 插件"
-description: "如何为 Hermes Agent 构建视频生成后端插件"
----
-
-# 构建视频生成 Provider 插件
-
-视频生成 provider 插件注册一个后端，用于处理所有 `video_generate` 工具调用。内置 provider（xAI、FAL）以插件形式提供。将目录放入 `plugins/video_gen/<name>/` 即可添加新 provider 或覆盖内置 provider。
-
-:::tip
-视频生成与[图像生成 Provider 插件](/developer-guide/image-gen-provider-plugin)几乎一一对应——如果你已构建过图像生成后端，对其结构应已了然于胸。主要区别在于：`capabilities()` 方法用于声明模态（modality）/宽高比/时长，以及路由约定（传入 `image_url` 则使用图生视频，省略则使用文生视频——provider 在内部选择正确的端点）。
-:::
-
-## 统一接口（一个工具，两种模态）
-
-`video_generate` 工具通过一个参数暴露两种模态：
-
-- **文生视频（Text-to-video）** — 仅传入 `prompt`。Provider 路由至其文生视频端点。
-- **图生视频（Image-to-video）** — 同时传入 `prompt` 和 `image_url`。Provider 路由至其图生视频端点。
-
-编辑和扩展功能有意不在支持范围内。大多数后端不支持这些功能，且不一致性会迫使 agent 的工具描述中出现针对各后端的说明文字。
-
-## 发现机制
-
-Hermes 在三个位置扫描视频生成后端：
-
-1. **内置** — `<repo>/plugins/video_gen/<name>/`（通过 `kind: backend` 自动加载）
-2. **用户** — `~/.hermes/plugins/video_gen/<name>/`（通过 `plugins.enabled` 选择启用）
-3. **Pip** — 声明了 `hermes_agent.plugins` 入口点的包
-
-每个插件的 `register(ctx)` 函数调用 `ctx.register_video_gen_provider(...)`。活跃 provider 由 `config.yaml` 中的 `video_gen.provider` 指定；`hermes tools` → Video Generation 引导用户完成选择。与 `image_generate` 不同，此处没有内置的遗留后端——每个 provider 都是插件。
-
-## 目录结构
-
-```
-plugins/video_gen/my-backend/
-├── __init__.py      # VideoGenProvider 子类 + register()
-└── plugin.yaml      # 包含 kind: backend 的清单文件
-```
-
-## VideoGenProvider ABC
-
-继承 `agent.video_gen_provider.VideoGenProvider`。必须实现：`name` 属性和 `generate()` 方法。
-
-```python
-# plugins/video_gen/my-backend/__init__.py
-from typing import Any, Dict, List, Optional
-import os
-
-from agent.video_gen_provider import (
-    VideoGenProvider,
-    error_response,
-    success_response,
-)
-
-
-class MyVideoGenProvider(VideoGenProvider):
-    @property
-    def name(self) -> str:
-        return "my-backend"
-
-    @property
-    def display_name(self) -> str:
-        return "My Backend"
-
-    def is_available(self) -> bool:
-        return bool(os.environ.get("MY_API_KEY"))
-
-    def list_models(self) -> List[Dict[str, Any]]:
-        # Each entry is a model FAMILY — a name the user picks once.
-        # Your provider's generate() routes within the family based on
-        # whether image_url was passed.
-        return [
-            {
-                "id": "fast",
-                "display": "Fast",
-                "speed": "~30s",
-                "strengths": "Cheapest tier",
-                "price": "$0.05/s",
-                "modalities": ["text", "image"],  # advisory
-            },
-        ]
-
-    def default_model(self) -> Optional[str]:
-        return "fast"
-
-    def capabilities(self) -> Dict[str, Any]:
-        return {
-            "modalities": ["text", "image"],
-            "aspect_ratios": ["16:9", "9:16"],
-            "resolutions": ["720p", "1080p"],
-            "min_duration": 1,
-            "max_duration": 10,
-            "supports_audio": False,
-            "supports_negative_prompt": True,
-            "max_reference_images": 0,
-        }
-
-    def get_setup_schema(self) -> Dict[str, Any]:
-        return {
-            "name": "My Backend",
-            "badge": "paid",
-            "tag": "Short description shown in `hermes tools`",
-            "env_vars": [
-                {
-                    "key": "MY_API_KEY",
-                    "prompt": "My Backend API key",
-                    "url": "https://mybackend.example.com/keys",
-                },
-            ],
-        }
-
-    def generate(
-        self,
-        prompt: str,
-        *,
-        model: Optional[str] = None,
-        image_url: Optional[str] = None,
-        reference_image_urls: Optional[List[str]] = None,
-        duration: Optional[int] = None,
-        aspect_ratio: str = "16:9",
-        resolution: str = "720p",
-        negative_prompt: Optional[str] = None,
-        audio: Optional[bool] = None,
-        seed: Optional[int] = None,
-        **kwargs: Any,  # always ignore unknown kwargs for forward-compat
-    ) -> Dict[str, Any]:
-        # ROUTE: image_url presence picks the endpoint.
-        if image_url:
-            endpoint = "my-backend/image-to-video"
-            modality_used = "image"
-        else:
-            endpoint = "my-backend/text-to-video"
-            modality_used = "text"
-
-        # ... call your API ...
-
-        return success_response(
-            video="https://your-cdn/output.mp4",
-            model=model or "fast",
-            prompt=prompt,
-            modality=modality_used,
-            aspect_ratio=aspect_ratio,
-            duration=duration or 5,
-            provider=self.name,
-        )
-
-
-def register(ctx) -> None:
-    ctx.register_video_gen_provider(MyVideoGenProvider())
-```
-
-## 插件清单
-
-```yaml
-# plugins/video_gen/my-backend/plugin.yaml
-name: my-backend
-version: 1.0.0
-description: "My video generation backend"
-author: Your Name
-kind: backend
-requires_env:
-  - MY_API_KEY
-```
-
-## `video_generate` 参数模式
-
-该工具在所有后端中使用统一的参数模式。Provider 忽略其不支持的参数。
-
-| 参数 | 说明 |
-|---|---|
-| `prompt` | 文本指令（必填） |
-| `image_url` | 设置时 → 图生视频；省略时 → 文生视频 |
-| `reference_image_urls` | 风格/角色参考图（取决于 provider） |
-| `duration` | 秒数——provider 会进行截断 |
-| `aspect_ratio` | `"16:9"`、`"9:16"`、`"1:1"` 等——provider 会进行截断 |
-| `resolution` | `"480p"` / `"540p"` / `"720p"` / `"1080p"`——provider 会进行截断 |
-| `negative_prompt` | 需要避免的内容（仅 Pixverse/Kling 支持） |
-| `audio` | 原生音频（Veo3 / Pixverse 定价层级） |
-| `seed` | 可复现性 |
-| `model` | 覆盖当前活跃的模型/系列 |
-
-Provider 的 `capabilities()` 声明上述哪些参数会被实际处理。Agent 在工具描述中看到的是当前活跃后端的能力信息，当用户通过 `hermes tools` 切换后端时会动态重建。
-
-## 模型系列与端点路由（FAL 模式）
-
-当你的后端每个"模型"对应多个端点时——例如 FAL，其中每个系列（Veo 3.1、Pixverse v6、Kling O3）都有 `/text-to-video` 和 `/image-to-video` 两个 URL——将每个**系列**表示为一个目录条目。你的 `generate()` 根据是否传入 `image_url` 来选择正确的端点：
-
-```python
-FAMILIES = {
-    "veo3.1": {
-        "text_endpoint": "fal-ai/veo3.1",
-        "image_endpoint": "fal-ai/veo3.1/image-to-video",
-        # ... family-specific capability flags ...
-    },
-}
-
-def generate(self, prompt, *, image_url=None, model=None, **kwargs):
-    family_id, family = _resolve_family(model)
-    endpoint = family["image_endpoint"] if image_url else family["text_endpoint"]
-    # ... build payload from family's declared capability flags, call endpoint ...
-```
-
-用户在 `hermes tools` 中只需选择一次 `veo3.1`。Agent 无需关心端点——它只负责传入（或不传入）`image_url`。
-
-## 选择优先级
-
-针对每个实例的模型配置（参见 `plugins/video_gen/fal/__init__.py`）：
-
-1. 工具调用中的 `model=` 关键字参数
-2. `<PROVIDER>_VIDEO_MODEL` 环境变量
-3. `config.yaml` 中的 `video_gen.<provider>.model`
-4. `config.yaml` 中的 `video_gen.model`（当其值为你的某个 ID 时）
-5. Provider 的 `default_model()`
-
-## 响应结构
-
-`success_response()` 和 `error_response()` 生成每个后端返回的标准 dict 结构。请使用它们——不要手动构造 dict。
-
-成功响应的键：`success`、`video`（URL 或绝对路径）、`model`、`prompt`、`modality`（`"text"` 或 `"image"`）、`aspect_ratio`、`duration`、`provider`，以及 `extra`。
-
-错误响应的键：`success`、`video`（None）、`error`、`error_type`、`model`、`prompt`、`aspect_ratio`、`provider`。
-
-## 产物保存位置
-
-如果你的后端返回 base64 数据，使用 `save_b64_video()` 将其写入 `$HERMES_HOME/cache/videos/`。对于通过后续 HTTP 请求获取的原始字节，使用 `save_bytes_video()`。否则直接返回上游 URL——gateway 在交付时会解析远程 URL。
-
-## 测试
-
-在 `tests/plugins/video_gen/test_<name>_plugin.py` 下添加冒烟测试。xAI 和 FAL 的测试展示了标准模式——注册、验证目录、分别在传入和不传入 `image_url` 的情况下测试路由，并断言在缺少认证时返回干净的错误响应。