早上起来习惯性瞄一眼 home lab 的日志，看到我那个 WebSocket 服务凌晨被重启过：

重启就重启吧，本来没当回事。结果顺手打开本博客——打不开。又试了下这台机器上跑的其他站，也全打不开。好家伙，整台机器的 nginx 全躺了，而且看时间已经躺了三个多小时。

先看现场

第一件事是确认机器有没有重启过。uptime 一看，没有，机器好好的。那就是 nginx 单独出事了。systemctl restart nginx 下去，唰一下全恢复了。

服务是回来了，但这更让人不安：能 restart 成功，说明磁盘上的配置本来就是好的，那它三个小时前到底为什么起不来？翻 unit 日志：

host not found in upstream。我博客有几个路径(比如这个)是反代到 GitHub Pages 的，nginx 起来的时候要解析 bones7456.github.io，那一刻没解析出来，直接 emerg 拒绝启动。

再一看，06:48 这个时间点太像 Debian 系的 cron.daily 窗口了（/etc/crontab 里是 6:25，加上 anacron 的随机延迟，另外 cron.weekly 是 6:47，更像），我当时第一反应是 certbot 续期把 nginx 重启崩了。结果把那五分钟的全量日志拉出来一看，跟 certbot 半毛钱关系没有。所以还是那句话：别猜，看日志。

1 秒的竞速

把 journalctl --since "06:45" --until "06:50" 全量捞出来，真凶一目了然：

看明白了：systemd 被 apt 自动升级，触发 needrestart 把机器上几乎所有服务全重启一遍。我这台机器上跑着 BIND 做内网 DNS，于是 named 和 nginx 一起被拖下水。

nginx 在 06:48:02 查 DNS，named 在 06:48:03 才恢复监听。就差 1 秒，nginx 输了这场竞速，代价是三个多小时的全站宕机。

最扎心的是同一批重启里的对比：php-fpm、redis、mariadb，还有我自己那几个 Flask 服务，全都 Started 成功了。唯独 nginx 死了。为什么？因为只有 nginx 在启动阶段需要解析外部域名，别的服务都不需要。

为什么 After=nss-lookup.target 没救下它

这才是这次最值得说的地方。翻开 Ubuntu 自带的 nginx unit：

nss-lookup.target 是 systemd 专门用来表示”域名解析已就绪”的标准锚点，DNS 服务一般会用 Before=nss-lookup.target 把自己挂上去。也就是说，nginx 早就声明过”我要等 DNS 就绪再启动”——然而它还是死在了 DNS 上。

原因在于After= 的语义被普遍误解了：

它只在同一个 systemd job transaction 内部编排启动先后，并不检查目标服务的实时健康状态。

needrestart 是逐个执行 systemctl restart <unit> 的，nginx 和 named 属于两个互相独立的 transaction，彼此之间没有任何排序约束。更要命的是，nss-lookup.target 是个 passive target，named 停止时它并不会跟着 deactivate，全程保持 active——于是 nginx 一查”依赖满足了吗”，满足，启动，然后一头撞死。

所以结论挺反直觉的：在 restart 场景下，After= 基本等于安慰剂。指望靠加一行 After=named.service 来防这类问题，是防不住的。

两道防线

既然顺序编排靠不住，那就换思路：一道事后自愈，一道事前免疫。

防线一：让它自己重试

Ubuntu 的 nginx.service 默认没有 Restart=，意味着启动失败一次就永久 failed，没有任何重试。而这次 named 只用了 1 秒就恢复——只要能重试一次，整件事根本不会发生。

StartLimit 那两行不是可选的：systemd 全局默认是 10 秒内最多 5 次，配上 RestartSec=10 会立刻撞上限流然后彻底放弃。改成 10 分钟内 20 次，才扛得住像样的 DNS 故障。

这里补一个 drop-in 的合并规则，很多人会搞混：

1. 标量指令（Restart=、RestartSec=、Type=、PIDFile=…）是覆盖。
2. 列表指令（After=、Wants=、Environment=、ExecStartPre=…）是追加，不是覆盖。想清空得先写一行空赋值 After= 再写新值。
3. ExecStart= 是重灾区：Type=forking 下只允许一条，直接在 drop-in 里写会报错，必须先 ExecStart= 清空再写。

想看合并后到底生效了什么，别看文件，看这个：

还有个细节值得确认：这次失败的其实是 ExecStartPre 里的 nginx -t -q（日志里那句 Control process exited, code=exited, status=1/FAILURE，result 是 exit-code）。Restart=on-failure 是覆盖这种情况的，不用担心它管不到。

防线二：别让 nginx 在启动期解析域名

自愈只是兜底，根上的毛病是：一个 location 的 upstream 解析不了，整个 nginx 拒绝启动，机器上所有站点陪葬。nginx 的配置校验是 all-or-nothing 的，一个小站点的临时故障被放大成了全局故障。

解法是给 proxy_pass 用变量——只要 proxy_pass 里含变量，nginx 就不再在启动期做一次性解析，改成运行时按需查 resolver。这样 DNS 挂了 nginx 照样能起来，最坏只是那一个 location 返回 502。

但这里有个大坑，下面单独说。

变量化 proxy_pass 的那个坑

我原来的配置是这样的，注意 proxy_pass 后面带了路径：

如果你天真地把域名换成变量，写成 proxy_pass https://$gh_pages/china-dynasty-timeline/;，就掉坑里了。nginx 的规则是：

1. proxy_pass 不含变量且带 URI → nginx 做前缀替换，把 location 匹配掉的 /data/shi/ 换成 /china-dynasty-timeline/。
2. proxy_pass 含变量 → 前缀替换机制彻底失效，URI 被固定成你写的那个。

后果是这样的：

首页看着还挺正常，所有子资源全部错位——CSS、JS、图片全挂。这种”打开一看好像没事”的故障最恶心。

正解是用 rewrite ... break 手动接管路径映射，配一个不带 URI 的 proxy_pass。nginx 文档明确写了：proxy_pass 不带 URI 时，若 URI 已被 rewrite 改写，传递的就是改写后的 URI——正是我们要的。

先在 server 块里放解析器和变量：

然后 location 改成：

实际只动了三处：加 rewrite ... break、proxy_pass 去掉路径换成变量、显式加 proxy_ssl_name（它默认取 $proxy_host，变量化后写死更稳）。proxy_redirect 是字面量匹配，不受影响。查询串也会自动带过去，/data/shi/a?b=1 照常工作。

几个坑

1. resolver 里写多个地址是轮询，不是主备。我这里反代的是公网域名，两个 DNS 都能解析，正好互为冗余；但如果你要反代本机 named 里那些内网 zone，就绝不能这么写——轮询到 1.1.1.1 直接解析失败。那种 location 得单独配 resolver 127.0.0.1;。
2. ipv6=off 是刻意加的。变量化之后每次请求都要重新解析，家宽 IPv6 到 GitHub 的连通性又不一定稳，少一个变数是一个。确认 IPv6 走得通再打开。
3. 别指望 After= 能防住 restart 场景，前面说透了。它在正常开机时有用，成本为零可以留着，但不能当防线。
4. nginx -t 通过不代表这次改对了。它只校验语法，rewrite 的路径映射对不对，它一个字都不会告诉你。

怎么验证真的修好了

改完一定要实测，光看配置”觉得对”没用。先验路径映射——必须测子路径，别只测首页：

说点本质的

复盘下来，这次事故里有三个独立的问题，任意修掉一个都不会出事：nginx 没有真正可靠的 DNS 就绪依赖、配置在启动期硬依赖 DNS、失败之后没有任何重试。三个凑齐了，一次 1 秒的 DNS 抖动才放大成 3 小时的全站宕机。

而我最想留下的一条经验是：别把系统的健壮性寄托在”顺序”上。After=、Before=、network-online.target 这些东西给人一种”我已经处理好依赖了”的错觉，但它们描述的是编排意图，不是运行时的真实状态。真正靠得住的只有两种东西——失败了能自己重试（自愈），和压根不依赖那个东西（免疫）。分布式系统里讲了很多年的道理，放在单机 systemd 上一样成立。

最后再补一句题外话：这次是我早上”顺手看了眼日志”才发现的，不然还得挂更久。所以监控该上还是得上，healthchecks.io、UptimeRobot 之类的免费额度足够个人站用了。再优雅的配置优化，也不如有人（或者有个机器人）在你睡觉的时候盯着。

全文完。

上次写 Notchy 的时候（从接手到日用：我把 Notchy 改成了什么样），我自以为已经比较完善了，自己想要的功能都有了。但后面自己深度使用以后，包括也有网友反馈，发现还是有不少细节需要打磨。

于是一晃一个半月过去，翻了下 git log，从 1.2.7 到 1.3.7，中间又是 23 个 commit、小一千五百行 Swift，版本号跳了整整十个小版本。。。

趁着 1.3.7 刚发出去，把这段时间攒的东西整理一下：

标签页：从”能用”到”顺手”

上次提到的 Shadow Tab（右键一个 Xcode 或 Pinned 标签页，开一个 cd 到同目录但不启动 agent 的纯 shell）用顺手之后，发现每次都要right-click 选菜单有点烦，于是加了个 Cmd+Shift+T，直接对当前标签页开一个分身。Pin、unpin、开 Shadow Tab 的时候，标签页角上也会弹一个小图标提示一下，不然经常按完不确定到底生效没有。

关掉当前标签页这件事之前也有点反人类：永远跳到”下一个”，跟浏览器的习惯不一样。现在改成关掉后自动回到关之前那个活跃的标签页，一路往回找，符合直觉多了。

标签页多了之后，顺序调整和快速定位就成了刚需。这次加了两个东西：

一是拖拽排序——按住标签页左右拖，松手自动补位，Cmd+1…9 的跳转序号也跟着重新编号，不用再手动数第几个。

二是 Cmd+K 快速切换器：弹出一个按最近使用顺序排列、支持模糊搜索的会话列表，方向键选、回车跳、Esc 取消。做这个的时候踩了个 AppKit 的老坑——SwiftUI 的浮层（QuickSwitcherOverlay）从视图树里移除之后，并不会自动把键盘焦点还给原来的终端，得在 Esc 或选中之后手动调用 makeFirstResponder 把焦点抢回来，否则切换器关了，键盘输入却发不出去，你会以为是终端卡住了。

终端里能像正经终端一样用了

早些版本的终端体验偏”能跑就行”，这轮补了不少 iTerm2 用户会想念的东西。

右键菜单是最直观的一个：复制/粘贴/全选、查词典、拿选中内容或光标下的词去搜网页、打开光标下的 URL、在 Finder 里显示当前工作目录（或复制路径）、清屏。标签页右键菜单也顺带加了”创建检查点”。

深压（force click）一个单词会弹出系统词典释义，跟 Safari 里的 Look Up 一模一样——原理是接进了 trackpad 的 deep-click 二段位移，从 SwiftTerm 的缓冲区里解出光标下的词，再丢给 AppKit 的 showDefinition(for:at:)。

Cmd+点击打开文件/链接这块改动最细，也最容易在细节上翻车。之前直接点会遇到带空格的路径识别不出来、相对路径解析错目录之类的问题。现在带引号的路径（比如截图文件名里常见的空格）能整体识别成一个链接，相对路径按 shell 当前实际所在目录解析（用 proc_pidinfo 拿真实 cwd，不是猜的），像 agent 输出里常见的 Sources/File.swift:12 这种”文件:行号”引用，点一下直接在 Xcode 里跳到对应行。

另外一个不算起眼但天天受益的：流式输出的时候终端选区不再被冲掉了。原来 SwiftTerm 只要收到新数据就会重置鼠标上报状态，顺带清掉你刚选中的文本；现在只有 vim、htop 这类真正需要鼠标事件的 TUI 才会保留上报，普通 agent 输出流不会再打断你复制粘贴。

输入法这次是另一个坑

上次那篇讲的输入法问题，是 SwiftTerm 的 NSTextInputClient 吞掉预编辑文本（打拼音看不到候选字下面自己打了啥）；这次修的是另一层——输入法来源（源）在标签页之间的记忆。

现在每个标签页会记住自己上次用的输入法：一个跑着 CLAUDE.md 项目、习惯打中文的标签页，切走切回来还是中文；旁边一个 Shadow Tab 默认停在英文，互不干扰。且只有 Notchy 面板真正拿到焦点时才会去改系统输入法，不会误动其他 App 正在用的输入法。

这个功能刚上的时候有个隐蔽 bug：macOS 的 panelDidResignKey 有时候一次失焦会触发两次，第二次触发时外部输入法已经被恢复了，结果把”外面那个 App 的中文输入法”错记成了这个标签页的输入法，污染了原本该是英文的 Shadow Tab。加了个 idempotent 保护（guard isPanelKey）才算收住。

同一批还加了 Quick Input：自己绑快捷键到预设命令，按一下自动敲进当前聚焦的终端（内置了 Cmd+G → git status），要不要自动回车可以按行配置，在 Settings → Quick Input 里随便增删，也可以整体关掉。

边边角角的细节

一些不太会单独写文章但用起来很舒服的小改动：

Xcode 工程在磁盘上被挪了地方之后，对应标签页现在会自动刷新到新路径——之前是按项目名字匹配的，工程一挪，标签页就一直 cd 到一个不存在的旧目录。

拖动窗口或者用 Cmd +/-/0 缩放字体的时候，HUD 提示会顺带把终端的字符行列数也标出来：

外接显示器没接的时候，相关开关会自动置灰并给提示，接上拔下都会跟着实时更新，不用再对着一个点了没反应的开关发呆。

还有个不起眼但对 agent 体验有直接影响的：内嵌终端之前没有正确设置 TERM_PROGRAM，claude 这类会识别宿主终端类型的 CLI 只能退回去看原始的 $TERM 值，现在能正确认出自己是跑在 Notchy 里。

顺手修的一堆 bug

这段时间里还有几个纯粹的显示 bug，挑重点提一句：设置窗口以前是 floating 层级，会盖住其他 App 窗口，改成 normal 就好了；改字体大小之后终端字符被滚动条挡住的问题修了；终端往上滚看历史的时候，敲的字没有正确回显到屏幕上的问题也修了——这几个都是 SwiftTerm 底层渲染逻辑的坑，改动细节没什么好展开的，能用就完事了。

—

十个版本攒下来，Notchy 离”能用”更远了一步，离”顺手”近了一大截。想试试的话去 GitHub 下最新的 DMG 或 ZIP。

之前我有个习惯，会把代码（整个repo）放到 iCloud 管理的 ~/Documents 下。一直觉得挺方便的，因为即使没有 commit+push，我到另一台电脑上也能接着干活，登了同一个iCloud账号的目录会自动同步。

但最近遇到一个特别邪门的问题。一个用 uv 管理的 Python 项目，editable 方式安装，前一个小时还好好的，突然就：

邪门在哪呢？同一个 venv、同一个解释器，pytest 跑起来一千六百多个用例全绿。测试说包在，入口脚本说包没了。去 site-packages 里看，editable 安装落下的 .pth 文件好好躺在那，内容就是一行指向源码目录的路径，权限 644，路径也真实存在。文件在、内容对、权限对，但它就是不生效。

排查：谁把我的 .pth 吞了

先补一句背景：editable 安装的机制，是往 site-packages 里放一个 .pth 文件，Python 启动时 site 模块会读它，把里面的路径追加进 sys.path。这个文件失效，包就从解释器眼里消失。

做了三个对照实验，结果非常有意思：

1. 自己写一个探针 .pth（内容随便指个存在的目录）放进同一个目录——生效；
2. 把出问题的 .pth 原样 cp 成另一个文件名——生效；
3. 出问题的那个文件本身——死活不生效。

同目录、同内容、同权限，副本能用原件不能用，那唯一的区别只剩下文件的元数据了。ls 加个 -O 把 BSD 文件标志打出来：

flags 一栏赫然写着 hidden——macOS 的 UF_HIDDEN 文件标志。cp 不会复制 BSD flags，所以副本是干净的，这就解释了实验 2。而 CPython 从 3.11 起，site.py 处理 .pth 时加了一条安全加固（防止恶意软件用隐藏 .pth 做隐蔽注入）：

带隐藏标志的 .pth，静默跳过，一个字的错都不报。两个各自都算合理的行为叠在一起，效果就是：文件在，import 没了。

那谁给文件打的 hidden？chflags nohidden 清掉，几秒钟之后再看，又变回 hidden 了——有个进程在实时跟我对抗。答案到这基本明了：这个仓库在 ~/Documents 底下，而这台 Mac 开着 iCloud 的“桌面与文稿”同步。把仓库挪出 Documents、重建 venv，flags 干干净净，问题再没复发。

iCloud Drive 到底在做什么

开了”桌面与文稿”同步之后，~/Documents 就不再是普通目录，而是由 fileproviderd 守护进程托管的同步空间。它主要干三类事：

1. 监听并上传每一次文件变更——它假设文件是”偶尔被人编辑的文档”；
2. 冲突消解——当它认为同一个文件出现两个竞争版本，不丢弃任何一边，而是生成”xxx 2″”xxx 3″这样的冲突副本；
3. 元数据管理——给托管文件打 xattr 和文件标志（上面那个 hidden 就是它干的），开了”优化 Mac 存储”还会把冷文件驱逐成无数据的占位符，读取时才按需下载。

对文档来说这些设计都挺好。但代码库不是文档。

代码库为什么全中

第一，写入模式冲突。开发工具链的写入是高频、批量、依赖原子性的：包管理器一次重写上万个小文件，Python 用”临时文件 + rename”做原子写，git 靠锁文件和 rename 更新引用。同步进程和这些写入异步竞争，竞争输了就落冲突副本。我这次在 site-packages 里就看到了 “_editable_impl_mycli 2.pth”、”3.pth”、”4.pth” 一窝副本，主 .pth 的内容更是被拼接成了四份路径首尾相连的乱码：

第二，元数据篡改。就是前面 UF_HIDDEN 那一段，而且它是主动维护的，你清掉它还会打回来。

第三，驱逐。.git/objects 里的 packfile、venv 里的二进制，都可能被”优化存储”驱逐成占位符——在线时表现为构建随机卡顿，离线时表现为仓库”损坏”。

第四，git 自己的风险。.git 里的 index、refs 一旦出现冲突副本，仓库状态可能真损坏。git 本身就是分布式同步工具，外面再套一层文件级同步，等于双重同步，语义必然打架。

这次踩到的坑

1. chflags nohidden 修不好——几秒内被 fileproviderd 顶回来，别在这条路上浪费时间；
2. 症状自相矛盾极具误导性：pytest 全绿（它靠 rootdir 机制自己把源码目录塞进了路径），入口脚本却挂了，两个工具对”包是否存在”给出相反答案，直觉上会先怀疑一万个别的东西，最后才怀疑文件系统在说谎；
3. 损坏是异步、随机发生的：同一个 venv 一小时内坏了两次，中间检查全都正常——因为坏不坏取决于同步进程什么时候追上来；
4. 诊断口诀：文件明明在但 import 不到，先 ls -lO 看 flags 列。

结论

iCloud（以及 Dropbox、OneDrive 这些文件级同步盘，机制细节不同但三板斧一样）适合放终态文档：文稿、图片、表格。任何带衍生状态的目录——代码库、venv、node_modules、.git、构建缓存——都不该放进去。代码的跨机同步交给 git，这本来就是它的职责，而且语义正确。仓库放个非托管路径（比如 ~/dev）就好；实在有目录必须留在 iCloud 里又想排除，macOS 没有官方排除项，只有给目录名加 .nosync 后缀这个 hack。

一个按文档假设设计的同步器，遇上一堆违反它全部假设的文件，双方都没有 bug，组合在一起就是灾难。就此，完毕。

最近上架了一个新 App：DailyDiff（每日一辨）。做它的初衷很简单：一是我自己想把英语再往上提一提，二是儿子也在学英语，我想给他（也给自己）找一个每天花几分钟、细水长流的练法。

市面上背单词的软件很多，但它们解决的基本都是”认识”：看见 soldier 知道是战士，看见 warrior 也知道是战士。可这两个词的区别是什么、什么场合该用哪个——这种”掌握”层面的功夫，几乎没有软件管。而”认识一个单词”和”掌握一个单词”之间恰恰隔着一条鸿沟，它决定了你的英语是只能读，还是真的能用。所以我做了一个专门练这个的 App。

每天一道题，它长什么样

玩法抄了 Wordle 的作业：每天全球所有人拿到同一道题——一对容易混淆的英语近义词，各配一张黑白线稿插图。你用英语写出这两个词在含义、语气、用法上的区别，一两句话就行，然后 AI 给你批改。

批改是这个 App 的核心。不是给个分就完事，而是从五个维度（准确性、覆盖度、语言、清晰度、洞察）各打一个 0–100 的分，每个维度都附一句针对你这次答案的点评——指出你答到位的地方、漏掉的要点，像一对一外教改作业。五个分数汇总成总分和等级，从 D 到 SSS。SSS 很难拿：不光要总分 95 以上，还要求最低的那个维度也不低于 90，纯靠某一项拉平均分是蒙不到的。

批改完揭晓标准答案，对照着学。之后就是熟悉的套路：每日连击打卡、日历一格格点亮，还能导出一张成绩卡分享——卡上只有词对、插图、等级和雷达图，刻意不含答案，朋友看到照样能去玩。

题库目前 200 道，四百张插图全是 AI 生成的黑白线稿，风格统一得像一个插画师画的。

技术上几个有意思的决定

作为技术博客，还是得聊聊后端。整个服务端就是一个 Cloudflare Worker，配 D1（题库和用户数据）和 R2（插图），没有一台服务器要运维，账单基本可以忽略——独立开发选这套栈真的省心。

我之前的服务，都是部署在自己的home lab上的，这也是一次全套采用cloudflare的技术方案，发觉这个赛博菩萨果然名不虚传，免费额度够用不说，wrangler的开发体验还非常棒！

几个细节自认为做得还算讲究：

1. 评分标准（rubric）永远不下发到客户端。客户端只上传题目 ID 和你写的答案，评分要点由服务端按 ID 查表后喂给模型。否则抓个包就能看到得分点，这游戏就没法玩了。

2. 总分和等级不信任模型自己报的数。LLM 的算术是出了名的不可靠，让它算五个维度的加权和，隔三差五给你算错一个。所以模型只负责逐维度打分和写点评，加总、定级在代码里重算。

3. 匿名用户不用注册就能玩，每天免费批改一次。防滥用靠的不是强制登录，而是 Apple 的 App Attest——让苹果证明请求来自真机上的正版 App，机器人和脚本过不来。这套东西的原理和服务端验证的坑，我之前单独写过一篇《Apple App Attest 简介》，感兴趣可以看看。

4. 批改额度是”先预扣、失败退还”。最早的实现是先只读检查额度、批改成功了再扣，看起来很稳妥——但批改一次要跑上一两分钟，这个窗口里并发发请求，每个请求检查时都显示”还有额度”，就都放行了，白烧 token。改成预扣制之后，靠 D1 单写者的串行化保证并发下最多放行额度上限那么多个请求，批改失败再把额度退回去。

免费与收费

说说钱的事，明码标价：每天的题目永远免费，匿名一天能批改 1 次，登录后 2 次。Pro 订阅（月付或年付）解锁 200 道历史题库、研读模式（先看标准答案再作答）和每天 15 次批改。订阅收入拿去付 AI 推理的账单——每一次批改都是真金白银的 API 调用，所以免费额度给得抠门，请理解哈哈。

来玩

App Store 搜「DailyDiff」或「每日一辨」，或者直接点这个链接。中英文界面都有，今天的题不用注册就能做。

如果你试了之后觉得 AI 批改哪次明显不靠谱，或者有任何建议，欢迎邮件 support@dailydiff.vip 或者直接在下面留言——独立开发，每一条反馈我都会看。

顺便说一句，今天的题你打算拿几分？我至今没拿到过自己 App 里的 SSS。

就此，完毕。

我的打鼾监测 App NightSnore 支持 7 种语言（简中、英、日、韩、德、法、阿拉伯语）。这带来一个每次发版都要经历的痛苦环节：在 App Store Connect 后台，把 What’s New（新功能介绍）逐个语言粘贴进去——切语言、粘贴、保存，再切下一个，七遍。要是 Promotional Text（推广文本）也更新了，那就是十四遍。发布过APP的朋友，肯定对此就深有体会了。

这次发 2.3.0 的时候我终于忍不住了：这玩意儿就没有 CLI 能自动化吗？

还真有，而且就是 fastlane。有意思的是，fastlane 我其实早就装了——之前一直拿它给 App Store 截图加设备边框（frameit），我一直以为它就是个截图美化工具，哈哈。这次才发现，截图加框只是它十八般武艺里最不起眼的一样。

fastlane 到底是什么

fastlane 的定位是”把 iOS/Android 发布流程的每个环节都变成可脚本化的命令”。它其实是一整套工具的集合，每个工具管一段：

1. deliver：上传元数据（What’s New、描述、关键词、截图）到 App Store Connect，本文主角。
2. snapshot：跑 UI 测试自动截图，能覆盖每种语言 × 每种设备尺寸。
3. frameit：给截图加设备边框，我之前唯一用过的那个。
4. gym / pilot：打包上传、TestFlight 分发和测试员管理。
5. match / cert / sigh：证书和描述文件的团队共享管理。
6. precheck：上传前扫描文案里的审核高危词。

单人开发、Xcode 自动签名的话，match 这类团队工具基本用不上；但 deliver 对多语言 App 来说是刚需级的效率工具。

deliver：把 ASC 表单变成本地文件

deliver 的思路很直接：ASC 后台的每个表单字段，对应本地一个文本文件，目录按语言组织：

一个很贴心的设计是：目录里有什么文件，它就只上传什么。我只放了 release_notes.txt 和 promotional_text.txt，那么描述、关键词、截图这些都不会被碰。配置文件 Deliverfile 里再把二进制和截图明确跳过：

搭一条 What’s New 流水线

我的 App Store 文案一直维护在仓库的 AppStore/*.md 里（七个语言各一个文件），每次发版往里追加一段”## What’s New (X.Y.Z)”。这个 Markdown 就是唯一数据源，所以流水线只需要一个提取脚本：从 md 里抠出指定版本的段落，写到 deliver 要的 metadata 目录去。再包一个 fastlane lane 串起来：

提取脚本里顺手做了两层校验：七个语言缺任何一个对应版本的段落就直接报错（强制多语言同步，防漏），超过 ASC 的字符上限（What’s New 4000 字符、Promotional Text 170 字符）也直接拦下。以后发版就是一条命令：

从跑命令到 ASC 七个语言全部填好，9 秒。之前手动粘贴至少十分钟，还得祈祷别粘串了语言。

API Key，和一个专门坑你的格式问题

deliver 走的是 App Store Connect API，需要一个 API 密钥：ASC 后台”用户和访问 → 集成 → App Store Connect API”里创建一个团队密钥，角色选 App Manager，会得到一个 .p8 私钥文件（只能下载一次）加 Key ID 和 Issuer ID。

然后我就结结实实踩了个坑。deliver 支持用一个 JSON 文件传密钥，我很自然地写成了指向 .p8 文件路径的形式，结果：

查了才知道：fastlane 的 Fastfile 里有个 app_store_connect_api_key 这个 action，它支持 key_filepath 参数指向 .p8 文件；但 deliver 的 api_key_path 参数指向的 JSON 文件，只认内联的 key 字段——你得把 .p8 的 PEM 内容整个塞进 JSON 字符串里（换行转成 \n）。同一个工具链里两种密钥写法长得几乎一样但互不兼容，这不纯纯挖坑嘛。正确格式长这样：

这个文件含私钥，务必进 .gitignore，待遇跟你的其他 secrets 一样。

踩坑与注意事项

1. deliver 只能写”可编辑状态”的版本（准备提交、被拒等），已在审核中或已上架的版本改不了。所以要在上传 build 之后、点提交审核之前跑它；版本还没建也没关系，deliver 会自动创建。

2. locale 代码不都带地区后缀：日语是 ja 不是 ja-JP，韩语是 ko，但英语是 en-US、德语是 de-DE。写映射表的时候留意。

3. metadata 目录里有什么就传什么，这既是特性也是风险：目录里残留一个过期的 description.txt，就会把线上描述覆盖掉。我的做法是 metadata 目录整个 gitignore，每次由脚本从 md 重新生成，保证它永远是纯派生产物。

用 skill 操作，vibe coding 更顺畅

还有一层我觉得比工具本身更有意思：这整条流水线，从功能开发、写七语言文案，到搭 fastlane、踩坑、修好，都是在 Claude Code 里完成的。搭好之后我顺手让它把整个发版流程沉淀成一个项目 skill——仓库里的一个 .claude/skills/release/SKILL.md 文件，把九个步骤写成清单：bump 版本号 → 编译验证 → 七语言 What’s New / Promotional Text → commit → xcodebuild 归档上传 → 打 tag → fastlane 同步 ASC 表单，连”deliver 的 JSON 只认内联 key”这种坑位说明都写在里面。

下次发版，我只需要说一句 /release 2.4.0，AI 就照着清单把整条链路跑完，唯一剩下的手动操作是去 ASC 点提交审核。skill 跟着仓库走，clone 下来就有，等于把发版的”部落知识”固化成了可执行的文档。对 vibe coding 来说这很关键：写代码交给 AI 大家都会了，但发布环节往往还是人肉在各个后台之间点来点去——把这段也纳入对话式工作流，从开发到上架才算真正闭环。

下一个目标

尝到甜头之后我看了一圈 fastlane 工具箱，对我这种多语言独立开发场景，下一个最值得上的是 snapshot：七个语言的商店截图现在还是手动截的，每次界面大改就是一下午。snapshot 跑 UI 测试自动出全语言截图，再接上我已经会用的 frameit 加框、deliver 上传，理论上截图这条线也能变成一条命令。挖个坑，做完再写。

发布流程自动化这件事，本质上是把”每次发版都要凭记忆和手感重复一遍的操作”变成”写一次、以后白嫖”的脚本。对独立开发者来说，省的那十几分钟是小事，真正值钱的是不再需要担心”这次是不是又漏了哪个语言”——机器不会漏。

就此，完毕。

但凡自己动手给 LLM 接过点内部数据的人，大概都被同一件事恶心过：上下文到处都是，就是没法用。表结构在元数据目录里，藏在某个有专有 API 的系统后面；指标的口径写在某个 Wiki 页面，链接还时不时失效；运维手册在网盘，注释在代码里，剩下一半干脆只在某个老同事脑子里。你想做个能回答”上周活跃用户怎么算的”的 agent，光是把这些上下文拼起来就得脱层皮，而且换个数据源、换个团队，这套拼装逻辑还得从头再来一遍。

Google 最近发了个东西想治这个病，叫 OKF（Open Knowledge Format，开放知识格式），目前是 v0.1。我看完第一反应是：这不就是给”内部知识”定了个通用文件格式嘛——类比一下，有点像知识界的 Markdown，或者说，想成为 Git 之于代码那样的存在。

OKF 到底是个啥

说穿了特别朴素：一堆带 YAML frontmatter 的 Markdown 文件，按目录组织起来，就这么点东西。没有复杂的压缩、没有运行时、不强制你装任何 SDK。一个 OKF 的 bundle（知识包）就是一个目录，每个概念对应一个 .md 文件：

每个文件头上用 YAML 写结构化字段，正文用 Markdown 写说明、schema 之类。比如一张订单表，用Google自己的例子，大概长这样：

注意最后那行——customer_id 直接用 Markdown 链接指向了 customers 表。文档之间这么互相一引用，整个知识包其实就织成了一张图。人能读，agent 也能顺着链接爬。

很克制

我个人比较欣赏它的一点是”少管闲事”。整个规范里强制要求的字段只有一个：type。其余全交给生产者自己定。这意味着它不会因为你的场景特殊就用不了。

围绕这点，它立了三条原则，我觉得是整个设计的魂：

1. 极简约束——只认 type，绝不替你过度规定。
2. 生产者和消费者解耦——格式本身就是契约。谁来生成这些文件、谁来消费它们，两边可以各自独立替换，互不绑死。
3. 是格式，不是平台——没有厂商锁定，不依赖某朵云，不要专有 SDK。这条是它跟那些”元数据目录产品”最本质的区别。

这三条凑一块，好处就很实在了：人可读（任意编辑器能打开，GitHub 能直接渲染），可移植（打成 tarball、塞进 git、挂任意文件系统都行），可互操作（A 团队产的知识包，B 团队的 agent 不用翻译直接就能吃）。而且因为就是一堆文本文件，它可以躺在版本控制里，跟代码放一起，agent 能读也能改，团队像 review 代码一样 review 知识。

Google 顺手给了几个轮子

光发个规范是空的，所以这次还附带了配套，降低上手门槛：一个参考用的”富化 agent”，能从 BigQuery 数据集自动生成 OKF 文档；一个纯静态的 HTML 可视化器，不需要任何后端，打开就能看那张知识图谱长啥样；外加三个示例 bundle——GA4、Stack Overflow、Bitcoin 数据集，拿来照着学格式正好。

这里头我觉得最值得单拎出来说的是那个富化 agent，因为它远不只是”导出元数据”那么简单。

富化 agent：让 LLM 去读文档

名字里”富化”（enrichment）这俩字是关键。光靠 BigQuery 的元数据，你能拿到的只是表名、列名、类型这些骨架；可 customer_id 到底什么含义、orders 和 customers 怎么关联、某个枚举值代表哪种业务状态——这些”肉”通常只长在人写的文档里。富化 agent 干的就是把骨架和肉缝起来。它的做法是两段式（two-pass）：

第一段，BigQuery Pass。扫源数据集，光靠 BigQuery 自身元数据，给每个发现的概念（表、字段、数据集）生成一份初始 OKF 文档。这步是机械的、确定的，产出骨架。

第二段，Web Pass，这段才是精华——它把一个 LLM（Gemini，走 AI Studio 或 Vertex AI）当成一个会自主决策的爬虫：你丢给它几个种子 URL（--web-seed，一般是官方文档地址），agent 用一个 fetch_url 工具去抓页面，然后 LLM 自己判断每页”看起来像不像权威文档”，再决定怎么处理——是拿来丰富某个已有的概念文档，还是单独建一份参考文档，还是这页没用直接跳过。它不是傻爬，是带着”我手里有哪些概念、这页能补哪个”的目标在选择性吸收。

既然是放 LLM 出去爬网，缰绳得备好：--web-max-pages 限制最多抓多少页，防止跑飞；--web-allowed-host 上域名白名单，只许它在你信任的站点里转悠。

最后吐出来的，就是一组分层组织好、带 frontmatter、能直接进版本控制的自包含 bundle。说白了，这个 agent 是 Google 给的一份”如何把现有系统改造成 OKF 生产者”的样板：结构化元数据打底，再让 LLM 读人类文档来富化——你完全可以照着这套路，给自家的数据系统写个类似的生产者。

可视化器：一个 HTML 文件就是查看器

如果说富化 agent 是”生产端”的样板，那这个可视化器就是”消费端”的样板，而且它把 OKF “是格式不是平台”那套哲学贯彻得相当彻底——连查看器都拒绝引入后端，就一个静态 HTML 文件。生成命令是富化 agent 的一个子命令：

它在生成时把整个 bundle 当成一段 JSON 直接嵌进 HTML 里，所以产物是个自给自足的单文件，可以分享、可以丢任意静态服务器、也可以跟 bundle 一起 commit。Google 就是这么干的——仓库里直接躺着三个生成好的 viz.html（GA4 50KB、Stack Overflow 122KB、Bitcoin 28KB），双击就能在浏览器里打开，看的人那边什么都不用装。

打开后是个左图右文的单页：左边一张力导向图，每个概念是个节点，颜色按 type 区分（table / dataset / reference…），节点之间的有向边就是文档正文里那些 Markdown 互链——前面说的那张”知识图谱”，在这儿被画了出来；点某个节点，右边详情面板就用 marked 把那份 .md 的 frontmatter 和正文实时渲染出来，正文里的内部链接还被改写成”在查看器里跳转”，点了不会把你甩走，而是切到对应节点。顶上一排是搜索框（匹配标题、ID、tags）、type 过滤、还有好几种图布局可切（cose、concentric、breadth-first、circle…）。图用 Cytoscape.js 渲染，全程在浏览器里跑，数据不出本地。

光说没用，我把 Stack Overflow 那个样例的 viz.html 直接搬到了自己博客下，你点开就能玩：stackoverflow_viz.html。其实我这个动作本身就是 OKF “好传播”的一个现成注脚——一个别人生成的知识查看器，我啥都不改、原样拷过来挂上就能用，这要是搁个需要起后端、连数据库的”平台”，可没这么轻巧。

几个我会留意的点

新东西总归要泼点冷水，几个我看完留了心眼的地方：

1. 目前才 v0.1。规范号摆在这，意思是接口和约定都还可能动，真要拿去做生产，得做好跟着升级的准备。
2. “只强制 type”是把双刃剑。约束少确实灵活，但也意味着不同团队产出的字段可能五花八门，跨组织互操作时，光有格式统一、字段语义不统一，照样得对齐。这部分活儿规范帮不了你。
3. 它解决的是”知识怎么存、怎么传”，不解决”知识怎么保证是对的、是新的”。frontmatter 里那个 timestamp 写得再漂亮，背后没人维护，照样会过期。说到底它是个格式，不是个能自动保鲜的系统。

说点本质的

抛开这些细节，我觉得 OKF 真正想干的事很清楚：在这个人人都在拿内部数据喂 agent 的当口，给”知识”这件东西定一个最朴素、最不挑食的通用载体。用最普通的文件约定，换跨工具、跨组织、跨时间的可移植性——这套思路，过去在代码上是 Git 干成的，在文档上是 Markdown 干成的。OKF 想在”知识”这一层复刻同样的故事。

能不能成，要看有多少人愿意给自己的系统写”生产者”、给自己的 agent 写”消费者”，把生态滚起来。但方向我是认的：与其每家都把知识锁在自己那套不兼容的专有系统里，不如先在格式上达成一致。毕竟，朴素的东西才传得开。

就此，完毕。

在这个AI时代，越来越多的应用（APP）是和AI相关的，其中有不少，对用户的请求需要调用LLM来处理，也就是要消耗token。如果这个应用，是对免费用户甚至未注册用户有一定的体验使用量的话，就要考虑怎么防止token被刷爆的问题了。恰巧我就在做一个这样的应用。

此时，一个自然而然的问题是：要怎么证明”这是正版 App 发来的”？

Apple App Attest 就是来解决这个问题的。（PS：大家如果有安卓的、PWA的解决方案，可以留言）

我想实现的是”匿名用户每天送一次 AI 评分”，不登录就能用，体验好、转化高。可这接口裸奔在公网上，谁拿 curl 写个循环都能把额度刷爆。加验证码太伤体验，强制登录又把”尝鲜”这个卖点废了。

我想要的其实是一句话：能不能让服务器确信”这条请求确实是从我那个正版 App、在一台真机上发出来的”？Apple 的 App Attest 就是干这个的。这篇把它的原理、整体流程，以及服务端到底该怎么验，讲清楚；我自己趟过的几个坑放在最后当佐料。

App Attest 解决的是什么问题

传统的”防刷”思路是给请求带个密钥或 token，可只要密钥在客户端，逆向、抓包、改包就能仿造，挡不住有心人。App Attest 换了个思路：它借助 Secure Enclave（设备上独立的安全芯片），由苹果来给你的 App 背书，证明两件事——这是从 App Store 渠道的正版 App 发出的，且跑在一台真实的苹果设备上。

这个背书是密码学保证的：签名私钥生成在 Secure Enclave 里、永远导不出来，连越狱也偷不走。所以它特别适合”匿名但要防滥用”的场景：免费额度、防注册机刷号、防接口被脚本薅。它不是用户身份认证（那是 Sign in with Apple 的活），它认的是”设备 + App”这个组合可信。

代价是它只在真机、正版渠道下成立——模拟器用不了，这点后面会再提。

两段式：attestation 和 assertion

理解 App Attest，关键是分清它的两段，这俩验证逻辑完全不同。

第一段 attestation，一次性的。App 首次要证明自己时，在 Secure Enclave 里生成一对密钥，请苹果给这把公钥签发一张证书；证书连同一坨 authenticator data 打包成 attestation 对象，发给你的服务器。服务器验完，把这把公钥存进库，跟这台设备绑定。这一步只做一次。

第二段 assertion，每次请求都做。App 用第一段那把私钥，对”本次请求的内容”签个名，随请求发出。服务器用之前存下的公钥验签——对得上，就说明这条请求确实来自那台被证明过的设备，且内容没被篡改。

客户端的代码很薄，DCAppAttestService 几个方法调一调就行。真正有讲究的是服务端这两段验证，下面分开说。

服务端怎么验 attestation

attestation 对象 CBOR 解开后，核心是一条证书链 x5c 和一段 authData。要验的东西不少，挑要点说：

证书链。x5c 里只有两张证书：给设备公钥签的叶子证书，和一张中间证书。你要做的是把它验到苹果的 App Attest 根证书。这里有个反直觉的点——根证书不在链里。别去比对”链里最后一张是不是根”，那是中间证书。正确做法是把苹果根证书内嵌进代码，用它的公钥验中间证书，再用中间证书验叶子。根证书是信任锚，得自己持有，不能从对方给的链里取。苹果根证书在 certificate authority 页面下载，建议顺手核对哈希：

nonce。光证明”证书合法”挡不住重放——截一个合法 attestation 反复发也行。苹果的办法是：服务器先发一个随机 challenge，苹果会在叶子证书的扩展里（OID 1.2.840.113635.100.8.2）塞进 nonce = SHA256(authData ‖ SHA256(challenge))。服务器照样算一遍比对，对上才说明这份证明是冲着你这次的 challenge 来的，authData 也没被动过。

剩下几项是常规校验：rpIdHash 要等于 SHA256(appId)（appId = Team ID 加 Bundle ID）；新鲜的 attestation 计数器必须是 0；aaguid 标明这是 App Attest（正式环境是 appattest，Xcode 调试走的开发环境是 appattestdevelop，两者都要放行）；最后把 authData 里的公钥 SHA256 一下，应当等于凭证 ID。全过了，把这把公钥存库。

证书链验签自己撸 ASN.1 容易出隐蔽 bug，我直接用了 @peculiar/x509，它在 Cloudflare Worker 的 WebCrypto 环境里能跑。

服务端怎么验 assertion

每次请求的验证简单些：CBOR 解开 assertion 拿到签名和 authenticatorData，先验 rpIdHash、再查计数器是否比库里存的大（防重放，每签一次苹果会自增），最后用存下的公钥验签。

验签的消息构造是这段里唯一的”暗礁”。苹果文档说签名覆盖的是 authenticatorData ‖ clientDataHash，但你要是把这俩直接拼起来交给 ECDSA-SHA256 去验，会失败。真相是：苹果用 ES256 签的是 nonce = SHA256(authData ‖ clientDataHash)，而 ES256 自己还会再 hash 一层，所以最终参与 ECDSA 的摘要是 SHA256(nonce)。WebCrypto 的 ECDSA 必定做一次 hash、跳不过，因此正确写法是先把 nonce 算出来，再把 nonce 当消息传进去，让它在上面再 hash 一次：

这层”看不见的 hash”我是把原始字节 dump 出来在本地穷举才定位到的——推理走不动时，让事实说话往往更快。

实现时几个容易绊倒的点

主线讲完了，把我真机联调时踩到的坑列一下，纯属佐料，但能省你几个小时：

1. Team ID 不一定是你以为的那个。报 “RP ID hash mismatch” 时我很懵，appId 明明拼对了。后来去构建产物里一看，签名证书的 team 和描述文件的 team 是两个，App Attest 取的是 application-identifier 里那个：

2. COSE 公钥是整数键。authData 里那把公钥是 COSE 格式，x、y 的键是 -2、-3 这种整数。cborg 默认解对象会直接抛 “non-string keys not supported”，得开 useMaps 解成 Map 再 get：

3. 模拟器测不了。App Attest 在模拟器上直接不支持，匿名链路只能上真机。开发期可以在服务端留个开关跳过验证方便联调，但上线前务必删掉。

值不值得用

如果你有”匿名 / 低门槛、但又怕被脚本滥用”的接口，App Attest 是目前苹果生态里最硬的一道闸：信任根在苹果、私钥锁在 Secure Enclave，比任何塞在客户端的密钥都难仿造。代价是只覆盖真机正版、客户端服务端都得改、还得忍受一段真机调试的来回。

它的坑也基本都不在文档主线上，而在那些”想当然”的接缝处——根证书的位置、Team ID 的来源、COSE 的键类型、ES256 那层默认的 hash。单看每个都不难，叠在一起就够耗你一天。提前知道它们长什么样，就能少趟很多。

全文完。

起因是最近我的域名要过期了，在操作续费(顺便还换了个注册商)的过程中，习惯性地敲了个 whois：

被拒了。换 whois 服务器、加参数，都是同一句话：请去网页上查。哈哈，用了快二十年的命令，说不让用就不让用了。

查了一下才知道，.li 域名的注册局是瑞士的 SWITCH（和 .ch 同一家），他们已经把传统的 43 端口 whois 服务关掉了，只留了个带验证码的网页查询入口（甚至whois返回的网址都是错的…）。原因也不难猜：一是 GDPR 之后，欧洲的注册局对注册人信息的批量获取管得很严，而 whois 这个协议天生没有任何访问控制，谁都能无限爬；二是网页入口可以加验证码和限流，挡掉数据挖掘的脚本。

那命令行党就没活路了吗？还真有——RDAP。

RDAP 是什么

一句话概括：RDAP 就是基于 HTTPS + JSON 的 whois。

whois 这个协议是 1982 年的产物，比 DNS 还老。它的问题攒了几十年：输出格式没有任何标准，每家注册局返回的文本长得都不一样，想程序化解析就得给每家写一套正则；协议里压根没有字符编码的概念，中文注册人姓名怎么显示全看运气；更要命的是没有认证和权限控制，这也是 GDPR 之后各家注册局纷纷关门的直接原因。

IETF 在 2015 年发布了 RDAP（Registration Data Access Protocol）来接班，核心就是 RFC 7480 那一组标准。ICANN 从 2019 年起强制要求所有 gTLD 注册局和注册商部署。所以 .com / .org / .net 这些域名，现在都有标准的 RDAP 接口可以查。

怎么用

不需要装任何东西，一个 curl 就够了：

返回的是规规矩矩的 JSON。我自己这个域名查出来大概长这样（节选）：

注册商、注册日期、NS、状态，一目了然。所有时间都是 ISO 8601 格式，状态码用的是标准的 EPP 状态（active、client transfer prohibited 这种），不再是各家自己发明的描述。对写脚本的人来说，这比解析 whois 文本舒服太多了。

顺便发现一个副作用：查一个没注册的域名，RDAP 直接返回 HTTP 404。所以拿状态码就能批量探测域名是否被注册，连响应体都不用解析。

不用记每家的地址：Bootstrap 机制

用 whois 有个老问题：你得先知道该问哪台服务器。查 .com 要问 Verisign，查 .org 要问 PIR，记不住。

RDAP 把这事标准化了。IANA 维护着一份 dns.json，里面列着每个顶级域对应的 RDAP 服务地址：

客户端缓存这份文件，就能自动路由到正确的服务器。嫌麻烦的话，直接用 rdap.org 这个公共服务，它帮你做转发：

查任何域名都是这一个入口，再也不用记谁家域名归谁管了。

那些 xn-- 开头的乱码是什么

翻 dns.json 的时候会看到一堆奇怪的顶级域，比如 xn--kpry57d、xn--fiqs8s。这不是乱码，是国际化域名（IDN）的 Punycode 编码。

DNS 天生只认 ASCII，但域名总不能只让用拉丁字母。于是有了 Punycode：把 Unicode 字符串编码成纯 ASCII，再加个 xn-- 前缀。解码出来其实都是各国文字：

想自己玩的话，Python 一行就能互转：

RDAP 对这个的支持也很到位：响应里同时给 ldhName（ASCII 形式）和 unicodeName（Unicode 形式）两个字段，客户端想显示哪个自己挑。而 whois 协议连编码都没定义，IDN 的处理完全看各家心情。

隐私这块儿

GDPR 干掉了 whois 里的注册人信息，RDAP 则把”隐藏”这件事做成了标准。响应里有个 redacted 数组，明确列出哪些字段被隐藏了、用的什么方式（整个移除、替换成占位值、还是置空），机器可读。需要完整数据的执法机构或商标方，可以走认证通道申请。这套分级访问的设计，whois 是完全做不到的——它只能简单粗暴地把字段换成 REDACTED FOR PRIVACY，别的什么都表达不了。

踩到的坑

也不是处处顺利。RDAP 标准归标准，各家实现的完整度差很多：

1. ccTLD 不强制部署。gTLD 是 ICANN 管的，必须上 RDAP；但国家域名各自为政，有的部署了，有的没有，有的部署了但缺斤短两。

2. 比如 .li / .ch 的 RDAP 就不返回到期时间。events 里只有 registration，没有 expiration，想知道域名什么时候过期，还是得去注册商后台看。而 .com / .org 的 RDAP 是给全的。

3. 注册局和注册商是两级数据。注册局（Registry）的 RDAP 只有基本信息，更详细的注册人信息要顺着响应里 rel 为 “related” 的链接去注册商（Registrar）的 RDAP 再查一次。

4. 部分url有反爬机制，直接用curl会失败，如果失败可以试试正常用浏览器打开。

最后

RDAP 其实没什么革命性的东西，本质上就是把四十多年前的纯文本协议用 HTTPS + JSON 重写了一遍。但恰恰是这种”无聊的现代化”，把格式混乱、没法国际化、没有隐私控制这几个老大难问题全解决了。另外它不只能查域名，IP 地址和 AS 号也是同一套协议（curl rdap.org/ip/8.8.8.8 试试），五大 RIR 都已经支持了。

以后再想 whois 什么东西，可以先试试 curl rdap.org。毕竟传统 whois 关一家少一家，而 RDAP 才刚刚开始。

就此，完毕。

和之前的awk手册一样，又是一个Claude design的作品。

这次做了《滕王阁序》的逐字解析，还挺有意思的，丢个链接。

如果有错误之处，可以去这里提issue，也不排除以后做其他经典古文的解析。

还记得上次那篇吗？当时我接手 Notchy 的时候，基本就是原作者 Adam Lyttle 的初始版本——点子非常好，但功能比较基础，bug 也不少。我本来只是想”修修 bug，打个包”就完事了。

结果一改就停不下来了。

55 个 commit、4600 多行 Swift 之后（当然大部分都是 vibing 的），Notchy 已经从一个”能用”的 demo 变成了我日常干活的主力终端。是的，之前我还是混着状态，现在 iTerm2 已经从 Dock 上消失了。

这篇就来聊聊，到底改了些啥，才让我有底气做出这个切换。

Terminal UX：从”能打字”到”能干活”

原版的终端体验非常朴素——打开一个黑框，能输入命令，仅此而已。要把它当日用终端，差的东西太多了。

动画和视觉：面板从菜单栏后面滑出来（slide-down），背景是 NSVisualEffectView 的毛玻璃效果。看起来比较像一个系统原生组件，而不是一个第三方窗口硬贴在那里。

快捷键：这是最影响手感的部分。

• 全局热键 Ctrl+` 呼出/收起面板，任何应用中随时可用
• Cmd+1..9 切 tab，Cmd+W 关 tab，Ctrl+Tab 和 Ctrl+Shift+Tab 循环切换
• Cmd++ / Cmd+- 缩放字体（全局生效，持久化），Cmd+0 重置
• Shift+Enter 发送换行而不是提交（通过 kitty CSI u 协议实现），这对 Claude Code 的多行输入至关重要
• Cmd+Backspace 清行（发 Ctrl-U）
• Copy-on-selection，选中即复制，iTerm2 用户的肌肉记忆

滚动：这块踩了不少坑。原版在 TUI 应用（比如 Claude Code 自己的界面）里滚动完全不工作。修了 alternate screen buffer 的滚轮转发，修了自动跟随输出的逻辑（在底部时跟随新输出，在回看历史时保持位置不动），还修了退出 vim/less 之后视口跳到顶部的 bug——这个 bug 的原因是 alt buffer 的 yDisp 始终是 0，退出时被误判为”用户在回看滚动历史”。Scrollback buffer 大小也做成了可配置的（默认 1000 行，最大 50000）。

字体：支持 Nerd Font，Powerline 图标正常显示。

从 Claude 专属到多 Agent 支持

原版 Notchy 是纯粹为 Claude Code 设计的——检测到 CLAUDE.md 就自动启动 claude，写死的，没有别的选项。

但现实是，越来越多人在用不同的 AI coding agent。OpenAI 的 Codex 出来之后，我公司也给我们同时配备了Claude 和 Codex，我会在不同项目中用不同的agent，Notchy应该能做到自动判断：

• 项目里有 CLAUDE.md → 启动 claude
• 项目里有 AGENTS.md → 启动 codex
• 两个都有 → 看 Settings 里的 Preferred Agent 设置来决定
• 两个都没有 → 不启动，给你一个普通 shell

终端状态检测也做了相应适配。原版只认 Claude 的输出模式（大写的 Esc to interrupt、Esc to cancel 等），Codex 的输出格式不一样——小写的 esc to cancel、you approved … to run …、Conversation interrupted。现在都能正确识别，notch 上的状态指示对两个 agent 都能工作。

这个改动的价值在于：Notchy 不再是一个”Claude Code 的前端”，而是一个通用的 AI coding agent 终端。以后再出新的 agent，加个 case 就行。

Tab 管理：三种 Tab，各司其职

原版只有 Xcode 自动检测的 tab。我加了一套完整的 tab 类型系统：

• Xcode tab（青色边框）：自动创建，跟 Xcode 项目生命周期绑定
• Pinned tab（橙色边框）：手动固定的 tab，跨重启持久化。固定时会通过 proc_pidinfo 快照当前 shell 的 CWD，重启后自动 cd 回去并重新检测 AI agent，适用于非 Xcode 的项目。
• Normal tab（无边框）：+ 按钮创建的临时 tab，关掉 app 就没了

另外加了 Shadow Tab——右键一个 Xcode 或 Pinned tab，选 Shadow Tab，会在旁边开一个 plain shell，cd 到同一个目录但不启动 Claude/Codex。跑 git status、npm run build 这种临时命令特别方便，不用打断正在工作的 agent。名字后面会加个 $ 后缀以示区分。

关 Pinned 和 Xcode tab 之前会弹确认框，防止手滑。这些 tab 带着恢复状态，误关了成本很高。

IME 输入法支持

SwiftTerm 的 NSTextInputClient 实现有问题，输入法的 marked text（预编辑文本）直接被吞掉了。打拼音的时候只能看到候选窗，看不到自己输入了什么。

第一版我做了一个 HUD 风格的浮动面板，显示在光标上方。后来改成了 inline 渲染，和 macOS Terminal.app 的行为一致——用终端前景色画文字，背景色填充遮住底下的块状光标。视觉上自然多了。

这个功能对中文用户来说是刚需。

自动更新 (Sparkle)

手动下载更新太烦了，用户也不会主动去看 GitHub Releases。所以集成了 Sparkle——macOS 上事实标准的自动更新框架。

这块的详细过程我单独写了一篇：给 macOS App 加自动更新：Sparkle 入门。大家可以参考这里。

CI/CD 发布流水线

推一个 v* tag 到 GitHub，Actions 自动搞定剩下的事：

1. xcodebuild archive 构建并用 Developer ID Application 签名
2. notarytool 提交公证（Apple 审查恶意代码）
3. 打包成 DMG 和 ZIP
4. 用 EdDSA 私钥签名 ZIP，生成 appcast.xml
5. 把所有产物挂到 GitHub Release 上

如意要长期维护这个应用，这些都是必不可少的基础设施了。

其他细节

• 外接显示器支持：接了外接显示器（比如 Studio Display）的时候，鼠标悬停在外屏顶部中央（摄像头区域）也能唤出面板，和 MacBook notch 的交互保持一致
• 通话静音：检测到麦克风在使用（Zoom、FaceTime 等），自动把 Notchy 的提示音静音，不会在开会的时候突然”叮”一声
• Checkpoint 增强：加了一个 popover 列出所有 checkpoint，可以浏览、恢复、删除任意一个，不再只能操作最近的那个
• Settings 窗口：从一个简单的菜单 toggle 变成了完整的 Settings 窗口（Cmd+,），分 General / Integrations / About 三个 tab
• Notch 动画优化：改成更平滑的 ease-in-out 曲线，修了 notch 和屏幕顶部之间的缝隙，修了 hover → click 模式切换时 notch 缩小的问题
• 面板大小持久化：拖动调整大小后会记住，下次打开恢复。调整时右上角还会显示尺寸指示

为什么能替代 iTerm2

这个问题的答案很简单：我日常用终端 90% 的场景是跑 AI coding agent。

在这个场景下，Notchy 比 iTerm2 好用。Ctrl+` 一按就出来，不用切窗口；Xcode 项目自动检测，不用手动 cd；agent 自动启动，不用手动输命令；状态一目了然，notch 上的小药丸告诉你 agent 是在干活还是在等你。

剩下 10% 的临时命令？Shadow Tab 搞定。

当然，如果你的主要场景是 SSH 管理十几台服务器、或者需要 tmux 分屏，iTerm2 仍然是更好的选择。但如果你和我一样，日常就是在本地项目里跑 Claude Code 或 Codex——试试 Notchy 吧。

GitHub: bones7456/notchy，非常欢迎提issue、MR等。。。

安装方式：去 Releases 下载 DMG 或 zip，拖进 /Applications 就行。因为签名、公证过，所以不会弹 Gatekeeper 警告。

全文完。