dwf-requirement

本技能用于把零散需求整理成 DWF 工作流的需求文档。它只负责需求捕获与需求文档生成；独立运行时不启动完整开发工作流，工作流模式下按 .dwf/state.json 继续当前阶段。

<HARD-GATE> 以下规则不可违反：

1. 只生成需求文档。

本技能默认只创建或更新目标 spec 目录下 01-需求/需求文档.md。不创建其它阶段文档或代码。

1. 目标 spec 目录由运行模式决定，不由本技能臆造。

- 工作流模式：读取 .dwf/state.json，在 specs 数组中找 status: "active" 且 current_step: "requirements" 的 spec，以 .dwf/specs/{spec.name} 作为目标 spec 目录。 - 独立模式：.dwf/state.json 不存在或不存在满足条件的 active spec。用 question 询问用户目标目录，默认提议 .dwf/specs/{今日日期}-{seq}-feat-{从用户输入提取的描述}，其中 seq 扫描 .dwf/specs/ 现有 spec 目录名中的最大序号 +1（无则 001），由用户确认或修改。

1. 独立模式下不要创建或推进 .dwf/state.json。

独立模式只写目标 spec 目录下的需求文档与该 spec 的 meta.json（如该 spec 目录为本技能创建）。不要把项目推进到 design、breakdown、plans、todos 或 code。只有工作流模式下才在用户确认后更新 state.json 中该 spec 的 currentstep。

1. 不要创建完整工作流目录。

除目标 spec 目录下的 01-需求/ 外，不要主动创建 02-设计稿/、03-需求分析/、04-技术方案/、05-实现清单/。项目代码目录由用户/dwf-coding 决定，本技能不创建。

1. 确认前不要覆盖已有文档。

如果目标 spec 目录下 01-需求/需求文档.md 已存在，先读取并告知用户已有文档，询问是保留、修改还是替换。用户确认前不要覆盖。

1. 全程使用中文。

除非用户明确要求使用其他语言，所有与用户的交互、需求澄清问题、生成文档、标题、标签、表格内容、说明文字、测试记录和产物说明都必须使用中文。代码、文件路径、命令、API 名、技术术语、第三方库名和用户提供的原文内容可以保留英文。

</HARD-GATE>

触发后流程

1. 探查上下文

• 检查 .dwf/state.json 是否存在，确定运行模式（见步骤 2）。
• 判断用户输入来源：长文本、本地文件路径、外部链接、简短想法或口头描述。
• 如果用户提供本地文件路径，读取文件内容后整理为需求依据。
• 如果用户提供外部文档链接，根据链接类型使用相应技能读取。例如飞书文档使用 lark-doc，网页文档使用 web-access。
• 如果用户只给出简短想法，先澄清会影响需求结构和验收标准的最少信息。

2. 判断运行模式与目标 spec 目录

读取 .dwf/state.json：

• 工作流模式：在 specs 数组中找到 status: "active" 且 current_step: "requirements" 的 spec。目标 spec 目录为 .dwf/specs/{spec.name}/。

- 如该目录下 01-需求/需求文档.md 已存在，先读取并按“已有文档处理”执行。 - 需求文档完成并经用户确认后，把该 spec 的 currentstep 更新为 "design"、把 requirements 追加到 confirmedstages，并同步其 meta.json 与顶层 updatedat。 - 遵循 dwf-orchestrator 的确认机制，不跳过用户确认。

• 独立模式：.dwf/state.json 不存在，或不存在满足条件的 active spec。

- 用 question 询问用户目标 spec 目录，默认提议 .dwf/specs/{今日日期}-{seq}-feat-{描述}（描述从用户输入提取，seq 扫描 .dwf/specs/ 现有 spec 目录名中的最大序号 +1，无则 001），由用户确认或修改。如用户选择别的目录，以用户输入为准。 - 如目标 spec 目录不存在，创建它及其下 01-需求/。 - 在该 spec 目录下写一份初始 meta.json（name 为目录名、status: "active"、currentstep: "requirements"、issharedcontext: false、shared_ref: null 等）。 - 不要创建 .dwf/state.json，不推进完整工作流。 - 需求文档完成后请求用户确认，确认后停止。

3. 判断输入来源

根据用户提供的信息选择处理方式：

• 完整需求文档或长文本： 直接提取项目名称、背景、目标、用户角色、范围、功能需求、非功能需求、约束、依赖、风险和验收标准。
• 本地文件路径： 读取文件内容后整理为需求文档。
• 外部文档链接： 根据链接类型使用相应技能读取。例如飞书文档使用 lark-doc，网页文档使用 web-access。
• 简短想法或口头描述： 先澄清需求，不要急于生成文档。

4. 澄清缺失信息

如果信息不足，按“一次一个问题”的方式追问。优先澄清会影响文档结构和验收标准的内容：

1. 项目名称或一句话概述。
2. 背景与业务价值。
3. 目标用户与角色。
4. 目标端：PC 端、移动端或双端。
5. 范围内和范围外内容。
6. 核心用例和主流程。
7. 功能性需求与优先级。
8. 非功能性需求。
9. 约束、假设、依赖与风险。
10. 整体验收标准。

不要一次抛出大量问题。若可以基于上下文合理假设，先明确写入“假设”，并把不确定项放入“待确认事项”。

5. 生成需求文档

读取 references/requirements_template.md，按模板生成中文需求文档。保存到目标 spec 目录下：

{目标 spec 目录}/01-需求/需求文档.md

生成规则：

• 保留 YAML frontmatter，包括 project、version、author、date、status 和 revision。
• 新文档的 status 默认为 draft。
• date 使用当前日期。
• version 初始为 1.0.0。
• revision 记录“初始版本”。
• 文档必须包含业务流程图，使用 Mermaid 表达主流程；如果信息不足，生成合理的高层流程，并在“待确认事项”中标注需要确认的分支。
• 功能性需求使用 FR-1、FR-2 编号。
• 非功能性需求使用 NFR-1、NFR-2 编号。
• 优先级使用 MoSCoW：必须、应该、可以、不会。
• 验收条件必须可观察或可测试。

6. 请求用户确认

生成文档后，向用户展示保存位置和简要摘要，并请求确认：

• 如果用户确认，说明需求文档已完成。
• 如果用户提出修改意见，直接更新目标 spec 目录下 01-需求/需求文档.md，保持 status: draft，并再次请求确认。
• 如果用户明确要求标记为已确认，将 frontmatter 中的 status 改为 confirmed，并在 revision 中追加确认记录。

确认完成后：

• 独立模式：停止，不自动进入设计稿、需求分析、技术方案、实现清单或编码。
• 工作流模式：更新该 spec 的 currentstep 为 "design"、把 requirements 追加到 confirmedstages，同步 meta.json 与 updatedat，由 dwf-orchestrator 推进。

已有文档处理

如果目标文件已存在：

1. 读取 {目标 spec 目录}/01-需求/需求文档.md。
2. 总结当前文档的项目名称、版本、状态和主要内容。
3. 询问用户要如何处理：

- 保留现有文档，仅查看或总结。 - 基于现有文档修改。 - 替换为新需求文档。

1. 只有用户明确选择修改或替换后，才能写入文件。

修改已有文档时：

• 保留原有结构，除非用户要求重写。
• 更新 date。
• 如用户确认这是新版本，递增 version 并追加 revision 条目。
• 不要创建 需求文档-v2.md 之类的新版本文件，除非用户明确要求。

完成前检查

结束前确认：

• 只创建或更新了目标 spec 目录下 01-需求/需求文档.md。
• 独立模式下没有创建 .dwf/state.json。
• 独立模式下没有创建除目标 spec 目录 01-需求/ 外的其它阶段目录。
• 独立模式下没有推进后续阶段。
• 工作流模式下只在用户确认后更新该 spec 的 current_step 为 design。
• 文档内容为中文。
• 文档包含 frontmatter。
• 文档包含背景、目标、用户角色、范围、用例、功能性需求、非功能性需求、约束、依赖、风险、验收标准和待确认事项。
• 已说明保存路径和下一步需要用户确认的事项。