dsh-data-cleaning-agent 0.6.3 → 0.8.0

package/lib/qcc.js

@@ -18,6 +18,13 @@ import {
   QCC_PHASE3_DOMAIN_META,
   QCC_PHASE3_TOOL_NAMES,
 } from './qcc-phase3.js';
+import {
+  RELATED_RISK_FACTORS,
+  RELATED_RISK_KEY_FACTORS,
+  RISK_FACTOR_CATALOG_VERSION,
+  SELF_RISK_FACTORS,
+  selectedSourceTools,
+} from './qcc-field-catalog.js';
 
 export const QCC_TOOL_NAMES = Object.freeze({
   oauthConnect: 'qcc_oauth_connect',
@@ -25,7 +32,12 @@ export const QCC_TOOL_NAMES = Object.freeze({
   entityLookup: 'mcp__qcc-company__get_company_by_query',
   registration: 'mcp__qcc-company__get_company_registration_info',
   profile: 'mcp__qcc-company__get_company_profile',
+  contact: 'mcp__qcc-company__get_contact_info',
+  listing: 'mcp__qcc-company__get_listing_info',
+  taxInvoice: 'mcp__qcc-company__get_tax_invoice_info',
+  importExportCredit: 'mcp__qcc-operation__get_import_export_credit',
   riskScan: 'mcp__qcc-risk__get_company_risk_scan',
+  relatedRiskScan: 'mcp__qcc-risk__get_company_related_risk_scan',
 });
 
 const EXACT_MATCH = '唯一精确匹配';
@@ -35,6 +47,7 @@ const DEFAULT_TIMEOUT_MS = 20_000;
 const DEFAULT_TOOL_WAIT_MS = 1_500;
 const DEFAULT_POLL_MS = 50;
 const DEFAULT_MAX_ROWS = 100;
+const DEFAULT_MAX_CALLS = 300;
 const MAX_CONCURRENCY = 4;
 
 function isRecord(value) {
@@ -324,72 +337,244 @@ export function mapRegistrationFields(value, fallback = {}) {
     }
     return '';
   };
-  const region = text('所属地区', '所属地域', '地区');
-  const location = splitAdministrativeRegion(region);
   return {
     company_name: text('企业名称') || String(fallback.companyName ?? ''),
     credit_no: text('统一社会信用代码', '信用代码') || String(fallback.creditNo ?? ''),
     reg_no: text('工商注册号', '注册号'),
     org_no: text('组织机构代码'),
+    tax_no: text('纳税人识别号'),
     reg_status: text('登记状态', '执业状态', '证书状态'),
     legal_rep: text('法定代表人', '负责人', '经营者'),
     reg_capital: text('注册资本', '注册资金', '开办资金', '成员出资总额', '资金数额'),
     paid_capital: text('实缴资本'),
     establish_date: text('成立日期'),
     company_type: text('企业类型', '公司类型'),
+    approval_date: text('核准日期'),
     registration_authority: text('登记机关'),
+    taxpayer_qualification: text('纳税人资质'),
+    payment_line_no: text('支付系统行号'),
+    import_export_company_code: text('进出口企业代码'),
+    short_name: text('企业简称'),
     english_name: text('英文名', '英文名称'),
     registered_address: text('注册地址', '住所', '经营场所'),
-    province: text('省份地区', '省份', '所属省份') || location.province,
-    city: text('城市', '所属城市', '市') || location.city,
-    district: text('区县', '所属区县') || location.district,
+    mailing_address: text('通信地址'),
+    region: text('所属地区'),
     business_scope: text('经营范围'),
     industry_category: text('国标行业'),
-    industry_large: text('一级行业', '企查查一级行业'),
-    industry_middle: text('二级行业', '企查查二级行业'),
     operating_period: text('营业期限', '经营期限'),
-    company_size: text('企业规模', '人员规模'),
-    biz_status: text('经营状态'),
+    company_size: text('人员规模'),
+    insured_count: text('参保人数'),
+    branch_insured_count: text('分支机构参保人数'),
   };
 }
 
-function splitAdministrativeRegion(value) {
-  const region = String(value ?? '').trim().replace(/\s+/g, '');
-  if (!region) return { province: '', city: '', district: '' };
-  const municipality = region.match(/^((?:北京|上海|天津|重庆)市)(.*)$/);
-  if (municipality) {
-    const district = municipality[2].match(/^(.+?(?:区|县))/)?.[1] ?? '';
-    return { province: municipality[1], city: municipality[1], district };
-  }
-  const provinceMatch = region.match(/^(.+?(?:省|自治区|特别行政区))/);
-  const province = provinceMatch?.[1] ?? '';
-  const remainder = province ? region.slice(province.length) : region;
-  const city = remainder.match(/^(.+?(?:市|自治州|地区|盟))/)?.[1] ?? '';
-  const districtRemainder = city ? remainder.slice(city.length) : remainder;
-  const district = districtRemainder.match(/^(.+?(?:区|县|旗|市))/)?.[1] ?? '';
-  return { province, city, district };
-}
-
 export function mapProfileFields(value) {
   if (!isRecord(value)) {
     throw new QccBridgeError('QCC_CONTRACT_MISMATCH', 'QCC profile tool returned a non-object result');
   }
   if (value.无匹配项 !== undefined) return {};
   return {
-    // “企查查行业”没有声明一/二级语义，不得猜测塞入层级列。
-    industry_large: String(value.一级行业 ?? value.企查查一级行业 ?? ''),
-    industry_middle: String(value.二级行业 ?? value.企查查二级行业 ?? ''),
+    // 工具只返回“企查查行业”这一最细层级展示值，不得猜测为一级或二级行业。
+    qcc_industry: String(value.企查查行业 ?? ''),
     company_profile: String(value.企业简介 ?? value.简介 ?? ''),
+    industry_chain_overview: String(value.产业链概览 ?? ''),
+  };
+}
+
+function scalarText(value, ...keys) {
+  if (!isRecord(value)) return '';
+  for (const key of keys) {
+    const item = value[key];
+    if (item !== undefined && item !== null && String(item).trim()) return String(item);
+  }
+  return '';
+}
+
+function scalarMap(value, mapping) {
+  if (!isRecord(value) || value.无匹配项 !== undefined || value.地域限制 !== undefined) return {};
+  return Object.fromEntries(mapping.map(([id, ...keys]) => [id, scalarText(value, ...keys)]));
+}
+
+export function mapContactFields(value) {
+  if (!isRecord(value)) return {};
+  const contact = isRecord(value.联系方式信息) ? value.联系方式信息 : {};
+  const phone = Array.isArray(contact.电话) && isRecord(contact.电话[0]) ? contact.电话[0] : {};
+  const email = Array.isArray(contact.邮箱) && isRecord(contact.邮箱[0]) ? contact.邮箱[0] : {};
+  const website = Array.isArray(contact.网址)
+    ? contact.网址.find((item) => isRecord(item) && item.是否是官网 === '是') ?? {}
+    : {};
+  return {
+    contact_preferred_phone: scalarText(phone, '电话号码'),
+    contact_phone_invalid_flag: scalarText(phone, '是否无效'),
+    contact_phone_tags: Array.isArray(phone.标签)
+      ? phone.标签.map((item) => String(item).trim()).filter(Boolean).join('；')
+      : '',
+    contact_preferred_email: scalarText(email, '邮箱'),
+    contact_official_website: scalarText(website, '网址'),
+    contact_official_website_icp: scalarText(website, 'ICP备案'),
+  };
+}
+
+export function mapListingFields(value) {
+  return scalarMap(value, [
+    ['listing_date', '上市日期'],
+    ['listing_short_name', '股票简称'],
+    ['listing_stock_code', '股票代码'],
+    ['listing_exchange', '上市交易所'],
+    ['listing_board', '上市板块'],
+    ['listing_former_short_name', '上市曾用名'],
+    ['listing_total_market_value', '总市值'],
+    ['listing_total_shares', '总股本'],
+    ['listing_predicted_pe', '预测市盈率'],
+    ['listing_float_market_value', '流通值'],
+    ['listing_float_shares', '流通股'],
+    ['listing_pb_ratio', '市净率'],
+    ['listing_eps', 'EPS'],
+    ['listing_voting_rights_difference', '表决权差异'],
+    ['listing_registration_based', '是否注册制'],
+  ]);
+}
+
+export function mapTaxInvoiceFields(value) {
+  return scalarMap(value, [
+    ['tax_company_name', '企业名称'],
+    ['tax_identification_no', '纳税人识别号'],
+    ['tax_company_type', '企业类型'],
+    ['tax_business_status', '经营状态'],
+    ['invoice_address', '地址'],
+    ['invoice_phone', '联系电话'],
+    ['invoice_bank', '开户行'],
+    ['invoice_bank_account', '开户行账号'],
+  ]);
+}
+
+export function mapImportExportCreditFields(value) {
+  return scalarMap(value, [
+    ['import_export_credit_no', '统一社会信用代码'],
+    ['import_export_customs', '所在地海关'],
+    ['import_export_admin_division', '行政区划'],
+    ['import_export_address', '地址'],
+    ['import_export_economic_area', '经济区划'],
+    ['import_export_trade_type', '经营类别'],
+    ['import_export_statistical_economic_area', '统计经济区划'],
+    ['import_export_industry', '行业种类'],
+    ['import_export_ecommerce_type', '跨境贸易电子商务类型'],
+    ['import_export_credit_grade', '信用等级'],
+    ['import_export_filing_date', '备案日期'],
+  ]);
+}
+
+function countValue(value) {
+  if (value === '' || value === null || value === undefined) return '';
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : '';
+}
+
+function selfRiskRows(value) {
+  return Array.isArray(value?.风险因子扫描) ? value.风险因子扫描.filter(isRecord) : [];
+}
+
+export function inspectSelfRiskCatalog(value) {
+  const applicable = Array.isArray(value?.风险因子扫描);
+  const actual = new Set(selfRiskRows(value).map((row) => String(row.风险因子 ?? '').trim()).filter(Boolean));
+  const expected = new Set(SELF_RISK_FACTORS.map(([, label]) => label));
+  return {
+    applicable,
+    version: RISK_FACTOR_CATALOG_VERSION,
+    missing: [...expected].filter((label) => !actual.has(label)),
+    unknown: [...actual].filter((label) => !expected.has(label)),
+  };
+}
+
+export function mapCompanyRiskScanFields(value) {
+  if (!isRecord(value) || !Array.isArray(value.风险因子扫描)) return {};
+  const counts = new Map(selfRiskRows(value).map((row) => [String(row.风险因子 ?? '').trim(), countValue(row.条目数)]));
+  const hits = SELF_RISK_FACTORS.flatMap(([, label]) => {
+    const count = counts.get(label);
+    return typeof count === 'number' && count > 0 ? [`${label}(${count})`] : [];
+  });
+  return {
+    risk_recorded_factor_count: countValue(value.有记录因子数),
+    risk_no_record_factor_count: countValue(value.无记录因子数),
+    risk_hit_summary: hits.join('；'),
+    ...Object.fromEntries(SELF_RISK_FACTORS.map(([id, label]) => [`risk_${id}_count`, counts.get(label) ?? ''])),
+  };
+}
+
+export function inspectRelatedRiskCatalog(value) {
+  const applicable = isRecord(value?.维度计数汇总);
+  // QCC MCP 当前契约名为“重要风险”；“关键风险”仅作早期预发环境兼容，
+  // 不得反向把兼容名称当成稳定上游契约。
+  const importantSource = value?.维度计数汇总?.重要风险 ?? value?.维度计数汇总?.关键风险;
+  const important = isRecord(importantSource) ? importantSource : {};
+  const locating = Array.isArray(value?.重点维度关联方定位) ? value.重点维度关联方定位.filter(isRecord) : [];
+  const importantActual = new Set(Object.keys(important));
+  const keyActual = new Set(locating.map((row) => String(row.维度 ?? '').trim()).filter(Boolean));
+  const importantExpected = new Set(RELATED_RISK_FACTORS.map(([, label]) => label));
+  const keyExpected = new Set(RELATED_RISK_KEY_FACTORS.map(([, label]) => label));
+  return {
+    applicable,
+    version: RISK_FACTOR_CATALOG_VERSION,
+    missing: [
+      ...[...importantExpected].filter((label) => !importantActual.has(label)).map((label) => `重要风险:${label}`),
+      ...[...keyExpected].filter((label) => !keyActual.has(label)).map((label) => `重点维度:${label}`),
+    ],
+    unknown: [
+      ...[...importantActual].filter((label) => !importantExpected.has(label)).map((label) => `重要风险:${label}`),
+      ...[...keyActual].filter((label) => !keyExpected.has(label)).map((label) => `重点维度:${label}`),
+    ],
+  };
+}
+
+export function mapCompanyRelatedRiskScanFields(value) {
+  if (!isRecord(value) || !isRecord(value.维度计数汇总)) return {};
+  const importantSource = value.维度计数汇总.重要风险 ?? value.维度计数汇总.关键风险;
+  const important = isRecord(importantSource) ? importantSource : {};
+  const locating = Array.isArray(value.重点维度关联方定位) ? value.重点维度关联方定位.filter(isRecord) : [];
+  const partyCounts = new Map(locating.map((row) => [String(row.维度 ?? '').trim(), countValue(row.命中关联方数)]));
+  const hits = RELATED_RISK_FACTORS.flatMap(([, label]) => {
+    const count = countValue(important[label]);
+    return typeof count === 'number' && count > 0 ? [`${label}(${count})`] : [];
+  });
+  const partyCount = countValue(value.有风险关联方数);
+  return {
+    related_risk_party_count: partyCount,
+    related_risk_summary: `${partyCount === '' ? '' : `有风险关联方${partyCount}个`}${hits.length ? `${partyCount === '' ? '' : '；'}${hits.join('；')}` : ''}`,
+    ...Object.fromEntries(RELATED_RISK_FACTORS.map(([id, label]) => [`related_risk_${id}_count`, countValue(important[label])])),
+    ...Object.fromEntries(RELATED_RISK_KEY_FACTORS.map(([id, label]) => [`related_risk_${id}_party_count`, partyCounts.get(label) ?? ''])),
   };
 }
 
 const LEGACY_ENRICHMENT_FIELDS = Object.freeze([
-  'credit_no', 'legal_rep', 'reg_capital', 'establish_date', 'reg_status', 'biz_status',
+  'credit_no', 'legal_rep', 'reg_capital', 'establish_date', 'reg_status',
 ]);
-const PROFILE_FIELDS = new Set(['industry_large', 'industry_middle', 'company_profile']);
+const SOURCE_TOOL_CONFIG = Object.freeze({
+  get_company_registration_info: Object.freeze({ name: QCC_TOOL_NAMES.registration, map: mapRegistrationFields }),
+  get_company_profile: Object.freeze({ name: QCC_TOOL_NAMES.profile, map: mapProfileFields }),
+  get_contact_info: Object.freeze({ name: QCC_TOOL_NAMES.contact, map: mapContactFields, args: { excludeInvalidPhone: false } }),
+  get_listing_info: Object.freeze({ name: QCC_TOOL_NAMES.listing, map: mapListingFields }),
+  get_tax_invoice_info: Object.freeze({ name: QCC_TOOL_NAMES.taxInvoice, map: mapTaxInvoiceFields }),
+  get_import_export_credit: Object.freeze({ name: QCC_TOOL_NAMES.importExportCredit, map: mapImportExportCreditFields }),
+  get_company_risk_scan: Object.freeze({ name: QCC_TOOL_NAMES.riskScan, map: mapCompanyRiskScanFields, inspect: inspectSelfRiskCatalog }),
+  get_company_related_risk_scan: Object.freeze({ name: QCC_TOOL_NAMES.relatedRiskScan, map: mapCompanyRelatedRiskScanFields, inspect: inspectRelatedRiskCatalog }),
+});
+
+export function sourceToolsForFieldSelection(fieldSelection, includeRisk = false) {
+  const selected = Array.isArray(fieldSelection) && fieldSelection.length ? fieldSelection : LEGACY_ENRICHMENT_FIELDS;
+  const tools = selectedSourceTools(selected, LEGACY_ENRICHMENT_FIELDS);
+  if (includeRisk && !tools.includes('get_company_risk_scan')) tools.push('get_company_risk_scan');
+  return tools;
+}
 
-function requiresProfile(fieldSelection) {
-  return Array.isArray(fieldSelection) && fieldSelection.some((field) => PROFILE_FIELDS.has(field));
+export function estimateQccCalls(uniqueCompanies, fieldSelection, includeRisk = false) {
+  const companies = Math.max(0, Math.trunc(Number(uniqueCompanies) || 0));
+  const sourceTools = sourceToolsForFieldSelection(fieldSelection, includeRisk);
+  return {
+    uniqueCompanies: companies,
+    sourceTools,
+    callsPerCompany: 1 + sourceTools.length,
+    estimatedCalls: companies * (1 + sourceTools.length),
+  };
 }
 
 function mergeMappedFields(...sources) {
@@ -481,7 +666,12 @@ export class QccHostBridge {
       entityLookup: this.has(QCC_TOOL_NAMES.entityLookup),
       registration: this.has(QCC_TOOL_NAMES.registration),
       profile: this.has(QCC_TOOL_NAMES.profile),
+      contact: this.has(QCC_TOOL_NAMES.contact),
+      listing: this.has(QCC_TOOL_NAMES.listing),
+      taxInvoice: this.has(QCC_TOOL_NAMES.taxInvoice),
+      importExportCredit: this.has(QCC_TOOL_NAMES.importExportCredit),
       riskScan: this.has(QCC_TOOL_NAMES.riskScan),
+      relatedRiskScan: this.has(QCC_TOOL_NAMES.relatedRiskScan),
     };
     const ready = capabilities.entityLookup && capabilities.registration;
     return {
@@ -720,28 +910,39 @@ export class QccHostBridge {
     );
     const match = classifyEntityMatch(lookup.data);
     if (match.status !== 'exact') return match;
+    return this.enrichMatchedCompany(match, options);
+  }
 
-    const lockedKey = match.creditNo || match.companyName;
-    const registration = await this.call(
-      QCC_TOOL_NAMES.registration,
-      { searchKey: lockedKey },
-      options,
-    );
-    let mapped = mapRegistrationFields(registration.data, match);
-    if (requiresProfile(options.fieldSelection)) {
-      const profile = await this.call(QCC_TOOL_NAMES.profile, { searchKey: lockedKey }, options);
-      mapped = mergeMappedFields(mapped, mapProfileFields(profile.data));
+  async enrichMatchedCompany(match, options = {}) {
+    const lockedKey = String(match?.creditNo || match?.companyName || '').trim();
+    const sourceTools = sourceToolsForFieldSelection(options.fieldSelection, options.includeRisk);
+    let mapped = {};
+    let legacyRiskTags = '';
+    for (const sourceTool of sourceTools) {
+      const config = SOURCE_TOOL_CONFIG[sourceTool];
+      if (!config) continue;
+      const response = await this.call(config.name, { searchKey: lockedKey, ...(config.args ?? {}) }, options);
+      const fields = config.map(response.data, match);
+      mapped = mergeMappedFields(mapped, fields);
+      if (sourceTool === 'get_company_risk_scan') legacyRiskTags = mapRiskTags(response.data);
+      if (config.inspect) {
+        const catalog = config.inspect(response.data);
+        if (catalog.applicable && (catalog.missing.length || catalog.unknown.length)) {
+          emitAudit(options, {
+            toolName: response.toolName,
+            callId: response.callId,
+            outcome: 'catalog-drift',
+            code: 'QCC_RISK_CATALOG_DRIFT',
+            catalogVersion: catalog.version,
+            missing: catalog.missing,
+            unknown: catalog.unknown,
+          });
+        }
+      }
     }
     const fields = projectSelectedFields(mapped, options.fieldSelection);
-    if (options.includeRisk) {
-      const risk = await this.call(QCC_TOOL_NAMES.riskScan, { searchKey: lockedKey }, options);
-      fields.risk_tags = mapRiskTags(risk.data);
-    }
-    return {
-      status: 'enriched',
-      companyName: match.companyName,
-      fields,
-    };
+    if (options.includeRisk) fields.risk_tags = legacyRiskTags;
+    return { status: 'enriched', companyName: String(match?.companyName ?? ''), fields };
   }
 
   async enrichLockedCompany(selection, options = {}) {
@@ -750,22 +951,7 @@ export class QccHostBridge {
     if (!creditNo) {
       throw new QccBridgeError('QCC_CANDIDATE_INVALID', 'A selected QCC candidate must include a credit number');
     }
-    const registration = await this.call(
-      QCC_TOOL_NAMES.registration,
-      { searchKey: creditNo },
-      options,
-    );
-    let mapped = mapRegistrationFields(registration.data, { companyName, creditNo });
-    if (requiresProfile(options.fieldSelection)) {
-      const profile = await this.call(QCC_TOOL_NAMES.profile, { searchKey: creditNo }, options);
-      mapped = mergeMappedFields(mapped, mapProfileFields(profile.data));
-    }
-    const fields = projectSelectedFields(mapped, options.fieldSelection);
-    if (options.includeRisk) {
-      const risk = await this.call(QCC_TOOL_NAMES.riskScan, { searchKey: creditNo }, options);
-      fields.risk_tags = mapRiskTags(risk.data);
-    }
-    return { status: 'enriched', companyName, fields };
+    return this.enrichMatchedCompany({ companyName, creditNo }, options);
   }
 
   async enrichRows(rows, options = {}) {
@@ -777,9 +963,27 @@ export class QccHostBridge {
       });
     }
 
-    const requiredTools = [QCC_TOOL_NAMES.entityLookup, QCC_TOOL_NAMES.registration];
-    if (requiresProfile(options.fieldSelection)) requiredTools.push(QCC_TOOL_NAMES.profile);
-    if (options.includeRisk) requiredTools.push(QCC_TOOL_NAMES.riskScan);
+    const nameField = String(options.nameField ?? 'name');
+    const normalized = rows.map((row, index) => ({
+      index,
+      row: isRecord(row) ? { ...row } : {},
+      companyName: String(isRecord(row) ? row[nameField] ?? '' : '').trim(),
+    }));
+    const names = [...new Set(normalized.map((item) => item.companyName).filter(Boolean))];
+    const estimate = estimateQccCalls(names.length, options.fieldSelection, options.includeRisk);
+    const maxCalls = Math.max(1, Math.trunc(options.maxCalls ?? DEFAULT_MAX_CALLS));
+    if (estimate.estimatedCalls > maxCalls) {
+      throw new QccBridgeError('QCC_CALL_BUDGET_EXCEEDED', `QCC call estimate exceeds ${maxCalls}`, {
+        details: { ...estimate, maxCalls },
+      });
+    }
+
+    const requiredTools = [
+      QCC_TOOL_NAMES.entityLookup,
+      ...estimate.sourceTools
+        .map((sourceTool) => SOURCE_TOOL_CONFIG[sourceTool]?.name)
+        .filter(Boolean),
+    ];
     try {
       await Promise.all(requiredTools.map((name) => this.waitForTool(name, {
         signal: options.signal,
@@ -796,13 +1000,6 @@ export class QccHostBridge {
       });
     }
 
-    const nameField = String(options.nameField ?? 'name');
-    const normalized = rows.map((row, index) => ({
-      index,
-      row: isRecord(row) ? { ...row } : {},
-      companyName: String(isRecord(row) ? row[nameField] ?? '' : '').trim(),
-    }));
-    const names = [...new Set(normalized.map((item) => item.companyName).filter(Boolean))];
     const concurrency = Math.min(MAX_CONCURRENCY, Math.max(1, Math.trunc(options.concurrency ?? 2)));
     let completedUnique = 0;
 
@@ -857,6 +1054,6 @@ export class QccHostBridge {
       includeRisk: Boolean(options.includeRisk),
     };
 
-    return { summary, rows: outputRows, reviewQueue, errors };
+    return { summary, rows: outputRows, reviewQueue, errors, estimate };
   }
 }

package/lib/web.js

@@ -16,6 +16,13 @@ import { PHASE3_BATCH_LIMITS, Phase3BatchService, Phase3RunStore } from './qcc-p
 import { publicWorkflowContract } from './workflow-contract.js';
 import { DataCleaningWorkflowStore, WorkflowError } from './workflow.js';
 import { ArtifactError, WorkflowArtifactStore } from './artifacts.js';
+import {
+  ImageIntakeError,
+  ImageIntakeStore,
+  registerImageIntakeTool,
+  serializeImageExtractionPrompt,
+  TOOL_IMAGE_EXTRACT,
+} from './image-intake.js';
 
 const MAX_BODY = 16 * 1024 * 1024; // 16 MiB 上传上限（MVP）
 
@@ -119,6 +126,17 @@ function writeWorkflowError(res, error) {
   });
 }
 
+function writeImageError(res, error) {
+  if (error instanceof ImageIntakeError) {
+    return writeJson(res, error.status, { ok: false, code: error.code, message: error.message });
+  }
+  return writeJson(res, 500, {
+    ok: false,
+    code: 'DC_IMAGE_INTERNAL',
+    message: '图片名单接入请求失败。',
+  });
+}
+
 /** 从 JSON 协议解析上传：{ filename, content }。content 为字符串；xlsx 时为 base64。 */
 async function parseUpload(body) {
   let payload;
@@ -285,13 +303,17 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
   const skills = wctx.skills;
   const disposers = [];
   const qccBridge = new QccHostBridge({ tools, logger });
+  const imageIntake = new ImageIntakeStore({ tools });
   const g5Runs = new G5RunStore();
   const qccCommands = new QccCommandStore({ bridge: qccBridge, runs: g5Runs });
   if (typeof tools?.register === 'function') {
     disposers.push(registerQccCommandTool(tools, qccCommands));
+    disposers.push(registerImageIntakeTool(tools, imageIntake));
     report.qccCommandToolRegistered = true;
+    report.imageIntakeToolRegistered = true;
   } else {
     report.qccCommandToolRegistered = false;
+    report.imageIntakeToolRegistered = false;
   }
   const phase3Service = new Phase3BatchService(qccBridge);
   const phase3Runs = new Phase3RunStore();
@@ -347,11 +369,64 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
         workflowV2: Boolean(wctx.storageDomain),
         durableArtifacts: Boolean(artifactStore),
         artifactBinaryStrategy: artifactStore ? 'xlsx-base64-over-writeText' : 'unavailable',
+        imageIntake: imageIntake.capabilities(),
         qccBridge: qccBridge.capabilities(),
       },
     });
   });
 
+  register('/data-cleaning/api/images/capabilities', (req, res) => {
+    if (!isTrusted(req)) return writeJson(res, 403, { ok: false, error: 'untrusted origin' });
+    if (req.method !== 'GET') return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'GET required' });
+    writeJson(res, 200, {
+      ok: true,
+      marker: 'data-cleaning-image-intake-v1',
+      tool: TOOL_IMAGE_EXTRACT,
+      toolRegistered: report.imageIntakeToolRegistered === true,
+      capabilities: imageIntake.capabilities(),
+      qccCalls: false,
+    });
+  });
+
+  register('/data-cleaning/api/images/commands', async (req, res) => {
+    if (!isTrusted(req)) return writeJson(res, 403, { ok: false, error: 'untrusted origin' });
+    try {
+      const pathname = new URL(req.url ?? '/data-cleaning/api/images/commands', 'http://127.0.0.1').pathname;
+      const segments = pathname.split('/').filter(Boolean);
+      const commandsIndex = segments.indexOf('commands');
+      const rest = commandsIndex >= 0 ? segments.slice(commandsIndex + 1) : [];
+      if (rest.length === 0 && req.method === 'POST') {
+        if (report.imageIntakeToolRegistered !== true) {
+          throw new ImageIntakeError('DC_IMAGE_TOOL_UNAVAILABLE', '当前 DSH Host 无法注册图片名单高层工具。', 503);
+        }
+        const payload = JSON.parse((await readBody(req)).toString('utf8'));
+        const command = await imageIntake.prepare(payload);
+        return writeJson(res, 201, {
+          ok: true,
+          marker: 'data-cleaning-image-intake-v1',
+          command: { ...command, prompt: serializeImageExtractionPrompt(command) },
+        });
+      }
+      if (rest.length === 1 && req.method === 'GET') {
+        return writeJson(res, 200, {
+          ok: true,
+          marker: 'data-cleaning-image-intake-v1',
+          command: imageIntake.status(decodeURIComponent(rest[0])),
+        });
+      }
+      if (rest.length === 1 && req.method === 'DELETE') {
+        await imageIntake.remove(decodeURIComponent(rest[0]));
+        return writeJson(res, 200, { ok: true, marker: 'data-cleaning-image-intake-v1', removed: true });
+      }
+      return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'POST a command, GET its status, or DELETE it.' });
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        return writeJson(res, 400, { ok: false, code: 'DC_BAD_JSON', message: 'Request body must be valid JSON.' });
+      }
+      return writeImageError(res, error);
+    }
+  });
+
   register('/data-cleaning/api/workflow/contract', (req, res) => {
     if (!isTrusted(req)) return writeJson(res, 403, { ok: false, error: 'untrusted origin' });
     if (req.method !== 'GET') {
@@ -955,6 +1030,7 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
   return () => {
     if (state) { state.dispose().catch(() => {}); }
     if (workflow) { workflow.dispose().catch(() => {}); }
+    imageIntake.dispose().catch(() => {});
     for (const dispose of disposers) dispose();
   };
 }