create-yss-spec 3.5.3 → 3.5.5

package/template/.agents/skills/yss-ddd-scaffold-generator/references/platform-selection.md

@@ -0,0 +1,16 @@
+# DDD 脚手架平台选择
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。Skill 自带的 bin/scripts 命令从 Skill 根目录执行；明确注明 repository root 的包装命令仍从项目根目录执行。
+
+## Spring Boot / Java 平台选择
+
+调用本技能前由生命周期编排器展示 `scripts/backend-platforms` 的精确版本清单及兼容状态，并通过 `gate.backend-architecture-platform-approved` 把架构、Spring Boot、Java 和 YSS 父 POM/BOM 合并展示、取得真实用户确认；生成器不提问、不猜版本、不使用 `x` 或 `latest`。已有批准且当前的选择展示摘要后复用；既有工程核验并复用登记值，不触发该门禁。
+
+- 精确候选版本与可选状态只读取 `scripts/backend-platforms` 和共享平台清单，不在此复制版本表；候选不等于可生成。
+- 独立子项目可继承主项目组合或覆盖，必须逐项目确认（允许一次确认明确列出的项目）；同一 Maven Reactor 使用一个平台。
+- 只开放共享兼容清单中已有真实 YSS 构建、依赖和启动证据的组合。缺少兼容父 POM、BOM、starter 或相应能力证据即 `blocked`；不替换官方组件、不降级回退。
+- 新生成合同必须有 `platform_configuration` v2，与架构决策、Maven 坐标及兼容条目摘要一致。Boot、Java、YSS 坐标或依赖配方变化时回生命周期重新确认并编译合同；仅追加同配置验证记录不重复确认，仍核验证据有效性。
+- Spring MVC、Servlet、Validation、Jackson 和 starter 坐标消费共享平台清单；Java 下限和允许组合由当前平台条目决定。Jakarta 转换不包括 `javax.sql` 等 Java SE API。
+- 平台候选维护验证产物标记 `platform_verification=candidate`，不能交给业务生成、升级完成等级或进入首切片验证。测试夹具不证明 YSS 兼容。
+
+版本清单、合同字段、候选验证和支持晋级规则见 仓库共享合同 `.template-spec/engineering/backend-platforms.md`。

package/template/.agents/skills/yss-design-system/SKILL.md

@@ -29,12 +29,20 @@ description: 建立或核验 YSS 设计系统、主题 Token 与页面视觉一
 5. 若是前端实现阶段，配合 `yss-ui`、`yss-ui-business-page-generation`、`yss-formily` 及实际命中的组件专项，但本技能负责风格与体验一致性门禁。
 6. 若发现视觉 Token 或组件变体不足，先更新根 `DESIGN.md` 并重新生成投影；只有治理、流程或验收说明不足时才更新 `.template-spec/design/design.md`。
 
+新建高保真原型默认选择根规范已有的紧凑组件变体，按需读取 [原型默认主题](references/prototype-default-theme.md)；此选择不改变生产主题默认值或既有批准页面。
+
+需要构建或评审企业后台页面层级、密度、表单反馈时，按需读取 [企业后台设计方法与示例](references/enterprise-craft.md)。示例演示同 Token 下的结构改进，不新增视觉规范或产品需求。
+
+需要调整页面分组、字段反馈、详情侧栏或紧凑工具栏时，读取 [页面组合与主题适配](references/page-composition.md)。
+
+新企业原型的模块、侧栏、页签和分栏使用根规范 workspace 角色；工作区充分利用宽度，窄屏导航改用 Sheet。缓存、草稿与场景重置由原型技能 `references/enterprise-workspace.md` 承担，不由主题定义业务状态。
+
 ## 核心基线
 
 - UI 定位：中后台、数据密集、表单密集、流程密集、可扫描、低装饰。
 - 颜色：使用 `DESIGN.md` 的 `colors.*`；品牌 seed 与高对比主控件变体是不同角色，不得用 seed 绕过 `components.button-primary*`。
 - 排版：使用 `DESIGN.md` 的 `typography.*`，状态不能只靠字重表达。
-- 密度：使用 `DESIGN.md` 的组件高度与 `spacing.*`；默认采用 Data Quality 浅色、32px 控件；仅显式紧凑模式应用一次 compact algorithm，不手工二次压缩。
+- 密度：使用 `DESIGN.md` 的组件高度与 `spacing.*`；生产默认采用 Data Quality 浅色和根规范普通控件；新高保真原型选择命名紧凑变体，窄屏采用普通控件。生产 compact algorithm 仅显式选择时应用一次。
 - 圆角：使用 `rounded.*`，控件、容器和 pill 角色不得用页面级 magic number 替代。
 - 运行时换肤：短名 CSS 变量必须指向 `--brand-*`，不要再维护第二套色值。
 - 表面层级：页面背景、内容容器、浮层三层模型。
@@ -52,7 +60,7 @@ description: 建立或核验 YSS 设计系统、主题 Token 与页面视觉一
 - 不硬编码表面色、边框色、状态色；优先使用 token 或主题变量。
 - 交互原型中的每个可点击主动作都必须给出 interaction feedback：状态变化、禁用原因、成功或失败反馈至少覆盖其一。
 - accessibility：品牌 Seed 保持 `colors.primary`；实际文字/背景组合不满足 WCAG 2.2 AA 时，优先使用 `components.*` 中的高对比变体或 `ConfigProvider` component token 调整，并验证 default/hover/active/disabled/focus、键盘焦点、200% zoom、reduced motion 与目标尺寸，不新增页面级特例色。
-- 离线原型直接消费所选主题的派生值；默认使用 default 快照，显式紧凑模式才使用 compact 快照，避免重复 compact。生产组件库的主题算法由其实现合同约束；暗色启用前必须核验当前派生 Token 与浏览器截图。
+- 离线原型直接消费所选主题的派生值；原型主题从 variables.css 的根规范命名变体选择密度，正文仍遵循 typography.body；生产算法快照按已选模式使用，避免重复 compact。生产组件库的主题算法由其实现合同约束；暗色启用前必须核验当前派生 Token 与浏览器截图。
 - 原型使用语义 HTML、项目主题变量与当前行为合同；生产实现不得依赖组件库内部 DOM、生成类名或未记录 API。
 - 不用 Tag 表达关键错误、阻断或审批状态；关键状态必须有可读文本和语义反馈。
 - 不让按钮、标签、表头、弹窗、卡片中的文字溢出或遮挡。
@@ -73,7 +81,7 @@ description: 建立或核验 YSS 设计系统、主题 Token 与页面视觉一
 
 - 是否通过 `ConfigProvider`、CSS variables 或项目 token 消费主题。
 - 是否将颜色、圆角、阴影和状态样式绑定到 semantic token，而不是复制表面色和交互色。
-- 是否使用当前 `DESIGN.md` 和所选主题派生快照中的控件、排版与间距值；默认使用 default，仅显式紧凑模式使用 compact，且没有重复 compact。
+- 是否使用当前 `DESIGN.md` 和所选主题派生快照中的控件、排版与间距值；原型已登记 compact/comfortable 密度，生产按当前合同选择算法快照，且没有重复 compact。
 - 是否使用 YSS UI / Ant Design 的语义组件，而不是自造同类组件。
 - 是否保留 hover、focus、active、disabled、loading、error、empty 状态。
 - 是否为可提交、导出、保存、发布、审批等操作提供明确的 interaction feedback 与不可逆操作确认。
@@ -94,6 +102,8 @@ description: 建立或核验 YSS 设计系统、主题 Token 与页面视觉一
 | 原型渲染适配 | `yss-prototype-stage/references/product-design-adapter.md`；H1/H2 统一 HTML 交付、分别验证视觉与可操作流程；不得调用 `yss-ui` |
 | API 契约 / 接入 | `yss-openapi-governance` / `yss-api-integration` |
 
+搜索选择、日期范围、320 CSS px 重排或读屏风险检查时，按需读取 [搜索日期主题与无障碍](references/search-date-theme.md)，并入现有六轴 QA。
+
 ## 更新设计系统
 
 当用户要求“引入设计系统”“形成项目规范”“更新设计系统 skill”时：

package/template/.agents/skills/yss-design-system/assets/enterprise-craft/app.js

@@ -0,0 +1,53 @@
+(() => {
+  const $ = id => document.getElementById(id);
+  let rows, scenario, retried, trigger;
+  for (const item of window.prototypeScenarios) $('scenario').add(new Option(item.label, item.id));
+  const descriptions = {
+    list: '观察查询与业务操作的分区、表头/数据的层级、长名称与空值。',
+    form: '观察字段分组、辅助说明、错误位置与提交区域；两侧失败都保留输入。',
+    approval: '观察待处理项、阻断原因和恢复动作能否关联；不以颜色代替状态文本。'
+  };
+  function element(tag, text) { const el = document.createElement(tag); el.textContent = text; return el; }
+  function feedback(text, kind = 'info') { $('feedback').textContent = text; $('feedback').dataset.kind = kind; }
+  function perform() {
+    if (scenario.outcome === 'no-permission') { feedback('无操作权限：可以查看资料，请联系负责人。', 'error'); return; }
+    if (scenario.outcome === 'failure' && !retried) { feedback('保存失败，当前输入已保留。请重试。', 'error'); $('retry').hidden = false; return; }
+    if (scenario.outcome === 'conflict' && !retried) { feedback('版本冲突：本地输入已保留。重新加载前可复制内容。', 'error'); $('reload').hidden = false; return; }
+    feedback('操作成功（本地模拟）。', 'success'); $('retry').hidden = true; $('reload').hidden = true; $('submit').focus();
+  }
+  function render(reloaded = false) {
+    const params = new URLSearchParams(location.hash.slice(1));
+    const pair = params.get('pair') || 'list'; const variant = params.get('variant') || 'after';
+    scenario = window.prototypeScenarios.find(s => s.id === (params.get('scenario') || 'primary'));
+    if (!descriptions[pair] || !['before','after'].includes(variant) || !scenario) { $('app').textContent = '示例链接无效：请检查示例、对照和场景。'; return; }
+    $('pair').value = pair; $('variant').value = variant; $('scenario').value = scenario.id;
+    $('explanation').textContent = descriptions[pair]; rows = (reloaded === true ? window.craftServerData : window.craftData).map(row => ({ ...row })); retried = reloaded === true;
+    $('app').className = variant;
+    $('app').innerHTML = `<section class="surface"><div class="page-heading"><div><h1>${pair === 'list' ? '资料工作台' : pair === 'form' ? '资料信息' : '待核对资料'}</h1><p class="secondary">核对资料名称、负责人和当前状态。所有操作均为本地模拟。</p></div><div class="actions"><button id="submit" class="primary">${pair === 'list' ? '保存当前清单' : pair === 'form' ? '保存资料' : '确认核对'}</button></div></div><div id="global-feedback"></div><div id="content"></div><div id="local-feedback"></div><div class="actions"><button id="retry" hidden>重试</button><button id="reload" hidden>重新加载</button></div></section>`;
+    const notice = element('p', ''); notice.id = 'feedback'; notice.className = 'feedback'; notice.setAttribute('role','status');
+    $(variant === 'before' ? 'global-feedback' : 'local-feedback').append(notice);
+    if (pair === 'list') {
+      $('content').innerHTML = '<form id="query" class="query"><label>名称或编号<input id="keyword" placeholder="输入资料名称或编号"></label><button>查询</button><button type="button" id="clear">重置查询</button></form><p id="count" class="secondary"></p><div class="table-scroll"><table><thead><tr><th>编号</th><th>资料名称</th><th>负责人</th><th>状态</th><th>操作</th></tr></thead><tbody id="rows"></tbody></table></div><dialog id="detail"><h2>资料详情</h2><dl id="detail-data"></dl><button id="close">关闭详情</button></dialog>';
+      const showRows = () => {
+        const visible = rows.filter(r => (r.id + r.name).includes($('keyword').value.trim())); $('rows').replaceChildren(); $('count').textContent = `共 ${visible.length} 条资料`;
+        for (const row of visible) { const tr = document.createElement('tr'); for (const key of ['id','name','owner','status']) tr.append(element('td', row[key] || '未填写')); const cell = document.createElement('td'); const button = element('button','查看'); button.setAttribute('aria-label',`查看 ${row.id}`); button.onclick = () => { trigger = button; $('detail-data').replaceChildren(); for (const [key,label] of [['id','编号'],['name','名称'],['owner','负责人'],['note','说明'],['version','版本']]) $('detail-data').append(element('dt',label),element('dd',row[key] || '未填写')); $('detail').showModal(); $('close').focus(); }; cell.append(button); tr.append(cell); $('rows').append(tr); }
+      };
+      $('query').onsubmit = e => { e.preventDefault(); showRows(); }; $('clear').onclick = () => { $('keyword').value = ''; showRows(); };
+      const close = () => { $('detail').close(); trigger?.focus(); }; $('close').onclick = close; $('detail').oncancel = e => { e.preventDefault(); close(); }; showRows();
+    } else if (pair === 'form') {
+      $('content').innerHTML = '<form id="editor"><section class="section"><h2>基本信息</h2><div class="fields"><div class="field"><label for="name">资料名称</label><input id="name" required aria-describedby="name-help"><p class="secondary" id="name-help">保留完整名称，便于查询与核对。</p></div><div class="field"><label for="owner">负责人</label><input id="owner" required aria-describedby="owner-help"><p class="secondary" id="owner-help">填写当前资料负责人。</p></div></div></section><section class="section"><h2>核对说明</h2><p id="note"></p><p>版本：<span id="version"></span></p></section></form>';
+      $('note').textContent = rows[0].note; $('version').textContent = rows[0].version; $('name').value = rows[0].name; $('owner').value = rows[0].owner; $('name').readOnly = $('owner').readOnly = scenario.outcome === 'no-permission';
+      $('editor').onsubmit = e => { e.preventDefault(); perform(); };
+    } else {
+      for (const row of rows) { const article = element('article',''); article.className = 'approval-item'; const content = element('div',''); content.append(element('h2',row.name), element('p',`${row.id} · ${row.owner || '负责人未填写'} · ${row.status}`), element('p',row.note)); article.append(content, element('span','核对当前资料后提交')); $('content').append(article); }
+    }
+    $('submit').disabled = scenario.outcome === 'no-permission';
+    if (scenario.outcome === 'no-permission') feedback('无操作权限：可以查看资料，请联系负责人。', 'error');
+    $('submit').onclick = () => pair === 'form' ? $('editor').requestSubmit() : perform();
+    $('retry').onclick = () => { retried = true; pair === 'form' ? $('editor').requestSubmit() : perform(); };
+    $('reload').onclick = () => { if (!confirm('重新加载将放弃本地修改，是否继续？')) return; render(true); $('reload').hidden = true; feedback('已重新加载，可继续核对和提交。'); $('submit').focus(); };
+    document.body.dataset.scenario = scenario.id;
+  }
+  for (const name of ['pair','variant','scenario']) $(name).onchange = () => { location.hash = new URLSearchParams({ pair: $('pair').value, variant: $('variant').value, scenario: $('scenario').value }).toString(); };
+  $('reset').onclick = render; window.addEventListener('hashchange', render); render();
+})();

package/template/.agents/skills/yss-design-system/assets/enterprise-craft/index.html

@@ -0,0 +1,2 @@
+<!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="../../../../../.template-spec/design/tokens/variables.css"><link rel="stylesheet" href="styles.css"></head>
+<body><aside class="review" aria-label="示例评审区"><strong>同 Token 设计对照</strong><p>虚构资料与固定场景，仅供方法教学；两侧业务内容和交互相同。</p><div class="controls"><label>示例 <select id="pair"><option value="list">查询列表</option><option value="form">表单详情</option><option value="approval">审批异常</option></select></label><label>对照 <select id="variant"><option value="before">调整前</option><option value="after" selected>调整后</option></select></label><label>场景 <select id="scenario"></select></label><button id="reset">重置</button></div><p id="explanation"></p></aside><main id="app"></main><script src="scenarios.js"></script><script src="app.js"></script></body></html>

package/template/.agents/skills/yss-design-system/assets/enterprise-craft/scenarios.js

@@ -0,0 +1,14 @@
+window.prototypeScenarios = [
+  { id: 'primary', label: '正常操作', outcome: 'success' },
+  { id: 'failure', label: '失败后重试', outcome: 'failure' },
+  { id: 'no-permission', label: '无操作权限', outcome: 'no-permission' },
+  { id: 'conflict', label: '版本冲突', outcome: 'conflict' }
+];
+window.craftData = [
+  { id: 'M-001', name: '季度经营分析资料', owner: '张明', version: 1, status: '待核对', note: '用于本季度经营分析，需核对归属部门。' },
+  { id: 'M-002', name: '跨部门业务协作与异常处理说明（长名称示例）', owner: '李华', version: 1, status: '待核对', note: '包含跨部门协作信息，请核对完整名称与负责人。' },
+  { id: 'M-003', name: '归档清单', owner: '', version: 1, status: '已更新', note: '负责人尚未填写。' }
+];
+
+// Complete simulated server snapshots for the maintenance-only conflict exercise.
+window.craftServerData = window.craftData.map((row, index) => ({...row, version: 2, ...(index === 0 ? {name: '服务端最新资料名称', owner: '最新负责人', note: '服务端已核对归属部门。'} : {})}));

package/template/.agents/skills/yss-design-system/assets/enterprise-craft/styles.css

@@ -0,0 +1,32 @@
+:root { font: var(--brand-font-size)/var(--brand-line-height) var(--brand-font-family); color: var(--brand-color-text); background: var(--brand-color-bg-layout); }
+* { box-sizing: border-box; } body { margin: 0; } main { max-width: 1440px; margin: auto; padding: var(--brand-size-lg); }
+.review { padding: var(--brand-size-sm) var(--brand-size); background: var(--brand-color-bg-container); border-bottom: 1px solid var(--brand-color-border); }
+.review p { margin: var(--brand-size-xs) 0; color: var(--brand-color-text-secondary); }
+.controls, .actions { display: flex; align-items: center; flex-wrap: wrap; gap: var(--brand-size-sm); }
+.controls label { display: flex; align-items: center; gap: var(--brand-size-xs); }
+h1 { font-size: var(--brand-font-size-xl); line-height: var(--brand-line-height-heading); margin: 0; }
+h2 { font-size: var(--brand-font-size-lg); margin: 0 0 var(--brand-size-sm); } p { overflow-wrap: anywhere; }
+.surface { background: var(--brand-color-bg-container); border-radius: var(--brand-border-radius-lg); padding: var(--yss-card-padding); }
+.page-heading { display: flex; justify-content: space-between; gap: var(--brand-size); align-items: start; margin-bottom: var(--brand-size); }
+.secondary { color: var(--brand-color-text-secondary); } .page-heading p { margin-bottom: 0; }
+button, input, select { font: inherit; color: inherit; background: var(--brand-color-bg-container); min-height: var(--yss-control-height); border: 1px solid var(--brand-color-border); border-radius: var(--brand-border-radius); max-width: 100%; }
+button { padding: 0 var(--brand-size-sm); cursor: pointer; } input { padding: 0 var(--brand-size-sm); width: 100%; } button:disabled { cursor: not-allowed; opacity: .5; }
+.primary { color: var(--yss-color-on-primary); background: var(--yss-color-primary-control); border-color: var(--yss-color-primary-control); }
+:focus-visible { outline: 2px solid var(--yss-color-primary-control); outline-offset: 2px; }
+label { display: block; } .query { display: flex; gap: var(--brand-size-sm); align-items: end; padding-bottom: var(--brand-size); border-bottom: 1px solid var(--brand-color-border-secondary); }
+.query label { flex: 1; max-width: 32rem; } .table-scroll { overflow-x: auto; } table { width: 100%; border-collapse: collapse; } th, td { text-align: left; padding: var(--brand-size-sm); border-bottom: 1px solid var(--brand-color-border-secondary); } th { font-weight: var(--brand-font-weight-strong); background: var(--brand-color-fill-quaternary); } td:first-child { white-space: nowrap; font-variant-numeric: tabular-nums; }
+.section { margin-block: var(--brand-size-lg); } .fields { display: grid; grid-template-columns: repeat(2,minmax(0,1fr)); gap: var(--brand-size); } .field p { margin: var(--brand-size-xs) 0; }
+.feedback { border-left: var(--brand-size-xxs) solid var(--brand-color-info); padding: var(--brand-size-sm); background: var(--brand-color-fill-quaternary); margin-block: var(--brand-size); }
+.feedback:empty { display: none; } .feedback[data-kind="error"] { border-color: var(--brand-color-error); } .feedback[data-kind="success"] { border-color: var(--brand-color-success); }
+.approval-item { display: grid; grid-template-columns: minmax(0,1fr) auto; gap: var(--brand-size); padding-block: var(--brand-size); border-bottom: 1px solid var(--brand-color-border-secondary); }
+dialog { color: inherit; background: var(--brand-color-bg-elevated); width: min(90vw,40rem); border: 1px solid var(--brand-color-border); border-radius: var(--brand-border-radius-lg); padding: var(--brand-size-lg); }
+dd { margin: 0 0 var(--brand-size); overflow-wrap: anywhere; }
+/* Deliberate hierarchy weaknesses; content, tokens and behavior stay identical. */
+.before h1, .before h2 { font-size: var(--brand-font-size); font-weight: normal; }
+.before .page-heading { display: block; } .before .page-heading .actions { margin-top: var(--brand-size-xs); }
+.before .section { margin-block: var(--brand-size-xs); } .before .secondary { color: var(--brand-color-text); }
+.before .query { border: 0; padding-bottom: var(--brand-size-xs); } .before th { background: var(--brand-color-bg-container); font-weight: normal; }
+.before .fields { gap: var(--brand-size-xs); } .before .approval-item { border: 0; padding-block: var(--brand-size-xs); }
+.before .primary { color: var(--brand-color-text); background: var(--brand-color-bg-container); border-color: var(--brand-color-border); }
+@media(max-width:576px) { main { padding: var(--brand-size-sm); } .surface { padding: var(--brand-size-sm); } .fields { grid-template-columns: 1fr; } .page-heading, .query { flex-direction: column; align-items: stretch; } .approval-item { grid-template-columns: 1fr; } .table-scroll table { min-width: 34rem; } }
+@media(prefers-reduced-motion:reduce) { * { animation: none !important; transition: none !important; } }

package/template/.agents/skills/yss-design-system/references/data-quality-theme.md

@@ -4,9 +4,9 @@
 
 采用 Data Quality `packages/src/store/theme.ts` 的全局浅色主题：主色 / info `#3371ff`，正文14px，默认 / small / large控件32 / 24 / 40px，圆角6 / 4 / 8px，Card内距20px。`isDarkMode=false`、`isCompactMode=false`。页面玻璃效果、广大发行主题与人保红色 JSP 主题均为局部选择。
 
-Ant Design v6 提供设计语义与 HTML 原型算法参考；Data Quality 真实运行时为 Vue3 + ant-design-vue4.2.6 + YSS UI。实现主题通过目标库公开 ConfigProvider API 适配，不能把 React API 或 v6版本号移植为 Vue 依赖结论。
+Ant Design v6 提供设计语义与历史算法来源参考；Data Quality 真实运行时为 Vue3 + ant-design-vue4.2.6 + YSS UI。实现主题通过目标库公开 ConfigProvider API 适配，不能把 React API 或 v6版本号移植为 Vue 依赖结论。
 
-`primary-control` / hover 是 YSS 为白色小字保留的可访问性变体，品牌 seed 保持 Data Quality 蓝；它们是已声明适配，不是 Data Quality 原值。默认32px，显式 compact28px，seed不得以28px再次压缩。暗色使用算法生成中性色，不能把浅色 text/surface 固定覆盖带入暗色。
+`primary-control` / hover 是 YSS 为白色小字保留的可访问性变体，品牌 seed 保持 Data Quality 蓝；它们是已声明适配，不是 Data Quality 原值。生产默认使用根规范普通控件，显式 compact 才应用算法一次；新原型默认采用命名紧凑变体，窄屏和 comfortable 使用普通变体，不应用生产 compact 算法。暗色使用算法生成中性色，不能把浅色 text/surface 固定覆盖带入暗色。
 
 更新顺序：修改根 DESIGN.md → 更新 design-system-sync.yaml 摘要 → 在独立作者目录提供固定 antd6.6.4 → `node .template-source/tooling/node/scripts/design-md.mjs export dtcg --write --write-manifest --antd-toolchain <作者目录>` → lint / drift → 刷新 frontend scaffold baseline → 浏览器核对 HTML 和 Vue 两条实现。禁止手改 token 快照或生成投影。
 

package/template/.agents/skills/yss-design-system/references/design-qa-theme.md

@@ -7,7 +7,7 @@
 - 规范：根 `DESIGN.md`
 - 治理说明：`.template-spec/design/design.md`
 - Token 投影：`.template-spec/design/tokens/theme.json`、`.template-spec/design/tokens/tokens.default.json`、`.template-spec/design/tokens/variables.css`
-- 主题选择：默认采用根 `DESIGN.md` 的 Data Quality 浅色主题；仅显式暗色 / 紧凑模式使用对应的 `tokens.dark.json` / `variables.dark.css` / `tokens.compact.json`，以实际消费文件记录摘要。
+- 主题选择：新原型默认浅色 compact，从根 `DESIGN.md` 的命名变体与 variables.css 选择密度；comfortable 使用普通变体，不消费生产 tokens.compact.json 算法结果。生产主题按实现合同选择。暗色只保留未验证历史快照入口，启用前重新派生与核验；摘要登记实际消费文件。
 - 实现截图：当前原型或页面在同一 viewport / 主题 / 状态下的渲染
 
 官方 `https://ant.design/design.md` 只是上游默认。项目覆盖与官方不同时，以根 `DESIGN.md` 为准；本清单不复制规范值。

package/template/.agents/skills/yss-design-system/references/design-system.md

@@ -88,7 +88,7 @@
 执行规则：
 
 - 间距只使用 `spacing.*`，不要补写未登记的中间值。
-- 默认采用 Data Quality 浅色、32px 控件；仅显式紧凑模式叠加一次 compact algorithm；seed 与计算结果从规范源和派生快照读取，不得二次 compact。
+- 原型新页面默认使用 [紧凑主题](prototype-default-theme.md) 中的根规范命名变体；生产主题仍按其合同，compact algorithm 仅显式选择时应用一次。
 - 表单、筛选区、工具栏、表格、详情页使用密集但有节奏的布局。
 - 控件圆角不得明显大于容器圆角。
 - 不使用任意 magic number；确需新增尺寸时，先说明为什么 token 不够。
@@ -179,7 +179,7 @@
 
 ## 前端落地
 
-React + Ant Design：
+历史来源或明确采用 React + Ant Design 的生产实现（新原型已退役此路线）：
 
 - 使用 `ConfigProvider` 注入主题。
 - 默认采用 Data Quality 浅色与 32px 控件；仅显式紧凑模式使用 `theme.compactAlgorithm`；暗色紧凑模式组合 `theme.darkAlgorithm` 与 `theme.compactAlgorithm`，不手工反转色值或逐组件压缩。
@@ -218,7 +218,7 @@ YSS UI / Vue：
 
 - 是否消费 token，而不是硬编码颜色和尺寸。
 - 是否以 semantic token 表达颜色、圆角、阴影和状态层级。
-- 是否使用当前 `DESIGN.md` 与所选主题快照的排版、控件和间距值；默认使用 default，仅显式紧凑模式使用 compact，且没有重复 compact。
+- 是否使用当前 `DESIGN.md` 与所选主题快照的排版、控件和间距值；原型按登记密度使用根规范命名变体，生产按合同选择算法快照，没有重复 compact。
 - 是否保留 hover、focus、active、disabled、loading、empty、error 状态。
 - 是否只保留一个 single primary action，并让每个关键操作提供 interaction feedback。
 - 是否在目标字号和背景下复核 accessibility contrast。

package/template/.agents/skills/yss-design-system/references/enterprise-craft.md

@@ -0,0 +1,33 @@
+# 企业后台设计方法与示例
+
+在已有 `DESIGN.md` 与当前行为合同内改善层级、密度和反馈。本参考不定义新的 Token、组件 API、业务规则或评分门禁。
+
+## 三个判断
+
+1. 主任务能否直接定位？首屏呈现当前任务、关键数据及主操作；辅助说明不与主操作竞争。
+2. 数据、动作与说明的权重是否合适？用项目已有排版、间距、分组和表面角色组织信息；密集不等于挤压所有间距，清晰不等于无限增加留白。
+3. 状态是否说明原因和下一步？错误靠近受影响内容，阻断和权限用明确文本，失败保留输入并说明恢复途径。装饰与动效不得延迟高频操作。
+
+先生成完整页面，再同批检查桌面与窄屏，集中修整并复验受影响场景。记录 visual/layout/interaction/content/accessibility/cross-platform 原有六轴中的发现。预算是停止继续迭代的条件，不是通过条件；关键缺陷仍阻断。代码扫描、画面观察与真实用户证据分别报告。
+
+局部修改先核对设计输入中的保持项：在相同视口与状态对照原页面的区域、字段顺序和操作位置。可读性修复不能顺带重排被要求保持的布局；若确有必要，先记录范围变化并按既有用户决定协议处理。该核对属于现有 layout/interaction QA，不新增评审门禁。
+
+## 可运行示例
+
+`assets/enterprise-craft/index.html` 提供查询列表、表单详情、审批异常三组前后对照，直接打开即可运行。它从当前仓库的派生 CSS 读取 Token；需要脱离仓库携带时运行：
+
+```bash
+node .agents/skills/yss-design-system/scripts/export-craft-examples.mjs --project-root <项目根> --output <新的空目录>
+```
+
+导出器复制当前项目 Token 并绑定 `DESIGN.md` 摘要。两侧共享数据、场景和交互实现；差异仅在内容组织、层级及反馈位置。示例使用虚构资料和固定失败/权限/冲突场景，不代表产品需求、已批准原型或生产组件能力。窄屏与键盘交互也需要实际检查。
+
+观察重点：列表中查询/重置与业务主操作的分区；表单中字段分组和错误定位；审批中待处理项、阻断原因、恢复动作的关联。对照前态刻意保留层级问题，仅供教学，不是可复用的推荐模板。
+
+## 来源与边界
+
+方法参考 Impeccable [Operate](https://github.com/pbakaus/impeccable/blob/114ea1d3838fca73b253af45f873b9c4f5f213c8/.github/skills/impeccable/reference/operate.md)（Apache-2.0）与 [Interface Design](https://github.com/Dammyjay93/interface-design/blob/2f9be3206855bcb2d1d0af262c8bae25cba6658d/.claude/skills/interface-design/SKILL.md)（MIT）。示例为本项目独立编写；不复制外部字体/数值默认值，不引入第二份设计系统或第二套 QA。
+
+## 从观察到任务模式
+
+需要完整交互时，按需读取 `yss-prototype-stage/references/business-patterns.md`：查询层级对应查询详情，字段分组对应分步表单，阻断与恢复对应审批及冲突模式。窄屏检查必须实际定位并操作按钮；无整体溢出不能证明操作可发现。高密度分析保留必要表格时，同时提供可键盘滚动的区域和稳定的资料定位入口。

package/template/.agents/skills/yss-design-system/references/page-composition.md

@@ -0,0 +1,24 @@
+# 企业页面组合与主题适配
+
+此文只说明使用规范角色的方法。先读根 DESIGN.md、已有页面保持项、交互说明和状态矩阵；数值以规范派生变量为准。
+
+- 页面按任务阶段分组：筛选区回答范围，工具栏回答可执行动作，结果区回答对象状态，详情承接次要字段。Card 表示有独立标题/责任的区域，不以 Card 套 Card 制造层级；Separator 分隔相邻内容，不替代标题。
+- 紧凑工具栏保持单个主操作；次要动作进入 DropdownMenu 时保留可发现入口。结果数、筛选范围、选中数量和剩余事项可扫描，窄屏按字段组换行，不压缩正文。
+- Field 同时组织标签、说明和错误，错误定位到控件；长说明自然换行。InputGroup 只承载输入附加信息或相关操作，外层统一边框与焦点，内层禁止重复尺寸。
+- Sheet 承接列表详情，Dialog 承接短决策，AlertDialog 承接现有合同要求的确认。标题、说明、退出和焦点返回齐全；窄屏操作不被浮层边缘遮挡。
+- 持续权限/冲突/部分失败原因用 Alert，Badge 仅补充状态。Tooltip 不承载唯一必要信息。Empty 给原因和下一步，Skeleton/Spinner 配可读加载状态。
+- 指标只突出任务相关主次；Tabs 不隐藏必须同时比较的信息。必要横向表格保留关键列和滚动提示，外层页面不滚动溢出。
+
+新原型默认浅色 compact；comfortable 显式选择，既有局部修改遵守保持项。映射层消费命名组件变体及 body/spacing/rounded 角色，不再应用生产 compact 算法。暗色入口仅供历史参考，未完成当前规范验证。
+
+组件使用条件、依赖、状态和键盘配方见 `yss-prototype-stage/references/component-recipes.md`。三组正反例见 [enterprise-craft.md](enterprise-craft.md)；五类可运行模式和组件状态展示由原型技能导出。预览 `.template-source/design/preview.html` 只展示主题与组件状态，不能当作已批准产品页面。
+
+## Vue 高保真组件适配
+
+新页面优先使用原型技能登记的 shadcn-vue 组件，按任务借鉴 Blocks；样式映射仍消费根 DESIGN 角色。Select/Menu/Sheet 的交互由 Reka UI 承担，主题层只改变外观，不删焦点环、禁用反馈或退出路径。玻璃仅用于已选择的局部表面，正文与表格保持稳定底色，实测背景合成对比度并支持减少透明；不把研究外观写成规范默认。
+
+## 企业应用壳
+
+模块导航 → 分组侧栏 → 已打开页面 Tag → 页面任务，只呈现真实可操作入口。根 DESIGN 的 workspace 角色规定尺寸和标题；主工作区流式填充，表单内部保留阅读宽度，去除装饰性大标题与重复说明。详情选中后才占位，关闭归还空间；窄屏由 Sheet 承接导航和详情，不保留桌面侧栏挤压正文。主内容、详情和表格滚动职责分开，固定工具栏不遮住焦点和错误。状态见原型技能 `references/enterprise-workspace.md`。
+
+页面导航 Tag 使用独立轮廓、主色浅底当前态以及分开的激活/关闭按钮；不套用页内 Tabs 下划线。页内 Tabs 只用主色文字和指示线，不叠加灰底分段控件。收起导航图标居中，当前项有标记，Tooltip 的反相背景与箭头一致。尺寸与动效读取根规范，减少动效时取消过渡。

package/template/.agents/skills/yss-design-system/references/prototype-default-theme.md

@@ -0,0 +1,26 @@
+# 高保真原型默认主题
+
+用于新高保真 H1/H2 页面，shadcn-vue + Vue 3 与原生轻量路线共用。颜色、字体、尺寸仍以当前项目根 DESIGN.md 为准；主题只选择已定义的角色和组件变体。既有批准原型不自动迁移，局部修改先登记保持项。
+
+## 密度与视觉角色
+
+新页面默认 `compact`：控件采用 `components.button-compact.height`，容器采用 `components.card-compact.padding`；窄屏恢复普通控件高度并让筛选、动作与摘要列表换行。`comfortable` 保留根规范普通控件与 Card 变体。密度不压缩正文、焦点或错误说明，不把生产 compact algorithm 的排版结果直接套给原型，也不再次运行算法。
+
+正文使用 `typography.body`，页面标题和分区标题分别使用 `heading-lg`、`heading-md`，辅助信息才用 `caption`。页面、内容、浮层分别使用对应表面角色；主操作使用 button-primary 系列，不能回退到品牌 seed。筛选、列表、表单和审批优先用边界与分组表达层次。
+
+`variables.css` 中 `--yss-colors-*`、`--yss-typography-*`、`--yss-components-*` 是规范角色投影；既有 `--brand-*` 保留运行时桥接。别名由 design-md 工具生成，不手工维护第二套值。只补视觉角色时可执行 `scripts/design-md export dtcg --write-css --write-manifest`，改动源值或生产算法时仍执行完整派生。新主题的计算样式须与当前根规范比对，历史缺少角色别名的快照不作为当前规范一致性的证据。
+
+## 默认页面结构
+
+新企业页面套用根规范 workspace 应用壳：模块、分组侧栏、页签和流式任务区。标题使用 workspace-title；既有页面保持项不被新框架覆盖。多页状态见原型技能 `references/enterprise-workspace.md`，不把页签缓存视为持久保存。
+
+- 查询：条件与筛选动作对齐；列表标题、排序/选择状态位于紧凑工具栏，分页在结果后。窄屏转为带身份、名称、状态和操作的摘要列表。
+- 表单：按任务分组，控制阅读宽度；错误靠近字段且可定位，返回保留输入，确认动作保持可见。
+- 审批：身份、状态、责任人与操作沿行组织；不可操作原因保留可读文本，失败项保持可重试。
+- 分析：指标主次与明细共用筛选；横向滚动限定在数据区域，提供提示、固定关键列与键盘访问。
+
+## 交互与检查
+
+统一 hover、active、focus-visible、disabled、selected、invalid；反馈采用语义表面和文字。动效只用于反馈且使用项目动效 Token，减少动效时取消。完整行为仍消费交互说明与状态矩阵，不由主题定义。
+
+六轴 QA 中检查当前计算样式、文字对比度、选中/错误状态、桌面和窄屏、键盘与焦点返回、200% 缩放、减少动效及 console。密度变小不能作为质量提升的证据；同时检查每屏信息量、主操作可发现性与恢复任务可完成性。前后对照必须采用相同内容、状态和视口，视觉收益需由用户确认。

package/template/.agents/skills/yss-design-system/references/search-date-theme.md

@@ -0,0 +1,19 @@
+# 搜索选择、日期范围与重排
+
+本配方消费根 DESIGN 与现有 Token，不新增颜色或生命周期门禁。原型语义和规则由 `yss-prototype-stage/references/search-date-patterns.md` 持有。
+
+| 表面 | 当前角色与检查 |
+|---|---|
+| 搜索输入/列表 | 使用当前密度控件、输入边框、主次文字、浮层表面；长中文允许换行，编号保持可辨；选中反馈与搜索文字分开 |
+| 错误/加载/禁用 | 复用错误文字、持续反馈和禁用角色；解释原因，不仅变色或降低透明度 |
+| 日期范围 | 端点用高对比主操作颜色，区间用浅主色与正文；同日仍可辨，键盘焦点独立于选中状态 |
+| 日历/浮层 | 七列均分且点击区域实测；内容限制在视口与可用高度，内部可滚动；应用/取消可达，定位错误不被覆盖 |
+| 窄屏 | 控件与筛选堆叠；日期输入单列；长标签、分页、主操作可重排；仅必要二维表格允许自身横向滚动 |
+
+compact/comfortable 分别核对实际计算样式；控件高度不等于点击区域，检查至少 24 CSS px 的实际目标或满足标准的间距例外，并记录依据。增加像素值前先确认是否已有 Token；确需稳定新角色时先登记根 `DESIGN.md`，再用既有工具生成派生值，禁止手改投影。
+
+320 CSS px 等效重排与实际 200% 浏览器缩放分别留证。重排检查筛选、分页、日期浮层、主操作和错误定位；二维数据表例外不能扩展至外围控件。按 [W3C Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html) 记录不适用依据；像素截图或自动扫描不自动证明 WCAG 符合性。
+
+焦点关闭时先检查原触发器仍存在且可见；触发器被隐藏/移除时转向当前页面主区域或明确后继，不能回到隐藏 KeepAlive 页面。键盘检查焦点环、自动滚动、固定栏遮挡、操作结果；减少动效独立核验。
+
+目标人群使用读屏，或动态错误、复合输入、范围选择、焦点恢复有高风险时，追加人工读屏：记录 OS、浏览器、辅助技术及版本；依次听取名称/角色/值、同名 ID、加载/失败、选中反馈、日期端点、应用/取消和离页后焦点。环境缺失写“未执行”及受影响结论；不能把自动扫描写成读屏通过。边界参考 [Playwright accessibility testing](https://playwright.dev/docs/accessibility-testing)。

package/template/.agents/skills/yss-design-system/scripts/export-craft-examples.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { existsSync, realpathSync } from 'node:fs';
+import { readFile, writeFile, mkdir, readdir, lstat, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+const digest = value => `sha256:${createHash('sha256').update(value).digest('hex')}`;
+export async function exportCraftExamples({ projectRoot, output }) {
+  const root = await realpath(projectRoot);
+  const target = path.resolve(output);
+  try { if ((await lstat(target)).isSymbolicLink()) throw new Error('示例输出不允许符号链接'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  try { if ((await readdir(target)).length) throw new Error('示例目录非空，拒绝覆盖'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const tokenRef = '.template-spec/design/tokens/variables.css';
+  const tokens = await readFile(path.join(root, tokenRef)); const design = await readFile(path.join(root, 'DESIGN.md'));
+  await mkdir(target, { recursive: true });
+  for (const file of ['index.html','styles.css','app.js','scenarios.js']) {
+    const text = await readFile(new URL(`../assets/enterprise-craft/${file}`, import.meta.url), 'utf8');
+    await writeFile(path.join(target,file), text.replace('../../../../../.template-spec/design/tokens/variables.css','tokens.css'));
+  }
+  await writeFile(path.join(target,'tokens.css'), tokens);
+  const files = {};
+  for (const file of (await readdir(target)).sort()) files[file] = digest(await readFile(path.join(target,file)));
+  await writeFile(path.join(target,'example-provenance.json'), JSON.stringify({ purpose:'teaching-only', design_source:{ref:'DESIGN.md',digest:digest(design)}, token_source:{ref:tokenRef,digest:digest(tokens)}, files },null,2)+'\n');
+  return { root:target, entry:path.join(target,'index.html') };
+}
+if (process.argv[1] && existsSync(process.argv[1]) && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  try { const { values } = parseArgs({ options: {'project-root':{type:'string'},output:{type:'string'}} }); console.log(JSON.stringify(await exportCraftExamples({projectRoot:values['project-root'],output:values.output}))); }
+  catch (error) { console.error(error.message); process.exitCode=1; }
+}

package/template/.agents/skills/yss-harness-upgrade/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: yss-harness-upgrade
+description: 升级既有 YSS 模板实例，规划同家族版本迁移、定制合并、持久归档、验证与恢复；用于 create-yss-spec 及 design/backend/frontend CLI 实例升级，不处理业务代码或数据库迁移。
+---
+
+# YSS 实例升级
+
+先读取根 `yss-project.yaml`、`CONTEXT.md` 和 [统一协议](../../../.template-spec/process/harness-upgrade.md)。目标必须是已登记的同家族 `project-instance`；身份/schema 不支持时只诊断，不能重新 init 或猜测身份。模板源的技能维护由 `maintaining-skills` 处理。
+
+## 工作顺序
+
+1. 确认目标绝对路径、用户授权范围、实际 CLI 路径及版本、模板 metadata、工作区已有改动。依据 [家族适配](references/cli-families.md) 选定 CLI。未指定目标版本时查询同家族稳定版本并固定精确包版本和摘要，执行期间不再引用 `latest`。CLI 程序升级和项目实例迁移分别记录，不自动安装全局版本。
+2. 用固定 CLI 的 `migrate status` 检查中断事务。有中断时先 `migrate recover` 预览，按既有授权执行 `--apply`，然后重新规划。不得删除状态目录绕过恢复。
+3. `migrate plan --target-dir <绝对路径> --output <项目外全新计划.json>`。旧治理布局迁移显式附加 `--migrate-layout`；退出分发文件清理显式附加 `--prune`。计划阶段不修改项目；检查计划中的版本、变化路径、保留项和归档位置。
+4. 冲突时在项目外起草候选差异和 `--resolutions` 文件。只使用计划报告的可信受管冲突；`preserve` 保留原文，`merge` 提供候选内容并绑定原文件及新模板摘要。向用户展示新的语义取舍，复用已有范围授权；未获授权的新决定保持等待。不能使用 `--force` 批量覆盖，不能先修改项目来消除冲突。
+5. 用相同固定 CLI 执行 `migrate apply --plan <计划>`。执行器重新生成候选并验证计划、归档、身份和输入摘要；`STALE_PLAN` 时重新规划，不能手改摘要续跑。迁移不自动 commit、stash、reset、push 或发布。
+6. 查看回执和实例验证结果，执行相同选项的新计划验证无重复迁移。核对业务文件与既有工作区改动保持，说明保留的定制和现有失败。输出实际版本、归档/回执位置、验证证据和剩余问题；结构检查不能代替真实 CLI 或 Agent 行为验证。
+
+## 恢复与边界
+
+- `migrate recover` 恢复未完成事务；`migrate rollback` 预览最近一次成功迁移的整体回退。两者仅加 `--apply` 才写入。回退遇到后续修改或损坏归档必须保留现场，不覆盖新工作。
+- Spec、Ticket、合同、人工回复、批准和正式验证默认保留。路径迁移不产生新批准；语义或批准绑定变化交回原生命周期，不补造旧状态。
+- 不执行跨家族转换、任意历史版本跳转、业务重构或数据库迁移。未知基线不能由 Agent 猜测；归档不能作为扩大写入授权的理由。
+- 旧实例缺少本技能时，从已固定 CLI 包的 `resources/upgrade-skill/` 在项目外读取入口及相邻协议。不得先同步目标项目来安装升级技能。
+
+本技能只编排，不复制迁移执行器。研究新技术事实时用 `yss-research`；结论输出按 `lifecycle-document-output` 使用 `i-have-adhd`。不批准 Slice、不设置 `ready-for-agent`、不宣称可发布。

package/template/.agents/skills/yss-harness-upgrade/references/cli-families.md

@@ -0,0 +1,14 @@
+# 同家族升级适配
+
+| CLI | 实例 metadata |
+|---|---|
+| create-yss-spec | .yss-template.json |
+| create-yss-harness-design | .yss-harness-design.json |
+| create-yss-harness-backend | .yss-harness-backend.json |
+| create-yss-harness-frontend | .yss-harness-frontend.json |
+
+身份还需通过各 CLI 原有 profile/schema 检查。多个 metadata、旧 dev 家族、未知 schema、符号链接或矛盾 profile 均不能自动接管。`migrate` 不是降级或跨家族工具。
+
+四类 CLI 的新入口一致：`migrate plan|apply|status|recover|rollback`，支持 `--json`。`migrate plan` 只向显式指定的项目外新文件输出；`apply --plan <文件>` 显式写入。recover/rollback 默认只读，写入需 `--apply`。不要从旧 `sync` 推断新接口：主 CLI 普通 sync 会写入，专职 CLI sync 默认预览。
+
+目标模板来自当前固定 CLI 包，不接受计划中的下载地址或脚本。版本、模板和执行器摘要不匹配时更换为生成计划的原包，或重新规划；不得修改计划来绕过。已有 `update/upgrade` 仅更新 CLI 程序，既有 `recover` 仍只恢复原事务。

package/template/.agents/skills/yss-hook/SKILL.md

@@ -38,113 +38,19 @@ description: Use when YSS Vue 页面涉及 vue-hooks-plus/useRequest、分页、
 
 ## 2. 列表 / 分页 Hook
 
-下面示例仅说明**已批准**的 `useRequest` 具有 `manual`、`run`、`onSuccess`、`onError` 时的组织方式；`vue-hooks-plus` 的专属契约见第 3 节，其他请求库以实际 API 为准。
-
-```ts
-export function useReportTable() {
-  const tableData = ref<any[]>([]);
-  const currentParams = ref({ pageIndex: 1, pageSize: 20 });
-  const pagination = reactive({
-    current: 1, pageSize: 20, total: 0,
-    showSizeChanger: true, showQuickJumper: true,
-  });
-
-  const { loading, run: fetchList } = useRequest(apiFn, {
-    manual: true,
-    onSuccess: (res) => {
-      tableData.value = res?.data || [];
-      pagination.total = res?.totalCount || 0;
-    },
-    onError: () => {
-      tableData.value = [];
-      pagination.total = 0;
-    },
-  });
-  const query = (params: Record<string, any>) => {
-    currentParams.value = { ...currentParams.value, ...params };
-    return fetchList(currentParams.value);
-  };
-  // YTable emits one object; adapt it at this boundary.
-  const handlePageChange = ({ current, pageSize }: { current: number; pageSize: number }) => {
-    pagination.current = current;
-    pagination.pageSize = pageSize;
-    return query({ pageIndex: current, pageSize });
-  };
-  return { loading, tableData, currentParams, pagination, query, handlePageChange };
-}
-```
-
-- 仅当项目已批准的请求库支持时使用 `useRequest`；通常使用 `manual: true`，除非需求明确要求挂载即请求。
-- `currentParams` 是唯一参数源。筛选变化重置 `pageIndex: 1`；翻页只改 `pageIndex/pageSize`；刷新、导出和编辑后重载复用它。
-- 在 Hook 内处理成功、失败、空数据和响应映射；旧列表会误导时才在失败时清空。
-- 树数据同样由 Hook 暴露 `treeData`、`treeLoading`、`selectedKey`、`handleSelect`，并在其中处理会触发加载的选中副作用。
+实现列表、筛选、树数据或分页时，读取 [列表与分页模式](references/list-pagination.md)。`currentParams` 保持唯一参数源；筛选回到第一页，刷新、导出和重载复用它。
 
 ## 3. `vue-hooks-plus/useRequest`（项目已批准时）
 
 仅项目已批准且当前任务使用该库时，读取 [useRequest 实现细则](references/use-request.md)，覆盖返回值、错误处理、取消、缓存、刷新、重试和轮询。不得因技能示例引入未批准依赖；调用 `runAsync` 必须捕获拒绝，业务失败提示遵循 mutator 的唯一所有权。
 
-## 4. 单一异步动作：`useLoading`
-
-`useLoading(initialValue?)` 返回 `loading`、`setLoading`、`toggleLoading` 与 `withLoading`。用 `withLoading` 包装提交、删除、导出等动作，并把刷新或状态修正写在回调中。
-
-```ts
-const { loading: removeLoading, withLoading } = useLoading();
-
-async function remove(id: string) {
-  // `withLoading` 不等同于去重锁；快速重复点击须显式短路。
-  if (removeLoading.value) return;
-  await withLoading(() => deleteReport(id), {
-    onSuccess: async () => { await query(currentParams.value); },
-    onError: (error) => { actionError.value = error; },
-  });
-}
-```
-
-- 确认弹窗属于页面 / 组件交互层；Hook 接收“已确认”的业务意图并负责执行、loading、结果更新和最小动作面。
-- `withLoading` 默认捕获异常并返回 `undefined`；调用方确实需要捕获时才设置 `rethrowError: true`。可用 `onSuccess`、`onError`、`onFinally` 或 `keepLoadingOnError` 定义行为。
-- 不要让一个全局 `loading` 掩盖多个互不相关动作；为删除、保存、导出等分别暴露必要状态。
-
-## 5. 搜索竞态、取消与并行详情
-
-`@yss-ui/hooks` 没有通用防抖、取消、缓存或重试 Hook。项目已批准 Vue Hooks Plus 时，优先遵循第 3 节；否则先确认项目请求库是否已提供这些能力，再在业务 Hook 中以最小实现处理：
-
-- 搜索建议：维护 timer、递增请求序号和（仅当客户端支持时）`AbortController`；新输入先清除旧 timer、递增序号并取消旧请求；响应写入前比较序号；在 `onScopeDispose` 清理 timer 并中止请求。不要把这些逻辑放在页面组件。
-- 并行详情：每个独立区域返回自己的 `{ data, loading, error, refresh }`，`refreshAll` 可以用 `Promise.allSettled` 聚合；某一区域失败不得清空或阻塞其他区域，也必须可单独刷新。
-- 提交类动作应回滚局部乐观状态；查询类动作只在旧数据会误导时清空。
-
-```ts
-function createDetailPanel<T>(load: () => Promise<T>) {
-  const data = ref<T>();
-  const error = ref<unknown>();
-  const { loading, withLoading } = useLoading();
-  const refresh = () => withLoading(load, {
-    onSuccess: (result) => { data.value = result; error.value = undefined; },
-    onError: (cause) => { error.value = cause; },
-  });
-  return { data, error, loading, refresh };
-}
-
-const refreshAll = () => Promise.allSettled([
-  profile.refresh(), permissions.refresh(), audit.refresh(),
-]);
-```
-
-## 6. 轮询：`usePollingTask`
-
-`usePollingTask` 是通用调度器，不管理业务数据、loading 或错误状态，也不能替代请求 Hook。它在本轮任务结束后用 `setTimeout` 安排下一轮，避免 `setInterval` 造成重叠堆积。若同一数据源已采用第 3.2 节的 `useRequest` 请求轮询，不得再使用本 Hook。
-
-```ts
-const polling = usePollingTask(async ({ isCurrent, signal }) => {
-  const result = await fetchStatus({ signal }); // 仅在客户端支持 signal 时传入
-  if (!isCurrent()) return;
-  status.value = result;
-}, { interval: 5_000, autoStart: true, pauseWhenHidden: true });
-```
-
-- `start`、`stop`、`restart` 会推进 generation；异步结果写入前必须调用 `isCurrent()`。`signal` 只有请求库真正支持时才能中止网络请求。
-- `stop()` 停止但保留 interval；`setInterval(0)` 停止并把当前 interval 置零。`runNow()` 可立即执行，`restart({ immediate: false })` 可避免手动刷新后紧接着重复请求。
-- 手动搜索 / 刷新时：先 `stop()`，走带 loading 的手动请求，再按需要 `restart()`；不可让轮询与手动请求同时竞争同一状态。
-- 默认页面隐藏时暂停后续调度；正在执行的任务不会自动取消。`continueOnError`、`resumeMode` 和 `concurrent` 必须按接口语义显式选择。
+## 4. 异步动作与竞态
+
+实现提交/删除/导出、搜索竞态或并行详情时，读取 [异步动作与竞态](references/async-actions.md)。确认属于交互层；Hook 只执行已确认意图，各独立区域保留自己的状态。
+
+## 6. 轮询
+
+实现后台刷新或多接口轮询时，读取 [轮询调度](references/polling.md)。同一数据源只有一个调度器；写入前检查 `isCurrent()`，并协调手动请求。
 
 ## 7. URL、全屏与高度类 Hooks