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

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

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