# AGENTS.md — IHUI-AI 项目 Agent 指南 > 作用域:`D:/IHUI-AI` 仓库根目录及所有子目录（2026-09-12 修正:仓库早已从 `G:` 迁到 `D:`，旧盘符路径已全部改为从脚本自身位置推导）。 > 历史案例归档见 `.ihui-agent/archive/AGENTS_history.md`。 > 本文件为精简版(2026-07-25 重构,原 783 行 → ≤400 行),保留所有强制规则核心条款。 --- ## 1. 任务计划文档规则(强制) - 项目**唯一**任务计划文档是 `PROJECT_PLAN.md`(根目录),所有任务计划、进度更新、待办清单、状态变更**只写**此文件,**不得**在 `.ihui-agent/`、`docs/`、根目录或其他位置新建计划/TODO/ROADMAP 文件。 - 完成任务后 `[ ]` → `[x] ✅(日期)`;新增任务追加到对应优先级(P0/P1/P2)末尾。commit message:`feat`/`fix`/`docs`/`chore`/`test`/`refactor` 前缀。 - **任务认领(2026-09-23 立)**:agent 开始任务前,在对应 `- [ ]` 后追加 `（进行中）` 标记(全角括号),例 `- [ ]（进行中）O20d 守门...`;完成后按上条改 `[x] ✅(日期)` 并删除 `（进行中）`。扫描 `PROJECT_PLAN.md` 可区分三态:无人认领(`- [ ]` 无标记)/ 进行中(`- [ ]（进行中）`)/ 已完成(`- [x]`)。派单前先扫进行中项,避免重复认领。扫描工具:`node scripts/check-task-claims.mjs`。 - **任务状态一致性(2026-09-26 立,守门 130 配套)**:计划文档被当台账用而**没有主键约束**,这是"完成的为什么还在这里、还有重复"的唯一根因 —— §1 上一条让每个 agent 追加登记,同一任务编号被不同批次各写一份,做完只翻自己那一批那份,其余副本永久烂成"未勾选";而既有防护链(门 71 防丢行 / 84 防写回旧版 / 100 防合并吞文件 / 工作区自愈)**全部单向防丢,没有一道判"状态分叉"**,并集合并当时又是"每行重数取 max",所以改写必然产出两份 —— **该口径已于 2026-09-29 由 G-814386 收窄**:带「重复登记副本」指针的行只许"从无到有带一份",不参与份数累加(同主键而正文已漂开的仍交人工);现行实现与四条落地断言见本节末「合并吞并的修复出口」条。三条规矩: 1. **派单口径只认一个入口**:`node scripts/plan-tasks.mjs --open`(未勾选 − 同题已完成副本 − 自带作废声明的行 − 同一件事的第二条待办副本;四条判据 F1/F2/F3/F4 都以"编号 + 标题前缀逐字等值"的复合主键为准,不依赖行号顺序也不依赖相似度)。`grep '^- \[ \]'` 不是待办清单(2026-09-26 一次实测的**不重叠**分解:未勾选 205 = 已认领 44 + 其余排除 28 + 真待办 133;同刻 F1/F2/F3/F4 读数均为 0 —— **这些数是当次现读,派单前必须重跑,勿照抄**;报告里其余排除项的明细计数彼此可重叠,只能当诊断看,不能拿来减法核账)。归并出口:`node scripts/plan-tasks-merge.mjs --heal --commit`(F1/F2 翻勾并写明归并到谁;**F4 只加"重复登记副本"指针、绝不动勾选** —— 两条都是没做完的事,把没做的记成做过的比原病更响)。 2. **一个编号只能有一行"当前状态"**:新登记同一件事时必须把旧行翻勾或就地改写,不得在别处再抄一份。判据是复合主键(编号 + 标题前缀**逐字**等值),不是相似度 —— 相似度只能报数,不配判红。 3. **证据指针禁止写行号**:行号在任何一次 append 后都会挪位。实测 HEAD 面 27 处 `存活于 L<行号>` 式指针**复核通过率 0/27**(目标行已不是条目行)——上一轮登记"已识别、只标注未翻勾"的那批账,今天已无法按它自己给的证据复核。必须用内容锚点(编号 + 标题原文)。 - **行首裸编号是本仓登记行的默认形态,必须算主键(2026-09-27 O87 续,`scripts/lib/plan-task-index.mjs`)**:`TASK_ID_PATTERN`(门 71 导出的编号族)只认 `G-/D/O/B/P/W/V3/守门`,而 `titleOf` 又在正文第一个 `.` 处截断 ⇒ `- [ ]75. file_search…`、`- [ ] **86A. 证据流水…**` 这类行的复合主键恒为 null,**F1/F4/归并器对整族结构失明** —— 后果实测:75/51/62 三票的实现与常驻尺子都在 HEAD 且 RC=0,台账仍报未勾选,于是被再派一次。**判据(照抄别重新发明)**:① 编号必须落在剥掉复选框与状态装饰后的**正文开头**,② ≤3 位、可带**单个大写字母后缀**,③ `.`/`、` 之后第一个非空字符不得是数字(否则 `**12.3 万**` 这类量值开头会成百地冒成"第二次登记")。**两条同源缺陷各由一条测试钉住**:M14 钉族缺失本身;M15 钉"**放宽编号判据时,标题跳过必须走同一个出口**" —— 我第一版在 `titleOf` 里另抄了一份窄正则(不认 `**` 与字母后缀),结果标题仍被 cut 在编号后面那个 `.` 上、只剩 `"86A"`(3 字 <4)⇒ composite 仍 null,**刚修判据的那一族上自己失明**;变异取证:把 `stripLeadingNumeric` 退回窄版 ⇒ M14+M15 同时翻红(`pass 14 / fail 2`),逐字还原(`cmp`)后 16/16 绿。**这一族的"行首"判据与门 71 的"登记行"判据是两件事**:门 71 的防丢面仍按裸族认登记行,所以整块回写这类形态目前只有台账层(F1/F4)看得见,门 71 那一面要不要同步扩,归该门持有人决定,不得由本层顺手改。 - 问责:`pnpm check:plan-task-state`(`--strict`,存量判红);提交链上跑的是**差值棘轮**(只拦"这次提交让分叉变多",存量永不拦 —— 与改动无关的恒红门只会逼人 `--no-verify`,连带废掉全部守门,§12e 同型)。修法只有**归并**(副本翻勾并注记归并到谁),§1 的"禁止无声删除"对已完成行仍然成立。 - **新登记必须有交代(2026-09-27 立,G-254 / 守门 130 新增 F7+F8 两维)**:一条 `- [ ]` 只有满足三者之一才算"交代得清"——① 带租约 `（进行中@日期/持有者）`;② 正文写明它在等什么(归属四态:等人拍板 / 等环境条件 / 归他人持有者);③ 有新鲜锚点(行内日期或进展日期)。**三样都没有 = 无交代**,提交链按**差值棘轮**只拦"本次带进来的无交代行"(`git show <新提交>^..<新提交>` 与当下基准面逐行比对,存量不算在本次头上),因为与提交内容无关的恒红门唯一结局是逼人 `--no-verify` 连带废掉全部守门(§12e)。**登记一件活时顺手写下它为什么还开着,是这本账不再无限膨胀的唯一止血点** —— 现读:未勾选 313 行里 128 行无交代,而真待办只有 203 行,"越做越多"涨的是账不是活。 - **寿命这一维不进提交链**:`node scripts/plan-tasks.mjs --stale`(或 `--strict`)才点名"超 21 天无进展"。行龄取 `git blame` 的作者时刻与行内日期的**较新者**(`scripts/lib/plan-line-age.mjs`,覆盖面由 `parseTaskRows` 一份判据闭合 ⇒ 量不到的行必须为 0,否则喊"未判定"),所以**不需要也不许**给人工回填"追溯出生日":回填等于替每行伪造一个新鲜时刻,寿命判据当场被架空。到期处置只有两条 —— 续进展(改日期)或写清它在等什么;**门绝不替你勾掉任何一行**。 - **派单先看可派单口径**:`node scripts/plan-tasks.mjs --open --dispatchable`(= 未认领 ∧ 不是同题副本 ∧ 现在可做)。默认 `--open` 仍是全部无人认领行(向后兼容,不改变既有派单语义);两者差集就是"挂着但今天做不了"的账。数字一律现读,勿照本节点名。 ### 归档机制 - 已完成任务条目(`### XXX(已完成 ✅ ...)` 标题)**禁止直接删除**,必须两步走:① 把完整任务条目(标题 + 正文)移动到 `.ihui-agent/archive/PROJECT_PLAN_YYYY-MM-DD.md`;② 在 `PROJECT_PLAN.md` 原位置留 HTML 注释占位:``。 - **自动归档**:`scripts/archive-completed-tasks.mjs` 扫描**已完成**条目(默认阈值 0 = 完成即归档;`--days N` 是降速档,不是默认),post-commit 钩子自动 `--auto-commit`。归档 commit 设 `IHUI_ARCHIVE_COMMIT=1` 防递归。 - **排空步骤已在提交链上(2026-09-28 接)**:`.husky/post-commit` 在调归档器**之前**先跑 `node scripts/ledger-strip-open-rows.mjs --apply`。理由:"标题写着已完成、体内还裹着未勾选登记"的块是归档器**结构上不许搬**的那一类(搬走等于把别人正开着的活账归档),没有这一步,"完成即归档"只对干净块成立,而实测大部分块都不干净(台账是几百次并发登记写出来的)。三条安全前提写在这里,下一个人不必重新猜:① 该脚本走**对象空间**(`commit-tree` + CAS),而 `commit-tree` **不跑钩子** ⇒ 结构上不会自触发递归,与归档器同一形态;② 它自带五条零损失不变量(行数不变 ∧ 消失 0 ∧ 非空行净新增只可能是区头 ∧ 被拒块归零 ∧ 勾选两态不缩水),任一不成立就**整批不落**并 exit 非零,所以"钩子跑了"不等于"台账被改了";③ 它**排在归档器前面**,同一轮里排空完就能搬。应急开关 `HUSKY_SKIP_LEDGER_STRIP=1` 只关这一步,不影响归档(两级开关刻意分开;`HUSKY_SKIP_ARCHIVE=1` 关的是整块,含本步)。 - **标题形态三处必须同形**(2026-09-25 G-182 实证):本节写的 `### XXX(已完成 ✅ ...)`、守门 13c 的提取式、归档器 `parseCompletedTasks()` 的匹配式,**任一处漂了另外两处不会响**。归档器曾按 `/^### \[x\]/` 找标题,而文件里 `^### [x]` 命中 0 次 ⇒ 连续 11 天每次跑都扫到 0 条、post-commit 静默无操作。现判据:含 `✅` 即算已完成条目,日期取标题里第一个 `YYYY-MM-DD`(真实形态日期常在 ✅ 之前);**无 `✅` 的小节标题(如 `### 已完成清单`)不算条目** ⇒ 归档器的搬运集必须是 13c 保护集的**真子集**,否则一边搬一边护就是互咬。 - **大批量阀门只挡自动档,但"全批或不动"是错的默认**(2026-09-28 改):旧写法在积压 >25 条或 >256 KB 时整批拒绝,于是超阈值之后**每次自动档重算同一批再拒绝** —— 实测 HEAD 面积压 3 条 / 592,001 B,归档机制对存量结构性失效而账面一路绿(参照 §5c 水印门"单次缺口 >200 拒绝自动回写"同一条设计,但那条阀只能对**一次动作**生效,不能当常态)。现 `selectWithinBudget` 按**最旧优先贪心取前缀**(单批仍不超 500 段 / 256 KB —— 段数上限只是"格式又漂了一次"的哨兵,真正把关的是字节,余量点名并报数、下一轮继续),只有"最旧一条自身就超预算"才回到拒绝路径且不拆条目搬(2026-09-28 同日把段数上限从 25 提到 500:bullet 级纳入后一段常常只有一行,25 段/轮只搬得动 100 KB,卡的不再是它想防的"半本活文档被重写");退出码仍 0(自动档少做一件事不是错误,不得把钩子链弄红),`--allow-mass` 只放宽字节预算这一件事。 - **归档粒度自 2026-09-28 起含 bullet 级 `- [x]`**:此前只认 `##`/`###` 带 `✅` 的条目标题,而台账里绝大多数完成状态写在 bullet 级(HEAD 面实测 2106 处),旧输出那句"不在 §1 条目粒度内,不搬也不护"就是计划文档只增不减(实测 4.9 MB)的唯一成因。`collectCompletedBullets` 把**连续**已完成登记并成一段(含缩进续行),**块内一遇任何 `- [ ]` 当场断开**,无日期不搬(不给没出生证明的行造生日);搬运仍走同一条结构等值自证 + 零损失闸 + 对象空间落地,别人在飞的磁盘副本逐字不动。`--no-bullets` 只作人工取证出口,不得当常态。 - **占位必须带上随块搬走的"归并落账注记"(`〔【归并】…落账:复测 日期〕`)**(2026-09-28 立):台账门 130 的 F5 存续性棘轮数的就是这批注记,而它们原本挂在 `- [x]` 行上 —— bullet 级纳入归档后,行一进归档,计划文档面上的计数直接掉到 0,门按"整文件写回旧版"那一型喊红。它分不清"随块归档"与"被抹掉",而**这是归档器造成的形态,不该靠放宽门解决**(§12e:修红不得顺手削判据)。故占位新增字段「随块带走的归并落账注记: …」,注记正则取自台账 lib 的 `MERGE_NOTE_RE` 那一份实现;字段插在「完整内容在 …」之**前**,使 13c 反查文件名的"最后一个逗号段"形态一字不变,且无注记时占位与旧形态**逐字相同**(成对自检 S17b/S17c)。 - **"标题写已完成、体内还有未勾"的假条目一律不搬,且 `--allow-mass` 绕不过**(守卫 `entryHasOpenRows`,与体积阀**正交**):立项当天抓到一条 —— `## P1 侧边栏底部 5 工具按钮…立并完成 ✅` 之后再无同级标题,整块一路吞到文件末尾 = 771 行 / 575,577 B、块内 `- [ ]` 237 条。旧阀按字节拒绝**纯属巧合救场**,而它给用户的出路正是 `--allow-mass`,谁按提示跑就把 237 件活账归档、派单口径静默少行。拒绝必须大声点名(标题、块大小、体内未勾数)。取证:归档器 `--self-test` 30 条(S12x 采集器正反例 / S13x 守卫含逐字取自真仓的真实形态 / S14x 贪心三态)+ 镜像 35 例(G:子弹真被搬走而同章 `- [ ]` 一字未动;H:连 `--allow-mass` 也搬不走假条目)。真仓首批现读:搬 12 段 / 69.8 KB / 76 条已勾行,未勾选 557 → 557,文档 4,926,467 → 4,857,252 B,门 71 与 13c 在新 HEAD 上 RC=0。 - **归档锚点必须受版本控制**(2026-09-25 G-183):`.gitignore` 对 `.ihui-agent/` 的处理是"忽略其内容 + `!.ihui-agent/archive/` 例外",**不得改回整目录忽略** —— §1 的"完整内容在 `.ihui-agent/archive/PROJECT_PLAN_*.md`"和守门 71 的"archive 里找得到 ⇒ 不算丢"都以它为事实基础。旧状态(整目录忽略)下:历史那次 `b599edbba` 归档 11 条的 commit **只含 PROJECT_PLAN.md 一个路径**,即副本从未入库,而"A 机归档过"可以授权"B 机删行"。守门 71 曾仍读磁盘副本 ⇒ 尚未入库的本机归档文件可以授权另一次提交删行,**该洞已于 2026-09-25 由 G-184 关闭**:`archivedCopy()` 的归档清单与内容现在**同面**取(`--staged` 走 `git ls-files` 索引、全量走 `git ls-tree HEAD`),面里没有的路径不构成删行凭据;`runCheck` 必须把当次判定面喂给豁免(`archiveExemptFor(isStaged)`)。取证:自测四条组合 + 镜像端到端 **A/B**(同一份归档正文、同样删掉 `## O42`,唯一差别是一次 `git add`:未入库侧必 exit 1、已入库侧必 exit 0),外加一条反向回归锁(函数体内不得再出现 `readdirSync(` / `readFileSync(`,对 HEAD 旧版该锁 5 条断言全红)。**G-183 当时登记的"被门 118 结构性棘轮挡住"这个前提实测已不成立** —— 并行会话已把门 71 的内容面迁到 `scripts/lib/face-reader.mjs`,门 118 见 face-reader 导入即判合规,所以这里不存在"必须先整道迁移"的阻塞;登记这条是为了说明**沿用旧理由会挡住一件已经可以直接做的事**。 - **归档 commit 必须带 pathspec**(2026-09-25 与上面同批修):旧实现第二步是 `execSync('git commit --no-verify -m "…"')` —— 不带路径 = 把当下共享索引里的东西全提交,而并发会话随时在索引里挂着 staged 内容,于是那枚"归档 commit"会把别人的在途改动打包带走(§12 污染型;它跑在 post-commit 里,没人盯着)。**它一直没炸,只因为匹配式漂了、这段代码从没真跑到过 ⇒ "让工具能用"和"修它的提交面"必须是同一条提交,否则修好匹配式的那一刻就是引爆那一刻。**现形:`execFileSync(GIT_BIN, […, 'commit', '--no-verify', '-m', msg, '--', <计划文档>, <归档文件>])`。A/B 实证:旧版在"计划文档 + 一个被 `git rm --cached` staged 的他人文件"场景下产出的 commit **确实含别人的文件**;新版只含声明的两路径(测试第 20 例钉成回归)。 - **归档占位点名的文件必须真在审面里(守门 13c 的 A1/A2/A3,2026-09-25 立)**:`` 是一句**可核验的指针**,不是修辞。A1 = 盘上有 `PROJECT_PLAN_*.md` 而审面(全量 HEAD 树 / `--staged` 索引)没有 ⇒ 红;A2 = 占位点名的具体文件不在审面里 ⇒ 红(写成 `PROJECT_PLAN_*.md` 通配的占位不点名,不参与判定)。**A3(同日 G-192)= 同一把尺子伸进归档件内部** —— 元归档层(归档文件正文里再写"完整内容在 archive/<另一个>")过去完全无人看守,实测 `2026-09-12` 那份里嵌着 **218 条**占位、点名 13 个文件,其中 12 个从未入库。A3 与 A2 共用"缺失⇒红 / 已登记⇒只报数 / 已入库仍挂台账⇒判清单腐烂"三段规矩,标签不串门,同一名字被 A2 与 A3 点到只计一次债;blob 取不到那一层 ⇒ 结论行喊"未判定",不静默通过。立项即抓到两条实测:`PROJECT_PLAN_dedup-2026-09-23.md` 只躺在本机(已随本票入库),以及 **8 个被 52 条占位点名的归档文件在仓库与本机两侧都不存在、其路径也从未出现在历史里** —— 即 §1 那句承诺对这批条目一直是空的。这 8 项进 `LOST_ANCHOR_LEDGER` **只报数**:它们是已发生的债,当场判红就是一台与任何提交都无关的恒红门(§12e 同型);台账是**待偿清单不是豁免清单** —— 修好了仍挂着 ⇒ 判"清单腐烂"红,删了行却没修好 ⇒ 照常红,两个方向各有一条自检钉死。按条目从计划文档历史版本逐字找回另计一票。 - **台账已第一次真清偿(2026-09-25 G-191,8 项减到 4 项)**:找回的办法是**从 git 历史逐字取回,不是重写历史**。每批归档都由"把正文从计划文档搬走"的那枚提交产生,所以那枚提交**删掉的内容块**就是归档正文;落地判据只有一条 —— 该正文逐字存在于所引提交的父版本 `PROJECT_PLAN.md`,不成立就不落地(实测有 2 条 `2026-07-26` 的占位是在 `3a5b737bf8` 里**凭空新增**的纯 `+` 行,按裸标题 `git log -S` 证明那两个条目从未存在过 ⇒ 从别的提交"补"出来就是编造,已确认为找不回,不当干)。落地 4 份 / **28 块 / 567 行实质正文、0 行无出处**,取证用两把**互相独立**的尺子(逐块对应 23/23 + 格式无关的全量行级比对 567/567 —— 后者专门防"重建脚本自己给自己发合格证")。每份文件里保留逐条 `recovered from ` 注释 + 一句"这是找回件,不是当时原写"的性质说明:**不写进文件,后来人就会把重建文本当一手记录。** **取出处时必绕过一个坑**:`b129e09482` 做过一次 `.trae-cn/archive/` → `.ihui-agent/archive/` 的**占位文本搬家**(它不删除任何内容),按"最旧一次 `-S` 命中"取出处会选中搬家那枚而非真正的删除,必须沿搬家链回走。 - **递归那一格已做完(2026-09-25 G-192),并把看守面扩到归档层自身**:上面"218 条嵌在元归档里的占位"共点名 **13 个**文件,三类处置 —— ① **4 个真存在过**(躺在 `.trae-cn/archive/` 下,搬家时漏带),按 `git cat-file blob <出处>^:.trae-cn/archive/<名>` **原字节**落盘,判据两把:注入水印**之前** `git hash-object` 与出处 blob **同 SHA**,注入**之后**正文仍须逐行全等(合计 2,210 行 / 170,608 B);② **8 个从未作为文件存在过**(`git log --all -- <任意前缀>/<名>` 对 8 个名字全部 0 命中)⇒ 占位被写过、文件没被写过,结构上找不回,进台账只报数;③ 1 个由 G-191 已入库。**为什么必须两把尺子**:找回脚本自己写的是"剥水印→逐行全等",它剥窄或剥宽都会让自己的断言跟着错(§22c"镜像测试只复读实现就是复读机"同型),所以独立复核换成异形判据 —— "blob 每一行必须在落地文件里**同序、连续、逐字**出现",水印层天然落在窗口之外。过程中真抓到一次不等:出处带 **UTF-8 BOM** 而 `watermark.mjs inject` 重写时会去掉 ⇒ 容差只开在 BOM 这一处(字节同值已由注入前的 SHA 判据证明),并写进文件里的出处注释,不让它读成"逐字节永远同值"。**A3 是本格的真正产出**:归档件**内部**的占位同样点名,A1/A2 过去只扫计划文档,这一层零看守。台账 4→12 项(**全部只报数**,所以扩 A3 不产生新恒红面)。 - **13c 自身的取材口径(同日迁移)**:此前 `ROOT = process.cwd()` + 裸 `git show` 用 `execSync` 拼字符串(无 timeout)+ 占位合规性看 `git diff` 文本,三处都与本仓现行口径相反(工作树滞后即换结论 / 服务账户 PATH 不通 / 别人同时改这文件时合规性跟着盘走)。现全部经 `scripts/lib/face-reader.mjs`,对照面是 `--staged`:HEAD→索引、全量:HEAD^→HEAD、`--worktree` 仅人工;整面取不到 ⇒ **exit 2 无法判定**,不冒红也不记绿。归档件正文也**同面**取(A3 用),单份 blob 取不到 ⇒ 在结论行喊"那一层未判定",不静默通过。另有两条是本门第一次自跑咬出来的:CRLF/LF 的同一条标题不得被读成"删除"(HEAD blob 是 LF、共享工作树常是 CRLF,不剥 `\r` 会把整批已完成条目误报成被删);**点名对象的归属必须拿该目录在审面上的"全集"判**,而不是只看 `PROJECT_PLAN_*` 形状 —— 归档目录里也放非该形状的跟踪件,按形状筛就会把"已入库"读成"落空"。 - **本门自己修掉的两个"拦了却不说话"型缺陷(2026-09-25 G-192,都值得记住形态)**:① A0 阻塞分支写成 `if (deletedHeadings.length > 0 && !del.addedPlaceholders)`,而**空数组是真值** ⇒ 该分支永不执行,门对"直接删已完成条目"`exit 1` 且**零输出** —— 调用方只看到提交被阻止,看不到原因(现走 `del.compliant`,由 length 决定)。② 门按自身位置推导 `ROOT` 之后,镜像测试靠 `cwd` 定位夹具的那套调用**结构上失效了**:13 例里 11 例其实在审真仓,账面全绿而结论与夹具无关(守门 70 同型)。夹具改经显式 `--root ` 通道进入,落点改回 `scripts/lib/scratch-dir.mjs`(§26,不再往 `os.tmpdir()` 写),并由两条**源码级反向锁**钉住(不得再出现"只靠 cwd"的调用形态、不得回到裸 `mkdtempSync`)—— 这类失效只有源码锁能防,加断言会跟着一起漂绿。取证现为 `--self-test` **17** 条 + 镜像 **20** 例(含 A1/A2/A3 端到端与"点名已入库的对象不该红"的反向对照,后者防的是把整层一律判红那种恒红门)。**本门没有应急跳过通道**(runner 条目无 `skipEnv`、脚本不读 env);登记这一事实,是因为本仓多次出现"文档写了一个跑不通的出路"。 - **手动触发**:`pnpm archive` / `--all`(全部)/ `--days 3`(自定义)/ `--dry-run`(预览);跳过用 `HUSKY_SKIP_ARCHIVE=1 git commit`。 - **守门**:`scripts/check-project-plan-archive.mjs` + pre-commit 第 13c 项。历史案例见 `.ihui-agent/archive/AGENTS_history.md`。 - **搬不走时读两把只读尺子,而不是放宽判据(2026-09-28 立,由"把所有已完成任务归档"这一轮逼出)**: ① `node scripts/archive-completed-tasks.mjs --list-blocked [--json]` —— 点名"条目标题写着已完成、体内还裹着未勾选登记"的块,并逐行给出被审面行号与原文(派单与人工裁决的输入)。分区判据是 `partitionPlanBlocks` **一份**实现,`main()` 与该出口共用:两处各写一遍必然漂开,而漂开的表现不是报错,是"日志说卡住 N 块、交给裁决的是另外 N 块"。`--json` 面必须是可 `JSON.parse` 的纯 JSON(人读行会把它打掉,第一版就犯过)。 ② `node scripts/plan-tasks-merge.mjs --audit-pointers [--json]` —— 点名"整族每一行都带着 `【归并】重复登记副本` 指针"的主键族,并分两读数:按主键无终端 / **按编号也找不到任何代表**(后者才是真隐形)。两把尺子都**只读、只报数、不判红**:存量与任何单次提交都无关,挂 blocking 就是恒红门(§12e 同型),数字一律现读不得照文档派单。 - **规矩:块内未勾选行必须"移出块",不得"改判据放过"。** 那些行按 §1 的 F4 口径「两条都是没做完的事、绝不动勾选」就是活账;把它们随已完成块搬进归档件 = 派单口径静默少行。本轮实测教训:520 行里 329 行带归并指针,一度被误判成"派单口径已逐出 ⇒ 归档器与派单口径不同形",据此要放宽 `entryHasOpenRows` —— 该改动作废并留档,因为"逐出派单口径"是为了**不重复派单**,不是说它做完了。唯一无损出路是把 `- [ ]` 行移到台账末尾的 `待办剥离区` —— **该动作已收编成常驻出口** `node scripts/ledger-strip-open-rows.mjs`(缺省档零副作用只出报告,`--apply` 才落地;落地面 = HEAD blob + 临时索引 commit-tree + CAS,**从不写工作树**,因为那份副本常年是别人的在飞现场)。它落地前五条守恒断言任一不过即拒绝写盘(区标题不得自认已完成 ∧ 非空行零消失 ∧ 新增只能是区头与移出行 ∧ 产出面被拒块归零 ∧ 未勾选与已勾选两态都不缩水),迭代到不动点(摘行会改块边界,一轮过会把"还剩几个"报成假 0)。它解的正是"归档器拒绝整块搬运 ⇒ 那些行永久挡住完成即归档"这一型死锁:只换位置,不删行、不改勾选、不动其余顺序,落地前四条守恒断言(区标题不得自认已完成 ∧ 行多重集零消失 ∧ 新增只能是区头 ∧ 派单口径未勾选择不缩水)必须全绿。 - **这一轮连出的第四笔账(当前无判据、无修法,须同笔两处才能收)**:归档把"幸存者"搬走之后,留在台账里的副本指针就地失去终点 ⇒ **归档越干净,隐形族越多**。收口必须**同时**改两处:① `rewriteDup` 在加指针前先问该族是否还有终端代表;② 归并落地的验收断言从「F4 必须归零」升级为「F4=0 ∨ 剩余副本各有终端」。**只改 ① 会让归并器每次自我拒绝**(副本归不了零 ⇒ 停手 ⇒ 自动档永不生效),与恒红门同罪。这条收敛链属台账判据持有人裁决,不得由"排空台账"这一轮顺手改。 - **同一轮的后半已经落地(2026-09-28,枚 7a075820d / 4064e68a6)**:① 活文档归并改成**搬运感知 max** —— `scripts/lib/ledger-move-aware.mjs` 复用归档器那一份块解析判"某行是否已被 `已归档` 占位代表",已代表的不再从对侧取回;失效方向刻意是**多带一行回来**(占位找不到 / 归属解析不出 / 该行被就地改写过 / 归档件取不到 ⇒ 一律照旧取回并打印未判定原因),因为少带一行 = 丢别人的内容。这解掉了"我搬完 → 别人那份滞台副本被合回来 → 台账又涨"的循环。② 守门 84 补 **R1r 行级复活判据**(判索引面、差值棘轮、锚点 = 该文件在 HEAD^→HEAD 那一步自身的复活数且祖先窗口必须剔掉 HEAD 与 HEAD^,否则棘轮被自己喂饱成假绿),`object-space-land` 的同一判据已提取成 `scripts/lib/stale-content-analysis.mjs` 供两处共用 —— 上线当场即点名 6 个路径正把已归档台账行搬进暂存,而旧的整 blob 判据对这一型全部沉默。 ### 唯一例外 - `/goal` 模式:`.ihui-agent/goal-runtime/STATE.md` + `loop-run-log.md`(临时,目标结束后删除);skills:`.ihui-agent/skills/SKILL.md`(AI 工具配置,非计划文档)。 --- ## 2. 项目概览 IHUI-AI 是全栈 AI 平台(TS Monorepo + pnpm workspace + Turborepo),8 端清单: - `apps/api`(Fastify 5 + Drizzle ORM 0.38 + PostgreSQL) - `apps/web`(Next.js 16.2.12 + React 19 + Tailwind 4 + shadcn/ui) - `apps/ai-service`(FastAPI + LangGraph + LiteLLM + MCP) - `apps/miniapp-taro`(Taro 4 + React) - `apps/desktop` / `apps/extension` / `apps/mobile-rn` / `apps/cli`(各端独立) - `packages/`(database / auth / types / ui / config / eslint-config / tsconfig) --- ## 3. 代码风格 - 做减法,最小化代码,零冗余。复用现有代码和模式,不创建文档文件(除非明确要求),不加 copyright/license header。 ### TypeScript 类型零技术债(强制) - **尽最大程度禁用 `any`**,优先用 `unknown` + 类型守卫 / `as const` / 泛型 / 条件类型 / 工具类型(`Pick`/`Omit`/`Record`/`Partial`/`Required`/`ReturnType`/`Parameters`)/ 精确接口替代,禁止把 `any` 当"类型兜底"逃避设计。 - **深度分析 TS 用法**:函数签名(入参/出参/泛型约束)、对象字段、API 响应、props、state 必须显式标注精确类型;能由 `tsc` 推断且可读性良好的局部变量可省略,但禁止"省略 = 不写类型"扩散到公共 API。 - **必须用 `any` 的例外(三选一)**:① 第三方库无 `@types` 或类型声明缺失;② 泛型推断失败且无法用 `unknown` + 守卫替代;③ 跨包循环依赖无法用类型导入断言解决。**必须**附行内注释 `// FIXME(any): 原因 + 移除计划 + 截止版本`,后续 PR 必须清理。 - **不留技术债**:新代码 `tsc --noEmit` 必须 0 错误,禁止"先 any 后修"占位;重构遗留 `any` 必须替换为精确类型,**禁止**复制粘贴扩散 `any`;PR 引入新的 `any` 必须在 PR 描述说明例外依据。 - **守门**(分层渐进): - **过渡期(当前生效)**:`@typescript-eslint/no-explicit-any: error`(packages/eslint-config/index.js,syntax-level 不需 type info,已生效)。lint-staged 对 staged 源码文件触发阻塞,新代码引入 `any` 会在 `pnpm lint` 报错。 - **目标态(已评估,推迟启用)**:`@typescript-eslint/no-unsafe-assignment` / `no-unsafe-member-access` / `no-unsafe-call` / `no-unsafe-return` / `no-unsafe-argument` 五条规则设为 `error`。**2026-07-28 评估结论**:实测启用 `recommendedTypeChecked` + `projectService` 后,(a) 性能不可接受 — cli 包(最小)lint 时间 2.7s -> 51.9s(慢 19 倍),web/api 包预计 30s -> 600s+;(b) 历史错误多 — cli 包已报 30+ 处(`require-await` / `no-unsafe-assignment` / `no-base-to-string` / `restrict-template-expressions` / `no-unnecessary-type-assertion`),全量预计 300+ 处;(c) 配置陷阱 — `eslint.config.js` 不被 tsconfig include 需 `allowDefaultProject`,JS 文件需单独豁免 `no-unsafe-*`。**启用前置条件(全部满足才可启用)**:1. lint 性能优化方案落地(eslint cache 持久化 / 仅 staged 文件 typed-lint / CI 才跑全量 typed-lint);2. 历史类型错误清零(`require-await` 等非 unsafe 错误先修);3. `allowDefaultProject` 配置就绪。 - **测试文件豁免**:`**/*.test.ts` / `**/*.spec.ts` / `**/tests/**` / `**/test/**` / `**/e2e/**` 路径下的 mock/stub 代码允许 `any`(mock 类型断言必需),启用 typed-linting 后通过 `files` overrides 关闭上述规则。 - CI `pnpm typecheck` 全绿方可合并。 ### 共享层优先(强制) - **写新代码前必须先查共享层**,确认是否已有现成实现。禁止在端内(apps/*)重新实现 `packages/` 已提供的功能。 - **检查清单(按顺序)**: 1. **hooks**: `packages/shared/src/hooks/` — 基础 hook(clipboard/debounce/countdown/form/mounted/pagination 等)和业务 hook(auth/chat/agents/articles/agent-runtime/confirm-dialog 等)共 16 个。各端 `hooks/` 目录应只做 re-export wrapper + 平台 adapter,不得独立实现。 2. **utils**: `packages/shared/src/utils/` — 工具函数(date-utils/dangerous-command-detector/format/file-helpers/error-messages/jwt-utils/ai-skill-variables 等)。各端 `lib/` 目录应只做 re-export wrapper。 3. **types**: `packages/types/src/` — 所有跨端类型(ChatMessage/MessageInputFile/WorkspacePermissionMode/User/ApiRequest 等)。禁止在端内重新声明同名类型。 4. **api-client**: `packages/api-client/src/` — 所有 API 调用。禁止在端内直接用 `fetch`/`axios`/`Taro.request` 调后端,必须走 `@ihui/api-client`。端内可保留 re-export + 平台 adapter(如 AsyncStorage 持久化)。 5. **stores**: `packages/shared/src/stores/` — 共享 store 工厂(createAuthStore/createThemeStore)。各端 store 应调工厂 + 注入平台 transport,不得重新定义 state shape。 6. **constants**: `packages/shared/src/constants/` — 跨端常量(storage key/URL/locale key 等)。禁止在端内硬编码同名常量。 - **如果共享层没有**: - 评估是否跨端可用 → 如果是,先提取到 `packages/shared/` 再在端内 import,不得直接在端内写。 - 如果确认平台特有(依赖 DOM/RN API/Taro API)→ 可在端内实现,但必须在文件头注释说明 `// 平台特有:依赖 [DOM/RN/Taro] API,不适合共享`。 - **工厂模式优先**:跨端 hook/util 用工厂函数 + 依赖注入(参考 `createUseClipboard` / `createAuthStore`),各端传入平台 adapter。不得用 `if (Platform.OS === 'web')` 条件分支在共享层处理平台差异。 - **守门**:PR review 时检查是否有端内文件重新实现了共享层已有功能。发现重复 → 要求改为 import 共享层。 --- ## 4. 前端 UI 约束 - compact 紧凑、elegant 优雅。hover 用 subtle 颜色变化,**不要蓝色发光边框**。复用 `packages/ui-react` 的 Card/Button/Input/Dialog。每个页面 < 250 行。时间用 `Intl.DateTimeFormat`,头像用 initials。状态徽章:draft 灰 / published 绿。积分正数绿色,负数红色。 ### 品牌 CTA / 主按钮色同源(强制,2026-09-24 收口) - **唯一写法(2026-09-26 回翻定稿)**:主按钮、选中胶囊、悬浮加号这类"品牌实底 + 其上文字",RN/共享包写 `brand.cta`(底)+ `brand.ctaForeground`(文字)**成对**;CSS/类名侧用 `--color-cta` + `--color-cta-foreground`(小程序 `CategoryBar`/FAB 同值)。**这一档黑/白反转**:亮=纯黑底(`#000000`)/ 纯白字(`#FFFFFF`),暗=纯白底(`#FFFFFF`)/ 纯黑字(`#000000`),与 `--color-primary` 同一明暗行为,`.dark` 显式覆盖。对账由「跨端色值同源对账」守门负责(编号以 `scripts/guardian-runner.mjs` 现值为准,勿照抄文档)。 - **为什么保留独立档名而不并进 `--color-primary`**:primary 在 web 端兼任墨色(`text-primary` 1803 处),改它等于给全站正文染色;CTA 保持独立档名、取值与同主题 primary 全等,语义 = "品牌实底 + 其上文字"。(2026-09-24 曾取 `#4A7A96` 明暗同值以避开"大色块与页面反极",2026-09-26 用户明确要求回翻为黑/白反转,该设计已废。) - ~~**唯一写法(2026-09-24 已废)**:主按钮/选中胶囊用 `brand.DEFAULT` + `brand.foreground`,CSS 侧 `--color-primary` + `--color-primary-foreground`。~~ 该行描述的正是被本票替换掉的旧档:DEFAULT 亮=纯黑 / 暗=纯白,大色块与页面反极。**现存唯一写法见本节第一条**(`brand.cta` / `--color-cta`)。保留本行仅为让早期条目里的 `brand.DEFAULT` 措辞能被追溯到已废。 - 真要新增品牌档:先在 `tokens.css` 落一个 CSS 变量,再到同源对账门的映射表登记依据;确属 RN 专属(如 `brand.dark` 品牌绿)才能进 `RN_ONLY_BRAND_KEYS` 并写明理由 —— 豁免项若已不存在同样算红(防清单腐烂)。 - 悬空引用由该门的"品牌键"判据直接拦(编译不一定红,运行时是 `undefined` 颜色)。并行会话的暂存区里若还残留 `tokens.brand.ctaFill/ctaText`,改法只有一行:`ctaFill` → `cta`、`ctaText` → `ctaForeground`(2026-09-24 改档;此前该行的指向是 `DEFAULT`/`foreground`,已随 CTA 独立成档而更新)。 - **禁止端内自立 CTA 档**:`brand.ctaFill` / `ctaText` 这类"浅色等于 web、深色另取一档"的**混血**键不得再加回 —— 当年删它不是因为"不许有 CTA 档",而是因为**它在端里自立、且两档取值互不相同**(那才是"手机上改了 web 没改"的成因)。`--color-cta` 走的是相反路径:先落 `tokens.css` 源头(2026-09-26 起 `.dark` 显式覆盖、黑/白反转)、再进同源对账门的映射表,所以它合法而旧键仍属禁止。要调主按钮观感就改 `tokens.css` 的 `--color-cta`(亮档)与 `.dark --color-cta`(暗档)**同一处**,三端一起动;不得在某一端单独覆盖。 - **成对即合规,不得再当债务**:主 CTA 的唯一写法是 `brand.cta` 实底 + `brand.ctaForeground` 文字(旧档 `brand.DEFAULT` + `brand.foreground` 已废,见上),所以这套配对**必须**被所有前景/容器对账判据认作合法 —— 按规矩写就红的门只有一个结局:逼人 `--no-verify`,连带废掉全部守门。拦的是**没有配对前景**的实底卡片与**跨档错配**(底取 `brand.cta`、字却取 `text.primary`/`surface.light` —— 前者黑/白反转下两态与底同色纯隐形,后者按档位法则本就非配对前景)。守门 83 的 R1_BG 已同时认 `brand.DEFAULT|brand.cta`,就是为了"判据必须覆盖门自己产出的形态"。 - **禁止端内自立 CTA 档**:`brand.ctaFill` / `ctaText` 这类"浅色等于 web、深色另取一档"的混血键已全部删除,**不得再加回**。要调暗色主按钮的观感(例如觉得纯白刺眼),改 `tokens.css` 的 `.dark --color-primary` **一处**,web / 小程序 / RN 同时动;不得在某一端单独覆盖 —— 那正是"手机上改了 web 没改"的成因。 > ⚠️ 本行已于 2026-09-24 被上面「禁止端内自立 CTA 档」新条目就地改写取代;保留原文只为不丢行,勿照它执行。 - **成对即合规,不得再当债务**(同日补):上面这条是主 CTA 的唯一写法,所以深色档案下"brand.DEFAULT 实底 + brand.foreground 文字"**必须**被所有前景/容器对账判据认作合法 —— 按规矩写就红的门只有一个结局:逼人 `--no-verify`,连带废掉全部守门。拦的是**没有配对前景**的白卡片与**跨档错配**(底取 brand、字取 `text.primary`/`surface.light`)。 > ⚠️ 本行已于 2026-09-24 被上面「成对即合规」新条目就地改写取代;保留原文只为不丢行,勿照它执行。 - **RN 侧 `dark:` 类必须与 App 主题同源才允许依赖**(强制):共享 preset 是 `darkMode: 'class'`,`dark:*` 工具类读 NativeWind 自己的 colorScheme store。`apps/mobile-rn/src/theme/color-scheme-sync.ts` + `ThemeProvider` 负责把 App 解析出的主题(light/dark/system→系统)落进该 store —— 缺这一步,`dark:` 只跟系统外观,与 App 内主题开关长期分裂(而前景/容器对账门把"同行有 `dark:` 变体"记为已配对,不同步时那些配对只是纸面正确)。**新增深色取用二选一**:走 `tokens.*`(模块级单例,重载 JS 生效,共享包默认),或走 `dark:` 变体(依赖上述同步);不得混用两套、更不得在端内自造第三个色源。回归:`apps/mobile-rn/tests/theme-colorscheme-sync.test.ts`。 - 真要新增品牌档:先在 `tokens.css` 落一个 CSS 变量,再到守门 90 的映射表登记依据;确属 RN 专属(如 `brand.dark` 品牌绿)才能进 `RN_ONLY_BRAND_KEYS` 并写明理由 —— 豁免项若已不存在同样算红(防清单腐烂)。 - 悬空引用由 R3 直接拦(编译不一定红,运行时是 `undefined` 颜色)。并行会话的暂存区里若还残留 `tokens.brand.ctaFill/ctaText`,改法只有一行:`ctaFill` → `DEFAULT`、`ctaText` → `foreground`。 ### 描边不得取墨档(强制,2026-09-26 立) - **规矩**:任何描边 —— RN/共享包的 `borderColor` / `borderBottomColor` / `border: \`1px solid …\``模板串、web 与小程序的`border-primary`/`ring-primary` 类名 —— **一律不得取墨档**。用户原话:「我们项目设计没有这样的纯黑色的描边」。 - **禁的四档**:`brand.DEFAULT`、`brand.foreground`、`brand.ctaForeground`、`text.primary`(亮=近纯黑,暗=近纯白)。它们兼任墨色与文字色,当描边用就是在容器外圈画一道硬黑线。 - **合法出路只有两条,都是项目已有档**:中性描边 → `border.light` / `border.medium`(= web 的 `border-border`);强调描边 → `brandAccent.light` / `brandAccent.deep`(= web 的 `border-brand-accent-deep`,亮 `#4a7a96` / 暗 `#a3c4d6`,端内在 R8 之前已有 7 处这么写)。不得在端内自拼 `#000` / `rgba(0,0,0,…)`,也不得为消红去改判据。 - **`brand.cta` 作描边不由本条判**:它是"主实底"档,与同色填充并用作描边时语义是加厚而非描边,且该形态早已计入守门 83 的 **R3** 计数面(`(backgroundColor|borderColor): *.brand.cta`)。同一笔债两道门各计一次会让两份基线互相顶掉。 - **染色档不算这一型**:`border-primary/20` 是 20% 染色、`border-primary-foreground` 是另一个键名,都不属"纯黑描边"。判据用尾部字符类同时排除两者,别放宽。 - **覆盖面(同日两次补,现行口径以这条为准)**:R8 判**三种书写形态**——RN style 对象(`border\w*:` 取墨档)、Tailwind 类名(`border-primary`/`ring-primary`)、**CSS 声明**(`border*: … var(--color-primary)`,含 TSX 内联字符串形态)。文件面**不再维护端名单**:`R8_DIRS = ['apps','packages']` 整面取,只靠 `e2e/tests/__tests__` 与 `*.test/spec.*` 排除叙述行;扩展名含 `tsx|jsx|ts|js|css|scss`。立项时前两种形态各自漏过一块(extension 不在 R5 端表里 → 类名形态在扩展端失明;.css 不在扩展名里 → **19 处** CSS 声明整面隐身),两处都已随同笔提交清零,基线 `inkBorderCounts` 仍为**空 = 零容忍**。**给守门扩面必须同批改两半**:内容判据的 scope 函数 + 枚举/预筛的目录表与扩展名;本条的第一版就只改了 scope,`git ls-files` 仍用旧表,结果**整块改动静默失效而门照报绿**。防线两条:① 拿真仓 HEAD 喂新判据,它必须点名已知存量(阳性对照);② 镜像测试锁源码——枚举面必须引用新表、旧表不得再出现、预筛常量必须含新形态。 - **历史成因(值得留着)**:本门自己的修复提示曾写着「`brand.DEFAULT` / `--color-primary` 只保留墨色、**描边**、文字色三义」—— 散文把这一档列为描边的合法语义,判据又只管"前景 vs 容器配对"、从不算描边取哪档,**两边一起漏**,所以这一型活了很久还一路报绿。现该措辞已就地改掉。 - **守门**:并入 83(见下方速查),新增判据 **R8**,基线键 `inkBorderCounts` 现为**空 = 零容忍**(立门当日 HEAD 实测 148 处:RN style 面 33 + web/小程序类名面 115,已全部并回上述两档)。行内豁免 `border-ink-exempt: <原因>` 必须带原因且**逐行**生效;上一行算豁免的前提是它是纯注释行。 ### 圆角单一源头(强制,2026-09-23 全端收口) - **唯一真相源**:`packages/design-tokens/src/radius.js` 的 `RADIUS_STEPS` = `xs 2 / sm 4 / md 6 / lg 8 / xl 12 / 2xl 16`(px;`DEFAULT`=8 对齐 web `--radius: 0.5rem`)。改档位只改这一处。`tailwind-preset.js` 必须写 `borderRadius: RADIUS_REM`,`tokens.css` / `app.css` 的 `--radius-*` 必须与之逐档同值。 - **"哪类元素取哪档"也有唯一真相源(2026-09-27 立)**:同文件的 `RADIUS_ROLES` = `tiny→xs / control→sm / chip→md / card→lg / panel→xl / hero→2xl`,JS 侧按 `rnRadiusFor.<角色>` 取,文档侧是 `docs/UI_GUIDELINES.md` §3.1 的展开。**立因**:项目此前只定义了档位**值**,从未定义角色→值,于是两端各按直觉选 —— 同一张 `UserInfoCard` 小程序 8px、App 12px,`ModelList` 一端 8 一端 12,而守门 77 一路报绿(它只判"有没有绕档位表写死数字")。§3.1 表格当时还写着 `rounded-sm`=2px、`rounded`=4px,与档位表差一档 —— 照文档写必错,那两行已随本表更正。**新增角色必须同笔有消费方**,不得先建表再等人用(与 `geometry.js` 同一条规矩)。 - **各端取用形态(不得自创写法)**: | 场景 | 唯一写法 | | -------------------------------------------- | ----------------------------------------------------------------------------- | | web / ui-react / extension(Tailwind v4 类名) | `rounded-xs` ~ `rounded-2xl`;CSS 里 `var(--radius-)` | | miniapp-taro / mobile-rn(NativeWind v3 类名) | 同上,**禁止** `rounded-[24rpx]` 这类任意值 | | RN StyleSheet / 任意内联 style | `borderRadius: rnRadius.lg`(`import { rnRadius } from '@ihui/design-tokens'`) | | `.css/.scss/.html` 任何端 | `border-radius: var(--radius-lg)`,禁止 px/rpx 字面量 | - **类名语义按 web 对齐(修文档漂移)**:v3 preset 曾把 `rounded-sm` 定成 2px、web v4 是 4px,同名不同值即"手机上圆角和全局不一致"的根因;现 `sm=4px`,2px 由 **`rounded-xs`** 承载。裸 `rounded` 全端统一 8px(web 现实)。旧条目里"`rounded-sm`(2px)"作废。 - **禁止绕档**:每文件自定 `const *_RADIUS = <数字>`(含 `BAR_RX` 这类**名字不带 RADIUS** 的圆角常量)、用 `rpx()` 算圆角、`rounded-[任意值]`、StyleSheet 里写数字字面量、**以及写字符串形态 `borderRadius: '8px'` / `"6px 6px 0 0"`**(字符串曾是守门盲区,2026-09-23 对抗排查补上;多值串须拆成四个角属性引用档位)。 - **上面那句"多值串须拆成四个角属性"曾只是散文**(2026-09-27 O81 票⑯实测推翻其覆盖声明):守门 77 的 B3 判 CSS 声明时是**整串判** —— 值里出现 `var(` 就整条放行,于是 `border-radius: var(--radius-xl) 24rpx 0 0`(第一个角引用档位、其余角写死字面量)这类多值声明**整型隐身**,HEAD 实存 4 处;另一型是 Tailwind **任意属性形态** `[border-radius:6rpx]` —— 判据的值前导字符类不含左方括号,整型隐身 1 处,而那个 6rpx(=3px)根本不在档位表上。**两型都是门 150 的"未判定"清单反手指出来的**(它按逐值读,所以看得见),即"两台尺子互相指认无人看守"这一缝在本仓第二次现形。现 B3 改为**逐值判**(每个角各自要求档位引用/豁免,`var(`/`calc(`/`0` 放过),值字符类同时排除右方括号(否则后半串 className 被当成一个值读),5 处站点同笔换成档位引用或 `rounded-full`。取证:门 77 自检 53→58 例(正反成对:多值必拦 / 全 var 不误伤 / 任意属性必拦 / 任意属性引档位放行)+ 镜像 8→10 例(夹具端到端逐条点名 `24rpx`、`6rpx`、`dot.tsx`,另两条源码形状反向锁:整串短路写法不得回来、前导字符类必须含 `[`)。 - **SVG 圆角同样受管(B5)**:`rx` / `ry` 会产生圆角,JSX 内联 SVG 必须写 `rx={rnRadius.xs}`;**静态 `.svg` 资产**没有 JS 通道,取值须等于档位值(偏档就近吸附、等距取小),确属形状需要则加 ``。 - **生成式 HTML/CSS 字符串**(cli 分享页、`packages/shared/src/design/design-templates.ts`、扩展 content script、api 的 `swagger-theme.ts` 等拼 CSS 文本处):**不得写死数字**,用同表插值 `border-radius: ${RADIUS_CSS_PX.md}`(`import { RADIUS_CSS_PX } from '@ihui/design-tokens'`),不新增第二份真相。 - **真圆/胶囊豁免**:头像 / 装饰点 / 红点 / 进度环 / Switch 拇指 / 半高胶囊输入框**不得方档化把形状改坏**。优先 `size / 2` 表达式;确需保留数值必须在同行或紧邻上行写 `radius-exempt: <一句话原因>`(JS/TSX 用 `//`,CSS 用 `/* */`,静态 .svg 用 ``),不得静默写死。 - **守门**:`scripts/check-radius-single-source.mjs`(guardian 第 **77** 项,blocking)三判据 —— A 档位表四处对账(改一处忘改另一处即红)、B 端内取用必须引用档位(B1 数值与字符串形态 / B2 本地常量 / B3 CSS 字面量 / B4 任意值类 / B5 SVG rx-ry / **B6 引用 `rnRadius`、`RADIUS_CSS_PX` 却没在本文件 import** —— 本门判 HEAD 而 `pnpm typecheck` 只跑 worktree,悬空标识符属于"两边都不红"那一类)、C 覆盖面对账(含圆角的跟踪文件要么落在 SCAN_DIRS,要么在 `OUT_OF_SCOPE` 写明为什么不适用)。**B 的棘轮锚点是「该文件 HEAD 版本自身的违规数」**,不是手工清单 —— 只拦"这次改动把绕档加回来了",不拦仓库既有债。2026-09-24 换锚的起因:并行会话的索引层重建把 309 个路径整文件回写成迁移前的旧基线(**HEAD 积累 1179 处**),静态清单对此完全绿灯;同时全量审计改判 **HEAD blob 而非工作树**,因为滞后的旧草稿会被按磁盘读误记成本仓债务(一道与真实改动无关的红门只会逼人 `--no-verify`,连带废掉全部守门)。`scripts/radius-single-source-baseline.json` 降级为人工兜底,**现须为空**(镜像测试钉死)。判据**不锚定行首**,故 `width:16px; border-radius:50%` 同行多声明、TS 里生成的 CSS 一样可见。按文件自验:`--files `;紧急跳过 `HUSKY_SKIP_RADIUS_GUARD=1`;自检 `--self-test`(49 例,含真实表端到端对账、静态/内联 SVG 两种语义、NaN 防回归、HEAD 锚点四方向正反例、多行 import 不误伤),镜像测试 `node --test scripts/tests/check-radius-single-source.test.mjs`(4 例,含"锚点必须是 HEAD 而非静态清单"的装车证明)。容器纯圆违规仍由 `scripts/check-rounded-full.mjs`(第 11 项)管,两条互补不互替。 ### Button 高度档位守门(强制,2026-09-07 立) - **`@ihui/ui-react` 的 `