<HARD-GATE> 本技能通过 .dwf/state.json 追踪严格的分阶段工作流。以下规则不可违反：

1. 禁止未经确认的自动推进。 每个阶段转换都必须使用 question 工具获取用户明确确认，不得仅用纯文本询问。如果用户没有选择确认选项或明确回复确认，不得进入下一阶段。

1. 禁止直接修改代码。 当 current_step 为 code 或 done 时，任何对 06-code/ 目录或项目代码的修改都必须走迭代流程，无一例外。这包括：bug 修复、小幅调整、文案修改、配置变更——无论多小。

1. 禁止跳过阶段。 用户说"直接写代码"或"这只是个小 bug"不是跳过流程的理由。正确做法是引导用户进入迭代流程。

1. 每次调用必须先读 state.json。 在生成任何内容或执行任何动作之前，首先读取 .dwf/state.json 以确定当前所处阶段。然后严格按照该阶段的要求行动。

1. 全程使用中文。 所有与用户的交互（包括 question 工具的选项和标题）、所有生成的文档（需求文档、设计稿、需求拆解文档、技术方案、实现清单）、以及文档中的标题/标签/说明，必须使用中文。仅代码、文件路径、技术术语（如 React、Vue、API）等本身无法翻译的内容可以使用英文。

违反以上任何一条都是对工作流的破坏。 </HARD-GATE>

dev-workflow 工作流

一个严格按顺序执行的工作流，将需求逐步转化为可交付的代码。每个阶段必须完成并经用户确认后才能进入下一阶段。

核心原则

任何阶段在上一个阶段经用户确认之前都不能开始。 这是不可协商的。如果用户试图跳过，请引导他们回到当前未确认的阶段。

编程规范与模板

编码相关阶段必须读取并遵循 references/coding_standards.md。该文件是本技能输出规范代码的统一来源，覆盖执行前分析、代码风格、React 前端约定、任务执行和验证要求。

当项目从零创建且技术方案选择 React 前端时，优先使用 assets/ 中的模板作为 06-code/ 的基础：

使用模板时，只复制与选定端和技术方案匹配的源码与配置；不要复制无关端模板，不要把 dist/ 构建产物当作后续开发源码，除非用户明确要求。

确认机制

每个需要用户确认的步骤，必须使用 question 工具进行交互，不得仅用纯文本询问。question 工具提供结构化的选项，确保用户明确做出决策。

所有 question 调用默认启用自定义输入（custom: true），用户可以在选项之外输入自由文本。各场景的标准问题格式详见 references/question_templates.md，包含以下场景：

重要： 如果用户选择"启动新项目"，不得立即执行。必须先进行二次风险告知与确认（参照 references/question_templates.md → 新项目风险确认），只有用户在二次确认中明确选择"确认删除并重启"后，才执行「重新开始」流程。

状态追踪

工作流在 .dwf/state.json 中追踪其状态。每次调用时首先读取此文件，以确定用户当前所处的阶段。

状态值及其含义：

如果 .dwf/state.json 不存在，说明工作流尚未启动，从阶段 1 开始。

state.json 结构

{
  "current_step": "requirements",
  "project_name": "项目名称",
  "iteration_count": 0,
  "design_skipped": false,
  "selected_plan": null,
  "created_at": "2026-06-24T10:00:00",
  "updated_at": "2026-06-24T10:00:00"
}

迭代状态结构

当工作流进入迭代模式时，state.json 会新增 iteration 子对象：

{
  "current_step": "iteration",
  "project_name": "项目名称",
  "iteration_count": 0,
  "design_skipped": false,
  "selected_plan": "方案A",
  "iteration": {
    "name": "bugfix-修复样式问题",
    "dir": "07-需求迭代/2026-06-24-bugfix-修复样式问题",
    "affected_stages": ["requirements", "todos"],
    "current_substep": "requirements",
    "confirmed_stages": []
  },
  "created_at": "2026-06-24T10:00:00",
  "updated_at": "2026-06-25T14:30:00"
}

• iteration.name 为迭代名称，格式 {type}-{描述}，在进入迭代时由 AI 提议、用户确认。
• iteration.dir 为迭代文档的保存目录，相对于工作区根目录，格式 07-需求迭代/{date}-{type}-{描述}。
• iteration.affected_stages 为本次迭代需要更新的阶段列表，按阶段顺序排列。由 AI 分析并提出，用户确认或调整。
• iteration.current_substep 为当前正在处理的阶段，每完成一个阶段的确认后推进到下一个受影响阶段。
• iteration.confirmed_stages 为已确认的阶段列表，确认后追加，用于断点恢复。

通用字段说明：

• project_name 为项目名称，在初始化时由用户提供或从需求文档中提取。
• iteration_count 记录已完成的迭代次数，首次迭代进行中为 0，完成后递增。
• design_skipped 标记设计稿阶段是否被跳过。
• selected_plan 记录用户在技术方案阶段选定的方案（如 "方案A"），迭代时不重置。
• createdat 为工作流首次创建时间，updatedat 为最近一次状态变更时间。
• 写入 state.json 时务必更新 updated_at 为当前时间。

目录结构

文档目录存储在工作区根目录下，状态追踪文件存储在 .dwf/ 中：

工作区根目录/
├── .dwf/
│   └── state.json                              # 当前阶段状态
├── 01-需求文档/
│   └── 需求文档.md                              # 需求文档
├── 02-设计稿/
│   ├── 设计稿.md                                # 设计稿说明（含链接等）
│   └── images/                                  # 设计稿图片
├── 03-需求拆解文档/
│   └── 需求拆解文档.md                          # 需求拆解文档
├── 04-技术方案/
│   └── 技术方案.md                              # 技术方案（含多个并列方案）
├── 05-实现清单/
│   └── 实现清单.md                              # 实现清单
├── 06-code/                                     # 实际项目代码
│   └── ...
└── 07-需求迭代/
    └── 2026-06-24-bugfix-修复样式问题/          # 迭代目录（date-type-描述）
        ├── 需求文档/                             (受影响时才包含)
        ├── 设计稿/                               (受影响时才包含)
        ├── 需求拆解文档/                         (受影响时才包含)
        ├── 技术方案/                             (受影响时才包含)
        └── 实现清单/                             (受影响时才包含)

阶段

阶段 0：自检（每次调用必执行）

1. 读取 .dwf/state.json（如存在）。
2. 根据 current_step 确定当前阶段。
3. 如果用户请求涉及代码修改且 current_step 为 code 或 done，必须告知用户将进入迭代流程，不得直接修改代码。
4. 按照当前阶段的要求行动，不得跳过。

阶段 1：初始化 & 捕获需求

进入条件： state.json 不存在，或状态为 init。

1. 创建 .dwf/ 目录及 state.json，并在工作区根目录创建文档子目录：01-需求文档/、02-设计稿/、02-设计稿/images/、03-需求拆解文档/、04-技术方案/、05-实现清单/、06-code/、07-需求迭代/。
2. 写入 .dwf/state.json，内容为：

``json { "currentstep": "requirements", "projectname": "<项目名称>", "iterationcount": 0, "designskipped": false, "selectedplan": null, "createdat": "<当前时间>", "updated_at": "<当前时间>" } ``

1. 根据用户输入判断需求获取方式：

- 用户提供完善的需求文档（markdown / 飞书文档 / Google docs / 纯文本 / 图片）： - 读取并提取需求内容。飞书文档 URL 使用 lark-doc 技能读取；网页文档使用 web-access 技能读取；本地文件直接读取。 - 按 references/requirementstemplate.md 模板归一化为需求文档。 - 用户提供大概的需求说明： - 提出澄清性问题，一次一个问题（优先多选），多轮迭代直到理解：要构建什么（目标、范围、边界）、为什么做（背景与业务价值）、谁是用户/角色、目标端、关键约束与假设、依赖与风险、验收标准。 > 编码准则：遵循 karpathy-guidelines「Think Before Coding」——显式陈述假设，不确定时发问，不隐藏困惑。 - 按 references/requirementstemplate.md 模板生成需求文档。

1. 保存到 01-需求文档/需求文档.md。
2. 使用 question 工具向用户展示文档并请求确认（参照 references/question_templates.md → 阶段文档确认）。
3. 等待用户确认。 在用户明确确认之前，不要进入阶段 2。

- 如果用户选择"需要修改"或输入修改意见：直接修改 01-需求文档/需求文档.md，更新 updatedat，并再次使用 question 工具请求确认。 - 只有在用户选择"确认"后：更新 .dwf/state.json 的 currentstep 为 "design" 和 updated_at，然后推进。

阶段 2：设计稿

进入条件： state.json 存在且 current_step 为 design。

1. 使用 question 工具向用户收集设计稿信息（参照「确认机制 → 设计稿方式选择」格式）。
2. 根据用户回复处理：

- 用户提供链接或图片： - 将链接记录到 设计稿.md 中；如为图片，保存到 02-设计稿/images/ 目录。 - 如为 Figma 等在线设计稿链接，尝试下载截图保存到 images/；若下载失败，仅记录链接并告知用户。 - 按照 references/designtemplate.md 中的模板生成设计稿说明文档，保存到 02-设计稿/设计稿.md。 - 用户选择由 AI 生成： - 读取 01-需求文档/需求文档.md，结合用户的设计思路生成设计方案。 - 分析项目类型（PC 端 / 移动端 / 双端），确定设计维度和规范。 - 按照 references/designtemplate.md 中的模板生成设计文档，包含：整体布局和页面结构说明、关键页面的设计描述（布局、配色、字号、间距等视觉规范）、交互说明、设计规范（颜色体系、字体体系、间距体系、组件规范）。 - 生成设计稿图片（PNG）保存到 02-设计稿/images/ 目录（机制：渲染 HTML/CSS mockup 为 PNG；如不适用则使用 nanobanana-skill 生成）。 - 保存设计文档到 02-设计稿/设计稿.md。 - 更新 state.json 的 designskipped 为 false。 - 用户选择跳过： - 在 02-设计稿/设计稿.md 中记录"设计稿阶段已跳过"。 - 更新 state.json 的 designskipped 为 true。

1. 使用 question 工具向用户展示结果并请求确认（参照 references/question_templates.md → 阶段文档确认）。
2. 等待用户确认。

- 如果用户选择"需要修改"或输入修改意见：修改后再次使用 question 工具请求确认。 - 只有在用户选择"确认"后：更新 .dwf/state.json 的 currentstep 为 "breakdown" 和 updatedat，然后推进。

阶段 3：需求拆解文档

进入条件： state.json 存在且 current_step 为 breakdown。

1. 读取 01-需求文档/需求文档.md；若 design_skipped 为 false，同时读取 02-设计稿/设计稿.md。
2. 结合需求文档和设计稿进行功能拆解，按照 references/breakdown_template.md 中的模板生成文档，覆盖：

- 目标端： PC 端 / 移动端 / 双端。 - 页面与功能拆解： 按页面分别列出每个页面的端、依赖与功能模块；跨页面共享模块单独归类。 - 素材/依赖清单： 需要用户提供哪些素材（如 API 密钥、账号、第三方服务凭证、图片素材等）。 - 范围边界： 明确不在本次实现内的部分。

1. 保存到 03-需求拆解文档/需求拆解文档.md。
2. 使用 question 工具向用户展示文档并请求确认（参照 references/question_templates.md → 阶段文档确认）。
3. 等待用户确认。

- 如果用户选择"需要修改"或输入修改意见：直接修改 03-需求拆解文档/需求拆解文档.md，更新 updatedat，并再次使用 question 工具请求确认。 - 只有在用户选择"确认"后：更新 .dwf/state.json 的 currentstep 为 "plans" 和 updated_at，然后推进。

阶段 4：生成技术方案

进入条件： state.json 存在且 current_step 为 plans。

1. 读取 01-需求文档/需求文档.md 和 03-需求拆解文档/需求拆解文档.md；若 design_skipped 为 false，同时读取 02-设计稿/设计稿.md。
2. 分析代码库（如果存在），了解当前架构、约定和模式。
3. 读取 references/coding_standards.md，并在方案中说明编码规范、验证策略和模板使用方式；如果是从零创建 React 前端项目，至少一个方案应优先基于 assets/react-pc/ 或 assets/react-mobile/ 模板。
4. 按照 references/plans_template.md 中的模板生成技术方案，必须提供至少 2 个并列方案。每个方案包括：

- 框架/技术栈选型及其理由 - 需要的第三方库 - 后端接口需求（需要后端提供哪些接口、接口字段定义） - 数据模型变更 - 受影响的文件和模块 - 编程规范与模板使用说明 - 风险评估和缓解策略 - 优劣对比

1. 在 04-技术方案/技术方案.md 中包含所有方案及方案对比表，更新 updated_at。
2. 使用 question 工具向用户展示方案并请求选择（参照「确认机制 → 技术方案选择确认」格式，按实际方案数量追加选项）。
3. 等待用户选择。

- 如果用户选择"需要修改"或输入修改意见：直接修改 04-技术方案/技术方案.md，更新 updatedat，并再次使用 question 工具请求确认。 - 只有在用户选择某个方案后：在 .dwf/state.json 的 selectedplan 记录所选方案（如 "方案A"），更新 currentstep 为 "todos" 和 updatedat，然后推进。

阶段 5：生成实现清单

进入条件： state.json 存在且 current_step 为 todos。

1. 同时读取 01-需求文档/需求文档.md、03-需求拆解文档/需求拆解文档.md 和 04-技术方案/技术方案.md（以 selected_plan 指定的方案为主）。
2. 读取 references/coding_standards.md，将其中的编码规范、模板使用和验证要求转化为实现清单中的执行约束。
3. 将选定方案分解为具体的、有序的任务，遵循 references/todos_template.md 中的模板。任务要求：

- 尽可能拆分，不要一次性实现某个功能或页面（例如一个页面应拆为骨架、组件A、组件B、状态接入、接口联调、样式等独立任务）。 - 足够具体，可以无歧义地执行。 - 按依赖关系排序（前面的任务为后面的任务解除阻塞）。 - 分配优先级（必须/应该/可以/不会，MoSCoW）。 - 每个任务都必须包含“编码规范检查”和“验证标准”，确保 coding 阶段能逐项核对。

1. 保存到 05-实现清单/实现清单.md，更新 updated_at。
2. 使用 question 工具向用户展示实现清单并请求确认（参照 references/question_templates.md → 阶段文档确认）。
3. 等待用户确认。

- 如果用户选择"需要修改"或输入修改意见：直接修改 05-实现清单/实现清单.md，更新 updatedat，并再次使用 question 工具请求确认。 - 只有在用户选择"确认"后：更新 .dwf/state.json 的 currentstep 为 "code" 和 updated_at，然后推进。

阶段 6：编码执行

进入条件： state.json 存在且 current_step 为 code。

1. 读取 05-实现清单/实现清单.md 和 04-技术方案/技术方案.md（以 selected_plan 指定的方案为主）。
2. 读取 references/coding_standards.md。如果 06-code/ 尚无项目代码且选定方案基于 React 模板，先按目标端使用 assets/react-pc/ 或 assets/react-mobile/ 初始化代码，并按需合并 assets/shared/。
3. 在 06-code/ 目录下按顺序逐个执行任务。每完成一个任务，按实现清单中的“编码规范检查”和“验证标准”核对，再在 05-实现清单/实现清单.md 中将其标记为已完成。
4. 如果某个任务暴露了使方案或需求失效的问题，暂停执行并通知用户。不要悄然偏离。
5. 所有任务完成后，写入 .dwf/state.json 为 {"currentstep": "done", ...} 并更新 updatedat。
6. 总结所做的工作以及任何后续事项，并使用「确认机制 → 工作流完成」格式向用户询问后续操作。

迭代机制

触发条件

以下任一情况出现时，必须进入迭代流程：

• 用户提出新功能需求
• 用户报告 bug 或请求 bug 修复
• 用户请求对现有代码做任何修改（包括配置调整、文案修改、样式微调等）
• 用户提出性能优化、重构等改进需求
• 用户请求对现有功能做任何增删改

无论修改大小，都必须走迭代。一行代码的修改也必须经过迭代确认。

迭代命名

迭代目录命名为 {date}-{type}-{描述}，例如 2026-06-24-bugfix-修复样式问题。type 采用 conventional-commit 风格前缀：feat（新功能）、bugfix（修复）、refactor（重构）、perf（性能）、style（样式）、docs（文档）、chore（杂项）。AI 根据用户描述提议格式化名称，用户确认。

迭代流程

迭代流程与初始流程一样，遵循严格的逐步确认原则。每个受影响阶段的文档必须逐一经过用户确认后，才能进入下一个阶段。

迭代步骤 1：初始化 & 影响分析

1. 根据用户描述提议迭代名称（{type}-{描述}），使用 question 工具请用户确认名称。
2. 创建 07-需求迭代/{date}-{type}-{描述}/ 目录。
3. 分析变更影响了哪些阶段，提出受影响阶段列表。阶段按以下顺序排列：

- requirements → design → breakdown → plans → todos - 仅包含受影响的阶段；如果 design_skipped 为 true，则自动排除 design。

1. 使用 question 工具向用户确认受影响阶段（参照「确认机制 → 迭代影响范围确认」格式）。
2. 等待用户确认。 用户可以增删阶段。

- 如果用户选择"需要调整"或输入调整意见：根据反馈调整 affectedstages 列表，再次使用 question 工具请求确认。 - 用户确认后：更新 .dwf/state.json： ``json { "currentstep": "iteration", "projectname": "<项目名称>", "iterationcount": <当前值>, "designskipped": <当前值>, "selectedplan": <当前值>, "iteration": { "name": "<type>-<描述>", "dir": "07-需求迭代/<date>-<type>-<描述>", "affectedstages": ["<阶段1>", "<阶段2>", ...], "currentsubstep": "<第一个受影响阶段>", "confirmedstages": [] }, "createdat": "<保持不变>", "updated_at": "<当前时间>" } ``

迭代步骤 2-N：逐步确认受影响阶段

对于 affectedstages 中的每个阶段，严格按照列表顺序，逐一执行（若 affectedstages 为空，跳过本步骤，直接进入迭代最终步骤）：

1. 根据当前 iteration.current_substep，读取已确认阶段和初始流程阶段文档作为上下文，生成该阶段的迭代文档。
2. 按照 references/ 中对应模板生成文档，保存在 {iteration.dir}/{阶段子目录}/{文件名} 下（阶段子目录映射见下表）。
3. 使用 question 工具向用户展示迭代文档并请求确认（参照「确认机制 → 阶段文档确认」格式，header 为"迭代文档审阅"）。技术方案阶段同样需提供 ≥2 个方案供用户选择。
4. 等待用户确认。

- 如果用户选择"需要修改"或输入修改意见：直接修改对应文档，更新 updatedat，并再次使用 question 工具请求确认。 - 用户确认后： - 将该阶段添加到 iteration.confirmedstages。 - 如果该阶段为 plans，将用户选定的方案写入 state.json 的 selectedplan。 - 推进 iteration.currentsubstep 到 affectedstages 中的下一个阶段。 - 更新 updatedat。 - 如果还有下一个受影响阶段，回到步骤 1 继续处理。 - 如果所有受影响阶段已确认，进入迭代最终步骤。

迭代最终步骤：实施变更

1. 所有受影响阶段的文档已确认。
2. 读取 references/coding_standards.md。
3. 读取本次迭代已确认的 技术方案/ 与 实现清单/（位于 iteration.dir 下，若该阶段受影响）作为实施依据；未受影响的阶段沿用主目录（04-技术方案/、05-实现清单/）文档。在 06-code/ 中实施变更。迭代实施必须只改本次确认的受影响范围，不顺手改进无关代码。
4. 完成后，更新 .dwf/state.json：

- 递增 iterationcount。 - 清除 iteration 子对象。 - 将 currentstep 设回 "code"。 - 更新 updated_at。

1. 总结迭代所做的变更及后续事项。

阶段到迭代子目录的映射

迭代目录示例

07-需求迭代/
├── 2026-06-24-bugfix-修复样式问题/
│   ├── 需求文档/
│   │   └── 需求文档.md
│   └── 实现清单/
│       └── 实现清单.md
└── 2026-06-25-feat-新增下载按钮/
    ├── 需求文档/
    │   └── 需求文档.md
    ├── 需求拆解文档/
    │   └── 需求拆解文档.md
    ├── 技术方案/
    │   └── 技术方案.md
    └── 实现清单/
        └── 实现清单.md

恢复

当技能被触发且 .dwf/state.json 已存在时，首先执行阶段 0 自检，然后读取状态并从相应阶段恢复。不要重新初始化或重启工作流。

• 如果状态为 requirements，展示需求文档，使用 question 工具请求确认。
• 如果状态为 design，展示设计稿信息，使用 question 工具请求确认。
• 如果状态为 breakdown，展示需求拆解文档，使用 question 工具请求确认。
• 如果状态为 plans，展示技术方案，使用 question 工具请求用户选择方案。
• 如果状态为 todos，展示实现清单，使用 question 工具请求确认。
• 如果状态为 code，检查 05-实现清单/实现清单.md：若有未完成任务，从中断处恢复执行；若所有任务已完成（已进入过迭代），则项目处于稳定状态，等待用户提出新需求变更并进入迭代流程。
• 如果状态为 iteration，读取 iteration 子对象：

- 确定 iteration.current_substep 指向的受影响阶段。 - 如果该阶段的文档已生成，展示文档并使用 question 工具请求确认。 - 如果该阶段的文档尚未生成，生成文档并使用 question 工具请求确认。 - 用户确认后，推进到下一个受影响阶段或进入实施。

• 如果状态为 done，使用 question 工具询问用户后续操作（参照工作流完成格式）。

重新开始

如果用户想从头开始（一个全新的项目或需求），必须先进行二次风险告知与确认：

1. 使用 question 工具向用户进行二次风险确认（参照「确认机制 → 新项目风险确认」格式），明确告知将永久删除 .dwf/ 目录及所有文档目录（01-需求文档/、02-设计稿/、03-需求拆解文档/、04-技术方案/、05-实现清单/、06-code/、07-需求迭代/）及其全部文件，且操作不可撤销。
2. 等待用户二次确认。

- 如果用户选择"取消，保留现有项目"或输入取消意向：不删除任何内容，回到当前工作流。 - 只有在用户明确选择"确认删除并重启"后，才删除上述目录，然后从阶段 1 开始。

在用户二次确认之前，不得删除任何文件或目录。

护栏

不可违反的规则

1. 永不跳过阶段。 如果用户说"直接开始写代码"或"这只是个小 bug"，你必须解释工作流要求先走流程，然后引导进入正确的阶段或迭代流程。

1. 永不自动推进。 每个阶段转换都必须使用 question 工具获取用户确认。用户选择"确认"选项或通过自定义输入明确确认后才能推进。如果没有收到确认，停下等待。

1. 永不直接修改代码。 当项目已有代码（current_step 为 code 或 done）时，对代码的任何修改必须通过迭代流程。这包括：bug 修复、小幅调整（颜色、文案、间距等）、配置变更、依赖更新、重构、性能优化——无论变更多小，都必须走迭代。

1. 永不跳过确认直接行动。 即使用户请你"确认是否是 bug"，你的回答只能是"是/否及分析"，不得附带代码修改。如需修改代码，必须先进入迭代流程。

1. 永不未经询问就覆盖。 如果文档目录中已存在文档，向用户展示现有内容，询问是保留、修改还是替换。修改时直接覆盖原文件，不创建新版本。

1. 迭代时只生成受影响阶段的文档。 不要为未变更的阶段重新生成文档。

1. 迭代时逐步确认，不要批量确认。 迭代中的每个受影响阶段必须逐一确认后才能进入下一个。

1. 迭代断点恢复时必须从当前阶段继续。 恢复时从 iteration.current_substep 指向的阶段继续，不要跳过未确认的阶段。

1. 技术方案必须提供至少 2 个方案。 阶段 4（以及迭代中的 plans 阶段）必须生成 ≥2 个并列方案，由用户使用 question 工具选定其一后才能推进。

1. 启动新项目必须二次确认。 当用户选择"启动新项目"或请求重新开始时，必须先用 question 工具进行风险告知（列出将被永久删除的目录、说明操作不可撤销），由用户二次确认后才能删除任何文件。在二次确认之前，不得删除任何内容。

1. 永不使用英文输出。 与用户的文字交互、question 工具的选项和标题、所有阶段生成的文档内容，一律使用中文。代码、文件路径、技术术语等无法翻译的内容除外。