better-dsh 0.2.4 → 0.2.5-a

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/guides/python-library.md

@@ -0,0 +1,333 @@
+---
+sidebar_position: 5
+title: "将 Hermes 作为 Python 库使用"
+description: "将 AIAgent 嵌入你自己的 Python 脚本、Web 应用或自动化流水线——无需 CLI"
+---
+
+# 将 Hermes 作为 Python 库使用
+
+Hermes 不仅仅是一个 CLI 工具。你可以直接导入 `AIAgent`，在自己的 Python 脚本、Web 应用或自动化流水线中以编程方式使用它。本指南将介绍具体方法。
+
+---
+
+## 安装
+
+克隆 Hermes 并创建受支持的可编辑开发环境：
+
+```bash
+git clone https://github.com/NousResearch/hermes-agent.git
+cd hermes-agent
+uv sync
+```
+
+在该检出目录中使用 `uv run python your_app.py` 运行应用。Hermes 不发布用于 `requirements.txt` 安装的受支持 wheel 或源代码发行版。
+
+:::tip
+将 Hermes 作为库使用时，CLI 所需的环境变量同样必须设置。至少需要设置 `OPENROUTER_API_KEY`（若直接访问提供商，则设置 `OPENAI_API_KEY` 或 `ANTHROPIC_API_KEY`）。
+:::
+
+---
+
+## 基本用法
+
+使用 Hermes 最简单的方式是 `chat()` 方法——传入一条消息，返回一个字符串：
+
+```python
+from run_agent import AIAgent
+
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4",
+    quiet_mode=True,
+)
+response = agent.chat("What is the capital of France?")
+print(response)
+```
+
+`chat()` 在内部处理完整的对话循环——工具调用、重试等一切事务——并仅返回最终的文本响应。
+
+:::warning
+将 Hermes 嵌入自己的代码时，务必设置 `quiet_mode=True`。否则，agent 会打印 CLI 的加载动画、进度指示器及其他终端输出，从而干扰你的应用输出。
+:::
+
+---
+
+## 完整对话控制
+
+如需对对话进行更精细的控制，可直接使用 `run_conversation()`。它返回一个包含完整响应、消息历史和元数据的字典：
+
+```python
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4",
+    quiet_mode=True,
+)
+
+result = agent.run_conversation(
+    user_message="Search for recent Python 3.13 features",
+    task_id="my-task-1",
+)
+
+print(result["final_response"])
+print(f"Messages exchanged: {len(result['messages'])}")
+```
+
+返回的字典包含：
+- **`final_response`** — agent 的最终文本回复
+- **`messages`** — 完整的消息历史（系统消息、用户消息、助手消息、工具调用）
+
+（传入的 `task_id` 存储在 agent 实例上用于 VM 隔离，不会在返回字典中回显。）
+
+你也可以传入自定义系统消息，覆盖该次调用的临时系统 prompt（提示词）：
+
+```python
+result = agent.run_conversation(
+    user_message="Explain quicksort",
+    system_message="You are a computer science tutor. Use simple analogies.",
+)
+```
+
+---
+
+## 配置工具集
+
+使用 `enabled_toolsets` 或 `disabled_toolsets` 控制 agent 可访问的工具集：
+
+```python
+# 仅启用 Web 工具（浏览、搜索）
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4",
+    enabled_toolsets=["web"],
+    quiet_mode=True,
+)
+
+# 启用除终端访问外的所有功能
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4",
+    disabled_toolsets=["terminal"],
+    quiet_mode=True,
+)
+```
+
+:::tip
+当你需要一个功能最小化、受限的 agent 时（例如，仅用于研究机器人的 Web 搜索），使用 `enabled_toolsets`。当你需要大部分功能但需限制特定能力时（例如，在共享环境中禁用终端访问），使用 `disabled_toolsets`。
+:::
+
+---
+
+## 多轮对话
+
+通过将消息历史传回来维护多轮对话的状态：
+
+```python
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4",
+    quiet_mode=True,
+)
+
+# 第一轮
+result1 = agent.run_conversation("My name is Alice")
+history = result1["messages"]
+
+# 第二轮——agent 记住了上下文
+result2 = agent.run_conversation(
+    "What's my name?",
+    conversation_history=history,
+)
+print(result2["final_response"])  # "Your name is Alice."
+```
+
+`conversation_history` 参数接受上一次结果的 `messages` 列表。agent 会在内部复制该列表，因此你的原始列表不会被修改。
+
+---
+
+## 保存轨迹数据
+
+启用轨迹保存，以 ShareGPT 格式捕获对话——适用于生成训练数据或调试：
+
+```python
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4",
+    save_trajectories=True,
+    quiet_mode=True,
+)
+
+agent.chat("Write a Python function to sort a list")
+# 以 ShareGPT 格式保存到 trajectory_samples.jsonl
+```
+
+每次对话以单行 JSONL 的形式追加写入，便于从自动化运行中收集数据集。
+
+---
+
+## 自定义系统 Prompt
+
+使用 `ephemeral_system_prompt` 设置自定义系统 prompt，用于引导 agent 的行为，但**不会**保存到轨迹文件中（保持训练数据的整洁）：
+
+```python
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4",
+    ephemeral_system_prompt="You are a SQL expert. Only answer database questions.",
+    quiet_mode=True,
+)
+
+response = agent.chat("How do I write a JOIN query?")
+print(response)
+```
+
+这非常适合构建专用 agent——代码审查员、文档撰写员、SQL 助手——全部使用相同的底层工具。
+
+---
+
+## 批量处理
+
+如需并行运行大量 prompt，Hermes 提供了 `batch_runner.py`，它可管理并发的 `AIAgent` 实例并进行适当的资源隔离：
+
+```bash
+python batch_runner.py --input prompts.jsonl --output results.jsonl
+```
+
+每个 prompt 都有自己的 `task_id` 和隔离环境。如果需要自定义批处理逻辑，可以直接使用 `AIAgent` 构建：
+
+```python
+import concurrent.futures
+from run_agent import AIAgent
+
+prompts = [
+    "Explain recursion",
+    "What is a hash table?",
+    "How does garbage collection work?",
+]
+
+def process_prompt(prompt):
+    # 每个任务创建一个新的 agent 实例以保证线程安全
+    agent = AIAgent(
+        model="anthropic/claude-sonnet-4",
+        quiet_mode=True,
+        skip_memory=True,
+    )
+    return agent.chat(prompt)
+
+with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
+    results = list(executor.map(process_prompt, prompts))
+
+for prompt, result in zip(prompts, results):
+    print(f"Q: {prompt}\nA: {result}\n")
+```
+
+:::warning
+务必为**每个线程或任务创建一个新的 `AIAgent` 实例**。agent 维护着内部状态（对话历史、工具会话、迭代计数器），这些状态不是线程安全的，不能共享。
+:::
+
+---
+
+## 集成示例
+
+### FastAPI 端点
+
+```python
+from fastapi import FastAPI
+from pydantic import BaseModel
+from run_agent import AIAgent
+
+app = FastAPI()
+
+class ChatRequest(BaseModel):
+    message: str
+    model: str = "anthropic/claude-sonnet-4"
+
+@app.post("/chat")
+async def chat(request: ChatRequest):
+    agent = AIAgent(
+        model=request.model,
+        quiet_mode=True,
+        skip_context_files=True,
+        skip_memory=True,
+    )
+    response = agent.chat(request.message)
+    return {"response": response}
+```
+
+### Discord 机器人
+
+```python
+import discord
+from run_agent import AIAgent
+
+client = discord.Client(intents=discord.Intents.default())
+
+@client.event
+async def on_message(message):
+    if message.author == client.user:
+        return
+    if message.content.startswith("!hermes "):
+        query = message.content[8:]
+        agent = AIAgent(
+            model="anthropic/claude-sonnet-4",
+            quiet_mode=True,
+            skip_context_files=True,
+            skip_memory=True,
+            platform="discord",
+        )
+        response = agent.chat(query)
+        await message.channel.send(response[:2000])
+
+client.run("YOUR_DISCORD_TOKEN")
+```
+
+### CI/CD 流水线步骤
+
+```python
+#!/usr/bin/env python3
+"""CI step: auto-review a PR diff."""
+import subprocess
+from run_agent import AIAgent
+
+diff = subprocess.check_output(["git", "diff", "main...HEAD"]).decode()
+
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4",
+    quiet_mode=True,
+    skip_context_files=True,
+    skip_memory=True,
+    disabled_toolsets=["terminal", "browser"],
+)
+
+review = agent.chat(
+    f"Review this PR diff for bugs, security issues, and style problems:\n\n{diff}"
+)
+print(review)
+```
+
+---
+
+## 关键构造函数参数
+
+| 参数 | 类型 | 默认值 | 描述 |
+|-----------|------|---------|-------------|
+| `model` | `str` | `"anthropic/claude-opus-4.6"` | OpenRouter 格式的模型名称 |
+| `quiet_mode` | `bool` | `False` | 抑制 CLI 输出 |
+| `enabled_toolsets` | `List[str]` | `None` | 白名单指定工具集 |
+| `disabled_toolsets` | `List[str]` | `None` | 黑名单指定工具集 |
+| `save_trajectories` | `bool` | `False` | 将对话保存为 JSONL |
+| `ephemeral_system_prompt` | `str` | `None` | 自定义系统 prompt（不保存到轨迹文件） |
+| `max_iterations` | `int` | `500` | 每次对话的最大工具调用迭代次数 |
+| `skip_context_files` | `bool` | `False` | 跳过加载 AGENTS.md 文件 |
+| `skip_memory` | `bool` | `False` | 禁用持久化内存的读写 |
+| `api_key` | `str` | `None` | API 密钥（回退到环境变量） |
+| `base_url` | `str` | `None` | 自定义 API 端点 URL |
+| `platform` | `str` | `None` | 平台提示（`"discord"`、`"telegram"` 等） |
+
+---
+
+## 重要说明
+
+:::tip
+- 如果不希望将工作目录中的 `AGENTS.md` 文件加载到系统 prompt 中，请设置 **`skip_context_files=True`**。
+- 设置 **`skip_memory=True`** 可阻止 agent 读写持久化内存——推荐用于无状态 API 端点。
+- `platform` 参数（如 `"discord"`、`"telegram"`）会注入平台特定的格式化提示，使 agent 适配其输出风格。
+:::
+
+:::warning
+- **线程安全**：每个线程或任务创建一个 `AIAgent` 实例。切勿在并发调用中共享同一实例。
+- **资源清理**：agent 在对话结束时会自动清理资源（终端会话、浏览器实例）。若在长期运行的进程中使用，请确保每次对话正常结束。
+- **迭代限制**：默认的 `max_iterations=500` 较为宽松。对于简单的问答场景，建议适当降低该值（如 `max_iterations=10`），以防止工具调用循环失控并控制成本。
+:::

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/guides/run-hermes-with-nous-portal.md

@@ -0,0 +1,273 @@
+---
+sidebar_position: 1
+title: "通过 Nous Portal 运行 Hermes Agent"
+description: "完整操作指南：订阅、配置、切换模型、启用 gateway 工具并验证路由"
+---
+
+# 通过 Nous Portal 运行 Hermes Agent
+
+本指南带你从头到尾完成在 [Nous Portal](https://portal.nousresearch.com) 订阅下运行 Hermes Agent 的全过程——从注册账号到验证每个工具的路由是否正确。如果你只想了解 Portal 的概述及订阅内容，请参阅 [Nous Portal 集成页面](/integrations/nous-portal)。本页是操作步骤脚本。
+
+## 前提条件
+
+- 已安装 Hermes Agent（[快速入门](/getting-started/quickstart)）
+- 在你正在配置的机器上有可用的浏览器（或 SSH 端口转发——参见 [OAuth over SSH](/guides/oauth-over-ssh)）
+- 约 5 分钟时间
+
+你**不需要**：OpenAI 密钥、Anthropic 密钥、Firecrawl 账号、FAL 账号、Browser Use 账号，或任何其他按供应商分配的凭证。这正是 Portal 的意义所在。
+
+## 1. 获取订阅
+
+打开 [portal.nousresearch.com/manage-subscription](https://portal.nousresearch.com/manage-subscription)，注册并选择一个套餐。
+
+已订阅？跳至第 2 步。
+
+## 2. 运行一键配置
+
+```bash
+hermes setup --portal
+```
+
+这条命令会完成五件事：
+
+1. 打开浏览器跳转至 portal.nousresearch.com 进行 OAuth 登录
+2. 将 refresh token 存储至 `~/.hermes/auth.json`
+3. 在 `~/.hermes/config.yaml` 中设置 `model.provider: nous`
+4. 选择一个默认的 agentic 模型（`anthropic/claude-sonnet-4.6` 或类似模型）
+5. 为网页搜索、图像生成、TTS 和浏览器自动化开启 Tool Gateway
+
+命令执行完毕后，你将回到终端，可以直接开始对话。
+
+### 如果我通过 SSH 连接到服务器怎么办？
+
+OAuth 需要浏览器，但 loopback 回调运行在 Hermes 所在的机器上。有两种方案：
+
+```bash
+# 方案 A：SSH 端口转发（推荐）
+ssh -N -L 8642:127.0.0.1:8642 user@remote-host    # 在本地终端执行
+hermes setup --portal                              # 在远程机器上执行，在本地浏览器中打开打印出的 URL
+
+# 方案 B：设备码登录（适用于 Cloud Shell、Codespaces、EC2 Instance Connect）
+hermes auth add nous --type oauth
+# 然后重新运行 `hermes setup --portal` 以连接 provider + gateway
+```
+
+完整操作说明（包括 ProxyJump 链、mosh/tmux 和 ControlMaster 注意事项）请参阅 [OAuth over SSH / 远程主机](/guides/oauth-over-ssh)。
+
+## 3. 验证配置是否成功
+
+```bash
+hermes portal info
+```
+
+你应该看到：
+
+```
+  Nous Portal
+  ───────────
+  Auth:    ✓ logged in
+  Portal:  https://portal.nousresearch.com
+  Model:   ✓ using Nous as inference provider
+
+  Tool Gateway
+  ────────────
+  Web search & extract  via Nous Portal
+  Image generation      via Nous Portal
+  Text-to-speech        via Nous Portal
+  Browser automation    via Nous Portal
+```
+
+如果任何一行显示的不是"via Nous Portal"，或者 auth 行显示"not logged in"，请跳至下方的[故障排查](#troubleshooting)。
+
+## 4. 运行第一次对话
+
+```bash
+hermes chat
+```
+
+尝试一个同时调用模型和 Tool Gateway 的请求：
+
+```
+Hey, search the web for "Hermes Agent release notes" and summarize the top 3 hits.
+```
+
+你应该看到 Hermes 调用 `web_search`（通过 gateway 由 Firecrawl 提供支持）并返回摘要。如果搜索正常执行且响应内容合理，说明配置完成——Portal 已端到端连通。
+
+## 5. 选择你实际需要的模型
+
+`hermes setup --portal` 会在设置过程中让你选择模型，但订阅的意义在于可以访问完整的模型目录——随时可在会话中使用 `/model` 切换：
+
+```bash
+/model anthropic/claude-sonnet-4.6     # 最佳通用 agentic 模型
+/model openai/gpt-5.4                  # 强推理 + 工具调用
+/model google/gemini-2.5-pro           # 超大上下文窗口
+/model deepseek/deepseek-v3.2          # 高性价比编程模型
+/model anthropic/claude-opus-4.6       # 处理复杂问题的重量级模型
+```
+
+或者打开选择器浏览：
+
+```bash
+/model
+```
+
+永久设置不同的默认模型：
+
+```bash
+# 在终端中，在任何会话之外执行
+hermes config set model.default anthropic/claude-sonnet-4.6
+```
+
+### 不要在 agent 任务中使用 Hermes-4
+
+Hermes-4-70B 和 Hermes-4-405B 在 Portal 上以大幅折扣提供，但它们是**对话/推理模型**，并非针对工具调用优化的模型。它们在多步骤 agent 循环中表现不佳。请通过[订阅代理](/user-guide/features/subscription-proxy)从非 agent 工具中将它们用于对话或研究工作。对于 Hermes Agent 本身，请坚持使用上述前沿 agentic 模型。
+
+Portal 的[信息页面](https://portal.nousresearch.com/info)也有此说明——这是 Nous 官方指导，并非仅代表 Hermes 一方的意见。
+
+## 6. （可选）自定义 Tool Gateway 路由
+
+gateway 是按工具选择启用的，而非全部开启或全部关闭。如果你已有 Browserbase 账号并希望继续使用，同时将网页搜索和图像生成路由至 Nous，这是支持的：
+
+```bash
+hermes tools
+# → Web search       → "Nous Subscription"     （推荐）
+# → Image generation → "Nous Subscription"     （推荐）
+# → Browser          → "Browserbase"           （你自己的密钥）
+# → TTS              → "Nous Subscription"     （推荐）
+```
+
+使用以下命令验证你的混合配置：
+
+```bash
+hermes portal tools
+```
+
+你将看到每个工具的路由情况——通过订阅路由的工具显示 `via Nous Portal`，使用你自己密钥的工具显示合作方名称（`browserbase`、`firecrawl` 等）。
+
+## 7. （可选）启用语音模式
+
+由于 Tool Gateway 包含 OpenAI TTS，无需单独的 OpenAI 密钥即可使用[语音模式](/user-guide/features/voice-mode)：
+
+```bash
+hermes setup voice
+# → 为 TTS 选择 "Nous Subscription"
+# → 选择语音转文字后端（本地 faster-whisper 免费，无需配置）
+```
+
+之后在任何消息平台会话中（Telegram、Discord、Signal 等），发送语音消息，Hermes 将转录内容、生成回复并以合成语音回复——全部通过你的 Portal 订阅完成。
+
+## 8. （可选）Cron 定时任务与常驻工作流
+
+Portal 订阅对 [cron 定时任务](/user-guide/features/cron)和[批处理](/user-guide/features/batch-processing)的支持方式与交互式对话相同——OAuth refresh token 会自动复用。无需额外配置，直接安排 cron 任务，费用将计入你的订阅。
+
+```bash
+hermes cron add "Daily AI news summary" "every day at 9am" \
+  "Search the web for top AI news and summarize the 5 most important stories"
+```
+
+该 cron 任务无人值守运行，调用模型、网页搜索和摘要生成，全部通过你的 Portal 订阅完成。
+
+## Profiles 与多用户配置
+
+如果你使用 [Hermes profiles](/user-guide/profiles)（例如每个项目单独一套配置），Portal refresh token 会通过共享 token 存储自动在所有 profiles 之间共享。在任意 profile 上登录一次，其余 profiles 会自动获取。
+
+对于多人共用一台机器的团队场景，每个人有自己的 Portal 账号 → 每个 home 目录保存各自的 `~/.hermes/auth.json` → 用户之间不共享 token。这是正确的边界划分。
+
+## 故障排查
+
+### 运行 `hermes setup --portal` 后，`hermes portal info` 显示"not logged in"
+
+OAuth 流程未完成。重新运行：
+
+```bash
+hermes portal
+```
+
+如果浏览器未打开或回调失败，你可能在远程/无头主机上——参见 [OAuth over SSH](/guides/oauth-over-ssh) 了解端口转发的解决方案。
+
+### "Model: currently openrouter"（或其他 provider）而非"using Nous as inference provider"
+
+本地配置发生了偏移。OAuth 成功，但 `model.provider` 仍指向其他 provider。修复方法：
+
+```bash
+hermes config set model.provider nous
+```
+
+或以交互方式：
+
+```bash
+hermes model
+# 选择 Nous Portal
+```
+
+使用 `hermes portal info` 重新验证。
+
+### Tool Gateway 工具显示合作方名称而非"via Nous Portal"
+
+按工具的配置覆盖了 gateway 设置。运行：
+
+```bash
+hermes tools
+# 对需要通过 gateway 路由的工具选择 "Nous Subscription"
+```
+
+部分用户会有意混合使用——例如网页搜索通过 Nous 路由，但浏览器使用自己的 Browserbase 密钥。如果这是有意为之，保持不变即可。如果不是，此命令可修复。
+
+### 会话中途出现"Re-authentication required"
+
+你的 Portal refresh token 已失效（密码更改、手动撤销、会话过期）。该 token 现已在本地被隔离，以防 Hermes 无限重试。重新登录即可：
+
+```bash
+hermes auth add nous
+```
+
+成功重新登录后，隔离状态会自动解除。
+
+### 我想要的模型不在 `/model` 选择器中
+
+Portal 目录基于 OpenRouter 的模型列表（300+ 个），并补充了通过专有或备用提供商提供的模型。如果某个模型缺失，尝试直接输入 OpenRouter 风格的 slug：
+
+```bash
+/model anthropic/claude-opus-4.6
+/model openai/o1-2025-12-17
+```
+
+如果某个模型确实不可用，请[提交 issue](https://github.com/NousResearch/hermes-agent/issues)——大多数缺失是我们可以更新的路由配置问题。
+
+### 账单未出现在我的 Portal 账号中
+
+`hermes portal info` 会告诉你是否真的在通过 Portal 路由，还是使用了其他 provider。常见原因：
+
+- `model.provider` 设置为 `openrouter`/`anthropic`/等，而非 `nous`
+- OAuth refresh 失败后回退到了其他已配置的 provider
+- 存在多个 Hermes profiles，你使用的是错误的那个（检查 `hermes profile list`）
+
+### 想要撤销并重新开始
+
+```bash
+hermes auth logout nous       # 清除本地 refresh token
+# 然后重新运行 setup，或在 Portal 网页界面取消订阅
+```
+
+## 用具体数字说明 Portal 的价值
+
+| 不使用 Portal | 使用 Portal |
+|----------------|-------------|
+| 1 个 OpenRouter / Anthropic / OpenAI 密钥写入 `.env` | 1 个 OAuth refresh token，无需 `.env` 密钥 |
+| 1 个 Firecrawl 密钥用于网页搜索 | 网页搜索通过 gateway 路由 |
+| 1 个 FAL 密钥用于图像生成 | 图像生成通过 gateway 路由 |
+| 1 个 Browser Use / Browserbase 密钥用于浏览器 | 浏览器通过 gateway 路由 |
+| 1 个 OpenAI 密钥用于 TTS / 语音模式 | TTS 通过 gateway 路由 |
+| 5 个独立的控制台、充值、发票 | 1 个订阅，1 张发票 |
+| 跨机器：复制全部 5 个密钥 | 跨机器：重新 OAuth 一次 |
+
+这就是 Portal 的价值。如果你本来就在使用其中两个以上的后端，订阅费用自然就回来了。
+
+## 另请参阅
+
+- **[Nous Portal 集成页面](/integrations/nous-portal)** — 订阅内容概述
+- **[Tool Gateway](/user-guide/features/tool-gateway)** — 每个 gateway 路由工具的完整说明
+- **[订阅代理](/user-guide/features/subscription-proxy)** — 在非 Hermes 工具中使用你的 Portal 订阅
+- **[语音模式](/user-guide/features/voice-mode)** — 在 Portal 订阅上配置语音对话
+- **[OAuth over SSH](/guides/oauth-over-ssh)** — 远程/无头主机登录方案
+- **[Profiles](/user-guide/profiles)** — 在多个 Hermes 配置之间共享一个 Portal 登录