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

better-dsh 0.2.5 → 0.3.0-a

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/github-pr-review-agent.md DELETED Viewed

@@ -1,303 +0,0 @@
----
-sidebar_position: 10
-title: "教程：GitHub PR 审查 Agent"
-description: "构建一个自动化 AI 代码审查器，监控你的仓库、审查 Pull Request 并自动发送反馈——全程无需人工干预"
----
-# 教程：构建 GitHub PR 审查 Agent
-**问题所在：** 团队提交 PR 的速度比你审查的速度还快。PR 等待数天无人问津。初级开发者因为没人检查而合并了有 bug 的代码。你每天早上都在追赶 diff，而不是在写新功能。
-**解决方案：** 一个全天候监控你的仓库的 AI agent，对每个新 PR 进行 bug、安全问题和代码质量审查，并向你发送摘要——这样你只需把时间花在真正需要人工判断的 PR 上。
-**你将构建的内容：**
-```
-┌───────────────────────────────────────────────────────────────────┐
-│                                                                   │
-│   Cron Timer  ──▶  Hermes Agent  ──▶  GitHub API  ──▶  Review     │
-│   (every 2h)       + gh CLI           (PR diffs)       delivery   │
-│                    + skill                             (Telegram, │
-│                    + memory                            Discord,   │
-│                                                        local)     │
-│                                                                   │
-└───────────────────────────────────────────────────────────────────┘
-```
-本指南使用 **cron 任务**按计划轮询 PR——无需服务器或公开端点，在 NAT 和防火墙后面同样可用。
-:::tip 想要实时审查？
-如果你有可用的公开端点，请查看[使用 Webhook 自动化 GitHub PR 评论](./webhook-github-pr-review.md)——GitHub 会在 PR 被打开或更新时立即向 Hermes 推送事件。
-:::
----
-## 前提条件
-- **已安装 Hermes Agent** — 参见[安装指南](/getting-started/installation)
-- **Gateway 已运行**（用于 cron 任务）：
-  ```bash
-  hermes gateway install   # Install as a service
-  # or
-  hermes gateway           # Run in foreground
-  ```
-- **已安装并认证 GitHub CLI（`gh`）**：
-  ```bash
-  # Install
-  brew install gh        # macOS
-  sudo apt install gh    # Ubuntu/Debian
-  # Authenticate
-  gh auth login
-  ```
-- **已配置消息通知**（可选）— [Telegram](/user-guide/messaging/telegram) 或 [Discord](/user-guide/messaging/discord)
-:::tip 没有消息通知？没关系
-使用 `deliver: "local"` 将审查结果保存到 `~/.hermes/cron/output/`。在接入通知之前用于测试非常方便。
-:::
----
-## 第一步：验证配置
-确保 Hermes 可以访问 GitHub。启动对话：
-```bash
-hermes
-```
-用一个简单命令测试：
-```
-Run: gh pr list --repo NousResearch/hermes-agent --state open --limit 3
-```
-你应该能看到一个开放 PR 的列表。如果成功，就可以继续了。
----
-## 第二步：手动试审一个 PR
-仍在对话中，让 Hermes 审查一个真实的 PR：
-```
-Review this pull request. Read the diff, check for bugs, security issues,
-and code quality. Be specific about line numbers and quote problematic code.
-Run: gh pr diff 3888 --repo NousResearch/hermes-agent
-```
-Hermes 将会：
-1. 执行 `gh pr diff` 获取代码变更
-2. 通读整个 diff
-3. 生成包含具体发现的结构化审查报告
-如果你对审查质量满意，就可以开始自动化了。
----
-## 第三步：创建审查 Skill
-Skill 为 Hermes 提供一致的审查准则，在会话和 cron 运行之间持久保存。没有 skill，审查质量会参差不齐。
-```bash
-mkdir -p ~/.hermes/skills/code-review
-```
-创建 `~/.hermes/skills/code-review/SKILL.md`：
-```markdown
----
-name: code-review
-description: Review pull requests for bugs, security issues, and code quality
----
-# Code Review Guidelines
-When reviewing a pull request:
-## What to Check
-1. **Bugs** — Logic errors, off-by-one, null/undefined handling
-2. **Security** — Injection, auth bypass, secrets in code, SSRF
-3. **Performance** — N+1 queries, unbounded loops, memory leaks
-4. **Style** — Naming conventions, dead code, missing error handling
-5. **Tests** — Are changes tested? Do tests cover edge cases?
-## Output Format
-For each finding:
-- **File:Line** — exact location
-- **Severity** — Critical / Warning / Suggestion
-- **What's wrong** — one sentence
-- **Fix** — how to fix it
-## Rules
-- Be specific. Quote the problematic code.
-- Don't flag style nitpicks unless they affect readability.
-- If the PR looks good, say so. Don't invent problems.
-- End with: APPROVE / REQUEST_CHANGES / COMMENT
-```
-验证是否已加载——启动 `hermes`，你应该能在启动时的 skill 列表中看到 `code-review`。
----
-## 第四步：教会它你的团队规范
-这才是让审查器真正有用的关键。启动一个会话，向 Hermes 传授你的团队标准：
-```
-Remember: In our backend repo, we use Python with FastAPI.
-All endpoints must have type annotations and Pydantic models.
-We don't allow raw SQL — only SQLAlchemy ORM.
-Test files go in tests/ and must use pytest fixtures.
-```
-```
-Remember: In our frontend repo, we use TypeScript with React.
-No `any` types allowed. All components must have props interfaces.
-We use React Query for data fetching, never useEffect for API calls.
-```
-这些记忆会永久保存——审查器无需每次提醒就会自动执行你的规范。
----
-## 第五步：创建自动化 Cron 任务
-现在把所有内容串联起来。创建一个每 2 小时运行一次的 cron 任务：
-```bash
-hermes cron create "0 */2 * * *" \
-  "Check for new open PRs and review them.
-Repos to monitor:
-- myorg/backend-api
-- myorg/frontend-app
-Steps:
-1. Run: gh pr list --repo REPO --state open --limit 5 --json number,title,author,createdAt
-2. For each PR created or updated in the last 4 hours:
-   - Run: gh pr diff NUMBER --repo REPO
-   - Review the diff using the code-review guidelines
-3. Format output as:
-## PR Reviews — today
-### [repo] #[number]: [title]
-**Author:** [name] | **Verdict:** APPROVE/REQUEST_CHANGES/COMMENT
-[findings]
-If no new PRs found, say: No new PRs to review." \
-  --name "pr-review" \
-  --deliver telegram \
-  --skill code-review
-```
-验证任务已调度：
-```bash
-hermes cron list
-```
-### 其他常用调度计划
-| 计划 | 触发时机 |
-|------|----------|
-| `0 */2 * * *` | 每 2 小时 |
-| `0 9,13,17 * * 1-5` | 工作日每天三次 |
-| `0 9 * * 1` | 每周一早上汇总 |
-| `30m` | 每 30 分钟（高流量仓库） |
----
-## 第六步：按需手动触发
-不想等待调度？手动触发：
-```bash
-hermes cron run pr-review
-```
-或在对话会话中：
-```
-/cron run pr-review
-```
----
-## 进阶用法
-### 直接在 GitHub 上发布审查评论
-不将结果发送到 Telegram，而是让 agent 直接在 PR 上评论：
-在你的 cron prompt（提示词）中添加：
-```
-After reviewing, post your review:
-- For issues: gh pr review NUMBER --repo REPO --comment --body "YOUR_REVIEW"
-- For critical issues: gh pr review NUMBER --repo REPO --request-changes --body "YOUR_REVIEW"
-- For clean PRs: gh pr review NUMBER --repo REPO --approve --body "Looks good"
-```
-:::caution
-确保 `gh` 使用的 token 具有 `repo` 权限范围。审查评论将以 `gh` 当前认证的用户身份发布。
-:::
-### 每周 PR 看板
-创建一个每周一早上的仓库概览：
-```bash
-hermes cron create "0 9 * * 1" \
-  "Generate a weekly PR dashboard:
-- myorg/backend-api
-- myorg/frontend-app
-- myorg/infra
-For each repo show:
-1. Open PR count and oldest PR age
-2. PRs merged this week
-3. Stale PRs (older than 5 days)
-4. PRs with no reviewer assigned
-Format as a clean summary." \
-  --name "weekly-dashboard" \
-  --deliver telegram
-```
-### 多仓库监控
-在 prompt 中添加更多仓库即可扩展规模。Agent 会按顺序处理它们——无需额外配置。
----
-## 故障排查
-### "gh: command not found"
-Gateway 在精简环境中运行。请确保 `gh` 在系统 PATH 中，然后重启 gateway。
-### 审查结果过于泛泛
-1. 添加 `code-review` skill（第三步）
-2. 通过 memory（记忆）向 Hermes 传授你的团队规范（第四步）
-3. 它对你的技术栈了解越多，审查质量越好
-### Cron 任务未运行
-```bash
-hermes gateway status    # Is the gateway running?
-hermes cron list         # Is the job enabled?
-```
-### 速率限制
-GitHub 对已认证用户每小时允许 5,000 次 API 请求。每次 PR 审查约消耗 3-5 次请求（列表 + diff + 可选评论）。即使每天审查 100 个 PR，也远低于限制。
----
-## 下一步
-- **[基于 Webhook 的 PR 审查](./webhook-github-pr-review.md)** — 在 PR 被打开时立即获得审查（需要公开端点）
-- **[每日简报 Bot](/guides/daily-briefing-bot)** — 将 PR 审查与你的晨间资讯摘要结合
-- **[构建 Plugin](/developer-guide/plugins)** — 将审查逻辑封装为可共享的 plugin
-- **[Profiles](/user-guide/profiles)** — 运行一个专属审查器 profile，拥有独立的 memory 和配置
-- **[Fallback Providers](/user-guide/features/fallback-providers)** — 确保在某个 provider 不可用时审查任务仍能正常运行

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

@@ -1,254 +0,0 @@
----
-sidebar_position: 16
-title: "Google Gemini"
-description: "将 Hermes Agent 与 Google Gemini 配合使用——原生 AI Studio API、API 密钥配置、工具调用、流式传输及配额说明"
----
-# Google Gemini
-Hermes Agent 通过 **Google AI Studio / Gemini API** 原生支持 Google Gemini——而非 OpenAI 兼容端点。这使 Hermes 能够将其内部 OpenAI 格式的消息和工具循环转换为 Gemini 原生的 `generateContent` API，同时保留工具调用、流式传输、多模态输入以及 Gemini 特有的响应元数据。
-## 前提条件
-- **Google AI Studio API 密钥** — 在 [aistudio.google.com/apikey](https://aistudio.google.com/apikey) 创建
-- **已启用计费的 Google Cloud 项目** — 推荐用于 Agent 场景。Gemini 免费层级对长时间运行的 Agent 会话而言配额过小，因为 Hermes 每次用户交互可能发起多次模型调用。
-- **已安装 Hermes** — 原生 Gemini provider 无需额外安装 Python 包。
-:::tip API 密钥路径
-设置 `GOOGLE_API_KEY` 或 `GEMINI_API_KEY`。Hermes 对 `gemini` provider 会同时检查这两个名称。
-:::
-## 快速开始
-```bash
-# 添加 Gemini API 密钥
-echo "GOOGLE_API_KEY=..." >> ~/.hermes/.env
-# 选择 Gemini 作为 provider
-hermes model
-# → 选择 "More providers..." → "Google AI Studio"
-# → Hermes 检查密钥层级并显示 Gemini 模型列表
-# → 选择一个模型
-# 开始对话
-hermes chat
-```
-如果你偏好直接编辑配置文件，请使用原生 Gemini API 基础 URL：
-```yaml
-model:
-  default: gemini-3-flash-preview
-  provider: gemini
-  base_url: https://generativelanguage.googleapis.com/v1beta
-```
-## 配置
-运行 `hermes model` 后，`~/.hermes/config.yaml` 将包含：
-```yaml
-model:
-  default: gemini-3-flash-preview
-  provider: gemini
-  base_url: https://generativelanguage.googleapis.com/v1beta
-```
-`~/.hermes/.env` 中：
-```bash
-GOOGLE_API_KEY=...
-```
-### 原生 Gemini API
-推荐使用的端点为：
-```text
-https://generativelanguage.googleapis.com/v1beta
-```
-Hermes 检测到该端点后会创建原生 Gemini 适配器。在内部，Hermes 仍以 OpenAI 格式维护 Agent 循环，然后将每个请求转换为 Gemini 原生 schema：
-- `messages[]` → Gemini `contents[]`
-- 系统提示（system prompt）→ Gemini `systemInstruction`
-- 工具 schema → Gemini `functionDeclarations`
-- 工具结果 → Gemini `functionResponse` 部分
-- 流式响应 → 供 Hermes 循环使用的 OpenAI 格式流式数据块
-:::note Gemini 3 思维签名
-对于 Gemini 3 的工具调用，Hermes 会保留附加在函数调用部分的 `thoughtSignature` 值，并在下一个工具轮次中重放。这覆盖了多步骤 Agent 工作流中验证关键路径的需求。
-Gemini 3 也可能在其他响应部分附加思维签名。Hermes 的原生适配器目前针对 Agent 工具循环进行了优化，尚未以完整的部分级保真度重放所有非工具调用签名。
-:::
-### 优先使用原生端点
-Google 还提供了 OpenAI 兼容端点：
-```text
-https://generativelanguage.googleapis.com/v1beta/openai/
-```
-对于 Hermes Agent 会话，请优先使用上述原生 Gemini 端点。Hermes 内置原生 Gemini 适配器，可将多轮工具调用、工具调用结果、流式传输、多模态输入以及 Gemini 响应元数据直接映射到 Gemini 的 `generateContent` API。OpenAI 兼容端点在你明确需要 OpenAI API 兼容性时仍然有用。
-如果你之前将 `GEMINI_BASE_URL` 设置为 `/openai` URL，请将其删除或修改：
-```bash
-GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
-```
-## 可用模型
-`hermes model` 选择器显示 Hermes provider 注册表中维护的 Gemini 模型。常见选项包括：
-| 模型 | ID | 说明 |
-|------|----|------|
-| Gemini 3.1 Pro Preview | `gemini-3.1-pro-preview` | 可用时最强大的预览模型 |
-| Gemini 3 Pro Preview | `gemini-3-pro-preview` | 强大的推理和编码模型 |
-| Gemini 3 Flash Preview | `gemini-3-flash-preview` | 推荐的默认选项，速度与能力均衡 |
-| Gemini 3.1 Flash Lite Preview | `gemini-3.1-flash-lite-preview` | 可用时速度最快、成本最低的选项 |
-模型可用性会随时间变化。如果某个模型消失或未对你的密钥启用，请重新运行 `hermes model` 并从当前列表中选择。
-:::info 模型 ID
-当 `provider: gemini` 时，请使用 Gemini 原生模型 ID，如 `gemini-3-flash-preview`，而非 OpenRouter 风格的 ID（如 `google/gemini-3-flash-preview`）。
-:::
-### 最新别名
-Google 为 Pro 和 Flash Gemini 系列发布了滚动别名。当你希望 Google 自动升级模型而无需修改 Hermes 配置时，`gemini-pro-latest` 和 `gemini-flash-latest` 非常实用。
-| 别名 | 当前指向 | 说明 |
-|------|----------|------|
-| `gemini-pro-latest` | 最新 Gemini Pro 模型 | 需要 Google 当前 Pro 默认值时的最佳选择 |
-| `gemini-flash-latest` | 最新 Gemini Flash 模型 | 需要 Google 当前 Flash 默认值时的最佳选择 |
-```yaml
-model:
-  default: gemini-pro-latest
-  provider: gemini
-  base_url: https://generativelanguage.googleapis.com/v1beta
-```
-如果需要严格的可复现性，请优先使用明确的模型 ID，如 `gemini-3.1-pro-preview` 或 `gemini-3-flash-preview`。
-### 通过 Gemini API 使用 Gemma
-Google 也通过 Gemini API 提供 Gemma 模型。Hermes 将这些模型识别为 Google 模型，但会在默认模型选择器中隐藏吞吐量极低的 Gemma 条目，以防新用户在长时间运行的 Agent 会话中意外选择评估层级的模型。
-常用评估 ID 包括：
-| 模型 | ID | 说明 |
-|------|----|------|
-| Gemma 4 31B IT | `gemma-4-31b-it` | 较大的 Gemma 模型；适用于兼容性和质量评估 |
-| Gemma 4 26B A4B IT | `gemma-4-26b-a4b-it` | 可用时的较小活跃参数变体 |
-这些模型最适合作为 Gemini API 密钥的评估选项。Google 的 Gemma API 定价仅限免费层级，与生产级 Gemini 模型相比使用上限较低，因此持续的 Hermes Agent 使用通常应切换到付费 Gemini 模型、自托管部署或具有适当配额的其他 provider。
-如需使用选择器中隐藏的 Gemma 模型，请直接在配置中指定：
-```yaml
-model:
-  default: gemma-4-31b-it
-  provider: gemini
-  base_url: https://generativelanguage.googleapis.com/v1beta
-```
-## 会话中途切换模型
-在对话中使用 `/model` 命令：
-```text
-/model gemini-3-flash-preview
-/model gemini-flash-latest
-/model gemini-3-pro-preview
-/model gemini-pro-latest
-/model gemma-4-31b-it
-/model gemini-3.1-flash-lite-preview
-```
-如果尚未配置 Gemini，请退出会话并先运行 `hermes model`。`/model` 用于在已配置的 provider 和模型之间切换，不会收集新的 API 密钥。
-## 诊断
-```bash
-hermes doctor
-```
-doctor 命令检查：
-- `GOOGLE_API_KEY` 或 `GEMINI_API_KEY` 是否可用
-- 已配置的 provider 凭据是否可以解析
-## Gateway（消息平台）
-Gemini 可与所有 Hermes gateway 平台配合使用（Telegram、Discord、Slack、WhatsApp、LINE、飞书等）。将 Gemini 配置为你的 provider，然后正常启动 gateway：
-```bash
-hermes gateway setup
-hermes gateway start
-```
-gateway 读取 `config.yaml` 并使用相同的 Gemini provider 配置。
-## 故障排查
-### "Gemini native client requires an API key"
-Hermes 找不到可用的 API 密钥。请将以下任一项添加到 `~/.hermes/.env`：
-```bash
-GOOGLE_API_KEY=...
-# 或
-GEMINI_API_KEY=...
-```
-然后重新运行 `hermes model`。
-### "This Google API key is on the free tier"
-Hermes 在设置期间会探测 Gemini API 密钥。由于工具调用、重试、压缩和辅助任务可能需要多次模型调用，免费层级配额在少数几轮 Agent 交互后即可耗尽。
-请为与密钥关联的 Google Cloud 项目启用计费，必要时重新生成密钥，然后运行：
-```bash
-hermes model
-```
-### "404 model not found"
-所选模型对你的账号、地区或密钥不可用。重新运行 `hermes model` 并从当前列表中选择其他 Gemini 模型。
-### Gemma 模型未显示在 `hermes model` 中
-Hermes 默认可能会在选择器中隐藏低吞吐量的 Gemma 模型。如果你有意评估某个模型，请直接在 `~/.hermes/config.yaml` 中设置模型 ID。
-### Gemma 出现 "429 quota exceeded"
-通过 Gemini API 提供的 Gemma 模型适合评估使用，但其 Gemini API 免费层级上限较低。请将其用于兼容性测试，然后切换到付费 Gemini 模型或其他 provider 以进行持续的 Agent 会话。
-### 已配置 OpenAI 兼容端点
-检查 `~/.hermes/.env` 中是否存在：
-```bash
-GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
-```
-将其修改为原生端点或删除该覆盖项：
-```bash
-GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
-```
-### 工具调用因 schema 错误而失败
-升级 Hermes 并重新运行 `hermes model`。原生 Gemini 适配器会针对 Gemini 更严格的函数声明格式对工具 schema 进行清理；旧版本或自定义端点可能不支持此功能。
-## 相关链接
-- [AI Providers](/integrations/providers)
-- [Configuration](/user-guide/configuration)
-- [Fallback Providers](/user-guide/features/fallback-providers)
-- [AWS Bedrock](/guides/aws-bedrock) — 使用 AWS 凭据的原生云 provider 集成