前言¶
在多工具协作（如 Cursor、Claude Code、DSH）的开发场景中，统一编码规范（ICVO）并确保 Harness 流程的 P0 门控执行，通常需要手动维护多套配置。SpecWave 提供了一个声明式的适配表，将一套规范原生化地落地到多个客户端中，并内置 Harness 进程命令与任务门控机制。
是什么¶
SpecWave 是一个多主机编码 CLI 工具。它通过声明式的适配表，将 ICVO 规范（告知、约束、验证、编排）和 Harness 流程直接注入到 Cursor、Claude Code、可选的 DSH 以及其他智能体工具中。工具提供 P0 门控（Gate）与 Harness 进程命令支持，确保流程在 IDE 和命令行中的一致性。
安装与启用¶
在使用前，请确保 Node.js 版本满足要求。
# 检查 Node.js 版本，需为 ^22.19.0 或 >=24.0.0
node -v
通过 npm 全局执行（推荐锁定版本）：
# 确认版本
npx spec-wave@3.0.2 --version
核心功能¶
- 多主机落地：一套适配表支持 Cursor、Claude Code、DSH 及其他智能体。
- P0 门控与 Harness：内置 Harness 进程命令与任务验证门控，支持硬停止（exit 2）。
- ICVO 规范：维护 Discipline 资产，确保编码行为的可约束性与可验证性。
- 主机应用：通过
host apply命令将适配表写入对应 IDE 的目录结构。
典型用法¶
1. 验证适配表¶
在正式应用前，先进行 dry-run 验证：
npx spec-wave@3.0.2 host validate
2. 应用主机配置¶
将适配表写入指定工具（以 Cursor、Claude Code、DSH 为例）：
npx spec-wave@3.0.2 host apply --tools cursor,claude,dsh --profile core
3. 初始化项目¶
如果这是首次初始化，指定 preset 并自动应用：
npx spec-wave@3.0.2 init --preset harness-only --tools cursor,claude,dsh --yes
4. 验证任务门控¶
在执行任务前，验证任务文档是否符合规范，如果门控失败则进程退出（exit 2）：
npx spec-wave@3.0.2 verify --task docs/tasks/active/task_<slug>.md
关于 DSH 与系统提示词的注意点¶
Loading ≠ injecting。安装或加载 DSH 插件不会自动重写系统提示词。apply() 仅注册工具。只有当你或模型调用了 apply_coding_standards 后，后续轮次的运行时上下文才会包含 # Coding Standards。
适用场景与注意¶
- 适用场景：需要在 Cursor、Claude Code、DSH 之间保持一致编码规范的开发者；使用 Harness 流程管理任务门控的团队。
- Node 版本限制：不支持 Node 20 及更早版本，升级前请检查环境。
- 文件写入限制：CLI 不会自动将示例任务写入
docs/tasks/，需手动复制模板。 - 人工门控表：
HG-AUDIT-R1等人工门控表必须包含 4 列。 - 源码与许可证：使用前请检查源码与许可证（MIT）。
结语¶
SpecWave 通过声明式配置解决了多客户端规范同步的痛点，结合 Harness 的 P0 门控，为 AI 编码提供了强约束的执行环境。更多细节可参考项目目录或 GitHub 仓库。
