Genarrative/docs/technical/ENCODING_CHECK_TRANSIENT_WORKSPACE_FIX_2026-04-22.md

编码检查与临时工作区噪音收口方案（2026-04-22）

日期：2026-04-22

1. 背景

当前仓库根目录存在多份本地临时工作区与 Cargo cache 目录，例如：

1. .codex-cargo-home-stage4*
2. server-rs-codex-stage4-*
3. server-rs/target-*

这些目录属于本地验证产物，不属于主工程源码、文档或正式资源，但 npm run check:encoding 仍会通过 git ls-files --cached --others --exclude-standard 把其中大量未跟踪文本文件纳入扫描，导致：

1. 编码检查耗时被临时目录放大
2. 检查结果容易被本地 cache / verify copy 噪音污染
3. 仓库级 UTF-8 检查无法稳定反映真实工程文件状态

同时，当前脚本没有把 .rs 纳入文本扩展名集合，这与仓库约束“Rust / 工程代码中的中文注释也必须保证 UTF-8 正常”不一致。

2. 本次冻结规则

本轮对编码检查口径做以下冻结：

1. scripts/check-encoding.mjs 只检查主工程真实文本文件，不扫描临时 Cargo cache、临时 verify copy 和 server-rs/target-* 目录。
2. .rs 必须纳入 UTF-8 编码检查，避免 Rust 文件中的中文注释或中文错误文案被写坏后漏检。
3. .encoding-check-ignore 继续只承载少量已知历史坏文本白名单，不用于掩盖大目录级临时产物。
4. 对临时目录的处理优先通过 .gitignore 与脚本排除规则完成，不要求物理删除本地 cache。

3. 具体落地点

3.1 .gitignore

新增忽略规则：

1. /.codex-cargo-home-*/
2. /server-rs-codex-*/
3. /server-rs/target-*/

目的：

1. 让 git ls-files --others --exclude-standard 不再把这些临时目录当作待检查仓库文件。
2. 与既有噪音清理基线保持一致，继续把本地检查产物留在仓库视野之外。

3.2 scripts/check-encoding.mjs

脚本同步收紧两点：

1. 增加对上述临时前缀目录的显式排除，避免脚本在显式传参或忽略规则未生效时仍误扫临时目录。
2. 把 .rs 加入文本扩展名集合，确保 Rust 源文件进入 UTF-8 校验面。

4. 完成定义

当以下条件满足时，本次修复视为完成：

1. npm run check:encoding 不再被临时 Cargo / verify 目录拖慢或污染结果。
2. 真实工程中的 Rust 文件会参与 UTF-8 检查。
3. 不需要清理用户本地 cache 目录，也不会对现有并行工作区造成破坏。

5. 不在本轮范围

本轮不处理：

1. .encoding-check-ignore 中历史坏文本的逐条修复
2. 各类本地 cache / verify 目录的物理删除
3. 与 UTF-8 检查无关的 lint / typecheck / cargo 输出目录清理策略

6. 相关文档

1. ./REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md