Skip to content

Commit 0bbe1fa

Browse files
committed
fix(docs): 复审两处 Minor 与断链隐患
受限复审 ALL_ADDRESSED 后的 2 条 Minor + 1 条自查发现: - refactoring.md 指代错位:0-C2/0-C3 的 5+10=15 是 >600 文件,此前挂在了 「300-600 行登记豁免清单」之后,读者会误读;已把两件事分开写清 - v0.22 的 tech-debt 链接改为纯代码路径:docs/tech-debt/ 整目录 0 tracked, 写成链接会让新克隆断链、docs-check 在别人机器上变红,而本机因文件存在而绿 - AGENTS.md 补更强的警示证据:SessionListPanel.tsx 604->577,即 >600 硬限违规 也能被 Get-Content 读成合规
1 parent 8222e7f commit 0bbe1fa

3 files changed

Lines changed: 4 additions & 3 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@
3939

4040
1. **模块化**:单文件 ≤300 行(>600 行必须硬拆;300-600 行登记豁免清单);纯逻辑与副作用物理分离;显式依赖注入。
4141
**行数口径(唯一有效)**:文件**全部行数**(含空行),以 `[System.IO.File]::ReadAllLines(path, UTF8).Count` 为准 —— 即 `scripts/line-limits.mjs` 的 `countLines()`。
42-
⚠️ **不要用**:`Get-Content`(本机 PowerShell 5.1 + 码页 `gb2312` 会按 GBK 解码、吞换行、**少算可达 56 行** —— 实测最大 `live_session_pause.rs` 353→297,**足以把越 300 红线的文件读成达标**)· `Measure-Object -Line`(**只数非空行**)· **字节 `0x0A` 计数**(对**末尾不带换行**的文件会少算 1;本仓实测有 8 个这样的源文件,含 `NotesPage.tsx`)。
42+
⚠️ **不要用**:`Get-Content`(本机 PowerShell 5.1 + 码页 `gb2312` 会按 GBK 解码、吞换行、**少算可达 56 行** —— 实测最大 `live_session_pause.rs` 353→297;**连硬限违规都能被读成合规**:`SessionListPanel.tsx` 604→577,>600 读成 ≤600)· `Measure-Object -Line`(**只数非空行**)· **字节 `0x0A` 计数**(对**末尾不带换行**的文件会少算 1;本仓实测有 8 个这样的源文件,含 `NotesPage.tsx`)。
4343
判定一律以 `node scripts/line-limits.mjs` 为准。
4444
2. **强类型契约**:业务术语贯穿全栈;禁止 `any`/无类型;入参出参必须定义类型(TS interface / Rust struct)。
4545
3. **上下文注释**:注释解释 Why 不解释 What;公共函数/模块必须含 `@ai-context` 业务背景注释;标注副作用与边界条件;Magic Number/Hack 必须说明原因。

‎docs/standards/refactoring.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -159,6 +159,6 @@
159159

160160
本文档的通用重构手法在本项目受以下硬性约束(详见 [ai-coding.md](./ai-coding.md) 第二部分):
161161

162-
- **§1 单文件 ≤300 行**:"过大类/文件"坏味道在本项目有明确阈值——>600 行必须硬拆;300-600 行登记豁免清单**待专项重构**(该项已排为批 0 的 `0-C2` 前端 5 个 / `0-C3` Rust 10 个拆分)。行数口径见 AGENTS.md §3.1(全部行数,以 `node scripts/line-limits.mjs` 为准)
162+
- **§1 单文件 ≤300 行**:"过大类/文件"坏味道在本项目有明确阈值——>600 行必须硬拆;300-600 行登记豁免清单**待专项重构**(该清单由批 0 的 `0-C1` 重建为快照表;注意与拆分任务区分:`0-C2` 前端 5 个 / `0-C3` Rust 10 个拆的是 **>600** 那 15 个文件,不是 300-600 清单)。行数口径见 AGENTS.md §3.1(全部行数,以 `node scripts/line-limits.mjs` 为准)
163163
- **§6 自底向上重构顺序**:拆分遵循 原子层(纯函数/类型)→ 业务层(hook/service)→ 系统层(页面/装配);公共 API 保持零改动(兼容 re-export)
164164
- **已验证拆分模式**:React 页面 → 纯展示组件 + 域 hook + 组合层;Python 巨型模块 → 包化 + Mixin + schemas 提取;Go 巨型 handler → 同包多文件职责拆分

‎docs/versions/v0.22.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,8 @@
113113

114114
本机 harness 的 `pwsh` 实为 **Windows PowerShell 5.1**(ANSI 码页 `gb2312`),`Get-Content` 会按 GBK 解码 UTF-8 文件并**吞掉换行、把行数少算**(实测:`index.ts` 19→12、`paths.test.ts` 130→112、`NoteListView.tsx` 654→609;**全量 868 文件实测最大少算 56 行**:`live_session_pause.rs` 353→297 —— **足以把越 300 红线的文件读成达标**)。
115115
⇒ **AGENTS.md §3 的「≤300 / >600」以 `[System.IO.File]::ReadAllLines(path, UTF8).Count` 为唯一口径**(即 `node scripts/line-limits.mjs`);禁用 `Get-Content`、`Measure-Object -Line`(只数非空行)与**字节 `0x0A` 计数**(对末尾无换行的文件会少算 1,本仓实测 8 个这样的源文件)。该失真已造成一次真实险情(据此误判 `IconName` 未导出)。
116-
治理侧(口径未定义、15 个 >600 硬限违规、豁免表数值过期)见 [tech-debt/review-2026-09-11.md](../tech-debt/review-2026-09-11.md);工具侧见批 0-B 台账。
116+
治理侧(口径未定义、15 个 >600 硬限违规、豁免表数值过期)见 `docs/tech-debt/review-2026-09-11.md`;工具侧见批 0-B 台账。
117+
> ⚠️ 上句**故意不写成 Markdown 链接**:该文件目前**未入 git**(`docs/tech-debt/` 整个目录 0 tracked)。写成链接会让**新克隆断链**、并让 `docs-check` 在别人机器上变红 —— 而在本机因文件存在而通过(这类"本地绿、别处红"的掩盖正是本批要消灭的缺陷类)。该文件入库后可改回链接。
117118
118119
**陷阱 2 · 退出码 —— `2>&1 | …` 会把成功的原生命令报成失败**
119120

0 commit comments

Comments
 (0)