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-dogfood.md

@@ -0,0 +1,181 @@
+---
+title: "Dogfood — 网页应用探索性 QA：发现缺陷、收集证据、生成报告"
+sidebar_label: "Dogfood"
+description: "网页应用探索性 QA：发现缺陷、收集证据、生成报告"
+---
+
+{/* 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. */}
+
+# Dogfood
+
+网页应用探索性 QA：发现缺陷、收集证据、生成报告。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/software-development/dogfood` |
+| 版本 | `1.0.0` |
+| 平台 | linux, macos, windows |
+| 标签 | `qa`, `testing`, `browser`, `web`, `dogfood` |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# Dogfood：系统化网页应用 QA 测试
+
+## 概述
+
+本 skill 指导你使用浏览器工具集对网页应用进行系统化探索性 QA 测试。你将浏览应用、与元素交互、收集问题证据，并生成结构化缺陷报告。
+
+## 前提条件
+
+- 浏览器工具集必须可用（`browser_navigate`、`browser_snapshot`、`browser_click`、`browser_type`、`browser_vision`、`browser_console`、`browser_scroll`、`browser_back`、`browser_press`）
+- 用户提供目标 URL 和测试范围
+
+## 输入
+
+用户提供：
+1. **目标 URL** — 测试入口点
+2. **范围** — 需要重点测试的区域/功能（或填写"全站"进行全面测试）
+3. **输出目录**（可选）— 截图和报告的保存位置（默认：`./dogfood-output`）
+
+## 工作流程
+
+遵循以下 5 阶段系统化工作流程：
+
+### 阶段 1：规划
+
+1. 创建输出目录结构：
+<!-- ascii-guard-ignore -->
+   ```
+   {output_dir}/
+   ├── screenshots/       # 证据截图
+   └── report.md          # 最终报告（在阶段 5 生成）
+   ```
+<!-- ascii-guard-ignore-end -->
+2. 根据用户输入确定测试范围。
+3. 通过规划待测页面和功能，构建粗略站点地图：
+   - 落地页/首页
+   - 导航链接（页头、页脚、侧边栏）
+   - 关键用户流程（注册、登录、搜索、结账等）
+   - 表单和交互元素
+   - 边界情况（空状态、错误页面、404 等）
+
+### 阶段 2：探索
+
+针对计划中的每个页面或功能：
+
+1. **导航**至该页面：
+   ```
+   browser_navigate(url="https://example.com/page")
+   ```
+
+2. **获取快照**以了解 DOM 结构：
+   ```
+   browser_snapshot()
+   ```
+
+3. **检查控制台**中的 JavaScript 错误：
+   ```
+   browser_console(clear=true)
+   ```
+   每次导航后及每次重要交互后都应执行此操作。静默 JS 错误是高价值发现。
+
+4. **获取带标注的截图**，以直观评估页面并识别交互元素：
+   ```
+   browser_vision(question="Describe the page layout, identify any visual issues, broken elements, or accessibility concerns", annotate=true)
+   ```
+   `annotate=true` 标志会在交互元素上叠加编号标签 `[N]`。每个 `[N]` 对应后续浏览器命令中的引用 `@eN`。
+
+5. **系统化测试交互元素**：
+   - 点击按钮和链接：`browser_click(ref="@eN")`
+   - 填写表单：`browser_type(ref="@eN", text="test input")`
+   - 测试键盘导航：`browser_press(key="Tab")`、`browser_press(key="Enter")`
+   - 滚动内容：`browser_scroll(direction="down")`
+   - 使用无效输入测试表单验证
+   - 测试空提交
+
+6. **每次交互后**，检查：
+   - 控制台错误：`browser_console()`
+   - 视觉变化：`browser_vision(question="What changed after the interaction?")`
+   - 预期行为与实际行为
+
+### 阶段 3：收集证据
+
+对于发现的每个问题：
+
+1. **截图**以记录问题：
+   ```
+   browser_vision(question="Capture and describe the issue visible on this page", annotate=false)
+   ```
+   保存响应中的 `screenshot_path` — 将在报告中引用它。
+
+2. **记录详情**：
+   - 问题发生的 URL
+   - 复现步骤
+   - 预期行为
+   - 实际行为
+   - 控制台错误（如有）
+   - 截图路径
+
+3. **按问题分类法对问题分类**（参见 `references/issue-taxonomy.md`）：
+   - 严重程度：Critical（严重）/ High（高）/ Medium（中）/ Low（低）
+   - 类别：Functional（功能）/ Visual（视觉）/ Accessibility（无障碍）/ Console（控制台）/ UX（用户体验）/ Content（内容）
+
+### 阶段 4：分类整理
+
+1. 审查所有收集到的问题。
+2. 去重 — 合并在不同位置表现为同一缺陷的问题。
+3. 为每个问题分配最终严重程度和类别。
+4. 按严重程度排序（Critical 优先，依次为 High、Medium、Low）。
+5. 按严重程度和类别统计问题数量，用于执行摘要。
+
+### 阶段 5：报告
+
+使用 `templates/dogfood-report-template.md` 中的模板生成最终报告。
+
+报告必须包含：
+1. **执行摘要**，含问题总数、按严重程度的分布情况及测试范围
+2. **每个问题的章节**，包含：
+   - 问题编号和标题
+   - 严重程度和类别标签
+   - 观察到问题的 URL
+   - 问题描述
+   - 复现步骤
+   - 预期行为与实际行为
+   - 截图引用（使用 `MEDIA:<screenshot_path>` 内联显示图片）
+   - 相关控制台错误（如有）
+3. **所有问题的汇总表**
+4. **测试说明** — 已测试内容、未测试内容及任何阻塞项
+
+将报告保存至 `{output_dir}/report.md`。
+
+## 工具参考
+
+| 工具 | 用途 |
+|------|---------|
+| `browser_navigate` | 跳转至指定 URL |
+| `browser_snapshot` | 获取 DOM 文本快照（无障碍树） |
+| `browser_click` | 通过引用（`@eN`）或文本点击元素 |
+| `browser_type` | 在输入框中输入文字 |
+| `browser_scroll` | 在页面上向上/向下滚动 |
+| `browser_back` | 在浏览器历史中后退 |
+| `browser_press` | 按下键盘按键 |
+| `browser_vision` | 截图 + AI 分析；使用 `annotate=true` 显示元素标签 |
+| `browser_console` | 获取 JS 控制台输出和错误 |
+
+## 使用技巧
+
+- **每次导航后及重要交互后，务必执行 `browser_console()`。** 静默 JS 错误是最有价值的发现之一。
+- **在需要推断交互元素位置或快照引用不清晰时，对 `browser_vision` 使用 `annotate=true`。**
+- **使用有效和无效输入分别测试** — 表单验证缺陷十分常见。
+- **滚动浏览长页面** — 折叠线以下的内容可能存在渲染问题。
+- **测试导航流程** — 端到端点击多步骤流程。
+- **通过截图中可见的布局问题检查响应式行为。**
+- **不要忽视边界情况**：空状态、超长文本、特殊字符、快速连续点击。
+- 向用户报告截图时，请包含 `MEDIA:<screenshot_path>`，以便他们能内联查看证据。

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

@@ -0,0 +1,183 @@
+---
+title: "Hermes Agent Skill 编写——在仓库中编写 SKILL"
+sidebar_label: "Hermes Agent Skill 编写"
+description: "在仓库中编写 SKILL.md"
+---
+
+{/* 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. */}
+
+# Hermes Agent Skill 编写
+
+编写仓库内 SKILL.md：frontmatter（前置元数据）、验证器、结构。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/software-development/hermes-agent-skill-authoring` |
+| 版本 | `1.0.0` |
+| 作者 | Hermes Agent |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `skills`, `authoring`, `hermes-agent`, `conventions`, `skill-md` |
+| 相关 skill | [`writing-plans`](/user-guide/skills/bundled/software-development/software-development-writing-plans), [`requesting-code-review`](/user-guide/skills/bundled/software-development/software-development-requesting-code-review) |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# 编写 Hermes-Agent Skills（仓库内）
+
+## 概述
+
+SKILL.md 可以存放在两个位置：
+
+1. **用户本地：** `~/.hermes/skills/<maybe-category>/<name>/SKILL.md` — 个人使用，不共享。通过 `skill_manage(action='create')` 创建。
+2. **仓库内（本 skill 讨论此情况）：** `/home/bb/hermes-agent/skills/<category>/<name>/SKILL.md` — 已提交，随包一起发布。使用 `write_file` + `git add`。`skill_manage(action='create')` **不**针对此目录树。
+
+## 使用时机
+
+- 用户要求你"在此分支 / 仓库 / 提交中"添加一个 skill
+- 你正在提交一个应随 hermes-agent 一起发布的可复用工作流
+- 你正在编辑 `/home/bb/hermes-agent/skills/` 下的现有 skill（小改动用 `patch`，重写用 `write_file`；`skill_manage` 对仓库内 skill 的 `patch` 仍有效，但 `create` 无效）
+
+## 必需的 Frontmatter
+
+真实来源：`tools/skill_manager_tool.py::_validate_frontmatter`。硬性要求：
+
+- 以 `---` 作为首字节开头（无前导空行）。
+- 在正文前以 `\n---\n` 结束。
+- 可解析为 YAML 映射。
+- 存在 `name` 字段。
+- 存在 `description` 字段，且 ≤ **1024 个字符**（`MAX_DESCRIPTION_LENGTH`）。
+- 关闭 `---` 后有非空正文。
+
+`skills/software-development/` 下每个 skill 使用的对等匹配格式：
+
+```yaml
+---
+name: my-skill-name               # 小写，连字符，≤64 个字符（MAX_NAME_LENGTH）
+description: Use when <trigger>. <one-line behavior>.
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+metadata:
+  hermes:
+    tags: [short, descriptive, tags]
+    related_skills: [other-skill, another-skill]
+---
+```
+
+`version` / `author` / `license` / `metadata` 不受验证器强制约束，但每个同类 skill 都有这些字段——省略会使你的 skill 显得格格不入。
+
+## 大小限制
+
+- Description：≤ 1024 个字符（强制执行）。
+- 完整 SKILL.md：≤ 100,000 个字符（强制执行为 `MAX_SKILL_CONTENT_CHARS`，约 36k token）。
+- `software-development/` 中的同类 skill 大小在 **8-14k 字符**之间。以此为目标范围。若超过 20k，请拆分为 `references/*.md` 并在 SKILL.md 中引用。
+
+## 对等匹配结构
+
+每个仓库内 skill 大致遵循以下结构：
+
+```
+# <Title>
+
+## Overview
+One or two paragraphs: what and why.
+
+## When to Use
+- Bulleted triggers
+- "Don't use for:" counter-triggers
+
+## <Topic sections specific to the skill>
+- Quick-reference tables are common
+- Code blocks with exact commands
+- Hermes-specific recipes (tests via scripts/run_tests.sh, ui-tui paths, etc.)
+
+## Common Pitfalls
+Numbered list of mistakes and their fixes.
+
+## Verification Checklist
+- [ ] Checkbox list of post-action verifications
+
+## One-Shot Recipes (optional)
+Named scenarios → concrete command sequences.
+```
+
+并非每个章节都是必需的，但 `Overview` + `When to Use` + 可操作正文 + 常见问题至少要有，skill 才能与同类看齐。
+
+## 目录放置
+
+```
+skills/<category>/<skill-name>/SKILL.md
+```
+
+仓库中现有的分类（通过 `ls skills/` 确认）：`autonomous-ai-agents`、`creative`、`data-science`、`devops`、`email`、`gaming`、`github`、`leisure`、`mcp`、`media`、`mlops/*`、`note-taking`、`productivity`、`red-teaming`、`research`、`smart-home`、`social-media`、`software-development`。
+
+选择最接近的现有分类。不要随意创建新的顶级分类。
+
+## 工作流
+
+1. **调查同类 skill**，位于目标分类下：
+   ```
+   ls skills/<category>/
+   ```
+   阅读 2-3 个同类 SKILL.md 文件，以匹配语气和结构。
+2. **如有疑问，检查 `tools/skill_manager_tool.py` 中的验证器约束。**
+3. **起草**，使用 `write_file` 写入 `skills/<category>/<name>/SKILL.md`。
+4. **本地验证**：
+   ```python
+   import yaml, re, pathlib
+   content = pathlib.Path("skills/<category>/<name>/SKILL.md").read_text()
+   assert content.startswith("---")
+   m = re.search(r'\n---\s*\n', content[3:])
+   fm = yaml.safe_load(content[3:m.start()+3])
+   assert "name" in fm and "description" in fm
+   assert len(fm["description"]) <= 1024
+   assert len(content) <= 100_000
+   ```
+5. **Git add + commit**，在当前活跃分支上。
+6. **注意：** 当前会话的 skill 加载器已缓存——`skill_view` / `skills_list` 在新会话开始前不会看到新 skill。这是预期行为，不是 bug。
+
+## 交叉引用其他 Skill
+
+`metadata.hermes.related_skills` 在加载时会合并两个目录树（仓库内 `skills/` 和 `~/.hermes/skills/`）。你**可以**从仓库内 skill 引用用户本地 skill，但对于全新克隆仓库的其他用户，该引用无法解析。仓库内 skill 优先只引用仓库内 skill。如果某个频繁被引用的 skill 仅存在于 `~/.hermes/skills/`，请考虑将其提升到仓库中。
+
+## 编辑现有仓库内 Skill
+
+- **小改动（修正错别字、添加常见问题、收紧触发条件）：** `skill_manage(action='patch', name=..., old_string=..., new_string=...)` 对仓库内 skill 同样有效。
+- **大规模重写：** 使用 `write_file` 写入完整 SKILL.md。`skill_manage(action='edit')` 也可以，但需要提供完整的新内容。
+- **添加支持文件：** 使用 `write_file` 写入 `skills/<category>/<name>/references/<file>.md`、`templates/<file>` 或 `scripts/<file>`。`skill_manage(action='write_file')` 也可以，并会强制执行 references/templates/scripts/assets 子目录白名单。
+- **始终提交**编辑——仓库内 skill 是源码，不是运行时状态。
+
+## 常见问题
+
+1. **对仓库内 skill 使用 `skill_manage(action='create')`。** 它会写入 `~/.hermes/skills/`，而非仓库目录树。仓库内创建请使用 `write_file`。
+
+2. **`---` 前有前导空白。** 验证器检查 `content.startswith("---")`；任何前导空行或 BOM 都会导致验证失败。
+
+3. **Description 过于泛泛。** 同类 skill 的 description 以"Use when ..."开头，描述的是*触发类别*，而非单一任务。"Use when debugging X" 优于 "Debug X"。
+
+4. **忘记添加 author/license/metadata 块。** 验证器不强制要求，但每个同类 skill 都有；省略会使 skill 看起来未完成。
+
+5. **编写了与同类重复的 skill。** 创建前先执行 `ls skills/<category>/` 并打开 2-3 个同类 skill。优先扩展现有 skill，而非创建功能狭窄的兄弟 skill。
+
+6. **期望当前会话能看到新 skill。** 不会。skill 加载器在会话开始时初始化。请在新会话中验证，或通过 `skill_view` 使用精确路径进行验证。
+
+7. **链接到仓库中不存在的 skill。** `related_skills: [some-user-local-skill]` 对你有效，但对其他克隆用户会失效。优先只使用仓库内链接。
+
+## 验证清单
+
+- [ ] 文件位于 `skills/<category>/<name>/SKILL.md`（不在 `~/.hermes/skills/` 中）
+- [ ] Frontmatter 从字节 0 以 `---` 开头，以 `\n---\n` 结束
+- [ ] `name`、`description`、`version`、`author`、`license`、`metadata.hermes.{tags, related_skills}` 均已填写
+- [ ] Name ≤ 64 个字符，小写加连字符
+- [ ] Description ≤ 1024 个字符，且以"Use when ..."开头
+- [ ] 文件总大小 ≤ 100,000 个字符（目标 8-15k）
+- [ ] 结构：`# Title` → `## Overview` → `## When to Use` → 正文 → `## Common Pitfalls` → `## Verification Checklist`
+- [ ] `related_skills` 中的引用在仓库内可解析（或明确允许为用户本地）
+- [ ] 已在目标分支上完成 `git add skills/<category>/<name>/ && git commit`