forked from admin/PlantAI-rag-new
jerryandClaude Fable 5
5024a12947
- 加密工具双模式往返验证通过(字段级 properties_json / 整文件 parquet) - 取消真实加密执行:数据库未定版,中间副本已清理,kb.key 保留 - tooling/KB_ENCRYPT_GUIDE.md:完整操作步骤/踩坑记录/解密验证/流水线接入 - 踩坑固化:Qdrant 必须 snapshot API(禁 rsync 活动卷);Neo4j 5.15 community 不支持在线 dump,走 frozen 目录冷拷;canonical 库不在 KB 交付内 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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）
快速启动（远端）
# 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 裁决
测试
# 后端（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（测试纪律）。