test-flow

name	test-flow
description	Hit 项目实测流程专用 skill。按 TEST_FLOW.md 执行完整命令测试，生成 REPORT.md 测试报告，并更新 BUGS.md 记录新发现的问题。
license	MIT
compatibility	Hit 项目
metadata	{"version":"1.0.0"}
allowed-tools	Shell Read Write Edit Glob Grep
user_invocable	true
disable_model_invocation	false

test-flow — Hit 项目实测流程

按 docs/bugs/TEST_FLOW.md 定义的完整流程执行命令测试，生成测试报告并更新 bug 记录。

核心原则

严格遵守：只测试，不修改代码。

• 仅执行测试命令并记录结果
• 将发现的问题写入 docs/bugs/BUGS.md
• 将完整测试输出写入 docs/bugs/REPORT.md
• 禁止对源代码进行任何修改
• 禁止修复发现的 bug（除非用户明确要求）

---

核心参考文档

文档	路径	用途
TEST_FLOW.md	docs/bugs/TEST_FLOW.md	测试用例清单和预期结果
REPORT.md	docs/bugs/REPORT.md	测试报告输出文件
BUGS.md	docs/bugs/BUGS.md	Bug 记录（新增问题写入）
SOLVED_BUGS.md	docs/bugs/SOLVED_BUGS.md	已解决的 Bug

---

工作流程

Step 1：确认测试环境

检查 hit 是否已安装且可用：

hit --version       # 应输出版本号
hit prefix          # 应输出安装根目录

如果未安装，按 TEST_FLOW.md §0.1-§0.2 进行构建和安装。

Step 2：读取测试流程文档

读取 docs/bugs/TEST_FLOW.md，确认：

• 当前需要执行的测试章节
• 各命令的预期结果
• 需要跳过的测试项（交互式或破坏性）

Step 3：执行测试用例

按 TEST_FLOW.md 的顺序逐一执行测试命令。注意：

• 原样输出：保留命令输出的原始格式，不美化、不修改
• 错误结果：即使命令失败，也要将错误信息写入报告
• 跳过项：交互式测试（§1、§15）、破坏性测试（§14.2、§14.4、§19.4、§20）、需要浏览器的测试（§12.3.1）应跳过，并在报告开头注明

执行命令的通用格式：

# 正常命令
hit <command>

# 预期失败的命令（记录错误）
hit <command> 2>&1

Step 4：生成测试报告

将所有测试结果写入 docs/bugs/REPORT.md，格式如下：

# Hit 实测报告（自动批量执行）
> 生成时间: <日期>
> 按 TEST_FLOW.md 顺序，stdout 入本文件，stderr(WARN) 入 REPORT_warn.log。
> 跳过: §1/§15/§12.3.1/§20/§14.2/§14.4/§19.4


────────────────────────────────────────────────
## §<章节号>
────────────────────────────────────────────────
命令: hit <command>
输出（原样）:
<命令输出内容>

Step 5：更新 Bug 记录

对比测试结果与预期结果，将新发现的 bug 追加到 docs/bugs/BUGS.md。注意：

• 不删除旧内容：只插入新 bug，保留已有记录
• 严重程度标记：用 ⭐ 表示严重程度（1-5 个）
• 证据引用：标注对应的测试章节（如"第十轮实测 §5.4"）
• 不重复记录：检查 BUGS.md 中是否已存在相同问题

新 bug 插入位置：在"已修复"部分之前。

Step 6：总结测试结果

输出测试总结，包括：

• 测试覆盖情况（完成/跳过的章节）
• 主要测试结果（表格形式）
• 需要注意的问题（新发现的 bug）

---

跳过的测试项

章节	原因
§1	首次启动引导（交互式菜单）
§15	交互式搜索安装（TUI 需要真实终端）
§12.3.1	打开浏览器访问主页
§14.2	需要手动删除 junction（破坏性）
§14.4	需要手动创建损坏的 shim 文件（破坏性）
§19.4	需要无网络环境
§20	完全卸载验证（破坏性，会清除测试环境）

---

测试项速查

模块	测试项数	对应章节
首次引导	4	§1
Bucket 管理	11	§2
搜索	5	§3
详情	4	§4
安装	7	§5
列表	4	§6
版本管理	10	§7
更新	5	§8
卸载	5	§9
缓存	5	§10
清理	4	§11
路径查询	5	§12
配置	10	§13
健康检查	4	§14
交互搜索	6	§15
系统状态	2	§16
命令简写	9	§17
日志级别	3	§18
错误处理	5	§19
完全卸载	5	§20
合计	108

---

Bug 记录格式

新增 bug 时按以下格式插入：

## <Bug 标题> ⭐⭐⭐⭐⭐

### 现象

<详细描述问题现象，包含命令和错误输出>

### 证据

<测试轮次>实测 §<章节号>

---

注意事项

1. PowerShell 版本：本项目使用 PowerShell 7（pwsh），不要用 powershell（5 版本）。TEST_FLOW.md 标注 PS5+ 兼容，但按项目约定统一使用 pwsh
2. 权限：所有命令在普通用户权限下运行，无需管理员
3. 环境变量：确保 hit 命令在 PATH 中，可用 hit --version 验证
4. 网络：测试需要网络连接（bucket 克隆、软件下载）
5. 报告覆盖：每次测试覆盖写入 REPORT.md，保留历史结果需手动备份
6. 中文错误消息：hit 命令输出的错误消息使用中文，记录时保持原样