workload-journal-support 里一共四个文件:README.md(198 字节)、.nojekyll(0 字节)、index.html(2546 字节)、privacy.html(3463 字节)。没有构建脚本,没有 package.json,没有一行 JavaScript。默认分支叫 codex/support,历史上只有两个提交,第二个提交的标题是 “Clarify independent app launch and retention timing”。
README.md 把边界写得很直白:
Public support and privacy pages for Workload Journal by Julian Cooper. No application source, credentials, receipts, or private session data belongs in this repository.
这句话决定了仓库的形态。上架要支持 URL 和隐私政策 URL,但应用源码和面向公众的页面放在一个仓库里,等于把发布渠道和开发仓库绑死;README 里点名排除的 credentials、receipts、session data 更是不能出现在公开页面旁边。拆出来之后这两页可以被任何人 clone、diff、提 issue,代价是隐私条款从此只能“声明”、不能“自证”——后面单独讲。
所以这个仓库不是“文档站”,它就是产品的一部分:App Store 里那个“App 支持”链接落到的就是这里。
整体数据流:真正在动数据的只有两处
写隐私页前先画数据流,因为读者真正问的是“哪一步会离开我的 Mac”。答案是:只有两处主动外流(内购经 Apple、issue 经 GitHub),其余全在本机。
| 数据 | 产生位置 | 存放位置 | 是否离开 Mac |
|---|---|---|---|
| 任务名、开始/停止时间 | 点“开始记录”/“停止记录” | 应用沙盒 | 否;导出报告时可由用户勾选加入 |
| 整机 CPU、内存估算、热状态、电池与供电 | 采样过程 | 应用沙盒 | 否;仅进入报告 |
| 机型、系统版本 | 应用启动 | 应用沙盒 | 否;仅进入报告 |
| 交易与高级权益 | Apple StoreKit | Apple | 是,但只到 Apple,不到开发者服务器 |
| 支持 issue 正文 | 用户手写 | GitHub | 是,由用户主动提交 |
| 导出报告 | 用户选目录导出 | 用户指定路径 | 否,除非用户自己分享 |
这张表决定了隐私页的章节顺序:保存在 Mac 上的数据 → 购买 → 你主动导出的报告 → 支持与联系。顺序即优先级:唯一会外流的购买环节单独成章,避免被误读成“内购所以有服务端”。
骨架同样素:没有模板引擎,没有 CSS 文件,样式直接写在 <head> 里,两页各一份。下面是换过行的真实头部:
<!doctype html><html lang="zh-Hans"><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>负载手记 Workload Journal · 支持</title>
<style>body{font:17px/1.7 system-ui,sans-serif;max-width:780px;margin:64px auto;
padding:0 24px;background:#faf9f5;color:#272731}a{color:#4742a0}
h1,h2{line-height:1.3}nav{margin-bottom:40px}small{color:#62626c}</style>
</head><body>
<nav><a href="./">负载手记 Workload Journal</a> · <a href="privacy.html">隐私 / Privacy</a></nav>
17px/1.7 的行高、780px 的最大宽度、#faf9f5 的米色底,就是全部设计决定。没有暗色模式,没有断点——padding:0 24px 加 max-width 在手机上够用。这不是懒:改不了几次的页面,构建链的维护成本高于收益。
把形容词换成参数:保留策略怎么写才算说清楚
隐私页最容易翻车的地方不是“有没有写”,而是写了等于没写,比如“我们会定期清理过期数据”。定期是多久?过期指哪一端?清理从哪条开始?
privacy.html 里这一段是整篇最硬的部分,关键参数全部落到具体值:
| 参数 | 取值 | 触发时机 | 出现位置 |
|---|---|---|---|
| 单次记录上限 | 2 小时 | 记录过程中 | index.html「使用与数据」 |
| 已完成任务保留期 | 30 天 | 启动或保存记录时 | index.html + privacy.html 中文 + 英文 |
| 任务条数上限 | 300 条 | 同上 | 同上,共 3 处 |
| 采样点上限 | 50,000 个 | 同上 | 同上,共 3 处 |
| 清理顺序 | 先删最早完成的任务 | 超上限时 | 三处都写明 |
| 系统要求 | macOS 14 及以上 | 安装 | index.html 首段 |
| 政策生效日期 | 2026-10-15 | — | privacy.html 顶部 |
注意“触发时机”那一列。第二个提交叫 “Clarify independent app launch and retention timing”,改的就是这一列:只说“清理超过 30 天”,读者无法判断清理是定时器、退出时、还是根本不跑。现在的写法把时机钉在“启动或保存记录时”——这是用户能观察到的行为:保存完一条记录,旧数据就没了。
同理,“达到上限先清理最早完成的任务”给的是一条可预测的排序规则,而不是“自动管理存储空间”。前者用户能预判自己会丢哪条,后者只能等着看。
中英双语在同一页,同一组数字要出现在两个语言段落,措辞必须一一对应:
<h2>保存在 Mac 上的数据</h2>
<p>任务名、任务时间、整机 CPU、内存估算、热状态、电池与供电状态,以及机型和系统版本,
仅写入本机应用沙盒。应用不上传这些记录,不使用广告、遥测或分析 SDK,
也不读取工作文档、键盘输入或进程名称。</p>
<h2>English</h2>
<p>Session titles, timing, whole-machine CPU and memory estimates, thermal state,
battery and power status, hardware model, and OS version remain in the app's local sandbox.
The app does not upload this data, use advertising or analytics SDKs, inspect documents,
capture keystrokes, or list process names.</p>
“不上传 / does not upload”、“不读取工作文档 / inspect documents”、“不记录键盘输入 / capture keystrokes”、“不列进程名 / list process names”——四条否定句是四条独立承诺,删掉任何一条,另一语言版本立刻失去对照。这是把“隐私友好”换成可审计的清单。
边界要写在支持页,不能只写在隐私页
反直觉的选择:产品能力边界我放在 index.html 而不是 privacy.html。来支持页的人多半带着“为什么这个数字不对劲”。
页面上有三句边界声明:
- CPU 和内存是整机观测,不能用于把资源消耗归因到某个任务或进程;
- 热状态不是温度,也不是功耗;
- 降级(不再持有高级权益)不会立即删除历史,但同样受 30 天 / 300 条 / 50,000 点约束。
第一条直接决定这个产品的定位:它记录的是“这台机器当时在扛什么”,不是“某个进程吃了多少”。如果不写在支持页,工单里会出现大量“为什么我的浏览器占用没显示”——这不是 bug,是设计。第三条是降级路径上最容易被误解的点:降级常被当成清库,实际是先保留、再按同一套上限淘汰,只失去“全部保留历史”和“两任务对比”。
导出报告同样给了默认值和一个显式开关:
报告默认隐藏任务名,导出前可以明确选择包含。
默认关闭 + 显式 opt-in,是这类功能唯一说得过去的形态:默认带任务名会让导出变成一次无意识泄露,完全不给选项又拿不到可读报告。privacy.html 里那句“导出文件不会随资料库保留上限自动删除”必须写——清理只管资料库,管不到你桌面的 CSV。
踩到的坑
坑一:绝对路径在项目页上会 404。 这类页面最常见的症状是:本地 file:// 打开正常,推到 GitHub Pages 项目页(路径 /workload-journal-support/)后 404——如果导航写成 /privacy.html,浏览器会去域根找文件,而项目页不在域根,之后换自定义域名又会再变一次。改法就是现在这样:href="./" 和 href="privacy.html",交给浏览器按当前目录解析。两条相对链接同时兼容本地预览、项目页和未来的自定义域名,成本为零。
坑二:.nojekyll 是个 0 字节文件,看着像误提交。 作用只有一个:关掉 GitHub Pages 默认的 Jekyll 处理。现在只有两个 .html,不装也不会挂;装它是为了以后放 _headers 或下划线开头的素材目录时不至于突然 404。代价要认:关掉 Jekyll 等于放弃 layout 和 include,两页的 <head> 与 <style> 只能复制——现在两份内联样式逐字相同,改一次字号要改两个文件。两页共约 6KB,复制比引构建链便宜。
坑三:同一组数字散在三处,改一处就自相矛盾。 30 天、300 条、50,000 点这三个数,在 index.html 出现一次,在 privacy.html 的中文段和英文段各出现一次。隐私条款没有变量,文案即代码,漏改一处的后果是“中文说 300、英文说 500”,而这种矛盾恰好出现在最需要可信度的地方。目前的兜底是提交前做一次机械核对:
gh api repos/Cooperiano/workload-journal-support/contents/index.html \
-H "Accept: application/vnd.github.raw" | grep -o "30 天\|300 条\|50,000"
gh api repos/Cooperiano/workload-journal-support/contents/privacy.html \
-H "Accept: application/vnd.github.raw" | grep -o "30 天\|300 条\|50,000\|30 days\|300 sessions\|50,000 samples"
如果页面数量继续涨,正确做法是在仓库里放一个 RETENTION.md 当唯一真相,两页文案从它抄——但在只有两页的阶段,多一个文件就多一处要同步的地方,不划算。
坑四(已知欠账):lang="zh-Hans" 覆盖整页,包括英文段。 屏幕阅读器会用中文语音读 English 部分,搜索引擎也拿不到语言信号。正确做法是把英文段包成 <section lang="en">,一行改动。单页双语省掉了语言切换器和两份文件的漂移风险,取舍成立,但 lang 该补。
边界与代价
这个仓库有一个结构性限制,值得说清楚:README.md 明确写着 “No application source... belongs in this repository”,所以隐私页里“应用不上传这些记录”这句话,读者在仓库里验证不了。它是一个声明,不是证明。
能交叉验证的只有外部可观察点:App Store 的隐私标签、应用沙盒容器里到底有什么文件、导出报告实际落在哪个目录、以及内购是否真的只经过 StoreKit。这也是为什么页面里的措辞都往“可观察行为”上靠——“写入本机应用沙盒”“通过 Apple 验证的交易和权益决定高级功能访问”“导出到你指定的位置”,每一条用户都能自己去看一眼。做不到可验证的承诺,就至少写成可被证伪的句子。
其余代价:
- 只有一个生效日期,没有变更记录。
privacy.html顶部只有一行生效日期 / Effective: 2026-10-15,改了什么只能翻 git log。如果保留策略真变过,用户拿不到“我同意的是哪一版”。 - 文案与实现之间没有自动校验。 如果某天采样上限从 50,000 调成 100,000 而忘了改页面,没有任何 CI 会报错。这类仓库的可信度完全建立在“每次改代码顺手改页面”的纪律上。
- 双语不分离。 一个生效日期同时管中英两版,无法按语言分别发布修订。
- 高级版边界是功能承诺,不是数据处理承诺。 所以它写在支持页,不写进隐私页——混在一起会让读者以为“两任务对比”也涉及数据外流。
小结
这两页 HTML 没有任何技术难度,难点全在措辞的颗粒度上:把“定期清理”换成“启动或保存记录时,清理超过 30 天的已完成任务,最多 300 条、50,000 个采样点,先删最早完成的”,可信度就来自这一句里的四个可核对项。支持页仓库的价值不在代码量,而在于它让每一条隐私承诺都短到能读完、具体到能被反驳。