Imported from r2ascension/skill_repo (skills/tabular-results-llm-bridge/SKILL.md). Install upstream with npx skills add r2ascension/skill_repo --skill tabular-results-llm-bridge. Copyright stays with the author.

Tabular Results LLM Bridge

核心目标

把本仓库中的分析结果表（尤其是 csv / tsv）安全、可追溯、可批量地接到 LLM API 上，产出结构化解释，而不是把大表一股脑倒进 prompt 里然后祈祷奇迹发生。

这个 skill 的重点不是“随便调用一个大模型”，而是复用当前仓库已经成熟的三层范式：

1. 证据标准化：把 DEG / enrichment / ssGSEA / gene-pathway map 压缩成紧凑证据块。
2. 结构化输出：强制 JSON schema，而不是接受自由散文。
3. 失败可恢复：JSON 解析失败时保留 raw text，并走 fallback / standardization，而不是直接把非结构化返回当成功。

何时使用

当用户要做下面这些事情时使用本 skill：

• “把某个分析结果 csv/tsv 接到 LLM 做解释”
• “给 DESeq2_results.csv / enrichment 结果 / ssGSEA 结果生成机制说明”
• “设计一个 LLM wrapper，把不同分析表统一转成结构化解释输出”
• “把多数据库富集结果整理后喂给模型，而不是逐数据库分开瞎讲”
• “批量读取对比目录里的结果表，输出标准化的 LLM 结果文件”
• “仿照 interpret() / interpret_agent() 写一个适配本仓库表格结果的 helper / script / workflow”

何时不使用

下面这些情况不要优先使用本 skill：

• 你手里已经是 R 内存中的 enrichResult / gseaResult / compareClusterResult，而且用户只是想直接解释对象；这时优先走 interpret() / interpret_agent()。
• 用户只是想读某一个结果表、做人工总结或生成一次性说明，而不是搭一个可复用的 LLM 接口层。
• 输入只有汇总主表（如 all_lineages_tissue_deg_llm_master.tsv），但没有准备回捞 contrast 级证据；这时先做筛选和定位，不要直接做机制推断。
• 用户问题本质上是 plotting / visualization / report layout，而不是“结果表 → LLM 结构化解释”。

先看这几个现成参考，不要重新发明轮子

一手参考实现

• script/R/interpret.R

  • process_enrichment_input()：输入标准化
  • construct_interpretation_prompt() / construct_annotation_prompt() / construct_phenotype_prompt()：prompt 模板
  • call_llm_fanyi()：LLM API 调用 + JSON 解析
  • interpret() / interpret_agent()：单阶段与多代理入口

• script/R/interpret_agent_hotfix.R

  • .ensure_list()：防守式 list 校验
  • hotfix interpret_agent()：非 JSON / character 返回的 fallback 包装

仓库里更贴近“CSV/TSV → LLM”的参考

• script/R/bcell_tissue_comparison_v2_6_20260406.R

  • prepare_llm_enrichment_bundle()：从多数据库结果挑代表对象 + 组装 evidence
  • build_multi_db_context_text()：多数据库富集表压缩为文本证据
  • build_gene_pathway_map()：从 enrichment + fold change 提取保守的 gene→pathway 映射
  • format_gene_pathway_map_text()：将 gene-pathway map 转成 prompt 证据行
  • build_integrated_directional_enrichment_text()：把 up/down + 多数据库证据合并成单一判断上下文
  • standardize_result_with_llm()：强制统一 JSON schema 的后标准化层

• script/R/tissue_deg_llm_crosslineage_summary_20260525.R

  • 展示了仓库里现有表格产物如何被再次消费：
    • DESeq2_results.csv
    • interpret_agent_integrated_up_down_structured.rds
    • llm_multi_db_evidence_integrated_up_down.csv
    • validated_gene_pathway_map_integrated_up_down.csv
    • all_lineages_tissue_deg_llm_master.tsv

输入表的优先级与用途

针对当前仓库的推荐工作流

场景 A：手里是 R enrichment 对象

优先复用：

1. process_enrichment_input()
2. construct_*_prompt()
3. call_llm_fanyi()
4. 必要时套 interpret_agent_hotfix.R

不要先导出成 csv 再绕一圈读回来，除非用户明确要求做可复用的表格接口层。

场景 B：手里是 csv/tsv 结果表

优先按下面顺序压缩证据：

1. 比较/群组切分：先按 comparison、cluster、celltype、direction 分组。
2. DEG 摘要：提取 top up / top down / top |log2FC| 基因。
3. 富集证据摘要：
   • 多数据库时优先用 build_multi_db_context_text() 或 build_integrated_directional_enrichment_text() 思路。
   • 不要逐数据库各写一段互相打架的解释。
4. gene-pathway map：
   • 若有 validated_gene_pathway_map*.csv，只允许根据它做 gene→pathway 直连表述。
   • 若没有，就把基因和通路分开说，不要脑补一条虚构边。
5. 标准化输出：
   • 第一轮可以允许 richer schema。
   • 最终扁平落盘时，优先模仿 standardize_result_with_llm() 的 schema。

场景 C：手里是主汇总 tsv

把它当成：

• 交付总表
• QA 面板
• 候选 contrast 筛选器
• 二次报告输入

不要把 all_lineages_tissue_deg_llm_master.tsv 当成“主要生物学证据来源”。 它应该告诉你去哪一个 contrast 目录回捞真正证据，而不是自己承担第一轮机制判断。

推荐的 schema：优先用扁平标准化版本

对于“结果表 → LLM → 可下游汇总”的任务，优先使用下面这组固定键：

• overview
• key_mechanisms
• hypothesis
• narrative
• key_drivers
• evidence
• limitations

原因：

• 便于落成一行一条记录的 csv/tsv
• 便于跨 lineage / cell type 汇总
• 比 interpret_agent() 的 richer network schema 更适合批量结果管理

什么时候再加 richer 字段

只有在输入里真的有足够网络级证据时，才增加：

• refined_network
• network_evidence
• functional_modules
• regulatory_drivers（rich object 版）

否则保持扁平 schema，别给未来自己制造解析灾难。

API 层设计约定

1. 最小 wrapper 接口骨架

如果后续要把这个 skill 落成真正可运行的 R helper，优先从一个最小而稳定的接口开始：

• 输入：
  • deg_path = NULL
  • enrichment_path = NULL
  • gene_pathway_map_path = NULL
  • result_scope（如 celltype/comparison/direction）
  • model
  • api_key = NULL
  • output_prefix
• 过程：
  • 读取表格
  • 压缩 evidence text
  • 调用 LLM
  • 解析 JSON
  • 失败时保留 raw text 并 fallback
  • 输出 structured + tabular artifacts
• 返回值最少应包含：
  • status
  • raw_text
  • parsed
  • warnings
  • output_files

重点是先把“输入路径 / evidence builder / LLM call / parse / outputs”这五段边界钉死，再考虑 richer network schema、批量调度和多代理扩展。

2. 把 API 调用层与 prompt 层分开

无论用：

• fanyi::chat_request()
• 自定义 httr2 / httr 调用
• 未来其他兼容 API

都尽量维持类似接口：

• 输入：prompt, model, api_key = NULL
• 输出：原始文本

然后把 JSON 解析、fallback、重试放在上层 helper 里。

3. 当前仓库的首选仿照对象

优先仿照 call_llm_fanyi() 的职责边界：

• 负责 API 调用
• 尝试解析 JSON
• 解析失败时保留 raw text 并报警告

4. 密钥处理规则

• 不要硬编码 API key。
• 不要把 key 打进日志、message、warning、输出表。
• 优先接受 api_key 参数；若为 NULL 再去 option / env 中找。
• 如果需要 .env，只检查变量是否存在，不在对话里回显其内容。

Prompt 设计规则

一定要做的事

1. 明确角色：如解释器、标注器、标准化器。
2. 明确输入来源：DEG、multi-db enrichment、validated gene-pathway map。
3. 明确 JSON schema：固定键名，固定值类型。
4. 明确 grounding：每个结论必须来自输入表里的 term / gene / direction。
5. 明确限制：
   • 证据弱时要保守
   • 没有验证过的 gene→pathway 映射时不能硬连
   • 多数据库结果要综合，不要只盯第一行

一定不要做的事

• 不要把整张超大 tsv 原样塞进 prompt。
• 不要让模型对一个数据库的单个术语过拟合。
• 不要从 master.tsv 直接推机制。
• 不要在没有 validated_gene_pathway_map 的情况下编造 gene→pathway 连接。
• 不要在 JSON parse 失败后把流程默默当成功。

针对本仓库最有用的三种输入模板

1. DEG-only 模式

适用：只有 DESeq2_results.csv

最低要求列：

• gene / symbol
• log2FoldChange / avg_log2FC
• 可选 padj / p_val_adj

输出重点：

• overview
• key_mechanisms
• evidence
• limitations

此模式下要主动承认：机制链条弱，更多是状态判断和候选假说。

2. Enrichment + gene-pathway map 模式

适用：

• llm_multi_db_evidence_integrated_up_down.csv
• validated_gene_pathway_map_integrated_up_down.csv

这是当前仓库最推荐的表格接口 → LLM模式。

输出时应优先：

• 综合 up/down
• 综合多个数据库
• 在 key_mechanisms 中只使用已验证的 gene→pathway 对

3. 汇总报告模式

适用：all_lineages_tissue_deg_llm_master.tsv

目标不是首轮解释，而是：

• 选出高价值 contrast
• 汇总各 lineage 结论
• 发现缺失文件 / 空 LLM 输出 / evidence rows 为 0 的异常项

建议的落盘产物

如果本 skill 被用于编写新脚本或 helper，优先沿用当前仓库产物命名：

• 原始模型文本：*_raw.txt
• 结构化对象：*_structured.rds
• 富集证据表：llm_multi_db_evidence_<tag>.csv
• 基因-通路映射：validated_gene_pathway_map_<tag>.csv
• 扁平汇总表：*.tsv

放置位置

• 新 R 脚本：script/R/
• 运行产物：data/R/<YYYYMMDD>/... 或已有 comparison 输出目录
• 日志：logs/<YYYYMMDD>/
• 实验记录：docs/experiments/WORKLOG-YYYYMMDD.md 或 EXP-YYYYMMDD-<slug>/README.md

批量处理时的拆分原则

一条 prompt 最好对应一个最小生物学单元，例如：

• 一个 celltype x comparison
• 一个 cluster
• 一个 tissue x cell type 组合
• 一个 direction-integrated contrast

不要把一整个 lineage 的几百行 contrast 直接混在一起。那不是“上下文丰富”，那是“模型失去人生方向”。

最低验证要求

使用本 skill 完成任务后，至少检查：

1. JSON 是否真的可解析。
2. 解析失败时 raw text 是否被保留。
3. 输出字段是否齐全。
4. evidence 是否真的引用了输入表中的 term / gene。
5. 若写了 gene→pathway，是否来自 validated_gene_pathway_map。
6. 扁平汇总表中的 status / error / warnings 是否可用于下游 QA。

在本仓库里，优先采用的设计结论

优先级 1：对象态解释

如果你在 R 会话里直接拿到 enrichment 对象，先看 interpret() / interpret_agent()。

优先级 2：表格态标准化

如果你要做复用性更强的 pipeline、批处理、跨 lineage 汇总、或用户明确给你 csv/tsv，优先看：

• prepare_llm_enrichment_bundle()
• build_multi_db_context_text()
• build_gene_pathway_map()
• build_integrated_directional_enrichment_text()
• standardize_result_with_llm()

优先级 3：热修复容错

如果 LLM 经常返回：

• 非 JSON
• 截断 JSON
• 纯文本散文
• 混合 markdown code fence

直接参考：

• call_llm_fanyi() 的解析清洗逻辑
• interpret_agent_hotfix.R 的 .ensure_list() + 非结构化 fallback 包装

你在实际工作中应该产出的内容

使用本 skill 时，目标通常不是只给一段聊天建议，而是产出以下一种或多种成果：

• 一个新的 R helper / script，把 csv/tsv 结果表接到 LLM
• 一个固定 JSON schema
• 一套 evidence text builder
• 一套 raw + structured 双落盘机制
• 一个可汇总的平面结果表
• 必要时补实验日志，说明输入、输出、参数、验证情况

如果这些都没有落地，只是“给模型喂了张表然后说了一段感想”，那还不算真正用好了这个 skill。