# 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",所以改写必然产出两份。三条规矩: 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**(目标行已不是条目行)——上一轮登记"已识别、只标注未翻勾"的那批账,今天已无法按它自己给的证据复核。必须用内容锚点(编号 + 标题原文)。 - 问责:`pnpm check:plan-task-state`(`--strict`,存量判红);提交链上跑的是**差值棘轮**(只拦"这次提交让分叉变多",存量永不拦 —— 与改动无关的恒红门只会逼人 `--no-verify`,连带废掉全部守门,§12e 同型)。修法只有**归并**(副本翻勾并注记归并到谁),§1 的"禁止无声删除"对已完成行仍然成立。 ### 归档机制 - 已完成任务条目(`### XXX(已完成 ✅ ...)` 标题)**禁止直接删除**,必须两步走:① 把完整任务条目(标题 + 正文)移动到 `.ihui-agent/archive/PROJECT_PLAN_YYYY-MM-DD.md`;② 在 `PROJECT_PLAN.md` 原位置留 HTML 注释占位:``。 - **自动归档**:`scripts/archive-completed-tasks.mjs` 扫描完成 ≥7 天的条目,post-commit 钩子自动 `--auto-commit`。归档 commit 设 `IHUI_ARCHIVE_COMMIT=1` 防递归。 - **标题形态三处必须同形**(2026-09-25 G-182 实证):本节写的 `### XXX(已完成 ✅ ...)`、守门 13c 的提取式、归档器 `parseCompletedTasks()` 的匹配式,**任一处漂了另外两处不会响**。归档器曾按 `/^### \[x\]/` 找标题,而文件里 `^### [x]` 命中 0 次 ⇒ 连续 11 天每次跑都扫到 0 条、post-commit 静默无操作。现判据:含 `✅` 即算已完成条目,日期取标题里第一个 `YYYY-MM-DD`(真实形态日期常在 ✅ 之前);**无 `✅` 的小节标题(如 `### 已完成清单`)不算条目** ⇒ 归档器的搬运集必须是 13c 保护集的**真子集**,否则一边搬一边护就是互咬。 - **大批量阀门只挡自动档**:`--auto-commit` 下一次 >25 条或 >256 KB 即拒绝并打印实测数字(退出码 0 —— 自动档少做一件事不是错误,不得把钩子链弄红),需人工 `--allow-mass` 放行。依据实测稳态一次 7 条 / 15,168 B / 全文 0.61%;超量只可能是格式又漂或积压一次放开(参照 §5c 水印门"单次缺口 >200 拒绝自动回写"同一条设计)。 - **归档锚点必须受版本控制**(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`。 ### 唯一例外 - `/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-*` 必须与之逐档同值。 - **各端取用形态(不得自创写法)**: | 场景 | 唯一写法 | | -------------------------------------------- | ----------------------------------------------------------------------------- | | 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 对抗排查补上;多值串须拆成四个角属性引用档位)。 - **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` 的 `