零依赖Node脚本自动刷新README徽章:frantic-board Town Crier实现解析
零依赖Node脚本自动刷新README徽章:frantic-board Town Crier实现解析
frantic-board 是 gofrantic.com(一个 AI Agent 悬赏公告板)的公开仓库,它 README 顶部的统计徽章和账本区块完全由一个零依赖的 Node 脚本 Town Crier 自动刷新,没有任何第三方库。本文带你拆解这套"标记区块 + 幂等写入"的实现思路,看看它如何让 README 数据永远保持最新。
徽章从哪来:README 顶部的"生命体征"
打开 README.md,你会在标题下方看到一排 shields.io 徽章:
<!-- crier:vitals:start -->
<img src="https://img.shields.io/badge/day-133-FF2E88" alt="day: 133" />
...
<!-- crier:vitals:end -->
这些徽章(运行天数、开放悬赏数、累计结算金额、注册 Agent 数)以及后面的"账本"代码块,都不是人手维护的。README 中明确写道:nothing here is hand-kept——这里的每一行数据都由 Town Crier 定时任务读取公开接口后重写。
对于任何"README 即门面"的开源项目来说,这是很典型的需求:数据要鲜,但不能靠人肉。
Town Crier 工作流程:一次定时任务做了什么
整个实现只有 scripts/town-crier.mjs 一个文件,要求 Node 20+,仅用到内置的 node:fs 和全局 fetch,零 npm 依赖。流程非常清晰:
- 取数:请求
stats和ledger两个公开 JSON 接口,地址可用环境变量FRANTIC_STATS_URL、FRANTIC_LEDGER_URL覆盖(见 town-crier.mjs#L12-L13) - 渲染:把数字渲染成 shields.io 的
<img>徽章和账本代码块 - 替换:只重写标记区块之间的内容
- 落盘:内容有变化才写文件,否则直接退出
它作为定时任务(scheduled action)在 CI 里运行,每次跑完,README 就自动"喊"出最新数据。
标记区块:只改"该改的地方"
这套方案最核心的技巧是成对 HTML 注释标记。town-crier.mjs#L15-L18 定义了两组标记:
<!-- crier:vitals:start --> / <!-- crier:vitals:end -->
<!-- crier:ledger:start --> / <!-- crier:ledger:end -->
替换函数 replaceSection 的逻辑只有三行核心判断:
- 找不到开始或结束标记 → 原样返回,什么都不改
- 找到标记 → 只截断标记之间的一小段,替换后拼回
这样做的好处是:README 的其他内容(标题、章节、链接)永远不会被脚本误伤;即使标记被误删,脚本也会安全地"什么都不做",而不是把整个文件写坏。
徽章的生成函数 badge() 还顺带处理了两件容易踩坑的小事:对标签和值做 encodeURIComponent 转义(shields.io 的下划线要写成 __),以及对 alt 文本做 HTML 转义,避免特殊字符破坏 markdown。
优雅降级与幂等写入
脚本对"失败"的处理非常克制:
- 接口没上线:fetchJson 捕获一切异常并返回
null,此时脚本 changes nothing and exits clean——工作流可以先合入、安静待命,等接口上线后自动"复活" - 幂等写入:落盘前先比较新旧内容(town-crier.mjs#L79-L84),有变化才写文件并输出
crier: README updated,否则输出crier: nothing new to shout
这意味着重复执行不会产生无意义的 commit,也不会污染 git 历史——对 CI 定时任务来说,这种"无变化即静默"的行为至关重要。
如何把这套思路用到你的项目
Town Crier 的模式可以总结为三点,非常适合新手借鉴到自己的 README 自动化里:
| 要点 | 做法 | 好处 |
|---|---|---|
| 标记区块 | 用成对 HTML 注释圈定"可写区域" | 误伤面为零,可人工审查 |
| 纯函数渲染 | 数据 → 字符串,渲染与 IO 分离 | 易测试、易本地预览 |
| 幂等 + 优雅失败 | 内容不变不写盘、接口挂了不动文件 | CI 可安全定时运行 |
另外,"零依赖"本身就是一个工程卖点:没有 package.json、没有供应链风险、CI 里不需要 npm install,任何有 Node 20 的环境都能直接跑。这个仓库也欢迎改进 Town Crier 的 PR(见 CONTRIBUTING.md),验证逻辑则放在 verify/ 目录中,供各悬赏的验收使用。
小结:一个百行左右的 .mjs 脚本 + 两对注释标记,就让 README 数据实现了"自动保鲜"。如果你也受够了手动更新仓库数据,不妨照搬这套"标记区块 + 幂等写入"的极简方案。
