===== 服务器关键环境事实（doc_writer 实施团队共享上下文，2026-09-03 实测） =====

【路径】
- 服务器仓库: /home/xzq/5090/teamWorkspace/zh/PlantAI-rag-new （git main，当前干净，HEAD aab24d2）
- 部署根: /home/xzq/5090/teamWorkspace/zh/plantai-rag-new-deploy-unified/（sdk/ + ui/，另有 legacy-rag/ qa/ methodology/）
- venv: /home/xzq/5090/teamWorkspace/zh/plantai-rag-new-venv/bin/python（py3.12.13）
- UI 源码: /home/xzq/5090/teamWorkspace/zh/PlantAI-rag-new/ui/（vite dev 5180，vite.config proxy 8090；生产 dist 由 TL 构建同步）

【端口】8090 BFF / 8091 QA（金标，零改动）/ 8092-8093 legacy RAG / 8094 vstore（新） / 8099 mock / 5180 vite dev
【版本】venv 已装：python-docx 1.1.2、pymupdf 1.28.2、faiss-cpu 1.14.3、cryptography 50.0.1、markdown-it-py 4.2.0、PyYAML、httpx、numpy；无 pandoc/libreoffice
【LLM/嵌入】ollama 在跑：bge-m3:567m（1024 维，0.37s/条，QA 现役同款）；qwen3:8b-q4_K_M 本机可用（保密档 LLM）
【字体】/usr/share/fonts/opentype/noto/NotoSansCJK-*.ttc、NotoSerifCJK-*.ttc、truetype/wps-office/（PDF 必须用真实字体文件，禁用 PyMuPDF 内置 CJK）

===== 关键代码事实 =====
- BFF 是 Cython 编译部署：db.py/services/ 编译为 .so；main.py/config.py/schemas.py 是明文白名单（pydantic 模型只能放 schemas.py；服务层只用 dataclass/dict）
- 测试命名先例：sdk/app/services/test_*.py、sdk/app/routers/test_*.py（新增照此）
- PipelineCard.vue：pc-head 含 pc-title + 状态 badge；块结构 {type:pipeline, status, steps:[{name,state,desc,phase}]}；PHASE_COLOR_VAR 键：planning/retrieval/evidence/generation/done（在 ui/src/i18n/labels.js:24-30）
- BenchPanel.vue：tabs 数组 + bench.activeTab===key 的 v-if pane 链（retrieval/sources/extract/kg）；bench.js setActiveTab(key) 任意 key 可用
- 前端已有 markdown-it 14.1.0 + dompurify 3.2.3（渲染/消毒现成）；上传先例：extraction multipart；http.js 600s 兜底
- 左栏展开/收起按钮样式：ui/src/styles/base.css:697-711 .side-handle-btn（26×26 圆角、hairline 描边、surface-1 底、跨左栏边缘半嵌、垂直居中）
- BFF 重启：bash /home/xzq/5090/teamWorkspace/zh/PlantAI-rag-new/deploy/bff_restart.sh（setsid 脱离 SSH，日志 /tmp/plantai-bff.log）
- vstore 将新增 deploy/vstore_restart.sh（仿 bff_restart.sh：uvicorn vstore.api:app --port 8094）
- 备份目录先例：/home/xzq/backups/<name>-<TS>/

===== 团队纪律（所有 agent 必须遵守） =====
1. 所有改码只在服务器仓库 /home/xzq/5090/teamWorkspace/zh/PlantAI-rag-new（经 ssh xzq@8.163.92.8 执行）
2. 开发 agent 只动自己模块的文件；不越界改其他模块
3. 零改动：QA 树（8091）、ui/src/stores/modes.js、ui/src/i18n/labels.js、ui/src/stores/bench.js(store)、ui/src/api/qa.js、ui/src/sse/parser.js；capabilities.py 零改动
4. 不 push git、不做 commit/tag（由 TL 统一决定）
5. 不改服务器运行中的生产进程；不自行部署（部署/重启由 TL 执行）
6. 不自行跑 ssh、不连生产端口探测（连 curl 127.0.0.1:8090/8091 也不行——别动运行中的服务）
7. 单元测试只跑不依赖生产服务/网络的（可用 mock/fixture/tmpdir）；pytest 入口由 TL 统一执行
8. 每个 agent 有独立工作文件目录（见各任务书），互不写入
9. 明文安全：不落未加密的模版/附件内容到仓库或日志；测试样例可用占位文本
10. 产出报告写在本任务书指定的报告文件

===== 需要改代码前必读的仓库文件 =====
- sdk/app/config.py、sdk/app/schemas.py、sdk/app/db.py、sdk/app/main.py（P2 必读全文）
- sdk/app/routers/qa.py（错误信封格式与 multipart 先例）、sdk/app/routers/extraction.py 或类似（上传先例）
- ui/src/stores/chat.js、ui/src/components/chat/Composer.vue、PipelineCard.vue、AssistantMessage.vue、ui/src/components/bench/BenchPanel.vue、ui/src/components/layout/AppShell.vue、ui/src/styles/base.css（P3 必读全文）
- tooling/compile/compile_sdk.sh（编译清单机制——P2 若增删编译白名单文件需 TL 确认）