Нет описания

ly 411858e845 feat: 完善海关格式解析、精确聚合与遮掩数据演示 3 дней назад
bff 411858e845 feat: 完善海关格式解析、精确聚合与遮掩数据演示 3 дней назад
deploy 1a9b2df88c feat: 海关问数 Agent 平台 1.0(DSH 架构 + 数据真实性核验 + 可替换数据处理工具) 4 дней назад
docs 411858e845 feat: 完善海关格式解析、精确聚合与遮掩数据演示 3 дней назад
offline 1a9b2df88c feat: 海关问数 Agent 平台 1.0(DSH 架构 + 数据真实性核验 + 可替换数据处理工具) 4 дней назад
samples 1a9b2df88c feat: 海关问数 Agent 平台 1.0(DSH 架构 + 数据真实性核验 + 可替换数据处理工具) 4 дней назад
scripts 411858e845 feat: 完善海关格式解析、精确聚合与遮掩数据演示 3 дней назад
tools-service 411858e845 feat: 完善海关格式解析、精确聚合与遮掩数据演示 3 дней назад
web 411858e845 feat: 完善海关格式解析、精确聚合与遮掩数据演示 3 дней назад
.env.example 1a9b2df88c feat: 海关问数 Agent 平台 1.0(DSH 架构 + 数据真实性核验 + 可替换数据处理工具) 4 дней назад
.gitattributes 1a9b2df88c feat: 海关问数 Agent 平台 1.0(DSH 架构 + 数据真实性核验 + 可替换数据处理工具) 4 дней назад
.gitignore 1a9b2df88c feat: 海关问数 Agent 平台 1.0(DSH 架构 + 数据真实性核验 + 可替换数据处理工具) 4 дней назад
README.md f5ed8dd507 feat: 补齐架构文档要求的交互与接口(溯源抽屉、跳转高亮、进度 SSE、按行取数) 4 дней назад
agent.cordis.yml 411858e845 feat: 完善海关格式解析、精确聚合与遮掩数据演示 3 дней назад
package.json f5ed8dd507 feat: 补齐架构文档要求的交互与接口(溯源抽屉、跳转高亮、进度 SSE、按行取数) 4 дней назад
停止.bat 1a9b2df88c feat: 海关问数 Agent 平台 1.0(DSH 架构 + 数据真实性核验 + 可替换数据处理工具) 4 дней назад
启动.bat 1a9b2df88c feat: 海关问数 Agent 平台 1.0(DSH 架构 + 数据真实性核验 + 可替换数据处理工具) 4 дней назад

README.md

# 海关问数 Agent(CustomesDataAgent)

海关电子元器件进出口数据的问数平台:把海关原始 CSV 处理成 16 张统计报表,再用一个"只用工具里的数字说话"的 Agent 回答业务问题。

  • 数据真实性由确定性核验层把关:答案里每个数字都要在观测台账里查到来源,查不到就拒绝交付(不是靠提示词请求模型"不要编")。
  • 数据处理是可整体替换的独立模块(tools-service/toolsvc/customs/),前端调用与 Agent 调用走同一份契约。
  • 一键启动:双击 启动.bat(或 node scripts/start.mjs),自动检查环境、装依赖、拉起两个服务、打开浏览器。

1. 30 秒上手

① 安装 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:对象 / 表 / 行号 / 行哈希 + 这一行原文
对话 溯源抽屉
点"在结果表中查看":跳到"文件"页并高亮那一行 数据处理(23 张结果表 + 预览/图表)
跳转高亮 数据处理
文件(原始数据 / 统计结果,含 SHA256 指纹) 系统(Harness、工具、两本台账)
文件 系统

2. 整体架构

┌─────────────────────────────────────────────────────────────────────┐
│ 前端  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. 目录结构

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/                    #   58 项单元与接口测试
├─ 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/                   #   85 项单元与接口测试
├─ web/                        # React 前端(27 项单测:格式化 + 组件渲染)
├─ scripts/                    # start/stop/e2e/run_tests/样本数据生成
├─ deploy/                     # Dockerfile + docker-compose(单镜像一键部署)
├─ samples/                    # 可复现的测试数据集 + 预言机(expected.json)
└─ docs/                       # 架构 / 实现 / 使用手册 / 替换指南 / 测试报告

4. 三个(+1 个辅助)工具

工具 职责 关键约束
customs_process 海关原始数据 → 统计结果(16 张模板表 + 7 张补充表) 只写新对象,不覆盖原始数据;长任务阻塞执行
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) 85 cd tools-service && python -m pytest tests/
BFF 单元与接口(node:test) 58 cd bff && npm run build && node --test "dist/test/*.test.js"
前端单元 + 渲染(vitest) 27 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/。

结果见 docs/05-测试报告.md。


6. 文档

文档 内容
docs/01-架构设计.md 分层、数据流、核验机制、DSH 对接方式、扩展点、已知取舍
docs/02-实现说明.md 所有实现细节:模块、数据模型、HTTP 接口、指标口径、配置项、性能
docs/03-使用手册.md 零基础部署与使用(含排错表)
docs/04-工具模块替换指南.md 如何整体替换数据处理工具 / 新增 Agent 工具
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。