# 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` 覆盖,不进本项目环境)

## 快速启动(远端)

```bash
# 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` 直接服务。

## 一键打包

```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` 头切换);
  集成期 `VITE_BFF_TARGET=http://127.0.0.1:8090` 指向真实 BFF
- 契约文档(docs/)是开发与测试的唯一依据,变更需 PM 裁决

## 测试

```bash
# 后端(统一 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 插件（热加载，不重启）

1. 编辑 `agent/qa/configs/capabilities.yaml`（或聊天内通过 `POST /api/capabilities/install` 安装）
2. 每段 manifest：`name` + `provider`（http/mcp/python/prompt_pack）+ `schema` + 配置段
3. 保存后热加载自动生效（registry 差分刷新，MCP 子进程按需拉起，已加载进程不重启）
4. `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(测试纪律)。