项目：react-ui ｜ 版本：v1.1 ｜ 生成日期：2026-10-06 ｜ 依据：源码分析
本篇把散落在源码注释、文档口径与既往篇目里的 ⚠️ 项汇总成一张台账：每一项给「位置 / 证据 / 影响 / 建议」四要素，全部经本轮回源码核实（不沿用传闻）。之后给出与台账对应的演进路线图。仓库自己的债务政策（CONTRIBUTING「债务政策」：棘轮只许调低、豁免必须留注释、争议写「待裁决」）与本篇的立场一致——债务必须可见、可定位、有处置意见，但不必全部立刻清偿。两轮全量审计的档案在 archive/audit/（12 条逐文件审查清单在 archive/audit/AUDIT-2026-09-17/CHECKLIST.md），本篇是它们之后的第三轮汇总。
apps/nas-console/（本检出仅含 dist/ 与 node_modules/）。apps/docs/dist，暂不涉及它，但 ADMIN-ROADMAP 的管理端示例叙事依赖它）；文档站迁移指南若引用其实现，读者无源可查；dist 产物会随时间与依赖漂移，变成无法重建的黑盒。@xiaoye-react/charts 在路线图中标记「✅ 可用」但仓库内不存在ADMIN-ROADMAP.md 第 26 行（「仪表盘 | @xiaoye-react/charts（recharts 封装）：Bar/Line/Area/Pie/Donut/Radar 等 | ✅ 可用」）；packages/ 与 packages/@xiaoye-react/ 下均无 charts 目录；全仓源码检索无 recharts 依赖。check:exports 与 peer 校验对它完全失明。属「文档承诺与仓库事实漂移」类债务，性质比代码 bug 更伤信任。packages/@xiaoye-react/charts；或把路线图该行改为「计划中/外部仓库」；或在 README 声明 charts 的真实位置。⚠️ 待确认该包是否存在于独立仓库。packages/ui/src/components/ 下 129 个目录中的 37 个（完整清单见《09-测试与质量保障》第 2 节；既往文档口径「91/130 有单测」与本批初稿的「90/129」均为目录计数与测试文件归类的口径差，2026-10-06 回源复核统一为实测 92/129）。*.test.tsx。@xiaoye-react/tests 的 axe 工具补输入外壳的无障碍断言；基建型与纯视觉型的优先级最低。配套动作：在 docs 或 CONTRIBUTING 里把「同目录必须有测试」从惯例升格为可检查的清单（甚至可加一个简单的缺测告警脚本入 docs:lint 旁路，⚠️ 待确认是否值得为它加脚本）。packages/hooks/package.json 的 description 字段、packages/hooks/README.md 第 7 行；实测 packages/hooks/src/ 下 83 个 use-* 目录。packages/hooks/vite.config.ts 注释里的「87 个 hook」是另一个口径——三个数字（60+/83/87）并存说明没有单一事实源。packages/hooks/src/index.ts 的导出为唯一事实源，README 与 description 改为实测数字；更彻底的做法是让 docgen 脚本顺带产出 hook 清单（apps/docs/scripts/docgen.ts 已具备类型扫描能力）。《15-接口全量参考》已按 83 目录口径建表，可作为对账基准。eslint.config.mjs 的 ignores 数组（packages/ui/src/components/Menubar/**/*、packages/ui/src/components/Tree/**/*）。eslint.config.mjs rules 段：no-explicit-any、no-unsafe-function-type、no-empty-object-type、ban-types、no-unused-vars、no-unused-expressions、no-namespace 均 off。any 的入库无门禁（实例见第 08 篇第 6 节的 adapter ctx）；no-unused-vars 关闭意味着死代码不被提示。packages/*/src 开启 no-explicit-any 为 warn 并并入棘轮总量（不追求清零，只防增长——与 exhaustive-deps 台账同一模式）；no-unused-vars 可用 tsc 的 noUnusedLocals 折中评估（2026-10-06 回源复核：根与各包 tsconfig 均未启用 noUnusedLocals，启用属纯新增、与现有 typecheck 配置无冲突；代价是存量未用变量会新增一批报错，需按棘轮模式消化）。playwright.config.ts 与 .github/workflows/ci.yml 注释（「基线跨平台不通用」）。actions/cache 缓存基线产物），本地与 CI 各自维护平台基线目录；若维护成本实测过高再退回现状并记录裁决（⚠️ 待确认基线维护成本）。packages/*/package.json 的 prepublishOnly（仅 build；ui 另跑 check:exports）。scripts/release.mjs 头注释明言「包级 prepublishOnly 只有 build，不含测试」并因此显式执行 runPackageTests。release.mjs 或根 publish:* 脚本时测试必跑（两处都补了），缺口只在绕过脚本直接 pnpm --filter <包> publish 的手工路径。packages/hooks/src/ 30 个测试文件 vs 83 个 hook 目录（清单见《09-测试与质量保障》第 2 节）。use-uncontrolled（全库状态模型法定实现，语义目前靠 ui 侧测试间接固化）、use-media-query（其 attachMediaListener 导出是 ui peer 下限所系）、use-focus-trap、use-id。use-uncontrolled 的「双 onChange 陷阱」与受控判定语义应像 merge-ui-theme.test.ts 一样固化为契约测试。packages/ui/package.json description 写「130+ 组件」、目录实测 129——「130+」作为约数可接受，但在《15-接口全量参考》建表后建议统一引用实测值；commitlint.config.cjs 尾部有大段注释掉的汉化配置（约 80 行死配置），建议删除或启用；CodeHighlight 同步高亮阻塞主线程的已知边界（CodeHighlight.tsx 注释自述），长期方案是异步/Worker adapter（见《10-性能设计与优化》第 6 节）；| 编号 | 摘要 | 风险 | 建议动作 | 优先级 |
|---|---|---|---|---|
| D1 | nas-console 仅 dist | 可审计性 | 源码入库或移除 | 高 |
| D2 | charts 路线图漂移 | 信任 | 澄清去向 | 高 |
| D3 | 37 组件无单测 | 回归风险 | 按优先级补测 | 中（分批） |
| D4 | hooks 60+ 口径 | 文档准确性 | 改为实测 83 | 低（10 分钟） |
| D5 | Menubar/Tree 免疫 lint | 质量洼地 | 修复后移出 ignores | 中 |
| D6 | 类型安全规则关闭 | 类型漏洞 | 开 warn 入棘轮 | 中 |
| D7 | 截图 e2e 不在 CI | 视觉回归 | 单平台基线试点 | 中 |
| D8 | prepublishOnly 无测试 | 手工路径 | 维持现状或收紧 | 低 |
| D9 | hooks 30/83 覆盖 | 契约漂移 | 补四个基建 hook | 中 |
| D10 | 口径/死配置/同步高亮 | 杂项 | 顺手清 | 低 |
把台账与既有路线图（ADMIN-ROADMAP.md）对齐，给出三个阶段的演进建议。每个阶段的立项都遵循同一条排期原则：先清「文档性债务」（零代码风险、立刻建立信任），再清「覆盖性债务」（补测试补 lint，风险低但耗工时），最后才动「结构性演进」（新包、换构建链、换实现）——这个顺序本身就是路线图的裁决逻辑，任何跳级（比如先做图表包再补覆盖缺口）都意味着在已知风险未消化时引入新面。
@xiaoye-react/tests 复用）；其二，文档站构建链迁移（rspress/vitepress 备选，dumi patch 与 mako 的长期维护是隐性成本，ADMIN-ROADMAP 已列为长期可选项）；其三，高亮链路异步化（CodeHighlight adapter 的 loadContext 已预留异步形态）；其四，React 官方 Activity API 稳定后替换 core/utils/Activity 的 fallback 实现（源码注释已预告这一步）。第三阶段项目因为动了结构，每项都需要独立的立项记录（实测数据、替代方案对比、回滚方案）——ADMIN-ROADMAP 里 mako 保留决策的记录方式就是范本：两个候选方案的实测数字、落选原因、复评触发条件全部在案。节奏上没有理由快：这是单人维护仓，路线图的执行者与受益者是同一个人，真正的约束不是进度而是每次改动都必须全绿——门禁清单本身就是最稳的节拍器。若多个阶段并行，唯一需要串行的点是发布：结构演进产出的新包（charts 等）要走《06-部署运行》的发布序列，与第二阶段的补测批次错开发布窗口即可。每一步都应延续本仓的纪律：先写注释记录实测数据，再动代码——债务治理与性能优化一样，起点是「可见」。
这份台账本身也需要一个「不腐化」的机制，建议与仓库既有的治理设施对齐：每项债务一个锚点——D 系列编号写进对应位置的注释（如 D5 写进 eslint.config.mjs 的 ignores 注释、D8 写进 release.mjs 头注释），让「债务存在」这件事在源码里可见，而不是只活在文档里；清偿动作走正常门禁——补测试、修 lint、移出 ignores 都随常规提交走 pnpm commit，不设专门的「还债分支」，避免债务分支与主干漂移出第三种状态；新债务的入口——按 CONTRIBUTING 的裁决原则，发现即记录（位置/证据/影响三要素齐全才入台账，「感觉不好」不算证据），争议项标「待裁决」挂起而不是强行定性；定期复核——台账与 archive/audit/ 的审计节奏对齐（两轮全量审计先例），每轮复核标记已消解项与新增项，路线图的阶段划分随之滚动。这套机制没有新增任何工具——它复用的全部是仓库已验证有效的设施（注释档案、棘轮、测试裁决），这正是对这个治理体系最好的信任投票：债务管理的答案不在更多流程里，而在把既有纪律延伸到「未修的东西」上。