diff --git a/.pi-lens.json b/.pi-lens.json index f8564df..c03b53a 100644 --- a/.pi-lens.json +++ b/.pi-lens.json @@ -1,36 +1,8 @@ { "$schema": "https://pi-lens.dev/schema/project.json", - // 关掉 pi-lens 对本仓库的自动改写。 - // - // # 为什么必须显式关 - // - // pi-lens 编辑任一文件后会「安全格式化」它。本仓库没有任何格式化器配置时， - // 它走 smart-default 回退：.ts/.tsx/.js → biome，**.html → prettier** - // （见 pi-lens 的 FORMATTER_POLICY_BY_EXTENSION）。两套默认值都与本仓库的 - // 手工排版不兼容 —— biome 默认 tab 缩进 + 双引号，prettier 默认双引号、 - // 还会把 改成小写、按 80 列折行。 - // - // 已经造成过两次真实损失： - // 1) 19a3161 用 `git add -A` 把约 7000 行 biome 重排扫进功能提交， - // 使那次提交无法审查（还掩盖了一处 Go 文件的删行）； - // 2) a404cba 里 prettier 改写了 client/electron/index.html —— 单引号变双引号、 - // DOCTYPE 变小写，直接打破 test/theme.test.mjs 的两条断言。 - // 该测试恰好要求同步内联脚本里是 classList.add('dark')（单引号）。 - // - // 根 biome.jsonc 只挡得住 biome，挡不住 prettier：两者是并列的候选格式化器， - // 各有各的配置。所以真正的开关是这里 —— 项目级、两条改写路径一起关。 - // - // # 为什么不是「把格式化器配成本仓库风格」 - // - // 试过把缩进/引号/lineWidth 全部对齐，`biome format --write` 仍然改动 17 个文件： - // 本仓库的注释按语义换行、数组与调用按可读性手工折行，这些格式化器还原不了。 - // 只要它还在跑，每次编辑都会产生与内容无关的大面积 diff，把真正的改动埋掉。 - // - // 本仓库的静态检查由 tsc / go vet / tree-sitter / ast-grep 与各自的测试套件承担。 "format": { "enabled": false }, - // autofix 同理：它会在与本次改动无关的行上做自动修复。 "autofix": { "enabled": false } diff --git a/biome.jsonc b/biome.jsonc index 2b64f49..a0cc648 100644 --- a/biome.jsonc +++ b/biome.jsonc @@ -1,4 +1,9 @@ { + // ⚠️ 本文件只是**两道闸中的一道**：biome 挡得住 biome，挡不住 prettier。 + // 真正的总开关是根目录的 `.pi-lens.json`（两条改写路径一起关）， + // 而它**必须是严格 JSON** —— 带 // 注释会被 pi-lens 整份忽略、防护静默失效。 + // 完整来龙去脉见 docs/DEV-TOOLING.md。 + // // 本仓库**不使用** biome 的格式化器，只借它做诊断（且由 pi-lens 统一调度）。 // // # 为什么显式关闭 diff --git a/docs/DEV-TOOLING.md b/docs/DEV-TOOLING.md new file mode 100644 index 0000000..7ea6c92 --- /dev/null +++ b/docs/DEV-TOOLING.md @@ -0,0 +1,69 @@ +# 开发工具配置：为什么关掉 pi-lens 的自动改写 + +本仓库**明确关闭** pi-lens 的项目级自动格式化与 autofix。这份文档记录原因， +配置本身在 `.pi-lens.json`（根目录）。 + +## 一句话 + +pi-lens 编辑任一文件后会「安全格式化」它，而它的默认格式化器与本仓库的手工排版 +不兼容 —— 每次编辑都会产生与内容无关的大面积 diff，把真正的改动埋掉。 +已经造成过两次**真实损失**。 + +## ⚠️ `.pi-lens.json` 必须是严格 JSON + +pi-lens 的配置加载是： + +```js +// pi-lens dist/index.js +PROJECT_CONFIG_BASENAMES = ['.pi-lens.json', 'pi-lens.json']; // 没有 .jsonc +function parseConfigFile(configPath) { + const text = fs.readFileSync(configPath, 'utf-8'); + raw = JSON.parse(text); // ← 不做去注释处理 +} +// 解析失败 → 打一行警告，然后**整份忽略** +``` + +所以**带 `//` 注释会让这份配置完全失效**，而失败方式是静默的： +进程照常跑，只有启动时一行 `[pi-lens] ignoring invalid project config`。 + +这个坑真的踩过：第一次写这份配置时把大段理由写成了 `//` 注释， +于是「已经关掉了」这个结论是假的 —— 防护从一开始就没生效。 +现在理由放在本文件里，JSON 里只留一个 `$comment` 指针。 + +## 为什么必须关 + +pi-lens 在编辑文件后会走 smart-default 回退选择格式化器（见它的 +`FORMATTER_POLICY_BY_EXTENSION`）： + +| 扩展名 | 默认格式化器 | +|---|---| +| `.ts` `.tsx` `.js` | biome（默认 tab 缩进 + 双引号） | +| `.html` | prettier（双引号、`` 变小写、按 80 列折行） | + +两套默认值都与本仓库的排版冲突。两次已发生的损失： + +1. **`19a3161`**：`git add -A` 把约 7000 行 biome 重排扫进了功能提交， + 那次提交无法审查（还掩盖了一处 Go 文件的删行）。 +2. **`a404cba`**：prettier 改写了 `client/electron/index.html` —— 单引号变双引号、 + DOCTYPE 变小写，直接打破 `test/theme.test.mjs` 的两条断言（该测试要求 + 同步内联脚本里是 `classList.add('dark')`，单引号）。 + +## 为什么不是「把格式化器配成本仓库风格」 + +试过：把缩进、引号、lineWidth 全部对齐之后，`biome format --write` 仍然改动 +17 个文件 —— 本仓库的注释按语义换行、数组与调用按可读性手工折行， +这些格式化器还原不了。 + +## 谁在守着这个仓库的格式 + +不是格式化器，是这些： + +- `tsc --noEmit`（前端类型） +- `go vet` / `gofmt -l`（Go） +- tree-sitter / ast-grep（pi-lens 的结构规则与安全规则，**只读、不改写**） +- 各包的测试套件（`npm test`、`go test ./...`、`node --test`） + +## 相关 + +- `biome.jsonc`：只挡得住 biome，**挡不住 prettier** —— 两者是并列的候选格式化器， + 各有各的配置。所以真正的开关是 `.pi-lens.json`，它两条改写路径一起关。 diff --git a/scripts/verify-l2.sh b/scripts/verify-l2.sh index 5898466..cebcbbc 100644 --- a/scripts/verify-l2.sh +++ b/scripts/verify-l2.sh @@ -1,7 +1,20 @@ #!/usr/bin/env bash # L2 端到端验证脚本 set -euo pipefail -TOKEN="98c118601275607be1f244f0f9c40c838b7f0d74d0ce23c04eeda00db99eb95e" +# 管理员 user key。**不要把它写进这个文件** —— 仓库是会被看到的地方， +# 而写进 git 历史的密钥只能靠轮换作废（删掉当前行不能把它从历史里拿掉）。 +# +# 取法（任一）： +# VERIFY_L2_TOKEN= bash scripts/verify-l2.sh +# echo > /root/gotmp/verify-l2-token.txt && chmod 600 该文件 +TOKEN="${VERIFY_L2_TOKEN:-}" +if [ -z "$TOKEN" ] && [ -r /root/gotmp/verify-l2-token.txt ]; then + TOKEN=$(tr -d '\n' < /root/gotmp/verify-l2-token.txt) +fi +if [ -z "$TOKEN" ]; then + echo "需要管理员 user key：设 VERIFY_L2_TOKEN，或写到 /root/gotmp/verify-l2-token.txt（600）" >&2 + exit 2 +fi BASE="http://127.0.0.1:8180/api/v1" H=(-H "Authorization: Bearer $TOKEN") PASS=0 FAIL=0