Files
streamline/bin/conditions.ts
T
2026-11-16 17:26:44 -08:00

262 lines
11 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* `conditions` — the instrumented wrapper the executor agents call to record what
* they established on the device. Replaces the old `spec-delta` wrapper; see the
* header of shared/src/conditions.ts for why the record was inverted from
* "deviations" to "conditions".
*
* Each invocation appends exactly one line to `<workspace>/Conditions.jsonl`.
* The agent never edits that file by hand, and never edits TestSpec.md — this
* tool is the only write path, which is what makes the record trustworthy enough
* to feed back into future spec drafting.
*
* Two verbs:
* record — one condition (repeat as many times as needed)
* done — close out the round; prints a summary and complains if the round
* recorded nothing, which is nearly always a miss rather than a run
* with genuinely zero preconditions.
*
* Callable directly (`bun bin/conditions.ts record …`) or as the satellite
* bundle's `conditions` subcommand (see satellite/src/entry.ts), so a deployed
* node runs the same version of this code as the runner that reads it back.
*/
import { existsSync, mkdirSync, appendFileSync, readFileSync } from "node:fs";
import path from "node:path";
import {
CONDITIONS_FILE,
CONDITIONS_SCHEMA_VERSION,
CONDITION_KINDS,
CONDITION_KIND_LABEL,
SPEC_AGREEMENT_LABEL,
conditionStats,
matchKind,
newConditionId,
normalizeKbLabels,
parseConditions,
type ConditionEntry,
type ConditionKind,
type ConditionVerdict,
type SpecAgreement,
} from "../shared/src/conditions";
function parseArgs(argv: string[]): Record<string, string> {
const out: Record<string, string> = {};
for (let i = 0; i < argv.length; i++) {
const a = argv[i];
if (!a.startsWith("--")) continue;
const key = a.slice(2);
const next = argv[i + 1];
if (next == null || next.startsWith("--")) {
out[key] = "true";
} else {
out[key] = next;
i++;
}
}
return out;
}
function die(code: number, msg: string): never {
process.stderr.write(msg.endsWith("\n") ? msg : msg + "\n");
process.exit(code);
}
/** A flag the parser filled with the placeholder "true" carries no real value. */
function val(args: Record<string, string>, key: string): string | null {
const v = args[key];
if (v == null || v === "true") return null;
const t = v.trim();
return t ? t : null;
}
/**
* Resolve the workspace directory. Tolerates being handed the `evidence/`
* subdirectory — the agent has been trained by `record-evidence` to pass that
* path, and bouncing it here would just cost a round trip for no reason.
*/
function workspaceDir(args: Record<string, string>): string {
const raw = val(args, "dir") || process.env.CONDITIONS_DIR || process.env.SPEC_DELTA_DIR || "";
if (!raw) die(2, "缺少 --dir <工作区目录>(或设置 $CONDITIONS_DIR)");
let dir = path.resolve(raw);
if (path.basename(dir) === "evidence") dir = path.dirname(dir);
if (!existsSync(dir)) die(2, `工作区目录不存在:${dir}`);
return dir;
}
function resolveRound(args: Record<string, string>): number {
const raw = val(args, "round") || process.env.CONDITIONS_ROUND || process.env.SPEC_DELTA_ROUND || "";
const n = Number(raw);
if (!Number.isFinite(n) || n < 1) {
die(2, "缺少或非法的 --round <轮次>(或设置 $CONDITIONS_ROUND),应为 >= 1 的整数");
}
return Math.floor(n);
}
const filePath = (dir: string) => path.join(dir, CONDITIONS_FILE);
function append(dir: string, entry: ConditionEntry): void {
mkdirSync(dir, { recursive: true });
appendFileSync(filePath(dir), JSON.stringify(entry) + "\n", "utf8");
}
function readExisting(dir: string): ConditionEntry[] {
const f = filePath(dir);
if (!existsSync(f)) return [];
try { return parseConditions(readFileSync(f, "utf8")); } catch { return []; }
}
const KIND_HELP = CONDITION_KINDS.map((k) => ` ${k.padEnd(12)} ${CONDITION_KIND_LABEL[k]}`).join("\n");
const USAGE =
"用法:\n" +
` conditions record --kind <${CONDITION_KINDS.join("|")}> --scope "<业务模块>" --subject "<这条讲哪件事>" --statement "<条件是什么>" \\\n` +
` [--spec <predicted|contradicted|absent>] [--spec-said "<spec 原本怎么写的>"] \\\n` +
" [--payload '<JSON>'] [--evidence <evidence 下的文件名>] [--assumed]\n" +
" conditions done # 本轮记录完毕,打印汇总\n\n" +
"kind 可用值:\n" + KIND_HELP + "\n";
// ── commands ────────────────────────────────────────────────────────────────
function cmdRecord(args: Record<string, string>): never {
const dir = workspaceDir(args);
const round = resolveRound(args);
const statement = val(args, "statement");
if (!statement) die(2, `缺少 --statement "<条件是什么>"(写成将来别人能直接照做的形式)`);
const scope = val(args, "scope");
if (!scope) die(2, `缺少 --scope "<业务模块>"(如 "Story 相机";要稳定、可复用,别写成本任务专有的描述)`);
const subject = val(args, "subject");
if (!subject) {
die(2, `缺少 --subject "<这条讲哪件事>"(如 "特效面板入口路径";同一件事在不同任务里必须写成同一个 subject)`);
}
const rawKind = val(args, "kind");
const kind: ConditionKind | null = matchKind(rawKind);
if (!kind) {
die(2, `缺少或无法识别的 --kind「${rawKind ?? ""}」。可用值:\n${KIND_HELP}`);
}
// How the drafted spec fared. Defaults to `absent` — the honest default when the
// agent doesn't say, since "the spec never mentioned this" is both the most
// common case and the one that understates rather than overstates spec quality.
const rawSpec = val(args, "spec");
let spec: SpecAgreement = "absent";
if (rawSpec) {
if (rawSpec === "predicted" || rawSpec === "contradicted" || rawSpec === "absent") {
spec = rawSpec;
} else {
process.stderr.write(`⚠️ 无法识别的 --spec「${rawSpec}」,按 absent 记录。可用值:predicted / contradicted / absent\n`);
}
}
const specSaid = val(args, "spec-said") || val(args, "specSaid");
if (spec === "contradicted" && !specSaid) {
process.stderr.write("⚠️ --spec contradicted 建议同时给 --spec-said \"<spec 原本怎么写的>\",否则事后无法复盘 spec 错在哪。\n");
}
let payload: Record<string, unknown> | undefined;
const rawPayload = val(args, "payload");
if (rawPayload) {
try {
const p = JSON.parse(rawPayload) as unknown;
if (p && typeof p === "object" && !Array.isArray(p)) payload = p as Record<string, unknown>;
else process.stderr.write("⚠️ --payload 需要是一个 JSON 对象,已忽略。\n");
} catch {
process.stderr.write("⚠️ --payload 不是合法 JSON,已忽略。\n");
}
}
const evidence = val(args, "evidence");
if (evidence) {
const f = path.join(dir, "evidence", evidence.replace(/^evidence\//, ""));
if (!existsSync(f)) {
process.stderr.write(`⚠️ 证据文件不存在:${f}(本条仍会记录,但报告里会是死链)\n`);
}
}
// Default `verified`: this tool is called from a real-device session, so the
// common case is something actually exercised. `--assumed` is the explicit
// downgrade for "I read this off the code but didn't run it".
const verdict: ConditionVerdict = args.assumed ? "assumed" : "verified";
// Which injected knowledge this condition speaks about. A label the prompt
// never showed is dropped with a warning rather than stored: the attribution
// loop resolves labels by POSITION in that run's injected list, so a made-up
// K9 would not fail — it would silently settle whichever claim happens to sit
// at index 8, which is worse than recording no link at all.
const kb = normalizeKbLabels([val(args, "kb") ?? ""]);
const rawKb = val(args, "kb");
if (rawKb && !kb.length) {
process.stderr.write(`⚠️ 无法识别的 --kb「${rawKb}」,已忽略。应为 prompt 里出现过的编号,如 --kb K1 或 --kb K1,K3\n`);
}
const entry: ConditionEntry = {
v: CONDITIONS_SCHEMA_VERSION,
ts: Date.now(),
id: newConditionId(),
round,
source: "agent",
kind,
scope,
subject,
statement,
...(payload ? { payload } : {}),
verdict,
spec,
...(specSaid ? { specSaid } : {}),
...(evidence ? { evidence } : {}),
...(kb.length ? { kb } : {}),
};
append(dir, entry);
process.stdout.write(
`✅ 已记录条件(round ${round}):[${CONDITION_KIND_LABEL[kind]}] ${scope} › ${subject}\n` +
` ${statement}\n` +
` ${verdict === "verified" ? "真机已验证" : "仅推断未验证"} · ${SPEC_AGREEMENT_LABEL[spec]}` +
(kb.length ? ` · 关联知识 ${kb.join(",")}` : "") + "\n",
);
process.exit(0);
}
function cmdDone(args: Record<string, string>): never {
const dir = workspaceDir(args);
const round = resolveRound(args);
const all = readExisting(dir);
const mine = all.filter((e) => e.round === round);
if (!mine.length) {
// Not an error exit: failing here would tempt the agent into skipping the
// tool entirely. But say plainly that this is almost certainly a miss.
process.stdout.write(
`⚠️ round ${round} 没有记录任何执行条件。\n` +
" 几乎每次执行都至少有账号、构建方式、入口路径这类前置条件 —— 一条都没有,\n" +
" 通常意味着漏记了,而不是真的没有。请回看本轮实际做了什么,补记后再执行 done。\n",
);
process.exit(0);
}
const st = conditionStats(mine);
const kinds = st.byKind.map((k) => `${CONDITION_KIND_LABEL[k.kind]}×${k.count}`).join(" · ");
const specs = st.bySpec.map((s) => `${SPEC_AGREEMENT_LABEL[s.spec]}×${s.count}`).join(" · ");
process.stdout.write(
`✅ round ${round} 共记录 ${mine.length} 条执行条件(真机验证 ${st.verified} · 推断 ${st.assumed})\n` +
` 分类:${kinds}\n` +
` spec 命中:${specs}\n`,
);
process.exit(0);
}
/**
* CLI entry, callable two ways — directly (`bun bin/conditions.ts record …`) or as
* the satellite bundle's `conditions` subcommand via satellite/src/entry.ts.
*/
export async function runConditions(argv: string[]): Promise<never> {
const sub = argv[0];
const args = parseArgs(argv.slice(1));
switch (sub) {
case "record": case "add": return cmdRecord(args);
case "done": case "confirm": return cmdDone(args);
case "-h": case "--help": case undefined: return die(sub ? 0 : 2, USAGE);
default: return die(2, `未知子命令「${sub}」\n\n${USAGE}`);
}
}
if (import.meta.main) await runConditions(process.argv.slice(2));