@hupan56/wlkj 3.1.32 → 3.3.0

package/templates/qoder/contracts/prd.md

@@ -0,0 +1,118 @@
+# 模块契约：prd（需求）
+
+> 产品模块。从「一句话」到「可发布的 PRD + 原型」。
+> 这是**最上游的契约源**，下游 design/spec/task/test 都靠它。
+
+---
+
+## Input（吃什么）
+
+| 优先级 | 输入 | 怎么用 |
+|--------|------|--------|
+| **完整** | 业务需求描述 + 平台 | `context_pack.py <词> --platform <web\|app>` 取上下文 |
+| 降级 1 | 只有业务描述，没指定平台 | **必须先问平台**（见铁律），不许跳过 |
+| 降级 2 ★ | 用户一句话口语需求 | 跑 context_pack + search_index --prd 自补上下文 |
+| 参考 | 现有页面 / 字段 / API | 来自 context_pack 的 7 段输出，不强依赖 |
+
+**平台是硬约束**：Web=fywl-ui / APP=Carmg-H5 / both。没定平台不许开干。
+
+---
+
+## Output（吐什么）
+
+### 主产物：PRD 草稿
+
+```
+路径：workspace/members/{developer}/drafts/REQ-{YYYY}-{NNN}-{标题}.md
+命名：REQ-ID 由 common/reqid.py 的 allocate_req_id() 原子分配
+```
+
+**第一行必须是契约头**（软契约，缺了只警告）：
+
+```markdown
+<!-- @contract prd v1
+platform: web|app|both
+req-id: REQ-2025-0042
+title: 保单批改功能
+mode: full|quick|reference|brainstorm|planning
+# brainstorm/planning 已随探索能力迁至 /wl-insight，PRD 不再主动产出这两个模式。
+# 保留枚举是为了向后兼容旧 PRD（eval_prd 仍能识别）。新 PRD 只用 quick/reference。
+acceptance: [验收点1, 验收点2]
+source: context_pack:保单批改,web
+-->
+```
+
+### 副产物：原型
+
+```
+单端：workspace/members/{developer}/drafts/prototype-{feature}.html
+两端：...prototype-{feature}-web.html + ...prototype-{feature}-app.html
+```
+
+### 归档（自动）
+
+```
+归档副本：workspace/members/{dev}/archive/{YYYY-MM-DD}/REQ-*.md（只复制不移动）
+```
+
+### 发布
+
+```
+发布后：git_sync.py 的 collect_prds() 把草稿拷到 data/docs/prd/REQ-*.md（立刻可搜）
+```
+
+---
+
+## 必含字段骨架
+
+### full 模式（完整需求）— 13 章
+
+版本信息 / 变更日志 / 名词解释 / 需求背景 / 需求来源 / 产品现状 /
+需求范围 / 功能清单 / 字段规格 / 操作与校验 / 非功能性需求 / 埋点 / 版本计划
+
+> **"版本计划"章节边界**：只写**本期排期**（本需求何时上线）。
+> 长期 roadmap / 多版本路线图已归 `/wl-insight plan`，不在 PRD 内展开。
+> PRD 聚焦"本次做什么"，不背"未来规划"的职责。
+
+### quick 模式（零星需求）— 6 章
+
+功能入口 / 需求背景 / 需求说明 / 影响范围 / 验收标准 / 不在本次范围
+
+> quick 模式整体跳过 EVA 门禁（用于快速出稿，不背完整质量责任）。
+
+---
+
+## 校验（唯一硬门禁）
+
+```bash
+python .qoder/scripts/orchestration/wlkj.py eval <prd.md> [原型.html]
+```
+
+| 维度 | 权重 | 检查内容 |
+|------|------|----------|
+| A1 现实锚定 | 40 分 | PRD 表格内 camelCase 字段、API 路径在索引命中比例 |
+| A2 风格保真 | 30 分 | 原型颜色来自真源（无原型则跳过，满分降为 70） |
+| A3 模板完整 | 30 分 | 章节齐全比例 |
+
+**阈值：≥ 80% 才 PASS**（`PASS_THRESHOLD = 80.0`）。结果追加到 `data/learning/eval-history.jsonl`。
+
+> full 模式无原型时满分 70，实际过线需 `A1+A3 ≥ 56`。
+> **这是整个工作流唯一的硬门禁**——因为 prd 是契约源头，源头不靠谱全链路歪。
+
+---
+
+## 与下游的接口
+
+| 下游模块 | 消费 prd 的什么 |
+|----------|----------------|
+| design | 验收标准里的界面相关点 + 平台 |
+| task | 功能清单 → 拆任务 |
+| spec | 全文，尤其是字段规格 + 操作校验 |
+| test | `acceptance` 列表 → 测试用例 |
+
+---
+
+## 现状提醒
+
+- ✅ eval_prd.py 已存在，校验可跑。
+- ⚠️ quick 模式跳过 EVA，可能产出质量较低的契约。下游拿到 quick PRD 时应留意。

package/templates/qoder/contracts/schemas/design-spec.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "qoder://contract/design-spec",
+  "title": "Design Spec 契约 (设计师规格)",
+  "description": "设计师从 Figma/Axure 录入的规格。优先级 > 代码风格 > PDF 规范。最适合 schema 化的契约 (纯 JSON 产物)。",
+  "type": "object",
+  "required": ["_contract", "design_tokens", "layout", "components"],
+  "properties": {
+    "_contract": {
+      "type": "object",
+      "required": ["type", "version", "platform", "requirement"],
+      "properties": {
+        "type": { "const": "design-spec" },
+        "version": { "type": "integer", "minimum": 1 },
+        "platform": { "type": "string", "enum": ["web", "app", "both"] },
+        "requirement": { "type": "string", "description": "关联的需求名/REQ-ID" },
+        "source": { "type": "string", "description": "figma:截图 / lanhu:链接" }
+      }
+    },
+    "design_tokens": {
+      "type": "object",
+      "description": "配色/尺寸/字体/圆角等设计令牌",
+      "properties": {
+        "colors": { "type": "object" },
+        "spacing": { "type": "object" },
+        "fonts": { "type": "object" },
+        "radius": { "type": "object" }
+      }
+    },
+    "layout": {
+      "type": "object",
+      "description": "页面布局结构 (栅格/区块/导航)"
+    },
+    "components": {
+      "type": "array",
+      "description": "组件清单 (类型/props/状态)",
+      "items": { "type": "object" }
+    },
+    "icons": {
+      "type": "array",
+      "description": "图标清单 (禁止 emoji, web=AntDesign SVG / app=Vant)",
+      "items": { "type": "string" }
+    }
+  },
+  "additionalProperties": true
+}

package/templates/qoder/contracts/schemas/prd.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "qoder://contract/prd",
+  "title": "PRD 契约 (产品需求文档)",
+  "description": "PRD 是最上游的契约源。下游 design/spec/task/test 都靠它。机器可校验版。",
+  "type": "object",
+  "required": ["type", "version", "req-id", "platform", "title", "acceptance"],
+  "properties": {
+    "type": { "const": "prd", "description": "契约类型标识" },
+    "version": { "type": "integer", "minimum": 1, "description": "契约版本, 未来演进用 (当前 v1)" },
+    "req-id": {
+      "type": "string",
+      "pattern": "^REQ-\\d{4}-\\d{3,}$",
+      "description": "需求编号, 贯穿全链路唯一 key, 由 reqid.py 原子分配"
+    },
+    "platform": {
+      "type": "string",
+      "enum": ["web", "app", "both"],
+      "description": "目标平台: web=fywl-ui / app=Carmg-H5 / both=两端"
+    },
+    "title": { "type": "string", "minLength": 2, "description": "需求标题" },
+    "acceptance": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1,
+      "description": "验收标准列表, 下游 test 据此生成用例"
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["quick", "reference", "brainstorm", "planning"],
+      "description": "生成模式 (quick 零星需求, reference 完整档)"
+    },
+    "source": { "type": "string", "description": "来源: context_pack:词,平台 / manual" }
+  },
+  "additionalProperties": true
+}

package/templates/qoder/contracts/schemas/test-cases.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "qoder://contract/test-cases",
+  "title": "Test Cases 契约 (测试用例集)",
+  "description": "从 PRD acceptance 或手动生成的测试用例。autotest 强依赖其结构。",
+  "type": "object",
+  "required": ["_contract", "cases"],
+  "properties": {
+    "_contract": {
+      "type": "object",
+      "required": ["type", "version"],
+      "properties": {
+        "type": { "const": "test-cases" },
+        "version": { "type": "integer", "minimum": 1 },
+        "platform": { "type": "string", "enum": ["web", "app", "both"] },
+        "req-id": {
+          "type": "string",
+          "pattern": "^REQ-\\d{4}-\\d{3,}$",
+          "description": "关联需求 (可空, 测试用例可能跨需求)"
+        }
+      }
+    },
+    "cases": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["name", "intent"],
+        "properties": {
+          "name": { "type": "string", "description": "用例名" },
+          "intent": { "type": "string", "description": "测试意图/验收点" },
+          "anchor": { "type": "string", "description": "页面锚点 (定位用)" },
+          "steps": { "type": "array", "items": { "type": "string" } },
+          "expected": { "type": "string" }
+        }
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/templates/qoder/contracts/spec.md

@@ -0,0 +1,116 @@
+# 模块契约：spec（技术规格）
+
+> 规格模块。把 PRD 翻译成开发能照着写的**技术契约**。
+> 是 code 模块的最佳输入。
+
+---
+
+## Input（吃什么）
+
+| 优先级 | 输入 | 怎么用 |
+|--------|------|--------|
+| **禅道（推荐）** | 禅道 task 关联的 story（`get_task → get_story_detail` 读 `spec` 字段） | task 来的需求经此读 PRD，**解决"别人提的 PRD 本地没有"**。1 task ↔ 1 spec |
+| 完整 | 本地已确认 PRD（`data/docs/prd/REQ-*.md`） | 字段规格 + 操作校验 → 接口/数据结构（禅道不可达时兜底） |
+| 降级 | PRD 草稿（REQ-ID 容器里） | 也能写 spec，标 `source: draft` |
+| 参考 | 历史 Spec | 同容器或历史 REQ-ID 容器看同类写法 |
+| 参考 | 字段命名 | `search_index.py --field <字段名>` |
+| 参考 | 数据字典 | `.qoder/context/data-dictionary.md`（不存在则跳过） |
+
+**团队技术约定（写进 spec 的默认约束）**：
+- 后端 Java：MyBatis Plus + RESTful + `BigDecimal` 金额 + JSR-303 校验 + `Result<T>`
+- 表名 `t_{module}_{entity}`，全栈 Entity→Mapper→Service→Controller
+- 不写 PRD 未定义的功能
+
+---
+
+## Output（吐什么）
+
+### 主产物：Spec 文件
+
+**路径（按来源）**：
+
+```
+① 禅道 task 来的（1 task ↔ 1 spec）：workspace/tasks/{task_id}/spec.md
+     └ task_id 即禅道 task id；复用现有 task 目录约定
+② 本地 PRD 来的：跟着 PRD 同容器（项目理念：一个需求的所有产出聚合在 REQ-ID 容器）
+     workspace/members/{dev}/{drafts|outputs}/{YYYY}/{MM}/{Ww}/{REQ-ID}/REQ-{ID}-{module}.spec.md
+     └ 复用 paths.get_req_dir() / find_req_dirs()，跨时间桶可查，不另开 specs 桶
+③ 兜底（老 PRD 不在时间桶）：workspace/specs/REQ-{ID}-{module}.spec.md
+```
+
+**生成方式**：spec-generator **读 `templates/spec-template.md` 固定 6 章骨架逐节填空**（不自由发挥结构）。
+
+**契约头**（含 `status` 状态字段 + 禅道关联 `zentao`）：
+
+```markdown
+<!-- @contract spec v1
+source-req: REQ-2025-0042
+platform: web
+module: policy
+endpoints: [POST /api/policy/amend, GET /api/policy/amend/{id}]
+status: draft
+zentao: task=1453 story=761
+zentao_id: 761
+platform_spec_id:
+-->
+```
+
+**字段说明**：
+- `status`：状态机见下表，/wl-code spec gate 的判据。
+- `zentao`：禅道 task 来的必须填（task+story）；本地来的留空，待回填时补。回填 task 后 spec 摘要写入该 task 的 `desc`。
+- `zentao_id`：禅道 story 号（关联键，= zentao 的 story）。spec_upload 据此让平台反查 Requirement 挂载；缺失则上传暂存待产品推禅道后回填。
+- `platform_spec_id`：平台 spec id（幂等锚）。spec_upload 首次 create 后自动回写，**勿手填**；有值则下次上传走 update_spec（新增版本不重复建）。
+
+**`status` 状态机**（/wl-code spec gate 的判据）：
+
+| status | 含义 | 谁能改 |
+|--------|------|--------|
+| `draft` | 刚生成，待用户确认 | spec-generator 生成时写入 |
+| `confirmed` | 用户已确认，可写码 | 仅 `/wl-code` 在用户明确确认后升级 |
+
+### 骨架（固定模板，见 `templates/spec-template.md`）
+
+6 章，必须照模板逐节填，结构每次一致、可复现：
+
+0. 概述（来源/一句话/涉及端/AC条数/改动范围）
+1. 接口定义（路径/方法/入参/出参/错误码，RESTful + JSR-303 + Result<T>）
+2. 数据结构（表 `t_{module}_{entity}` / 字段 / 类型 / 约束，金额 BigDecimal）
+3. **异常处理矩阵 ★强制**（每操作 × 全部失败场景 × 错误码 × HTTP × 处理策略）
+4. **AI 能力边界 ★强制**（✅可自动 / ⚠️必须人工确认 / 🚫禁止AI做）
+5. **测试用例 ★强制**（每条 PRD 验收标准 → 输入/预期/断言，详细可复现）
+6. PRD 验收标准映射表（每条 acceptance → 接口/数据/异常/用例，可追溯不漏）
+
+★强制章节不适用写"无"并附原因。
+
+---
+
+## 校验
+
+- ❌ **无独立校验脚本**（待建 `eval_spec.py`）。本期靠固定模板 + 强制章节保证一致性。
+- **spec gate（/wl-code 内，非侵入式）**：`/wl-code` Step 1 读 `status` 字段——
+  无 spec 或 `status≠confirmed` → 生成/展示 → 等用户确认 → 升级 `confirmed` → 才写码。
+  不调 `/wl-code` 时完全无感。
+- 软契约：缺 `source-req` 只警告。
+- review 模式（带 `review` 参数）只给改进建议，不重生成。
+
+---
+
+## 与上下游的接口
+
+| 方向 | 接口 |
+|------|------|
+| 上游 prd | 读 PRD 验收标准 + 字段规格 |
+| 下游 code | spec 是 code 的最佳输入 |
+| 下游 test | spec 的测试用例映射 → 单元测试 |
+
+---
+
+## ⚠️ 现状提醒（KNOWN GAP）
+
+- ✅ **固定模板已补**：`templates/spec-template.md`（6 章 + 异常矩阵/AI边界/测试用例 3 强制章节 + `status` 字段）。
+- ✅ **spec gate 已落地**：`/wl-code` Step 1 读 `status`，非侵入式。
+- ✅ **禅道对接已落地**：PRD 源优先读禅道 task→story（`get_task`/`get_story_detail`）；1 task ↔ 1 spec；confirmed 后回填 task `desc`（`update_task` 加了 desc 参数）。
+- ✅ **命名已统一**：`REQ-{ID}-{module}.spec.md`（spec-generator 与 wl-spec 一致，便于贯穿检索）。
+- ✅ **存储对齐时间桶**：本地来源的 spec 跟 PRD 同 REQ-ID 容器，复用 `paths.get_req_dir / find_req_dirs`；禅道来源的放 `workspace/tasks/{task_id}/spec.md`。
+- ⬜ 待修正 `wl-spec/SKILL.md` 的输出路径声明（仍写老平铺路径）。
+- ⬜ 待建 `eval_spec.py` 独立校验脚本（本期靠固定模板保证一致性）。

package/templates/qoder/contracts/task.md

@@ -0,0 +1,125 @@
+# 模块契约：task（任务）
+
+> 任务模块。把 PRD 拆成可执行任务 + RICE 排优先级。
+> task.json 是本模块的**唯一事实源**。
+
+---
+
+## Input（吃什么）
+
+| 优先级 | 输入 | 怎么用 |
+|--------|------|--------|
+| **完整** | 一份 PRD（`REQ-*.md`） | 功能清单 → 拆任务 |
+| 降级 1 | PRD 草稿（drafts 里的） | 也能拆，只是还没发布 |
+| 降级 2 | 一句话任务描述 | 直接 `task.py create "XXX"` |
+| 参考 | 已有任务 | `task.py list` 看排期，避免重复 |
+
+不强依赖 prd 模块执行——可以直接手动建任务。
+
+---
+
+## Output（吐什么）
+
+### 任务目录
+
+```
+路径：workspace/tasks/{MM-DD-slug}/
+内含：
+  task.json         ← 任务元数据 + 状态 + RICE
+  prd.md            ← 任务级需求（可空）
+  implement.jsonl   ← 实现记录
+  check.jsonl       ← 检查记录
+```
+
+### task.json 骨架（对齐 task.py 真实输出）
+
+```json
+{
+  "title": "...",
+  "slug": "baodan-piGai",
+  "status": "planning",           // planning → in_progress → completed（归档时再补 archived_at）
+  "priority": "P0|P1|P2|P3",
+  "assignee": "{developer}",       // ← 注意是 assignee 不是 owner
+  "creator": "{developer}",
+  "created_at": "...", "updated_at": "...",
+  "branch": null, "base_branch": null,
+  "scope": null,
+  "parent": null, "children": [],  // 父子任务
+  "tags": ["REQ-2026-0042"],       // ← PRD 的 REQ-ID 记这里（双向追溯）
+  "rice": 24,                      // ← RICE 排序时 AI 算好后写入（数值，不是对象）
+  // 能力增强字段（可选，旧 task.json 不含时取默认值）
+  "due_date": "2026-07-01",        // YYYY-MM-DD（set-due 写）
+  "start_date": null,
+  "estimate_hours": null,
+  "blocked_by": [],                // 被哪些任务阻塞（block 写，自动维护反向 blocks）
+  "blocks": [],                    // 被哪些任务依赖（自动维护）
+  "stage_ts": { "created": "...", "started": null, "completed": null },
+  "zentao_id": null                // 对应禅道任务 ID（zentao_sync 写）。幂等主键: 已有则跳过 create。
+                                   //   隔离契约见 contracts/isolation.md「禅道同步」。
+}
+```
+
+> ⚠️ 字段名以 **task.py 实际输出**为准（`assignee`/`planning`/`completed`/`rice` 为数值）。
+> 上面是权威骨架，与 task.py 的 `cmd_create` 逐字段对齐。
+
+### 状态流转
+
+```
+create(planning) → start → in_progress → finish → completed → archive
+```
+
+**关键动作都会自动 stage workspace/tasks/ 到 team_sync**（push 后团队可见）。
+
+---
+
+## 操作命令
+
+```bash
+# 基础生命周期
+python .qoder/scripts/orchestration/wlkj.py task create "XXX" [--slug ...] [--assignee ...] [--priority P0|P1|P2|P3]
+python .qoder/scripts/orchestration/wlkj.py task list [--mine] [--status in_progress] [--ready] [--blocked]
+python .qoder/scripts/orchestration/wlkj.py task show <task-dir>
+python .qoder/scripts/orchestration/wlkj.py task start <task-dir>      # planning → in_progress，设为活跃任务
+python .qoder/scripts/orchestration/wlkj.py task current [--source]    # 看当前活跃任务
+python .qoder/scripts/orchestration/wlkj.py task finish                 # 活跃任务 → completed，清活跃指针
+python .qoder/scripts/orchestration/wlkj.py task archive <task-dir>     # 移到 .qoder/archive/{YYYY-MM}/，自动清孤儿依赖
+
+# 子任务
+python .qoder/scripts/orchestration/wlkj.py task add-subtask <parent> <child>
+python .qoder/scripts/orchestration/wlkj.py task remove-subtask <parent> <child>
+
+# 排期与依赖（B2 能力）
+python .qoder/scripts/orchestration/wlkj.py task set-due <task> <YYYY-MM-DD>
+python .qoder/scripts/orchestration/wlkj.py task block <task> <blocker>     # 循环依赖自动检测，反向 blocks 自动维护
+python .qoder/scripts/orchestration/wlkj.py task unblock <task> <blocker>
+python .qoder/scripts/orchestration/wlkj.py task gantt [--weeks 4]          # 只排有日期的任务，自动标逾期
+```
+
+**退出码**：`0`=成功 / `1`=任务不存在/JSON 缺失/循环依赖 / `4`=权限不足（零信任 ACL，仅 creator/assignee/admin 可改）。
+
+**RICE** = Reach × Impact × Confidence ÷ Effort（AI 层评估，算好后写入 task.json 的 `rice` 数值字段）
+
+---
+
+## 校验
+
+- ❌ **无独立校验脚本**。当前靠 task.py 自身的状态机约束。
+- 软契约：task.json 缺 `_contract` / `acceptance` 只警告不拦。
+
+---
+
+## 与上下游的接口
+
+| 方向 | 接口 |
+|------|------|
+| 上游 prd | 读 PRD 的功能清单 → 拆任务 |
+| 下游 spec/code | 任务目录可放 `spec.md`（spec 模块写到任务目录时） |
+
+---
+
+## 现状提醒
+
+- ✅ task.py 功能完整：CRUD + 依赖图（block/unblock + 循环检测）+ 排期（set-due/gantt）+ 子任务 + 零信任 ACL + 归档孤儿依赖清理。
+- ✅ PRD→task 衔接：create 时把 REQ-ID 记进 `tags`，PRD 验收点贴进 task 的 `prd.md`（命令层引导）。
+- ✅ RICE 排序在 AI 层（task.py 只存数值，不替 AI 算分）。
+- 🧩 QoderWork 增强（可选）：待办双向同步。无连接器则回退，task.json 仍为准。

package/templates/qoder/contracts/test.md

@@ -0,0 +1,112 @@
+# 模块契约：test（测试）
+
+> 测试模块。三条线：quick（默认）/ browser / unit。
+> 测试用例锚定到 PRD 的验收标准编号。
+
+---
+
+## Input（吃什么）
+
+三条线，输入不同：
+
+| 线 | 输入 | 怎么用 |
+|----|------|--------|
+| **quick**（默认） | 零输入，用户直接给用例 | `autotest.py quick --cases '<JSON>' --desc "..." --platform <web\|app>` |
+| **browser** | 任务名 | 读任务 PRD 的验收标准，**不搜源码**；`autotest.py generate <task>` / `run <task>` |
+| **unit** | 代码关键词 | 搜代码读源码，test-generator skill + `search_index.py` |
+| **assertion-gen** | PRD 验收章节 / GWT 文本 | `autotest.py assertion-gen --task <任务> --page <业务词>`（详见下方） |
+
+### 降级链路
+
+| 优先级 | 输入 |
+|--------|------|
+| **完整** | spec 文件（接口清晰） |
+| 降级 1 | PRD（读 `acceptance` 列表） |
+| 降级 2 | 任务 PRD（browser 线） |
+| 降级 3 ★ | 一句话 + 全索引（搜相关页面/字段，凑出验收点） |
+
+**环境**：域名/环境来自 `.qoder/config.yaml` 的 `autotest:` 段；`--url` 可临时覆盖。
+**测试数据**：个人数据在 `workspace/members/{名字}/autotest-data.yaml`（gitignored）；
+真实数据用 `{{ask:描述}}` 占位，**绝不编造**。
+
+---
+
+## Output（吐什么）
+
+### quick / browser
+
+```
+用例 JSON + 执行计划
+回传：autotest.py ... --record '{"Q-1":"pass"}'
+browser 骨架写到任务的 autotest-cases.jsonl
+```
+
+### unit
+
+```
+路径：tests/{package-path}/{ClassName}Test.java
+风格：Given-When-Then，@DisplayName 中文，AssertJ，全 Mock
+```
+
+### assertion-gen（业务规则断言）
+
+```
+输出：workspace/tasks/<task>/assertions.json
+结构：{ _contract:{type:assertions}, assertions:[{intent:"assert", expect:{...}, source, desc}] }
+每条断言带 source 置信度标记：
+  - 规则·句中含接口 / 图谱·按钮画像 / 图谱·字段表命中  = 可信
+  - 需确认·字段未命中 / 需确认·接口未指明              = 待补 {{ask:}} 占位
+expect 字段对齐 autotest_webaccess.py _check_expect 契约：
+  fetch 断言：{fetch, jsonpath, equals} 必填 + {method?, body?} 可选 (默认 POST/{})
+  dom 断言：  {dom, jsonpath, equals}                   三字段齐全
+  注: assertion_gen 只产必填 3 字段, method/body 走 _check_expect 默认值。
+```
+
+**红线：断言不编造。** PRD 无结构化验收（空/纯描述）→ 输出"无可抽取的结构化断言"并退出码 2，
+**绝不**让 LLM 瞜编 `expect.equals`。图谱/字段表只补字段不编语义。
+
+### 用例契约头（JSON）
+
+```json
+{
+  "_contract": { "type": "test-cases", "version": 1, "source": "REQ-2025-0042" },
+  "cases": [
+    { "id": "Q-1", "anchor": "REQ-2025-0042#验收点1", "step": "...", "expect": "..." }
+  ]
+}
+```
+
+**每个用例的 `anchor` 字段锚定到 PRD 验收标准编号**——这是测试可追溯的关键。
+
+---
+
+## 校验
+
+- ❌ **无独立校验脚本**。靠自检清单：
+  - [ ] 正常路径 + 错误路径 100% 覆盖
+  - [ ] 核心边界覆盖
+  - [ ] 无外部依赖（全 Mock）
+  - [ ] 测试方法间无依赖
+  - [ ] 每个用例有 anchor 指向验收标准
+
+**铁律**：`autotest.py` 绝不 import playwright/selenium。
+浏览器执行由 QoderWork 连接器承担，无连接器 → 降级为人工核对清单（不报错）。
+
+---
+
+## 与上下游的接口
+
+| 方向 | 接口 |
+|------|------|
+| 上游 prd | 读 acceptance 列表 |
+| 上游 spec | 读接口定义 |
+| 上游 code | unit 线读源码 |
+| 下游 commit | 测试通过是 commit 门禁之一 |
+
+---
+
+## 现状提醒
+
+- ✅ 三线分工清晰。
+- 🧩 QoderWork 增强（可选）：browser 线的浏览器执行。无连接器 → 降级人工核对。
+- ⚠️ 测试数据绝不能编造——这条是红线。