PlantAI-rag-new/docs/EXTENSION_CONTRACT.md

扩展分析契约文档(Dev-A/B/C 与测试 agent 对齐基线)

生成 2026-09-12,方案见 docs/DEPLOY_SKILL.md 同源的扩展分析方案。三个开发分支与本契约对齐,测试 agent 按本契约+计划文档验收。

1. 扩展资产目录布局(服务端存储)

{BIOFLOW_DATA}/extensions/{ext_id}/
├── extension.json          # 唯一事实源(schema 见 §2)
├── raw_code/               # 上传 zip 解压的原始代码(含 run.sh 等)
├── raw_test_data/          # 上传的测试数据(可选)
├── converted_code/         # AI 转换后写入的代码(与 raw_code 相同或改写版)
├── validation/             # 试运行/金标/修复循环中间产物
│   ├── trial_{n}.log
│   ├── trial_{n}.outputs/
│   └── golden_report.json
└── runs/{run_id}/          # 每次正式运行
    ├── inputs/             # 运行输入(路径登记或复制的文件)
    ├── outputs/            # 运行输出(输出契约校验对象)
    ├── run.log
    └── run_result.json     # {run_id, ext_id, exit_code, started_at, finished_at, outputs: [...], error}

2. extension.json schema(唯一事实源)

{
  "schema_version": "extension_stage_v1",
  "ext_id": "ext_xxxxxxxx",
  "display_name": "测序质量统计",
  "status": "draft|building|built|trial_running|trial_passed|trial_failed|validating|validated|repairing|confirming|published|build_failed",
  "command_template": "python {code_dir}/quality_stats.py --fastq {input_file} --out {output_dir}",
  "original_command": "python quality_stats.py --fastq input.fastq --out results/",
  "runtime_image": "bioflow-gf",
  "requirements": { "pip": [], "apt": [] },
  "parameters": [ { "name": "fastq", "type": "file", "required": true, "description": "..." } ],
  "input_roles": { "input_file": "fastq" },
  "nl_triggers": ["质量统计", "fastq 统计"],
  "analysis_type": "table_filter",
  "golden": { "test_input": "sample.fastq", "expected_outputs": ["..."] } | null,
  "repair_count": 0,
  "created_at": "...", "updated_at": "..."
}

占位符白名单(spec_v2 移植):{code_dir} {input_dir} {input_file} {input_hmm} {input_fasta} {input_query_fasta} {input_reference_fasta} {input_pep_fasta} {input_cds_fasta} {input_id_file} {output_dir} {work_dir} + {param_<name>}。硬约束:{output_dir} 必含;白名单外占位符拒绝。

3. docker 执行契约(Dev-B 负责实现)

宿主挂载入口 bioflow_kernel/cli/run_extension.py,命令形态:

docker run --rm --user <uid> \
  -v <ext_dir>:/job/ext:ro \
  -v <input_dir>:/job/input \
  -v <output_dir>:/job/output \
  -v <宿主 bioflow_kernel/cli>:/opt/bioflow-entry:ro \
  --cpus <白名单> --memory <白名单> \
  <image>:dev python -B /opt/bioflow-entry/run_extension.py \
  --ext-dir /job/ext --input-dir /job/input --output-dir /job/output [--param name=value ...]

run_extension.py 职责:读 /job/ext/extension.json → 渲染 command_template(code_dir=/job/ext/converted_code)→ subprocess 执行 → 日志/退出码返回 → 输出契约校验(输出目录非空,否则退出码 3)。8 个 base 镜像与自动生成镜像零改动。

4. 事件帧契约(chat/stream 扩展分支下发,Dev-C 消费)

帧 = {event, data},事件集:

event	data 关键字段	触发
extension_upload	{session_ext_id}	创建意图命中 → 上传引导卡
extension_created	{ext_id, display_name, status:"draft"}	上传完成
extension_build	{ext_id, command_template, requirements, runtime_image, nl_triggers, analysis_type, parameters, status}	AI 转换完成 → 转换卡
extension_trial	{ext_id, status:"running"|"done"|"failed", log_tail, exit_code, error}	试运行状态/结果
extension_repair	{ext_id, repair_count, suggestion, status}	修复循环
extension_validate	{ext_id, golden: {...}|null, form_defaults}	金标/确认卡
extension_published	{ext_id, display_name, nl_triggers}	发布完成
extension_candidates	{candidates: [{ext_id, display_name, purpose}]}	多命中候选卡
extension_confirm	{ext_id, params_schema, extracted_params, files_required}	运行前参数确认卡
extension_run_started	{run_id, ext_id}	运行开始
extension_run_log	{run_id, log}	运行日志追加
extension_run_done	{run_id, outputs}	运行完成
extension_run_failed	{run_id, exit_code, error, log_tail}	运行失败

5. 意图两层判定(Dev-A 负责,intent.py 扩展)

• A 层创建:动作词{创建,建,新建,上传,自定义,写,弄,做一个} × 目标词{扩展,拓展分析,分析模板,分析脚本,分析工具},同句命中即进创建流程。
• B 层运行:已发布扩展打分 = display_name 模糊 + nl_triggers 关键词 + analysis_type;动作词{帮我跑,用,做一下,分析一下}加分。仅 published 可被触发。
• 歧义消解:目标词命中但无动作词 → 有 B 层命中走运行;无命中回「没有匹配的已发布扩展,是否创建?」引导卡。
• 漏判安全:无命中且非创建 → 回落正常生信阶段规划,现网零影响。

6. 端点清单(Dev-A 实现,Dev-C 调用)

POST   /api/bioflow/extensions                      (multipart: code_zip 归档[zip/tar/tar.gz,服务端魔数解压] 或 code_files 多文件[目录直传,filename=相对路径] + display_name + command + runtime_image? + golden?[JSON 字符串] + test_file?[金标数据文件])
                                                    上传内容结构自适应分类:raw_code|code|scripts → 代码;raw_test_data|test_data|data → 数据;
                                                    散落文件按运行命令解析入口 + 扩展名模式分类,未知扩展名归代码;纯数据包 422,纯脚本包合法
GET    /api/bioflow/extensions                      (列表,published 优先)
GET    /api/bioflow/extensions/{id}
DELETE /api/bioflow/extensions/{id}
POST   /api/bioflow/extensions/{id}/build           (AI 转换)
POST   /api/bioflow/extensions/{id}/trial-run       (test_inputs 文件)
POST   /api/bioflow/extensions/{id}/repair          (LLM 修复,上限 20 轮可配)
POST   /api/bioflow/extensions/{id}/publish
POST   /api/bioflow/extensions/{id}/run             (params + files → run_id)
GET    /api/bioflow/extensions/{id}/runs
GET    /api/bioflow/extensions/{id}/runs/{run_id}/events   (SSE,首帧快照)

7. 约束(全部 agent)

• 代码仅限 175 仓库 /home/xzq/5090/teamWorkspace/zh/PlantAI-rag-new(worktree 副本)。
• 不 push、不部署 176、不动生产部署树;dev 栈不得重启生产服务。
• 依赖安装:服务端零新增依赖(纯 stdlib+现有 httpx/pydantic/fastapi);镜像内依赖走自动镜像生成(Dev-B)。
• 现有 bioflow 路径零改动:kernel.py/runner.py/planner.py/catalog.py/stage_image_map.json 一律不碰(扩展是并行链路)。