@tea-agent/loop-agent 0.39.0-beta.0 → 0.39.0-beta.10

package/scripts/next-publish-gate.mjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+/**
+ * next-publish-gate: throttle main -> npm `next` publishing.
+ *
+ * Every main push used to publish a new next build. With this gate a
+ * push-triggered run only publishes when HEAD is at least COMMIT_THRESHOLD
+ * commits ahead of the commit that produced the current dist-tags.next
+ * build (read from the published tarball's dist/build-stamp.json).
+ *
+ * Bypasses (publish regardless of the count):
+ *   - workflow_dispatch runs (manual trigger, e.g. right before cutting a
+ *     release line); the workflow passes --force for those.
+ *   - recovery: HEAD already IS the source of the current next build, so
+ *     re-publishing would be the same version anyway.
+ *   - unknown last-published SHA (no npm history / unreadable stamp /
+ *     SHA not an ancestor of HEAD): fail open — a missed next build is
+ *     cheap, permanently stuck publishing is not.
+ *
+ * Exit codes: 0 = publish, 2 = skip (gate), 1 = hard error. The workflow
+ * maps skip to a successful early exit so non-publishing runs are green.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+import { readTarballBuildStamp } from "./release-source-binding.mjs";
+
+export const COMMIT_THRESHOLD_DEFAULT = 5;
+const SKIP_EXIT_CODE = 2;
+
+/** Run a command and return trimmed stdout; injected for tests. */
+function normalizeWindowsTarArg(value) {
+	const match = /^([A-Za-z]):[\\/](.*)$/.exec(String(value));
+	if (!match) return value;
+	return `/${match[1].toLowerCase()}/${match[2].replaceAll("\\", "/")}`;
+}
+
+export function normalizeCommandArgs(cmd, args, platform = process.platform) {
+	if (platform !== "win32" || cmd !== "tar") return args;
+	return args.map(normalizeWindowsTarArg);
+}
+
+export function commandLaunch(cmd, args, platform = process.platform) {
+	if (platform === "win32" && cmd === "npm") {
+		return {
+			cmd: process.env.ComSpec || "cmd.exe",
+			args: ["/d", "/s", "/c", "npm", ...args],
+		};
+	}
+	return { cmd, args };
+}
+
+export function defaultRun(cmd, args) {
+	const launch = commandLaunch(cmd, normalizeCommandArgs(cmd, args));
+	return execFileSync(launch.cmd, launch.args, {
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "pipe"],
+	});
+}
+
+export function npmViewDistTags(run = defaultRun) {
+	const out = run("npm", [
+		"view",
+		"@tea-agent/loop-agent",
+		"dist-tags",
+		"--json",
+	]);
+	const trimmed = String(out ?? "").trim();
+	if (!trimmed) return {};
+	let parsed;
+	try {
+		parsed = JSON.parse(trimmed);
+	} catch {
+		return {};
+	}
+	return parsed && typeof parsed === "object" ? parsed : {};
+}
+
+/** Download the exact published next version and read its build stamp. */
+export function defaultStampProbe(version) {
+	const dir = mkdtempSync(join(tmpdir(), "loop-agent-next-gate-"));
+	try {
+		defaultRun("npm", [
+			"pack",
+			`@tea-agent/loop-agent@${version}`,
+			"--pack-destination",
+			dir,
+		]);
+		const file = readdirSync(dir).find((entry) => entry.endsWith(".tgz"));
+		if (!file) return null;
+		try {
+			return readTarballBuildStamp(join(dir, file), defaultRun);
+		} catch {
+			return null;
+		}
+	} catch {
+		return null;
+	} finally {
+		rmSync(dir, { recursive: true, force: true });
+	}
+}
+
+export function isAncestor(sha, head, run = defaultRun) {
+	try {
+		run("git", ["merge-base", "--is-ancestor", sha, head]);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Pure decision. Inputs:
+ *   - threshold: minimum commits ahead of lastPublishedSha to publish
+ *   - aheadBy: commits between lastPublishedSha and headSha (null = unknown)
+ *   - lastPublishedSha / headSha: for the recovery equality check
+ * Returns { publish, reason, aheadBy }.
+ */
+export function shouldPublishNext({
+	threshold = COMMIT_THRESHOLD_DEFAULT,
+	lastPublishedSha,
+	headSha,
+	aheadBy,
+	force = false,
+}) {
+	if (force) {
+		return { publish: true, reason: "force-bypass", aheadBy };
+	}
+	if (!headSha) {
+		return { publish: true, reason: "head-unknown-fail-open", aheadBy };
+	}
+	if (!lastPublishedSha) {
+		return {
+			publish: true,
+			reason: "last-published-sha-unknown-fail-open",
+			aheadBy,
+		};
+	}
+	const last = String(lastPublishedSha).toLowerCase();
+	const head = String(headSha).toLowerCase();
+	if (last === head) {
+		return { publish: true, reason: "same-commit-recovery", aheadBy: 0 };
+	}
+	if (aheadBy === null || aheadBy === undefined || !Number.isFinite(aheadBy)) {
+		return { publish: true, reason: "ahead-unknown-fail-open", aheadBy: null };
+	}
+	const normalizedThreshold = Number(threshold);
+	if (!Number.isFinite(normalizedThreshold) || normalizedThreshold <= 0) {
+		return { publish: true, reason: "threshold-invalid-fail-open", aheadBy };
+	}
+	if (aheadBy >= normalizedThreshold) {
+		return { publish: true, reason: "ahead-threshold-met", aheadBy };
+	}
+	return { publish: false, reason: "below-threshold-skip", aheadBy };
+}
+
+function parseArgs(argv) {
+	return Object.fromEntries(
+		argv
+			.filter((arg) => arg.startsWith("--"))
+			.map((arg) => {
+				const [key, ...value] = arg.replace(/^--/, "").split("=");
+				return [key, value.join("=") || "true"];
+			}),
+	);
+}
+
+function main() {
+	const args = parseArgs(process.argv.slice(2));
+	const threshold = Number(args.threshold || COMMIT_THRESHOLD_DEFAULT);
+	const distTags = npmViewDistTags();
+	const currentNext = distTags.next ? String(distTags.next) : null;
+	let lastPublishedSha = null;
+	let currentNextNote = "no dist-tags.next";
+	if (currentNext) {
+		const stamp = defaultStampProbe(currentNext);
+		if (stamp && stamp.gitSha) {
+			lastPublishedSha = stamp.gitSha;
+			currentNextNote = `next=${currentNext} from ${stamp.gitSha.slice(0, 10)}`;
+		} else {
+			currentNextNote = `next=${currentNext} (stamp unreadable)`;
+		}
+	}
+	let headSha = null;
+	let aheadBy = null;
+	try {
+		headSha = defaultRun("git", ["rev-parse", "HEAD"]).trim();
+	} catch {
+		headSha = null;
+	}
+	if (headSha && lastPublishedSha) {
+		if (!isAncestor(lastPublishedSha, headSha)) {
+			aheadBy = null;
+		} else {
+			aheadBy = Number(
+				defaultRun("git", [
+					"rev-list",
+					"--count",
+					`${lastPublishedSha}..${headSha}`,
+				]).trim(),
+			);
+		}
+	}
+	const decision = shouldPublishNext({
+		threshold,
+		lastPublishedSha,
+		headSha,
+		aheadBy,
+		force: args.force === "true",
+	});
+	process.stdout.write(
+		`next-publish-gate: ${currentNextNote}\n` +
+			`next-publish-gate: head=${headSha ? headSha.slice(0, 10) : "unknown"} ` +
+			`aheadBy=${aheadBy === null ? "unknown" : aheadBy} ` +
+			`threshold=${threshold}\n` +
+			`next-publish-gate: ${decision.publish ? "PUBLISH" : "SKIP"} ` +
+			`(${decision.reason})\n`,
+	);
+	process.exit(decision.publish ? 0 : SKIP_EXIT_CODE);
+}
+
+// CLI 入口安全判断（argv[1] 非合法 file: URL 时 new URL 会抛异常）
+function scriptEntryHref(argv1) {
+	try {
+		return argv1 ? new URL(`file://${argv1}`).href : "";
+	} catch {
+		return "";
+	}
+}
+
+const invokedAsScript =
+	Boolean(process.argv[1]) &&
+	import.meta.url === scriptEntryHref(process.argv[1]);
+
+if (invokedAsScript) {
+	main();
+}

package/scripts/release-source-binding.mjs

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+/**
+ * release-source-binding: resolve the exact source SHA behind a selected next
+ * build, and validate cut-release-line preconditions.
+ *
+ * The next tarball carries dist/build-stamp.json { version, gitSha }. A release
+ * line must be cut from THAT commit — never from a floating main HEAD at
+ * workflow runtime. This module provides:
+ *
+ * - resolveSourceBinding: given a next version, return its gitSha (from the
+ *   registry tarball build stamp) and validated facts.
+ * - validateCutPreconditions: line monotonicity, branch absence, no parallel
+ *   un-promoted train, source sha on main.
+ */
+import { execFileSync } from "node:child_process";
+import process from "node:process";
+
+export const NEXT_TARGET_ENV = "LOOP_AGENT_NEXT_TARGET";
+
+const FORMAL_LINE_RE = /^\d+\.\d+$/;
+
+/**
+ * Read build stamp fields from a packed tarball without installing it.
+ * @param {string} tarballPath
+ * @param {(cmd: string, args: string[]) => string} [run]
+ */
+export function readTarballBuildStamp(tarballPath, run = runCommand) {
+	const listing = run("tar", ["-tzf", tarballPath]);
+	const stampEntry = listing
+		.split("\n")
+		.map((line) => line.trim())
+		.find((line) => /\/dist\/build-stamp\.json$/.test(line));
+	if (!stampEntry) {
+		throw new Error(`tarball ${tarballPath} does not contain dist/build-stamp.json`);
+	}
+	const stampJson = run("tar", ["-xzf", tarballPath, "-O", stampEntry]);
+	let parsed;
+	try {
+		parsed = JSON.parse(stampJson);
+	} catch (error) {
+		throw new Error(
+			`build stamp is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+	if (typeof parsed.gitSha !== "string" || !/^[0-9a-f]{7,40}$/i.test(parsed.gitSha)) {
+		throw new Error("build stamp gitSha missing or malformed");
+	}
+	return { gitSha: parsed.gitSha, version: parsed.version ?? null };
+}
+
+function runCommand(cmd, args) {
+	return execFileSync(cmd, args, {
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "pipe"],
+	});
+}
+
+/**
+ * Download an exact next version tarball (without install scripts) into a
+ * directory and return its path.
+ */
+export function downloadNpmTarball(version, destDir, run = runCommand) {
+	run("npm", [
+		"pack",
+		`@tea-agent/loop-agent@${version}`,
+		"--pack-destination",
+		destDir,
+	]);
+	const listing = run("ls", [destDir]);
+	const file = listing
+		.split("\n")
+		.map((line) => line.trim())
+		.find((line) => line.endsWith(".tgz"));
+	if (!file) throw new Error(`npm pack did not produce a tarball in ${destDir}`);
+	return `${destDir}/${file}`;
+}
+
+/**
+ * Pure checks for cutting a release line.
+ *
+ * @param {object} input
+ * @param {string} input.selectedNextVersion e.g. "0.37.0-next.42"
+ * @param {string} input.releaseLine e.g. "0.37"
+ * @param {string} input.sourceSha commit the next tarball was built from
+ * @param {string[]} input.remoteBranches remote release branch names (e.g. ["release/0.36"])
+ * @param {string|null} [input.latestFormalVersion] current npm latest (for reference in results)
+ * @param {(sha: string) => boolean} [input.shaOnMain] whether sha is an ancestor of origin/main
+ * @returns {{ok: true} | {ok: false, reason: string, detail?: string}}
+ */
+export function validateCutPreconditions(input) {
+	const nextMatch = /^(\d+)\.(\d+)\.(0|[1-9]\d*)-next\.([0-9]\d*)$/.exec(
+		String(input.selectedNextVersion ?? ""),
+	);
+	if (!nextMatch) {
+		return {
+			ok: false,
+			reason: "invalid-selected-next",
+			detail: `selectedNextVersion=${input.selectedNextVersion}`,
+		};
+	}
+	const nextLine = `${nextMatch[1]}.${nextMatch[2]}`;
+	const patch = nextMatch[3];
+	if (patch !== "0") {
+		return {
+			ok: false,
+			reason: "selected-next-not-minor-zero",
+			detail: `next target patch must be 0, got ${patch}`,
+		};
+	}
+	if (!FORMAL_LINE_RE.test(String(input.releaseLine ?? ""))) {
+		return {
+			ok: false,
+			reason: "invalid-release-line",
+			detail: `releaseLine=${input.releaseLine}`,
+		};
+	}
+	if (input.releaseLine !== nextLine) {
+		return {
+			ok: false,
+			reason: "line-mismatch",
+			detail: `selected next ${nextLine} vs release line ${input.releaseLine}`,
+		};
+	}
+	if (!/^[0-9a-f]{7,40}$/i.test(String(input.sourceSha ?? ""))) {
+		return {
+			ok: false,
+			reason: "invalid-source-sha",
+			detail: `sourceSha=${input.sourceSha}`,
+		};
+	}
+	const branches = Array.isArray(input.remoteBranches)
+		? input.remoteBranches
+		: [];
+	const existing = branches.find((b) => b === `release/${input.releaseLine}`);
+	if (existing) {
+		return {
+			ok: false,
+			reason: "release-branch-exists",
+			detail: existing,
+		};
+	}
+	const existingLines = branches
+		.map((b) => /^release\/(\d+)\.(\d+)$/.exec(b))
+		.filter(Boolean)
+		.map((m) => ({ major: Number(m[1]), minor: Number(m[2]), name: m[0] }));
+	const [cutMajor, cutMinor] = input.releaseLine.split(".").map(Number);
+	const higher = existingLines.find(
+		(l) => l.major > cutMajor || (l.major === cutMajor && l.minor > cutMinor),
+	);
+	if (higher) {
+		return {
+			ok: false,
+			reason: "line-not-monotonic",
+			detail: `higher release branch exists: ${higher.name}`,
+		};
+	}
+	if (input.shaOnMain !== undefined && input.shaOnMain(input.sourceSha) === false) {
+		return {
+			ok: false,
+			reason: "source-sha-not-on-main",
+			detail: input.sourceSha,
+		};
+	}
+	return { ok: true };
+}
+
+/**
+ * Resolve the next target line from env override (LOOP_AGENT_NEXT_TARGET).
+ * Returns null when unset/invalid — callers decide the fallback derivation.
+ */
+export function nextTargetFromEnv(env = process.env) {
+	const raw = env[NEXT_TARGET_ENV];
+	if (!raw) return null;
+	return /^\d+\.\d+\.0$/.test(raw) ? raw : null;
+}
+
+// CLI 入口安全判断（argv[1] 非合法 file: URL 时 new URL 会抛异常）
+function scriptEntryHref(argv1) {
+	try {
+		return argv1 ? new URL(`file://${argv1}`).href : "";
+	} catch {
+		return "";
+	}
+}
+
+const invokedAsScript =
+	Boolean(process.argv[1]) && import.meta.url === scriptEntryHref(process.argv[1]);
+
+if (invokedAsScript) {
+	const args = Object.fromEntries(
+		process.argv
+			.filter((arg) => arg.startsWith("--"))
+			.map((arg) => {
+				const [key, ...value] = arg.replace(/^--/, "").split("=");
+				return [key, value.join("=") || "true"];
+			}),
+	);
+	if (args["self-test"]) {
+		const scenario = String(args["self-test"]);
+		const scenarios = {
+			"cut-ok": () =>
+				validateCutPreconditions({
+					selectedNextVersion: "0.37.0-next.42",
+					releaseLine: "0.37",
+					sourceSha: "abc1234567890abcdef",
+					remoteBranches: ["release/0.36"],
+				}),
+			"cut-exists": () =>
+				validateCutPreconditions({
+					selectedNextVersion: "0.37.0-next.42",
+					releaseLine: "0.37",
+					sourceSha: "abc1234567890abcdef",
+					remoteBranches: ["release/0.36", "release/0.37"],
+				}),
+			"cut-not-monotonic": () =>
+				validateCutPreconditions({
+					selectedNextVersion: "0.37.0-next.42",
+					releaseLine: "0.37",
+					sourceSha: "abc1234567890abcdef",
+					remoteBranches: ["release/0.38"],
+				}),
+			"cut-line-mismatch": () =>
+				validateCutPreconditions({
+					selectedNextVersion: "0.37.0-next.42",
+					releaseLine: "0.38",
+					sourceSha: "abc1234567890abcdef",
+					remoteBranches: [],
+				}),
+			"cut-sha-not-on-main": () =>
+				validateCutPreconditions({
+					selectedNextVersion: "0.37.0-next.42",
+					releaseLine: "0.37",
+					sourceSha: "abc1234567890abcdef",
+					remoteBranches: [],
+					shaOnMain: () => false,
+				}),
+		};
+		const run = scenarios[scenario];
+		if (!run) {
+			process.stderr.write(`unknown self-test scenario: ${scenario}\n`);
+			process.exitCode = 2;
+		} else {
+			process.stdout.write(`${JSON.stringify(run())}\n`);
+		}
+	} else {
+		process.stderr.write(
+			"usage: node scripts/release-source-binding.mjs --self-test=<scenario>\n",
+		);
+		process.exitCode = 2;
+	}
+}

package/skills/codebase-scout/SKILL.md

@@ -10,7 +10,7 @@ description: 用于只读 scout 节点，在实现前定位现有代码、测试
 ## 规则
 
 - 从 repo 指令、task source 与邻近测试入手。
-- 可用时优先 CodeGraph；否则用 `rg` 与聚焦文件阅读。
+- 可用时优先 CodeGraph；否则 Shell 搜索优先 `rg`，按名找文件优先 `fd`，再聚焦阅读文件。
 - 在提议新抽象前，识别现有 helper 与 ownership 边界。
 - 只返回事实，不做编辑。
 

package/skills/fe-test-ui-scout/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: fe-test-ui-scout
+description: 在写 frontend-test Wave PRD/回归目录之前，对真实运行的被测页面做只读锚点侦察，产出并维护 {testRoot}/rag/ui-anchors.md 锚点台账（默认 testcase/frontend/rag/ui-anchors.md）。用 playwright-cli snapshot/find 逐字面验证命中数与唯一性，防止 PRD 验收标准引用不存在或不唯一的文案。触发词：frontend-test、锚点、台账、ui-anchors、侦察、写 PRD 前、snapshot/find 校准、Wave PRD。
+references:
+  - path: references/ledger-schema.md
+    required: true
+  - path: references/recon-protocol.md
+    required: true
+---
+
+# FE-Test UI Scout（锚点侦察）
+
+## 定位
+
+写 Wave PRD / 校准回归目录 AC **之前**的前置侦察。产出锚点台账
+`{testRoot}/rag/ui-anchors.md`（默认 `testcase/frontend/rag/ui-anchors.md`）：每个「页面 × 状态」下真实可见、
+`find` 可命中的字面清单。PRD 的每条 `find "..."` 断言必须能在台账找到对应行；
+台账没有的字面禁止写进验收标准。
+
+本 skill **不生成用例、不执行用例、不点任何写控件**。生成由
+`playwright-cli-case-generator`（DAG generate 节点）负责，执行由
+`playwright-cli`（DAG execute 节点）负责；本 skill 只在 DAG 之外的主会话使用。
+
+## 输入
+
+- 被测 baseUrl（来自 `{testRoot}/rag/context.md` 的 `environmentProbe=reachable` URL；默认 `testcase/frontend/rag/context.md`）
+- 目标 Wave 的 AC 清单（回归目录中本 Wave 范围的行）
+- 既有台账（增量更新，不整表重写）
+
+## 流程
+
+1. **读取范围**：从回归目录取本 Wave AC 的「页面 + 测试点 + 验收标准」，
+   提取所有候选字面（引号内文案、aria-label、控件名）。
+2. **逐状态侦察**：对每个涉及页面/状态组合：
+   `playwright-cli open --browser=chrome <baseUrl>/#/<route>` → `snapshot` →
+   逐候选 `find "<字面>"`，记录命中数与命中位置。
+3. **记录陷阱**：拆节点（`<kbd>`+`<span>`、文本+`<code>`）、同名多控件、
+   aria-label 与可见文本不一致、状态前置（no-session / has-session / empty、
+   setup-required）都要写进备注列。
+4. **增量写台账**：按 [references/ledger-schema.md](references/ledger-schema.md)
+   的表结构与分节规则追加/修订行，保留既有行历史（用备注标注失效原因，
+   不删行）。
+5. **报告**：侦察完成后输出小结（新增/修订/失效行数、命中率、给 PRD 的
+   可用锚点清单与禁用清单）。
+
+## 硬规则
+
+- 只读：不点提交/保存/发送类控件、不创建会话以外的任何状态（「新建空白
+  对话」CTA 允许点击一次以进入 has-session 状态，属于台账明确的状态夹具）。
+- 命中 0 或命中数 >1 且无法用状态/作用域区分的字面，标记 `不可断言`，
+  禁止进入 PRD `find` 断言。
+- 台账每行必须带验证时间与当时 baseUrl；页面改版后旧行标 `失效` 而非删除。
+- 不猜测：没跑过 `find` 的字面不进台账。
+- PRD 正文（含背景/夹具段）不得出现会被需求 id 扫描捕获的形态：大写或小写的 REQ/BR/AC 前缀 + 连字符 + hash/序号（如夹具任务 id 里的 req 段、或自示范用的「req 加连字符 hash」字面）。夹具引用只写日期 + 短 hash（如 f03535aa），规则说明文字用中文描述或代码块包裹仍可能被扫——一律避免连写。
+- PRD 验收标准只用**目录 AC id**（如 AC-FE-INS-005）作条目 id；不要写本地序号前缀（如 AC-003 加粗目录 id 的双 id 形态）——双 id 会被同时提取，生成器只引用其一，另一个落入 acceptanceCoverage.missing。
+
+## 输出
+
+- `{testRoot}/rag/ui-anchors.md`（增量更新；默认 `testcase/frontend/rag/ui-anchors.md`）
+- 侦察小结（对话内输出，不落盘；结论回写 PRD 草稿的锚点引用）
+
+## References
+
+- [references/ledger-schema.md](references/ledger-schema.md) — 台账表结构与分节规则
+- [references/recon-protocol.md](references/recon-protocol.md) — 逐状态侦察操作协议与陷阱清单

package/skills/fe-test-ui-scout/references/ledger-schema.md

@@ -0,0 +1,62 @@
+# 台账（ui-anchors.md）表结构与分节规则
+
+## 文件位置与命名
+
+- 路径：`{testRoot}/rag/ui-anchors.md`（默认 `testcase/frontend/rag/ui-anchors.md`）
+- 编码：UTF-8，LF；表格用 GitHub Flavored Markdown。
+- 台账是**增量账本**：修订不删除历史行；失效行改状态列并注明原因。
+
+## 顶层结构
+
+```markdown
+# UI 锚点台账（frontend-test）
+
+- baseUrl：<验证时的绝对 URL>
+- 更新时间：<YYYY-MM-DD HH:mm（本地时区）>
+- 维护：fe-test-ui-scout skill
+
+## <页面路由> · <状态>
+
+| 字面（find 原文） | 命中 | 唯一 | 控件/位置 | 状态 | 备注 | 验证时间 |
+| --- | --- | --- | --- | --- | --- | --- |
+| 后端研发（默认 DAG） | 1 | 是 | workflow-kind-select option | 有效 | 括号必须带全 | 2026-08-22 15:00 |
+```
+
+## 分节规则
+
+- 一节 = 一个「页面路由 × 状态」组合。路由用 hash 形式（`#/tasks`、
+  `#/chat`、`/inspect/#/dags`）；状态至少区分：
+  - `no-session`（无会话 landing）
+  - `has-session`（已存在会话，composer 可见）
+  - `empty-session`（新建空会话，无消息）
+  - 页面特有态（如 `#/night · 无计划`、`#/recovery · 无候选`、
+    setup-required）随需追加，节名写清楚。
+- 同一页面多个状态各自成节；不要把跨状态结果合并进一行。
+
+## 列语义
+
+| 列 | 说明 |
+| --- | --- |
+| 字面（find 原文） | `playwright-cli find "<字面>"` 的唯一入参原文，逐字节照抄（含括号、空格、中点） |
+| 命中 | 侦察时 `find` 实际返回的匹配数（0/1/N） |
+| 唯一 | 是/否/不适用；命中=1 且作用于目标控件才算「是」 |
+| 控件/位置 | 命中元素的角色与位置（如 `h2`、`oc-suggestion strong`、`aria-label`） |
+| 状态 | `有效` / `失效` / `待复核`；失效须在备注注明原因与替代字面 |
+| 备注 | 陷阱与前置：拆节点（kbd+span、text+code）、同名多控件、aria-label≠可见文本、状态前置、setup 门 |
+| 验证时间 | YYYY-MM-DD HH:mm |
+
+## 有效 / 失效判定
+
+- **有效**：命中=1、目标控件、字面在当前 build 下可复现。
+- **不可断言**：命中 0（字面不存在或被拆节点）、命中 >1 且状态/作用域
+  无法区分（如「发送」同时命中 tips 与按钮）。这类行保留在台账里，
+  状态列写 `不可断言`，备注写原因——它们正是 PRD 的「禁用清单」。
+- **失效**：页面改版后不再命中。不删行，改状态 + 备注（替代字面是什么）。
+
+## 与 PRD / 目录的关系
+
+- PRD 每条 `find "..."` 断言的字面必须出自台账某行且该行状态为
+  `有效`（或备注给出拆节点断言替代方案，如 `find "taskKind="` 与
+  `find "frontend-test"` 二选一）。
+- 目录 AC 的 live 校准注记引用台账行（日期 + 路由+状态），保持
+  「AC ↔ 台账」双向可追溯。

package/skills/fe-test-ui-scout/references/recon-protocol.md

@@ -0,0 +1,54 @@
+# 逐状态侦察操作协议与陷阱清单
+
+## 前置检查
+
+1. 确认 SUT 健康：`curl -s -o /dev/null -w '%{http_code}' <baseUrl>/api/health`
+   返回 200；非 200 先解决环境，不侦察。
+2. 确认 SUT 跑的是当前 build（改过 `src/**` 后必须 `npm run build` 并重启
+   SUT，否则台账记录的是旧页面）。
+3. 准备隔离 app-data（SUT 启动参数已带 `/tmp` 隔离目录时无需额外动作）；
+   侦察结束把 no-session 状态还原（关闭页面即可；若点了「新建空白对话」
+   产生空会话，记录在案即可，不必清理 app-data）。
+
+## 每个页面 × 状态的标准动作序列
+
+```text
+playwright-cli open --browser=chrome <baseUrl>/#/<route>
+playwright-cli snapshot
+playwright-cli find "<候选字面 1>"
+playwright-cli find "<候选字面 2>"
+...
+playwright-cli close
+```
+
+- `snapshot` 先行：从 snapshot 里核对候选字面的真实渲染形态（是否拆节点、
+  是否 aria-label、是否在折叠组内需先展开）。
+- 每个候选字面必须真实 `find` 一次；snapshot 里「看起来有」不算数。
+- 折叠组（如「工程边界（可选，人类确认）」）：先记录折叠态的组标题字面，
+  再展开后侦察组内字段；两种形态分两行记。
+- 需要状态夹具的节（has-session）：点一次「新建空白对话」CTA 进入；
+  这是协议允许的唯一写动作。
+
+## 陷阱清单（出现即写进备注列）
+
+| 陷阱 | 症状 | 台账记法 |
+| --- | --- | --- |
+| 拆节点 | `find "Enter 发送"` 0 命中；DOM 是 `<kbd>Enter</kbd><span>发送</span>` | 字面行记完整原文 + 命中 0 + 状态 `不可断言`；备注给出替代（`find "发送"` 或 `find "Enter"`）并说明拆法 |
+| text+code 拆分 | `taskKind=frontend-test` 渲染为 `taskKind=` + `<code>frontend-test</code>` | 同上 |
+| 同名多控件 | 「发送」同时命中 tips span 与发送按钮 aria-label | 命中 N>1，唯一=否；备注指明各自位置，PRD 需换更独特字面或限定状态 |
+| 同名多行按钮（列表态） | 「重命名会话」在 3 行会话各自命中 1，全局命中 3；单会话态侦察时命中 1 | 备注标「会话数依赖」；断言法降级为 hover 目标行 → snapshot 解析该行真实 ref（存在即通过），禁止声明 find 命中数=1；或确保夹具为单行态（清 app-data） |
+| aria-label ≠ 可见文本 | 控件可访问名是 aria-label，渲染文本不同 | 字面列记 aria-label 值，备注「aria-label；可见文本为 X」 |
+| 无名 flex 子项 | flex 匿名文本无 name-from-content，find 不到 | 记录控件缺 aria-label → 这是**产品可修问题**，报告给修复决策树（页面象限），台账暂记 `不可断言` |
+| 括号/全半角 | 「后端研发（默认 DAG）」少括号 0 命中 | 字面逐字节照抄；备注提醒 |
+| 状态前置 | 控件只在 has-session / setup-required 等状态下存在 | 分节记录；PRD 引用时必须声明状态夹具 |
+| 折叠组 | 字面在 `<details>` 内，未展开时 find 0 | 两种形态分行记录（折叠标题/展开后字段） |
+| 瞬态文案 | 「正在加载…」类短暂存在 | 备注标「瞬态」，PRD 不引用 |
+
+## 输出纪律
+
+- find 命中数以工具返回为准，不目测。
+- 每节侦察完立即写台账（不攒到最后凭记忆写）。
+- 侦察小结按 SKILL.md 第 5 步输出：新增/修订/失效行数、命中率、
+  PRD 可用锚点清单与禁用清单。
+- 发现疑似产品缺陷（白屏、文案缺失、aria 错误）：记入小结的「移交修复」
+  段，不在台账内修，不因缺陷跳过其余候选字面的侦察。