@birdie_moblie/open_spec 2.1.7

package/dist/core/worker-evidence.d.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { type WorkerPacket } from './types.js';
+/** 本 task 已做过几次独立验收（每次 `worker review` 一条记录）；控制会话据此判断返修上限，不凭记忆。 */
+export declare function reviewRounds(root: string, change: string, packet: WorkerPacket): number;
+export declare function repairRounds(root: string, change: string, packet: WorkerPacket): number;
+export declare function prepareWorkerEvidence(root: string, change: string, packet: WorkerPacket): void;
+/** Runs once, stores full output on disk, and reuses only successful unchanged receipts. */
+export declare function runWorkerCheck(root: string, change: string, id: string, command?: string, force?: boolean, inputFile?: string): {
+    cached: boolean;
+    id: string;
+    runId: string;
+    command: string;
+    code: number;
+    ok: boolean;
+    fingerprint: string;
+    log: string;
+    logDigest: string;
+    at: string;
+    outputSummary?: string | undefined;
+    workerId?: string | undefined;
+    plugin?: {
+        path: string;
+        sha256: string;
+        binding: {
+            use: string;
+            kind: "hook" | "adapter";
+            operation: "preview" | "hook" | "read";
+            identity: {
+                name: string;
+                marketplace: string;
+                resolvedSha: string;
+                digest: string;
+            };
+            input?: Record<string, unknown> | undefined;
+            inputFiles?: string[] | undefined;
+            inputDescription?: string | undefined;
+        };
+        workerId?: string | undefined;
+        stepId?: string | undefined;
+    } | undefined;
+    context?: {
+        path: string;
+        digest: string;
+    } | undefined;
+};
+/** Reviewer updates are merged by id: omitting an old issue cannot resolve it. An empty array records a clean pass. */
+export declare function recordWorkerReview(root: string, change: string, updates: unknown, repaired?: boolean): {
+    path: string;
+    open: string[];
+    blocking: string[];
+    advisory: string[];
+    rounds: number;
+    repairRounds: number;
+};
+export declare function validateWorkerEvidence(root: string, change: string, packet: WorkerPacket): void;
+/** Final disclosure comes from review records, not optional prose in a worker result. */
+export declare const VisualAdvisorySchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodEnum<{
+        open: "open";
+        resolved: "resolved";
+    }>;
+    description: z.ZodString;
+    advisory: z.ZodOptional<z.ZodLiteral<true>>;
+    evidence: z.ZodOptional<z.ZodString>;
+    evidenceDigest: z.ZodOptional<z.ZodString>;
+    fingerprint: z.ZodOptional<z.ZodString>;
+    stepId: z.ZodString;
+}, z.core.$strict>;
+export declare function visualAdvisories(root: string, change: string): Array<z.infer<typeof VisualAdvisorySchema>>;
+//# sourceMappingURL=worker-evidence.d.ts.map

package/dist/core/worker-evidence.js

@@ -0,0 +1,253 @@
+import path from 'node:path';
+import { savePluginEvidence, PluginEvidenceSchema, runPluginCommand, pluginEvidenceCurrent } from '../hooks/plugin-runtime.js';
+import { operationContext } from './source-operations.js';
+import { randomUUID } from 'node:crypto';
+import { readdirSync, statSync } from 'node:fs';
+import { z } from 'zod';
+import { exists, readJson, writeJson } from '../shared/fs.js';
+import { sha256File } from '../shared/hash.js';
+import { checkoutFingerprint as fingerprint } from '../shared/git.js';
+import { resolveInside } from '../shared/paths.js';
+import { splitCommand } from '../shared/exec.js';
+import { runLoggedCommand } from '../shared/command-log.js';
+import { AppError } from '../shared/errors.js';
+import { artifactRel, requireChange } from './change.js';
+import { appendEvent } from './state.js';
+import { WorkerPacketSchema } from './types.js';
+import { CommandContextEvidenceSchema, commandContextCurrent, prepareCommandContext } from '../hooks/command-context.js';
+const Id = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/);
+const Run = z.object({
+    id: Id, runId: z.string(), command: z.string(), code: z.number().int(), ok: z.boolean(),
+    fingerprint: z.string(), log: z.string(), logDigest: z.string(), at: z.string(),
+    outputSummary: z.string().optional(),
+    workerId: z.string().optional(),
+    plugin: PluginEvidenceSchema.optional(),
+    context: CommandContextEvidenceSchema.optional(),
+}).strict();
+const Issue = z.object({
+    id: Id, status: z.enum(['open', 'resolved']), description: z.string().min(1),
+    advisory: z.literal(true).optional(),
+    evidence: z.string().optional(), evidenceDigest: z.string().optional(), fingerprint: z.string().optional(),
+}).strict();
+const Ledger = z.object({
+    runs: z.record(z.string(), Run), issues: z.record(z.string(), Issue),
+}).strict();
+// updates 允许为空：一次独立验收没有发现问题也要留下记录，轮次统计以记录数为准。
+const ReviewRecord = z.object({ at: z.string(), updates: z.array(Issue), codeFingerprint: z.string().optional(), repair: z.boolean().optional() }).strict();
+const REVIEW_FILE = /^review-[0-9a-f-]{36}\.json$/;
+function location(root, change, packet) {
+    const state = requireChange(root, change);
+    const directory = artifactRel(change, `.opsx/execution/r${state.sourceRevision}/${packet.stepId}`);
+    const relative = `${directory}/index.json`;
+    return { directory, relative, absolute: resolveInside(root, relative) };
+}
+function load(root, change, packet) {
+    const paths = location(root, change, packet);
+    const ledger = exists(paths.absolute) ? Ledger.parse(readJson(paths.absolute)) : { runs: {}, issues: {} };
+    // Each command/review writes its own atomic record. The shared index is only a view:
+    // concurrent commands must not erase a failure or a review update by replacing it.
+    const directory = resolveInside(root, paths.directory);
+    const names = exists(directory) ? readdirSync(directory).sort() : [];
+    const runs = names.filter((name) => /^[0-9a-f-]{36}\.json$/.test(name))
+        .map((name) => Run.parse(readJson(resolveInside(root, `${paths.directory}/${name}`))))
+        .sort((a, b) => a.at.localeCompare(b.at) || a.runId.localeCompare(b.runId));
+    for (const run of runs)
+        ledger.runs[run.id] = run;
+    const reviews = names.filter((name) => REVIEW_FILE.test(name))
+        .map((name) => ({ name, record: ReviewRecord.parse(readJson(resolveInside(root, `${paths.directory}/${name}`))) }))
+        .sort((a, b) => a.record.at.localeCompare(b.record.at) || a.name.localeCompare(b.name));
+    for (const { record } of reviews)
+        for (const issue of record.updates)
+            ledger.issues[issue.id] = issue;
+    return { ...paths, ledger, rounds: reviews.length, repairRounds: repairRoundsAcrossRevisions(root, change, packet.stepId), lastReview: reviews.at(-1)?.record };
+}
+/**
+ * The two-repair cost guard belongs to the task, not to one source revision: a cancel → source update →
+ * re-plan keeps the same task id and its retained files, so earlier actual repairs still count.
+ * Runs and issues stay per revision because the sources they were checked against changed.
+ */
+function repairRoundsAcrossRevisions(root, change, stepId) {
+    const executionDir = resolveInside(root, artifactRel(change, '.opsx/execution'));
+    if (!exists(executionDir))
+        return 0;
+    let count = 0;
+    for (const revision of readdirSync(executionDir).filter((name) => /^r\d+$/.test(name))) {
+        const directory = path.join(executionDir, revision, stepId);
+        if (!exists(directory))
+            continue;
+        for (const name of readdirSync(directory).filter((file) => REVIEW_FILE.test(file))) {
+            if (ReviewRecord.parse(readJson(path.join(directory, name))).repair)
+                count += 1;
+        }
+    }
+    return count;
+}
+/** 本 task 已做过几次独立验收（每次 `worker review` 一条记录）；控制会话据此判断返修上限，不凭记忆。 */
+export function reviewRounds(root, change, packet) {
+    if (!packet.executionEvidence)
+        return 0;
+    return load(root, change, packet).rounds;
+}
+export function repairRounds(root, change, packet) {
+    return packet.executionEvidence ? load(root, change, packet).repairRounds : 0;
+}
+export function prepareWorkerEvidence(root, change, packet) {
+    if (!packet.executionEvidence)
+        return;
+    const store = load(root, change, packet);
+    // Redispatch must expose the latest records before the next worker reads the index.
+    writeJson(store.absolute, store.ledger);
+    packet.refs.executionEvidence = store.relative;
+}
+function activePacket(root, change) {
+    const state = requireChange(root, change);
+    if (!state.activeWorker)
+        throw new AppError('no_active_worker', '当前没有待验收的 worker');
+    const packet = WorkerPacketSchema.parse(readJson(resolveInside(root, state.activeWorker.packet)));
+    if (packet.workerId !== state.activeWorker.workerId || packet.stepId !== state.activeWorker.stepId || packet.changeName !== change
+        || !packet.executionEvidence)
+        throw new AppError('worker_evidence_unavailable', '检查回执仅用于启用 executionEvidence 的 Worker packet');
+    return packet;
+}
+function validArtifact(root, relative, digest) {
+    const absolute = resolveInside(root, relative, 'worker_evidence_outside_project');
+    return exists(absolute) && statSync(absolute).isFile() && sha256File(absolute) === digest;
+}
+/** Runs once, stores full output on disk, and reuses only successful unchanged receipts. */
+export function runWorkerCheck(root, change, id, command, force = false, inputFile) {
+    Id.parse(id);
+    const packet = activePacket(root, change);
+    const hook = packet.initContext?.hooks.find((item) => item.id === id);
+    if (hook?.type === 'command') {
+        if (command && command !== hook.command)
+            throw new AppError('worker_check_command_mismatch', '不能覆盖 packet 中的 command Hook');
+        command = hook.command;
+    }
+    if (!command?.trim())
+        throw new AppError('worker_check_command_missing', '提供 --command 或使用 command Hook id');
+    if (inputFile && !hook?.plugin)
+        throw new AppError('worker_check_input_unsupported', '--input 仅用于插件 command Hook');
+    const executable = hook?.plugin ? undefined : splitCommand(command);
+    const store = load(root, change, packet);
+    const before = fingerprint(root);
+    const previous = store.ledger.runs[id];
+    if (!hook?.plugin && !force && previous?.ok && (previous.workerId === packet.workerId || (!packet.executionEvidenceVersion && !previous.workerId)) && previous.command === command && previous.fingerprint === before
+        && validArtifact(root, previous.log, previous.logDigest) && (!previous.context || commandContextCurrent(root, previous.context)))
+        return { ...previous, cached: true };
+    const runId = randomUUID();
+    const log = `${store.directory}/${runId}.log`;
+    const prepared = hook?.plugin ? operationContext(root, change, hook.plugin, resolveInside(root, `${store.directory}/${runId}`), inputFile, { workerId: packet.workerId, stepId: packet.stepId }) : undefined;
+    const pluginResult = hook?.plugin && prepared ? runPluginCommand(root, hook.plugin, prepared.context, prepared.files) : undefined;
+    const context = hook?.plugin ? undefined : prepareCommandContext(root, change, `${store.directory}/${runId}.context.json`, runId, id, packet);
+    const result = pluginResult ? { ...pluginResult, stdout: `完整结果: ${path.relative(root, pluginResult.stdoutPath)}`, stderr: `诊断: ${path.relative(root, pluginResult.stderrPath)}` }
+        : runLoggedCommand(executable.bin, executable.args, root, resolveInside(root, log), 0, context?.env);
+    const actualLog = pluginResult ? path.relative(root, pluginResult.stdoutPath) : log;
+    const run = Run.parse({ id, runId, workerId: packet.workerId, command, code: result.code, ok: result.ok,
+        ...(pluginResult ? { plugin: savePluginEvidence(root, prepared.context.outputDir, pluginResult.receipt) } : {}),
+        ...(context ? { context: context.evidence } : {}),
+        outputSummary: [result.stdout, result.stderr].filter(Boolean).join('\n'),
+        fingerprint: fingerprint(root), log: actualLog, logDigest: sha256File(resolveInside(root, actualLog)), at: new Date().toISOString() });
+    // Keep every attempt; rebuild the view from independent records after publishing.
+    writeJson(resolveInside(root, `${store.directory}/${runId}.json`), run);
+    const latest = load(root, change, packet);
+    writeJson(latest.absolute, latest.ledger);
+    appendEvent(root, change, 'worker.check', { workerId: packet.workerId, id, runId, ok: run.ok, log: actualLog });
+    return { ...run, cached: false };
+}
+/** Reviewer updates are merged by id: omitting an old issue cannot resolve it. An empty array records a clean pass. */
+export function recordWorkerReview(root, change, updates, repaired = false) {
+    const parsed = z.array(Issue.omit({ evidenceDigest: true, fingerprint: true })).parse(updates);
+    if (new Set(parsed.map((item) => item.id)).size !== parsed.length)
+        throw new AppError('duplicate_review_issue', '同次更新不能重复问题 id');
+    const packet = activePacket(root, change);
+    const store = load(root, change, packet);
+    const current = fingerprint(root);
+    if (repaired && !store.lastReview)
+        throw new AppError('initial_review_required', '首次独立验收不能计为返修');
+    const actualRepair = repaired && store.lastReview?.codeFingerprint !== current;
+    if (actualRepair && packet.task?.category === 'ui' && store.repairRounds >= 2) {
+        throw new AppError('worker_repair_limit', '本 UI task 已完成两轮实际返修；保留未通过问题并停止');
+    }
+    for (const item of parsed) {
+        if (item.advisory && packet.task?.category !== 'ui')
+            throw new AppError('review_advisory_ui_only', 'advisory 仅用于 UI 普通视觉偏差，不用于行为、构建或证据不可用');
+        if (item.status === 'resolved' && !store.ledger.issues[item.id])
+            throw new AppError('unknown_review_issue', `先登记问题再解决: ${item.id}`);
+        if (item.status === 'resolved' || item.advisory) {
+            if (!item.evidence)
+                throw new AppError('review_evidence_missing', `解决或披露问题需要证据: ${item.id}`);
+            const absolute = resolveInside(root, item.evidence, 'worker_evidence_outside_project');
+            if (!exists(absolute) || !statSync(absolute).isFile() || statSync(absolute).size === 0)
+                throw new AppError('review_evidence_missing', `证据必须是非空文件: ${item.id}`);
+            store.ledger.issues[item.id] = { ...item, evidenceDigest: sha256File(absolute), fingerprint: current };
+        }
+        else
+            store.ledger.issues[item.id] = item;
+    }
+    writeJson(resolveInside(root, `${store.directory}/review-${randomUUID()}.json`), {
+        at: new Date().toISOString(), updates: parsed.map((item) => store.ledger.issues[item.id]), codeFingerprint: current, repair: actualRepair,
+    });
+    const latest = load(root, change, packet);
+    writeJson(latest.absolute, latest.ledger);
+    appendEvent(root, change, 'worker.review', { workerId: packet.workerId, updates: parsed });
+    return {
+        path: store.relative,
+        open: Object.values(latest.ledger.issues).filter((item) => item.status === 'open').map((item) => item.id),
+        blocking: Object.values(latest.ledger.issues).filter((item) => item.status === 'open' && !item.advisory).map((item) => item.id),
+        advisory: Object.values(latest.ledger.issues).filter((item) => item.status === 'open' && item.advisory).map((item) => item.id),
+        rounds: latest.rounds, repairRounds: latest.repairRounds,
+    };
+}
+export function validateWorkerEvidence(root, change, packet) {
+    if (!packet.executionEvidence)
+        return; // Existing in-flight packets keep their original contract.
+    const store = load(root, change, packet);
+    const { ledger } = store;
+    writeJson(store.absolute, ledger);
+    const failures = [];
+    const fail = (code, message, details) => failures.push({ code, message, ...(details === undefined ? {} : { details }) });
+    const required = packet.initContext?.hooks.filter((item) => item.type === 'command' && item.required) ?? [];
+    for (const hook of required) {
+        const run = ledger.runs[hook.id];
+        if (!run || hook.type !== 'command' || run.command !== hook.command || ((packet.executionEvidenceVersion || run.workerId) && run.workerId !== packet.workerId) || (hook.plugin && (!run.plugin || JSON.stringify(run.plugin.binding) !== JSON.stringify(hook.plugin) || run.plugin.workerId !== packet.workerId || run.plugin.stepId !== packet.stepId)))
+            fail('worker_check_missing', `缺少 CLI 检查回执: ${hook.id}`);
+    }
+    const runs = Object.values(ledger.runs);
+    const current = runs.length || Object.keys(ledger.issues).length ? fingerprint(root) : '';
+    for (const run of runs) {
+        const optional = packet.initContext?.hooks.some((hook) => hook.id === run.id && hook.type === 'command' && !hook.required);
+        if (optional)
+            continue;
+        if (!run.ok)
+            fail('worker_check_failed', `检查失败，修复后用同一 id 重跑: ${run.id}`, { log: run.log });
+        else if ((packet.executionEvidenceVersion && run.workerId !== packet.workerId) || run.fingerprint !== current || !validArtifact(root, run.log, run.logDigest) || (run.plugin && !pluginEvidenceCurrent(root, run.plugin)) || (run.context && !commandContextCurrent(root, run.context)))
+            fail('worker_check_stale', `Worker、代码或日志已变化，重新检查: ${run.id}`);
+    }
+    for (const issue of Object.values(ledger.issues)) {
+        if (issue.status === 'open' && (!issue.advisory || packet.task?.category !== 'ui'))
+            fail('worker_review_open', `未解决的返修问题: ${issue.id}`, { description: issue.description });
+        else if (issue.fingerprint !== current || !issue.evidence || !issue.evidenceDigest || !validArtifact(root, issue.evidence, issue.evidenceDigest))
+            fail('worker_review_stale', `返修证据已变化，重新复核: ${issue.id}`);
+    }
+    if (failures.length)
+        throw new AppError(failures[0].code, failures.map((item) => item.message).join('\n'), { failures });
+}
+/** Final disclosure comes from review records, not optional prose in a worker result. */
+export const VisualAdvisorySchema = Issue.extend({ stepId: z.string() });
+export function visualAdvisories(root, change) {
+    const state = requireChange(root, change);
+    const directory = resolveInside(root, artifactRel(change, `.opsx/execution/r${state.sourceRevision}`));
+    if (!exists(directory))
+        return [];
+    return readdirSync(directory).filter(name => /^code-/.test(name) && statSync(path.join(directory, name)).isDirectory()).flatMap(stepId => {
+        const issues = {};
+        const reviews = readdirSync(path.join(directory, stepId)).filter(name => REVIEW_FILE.test(name))
+            .map(name => ({ name, record: ReviewRecord.parse(readJson(path.join(directory, stepId, name))) }))
+            .sort((a, b) => a.record.at.localeCompare(b.record.at) || a.name.localeCompare(b.name));
+        for (const { record } of reviews)
+            for (const issue of record.updates)
+                issues[issue.id] = issue;
+        return Object.values(issues).filter(issue => issue.status === 'open' && issue.advisory).map(issue => ({ ...issue, stepId }));
+    });
+}
+//# sourceMappingURL=worker-evidence.js.map

package/dist/core/worker.d.ts

@@ -0,0 +1,22 @@
+import { type ProjectConfig } from '../config/schema.js';
+import { type ChangeState, type WorkerPacket } from './types.js';
+export declare function createWorker(projectRoot: string, changeName: string, stepId: string, config: ProjectConfig, options?: {
+    refresh?: boolean;
+}): {
+    packet: WorkerPacket;
+    path: string;
+};
+export declare function acceptWorker(projectRoot: string, changeName: string, resultPath: string, config: ProjectConfig): ChangeState;
+/**
+ * 记录用户对 blocked Worker 的答复：写入 packet.decisions 并清除 blocked issue。
+ * 之后 `worker create` 同一 step 会复用该 packet，Worker 按 decisions 完成产物后重新 accept。
+ */
+export declare function answerWorker(projectRoot: string, changeName: string, answers: string[]): {
+    state: ChangeState;
+    packet: WorkerPacket;
+    path: string;
+};
+export declare function cancelWorker(projectRoot: string, changeName: string, reason: string): ChangeState;
+/** scout 子代理写出的 task 摘要路径；按 taskId 固定，与 workerId 无关，返修与重派都能复用。 */
+export declare function taskContextRel(changeName: string, taskId: string): string;
+//# sourceMappingURL=worker.d.ts.map