这一页写给想改这个工具的人。它讲三件事：模块怎么分层、 一轮采样里数据怎么流、以及七条决定了它长成什么样的取舍。 要动手改代码，配合 CONTRIBUTING 一起读 —— 那份讲的是规矩，这份讲的是形状。
分层的判据只有一条：这个模块碰不碰外界。碰外界的（发请求、跑命令、 读文件）归采集层；不碰的归计算层，全是纯函数，可以喂固定样本做离线测试； 呈现层只负责整形，不做判断。
这条线画得很硬，好处是测试套件可以完全离线 —— 一个需要联网才能跑的测试套件，在没网的时候就等于没有。 而这个工具恰恰是给网络出问题的人用的。
按下「立刻采一轮」或者定时器到点时，走的是下面这条链。整条链在一个后台线程里跑， 界面通过 SSE 收结果 —— 采样卡住不会让界面卡住。
每一条都是「选了 A 而不是 B」，以及不这么做会怎样。 改代码时如果要推翻其中一条，先看看这里写的代价还在不在。
一个专门监控网络流量的工具，在你没同意之前就开始发请求，它的可信度当场就没了。 所以空状态不是占位符，它是页面在如实说「我到目前为止什么都没做」。 代价是多一次点击，换来的是这个工具可以被放心地装在一台不属于你的机器上。
任何装了代理的机器上，三个入口读的是不同的配置文件，可以从不同国家出去。 一个大标题必须挑一个显示，那它对另外两个就是错的 —— 而这个工具存在的全部理由，就是那个「不一样」。
往别人的遥测接入点写数据，等于污染他们的数据，也把这个监控工具变成了一个上报源。 握手已经能回答「通不通、多快」，那就到此为止。 界面上这一句也写出来了 —— 使用者有权知道这个工具对第三方做了什么。
「慢」有四种完全不同的原因，修法也完全不同：DNS 慢换解析器，TCP 慢换出口节点， TLS 慢多半是链路丢包重传，首字节慢是服务端或中间代理在等。 一个总数无法告诉你是哪一种，于是人只能瞎换节点。
静态提取只能知道「会发哪些字段」，不知道「某一次具体发了什么值」。 后者要装一个根 CA —— 而根 CA 私钥一旦泄露，本机所有 HTTPS 都可被解密。 这个代价大于收益，所以本仓不做，也不提供做这件事的工具。 能给的答案边界写清楚，比给一个越界的答案更有用。
一份完整采样约 15 KB，精简记录约 1 KB。挂一个月的差别是 400 MB 和 30 MB。
精简记录只留结论要用的字段，代价是历史看板答不了「三周前那一轮的第七个域名 TTFB 是多少」——
但那个问题没人问。想留全量的人可以加 --persist，那份文件在 gitignore 里。
这个站上的 demo 用的就是 web/index.html 和 web/app.js 本身，
只是把三个接口换成了内置的一轮虚构采样。所以它不会随时间和真实界面走偏 ——
一个和产品长得不一样的 demo 比没有 demo 更糟。
代价是生成脚本要做一次 fetch 替换，那段代码在 scripts/build_docs.py 里，有注释。
| 你想加 | 改哪个文件 | 要注意 |
|---|---|---|
| 一个 Claude 域名 | cem/endpoints.py |
必须带 evidence（怎么知道的），不是 Claude 的要标 baseline=True，否则会污染结论 |
| 一个数据源 | 采集层新建一个模块 | 拿不到返回 None 不抛异常；并在 数据源里加一行，写明能撑到哪一档置信度 |
| 一条诊断规则 | cem/diagnose.py |
判据 / 成因 / 下一步三样缺一不可；测试要同时断言「该触发时触发」和「不该触发时不触发」 |
| 一个界面面板 | web/index.html + web/app.js |
节点用 el() 造（外部输入拼 innerHTML 就是 XSS）；文案双语；atl- 前缀的样式别改 |
| Linux 支持 | cem/paths.py · cem/sockets.py |
核心探测本来就能跑，卡住的是「读系统代理」和「列进程连接」两块 macOS 命令 |
| 一章文档 | docs/*.md |
写完跑 python3 scripts/build_docs.py，把 .md 和生成的 .html 一起提交 |
文档站的 HTML 是生成后提交进仓库的，不靠 GitHub Actions 构建。
这样 fork 的人开个 Pages 就能用，不需要配任何东西，也不需要给 token 加权限。
代价是改 .md 之后必须记得跑一次生成器 ——
python3 scripts/build_docs.py --check 可以检查有没有忘。