bensz-rmd-rules

目标

规范 AI 开发 R Markdown 分析脚本的行为准则。当用户要求"写 Rmd 分析"、"开发 R 脚本"、"做数据分析"时触发。核心原则：遵循主业与副业分离架构（.R 保留完整数据，.Rmd 应用业务阈值），优先使用用户已有 R 包资源；图表默认按 Nature 级别可读性与出版质量生成；专家级解读兼顾弱背景读者，提供四层框架、指标导读与不常用指标首次解释协议；路径验证确保跨平台兼容性。前提：luckyBase 为硬依赖。

流程

输入

输入为项目的 .R/.Rmd 文件、已有 R 包资源、数据字典、分析目标和输出要求；运行前确认 luckyBase::Plus.library() 可用，并读取 config.yaml、模板和与当前分析直接相关的 references。

执行步骤

核心原则概览

原则	核心要求
现有资源优先	优先使用用户已有的 R 包和函数，不重复造轮子
人类可读	代码简洁优雅，天然适合人类审查
混合架构	.R 负责数据处理/计算（保留完整数据），.Rmd 负责可视化/分析（应用业务阈值）
函数分离	专用函数脚本 _functions.R，避免污染全局环境
数据筛选分离	.R 不应用阈值筛选（方便审查原始状态），.Rmd 根据业务需求应用阈值（确保分析价值）
不过度保护	避免过多防御性代码，以人类为中心
跨平台兼容	代码在 macOS/Linux/Windows 上均可运行，路径使用相对路径
完整因果链	代码前解释"为什么"，结果后解读"意味什么"
分层指标解释	默认读者背景较弱；不常用指标先导读、首次详解、后续简写

现有资源优先原则

R 包资源清单

优先使用用户已有的 R 包资源。完整包清单详见 [config.yaml:r_packages]，主要包括：

包名	用途	典型场景
ccs	泛癌症基因组分类计算框架	癌症分型、亚型分类
GSClassifier	转录组学综合分类工具	基因签名分类、预测模型
lucky	常规 R 函数集合	生存分析、差异表达、可视化
luckyBase	lucky 系列基础辅助包	包管理、基础工具函数
luckyExperiment	生物学实验数据处理	实验数据处理
luckyGEO	GEO 数据下载与处理	GEO 数据下载、处理
luckyModel	第三方生物信息学模型	模型集成、预测

luckyBase 强制要求（硬性规定）

⚠️ 关键 1：luckyBase 必须强制加载

luckyBase 是本技能的核心依赖，必须强制加载，不得跳过或提供降级方案。

⚠️ 关键 2：必须使用 luckyBase::Plus.library 自动安装/加载包

# 正确做法（强制）
luckyBase::Plus.library("ggplot2")
luckyBase::Plus.library("DT")

# 错误做法（禁止）
library(ggplot2)  # 禁止直接使用 library()
if (!requireNamespace("ggplot2", quietly = TRUE)) {  # 禁止手动检查
  install.packages("ggplot2")
}

⚠️ 关键 3：必须使用 luckyBase::convert 进行基因 ID 转换

在涉及基因 ID 转换的场景（如 ENSEMBL → SYMBOL、ENTREZID → SYMBOL），必须使用 luckyBase::convert() 函数：

# 正确做法（强制）
gene_symbols <- luckyBase::convert(
  ids = gene_ensembl_ids,
  from_type = "ENSEMBL",
  to_type = "SYMBOL",
  organism = "human"
)

# 错误做法（禁止）
# 禁止使用 biomaRt、AnnotationDbi 等其他包手动转换
# 禁止硬编码 ID 映射表

理由：

• luckyBase::Plus.library() 自动处理包的安装和加载，无需手动检查
• luckyBase::convert() 提供统一的基因 ID 转换接口，支持多物种、多 ID 类型
• 避免重复造轮子，保持代码简洁

candidate_r 函数库（可选）

当 lucky 系列不能满足需求时，可使用 candidate_r 函数库（用户可能拥有的自定义函数目录）。

核心原则：

• candidate_r 是可选的，不是必需的
• 用户已在 00.Environment.R 加载时，AI 可直接使用（轻量检查函数是否存在）
• 用户指定 candidate_r_path 时，AI 按该路径 source() 脚本
• 不猜路径、不扫描磁盘，优先提供回退方案（lucky/CRAN/最小实现）

详细用法参见 [references/candidate_r.md](references/candidate_r.md)。

资源使用优先级

1. 用户已有/已约定的 R 包：在 00.Environment.R 里用 luckyBase::Plus.library() 统一加载；在分析脚本中优先使用 pkg::fn() 调用（避免到处 library()）
2. candidate_r 函数库（可选）：仅在用户已加载或用户提供 candidate_r_path 时再 source()（详见 references/candidate_r.md）
3. CRAN/Bioconductor 包：确实需要时，仍通过 00.Environment.R 用 luckyBase::Plus.library() 引入
4. 最小自定义函数：最后选择，写入 {主脚本名}_functions.R（不要散落在 .Rmd 内）

人类可读原则

代码风格、命名规范、注释要求等详细内容见 [references/code_style_guide.md](references/code_style_guide.md)。

核心要点：

• 管道优先：使用 %>% 或 |> 构建可读的数据处理流程
• 向量化思维：优先使用向量化操作，避免遍历 + if 判断
• 函数式编程：使用 purrr::map() 等函数式工具替代循环
• 数据驱动：用查找表、join 等数据驱动方式替代硬编码逻辑
• 不过度防御：避免对已由 00.Environment.R 管理的包/函数做冗余检查；仅在 I/O 边界与硬性前提（如 00.Environment.R、关键输入文件/目录）做明确的 file.exists()/dir.exists() + stop()，以提供更清晰的失败信息（见 references/no_overdefensive_code.md）

图表语言规范

默认英文；如确需中文（如中文期刊投稿），通过 .Rmd 的 YAML params.plot_language 显式切换。

详细规则与示例见 [references/plot_language.md](references/plot_language.md)。

Rmd 标题规范

标题应描述“内容是什么”，而非“如何做/用什么函数做”。本规范适用于 .Rmd 正文中的 Markdown 标题（##/###/####）。

禁止形式

禁止形式	示例	问题
括号备注	结果解读（专家叙事）	增加形式化感，不自然
主标题-副标题	决策曲线分析 - get_dca	暴露实现细节，冗余
函数名标题	数据筛选 - filter_data()	标题不应包含实现细节
流程化标注	数据加载与处理（第一步）	把过程编号写进标题，降低可读性

推荐形式

推荐形式	示例	理由
简洁描述	结果解读	自然语言，简洁明了
内容导向	决策曲线分析	描述内容，不描述方法
专业术语	多因素 Cox 回归	使用领域标准术语
层级清晰	## 单因素筛选 ### Top 25 基因	结构清晰，读者易定位

实践示例

❌ 错误示范：

## 数据加载与处理（第一步）

### 单因素筛选 - univ_screen()

#### 结果解读（专家叙事）

✅ 正确示范：

## 数据加载与处理

### 单因素筛选

#### 结果解读

主业与副业分离原则

硬性要求（最小口径）：

• 采用 .R + .Rmd + {主脚本名}_functions.R + 00.Environment.R + tmp/{主脚本名}/ 的混合架构（默认结构见 config.yaml:file_structure）
• .R 负责重型计算与保存全量产物（不做业务阈值筛选）；.Rmd 基于 YAML params 做阈值筛选、可视化与专家级解读
• 命名一致：{name}.R / {name}.Rmd / {name}.html（除后缀外完全相同）

起手与细节（下沉到 references/templates）：

• 指南：references/hybrid_architecture_guide.md
• 示例：references/hybrid_architecture_examples.md
• 模板入口：templates/（R_data_template/Rmd_template/functions_template/00.Environment）

不过度保护原则

核心口径：

• 主脚本/主 Rmd 不做冗余包检查与降级分支（包加载集中在 00.Environment.R）
• 禁止“占位性代码”掩盖失败：要么切实落地，要么显式 stop()，如需容错必须提供有效降级方案

详细反模式与边界规则见 [references/no_overdefensive_code.md](references/no_overdefensive_code.md)。

跨平台兼容性原则

核心口径：相对路径 + file.path()；跨平台细节与可选验证脚本见 [references/cross_platform.md](references/cross_platform.md)。

完整因果链原则

本原则要求 AI 像顶级科学家面向跨专业读者写作：默认读者相关背景较弱，先提供不失真的理解支架，再给出从数据描述到深刻见解的完整因果链，而非简单罗列统计结果。通俗表达不得牺牲定义、计算边界或不确定性。

基因 ID 优先级（生物医学分析专用）

在生物信息学、医学统计等涉及基因的分析中，需遵循基因 ID 优先级规范：

• 展示优先级：可视化、表格、文本解读中使用 SYMBOL（如 TP53），而非 ENSEMBL ID 或 ENTREZID
• 数据完整性：保存的数据应包含 SYMBOL、ENSEMBL、ENTREZID 多种 ID，确保准确性和可追溯性
• 核心理由：增强可读性，让临床医生、生物学家等非生信专业读者也能理解

详细规范参见 [references/gene_id_guidelines.md](references/gene_id_guidelines.md)。

代码块前解释

代码块前解释的模板与示例已下沉：references/code_block_explanations.md。

指标分层与首次解释（必须）

• 先按 config.yaml:metric_explanation 盘点指标；默认白名单包括描述统计、p/q/FDR/CI、常见效应量与相关系数、经典生存分析以及 ROC AUC 等经典诊断指标。未命中、无法确定或采用非标准定义时，按不常用指标处理。
• 只要出现不常用指标，就在首个分析模块前增加“指标导读”表，至少说明尺度/参考点、升降趋势、置信区间或其它不确定性、本次选用理由与判读边界。
• 不常用指标在结果正文首次出现时，先自然解释“是什么、如何计算、为什么使用、带来什么价值、如何判读”，随后立即结合本次数字解读；第二次起不再重复原理，只解读当前证据。
• 同名指标的公式、量纲、方向、参考点或时间窗发生变化时，视为新指标并重新解释。常用指标通常不展开教学，但存在反直觉方向或非标准设定时需简短澄清。

完整分类、表格字段、首次/后续出现协议与边界见 references/metric_explanation_protocol.md。

结果后解读（专家级，非模板化）

对重要输出（图表/表格/统计量）在交付/收敛阶段必须满足：

• 证据锚定 + 数字可追溯：关键判断尽量用 `r ...` 内联数字（或明确可追溯的字面数字），避免“凭空写数字”
• 覆盖不漏项：任何可见图/表输出块附近必须有 prose 解读（Fail Fast 门禁）
• 禁止代码生成解释文本：允许代码生成数字，不允许代码拼接解释段落 “四层框架 / Top 信号 / 不确定性提示 / 可执行后续”保留为推荐结构（适用于关键输出与终稿；探索期可先低密度写解读，再逐步加深）。 解读是思考的输出，不是结构的填空。目标是让研究者在 30–60 秒内回答：这个结果对我意味着什么？我下一步应该优先做什么？（而不是解释“这个统计量是什么/这个图表用于做什么”）。

解读前：建议先回答的四个问题（关键输出/终稿强烈建议）

1. 研究者视角：如果我是项目负责人，看到这个结果，我最想确认/反驳的是什么？
2. 领域映射：这个统计发现如何改变我对机制/病程/人群差异的理解（只给“可证伪”的推断，不写玄学结论）？
3. 决策帮助：基于这个结果，我会优先做什么？不做什么？为什么？
4. 风险边界：如果该结论不复现，最可能的原因是什么（分层样本量、构成混杂、批次、模型假设等）？

禁止：机械套用模板（硬门槛）

以下写法属于“不看数据也能写”的空壳，必须避免：

• ❌ “这张图/表在本次数据中的直接观察是：... 这在统计层面的含义是：... 对研究者的直接意义是：... 你可以立即执行的下一步是：...”
• ❌ “数据描述：... 统计见解：... 领域见解：... 局限与后续：...” 的机械分项（把四层当成固定四段/固定四行标签）

必须：分层解释 + 连贯叙述 + 证据锚定

• 面向弱背景读者时，先按指标解释协议搭建理解支架；这不是降低专业性，也不是允许重复教学。
• 默认采用1–2 段连贯叙述，自然融入四层内涵（四层是内容门槛，不是固定写作格式）。
• 每个关键判断至少包含：对象 + 对比/排序/方向 + 数值证据（优先 `r ...` 或明确可追溯的字面数字），并解释统计量在本次结果中的量级含义。
• 推荐（关键输出/终稿；严格模式下可能作为门禁）：Top 1–3 + 不确定性线索（CI/SE/bootstrap/CV 等）+ 至少 1 条可证伪推理 + 至少 1 条可执行后续（方法 + 输入 + 判据；阈值来自 params）。

交付前自检（推荐；严格模式强烈建议）

• 判断是否绑定“对象 + 方向/对比 + 数值证据（优先 `r ...`）”，并解释量级含义（不只报 p/q/rho/HR）？
• 是否至少给出 1 条可执行后续（方法 + 输入 + 判据，阈值来自 params），并避免空泛句式缺少本地证据？

禁止通用套话（硬门槛）

解读中的每个判断必须绑定当前数据的具体对象与数值，禁止写成教学口吻或通用规则。 强制要求：必须指出"当前数据中，哪几组/变量呈现什么模式"，优先用 `r ...` 嵌入具体数值（或明确可追溯的字面数字），必须解释统计量在当前数据中的量级含义。 黑白名单详见：references/four_tier_interpretation_framework.md / references/interpretation_templates.md / references/interpretation_narrative_examples.md。 交付前静态预检（覆盖 + 质量）：

1. 图表/表格解读覆盖检验（强制，Fail Fast）：

# 探索期：仅报告（不阻断）
python3 bensz-rmd-rules/scripts/check_figure_table_interpretation.py your_report.Rmd
# 交付期：Fail Fast 门禁（不通过则阻断）
python3 bensz-rmd-rules/scripts/check_figure_table_interpretation.py your_report.Rmd --strict

若未通过：必须先补齐/加强对应输出块的解读（按“证据锚定 + 当前数据观察”口径；不强制四层标签），直到 --strict 命令通过，才允许进入后续步骤。 判定口径与可调参数见：references/figure_interpretation_criteria.md 与 config.yaml:figure_interpretation_check。 少数“命中输出模式但确实不产生可见输出”的 chunk，可在 chunk 头部加 interp_check=FALSE 手动豁免（避免误杀）。 2) 解读质量预检（启发式，推荐）：

# 探索期：仅提示不阻断
python3 bensz-rmd-rules/scripts/check_interpretation_quality.py your_report.Rmd --warn-only
# 交付期：默认门禁（不通过则阻断）
python3 bensz-rmd-rules/scripts/check_interpretation_quality.py your_report.Rmd

该脚本会读取 bensz-rmd-rules/config.yaml:interpretation_quality_check 作为默认阈值与检查开关（如环境缺少 PyYAML 则降级为内置默认值）。 如需更强的“反模板化/反流于表面”检查（机械模板识别、Top 名单落地、后续动作可执行句、强语气与稳健性约束等），使用：

python3 bensz-rmd-rules/scripts/check_interpretation_quality.py your_report.Rmd --strict

禁止代码生成解释

解释性文本必须由 AI 直接写出；允许用 `r ...` 动态嵌入数字以保证精确与同步，但不得通过代码逻辑拼接/生成解释句子。

场景	允许	禁止
数字嵌入	✅ `r sprintf('%.2f', hr)`	❌ 在正文硬写不可追溯数字
轻量词语选择	✅ ifelse() 选择“升高/降低”等词	❌ 通过代码拼接完整解释段落
结果引用	✅ `r nrow(tbl)`	❌ cat()/字符串拼接输出解释文本

❌ 错误做法（代码生成解释）：

interpretation <- ifelse(hr > 1, "提示风险增加", "提示风险降低")
cat("从统计上看，", interpretation)

✅ 正确做法（数字动态、解释直接）：

从统计上看，该效应为 `r sprintf('%.2f', hr)`（95% CI: `r ci_low`–`r ci_high`），**提示暴露组风险显著高于参照组**。

解读语气与风格

默认采用“论文口吻”：克制、客观、推论式。避免模板化教学提示与括号解释堆叠。不常用指标首次出现时的必要解释是例外，但应自然融入结果叙述，并从第二次起收敛。

维度	教学口吻（避免）	论文口吻（推荐）
括号使用	（即...） （注意：...）	尽量融入正文，括号主要用于 CI/单位等必要信息
提示语	提示： 注意：	直接陈述结论与边界，不使用提示标记
解释重心	“这是什么”式定义	“意味着什么”式推论（绑定本次结果证据）
语气	教导式、向导式	克制、客观、可验证

❌ 教学口吻（避免）：

该效应为 1.85（95% CI: 1.32-2.59），这表明风险增加。（即：HR > 1 意味着暴露组风险更高）
需要注意的是，该结论可能受混杂因素影响。

✅ 论文口吻（推荐）：

该效应为 `r sprintf('%.2f', hr)`（95% CI: `r ci_low`–`r ci_high`），**提示暴露组风险显著高于参照组**。
该结论的不确定性主要来自潜在混杂因素，需在多因素模型中进一步检验其稳健性。

文本强调规范

在结果解读中，对核心发现、关键判断、重要结论、不确定性来源做适度加粗，帮助读者快速抓住重点；避免“满篇加粗”。

• 一个解读段落中，加粗内容通常不超过 2–3 处
• 不加粗方法说明、流程描述、一般属性（如“表格包含 700 行”）

末尾讨论与分析

每个 Rmd 末尾必须包含讨论章节（主要发现 + 局限 + 可落地后续），随后添加“数字准确性验证”章节。深度模板见 [references/expert_discussion_template.md](references/expert_discussion_template.md)。

Rmd 模板规范

章节结构（硬门槛）

每个 .Rmd 默认采用以下章节顺序（允许在中间插入具体分析模块，但不要删掉硬门槛章节）：

• ## 数据概览
• ## 关键函数、参数与源代码位置（强制，紧跟“数据概览”之后）
• ## 指标导读（条件强制：存在不常用指标时保留；否则删除）
• （一个或多个）分析模块：如 ## 单因素筛选 / ## 多因素模型 / ## 模型性能与验证 / ## 可视化分析 等
• ## 讨论与分析（强制：主要发现 + 局限 + 可落地后续）
• ## 数字准确性验证（强制：末尾检验）

关键函数、参数与源代码位置（强制）

该章节的目标是“可追溯性”：让任何读者都能快速定位本报告的关键实现（以及为什么这样设）。

必须包含：

• 关键的分析过程是什么（按顺序，建议覆盖 3–10 个关键步骤）
• 用了哪些关键函数（推荐写成 pkg::fn()，并注明关键输入/输出对象名）
• 函数的关键参数是什么；为什么要这么设置（理由必须绑定本次数据/假设/阈值/限制）
• 源代码在哪个文件的第几行（写项目内的 .R/.Rmd/_functions.R 为主；格式建议 相对路径:行号）

推荐表格模板（直接复制到 Rmd 正文填写）：

| 分析过程/产物 | 关键函数/对象 | 关键参数（是什么） | 为什么这样设置（理由） | 源代码位置（文件:行号） |
|---|---|---|---|---|
| 数据加载与整理 | `readRDS()` / `dplyr::mutate()` | `path=...` / `na.rm=TRUE` | 读取主脚本产物；避免 NA 影响统计量 | `cf01.R:42` / `cf01.Rmd:28` |
| 主要统计分析 | `survival::coxph()` | `formula=...` / `ties="efron"` | 选择 Cox 模型；ties 处理与数据规模匹配 | `cf01_functions.R:85` |
| 可视化输出 | `ggplot2::ggplot()` / `ggplot2::ggsave()` | `width/height/base_size` | 确保 Nature 级别可读性与打印清晰 | `cf01.Rmd:92` |

YAML 头部

Rmd 的 YAML 头以 config.yaml:rmd_template.yaml_header 为准；templates/Rmd_template.Rmd 内保留一份便于起手的拷贝，维护时需与 config 同步（可用 scripts/check_rmd_template_yaml.py 校验）。

HTML 主题（Liquid Glass / glassmorphism）

默认使用 Liquid Glass 主题（templates/liquid_glass_theme.css），这是一套 glassmorphism 风格的专业级样式：

• Glassmorphism：玻璃拟态效果，背景模糊与半透明层次
• Motionless by Default：默认无无限动画，避免选中文本/代码时出现"高亮漂移"的干扰
• Auto Dark Mode：根据系统偏好自动切换深色模式
• Floating TOC（两种模式）：静态浮动（常驻）/ 动态浮动（收起为左上角小圆点，悬停展开；默认）；移动端自动折叠，可点击顶部按钮展开

使用方式：

• 详细的 YAML 配置、特性说明、自定义选项见 references/liquid_glass_theme_guide.md（说明文档；具体字段以 config.yaml:rmd_template.yaml_header 为准）
• 一键初始化脚本见下方"一键初始化新项目"

一键初始化新项目（推荐）

本 skill 的默认模板假设你在“项目根目录”存在如下文件：

• templates/liquid_glass_theme.css
• templates/liquid_glass_lightbox.html（图片点击放大 + 刷新后缩放/阅读位置尽量保持）

为避免手工拷贝，推荐在新项目根目录运行（脚本对安装位置不敏感，会基于 __file__ 自动定位 skill 目录）：

python3 /path/to/bensz-rmd-rules/scripts/bootstrap_liquid_glass.py --with-env

说明：

• --with-env 会在项目根目录创建 00.Environment.R（如已存在则跳过）
• 如需同时复制 DT/主题等常用模板，可加 --with-extras

表格渲染

默认规则（HTML：DT 优先）

当输出格式为 HTML 时，所有“数据表/结果表”（R 代码生成的 data.frame/tibble）默认使用 DT（DT::datatable()）进行渲染，除非用户明确指定使用其他表格方案（如 knitr::kable() / gt / flextable / reactable 等）。

推荐做法（优先）：

• 在项目根目录的 templates/ 下 source("templates/datatables_helper.R")，并使用 render_dt(...) / render_dt_output(...) 输出表格（该 helper 由本 skill 维护，路径见 config.yaml:datatables_helper）。
• 若项目内缺少该文件，优先用 bootstrap_liquid_glass.py --with-extras 一次性复制（或手动从本 skill 的 templates/datatables_helper.R 取用）。
• 若未使用 helper，直接使用 DT::datatable() 也可，但需遵守下方“HTML 可见性硬规则”。

最小示例：

# 00.Environment.R（强制）
luckyBase::Plus.library("DT")

# in .Rmd（HTML）
source(file.path("templates", "datatables_helper.R"))
render_dt(head(df, 100), pageLength = 10)  # 让它成为 chunk 的最后表达式

HTML 可见性硬规则（htmlwidget/DT，强制）

R Markdown 渲染为 HTML 时，DT::datatable() 等 htmlwidget 必须作为 code chunk 的“可见结果”返回，否则容易出现“代码在但不渲染”的漏项。

硬规则与示例见：references/htmlwidget_visibility_rules.md。

交付前强制检查（强制）

交付前必须先通过“图表/表格解读覆盖检验”，避免出现“有输出但无解读”的漏项：

python3 bensz-rmd-rules/scripts/check_figure_table_interpretation.py path/to/your.Rmd --strict

交付前必须运行一次 htmlwidget 可见性静态检查，避免出现“代码在但 HTML 不出表/不出图”的漏项：

python3 bensz-rmd-rules/scripts/check_htmlwidget_visibility.py path/to/your.Rmd

输出 HTML

使用 knit-rmd-html skill 将 Rmd 渲染为同名 HTML，保存在同级目录。

输出

输出包括遵循主业/副业分离的 .R、.Rmd、同名 HTML、图表/表格及数字准确性验证结果；分析过程、检查报告和临时文件按本 Skill 的 .bensz-api 工作区规则保存，不把中间结果混入源文件目录。

输出管理

BenszAPI 任务工作区

校验

图表质量规范（Nature 级别）

所有代码生成的图表必须默认达到 Nature 系列期刊的出版级别（“默认即专业”）。

唯一目标：最大程度保证人类可读性（屏幕阅读 + 打印均清晰）。

⚠️ 关键 4：每画一个图，必须主动检查并修复可读性问题（画完即交付，无需人工调整）

AI 自主规划原则（必须）

• 可读性优先：字体/线条/点大小/图例/比例等参数以“读者能否清晰阅读”为第一准则。
• 场景自适应：根据数据量、图表类型、展示场景动态调整；必要时可偏离默认值，但需说明原因。
• 避免视觉缺陷：主动处理标签重叠、图例遮挡、乱码/缺字、低对比度、过密/过空等问题。

可读性硬检查（生成绘图代码后必须显式检查）

每次生成绘图代码后，必须对以下项目逐条“检查→处理→再检查”，并在代码附近用 1-2 句说明你做了哪些可读性修复（避免只写一句“已优化”）。

阈值与默认策略以 config.yaml:plot_readability 为准（如用户另有要求，则以用户要求为准并说明偏离理由）。

检查项	常见触发条件（经验阈值）	处理策略（至少做 1 个）
标签溢出	长标签导致超出画布边界（尤其 x 轴分类）	旋转/换行/缩写 + 增加边距/增大画布
标签遮挡	文字与点/线/图例/注释发生重叠	调整 label 位置、只标注关键点、移动图例、分面
轴刻度过密	刻度数量过多导致挤在一起	减少 breaks、采样显示、增大画布
字体过小	预估打印或投影不可读（过密时尤甚）	提高 base_size、增大图尺寸、减少信息量
图例遮挡	图例与数据区域重叠或挤压数据	改为 "bottom"/"left"/外置，调整 guides()
中文/特殊字符	出现方块/乱码/缺字（或包含中文字符）	显式指定支持中文的字体族（跨平台候选），必要时降级为英文

可读性自检清单（生成代码时必须自检）

• 字体大小是否清晰可读（轴标题/图例/注释）？
• 线宽/点大小是否与数据密度匹配？
• 标签是否重叠（必要时旋转/缩写/分面）？
• 中文/特殊符号是否正确显示（必要时指定字体）？
• 图例是否遮挡数据（必要时外置/调整方向）？
• 配色是否色盲友好、对比充足（避免彩虹色）？
• 宽高比是否合理（避免信息拥挤）？

技术规范（默认值，可按场景调整）

维度	推荐默认值	说明
格式（静态）	PDF（矢量图，优先）	位图仅用于特殊场景并说明理由
字体	Arial/Helvetica（无衬线）	系统缺失时回退 sans
配色	Nature 调色板或 viridis	必须色盲友好，避免彩虹色
背景	白底 + 低噪声	轻网格或无网格，强调数据本身

参数面向用户（写在 .Rmd 里；必须）

AI 在 .Rmd 中生成每张图的绘图代码时，必须把“用户可能需要调整的参数”集中成一个参数区块，并为每个参数写清楚 # 注释说明（含：作用、推荐范围/常用取值、调大/调小的视觉后果）。

硬约束：禁止把关键值散落在 theme() / geom_*() / scale_*() 里让用户难以定位；所有可读性关键参数必须从参数区块引用。

图表标题策略（默认不落图；必须）

硬约束：默认生成的图（ggplot2 / plotly / 其他）不得使用 title / subtitle 参数（例如 ggplot2::labs(title=..., subtitle=...)、ggtitle()、plotly::layout(title=...)）。

理由：

• 图的语义应由文件名、.Rmd 的小节标题与图前说明来承载；保存文件名即可推断图是什么。
• 发表/投稿场景通常也不在图内放大标题（避免占用空间、与正文/图注重复）。

替代做法（推荐）：

• 用 .Rmd 的 Markdown 标题（##/###）+ 图前 1–2 句说明定位图的目的与变量定义。
• 如需图注，优先用 Rmd 的 fig.cap（而不是把标题写进图里）。

例外：仅当用户明确要求，或场景确实需要（例如教学演示、单图独立传播、外部审稿要求）时，才允许添加标题/副标题；且默认必须英文（受 references/plot_language.md 约束）。

示意结构（每张图都应遵循；可按场景增删参数，但必须保留“集中参数块 + 注释说明”口径）：

# ==== Figure 1: {短标题}（用户可调参数）====
# 说明：下面所有参数都是“面向用户”的调参入口；默认值是 Nature 级别可读性起点。
fig1 <- list(
  # 画布尺寸（英寸）。调大：更不拥挤、更适合长标签；调小：更紧凑但更易溢出/字体显得小。
  width_in  = 6.0,
  height_in = 4.0,

  # 字体基准（pt）。影响轴刻度/图例等整体尺度；打印/投影不清晰时优先调大。
  base_size = 10,

  # 线条/点大小。点太密：减小 point_size 或加 alpha；线看不清：增大 line_size。
  line_size   = 0.8,
  point_size  = 1.2,
  point_alpha = 0.85,

  # 图例位置：避免遮挡数据。常用："right" / "bottom" / "left" / "top" / "none"。
  legend_position = "right",

  # x 轴文字角度。长分类名常用 45/60；角度越大越不重叠，但需要更大的 bottom margin。
  x_text_angle = 0
)

落地要点：

• ggplot2：统一用 theme_nature_readable(base_size=..., x_text_angle=..., legend_position=...)，并把 geom_* 的 size/alpha/linewidth 等绑到 fig$...。
• ComplexHeatmap：save_heatmap_pdf(..., width=fig$width_in, height=fig$height_in, ...)；row/col 字号、legend 字号等至少暴露“常用可调项”。

交付门禁：矢量 PDF + JPG 预览 + 视觉自检（必须）

1. 正式交付唯一格式：矢量 PDF 每张图必须保存为矢量 PDF（例如 figure_xxx.pdf）。HTML 内联图仅作为阅读体验，不视作正式交付。

2. 保存 PDF 后，必须自动生成 JPG 预览图，并基于预览图做视觉自检 默认 run 目录：当前项目下 .bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/bensz-rmd-rules/run_YYYYMMDDHHMMSS/；用户可通过 .Rmd 的 YAML params.plot_run_dir 覆盖父目录。

推荐做法：将 templates/plot_delivery_helpers.R 复制到用户项目 templates/ 下，并在 .Rmd 的 plot-style chunk source()；然后在每次 ggsave()/save_heatmap_pdf() 后调用 bensz_pdf_to_jpg() 生成 *.jpg 预览图（详见 templates/Rmd_template.Rmd 示例）。

HTML 展示比例规则（必须）：

• HTML 里“展示用的图”（内联图片）默认应使用 由正式交付 PDF 渲染得到的 JPG 预览图（即 bensz_pdf_to_jpg() 的产物），以保证 HTML 展示比例与 PDF 完全一致，便于用户对照查看。
• HTML 里图片可以刻意偏小：用 out.width 控制展示宽度（例如 out.width="70%" 或 out.width="600px"），但不要同时指定 out.height（避免拉伸导致比例失真）。Liquid Glass 默认支持点击放大，因此不需要把图放得很大。

常用可调参数（写在 .Rmd 的 YAML params，便于用户改动）：

• params.plot_run_dir：JPG 预览 run_* 的父目录；默认使用当前项目下 .bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/bensz-rmd-rules/
• params.plot_preview_dpi：JPG 预览 DPI（越大越清晰但文件越大；默认 200）

3. AI 必须基于 JPG 逐图检查并处理（交付前门禁）

• 文字是否溢出/裁切（贴边、超出边界、被上边界/边框挤压）
• 字体是否“人类可读”（过小、密集导致不可读）
• 线/点是否过细（打印/投影不清晰）
• 图例是否遮挡数据（或挤压主体导致过密）
• 信息是否过密（必要时采样 breaks / 只标注 topN / 分面 / 增大画布）

标准化模板（强烈推荐复用）

本 skill 提供可直接复制到用户项目的模板（见 templates/）：

• templates/nature_colors.R：nature_colors
• templates/nature_theme.R：theme_nature()、theme_nature_readable()
• templates/complexheatmap_template.R：ComplexHeatmap 可读性模板
• templates/plotly_template.R：plotly 交互图模板
• templates/plot_delivery_helpers.R：PDF 交付 + JPG 预览（bensz_run_dir() / bensz_pdf_to_jpg()）

落地方式（推荐）：

• 将上述模板复制到用户项目根目录的 templates/ 下（与本 skill 同名即可）。
• 在 .Rmd 开头 source(file.path("templates", "...")) 统一加载（见 templates/Rmd_template.Rmd 的 plot-style 代码块）。

图表质量的完整规范与检查项见：references/plot_quality_standards.md。

常见可读性问题场景与可复制最小示例见：references/plot_quality_standards.md。

数字准确性验证（末尾检验）

每个 .Rmd 的末尾应包含“数字准确性验证”章节，确保解读中的关键数字可追溯到变量/计算逻辑，并优先使用 `r ...` 动态嵌入以避免漂移。

模板与规范见：references/numeric_accuracy_verification.md。

交付验证（强制）

交付前必须附带自检报告（含“解读-代码一致性”证据）。

模板与真实示例入口见 [references/delivery_verification.md](references/delivery_verification.md)。

工作流检查清单

内部检查清单见 [references/workflow_checklist.md](references/workflow_checklist.md)。

失败与恢复

缺少 luckyBase、R 包/模板、输入文件或渲染依赖时，保留命令输出和检查报告并停止相应阶段；图表/表格解读或 HTML 可见性门禁未通过时先修复或明确阻塞，不把未验证结果交付为完成。可在同一任务工作区重试。

约束

公共硬约束

本块由 docs/templates/skill-common-constraints.md 统一维护；每个 SKILL.md 的 ## 约束 必须逐字同步本块，不得在副本中改写公共规则。

• 任务需要落盘时，使用唯一的 ./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/ 根目录；共享材料放入 shared/，Skill 专属材料放入该 Skill 的 input/、output/、log/。
• 正式交付物、源代码和正式计划按项目约定保存，不写入任务工作区；未经授权不覆盖、删除、迁移或远程写入。
• 项目维护变更检查 BAC 可用性并记录需求、AI 产出、工具结果、文件改动和验证摘要；BAC 只做过程审计，不替代署名、责任或合规判断。
• 不记录 API Key、访问令牌、密码、Cookie、环境/凭据文件、私有 Prompt、身份信息、本地用户名、主机名或不必要的大体积原始数据。
• 文件路径必须规范化并限制在授权项目范围内；外部 URL、子进程和网络访问遵循最小权限，防止路径遍历、SSRF 和命令注入。
• Skill 版本唯一记录在自身 config.yaml:skill_info.version；公开 API、协议、目录或配置变更同步文档与 CHANGELOG.md。
• bensz-collect-bugs 是一个 Agent Skill；仅将 Bensz Agent Skill 或 Bensz 基础设施本身的设计缺陷交给它。先脱敏写入 ~/.bensz-skills/bugs/，当前任务不中断，只有用户明确要求才公开上报，禁止直接修改用户已安装的 Skill 源码。