@tea-agent/loop-agent 0.24.4-beta.0 → 0.24.5

package/AGENTS.md

@@ -37,7 +37,7 @@
 4. 涉及测试纪律/验证声明/调试时继续读：`docs/governance/harness-methodology-*.md`。
 5. 查看最近提交、相关 plan/progress/report；`git status --short --branch`；跑最小基线验证。
 6. 后端/接口/pytest → `taskKind: "backend-test"`（不是 `--profile`）；知识回写 `knowledge-sync`；图谱开荒 `knowledge-graph-bootstrap`。`--profile` 仅 `auto|minimal|standard|reviewed|supervised`。
-7. 看板/observe → `agent-worker console serve --repo . --port 8790`（`/inspect/` 只读）；`observe serve` 仅为兼容入口。
+7. 看板/observe → `agent-worker console`（默认 repo=当前目录、port=8790；兼容入口 `agent-worker console serve --repo . --port 8790`）（`/inspect/` 只读）；`observe serve` 仅为兼容入口。
 8. 分支合并 → 先读 `docs/operations/branch-merge-guideline.md`。
 
 ## 会话协议
@@ -64,13 +64,21 @@
 
 ## 验证
 
-权威源：`docs/governance/verification-matrix.md`。常用：
+权威源：`docs/governance/verification-matrix.md`。
+
+默认节奏：编辑中只跑矩阵「最低验证」（typecheck + 定向 Vitest）；`git commit` 的 `pre-commit` 只做 `check-repo`；`git push` 的 `pre-push` 跑 `bash scripts/ci.sh`（全量 typecheck + `npm test`）。每个 clone 安装一次 hooks：`bash scripts/install-git-hooks.sh`。
+
+常用：
 
 ```bash
-npm run typecheck && npm test && npm run build
-node bin/loop-agent.js --help
-bash scripts/check-repo.sh
+# 编辑中
+npm run typecheck
+npx vitest run <相关测试路径>
+
+# push / 交付前（或依赖 pre-push）
 bash scripts/ci.sh
+npm run build
+node bin/loop-agent.js --help
 ```
 
 文档站变更：`npm run docs:build`。init / architecture / skill entry / pack 定向验证见 verification-matrix。

package/CHANGELOG.md

@@ -2,8 +2,60 @@
 
 ## [Unreleased]
 
+## [0.24.5] - 2026-07-28
+
+### 重点更新
+
+- 后端测试 Markdown 模块与 pytest 脚本实现一对一精准映射，提升测试执行的确定性
+- 修复后端测试 HTML 报告中请求参数显示为空的问题，正确展示请求与响应日志
+- 初始化项目支持将「帮我完成/实现/修复」等通用需求表达直接路由进 Agent DAG
+- 新增裸 agent-worker console 入口，简化本地看板启动流程
+
+### 新增
+
+- 初始化后的目标项目支持将「帮我完成/实现/修复/开发」等通用需求表达确定性地路由进 Agent DAG（new-task → dag run-task → dag validate → run-dag），无需追加额外的 cli 关键词
+- 新增裸 agent-worker console 入口，直接启动 Loop Operator Console，repo 默认当前目录、port 默认 8790
+- check-skill-entry.sh 及初始化投影脚本支持解析 YAML 折叠块，对通用需求触发词建立机器门禁以防漂移
+
+### 改进
+
+- 后端测试收敛模块映射，生成与评审 prompt 强制模块文件一对一映射，在映射缺失时支持确定性恢复
+- 后端测试 execute/report 节点文案与 pytest-html 真源对齐，移除残留的 JUnit 表述
+- 后端测试 HTML 报告对齐 R04 模板样式，采用全 inline style 设计（渐变 banner、可折叠用例卡片、状态胶囊及请求/响应分块展示）
+- 本地看板启动更简，端口被占用时不再自动更换，改为明确提示使用 --port 显式指定其它端口
+- 旧项目经 init check-update 与 apply-safe 即可安全补回新的「通用需求实现」路由行，并保留用户自定义前言
+
+### 修复
+
+- 修复后端测试 HTML 报告中请求参数显示为空的问题：渲染器现已兼容 payload= 键或 JSON request_record 格式的请求摘要
+- 修复后端测试报告无法正确获取请求/响应日志的问题：兼容 HTTP_REQUEST 与 HTTP REQUEST 两种日志前缀，并在解析前正确解码 HTML 实体
+- 修复 shell-executor 在 Windows 环境下因反斜杠路径导致 runDir 损坏的问题，确保路径注入稳定
+- 修复前端 lint baseline 在 Windows 下因路径解析逻辑缺陷，拒绝相对路径输出导致评估误报为不可用的问题
+- 修复多个测试固件在 Windows 下因嵌套 Shell 引号剥离导致命令执行输出为空或报错的问题（涉及 composite-shell 与 init-command）
+
+## [0.24.4] - 2026-07-28
+
+### 重点更新
+
+- 控制台「导入需求」支持多文件批量导入，自动合成可编辑正文后创建任务
+- 后端测试移除重复运行稳定性门槛，每次执行同时生成用户可读的 HTML 与 Markdown 报告
+- 本地 pre-push 钩子升级为执行完整 CI 流程，覆盖治理检查、类型检查与全量测试
+
+### 新增
+
+- 控制台「导入需求」支持选择或拖入一份或多份 Markdown/TXT 文档（严格 UTF-8，单文件 ≤8 MiB，最多 8 个），多文件分卷归档并合成可编辑正文后创建任务
+
 ### 改进
 
+- 后端测试 L-5 结论不再将重复运行稳定性作为门槛，每次执行同时产出用户可读的 HTML 与 Markdown 报告，内部 facts 文件保留用于审计
+- 本地 pre-push 钩子改为执行完整 CI 流程（治理检查 + 类型检查 + 全量测试），pre-commit 保持仅执行 check-repo
+- harness 中等复杂度（MED）模型调整为 grok-4.5，并同步对齐相关 smoke/init 断言
+- 归档已完成的设计文档与执行计划，刷新 0.24.x 六个月规划与能力摘要，并同步验证与 hooks 文档
+
+## [0.24.3] - 2026-07-28
+
+### 重点更新
+
 - 发布工作流改为发布已通过完整门禁并经 SHA-256 校验的 npm tarball，避免 `npm publish` 再次触发全量测试、类型检查与构建。
 - 默认 `standard` 实现任务在 React、Next.js 或 Vue 项目中直接选择 `frontend-implementation` DAG，不再依赖需求关键词；明确后端、文档/测试范围或前端否定仍保留对应通用流程。
 

package/README.md

@@ -52,6 +52,8 @@ loop-agent init reconcile --repo-root .
 
 ### 运行第一个任务
 
+初始化后，在已初始化的目标项目中你可以直接对宿主 agent 说「**loop-agent 帮我完成 XXX 需求**」（或「帮我实现 / 帮我修复 / 帮我开发 XXX」「使用 loop-agent 完成 XXX」「按 loop-agent 流程处理 XXX」），初始化写入的 `AGENTS.md` 与 `.agents/skills/loop-agent/` 会把这类通用需求表达确定性地路由进 Agent DAG，**无需**追加额外的 `cli` 关键词。主会话只负责编排与验证，业务实现由受治理 DAG writer 完成。
+
 ```bash
 loop-agent new-task example-task "实现一个有明确验收标准的小功能"
 ```
@@ -90,12 +92,13 @@ loop-agent dag report --run-id <run-id>
 | 入口 | 命令 | 角色 |
 | --- | --- | --- |
 | 受治理 CLI | `loop-agent …` / `agent-worker …` | 权威写入与诊断 |
-| Loop Operator Console | `agent-worker console serve --repo .` | Official 本地控制面（默认 `127.0.0.1:8790`，含 Operate 与 Inspect） |
+| Loop Operator Console | `agent-worker console` | Official 本地控制面（默认 repo=当前目录、`127.0.0.1:8790`，含 Operate 与 Inspect） |
 | Observe | `agent-worker observe serve --repo . --port 8787` | 兼容期独立只读入口；不再作为推荐路径 |
 
 ```bash
 # 终端 A：Console（任务/运行操作面；canonical mutation 只经 sibling loop-agent）
-agent-worker console serve --repo .
+agent-worker console                              # 默认 repo=当前目录、port=8790
+agent-worker console serve --repo .               # 兼容入口，等价于裸入口
 agent-worker console doctor --repo .
 
 ```

package/dist/commands/init.js

@@ -415,6 +415,18 @@ check_skill "loop-agent" \\
   "references/command-reference.md"
 check_skill "agent-worker" "references/agent-worker-operator.md"
 
+# loop-agent description is a YAML folded block (>-); grep ^description: only
+# captures the indicator line. Validate the general-demand trigger terms
+# against the whole skill file so host auto-discovery phrasing cannot drift.
+loop_agent_skill=".agents/skills/loop-agent/SKILL.md"
+loop_agent_text="$(tr '[:upper:]' '[:lower:]' < "\${loop_agent_skill}")"
+for term in "loop-agent 帮我完成" "帮我实现" "帮我修复" "帮我开发" "agent dag" "new-task" "dag run-task" "dag validate" "run-dag"; do
+  if [[ "\${loop_agent_text}" != *"\${term}"* ]]; then
+    echo "skill entry 检查失败（loop-agent）：description 缺少触发/路由词 \${term}" >&2
+    exit 1
+  fi
+done
+
 description_line="$(grep -E '^description:' .agents/skills/agent-worker/SKILL.md | head -n 1 | tr '[:upper:]' '[:lower:]')"
 for term in "agent-worker" "feature packet" "taskspec" "task pool" "self-host" "candidate" "loop-agent"; do
   if [[ "\${description_line}" != *"\${term}"* ]]; then
@@ -802,6 +814,7 @@ function buildManagedAgentsBlock(input) {
         "| 初始化更新校验 / 检查初始化更新 / 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` 或模型合并。",
         "",
@@ -861,10 +874,11 @@ function buildManagedAgentsBlock(input) {
         "### 运行看板（只读）",
         "",
         "```bash",
-        "agent-worker console serve --repo . --port 8790",
+        "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`；不要直接暴露到公开网络。`agent-worker observe serve` 仅为兼容入口。",
+        "浏览器打开 `http://127.0.0.1:8790/`；检视面为 `http://127.0.0.1:8790/inspect/`。默认绑定本机 `127.0.0.1`；不要直接暴露到公开网络。端口被占用时不会自动更换，请用 `--port <port>` 显式指定。`agent-worker observe serve` 仅为兼容入口。",
         "",
         "### DAG 诊断与收口",
         "",

package/dist/worker/cli.js

@@ -41,7 +41,8 @@ export function buildAgentWorkerProgram() {
         .description("Local product-line worker utilities for TaskSpec validation")
         .version(readPackageVersion(path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))))) ?? "0.0.0", "-V, --version", "display version")
         .showHelpAfterError()
-        .showSuggestionAfterError();
+        .showSuggestionAfterError()
+        .enablePositionalOptions();
     const task = program.command("task").description("TaskSpec utilities");
     const batch = program
         .command("batch")
@@ -593,18 +594,17 @@ export function buildAgentWorkerProgram() {
         process.stdout.write(`${JSON.stringify(snapshot)}\n`);
     });
     consoleCmd
-        .command("serve")
-        .requiredOption("--repo <repo-root>", "Target repo root")
+        .description("Loop Operator Console (local); bare `agent-worker console` starts it directly (repo defaults to current working directory, port defaults to 8790)")
+        .enablePositionalOptions()
+        .passThroughOptions()
+        .option("--repo <repo-root>", "Target repo root (default: current working directory)", process.cwd())
         .option("--port <port>", "HTTP port", "8790")
         .option("--host <host>", "Bind host (default 127.0.0.1; use 0.0.0.0 for LAN, no network auth)", "127.0.0.1")
         .option("--debug", "Log request source/method/path/status to stderr")
         .option("--app-data <path>", "Override Console application-data root (Draft/Operation/confirmation)")
-        .description("Start Loop Operator Console HTTP server (Operate + Inspect; static SPA + Operator API)")
         .action(async (options) => {
-        const { createConsoleServer } = await import("./console/server.js");
-        const repoRoot = path.resolve(options.repo);
-        const server = await createConsoleServer({
-            repoRoot,
+        await runConsoleServe({
+            repoRoot: path.resolve(options.repo),
             host: options.host,
             port: Number.parseInt(options.port, 10),
             debug: options.debug === true,
@@ -612,13 +612,25 @@ export function buildAgentWorkerProgram() {
                 ? path.resolve(options.appData)
                 : undefined,
         });
-        process.stdout.write(`${server.url}\n`);
-        await new Promise((resolve) => {
-            const shutdown = () => resolve();
-            process.once("SIGINT", shutdown);
-            process.once("SIGTERM", shutdown);
+    });
+    consoleCmd
+        .command("serve")
+        .option("--repo <repo-root>", "Target repo root (default: current working directory)", process.cwd())
+        .option("--port <port>", "HTTP port", "8790")
+        .option("--host <host>", "Bind host (default 127.0.0.1; use 0.0.0.0 for LAN, no network auth)", "127.0.0.1")
+        .option("--debug", "Log request source/method/path/status to stderr")
+        .option("--app-data <path>", "Override Console application-data root (Draft/Operation/confirmation)")
+        .description("Start Loop Operator Console HTTP server (compat entry; equivalent to bare `agent-worker console`)")
+        .action(async (options) => {
+        await runConsoleServe({
+            repoRoot: path.resolve(options.repo),
+            host: options.host,
+            port: Number.parseInt(options.port, 10),
+            debug: options.debug === true,
+            appDataRoot: options.appData
+                ? path.resolve(options.appData)
+                : undefined,
         });
-        await server.close();
     });
     consoleCmd
         .command("doctor")
@@ -693,6 +705,39 @@ export async function main(argv = process.argv) {
 async function readTaskYaml(taskSpecPath) {
     return YAML.parse(await readFile(taskSpecPath, "utf-8"));
 }
+/** Shared console serve entry used by both bare `console` and `console serve`. */
+async function runConsoleServe(options) {
+    const { createConsoleServer } = await import("./console/server.js");
+    try {
+        const server = await createConsoleServer({
+            repoRoot: options.repoRoot,
+            host: options.host,
+            port: options.port,
+            debug: options.debug === true,
+            appDataRoot: options.appDataRoot,
+        });
+        process.stdout.write(`${server.url}\n`);
+        await new Promise((resolve) => {
+            const shutdown = () => resolve();
+            process.once("SIGINT", shutdown);
+            process.once("SIGTERM", shutdown);
+        });
+        await server.close();
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        const code = error?.code;
+        const isPortInUse = code === "EADDRINUSE" ||
+            /listen EADDRINUSE/i.test(detail) ||
+            /address already in use/i.test(detail);
+        if (isPortInUse) {
+            process.stderr.write(`端口 ${options.port} 已被占用，请使用 --port <port> 指定其它端口后重试。\n`);
+            process.exit(1);
+        }
+        process.stderr.write(`${detail}\n`);
+        process.exit(1);
+    }
+}
 function handlePoolRecoveryCliError(error) {
     const detail = error instanceof Error ? error.message : String(error);
     process.stderr.write(`${detail}\n`);

package/dist/worker/console/operator-actions.js

@@ -1490,9 +1490,14 @@ async function allocateUniqueTaskId(repoRoot, preferredId) {
 }
 async function dispatchBootstrapFromPrd(ctx, p) {
     const content = str(p.content) ?? str(p.fileText);
-    if (!content) {
+    if (!content?.trim()) {
         return invalid("bootstrapFromPrd", "content is required");
     }
+    const parsedDocs = parseBootstrapDocuments(p.documents);
+    if (!parsedDocs.ok) {
+        return invalid("bootstrapFromPrd", parsedDocs.message);
+    }
+    const documents = parsedDocs.documents;
     const taskKind = normalizeConsoleWorkflowKind(str(p.taskKind), "standard");
     const identity = deriveTaskIdentityFromPrd(content);
     let taskId;
@@ -1539,28 +1544,86 @@ async function dispatchBootstrapFromPrd(ctx, p) {
             }),
         };
     }
-    const staged = await stageUtf8Text(ctx.appData, content, {
-        extension: ".md",
-    });
-    const imported = await run(["import-prd", taskId, "--file", staged.path, "--json"], {
-        cwd: ctx.repoRoot,
-        artifactName: "bootstrap-import-prd",
-        expectJson: true,
-        timeoutMs: 60_000,
-    });
-    if (!imported.ok || imported.exitCode !== 0) {
-        return {
-            kind: "error",
-            status: 400,
-            body: operatorFailed({
-                command: "bootstrapFromPrd",
-                outcome: "rejected",
-                code: "INTERNAL_ERROR",
-                message: imported.stderr?.trim() ||
-                    `import-prd failed with exit ${imported.exitCode}`,
-                details: { exitCode: imported.exitCode, taskId },
-            }),
-        };
+    const succeededImports = [];
+    const importResults = [];
+    const runImportPrd = async (label, text, name) => {
+        const staged = await stageUtf8Text(ctx.appData, text, {
+            extension: ".md",
+        });
+        const imported = await run([
+            "import-prd",
+            taskId,
+            "--file",
+            staged.path,
+            "--name",
+            name,
+            "--role",
+            "requirement",
+            "--json",
+        ], {
+            cwd: ctx.repoRoot,
+            artifactName: `bootstrap-import-prd-${label}`,
+            expectJson: true,
+            timeoutMs: 60_000,
+        });
+        if (!imported.ok || imported.exitCode !== 0) {
+            return {
+                kind: "error",
+                status: 400,
+                body: operatorFailed({
+                    command: "bootstrapFromPrd",
+                    outcome: "rejected",
+                    code: "INTERNAL_ERROR",
+                    message: imported.stderr?.trim() ||
+                        `import-prd failed for "${name}" with exit ${imported.exitCode}. 任务已创建但不完整，请用 CLI 补 import-prd 或换 taskId 重试。`,
+                    details: {
+                        exitCode: imported.exitCode,
+                        taskId,
+                        failedName: name,
+                        succeededImports: [...succeededImports],
+                    },
+                }),
+            };
+        }
+        succeededImports.push(name);
+        importResults.push(imported.json ?? null);
+        return null;
+    };
+    if (documents && documents.length > 0) {
+        for (const doc of documents) {
+            const failure = await runImportPrd(doc.name, doc.content, doc.name);
+            if (failure)
+                return failure;
+        }
+        const composedFailure = await runImportPrd("composed", content, "composed");
+        if (composedFailure)
+            return composedFailure;
+    }
+    else {
+        const staged = await stageUtf8Text(ctx.appData, content, {
+            extension: ".md",
+        });
+        const imported = await run(["import-prd", taskId, "--file", staged.path, "--json"], {
+            cwd: ctx.repoRoot,
+            artifactName: "bootstrap-import-prd",
+            expectJson: true,
+            timeoutMs: 60_000,
+        });
+        if (!imported.ok || imported.exitCode !== 0) {
+            return {
+                kind: "error",
+                status: 400,
+                body: operatorFailed({
+                    command: "bootstrapFromPrd",
+                    outcome: "rejected",
+                    code: "INTERNAL_ERROR",
+                    message: imported.stderr?.trim() ||
+                        `import-prd failed with exit ${imported.exitCode}`,
+                    details: { exitCode: imported.exitCode, taskId },
+                }),
+            };
+        }
+        importResults.push(imported.json ?? null);
     }
     const draftSaved = await ctx.drafts.save({
         ...emptyDraft(taskId, title, { taskKind }),
@@ -1578,10 +1641,58 @@ async function dispatchBootstrapFromPrd(ctx, p) {
             identitySource: identity.source,
             preferredTaskId: identity.taskId,
             draftSha256: draftSaved.draftSha256,
-            import: imported.json ?? null,
+            import: importResults.length === 1 ? importResults[0] : null,
+            imports: importResults,
+            documentNames: documents && documents.length > 0
+                ? [...documents.map((d) => d.name), "composed"]
+                : undefined,
         }),
     };
 }
+const MAX_BOOTSTRAP_DOCUMENTS = 8;
+function parseBootstrapDocuments(raw) {
+    if (raw === undefined || raw === null) {
+        return { ok: true, documents: null };
+    }
+    if (!Array.isArray(raw)) {
+        return { ok: false, message: "documents must be an array" };
+    }
+    if (raw.length === 0) {
+        return { ok: true, documents: null };
+    }
+    if (raw.length > MAX_BOOTSTRAP_DOCUMENTS) {
+        return {
+            ok: false,
+            message: `documents supports at most ${MAX_BOOTSTRAP_DOCUMENTS} entries`,
+        };
+    }
+    const documents = [];
+    for (let i = 0; i < raw.length; i += 1) {
+        const entry = raw[i];
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            return { ok: false, message: `documents[${i}] must be an object` };
+        }
+        const rec = entry;
+        const name = str(rec.name)?.trim();
+        const content = str(rec.content);
+        const fileName = str(rec.fileName)?.trim();
+        if (!name) {
+            return { ok: false, message: `documents[${i}].name is required` };
+        }
+        if (!content?.trim()) {
+            return {
+                ok: false,
+                message: `documents[${i}].content is required`,
+            };
+        }
+        documents.push({
+            name,
+            content,
+            ...(fileName ? { fileName } : {}),
+        });
+    }
+    return { ok: true, documents };
+}
 async function ensureDraft(ctx, taskId, title, options) {
     const existing = await ctx.drafts.get(taskId);
     if (existing) {