@tea-agent/loop-agent 0.18.1 → 0.20.0

package/dist/workflows/dag/types.js

@@ -113,6 +113,33 @@ export const dagJsonArtifactGateSchema = z.object({
     outputDir: z.string().regex(/^[a-z0-9][a-z0-9._-]*$/),
     junitRelativePath: z.string().min(1).optional(),
 });
+const dagFrontendNodeIdSchema = z
+    .string()
+    .regex(/^[a-z][a-z0-9-]*$/, "frontend node id must be kebab-case");
+export const dagFrontendPrewriteGateSchema = z.object({
+    schemaVersion: z.literal(1),
+    planFromNodeId: dagFrontendNodeIdSchema,
+    planFallbackFromNodeIds: z.array(dagFrontendNodeIdSchema).default([]),
+    reviewFromNodeId: dagFrontendNodeIdSchema,
+    reviewFallbackFromNodeIds: z.array(dagFrontendNodeIdSchema).default([]),
+    requiredRequirementIds: z.array(z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/)).default([]),
+    allowedMockStrategies: z.array(z.enum(["native", "browser-intercept", "request-adapter", "not-needed"])).min(1),
+    artifactName: z.string().regex(/^[a-z0-9][a-z0-9._-]*\.json$/),
+    outputDir: z.string().regex(/^[a-z0-9][a-z0-9._-]*$/),
+});
+export const dagFrontendVerificationBundleSchema = z.object({
+    schemaVersion: z.literal(1),
+    mockCommands: z.array(z.string()).default([]),
+    staticCommands: z.array(z.string()).min(1),
+    behaviorCommands: z.array(z.string()).min(1),
+    mockEvidence: dagShellVerifyEvidenceSchema.optional(),
+    staticEvidence: dagShellVerifyEvidenceSchema,
+    behaviorEvidence: dagShellVerifyEvidenceSchema,
+    mode: z.enum(["initial", "repair"]),
+});
+export const dagFrontendReviewContextSchema = z.object({
+    schemaVersion: z.literal(1),
+});
 export const ENV_VAR_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 export const dagVersionSchema = z
     .union([z.literal(1), z.literal(2), z.literal(3), z.literal(4)])
@@ -191,6 +218,9 @@ export const dagShellConfigSchema = z.object({
     }).strict().optional(),
     requirementCoverageGate: dagRequirementCoverageGateSchema.optional(),
     jsonArtifactGate: dagJsonArtifactGateSchema.optional(),
+    frontendPrewriteGate: dagFrontendPrewriteGateSchema.optional(),
+    frontendVerificationBundle: dagFrontendVerificationBundleSchema.optional(),
+    frontendReviewContext: dagFrontendReviewContextSchema.optional(),
     backendTestPipeline: dagBackendTestPipelineSchema.optional(),
     verifyEvidence: dagShellVerifyEvidenceSchema.optional(),
     repairArtifactGate: dagRepairArtifactGateSchema.optional(),

package/dist/workflows/dag/validate.js

@@ -456,7 +456,12 @@ function validateShellTaskConfig(task, spec, issues) {
         return;
     }
     const commands = resolveShellCommands(shell);
-    if (commands.length === 0 && !shell.jsonArtifactGate && !shell.backendTestPipeline) {
+    if (commands.length === 0 &&
+        !shell.jsonArtifactGate &&
+        !shell.backendTestPipeline &&
+        !shell.frontendPrewriteGate &&
+        !shell.frontendVerificationBundle &&
+        !shell.frontendReviewContext) {
         issues.push({
             type: "missing-shell-commands",
             message: `shell task ${task.id} requires shell.preset, shell.verdictGate, shell.jsonArtifactGate, shell.backendTestPipeline, and/or non-empty shell.commands`,
@@ -517,6 +522,22 @@ function validateShellTaskConfig(task, spec, issues) {
             }
         }
     }
+    if (shell.frontendPrewriteGate) {
+        const sourceNodeIds = [
+            shell.frontendPrewriteGate.planFromNodeId,
+            ...shell.frontendPrewriteGate.planFallbackFromNodeIds,
+            shell.frontendPrewriteGate.reviewFromNodeId,
+            ...shell.frontendPrewriteGate.reviewFallbackFromNodeIds,
+        ];
+        for (const sourceNodeId of new Set(sourceNodeIds)) {
+            if (!task.depends_on.includes(sourceNodeId)) {
+                issues.push({
+                    type: "missing-dependency",
+                    message: `shell task ${task.id} frontendPrewriteGate source ${sourceNodeId} must be a direct dependency`,
+                });
+            }
+        }
+    }
     validateRepairArtifactGateConfig(task, spec, issues);
     validateShellVerdictGateGovernance(task, commands, issues);
 }

package/docs/README.md

@@ -6,7 +6,7 @@
 
 **索引职责**：本文件只索引**核心契约、方法论、产物目录入口与模板**。单篇 progress / report / completed plan 的全量列表分别由对应子目录 `README.md` 维护，避免三处精选榜漂移。
 
-**维护日：2026-07-22** — 索引对齐仓库头 `@tea-agent/loop-agent@0.17.2`、reports 按类型分子目录，以及 progress / completed 导读制；版本与能力细节以 `CHANGELOG.md`、`reports/current-capability-summary.md` 与 active plans 为准。
+**维护日：2026-07-22** — 索引对齐仓库头 `@tea-agent/loop-agent@0.18.0`、reports 按类型分子目录，以及 progress / completed 导读制；版本与能力细节以 `CHANGELOG.md`、`reports/current-capability-summary.md` 与 active plans 为准。
 
 站上用法文档在 `../website/docs/`；双树收敛见 `../skills/loop-agent/references/docs-converge.md`。
 
@@ -57,7 +57,8 @@
 - `design/dag-source-binding-and-recovery.md` — 新生成 DAG 的任务源绑定与中断恢复
 - `design/agent-worker-fullstack-workflow-integration.md` — workflow routing、Task Outcome、artifact-aware Ready、`fullstack-v1` 与 Verification Bundle
 - `design/fullstack-end-to-end-delivery-optimization-roadmap.md` — 全栈端到端优化收敛路线图（release train / Delivery / Final Verification）
-- `design/local-operator-console-from-pi-web.md` — Operator Console 设计输入；MVP 已随 `0.17.0`–`0.17.2` 发布
+- `design/2026-07-22-console-observe-unified-operator-surface.md` — Observe 深度融合进 Console（Wave 1–3 已实现，目标 0.18.0）
+- `design/local-operator-console-from-pi-web.md` — Operator Console 设计输入；MVP 已随 `0.17.0`–`0.17.2` 发布；统一 surface 见上条
 - `design/taskspec-to-loop-agent-mapping.md` — TaskSpec → loop-agent task 兼容契约（文档镜像；runtime 真源在代码）
 
 已实现且仅作历史说明的设计见 `design/archive/`（例如 `design/archive/2026-07-14-loop-agent-self-update-notifier.md`）。
@@ -74,6 +75,7 @@
 
 完整 completed 列表与主题速览见 `exec-plans/completed/README.md`。近期高频归档：
 
+- `exec-plans/completed/2026-07-23-backend-test-human-readable-artifacts.md` — 中文 README/用例卡片、class-based pytest traceability 与逐条 self-contained HTML 报告；真实 `my-webapp` Campaign Round 04 8/8、16 passed
 - `exec-plans/completed/2026-07-22-backend-markdown-gate-fix.md` — backend-test Markdown gate、traceability、中文生成与真实 Campaign 收口
 - `exec-plans/completed/2026-07-22-backend-test-markdown-first-8-node.md` — backend-test Markdown-first 8 节点
 - `exec-plans/completed/2026-07-22-backend-test-report-first-flow.md` — backend-test 报告优先 12 节点

package/docs/architecture/evolution.md

@@ -2,9 +2,9 @@
 
 本页区分 loop-agent **当前已实现**的架构能力与**未来规划**。当前事实以代码、发布 CLI、已完成计划为准；未来能力一律标「规划 / 未实现 / 前瞻」。权威源：`CHANGELOG.md`、`docs/reports/current-capability-summary.md`、ADR 0001–0005、`docs/exec-plans/completed/` 与 `docs/exec-plans/active/`。
 
-**对照版本：`@tea-agent/loop-agent@0.17.2`（2026-07-22）**。细节版本条目见根 `CHANGELOG.md`；本表只保留架构层可读摘要。
+**对照版本：`@tea-agent/loop-agent@0.18.0`（2026-07-22）**。细节版本条目见根 `CHANGELOG.md`；本表只保留架构层可读摘要。
 
-## 当前已实现（累计至 0.17.2）
+## 当前已实现（累计至 0.18.0）
 
 | 域 | 现状 | 权威入口 |
 | --- | --- | --- |
@@ -20,8 +20,8 @@
 | Backend-test | **Markdown-first 8 节点**（env → MD cases/review → 单次 pytest+HTML → report+L-5）；历史 JSON 读兼容 | completed `2026-07-22-backend-test-markdown-first-8-node.md` |
 | Frontend-test | 默认 short-chain RAG；结果链 / Outcome 投影；formal smoke 仍 active | `CHANGELOG.md [0.16.24]`；active success-rate plan |
 | Frontend-implementation | Contract / trace / repair / Mock assess；条件 design/repair 分支 | `CHANGELOG.md [0.13.0]` / `[0.17.x]` |
-| Observe | 本地只读暖白运营控制台 R1–R5 + 执行面富时间线；versioned `/api/health` | `website/docs/guides/observe-ui.md`、`CHANGELOG.md [0.11.0]` / `[0.14.0]` / `[0.17.x]` |
-| Local Operator Console | `agent-worker console serve\|doctor`（loopback）；Happy Path / Interview / Observe 深链 / recovery CTA；**非**远端多用户 Console | completed Console plans；`docs/design/local-operator-console-from-pi-web.md`；ADR 0005 |
+| Inspect（原 Observe） | 统一 Console 的 `/inspect/` 只读运营面与富时间线；兼容期仍保留独立 `observe serve` | `website/docs/guides/observe-ui.md`、`CHANGELOG.md [Unreleased]` |
+| Local Operator Console | `agent-worker console serve\|doctor`（loopback）；Operate + Inspect、Happy Path / Interview / split view / recovery CTA；**非**远端多用户 Console | unify design；ADR 0005 |
 | Task Contract / operator surface | journaled `task contract *`；machine envelope；**DagSpec v4 `taskContractBinding`**（exclusive writer 强制） | `CHANGELOG.md [0.17.0]`–`[0.17.2]`；ADR 0005 |
 | DagSpec / repair | v3 `runtimeContract` + 显式 `repairNodeId`；新 writer 生成默认 v4 binding | `dag-execution.md`、`CHANGELOG.md [0.11.0]` / `[0.17.0]` |
 | Eval Lab | corpus / campaign / promote（人工门禁）；`autoPromote=false`；**非** RSI Level 1 | `CHANGELOG.md [0.15.0]`；active plan 可归档 |
@@ -50,10 +50,10 @@
 | fullstack Delivery / Final Verification live 闭环 | 进行中（active train） | `docs/exec-plans/active/2026-07-19-fullstack-dogfood-016x-release-train.md` |
 | Dynamic Workflow runtime limits 强执法、更广 profile | 设计输入 | `docs/design/dynamic-workflow-dag-engine-roadmap.md` |
 | Loop 与 Dynamic Workflow 更深双向集成 / 自动恢复 | 设计输入 | 同上；当前已有基础 `workflow` action |
-| Console Phase 4 General Operator Chat / 与 Observe 合服 | 规划 / 未实现 | Console design residual |
+| Console Phase 4 General Operator Chat | 规划 / 未实现 | Console design residual |
 | Eval Lab auto-promote / RSI Level 1 产品声称 | **禁止**写成已交付 | Eval Lab design + active plan |
 
-> 本地 Operator Console MVP（0.17.0–0.17.2）已发布：单仓库、loopback、随 `@tea-agent/loop-agent` 同包、canonical mutation 只经 sibling CLI、与 Observe 分进程。它不是远端 Web Console，也不能把多租户/云编排需求偷渡进本地 MVP。
+> 本地 Operator Console 统一面（0.18.0）已发布：单仓库、loopback、随 `@tea-agent/loop-agent` 同包、canonical mutation 只经 sibling CLI，Inspect 复用 GET-only Observe read model。它不是远端 Web Console，也不能把多租户/云编排需求偷渡进本地 Console。
 
 > 注意：`docs/design/dynamic-workflow-dag-engine-roadmap.md` 含 2026-07-04 历史叙述；文中凡把 Cursor 写成受治理 executor 或 `loop` 的 `cursor-fix` 动作，均为**历史叙述**，现状以 Pi-only + 显式 `cursor-prompt` sidecar 为准。
 

package/docs/architecture/worker-and-feature.md

@@ -1,8 +1,8 @@
 # Worker 与 Feature 架构
 
-本页说明 `agent-worker` 如何通过冻结的已发布 `loop-agent` 子进程执行 DAG（不 in-process import runtime kernel），以及其上的产品线 read model：TaskSpec、Task Pool、Feature、Observe 与 Local Operator Console。边界契约权威是 `runtime-boundaries.md` §Worker adapter。
+本页说明 `agent-worker` 如何通过冻结的已发布 `loop-agent` 子进程执行 DAG（不 in-process import runtime kernel），以及其上的产品线 read model：TaskSpec、Task Pool、Feature 与统一 Operator Console（Operate + Inspect）。边界契约权威是 `runtime-boundaries.md` §Worker adapter。
 
-**维护校准：2026-07-22 / `@tea-agent/loop-agent@0.17.2`** — Console MVP、Task Contract 与 TaskSpec workflow 路由已落地；细节以 `CHANGELOG.md` 与 completed plans 为准。
+**维护校准：2026-07-22 / `@tea-agent/loop-agent@0.18.0`** — 统一 Operator Console（Operate + Inspect）已落地；细节以 `CHANGELOG.md` 与 active unify plan 为准。
 
 ## 核心事实：子进程，非 in-process
 
@@ -73,19 +73,19 @@ controller identity 与 DAG skill snapshot 是两个不同冻结层（前者跨
 - Delivery / Closeout：clean Delivery HEAD 上生成 canonical QA/最终验证证据、Delivery Package、Acceptance Coverage、PR 草稿；Closeout 默认预览，显式 `--apply --owner` 才原子写回。
 - 权威证据：`CHANGELOG.md [0.10.0]`、`docs/reports/feature/2026-07-12-m2-completion-audit.md`。
 
-### Observe（只读 read model）
+### Inspect（Observe 只读 read model）
 
 - 模块：`src/worker/observe/`、`src/worker/observability/{read-model,event-store}.ts`。
 - 全局快照：`buildGlobalSnapshot({ repoRoot })`（`src/worker/observability/read-model.ts`），是 **derived** 视图，消费 `.harness/` 与 Task Pool 事实，**不**改变执行成败。
-- Observe 是本地只读暖白控制台；snapshot 投影失败返回安全错误摘要而非全零健康状态（见 `CHANGELOG.md [0.9.0]`）。
-- Phase 3：`GET /api/health` 为 versioned DTO（`schemaVersion: 1`、`repoFingerprint` 复用 Console `repoFingerprintV1`、package 元数据、由 ROUTES 派生的 `routeCapabilities`）。Console 深链 fail-closed 依赖该合同；Observe 仍独立进程、不经 Console proxy。
+- Observe read model 是本地只读 Inspect 能力；snapshot 投影失败返回安全错误摘要而非全零健康状态。
+- `agent-worker console serve` 在同一进程挂载 `/inspect/` 与现有 GET `/api/**`；`/api/health` 返回 `OperatorSurfaceHealthV1`。兼容期独立 Observe `:8787` 保持旧 health DTO 与 GET-only 行为。
 
-### Local Operator Console（Official，0.17.x MVP）
+### Local Operator Console（Official，0.18.0）
 
 - 模块：`src/worker/console/`（loopback `serve|doctor`、operator API、Vite SPA）。
-- **已发布能力**：Happy Path / Interview 策略面、Task Contract 落地、SSE 运行跟随、Observe 深链 fail-closed、recovery CTA 矩阵（无 Cancel / 无主 CTA「直接改代码」）。
-- 与 Observe 协作：versioned Observe health + `repoFingerprint`；**不** mount / proxy / 复制第二套 read model。
-- 写入路径仍只经 `LoopAgentClient` → 已发布 `loop-agent`（含 `task contract *` / DAG confirm-run）；不与 Observe 合服。
+- **已发布能力**：Happy Path / Interview、Task Contract、SSE、同站 Inspect、Run/Recovery 紧凑检视与 recovery CTA 矩阵（无 Cancel / 无主 CTA「直接改代码」）。
+- Inspect 仍复用唯一 Observe read model，GET-only；不复制 snapshot projector。
+- 写入路径仍只经 `LoopAgentClient` → 已发布 `loop-agent`（含 `task contract *` / DAG confirm-run）。
 - 证据：completed Console Phase 0.5 / 1–3；handoff `docs/reports/feature/2026-07-22-console-mvp-handoff.md`；ADR 0005。
 
 ## 版本化自举的 deterministic canary

package/docs/templates/agent-dag.schema.json

@@ -303,6 +303,43 @@
             "junitRelativePath": { "type": "string", "minLength": 1 }
           }
         },
+        "frontendPrewriteGate": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["schemaVersion", "planFromNodeId", "reviewFromNodeId", "allowedMockStrategies", "artifactName", "outputDir"],
+          "properties": {
+            "schemaVersion": { "const": 1 },
+            "planFromNodeId": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "planFallbackFromNodeIds": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" } },
+            "reviewFromNodeId": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "reviewFallbackFromNodeIds": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" } },
+            "requiredRequirementIds": { "type": "array", "items": { "type": "string", "pattern": "^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$" } },
+            "allowedMockStrategies": { "type": "array", "minItems": 1, "items": { "enum": ["native", "browser-intercept", "request-adapter", "not-needed"] } },
+            "artifactName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*\\.json$" },
+            "outputDir": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" }
+          }
+        },
+        "frontendVerificationBundle": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["schemaVersion", "staticCommands", "behaviorCommands", "staticEvidence", "behaviorEvidence", "mode"],
+          "properties": {
+            "schemaVersion": { "const": 1 },
+            "mockCommands": { "type": "array", "items": { "type": "string" } },
+            "staticCommands": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+            "behaviorCommands": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+            "mockEvidence": { "$ref": "#/$defs/shellVerifyEvidence" },
+            "staticEvidence": { "$ref": "#/$defs/shellVerifyEvidence" },
+            "behaviorEvidence": { "$ref": "#/$defs/shellVerifyEvidence" },
+            "mode": { "enum": ["initial", "repair"] }
+          }
+        },
+        "frontendReviewContext": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["schemaVersion"],
+          "properties": { "schemaVersion": { "const": 1 } }
+        },
         "backendTestPipeline": {
           "enum": ["contracts", "semantic-initial", "execute-parse-initial", "classification-result-context"]
         },
@@ -324,6 +361,9 @@
         { "required": ["verdictGate"] },
         { "required": ["requirementCoverageGate"] },
         { "required": ["jsonArtifactGate"] },
+        { "required": ["frontendPrewriteGate"] },
+        { "required": ["frontendVerificationBundle"] },
+        { "required": ["frontendReviewContext"] },
         { "required": ["backendTestPipeline"] }
       ]
     },

package/docs/templates/backend-test-dag.generate-pytest.prompt.md

@@ -2,205 +2,36 @@
 
 ## Purpose
 
-Use this prompt for a **pytest code generation** node: `executor: "pi"`, `role: "implementer"`, `toolProfile: "write"`, `writePolicy: "exclusive"`. The implementer converts validated backend functional test cases into pytest automation code with 1:1 traceability. The independent case review is advisory evidence and does not authorize this writer.
+供 `generate-backend-pytest-pi` 使用。该节点是 `executor: "pi"`、`role: "implementer"`、`toolProfile: "write"` 的受限 writer，只把已经通过 Markdown gate 的最终用例转换为 pytest 资产。
 
-Do **not** create a new executor type. This is a standard `executor: pi` writer node.
+## 当前合同
 
-## Recommended DAG Node Shape
-
-```json
-{
-  "id": "generate-backend-pytest-pi",
-  "depends_on": ["backend-test-case-manifest-shell", "validate-backend-test-contracts-shell"],
-  "complexity": "HIGH",
-  "executor": "pi",
-  "role": "implementer",
-  "toolProfile": "write",
-  "writePolicy": "exclusive",
-  "writeSet": ["testcase/**/test_*.py", "testcase/**/helpers/**", "testcase/**/factories/**"],
-  "allowedPaths": ["**"],
-  "forbiddenPaths": [".harness/**", "artifacts/**"],
-  "outputContract": "Pytest test files under testcase/ with 1:1 mapping to functional test case IDs; optional helpers/factories. Summary lists generated files, test function count, and any skipped cases with reasons.",
-  "subtask_prompt_markdown": "./backend-test-dag.generate-pytest.prompt.md"
-}
-```
-
-## Prompt Body
-
-You are the Backend Test DAG **pytest code generator**.
-
-Your job is to convert reviewed test cases under `testcase/md/` into pytest automation code. Write test files under `testcase/` only. Stay within `writeSet`. Do not write root `artifacts/**`.
-
-### Output Steps (do in order)
-
-1. First, output a brief summary: how many files, how many test functions planned
-2. Then write each test file under `testcase/`
-
-### Inputs
-
-1. **Validated test cases and manifest** — files under `testcase/md/` plus run-owned `contracts/backend-test-case-manifest.json`. The case review runs independently as advisory evidence.
-2. **Validated Backend Test Analysis v2** — run-owned `contracts/backend-test-analysis.json`.
-3. **Validated Backend Test Execution Contract v1** — run-owned `contracts/backend-test-execution.json` from `backend-test-execution-contract-shell` (fixtures, env *names*, `testRoot`, `targetMode`, authenticationMode).
-4. **Target project conventions** — read `conftest.py`, `pytest.ini` / `pyproject.toml` to understand conventions, but do NOT modify them.
-
-Do NOT re-read source documents for free-form analysis. Use only validated cases, manifest, and contracts. Use only fixture/env/testRoot facts already present in the execution contract; never invent production credentials or secret values.
-
-When `targetMode` is `in-process` (including demoted local npm/node managed servers): bootstrap the service inside function-scoped pytest fixtures under `testcase/**` (for example subprocess `node server.js` / `startWelcomeServer` with `PORT=0`). Never require host-injected base URL env vars such as `WELCOME_BASE_URL` / `API_BASE_URL` — the clean-env pytest shell will not provide them.
-
-### Conversion Rules
-
-#### File Naming
-
-- Every test file must start with `test_` prefix (e.g. `test_order.py`, `test_user_api.py`)
-- pytest collects tests from files matching `test_*.py` or `*_test.py` — use `test_` prefix exclusively
-- Never create test files without the `test_` prefix
-
-#### Write Boundary
-
-- Only **create new** files under writeSet:
-  - `testcase/**/test_*.py`
-  - `testcase/**/helpers/**` (optional pure helpers)
-  - `testcase/**/factories/**` (optional test data factories)
-- Do NOT modify existing files: `conftest.py`, `pytest.ini`, `pyproject.toml`, `setup.cfg`, `__init__.py`, or any other framework/config file
-- Reuse existing fixtures; if required helpers are missing, create NEW helper/factory modules under the writeSet paths above — never edit root conftest
-- Read existing framework files to understand conventions, but treat them as immutable
-- Do NOT write production code, `.env`, secrets, or credential files
-
-#### Naming Conflict Resolution
-
-- If a file with the target name already exists under `testcase/`, add a numeric suffix: `test_order.py` → `test_order_01.py` → `test_order_02.py`
-- Never overwrite or append to existing files — each test script must be a standalone file
-- Check for existing files before writing; if `test_<module>.py` exists, use `test_<module>_01.py`
-
-#### 1:1 Traceability
-
-Every functional test case ID (`BE-<MODULE>-<NNN>`) must map to exactly one pytest function:
+- 输入：最终 `testcase/md/**`、run-owned 环境报告与 Markdown 校验报告，以及有界的 pytest config / `conftest.py`。
+- 禁止重新读取 `source/**`、新增测试场景、重新分配 AC、执行 pytest、修改生产代码/配置或输出业务 JSON。
+- 写入范围：`testcase/**/test_*.py`、`testcase/**/helpers/**`、`testcase/**/factories/**`。
+- pytest 可以使用模块级 `test_*` 函数，也可以使用 pytest 测试类中的 `test_*` 方法；不得为了追溯强迫目标项目放弃现有 class-based 风格。
+- 每个最终 Markdown Case ID 必须出现在至少一个真实测试函数/方法区域中，优先同时出现在函数/方法名和 docstring：
 
 ```python
-# testcase/md/BE-ORDER-001 → testcase/test_order.py
-def test_BE_ORDER_001_create_order_with_valid_data():
-    """BE-ORDER-001: Create order with valid request body."""
-    ...
+class TestOrderApi:
+    def test_BE_ORDER_001_create_order(self) -> None:
+        """BE-ORDER-001 创建合法订单。"""
+        ...
 ```
 
-- Function name: `test_<CASE_ID_with_underscores>` (e.g. `test_BE_ORDER_001_...`)
-- Docstring first line: `<CASE_ID>: <Case Title>`
-
-#### File Organization
-
-- All test files go under `testcase/` directory in the host project root
-- Group test files by MODULE segment: `BE-ORDER-*` → `testcase/test_order.py`, `BE-USER-*` → `testcase/test_user.py`
-- Follow existing project conventions for import style, fixture scope
-
-#### Fixture Strategy
-
-- Reuse existing project fixtures from `conftest.py` when available (read-only)
-- Do not create or modify root fixture/configuration files (`conftest.py`, pytest.ini, …)
-- Optional NEW helpers/factories may live under `testcase/**/helpers/**` or `testcase/**/factories/**` only
-- Prefer `@pytest.fixture(scope="function")` for test isolation
-- Use `@pytest.mark.parametrize` for boundary condition cases with multiple inputs
-
-#### Test Integrity
-
-- Tests verify implementation correctness — if a test fails, the implementation likely has a bug, not the test
-- Do NOT weaken assertions, remove test cases, or modify test logic to make tests pass
-- Do NOT add workarounds, skips, or try/except blocks to hide failures without explicit justification
-- Report all failures honestly in the output; the downstream `execute-backend-pytest-shell` node captures exit codes and stdout/stderr as-is
-
-#### Test Data Preparation Rules (MUST follow)
-
-**When Setup is Needed**
-
-Setup phase is REQUIRED only when test cases need pre-existing data:
-- Query/Read APIs: need data to exist before querying
-- Update/Delete APIs: need data to exist before modifying
-- State transition tests: need data in specific state
-
-Setup phase is NOT needed for:
-- Create APIs: testing the creation itself
-- Validation tests: testing input validation with invalid data
-
-**Data Setup Strategy**
-
-When setup is needed:
-1. Use `@pytest.fixture(scope='module')` or `@pytest.fixture(scope='session')` to prepare shared test data
-2. All test cases in the file share the same pre-constructed data
-
-**Data Construction Priority**
-
-1. **API-first**: Use documented APIs from `analyze-inputs-pi` / reviewed cases
-2. **Reuse existing conftest fixtures** (read-only)
-3. **Direct DB writes are last resort** and only via safe test-DB fixtures with rollback/isolation
-4. If neither API nor safe DB fixture exists, **skip with an explicit gap note** — do not invent credentials or touch live data
-
-**API Data Construction**
-
-- Prefer the `analyze-inputs-pi` API Endpoints section and reviewed cases for method/path/fields
-- Chain API calls only when cases document multi-step preconditions
-- Store created resource IDs in fixtures for reuse
-- Do **not** broadly search host route/controller trees for secrets, `.env`, private keys, or production configs
-- Read host API definitions only when needed to resolve a field name already referenced by reviewed cases
-
-**Database Data Construction (restricted)**
-
-- Allowed only via existing `conftest.py` test-DB fixtures with transaction rollback or equivalent isolation
-- Never hardcode connection strings, passwords, tokens, or cloud credentials
-- Never target production/shared non-test databases
-- If isolation is unclear, report the gap instead of writing DB rows
-
-#### Assertion Rules (MUST follow)
-
-**Positive Path (成功场景)**
-
-MUST assert ALL of the following:
-1. HTTP status code: as defined in API spec (e.g. 200, 201)
-2. Response structure: key fields exist in response body
-3. Specific values: each field equals expected value from test case
-4. Data type: each field is correct type
-
-**Negative Path (异常场景)**
-
-MUST assert ALL of the following:
-1. HTTP status code: as defined in API spec (e.g. 400, 404, 500)
-2. Error code field: field name from API spec (e.g. code, error_code, errcode, ret)
-3. Error message field: field name from API spec (e.g. message, msg, errmsg, error)
-
-**Field Name Resolution**
-
-Field names MUST come from the upstream `analyze-inputs-pi` output (API Endpoints section), NOT hardcoded. For example:
-- If API spec defines `{"ret": 0, "msg": "success"}`, assert `response.json()["ret"]` and `response.json()["msg"]`
-- If API spec defines `{"code": 4001, "message": "error"}`, assert `response.json()["code"]` and `response.json()["message"]`
-
-
-#### Conditional Test Implementation (include ONLY if test cases exist)
-
-- **Authentication tests**: implement ONLY if `testcase/md/` contains auth-related cases
-  - Use `@pytest.mark.auth` marker
-  - Test no token, expired token, invalid token, insufficient permissions, cross-user access
-- **Timeout tests**: implement ONLY if `testcase/md/` contains timeout-related cases
-  - Use `@pytest.mark.timeout` marker
-  - Use `unittest.mock.patch` or `pytest-mock` to simulate slow responses
-- If no such cases exist in the reviewed test cases, do NOT add these tests
-
-#### Markers
-
-- `@pytest.mark.positive` — happy path cases
-- `@pytest.mark.negative` — error/exception cases
-- `@pytest.mark.boundary` — edge cases
-- `@pytest.mark.<MODULE>` — module-specific marker (e.g. `@pytest.mark.order`)
-
-#### Skip Policy
-
-If a test case cannot be automated (requires external service not mockable, requires manual verification), add it with `@pytest.mark.skip(reason="...")` and document the reason. Do not omit the function — traceability requires it exists.
+- 断言只来自 `### 预期结果` / `### Expected Results`；setup 只来自 `### 前置条件`、`### 测试数据`、`### 自动化映射` 或对应历史英文分节。
+- 禁止 `skip` / `xfail`、吞断言、宽异常静默通过、mock 替代真实目标、删除用例或弱化断言。
+- best-effort 清理只能捕获所选 HTTP client 实际抛出的窄 transport exception，例如 `requests.RequestException` 或 `urllib.error.URLError`；禁止 `except:`、`except Exception`、`except BaseException` 后 `pass`。
+- 同一 Case ID 可以由多个 pytest 函数覆盖；额外映射会进入 traceability 报告，但不能伪造未在 Markdown 中定义的业务场景。
+- 测试失败必须诚实保留，后续节点只执行一次 pytest，并从同一 JUnit 生成 HTML/facts。
 
-### Output Shape (after summary line)
+## 推荐输出
 
-After the mandatory summary line, provide:
+写入文件后，用简短中文总结：
 
-1. **Generated Files** — list of files written under `tests/backend/`.
-2. **Function Mapping Table** — `| Test Case ID | Pytest Function | File | Marker |`.
-3. **Skipped Cases** — if any, list with reason.
-4. **Conventions Observed** — note project fixtures/config discovered and followed.
-5. **Residual Risks** — cases that may need manual verification or environment setup.
+1. 生成或更新了哪些测试文件；
+2. Case ID → 脚本 → pytest 函数/方法映射；
+3. 复用的 fixture/config；
+4. 仍存在的环境或自动化缺口。
 
-Do not include chain-of-thought. Do not write root `artifacts/**`.
+不得输出 chain-of-thought，不得执行 pytest。

package/docs/templates/backend-test-dag.json

@@ -68,8 +68,8 @@
   "executorModels": {
     "pi": {
       "LOW": "gpt-5.3-codex-spark",
-      "MED": "glm-5.2",
-      "HIGH": "gpt-5.5"
+      "MED": "grok-4.5",
+      "HIGH": "gpt-5.6-sol"
     }
   },
   "tasks": [
@@ -124,8 +124,8 @@
         ".harness/dag-runs/**",
         "artifacts/**"
       ],
-      "outputContract": "Write testcase/md/README.md plus module Markdown cases using BE-<MODULE>-<NNN>. Use Chinese for human-readable content while preserving required machine-readable identifiers and section headings; no JSON, pytest execution, production code or config writes.",
-      "subtask_prompt": "Read the upstream environment report. Generate a Markdown-first backend test strategy and cases under testcase/md/**.\n\nWrite human-readable content in Simplified Chinese by default: document titles, case titles, strategy explanations, preconditions, test-data descriptions, step descriptions, expected-result descriptions, automation notes, table headers and evidence-gap explanations. Keep English only where it is part of a machine-readable contract or established technical literal, including Case IDs, AC/REQ/BR IDs, exact section headings, HTTP methods, paths, field names, enum values, commands, filenames, code symbols and source citations. Do not add an English translation when Chinese already conveys the meaning.\n\nEvery case heading is `## BE-<MODULE>-<NNN> <中文用例标题>` and contains these exact machine-readable headings: `### Acceptance Criteria`, `### Source References`, `### Preconditions`, `### Test Data`, `### Steps`, `### Expected Results`, and `### Automation Notes`. API cases also contain `### Endpoint` with Method and Path. Under those headings, write descriptions in Chinese while preserving exact IDs, values and protocol literals.\n\nCreate testcase/md/README.md in Chinese. It should concisely explain the test objective, environment/target, isolation and cleanup strategy, module index, traceability summary, assertion principles, evidence gaps and non-goals. Prefer readable Chinese tables and lists over repeated boilerplate.\n\nExpected Results must be concrete, independently assertable Chinese statements. Each result should name the observable HTTP status, response field/value, state transition or membership condition instead of vague phrases such as ‘works correctly’ or ‘符合预期’. Steps must be executable and ordered. Use only environment-supported fixtures/targets/isolation. Record evidence gaps in Chinese instead of inventing behavior or credentials. Do not emit JSON, pytest, or execute commands.\n\n## Derived task contract: 需求.md\n\n# Backend test\n- AC-001 proof\n\n## Authoritative reference index\n\n[]\n\nFor each index entry, use `readPath` for Pi read-tool calls and copy `path` exactly into Markdown Source References. Bound files under .harness/tasks/<taskId>/source/** are read-only inputs: reading them is allowed even though writing .harness/** is forbidden. Never resolve `path` relative to the repository root, search for substitutes, or fall back to docs/** when a bound read fails.\n\nRead only precise indexed references needed for AC/API/field/rule evidence; references remain authoritative over derived text."
+      "outputContract": "Write a Chinese, human-readable testcase/md/README.md plus module Markdown case cards using BE-<MODULE>-<NNN>; keep machine IDs/literals exact and do not execute pytest or modify production code/config.",
+      "subtask_prompt": "Read the upstream environment report. Generate a Markdown-first backend test strategy and cases under testcase/md/**.\n\nWrite human-readable content in Simplified Chinese by default. Keep English only for machine-readable IDs and technical literals such as Case/AC/REQ/BR IDs, HTTP methods, paths, field names, enum values, commands, filenames, code symbols and exact source citations.\n\nCreate testcase/md/README.md as the concise entry page: test objective, target/environment, isolation/cleanup, module summary and a linked case index table with Case ID, Chinese case name, scenario type, endpoint and expected status/result. Avoid repeating every case body in README.\n\nWrite each module as readable case cards. Every case starts with `## BE-<MODULE>-<NNN>｜<中文用例名称>` and uses these Chinese headings: `### 测试目的`, `### 验收标准`, `### 需求依据`, `### 前置条件`, optional `### 测试数据`, `### 操作步骤`, `### 预期结果`, and `### 自动化映射`. API metadata may use a compact table under the case heading. The deterministic validator also accepts legacy English headings, but new output should use this Chinese presentation.\n\nPlace steps and their expected results in a compact readable table when that improves clarity; otherwise keep numbered executable steps and numbered/bulleted independently assertable results. Every result must name the observable HTTP status, response field/value, state transition or membership condition, never vague wording such as ‘符合预期’.\n\nIn `自动化映射`, record the planned script path and pytest function name when known. Put implementation-only restrictions in a concise `<details>` block rather than dominating the main case flow. Use only environment-supported fixtures/targets/isolation, record evidence gaps in Chinese, and do not emit JSON, pytest, or execute commands.\n\n## Derived task contract: 需求.md\n\n# Backend test\n- AC-001 proof\n\n## Authoritative reference index\n\n[]\n\nFor each index entry, use `readPath` for Pi read-tool calls and copy `path` exactly into Markdown Source References. Bound files under .harness/tasks/<taskId>/source/** are read-only inputs: reading them is allowed even though writing .harness/** is forbidden. Never resolve `path` relative to the repository root, search for substitutes, or fall back to docs/** when a bound read fails.\n\nRead only precise indexed references needed for AC/API/field/rule evidence; references remain authoritative over derived text."
     },
     {
       "id": "review-and-revise-backend-md-cases-pi",
@@ -149,7 +149,7 @@
         "artifacts/**"
       ],
       "outputContract": "Review source fidelity and directly revise only testcase/md/**; return concise Markdown, never JSON.",
-      "subtask_prompt": "Independently review generated Markdown cases against each case Source References and environment evidence. Preserve and improve the Simplified Chinese presentation: human-readable titles, prose, table headers, steps, expected results and notes should be Chinese unless the token is a machine-readable ID, exact required heading, HTTP/API literal, field/enum value, path, filename, command or code symbol.\n\nCheck AC completeness/meaning, endpoint, fields/shape, status/error codes, rules, states, documented boundaries/auth, positive/negative coverage, executable steps and assertable results. Also reject avoidable English prose, duplicated bilingual wording, vague Chinese results such as ‘符合预期’, and literal translations that obscure the observable assertion.\n\nCorrect testcase/md/** directly: add documented omissions, remove unsupported cases, fix mappings/expectations, merge duplicates, improve unclear Chinese wording, or record gaps in Chinese. Do not translate or alter Case IDs, AC/REQ/BR IDs, exact required section headings, HTTP methods, paths, field names, enum values, filenames, code symbols or Source References. Avoid cosmetic rewrites that do not improve correctness or readability.\n\nRead only precise referenced source paths plus requirement sections needed for uncovered ACs. Do not scan the repository, modify source/**, generate pytest, execute tests, or emit JSON.\n\n## Derived task contract: 需求.md\n\n# Backend test\n- AC-001 proof\n\n## Authoritative reference index\n\n[]\n\nFor each index entry, use `readPath` for Pi read-tool calls and keep `path` as the exact Markdown Source References citation. Bound files under .harness/tasks/<taskId>/source/** are read-only inputs: reading them is allowed even though writing .harness/** is forbidden. Never resolve `path` relative to the repository root, search for substitutes, or fall back to docs/** when a bound read fails."
+      "subtask_prompt": "Independently review generated Markdown cases against each case 需求依据 and environment evidence. Treat the files as human-facing test documentation: require a clear Chinese name and scenario/purpose, compact metadata, readable steps/results, and a concise automation mapping while preserving exact machine IDs and technical literals.\n\nCheck AC completeness/meaning, endpoint, fields/shape, status/error codes, rules, states, documented boundaries/auth, positive/negative coverage, executable steps and assertable results. Reject avoidable English prose, duplicated bilingual wording, repeated boilerplate, oversized unstructured sections, vague results such as ‘符合预期’, and missing script/function mapping where it can be derived.\n\nCorrect testcase/md/** directly: add documented omissions, remove unsupported cases, fix mappings/expectations, merge duplicates, improve navigation/tables/Chinese wording, or record gaps in Chinese. Keep Case IDs, AC/REQ/BR IDs, HTTP methods, paths, fields, enum values, filenames, code symbols and source citations exact. The validator accepts Chinese and legacy English section aliases; retain or converge to the Chinese human-readable headings without losing structure.\n\nRead only precise referenced source paths plus requirement sections needed for uncovered ACs. Do not scan the repository, modify source/**, generate pytest, execute tests, or emit JSON.\n\n## Derived task contract: 需求.md\n\n# Backend test\n- AC-001 proof\n\n## Authoritative reference index\n\n[]\n\nFor each index entry, use `readPath` for Pi read-tool calls and keep `path` as the exact Markdown Source References citation. Bound files under .harness/tasks/<taskId>/source/** are read-only inputs: reading them is allowed even though writing .harness/** is forbidden. Never resolve `path` relative to the repository root, search for substitutes, or fall back to docs/** when a bound read fails."
     },
     {
       "id": "validate-backend-md-cases-shell",
@@ -203,7 +203,7 @@
         "artifacts/**"
       ],
       "outputContract": "Convert every final automatable Markdown case into pytest assets whose actual test function region contains the exact Case ID, preferably in the function name or docstring; no JSON and no pytest execution.",
-      "subtask_prompt": "Convert validated testcase/md/** to pytest using upstream environment and validation evidence plus only bounded pytest config/conftest.\n\nEnsure every final Markdown Case ID appears in at least one real top-level test_* function region, preferably as `test_BE_<MODULE>_<NNN>_<description>` or in that function's docstring. Multiple test functions may cover one Case ID; assertions come only from Expected Results and setup comes only from Preconditions/Test Data/Automation Notes.\n\nDo not read source/**, add cases, reassign ACs, modify conftest/config/production code, use skip/xfail, swallow assertions, execute pytest, or emit JSON."
+      "subtask_prompt": "Convert validated testcase/md/** to pytest using upstream environment and validation evidence plus only bounded pytest config/conftest.\n\nEnsure every final Markdown Case ID appears in at least one real pytest test function or pytest test class method region, preferably as `test_BE_<MODULE>_<NNN>_<description>` and in that function/method docstring. Module-level functions and class-based pytest methods are both supported. Multiple test functions may cover one Case ID; assertions come only from 预期结果/Expected Results and setup comes only from 前置条件/测试数据/自动化映射 or their legacy English aliases.\n\nDo not read source/**, add cases, reassign ACs, modify conftest/config/production code, use skip/xfail, swallow assertions, execute pytest, or emit JSON. For best-effort cleanup, catch only the narrow transport exception actually raised by the selected HTTP client (for example `requests.RequestException` or `urllib.error.URLError`); never use bare `except`, `Exception`, or `BaseException` with `pass`."
     },
     {
       "id": "backend-test-traceability-gate-shell",
@@ -224,7 +224,7 @@
         "artifacts/**"
       ],
       "outputContract": "Run-owned reports/backend-test-traceability.md proving every real Markdown Case ID is covered by at least one pytest test function.",
-      "subtask_prompt": "Fail closed only when a real Markdown case heading has no associated top-level pytest test function. Accept exact Case IDs in the function name or its decorator/body/docstring region; report multiple mappings and extra automation Case IDs without blocking. Continue to reject skip/xfail or swallowed exceptions.",
+      "subtask_prompt": "Fail closed only when a real Markdown case heading has no associated pytest test function or class method. Accept exact Case IDs in the function/method name or its decorator/body/docstring region; report multiple mappings and extra automation Case IDs without blocking. Continue to reject skip/xfail or swallowed exceptions.",
       "shell": {
         "commands": [],
         "backendTestPipeline": "markdown-traceability",
@@ -251,7 +251,7 @@
         "artifacts/**"
       ],
       "outputContract": "One pytest execution producing valid JUnit, self-contained HTML and reports/backend-test-facts.md; exit 0/1 with valid evidence continues.",
-      "subtask_prompt": "Execute pytest exactly once. Validate JUnit, render self-contained HTML from that JUnit without rerun, and preserve failures as facts.",
+      "subtask_prompt": "Execute pytest exactly once. Validate JUnit, render the primary self-contained Chinese HTML report from the same JUnit plus final Markdown case metadata without rerun, list every case with name/scenario/script/function/result/duration, and preserve failure summaries plus expandable technical details as facts.",
       "shell": {
         "commands": [
           "mkdir -p \"${HARNESS_DAG_RUN_DIR}/reports\"; PYTHONUTF8=1 PYTHONIOENCODING=utf-8 PYTHONDONTWRITEBYTECODE=1 python -m pytest testcase/ -v -p no:cacheprovider --junitxml=\"${HARNESS_DAG_RUN_DIR}/reports/backend-test.junit.xml\"; STATUS=$?; printf \"%s\" \"${STATUS}\" > \"${HARNESS_DAG_RUN_DIR}/reports/backend-test-pytest-exit.txt\"; if { [ \"${STATUS}\" -eq 0 ] || [ \"${STATUS}\" -eq 1 ]; } && [ -s \"${HARNESS_DAG_RUN_DIR}/reports/backend-test.junit.xml\" ]; then exit 0; fi; exit \"${STATUS}\""