specworkflow

dsh plugin --profile web add specworkflow

SpecWorkflow

[English](README.md) | 中文

SpecWorkflow 是一套面向 DeepSeek Harness 和其它兼容 Agent Skills 工具的工作流技能包，涵盖需求澄清、需求规格、实施、交付审查、修复规划、问题诊断和一手来源调研。

简单明确的修改可以直接处理；需求模糊、跨模块，或影响产品体验、数据、权限、接口和发布风险的工作，才进入完整工作流。

功能

阶段 · Skill · 处理内容

调研 · deep-research · 基于官方文档、API、标准、源码等一手来源做调研。

1 · to-grill · 需求质询、消除歧义、风险审查，并判断直接实施还是进入完整流程。

2 · to-spec · 编写可实施的需求规格、修订说明、验收标准、验证计划和可选任务单。

3 · spec-do · 根据已批准的需求规格、任务单、修订或修复计划进行实施。

4 · do-review · 对照需求、规格、代码和证据做最终交付审查。

5 · fix-review · 把必须修复的问题整理成修复规格和修复任务单。

调试 · bugs-fix · 针对 bug、回归和性能问题做复现、根因定位、修复和证据留存。

安装

DSH

dsh plugin --profile web add specworkflow
dsh web

其它 Agent

npx specworkflow install codex

使用 -g 安装到全局目录：

npx specworkflow install -g codex

需要时把 codex 换成其它预设：

输入 · 项目安装位置 · -g 全局安装位置

codex, openai, agents, agent, agent-skills, agents-md, goose, zed, amp, sourcegraph-amp · .agents/skills · ~/.agents/skills

gemini, gemini-cli, antigravity, google-antigravity · .agents/skills · ~/.gemini/antigravity/skills

claude, claude-code, claudecode · .claude/skills · ~/.claude/skills

cursor, cursor-agent, cursor-native · .cursor/skills · ~/.cursor/skills

copilot, github-copilot, vscode, vs-code · .github/skills · ~/.github/skills

dsh, deepseek, deepseek-harness · .dsh/skills · ~/.dsh/skills

opencode, open-code · .opencode/skills · ~/.opencode/skills

windsurf, cascade · .windsurf/skills · ~/.windsurf/skills

cline, claudine · .cline/skills · ~/.cline/skills

roo, roo-code, roocode · .roo/skills · ~/.roo/skills

qwen, qwen-code, qwencode · .qwen/skills · ~/.qwen/skills

kiro · .kiro/skills · ~/.kiro/skills

kilo, kilo-code, kilocode · .kilo/skills · ~/.kilo/skills

augment, augment-code, augmentcode, auggie · .augment/skills · ~/.augment/skills

openclaw, claw · skills · ~/.openclaw/skills

未识别的纯名称会直接报错，避免因为拼错而创建错误目录。如果当前工具不在预设里，请传入明确的项目级 skills 路径：

npx specworkflow install .my-agent/skills

带 -g 时，相对显式路径会从用户主目录解析。

快速开始

典型功能开发：

使用 to-grill 澄清这个需求，需求收口后再进入 to-spec。

简单修改保持简单：

把表格字体调大一点。

这类请求应该直接实施，不应该强行进入五阶段流程。

工作流

先判断需求是否需要正式规格。改一段文案、调一个样式、补一个明确遗漏的判断，这类小修改可以直接完成。

只有当需求开始牵涉产品含义、数据语义、权限边界、跨模块影响、发布风险，或者“做错了会很难收拾”时，才进入完整流程。同一件事产生的材料都放在同一个 .spec-workflow/<feature-slug>/ 目录下，后续每一轮都能接得上。

to-grill -> to-spec -> spec-do -> do-review -> fix-review -> spec-do repair -> do-review

to-grill 先读取上下文和现有实现，再询问需要用户决定的问题。阶段结束时，会明确直接修改、暂缓或编写需求规格，并留下下一阶段可读取的需求结论。

to-spec 将需求结论写成实施规格，说明做什么、不做什么、影响哪些模块、数据和权限如何处理，以及验收需要哪些证据。调整已有规格时，会保留修订记录和影响范围。

spec-do 按已批准的规格、任务单、修订或修复计划实施。动代码前检查 Git 分支和未提交改动；目标模式沿用最后选择的提交策略，分阶段执行则先确定提交权限。临时证据保存在 .spec-workflow，长期测试放在项目自己的测试目录。业务逻辑必须真实执行，不能靠模拟系统业务逻辑让验证通过。

do-review 对照原始需求、规格、代码 diff、测试和证据检查遗漏、回归、边界与验收缺口，给出可以交付、修复后交付或不可交付的结论。该阶段只审查，不修改代码或扩大范围。

需要修复时，fix-review 根据问题的根因、优先级和验证方式编写修复计划，必要时拆成任务单，再交给 spec-do。修复后由 do-review 再次检查，直到可以交付或出现需要用户决定的阻断。

deep-research 和 bugs-fix 不属于主链上的固定阶段，更像两条随时可以插入的支线。遇到外部事实、官方文档、API 行为、标准差异时，先用 deep-research 把依据找齐；如果起点不是新需求，而是失败、回归、异常或性能问题，就直接走 bugs-fix，先复现和定位根因。

目标模式

目标模式放在 to-spec 最后选择。需求、测试方案、任务单、分支处理和完整规格都先确定，再展示本次的规格版本、完成标准、修复次数上限、执行方式和提交策略。提前说“后续自主执行”只记录意向，不会启动目标。

自动修复次数默认推荐 3 次，同时提供 5 次、10 次、自定义。该上限仅限制当前规格的修复循环，目标达成就提前结束。次数在最后的执行选择前确定；宿主续跑上限和 token 预算单独记录。

选择目标模式代表同意本次执行；真正启动仍要经过宿主操作。有目标 API 时，Agent 必须创建或复用当前规格的目标，并读回状态验证。只能通过用户命令或界面启动时，会显示“等待宿主启动”。仅记录“目标模式：仅对当前规格启用”不能证明启动成功。

启动后，实施、交付审查、修复规划和修复实施连续推进，已确定的需求、测试和提交策略不重复询问。范围内的缺陷由 Agent 修复。新产品选择、范围变化、文件归属冲突、必要验证不可用或次数耗尽时，先记录阻断，再提问。新的规格或修订版本必须重新选择。

未核实持久目标或循环机制时，只能明确提供当前会话连续执行，宿主结束回合后不保证自动续跑。自动批准和跳过权限不能代替目标驱动。各工具的入口和验证方式见[运行适配说明](skill-package/to-spec/references/agent-runtime-adapters.md)。

工具 · 目标或续跑入口

Codex · 有目标工具时直接调用；否则由用户在当前对话提交 /goal。

Claude Code · 用户提交 /goal <condition>，检查活动指示和状态。

Cursor · 已开放该功能的版本使用 /goal [objective]。

DSH · 调用 create_goal，并核对官方续轮驱动器、活动状态 active 和续跑状态 armed。

Copilot CLI · 切到实际的 Autopilot 模式后提交当前规格的执行提示，或接受已就绪计划并开始执行。

Qwen Code、Kiro CLI、Kilo Code、Antigravity、Junie、Hermes · 已核实原生目标入口；审批、状态、完成判定和恢复规则按产品分别处理。

其它工具和未来版本 · 先自行调研当前宿主，再决定执行方式；自动批准或目标状态持久化本身不足以证明自主续跑。

内置的[调研目录](skill-package/to-spec/references/additional-agent-runtimes.md)覆盖 30 个工具和产品，包含安装器预设涉及的全部宿主，保存了启动步骤、执行表面、生命周期限制和一手来源。证据不足的明确标注。

新 Agent、入口缺失、版本变化或资料冲突都会触发[内置兜底调研](skill-package/to-spec/references/runtime-discovery.md)：Agent 自己检查当前工具和帮助菜单，读取最新官方文档或源码，把本次结果存到 .spec-workflow/<feature-slug>/research/agent-runtime.md，确认真实启动后才实施。它不会自动重写已安装 skill，也不会因为查到一种方法，就自行装插件、提高权限或新开云任务。

展示语言与阶段交接

七个技能各自内置[中英对照与读取规则](skill-package/to-spec/references/bilingual-output.md)。中文请求使用中文问题、进度、报告标题和交付结论；英文请求使用英文，不要求每句话同时展示两种语言。编程术语、实际命令/API 字段、文件路径和原始证据保留真实写法。

语言要求按对象生效：中文对话里指定“报告用英文”，报告使用英文，日常进度和提问仍使用中文；只有明确要求全部切换，才改变所有输出。子代理及中断续作都会接收并沿用这套已确定的规则。

后续阶段会识别“完成状态：完成”“交付结论：可以交付”，也兼容旧英文和混合材料；状态仍按任务、审查、目标执行等领域判断，翻译不改变授权或修复计数。技能面板元数据只有静态字符串，因此使用中英双语标签，不宣称能自动切换语言。

目录产出

工作流材料保存在 .spec-workflow 下。

.spec-workflow/<feature-slug>/
  requirements.md
  spec.md
  issues/
  amendments/
  implementation/
  review/
  repair-spec.md
  repair-issues/
  verification/
  debug/
  bugs/
  research/

项目长期测试仍然放在项目原本的测试目录，不放进 .spec-workflow。

验证

安装到 DSH 后运行：

dsh --profile web --dump-config

组合配置里应该出现：

# == specworkflow
- id: specworkflow
  name: specworkflow

也可以直接询问 Agent 当前有哪些 SpecWorkflow skills，以及什么时候使用 to-grill。

卸载

dsh plugin --profile web remove specworkflow

把 web 换成你实际安装的 profile。

#

…(truncated)