create-yss-spec 3.5.3 → 3.5.4

package/template/.pi/skills/yss-prototype-stage/tests/workspace.test.mjs

@@ -0,0 +1,70 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {readFile,mkdtemp,mkdir,cp} from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import {createHash} from 'node:crypto';
+import {validateWorkspace,readPageId,pageLink,createWorkspaceState,openPage,closePage,pageScene,pageTagFocusTarget} from '../assets/vue-business-patterns/workspace-model.js';
+import {composeWorkspaceScenarios} from '../scripts/compose-workspace-scenarios.mjs';
+import {buildShadcnVuePrototype} from '../scripts/build-shadcn-vue-prototype.mjs';
+import {validatePrototypeProject} from '../scripts/prototype-contract.mjs';
+const definition={brand:'fixture',modules:[{id:'records',label:'资料'},{id:'operations',label:'事项'}],groups:[{id:'records-pages',label:'资料',moduleId:'records'},{id:'operations-pages',label:'事项',moduleId:'operations'}],pages:[{id:'list',title:'查询',moduleId:'records',groupId:'records-pages',component:{}},{id:'form',title:'表单',moduleId:'records',groupId:'records-pages',component:{}},{id:'conflict',title:'冲突',moduleId:'operations',groupId:'operations-pages',component:{}}],defaultPage:'list'};
+test('navigation registration rejects ambiguous or unreachable pages',()=>{
+ assert.equal(validateWorkspace(definition),definition);
+ for(const mutate of [d=>d.pages.push(d.pages[0]),d=>d.pages[1].groupId='missing',d=>d.defaultPage='missing',d=>d.modules.push({id:'empty',label:'空模块'}),d=>d.pages[1].id='../outside']){const d=structuredClone(definition);mutate(d);assert.throws(()=>validateWorkspace(d));}
+});
+test('page deep links are strict and preserve the existing scene fragment',()=>{
+ assert.equal(readPageId('',definition),'list');assert.equal(readPageId('?page=form',definition),'form');
+ for(const query of ['?page=missing','?page=','?page=list&page=form','?other=x','?page=list&scenario=primary'])assert.throws(()=>readPageId(query,definition));
+ for(const prefix of ['file:///offline/index.html','https://example.test/offline/index.html']) {
+  const result=new URL(pageLink(prefix+'?page=form#scenario=conflict',definition,'list'));
+  assert.equal(result.pathname,new URL(prefix).pathname);assert.equal(result.origin,new URL(prefix).origin);assert.equal(result.hash,'#scenario=conflict');assert.equal(result.search,'?page=list');
+ }
+ assert.throws(()=>pageLink('file:///a/index.html',definition,'../other'));assert.throws(()=>pageLink('javascript:alert(1)',definition,'list'));
+});
+test('switching retains per-page state while closing removes only its cache identity',()=>{
+ const state=createWorkspaceState(definition);openPage(state,definition,'form');state.dirty.form=true;state.scroll.form=180;
+ openPage(state,definition,'conflict');openPage(state,definition,'form');assert.deepEqual(state.opened,['list','form','conflict']);assert.equal(state.scroll.form,180);assert.equal(state.dirty.form,true);
+ const before=structuredClone(state);assert.equal(closePage(state,definition,'form'),'confirm');assert.deepEqual(state,before,'cancel has no destructive transition');
+ assert.equal(closePage(state,definition,'form',true),'closed');assert.equal(state.activeId,'list');assert.equal(state.dirty.form,undefined);assert.equal(state.scroll.form,undefined);assert.deepEqual(state.opened,['list','conflict']);
+ openPage(state,definition,'form');assert.equal(state.dirty.form,undefined);state.scroll.form=35;assert.equal(closePage(state,definition,'conflict'),'closed');assert.equal(state.activeId,'form');assert.equal(state.scroll.form,35);
+ assert.equal(closePage(state,definition,'list',true),'pinned');assert.deepEqual(createWorkspaceState(definition,'conflict'),{activeId:'conflict',opened:['list','conflict'],dirty:{},scroll:{}});
+});
+test('page Tag keyboard focus wraps without activating pages or discarding drafts',()=>{
+ const state=createWorkspaceState(definition);openPage(state,definition,'form');openPage(state,definition,'conflict');state.dirty.form=true;state.scroll.form=180;
+ const before=structuredClone(state);
+ assert.equal(pageTagFocusTarget(state.opened,'list','ArrowLeft'),'conflict');
+ assert.equal(pageTagFocusTarget(state.opened,'conflict','ArrowRight'),'list');
+ assert.equal(pageTagFocusTarget(state.opened,'form','Home'),'list');
+ assert.equal(pageTagFocusTarget(state.opened,'list','End'),'conflict');
+ assert.equal(pageTagFocusTarget(state.opened,'form','ArrowLeft'),'list');
+ for(const key of ['Enter',' ','Tab','Delete','Escape'])assert.equal(pageTagFocusTarget(state.opened,'form',key),null);
+ assert.equal(pageTagFocusTarget([], 'list','Home'),null);
+ assert.equal(pageTagFocusTarget(state.opened,'closed','ArrowLeft'),null);
+ assert.equal(pageTagFocusTarget(['form'],'form','ArrowRight'),'form');
+ assert.deepEqual(state,before,'moving focus must not activate or mutate page caches');
+});
+test('composed fixtures bind original states and isolate data between scenes/pages',async()=>{
+ const composed=await composeWorkspaceScenarios();const bytes=await readFile(new URL('../assets/vue-business-patterns/workspace.scenarios.json',import.meta.url),'utf8');assert.equal(bytes,JSON.stringify(composed,null,2)+'\n');
+ for(const scenario of composed.scenarios)for(const [name,page] of Object.entries(scenario.initial_data.pages)){
+  const source=await readFile(new URL(`../assets/vue-business-patterns/${name}.scenarios.json`,import.meta.url));assert.equal(page.source_digest,'sha256:'+createHash('sha256').update(source).digest('hex'));
+  const original=JSON.parse(source).scenarios.find(s=>s.id===page.id);assert.deepEqual(page.initial_data,original.initial_data);assert.equal(page.state_ref,original.state_ref);
+ }
+ const primary=composed.scenarios[0],scene={id:primary.id,data:primary.initial_data,ticket:1};const page={id:'list-detail'};
+ const a=pageScene(scene,page);a.data.rows[0].name='local draft';assert.notEqual(pageScene(scene,page).data.rows[0].name,'local draft');assert.throws(()=>pageScene(scene,{id:'absent'}),/缺少/);
+ assert.throws(()=>pageScene(scene,{id:'list-detail',mapScene:()=>({id:'primary',data:{}})}),/来源/);
+});
+test('workspace style references resolve to generated project or local variables',async()=>{
+ const base=new URL('../assets/vue-business-patterns/',import.meta.url),style=await readFile(new URL('workspace.css',base),'utf8');
+ const tokens=await readFile(new URL('../../../../.template-spec/design/tokens/variables.css',import.meta.url),'utf8');const declared=new Set([...tokens.matchAll(/(--[\w-]+)\s*:/g),...style.matchAll(/(--[\w-]+)\s*:/g)].map(m=>m[1]));
+ for(const ref of style.matchAll(/var\((--[\w-]+)/g))assert(declared.has(ref[1]),`Unresolved theme role ${ref[1]}`);
+});
+test('workspace builds as a portable Vue package with exact page source closure',{},async()=>{
+ const projectRoot=await mkdtemp(path.join(os.tmpdir(),'yss-workspace-contract-'));await mkdir(path.join(projectRoot,'.template-spec/design/tokens'),{recursive:true});
+ for(const file of ['DESIGN.md','.template-spec/design/tokens/variables.css'])await cp(new URL('../../../../'+file,import.meta.url),path.join(projectRoot,file));
+ const root=path.join(projectRoot,'docs/.scratch/workspace/design/prototypes');const manifest=await buildShadcnVuePrototype({projectRoot,root,feature:'workspace',toolchain:process.env.YSS_VUE_TOOLCHAIN,config:new URL('../assets/vue-business-patterns/workspace-standard.config.json',import.meta.url).pathname});
+ assert.equal(manifest.component_basis,'vue-shadcn-prebuilt');assert.equal(manifest.build_provenance.component_groups.length,27);assert.deepEqual((await validatePrototypeProject({root,projectRoot})).errors,[]);
+ for(const source of ['ListDetail.vue','MultiStep.vue','Approval.vue','Conflict.vue','Analysis.vue','workspace-model.js','workspace-page.ts','workspace-definition.ts'])assert(manifest.files['authoring-sources/'+source],source);
+ const scenarios=JSON.parse(await readFile(path.join(root,'scenarios.json')));for(const item of Object.values(scenarios.scenarios[0].initial_data.pages))assert.equal(manifest.files[item.source_ref],item.source_digest,'bound page fixture must travel with the package');
+ const copied=path.join(projectRoot,'portable-copy');await cp(root,copied,{recursive:true});assert.deepEqual((await validatePrototypeProject({root:copied})).errors,[]);
+});

package/template/.pi/skills/yss-prototype-stage/tests/zoom-browser.mjs

@@ -0,0 +1,26 @@
+// Use the browser's actual tabs.setZoom API, not CSS zoom or DPR emulation.
+import assert from 'node:assert/strict';import{mkdtemp,mkdir,writeFile}from'node:fs/promises';import path from'node:path';import os from'node:os';import{pathToFileURL}from'node:url';
+const{chromium}=await import(process.env.YSS_PLAYWRIGHT_MODULE||'playwright');
+const root=process.argv[2];if(!root)throw Error('需要已构建的模式目录');
+const temp=await mkdtemp(path.join(os.tmpdir(),'yss-zoom-browser-')),extension=path.join(temp,'extension');await mkdir(extension);
+await writeFile(path.join(extension,'manifest.json'),JSON.stringify({manifest_version:3,name:'Local prototype zoom verification',version:'1.0',permissions:['tabs'],background:{service_worker:'worker.js'}}));await writeFile(path.join(extension,'worker.js'),'chrome.runtime.onInstalled.addListener(()=>{});');
+const context=await chromium.launchPersistentContext(path.join(temp,'profile'),{headless:true,channel:'chromium',viewport:null,args:['--window-size=1440,1000',`--disable-extensions-except=${extension}`,`--load-extension=${extension}`]});
+const rows=[];
+try{await context.setOffline(true);const worker=context.serviceWorkers()[0]||await context.waitForEvent('serviceworker');const page=await context.newPage(),errors=[];page.on('pageerror',e=>errors.push(e.message));
+ for(const mode of ['list-detail','multi-step','approval','conflict','analysis','component-states','combined-query','owner-validity','workspace']){
+  const url=pathToFileURL(path.join(path.resolve(root),mode,'index.html')).href;await page.goto(url);await page.locator('h1').waitFor();
+  await worker.evaluate(async url=>{const tab=(await chrome.tabs.query({})).find(t=>t.url===url);await chrome.tabs.setZoom(tab.id,1);},url);await page.waitForTimeout(100);const initialWidth=await page.evaluate(()=>innerWidth);
+  const zoom=await worker.evaluate(async url=>{const tab=(await chrome.tabs.query({})).find(t=>t.url===url);await chrome.tabs.setZoom(tab.id,2);return await chrome.tabs.getZoom(tab.id);},url);assert.equal(zoom,2);await page.waitForFunction(w=>Math.abs(innerWidth-w/2)<=1,initialWidth);
+  assert.equal(await page.evaluate(()=>document.documentElement.scrollWidth>innerWidth),false);
+  if(mode==='list-detail'){await page.getByRole('button',{name:'查看 M-001',exact:true}).click();await page.getByRole('dialog').waitFor();await page.keyboard.press('Escape');}
+  else if(mode==='multi-step'){await page.locator('#name').fill('缩放验证');await page.getByRole('button',{name:'下一步',exact:true}).click();await page.locator('#owner').fill('测试');await page.getByRole('button',{name:'确认提交',exact:true}).click();await page.getByText('提交成功（本地模拟）。',{exact:true}).waitFor();}
+  else if(mode==='approval'){await page.getByRole('button',{name:'通过 M-001',exact:true}).click();await page.getByText('已处理 1 项（本地模拟）。',{exact:true}).waitFor();}
+  else if(mode==='conflict'){await page.getByRole('button',{name:'编辑 M-001',exact:true}).click();await page.locator('#name').fill('缩放编辑');await page.locator('#save').click();await page.getByText('保存成功（本地模拟）。',{exact:true}).waitFor();}
+  else if(mode==='component-states'){await page.getByRole('button',{name:'验证字段',exact:true}).click();assert.equal(await page.evaluate(()=>document.activeElement.id),'catalog-input');await page.locator('#catalog-input').fill('缩放组件');await page.getByRole('button',{name:'打开详情侧栏',exact:true}).click();await page.getByRole('dialog').waitFor();await page.getByRole('button',{name:'关闭详情',exact:true}).click();}
+  else if(mode==='combined-query'||mode==='owner-validity'){const id=mode==='combined-query'?'query':'form';await page.locator('#'+id+'-range').click();assert.equal(await page.evaluate(()=>document.documentElement.scrollWidth>innerWidth),false);await page.getByRole('button',{name:'取消',exact:true}).click();}
+  else if(mode==='workspace'){await page.getByRole('button',{name:'已打开页面菜单',exact:true}).click();await page.keyboard.press('Escape');}
+  else{await page.locator('#keyword').fill('张明');await page.getByRole('button',{name:'定位 M-001',exact:true}).click();await page.getByRole('region',{name:'定位资料',exact:true}).waitFor();}
+  await page.screenshot({path:path.join(temp,`${mode}-200.png`),fullPage:true});rows.push({mode,zoom,initialWidth,status:'passed',geometry:await page.evaluate(()=>({width:innerWidth,dpr:devicePixelRatio}))});
+ }
+ assert.deepEqual(errors,[]);await writeFile(path.join(temp,'result.json'),JSON.stringify({status:'passed',mechanism:'chrome.tabs.setZoom/getZoom in isolated test profile',rows,errors},null,2));console.log(path.join(temp,'result.json'));
+}finally{await context.close();}

package/template/.pi/skills/yss-stage-decision/SKILL.md

@@ -34,6 +34,8 @@ Plan 的目标与退出条件由 `.template-spec/process/lifecycle-registry.yaml
 6. 生成 schema v3 `domain_strategy` 和 `stage_decision_package`，使用稳定规则、场景、决定、假设、约束、成功标准、测试 seam 和 downstream mapping ID，并以 `context_snapshot` 绑定根 `CONTEXT.md`、术语身份、完整文档 digest、引用术语 digest和证据。
 7. 运行 Schema、唯一性、悬空引用、根路径、术语引用、digest、语义一致性和传播验证；发现关键冲突时返回 `blocked`，不得生成 `approved` 包。v2 仅只读；修改或重发必须使用 `scripts/migrate-contract-v3.mjs` 显式迁移为 `draft` 并重新批准。v1 字符串引用先用 `scripts/migrate-context-references.mjs` 迁移到 v2；歧义引用不得猜测。
 
+Plan 成功标准在既有 `success_criteria[].statement` 细化指标定义、基线或未知原因、目标及确认状态、观测窗口、数据来源、验证方式和补齐动作；Plan 引用 `success-criterion.*`。关键取舍复用 `decision.*`，记录真实候选、理由、代价和重新考虑条件，不凑备选数量。表达和诊断见 `.template-spec/process/plan-spec-quality.md`；诊断不批准或阻断阶段，不扩展合同 schema。
+
 ## 控制面引用
 
 - 用户决定遵循 [用户决定协议](../yss-product-lifecycle/references/user-decisions.md)：决定必须绑定资产、版本、范围和证据；范围、风险、摘要或失效条件变化后重新确认。

package/template/.pi/skills/yss-technical-design/SKILL.md

@@ -45,3 +45,7 @@ schema v1 战术合同只按 DDD 显式兼容读取；使用 `--legacy-ddd`，
 ## 后端脚手架平台承接
 
 消费生命周期已确认的架构与 `platform_configuration` v2；不得自行选择、批准或静默升级 Boot/Java。平台清单执行 `scripts/backend-platforms` 查询；只允许已验证 YSS 组合，新生成缺少配置或证据即阻断。决定、合同、Manifest 与下游架构身份须绑定同一平台及兼容摘要。详见 仓库共享合同 `.template-spec/engineering/backend-platforms.md`。
+
+## 业务拆分输入
+
+按 `.template-spec/process/business-tickets.md` 执行 Spec 业务草案、Design 校准与业务正式化。业务票放在 `business-tickets/`，集合引用进入 Spec / map / checkpoint；业务票不授予实现资格。实现票仍在 `issues/`，受工程准备、当前 Slice 合同批准和完整就绪检查约束。 核验业务票与原 FR/AC、适用规则和场景对应关系。可在技术分析中起草实现 Slice；既有工程事实须当前核验，新工程按批准的脚手架合同生成机械骨架。工程前置未闭合时保持待满足，不把它写为 not-applicable。

package/template/.pi/skills/yss-ui-business-page-generation/SKILL.md

@@ -68,21 +68,9 @@ description: "生成或改造完整 YSS UI CRUD、列表、表单、详情或左
 - 页面包含导出、报表、模板或附件下载时必须遵循 `file-export-download`，使用 `handleBlobResponse(res.data, res.headers)`，并检查生成方法是否已包含 `responseType: 'blob'`。
 - 若用户给出旧项目路径或截图，开发前必须先提取 UI/交互验收清单；交付前逐项对照，不允许只实现字段和接口。
 
-## 标准代码骨架
-
-```text
-src/views/{module-name}/
-├── index.vue
-├── constant.ts
-├── style.less
-├── hooks/
-│   ├── use{Module}List.ts
-│   └── use{Module}Form.ts
-├── type.ts              # 独立类型较多时增加
-└── components/          # 多个私有视图时增加
-    ├── {Module}Table.vue
-    └── {Module}Modal.vue
-```
+## 页面骨架
+
+首次建立页面目录时，读取 [页面目录与组合示例](references/page-layout-example.md)。
 
 ## 生成流程
 
@@ -94,52 +82,7 @@ src/views/{module-name}/
 6. 对 API 请求使用 Orval 真实生成类型和导出，在 hooks 内封装 loading、分页映射和失败后状态；错误 Toast 由 mutator 统一处理。
 7. 交付前检查导入来源、真实组件 API、分页字段、Formily schema 层级、主题 Token、查询按钮右下角布局、表格工具栏、样式作用域、删除确认和原型对照清单。
 
-## 最小组合示例
-
-```vue
-<script setup lang="ts">
-import { ref } from 'vue';
-import { YButton, YCard, YTable } from '@yss-ui/components';
-import { useTableHeight } from '@yss-ui/hooks';
-import { TABLE_COLUMNS } from './constant';
-import { useRuleList } from './hooks/useRuleList';
-
-const emit = defineEmits<{ create: [] }>();
-const tableAreaRef = ref<HTMLDivElement>();
-const { tableHeight, isReady } = useTableHeight(tableAreaRef, { withPagination: true, withToolbar: true });
-const { loading, dataList, pagination, handlePageChange } = useRuleList();
-
-/** 打开新增表单，实际项目中由表单 Hook 实现。 */
-const openCreate = (): void => {
-  emit('create');
-};
-</script>
-
-<template>
-  <YCard class="page-card">
-    <div ref="tableAreaRef" class="table-area">
-      <YTable
-        v-if="isReady"
-        :height="tableHeight"
-        :data="dataList"
-        :columns="TABLE_COLUMNS"
-        :loading="loading"
-        pageable
-        v-model:pagination="pagination"
-        @page-change="handlePageChange"
-      >
-        <template #toolbar-right>
-          <YButton type="primary" @click="openCreate">新增</YButton>
-        </template>
-      </YTable>
-    </div>
-  </YCard>
-</template>
-
-<style scoped lang="less">
-@import './style.less';
-</style>
-```
+需要组合 YCard、YTable 与高度 Hook 时，读取 [页面组合示例](references/page-composition-example.md)；API 与分页细则仍按实际命中的专项 Skill。
 
 ## 交付检查清单
 

package/template/.pi/skills/yss-ui-business-page-generation/references/page-composition-example.md

@@ -0,0 +1,50 @@
+# 页面组合示例
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。示例代码属于目标工程，模块相对导入按所示文件位置解析。
+
+## 最小组合示例
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { YButton, YCard, YTable } from '@yss-ui/components';
+import { useTableHeight } from '@yss-ui/hooks';
+import { TABLE_COLUMNS } from './constant';
+import { useRuleList } from './hooks/useRuleList';
+
+const emit = defineEmits<{ create: [] }>();
+const tableAreaRef = ref<HTMLDivElement>();
+const { tableHeight, isReady } = useTableHeight(tableAreaRef, { withPagination: true, withToolbar: true });
+const { loading, dataList, pagination, handlePageChange } = useRuleList();
+
+/** 打开新增表单，实际项目中由表单 Hook 实现。 */
+const openCreate = (): void => {
+  emit('create');
+};
+</script>
+
+<template>
+  <YCard class="page-card">
+    <div ref="tableAreaRef" class="table-area">
+      <YTable
+        v-if="isReady"
+        :height="tableHeight"
+        :data="dataList"
+        :columns="TABLE_COLUMNS"
+        :loading="loading"
+        pageable
+        v-model:pagination="pagination"
+        @page-change="handlePageChange"
+      >
+        <template #toolbar-right>
+          <YButton type="primary" @click="openCreate">新增</YButton>
+        </template>
+      </YTable>
+    </div>
+  </YCard>
+</template>
+
+<style scoped lang="less">
+@import './style.less';
+</style>
+```

package/template/.pi/skills/yss-ui-business-page-generation/references/page-layout-example.md

@@ -0,0 +1,19 @@
+# 页面目录与组合示例
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。示例代码属于目标工程，模块相对导入按所示文件位置解析。
+
+## 标准代码骨架
+
+```text
+src/views/{module-name}/
+├── index.vue
+├── constant.ts
+├── style.less
+├── hooks/
+│   ├── use{Module}List.ts
+│   └── use{Module}Form.ts
+├── type.ts              # 独立类型较多时增加
+└── components/          # 多个私有视图时增加
+    ├── {Module}Table.vue
+    └── {Module}Modal.vue
+```

package/template/.pi/skills/ytable-usage/SKILL.md

@@ -41,199 +41,11 @@ description: "配置或修复 YSS UI YTable 的列表查询、列、分页、行
 - 使用真实签名 `useTableHeight(tableAreaRef, options)`，结果绑定 `:height="tableHeight"`。稳定布局采用可计算高度的 flex column，表格区设置 `flex: 1; min-height: 0; overflow: hidden`，不用固定大高度或魔法偏移。
 - `pageable`、工具栏插槽、YEditTable 添加按钮分别对应 `withPagination`、`withToolbar`、`withAddButton`；只扣除实际开启的区域。shrink-wrap 容器使用更外层稳定 `boundaryRef`，弹层或隐藏布局仅在可见后按需 `nextTick(recalculateHeight)`。
 
-## 标准代码骨架
+## 按需示例
 
-```typescript
-import type { YTableActionConfig, YTableColumn } from '@yss-ui/components';
+首次搭建列表、列工厂或排查远程分页映射时，读取 [列表与分页示例](references/table-pagination-examples.md)。示例不替代当前项目 API 核验。
 
-/** 列表行数据。 */
-export interface ItemRow {
-  id: string;
-  name: string;
-  status: string;
-}
-
-/** 状态字典。 */
-export const STATUS_OPTIONS = [
-  { label: '启用', value: '1' },
-  { label: '停用', value: '0' },
-];
-
-/** 列表固定列配置。 */
-export const TABLE_COLUMNS: YTableColumn[] = [
-  { type: 'seq', title: '序号', width: 70 },
-  { field: 'name', title: '名称', minWidth: 180 },
-  { field: 'status', title: '状态', width: 120, isTransform: true },
-  { type: 'action', title: '操作', width: 180 },
-];
-
-/** 按组件 Hook 提供的回调创建操作列配置。 */
-export const createActionConfig = (handlers: {
-  onEdit: (row: ItemRow) => void;
-  onDelete: (row: ItemRow) => Promise<void>;
-}): YTableActionConfig => ({
-  width: 180,
-  fixed: 'right',
-  buttons: [
-    { value: 'edit', label: '编辑', type: 'link', click: ({ row }) => handlers.onEdit(row) },
-    {
-      value: 'delete',
-      label: '删除',
-      type: 'link',
-      isConfirm: true,
-      confirmProps: { title: '确认删除该数据吗？', okText: '确定', cancelText: '取消' },
-      click: ({ row }) => handlers.onDelete(row),
-    },
-  ],
-});
-```
-
-## 远程分页 Hook 关键模式
-
-```typescript
-import { ref } from 'vue';
-import type { YTablePagination } from '@yss-ui/components';
-import type { ItemRow } from '../constant';
-
-/** 列表 API 依赖，由当前项目的 Orval 函数适配。 */
-export interface ItemListApi {
-  queryPage: (params: { pageIndex: number; pageSize: number }) => Promise<{
-    list?: ItemRow[];
-    totalCount?: number;
-  }>;
-  deleteItem: (params: { id: string }) => Promise<unknown>;
-}
-
-/** 管理 YTable 远程分页和删除刷新。 */
-export const useItemList = (api: ItemListApi) => {
-  const dataList = ref<ItemRow[]>([]);
-  const loading = ref(false);
-  const currentParams = ref({ pageIndex: 1, pageSize: 20 });
-  const pagination = ref<YTablePagination>({ current: 1, pageSize: 20, total: 0, remote: true });
-
-  /** 查询当前页；错误提示由 mutator 统一处理。 */
-  const loadList = async () => {
-    loading.value = true;
-    try {
-      currentParams.value = {
-        ...currentParams.value,
-        pageIndex: pagination.value.current,
-        pageSize: pagination.value.pageSize,
-      };
-      const result = await api.queryPage(currentParams.value);
-      dataList.value = result.list ?? [];
-      pagination.value = { ...pagination.value, total: result.totalCount ?? 0 };
-    } finally {
-      loading.value = false;
-    }
-  };
-
-  /** 同步 YTable 分页状态并重新查询。 */
-  const handlePageChange = async ({ current, pageSize }: { current: number; pageSize: number }) => {
-    pagination.value = { ...pagination.value, current, pageSize };
-    await loadList();
-  };
-
-  /** 删除后刷新列表；不重复弹出 API 错误。 */
-  const handleDelete = async (row: ItemRow) => {
-    await api.deleteItem({ id: row.id });
-    await loadList();
-  };
-
-  return { currentParams, dataList, loading, pagination, loadList, handlePageChange, handleDelete };
-};
-```
-
-```vue
-<script setup lang="ts">
-import { onMounted, ref } from 'vue';
-import { YButton, YTable } from '@yss-ui/components';
-import { useTableHeight } from '@yss-ui/hooks';
-import { createActionConfig, STATUS_OPTIONS, TABLE_COLUMNS, type ItemRow } from './constant';
-import { useItemList, type ItemListApi } from './hooks/useItemList';
-
-/** 列表实例的 API 依赖。 */
-interface Props {
-  api: ItemListApi;
-}
-
-const props = defineProps<Props>();
-const emit = defineEmits<{
-  create: [];
-  edit: [row: ItemRow];
-}>();
-const tableAreaRef = ref<HTMLDivElement>();
-const { tableHeight } = useTableHeight(tableAreaRef, { withPagination: true, withToolbar: true });
-const { dataList, loading, pagination, loadList, handlePageChange, handleDelete } = useItemList(props.api);
-const actionConfig = createActionConfig({
-  onEdit: row => emit('edit', row),
-  onDelete: handleDelete,
-});
-
-onMounted(loadList);
-</script>
-
-<template>
-  <div ref="tableAreaRef" class="table-area">
-    <YTable
-      :data="dataList"
-      :columns="TABLE_COLUMNS"
-      :action-config="actionConfig"
-      :loading="loading"
-      :options-map="{ status: STATUS_OPTIONS }"
-      :row-config="{ keyField: 'id', useKey: true }"
-      :height="tableHeight"
-      pageable
-      v-model:pagination="pagination"
-      @page-change="handlePageChange"
-    >
-      <template #toolbar-right>
-        <YButton type="primary" @click="emit('create')">新增</YButton>
-      </template>
-    </YTable>
-  </div>
-</template>
-
-<style scoped lang="less">
-@import './style.less';
-</style>
-```
-
-```less
-/* style.less */
-.table-area {
-  flex: 1;
-  min-height: 0;
-  overflow: hidden;
-}
-```
-
-## 表格多选与批量操作标准模式
-
-当业务需要 Checkbox 多选与批量操作（如批量删除、批量导出、批量启用）时，遵循以下规范：
-
-1. **列配置**：首列必须声明 `{ type: 'checkbox', width: 50, fixed: 'left', align: 'center' }`。
-2. **行唯一键**：必须显式指定 `:row-config="{ keyField: 'id', useKey: true }"`（`keyField` 与业务主键如 `userCode` 对齐）。
-3. **受控双向绑定**：推荐优先使用 `v-model:selected-row-keys="selectedRowKeys"` 或 `v-model:selected-rows="selectedRows"`，或者统一监听 `@selection-change`。
-4. **批量操作按钮**：放在 `#toolbar-right`，并配置 `:disabled="selectedRowKeys.length === 0"`。
-5. **清空选中态**：批量操作成功后，清空实际受控的 `selectedRowKeys` / `selectedRows`，并在存在表格内部选择缓存时调用已核验的 `tableRef.value.clearSelection()`。受控状态与组件可见勾选必须一致；不能只清其中一层。
-
-```vue
-<YTable
-  ref="tableRef"
-  v-model:selected-row-keys="selectedRowKeys"
-  :row-config="{ keyField: 'id', useKey: true }"
-  :data="dataList"
-  :columns="TABLE_COLUMNS"
-  pageable
-  v-model:pagination="pagination"
-  @page-change="handlePageChange"
->
-  <template #toolbar-right>
-    <YButton :disabled="selectedRowKeys.length === 0" @click="handleBatchDelete">批量删除</YButton>
-  </template>
-</YTable>
-```
+启用 Checkbox 多选或批量操作时，读取 [多选与批量操作](references/selection-and-batch.md)，核验受控状态、禁用条件和成功后的清理。
 
 ## 插槽与实例边界
 

package/template/.pi/skills/ytable-usage/references/selection-and-batch.md

@@ -0,0 +1,30 @@
+# YTable 多选与批量操作
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。示例代码属于目标工程，模块相对导入按所示文件位置解析。
+
+## 表格多选与批量操作标准模式
+
+当业务需要 Checkbox 多选与批量操作（如批量删除、批量导出、批量启用）时，遵循以下规范：
+
+1. **列配置**：首列必须声明 `{ type: 'checkbox', width: 50, fixed: 'left', align: 'center' }`。
+2. **行唯一键**：必须显式指定 `:row-config="{ keyField: 'id', useKey: true }"`（`keyField` 与业务主键如 `userCode` 对齐）。
+3. **受控双向绑定**：推荐优先使用 `v-model:selected-row-keys="selectedRowKeys"` 或 `v-model:selected-rows="selectedRows"`，或者统一监听 `@selection-change`。
+4. **批量操作按钮**：放在 `#toolbar-right`，并配置 `:disabled="selectedRowKeys.length === 0"`。
+5. **清空选中态**：批量操作成功后，清空实际受控的 `selectedRowKeys` / `selectedRows`，并在存在表格内部选择缓存时调用已核验的 `tableRef.value.clearSelection()`。受控状态与组件可见勾选必须一致；不能只清其中一层。
+
+```vue
+<YTable
+  ref="tableRef"
+  v-model:selected-row-keys="selectedRowKeys"
+  :row-config="{ keyField: 'id', useKey: true }"
+  :data="dataList"
+  :columns="TABLE_COLUMNS"
+  pageable
+  v-model:pagination="pagination"
+  @page-change="handlePageChange"
+>
+  <template #toolbar-right>
+    <YButton :disabled="selectedRowKeys.length === 0" @click="handleBatchDelete">批量删除</YButton>
+  </template>
+</YTable>
+```