v1.0.2 —— 修 demo 在重定向下的崩溃 + README 到处都点得开

v1.0.2

pip install preflight-check-cli
preflight-check demo

修了什么

demo 在输出被重定向时会崩。 它的输出里有 🔴 / 🟢，而 Windows 的控制台代码页
（中文 cp936、英文 cp1252）编不出 emoji：

UnicodeEncodeError: 'gbk' codec can't encode character '\U0001f534'

整条命令崩在写第一行之前 —— 而"被重定向"恰恰是它最常见的用法：写日志、进 CI、| grep。
现在重定向时 stdout / stderr 会钉成 UTF-8；真正的终端不动它（那里 rich 处理得更好）。
生成的文件不受影响 —— 那些写文件的调用每一个都显式带了自己的编码。

改了什么

• README 的链接改成绝对地址：PyPI 上的项目描述就是 README，而它不解析相对路径 ——
  原来那 17 个链接在 PyPI 页面上点了就是 404。
• 死链测试跟着升级：指向本仓库的绝对链接现在也会被离线核对
  （把前缀去掉还原成仓库内路径），所以覆盖没有因为这次改动丢掉。
• README 首页改成纯项目介绍（「今天修了什么」属于过程记录，留在 STATUS / PROGRESS 里），
  并加了 PyPI 版本徽章。

验证

项	证据
CI	六格全绿：ubuntu / windows × Python 3.11 / 3.12 / 3.13（每格 545 passed, 5 skipped）
本地	547 passed + 3 skipped；mypy 44 个文件无错误；ruff 干净
修的那个 bug	新增的测试在抽掉修复时会立刻红，报的就是上面那个 UnicodeEncodeError
链接	故意写错一处 → 测试立刻报「指向本仓库，但 xxx 不存在」
发布	PyPI 上有构建来源证明（OIDC attestation）

矩阵覆盖仍然是 3/60，问卷答案仍未接到结论上 —— 那些是功能缺口，不是这一版的事。

v1.0.1 —— 首个发布到 PyPI 的版本

v1.0.1 —— 首个发布到 PyPI 的版本

pip install preflight-check-cli
preflight-check demo

CI 告诉你「测试通过了没有」。
这个工具告诉你「该做的测试有没有被做过」。

这一版为什么换了分发名

preflight-check 在 PyPI 上注册不了。PyPI 的「名字太相似」检查会把 - _ . 全删掉、
再把 l/L/i/I 换成 1、o/O 换成 0，然后全等比较 —— 而 preflight-check 与已存在的
pre-flight-check（v1.4.0，一个活跃的 AI agent
质量门禁项目）归一化后是同一个字符串。去掉连字符也救不了：preflightcheck 归一化后还是它。

所以只改了分发名，命令名和导入名一个都没变：

	名字
分发（PyPI）	preflight-check-cli
导入包	preflight_check
命令	preflight-check

v1.0.0 只发在 GitHub（那时 pyproject.toml 里还是旧名字）—— 所以 PyPI 首发是 1.0.1。

这一版验证到了什么

项	证据
CI	六格全绿：ubuntu / windows × Python 3.11 / 3.12 / 3.13（每格 544 passed, 5 skipped）
本地	546 passed + 3 skipped；mypy 44 个文件无错误；ruff check + format 干净
打包	sdist + wheel 构建、twine check 通过，PyPI 上有构建来源证明（OIDC attestation）
干净安装	新建虚拟环境里 pip install preflight-check-cli，preflight-check demo 的输出与 README 第一屏逐行一致

顺带一提：v1.0.0 之前那次 CI 是第一次真跑，它在 windows-latest 上抓出 4 个本地
一条都看不到的失败（3 条是子进程输出编码只钉了一头 —— 把一次崩溃读成了「没问题」；
1 条是断言假设只在虚拟环境里成立）。修完才有这一版。

还没做的（说清楚比含糊好）

• 矩阵覆盖 3/60 —— 60 个「机制 × 不变量」格子里只有 3 格有规则真的去查。最大的功能缺口。
• 问卷的 5 条答案目前只进报告，还没接到严重度 / 门禁上。
• demo 在中文区域的 Windows 上、输出被重定向时会崩（🔴 这类 emoji 编不进 cp936 代码页；
  加 PYTHONIOENCODING=utf-8 正常，其余命令不受影响）。
• 只在 2 个真实项目上验证过，换一种文档风格表现未知。

MIT 许可。踩过的 18 个坑在
docs/PITFALLS.md
—— 那可能是这个仓库里最值钱的一份文档。

v1.0.0 —— 首个公开预发布（测试版本）

v1.0.0 —— 首个公开预发布

CI 告诉你「测试通过了没有」。
这个工具告诉你「该做的测试有没有被做过」。

⚠️ 这是一个预发布（pre-release）。 功能完整、CI 全绿，但还没有人在真实项目上长期用过它 ——
只有作者自己的两个项目跑过。装上之前请知道这一点。

这一版验证到了什么

项	证据
6 个环境组合	✅ ubuntu / windows × Python 3.11 / 3.12 / 3.13 —— 全绿，每格 544 passed, 5 skipped
类型与风格	mypy 44 个文件无错误 · ruff check + format 干净
打包	sdist 与 wheel 能构建 · twine check 通过（CI 实测，不只是本地声称）
语料	29 条规则（每条都有正例 + 反例夹具）· 10 机制 × 6 不变量 · 4 个场景档案
离线可用	preflight-check demo 零 LLM、零联网就能跑出对比

本地是 546 passed + 3 skipped：多的那 2 条是验收测试，需要作者另一个项目在场（CI 上正确地跳过，而不是假装通过）。

推上 GitHub 之后，第一次 CI 就抓出来的问题

这一版之前的代码本地 545 条全绿，但它从没在真实的 CI 环境里跑过。第一次跑红了 4 条，
每一条都属于「装完之后才出现」那一类：

1. 子进程输出编码只钉了一头 —— 父进程按 UTF-8 解码，却没告诉子进程按什么编码写。
   英文 Windows 上代码页是 cp1252，子进程写不出非 ASCII 就直接崩在写第一行之前，
   stdout 为空；而这个项目里「空输出」的含义是「工具说它没发现问题」。
   一次真实的崩溃被读成了一次干净的结果 —— 正是这个工具最想防的那种错。
   本地是 cp936（编得出中文），所以一直没露出来。
2. find_tool 的测试断言假设「工具和 python.exe 在同一层目录」—— 那只在虚拟环境里成立，
   CI 上是非虚拟环境安装，控制台脚本在 Scripts/。错的是断言里的假设，不是实现。
3. ci.yml 缺 workflow_call —— 发布工作流用 uses: 复用它，而 GitHub 要求被复用的工作流
   必须声明这个触发器。少了它，推 tag 时整个发布运行会在校验阶段失败，
   而本地测试依然全绿。
4. 上面这条现在有测试守着了：新增的测试会扫描所有 uses: ./.github/workflows/*.yml 引用，
   要求被引用的工作流可被复用（把那一行删掉，它会立刻红）。

还没做的（说清楚比含糊好）

• 未发布 PyPI —— 发布工作流已经写好（可信发布，不需要 token），缺的是 PyPI 侧的项目配置。
  今天的 tag 已经把它跑到最后一步，上传会被 PyPI 拒绝（没有可信发布者），这是预期的。
• 矩阵覆盖 3/60 —— 60 个「机制 × 不变量」格子里只有 3 格有规则真的去查。这是最大的功能缺口。
• 问卷答案目前只进报告，还没有接到严重度 / 门禁上。
• 只在 2 个真实项目上验证过，换一种文档风格表现未知。

试它

git clone https://github.com/lddd1026/preflight.git
cd preflight
pip install -e ".[dev]"

preflight-check demo                 # ⭐ 离线：不配 Key、不联网就能看到对比
preflight-check run <你的项目>        # 确定性检查（零 LLM）
preflight-check mechanisms <你的项目> # 机制推导：这个项目该查哪些不变量

MIT 许可。踩过的 18 个坑写在 docs/PITFALLS.md ——
那可能是这个仓库里最值钱的一份文档。