adminandClaude Fable 5
dea46402e8
用户需求:客户上传 PDF 等资料进行向量化并追加进向量库,且问答可检索。 决策:全局检索融合 / BFF 直连 DeepSeek 生成私有回答 / 两路并行展示(命中才显示) / 「我的资料」管理界面挂文档 TAB 空态。改动仅限本分支,QA 金标树与红线零改动。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
44 lines
4.0 KiB
Markdown
44 lines
4.0 KiB
Markdown
# 私有资料问答（FR-PRIV）· 团队共享上下文
|
||
|
||
> docs/private_docs_team_context.md —— A1（编码）与 T1（测试）开工前必读。仿 docgen_team_context.md 纪律。
|
||
|
||
## 1. 目标与范围（只做这些）
|
||
|
||
客户上传 PDF/DOCX/TXT → 向量化 → 追加向量库 → **问答可检索**（PRD §17 FR-PRIV-001~008）。四决策已拍板：全局检索融合；私有答案 BFF 直连 DeepSeek；两路并行展示（命中才显示）；「我的资料」管理界面挂文档 TAB 空态。
|
||
|
||
## 2. 服务器事实（不可想当然）
|
||
|
||
- 仓库 `/home/xzq/5090/teamWorkspace/zh/PlantAI-rag-new`（分支 feature/bioflow-conversation-orchestration，当前 HEAD 759427b）；部署树 `/home/xzq/5090/teamWorkspace/zh/plantai-rag-new-deploy-unified`。
|
||
- 端口：BFF 8090（0.0.0.0）、vstore 8094（127.0.0.1 单 worker 明文 Python）、QA 8091（金标树红线）。venv = /home/xzq/5090/teamWorkspace/zh/plantai-rag-new-venv/bin/python（py3.12）。
|
||
- vstore 数据根：deploy-unified/docgen/（vault 210 个 .enc + index/index.json）；embed 走 Ollama（127.0.0.1:11434，bge-m3:567m 1024 维，实测单条 3.44s、input 数组 4 条 0.32s）。
|
||
- 上传链路已存在（勿重造）：BFF POST /api/docgen/library → vstore /api/vstore/ingest → doc_library 表；前端 uploadLibrary/listLibrary 已有。
|
||
- 生产 .env 已配：VSTORE_BASE_URL、DOCGEN_LLM_*（deepseek-chat）。
|
||
|
||
## 3. 改动文件清单（只动这些；多动一个即违规）
|
||
|
||
vstore 侧（明文，不编译）：`vstore/chunks.py`（新）、`vstore/embed.py`、`vstore/vault.py`、`vstore/api.py`、`vstore/settings.py`、`vstore/scripts/rebuild_chunks.py`（新）、`vstore/tests/test_chunks.py`（新，T1）。
|
||
BFF 侧：`sdk/app/services/privateqa.py`（新）、`sdk/app/routers/private_docs.py`（新）、`sdk/app/schemas.py`、`sdk/app/main.py`、`sdk/app/services/docgen/client.py`、`sdk/app/services/docgen/llm.py`。
|
||
前端：`ui/src/api/private.js`（新）、`ui/src/stores/chat.js`、`ui/src/components/chat/AssistantMessage.vue`、`ui/src/i18n/private.js`（新）、`ui/src/components/bench/PrivateLibraryPane.vue`（新）、`ui/src/components/bench/DocPane.vue`、`ui/src/api/docgen.js`、`ui/tests/private_docs/*`（新，T1）。
|
||
文档（TL 独占）：PRD.md、UI_SPEC.md、PRIVATE_DOCS_TEST_PLAN.md、team/ 下任务书与轮次报告。
|
||
|
||
## 4. 红线（零改动，diff 必须为空）
|
||
|
||
- QA 金标树 8091（agent/qa 与部署树 qa 全部文件）。
|
||
- 前端：stores/modes.js、labels.js、bench.js、api/qa.js、sse/parser.js、PipelineCard.vue。
|
||
- vstore：retrieval.py、parsing.py、backend.py、crypto.py（chunk 能力全部新写，不改造既有模块）。
|
||
- sdk：routers/qa.py、services/sse_relay.py、tooling/compile/compile_sdk.sh 白名单（不动）。
|
||
- docgen 既有行为：doc 级 title 检索、模板匹配、生成链路——行为零变化。
|
||
|
||
## 5. 技术纪律
|
||
|
||
- vstore 侧纯明文部署，禁止擅自引入新依赖（只用 faiss/numpy/pymupdf/python-docx/Ollama HTTP 既有件）。
|
||
- BFF 新模块**禁止 yield/SSE**（Cython 协程取消断言会崩 BFF）；新模块可编译 .so，不进白名单。
|
||
- 服务层只用 dataclass/dict/stdlib；pydantic 只进 schemas.py。
|
||
- 零硬编码：路径/URL 全部环境变量或设置推导（VSTORE_CHUNK_PATH 等）。
|
||
- 嵌入纪律：批量数组（batch 16 × workers 4）；失败重试一次仍失败降级零向量；chunk 失败不阻断 doc 级入库。
|
||
- 同步阻塞：api.py 端点内同步段一律 `asyncio.to_thread`。
|
||
|
||
## 6. 纪律（同 docgen_team_context 十条）
|
||
|
||
1. 只动 §3 清单文件；2. 不 commit、不 push、不部署（TL 统一执行）；3. 测试 agent 不修改任何产品代码；4. 不自连生产服务做破坏性操作（vstore 重启/重建由 TL 执行）；5. 凭据不落文件不打印；6. 改动必须能说明对应哪个 FR-PRIV；7. 每轮测试产出轮次报告；8. 自测通过才交付；9. 有疑问先问 TL 不要自行裁决；10. 完成任务后回报 TL。
|