dsh-data-cleaning-agent 0.5.3 → 0.6.1

package/lib/engine.js

@@ -221,7 +221,7 @@ export function completeRows(rows, opts = {}) {
 
   return {
     total: input.length,
-    completed: completed.length,
+    completedCount: completed.length,
     incompleteCount: incomplete.length,
     fillStats,
     incomplete,

package/lib/index.js

@@ -59,12 +59,17 @@ export function apply(ctx, config) {
 
   // 3. web 半区（仅 web 组合存在；headless 组合无 webServer/webRuntime，inject 会失败）
   try {
-    ctx.inject(['webServer', 'webRuntime', 'tools', 'skills', 'jobs', 'storageDomain'], (wctx) => {
-      const dispose = mountWebRoutes(wctx, { logger: ctx.logger, report, TOOL_NAME: TOOL_CLEAN, SKILL_NAME });
-      if (typeof dispose === 'function' && typeof ctx.effect === 'function') {
-        ctx.effect(() => () => dispose(), 'data-cleaning-agent: web routes');
+    ctx.inject(['webServer', 'webRuntime', 'tools', 'skills', 'jobs', 'storageDomain', 'fs'], (wctx) => {
+      try {
+        const dispose = mountWebRoutes(wctx, { logger: ctx.logger, report, TOOL_NAME: TOOL_CLEAN, SKILL_NAME });
+        if (typeof dispose === 'function' && typeof ctx.effect === 'function') {
+          ctx.effect(() => () => dispose(), 'data-cleaning-agent: web routes');
+        }
+        report.webMounted = true;
+      } catch (error) {
+        report.webSkipped = true;
+        console.warn(`[dc-agent] web half failed during deferred mount: ${error instanceof Error ? error.stack : String(error)}`);
       }
-      report.webMounted = true;
     });
   } catch (error) {
     report.webSkipped = true;

package/lib/jobs.js

@@ -35,7 +35,7 @@ export function runSync(kind, rows, opts = {}) {
     }
     case 'complete': {
       const r = completeRows(rows, opts);
-      return { kind, summary: { total: r.total, completed: r.completed, incompleteCount: r.incompleteCount, name: r.fillStats.name, amount: r.fillStats.amount, phoneNormalized: r.fillStats.phoneNormalized }, rows: r.completed, headers: opts.headers ?? [] };
+      return { kind, summary: { total: r.total, completed: r.completedCount, incompleteCount: r.incompleteCount, name: r.fillStats.name, amount: r.fillStats.amount, phoneNormalized: r.fillStats.phoneNormalized }, rows: r.completed, headers: opts.headers ?? [] };
     }
     case 'profile': {
       const r = profileRows(rows, opts);

package/lib/qcc-command.js

@@ -0,0 +1,276 @@
+/**
+ * Agent-owned QCC command bridge.
+ *
+ * DSH Code Mode only permits dynamic MCP calls as nested executions of an
+ * Agent-owned tool call.  The Web workbench therefore stages rows under an
+ * opaque command id, sends only that id through the visible conversation,
+ * and lets this high-level tool perform the paid calls with exec.token.
+ */
+import { randomUUID } from 'node:crypto';
+import { QccBridgeError } from './qcc.js';
+
+export const TOOL_QCC_COMMAND = 'data_cleaning_qcc_run';
+
+const DEFAULT_TTL_MS = 30 * 60 * 1000;
+const DEFAULT_MAX_COMMANDS = 50;
+
+function clone(value) {
+  return structuredClone(value);
+}
+
+function safeError(error) {
+  if (error instanceof QccBridgeError) return error.toJSON();
+  return new QccBridgeError('QCC_COMMAND_FAILED', 'Data-cleaning QCC command failed', {
+    retryable: false,
+  }).toJSON();
+}
+
+function requiredText(value, code, message) {
+  const text = String(value ?? '').trim();
+  if (!text) throw new QccBridgeError(code, message);
+  return text;
+}
+
+function normalizedInput(input = {}) {
+  const kind = String(input.kind ?? 'enrich');
+  if (!['enrich', 'resolve', 'retry'].includes(kind)) {
+    throw new QccBridgeError('QCC_COMMAND_KIND_INVALID', 'Unsupported data-cleaning QCC command kind');
+  }
+  const taskId = requiredText(input.taskId, 'QCC_COMMAND_TASK_REQUIRED', 'A workflow taskId is required');
+  if (kind === 'enrich') {
+    const rows = Array.isArray(input.rows) ? input.rows : [];
+    if (rows.length === 0) throw new QccBridgeError('QCC_INVALID_ROWS', 'At least one row is required');
+    if (rows.length > 100) throw new QccBridgeError('QCC_BATCH_TOO_LARGE', 'QCC batch exceeds 100 rows');
+    return {
+      kind,
+      taskId,
+      rows: clone(rows),
+      headers: Array.isArray(input.headers) ? input.headers.map(String) : [],
+      nameField: String(input.nameField ?? 'name'),
+      includeRisk: input.includeRisk === true,
+      concurrency: Math.min(4, Math.max(1, Math.trunc(Number(input.concurrency ?? 2)))),
+    };
+  }
+  const runId = requiredText(input.runId, 'QCC_RUN_NOT_FOUND', 'A G5 runId is required');
+  if (kind === 'resolve') {
+    return {
+      kind,
+      taskId,
+      runId,
+      companyName: requiredText(input.companyName, 'QCC_REVIEW_NOT_PENDING', 'A company name is required'),
+      selectedCreditNo: requiredText(input.selectedCreditNo, 'QCC_CANDIDATE_INVALID', 'A selected credit number is required'),
+    };
+  }
+  const companyNames = [...new Set((Array.isArray(input.companyNames) ? input.companyNames : [])
+    .map((name) => String(name).trim()).filter(Boolean))];
+  if (companyNames.length === 0) throw new QccBridgeError('QCC_RETRY_EMPTY', 'At least one failed company must be selected');
+  return { kind, taskId, runId, companyNames };
+}
+
+export function serializeQccCommandPrompt(command) {
+  const visible = {
+    schemaVersion: 1,
+    commandId: command.commandId,
+    taskId: command.taskId,
+    kind: command.kind,
+  };
+  return [
+    '请执行数据清洗补全企查查任务。',
+    '',
+    '类型化任务意图（schemaVersion 1）：',
+    '```json',
+    JSON.stringify(visible, null, 2),
+    '```',
+    '',
+    `请准确调用一次 ${TOOL_QCC_COMMAND} 并只传递 commandId。`,
+    '企业名单和字段选择已安全暂存在本机 Host，不得要求用户在对话中重复粘贴，不得直接调用任何 mcp__qcc-* 工具。',
+    '高层工具返回后立即结束本轮；不得重试、扩大名单或追加字段。',
+  ].join('\n');
+}
+
+export class QccCommandStore {
+  constructor({ bridge, runs, clock = () => Date.now(), ttlMs = DEFAULT_TTL_MS, maxCommands = DEFAULT_MAX_COMMANDS } = {}) {
+    if (!bridge || !runs) throw new TypeError('QccCommandStore requires bridge and runs');
+    this.bridge = bridge;
+    this.runs = runs;
+    this.clock = clock;
+    this.ttlMs = ttlMs;
+    this.maxCommands = maxCommands;
+    this.commands = new Map();
+  }
+
+  cleanup(reserveSlot = false) {
+    const cutoff = this.clock() - this.ttlMs;
+    for (const [id, command] of this.commands) {
+      if (command.state !== 'running' && command.touchedAtMs < cutoff) this.commands.delete(id);
+    }
+    const limit = reserveSlot ? this.maxCommands - 1 : this.maxCommands;
+    while (this.commands.size > limit) {
+      const removable = [...this.commands].find(([, command]) => command.state !== 'running');
+      if (!removable) throw new QccBridgeError('QCC_COMMAND_CAPACITY', 'QCC command queue is full', { retryable: true });
+      this.commands.delete(removable[0]);
+    }
+  }
+
+  prepare(input) {
+    this.cleanup(true);
+    const normalized = normalizedInput(input);
+    const commandId = `dcq-${randomUUID()}`;
+    const at = new Date(this.clock()).toISOString();
+    const record = {
+      commandId,
+      taskId: normalized.taskId,
+      kind: normalized.kind,
+      state: 'prepared',
+      createdAt: at,
+      updatedAt: at,
+      touchedAtMs: this.clock(),
+      input: normalized,
+      runId: null,
+      error: null,
+      promise: null,
+    };
+    this.commands.set(commandId, record);
+    return { ...this.publicRecord(record), prompt: serializeQccCommandPrompt(record) };
+  }
+
+  require(commandId) {
+    this.cleanup();
+    const record = this.commands.get(String(commandId ?? ''));
+    if (!record) throw new QccBridgeError('QCC_COMMAND_NOT_FOUND', 'QCC command was not found or expired');
+    record.touchedAtMs = this.clock();
+    return record;
+  }
+
+  publicRecord(record) {
+    return clone({
+      commandId: record.commandId,
+      taskId: record.taskId,
+      kind: record.kind,
+      state: record.state,
+      createdAt: record.createdAt,
+      updatedAt: record.updatedAt,
+      runId: record.runId,
+      error: record.error,
+      expiresInMs: this.ttlMs,
+    });
+  }
+
+  status(commandId) {
+    const record = this.require(commandId);
+    const output = this.publicRecord(record);
+    if (record.runId) output.run = this.runs.get(record.runId);
+    return output;
+  }
+
+  async run(commandId, execution) {
+    const record = this.require(commandId);
+    if (!execution?.agent || !execution?.token) {
+      throw new QccBridgeError('QCC_AGENT_EXECUTION_REQUIRED', 'QCC commands require an Agent-owned DSH tool execution');
+    }
+    if (record.promise) return record.promise;
+    record.state = 'running';
+    record.updatedAt = new Date(this.clock()).toISOString();
+    record.promise = this.execute(record, execution)
+      .then((run) => {
+        record.runId = run.runId;
+        record.state = 'completed';
+        record.updatedAt = new Date(this.clock()).toISOString();
+        record.touchedAtMs = this.clock();
+        return this.toolResult(record, run);
+      })
+      .catch((error) => {
+        record.error = safeError(error);
+        record.state = 'failed';
+        record.updatedAt = new Date(this.clock()).toISOString();
+        record.touchedAtMs = this.clock();
+        throw error;
+      });
+    return record.promise;
+  }
+
+  async execute(record, execution) {
+    const options = { execution };
+    if (record.kind === 'resolve') {
+      return this.runs.resolveCandidate(record.input.runId, record.input, this.bridge, options);
+    }
+    if (record.kind === 'retry') {
+      return this.runs.retryCompanies(record.input.runId, record.input.companyNames, this.bridge, options);
+    }
+    const audit = [];
+    const result = await this.bridge.enrichRows(record.input.rows, {
+      nameField: record.input.nameField,
+      includeRisk: record.input.includeRisk,
+      concurrency: record.input.concurrency,
+      maxRows: 100,
+      execution,
+      onAudit: (event) => audit.push(event),
+    });
+    return this.runs.createRun({
+      headers: record.input.headers,
+      nameField: record.input.nameField,
+      includeRisk: record.input.includeRisk,
+      concurrency: record.input.concurrency,
+      result,
+      audit,
+    });
+  }
+
+  toolResult(record, run) {
+    return clone({
+      commandId: record.commandId,
+      taskId: record.taskId,
+      runId: run.runId,
+      state: run.state,
+      summary: run.summary,
+    });
+  }
+}
+
+export function registerQccCommandTool(tools, commands) {
+  return tools.register({
+    name: TOOL_QCC_COMMAND,
+    description: 'Execute one already-staged data-cleaning QCC command. Call only when a visible typed intent supplies commandId. The Host owns rows, billing confirmation, idempotency and result artifacts.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: { commandId: { type: 'string' } },
+      required: ['commandId'],
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          commandId: { type: 'string' },
+          taskId: { type: 'string' },
+          runId: { type: 'string' },
+          state: { type: 'string' },
+          summary: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              totalRows: { type: 'integer' },
+              uniqueCompanies: { type: 'integer' },
+              enriched: { type: 'integer' },
+              ambiguous: { type: 'integer' },
+              unresolved: { type: 'integer' },
+              failed: { type: 'integer' },
+              missingName: { type: 'integer' },
+              includeRisk: { type: 'boolean' },
+            },
+            required: ['totalRows', 'uniqueCompanies', 'enriched', 'ambiguous', 'unresolved', 'failed', 'missingName', 'includeRisk'],
+          },
+        },
+        required: ['commandId', 'taskId', 'runId', 'state', 'summary'],
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: `数据清洗补全企查查任务已完成：${value.summary?.enriched ?? 0}/${value.summary?.totalRows ?? 0} 条已补全，状态 ${value.state}。`,
+      }],
+    },
+    async execute(args, exec) {
+      return commands.run(args.commandId, exec);
+    },
+  });
+}

package/lib/qcc.js

@@ -145,13 +145,31 @@ export class QccBridgeError extends Error {
   }
 }
 
+function messageFailureCode(message) {
+  const text = String(message ?? '').trim();
+  if (!text) return '';
+  const cases = [
+    [/only\s+[`'\"]?run_code|requires task-based execution|direct(?:ly)?[^.]{0,48}(?:not allowed|not callable|denied)/i, 'DSH_EXECUTION_DENIED'],
+    [/(?:^|\D)401(?:\D|$)|unauthori[sz]ed|auth(?:entication|orization)? required|invalid token|token expired/i, '401'],
+    [/(?:^|\D)403(?:\D|$)|forbidden|permission denied|resource not authorized/i, '403'],
+    [/(?:^|\D)429(?:\D|$)|rate[ -]?limit|too many requests/i, '429'],
+    [/quota[^.]{0,32}(?:exhausted|insufficient|limit)|insufficient quota/i, 'QUOTA_EXHAUSTED'],
+    [/unknown tool|tool unavailable|method not found|mcp error\s*-32601/i, 'UNKNOWN_TOOL'],
+    [/timed?\s*out|deadline exceeded/i, 'TIMEOUT'],
+    [/mcp error\s*-32602|invalid (?:argument|parameter)|validation error|bad request/i, 'INVALID_ARGUMENT'],
+    [/(?:^|\D)5\d\d(?:\D|$)|service unavailable|upstream unavailable|connection (?:error|failed)/i, 'UPSTREAM_UNAVAILABLE'],
+  ];
+  return cases.find(([pattern]) => pattern.test(text))?.[1] ?? 'UNCLASSIFIED_TOOL_ERROR';
+}
+
 function upstreamFailureCode(result) {
-  return String(
+  const structured = String(
     result?.error?.info?.code
       ?? result?.error?.info?.status
       ?? result?.error?.info?.httpStatus
       ?? '',
   ).trim().toUpperCase();
+  return structured || messageFailureCode(result?.error?.message);
 }
 
 function failureDetails(result) {
@@ -218,6 +236,13 @@ function normalizedFailure(result, toolName, state) {
       connectRequired: true,
     });
   }
+  if (upstreamCode === 'DSH_EXECUTION_DENIED') {
+    return new QccBridgeError('QCC_EXECUTION_DENIED', 'DSH denied this programmatic QCC tool execution', {
+      toolName,
+      upstreamCode,
+      retryable: false,
+    });
+  }
   if (/^(?:5\d\d|SERVICE_UNAVAILABLE|UPSTREAM_UNAVAILABLE|CONNECTION_ERROR)$/.test(upstreamCode)) {
     return new QccBridgeError('QCC_UPSTREAM_UNAVAILABLE', 'QCC upstream service is temporarily unavailable', {
       toolName,
@@ -507,11 +532,24 @@ export class QccHostBridge {
           attemptAudited = true;
           throw error;
         }
+        const execution = options.execution;
+        if (execution && (!execution.agent || !execution.token)) {
+          throw new QccBridgeError(
+            'QCC_AGENT_EXECUTION_REQUIRED',
+            'Nested QCC calls require an Agent-owned DSH tool execution',
+            { toolName: activeToolName },
+          );
+        }
         const result = await this.tools.execute({
           name: activeToolName,
           callId,
           signal: state.signal,
           arguments: args,
+          ...(execution ? {
+            rootCallId: execution.rootCallId,
+            parent: execution.token,
+            agent: execution.agent,
+          } : {}),
         });
         if (result?.isError !== true) {
           emitAudit(options, {

package/lib/skill-enrich.js

@@ -6,9 +6,10 @@
  *   - `enterprise-enrichment`：用企查查 MCP 工具按最新工商信息补全企业名单
  *     （依赖 `qcc-dsh-mcp-oauth` 已连接；本 Skill 不重造 OAuth）。
  *
- * 方案 A（模型中介式）：模型亲自调用 `mcp__qcc-company__*` / `mcp__qcc-risk__*`
+ * 方案 A（自由对话）：模型亲自调用 `mcp__qcc-company__*` / `mcp__qcc-risk__*`
  * / `mcp__qcc-ipr__*` / `mcp__qcc-operation__*` 完成消歧 → 工商详情 → 各域维度，
- * 再组装结果。本插件零后端改动（Host Bridge 批量是独立于本 Skill 的方案 B）。
+ * 再组装结果。工作台批量路径则只调用 Agent-owned 高层工具，避免 Code Mode
+ * 拒绝 Web Host 的无父执行调用。
  */
 import {
   QCC_PHASE2_COMPANY_TOOLS,
@@ -53,6 +54,10 @@ export function registerEnrichSkill(skills) {
     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.',
       '',
+      'Typed workbench command (highest priority):',
+      '- If the visible user message contains a typed data-cleaning intent with `commandId` and explicitly requests `data_cleaning_qcc_run`, call that high-level tool exactly once with only `commandId`, then stop.',
+      '- The Host already holds the rows, billing confirmation and field selection. Do not ask the user to paste rows, do not call any `mcp__qcc-*` tool directly, do not retry, and do not expand the batch.',
+      '',
       '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.',

package/lib/tools.js

@@ -100,7 +100,7 @@ export function registerTools(tools) {
       const r = completeRows(Array.isArray(args.rows) ? args.rows : []);
       return {
         total: r.total,
-        completed: r.completed,
+        completed: r.completedCount,
         incompleteCount: r.incompleteCount,
         name: r.fillStats.name,
         amount: r.fillStats.amount,