qPCR Kit

一个 145 KB 的 HTML 文件，同时是三样东西：能用的分析工具、能交给 agent 的技能、能照着造同类工具的规范。

仪器原始表 → ΔΔCt → 统计检验 → 图 → Excel / JSON，全部在浏览器里跑完。 没有服务端、没有 CDN、没有构建步骤、没有网络请求。双击打开，断网可用。

▶ 三分钟介绍片（讲原理 + 演示用法）：qpcr-kit-intro.mp4

---

三合一

	是什么	给谁用	在哪
① 工具	拖入仪器导出表，自动认列 → 96 孔板框选分组 → ΔΔCt + 检验 + 图 → 导出	做实验的人	qpcr.html 页面本身
② 技能	内嵌 SKILL.md + 无头执行器 + JSON Schema。把 HTML 原样发给 agent，它自己抽出来就能跑	AI / 自动化	HTML 里的 script#qpcr-skill 等四块
③ 规范	五层结构 + 10 条硬规则 + 门禁清单 + 骨架生成器。换一种实验数据，照它再造一个同类工具	想造工具的人	spec/ 与 HTML 里的 script#qpcr-spec

三样东西装在同一个文件里，版本永远同源——不会出现"技能说的和工具做的不是一回事"。

快速开始（人）

1. 下载 qpcr.html，双击用浏览器打开（Chromium / Edge / Chrome 均可）
2. 把仪器导出的 .xlsx / .csv 拖进页面
3. 在 96 孔板上拖框分组，给组起名，指定内参和校准组
4. 看结果：ΔCt 逐孔表、倍数变化、正态性 / 方差齐性、检验结果、诊断警告
5. 导出 Excel（保留原表 + 追加列）、CSV、PNG、或 qpcr-plate/v1 JSON

examples/pcr2301.xlsx 是一份真实的 Bio-Rad CFX 导出（67 孔，靶标 Gnai2，内参 actin），可以直接拿来试。详见 examples/README.md。

快速开始（agent）

不需要装任何东西——把 qpcr.html 发给它就行。文件里第 0 节写着它是谁、有什么、下一步做什么。 如果要在这台机器上跑，两条命令：

# 1) 抽出执行器（SKILL.md 第 1 节里的脚本，按边界注释切，不按标签名切）
python3 - <<'EOF'
import re
h = open('qpcr.html', encoding='utf-8').read()
for k, out in {'skill':'SKILL.md','runner':'qpcr-run.js','schema':'qpcr-plate.schema.json','spec':'SPEC.md'}.items():
    body = re.search(r'<!--QPCR-KIT:%s-->(.*?)<!--/QPCR-KIT:%s-->' % (k, k), h, re.S).group(1)
    open(out, 'w', encoding='utf-8').write(body.strip() + '\n')
EOF

# 2) 先看数据形态，别急着算
node qpcr-run.js --html qpcr.html --data examples/pcr2301.xlsx --inspect

执行器只做一件事：载入页面 → 注入文件 → 调 window.QPCR → 取回 JSON。 它不重写算法——和手工点按钮走的是同一份代码，所以结果逐位一致。

拿到数据形态后，写一份 spec 再跑：

{
  "ref": "actin",
  "calibrator": "Control",
  "test": "welch",
  "groups": { "Control": ["A01","A02","B01","E01","F01"], "Treat": ["A07","A08","B07","E07","F07"] }
}

node qpcr-run.js --html qpcr.html --data 数据.xlsx --spec spec.json --out result.json

依赖只有 playwright-core + 任意 Chromium；路径可用 QPCR_PLAYWRIGHT / QPCR_CHROME 指定。

三件事只能问人，不要猜

程序里没有任何信息能推出实验设计。内参是哪个、哪组是校准组、哪些孔属于哪个组—— 这三件事猜错，结果是"看起来对"的错。内嵌的 SKILL.md 第 3 节给了问法模板。

造同类工具

同一个文件里还嵌了一份《科研数据工具开发规范》，仓库里带着生成器：

python3 spec/newtool.py --dir my-tool --name MyAssay --id assay-x/v1 --title "某实验数据分析器"
cd my-tool && npm install && python3 build.py

生成的骨架一出生就带着：五层结构（解析 / 计算 / 统计 / 呈现 / 交接）、一份声明同时产出 TypeScript 类型 + 运行时校验 + JSON Schema、window 单一出口、四条门禁。 spec/demo-tool/ 就是它生成的样例，可以直接打开看。

规范的核心不是"分层好看"，是这三条：

• 只信任两处边界（文件入口、用户输入），其余一律窄类型
• 一条公式只有一个入口，界面和 agent 走同一个函数
• agent 要读的内容内嵌进产物，不要另发一份会过期的说明书

它具体做了什么

环节	能力
读	xlsx / csv；长表、宽表、QuantStudio 汇总表、Bio-Rad CFX 导出（Sample 列全空也能读）、脏数据（Undetermined / N/A / 大小写混杂）；多 sheet 切换
认	自动识别孔位、样本名、基因、Ct、重复列；排除 Ct Mean / Ct SD / Quantity 这类派生列；内参名可从样本名里拆（CON-IL6）
分	名称列切组、Replicate 列合并技术重复、96 孔板拖框分组、按行/列批量选、组名可改可撤
算	ΔCt、ΔΔCt、2^-mean(ΔΔCt)；几何均值与逐孔算术均值并列；孔位配对（同孔 / 同列 / 同块相对位置 / 顺序）
检	Welch t、Student t、Mann-Whitney U、配对 t、Wilcoxon；三组以上 ANOVA / Welch ANOVA / Kruskal-Wallis + 两两事后 + Bonferroni / Holm / BH
诊	Anderson-Darling 正态性、Levene / Brown-Forsythe 方差齐性、Grubbs 离群孔（点名到 C09）、MAD 提示、内参漂移、Ct > 35、零方差
出	柱状图（非对称误差棒、y 轴稳健截断、PNG 2×）、5 个 sheet 的 xlsx（原表逐格照抄 + 右侧追加）、CSV、qpcr-plate/v1 JSON

两个容易被忽略的统计细节

• ΔΔCt 的零点可以任取。它是一组 ΔCt 同减一个常数，常数取 0 就是 ΔCt 本身； 「突变体均值 − 野生型均值」是组间 ΔCt 差，不是逐孔的 ΔΔCt。本工具取 0，所以 ΔΔCt ≡ ΔCt， 2^-ΔCt 就是每个孔的表达量。「相对校准组 = 1×」只是展示时除以校准组几何均值。
• 检验与展示同口径：都在 2^-ΔCt 上。代价是 2^-ΔCt 右偏、两组方差比被放大，Welch 的自由度会被压低， 所以同时报 Mann-Whitney 的 p（秩在单调变换下不变，两种尺度给出同一个 p）。 传 scale: "dct" 可改用 ΔCt 口径做 t——p 值会变，同一份报告只能用一种。
• 技术重复要合并。3 个技术孔当成 3 个生物学样本，n 从 3 变 9，p 会虚高几个数量级。

为什么是单文件

决策	理由	代价
单文件、零依赖	分发即交付；断网可用；不会因为 CDN 挂掉或依赖升级而坏	手写 zip 读写与 xlsx 解析；没有组件框架
算法与界面同源	agent 和手点走同一份代码，不会有两套结果	全局状态要守纪律
skill 内嵌进产物	版本同源，单一分发物	HTML 变大 12 KB；执行器依赖浏览器

源码是 TypeScript 五层工程（src/，22 个文件 3,891 行），tsc --strict 0 错误后打包内联成这个 HTML。 审计统计实现可以直接读 src/core/stats.ts，不用读压缩后的产物。

局限

• 统计：只有 ΔΔCt（Livak）。没有 Pfaffl 效率校正、没有多内参稳定性排序、没有 RDML 导入。 扩增效率明显偏离 100% 时结论要打折扣——界面写明了，但没有量化。
• 数据：不支持 .xls（97-2003 二进制）；导出不保留单元格样式；十万行级大表没测过。
• 运行：单线程 DOM + canvas，超过 15 组图表会挤；只在 Chromium 上测过。
• 判断：分组、对照、内参是实验设计信息，工具只能猜默认值。报告里必须区分 「数据支持的」与「需要你确认的」。

构建

npm install
npm run build          # tsc 类型门禁 → esbuild 打包 → 替换 qpcr.html 主脚本 → 重新注入 kit/spec

qpcr.html 既是产物也是输入（CSS 与四块内嵌内容在里面），两个脚本都幂等，可以反复跑。 改了 kit/ 或 spec/ 只跑 python3 tools/embed.py；改了 src/ 跑 python3 tools/build.py。

目录

qpcr.html                     产物：单文件工具（含全部内嵌内容）
src/                          TypeScript 源码，五层
kit/                          SKILL.md / qpcr-run.js / qpcr-plate.schema.json（被内嵌进 HTML）
spec/                         科研数据工具开发规范 + newtool.py 骨架生成器 + demo-tool 样例
tools/                        build.py（tsc+esbuild）/ embed.py（注入内嵌块）
examples/                     可以直接拖进去试的真实导出表
docs/design.md                设计决策、五轮迭代、修掉的真问题
docs/ts-refactor.md           TypeScript 重构记录

许可

MIT。数据与统计口径按 ΔΔCt（Livak）实现，用于科研辅助，不替代人工复核。