---
name: "visual-spec"
description: "将原始需求分析为可评审的视觉规格，并生成相关产物。当用户运行 /vspec:new 进行分析或运行 /vspec:verify 生成模型与原型时调用。"
---

# Visual Spec Skill（中文）

基于用户输入分析视觉规格，把简短的业务请求转化为结构化的需求输出。

## 何时使用

在以下情况调用本 Skill：
- 业务侧给出的需求描述非常简略。
- 用户运行 `/vspec:new` 开始新的需求分析流程。

## 本 Skill 定义的内容

- 使用“场景驱动拆解”的方式补齐细节。
- 设计数据模型。
- 基于补齐后的细节生成 UI 原型。
- 以可视化/结构化形式生成业务逻辑细节。

## Commands

### `/vspec:new`

用于创建一轮新的需求分析会话。

流程：
0. 确保 `/docs/` 存在，并确保子目录存在：
   - `/docs/legacy/`
   - `/docs/current/`
   - `/docs/refine/`
   - `/docs/dependencies/`
   - 不要创建 `/docs/change/`（已废弃）
0.2 若用户在命令参数中传入 `lang=<en|zh|ja>`，则将 `/scheme.yaml` 的 `selected.language` 设置为该值（只更新该字段，其他字段与格式保持不变；`zh-CN` 视为 `zh` 的别名）。
0.5 尽早创建可编辑的项目约束文件，便于用户提前调整（若已存在则不得覆盖）：
   - 若缺失则创建 `/scheme.yaml`（包含原型选栈 + catalog）
   - 若缺失则创建 `/prototype_ui_convention.md`（与 `/scheme.yaml` 同级）
1. 提示用户输入原始需求。
2. 当用户按下回车，将输入视为原始需求来源。
3. 加载提示词文件 `prompts/vspec_new/background.md`。
4. 使用该提示词分析需求并扩展业务背景。
5. 将原始需求与背景分析写入 `/specs/background/original.md`。
5.2 同时将 `original.md` 中的“待确认问题/Open Questions/要確認事項”抽取并写入统一问答存储：
   - JSON：`/specs/background/questions.json`
   - Markdown：`/specs/background/questions.md`（从 questions.json 导出，条目逐条一致）
   - 即使“待确认问题”小节缺失/为空，也必须创建两份文件（questions.json 必须是合法 JSON，`items: []` 且 `meta.total=0`）。
5.5 同时生成交互式问答页面：`/specs/background/question_and_answer.html`（单文件 HTML，内联 CSS/JS），用于回答并回写。
   - 若该文件已存在：不得覆盖、不得重复生成，直接复用现有文件。
   - 若该文件不存在：才生成一次；模板来源为本 Skill 内置模板 `prompts/vspec_new/question_and_answer.html`（只读读取模板并写入目标路径）。
   - 禁止在项目中创建 `prompt/` 或 `prompts/` 目录；不得向 `prompts/**` 写入任何文件。
6. 提示用户回答“待确认问题/Open Questions/要確認事項”章节中的问题（按所选语言对应章节标题），并要求通过 `/specs/background/question_and_answer.html` 完成（在页面中选择 `/specs/background/original.md`，填写并保存回写）。
   - 必须区分“必答题（priority=required）”与“选答题（priority=optional）”：
     - 必答题：影响范围/规则/验收的关键口径；未回答将阻塞后续生成
     - 选答题：不影响需求分析细节推进，但仍建议后续补齐（可推迟作答，例如法律文书全文、协议条款、计算公式、模板样例等）
   - 然后必须暂停并等待用户回复“继续/continue/続けて”（表示必答题已完成或同意继续）。不得继续加载后续提示词或生成后续产物（不得越过必答问答直接进入 stakeholders/roles/terms 等阶段）。用户明确回复后再进入下一步。
7. 用户回复后，加载 `prompts/vspec_new/stakeholders.md` 分析干系人。
8. 将干系人结果写入 `/specs/background/stakeholder.md`（markdown 表格）。
9. 加载 `prompts/vspec_new/roles.md` 分析系统用户角色（直接用户）及其工作任务。
10. 将角色结果写入 `/specs/background/roles.md`。
11. 加载 `prompts/vspec_new/terms.md` 抽取关键术语与定义。
12. 将术语结果写入 `/specs/background/terms.md`（markdown 表格）。
13. 加载 `prompts/vspec_new/flows.md` 分析业务流程并生成 PlantUML 泳道图。
14. 将图写入 `/specs/flows/*.puml`。
15. 加载 `prompts/vspec_new/scenarios.md` 按节点组合枚举业务场景。
16. 将场景结果写入 `/specs/background/scenarios.md`（markdown 表格）。
17. 加载 `prompts/vspec_new/details_pre_post.md` 创建按节点拆分的详情目录，并为每个节点生成 `pre_post.md`。
18. 加载 `prompts/vspec_new/details_constraints.md` 为每个节点生成 `constraints.md`。
19. 加载 `prompts/vspec_new/details_variations.md` 为每个节点生成 `variations.md`。
20. 加载 `prompts/vspec_new/details_boundaries.md` 为每个节点生成 `boundaries.md`。
21. 加载 `prompts/vspec_new/details_symmetry.md` 为每个节点生成 `symmetry.md`。
22. 确保按节点拆分的输出都写到 `/specs/background/scenario_details/`。
23. 加载 `prompts/vspec_new/dependencies.md` 分析外部依赖系统。
24. 将依赖结果写入 `/specs/background/dependencies.md`。
25. 加载 `prompts/vspec_new/functions.md` 生成按模块与外部依赖系统分组的功能/特性清单。
26. 将功能清单产物写入 `/specs/functions/`：
   - `core.md`：核心系统功能清单表
   - `<system_key>.md`：每个外部依赖系统的功能清单表
   - `functions.json`：统一的结构化功能清单数据源
   - `functions.html`：功能清单阅读页（仅在缺失时创建，必须逐字节复制内置模板 `prompts/vspec_new/functions.html`）
27. 加载 `prompts/vspec_new/questions.md` 生成问题清单与所需业务材料清单。
28. 将问题清单写入 `/specs/background/questions.md`（markdown 列表）。
29. 加载 `prompts/harness/new/post_new_verify.md` 验证 functions 与 scenario_details 是否完备（登录/配置/主数据维护/审批等）。若输出了问题列表，则提示问题并立即结束。
30. 返回结构化分析结果，并进入下一步需求设计流程。

### `/vspec:interview`

用于生成访谈用户的大纲与调查问卷（Markdown），覆盖系统建设目的、目标、用户群体、场景、要解决的问题、使用频率等关键问题，并以“判断题/选择题”为主。

流程：
1. 加载 `prompts/vspec_interview/interview.md`。
2. 生成问卷并写入：`/docs/current/interview_questionnaire.md`。

### `/vspec:i-word`

用于生成调查问卷的 Word 版本（Word 可打开的单文件 `.docx`，HTML 格式）。

流程：
1. 若 `/docs/current/interview_questionnaire.md` 不存在：停止并提示先运行 `/vspec:interview`。
2. 加载 `prompts/vspec_interview/interview_word.md`。
3. 将输出写入：`/docs/current/interview_questionnaire.docx`。

### `/vspec:refine`

用于基于 `/docs/refine/` 下的补充/澄清材料，或基于命令参数提供的一个/多个输入文件或目录，对需求进行补充与更新。

流程：
0. 确保 `/specs/details/` 存在且非空；若缺失则停止并提示用户先运行 `/vspec:detail`。
1. 读取 refine 输入：
   - 若命令参数提供了路径，将其视为 refine 输入源（文件/目录）。
   - 否则：
     - 优先读取 `/docs/refine/refine.md`（如存在）。
     - 若 `/docs/refine/refine.md` 不存在：先提示用户在提示词窗口/对话窗口粘贴本次需要修改的内容（变更点或完整新口径均可），并将该粘贴内容视为 refine 输入继续执行。
     - 可按需读取 `/docs/refine/` 作为补充材料（仅在被引用/明确需要时读取；若存在优先读 `/docs/refine/file_list.md`；否则按文件名顺序读取）。
2. 若 `prompts/vspec_refine/refine.md` 不存在：立即结束，不执行任何写入。
3. 加载 `prompts/vspec_refine/refine.md` 应用补充信息、更新需求口径并同步更新受影响的产物。
4. 将 refine 结果追加到 `/specs/background/original.md`，并更新受影响的 `/specs/details/` 与 `/specs/prototypes/`；若 `/specs/backend/` 已存在且非空，则同步更新受影响的后端代码。

### `/vspec:refine-q`

用于基于“已回答的问题”补充与更新需求。

流程：
1. 若 `/specs/background/questions.md` 不存在：立即结束，不执行任何写入。
2. 若 `/specs/background/questions.md` 中不存在待回答的问题：立即结束，不执行任何写入。
3. 读取 `/specs/background/questions.md` 并选择已回答项。
4. 加载 `prompts/vspec_refine/refine_q.md` 将答案合并进最新口径。
5. 将结果追加到 `/specs/background/original.md`。
6. 更新 `/specs/background/questions.md`，标记本次运行中已视为回答的条目：
   - 用 `<mark>...</mark>` 包裹 `回答` 与 `状态`，以高亮已回答项。

### `/vspec:more-q`

用于在现有问题清单基础上，补充更多“待确认问题”，并追加到 `/specs/background/questions.md` 末尾。

流程：
1. 若 `/specs/background/questions.md` 不存在：停止并提示用户先运行 `/vspec:new` 生成基础问题清单。
2. 加载 `prompts/vspec_more_q/more_q.md` 生成更多问题（必须去重，并延续编号）。
3. 将新增条目追加到 `/specs/background/questions.md`（不得重写既有条目）。
4. 输出明确指引：让用户按编号填写答案，然后执行 `/vspec:refine-q` 合并答案进入 `original.md`。

### `/vspec:detail`

用于基于功能清单展开需求细节。

语言：
- 读取 `/scheme.yaml` 的 `selected.language`（支持 `en`、`zh`、`ja`；若缺失/非法则按 `en` 处理；`zh-CN` 视为 `zh` 的别名）。
- `/specs/` 下生成的规格文档必须统一使用所选语言（标题、表格、字段说明、状态文案、按钮文案、提示语等）。

流程：
1. 读取 `/specs/functions/*` 中的功能清单。
   - 必须遍历 `/specs/functions/` 目录下所有文件的每一行功能（不仅是 core.md），避免遗漏任何模块/外部系统相关功能点。
2. 尽可能读取可用的上下文产物：`/specs/background/*`、`/specs/flows/*.puml`、`/specs/background/scenario_details/`、`/specs/background/roles.md`，以及已有的 `/specs/models/*.md`（若存在）。
3. 对每个功能（页面或非页面任务），先判断哪些详情产物真正涉及，再只生成涉及的部分；对不涉及的部分不得生成空文档。
   - 覆盖性要求（必须）：对遍历到的每个功能点，必须至少产出 `rbac.md` 与 `data_permission.md`（按规则写入对应路径）；若因信息不足无法产出，必须输出可见错误并停止，而不是静默跳过。
   - Step 类型要求（必须）：你必须从功能行的“说明”中解析 step 的类型（端=Web/Mobile/Web+Mobile/Backend/Job），并生成对应的逻辑细节文档；不得跳过逻辑部分：
     - 对 `端=Web` / `端=Mobile` / `端=Web+Mobile`：必须生成 `page_load.md` 与 `interaction.md`（页面加载 + 交互逻辑是必需的）。
     - 对 `端=Backend`：必须生成 `service_logic.md`（服务端逻辑：输入输出、规则、状态、接口/事件、错误与幂等/一致性）。
     - 对 `端=Job`：必须生成 `job_logic.md`（作业逻辑：触发/频率、数据范围、重试/补偿、可观测性、失败处理）。
   - 始终生成基础文档：
     - `rbac.md`：RBAC 权限下沉到页面区域与控件级。
     - `data_permission.md`：数据权限规则与范围。
   - 仅页面类功能生成：
     - `page_load.md`：页面加载逻辑。
      - `interaction.md`：页面交互逻辑。
     - `validation_matrix.md`：矩阵形式的校验逻辑（仅提交类页面/动作；若页面无 submit/save/approve/reject/cancel/change 等动作则跳过）。
     - `post_submit_check.md`：提交后检查（若页面存在提交）。
     - `post_submit_processing.md`：提交后处理（若页面存在提交）。
     - `post_submit_navigation.md`：提交后返回与跳转（若页面存在提交）。
   - 条件生成（仅当该功能的逻辑/场景/模型/依赖涉及时才生成）：
     - `logging_matrix.md`：操作/审计日志（仅在业务需要保留变更历史、合规审计或不可抵赖时生成，否则跳过）。
     - `decision_matrix.md`：决策矩阵（用于状态机下各状态/角色的操作可用性）。
     - `notification_matrix.md`：通知（存在通知需求时生成）。
     - `mq.md`：MQ topic/event/消息 schema/可靠性细节（存在异步事件、队列或跨系统事件时生成）。
     - `file_import.md`：导入（存在导入入口/需求时生成）。
     - `file_export.md`：导出（存在导出入口/需求时生成）。
     - `formula.md`：计算公式与指标语义（存在计算/指标时生成）。
     - `expression_tree.md`：表达式树（HTML）（存在多层嵌套分支逻辑时生成）。
     - `code_rules.md`：编号/编码生成规则（存在编码生成时生成）。
     - `payment.md`：支付与退款细节（存在支付/退款/结算/对账等资金链路时生成）。
     - `auth.md`：账号与登录细节（存在非 SSO 的登录/账号/密码相关功能时生成）。
     - `judgemental_matrix.md`：判定矩阵（2+ 因素共同决定结果的多因子分支时生成）。
   - 模块级（每模块最多生成一次，且仅当涉及时生成）：
     - `timeline.md`：时间轴（HTML）用于整体流程影响分析（存在跨较长时间跨度影响决策的逻辑，如生效/失效、截止期、宽限期、跨天规则等时生成）。
      - `state_machine.md`：状态列表 + 迁移 + PlantUML 状态图（模块整体，不按功能拆分）。
     - `nfp.md`：模块非功能需求总结（模块整体，不按功能拆分）。
     - `cron_job.md`：模块定时任务总结（模块整体，不按功能拆分）。
4. 仅写入生成的（涉及的）详情文档：
   - 单功能：`/specs/details/<module_slug>/<logic_type>/<function_slug>.(md|html)`
   - 模块级：`/specs/details/<module_slug>/<logic_type>/<module_slug>.(md|html)`
5. 加载 `prompts/vspec_detail/index.md` 生成单页阅读入口：`/specs/details/reader.html`
   - 左侧：按 `/specs/details/` 目录结构生成目录树
   - 右侧：以 Markdown 渲染方式阅读详情内容
   - 遇到 PlantUML 必须渲染成图（不得展示源码文本）

### `/vspec:doc`

用于生成“需求详细文档”的 Word 文件（Word 可打开的单文件 `.doc`，HTML 格式），并写入到 `/docs/current/` 目录下。

语言：
- 读取 `/scheme.yaml` 的 `selected.language`（支持 `en`、`zh`、`ja`；若缺失/非法则按 `en` 处理；`zh-CN` 视为 `zh` 的别名）。
- 生成的 Word 文档必须统一使用所选语言（标题、章节名、字段名、表头与说明文字）。

流程：
1. 确保 `/docs/current/` 存在。
2. 尽可能读取已有产物作为输入：
   - 需求口径：`/specs/background/original.md`
   - 功能清单：`/specs/functions/*`
   - 需求详情：`/specs/details/**`
   - 角色与权限：`/specs/background/roles.md`、`/specs/details/**/rbac.md`
   - 数据权限：`/specs/details/**/data_permission.md`
   - 场景与流程：`/specs/background/scenarios.md`、`/specs/background/scenario_details/**`、`/specs/flows/*.puml`
   - 外部依赖：`/specs/background/dependencies.md`
   - 数据模型：`/specs/models/*.md`
3. 加载 `prompts/vspec_doc/doc.md`，生成 Word 可打开的单文件 HTML 文档。
4. 将输出写入：`/docs/current/requirement_detail.docx`。

### `/vspec:verify`

用于生成模型与可运行原型，用于快速验证与评审。

语言：
- 读取 `/scheme.yaml` 的 `selected.language`（支持 `en`、`zh`、`ja`；若缺失/非法则按 `en` 处理；`zh-CN` 视为 `zh` 的别名）。
- `/specs/models/` 模型文档与原型界面所有文案必须统一使用所选语言。

流程：
0. 确保 `/specs/details/` 存在且非空；若缺失则立即停止并提示前置条件：“请先执行 /vspec:detail 生成 /specs/details/，再执行 /vspec:verify”。
1. 若 `/specs/background/questions.md` 存在且仍有未回答的问题，先要求用户回答再继续（允许逐条跳过，但必须保证不存在“未处理”的问题）。
2. 加载 `prompts/vspec_verify/model.md` 生成数据模型。
3. 将模型文件写入 `/specs/models/*.md`。
4. 基于 functions/details/models/roles 生成可运行的页面原型；原型技术栈由 `/scheme.yaml` 选择（若缺失则按默认值自动创建）。
   - 加载 `prompts/vspec_verify/prototype.md` 执行原型生成规则（必须遵循 `scheme.yaml` 技术栈；禁止只生成 html-only）。
5. 将原型工程写入 `/specs/prototypes/`。
6. 加载 `prompts/harness/verify/post_verify_stack_verify.md` 检查原型前端工程是否严格符合 `/scheme.yaml` 中选择的前端栈；若输出了问题列表，则提示问题并立即结束。
7. 加载 `prompts/vspec_verify/validation.md` 生成场景验证网页。
8. 将验证页面写入 `/specs/prototypes/`，并提供 `scenario.html` 作为访问入口。
9. 加载 `prompts/vspec_verify/entries.md` 生成全功能入口页，并写入 `/specs/prototypes/entries.html`（禁止在菜单/Header 内提供入口）。
10. 加载 `prompts/harness/verify/post_verify_mobile_selection_check.md` 检查移动端数据选择是否使用“选择页（List）选择→返回回填”，而不是下拉框 Select；若输出了问题列表，则提示问题并立即结束。
11. 加载 `prompts/harness/verify/post_verify_price_format_check.md` 检查价格/金额格式是否统一（右对齐、两位小数、千位分隔符）；若输出了问题列表，则提示问题并立即结束。
12. 加载 `prompts/harness/verify/post_verify_click_check.md` 检查是否存在“按钮/链接点击无反应”的情况；若输出了问题列表，则提示问题并立即结束。
13. 加载 `prompts/harness/verify/post_verify_verify.md` 检查原型是否覆盖关键约束（移动端/审批/CRUD/布局/登录/RBAC 等）。若输出了问题列表，则提示问题并立即结束。

### `/vspec:qc`

用于对 `/specs/` 下生成的需求产物进行质量检查。

Note：Pro 版支持更广泛的质量检测能力（例如更完整的原型/实现后校验项等），需要付费开通。

语言：
- 读取 `/scheme.yaml` 的 `selected.language`（支持 `en`、`zh`、`ja`；若缺失/非法则按 `en` 处理；`zh-CN` 视为 `zh` 的别名）。
- `/specs/qc_report.md` 报告必须统一使用所选语言。

流程：
1. 读取内置标准 `prompts/vspec_qc/quality_standard.md`。
2. 若项目 `qc/` 下存在“需求质量错误簿”，则据此生成/更新项目根目录的 `quality_standard.md`。
3. 若项目根目录存在 `quality_standard.md`，则将其作为补充/覆盖标准合并。
4. 加载 `prompts/vspec_qc/qc.md` 生成不符合项清单。
5. 将报告写入 `/specs/qc_report.md`。

### `/vspec:accept`

用于生成验收测试用例。

语言：
- 读取 `/scheme.yaml` 的 `selected.language`（支持 `en`、`zh`、`ja`；若缺失/非法则按 `en` 处理；`zh-CN` 视为 `zh` 的别名）。
- `/test/验收用例/` 下生成的验收产物必须统一使用所选语言。

流程：
1. 读取 `/specs/functions/*`、`/specs/background/scenarios.md`、`/specs/background/scenario_details/`、`/specs/background/roles.md`、`/specs/models/*.md`。
2. 确保 `/test/` 存在，并确保子目录存在：
   - `/test/验收用例/`
   - `/test/单元测试/`
   - `/test/集成测试/`
   - `/test/playwright/`
3. 复制内置用例阅读器 `prompts/vspec_testcase_reader/testcase_reader.html` 到 `/test/testcase_reader.html`（覆盖写入）。该模板已内置中日英三语切换功能。
4. 加载 `prompts/vspec_accept/accept.md` 生成“场景驱动”的验收用例（JSON），覆盖主流程、异常、边界、权限与数据范围。
5. 将验收用例写入 `/test/验收用例/acceptance_cases.json`。

### `/vspec:i-test`

用于生成单元测试与集成测试用例（JSON），用例从场景与可实现粒度的细节规格中推导。

语言：
- 读取 `/scheme.yaml` 的 `selected.language`（支持 `en`、`zh`、`ja`；若缺失/非法则按 `en` 处理）。
- JSON 中所有用例标题与描述必须统一使用所选语言。

流程：
1. 读取 `/specs/functions/*`、`/specs/background/scenarios.md`、`/specs/background/scenario_details/`、`/specs/background/roles.md`、`/specs/details/`、`/specs/models/*.md`（如有）。
2. 确保 `/test/` 存在，并确保子目录存在：
   - `/test/单元测试/`
   - `/test/集成测试/`
3. 复制内置用例阅读器 `prompts/vspec_testcase_reader/testcase_reader.html` 到 `/test/testcase_reader.html`（覆盖写入）。该模板已内置中日英三语切换功能。
4. 加载 `prompts/vspec_i_test/i_test.md` 生成单元测试用例（JSON），写入 `/test/单元测试/unit_test_cases.json`。
5. 再次加载 `prompts/vspec_i_test/i_test.md` 生成集成测试用例（JSON），写入 `/test/集成测试/integration_test_cases.json`。

### `/vspec:script`

用于基于 JSON 测试用例生成 Playwright 脚本。

流程：
1. 读取以下 JSON 用例（存在则读取）：
   - `/test/验收用例/acceptance_cases.json`
   - `/test/集成测试/integration_test_cases.json`
2. 确保 `/test/playwright/` 存在。
3. 加载 `prompts/vspec_script/script.md` 生成 Playwright 测试脚本。
4. 写入输出：
   - `/test/playwright/acceptance.spec.ts`
   - `/test/playwright/integration.spec.ts`

### `/vspec:append-test`

用于基于验收用例与规格生成自动化测试代码。

语言：
- 读取 `/scheme.yaml` 的 `selected.language`（支持 `en`、`zh`、`ja`；若缺失/非法则按 `en` 处理；`zh-CN` 视为 `zh` 的别名）。
- 测试用例标题/描述尽量遵循所选语言。

流程：
1. 读取 `/test/验收用例/acceptance_cases.json`、`/specs/functions/*`、`/specs/details/`，并识别仓库中已有的测试框架。
2. 加载 `prompts/vspec_test/test.md`，按既有框架与约定生成自动化测试。
3. 将测试代码写入项目测试目录（若不存在标准目录则写入 `/tests/`），并确保能通过已有脚本运行。
4. 加载 `prompts/harness/append-test/post_append_test_coverage_check.md` 检查测试覆盖率是否足够完整；若输出了问题列表，则继续执行下一步。
5. 若存在问题列表：基于缺失项再次运行一次 `/vspec:append-test`（只补缺失项），然后再次运行覆盖检查。
6. 若第二次覆盖检查仍输出问题列表：提示问题并立即结束。
7. 本指令用于补齐测试代码以提升覆盖率，不负责执行测试命令（例如 mvn test）。

### `/vspec:impl`

用于基于 specs 生成前后端集成实现代码。

流程：
1. 读取 `/specs/functions/*`、`/specs/details/`、`/specs/models/*.md`、`/specs/background/dependencies.md`，并识别当前前后端技术栈与代码约定。
2. 加载 `prompts/vspec_impl/implement.md` 并按后端优先实现：先在 `/specs/backend/` 生成可运行后端工程（health check + 核心 API/service），再在后端 API 可用后生成前端集成对接。
3. 仅允许在 `/specs/` 下写代码，并尽量保持差异最小且可审查；后端必须在 `/specs/backend/`，原型前端在 `/specs/prototypes/`。
4. 加载 `prompts/harness/impl/post_impl_verify.md` 检查后端是否符合 MVC 架构且测试覆盖是否完整；若输出了问题列表，则提示问题并立即结束。

### `/vspec:upgrade`

用于基于 `/docs/` 下材料（`/docs/legacy` 遗留系统、`/docs/current` 新输入）进行升级/改造分析，并按 `/vspec:new` 相同结构重新生成 `/specs/` 产物。

语言：
- 读取 `/scheme.yaml` 的 `selected.language`（支持 `en`、`zh`、`ja`；若缺失/非法则按 `en` 处理；`zh-CN` 视为 `zh` 的别名）。
- 重新生成/更新的 `/specs/**` 产物必须统一使用所选语言。

流程：
1. 确保 `/docs/current/file_list.md` 入口文件存在；若缺失则按模板生成。
2. 读取 `/docs/current/file_list.md`，再按顺序读取 `/docs/` 下列出的输入（通常 `/docs/legacy/*`、`/docs/current/*`，可选 `/docs/templates/*`、`/docs/texts/*`、`/docs/assets/*`）并抽取结构化信息（功能、依赖、UI 风格、角色/权限、技术规格）。另外，必须递归扫描 `/docs/legacy/` 及其子目录下的文档，作为原始输入资料（即使尚未被 `file_list.md` 显式列出）；当发现 `file_list.md` 未覆盖的 legacy 文件时，先把它们追加写入 `/docs/current/file_list.md`，再读取并参与抽取。
3. 若 `/specs/background/original.md` 已存在，则将其视为当前需求口径并作为 diff 基线（继承/新增/变更/废弃）。
4. 加载 `prompts/vspec_upgrade/upgrade.md`，按 `/vspec:new` 产物约定生成/更新 `/specs/`。
5. 将抽取到的技术规格同步到 `/scheme.yaml`，供 `/vspec:verify` 与 `/vspec:impl` 使用。

### `/vspec:plan`

用于把需求拆解为故事地图并进行估算与排期。

语言：
- 读取 `/scheme.yaml` 的 `selected.language`（支持 `en`、`zh`、`ja`；若缺失/非法则按 `en` 处理；`zh-CN` 视为 `zh` 的别名）。
- `/specs/plan/plan_estimate.md` 与 `/specs/plan/plan_schedule.html` 必须统一使用所选语言。

流程：
1. 读取 `/specs/functions/*`、`/specs/background/roles.md`、`/specs/background/scenarios.md`、`/specs/details/`、`/specs/background/dependencies.md`。
2. 加载 `prompts/vspec_plan/estimate.md`，按功能清单生成估算。
3. 将估算写入 `/specs/plan/plan_estimate.md`。
4. 加载 `prompts/vspec_plan/schedule.md` 生成排期与交付地图。
5. 将排期 HTML 写入 `/specs/plan/plan_schedule.html`。

### `/vspec:mrd`

用于生成市场与产品定位分析包（MRD）：市场环境、竞品分析、用户定位、产品设计。

流程：
1. 确保 `/docs/market/` 存在。
2. 读取可用输入：`/specs/background/original.md`、`/specs/background/roles.md`、`/specs/background/terms.md`、`/specs/background/scenarios.md`、`/specs/flows/*.puml`、`/specs/background/dependencies.md`，以及（如存在）`/specs/functions/*`。
3. 加载 `prompts/vspec_mrd/mrd.md`。
4. 分别写入：
   - `/docs/market/market.md`
   - `/docs/market/competitors.md`
   - `/docs/market/users.md`
   - `/docs/market/product_design.md`

## Prompt Files

- `prompts/vspec_new/background.md`：`/vspec:new` 接收原始需求后立即使用的提示词。
- `prompts/vspec_interview/interview.md`：`/vspec:interview` 使用的提示词，用于生成 `/docs/current/interview_questionnaire.md`。
- `prompts/vspec_interview/interview_word.md`：`/vspec:i-word` 使用的提示词，用于生成 `/docs/current/interview_questionnaire.docx`（Word 可打开的单文件 HTML）。
- `prompts/vspec_new/stakeholders.md`：用户回答 `待确认问题` 后生成 `/specs/background/stakeholder.md` 的提示词。
- `prompts/vspec_new/roles.md`：生成 `/specs/background/roles.md` 的提示词。
- `prompts/vspec_new/terms.md`：生成 `/specs/background/terms.md` 的提示词。
- `prompts/vspec_new/flows.md`：生成 `/specs/flows/*.puml` 的提示词。
- `prompts/vspec_new/scenarios.md`：生成 `/specs/background/scenarios.md` 的提示词。
- `prompts/vspec_new/details_pre_post.md`：生成按节点拆分的 `pre_post.md` 的提示词。
- `prompts/vspec_new/details_constraints.md`：生成按节点拆分的 `constraints.md` 的提示词。
- `prompts/vspec_new/details_variations.md`：生成按节点拆分的 `variations.md` 的提示词。
- `prompts/vspec_new/details_boundaries.md`：生成按节点拆分的 `boundaries.md` 的提示词。
- `prompts/vspec_new/details_symmetry.md`：生成按节点拆分的 `symmetry.md` 的提示词。
- `prompts/vspec_new/dependencies.md`：生成 `/specs/background/dependencies.md` 的提示词。
- `prompts/vspec_new/functions.md`：生成 `/specs/functions/` 的提示词。
- `prompts/vspec_new/questions.md`：生成 `/specs/background/questions.md` 的提示词。
- `prompts/vspec_refine/refine.md`：`/vspec:refine` 使用的提示词。
- `prompts/vspec_refine/refine_q.md`：`/vspec:refine-q` 使用的提示词。
- `prompts/vspec_doc/doc.md`：`/vspec:doc` 使用的提示词，用于生成 Word 可打开的 `.docx`（HTML）需求详细文档到 `/docs/current/`。
- `prompts/vspec_verify/model.md`：生成 `/specs/models/*.md` 的提示词。
- `prompts/vspec_verify/prototype.md`：生成按选栈的可运行原型工程（`/specs/prototypes/`）的提示词（必须遵循 `scheme.yaml`）。
- `prompts/vspec_verify/validation.md`：生成 `scenario.html` 场景评审页的提示词。
- `prompts/vspec_detail/rbac.md`：生成 RBAC 详情的提示词。
- `prompts/vspec_detail/data_permission.md`：生成数据权限详情的提示词。
- `prompts/vspec_detail/page_load.md`：生成页面加载逻辑的提示词。
- `prompts/vspec_detail/interaction.md`：生成页面交互逻辑的提示词。
- `prompts/vspec_detail/index.md`：生成 `/specs/details/reader.html` 单页阅读入口（Markdown/PlantUML 渲染）的提示词。
- `prompts/vspec_detail/index.html`：`/specs/details/reader.html` 的固定 HTML 模板（用于稳定生成：目录树 + Markdown 渲染）。
- `prompts/vspec_detail/timeline.md`：生成时间轴 HTML 的提示词。
- `prompts/vspec_detail/formula.md`：生成公式说明的提示词。
- `prompts/vspec_detail/expression_tree.md`：生成表达式树 HTML 的提示词。
- `prompts/vspec_detail/code_rules.md`：生成编号/编码规则的提示词。
- `prompts/vspec_detail/judgemental_matrix.md`：生成判定矩阵的提示词。
- `prompts/vspec_detail/validation_matrix.md`：生成校验矩阵的提示词。
- `prompts/vspec_detail/post_submit_check.md`：生成提交后检查的提示词。
- `prompts/vspec_detail/post_submit_processing.md`：生成提交后处理的提示词。
- `prompts/vspec_detail/post_submit_navigation.md`：生成提交后跳转规则的提示词。
- `prompts/vspec_detail/mq.md`：生成 MQ 设计的提示词。
- `prompts/vspec_detail/message_queue.md`：生成消息队列设计的提示词。
- `prompts/vspec_detail/cache.md`：生成缓存设计的提示词。
- `prompts/vspec_detail/service_logic.md`：生成 `端=Backend` 功能点的服务端逻辑细节（service logic）的提示词。
- `prompts/vspec_detail/job_logic.md`：生成 `端=Job` 功能点的作业逻辑细节（job logic）的提示词。
- `prompts/vspec_detail/logging_matrix.md`：生成日志矩阵的提示词。
- `prompts/vspec_detail/notification_matrix.md`：生成通知矩阵的提示词。
- `prompts/vspec_detail/nfp.md`：生成非功能需求的提示词。
- `prompts/vspec_detail/file_import.md`：生成导入设计的提示词。
- `prompts/vspec_detail/file_export.md`：生成导出设计的提示词。
- `prompts/vspec_detail/cron_job.md`：生成定时任务设计的提示词。
- `prompts/vspec_accept/accept.md`：生成验收用例的提示词。
- `prompts/vspec_i_test/i_test.md`：生成单元测试/集成测试用例（JSON）的提示词。
- `prompts/vspec_script/script.md`：生成 Playwright 脚本的提示词。
- `prompts/vspec_testcase_reader/testcase_reader.html`：用于阅读 JSON 用例的单文件 HTML。
- `prompts/vspec_test/test.md`：生成自动化测试的提示词。
- `prompts/vspec_impl/implement.md`：生成前后端集成实现的提示词。
- `prompts/vspec_upgrade/upgrade.md`：生成升级/改造规格的提示词。
- `prompts/vspec_plan/estimate.md`：生成估算的提示词。
