From f81971b17677f59f2b9259277ff4ae1accdff1d0 Mon Sep 17 00:00:00 2001 From: jerry Date: Tue, 1 Sep 2026 14:28:10 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E6=8C=89=E6=9C=80=E6=96=B0?= =?UTF-8?q?=E7=8A=B6=E6=80=81=E6=9B=B4=E6=96=B0(=E7=BB=88=E6=80=81?= =?UTF-8?q?=E6=8B=93=E6=89=91=208090-8093=E3=80=81=E7=BB=9F=E4=B8=80=20ven?= =?UTF-8?q?v=E3=80=81=E4=B8=80=E9=94=AE=E6=89=93=E5=8C=85=E3=80=81?= =?UTF-8?q?=E5=AE=9E=E9=99=85=E5=BA=93=E8=AE=A1=E6=95=B0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- README.md | 106 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 63 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index bc3dfa9..19b304a 100644 --- a/README.md +++ b/README.md @@ -1,81 +1,101 @@ # PlantAI-rag-new —— 植物基因家族文献知识工作台 -海古纪 PlantAI 的知识问答工作台：基于文献知识库（100 篇论文 / 44,595 条关系断言 / 382 万实体）的 -基因家族问答系统。采用 `plantai-agent-ui-prototype` 的视觉设计（深色默认、青紫渐变、Agent 五相位时间线）， -支持桌面 / 平板 / 手机四档响应式。 +海古纪 PlantAI 的知识问答工作台：基于文献知识库(31,207 篇论文 / 824 万条关系断言 / 382 万 canonical 实体 / 631 万 normalized 实体)的基因家族问答系统。采用 `plantai-agent-ui-prototype` 的视觉设计(深色默认、青紫渐变、Agent 五相位时间线),支持桌面 / 平板 / 手机四档响应式。 -**架构**：薄适配层（BFF）+ 全新前端，不重写 RAG 算法。上游为现有运行中的服务，本项目只读消费。 +**架构**：四部分结构——① UI 前端(Vue3+Vite,开源) ② SDK 中间层(BFF,Cython 编译 .so) ③ Agent 底层服务(完全编译,仅 shell 启动) ④ 独立向量知识库(加密打包)。数据后端(Qdrant/Neo4j)只读消费,本项目不重写 RAG 算法。 ``` -浏览器 ──> BFF (FastAPI, 127.0.0.1:8090) ──> QA 7920（问答引擎） - │ ├─> RAG 8000/7900（论文抽取） - │ └─> Neo4j 18788（知识图谱，Bolt 直连） - └─> SQLite（会话历史，WAL） +浏览器 ──> BFF 8090 (FastAPI, venv py3.12.13, 静态托管 ui/dist) + ├─> QA 8091 agent/qa 编译树(45 .so,断言锚定 1.1.73) + ├─> RAG 8092 agent/methodology 编译树(28 .so,论文抽取) + ├─> legacy 8093 agent/legacy-rag 编译树(283 .so,旧路由族) + ├─> Neo4j 18788 知识图谱(Bolt 直连) + └─> SQLite sdk/data/plantai.db(会话历史,WAL) ``` ## 目录 ``` -sdk/ BFF（app/ 应用代码，mock/ 前端开发用 mock server） -ui/ Vue 3 + Vite 前端（src/ 源码） -agent/ 底层服务：qa / methodology / legacy-rag + vendor 共享池（编译交付） -knowledge/ 向量知识库打包定义（数据不入 git） -tooling/ 统一打包工具（编译/加密/组装） -docs/ 全部文档：PRD / API / UI_SPEC / ARCHITECTURE / TEST_PLAN / TEST_CASES / DISCOVERY / 测试报告 -deploy/ 部署脚本：sync.sh（本地→远端）、bff_restart.sh、start-dev.sh、集成检查、E2E 验收 -tests/ 测试（sdk 接口、ui 单元、e2e） +sdk/ BFF(app/ 应用代码,mock/ 前端开发用 mock server) +ui/ Vue 3 + Vite 前端(src/ 源码,dist/ 由 BFF 静态托管) +agent/ 底层服务:qa / methodology / legacy-rag + vendor 共享池(编译交付) +knowledge/ 向量知识库打包定义(数据不入 git) +tooling/ 统一打包工具(编译/审计/加密/组装,一键 build_all.sh) +docs/ 全部文档:PRD / API / UI_SPEC / ARCHITECTURE / TEST_PLAN / TEST_CASES / DISCOVERY / 测试报告 +deploy/ 部署脚本:sync.sh(本地→远端)、bff_restart.sh、start-dev.sh、集成检查、E2E 验收 +tests/ 测试(sdk 接口、ui 单元、e2e) ``` -## 快速启动（远端） +## 运行环境(2026-09-01 起:统一 venv,不再依赖 conda) + +- **统一 venv**:`/home/xzq/5090/teamWorkspace/zh/plantai-rag-new-venv`(Python 3.12.13,130 包) +- 依赖固化:`tooling/requirements.lock`;环境重建 = `python -m venv <路径> && pip install -r tooling/requirements.lock` +- 运行、编译、打包全部只用 venv;历史 conda 环境(gfpy312/plantai-bff/test4py311)是其他产品线共享,未删除但本项目不再引用 +- MinerU 文档解析为外部子进程(独立 conda 环境 minerupy312,经 `MINERU_CMD` 覆盖,不进本项目环境) + +## 快速启动(远端) ```bash -# 1. 启动 BFF（自动激活 conda plantai-bff） -ssh 100.109.52.26 'bash ~/5090/teamWorkspace/zh/PlantAI-rag-new/deploy/bff_restart.sh' +# 1. 三个 agent 服务(编译树,终态端口;均 venv python) +D=/home/xzq/5090/teamWorkspace/zh/plantai-rag-new-deploy-unified +(cd $D/qa && bash scripts/start.sh 8091) +(cd $D/methodology && bash scripts/start.sh 8092) +(cd $D/legacy-rag && bash scripts/start.sh 8093) -# 2. 启动 Vite 开发服务器（开发模式） -ssh 100.109.52.26 'cd ~/5090/teamWorkspace/zh/PlantAI-rag-new/ui && \ - VITE_BFF_TARGET=http://127.0.0.1:8090 setsid nohup npm run dev > /tmp/plantai-vite.log 2>&1 < /dev/null & disown' - -# 3. Mac 侧访问隧道 -ssh -N -L 5180:127.0.0.1:5180 -L 8090:127.0.0.1:8090 100.109.52.26 -# 浏览器打开 http://localhost:5180 +# 2. BFF(venv,静态托管;默认绑 127.0.0.1,公网演示传 0.0.0.0) +ssh 100.109.52.26 'bash ~/5090/teamWorkspace/zh/PlantAI-rag-new/deploy/bff_restart.sh 0.0.0.0' ``` -生产形态：`npm run build` 产出 `ui/dist`，BFF 启动时自动静态托管，单进程从 `:8090` 直接服务。 +生产形态:`npm run build` 产出 `ui/dist`,BFF 单进程静态托管,`http://:8090` 直接服务。 + +## 一键打包 + +```bash +cd tooling && bash build_all.sh [版本] # 四树编译 → 双审计 → 冒烟 → 组装 install/ +``` + +产物 `tooling/build/<版本>/install/`(sdk + 三 agent 编译树 + ui/dist + start_all.sh + SHA256SUMS + 泄露门禁)。 +P6 空目录安装验收(备用端口 8094/8095/8096/8097)待执行。 ## 开发工作流 -- **本地编辑** `/Users/jerry/haiguji/PlantAI-rag-new/`，**远端运行** `/home/xzq/5090/teamWorkspace/zh/PlantAI-rag-new/` -- 同步（PM 执行）：`bash deploy/sync.sh`（rsync，排除 node_modules/venv/data/dist） -- 前端开发期 API 指向 mock（8099，`scenario=normal|empty|slow|error|degraded` 经 `X-Mock-Scenario` 头切换）； +- **本地编辑** `/Users/jerry/haiguji/PlantAI-rag-new/`,**远端运行** `/home/xzq/5090/teamWorkspace/zh/PlantAI-rag-new/` +- 同步(PM 执行):`bash deploy/sync.sh`(rsync,排除 node_modules/.venv/data/dist) +- 前端开发期 API 指向 mock(8099,`scenario=normal|empty|slow|error|degraded` 经 `X-Mock-Scenario` 头切换); 集成期 `VITE_BFF_TARGET=http://127.0.0.1:8090` 指向真实 BFF -- 契约文档（docs/）是开发与测试的唯一依据，变更需 PM 裁决 +- 契约文档(docs/)是开发与测试的唯一依据,变更需 PM 裁决 ## 测试 ```bash -# 后端（conda plantai-bff 或本地 .venv-backend） -cd sdk && python -m pytest . -q # 单元 + 接口 +# 后端(统一 venv) +cd sdk && /home/xzq/5090/teamWorkspace/zh/plantai-rag-new-venv/bin/python -m pytest . -q # 前端 cd ui && npx vitest run --config vitest.config.js # 单元 + 组件 -cd ui && npx playwright test # E2E 三档视口（mobile/tablet/desktop） +cd ui && npx playwright test # E2E 三档视口(mobile/tablet/desktop) # 上游连通冒烟 bash tests/smoke_upstreams.sh ``` -## 上游与端口 +## 上游与端口(终态,2026-09-01) | 服务 | 端口 | 说明 | |---|---|---| -| QA V1.1.73（问答引擎） | 7920 | 只读消费；LLM 依赖 DeepSeek 余额 | -| Gene Family RAG System（抽取） | 8000 | 回落 7900 | -| Neo4j（知识图谱） | 18788 | canonical schema，Bolt 直连 | +| SDK 中间层(BFF) | 8090 | venv py3.12.13,静态托管 ui/dist,**唯一对外端口** | +| QA 问答引擎(agent/qa) | 8091 | 编译树 45 .so,版本 `1.1.73-assertion-anchored`,绑 127.0.0.1 | +| Methodology 提取(agent/methodology) | 8092 | 编译树 28 .so,绑 127.0.0.1 | +| legacy 旧路由族(agent/legacy-rag) | 8093 | 编译树 283 .so(app 3 路由 / main 11 族),绑 127.0.0.1 | +| Neo4j(知识图谱) | 18788 | canonical schema,Bolt 直连 | + +- 回滚窗(停而不删,30 天):QA 容器 `qa-normalized-formal-20260828`(7920)、methodology 宿主进程(8000)、7900 protected 容器 +- 回滚方法:重启旧服务 + `sdk/.env` 加回四行覆盖(`QA_BASE_URL`/`RAG_BASE_URL`/`RAG_LEGACY_BASE_URL`/`RAG_ALT_BASE_URL`)→ `bff_restart` ## 已知限制 -- 上游 QA 无 token 级流式（答案在终态一次返回），打字机为客户端揭示动画 -- 每次提问独立检索（`max_rounds:1`），无多轮上下文 -- DeepSeek 余额用尽时答案退化为证据列表（检索/图谱/来源不受影响） +- 上游 QA 无 token 级流式(答案在终态一次返回),打字机为客户端揭示动画 +- 每次提问独立检索(`max_rounds:1`),无多轮上下文 +- DeepSeek 余额用尽时答案退化为证据列表(检索/图谱/来源不受影响) +- KG `/overview` 慢查询(1644 万边聚合,既有问题,60s 超时返回 503 信封;`/api/kg/status` 快路径正常) -详细设计见 `docs/`：PRD.md（81 个功能点）、API.md（BFF 契约）、UI_SPEC.md（设计令牌）、 -ARCHITECTURE.md（分工与协作约定）、DISCOVERY.md（上游探测事实）、TEST_PLAN.md（测试纪律）。 +详细设计见 `docs/`:PRD.md(81 个功能点)、API.md(BFF 契约)、UI_SPEC.md(设计令牌)、 +ARCHITECTURE.md(分工与协作约定)、DISCOVERY.md(上游探测事实)、TEST_PLAN.md(测试纪律)。