tuner-testkit 5.2.0__tar.gz → 5.3.0__tar.gz

{tuner_testkit-5.2.0/tuner_testkit.egg-info → tuner_testkit-5.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tuner-testkit
-Version: 5.2.0
+Version: 5.3.0
 Summary: Shared test runtime, recorders, and DNA overlay for SUT test repos
 Author: tuner-testkit contributors
 License-Expression: MIT
@@ -221,4 +221,4 @@ uv sync --extra all
 （被测系统 = 平台本身，uv workspace 成员，共用 `.venv`）：路线图在 `dogfood/assets/domain-notes/platform/roadmap.md`，
 验收活文档在 `dogfood/tests/features/`。见 [`dogfood/README.md`](dogfood/README.md)。
 
-5.2.0 发行说明（work task / 测试设计 / 证据附件）见 [`docs/changelog/TEMPLATE-5.2.0.md`](docs/changelog/TEMPLATE-5.2.0.md)；5.1.0 发行说明（工作台 / meta stamp / `--json`）见 [`docs/changelog/TEMPLATE-5.1.0.md`](docs/changelog/TEMPLATE-5.1.0.md)；5.0.0（Plane Job 协议退场、`tuner-workspace`）见 [`TEMPLATE-5.0.0.md`](docs/changelog/TEMPLATE-5.0.0.md)；4.3.0 见 [`TEMPLATE-4.3.0.md`](docs/changelog/TEMPLATE-4.3.0.md)；3.x → 4.x 迁移见 [`TEMPLATE-4.0.0.md`](docs/changelog/TEMPLATE-4.0.0.md)。平台能力地图见 [`INDEX.md`](INDEX.md)。
+5.3.0 发行说明（功能用例集 `assets/testcases/`）见 [`docs/changelog/TEMPLATE-5.3.0.md`](docs/changelog/TEMPLATE-5.3.0.md)；5.2.0 发行说明（work task / 测试设计 / 证据附件）见 [`docs/changelog/TEMPLATE-5.2.0.md`](docs/changelog/TEMPLATE-5.2.0.md)；5.1.0 发行说明（工作台 / meta stamp / `--json`）见 [`docs/changelog/TEMPLATE-5.1.0.md`](docs/changelog/TEMPLATE-5.1.0.md)；5.0.0（Plane Job 协议退场、`tuner-workspace`）见 [`TEMPLATE-5.0.0.md`](docs/changelog/TEMPLATE-5.0.0.md)；4.3.0 见 [`TEMPLATE-4.3.0.md`](docs/changelog/TEMPLATE-4.3.0.md)；3.x → 4.x 迁移见 [`TEMPLATE-4.0.0.md`](docs/changelog/TEMPLATE-4.0.0.md)。平台能力地图见 [`INDEX.md`](INDEX.md)。

{tuner_testkit-5.2.0 → tuner_testkit-5.3.0}/README.md

@@ -173,4 +173,4 @@ uv sync --extra all
 （被测系统 = 平台本身，uv workspace 成员，共用 `.venv`）：路线图在 `dogfood/assets/domain-notes/platform/roadmap.md`，
 验收活文档在 `dogfood/tests/features/`。见 [`dogfood/README.md`](dogfood/README.md)。
 
-5.2.0 发行说明（work task / 测试设计 / 证据附件）见 [`docs/changelog/TEMPLATE-5.2.0.md`](docs/changelog/TEMPLATE-5.2.0.md)；5.1.0 发行说明（工作台 / meta stamp / `--json`）见 [`docs/changelog/TEMPLATE-5.1.0.md`](docs/changelog/TEMPLATE-5.1.0.md)；5.0.0（Plane Job 协议退场、`tuner-workspace`）见 [`TEMPLATE-5.0.0.md`](docs/changelog/TEMPLATE-5.0.0.md)；4.3.0 见 [`TEMPLATE-4.3.0.md`](docs/changelog/TEMPLATE-4.3.0.md)；3.x → 4.x 迁移见 [`TEMPLATE-4.0.0.md`](docs/changelog/TEMPLATE-4.0.0.md)。平台能力地图见 [`INDEX.md`](INDEX.md)。
+5.3.0 发行说明（功能用例集 `assets/testcases/`）见 [`docs/changelog/TEMPLATE-5.3.0.md`](docs/changelog/TEMPLATE-5.3.0.md)；5.2.0 发行说明（work task / 测试设计 / 证据附件）见 [`docs/changelog/TEMPLATE-5.2.0.md`](docs/changelog/TEMPLATE-5.2.0.md)；5.1.0 发行说明（工作台 / meta stamp / `--json`）见 [`docs/changelog/TEMPLATE-5.1.0.md`](docs/changelog/TEMPLATE-5.1.0.md)；5.0.0（Plane Job 协议退场、`tuner-workspace`）见 [`TEMPLATE-5.0.0.md`](docs/changelog/TEMPLATE-5.0.0.md)；4.3.0 见 [`TEMPLATE-4.3.0.md`](docs/changelog/TEMPLATE-4.3.0.md)；3.x → 4.x 迁移见 [`TEMPLATE-4.0.0.md`](docs/changelog/TEMPLATE-4.0.0.md)。平台能力地图见 [`INDEX.md`](INDEX.md)。

{tuner_testkit-5.2.0 → tuner_testkit-5.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tuner-testkit"
-version = "5.2.0"
+version = "5.3.0"
 description = "Shared test runtime, recorders, and DNA overlay for SUT test repos"
 readme = "README.md"
 license = "MIT"

{tuner_testkit-5.2.0 → tuner_testkit-5.3.0}/tuner_testkit/__init__.py

@@ -2,4 +2,4 @@
 
 from __future__ import annotations
 
-__version__ = "5.2.0"
+__version__ = "5.3.0"

{tuner_testkit-5.2.0 → tuner_testkit-5.3.0}/tuner_testkit/apps/dna/dna_payload/.cursor/rules/assets-knowledge.mdc

@@ -2,7 +2,7 @@
 description: assets/ is the knowledge base for humans and the LLM; enforce provenance metadata, raw-vs-curated boundaries, and grounding (consult INDEX before generating)
 globs: assets/**
 alwaysApply: false
-version: 1.1.0
+version: 1.2.0
 ---
 
 # assets — 知识层硬约束
@@ -25,8 +25,9 @@ SUT 自学习见 `docs/spec/sut-self-learning.md`；design schema 见
 ## 目录与元数据
 
 - 目录分类固定：`ddl/<datasource>/`、`sql/`、`usecases/<domain>/`、
-  `domain-notes/<domain>/`、`explore/<app>/`、`design/<app>/`、`testreport/`
-  （新增类别前先改 spec，再改本 rule）。
+  `domain-notes/<domain>/`、`explore/<app>/`、`design/<app>/`、`testdesign/`、
+  `testcases/<模块>/`、`testreport/`
+  （新增类别前先改 spec，再改本 rule）。功能用例集见 `docs/spec/testcase-syntax.md`。
 - 人工/半自动区文件头必须带元数据：`domain / source / date / version / confidence`
   （Markdown 用 YAML front-matter，SQL 用顶部 `--` 注释）。
 - `explore/` 与 `design/` 还应填 `evidence`（run_id 列表）。

tuner_testkit-5.3.0/tuner_testkit/apps/dna/dna_payload/.cursor/rules/testcases.mdc

@@ -0,0 +1,29 @@
+---
+description: Functional testcases live under assets/testcases/<module>/<feature>.md with four heading levels and stable CASE IDs
+globs: assets/testcases/**
+alwaysApply: false
+version: 1.1.0
+---
+
+# testcases — 功能用例集
+
+完整规范：`docs/spec/testcase-syntax.md`。生成或改写走 skill `maintain-testcases`。
+
+## 位置
+
+- 总索引：`assets/testcases/README.md`
+- 模块说明：`assets/testcases/<模块>/README.md`
+- 一个功能一个文件：`assets/testcases/<模块>/<功能>.md`
+- 不要写到 `usecases/`、`testdesign/` 或 `tests/features/`。
+
+## 功能文件
+
+- `# 测试用例` → `## <模块>` → `### <功能>` → `#### <缩写><四位序号> 正向-|反向-<测试点>`
+- 二级标题等于目录名，三级标题等于文件名。
+- 每条用例必填 `- 步骤：` 与 `- 预期：`。
+- ID 形如 `User-Login0001`：`id_prefix` 是功能英文缩写，后接 4 位序号。全库唯一；不改号、不复用、不重排。
+
+## 禁止
+
+- 密码、token、Cookie、Authorization。账号只写 `account_id`。
+- 没有出处的业务规则。出处是用户本次说明，或索引能指向的知识。

tuner_testkit-5.3.0/tuner_testkit/apps/dna/dna_payload/.cursor/skills/maintain-testcases/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: maintain-testcases
+version: 1.1.0
+description: Creates and updates the functional testcase set under assets/testcases/<module>/<feature>.md using the four-level heading template and stable feature-prefixed IDs such as User-Login0001. Use when the user asks to 编写/生成/维护测试用例, add a module or feature case file, or mentions assets/testcases or case ID. Do not use for testdesign click-paths or behave .feature files.
+---
+
+# Maintain testcases
+
+## Scope
+
+- **Write**: `assets/testcases/**` only.
+- **Must follow**: `docs/spec/testcase-syntax.md`.
+- **Out of scope**: `assets/testdesign/`（用 `derive-test-design`）、`tests/features/**`（用 `feature-authoring`）、pytest。
+
+## Before writing
+
+1. 读 `assets/testcases/README.md` 与目标模块的 `README.md`（没有就先按下面的模板建）。
+2. 读 `INDEX.md`；存在 `INDEX.project.md` 时一并读。只采用已有 usecase / domain-notes / explore / design，或用户本次给出的事实。
+3. 功能文件已有 `id_prefix` 就沿用，不要另起缩写。新建功能时用功能名的英文词，每词首字母大写、`-` 连接（`用户登录` → `User-Login`），写入 `id_prefix`。确认这个前缀没有被别的功能占用。
+4. 序号只在该前缀内递增：`rg -N "^#### User-Login[0-9]{4} " assets/testcases`。下一条 = 最大序号 + 1，4 位补零。该前缀还没有用例时从 `0001` 起，得到 `User-Login0001`。
+
+## Where a case goes
+
+- 已有同名 `<模块>/<功能>.md`：只追加或修改四级标题，不新建第二份文件。
+- 模块已存在、功能没有：新建 `assets/testcases/<模块>/<功能>.md`，并在该模块 README 的功能清单加一行。
+- 模块也没有：新建目录和模块 README，再在总索引的模块表加一行，然后写功能文件。
+
+## Templates
+
+功能文件：
+
+```markdown
+---
+kind: testcase
+id: <ascii-slug>
+id_prefix: <Feature-Name>
+title: <功能>
+module: <模块>
+source: <依据路径或需求名>
+version: 1.0.0
+confidence: medium
+---
+
+# 测试用例
+## <模块>
+### <功能>
+#### <Feature-Name>0001 正向-<测试点>
+- 步骤：<操作>
+- 预期：<可观察结果>
+#### <Feature-Name>0002 反向-<测试点>
+- 步骤：<操作>
+- 预期：<可观察结果>
+```
+
+总索引 `assets/testcases/README.md`：
+
+```markdown
+---
+kind: testcase-index
+title: 测试用例模块索引
+version: 1.0.0
+confidence: high
+---
+
+# 测试用例模块索引
+
+规范：`docs/spec/testcase-syntax.md`。一个功能一个文件，用例写在四级标题下，ID 全库唯一且不重排。
+
+## 放置规则
+
+- 新用例归入已有模块的功能文件；对不上时才新增模块目录。
+- 目录名 = 二级标题；文件名 = 三级标题。
+- 不写密码、token、Cookie。账号只写 `account_id`。
+
+## 模块
+
+| 模块 | 目录 | 范围 | 状态 |
+| --- | --- | --- | --- |
+| <模块> | `assets/testcases/<模块>/` | <一句话> | 在用 |
+```
+
+模块 README：
+
+```markdown
+---
+kind: testcase-module
+id: <ascii-slug>
+title: <模块>
+module: <模块>
+version: 1.0.0
+confidence: high
+---
+
+# <模块>
+
+## 范围
+
+## 不测
+
+## 功能
+
+| 功能 | 文件 |
+| --- | --- |
+| <功能> | [<功能>.md](<功能>.md) |
+
+## 相关知识
+
+无
+```
+
+## Update rules
+
+- 改步骤或预期：保留原 ID 和 `id_prefix`，bump 该文件 `version`。
+- 废弃：标题加 `（废弃）`，补 `- 状态：废弃` 与原因。不删除该四级标题，不把 ID 让给新用例。
+- 拆文件或改功能名：用例带着原 ID 搬家，并改两边 README 的链接。
+
+## Finish
+
+```bash
+python -m tuner_testkit.testcases assets/testcases
+uv run tuner-workspace meta stamp <改过的.md> --kind <testcase|testcase-module|testcase-index>
+```
+
+校验失败就改文件再跑，通过后再停。有 `INDEX.project.md` 时在其知识表登记新功能文件的路径（只读 front-matter）；平台仓没有业务用例时不要往根 `INDEX.md` 填模块明细。

{tuner_testkit-5.2.0 → tuner_testkit-5.3.0}/tuner_testkit/apps/dna/dna_payload/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- version: 1.6.0 -->
+<!-- version: 1.7.0 -->
 # AGENTS — 平台总入口（轻量 DM）
 
 > 本文件是"repo as a platform"的**稳定世界观**：只写不常变的分层结构与角色。
@@ -13,7 +13,7 @@
 
 | 层 | 目录 | 职责 | 谁运行 |
 | --- | --- | --- | --- |
-| 知识层 | `assets/` | 给人和 LLM 阅读、生成测试代码的基础知识（ddl / sql / usecases / domain-notes / explore / design / testdesign / testreport）。见 `docs/spec/assets-knowledge-syntax.md`。 | 只读引用 |
+| 知识层 | `assets/` | 给人和 LLM 阅读、生成测试代码的基础知识（ddl / sql / usecases / domain-notes / explore / design / testdesign / testcases / testreport）。见 `docs/spec/assets-knowledge-syntax.md`。 | 只读引用 |
 | 运行库 | `tuner_testkit/`（PyPI：`tuner-testkit`） | 公共运行时与 CLI（db / logging / api_test / page_test / fake / recorders / dna）。SUT 用 `uv` 锁版本。 | `import tuner_testkit`；`tuner-recorder` 等 scripts |
 | 组件层 | `packages/` | **本仓业务资产**（api_objects / page_objects / action_words），不是 kit 运行库。 | 被 import |
 | 工具层 | `apps/` | **本仓私有**工具。公共工具在 `tuner_testkit.apps`。见 `docs/spec/apps-authoring-syntax.md`。 | `python -m apps.<name>`（仅项目工具） |
@@ -51,6 +51,7 @@ flowchart TD
   Q -->|"新建/更新项目仓"| Init["tuner-init / tuner-dna / release-template"]
   Q -->|"读/策展/索引知识"| Idx["查 INDEX.md + maintain-index skill"]
   Q -->|"发布任务 / 测试设计 / 端到端执行"| Task["work/tasks + tuner-task\ndocs/spec/work-task.md"]
+  Q -->|"生成或维护功能测试用例"| Cases["maintain-testcases skill\ndocs/spec/testcase-syntax.md"]
 ```
 
 - **学习被测系统** → `.cursor/agents/sut-self-learning.md`（编排 explore → freeze → design；规格 `docs/spec/sut-self-learning.md`；任务 log 见 `docs/spec/agent-task-log.md`）。
@@ -61,6 +62,7 @@ flowchart TD
 - **仓库初始化/发布** → `tuner-init scaffold`（骨架 + 依赖 `tuner-testkit` + 一次 `tuner-dna sync`）+ `release-template` skill。下游升 kit：`uv add tuner-testkit==x.y.z` 然后 `tuner-dna sync`，再提交。
 - **读/索引知识** → 先查 `INDEX.md`；若存在 `INDEX.project.md` 则一并查。索引维护用 `maintain-index` skill。
 - **发布任务** → `tuner-task create` 写入 `work/tasks/`。测试设计走 `derive-test-design`；端到端点击报告走 `run-test-execution`。缺人才能决定的通道（如后端日志）用 `tuner-task ask`，不要猜。
+- **功能测试用例** → skill `maintain-testcases`，落在 `assets/testcases/<模块>/<功能>.md`（规格 `docs/spec/testcase-syntax.md`）。这不是测试设计，也不直接产出 `.feature`。
 
 ## 5. 全程硬约束（跨分支）
 

{tuner_testkit-5.2.0 → tuner_testkit-5.3.0}/tuner_testkit/apps/dna/dna_payload/MANIFEST.txt

@@ -1,5 +1,5 @@
 {
-  "files": 62,
+  "files": 65,
   "paths": [
     ".cursor/rules",
     ".cursor/skills",

{tuner_testkit-5.2.0 → tuner_testkit-5.3.0}/tuner_testkit/apps/dna/dna_payload/docs/spec/assets-knowledge-syntax.md

@@ -17,13 +17,16 @@ assets/
 ├── explore/<app>/<name>.md        # 探索式测试产出的能力清单 / 站点地图（半自动）
 ├── design/<app>/<route-slug>.md   # API↔DB effects 收敛知识（见 design-knowledge-syntax）
 ├── testdesign/<sut>/<slug>.md     # 测试设计（见 test-design-syntax）；执行反馈回写在此
+├── testcases/README.md            # 功能用例集总索引（见 testcase-syntax）
+├── testcases/<模块>/README.md     # 模块范围与功能清单
+├── testcases/<模块>/<功能>.md     # 该功能的全部用例（四级标题 + CASE ID）
 ├── testreport/<name>.md           # 测试报告类原始资产
 └── CHANGELOG.md                   # 自动区变更流水(供 maintain-index 读取 delta)
 ```
 
 - **自动区**（工具产出，可被覆盖重写）：`ddl/`、以及每次生成会追加 `CHANGELOG.md`。
   人不手改这些文件的内容语义；要更新就重跑工具。
-- **人工/半自动区**：`sql/`、`usecases/`、`domain-notes/`、`explore/`、`design/`、`testdesign/`、`testreport/`。
+- **人工/半自动区**：`sql/`、`usecases/`、`domain-notes/`、`explore/`、`design/`、`testdesign/`、`testcases/`、`testreport/`。
 - `apidoc/` **不单列**：人工导入的接口说明放 `domain-notes/` 或 `usecases/`；
   运行时冻结的契约在 `packages/api_objects/`。是否再拆目录留给下游实践决定。
 

{tuner_testkit-5.2.0 → tuner_testkit-5.3.0}/tuner_testkit/apps/dna/dna_payload/docs/spec/metadata-conventions.md

@@ -13,7 +13,7 @@ description: 统一 front-matter / run manifest 字段家族，供 catalog、工
 
 | 字段 | 类型 | 含义 |
 | --- | --- | --- |
-| `kind` | string | `app` / `action_word` / `testreport` / `inbox` / `question` / `task` / `testdesign` / `explore` / `design` / `usecase` / `domain-note` |
+| `kind` | string | `app` / `action_word` / `testreport` / `inbox` / `question` / `task` / `testdesign` / `testcase` / `testcase-module` / `testcase-index` / `explore` / `design` / `usecase` / `domain-note` |
 | `id` | string | 稳定标识（`tool_id` / `word_id` / 报告 slug） |
 | `title` | string | 短标题 |
 | `author` | email | 创建者，来自 `git config user.email` |
@@ -56,6 +56,7 @@ catalog 同时用 `git log --diff-filter=A --format=%ae -- <path>` 算首次提
 - `kind: task` 落在 `work/tasks/TASK-*.md`，字段见 `docs/spec/work-task.md`。
 - `kind: question` 落在 `artifacts/inbox/questions/Q-*.md`（不入库）。
 - `kind: testdesign` 落在 `assets/testdesign/<sut>/<slug>.md`，字段见 `docs/spec/test-design-syntax.md`。
+- `kind: testcase` 落在 `assets/testcases/<模块>/<功能>.md`；模块说明是 `testcase-module`，总索引是 `testcase-index`。字段见 `docs/spec/testcase-syntax.md`。
 
 ### run manifest
 

tuner_testkit-5.3.0/tuner_testkit/apps/dna/dna_payload/docs/spec/testcase-syntax.md

@@ -0,0 +1,120 @@
+---
+name: testcase-syntax
+version: 1.1.0
+description: assets/testcases 的目录、四级标题、功能缩写用例 ID 与模块 README。功能用例集的唯一事实源。
+---
+
+# 测试用例（testcase-syntax）
+
+> 一份功能文件收齐该功能的全部用例。给人读，也给 LLM 按同一棵树增删改。
+> 维护流程见 skill `maintain-testcases`。编辑约束见 `.cursor/rules/testcases.mdc`。
+
+## 1. 和相邻知识的分工
+
+| 路径 | 记什么 |
+| --- | --- |
+| `assets/usecases/` | 导入或讲解过的业务场景，不是带稳定 ID 的用例集 |
+| `assets/testdesign/` | 一次任务的范围、策略和点击路径 |
+| `assets/testcases/` | 按模块 / 功能维护的用例集，每条用例一个稳定 `CASE` ID |
+| `tests/features/` | 已自动化的 Gherkin。本规范不写 `.feature` |
+
+## 2. 目录
+
+```text
+assets/testcases/README.md                 # 模块总索引：规划、模块一览、给人和 LLM 的放置规则
+assets/testcases/<模块>/README.md          # 该模块的范围、边界、功能清单
+assets/testcases/<模块>/<功能>.md          # 该功能的全部用例
+```
+
+例子：`assets/testcases/用户系统/用户登录.md`。
+
+- 目录名 = 模块显示名 = 功能文件里的二级标题。
+- 文件名（不含 `.md`）= 功能显示名 = 三级标题。
+- 只允许这一层：模块目录里不再套子目录。
+- 名称不要用 `\ / : * ? " < > |`。
+
+## 3. 标题层级
+
+功能文件正文只用这四级。一个功能的全部用例都放在四级标题下。
+
+```markdown
+# 测试用例
+## 用户系统
+### 用户登录
+#### User-Login0001 正向-正确账号密码
+- 步骤：输入已注册账号与正确密码点击登录
+- 预期：登录成功进入首页或个人中心
+#### User-Login0002 反向-正确账号错误密码
+- 步骤：输入已注册账号与错误密码点击登录
+- 预期：停留在登录页并提示账号或密码错误
+```
+
+| 级别 | 含义 | 规则 |
+| --- | --- | --- |
+| `#` | 中心主题 | 固定为 `测试用例` |
+| `##` | 模块 | 全文件只有一个，且等于父目录名 |
+| `###` | 功能 | 全文件只有一个，且等于文件名 |
+| `####` | 一条用例 | 功能缩写 ID + 空格 + `正向-` 或 `反向-` + 测试点名称 |
+
+## 4. 用例 ID
+
+ID 是全库唯一键，由功能缩写和该功能内的序号组成：`<缩写><四位序号>`。
+
+- 缩写：功能名的英文词，每词首字母大写，用 `-` 连接。`用户登录` → `User-Login`。只含字母和连字符，不含数字。
+- 序号：4 位数字，从 `0001` 起。`User-Login0001`、`User-Login0002`。
+- 缩写写在功能文件 front-matter 的 `id_prefix`，之后不得改。同一 `id_prefix` 只能属于一个功能文件。
+- 新增时只扫描这个前缀：`rg -N "^#### User-Login[0-9]{4} " assets/testcases`，取最大序号 + 1。
+- 不同功能的前缀不同，所以 `User-Login0001` 与 `Reset-Password0001` 不会撞键。
+- 已发出的 ID 不改、不复用、不因为删用例而重排。
+- 废弃：标题末尾加 `（废弃）`，并在该条下写 `- 状态：废弃` 与原因。保留标题，不要删掉这一节。
+
+## 5. 每条用例的子弹
+
+必填，且用中文冒号：
+
+- `- 步骤：` 测试人员或 LLM 能照做的操作
+- `- 预期：` 可观察结果
+
+可选，仍放在同一条四级标题下：
+
+- `- 前置：`
+- `- 数据：` 用账号 `account_id` 或数据文件路径，不写密码、token、Cookie
+- `- 备注：`
+
+没有依据的业务规则不要写进步骤或预期。依据来自用户说明，或 `INDEX.md` / `INDEX.project.md` 能指向的 usecase、domain-notes、explore、design。
+
+## 6. Front-matter
+
+功能文件：
+
+```yaml
+---
+kind: testcase
+id: user-login
+id_prefix: User-Login
+title: 用户登录
+module: 用户系统
+sut: <sut 短名，未知可省略>
+source: <assets/… 或需求名>
+version: 1.0.0
+confidence: medium
+---
+```
+
+模块 README 用 `kind: testcase-module`。总索引用 `kind: testcase-index`。
+人工修改后 bump `version`。署名用 `tuner-workspace meta stamp <path> --kind testcase`（模块 README 用 `testcase-module`，总索引用 `testcase-index`）。
+
+## 7. 两份 README
+
+`assets/testcases/README.md` 告诉人和 LLM：模块怎么划分、新功能该进哪个目录、当前有哪些模块。至少包含：
+
+- 放置规则（指向本 spec）
+- 模块表：模块名、目录、一句话范围、状态（`在用` / `规划中`）
+
+`assets/testcases/<模块>/README.md` 至少包含：
+
+- 这个模块测什么、不测什么
+- 功能清单：每个 `<功能>.md` 一行链接
+- 相关知识路径（没有就写「无」）
+
+新增或重命名功能文件时，两份 README 一起改。总索引的模块表与模块目录一致；模块 README 的功能清单与该目录下的功能文件一致。

{tuner_testkit-5.2.0 → tuner_testkit-5.3.0}/tuner_testkit/apps/init_repo/scaffold.py

@@ -13,6 +13,7 @@ SKELETON_DIRS: tuple[str, ...] = (
     "assets/explore",
     "assets/design",
     "assets/testreport",
+    "assets/testcases",
     "packages/action_words/db_seed",
     "packages/action_words/db_assert",
     "packages/action_words/api_request",

{tuner_testkit-5.2.0 → tuner_testkit-5.3.0}/tuner_testkit/catalog/scan.py

@@ -24,7 +24,17 @@ MAX_PARSE_BYTES = 256_000
 _SKIP_API_OBJECT_FILES = {"__init__.py", "conftest.py", "auth.py", "registry.py"}
 _SKIP_API_OBJECT_DIRS = {"recording", "tests"}
 _SKIP_PAGE_OBJECT_FILES = {"__init__.py", "conftest.py", "session.py", "pages.py"}
-ASSET_CATEGORIES: tuple[str, ...] = ("ddl", "sql", "usecases", "domain-notes", "explore", "design", "testreport")
+ASSET_CATEGORIES: tuple[str, ...] = (
+    "ddl",
+    "sql",
+    "usecases",
+    "domain-notes",
+    "explore",
+    "design",
+    "testdesign",
+    "testcases",
+    "testreport",
+)
 
 
 # ---------------------------------------------------------------------------

tuner_testkit-5.3.0/tuner_testkit/testcases/__init__.py

@@ -0,0 +1,5 @@
+"""Validate assets/testcases against docs/spec/testcase-syntax.md."""
+
+from tuner_testkit.testcases.validate import validate_tree
+
+__all__ = ["validate_tree"]

tuner_testkit-5.3.0/tuner_testkit/testcases/__main__.py

@@ -0,0 +1,25 @@
+"""CLI: python -m tuner_testkit.testcases [assets/testcases]."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from tuner_testkit.testcases.validate import validate_tree
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    target = Path(args[0] if args else "assets/testcases")
+    errors = validate_tree(target)
+    if errors:
+        for item in errors:
+            print(item, file=sys.stderr)
+        print(f"{len(errors)} error(s)", file=sys.stderr)
+        return 1
+    print(f"ok {target}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tuner_testkit-5.3.0/tuner_testkit/testcases/tests/test_validate.py

@@ -0,0 +1,76 @@
+from pathlib import Path
+
+from tuner_testkit.testcases.validate import validate_tree
+
+_INDEX = """---
+kind: testcase-index
+title: 测试用例模块索引
+version: 1.0.0
+---
+
+# 测试用例模块索引
+"""
+
+_MODULE = """---
+kind: testcase-module
+id: user-system
+title: 用户系统
+module: 用户系统
+version: 1.0.0
+---
+
+# 用户系统
+
+## 功能
+
+| 功能 | 文件 |
+| --- | --- |
+| 用户登录 | [用户登录.md](用户登录.md) |
+"""
+
+_FEATURE = """---
+kind: testcase
+id: user-login
+id_prefix: User-Login
+title: 用户登录
+module: 用户系统
+source: 需求
+version: 1.0.0
+confidence: medium
+---
+
+# 测试用例
+## 用户系统
+### 用户登录
+#### User-Login0001 正向-正确账号密码
+- 步骤：输入已注册账号与正确密码点击登录
+- 预期：登录成功进入首页或个人中心
+#### User-Login0002 反向-正确账号错误密码
+- 步骤：输入已注册账号与错误密码点击登录
+- 预期：停留在登录页并提示账号或密码错误
+"""
+
+
+def _tree(root: Path, feature: str = _FEATURE) -> None:
+    base = root / "assets" / "testcases"
+    module = base / "用户系统"
+    module.mkdir(parents=True)
+    (base / "README.md").write_text(_INDEX, encoding="utf-8")
+    (module / "README.md").write_text(_MODULE, encoding="utf-8")
+    (module / "用户登录.md").write_text(feature, encoding="utf-8")
+
+
+def test_valid_tree(tmp_path: Path) -> None:
+    _tree(tmp_path)
+    assert validate_tree(tmp_path / "assets" / "testcases") == []
+
+
+def test_duplicate_id_and_bad_heading(tmp_path: Path) -> None:
+    broken = _FEATURE.replace(
+        "#### User-Login0002 反向-正确账号错误密码",
+        "#### User-Login0001 反向-错误密码\n#### 没有编号",
+    )
+    _tree(tmp_path, broken)
+    errors = validate_tree(tmp_path / "assets" / "testcases")
+    assert any("duplicate User-Login0001" in item for item in errors)
+    assert any("case heading must be" in item for item in errors)