PlantAI-rag-new/docs/team/brief_bioflow_dev2_p1.md

任务书：开发 agent A2 —— P1 生信服务地基（bioflow-service 8098 + BFF 最小反代）

前置必读

1. docs/bioflow_team_context.md（环境事实 + 团队纪律，全部遵守）
2. 本任务书 + 模块职责边界
3. docs/PRD.md §16（FR-BIO-028 独立服务 / FR-BIO-031 并发与恢复）、实施计划 §六（端点与三表清单）

职责范围（新增 bioflow_service/ 独立部署树；BFF 仅两处最小改动）

A. bioflow_service/ 部署树（仓库 /home/xzq/5090/teamWorkspace/zh/PlantAI-rag-new/bioflow_service/）：

• app/config.py —— 配置键：BIOFLOW_IMAGE_MAP（镜像名映射，含 stage_image_map.json 路径）、BIOFLOW_DATA_ROOT、BIOFLOW_CONCURRENCY=3、BIOFLOW_JOBS_DIR、BIOFLOW_DB_PATH、DOCGEN_LLM_*（沿用 docgen 直连模式）、BIOFLOW_SERVICE_URL
• app/schemas.py —— pydantic 请求/响应模型（明文白名单文件，同 rag-new 规则）
• app/db.py —— 独立 SQLite bioflow.db 三张表 + 幂等迁移（沿用 docgen 同款模式）：bio_jobs（id/会话/标题/状态/阶段链 JSON/参数 JSON/档案 id/时间戳）、bio_stages（任务/阶段/状态/参数 JSON/manifest 路径/日志尾/起止）、bio_archives（id/任务 id/名称/需求摘要/阶段链+参数 JSON/报告制品 id/磁盘路径/大小/时间）
• app/services/bioflow/（全部 dataclass/dict/stdlib，禁 pydantic——Cython 编译纪律）：
  • kernel.py —— Docker 执行器：按阶段→镜像映射表拼装 docker run --rm --user xzq uid -v 任务目录 -v BIOFLOW_DATA（只读）-e BBA_* --cpus/--memory，容器内 python -B -m cli.run_{stage}；超时/日志截取；命令拼装可 mock 断言
  • catalog.py —— 阶段目录（从 gfa_core/mas/stage_catalog.py 移植定义 + 基因家族链约 18 阶段手写参数 schema YAML；参数 help 文案从入口 argparse 提取）；不用运行时反射
  • manifests.py —— manifest 解析与校验（schema 随内核树）；跨阶段输入定位（上游 manifest 的 artifacts 路径）
  • runner.py —— 任务状态机（逐阶段：检查输入→等待确认→docker run→读 manifest 判成败→推进/暂停）；事件总线（进程内 pub/sub 供 SSE）；并发信号量（BIOFLOW_CONCURRENCY 默认 3）；服务重启恢复（扫 DB 恢复 in-flight 续跑，不重跑已完成阶段）
  • planner.py —— 路径规划（知识库检索 + LLM 生成候选路径→catalog 硬校验，未知阶段拒绝，前置补全明示）
  • reports.py —— 报告登记（内核报告产物→docgen 报告登记端点协调，接口先以内部 HTTP 调 BFF 反代端点预留）
  • archive.py —— 存档/复用（过程记录/中间文件/结果文件/报告打包落盘；名称匹配复用）
  • llm.py —— LLM 调用（沿用 docgen deepseek 直连模式）
  • params.py —— 参数预填（BBA_* 历史/契约文档→表单默认值）
• app/routers/bioflow.py、biojobs.py、bioarchives.py —— 端点按实施计划 §六清单实现（chat/stream SSE 入口、catalog、jobs 全套、files 上传（multipart 流式，大文件超时单独调大）、stages confirm/rerun/skip、pause/resume、manifest+日志尾 80 行、events SSE（事件类型全清单）、report revise、archives 全套）
• app/main.py —— FastAPI 组装；health 端点（/api/bioflow/health，前端探活用）
• build.sh —— 复制 tooling/compile/compile_sdk.sh 改白名单（明文：main.py/config.py/schemas.py/db.py + __init__.py 规则）；restart.sh
• tests/ —— pytest（-m bioflow_unit）：runner 状态机全路径（成功/失败/重跑/跳过/暂停/恢复/重启续跑/超时/日志截断/并发上限，mock docker 执行）、manifest 解析、三表迁移幂等、错误信封；端点用例（-m bioflow_api，respx/mock LLM+vstore+docker） B. BFF 两处最小改动：

1. 新增 sdk/app/routers/bioflow_proxy.py —— 流式反代 /api/bioflow/* → BIOFLOW_SERVICE_URL（SSE 不缓冲透传）；报告登记端点（生信报告→doc_artifacts，字段与 docgen 现有表对齐，协调 A3 的 report 模板）；BIOFLOW_ENABLED 为假时路由不注册
2. sdk/app/main.py —— 注册该路由 2 行（按 BIOFLOW_ENABLED 开关）
3. sdk/app/config.py —— 加 BIOFLOW_ENABLED（默认 false）、BIOFLOW_SERVICE_URL 两键

【跨模块契约】

• 阶段→镜像映射表由 A1 产出（bioflow_kernel/stage_image_map.json），kernel.py 读取之，A1 未交付前可用占位表跑通单测
• 报告登记与 A3 的 report 模板/fi图渲染协作：登记接口字段约定（job_id/标题/md/图清单），写入报告交 TL 转达 A3
• 事件类型清单照实施计划 §六（job_created/plan_ready/stage_started/stage_log/stage_done/stage_failed/stage_skipped/stage_await_confirm/stage_await_files/job_done/job_paused/job_archived）

【纪律再强调】

• 不碰生产服务；服务层禁 pydantic；不 commit/push；发现需改任务书外文件 → 报告交 TL
• 端点/字段名与本任务书不一致时以实施计划 §六为准；不确定处记入报告

【自测要求】

• cd bioflow_service && /home/xzq/5090/teamWorkspace/zh/plantai-rag-new-venv/bin/python -m pytest tests/ -q（mock docker/LLM/vstore，不依赖生产服务）
• 自测结果写入 docs/team/report_bioflow_dev2.md（模块清单、用例数与通过数、已知限制）

【完成标准】

报告写入后，最终回复明确写「BIOFLOW DEV2 P1 完成」+ 报告路径 + 自测通过数

【P6 对接补充（2026-09-05 TL 追加，A4 已交付）】

planner.py 的知识库检索对接 vstore/flow.py 的 FlowStore 本地实例（不是 8094 HTTP API）：

• flow_docs 集合：vstore/data/flow_docs/（index.json + chunks/*.json 明文）；块字段约定见 docs/team/report_bioflow_dev4.md §5（source 三源 corpus|stage_contract|skill、title_path、heading、stage_name、cite{anchor,line}、keywords 二档检索等）
• 检索方式：FlowStore.search 混合检索（向量+词面双通道）；对话咨询引用块携带 cite 字段供前端跳转（跳转渲染由 A3 对接）
• 生产入库：vstore/scripts/ingest_flow_docs.py（幂等可重跑）；语料 106 文件/724 块已切好