cgraphx 2.0.2 → 2.0.6

package/dist/.claude-template/skills/write-api/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: write-api
-description: 基于需求生成 bruno 测试接口(.bru + 测试规格 + 环境配置)。流程:识别接口范围(用户显式给 / spec 接口章节 / AI 读 spec 理解)→ 生成测试规格文档 → 单次 AI 调用生成 .bru(含真实参数 + 内嵌断言)→ 首次接入时生成 bruno.json + environments/*.bru 骨架。产物:测试规格随 feature 走;.bru collection 按 <服务>/<需求前缀>/<接口名>/<场景> 组织在 docs/bruno/(按需求隔离,跨需求不覆盖);environments 统一管理。本 skill 不跑 bru run、不核实 DB、不出报告——那是 /run-api-test 的职责。不调 write-api-doc、不自动修代码、不引入程序化配置文件(微服务/通用接口识别由 AI 判断)。Use when 用户要求生成测试接口 / 写接口测试 / 准备 bruno 测试 / 帮需求补接口 / 免去手动录接口。
+description: 基于需求生成 bruno 测试接口(.bru + 接口测试规格 + 环境配置)。流程:识别接口范围(用户显式给 / spec 接口章节 / AI 读 spec 理解)→ 生成接口测试规格文档 → 单次 AI 调用生成 .bru(含真实参数 + 内嵌断言)→ 首次接入时生成 bruno.json + environments/*.bru 骨架。产物:接口测试规格随 feature 走;.bru collection 按 <服务>/<需求前缀>/<接口名>/<场景> 组织在 docs/bruno/(按需求隔离,跨需求不覆盖);environments 统一管理。本 skill 不跑 bru run、不核实 DB、不出报告——那是 /run-api-test 的职责。不调 write-api-doc、不自动修代码、不引入程序化配置文件(微服务/通用接口识别由 AI 判断)。Use when 用户要求生成测试接口 / 写接口测试 / 准备 bruno 测试 / 帮需求补接口 / 免去手动录接口。
 ---
 
 # Write API
 
 ## 定位
 
-造弹药 skill:基于需求生成 bruno 测试接口的"原料"——测试规格 + .bru + 多环境配置。跑测试 + DB 核实 + 出报告由 `/run-api-test` 接管,本 skill 不做。
+造弹药 skill:基于需求生成 bruno 测试接口的"原料"——接口测试规格 + .bru + 多环境配置。跑测试 + DB 核实 + 出报告由 `/run-api-test` 接管,本 skill 不做。
 
 ## HARD-GATE
 
@@ -33,9 +33,9 @@ description: 基于需求生成 bruno 测试接口(.bru + 测试规格 + 环境
 
 | skill | 关系 | 说明 |
 |---|---|---|
-| `run-api-test` | 下游 + 独立 | 消费本 skill 产的 .bru + 测试规格跑测试;本 skill 不调它,跑测试由用户显式触发;同一份 .bru 可被多次 run-api-test 复用 |
+| `run-api-test` | 下游 + 独立 | 消费本 skill 产的 .bru + 接口测试规格跑测试;本 skill 不调它,跑测试由用户显式触发;同一份 .bru 可被多次 run-api-test 复用 |
 | `db-query` | 复用 | S3 查真实测试数据;DB 副作用核实由 `/run-api-test` R4 做 |
-| `write-api-doc` | 独立并列 | 不互相调用;本 skill 产 .bru + 测试规格,write-api-doc 产 HTML 接口文档 |
+| `write-api-doc` | 独立并列 | 不互相调用;本 skill 产 .bru + 接口测试规格,write-api-doc 产 HTML 接口文档 |
 | `implementation` / `subagent-implement` | 上游 | 编码阶段,跑完触发本 skill |
 | `write-design-doc` | 独立 | 发布后按需产设计文档 |
 
@@ -56,11 +56,11 @@ description: 基于需求生成 bruno 测试接口(.bru + 测试规格 + 环境
 - 文件名不得包含 `/`、`:`、`*`、`?`、`"`、`<`、`>`、`|`
 
 产物文件名:
-- 测试规格:`docs/features/<feature-id>/<文件前缀>-api-spec.md`
+- 接口测试规格:`docs/features/<feature-id>/<文件前缀>-接口测试-spec.md`
 - .bru:`docs/bruno/<服务>/<文件前缀>/<接口名>/<场景>.bru`(按需求隔离,见 `references/collection-layout.md`)
 - bruno.json + environments:见 `references/environment-setup.md`
 
-测试报告 / JSONL 不由本 skill 产——`/run-api-test` 跑完后产,落 `docs/features/<feature-id>/`。
+接口测试报告 / JSONL 不由本 skill 产——`/run-api-test` 跑完后产,落 `docs/features/<feature-id>/`。
 
 ## 工作流
 
@@ -76,22 +76,22 @@ description: 基于需求生成 bruno 测试接口(.bru + 测试规格 + 环境
 - **拿到接口并用户确认** → 进 S2
 - **拿不到** → 报错"未检测到接口范围,请显式给接口清单或确认 spec 接口章节完整"并退出,不生成任何产物
 
-### S2. 生成测试规格文档
+### S2. 生成接口测试规格文档
 
 - **前置**:S1 接口清单已确认
-- **行为**:按 `references/api-spec-format.md` 六节结构生成测试规格文档;AI 做微服务识别 + 通用接口判断(prompt 见 `references/ai-prompts.md` §S2),结果写入 §1 接口清单的"服务"和"通用"列
+- **行为**:按 `references/接口测试-spec-format.md` 六节结构生成接口测试规格文档;AI 做微服务识别 + 通用接口判断(prompt 见 `references/ai-prompts.md` §S2),结果写入 §1 接口清单的"服务"和"通用"列
 - **用户校正**:AI 识别结果在 §1 列出后,用户可在 S3 前校正"服务"和"通用"两列,skill 以校正后为准
-- **结果**:落盘 `docs/features/<feature-id>/<文件前缀>-api-spec.md`
+- **结果**:落盘 `docs/features/<feature-id>/<文件前缀>-接口测试-spec.md`
 
 ### S3. 生成 bruno 测试接口
 
-- **前置**:S2 测试规格就绪(含用户校正后的服务/通用标注)
+- **前置**:S2 接口测试规格就绪(含用户校正后的服务/通用标注)
 - **行为**:**单次 AI 调用**生成全部 .bru(不拆两阶段、不逐接口循环,见 `references/ai-prompts.md` §S3)
   - .bru 格式 / 断言 / 入参 / docs 段 → `references/bru-format.md`
   - 落盘路径 / 按需求隔离 / 根级 bruno.json → `references/collection-layout.md`
   - 使用 db-query skill 获取基于数据库的测试数据
-  - 拿不到真实数据时 → 留 `{{var}}` 占位 + 测试规格 §3 标注"需用户手填"
-- **AI 调用失败**(超时/限流)→ 报"AI 增强失败" + 保留 S2 测试规格,**不继续 S4**
+  - 拿不到真实数据时 → 留 `{{var}}` 占位 + 接口测试规格 §3 标注"需用户手填"
+- **AI 调用失败**(超时/限流)→ 报"AI 增强失败" + 保留 S2 接口测试规格,**不继续 S4**
 - **结果**:全部 .bru 落盘到 `<服务>/<需求前缀>/<接口名>/<场景>.bru` + 根级 bruno.json 就绪
 
 ### S4. 首次接入环境准备
@@ -108,7 +108,7 @@ description: 基于需求生成 bruno 测试接口(.bru + 测试规格 + 环境
 S4 完成后 skill 结束。**不跑 bru run、不核实 DB、不出报告**。
 
 产物:
-- `docs/features/<feature-id>/<文件前缀>-api-spec.md`(测试规格)
+- `docs/features/<feature-id>/<文件前缀>-接口测试-spec.md`(接口测试规格)
 - `docs/bruno/<服务>/<文件前缀>/<接口名>/<场景>.bru`(测试接口,按需求隔离)
 - `docs/bruno/bruno.json` + `docs/bruno/environments/*.bru`(首次接入生成)
 
@@ -118,9 +118,9 @@ S4 完成后 skill 结束。**不跑 bru run、不核实 DB、不出报告**。
 |---|---|
 | 无新增接口 | 报错退出,不生成空产物 |
 | 接口范围三种来源都拿不到 | 报错退出 |
-| AI 拿不到真实测试数据 | 留 `{{var}}` 占位 + 测试规格标注"需用户手填",继续跑能跑的部分 |
-| AI 调用失败 | 报"AI 增强失败" + 保留测试规格,不继续 S4 |
-| 同需求重复触发 write-api | 覆盖该需求的 .bru + 覆盖测试规格(数据从当前需求 spec + DB 重新取) |
+| AI 拿不到真实测试数据 | 留 `{{var}}` 占位 + 接口测试规格标注"需用户手填",继续跑能跑的部分 |
+| AI 调用失败 | 报"AI 增强失败" + 保留接口测试规格,不继续 S4 |
+| 同需求重复触发 write-api | 覆盖该需求的 .bru + 覆盖接口测试规格(数据从当前需求 spec + DB 重新取) |
 | 跨需求同接口同场景 | 各需求独立保留,不覆盖(分别在自己需求目录下) |
 | 项目首次接入 | 自动创建 `docs/bruno/` + bruno.json + environments/ |
 | env 文件缺失 | S4 生成骨架 + AI 填 non-secret + 暂停提示用户填 secret |
@@ -130,7 +130,7 @@ S4 完成后 skill 结束。**不跑 bru run、不核实 DB、不出报告**。
 ## 质量检查
 
 跑完后自检:
-- 测试规格文档落盘 feature 目录,六节齐全
+- 接口测试规格文档落盘 feature 目录,六节齐全
 - .bru 按 `<服务>/<需求前缀>/<接口名>/<场景>.bru` 组织,无 `collection.bru`
 - 根级 `bruno.json` 存在;首次接入时 `environments/` + 三环境 .bru 生成,secret 留空
 - .bru 用旧版 tests 语法(`test("name", function() { res.getStatus()/res.getBody()... })`),无 `assert` 段、无 `function onResponse`
@@ -144,7 +144,7 @@ S4 完成后 skill 结束。**不跑 bru run、不核实 DB、不出报告**。
 ## 收尾
 
 提示用户:
-1. 测试规格位置(`<文件前缀>-api-spec.md`)
+1. 接口测试规格位置(`<文件前缀>-接口测试-spec.md`)
 2. .bru collection 位置(`docs/bruno/<服务>/<文件前缀>/<接口名>/`)
 3. 首次接入:bruno.json + environments/*.bru 已生成,需填 `local.bru` 的 secret 变量
 4. 下一步:**跑 `/run-api-test` 跑测试 + 核实 DB + 出报告**

package/dist/.claude-template/skills/write-api/assets/{template-api-spec.md → template-/346/216/245/345/217/243/346/265/213/350/257/225-spec.md}

@@ -1,6 +1,6 @@
 # 接口测试规格模板
 
-适用于 feature 编码完成后,由 `write-api` skill 在 S2 生成。默认输出到 `docs/features/<feature-id>/<文件前缀>-api-spec.md`。
+适用于 feature 编码完成后,由 `write-api` skill 在 S2 生成。默认输出到 `docs/features/<feature-id>/<文件前缀>-接口测试-spec.md`。
 
 本模板由 AI 在 S2 填充:§1 接口清单的"服务"和"通用"列由 AI 判断(见 SKILL.md 的 S2 prompt 指引),用户可在 S3 前手动校正。
 

package/dist/.claude-template/skills/write-api/references/{api-spec-format.md → /346/216/245/345/217/243/346/265/213/350/257/225-spec-format.md}

@@ -1,8 +1,8 @@
-# S2 测试规格文档格式规范
+# S2 接口测试规格文档格式规范
 
 ## 六节结构(必须完整)
 
-测试规格文档 `<文件前缀>-api-spec.md` 必须含以下六节,顺序固定:
+接口测试规格文档 `<文件前缀>-接口测试-spec.md` 必须含以下六节,顺序固定:
 
 ### §1. 接口清单
 
@@ -97,7 +97,7 @@
 
 ## 模板
 
-完整填充示例见 `assets/template-api-spec.md`,AI 生成时以它为骨架填充。
+完整填充示例见 `assets/template-接口测试-spec.md`,AI 生成时以它为骨架填充。
 
 ## 与下游 skill 的契约
 

package/dist/.claude-template/skills/write-plan/SKILL.md

@@ -47,11 +47,13 @@ spec 中"不可留到实现期的决策"或影响任务拆分的【待确认】,
 
 - 按依赖和风险拆,不按模板拆:数据/契约 → 后端 → 前端(依实际依赖调整)。
 - **默认合并**(减少审查次数,写明理由):同文件多章节改写归单 implementer;schema 改动 + 对应 migration 合一。拆开仅限:任务过大撑爆上下文、强耦合需实时反馈。
+- **任务 = 工作包**(连贯的功能块/层块,可独立验证):「改 1 字段 / 加 1 参数 / 调 1 处样式」级微任务并入同层/同功能任务;总任务数一般 ≤6,超过先检查是否拆太细,优先合并。
 - **测试不进 plan**:单元测试 / 接口测试是代码完成后的独立流程(`write-unit-test-spec` → `write-unit-test-code`、`write-api` → `run-api-test`,各自从 spec 派生),plan 不排测试任务、不写必测路径 / 测试命令、implementer 实现期不写新测试。plan 对测试的唯一要求是完成定义:任务提交后既有测试不被弄红(改动弄红的既有测试须同步修正)。
 - 能独立验证的尽量独立成任务;高风险任务写保护条件和回退思路。
 - **可独立提交的任务标「独立提交」**:任务完成后仓库处于可工作状态(能编译、相关测试不红)→ 标「独立提交:是」并给建议提交粒度 + commit message 主题;强耦合(完成后仓库不可工作、需后续任务才闭合)→ 不标,说明随哪个任务一起提交。判断依据写进任务,不机械地每任务都标——小步提交是为了原子化历史(好 review / revert / bisect),不是为了凑提交数。
 - 可并行任务显式成批 + 写明文件集/公共契约/测试状态互不冲突;不确定 → 串行。
 - 不重新打开 spec 已锁定的契约;不把简单需求拆碎。
+- **执行方式建议(终判,写进 index)**:仅当三条件同时成立才建议 `/subagent-implement`——任务跨 ≥3 个相互独立的模块、预估变更文件总数 ≥10、任务间无需实时反馈(可独立派任);否则建议 `/implementation`,拿不准 → implementation。不以任务量或跨域数为依据(小全栈需求天然跨 3 域,任何需求都拆得出 ≥3 任务)。
 
 ## 消费模型与防漂移
 
@@ -80,7 +82,7 @@ docs/guides/ 存在时(init-project-guides 产出),写 plan 前按下表读规
 
 ## index.md 必备内容
 
-feature-id/负责人/日期/来源 spec 摘要(需求阶段由 `cgraphx features` 从产物自动派生,不手填状态) · 目标与范围 · 明确不包含 · 计划文件清单(哪些存在/不涉及) · 总任务清单(每个任务标对应 spec 条款 + 是否「独立提交」) · 全局依赖图(Mermaid 或文本;没有依赖就直说,不强行造依赖) · 推荐执行顺序 · 可并行批次(文件/模块/验证状态不重叠依据) · 必须严格执行的契约 · 实现手段决策(自主项:选项+推荐+理由;回跳项:业务拍板结论) · 适用规范(文件 + 章节标题) · **提交规范**(有「独立提交」任务时必备:从 `git-standards.md` 结晶的提交消息格式 + 提交前检查点,实施期据此提交,precommit 门禁仅兜底) · 允许局部工程适配的范围 · Plan 冲突上报规则 · 关键风险与防跑偏约束 · 待确认项。
+feature-id/负责人/日期/来源 spec 摘要(需求阶段由 `cgraphx features` 从产物自动派生,不手填状态) · 目标与范围 · 明确不包含 · 计划文件清单(哪些存在/不涉及) · 总任务清单(每个任务标对应 spec 条款 + 是否「独立提交」) · 全局依赖图(Mermaid 或文本;没有依赖就直说,不强行造依赖) · 推荐执行顺序 · 可并行批次(文件/模块/验证状态不重叠依据) · 必须严格执行的契约 · 实现手段决策(自主项:选项+推荐+理由;回跳项:业务拍板结论) · **执行方式建议**(`/implementation` 或 `/subagent-implement` + 理由,判据见「拆分规则」终判条) · 适用规范(文件 + 章节标题) · **提交规范**(有「独立提交」任务时必备:从 `git-standards.md` 结晶的提交消息格式 + 提交前检查点,实施期据此提交,precommit 门禁仅兜底) · 允许局部工程适配的范围 · Plan 冲突上报规则 · 关键风险与防跑偏约束 · 待确认项。
 
 ## 子计划文件(按需,不建空文件)
 
@@ -133,7 +135,7 @@ feature-id/负责人/日期/来源 spec 摘要(需求阶段由 `cgraphx features
 
 ## 收尾
 
-产物落盘后自动跑 `cgraphx features sync`(更新本人需求索引,本地幂等)。全部通过后推荐执行模式一句话:**1-3 文件/单模块 → `/implementation`;跨域多任务 → `/subagent-implement`。** 不自动开始实现,停下等用户。找需求目录:`cgraphx features list --mine`。
+产物落盘后自动跑 `cgraphx features sync`(更新本人需求索引,本地幂等)。全部通过后推荐执行模式一句话(即 index「执行方式建议」):**小规模 → `/implementation`;大规模(≥10 文件且 ≥3 独立模块、任务可独立派任)→ `/subagent-implement`。** 不自动开始实现,停下等用户。找需求目录:`cgraphx features list --mine`。
 
 ## 红线(绝对不能做)
 

package/dist/.claude-template/skills/write-ui-test/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: write-ui-test
+description: 从需求 spec 派生 UI 功能测试用例规格(一功能点一用例,每条含功能点名/操作步骤/预期表现/数据前提/登录账号)。流程:读需求 spec 识别功能点 → 功能点清单用户确认 → 派生用例 → 用例清单用户确认 → 落盘 docs/features/<feature-id>/ui功能测试/。本 skill 不碰浏览器、不执行、不出报告——那是 /run-ui-test 的职责。不调 run-ui-test、不修代码、不改需求 spec。Use when 用户要求写 UI 功能测试用例 / 生成界面功能测试 / 准备页面功能测试 / write-ui-test / 需求要在界面上验一遍。
+---
+
+# Write UI Test
+
+## 定位
+
+造弹药 skill:从需求 spec 派生 UI 功能测试的用例规格——agent 打开浏览器按它执行是 `/run-ui-test` 的事,本 skill 只做用例派生,不碰浏览器。
+
+用例规格是**自然语言用例**,不是可执行脚本:执行期由 agent 读用例、通过 Playwright MCP 实时驱动浏览器。
+
+## HARD-GATE
+
+- **不碰浏览器** —— 本 skill 全程不启动/不驱动浏览器,不截图
+- **不编造功能点** —— 用例必须来自需求 spec 的功能点/验收标准,spec 里没有的功能点不派生
+- **用例清单未经用户确认不落盘**
+- **不重新定义 spec 已锁定的业务规则** —— 发现 spec 与代码现实不符,标注【待确认】而不是自行解释
+
+## Trigger
+
+**使用此 skill 当**:
+- 用户要求"写 UI 功能测试用例""生成界面功能测试""write-ui-test"
+- 用户在 `/implementation` 或 `/subagent-implement` 完成编码后,要在界面上验一遍需求
+- 接口测试跑完,用户要继续验 UI 层(推荐顺序,非硬前置)
+
+**不要使用此 skill 当**:
+- 跑测试 / 驱动浏览器 → 用 `/run-ui-test`
+- 接口测试 → 用 `/write-api` / `/run-api-test`
+- 视觉回归 / 跨浏览器兼容 / 性能测试 → 非本流程目标,不接
+- 写 spec / plan → 用 `/write-spec` / `/write-plan`
+
+## 与既有 skill 边界
+
+| skill | 关系 | 说明 |
+|---|---|---|
+| `run-ui-test` | 下游 + 独立 | 消费本 skill 产的用例规格驱动浏览器;本 skill 不调它,执行由用户显式触发;同一份用例规格可被多次 run-ui-test 复用 |
+| `write-api` / `run-api-test` | 平行 | 接口层测试;本流程推荐在其之后跑,但非硬前置 |
+| `implementation` / `subagent-implement` | 上游 | 编码完成后触发本 skill |
+
+## 依赖
+
+- `docs/features/<feature-id>/<文件前缀>-spec.md` 存在(U1 派生输入)
+- 目标项目编码已完成(推荐;纯前端需求同理)
+- **不依赖** Playwright MCP(本 skill 不碰浏览器;执行期才需要,归 `/run-ui-test` 校验)
+
+## feature-id 与文件前缀规则
+
+复用既有规则(同 `/write-api` / `/run-api-test` / `/write-spec` 的算法):
+
+- feature-id 格式:`YYYY-MM-DD-[业务ID-]<标题>`
+- 文件前缀:有业务ID = `<业务ID>-<标题>`,无业务ID = `<标题>`
+- 标题段允许中文、英文或混合,**不得**对中文做英文 slug 转换
+- 文件名不得包含 `/`、`:`、`*`、`?`、`"`、`<`、`>`、`|`
+
+产物文件名:
+
+- 用例规格:`docs/features/<feature-id>/ui功能测试/<文件前缀>-ui功能测试-spec.md`
+
+`ui功能测试/` 目录不存在则创建(与 plan/ 平级,按需求隔离;截图与报告同目录,由 `/run-ui-test` 产)。
+
+## 工作流
+
+按 U1-U3 顺序执行,格式规范见 `references/用例规格-format.md`。
+
+### U1. 确认需求与功能点范围
+
+- **前置**:用户指定需求(feature-id / spec / 需求名)
+- **行为**:
+  - 读 `docs/features/<feature-id>/<文件前缀>-spec.md`
+  - 从功能描述/验收标准识别功能点(用户可显式给功能点清单,优先级最高)
+- **功能点清单必须显示给用户确认**——避免 AI 理解偏差测错范围;用户确认后才进 U2
+- **拿不到功能点**(spec 缺失 / 无验收标准可派生)→ 报错退出,不产空产物
+
+### U2. 派生用例
+
+- **前置**:U1 功能点清单已确认
+- **行为**:按 `references/用例规格-format.md` 派生——**一功能点一用例**,每条含五要素:
+  - 功能点名(与截图命名对应)
+  - 操作步骤(自然语言,页面动线)
+  - 预期表现(UI 上应看到什么——渲染/跳转/提示/输入回显;**不写 DB 断言**,本流程不验库)
+  - 数据前提(需要什么存量数据;无则写「无」)
+  - 登录账号(需要登录时记测试账号;拿不到留【待用户填写】;无需登录写「无需登录」)
+- **入口 URL**:记入用例规格 §1 概览;拿不到留【需用户填写】
+- **结果**:用例草稿
+
+### U3. 确认落盘
+
+- **前置**:U2 用例草稿就绪
+- **行为**:用例清单(功能点名 + 步骤摘要 + 数据前提)显示给用户确认;确认后按格式规范落盘
+- **用户校正**:增删用例、改步骤/预期/数据前提,以校正后为准
+- **结果**:`docs/features/<feature-id>/ui功能测试/<文件前缀>-ui功能测试-spec.md` 落盘
+
+## 工作流结束
+
+U3 完成后 skill 结束。**不碰浏览器、不执行用例、不出报告**。
+
+## 异常速查
+
+| 场景 | 行为 |
+|---|---|
+| 需求 spec 缺失 | 报错退出,提示先跑 `/write-spec` |
+| spec 无可派生功能点/验收标准 | 报错退出,不产空产物 |
+| 登录账号拿不到 | 留【待用户填写】,继续派生其余内容 |
+| 入口 URL 拿不到 | §1 概览留【需用户填写】,继续派生 |
+| 同需求重复触发 | 覆盖该需求已有用例规格(从当前需求 spec 重新派生) |
+
+## 质量检查
+
+跑完后自检:
+- 用例规格落盘 `ui功能测试/` 目录,四节齐全(概览/用例/数据前提清单/登录说明)
+- 一功能点一用例,五要素齐全,无编造的功能点
+- 预期表现只写 UI 表现,无 DB 断言
+- 功能点清单与用例清单都有用户确认环节
+- 没碰浏览器,没执行用例,没出报告
+
+## 收尾
+
+提示用户:
+1. 用例规格位置(`<文件前缀>-ui功能测试-spec.md`)
+2. 待用户填写项(登录账号 / 入口 URL,若有)
+3. 下一步:**跑 `/run-ui-test` 驱动浏览器执行 + 截图 + 出报告**
+
+不主动调用 `/run-ui-test` 或其他下游 skill。不写 knowledge 文件。不修改 spec / plan / 代码。

package/dist/.claude-template/skills/write-ui-test/references//347/224/250/344/276/213/350/247/204/346/240/274-format.md

@@ -0,0 +1,94 @@
+# U2/U3 UI 功能测试用例规格格式规范
+
+## 四节结构(必须完整)
+
+用例规格文档 `<文件前缀>-ui功能测试-spec.md` 必须含以下四节,顺序固定。
+
+### §1. 概览
+
+```markdown
+## 1. 概览
+
+| 项 | 值 |
+|---|---|
+| 来源需求 | <文件前缀>-spec.md |
+| 功能点数 | 3 |
+| 入口 URL | http://127.0.0.1:5173/admin |
+| 需要登录 | 是 |
+
+截图约定:截图存本目录,按功能点命名(`<功能点名>.png`,同功能点多张追加 `-2`/`-3`)。
+```
+
+- 入口 URL 拿不到 → 填【需用户填写】,`/run-ui-test` 执行前会向用户要
+- 入口 URL 是执行默认值,用户触发 `/run-ui-test` 时可覆盖
+
+### §2. 用例
+
+**一功能点一小节**,五要素齐全。最好案例:
+
+```markdown
+## 2. 用例
+
+### 用例 1:新建客户
+
+- **功能点名**:新建客户
+- **操作步骤**:
+  1. 左侧菜单点「客户管理」进入列表页
+  2. 点右上角「新建」按钮,弹出新建表单
+  3. 填写:客户名称「测试客户-0825」、联系电话「13800138000」、所属行业选「制造业」
+  4. 点「保存」
+- **预期表现**:
+  - 表单校验通过,无红色错误提示
+  - 提示「保存成功」
+  - 返回列表页,第一行出现「测试客户-0825」
+- **数据前提**:无(本用例自行创建)
+- **登录账号**:见 §4
+
+### 用例 2:编辑客户
+
+- **功能点名**:编辑客户
+- **操作步骤**:
+  1. 客户列表页找到「华东贸易」
+  2. 点该行「编辑」,表单回填现有值
+  3. 把联系电话改为「13900139000」,点「保存」
+- **预期表现**:提示「保存成功」;列表中「华东贸易」的联系电话显示为「13900139000」
+- **数据前提**:存在客户「华东贸易」(见 §3)
+- **登录账号**:见 §4
+```
+
+要求:
+
+- 操作步骤写**页面动线**(点什么、填什么),不写接口/代码细节
+- 预期表现只写 **UI 上可观察的**(渲染/跳转/提示/回显),**不写 DB 断言**——本流程不验库,数据层归接口测试
+- 功能点名同时是截图文件名,不得含 `/`、`:`、`*`、`?`、`"`、`<`、`>`、`|`
+
+### §3. 数据前提清单
+
+汇总各用例的数据前提,供 `/run-ui-test` 执行前人工核对备齐:
+
+```markdown
+## 3. 数据前提清单
+
+| 用例 | 数据前提 | 状态 |
+|---|---|---|
+| 用例 1:新建客户 | 无 | - |
+| 用例 2:编辑客户 | 存在客户「华东贸易」 | 待人工备 |
+```
+
+- 数据前提一律**人工准备**(本流程不自动造数据);「状态」列初始全填「待人工备」
+- 用例自行创建的(如用例 1)填「无」
+
+### §4. 登录说明
+
+```markdown
+## 4. 登录说明
+
+- 登录页:`/login`(入口 URL 跳转后第一个页面)
+- 测试账号:`admin` / 【待用户填写】
+- 登录动线:输入账号密码 → 点「登录」→ 跳转首页
+
+若登录遇到验证码/SSO,`/run-ui-test` 会暂停请人工介入。
+```
+
+- 账号拿不到 → 密码留【待用户填写】
+- 无需登录的应用写「无需登录」并省略登录动线