better-dsh 0.2.5 → 0.3.0-a

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

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

@@ -1,191 +0,0 @@
----
-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` 运行配置脚本 |