# dateagent **Repository Path**: xxwdoo/dateagent ## Basic Information - **Project Name**: dateagent - **Description**: 生态环境监测数据、报告、知识库 agent(自 GitHub xxwdoo/dateagent 迁移) - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-04 - **Last Updated**: 2026-11-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # pi-dateagent · 生态环境监测数据工作助手 把监测实验室的**原始数据**自动算成**规范的报告**(Word 报告 + 结果报告单 + 结果表)。 它做三件事:**干活**(算指标 / 出报告 / 引标准)、**记事**(每个工作空间一份长期记忆)、 **固化流程**(反复跑的流程沉淀成工作流)。带一个与 pi-web 同款形式的工作台。 ``` 原始数据(xlsx/xls) ──► 工作流引擎(datasets → compute → outputs)──► 报告(docx) + 结果表(xlsx) ▲ │ │ 试跑 / 诊断 / 落盘 │ 引用 pi Agent(工作流工程师)◄──────► 标准知识库(RAG) ▲ │ Web 工作台:工作空间(数据 · 会话 · 记忆)| 工作流库 · 知识库 · 设置 ``` ## 一、总体架构 | 层 | 位置 | 技术 | 职责 | | --- | --- | --- | --- | | 计算引擎 | `engine/` | Python 3.12 + FastAPI | Excel 解析、工作流执行、模板填充、docx/xlsx 渲染、标准检索 | | 智能体 | `server/` | Next.js 16 + React 19 + TS 5 | 会话编排、工具调用(工作流开发)、SSE 流式转发 | | 工作台 | `server/app/` `server/components/` | Tailwind v4(复用 pi-web 设计令牌) | 工作空间 / 会话 / 工作流库 / 知识库 / 设置 | | 数据 | `data/` | — | 默认工作空间:`raw/` `output/` `standards/` `AGENTS.md` | | 工作流库 | `workflows/` | — | 全局共用:`specs/`(YAML 工作流)`templates/`(报告模板) | **四条设计原则** 1. **工作空间 = 一个目录**(与 pi-web 一致):`raw/ output/ AGENTS.md`;工作流与模板不属于工作空间,统一在全局工作流库 `workflows/`, 默认工作空间就是仓库的 `data/`,不再有两套目录布局。 2. **工作流是数据,不是代码**:反复跑的流程沉淀成 YAML;只跑一次的探索不必写工作流。 3. **计算与渲染全部确定性**:报告数字只来自引擎返回,LLM 只编排与叙述。 4. **配置与 pi 隔离**:设置 / 供应商 / 凭据 / 技能全部落在 `.pi-dateagent/`,不碰 `~/.pi/agent`。 界面与工作空间的详细设计见 [`docs/界面与工作空间.md`](docs/界面与工作空间.md)。 内网单机部署本地大模型(llama.cpp / vLLM)与「本地精简」运行档位见 [`docs/本地模型部署.md`](docs/本地模型部署.md)。 Word 表格与图片数据(识别 + 人工核查)见 [`docs/Word与图片数据.md`](docs/Word与图片数据.md)。 ## 二、快速开始 ```bash # 1) 安装依赖 cd engine && pip install -r requirements.txt && cd .. npm install # 根目录:并发启动脚本 cd server && npm install && cd .. # 2) 准备标准知识库(RAG,一次性) cd engine python -m engine.rag.fetch_model # 拉取 BGE 中文向量模型(约 95 MB) python -m engine.rag.ingest # 切分标准 PDF 并建立向量索引 cd .. # 3) 一键启动(引擎 8710 + 网页 3000) npm run dev ``` 然后打开 ,直接说: > 请按现成的报告规格 pm25_manual_auto_compare 生成本次细颗粒物比对报告,并汇总结果给出结论。 ### 其它命令 ```bash npm run engine:test # 引擎回归测试(pytest:参考实现 + 规格引擎 + 取整口径) npm run spec:check # 校验规格 + 真实数据试跑 npm run spec:build # 不走 LLM,直接按规格出报告 npm run rag:ingest # 重建标准向量索引 npm run rag:list # 查看知识库收录情况 npm run e2e:agent -- "请按现成的报告规格 pm25_manual_auto_compare 生成比对报告。" # 端到端验收(需先启动服务) npm run dev:engine # 只启动引擎 npm run dev:web # 只启动网页 ``` ### 界面一览 | 页面 | 作用 | | --- | --- | | 💬 对话 | 与「工作流工程师」对话;工具过程可展开;回答下方给出知识库引用(可点开条款/原文) | | 🧩 工作流 | 独立的全局工作流库:卡片列出全部工作流;点进去试跑 / 出报告(选择用哪个工作空间的数据)、编辑 YAML、让智能体改、删除 | | 📚 知识库 | 已收录标准清单 + 语义检索 + 条款原文 + 未收录清单 | | 🧠 记忆 | 本工作空间的长期记忆(`AGENTS.md`),agent 自动维护,人也能改 | | ⚙️ 设置 | 默认模型、**模型供应商增删**、**技能**、推理强度、运行环境(配置与 pi 完全隔离) | 侧栏顶部是**工作空间(目录)选择器**:最近使用 + 路径输入 + 目录浏览,与 pi-web 的 cwd 选择器同形式。 一个工作空间有自己独立的原始数据、输出、长期记忆和多个会话;工作流库是全局的,所有工作空间共用(`PI_DATEAGENT_WORKFLOW_DIR` 可改位置)。旧版放在各工作空间 `specs/` `templates/` 里的文件会在首次启动时自动合并进工作流库(同名不覆盖,原文件保留)。 ### 命令速查 | 命令 | 说明 | | --- | --- | | `npm run dev` | 同时启动引擎(8710)与网页(3000) | | `npm run engine:test` | 引擎回归测试(与参考报告逐项比对) | | `npm run spec:check` / `spec:build` | 校验工作流 / 按工作流出报告(不走 LLM) | | `npm run rag:ingest` / `rag:list` | 重建标准索引 / 查看收录情况 | | `npm run e2e:agent -- "…"` | 端到端验收(对话) | | `npm run e2e:workspace` | 端到端验收(工作空间/工作流/记忆/设置隔离) | | `npm run e2e:memory` | 验证记忆注入 + 记忆按工作空间隔离 + 技能进提示词 | ## 三、智能体工具(仅业务工具,不暴露 bash / 文件读写) 工具全部**绑定当前工作空间**(目录在工具工厂里闭合,模型改不了),共 12 个: | 工具 | 作用 | | --- | --- | | `list_raw_files` | 列出本工作空间的原始数据文件 | | `preview_dataset` | 看真实表头与取值格式(仅 `.xls/.xlsx/.csv`) | | `list_workflows` | 列出已有工作流(id / 状态 / 数据集 / 输出) | | `get_workflow` | 读取工作流 YAML 原文(改之前必须先抄原文) | | `get_workflow_guide` | 工作流写法说明 + 全部可用函数 | | `check_workflow` | 用真实数据试跑(不写文件)→ 数据集诊断 + 全部计算结果 | | `save_workflow` | 保存工作流(结构校验) | | `run_workflow` | 按工作流计算并渲染输出文件 | | `search_standards` | 标准知识库语义检索,结果同时作为界面引用 | | `memory_read` | 读取本工作空间长期记忆 | | `memory_update` | 往记忆小节追加结论(数据字典 / 业务口径 / 历史决策 / 待确认问题) | | `read_skill` | 读取某个技能的完整说明 | 按 pi 二次开发规范,已替换系统提示词(`server/lib/system-prompt.ts`)、 收窄工具白名单(`server/lib/tools.ts`),并使用 `SessionManager.create(cwd, sessionDir)` **按工作空间落盘持久化**(不用 `inMemory`,刷新不丢), 避免多用户场景下默认 `bash`/`read`/`write` 带来的越权风险。 ## 四、计算规则(已与参考报告逐项核对一致) > 这些规则已经从代码里搬到声明式规格 `workflows/specs/pm25_manual_auto_compare.yaml`, > 改算法 = 改规格,不用改 Python。规格写法见 [`docs/通用工作流.md`](docs/通用工作流.md)。 设称重表得到「平均值(初重)」「平均值(终重)」,采样体积表得到「工况体积」: | 量 | 公式 | 处理 | | --- | --- | --- | | 净重 | `平均值(终重) − 平均值(初重)` | mg,保留原始精度 | | 采样体积 | `工况体积(m³) × 1000` | L | | 手工浓度 | `净重(mg) × 1e6 ÷ 体积(L)` | 四舍五入取整,µg/m³ | | 自动结果 | 采样时段内自动小时值的日均 | 带质量标记(如 `42(PF)`)的值剔除;取整 | | 相对误差 | `(自动 − 手工) ÷ 手工 × 100` | 保留 1 位小数,% | | 平均值行 | 分别对自动、手工取均值后取整,**再用两个均值重算相对误差** | 不是把各日误差再平均 | | 合格判定 | `|相对误差| ≤ 15%` | 质量目标 ±15% | | 线性回归 | 手工为 x、自动为 y | 给出 `y = ax + b`、`R²` | 两个易踩的坑: 1. **取整方式**:必须用 `ROUND_HALF_UP`(四舍五入)。Python 内置 `round()` 是银行家舍入, 会把 `0.5` 舍到偶数,与本报告口径不符 —— 引擎统一用 `engine/numeric.py: round_half_up()`, 规格表达式里的 `round()` / `rnd()` 也已改为四舍五入(见 `engine/tests/test_expr.py`)。 2. **自动日均剔除无效值**:自动数据带 `(PF)` 等质量标记的小时值不参与日均, 分母是有效小时数而非固定 24。 细颗粒物(PM2.5)示例(龙山路 240 号,2026-01-09 11:00 ~ 01-15 10:00): | 滤膜编码 | 手工 µg/m³ | 自动 µg/m³ | 相对误差 % | | --- | ---: | ---: | ---: | | 2512068 | 45 | 33 | −26.7 | | 2512069 | 35 | 25 | −28.6 | | 2512070 | 24 | 17 | −29.2 | | 2512071 | 51 | 39 | −23.5 | | 2512072 | 55 | 44 | −20.0 | | 2512073 | 44 | 36 | −18.2 | | **平均** | **42** | **32** | **−23.8**(合格率 0%) | 回归:`y = 0.8631x − 4.203`,`R² = 0.9791`。 ## 五、标准知识库(RAG) 目标:报告里每一个「依据」都能回引到标准原文条款,而不是模型凭记忆编造。 ### 5.1 技术选型 | 环节 | 方案 | 理由 | | --- | --- | --- | | 文本抽取 | PyMuPDF | 只收**带原生文本层**的 PDF;扫描件会抽出乱码,一律不收 | | 切分 | 条款级切分(`engine/rag/chunking.py`) | 按 `1`、`3.1`、`5.1.1`、`附录A` 等标题切块,检索结果能给出条款号 | | 向量化 | BGE-small-zh-v1.5(ONNX,512 维) | 中文效果稳;**onnxruntime CPU 推理,无需 torch、无需 GPU** | | 检索 | 归一化向量点积 + top-k(`engine/rag/store.py`) | 417 块规模下 numpy 暴力检索即毫秒级,不必上 faiss/chroma | 模型从 ModelScope 拉取(HuggingFace 在本机不可达),缓存在 `data/models/`(已 gitignore)。 BGE 官方用法:**问句加指令前缀、段落不加**,已在 `model.py` 中区分。 ### 5.2 已收录标准 | 标准号 | 名称 | 作用 | | --- | --- | --- | | HJ 618-2011 | 环境空气 PM10 和 PM2.5 的测定 重量法 | 手工浓度计算方法依据 | | HJ 194-2017 | 环境空气质量手工监测技术规范 | 采样体积换算、采样与质控 | | HJ 653-2021 | 环境空气颗粒物连续自动监测系统技术要求及检测方法 | 自动监测系统技术要求、数据标记 | | HJ 817-2018 | 环境空气颗粒物连续自动监测系统运行和质控技术规范 | 数据有效性判定 | | HJ 93-2026 | 环境空气颗粒物采样器技术要求及检测方法 | 采样器要求(已代替 HJ 93-2013) | ### 5.3 待补文件(需人工提供) 以下文件在公开渠道**找不到带原生文本层的版本**(只有扫描件/文库转载),为保证检索质量未强行入库: | 文件 | 影响 | | --- | --- | | 《国家环境监测网环境空气颗粒物(PM10 与 PM2.5)自动监测手工比对核查技术规定》(试行) | **±15% 质量目标**的依据;目前只能按既定值判定,无法引用条款号 | | 《2026 年安徽省环境空气监测质量检查实施方案》 | 省级考核要求 | | HJ 93-2013 原文 | 已被 HJ 93-2026 代替,暂以代替标准入库 | 补入方法:把 PDF 放进 `data/standards/raw/`,在 `data/standards/manifest.json` 里登记标准号与标题, 再执行 `npm run rag:ingest` 即可,无需改代码。 ### 5.4 接口 ```bash GET /health # 含 rag 索引状态 POST /search # {query, top_k, standard?, min_score?} -> {hits:[{standard,title,clause,page,text,score}]} ``` ## 六、工作流(工作流库 + 引擎) 报告不再写死在代码里,而是一份 YAML **规格**,分三段: ``` datasets(数据适配) ─► compute(计算规则) ─► outputs(输出绑定) 从任意原始表到 select/zip/eval/ docx 模板按段落下标 / 统一字段名的记录 filter/sort/assign/ 表格行号绑定、xlsx、json aggregate ``` - 加一种报告类型 = 加一个 YAML,**不动引擎代码,也不会有第二套数字算法**。 - 表达式在 AST 白名单里求值(禁私有名/导入/危险属性),数字全部由确定性代码算出。 - 适配失败返回的不是堆栈,而是结构化诊断(实际表头、哪个字段没匹配上、第几步失败), 智能体可以自己改规格重跑。 ```bash cd engine python -m engine.cli specs # 列出已有规格 python -m engine.cli schema # 打印写法说明 python -m engine.cli check pm25_manual_auto_compare # 校验 + 真实数据试跑 python -m engine.cli build pm25_manual_auto_compare # 出报告 ``` HTTP:`GET /specs`、`GET /specs/schema`、`POST /specs/check`、`POST /specs/run`、`PUT /specs/{id}`。 **一致性验证**:规格产出的两份 docx(正文段落 + 全部表格单元格)与 xlsx 与 Phase 1 手写实现 逐字/逐单元格完全一致;自动数据表自带的 6 个日均值也与规格用 `agg_window` 现算的结果相同。 ## 七、目录结构 ``` engine/ Python 计算引擎 engine/numeric.py 四舍五入等数值工具 engine/models.py 数据模型 engine/parsing/ Excel/xls 读取与数据集解析 engine/spec/ 报告规格引擎(schema/expr/adapters/helpers/runner/outputs) engine/reports/ 计算规则(pm25_compare.py,Phase 1 参考实现) engine/render/ docx / xlsx 渲染 engine/rag/ 标准知识库(model/chunking/store/ingest/fetch_model) engine/api.py FastAPI 服务 engine/cli.py 命令行入口 tests/test_pm25.py 回归测试(Phase 1 参考实现) tests/test_spec_pm25.py 回归测试(规格引擎:数字 + docx/xlsx 逐字逐格比对) tests/test_expr.py 表达式取整口径 / 白名单函数测试 server/ Next.js + pi Agent lib/system-prompt.ts 「工作流工程师」系统提示词(按工作空间注入目录) lib/tools.ts 9 个工作流开发工具(绑定工作空间) lib/session.ts 会话装配 + 按工作空间落盘持久化 lib/workspace.ts 工作空间注册/创建/删除(目录隔离) lib/settings.ts 隔离的 SettingsManager + provider + 技能 lib/memory.ts 工作空间长期记忆(AGENTS.md)读写与分节追加 lib/workspace.ts 工作空间 = 目录:注册/浏览/种子工作流 lib/engine.ts 引擎 HTTP 客户端(工作流 / 标准 / 设置) lib/paths.ts 仓库根目录与引擎地址 lib/client/{api.ts,store.tsx} 浏览器端接口封装 + 全局状态 components/ AppShell / ChatPanel / WorkflowsView / KnowledgeView / SettingsView / Citations / ui app/(app)/page.tsx 对话 app/(app)/workflows/ 工作流库 app/(app)/memory/ 长期记忆 app/(app)/knowledge/ 标准知识库 app/(app)/settings/ 设置 app/api/agent/route.ts SSE 对话(工作空间 + 会话 + 引用事件) app/api/workspaces/ 工作空间(目录)列表/浏览/打开 + 原始数据上传/导入 app/api/memory/ 长期记忆读写 app/api/sessions/ 会话列表/历史/新建/改名/删除 app/api/workflows/ 工作流列表/原文/保存/试跑/运行/删除 app/api/standards/ 知识库清单/条款/原文 PDF/检索 app/api/settings/ pi 设置读写 app/api/engine/[...path]/ 引擎反向代理 app/api/download/route.ts 文件下载 scripts/e2e-agent.mjs 端到端验收脚本 data/ 默认工作空间(raw/ specs/ templates/ output/) data/standards/ 标准 PDF 与向量索引 data/models/ BGE 向量模型(gitignore) .pi-dateagent/ 本应用状态(gitignore):agent 配置 / 会话 / 最近工作空间 engine/engine/spec/examples/ 随仓库分发的工作流示例(新工作空间自动复制) data/standards/raw/ 标准 PDF(仅原生文本层) data/standards/index/ 向量索引(chunks.jsonl / vectors.npy / meta.json) data/models/ BGE 向量模型(gitignore) data/output/ 生成结果 docs/ 设计文档 ``` ## 八、路线图 - [x] **Phase 1 固定报告闭环**:原始数据 → 计算 → 报告 docx + 报告单 docx + 结果表 xlsx + Web 预览/下载 - [x] **Phase 2 标准知识库(RAG)**:中文 BGE 向量检索(ONNX/CPU),417 块条款级索引,报告可回引条款号 - [x] **Phase 3 通用工作流**:声明式报告规格(数据适配 + 计算规则 + 输出绑定),智能体按 「看数据 → 读写法 → 起草规格 → 试跑 → 改正 → 出报告」的固定套路半自动新建报告类型 - [x] **Phase 4 工作台**:多工作空间(目录隔离)+ 多会话(pi 会话落盘、可续)+ 左侧工作流库 + 设置 + 知识库页面与对话引用跳转 - [x] **Phase 5 对齐 pi-web**:工作空间统一为「一个目录」+ 目录选择器;设置与 pi 配置完全隔离 (`.pi-dateagent/agent`)并支持供应商/技能管理;每个工作空间一份长期记忆(`AGENTS.md`), agent 每次工作后自动更新、下次会话自动带回