@tea-agent/loop-agent 0.25.0 → 0.25.2

package/dist/workflows/dag/backend-test-markdown-workflow.js

@@ -1,6 +1,12 @@
 import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { connect } from "node:net";
 import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { createWriteStream } from "node:fs";
 import path from "node:path";
+import { promisify } from "node:util";
+import { parseJacocoXml, } from "./backend-test-coverage-contract.js";
+const execFileAsync = promisify(execFile);
 const CASE_ID = /\bBE-[A-Z0-9]+(?:-[A-Z0-9]+)*-\d{3}\b/g;
 const AC_ID = /\bAC-[A-Z0-9]+(?:-[A-Z0-9]+)*\b/g;
 const SECRET = /(?:password|passwd|secret|token|api[_-]?key|private[_-]?key|authorization)\s*[:=]\s*\S+/i;
@@ -768,15 +774,57 @@ export async function collectBackendTestHumanCaseCatalog(workspaceRoot) {
 function junitCaseId(name) {
     return symbolCaseId(name) ?? name.match(CASE_ID)?.[0];
 }
+/** Prefer function-name Case ID; fall back to first BE-* in free text (docstring/log). */
+function extractCaseIdFromText(value) {
+    if (!value?.trim())
+        return undefined;
+    return junitCaseId(value) ?? value.match(CASE_ID)?.[0];
+}
+function resolveReportCaseId(result, catalog) {
+    const fromName = extractCaseIdFromText(result.name);
+    if (fromName && catalog.has(fromName))
+        return fromName;
+    if (fromName)
+        return fromName;
+    // Match catalog by pytest function/method name when Case ID is only in docstring/md.
+    const byFunction = [...catalog.values()].find((item) => item.testFunctions.includes(result.name));
+    if (byFunction)
+        return byFunction.id;
+    const fromStdout = extractCaseIdFromText(result.stdout);
+    if (fromStdout && catalog.has(fromStdout))
+        return fromStdout;
+    if (fromStdout)
+        return fromStdout;
+    const fromDetails = extractCaseIdFromText(result.details);
+    if (fromDetails && catalog.has(fromDetails))
+        return fromDetails;
+    return "未关联";
+}
 function humanStatus(status) {
     return status === "passed" ? "通过" : status === "failure" ? "失败" : status === "error" ? "错误" : "跳过";
 }
 function formatDuration(durationMs) {
     return durationMs === undefined ? "未记录" : `${(durationMs / 1000).toFixed(3)} 秒`;
 }
-function inferredScriptPath(classname) {
-    const moduleName = classname.split(".").filter((part) => part && !/^Test/.test(part)).join("/");
-    return `${moduleName || "unknown"}.py`;
+function inferredScriptPath(classname, filePath) {
+    if (filePath?.trim()) {
+        return filePath.replaceAll("\\", "/").replace(/^\.\//, "");
+    }
+    const moduleName = classname
+        .split(".")
+        .filter((part) => part && !/^Test[A-Z_]/.test(part) && part !== "Test")
+        .join("/");
+    if (!moduleName || moduleName === "unknown")
+        return "unknown.py";
+    return moduleName.endsWith(".py") ? moduleName : `${moduleName}.py`;
+}
+function resolveReportScriptPath(result, item) {
+    if (item?.scriptPath)
+        return item.scriptPath;
+    if (result.filePath?.trim()) {
+        return result.filePath.replaceAll("\\", "/").replace(/^\.\//, "");
+    }
+    return inferredScriptPath(result.classname, result.filePath);
 }
 export function redactBackendTestOutput(value) {
     return value
@@ -809,8 +857,97 @@ function reportOutputLines(value, prefix) {
         return redactBackendTestOutput(trimmed.trim()).slice(0, 4000);
     });
 }
+/**
+ * Normalize alternate HTTP log dialects into HTTP_REQUEST / HTTP_RESPONSE lines.
+ * Supports common project helpers that emit [REQ]/[RESP] block style instead of
+ * the contract prefixes (keeps original HTTP_* lines unchanged).
+ */
+export function normalizeBackendTestHttpLogText(value) {
+    if (!value.trim())
+        return value;
+    const lines = value.split(/\r?\n/);
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        const raw = lines[i];
+        const line = raw.trim();
+        // Already-contract lines: pass through.
+        if (/^(HTTP_REQUEST|HTTP REQUEST|HTTP_RESPONSE|HTTP RESPONSE)\b/i.test(line)) {
+            out.push(raw);
+            i += 1;
+            continue;
+        }
+        // [REQ] METHOD path  OR  [REQ] METHOD url
+        const reqHead = line.match(/^\[REQ\]\s+([A-Z]+)\s+(\S+)\s*$/i);
+        if (reqHead) {
+            const method = reqHead[1].toUpperCase();
+            const url = reqHead[2];
+            let body = "";
+            let j = i + 1;
+            // Optional [REQ body] then JSON/text until separator or next tag.
+            if (j < lines.length && /^\[REQ\s*body\]/i.test(lines[j].trim())) {
+                j += 1;
+                const bodyLines = [];
+                while (j < lines.length &&
+                    !/^[=-]{3,}\s*$/.test(lines[j].trim()) &&
+                    !/^\[(?:REQ|RESP)/i.test(lines[j].trim()) &&
+                    !/^(HTTP_REQUEST|HTTP_RESPONSE|HTTP REQUEST|HTTP RESPONSE)\b/i.test(lines[j].trim())) {
+                    bodyLines.push(lines[j]);
+                    j += 1;
+                }
+                body = bodyLines.join("\n").trim();
+            }
+            const payload = { method, url };
+            if (body) {
+                try {
+                    payload.json = JSON.parse(body);
+                }
+                catch {
+                    payload.body = body.slice(0, 4000);
+                }
+            }
+            out.push(`HTTP_REQUEST ${JSON.stringify(payload)}`);
+            i = j;
+            continue;
+        }
+        // [RESP status] 200  OR  [RESP] 200
+        const respHead = line.match(/^\[RESP(?:\s+status)?\]\s+(\d{3})\b/i);
+        if (respHead) {
+            const status_code = Number(respHead[1]);
+            let body = "";
+            let j = i + 1;
+            if (j < lines.length && /^\[RESP\s*body\]/i.test(lines[j].trim())) {
+                j += 1;
+                const bodyLines = [];
+                while (j < lines.length &&
+                    !/^[=-]{3,}\s*$/.test(lines[j].trim()) &&
+                    !/^\[(?:REQ|RESP)/i.test(lines[j].trim()) &&
+                    !/^(HTTP_REQUEST|HTTP_RESPONSE|HTTP REQUEST|HTTP RESPONSE)\b/i.test(lines[j].trim())) {
+                    bodyLines.push(lines[j]);
+                    j += 1;
+                }
+                body = bodyLines.join("\n").trim();
+            }
+            const payload = { status_code };
+            if (body) {
+                try {
+                    payload.result = JSON.parse(body);
+                }
+                catch {
+                    payload.result = body.slice(0, 4000);
+                }
+            }
+            out.push(`HTTP_RESPONSE ${JSON.stringify(payload)}`);
+            i = j;
+            continue;
+        }
+        out.push(raw);
+        i += 1;
+    }
+    return out.join("\n");
+}
 function requestResponseSummary(result) {
-    const combined = [result.stdout, result.stderr].filter(Boolean).join("\n");
+    const combined = normalizeBackendTestHttpLogText([result.stdout, result.stderr].filter(Boolean).join("\n"));
     return {
         requests: reportOutputLines(combined, "HTTP_REQUEST"),
         responses: reportOutputLines(combined, "HTTP_RESPONSE"),
@@ -1047,8 +1184,8 @@ export function renderBackendTestHtml(input) {
     const failures = input.parsed.cases.filter((result) => result.status !== "passed");
     const headColor = failed ? { fg: "#b42318", bg: "linear-gradient(135deg,#fef3f2 0,#fee4e2 100%)", border: "#fda29b", icon: "✗" } : { fg: "#067647", bg: "linear-gradient(135deg,#ecfdf3 0,#d1fadf 100%)", border: "#abefc6", icon: "✓" };
     const caseCards = input.parsed.cases.map((result) => {
-        const caseId = junitCaseId(result.name) ?? "未关联";
-        const item = catalog.get(caseId);
+        const caseId = resolveReportCaseId(result, catalog);
+        const item = caseId === "未关联" ? undefined : catalog.get(caseId);
         const io = requestResponseSummary(result);
         const calls = pairHttpCalls(io.requests, io.responses);
         const statusColors = statusColor(result.status);
@@ -1058,7 +1195,7 @@ export function renderBackendTestHtml(input) {
         const failureBlock = result.status === "passed"
             ? ""
             : `<div style="margin-top:12px;padding:10px 12px;border-radius:8px;background:#fef3f2;border:1px solid #fda29b;color:#b42318;font-size:0.84rem"><strong>${escapeHtml(result.message || humanStatus(result.status))}</strong>${result.details ? `<details style="margin-top:6px"><summary style="cursor:pointer;color:#b42318;font-size:0.78rem">失败详情</summary><pre style="white-space:pre-wrap;background:#f6f8fa;color:#1f2937;padding:10px 12px;border-radius:8px;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:0.78rem;margin-top:6px;border:1px solid #eceef2;line-height:1.6">${escapeHtml(result.details)}</pre></details>` : ""}</div>`;
-        const scriptPath = item?.scriptPath ?? inferredScriptPath(result.classname);
+        const scriptPath = resolveReportScriptPath(result, item);
         return `<details style="background:#fff;border:1px solid #e6eaf0;border-radius:12px;margin-top:10px"><summary style="display:flex;align-items:center;gap:12px;padding:12px 16px;cursor:pointer;list-style:none"><span style="background:#e8edf5;color:#2b3a55;padding:2px 9px;border-radius:6px;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:0.76rem;font-weight:600;white-space:nowrap">${escapeHtml(caseId)}</span><div style="flex:1;min-width:0"><div style="font-weight:600;color:#172033;font-size:0.92rem">${escapeHtml(item?.title ?? result.name)}</div><code style="font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:0.74rem;color:#98a2b3">${escapeHtml(result.name)}</code></div><span style="color:#98a2b3;font-size:0.8rem;white-space:nowrap">${formatDuration(result.durationMs)}</span><span style="display:inline-block;padding:2px 10px;border-radius:999px;font-weight:700;font-size:0.72rem;color:${statusColors.fg};background:${statusColors.bg}">${humanStatus(result.status)}</span><span style="color:#aab2bf;font-size:0.8rem">▾</span></summary><div style="padding:4px 16px 14px 16px;border-top:1px solid #f0f3f7"><div style="margin-top:10px"><div style="color:#667085;font-size:0.74rem;font-weight:600;margin-bottom:3px">自动化脚本</div><code style="background:#eef2f7;color:#344054;padding:1px 6px;border-radius:5px;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:0.8rem">${escapeHtml(scriptPath)}</code></div>${item?.scenario ? `<div style="margin-top:12px"><div style="color:#667085;font-size:0.74rem;font-weight:600;margin-bottom:3px">验收场景</div><div style="color:#475467;font-size:0.86rem;line-height:1.75">${escapeHtml(item.scenario)}</div></div>` : ""}${logSection}${failureBlock}</div></details>`;
     }).join("");
     const metricCard = (label, value, valueColor = "#172033") => `<div style="padding:14px 16px;border:1px solid #e3e8ef;border-radius:12px;background:#fbfcfe"><span style="color:#667085;font-size:0.78rem">${escapeHtml(label)}</span><div style="font-size:22px;font-weight:700;color:${valueColor}">${value}</div></div>`;
@@ -1067,7 +1204,7 @@ export function renderBackendTestHtml(input) {
     const qualityBlock = `<div style="margin-top:18px"><div style="color:#17365d;font-size:16px;font-weight:700;margin:0 4px 6px">质量校验</div><div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:12px;margin-top:8px">${renderQualityCard("Markdown 用例校验", caseValidation)}${renderQualityCard("Markdown → pytest 追溯", traceability)}</div></div>`;
     const failureOverview = failures.length > 0
         ? `<div style="margin-top:18px"><div style="color:#17365d;font-size:16px;font-weight:700;margin:0 4px 6px">失败概览</div><div style="display:grid;gap:10px;margin-top:8px">${failures.map((result) => {
-            const caseId = junitCaseId(result.name) ?? "未关联";
+            const caseId = resolveReportCaseId(result, catalog);
             const c = statusColor(result.status);
             return `<div style="border-left:4px solid ${c.fg};background:${c.bg};padding:10px 12px;border-radius:8px"><div style="font-weight:600;color:#172033;font-size:0.88rem">${escapeHtml(caseId)} · ${escapeHtml(catalog.get(caseId)?.title ?? result.name)}</div><div style="color:${c.fg};font-size:0.82rem;margin-top:2px">${escapeHtml(result.message || humanStatus(result.status))}</div></div>`;
         }).join("")}</div></div>`
@@ -1079,6 +1216,98 @@ function renderQualityCard(title, summary) {
     const label = summary.status === "Unavailable" ? "不可用" : summary.status;
     return `<div style="padding:12px 14px;border:1px solid #e3e8ef;border-radius:10px;background:#fbfcfe"><div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:6px"><strong style="color:#17365d;font-size:0.88rem">${escapeHtml(title)}</strong><span style="display:inline-block;padding:2px 9px;border-radius:999px;font-weight:700;font-size:0.72rem;color:${colors.fg};background:${colors.bg}">${label}</span></div><div style="color:#667085;font-size:0.78rem">Findings：${summary.findings ?? "不可用"}</div><div style="color:#475467;font-size:0.8rem;margin-top:2px">${escapeHtml(summary.firstFinding)}</div></div>`;
 }
+/**
+ * Dump JaCoCo execution data over TCP from a JaCoCo tcpserver agent, convert
+ * .exec → jacoco.xml via jacococli.jar, then parse into a code-coverage-v1
+ * contract. Designed for Java services started with
+ * `-javaagent:jacocoagent.jar=output=tcpserver,port=6300,append=false`.
+ *
+ * Failure-safe: any transport/conversion/parse error returns null so the L-5
+ * dashboard degrades coverage to unavailable instead of blocking the run.
+ */
+export async function collectJacocoCoverage(input) {
+    const [host, portStr] = input.endpoint.split(":");
+    const port = Number(portStr);
+    if (!host || !Number.isInteger(port) || port <= 0 || port > 65535) {
+        return null;
+    }
+    const execPath = path.join(input.workDir, "jacoco.exec");
+    const xmlPath = path.join(input.workDir, "jacoco.xml");
+    // Step 1: TCP dump of JaCoCo execution data. The protocol is JaCoCo's
+    // binary "dump" command: a magic header + command byte. We send the dump
+    // request and stream the response into jacoco.exec.
+    try {
+        await dumpJacocoExec(host, port, execPath, input.connectTimeoutMs);
+    }
+    catch {
+        return null;
+    }
+    // Step 2: jacococli.jar report .exec → jacoco.xml
+    try {
+        await execFileAsync("java", [
+            "-jar", input.cliJarPath,
+            "report", execPath,
+            "--xml", xmlPath,
+            "--includes", input.includes,
+        ], { timeout: 60000, windowsHide: true });
+    }
+    catch {
+        return null;
+    }
+    // Step 3: parse jacoco.xml into a code-coverage-v1 contract.
+    try {
+        const xml = await readFile(xmlPath, "utf8");
+        const artifactSha256 = createHash("sha256").update(xml).digest("hex");
+        return parseJacocoXml(xml, {
+            sourceScope: input.sourceScope,
+            commitSha: input.commitSha,
+            artifactPath: "reports/jacoco.xml",
+            artifactSha256,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Send a JaCoCo TCP dump command and stream the response into destPath.
+ * JaCoCo tcpserver protocol: connect, send dump command header, read until close.
+ */
+function dumpJacocoExec(host, port, destPath, connectTimeoutMs) {
+    return new Promise((resolve, reject) => {
+        const socket = connect({ host, port });
+        const writeStream = createWriteStream(destPath);
+        const timer = setTimeout(() => {
+            socket.destroy();
+            reject(new Error("jacoco-tcp-connect-timeout"));
+        }, connectTimeoutMs);
+        socket.on("connect", () => {
+            // JaCoCo TCP "dump" command: magic 0xC0FFEE + cmd=0x40 (dump)
+            // Format: <magic 3 bytes><cmd id 1 byte>
+            // The server responds with the exec data and closes.
+            const magic = Buffer.from([0xC0, 0xFF, 0xEE]);
+            const dumpCmd = Buffer.from([0x40]);
+            socket.end(Buffer.concat([magic, dumpCmd]));
+        });
+        socket.on("error", (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        socket.on("close", () => {
+            clearTimeout(timer);
+            writeStream.end(() => {
+                // Verify we got non-empty exec data.
+                readFile(destPath).then((buf) => {
+                    if (buf.length === 0)
+                        reject(new Error("jacoco-dump-empty"));
+                    else
+                        resolve();
+                }).catch(reject);
+            });
+        });
+        socket.pipe(writeStream);
+    });
+}
 function inferModuleScript(classname) {
     // classname like "test_process_definition_list.py::TestX::test_a" → take the file stem.
     const first = classname.split("::")[0] ?? classname;
@@ -1244,9 +1473,9 @@ export function renderBackendTestFacts(input) {
         "| 用例编号 | 用例名称 | 自动化脚本 | 测试函数 | 结果 | 耗时 | 失败原因 |",
         "|---|---|---|---|---|---:|---|",
         ...input.parsed.cases.map((result) => {
-            const caseId = junitCaseId(result.name) ?? "未关联";
-            const item = catalog.get(caseId);
-            const script = item?.scriptPath ?? inferredScriptPath(result.classname);
+            const caseId = resolveReportCaseId(result, catalog);
+            const item = caseId === "未关联" ? undefined : catalog.get(caseId);
+            const script = resolveReportScriptPath(result, item);
             return `| ${caseId} | ${item?.title ?? result.name} | \`${script}\` | \`${result.name}\` | ${humanStatus(result.status)} | ${formatDuration(result.durationMs)} | ${(result.message ?? "—").replaceAll("|", "\\|")} |`;
         }),
         "",

package/dist/workflows/dag/backend-test-result-contract.js

@@ -428,7 +428,8 @@ export function parsePytestHtmlReport(html) {
             continue;
         const rawResult = (record.result ?? "").toLowerCase();
         const testId = record.testId ?? nodeId;
-        const { classname, name } = splitPytestNodeId(testId);
+        const { classname, name, filePath } = splitPytestNodeId(testId);
+        const filePathFields = filePath ? { filePath } : {};
         const durationMs = parseDurationLabelMs(record.duration);
         const capturedLog = record.log ?? "";
         // pytest-html collapses captured stdout/stderr into a single `log` field
@@ -441,6 +442,8 @@ export function parsePytestHtmlReport(html) {
             cases.push({
                 classname,
                 name,
+                ...filePathFields,
+                ...filePathFields,
                 durationMs,
                 status: "passed",
                 ...(stdout ? { stdout } : {}),
@@ -455,6 +458,7 @@ export function parsePytestHtmlReport(html) {
             cases.push({
                 classname,
                 name,
+                ...filePathFields,
                 durationMs,
                 status: "failure",
                 message: summary,
@@ -471,6 +475,7 @@ export function parsePytestHtmlReport(html) {
             cases.push({
                 classname,
                 name,
+                ...filePathFields,
                 durationMs,
                 status: "error",
                 message: summary,
@@ -484,6 +489,7 @@ export function parsePytestHtmlReport(html) {
             cases.push({
                 classname,
                 name,
+                ...filePathFields,
                 durationMs,
                 status: "skipped",
                 ...(stdout ? { stdout } : {}),
@@ -499,6 +505,7 @@ export function parsePytestHtmlReport(html) {
             cases.push({
                 classname,
                 name,
+                ...filePathFields,
                 durationMs,
                 status: "error",
                 message: summary,
@@ -520,20 +527,44 @@ export function parsePytestHtmlReport(html) {
         failures: failures.slice(0, MAX_FAILURES),
     };
 }
-function splitPytestNodeId(testId) {
-    // pytest-html uses node ids like "path/to/test_x.py::TestClass::test_name".
-    const sepIndex = testId.lastIndexOf("::");
-    if (sepIndex < 0) {
-        return { classname: "unknown", name: testId };
-    }
-    const prefix = testId.slice(0, sepIndex);
-    const name = testId.slice(sepIndex + 2);
-    const lastParen = name.indexOf("(");
-    const cleanName = lastParen >= 0 ? name.slice(0, lastParen) : name;
-    const moduleSep = prefix.lastIndexOf("::");
-    const filePart = moduleSep >= 0 ? prefix.slice(moduleSep + 2) : prefix;
-    const moduleWithoutExt = filePart.replace(/\.py$/i, "");
-    return { classname: moduleWithoutExt.replace(/\//g, ".") || "unknown", name: cleanName };
+/**
+ * Split a pytest node id into module classname, test name, and optional file path.
+ *
+ * Handles:
+ * - `testcase/test_x.py::test_name`
+ * - `testcase/test_x.py::TestClass::test_name` (class-based; previous code
+ *   treated `TestClass` as the file segment and later filtered it to unknown.py)
+ * - Windows separators and parametrized names `test_name[param]`
+ */
+export function splitPytestNodeId(testId) {
+    const normalized = testId.replaceAll("\\", "/").trim();
+    if (!normalized) {
+        return { classname: "unknown", name: "unknown" };
+    }
+    const parts = normalized.split("::").filter(Boolean);
+    if (parts.length < 2) {
+        // Bare id without "::" — keep as name; path unknown.
+        return { classname: "unknown", name: normalized };
+    }
+    let rawName = parts[parts.length - 1];
+    // Drop call args if present; keep parametrize brackets in display name strip for id match.
+    const paren = rawName.indexOf("(");
+    if (paren >= 0)
+        rawName = rawName.slice(0, paren);
+    const cleanName = rawName.trim() || "unknown";
+    // Prefer the first segment that looks like a .py file path.
+    const filePart = parts.find((part) => /\.py$/i.test(part)) ??
+        (parts[0].includes("/") || parts[0].includes(".") ? parts[0] : undefined);
+    const filePath = filePart
+        ? filePart.replace(/\\/g, "/")
+        : undefined;
+    const moduleWithoutExt = (filePath ?? "unknown").replace(/\.py$/i, "");
+    const classname = moduleWithoutExt.replaceAll("/", ".") || "unknown";
+    return {
+        classname,
+        name: cleanName,
+        ...(filePath ? { filePath } : {}),
+    };
 }
 function splitPytestHtmlLogSections(log) {
     if (!log)

package/dist/workflows/dag/init-hybrid.js

@@ -1,8 +1,8 @@
 import { createHash } from "node:crypto";
-import { access, readdir, readFile, realpath, writeFile, } from "node:fs/promises";
+import { access, readdir, readFile, realpath, } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
-import os from "node:os";
 import path from "node:path";
+import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
 import { assertValidDagSpec } from "./validate.js";
 import { DAG_AGENT_RUNTIME_PI_ONLY, DAG_REPAIR_WRITER_PROTOCOL_EXPLICIT_NODE_V1, DAG_RUNTIME_CONTRACT_SCHEMA_VERSION, DEFAULT_DAG_OUTPUT_LANGUAGE, DEFAULT_DAG_EXECUTOR_MODELS, parseDagSpec, } from "./types.js";
 import { planMavenVerification, } from "../../verification/maven/index.js";
@@ -3515,7 +3515,7 @@ async function buildBackendTestHybridDag(sources) {
         'mkdir -p "${HARNESS_DAG_RUN_DIR}/reports"',
         'echo "pytest targets are resolved at runtime from final Markdown 自动化映射"',
     ].join("; ");
-    const execute = shellNode("execute-backend-pytest-and-html-report-shell", [traceability.id], "markdown-execute-html", "Resolve the final Markdown Automation Notes/自动化映射 to a unique, safe set of testcase/**/test_*.py targets and execute only those scripts exactly once. Prefer the deterministic module one-to-one path when a mapped script is missing but the module stem file exists. Generate a native pytest-html self-contained report, then render the primary self-contained Chinese HTML report from the same pytest-html plus final Markdown case metadata without rerun. Keep 测试结论, quality status, failure overview, and a polished per-case result card with concise scenario, automation test name, result, duration, and redacted bounded HTTP request parameters/response results for both passed and failed cases. Do not render a technical/execution evidence section in HTML; retain auditable paths and hashes in facts.", "One scoped pytest execution over Markdown-mapped scripts producing a valid pytest-html report with per-case captured output, self-contained reports/backend-test.html, reports/backend-test.md, reports/backend-test-facts.md, and a deterministic self-contained reports/backend-test-l5-dashboard.html (machine-computed L-5 metrics, no JSON); exit 0/1 with valid evidence continues.", [pytestCommand], 300000);
+    const execute = shellNode("execute-backend-pytest-and-html-report-shell", [traceability.id], "markdown-execute-html", "Resolve the final Markdown Automation Notes/自动化映射 to a unique, safe set of testcase/**/test_*.py targets and execute only those scripts exactly once. Prefer the deterministic module one-to-one path when a mapped script is missing but the module stem file exists. Generate a native pytest-html self-contained report, then render the primary self-contained Chinese HTML report from the same pytest-html plus final Markdown case metadata without rerun. Keep 测试结论, quality status, failure overview, and a polished per-case result card with concise scenario, automation test name, result, duration, and redacted bounded HTTP request parameters/response results for both passed and failed cases. Do not render a technical/execution evidence section in HTML; retain auditable paths and hashes in facts.", "One scoped pytest execution over Markdown-mapped scripts producing a valid pytest-html report with per-case captured output, self-contained reports/backend-test.html, reports/backend-test.md, reports/backend-test-facts.md, a deterministic self-contained reports/backend-test-l5-dashboard.html (machine-computed L-5 metrics, no JSON), and an optional contracts/code-coverage-v1.json when jacocoCoverage is configured (JaCoCo TCP dump → jacoco.xml → parsed; failure-safe); exit 0/1 with valid evidence continues.", [pytestCommand], 300000);
     if (execute.shell) {
         execute.shell.envAllowlist = collectBackendTestShellEnvAllowlist(sources);
     }
@@ -5741,9 +5741,6 @@ function buildSupervisedHybridDag(standard, sources) {
     assertValidDagSpec(spec);
     return spec;
 }
-export function defaultHybridDagOutputPath(taskId) {
-    return path.join(os.tmpdir(), `${taskId}-hybrid-dag.json`);
-}
 export async function writeHybridDagDraft(sources, outputPath, options = {}) {
     const routingProjectCapability = sources.taskConfig.taskKind === "standard" &&
         (options.template === undefined || options.template === "standard-dag")
@@ -5774,7 +5771,7 @@ export async function writeHybridDagDraft(sources, outputPath, options = {}) {
             taskId: preparedSources.taskId,
         });
     }
-    await writeFile(outputPath, `${JSON.stringify(spec, null, 2)}\n`, "utf-8");
+    await writeJsonAtomic(outputPath, spec, { repoRoot: sources.repoRoot });
     return {
         taskId: sources.taskId,
         outputPath,
@@ -5787,7 +5784,7 @@ export async function writeHybridDagDraft(sources, outputPath, options = {}) {
 export async function initHybridDagFromTask(repoRoot, taskId, options = {}) {
     const sources = await loadTaskHybridSources(repoRoot, taskId);
     assertTaskAllowedPathsPreflight(sources.taskConfig);
-    const outputPath = options.outputPath ?? defaultHybridDagOutputPath(taskId);
+    const outputPath = options.outputPath ?? getTaskPaths(repoRoot, taskId).dagDraftPath;
     return writeHybridDagDraft(sources, outputPath, {
         template: options.template,
     });

package/dist/workflows/dag/types.js

@@ -326,6 +326,17 @@ export const dagShellConfigSchema = z.object({
     frontendReviewContext: dagFrontendReviewContextSchema.optional(),
     frontendTestEvidenceValidation: dagFrontendTestEvidenceValidationSchema.optional(),
     backendTestPipeline: dagBackendTestPipelineSchema.optional(),
+    /** JaCoCo coverage collection for backend-test (Java services). When set, node 7 dumps coverage over TCP from a JaCoCo tcpserver agent and feeds it to the L-5 dashboard. */
+    jacocoCoverage: z.object({
+        /** JaCoCo tcpserver endpoint, e.g. "host:6300". */
+        endpoint: z.string().min(1),
+        /** Absolute path to jacococli.jar on this machine, used to convert .exec → jacoco.xml. */
+        cliJarPath: z.string().min(1),
+        /** Business package filter passed to JaCoCo includes, e.g. "com.example.*". Defaults to "*". */
+        includes: z.string().min(1).optional().default("*"),
+        /** TCP connect timeout in ms. Defaults to 5000. */
+        connectTimeoutMs: z.number().int().positive().optional().default(5000),
+    }).strict().optional(),
     verifyEvidence: dagShellVerifyEvidenceSchema.optional(),
     repairArtifactGate: dagRepairArtifactGateSchema.optional(),
     /** fail (default): any nonzero command fails the node. record: finish node FINISHED with failure facts for downstream assess/repair. */

package/dist/workflows/loop/actions/dag-action.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { mkdir } from "node:fs/promises";
 import { writeLoopDagRecord } from "../../../infrastructure/harness/loop-action-store.js";
+import { getTaskPaths } from "../../../task/runtime.js";
 import { getLoopPaths } from "../paths.js";
 import { appendLoopRound } from "../rounds.js";
 import { rewriteLoopContext } from "../context.js";
@@ -26,7 +27,7 @@ export async function runLoopDagAction(repoRoot, taskId, options = {}) {
     await mkdir(dagEvidenceDir, { recursive: true });
     const dagPath = options.dagPath
         ? path.resolve(repoRoot, options.dagPath)
-        : path.join(dagEvidenceDir, `round-${round}.dag.json`);
+        : getTaskPaths(repoRoot, taskId).dagDraftPath;
     const runner = options.runner ?? resolveDefaultRunner(repoRoot);
     let generated = {};
     if (!options.dagPath) {

package/docs/init-surface.manifest.json

@@ -55,6 +55,7 @@
     "skills/agent-worker/references/agent-worker-operator.md",
     "skills/loop-agent/SKILL.md",
     "skills/loop-agent/references/command-reference.md",
+    "skills/loop-agent/references/source-and-plan-practice.md",
     "skills/loop-agent/references/docs-converge.md",
     "skills/ai-engineering-context/SKILL.md",
     "skills/verification-before-completion/SKILL.md",
@@ -133,6 +134,7 @@
     ".agents/skills/agent-worker/references/agent-worker-operator.md",
     ".agents/skills/loop-agent/SKILL.md",
     ".agents/skills/loop-agent/references/command-reference.md",
+    ".agents/skills/loop-agent/references/source-and-plan-practice.md",
     ".agents/skills/loop-agent/references/docs-converge.md",
     ".agents/skills/ai-engineering-context/SKILL.md",
     ".agents/skills/verification-before-completion/SKILL.md",
@@ -212,6 +214,7 @@
     ".agents/skills/agent-worker/references/agent-worker-operator.md": "copied",
     ".agents/skills/loop-agent/SKILL.md": "copied",
     ".agents/skills/loop-agent/references/command-reference.md": "copied",
+    ".agents/skills/loop-agent/references/source-and-plan-practice.md": "copied",
     ".agents/skills/loop-agent/references/docs-converge.md": "copied",
     ".agents/skills/ai-engineering-context/SKILL.md": "copied",
     ".agents/skills/verification-before-completion/SKILL.md": "copied",

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

@@ -250,7 +250,7 @@
         ".harness/dag-runs/**",
         "artifacts/**"
       ],
-      "outputContract": "One scoped pytest execution over Markdown-mapped scripts producing a valid pytest-html report with per-case captured output, self-contained reports/backend-test.html, reports/backend-test.md, reports/backend-test-facts.md, and a deterministic self-contained reports/backend-test-l5-dashboard.html (machine-computed L-5 metrics, no JSON); exit 0/1 with valid evidence continues.",
+      "outputContract": "One scoped pytest execution over Markdown-mapped scripts producing a valid pytest-html report with per-case captured output, self-contained reports/backend-test.html, reports/backend-test.md, reports/backend-test-facts.md, a deterministic self-contained reports/backend-test-l5-dashboard.html (machine-computed L-5 metrics, no JSON), and an optional contracts/code-coverage-v1.json when jacocoCoverage is configured (JaCoCo TCP dump → jacoco.xml → parsed; failure-safe); exit 0/1 with valid evidence continues.",
       "subtask_prompt": "Resolve the final Markdown Automation Notes/自动化映射 to a unique, safe set of testcase/**/test_*.py targets and execute only those scripts exactly once. Prefer the deterministic module one-to-one path when a mapped script is missing but the module stem file exists. Generate a native pytest-html self-contained report, then render the primary self-contained Chinese HTML report from the same pytest-html plus final Markdown case metadata without rerun. Keep 测试结论, quality status, failure overview, and a polished per-case result card with concise scenario, automation test name, result, duration, and redacted bounded HTTP request parameters/response results for both passed and failed cases. Do not render a technical/execution evidence section in HTML; retain auditable paths and hashes in facts.",
       "shell": {
         "commands": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.25.0",
+  "version": "0.25.2",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/skills/loop-agent/SKILL.md

@@ -27,10 +27,12 @@ Entry: routing and hard rules. Required details come from frontmatter references
 
 ```bash
 loop-agent new-task <task-id> "Title"
-# Prefer immutable PRD: loop-agent import-prd <task-id> --file <path>
-loop-agent dag run-task <task-id> --profile auto --strict-models --output <dag.json>
-loop-agent dag validate --dag <dag.json> --strict-models --strict-governance
-loop-agent run-dag --dag <dag.json> --cwd <repo-root>
+# Prefer import-prd when a PRD exists; plan create for non-trivial work
+# (see references/source-and-plan-practice.md)
+loop-agent dag run-task <task-id> --profile auto --strict-models
+# default draft: .harness/tasks/<task-id>/dag.json
+loop-agent dag validate --dag .harness/tasks/<task-id>/dag.json --strict-models --strict-governance
+loop-agent run-dag --dag .harness/tasks/<task-id>/dag.json --cwd <repo-root>
 ```
 
 执行前审阅 `profileRouting`、`governanceProfile`、writer `writeSet`、`forbiddenPaths`、decision gate mode。
@@ -44,10 +46,6 @@ loop-agent run-dag --dag <dag.json> --cwd <repo-root>
 | Operator commands、`agent-worker` | `references/command-reference.md` |
 | 独立验证、failure handling、closeout | `references/verification-and-failure-handling.md` |
 
-## Source Layout
-
-CLI `src/cli/`；DAG `src/workflows/dag/`；loop `src/workflows/loop/`；executors `src/executors/`；worker `src/worker/`；governance `src/governance/`。不新增平行兼容入口。
-
 ## Hard Rules
 
 1. Use vertical tracer bullets across real integration layers；each needs independent acceptance and verification.