| name | consulting-delivery |
| description | 把已完成并验证的 R 或 Python 分析打包为客户可独立复现、可直接阅读且保留真实溯源的咨询交付物。用于“给客户交付”“打包结果”或在 05_reports/ 建正式结果包；不用于未完成分析或内部探索。上游为 biostat-principles，文本终审配合 academic-humanizer，签发配合 epi-project-audit。
|
咨询交付包标准 skill
目标：客户拿到一个 zip → 不问任何问题 → 运行 run_all.R 或 run_all.py → 重现全部结果 → 打开 01_方法与结果.docx 直接阅读。
不触发的情况：自己研究用的中间产物、实验性脚本、不打算外发的结果。
一、分享包与主流程的关系（防漂移，CRITICAL）
分享包按来源分三类，处理方式不同：
| 类型 | 含义 | 真源在哪 | 做法 |
|---|
| (a) 主流程搬运 | 把主流程已有结果/论文打包外发 | 主流程 | 分享包是主流程的导出快照，零手改；要改内容先改主流程再重导出 |
| (b) 补充结果 | 主流程没有、为这次分享新做的分析 | 分享包或主流程 | 若进论文/长期用 → 写成主流程编号脚本；纯一次性 → 09_backup/ |
| (c) 尝试/探索 | 试新方法 | 09_backup/<日期>_*/ | 验证有效才合并进主流程（biostat-principles §7）；从不直接进分享 |
核心原则：单一真源，分享包是派生物不是手改终点。
- 口径常量集中一处：有序水平、P 值格式、表组成、配色、字体和 registry 放入所选语言的
02_code/conventions.* 与 config.*。主流程与导出脚本共用该单源。
- 分享包由导出脚本生成：写与主流程同语言的
02_code/NN_export_<topic>.* 或正式项目归档区的一次性脚本，自动建目录、复制数据/表/图、清理意外调试痕迹并生成文档。要改内容先改主流程源再重导出。
- 冻结部分例外：已发表/冻结的产物不套用新口径，在 DECISIONS 记为豁免。
- 防漂移两条硬规则：① 分享包
00_说明.md 记一行"由 <脚本> 于 <日期> 从主流程导出"；② 用户在分享包里提的修改意见必须回写主流程源 + 所选语言的 conventions 文件，不能只改分享包。
- 若确实只想改分享、不动主流程：在该包
00_说明.md 注明"脱离主流程的定制版，未回写"，并记 DECISIONS.md。
二、交付包状态机
[R 或 Python 分析已完成并验证]
↓
[SCAFFOLD] 建交付包骨架（scripts/consulting_scaffold.R）
↓
[MIGRATE] 迁移数据/脚本/表/图进包
↓
[ISOLATE] 改路径，让包自包含、不依赖项目根
↓
[RUN_ALL] 按主流程语言写 run_all.R 或 run_all.py
↓
[REPRODUCE] 空 R session 或干净 Python 环境实测跑通
↓ ↓ 不通过回到 ISOLATE
[WRITE] 写 00_客户说明.md + 01_方法与结果.docx（模板见 references/templates.md §3-4）
↓
[ACADEMIC_EDIT] academic-humanizer 扫全包
↓
[FINAL] 终检 + 压缩 + 交付
每阶不通过不许进入下一阶。REPRODUCE 失败必须回退修路径，不能靠在自己电脑上跑通蒙混。
三、命名与编号
| 对象 | 格式 | 示例 |
|---|
| 文件夹 | 结果-M-D[-主题]（用户指定名优先） | 结果-4-20-训练测试集 |
| 压缩包 | 同文件夹名 .zip | 结果-4-20-训练测试集.zip |
| 包内脚本 | NN_描述.R 或 NN_描述.py 从 01 起 | 01_data_prep.R |
| 包内表 | TableN_描述.xlsx（或 TN_/TSN_） | Table1_baseline.xlsx |
| 包内图 | FigN_描述.pdf/.png（或 FN_/FSN_） | Fig2_forest.pdf |
禁止命名：最终版、最新、final2、new、修订、v2、修改后。05_reports/ 同一主题只保留一个当前包；反馈迭代前先把上一交付批次整包归档，再在当前包路径重建。用户明确要求日期入名时可更新当前包日期，但旧日期包不得继续留在 05_reports/。
包内编号连续性（CRITICAL，与项目主文件夹同一标准）：
data/（含子目录）、tables/、figures/ 内所有文件及 code/ 的分析脚本一律带编号前缀且从 01（或 T1/F1）起连续，包括复制进来的原始数据与质性材料；code/config.*、code/conventions.* 作为单源 helper 不编号。- 任何合并 / 增删 / 改名后立即重排补号，不许断号或跳号残留；脚本输出路径与脚本头注释同步改。
- 同主题多张表合并为单 xlsx 多 sheet，合并后下游编号顺延重排。
- docx 正文"表 N / 图 N"引用与包内文件编号保持一致，重排后同步改正文。
四、标准目录结构（CRITICAL）
05_reports/结果-4-20-训练测试集/
├── 00_客户说明.md ← 逐文件清单（模板 §3）
├── 01_方法与结果.docx ← 可直接阅读的方法+结果（要求 §4）
├── run_all.R / run_all.py ← 与主流程语言一致的一键复现入口
├── README.md ← 文件清单（可选）
├── data/ ← 本包需要的数据（编号从 01 起）
├── code/ ← config.* / conventions.* + 包内分析脚本，从 01 起
├── results/ ← 中间数据（xlsx，按内容命名不编号；禁 rds/RData）
├── tables/ ← TableN_*.xlsx
└── figures/ ← FigN_*.pdf + .png
根目录只允许上面这些内容。散落 .csv、截图、缓存、临时稿 → 全部清出或移入子目录。
骨架用 scripts/consulting_scaffold.R 的 create_delivery_pack("结果-4-20-主题", language = "R") 或 language = "python" 创建。
五、复现入口与包内脚本核心要求
完整模板见 references/templates.md §1-2；不可妥协的要求：
- R 包在空 R session 中运行
run_all.R；Python 包在用户选定的隔离环境中按锁定依赖运行 run_all.py。入口必须检查工作目录并按编号执行脚本。
- 脚本之间只靠
results/*.xlsx 传表格化数据，不靠环境变量；禁 rds/RData；模型对象不跨脚本传（留在产出它的脚本内、只导出结果表）。
- R 脚本声明完整
library()；Python 包提供 requirements.txt 或项目锁文件。全部路径相对，不读包外文件，不写死 setwd() 或绝对路径。
- 模板与输出内禁 emoji，状态用文字。
- 复现检查只使用本机已有的兼容 R/Python 环境。若环境或依赖缺失，停止检查并说明缺什么、影响什么以及用户可如何准备；不得创建虚拟环境或执行安装、升级命令。
六、REPRODUCE 阶段（强制）
cp -r "05_reports/结果-4-20-训练测试集" /tmp/test_pack
Rscript --vanilla -e "setwd('/tmp/test_pack'); source('run_all.R')"
/path/to/existing/environment/python /tmp/test_pack/run_all.py
Windows 使用用户已准备好的隔离环境中的 python.exe 执行同一流程。通过标准：复现入口无 error；所有预期 table / figure 都生成；数字与原 03_tables/ 完全一致。
不通过 → 多是路径硬编码、依赖未声明、脚本顺序隐式依赖；回 ISOLATE 修。
七、ACADEMIC_EDIT 阶段（CRITICAL）
docx 写完后必须过 academic-humanizer（不可变事实清单 → 模式审计 → 最小改写 → 证据与语体复核）。本阶段交付包特有的补充：
- 不篡改真实溯源：不得修改分析数据、审计字段、作者身份、工具使用或法规、期刊、合同要求披露的事实。扫描 csv/xlsx 仅用于发现意外调试文本、临时内部标签和不应外发的非分析字段；命中后先判定字段语义。
- 非分析审计字段只有在不影响结果、合同允许且导出 manifest 记录字段名与排除理由时，才可从外发副本排除；主流程源保持不变。无法判断是否应披露时保留并向用户报告。
- 全包（md / docx / 表 / 代码注释）禁 emoji；扫描用 perl Unicode 区间
[\x{1F300}-\x{1FAFF}\x{2600}-\x{27BF}]（sed 对多字节 emoji 不可靠）。
- docx 禁出现的内容（版本号 / 内部变量名 / 调试痕迹等）见
references/templates.md §4。
交付目标：研究者视角、方法与结果准确、责任和工具披露真实、复现路径完整。后续修改按 §九 从主流程重生当前包。
八、FINAL 阶段 · 终检清单
发出去之前逐项对照：
可复现
可读
不露生成过程痕迹
编号
目录干净
安全
九、版本迭代规则
客户反馈后要改结果 → 先把上一版文件夹、同名 zip、对应主流程旧代码与核验记录整组移入 09_backup/YYYY-MM-DD_HHMM_<主题>_<反馈阶段>/，保留原相对目录并写 MANIFEST.md；随后在 05_reports/ 重建唯一当前包，并在 09_backup/INDEX.md 顶部登记归档时间、目录、当前包路径和原因。
05_reports/
└── 结果-5-02-训练测试集/ ← 唯一当前交付包
09_backup/2026-05-02_1430_训练测试集_客户反馈/
├── MANIFEST.md
└── 05_reports/
├── 结果-4-25-训练测试集/
└── 结果-4-25-训练测试集.zip
禁止：未留快照就覆盖上一版、用 final_v2 命名、让多个日期包并列留在 05_reports/、只归档成品却遗漏与该版绑定的代码或核验记录。
十、与其他 skill 的协作 + 常见问题
| 上游 | 本 skill 做什么 | 下游 |
|---|
biostat-principles 原则 6（可复现） | 落实为语言匹配的复现入口 + 实测 | — |
r-biostats 或 python-biostats 完成分析 | 打包、改路径、写客户文档 | academic-humanizer 做不可变事实清单、证据强度与学术语体审校 |
project-init --consulting | 骨架已建 | 本 skill 做后续填充 |
| 常见问题 | 原因 | 预防 |
|---|
| 客户打开报错 | 路径硬编码 / 没锁定依赖 | REPRODUCE 必做 + 语言对应的依赖清单 |
| docx 数字和 xlsx 对不上 | 结果改了 docx 没更新 | 每次改分析重跑 docx 生成脚本 |
| 中文 PDF 乱码 | 用了默认 pdf() | 统一 cairo_pdf |
| 字体在客户电脑变形 | 本地特殊字体 | Times New Roman + 宋体 |
| 客户说"看不懂" | docx 太技术 | 00_客户说明.md 写明看哪里 |
| 文风模板化、缺少研究者声纹 | 套话太多 | ACADEMIC_EDIT 阶段不跳过 |
| 返工多次 | 开工没对齐口径 | biostat-principles 原则 1 严格执行 |
reference 导航
| 文件 | 何时读 | 内容 |
|---|
references/templates.md | R 包 RUN_ALL / WRITE 阶段 | run_all.R 模板、包内脚本头部模板、00_客户说明.md 模板、01_方法与结果.docx 结构与禁词表 |
scripts/consulting_scaffold.R | SCAFFOLD 阶段 | create_delivery_pack() 一键建骨架 |
