用 /hx 把一条需求跑到 MR
hx 是一个 Agent Skill，把「获取需求 → 生成计划 → 执行任务 → 质量检查 → 提 MR」串成一条可检查的流水线。 命令契约、事实脚本和规则模板分层设计，Agent 只负责语义判断。
01为什么需要 hx
大多数 AI Coding 流程栽在「上下文漂移」与「步骤不可验证」。hx 通过三层分工把语义与事实解耦。
命令契约
每个 hx-* 命令只写目标、边界和输出要求；短、可执行、可审阅。
事实脚本
scripts/tools/*.ts 给 Agent 提供结构化事实，替代靠模型猜测路径、状态、schema。
模板与质量门
规则模板、progress.json、质量门全部落到 .hx/，运行时只认配置。
02快速开始
三步把 hx 接到你的项目。所有命令都在 Agent（Claude Code / 兼容 Skills 的运行时）里以 /hx 前缀调用。
安装 Skill
通过 npx skills 一行安装，无需手动克隆。
npx skills add hxflow/workflow
初始化项目
在目标仓库中运行 /hx init。单项目生成 config.yaml，多服务仓库生成 workspace.yaml。已存在配置时不会覆盖。
/hx init # → 单项目：生成 .hx/config.yaml # → 多项目：生成 .hx/workspace.yaml # → 落地 rules/ 模板（需求、计划、bugfix）
驱动一条需求
用 /hx go <feature> 一把跑完全流程；或按阶段手动驱动，在关键 checkpoint 上停下来评审。
# 全自动 /hx go login-sso # 分阶段 /hx doc login-sso /hx plan login-sso /hx run login-sso /hx check login-sso /hx mr login-sso
Bun ≥ 1.0.0；未安装 Bun 时可使用 Node.js 并通过 npx tsx 执行 hxflow/scripts/**/*.ts。
03流水线一览
/hx go 会按下列节点推进，遇到 check 自动开子 agent 做评审，未通过则不进入下一步。
约束
• 不跳过最早未完成 step
• 只按脚本返回的下一步推进
• --from <step> 只用于从指定步重启
产物
• docs/requirement/{feature}.md
• docs/plans/{feature}.md
• docs/plans/{feature}-progress.json
04命令参考
统一通过 /hx <command> [args] 触发。无参数时默认执行 go。
| 命令 | 阶段 | 作用 | 下一步 |
|---|---|---|---|
/hx init |
初始化 | 生成 .hx/config.yaml（单项目）或 .hx/workspace.yaml（多项目）与规则模板 |
doc |
/hx doc <feature> |
Phase 01 | 获取需求并写入 docs/requirement/{feature}.md |
plan |
/hx plan <feature> |
Phase 02 | 生成执行计划与 progress.json |
run |
/hx run <feature> |
Phase 04 | 按批次执行 task，完成后回写 progress | check |
/hx check <feature> |
Phase 06 | 质量门、审查、工程卫生检查 | mr |
/hx mr <feature> |
Phase 08 | 生成标题与描述，创建 Merge Request | — |
/hx go <feature> |
全流程 | 串联 doc → plan → run → check → mr |
自动 |
/hx status |
状态 | 查看当前任务进度 | — |
/hx reset <feature> [plan|doc|code] |
维护 | 重置需求、计划或执行状态 | — |
05项目结构
框架目录与使用者产物严格分层：改行为改 hxflow/，读/写运行时事实读 .hx/。
框架层 hxflow/
hxflow/ ├─ SKILL.md # Skill 入口，路由命令 ├─ commands/ # hx-*.md 命令契约 ├─ scripts/ │ ├─ tools/ # 事实脚本（AI 调用） │ └─ lib/ # 共享工具 └─ templates/ # 规则模板与默认配置
使用者产物 .hx/
.hx/ ├─ config.yaml # 单项目模式 ├─ workspace.yaml # workspace 模式（多项目） ├─ rules/ # 规则模板（需求/计划等） ├─ hooks/ # 自定义 hook（可选） └─ pipelines/ # 自定义 pipeline（可选）
改命令行为、默认骨架请修改 hxflow/commands / hxflow/scripts / hxflow/templates；.hx/* 只是 hx-init 的落地验证，不是事实源。
06测试与发布
本地开发循环一行命令解决；发布走 GitHub Packages，由 v* tag 自动触发。
常用命令
bun run hx:test # 全量 bun run hx:test:unit # 单元 bun run hx:test:integration # 集成 bun run pack:dry-run # 检查发包内容
持续评测
bun run hx:evals:validate bun run hx:evals:report
失败样本沉淀到 regressions.jsonl，对 prompt / 命令 / 脚本改动做回归对比。