PlantAI-rag-new/docs/ARCHITECTURE.md

ARCHITECTURE.md —— PlantAI-rag-new 架构与协作约定

版本 1.0 ｜ 作者 PM ｜ 本文件由 PM 独占写入，所有开发/测试 agent 只读

---

1. 项目定位

PlantAI-rag-new 是植物基因家族文献 RAG 知识系统的新一代工作台。

它不重写 RAG 算法、检索引擎与论文抽取流水线——那些是现有 PlantAI-rag 工程中经真实论文验证的资产。本项目做两件事：

1. 一层薄适配（BFF, Backend-For-Frontend）：代理并归一化现有运行中的上游服务，补齐上游缺失的能力（会话持久化、图谱直连、统一错误信封）。
2. 一套全新的响应式前端：严格实现 plantai-agent-ui-prototype.html 的视觉系统，并扩展为支持手机的四档自适应布局。

红线：不修改 PlantAI-rag、PlantAI-dev、rag-qa-v1_1_73 的任何源文件；不占用其端口；不切换其流量。

---

2. 系统拓扑

┌────────── 用户浏览器（桌面 / 平板 / 手机）──────────┐
│                                                      │
│   Vue 3 SPA   ← 开发期 Vite dev :5180                │
│                 生产期由 BFF 静态托管                 │
└───────────────────────┬──────────────────────────────┘
                        │ /api/*  (同源，JSON + SSE)
┌───────────────────────▼──────────────────────────────┐
│         BFF   FastAPI + Uvicorn   127.0.0.1:8090     │
│  ┌────────────┬────────────┬───────────┬──────────┐  │
│  │ sessions   │ qa         │ kg        │extraction│  │
│  │ (SQLite)   │ (代理+SSE) │(Bolt直连) │ (代理)   │  │
│  └────────────┴─────┬──────┴─────┬─────┴────┬─────┘  │
└────────────────────┬┴────────────┴──────────┴────────┘
                     │             │          │
        ┌────────────▼──┐  ┌───────▼─────┐  ┌─▼──────────────┐
        │ QA V1.1.73    │  │  Neo4j Bolt │  │ Gene Family    │
        │ 127.0.0.1:7920│  │ 19788/18788 │  │ RAG :8000      │
        │ （只读消费）  │  │ /17687      │  │ 回落 :7900     │
        └───────────────┘  └─────────────┘  └────────────────┘

BFF 的存在理由（不是无谓的中间层）：

职责	为什么前端不能直连上游
会话持久化	上游 QA 完全无状态，没有会话概念，UI 的历史列表必须有人存
别名归一化	上游同一语义有多个字段名（answer/response/message 等），归一化放前端会污染每个组件
SSE 阶段映射	上游推十余个细粒度 stage，UI 只需五阶段；映射放 BFF，前端不需要知道上游阶段名
图谱直连	上游 /kg/* 路由指向已死的 7687 端口，必须由 BFF 用 Bolt 驱动绕过
统一错误信封	三个上游三套错误格式，前端只应处理一种
跨域与凭据	上游只绑回环且 Neo4j 需要密码，凭据不能进浏览器

---

3. 运行时约定

项	值
BFF 监听	127.0.0.1:8090（占用则退 8091）
Vite dev	127.0.0.1:5180（占用则退 5181）
BFF conda 环境	plantai-bff（Python 3.11，新建，不复用 gfpy312）
SQLite 路径	sdk/data/plantai.db（WAL 模式）
前端工具链	Vite 5.4.x + @vitejs/plugin-vue 5.2.x + Vue 3.5.x + Pinia 2.3.x
Node	v18.19.1（已 EOL）——禁止升级 Vite 至 7（需 Node 20+），禁止用 npm create vite

生产形态：npm run build 产出 ui/dist，BFF 用 StaticFiles 挂载，单进程从 :8090 提供服务。

---

4. 开发工作流：本地 staging + rsync

远端机器是运行与测试环境，本地是编辑环境。原因：agent 在本地能用完整的读/写/编辑工具迭代，通过 SSH 逐行改远端文件既慢又易错。

角色	路径
本地编辑（权威源）	/Users/jerry/haiguji/PlantAI-rag-new/
远端运行（部署副本）	/home/xzq/5090/teamWorkspace/zh/PlantAI-rag-new/

同步命令（由 deploy/sync.sh 封装）：

rsync -az --delete \
  --exclude 'node_modules' --exclude '__pycache__' --exclude '.venv' \
  --exclude 'sdk/data' --exclude 'ui/dist' --exclude '.pytest_cache' \
  /Users/jerry/haiguji/PlantAI-rag-new/ \
  100.109.52.26:/home/xzq/5090/teamWorkspace/zh/PlantAI-rag-new/

规则：

• 所有 agent 只在本地路径写文件，绝不用 SSH heredoc 改代码。
• 同步由 PM 统一执行，agent 不自行 rsync（避免半成品覆盖远端）。
• sdk/data（数据库）、node_modules、dist 不同步，属远端运行时产物。
• 文档最终必须在远端 docs/ 下可查——每次里程碑结束由 PM 同步一次。

---

5. Agent 分工与文件归属

铁律：文件归属严格互斥。任何 agent 不得写入不属于自己的文件。 需要跨归属改动时，向 PM 提出，由 PM 单点裁决修改。

Agent	职责	独占路径
PM	契约文档、集成、缺陷派发、验收、rsync	docs/{PRD,API,UI_SPEC,ARCHITECTURE,TEST_PLAN,ACCEPTANCE,CHANGELOG}.md、deploy/**、src/i18n/labels.js、src/config/modes.js、sdk/mock/**
D0 探测	上游探测与选型	docs/DISCOVERY.md
A1 后端·骨架	app 工厂、配置、SQLite、会话与消息 CRUD、归一化器、错误信封	sdk/pyproject.toml、sdk/run.sh、sdk/.env.example、sdk/app/{main,config,db,schemas,upstream}.py、sdk/app/routers/{health,sessions}.py、sdk/app/services/normalize.py
A2 后端·QA	QA 代理、SSE 中继、阶段映射、重试与看门狗	sdk/app/routers/qa.py、sdk/app/services/sse_relay.py
A3 后端·图谱与抽取	Neo4j Bolt 直连、抽取代理与回落	sdk/app/routers/{kg,extraction}.py、sdk/app/services/{neo4j,extraction}.py
B1 前端·基础	令牌层、AppShell、四档响应式框架、主题、顶栏/底栏、通用 UI、健康轮询	ui/{package.json,vite.config.js,vitest.config.js,index.html}、ui/src/{main.js,App.vue}、ui/src/styles/**、ui/src/components/{layout,ui}/**、ui/src/stores/{theme,health}.js、ui/src/api/http.js、tests/ui/unit/b1/**
B2 前端·会话与对话	会话列表与抽屉、对话区、作曲器、流水线卡、SSE 客户端	ui/src/components/{session,chat}/**、ui/src/stores/{sessions,chat}.js、ui/src/sse/**、ui/src/api/{qa,sessions}.js、tests/ui/unit/b2/**
B3 前端·工作台	右侧四个 tab：检索过程、文献来源、提取任务、知识图谱	ui/src/components/bench/**、ui/src/stores/bench.js、ui/src/api/{kg,extraction}.js、tests/ui/unit/b3/**
T 测试	用例编写与执行、缺陷报告	tests/sdk/api/**、tests/e2e/**、playwright.config.js、docs/TEST_CASES.md、docs/TEST_REPORT_*.md

后端各 agent 的单测放在各自归属子树内（sdk/app/**/test_*.py，随代码一起交付），运行 pytest sdk/app -q；T 的 L2 接口测试与 L5 e2e 放在 tests/。

跨归属的接缝

以下文件被多方读取但只有一个写入方，接缝处必须按契约对齐：

接缝	写入方	读取方	契约依据
BFF 接口形态	A1/A2/A3	B1/B2/B3、T	API.md
设计令牌 CSS 变量	B1 (styles/tokens.css)	B2、B3	UI_SPEC.md §令牌
组件类名	B1 定义基础类，B2/B3 复用	互相	UI_SPEC.md §组件
五阶段标签与颜色	PM (i18n/labels.js)	A2（计算 phase）、B2、B3	PRD.md FR-CHAT-009
模式参数集	PM (config/modes.js)	B2	PRD.md FR-CHAT-006
块联合结构	A1（落库）、B2（渲染）	T	API.md §块联合

---

6. 并行解耦：mock server

前端三个 agent 不等待后端。M0 阶段 PM 产出 sdk/mock/mock_server.py：

• FastAPI，监听 127.0.0.1:8099
• 实现 API.md 中全部接口，返回 sdk/mock/fixtures/*.json 里的固定数据
• 包含一条可回放的 SSE 事件序列（按真实时序 sleep），让流式 UI 能在无上游时开发
• 支持 ?scenario= 查询参数切换场景：normal / empty（空结果）/ slow（慢响应）/ error（上游故障）/ degraded（部分降级）

B 组开发时把 vite.config.js 的 proxy 指向 8099；集成阶段由 PM 切回 8090。

fixtures 是单一事实源：mock 与真实 BFF 的单元测试共用同一批 fixture 文件，保证契约不漂移。

---

7. 集成节奏

M0 契约锁定 ──┬─→ A1 A2 A3（对真实上游）──┐
              ├─→ B1 B2 B3（对 mock）    ─┤→ M2 PM 集成 → M3 补齐 → M4 测试循环 → M5 验收
              └─→ T 写用例（对 PRD）      ─┘

• 每一波结束，agent 向 PM 汇报「完成项 + 未决问题 + 对契约的偏差建议」，不直接改契约。
• PM 在集成点统一处理契约偏差，必要时更新 API.md 并广播给受影响的 agent。
• 缺陷修复一律批量派发，禁止边测边改（见 TEST_PLAN.md 轮次纪律）。

---

8. 目录结构

PlantAI-rag-new/
├── docs/                       # 全部文档，见第 5 节归属
├── deploy/
│   ├── sync.sh                 # 本地 → 远端 rsync
│   └── start-dev.sh            # 拉起 BFF + vite，打印隧道命令
├── sdk/
│   ├── pyproject.toml  run.sh  .env.example
│   ├── data/                   # plantai.db（不入库、不同步）
│   ├── mock/
│   │   ├── mock_server.py
│   │   └── fixtures/*.json
│   └── app/
│       ├── main.py config.py db.py schemas.py upstream.py
│       ├── routers/  health.py sessions.py qa.py kg.py extraction.py
│       └── services/ normalize.py sse_relay.py neo4j.py extraction.py
├── ui/
│   ├── package.json  vite.config.js  index.html  vitest.config.js
│   └── src/
│       ├── main.js  App.vue
│       ├── styles/    tokens.css base.css animations.css responsive.css
│       ├── i18n/labels.js       config/modes.js
│       ├── api/       http.js qa.js sessions.js kg.js extraction.js
│       ├── sse/       parser.js
│       ├── stores/    theme.js health.js sessions.js chat.js bench.js
│       └── components/
│           ├── layout/   AppShell 相关、TopBar、StatusBar、AuroraBg、Drawer
│           ├── ui/       StatusBadge、StatusDot、IconButton、Skeleton、EmptyNotice
│           ├── session/  SessionPanel、SessionItem、SessionRail、SearchBox
│           ├── chat/     ChatPanel、MessageList、Composer、PipelineCard、ToolCard …
│           └── bench/    BenchPanel、RetrievalPane、SourcesPane、ExtractionPane、KgPane …
├── tests/
│   ├── sdk/                # pytest
│   ├── ui/               # vitest
│   └── e2e/                    # playwright
└── playwright.config.js

---

9. 编码约定

后端

• 全异步（async def + httpx.AsyncClient + aiosqlite）；不在请求路径上做阻塞 IO。
• 所有对上游的调用集中在 services/，routers/ 只做参数校验与响应组装。
• 不吞异常：上游故障必须转成带 code 的错误信封，并在日志里保留原始异常。
• 类型标注齐全，Pydantic v2 模型定义在 schemas.py。

前端

• Vue 3 <script setup> + Composition API；组件单一职责，超过 ~250 行考虑拆分。
• 样式一律用 --pa-* 令牌，禁止硬编码颜色值（令牌表见 UI_SPEC.md）。
• 组件内 <style scoped>；跨组件复用的类放 styles/base.css（B1 归属）。
• 状态跨组件共享一律走 Pinia store，禁止用 provide/inject 传业务状态。
• 所有用户可见文案走 i18n/labels.js，组件内不写死中文字符串（错误提示除外，见 PRD.md §全局约定）。

通用

• 文件编码 UTF-8，LF 换行。
• 提交粒度：一个 FR 一次提交，提交信息含 FR 编号。

---

10.5 Capability Gateway（2026-09-02 起）

三层机制

• 注册层：agent/qa/configs/capabilities.yaml（明文、可热加载）。每个能力一段 manifest（provider/permission/schema/默认开关）；坏条目跳过并记 load_warnings， 一条坏配置不影响其余能力，更不影响 QA 主体启动。
• 调用层：capabilities/{manifests,registry,providers,install_manager}.py + tool_runner.py（编译 .so）。四 Provider：HttpToolProvider（HTTP JSON 工具）、 McpToolProvider（官方 mcp SDK，stdio 子进程 + streamable-http；空闲回收、 崩溃限次重启 3 次熔断）、PythonToolProvider（module:function）、 PromptPackProvider（SKILL.md 注入）。
• 安装管理层：install_manager.py（白名单校验、单写锁 + 原子替换、操作审计 JSONL）+ QA loopback /api/v1/qa-v1-1-73/capabilities/install + BFF 透传 POST /api/capabilities/install。热加载 = 重解析 → registry 差分刷新 → MCP 子进程按 diff 启停（已加载进程不重启；QA 冷启动 ~167s 是热加载硬要求的动因）。

会话级开关链

设置面板 PATCH sessions.meta.capabilities（BFF 白名单 sanitize）→ BFF 读 meta → 注入 body.history（memory on）/ body.capabilities（web_search 双闸：会话开 AND env 总闸）→ QA 按 capabilities 决策。humanize 在 BFF complete 帧归一化后、 图片注入后执行（纯 BFF 层）。

首批四项能力落点

能力	落点
多轮记忆	SDK services/history.py（3 轮/16k 预算）→ QA answer_composer Dialogue Context 段（检索零回归）
联网搜索	QA web_search.py（PubMed esearch+esummary → Crossref 兜底；中文问题经 build_query 转英文）→ pipeline 证据采纳后确定性门控（去重公开引用数 < min_evidence）
Humanizer	SDK services/humanizer.py（9 类规则纯函数；块级保护）
Superpowers	QA prompts/*.md + prompt_pack.py 注入 answer_composer SYSTEM / agentic REVIEW

金标防抖（LLM 方差实证）

金标 compare 对基线 PASS 而批次 FAIL 的题复跑一次；GI-005（拟南芥 WRKY 成员数） 经配对采样实证为上游 deepseek-chat 随时间漂移（同题同端口多次采样 key_hit 0.2~0.8 横跨阈值），标记 flaky 不计回归。见 qa-golden/S0_RECORD.md。

10. 已知的既存故障（不修，仅规避）

现象	影响	我们的对策
默认端口 7687 无 Neo4j，:8000/api/v1/kg/* 与 /v15-graph-qa/* 报错	上游图谱路由不可用	BFF 用 Bolt 直连非标准端口实例，见 DISCOVERY.md
PlantAI-dev .env 指向 7925（空端口），实际 QA 在 7920	PlantAI-dev 知识问答当前是坏的	与本项目无关，仅记录；本项目指向 7920
上游 QA 无 token 级流式，答案在终态一次返回	无法做真流式打字	客户端揭示动画，视觉一致但不伪造数据流
上游 max_rounds: 1，每个提问独立	无多轮上下文	UI 明确提示「每次提问独立检索」，不假装有上下文记忆