dsh-data-cleaning-agent 0.2.1 → 0.4.0

package/lib/qcc-phase2-acceptance.js

@@ -0,0 +1,191 @@
+import { isDeepStrictEqual } from 'node:util';
+import {
+  QCC_PHASE2_COMPANY_TOOLS,
+  QCC_PHASE2_HISTORY_TOOLS,
+  qccToolRuntimeCandidates,
+} from './qcc-phase2.js';
+
+export const QCC_PHASE2_ACCEPTANCE_SCHEMA_VERSION = 1;
+export const QCC_PHASE2_EVIDENCE_KIND = 'qcc-phase2-real-tool-transcript';
+export const QCC_PHASE2_ACCEPTANCE_FLOORS = Object.freeze({
+  minimumRecords: 20,
+  minimumCurrentDimensions: 15,
+  requiredHistoryDimensions: Object.keys(QCC_PHASE2_HISTORY_TOOLS).length,
+});
+
+const CURRENT_TOOLS = new Map(Object.entries(QCC_PHASE2_COMPANY_TOOLS));
+const HISTORY_TOOLS = new Map(Object.entries(QCC_PHASE2_HISTORY_TOOLS));
+const DELIVERED_STATUSES = new Set(['resolved', 'no_data']);
+const ALLOWED_STATUSES = new Set([
+  ...DELIVERED_STATUSES,
+  'permission_required',
+  'not_available',
+  'error',
+]);
+const OPAQUE_REFERENCE = /^row-[0-9]{3,6}$/;
+
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function hasMeaningfulValue(value) {
+  if (value === null || value === undefined) return false;
+  if (typeof value === 'string') return value.trim().length > 0;
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === 'object') return Object.keys(value).length > 0;
+  return true;
+}
+
+function evaluateField(field) {
+  if (!field || typeof field !== 'object' || Array.isArray(field)) return false;
+  if (typeof field.key !== 'string' || field.key.length === 0) return false;
+  if (!hasOwn(field, 'value') || !hasOwn(field, 'sourceValue')) return false;
+  if (!hasMeaningfulValue(field.value) || !hasMeaningfulValue(field.sourceValue)) return false;
+  return isDeepStrictEqual(field.value, field.sourceValue);
+}
+
+function evaluateDimension(dimension, knownTools) {
+  const failures = [];
+  if (!dimension || typeof dimension !== 'object' || Array.isArray(dimension)) {
+    return { id: null, delivered: false, failures: ['DIMENSION_INVALID'] };
+  }
+  const id = typeof dimension.id === 'string' ? dimension.id : null;
+  const expectedTool = id ? knownTools.get(id) : null;
+  if (!expectedTool) failures.push('DIMENSION_UNKNOWN');
+  if (!qccToolRuntimeCandidates(expectedTool ?? '').includes(dimension.sourceTool)) {
+    failures.push('SOURCE_TOOL_MISMATCH');
+  }
+  if (!ALLOWED_STATUSES.has(dimension.status)) failures.push('DIMENSION_STATUS_INVALID');
+
+  const fieldsAreArray = Array.isArray(dimension.fields);
+  const fields = fieldsAreArray ? dimension.fields : [];
+  if (!fieldsAreArray) failures.push('FIELDS_ARRAY_REQUIRED');
+  if (dimension.status === 'resolved') {
+    if (fields.length === 0) failures.push('RESOLVED_FIELDS_REQUIRED');
+    if (!fields.every(evaluateField)) failures.push('VALUE_NOT_VERBATIM');
+  }
+  if (dimension.status === 'no_data' && fields.length > 0) {
+    failures.push('NO_DATA_MUST_NOT_CARRY_VALUES');
+  }
+
+  return {
+    id,
+    delivered: failures.length === 0 && DELIVERED_STATUSES.has(dimension.status),
+    failures,
+  };
+}
+
+function evaluateRecord(record, index, { requireHistory }) {
+  const safeReference = OPAQUE_REFERENCE.test(record?.reference ?? '')
+    ? record.reference
+    : `row-${String(index + 1).padStart(3, '0')}`;
+  const failures = [];
+  if (!OPAQUE_REFERENCE.test(record?.reference ?? '')) failures.push('REFERENCE_NOT_OPAQUE');
+  if (record?.entityStatus !== 'resolved') failures.push('ENTITY_NOT_RESOLVED');
+
+  const dimensions = Array.isArray(record?.dimensions) ? record.dimensions : [];
+  if (!Array.isArray(record?.dimensions)) failures.push('DIMENSIONS_REQUIRED');
+
+  const seen = new Set();
+  const deliveredStatuses = new Map();
+  let currentDelivered = 0;
+  let historyDelivered = 0;
+  for (const dimension of dimensions) {
+    const domain = dimension?.domain;
+    const tools = domain === 'history' ? HISTORY_TOOLS : domain === 'company' ? CURRENT_TOOLS : null;
+    if (!tools) {
+      failures.push('DIMENSION_DOMAIN_INVALID');
+      continue;
+    }
+    const uniqueKey = `${domain}:${dimension?.id ?? ''}`;
+    if (seen.has(uniqueKey)) {
+      failures.push('DIMENSION_DUPLICATE');
+      continue;
+    }
+    seen.add(uniqueKey);
+    const result = evaluateDimension(dimension, tools);
+    failures.push(...result.failures);
+    if (result.delivered) deliveredStatuses.set(uniqueKey, dimension.status);
+    if (result.delivered && domain === 'company') currentDelivered += 1;
+    if (result.delivered && domain === 'history') historyDelivered += 1;
+  }
+
+  if (
+    deliveredStatuses.get('company:resolveEntity') !== 'resolved'
+    || deliveredStatuses.get('company:registration') !== 'resolved'
+  ) {
+    failures.push('IDENTITY_EVIDENCE_REQUIRED');
+  }
+  if (currentDelivered < QCC_PHASE2_ACCEPTANCE_FLOORS.minimumCurrentDimensions) {
+    failures.push('CURRENT_DIMENSION_FLOOR_NOT_MET');
+  }
+  if (requireHistory && historyDelivered < QCC_PHASE2_ACCEPTANCE_FLOORS.requiredHistoryDimensions) {
+    failures.push('HISTORY_DIMENSION_FLOOR_NOT_MET');
+  }
+
+  return {
+    reference: safeReference,
+    passed: failures.length === 0,
+    currentDelivered,
+    historyDelivered,
+    failures: [...new Set(failures)].sort(),
+    entityStatus: ['resolved', 'ambiguous', 'unresolved'].includes(record?.entityStatus)
+      ? record.entityStatus
+      : 'invalid',
+  };
+}
+
+/**
+ * 评估 0.4.0 真实 E2E 证据。返回值严格不携带企业名、信用代码或字段值。
+ */
+export function evaluateQccPhase2Evidence(evidence, { requireHistory = false } = {}) {
+  const globalFailures = [];
+  if (!evidence || typeof evidence !== 'object' || Array.isArray(evidence)) {
+    globalFailures.push('EVIDENCE_INVALID');
+  }
+  if (evidence?.schemaVersion !== QCC_PHASE2_ACCEPTANCE_SCHEMA_VERSION) {
+    globalFailures.push('SCHEMA_VERSION_UNSUPPORTED');
+  }
+  if (evidence?.evidenceKind !== QCC_PHASE2_EVIDENCE_KIND) {
+    globalFailures.push('EVIDENCE_KIND_UNVERIFIED');
+  }
+  // 真实 E2E 证据必须显式声明 synthetic:false；缺省值也按未验证处理，保持 fail-closed。
+  if (evidence?.synthetic !== false) globalFailures.push('SYNTHETIC_EVIDENCE_REJECTED');
+  if (!Array.isArray(evidence?.records)) globalFailures.push('RECORDS_REQUIRED');
+  const records = Array.isArray(evidence?.records) ? evidence.records : [];
+  if (records.length < QCC_PHASE2_ACCEPTANCE_FLOORS.minimumRecords) {
+    globalFailures.push('RECORD_FLOOR_NOT_MET');
+  }
+  if (requireHistory && evidence?.historyAccess !== 'enterprise-certified') {
+    globalFailures.push('ENTERPRISE_HISTORY_ACCESS_NOT_VERIFIED');
+  }
+
+  const recordReports = records.map((record, index) => evaluateRecord(record, index, { requireHistory }));
+  const references = recordReports.map((record) => record.reference);
+  if (new Set(references).size !== references.length) globalFailures.push('REFERENCE_DUPLICATE');
+
+  const failedRecords = recordReports.filter((record) => !record.passed);
+  const summary = {
+    recordCount: recordReports.length,
+    passedRecords: recordReports.length - failedRecords.length,
+    failedRecords: failedRecords.length,
+    ambiguousRecords: recordReports.filter((record) => record.entityStatus === 'ambiguous').length,
+    unresolvedRecords: recordReports.filter((record) => record.entityStatus === 'unresolved').length,
+    minimumCurrentDimensions: recordReports.length === 0
+      ? 0
+      : Math.min(...recordReports.map((record) => record.currentDelivered)),
+    minimumHistoryDimensions: recordReports.length === 0
+      ? 0
+      : Math.min(...recordReports.map((record) => record.historyDelivered)),
+  };
+
+  return {
+    schemaVersion: QCC_PHASE2_ACCEPTANCE_SCHEMA_VERSION,
+    passed: globalFailures.length === 0 && failedRecords.length === 0,
+    requireHistory,
+    floors: QCC_PHASE2_ACCEPTANCE_FLOORS,
+    summary,
+    globalFailures: [...new Set(globalFailures)].sort(),
+    failures: failedRecords.map(({ reference, failures }) => ({ reference, codes: failures })),
+  };
+}

package/lib/qcc-phase2.js

@@ -0,0 +1,99 @@
+/**
+ * QCC 0.4.0 二期工具契约。
+ *
+ * 这里只固化已经在本地 QCC MCP 一手源码注册表中核对过的工具名。
+ * 不固化上游响应字段：方案 A 由模型中介解读工具返回，并必须保留原值。
+ */
+
+const companyTool = (name) => `mcp__qcc-company__${name}`;
+const historyTool = (name) => `mcp__qcc-history__${name}`;
+
+/**
+ * qcc-dsh-mcp-oauth 0.1.7 把 serverKey 直接作为 serverName，因而注册为
+ * `mcp__company__*` / `mcp__history__*`；修复版与手工配置使用文档约定的
+ * `mcp__qcc-company__*` / `mcp__qcc-history__*`。Bridge 同时兼容两者，
+ * 但始终把带 qcc- 前缀的名称作为规范契约。
+ */
+export function qccToolRuntimeCandidates(canonicalName) {
+  const name = String(canonicalName ?? '');
+  const legacy = name.replace(/^mcp__qcc-(company|risk|ipr|operation|history|executive)__/, 'mcp__$1__');
+  return legacy === name ? Object.freeze([name]) : Object.freeze([name, legacy]);
+}
+
+export const QCC_PHASE2_COMPANY_TOOLS = Object.freeze({
+  resolveEntity: companyTool('get_company_by_query'),
+  registration: companyTool('get_company_registration_info'),
+  profile: companyTool('get_company_profile'),
+  verifyIdentity: companyTool('verify_company_accuracy'),
+  actualController: companyTool('get_actual_controller'),
+  beneficialOwners: companyTool('get_beneficial_owners'),
+  shareholders: companyTool('get_shareholder_info'),
+  externalInvestments: companyTool('get_external_investments'),
+  branches: companyTool('get_branches'),
+  keyPersonnel: companyTool('get_key_personnel'),
+  changes: companyTool('get_change_records'),
+  annualReports: companyTool('get_annual_reports'),
+  contact: companyTool('get_contact_info'),
+  taxInvoice: companyTool('get_tax_invoice_info'),
+  listing: companyTool('get_listing_info'),
+  financial: companyTool('get_financial_data'),
+});
+
+export const QCC_PHASE2_HISTORY_TOOLS = Object.freeze({
+  shareholders: historyTool('get_historical_shareholders'),
+  legalRepresentative: historyTool('get_historical_legal_rep'),
+  executives: historyTool('get_historical_executives'),
+  registration: historyTool('get_historical_registration'),
+});
+
+/**
+ * 用户可选的维度组。identity 是任何任务的必需步骤；其余组按用户意图调用。
+ * 字段缺失、无权或上游不可用时，应保留状态而不是补造值。
+ */
+export const QCC_PHASE2_DIMENSION_GROUPS = Object.freeze({
+  identity: Object.freeze({
+    label: '主体锚定与核验',
+    access: 'basic',
+    tools: Object.freeze([
+      QCC_PHASE2_COMPANY_TOOLS.resolveEntity,
+      QCC_PHASE2_COMPANY_TOOLS.registration,
+      QCC_PHASE2_COMPANY_TOOLS.verifyIdentity,
+    ]),
+  }),
+  panorama: Object.freeze({
+    label: '企业全景',
+    access: 'basic',
+    tools: Object.freeze([
+      QCC_PHASE2_COMPANY_TOOLS.profile,
+      QCC_PHASE2_COMPANY_TOOLS.contact,
+      QCC_PHASE2_COMPANY_TOOLS.taxInvoice,
+      QCC_PHASE2_COMPANY_TOOLS.listing,
+      QCC_PHASE2_COMPANY_TOOLS.financial,
+    ]),
+  }),
+  ownership: Object.freeze({
+    label: '股权穿透',
+    access: 'basic',
+    tools: Object.freeze([
+      QCC_PHASE2_COMPANY_TOOLS.actualController,
+      QCC_PHASE2_COMPANY_TOOLS.beneficialOwners,
+      QCC_PHASE2_COMPANY_TOOLS.shareholders,
+      QCC_PHASE2_COMPANY_TOOLS.externalInvestments,
+    ]),
+  }),
+  governance: Object.freeze({
+    label: '组织与沿革',
+    access: 'basic',
+    tools: Object.freeze([
+      QCC_PHASE2_COMPANY_TOOLS.branches,
+      QCC_PHASE2_COMPANY_TOOLS.keyPersonnel,
+      QCC_PHASE2_COMPANY_TOOLS.changes,
+      QCC_PHASE2_COMPANY_TOOLS.annualReports,
+    ]),
+  }),
+  history: Object.freeze({
+    label: '历史工商',
+    access: 'enterprise-certified',
+    tools: Object.freeze(Object.values(QCC_PHASE2_HISTORY_TOOLS)),
+  }),
+});

package/lib/qcc-runs.js

@@ -0,0 +1,322 @@
+/**
+ * G5 Host 内存态：候选续跑、人工重试和请求幂等。
+ *
+ * 原始/补全行只保存在当前 Host 进程，不写 storageDomain；重启后 run 明确失效。
+ * 幂等缓存保存请求指纹与同源响应，避免客户端超时重发导致重复计费。
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { QccBridgeError } from './qcc.js';
+import { safeAuditEvent } from './qcc-safety.js';
+
+const DEFAULT_TTL_MS = 30 * 60 * 1000;
+const DEFAULT_MAX_RUNS = 50;
+const DEFAULT_MAX_AUDIT = 200;
+const DEFAULT_MAX_IDEMPOTENCY = 200;
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+}
+
+export function fingerprintRequest(operation, payload) {
+  return createHash('sha256')
+    .update(JSON.stringify({ operation: String(operation), payload: canonicalize(payload) }))
+    .digest('hex');
+}
+
+export function validateIdempotencyKey(value) {
+  const key = String(value ?? '').trim();
+  if (!key) {
+    throw new QccBridgeError('QCC_IDEMPOTENCY_REQUIRED', 'A unique idempotencyKey is required before paid QCC calls');
+  }
+  if (!/^[A-Za-z0-9._:-]{8,128}$/.test(key)) {
+    throw new QccBridgeError(
+      'QCC_IDEMPOTENCY_INVALID',
+      'idempotencyKey must be 8-128 characters using letters, numbers, dot, underscore, colon or hyphen',
+    );
+  }
+  return key;
+}
+
+function deriveState(record) {
+  if (record.reviewQueue.length > 0) return 'awaiting-review';
+  if (record.errors.some((item) => item.error?.retryable)) return 'needs-retry';
+  if (record.errors.length > 0) return 'completed-with-errors';
+  return 'completed';
+}
+
+function recomputeSummary(record) {
+  const count = (status) => record.rows.filter((row) => row.qcc_match_status === status).length;
+  record.summary = {
+    ...record.summary,
+    totalRows: record.rows.length,
+    enriched: count('enriched'),
+    ambiguous: count('ambiguous'),
+    unresolved: count('unresolved'),
+    failed: count('failed'),
+    missingName: count('missing-name'),
+    includeRisk: Boolean(record.includeRisk),
+  };
+  record.state = deriveState(record);
+}
+
+function clone(value) {
+  return structuredClone(value);
+}
+
+export class G5RunStore {
+  constructor({
+    clock = () => Date.now(),
+    runIdFactory = () => `g5-${randomUUID()}`,
+    ttlMs = DEFAULT_TTL_MS,
+    maxRuns = DEFAULT_MAX_RUNS,
+    maxAudit = DEFAULT_MAX_AUDIT,
+    maxIdempotency = DEFAULT_MAX_IDEMPOTENCY,
+  } = {}) {
+    this.clock = clock;
+    this.runIdFactory = runIdFactory;
+    this.ttlMs = ttlMs;
+    this.maxRuns = maxRuns;
+    this.maxAudit = maxAudit;
+    this.maxIdempotency = maxIdempotency;
+    this.runs = new Map();
+    this.idempotency = new Map();
+    this.locks = new Set();
+  }
+
+  nowIso() {
+    return new Date(this.clock()).toISOString();
+  }
+
+  cleanup() {
+    const cutoff = this.clock() - this.ttlMs;
+    for (const [id, run] of this.runs) {
+      if (run.touchedAtMs < cutoff) this.runs.delete(id);
+    }
+    for (const [key, entry] of this.idempotency) {
+      // 进行中的付费请求必须保留幂等屏障：即使执行时间超过 TTL，也不能让
+      // 同一 key 的重试绕过首个 Promise，否则可能重复计费。
+      if (entry.settled && entry.touchedAtMs < cutoff) this.idempotency.delete(key);
+    }
+    while (this.runs.size > this.maxRuns) this.runs.delete(this.runs.keys().next().value);
+  }
+
+  async executeOnce({ key: rawKey, fingerprint, operation }) {
+    const key = validateIdempotencyKey(rawKey);
+    this.cleanup();
+    const existing = this.idempotency.get(key);
+    if (existing) {
+      existing.touchedAtMs = this.clock();
+      if (existing.fingerprint !== fingerprint) {
+        throw new QccBridgeError(
+          'QCC_IDEMPOTENCY_CONFLICT',
+          'idempotencyKey was already used with a different request',
+        );
+      }
+      return { value: await existing.promise, replayed: true };
+    }
+    if (this.idempotency.size >= this.maxIdempotency) {
+      throw new QccBridgeError(
+        'QCC_IDEMPOTENCY_CAPACITY',
+        'G5 idempotency cache is full; wait for older requests to expire before starting another paid call',
+        { retryable: true },
+      );
+    }
+
+    const entry = {
+      fingerprint,
+      promise: null,
+      touchedAtMs: this.clock(),
+      settled: false,
+    };
+    entry.promise = Promise.resolve()
+      .then(operation)
+      .finally(() => {
+        entry.settled = true;
+      });
+    this.idempotency.set(key, entry);
+    return { value: await entry.promise, replayed: false };
+  }
+
+  createRun({ headers, nameField, includeRisk, concurrency, result, audit = [] }) {
+    this.cleanup();
+    const id = this.runIdFactory();
+    const at = this.nowIso();
+    const record = {
+      id,
+      state: 'completed',
+      version: 1,
+      createdAt: at,
+      updatedAt: at,
+      touchedAtMs: this.clock(),
+      headers: Array.isArray(headers) ? headers.map(String) : [],
+      nameField: String(nameField ?? 'name'),
+      includeRisk: Boolean(includeRisk),
+      concurrency: Number(concurrency ?? 2),
+      summary: clone(result.summary),
+      rows: clone(result.rows),
+      reviewQueue: clone(result.reviewQueue),
+      errors: clone(result.errors),
+      audit: audit.map(safeAuditEvent).slice(-this.maxAudit),
+    };
+    recomputeSummary(record);
+    this.runs.set(id, record);
+    this.cleanup();
+    return this.snapshot(record);
+  }
+
+  requireRun(id) {
+    this.cleanup();
+    const record = this.runs.get(String(id ?? ''));
+    if (!record) {
+      throw new QccBridgeError(
+        'QCC_RUN_NOT_FOUND',
+        'G5 run was not found or expired; start a new enrichment run',
+        { retryable: false },
+      );
+    }
+    record.touchedAtMs = this.clock();
+    return record;
+  }
+
+  get(id) {
+    return this.snapshot(this.requireRun(id));
+  }
+
+  snapshot(record) {
+    return clone({
+      runId: record.id,
+      state: record.state,
+      version: record.version,
+      createdAt: record.createdAt,
+      updatedAt: record.updatedAt,
+      headers: record.headers,
+      summary: record.summary,
+      rows: record.rows,
+      reviewQueue: record.reviewQueue,
+      errors: record.errors,
+      audit: record.audit,
+      expiresInMs: this.ttlMs,
+      persistence: 'host-memory',
+    });
+  }
+
+  appendAudit(record, event) {
+    record.audit.push(safeAuditEvent(event));
+    if (record.audit.length > this.maxAudit) record.audit.splice(0, record.audit.length - this.maxAudit);
+    record.touchedAtMs = this.clock();
+  }
+
+  touch(record) {
+    record.version += 1;
+    record.updatedAt = this.nowIso();
+    record.touchedAtMs = this.clock();
+    recomputeSummary(record);
+  }
+
+  patchCompany(record, companyName, rowIndexes, result) {
+    record.reviewQueue = record.reviewQueue.filter((item) => item.companyName !== companyName);
+    record.errors = record.errors.filter((item) => item.companyName !== companyName);
+    for (const index of rowIndexes) {
+      const row = record.rows[index] ?? {};
+      if (result.status === 'enriched') {
+        record.rows[index] = {
+          ...row,
+          ...result.fields,
+          qcc_match_status: 'enriched',
+          qcc_source: 'qcc-mcp',
+        };
+      } else {
+        record.rows[index] = { ...row, qcc_match_status: result.status };
+      }
+    }
+    if (result.status === 'ambiguous') {
+      record.reviewQueue.push({ companyName, rowIndexes: [...rowIndexes], candidates: clone(result.candidates) });
+    }
+    if (result.status === 'failed') {
+      record.errors.push({ companyName, rowIndexes: [...rowIndexes], error: clone(result.error) });
+    }
+    this.touch(record);
+  }
+
+  async resolveCandidate(runId, { companyName, selectedCreditNo }, bridge, options = {}) {
+    const record = this.requireRun(runId);
+    const name = String(companyName ?? '').trim();
+    const creditNo = String(selectedCreditNo ?? '').trim();
+    const queued = record.reviewQueue.find((item) => item.companyName === name);
+    if (!queued) {
+      throw new QccBridgeError('QCC_REVIEW_NOT_PENDING', 'This company is not awaiting candidate review');
+    }
+    const candidate = queued.candidates.find((item) => item.creditNo === creditNo);
+    if (!creditNo || !candidate) {
+      throw new QccBridgeError('QCC_CANDIDATE_INVALID', 'Selected credit number is not in the pending candidate list');
+    }
+
+    const lock = `${record.id}:resolve:${name}`;
+    if (this.locks.has(lock)) {
+      throw new QccBridgeError('QCC_OPERATION_IN_PROGRESS', 'Candidate resolution is already in progress', { retryable: true });
+    }
+    this.locks.add(lock);
+    try {
+      const result = await bridge.enrichLockedCompany({
+        companyName: candidate.companyName || name,
+        creditNo,
+      }, {
+        ...options,
+        includeRisk: record.includeRisk,
+        onAudit: (event) => this.appendAudit(record, event),
+      });
+      this.patchCompany(record, name, queued.rowIndexes, result);
+      return this.snapshot(record);
+    } finally {
+      this.locks.delete(lock);
+    }
+  }
+
+  async retryCompanies(runId, companyNames, bridge, options = {}) {
+    const record = this.requireRun(runId);
+    const names = [...new Set((Array.isArray(companyNames) ? companyNames : []).map((name) => String(name).trim()).filter(Boolean))];
+    if (names.length === 0) {
+      throw new QccBridgeError('QCC_RETRY_EMPTY', 'At least one failed company must be selected for manual retry');
+    }
+    const selected = names.map((name) => {
+      const item = record.errors.find((error) => error.companyName === name);
+      if (!item) throw new QccBridgeError('QCC_RETRY_NOT_FAILED', 'Selected company is not in the failed queue');
+      if (!item.error?.retryable) throw new QccBridgeError('QCC_RETRY_NOT_ALLOWED', 'Selected failure is not retryable');
+      return item;
+    });
+    const locks = selected.map((item) => `${record.id}:retry:${item.companyName}`);
+    if (locks.some((lock) => this.locks.has(lock))) {
+      throw new QccBridgeError('QCC_OPERATION_IN_PROGRESS', 'A selected retry is already in progress', { retryable: true });
+    }
+    locks.forEach((lock) => this.locks.add(lock));
+
+    try {
+      for (const item of selected) {
+        let result;
+        try {
+          result = await bridge.enrichCompany(item.companyName, {
+            ...options,
+            includeRisk: record.includeRisk,
+            onAudit: (event) => this.appendAudit(record, event),
+          });
+        } catch (error) {
+          if (error?.code === 'QCC_ABORTED') throw error;
+          const normalized = error instanceof QccBridgeError
+            ? error
+            : new QccBridgeError('QCC_RUNTIME_ERROR', 'QCC enrichment failed', { retryable: true });
+          result = { status: 'failed', error: normalized.toJSON() };
+        }
+        this.patchCompany(record, item.companyName, item.rowIndexes, result);
+      }
+      return this.snapshot(record);
+    } finally {
+      locks.forEach((lock) => this.locks.delete(lock));
+    }
+  }
+}

package/lib/qcc-safety.js

@@ -0,0 +1,77 @@
+/**
+ * G5 安全输出工具。
+ *
+ * 仅用于日志、审计和 E2E 报告；同源业务响应仍由调用方按契约返回。
+ * 这里不尝试“识别所有秘密”，而是采用两层防线：敏感键整值抹除，字符串再做
+ * Bearer/JWT/OAuth 参数、信用代码、邮箱、手机号和已知企业名替换。
+ */
+
+const SECRET_KEY = /(?:^|_)(?:access_token|refresh_token|id_token|token|authorization|cookie|secret|client_secret|code_verifier|api_key|apikey|password)(?:$|_)/i;
+const CREDIT_NO = /\b[0-9A-Z]{18}\b/g;
+const PHONE = /(?<!\d)1[3-9]\d{9}(?!\d)/g;
+const EMAIL = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi;
+const BEARER = /\bBearer\s+[A-Za-z0-9._~+/=-]+/gi;
+const JWT = /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g;
+const URL_SECRET = /([?&](?:code|token|access_token|refresh_token|id_token|client_secret)=)[^&\s]+/gi;
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function companyAliases(companyNames) {
+  const seen = new Set();
+  return (Array.isArray(companyNames) ? companyNames : [])
+    .map((name) => String(name ?? '').trim())
+    .filter((name) => name && !seen.has(name) && seen.add(name))
+    .sort((a, b) => b.length - a.length)
+    .map((name, index) => ({
+      pattern: new RegExp(escapeRegExp(name), 'g'),
+      replacement: `[COMPANY_${String(index + 1).padStart(2, '0')}]`,
+    }));
+}
+
+export function redactSensitiveText(value, options = {}) {
+  let text = String(value ?? '');
+  text = text
+    .replace(BEARER, 'Bearer [REDACTED]')
+    .replace(JWT, '[JWT_REDACTED]')
+    .replace(URL_SECRET, '$1[REDACTED]')
+    .replace(CREDIT_NO, '[CREDIT_NO_REDACTED]')
+    .replace(PHONE, '[PHONE_REDACTED]')
+    .replace(EMAIL, '[EMAIL_REDACTED]');
+  for (const alias of companyAliases(options.companyNames)) {
+    text = text.replace(alias.pattern, alias.replacement);
+  }
+  return text;
+}
+
+export function redactSensitive(value, options = {}) {
+  const seen = new WeakSet();
+
+  const visit = (input, key = '') => {
+    if (SECRET_KEY.test(key)) return '[REDACTED]';
+    if (typeof input === 'string') return redactSensitiveText(input, options);
+    if (input === null || typeof input !== 'object') return input;
+    if (seen.has(input)) return '[CIRCULAR]';
+    seen.add(input);
+    if (Array.isArray(input)) return input.map((item) => visit(item));
+    return Object.fromEntries(Object.entries(input).map(([childKey, child]) => [childKey, visit(child, childKey)]));
+  };
+
+  return visit(value);
+}
+
+export function safeAuditEvent(event) {
+  const source = event && typeof event === 'object' ? event : {};
+  return {
+    at: String(source.at ?? new Date().toISOString()),
+    event: 'qcc-tool-call',
+    toolName: String(source.toolName ?? ''),
+    callId: String(source.callId ?? ''),
+    attempt: Number(source.attempt ?? 0),
+    outcome: String(source.outcome ?? 'unknown'),
+    code: source.code ? String(source.code) : null,
+    upstreamCode: source.upstreamCode ? String(source.upstreamCode) : null,
+    durationMs: Math.max(0, Number(source.durationMs ?? 0)),
+  };
+}