weaver-work-cli 0.1.5 → 0.1.7

package/dist/shortcuts/workflow/continuation.js

@@ -0,0 +1,508 @@
+import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { chmod, mkdir, readFile, readdir, unlink, writeFile } from 'node:fs/promises';
+import { homedir, hostname } from 'node:os';
+import { resolve } from 'node:path';
+import { workflowAlreadyAppliedError, workflowPartialError, workflowValidationError, } from './errors.js';
+const DEFAULT_TTL_MS = 10 * 60_000;
+/**
+ * 「上一次只抢到句柄、还没发出写入」的**安全重占宽限期**。
+ *
+ * 抢到句柄到把阶段推进到 `saving`（发出写入请求前）之间还有若干本地/只读步骤
+ * （只读校验、字段联动等），这段时间内不能让别人抢走，否则两次执行会同时写入。
+ * 超过宽限期仍停在 `claimed`、且记录里的进程已不存在 ⇒ 上一次确实死在写入之前，可安全重占。
+ */
+const RECLAIM_GRACE_MS = 30_000;
+/**
+ * 短句柄格式：`wc-` + 16 位十六进制（8 字节随机）。
+ *
+ * 句柄只是**本机不透明 id**，不是可解开的令牌——prepare 算好的载荷落在
+ * `<stateRoot>/state/workflow/continuation-pending/<句柄>`，apply 时按句柄取回。
+ * 这样模型只需要原样搬运 ~19 个字符，而不必复制数百字符的 base64 载荷。
+ *
+ * 安全：句柄来自模型入参，**必须先过这条严格正则**才能拼进文件路径，
+ * 否则 `wc-../../…` 之类的输入会造成路径穿越。
+ */
+const HANDLE_PATTERN = /^wc-[0-9a-f]{16}$/;
+/**
+ * 状态目录清理阈值（V12.1.23）：只有目录内条目数**超过**该值时，才顺手清掉已过期的条目。
+ *
+ * 背景（对齐 V11.3）：V11.3 的写门禁状态是**单文件** `session_maps.json`，直接覆盖写、
+ * 写路径**零删除**，所以不会触发宿主沙箱的「文件删除审批」。V12 的 continuation 是
+ * 「一句柄一文件」，只能靠删除让目录有界；而「每次写操作都顺手清理」会让**每一次**
+ * apply / prepare 都产生删除动作——宿主据此判定该命令要删文件，弹出提权确认，并把命令在
+ * 无沙箱下**重跑一次**（重跑撞一次性门禁 → 模型拿到 `ALREADY_APPLIED`）。
+ * 改成阈值触发后，日常写操作**零删除**；只有残留累积到阈值时才做一次集中清理。
+ */
+const SWEEP_THRESHOLD = 200;
+/** 目录条目数是否已达到需要清理的规模。读取失败视为「不需要」，本判断不产生副作用。 */
+async function shouldSweep(dir) {
+    try {
+        return (await readdir(dir)).length > SWEEP_THRESHOLD;
+    }
+    catch {
+        return false;
+    }
+}
+function stateRoot(ctx) {
+    const configured = ctx?.config?.path();
+    if (configured)
+        return resolve(configured, '..');
+    return process.env.WEAVER_WORK_CLI_HOME || process.env.WORK_CLI_HOME || resolve(homedir(), '.weaver-work-cli');
+}
+/** 旧版自包含令牌的签名密钥（仅兼容路径在用：verify 旧令牌 / 验证其签名）。 */
+async function loadKey(ctx) {
+    const keysDir = resolve(stateRoot(ctx), 'keys');
+    const filename = resolve(keysDir, 'workflow-continuation.key');
+    await mkdir(keysDir, { recursive: true, mode: 0o700 });
+    if (existsSync(filename))
+        return readFile(filename);
+    const key = randomBytes(32);
+    try {
+        await writeFile(filename, key, { flag: 'wx', mode: 0o600 });
+        if (process.platform !== 'win32')
+            await chmod(filename, 0o600).catch(() => undefined);
+        return key;
+    }
+    catch {
+        return readFile(filename);
+    }
+}
+function signature(payload, key) {
+    return createHmac('sha256', key).update(payload).digest('base64url');
+}
+/** 引用的稳定指纹（sha256），用于一次性消费去重——不依赖签名 key，跨进程一致。 */
+function referenceFingerprint(reference) {
+    return createHash('sha256').update(reference).digest('hex');
+}
+/** 托管中的续跑载荷目录（与 search-index.json 同层 state/workflow/）。 */
+function pendingDir(ctx) {
+    return resolve(stateRoot(ctx), 'state', 'workflow', 'continuation-pending');
+}
+/** 已消费续跑引用的落盘目录（与 search-index.json 同层 state/workflow/）。 */
+function consumedDir(ctx) {
+    return resolve(stateRoot(ctx), 'state', 'workflow', 'continuation-consumed');
+}
+/** 清理已过期的消费记录，避免目录无限增长。兼容旧版「纯数字 expiresAt」标记与新版 JSON 标记。 */
+async function sweepConsumed(dir) {
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return;
+    }
+    const now = Date.now();
+    for (const name of names) {
+        const file = resolve(dir, name);
+        try {
+            const content = await readFile(file, 'utf8');
+            let expiresAt = Number(content);
+            if (!Number.isFinite(expiresAt)) {
+                try {
+                    expiresAt = Number(JSON.parse(content)?.expiresAt);
+                }
+                catch {
+                    /* 无法解析：保守留档，不删 */
+                }
+            }
+            if (Number.isFinite(expiresAt) && expiresAt < now)
+                await unlink(file);
+        }
+        catch {
+            /* 单文件清理失败不影响主流程 */
+        }
+    }
+}
+/** 读取消费标记；返回 null 表示「未被消费」。旧版纯数字标记归一化为 `{state:'unknown'}`。 */
+async function readConsumedMarker(ctx, reference) {
+    const file = resolve(consumedDir(ctx), referenceFingerprint(reference));
+    let raw;
+    try {
+        raw = await readFile(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            return parsed;
+    }
+    catch {
+        /* 旧版格式（纯数字）走下面归一化 */
+    }
+    return { state: 'unknown' };
+}
+/** 标记里记录的进程是否还活着（同 hostname 才判；没有 pid 或判定不了时一律按"还活着"保守处理）。 */
+function markerProcessAlive(marker) {
+    const pid = Number(marker.pid);
+    if (!Number.isFinite(pid) || pid <= 0)
+        return true;
+    if (typeof marker.hostname === 'string' && marker.hostname && marker.hostname !== hostname())
+        return true;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error?.code !== 'ESRCH';
+    }
+}
+function replayOf(marker) {
+    let state = 'unknown';
+    if (marker.state === 'succeeded') {
+        state = 'succeeded';
+    }
+    else if (marker.state === 'running') {
+        // V12.1.21 起标记带 stage；更早的标记（无 stage）无法区分"已发出写入"与"刚抢到"，保守按 saving 处理。
+        state = marker.stage === 'claimed' ? 'claimed'
+            : marker.stage === 'committed' ? 'committed'
+                : 'saving';
+    }
+    const stage = marker.stage === 'claimed' || marker.stage === 'saving' || marker.stage === 'committed'
+        ? marker.stage
+        : undefined;
+    return {
+        state,
+        ...(stage ? { stage } : {}),
+        ...(typeof marker.operation === 'string' ? { operation: marker.operation } : {}),
+        ...(Number.isFinite(Number(marker.consumedAt)) ? { consumedAt: Number(marker.consumedAt) } : {}),
+        ...(Number.isFinite(Number(marker.finishedAt)) ? { finishedAt: Number(marker.finishedAt) } : {}),
+        ...(typeof marker.requestId === 'string' && marker.requestId ? { requestId: marker.requestId } : {}),
+        ...(state === 'succeeded' ? { result: marker.result ?? null } : {}),
+    };
+}
+/**
+ * 引用已被占用时的错误：**上一次执行成功** → 幂等重放（调度层转成功信封）；否则维持「已使用」语义。
+ *
+ * 上一次的状态必须并入文案——旧文案默认「已使用＝上次失败了」，直接诱导模型重跑 Prepare，
+ * 而重跑在批量门禁（写入成功后条目已不在可执行列表）里必然失败，是一条死路。
+ */
+export function continuationReplayError(replay, expectedOperation) {
+    const operation = replay.operation ?? expectedOperation;
+    if (replay.state === 'succeeded') {
+        return workflowAlreadyAppliedError(operation, replay);
+    }
+    if (replay.state === 'committed') {
+        // 服务端已返回成功回执、只是没来得及回写结果：同样属"已经做过"，按幂等回报。
+        return workflowAlreadyAppliedError(operation, replay);
+    }
+    if (replay.state === 'saving') {
+        // 写入请求已发出但结果未知：一律按"结果不确定"处理（先只读核对，禁止重复提交）。
+        // 恢复路径按命令形态分述：单命令（batchSubmit）没有 Prepare 可重跑，只能等幂等窗口过去后原样重跑。
+        const recovery = /Apply$/u.test(operation)
+            ? '确认未生效后再重跑对应的 Prepare 获取新句柄。'
+            : '确认未生效后，等本次写入的幂等保护窗口过去（约 1 分钟）再原样重跑同一条命令（同一批 requestId 在窗口内会被拦住）。';
+        return workflowPartialError('该 continuation 对应的上一次执行**已经发出写入请求，但结果未确认**（进程被中止或回执丢失），'
+            + '本次未执行、也不要重复提交。请先只读核对（如 workflow.search --category done --requestId <目标ID>'
+            + '，或 workflow.search --category mine 看是否已出现目标条目）确认真实状态，'
+            + recovery, replay, { stage: 'continuation_replay', ...replay });
+    }
+    if (replay.state === 'claimed') {
+        // 只抢到句柄、未发出任何写入：并发的另一次执行正在占用，等它结束再重试即可。
+        return workflowValidationError('continuation_busy', '该 continuation 正被另一次执行占用（上一次只抢到句柄、尚未发出写入请求），本次未执行。'
+            + '请稍后重试同一条命令；若上一次执行其实已经完成，直接看返回结果即可。', replay);
+    }
+    return workflowValidationError('continuation_consumed', 'continuation 已使用（一次性），禁止重复提交。若怀疑上一次没生效，请先只读核对目标流程是否已存在'
+        + '（workflow.search --category done/mine --requestId <目标ID>），确认未生效再重跑对应的 Prepare。', replay);
+}
+/** 清理已过期但仍未被 apply 消费的托管载荷，避免 prepare 后不了了之的调用累积。 */
+async function sweepPending(dir) {
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return;
+    }
+    const now = Date.now();
+    for (const name of names) {
+        const file = resolve(dir, name);
+        try {
+            const value = JSON.parse(await readFile(file, 'utf8'));
+            const expiresAt = Number(value?.expiresAt);
+            if (Number.isFinite(expiresAt) && expiresAt < now)
+                await unlink(file);
+        }
+        catch {
+            /* 单文件清理失败不影响主流程 */
+        }
+    }
+}
+/** 按句柄读取托管载荷；文件不在 = 已被消费 / 已过期 / 不是本机签发的句柄。 */
+async function readPendingPayload(ctx, handle) {
+    let content;
+    try {
+        content = await readFile(resolve(pendingDir(ctx), handle), 'utf8');
+    }
+    catch {
+        throw workflowValidationError('continuation_expired', 'continuation 在本机状态目录中不存在（已被使用、已过期，或不是本机签发的句柄）。'
+            + '请重新执行对应的 Prepare 命令后再 apply，不要复用旧句柄。');
+    }
+    try {
+        return JSON.parse(content);
+    }
+    catch {
+        throw workflowValidationError('continuation_invalid', 'continuation 本机载荷无法解析，请重新执行对应的 Prepare 命令');
+    }
+}
+/**
+ * 兼容 V12.1.11 及更早版本签发的**自包含签名令牌**（`base64url(JSON).HMAC-SHA256`）：
+ * 升级前已在会话里拿到的旧令牌仍可用，不必重新 prepare。新会话一律走短句柄。
+ */
+async function verifyLegacyToken(ctx, token) {
+    const [body, provided] = token.split('.');
+    const expected = signature(body, await loadKey(ctx));
+    const valid = typeof provided === 'string'
+        && provided.length === expected.length
+        && timingSafeEqual(Buffer.from(provided), Buffer.from(expected));
+    if (!valid)
+        throw workflowValidationError('continuation_invalid', 'continuation 签名校验失败');
+    try {
+        return JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw workflowValidationError('continuation_invalid', 'continuation 内容无法解析');
+    }
+}
+/**
+ * 尝试**安全重占**一个"只抢到句柄、还没发出写入请求"的标记。
+ *
+ * 返回 `null` 表示重占成功（调用方可继续）；返回 replay 表示仍被占用（不得写入）。
+ *
+ * 三条同时成立才允许重占：① 阶段停在 `claimed`；② 距占用已超过 `RECLAIM_GRACE_MS`；
+ * ③ 记录里的进程已经不在了。⇒ 上一次确定死在"发出写入请求之前"，重占不会造成重复写入。
+ *
+ * 原子性不靠 `wx`（此时文件已存在）：先写入自己的 `owner`，再**回读校验 owner 是否还是自己**——
+ * 并发重占时只有最后一个写入者能读到自己的 owner，其余全部退出，不存在"先判存在再写"的窗口。
+ */
+async function tryReclaim(ctx, reference, marker, record) {
+    const age = Date.now() - Number(marker.consumedAt);
+    const claimable = marker.state === 'running' && marker.stage === 'claimed';
+    if (!claimable || !Number.isFinite(age) || age < RECLAIM_GRACE_MS || markerProcessAlive(marker)) {
+        return replayOf(marker);
+    }
+    const file = resolve(consumedDir(ctx), referenceFingerprint(reference));
+    try {
+        await writeFile(file, JSON.stringify(record), { mode: 0o600 });
+    }
+    catch {
+        return replayOf(marker);
+    }
+    const after = await readConsumedMarker(ctx, reference);
+    if (after && after.owner === record.owner)
+        return null;
+    return replayOf(after ?? marker);
+}
+/**
+ * **有界幂等窗口内的过期接管**：把一条「已确认成功、但幂等窗口已过」的消费标记原子换成本次的标记。
+ *
+ * 只在调用方**显式声明了窗口**（`consume(..., ttlMs)`）时才会被调用，且只接管 `succeeded` 标记：
+ * `saving`（写入已发出、结果未知）与 `running/committed`（服务端已回执但本机没落结果）都**不在**
+ * 接管范围内——它们永不放行重放；`running/claimed`（并发占用中）交给 `tryReclaim` 按
+ * 「宽限期 + 进程已死」判定，不在这里抢。
+ *
+ * 返回 true 表示本次已接管（调用方可继续写入）。原子性同 `tryReclaim`：先写入自己的 owner，
+ * 再**回读校验 owner 仍是自己**——并发接管时只有最后一个写入者能读到自己，其余按"仍被占用"退出。
+ */
+async function tryTakeoverExpiredWindow(ctx, reference, marker, record) {
+    const expiresAt = Number(marker.expiresAt);
+    if (!Number.isFinite(expiresAt) || expiresAt >= Date.now())
+        return false;
+    if (marker.state !== 'succeeded')
+        return false;
+    const file = resolve(consumedDir(ctx), referenceFingerprint(reference));
+    try {
+        await writeFile(file, JSON.stringify(record), { mode: 0o600 });
+    }
+    catch {
+        return false;
+    }
+    const after = await readConsumedMarker(ctx, reference);
+    return Boolean(after && after.owner === record.owner);
+}
+export function createWorkflowContinuationSigner(ctx) {
+    return {
+        async issue(payload, ttlMs = DEFAULT_TTL_MS) {
+            const issuedAt = Date.now();
+            const ttl = Number.isFinite(ttlMs) ? Math.trunc(ttlMs) : DEFAULT_TTL_MS;
+            const record = JSON.stringify({ ...payload, issuedAt, expiresAt: issuedAt + ttl });
+            const dir = pendingDir(ctx);
+            await mkdir(dir, { recursive: true, mode: 0o700 });
+            // `wx` 保证不覆盖已存在的载荷；极小概率撞名时换一个句柄重试。
+            for (let attempt = 0; attempt < 5; attempt += 1) {
+                const handle = `wc-${randomBytes(8).toString('hex')}`;
+                try {
+                    await writeFile(resolve(dir, handle), record, { flag: 'wx', mode: 0o600 });
+                    if (await shouldSweep(dir))
+                        await sweepPending(dir);
+                    return handle;
+                }
+                catch (error) {
+                    if (error?.code !== 'EEXIST') {
+                        throw workflowValidationError('continuation_unavailable', `本机状态目录不可写，无法托管 continuation：${dir}`);
+                    }
+                }
+            }
+            throw workflowValidationError('continuation_unavailable', '签发 continuation 失败（句柄连续冲突），请重试');
+        },
+        async verify(reference, expectedOperation) {
+            if (typeof reference !== 'string' || !reference.trim()) {
+                throw workflowValidationError('continuation_invalid', 'continuation 无效（缺少入参）');
+            }
+            // 引用两侧可能被模型带上空白，统一归一化，保证 verify 与 consume 的指纹一致。
+            const ref = reference.trim();
+            if (ref.startsWith('wc-') && !HANDLE_PATTERN.test(ref)) {
+                throw workflowValidationError('continuation_invalid', 'continuation 句柄格式无效：必须原样回传 Prepare 返回的 wc-… 值，禁止手工构造或拼接。');
+            }
+            // 一次性消费检查放在最前：必须先看消费标记，才能把重放正确判定为「已使用」而不是「不存在」。
+            // 标记里带着上一次的执行阶段与结果，于是：已成功/已创建 → 幂等回报（ALREADY_APPLIED）；
+            // 已发出写入但未确认 → 按"结果不确定"处理；只抢到句柄未发出写入 → 允许继续（由 consume 安全重占）。
+            const marker = await readConsumedMarker(ctx, ref);
+            if (marker) {
+                const replay = replayOf(marker);
+                if (replay.state !== 'claimed')
+                    throw continuationReplayError(replay, expectedOperation);
+            }
+            const handle = HANDLE_PATTERN.test(ref);
+            const value = handle
+                ? await readPendingPayload(ctx, ref)
+                : await verifyLegacyToken(ctx, ref);
+            if (value.operation !== expectedOperation) {
+                throw workflowValidationError('continuation_mismatch', 'continuation 不属于当前操作');
+            }
+            if (!Number.isSafeInteger(value.expiresAt) || value.expiresAt < Date.now()) {
+                // 过期句柄的托管载荷**不在这里删**：写路径保持零删除动作（见 SWEEP_THRESHOLD 注释），
+                // 过期载荷由 issue 时阈值触发的 sweepPending 统一回收。
+                throw workflowValidationError('continuation_expired', 'continuation 已过期');
+            }
+            return value;
+        },
+        async consume(reference, operation, ttlMs) {
+            if (typeof reference !== 'string' || !reference.trim())
+                return { claimed: true };
+            const ref = reference.trim();
+            const handle = HANDLE_PATTERN.test(ref);
+            // 有界幂等窗口：>0 表示调用方按"确定性键 + 保护窗口"使用，窗口过期后允许接管已成功的旧标记。
+            const window = Number.isFinite(ttlMs) && Number(ttlMs) > 0 ? Math.trunc(Number(ttlMs)) : 0;
+            let expiresAt = Date.now() + (window || DEFAULT_TTL_MS);
+            let prepared;
+            try {
+                const value = handle
+                    ? JSON.parse(await readFile(resolve(pendingDir(ctx), ref), 'utf8'))
+                    : JSON.parse(Buffer.from(ref.split('.')[0], 'base64url').toString('utf8'));
+                // 有界窗口优先：句柄自带的 expiresAt 是 prepare 载荷的有效期，与"幂等窗口"不是一回事，
+                // 因此传了窗口就不再让载荷覆盖（确定性键本来也没有载荷）。
+                if (!window && Number.isSafeInteger(value.expiresAt))
+                    expiresAt = value.expiresAt;
+                // 留档"这次准备写什么"：既是审计线索，也让"未确认成功"的重放能报出目标范围。
+                prepared = value.prepared;
+            }
+            catch {
+                /* 载荷缺失/解析失败：沿用默认 TTL，仍会落一条消费记录防重放 */
+            }
+            const dir = consumedDir(ctx);
+            const file = resolve(dir, referenceFingerprint(ref));
+            const record = {
+                state: 'running',
+                stage: 'claimed',
+                ...(operation ? { operation } : {}),
+                // owner/pid/hostname 只服务于"上一次死在写入之前"的安全重占判定（见 tryReclaim）。
+                owner: randomUUID(),
+                pid: process.pid,
+                hostname: hostname(),
+                consumedAt: Date.now(),
+                expiresAt,
+                ...(prepared === undefined ? {} : { prepared }),
+            };
+            try {
+                await mkdir(dir, { recursive: true, mode: 0o700 });
+                // 抢占判据 = 这次 `wx` 创建本身：抢不到（EEXIST）说明已被另一次执行占用，调用方**不得再写入**。
+                await writeFile(file, JSON.stringify(record), { flag: 'wx', mode: 0o600 });
+            }
+            catch (error) {
+                if (error?.code === 'EEXIST') {
+                    const existing = await readConsumedMarker(ctx, ref);
+                    if (!existing)
+                        return { claimed: false, previous: { state: 'unknown' } };
+                    // 有界窗口：窗口已过且上一次已确认成功 → 本次原子接管，允许第二次**合法**提交。
+                    if (window && await tryTakeoverExpiredWindow(ctx, ref, existing, record)) {
+                        if (await shouldSweep(dir))
+                            await sweepConsumed(dir);
+                        return { claimed: true };
+                    }
+                    const blocker = await tryReclaim(ctx, ref, existing, record);
+                    if (!blocker)
+                        return { claimed: true };
+                    return { claimed: false, previous: blocker };
+                }
+                // 目录不可写：本机无法留痕，只能沿用旧行为放行（无标记可防重放，属环境限制而非参数问题）。
+            }
+            // 注意：**这里不再删除托管载荷**。载荷要留到重放判定真的需要它的时候
+            // （上一次只抢到句柄、死在写入之前时，允许用同一句柄继续；删了就只能重跑 Prepare）。
+            // 清理时机：**只在已消费标记累积超过阈值时**顺手清一次（见 SWEEP_THRESHOLD 注释），
+            // 而不是每次写操作都清——日常写路径必须保持零删除动作。
+            if (await shouldSweep(dir))
+                await sweepConsumed(dir);
+            return { claimed: true };
+        },
+        async markStage(reference, stage, extra) {
+            if (typeof reference !== 'string' || !reference.trim())
+                return;
+            const file = resolve(consumedDir(ctx), referenceFingerprint(reference.trim()));
+            let raw;
+            try {
+                raw = await readFile(file, 'utf8');
+            }
+            catch {
+                // 本机没有标记（状态目录不可写等环境限制）：不阻断，沿用"无痕迹"的旧行为。
+                return;
+            }
+            let marker;
+            try {
+                marker = JSON.parse(raw);
+            }
+            catch {
+                // 旧版纯数字标记：没有可写阶段的位置，跳过。
+                return;
+            }
+            if (!marker || typeof marker !== 'object' || Array.isArray(marker))
+                return;
+            try {
+                await writeFile(file, JSON.stringify({ ...marker, stage, ...(extra ?? {}) }), { mode: 0o600 });
+            }
+            catch {
+                // 有标记却写不进阶段 ⇒ 记录不了进度就不能发出写入请求（否则会留下无法判定的一次性写入）。
+                throw workflowValidationError('continuation_unavailable', '本机无法记录本次写入的进度（状态目录不可写），为避免留下无法判定结果的一次性写入，已停止本次操作。');
+            }
+        },
+        async settle(reference, result, operation) {
+            if (typeof reference !== 'string' || !reference.trim())
+                return;
+            const ref = reference.trim();
+            const file = resolve(consumedDir(ctx), referenceFingerprint(ref));
+            try {
+                const raw = await readFile(file, 'utf8');
+                const marker = JSON.parse(raw);
+                // 旧版标记（纯数字）没有承载执行结果的位置，保持原样不动。
+                if (marker && typeof marker === 'object' && !Array.isArray(marker)) {
+                    await writeFile(file, JSON.stringify({
+                        ...marker,
+                        state: 'succeeded',
+                        ...(operation ? { operation } : {}),
+                        finishedAt: Date.now(),
+                        result: result ?? null,
+                    }), { mode: 0o600 });
+                }
+            }
+            catch {
+                /* 回写失败不影响命令结果：重放只会退化成「未确认」提示 */
+            }
+            // 写入已确认成功后**不再删除托管载荷**（V11.3 对齐：写路径零删除动作）。
+            // 原因：删除会让宿主沙箱判定该命令要删文件 → 弹提权确认 → 命令无沙箱重跑一次。
+            // 载荷保留无害：消费标记里本就存着同一份 prepared 载荷，且 verify 在读到消费标记后
+            // 即短路（不会回读 pending）；过期载荷由 issue 时阈值触发的 sweepPending 统一回收。
+        },
+    };
+}

package/dist/shortcuts/workflow/endpoints.js

@@ -0,0 +1,149 @@
+/**
+ * E10 工作流接口路径表。
+ *
+ * 来源：原 Python skill 的 `scripts/e10_workflow.py`（`DEFAULT_ENDPOINTS`）与
+ * `scripts/e10_workflow_create.py`（`ENDPOINTS`）。只保留 CLI 侧真正需要调用的路径；
+ * Python 内部用于调试的裸接口能力（raw-post / raw-get）不迁移。
+ */
+/** 流程查询与操作（原 e10_workflow.py DEFAULT_ENDPOINTS） */
+export const WORKFLOW_ENDPOINTS = {
+    /** 记忆：读取用户记忆提示词 */
+    MEMORY_PROMPT: '/api/ai/application/memory/buildAgentMemoryPrompt',
+    /** 记忆：保存/抽取用户记忆 */
+    MEMORY_EXTRACT: '/api/ai/application/memory/agentMemoryExtract',
+    /** 流程路径浏览按钮：按关键字解析工作流 */
+    WORKFLOW_PATH_BROWSER: '/api/workflow/pathdef/common/browser/complete/workflowPathBrowser',
+    /** 流程大类浏览按钮：解析大分类 / tabid */
+    WORKFLOW_TYPE_BROWSER: '/api/workflow/pathdef/common/browser/complete/workflowPathTypeBrowser',
+    /** 资源浏览按钮（人员/角色/群组等） */
+    RESOURCE_BROWSER: '/api/workflow/core/common/browser/complete/resource',
+    /** 部门浏览按钮 */
+    DEPT_BROWSER: '/api/hrm/common/browser/complete/department',
+    /** 分部浏览按钮 */
+    SUBCOMPANY_BROWSER: '/api/hrm/common/browser/complete/subcompany',
+    /** 群组浏览按钮（共享对象 group；来源：Python EMPLOYEE_SCOPE_BROWSER_TYPES group→channel） */
+    GROUP_BROWSER: '/api/hrm/common/browser/complete/channel',
+    /** 角色浏览按钮（共享对象 role） */
+    ROLE_BROWSER: '/api/hrm/common/browser/complete/role',
+    /** 岗位浏览按钮（共享对象 position） */
+    POSITION_BROWSER: '/api/hrm/common/browser/complete/position',
+    /** 人员浏览按钮（共享对象 user；Python EmployeeScope module=hrm） */
+    HRM_RESOURCE_BROWSER: '/api/hrm/common/browser/complete/resource',
+    /** 节点浏览按钮 */
+    NODE_BROWSER: '/api/workflow/pathdef/common/browser/data/workflowPathNodeBrowser',
+    /** 字段选项浏览按钮 */
+    FIELD_OPTION_BROWSER: '/api/workflow/core/common/browser/complete/field_option',
+    /** 流程列表查询（带表单字段） */
+    SEARCH_AD_WITH_FORM: '/api/workflow/list/searchad/getListSearchAdWithForm',
+    /** 查询动态依赖数据（紧急程度等） */
+    QUERY_DEPENDENCY: '/api/workflow/list/smartQuery/getQueryDependency',
+    /** 名称转 ID（系统查询字段 / 浏览按钮字段） */
+    RELATE_NAME2ID: '/api/workflow/list/smartQuery/relateName2Id',
+    /** 待办总数 / 列表 */
+    TODO_TOTAL: '/api/workflow/list/total/getTodoListTotal',
+    TODO_LIST: '/api/workflow/list/data/getTodoListData',
+    /** 待办分组计数（按工作流/参与节点/参与身份三元组） */
+    TODO_GROUP_STAT: '/api/workflow/list/count/getTodoGroupCount',
+    /** 已办总数 / 列表 */
+    DONE_TOTAL: '/api/workflow/list/total/getDoneListTotal',
+    DONE_LIST: '/api/workflow/list/data/getDoneListData',
+    /** 我发起总数 / 列表 */
+    MINE_TOTAL: '/api/workflow/list/total/getMineListTotal',
+    MINE_LIST: '/api/workflow/list/data/getMineListData',
+    /** 全部总数 / 列表 */
+    ALL_TOTAL: '/api/workflow/list/total/getAllListTotal',
+    ALL_LIST: '/api/workflow/list/data/getAllListData',
+    /** 批量操作专用查询（可执行批量提交/催办/置已读等的待办数据） */
+    TODO_TOTAL_BATCH_SUBMIT: '/api/workflow/list/total/getTodoListTotal/batch/batchSubmit',
+    TODO_LIST_BATCH_SUBMIT: '/api/workflow/list/data/getTodoListData/batch/batchSubmit',
+    TODO_TOTAL_BATCH_URGE: '/api/workflow/list/total/getTodoListTotal/batch/batchUrge',
+    TODO_LIST_BATCH_URGE: '/api/workflow/list/data/getTodoListData/batch/batchUrge',
+    TODO_TOTAL_BATCH_READ: '/api/workflow/list/total/getTodoListTotal/batch/batchRead',
+    TODO_LIST_BATCH_READ: '/api/workflow/list/data/getTodoListData/batch/batchRead',
+    TODO_TOTAL_BATCH_SHARE: '/api/workflow/list/total/getTodoListTotal/batch/batchShare',
+    TODO_LIST_BATCH_SHARE: '/api/workflow/list/data/getTodoListData/batch/batchShare',
+    TODO_TOTAL_BATCH_FORWARD: '/api/workflow/list/total/getTodoListTotal/batch/batchForward',
+    TODO_LIST_BATCH_FORWARD: '/api/workflow/list/data/getTodoListData/batch/batchForward',
+    TODO_TOTAL_BATCH_REJECT: '/api/workflow/list/total/getTodoListTotal/batch/batchReject',
+    TODO_LIST_BATCH_REJECT: '/api/workflow/list/data/getTodoListData/batch/batchReject',
+    /** 流程详情 / 流转日志 */
+    REQUEST_DETAIL: '/api/workflow/core/paService/v1/getWorkflowRequest',
+    REQUEST_LOG: '/api/workflow/core/paService/v1/getRequestLog',
+    /** 单条流程操作 */
+    SUBMIT_REQUEST: '/api/workflow/core/paService/v1/submitRequest',
+    REJECT_REQUEST: '/api/workflow/core/paService/v1/rejectRequest',
+    TRANSFER_REQUEST: '/api/workflow/core/paService/v1/doTurnTodo',
+    DELEGATE_REQUEST: '/api/workflow/core/paService/v1/manualAgentRequest',
+    FORWARD_REQUEST: '/api/workflow/core/paService/v1/forward',
+    CC_REQUEST: '/api/workflow/core/paService/v1/manualCC',
+    ADD_REVIEW_REQUEST: '/api/workflow/core/paService/v1/addSignOperator',
+    BATCH_SUBMIT: '/api/workflow/core/paService/v1/batchSubmit',
+    FORCE_DRAW_BACK: '/api/workflow/core/paService/v1/doForceDrawBack',
+    FORCE_OVER: '/api/workflow/core/paService/v1/doForceOver',
+    CONSUL: '/api/workflow/core/paService/v1/consul',
+    CONSUL_REPLY: '/api/workflow/core/paService/v1/consulReply',
+    DELETE_REQUEST: '/api/workflow/core/paService/v1/deleteRequest',
+    SUPERVISE: '/api/workflow/core/paService/v1/requestSupervise',
+    BATCH_SUPERVISE: '/api/workflow/core/flow/batchSupervise',
+    BATCH_READ: '/api/workflow/list/operate/doBatchRead',
+    /** 流程共享 */
+    SHARE_ADD_FORM: '/api/workflow/list/share/getAddShareForm',
+    SHARE_ADD: '/api/workflow/list/share/addRequestShare2',
+    /** 批量转发 */
+    BATCH_FORWARD: '/api/workflow/core/flow/operate/batchForward',
+    FORWARD_ALLOW_ALL: '/api/workflow/core/flow/operate/getReceiverAllowAllConfig',
+    /** 批量退回 */
+    BATCH_REJECT: '/api/workflow/core/flow/operate/batchReject',
+    /** 流程节点符合性校验（发起前字段校验） */
+    CONFORMANCE_SET: '/api/bs/workflow/pathdef/nodeConformance/getConformanceSetByVerification',
+    VERIFICATION_REQUEST_DATA: '/api/workflow/core/verification/getRequestDataByRequestId',
+    VERIFICATION_CONDITION_RULE: '/api/bs/workflow/pathdef/nodeConformance/verificationConditionRule',
+};
+/** 表单 / 发起流程（原 e10_workflow_create.py ENDPOINTS） */
+export const FORM_ENDPOINTS = {
+    /** 可发起工作流列表 */
+    workflowCreateList: '/api/workflow/list/newflow/getNewFlowListData',
+    /** 发起流程：基础参数 */
+    loadBase: '/api/workflow/core/flowPage/loadBaseParam',
+    /** 发起流程：页面框架参数 */
+    loadFrame: '/api/workflow/core/flowPage/loadFrameParam',
+    /** 发起流程：次要信息（安全级别默认值等） */
+    loadMinor: '/api/workflow/core/flowPage/loadMinorInfo',
+    /** 表单布局 */
+    formLayout: '/api/workflow/core/form/core/getFormLayout',
+    /** 表单数据 + 布局（修改已存在流程时用） */
+    formDataAndLayout: '/api/workflow/core/form/core/getFormDataAndLayout',
+    /** 名称转 ID（AI 字段映射） */
+    nameToId: '/api/ai/chat/fieldMapping/getRelateData',
+    /** 字段联动 */
+    fdLinkage: '/api/workflow/core/form/linkage/executeFdLinkage',
+    /** 保存表单数据 */
+    save: '/api/workflow/core/form/core/saveFormData',
+    /** 发起流程 */
+    create: '/api/workflow/core/flow/create',
+    /** 提交（复用查询侧同一路径） */
+    submit: '/api/workflow/core/paService/v1/submitRequest',
+    /** 节点符合性校验 */
+    conformanceSet: '/api/bs/workflow/pathdef/nodeConformance/getConformanceSetByVerification',
+    verificationRequestData: '/api/workflow/core/verification/getRequestDataByRequestId',
+    verificationConditionRule: '/api/bs/workflow/pathdef/nodeConformance/verificationConditionRule',
+    /** 租户级文件上传设置（单文件大小上限 + 格式黑白名单） */
+    tenantSetting: '/api/file/tenant/setting',
+};
+/** 表单接口公共 query 参数（原 AJAX_QUERY） */
+export const AJAX_QUERY = { sf_request_type: 'ajax' };
+/**
+ * 表单接口路径：按 relateType 切换 module 前缀。
+ *
+ * `path` 必须是**完整路径**（传 `FORM_ENDPOINTS.xxx`）；传短 key 会因匹配不到
+ * `/api/workflow/core/` 而原样返回，导致请求路径非法。
+ *
+ * - WEA_FORM（工作流表单）→ 保持 `FORM_ENDPOINTS` 默认地址
+ * - WEA_EBUILDER（建模表单）→ `/api/workflow/core/` 段替换为 `/api/ebuilder/flow/`
+ */
+export function formApiUrl(path, relateType) {
+    if (String(relateType || '').trim() === 'WEA_EBUILDER') {
+        return path.replace('/api/workflow/core/', '/api/ebuilder/flow/');
+    }
+    return path;
+}