dsh-data-cleaning-agent 0.2.1 → 0.4.0

package/lib/skill-enrich.js

@@ -0,0 +1,63 @@
+/**
+ * 内嵌 Skill：`enterprise-enrichment`（企查查企业名单补全）。
+ *
+ * 与 `data-cleaning` 职责分离：
+ *   - `data-cleaning`：确定性清洗 / 补全 / 概览（本地引擎，不依赖外部数据）。
+ *   - `enterprise-enrichment`：用企查查 MCP 工具按最新工商信息补全企业名单
+ *     （依赖 `qcc-dsh-mcp-oauth` 已连接；本 Skill 不重造 OAuth）。
+ *
+ * 方案 A（模型中介式）：模型亲自调用 `mcp__qcc-company__*` / `mcp__qcc-risk__*`
+ * 完成消歧 → 工商详情 → 风险标签，再组装结果。本插件零后端改动。
+ */
+import {
+  QCC_PHASE2_COMPANY_TOOLS,
+  QCC_PHASE2_DIMENSION_GROUPS,
+  QCC_PHASE2_HISTORY_TOOLS,
+} from './qcc-phase2.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');
+
+export function registerEnrichSkill(skills) {
+  return skills.register({
+    name: ENRICH_SKILL_NAME,
+    description:
+      'Enrich company lists with Qichacha (QCC) registration, company panorama, ownership, governance, and optional historical-business dimensions.',
+    whenToUse:
+      'When the user gives company names and asks to enrich / complete them with Qichacha (企查查), including registration fields, company panorama, ownership penetration, governance, historical changes, or risk tags.',
+    source: 'dsh-data-cleaning-agent',
+    content: [
+      '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 \`${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, 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 `panorama`, `ownership`, `governance`, and/or `history`; do not invoke every 0.4.0 tool by default. The verified 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. When risk tags are explicitly requested, run `mcp__qcc-risk__get_company_risk_scan` and use hit dimensions + returned counts only. Risk is outside the 0.4.0 panorama contract and must not be called implicitly.',
+      '9. Assemble each requested dimension with `value`, `status`, and `source_tool`. Missing values are `unresolved`; an absent field never means "none" or zero.',
+      '10. Report enriched / unresolved / ambiguous / permission-required 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, multiply ownership chains, aggregate, or estimate.',
+      '- Preserve provenance: every populated dimension must identify the QCC source tool that returned it.',
+      '- Do not continue a paid batch after cancellation, authorization failure, or an unresolved ambiguity that affects entity identity.',
+      '- Never expose QCC tokens or credentials.',
+    ].join('\n'),
+  });
+}

package/lib/web.js

@@ -9,6 +9,8 @@
  */
 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';
 
 const MAX_BODY = 16 * 1024 * 1024; // 16 MiB 上传上限（MVP）
 
@@ -52,6 +54,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 user confirms QCC paid data calls.',
+    );
+  }
+}
+
+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 +192,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 +262,9 @@ 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();
+  report.qccBridgeMounted = true;
   let state = null; // DataCleaningJobs，惰性初始化
   let stateReady = null;
 
@@ -248,10 +301,145 @@ 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,
+    });
+  });
+
+  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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-data-cleaning-agent",
-  "version": "0.2.1",
+  "version": "0.4.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",
@@ -21,14 +21,23 @@
     "marketing",
     "docs/USER-GUIDE.md",
     "docs/FIRST-CONTRIBUTION.md",
-    "docs/COMPATIBILITY.md"
+    "docs/COMPATIBILITY.md",
+    "docs/QCC-ENRICHMENT-DESIGN.md",
+    "docs/QCC-PHASES-ROADMAP.md",
+    "docs/PHASE2-ACCEPTANCE.md",
+    "docs/RELEASE-0.4.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/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-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/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: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"
   },