bensz-rmd-rules · git:20260917.6e753cd · 2026-09-17 · sha256 c9dd338b1ab7ed77
bensz-rmd-rules git:20260917.6e753cdA
Immutable. This exact content never changes and is served at /api/v1/blob/c9dd338b1ab7ed77.
---
name: bensz-rmd-rules
description: 当用户要求编写或维护 R Markdown、R 分析脚本、可复现数据分析，尤其涉及多阶段计算、缓存复用、断点恢复或论文级图表与解读时使用。负责规划分析单元、组织 R/Rmd 数据流、验证缓存与交付质量；不用于仅渲染既有 Rmd 或其它语言的数据分析。
metadata:
author: Bensz Conan
short-description: R/Rmd 多阶段分析、可恢复数据产品与论文级报告规范
keywords:
- bensz-rmd-rules
- R Markdown
- Rmd
- 数据分析
- 断点续算
- 可复现报告
---
# bensz-rmd-rules
## 目标
先理解研究目标与数据，再把任务组织为可审查、可恢复的 R 分析单元。`.R` 负责完整数据、重型计算和持久数据产品；`.Rmd` 负责报告层筛选、可视化与证据锚定的专家解读。新项目默认使用编号根文件及 `raw/`、`products/`、`reports/`；已有 `tmp/` 项目保持原布局，除非用户明确要求迁移。
本 Skill 还负责 Nature 级图表、弱背景读者的指标导读、数字追溯、HTML widget 可见性和跨平台路径。`luckyBase` 是硬依赖。它不替代领域统计判断，不缓存每个临时变量，不默认引入 `targets`/`drake`，也不自动接入 State、Verifier、Pack 或 Gate。
## 流程
### 输入
确认以下信息；已有上下文足够时直接提取，不重复询问：
- 研究问题、报告用途、正式交付物和可接受的统计边界；
- 原始输入、数据字典、样本/变量含义、隐私限制与只读范围；
- 重算成本、外部请求、随机性、关键参数与已有项目布局；
- 现有 `.R`、`.Rmd`、`00.Environment.R`、`products/` 或旧 `tmp/` 产物；
- 用户已有 R 包与函数。优先 `ccs`、`GSClassifier`、`lucky*`；`candidate_r` 仅在用户已加载或显式给出路径时使用。
读取 `config.yaml`。按任务选择 references：
- 新建/重构数据流：[`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` 编号、目的、上游、输入、主要数据产品、缓存决定、报告关系与完成判据。只有在以下条件成立后才生成代码：
- 每项需求至少映射到一个单元或明确说明不处理；
- 依赖无环，且上游编号严格早于下游；
- 综合报告晚于其全部输入；
- 简单低成本任务保持一个必要单元，不为形式完整强拆步骤或制造缓存。
编号与文件契约：
```text
AA.BB.CC. 名称.R
AA.BB.CC. 名称_functions.R
AA.BB.CC. 名称.Rmd
AA.BB.CC. 名称.html
```
同一单元只创建实际需要的文件；`_functions.R` 不是执行节点。数字元组升序是默认执行顺序。`00.Environment.R` 默认全项目唯一，只负责包加载、项目根路径、全局选项和真正跨单元的配置。
#### 2. 确定目录与兼容模式
新项目使用以下边界：
| 位置 | 职责 |
| --- | --- |
| 项目根目录 | `00.Environment.R`、编号 R/functions/Rmd 及同名 HTML |
| `raw/` | 用户原始输入；默认只读 |
| `products/<流程>/<编号名称>/` | 可恢复、可审查、供下游复用的完整数据产品 |
| `reports/figures\|tables\|supplementary/` | 论文可直接使用的正式图、表和补充材料 |
| `.bensz-api/` | AI 草案、审查结果、预览与验证日志；不得成为科学数据唯一副本 |
若现有项目仍以 `tmp/{主脚本名}/` 工作，先识别并保留，不迁移、不覆盖；只有用户明确要求迁移时才建立映射、保留原路径并提供回退。详见架构指南。
#### 3. 设计缓存边界
边界在以下任一条件下通常值得缓存：计算昂贵；被多个下游复用；经历高风险/有损转换；需要人工审查；依赖可变外部请求；中断后重做代价高。毫秒内可重建、只服务下一行或纯展示格式的对象不默认缓存。
每个持久检查点承担四类职责：
1. 可恢复的完整主对象；
2. 人类可读的全量表、受控预览、schema 或 `summary.md`；
3. `metadata.yaml`，记录单元、输入、参数、相关代码、上游身份、输出结构、契约版本和耗时；
4. 所有文件重新读取与完整性检查通过后才写入的 `SUCCESS`。
缓存身份至少覆盖输入摘要、影响本步骤的参数、相关代码摘要、上游产品身份和输出契约版本；必要时加入会改变结果的 R/包版本。时间戳不得进入身份。使用 `templates/checkpoint_helpers.R` 提供的路径、摘要、命中判断和“临时文件 → 验证 → 正式文件 → SUCCESS”协议，不即席复制一套 helper。
#### 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/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. 在真实昂贵运行前串行审查
主 Agent 完成全部初稿后，按顺序启动三个新的、彼此独立且只读的子 Agent：
1. 结构与数据流：需求覆盖、编号、依赖、目录、缓存边界、`raw/` 只读；
2. R 实现与恢复：对象生命周期、路径、随机性、缓存身份、原子落盘、损坏识别、断点恢复；
3. 科学与统计：方法、偏差/混杂、多重检验、数据泄漏、模型假设、不确定性、结论边界。
每轮读取主 Agent 修正后的最新版本，只输出问题、证据和建议；只有主 Agent 修改文件。记录“通过”也是有效结论，不制造形式性修改。完整权限与降级规则见串行审查协议。
#### 6. 运行、缓存命中与恢复
存在 `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 <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
```
严禁仅因文件存在就命中缓存。失败单元不得留下 `SUCCESS`，已成功的前序产品保留。
#### 7. 完成报告与交付
图表默认英文；中文期刊等场景通过 `params.plot_language` 显式切换。静态正式图保存矢量 PDF，生成 JPG 预览并逐图检查裁切、字体、线点、图例、密度与配色；预览进入任务工作区，不进入正式报告目录。
每个可见图/表附近写基于当前数据的连贯解读：对象 + 方向/对比 + 可追溯数值 + 量级含义；关键结果补不确定性、可证伪推理和“方法 + 输入 + 判据”的后续。允许 `` `r ...` `` 嵌入数字，不允许代码拼接解释段落。
### 输出
按复杂度交付：分析单元表、唯一 `00.Environment.R`、必要的编号 `.R`/`_functions.R`/`.Rmd`、同名 HTML、`reports/` 正式材料，以及验证摘要。只有多阶段计算流才交付 `analysis-plan.yaml` 和 `products/` 数据产品；简单任务只产生最小必要集合。
### 输出管理
正式代码、Rmd/HTML、科学数据产品和报告留在用户项目约定位置。AI 输入引用、草稿、三轮审查、JPG 预览、命令和验证日志进入本轮唯一 `.bensz-api/task-*` 工作区。`raw/` 不写入；`products/` 不保存只服务本轮 Agent 的草稿；`reports/` 不放 Rmd、HTML、模型缓存或审查日志。
### 校验
交付前按适用模式完成检查。编号计算流额外执行：
```bash
python3 <skill-root>/scripts/check_analysis_workflow.py <项目根> --plan analysis-plan.yaml --strict
python3 <skill-root>/scripts/check_rmd_template_yaml.py
```
简单报告和旧 `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
```
按项目实际情况再执行 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)。
最低验收：
- 编号、依赖、同词干文件、产品目录和报告文件可相互定位；
- 相同输入重跑命中缓存，参数/代码/上游变化只失效必要下游；
- 中途失败无 `SUCCESS`，损坏缓存不会被误命中；
- 修改报告阈值/配色不触发重型计算；
- 删除 `.bensz-api/` 不影响正式流程重跑；
- 旧 `tmp/` 项目未被隐式迁移；
- 三轮审查及轮间修正可追溯，或按规则明确披露降级。
### 失败与恢复
- 缺少 `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 只处理路径、摘要、身份、完整性与安全落盘。