jianf/MailUI4Agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(tooling): pi-lens 的项目防护其实一直没生效（JSON 里带注释 → 整份被忽略）

Browse Source 
## 现场

跑 `pi --help` 时有一行不起眼的警告：

    [pi-lens] ignoring invalid project config …/.pi-lens.json:
    Expected double-quoted property name in JSON at position 60

`.pi-lens.json` 是 `d50c55d` 专门加的项目级防护（关掉 pi-lens 的格式化与
autofix），但它的说明写成了 `//` 注释 —— 读 pi-lens 的源码确认：

    PROJECT_CONFIG_BASENAMES = ['.pi-lens.json', 'pi-lens.json'];  // 没有 .jsonc
    raw = JSON.parse(text);                                        // 不去注释
    // 解析失败 → 打一行警告，然后**整份忽略**

所以「已经关掉了」这个结论是**错的**，防护从落地那天起就没生效过。
而它要防的是两次已发生的真实损失：一次是 `19a3161` 把约 7000 行 biome 重排
扫进功能提交（无法审查、还掩盖了一处删行），一次是 prettier 改坏
`client/electron/index.html` 并打破 `test/theme.test.mjs` 的两条断言。

失败方式是静默的：进程照常跑，只有启动时一行警告 —— 而我正是在
`pi --help` 的输出里才看见它。

## 修

- `.pi-lens.json` 改为**严格 JSON**（只有 `$schema` / `format` / `autofix`；
  `$comment` 也不行 —— pi-lens 校验未知键，会为它刷一条
  「unknown key … ignored」的警告，而噪声会训练人忽略告警）。
- 理由移到 `docs/DEV-TOOLING.md`（含 pi-lens 的源码依据、两次事故、
  以及「为什么不是把格式化器配成本仓库风格」——试过，仍改 17 个文件）。
- `biome.jsonc`（允许注释）里加指针：它只是两道闸中的一道，真正的总开关是
  `.pi-lens.json`，而那份**必须是严格 JSON**。
- 验证：`pi --help` 现在 **0 行** pi-lens 输出；反向对照（故意塞回一行注释）
  会重新出现 `ignoring invalid project config`。

## 顺带：仓库里有一个活的凭据

`scripts/verify-l2.sh` 把**管理员 user key 硬编码**在文件里（`1759666` 起就在
git 历史里）。实测它**仍然有效**（`/auth/me` → 200），属于用户 `jianf`。

- 已改为从 `VERIFY_L2_TOKEN` 或 `/root/gotmp/verify-l2-token.txt`（600）读取，
  两者都没有时**报错退出**（反向对照验过：EXIT=2，不静默跑）；
- 跑通一次确认可用（6 通过 0 失败）。

**但删掉当前这行不能把它从历史里拿掉** —— 要真正作废必须轮换那把 key。
这需要你定（它是你账号的密钥，可能还有别的工具在用），见提交后的说明。
This commit is contained in:
JianFeeeee
2026-09-12 23:49:55 +08:00
parent 2e28696e74
commit 33e44074e7
4 changed files with 88 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
.pi-lens.json
View File

@ -1,36 +1,8 @@
{ {
"$schema": "https://pi-lens.dev/schema/project.json", "$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 默认双引号、
// 还会把 <!DOCTYPE html> 改成小写、按 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": { "format": {
"enabled": false "enabled": false
}, },
// autofix 同理：它会在与本次改动无关的行上做自动修复。
"autofix": { "autofix": {
"enabled": false "enabled": false
} }

5
biome.jsonc
View File

@ -1,4 +1,9 @@
{ {
// ⚠️ 本文件只是**两道闸中的一道**：biome 挡得住 biome，挡不住 prettier。
// 真正的总开关是根目录的 `.pi-lens.json`（两条改写路径一起关），
// 而它**必须是严格 JSON** —— 带 // 注释会被 pi-lens 整份忽略、防护静默失效。
// 完整来龙去脉见 docs/DEV-TOOLING.md。
//
// 本仓库**不使用** biome 的格式化器，只借它做诊断（且由 pi-lens 统一调度）。 // 本仓库**不使用** biome 的格式化器，只借它做诊断（且由 pi-lens 统一调度）。
// //
// # 为什么显式关闭 // # 为什么显式关闭

69
docs/DEV-TOOLING.md Normal file
View File

@ -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（双引号、`<!DOCTYPE html>` 变小写、按 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`，它两条改写路径一起关。

15
scripts/verify-l2.sh
View File

@ -1,7 +1,20 @@
#!/usr/bin/env bash #!/usr/bin/env bash
# L2 端到端验证脚本 # L2 端到端验证脚本
set -euo pipefail set -euo pipefail
TOKEN="98c118601275607be1f244f0f9c40c838b7f0d74d0ce23c04eeda00db99eb95e" # 管理员 user key。**不要把它写进这个文件** —— 仓库是会被看到的地方，
# 而写进 git 历史的密钥只能靠轮换作废（删掉当前行不能把它从历史里拿掉）。
#
# 取法（任一）：
# VERIFY_L2_TOKEN=<key> bash scripts/verify-l2.sh
# echo <key> > /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" BASE="http://127.0.0.1:8180/api/v1"
H=(-H "Authorization: Bearer $TOKEN") H=(-H "Authorization: Bearer $TOKEN")
PASS=0 FAIL=0 PASS=0 FAIL=0