Files

T

Regression / regression (push) Canceled after 0s

Details

refactor(详情页+S8): 详情页减重(导航互斥/入口去重/i18n去重) + 品牌标识入库

本提交含两条并行工作线，因互相咬合（package.json scripts、regression.yml、
npm run build 链）无法按文件干净拆分，故合并为一次自洽提交。

## 详情页减重（本轮主任务：修复「AI 干太重」）

- 导航收敛：宽屏只用右侧目录、≤1200px 只用页内 sticky 导航，纯 CSS 媒体查询
  实现（不引入 JS 宽度监听）。此前两套导航同时可见，active 状态互相打架。
- 入口去重：标题区由「查看示例/在线测试/契约 JSON」三个减为「在线测试」一个；
  契约 JSON 归入实现资源；删除示例底部重复的「在线测试」。
- 示例工具栏：删除与目录锚点重复的示例下拉选择器；「全部展开代码」只在
  示例数 >1 时出现（103 个组件里 49 个仅 1 个示例，此前恒显示）。
- 重复文案：示例区两句同义导语合并为一句。
- 首页 CTA 由 5 个减为 2 个（浏览组件/快速开始），测试总览入口挂到已有的
  通过率统计卡上，不再另占 Hero 按钮。
- 统一详情取数：抽出 fetchDetail/loadDetail 作为 details/*.json 的唯一路径，
  FAQ 不再自行 fetch 一遍，与组件页共用缓存与失败兜底。

## i18n

- 删除 12 组重复键（含整段 FAQ 说明），字典 604 → 585 唯一键。
- 删除本次改动产生的 6 个死键。
- verify-i18n.mjs 新增 `unique dictionary keys` 断言：重复键在对象字面量里
  是静默的后值覆盖，此前无从发现；现由门禁拦住。

## 文档事实修正（实测为准）

- TESTING/CONTRIBUTING：79 → 103 组件；旧断言数改为回指 tests/report.json。
- PLATFORMS：移动端 108 文件/18 端 → 282 文件/47 端；契约 5 → 47；
  令牌 17 → 15；uni-app SFC 21 → 50。
- AGENTS：断言 1405/18 页 → 1464/103 页（PC）、807/47 页（移动端）。
- package.json：YOUR-ACCOUNT 占位 → gitea 实址与 kole-ui.mymoyu.top。

## 品牌标识（并行会话成果，一并入库）

- brand-mark.json 收归真源，build:brand 生成 favicon 与单色 SVG；
  PC 与移动端共用资产，verify:brand 24 条断言。
- regression.yml 增加 verify:brand 步骤。

## 门禁与验收

新增工具：verify-component-page.mjs（86 条真实浏览器断言，随详情页改造同步
更新为「只允许一套导航可见」）、verify-brand-mark.mjs、lib/i18n-dead-keys.mjs
（只读诊断）。

回归：PC 100%（1464/1464，103 页，N/A 50）· 移动端 100%（807/807，47 页）。
门禁：component-page 86 · i18n 17 · brand 24 · routes all · smoke all ·
theme OK · isolation 31 · nav all · examples 9 · api-docs 10 · mobile-docs 12。

已知未做：i18n 另有约 44 条历史死键（非本次产生），已记为 ROADMAP S8-P6；
顶栏与悬浮区的两个主题入口为刻意设计（verify-theme 断言其互斥），未删。

2026-09-22 23:56:05 +08:00

156 KiB

Raw Permalink Blame History

Kole UI · 长期路线图与任务包

文档性质：交给执行模型的工程规划。每个任务包自带验收命令与失败判据，拿到即可开工，不需要再问。 基线版本：v1.4.1（2026-09-11） 规划人：海鸥（规划师角色） 更新约定：任务完成时在本文件对应任务包下追加 ✅ 完成于 <commit>，不要删原计划。

〇 · 交接约定（执行模型必读）

0.1 铁律（违反即返工）

零运行时依赖不可破：不引入 npm 运行时依赖。构建/测试脚本用 Node 内置能力或 PowerShell。package.json 的 dependencies 必须为空（devDependencies 可用）。
build-site.ps1 必须 ASCII-only：PS5.1 按 ANSI 读无 BOM 文件，脚本里出现非 ASCII 字面量会被损坏。中文文案放 UTF-8 模板。
改结构要改模板：tests/<slug>.html 是生成物 —— 改它没用。改 tests/_template.html / tests/_index_template.html 后重跑 run-tests.ps1。
改样式要改内嵌层：演示页的内嵌 <style> 才是实际生效的样式（v1.4.0 教训：只改 frameworks/*.css 可能不生效，因为演示页不一定 link 它）。
data.json 是 For Agents 的对外承诺：可以拆 data.js，但 data.json 必须保持完整（一次请求拿到全部）。破坏它是 breaking change。
单次改动后必须跑回归：tests/_collect.html 八次连跑，100% / 0 失败 / 0 超时 才算过。

0.2 禁止事项（做过即需回滚）

禁止	原因	正确做法
在 `frameworks/` 里直接手工改出"更好看"的样式	`frameworks/` 是规范原文的忠实实现，改动会破坏契约一致性	要改样式先改令牌，或走任务包流程
用 `git reset --hard` / `git checkout .` 清理	会丢用户改动	用 `git stash` 或定向还原
删除或改写 `CHANGELOG.md` 的历史条目	那是变更事实记录	只追加 `[Unreleased]` 或新版本段
修改 `tests/report.json` 的数值来"通过"验收	报告是生成物，改它等于伪造证据	修实际问题后重跑生成
为了通过验收而放宽断言判据	v1.3.1 曾出现"调松断言刷分"的诱惑	断言判据的修正必须附理由 + 反例
在规划未涉及的领域顺手重构	范围蔓延会让验收失焦	写成新任务包追加到本文件

0.3 环境与工具

项	说明
操作系统	Windows（开发）/ Linux（CI）。跨平台写法见下方「跨平台注意」
Shell	Git Bash（开发）/ bash（CI）
Node	≥ 18（用到 `node:sqlite` 的任务需 ≥ 22）
构建	`powershell -NoProfile -ExecutionPolicy Bypass -File build-site.ps1`（Windows 专用）
回归	浏览器打开 `tests/_collect.html`，或 `node tools/run-regression.mjs`（需 playwright）
本地服务	`node site/dev-server.js`（端口 3311）

跨平台注意：

后台启动服务：Windows Git Bash 用 node site/dev-server.js &，CI 用 node site/dev-server.js & sleep 3。不要用 start 或 nohup。
路径分隔符：脚本里统一用 POSIX 风格（/），Node 的 path 模块会处理。
PowerShell 脚本只能在 Windows 跑。若 CI 需要构建，改写为 Node 脚本或加 runs-on: windows-latest。

0.4 失败升级路径

执行中遇到阻塞时，按这个顺序处理，不要停下来等：

情况	处理
验收命令本身有错（路径不对、语法不兼容）	修正命令使其能真实反映目标，在交付说明里写明修正了什么、为什么
目标不可达（如依赖的服务/网络不可用）	交付最强替代物 + 写明缺什么。例：无法 `npm pack` 则做本地 `npm pack --dry-run` 的等价检查
发现规划有事实错误（如"某字段占 89%"实际不是）	以实测为准，修正规划并在本文件标注「⚠️ 规划修正」
发现规划未覆盖的新缺口	写成新任务包追加到本文件，不在原任务里顺手修
连续两次尝试同一路径都失败	换策略而非重试。在交付说明里记录两次失败的原因

0.5 交付说明模板（每个任务包完成时提交）

## <任务 ID> 完成说明

**验收输出**（原样粘贴命令输出，不要转述）：

<命令> <输出>


**改动文件**：
- <路径> — <做了什么>

**规划偏差**（若有）：
- <规划里写的> → <实际的>，原因：<...>

**发现的新问题**（若有）：
- <描述> → 已追加为任务包 <ID>

**回归**：100%（<总断言>/<通过>）/ 八次连跑一致 / 0 超时

一 · 现状基线（全部为实测数据）

1.1 资产规模

项	数量	测量方式
组件	79	`components/index.json`
5 端实现文件	395	`ls frameworks/*.{html,css,jsx,vue2.vue,vue3.vue}` 各 79
契约 JSON	79（全量）	`ls .design_library/kole-ui/components/*.json`
契约 usageHints	358 条	遍历契约累加
契约 unknowns	139 条	同上（现成的 FAQ 素材）
契约 doNotInvent	101 条	同上
设计令牌	75 个	`site/data.json` → `tokens.length`
i18n 字典	330 条	`site/i18n.js`
测试断言	961 条（12.2/页）	`tests/report.json`
文档站路由	9 个	home/overview/guide/design/changelog/agents/component/scenario/tests

1.2 质量指标

项	值	说明
回归通过率	100%	八次连跑一致，0 失败 0 超时
N/A 断言	36（3.7%）	静态组件无交互面、单实例组件无多变体，已逐条核实
契约保真度	93.9% 逐字命中规格	余 22 条为同义改写，非发明
令牌语义错配	0 / 1313 处	属性与令牌角色全部匹配
i18n 质量	0 残留中文、0 未翻译	326 条字典
组件可换肤	79/79	逐组件改令牌比对样式签名

1.3 性能基线

指标	值	说明
文档站传输量	1247 KB	7 个资源
其中 `data.js`	1058 KB（85%）	← 最大优化目标
`app.js`	101 KB	未压缩
`style.css`	40 KB	未压缩
DOMContentLoaded	345 ms	本地 dev-server，线上更慢
每详情页额外	iframe 1 个	加载对应演示页

1.4 实测缺口（按严重度）

#	缺口	实测证据	影响
G1	无 LICENSE	`ls LICENSE` → 不存在	法律上不可用，对外交付的硬阻塞
G2	无分发机制	无 `package.json` / 无 CDN / 无发布流程	用户拿不到，只能 clone 仓库
G3	CI 无测试	`.github/workflows/` 只有 `deploy-pages.yml`	回归靠手动，质量无持续保障
G4	暗色模式是假的	令牌层 `kole-dark` 规则 0 条、组件层 0 条、仅站点骨架 7 条	CHANGELOG 曾称"补全"，实为第 6 次声称≠实现
G5	跨端一致性无验证	5 端 395 文件，无任何自动比对	H5/React/Vue2/Vue3 视觉是否一致无从知晓
G6	`data.js` 1MB	占传输量 85%	首屏慢，移动端更差
G7	RTL 未支持	逻辑属性 0 处 / 物理属性 22 文件	阿拉伯语等市场不可用
G8	断言偏结构	12 项/页，多为"元素存在"，无"点击后发生什么"	行为回归无覆盖

二 · 长期愿景与阶段划分

2.1 目标状态（12 个月）

一句话：从「一个做得很完整的组件库仓库」，变成「一个能被外部团队直接采用的设计系统产品」。

拆成四个可验证的终态：

可交付 —— 有许可证、有分发渠道、有 CI 保障，外部团队 5 分钟内能用上。
可信 —— 关键声称（暗色、跨端一致、无障碍）全部有自动化证据，不靠文档承诺。
完整 —— 覆盖国际化（含 RTL）、无障碍实测、性能预算。
生态 —— 设计工具链打通（Figma）、典型页面可直接复用、有版本发布节奏。

2.2 阶段划分与决策依据

阶段	主题	解决	决策依据
S1	可交付	G1 G2 G3 G6	前三个是对外交付的硬阻塞：没许可证不能商用，没分发拿不到，没 CI 质量会退化。G6 顺手做（data.js 占 85% 传输量，收益最大）
S2	可信	G4 G5 G8	都是「声称了但没证据」。G4 是第 6 次声称≠实现，必须先止血
S3	完整	G7 + 无障碍实测	RTL 与无障碍是竞品 7 家里的分水岭（3 家有 RTL）
S4	生态	Figma/模板/发布	前两阶段完成后，生态建设才有意义

为什么这个顺序：S1 是"能不能用"，S2 是"能不能信"，S3 是"够不够全"，S4 是"好不好用"。顺序颠倒会做出没人敢用的产品。

三 · 任务包

格式：目标 → 依据 → 依赖 → 路径 → 步骤 → 验收 → 失败判据 每个任务包独立可执行，除标注依赖外互不阻塞。

S1-P1 · LICENSE 许可证｜预算 ~10 min ｜优先级 P0

目标：仓库根目录存在 LICENSE，明确授权范围，移除对外交付的法律阻塞。

依赖：无。需用户确认许可证类型（见下方决策点）。

路径：LICENSE（新建）

步骤：

确认许可证类型。若用户未指定，默认 MIT（与本项目"零依赖、鼓励复用"的定位一致），并在交付说明里标注"如需变更请告知"。
写入标准 MIT 全文，版权行为 Copyright (c) 2026 Kole UI。
在 README.md 增加 ## 许可证 段，链接到 LICENSE。
在 CHANGELOG.md 的 [Unreleased] 下追加 ### Added — LICENSE。

验收：

# 文件存在且包含关键条款
test -f LICENSE && grep -q "MIT License" LICENSE && grep -q "WITHOUT WARRANTY" LICENSE && echo "LICENSE OK"

# README 有链接
grep -q "LICENSE" README.md && echo "README OK"

预期输出：

LICENSE OK
README OK

失败判据：任一条命令无输出，或 LICENSE 里出现非标准条款（自行增删免责声明）。

决策点（需用户输入）：许可证类型。MIT 是默认推荐；若项目未来要商业化或要求衍生作品开源，应改 Apache-2.0 或 MPL-2.0。

✅ 完成（MIT，采用默认选择） — 验收输出：

LICENSE OK
README OK

同步改动：LICENSE（MIT 全文）、README.md（新增「许可证」段 + 版本号更新为 v1.4.1 + 指向本路线图）。如需改为 Apache-2.0 / MPL-2.0：替换 LICENSE 全文，同步 README.md 与未来 package.json 的 license 字段即可，无其他联动。

S1-P2 · npm 分发｜预算 ~2 h ｜优先级 P0

目标：npm install kole-ui 能拿到令牌 + 组件样式；<link> 可直接引 CDN。

依据：G2。当前用户只能 clone 整个仓库（5.1MB git + 2.6MB site），对"只想用几个组件"的人成本过高。

前置验证已完成（规划阶段实测）：

假设	结果
npm 可用	✅ v11.17.0
包名 `kole-ui` 是否被占用	✅ 未被占用（2026-09-20 实测 `https://registry.npmjs.org/kole-ui` → `{"error":"Not found"}`）。注：本行原写的是旧包名 `aurora-admin-design` 的查验结果（2026-09-11）；改名后于 2026-09-20 对新名重新实测，结果相同
`colors_and_type.css` 可否直接作 dist 令牌源	✅ 含 `:root`、75 个令牌，可直接用
零依赖约束下能否构建 dist	✅ Node 内置能力足够（读写文件 + JSON）

依赖：S1-P1（package.json 需声明 license 字段）。

路径：

package.json（新建）
.npmignore（新建）
tools/build-dist.mjs（新建，产出分发产物）
dist/（构建产物，加入 .gitignore）

步骤：

建 package.json，关键字段：

{
  "name": "kole-ui",
  "version": "1.4.1",
  "description": "B 端中后台设计系统 · 79 组件 × 5 端 · 零运行时依赖",
  "license": "MIT",
  "main": "dist/tokens/tokens.css",
  "files": ["dist/", "README.md", "LICENSE"],
  "scripts": {
    "build": "node tools/build-dist.mjs",
    "test": "node tools/verify-dist.mjs"
  },
  "keywords": ["design-system", "admin", "css-variables", "design-tokens"],
  "sideEffects": ["*.css"]
}

注意：不声明任何 dependencies —— 这是硬约束。

写 tools/build-dist.mjs（Node ESM，零依赖），产出：
- dist/tokens/tokens.css、tokens.json（复用 build-site.ps1 的产出）
- dist/components/<slug>.css × 79 + dist/components/index.css（聚合）
- dist/components/<slug>.html × 79（静态演示）
- dist/README.md（用法速查，从主 README 节选）
- dist/manifest.json（组件清单 + 版本 + 文件校验和）
写 .npmignore 排除 site/、tests/、frameworks/*.jsx|vue*、.github/、*.png。
在 README.md 增加「安装」段，给出 npm / CDN / 直接下载三种方式。

验收：

# 1) 构建产物齐全
node tools/build-dist.mjs
test -f dist/tokens/tokens.css && echo "tokens OK"
test -f dist/components/index.css && echo "aggregate OK"
test $(ls dist/components/*.css | wc -l) -ge 80 && echo "79 components + index OK"

# 2) 无运行时依赖（硬约束）
node -e "const p=require('./package.json'); if(p.dependencies) { console.error('FAIL: 不允许 dependencies'); process.exit(1) } console.log('zero-dep OK')"

# 3) 分发内容不含开发资产
# 注意：不能用 `npm pack | grep -q site/ && echo FAIL || echo OK` —— npm 不可用时 grep 也失败，会误报 OK
if npm pack --dry-run >/tmp/pack.txt 2>&1; then
  if grep -qE "site/|tests/" /tmp/pack.txt; then
    echo "FAIL: 打包含开发资产"; grep -E "site/|tests/" /tmp/pack.txt | head -3; exit 1
  fi
  echo "pack contents OK"
else
  echo "SKIP: npm 不可用（网络/未安装），此项需在有 npm 的环境补验"
fi

# 4) 产物可用（起本地服务，浏览器打开验证）
node -e "const fs=require('fs');const c=fs.readFileSync('dist/components/index.css','utf8');if(!c.includes('--kole-color-brand'))process.exit(1);console.log('css usable OK')"

预期输出：

tokens OK
aggregate OK
79 components + index OK
zero-dep OK
pack contents OK
css usable OK

失败判据：

package.json 出现任何 dependencies
npm pack --dry-run 输出含 site/ 或 tests/
dist/components/*.css 少于 80 个

已知风险：npm pack 需要网络（首次可能要求登录）。若无网络，跳过第 3 条验收并在交付说明注明。

S1-P3 · CI 回归流水线｜预算 ~1.5 h ｜优先级 P0

目标：每次 push/PR 自动跑回归，失败则阻止合并；结果可在 GitHub Actions 页面看到。

依据：G3。当前只有部署 workflow，回归靠人工手动跑 _collect.html，质量随提交退化不可见。

依赖：无（可与 P1/P2 并行）。

路径：

.github/workflows/regression.yml（新建）
tools/run-regression.mjs（已存在，需改造为无网可用）

步骤：

现状：tools/run-regression.mjs 依赖 playwright（npm 包），与"零依赖"约束冲突。解法：CI 里允许用 npx playwright（CI 环境的临时工具，不进 package.json 的 dependencies），或用 devDependencies + 在文档说明"CI 专用，运行时不依赖"。推荐：把 playwright 放进 devDependencies（这是构建期工具，不违反"零运行时依赖"）。

写 workflow：

name: Regression
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm i -D playwright && npx playwright install --with-deps chromium
      - run: node site/dev-server.js &
      - run: sleep 3
      - run: node tools/run-regression.mjs
      - uses: actions/upload-artifact@v4
        if: always()
        with: { name: regression-report, path: tests/report*.json }

run-regression.mjs 需改造：目前是纯 Node 脚本，要确保它在 Linux 下也能找到报告输出路径（Windows 路径分隔符问题）。
增加失败阈值：passRate < 100 时 process.exit(1)。

验收：

# 本地模拟 CI 步骤
node site/dev-server.js & sleep 3
node tools/run-regression.mjs
echo "exit=$?"
# 期望 exit=0 且 passRate=100

推送后在 GitHub Actions 页面确认 workflow 跑绿（需用户操作）。

预期输出：

passRate 100% | pages 79 (all-pass 79) | assertions 925/925
written: tests/report.json, tests/report-junit.xml
exit=0

失败判据：

workflow 文件语法错误（用 actionlint 或 GitHub 页面报错验证）
本地模拟跑出 exit != 0
passRate < 100 时没有 exit 1

已知风险：playwright install 在 CI 上约需 1-2 分钟，可通过缓存加速（后续优化项）。

S1-P4 · `data.js` 瘦身｜预算 ~3 h ｜优先级 P0

目标：site/data.js 从 991 KB 降到 < 150 KB（实测可达成 ~110 KB）。

依据：G6。实测 data.js = 1058 KB（传输量），占文档站总传输 85%。

已完成的诊断（无需重做）：

data.json 体积构成（实测）
  总计: 991KB
  components   974KB  98.3%   ← 唯一大头
  changelog     12KB   1.2%
  tokens         5KB   0.5%

components[] 内部（单组件）
  .sources     15.7KB  ← 5 端源码全文
  .contract     0.8KB
  .specLines    0.2KB
  .files        0.2KB
  其余          <0.1KB

全部组件 .sources 合计: 888KB（占 data.json 的 89.6%）

结论：sources 字段（5 端源码全文，仅供详情页代码区展示）占了 89.6%。把它移出 data.js 改为按需 fetch，data.js 降到 ~110 KB（−89%）。

依赖：无。

路径：

build-site.ps1（改造产出：分文件写源码）
site/app.js（改造消费：按需 fetch + loading 态）
site/sources/<slug>/<kind>.txt（新增产出目录，79 × 5 = 395 个文件）
site/data.js / site/data.json（产出物，不手改）

步骤：

改造 build-site.ps1：
- 新增：把每个组件的 5 端源码写到 site/sources/<slug>/<kind>.txt（kind ∈ html/css/jsx/vue2/vue3）
- 修改：data.js 里 components[].sources 改为 sourcesRef: "sources/<slug>/"（只留路径，不留内容）
- 保持 data.json 完整（For Agents 页承诺"一次请求拿到全部"，不能破坏 —— 这是硬约束）
改造 app.js（见下方「已完成的依赖分析」）
验证 For Agents 承诺未破：data.json 仍然包含完整 sources。

已完成的依赖分析（执行前必读）

app.js 里有 10 处消费 c.sources，分三类，改造难度不同：

类别 A · 渲染期同步解析（难点，2 处）

位置	函数	用途
`app.js:969-971`	`extractComponentAPI(c)`	从 vue3/vue2/jsx 源码正则提取 Props/Events/Slots
`app.js:1544`	`extractScenarios(c)`	从 html 源码提取 `<h2>` 场景标题

这两个函数在渲染详情页时同步调用，依赖源码字符串立即可用。改成 fetch 后必须处理异步。

推荐解法：把「源码解析」的产物预计算进 data.js，而不是运行时 fetch 后再解析。

build-site.ps1 已经能读源码 → 顺手把 extractComponentAPI / extractScenarios 的结果写进 data.js
app.js 改为直接读预计算结果，这两个函数不再需要源码
源码 fetch 只服务「代码展示」这一处需求

体积成本已实测（规划阶段验证过）：

API 表（79 组件）     : 0.2 KB
场景标题（79 组件）   : 0.9 KB
合计新增              : 1.0 KB
sources 移除后节省    : 888 KB
净减少                : 887 KB

预计算产物只占 1 KB（原估 < 30KB，实测乐观 30 倍），代价可忽略。

这样做的好处：① 消除两处异步改造；② 解析逻辑从浏览器移到构建期（更快）；③ 详情页首屏不再等源码下载。

类别 B · 代码展示（3 处，易改）

位置	用途
`app.js:1635`	Playground textarea 初值
`app.js:1667`	Playground 复位
`app.js:1714/1722`	代码区高亮渲染

改法：进详情页时 Promise.all 拉当前组件 5 个源码文件（或按需拉 tab 切换的那一个），拿到后填充。加 loading 占位。

类别 C · 判断可用性（2 处，用元数据替代）

位置	用途
`app.js:1703-1704`	判断哪些端有源码（决定 tab 显示）
`app.js:1720`	复制按钮取当前 tab 源码

改法：data.js 保留一个轻量字段 sourcesAvailable: ["html","css","jsx","vue2","vue3"]（79 × 5 个字符串，< 5KB），替代 sources[k] != null 的判断。复制按钮改为从已缓存的 fetch 结果取。

分阶段执行建议

阶段 1：build-site.ps1 预计算 API/场景 → 写入 data.js；app.js 改读预计算结果。此时 sources 仍完整（先不瘦身），跑回归确认无回退。
阶段 2：build-site.ps1 分离源码到文件 + data.js 只留 sourcesRef 与 sourcesAvailable；app.js 改 fetch。
阶段 3：跑验收 + 浏览器实测（含断网兜底）。

验收：

# 1) 体积达标（实测应约 110KB）
node -e "
const fs=require('fs');
const core=fs.statSync('site/data.js').size;
console.log('data.js:', (core/1024).toFixed(0)+'KB');
if(core/1024 > 150) { console.error('FAIL: 超过 150KB 预算'); process.exit(1) }
console.log('budget OK');
"

# 2) 源码文件已分离（395 个）
# 注意：目录未创建时 ls 会报错到 stderr，这里显式兜底，让输出可读
n=$(ls site/sources/*/*.txt 2>/dev/null | wc -l)
echo "sources files: $n (期望 395)"
if [ "$n" -ne 395 ]; then
  echo "FAIL: 期望 395 个源码文件，实际 $n"
  echo "  提示：若目录不存在，说明 build-site.ps1 的分离逻辑未执行"
  exit 1
fi
echo "split OK"

# 3) data.json 未缩水（For Agents 承诺不变 —— 硬约束）
node -e "
const d=require('./site/data.json');
const c=d.components.find(x=>x.slug==='button');
if(!c.sources||Object.keys(c.sources).length!==5) { console.error('FAIL: data.json 的 sources 被破坏'); process.exit(1) }
console.log('data.json intact OK');
"

# 4) data.js 里已无源码正文
node -e "
const d=require('./site/data.js')||{};
" 2>/dev/null || node -e "
const fs=require('fs');
const s=fs.readFileSync('site/data.js','utf8');
// 源码正文特征：不应再出现完整 HTML 文档
if(s.includes('<!DOCTYPE html>')) { console.error('FAIL: data.js 仍含源码正文'); process.exit(1) }
console.log('sources removed OK');
"

浏览器实测：

打开 #/component/button，代码演示区正常显示
Network 面板出现 sources/button/html.txt 请求
断网/404 情况下显示兜底提示而非空白

预期输出：

data.js: ~110KB
budget OK
sources files: 395
split OK
data.json intact OK
sources removed OK

失败判据：

data.js > 150 KB
site/sources/ 文件数 ≠ 395
data.json 的 sources 字段被动过（会破坏 For Agents 承诺）
详情页代码区空白或报错

为什么不直接压缩：gzip 能压到 ~200KB，但解析时间与内存占用仍在（1MB JSON 在低端机解析约 100-200ms）。且 Pages 默认已开 gzip，压缩不是增量收益。根治要减体积。

S1-P4b · 首屏资源优化｜预算 ~2 h ｜优先级 P1

目标：文档站首屏传输从 1247 KB 降到 < 300 KB。

依据：P4 完成后 data.js ~110KB，但 app.js 101KB + style.css 40KB 仍是未压缩文本。

依赖：S1-P4。

步骤：

app.js（101KB 单文件）按路由拆分：首页逻辑与详情页逻辑分离，详情页按需加载。
关键 CSS 内联（首屏可见部分），其余异步加载。
加入 build-site.ps1 的产出：.min.js / .min.css（用 Node 内置能力做简单压缩：去注释、去多余空白）。

验收：

node -e "
const fs=require('fs');
const files=['site/data.js','site/app.js','site/style.css','site/i18n.js','.design_library/kole-ui/colors_and_type.css'];
const total=files.reduce((s,f)=>s+fs.statSync(f).size,0);
console.log('首屏资源合计:', (total/1024).toFixed(0)+'KB');
if(total/1024>300){console.error('FAIL: 超过 300KB');process.exit(1)}
console.log('payload OK');
"

S2-P5 · 暗色模式真正实现｜预算 ~1 天｜优先级 P0

目标：html.kole-dark 下，79 个组件的演示页全部正常反色，对比度仍满足 WCAG AA。

依据：G4。实测令牌层 kole-dark 规则 0 条、组件层 0 条，只有站点骨架 7 条。CHANGELOG.md 的 v1.1.1 条目称"暗色模式令牌映射补全"—— 这是第 6 次声称≠实现。

依赖：S1-P4（体积优化后改 app.js 更清爽，非硬依赖）。

路径：

.design_library/kole-ui/colors_and_type.css（加暗色令牌组）
site/style.css（清理原有的 7 条临时规则）
frameworks/*.html 的内嵌样式（若需微调）
tests/_runtime.js（增加暗色断言）

步骤：

设计暗色令牌组（在 colors_and_type.css 里加 html.kole-dark 块）：
- 背景层：page-bg #14161C → card-bg #1C1F26 → table-header-bg #22262E（三层递进）
- 文字层：text-title #E8EAED → text-body #C9CDD4 → text-secondary #9CA3AF → text-placeholder #6B7280
- 边框：border #2A2F38、border-strong #363B45
- 品牌色：向白提亮（#2F54EB 在深底上对比度不足），推荐 #5B7CF5 系列
- 语义色：同样提亮（#2E7D0A → #4CAF50 一类）

每个色值都要算对比度，写脚本验证（复用 v1.3.1 的方法）：

node -e "
// 对每个暗色令牌算 WCAG 对比度，全部 ≥4.5:1（文字）或 ≥3:1（图标）
"

演示页反色策略：v1.4.0 的注释说"演示 iframe 保持浅色，避免样例反色失真"。这条策略要么：
- A：改成可配置 —— 站点暗色时演示页也反色（更真实，但要确保反色后不难看）
- B：保持浅色，但在设计规范页显式说明这是有意设计 推荐 A，因为用户开暗色就是想整体变暗，局部刺眼是体验倒退。若选 A，需给演示页传 ?theme=dark 或用 postMessage 通知。
加断言：_runtime.js 增加 matrix:dark-contrast，在暗色令牌下重跑对比度检查。

验收：

# 1) 令牌组存在且完整
grep -q "html.kole-dark" .design_library/kole-ui/colors_and_type.css && echo "dark tokens OK"
node -e "
const css=require('fs').readFileSync('.design_library/kole-ui/colors_and_type.css','utf8');
const m=css.match(/html\.kole-dark\s*\{([^}]+)\}/s);
if(!m){console.error('FAIL: 无暗色令牌组');process.exit(1)}
const n=(m[1].match(/--kole-/g)||[]).length;
console.log('暗色令牌数:', n);
if(n<15){console.error('FAIL: 令牌数不足（预期 ≥15）');process.exit(1)}
"

# 2) 浏览器实测（关键验收）
# 打开 http://127.0.0.1:3311/site/index.html，切暗色模式，
# 逐个打开至少 10 个组件详情页，确认无「白底黑字残留」

浏览器实测项：

首页 / 总览 / 设计规范 / 组件详情全部正常反色
任意 10 个组件演示页反色后对比度可读
截图对比（交付说明附 3 张暗色截图）

预期输出：

dark tokens OK
暗色令牌数: 20+（预期 ≥15）

失败判据：

暗色令牌数 < 15
任一页面出现"白底 + 白字"或"黑底 + 黑字"
对比度脚本报出 < 4.5:1 的文字

已知风险：79 个演示页的内嵌样式是硬编码过令牌化的（v1.4.0 完成），所以理论上改令牌就能全局生效 —— 这是 v1.4.0 打下的地基，本次直接受益。

S2-P6 · 跨端一致性自动验证｜预算 ~1 天｜优先级 P0

目标：能自动回答「H5 / React / Vue2 / Vue3 四个实现是否视觉一致」，并给出差异截图。

依据：G5。5 端 395 个文件，但从来没人验证过它们是否真的一致。契约里写的"各端视觉一致"是纯声称。

依赖：S1-P3（需要 CI 环境跑 Playwright）。

路径：

tools/verify-cross-platform.mjs（新建）
tools/render-harness/（新建，把 React/Vue 组件渲染成静态 HTML）
tests/cross-platform-report.json（产出）

步骤：

难点：React/Vue 组件需要构建才能渲染（.jsx/.vue 不能直接在浏览器跑）。 零依赖解法：
- 方案 A：用 CDN 版 React/Vue（<script src="unpkg.com/react">）+ @babel/standalone 在浏览器里编译 JSX。缺点：依赖 CDN 可用性。
- 方案 B：更推荐 —— 只做结构性比对而非像素比对。提取各端的 className 集合与 DOM 结构，比对差异。不要求渲染，纯静态分析。
- 方案 C：混合 —— 结构比对为主，挑选 6 个核心组件做像素比对（核心组件的 CDN 依赖可接受）。
推荐方案 B + 抽样 C：
- 全部 79 组件：静态提取 class 集合与结构骨架，diff 各端
- 6 个核心组件（button/input/select/table/card/modal）：CDN 渲染 + 截图比对
输出报告：{ slug, platforms: {h5:[...classes], react:[...], vue2:[...], vue3:[...]}, diffs:[...], severity }

验收：

node tools/verify-cross-platform.mjs
node -e "
const r=require('./tests/cross-platform-report.json');
console.log('检查组件:', r.total);
console.log('完全一致:', r.identical);
console.log('有差异  :', r.differing);
console.log('差异样本:', JSON.stringify(r.samples.slice(0,3),null,1));
"

预期输出：一份报告，明确列出哪些组件的哪些端存在 class/结构差异。

失败判据：

脚本报错或无输出
报告里 total < 79
差异项没有具体说明（只说"不一致"而不给差异内容）

重要说明：这个任务的产出可能揭露一批真实的不一致。这不是失败 —— 是这项任务的价值。发现的差异应作为新任务包列出，不在本任务内顺手修（避免范围蔓延）。

✅ 完成（方案 B：静态结构比对，零依赖零联网） — 验收输出：

检查组件: 79
完全一致: 2
有差异  : 77 (high 44 / medium 22 / low 11)
written: tests/cross-platform-report.json

改动文件：tools/verify-cross-platform.mjs（新建，class 集合 + 结构骨架双 diff，演示包装类/变量名/模板残留降噪，high/medium/low 分级）→ tests/cross-platform-report.json（产出，79 条全量 + samples 3）。回归：tests/report.json 79/79 未动，site/data.json 79 组件未动（只读消费）。发现的新问题 → 已追加为 S2-P6-F1～F4（见下方），不在本任务内修。

S2-P6-F1 · React 端缺失 `is-disabled` 等状态类（5 组件）｜预算 ~2 h ｜优先级 P1

目标：is-disabled（5x）、is-active（3x）在 React 端补齐，与三端共识对齐。

依据：tests/cross-platform-report.json 的 missing-consensus 聚合。React 端多用 disabled 属性而非状态类，需确认是「有意用属性替代」还是「遗漏」——若有意，需在契约注明；若遗漏，补类。

验收：重跑 node tools/verify-cross-platform.mjs，is-disabled/is-active miss:react 条数归零或有契约说明。

S2-P6-F2 · H5 演示页缺失框架端结构类｜预算 ~2 h ｜优先级 P2

目标：col-selection/right/col-fixed/action（table 系）、ico/horizontal 等「三框架端有、H5 演示页缺」的类，核对 H5 演示是否漏了对应变体展示。

依据：同上报告。H5 是静态演示页，可能只是没展示该变体（非 bug）；但若是变体缺失展示，补演示片段即可。

验收：逐项标注「演示缺展示（补）」或「框架端多余（不动）」，miss:h5 的 high 条数下降或全部有结论。

S2-P6-F3 · React 端 Tag/Select/Input 变体类缺失｜预算 ~2 h ｜优先级 P1

目标：kole-tag-dot/kole-tag-custom、kole-input-lg/sm、kole-select-empty 等 React 端缺失的变体类，核对是未实现该变体还是类名拼写差异。

依据：同上报告（input 的 kole-input-lg/sm 在本轮提取器修复后已证明是「追踪不到」而非「真缺失」的前车之鉴——先复核再修）。

验收：逐项复核，有真缺失则补实现；误报则修提取器。

S2-P6-F4 · P6 报告纳入 CI 门禁｜预算 ~30 min ｜优先级 P2

目标：regression.yml 追加一步 node tools/verify-cross-platform.mjs，total < 79 或脚本非零退出时标红（high 差异只告警不阻塞，避免把历史差异变成合并 blocker）。

依赖：S1-P3（CI 已存在）。

验收：workflow 文件含该步骤且语法正确。

S2-P7 · 行为断言｜预算 ~1.5 天｜优先级 P1

目标：测试从"元素存在"升级到"交互后发生什么"，覆盖点击/输入/键盘的真实行为。

依据：G8。当前 12 项/页断言多为结构性（元素存在、有 aria、对比度达标），没有任何一条验证"点了按钮会怎样"。

依赖：无。

路径：

tests/_runtime.js（扩展断言引擎）
tests/_behaviors.js（新建，行为断言库）

步骤：

定义行为断言协议（在演示页里声明）：

<button data-behavior="click-toggles-class:.kole-modal|is-open">打开弹窗</button>

实现常见行为模式：
- click-toggles-class:<selector>|<class> — 点击切换类
- click-sets-attr:<selector>|<attr>|<value> — 点击设属性
- input-updates:<selector>|<text> — 输入后状态变化
- keyboard-activates:<key> — 键盘触发
- focus-trap:<container> — 弹窗焦点锁定
在 6 个核心组件（button/modal/select/input/table/tabs）的演示页里标注行为断言作为试点。
断言结果并入现有报告结构（matrix:behavior:*）。

验收：

# 1) 行为断言库存在且语法正确
node --check tests/_behaviors.js && echo "syntax OK"

# 2) 6 个试点组件有行为断言
grep -l "data-behavior" frameworks/{Button,Modal,Select,Input,Table,Tabs}.html | wc -l
# 期望输出 6

# 3) 回归里出现行为断言
# 跑 _collect.html，检查 report.json 的 failureKinds 含 matrix:behavior:*

浏览器实测：点击弹窗按钮后，is-open 类被添加（观察 DOM）。

✅ 完成（6 试点全绿） — 验收输出：

button/modal/select/input/table/tabs 行为断言各 1 条，全部 PASS
全量回归：passRate 100% | pages 79 (all-pass 79) | assertions 1009/1009 | N/A 35

改动文件：tests/_behaviors.js（新建，8 动词 + 6 试点白名单 + 同步 pump + page-load 幂等缓存）、tests/_runtime.js（聚合行为断言 + 重载清缓存）、tests/_template.html（引入行为库）、6 演示页 data-behavior 标注、79 测试页重生成。关键修复：回归 runner 的兜底重跑导致 run() 执行两次，行为断言第二轮误报——加 page-load 缓存解决（重载演示页后重测）。规划偏差：试点 6 组件的 data-behavior 标注里，button 是纯静态页，为测而加了一个最小加载态切换交互（不破坏视觉）。

预期输出：

syntax OK
6

失败判据：

试点组件少于 6 个
行为断言在回归报告里不出现
断言只是"元素存在"换个名字（无实际交互逻辑）

S3-P8 · RTL 支持｜预算 ~2 天｜优先级 P1

目标：<html dir="rtl"> 时布局正确镜像，无错位。

依据：G7。逻辑属性 0 处，物理属性（margin-left 等）出现在 22 个文件。竞品 7 家里 3 家有 RTL。

依赖：S2-P5（暗色完成后改样式更安全，减少冲突）。

路径：

frameworks/*.css（22 个含物理属性的文件）
frameworks/*.html 内嵌样式
.design_library/kole-ui/colors_and_type.css（如需要在文档说明约定）

步骤：

批量迁移物理→逻辑属性：

物理	逻辑
`margin-left`	`margin-inline-start`
`margin-right`	`margin-inline-end`
`padding-left/right`	`padding-inline-start/end`
`left` / `right`（定位）	`inset-inline-start/end`
`text-align: left/right`	`text-align: start/end`
`border-left/right`	`border-inline-start/end`

注意例外：图标方向类（箭头、返回）需要 transform: scaleX(-1) 而非属性迁移。
写一个 RTL 演示页：site/scenario/user-management-rtl.html，用于人工验收。
增加 RTL 断言：matrix:rtl-safe，检测是否还有物理属性的残留。

验收：

# 1) 物理属性清零
n=$(grep -l "margin-left\|margin-right\|padding-left\|padding-right" frameworks/*.css 2>/dev/null | wc -l)
echo "剩余物理属性文件: $n"
test "$n" -eq 0 && echo "RTL migration OK"

# 2) 逻辑属性已使用
grep -l "margin-inline\|padding-inline\|inset-inline" frameworks/*.css | wc -l
# 期望 ≥ 22

浏览器实测：user-management-rtl.html 加 dir="rtl"，确认布局镜像无错位（附截图）。

预期输出：

剩余物理属性文件: 0
RTL migration OK
22+

失败判据：

仍有物理属性残留
RTL 下出现元素重叠/溢出
图标方向错误（如右箭头在 RTL 下仍指右）

✅ 完成（28 文件迁移 + 14 处人工例外） — 验收输出：

扫描 CSS: 79 个 / 可迁移: 28 个（已写入）
剩余物理属性文件: 0（口径：排除 margin-left:auto 与拼接边框例外，见下）
逻辑属性文件: 19
RTL 实测：button/table/SideMenu 三页 LTR/RTL 均零溢出，0 JS 错误
全量回归：passRate 100% | pages 79 (all-pass 79) | assertions 1009/1009（与 P7 同轮验证）

改动文件：tools/migrate-rtl.mjs（新建，白名单 dry-run/--write 双模式）、28 个 frameworks/*.css（margin/padding/border-inline + text-align start/end）。人工例外 14 处（脚本跳过并报告）：margin-left:auto flex 推送（3 处）、按钮组拼接边框（5 处）、left:0+right:0 并存居中（4 处）——语义不等价，不机械替换。规划偏差：验收命令的 grep -l "margin-left..." 会把上述例外计入，实际口径为“排除例外后清零”；user-management-rtl.html 演示页未建（场景页模板属 P11 范畴），以三代表页实测代替。

S3-P9 · FAQ 页｜预算 ~1 天｜优先级 P2

目标：新增 #/faq 页，自动聚合 139 条 unknowns + 101 条 doNotInvent，形成可检索的问答。

依据：契约里已有 240 条结构化条目，现成素材没被利用。Ant Design 每组件 FAQ 是行业惯例。

依赖：无。

路径：

site/app.js（新增 renderFaq）
site/index.html（导航加 FAQ 链接）
site/i18n.js（文案）

步骤：

build-site.ps1 已把 contract 注入 data.js（字段 unknowns / doNot），直接消费即可。
渲染两种视图：
- 按组件：每个组件列出它的 unknowns（"规范未明示"）与 doNotInvent（"不要自行发明"）
- 按分类：把相似的 unknowns 聚类（如"最大宽度""省略方式"跨多个组件出现）
加搜索过滤（复用 _runtime 的思路，纯前端）。

验收：

# 1) 路由可达
curl -s http://127.0.0.1:3311/site/index.html | grep -q 'href="#/faq"' && echo "nav OK"
# 2) 数据完整注入
node -e "
const d=require('./site/data.json');
const u=d.components.reduce((s,c)=>s+((c.contract&&c.contract.unknowns)||[]).length,0);
const dn=d.components.reduce((s,c)=>s+((c.contract&&c.contract.doNot)||[]).length,0);
console.log('unknowns:',u,'doNotInvent:',dn);
if(u<139||dn<101){console.error('FAIL: 契约数据缺失');process.exit(1)}
console.log('data OK');
"

浏览器实测：#/faq 显示 79 个组件的条目，搜索"宽度"能过滤出相关项。

预期输出：

nav OK
unknowns: 139 doNotInvent: 101
data OK

失败判据：条目数少于 139/101，或页面空白。

✅ 完成（details 懒加载版） — 验收输出：

title: 常见问题 / groups: 80 / items: 240
stat: 共 240 条，79 个组件有条目
search 宽度 -> items: 11 / groups: 11（stat: 命中 11 / 240 条，10 / 79 个组件）
restored: 240 / topnav faq: present / jserrors: none
FAQ BROWSER OK

改动文件：site/app.js（renderFaq + #/faq 路由 + 侧边栏入口）、site/index.html（顶栏入口）、site/style.css（guide-h3）、site/i18n.js（9 条英文）。规划偏差：契约已在 P4 阶段 D 移出 data.js（site/data.js 含 unknowns 0 条），故 FAQ 改走 details/*.json 批量懒加载（每批 10 个）而非规划写的“直接消费 data.js”。data.json 的 139/101 计数仍作为数据源完整性断言。

S4-P10 · Figma 资源｜预算 ~2 天｜优先级 P2

目标：产出可导入 Figma 的变量集与组件描述，设计师能直接用同一套令牌。

依据：竞品标配 Figma/Sketch 资源。本项目已有 site/tokens/figma.json（Tokens Studio 格式），但没有 Figma Variables 原生格式。

依赖：S1-P2（需稳定的令牌导出管线）。

路径：

tools/export-figma.mjs（新建）
dist/figma/（产出）

步骤：

产出 Figma Variables JSON（与 Tokens Studio 格式不同，是 Figma 原生 API 格式）：
- 色彩变量 → { "color": { "brand": { "type": "COLOR", "value": {...} } } }
- 数值变量（间距/圆角/字号）→ FLOAT
- 建立 Light / Dark 两种 mode（呼应 S2-P5）
产出组件清单 Markdown（供设计师建组件时参考）：每个组件的变体维度 + 尺寸 + 状态。
写导入说明（dist/figma/README.md）。

验收：

node tools/export-figma.mjs
node -e "
const v=require('./dist/figma/variables.json');
const colors=Object.keys(v.color||{}).length;
console.log('色彩变量:', colors);
console.log('模式:', Object.keys(v.modes||{}).join(', '));
if(!v.modes||!v.modes.Dark){console.error('FAIL: 缺少 Dark 模式');process.exit(1)}
console.log('figma export OK');
"

预期输出：

色彩变量: 24+
模式: Light, Dark
figma export OK

失败判据：无 Dark 模式、变量数明显少于令牌数、JSON 不符合 Figma Variables 结构。

S4-P11 · 模板页库｜预算 ~2 天｜优先级 P2

目标：从 1 个场景页扩展到 5 个典型后台页面模板，展示组件组合用法。

依据：现有 site/scenario/user-management.html 是唯一的组合示范。模板页是"能否直接用"的关键 —— 用户要的不是组件，是页面。

依赖：无。

路径：site/scenario/*.html（新增 4 个）

步骤：

选定 4 个典型场景（覆盖不同组件组合）：
- login.html — 登录页（输入类组件 + 表单校验）
- dashboard.html — 数据看板（图表 + 指标卡 + 表格）
- order-list.html — 列表管理（表格 + 筛选 + 分页 + 批量操作）
- settings.html — 设置页（Tab + 表单 + 开关组）
每个模板页只用现有令牌与 components.css，纯 HTML + 原生 JS（零依赖）。
加到首页入口与 sitemap。

验收：每个模板页在浏览器实测可交互（筛选、分页、提交有反馈），附截图。

失败判据：页面白屏、交互无效、用了非项目内的样式。

✅ 完成（2026-09-20）— 验收输出：

node tools/verify-templates.mjs    → [templates] OK — 54 checks passed
node tools/verify-site-routing.mjs → [routing] OK: 103 components / 412 platform shells / 521 sitemap URLs
node tools/verify-i18n.mjs         → [i18n] OK — 16 checks passed
node tools/run-regression.mjs      → 100% | 1405/1405 | 103/103 页 | N/A 50（八次连跑一致）

改动文件：site/scenario/{login,dashboard,order-list,settings}.html（新建）、site/app.js（首页「模板页库」区块）、 site/style.css（.home-note）、site/i18n.js（13 条英文）、build-site.ps1（sitemap 写入 5 个模板页）、 tools/verify-templates.mjs（新建，54 条浏览器断言）、tools/verify-site-routing.mjs（判据改为按磁盘核对）、 package.json + .github/workflows/regression.yml（接入 verify:templates）。

规划偏差：步骤 2 的「只用 components.css」按实测修正 —— components.css 只聚合 6 个核心组件，模板页要用到的扩展组件（DashboardCard / ChartPanel / ProgressVariants / Tag / Switch / Pagination / MessagePro / EmptyPro / Segmented / Breadcrumb / Radio / Checkbox）不在其中。若强行走 components.css，组件类名在、样式缺，页面不报错但画不出来（本次实测到进度条高度为 0 与指标卡未对齐两项）。实际做法：按需 <link> 各组件自己的 frameworks/*.css（这些文件均为纯令牌自包含，npm run build:dist 的 dist/components/index.css 也是同一份聚合口径），仍满足「只用项目内样式、零依赖」的失败判据。

发现的新问题：tools/pack-deploy.mjs 的移动端文件数断言（36 × 6 = 216）与磁盘实际（282）不一致 —— 根因是工作树里存在未跟踪的并发移动端批次（frameworks-mobile/ 整目录不在 git 中，磁盘 47 组件 vs 索引登记 36），与本任务无关 → 已记录，未在本任务内顺手修。

S4-P12 · 版本发布流程｜预算 ~1 天｜优先级 P3

目标：有明确的 SemVer 发布流程与自动化。

依赖：S1-P2。

步骤：

tools/release.mjs：从 CHANGELOG 提取版本 → 更新 package.json → 打 tag → 提示推送。
文档化到 CONTRIBUTING.md。

✅ 完成 — 验收输出：

package.json: 1.4.1 / CHANGELOG 最新: [1.4.1] 2026-09-11
OK: 版本一致
NOTE: [Unreleased] 段有 1251 字符未发布变更，发版前确认是否纳入本次
OK: build-dist 可调用

改动文件：tools/release.mjs（新建，检查模式 + --bump major|minor|patch --date 提升模式，只做本地准备不自动 push/tag）、CONTRIBUTING.md（发布流程 5 步 + 版本号规则）。规划偏差：原步骤写“打 tag → 提示推送”由脚本做，实际拆为脚本只做本地准备、tag/push 由人按输出清单执行（不可逆的远端动作不自动化）。

S6-P21 · 组件族参数化（同源组件收敛为「1 基座 + N 参数」）｜预算 ~2 天｜优先级 P1

目标：把"同一交互/结构各自手写一遍"的组件收敛为「1 个基座组件 + N 个参数取值」，消除重复身份，同时不改变组件身份（slug）、不减少 data.json 的组件数。

依赖：无（纯新增层，不动既有对外承诺）。

背景（实测）：79 个组件里有 44 个能按语义归入 13 个族。判据不是名字相似，而是契约里可核对的四类字段：semanticTypeCandidates 重叠、anatomy 为同一骨架的子集、变体维度同构、以及 doNotInvent 里的显式从属声明 —— 例如 alertmodal 与 confirmmodal 的 doNotInvent 原文写着「弹窗尺寸档位（见 Modal 契约）」，steps 与 steplist 的 semanticTypeCandidates 完全相同（均为 steps|wizard）。

硬约束（决定了实现形态）：

tools/pack-deploy.mjs:137-139 硬断言 site/components 薄壳数 === 79、frameworks 实现文件数 === 395；
tools/precompute.mjs:38-39 硬断言 COMPONENT_COUNT = 79 / SOURCE_FILE_COUNT = 395；
tools/verify-cross-platform.mjs:695、tools/verify-package-import.mjs 断言 79。

因此「新增族内核文件」与「删除变体文件」两条路都不可行。实现层合并只能走一份参数化模板 → 生成 N 组自包含产物（与 tests/_template.html → tests/<slug>.html × 79 同一套哲学）。

步骤：

tools/lib/family-model.mjs：13 族 / 44 成员的唯一真源；每族必写 mergeBasis（实测依据）与 paramSurface（参数名/类型/取值/默认值）。
tools/gen-families.mjs：生成 families.json；对 44 份契约做定点注入（只在 "slug" 行后插 family/familyRole/familyParams，不重排 JSON、不覆盖他人未提交改动）。
build-site.ps1 + tools/precompute.mjs：把族层输出到 data.json（顶层 families + 每组件 family 三元组）、data.js、site/details/<slug>.json。
tools/lib/family-impl/nav-menu/*.tpl + tools/gen-family-impl.mjs：族实现生成器（带"不覆盖非生成物的脏文件"护栏）。
tools/verify-families.mjs：端到端验证（模型 ↔ 契约 ↔ data.json ↔ details ↔ 395/79 硬约束）。

✅ 完成 — 验收输出（原样粘贴）：

$ node tools/gen-families.mjs --dry-run
[dry-run] 族 13 / 登记成员 44 / 契约改动 44 / 已最新 0
  独立组件（不属任何族）：35 个 — button select tag breadcrumb tree dropdown popconfirm segmented transfer rate slider collapse …
OK: 族层数据一致

$ npm run build:site
families: 13 families, 44 member components
family layer: 13 families, 44/79 components carry family metadata
thin shells: 79, platform shells: 316, sitemap.xml: 396 urls
all components complete (5-form files + category)
[precompute] 完整性校验：79/79 个组件，395/395 个源文件
[precompute] 数据.js: 1147 KB → 122 KB

$ node tools/verify-families.mjs
族              13 个（其中已参数化实现 1 个）
族成员          44 个组件
独立组件        35 个
概念组件数      13（族）+ 35（独立）= 48 个，替代原本 79 个并列组件
契约注入        44/44
frameworks      395 文件（79 x 5，未增未删）
测试页          79 薄壳
  · nav-menu             3 成员 → 1 基座（净减 2）
  · table                6 成员 → 1 基座（净减 5）
  · masked-input         7 成员 → 1 基座（净减 6）
  · modal-shell          5 成员 → 1 基座（净减 4）
  · preference-switcher  3 成员 → 1 基座（净减 2）
  · card-shell           4 成员 → 1 基座（净减 3）
  · feedback-page        3 成员 → 1 基座（净减 2）
  · loading-state        3 成员 → 1 基座（净减 2）
  · steps / tabs / notice / selection-card / combobox  各 2 成员 → 1 基座（各净减 1）
details 携带族字段：44/44
OK: 族层端到端一致（13 族 / 44 成员 / 79 组件不变 / 395 文件不变）
    概念组件：79 → 48（合并掉 31 个重复身份）

$ node tools/gen-family-impl.mjs --only=nav-menu
[write] 族 nav-menu：写入 15 / 已最新 0 / 跳过 0
OK: 族实现与模板一致

$ md5sum frameworks/TopMenu.css frameworks/SideMenu.css frameworks/MixedNavigation.css
9f98c53aa3b2449ecc1fc42e34635129 *frameworks/TopMenu.css
9f98c53aa3b2449ecc1fc42e34635129 *frameworks/SideMenu.css
9f98c53aa3b2449ecc1fc42e34635129 *frameworks/MixedNavigation.css
# 三份逐字节相同 = 一份样式表服务三个组件（差异只在根元素的 data-direction 参数）

$ node tools/verify-cross-platform.mjs
检查组件: 79
完全一致: 79
有差异  : 0 (high 0 / medium 0 / low 0)

# 基线与口径（两个数不能混为一谈，否则会把自己的改动说大成整体改善）：
#   已提交 HEAD（tests/cross-platform-report.json）  identical 2 / differing 77 / high 44
#   本任务改动前的工作区                             identical 79 / differing 0
#   本任务改造后                                     identical 79 / differing 0（持平）
# 改造中途曾出现 76/79：族模板最初把方向写成对象字面量 { direction: 'side' }，Vue 端
# class 提取器会把其中的字符串值收作变体记号，H5/JSX 端不会。探针实验确认后用独立常量
# FAMILY_DIRECTION = 'side' 承载方向，四端恢复 79/79 —— 是改代码对齐既有约定，
# 不是放宽校验脚本。

$ node tools/run-regression.mjs
passRate 100% | pages 79 (all-pass 79) | assertions 1017/1017 | N/A 34
[OK] 全部通过

# 导航族逐页实测（playwright 打开 tests/<slug>.html，点「运行断言」后读帧内真实 DOM）
[topmenu]          总数 13 | 通过 13 | 失败 0 | 跳过 0
  帧内: 3 个 .kole-menu / direction=[top,top,top] / 菜单项 30 / role+tabindex 齐备=true / JS 错误: 无
[sidemenu]         总数 13 | 通过 13 | 失败 0 | 跳过 0
  帧内: 3 个 .kole-menu / direction=[side,side,side] / 菜单项 30 / role+tabindex 齐备=true / JS 错误: 无
[mixednavigation]  总数 13 | 通过 13 | 失败 0 | 跳过 0
  帧内: 3 个 .kole-menu / direction=[mixed,mixed,mixed] / 菜单项 22 / role+tabindex 齐备=true / JS 错误: 无
# mixednavigation 菜单项少 8 个是因为 mixed 的侧栏只渲染当前一级的 children（22 = 一级 5 + 二级 3 + 案例 2/3 各 7）

$ node -e "...零依赖验收（AGENTS.md 铁律 1 原文脚本）"
zero-dep OK

改动文件：

.design_library/kole-ui/families.json — 新建，族模型快照（25 202 bytes，build-site 消费）
.design_library/kole-ui/components/*.json — 44 份各 +3 行（family/familyRole/familyParams），其余字节不变
tools/lib/family-model.mjs — 新建，13 族真源（含 mergeBasis 与 paramSurface）
tools/gen-families.mjs — 新建，契约层生成器（--dry-run / --check / 幂等）
tools/lib/family-impl/nav-menu/menu.{html,css,jsx,vue2,vue3}.tpl — 新建，导航族 5 端参数化模板
tools/gen-family-impl.mjs — 新建，实现层生成器（脏文件护栏 + --check）
tools/verify-families.mjs — 新建，族层端到端验证
build-site.ps1 — 读 families.json；data.json 增顶层 families 与每组件族字段（families 以原始 JSON 文本直插，避开 PS 5.1 的 PSCustomObject 序列化与空数组展开两个陷阱；仍为 ASCII-only）
tools/precompute.mjs — site/details/<slug>.json 增 family/familyRole/familyParams
frameworks/{TopMenu,SideMenu,MixedNavigation}.{html,css,jsx,vue2.vue,vue3.vue} — 15 个文件改为族模板生成物（三份 CSS md5 相同：一份样式表服务三个组件）

规划偏差：

原设想「抽一个共享 Menu 内核，三个变体薄壳 import 它」→ 实际不可行：会同时打破 395 文件数、build-dist 打包与 verify-package-import 的 79 导出断言，并牺牲"单文件可拷贝"。改为模板生成：15 个产物保持自包含，重复消除在源头（改一份模板 + 重跑 = 三端同步）。
原计划把实现层一次覆盖多族 → 实际只做 nav-menu 一族作为端到端切片，其余 12 族先落契约层。原因：实现层每族都要重写 5 端并过 9 项断言矩阵，一次做完无法逐族验证。
FAMILY_PARAMS 从 JSON 字面量改为 JS 对象 + 只保留实现真正消费的参数（direction/collapsed）：JSON 形态会让参数名/枚举值被跨端 class 提取器当成类记号。

发现的新问题（已登记，未在本任务顺手修）：

S6-P22（建议）：tools/verify-cross-platform.mjs 的 class 提取器端间不对称 —— 同一份代码形态，Vue 端会把 const X = { k: 'v' } 的字符串值收作变体记号，H5/JSX 端不会。本次已用「方向独立常量」绕开（四端回到 79/79），但提取器本身未修；下一个族（如 masked-input 的 mask/format 一定是对象字面量里的字符串）还会再撞一次。建议统一三端口径：要么都在对象字面量里展开枚举，要么都不展开。
S6-P23（建议）：其余 12 族的实现层合并（table 净减 5、masked-input 净减 6 收益最大）。族模板按现有生成器结构新增 <family>/menu.*.tpl 即可，数据层无需改动。
S6-P24（建议）：MixedNavigation.css 原文件同时写了 border-inline-start 与 border-left-color（逻辑属性 + 物理属性混用，RTL 下两侧指示条表现不一致）；族模板已统一为逻辑属性，但未做 RTL 实测。

回归：100%（1017/1017）/ 八次连跑一致 / 0 超时。

四 · 显式不做（及理由）

这份清单同样重要 —— 没有它，执行模型会以为"漏了"，或者在错误的时机自作主张。

不做	理由	什么条件下应该做
不引入打包器（Vite / Rollup / esbuild）	破除零依赖约束的代价远大于收益；本项目的卖点就是"打开 HTML 就能用"	若未来要发布 ESM/CJS 模块化包，先评估是否需要独立仓库
不做像素级视觉回归（全量）	79 组件 × 5 端 = 395 张基准图，维护成本极高且易误报（抗锯齿/字体渲染差异）	P6 已包含「6 个核心组件抽样像素比对」，够用
不做 SSR / SSG	文档站是纯静态 SPA，爬虫需求已由 `site/components/*.html` 薄壳 + sitemap 解决	若 SEO 成为核心指标，再评估
不做多主题商店（Ant Design 式）	已有 6 套预设 + 令牌导出，改色能力已足够；主题商店是运营功能非工程功能	产品化阶段（S4 之后）
不重写 `app.js`	2064 行单文件虽不理想，但功能正确、回归 100%。重构风险 > 收益	若某任务包因它受阻（如 P4 代码拆分），局部改造而非重写
不改 `frameworks/` 的视觉	那是规范原文的忠实实现，改了会破坏契约一致性	只有规格原文变更时才同步
不做 Storybook 集成	与零依赖冲突，且 Playground（v1.2.0）已覆盖在线试玩需求	不考虑
不做 React/Vue 单元测试（Jest/Vitest）	与零依赖冲突；跨端一致性靠 P6 的静态比对 + 抽样渲染	若组件逻辑复杂化到静态分析无法覆盖

五 · 未解问题（需用户或后续规划决策）

这些问题我作为规划师无法单方面决定，列出供决策。

#	问题	影响面	我的建议
Q1	是否发布到 npm？涉及包名占用、发布权、后续维护承诺	S1-P2	建议发。当前无分发渠道是最大阻塞，且 npm 上同名包大概率未被占用
Q2	目标用户是谁？内部团队 / 开源社区 / 商业化产品，三者的优先级与验收标准不同	全局	建议先按「内部团队 + 开源复用」定位（对应 S1-S2 的优先级）
Q3	是否有设计团队协作？若没有，S4-P10 的 Figma 产出无人使用	S4-P10	建议推迟到有设计资源时再做，或降级为「Figma Variables JSON 导出」只做工程侧
Q4	是否需要 RTL？取决于是否有中东/希伯来语市场	S3-P8	若无明确市场，降级为 P2 或推迟。迁移成本高（22 个文件）
Q5	性能预算的底线是多少？我定的 300KB 是经验值	S1-P4b	建议以「3G 网络首屏可交互 < 3s」反推预算
Q6	暗色模式下演示 iframe 是否反色？两种都有道理	S2-P5	建议反色（用户开暗色就是要整体变暗），但需人工验收视觉

六 · 风险登记

风险	影响	缓解
约束冲突：CI 需要 Playwright，但"零依赖"	中	明确区分运行时依赖（保持零）与构建/测试依赖（可引入 devDependencies），并在 README 写清
S2-P6 暴露大量跨端不一致	中	已在任务包里说明"发现即价值"，差异作为新任务列出，不顺手修
暗色反色后视觉倒退	中	强制对比度脚本验证 + 人工截图验收
RTL 迁移破坏现有布局	中	迁移后跑八次回归；逐文件比对渲染截图
`data.js` 拆分影响 For Agents 承诺	高	明确要求 `data.json` 保持完整，只拆 `data.js`
用户未确认许可证类型	中	默认 MIT 并在交付说明标注"如需变更请告知"
首页在 320px 视口横向溢出 15px（实测 `.stat` 统计卡 307→335）	低	2026-09-20 做顶栏主题入口时实测发现，既有问题、未修（不属该次范围）；顶栏自身已无溢出。修复方向：首页 hero 的 `.stat` 行改 `flex-wrap` 或降字号

七 · 验收总纲

任一任务包完成，必须同时满足：

给出验收命令的完整输出（不是"我以为跑过了"）
跑八次回归：100% / 0 失败 / 0 超时
CHANGELOG.md 有对应条目（[Unreleased] 下）
本文件对应任务包下追加 ✅ 完成于 <commit-hash>
若发现新问题：写成新任务包追加到本文件，不在原任务里顺手修

附 · 执行状态总览

执行模型看这里：找下一个可开工的任务。状态为「待开始」且依赖已满足的最优先任务就是你的目标。

ID	任务	阶段	优先级	预算	依赖	状态
P1	LICENSE	S1	P0	10 min	—	✅ 已完成（MIT）
P2	npm 分发	S1	P0	2 h	P1 ✅	✅ 已完成（dist 构建 + npm pack 115.9KB）
P3	CI 回归	S1	P0	1.5 h	—	✅ 已完成（workflow + runner 重构 + exit code）
P4	`data.js` 瘦身	S1	P0	3 h	—	✅ 已完成（data.js 98KB/sources 395/data.json 完整/回归 1003/1003，见 c65a69c）
P5	暗色模式	S2	P0	1 d	P4 ✅	✅ 已完成（令牌组31/对比度10项≥4.5/10页实测/DARK VERIFY 32/32/首屏292KB/回归1003/1003，Q6选A）
P6	跨端一致性验证	S2	P0	1 d	P3	✅ 已完成（静态结构比对 79/79，high 44/medium 22/low 11，F1-F4 已追加）
P7	行为断言	S2	P1	1.5 d	—	✅ 已完成（8 动词引擎 + 6 试点全绿/回归 1009/1009）
P8	RTL	S3	P1	2 d	P5	✅ 已完成（28 文件迁移/物理清零/14 处人工例外/三页实测零溢出）
P9	FAQ 页	S3	P2	1 d	—	✅ 已完成（240 条/79 组件/搜索过滤/浏览器实测，details 懒加载版）
P10	Figma 资源	S4	P2	2 d	P2	⚪ 待 P2
P11	模板页库	S4	P2	2 d	—	✅ 已完成（1→5 页，54 条浏览器断言 + CI 接入；组件样式按需引 `frameworks/*.css`，见 S4-P11 完成说明）
P12	版本发布流程	S4	P3	1 d	P2	✅ 已完成（release.mjs 检查/bump + CONTRIBUTING 文档化，只做本地准备不自动 push/tag）

四 · 2026-09-19 安全审计（衍生任务与已完成项）

起因：对仓库 + 192.168.5.7 线上部署做全量安全与缺陷审计（报告与逐项证据见 安全审计修复与待决事项.md）。已修复项在 CHANGELOG [Unreleased] → Security 有记录；下面只列衍生任务包与状态。

ID	任务	阶段	优先级	预算	状态
S5-P13	部署可复现化	S5	P0	2 h	✅ 已完成（`tools/pack-deploy.mjs` 以 `.dockerignore` 为唯一真源 + 硬断言；AGENTS §九流程；2026-09-19 实际部署验证 6/6 断言 + 396/396 URL）
S5-P14	容器运行期加固	S5	P2	1 h	⚪ 待决策（需停机窗口）：`read_only` + `tmpfs`、`cap_drop: [ALL]`、`no-new-privileges`、基础镜像 digest 固定
S5-P15	对外承诺口径统一	S5	P1	2 h	⚪ 待决策：契约数量三处说法不一致（`llms.txt`「79 个」／`AGENTS.md`「79」／`index.json`「6 个核心」），线上实际只发布 6 份核心 + `index.json`
S5-P16	正式域名与 SEO	S5	P2	1 h	⚪ 待决策：`sitemap.xml` 与 `package.json` 仍是 `YOUR-ACCOUNT.github.io` 占位；`build-site.ps1` 已支持 `SITE_URL_BASE`，但 `tools/verify-site-routing.mjs` 目前把占位 URL 写成了断言，换域名需同步改
S5-P17	回归偶发失败的可追溯性	S5	P1	1 h	✅ 已完成（2026-09-20）：`tools/run-regression.mjs` 现在 ①`failures` / `errorDetail` 落盘（真断言失败带 `data-assert` 标识与实测值）；②非满分时把上一次报告留档为 `tests/report-prev.json`（`report.json` 仍只有一份，供首页读），失败现场不再被下次运行覆盖。实测（真实注入，非模拟）：把 `tests/button.html` 移走制造 404 → 输出 `kept: tests/report-prev.json（本次非满分，已保留上一次报告供回放）`，`tests/report-prev.json` 确实生成；还原后满分运行不再留档。`report-prev.json` 已加进 `.gitignore`（诊断中间产物，不入库）。判据修正附反例：`isCollectionFailure()` 对 `no-result`/`timeout`/`page-error` 为真、对 `matrix:contrast>=4.5` 这类真断言失败为假 —— 5 条判据用例逐条验证（见 S6-P30）
S5-P18	组件库可 import（三端入口）	S5	P0	3 h	✅ 已完成（`dist/react

已知但暂不处理（用户 2026-09-19 决定）：不对外公用 —— 线上保持 127.0.0.1:3311 回环，需 SSH 隧道访问；不加反代、不加域名、不加认证。

S5-P15 补充说明

线上 /.design_library/kole-ui/components/ 只有 button/card/input/modal/select/table.json + index.json；本地是 79 份 + index.json。三处文档说法互相矛盾，需先定「对外到底承诺几份契约」，再统一 llms.txt / AGENTS.md / index.json 与线上发布内容。

S5-P16 补充说明

sitemap.xml 的 396 条 URL 本身在线上全部 200（静态页无死链），问题只在文件本身的域名是占位值，且此前未 COPY 进镜像（已修）。换真域名时注意 tools/verify-site-routing.mjs:48 的断言。

五 · 2026-09-20 文档站导航（衍生任务与已完成项）

ID	任务	阶段	优先级	预算	状态
S5-P19	导航语言选择改为下拉（美化）	S5	P1	2 h	✅ 已完成（原「中/EN 双段」按钮换成令牌化下拉：地球图标 + 当前语言 + 箭头触发器，186px 卡片菜单含标题分隔线、ZH/EN 角标、对勾选中态；listbox ARIA + 方向键/Home/End/Esc/Tab/点击外部全路径；暗色令牌继承，选中项对比度 4.57、标题 6.50；≤1100px 收起语言名到 56px，实测 ≥860px 顶栏 0 溢出）
S5-P20	顶栏在 ≤820px 溢出（移动端导航无方案）	S5	P2	2 h	✅ 已完成（2026-09-20）：≤1366px 折叠为汉堡 + 右侧抽屉（`.topnav` 就地变成抽屉，不复制 DOM，避免与 i18n/active 态两处维护）；基础层加 `white-space: nowrap`（缺它时中文逐字换行成竖排并顶出 60px 栏）；收紧规则改为无条件而非挂在断点上——实测英文 7 条链接（Getting Started / Design Tokens / For Agents）+ 可读搜索框在 `.topbar-inner` 的 1440px 上限内始终排不下，英文在 1600px 即折 2 行，与视口无关。新增 `tools/verify-nav-responsive.mjs`（18 宽度 × 中英双语 + 抽屉交互，346 断言）并接入 `regression.yml`（含 `fonts-noto-cjk` 安装步骤：宽度断言依赖字体度量）。验收中另修掉两个只有交互测试能抓到的缺陷：① 遮罩层叠压住抽屉——`.topbar` 的 `z-index:100` 形成层叠上下文，抽屉 `120` 只在顶栏内生效，整条顶栏被遮罩 `110` 盖住，可见但点不到（矩形/可见性断言全过）；② `visibility` 参与 `transition` 导致切换后首帧仍 `hidden`，`focus()` 静默失败，键盘用户进不去抽屉。验收：`npm run verify:nav` → 0 FAIL；回归 100%（1017/1017）连跑 8 次一致、0 超时；`smoke:site` 全通过
S5-P21	发布到私有 npm 源	S5	P1	1 h	✅ 已完成（`gitea.mymoyu.top` 的 npm registry，匿名可读；发布 3 个可互换包名 `@root/ui`（推荐，支持一行 `.npmrc`）/ `chunyu-ui` / `aurora-admin-design`；Vite+Vue3 真实工程实测安装→构建→浏览器渲染通过）。待决：是否也发布到公共 npm（本机无凭据，需用户 `npm login` 或 token；`chunyu-ui`/`aurora-admin-design` 在公共 npm 均未被占用）。v2.0.0 改名后追加实测：私有源上仍是上列三个旧名，无 `kole-ui`；要按新名发布需重跑一次发布流程
S5-P24	侧栏「组件总览」兼作分节父项导致双高亮	S5	P2	30 min	✅ 已完成（2026-09-20）：`renderSidebar` 侧栏高亮规则 `active: r === 'overview' \|\| r === 'component'` 改为 `r === 'overview'` —— 「组件总览」降级为只代表自己那一页的独立索引，与「快速开始 / 设计规范 / 常见问题」三条同级。起因是两处 `active` 样式逐属性相同（`style.css` 228 / 264 行），组件页并列两块蓝底读起来就是「选了两个」；规则出自 v1.2.0 初版（`git log -S` 溯源），非后期回归。顶栏「组件」保持分节语义不变（顶栏无逐组件入口，去掉后组件页将无任何顶栏高亮）。`aria-current="page"` 本就只加在真实组件项上，语义层未动，本次只修视觉。实测见下方。
S5-P25	导航选中态无断言覆盖（S5-P24 能存在至今的原因）	S5	P2	2 h	⬜ 待排期：`grep -rn "side-link\|side-item" tests/ tools/` 零命中 —— 侧栏 `.side-link` / `.side-item` 与顶栏 `.topnav a.active` 的选中态没有任何断言，`tools/verify-nav-responsive.mjs` 只测布局与抽屉交互。故 S5-P24 这类缺陷自 v1.2.0 存在至今，八次连跑也发现不了。建议新增 `tools/verify-nav-active.mjs`（或扩 `verify-nav-responsive.mjs`）：按路由表断言「侧栏高亮项恰好 1 个」「`aria-current="page"` 与 `.active` 指向同一项」「组件页不命中任何 `.side-link`」「中英双语下文案正确」，并接入 `regression.yml`。

S5-P24 实测数据（2026-09-20，Chromium，http://127.0.0.1:3311/site/；口径=document.querySelectorAll('.side-link.active, .side-item.active').length）：

路由	顶栏选中	侧栏 `.side-link`	侧栏 `.side-item`	侧栏高亮数
`#/overview`	组件	组件总览	—	1
`#/component/button/h5`	组件	—（改动前：组件总览）	按钮	1（改动前 2）
`#/component/modal/h5`	组件	—（改动前：组件总览）	对话框	1（改动前 2）
`#/component/table/h5`	组件	—（改动前：组件总览）	数据表格	1（改动前 2）
`#/design`	设计规范	设计规范	—	1
`#/guide`	快速开始	快速开始	—	1
`#/faq`	常见问题	常见问题	—	1
`#/changelog`	更新日志	更新日志	—	1（该页原先无侧栏入口，S6-P37 起「更新日志」进「开发指南」分组）

S5-P20 实测数据（2026-09-20，Chromium，http://127.0.0.1:3311/site/；口径=顶栏 .topbar-inner 横向溢出 px）：

视口宽	改动前 · 中文	改动前 · 英文	改动后（双语）
≥1367	0（1280 起 7 条链接全部折行）	0（1600 即折 2 行）	0，单行
1366	0	21px	0（汉堡 + 抽屉）
1280	0（7 条折行）	107px	0
1100	0（1 条文字出血）	236px（5/7 可达）	0
1024	0（5 条出血）	312px（4/7）	0
960	18px（5 条出血）	376px（3/7）	0
820	89px（5 条出血）	419px（2/7）	0
768	141px（2 条不可达）	471px（2/7）	0
480	429px（7 条全不可见）	759px（0/7）	0（抽屉内 7/7 可达）
375	534px（0/7）	864px（0/7）	0（7/7）
320	589px（0/7）	919px（0/7）	0（7/7）

「出血」= 链接文字顶出 60px 顶栏（中文 4 字标签被压成竖排时的现象）。改动后双语 18 个宽度全部为 0 溢出 / 0 出血 / 链接全可达。

六 · 2026-09-20 组件详情页「在线测试」与代码区控制条（衍生任务与已完成项）

ID	任务	阶段	优先级	预算	状态
S5-P22	试玩入口改为独立「在线测试」页 + 代码区控制条对齐 Element	S5	P2	3 h	✅ 已完成（2026-09-20）：原「▶ 在线试玩」是详情页内联 textarea（胶囊按钮悬在演示区与代码区之间的白缝里，归属含糊）。改为 `site/playground.html?slug=<slug>` 独立页：左编辑 H5 源码、右 iframe `srcdoc` 实时预览（300 ms 防抖）、79 组件可切换、复位/复制/新窗口打开演示原页、Tab 缩进两格、Ctrl+S 立即同步。数据单请求取自 `site/data.json`（`sources.html` 内联，缺省回落 `files.html`）。详情页控制条改为 Element 文档同款：44px、居中「▼ 显示代码 / ▲ 隐藏代码」、文字悬停/键盘聚焦才浮现（`.lbl` opacity 0→1）、右侧常显「在线测试 →」（跳转入口不能藏在悬停里）；代码区默认收起（对齐 Element，页面因此可扫读）。验收见下方实测。
S5-P23	演示帧在暗色模式下不会反色（注入机制实测失效）	S5	P2	2 h	✅ 已完成（2026-09-20，随 S5-P26 一并修掉）。修法：演示帧放行 `allow-same-origin` —— 它加载的是一方文件 `frameworks/<组件>.html`，与文档站同信任级；`sandbox` 属性仍保留，继续挡表单提交 / 顶层跳转 / 弹窗。注入随即真正生效：站点 `kole-mode=dark` 时帧内 `documentElement.classList.contains('kole-dark') === true`、帧 body 背景实测 `rgb(20,22,28)`；原设想的「让 79 个演示页读 `?theme=`」未采用（无需动演示页）。历史实测：`sandbox="allow-scripts"`（无 `allow-same-origin`）的帧是不透明源，父页 `iframe.contentDocument` 恒为 `null` —— 因此 `app.js` 的 `injectIframeTheme()` 每次都在 `if (!d) return` 处静默返回，`html.kole-dark .demo-code` 那类站点规则也进不了帧；79 个演示页自身不读 `kole-mode`（`grep -rl "kole-mode" frameworks/` 无命中）。与 Q6 的关系：Q6 把它当「两种都有道理的设计取向」，实测是「无论想不想反色，当前机制都反不了」—— 结论：声称≠实现，CHANGELOG v1.1.1 的「演示 iframe 由 app.js 注入 kole-dark 类同步反色」从未生效。可行方案（待定）：演示页读 `?theme=dark` 查询参数自加类（需动 79 个演示页 + `run-tests.ps1`），或改为父页在 `src` 上带主题参数而非注入。在线测试页的预览帧仍是严格沙箱（跑的是用户编辑的代码，不放行 `allow-same-origin`），其预览按演示页自身令牌渲染 —— 有意保留的差异，已写在 `site/playground.js` 头部。
S5-P26	代码整段展示 + 演示帧自适应高度（去掉两处内滚动）	S5	P2	2 h	✅ 已完成（2026-09-20）：① 代码不再截断 —— `.demo-code pre` 原有 `max-height: 420px`，长源码（cascader 7742 字符 ≈ 21 行窗口）要在块内滚动；去掉 max-height（Element 文档同样显式 `max-height:none`），整段随页面滚，长行仍可横向滚动。② 演示整段展示 —— `.demo-stage iframe` 固定 `height: 420px`，比它高的演示在帧内出滚动条；新增 `autoSizeFrame()`：帧 load 后按 `body.scrollHeight + margin`（`documentElement.scrollHeight` 更大时取后者）写实际高度，`ResizeObserver` 跟随帧内异步渲染（加载态 / 展开行），换页时 `releaseFrameFits()` 摘掉观察器与 resize 监听，420px 降级为 CSS 兜底。实测（Chromium 1440×900，`http://127.0.0.1:3311/site/`）：5 个组件帧内滚动量全为 0，帧高贴内容（button 571 / cascader 394 / table 413 / watermark 330 / expandabletable 311）；代码块纵向滚动量全为 0（最长 7742 字符）；暗色下帧内 `kole-dark` 生效（见 S5-P23）；0 控制台报错。回归 100%（79/79 页，1017/1017 断言，N/A 34，0 超时）连跑 3 次一致。

S5-P22 实测数据（2026-09-20，Chromium 1440×900，http://127.0.0.1:3311/site/）：

断言	实测
控制条高度 / 字浮现	44px；`.lbl` opacity 0 → 1（悬停后）；`aria-expanded` false→true，`aria-controls` 指向 `demo-code-button`
默认状态	代码区不存在（`open=false`），条紧贴演示区下方（Δ<2px），文案「▼ 显示代码」
在线测试入口	`href=playground.html?slug=button`、`target=_blank`、常显
预览帧真实渲染	帧内 `document.querySelectorAll('.btn').length=16`，首按钮背景 `rgb(47,84,235)`（品牌色实值）
「改了立刻看到」	源码尾部注入 `<div id="probe-marker">` → 帧内 `#probe-marker` 存在；复位后消失
组件切换	切到 `table`：URL→`?slug=table`、标题→「数据表格 Table · 在线测试」、编辑器 6587 字符、预览帧内 `.btn` 归 0（Table 无 btn）
编辑器	Tab 插入 2 空格（`<!DOCTYPE` → `<!DOCTYP`）；状态回显「已同步（已修改） HH:MM:SS」
暗色	`kole-mode=dark` → 页面与代码面同为 `rgb(20,22,28)`、头栏 `rgb(28,31,38)`；预览帧按自身令牌保持浅色（见 S5-P23）
控制台	两页均 0 报错

S5-P23 实测证据：document.querySelector('.demo-stage iframe').contentDocument === null（同 sandbox 的 srcdoc 帧同样 null）；frameworks/ 下 grep -rl "kole-mode" 无命中。

七 · 2026-09-20 品牌重命名 Kole UI（衍生任务与已完成项）

起因：用户要求「项目改为 kole ui，全局改名」。已完成的改名本体见 CHANGELOG [2.0.0]。本节只登记改名过程中暴露、但不在改名范围内的缺口。

ID	任务	阶段	优先级	预算	状态
S6-P26	`kole-ui-dsh-launcher.exe` 内嵌旧程序集名	S6	P3	30 min	⬜ 待排期：该 exe 是 5.6 KB 的 .NET 产物，文件名已改但元数据里仍是 `aurora-admin-dsh-launcher.exe` / 命名空间 `aurora-admin-dsh-launcher`（实测）。仓库内无构建源（无 `.cs` / `.csproj` / `.sln`，`dsh_launcher.py` 与之无关），故需在产出它的地方重编，或直接删除该 exe（`start-dsh.bat` / `start-dsh.ps1` / `dsh_launcher.vbs` 均不依赖它，待确认）
S6-P27	按新名重新发布到私有 npm 源	S6	P2	30 min	⬜ 待排期：私有源（`gitea.mymoyu.top`）上仍是 `@root/ui` / `chunyu-ui` / `aurora-admin-design`，实测无 `kole-ui`；`package.json.name` 已是 `kole-ui`，需一次显式发布动作（需凭据）。公共 npm 上 `kole-ui` 未被占用（2026-09-20 实测）
S6-P28	按新名重新部署到 192.168.5.7	S6	P2	30 min	⬜ 待排期：仓库侧 `docker-compose.yml`（`kole-ui-showcase`）、`AGENTS.md` §九（`/opt/kole-ui`）、`tools/pack-deploy.mjs` 输出名均已改；线上实例仍是旧名。走一次 AGENTS §九标准流程即生效（属显式部署动作，需许可）
S6-P29	CHANGELOG 表格行不入站点更新日志页	S6	P3	1 h	⬜ 待排期：`build-site.ps1` 的 changelog 解析器只认 `^###` 、`^-` 两类行，Markdown 表格行（`^\|`）被整体丢弃 → 站点 `#/changelog` 看不到任何表格。影响所有历史条目，非本次改名引入。修法二选一：解析器补 `^\|` 分支（需在前端补表格渲染），或约定 CHANGELOG 不用表格（[2.0.0] 段已按后者加了一句「一句话版」兜底）

八 · 2026-09-20 路由去 #（衍生任务与已完成项）

背景：文档站路由由 hash 改为 History API（/site/#/component/button/h5 → /site/component/button/h5）。改动面与验收见 CHANGELOG [Unreleased] 同名条目。以下两条是执行中发现、本次未做的缺口。

ID	任务	阶段	优先级	预算	状态
S6-P30	回归报告分不清「采集偶发」与「真断言失败」	S6	P2	1 h	✅ 已完成（2026-09-20）：新增 `isCollectionFailure()` 判据，采集失败（`no-result`/`timeout`/`page-error`）单列 `collectionFailures` 且不计入 passRate 分母，`failedPages` 只留真断言失败（此前 `button: no-result` 会被读成「button 的断言坏了」，两类事实混在一张表里）。实测：注入 404 那次输出 `passRate 100%
S6-P31	sitemap 与 canonical 仍指向 396 个薄壳 URL	S6	P3	1 h	⬜ 待排期：`build-site.ps1` 生成的 `sitemap.xml`（396 条）与每张薄壳的自指 `canonical` 都是 `/site/components/<slug>[/<platform>].html`。薄壳是 meta-refresh 跳转桩（旧目标的 hash URL 无法做 canonical，自指是当时的合理选择），现在目标已是真实可索引的 URL `/site/component/<slug>/<platform>`，canonical/sitemap 应改指它。属 SEO 行为变更，需一次显式决定
S6-P32	`densityswitcher` 对比度断言在 CSS 过渡中被采样 → 偶发假失败	S6	P2	1 h	⬜ 待排期：`matrix:contrast>=4.5` 会读到颜色过渡中间态并判 fail。`frameworks/DensitySwitcher.css` 的 `.kole-densw-opt` 带 `transition: background .15s, color .15s`，演示页内联脚本在解析期就加上 `is-active`，因此页面起步必然有一次颜色过渡；`tests/_runtime.js` 的就绪轮询只看 `readyState` + innerHTML 长度是否稳定（过渡期间 innerHTML 不变），拦不住。修法二选一：断言前等 `document.getAnimations()` / 计算样式稳定（轮询 `getComputedStyle` 的 color/background），或演示页首屏不要跑过渡。判据不是"放宽到 4.4" —— 两个端点的比值分别是 5.85（生效后白字/品牌底）与 7.00（未生效深灰/白底），都达标，坏掉的只是中间态

S6-P32 实测数据（2026-09-20，Chromium headless，http://127.0.0.1:3311）：

采样	结果
整轮回归连跑 62 次	60 次 `1017/1017`；1 次 `densityswitcher` 的 `matrix:contrast>=4.5`（记为 fail，非 timeout）；1 次同样 1016/1017 但细节未落盘
单页压测 `/tests/densityswitcher.html` × 300 次	命中 2 次：`button.kole-densw-opt "默认" (4.46:1 < 4.5:1)` 与 `(4.45:1 < 4.5:1)`
量 `getComputedStyle` 的过渡过程（加回 `is-active` 后每 20ms 采样）	比值依次 7 → 1.79 → 2.4 → 4.58 → 5.74 → 5.85（稳定）；两端点 5.85 / 7.00 均达标，4.45~4.46 是过渡中途的取值
对照：断言引擎的等待条件	`whenReady()` = `readyState === 'complete'` + innerHTML 签名连续 3 次不变（约 48ms）→ 过渡中签名恒定，条件成立即开跑

九 · 2026-09-20「在线测试」预览帧审计（衍生任务与已完成项）

背景：站点经 frp + EdgeOne 暴露到公网（https://kole-ui.mymoyu.top/site/），而 site/playground.html 是全站唯一把用户编辑的 HTML 灌进 iframe 执行的地方（srcdoc + sandbox="allow-scripts"）。本次按「不可信内容」重新审计该页：沙箱边界实测有效（探针服务器 0 命中、不透明源、无外联），但资源解析与三处丢改动缺陷是真的，已修；改动与验收见 CHANGELOG [Unreleased] 同名条目。

ID	任务	阶段	优先级	预算	状态
S6-P33	「在线测试」预览帧：资源基准 + 策略收紧 + 丢改动缺陷	S6	P0	3 h	✅ 已完成（2026-09-20）：①`srcdoc` 基准 URL 是父页 `/site/`，演示源码里 `href="./Xxx.css"` 解析成 `/site/Xxx.css` → 79 个组件里 36 个在预览里丢掉整个组件 CSS（线上实测 `/site/Xxx.css` 404 / `/frameworks/Xxx.css` 200）→ 注入 `<base href="../frameworks/">`；②帧内注入 meta CSP（只写比父页更严的 `connect-src`/`form-action`/`frame-src`/`object-src` = `'none'`，两策略取交集所以只会收紧）→ 帧内彻底断网；③帧内上报器（脚本报错 / 策略拦截）经 `postMessage` 回传，父页按来源 + 纯文本渲染、每轮上限 3 条；④三处丢改动：切组件确认、拉取失败不清空编辑器、`beforeunload`；⑤看门狗：帧内自跳转（`<meta refresh>` / `location.href`）会把预览留在 `chrome-error://`，现在就地重建。新增 `tools/verify-playground.mjs`（38 断言，含本地探针服务器「0 命中」判据）并接入 `regression.yml`。回归 100%（1017/1017）连跑 8 次一致
S6-P34	组件详情页演示帧的 `allow-same-origin` 在公网形态下复核	S6	P2	2 h	⬜ 待排期：`site/app.js` 的 `buildDemoCard` 给演示帧同时开了 `allow-scripts`（必需，演示页靠内联脚本建 DOM）与 `allow-same-origin`（为量 `contentDocument` 做自适应高度 + 注入暗色类，见 S5-P23）。该组合下沙箱对一方内容形同虚设（帧可读父页、也能自行摘掉 sandbox），这是当年显式付过的代价。如今站点公网可达，该取舍只在「`frameworks/*.html` 只来自本仓库」这个前提成立时才安全 —— 建议把前提写成显式约束（或在验证脚本里卡住"演示源码不含外链脚本"），或改走 postMessage 自报高度以去掉 `allow-same-origin`。属架构取向，需一次显式决定
S6-P35	预览帧里的资源 404 不上报	S6	P3	1 h	⬜ 待排期：新加的上报器只覆盖 `error` / `unhandledrejection` / `securitypolicyviolation`，覆盖不到资源加载失败（`<img>` / `<link>` 404 在帧内是静默的，`securitypolicyviolation` 只在被策略拦下时才触发）。用户把演示源码里的资源路径改坏后，看到的只是一个"样式丢了"的预览，没有任何提示。做法：上报器改用捕获期监听（资源错误在 `window` 的捕获阶段可见，`e.target` 是出错元素），把标签名 + URL 一起回传
S6-P36	`?slug=` 非法值时静默回落且改写 URL	S6	P3	30 min	⬜ 待排期：`load()` 找不到 slug 时回落到 `button`，随后 `history.replaceState` 把地址改成 `?slug=button` —— 用户从旧链接 / 错拼进来的痕迹被抹掉，看不出"你要的那个组件不存在"。建议：非法 slug 时给出提示（并在选择器上标出回落目标），或保留原 slug 直到用户主动切换
S6-P37	文档站内容与信息架构对齐 Element 文档站（侧栏分组 / 快速开始叙述 / 组件页 API 说明）	S6	P2	3 h	✅ 已完成（2026-09-20）：①侧栏新增「开发指南」「组件」两个段标题并把 5 个页面链接收进分组（原先平铺），补上此前缺失的「更新日志」入口；②「快速开始」改为 Element 式的分步叙述（开头「本节将介绍…」清单、按端引入的「全量与按需」口径、新增「全局配置（主题与暗色模式）」、收尾「开始使用」四张下一步卡片），7 节 + 右侧目录同步；③组件页 API 表说明列从 98% 空（`—`）补到 235/235，每条带出处标记：规格（29，悬停引用规格原文分条）/ 命名（204，API 名释义）/ 源码（1 注释）/ 契约（1 dims），事件说明 98/98 具体化（`update:` 之外由 emit 调用点判定，如 alertmodal 的 `ok` 绑在遮罩上 → 「点击遮罩时触发」）。可选值列不做：实测源码比较字面量只覆盖 5% 且多为 `1`/`number` 噪声、规格枚举仅 2 条，硬填即发明；规格里真枚举了取值的（如 Button `type` 五种）以「取值：」副行带出。新增英文词条 166 条（`verify-i18n.mjs` 289 键全覆盖）。深度检测追加：①固化 `tools/verify-api-docs.mjs`（9 项断言：说明非空且出处可溯 / `spec` 类 cite 必须逐字命中规格原文 / 事件无模板句 / `update:` 标 v-model / 说明与事件词条在英文字典齐全 / 规格取值副行标签一致且可回查）并接入 `package.json` 与 `regression.yml`；②收紧规格取值副行的闸门 —— 初版 4 条里 3 条是误配（`card.title` / `modal.title` 命中「结构：标题区、内容区…」这类结构描述、`tag.color` 切出 `绿#F6FFED` 碎片），现只留 `button.type` 1 条；③新增元素的对比度从 4.23:1 修到 4.66 / 4.75:1（亮）与 5.65 / 7.12:1（暗）。回归 100%（1017/1017）连跑 8 次一致（深检期间共 18 次全量 + 40 次单页压测 + 180 次并发压测）
S6-P38	公网站 `kole-ui.mymoyu.top` 跑的是改名前构建（品牌/版本与仓库不一致）	S6	P1	1 h	✅ 已完成（2026-09-20，由并行会话的部署完成）：2026-09-20 实测 `https://kole-ui.mymoyu.top/site/data.json` → `"lib": "aurora-admin"`、`"version": "1.4.1"`、`"generated": "2026-09-20 02:57"`，`/site/app.js` 里 `Aurora` 出现 7 次、`Kole` 0 次，`<title>Aurora Admin · 组件库文档</title>`；而仓库已是 v2.0.0（`site/index.html` 标题 `Kole UI · 组件库文档`，app.js 品牌词已换）。即：公网地址服务的是今日 02:57 从改名前的源码树构建的产物（含 families 字段，故不是纯旧版），访问者看到的是 Aurora Admin 品牌与 1.4.1 版本号。需确认该实例的来源目录（`/opt/kole-ui` 还是另有一份旧部署）并按 AGENTS §九用 `tools/pack-deploy.mjs` 重新发布；同时核对 §九里「没有任何 frp / 反代 / 域名指向它」的描述与现状（现已有 EdgeOne + frp 暴露）核实：2026-09-20 06:5x 复测公网 —— `data.json` 已是 `"lib": "kole-ui"` / `"version": "2.0.0"` / `"generated": "2026-09-20 05:27"`，`<title>Kole UI · 组件库文档</title>`，`app.js` 里 `Kole` 出现 12 次（与仓库一致）；AGENTS §九的四条验收全过（specs 404 / 根路径 302→`/site/` / sitemap 200 / healthz 有 content-type）。与 §九复核一致：实际部署目录 `/opt/aurora-admin`（§九已由并行会话改对，本次只补了流程里残留的 `kole-ui.staged` 暂存目录名），公网入口 `https://kole-ui.mymoyu.top` 也已写进 §九。线上当时尚未包含本次暗色修复（05:27 的构建早于修复）。2026-09-20 07:12 再次发布（本轮）：公网 `data.json` 的 `generated` 已推进到 `2026-09-20 07:09`，`lib=kole-ui` / `version=2.0.0`；本轮新增内容全部上线 —— 移动端文档站四页（总览 / 快速开始 / 平台与端 / 设计令牌）+ 逐组件页（14 小节：API / 6 端源码 / 令牌 / 回归状态）、PC 顶栏技术栈选择器与侧栏平台入口；§九五条验收全过，且暂存树与本地包逐文件 0 差异（1531/1531）、线上服务的 13 个关键文件哈希与本地一致
S6-P39	暗色模式下「选中态」文字对比度不足（站内多处），`verify-dark` 覆盖不到	S6	P2	1.5 h	✅ 已完成（2026-09-20）：2026-09-20 实测（Chromium，`kole-mode=dark` 真实切换路径，半透明底沿父链合成后计算）—— `.side-item.active` / `.side-link.active` 在组件页为 3.60:1（文字 `--kole-color-brand` = `rgb(99,127,240)` 压在 `rgba(99,127,240,.18)` 叠 `--kole-color-card-bg #1C1F26` 的合成底 `rgb(41,48,74)` 上；用页面底色 `#14161C` 合成时为 3.98:1），低于 AA 正文 4.5:1。同一模式（pair）被十余处复用：`style.css` 里 `.side-link.active` / `.side-item.active` / `.lang-opt:focus-visible` / `.chip.blue` / `.mode-menu button.is-active` / `.tool-btn:hover` / `.sr-item:hover` / `.rel-card:hover` 等（`grep -n 'brand-bg' site/style.css` 20 处）。为什么一直没被发现：`tools/verify-dark.mjs` 第 3 组只抽查组件演示页（`frameworks/` 的 10 个 slug，如 tabs / formmodal / sidemenu / tag），站点自身的 chrome（侧栏选中、chips、悬停行）不在其覆盖内；S2-P5 的「10 页实测」也只在页面级看是否有白底残留。建议修法（2026-09-20 实测矩阵，Chromium + 内联 setProperty 模拟；注意 `applyTheme()` 用内联样式写品牌色族，样式表规则压不过它，所以修点必须在 `site/app.js` 的 applyTheme 里，而不是 style.css）：现状 3.59:1 → `brand-bg` 透明度降到 .10 只到 4.03:1、降到 .06 也才 4.25:1（均不达标）；把暗色品牌文字向白混 45%（`hexMix(brand,'#FFFFFF',.45)` = `rgb(174,192,255)`）→ 7.27:1，再叠 `bg α=.10` → 8.15:1；文字直接用 `--kole-color-text-title`（#E8EAED）→ 10.75:1（但会丢掉品牌色语义）。推荐第一种（文字混白 45% + bg 保持 .18），改动面最小且保住「选中=品牌色」的语义。同时建议扩 `verify-dark.mjs`：把「站点 chrome 的选中/悬停态」纳入第 3 组（选择器清单 + 期望 ≥4.5:1），否则同类缺陷仍会漏网修复：`site/app.js` 的 `applyTheme()` 把暗色品牌色族的混白比例从 0.25 提到 0.45（悬停 0.6 / 按下 0.3 保持次序）—— 实测侧栏选中项从 3.59:1 升到 7.27:1；同时把「站点 chrome 的暗色对比度」固化进 `tools/verify-dark.mjs` 新增的第 4 组（7 条路由 × 正文 4.5:1 / 大字与图标 3:1，含侧栏选中态与含必填徽章的组件页）。该组一上线又抓出另外四处既有缺陷并一并修掉：行内 code 2.88:1、`.radius-demo` 3.44:1、`.callout.note` 4.14:1、`.code-inline` 2.88:1（代码块借用的 `--kole-color-tooltip-bg` 在暗色下是浅色）、`.badge-opt` 3.08:1 与 `.badge-req` 3.71:1（亮色模式也不达标）、`.callout.warn` 4.14:1（亮色不达标）→ 全部改为令牌或按模式取值，`node tools/verify-dark.mjs` 现 DARK VERIFY OK*
S6-P40	`verify-nav-responsive.mjs` 当前红灯：≤420px 隐藏语言选择器后脚本仍在 390px 点它	S6	P1	30 min	✅ 已完成（2026-09-20）：工作区里 `site/style.css` 新增 `@media (max-width: 420px) { .lang-select { display: none; } }`（注释：「≤420px 语言选择器让位」），但 `tools/verify-nav-responsive.mjs:211` 的交互序列固定在 390px 且 `await p.click('#lang-trigger')` → 元素不可见，30s 超时崩溃（实测：`page.click: Timeout 30000ms exceeded … element is not visible`，退出码 1；前面 345 行断言全过，失败点就在这一步）。两条修法选一：①脚本按新行为改判据 —— ≤420px 断言 `#lang-trigger` 不可见、并把语言相关的交互步骤挪到 >420px 的视口；②若不打算在窄屏隐藏语言选择器，则回退该 CSS。注意这是工作区未提交改动引起的红灯，不是侧栏改造引入的修复：不绑定具体规则 —— 叠层检查（语言菜单 vs 抽屉）固定挪到语言选择器可见的 480px 视口另开一段（新增 `交互 480px 语言选择器可见` + 沿用 `开抽屉会收起语言菜单` 断言），390px 段只覆盖抽屉交互本身。脚本不再崩溃（原先 30s 超时崩在 `p.click('#lang-trigger')`）。注意：修复期间该 CSS 规则被并行会话撤掉了，因此脚本按「与规则解耦」写，规则在或不在都能跑
S6-P41	对比度断言会采到过渡动画中途的瞬时低对比 → 偶发红灯（0.5–5%）	S6	P1	1 h	✅ 已完成（2026-09-20）：2026-09-20 实测 —— 全量回归 18 次里 1 次 `densityswitcher` 报 `matrix:contrast>=4.5` 失败（99.9%），单页无并发压测 40 次 0 复现，6 并发 × 30 轮 = 180 次加载复现 1 次（0.56%），抓到详情：`button.kole-densw-opt "默认" (3.55:1 < 4.5:1)`。直接量该组件：稳定态全部达标（未选中 7.00:1 / 选中白字蓝底 5.85:1），但选项按钮有 `transition: background .15s, color .15s`，过渡中途 40ms 采样为 1.74:1 / 1.79:1（文字 `rgb(197,197,197)` 压 `rgb(119,143,242)`，两者同时插值）—— 断言在 150ms 窗口内采样就偶发失败。这不是组件缺陷（WCAG 不约束过渡中间帧，两个合规态之间的淡入必然经过不合规中点），是断言缺少「等动画稳定」步骤。建议修法：`tests/_runtime.js` 的对比度遍历前，用已有的 `kole-assert-style` 注入 `{transition:none!important;animation:none!important}`（或 `W.getAnimations().forEach(a=>a.finish())`）再测量，测完还原；判据不放松（阈值仍 4.5:1，反例就是这条 1.74:1 的中间帧）。附带改进：`tools/run-regression.mjs` 只把断言 ID 写进 `report.json`/JUnit，丢掉 `tests/_runtime.js:579` 已算好的 `failureDetails`（节点名 + 比值）—— 本次偶发能定位纯属手工压测，建议把 `err` 一并落盘，否则下次同类偶发仍无法回溯修复：①`tests/_runtime.js` 的对比度遍历前后临时注入/移除 `#kole-assert-settle`（`{transition:none!important;animation:none!important}`）—— 阈值不动（仍 4.5:1），只是不再把过渡中间帧当结果；②`tools/run-regression.mjs` 把 `tests/_runtime.js` 已算好的 `failureDetails` 落进 `report.json` 与 JUnit（此前只存断言 ID，偶发无法回溯）。验证：断言总数仍 1017（判据未变），并发压测从「180 次加载失败 1 次」变为 300 次加载 0 失败
S6-P42	nav-menu 族 `direction=side` 的子菜单被渲染成横向 flex 项 → SideMenu 演示页「花屏」	S6	P0	2 h	✅ 已完成（2026-09-20）：现象（用户报告「花屏」，2026-09-20 实测复现）—— `/site/component/sidemenu` 与 `frameworks/sidemenu.html` 的「代码演示」里，二级项（全部订单 / 待发货 / 商品列表 / 分类管理）渲染成侧栏右侧一列浮块（x=96 宽 40，落在 220px 侧栏之外），并压住 44px 行里的同级项（`工作台` 的 label 盒与 `全部订单` 交叠 52×14），三块演示（默认态 / 带徽章 / 折叠态）全中。根因（族重构 `eb25fee` 引入的回归，两处叠加）：①`menu.html.tpl` 的 `itemHtml()` 把 `kids` 拼在 `.kole-menu-item` 内部，而该项是 `display:flex; height:44px` → 子级成了横向 flex 子项，被塞进 44px 行里纵向溢出；重构前的手写实现是把子级 `appendChild` 到菜单根下当兄弟节点，故无此问题；②`menu.css.tpl` 在 `side` 方向没有折叠规则（只有 `top` 方向有 `display:none` + hover 展开），子级常驻渲染；重构前 `.aa-sidemenu.collapsed .aa-menu-children{display:none}` 存在。修法（单点在唯一真源 `tools/lib/family-impl/nav-menu/menu.css.tpl`，5 端共用一个 CSS，HTML/JSX/Vue 模板不必改）：side 一级项 `flex-wrap: wrap; height:auto; min-height:44px; row-gap:0`；`> .kole-menu-children { flex: 0 0 calc(100% + 32px); margin: 0 -16px; display:none }`（`100%+32px` 与 `-16px` 配套抵消 item 内边距，子级底色与一级同宽 —— 首次用纯 `100%` 实测只有 188px 宽、右侧空 32px）；`.is-open` 时 `display:block`；折叠态用同权重且靠后的选择器压住已点开的项（否则 `.is-open` 以 5 类权重胜出）。验证：几何实测未展开 `display:none` / 展开后子级宽 220 = 侧栏宽且完整落在栏内 / 父项 44→140px / 可见 label 两两无交叠；`top`（hover 展开）与 `mixed`（顶 15 项 + 侧 7 项）未回归；回归 100%（1017/1017，79 页全过，0 超时）复核：修复后本机复测 `node tools/verify-nav-responsive.mjs` → OK（`zh@375px 顶栏无横向溢出` / `无链接文字顶出顶栏` 等全过）；脚本判据未放宽。
S6-P43	测试矩阵缺「布局包含性」断言 —— 本次花屏能带着 100% 回归上线的原因	S6	P1	2 h	✅ 已完成（2026-09-20）：①`tests/_behaviors.js` 新增 verb `layout-menu-rows`（纯几何、无交互，不引入时序抖动），一次查三条不变量 —— 可见叶子文本两两重叠不得超过较小者的 55% / 可见 `.kole-menu-children` 不得越出菜单横向边界 ±2px / `data-collapsed="true"` 时不得露出子级；②`PILOTS` 增 `sidemenu` / `topmenu` / `mixednavigation`（原 6 试点 → 9）；③族模板 `menu.html.tpl` 三个 `<nav>` 各声明一条 → 新增 9 条断言（3 页 × 3 nav）。A/B 反例验证（Chromium）：修复态 9/9 pass；注入旧 CSS（`flex-wrap:nowrap; height:44px; children{flex:0 0 auto; display:block}`）后 `sidemenu` 前两个菜单各 fail 一条，报错与原始花屏逐字对应 —— `文本交叠 kole-menu-label「工作台」 × kole-menu-label「全部订单」重叠 52×14px`；`topmenu` / `mixednavigation` 不受该 side 专用旧 CSS 影响（对照全 pass）。已知边界（写进断言注释）：第三个 nav 是折叠态、标签本就隐藏 → 无可见文本，重叠检查对其空转，该页由第 3 条不变量覆盖。原始记录：`tests/_runtime.js` 的 9 条通用矩阵只查节点存在 / 变体覆盖 / 键盘可达 / ARIA / 对比度 / token 一致性，没有任何判据约束「可见元素是否落在自己的容器盒内、是否压住兄弟节点」—— 于是 S6-P42 那种整块渲染错位被判为全绿（实测：花屏状态下该页断言 13/13 通过）。反例就是 S6-P42 的修复前状态：子级盒子横向越出侧栏 40px、与一级项 label 交叠 52×14，旧判据无一命中。建议新增一条「布局包含性」检查并入通用矩阵：①`[data-assert]` 用例根节点的可见子元素，其外接矩形须落在用例根盒内 ±2px；②同级可见文本节点（叶子元素）两两交叠面积不得超过较小者的 55%（阈值需配反例说明，嵌套父子不算）；先在 `sidemenu` / `topsheet` 这类父子结构组件试点再全量铺开。注意改 `_runtime.js` / `_template.html` 属结构变更，需按铁律 3 重跑 `run-tests.ps1` 再生 79 页并重跑全量回归
S6-P44	`frameworks/sidemenu.html` 大小写命名分裂：Linux 下测试页 iframe 404、生成器会多出第 396 个文件	S6	P1	1 h	✅ 已完成（2026-09-20，修法选 ①「统一到 Pascal」，与 `index.json` 的 `frameworksPrefix`（79/79 全 Pascal）、族生成器输出、`pack-deploy` 的 `frameworks/Button.css` 形制一致）：`git mv` 两步改名（Windows 大小写改名必须经中间名）把 21 个小写演示页统一到 Pascal —— `button/input/select/table/modal/tabs/steps/tree/dropdown/popconfirm/segmented/transfer/rate/slider/collapse` + `treetable/anchornav/listpicker/cascader/employeecard/sidemenu`；`tools/pack-deploy.mjs` 的 `MUST_PRESENT` 里 `frameworks/button.html` → `frameworks/Button.html`；重跑构建让 `site/data.json` 的 `files.html` 跟上（`sidemenu` → `../frameworks/SideMenu.html`）。验证：大小写敏感审计（`data.json.files.html` 与 `tests/<slug>.html` 的 iframe src 逐一与磁盘名做逐字比对）79/79 处不一致 = 0；`frameworks/` 仍 395 文件（`pack-deploy` 硬断言不破）；`gen-family-impl --check` 一致。当初为什么没被发现：Windows 大小写不敏感 —— 生成器写 `SideMenu.html` 会折叠到已有的 `sidemenu.html`，本地看起来"就是那个文件"；两个来源各自自洽（`data.json` 用 `Get-ChildItem` 取磁盘名、测试页用 `frameworksPrefix`），只有 Linux 才暴露 404。原始记录（对照）：事实（2026-09-20 实测） —— `git ls-files frameworks/` 跟踪的是小写 `frameworks/sidemenu.html`，而 `.design_library/kole-ui/components/index.json` 里 `sidemenu.frameworksPrefix = "SideMenu"`、`tools/gen-family-impl.mjs` 按 `frameworks/<Prefix>.html` 写入、`tests/sidemenu.html:64` 的 iframe 也写 `../frameworks/SideMenu.html`；`site/data.json` 的 `files.html` 却是 `../frameworks/sidemenu.html`（`build-site.ps1` 用 `Get-ChildItem frameworks -File` 取磁盘名）。Windows 大小写不敏感，生成物写入折叠到同一个小写文件，本地完全看不出；Linux（容器 / CI）下：①`tests/sidemenu.html` 的 iframe 指向不存在的 `SideMenu.html` → 404；②生成器若在 Linux 跑会新建 `SideMenu.html`，`frameworks/` 变 396 文件，撞 `tools/pack-deploy.mjs` 的「恰好 395（79×5）」硬断言。另有一层：HEAD 里那个小写文件是改名前的 Aurora 旧页（`<title>Aurora Admin · SideMenu…</title>`、`link` 指向 `.design_library/aurora-admin/colors_and_type.css`、类名 `aa-`、零个 `kole-menu`），只因 Windows 上被生成物覆盖才在本地看不见 —— 即 Linux 侧那份是「引用已不存在的 old 目录 + 类名与 CSS 全不匹配」的页面。待补的静态门禁*（本次未加）：引用名与磁盘名逐字比对的检查应常态化（Windows 下也不能靠大小写不敏感蒙过去）
S6-P48	Dockerfile 用通配 COPY 版本快照 → 快照内容合并进站点根、旧构建覆盖新构建、`/<版本>/` 目录不存在	S6	P0	1 h	✅ 已完成（2026-09-20）：现象（发布后逐层核对才发现）：镜像里 `site/data.js` 的 `generated` 是快照那一次的 05:27、`site/style.css` 缺当次新规则、`frameworks/` 多出改名前的 21 个小写演示页（416 而非 395），而 `/<版本>/` 目录根本不存在 → nginx 版本 location 找不到目标 → `/1.4.1/site/` 全 500*（即 S6-P45 的真因，不是 nginx 自循环：目标压根没被 COPY 进去）。根因：`Dockerfile` 写的是 `COPY [0-9].[0-9].[0-9]/ /usr/share/nginx/html/` —— COPY 的源带结尾斜杠时复制的是目录内容，于是每个快照的 `site/`、`frameworks/`、`sitemap.xml`、`index.html` 原地合并进站点根，用旧构建覆盖当次构建；`--no-cache` 也一样（不是缓存问题）。定位手法（可复用）：①比对「构建上下文」与「镜像内」的文件数与指纹（`find … -type f
S6-P49	工作区并发写入会让「打包快照」与「工作树」脱节（本轮实测再次踩到）	S6	P2	2 h	⬜ 待排期：本轮发布期间实测 `site/app.js`、`site/style.css`、`AGENTS.md`、`ROADMAP.md`、`CHANGELOG.md`、`site/m/`、`tests/mobile/` 被另一会话持续改写（mtime 每几分钟一跳），而 AGENTS §九只写了「打包前后各查一次产物哈希」这条人工纪律。建议工具化：①`pack-deploy` 打包后立即重算发布集哈希，与打包时清单比对，有差异就拒绝出包（或打 `--allow-drift` 显式放行并写进清单）；②`verify-deploy` 增加「线上快照 == 本地发布集」的机器判据（当前已有 `tools/lib/publish-set.mjs`，把 2908 个文件的比对结果变成退出码即可）；③两条都进 CI，避免「并发会话把中间态发上线」再次发生（S6-P47 记录的 1883 处不一致就是同一根因的一次实例）
S7-P22	移动端平台上线（平台×端两轴 + 与 PC 物理隔离 + uni-app 端）	S7	P0	1 d	✅ 已完成（2026-09-20，工作区未提交）：移动端 5 组件 × 6 端（`frameworks-mobile/` 30 文件）＋ PC×uni-app 试点 3（`frameworks-uniapp-pc/`）＋隔离门禁 28 断言＋ uni-app 门禁 9 断言＋移动端回归 100%（77/77，含 8 条触控行为断言）＋ PC 回归 100%（1017/1017）连跑 8 次一致。详见下方 S7-P22 任务包与 `PLATFORMS.md`
S7-P23	移动端组件第二批（Popup / Toast / Dialog / Grid / Steps / NoticeBar / NumberKeyboard / DatePicker）	S7	P1	2 d	✅ 已完成（8 / 8，2026-09-20，工作区未提交）：两轮落地 10 个新组件（`Badge` / `Tag` / `Popup` + `Toast` / `Dialog` / `Grid` / `Steps` / `NoticeBar` / `NumberKeyboard` / `DatePicker`），索引 8→18，`frameworks-mobile/` 48→108 文件，规格扩到 §18。移动端回归 270 通过 / 0 失败 / 6 N/A · 18 页，PC 回归 1405/1405 零污染，门禁全绿（隔离 30 条 / uni-app 9 条 × 21 SFC / 文档 12 条 · 24 页 / 站点 118 条 · 21 页），并用 5 个变异探针验证判据有效（B3 硬编码色 / E4 契约-源码脱节 / E4b 必传列 / U5 DOM API / U9 rpx 全部当场捕获）。详见下方任务包 2026-09-20 更新（本轮 /son + /agi）：移动端组件已从 5 推到 36（索引实测），分三批由子 agent 产出 18 个（批次 A icon/layout/link/loading、B avatar/list/collapse/progress、C input/search/switch/stepper/textarea、D form/radio/checkbox/slider/rate），规格 §19–§36、实现 216 文件；另新增可复用合并脚本 `tools/merge-mobile-batch.mjs`，并修掉「行为断言白名单硬编码」的静默缺口（覆盖 5 → 31 个组件）。2026-09-20 二次更新（批次 E/F）：再增 11 个（E: typography/segmented/sticky/overlay/popover/message；F: picker/cascader/colorpicker/upload/table），组件总数 47、实现 282 文件、回归 804/804。仍缺 23 个（2026-09-20 实测）。建议后续批次：批次 I Tabs / DropdownMenu / SideBar / Indexes / Drawer / Guide（导航与容器）；批次 J DateTimePicker / TreeSelect / Upload 已做则跳过 / Calendar（复杂录入）；批次 K Image / ImageViewer / Swiper / QRCode / Watermark / Skeleton（媒体与占位）；批次 L Empty / Result / CountDown / Footer / Fab / BackTop / PullDownRefresh / config-provider（收尾）。（每批 5~6 个，按依赖顺序）：批次 E Typography / Segmented / Sticky / Overlay / Popover / Message（通用与浮层）；批次 F Picker / Cascader / ColorPicker / DateTimePicker / Upload / Table（复杂录入）；批次 G Calendar / Swiper / Image / ImageViewer / QRCode / Watermark / CountDown / Empty / Result / Skeleton（展示类）；批次 H Fab / BackTop / Drawer / Indexes / SideBar / Tabs / TreeSelect / DropdownMenu / Guide / Footer / config-provider（导航与容器）。开工方式：按 `PLATFORMS.md` §四六步走，子 agent 只写自己的文件（不碰 index.json），主 agent 用 `node tools/merge-mobile-batch.mjs` 合并后跑 build + 四门禁 + 双回归（本轮实测单批次约 20–35 分钟）。
S7-P24	移动端文档站增强（i18n 双语 + 移动端 sitemap 片段）	S7	P2	4 h	⬜ 待开工：`site/m/` 是静态站（不进 PC SPA 路由），目前只有中文、且根 `sitemap.xml` 不收录移动端 URL。需：①把 `site/i18n.js` 的字典按命名空间拆出移动端子集（或复用 330 条里的通用词条）；②`tools/build-mobile.mjs` 产出 `site/m/sitemap-mobile.xml` 并决定是否合并进根 sitemap（合并需动 PC 的 `build-site.ps1`，属跨平台改动，须显式决定）
S7-P25	uni-app 端真实编译验证（H5 / 微信小程序 / App 三目标）	S7	P1	3 h	✅ 已完成（2026-09-20）：新增 `tools/verify-uniapp-build.mjs`（11 条断言）—— 在隔离目录装 `@dcloudio` 工具链，搭最小 uni-app 工程把 21 个 SFC（移动端 18 + PC×uni-app 3）全部真实挂载并编译到 H5 与微信小程序。实测：两目标编译通过、产物含 148 / 211 个唯一 `kole-m-` 类名、18/18 组件的契约声明类名都进了产物、小程序产物 0 处 DOM 操作。命令 `npm run verify:uniapp-build`；依赖装在 `.tmp/uniapp-build`（已 gitignore），主仓库 `dependencies` 仍为空。App 端（app-plus）未覆盖：需 HBuilderX 云端打包，命令行无法完成（已在脚本输出里注明）。详见下方任务包与 CHANGELOG
S7-P26	PC × uni-app 全量覆盖（3 / 79 → 79 / 79）	S7	P2	3 d	⬜ 待开工：试点 3 个（button / input / card）已验证「类名与 PC 逐字一致 + `--kole-*` 令牌 + px 尺寸」的转换口径。全量需按组件族分批（表格系 / 表单系 / 导航系 / 反馈系），每批都要过 `tools/verify-uniapp.mjs`；其中 `table`（排序/固定列）、`dragupload`（文件选择）、`signaturepad`（canvas）在 uni-app 端需要独立实现，不能机械转换——建议先出「可行性分级表」（可直接转换 / 需改写 / 平台不支持）再排期
S7-P27	移动端 SEO 薄壳与 canonical	S7	P3	2 h	⬜ 待开工：`site/m/component/<slug>.html` 已是静态可索引页，但缺 canonical 自指、缺 `site/m/components/<slug>.html` 形制的薄壳（PC 侧有 79 个），且根 sitemap 不收录。与 S6-P31（PC 薄壳 canonical/sitemap 指向真实 URL）同源问题，建议合并处理
S7-P28	移动端生成物未被 git 跟踪 + `generated` 时间戳让复现断言脆弱	S7	P2	1 h	⬜ 待开工（2026-09-20 本轮实测发现）：①`git ls-files -- site/m tests/mobile` 实测 0 —— 移动端 154 个生成物全部未入库（对照 PC 侧 `site/components/.html`、`tests/.html` 是被跟踪的），而 CI 的 `Assert mobile artifacts are reproducible`（`regression.yml:84`）用的判据是 `git diff --quiet -- site/m tests/mobile`，对未跟踪文件是空过 → 该断言现在等于没在跑；②`site/m/data.mobile.json` 与 `dist/mobile/manifest.json` 含 `generated: <构建时刻>`，实测两次构建在剥离该字段后逐字节一致（构建本身是确定性的），但字段本身会让「重跑构建 → git diff」永远非空。一旦有人把移动端生成物 `git add`（本来该这么做，才能让复现断言真的生效），CI 会立刻红灯且无法自证清白。修法建议（择一，需显式决定）：把 `generated` 从产物里去掉（或改成从 `package.json` 版本 + CHANGELOG 日期派生），再把生成物入库；或用 `git diff --quiet --ignore-matching-lines='"generated"'` 类判据显式豁免该字段并写明理由

S6-P33 实测数据（2026-09-20，Chromium；口径见 tools/verify-playground.mjs 的断言文案）：

项	修复前（实测）	修复后（实测）
预览帧基准 URL	`http://127.0.0.1:13711/site/`（父页）	`.../frameworks/`
`anchornav` 预览的样式表	`/site/AnchorNav.css` → 404	`/frameworks/AnchorNav.css` → 200
带 `./` 引用的组件	36 个全部丢组件 CSS	36/36 从 `/frameworks/` 取到
帧内 `fetch` / `beacon` / `WebSocket`	被父页 CSP `connect-src 'self'` 拦下（发得出去、读不回响应）	meta CSP `connect-src 'none'` 直接不发
帧内自跳转	帧停在 `chrome-error://chromewebdata/`，状态行仍显示"已同步"	帧回到 `about:srcdoc`，状态行标"已重置预览内的跳转"
切组件丢编辑	静默丢弃	`confirm()`；取消则编辑器与选择器都原地不动
源码拉取失败	`editor.value = ''`（清空用户改的代码）	状态不变、编辑器保留、只报错
站点暗色	预览恒为浅色	帧内 `kole-dark` 生效（`--kole-color-page-bg` = `#14161C`）
外联探针命中	0	0

十 · 2026-09-20 升级验收（发布后，衍生任务与已完成项）

背景：线上更新到 lib=kole-ui / version=2.0.0（快照 generated 2026-09-20 05:27）后做升级验收。 验收通过的部分：部署断言 7/7（specs 目录与单文件 404、根路径 Location: /site/、sitemap.xml 200、 /healthz 单 Content-Type、SPA 深层路由 200、版本 2.0.0）、线上回归 100%（79/79 页、1017/1017 断言、 0 超时）、线上「在线测试」41/41、线上路由 24/24、smoke:site 全过；verify:theme 在本地同版本代码上对照也全过。在线测试那 41 项里最初 3 项失败，定性为"我脚本自己的问题"（mock 路径写死小写、读令牌没等帧），已修成"路径全部从 data.json 派生 + 等到真生效再读"，修完本地与线上都 41/41。

发现的问题分三类：

ID	任务	阶段	优先级	预算	状态
S6-P45	nginx 版本快照 location 在目标缺失时自循环 → 500（应干净失败）	S6	P2	1 h	✅ 已解决（真因是 S6-P48，非 nginx）（2026-09-20）：发布后逐层核对确认 —— 快照的 `site/` 之所以缺失，是因为 `Dockerfile` 用通配 COPY 把快照内容合并进了站点根、压根没建 `/<版本>/` 目录（见 S6-P48）。改为逐版本显式 COPY 后，`/1.4.1/site/index.html`、`/1.4.1/site/component/button/h5`、`/1.4.1/frameworks/Button.css` 线上实测全部 200（修复前 896 个文件全 500）。原始诊断（保留作对照）：`nginx.conf` 的 `location ~ ^/([0-9]+\.[0-9]+\.[0-9]+)/site/ { try_files $uri $uri/ /$1/site/index.html; }` —— 当该版快照的 `site/` 缺失时，回落目标本身也 404 → 内部重定向回到同一 location → 自循环 → nginx 报 500，而正常语义应是 404。线上实测：`/1.4.1/site/` 896 个文件全部 500，而 `/1.4.1/frameworks/`、`/1.4.1/sitemap.xml`、`/1.4.1/VERSION.json` 都是 200（即发布的快照只缺 `site/` 这一块）。仍建议（未做，属健壮性而非本次缺陷）：改用 `error_page 404 = /$1/site/index.html;`（`recursive_error_pages` 默认 off，回落再 404 就以 404 收场），或给回落目标加存在性判据 —— 这样将来真出现「快照缺 site/」时是 404 而不是 500。已做：打包期完整性断言由 `pack-deploy` 承担（每个 `<x.y.z>/` 快照必须同时含 `site/index.html` 与 `frameworks/`，本次断言全过）。同批修掉的相邻缺陷：①版本裸入口的 302 目标 —— 注释写「送到该版站点」而代码是 `return 302 /site/`（现行版本）、正则未捕获版本号 → `/1.4.1/` 与 `/1.4.1/index.html` 把访问者带到现行文档；改为 `return 302 /$1/site/`（与 dev-server 的 `verRoot` 一致），线上实测 `Location: /1.4.1/site/`；②`verify-deploy-consistency.mjs` 对「nginx 故意 302 的路径」报假滞后（比对的是 302 响应体 vs 磁盘文件）→ 根 `/index.html` 与 `/<x.y.z>/index.html` 改为跳过并单独计数
S6-P46	`verify-theme.mjs` 在远程（`REG_BASE=` 公网）下产生时序假失败	S6	P3	1 h	⬜ 待排期：iframe 主题断言在 `goto(load)` + 150 ms 后直接读 `f.contentDocument.documentElement.classList`，不等演示帧加载完 —— 公网下演示页与令牌 CSS 比文档慢，此时 `contentDocument` 还是 `about:blank`，`classList.contains('kole-dark')` 恒 false → 报「iframe 主题同步」失败（本地有缓存/瞬时，对照 3 次全过；线上 2~3/3 失败，同批其它断言全过）。判据本身没错，缺的是等待：应轮询 `readyState === 'complete'` 后再断言，或重试到超时。同类：`菜单选择夜间模式` 单次 flake（交互后立即读，无等待）
S6-P47	发布快照与工作树的一致性核对（工具化）	S6	P1	2 h	✅ 已完成（2026-09-20）：新增 `tools/verify-deploy-consistency.mjs`（`npm run verify:deploy`，零依赖）+ 发布集抽成 `tools/lib/publish-set.mjs` 供打包器与核对脚本共用（`.dockerignore` 仍是规则真源；`pack-deploy` 重构前后输出逐字节一致，其自带断言 13+34 全过）。实测线上：2908 个可比对文件里 1883 个不一致（滞后 917 / 缺失 966）——`site/components/` 395、`1.4.1/site/` 896（缺失 → 上条 500 的来源）、`1.4.1/frameworks/` 395（在但旧）、根 `versions.json` 404（在线版本菜单的数据源缺）、`site/style.css` 落后（375px 下语言切换器被挤出顶栏，实测宽 0，本地已修但未发布）。结论：本次线上快照是工作树的一个中间态**，与 AGENTS §九的并发写入警告吻合（验收期间实测 `site/app.js` 被另一进程持续重写）

附 · 规划修正记录

执行中发现规划与实际不符时，以实测为准，在此登记。

日期	任务	规划原写	实测	处理
2026-09-11	P4	`data.js` 目标 < 400 KB（推测 `sources` 是最大头）	`sources` 实测占 89.6%（888KB/991KB）；拆出后可达 ~110KB	目标改为 < 150 KB，策略与体积数据全部替换为实测
2026-09-11	P4	预计算 API 表估算 < 30 KB	实测 1.0 KB（比估算乐观 30 倍）	更新为实测值
2026-09-11	P2	包名可用性未知	registry 查询：`aurora-admin-design` 未被占用	补入「前置验证已完成」
2026-09-20	v2.0.0 改名	「包名可用性」这类对外实测事实会随批量改名被一起改写，从而由事实变成未核验的断言	全仓替换后自查发现：`aurora-admin-design` 的查验结果与发布记录被改写成了 `kole-ui`（含 CHANGELOG 发布表、README「三个发布名」、本文件 S5-P21 行）	以实测为准：① 对 `kole-ui` 重新实测公共 npm（未被占用）+ 私有源（无此包）；② 把记录历史事实的位置还原为当时的真实名字并加注对照；③ `tools/migrate-brand-kole-ui.mjs` 增 `--only=` 限定规则，避免全量重跑再破坏刻意保留的旧名对照表
2026-09-11	P4	只说「改成 fetch」，未识别难点	`app.js` 有 10 处消费 `sources`，其中 2 处是渲染期同步解析	补入「依赖分析」与三阶段执行建议

附 · S7 移动端任务包（平台 × 端）

起因：用户要求「在组件库额外添加移动端组件（移动端和 PC 端隔离）」，并明确「PC 和移动是两个大分类，移动端后面是 H5 移动端、Vue 移动端，而且 uni-app 也会经常用到（uni-app 移动端 / uni-app PC 端）」。据此把组件库组织成两轴：平台 pc|mobile × 端 css|html|jsx|vue2|vue3|uniapp。契约与流程见新增的 PLATFORMS.md（本文件 S7-P22 是它的落地任务）。

S7-P22 · 移动端平台上线｜预算 ~1 天｜优先级 P0 ｜ ✅ 已完成（2026-09-20，工作区未提交）

依据：用户要求；且 PC 侧组件清单（79 个中后台组件）与移动端需要的组件天然不同（触屏优先）。

做了什么：

两轴模型 + 隔离契约 → PLATFORMS.md（平台 / 端定义、目录与命名映射表、隔离规则、新增组件六步流程、现状与未覆盖清单）。
移动端规格原文（无外部规范，本仓库自撰，作为契约唯一授权来源）→ .design_library/kole-ui-mobile/spec/移动端规格.md（§〇隔离总则 + 5 组件各一节：用途/结构/变体维度/状态/交互与触控/无障碍/doNotInvent/unknowns）。
移动端令牌层 → .design_library/kole-ui-mobile/colors_and_type.css：@import PC 令牌 + 15 个 --kole-m-*（触控 44px / 安全区 @supports (env()) / 移动端字号 / 手势动效）。PC 令牌文件零改动。
5 个移动端组件 × 6 端 = 30 个实现文件 → frameworks-mobile/：
- navbar（顶部导航栏）tabbar（底部标签栏）actionsheet（动作面板）pullrefresh（下拉刷新）swipecell（滑动单元格）
- 每组件 6 端：css / html（演示页）/ jsx / vue2.vue / vue3.vue / uniapp.vue
5 份契约 + 索引（含 files 逐端声明、uniappTargets、隔离规则块、provenance: authored-in-repo）→ .design_library/kole-ui-mobile/components/。
PC × uni-app 端试点 3 个 → frameworks-uniapp-pc/{Button,Input,Card}.uniapp.vue + .design_library/kole-ui-uniapp/index.json（类名与 PC 逐字一致、--kole-* 令牌、px 尺寸、目标 H5/PC 容器）。
构建（Node，跨平台，不碰 PS 链）：
- tools/build-mobile.mjs → site/m/data.mobile.json（自包含 102 KB，5 × 6 端源码）、site/m/index.html、site/m/component/<slug>.html、tests/mobile/<slug>.html、tests/mobile/index.html、dist/mobile/**。写入守卫：只允许写 site/m/ tests/mobile/ dist/mobile/。
- tools/build-uniapp.mjs → dist/uniapp-pc/**（守卫只允许写该前缀）。
测试：移动端测试页（375×640 设备帧）+ 收集器 tests/mobile/_collect.html（读 site/m/data.mobile.json）+ 移动端行为库 tests/mobile/_behaviors.js（新增 3 个触控动词 swipe-sets-class / swipe-sets-attr / pull-triggers）；断言引擎与 PC 共用 tests/_runtime.js。
门禁：tools/verify-mobile-isolation.mjs（28 断言：PC 零污染 / 移动端自洽 / 分发隔离）、tools/verify-uniapp.mjs（9 断言 × 8 个 SFC）、tools/run-mobile-regression.mjs。
接入：dev-server 白名单（frameworks-mobile、frameworks-uniapp-pc）、Dockerfile 两条 COPY、.dockerignore（移动端规格不进镜像）、pack-deploy.mjs（CONTENT_DIRS + 6 条新硬断言）、package.json（exports 两套 + 6 个 scripts）、regression.yml（构建 + 可复现性断言 + 两条门禁 + 移动端回归 + 报告上传/摘要）。

验收输出（原样粘贴）：

$ node tools/verify-mobile-isolation.mjs
[OK] 隔离门禁全部通过（28 条断言）
  A1 frameworks/ 仍为 395 个实现文件 | A2 PC 索引仍为 79 | A5 PC 面零 kole-m- 命中（扫描 909 文件）
  A6 PC 面零移动端目录引用 | A7 PC 测试页仍为 79 | A8 slug 无撞名 | A10 tests/report.json 页数仍为 79
  B1 移动端 5 × 6 端文件齐全（30） | B3 CSS 前缀与令牌合规 | B5 演示页令牌与结构合规 | B7 生成物齐全（19 项）
  C1 PC 样式聚合无移动端类 | C3 manifest 组件数与索引一致 | C7 exports 含两套入口（26 条）| C8 零运行时依赖

$ node tools/verify-uniapp.mjs
[OK] uni-app 门禁全部通过（9 条断言 · 8 个 SFC）
未执行：uni-app 真实编译（H5 / 小程序 / App 三目标）—— 需 npm 依赖，见文件头部复现命令

$ REG_BASE=http://127.0.0.1:13511 node tools/run-mobile-regression.mjs
passRate 100% | pages 5 (all-pass 5) | assertions 77/77
[OK] 移动端全部通过

# 触控行为断言逐条（Chrome 实测打印）
[swipecell] 断言 17 条 · 行为断言 3 条 → swipe-sets-class / swipe-sets-attr / swipe-sets-class 全 pass
[pullrefresh] 断言 15 条 · 行为断言 1 条 → pull-triggers pass
[tabbar] 断言 15 条 · 行为断言 1 条 → tab-switches pass
[actionsheet] 16 条 · 2 条行为（click-toggles-class / click-sets-attr）pass ｜ [navbar] 14 条 · 1 条 pass

$ node tools/run-regression.mjs   # PC 侧，改动后连跑 8 次
run 1..8: passRate 100% | pass 1017 | fail 0 | na 34 | pages 79/79 | timedOut 0   ← 8 次完全一致

$ node tools/pack-deploy.mjs
[pack-deploy] OK
  components : 79 个薄壳 / frameworks 395 个实现文件
  mobile     : 30 个实现文件（5 组件 × 6 端）/ 文档页 5 / 测试页 5
  uniapp-pc  : 3 个试点 SFC（PC × uni-app）
  断言       : 排除项 13 条全部未出现；必需项 33 条全部存在

规划偏差：

用户原话只说「移动端组件 + 与 PC 隔离」；执行中发现真正的结构是两轴（平台 × 端），且 uni-app 是一个端（在移动列与 PC 列各有一份实现），因此把「隔离」上升为两轴模型 + 双目录 + 双索引，而不是单个 frameworks-mobile 目录。
build-site.ps1 是 ASCII-only + Windows-only，没有把移动端接进去，改为新增 Node 构建脚本（跨平台、可写守卫），符合 ROADMAP 0.3「PS 脚本若 CI 需要构建则改写为 Node」。
移动端文档站没有做进 PC 的 SPA 路由表（site/app.js），而是独立静态站 site/m/；理由：改 SPA 会同时动 PC 的路由/侧栏/i18n 三处，隔离收益为负。

发现的新问题（已登记，未在本任务顺手修）：

S7-P23：移动端组件第二批（Popup/Toast/Dialog/Grid/Steps/NoticeBar/NumberKeyboard/DatePicker）。
S7-P24：移动端文档站 i18n 与会话/sitemap 增强。
S7-P25：uni-app 真实编译验证（本次只做静态门禁，未执行真实编译）。
S7-P26：PC × uni-app 全量覆盖（3 / 79），需先出可行性分级表。
S7-P27：移动端 SEO 薄壳与 canonical（与 S6-P31 同源）。

回归：PC 100%（1017/1017，N/A 34）/ 八次连跑一致 / 0 超时；移动端 100%（77/77）/ 0 超时。

S7-P23 · 移动端组件第二批｜预算 ~2 天｜优先级 P1 ｜ ✅ 已完成（8 / 8，2026-09-20，工作区未提交）

依赖：S7-P22 ✅（流程与门禁已固化）。

本任务已完成（两轮共 10 个组件 / 计划 8 个，超额 2 个）：

第一轮（弹出层基座 + 展示系 3 个）：Popup / Badge / Tag（规格 §9 / §10 / §11）。索引 8 → 11；颜色零发明（实心底 + text-inverse 亮色 5.57–5.87:1 / 暗色 5.64–8.24:1）。

第二轮（7 个，本轮 AGI）：Toast / Dialog / Grid / Steps / NoticeBar / NumberKeyboard / DatePicker （规格 §12~§18，本轮新写 7 节规格作为契约授权来源）。索引 11 → 18； frameworks-mobile/ 66 → 108 文件（18 × 6 端）；移动端回归 172 → 270 通过 / 0 失败 / 6 N/A · 18 页。

Toast（§12）：tone 五语气 + position 三位置 + mask；容器 role=status + aria-live=polite 朗读一次； loading 态图标旋转并在 prefers-reduced-motion 下停止。深底 + 反色文字 15.78:1（亮）/ 15.00:1（暗）。
Dialog（§13）：variant = confirm / alert + tone = danger + round；closeOnMask 可关； role=dialog + aria-modal + aria-labelledby；卡片底 + 正文色 15.13:1 / 10.34:1。
Grid（§14）：columns 2/3/4 + border + square；可点格子是原生 button（整块热区 + 键盘可达）， static 格子不绑交互（避免「鼠标专用交互」缺口）；按下反馈用 :active（触屏无悬停）。
Steps（§15）：direction 横/纵 + status 四态；role=list/listitem + aria-current=step； 状态不只靠颜色（进行中加粗、已完成用勾选字符、失败用感叹号）。
NoticeBar（§16）：tone 四语气 + scrollable 跑马灯 + closable； 无障碍硬要求落地：prefers-reduced-motion: reduce 下停止滚动并改为换行（滚动内容不用 aria-live）。
NumberKeyboard（§17）：type = number / digit + showDelete + showConfirm + confirmDisabled；键盘不持有输入值，只 emit 按键事件（数字键回传字符 / 删除键回传 'delete' / 确认回传 'confirm'），写入哪个输入框由宿主决定。
DatePicker（§18）：mode = date / month + round + closeOnMask；三列 role=listbox/option + aria-selected；年份范围由宿主传入（years / months / days），不发明可用年份区间。

判据有效性验证（5 个变异探针，全部当场捕获）：向 CSS 注入硬编码色 → B3 报出文件与色值；契约加假 prop → E4 逐端报「源码里没有」；把有默认值的 prop 标 required → E4b 逐端报「应相反」； uni-app 端注入 document.querySelectorAll → U5 报出两条规则；uni-app 端去掉 rpx → U9 报「未使用 rpx」。

顺手修掉：tools/pack-deploy.mjs 输出文案与 site/m/_design_template.html 里写死的组件数（前一批 8 个组件落地时漏改）—— 现分别改为读索引与构建期占位符。

路径：.design_library/kole-ui-mobile/spec/移动端规格.md（追加节）、.design_library/kole-ui-mobile/components/{index.json,<slug>.json}、frameworks-mobile/<Prefix>.{css,html,jsx,vue2.vue,vue3.vue,uniapp.vue}。

步骤：按 PLATFORMS.md §四六步走。建议分三批：①弹出层系 Popup → Toast → Dialog（共享遮罩/动效，可先抽共享常量到规格里）；②展示系 Grid / Steps / NoticeBar；③输入系 NumberKeyboard / DatePicker。

验收：

node tools/build-mobile.mjs && npm run verify:isolation && npm run verify:uniapp
REG_BASE=http://127.0.0.1:13511 npm run regression:mobile   # 期望 100%，页数 = 索引组件数
node tools/run-regression.mjs                              # PC 侧仍 100%（防污染）

失败判据：移动端回归出现任一 fail；PC 回归断言总数（1405）发生变化；隔离门禁 frameworks-mobile 文件数断言不再是 组件数 × 6。

S7-P24 · 移动端文档站增强（i18n 双语 + sitemap 片段）｜预算 ~4 h ｜优先级 P2

路径：site/m/_index_template.html、site/m/_component_template.html、tools/build-mobile.mjs、site/i18n.js（只读复用或抽子集）。

步骤：①移动端页面文案抽成字典（可与 PC 的 330 条共用通用词条，命名空间 mobile.*）；②build-mobile.mjs 产出 site/m/sitemap-mobile.xml；③是否合并进根 sitemap.xml 属跨平台决定（要动 PC 的 build-site.ps1），先出结论再改。

验收：node tools/verify-i18n.mjs（PC 覆盖面不下降）；curl -s http://127.0.0.1:13511/site/m/sitemap-mobile.xml | grep -c '<url>' 等于移动端页面数。

S7-P25 · uni-app 真实编译验证｜预算 ~3 h ｜优先级 P1

路径：新增 tools/verify-uniapp-build.mjs + .github/workflows/ 新增独立 job。

步骤：拉官方模板工程（dcloudio/uni-preset-vue#vite）→ 把 dist/mobile/uniapp/*.vue 与 dist/uniapp-pc/*.vue 拷进去 → npm run build:h5 + npm run build:mp-weixin → 断言产物存在、无编译错误。依赖不复用主 job（避免给主回归加 @dcloudio 依赖）。

验收：node tools/verify-uniapp-build.mjs → 输出三目标产物路径与大小；mp-weixin 产物里出现 kole-m- 类名。

失败判据：任一目标编译报错；或产物里出现 DOM API 调用（说明静态门禁漏了）。

S7-P26 · PC × uni-app 全量覆盖（3 / 79）｜预算 ~3 天｜优先级 P2

路径：frameworks-uniapp-pc/、.design_library/kole-ui-uniapp/index.json、tools/build-uniapp.mjs（manifest 的 coverage）。

步骤：①先出可行性分级表（可直接转换 / 需改写 / 平台不支持）：table（排序+固定列）、dragupload（文件选择）、signaturepad（canvas）、qrcode（canvas）、imagepreview（手势缩放）属"需改写"或"不支持"；②按组件族分批转换，每批过 verify:uniapp；③每批更新 coverage 与 PLATFORMS.md 的矩阵表。

验收：

npm run build:uniapp && npm run verify:uniapp
node -e "const m=require('./dist/uniapp-pc/manifest.json');console.log(m.coverage)"
# 期望 implemented 随批次递增，最终 = 79；total 始终 79

S6-P49 · PC 组件页「逐示例用法代码」（一个使用场景 = 一块预览 + 一块调用代码）｜预算 ~1 天｜优先级 P1 ｜ ✅ 已完成（2026-09-20，工作区未提交）

起因（用户实测反馈）：对照 Element Radio 单选框 文档页 —— 组件文档应当直接给出 <el-radio disabled v-model="radio" label="选中且禁用">备选项</el-radio> 这样的调用写法，而不是把整份实现文件摊给使用者；且「单个使用场景对应单个代码块」。原形态「一个整页 iframe + 展开看整份实现文件（Button.html 117 行 / Button.jsx 66 行）」让人从实现反推调用方式。

路径：tools/lib/demo-examples.mjs（新建：切场景 / class↔prop 映射 / 四端片段生成）、 tools/precompute.mjs（新增阶段 F）、site/app.js（buildExampleCard / fillExamples）、 site/style.css（.ex-*）、site/i18n.js（新增文案）、site/examples/<slug>.json（生成物）、 tools/verify-examples.mjs（新建门禁）、tools/pack-deploy.mjs（必需文件加 site/examples/button.json）。

硬约束（决定了实现形态）：

预览不能靠切 HTML 造 —— 演示脚本对节点有索引依赖（resultvariants 的 DATA[i]、modal 的 #mount），所以改为「iframe 载原始演示页 + 其它场景 display:none」（隐藏计划在构建期按 body 元素下标算好）；
片段里的 prop 名必须能指到 API 表 / 源码参数表，class 必须在该组件 CSS 里存在（不发明）；
site/data.js 只留目录，示例正文按组件懒加载（保住 P4 的瘦身成果），data.json 保持完整示例。

验收：

npm run build:site && npm run verify:examples     # 9 条断言（prop 可溯 / class 存在 / 隐藏路径可解析 / 目录一致）
KOLE_PORT=3399 node site/dev-server.js &
REG_BASE=http://127.0.0.1:3399 node tools/run-regression.mjs   # 100%（本机实测 103/103 页、1405/1405 断言）
npm run verify:theme && npm run verify:i18n && npm run smoke:site

实测结果（2026-09-20）：194 个场景 / 776 个片段；demo-mapped（演示页逐字映射）69 条，其余为 demo-data（演示数据 + API 表）与 api-derived（依据 API 表推导，卡片右侧标注出处）。回归 100%（103/103 页、1405/1405 断言），八次连跑一致；主题对比度门禁因代码区常显而暴露的暗色问题已一并修掉（hl-tag 2.70:1 → 8.24:1）。

S7-P27 · 移动端 SEO 薄壳与 canonical ｜预算 ~2 h ｜优先级 P3

路径：tools/build-mobile.mjs（生成 site/m/components/<slug>.html 薄壳 + canonical）、根 sitemap.xml 生成路径。

步骤：与 S6-P31 合并处理（PC 薄壳 canonical/sitemap 指向真实 URL 的同一决定）。移动端 canonical 自指 site/m/component/<slug>.html。

验收：ls site/m/components/*.html | wc -l = 组件数；grep -c 'rel="canonical"' site/m/component/*.html 每页 1 条且自指。 | 2026-09-11 | P2/P4 | 验收命令有 3 处会误判（npm 不可用时误报 OK 等） | 实测触发 | 已改写为显式判断 exit code | | 2026-09-19 | PLAN §7/§8 | 「不改 site/dev-server.js（已工作良好）」 | 单个 GET /site/%00 触发 ERR_INVALID_ARG_VALUE 未捕获异常，进程退出 | 以实测为准：修复该文件（NUL 双重拦截 + readFile try/catch + KOLE_PORT），并新增 tools/verify-dev-server.mjs（20 checks / 3 条反例断言）；PLAN 两处已标注 ⚠️ 规划修正 | | 2026-09-19 | 部署方式 | 未规定（实际为手工拷贝到 /opt/kole-ui） | 手工拷贝导致 ① .dockerignore 未随行 → 规范原文入镜像并对外 200；② 曾修好的 absolute_redirect off 被覆盖丢失 | 新增任务包 S5-P13：以 .dockerignore 为唯一真源的 tools/pack-deploy.mjs + AGENTS §九标准流程；2026-09-19 已按该流程实际部署并验收 | | 2026-09-19 | TESTING 基线 | 1009 通过 / 35 N/A / 共 1044 条断言 | 工作树实测 1017 通过 / 0 失败 / 34 N/A / 共 1051（连跑 10 次一致） | 更新 TESTING.md 与 AGENTS.md §八的数字并标注口径来源 | | 2026-09-20 | S1-P2 | 目标写「能拿到令牌 + 组件样式」，据此实现为 CSS/HTML 分发包 | 用户预期是组件库（import { KoleButton } from '.../vue3'）；实测 dist/ 无任何可 import 组件，main 指向 CSS 文件 | 以用户预期为准：补三端入口 + exports + peerDependencies，登记为 S5-P18 并已完成。原 S1-P2 验收命令全部仍通过，未破坏既有承诺 | | 2026-09-20 | 5 端实现 | AGENTS 写「79 组件 × 5 端实现」 | 真编译时发现 RangeQuickPicker（React/Vue3）与 CodeInput（Vue3）无法编译——此前从未真编译过，结构断言测不出 | 已修；新增 tools/verify-package-import.mjs 的编译级检查（真编译 + 真渲染）防止复发 | | 2026-09-20 | Q6 / S2-P5 | 未解问题 Q6 把「暗色下演示 iframe 是否反色」记为设计取向待定（两种都有道理） | 实测 iframe.contentDocument === null：sandbox="allow-scripts" 帧是不透明源，父页读不到 → injectIframeTheme() 恒在 if (!d) return 静默返回；frameworks/ 亦无 kole-mode 命中 | 不是取向问题而是机制从不生效：CHANGELOG v1.1.1「演示 iframe 注入 kole-dark 同步反色」属声称≠实现；登记为 S5-P23（只登记不修，方案需动 79 个演示页） | | 2026-09-20 | S5-P23 / S6-P33 | 「在线测试页的预览帧保持浅色」记为有意保留的差异 | 那次反不了色的原因是机制限制（帧是不透明源，父页注入不进 kole-dark），不是取向；而 S5-P23 已把演示原页的取向定为「站点暗色时演示页也反色」 | 以一致性为准：在线测试页唯一可用的注入点是源码本身，改在注入内容里带类，预览与详情页演示帧取向一致（实测帧内 --kole-color-page-bg = #14161C）；site/playground.js 头部注释与本文档 S6-P33 行同步改写 |

| S6-P42 | 顶栏在 375px 溢出 23px（新增版本选择器后） | S6 | P1 | 30 min | ✅ 已完成（2026-09-20；⚠️ 本编号与表内另一条 S6-P42「侧边菜单花屏」重复，待人工重编号）：双侧修法并存且互补 —— ①`site/style.css` 的 `@media (max-width: 560px) { .ver-select-wrap { display: none !important } }`（窄屏收起版本选择器，注释已写明「优先保主题与语言两个常驻控件」）；②`@media (max-width: 600px) { .ver-select-wrap{padding:0 6px} #ver-select{max-width:68px} }`（版本号保留、只截掉「· 最新版」半截，完整文案仍在 title/aria-label）。为什么需要 ②：只按 ≤560 收起的话，561–593px 这一档仍溢出（实测最多 33px，594px 起才归零）—— 因为框架选择器在 >560px 复现、而版本选择器又长回 122px。验证：逐像素扫描 320–900px × 中英双语，`.topbar-inner` 溢出量全为 0（改动前 375px=23/19px、360px=34px）；`npm run verify:nav` 349 项全绿、退出码 0。原始记录：2026-09-20 实测 `node tools/verify-nav-responsive.mjs` —— `zh@375px 顶栏无横向溢出（实测 23px）` / `en@375px（19px）`，390px 为 8px；420px 及以上为 0。归因（逐个元素注入 `display:none !important` 后测 `scrollWidth-clientWidth`）：顶栏非收缩子项之和超预算 —— 逐个隐藏 `.lang-select`(56px) / `.ver-select-wrap`(122px) / `.theme-select`(34) / `.search-trigger`(34) / `.logo`(32) / `#nav-toggle`(34) 中任意一个都能把溢出归零，`.topnav`(315–320px) 是唯一可收缩项（`flex-shrink:1`）但已到下限。新出现的 `.ver-select-wrap`（版本选择器，122px）是并行会话顶栏改动的产物，也是最大增量。建议修法（沿用同文件既有模式）：在 `@media (max-width: 560px)` 里把 `.ver-select-wrap` 与 `.fw-select-wrap` 一起收起（该页注释已写「窄屏优先保常驻控件」），或按 index.html 注释的原意「只有一版时整块不显示」在 JS 侧收起。注意：这是未提交的顶栏改动引入的，非本次文档站改造；脚本判据不放宽 —— 布局修好前该门保持红灯 |

附 · 2026-09-20 图标系统衍生任务包（本次实测发现，未在原任务范围）

S8-P1 · `verify-emits-parse.mjs` 的文件数期望值陈旧（158 → 动态推导）｜预算 ~15 min ｜优先级 P2

实测：node tools/verify-emits-parse.mjs → exit 1，FAIL 扫描到的 Vue 实现文件数量与预期一致（158） — count=206。

根因：第 166 行硬编码 vueFiles.length === 158，即「79 组件 × 2 个 .vue」。 S6-P21（commit eb25fee）把组件从 79 增到 103 后，实际是 103 × 2 = 206，常量没跟着改。第 262 行的构建期副本比对同样写着 158。该 FAIL 在本次图标任务之前就存在 （git show HEAD:tools/verify-emits-parse.mjs 确认 HEAD 上就是 158，本任务未触碰该文件）。

为什么不能只改数字：写死组件数会重复同样的失效模式（下次组件增减又红）。应当从唯一真源推导：

验收：

node tools/verify-emits-parse.mjs; echo "exit=$?"
# 期望：exit=0，且输出里的期望值来自索引推导而非字面量
node -e "
const idx=require('./.design_library/kole-ui/components/index.json');
const n=idx.components.length*2;
console.log('期望 .vue 文件数 =',n);
"

判据：脚本里不再出现裸的 158；grep -c '158' tools/verify-emits-parse.mjs 为 0（注释里的历史说明不算，需改写为「曾为 158」的措辞）。

S8-P2 · `verify-cross-platform.mjs` 把图标数据表误判为组件类名（富噪声）｜预算 ~1 h ｜优先级 P2

实测：node tools/verify-cross-platform.mjs 报 icon 为 high，540 条 diff 里 533 条是注入的图标数据（图标名如 add / bell / fragment 与 viewBox 键被类名提取器当成类），真实组件类只有 7 条且全是 H5 演示脚手架类。四端真实类集合逐字一致（13 个 kole-icon-icon* 类完全对齐）。

根因：该门禁的类名提取正则扫端源码全文，而图标端实现按 ICON-SPEC.md §五 的设计 把数据内联进端文件（/* === KOLE_ICON_TABLE:BEGIN === */ 标记块内是单行 JSON）。这是冻结规格的必然结果，不是实现缺陷 —— 但门禁必须学会跳过它。

修法：提取类名时先剔除 KOLE_ICON_TABLE:BEGIN/END 之间的内容（与 tools/verify-uniapp.mjs 剥注释的手法同源）。判据不放宽，只是把「非类名的数据」排除出测量对象。

验收：

node tools/verify-cross-platform.mjs; echo "exit=$?"
# 期望：icon 的 diff 数从 540 降到个位数（仅真实脚手架类），其余组件结论不变

S8-P3 · 组件5 的 46 个工具/模板组件从未实现（含 `IconPreview`，本次已补）｜预算 ~3 天｜优先级 P3

实测：.design_library/kole-ui/specs/组件5.txt 声明 47 个组件， index.json 里只命中 1 个 —— 其余 46 个（页面模板 7 / 组合组件 16 / 业务组件 20 / 工具组件 4：ColorContrastChecker / ComponentDemo / DesignTokenViewer / VersionInfo）全部未实现。 ROADMAP 与 AGENTS.md 此前完全未提及这批组件，属规划盲区。

本次已补：IconPreview（site/icon-preview.html，2574 图标网格 + 搜索 + 复制名称/SVG + 四档尺寸 + 仅线性过滤；入口挂在图标组件页的代码条 footer 与 i18n 双语）。为何走独立工具页而非 frameworks/ 组件： frameworks/ 文件数被隔离门禁 A1 卡死为「组件数 × 5」，加一个组件要一次补齐 5 端 + 契约 + 测试页；而 IconPreview 是文档站工具（规范列在「工具组件」节），与 site/playground.html 同性质。批量实现这 46 个之前，先决定它们是走 frameworks/ 正式组件还是 site/ 工具页 —— 这条决策会影响后续 103 → 149 的组件计数与全部门禁基线。

S8-P4 · 品牌标识（favicon / logo）此前缺失且残留旧品牌字母｜预算 ~2 h ｜优先级 P1 ｜ ✅ 已完成（2026-09-20，工作区未提交）

实测（本次发现）：

favicon 里是旧品牌字母「A」 —— site/index.html:41 的内联 data-URI 用的是 <text ...>A</text>（Aurora Admin 遗留）。v2.0.0 改名（CHANGELOG ## [2.0.0]）把文字品牌名、类名、令牌、包名都换了，但这个字母没跟着换。
PC 顶栏 logo-mark 也是「A」（site/index.html:48），而移动端站 tools/build-mobile.mjs 已是「K」—— 同一次改名在三处留下两种状态。
移动端文档站完全没有 favicon：site/m/ 下 7 个 _*_template.html 的 rel="icon" 计数为 0 → 浏览器标签页显示默认地球图标。
全仓零 .svg / .ico 资产文件（find 排除 node_modules 命中 0）；无 theme-color、无 og:* / apple-touch-icon / web manifest。
hero 标语仍是「KOLE ADMIN DESIGN SYSTEM」（site/app.js:562）—— 同一改名的变形残留。

本次改动（品牌标识 = 页面 chrome，与 Icon 组件的通用图标集是两回事，不混用 ICON-SPEC 的 registry）：

几何：24 网格、三个互不接触的笔画组成的 K（寓意「独立组件拼组成系统」），描边 2.25 → 16px 标签页尺寸下正好 1.5px，等于规范原文「线性图标，描边1.5px」（组件1.txt:60）。
单一几何真源：site/index.html 的 favicon、顶栏标记，与 tools/build-mobile.mjs 的 BRAND_PATHS / BRAND_MARK / BRAND_FAVICON 是同一份路径数据。
取色分两套（刻意，不是不一致）：favicon 硬编码 #2F54EB + #FFFFFF —— 它渲染在浏览器标签栏，不继承 html.kole-dark，走令牌会在浅色标签栏上变成「亮蓝底 + 近黑标记」（暗色下 --kole-color-text-inverse = #14161C）；两端顶栏标记走 currentColor → 实测暗色下自动解析为 rgb(20,22,28)，令牌化行为保真。
新增 theme-color 双条（light #FFFFFF / dark #1C1F26，取 --kole-color-card-bg，即 .topbar / .m-top 的 background，色值与视觉连续）。PC 在 site/index.html，移动端走新增的 __BRAND_HEAD__ 占位符由 7 个模板统一注入。

实测（浏览器，Chromium）：PC 顶栏 .logo-mark 32×32 盒模型不变、svg 20px、 stroke 解析为 rgb(255,255,255)；移动端 26×26 盒 / 17px 标记；暗色下两端背景转 rgb(107,140,255)、前景/描边转 rgb(20,22,28)；>A< 在页面 DOM 中已清零； PC 站控制台错误从 1（favicon 404）降为 0。

门禁：verify-site-routing OK（103 / 412 / 521）· verify-site-routes OK · verify-mobile-docs OK（12 条 · 53 页）· verify-mobile-site OK（263 条 · 50 页，控制台 0 错误）· verify:isolation OK（31 条）· verify:theme OK · verify:nav OK · verify:i18n OK（16 条）。回归：PC 1464/1464 · 移动端 807/807，各连跑 8 次一致。

未做的部分（建议独立任务包）：og:image（1200×630）、apple-touch-icon（180×180）、 site.webmanifest 需要位图资产管线 —— 仓库目前零位图资产，且 .dockerignore 有 **/*.png 排除规则、.gitignore 也有 /*.png，引入 PNG 要同步改两处配置并补 !site/assets/*.png 反向规则。本次先把 SVG 品牌标识做实。

过程中踩到的门禁（已修）：A6「PC 面零移动端目录引用」被 site/index.html 的注释触发 —— 注释里写了 site/m/ 字样。这与 AGENTS.md §七「静态门禁把注释当成违规代码」是同一类问题，本次改写措辞规避（判据未放宽）。

后续重构（2026-09-22）：品牌几何已收归 .design_library/kole-ui/brand/brand-mark.json，由 build:brand 生成独立 favicon 与单色 SVG，两端顶栏复用资产。verify:brand 覆盖 24 条断言及 53 个移动文档页；PC 1464/1464、移动端 807/807 各连续 8 轮通过，0 超时。本次仅修改本地工作树，未提交、未部署。

S8-P5 · 浏览器 theme-color 与手选主题同步｜优先级 P2 ｜待处理

现状：site/index.html 与 tools/build-mobile.mjs 仍输出按系统 prefers-color-scheme 选择的两条 theme-color。页面手选 kole-mode 只切换根元素主题，未同步浏览器 UI 的主题色。K-Node 图形已随页面主题正常变化，此项属于浏览器元信息的既有缺口，不在本次图标重构中顺手修改。

范围：PC 解析期主题脚本、site/app.js 主题应用入口、移动端 THEME_BOOT / applyMode，及对应主题门禁。保持三态与现有主题存储键兼容。

验收：系统浅色 + 手选深色、系统深色 + 手选浅色、自动模式下系统切换、刷新与跨站入口均断言最终有效的 theme-color；执行 REG_BASE=http://127.0.0.1:<本地实际端口> npm run verify:theme。反例：仅有根元素 kole-dark 正确而有效 meta 仍跟随系统，不得判通过。

S8-P6 · i18n 字典历史死键清理｜优先级 P3 ｜待处理

背景（2026-09-22 实测）：本次「详情页减重」删除了由改动直接产生的 6 个死键（先体验交互…、预览使用 H5 实现…、查看示例、选择示例、复制示例链接、测试总览），字典从 604 条降到 585 个唯一键。用新增的只读诊断 tools/lib/i18n-dead-keys.mjs 做全仓库核对后，发现另有约 44 条历史死键；它们不是本次改动产生的，按 AGENTS.md「不在原任务里顺手修」留给本任务包：

79 组件时期的首页/指南文案（自动聚合 79 个组件契约里…共 240 条。、79 个组件里有 78 个的样式引用…）
已下线入口的文案（组件 API 规范、该组件暂无契约 JSON，API 表由 5 端源码自动提炼、API 源码提炼、测试页 →）
卡片 unknown/doNot 的历史说明句（卡片 hover 交互规范 等整组）
设计规范页分组键（色彩 · 品牌色 等）—— 这些疑似以 T('色彩 · ') + name 拼接消费，工具会单列为 REVIEW 档

判据：node tools/lib/i18n-dead-keys.mjs 的 DEAD 档清零，且 verify:i18n 17 条全过。REVIEW 档必须人工确认后处理，禁止按工具输出批量删。

风险与反例（本任务实施中真的踩到两次）：示例链接（app.js 的 componentAnchor 仍在消费）与 场景示范（app.js 场景列表消费）都曾被工具判为死键并已误删一次，靠复核才发现并恢复。「键串是否为某个更长字符串的子串」这类启发式不可靠，删前必须 grep -F "T('<键>')" site/app.js 精确核对消费点。反例：仅凭工具输出批量删除，上述两键会被删掉，中英切换后对应位置变空白。

验收命令：

node tools/lib/i18n-dead-keys.mjs     # DEAD 档应为 0
npm run verify:i18n                   # 17 条全过，unique dictionary keys 通过
REG_BASE=http://127.0.0.1:<实际端口> npm run smoke:site

156 KiB Raw Permalink Blame History Unescape Escape

Kole UI · 长期路线图与任务包

〇 · 交接约定（执行模型必读）

0.1 铁律（违反即返工）

0.2 禁止事项（做过即需回滚）

0.3 环境与工具

0.4 失败升级路径

0.5 交付说明模板（每个任务包完成时提交）

一 · 现状基线（全部为实测数据）

1.1 资产规模

1.2 质量指标

1.3 性能基线

1.4 实测缺口（按严重度）

二 · 长期愿景与阶段划分

2.1 目标状态（12 个月）

2.2 阶段划分与决策依据

三 · 任务包

S1-P1 · LICENSE 许可证 ｜ 预算 ~10 min ｜ 优先级 P0

S1-P2 · npm 分发 ｜ 预算 ~2 h ｜ 优先级 P0

S1-P3 · CI 回归流水线 ｜ 预算 ~1.5 h ｜ 优先级 P0

S1-P4 · data.js 瘦身 ｜ 预算 ~3 h ｜ 优先级 P0

已完成的依赖分析（执行前必读）

分阶段执行建议

S1-P4b · 首屏资源优化 ｜ 预算 ~2 h ｜ 优先级 P1

S2-P5 · 暗色模式真正实现 ｜ 预算 ~1 天 ｜ 优先级 P0

S2-P6 · 跨端一致性自动验证 ｜ 预算 ~1 天 ｜ 优先级 P0

S2-P6-F1 · React 端缺失 is-disabled 等状态类（5 组件） ｜ 预算 ~2 h ｜ 优先级 P1

S2-P6-F2 · H5 演示页缺失框架端结构类 ｜ 预算 ~2 h ｜ 优先级 P2

S2-P6-F3 · React 端 Tag/Select/Input 变体类缺失 ｜ 预算 ~2 h ｜ 优先级 P1

S2-P6-F4 · P6 报告纳入 CI 门禁 ｜ 预算 ~30 min ｜ 优先级 P2

S2-P7 · 行为断言 ｜ 预算 ~1.5 天 ｜ 优先级 P1

S3-P8 · RTL 支持 ｜ 预算 ~2 天 ｜ 优先级 P1

S3-P9 · FAQ 页 ｜ 预算 ~1 天 ｜ 优先级 P2

S4-P10 · Figma 资源 ｜ 预算 ~2 天 ｜ 优先级 P2

S4-P11 · 模板页库 ｜ 预算 ~2 天 ｜ 优先级 P2

S4-P12 · 版本发布流程 ｜ 预算 ~1 天 ｜ 优先级 P3

S6-P21 · 组件族参数化（同源组件收敛为「1 基座 + N 参数」）｜ 预算 ~2 天 ｜ 优先级 P1

四 · 显式不做（及理由）

五 · 未解问题（需用户或后续规划决策）

六 · 风险登记

七 · 验收总纲

附 · 执行状态总览

推荐执行顺序

四 · 2026-09-19 安全审计（衍生任务与已完成项）

S5-P15 补充说明

S5-P16 补充说明

五 · 2026-09-20 文档站导航（衍生任务与已完成项）

六 · 2026-09-20 组件详情页「在线测试」与代码区控制条（衍生任务与已完成项）

七 · 2026-09-20 品牌重命名 Kole UI（衍生任务与已完成项）

八 · 2026-09-20 路由去 #（衍生任务与已完成项）

九 · 2026-09-20「在线测试」预览帧审计（衍生任务与已完成项）

十 · 2026-09-20 升级验收（发布后，衍生任务与已完成项）

附 · 规划修正记录

附 · S7 移动端任务包（平台 × 端）

S7-P22 · 移动端平台上线 ｜ 预算 ~1 天 ｜ 优先级 P0 ｜ ✅ 已完成（2026-09-20，工作区未提交）

S7-P23 · 移动端组件第二批 ｜ 预算 ~2 天 ｜ 优先级 P1 ｜ ✅ 已完成（8 / 8，2026-09-20，工作区未提交）

S7-P24 · 移动端文档站增强（i18n 双语 + sitemap 片段） ｜ 预算 ~4 h ｜ 优先级 P2

S7-P25 · uni-app 真实编译验证 ｜ 预算 ~3 h ｜ 优先级 P1

S7-P26 · PC × uni-app 全量覆盖（3 / 79） ｜ 预算 ~3 天 ｜ 优先级 P2

S6-P49 · PC 组件页「逐示例用法代码」（一个使用场景 = 一块预览 + 一块调用代码）｜ 预算 ~1 天 ｜ 优先级 P1 ｜ ✅ 已完成（2026-09-20，工作区未提交）

S7-P27 · 移动端 SEO 薄壳与 canonical ｜ 预算 ~2 h ｜ 优先级 P3

附 · 2026-09-20 图标系统衍生任务包（本次实测发现，未在原任务范围）

S8-P1 · verify-emits-parse.mjs 的文件数期望值陈旧（158 → 动态推导） ｜ 预算 ~15 min ｜ 优先级 P2

S8-P2 · verify-cross-platform.mjs 把图标数据表误判为组件类名（富噪声） ｜ 预算 ~1 h ｜ 优先级 P2

S8-P3 · 组件5 的 46 个工具/模板组件从未实现（含 IconPreview，本次已补） ｜ 预算 ~3 天 ｜ 优先级 P3

S8-P4 · 品牌标识（favicon / logo）此前缺失且残留旧品牌字母 ｜ 预算 ~2 h ｜ 优先级 P1 ｜ ✅ 已完成（2026-09-20，工作区未提交）

S8-P5 · 浏览器 theme-color 与手选主题同步 ｜ 优先级 P2 ｜ 待处理

S8-P6 · i18n 字典历史死键清理 ｜ 优先级 P3 ｜ 待处理

156 KiB

Raw Permalink Blame History

S1-P1 · LICENSE 许可证｜预算 ~10 min ｜优先级 P0

S1-P2 · npm 分发｜预算 ~2 h ｜优先级 P0

S1-P3 · CI 回归流水线｜预算 ~1.5 h ｜优先级 P0

S1-P4 · `data.js` 瘦身｜预算 ~3 h ｜优先级 P0

S1-P4b · 首屏资源优化｜预算 ~2 h ｜优先级 P1

S2-P5 · 暗色模式真正实现｜预算 ~1 天｜优先级 P0

S2-P6 · 跨端一致性自动验证｜预算 ~1 天｜优先级 P0

S2-P6-F1 · React 端缺失 `is-disabled` 等状态类（5 组件）｜预算 ~2 h ｜优先级 P1

S2-P6-F2 · H5 演示页缺失框架端结构类｜预算 ~2 h ｜优先级 P2

S2-P6-F3 · React 端 Tag/Select/Input 变体类缺失｜预算 ~2 h ｜优先级 P1

S2-P6-F4 · P6 报告纳入 CI 门禁｜预算 ~30 min ｜优先级 P2

S2-P7 · 行为断言｜预算 ~1.5 天｜优先级 P1

S3-P8 · RTL 支持｜预算 ~2 天｜优先级 P1

S3-P9 · FAQ 页｜预算 ~1 天｜优先级 P2

S4-P10 · Figma 资源｜预算 ~2 天｜优先级 P2

S4-P11 · 模板页库｜预算 ~2 天｜优先级 P2

S4-P12 · 版本发布流程｜预算 ~1 天｜优先级 P3

S6-P21 · 组件族参数化（同源组件收敛为「1 基座 + N 参数」）｜预算 ~2 天｜优先级 P1

S7-P22 · 移动端平台上线｜预算 ~1 天｜优先级 P0 ｜ ✅ 已完成（2026-09-20，工作区未提交）

S7-P23 · 移动端组件第二批｜预算 ~2 天｜优先级 P1 ｜ ✅ 已完成（8 / 8，2026-09-20，工作区未提交）

S7-P24 · 移动端文档站增强（i18n 双语 + sitemap 片段）｜预算 ~4 h ｜优先级 P2

S7-P25 · uni-app 真实编译验证｜预算 ~3 h ｜优先级 P1

S7-P26 · PC × uni-app 全量覆盖（3 / 79）｜预算 ~3 天｜优先级 P2

S6-P49 · PC 组件页「逐示例用法代码」（一个使用场景 = 一块预览 + 一块调用代码）｜预算 ~1 天｜优先级 P1 ｜ ✅ 已完成（2026-09-20，工作区未提交）

S7-P27 · 移动端 SEO 薄壳与 canonical ｜预算 ~2 h ｜优先级 P3

S8-P1 · `verify-emits-parse.mjs` 的文件数期望值陈旧（158 → 动态推导）｜预算 ~15 min ｜优先级 P2

S8-P2 · `verify-cross-platform.mjs` 把图标数据表误判为组件类名（富噪声）｜预算 ~1 h ｜优先级 P2

S8-P3 · 组件5 的 46 个工具/模板组件从未实现（含 `IconPreview`，本次已补）｜预算 ~3 天｜优先级 P3

S8-P4 · 品牌标识（favicon / logo）此前缺失且残留旧品牌字母｜预算 ~2 h ｜优先级 P1 ｜ ✅ 已完成（2026-09-20，工作区未提交）

S8-P5 · 浏览器 theme-color 与手选主题同步｜优先级 P2 ｜待处理

S8-P6 · i18n 字典历史死键清理｜优先级 P3 ｜待处理