# 海关问数 Agent(CustomesDataAgent) 海关电子元器件进出口数据的**问数平台**:把海关原始 CSV 处理成 16 张统计报表,再用一个"只用工具里的数字说话"的 Agent 回答业务问题。 - 数据真实性由**确定性核验层**把关:答案里每个数字都要在观测台账里查到来源,查不到就拒绝交付(不是靠提示词请求模型"不要编")。 - 数据处理是**可整体替换的独立模块**(`tools-service/toolsvc/customs/`),前端调用与 Agent 调用走同一份契约。 - **一键启动**:双击 `启动.bat`(或 `node scripts/start.mjs`),自动检查环境、装依赖、拉起两个服务、打开浏览器。 --- ## 1. 30 秒上手 ```text ① 安装 Node.js 22+ 和 Python 3.11+ ② 把 .env.example 复制成 .env,填入 DEEPSEEK_API_KEY ③ 双击 启动.bat → 浏览器打开 http://127.0.0.1:8787 ``` 第一次用:`文件` 页上传 `samples/small.csv` → `数据处理` 页点"开始处理" → `对话问数` 页问"2025 年 1 月 MLCC 进口额是多少?" 详细的零基础步骤见 [docs/03-使用手册.md](docs/03-使用手册.md)。 --- ## 界面 | 对话问数(数字带溯源 chip + 核验结论) | 点开 chip:对象 / 表 / 行号 / 行哈希 + 这一行原文 | |---|---| | ![对话](docs/images/01-chat.png) | ![溯源抽屉](docs/images/05-trace-drawer.png) | | 点"在结果表中查看":跳到"文件"页并高亮那一行 | 数据处理(25 张结果表 + 预览/图表) | |---|---| | ![跳转高亮](docs/images/06-row-jump.png) | ![数据处理](docs/images/02-process.png) | | 文件(原始数据 / 统计结果,含 SHA256 指纹) | 系统(Harness、工具、两本台账) | |---|---| | ![文件](docs/images/03-files.png) | ![系统](docs/images/04-system.png) | ## 2. 整体架构 ```text ┌─────────────────────────────────────────────────────────────────────┐ │ 前端 React + Vite + TypeScript (web/,构建产物由 BFF 托管) │ │ 工作区 │ 文件上传 │ 数据处理 │ 对话(SSE 流式 + 溯源 chip) │ └───────────────────────────────┬─────────────────────────────────────┘ │ HTTP / SSE ┌───────────────────────────────▼─────────────────────────────────────┐ │ BFF Node 24 + TypeScript,零运行时依赖 (bff/) │ │ · Harness 运行时(Agent Loop / 工具注册 / finalizeContent / Preset)│ │ · 会话与消息持久化(node:sqlite) │ │ · 会话级观测台账 │ │ · ★ 输出核验层(纯代码,模型不可见、不可调用) │ └──────┬──────────────────────────────────────────┬───────────────────┘ │ HTTP │(同一批返回值) ┌──────▼──────────────────────────────────┐ ┌────▼───────────────────┐ │ 工具执行服务 Python + FastAPI(tools-service/) │ │ customs_process │ data_read │ calculator │ list_objects │ │ 对象库 · 行级血缘 · 数据面台账(哈希链 + JSONL) │ │ ★ customs/ 可整体替换的数据处理模块 │ └─────────────────────────────────────────┴────────────────────────────┘ ``` **关键判断**:把 Harness 定位为推理编排层,把数据真实性的最终裁决权放在 Harness 之外。 `finalizeContent` 只负责把溯源令牌注入工具输出;答案里的数字能否交付,由核验层用台账反查后裁决。 --- ## 3. 目录结构 ```text CustomesDataAgent/ ├─ agent.cordis.yml # Agent Preset:模型、系统提示、启用的工具、核验策略 ├─ 启动.bat / 停止.bat # Windows 一键启停 ├─ .env.example # 环境变量模板(复制成 .env) ├─ bff/ # Node + TypeScript BFF(运行时零依赖) │ ├─ src/harness/ # Harness 运行时、工具注册、模型提供方、Preset │ ├─ src/verify/ # 输出核验层:数字抽取 + 台账反查 + 裁决 │ ├─ src/routes/ # 工作区/文件/处理/会话/对话(SSE)/系统 │ ├─ src/store/ # sqlite:会话、消息、会话台账 │ └─ test/ # 69 项单元与接口测试 ├─ tools-service/ # Python 工具执行服务 │ ├─ toolsvc/customs/ # ★ 可替换的数据处理模块(契约 + engine + rules/) │ ├─ toolsvc/objects.py # 对象库、原始数据索引、行级血缘 │ ├─ toolsvc/ledger.py # 数据面台账 │ ├─ toolsvc/calc.py # calculator(带输入溯源) │ ├─ toolsvc/readers.py # data_read(SQL 过滤/排序/聚合) │ ├─ toolsvc/api.py # HTTP 接口 │ └─ tests/ # 274 项单元与接口测试 ├─ web/ # React 前端(29 项单测:格式化 + 组件渲染) ├─ scripts/ # start/stop/e2e/run_tests/样本数据生成 ├─ deploy/ # Dockerfile + docker-compose(单镜像一键部署) ├─ samples/ # 可复现的测试数据集 + 预言机(expected.json) └─ docs/ # 架构 / 实现 / 使用手册 / 替换指南 / 测试报告 ``` --- ## 4. 三个(+1 个辅助)工具 | 工具 | 职责 | 关键约束 | |---|---|---| | `customs_process` | 海关原始数据 → 统计结果(16 张模板表 + 7 张补充表 + 2 张查询汇总表) | 只写新对象,不覆盖原始数据;长任务阻塞执行 | | `data_read` | 读取对象中一张表的子集(过滤/排序/分页/聚合) | 绝不返回整表;每行带 `_trace` 行级哈希 | | `calculator` | 算术与统计:sum/mean/growth/ratio/index/share/expression | 唯一能产生新数字的入口,输入必须带 `call_id` + `row_hash` | | `list_objects` | 列出工作区对象与表结构(辅助,不返回业务数字) | 只读,供 Agent 定位 `object_id` | 没有任何 `bash`/`write`/`edit` 之类的能力:模型无法自己读文件、也无法绕过工具算数。 --- ## 5. 测试 | 测试组 | 数量 | 命令 | |---|---|---| | Python 引擎与接口(pytest) | 274 | `cd tools-service && python -m pytest tests/` | | BFF 单元与接口(node:test) | 69 | `cd bff && npm run build && node --test "dist/test/*.test.js"` | | 前端单元 + 渲染(vitest) | 29 | `cd web && npx vitest run` | | 端到端联调(真实服务 + 真实模型) | 33 项检查 | `node scripts/e2e.mjs` | | 真实浏览器交互(CDP 点击 + 截图) | 3 步断言 + 6 张截图 | `node scripts/ui_probe.mjs` | 一条命令全跑: ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File scripts\run_tests.ps1 ``` 另有**真实浏览器交互探针** `node scripts/ui_probe.mjs`(用 CDP 点开 chip、跳转高亮、逐页截图),产物在 `.run/ui/`; 以及**核验取证工具** `node scripts/verify_probe.mjs <答案文件>`(打印每个候选数字的类别与判定,改规则前先看它)。 结果见 [docs/05-测试报告.md](docs/05-测试报告.md)。 --- ## 6. 文档 | 文档 | 内容 | |---|---| | [docs/01-架构设计.md](docs/01-架构设计.md) | 分层、数据流、核验机制、DSH 对接方式、扩展点、已知取舍 | | [docs/02-实现说明.md](docs/02-实现说明.md) | **所有实现细节**:模块、数据模型、HTTP 接口、指标口径、配置项、性能 | | [docs/03-使用手册.md](docs/03-使用手册.md) | 零基础部署与使用(含排错表) | | [docs/04-工具模块替换指南.md](docs/04-工具模块替换指南.md) | 如何整体替换数据处理工具 / 新增 Agent 工具 | | [docs/05-测试报告.md](docs/05-测试报告.md) | 测试范围、用例、结果、复现方式 | --- ## 7. 版本说明 * 本版本模型使用 DeepSeek 官方 API(`deepseek-flash`)。 * 下一版切换到本地部署模型:把 `agent.cordis.yml` 的 `model.provider` 改成 `local`,在 `.env` 里配置 `CDA_LOCAL_BASE_URL`(llama.cpp / vLLM / Ollama 的 `/v1` 端点)即可,代码零改动。 * Harness 默认使用内嵌实现(与 DeepSeek Harness 同语义、零外部进程、离线可用); 装好 DSH CLI 后可设 `CDA_HARNESS=dsh` 转交给官方运行时,见 `bff/src/harness/dshAdapter.ts`。 ## 大数据查询补充(2026-11-18) 在原23张Excel报表之外增加2张SQLite查询汇总表,补充业务表目录、定向联合索引、Decimal精确筛选与排序、受限聚合、按需计数、行号游标、查询时限、版本缓存和分批血缘。业务分类与统计公式保持不变。 设计、口径差异、四百万行查询样本与十万唯一申报完整流程的实测范围,以及未验证项,见 [大数据查询设计与实测](docs/07-大数据查询设计与实测.md);机器可读目录见 [统计表业务目录](docs/08-统计表业务目录.json)。这些结果不能外推真实四百万行完整流水线性能。 最新扩展回归与界面验证见 [docs/09-扩展测试与界面回归.md](docs/09-扩展测试与界面回归.md)。