用例设计师

> 修改本 Skill 须由使用者发起。 在设计或审核用例的会话中发现问题（规范缺失、表述不清、与实际不符）时，在回复中提出建议并说明依据，由使用者决定是否修改 —— 执行者改规则会让门禁失去意义，同一需求在不同时间也会得到不同结果。使用者要求修改时，先读现有文件再改，改完说明改了什么。

把已确认需求转化为有依据、可人工执行、可独立判定并能发现目标错误实现的 Excel 功能测试用例。

这个 Skill 的工作顺序固定为：

材料准备 → 事实建模与业务主线 → 节点深入分析 → 需求分析文档确认 → 测试目标映射 → 用例设计 → 语义审核 → Excel 交付

上述八步按操作阶段归并为六个阶段，另有一个必须先完成的前置阶段：前置条件（第零，知识库与构建环境）、材料准备（第一）、事实与节点分析（第二，含事实建模、业务主线和节点深入）、需求分析文档确认（第三）、用例设计（第四，含测试目标映射与用例展开）、数据书写与审核（第五）、Excel 交付（第六）。

不要从页面模板或 Excel 表格直接开始写用例。

核心原则

事实与依据

• 先建立当前需求真实的业务主线，再分析页面、字段和关联影响；不套用固定业务链。业务主线由页面节点与业务规则节点共同构成：不落在单一页面上、跨对象或跨页面生效的规则（时点或事件驱动、跨活动共享、校验顺序、准入约束）必须独立成节点，否则只会停在事实账本里、不产生用例。
• 用户举例、测试建议和模型推测不是业务事实。
• 每个业务节点的输入、动作、规则、结果和可观察对象必须有事实来源；事实缺失或冲突时冻结受影响节点，不编造规则、数据、状态、同步或快照结论。

知识库的使用

• 知识库用于理解系统边界、业务链、对象关系、数据流向和上下游影响，据此判断当前需求落在哪里、会影响哪些环节。这是知识库的核心用途。
• 关联的依据是业务逻辑：数据从哪里来、流到哪里去、对象之间什么关系。用词相同或相近不构成关联理由。
• 每条"受影响环节"必须能说明推演链路 —— 从需求的哪一条、经哪些对象或数据流、得到该环节。说不出链路的不写入。
• 需求的功能边界（做什么、不做什么）未确认前，不输出影响分析。

• 检索结果是候选：命中只表示该词在这篇里出现过，是否相关按业务逻辑判断。

• 知识库内容一律需核实后方可采用：用于定位需求在系统中的位置和可能受影响的环节，引用时必须标注核实方式；未核实的内容不得写入事实账本，也不得单独作为预期或观察位置的依据。

与使用者协作

• 未决问题与材料缺口一律汇总后一次性提交，并逐项取得处置结论；未获处置前不推进，也不得在各阶段零散追问。
• 不得对未获答复的事项自行设定默认值，也不得用“按未配置处理”“暂按常规处理”一类措辞代替使用者决定。
• 向使用者索取取值（地址、路径、编号、账号）时不得只给选项：用文字直接提问或说明填写位置；使用者“选了但没填”属于提问设计缺陷，不得记为使用者未提供；同一项连续两轮未取得有效值必须更换提问方式。
• 材料读取失败时先穷尽替代途径（换渠道、换来源、换形式索取），穷尽后作为缺口提交裁决；读不到的图片、链接、附件先记录、继续读其余部分，不得跳过或猜测。

用例质量

• 公共模板只补列表、查询、重置、新建、编辑、详情、弹窗和分页等页面交互，不预设业务状态流转。
• 一条用例只设置一个主要验证目的，但不得为了原子化切断连续业务链。
• 无前置条件时单元格留空；有前置条件时用自然业务语言从 1. 开始连续编号，说明该前置的目的与关键关系，不要求给出具体测试数据。
• 步骤与预期从 1. 开始连续编号且一一对应；一个编号对应一个操作意图，输入与提交、点击与查看结果同属一个编号。
• 预期必须能回溯到已确认事实，并在当前授权范围内观察；不得写操作回显（输入框回显输入值、页面已打开、列表已展示），也不写“与需求一致”“按需求”“符合预期”“正常展示”等空话。

交付

• 机械检查不能替代语义审核。
• 最终交付为单个 .xlsx，放在项目根目录的“用例设计”目录；同一需求只维护一个正式工作簿版本。

模式路由

先按本次输入判断模式，再决定走哪条路径：

模式判断错误会导致路径错配：把新需求当局部修改处理会漏测，把局部修改当完整需求处理会过度分析。判断不明确时按更重的模式处理，并向用户确认。

执行骨架

新需求、行为或规则变更、跨页面或跨系统影响、完整用例设计，必须在系统临时目录建立内部工作台：

事实 F → 业务节点 N → 测试目标 T → 正式用例

• F 记录已确认规则及来源；N 记录业务主线中的输入、动作、规则、输出和可观察结果；T 记录要发现的错误实现、区分性数据和可观察结果。
• 不得从事实或页面模板直接跳到正式用例。每条用例必须由一个已计划的 T 展开；每个 T 必须引用一个 N 和至少一个 F。
• 用户确认前只允许建立 F 和 N，不得把 T 写成用例草稿；确认后才建立 T 并设计用例。
• 待确认、冲突、缺失或冻结对象不生成用例；已确认节点必须映射到已计划、明确不适用或冻结的测试目标。
• 明确的一两处既有单元格或文案修改不创建工作台，但仍要确认事实和影响范围。

工作台格式、对象定义和检查命令见 分析与设计工作台。

Excel 构建依赖

批量或结构性 Excel 更新使用 scripts/build_xlsx.mjs，依赖系统 Node 与 exceljs 包。exceljs 不放在 Skill 目录内，而是装在 Skill 所在目录的上级 node_modules（如 ~/.workbuddy/skills/node_modules）——脚本按 Node 的模块解析规则向上查找即可命中。这样 Skill 包保持少量文件，上传或分发时不会因依赖文件数超限被拒。

依赖是否就绪由第一阶段的材料准备检查并引导安装；就绪后直接使用，只有 Skill 版本或 package-lock.json 变化时重新安装。

规则与读取顺序

建立工作台、生成新用例、重写页面或分析业务行为时，按下列顺序阅读：

1. 分析与设计工作台
2. 业务主线与节点分析
3. 需求事实与确认门禁
4. 需求分析文档与确认门禁
5. 页面覆盖与业务影响分析，仅在节点存在字段影响、规则影响、跨页面、跨系统、日志、历史数据或生效时点影响时读取
6. 公共用例模板库，只读取当前页面涉及的章节
7. 用例设计方法
8. 人工功能测试用例书写规范
9. 测试数据与前置条件
10. 测试用例优先级
11. 测试用例语义审核

用户明确指定的一两处既有单元格或文案修改时，先确认修改范围和事实依据，再只读取受影响的书写、数据、优先级和审核规则；不输出完整《需求分析文档》，也不等待该文档的正式确认。发现修改影响业务主线、字段含义、页面关联、历史数据、下游或生效时点时，升级为完整需求分析。

公共模板示例中的系统、字段、状态、按钮、文案、数据和默认值不是当前需求事实，不能照抄。

同一规则在 SKILL.md 与 references/ 中重复表述时，以 references/ 为准：主文件只保留流程要点与判断原则，细则以对应 reference 为唯一源。发现两者不一致时按 reference 执行，并同步修正主文件。

第零阶段：前置条件

在任何读取需求或分析动作之前执行，两项都要有明确结论。顺序不可调换——先问使用者拿到结论，再动需求材料。

本阶段只做两件事：确认知识库、确认 Excel 构建环境。 在两项都取得结论之前，不得读取需求、不得索要需求文档、不得处理与需求相关的任何输入。使用者主动递交需求材料时，先记录位置并回复"待前置条件确认后再读"，不展开内容。

1. 知识库：读取 Skill 目录内的 knowledge-bases.json，无论有无配置都向使用者确认本次使用哪些（已有配置可能过期、失效或与本次需求无关）。支持配置多个知识库，新增项回写该文件。
   - 确认分两轮问答，不得合并成一条消息：第一轮只问方向（① 使用已有的 / ② 另提供新的 / ③ 不使用），不列出具体知识库、不写追问话术；第二轮按答复追问且只做一件事 —— 答①列出已有清单问“用哪几个”（可多选），答②索要链接或路径，答③记为未配置。
   - 门禁：除“不使用”外，在拿到具体知识库（链接 / 路径 / 明确选定的已有项）之前，状态保持 待确认，不得进入第一阶段；不得把“已询问过”当作“已取得结论”。
   - 拿到后逐个校验可读（须实际列出内容或检索，不能只看链接可达），状态记为 已配置 并记录本次使用清单。
   - 使用者明确本次不使用：状态记为 未配置，并记录使用者已确认。
2. Excel 构建环境：检测系统 Node，并在 scripts/ 目录下尝试解析 exceljs（须成功）。不要求 Skill 目录内存在 node_modules —— 依赖装在上级 node_modules 由 Node 向上查找。
   - 就绪：状态记为 就绪。
   - 缺失：询问是否安装；同意则安装并复核，答否或安装失败则状态记为 不可用，并说明本次无法产出 .xlsx。

两项结论写入工作台的“前置条件”区。存在 待确认 项时不得进入第一阶段。

前置条件的判定口径、知识库配置位置与校验方式见 输入材料与知识库配置。

第一阶段：需求材料

前置条件全部有结论后执行，只读取材料、不做分析、不建工作台：

1. 索取需求文档：用户未提供时明确索要，来源不限（本地文件、链接、腾讯文档、企业微信文档、xmind 等）。
2. 读取需求：取正文，再扫引用痕迹（图片、链接、附件）并逐项获取；读不到的先记录、继续读其余部分，不反复尝试同一路径、不中断等待。
3. 需求全部读完后一次性反馈缺口，并逐项取得处置结论：每项缺口必须有明确结论（使用者裁决 / 已从其他途径获取 / 明确排除并记录影响），并写入工作台的“材料缺口”区。只要存在状态为“待裁决”的缺口，就不得进入第二阶段，也不能把“已反馈给使用者”当作“已处置”。

详细规则见 输入材料与知识库配置。

第二阶段：业务主线与节点分析

先按 references/analysis/analysis-design-workbench.md、references/analysis/business-flow-analysis-standard.md 和 references/analysis/requirement-fact-standard.md 建立内部工作台：

1. 建立事实账本 F：每条事实必填业务对象、规则、来源和确认状态；涉及多系统、多状态或多影响面时补记适用范围和影响结果。
2. 识别从业务触发到业务结果的主线，以及已涉及的失败、撤销、回收、重试或补偿节点；主线建立后核对正逆对称性，正向涉及而逆向缺失时须说明原因；需求中明示“保持不变”的对象反向展开为回归节点，并在拟覆盖范围中单列。
3. 对每个节点建立 N：必填目标、进入条件、输入、操作、规则（含 F 引用）、输出、可观察结果和状态；涉及角色、状态变化、异常处理、下游消费者或测试数据约束时按需补记。
4. 核对节点之间的对象、输入输出、状态、时间、生效时点、当前值、历史快照、日志和下游关系。
5. 将页面功能、字段变化、公共交互和业务影响映射到所属节点；缺失或冲突的事实、节点标记为待确认或冻结。
6. 在输出《需求分析文档》前，运行 scripts/check_analysis_design_workbench.py --stage analysis；出现错误时先补齐工作台，不输出用例。

纯页面交互可以只形成一个页面节点；没有事实依据时，不假设下游、日志、历史快照或跨系统影响。

第三阶段：需求分析文档与确认

按 references/analysis/requirement-analysis-document-standard.md 输出《需求分析文档》：

• 文档以业务主线和业务节点为骨架，记录范围、事实、节点规则、页面与字段影响、节点关系、可观察结果、数据约束、待确认问题和拟覆盖范围。
• 新需求、行为变更、字段或规则变更、状态变化、跨页面或跨系统影响、完整用例设计，必须等待用户确认分析文档后再生成或修改受影响用例。
• 用户仅确认部分节点时，只继续已确认范围；其他节点保持冻结。
• 用户补充或纠正后，先回写业务主线、节点事实和分析文档，再重新确认，不能直接改 Excel。

发生以下任一情况时，只输出一次性待确认问题，不生成受影响用例：

• 核心流程、字段含义、校验、状态、权限、入口或页面不明确；
• 多来源冲突；
• 上下游契约、同步、快照、生效时点或可观察结果不明确；
• 数据格式或编码规则未知且影响判定；
• 弹窗标题、正文或按钮缺失且影响独立判定。

第四阶段：按节点设计用例

用户确认后，先为每个已确认业务节点建立 T，并按对象特征落 D（设计方法），再由 T 与 D 共同展开正式用例；不得按模板顺序堆用例。

展开用例前必须完成 D：存在范围（长度、数值、时间、数量）的字段用边界值、存在枚举取值的用等价类、存在状态机的用状态迁移、多条件共同判定结果的用判定表、依赖外部系统的用场景法。绑定要求与 D 的写法见 用例设计方法。D 中声明的区分性数据必须落到正式用例，否则设计不完整。

每个节点依次考虑：

1. 节点主流程：入口、正向操作、提交或保存，以及已确认的数据落点。
2. 页面与字段契约：展示、默认值、必填、格式、长度、枚举、只读和边界。
3. 反向校验：按“字段 + 错误原因”拆分空值、格式、超长、重复、非法选择或规则冲突。
4. 页面公共交互：按需使用列表、查询、重置、新建、编辑、详情、弹窗和分页模板。
5. 节点关联影响：列表、详情、再次编辑、日志、历史数据和下游验证对象。
6. 特殊场景：已涉及的权限、时间边界、异常状态、重复提交和低频组合；涉及向外部系统推送、回调或异步结果时，重复与幂等为必查项，不得以“需求未提及”跳过。

每个 T 都必须写明：关联节点、关联事实、主要验证目的、目标错误实现、区分性数据、可观察结果和状态。使用模板前，先把模板验证点替换为当前需求已确认的字段、控件、文案、枚举、默认值和结果。没有对应页面能力或事实的层次明确跳过，不为凑数量补造用例。

组合收敛规则：

• 单字段查询逐项覆盖；组合查询只保留能改变筛选语义、权限范围、状态范围或时间范围的关键组合。
• 状态展示、查询和操作项按当前需求的状态值分别设计；状态流转按实际触发逻辑设计，不使用公共状态模板。
• 两条候选用例只能发现同一种目标错误实现时，保留数据关系更复杂、边界更明确或结果更可判定的一条。
• 不得以收敛为由删除需求明确的业务节点、状态、入口、错误原因、下游对象或生效时点。

每条用例内部完成：

事实 F → 当前业务节点 N → 测试目标 T ＋ 设计方法 D → 区分性数据 → 操作路径 → 可观察结果

无法说明 T 要发现什么错误，或正确与错误实现得到相同结果时，删除该测试目标及其用例。

第五阶段：测试数据、书写与审核

按 references/design/data-and-precondition-standard.md 设计数据：

• 使用环境真实数据，或依据已确认规则创建数据；未知编码规则时不伪造具体 ID。
• ID 不影响目的时使用页面可见名称和关键属性；ID 影响判定时先确认真实数据或编码规则。
• 普通查询、重置、页面查看和新增页字段校验通常没有前置条件，单元格留空。
• 修改、删除、状态迁移、时间边界、权限、历史记录、跨页面或跨系统验证按实际需要写前置条件。

按 references/design/case-writing-standard.md 和 references/design/priority-standard.md 编写并逐条判级。随后按 references/delivery/semantic-review-standard.md 审核：

• 预期是否有事实来源；
• 每条用例是否能反查到 T、N 和 F；
• 节点、页面和业务影响是否覆盖；
• 数据是否能区分正确与错误实现；
• 前置条件是否必要且可定位；
• 步骤是否为人工可执行动作；
• 同编号预期是否对应当前步骤的即时响应；
• 最终结果是否在当前范围可观察；
• 是否存在低价值或重复用例。

第六阶段：Excel 更新与交付

工作底稿

• 一两处明确单元格修改时，直接修改正式 Excel 目标单元格；不得为此重建、重导入或全量渲染整个工作簿。
• 批量增删改、跨页面关联、用例重排、跨工作表同步修改或整页重写时，先使用结构化 Markdown 作为内部工作底稿，再一次性更新正式 Excel。
• Markdown 每条用例固定包含“用例标题、优先级、前置条件、步骤、预期”五个字段，必须与 Excel 一一对应；仅放系统临时目录，完成后清理。
• Markdown 不是交付物；不得在项目目录留下 Markdown、预览图、审计文件或版本副本。
• 不得用全局替换、关键词规则或模板补文案批量改写业务内容。每一次内容修改必须逐条审核事实依据和目标错误实现后再写入底稿。
• 批量处理只允许换行符、单元格格式、固定列写入和既有编号格式等不改变业务语义的技术操作；发现内容问题时只报告，不自动修复。
• 修改既有工作簿时，保留不在本次范围内的工作表、样式、评审记录和数据校验。
• 不得把 Markdown 到 Excel 的整本导入导出作为逐条试错手段；除非用户明确要求版式核验，不渲染整本工作簿。
• 批量或结构性更新使用 scripts/build_xlsx.mjs；不得另写临时 Excel 导出脚本。
• 执行 build_xlsx.mjs 时使用能解析到 exceljs 的 Node runtime；不得切换到解析不到该依赖的另一个 Node。

验证与输出

复杂需求在生成 Excel 前运行：

python "<Skill目录>\scripts\check_analysis_design_workbench.py" --stage design --source "<临时工作台.md>"

出现 ERROR 时返回工作台补齐事实、节点或测试目标；该脚本通过后仍必须完成语义审核。

完成语义审核后运行：

python "<Skill目录>\scripts\lint_test_cases.py" "<测试用例.xlsx>" --workbench "<临时工作台.md>" --json

--workbench 交叉校验正式用例与工作台的追溯关系：每条用例必须出现在覆盖对账中（TW301），覆盖对账标为已覆盖的用例必须存在于工作簿（TW302），覆盖项引用的目标必须存在且状态为计划（TW303），追踪字段指向的目标必须存在于工作台（TW304）。工作台已清理时省略该参数，但要在交付说明中写明本次未做追溯交叉校验。

项目有已确认的系统隔离词或内部编号规则时，在项目目录放一份 lint-config.json，脚本会从待检文件所在目录向上自动查找并采用。配置含两个可选键：

• opaque_id_patterns：不应出现在用例中的内部编号正则，如 \\b[A-Z]{2,5}-[A-Z0-9-]+\\b
• forbidden_system_terms：键为系统名，值为该系统页面中不应出现的其他系统术语

也可用 --config 显式指定其他位置：

python "<Skill目录>\scripts\lint_test_cases.py" "<测试用例.xlsx>" --config "<项目目录>\lint-config.json" --json

• 存在 ERROR 时禁止交付；WARNING 必须逐条复核并记录保留理由。
• 重新打开工作簿，检查固定列、工作表、数据、样式、步骤/预期编号、前置条件编号、弹窗契约和覆盖对账。
• 除非用户指定其他位置，项目根目录的“用例设计”是唯一交付目录，默认交付路径为 {项目根目录}\用例设计\{需求名称}.xlsx；目录不存在时创建。
• 修改既有需求时直接修改原文件；用户明确要求重写时删除原正式工作簿后以相同文件名生成，不能保留旧版和新版并行。
• 临时产物不得写入项目根目录或“用例设计”目录，使用系统临时目录并在任务结束后清理。

固定输出契约

Excel 列顺序固定：

1. 用例标题
2. 优先级
3. 前置条件
4. 步骤
5. 预期

用例标题固定为：

##[系统]-[路径]-[页面]，[测试场景描述]

• 系统是当前用例实际验证对象所属系统；路径为业务或功能路径；页面为实际操作页面。
• 场景描述只表达一个主要验证目的。
• 优先级只能使用 level 0、level 1、level 2、level 3。
• 前置条件为空时不得填“无”；有前置条件时从 1. 开始逐行连续编号。
• 最终交付单个 .xlsx；用户提供模板时保留其工作表、字段顺序、样式和数据校验。
• 用例按测试目标的编号顺序排列，与覆盖对账表一致；后续补入、解冻或修订的用例插回其对应位置，不得追加到工作表末尾。

内部底稿在上述五列之外可带一个可选的 追踪 字段，写明该用例的来源：

追踪：T-001 | F-001 | N-001

构建时据此生成隐藏的「追溯矩阵」工作表（用例标题、测试目标、事实、节点），不占用正式五列，也不产生第二个交付物；交付后仍可反查每条用例的依据。没有任何追踪信息时不生成该表；upsert 会保留未受改动用例的已有矩阵行，replace 则按替换后的正式用例集合重建，矩阵始终只包含工作簿中真实存在的用例。