diff --git a/.ua/backlog.json b/.ua/backlog.json index 53cb783..46665a2 100644 --- a/.ua/backlog.json +++ b/.ua/backlog.json @@ -596,6 +596,14 @@ "acceptance": "carousel({ items, index, autoplay, height, label, onChange }) 横排位移 + 指示点/箭头/←→ 键切换 + 悬停暂停 + 环形回绕;组件数 39→40 三处计数同步;npm run check 全绿", "status": "done", "notes": "自补:组件补充;index 信号可外部受控,内部信号兜底" + }, + { + "id": "g30", + "title": "check 链并入 demo 构建 + 产物锚点校验", + "motivation": "npm run check 不重建 apps/demo/dist/demo.html,改了演示页门禁照样全绿,文档站 iframe 拿到的是旧产物;verify 只查 main.ts 源码锚点,查不到产物缺块", + "acceptance": "check 链为 build → demo → style → typecheck → smoke → index → verify → lint-iterations;verify 校验产物含全部 sec-* 锚点(负向删除锚点即失败);文档四处链路描述同步;npm run check 全绿", + "status": "open", + "notes": "自补:构建/门禁工具链改进" } ] } diff --git a/.ua/index.json b/.ua/index.json index fc209bf..df1fd26 100644 --- a/.ua/index.json +++ b/.ua/index.json @@ -1,6 +1,6 @@ { "$schema": "ui-arch-registry-index/0.1", - "generatedAt": "2026-10-26T03:39:41.448Z", + "generatedAt": "2026-10-26T03:40:46.247Z", "repoRoot": ".", "packages": [ { @@ -1904,7 +1904,7 @@ "docs": { "intro": "工程层工具包(private,不发布)。所有 Agent 与人都通过它读取组件库:清单驱动索引、文档、MCP 三件套,外加 style / verify 两道门禁。", "steps": [ - "装好依赖后先跑 npm run check 确认基线全绿(build → style → typecheck → smoke → index → verify)", + "装好依赖后先跑 npm run check 确认基线全绿(build → demo → style → typecheck → smoke → index → verify)", "查组件:ua list 看全量,ua info <包名> 看单包 api 与约定", "查令牌:ua tokens 打印全部 --ua-* 变量(颜色带暗色值),--json 输出结构化数组;写样式前先查,禁止硬编码", "改完清单跑 npm run docs:同时刷新人类文档站与 llms-full.txt(Agent 首选喂料)", diff --git a/AGENTS.md b/AGENTS.md index 1d9dd51..cbf02ed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,7 @@ 1. **包管理器必须用 pnpm**:包间依赖用 `workspace:*` 协议,npm 不支持。安装依赖:`pnpm install`。 2. **构建工具**:TypeScript 5(`tsc`)。若环境未全局安装,可使用托管工作区的副本:`C:/Users/shawn/.workbuddy/binaries/node/workspace/node_modules/typescript`(本仓库历史即如此构建)。 3. **Node**:>= 18,ESM(`"type": "module"`)。 -4. **验证自检**:装好后先跑 `npm run check`(build → style → typecheck → smoke → index → verify)确认基线全绿,再开始改代码。 +4. **验证自检**:装好后先跑 `npm run check`(build → demo → style → typecheck → smoke → index → verify)确认基线全绿,再开始改代码。 ## 编码规范(强制) @@ -27,7 +27,7 @@ - `apps/demo`(@ui-arch/demo):交互演示,产物 apps/demo/dist/demo.html - `apps/docs`:文档站,纯产物(ua docs 生成) -**门禁一条龙**:`npm run check` = build + style + typecheck + smoke + index + verify,提交前必过。`ua verify` 校验清单 ↔ 文档 ↔ 演示一致(docs.components 的 id 必须在 api.exports 有对应条目、props 必须带 n/t/d、demo 锚点必须在 `apps/demo/main.ts` 中存在),检查皮肤包样式表无硬编码颜色(`#hex` 一律禁止,必须走 `--ua-*` 令牌)与令牌引用有效(`var(--ua-*)` 必须是 tokens.css 已定义或组件自设的变量),核对 README 的 `` 区块与清单组件集合完全一致,并交叉校验 backlog 的 done 条目与 `.ua/iterations.log` 的 done 留痕一一对应。 +**门禁一条龙**:`npm run check` = build + demo + style + typecheck + smoke + index + verify,提交前必过。`ua verify` 校验清单 ↔ 文档 ↔ 演示一致(docs.components 的 id 必须在 api.exports 有对应条目、props 必须带 n/t/d、demo 锚点必须在 `apps/demo/main.ts` 中存在),检查皮肤包样式表无硬编码颜色(`#hex` 一律禁止,必须走 `--ua-*` 令牌)与令牌引用有效(`var(--ua-*)` 必须是 tokens.css 已定义或组件自设的变量),核对 README 的 `` 区块与清单组件集合完全一致,并交叉校验 backlog 的 done 条目与 `.ua/iterations.log` 的 done 留痕一一对应。 **提交信息规范**:`COMMITTING.md`(`(): <中文祈使句>`),`ua commit-lint` + commit-msg 钩子自动校验,迭代提交用 `iter(<条目id>): `。 diff --git a/ITERATION.md b/ITERATION.md index 7f8a197..de32f0b 100644 --- a/ITERATION.md +++ b/ITERATION.md @@ -30,7 +30,7 @@ qa/probe ──门禁通过──▶ qa/stable ──人工审阅──▶ main 1. **同步**:`git fetch --all --prune`,切到 `qa/stable` 并 `git pull`;从其最新提交强制重建 `qa/probe` 并切换过去。 2. **选题**:读 `.ua/backlog.json`,取第一条 `status === "open"` 的条目;若全部关闭,按《选题规则》自行补充一条新点子后继续。 3. **实现**:按 `CODING.md` 编码规范实现,保持低侵入,单文件 < 200 行,涉及组件需同步 manifest/docs/llms-full.txt。 -4. **门禁**:跑 `npm run check`(build → style → typecheck → smoke → index → verify)。 +4. **门禁**:跑 `npm run check`(build → demo → style → typecheck → smoke → index → verify)。 - **通过**:提交到 `qa/probe`,提交信息按 `COMMITTING.md` 规范(`iter(<条目id>): <中文祈使句>`,元数据变更用 `chore(backlog): 记录 完成`;commit-msg 钩子自动校验),推送 `qa/probe`,fast-forward 合并到 `qa/stable` 并推送;将 backlog 条目 `status` 置为 `done` 并随迭代提交。 - **失败**:尝试修复一次;仍失败则放弃本轮——`qa/probe` 直接重置回 `qa/stable`,backlog 条目在 `notes` 里追加失败原因、`status` 保持 `open`,提交并推送该元数据变更(仅改 `.ua/backlog.json`,不碰代码)。 5. **留痕**:在 `.ua/iterations.log` 追加一行 JSON,**字段统一**:`{"ts":"本地ISO时间","id":"条目id","result":"done|aborted","commit":"短哈希","summary":"一句话"}`。硬性规范:`ts` 必须来自 `date` 命令实测(本地时间,带 +08:00 偏移,**禁止手写或用 UTC 换算**);时长结论必须来自两次时间查询之差,禁止使用「大约/接近」等估算词;并发实例格式不得自创变体。随本轮提交。 diff --git a/README.md b/README.md index d432423..027a392 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ ```bash pnpm install # 包间依赖用 workspace:*,npm 不支持 -npm run check # 门禁一条龙:build → style → typecheck → smoke → index → verify +npm run check # 门禁一条龙:build → demo → style → typecheck → smoke → index → verify npm run demo # 打开演示:apps/demo/dist/demo.html npm run docs # 生成人类文档站 apps/docs/index.html + Agent 全量文档 llms-full.txt ``` diff --git a/llms-full.txt b/llms-full.txt index 3fa7841..65030b0 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -1,6 +1,6 @@ # @ui-arch 组件库 Agent 文档(无图形版) -> 自动生成于 2026-10-26T03:39:41.448Z,数据源:各包 ua.manifest.json,勿手改。人类版文档站:apps/docs/index.html。 +> 自动生成于 2026-10-26T03:40:46.247Z,数据源:各包 ua.manifest.json,勿手改。人类版文档站:apps/docs/index.html。 > 组件 = 普通函数,传 props 返回 DOM;状态用 signal 双向绑定:读 signal() 写 signal(v)。 ## 快速上手 @@ -40,7 +40,7 @@ ### @ui-arch/cli -1. 装好依赖后先跑 npm run check 确认基线全绿(build → style → typecheck → smoke → index → verify) +1. 装好依赖后先跑 npm run check 确认基线全绿(build → demo → style → typecheck → smoke → index → verify) 2. 查组件:ua list 看全量,ua info <包名> 看单包 api 与约定 3. 查令牌:ua tokens 打印全部 --ua-* 变量(颜色带暗色值),--json 输出结构化数组;写样式前先查,禁止硬编码 4. 改完清单跑 npm run docs:同时刷新人类文档站与 llms-full.txt(Agent 首选喂料) diff --git a/package.json b/package.json index a626376..6d232cd 100644 --- a/package.json +++ b/package.json @@ -12,7 +12,7 @@ "style": "node packages/tools/cli/bin/ua.js style", "index": "node packages/tools/cli/bin/ua.js index", "docs": "node packages/tools/cli/bin/ua.js index && node packages/tools/cli/bin/ua.js docs", - "check": "npm run build && npm run style && npm run typecheck && npm run smoke && npm run index && npm run verify && npm run lint-iterations", + "check": "npm run build && npm run demo && npm run style && npm run typecheck && npm run smoke && npm run index && npm run verify && npm run lint-iterations", "ua": "node packages/tools/cli/bin/ua.js", "verify": "node packages/tools/cli/bin/ua.js verify", "lint-iterations": "node packages/tools/cli/bin/ua.js lint-iterations", diff --git a/packages/tools/cli/bin/ua.js b/packages/tools/cli/bin/ua.js index 3e0f973..f757901 100644 --- a/packages/tools/cli/bin/ua.js +++ b/packages/tools/cli/bin/ua.js @@ -763,6 +763,18 @@ function checkIterations() { return issues; } +/*** 演示产物校验:打包后的 demo.html 必须含每个区块锚点,证明演示代码真的编进了产物(防「只改源码、产物过期」) ***/ +function checkDemoBundle(anchors) { + const issues = []; + const file = path.join(ROOT, 'apps', 'demo', 'dist', 'demo.html'); + if (!fs.existsSync(file)) return issues; // 卫语句:产物未构建时不判定(check 链已保证有 demo 步骤) + const html = fs.readFileSync(file, 'utf8'); + for (const a of anchors) { + if (!html.includes(a)) issues.push(`demo 产物缺少区块锚点 ${a},请重跑 npm run demo`); + } + return issues; +} + /*** 清单一致性校验:组件文档块的 id / props 说明 / demo 锚点必须与代码和演示产物对齐 ***/ function cmdVerify() { const issues = []; @@ -771,6 +783,7 @@ function cmdVerify() { const demoSource = fs.existsSync(demoPath) ? fs.readFileSync(demoPath, 'utf8') : ''; const anchors = new Set(demoSource.match(/sec-[a-z0-9-]+/g) ?? []); // 已定义的区块锚点 const tokenVars = new Set(loadTokenList().map((t) => t.cssVar)); // 令牌白名单:tokens.json 拍平结果 + if (demoSource) issues.push(...checkDemoBundle(anchors)); // 产物与源码同步校验 if (!demoSource) console.log('verify: 未找到 apps/demo/main.ts,跳过 demo 锚点校验'); for (const pkg of pkgs) { diff --git a/packages/tools/cli/ua.manifest.json b/packages/tools/cli/ua.manifest.json index 7585658..2e48719 100644 --- a/packages/tools/cli/ua.manifest.json +++ b/packages/tools/cli/ua.manifest.json @@ -35,7 +35,7 @@ "docs": { "intro": "工程层工具包(private,不发布)。所有 Agent 与人都通过它读取组件库:清单驱动索引、文档、MCP 三件套,外加 style / verify 两道门禁。", "steps": [ - "装好依赖后先跑 npm run check 确认基线全绿(build → style → typecheck → smoke → index → verify)", + "装好依赖后先跑 npm run check 确认基线全绿(build → demo → style → typecheck → smoke → index → verify)", "查组件:ua list 看全量,ua info <包名> 看单包 api 与约定", "查令牌:ua tokens 打印全部 --ua-* 变量(颜色带暗色值),--json 输出结构化数组;写样式前先查,禁止硬编码", "改完清单跑 npm run docs:同时刷新人类文档站与 llms-full.txt(Agent 首选喂料)",