jerryandClaude Fable 5
cd7e98e7c7
- sdk/services/capabilities.py: MANIFEST+DEFAULTS+sanitize+QA 注册表合并 - sdk/services/humanizer.py: 9 类中文 AI 痕迹规则(块级保护引用/表格/代码/图片) - sdk/routers/capabilities.py: GET /api/capabilities + POST install 透传 - sdk/schemas.py+sessions.py: SessionMeta.capabilities + PATCH meta 白名单 merge - sdk/routers/qa.py: humanize 会话开关注入 SSE;chat.js: body 加 session_id - sse_relay.py: humanize_enabled 参数链(修 _pump_events 可见性编译错误) - api.py(QA): /capabilities/registry loopback(BFF 合并) - ui: settings store+SettingsPanel+AppShell 接线+SessionPanel 展开态设置入口+labels - 测试: humanizer 8 用例+capabilities_svc 6 用例;SDK 146 全绿;UI vitest 172 全绿 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
已知限制
- 上游 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(测试纪律)。