@youcloud/metersphere-mcp 0.0.0-stage → 1.0.0

package/dist/workflow/executor.js

@@ -0,0 +1,599 @@
+import { randomUUID } from 'node:crypto';
+import { ApiError, ensure, problem, WorkflowError } from '../errors.js';
+import { executionDefinition, executionSnapshot, fieldsMatch, pick, renderRecord, resultBody, segment, serializeSteps, escapeHtml, reportSnapshotVerification } from '../adapters/v1-20.js';
+import { digest } from './tokens.js';
+const creates = new Set(['create_test_case', 'create_case_module', 'create_test_plan', 'create_case_review']);
+const editableFields = ['id', 'nodeId', 'testId', 'nodePath', 'projectId', 'name', 'type', 'maintainer', 'priority', 'method', 'otherTestName', 'reviewStatus', 'tags', 'demandId', 'demandName', 'status', 'stepModel', 'customNum', 'casePublic', 'versionId', 'refId', 'prerequisite', 'remark', 'steps', 'stepDescription', 'expectedResult', 'customFields'];
+const business = (input) => { const { dry_run: _d, resume: _r, ...rest } = input; return rest; };
+export class Executor {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    get ms() { return this.context.ms; }
+    async execute(action, input) {
+        return this.withLocks(releases => this.executeWithLocks(action, input, releases));
+    }
+    async executeWithLocks(action, input, releases) {
+        let op = null, ledger, mayPersist = false;
+        try {
+            this.context.assertToolEnabled(action);
+            ensure(!input.dry_run || !input.resume, 'INVALID_INPUT', '预览不能同时恢复');
+            ensure(input.dry_run || input.operation_id, 'INVALID_INPUT', '真实写入必须提供 operation_id');
+            ensure(input.dry_run || creates.has(action) || input.expected_revision, 'INVALID_INPUT', '修改已有对象必须提供 expected_revision');
+            const session = await this.ms.session();
+            ledger = this.context.ledger(session);
+            await this.context.visible(input);
+            if (input.dry_run) {
+                const plan = await this.prepare(action, input, session);
+                return this.output(action, null, 'preview', { subject: plan.subject, result: { proposed: plan.public_plan }, verification: { write_permission_verified: false } });
+            }
+            const lock = await ledger.lock(`operation:${input.operation_id}`);
+            if (!lock)
+                return this.output(action, input.operation_id, 'in_progress');
+            releases.push(lock);
+            op = await ledger.load(input.operation_id);
+            const args = business(input);
+            if (op) {
+                ensure(op.actor_id === session.user.id && op.action === action && op.request_hash === digest(args), 'OPERATION_CONFLICT', '同一操作 ID 的工具、主体或业务参数不能改变');
+                ensure(op.config_hash === digest(this.ms.config.workflow), 'CONFIG_CONFLICT', '操作创建后的配置已改变，请先核对原配置再恢复');
+                await this.context.visible({ ...op.args, ...op.plan.subject });
+            }
+            else
+                ensure(!input.resume, 'RECOVERY_UNAVAILABLE', '原操作记录不存在，禁止将恢复当成新操作执行');
+            mayPersist = true;
+            for (const key of await this.targetLocks(action, input)) {
+                const targetLock = await ledger.lock(key);
+                if (!targetLock)
+                    return this.output(action, input.operation_id, 'in_progress');
+                releases.push(targetLock);
+            }
+            if (!op) {
+                const plan = await this.prepare(action, input, session);
+                op = { schema_version: 1, id: input.operation_id, action, actor_id: session.user.id, config_hash: digest(this.ms.config.workflow), args, request_hash: digest(args),
+                    plan, plan_hash: digest(plan), steps: [], created_at: Date.now(), updated_at: Date.now() };
+                await ledger.save(op);
+            }
+            else {
+                for (const step of op.steps)
+                    if (step.state === 'in_flight')
+                        step.state = 'unknown';
+                if (op.outcome === 'succeeded')
+                    return this.format(op, { historical_result: true });
+            }
+            // 已存在的操作，只有明确恢复才允许发出尚未开始/明确被拒绝的写入；核查始终可以读。
+            const mayWrite = op.steps.length === 0 || input.resume === true;
+            await this.run(op, session, ledger, mayWrite);
+            await ledger.save(op);
+            return this.format(op);
+        }
+        catch (error) {
+            if (op && ledger && mayPersist) {
+                this.recordFailure(op, error);
+                try {
+                    await ledger.save(op);
+                }
+                catch (persistenceError) {
+                    return this.persistenceFailure(op, persistenceError);
+                }
+                return this.format(op);
+            }
+            return this.output(action, input.operation_id ?? null, 'rejected', { error: problem(error) });
+        }
+    }
+    async operation(id) {
+        this.context.assertToolEnabled('get_workflow_operation');
+        const session = await this.ms.session(), ledger = this.context.ledger(session);
+        let op = await ledger.load(id);
+        ensure(op && op.actor_id === session.user.id, 'RECOVERY_UNAVAILABLE', '当前主体没有该操作记录');
+        await this.context.visible({ ...op.args, ...op.plan.subject });
+        return this.withLocks(async (releases) => {
+            ensure(op, 'RECOVERY_UNAVAILABLE', '操作记录不可恢复');
+            for (const key of [`operation:${id}`, ...await this.targetLocks(op.action, op.args)]) {
+                const lock = await ledger.lock(key);
+                if (!lock)
+                    return this.output(op.action, id, 'in_progress');
+                releases.push(lock);
+            }
+            op = await ledger.load(id);
+            ensure(op && op.actor_id === session.user.id, 'RECOVERY_UNAVAILABLE', '操作记录不可恢复');
+            if (op.outcome === 'succeeded')
+                return this.format(op, { historical_result: true });
+            ensure(op.config_hash === digest(this.ms.config.workflow), 'CONFIG_CONFLICT', '操作创建后的配置已改变，请先核对原配置再恢复');
+            for (const step of op.steps)
+                if (step.state === 'in_flight')
+                    step.state = 'unknown';
+            try {
+                await this.run(op, session, ledger, false);
+            }
+            catch (error) {
+                this.recordFailure(op, error);
+            }
+            try {
+                await ledger.save(op);
+            }
+            catch (error) {
+                this.recordFailure(op, error);
+                return this.persistenceFailure(op, error);
+            }
+            return this.format(op);
+        });
+    }
+    async withLocks(work) {
+        const releases = [], errors = [];
+        let result;
+        try {
+            result = await work(releases);
+            return result;
+        }
+        finally {
+            // 清理失败不能覆盖已确认的业务结果，也不能阻止其余锁释放。
+            for (const release of releases.reverse()) {
+                try {
+                    await release();
+                }
+                catch (error) {
+                    errors.push(problem(error));
+                }
+            }
+            if (result && errors.length) {
+                result.verification = { ...result.verification, locks_released: false, lock_release_errors: errors };
+                result.recovery = { action: 'manual_review', automatic_retry: false };
+                result.warnings.push('本地锁未能全部释放；业务结果保留，修复存储并清理遗留锁后用原 operation_id 核查');
+            }
+        }
+    }
+    recordFailure(op, error) {
+        op.error = problem(error);
+        op.outcome = op.steps.some(s => ['unknown', 'in_flight'].includes(s.state)) ? 'unknown'
+            : error instanceof WorkflowError && ['REVISION_CONFLICT', 'RESULT_MISMATCH', 'TARGET_MISMATCH'].includes(error.code) ? 'conflict'
+                : op.steps.some(s => s.state === 'succeeded') ? 'partial_success' : 'rejected';
+    }
+    persistenceFailure(op, error) {
+        // 账本再次保存失败不能退化成无步骤的 rejected，更不能暗示未知请求可直接重发。
+        const result = this.format(op, { ledger_persisted: false, persistence_error: problem(error) });
+        return { ...result, recovery: { action: 'manual_review', automatic_retry: false },
+            warnings: [...result.warnings, '操作账本未能可靠保存；保留原 operation_id，恢复存储后先核查'] };
+    }
+    async targetLocks(action, args) {
+        const keys = [`project:${args.project_id}:${creates.has(action) ? 'creation' : args.plan_id || args.case_id}`];
+        if (args.case_id)
+            keys.push(`case:${args.case_id}`);
+        for (const id of args.case_ids || [])
+            keys.push(`case:${id}`);
+        if (args.plan_case_id)
+            keys.push(`case:${(await this.ms.planCase(args.project_id, args.plan_id, args.plan_case_id)).caseId}`);
+        return [...new Set(keys)].sort();
+    }
+    output(action, id, outcome, extra = {}) {
+        return { schema_version: 1, action, operation_id: id, outcome, subject: {}, result: null, steps: [],
+            verification: { concurrency_mode: 'snapshot_precheck' }, recovery: { action: 'none', automatic_retry: false }, warnings: [], ...extra };
+    }
+    format(op, verification = {}) {
+        const uncertain = op.outcome === 'unknown' || op.steps.some(s => s.state === 'unknown' || s.state === 'in_flight');
+        const success = op.outcome === 'succeeded';
+        const enabled = this.context.enabledTools.has(op.action);
+        const resumable = !success && !uncertain && op.outcome !== 'conflict' && enabled;
+        return this.output(op.action, op.id, op.outcome || (uncertain ? 'unknown' : 'partial_success'), {
+            subject: op.plan.subject, result: op.result || null,
+            steps: op.steps.map(s => ({ name: s.name, state: s.state, ...(s.error ? { error: s.error } : {}) })),
+            verification: { concurrency_mode: 'snapshot_precheck', readback_verified: op.verified === true, ...verification },
+            recovery: { action: success ? 'none' : resumable ? 'resume_same_operation' : 'manual_review', automatic_retry: false,
+                ...(resumable ? { tool: op.action, resume: true } : {}) },
+            warnings: ['本地前置检查不能消除网页用户或其他机器的并发写入', ...(!success && !enabled ? ['当前配置禁用原写工具，仅可核查，恢复前须调整访问配置并重启服务'] : [])], ...(op.error ? { error: op.error } : {})
+        });
+    }
+    async prepare(action, args, session) {
+        const project = await this.ms.project(args.project_id), plan = { subject: pick(args, ['project_id', 'case_id', 'plan_id', 'plan_case_id', 'run_id', 'attempt_id']), public_plan: { action } };
+        const marker = `MSMCP:${args.operation_id || 'preview'}`;
+        if (action === 'create_test_plan' || action === 'create_case_review') {
+            plan.marker = marker;
+            const path = action === 'create_test_plan' ? '/test/plan/list' : '/test/case/review/list';
+            const existing = (await this.ms.all(path, { projectId: args.project_id, name: args.name })).filter(x => x.name === args.name && x.projectId === args.project_id);
+            ensure(!existing.length, 'AMBIGUOUS_TARGET', '已存在同名对象，请先核对并使用其真实 ID；不自动复用或重复创建');
+        }
+        if (action === 'create_case_module') {
+            plan.location = await this.ms.moduleLocation(args.project_id, args.name, args.parent_id);
+            plan.body = { id: randomUUID(), projectId: args.project_id, name: args.name, parentId: plan.location.parent_id, level: plan.location.level };
+        }
+        else if (action === 'create_test_case') {
+            const node = await this.ms.node(args.project_id, args.node_id);
+            plan.node_location = node;
+            const tags = [...new Set([...args.tags, 'AI'])];
+            ensure(tags.length <= 50, 'INVALID_INPUT', '包含自动添加的 AI 标签后，标签总数不能超过 50 个');
+            // v1.20.23 接受客户端 UUID；随计划先持久化，未知写入按 ID 回读，不污染业务备注。
+            plan.body = { id: randomUUID(), projectId: args.project_id, nodeId: node.id, nodePath: node.path, name: args.name, type: 'functional', priority: args.priority,
+                prerequisite: escapeHtml(args.prerequisite), stepModel: 'STEP', steps: serializeSteps(args.steps), tags: JSON.stringify(tags), remark: escapeHtml(args.remark), status: 'Prepare', follows: [], updatedFileList: [], selected: [], handleAttachment: false };
+        }
+        else if (action === 'update_test_case') {
+            const state = await this.ms.caseEditState(args.project_id, args.case_id);
+            this.revision(args, session, 'case_definition', args.case_id, state);
+            plan.before = state;
+            plan.body = { ...pick(state.item, editableFields), follows: state.follows, updatedFileList: state.files, selected: [], handleAttachment: false };
+            for (const [key, value] of Object.entries(args.changes)) {
+                if (key === 'steps') {
+                    ensure(state.item.stepModel === 'STEP', 'UNSUPPORTED_STEP_MODEL', '不允许将 TEXT 隐式转换成 STEP');
+                    plan.body.steps = serializeSteps(value);
+                }
+                else if (key === 'step_description' || key === 'expected_result') {
+                    ensure(state.item.stepModel === 'TEXT', 'UNSUPPORTED_STEP_MODEL', '不允许将 STEP 隐式转换成 TEXT');
+                    plan.body[key === 'step_description' ? 'stepDescription' : 'expectedResult'] = escapeHtml(value);
+                }
+                else if (key === 'node_id') {
+                    const node = await this.ms.node(args.project_id, value);
+                    plan.body.nodeId = node.id;
+                    plan.body.nodePath = node.path;
+                }
+                else
+                    plan.body[key] = key === 'tags' ? JSON.stringify(value) : ['remark', 'prerequisite'].includes(key) ? escapeHtml(value) : value;
+            }
+        }
+        else if (action === 'create_test_plan') {
+            await this.ms.checkMembers(args.project_id, args.principal_ids);
+            const stages = await this.ms.client.read(`/test/plan/get/stage/option/${segment(args.project_id)}`);
+            ensure(Array.isArray(stages) && stages.some(x => x === args.stage || x?.value === args.stage || x?.id === args.stage), 'INVALID_STAGE', '阶段不在当前项目的可选值中');
+            plan.body = { projectId: args.project_id, workspaceId: project.workspaceId, name: args.name, stage: args.stage, status: 'Prepare', principals: [...new Set(args.principal_ids)], follows: [],
+                plannedStartTime: Date.parse(args.starts_at), plannedEndTime: Date.parse(args.ends_at), description: `${escapeHtml(args.description)}\n${marker}` };
+        }
+        else if (action === 'create_case_review') {
+            await this.ms.checkMembers(args.project_id, args.reviewer_ids);
+            await this.checkCases(args);
+            plan.sources = [];
+            for (const id of args.case_ids)
+                plan.sources.push({ id, snapshot: executionDefinition(await this.ms.case(args.project_id, id)) });
+            plan.body = { projectId: args.project_id, name: args.name, userIds: [...new Set(args.reviewer_ids)], followIds: [],
+                endTime: args.ends_at ? Date.parse(args.ends_at) : Date.now() + 3 * 86400000, description: `${escapeHtml(args.description)}\n${marker}` };
+        }
+        else if (action === 'add_cases_to_plan') {
+            await this.checkCases(args);
+            const inventory = await this.ms.inventory(args.project_id, args.plan_id);
+            ensure(inventory.plan.status !== 'Archived', 'ARCHIVED_PLAN', '已归档计划不可修改');
+            this.revision(args, session, 'plan_membership', args.plan_id, this.ms.membership(inventory));
+            plan.before = this.ms.membership(inventory);
+            plan.existing = inventory.cases;
+            plan.sources = [];
+            for (const id of args.case_ids)
+                plan.sources.push({ id, snapshot: executionDefinition(await this.ms.case(args.project_id, id)) });
+        }
+        else if (action === 'record_case_result' || action === 'link_mantis_issue') {
+            const targetPlan = await this.ms.plan(args.project_id, args.plan_id);
+            ensure(targetPlan.status !== 'Archived', 'ARCHIVED_PLAN', '已归档计划不可修改');
+            const item = await this.ms.planCase(args.project_id, args.plan_id, args.plan_case_id);
+            this.revision(args, session, 'case_execution', args.plan_case_id, executionSnapshot(item));
+            plan.before = executionSnapshot(item);
+            plan.case_id = item.caseId;
+            const records = await this.ms.records(item.caseId);
+            const matching = records.filter(x => x.project_id === args.project_id && x.plan_id === args.plan_id && x.plan_case_id === args.plan_case_id && x.run_id === args.run_id && x.attempt_id === args.attempt_id && x.kind === 'execution');
+            const record = { schema_version: 1, kind: action === 'record_case_result' ? 'execution' : 'mantis_reference', actor_id: session.user.id,
+                ...pick(args, ['project_id', 'plan_id', 'plan_case_id', 'run_id', 'attempt_id']), case_id: item.caseId, operation_id: args.operation_id || 'preview', definition_hash: digest(executionDefinition(item)) };
+            if (action === 'record_case_result') {
+                ensure(!matching.length, 'DUPLICATE_ATTEMPT', `该 attempt 已记录，请核查原操作 ${matching[0]?.operation_id || ''}`);
+                plan.body = resultBody(item, args.result);
+                record.result = args.result;
+            }
+            else {
+                ensure(matching.length === 1 && matching[0].actor_id === session.user.id && matching[0].definition_hash === record.definition_hash, 'MISSING_CURRENT_ATTEMPT', '找不到当前主体的唯一对应执行记录');
+                const binding = this.ms.config.workflow.project_bindings.find(x => x.metersphere_project_id === args.project_id);
+                ensure(binding?.mantis_project_id === args.mantis_project_id, 'MISSING_PROJECT_BINDING', 'Mantis 项目与显式绑定不一致');
+                Object.assign(record, pick(args, ['mantis_project_id', 'issue_id', 'relation', 'reason']), { url: `${this.ms.config.workflow.mantis_base_url}/view.php?id=${args.issue_id}` });
+            }
+            ensure(JSON.stringify(record).length <= this.ms.config.workflow.limits.max_execution_record_chars, 'RECORD_TOO_LARGE', '执行记录超过配置上限，未截断证据');
+            plan.record = record;
+            plan.comment = { caseId: item.caseId, description: renderRecord(record) };
+        }
+        else if (action === 'complete_test_plan' || action === 'generate_test_report') {
+            const inventory = await this.ms.inventory(args.project_id, args.plan_id);
+            plan.execution_summary = await this.ms.executionSummary(inventory, args.run_id);
+            plan.before = this.ms.completionSnapshot(inventory, args.run_id, plan.execution_summary);
+            this.revision(args, session, 'plan_completion', args.plan_id, plan.before);
+            ensure(!(await this.context.ledger(session).pending(args.plan_id, args.operation_id)).length, 'PENDING_OPERATION', '该计划有尚待核查的写操作');
+            if (action === 'complete_test_plan') {
+                ensure(inventory.plan.status !== 'Archived', 'ARCHIVED_PLAN', '已归档计划不可完成');
+                ensure(plan.execution_summary.completion_ready, 'INCOMPLETE_SCOPE', '本轮存在未执行、未处置失败或不支持的计划成员，请读取 execution_summary');
+                plan.already_terminal = ['Completed', 'Finished'].includes(inventory.plan.status);
+            }
+            else {
+                this.reportReady(inventory, plan.execution_summary);
+                plan.before_report_ids = (await this.ms.all('/test/plan/report/list', { projectId: args.project_id })).map(x => x.id);
+                plan.report_snapshot = inventory.cases.map((x) => pick(x, ['id', 'caseId', 'status', 'results', 'actualResult']));
+            }
+        }
+        plan.public_plan = { action, subject: plan.subject, ...(plan.body ? { fields: plan.body } : {}),
+            ...(plan.location ? { path: plan.location.path } : {}),
+            ...(plan.comment ? { execution_record: plan.record, may_notify_followers: true } : {}), ...(args.case_ids ? { case_ids: args.case_ids } : {}),
+            ...(plan.execution_summary ? { execution_summary: plan.execution_summary } : {}) };
+        return plan;
+    }
+    revision(args, session, scope, subject, snapshot) {
+        if (args.expected_revision)
+            session.tokens.check(args.expected_revision, scope, subject, snapshot);
+        else
+            ensure(args.dry_run, 'INVALID_INPUT', '缺少对应的 expected_revision');
+    }
+    async checkCases(args) {
+        ensure(args.case_ids.length <= this.ms.config.workflow.limits.max_association_items && new Set(args.case_ids).size === args.case_ids.length, 'INVALID_INPUT', '关联用例不能重复或超过配置上限');
+        for (const id of args.case_ids)
+            await this.ms.case(args.project_id, id);
+    }
+    reportReady(inventory, summary) {
+        ensure(inventory.plan.status !== 'Archived', 'ARCHIVED_PLAN', '已归档计划不可生成报告，以免解除归档');
+        ensure(['Completed', 'Finished'].includes(inventory.plan.status), 'PLAN_NOT_COMPLETED', '生成报告会重算计划状态；请先完成本轮计划，不支持未完成的阶段报告');
+        ensure(!Object.values(inventory.other_counts).some(x => Number(x) > 0), 'MIXED_PLAN', '首版不生成混合计划的完整测试报告');
+        ensure(summary.completion_ready, 'INCOMPLETE_SCOPE', '生成报告前须核对本轮完整执行与失败处置，不能使用旧轮次结果');
+    }
+    membershipMatches(current, before, allowAdditions = false) {
+        // testPlanRelevance 在新增成员后将 Prepare/Completed 改为 Underway，发送前不放宽检查。
+        const expectedPlan = allowAdditions && ['Prepare', 'Completed'].includes(before.plan.status) ? { ...before.plan, status: 'Underway' } : before.plan;
+        return digest(current.plan) === digest(expectedPlan) && digest(current.other_counts) === digest(before.other_counts)
+            && (allowAdditions || current.members.length === before.members.length)
+            // 旧账本的列表快照可能没有 refId；保留其中已记录字段的检查，不能因补读详情而误报变化。
+            && before.members.every((x) => current.members.some((v) => fieldsMatch(v, x)));
+    }
+    async guard(op) {
+        const a = op.args;
+        await this.context.visible(a);
+        if (op.action === 'create_case_module') {
+            const location = await this.ms.moduleLocation(a.project_id, a.name, a.parent_id);
+            ensure(digest(location) === digest(op.plan.location), 'REVISION_CONFLICT', '创建前父模块的位置或名称已改变，请重新核对模块树');
+        }
+        if (op.action === 'create_test_case') {
+            const node = await this.ms.node(a.project_id, a.node_id);
+            const unchanged = op.plan.node_location ? digest(node) === digest(op.plan.node_location) : node.path === op.plan.body.nodePath;
+            ensure(unchanged, 'REVISION_CONFLICT', '创建前目标模块的位置或名称已改变，请重新核对模块树');
+        }
+        if (op.action === 'update_test_case')
+            ensure(digest(await this.ms.caseEditState(a.project_id, a.case_id)) === digest(op.plan.before), 'REVISION_CONFLICT', '编辑前用例、附件或关注人已改变');
+        if (op.action === 'add_cases_to_plan') {
+            const inventory = await this.ms.inventory(a.project_id, a.plan_id);
+            ensure(this.membershipMatches(this.ms.membership(inventory), op.plan.current_membership || op.plan.before), 'REVISION_CONFLICT', '关联前计划成员已改变');
+            for (const source of op.plan.sources)
+                ensure(digest(executionDefinition(await this.ms.case(a.project_id, source.id))) === digest(source.snapshot), 'REVISION_CONFLICT', '待关联用例内容已改变');
+        }
+        if (op.action === 'create_case_review') {
+            for (const source of op.plan.sources)
+                ensure(digest(executionDefinition(await this.ms.case(a.project_id, source.id))) === digest(source.snapshot), 'REVISION_CONFLICT', '待评审用例内容已改变');
+            if (op.plan.created_id)
+                await this.ms.review(a.project_id, op.plan.created_id);
+        }
+        if (['record_case_result', 'link_mantis_issue'].includes(op.action)) {
+            const current = await this.ms.planCase(a.project_id, a.plan_id, a.plan_case_id);
+            ensure(digest(executionSnapshot(current)) === digest(op.plan.before), 'REVISION_CONFLICT', '执行结果或用例定义已改变');
+            ensure((await this.ms.plan(a.project_id, a.plan_id)).status !== 'Archived', 'ARCHIVED_PLAN', '计划已归档');
+        }
+        if (['complete_test_plan', 'generate_test_report'].includes(op.action)) {
+            const now = await this.ms.inventory(a.project_id, a.plan_id);
+            const summary = await this.ms.executionSummary(now, a.run_id);
+            if (op.action === 'generate_test_report')
+                this.reportReady(now, summary);
+            ensure(digest(this.ms.completionSnapshot(now, a.run_id, summary)) === digest(op.plan.before), 'REVISION_CONFLICT', '计划范围、结果或执行证据已改变');
+        }
+    }
+    async write(op, ledger, name, spec, mayWrite, verify) {
+        let step = op.steps.find(x => x.name === name);
+        if (!step) {
+            step = { name, state: 'not_started' };
+            op.steps.push(step);
+            await ledger.save(op);
+        }
+        if (['succeeded', 'unknown'].includes(step.state)) {
+            if (await verify()) {
+                step.state = 'succeeded';
+                step.error = undefined;
+                await ledger.save(op);
+                return true;
+            }
+            if (op.action === 'generate_test_report') {
+                op.outcome = 'unknown';
+                return false;
+            }
+            if (step.state === 'succeeded')
+                throw new WorkflowError('RESULT_MISMATCH', '已确认写入的当前内容与预期不一致；禁止重复写入');
+            op.outcome = 'unknown';
+            return false;
+        }
+        if (!mayWrite) {
+            op.outcome = op.steps.some(x => x.state === 'succeeded') ? 'partial_success' : 'rejected';
+            return false;
+        }
+        await this.guard(op);
+        const hash = digest(spec);
+        ensure(!step.request_hash || step.request_hash === hash, 'OPERATION_CONFLICT', '恢复步骤的请求内容发生变化');
+        step.request_hash = hash;
+        step.state = 'in_flight';
+        step.error = undefined;
+        step.started_at = Date.now();
+        await ledger.save(op);
+        try {
+            step.response = await this.ms.client.request(spec);
+            step.state = 'succeeded';
+            step.acknowledged_at = Date.now();
+            await ledger.save(op);
+        }
+        catch (error) {
+            step.state = error instanceof ApiError && error.definite ? 'rejected' : 'unknown';
+            step.error = problem(error);
+            await ledger.save(op);
+            throw error;
+        }
+        if (!await verify()) {
+            if (op.action === 'generate_test_report') {
+                op.outcome = 'unknown';
+                return false;
+            }
+            throw new WorkflowError('RESULT_MISMATCH', '写入响应成功，但回读未确认预期效果；未重新发送写入');
+        }
+        await ledger.save(op);
+        return true;
+    }
+    async comment(op, session, ledger, mayWrite) {
+        return this.write(op, ledger, 'append_execution_record', { method: 'POST', path: '/test/case/comment/save', effect: 'write', body: op.plan.comment }, mayWrite, async () => {
+            const found = (await this.ms.comments(op.plan.case_id)).filter(x => x.caseId === op.plan.case_id && x.author === session.user.id && x.description === op.plan.comment.description);
+            if (found.length !== 1)
+                return false;
+            op.plan.comment_id = found[0].id;
+            return true;
+        });
+    }
+    async run(op, session, ledger, mayWrite) {
+        const a = op.args, p = op.plan;
+        op.error = undefined;
+        if (op.action === 'create_case_module') {
+            if (!await this.write(op, ledger, 'create_module', { method: 'POST', path: '/case/node/add', effect: 'write', body: p.body }, mayWrite, async () => {
+                const response = op.steps.find(s => s.name === 'create_module')?.response;
+                if (response !== undefined && response !== p.body.id)
+                    return false;
+                const node = await this.ms.node(a.project_id, p.body.id);
+                if (!fieldsMatch(node, p.body) || node.path !== p.location.path)
+                    return false;
+                p.subject.node_id = node.id;
+                return true;
+            }))
+                return;
+            op.result = { ...p.subject, parent_id: p.body.parentId, level: p.body.level, path: p.location.path, created: true };
+        }
+        else if (['create_test_case', 'create_test_plan', 'create_case_review'].includes(op.action)) {
+            const kind = op.action === 'create_test_case' ? 'case' : op.action === 'create_test_plan' ? 'plan' : 'review';
+            const path = kind === 'case' ? '/test/case/add' : kind === 'plan' ? '/test/plan/add' : '/test/case/review/save';
+            const verified = await this.write(op, ledger, 'create', { method: 'POST', path, effect: 'write', body: p.body, multipart: kind === 'case' }, mayWrite, async () => {
+                const response = op.steps.find(s => s.name === 'create')?.response;
+                const responseId = typeof response === 'string' && response !== 'success' ? response : typeof response === 'object' ? response?.id : undefined;
+                if (kind === 'case' && p.body.id && responseId && responseId !== p.body.id)
+                    return false;
+                let id = p.created_id || (kind === 'case' ? p.body.id : undefined) || responseId;
+                if (!id) {
+                    // 兼容升级前已持久化的来源标记；新用例不再生成标记，也不按名称推测目标。
+                    if (typeof p.marker !== 'string' || !p.marker)
+                        return false;
+                    const listPath = kind === 'case' ? '/test/case/list' : kind === 'plan' ? '/test/plan/list' : '/test/case/review/list';
+                    const found = (await this.ms.all(listPath, { projectId: a.project_id, name: a.name })).filter(x => x.projectId === a.project_id && x.name === a.name && String(x[kind === 'case' ? 'remark' : 'description']).includes(p.marker));
+                    if (found.length !== 1)
+                        return false;
+                    id = found[0].id;
+                }
+                let actual;
+                if (kind === 'case')
+                    actual = await this.ms.case(a.project_id, id);
+                else if (kind === 'plan')
+                    actual = await this.ms.plan(a.project_id, id);
+                else
+                    actual = await this.ms.review(a.project_id, id);
+                const expected = kind === 'case' ? pick(p.body, ['id', 'projectId', 'name', 'type', 'nodeId', 'nodePath', 'stepModel', 'steps', 'priority', 'prerequisite', 'tags', 'remark'])
+                    : kind === 'plan' ? pick(p.body, ['projectId', 'name', 'stage', 'description', 'plannedStartTime', 'plannedEndTime']) : pick(p.body, ['projectId', 'name', 'description', 'endTime']);
+                if (!fieldsMatch(actual, expected))
+                    return false;
+                if (kind === 'plan') {
+                    const principals = await this.ms.principals(id);
+                    if (digest([...new Set(principals.map(x => x.id))].sort()) !== digest([...p.body.principals].sort()))
+                        return false;
+                }
+                if (kind === 'review' && digest((await this.ms.reviewers(id)).map(x => x.id).sort()) !== digest([...new Set(a.reviewer_ids)].sort()))
+                    return false;
+                p.created_id = id;
+                p.subject[`${kind}_id`] = id;
+                return true;
+            });
+            if (!verified)
+                return;
+            if (kind === 'review') {
+                const linked = await this.write(op, ledger, 'associate_review_cases', { method: 'POST', path: '/test/case/review/relevance', effect: 'write', body: { reviewId: p.created_id, testCaseIds: a.case_ids, request: { selectAll: false }, checked: false } }, mayWrite, async () => {
+                    const cases = await this.ms.all('/test/review/case/list', { projectId: a.project_id, reviewId: p.created_id });
+                    for (const item of cases)
+                        await this.ms.reviewCase(a.project_id, p.created_id, item);
+                    return cases.length === a.case_ids.length && a.case_ids.every((id) => cases.filter(x => x.caseId === id).length === 1);
+                });
+                if (!linked)
+                    return;
+            }
+            op.result = { ...p.subject, created: true, ...(kind === 'review' ? { case_ids: a.case_ids, review_decision_written: false } : {}) };
+        }
+        else if (op.action === 'update_test_case') {
+            if (!await this.write(op, ledger, 'update_definition', { method: 'POST', path: '/test/case/edit', effect: 'write', body: p.body, multipart: true }, mayWrite, async () => {
+                const state = await this.ms.caseEditState(a.project_id, a.case_id);
+                return fieldsMatch(state.item, pick(p.body, editableFields)) && digest(state.follows) === digest(p.before.follows) && digest(state.files) === digest(p.before.files);
+            }))
+                return;
+            const state = await this.ms.caseEditState(a.project_id, a.case_id);
+            op.result = { case_id: a.case_id, expected_revision: session.tokens.revision('case_definition', a.case_id, state) };
+        }
+        else if (op.action === 'add_cases_to_plan') {
+            for (const id of a.case_ids) {
+                if (p.existing.some(x => x.caseId === id))
+                    continue;
+                if (!await this.write(op, ledger, `associate:${id}`, { method: 'POST', path: '/test/plan/relevance', effect: 'write', body: { planId: a.plan_id, ids: [id], request: { selectAll: false }, checked: false } }, mayWrite, async () => {
+                    const inventory = await this.ms.inventory(a.project_id, a.plan_id);
+                    const current = this.ms.membership(inventory), before = p.current_membership || p.before;
+                    const additions = current.members.filter((x) => !before.members.some((v) => v.id === x.id));
+                    if (inventory.cases.filter((x) => x.caseId === id && x.planId === a.plan_id && x.projectId === a.project_id).length !== 1)
+                        return false;
+                    if (!this.membershipMatches(current, before, true))
+                        return false;
+                    // 核查前面的成功步骤时，后续已发送步骤也可能已经生效；只接纳本操作确实发送过的成员。
+                    const sent = new Set(op.steps.filter(s => ['succeeded', 'unknown', 'in_flight'].includes(s.state)).map(s => s.name));
+                    if (additions.some((x) => {
+                        const source = p.sources.find((s) => s.id === x.caseId);
+                        return !sent.has(`associate:${x.caseId}`) || !source || x.refId !== source.snapshot.refId || x.versionId !== source.snapshot.versionId
+                            || current.members.filter((v) => v.caseId === x.caseId).length !== 1;
+                    }))
+                        return false;
+                    p.current_membership = current;
+                    return true;
+                }))
+                    return;
+            }
+            const inventory = await this.ms.inventory(a.project_id, a.plan_id);
+            ensure(a.case_ids.every((id) => inventory.cases.filter((x) => x.caseId === id).length === 1), 'RESULT_MISMATCH', '部分关联缺失或重复，未宣称全部成功');
+            op.result = { associations: inventory.cases.filter((x) => a.case_ids.includes(x.caseId)).map((x) => ({ case_id: x.caseId, plan_case_id: x.id, already_existed: p.existing.some((v) => v.id === x.id) })), expected_revision: session.tokens.revision('plan_membership', a.plan_id, this.ms.membership(inventory)) };
+        }
+        else if (op.action === 'record_case_result' || op.action === 'link_mantis_issue') {
+            if (!await this.comment(op, session, ledger, mayWrite))
+                return;
+            if (op.action === 'record_case_result') {
+                if (!await this.write(op, ledger, 'update_execution_result', { method: 'POST', path: '/test/plan/case/edit', effect: 'write', body: p.body }, mayWrite, async () => fieldsMatch(await this.ms.planCase(a.project_id, a.plan_id, a.plan_case_id), p.body)))
+                    return;
+            }
+            const current = await this.ms.planCase(a.project_id, a.plan_id, a.plan_case_id);
+            op.result = { ...p.subject, comment_id: p.comment_id, observed_executor: current.executor ?? null, status: current.status,
+                expected_revision: session.tokens.revision('case_execution', a.plan_case_id, executionSnapshot(current)),
+                ...(op.action === 'link_mantis_issue' ? { issue_id: a.issue_id, url: p.record.url, link_kind: 'external_reference', native_issue_id: null, external_validation: 'caller_supplied' } : {}) };
+        }
+        else if (op.action === 'complete_test_plan') {
+            if (!p.already_terminal && !await this.write(op, ledger, 'complete_plan', { method: 'POST', path: '/test/plan/edit', effect: 'write', body: { id: a.plan_id, status: 'Completed' } }, mayWrite, async () => ['Completed', 'Finished'].includes((await this.ms.plan(a.project_id, a.plan_id)).status)))
+                return;
+            const inventory = await this.ms.inventory(a.project_id, a.plan_id);
+            const summary = await this.ms.executionSummary(inventory, a.run_id);
+            ensure(summary.completion_ready && ['Completed', 'Finished'].includes(inventory.plan.status), 'RESULT_MISMATCH', '完成后的实时范围、结果或生命周期不能确认完整');
+            ensure(digest(this.ms.evidenceSnapshot(summary)) === digest(this.ms.evidenceSnapshot(p.execution_summary)), 'RESULT_MISMATCH', '计划结束时的执行证据已发生变化');
+            op.result = { plan_id: a.plan_id, lifecycle_status: inventory.plan.status, summary: a.summary, summary_storage: 'local_operation', execution_summary: summary,
+                completion_revision: session.tokens.revision('plan_completion', a.plan_id, this.ms.completionSnapshot(inventory, a.run_id, summary)) };
+        }
+        else if (op.action === 'generate_test_report') {
+            if (!await this.write(op, ledger, 'generate_report', { method: 'GET', path: `/test/plan/report/saveTestPlanReport/${segment(a.plan_id)}/MANUAL`, effect: 'write' }, mayWrite, async () => {
+                const currentPlan = await this.ms.plan(a.project_id, a.plan_id);
+                const lifecycle = { plan_id: a.plan_id, lifecycle_status_before: p.before.membership.plan.status, lifecycle_status: currentPlan.status,
+                    lifecycle_verified: ['Completed', 'Finished'].includes(currentPlan.status) };
+                op.result = lifecycle;
+                // 请求没有可靠确认时，单个相近报告也不能证明是该操作生成的。
+                const step = op.steps.find(x => x.name === 'generate_report');
+                if (step?.response !== 'success' || !step.started_at || !step.acknowledged_at)
+                    return false;
+                // creator 在列表中是显示名，服务端筛选参数才使用真实用户 ID。
+                const found = (await this.ms.all('/test/plan/report/list', { projectId: a.project_id, creator: session.user.id })).filter(x => x.testPlanId === a.plan_id && !p.before_report_ids.includes(x.id) && x.triggerMode === 'MANUAL' && x.createTime >= step.started_at - 60000 && x.createTime <= step.acknowledged_at + 60000);
+                if (found.length !== 1) {
+                    op.outcome = 'unknown';
+                    return false;
+                }
+                const report = await this.ms.report(a.project_id, found[0].id);
+                op.result = { ...this.ms.reportView(report), ...lifecycle, execution_summary: p.execution_summary, stage_report: !p.execution_summary.completion_ready, correlation: 'best_effort', created_by_this_operation_verified: false, content_verification: 'partial' };
+                const verification = reportSnapshotVerification(report.content.functionAllCases, p.report_snapshot);
+                if (!verification)
+                    return false;
+                Object.assign(op.result, verification);
+                return lifecycle.lifecycle_verified;
+            }))
+                return;
+        }
+        op.verified = true;
+        op.outcome = 'succeeded';
+        op.error = undefined;
+    }
+}