weaver-work-cli 0.1.29 → 0.1.31

package/dist/shortcuts/contract/operations/assistant.js

@@ -0,0 +1,1156 @@
+import { contractPolicyError, contractValidationError } from '../errors.js';
+import { aiSettingPageUrl } from './page.js';
+import { bodyFrom, fingerprintFields, idList, requireId, requireNonEmptyString, toJsonString } from './shared.js';
+import { ContractWriteApplyOperation, ContractWritePrepareOperation } from './write.js';
+const AI_BASE = '/api/ebd/contract/ai';
+const AUDIT_BASE = '/api/ebd/contract/audit';
+const CONFIG_BASE = `${AI_BASE}/config`;
+const TIP_BASE = `${AI_BASE}/tip`;
+const PERMISSION_BASE = '/api/ebd/contract/tool/permission';
+/** 关联流程固定 toolId / componentId（源资料第十一节）。 */
+const FLOW_TOOL_ID = '803297036482249914';
+/** 关联流程删除必须携带 type，缺失会返回 success 但实际不删除。 */
+const FLOW_DELETE_TYPE = 'contract_ai_workflow_data';
+const AI_MARKS = [
+    'Chat', 'Summary', 'ProcurementRisk', 'Control', 'Review', 'Correct', 'Extract',
+    'Credit', 'Signature', 'Compare', 'Desensitization', 'RiskReview',
+    'riskRuleComponent', 'consultComponent', 'termComponent', 'keywordComponent',
+];
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function dataOf(value) {
+    return value?.data ?? {};
+}
+function rowsOf(value) {
+    const data = dataOf(value);
+    for (const candidate of [data.data, data.records, data.list, data.rows, data]) {
+        if (Array.isArray(candidate))
+            return candidate;
+    }
+    return [];
+}
+// ---------------------------------------------------------------- 串联链路
+/**
+ * getEbData?type=ai_background_config 是助手本体列表的唯一合法 type。
+ * ai_component_config 是组件配置（实测能查出数据但答非所问），ai_compenent_config 不存在，均在此阻断。
+ */
+async function assistantMeta(host) {
+    const value = await host.contractRequest({
+        method: 'GET',
+        path: `${AI_BASE}/getEbData`,
+        query: { type: 'ai_background_config' },
+    });
+    const data = dataOf(value);
+    if (!data.formId || !data.viewId) {
+        throw contractValidationError('assistant_meta_missing', 'getEbData 未返回 formId/viewId，助手列表链路不可用；请先运行 contract.assistant.init 完成初始化');
+    }
+    return { ebFormId: String(data.formId), viewId: String(data.viewId), fieldsMap: data.fieldsMap ?? {} };
+}
+async function listAssistants(host, name) {
+    const meta = await assistantMeta(host);
+    const quickSearchFields = {};
+    if (name) {
+        const fieldId = meta.fieldsMap.ai_name;
+        if (!fieldId) {
+            throw contractValidationError('assistant_meta_missing', 'fieldsMap 缺少 ai_name 字段映射，无法按名称过滤；请省略 name 做全量查询');
+        }
+        quickSearchFields[`field_${fieldId}`] = name;
+    }
+    const value = await host.contractRequest({
+        method: 'POST',
+        path: '/api/ebuilder/form/list/getListDatas',
+        query: { cid: meta.ebFormId },
+        body: {
+            current: 1,
+            requiredMatch: 1,
+            tableuid: '',
+            mapResult: '1',
+            recheckQuery: '1',
+            searchParamData: {
+                searchType: '2',
+                quickSearchFields,
+                commonSearchFields: {},
+                type: 'and',
+                groupFields: {},
+            },
+            listId: meta.viewId,
+            isFollow: 0,
+            isShareToMe: 0,
+            filterCondition: {},
+            browser: 'Chrome',
+        },
+    });
+    return rowsOf(value);
+}
+async function queryAiDoc(host, aiId) {
+    const value = await host.contractRequest({ method: 'POST', path: `${CONFIG_BASE}/queryAiDoc`, body: { ai_id: aiId } });
+    return rowsOf(value);
+}
+async function queryTips(host, aiId) {
+    const value = await host.contractRequest({ method: 'POST', path: `${TIP_BASE}/queryTips`, body: { ai_id: aiId } });
+    return rowsOf(value);
+}
+async function queryClassificationList(host) {
+    const value = await host.contractRequest({
+        method: 'POST',
+        path: `${AI_BASE}/queryList`,
+        body: { type: 'contract_classification', condition: [{ fieldName: 'personal_config', conditionType: 'isNull' }] },
+    });
+    return rowsOf(value);
+}
+async function queryRuleList(host, flid, pageNo = 1, pageSize = 20) {
+    const condition = [{ fieldName: 'personal_config', conditionType: 'neq', value: '1' }];
+    if (flid)
+        condition.push({ fieldName: 'flid', conditionType: 'like', value: String(flid) });
+    const value = await host.contractRequest({
+        method: 'POST',
+        path: `${AI_BASE}/queryList`,
+        body: { type: 'contract_rule_datasource', condition, pageNo, pageSize },
+    });
+    return rowsOf(value);
+}
+async function queryAiConfig(host, aiId) {
+    const value = await host.contractRequest({ method: 'POST', path: `${CONFIG_BASE}/queryAiConfig`, body: { ai_id: aiId } });
+    return rowsOf(value);
+}
+async function queryFlowList(host, aiId, ruleConfigId, pageIndex = 1, pageSize = 50) {
+    const value = await host.contractRequest({
+        method: 'POST',
+        path: `${PERMISSION_BASE}/list/page`,
+        body: { appId: '-1', aiId, rule_config_id: ruleConfigId, componentId: FLOW_TOOL_ID, pageIndex, pageSize },
+    });
+    return rowsOf(value);
+}
+// ---------------------------------------------------------------- 查询类
+/** 初始化状态：importStatus 非 already 时自动轮询 getInitStatus。 */
+export const contractAssistantInitOperation = {
+    name: 'contract.assistant.init',
+    async execute(_input, { host }) {
+        let value = await host.contractRequest({ method: 'GET', path: `${AUDIT_BASE}/getAllEbConfig` });
+        let data = dataOf(value);
+        let polled = 0;
+        if (data.importStatus !== 'already' && data.traceId) {
+            for (let i = 0; i < 6; i += 1) {
+                await sleep(1500);
+                polled += 1;
+                await host.contractRequest({
+                    method: 'GET',
+                    path: `${AUDIT_BASE}/getInitStatus`,
+                    query: { traceId: String(data.traceId) },
+                });
+                value = await host.contractRequest({ method: 'GET', path: `${AUDIT_BASE}/getAllEbConfig` });
+                data = dataOf(value);
+                if (data.importStatus === 'already')
+                    break;
+            }
+        }
+        return {
+            status: 'COMPLETE',
+            data: {
+                importStatus: data.importStatus,
+                polled,
+                companyEbConfigMap: data.companyEbConfigMap,
+                ...(data.importStatus === 'already' ? {} : {
+                    warning: `初始化未完成（traceId=${data.traceId}）；稍后重新运行本命令，配置链路（getEbData/getListDatas）在完成前不可用`,
+                }),
+            },
+        };
+    },
+};
+/** 列表字段映射；type 固定 ai_background_config（组件配置是合法 type 但答非所问，在此固定掉）。 */
+export const contractAssistantMetaOperation = {
+    name: 'contract.assistant.meta',
+    async execute(_input, { host }) {
+        const meta = await assistantMeta(host);
+        return { status: 'COMPLETE', data: { ...meta, note: '查询条件 key 格式为 field_<字段id>' } };
+    },
+};
+export const contractAssistantListOperation = {
+    name: 'contract.assistant.list',
+    async execute(input, { host }) {
+        const name = typeof input.name === 'string' && input.name.trim() ? input.name.trim() : undefined;
+        const rows = await listAssistants(host, name);
+        return {
+            status: 'COMPLETE',
+            data: {
+                assistants: rows.map((row) => ({
+                    id: row.id,
+                    ai_name: row.ai_name,
+                    ai_desc: row.ai_desc,
+                    type_name: row.type_name,
+                    stand_name: row.stand_name,
+                })),
+                hint: rows.length === 1
+                    ? '列表只有一个助手，后续操作可默认使用它'
+                    : '多个助手时后续操作必须明确指定 ai_id，否则列出全部让用户选择',
+            },
+        };
+    },
+};
+/** 存储目录 + 自动执行配置；无 base_type=存储目录，base_type=1=执行方式。 */
+export const contractAssistantDocQueryOperation = {
+    name: 'contract.assistant.doc.query',
+    async execute(input, { host }) {
+        const aiId = requireId(input.ai_id ?? input.aiId, 'ai_id');
+        const rows = await queryAiDoc(host, aiId);
+        return {
+            status: 'COMPLETE',
+            data: {
+                storage: rows.filter((row) => row.base_type === undefined || row.base_type === ''),
+                execute: rows.filter((row) => row.base_type === '1' || row.base_type === 1),
+                hint: 'execute_type=2 手动执行，其他值为自动',
+            },
+        };
+    },
+};
+/** 16 智能体查询；自动挑出 Control（rule_config_id）与 Extract（config_id）。 */
+export const contractAssistantConfigQueryOperation = {
+    name: 'contract.assistant.config.query',
+    async execute(input, { host }) {
+        const aiId = requireId(input.ai_id ?? input.aiId, 'ai_id');
+        const aiMark = typeof input.aiMark === 'string' && input.aiMark ? input.aiMark : undefined;
+        if (aiMark && !AI_MARKS.includes(aiMark)) {
+            throw contractValidationError('ai_mark_invalid', `未知 ai_mark：${aiMark}；合法值 ${AI_MARKS.join('/')}`);
+        }
+        const rows = await queryAiConfig(host, aiId);
+        const agents = rows
+            .filter((row) => !aiMark || row.ai_mark === aiMark)
+            .map((row) => ({
+            id: row.id,
+            ai_mark: row.ai_mark,
+            ai_name: row.ai_name,
+            display: row.display,
+            status_info: row.status_info,
+            iorder: row.iorder,
+        }));
+        const control = rows.find((row) => row.ai_mark === 'Control');
+        const extract = rows.find((row) => row.ai_mark === 'Extract');
+        return {
+            status: 'COMPLETE',
+            data: {
+                agents,
+                controlAgentId: control?.id,
+                extractAgentId: extract?.id,
+                warning: 'display 是平台保留字段（前端卡片展示），启用/停用智能体只允许改 status_info',
+            },
+        };
+    },
+};
+export const contractAssistantTipsQueryOperation = {
+    name: 'contract.assistant.tips.query',
+    async execute(input, { host }) {
+        const aiId = requireId(input.ai_id ?? input.aiId, 'ai_id');
+        const rows = await queryTips(host, aiId);
+        return {
+            status: 'COMPLETE',
+            data: {
+                tips: rows.map((row) => ({ id: row.id, aizjid: row.aizjid, tsynr: row.tsynr })),
+                hint: '提示语无编辑接口，改动需先删后增；新建助手自带 4 条默认提示语',
+            },
+        };
+    },
+};
+export const contractAssistantDocFolderSearchOperation = {
+    name: 'contract.assistant.doc.folder.search',
+    async execute(input, { host }) {
+        const name = typeof input.name === 'string' && input.name.trim() ? input.name.trim() : '';
+        const value = await host.contractRequest({
+            method: 'POST',
+            path: '/api/doc/common/browser/data/folder',
+            body: {
+                browserMultiple: false,
+                dimension: 'all',
+                current: 1,
+                pageSize: 10,
+                formDatas: {},
+                quickSearchDatas: { name },
+                type: 'and',
+                useListViewType: false,
+                browserTreeDefaultExpandedLevel: '0',
+            },
+        });
+        return { status: 'COMPLETE', data: { name, folders: rowsOf(value) } };
+    },
+};
+export const contractAssistantKeygroupSearchOperation = {
+    name: 'contract.assistant.keygroup.search',
+    async execute(input, { host }) {
+        const name = typeof input.name === 'string' && input.name.trim() ? input.name.trim() : '';
+        const value = await host.contractRequest({
+            method: 'POST',
+            path: '/api/ebd/contract/common/browser/data/ebContractKeyGroupBrowser',
+            body: { browserMultiple: true, current: 1, pageSize: 10, formDatas: {}, quickSearchDatas: { name }, type: 'and' },
+        });
+        return { status: 'COMPLETE', data: { name, groups: rowsOf(value) } };
+    },
+};
+export const contractAssistantClassificationListOperation = {
+    name: 'contract.assistant.rule.classification.list',
+    async execute(_input, { host }) {
+        const rows = await queryClassificationList(host);
+        return { status: 'COMPLETE', data: { classifications: rows, hint: '该接口无模糊检索，全量返回后自行过滤' } };
+    },
+};
+export const contractAssistantRuleListOperation = {
+    name: 'contract.assistant.rule.list',
+    async execute(input, { host }) {
+        const flid = input.flid === undefined || input.flid === '' ? undefined : requireId(input.flid, 'flid');
+        const pageNo = typeof input.pageNo === 'number' ? input.pageNo : 1;
+        const pageSize = typeof input.pageSize === 'number' ? input.pageSize : 20;
+        const rows = await queryRuleList(host, flid, pageNo, pageSize);
+        return { status: 'COMPLETE', data: { rules: rows } };
+    },
+};
+export const contractAssistantRuleGroupQueryOperation = {
+    name: 'contract.assistant.rule.group.query',
+    async execute(input, { host }) {
+        const configId = requireId(input.config_id ?? input.configId, 'config_id（Control 智能体 id）');
+        const value = await host.contractRequest({
+            method: 'POST',
+            path: `${CONFIG_BASE}/queryCustomConfigRules`,
+            body: { config_id: configId },
+        });
+        return { status: 'COMPLETE', data: { groups: rowsOf(value) } };
+    },
+};
+export const contractAssistantElementQueryOperation = {
+    name: 'contract.assistant.element.query',
+    async execute(input, { host }) {
+        const configId = requireId(input.config_id ?? input.configId, 'config_id（Extract 智能体 id）');
+        const value = await host.contractRequest({
+            method: 'POST',
+            path: `${CONFIG_BASE}/queryElementConfigRules`,
+            body: { config_id: configId },
+        });
+        return { status: 'COMPLETE', data: { elementSets: rowsOf(value) } };
+    },
+};
+export const contractAssistantFlowListOperation = {
+    name: 'contract.assistant.flow.list',
+    async execute(input, { host }) {
+        const aiId = requireId(input.ai_id ?? input.aiId, 'ai_id');
+        const ruleConfigId = requireId(input.rule_config_id ?? input.ruleConfigId, 'rule_config_id（Control 智能体 id）');
+        const pageIndex = typeof input.pageIndex === 'number' ? input.pageIndex : 1;
+        const pageSize = typeof input.pageSize === 'number' ? input.pageSize : 50;
+        const rows = await queryFlowList(host, aiId, ruleConfigId, pageIndex, pageSize);
+        return {
+            status: 'COMPLETE',
+            data: {
+                bindings: rows,
+                hint: '一个流程全局只能绑定一次（跨助手唯一）；绑定前先在这里排查是否已被占用',
+            },
+        };
+    },
+};
+// ---------------------------------------------------------------- 写操作公共
+/** 读取并归一化 ai_id：驼峰 aiId 一律写回 ai_id，供 body 构造与指纹复用。 */
+function requireAiId(input) {
+    const value = requireId(input.ai_id ?? input.aiId, 'ai_id（助手数据 id）');
+    input.ai_id = value;
+    return value;
+}
+function requireConfigId(input, label) {
+    const value = requireId(input.config_id ?? input.configId, `config_id（${label}）`);
+    input.config_id = value;
+    return value;
+}
+/** ai-setting 功能页地址随写结果一并返回，供写后打开页面确认。 */
+async function pageHint(host) {
+    const session = await host.getSession();
+    return { url: aiSettingPageUrl(session.baseUrl) };
+}
+function writePair(name, spec) {
+    return [
+        new ContractWritePrepareOperation(`${name}.prepare`, `${name}.apply`, spec),
+        new ContractWriteApplyOperation(`${name}.apply`, spec),
+    ];
+}
+/** tips.create 需要在 prepare / apply 两端自动补算 aizjid，用专用子类注册。 */
+function tipsWritePair(spec) {
+    return [
+        new TipsCreatePrepareOperation('contract.assistant.tips.create.prepare', 'contract.assistant.tips.create.apply', spec),
+        new TipsCreateApplyOperation('contract.assistant.tips.create.apply', spec),
+    ];
+}
+// ---------------------------------------------------------------- 助手新建 / 删除
+const assistantCreateSpec = {
+    method: 'POST',
+    path: `${CONFIG_BASE}/saveAiInfo`,
+    validate(input) {
+        requireNonEmptyString(input.ai_name, 'ai_name', 200);
+        if ((input.type === undefined) !== (input.type_name === undefined)) {
+            throw contractValidationError('type_pair_required', 'type 与 type_name（合同类型 id 与名称）必须成对提交');
+        }
+        if (input.type !== undefined)
+            requireId(input.type, 'type');
+        if (input.contract_stand !== undefined) {
+            const stand = String(input.contract_stand);
+            if (!['0', '1'].includes(stand)) {
+                throw contractValidationError('contract_stand_invalid', 'contract_stand 只能是 0（甲方）或 1（乙方）');
+            }
+            if (input.stand_name === undefined) {
+                throw contractValidationError('stand_pair_required', 'contract_stand 与 stand_name 必须成对提交');
+            }
+        }
+    },
+    body: (input) => bodyFrom(input, ['ai_name', 'ai_desc', 'type', 'type_name', 'contract_stand', 'stand_name']),
+    fingerprint: fingerprintFields(['ai_name', 'ai_desc', 'type', 'type_name', 'contract_stand', 'stand_name']),
+    preview: (input) => ({
+        action: '新建智能助手',
+        ai_name: input.ai_name,
+        type_name: input.type_name,
+        stand_name: input.stand_name ?? input.contract_stand,
+        warning: '助手基本信息（名称/说明/类型/立场）平台不支持修改，需调整时删除后重建',
+    }),
+    async readback(_result, input, host) {
+        const rows = await listAssistants(host, input.ai_name);
+        const hit = rows.find((row) => row.ai_name === input.ai_name);
+        if (!hit)
+            throw new Error('助手列表中未找到刚创建的助手');
+        return { id: hit.id, ai_name: hit.ai_name, ...(await pageHint(host)) };
+    },
+};
+const assistantDeleteSpec = {
+    method: 'POST',
+    path: `${CONFIG_BASE}/deleteAiInfo`,
+    validate(input) {
+        const ids = idList(input.ids ?? input.id, 'ids');
+        input.ids = ids.join(',');
+    },
+    body: (input) => ({ ids: String(input.ids) }),
+    fingerprint: fingerprintFields(['ids']),
+    preview: (input) => ({
+        action: '删除智能助手',
+        ids: input.ids,
+        warning: '删除接口对不存在的 id 也返回 success（假成功），apply 会强制回读复核',
+    }),
+    async precheck(input, host) {
+        const ids = String(input.ids).split(',');
+        const rows = await listAssistants(host);
+        const existing = rows.filter((row) => ids.includes(String(row.id)));
+        if (existing.length === 0) {
+            throw contractPolicyError('assistant_not_found', '待删除的助手 id 均不存在，未发起删除', { ids: input.ids });
+        }
+        return {
+            found: existing.map((row) => ({ id: row.id, ai_name: row.ai_name })),
+            missing: ids.filter((id) => !existing.some((row) => String(row.id) === id)),
+        };
+    },
+    async readback(_result, input, host) {
+        const ids = String(input.ids).split(',');
+        const rows = await listAssistants(host);
+        const remaining = rows.filter((row) => ids.includes(String(row.id)));
+        if (remaining.length) {
+            throw new Error(`删除接口返回成功，但列表中仍能查到 ${remaining.length} 个助手（${remaining.map((r) => r.ai_name).join('/')}）`);
+        }
+        return { removed: true, ...(await pageHint(host)) };
+    },
+};
+// ---------------------------------------------------------------- 存储目录 / 执行方式（saveAiDoc 同表覆盖防护）
+const assistantDocSaveSpec = {
+    method: 'POST',
+    path: `${CONFIG_BASE}/saveAiDoc`,
+    validate(input) {
+        requireAiId(input);
+        const kind = input.kind;
+        if (!['storage', 'execute'].includes(kind)) {
+            throw contractValidationError('kind_required', "kind 必传且只能是 'storage'（存储目录）或 'execute'（执行方式）");
+        }
+        if (kind === 'storage') {
+            requireId(input.doc_id ?? input.docId, 'doc_id');
+            requireNonEmptyString(input.doc_name ?? input.docName, 'doc_name', 200);
+        }
+        else {
+            const executeType = String(input.execute_type ?? input.executeType ?? '');
+            if (!['1', '2'].includes(executeType)) {
+                throw contractValidationError('execute_type_invalid', "execute_type 只能是 '1'（自动）或 '2'（手动）");
+            }
+        }
+    },
+    body: (input) => {
+        const base = { ai_id: requireAiId(input) };
+        if (input.id !== undefined)
+            base.id = requireId(input.id, '记录 id');
+        if (input.kind === 'storage') {
+            base.doc_id = String(input.doc_id ?? input.docId);
+            base.doc_name = String(input.doc_name ?? input.docName);
+        }
+        else {
+            base.execute_type = String(input.execute_type ?? input.executeType);
+            base.base_type = '1';
+        }
+        return base;
+    },
+    fingerprint: fingerprintFields(['kind', 'ai_id', 'id', 'doc_id', 'doc_name', 'execute_type']),
+    preview: (input) => ({
+        action: input.kind === 'storage' ? '设置存储目录' : '设置自动执行方式',
+        kind: input.kind,
+        id: input.id ?? '(新增)',
+        doc_name: input.doc_name ?? input.docName,
+        execute_type: input.execute_type ?? input.executeType,
+    }),
+    async precheck(input, host) {
+        if (input.id === undefined)
+            return { mode: 'create' };
+        // saveAiDoc 同表按 id 覆盖：record-id 传错会把另一类记录改写污染且无法回退，必须前置校验类型。
+        const aiId = requireAiId(input);
+        const rows = await queryAiDoc(host, aiId);
+        const hit = rows.find((row) => String(row.id) === String(input.id));
+        if (!hit) {
+            throw contractPolicyError('record_not_found', '该 ai_id 下查不到此记录 id，拒绝覆盖（saveAiDoc 同表按 id 覆盖，传错会污染另一类记录）', { id: input.id });
+        }
+        const hitIsExecute = hit.base_type === '1' || hit.base_type === 1;
+        if (input.kind === 'storage' && hitIsExecute) {
+            throw contractPolicyError('record_type_mismatch', '目标记录是执行方式记录，不能用于存储目录写入', { id: input.id });
+        }
+        if (input.kind === 'execute' && !hitIsExecute) {
+            throw contractPolicyError('record_type_mismatch', '目标记录是存储目录记录，写入执行方式会使其语义丢失且无法回退', { id: input.id });
+        }
+        return { mode: 'overwrite', recordType: hitIsExecute ? 'execute' : 'storage' };
+    },
+    async readback(_result, input, host) {
+        const rows = await queryAiDoc(host, requireAiId(input));
+        if (input.kind === 'storage') {
+            const docId = String(input.doc_id ?? input.docId);
+            const hit = rows.find((row) => (row.base_type === undefined || row.base_type === '') && String(row.doc_id) === docId);
+            if (!hit)
+                throw new Error('回读未找到刚写入的存储目录记录');
+            return { id: hit.id, doc_id: hit.doc_id, doc_name: hit.doc_name, ...(await pageHint(host)) };
+        }
+        const executeType = String(input.execute_type ?? input.executeType);
+        const hit = rows.find((row) => (row.base_type === '1' || row.base_type === 1) && String(row.execute_type) === executeType);
+        if (!hit)
+            throw new Error('回读未找到刚写入的执行方式记录');
+        return { id: hit.id, execute_type: hit.execute_type, ...(await pageHint(host)) };
+    },
+};
+// ---------------------------------------------------------------- 智能体配置（updateAiConfig）
+const assistantAgentUpdateSpec = {
+    method: 'POST',
+    path: `${CONFIG_BASE}/updateAiConfig`,
+    validate(input) {
+        if ('display' in input) {
+            throw contractPolicyError('display_forbidden', 'display 是平台保留字段（前端卡片展示），技术上会被静默落库导致卡片消失；启用/停用只允许改 status_info，请从输入中删除 display');
+        }
+        requireAiId(input);
+        requireId(input.id, '智能体 id');
+        if (input.ai_mark !== undefined && !AI_MARKS.includes(String(input.ai_mark))) {
+            throw contractValidationError('ai_mark_invalid', `未知 ai_mark：${input.ai_mark}；合法值 ${AI_MARKS.join('/')}`);
+        }
+        if (input.status_info !== undefined && !['0', '1'].includes(String(input.status_info))) {
+            throw contractValidationError('status_info_invalid', "status_info 只能是 '0'（停用）或 '1'（启用）");
+        }
+        if (input.pzxx !== undefined)
+            input.pzxx = toJsonString(input.pzxx, 'pzxx');
+    },
+    body: (input) => bodyFrom(input, ['id', 'ai_id', 'ai_mark', 'ai_name', 'status_info', 'headline', 'prompt', 'ai_desc', 'iorder', 'pzxx']),
+    fingerprint: fingerprintFields(['id', 'ai_id', 'ai_mark', 'ai_name', 'status_info', 'headline', 'prompt', 'ai_desc', 'iorder', 'pzxx']),
+    preview: (input) => ({
+        action: '修改智能体配置',
+        id: input.id,
+        ai_mark: input.ai_mark,
+        status_info: input.status_info,
+        warning: '一次只改一个智能体；pzxx / ruleData 等附加字段会被服务端拒绝，已自动剔除 ruleData',
+    }),
+    body2: undefined,
+    async readback(_result, input, host) {
+        const rows = await queryAiConfig(host, requireAiId(input));
+        const hit = rows.find((row) => String(row.id) === String(input.id));
+        if (!hit)
+            throw new Error('回读未找到该智能体');
+        if (input.status_info !== undefined && String(hit.status_info) !== String(input.status_info)) {
+            throw new Error(`status_info 未落库：期望 ${input.status_info}，实际 ${hit.status_info}`);
+        }
+        return {
+            id: hit.id,
+            ai_mark: hit.ai_mark,
+            status_info: hit.status_info,
+            ...(await pageHint(host)),
+        };
+    },
+};
+// ---------------------------------------------------------------- 提示语（aizjid 服务端不补，必须自算最大序号 + 1）
+function nextAizjid(rows) {
+    let max = 0;
+    for (const row of rows) {
+        const n = Number(row.aizjid);
+        if (Number.isFinite(n) && n > max)
+            max = n;
+    }
+    return String(max + 1);
+}
+class TipsCreatePrepareOperation extends ContractWritePrepareOperation {
+    async execute(input, context) {
+        requireNonEmptyString(input.tsynr, 'tsynr', 2000);
+        requireAiId(input);
+        if (input.aizjid === undefined)
+            input.aizjid = nextAizjid(await queryTips(context.host, requireAiId(input)));
+        return super.execute(input, context);
+    }
+}
+class TipsCreateApplyOperation extends ContractWriteApplyOperation {
+    async execute(input, context) {
+        requireNonEmptyString(input.tsynr, 'tsynr', 2000);
+        requireAiId(input);
+        // apply 阶段重算序号：prepare 与 apply 之间可能有其他人新增了提示语。
+        if (input.aizjid === undefined)
+            input.aizjid = nextAizjid(await queryTips(context.host, requireAiId(input)));
+        return super.execute(input, context);
+    }
+}
+const tipsCreateSpec = {
+    method: 'POST',
+    path: `${TIP_BASE}/save`,
+    validate(input) {
+        requireNonEmptyString(input.tsynr, 'tsynr', 2000);
+        requireAiId(input);
+        if (input.aizjid === undefined) {
+            throw contractValidationError('aizjid_missing', 'aizjid 缺失（正常由 CLI 自动计算，请重新 prepare）');
+        }
+    },
+    body: (input) => ({ tsynr: input.tsynr, ai_id: requireAiId(input), aizjid: String(input.aizjid) }),
+    fingerprint: fingerprintFields(['tsynr', 'ai_id']),
+    preview: (input) => ({
+        action: '新增提示语',
+        tsynr: input.tsynr,
+        aizjid: input.aizjid,
+        warning: '提示语无编辑接口；不传 aizjid 会显示"序号undefined"，CLI 已自动按当前最大序号 + 1 计算',
+    }),
+    async readback(_result, input, host) {
+        const rows = await queryTips(host, requireAiId(input));
+        const hit = rows.find((row) => row.tsynr === input.tsynr);
+        if (!hit)
+            throw new Error('回读未找到刚新增的提示语');
+        if (String(hit.aizjid) !== String(input.aizjid)) {
+            throw new Error(`序号未落库：期望 ${input.aizjid}，实际 ${hit.aizjid}`);
+        }
+        return { id: hit.id, aizjid: hit.aizjid, ...(await pageHint(host)) };
+    },
+};
+const tipsDeleteSpec = {
+    method: 'POST',
+    path: `${TIP_BASE}/batchDelete`,
+    validate(input) {
+        input.ids = idList(input.ids ?? input.id, 'ids');
+        requireAiId(input);
+    },
+    body: (input) => ({ ids: input.ids, ai_id: requireAiId(input) }),
+    fingerprint: fingerprintFields(['ids', 'ai_id']),
+    preview: (input) => ({ action: '批量删除提示语', ids: input.ids, ai_id: requireAiId(input) }),
+    async readback(_result, input, host) {
+        const rows = await queryTips(host, requireAiId(input));
+        const remaining = rows.filter((row) => input.ids.includes(String(row.id)));
+        if (remaining.length)
+            throw new Error(`删除后仍能查到 ${remaining.length} 条提示语`);
+        return { removed: true, ...(await pageHint(host)) };
+    },
+};
+// ---------------------------------------------------------------- 内控规则台账（分类 → 规则 → 规则组，三步缺一不可）
+const classificationCreateSpec = {
+    method: 'POST',
+    path: `${AI_BASE}/save`,
+    validate(input) {
+        requireNonEmptyString(input.htlx, 'htlx（分类名称）', 200);
+    },
+    body: (input) => ({ htlx: input.htlx, htlxlabelid: input.htlxlabelid ?? '', type: 'contract_classification' }),
+    fingerprint: fingerprintFields(['htlx', 'htlxlabelid']),
+    preview: (input) => ({ action: '新建内控规则分类', htlx: input.htlx }),
+    async precheck(input, host) {
+        const rows = await queryClassificationList(host);
+        if (rows.some((row) => row.htlx === input.htlx)) {
+            throw contractPolicyError('classification_already_exists', '已存在同名内控规则分类，禁止重复创建', { htlx: input.htlx });
+        }
+        return { duplicateCheck: 'passed' };
+    },
+    async readback(_result, input, host) {
+        const rows = await queryClassificationList(host);
+        const hit = rows.find((row) => row.htlx === input.htlx);
+        if (!hit)
+            throw new Error('分类列表中未找到刚创建的分类');
+        return { id: hit.id, htlx: hit.htlx, ...(await pageHint(host)) };
+    },
+};
+const classificationUpdateSpec = {
+    method: 'POST',
+    path: `${AI_BASE}/update`,
+    validate(input) {
+        requireId(input.id, '分类 id');
+        requireNonEmptyString(input.htlx, 'htlx（分类名称）', 200);
+    },
+    body: (input) => ({ id: String(input.id), htlx: input.htlx }),
+    fingerprint: fingerprintFields(['id', 'htlx']),
+    preview: (input) => ({ action: '修改内控规则分类', id: input.id, htlx: input.htlx }),
+    async readback(_result, input, host) {
+        const rows = await queryClassificationList(host);
+        const hit = rows.find((row) => String(row.id) === String(input.id));
+        if (!hit)
+            throw new Error('分类列表中未找到被修改的分类');
+        return { id: hit.id, htlx: hit.htlx, ...(await pageHint(host)) };
+    },
+};
+const classificationDeleteSpec = {
+    method: 'POST',
+    path: `${AI_BASE}/delete`,
+    validate(input) {
+        input.id = requireId(input.id, '分类 id');
+    },
+    body: (input) => ({ id: String(input.id) }),
+    fingerprint: fingerprintFields(['id']),
+    preview: (input) => ({ action: '删除内控规则分类', id: input.id }),
+    async precheck(input, host) {
+        const rows = await queryRuleList(host, String(input.id));
+        if (rows.length) {
+            throw contractPolicyError('rules_remaining', `该分类下仍有 ${rows.length} 条规则，必须先批量删除规则再删分类`, { id: input.id, rules: rows.map((row) => ({ id: row.id, gzmc: row.gzmc })) });
+        }
+        return { ruleCount: 0 };
+    },
+    async readback(_result, input, host) {
+        const rows = await queryClassificationList(host);
+        if (rows.some((row) => String(row.id) === String(input.id))) {
+            throw new Error('删除接口返回成功，但分类列表中仍能查到该分类');
+        }
+        return { removed: true, ...(await pageHint(host)) };
+    },
+};
+const ruleCreateSpec = {
+    method: 'POST',
+    path: `${AI_BASE}/save`,
+    validate(input) {
+        requireNonEmptyString(input.gzmc, 'gzmc（规则名称）', 200);
+        requireNonEmptyString(input.rule_content, 'rule_content（规则内容）', 8000);
+        requireId(input.flid, 'flid（所属分类 id）');
+        if (input.enable_info !== undefined && !['0', '1'].includes(String(input.enable_info))) {
+            throw contractValidationError('enable_info_invalid', "enable_info 只能是 '0' 或 '1'");
+        }
+    },
+    body: (input) => ({
+        gzmc: input.gzmc,
+        rule_content: input.rule_content,
+        flid: String(input.flid),
+        enable_info: input.enable_info === undefined ? '1' : String(input.enable_info),
+        type: 'contract_rule_datasource',
+    }),
+    fingerprint: fingerprintFields(['gzmc', 'rule_content', 'flid', 'enable_info']),
+    preview: (input) => ({
+        action: '新建内控规则',
+        gzmc: input.gzmc,
+        flid: input.flid,
+        warning: '只建规则助手里看不到；必须再建规则组关联 Control 智能体（三步缺一不可）',
+    }),
+    async precheck(input, host) {
+        const rows = await queryClassificationList(host);
+        if (!rows.some((row) => String(row.id) === String(input.flid))) {
+            throw contractPolicyError('classification_not_found', 'flid 对应的分类不存在，先用 rule.classification.list 获取', { flid: input.flid });
+        }
+        return { classificationExists: true };
+    },
+    async readback(_result, input, host) {
+        const rows = await queryRuleList(host, String(input.flid));
+        const hit = rows.find((row) => row.gzmc === input.gzmc);
+        if (!hit)
+            throw new Error('规则列表中未找到刚创建的规则');
+        return { id: hit.id, gzmc: hit.gzmc, ...(await pageHint(host)) };
+    },
+};
+const ruleUpdateSpec = {
+    method: 'POST',
+    path: `${AI_BASE}/update`,
+    validate(input) {
+        requireId(input.id, '规则 id');
+        if (input.flid !== undefined)
+            requireId(input.flid, 'flid');
+    },
+    body: (input) => bodyFrom(input, ['id', 'gzmc', 'rule_content', 'flid', 'enable_info'], { id: String(input.id) }),
+    fingerprint: fingerprintFields(['id', 'gzmc', 'rule_content', 'flid', 'enable_info']),
+    preview: (input) => ({ action: '修改内控规则', id: input.id, gzmc: input.gzmc }),
+    async readback(_result, input, host) {
+        const rows = await queryRuleList(host, input.flid === undefined ? undefined : String(input.flid));
+        const hit = rows.find((row) => String(row.id) === String(input.id));
+        if (!hit)
+            throw new Error('规则列表中未找到被修改的规则（未传 flid 时按分类过滤可能查不到，建议补传 flid）');
+        return { id: hit.id, gzmc: hit.gzmc, ...(await pageHint(host)) };
+    },
+};
+const ruleDeleteSpec = {
+    method: 'POST',
+    path: `${AI_BASE}/delete`,
+    validate(input) {
+        input.ids = idList(input.ids ?? input.id, 'ids').join(',');
+    },
+    body: (input) => ({ ids: String(input.ids) }),
+    fingerprint: fingerprintFields(['ids']),
+    preview: (input) => ({ action: '批量删除内控规则', ids: input.ids }),
+    async readback(_result, input, host) {
+        const ids = String(input.ids).split(',');
+        const rows = await queryRuleList(host);
+        const remaining = rows.filter((row) => ids.includes(String(row.id)));
+        if (remaining.length)
+            throw new Error(`删除后规则列表中仍能查到 ${remaining.length} 条规则`);
+        return { removed: true, ...(await pageHint(host)) };
+    },
+};
+function normalizeRuleSource(value, name) {
+    let items;
+    if (typeof value === 'string') {
+        try {
+            items = JSON.parse(value);
+        }
+        catch {
+            throw contractValidationError('json_invalid', `${name} 必须是可解析的 JSON 数组字符串`);
+        }
+    }
+    else {
+        items = value;
+    }
+    if (!Array.isArray(items) || items.length === 0) {
+        throw contractValidationError('input_invalid', `${name} 必须是非空数组（元素含 id 与 name）`);
+    }
+    for (const item of items) {
+        if (!item || typeof item !== 'object' || !item.id || !item.name) {
+            throw contractValidationError('input_invalid', `${name} 的每个元素必须包含 id 与 name`);
+        }
+    }
+    return JSON.stringify(items);
+}
+const ruleGroupCreateSpec = {
+    method: 'POST',
+    path: `${AI_BASE}/saveCustomRules`,
+    validate(input) {
+        requireNonEmptyString(input.rule_flag, 'rule_flag（规则组名称）', 200);
+        requireConfigId(input, 'Control 智能体 id');
+        if (input.default_type !== undefined && !['0', '1'].includes(String(input.default_type))) {
+            throw contractValidationError('default_type_invalid', "default_type 只能是 0 或 1");
+        }
+    },
+    body: (input) => ({
+        rule_flag: input.rule_flag,
+        default_type: input.default_type === undefined ? 0 : Number(input.default_type),
+        contract_rule_source: normalizeRuleSource(input.contract_rule_source, 'contract_rule_source'),
+        config_id: requireConfigId(input, 'Control 智能体 id'),
+    }),
+    fingerprint: fingerprintFields(['rule_flag', 'default_type', 'contract_rule_source', 'config_id']),
+    preview: (input) => ({
+        action: '新建内控规则组',
+        rule_flag: input.rule_flag,
+        default_type: input.default_type ?? 0,
+        warning: 'default_type 服务端互斥：一个助手只能有一个默认组，后建/后改的会抢占默认标记（前面自动回落 0）；要当默认的放最后建',
+    }),
+    async readback(_result, input, host) {
+        const value = await host.contractRequest({
+            method: 'POST',
+            path: `${CONFIG_BASE}/queryCustomConfigRules`,
+            body: { config_id: requireConfigId(input, 'Control 智能体 id') },
+        });
+        const hit = rowsOf(value).find((row) => row.rule_flag === input.rule_flag);
+        if (!hit)
+            throw new Error('规则组列表中未找到刚创建的规则组');
+        return { id: hit.id, rule_flag: hit.rule_flag, default_type: hit.default_type, ...(await pageHint(host)) };
+    },
+};
+const ruleGroupUpdateSpec = {
+    method: 'POST',
+    path: `${AI_BASE}/updateCustomRules`,
+    validate(input) {
+        requireId(input.id, '规则组 id');
+        if (input.rule_flag !== undefined)
+            requireNonEmptyString(input.rule_flag, 'rule_flag', 200);
+        if (input.default_type !== undefined && !['0', '1'].includes(String(input.default_type))) {
+            throw contractValidationError('default_type_invalid', "default_type 只能是 0 或 1");
+        }
+    },
+    body: (input) => bodyFrom(input, ['id', 'rule_flag', 'default_type'], { id: String(input.id) }),
+    fingerprint: fingerprintFields(['id', 'rule_flag', 'default_type']),
+    preview: (input) => ({ action: '修改内控规则组', id: input.id, rule_flag: input.rule_flag }),
+    async readback(_result, input, host) {
+        if (input.config_id === undefined && input.configId === undefined)
+            return { skipped: '未提供 config_id，无法回读' };
+        const value = await host.contractRequest({
+            method: 'POST',
+            path: `${CONFIG_BASE}/queryCustomConfigRules`,
+            body: { config_id: requireConfigId(input, 'Control 智能体 id') },
+        });
+        const hit = rowsOf(value).find((row) => String(row.id) === String(input.id));
+        if (!hit)
+            throw new Error('规则组列表中未找到被修改的规则组');
+        return { id: hit.id, rule_flag: hit.rule_flag, default_type: hit.default_type, ...(await pageHint(host)) };
+    },
+};
+const ruleGroupDeleteSpec = {
+    method: 'POST',
+    path: `${CONFIG_BASE}/batchDeleteCustomRules`,
+    validate(input) {
+        input.ids = idList(input.ids ?? input.id, 'ids');
+    },
+    body: (input) => ({ ids: input.ids }),
+    fingerprint: fingerprintFields(['ids']),
+    preview: (input) => ({ action: '批量删除内控规则组', ids: input.ids }),
+    async readback(_result, input, host) {
+        if (input.config_id === undefined && input.configId === undefined)
+            return { skipped: '未提供 config_id，无法回读' };
+        const value = await host.contractRequest({
+            method: 'POST',
+            path: `${CONFIG_BASE}/queryCustomConfigRules`,
+            body: { config_id: requireConfigId(input, 'Control 智能体 id') },
+        });
+        const remaining = rowsOf(value).filter((row) => input.ids.includes(String(row.id)));
+        if (remaining.length)
+            throw new Error(`删除后仍能查到 ${remaining.length} 个规则组`);
+        return { removed: true, ...(await pageHint(host)) };
+    },
+};
+// ---------------------------------------------------------------- 要素抽取（element_content 与 element_mxb 是两份重复数据，都要传）
+const elementCreateSpec = {
+    method: 'POST',
+    path: `${AI_BASE}/element/saveElementRules`,
+    validate(input) {
+        requireNonEmptyString(input.element_name, 'element_name', 200);
+        requireConfigId(input, 'Extract 智能体 id');
+        if (input.default_type !== undefined && !['0', '1'].includes(String(input.default_type))) {
+            throw contractValidationError('default_type_invalid', "default_type 只能是 0 或 1");
+        }
+        let mxb;
+        if (typeof input.element_mxb === 'string') {
+            try {
+                mxb = JSON.parse(input.element_mxb);
+            }
+            catch {
+                throw contractValidationError('json_invalid', 'element_mxb 必须是可解析的 JSON 数组字符串');
+            }
+        }
+        else {
+            mxb = input.element_mxb;
+        }
+        if (!Array.isArray(mxb) || mxb.length === 0) {
+            // 传空数组服务端报「系统错误」，必须前置拦截。
+            throw contractValidationError('input_invalid', 'element_mxb 必须是非空数组（元素含 name/fieldName/dbField）');
+        }
+        for (const item of mxb) {
+            if (!item || typeof item !== 'object' || !item.name || !item.fieldName || !item.dbField) {
+                throw contractValidationError('input_invalid', 'element_mxb 的每个元素必须包含 name、fieldName、dbField 三键');
+            }
+        }
+        input.element_mxb = JSON.stringify(mxb);
+        if (input.element_content === undefined || input.element_content === '') {
+            input.element_content = mxb.map((item) => item.name).join('\n');
+        }
+    },
+    body: (input) => ({
+        element_name: input.element_name,
+        element_content: String(input.element_content),
+        element_mxb: String(input.element_mxb),
+        default_type: input.default_type === undefined ? 1 : Number(input.default_type),
+        config_id: requireConfigId(input, 'Extract 智能体 id'),
+    }),
+    fingerprint: fingerprintFields(['element_name', 'element_content', 'element_mxb', 'default_type', 'config_id']),
+    preview: (input) => ({
+        action: '新增要素抽取集合',
+        element_name: input.element_name,
+        elementCount: JSON.parse(String(input.element_mxb)).length,
+        warning: 'element_content 与 element_mxb 是两份重复数据，必须都传（页面读 content，字段映射读 mxb）；要素集合无更新接口，改动需先删后增',
+    }),
+    async readback(_result, input, host) {
+        const value = await host.contractRequest({
+            method: 'POST',
+            path: `${CONFIG_BASE}/queryElementConfigRules`,
+            body: { config_id: requireConfigId(input, 'Extract 智能体 id') },
+        });
+        const hit = rowsOf(value).find((row) => row.element_name === input.element_name);
+        if (!hit)
+            throw new Error('要素集合列表中未找到刚创建的集合');
+        return { id: hit.id, element_name: hit.element_name, ...(await pageHint(host)) };
+    },
+};
+const elementDeleteSpec = {
+    method: 'POST',
+    path: `${CONFIG_BASE}/batchDeleteElementRules`,
+    validate(input) {
+        input.ids = idList(input.ids ?? input.id, 'ids');
+    },
+    body: (input) => ({ ids: input.ids }),
+    fingerprint: fingerprintFields(['ids']),
+    preview: (input) => ({ action: '批量删除要素抽取集合', ids: input.ids }),
+    async readback(_result, input, host) {
+        if (input.config_id === undefined && input.configId === undefined)
+            return { skipped: '未提供 config_id，无法回读' };
+        const value = await host.contractRequest({
+            method: 'POST',
+            path: `${CONFIG_BASE}/queryElementConfigRules`,
+            body: { config_id: requireConfigId(input, 'Extract 智能体 id') },
+        });
+        const remaining = rowsOf(value).filter((row) => input.ids.includes(String(row.id)));
+        if (remaining.length)
+            throw new Error(`删除后仍能查到 ${remaining.length} 个要素集合`);
+        return { removed: true, ...(await pageHint(host)) };
+    },
+};
+// ---------------------------------------------------------------- 助手关联流程
+function validateFlowInput(input, requireRecordId) {
+    requireAiId(input);
+    requireId(input.flowId, 'flowId（流程 id）');
+    requireId(input.rule_config_id ?? input.ruleConfigId, 'rule_config_id（Control 智能体 id）');
+    if (requireRecordId)
+        requireId(input.id, '记录 id');
+    const showPosition = input.showPosition === undefined ? undefined : String(input.showPosition);
+    if (showPosition !== undefined && !['1', '2', '3'].includes(showPosition)) {
+        throw contractValidationError('show_position_invalid', "showPosition 只能是 1（更多菜单）/ 2（右上角）/ 3（字段上）");
+    }
+    // 源资料 NEED-CONFIRM 三场景：不满足就直接拦截，让用户回补参数。
+    if (showPosition === '3' && (input.fieldId === undefined || input.fieldId === '')) {
+        throw contractValidationError('field_id_required', 'showPosition=3（字段上）时 fieldId 必传；请向用户确认来源字段后再 prepare');
+    }
+    const termConfig = input.term_config;
+    if (termConfig && typeof termConfig === 'object' && !Array.isArray(termConfig) && (termConfig.contractTypeField === undefined || termConfig.contractTypeField === '')) {
+        throw contractValidationError('contract_type_field_required', 'term_config 缺少 contractTypeField（合同类型字段 id）；请向用户确认后再 prepare');
+    }
+    if (input.key_config !== undefined) {
+        let parsed = input.key_config;
+        if (typeof parsed === 'string') {
+            try {
+                parsed = JSON.parse(parsed);
+            }
+            catch {
+                throw contractValidationError('json_invalid', 'key_config 必须是可解析的 JSON');
+            }
+        }
+        const empty = parsed === null
+            || (Array.isArray(parsed) && parsed.length === 0)
+            || (typeof parsed === 'object' && !Array.isArray(parsed) && Object.keys(parsed).length === 0);
+        if (empty) {
+            throw contractValidationError('key_config_required', 'key_config 未指定任何关键词组；请先用 contract.assistant.keygroup.search 检索后确认');
+        }
+    }
+    const customRules = input.customRules;
+    if (customRules && typeof customRules === 'object' && !Array.isArray(customRules) && String(customRules.type) === '0') {
+        throw contractPolicyError('custom_rules_type_unsupported', 'customRules type=0（自定义内控规则）不被支持，请阻断用户并改用 type=1（指定规则）或 type=2（按合同类型过滤）');
+    }
+    if (input.showPosition === undefined)
+        input.showPosition = '2';
+    if (input.config !== undefined)
+        input.config = toJsonString(input.config, 'config');
+    for (const key of ['risk_review', 'customRules', 'key_config', 'consult_config', 'term_config', 'fieldMapping']) {
+        if (input[key] !== undefined)
+            input[key] = toJsonString(input[key], key);
+    }
+}
+function flowBody(input, includeId) {
+    const body = {
+        toolId: FLOW_TOOL_ID,
+        aiId: requireAiId(input),
+        rule_config_id: String(input.rule_config_id ?? input.ruleConfigId),
+        flowId: String(input.flowId),
+        showPosition: String(input.showPosition),
+        openMode: input.openMode === undefined ? 1 : input.openMode,
+        config: input.config === undefined ? '[]' : String(input.config),
+    };
+    if (includeId)
+        body.id = String(input.id);
+    for (const key of ['risk_review', 'customRules', 'key_config', 'consult_config', 'term_config', 'fieldMapping']) {
+        if (input[key] !== undefined)
+            body[key] = input[key];
+    }
+    for (const key of ['elementExtractConfig', 'fieldId', 'fieldName']) {
+        if (input[key] !== undefined)
+            body[key] = input[key];
+    }
+    return body;
+}
+const flowSaveSpec = {
+    method: 'POST',
+    path: `${PERMISSION_BASE}/save`,
+    validate(input) {
+        validateFlowInput(input, false);
+    },
+    body: (input) => flowBody(input, false),
+    fingerprint: fingerprintFields(['ai_id', 'aiId', 'flowId', 'rule_config_id', 'ruleConfigId', 'showPosition', 'openMode', 'config', 'risk_review', 'customRules', 'key_config', 'consult_config', 'term_config', 'fieldMapping', 'elementExtractConfig', 'fieldId', 'fieldName']),
+    preview: (input) => ({
+        action: '新增助手关联流程',
+        aiId: input.ai_id ?? input.aiId,
+        flowId: input.flowId,
+        showPosition: input.showPosition,
+        warning: '一个流程全局只能绑定一次（跨助手唯一）；绑定前先用 contract.assistant.flow.list 排查',
+    }),
+    async readback(_result, input, host) {
+        const rows = await queryFlowList(host, requireAiId(input), String(input.rule_config_id ?? input.ruleConfigId));
+        const hit = rows.find((row) => String(row.flowId) === String(input.flowId));
+        if (!hit)
+            throw new Error('关联流程列表中未找到刚创建的绑定');
+        return { id: hit.id, flowId: hit.flowId, ...(await pageHint(host)) };
+    },
+};
+const flowUpdateSpec = {
+    method: 'POST',
+    path: `${PERMISSION_BASE}/modify`,
+    pathOf: (input) => `${PERMISSION_BASE}/modify/${requireId(input.id, '记录 id')}`,
+    validate(input) {
+        validateFlowInput(input, true);
+    },
+    body: (input) => flowBody(input, true),
+    fingerprint: fingerprintFields(['id', 'ai_id', 'aiId', 'flowId', 'rule_config_id', 'ruleConfigId', 'showPosition', 'openMode', 'config', 'risk_review', 'customRules', 'key_config', 'consult_config', 'term_config', 'fieldMapping', 'elementExtractConfig', 'fieldId', 'fieldName']),
+    preview: (input) => ({ action: '修改助手关联流程', id: input.id, flowId: input.flowId, showPosition: input.showPosition }),
+    async readback(_result, input, host) {
+        const rows = await queryFlowList(host, requireAiId(input), String(input.rule_config_id ?? input.ruleConfigId));
+        const hit = rows.find((row) => String(row.id) === String(input.id));
+        if (!hit)
+            throw new Error('关联流程列表中未找到被修改的绑定');
+        return { id: hit.id, flowId: hit.flowId, showPosition: hit.showPosition, ...(await pageHint(host)) };
+    },
+};
+const flowDeleteSpec = {
+    method: 'POST',
+    path: `${PERMISSION_BASE}/delete`,
+    validate(input) {
+        input.ids = idList(input.ids ?? input.id, 'ids').join(',');
+        requireAiId(input);
+        requireId(input.rule_config_id ?? input.ruleConfigId, 'rule_config_id（回读复核用）');
+    },
+    body: (input) => ({
+        ids: String(input.ids),
+        // 删除不带 type 会返回 success 但实际不删除，CLI 强制补上。
+        type: FLOW_DELETE_TYPE,
+    }),
+    fingerprint: fingerprintFields(['ids', 'ai_id', 'aiId']),
+    preview: (input) => ({ action: '删除助手关联流程', ids: input.ids, type: FLOW_DELETE_TYPE }),
+    async readback(_result, input, host) {
+        const ids = String(input.ids).split(',');
+        const rows = await queryFlowList(host, requireAiId(input), String(input.rule_config_id ?? input.ruleConfigId));
+        const remaining = rows.filter((row) => ids.includes(String(row.id)));
+        if (remaining.length)
+            throw new Error(`删除后关联流程列表中仍能查到 ${remaining.length} 条绑定（疑似缺 type 的假成功）`);
+        return { removed: true, ...(await pageHint(host)) };
+    },
+};
+// ---------------------------------------------------------------- 汇总
+export const contractAssistantOperations = [
+    contractAssistantInitOperation,
+    contractAssistantMetaOperation,
+    contractAssistantListOperation,
+    contractAssistantDocQueryOperation,
+    contractAssistantConfigQueryOperation,
+    contractAssistantTipsQueryOperation,
+    contractAssistantDocFolderSearchOperation,
+    contractAssistantKeygroupSearchOperation,
+    contractAssistantClassificationListOperation,
+    contractAssistantRuleListOperation,
+    contractAssistantRuleGroupQueryOperation,
+    contractAssistantElementQueryOperation,
+    contractAssistantFlowListOperation,
+    ...writePair('contract.assistant.create', assistantCreateSpec),
+    ...writePair('contract.assistant.delete', assistantDeleteSpec),
+    ...writePair('contract.assistant.doc.save', assistantDocSaveSpec),
+    ...writePair('contract.assistant.agent.update', assistantAgentUpdateSpec),
+    ...tipsWritePair(tipsCreateSpec),
+    ...writePair('contract.assistant.tips.delete', tipsDeleteSpec),
+    ...writePair('contract.assistant.rule.classification.create', classificationCreateSpec),
+    ...writePair('contract.assistant.rule.classification.update', classificationUpdateSpec),
+    ...writePair('contract.assistant.rule.classification.delete', classificationDeleteSpec),
+    ...writePair('contract.assistant.rule.create', ruleCreateSpec),
+    ...writePair('contract.assistant.rule.update', ruleUpdateSpec),
+    ...writePair('contract.assistant.rule.delete', ruleDeleteSpec),
+    ...writePair('contract.assistant.rule.group.create', ruleGroupCreateSpec),
+    ...writePair('contract.assistant.rule.group.update', ruleGroupUpdateSpec),
+    ...writePair('contract.assistant.rule.group.delete', ruleGroupDeleteSpec),
+    ...writePair('contract.assistant.element.create', elementCreateSpec),
+    ...writePair('contract.assistant.element.delete', elementDeleteSpec),
+    ...writePair('contract.assistant.flow.save', flowSaveSpec),
+    ...writePair('contract.assistant.flow.update', flowUpdateSpec),
+    ...writePair('contract.assistant.flow.delete', flowDeleteSpec),
+];