dsh-data-cleaning-agent 0.3.0 → 0.5.0

package/lib/skill-enrich.js

@@ -7,36 +7,81 @@
  *     （依赖 `qcc-dsh-mcp-oauth` 已连接；本 Skill 不重造 OAuth）。
  *
  * 方案 A（模型中介式）：模型亲自调用 `mcp__qcc-company__*` / `mcp__qcc-risk__*`
- * 完成消歧 → 工商详情 → 风险标签，再组装结果。本插件零后端改动。
+ * / `mcp__qcc-ipr__*` / `mcp__qcc-operation__*` 完成消歧 → 工商详情 → 各域维度，
+ * 再组装结果。本插件零后端改动（Host Bridge 批量是独立于本 Skill 的方案 B）。
  */
+import {
+  QCC_PHASE2_COMPANY_TOOLS,
+  QCC_PHASE2_DIMENSION_GROUPS,
+  QCC_PHASE2_HISTORY_TOOLS,
+} from './qcc-phase2.js';
+import {
+  QCC_PHASE3_DOMAIN_META,
+  QCC_PHASE3_TOOL_NAMES,
+  canonicalPhase3ToolName,
+} from './qcc-phase3.js';
+
 export const ENRICH_SKILL_NAME = 'enterprise-enrichment';
 
+const companyTools = QCC_PHASE2_COMPANY_TOOLS;
+const historyTools = QCC_PHASE2_HISTORY_TOOLS;
+
+const groupSummary = Object.entries(QCC_PHASE2_DIMENSION_GROUPS)
+  .map(([id, group]) => `   - \`${id}\`（${group.label}）: ${group.tools.join(', ')}`)
+  .join('\n');
+
+/**
+ * 0.5.0 三大域（风险/知产/经营）的用户可选域组说明。
+ * 每一域均为 basic 授权 + 按次计费 + 调用前必须确认；工具名一律用规范名。
+ */
+const phase3GroupSummary = Object.keys(QCC_PHASE3_TOOL_NAMES)
+  .map((domain) => {
+    const meta = QCC_PHASE3_DOMAIN_META[domain];
+    const tools = QCC_PHASE3_TOOL_NAMES[domain].map((name) => canonicalPhase3ToolName(domain, name));
+    return `   - \`${domain}\`（${meta.label} · basic · 按次计费 · 调用前须确认）: ${tools.join(', ')}`;
+  })
+  .join('\n');
+
 export function registerEnrichSkill(skills) {
   return skills.register({
     name: ENRICH_SKILL_NAME,
     description:
-      'Enrich a list of company names with the latest Qichacha (QCC) business-registration fields via the QCC MCP tools.',
+      'Enrich company lists with Qichacha (QCC) registration, company panorama, ownership, governance, risk, intellectual-property, operations, and optional historical-business dimensions.',
     whenToUse:
-      'When the user gives a list of company names (possibly fuzzy or incomplete) and asks to fill in credit code / legal representative / registered capital / establishment date / registration & business status / risk tags, or asks to "enrich / complete with Qichacha (企查查)".',
+      'When the user gives company names and asks to enrich / complete them with Qichacha (企查查), including registration fields, company panorama, ownership penetration, governance, historical changes, risk tags, intellectual property, or operational / bidding dimensions.',
     source: 'dsh-data-cleaning-agent',
     content: [
-      'You are an enterprise-list enrichment assistant. You fill a list of company names with the latest Qichacha (QCC) business-registration fields by calling the QCC MCP tools. Never invent, pad, or fabricate any field.',
+      'You are an enterprise-list enrichment assistant. You fill company lists with Qichacha (QCC) data by calling QCC MCP tools. Never invent, pad, or fabricate any field.',
       '',
       'Workflow:',
       '1. Check QCC availability first: run `qcc_oauth_status`. If not connected, tell the user to run `qcc_oauth_connect` first and stop. If the token is expired, guide the user to `qcc_oauth_connect` (it reuses the grant and refreshes without a new authorization page).',
       '2. Parse the company-name list from what the user gave (pasted text / CSV / JSON / inline list). Keep only the distinct company-name column.',
-      '3. For EACH name: run `mcp__qcc-company__get_company_by_query`.',
+      `3. For EACH name: run \`${companyTools.resolveEntity}\`.`,
       '   - Unique exact match → lock that entity and keep its credit code.',
       '   - Multiple candidates → DO NOT auto-pick the first. List the candidates (name + region + credit code) and ask the user which one to use.',
       '   - No match → mark that row as `unresolved` and continue.',
-      '4. For each locked entity: run `mcp__qcc-company__get_company_registration_info` to fill `credit_no` / `legal_rep` / `reg_capital` / `establish_date` / `reg_status` / `biz_status`. When the user also wants risk tags, run `mcp__qcc-risk__get_company_risk_scan` and fill `risk_tags` from the hit dimensions + counts only.',
-      '5. Assemble the enriched table. NEVER invent a field — if QCC returns no value, leave it empty and mark the row/field `unresolved`.',
-      '6. Report a one-line summary (enriched N / unresolved M / multi-candidate K) plus the enriched table as Markdown. For large lists (dozens of rows or more), process in batches and report progress per batch; do not drop rows silently.',
+      `4. For each locked entity, always run \`${companyTools.registration}\`. Run \`${companyTools.verifyIdentity}\` when the input includes a credit code or the user asks for identity verification.`,
+      '5. Determine requested dimension groups from the user request. If it is not explicit, ask the user to choose among the 0.4.0 groups (`panorama`, `ownership`, `governance`, `history`) and the 0.5.0 domains (`risk`, `ipr`, `operation`); do not invoke every tool by default. The verified 0.4.0 group contract is:',
+      groupSummary,
+      '6. Call only the tools required by the selected groups. Process large lists in explicit batches, announce the next batch before paid calls, preserve input row order, and never drop a row silently.',
+      `7. The \`history\` group requires an enterprise-certified account. Only call ${Object.values(historyTools).map((tool) => `\`${tool}\``).join(', ')} when the user requested history and the account is eligible. If a history tool is unavailable or returns a permission error, mark the group \`permission_required\` or \`not_available\`, continue current-data groups, and never replace history with guessed values.`,
+      '8. The 0.5.0 domains are risk / intellectual-property / operations. Each is basic access, per-call paid, and requires explicit user confirmation BEFORE any call; do not call them implicitly and do not call any tool before the user confirms the domain and the batch. The verified 0.5.0 domain contract is:',
+      phase3GroupSummary,
+      '9. Within a confirmed 0.5.0 domain, call only that domain\'s tools, and only the ones that answer the requested dimensions. For risk, prefer `mcp__qcc-risk__get_company_risk_scan` (35-factor hit counts) as the entry scan and `mcp__qcc-risk__get_company_related_risk_scan` for related-party risk; `mcp__qcc-risk__get_judicial_document_detail` additionally requires `documentId`, so call it only with a document ID returned by `mcp__qcc-risk__get_judicial_documents`. For intellectual property, prefer `mcp__qcc-ipr__get_patent_info`, `mcp__qcc-ipr__get_trademark_info`, `mcp__qcc-ipr__get_software_copyright_info` as entry points. For operations, prefer `mcp__qcc-operation__get_bidding_info` (bid role), `mcp__qcc-operation__get_financing_records`, `mcp__qcc-operation__get_qualifications` as entry points. Use hit dimensions + returned counts only; do not derive risk conclusions or ratings beyond what the tool returned.',
+      '10. Degrade explicitly on the three failure classes and never fabricate a fallback:',
+      '   - permission / authorization → mark `permission_required` and continue other confirmed domains;',
+      '   - no data / empty result → mark `not_available`; an absent field never means "none" or zero;',
+      '   - rate limit / quota / throttling → mark `rate_limited` and STOP that domain for this batch; do not retry in a loop or switch to an unconfirmed domain.',
+      '11. Assemble each requested dimension with `value`, `status`, and `sourceTool`. Missing values are `unresolved`; an absent field never means "none" or zero.',
+      '12. Report enriched / unresolved / ambiguous / permission-required / rate-limited counts and a small requested preview. Do not paste a full sensitive list into chat. Use a same-origin Host download or artifact when that capability is available; otherwise say that no downloadable artifact was created instead of pretending one exists.',
       '',
       'Safety rules:',
       '- Never fabricate a credit code, legal representative, capital, amount, ratio, or status.',
       '- Never auto-select among ambiguous candidates — always confirm with the user.',
-      '- Quote amounts / ratios / counts exactly as the QCC tool returned them; never recompute or estimate.',
+      '- Quote amounts / ratios / counts exactly as the QCC tool returned them; never recompute, multiply ownership chains, aggregate, or estimate.',
+      '- Preserve provenance: every populated dimension must identify the QCC source tool that returned it (`sourceTool`).',
+      '- Do not continue a paid batch after cancellation, authorization failure, or an unresolved ambiguity that affects entity identity.',
+      '- Make zero QCC calls before the user confirms the domain and batch; idempotent replay must not re-bill.',
       '- Never expose QCC tokens or credentials.',
     ].join('\n'),
   });

package/lib/web.js

@@ -9,6 +9,9 @@
  */
 import { parseCsv, parseXlsx, parseJson, detectFormat, toCsv } from './engine.js';
 import { runSync, DataCleaningJobs } from './jobs.js';
+import { QccBridgeError, QccHostBridge } from './qcc.js';
+import { fingerprintRequest, G5RunStore } from './qcc-runs.js';
+import { PHASE3_BATCH_LIMITS, Phase3BatchService, Phase3RunStore } from './qcc-phase3-batch.js';
 
 const MAX_BODY = 16 * 1024 * 1024; // 16 MiB 上传上限（MVP）
 
@@ -52,6 +55,49 @@ async function readBody(req, max = MAX_BODY) {
   return Buffer.concat(chunks);
 }
 
+function requirePaidConfirmation(payload) {
+  if (payload?.confirmPaidCalls !== true) {
+    throw new QccBridgeError(
+      'QCC_CONFIRM_REQUIRED',
+      'Set confirmPaidCalls=true after the current user confirms use of their own QCC account quota or billing.',
+    );
+  }
+}
+
+function qccHttpStatus(code) {
+  if (code === 'QCC_RUN_NOT_FOUND') return 404;
+  if (code === 'QCC_AUTH_REQUIRED') return 401;
+  if (code === 'QCC_PERMISSION_DENIED') return 403;
+  if (code === 'QCC_QUOTA_EXHAUSTED') return 402;
+  if (code === 'QCC_RATE_LIMITED') return 429;
+  if (code === 'QCC_TIMEOUT') return 504;
+  if (
+    code === 'QCC_NOT_CONNECTED'
+    || code === 'QCC_TOOL_UNAVAILABLE'
+    || code === 'QCC_UPSTREAM_UNAVAILABLE'
+    || code === 'QCC_IDEMPOTENCY_CAPACITY'
+  ) return 503;
+  if (
+    code === 'QCC_CONFIRM_REQUIRED'
+    || code === 'QCC_ABORTED'
+    || code === 'QCC_IDEMPOTENCY_CONFLICT'
+    || code === 'QCC_REVIEW_NOT_PENDING'
+    || code === 'QCC_CANDIDATE_INVALID'
+    || code === 'QCC_OPERATION_IN_PROGRESS'
+    || code === 'QCC_RETRY_NOT_FAILED'
+    || code === 'QCC_RETRY_NOT_ALLOWED'
+  ) return 409;
+  return 400;
+}
+
+function writeQccError(res, error) {
+  const code = error?.code ?? 'QCC_BRIDGE';
+  const payload = error instanceof QccBridgeError
+    ? error.toJSON()
+    : { code, message: 'G5 Host Bridge request failed' };
+  writeJson(res, qccHttpStatus(code), { ok: false, ...payload });
+}
+
 /** 从 JSON 协议解析上传：{ filename, content }。content 为字符串；xlsx 时为 base64。 */
 async function parseUpload(body) {
   let payload;
@@ -147,7 +193,12 @@ async function withRows() {
     if (!p.ok) throw new Error(JSON.stringify(p));
     return { rows: p.rows, headers: p.headers };
   }
-  return { rows: JSON.parse($('src').value || '[]'), headers: null };
+  const content = $('src').value.trim();
+  if (!content) return { rows: [], headers: null };
+  if (content.startsWith('[')) return { rows: JSON.parse(content), headers: null };
+  const p = await call('/data-cleaning/api/mvp/parse', { filename: 'data.csv', content });
+  if (!p.ok) throw new Error(JSON.stringify(p));
+  return { rows: p.rows, headers: p.headers };
 }
 
 $('parse').onclick = async () => {
@@ -212,6 +263,11 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
   const tools = wctx.tools;
   const skills = wctx.skills;
   const disposers = [];
+  const qccBridge = new QccHostBridge({ tools, logger });
+  const g5Runs = new G5RunStore();
+  const phase3Service = new Phase3BatchService(qccBridge);
+  const phase3Runs = new Phase3RunStore();
+  report.qccBridgeMounted = true;
   let state = null; // DataCleaningJobs，惰性初始化
   let stateReady = null;
 
@@ -248,10 +304,288 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
         skillListed: null,
         jobs: Boolean(wctx.jobs),
         storageDomain: Boolean(wctx.storageDomain),
+        qccBridge: qccBridge.capabilities(),
       },
     });
   });
 
+  register('/data-cleaning/api/g5/capabilities', (req, res) => {
+    if (!isTrusted(req)) return writeJson(res, 403, { ok: false, error: 'untrusted origin' });
+    writeJson(res, 200, {
+      ok: true,
+      marker: 'g5-host-bridge',
+      capabilities: qccBridge.capabilities(),
+      limits: { maxRows: 100, maxConcurrency: 4 },
+      paidCallConfirmationRequired: true,
+      idempotencyRequired: true,
+      candidateResume: true,
+      manualRetry: true,
+      runPersistence: 'host-memory',
+    });
+  });
+
+  register('/data-cleaning/api/phase2/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: 'qcc-phase2-capabilities',
+      capabilities: qccBridge.phase2Capabilities(),
+      executesTools: false,
+      paidCalls: false,
+      historyAuthorizationRequiresRealCall: true,
+    });
+  });
+
+  register('/data-cleaning/api/phase3/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: 'qcc-phase3-capabilities',
+      capabilities: qccBridge.phase3Capabilities(),
+      limits: PHASE3_BATCH_LIMITS,
+      executesTools: false,
+      paidCalls: false,
+      estimateEndpoint: '/data-cleaning/api/phase3/estimate',
+      paidCallConfirmationRequired: true,
+      idempotencyRequired: true,
+      candidateResume: true,
+      manualRetry: true,
+      runPersistence: 'host-memory',
+    });
+  });
+
+  const phase3Payload = (run, replayed = false) => {
+    const headers = [...new Set([...run.headers, ...run.rows.flatMap((row) => Object.keys(row))])];
+    const reviewRows = run.reviewQueue.flatMap((item) => item.candidates.map((candidate) => ({
+      input_company: item.companyName,
+      candidate_company: candidate.companyName,
+      credit_no: candidate.creditNo,
+      legal_rep: Array.isArray(candidate.legalRep) ? candidate.legalRep.join('；') : '',
+      status: candidate.status,
+    })));
+    return {
+      ok: true,
+      marker: 'qcc-phase3-batch',
+      ...run,
+      idempotencyReplayed: replayed,
+      rowCount: run.rows.length,
+      csv: toCsv(headers, run.rows),
+      reviewCsv: toCsv(['input_company', 'candidate_company', 'credit_no', 'legal_rep', 'status'], reviewRows),
+      downloadName: 'qcc-phase3-enriched.csv',
+      reviewDownloadName: 'qcc-phase3-review.csv',
+    };
+  };
+
+  const phase3Options = (payload) => ({
+    nameField: String(payload?.nameField ?? 'name'),
+    domains: Array.isArray(payload?.domains) ? payload.domains.map(String) : [],
+    tools: Array.isArray(payload?.tools) ? payload.tools.map(String) : [],
+    toolArguments: payload?.toolArguments && typeof payload.toolArguments === 'object' ? payload.toolArguments : {},
+    concurrency: Number(payload?.concurrency ?? 2),
+    maxRows: Number(payload?.maxRows ?? PHASE3_BATCH_LIMITS.maxRows),
+    maxCalls: Number(payload?.maxCalls ?? PHASE3_BATCH_LIMITS.defaultMaxCalls),
+  });
+
+  register('/data-cleaning/api/phase3/estimate', async (req, res) => {
+    if (!isTrusted(req)) return writeJson(res, 403, { ok: false, error: 'untrusted origin' });
+    if (req.method !== 'POST') return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'POST required' });
+    try {
+      const payload = JSON.parse((await readBody(req)).toString('utf8'));
+      const rows = Array.isArray(payload?.rows) ? payload.rows : [];
+      writeJson(res, 200, { ok: true, marker: 'qcc-phase3-estimate', estimate: phase3Service.estimate(rows, phase3Options(payload)) });
+    } catch (error) {
+      writeQccError(res, error);
+    }
+  });
+
+  register('/data-cleaning/api/phase3/enrich', async (req, res) => {
+    if (!isTrusted(req)) return writeJson(res, 403, { ok: false, error: 'untrusted origin' });
+    if (req.method !== 'POST') return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'POST required' });
+    try {
+      const payload = JSON.parse((await readBody(req)).toString('utf8'));
+      requirePaidConfirmation(payload);
+      const rows = Array.isArray(payload?.rows) ? payload.rows : [];
+      const headers = Array.isArray(payload?.headers) ? payload.headers.map(String) : [];
+      const options = phase3Options(payload);
+      const fingerprintInput = { rows, headers, ...options };
+      const executed = await g5Runs.executeOnce({
+        key: payload?.idempotencyKey,
+        fingerprint: fingerprintRequest('phase3-enrich', fingerprintInput),
+        operation: async () => {
+          const result = await phase3Service.run(rows, options);
+          return phase3Runs.create({ headers, nameField: options.nameField, input: options, result });
+        },
+      });
+      writeJson(res, 200, phase3Payload(executed.value, executed.replayed));
+    } catch (error) {
+      writeQccError(res, error);
+    }
+  });
+
+  register('/data-cleaning/api/phase3/resolve', async (req, res) => {
+    if (!isTrusted(req)) return writeJson(res, 403, { ok: false, error: 'untrusted origin' });
+    if (req.method !== 'POST') return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'POST required' });
+    try {
+      const payload = JSON.parse((await readBody(req)).toString('utf8'));
+      requirePaidConfirmation(payload);
+      const input = {
+        runId: String(payload?.runId ?? ''),
+        companyName: String(payload?.companyName ?? ''),
+        selectedCreditNo: String(payload?.selectedCreditNo ?? ''),
+      };
+      const executed = await g5Runs.executeOnce({
+        key: payload?.idempotencyKey,
+        fingerprint: fingerprintRequest('phase3-resolve', input),
+        operation: () => phase3Runs.resolve(input.runId, input, phase3Service),
+      });
+      writeJson(res, 200, phase3Payload(executed.value, executed.replayed));
+    } catch (error) {
+      writeQccError(res, error);
+    }
+  });
+
+  register('/data-cleaning/api/phase3/retry', async (req, res) => {
+    if (!isTrusted(req)) return writeJson(res, 403, { ok: false, error: 'untrusted origin' });
+    if (req.method !== 'POST') return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'POST required' });
+    try {
+      const payload = JSON.parse((await readBody(req)).toString('utf8'));
+      requirePaidConfirmation(payload);
+      const input = {
+        runId: String(payload?.runId ?? ''),
+        companyNames: Array.isArray(payload?.companyNames) ? payload.companyNames.map(String) : [],
+      };
+      const executed = await g5Runs.executeOnce({
+        key: payload?.idempotencyKey,
+        fingerprint: fingerprintRequest('phase3-retry', input),
+        operation: () => phase3Runs.retry(input.runId, input.companyNames, phase3Service),
+      });
+      writeJson(res, 200, phase3Payload(executed.value, executed.replayed));
+    } catch (error) {
+      writeQccError(res, error);
+    }
+  });
+
+  register('/data-cleaning/api/phase3/run', (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' });
+    try {
+      const runId = String((req.url ?? '').split('/').filter(Boolean).pop() ?? '');
+      writeJson(res, 200, phase3Payload(phase3Runs.get(runId)));
+    } catch (error) {
+      writeQccError(res, error);
+    }
+  });
+
+  const runPayload = (run, replayed = false) => {
+    const headers = [...new Set([
+      ...run.headers,
+      ...run.rows.flatMap((row) => Object.keys(row)),
+    ])];
+    return {
+      ok: true,
+      marker: 'g5-host-bridge',
+      ...run,
+      idempotencyReplayed: replayed,
+      rowCount: run.rows.length,
+      csv: toCsv(headers, run.rows),
+      downloadName: 'qcc-enriched.csv',
+    };
+  };
+
+  register('/data-cleaning/api/g5/enrich', async (req, res) => {
+    if (!isTrusted(req)) return writeJson(res, 403, { ok: false, error: 'untrusted origin' });
+    if (req.method !== 'POST') return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'POST required' });
+    try {
+      const body = await readBody(req);
+      const payload = JSON.parse(body.toString('utf8'));
+      requirePaidConfirmation(payload);
+      const rows = Array.isArray(payload?.rows) ? payload.rows : [];
+      const headers = Array.isArray(payload?.headers) ? payload.headers.map(String) : [];
+      const nameField = String(payload?.nameField ?? 'name');
+      const includeRisk = payload?.includeRisk === true;
+      const concurrency = Number(payload?.concurrency ?? 2);
+      const input = { rows, headers, nameField, includeRisk, concurrency };
+      const executed = await g5Runs.executeOnce({
+        key: payload?.idempotencyKey,
+        fingerprint: fingerprintRequest('enrich', input),
+        operation: async () => {
+          const audit = [];
+          const result = await qccBridge.enrichRows(rows, {
+            nameField,
+            includeRisk,
+            concurrency,
+            maxRows: 100,
+            onAudit: (event) => audit.push(event),
+          });
+          return g5Runs.createRun({ headers, nameField, includeRisk, concurrency, result, audit });
+        },
+      });
+      writeJson(res, 200, runPayload(executed.value, executed.replayed));
+    } catch (error) {
+      writeQccError(res, error);
+    }
+  });
+
+  register('/data-cleaning/api/g5/resolve', async (req, res) => {
+    if (!isTrusted(req)) return writeJson(res, 403, { ok: false, error: 'untrusted origin' });
+    if (req.method !== 'POST') return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'POST required' });
+    try {
+      const payload = JSON.parse((await readBody(req)).toString('utf8'));
+      requirePaidConfirmation(payload);
+      const input = {
+        runId: String(payload?.runId ?? ''),
+        companyName: String(payload?.companyName ?? ''),
+        selectedCreditNo: String(payload?.selectedCreditNo ?? ''),
+      };
+      const executed = await g5Runs.executeOnce({
+        key: payload?.idempotencyKey,
+        fingerprint: fingerprintRequest('resolve', input),
+        operation: () => g5Runs.resolveCandidate(input.runId, input, qccBridge),
+      });
+      writeJson(res, 200, runPayload(executed.value, executed.replayed));
+    } catch (error) {
+      writeQccError(res, error);
+    }
+  });
+
+  register('/data-cleaning/api/g5/retry', async (req, res) => {
+    if (!isTrusted(req)) return writeJson(res, 403, { ok: false, error: 'untrusted origin' });
+    if (req.method !== 'POST') return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'POST required' });
+    try {
+      const payload = JSON.parse((await readBody(req)).toString('utf8'));
+      requirePaidConfirmation(payload);
+      const input = {
+        runId: String(payload?.runId ?? ''),
+        companyNames: Array.isArray(payload?.companyNames) ? payload.companyNames.map(String) : [],
+      };
+      const executed = await g5Runs.executeOnce({
+        key: payload?.idempotencyKey,
+        fingerprint: fingerprintRequest('retry', input),
+        operation: () => g5Runs.retryCompanies(input.runId, input.companyNames, qccBridge),
+      });
+      writeJson(res, 200, runPayload(executed.value, executed.replayed));
+    } catch (error) {
+      writeQccError(res, error);
+    }
+  });
+
+  register('/data-cleaning/api/g5/run', (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' });
+    try {
+      const runId = String((req.url ?? '').split('/').filter(Boolean).pop() ?? '');
+      writeJson(res, 200, runPayload(g5Runs.get(runId)));
+    } catch (error) {
+      writeQccError(res, error);
+    }
+  });
+
   register('/data-cleaning/api/mvp/parse', async (req, res) => {
     if (!isTrusted(req)) return writeJson(res, 403, { ok: false, error: 'untrusted origin' });
     try {
@@ -277,7 +611,22 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
       const payload = JSON.parse(body.toString('utf8'));
       const rows = Array.isArray(payload?.rows) ? payload.rows : [];
       const headers = Array.isArray(payload?.headers) ? payload.headers : [];
-      const result = runSync(kind, rows, { headers });
+      const requested = payload?.options && typeof payload.options === 'object'
+        ? payload.options
+        : {};
+      const options = { headers };
+      if (Array.isArray(requested.required)) {
+        options.required = requested.required.map(String).filter(Boolean).slice(0, 32);
+      }
+      for (const key of ['amountField', 'dedupeOn', 'phoneField']) {
+        if (Object.hasOwn(requested, key)) {
+          options[key] = requested[key] === null ? null : String(requested[key]);
+        }
+      }
+      if (Object.hasOwn(requested, 'fillableName')) {
+        options.fillableName = requested.fillableName === true;
+      }
+      const result = runSync(kind, rows, options);
       const csv = result.rows.length ? toCsv(headers.length ? headers : result.rows[0] ? Object.keys(result.rows[0]) : [], result.rows) : '';
       writeJson(res, 200, {
         ok: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-data-cleaning-agent",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Clean, complete, and profile enterprise name lists in DeepSeek Harness — a data cleaning & completion agent plugin with local CSV/XLSX/JSON engine and optional Qichacha (QCC) MCP enrichment. Maintained by Qichacha/QCC.",
   "type": "module",
   "main": "lib/index.js",
@@ -23,14 +23,24 @@
     "docs/FIRST-CONTRIBUTION.md",
     "docs/COMPATIBILITY.md",
     "docs/QCC-ENRICHMENT-DESIGN.md",
-    "docs/QCC-PHASES-ROADMAP.md"
+    "docs/QCC-PHASES-ROADMAP.md",
+    "docs/PHASE2-ACCEPTANCE.md",
+    "docs/PHASE3-ACCEPTANCE.md",
+    "docs/RELEASE-0.4.0.md",
+    "docs/RELEASE-0.5.0.md",
+    "docs/G5-HOST-BRIDGE.md",
+    "docs/G5-E2E-RUNBOOK.md"
   ],
   "scripts": {
     "test": "node --test",
-    "lint": "node --check lib/index.js && node --check lib/engine.js && node --check lib/tools.js && node --check lib/skill.js && node --check lib/skill-enrich.js && node --check lib/jobs.js && node --check lib/web.js && node --check lib/client.js",
+    "lint": "node --check lib/index.js && node --check lib/engine.js && node --check lib/tools.js && node --check lib/skill.js && node --check lib/qcc-phase2.js && node --check lib/qcc-phase3.js && node --check lib/qcc-phase3-batch.js && node --check lib/qcc-phase2-acceptance.js && node --check lib/skill-enrich.js && node --check lib/jobs.js && node --check lib/qcc-safety.js && node --check lib/qcc.js && node --check lib/qcc-runs.js && node --check lib/web.js && node --check lib/client.js && node --check scripts/check-market-registration.mjs && node --check scripts/g5-e2e.mjs && node --check scripts/phase3-e2e.mjs && node --check scripts/phase2-acceptance.mjs",
     "docs:check": "node scripts/check-readme-version.mjs",
     "marketing:check": "node scripts/check-marketing.mjs",
     "verify-pack": "node scripts/verify-pack.mjs",
+    "market:check": "node scripts/check-market-registration.mjs",
+    "e2e:g5": "node scripts/g5-e2e.mjs",
+    "e2e:phase3": "node scripts/phase3-e2e.mjs",
+    "e2e:phase2": "node scripts/phase2-acceptance.mjs",
     "check": "npm run lint && npm run docs:check && npm run marketing:check && npm run verify-pack && npm test",
     "prepublishOnly": "npm run check"
   },
@@ -77,12 +87,21 @@
   "dependencies": {
     "xlsx": "^0.18.5"
   },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-ui-conversation": "*",
+    "@deepseek-ai/dsh-client-ui-layout": "*",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
     "client": {
-      "inject": [],
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ],
       "platform": "web"
     }
   }