jerryandClaude Fable 5
0875bb036c
- git mv 保留历史：ui/(Vue3+Vite)、sdk/(BFF 中间层)
- 路径语义修正：db_path/figures_cache 改相对 sdk/(BFF cwd)，
历史库 sdk/backend/data 迁移至 sdk/data/(会话/图片缓存无损)
- 引用修复 ~15 处：config.py、deploy/*.sh、vitest/playwright 配置、
单测导入路径、docs、README、gitignore、.env.example
- 骨架：agent/{qa,methodology,legacy-rag,vendor}、knowledge/manifest.yaml、
tooling/{compile,kb,crypto,assemble,audit,tools,scripts} + README
- 门禁验证：sdk pytest 125 通过、ui vitest 158 通过、
生产 BFF 脚本重启四上游全绿 + 静态托管 + 会话库无损
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
82 lines
3.8 KiB
Markdown
82 lines
3.8 KiB
Markdown
# PlantAI-rag-new —— 植物基因家族文献知识工作台
|
||
|
||
海古纪 PlantAI 的知识问答工作台：基于文献知识库（100 篇论文 / 44,595 条关系断言 / 382 万实体）的
|
||
基因家族问答系统。采用 `plantai-agent-ui-prototype` 的视觉设计（深色默认、青紫渐变、Agent 五相位时间线），
|
||
支持桌面 / 平板 / 手机四档响应式。
|
||
|
||
**架构**：薄适配层（BFF）+ 全新前端，不重写 RAG 算法。上游为现有运行中的服务，本项目只读消费。
|
||
|
||
```
|
||
浏览器 ──> BFF (FastAPI, 127.0.0.1:8090) ──> QA 7920（问答引擎）
|
||
│ ├─> RAG 8000/7900（论文抽取）
|
||
│ └─> Neo4j 18788（知识图谱，Bolt 直连）
|
||
└─> SQLite（会话历史，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）
|
||
```
|
||
|
||
## 快速启动（远端）
|
||
|
||
```bash
|
||
# 1. 启动 BFF（自动激活 conda plantai-bff）
|
||
ssh 100.109.52.26 'bash ~/5090/teamWorkspace/zh/PlantAI-rag-new/deploy/bff_restart.sh'
|
||
|
||
# 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
|
||
```
|
||
|
||
生产形态：`npm run build` 产出 `ui/dist`，BFF 启动时自动静态托管，单进程从 `:8090` 直接服务。
|
||
|
||
## 开发工作流
|
||
|
||
- **本地编辑** `/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 裁决
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
# 后端（conda plantai-bff 或本地 .venv-backend）
|
||
cd sdk && python -m pytest . -q # 单元 + 接口
|
||
# 前端
|
||
cd ui && npx vitest run --config vitest.config.js # 单元 + 组件
|
||
cd ui && npx playwright test # E2E 三档视口（mobile/tablet/desktop）
|
||
# 上游连通冒烟
|
||
bash tests/smoke_upstreams.sh
|
||
```
|
||
|
||
## 上游与端口
|
||
|
||
| 服务 | 端口 | 说明 |
|
||
|---|---|---|
|
||
| QA V1.1.73（问答引擎） | 7920 | 只读消费；LLM 依赖 DeepSeek 余额 |
|
||
| Gene Family RAG System（抽取） | 8000 | 回落 7900 |
|
||
| Neo4j（知识图谱） | 18788 | canonical schema，Bolt 直连 |
|
||
|
||
## 已知限制
|
||
|
||
- 上游 QA 无 token 级流式（答案在终态一次返回），打字机为客户端揭示动画
|
||
- 每次提问独立检索（`max_rounds:1`），无多轮上下文
|
||
- DeepSeek 余额用尽时答案退化为证据列表（检索/图谱/来源不受影响）
|
||
|
||
详细设计见 `docs/`：PRD.md（81 个功能点）、API.md（BFF 契约）、UI_SPEC.md（设计令牌）、
|
||
ARCHITECTURE.md（分工与协作约定）、DISCOVERY.md（上游探测事实）、TEST_PLAN.md（测试纪律）。
|