@guanwenai/high-tech-project-cli 0.1.0

package/scripts/services/sop.mjs

@@ -0,0 +1,592 @@
+import { randomUUID } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { mkdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, extname } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+import { CliError } from '../core/errors.mjs';
+import { resolveWithinBase } from '../core/files.mjs';
+
+const HIGH_TECH_ITEM_TYPE = 'HIGH_TECH';
+const BASE_CONTEXT = ['gatewayUrl'];
+const PROJECT_CONTEXT = [...BASE_CONTEXT, 'uuid'];
+const AGENT_WIKI_BASE = '/api/internal/v1/project-writing/sop/agent-wiki';
+const COMMON_REMINDER = '必须以远端 SOP Wiki 返回内容作为唯一事实来源，不得自行编造流程、模板、撰写策略或评审规则。';
+
+function objectInput(input) {
+  if (input === null || Array.isArray(input) || typeof input !== 'object') {
+    throw new CliError('ARGUMENT_INVALID', '命令输入必须是对象');
+  }
+  return input;
+}
+
+function valueOf(input, snakeName, camelName = snakeName) {
+  return input[snakeName] ?? input[camelName];
+}
+
+function requiredString(value, field) {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new CliError('ARGUMENT_INVALID', `${field} 不能为空`);
+  }
+  return value.trim();
+}
+
+function configTypeInput(input) {
+  const value = objectInput(input);
+  const nodeCode = requiredString(valueOf(value, 'node_code', 'nodeCode'), 'node_code');
+  const configType = requiredString(valueOf(value, 'config_type', 'configType'), 'config_type').toUpperCase();
+  if (!['MIDDLEWARE', 'FINAL_FILE'].includes(configType)) {
+    throw new CliError('ARGUMENT_INVALID', 'config_type 必须是 MIDDLEWARE 或 FINAL_FILE');
+  }
+  return { ...value, nodeCode, configType };
+}
+
+function nodeCodeInput(input) {
+  const value = objectInput(input);
+  return {
+    ...value,
+    nodeCode: requiredString(valueOf(value, 'node_code', 'nodeCode'), 'node_code'),
+  };
+}
+
+function optionalPositiveId(value, field) {
+  if (value === undefined || value === null) return undefined;
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new CliError('ARGUMENT_INVALID', `${field} 必须是正整数`);
+  }
+  return value;
+}
+
+function outputStrategyInput(input) {
+  const value = configTypeInput(input);
+  const contextData = valueOf(value, 'context_data', 'contextData');
+  if (contextData !== undefined
+    && (contextData === null || Array.isArray(contextData) || typeof contextData !== 'object')) {
+    throw new CliError('ARGUMENT_INVALID', 'context_data 必须是对象');
+  }
+  return {
+    nodeCode: value.nodeCode,
+    configType: value.configType,
+    selectedOutputTemplateId: optionalPositiveId(
+      valueOf(value, 'selected_output_template_id', 'selectedOutputTemplateId'),
+      'selected_output_template_id',
+    ),
+    selectedScenarioId: optionalPositiveId(
+      valueOf(value, 'selected_scenario_id', 'selectedScenarioId'),
+      'selected_scenario_id',
+    ),
+    contextData,
+  };
+}
+
+function templateFileInput(input) {
+  const value = objectInput(input);
+  const outputTemplateId = optionalPositiveId(
+    valueOf(value, 'output_template_id', 'outputTemplateId'),
+    'output_template_id',
+  );
+  if (outputTemplateId === undefined) {
+    throw new CliError('ARGUMENT_INVALID', 'output_template_id 不能为空');
+  }
+  const targetPath = relativePathValue(
+    valueOf(value, 'target_path', 'targetPath'),
+    'target_path',
+  );
+  if (!targetPath.startsWith('.guanwen/sop-templates/')) {
+    throw new CliError('ARGUMENT_INVALID', 'target_path 必须位于 .guanwen/sop-templates/ 目录');
+  }
+  const overwriteValue = valueOf(value, 'confirm_overwrite', 'confirmOverwrite');
+  if (overwriteValue !== undefined && typeof overwriteValue !== 'boolean') {
+    throw new CliError('ARGUMENT_INVALID', 'confirm_overwrite 必须是布尔值');
+  }
+  return { outputTemplateId, targetPath, confirmOverwrite: overwriteValue === true };
+}
+
+function normalizedFileFormat(template, targetPath) {
+  const raw = template?.fileFormat || extname(template?.fileName || targetPath);
+  const normalized = String(raw ?? '').trim().replace(/^\./u, '').toUpperCase();
+  const format = normalized === 'WORD' ? 'DOCX' : normalized === 'EXCEL' ? 'XLSX' : normalized;
+  if (!['DOCX', 'XLSX'].includes(format)) {
+    throw new CliError('BUSINESS_ERROR', `模板文件格式不支持，仅支持 DOCX 和 XLSX: ${format}`);
+  }
+  const targetFormat = extname(targetPath).slice(1).toUpperCase();
+  if (targetFormat !== format) {
+    throw new CliError('ARGUMENT_INVALID', `target_path 扩展名必须是 .${format.toLowerCase()}`);
+  }
+  return format;
+}
+
+async function assertTargetWritable(relativePath, baseDir, resolvedPath, confirmOverwrite) {
+  try {
+    await stat(resolvedPath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false;
+    throw new CliError('FILE_WRITE_FAILED', '无法检查模板目标文件', {
+      relativePath, baseDir, resolvedPath,
+    });
+  }
+  if (confirmOverwrite) return true;
+  throw new CliError('FILE_ALREADY_EXISTS', '模板目标文件已存在，禁止自动覆盖', {
+    relativePath, baseDir, resolvedPath,
+  });
+}
+
+async function downloadTemplate({ client, template, targetPath, baseDir, confirmOverwrite }) {
+  if (typeof baseDir !== 'string' || !baseDir) {
+    throw new CliError('CONFIG_MISSING', '模板下载缺少 baseDir');
+  }
+  const resolvedPath = resolveWithinBase(targetPath, baseDir);
+  const targetExists = await assertTargetWritable(
+    targetPath,
+    baseDir,
+    resolvedPath,
+    confirmOverwrite,
+  );
+  await mkdir(dirname(resolvedPath), { recursive: true });
+  const temporaryPath = `${resolvedPath}.${randomUUID()}.tmp`;
+  const response = await client.download({
+    method: 'POST',
+    path: '/api/project-writing/file/download',
+    body: { fileUrl: template.fileUrl, fileName: template.fileName },
+  });
+  if (!response?.body || typeof response.body.getReader !== 'function') {
+    throw new CliError('FILE_WRITE_FAILED', '模板下载响应缺少文件流', {
+      relativePath: targetPath, baseDir, resolvedPath,
+    });
+  }
+  let bytesWritten = 0;
+  const counter = new Transform({
+    transform(chunk, _encoding, callback) {
+      bytesWritten += chunk.length;
+      callback(null, chunk);
+    },
+  });
+  try {
+    await pipeline(
+      Readable.fromWeb(response.body),
+      counter,
+      createWriteStream(temporaryPath, { flags: 'wx' }),
+    );
+    if (bytesWritten <= 0) {
+      throw new Error('模板文件内容为空');
+    }
+    try {
+      await rename(temporaryPath, resolvedPath);
+    } catch (error) {
+      if (!targetExists || !confirmOverwrite) throw error;
+      await rm(resolvedPath, { force: true });
+      await rename(temporaryPath, resolvedPath);
+    }
+  } catch (error) {
+    await rm(temporaryPath, { force: true }).catch(() => undefined);
+    throw new CliError('FILE_WRITE_FAILED', '模板下载或写入失败', {
+      relativePath: targetPath,
+      baseDir,
+      resolvedPath,
+      cause: error instanceof Error ? error.message : String(error),
+    });
+  }
+  return { resolvedPath, bytesWritten };
+}
+
+function relativePathValue(value, field) {
+  const normalized = requiredString(value, field).replaceAll('\\', '/');
+  if (normalized.startsWith('/')
+    || /^[a-zA-Z]:/u.test(normalized)
+    || normalized.split('/').some((part) => part === '..')) {
+    throw new CliError('ARGUMENT_INVALID', `${field} 必须是工作目录内的相对路径`);
+  }
+  return normalized;
+}
+
+function auditInput(input) {
+  const value = objectInput(input);
+  const nodeName = requiredString(valueOf(value, 'node_name', 'nodeName'), 'node_name');
+  if (nodeName === '.' || nodeName === '..' || /[\\/]/u.test(nodeName)) {
+    throw new CliError('ARGUMENT_INVALID', 'node_name 必须是单个工作空间目录名');
+  }
+  const outputTemplateId = optionalPositiveId(
+    valueOf(value, 'output_template_id', 'outputTemplateId'),
+    'output_template_id',
+  );
+  if (outputTemplateId === undefined) {
+    throw new CliError('ARGUMENT_INVALID', 'output_template_id 不能为空');
+  }
+  const templatePath = relativePathValue(
+    valueOf(value, 'template_path', 'templatePath'),
+    'template_path',
+  );
+  if (!templatePath.startsWith('.guanwen/sop-templates/')) {
+    throw new CliError('ARGUMENT_INVALID', 'template_path 必须位于 .guanwen/sop-templates/ 目录');
+  }
+  const artifactPath = relativePathValue(
+    valueOf(value, 'artifact_path', 'artifactPath'),
+    'artifact_path',
+  );
+  const artifactParts = artifactPath.split('/');
+  if (artifactParts.length !== 2 || artifactParts[0] !== nodeName || !artifactParts[1]) {
+    throw new CliError('ARGUMENT_INVALID', 'artifact_path 必须符合 <node_name>/<业务文件名>');
+  }
+  const fileFormat = requiredString(
+    valueOf(value, 'file_format', 'fileFormat'),
+    'file_format',
+  ).replace(/^\./u, '').toUpperCase();
+  if (!['DOCX', 'XLSX'].includes(fileFormat)) {
+    throw new CliError('ARGUMENT_INVALID', 'file_format 必须是 DOCX 或 XLSX');
+  }
+  if (extname(templatePath).slice(1).toUpperCase() !== fileFormat
+    || extname(artifactPath).slice(1).toUpperCase() !== fileFormat) {
+    throw new CliError('ARGUMENT_INVALID', '模板和交付物扩展名必须与 file_format 一致');
+  }
+  const fillResults = valueOf(value, 'fill_results', 'fillResults');
+  const remainingPlaceholders = valueOf(value, 'remaining_placeholders', 'remainingPlaceholders');
+  const formatRisks = valueOf(value, 'format_risks', 'formatRisks');
+  if (!Array.isArray(fillResults)
+    || !Array.isArray(remainingPlaceholders)
+    || !Array.isArray(formatRisks)) {
+    throw new CliError(
+      'ARGUMENT_INVALID',
+      'fill_results、remaining_placeholders 和 format_risks 必须是数组',
+    );
+  }
+  const officecliValidation = valueOf(value, 'officecli_validation', 'officecliValidation');
+  if (officecliValidation === null
+    || Array.isArray(officecliValidation)
+    || typeof officecliValidation !== 'object'
+    || officecliValidation.valid !== true) {
+    throw new CliError('ARGUMENT_INVALID', 'officecli_validation.valid 必须为 true');
+  }
+  const overwriteValue = valueOf(value, 'confirm_overwrite', 'confirmOverwrite');
+  if (overwriteValue !== undefined && typeof overwriteValue !== 'boolean') {
+    throw new CliError('ARGUMENT_INVALID', 'confirm_overwrite 必须是布尔值');
+  }
+  return {
+    nodeName,
+    outputTemplateId,
+    templatePath,
+    artifactPath,
+    fileFormat,
+    fillResults,
+    remainingPlaceholders,
+    formatRisks,
+    officecliValidation,
+    confirmOverwrite: overwriteValue === true,
+  };
+}
+
+async function requireRegularFile(relativePath, baseDir) {
+  const resolvedPath = resolveWithinBase(relativePath, baseDir);
+  try {
+    const value = await stat(resolvedPath);
+    if (!value.isFile()) throw new Error('目标不是文件');
+  } catch (error) {
+    throw new CliError('FILE_NOT_FOUND', 'SOP 审计所需文件不存在', {
+      relativePath,
+      baseDir,
+      resolvedPath,
+      cause: error instanceof Error ? error.message : String(error),
+    });
+  }
+  return resolvedPath;
+}
+
+async function writeAudit(input, baseDir) {
+  if (typeof baseDir !== 'string' || !baseDir) {
+    throw new CliError('CONFIG_MISSING', 'SOP 审计缺少 baseDir');
+  }
+  await requireRegularFile(input.templatePath, baseDir);
+  await requireRegularFile(input.artifactPath, baseDir);
+  const auditPath = `${input.nodeName}/audit.json`;
+  const resolvedPath = resolveWithinBase(auditPath, baseDir);
+  try {
+    await stat(resolvedPath);
+    if (!input.confirmOverwrite) {
+      throw new CliError('FILE_ALREADY_EXISTS', '审计文件已存在，覆盖前必须取得用户明确确认', {
+        relativePath: auditPath, baseDir, resolvedPath,
+      });
+    }
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    if (error?.code !== 'ENOENT') {
+      throw new CliError('FILE_WRITE_FAILED', '无法检查审计目标文件', {
+        relativePath: auditPath, baseDir, resolvedPath,
+      });
+    }
+  }
+  const audit = {
+    nodeName: input.nodeName,
+    outputTemplateId: input.outputTemplateId,
+    templatePath: input.templatePath,
+    finalArtifactPath: input.artifactPath,
+    fileFormat: input.fileFormat,
+    fillResults: input.fillResults,
+    remainingPlaceholders: input.remainingPlaceholders,
+    formatRisks: input.formatRisks,
+    officecliValidation: input.officecliValidation,
+    generatedAt: new Date().toISOString(),
+  };
+  const temporaryPath = `${resolvedPath}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporaryPath, `${JSON.stringify(audit, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+    await rename(temporaryPath, resolvedPath);
+  } catch (error) {
+    await rm(temporaryPath, { force: true }).catch(() => undefined);
+    throw new CliError('FILE_WRITE_FAILED', 'SOP 审计文件写入失败', {
+      relativePath: auditPath,
+      baseDir,
+      resolvedPath,
+      cause: error instanceof Error ? error.message : String(error),
+    });
+  }
+  return {
+    auditPath,
+    templatePath: input.templatePath,
+    finalArtifactPath: input.artifactPath,
+  };
+}
+
+function splitRegion(value) {
+  const region = typeof value === 'string' ? value.trim() : '';
+  if (!region) return { province: '', city: '' };
+  const parts = region.split(/[\s－_/|,，、-]+/u).map((part) => part.trim()).filter(Boolean);
+  if (parts.length >= 2) return { province: parts[0], city: parts[1] };
+  const provinceIndex = region.indexOf('省');
+  if (provinceIndex > 0 && provinceIndex + 1 < region.length) {
+    return { province: region.slice(0, provinceIndex + 1), city: region.slice(provinceIndex + 1) };
+  }
+  const cityIndex = region.indexOf('市');
+  if (cityIndex > 0 && cityIndex + 1 < region.length) {
+    return { province: region.slice(0, cityIndex + 1), city: region.slice(cityIndex + 1) };
+  }
+  return { province: region, city: '' };
+}
+
+function filterPrecheck(precheck, configType) {
+  if (precheck === null || typeof precheck !== 'object') return precheck;
+  const matches = (item) => String(item?.configType ?? '').trim().toUpperCase() === configType;
+  const materials = Array.isArray(precheck.materials) ? precheck.materials.filter(matches) : [];
+  const groups = Array.isArray(precheck.groups)
+    ? precheck.groups.filter(matches).map((group) => ({
+      configType: group.configType,
+      checkStrategy: group.checkStrategy,
+      materials: Array.isArray(group.materials) ? group.materials.filter(matches) : [],
+    }))
+    : [];
+  return {
+    nodeCode: precheck.nodeCode,
+    nodeName: precheck.nodeName,
+    configured: materials.length > 0,
+    checkStrategies: precheck.checkStrategies,
+    materials,
+    groups,
+    missingReason: materials.length > 0 ? null : `未配置 ${configType} 前置检查材料`,
+  };
+}
+
+function wrap(data, reminders, nextStepHint) {
+  return {
+    data,
+    system_reminder: [COMMON_REMINDER, ...reminders],
+    next_step_hint: nextStepHint,
+  };
+}
+
+export const commands = [
+  {
+    name: 'sop.node-list',
+    method: 'POST',
+    path: `${AGENT_WIKI_BASE}/node-list`,
+    idempotent: true,
+    multipart: false,
+    requiredContext: BASE_CONTEXT,
+    validate: objectInput,
+    handler: async ({ client, context }) => {
+      const data = await client.request({
+        method: 'POST',
+        path: `${AGENT_WIKI_BASE}/node-list`,
+        idempotent: true,
+        body: {
+          ...(context.tenantCode ? { tenantCode: context.tenantCode } : {}),
+          itemType: HIGH_TECH_ITEM_TYPE,
+        },
+      });
+      return wrap(data, [
+        '必须根据返回的 nodeName、nodeRule、entryCondition 和 summary 识别事项节点，不得使用本地硬编码节点。',
+        '存在多个候选节点时必须停止并让用户选择，不得自行猜测。',
+      ], '选定唯一节点后，调用 sop.precheck-get 获取对应配置类型的前置检查。');
+    },
+  },
+  {
+    name: 'sop.precheck-get',
+    method: 'POST',
+    path: `${AGENT_WIKI_BASE}/node-detail`,
+    idempotent: true,
+    multipart: false,
+    requiredContext: BASE_CONTEXT,
+    validate: configTypeInput,
+    handler: async ({ client, context, input }) => {
+      const detail = await client.request({
+        method: 'POST',
+        path: `${AGENT_WIKI_BASE}/node-detail`,
+        idempotent: true,
+        body: {
+          ...(context.tenantCode ? { tenantCode: context.tenantCode } : {}),
+          itemType: HIGH_TECH_ITEM_TYPE,
+          nodeCode: input.nodeCode,
+          includeSections: ['PRECHECK'],
+        },
+      });
+      const data = filterPrecheck(detail?.precheck ?? null, input.configType);
+      return wrap(data, [
+        '必须分别处理 REQUIRED 必备材料和已配置的 PRE_RESULT 前置成果材料，不得自行增加检查项。',
+        '必备材料缺失或定稿所需中间件缺失时不得进入下一阶段；非必备材料缺失也必须先向用户确认。',
+      ], '前置检查通过后，调用 sop.output-strategy-resolve 解析模板与撰写策略。');
+    },
+  },
+  {
+    name: 'sop.output-strategy-resolve',
+    method: 'POST',
+    path: `${AGENT_WIKI_BASE}/resolve-output-strategy`,
+    idempotent: true,
+    multipart: false,
+    requiredContext: PROJECT_CONTEXT,
+    validate: outputStrategyInput,
+    handler: async ({ client, context, input }) => {
+      const customer = await client.request({
+        method: 'POST',
+        path: '/api/internal/v1/project-writing/customer/detail',
+        idempotent: true,
+        body: {
+          ...(context.tenantCode ? { tenantCode: context.tenantCode } : {}),
+          uuid: context.uuid,
+        },
+      });
+      const { province, city } = splitRegion(customer?.region);
+      const industry = typeof customer?.industry === 'string' ? customer.industry.trim() : '';
+      if (!province || !city || !industry) {
+        throw new CliError('BUSINESS_ERROR', '当前项目缺少完整省市或行业信息，请先补充客户详情', {
+          missing: [!province && 'province', !city && 'city', !industry && 'industry'].filter(Boolean),
+        });
+      }
+      const body = {
+        ...(context.tenantCode ? { tenantCode: context.tenantCode } : {}),
+        itemType: HIGH_TECH_ITEM_TYPE,
+        nodeCode: input.nodeCode,
+        configType: input.configType,
+        province,
+        city,
+        industry,
+        ...(input.selectedOutputTemplateId === undefined
+          ? {} : { selectedOutputTemplateId: input.selectedOutputTemplateId }),
+        ...(input.selectedScenarioId === undefined
+          ? {} : { selectedScenarioId: input.selectedScenarioId }),
+        ...(input.contextData === undefined ? {} : { contextData: input.contextData }),
+      };
+      const data = await client.request({
+        method: 'POST',
+        path: `${AGENT_WIKI_BASE}/resolve-output-strategy`,
+        idempotent: true,
+        body,
+      });
+      return wrap(data, [
+        '必须先读取 resolveStatus：RESOLVED 才能继续；NEED_TEMPLATE_SELECTION 或 NEED_STRATEGY_SELECTION 必须让用户选择；NO_TEMPLATE 或 NO_STRATEGY 必须停止。',
+        'RESOLVED 后必须逐项检查 resolvedOutputs；可明确对应的已有成果可以复用，缺失成果才下载模板，不得漏做、合并或新增。',
+        '最终文件必须写入以当前节点 nodeName 命名的首级目录；覆盖任何已有文件前必须取得用户明确确认。',
+      ], 'RESOLVED 后先检查已有成果；缺失成果调用 sop.template-file-get，全部成果就绪后调用 sop.review-get。');
+    },
+  },
+  {
+    name: 'sop.template-file-get',
+    method: 'POST',
+    path: '/api/internal/v1/project-writing/sop/template-file/get',
+    idempotent: false,
+    multipart: false,
+    requiredContext: PROJECT_CONTEXT,
+    validate: templateFileInput,
+    handler: async ({ client, context, input, baseDir }) => {
+      const template = await client.request({
+        method: 'POST',
+        path: '/api/internal/v1/project-writing/sop/template-file/get',
+        idempotent: true,
+        body: {
+          ...(context.tenantCode ? { tenantCode: context.tenantCode } : {}),
+          contextId: context.uuid,
+          outputTemplateId: input.outputTemplateId,
+          targetPath: input.targetPath,
+        },
+      });
+      if (typeof template?.fileUrl !== 'string' || !template.fileUrl.trim()
+        || typeof template?.fileName !== 'string' || !template.fileName.trim()) {
+        throw new CliError('BUSINESS_ERROR', '模板文件缺少下载地址或文件名');
+      }
+      const fileFormat = normalizedFileFormat(template, input.targetPath);
+      const { bytesWritten } = await downloadTemplate({
+        client,
+        template,
+        targetPath: input.targetPath,
+        baseDir,
+        confirmOverwrite: input.confirmOverwrite,
+      });
+      const extension = fileFormat.toLowerCase();
+      const data = {
+        ...template,
+        workspacePath: input.targetPath,
+        fileFormat,
+        recommendedSkillCode: 'officecli',
+        recommendedSkillPath: 'load_skill(name: "officecli")',
+        templateRuntimePath: input.targetPath,
+        finalPathRule: `<当前事项名称>/<业务文件名>.${extension}`,
+        auditPathRule: '<当前事项名称>/audit.json',
+        bytesWritten,
+      };
+      return wrap(data, [
+        '必须先加载 officecli Skill；原始模板仅作为只读底稿，不得原地修改。',
+        '最终文件必须写入 <当前事项名称>/，并严格执行 fillGuide、usageNote 和已解析撰写策略。',
+        '完成 officecli validate 和结构检查后必须调用 sop.audit-write；验证失败或审计失败不得交付或同步。',
+      ], '使用 officecli 生成并验证缺失成果，调用 sop.audit-write 写入审计；全部成果就绪后调用 sop.review-get。');
+    },
+  },
+  {
+    name: 'sop.review-get',
+    method: 'POST',
+    path: '/api/internal/v1/project-writing/sop/node/review-config',
+    idempotent: true,
+    multipart: false,
+    requiredContext: BASE_CONTEXT,
+    validate: nodeCodeInput,
+    handler: async ({ client, context, input }) => {
+      const data = await client.request({
+        method: 'POST',
+        path: '/api/internal/v1/project-writing/sop/node/review-config',
+        idempotent: true,
+        body: {
+          ...(context.tenantCode ? { tenantCode: context.tenantCode } : {}),
+          itemType: HIGH_TECH_ITEM_TYPE,
+          nodeCode: input.nodeCode,
+        },
+      });
+      return wrap(data, [
+        'reviewSuggestionDocument 是优化建议，必须反馈给用户，但不作为同步阻断依据。',
+        'reviewGateDocument 是同步定稿前的硬性校验，任一条件不满足时不得同步。',
+        '只有用户明确要求同步定稿且硬性校验通过后，才能调用对应领域写命令；写入后必须使用对应查询命令查询验证。',
+      ], '评审完成后停留在中间件阶段；只有用户明确要求同步定稿且硬门禁通过时才执行同步并查询验证。');
+    },
+  },
+  {
+    name: 'sop.audit-write',
+    method: 'LOCAL',
+    path: null,
+    idempotent: false,
+    multipart: false,
+    requiredContext: [],
+    validate: auditInput,
+    handler: async ({ input, baseDir }) => {
+      const data = await writeAudit(input, baseDir);
+      return wrap(data, [
+        '当前交付物已完成本地审计；审计记录不能替代远端 SOP 评审。',
+        '必须继续调用 sop.review-get，评审完成前不得交付定稿或同步正式业务模块。',
+      ], '调用 sop.review-get 获取优化建议和同步硬门禁。');
+    },
+  },
+];

package/scripts/services/workflow.mjs

@@ -0,0 +1,99 @@
+import { CliError } from '../core/errors.mjs';
+import { commands as materialCommands } from './material.mjs';
+import { commands as projectCommands } from './project.mjs';
+import { commands as reportCommands } from './report.mjs';
+
+const BASE_CONTEXT = ['gatewayUrl'];
+const PROJECT_CONTEXT = [...BASE_CONTEXT, 'uuid'];
+
+function findCommand(commands, name) {
+  const command = commands.find((item) => item.name === name);
+  if (!command) throw new CliError('CLI_INTERNAL_ERROR', `工作流步骤不存在: ${name}`);
+  return command;
+}
+
+const PROJECT_BIND = findCommand(projectCommands, 'project.bind');
+const COMPLETENESS = findCommand(reportCommands, 'report.completeness');
+const MATERIAL_LIST = findCommand(materialCommands, 'material.list');
+const REPORT_GENERATE = findCommand(reportCommands, 'report.generate');
+
+function objectInput(input) {
+  if (input === null || Array.isArray(input) || typeof input !== 'object') {
+    throw new CliError('ARGUMENT_INVALID', '工作流输入必须是对象');
+  }
+  return input;
+}
+
+function initializeInput(input) {
+  const value = objectInput(input);
+  return { ...value, project: PROJECT_BIND.validate(value.project) };
+}
+
+function organizeInput(input) {
+  const value = objectInput(input);
+  const material = MATERIAL_LIST.validate({ kind: value.kind });
+  const report = REPORT_GENERATE.validate({ jobs: value.jobs });
+  return { ...value, kind: material.kind, jobs: report.jobs };
+}
+
+function failedStep(command, error) {
+  return {
+    command,
+    code: error?.code ?? 'BUSINESS_ERROR',
+    message: error instanceof Error ? error.message : '工作流步骤失败',
+  };
+}
+
+async function runSequential(steps, args) {
+  const results = [];
+  for (const { command, input } of steps) {
+    try {
+      const data = await command.handler({ ...args, command, input });
+      results.push({ command: command.name, status: 'completed', data });
+    } catch (error) {
+      const failed = failedStep(command.name, error);
+      results.push({ command: command.name, status: 'failed', error: failed });
+      return { completed: false, failed, steps: results };
+    }
+  }
+  return { completed: true, failed: null, steps: results };
+}
+
+export const commands = [
+  {
+    name: 'workflow.initialize', method: 'POST', path: PROJECT_BIND.path,
+    idempotent: false, multipart: false, requiredContext: BASE_CONTEXT, validate: initializeInput,
+    handler: async (args) => await runSequential([
+      { command: PROJECT_BIND, input: args.input.project },
+    ], args),
+  },
+  {
+    name: 'workflow.completeness', method: 'POST', path: COMPLETENESS.path,
+    idempotent: true, multipart: false, requiredContext: PROJECT_CONTEXT, validate: objectInput,
+    handler: async (args) => {
+      const result = await runSequential([
+        { command: COMPLETENESS, input: COMPLETENESS.validate(args.input) },
+      ], args);
+      const data = result.steps[0]?.data;
+      if (result.completed && data?.complete === false) {
+        const failed = {
+          command: COMPLETENESS.name,
+          code: 'WORKFLOW_STEP_FAILED',
+          message: '完整性查询存在失败项',
+        };
+        result.completed = false;
+        result.failed = failed;
+        result.steps[0] = { command: COMPLETENESS.name, status: 'failed', data, error: failed };
+      }
+      return result;
+    },
+  },
+  {
+    name: 'workflow.organize-materials', method: 'POST', path: REPORT_GENERATE.path,
+    idempotent: false, multipart: false, requiredContext: PROJECT_CONTEXT, validate: organizeInput,
+    handler: async (args) => await runSequential([
+      { command: MATERIAL_LIST, input: MATERIAL_LIST.validate({ kind: args.input.kind }) },
+      { command: REPORT_GENERATE, input: REPORT_GENERATE.validate({ jobs: args.input.jobs }) },
+    ], args),
+  },
+];