@tea-agent/loop-agent 0.25.5 → 0.25.6

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [0.25.6] - 2026-08-01
+
+### 重点更新
+
+- 后端测试新增按变更类型界定覆盖深度的机制，精准控制测试范围并避免无关用例膨胀
+- 初始化托管块改为从独立模板文件渲染，大幅降低维护难度并提升可读性
+
+### 新增
+
+- backend-test 新增机器可读的 Coverage Scope，支持按新增接口、契约变化、行为变化、缺陷修复和纯实现优化选择覆盖深度
+- 目标项目的 AGENTS.md 托管块改为从 docs/templates/init-managed-agents.md 渲染，便于直接编辑维护
+
+### 改进
+
+- 纯优化类变更现聚焦于需求、确定性影响面与最小回归集，避免无关接口全量用例膨胀
+- 该初始化模板仅随 npm 包发布，不投影到目标项目治理目录，同时同步了多项推荐路径与精确命令
+
 ## [0.25.5] - 2026-07-31
 
 ### 重点更新
@@ -20,6 +37,9 @@
 
 ### 改进
 
+- backend-test 用例生成/独立 Review 改为产品需求优先，再穷举文档化 API 规则：覆盖 active/deleted duplicate-name 生命周期、每个合法枚举值、非法枚举等价类、长度/数值边界、字符格式、null/missing/type 错误和业务状态迁移；每个 Case 绑定唯一 primary pytest symbol
+- backend-test 将 Coverage Test Point 与 pytest 执行单元解耦：Test Point 明确分为 `variant`、`assertion`、`cross-cutting`，只有真实输入/状态/结果变体生成参数 item，同一业务旅程检查点通过 symbol docstring 追溯，HTTP 日志等横切证据不再制造重复业务 item；报告区分 Markdown Case、primary symbol、pytest item 并展示执行放大率
+- backend-test HTML/facts 新增可展开的“用例场景覆盖分析”和“Markdown → pytest 一一对应”质量详情，并由最终报告分别消费节点 4/6 详细 findings 与节点 7 machine totals
 - 减少全量测试中的重复 CLI 冷启动和 self-host canary 二次打包安装场景，收敛低价值重复用例并保留关键端到端主路径
 - DAG 执行期间的主会话行为约束得到增补：启动后自主推进至结束、持续可靠判活、严格限制工作区文件修改，并优先使用纯函数探针排查路由
 

package/dist/commands/init.js

@@ -4,7 +4,6 @@ import os from "node:os";
 import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { fileURLToPath } from "node:url";
-import { copyDir } from "../shared/copy-dir.js";
 import { isInitRuntimeActive, } from "../shared/runtime-activity.js";
 import { loadHarnessManifest } from "../governance/harness.js";
 import { OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH, applyPiRetryMerge, buildOpenCodeTransientRetryPluginSource, inspectPiRetryConfig, parseClientRecoveryMode, runClientRecovery, } from "./client-recovery.js";
@@ -119,6 +118,12 @@ const COMPAT_PROMPTS = {
     ].join("\n"),
 };
 const GOVERNANCE_ROOT_TOKEN = "__LOOP_AGENT_GOVERNANCE_ROOT__";
+const PROJECT_NAME_TOKEN = "__LOOP_AGENT_PROJECT_NAME__";
+/** Package-shipped render source for AGENTS.md managed block; not projected to target repos. */
+const MANAGED_AGENTS_TEMPLATE_PATH = "docs/templates/init-managed-agents.md";
+/** Files under package assets that init must not copy into target projects. */
+const PACKAGE_ONLY_SURFACE_FILES = new Set([MANAGED_AGENTS_TEMPLATE_PATH]);
+let managedAgentsTemplateCache;
 const INIT_CHECK_ENGINEERING_STRUCTURE_SH = `#!/usr/bin/env bash
 set -euo pipefail
 
@@ -798,130 +803,28 @@ function mergeRecord(base, patch) {
         ...patch,
     };
 }
-function buildManagedAgentsBlock(input) {
-    return [
-        MANAGED_BLOCK_START,
-        "## loop-agent 治理",
-        "",
-        `本仓库已初始化为 \`${input.projectName}\` 的 loop-agent harness 项目。`,
-        "",
-        "### 默认立场",
-        "",
-        "- 仓库是记录系统：决策、契约、计划、验证、报告和交接应进入可追踪文件。",
-        "- 一次只推进一个有边界、可验证的工作块；实现前先搜索现有代码、文档、脚本和测试。",
-        "- Shell 验证是完成依据；模型建议不能替代命令证据。",
-        "- 保留无关的用户改动，不要回退自己没有做的修改。",
-        "- 委托模型写入前，必须把写入边界写成结构化 `task.json.allowedPaths` / `task.json.forbiddenPaths`，再审查生成 DAG 的 writer `writeSet`；不要只依赖 `source/执行约束.md` 的自然语言约束。",
-        "- 本仓库对 openCode 等主会话的定位是 **Compatibility / Operator Assist**：主会话编排 CLI 与只读诊断，**不是**默认实现 agent。",
-        "",
-        "### 主会话硬约束（Compatibility / Operator Assist）",
-        "",
-        "主会话（含 openCode、Cursor Chat、其他宿主 agent）= **operator-only**；skills 与本文件是纪律文档，**不能**替代 `task.json` / DAG `writeSet` / runtime 执法。",
-        "",
-        "| 类别 | 规则 |",
-        "|---|---|",
-        "| **允许** | 已发布 `loop-agent` / `agent-worker` CLI；只读 status/doctor/report/inspect/observe；准备 `source/*` 与 `task.json` 边界；human gate；shell 验证与 handoff。 |",
-        "| **禁止** | 绕过 CLI 用宿主 Edit/Write/ApplyPatch 直接改业务实现；CLI/DAG 失败后「救火改文件」；用聊天自述代替 shell 验证。 |",
-        "| **失败时** | `dag doctor` / `dag report` / `dag reconcile-run`（及适用 worker reconcile）；修正任务源/`task.json`/DAG 后经 CLI 重跑。 |",
-        "| **实现写入** | 业务代码 **只** 经受治理 DAG writer（`implement-pi` / `repair-pi`）经 `dag run-task` / `run-dag`。 |",
-        "",
-        "**永远不要**：`loop-agent` / `agent-worker` 失败 ⇒ 主会话直接改仓库实现。",
-        "",
-        "### 自然语言入口路由",
-        "",
-        "| 用户表达 | 入口 | 执行动作 |",
-        "|---|---|---|",
-        "| loop-agent 初始化 / loop agent 初始化 / loop agent初始化 / 初始化 loop-agent | 初始化 | 完成确定性初始化闭环 |",
-        "| 初始化更新校验 / 检查初始化更新 / loop-agent 初始化更新校验 / loop agent初始化更新校验 | 更新校验 | 只读报告，不写入 |",
-        "| 初始化对齐 / 升级后对齐 / reconcile 初始化 / loop-agent 初始化对齐 | 升级对齐 | 自动应用确定性安全动作；活跃 DAG/Worker 或人工决策时零写入 |",
-        "| 初始化安全更新 / 应用初始化更新 / loop-agent 初始化安全更新 / loop agent初始化安全更新 | 安全更新 | 先 check-update，再只执行确定性安全动作 |",
-        "| loop-agent 帮我完成 / 帮我实现 / 帮我修复 / 帮我开发 <需求>；使用 loop-agent 完成 <X>；按 loop-agent 流程处理 <X> | 通用需求实现 | 先建任务源与 `task.json.allowedPaths` / `forbiddenPaths`，再 `new-task` → `dag run-task` → `dag validate` → `run-dag`；主会话不得直接修改业务实现 |",
-        "",
-        "**更新校验（只读）**：只读执行下面命令；**不得自动**执行 `apply-safe` 或模型合并。",
-        "",
-        "```bash",
-        "loop-agent init check-update --repo-root . --markdown",
-        "```",
-        "",
-        "**升级对齐**：`loop-agent init reconcile --repo-root .`；存在活跃 DAG/Worker、human decisions 时必须零写入。",
-        "",
-        "**安全更新**：先 check-update，再 `apply-safe`；surface 缺失才 `--bootstrap-surface`。完成后复查 `init doctor` / `inspect` / `docs audit` 与目标治理检查。",
-        "",
-        "```bash",
-        "loop-agent init check-update --repo-root . --markdown",
-        "loop-agent init update --repo-root . --apply-safe",
-        "```",
-        "",
-        "### 初始化闭环",
-        "",
-        `当用户要求初始化 loop-agent（“初始化 loop-agent”“loop agent 初始化”“loop agent初始化”“loop-agent 初始化”），或发现 \`README.md\` / \`${input.governanceRoot}/verification-matrix.md\` 仍停留在通用初始化状态时，模型应在同一轮工作中完成初始化闭环，不要把补全文档和验证矩阵留给用户交互。`,
-        "",
-        "1. 运行 `loop-agent init instructions --repo-root .`。",
-        "2. 运行 `loop-agent init --repo-root . --profile full --merge`。",
-        `3. 基于真实项目文件补全根 \`README.md\`、\`${input.governanceRoot}/verification-matrix.md\`，必要时适配 \`scripts/ci-tests.sh\`。`,
-        "4. 复查 `init doctor` / `inspect` / `docs audit` 与 quick verification。",
-        "",
-        "信息不足时写明尚未识别到的事实；不要留下泛化占位符。",
-        "",
-        "### 文档收敛",
-        "",
-        "完成实现和验证后，必须检查 `README.md`、`AGENTS.md`、`CHANGELOG.md`（如果目标项目维护）、治理文档、skills references、初始化模板和脚本说明是否仍与实际行为一致。只更新与本次变更相关的内容；如果决定不更新，应在交接里写明理由。",
-        "",
-        "### 开始顺序",
-        "",
-        `pwd → \`README.md\` → \`harness.json\` → \`${input.governanceRoot}/README.md\` → 实现类再读 principles/feature-workflow/verification-matrix；测试纪律读 harness-methodology-*；\`git status\`；最小基线验证。`,
-        "",
-        "### Agent DAG 路径",
-        "",
-        "```bash",
-        'loop-agent new-task <task-id> "任务标题"',
-        "# write .harness/tasks/<task-id>/source/需求.md",
-        "# write .harness/tasks/<task-id>/source/执行约束.md",
-        "loop-agent dag run-task <task-id> --profile auto --strict-models",
-        "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 .",
-        "```",
-        "",
-        "`source/需求.md` 与 `source/执行约束.md` 必需；写入前同步 `task.json.allowedPaths` / `task.json.forbiddenPaths` 并审查 writer `writeSet`。",
-        "",
-        "凡是影响项目公共契约、执行入口、交付流水线、自动化/治理、数据模型、安全或权限模型、跨模块行为、用户可见工作流的改动，都必须在编辑实现文件前先创建任务、写好两个 source 文件、生成 DAG，并审查 DAG/writeSet。",
-        "",
-        "### 任务类型路由（taskKind）",
-        "",
-        '- 用户明确提出后端测试、接口/API 测试、pytest，或语境明确为后端的自动化测试时，必须把 `.harness/tasks/<task-id>/task.json` 的 `taskKind` 设置为 `"backend-test"`，不得保留默认 `standard`。',
-        "- `backend-test` 是 `taskKind`，不是 `--profile` 的可选值；运行 `dag run-task` 时继续使用 `--profile auto`。",
-        "- 仅出现“自动化测试”且无法判断前后端时，先阅读任务源与目标项目技术栈再决定，禁止无条件路由到 `backend-test`。",
-        '- 用户提示词明确是前端实现需求（例如前端页面、UI、组件或交互开发）时，必须把 `.harness/tasks/<task-id>/task.json` 的 `taskKind` 设置为 `"frontend-implementation"`，不得保留默认 `standard`。',
-        "- `frontend-implementation` 是 `taskKind`，不是 `--profile` 的可选值；运行 `dag run-task` 时继续使用 `--profile auto`，也可按需显式选择 `minimal` / `standard` / `reviewed` / `supervised`，不要把业务模板名当作 profile。",
-        '- 前端自动化测试（浏览器/UI 自动化、Playwright、E2E）继续使用 `taskKind: "frontend-test"`，不得设置为 `frontend-implementation`。',
-        "",
-        "### 运行看板（只读）",
-        "",
-        "```bash",
-        "agent-worker console                       # 默认 repo=当前目录，port=8790",
-        "agent-worker console serve --repo . --port 8790   # 兼容入口，等价于上面裸入口",
-        "```",
-        "",
-        "浏览器打开 `http://127.0.0.1:8790/`；检视面为 `http://127.0.0.1:8790/inspect/`。默认绑定本机 `127.0.0.1`；不要直接暴露到公开网络。端口被占用时不会自动更换，请用 `--port <port>` 显式指定。`agent-worker observe serve` 仅为兼容入口。",
-        "",
-        "### DAG 诊断与收口",
-        "",
-        "用 `loop-agent dag report --run-id <run-id> --markdown` 读 facts；失败/paused 用 `loop-agent dag doctor --run-id <run-id> --markdown`；生命周期对齐用 `loop-agent dag reconcile-run`。失败 run 用 `dag closeout-draft` 生成 failure handoff，不要写成成功 closeout。",
-        "",
-        "恢复：doctor/report → classify → reconcile/replan → CLI 重跑 → shell verify。**禁止**把主会话直接 Edit 业务代码当作恢复手段。",
-        "",
-        "### 运行态与验证",
-        "",
-        "- `.harness/tasks/`、`.harness/dag-runs/`、`.harness/runs/` 保存运行事实；已完成事实只读。",
-        "- `.agents/skills/` 为本地 skills；缺失时可回退 npm 包内置。",
-        `- 验证命令选择：\`${input.governanceRoot}/verification-matrix.md\`。常用：\`bash scripts/check-repo.sh\`、\`bash scripts/ci.sh\`、\`loop-agent inspect\`、\`loop-agent doctor\`、\`loop-agent docs audit\`。`,
-        "- `scripts/ci-tests.sh` 必须反映目标项目真实工具链。Windows 脚本用 Git Bash；仓库引用用 `/`。",
-        "",
-        "### 交接",
-        "",
-        `交接写清变更、原因、验证证据、影响面、风险与下一步；长期结论进入 \`${input.governanceRoot}/progress\`、reports、exec-plans、decisions。`,
-        MANAGED_BLOCK_END,
-    ].join("\n");
+async function loadManagedAgentsTemplate(assetRoot) {
+    if (managedAgentsTemplateCache !== undefined)
+        return managedAgentsTemplateCache;
+    const templatePath = path.join(assetRoot, MANAGED_AGENTS_TEMPLATE_PATH);
+    const raw = await readFile(templatePath, "utf-8");
+    // Prefer a START marker on its own line so header notes mentioning the token are ignored.
+    const lines = raw.split(/\r?\n/);
+    const startLine = lines.findIndex((line) => line.trim() === MANAGED_BLOCK_START);
+    const endLine = startLine >= 0
+        ? lines.findIndex((line, index) => index > startLine && line.trim() === MANAGED_BLOCK_END)
+        : -1;
+    if (startLine < 0 || endLine < 0) {
+        throw new Error(`managed agents template missing LOOP_AGENT_INIT markers: ${MANAGED_AGENTS_TEMPLATE_PATH}`);
+    }
+    managedAgentsTemplateCache = lines.slice(startLine, endLine + 1).join("\n");
+    return managedAgentsTemplateCache;
+}
+async function buildManagedAgentsBlock(input) {
+    const template = await loadManagedAgentsTemplate(input.assetRoot);
+    return template
+        .replaceAll(PROJECT_NAME_TOKEN, input.projectName)
+        .replaceAll(GOVERNANCE_ROOT_TOKEN, input.governanceRoot);
 }
 function mergeManagedBlock(existing, block) {
     const start = existing.indexOf(MANAGED_BLOCK_START);
@@ -1137,11 +1040,39 @@ async function copyFileIfMissing(input) {
 async function copyDirMerge(input) {
     const source = path.join(input.assetRoot, input.sourceRelativePath);
     const target = path.join(input.repoRoot, input.targetRelativePath);
-    await copyDir(source, target);
+    const sourcePrefix = `${input.sourceRelativePath.replaceAll(path.sep, "/").replace(/\/$/, "")}/`;
+    await copyDirSkippingPackageOnly({
+        source,
+        target,
+        packageRelativePrefix: sourcePrefix,
+    });
     input.written.push(input.targetRelativePath.endsWith("/")
         ? input.targetRelativePath
         : `${input.targetRelativePath}/`);
 }
+/** Like copyDir, but skips package-only assets that must not land in target projects. */
+async function copyDirSkippingPackageOnly(input) {
+    await mkdir(input.target, { recursive: true });
+    const entries = await readdir(input.source, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(input.source, entry.name);
+        const destPath = path.join(input.target, entry.name);
+        const packageRelative = `${input.packageRelativePrefix}${entry.name}`;
+        if (entry.isDirectory()) {
+            await copyDirSkippingPackageOnly({
+                source: srcPath,
+                target: destPath,
+                packageRelativePrefix: `${packageRelative}/`,
+            });
+            continue;
+        }
+        if (PACKAGE_ONLY_SURFACE_FILES.has(packageRelative))
+            continue;
+        if (entry.isFile() || entry.isSymbolicLink()) {
+            await copyFile(srcPath, destPath);
+        }
+    }
+}
 async function ensureHarnessDirs(repoRoot, written) {
     const dirs = [
         ".harness/prompts",
@@ -1289,7 +1220,10 @@ async function discoverCopiedSurfaceFiles(assetRoot) {
             continue;
         const files = await listRelativeFiles(rootPath);
         for (const relativePath of files) {
-            discovered.push(`${prefix}${relativePath}`);
+            const manifestPath = `${prefix}${relativePath}`;
+            if (PACKAGE_ONLY_SURFACE_FILES.has(manifestPath))
+                continue;
+            discovered.push(manifestPath);
         }
     }
     return discovered.sort();
@@ -1335,7 +1269,8 @@ async function buildDesiredSurfaceContent(input) {
     }
     if (manifestPath === "AGENTS.md") {
         return {
-            content: buildManagedAgentsBlock({
+            content: await buildManagedAgentsBlock({
+                assetRoot: input.assetRoot,
                 projectName: input.projectName,
                 governanceRoot: input.governanceRoot,
             }),
@@ -2427,7 +2362,11 @@ export async function initializeLoopAgentProject(options) {
     await writeText({
         repoRoot,
         relativePath: "AGENTS.md",
-        content: mergeManagedBlock(existingAgents, buildManagedAgentsBlock({ projectName, governanceRoot })),
+        content: mergeManagedBlock(existingAgents, await buildManagedAgentsBlock({
+            assetRoot,
+            projectName,
+            governanceRoot,
+        })),
         merge: true,
         written,
         skipped,

package/dist/executors/shell-executor.js

@@ -539,7 +539,7 @@ async function executeBackendTestPipeline(input, meta) {
             });
             const manifestPath = path.join(meta.runDir, "contracts", "backend-test-case-manifest.json");
             const summary = manifest.coverageSummary;
-            outputs.push(`manifest=${manifestPath}`, `materializationStatus=${manifest.materializationStatus ?? "available"}`, `coverageSummary.explicitAcCount=${summary?.explicitAcCount ?? "unavailable"}`, `coverageSummary.coveredAcCount=${summary?.coveredAcCount ?? "unavailable"}`, `coverageSummary.caseCount=${summary?.caseCount ?? "unavailable"}`, `coverageSummary.generatedCount=${summary?.generatedCount ?? "unavailable"}`, `ruleCoverageSummary.ruleCount=${manifest.ruleCoverageSummary?.ruleCount ?? "unavailable"}`, `correspondenceSummary.exactCorrespondenceCount=${manifest.correspondenceSummary?.exactCorrespondenceCount ?? "unavailable"}`);
+            outputs.push(`manifest=${manifestPath}`, `materializationStatus=${manifest.materializationStatus ?? "available"}`, `coverageSummary.explicitAcCount=${summary?.explicitAcCount ?? "unavailable"}`, `coverageSummary.coveredAcCount=${summary?.coveredAcCount ?? "unavailable"}`, `coverageSummary.caseCount=${summary?.caseCount ?? "unavailable"}`, `coverageSummary.generatedCount=${summary?.generatedCount ?? "unavailable"}`, `ruleCoverageSummary.ruleCount=${manifest.ruleCoverageSummary?.ruleCount ?? "unavailable"}`, `correspondenceSummary.exactCorrespondenceCount=${manifest.correspondenceSummary?.exactCorrespondenceCount ?? "unavailable"}`, `correspondenceSummary.primarySymbolCount=${manifest.correspondenceSummary?.primarySymbolCount ?? "unavailable"}`, `correspondenceSummary.testPoints=${manifest.correspondenceSummary?.mappedTestPointCount ?? "unavailable"}/${manifest.correspondenceSummary?.testPointCount ?? "unavailable"}`, `correspondenceSummary.variantTestPointCount=${manifest.correspondenceSummary?.variantTestPointCount ?? "unavailable"}`, `correspondenceSummary.assertionTestPointCount=${manifest.correspondenceSummary?.assertionTestPointCount ?? "unavailable"}`, `correspondenceSummary.crossCuttingTestPointCount=${manifest.correspondenceSummary?.crossCuttingTestPointCount ?? "unavailable"}`, `correspondenceSummary.unclassifiedTestPointCount=${manifest.correspondenceSummary?.unclassifiedTestPointCount ?? "unavailable"}`, `correspondenceSummary.duplicateBindingTestPointCount=${manifest.correspondenceSummary?.duplicateBindingTestPointCount ?? "unavailable"}`);
         }
         else if (pipeline === "markdown-execute-html") {
             const mappedScripts = await collectBackendTestMappedPytestScripts(input.cwd);