create-yss-spec 3.3.7 → 3.4.1

package/template/.agents/skills/yss-prototype-stage/references/antd-integration.md

@@ -0,0 +1,61 @@
+# AntD 组件知识与条件预构建
+
+默认用原生 HTML/CSS/JS；当复杂表格、树选择、日期范围等简化模拟会改变评审结论时，记录 `selection_reason` 并使用 `react-antd-prebuilt`。复杂组件的出现不是自动启用条件，先判断本次实际要验证的行为。两条路线都交付 `index.html` 与完整本地资源，接收者无需 Node。预构建仍在浏览器运行 React；不是零 JavaScript，也不是生产 YSS 组件证明。
+
+## 组件选择
+
+[全量组件索引](antd-component-catalog.json) 固定官方来源、版本、分类、废弃状态及链接：73 个基础目录条目（包含已废弃 List），6 个重型组件单列外部来源。Icon 属于 `@ant-design/icons`；目录条目不等于 `antd` 直接导出。默认排除废弃组件。实际使用前按锁定版本查询；不要把官网当前页自动当成项目版本。
+
+首批选型覆盖 23 种语义：Layout、Menu、Breadcrumb、Tabs、Button、Typography、Form、Input、InputNumber、Select、Checkbox、Radio、Switch、Table、Pagination、Tag、Descriptions、Empty、Modal、Drawer、Alert、Spin、Message。组件知识可查不代表每种组件已有本地实现；可运行 starter 覆盖查询列表、详情、编辑弹窗、失败恢复。原生详情使用 dialog，AntD 详情使用 Drawer。其他变体按实际状态矩阵补充。
+
+Table 首先限定分页、筛选、选择与操作；编辑、虚拟滚动、拖拽按需求验证，不从少量模拟数据推断性能。树控件明确勾选传导、禁用与异步加载；日期明确清空/非法输入/区间；Upload 只模拟交互，不把模拟成功标为服务端接收。ProTable 等重型组件只作为模式参考，另行评估依赖。
+
+## 资料与版本
+
+官方事实入口：[CLI](https://ant.design/docs/react/cli-cn/)、[LLMs/Markdown](https://ant.design/docs/react/llms-cn/)、组件源码。优先按组件查询，避免每次加载整个站点。
+
+当前作者工具固定 AntD 6.6.4、React/ReactDOM 19.2.4、esbuild 0.28.2、CLI 6.6.4，由 `assets/antd-authoring/package.json` 和 `pnpm-lock.yaml` 持有版本。更新时重新生成目录/来源记录并运行脚本和浏览器验证，不自动追随 latest。
+
+CLI 按 minor 快照选择，可能回退到更早 minor 或 major；`--version` 不是补丁版本精确性的证据。采集器记录 requested/resolved snapshot 及原始摘要；未命中同 minor 时明确拒绝，补固定源码证据。`design.md` 是 major 粒度的默认 light 参考，根 `DESIGN.md` 才是项目权威。`zeroRuntime` 只关闭运行时样式生成，不移除 React；本适配器保留常规 AntD 样式生成，并用已计算 Token 映射主题，不再执行 compact 算法。
+
+## 作者侧工具（与交付包分离）
+
+在独立作者目录安装依赖，禁止在 canonical Skill 或生成投影内安装，禁止把 `node_modules` 和 lockfile 放入原型交付目录。
+
+```bash
+mkdir -p docs/.scratch/<feature>/design/authoring
+cp .agents/skills/yss-prototype-stage/assets/antd-authoring/{package.json,pnpm-lock.yaml} docs/.scratch/<feature>/design/authoring/
+pnpm --dir docs/.scratch/<feature>/design/authoring install --frozen-lockfile
+node .agents/skills/yss-prototype-stage/scripts/collect-antd-reference.mjs \
+  --toolchain docs/.scratch/<feature>/design/authoring \
+  --version 6.6.4 --output docs/.scratch/<feature>/design/antd-reference
+```
+
+采集器默认缓存上述 23 个组件，可用 `--components Table,Select,DatePicker` 按需指定。CLI 尚缺的条目（例如此版本的 Util）必须补读官方源码，不伪造 API。返回的 `runtime_compatibility_verified=false` 只能由实际原型验证补足，采集不是批准。
+
+## 构建与验证
+
+原生完整业务流程 starter：
+
+```bash
+node .agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs prepare-flow \
+  --project-root . --root docs/.scratch/<feature>/design/prototypes \
+  --feature <feature> --pattern workbench
+```
+
+真实 AntD starter（初次可用默认示例；定制后 `--entry` 指向作者目录中的 JSX 源文件）：
+
+```bash
+node .agents/skills/yss-prototype-stage/scripts/build-antd-prototype.mjs \
+  --project-root . --feature <feature> \
+  --toolchain docs/.scratch/<feature>/design/authoring \
+  --reason '<说明简化模拟如何影响本次评审结论>'
+```
+
+输出是 IIFE bundle、Token/CSS、作者 JSX、构建来源和第三方许可；`build-provenance.json` 绑定实际包版本、作者 lock、源码及主题摘要。已有目录拒绝覆盖。继续修改原型时选择新版本工作目录，避免重写冻结截图与用户确认。`--entry` 当前接受单个 JSX bundle，额外资源须先补明确的本地打包支持，不能静默漏交付。
+
+两条路线统一 `seal-project` / `validate-project`、六轴 QA、Visual Baseline 和用户确认。`react-antd-prebuilt` 的 evidence 声明 `runtime_build_required=false`、`framework=react-antd-prebuilt`、`selection_reason`，组件事实仍绑定实际版本、组件集合、项目 DESIGN/Token digest 与来源 manifest；额外提供 `build_provenance_ref`。它不复用已退役 `react-antd-6` 路线。
+
+将包复制到独立目录，用 `file://`、禁用网络，验证 desktop/narrow、查询、详情、保存/失败重试、空/加载/权限/冲突、场景重置、键盘焦点、实际 32px 默认控件与主色。静态扫描有边界：编译后的依赖不按网络关键词判断，必须以真实浏览器的请求、console、状态证据复验。若离线小样不通过，记录阻塞，不自动换成需要服务器的工程。
+
+维护回归：`tests/run-scenarios.mjs`；配置 Playwright 和独立 `YSS_ANTD_TOOLCHAIN` 后运行 `tests/workbench-smoke.mjs`。模板示例与截图仅验证 starter，不代替具体产品独立评审和批准。

package/template/.agents/skills/yss-prototype-stage/references/html-prototype-practices.md

@@ -0,0 +1,14 @@
+# HTML 原型实践与来源
+
+这些方法补充既有状态矩阵、六轴 QA 和 Visual Baseline，不引入新的生命周期或整套第三方技能。2026-09-14 核查；外部 main 是观察来源，不是自动更新授权。不复制第三方实现代码。
+
+| 来源 | 采纳 | 边界 |
+|---|---|---|
+| [Google design.md](https://github.com/google-labs-code/design.md/blob/main/README.md) | 规范 Token、lint、diff 和派生导出 | alpha；沿用项目锁定工具，导出成功不替代 lint，规范不承载业务状态 |
+| [GOV.UK 场景数据](https://prototype-kit.service.gov.uk/pass-data/) | 场景初值、输入保留、切换和清空 | 借鉴行为，服务端 session 不进入离线包 |
+| [WAI APG](https://www.w3.org/WAI/ARIA/apg/practices/read-me-first/) 与 [Dialog](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) | 原生语义、键盘与焦点承诺 | ARIA 本身不实现交互；按实际采用模式复验 |
+| [Playwright visual comparisons](https://playwright.dev/docs/test-snapshots) | 同环境、同场景的截图比较 | 首版截图不是已通过的回归；环境变化可能产生渲染差异 |
+| [MDN modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) 与 [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) | 普通脚本、随包数据、内存场景与 file:// 复验 | 不依赖模块本地加载或 file: 持久化保证 |
+| [Frontend Design](https://github.com/anthropics/claude-code/blob/main/plugins/frontend-design/skills/frontend-design/SKILL.md) | 内容、用户任务、数据密度驱动的设计 | 不采用其营销 hero 或改变 YSS 字体/品牌的默认倾向 |
+
+Owl-Listener/designer-skills 四项方法已融合，固定 revision 与原型策略见 [档位合同](prototype-profile-routing.md)。页面行为根据实际 Spec 编写；场景与重置示例为 YSS 自行实现，不代表生产能力。

package/template/.agents/skills/yss-prototype-stage/references/product-design-adapter.md

@@ -1,75 +1,50 @@
-# YSS 原型渲染适配器
+# YSS HTML 原型适配器
 
-生命周期调用方只选择 H1/H2 并验证 schema v3；静态与流程原型渲染细节留在本适配器内。
+H1/H2 表示验证深度，不表示低/高保真。统一消费 Prototype Evidence schema v4 与 Visual Baseline schema v1。默认 `html-css-js`，接收者可离线打开；生产组件验证仍归下游 `yss-ui`，原型阶段不得调用。
 
-## H1：静态视觉评审
+## 构建与交付
 
-目录固定为 `docs/.scratch/<feature>/design/prototypes/`。运行：
+在项目实例中，低保真和状态矩阵评审通过后运行；模板源仅在临时 fixture 测试生成器：
 
 ```bash
-node .agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs prepare-static \
-  --project-root <project-root> \
-  --root <project-root>/docs/.scratch/<feature>/design/prototypes \
-  --feature <feature>
+node .agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs prepare-flow \
+  --project-root <project-root> --root <project-root>/docs/.scratch/<feature>/design/prototypes --feature <feature>
 ```
 
-命令生成语义化 `index.html`、`styles.css` 和 `yss-prototype-adapter.json`，引用项目 Token CSS。它不创建 `package.json`、lockfile、`node_modules` 或运行时构建合同。设计者在此最小壳中实现布局和少量关键交互；交付可以是静态目录或 URL，不要求单文件。
-
-校验：
+H1 将 `prepare-flow` 换成 `prepare-static`。两者输出 `index.html`、`styles.css`、`tokens.css`、`scenarios.js`、`app.js` 和 `yss-prototype-adapter.json`。初始交互仅为模板示例，必须按已评审的 Spec、页面与状态替换。已有非空目录拒绝覆盖；旧批准版本保持只读，新工作版本使用新的工作目录标识并保留业务 feature 的追踪关系。
 
-```bash
-node .agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs validate-project \
-  --profile H1 --root <prototype-root>
-```
+制作时可以使用必要工具，交付包不携带 package、lockfile、node_modules，不要求接收方运行 Node。使用普通 script、本地相对路径和随包数据；模块与工具源需先转换成可离线执行的脚本。场景状态默认在内存中，不以 file:// 下不确定的 localStorage 行为作为正确性前提。无需为简单流程建设路由或状态框架。
 
-## H2：可运行流程
+所有运行资源收在交付目录内，Token 从 `DESIGN.md` 的项目派生 CSS 复制并保存来源摘要。静态扫描拒绝远程资源、越出目录、符号链接、缺失文件和常见网络依赖；动态构造资源及浏览器差异仍由真实离线复验发现。
 
-H2 可选择任何能稳定浏览器交付的轻量前端实现。默认 `component_basis=vue-antdv-next`，使用 Vue 3/Vite + Antdv Next：
+完成编辑后执行：
 
 ```bash
-node .agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs prepare-flow \
-  --project-root <project-root> \
-  --root <prototype-root> \
-  --feature <feature> \
-  --pnpm-version <actual-pnpm-version>
-
-node .agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs validate-project \
-  --profile H2 --root <prototype-root>
+node .agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs seal-project --root <prototype-root> --profile H2
+node .agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs validate-project --root <prototype-root> --profile H2
 ```
 
-默认命令生成最小 Vue/Vite starter，精确写入 `antdv-next@1.5.2`、`vue@3.5.21`、`vite@6.4.2`、`@vitejs/plugin-vue@5.2.4`，登记实际 pnpm，生成 Vue 入口、`src/yss-theme.js` 与 provider-neutral adapter schema v3。设计 workflow 在 starter 中替换占位页面，再以 `ConfigProvider`、`pnpm install`、`pnpm build` 形成可移植静态输出。已有 Vue 页面不会被重写，但必须通过合同验证。
+`seal-project` 更新资源清单和摘要，不表示设计通过；修改批准原型前先建立新版本。封存后资源变化会使验证失败。规范或 Token 变化时先由设计系统重新派生，再更新包内副本与对应来源摘要，重新验证受影响场景并取得当前版本确认。
 
-显式兼容 React/Vite + Ant Design v6 时传入：
+## 规范直出与视觉还原
 
-```bash
-node .agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs prepare-flow \
-  --project-root <project-root> \
-  --root <prototype-root> \
-  --feature <feature> \
-  --component-basis react-antd-6 \
-  --library-version <exact-6.x-version> \
-  --pnpm-version <actual-pnpm-version>
-```
+- `source_visual.kind=design-system`：输入为根 `DESIGN.md`、交互说明、状态矩阵和已有页面模式；由本适配器直接构建，QA 使用 `design-contract`，核对 Token、实际计算样式、密度、内容和交互。不要调用要求图片前置的 Product Design prototype/image-to-code/design-qa，不改写上游插件的规则。
+- `source_visual.kind=visual-reference`：已有用户选定、可定位的图像或页面捕获，QA 使用 `visual-comparison`。只有选用的 focused workflow 能满足本交付边界时才调用；要求 Node starter 的 workflow 不用于默认离线构建，可由 YSS adapter 直接还原该视觉目标。
+- 没有足够设计依据时先澄清；仅视觉方向或信息架构不确定时比较候选方案。首版图不可当作独立来源来证明符合规范，必须先完成规范审查和用户确认，才能成为后续回归基线。
 
-历史 `--target-antd-version` 继续映射到 `react-antd-6`，只为在途兼容，不再是默认调用。其他 H2 基座必须在证据中明确记录，不得伪造 Antdv Next 或 AntD 字段。
+## 流程和内容
 
-### Provider fact pack
+使用现有状态矩阵约束事件、guard、动作与退出路径。以 `case_id/data_scenario` 定位固定场景，支持重置和重复操作；场景入口留在独立评审区域，不混入产品主流程。H2 覆盖主流程及命中的 failure/no-permission/conflict/recovery 状态，记录 `scenario_replay_ref`、`scenario_reset_result`。
 
-默认目录为 `docs/design/facts/antdv-next/<exact-version>/`；React 兼容路线使用 `docs/design/facts/antd/<exact-version>/`。至少包含 `manifest.json`、design-md 摘要、组件事实与 digest。只有以下全部相等才为 fresh：
+表格、表单与说明使用代表性业务内容和数据密度，覆盖长中文、空值、校验反馈与窄屏形态。复杂组件只实现当前决策需要的可操作模拟；若模拟无法支持关键结论，记录 gap 并返回设计澄清，真实组件假设由 `implementation_handoff` 交给实现阶段。
 
-- manifest 的 package 与 exact version 等于原型 lockfile；
-- 所需组件均被覆盖；
-- 根 `DESIGN.md` path / digest 与当前规范源相等；
-- `project_token_baseline_digest` 等于当前 Token 派生基线；
-- 没有新的 API/semantic 疑问。
+## 统一 QA 与离线复验
 
-不满足时只查询缺失或变化的事实。默认 Vue 路线调用 `yss-antdv-next-design`；React 兼容路线调用 `yss-antd-design`，且 `lint/doctor` 只在存在相关 React 源时运行。不要创建占位 fact 目录；feature 证据只引用实际 manifest。
+六轴仍为 visual/layout/interaction/content/accessibility/cross-platform，写同一份 feature 级 `verification/design-qa.md`。原生语义优先；弹窗按适用行为验证初始焦点、Tab、Escape 和关闭后的焦点去向。ARIA 属性或自动扫描不替代键盘实操。
 
-## 共同映射与验证
+复制资源包到脱离源仓的目录，以 `file://` 且无网络运行，检查所有采用的场景、资源加载、console、键盘、焦点、200% zoom/reduced motion。证据写 `delivery_contract=offline-html-v1`、`resource_manifest_ref`、`offline_verification_ref/result`。机器静态检查通过只代表结构可检查。
 
-映射的是 semantic role、项目 Token、状态和验收行为，不是 React API 表面。默认视口为 desktop `1440x900` 与 narrow `390x844`；按影响追加其他断点。Design QA 固定写 feature 级 verification 路径，并按 visual/layout/interaction/content/accessibility/cross-platform 六轴执行。
-
-浏览器/Design QA 将每个风险驱动 case 捕获为 PNG，写入 `docs/.scratch/<feature>/handoff/visual-baseline-v<version>/images/`，并从 `docs/design/templates/visual-baseline-template.yaml` 生成 manifest。截图必须使用固定数据、sRGB、DPR 1，等待字体完成，关闭动画、过渡和光标闪烁；长页面使用固定滚动分段。捕获完成后运行：
+默认视口 desktop `1440x900`、narrow `390x844`；按影响追加。Visual Baseline 捕获固定数据、浏览器及版本、操作系统、字体、时区、locale、sRGB、DPR 1，关闭动画与光标，等待字体就绪；复验前重置场景。长页面按固定滚动位置分段。
 
 ```bash
 node .agents/skills/yss-prototype-stage/scripts/visual-baseline-contract.mjs seal \
@@ -77,6 +52,8 @@ node .agents/skills/yss-prototype-stage/scripts/visual-baseline-contract.mjs sea
   --bundle-root docs/.scratch/<feature>/handoff/visual-baseline-v1
 ```
 
-`seal` 校验 PNG 尺寸与大小并写入图像和整包摘要；随后以 `validate` 重验。模型和下游实现只从 manifest 的 `case_id` 取图，不通过 glob 推断含义。工作目录可位于被忽略的 `.scratch`，但 Strategic Design Handoff 必须携带或引用可读取的自包含 Bundle。
+从 manifest 的 `case_id` 读取语义与截图，不依赖 glob；视觉回归按风险采用，首次生成基线不声称已有回归通过。六轴 QA、独立评审、用户确认和生产实现隔离保持原合同。
+
+## 条件 AntD 路线
 
-H1/H2 的条件验证矩阵与实现阶段交接规则见 [prototype-profile-routing.md](prototype-profile-routing.md)。原型阶段禁止调用 `yss-ui`；真实组件事实只在批准后的前端实现与实现还原验证中取得。
+已确认复杂交互需要真实组件时，按 [AntD 集成](antd-integration.md) 使用 `react-antd-prebuilt`；这是作者侧预构建，接收者仍无需 Node，所有资源离线随包。默认 `html-css-js` 保持原生实现。组件库知识仅作为本阶段设计事实，不取代根 DESIGN.md 或授权生产实现。

package/template/.agents/skills/yss-prototype-stage/references/prototype-profile-routing.md

@@ -9,7 +9,7 @@
 | 档位 | 名称 | 命中条件 | 默认适配器 |
 |---|---|---|---|
 | H1 | `visual-review` | 仅需确认布局、密度、层级、文案或少量关键交互；不涉及多页面导航、复杂联动、权限、恢复、冲突或真实组件差异 | 语义 HTML + 项目 Token CSS + 最小 JavaScript；可使用设计工具导出，但必须有浏览器可复验入口 |
-| H2 | `flow-review` | 多页面/路由、复杂表单联动、权限体验、失败恢复、并发冲突或需要可操作主流程测试 | 可运行前端原型；Vue 3/Vite + Antdv Next 是受支持默认，React/Vite + Ant Design v6 为显式兼容路线 |
+| H2 | `flow-review` | 多页面/路由、复杂表单联动、权限体验、失败恢复、并发冲突或需要可操作主流程测试 | HTML/CSS/JavaScript 可操作流程；默认离线资源包，保持同等流程和异常验收 |
 
 真实 YSS/AntDV 组件行为、lockfile、props、slots、events 或 Storybook 状态不是第三种原型档位。它们属于前端实现计划、已批准切片的生产实现与实现还原验证。原型中发现的相关不确定性写入 `implementation_handoff`，不得为解决它调用 `yss-ui` 或把实现仓组件代码引入原型。
 
@@ -39,8 +39,9 @@
 
 - 主流程与关键 failure / no-permission / conflict 状态可操作。
 - 验证键盘、焦点、对比度、200% zoom、reduced motion；按风险决定视觉回归。
-- 默认使用 `vue-antdv-next` 并记录 package 与精确版本；显式兼容路线记录 `react-antd-6`。fact pack 只有在 provider、版本、组件集合和项目 Token baseline digest 全部匹配且没有新 API 疑问时才可复用，否则只补增量查询。
-- 使用其他基座时记录 `component_basis`，不创建空 Antdv Next 或 AntD 字段。
+- 默认 `component_basis=html-css-js`、`runtime_build_required=false`、`prototype_library_facts.applicable=false`，不创建 package、lockfile 或空事实包。
+- 场景使用现有 `case_id/data_scenario` 对应状态矩阵；固定初始输入与结果，提供切换、深链接和重置，验证失败后的输入保留、重试、权限边界及冲突恢复。
+- `offline-html-v1` 交付包记录所有本地资源及摘要；断开网络后通过 `file://` 从独立目录复验，保存 console、资源、交互和截图结果。静态扫描不能替代浏览器行为证明。
 
 ### 实现阶段交接
 
@@ -50,7 +51,9 @@
 
 ## 条件 ideation
 
-新视觉方向、信息架构不确定或存在两个以上合理布局时，`product-design:ideate` 的三方案比较为 mandatory。沿用已批准模式且 source visual 可定位时记录 `not-applicable`、复用来源和理由，不制造三份无意义变体。
+新视觉方向、信息架构不确定或存在多个合理布局时比较三个候选方案，由用户选择后构建。可用低保真、HTML 或按需 `product-design:ideate`；不把 ImageGen 当作所有原型的前置依赖。已批准模式或当前设计规范足以约束页面时，记录 `not-applicable`、来源与理由。
+
+`source_visual.kind=design-system` 引用 `DESIGN.md`，走规范直出和 `design-contract` QA；`visual-reference` 引用独立视觉稿，走 `visual-comparison` QA。两者都要求统一六轴 QA 和用户确认；首版截图只在确认后成为后续回归基线。
 
 ## 上游融合记录
 
@@ -67,3 +70,11 @@
 - 新证据只生成 schema v4、Visual Baseline schema v1 与 `artifact.prototype-deliverable`。
 - prototype evidence schema v1/v2/v3 和 `artifact.high-fidelity-html-prototype` 只读兼容；已经关闭的历史证据保持有效，不补造图片。
 - 在途 UI 证据必须迁移到 v4 并产生 Visual Baseline 后才能关闭 `check.prototype-verified`；非 UI 功能不生成空包。
+
+### HTML 路线迁移
+
+两个原型组件 Provider 已从当前技能与生成路线退役。历史 Vue/React 原型、fact pack 与批准证据保留原字节；`--allow-legacy` 只读校验不代表通过当前门禁。在途原型继续演进时生成新的 HTML 工作版本、补离线与场景证据并重新确认，禁止覆盖旧版本。
+
+采纳的外部方法与适用边界见 [HTML 原型实践](html-prototype-practices.md)；不安装上游整包或引入第二套状态、QA、交接体系。
+
+真实组件确有评审价值时，H2 可条件使用 `react-antd-prebuilt`，仍交付离线 HTML 资源包；启用条件、版本与验证见 [AntD 集成](antd-integration.md)。

package/template/.agents/skills/yss-prototype-stage/scripts/build-antd-prototype.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Author-side only. No package manager or build server is shipped to prototype recipients.
+import {readFile,writeFile} from 'node:fs/promises';
+import {createRequire} from 'node:module';
+import {createHash} from 'node:crypto';
+import {pathToFileURL} from 'node:url';
+import path from 'node:path';
+import {prepareOfflineHtml,sealOfflineHtml} from './offline-html.mjs';
+const assets=new URL('../assets/antd-authoring/',import.meta.url);
+const sha=b=>`sha256:${createHash('sha256').update(b).digest('hex')}`;
+export async function buildAntdPrototype({projectRoot,root,feature,toolchain,reason,entry}){
+ if(!reason?.trim())throw new Error('真实 AntD 路线必须记录简化模拟影响评审结论的理由');
+ if(!toolchain)throw new Error('需要独立作者工具目录 toolchain；不要在共享 Skill 内安装依赖');
+ const expected=JSON.parse(await readFile(new URL('package.json',assets),'utf8'));
+ const require=createRequire(path.join(path.resolve(toolchain),'package.json'));
+ for(const [name,version]of Object.entries({...expected.dependencies,...expected.devDependencies})){
+  const actual=require(`${name}/package.json`).version;if(actual!==version)throw new Error(`${name} 需要锁定 ${version}，实际 ${actual}`);
+ }
+ const lock=await readFile(new URL('pnpm-lock.yaml',assets));
+ if(sha(await readFile(path.join(toolchain,'pnpm-lock.yaml')))!==sha(lock))throw new Error('作者工具 pnpm lock 与技能基线不匹配');
+ const tokenCss=await readFile(path.join(projectRoot,'docs/design/tokens/variables.css'),'utf8');
+ // This adapter targets the default light :root baseline, never the later dark-theme overrides.
+ const lightCss=tokenCss.match(/^:root\s*\{([^}]+)\}/m)?.[1];
+ if(!lightCss)throw new Error('缺少明确的 :root light Token 基线');
+ const tokens=Object.fromEntries([...lightCss.matchAll(/(--[\w-]+):\s*([^;]+);/g)].map(m=>[m[1],m[2].trim()]));
+ const value=key=>{if(!tokens[key]||tokens[key].includes('var('))throw new Error(`需先派生实际 Token 值 ${key}`);return tokens[key];};
+ const theme={colorPrimary:value('--yss-color-primary-control'),colorPrimaryHover:value('--yss-color-primary-control-hover'),fontFamily:value('--brand-font-family'),fontSize:parseFloat(value('--brand-font-size')),controlHeight:parseFloat(value('--yss-control-height')),borderRadius:parseFloat(value('--brand-border-radius')),colorText:value('--brand-color-text'),colorBgLayout:value('--brand-color-bg-layout'),colorBgContainer:value('--brand-color-bg-container'),colorBorder:value('--brand-color-border'),motion:false};
+ const source=await readFile(entry?path.resolve(entry):new URL('workbench.jsx',assets),'utf8');
+ if(/\b(?:fetch\s*\(|XMLHttpRequest|WebSocket|EventSource|import\s*\(|serviceWorker\s*\.)/.test(source))throw new Error('离线原型源不得依赖网络或动态模块');
+ {
+  const {build}=require('esbuild');
+  const result=await build({stdin:{contents:source,loader:'jsx',resolveDir:path.resolve(toolchain)},bundle:true,write:false,format:'iife',platform:'browser',target:['chrome110'],minify:true,metafile:true,legalComments:'eof',define:{'process.env.NODE_ENV':'"production"',__PROTOTYPE_THEME__:JSON.stringify(theme)}});
+  if(result.outputFiles.length!==1)throw new Error('此离线路线仅接受一个 JS bundle；额外 CSS/资源需明确本地打包支持');
+  const packageRoots=new Set();
+  for(const input of Object.keys(result.metafile.inputs)){
+    let current=path.dirname(path.resolve(input));
+    if(!current.includes('node_modules'))continue;
+    while(current!==path.dirname(current)){
+      try{const pkg=JSON.parse(await readFile(path.join(current,'package.json'),'utf8'));if(pkg.name&&pkg.version){packageRoots.add(current);break;}}catch{}current=path.dirname(current);
+    }
+  }
+  const notices=[];
+  for(const base of [...packageRoots].sort()){
+    const pkg=JSON.parse(await readFile(path.join(base,'package.json'),'utf8'));
+    let license;
+    for(const file of ['LICENSE','LICENSE.md','LICENSE.txt','license','license.md']){try{license=await readFile(path.join(base,file),'utf8');break;}catch{}}
+    if(!license){for(const file of ['README.md','Readme.md','readme.md']){try{const readme=await readFile(path.join(base,file),'utf8');const section=readme.match(/^##? License[^\n]*\n([\s\S]*?)(?=^##? |$(?![\s\S]))/im);if(section?.[1].includes('Permission is hereby granted')){license=section[1].trim();break;}}catch{}}}
+    if(!license && pkg.name==='@ant-design/icons-svg' && pkg.version==='4.6.0' && pkg.license==='MIT'){
+      const antdRequire=createRequire(require.resolve('antd/package.json'));
+      const iconsRoot=path.dirname(antdRequire.resolve('@ant-design/icons/package.json'));
+      const icons=JSON.parse(await readFile(path.join(iconsRoot,'package.json'),'utf8'));
+      if(JSON.stringify(icons.repository).includes('ant-design-icons'))license=await readFile(path.join(iconsRoot,'LICENSE'),'utf8');
+    }
+    if(!license)throw new Error(`缺少已打包依赖的许可文件 ${pkg.name}`);
+    notices.push(`${pkg.name}@${pkg.version}\n${license}`);
+  }
+  if(notices.length<3)throw new Error('无法确认已打包依赖许可');
+  const manifest=await prepareOfflineHtml({projectRoot,root,feature,profile:'H2'});
+  await writeFile(path.join(root,'app.js'),result.outputFiles[0].contents);
+  await writeFile(path.join(root,'index.html'),'<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>资料维护</title><link rel="stylesheet" href="./tokens.css"><link rel="stylesheet" href="./styles.css"><script defer src="./app.js"></script></head><body><div id="app"></div></body></html>');
+  await writeFile(path.join(root,'styles.css'),`:root{font-family:var(--brand-font-family);color:var(--brand-color-text);background:var(--brand-color-bg-layout)}*{box-sizing:border-box}body{margin:0}.ant-layout-header{height:auto;line-height:normal;padding:16px 24px;background:var(--brand-color-bg-container);display:flex;gap:32px;align-items:center}.ant-layout-content{width:100%;max-width:1440px;margin:auto;padding:24px}.heading{display:flex;justify-content:space-between;align-items:center}.surface{background:var(--brand-color-bg-container);padding:16px;border-radius:8px;margin-block:16px}.review-controls{margin-block:24px}select{min-height:var(--yss-control-height);color:var(--brand-color-text);border:1px solid var(--brand-color-border);background:var(--brand-color-bg-container)}:focus-visible{outline:2px solid var(--yss-color-primary-control);outline-offset:2px}@media(max-width:576px){.ant-layout-content{padding:12px}.ant-layout-header{padding:12px;gap:16px}.surface{padding:12px}.heading{align-items:start;gap:8px}}`);
+  const buildBasis={reason,packages:{...expected.dependencies,...expected.devDependencies},lock_digest:sha(lock),source_digest:sha(source),theme_digest:sha(JSON.stringify(theme)),format:'iife',browser_runtime:'react',toolchain_required_by_recipient:false};
+  await writeFile(path.join(root,'authoring-source.jsx'),source);
+  await writeFile(path.join(root,'build-provenance.json'),JSON.stringify(buildBasis,null,2)+'\n');
+  // Preserve bundled third-party notices alongside the generated resources.
+  await writeFile(path.join(root,'THIRD-PARTY-NOTICES.txt'),notices.join('\n\n'));
+  await writeFile(path.join(root,'yss-prototype-adapter.json'),JSON.stringify({...manifest,component_basis:'react-antd-prebuilt',build_provenance:buildBasis},null,2));
+  return await sealOfflineHtml(root,'H2');
+ }
+}
+if(process.argv[1]&&pathToFileURL(path.resolve(process.argv[1])).href===import.meta.url){const args={};for(let i=2;i<process.argv.length;i+=2){if(!process.argv[i].startsWith('--')||!process.argv[i+1])throw new Error('参数必须是 --key value');args[process.argv[i].slice(2)]=process.argv[i+1];}const projectRoot=path.resolve(args['project-root']||'.');const root=args.root||path.join(projectRoot,'docs/.scratch',args.feature||'','design/prototypes');console.log(JSON.stringify(await buildAntdPrototype({projectRoot,root,feature:args.feature,toolchain:args.toolchain,reason:args.reason,entry:args.entry}),null,2));}

package/template/.agents/skills/yss-prototype-stage/scripts/collect-antd-reference.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import{readFileSync,existsSync,mkdirSync,writeFileSync}from'node:fs';
+import{createRequire}from'node:module';
+import{createHash}from'node:crypto';
+import{gunzipSync}from'node:zlib';
+import path from'node:path';
+import{pathToFileURL}from'node:url';
+const core=['Layout','Menu','Breadcrumb','Tabs','Button','Typography','Form','Input','InputNumber','Select','Checkbox','Radio','Switch','Table','Pagination','Tag','Descriptions','Empty','Modal','Drawer','Alert','Spin','Message'];
+const digest=b=>`sha256:${createHash('sha256').update(b).digest('hex')}`;
+export function collectAntdReference({toolchain,version,output,components=core}){
+ if(!/^6\.\d+\.\d+$/.test(version||''))throw new Error('明确指定 --version 6.x.y；不自动检测或静默回退');
+ if(existsSync(output))throw new Error('输出已存在，保留历史快照，请选新目录');
+ const require=createRequire(path.join(path.resolve(toolchain),'package.json'));
+ const cliPath=require.resolve('@ant-design/cli/package.json'),cli=JSON.parse(readFileSync(cliPath));
+ if(cli.version!=='6.6.4')throw new Error('此采集器只适配已核验的 CLI 6.6.4 数据布局');
+ const dataRoot=path.join(path.dirname(cliPath),'data');const index=JSON.parse(readFileSync(path.join(dataRoot,'versions.json')));
+ const snapshot=index.v6?.[version.split('.').slice(0,2).join('.')];if(!snapshot)throw new Error('CLI 未收录该 minor；须补充固定源码证据');
+ const ref=`v${snapshot}.json`;const source=existsSync(path.join(dataRoot,ref))?readFileSync(path.join(dataRoot,ref)):gunzipSync(readFileSync(path.join(dataRoot,ref+'.gz')));const data=JSON.parse(source);
+ if(data.version!==snapshot)throw new Error('CLI 索引与实际数据版本不一致');
+ const selected=components.map(name=>{const c=data.components.find(c=>c.name.toLowerCase()===name.toLowerCase());if(!c)throw new Error(`CLI 不含 ${name}，请读取固定官方源码；不可补造 API`);return c;});
+ const manifest={schema_version:1,requested_version:version,resolved_snapshot_version:snapshot,version_match:snapshot===version?'exact':'minor-snapshot-only',cli_version:cli.version,cli_snapshot_digest:digest(source),components_covered:selected.map(c=>c.name),design_doc_scope:'major-v6/default-light; reference only, project DESIGN.md is authoritative',runtime_compatibility_verified:false,files:{}};
+ const files={};for(const c of selected)files[`${c.name}.json`]=JSON.stringify(c,null,2)+'\n';
+ for(const[ref,bytes]of Object.entries(files))manifest.files[ref]=digest(bytes);
+ mkdirSync(output,{recursive:true});for(const[ref,bytes]of Object.entries(files))writeFileSync(path.join(output,ref),bytes);writeFileSync(path.join(output,'manifest.json'),JSON.stringify(manifest,null,2)+'\n');return manifest;
+}
+if(process.argv[1]&&pathToFileURL(path.resolve(process.argv[1])).href===import.meta.url){const a={};for(let i=2;i<process.argv.length;i+=2)a[process.argv[i].slice(2)]=process.argv[i+1];console.log(JSON.stringify(collectAntdReference({toolchain:a.toolchain,version:a.version,output:a.output,components:a.components?.split(',')}),null,2));}

package/template/.agents/skills/yss-prototype-stage/scripts/offline-html.mjs

@@ -0,0 +1,121 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile, readdir, lstat } from "node:fs/promises";
+import path from "node:path";
+
+const manifestName = "yss-prototype-adapter.json";
+const sha = (bytes) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+const assetRoot = new URL("../assets/offline-html/", import.meta.url);
+
+async function inventory(root, relative = "") {
+  const result = {};
+  if ((await lstat(path.join(root, relative))).isSymbolicLink()) throw new Error(`原型资源不允许符号链接: ${relative || "."}`);
+  for (const entry of await readdir(path.join(root, relative), { withFileTypes: true })) {
+    const name = path.posix.join(relative, entry.name);
+    if (entry.isSymbolicLink()) throw new Error(`原型资源不允许符号链接: ${name}`);
+    if (entry.isDirectory()) Object.assign(result, await inventory(root, name));
+    else if (!entry.isFile()) throw new Error(`原型资源不是普通文件: ${name}`);
+    else if (name !== manifestName) result[name] = sha(await readFile(path.join(root, name)));
+  }
+  return Object.fromEntries(Object.entries(result).sort(([a], [b]) => a.localeCompare(b, "en")));
+}
+
+function resourceErrors(file, text, files) {
+  const errors = [];
+  const refs = [];
+  if (/\.html?$/i.test(file)) {
+    for (const tag of text.matchAll(/<(?:script|link|img|source|iframe|video|audio|object|embed)\b[^>]*>/gi)) {
+      for (const attr of tag[0].matchAll(/\b(?:src|href|poster|data)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/gi)) refs.push(attr[1] ?? attr[2] ?? attr[3]);
+      if (/\bsrcset\s*=/i.test(tag[0])) errors.push(`${file}: 离线包请使用明确的本地 src，srcset 需先转换并复验`);
+    }
+    if (/<base\b/i.test(text) || /<script\b[^>]*\btype\s*=\s*["']?module\b/i.test(text)) errors.push(`${file}: file:// 交付不使用 base 或 module script`);
+  }
+  if (/\.(?:css|html?)$/i.test(file)) {
+    for (const match of text.matchAll(/url\(\s*["']?([^"')]+)["']?\s*\)|@import\s+["']([^"']+)["']/gi)) refs.push((match[1] ?? match[2]).trim());
+  }
+  for (const ref of refs) {
+    if (/^(?:data:|#)/i.test(ref)) continue;
+    let decoded;
+    try { decoded = decodeURIComponent(ref.split(/[?#]/)[0]); } catch { errors.push(`${file}: 非法资源 URL ${ref}`); continue; }
+    if (/^(?:[a-z][\w+.-]*:|\/|\\)/i.test(decoded) || decoded.includes("\\")) { errors.push(`${file}: 非本地相对资源 ${ref}`); continue; }
+    const target = path.posix.normalize(path.posix.join(path.posix.dirname(file), decoded));
+    if (target.startsWith("../") || !Object.hasOwn(files, target)) errors.push(`${file}: 资源缺失或越出交付包 ${ref}`);
+  }
+  if (/\.(?:jsx?|html?)$/i.test(file) && /\b(?:fetch\s*\(|XMLHttpRequest|WebSocket|EventSource|import\s*\(|serviceWorker\s*\.)/.test(text)) errors.push(`${file}: 离线默认路线不依赖网络、动态模块或 Service Worker；使用随包场景数据`);
+  return errors;
+}
+
+async function inspect(root, profile, checkDigests) {
+  const errors = [];
+  let manifest, files;
+  try {
+    files = await inventory(root);
+    manifest = JSON.parse(await readFile(path.join(root, manifestName), "utf8"));
+  } catch (error) { return { errors: [error.message] }; }
+  if (manifest.schema_version !== 4 || !["html-css-js", "react-antd-prebuilt"].includes(manifest.component_basis) || manifest.runtime_build_required !== false) errors.push("原型必须使用 offline-html adapter schema v4 / html-css-js / runtime_build_required=false");
+  if (manifest.prototype_profile !== profile || manifest.profile_kind !== (profile === "H1" ? "visual-review" : "flow-review")) errors.push("adapter 档位与验证档位不一致");
+  if (manifest.entry !== "index.html" || !files[manifest.entry]) errors.push("缺少本地 index.html 入口");
+  for (const file of ["styles.css", "tokens.css", "app.js", "scenarios.js"]) if (!files[file]) errors.push(`缺少 ${file}`);
+  for (const file of Object.keys(files)) {
+    if (/(^|\/)(node_modules|package\.json|(?:pnpm|package)-lock\.(?:yaml|json)|yarn\.lock)(\/|$)/.test(file)) errors.push(`交付包不得依赖 ${file}`);
+    if (/\.(css|jsx?|html?)$/i.test(file)) {
+      const content = await readFile(path.join(root, file), "utf8");
+      // Compiled dependencies contain network API names; inspect authored code and require real offline browser evidence.
+      if (!(manifest.component_basis === "react-antd-prebuilt" && file === "app.js")) errors.push(...resourceErrors(file, content, files));
+    }
+  }
+  if (manifest.component_basis === "react-antd-prebuilt") {
+    const build = manifest.build_provenance;
+    if (profile !== "H2" || build?.format !== "iife" || build?.browser_runtime !== "react" || build?.toolchain_required_by_recipient !== false || !build?.reason?.trim()) errors.push("真实 AntD 必须是 H2 离线预构建并记录选择理由");
+    for (const field of ["source_digest", "lock_digest", "theme_digest"]) if (!/^sha256:[a-f0-9]{64}$/.test(build?.[field] ?? "")) errors.push(`缺少 AntD ${field}`);
+    if (build?.source_digest !== files["authoring-source.jsx"]) errors.push("AntD 源文件与构建来源摘要不一致");
+    for (const name of ["antd", "react", "react-dom", "esbuild"]) if (!/^\d+\.\d+\.\d+$/.test(build?.packages?.[name] ?? "")) errors.push(`AntD 作者工具需要精确版本 ${name}`);
+    if (!files["THIRD-PARTY-NOTICES.txt"] || !files["build-provenance.json"]) errors.push("缺少构建来源或第三方许可");
+    else { try { if (JSON.stringify(JSON.parse(await readFile(path.join(root, "build-provenance.json"), "utf8"))) !== JSON.stringify(build)) errors.push("构建来源与 manifest 不匹配"); } catch { errors.push("构建来源不是有效 JSON"); } }
+  }
+  if (files["styles.css"]) {
+    const styles = await readFile(path.join(root, "styles.css"), "utf8");
+    for (const token of ["--brand-font-family", "--brand-color-text", "--brand-color-bg-layout", "--brand-color-bg-container", "--yss-color-primary-control", "--yss-control-height"]) if (!styles.includes(token)) errors.push(`styles.css 未消费项目 Token ${token}`);
+  }
+  if (manifest.design_source?.path !== "DESIGN.md" || !/^sha256:[a-f0-9]{64}$/.test(manifest.design_source?.digest ?? "")) errors.push("缺少根 DESIGN.md 来源摘要");
+  if (manifest.token_source?.path !== "docs/design/tokens/variables.css" || manifest.token_source?.digest !== files["tokens.css"]) errors.push("tokens.css 与登记的 Token 来源摘要不一致");
+  if (checkDigests && JSON.stringify(manifest.files) !== JSON.stringify(files)) errors.push("原型资源摘要或清单已变化，审查后重新 seal-project");
+  return { errors, manifest, files };
+}
+
+export async function validateOfflineHtml(root, profile) {
+  const { errors } = await inspect(root, profile, true);
+  return { errors };
+}
+
+export async function sealOfflineHtml(root, profile) {
+  const result = await inspect(root, profile, false);
+  if (result.errors.length) throw new Error(result.errors.join("\n"));
+  const manifest = { ...result.manifest, files: result.files };
+  await writeFile(path.join(root, manifestName), `${JSON.stringify(manifest, null, 2)}\n`);
+  return manifest;
+}
+
+export async function prepareOfflineHtml({ projectRoot, root, feature, profile, pattern = "editor" }) {
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(feature ?? "")) throw new TypeError("feature 必须是小写 kebab-case");
+  if (!["editor", "workbench"].includes(pattern)) throw new Error("pattern 必须为 editor/workbench");
+  const expected = path.resolve(projectRoot, "docs/.scratch", feature, "design/prototypes");
+  if (path.resolve(root) !== expected) throw new TypeError(`原型目录必须精确匹配 ${expected}`);
+  for (let current = path.resolve(root); current.startsWith(`${path.resolve(projectRoot)}${path.sep}`); current = path.dirname(current)) {
+    if (existsSync(current) && (await lstat(current)).isSymbolicLink()) throw new Error(`原型路径不允许符号链接: ${current}`);
+  }
+  // Refuse an occupied destination instead of replacing an existing or frozen prototype.
+  if (existsSync(root) && ((await lstat(root)).isSymbolicLink() || (await readdir(root)).length)) throw new Error("原型目录已存在内容；请在保留旧版本后选择新 feature 工作目录，不覆盖已有原型");
+  const design = await readFile(path.join(projectRoot, "DESIGN.md"));
+  const tokens = await readFile(path.join(projectRoot, "docs/design/tokens/variables.css"));
+  await mkdir(root, { recursive: true });
+  for (const file of ["index.html", "styles.css", "app.js", "scenarios.js"]) {
+    const folder = pattern === "workbench" && file !== "scenarios.js" ? new URL("../assets/native-workbench/", import.meta.url) : assetRoot;
+    const source = await readFile(new URL(file, folder), "utf8");
+    await writeFile(path.join(root, file), source.replaceAll("__FEATURE__", feature).replaceAll("__PROFILE__", profile));
+  }
+  await writeFile(path.join(root, "tokens.css"), tokens);
+  const manifest = { schema_version: 4, feature, pattern, prototype_profile: profile, profile_kind: profile === "H1" ? "visual-review" : "flow-review", component_basis: "html-css-js", runtime_build_required: false, entry: "index.html", design_source: { path: "DESIGN.md", digest: sha(design) }, token_source: { path: "docs/design/tokens/variables.css", digest: sha(tokens) }, files: {} };
+  await writeFile(path.join(root, manifestName), JSON.stringify(manifest));
+  return sealOfflineHtml(root, profile);
+}