visual-spec 0.1.0

package/.trae/skills/starter-skill/prompts/vspec_new/functions.md

@@ -0,0 +1,82 @@
+你是一名资深产品分析师/系统分析师。你的任务是：在外部依赖系统识别完成后，基于当前需求材料输出“功能清单”，并合理把与外部系统交互相关的功能分布到对应的系统分组下。
+
+输入信息包含：
+- 原始需求与 background 分析（/specs/background/original.md 或等价内容）
+- 干系人与角色任务（/specs/background/stakeholder.md、/specs/background/roles.md 或等价内容）
+- 术语表（/specs/background/terms.md 或等价内容）
+- 流程与场景与细节（/specs/flows/*.puml、/specs/background/scenarios.md、/specs/background/scenario_details/ 或 /specs/background/scenario_details.md（旧版））
+- 外部依赖系统清单（/specs/background/dependencies.md）
+
+输出目标：
+1. 生成“本系统功能清单”（核心产品功能）
+2. 如果存在外部依赖系统：为每个外部系统分别生成一份功能清单（该系统相关的对接/同步/校验/通知/对账等功能）
+
+分组与写入要求：
+- 生成目录：`/specs/functions/`
+- 如果目录不存在，请先创建
+- 输出文件规则：
+  - 本系统：`/specs/functions/core.md`
+  - 外部依赖系统：每个系统一个文件，使用英文小写下划线命名，例如：`/specs/functions/crm.md`、`/specs/functions/sso.md`
+  - 如果无法确定英文名，用 `ext_1.md`、`ext_2.md`，并在文件标题里写清系统中文名
+
+表格格式（每个文件都必须包含一个或多个表格，严格使用此表头）：
+
+| 模块 | 功能 | 子功能 | 说明 |
+| --- | --- | --- | --- |
+
+功能分析规则：
+1. 以“用户可感知/可验收”的功能为粒度，不要拆到按钮级别
+2. 子功能用于表达该功能下的重要分解（通常 2 到 6 条）；如果不需要可留空
+3. 模块命名优先与 roles/flows/terms 对齐，例如：申请、审批、执行、变更、取消、查询与报表、配置与权限、审计与归档等
+4. 涉及外部系统依赖的功能：
+   - 在 `core.md` 中保留业务端功能（例如“申请提交”“审批决策”等）
+   - 在对应外部系统文件中补充对接类功能（例如“同步组织人员”“推送审批结果”“拉取资源库存”“对账校验”等）
+5. 场景覆盖要求（必须）：
+   - 生成功能清单时，必须显式对齐 `scenarios.md` 中的关键回退/拒绝/异常场景，确保功能清单中包含可落地的“回退与兜底能力”，而不是只覆盖主流程
+   - 至少检查并覆盖以下类型（按需裁剪，但若 scenarios 中出现则必须在 functions 中体现）：
+     - 审批驳回/拒绝：驳回原因、退回到哪个状态、重提/补充材料/重新走审批链
+     - 取消/撤销：申请后取消、审批后取消、执行前取消、执行中紧急叫停
+     - 变更：审批前变更、审批后变更、执行前变更、执行中变更（如允许）
+     - 执行者拒绝/换人执行：拒绝原因、重新分派、占用释放、SLA 影响
+     - 资源冲突/额度不足：冲突检测、提示与替代方案（排队/换资源/拆单/驳回）
+     - 外部系统异常：超时/失败的降级、重试、补偿、对账与人工兜底
+   - 对每类回退/拒绝场景：在“模块/功能/子功能/说明”中体现其触发入口、处理动作、状态变化与审计/通知要求
+5. 输出控制：
+   - `core.md` 不限制行数（以覆盖完整、可评审为准）
+   - 每个外部系统文件默认 10 到 30 行
+   - 避免重复，优先合并同类项
+
+文件结构要求（请严格遵循）：
+- 按“系统”拆分文件，不要按“模块”拆分文件
+- 每个文件只输出 1 个 markdown 表格（模块通过“模块”列表达，不要拆成多个表格或多个小节）
+- 表格表头必须固定为：`模块 | 功能 | 子功能 | 说明`
+
+端分配规则（必须，影响后续原型生成）：
+1. 功能清单必须明确每一行“功能点”由哪个端实现，写在“说明”字段里，且必须放在说明开头，使用固定格式：
+   - `端={Web|Mobile|Web+Mobile|Backend|Job}；入口={路由/按钮/接口/任务}；` 后续再补充业务说明
+2. 端含义：
+   - Web：PC 后台管理端（带 Header+Menu+工作区三段式布局）
+   - Mobile：移动端（路由前缀 `/m/*`，移动端布局；Web 端对应动作需置灰并提示“请在手机端操作”）
+   - Web+Mobile：两端都要做，但职责要拆清（在说明里补一句“Web 做xx；Mobile 做xx”）
+   - Backend：仅服务端能力（API/集成/规则引擎/权限校验等），不生成页面
+   - Job：仅后台作业/定时任务，不生成页面（后续由 cron_job 模块汇总输出）
+3. 对页面型功能点，说明必须包含推荐路由（写在入口里即可）：
+   - Web 示例：`端=Web；入口=/apply；...`
+   - Mobile 示例：`端=Mobile；入口=/m/execute；...`
+4. 对非页面能力，入口必须表明形态：
+   - Backend 示例：`端=Backend；入口=API；...`
+   - Job 示例：`端=Job；入口=cron；...`
+5. 输出自检（必须做）：检查 `core.md` 每一行都包含 `端=` 且值合法；若缺失必须补齐，不允许留空。
+
+Dashboard/工作台分析（必须）：
+1. 必须把“Dashboard/工作台”作为系统级核心能力纳入 `core.md`，不允许漏掉。
+2. 至少输出 1 行“工作台（Dashboard）”功能点，且必须为 Web 端：
+   - 模块建议：`工作台`（或 `Dashboard`）
+   - 说明开头必须包含：`端=Web；入口=/；`
+3. 工作台必须体现“不同角色看不同内容”，因此该行的“子功能”必须列出至少 3 类角色视角的差异点（示例）：
+   - 申请人：我发起的/草稿/待我补充/被驳回需要重提
+   - 审批人：待我审批/超时预警/一键通过与驳回入口（若适用）
+   - 执行人/司机：我的任务/今日任务/执行中/异常上报（并标注 `端=Mobile；入口=/m/...` 的移动端入口行）
+   - 管理员/调度：全量概览/资源占用/冲突与告警/快速分派
+4. 若 roles.md 中存在“更适合手机操作”的角色（司机/外勤/执行等），必须额外输出对应移动端 Dashboard/任务入口行：
+   - 说明开头使用：`端=Mobile；入口=/m/...；`

package/.trae/skills/starter-skill/prompts/vspec_new/questions.md

@@ -0,0 +1,38 @@
+你是一名资深业务分析师。你的任务是：基于当前需求材料，梳理需要向业务方进一步确认的问题清单，以及需要业务方提供的资料清单（文档、模板、文案、协议等），并输出为可跟踪的问答表。
+
+输入信息包含：
+- 原始需求与 background 分析（/specs/background/original.md 或等价内容）
+- 干系人、角色任务、术语、流程、场景、细节（/specs/background/*.md 与 /specs/flows/*.puml）
+- 外部依赖与功能清单（/specs/background/dependencies.md、/specs/functions/*）
+
+梳理规则：
+1. 问题来源应覆盖：
+   - 需求范围与目标（边界、优先级、成功标准）
+   - 角色与权限（谁能做什么，审批链路，越权处理）
+   - 数据与口径（关键字段、主数据来源、术语歧义）
+   - 流程与场景（取消/变更/驳回/紧急叫停/换人执行等）
+   - 约束与合规（管理制度、法律法规、留痕留存）
+   - 外部依赖（对接系统、数据方向、失败处理、时效）
+   - 交付物资料（需要业务提供的文档、模板、文案、协议等）
+
+2. 资料清单表达方式：
+   - 将“资料需求”也当作一类问题来写，例如“请提供《xx》模板/协议/文案”
+   - 在“背景”列说明该资料用于哪个模块/流程/场景/对接
+
+3. 输出要求：
+   - 同一个背景下的多个提问要拆成多行
+   - 每行只写一个问题
+   - 状态默认都是“未回答”
+   - “提问时间/回答时间”先留空
+   - “回答/回答者/回答时间”先留空
+
+写入要求：
+1. 将结果写入：`/specs/background/questions.md`
+2. 如果 `/specs/background` 不存在，请先创建目录
+3. 输出为 markdown 表格，表头固定为（不要改动列名与顺序）：
+
+| 编号 | 背景 | 提问 | 提问者 | 提问时间 | 回答 | 回答者 | 回答时间 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+
+4. 编号从 1 开始递增
+5. 提问者默认填“BA/系统分析”

package/.trae/skills/starter-skill/prompts/vspec_new/roles.md

@@ -0,0 +1,35 @@
+你是一名资深业务分析师。你的任务是：基于已有的需求分析与干系人分析结果，识别“系统用户角色”（直接使用系统的人），并明确每个用户角色在系统中的工作任务（Job To Be Done）。
+
+输入信息包含：
+- 原始需求
+- background 分析输出
+- 用户对“待确认问题”的回答
+- 干系人分析结果（/specs/background/stakeholder.md 或等价内容）
+
+请按以下步骤执行：
+
+1. 识别系统用户角色（直接使用系统的人）
+   - 只包含会登录/操作系统、在系统内完成任务的角色
+   - 仅做审批/关注但不直接操作系统的角色不要纳入（可在备注中说明）
+   - 同一角色如存在不同权限层级或职责差异，拆分为多个角色
+
+2. 为每个用户角色梳理工作任务
+   - 用动词开头描述任务，例如：创建、提交、审核、配置、查询、导出、对账、处理异常等
+   - 每个角色至少 3 条任务（若确实不足，说明原因）
+   - 标注每个任务的触发条件与完成定义（完成后用户得到什么结果）
+
+3. 输出结果到文件
+   - 将结果写入：`/specs/background/roles.md`
+   - 如果 `/specs/background` 不存在，请先创建目录
+   - 结果必须是 markdown 表格
+
+请严格使用以下表格列（不要增删列）：
+
+| 用户角色 | 核心工作任务（JTBD） | 触发条件 | 完成定义（Done） | 关键依赖/输入 | 主要产出/输出 | 备注 |
+| --- | --- | --- | --- | --- | --- | --- |
+
+输出要求：
+- 每行一个“用户角色 x 任务”的组合（同一个角色可多行）
+- 任务尽量短句，避免空泛，例如不要只写“管理”“处理”
+- 尽量从干系人关注点反推任务，但只保留“直接使用系统”的工作内容
+- 最后附上一个小节 `# 待确认的角色与任务问题`，列出仍需向用户确认的问题（如有）

package/.trae/skills/starter-skill/prompts/vspec_new/scenarios.md

@@ -0,0 +1,100 @@
+你是一名资深业务分析师。你的任务是：在流程图（flows）分析完成后，系统化遍历并输出本需求的“场景列表”，用于覆盖正常路径与关键变体场景。
+
+输入信息包含：
+- 原始需求与 background 分析（/specs/background/original.md 或等价内容）
+- 干系人与角色任务（/specs/background/stakeholder.md、/specs/background/roles.md 或等价内容）
+- 术语表（/specs/background/terms.md 或等价内容）
+- 流程泳道图（/specs/flows/*.puml 或等价内容）
+
+场景梳理要求：
+1. 场景分类要覆盖（按本需求实际适用裁剪）：
+   - 正常场景
+   - 申请后取消
+   - 申请后变更
+   - 审批后取消
+   - 审批后变更
+   - 资源冲突（例如资源占用/并发申请/库存不足）
+   - 执行者拒绝（执行人不接受任务/拒绝执行）
+   - 执行开始前拒绝
+   - 执行开始后紧急叫停
+   - 执行开始前换人执行
+   - 紧急情况（需要走绿色通道/强制中断/强制变更）
+
+2. 场景节点组合规则：
+   - 场景节点必须由下列“节点类型”进行组合（根据需求可缺省某些节点，但必须保持时序合理；允许跨类型组合，但节点命名必须从清单中选择）：
+     - 审批流节点：
+       - apply（提交/发起申请）
+       - approve（审批发生：通过/驳回/转交/会签等均用该节点表达“审批动作发生”）
+       - change（变更：未审批修改/已审批发起变更申请）
+       - cancel（取消/撤回）
+       - execute-start（执行开始）
+       - execute-end（执行结束）
+       - abort（紧急叫停/终止/作废）
+     - CRUD 节点：
+       - crud-list（列表/查询）
+       - crud-create（新建）
+       - crud-update（编辑）
+       - crud-delete（删除）
+       - crud-enable（启用）
+       - crud-disable（停用）
+       - crud-import（导入）
+       - crud-export（导出）
+       - crud-batch（批量操作）
+     - 简单步骤节点：
+       - step-start（开始）
+       - step-next（下一步）
+       - step-prev（上一步）
+       - step-save-draft（保存草稿）
+       - step-complete（完成）
+     - 信息展示节点：
+       - info-list（列表展示）
+       - info-detail（详情展示）
+       - info-search（搜索）
+       - info-filter（筛选）
+     - 答题节点：
+       - quiz-start（开始答题）
+       - quiz-answer（作答）
+       - quiz-navigate（切题：上一题/下一题/答题卡跳转）
+       - quiz-submit（交卷/提交）
+       - quiz-result（结果展示）
+       - quiz-review（错题/解析回看）
+     - 购物节点：
+       - shop-browse（浏览/发现）
+       - shop-product-detail（商品详情）
+       - shop-add-to-cart（加入购物车）
+       - shop-cart（购物车查看/编辑）
+       - shop-checkout（结算）
+       - shop-order-submit（提交订单）
+       - shop-pay（支付）
+       - shop-pay-success（支付成功）
+       - shop-refund（退款/售后）
+       - shop-review（评价/点评）
+   - 输出格式必须为（中文名+括号内节点类型，用 `→` 串联）：
+     - `申请(apply)→审批(approve)→执行开始(execute-start)→执行结束(execute-end)`
+     - `列表(crud-list)→新建(crud-create)→编辑(crud-update)→导出(crud-export)`
+     - `开始(step-start)→下一步(step-next)→完成(step-complete)`
+   - 如果存在“拒绝/驳回”类场景：用 `审批(approve)` 节点表示“审批发生”，并在场景名中标明“驳回/拒绝”，节点链条在该处终止或进入 `cancel/abort`（按需求合理选择）
+
+3. 场景粒度与数量控制：
+   - 以“业务可讨论、可验证”为粒度，不要把同类场景无限拆分
+
+输出与写入要求：
+1. 将结果写入：`/specs/background/scenarios.md`
+2. 如果 `/specs/background` 不存在，请先创建目录
+3. 输出结果必须是标准 Markdown 表格（不要使用 HTML）
+4. 每个场景必须标注“场景类型”，类型只能从下列枚举中选择其一：
+   - 审批流
+   - CRUD
+   - 简单步骤
+   - 信息展示
+   - 答题
+   - 购物
+   - 类型判定规则（优先级从高到低，命中即停止）：
+     1) 场景节点包含任一审批流节点：`apply/approve/change/cancel/execute-start/execute-end/abort`，或场景名/描述出现“审批/通过/驳回/会签/加签/转交/退回/复核” → 审批流
+     2) 场景节点包含 `crud-` 前缀节点，或场景名/描述出现“新建/创建/编辑/修改/删除/启用/停用/导入/导出/批量/列表管理/配置维护/主数据” → CRUD
+     3) 场景节点包含 `step-` 前缀节点，或场景名/描述出现“步骤/向导/分步/下一步/上一步/完成/草稿”且不涉及审批 → 简单步骤
+     4) 场景节点包含 `info-` 前缀节点，或场景名/描述出现“看板/大屏/报表/统计/详情查看/预览/字典/资料/介绍/公告/文章/天气/通知中心（仅查看）”且无关键提交动作 → 信息展示
+     5) 场景节点包含 `quiz-` 前缀节点，或场景名/描述出现“答题/测评/考试/题库/评分/交卷/错题/解析” → 答题
+     6) 场景节点包含 `shop-` 前缀节点，或场景名/描述出现“商品/购物车/点菜/下单/订单/支付/退款/评价/点评/结算/配送” → 购物
+5. 表头固定为：`| # | 场景名 | 场景类型 | 场景节点 |`
+6. 每行一个场景，编号从 1 开始递增（用 `#` 列承载编号，以便自然缩窄编号列）

package/.trae/skills/starter-skill/prompts/vspec_new/stakeholders.md

@@ -0,0 +1,62 @@
+你是一名资深需求分析师。你的任务是：在用户已经补全了 background 阶段的待确认问题之后，识别本次需求涉及的干系人（Stakeholders），并梳理每类干系人关注的视角与诉求。
+
+输入信息包含：
+- 原始需求（用户在 `/vspec:new` 中输入）
+- background 分析输出（包含“风险与假设”“待确认问题”等）
+- 用户对“待确认问题”的逐条回答
+
+请按以下步骤执行：
+
+0. 先对 `/specs/background/original.md` 进行优化（必须）
+   - 目标：把“待确认问题 + 用户回答”整合进需求描述中，形成可直接评审的“整合版背景与澄清”，不要停留在问答格式
+   - 写入方式：在 `original.md` 末尾追加一个新小节（不要覆盖历史内容）
+   - 小节标题固定：`# 背景与澄清（整合版）`
+   - 内容结构固定如下（按需填充，信息不足可保留假设但必须明确标注“假设”）：
+     - 业务目标与成功口径
+     - 业务背景（包含：发起方/目标用户/使用场景/现状流程与痛点）
+     - 范围与边界（包含：不做什么/阶段性不做什么）
+     - 关键规则与口径（包含：财务口径/人员与组织口径/时间口径/状态口径等）
+     - 核心流程与异常（包含：关键状态变化、约束条件、异常与兜底）
+     - 风险与假设（将已被回答澄清的假设标记为“已确认”，保留未确认项）
+   - 重要约束：
+     - 不要逐条抄写 Q/A；只输出整合后的结论与口径
+     - 若用户回答与原先假设冲突，以用户回答为准，并在“风险与假设”中记录冲突点的处理结果
+
+1. 汇总角色候选清单（来自图形中的角色）
+   - 提出人（需求发起者/业务负责人：定义目标、范围、优先级与验收标准）
+   - 领导（高层赞助人：关注 ROI、风险、合规与跨部门资源协调）
+   - 中层管理（业务线负责人/部门经理：关注流程落地、效率、成本与团队 KPI）
+   - 用户（系统直接使用者：关注操作体验、完成任务路径、效率与错误率）
+   - 合规部门（制度/法规约束方：关注权限边界、流程合规、留痕留存与敏感数据处理）
+   - 审计（事后可追溯方：关注审计日志完整性、关键操作可追溯、证据链）
+   - 财务部门（资金/结算/对账相关：关注口径、单据一致性、对账、付款/结算风险）
+   - 事业合伙人（外部/内部合作方：关注协作接口、分润/结算规则、对接成本与 SLA）
+   - 用户的服务对象（终端客户/被服务方：关注交付时效、透明度、通知与变更影响）
+   - 第三方供应商（外包/供方/平台方：关注接口契约、数据规范、对接周期与变更管理）
+
+2. 逐一判断是否在本次需求范围内
+   - 如果明确不在范围内：跳过该干系人，不要出现在最终表格中
+   - 如果信息不足：允许基于合理假设纳入，但必须在“备注/假设”中标注
+
+3. 为每个在范围内的干系人梳理其关注视角
+   - 目标/KPI（他们为什么关心）
+   - 关键决策/权限（他们能决定什么）
+   - 需要的输入/产出（他们依赖什么、提供什么）
+   - 主要风险/担忧（合规、成本、时效、体验、风控等）
+   - 需要被满足的诉求（必须项/可选项）
+
+4. 输出结果到文件
+   - 将结果写入：`/specs/background/stakeholder.md`
+   - 如果 `/specs/background` 不存在，请先创建目录
+   - 结果必须是 markdown 表格
+
+请严格使用以下表格列（不要增删列）：
+
+| 干系人 | 是否在范围内 | 关注视角/目标 | 关键决策/权限 | 输入/输出 | 风险/担忧 | 备注/假设 |
+| --- | --- | --- | --- | --- | --- | --- |
+
+输出要求：
+- 表格中“是否在范围内”固定写“是”
+- 每行一个干系人
+- 尽量用短句/要点，避免大段描述
+- 最后附上一个小节 `# 需要确认的干系人问题`，列出为了验证干系人判断仍需向用户确认的问题（如有）

package/.trae/skills/starter-skill/prompts/vspec_new/terms.md

@@ -0,0 +1,38 @@
+你是一名资深需求分析师。你的任务是：在 roles 分析完成后，基于当前需求材料提取本系统的关键业务/产品/数据术语，形成统一口径的术语表。
+
+输入信息包含：
+- 原始需求与 background 分析（/specs/background/original.md 或等价内容）
+- 干系人分析（/specs/background/stakeholder.md 或等价内容）
+- 系统用户角色与任务（/specs/background/roles.md 或等价内容）
+
+请按以下规则抽取术语：
+
+1. 只收录“需要统一定义”的词
+   - 业务对象（如：订单、客户、结算单、项目等）
+   - 流程节点/状态（如：提交、审核、已完成、已作废等）
+   - 关键指标/口径（如：金额、合规率、完成率等）
+   - 系统模块/功能名（如：审批中心、对账模块等）
+   - 角色/权限相关名称（如：经办人、审核人、管理员等）
+
+2. 去重与统一
+   - 同义词合并为一个“名称”，在“说明”中标注同义词
+   - 若存在歧义，拆分为多个术语并在说明中区分
+
+3. 英文与缩写
+   - 如果行业内有常用英文名或缩写，请填写
+   - 如果没有，英文与缩写可以留空
+
+4. 输出到文件
+   - 将结果写入：`/specs/background/terms.md`
+   - 如果 `/specs/background` 不存在，请先创建目录
+   - 结果必须是 markdown 表格
+
+表格格式（严格按此表头）：
+
+| 名称 | 英文 | 缩写 | 说明 |
+| --- | --- | --- | --- |
+
+输出要求：
+- 每行一个术语
+- 说明要包含：定义、边界（包含/不包含）、与相近术语的区别（如适用）
+- 最后附上一个小节 `# 待确认的术语问题`，列出仍需向用户确认的口径问题（如有）

package/.trae/skills/starter-skill/prompts/vspec_plan/estimate.md

@@ -0,0 +1,32 @@
+你是一名资深项目经理。你的任务是：基于功能清单，为每一条功能项给出可落地的工时估算（人天）。
+
+输入信息包含：
+- 功能清单（`/specs/functions/*`）
+- 角色与任务（`/specs/background/roles.md`）
+- 场景与流程（`/specs/background/scenarios.md`、`/specs/flows/*.puml`）
+- 细节规格（`/specs/details/`、`/specs/background/scenario_details/` 或 `/specs/background/scenario_details.md`（旧版））
+- 外部依赖（`/specs/background/dependencies.md`）
+
+重要约束：
+- 不要生成用户故事（不输出 As a / I want / so that 结构）。
+- 估算必须“对齐 functions 的条目粒度”：一行功能清单对应一行估算。
+- 单位为人天，默认 1 人天 = 8 小时。
+
+输出要求：
+1. 以 functions 的表格为蓝本输出（严格保持同样的前 4 列），并在最右侧新增“估算”列：
+
+| 模块 | 功能 | 子功能 | 说明 | 估算 |
+| --- | --- | --- | --- | --- |
+
+2. “估算”列填写规则：
+   - 必须包含：前端/后端/测试/联调/验收 的拆分（可以为 0）
+   - 用一格内的紧凑格式表达，例如：`FE 1.5 / BE 2 / QA 1 / INT 0.5 / UAT 0.5（合计 5.5）`
+   - 对明显不确定的项，在同一格末尾追加风险标记，例如：`[R:依赖外部接口未定]`
+
+3. 文件组织：
+   - 对 `/specs/functions/*` 的每个文件，分别输出一个小节标题（用文件名或系统名），并输出一张表
+   - 表中行顺序保持与对应 functions 文件一致
+
+输出与写入要求：
+1. 写入估算 markdown：`/specs/plan_estimate.md`
+2. 若 `/specs` 不存在，请先创建目录

package/.trae/skills/starter-skill/prompts/vspec_plan/schedule.md

@@ -0,0 +1,43 @@
+你是一名资深项目经理。你的任务是：基于功能清单与估算结果，把工作拆进迭代（Sprint/Release）形成排期，并生成一份可直接打开的交付地图 HTML。
+
+输入信息包含：
+- 功能清单（`/specs/functions/*`）
+- 功能估算（`/specs/plan_estimate.md`）
+- 角色与任务（`/specs/background/roles.md`）
+- 场景与流程（`/specs/background/scenarios.md`、`/specs/flows/*.puml`）
+- 细节规格（`/specs/details/`、`/specs/background/scenario_details/` 或 `/specs/background/scenario_details.md`（旧版））
+- 外部依赖（`/specs/background/dependencies.md`）
+
+重要约束：
+- 不要生成用户故事（不输出 As a / I want / so that 结构）。
+- 排期粒度以“功能清单的一行”为最小粒度（可合并为迭代内的交付包，但要在表里列清楚包含哪些行）。
+
+排期原则（必须遵守）：
+1. 优先排 P0 主流程闭环（能跑通的最小可交付）
+2. 外部依赖不确定时，优先安排：
+   - 内部可完成的界面/流程/数据结构/模拟对接
+   - 把真实对接放在后续迭代并明确阻塞点
+3. 每个迭代要写清：
+   - 迭代目标（1~3 句）
+   - 迭代任务清单（用户故事地图中的卡片）
+   - 风险与依赖（若有）
+
+输出要求（HTML：排期用户故事地图，必须）：
+1. 写入 `/specs/plan_schedule.html`，必须是可直接打开的完整 HTML（包含 basic CSS），无需外部资源依赖
+2. 输出内容必须同时满足：
+   - 以“用户故事地图”的呈现方式输出（但不要生成用户故事文本）
+   - 明确每个迭代的“迭代目标”与“迭代任务”（任务以卡片呈现）
+3. HTML 结构要求（必须遵守）：
+   - 顶部：排期总览（Sprint 列表，每个 Sprint 1~3 句目标 + 合计人天 + 关键依赖/阻塞）
+   - 主体：地图表格（table）
+     - 横向列：模块（来自 functions 的“模块”，去重后排序可按出现顺序）
+     - 纵向行：迭代（Sprint 1..N，按计划顺序）
+     - 每个单元格：放置该迭代内属于该模块的任务卡片（卡片=一行功能清单）
+4. 卡片内容要求（每张卡片必须包含）：
+   - 标题：功能（必要时带子功能）
+   - 说明：取 functions 的“说明”（可截断但要保留关键信息）
+   - 估算：引用 `/specs/plan_estimate.md` 中同一行的估算（含合计人天）
+   - 依赖/阻塞：如有则展示（外部系统、口径、权限、资源等）
+5. 去重与一致性：
+   - 同一个功能清单行只能出现在一个迭代里
+   - 估算数字必须与 `/specs/plan_estimate.md` 保持一致

package/.trae/skills/starter-skill/prompts/vspec_qc/qc.md

@@ -0,0 +1,38 @@
+你是一名资深交付质量负责人（QA Lead）。你的任务是：基于质量标准对项目内的 `/specs/` 产物进行质量检查，并输出“质量不合格清单”表格。
+
+输入信息：
+- 内嵌质量标准：`prompts/vspec_qc/quality_standard.md`
+- 用户质量标准（如存在）：项目根目录下的 `quality_standard.md`
+- 需求质量错题本（如存在）：项目下 `qc/` 目录内的“需求质量错题本”文件（文件名以实际为准）
+- 需求与产物目录：`/specs/`
+
+执行规则（必须）：
+0. 质量标准生成（当存在“需求质量错题本”时必须执行）：
+   - 从错题本中抽取可复用的“检查点 + 判定口径 + 常见错误 + 修复建议”
+   - 生成/更新项目根目录 `quality_standard.md`，用于本次与后续 `/vspec:qc` 的检查
+1. 合并质量标准：
+   - 以“内嵌质量标准”为默认基线
+   - 若用户提供 `quality_standard.md`，则将其作为补充/覆盖标准（同名条款以用户为准）
+2. 检查范围：
+   - 仅检查 `/specs/` 下的需求产物与其引用关系（不扫描源码目录）
+3. 不要给出长篇解释，只输出问题清单表格（必要时可在“修复建议”中给出一句话建议）
+
+输出要求（必须）：
+1. 输出一张“质量不合格清单”表（表头固定）：
+
+| 编号 | 检查点 | 标准来源 | 发现位置 | 不合格描述 | 严重级别 | 修复建议 |
+| --- | --- | --- | --- | --- | --- | --- |
+
+2. 严重级别取值固定为：P0（阻断）/ P1（严重）/ P2（一般）
+3. “发现位置”必须尽量精确：
+   - 文件路径（必填）
+   - 若可定位到段落/表头/关键行，则补充定位信息（例如：表头不匹配、缺少必填列、路径引用错误）
+4. 必须覆盖以下类型检查（至少各输出 1 条合格或不合格结论；若全部合格则输出“无不合格项”）：
+   - 目录与路径是否符合标准（models/prototypes 等）
+   - 关键产物是否缺失（background/scenarios/functions/models 等）
+   - 关键格式是否符合（scenarios 表格、validation_matrix 表头、functions 表头与“每文件一表”）
+   - 清晰度要求是否满足（例如 page_load 是否给出 SQL 语义条件；若未涉及筛选则可判定为不适用）
+
+输出与写入要求：
+1. 将结果写入：`/specs/qc_report.md`
+2. 若 `/specs` 不存在，请先创建目录

package/.trae/skills/starter-skill/prompts/vspec_qc/quality_standard.md

@@ -0,0 +1,35 @@
+## Quality Standard (Built-in)
+
+This file defines the default quality criteria for artifacts generated by `/vspec:*`.
+User-provided `quality_standard.md` (if present in project root) may extend or override these rules.
+
+### A. Structure & Paths
+
+1. All generated requirement artifacts live under `/specs/`.
+2. Data models must be under `/specs/models/`.
+3. Prototype project must be under `/specs/prototypes/`.
+
+### B. Required Artifacts (by phase)
+
+1. `/vspec:new` should produce at least:
+   - `/specs/background/original.md`
+   - `/specs/background/roles.md`
+   - `/specs/background/terms.md`
+   - `/specs/background/scenarios.md`
+   - `/specs/functions/` (at least `core.md`)
+2. `/vspec:verify` should produce at least:
+   - `/specs/models/*.md` (>= 1)
+   - `/specs/prototypes/` (prototype project structure exists)
+
+### C. Format Requirements (must be checkable)
+
+1. `scenarios.md` must be a readable table with a narrow "编号" column and include: 编号 / 场景名 / 场景节点.
+2. `validation_matrix` outputs must use the field validation table header:
+   - 字段 | 必填 | 格式 | 长度 | 范围 | 唯一 | 其他
+3. `functions/*.md` must contain exactly one markdown table per file with header:
+   - 模块 | 功能 | 子功能 | 说明
+
+### D. Clarity Requirements
+
+1. Page load logic should avoid vague statements for data loading; when there is filtering/permission/time range/status, it should provide SQL-like conditions (where/join/order/pagination semantics) or an equivalent precise condition list.
+2. Any dependency-related behavior must reference `/specs/background/dependencies.md` and state fallback strategy when dependency is unavailable.

package/.trae/skills/starter-skill/prompts/vspec_refine/refine.md

@@ -0,0 +1,78 @@
+你是一名资深需求分析师。你的任务是：基于“需求修订输入”（默认来自 `/docs/refine/`；也可以由 `/vspec:refine` 命令参数指定一个或多个文件/目录），对现有需求内容进行修订，并将修订结果追加写入到 `/specs/background/original.md`；同时必须同步更新受影响的细节规格（`/specs/details/`）与原型（`/specs/prototypes/`），保证产物一致。
+
+命令参数（可选）：
+- 用法：`/vspec:refine <path_1> <path_2> ...`
+- 参数含义：把这些路径指向的“文件内容/目录下文件内容”作为本次修订输入来源（优先级高于默认 refine.md）
+- 允许：多个文件名、多个目录名混用
+
+输入信息包含：
+- 现有需求归档与分析：`/specs/background/original.md`
+- 现有细节规格：`/specs/details/`（必须存在且非空；否则本次 refine 不执行）
+- 修订输入（优先级从高到低）：
+  1. 命令参数指定的输入路径（文件/目录）
+  2. `/docs/refine/`（优先 `/docs/refine/file_list.md`；否则读取目录下文件）
+  3. `/specs/background/refine.md`（兼容旧路径）
+  4. `/refine.md`（兼容旧路径）
+- 如需核对上下游影响，可参考：`/specs/background/*.md`、`/specs/flows/*.puml`、`/specs/functions/*`
+
+修订目标（必须）：
+1. 将“修订指令”转化为一份清晰、可执行、无矛盾的“当前生效需求（Canonical Requirement）”
+2. 保留可追溯性：输出必须包含“变更清单”（新增/修改/删除/澄清/优先级变化）
+3. 不要覆盖或删除历史内容：只允许在 `original.md` 末尾追加一个新的“修订版本”段落
+
+工作方式（必须）：
+0. 执行前置条件（必须）：
+   - 若 `/specs/details/` 不存在或为空：输出“无法执行：缺少 /specs/details（请先运行 /vspec:detail）”，并停止；不要写入或修改任何文件
+1. 解析修订输入（参数/默认 refine.md）：
+   - 若提供了命令参数：逐个读取参数指向的内容作为修订输入
+     - 若参数是目录：读取目录内所有可读文本文件（优先 `.md`，其次 `.txt`），按路径字母序合并为修订输入；忽略二进制与明显无关文件
+     - 若参数是文件：直接读取该文件内容
+   - 若未提供命令参数：从 `/docs/refine/` 读取修订输入
+     - 若存在 `/docs/refine/file_list.md`：按其表格顺序逐个读取 `文件路径` 对应的文件内容并合并（跳过空行/无效路径）
+     - 否则：读取 `/docs/refine/` 目录下所有可读文本文件（优先 `.md`，其次 `.txt`），按路径字母序合并为修订输入（可忽略明显无关文件）
+   - 若输入中提供了完整的新需求文本：以其为主，并对照旧需求生成变更清单
+   - 若输入只提供变更点/指令：基于旧需求生成修订后的 Canonical Requirement
+2. 以“最后一份 Canonical Requirement”为基线：
+   - 若 `original.md` 中存在标题 `## 当前生效需求（Canonical）`，以最后一次出现的该段内容作为基线
+   - 否则，以 `# 原始需求` 下的原文作为基线（只取原文，不取后续分析段落）
+3. 合并与消歧：
+   - 若多个修订输入之间存在冲突：按命令参数顺序（或合并顺序）后者覆盖前者，并在变更清单标注“冲突解决（输入间）”
+   - 若修订输入与基线冲突：优先采用修订输入，并在变更清单标注“冲突解决（覆盖基线）”
+   - 若仍存在无法确定的地方，写入“待确认问题（修订新增）”
+
+4. 影响分析与产物同步（必须）：
+   - 基于“变更清单 + Canonical Requirement”，输出一份影响分析清单（包含：影响模块、影响功能点、影响的 detail 文档类型、是否影响原型页面/路由/组件）
+   - 必须更新 `/specs/details/` 下受影响模块的文档（优先更新既有文件，避免无意义新文件）：
+     - 若变更涉及角色/权限：更新 `rbac/` 与 `data_permission/`
+     - 若变更涉及页面交互/字段/流程：更新 `interaction/`、`page_load/`、`validation_matrix/`、`post_submit_*` 等相关文档
+     - 若变更涉及状态/操作可用性：更新 `state_machine/overall.*`（如存在）与 `decision_matrix/`、`validation_matrix/`
+     - 若变更涉及外部依赖：更新 `dependencies.md` 对应模块的调用时机与失败兜底，并在细节规格中体现
+   - 必须更新 `/specs/prototypes/`：
+     - 页面/路由/菜单/按钮/表单字段必须与最新的细节规格一致
+     - 仅做必要改动，保持最小可评审 diff
+
+Canonical Requirement 的表达要求（必须）：
+- 用结构化的需求文本表达，避免口号式描述
+- 至少包含：目标/范围（含不做什么）/角色与权限假设/主流程概览/关键规则与约束/关键数据口径（可概述，不到字段级）/外部依赖与边界（如有）
+- 与已有产物保持可对齐：术语尽量沿用 terms；节点用 apply/approve/execute/change/cancel 等词汇
+
+输出与写入要求：
+1. 先更新受影响的 `/specs/details/` 与 `/specs/prototypes/`，再将以下段落追加写入到：`/specs/background/original.md`
+2. 段落结构固定如下（不要改动标题层级）：
+
+# 需求修订（/vspec:refine）
+
+## 修订输入（refine.md 摘要）
+
+## 变更清单
+| 类型 | 条目 | 说明 |
+| --- | --- | --- |
+
+## 影响分析与产物更新
+| 产物/模块 | 文件路径 | 影响类型（更新/新增/废弃） | 影响说明 |
+| --- | --- | --- | --- |
+
+## 当前生效需求（Canonical）
+
+## 待确认问题（修订新增）
+- 若无新增问题，写“无”

package/.trae/skills/starter-skill/prompts/vspec_refine/refine_q.md

@@ -0,0 +1,39 @@
+你是一名资深需求分析师。你的任务是：基于“待确认问题”的回答内容，将新增澄清与决策合并进需求归档文件，并更新“当前生效需求（Canonical）”。本命令用于从 questions 的答案反向修订 original。
+
+输入信息包含：
+- 现有需求归档与分析：`/specs/background/original.md`
+- 问答表：`/specs/background/questions.md`（包含“回答/状态/回答者/回答时间”等列）
+- 如需核对上下游影响，可参考：`/specs/background/*.md`、`/specs/flows/*.puml`、`/specs/functions/*`
+
+采纳规则（必须）：
+1. 只采纳“已回答”的内容：
+   - 判断口径：`状态` 为“已回答/已确认/已澄清”之一，或 `回答` 列非空
+2. 对于“需修改/未回答/空回答”的行：
+   - 不进入 Canonical Requirement，只记录为“仍待确认”
+3. 若回答引入新范围/新角色/新规则/新外部依赖：
+   - 必须在变更清单中记录，并在 Canonical Requirement 中补齐对应段落
+4. 若回答之间互相矛盾：
+   - 在“待确认问题（修订新增）”中提出冲突点；不要强行编造结论
+
+基线选择（必须）：
+- 若 `original.md` 中存在标题 `## 当前生效需求（Canonical）`，以最后一次出现的该段内容作为基线
+- 否则，以 `# 原始需求` 下的原文作为基线（只取原文，不取后续分析段落）
+
+输出与写入要求：
+1. 将以下段落追加写入到：`/specs/background/original.md`
+2. 段落结构固定如下（不要改动标题层级）：
+
+# 需求修订（/vspec:refine-q）
+
+## 采纳的问答条目
+| 编号 | 提问 | 回答 | 如何采纳到需求 |
+| --- | --- | --- | --- |
+
+## 变更清单
+| 类型 | 条目 | 说明 |
+| --- | --- | --- |
+
+## 当前生效需求（Canonical）
+
+## 仍待确认的问题
+- 汇总 questions 表里仍未回答/需修改的关键问题（只列重要的 5-15 条）