create-yss-spec 3.5.2 → 3.5.4

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

@@ -1,61 +0,0 @@
-# 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/.pi/skills/yss-prototype-stage/scripts/build-antd-prototype.mjs

@@ -1,71 +0,0 @@
-#!/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,'.template-spec/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/.pi/skills/yss-prototype-stage/scripts/collect-antd-reference.mjs

@@ -1,26 +0,0 @@
-#!/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/.template-spec/agents/domain.md

@@ -1,31 +0,0 @@
-# 业务词汇与决策文档
-
-本文规定 Engineering Skills 在探索仓库、起草 Ticket、设计架构或实施代码前，如何读取和使用业务词汇与决策文档。
-
-## 文档布局
-
-本仓库只维护一份根业务词汇表：
-
-```text
-/
-├── CONTEXT.md
-├── docs/adr/
-└── docs/
-```
-
-## 探索前读取规则
-
-根据任务影响范围读取：
-
-- 根目录唯一的 `CONTEXT.md`：流程术语、业务术语和统一业务词汇；禁止按业务责任区重复创建。
-- `docs/adr/`：与当前任务相关的架构决策。
-
-`CONTEXT.md` 缺失时必须先恢复该合同；`domain-modeling` skill 会在形成稳定术语或关键决策时按需更新业务词汇或 ADR。
-
-## 使用规则
-
-- 在 Spec、Ticket 标题、测试、架构说明和实施总结中使用 `CONTEXT.md` 定义的中文术语。
-- 业务术语必须同时有 PascalCase `英文标识`；代码类型 / 字段与契约 property 使用该词干按 `CONTEXT.md` 文首规则变形。不把具体类全名、表名或接口路径写入词汇表。
-- `CONTEXT.md` 是业务词汇表，不是需求或实现规格；临时计划和未确认猜测不写入。
-- 业务术语身份固定为 `<ContextId>/<EnglishIdentifier>`；`ContextId` 来自已确认的业务责任区，跨责任区共享才使用 `Global`。生命周期资产只保存结构化 snapshot 与双摘要，不使用 Markdown 标题锚点冒充可解析引用。
-- 如果提案与现有 ADR 或已冻结术语冲突，必须在继续执行前明确指出冲突。