better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/guides/github-pr-review-agent.md

@@ -0,0 +1,303 @@
+---
+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

@@ -0,0 +1,254 @@
+---
+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 集成