Initial import of streamline
This commit is contained in:
@@ -0,0 +1,261 @@
|
||||
/**
|
||||
* `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));
|
||||
Reference in New Issue
Block a user