# 开发工具配置：为什么关掉 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`，它两条改写路径一起关。 ## 部署残留清理（`deploy/prune-deploy-artifacts.sh`） 部署会留下两类持续增长的东西：网关旧二进制（每份 ~24MB）与插件快照（opencode/dsh 的 快照含 node_modules，一份几十 MB）。2026-09-14 实测 `/opt/agentmail` 累计到 **1.3GB**， 其中旧二进制 ~790MB、快照 ~540MB。 ```bash bash deploy/prune-deploy-artifacts.sh # 干跑，只报告 bash deploy/prune-deploy-artifacts.sh --apply # 真删（默认：网关留 3 份、每插件留 3 份快照） ``` 两条硬规矩：**保留回滚窗口**（发布纪律要求有回滚目标，所以不是全清）；**绝不删正在使用的 快照**（扫 /proc 的 cmdline 与 cwd，命中就跳过 —— 删掉它进程一重启就找不到自己的代码）。 注意那个"在用"判断必须排除**本进程及其祖先链**：调用方常把路径写在命令行里， 不排除就会出现"永远判为在用"（与 `pkill -f` 杀掉自己那条命令同一个坑，已写进脚本注释）。