ai4s-dry-lab

name	ai4s-dry-lab
description	AI4S 端到端干实验自动化研究引擎。自启动检查+追溯入职(半路加入也能补齐历史)+强制Worklog(W1)+输出目录README(W2)+强制文献验证(W3)+强制脚本日志(W4)+分层记忆注入+SPEC驱动+OODA循环+Gate门控。适用于scRNA-seq/空间转录组/跨物种比较等计算生物学项目。
version	2.2.0

AI4S Dry Lab — 端到端干实验自动化研究引擎

设计哲学

本 skill 从计算生物学项目实践中提炼而成。核心设计原则：

1. SPEC 驱动：研究方案是北极星，所有分析可追溯到 SPEC 目标
2. Worklog 追溯：每一步操作都有记录
3. OODA 循环：Observe-Orient-Decide-Act 假设驱动闭环
4. Gate Control：线性门控验证交付物完整性
5. Human-in-the-loop：关键决策必须与研究者确认
6. 【强制】实验记录不可跳过 — 任何改动、测试、运行必须先写 WORKLOG
7. 【强制】输出目录必须带解释文档 — 每个结果目录含 README_文件说明.md，逐图逐表引用代码解释
8. 【强制】文献验证不可跳过 (W3) — 每个关键结果必须有文献支撑，WORKLOG 和 README 必须包含文献检索记录

适用场景：scRNA-seq、空间转录组、多组学、跨物种比较、论文级可视化。 不适用于：湿实验设计、临床数据分析、非生物学领域。

---

自启动协议 (Auto-Bootstrap Protocol)

v2.1 核心能力：skill 激活时自动检查任务容器套件，有则改之无则加勉，保证任何时候都能进入工作状态。 即使半路出家加入已有项目，也能扫描理解全部历史工作，反向填充所有容器文档。

任务容器套件（5 个核心文件 + 硬件配置）

#	文件	作用	缺失时动作
0	HARDWARE_CONFIG.md	硬件资源限制（防止资源耗尽）	自动探测系统硬件 → 生成
1	docs/SPEC-experiment.md	研究方案（北极星）	新项目→从模板创建；已有项目→追溯构建
2	docs/WORKLOG.md	实验记录（W1 强制）	新项目→从模板创建；已有项目→反向填充
3	docs/STATE.md	状态检查点（记忆锚点）	始终创建，从项目实际状态生成
4	docs/SPEC-visualization.md	可视化方案	从模板创建（可后续填充）
5	data/raw/DATA_MANIFEST.md	数据清单	从模板创建

硬件感知协议 (Hardware Awareness Protocol) — Advisory 模式

自动探测硬件、生成 HARDWARE_CONFIG.md、警告资源超限，但不阻塞执行。 探测内容：CPU cores, RAM, GPU, max_workers, future.globals.maxSize。 所有分析脚本开头应读取此配置，不要直接使用 detectCores()。

激活时自动检测流程

/ai4s-lab 激活
  │
  ├─ 0. 【硬件感知检查】(Hardware Awareness Check) — Advisory 模式
  │     ├─ 检查项目根目录是否存在 HARDWARE_CONFIG.md
  │     ├─ 存在 → 读取配置（CPU cores, RAM, GPU, max_workers, future_globals_maxSize）
  │     ├─ 不存在 → 探测系统硬件 → 自动生成 HARDWARE_CONFIG.md
  │     ├─ 将硬件限制写入 STATE.md 的 Hardware 段供后续脚本参考
  │     └─ 若后续脚本请求资源超过配置限制 → 输出 ⚠️ WARNING（不阻塞执行）
  │
  ├─ 1. 读取 docs/STATE.md
  │     ├─ 存在 → 恢复上下文（Phase/Step/OODA位置）→ 跳到第4步
  │     └─ 不存在 → 继续
  │
  ├─ 2. 检测项目状态
  │     ├─ 项目为空（无脚本无输出）→ 全新项目初始化
  │     └─ 项目非空（有脚本/有输出）→ 触发追溯入职协议
  │
  ├─ 3. 追溯入职协议 (Retroactive Onboarding)
  │     ├─ 扫描项目结构 → 识别脚本/输出/数据
  │     ├─ 读取每个脚本 → 理解功能、输入输出映射
  │     ├─ 反向构建 SPEC（从代码推导研究目标和Phase划分）
  │     ├─ 反向填充 WORKLOG（为每个已有脚本生成记录条目）
  │     ├─ 为每个输出目录生成 README_文件说明.md
  │     ├─ 生成 STATE.md（当前研究边界快照）
  │     └─ 呈现摘要给研究者确认 → 确认后进入正常循环
  │
  └─ 4. 进入正常 OODA 循环
        ├─ 读取 SPEC 目标 → 知道要做什么
        ├─ 读取 STATE 位置 → 知道从哪里继续
        ├─ 读取 WORKLOG 尾部 → 知道最近做了什么
        └─ 开始下一轮 Observe → Orient → Decide → Act

追溯入职协议详细步骤

详见 references/onboard-protocol.md。核心流程：

1. 结构扫描 — 识别项目类型、脚本数量、输出数量
2. 代码溯源 — 逐脚本读取，提取功能/输入/输出/参数
3. 反向构建 SPEC — 从脚本编号推断 Phase，从功能推断目标
4. 反向填充 WORKLOG — 为每个脚本生成 [追溯记录] 条目
5. 生成输出 README — 为每个结果目录从代码逆向生成解释
6. 生成 STATE.md — 当前位置快照 + 待办清单
7. 研究者确认 — 确认后进入正常 OODA

---

分层记忆架构 (Layered Memory Architecture)

解决长链路问题：科研任务跨越多轮对话/context 压缩，通过分层设计保证核心规则和状态永不丢失。

四层指令架构

┌─────────────────────────────────────────────────┐
│ Layer 1: CLAUDE.md (永驻，不参与压缩)             │
│ → 3-5 条硬规则，永远在上下文中                      │
│ → "你在执行 ai4s-dry-lab，读 STATE.md 恢复上下文"  │
├─────────────────────────────────────────────────┤
│ Layer 2: docs/STATE.md (每次激活读取)              │
│ → 轻量状态快照 (≤50行)                            │
│ → Phase/Step/OODA 位置 + 待办清单 + 规则提醒       │
├─────────────────────────────────────────────────┤
│ Layer 3: docs/WORKLOG.md 尾部 (按需读取)           │
│ → 最近 3-5 个 Step 的详细记录                      │
│ → 验证 STATE 准确性 + 恢复近期上下文               │
├─────────────────────────────────────────────────┤
│ Layer 4: SKILL.md (子命令触发时加载)               │
│ → 完整工作流、Gate 规则、模板引用                   │
│ → 仅在 /ai4s-lab 调用时加载，不常驻                 │
└─────────────────────────────────────────────────┘

每层职责

层	文件	何时加载	加载量	丢失风险
L1	CLAUDE.md	始终	~5 行	几乎不丢失
L2	STATE.md	每次 skill 激活	~30 行	不丢失（文件持久）
L3	WORKLOG 尾部	每次激活	~50 行	不丢失（文件持久）
L4	SKILL.md	/ai4s-lab 调用时	~400 行	context 压缩时可能丢失

状态维护规则

• OODA Act 后 → 更新 STATE.md（当前位置 + 待办）
• 新 Phase 开始 → 更新 STATE.md（Phase 完成度表）
• 每次 /ai4s-lab 调用 → 先读 STATE.md → 读 WORKLOG 尾部 → 确认一致性
• STATE 与 WORKLOG 不一致 → 以 WORKLOG 为准，修正 STATE

CLAUDE.md 推荐注入内容

在项目 CLAUDE.md 中加入以下内容（~5行），保证核心规则永驻：

## AI4S Dry Lab 规则
1. 你在执行 ai4s-dry-lab 框架，每次开始先读 docs/STATE.md 恢复上下文
2. W1: 每次操作（运行/修改/测试）前必须写 docs/WORKLOG.md
3. W2: 每次产生输出文件后必须更新对应目录的 README_文件说明.md
4. W4: 每个分析脚本必须输出同名 .log 到结果目录（含版本+验证+计时）
5. 每 Phase 完成后运行 Gate Check

---

不可妥协规则（Inviolable Rules）

规则-1: 强制实验记录（W1 — Mandatory Worklog）

在本框架内，任何操作必须有 WORKLOG 条目，无一例外。

覆盖范围（全部必须记录）：

• 运行分析脚本（含成功/失败/部分完成）
• 修改脚本参数或代码
• 新增分析脚本
• 数据格式转换/预处理
• 可视化生成/修改
• 依赖安装/环境配置
• Bug 修复和调试
• 与研究者讨论后的方案调整
• Gate Check 结果

执行时机：

• 脚本运行前 → 先写 "Observe" 条目
• 脚本运行后 → 立即追加结果
• 任何改动前 → 先记录 "为什么改"

最小记录格式：

### Step XXa: [操作描述]
- **方法**: [具体做了什么]
- **输入**: [文件路径]
- **输出**: [文件路径]
- **代码位置**: [脚本:行号]
- **OODA 状态**: Observe | Orient | Decide | Act

规则-2: 输出目录解释文档（W2 — Mandatory Output README）

每个包含分析结果的目录必须包含 README_文件说明.md。

覆盖范围：包含 PDF/PNG/CSV/TSV/H5AD/RDS 的任何目录。

README 必须包含：

1. 头部信息：生成脚本名、分析方法、关键参数
2. 每个图形文件：数据源、生成逻辑（X/Y轴含义、颜色编码）、读图方法、关键发现
3. 每个数据文件：列定义、数据来源、计算逻辑、用途
4. 注意事项：版本修正、已知局限、与其他 Figure 的关联
5. 参考文献：关键发现的文献支撑（PMID/DOI）

核心要求：解释必须溯源到生成代码 — 禁止凭空编造，每条解读需有代码行支撑。

规则-2b: 强制脚本日志（W4 — Mandatory Script Log）

每个分析脚本运行时必须输出同名 .log 文件到结果目录。

W1-W3 管的是 Agent 层面的文档纪律（AI写日志、AI写README、AI做文献验证）。W4 管的是脚本层面的自动化质量控制（代码自己输出日志、自己做输入验证、自动记录环境版本）。两层互补：W1-W3 保证"人/AI知道自己做了什么"，W4 保证"机器能证明自己做了什么、做对了"。

日志输出模板：

R 脚本：

.LOG_FILE <- "results/[分析目录]/[脚本名].log"
.LOG_START <- Sys.time()
.log <- function(msg) {
  ts <- format(Sys.time(), "%Y-%m-%d %H:%M:%S")
  line <- paste0("[", ts, "] ", msg)
  cat(line, "\n")
  cat(line, "\n", file = .LOG_FILE, append = TRUE)
}
cat(paste0("=== [分析名] Log ===\nStarted: ", .LOG_START, "\n"), file = .LOG_FILE)

Python 脚本：

import logging
LOG_FILE = os.path.join(OUTPUT_DIR, "[脚本名].log")
logging.basicConfig(level=logging.INFO, format='[%(asctime)s] %(message)s',
    datefmt='%Y-%m-%d %H:%M:%S',
    handlers=[logging.FileHandler(LOG_FILE, mode='w', encoding='utf-8'),
              logging.StreamHandler(sys.stdout)])
log = logging.getLogger(__name__)

.log 文件必须包含：

1. 执行开始时间戳
2. 关键包版本（R: packageVersion()；Python: package.__version__）
3. 输入文件存在性验证（R: stopifnot(file.exists())；Python: os.path.exists()）
4. 关键基因/特征的存在性检查（Gate check at data level）
5. 每个主要分析步骤的日志记录
6. 输出文件保存确认
7. 执行完成时间戳 + 总耗时

输入验证要求：

• 脚本运行前必须验证所有输入文件存在
• 验证失败时必须 stop() / sys.exit() 并输出明确错误信息
• 关键基因/特征在数据中存在性检查：
  • 缺失时记录 WARNING 到 .log，不静默跳过
  • 对于核心marker基因缺失，应 stop() 终止脚本

目录规范更新：

results/[分析子目录]/
├── [图/表/数据文件]
├── [脚本名].log          ← W4: 脚本同名日志
└── README_文件说明.md

规则-3: 强制文献验证（W3 — Mandatory Literature Verification）

在本框架内，每个关键结果必须有文献支撑，WORKLOG 和 README 必须包含文献检索记录。

学术研究的核心逻辑：

• 实验 → 发现结果 → 文献验证 → 结果解释 → 进一步实验
• 没有文献支撑的结果是孤立的，无法纳入学术叙事
• 文献验证是连接"数据"与"故事"的桥梁

覆盖范围：

• 每个关键发现（如：TC 是通讯枢纽、MP 极化轨迹、LR 对差异）
• 每个生物学结论（如：WNT 通路排他性、趋化因子富集）
• 每个方法选择（如：Slingshot 替代 Monocle3、CellCall 参数）
• 每个意外发现或矛盾结果

执行时机：

• Orient 阶段：必须进行文献检索，验证结果与已有知识的一致性
• WORKLOG 记录时：必须包含文献检索结果（PMID/DOI 或"待验证"）
• README 撰写时：必须包含参考文献列表和验证结论

最小记录格式：

### Step XXa: [操作描述]
- **方法**: [具体做了什么]
- **输入**: [文件路径]
- **输出**: [文件路径]
- **关键结果**: [数字/结论]
- **文献验证**:
  - 检索关键词: [PubMed/OpenAlex 检索词]
  - 找到文献: [PMID/DOI] 或 "未找到直接文献"
  - 验证结论: [一致/部分一致/矛盾]
  - 解释依据: [文献内容摘要]
- **OODA 状态**: Observe | Orient | Decide | Act

文献检索工具：

• PubMed MCP: 用于检索生物医学文献
• OpenAlex MCP: 用于检索学术论文和引用
• WebSearch: 用于补充检索和最新研究

验证决策树：

结果与文献一致？
├── 是 → 标记"文献验证通过" → 记录 PMID/DOI → 进入 Decide
├── 部分一致 → 标记"部分验证" → 提出修正假设 → 与研究者讨论
├── 矛盾 → 触发 OODA 回退 → 重新 Observe → 检查方法/数据
└── 无直接文献 → 标记"新颖发现" → 需要研究者确认 → 考虑是否需要补充实验

Gate Check 规则：

• W3 失败 → 阻塞，不允许继续下一 Phase
• 每个 Figure 的 README 必须包含参考文献列表
• 每个 WORKLOG 条目必须有"文献验证"字段

文献调研深度标准 (L1/L2/L3)：

级别	处理方式	适用场景	工具
L1: 摘要级	读摘要 + 结论	验证一致性、背景补充、方法确认	PubMed MCP (get_details)
L2: 关键段落	读摘要 + 方法 + 结果	方法学细节、关键发现验证	OpenAlex MCP (get_fulltext_sections)
L3: 全文精读	下载全文 + 精读	核心文献、争议结论、方法复现	PubMed/OpenAlex download_fulltext

文献深度判定决策树：

文献相关性评估
│
├── 是否直接支撑核心论点？
│   ├── 是 → L3 全文精读
│   └── 否 → 继续评估
│
├── 是否涉及方法学细节？
│   ├── 是（需要复现/比较）→ L2 关键段落
│   └── 否 → 继续评估
│
├── 是否验证已有知识？
│   ├── 是（一致性检查）→ L1 摘要级
│   └── 否（矛盾/新颖）→ L2 或 L3
│
└── 默认 → L1 摘要级

与 deep-research 联动机制：

触发条件	门控标准	执行策略
矛盾结果	Orient 阶段发现与文献不一致	调用 deep-research 系统性调研
新颖发现	无直接文献支撑	调用 deep-research 确认是否已有报道
方法选择	需要全面比较不同方法	调用 deep-research 方法学综述
跨领域	需要跨学科文献支持	调用 deep-research 跨领域检索
研究者要求	明确要求深度调研	调用 deep-research

deep-research 调用判定流程：

OODA Orient 阶段
│
├── 1. 快速文献检索 (L1)
│   └── 使用 PubMed/OpenAlex MCP 检索关键词
│
├── 2. 结果评估
│   ├── 找到直接支撑文献 → 记录 PMID → 继续
│   ├── 找到部分一致文献 → 标记"部分验证" → 继续
│   ├── 找到矛盾文献 → 触发 deep-research
│   └── 未找到文献 → 触发 deep-research
│
├── 3. 深度调研判定
│   ├── 是否需要系统性综述？ → 是 → 调用 deep-research
│   ├── 是否需要方法学比较？ → 是 → 调用 deep-research
│   ├── 是否需要跨领域支持？ → 是 → 调用 deep-research
│   └── 否 → 使用 L1/L2 级别处理
│
└── 4. 记录决策
    └── 在 WORKLOG 中记录调研深度和决策理由

deep-research 调用格式：

/deep-research "[研究主题]"
目标: [具体调研目标]
背景: [当前结果和需要验证的内容]
预期产出: [文献列表/综述/方法比较]

---

OODA 循环引擎（含强制记录点）

Observe（观察）

1. [WORKLOG] 写入 "Observe" 条目（脚本路径、预期目标）
2. 执行分析脚本
3. 收集统计数据，生成初步可视化
4. [WORKLOG] 追加执行结果
5. [README] 为新输出目录创建 README_文件说明.md
6. 可并行 spawn Explore Agent 检查输出

Orient（定向）

1. 将结果与 SPEC 目标对比
2. 【强制 W3】通过 PubMed/OpenAlex MCP 检索文献
   • 检索关键词：基于结果中的生物学概念（如"Telocyte communication", "macrophage polarization", "WNT signaling fascia"）
   • 检索目标：验证结果与已有知识的一致性
   • 记录要求：PMID/DOI 或"未找到直接文献"
3. 检查结果与生物学知识一致性
4. 识别意外发现或矛盾
5. [WORKLOG] 写入 "Orient" 条目（含文献对比结论）
6. [README] 为每个关键发现添加参考文献

文献验证流程：

1. 提取关键发现中的生物学概念
2. 使用 PubMed MCP 检索相关文献
3. 使用 OpenAlex MCP 补充检索
4. 阅读摘要/全文，验证结果一致性
5. 记录验证结论到 WORKLOG
6. 将参考文献添加到 README

文献验证决策树：

结果与文献一致？
├── 是 → 标记"文献验证通过" → 记录 PMID/DOI → 进入 Decide
├── 部分一致 → 标记"部分验证" → 提出修正假设 → 与研究者讨论
├── 矛盾 → 触发 OODA 回退 → 重新 Observe → 检查方法/数据
└── 无直接文献 → 标记"新颖发现" → 需要研究者确认

Decide（决策）

1. 基于证据决定：继续推进 / 修正参数 / 回退重做 / 新发现标记
2. 必须与研究者确认（Human-in-the-loop）
3. [WORKLOG] 写入 "Decide" 条目（含决策理由）

Human-in-the-loop 关键节点：

• Phase 切换时
• 发现与预期不符时
• 需要追加分析时
• 可视化方案讨论时

Act（行动）

1. 执行决策（运行脚本 / 修改参数 / 追加分析）
2. [WORKLOG] 写入 "Act" 条目
3. [README] 为新增/变更输出更新 README_文件说明.md
4. 运行 Gate Check（含 W1/W2 检查）
5. 自动进入下一个 OODA 循环

---

核心产出物

文本1：实验方案 SPEC（docs/SPEC-experiment.md）

定义：研究背景与目标(G1-Gn) → ADR → Phase 划分 → 数据流图 → 参数常量

文本2：实验记录 Worklog（docs/WORKLOG.md）

每步记录格式：

### Step XXa: [脚本名]
- **方法**: [算法/工具/参数]
- **输入**: [文件路径 + 大小/行数]
- **输出**: [文件路径 + 大小/行数]
- **关键结果**: [数字/结论]
- **代码位置**: `scripts/XXa_xxx.py:行号`
- **SPEC 关联**: G{n} → ADR-{m}
- **OODA 状态**: Observe | Orient | Decide | Act
- **文献验证**:
  - 检索关键词: [PubMed/OpenAlex 检索词]
  - 找到文献: [PMID/DOI] 或 "未找到直接文献"
  - 验证结论: [一致/部分一致/矛盾/新颖发现]
  - 解释依据: [文献内容摘要，1-2 句话]

文本3：可视化方案 SPEC（docs/SPEC-visualization.md）

定义：Figure 编号 → Panel 布局 → 设计系统 → 数据源映射 → Results 对应

门控：Gate Check

验证 SPEC + DATA_MANIFEST + 分析脚本 + 输出数据 + Worklog + 可视化 + W1/W2 规则

---

项目目录规范

{project_root}/
├── docs/
│   ├── SPEC-experiment.md
│   ├── SPEC-visualization.md
│   ├── STATE.md                     ← v2.1 新增：状态检查点
│   └── WORKLOG.md
├── data/
│   ├── raw/DATA_MANIFEST.md
│   └── processed/
├── scripts/
├── results/ (或 output/)
│   ├── [分析子目录]/
│   │   ├── [图/表/数据文件]
│   │   └── README_文件说明.md      ← 每个输出子目录必须
│   └── ...
└── .venv/

---

Gate Check 门控系统

规则	类型	检查内容
W1	强制	每个 Step 有 WORKLOG 条目
W2	强制	每个输出目录含 README_文件说明.md 且覆盖所有文件
W3	强制	每个关键结果有文献验证记录（WORKLOG 和 README 中）
W4	强制	每个分析脚本输出同名 .log 到结果目录（含版本+验证+计时）
G1	标准	SPEC 存在且完整
G2	标准	DATA_MANIFEST 存在
G3	标准	分析脚本存在
G4	标准	输出数据存在
G5	标准	Worklog 覆盖所有 Phase
G6	标准	可视化与 SPEC-visualization 一致
G7	标准	最终报告包含所有 Figure
G8	标准	参考文献列表完整（每个 Figure 至少 1 篇支撑文献）
G9	标准	每个 Phase 的结果目录含对应 .log 文件，时间戳一致

W1/W2/W3/W4 失败 → 阻塞，不允许继续下一 Phase。

---

多 Skill 联动框架（学术研究-论文发表完整工作流）

核心理念：ai4s 作为主引擎，通过门控逻辑调度其他专业 skill，实现"一个脚手架拿出，agent 自动联动"。

联动架构图

ai4s-dry-lab (主引擎)
    │
    ├── Observe/Act 阶段（数据分析）
    │   ├── scRNA-seq 任务 → /scrna-bindlab-full-workflow (全流程自动化)
    │   │   └── Phase 4 细胞注释 → /scrna-celltype-annotation (AI 文献注释)
    │   └── 其他分析 → 原有流程
    │
    ├── Orient 阶段（文献验证）
    │   ├── L1 快速验证 → PubMed/OpenAlex MCP
    │   ├── L2 关键段落 → /paper-reader
    │   └── L3 深度调研 → /deep-research
    │
    ├── Report 阶段（论文产出）
    │   ├── 图表叙事 → /midas
    │   ├── 中文论文 → /thesis-writing-mentor
    │   └── 英文论文 → 直接撰写
    │
    └── Submit 阶段（投稿执行）
        ├── 选刊 → /sci-journal-submission-expert
        ├── 投稿 → /paper-submission-manager
        └── 审稿回复 → /sci-journal-submission-expert

联动 Skill 清单

Skill	角色	调用阶段	门控条件
/paper-reader	文献精读	Orient	L1 验证需要深入阅读
/deep-research	深度调研	Orient	矛盾结果/新颖发现/跨领域
/scrna-bindlab-full-workflow	scRNA全流程	Observe/Act	检测到scRNA-seq任务（CellRanger输出/10X数据/Seurat对象）
/scrna-celltype-annotation	细胞注释	Observe	scRNA-seq 亚群注释（由 scrna-bindlab-full-workflow Phase 4 自动调用）
/midas	论文叙事	Report	图表完成，需要生成叙事
/thesis-writing-mentor	中文论文	Report	学位论文撰写
/sci-journal-submission-expert	投稿专家	Submit	选刊/审稿回复
/paper-submission-manager	投稿管理	Submit	最终投递
/pubmed-linker	文献链接	Report	参考文献整理

scRNA-seq 任务自动调度逻辑

任务检测（Observe 阶段初始化时）
    │
    ├── 检测到 scRNA-seq 数据/任务？
    │   判定条件（满足任一即触发）:
    │   ├─ 项目含 CellRanger 输出目录 (filtered_feature_bc_matrix/)
    │   ├─ 项目含 10X .h5 文件
    │   ├─ 项目含 Seurat .rds 对象
    │   ├─ SPEC 中包含 scRNA-seq 相关目标
    │   └─ 用户明确指定单细胞分析任务
    │
    ├── 是 → 自动调用 /scrna-bindlab-full-workflow
    │   ├─ 继承当前 ai4s-dry-lab 的 W1-W4 规则
    │   ├─ 每个 Phase = 一轮 OODA 循环
    │   ├─ Phase 4 内部自动调用 /scrna-celltype-annotation
    │   └─ 完成后返回 ai4s-dry-lab 主循环
    │
    └── 否 → 原有分析流程

门控逻辑详细设计

Orient 阶段门控

Orient 开始
    │
    ├── 1. L1 快速验证 (PubMed/OpenAlex MCP)
    │   ├── 找到直接文献 → 记录 PMID → 继续
    │   ├── 找到部分一致 → 标记"部分验证" → 继续
    │   ├── 找到矛盾文献 → 触发 L2/L3
    │   └── 未找到文献 → 触发 L2/L3
    │
    ├── 2. L2 关键段落判定
    │   ├── 是否涉及方法学细节？ → /paper-reader
    │   ├── 是否需要批判性分析？ → /paper-reader
    │   └── 否 → 跳过 L2
    │
    ├── 3. L3 深度调研判定
    │   ├── 是否需要系统性综述？ → /deep-research
    │   ├── 是否需要方法学比较？ → /deep-research
    │   ├── 是否需要跨领域支持？ → /deep-research
    │   ├── 是否为新颖发现（需确认是否已有报道）？ → /deep-research
    │   └── 否 → 跳过 L3
    │
    └── 4. 记录决策到 WORKLOG

Report 阶段门控

Report 开始
    │
    ├── 1. 图表完成度检查
    │   ├── 所有 Figure 已生成？ → 继续
    │   └── 否 → 回退到 Analyze 阶段
    │
    ├── 2. 论文叙事生成
    │   ├── 图表需要深度解读？ → /midas
    │   └── 否 → 直接撰写
    │
    ├── 3. 论文类型判定
    │   ├── 学位论文（中文）？ → /thesis-writing-mentor
    │   ├── SCI 论文（英文）？ → 直接撰写
    │   └── 综述论文？ → /deep-research + 撰写
    │
    └── 4. 参考文献整理
        ├── 需要更新 PubMed 链接？ → /pubmed-linker
        └── 否 → 手动整理

Submit 阶段门控

Submit 开始
    │
    ├── 1. 论文完成度检查
    │   ├── 正文 + 图表 + 参考文献完整？ → 继续
    │   └── 否 → 回退到 Report 阶段
    │
    ├── 2. 选刊
    │   ├── 需要选刊建议？ → /sci-journal-submission-expert
    │   └── 已确定期刊 → 跳过
    │
    ├── 3. 投稿准备
    │   ├── 需要投稿管理？ → /paper-submission-manager
    │   └── 否 → 手动投稿
    │
    └── 4. 审稿回复
        ├── 收到审稿意见？ → /sci-journal-submission-expert
        └── 否 → 等待

调用格式模板

/paper-reader 调用

/paper-reader "PMID: 12345678"
目标: 验证 [具体发现]
重点: [方法学/结果/结论]
产出: 精读报告 + 验证结论

/deep-research 调用

/deep-research "[研究主题]"
目标: [具体调研目标]
背景: [当前结果和需要验证的内容]
预期产出: [文献列表/综述/方法比较]

/midas 调用

/midas
图表: [Figure 编号]
数据: [关键发现]
目标: 生成论文叙事

/thesis-writing-mentor 调用

/thesis-writing-mentor "[章节名称]"
内容: [核心内容]
风格: 学位论文规范
目标: 生成符合盲审要求的章节

/sci-journal-submission-expert 调用

/sci-journal-submission-expert "[任务类型]"
论文: [论文标题/摘要]
目标: [选刊/预审/审稿回复]

联动日志记录

每次调用其他 skill 时，必须在 WORKLOG 中记录：

### Skill 联动记录
- **调用 skill**: [skill 名称]
- **调用阶段**: [Orient/Report/Submit]
- **触发条件**: [门控条件]
- **调用参数**: [参数]
- **执行结果**: [成功/失败/取消]
- **产出文件**: [如果有]

---

轻量级验证脚本

check_literature.py — 检查 WORKLOG 文献验证字段

python scripts/check_literature.py [WORKLOG_PATH]

功能：扫描 WORKLOG.md，检查每个 Step 条目是否包含"文献验证"字段。

log_skill_call.py — 记录 skill 调用历史

python scripts/log_skill_call.py log <skill_name> [parameters...]
python scripts/log_skill_call.py list [--last N]
python scripts/log_skill_call.py stats
python scripts/log_skill_call.py export [output_path]

功能：记录 skill 调用的时间、参数、结果，支持查询和导出。

ooda_orient_checklist.md — Orient 阶段检查清单

路径：templates/ooda_orient_checklist.md

功能：OODA Orient 阶段的标准化检查流程。

---

多 Agent 协同架构

角色	用途	触发条件
主 Agent	分析执行、Worklog 写入、README 维护	始终活跃
Explore Agent	代码探索（为 README 溯源生成逻辑）	需要理解代码时
Deep Research Agent	文献调研	Orient 阶段
Plan Agent	复杂任务规划	新 Phase 开始前

MCP 调用策略

MCP Server	用途	调用时机
PubMed	文献验证	Orient 阶段
OpenAlex	学术搜索补充	Orient 阶段

---

Resources

文件	路径	用途	何时加载
OODA 指南	references/ooda-playbook.md	OODA 循环详解	Orient 阶段
追溯入职协议	references/onboard-protocol.md	半路加入时反向填充容器文档	项目非空但无容器文档时
SPEC 模板	templates/SPEC-experiment.md	实验方案模板	Phase 1
可视化模板	templates/SPEC-visualization.md	可视化方案模板	Phase 3
Worklog 模板	templates/WORKLOG.md	实验记录模板	项目初始化
输出 README 模板	templates/OUTPUT_README.md	输出目录解释文档模板	产生输出时
状态模板	templates/STATE.md	轻量状态检查点	skill 激活时
初始化脚本	scripts/ai4s-init.sh	目录初始化	Phase 0
Gate 脚本	scripts/ai4s-gate-check.sh	交付物验证	每 Phase 后
Worklog 工具	scripts/ai4s-worklog.py	记录追加/查询	每步骤

---

研究生命周期

1. INIT → 初始化 + 模板
2. SPEC → 研究问题 → ADR → SPEC 文档
3. DATA → 下载 → QC → DATA_MANIFEST
4. ANALYZE → OODA × N Phase
   Observe → [WORKLOG] → [README] → Orient → [WORKLOG] → Decide → [WORKLOG] → Act → [WORKLOG] → [README] → Gate
5. VISUALIZE → SPEC-visualization → 实现 → 迭代
6. DELIVER → Gate Final → 报告 → DOCX

---

质量标准

• W1：每个 Phase 每个 Step 都有 WORKLOG 条目，OODA 4 阶段完整
• W2：每个输出目录含 README_文件说明.md，覆盖所有文件，溯源到代码
• W3：每个关键结果有文献验证记录，含 PMID/DOI
• W4：每个分析脚本输出同名 .log 文件，含包版本、输入验证、执行计时
• SPEC 追溯：代码可追溯到 G{n} 目标，ADR 有理由和替代方案
• 可重复：固定种子、记录版本、DATA_MANIFEST 完整

---

v2.2.0 — 新增 W4 脚本级强制日志规则 + G9 结果-日志一致性 Gate Check + 输入验证模式。基于实际科研项目（FASEB J 审稿干实验验证）实践提炼。

关联 Skill（网络调度协议）

关系	Skill	场景
可调用	scrna-celltype-annotation	marker 分析完成需要细胞注释
可调用	deep-research	实验结果需要文献验证
被调用	vitaforge-orchestrator	实验分析阶段