bensz-rmd-rules · diff
git:20260906.d2681a7 to git:20260917.6e753cd
114 added, 558 removed. Audit A to A.
---
name: bensz-rmd-rules
- description: 当用户要求编写 R Markdown 分析、开发 R 脚本或进行 R 数据分析时使用。规范脚本与报告分工、图表表达、结果解读和跨平台路径处理。
+ description: 当用户要求编写或维护 R Markdown、R 分析脚本、可复现数据分析，尤其涉及多阶段计算、缓存复用、断点恢复或论文级图表与解读时使用。负责规划分析单元、组织 R/Rmd 数据流、验证缓存与交付质量；不用于仅渲染既有 Rmd 或其它语言的数据分析。
metadata:
author: Bensz Conan
- short-description: R Markdown 开发规范（.R+.Rmd 混合架构 + 专家级解读 + 跨平台兼容）
+ short-description: R/Rmd 多阶段分析、可恢复数据产品与论文级报告规范
keywords:
- bensz-rmd-rules
- R Markdown
- Rmd
- 数据分析
+ - 断点续算
- 可复现报告
- - R 脚本
---
# bensz-rmd-rules
## 目标
- 规范 AI 开发 R Markdown 分析脚本的行为准则。当用户要求"写 Rmd 分析"、"开发 R 脚本"、"做数据分析"时触发。核心原则：遵循主业与副业分离架构（.R 保留完整数据，.Rmd 应用业务阈值），优先使用用户已有 R 包资源；图表默认按 Nature 级别可读性与出版质量生成；专家级解读兼顾弱背景读者，提供四层框架、指标导读与不常用指标首次解释协议；路径验证确保跨平台兼容性。前提：luckyBase 为硬依赖。
+ 先理解研究目标与数据，再把任务组织为可审查、可恢复的 R 分析单元。`.R` 负责完整数据、重型计算和持久数据产品；`.Rmd` 负责报告层筛选、可视化与证据锚定的专家解读。新项目默认使用编号根文件及 `raw/`、`products/`、`reports/`；已有 `tmp/` 项目保持原布局，除非用户明确要求迁移。
+ 本 Skill 还负责 Nature 级图表、弱背景读者的指标导读、数字追溯、HTML widget 可见性和跨平台路径。`luckyBase` 是硬依赖。它不替代领域统计判断，不缓存每个临时变量，不默认引入 `targets`/`drake`，也不自动接入 State、Verifier、Pack 或 Gate。
+
## 流程
### 输入
- 输入为项目的 `.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 自动安装/加载包**
-
- ```r
- # 正确做法（强制）
- 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()` 函数：
-
- ```r
- # 正确做法（强制）
- 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 基因` | 结构清晰，读者易定位 |
-
- ##### 实践示例
-
- ❌ 错误示范：
-
- ```markdown
- ## 数据加载与处理（第一步）
-
- ### 单因素筛选 - univ_screen()
-
- #### 结果解读（专家叙事）
- ```
-
- ✅ 正确示范：
-
- ```markdown
- ## 数据加载与处理
-
- ### 单因素筛选
-
- #### 结果解读
- ```
-
- #### 主业与副业分离原则
-
- 硬性要求（最小口径）：
-
- - 采用 `.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_guide.md)
- - 示例：[`references/hybrid_architecture_examples.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`](references/code_block_explanations.md)。
-
- ##### 指标分层与首次解释（必须）
-
- - 先按 `config.yaml:metric_explanation` 盘点指标；默认白名单包括描述统计、p/q/FDR/CI、常见效应量与相关系数、经典生存分析以及 ROC AUC 等经典诊断指标。未命中、无法确定或采用非标准定义时，按不常用指标处理。
- - 只要出现不常用指标，就在首个分析模块前增加“指标导读”表，至少说明尺度/参考点、升降趋势、置信区间或其它不确定性、本次选用理由与判读边界。
- - 不常用指标在结果正文首次出现时，先自然解释“是什么、如何计算、为什么使用、带来什么价值、如何判读”，随后立即结合本次数字解读；第二次起不再重复原理，只解读当前证据。
- - 同名指标的公式、量纲、方向、参考点或时间窗发生变化时，视为新指标并重新解释。常用指标通常不展开教学，但存在反直觉方向或非标准设定时需简短澄清。
-
- 完整分类、表格字段、首次/后续出现协议与边界见 [`references/metric_explanation_protocol.md`](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/four_tier_interpretation_framework.md) / [`references/interpretation_templates.md`](references/interpretation_templates.md) / [`references/interpretation_narrative_examples.md`](references/interpretation_narrative_examples.md)。
- 交付前静态预检（覆盖 + 质量）：
- 1) 图表/表格解读覆盖检验（强制，Fail Fast）：
- ```bash
- # 探索期：仅报告（不阻断）
- 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) 解读质量预检（启发式，推荐）：
- ```bash
- # 探索期：仅提示不阻断
- 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 名单落地、后续动作可执行句、强语气与稳健性约束等），使用：
-
- ```bash
- python3 bensz-rmd-rules/scripts/check_interpretation_quality.py your_report.Rmd --strict
- ```
-
- ###### 禁止代码生成解释
- 解释性文本必须由 AI 直接写出；允许用 `` `r ...` `` 动态嵌入数字以保证精确与同步，但不得通过代码逻辑拼接/生成解释句子。
-
- | 场景 | 允许 | 禁止 |
- |---|---|---|
- | 数字嵌入 | ✅ `` `r sprintf('%.2f', hr)` `` | ❌ 在正文硬写不可追溯数字 |
- | 轻量词语选择 | ✅ `ifelse()` 选择“升高/降低”等词 | ❌ 通过代码拼接完整解释段落 |
- | 结果引用 | ✅ `` `r nrow(tbl)` `` | ❌ `cat()`/字符串拼接输出解释文本 |
-
- ❌ 错误做法（代码生成解释）：
-
- ```r
- interpretation <- ifelse(hr > 1, "提示风险增加", "提示风险降低")
- cat("从统计上看，", interpretation)
- ```
-
- ✅ 正确做法（数字动态、解释直接）：
-
- ```markdown
- 从统计上看，该效应为 `r sprintf('%.2f', hr)`（95% CI: `r ci_low`–`r ci_high`），**提示暴露组风险显著高于参照组**。
- ```
-
- ##### 解读语气与风格
-
- 默认采用“论文口吻”：克制、客观、推论式。避免模板化教学提示与括号解释堆叠。不常用指标首次出现时的必要解释是例外，但应自然融入结果叙述，并从第二次起收敛。
-
- | 维度 | 教学口吻（避免） | 论文口吻（推荐） |
- |---|---|---|
- | 括号使用 | `（即...）` `（注意：...）` | 尽量融入正文，括号主要用于 CI/单位等必要信息 |
- | 提示语 | `提示：` `注意：` | 直接陈述结论与边界，不使用提示标记 |
- | 解释重心 | “这是什么”式定义 | “意味着什么”式推论（绑定本次结果证据） |
- | 语气 | 教导式、向导式 | 克制、客观、可验证 |
-
- ❌ 教学口吻（避免）：
-
- ```markdown
- 该效应为 1.85（95% CI: 1.32-2.59），这表明风险增加。（即：HR > 1 意味着暴露组风险更高）
- 需要注意的是，该结论可能受混杂因素影响。
- ```
-
- ✅ 论文口吻（推荐）：
-
- ```markdown
- 该效应为 `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 模板规范
+ - 研究问题、报告用途、正式交付物和可接受的统计边界；
+ - 原始输入、数据字典、样本/变量含义、隐私限制与只读范围；
+ - 重算成本、外部请求、随机性、关键参数与已有项目布局；
+ - 现有 `.R`、`.Rmd`、`00.Environment.R`、`products/` 或旧 `tmp/` 产物；
+ - 用户已有 R 包与函数。优先 `ccs`、`GSClassifier`、`lucky*`；`candidate_r` 仅在用户已加载或显式给出路径时使用。
- ##### 章节结构（硬门槛）
+ 读取 `config.yaml`。按任务选择 references：
- 每个 `.Rmd` 默认采用以下章节顺序（允许在中间插入具体分析模块，但不要删掉硬门槛章节）：
+ - 新建/重构数据流：[`references/hybrid_architecture_guide.md`](references/hybrid_architecture_guide.md)、[`references/hybrid_architecture_examples.md`](references/hybrid_architecture_examples.md)、[`references/analysis_workflow_cache.md`](references/analysis_workflow_cache.md)；
+ - 审查流程：[`references/serial_review_protocol.md`](references/serial_review_protocol.md)；
+ - R 实现：[`references/code_style_guide.md`](references/code_style_guide.md)、[`references/no_overdefensive_code.md`](references/no_overdefensive_code.md)、[`references/cross_platform.md`](references/cross_platform.md)；
+ - 指标与解读：[`references/metric_explanation_protocol.md`](references/metric_explanation_protocol.md)、[`references/four_tier_interpretation_framework.md`](references/four_tier_interpretation_framework.md)、[`references/interpretation_templates.md`](references/interpretation_templates.md)、[`references/interpretation_narrative_examples.md`](references/interpretation_narrative_examples.md)、[`references/expert_discussion_template.md`](references/expert_discussion_template.md)；
+ - 图表/HTML：[`references/plot_quality_standards.md`](references/plot_quality_standards.md)、[`references/plot_language.md`](references/plot_language.md)、[`references/htmlwidget_visibility_rules.md`](references/htmlwidget_visibility_rules.md)、[`references/liquid_glass_theme_guide.md`](references/liquid_glass_theme_guide.md)；
+ - 生物医学 ID：[`references/gene_id_guidelines.md`](references/gene_id_guidelines.md)；可选函数库：[`references/candidate_r.md`](references/candidate_r.md)。
- - `## 数据概览`
- - `## 关键函数、参数与源代码位置`（**强制**，紧跟“数据概览”之后）
- - `## 指标导读`（条件强制：存在不常用指标时保留；否则删除）
- - （一个或多个）分析模块：如 `## 单因素筛选` / `## 多因素模型` / `## 模型性能与验证` / `## 可视化分析` 等
- - `## 讨论与分析`（强制：主要发现 + 局限 + 可落地后续）
- - `## 数字准确性验证`（强制：末尾检验）
+ 对 `raw/` 只做足以规划的轻量只读盘点；规划阶段不得意外启动完整计算。
- ##### 关键函数、参数与源代码位置（强制）
+ ### 执行步骤
- 该章节的目标是“可追溯性”：让任何读者都能快速定位本报告的关键实现（以及为什么这样设）。
+ #### 1. 建立需求—分析图
- 必须包含：
+ 先列出需求与交付物，再形成分析单元表。每行至少包含：`AA.BB.CC` 编号、目的、上游、输入、主要数据产品、缓存决定、报告关系与完成判据。只有在以下条件成立后才生成代码：
- - 关键的分析过程是什么（按顺序，建议覆盖 3–10 个关键步骤）
- - 用了哪些关键函数（推荐写成 `pkg::fn()`，并注明关键输入/输出对象名）
- - 函数的关键参数是什么；为什么要这么设置（理由必须绑定本次数据/假设/阈值/限制）
- - 源代码在哪个文件的第几行（写项目内的 `.R/.Rmd/_functions.R` 为主；格式建议 `相对路径:行号`）
+ - 每项需求至少映射到一个单元或明确说明不处理；
+ - 依赖无环，且上游编号严格早于下游；
+ - 综合报告晚于其全部输入；
+ - 简单低成本任务保持一个必要单元，不为形式完整强拆步骤或制造缓存。
- 推荐表格模板（直接复制到 Rmd 正文填写）：
+ 编号与文件契约：
- ```markdown
- | 分析过程/产物 | 关键函数/对象 | 关键参数（是什么） | 为什么这样设置（理由） | 源代码位置（文件:行号） |
- |---|---|---|---|---|
- | 数据加载与整理 | `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` |
+ ```text
+ AA.BB.CC. 名称.R
+ AA.BB.CC. 名称_functions.R
+ AA.BB.CC. 名称.Rmd
+ AA.BB.CC. 名称.html
```
- ##### YAML 头部
-
- Rmd 的 YAML 头以 `config.yaml:rmd_template.yaml_header` 为准；`templates/Rmd_template.Rmd` 内保留一份便于起手的拷贝，维护时需与 config 同步（可用 `scripts/check_rmd_template_yaml.py` 校验）。
-
- ##### HTML 主题（Liquid Glass / glassmorphism）
+ 同一单元只创建实际需要的文件；`_functions.R` 不是执行节点。数字元组升序是默认执行顺序。`00.Environment.R` 默认全项目唯一，只负责包加载、项目根路径、全局选项和真正跨单元的配置。
- 默认使用 **Liquid Glass 主题**（`templates/liquid_glass_theme.css`），这是一套 glassmorphism 风格的专业级样式：
- - **Glassmorphism**：玻璃拟态效果，背景模糊与半透明层次
- - **Motionless by Default**：默认无无限动画，避免选中文本/代码时出现"高亮漂移"的干扰
- - **Auto Dark Mode**：根据系统偏好自动切换深色模式
- - **Floating TOC（两种模式）**：静态浮动（常驻）/ 动态浮动（收起为左上角小圆点，悬停展开；默认）；移动端自动折叠，可点击顶部按钮展开
+ #### 2. 确定目录与兼容模式
- **使用方式**：
- - 详细的 YAML 配置、特性说明、自定义选项见 [references/liquid_glass_theme_guide.md](references/liquid_glass_theme_guide.md)（说明文档；具体字段以 `config.yaml:rmd_template.yaml_header` 为准）
- - 一键初始化脚本见下方"一键初始化新项目"
+ 新项目使用以下边界：
- ###### 一键初始化新项目（推荐）
+ | 位置 | 职责 |
+ | --- | --- |
+ | 项目根目录 | `00.Environment.R`、编号 R/functions/Rmd 及同名 HTML |
+ | `raw/` | 用户原始输入；默认只读 |
+ | `products/<流程>/<编号名称>/` | 可恢复、可审查、供下游复用的完整数据产品 |
+ | `reports/figures\|tables\|supplementary/` | 论文可直接使用的正式图、表和补充材料 |
+ | `.bensz-api/` | AI 草案、审查结果、预览与验证日志；不得成为科学数据唯一副本 |
- 本 skill 的默认模板假设你在“项目根目录”存在如下文件：
- - `templates/liquid_glass_theme.css`
- - `templates/liquid_glass_lightbox.html`（图片点击放大 + 刷新后缩放/阅读位置尽量保持）
+ 若现有项目仍以 `tmp/{主脚本名}/` 工作，先识别并保留，不迁移、不覆盖；只有用户明确要求迁移时才建立映射、保留原路径并提供回退。详见架构指南。
- 为避免手工拷贝，推荐在新项目根目录运行（脚本对安装位置不敏感，会基于 `__file__` 自动定位 skill 目录）：
+ #### 3. 设计缓存边界
- ```bash
- python3 /path/to/bensz-rmd-rules/scripts/bootstrap_liquid_glass.py --with-env
- ```
+ 边界在以下任一条件下通常值得缓存：计算昂贵；被多个下游复用；经历高风险/有损转换；需要人工审查；依赖可变外部请求；中断后重做代价高。毫秒内可重建、只服务下一行或纯展示格式的对象不默认缓存。
- 说明：
- - `--with-env` 会在项目根目录创建 `00.Environment.R`（如已存在则跳过）
- - 如需同时复制 DT/主题等常用模板，可加 `--with-extras`
+ 每个持久检查点承担四类职责：
- ##### 表格渲染
+ 1. 可恢复的完整主对象；
+ 2. 人类可读的全量表、受控预览、schema 或 `summary.md`；
+ 3. `metadata.yaml`，记录单元、输入、参数、相关代码、上游身份、输出结构、契约版本和耗时；
+ 4. 所有文件重新读取与完整性检查通过后才写入的 `SUCCESS`。
- ###### 默认规则（HTML：DT 优先）
+ 缓存身份至少覆盖输入摘要、影响本步骤的参数、相关代码摘要、上游产品身份和输出契约版本；必要时加入会改变结果的 R/包版本。时间戳不得进入身份。使用 `templates/checkpoint_helpers.R` 提供的路径、摘要、命中判断和“临时文件 → 验证 → 正式文件 → SUCCESS”协议，不即席复制一套 helper。
- 当输出格式为 **HTML** 时，所有“数据表/结果表”（R 代码生成的 `data.frame`/`tibble`）默认使用 **DT**（`DT::datatable()`）进行渲染，除非用户明确指定使用其他表格方案（如 `knitr::kable()` / `gt` / `flextable` / `reactable` 等）。
+ #### 4. 实现计算层与报告层
- 推荐做法（优先）：
+ - 所有包在 `00.Environment.R` 中经 `luckyBase::Plus.library()` 加载；分析脚本优先用 `pkg::fn()`。基因 ID 转换使用 `luckyBase::convert()`。
+ - `.R` 读取 `raw/` 或上游 `products/`，保留未经报告阈值筛选的完整结果，并写入自己的产品目录。
+ - 报告阈值、Top N、配色和展示策略放在 `.Rmd` YAML `params`；修改这些参数只重渲染报告，不使重型产品失效。
+ - `.Rmd` 从 `products/` 读取全量结果；正式图表写 `reports/`，同名 HTML 留在根目录。图表标题由 Rmd 小节与图注承担，默认不在图内重复标题。
+ - 只在 I/O 边界和硬前提做明确检查；不以占位代码、静默降级或过度防御掩盖失败。
+ - 涉及不常用、任务自定义或非标准定义指标时，先写指标导读，首次完整解释，后续只解释当前证据；同名指标定义变化时重新解释。
- - 在项目根目录的 `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 可见性硬规则”。
+ 简单单报告从 `templates/Rmd_simple_template.Rmd` 起步，直接只读 `raw/`，不创建 plan、checkpoint 或 runner 链路。多阶段分析再使用 `analysis_plan_template.yaml`、`R_data_template.R`、`functions_template.R`、`Rmd_template.Rmd` 和 `00.Environment.R`，并把 `templates/checkpoint_helpers.R` 复制到用户项目同名路径；可用 `bootstrap_liquid_glass.py --with-extras` 安全复制，默认不覆盖。已有文件只增量修改。图表、DT、plotly 和主题 helper 按需复制，不创建未使用的模板文件。
- 最小示例：
+ #### 5. 在真实昂贵运行前串行审查
- ```r
- # 00.Environment.R（强制）
- luckyBase::Plus.library("DT")
+ 主 Agent 完成全部初稿后，按顺序启动三个新的、彼此独立且只读的子 Agent：
- # in .Rmd（HTML）
- source(file.path("templates", "datatables_helper.R"))
- render_dt(head(df, 100), pageLength = 10) # 让它成为 chunk 的最后表达式
- ```
+ 1. 结构与数据流：需求覆盖、编号、依赖、目录、缓存边界、`raw/` 只读；
+ 2. R 实现与恢复：对象生命周期、路径、随机性、缓存身份、原子落盘、损坏识别、断点恢复；
+ 3. 科学与统计：方法、偏差/混杂、多重检验、数据泄漏、模型假设、不确定性、结论边界。
- ###### HTML 可见性硬规则（htmlwidget/DT，强制）
+ 每轮读取主 Agent 修正后的最新版本，只输出问题、证据和建议；只有主 Agent 修改文件。记录“通过”也是有效结论，不制造形式性修改。完整权限与降级规则见串行审查协议。
- R Markdown 渲染为 HTML 时，`DT::datatable()` 等 htmlwidget 必须作为 code chunk 的“可见结果”返回，否则容易出现“代码在但不渲染”的漏项。
+ #### 6. 运行、缓存命中与恢复
- 硬规则与示例见：[references/htmlwidget_visibility_rules.md](references/htmlwidget_visibility_rules.md)。
+ 存在 `analysis-plan.yaml` 和编号 `.R` 计算节点时，先从已安装 Skill 根目录运行 `<skill-root>/scripts/check_analysis_workflow.py <项目根> --plan analysis-plan.yaml`；首次正式运行或交付前使用 `--strict`。获得真实运行授权后，用 `<skill-root>/scripts/run_analysis_workflow.py` 按编号遍历计算节点。简单无缓存报告跳过本步骤；旧 `tmp/` 项目不补 plan、不调用 runner，只运行不带 `--plan` 的 checker 并沿用原项目入口。
- ###### 交付前强制检查（强制）
+ 编号计算流遵循：
- 交付前必须先通过“图表/表格解读覆盖检验”，避免出现“有输出但无解读”的漏项：
+ - 身份和完整性均匹配：记录 `cache hit`，读取产品；
+ - 缺少 `SUCCESS`、元数据/输出损坏或身份变化：当前单元重算；
+ - 上游身份变化：必要下游自然失效；不相关的更早单元继续复用；
+ - “从某步恢复”仍按顺序记录更早步骤命中，再从失败边界执行；
+ - 强制重算和恢复控制属于计算层，不写入 Rmd YAML。
```bash
- python3 bensz-rmd-rules/scripts/check_figure_table_interpretation.py path/to/your.Rmd --strict
+ python3 <skill-root>/scripts/run_analysis_workflow.py <项目根> --force-step 01.00.00
+ python3 <skill-root>/scripts/run_analysis_workflow.py <项目根> --resume-from 01.00.00
```
- 交付前必须运行一次 htmlwidget 可见性静态检查，避免出现“代码在但 HTML 不出表/不出图”的漏项：
+ 严禁仅因文件存在就命中缓存。失败单元不得留下 `SUCCESS`，已成功的前序产品保留。
- ```bash
- python3 bensz-rmd-rules/scripts/check_htmlwidget_visibility.py path/to/your.Rmd
- ```
+ #### 7. 完成报告与交付
- ##### 输出 HTML
+ 图表默认英文；中文期刊等场景通过 `params.plot_language` 显式切换。静态正式图保存矢量 PDF，生成 JPG 预览并逐图检查裁切、字体、线点、图例、密度与配色；预览进入任务工作区，不进入正式报告目录。
- 使用 `knit-rmd-html` skill 将 Rmd 渲染为同名 HTML，保存在同级目录。
+ 每个可见图/表附近写基于当前数据的连贯解读：对象 + 方向/对比 + 可追溯数值 + 量级含义；关键结果补不确定性、可证伪推理和“方法 + 输入 + 判据”的后续。允许 `` `r ...` `` 嵌入数字，不允许代码拼接解释段落。
### 输出
- 输出包括遵循主业/副业分离的 `.R`、`.Rmd`、同名 HTML、图表/表格及数字准确性验证结果；分析过程、检查报告和临时文件按本 Skill 的 `.bensz-api` 工作区规则保存，不把中间结果混入源文件目录。
+ 按复杂度交付：分析单元表、唯一 `00.Environment.R`、必要的编号 `.R`/`_functions.R`/`.Rmd`、同名 HTML、`reports/` 正式材料，以及验证摘要。只有多阶段计算流才交付 `analysis-plan.yaml` 和 `products/` 数据产品；简单任务只产生最小必要集合。
### 输出管理
- #### BenszAPI 任务工作区
-
+ 正式代码、Rmd/HTML、科学数据产品和报告留在用户项目约定位置。AI 输入引用、草稿、三轮审查、JPG 预览、命令和验证日志进入本轮唯一 `.bensz-api/task-*` 工作区。`raw/` 不写入；`products/` 不保存只服务本轮 Agent 的草稿；`reports/` 不放 Rmd、HTML、模型缓存或审查日志。
### 校验
- #### 图表质量规范（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` 约束）。
-
- 示意结构（每张图都应遵循；可按场景增删参数，但必须保留“集中参数块 + 注释说明”口径）：
-
- ```r
- # ==== 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
- )
+ ```bash
+ python3 <skill-root>/scripts/check_analysis_workflow.py <项目根> --plan analysis-plan.yaml --strict
+ python3 <skill-root>/scripts/check_rmd_template_yaml.py
```
- 落地要点：
-
- - 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)。
-
- 常见可读性问题场景与可复制最小示例见：[references/plot_quality_standards.md](references/plot_quality_standards.md)。
-
- #### 数字准确性验证（末尾检验）
-
- 每个 `.Rmd` 的末尾应包含“数字准确性验证”章节，确保解读中的关键数字可追溯到变量/计算逻辑，并优先使用 `` `r ...` `` 动态嵌入以避免漂移。
-
- 模板与规范见：[references/numeric_accuracy_verification.md](references/numeric_accuracy_verification.md)。
-
- #### 交付验证（强制）
+ 简单报告和旧 `tmp/` 项目不要求 plan/runner；旧项目可用 `--legacy` 显式确认兼容模式。所有 Rmd 报告继续执行：
- 交付前必须附带自检报告（含“解读-代码一致性”证据）。
+ ```bash
+ python3 <skill-root>/scripts/check_figure_table_interpretation.py <报告.Rmd> --strict
+ python3 <skill-root>/scripts/check_interpretation_quality.py <报告.Rmd> --strict
+ python3 <skill-root>/scripts/check_htmlwidget_visibility.py <报告.Rmd>
+ Rscript <skill-root>/scripts/check_plot_readability.R <正式图.pdf> --render-jpg --out-dir <任务根>/bensz-rmd-rules/output/plot-check
+ ```
- 模板与真实示例入口见 `[references/delivery_verification.md](references/delivery_verification.md)`。
+ 按项目实际情况再执行 R 语法/运行、Rmd 渲染、PDF/JPG 视觉检查和数字追溯。检查清单见 [`references/workflow_checklist.md`](references/workflow_checklist.md)，交付证据格式见 [`references/delivery_verification.md`](references/delivery_verification.md)，数字规则见 [`references/numeric_accuracy_verification.md`](references/numeric_accuracy_verification.md)，代码块说明见 [`references/code_block_explanations.md`](references/code_block_explanations.md)，图表覆盖判据见 [`references/figure_interpretation_criteria.md`](references/figure_interpretation_criteria.md)。
- #### 工作流检查清单
+ 最低验收：
- 内部检查清单见 `[references/workflow_checklist.md](references/workflow_checklist.md)`。
+ - 编号、依赖、同词干文件、产品目录和报告文件可相互定位；
+ - 相同输入重跑命中缓存，参数/代码/上游变化只失效必要下游；
+ - 中途失败无 `SUCCESS`，损坏缓存不会被误命中；
+ - 修改报告阈值/配色不触发重型计算；
+ - 删除 `.bensz-api/` 不影响正式流程重跑；
+ - 旧 `tmp/` 项目未被隐式迁移；
+ - 三轮审查及轮间修正可追溯，或按规则明确披露降级。
### 失败与恢复
- 缺少 `luckyBase`、R 包/模板、输入文件或渲染依赖时，保留命令输出和检查报告并停止相应阶段；图表/表格解读或 HTML 可见性门禁未通过时先修复或明确阻塞，不把未验证结果交付为完成。可在同一任务工作区重试。
-
+ - 缺少 `luckyBase`：立即停止并说明安装前提，不改用另一套包管理逻辑。
+ - 需求、数据字典或统计边界不足：完成安全的只读盘点与待确认分析图，不启动昂贵计算。
+ - 缓存不完整、哈希不符或无法解析：视为 miss，保留证据，重算该单元及必要下游；不手工伪造 `SUCCESS`。
+ - Rmd 渲染失败：保留 `.Rmd`、计算层产品和日志，从报告层恢复，不重跑无关计算。
+ - 宿主无子 Agent：披露降级，按三个职责串行自检并明确“非独立审查”；用户明确要求真实多 Agent 或任务高风险时停止在运行前。
+ - 已有项目冲突：不覆盖、不迁移；旧 `tmp/` 项目沿用原运行入口，不因新 checker 补建 plan；仅提供增量修改或显式迁移方案。
## 约束
<!-- BEGIN COMMON CONSTRAINTS -->
<!-- Source-Hash: sha256:15120201e9e0c7569517261d57ecefb63ac279c26ed13876f8e95b6dc35854d3 -->
<!-- Template-ID: skill-common-constraints; Template-Version: 1; Sync-Policy: exact-block -->
### 公共硬约束
本块由 `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 源码。
<!-- End of canonical common constraints. -->
<!-- END COMMON CONSTRAINTS -->
+
+ ### Skill 专属约束
+
+ - 仅在授权范围内只读盘点和读取 `raw/` 输入；不修改、覆盖或向 `raw/` 写入。不在日志或元数据记录绝对私有路径、凭据或不必要的原始数据。
+ - 不因本 Skill 提供模板就强制创建全部文件；分析复杂度、缓存边界和报告数量由真实需求决定。
+ - 不把业务统计规则写入通用 checkpoint helper；helper 只处理路径、摘要、身份、完整性与安全落盘。