|
|
il y a 2 jours | |
|---|---|---|
| bff | il y a 2 jours | |
| deploy | il y a 4 jours | |
| docs | il y a 2 jours | |
| offline | il y a 4 jours | |
| samples | il y a 3 jours | |
| scripts | il y a 3 jours | |
| tools-service | il y a 2 jours | |
| web | il y a 2 jours | |
| .env.example | il y a 3 jours | |
| .gitattributes | il y a 4 jours | |
| .gitignore | il y a 4 jours | |
| README.md | il y a 2 jours | |
| agent.cordis.yml | il y a 3 jours | |
| package.json | il y a 4 jours | |
| 停止.bat | il y a 4 jours | |
| 启动.bat | il y a 4 jours |
# 海关问数 Agent(CustomesDataAgent)
海关电子元器件进出口数据的问数平台:把海关原始 CSV 处理成 16 张统计报表,再用一个"只用工具里的数字说话"的 Agent 回答业务问题。
tools-service/toolsvc/customs/),前端调用与 Agent 调用走同一份契约。启动.bat(或 node scripts/start.mjs),自动检查环境、装依赖、拉起两个服务、打开浏览器。① 安装 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。
| 对话问数(数字带溯源 chip + 核验结论) | 点开 chip:对象 / 表 / 行号 / 行哈希 + 这一行原文 |
|---|---|
![]() |
![]() |
| 点"在结果表中查看":跳到"文件"页并高亮那一行 | 数据处理(25 张结果表 + 预览/图表) |
|---|---|
![]() |
![]() |
| 文件(原始数据 / 统计结果,含 SHA256 指纹) | 系统(Harness、工具、两本台账) |
|---|---|
![]() |
![]() |
┌─────────────────────────────────────────────────────────────────────┐
│ 前端 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 只负责把溯源令牌注入工具输出;答案里的数字能否交付,由核验层用台账反查后裁决。
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/ # 架构 / 实现 / 使用手册 / 替换指南 / 测试报告
| 工具 | 职责 | 关键约束 |
|---|---|---|
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 之类的能力:模型无法自己读文件、也无法绕过工具算数。
| 测试组 | 数量 | 命令 |
|---|---|---|
| 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 -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/01-架构设计.md | 分层、数据流、核验机制、DSH 对接方式、扩展点、已知取舍 |
| docs/02-实现说明.md | 所有实现细节:模块、数据模型、HTTP 接口、指标口径、配置项、性能 |
| docs/03-使用手册.md | 零基础部署与使用(含排错表) |
| docs/04-工具模块替换指南.md | 如何整体替换数据处理工具 / 新增 Agent 工具 |
| docs/05-测试报告.md | 测试范围、用例、结果、复现方式 |
deepseek-flash)。agent.cordis.yml 的 model.provider 改成 local,在 .env 里配置
CDA_LOCAL_BASE_URL(llama.cpp / vLLM / Ollama 的 /v1 端点)即可,代码零改动。CDA_HARNESS=dsh 转交给官方运行时,见 bff/src/harness/dshAdapter.ts。在原23张Excel报表之外增加2张SQLite查询汇总表,补充业务表目录、定向联合索引、Decimal精确筛选与排序、受限聚合、按需计数、行号游标、查询时限、版本缓存和分批血缘。业务分类与统计公式保持不变。
设计、口径差异、四百万行查询样本与十万唯一申报完整流程的实测范围,以及未验证项,见 大数据查询设计与实测;机器可读目录见 统计表业务目录。这些结果不能外推真实四百万行完整流水线性能。
最新扩展回归与界面验证见 docs/09-扩展测试与界面回归.md。