PlantAI-rag-new/docs/docgen_team_context.md at main

Files

T

jerryandClaude Fable 5 8467dec3a8 fix(bff): 断流崩溃根治——SSE 取消链模块明文化 + 团队文档归档

客户端中途断开流时 Cython 协程 __Pyx_Coroutine_SendEx 断言 abort 整个 BFF。
证据链:3.2.8 崩 db.c / 3.3.0 仍崩(升级无效) / db 明文后迁移 sse_relay.c,
证明取消链上任意 Cython 协程均可触发。最终把 db.py/qa.py/sse_relay.py
加入编译白名单(明文),隔离实例断流探针 10/10 存活,生产同构建实测通过。
代价:3 模块失去编译硬化(无凭据内容),编译模块 30->27。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-09-03 21:13:56 +08:00

4.1 KiB

Raw Permalink Blame History

===== 服务器关键环境事实（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/-/

===== 团队纪律（所有 agent 必须遵守） =====

所有改码只在服务器仓库 /home/xzq/5090/teamWorkspace/zh/PlantAI-rag-new（经 ssh xzq@8.163.92.8 执行）
开发 agent 只动自己模块的文件；不越界改其他模块
零改动：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 零改动
不 push git、不做 commit/tag（由 TL 统一决定）
不改服务器运行中的生产进程；不自行部署（部署/重启由 TL 执行）
不自行跑 ssh、不连生产端口探测（连 curl 127.0.0.1:8090/8091 也不行——别动运行中的服务）
单元测试只跑不依赖生产服务/网络的（可用 mock/fixture/tmpdir）；pytest 入口由 TL 统一执行
每个 agent 有独立工作文件目录（见各任务书），互不写入
明文安全：不落未加密的模版/附件内容到仓库或日志；测试样例可用占位文本
产出报告写在本任务书指定的报告文件

===== 需要改代码前必读的仓库文件 =====

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 确认）

4.1 KiB Raw Permalink Blame History Unescape Escape

4.1 KiB

Raw Permalink Blame History