npm - better-dsh - Versions diffs - 0.2.5 → 0.3.0 - Mend

better-dsh 0.2.5 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (999) hide show

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

@@ -1,333 +0,0 @@
----
-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 DELETED Viewed

@@ -1,273 +0,0 @@
----
-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 登录