better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/bundled/software-development/software-development-test-driven-development.md

@@ -0,0 +1,361 @@
+---
+title: "测试驱动开发 — TDD：强制执行 RED-GREEN-REFACTOR，测试先于代码"
+sidebar_label: "测试驱动开发"
+description: "TDD：强制执行 RED-GREEN-REFACTOR，测试先于代码"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# 测试驱动开发
+
+TDD：强制执行 RED-GREEN-REFACTOR，测试先于代码。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/software-development/test-driven-development` |
+| 版本 | `1.1.0` |
+| 作者 | Hermes Agent（改编自 obra/superpowers） |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `testing`, `tdd`, `development`, `quality`, `red-green-refactor` |
+| 相关 skill | [`systematic-debugging`](/user-guide/skills/bundled/software-development/software-development-systematic-debugging)、[`writing-plans`](/user-guide/skills/bundled/software-development/software-development-writing-plans)、[`subagent-driven-development`](/user-guide/skills/bundled/software-development/software-development-subagent-driven-development) |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发该 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# 测试驱动开发（TDD）
+
+## 概述
+
+先写测试。看它失败。再写最少的代码使其通过。
+
+**核心原则：** 如果你没有亲眼看到测试失败，你就不知道它是否测试了正确的东西。
+
+**违反规则的字面意义，就是违反规则的精神。**
+
+## 何时使用
+
+**始终使用：**
+- 新功能
+- Bug 修复
+- 重构
+- 行为变更
+
+**例外情况（须先询问用户）：**
+- 一次性原型
+- 生成的代码
+- 配置文件
+
+觉得"这次跳过 TDD 就好"？停下来。那是在自我合理化。
+
+## 铁律
+
+```
+没有先写失败的测试，就不能写生产代码
+```
+
+在写测试之前就写了代码？删掉它。重新开始。
+
+**没有例外：**
+- 不要以"参考"为由保留它
+- 不要在写测试时"改编"它
+- 不要看它
+- 删除就是删除
+
+从测试出发重新实现。就这样。
+
+## Red-Green-Refactor 循环
+
+### RED — 编写失败的测试
+
+编写一个最简测试，说明应该发生什么。
+
+**好的测试：**
+```python
+def test_retries_failed_operations_3_times():
+    attempts = 0
+    def operation():
+        nonlocal attempts
+        attempts += 1
+        if attempts < 3:
+            raise Exception('fail')
+        return 'success'
+
+    result = retry_operation(operation)
+
+    assert result == 'success'
+    assert attempts == 3
+```
+名称清晰，测试真实行为，只测一件事。
+
+**坏的测试：**
+```python
+def test_retry_works():
+    mock = MagicMock()
+    mock.side_effect = [Exception(), Exception(), 'success']
+    result = retry_operation(mock)
+    assert result == 'success'  # 重试次数呢？时序呢？
+```
+名称模糊，测试的是 mock 而非真实代码。
+
+**要求：**
+- 每个测试只测一个行为
+- 名称清晰具描述性（名称中有"and"？拆分它）
+- 使用真实代码，而非 mock（除非确实不可避免）
+- 名称描述行为，而非实现
+
+### 验证 RED — 亲眼看到它失败
+
+**强制要求。绝不跳过。**
+
+```bash
+# 使用 terminal 工具运行特定测试
+pytest tests/test_feature.py::test_specific_behavior -v
+```
+
+确认：
+- 测试失败（不是因为拼写错误导致的报错）
+- 失败信息符合预期
+- 因功能缺失而失败
+
+**测试立即通过？** 你在测试已有的行为。修正测试。
+
+**测试报错？** 修复错误，重新运行，直到它正确地失败。
+
+### GREEN — 最少代码
+
+编写最简单的代码使测试通过。不多不少。
+
+**好的：**
+```python
+def add(a, b):
+    return a + b  # 没有多余的东西
+```
+
+**坏的：**
+```python
+def add(a, b):
+    result = a + b
+    logging.info(f"Adding {a} + {b} = {result}")  # 多余！
+    return result
+```
+
+不要添加功能、重构其他代码，或在测试范围之外"改进"。
+
+**GREEN 阶段允许作弊：**
+- 硬编码返回值
+- 复制粘贴
+- 重复代码
+- 跳过边界情况
+
+我们会在 REFACTOR 阶段修复它。
+
+### 验证 GREEN — 亲眼看到它通过
+
+**强制要求。**
+
+```bash
+# 运行特定测试
+pytest tests/test_feature.py::test_specific_behavior -v
+
+# 然后运行所有测试，检查是否有回归
+pytest tests/ -q
+```
+
+确认：
+- 测试通过
+- 其他测试仍然通过
+- 输出干净（无错误、无警告）
+
+**测试失败？** 修复代码，而非测试。
+
+**其他测试失败？** 立即修复回归问题。
+
+### REFACTOR — 清理
+
+仅在绿色之后：
+- 消除重复
+- 改善命名
+- 提取辅助函数
+- 简化表达式
+
+全程保持测试绿色。不要添加行为。
+
+**重构期间测试失败？** 立即撤销。步子迈小一点。
+
+### 重复
+
+为下一个行为编写下一个失败的测试。一次一个循环。
+
+## 为什么顺序很重要
+
+**"我会在之后写测试来验证它是否有效"**
+
+在代码之后写的测试会立即通过。立即通过什么都证明不了：
+- 可能测试了错误的东西
+- 可能测试的是实现而非行为
+- 可能遗漏了你忘记的边界情况
+- 你从未看到它捕获 bug
+
+测试先行迫使你看到测试失败，证明它确实在测试某些东西。
+
+**"我已经手动测试了所有边界情况"**
+
+手动测试是临时性的。你以为自己测试了所有情况，但：
+- 没有记录你测试了什么
+- 代码变更时无法重新运行
+- 在压力下容易遗漏情况
+- "我试过时它能用" ≠ 全面覆盖
+
+自动化测试是系统性的。每次以相同方式运行。
+
+**"删除 X 小时的工作是浪费"**
+
+这是沉没成本谬误。时间已经过去了。你现在的选择是：
+- 删除并用 TDD 重写（高置信度）
+- 保留并事后添加测试（低置信度，可能有 bug）
+
+"浪费"是保留你无法信任的代码。
+
+**"TDD 是教条主义，务实意味着适应"**
+
+TDD 本身就是务实的：
+- 在提交前发现 bug（比事后调试更快）
+- 防止回归（测试立即捕获破坏）
+- 记录行为（测试展示如何使用代码）
+- 支持重构（自由修改，测试捕获破坏）
+
+"务实"的捷径 = 在生产环境调试 = 更慢。
+
+**"事后写测试能达到相同目标——重要的是精神而非仪式"**
+
+不对。事后写的测试回答"这做了什么？"测试先行回答"这应该做什么？"
+
+事后写的测试受你的实现偏见影响。你测试的是你构建的东西，而非需求。测试先行迫使你在实现之前发现边界情况。
+
+## 常见自我合理化
+
+| 借口 | 现实 |
+|--------|---------|
+| "太简单了，不需要测试" | 简单的代码也会出错。写测试只需 30 秒。 |
+| "我之后再测试" | 立即通过的测试什么都证明不了。 |
+| "事后写测试能达到相同目标" | 事后测试 = "这做了什么？"测试先行 = "这应该做什么？" |
+| "已经手动测试过了" | 临时性 ≠ 系统性。没有记录，无法重新运行。 |
+| "删除 X 小时的工作是浪费" | 沉没成本谬误。保留未经验证的代码就是技术债务。 |
+| "保留作参考，先写测试" | 你会改编它。那就是事后测试。删除就是删除。 |
+| "需要先探索" | 没问题。丢掉探索代码，从 TDD 开始。 |
+| "测试难写 = 设计不清晰" | 听测试的话。难以测试 = 难以使用。 |
+| "TDD 会让我变慢" | TDD 比调试更快。务实 = 测试先行。 |
+| "手动测试更快" | 手动测试无法证明边界情况。每次变更都要重新测试。 |
+| "现有代码没有测试" | 你在改进它。为你接触的代码添加测试。 |
+
+## 红色警报 — 停下来，重新开始
+
+如果你发现自己在做以下任何一件事，删除代码并用 TDD 重新开始：
+
+- 测试之前写了代码
+- 实现之后写测试
+- 测试在第一次运行时立即通过
+- 无法解释测试为何失败
+- 测试"稍后"添加
+- 合理化"就这一次"
+- "我已经手动测试过了"
+- "事后写测试能达到相同目的"
+- "保留作参考"或"改编现有代码"
+- "已经花了 X 小时，删除是浪费"
+- "TDD 是教条主义，我在务实"
+- "这种情况不同，因为……"
+
+**所有这些都意味着：删除代码。用 TDD 重新开始。**
+
+## 验证清单
+
+在标记工作完成之前：
+
+- [ ] 每个新函数/方法都有测试
+- [ ] 在实现之前亲眼看到每个测试失败
+- [ ] 每个测试因预期原因失败（功能缺失，而非拼写错误）
+- [ ] 编写了最少的代码使每个测试通过
+- [ ] 所有测试通过
+- [ ] 输出干净（无错误、无警告）
+- [ ] 测试使用真实代码（仅在不可避免时使用 mock）
+- [ ] 边界情况和错误情况已覆盖
+
+无法勾选所有项？你跳过了 TDD。重新开始。
+
+## 遇到困难时
+
+| 问题 | 解决方案 |
+|---------|----------|
+| 不知道如何测试 | 写出期望的 API。先写断言。询问用户。 |
+| 测试太复杂 | 设计太复杂。简化接口。 |
+| 必须 mock 所有东西 | 代码耦合度太高。使用依赖注入。 |
+| 测试 setup 很庞大 | 提取辅助函数。仍然复杂？简化设计。 |
+
+## Hermes Agent 集成
+
+### 运行测试
+
+使用 `terminal` 工具在每个步骤运行测试：
+
+```python
+# RED — 验证失败
+terminal("pytest tests/test_feature.py::test_name -v")
+
+# GREEN — 验证通过
+terminal("pytest tests/test_feature.py::test_name -v")
+
+# 完整套件 — 验证无回归
+terminal("pytest tests/ -q")
+```
+
+### 与 delegate_task 配合使用
+
+向子 agent 分派实现任务时，在目标中强制执行 TDD：
+
+```python
+delegate_task(
+    goal="Implement [feature] using strict TDD",
+    context="""
+    Follow test-driven-development skill:
+    1. Write failing test FIRST
+    2. Run test to verify it fails
+    3. Write minimal code to pass
+    4. Run test to verify it passes
+    5. Refactor if needed
+    6. Commit
+
+    Project test command: pytest tests/ -q
+    Project structure: [describe relevant files]
+    """,
+    toolsets=['terminal', 'file']
+)
+```
+
+### 与 systematic-debugging 配合使用
+
+发现 bug？编写能复现它的失败测试。遵循 TDD 循环。测试证明了修复的有效性并防止回归。
+
+绝不在没有测试的情况下修复 bug。
+
+## 测试反模式
+
+- **测试 mock 行为而非真实行为** — mock 应用于验证交互，而非替代被测系统
+- **测试实现细节** — 测试行为/结果，而非内部方法调用
+- **只测试正常路径** — 始终测试边界情况、错误情况和边界值
+- **脆弱的测试** — 测试应验证行为而非结构；重构不应导致测试失败
+
+## 最终规则
+
+```
+生产代码 → 测试先存在且先失败
+否则 → 不是 TDD
+```
+
+未经用户明确许可，没有例外。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/google-workspace.md

@@ -0,0 +1,191 @@
+---
+sidebar_position: 2
+sidebar_label: "Google Workspace"
+title: "Google Workspace — Gmail、Calendar、Drive、Sheets 与 Docs"
+description: "通过 OAuth2 认证的 Google API，发送邮件、管理日历事件、搜索 Drive、读写 Sheets 并访问 Docs"
+---
+
+# Google Workspace Skill
+
+Gmail、Calendar、Drive、Contacts、Sheets 和 Docs 与 Hermes 的集成。使用 OAuth2 并支持自动刷新 token（令牌）。优先使用 [Google Workspace CLI（`gws`）](https://github.com/nicholasgasior/gws)（如已安装）以获得更广泛的覆盖，否则回退到 Google 的 Python 客户端库。
+
+**Skill 路径：** `skills/productivity/google-workspace/`
+
+## 配置
+
+配置流程完全由 Agent 驱动——让 Hermes 设置 Google Workspace，它会引导你完成每个步骤。流程如下：
+
+1. **创建 Google Cloud 项目**并启用所需 API（Gmail、Calendar、Drive、Sheets、Docs、People）
+2. **创建 OAuth 2.0 凭据**（Desktop app 类型）并下载客户端密钥 JSON
+3. **授权**——Hermes 生成授权 URL，你在浏览器中批准，然后将重定向 URL 粘贴回来
+4. **完成**——token 从此自动刷新
+
+:::tip 仅需邮件的用户
+如果你只需要邮件功能（无需 Calendar/Drive/Sheets），请改用 **himalaya** skill——它使用 Gmail 应用专用密码，只需 2 分钟即可完成配置，无需 Google Cloud 项目。
+:::
+
+## Gmail
+
+### 搜索
+
+```bash
+$GAPI gmail search "is:unread" --max 10
+$GAPI gmail search "from:boss@company.com newer_than:1d"
+$GAPI gmail search "has:attachment filename:pdf newer_than:7d"
+```
+
+返回 JSON，每条消息包含 `id`、`from`、`subject`、`date`、`snippet` 和 `labels` 字段。
+
+### 读取
+
+```bash
+$GAPI gmail get MESSAGE_ID
+```
+
+以文本形式返回完整消息正文（优先纯文本，回退到 HTML）。
+
+### 发送
+
+```bash
+# 基本发送
+$GAPI gmail send --to user@example.com --subject "Hello" --body "Message text"
+
+# HTML 邮件
+$GAPI gmail send --to user@example.com --subject "Report" \
+  --body "<h1>Q4 Results</h1><p>Details here</p>" --html
+
+# 自定义 From 头（显示名称 + 邮箱）
+$GAPI gmail send --to user@example.com --subject "Hello" \
+  --from '"Research Agent" <user@example.com>' --body "Message text"
+
+# 带 CC
+$GAPI gmail send --to user@example.com --cc "team@example.com" \
+  --subject "Update" --body "FYI"
+```
+
+### 自定义 From 头
+
+`--from` 标志允许你自定义外发邮件的发件人显示名称。当多个 Agent 共享同一个 Gmail 账户但希望收件人看到不同名称时，此功能非常有用：
+
+```bash
+# Agent 1
+$GAPI gmail send --to client@co.com --subject "Research Summary" \
+  --from '"Research Agent" <shared@company.com>' --body "..."
+
+# Agent 2  
+$GAPI gmail send --to client@co.com --subject "Code Review" \
+  --from '"Code Assistant" <shared@company.com>' --body "..."
+```
+
+**工作原理：** `--from` 的值会被设置为 MIME 消息的 RFC 5322 `From` 头。Gmail 允许在已认证的邮箱地址上自定义显示名称，无需任何额外配置。收件人看到的是自定义显示名称（如"Research Agent"），而邮箱地址保持不变。
+
+**重要提示：** 如果你在 `--from` 中使用*不同的邮箱地址*（非已认证账户），Gmail 要求该地址在 Gmail 设置 → 账户 → 以其他地址发送邮件中配置为 [Send As 别名](https://support.google.com/mail/answer/22370)。
+
+`--from` 标志同时适用于 `send` 和 `reply`：
+
+```bash
+$GAPI gmail reply MESSAGE_ID \
+  --from '"Support Bot" <shared@company.com>' --body "We're on it"
+```
+
+### 回复
+
+```bash
+$GAPI gmail reply MESSAGE_ID --body "Thanks, that works for me."
+```
+
+自动将回复归入同一会话（设置 `In-Reply-To` 和 `References` 头），并使用原始消息的 thread ID。
+
+### 标签
+
+```bash
+# 列出所有标签
+$GAPI gmail labels
+
+# 添加/移除标签
+$GAPI gmail modify MESSAGE_ID --add-labels LABEL_ID
+$GAPI gmail modify MESSAGE_ID --remove-labels UNREAD
+```
+
+## Calendar
+
+```bash
+# 列出事件（默认为未来 7 天）
+$GAPI calendar list
+$GAPI calendar list --start 2026-03-01T00:00:00Z --end 2026-03-07T23:59:59Z
+
+# 创建事件（必须指定时区）
+$GAPI calendar create --summary "Team Standup" \
+  --start 2026-03-01T10:00:00-07:00 --end 2026-03-01T10:30:00-07:00
+
+# 带地点和参与者
+$GAPI calendar create --summary "Lunch" \
+  --start 2026-03-01T12:00:00Z --end 2026-03-01T13:00:00Z \
+  --location "Cafe" --attendees "alice@co.com,bob@co.com"
+
+# 删除事件
+$GAPI calendar delete EVENT_ID
+```
+
+:::warning
+Calendar 时间**必须**包含时区偏移（如 `-07:00`）或使用 UTC（`Z`）。不带时区的裸日期时间（如 `2026-03-01T10:00:00`）存在歧义，将被视为 UTC 处理。
+:::
+
+## Drive
+
+```bash
+$GAPI drive search "quarterly report" --max 10
+$GAPI drive search "mimeType='application/pdf'" --raw-query --max 5
+```
+
+## Sheets
+
+```bash
+# 读取范围
+$GAPI sheets get SHEET_ID "Sheet1!A1:D10"
+
+# 写入范围
+$GAPI sheets update SHEET_ID "Sheet1!A1:B2" --values '[["Name","Score"],["Alice","95"]]'
+
+# 追加行
+$GAPI sheets append SHEET_ID "Sheet1!A:C" --values '[["new","row","data"]]'
+```
+
+## Docs
+
+```bash
+$GAPI docs get DOC_ID
+```
+
+返回文档标题和完整文本内容。
+
+## Contacts
+
+```bash
+$GAPI contacts list --max 20
+```
+
+## 输出格式
+
+所有命令均返回 JSON。各服务的关键字段：
+
+| 命令 | 字段 |
+|---------|--------|
+| `gmail search` | `id`、`threadId`、`from`、`to`、`subject`、`date`、`snippet`、`labels` |
+| `gmail get` | `id`、`threadId`、`from`、`to`、`subject`、`date`、`labels`、`body` |
+| `gmail send/reply` | `status`、`id`、`threadId` |
+| `calendar list` | `id`、`summary`、`start`、`end`、`location`、`description`、`htmlLink` |
+| `calendar create` | `status`、`id`、`summary`、`htmlLink` |
+| `drive search` | `id`、`name`、`mimeType`、`modifiedTime`、`webViewLink` |
+| `contacts list` | `name`、`emails`、`phones` |
+| `sheets get` | 单元格值的二维数组 |
+
+## 故障排查
+
+| 问题 | 解决方法 |
+|---------|-----|
+| `NOT_AUTHENTICATED` | 运行配置（让 Hermes 设置 Google Workspace） |
+| `REFRESH_FAILED` | Token 已被撤销——重新执行授权步骤 |
+| `HttpError 403: Insufficient Permission` | 缺少 scope（权限范围）——撤销并以正确的服务重新授权 |
+| `HttpError 403: Access Not Configured` | API 未在 Google Cloud Console 中启用 |
+| `ModuleNotFoundError` | 使用 `--install-deps` 运行配置脚本 |