Test Harness CLI

把需求文档变成测试资产（测试点思维导图 → 测试用例）的 AI 流水线 CLI。

借鉴 OpenSpec 的架构：schema 驱动产物依赖图 + 指令驱动生成 + 目录即数据库。核心思路是——

测试点思维导图和测试用例的书写风格因公司而异，因此先生成风格档案，再按风格生成测试点、测试用例。每一步都有独立指令，产物落盘即状态，支持单步重跑与人工确认门。

特性

• 风格优先：/hx:discover-style 从样例/对话中提取公司测试风格（导图层级、用例字段、编号规则、优先级枚举、粒度），沉淀为 knowledge/styles/<name>.yaml，作为所有生成阶段的规则源
• 混合输入：需求文档支持 docx / markdown / xlsx 混用
• 分阶段指令：analyze-reqs → test-points → test-cases 各自独立，可单步重跑；/hx:propose 一键走完
• 人工确认门：测试点思维导图必须经人工确认后才能生成用例（harness confirm）
• 多 agent 适配：init 时选择 AI 工具，按该工具的约定放置命令与 skill
• 目录即数据库：runs/<batch-id>/ 落盘即状态，无需额外数据库
• 多格式产物：思维导图输出 json + Freemind(.mm) + Markdown，用例输出 json + xlsx

安装

需要 Node.js ≥ 18。

npm install -g test-harness-cli

快速开始

在项目目录中运行：

harness init

交互式选择项目使用的 AI 工具（CodeBuddy / Claude Code / Cursor / OpenAI Codex / GitHub Copilot / Gemini CLI / Windsurf）。CLI 会自动：

1. 在对应 agent 配置目录中生成 6 个 slash 命令文件（如 .codebuddy/commands/hx/*.md → /hx:test-points）
2. 安装 harness skill（如 .codebuddy/skills/harness/SKILL.md）
3. 初始化工作目录：runs/、knowledge/styles/、archive/

非交互式：

harness init --agent codebuddy

完成后在 agent 中重载会话，即可开始：

/hx:discover-style acme-banking --from 测试点样例.docx 用例样例.xlsx   # 1. 先探索风格
/hx:propose --docs 需求v2.docx 需求补充.md --style acme-banking         # 2. 一键走完全流程

/hx:propose 会在测试点生成后自动暂停等待人工确认。之后也可以分步执行、随时单步重跑：

/hx:analyze-reqs <batch-id> --docs 需求文档.md
/hx:test-points <batch-id> --style acme-banking
/hx:test-cases  <batch-id> --style acme-banking
/hx:archive     <batch-id>

Agent 支持

| Agent | 配置目录 | 命令调用 | |---|---|---| | CodeBuddy | .codebuddy/commands/hx/*.md | /hx:test-points | | Claude Code | .claude/commands/hx-*.md | /hx-test-points | | Cursor | .cursor/commands/hx-*.md | /hx-test-points | | OpenAI Codex | .codex/commands/hx-*.md | /hx-test-points | | GitHub Copilot | .github/commands/hx-*.md | /hx-test-points | | Gemini CLI | .gemini/commands/hx-*.md | $hx-test-points | | Windsurf | .windsurf/commands/hx-*.md | /hx-test-points |

流水线

knowledge/styles/<name>.yaml   # 风格档案（Phase 0，可复用）
        │
        ▼
requirements.json              # Phase 1: 需求结构化 + 缺口/歧义分析
        │  （需人工确认）
        ▼
test_points.{json,mm,md}       # Phase 2: 测试点思维导图（按风格）
        │  （强制人工确认门）
        ▼
test_cases.{json,xlsx}         # Phase 3: 测试用例（按风格字段/编号/优先级）

状态检查：

harness status                     # 列出所有批次
harness status --batch <id> --json # 某批次的产物依赖状态（JSON，供 AI 读取）

| 产物 | 文件 | 依赖 | 需确认 | |---|---|---|---| | requirements | requirements.json | — | ✅ | | test_points | test_points.json / .mm / .md | requirements | ✅（强制） | | test_cases | test_cases.json / .xlsx | test_points | 软确认 |

CLI 命令

harness init [--agent <id>] [--force]    安装命令与 skill（交互选择 agent）
harness update [--agent <id>]            重新生成已安装的模板
harness status [--batch <id>] [--json]   查看批次/全部状态
harness init-batch <batch-id>            创建空批次
harness confirm --batch <id> --artifact <name>
                                          将产物标记为人工已确认
harness archive <batch-id> [--force]     归档批次到 archive/YYYY-MM-DD-<batch>
harness style-list                       列出风格档案
harness style-show <name>                打印风格档案
harness version / help

目录结构

runs/<batch-id>/         批次产物（目录即数据库）
  requirements.json
  test_points.json|.mm|.md
  test_cases.json|.xlsx
  .harness/<artifact>.confirmed   人工确认标记
knowledge/styles/        风格档案（<name>.yaml）
archive/                 已归档批次
.harness-agent.json      记录 init 选择的 agent（供 update 用）

开发

git clone <repo-url>
cd test-harness-cli
npm link                 # 本地全局安装（或 npm install -g .）
harness init --agent codebuddy   # 在任意项目里测试

发布

npm login
npm publish              # 发布到 npm（需先将 package.json 的 name/author/repository 改好）

目录说明

src/                     npm CLI 源码（零依赖）
  cli.js                 命令路由
  init.js                harness init / update
  agents.js              agent 适配表
  state.js               批次状态（目录即数据库）
  status.js              status/confirm/archive/style 命令
  templates/             slash 命令与 skill 模板（纯 markdown）
bin/harness.js           npm bin 入口
harness/                 早期本地 Python 骨架（可选参考实现，非主推）

后续规划

• /hx:automate：基于测试用例生成 pytest 自动化代码（产物链已预留扩展位）
• 更多产物格式（xmind、TestRail 导入模板等）

License

MIT