源码指纹自升级（Source Fingerprint Self-Upgrade）—— 参考资料

⚠️ 本 skill 是参考资料，不是可执行功能。AI 不会自动触发它去做任何事；只有你主动 @ 它、或明确要求查阅时才会加载。其价值在于：把「源码指纹自升级」这套设计思路归档成规范形态，供你阅读、或往自己项目里套。

这是什么

"源码指纹自升级"是一种让程序在启动时自己判断该不该启动、要不要替换掉已经在跑的旧程序的做法。

核心思路：不靠人手动输出版本号，而是直接对程序自身的源码算一个哈希指纹。源码有任何改动，指纹就变；没动，指纹就不变。

启动流程

程序启动，先算自己的源码指纹 FP_new。
检查目标端口有没有已经在跑的旧程序。
没有旧程序 → 直接正常启动。
有旧程序 → 向它要它的指纹 FP_old。
- FP_old === FP_new → 两份代码一模一样，说明"我"就是已经在跑的那个 → 直接退出（不要重复启动）。
- FP_old !== FP_new → 代码升级了 → 先优雅关闭旧程序（释放端口），再启动自己（替掉旧的）。

为什么不用版本号

版本号是"人写的字符串"，容易漏改：

改了代码但忘了 bump 版本号 → 两份不同代码被认为"同一版本" → 旧程序不会被替换，bug 还在。
没改代码但误 bump 版本号 → 被认为是"新版本" → 白白重启一次。

源码指纹是"代码算出来的"，代码变它才变，不存在"忘了改"的问题。

大公司通常结合使用：版本号（给人看）+ commit 哈希 / 构建摘要（给机器比）+ 健康检查接口。源码指纹是其中"给机器比"的一种，且不需要 git、不需要构建步骤，纯 JS 项目直接可用。

采集哪些指纹（规则）

指纹模块 demo/fingerprint.js 的规则如下：

规则	说明
只采集 `.js` 文件	这是真正的"源码"，会影响程序行为。非 JS 脚本（`.sh`/`.py`/`.bat` 等）不算。
递归扫描	从根目录开始，子目录、子子目录全部递归进去，包括任意层嵌套子模块。
按路径排序	先 `sort()` 再拼接，保证不同机器、不同文件名顺序下指纹一致。
算法 sha256	用 Node 内置 `crypto`，无第三方依赖。
取前 16 位十六进制	`digest("hex").slice(0,16)`，够区分又好展示。
文件间用 `\0` 分隔	每个文件内容后加一个 `\0`，避免两个文件首尾拼接产生误判。
排除运行期目录	`node_modules`、`runtime`、以 `.` 开头的目录不计入（这些不是源码）。
读不到就跳过	单个文件读失败不影响整体，保证健壮性。

关键：非 JS 脚本（如 demo/scripts/run.sh）是程序的一部分，但按规则不计入指纹。 因为改个部署脚本不该触发"代码升级重启"。

文件结构

source-fingerprint-self-upgrade/
├── SKILL.md            # 本文件（skill 入口）
├── README.md           # 详细原理与规则文档
├── package.json        # type: module
├── demo/               # 示例程序（可运行）
│   ├── fingerprint.js  # 指纹计算模块（核心，纯函数）
│   ├── main.js         # 入口：HTTP 服务 + 自升级协调逻辑
│   ├── lib/            # 递归扫描验证用的嵌套模块
│   └── scripts/        # 非 JS 脚本（不计入指纹）
└── test/
    └── test.js         # 最简单的测试

怎么跑（验证用，非 skill 功能）

cd source-fingerprint-self-upgrade
node demo/main.js            # 启动示例服务（默认端口 9421）
# 另开终端
curl http://localhost:9421/version   # 看指纹
curl http://localhost:9421/health    # 健康检查
node test/test.js           # 跑测试（验证指纹行为）

验证指纹是否生效：

改一个 .js 文件（例如给 lib/util.js 加一行注释）→ 指纹立刻变化。
改 scripts/run.sh → 指纹不变（它不计入指纹）。

给 AI 的提示（套用到你自己的项目时看）

如果你（AI）要帮用户实现这套机制：

把 fingerprint.js 当成一个纯函数模块引入，不要在里面写副作用。
入口文件在启动逻辑最前面调用 computeFingerprint()，并在 /version 接口返回它。
自升级协调要遵守顺序：先让旧程序释放端口，再启动自己。绝不允许"先启动新的、再杀旧的"——新程序会因端口被占而启动失败。
关闭旧程序优先用程序自己提供的优雅停机接口（如 POST /shutdown）；没有的话再回退到按 PID 杀进程。
指纹不一致且旧程序无响应时，要有超时兜底，避免卡死。
永远不要为了"方便"把 node_modules、上传目录、截图目录算进指纹，否则指纹会天天变。

备注：更完整的背景说明见同目录 README.md。

source-fingerprint-self-upgrade-yashu