weaver-work-cli 0.1.40 → 0.1.44

package/dist/shortcuts/reception/operations/render-assets.js

@@ -0,0 +1,184 @@
+import { spawnSync, execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { PYTHON_CACHE_TTL_MS } from '../constants.js';
+import { receptionBusinessError, receptionEnvironmentError } from '../errors.js';
+import { ensureDir, mtimeMs, readJson, writeJson } from './shared.js';
+import { skillRootFromSnapshot } from './snapshot.js';
+/**
+ * docx / md 渲染外壳。
+ *
+ * 边界：这里只负责「找到 python、找到 render.py、解析它吐的 JSON」，
+ * 产物口径全在技能包的 `scripts/render.py` 里（模板也在技能包 `assets/` 下，由 py 自己定位）。
+ * CLI 不打包 render.py，也不打包模板——字段与版式调整不该触发 CLI 发版。
+ */
+const PYTHON_CACHE_FILE = 'python.json';
+let pythonCache;
+function runSync(file, args, options = {}) {
+    const result = spawnSync(file, args, { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, ...options });
+    return {
+        stdout: String(result.stdout || ''),
+        stderr: String(result.stderr || ''),
+        status: result.status,
+    };
+}
+function runAsync(file, args) {
+    return new Promise((resolve) => {
+        execFile(file, args, { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
+            resolve({
+                stdout: String(stdout || ''),
+                stderr: String(stderr || ''),
+                status: error ? (typeof error.code === 'number' ? error.code : 1) : 0,
+            });
+        });
+    });
+}
+/** 从混杂输出里取最后一个合法 JSON（render.py 可能先打印日志）。 */
+function lastJsonLine(text) {
+    const lines = String(text || '').split(/\r?\n/).filter((line) => line.trim().startsWith('{'));
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        try {
+            return JSON.parse(lines[index]);
+        }
+        catch {
+            // 继续往上找
+        }
+    }
+    return null;
+}
+/**
+ * 依次探测 RECEPTION_PY / python3 / python，要求能 `import docx`。
+ * 探测结果落盘 7 天省掉每次 0.3~1s；磁盘缓存也要能真跑起来才认（避免升级后命中死路径）。
+ */
+export function pickPython(stateDir) {
+    if (pythonCache !== undefined)
+        return pythonCache;
+    if (process.env.RECEPTION_PY) {
+        pythonCache = process.env.RECEPTION_PY;
+        return pythonCache;
+    }
+    const cachePath = join(stateDir, PYTHON_CACHE_FILE);
+    const disk = readJson(cachePath);
+    if (disk?.py && Date.now() - Number(disk.at || 0) < PYTHON_CACHE_TTL_MS) {
+        if (runSync(disk.py, ['-c', 'import docx'], { stdio: 'ignore' }).status === 0) {
+            pythonCache = disk.py;
+            return pythonCache;
+        }
+    }
+    for (const candidate of ['python3', 'python', 'py']) {
+        const args = candidate === 'py' ? ['-3', '-c', 'import docx'] : ['-c', 'import docx'];
+        if (runSync(candidate, args, { stdio: 'ignore' }).status === 0) {
+            pythonCache = candidate;
+            try {
+                writeJson(cachePath, { py: candidate, at: Date.now() });
+            }
+            catch {
+                // 缓存写不进不阻断
+            }
+            return candidate;
+        }
+    }
+    pythonCache = null;
+    return null;
+}
+/** 测试用：清掉进程内缓存。 */
+export function resetPythonCache() {
+    pythonCache = undefined;
+}
+/**
+ * 定位 render.py。优先级：显式参数 → 环境变量 → 技能包内固定相对位置。
+ *
+ * 技能包布局固定为 `<skill>/scripts/render.py` + `<skill>/data/fields-snapshot.json`，
+ * 因此拿到快照路径就能反推脚本位置，调用方不必传两个参数。
+ */
+export function resolveRenderPy(explicitPath = '', snapshotPath = '') {
+    const candidates = [
+        explicitPath,
+        process.env.RECEPTION_RENDER_PY || '',
+        snapshotPath ? join(skillRootFromSnapshot(snapshotPath), 'scripts', 'render.py') : '',
+        join(process.cwd(), 'scripts', 'render.py'),
+    ].filter(Boolean);
+    for (const path of candidates) {
+        if (existsSync(path))
+            return path;
+    }
+    throw receptionEnvironmentError('RENDER_PY_MISSING', '找不到 render.py：请传 --render-py，或确保技能包 scripts/render.py 存在', { candidates });
+}
+function parseRenderOutput(result, outDir) {
+    const parsed = lastJsonLine(result.stdout);
+    if (!parsed) {
+        throw receptionBusinessError('RENDER_NO_JSON', '渲染失败：render.py 未返回 JSON', {
+            hint: `检查 ${outDir} 是否可写、render.py 是否完整`,
+            detail: String(result.stderr || '').split(/\r?\n/).filter(Boolean).slice(-12).join('\n').slice(-1200),
+        });
+    }
+    if (!parsed.ok) {
+        throw receptionBusinessError('RENDER_FAILED', `渲染失败: ${parsed.error || '未知错误'}`, {
+            hint: '多为字段类型不匹配（日期需 yyyy-MM-dd、金额为数字）；按 detail 修数据后重跑',
+            detail: String(result.stderr || '').split(/\r?\n/).filter(Boolean).slice(-12).join('\n').slice(-1200),
+        });
+    }
+    return parsed;
+}
+/** 单份渲染（异步）：供 docx 与 md 并行调用。 */
+export async function renderOnly(options) {
+    ensureDir(options.outDir);
+    const args = [options.renderPy, '--data', options.dataPath, '--out-dir', options.outDir, '--only', options.only];
+    const raw = await runAsync(options.python, args);
+    return parseRenderOutput(raw, options.outDir);
+}
+function mergeTwo(docx, md) {
+    const files = [...(docx.files || []), ...(md.files || [])];
+    const qa = { ...(docx.qa || {}), ...(md.qa || {}) };
+    if (docx.qa && docx.qa.external)
+        qa.external = docx.qa.external;
+    const warnings = [
+        ...((docx.qa && docx.qa.warnings) || []),
+        ...((md.qa && md.qa.warnings) || []),
+    ];
+    if (warnings.length)
+        qa.warnings = warnings;
+    const verify = { ...(docx.verify || {}), ...(md.verify || {}) };
+    verify.fileCount = files.length;
+    return {
+        ok: true,
+        files,
+        qa,
+        verify,
+        agendaRows: docx.agendaRows || md.agendaRows || [],
+        scheduleRows: docx.scheduleRows || md.scheduleRows || [],
+    };
+}
+/** 并行渲染两份并合并。两份都落盘后再上传，因为要挂到同一个附件字段。 */
+export async function renderBoth(options) {
+    ensureDir(options.outDir);
+    const startedAt = Date.now();
+    let docxMs = 0;
+    let mdMs = 0;
+    const docxPromise = renderOnly({ ...options, only: 'docx' }).then((result) => {
+        docxMs = Date.now() - startedAt;
+        return result;
+    });
+    const mdPromise = renderOnly({ ...options, only: 'md' }).then((result) => {
+        mdMs = Date.now() - startedAt;
+        return result;
+    });
+    const [docxResult, mdResult] = await Promise.all([docxPromise, mdPromise]);
+    return {
+        result: mergeTwo(docxResult, mdResult),
+        docxResult,
+        mdResult,
+        docxMs,
+        mdMs,
+        parallelMs: Date.now() - startedAt,
+    };
+}
+/** 供 doc 用：缺 python 时给出可执行的提示而不是堆栈。 */
+export function requirePython(stateDir) {
+    const python = pickPython(stateDir);
+    if (!python) {
+        throw receptionEnvironmentError('NO_PYTHON_DOCX', '缺 python3 + python-docx，无法渲染 docx', { hint: 'pip install python-docx；离线环境只能交付 md' });
+    }
+    return python;
+}
+export { mtimeMs };

package/dist/shortcuts/reception/operations/render.js

@@ -0,0 +1,123 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { receptionEnvironmentError } from '../errors.js';
+import { renderBrowsertool, resolveRenderType } from './browsertool.js';
+import { composeInitialValues } from './compose.js';
+import { mergeAnswers } from './panels.js';
+import { loadRun, runsDir } from './runs.js';
+import { nameList } from './shared.js';
+import { resolveSnapshot } from './snapshot.js';
+export async function render(input, ctx) {
+    const startedAt = Date.now();
+    const run = loadRun(ctx.stateDir, String(input.runId || '').trim());
+    // 快照优先级：显式参数 → doc 记在 run 里的路径。重建的 run 没有记录，仍需显式传。
+    const snapshotPath = String(input.snapshot || '').trim() || run.snapshotPath || '';
+    const resolved = resolveSnapshot(snapshotPath);
+    if (!resolved.snapshot) {
+        throw receptionEnvironmentError('SNAPSHOT_MISSING', '未找到字段快照 data/fields-snapshot.json', {
+            hint: '传 --snapshot "<技能目录>/data/fields-snapshot.json"；doc 传过的话通常已记在 run 里，不必重复传',
+            snapshotPath,
+        });
+    }
+    const answers = input.answers ?? run.answers ?? {};
+    const data = mergeAnswers(run, answers);
+    // 附件：显式 --attachment-fileid（可逗号分隔多个）优先，否则用 doc 落盘的附件数组
+    const argAttachment = String(input.attachmentFileid || '').trim();
+    const runAttachments = Array.isArray(run.attachmentFileids) ? run.attachmentFileids : [];
+    // 「参与人员」兜底：一个人名都没有时，才用当前登录人填。
+    // 读会话要解 keyring（~300ms），有人名的正常流程不该为它付代价。
+    const hasCompanions = Array.isArray(data.companions) && data.companions.length > 0;
+    const hasEscorts = nameList(data.escorts).length > 0;
+    if (!data.empId && !hasCompanions && !hasEscorts) {
+        const session = await ctx.host.getSession();
+        data.empId = session.userId || '';
+    }
+    const composed = composeInitialValues({
+        snapshot: resolved.snapshot,
+        data,
+        attachmentFileid: argAttachment || run.attachmentFileid || '',
+        attachmentFileids: argAttachment ? null : runAttachments,
+    });
+    // 主联络人一致性：用户明确指定了对接人（escorts），但实际填入的是别人时提前报警。
+    // 修复不彻底或调用方传参有误时，这是最后一道防线。
+    const escortNames = nameList(data.escorts);
+    const filledNames = (Array.isArray(data.companions) ? data.companions : [])
+        .map((item) => (typeof item === 'string' ? item : (item && (item.name || item.id)) || ''))
+        .map((item) => String(item || '').trim())
+        .filter(Boolean);
+    if (escortNames.length && filledNames.length && !escortNames.some((name) => filledNames.includes(name))) {
+        composed.warnings.push([
+            '主联络人可能填错：',
+            `指定对接人为 ${escortNames.join(',')}，实际填入 ${filledNames.join(',')}。`,
+            '请在页面上核对「泛微分支机构参与人员（主联络人）」字段。',
+        ].join(''));
+    }
+    if (!composed.keys.length) {
+        return {
+            state: 'empty',
+            ok: false,
+            data: { customParams: {}, fieldAssignKeys: '', todos: composed.todos },
+            warnings: composed.warnings,
+            next: {
+                command: 'weaver-work-cli reception render --run-id … --answers \'{...}\'',
+                reason: '没有任何字段有值，先补齐 answers',
+            },
+        };
+    }
+    // baseUrl 优先级：run 记录 → 当前会话 → 快照环境值。
+    // run.base 是 doc 上传时回填的，与本次执行同机同环境；先取它能省掉一次会话解析（~228ms）。
+    // run 被重建（RUN_NOT_FOUND）时 run.base 为空，才回落到会话。
+    const baseUrl = run.base
+        || (await ctx.host.getSession()).baseUrl
+        || (resolved.snapshot.env && resolved.snapshot.env.baseUrl)
+        || '';
+    const browsertool = renderBrowsertool({
+        baseUrl,
+        workflowId: (resolved.snapshot.workflow && resolved.snapshot.workflow.workflowId) || '',
+        workflowName: (resolved.snapshot.workflow && resolved.snapshot.workflow.name) || run.workflow,
+        customParams: { values: composed.values, keys: composed.keys },
+        sdkRenderType: input.sdkRender,
+    });
+    // browsertool 落盘：宿主若支持文件引用，模型就不必逐字复述这 2.5KB 结构化 JSON
+    // （那是整条链路里最贵的一段生成）。`data.browsertool` 仍然保留，宿主不支持时照旧整段输出。
+    let browsertoolFile = '';
+    try {
+        const dir = runsDir(ctx.stateDir);
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const file = join(dir, `${run.runId}.browsertool.json`);
+        // 落纯 JSON（不含 <browsertool> 标签）：标签由宿主按自己的解析规则包上
+        const payload = browsertool
+            .replace(/^<browsertool>\s*/u, '')
+            .replace(/\s*<\/browsertool>$/u, '');
+        writeFileSync(file, payload, 'utf8');
+        // 统一正斜杠：JSON 里不用转义，Windows 前端也能直接读
+        browsertoolFile = file.replace(/\\/gu, '/');
+    }
+    catch (error) {
+        composed.warnings.push(`browsertool 落盘失败（${error.message}）：按整段 browsertool 输出即可`);
+    }
+    return {
+        state: 'rendered',
+        ok: true,
+        data: {
+            customParams: composed.values,
+            fieldAssignKeys: composed.keys.join(','),
+            detailRowCount: composed.detailRowCount,
+            attachmentPending: composed.attachmentPending,
+            sdkRenderType: resolveRenderType(input.sdkRender),
+            todos: composed.todos,
+            browsertool,
+            browsertoolFile,
+            browsertoolRef: browsertoolFile ? `<browsertool-file path="${browsertoolFile}" />` : '',
+            timings: { totalMs: Date.now() - startedAt },
+        },
+        warnings: composed.warnings,
+        next: {
+            command: '把 data.browsertool 整段原样作为回复正文（不包代码块）',
+            reason: '宿主会打开新建页并带值；用户自己提交',
+        },
+    };
+}
+export const renderOperation = {
+    execute: (input, ctx) => render(input, ctx),
+};

package/dist/shortcuts/reception/operations/runs.js

@@ -0,0 +1,38 @@
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { receptionRunNotFound, receptionValidationError } from '../errors.js';
+import { ensureDir, readJson, writeJson } from './shared.js';
+function pad(value) {
+    return String(value).padStart(2, '0');
+}
+export function newRunId(now = new Date()) {
+    const stamp = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`
+        + `${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+    return `rc-${stamp}-${randomBytes(2).toString('hex')}`;
+}
+export function runsDir(stateDir) {
+    return join(stateDir, 'runs');
+}
+export function runPath(stateDir, runId) {
+    return join(runsDir(stateDir), `${runId}.json`);
+}
+export function saveRun(stateDir, run) {
+    ensureDir(runsDir(stateDir));
+    writeJson(runPath(stateDir, run.runId), run);
+    return run;
+}
+export function loadRun(stateDir, runId) {
+    if (!runId) {
+        throw receptionValidationError('RUN_ID_MISSING', '缺少 --run-id（正常流程先用 ask 取 runId；run 已失效时改用 --known 现场重建）', { hint: 'reception doc --known \'{"customer":"…","visitDate":"…"}\' --answers \'{…}\'' });
+    }
+    const found = readJson(runPath(stateDir, runId));
+    if (!found)
+        throw receptionRunNotFound(runId, stateDir);
+    return found;
+}
+/** 尝试读取；不存在返回 null，不抛。doc 的"现场重建"分支用它。 */
+export function tryLoadRun(stateDir, runId) {
+    if (!runId)
+        return null;
+    return readJson(runPath(stateDir, runId));
+}

package/dist/shortcuts/reception/operations/schedule.js

@@ -0,0 +1,127 @@
+import { nameList } from './shared.js';
+/**
+ * 日程明细口径：四种来源（scheduleRows / schedule / agenda / 标准议程兜底）+ 7 列按字段 ID 映射。
+ *
+ * 这张表是表单 subForm 的真实结构，改动必须先在真机核对快照；
+ * 口径与 `data/fields-snapshot.json` 的 details 段一一对应。
+ */
+export const SCHEDULE_DETAIL = {
+    subFormId: '100003690000000143',
+    dataKey: 'formtable_main_23_dt2',
+    switch: { fieldId: '100003720000014930', on: '启用' },
+    columns: {
+        date: '100003720000014936',
+        time: '100003720000014937',
+        item: '100003720000014938',
+        place: '100003720000014939',
+        person: '100003720000014940',
+        activity: '100003720000014941',
+        remark: '100003720000014942',
+    },
+};
+export const STANDARD_AGENDA = [
+    { offset: 0, item: '公司参观', activity: '参观泛微上海总部展厅与办公区，了解公司发展历程与产品能力' },
+    { offset: 45, item: '方案介绍', activity: '' },
+    { offset: 120, item: '讨论交流', activity: '双方围绕关注点交流答疑，明确后续推进节奏' },
+];
+const SEVEN = ['date', 'time', 'item', 'place', 'person', 'activity', 'remark'];
+export function hhmmPlus(start, mins) {
+    const base = /^\d{1,2}:\d{2}$/.test(String(start || '')) ? String(start) : '09:30';
+    const [hour, minute] = base.split(':').map(Number);
+    const total = (((hour * 60 + minute + mins) % 1440) + 1440) % 1440;
+    return `${String(Math.floor(total / 60)).padStart(2, '0')}:${String(total % 60).padStart(2, '0')}`;
+}
+function pick7(row) {
+    if (!row || typeof row !== 'object' || Array.isArray(row))
+        return null;
+    const source = row;
+    const out = {};
+    for (const key of SEVEN) {
+        const value = source[key];
+        if (value !== null && value !== undefined && String(value).trim())
+            out[key] = String(value).trim();
+    }
+    return Object.keys(out).length ? out : null;
+}
+export function normalizeScheduleRows(data = {}) {
+    const rows = [];
+    const push = (row) => {
+        if (row)
+            rows.push(row);
+    };
+    const companions = Array.isArray(data.companions) ? data.companions : [];
+    // 接待人员优先取用户指定的对接人（escorts）；companions 可能被 --user 覆盖成当前操作人
+    const escortNames = nameList(data.escorts);
+    const mainPerson = escortNames[0] || companions
+        .map((item) => (typeof item === 'string' ? item : (item && item.name) || ''))
+        .filter(Boolean)[0] || data.contact || '';
+    if (Array.isArray(data.scheduleRows))
+        data.scheduleRows.forEach((row) => push(pick7(row)));
+    if (!rows.length && Array.isArray(data.schedule)) {
+        data.schedule.forEach((row) => {
+            if (Array.isArray(row)) {
+                const [time, item, place] = row;
+                push(pick7({ date: data.visitDate || data.arrivalDate || '', time, item, place, person: mainPerson }));
+            }
+            else {
+                push(pick7(row));
+            }
+        });
+    }
+    if (!rows.length && Array.isArray(data.agenda)) {
+        data.agenda.forEach((row) => push(pick7({
+            date: data.visitDate || data.arrivalDate || '',
+            time: (row && (row.start || row.time)) || '',
+            item: row && row.item,
+            place: row && row.place,
+            person: (row && row.person) || mainPerson,
+            activity: row && row.activity,
+            remark: row && row.remark,
+        })));
+    }
+    if (!rows.length) {
+        const date = data.visitDate || data.arrivalDate || '';
+        const start = /^\d{1,2}:\d{2}$/.test(String(data.agendaStart || '')) ? String(data.agendaStart) : '09:30';
+        const room = data.meetingRoom || '总部129/130/131会议室（按人数择一）';
+        for (const item of STANDARD_AGENDA) {
+            push(pick7({
+                date,
+                time: hhmmPlus(start, item.offset),
+                item: item.item,
+                place: item.item === '公司参观' ? '泛微上海总部' : room,
+                person: mainPerson,
+                activity: item.item === '方案介绍' ? (data.demand || '产品与方案介绍') : item.activity,
+            }));
+        }
+    }
+    for (const row of rows)
+        if (!row.person && mainPerson)
+            row.person = mainPerson;
+    return rows;
+}
+export function buildDetailsPayload(rows) {
+    const list = Array.isArray(rows) ? rows : [];
+    const out = [];
+    for (const item of list) {
+        const row = {};
+        for (const [semantic, fieldId] of Object.entries(SCHEDULE_DETAIL.columns)) {
+            const value = item && item[semantic];
+            if (value === null || value === undefined)
+                continue;
+            const text = String(value).trim();
+            if (text)
+                row[fieldId] = text;
+        }
+        if (Object.keys(row).length)
+            out.push(row);
+    }
+    if (!out.length)
+        return null;
+    return {
+        details: { [SCHEDULE_DETAIL.subFormId]: out },
+        switchField: SCHEDULE_DETAIL.switch,
+        subFormId: SCHEDULE_DETAIL.subFormId,
+        dataKey: SCHEDULE_DETAIL.dataKey,
+        rowCount: out.length,
+    };
+}

package/dist/shortcuts/reception/operations/shared.js

@@ -0,0 +1,196 @@
+import { createHash } from 'node:crypto';
+import { chmodSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { receptionValidationError } from '../errors.js';
+/** 稳定序列化：键排序，保证同数据同哈希。 */
+export function canonical(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value ?? null);
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    const record = value;
+    const keys = Object.keys(record).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonical(record[key])}`).join(',')}}`;
+}
+export function sha256(text) {
+    return createHash('sha256').update(String(text)).digest('hex');
+}
+export function ensureDir(path) {
+    try {
+        mkdirSync(path, { recursive: true });
+    }
+    catch {
+        // 已存在或不可写；可写性交给后续真实写入报错
+    }
+}
+export function readJson(path, fallback = null) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return fallback;
+    }
+}
+export function writeJson(path, value) {
+    ensureDir(dirname(path));
+    writeFileSync(path, JSON.stringify(value, null, 2));
+}
+/** 最近修改时间，取不到算 0（用于 Python 缓存新鲜度判断）。 */
+export function mtimeMs(path) {
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+export function fileSize(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return 0;
+    }
+}
+/** 只有存在且未超过 ttl 才算新鲜。 */
+export function fresh(path, ttlMs) {
+    const mtime = mtimeMs(path);
+    return Boolean(mtime) && Date.now() - mtime < ttlMs;
+}
+/** 严紧权限落盘；Windows 上 chmod 无效，忽略即可。 */
+export function writeJsonSecure(path, value, mode = 0o600) {
+    writeJson(path, value);
+    try {
+        chmodSync(path, mode);
+    }
+    catch {
+        // Windows 无 POSIX 权限位
+    }
+}
+// ---------------------------------------------------------------------------
+// JSON 入参
+//
+// 三条铁律（2026-11-02 事故的产物，不要简化）：
+//   1. 文件优先（--xxx-file），彻底绕开 shell 转义；
+//   2. 解析前清 BOM / 零宽字符，失败再试中文引号 + 尾随逗号；
+//   3. 报错必须自证：区分 missing / file_unreadable / invalid，invalid 带 preview + hasBom。
+// ---------------------------------------------------------------------------
+const BOM = /^\uFEFF/;
+const ZERO_WIDTH = /[\u200B-\u200D\uFEFF]/g;
+/** 纯文本 → 对象。不做 IO，便于单测。 */
+export function parseJsonText(raw) {
+    const src = String(raw ?? '');
+    const hasBom = src.charCodeAt(0) === 0xfeff;
+    const cleaned = src.replace(BOM, '').replace(ZERO_WIDTH, '').trim();
+    try {
+        return { ok: true, value: JSON.parse(cleaned), hasBom };
+    }
+    catch (firstError) {
+        const fixed = cleaned
+            .replace(/[\u201C\u201D]/g, '"')
+            .replace(/[\u2018\u2019]/g, "'")
+            .replace(/,\s*([}\]])/g, '$1');
+        try {
+            return { ok: true, value: JSON.parse(fixed), hasBom, autoFixed: true };
+        }
+        catch {
+            return {
+                ok: false,
+                reason: 'invalid',
+                error: firstError.message,
+                preview: cleaned.slice(0, 120),
+                hasBom,
+            };
+        }
+    }
+}
+/** 从选项对象读 JSON：`--<name>-file` 优先，其次 `--<name>` 内联。 */
+export function readJsonArg(options, name) {
+    const filePath = textOf(options, `${name}File`) || textOf(options, `${name}-file`);
+    if (filePath) {
+        let raw;
+        try {
+            raw = readFileSync(filePath, 'utf8');
+        }
+        catch (error) {
+            return {
+                ok: false,
+                reason: 'file_unreadable',
+                path: filePath,
+                error: error.message,
+            };
+        }
+        return { ...parseJsonText(raw), source: 'file', path: filePath };
+    }
+    const inline = options[name];
+    if (inline === undefined || inline === null || inline === true) {
+        return { ok: false, reason: 'missing' };
+    }
+    return { ...parseJsonText(String(inline)), source: 'inline' };
+}
+/**
+ * 取一个 JSON 参数，按语义抛错。
+ *
+ * @param options  commander 收集到的选项对象
+ * @param name     逻辑名，如 `known`（对应 --known / --known-file）
+ * @param config.code 错误码前缀，如 `KNOWN` → KNOWN_REQUIRED / KNOWN_INVALID / KNOWN_FILE_UNREADABLE
+ */
+export function jsonArg(options, name, config = {}) {
+    const prefix = config.code || name.toUpperCase().replace(/-/g, '_');
+    const result = readJsonArg(options, name);
+    if (result.ok)
+        return result.value;
+    if (result.reason === 'missing') {
+        if (!config.required)
+            return null;
+        throw receptionValidationError(`${prefix}_REQUIRED`, `缺少 --${name} <JSON> 或 --${name}-file <path>`, {
+            hint: config.hint || `推荐用文件传参：先写 ${name}.json，再 --${name}-file ${name}.json`,
+        });
+    }
+    if (result.reason === 'file_unreadable') {
+        throw receptionValidationError(`${prefix}_FILE_UNREADABLE`, `读不到 --${name}-file：${result.path}`, {
+            path: result.path,
+            detail: result.error,
+            hint: '检查文件是否存在、路径是否正确、是否有读权限；不要因此改回内联传参',
+        });
+    }
+    throw receptionValidationError(`${prefix}_INVALID`, `--${name} 不是合法 JSON：${result.error}`, {
+        hint: '常见原因：UTF-8 BOM（hasBom:true）、中文引号、尾随逗号、shell 吃掉双引号。'
+            + '请看 preview 定位，修 JSON 本身，不要换传参方式重试',
+        preview: result.preview,
+        hasBom: result.hasBom,
+    });
+}
+/** 从选项对象取字符串；commander 对未传的选项给 undefined，对布尔开关给 true。 */
+export function textOf(options, key) {
+    const value = options[key];
+    if (value === undefined || value === null || value === true || value === false)
+        return '';
+    return String(value).trim();
+}
+/** 姓名归一：数组 / 逗号分隔串 / {name} 对象都吃。 */
+export function nameList(value) {
+    const list = Array.isArray(value) ? value : String(value ?? '').split(/[,，、;；\s]+/);
+    return list
+        .map((item) => (typeof item === 'string' ? item : (item && (item.name || item.id)) || ''))
+        .map((item) => String(item).trim())
+        .filter(Boolean);
+}
+const hasValue = (value) => !(value === undefined || value === null || value === ''
+    || (Array.isArray(value) && value.length === 0));
+/** 7 项缺口：只判「有没有」，语义判断仍由模型完成。 */
+export function computeGaps(data = {}) {
+    const filled = [];
+    const gap = [];
+    const push = (key, value) => (hasValue(value) ? filled.push(key) : gap.push(key));
+    push('customer', data.customer || data.customerId);
+    push('headcount', data.headcount);
+    push('visitDate', data.visitDate);
+    push('visitType', data.visitType);
+    push('companions', data.companions);
+    push('demand', data.demand);
+    const logistics = ['headcount', 'meetingRoom', 'pickup', 'meal', 'hotel', 'gift'];
+    const logisticsMissing = logistics.filter((key) => !hasValue(data[key]));
+    push('logistics', logisticsMissing.length ? null : logistics);
+    return { filled, gap, logisticsMissing };
+}