adminandClaude Fable 5
964346dc77
- source .env 进 os.environ:neo4j.py 的 BFF_NEO4J_* 键与上游 URL 依赖 进程 env,仅靠 pydantic env_file 不够(175 重启卡点实测) - BIND host env 化:默认 127.0.0.1(176 生产,nginx 80 唯一入口); 175 开发在 sdk/.env 设 BFF_BIND_HOST=0.0.0.0 - 一份脚本两机通用,下次打包部署 176 不会把 BFF 暴露到 0.0.0.0 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
PlantAI-rag-new —— 植物基因家族文献知识工作台
海古纪 PlantAI 的知识问答工作台：基于文献知识库(31,207 篇论文 / 824 万条关系断言 / 382 万 canonical 实体 / 631 万 normalized 实体)的基因家族问答系统。采用 plantai-agent-ui-prototype 的视觉设计(深色默认、青紫渐变、Agent 五相位时间线),支持桌面 / 平板 / 手机四档响应式。
架构：四部分结构——① UI 前端(Vue3+Vite,开源) ② SDK 中间层(BFF,Cython 编译 .so) ③ Agent 底层服务(完全编译,仅 shell 启动) ④ 独立向量知识库(加密打包)。数据后端(Qdrant/Neo4j)只读消费,本项目不重写 RAG 算法。
浏览器 ──> 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/ 源码,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覆盖,不进本项目环境)
快速启动(远端)
# 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. 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 单进程静态托管,http://<host>:8090 直接服务。
一键打包
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头切换); 集成期VITE_BFF_TARGET=http://127.0.0.1:8090指向真实 BFF - 契约文档(docs/)是开发与测试的唯一依据,变更需 PM 裁决
测试
# 后端(统一 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)
# 上游连通冒烟
bash tests/smoke_upstreams.sh
上游与端口(终态,2026-09-01)
| 服务 | 端口 | 说明 |
|---|---|---|
| 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
能力系统（Capability Gateway，2026-09-02 起）
能力矩阵
| 能力 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 多轮记忆 | SDK 层 | 开 | 同会话连续提问携带上文（最近 3 轮，检索仍独立执行） |
| 联网搜索 | QA Gateway（http provider） | 关 | KB 证据不足时补 PubMed/Crossref 文献（[WEB: url] 引用） |
| 答案润色 Humanizer | SDK 层 | 关 | 9 类规则去 AI 行文痕迹（引用/表格/图片/代码块原样保留） |
| Superpowers 提示词包 | QA Gateway（prompt_pack） | 关 | 证据审查与答案自检强化（3 个 SKILL.md 注入） |
- 开关：设置面板（左栏底部齿轮，展开态「设置」按钮）→ 按会话生效（sessions.meta.capabilities）
- 联网搜索/ Superpowers 受 env 总闸控制（见下表）；聊天内安装的 MCP 插件走同一 Gateway
环境变量
| 变量 | 默认 | 说明 |
|---|---|---|
| QA_V1_ENABLE_WEB_SEARCH | 0 | 联网搜索总闸（会话开关之下） |
| QA_V1_WEB_SEARCH_MAX_RESULTS | 4 | 联网结果条数上限 |
| QA_V1_WEB_SEARCH_TIMEOUT | 8 | 出网超时（秒） |
| QA_V1_WEB_SEARCH_MAX_CHARS | 1200 | 摘要截断长度 |
| QA_V1_ENABLE_SUPERPOWERS | 0 | Superpowers 注入总闸 |
| BFF_HISTORY_ROUNDS | 3 | 多轮记忆轮数（BFF） |
如何新增 skill/MCP 插件（热加载，不重启）
- 编辑
agent/qa/configs/capabilities.yaml（或聊天内通过POST /api/capabilities/install安装） - 每段 manifest：
name+provider（http/mcp/python/prompt_pack）+schema+ 配置段 - 保存后热加载自动生效（registry 差分刷新，MCP 子进程按需拉起，已加载进程不重启）
GET /api/capabilities可查已装清单与 load_warnings（坏条目跳过不影响主体）
详见 docs/ARCHITECTURE.md「Capability Gateway」章节与 docs/API.md §6。
已知限制
- 上游 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(测试纪律)。