jerryandClaude Fable 5
bbd5db2315
- prompts/superpowers_{review,answer_quality,minimal_code}.md + prompt_pack.py
- agentic_controller/answer_composer Superpowers 注入点(env 总闸,关态逐字节一致)
- compile_qa.sh: prompts/ 目录自动拷贝
- humanizer: CJK 逗号规则 + 引用保护收窄(只护标记本身,带引用句可润色)
- docs: README 能力矩阵+env 表 / ARCHITECTURE Gateway 章 / API §6 / PRD:17 /
TEST_CASES:126 多轮语义 / CHANGELOG
- tooling/cap/final_acceptance.sh 终验矩阵
- 终验: 金标 16/20 regressions=0, 多轮指代 PASS, 热加载 PID 不变 PASS,
Humanizer 开态「此外」消除且 22 引用保留, 五上游全绿, 7913 已释放
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
136 lines
7.3 KiB
Markdown
136 lines
7.3 KiB
Markdown
# 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(测试纪律)。
|