create-yss-spec 2.2.0 → 2.2.2

package/template/.trae/skills/yss-page-module-development/references/hooks-map.md

@@ -0,0 +1,11 @@
+# YSS UI Hooks 速查
+
+业务页面生成时优先从 `@yss-ui/hooks` 复用 hooks。
+
+## 高度与异步
+
+- `useTableHeight` 和 `useTreeHeight` 必须绑定真实容器 `ref`，并按页面的分页、工具栏、搜索区选择扣除项。
+- `useLoading` 负责异步 loading 和错误边界；Orval mutator 已提示的错误不得在 `onError` 重复提示。
+- `usePollingTask` 只负责轮询调度，不接管页面的 `loading/data/error`。
+- `useUrlState` 用于把查询条件、分页和 Tab 状态同步到 URL。
+- `useFullscreen` 用于容器、图表或编辑器全屏。

package/template/.trae/skills/yss-page-module-development/references/utils-map.md

@@ -0,0 +1,14 @@
+# YSS UI Utils 速查
+
+业务页面生成时优先从 `@yss-ui/utils` 复用工具函数，避免重复实现。
+
+## 常用工具
+
+- 权限：`getAuthBtns`、`hasAuth`、`getBtnInfo`、`clearAuthInfo`。
+- 复制：`copyToClipboard(text)`。
+- 下载：`downloadFileStream`、`getFileNameFromContentDisposition`、`handleBlobResponse`、`downloadFileFromUrl`。
+- 格式化：`formatMoney`、`formatDate`、`formatFileSize`、`formatDateRelative`。
+- 主题：`applyYssTheme`、`lightenColor`、`darkenColor`。
+- URL：`getUrlData`。
+
+接口导出下载必须读取 `file-export-download` 专项技能，优先复用统一的 Blob 响应处理，不在页面 Hook 重复解析文件名和创建下载链接。

package/template/.trae/skills/yss-product-lifecycle/references/orchestration-contract.yaml

@@ -88,6 +88,9 @@ workflow_execution_result:
       removal_target: schema_version_2
   result_values: [completed, blocked, needs-human, failed]
   required: [result_schema, work_unit, workflow_reference, result, evidence_refs, changed_artifacts, new_impacts, stale_candidates, next_route, blocking_signals]
+  unavailable_skill:
+    required: [skill, provider, fallback, resolution]
+    blocking_result: blocked
   blocking_signals: [drift, new_impacts, violation, missing_evidence, stale_candidates]
   completed_requires_empty: [new_impacts, stale_candidates]
   completed_requires_non_empty: [evidence_refs]
@@ -130,43 +133,101 @@ lifecycle_native_entries:
 work_unit_routes:
   work-unit.discovery-opportunity:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    primary_skill: yss-product-lifecycle
+    supporting_skills: [competitive-intelligence, research]
     skills: [competitive-intelligence, research]
     route_by: {market_or_competitor_fact: competitive-intelligence, technical_or_standard_fact: research, no_external_fact: yss-product-lifecycle}
+    applies_when: opportunity_or_external_fact_requires_validation
+    not_applicable_reason: no_external_fact
   work-unit.discovery-requirements:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    primary_skill: yss-product-lifecycle
+    supporting_skills: [grilling, domain-modeling]
     skills: [grilling, domain-modeling]
+    applies_when: requirements_or_domain_boundary_unclear
+    not_applicable_reason: requirements_already_confirmed
   work-unit.spec-synthesis:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    primary_skill: yss-product-lifecycle
+    supporting_skills: [domain-modeling]
     compatibility: {source: mattpocock/skills, skill: to-spec, invocation_mode: reference, formal_artifact_owner: explicit-user-entry}
     skills: [domain-modeling]
     human_gate: spec-baseline
+    applies_when: new_feature_or_behavior_change
+    not_applicable_reason: existing_frozen_spec_is_current
   work-unit.prototype-design:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
-    skills: [yss-design-system, yss-prototype-stage, yss-antd-design, product-design:index]
+    primary_skill: yss-prototype-stage
+    supporting_skills: [prototype-review, yss-design-system, yss-antd-design, product-design:index]
+    skills: [prototype-review, yss-design-system, yss-prototype-stage, yss-antd-design, product-design:index]
     human_gate: prototype-confirmation
+    applies_when: product_design_impact
+    not_applicable_reason: no_ui_or_product_design_impact
   work-unit.technical-analysis:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    primary_skill: yss-router
+    supporting_skills: [yss-openapi-governance, yss-openapi-draft-review, codebase-design, implementation-repo-onboarding]
     skills: [yss-openapi-governance, yss-openapi-draft-review, codebase-design, implementation-repo-onboarding, yss-router]
     human_gate: openapi-freeze_if_api_impact
+    applies_when: technical_or_contract_impact
+    not_applicable_reason: no_technical_or_contract_impact
   work-unit.ticket-decomposition:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    primary_skill: yss-product-lifecycle
+    supporting_skills: [yss-router]
     compatibility: {source: mattpocock/skills, skill: to-tickets, invocation_mode: reference, formal_artifact_owner: explicit-user-entry}
     skills: [yss-router]
+    applies_when: frozen_scope_ready_for_slicing
+    not_applicable_reason: contract_or_scope_not_frozen
   work-unit.slice-implementation:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    primary_skill: yss-router
+    supporting_skills: [tdd, yss-ui, yss-page-module-development]
     compatibility: {source: mattpocock/skills, skill: implement, invocation_mode: reference, formal_artifact_owner: explicit-user-entry}
     skills: [tdd, yss-router, yss-ui, yss-page-module-development]
+    frontend_route:
+      primary_skill: yss-ui
+      page_orchestration_skill: yss-page-module-development
+      conditional_skills:
+        api_impact: [yss-api-integration]
+        formily_impact: [yss-formily, formily-foundation, formily-linkage-effects, formily-mode-slot-detail, formily-step-flow]
+        table_impact: [ytable-usage, yedit-table-usage]
+        tree_impact: [ytree-usage]
+        height_impact: [yss-use-table-height, yss-use-tree-height]
+        export_impact: [file-export-download]
+        theme_impact: [theme-token-usage]
+      not_applicable_reasons:
+        api_impact: no_api_impact
+        formily_impact: no_formily_impact
+        table_impact: no_table_impact
+        tree_impact: no_tree_impact
+        height_impact: no_height_impact
+        export_impact: no_export_impact
+        theme_impact: no_theme_impact
+    applies_when: ready_for_agent
+    not_applicable_reason: slice_contract_not_approved
   work-unit.frontend-implementation-verification:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    primary_skill: yss-ui
+    supporting_skills: [yss-design-system, code-review]
     skills: [yss-ui, yss-design-system, code-review]
     applies_when: ui_impact
+    not_applicable_reason: no_ui_impact
   work-unit.code-review:
     native: {source: yss-product-lifecycle, skill: code-review, invocation_mode: model-invoked}
+    primary_skill: code-review
+    supporting_skills: []
     skills: [code-review]
+    applies_when: implementation_candidate_exists
+    not_applicable_reason: no_implementation_candidate
   work-unit.release-and-retrospective:
     native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    primary_skill: yss-product-lifecycle
+    supporting_skills: []
     skills: [yss-product-lifecycle]
     human_gate: merge_or_release
+    applies_when: release_or_stage_completion
+    not_applicable_reason: work_not_ready_for_release
 
 compatibility_flow_preconditions:
   to-spec:

package/template/.trae/skills/yss-router/references/boundaries.md

@@ -9,7 +9,7 @@ Use this reference when multiple YSS skills seem applicable.
 - `yss-page-module-development`: Page/module workflow. Use for creating or reorganizing a page folder, deciding structure, and assembling page, hooks, schemas, and blocks.
 - `yss-components`: Component layout and visual/page composition rules. Use for YTable/YTree/YssFormily/YSplitPane usage details.
 - `yss-hook`: Request, pagination, parameter, tree-selection, and response-mapping logic in `views/**/hooks/useXxx.ts`.
-- `api-integration`: Orval-generated API client imports, request/response mapping, `useRequest` calling patterns, submit/list/detail flows.
+- `yss-api-integration`: Orval-generated API client imports, request/response mapping, `useRequest` calling patterns, submit/list/detail flows.
 - `yss-formily`: Hand-written YssFormily schema implementation and form behavior.
 - `yss-formily-schema-generator`: Generate YssFormily schema from requirements, screenshots, mockups, Figma, or natural-language field descriptions.
 - `yss-use-table-height`: Only table available-height calculation and required container/pagination/toolbar wiring.

package/template/.trae/skills/yss-router/references/router-contract.yaml

@@ -4,6 +4,10 @@ forbidden_statuses: [approved, ready-for-agent, completed]
 skill_aliases:
   api-integration: yss-api-integration
   microapp-commit: yss-microapp-commit
+  page-module-development: yss-page-module-development
+  yss-ui-business-page-generation: yss-page-module-development
+  use-table-height: yss-use-table-height
+  use-tree-height: yss-use-tree-height
 implementation_path_policy:
   applies_to: harness-resident-runtime-code
   project_roots:
@@ -169,8 +173,8 @@ dependency_closure:
     when_components: [yss-components]
     when_hooks: [yss-hook]
     when_form: [yss-formily]
-    when_api: [api-integration]
-  api-integration:
+    when_api: [yss-api-integration]
+  yss-api-integration:
     when_regeneration: [yss-openapi-governance]
 
 component_impact_values:

package/template/.trae/skills/yss-ui/SKILL.md

@@ -59,7 +59,7 @@ pnpm why vue @yss-ui/components @yss-ui/hooks ant-design-vue vxe-table
 | Formily schema、联动、校验、详情态 | `yss-formily` |
 | 表格高度 | `yss-use-table-height` |
 | 树高度 | `yss-use-tree-height` |
-| Orval、API、useRequest 接入 | `api-integration` |
+| Orval、API、useRequest 接入 | `yss-api-integration` |
 | 视觉、token、响应式体验 | `yss-design-system` |
 
 不得引用不存在的复数 Hook skill 名称。

package/template/.trae/skills/yss-use-table-height/SKILL.md

@@ -5,6 +5,15 @@ description: Use when working with YTable that needs responsive height, paginati
 
 # useTableHeight 表格高度计算 Hook
 
+本目录是表格高度的 canonical 技能；历史名称 `use-table-height` 仅通过注册表和 Router alias 解析。
+
+## YSS canonical execution rules
+
+- 使用真实签名 `useTableHeight(containerRef, options)`，结果解构为 `tableHeight`、`isReady` 和 `recalculateHeight`。
+- `YTable` 必须绑定 `:height="tableHeight"`；不要只绑定 `max-height`，也不要用固定魔法高度替代 Hook。
+- `pageable`、工具栏和 `YEditTable` 添加按钮分别对应 `withPagination`、`withToolbar` 和 `withAddButton`。
+- 容器使用 `flex: 1; min-height: 0; overflow: hidden`，避免观察由表格内容反向撑开的直属容器。
+
 ## Authoritative Docs And Boundary
 
 - YSS UI hooks documentation: `http://192.168.164.27:3200/hooks`

package/template/.trae/skills/yss-use-tree-height/SKILL.md

@@ -5,6 +5,15 @@ description: Use when working with YTree that needs responsive height, virtual s
 
 # useTreeHeight 树组件高度计算 Hook
 
+本目录是树高度的 canonical 技能；历史名称 `use-tree-height` 仅通过注册表和 Router alias 解析。
+
+## YSS canonical execution rules
+
+- 使用真实签名 `useTreeHeight(containerRef, options)`，结果绑定到 `YTree` 的 `:height`。
+- `filterable` 时配置 `extraOffset: YTREE_SEARCH_HEIGHT`；不得重复扣减或添加无依据偏移。
+- 容器使用 `flex: 1; min-height: 0; overflow: hidden`，隐藏态切换后在可见的 `nextTick` 中调用 `recalculateHeight()`。
+- 不因节点数量少而强制开启虚拟滚动；按实际可见节点阈值决定是否裁剪 DOM。
+
 ## Authoritative Docs And Boundary
 
 - YSS UI hooks documentation: `http://192.168.164.27:3200/hooks`

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

@@ -0,0 +1,251 @@
+---
+name: ytable-usage
+description: 指导 YSS UI 业务列表页、CRUD 表格、远程分页、操作列、气泡确认、列筛选、字典翻译、行拖拽、工具栏和自定义插槽正确使用 @yss-ui/components 的 YTable；当需要配置 YTableColumn、YTableActionConfig、pagination、filter-change 或表格实例方法时使用。
+---
+
+# YTable 使用
+
+## 触发条件
+
+- 生成或修改业务列表、CRUD 表格、远程分页、操作列、列筛选、工具栏或行拖拽。
+- 需要配置 `YTableColumn`、`YTableActionConfig`、分页状态或表格实例方法。
+
+## 不适用场景
+
+- 可编辑表格是核心需求：使用 `../yedit-table-usage/SKILL.md`。
+- 页面只有短小静态数据且不需要表格交互。
+
+## 实施流程
+
+1. 当前会话可用 yss-ui MCP 时，先用 `get_component_docs` 查询 `YTable` 的 Props、Events、Slots、Types 与实例方法；需要远程分页、筛选、操作列、拖拽或工具栏时，再用 `get_demo` 获取对应官方 Demo。
+2. MCP 工具不可用、调用失败或用 `search_docs/list_components` 校正后仍无结果时，才读取最新 `llms-full.txt`；若文档与当前项目依赖版本不一致，用当前源码和导出核验。
+3. 把远程数据、`loading`、分页映射、API 调用和事件处理放入 Hook；把列定义和纯配置放入 `constant.ts`。
+4. 在模板中组合 `data/columns/loading/pagination`，并根据真实开启的工具栏和分页配置高度 Hook。
+5. 完成后核对删除确认、远程筛选、分页字段映射和 API 错误处理边界。
+
+## 硬约束（禁止/必须）
+
+- 必须从 `@yss-ui/components` 导入 `YTable`、`YTableColumn`、`YTableActionConfig` 等真实导出，不使用 `a-table` 实现业务主表格。
+- 远程分页状态使用 `current/pageSize/total/remote`，显式设置 `remote: true`；后端 `pageIndex/pageSize/totalCount` 只在 Hook 中映射。
+- 开启内置分页时传 `pageable`，受控更新使用 `v-model:pagination`，请求时机使用 `@page-change="handlePageChange"`。
+- `page-change` 事件参数固定为 `{ current: number, pageSize: number }`；回调必须读取 `current`，禁止写成组件不会派发的 `currentPage`。
+- YTable 没有 `request` 或 `searchParams` Props；远程查询由业务 Hook 管理。`refresh()` 是真实实例方法，内部调用 vxe-table `updateData()` 刷新当前表格数据，不等于重新调用后端接口。
+- 行键使用 `:row-config="{ keyField: 'id', useKey: true }"`，不臆造 `row-key` Prop。
+- 新增、导入、批量操作等主按钮直接放入 `#toolbar-right` 或 `#toolbar-left` 插槽即可自动渲染工具栏；**无需配置 `:toolbar-config="{ custom: true }"`**，避免无端展示列设置图标；**仅在业务明确需要列设置时才传入 `:toolbar-config="{ custom: true }"`**。
+- 删除、启停、发布等危险操作使用 `actionConfig.buttons[].isConfirm = true`，不默认使用 `Modal.confirm`。
+- 列配置超过 10 行时放入 `constant.ts`；需要调用组件 Hook 的操作配置使用工厂函数注入回调，禁止在 `constant.ts` 直接引用组件局部的 `openEdit/deleteItem`。
+- 远程筛选必须提供稳定 `filters`，设置 `filterMethod: () => true` 禁用本地二次过滤，并监听 `filter-change`。
+- 自适应滚动列表绑定 `:height="tableHeight"`；`pageable`、工具栏分别对应 `withPagination: true`、`withToolbar: true`。纯短表不强制引入高度 Hook。
+- `mutator.ts` 已对网络错误和 `success === false` 统一 `message.error` 并 reject。API Hook 不再检查 `success === false`，不在 `else/catch` 重复 `message.error`；用 `finally` 恢复 loading，让异常继续中断流程。
+
+## 标准代码骨架
+
+```typescript
+import type { YTableActionConfig, YTableColumn } from '@yss-ui/components';
+
+/** 列表行数据。 */
+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 pagination = ref<YTablePagination>({ current: 1, pageSize: 20, total: 0, remote: true });
+
+  /** 查询当前页；错误提示由 mutator 统一处理。 */
+  const loadList = async () => {
+    loading.value = true;
+    try {
+      const result = await api.queryPage({
+        pageIndex: pagination.value.current,
+        pageSize: pagination.value.pageSize,
+      });
+      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 { 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 {
+  height: 100%;
+  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.value = []` 或调用 `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>
+```
+
+## 插槽与实例边界
+
+- 优先使用 kebab-case：单元格 `#<field>`、表头 `#<field>-header`、筛选 `#<field>-filter`、工具栏 `#toolbar-left/#toolbar-right`、展开行 `#expand-row`、分组表头 `#group-header`、更多图标 `#action-more-icon`。
+- `getTableInstance()`、`refresh()`、`recalculate()`、`clearSelection()`、`getSelectedRows()`、`getSelectedRowKeys()`、`setSelection()`、`getPaginationInstance()` 是真实暴露方法；只在对应语义下使用。
+
+## 交付检查清单
+
+- [ ] 分页状态和 `page-change` 参数均使用 `current/pageSize`，未使用 `currentPage`；`filter-change` 与 YTable 真实 API 一致。
+- [ ] 多选列已配置 `type: 'checkbox'`，已设置 `:row-config="{ keyField: 'xxx', useKey: true }"`，批量按钮绑定了 `selectedRowKeys.length === 0` 禁用。
+- [ ] 批量操作成功后已重置 `selectedRowKeys` 并调用 `tableRef.clearSelection()`。
+- [ ] 未使用虚构 `request/searchParams/row-key` Props，也未把 `refresh()` 当成远程请求。
+- [ ] 工具栏、字典翻译、操作确认与高度偏移均与实际开关一致。
+- [ ] API Hook 没有 `success === false` 分支或重复 `message.error`。
+
+## 失败兜底策略
+
+- 分页字段混乱时，在 Hook 中分离 YTable 状态和后端参数，不直接把 `pageIndex/totalCount` 绑到组件。
+- 操作过多时使用 `displayLimit` 和更多菜单；远程刷新失效时回到业务 `loadList()`，不把实例 `refresh()` 当成接口请求。
+- API 失败后只在 `finally` 恢复本地 loading，让 mutator 的 reject 继续中断删除后刷新等后续流程。
+

package/template/.trae/skills/ytree-usage/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: ytree-usage
+description: 指导 YSS UI 左树右表、组织树、分类树、目录树和节点管理页使用 @yss-ui/components 的 YTree，覆盖 fieldNames 字段映射、搜索过滤、受控选中、节点动作、删除确认、虚拟滚动和自适应高度；当生成或修改树形筛选、左树右表、树搜索或树节点操作时使用。
+---
+
+# YTree 使用
+
+## 触发条件
+
+- 生成或修改左树右表、组织树、分类树、目录树、树搜索或树节点操作。
+- 需要配置 `fieldNames`、受控选中、`YTreeActionItem` 或树区域自适应高度。
+
+## 不适用场景
+
+- 树数据只用于表单 TreeSelect 字段：使用 `YFormily` 或对应表单规范。
+- 页面只有普通列表而没有层级筛选：使用 `../ytable-usage/SKILL.md`。
+
+## 实施流程
+
+1. 当前会话可用 yss-ui MCP 时，先用 `get_component_docs` 查询 `YTree` 的 Props、Slots、Events 和 `YTreeActionItem`；需要搜索、节点动作、受控选中或左树右表时，再用 `get_demo` 获取对应官方 Demo。
+2. MCP 工具不可用、调用失败或用 `search_docs/list_components` 校正后仍无结果时，才读取最新 `llms-full.txt`；若文档与当前项目依赖版本不一致，用当前源码和导出核验。
+3. 确定树数据的 title/key/children 字段、受控状态和选中后的业务联动。
+4. 按容器布局配置 `useTreeHeight`，再添加搜索和节点动作。
+5. 若包含删除，单独完成气泡确认链路；不把 `danger` 颜色当成二次确认。
+
+## 硬约束（禁止/必须）
+
+- 从 `@yss-ui/components` 导入 `YTree`、`YTreeActionItem` 等真实导出；高度使用 `@yss-ui/hooks` 的 `useTreeHeight`。
+- 数据字段不一致时配置 `fieldNames`，不为了改名重复递归复制树数据。
+- 搜索使用 `filterable + v-model:searchValue`；受控选中使用 `v-model:selectedKeys`。
+- 普通节点菜单使用 `showActions + getNodeActions`，并监听 `@action`。`YTreeActionItem` 只支持 `key/label/icon/disabled/danger`，禁止臆造 `isConfirm/click` 等字段。
+- `danger: true` 只改变危险项视觉，不会弹出确认框。删除必须放在节点附近的 `#node-suffix` 或当前选中节点操作区，用 Ant Design Vue `Popconfirm` 的 `@confirm` 调用接口；不使用居中 `Modal.confirm`。
+- 树区域需要滚动时绑定 `:height="treeHeight"`，不默认添加 `:virtual="true"`。只有展开后可见扁平节点数 `* itemHeight > height` 时才会实际裁剪 DOM。
+- 使用 YTree 内置搜索时，高度 Hook 通过 `extraOffset: YTREE_SEARCH_HEIGHT` 扣除 48px；不再叠加无依据的魔法数。
+- 左树右表优先组合 `YSplitPane + YCard + YTree + YTable`；切换节点时同步查询条件并把右表分页重置为第 1 页。
+- 节点删除 API 的错误由 `mutator.ts` 统一提示并 reject；不在 `else/catch` 重复 `message.error`。
+
+## 标准代码骨架
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { YTree, type YTreeActionItem } from '@yss-ui/components';
+import { useTreeHeight, YTREE_SEARCH_HEIGHT } from '@yss-ui/hooks';
+
+/** 树节点数据。 */
+interface TreeNode {
+  id: string;
+  name: string;
+  children?: TreeNode[];
+}
+
+const emit = defineEmits<{
+  create: [node: TreeNode];
+  edit: [node: TreeNode];
+}>();
+const treeAreaRef = ref<HTMLDivElement>();
+const treeData = ref<TreeNode[]>([]);
+const searchValue = ref('');
+const selectedKeys = ref<Array<string | number>>([]);
+const { treeHeight } = useTreeHeight(treeAreaRef, {
+  extraOffset: YTREE_SEARCH_HEIGHT,
+});
+
+/** 生成当前节点的非危险操作。 */
+const getNodeActions = (): YTreeActionItem[] => [
+  { key: 'add', label: '新增子节点' },
+  { key: 'edit', label: '编辑' },
+];
+
+/** 处理 YTree 动作事件。 */
+const handleTreeAction = ({ key, node }: { key: string; node: TreeNode }) => {
+  if (key === 'add') emit('create', node);
+  if (key === 'edit') emit('edit', node);
+};
+</script>
+
+<template>
+  <div ref="treeAreaRef" class="tree-area">
+    <YTree
+      :height="treeHeight"
+      :tree-data="treeData"
+      :field-names="{ title: 'name', key: 'id', children: 'children' }"
+      filterable
+      show-actions
+      v-model:searchValue="searchValue"
+      v-model:selectedKeys="selectedKeys"
+      :get-node-actions="getNodeActions"
+      @action="handleTreeAction"
+    />
+  </div>
+</template>
+
+<style scoped lang="less">
+@import './style.less';
+</style>
+```
+
+```less
+/* style.less */
+.tree-area {
+  flex: 1;
+  min-height: 0;
+  overflow: hidden;
+}
+```
+
+## 删除确认边界
+
+```vue
+<template #node-suffix="{ node }">
+  <Popconfirm title="确认删除该节点吗？" ok-text="确定" cancel-text="取消" @confirm="handleDelete(node)">
+    <YButton type="link" @click.stop>删除</YButton>
+  </Popconfirm>
+</template>
+```
+
+`Popconfirm` 从 `ant-design-vue` 导入，`YButton` 从 `@yss-ui/components` 导入。如果每个节点都展示删除会过密，把同样的 `Popconfirm` 放到选中节点的页面工具栏。
+
+## 交付检查清单
+
+- [ ] `fieldNames`、`searchValue`、`selectedKeys`、`action` 与真实 API 一致。
+- [ ] 节点动作项未出现虚构字段，删除不会点菜单后立即执行。
+- [ ] 高度偏移与内置搜索实际开关一致，没有多扣魔法数。
+- [ ] 左树选中后，右表查询条件和分页重置闭环清晰。
+
+## 失败兜底策略
+
+- 节点字段不统一时先修正 `fieldNames`，不复制整棵树换键。
+- 点击删除立即调用 API 时，移出节点动作菜单，改为节点附近或页面操作区 `Popconfirm`。
+- 传入 `height` 但节点未裁剪时，先核对展开后可见节点数、`itemHeight` 和阈值，不盲目强制 `virtual=true`。
+- 节点 API 失败后让 mutator reject 中断右表刷新等后续流程，不重复错误提示。

package/template/AGENTS.md

@@ -10,7 +10,7 @@
 - `repository_mode: project-instance`：按产品研发生命周期分诊任务。
 - 文件缺失、schema 版本不支持或模式值非法时，停止路由并执行迁移检查；不根据目录、Git 远程或占位符猜测身份。
 
-仓库身份契约见 `docs/adr/0002-yss-project-repository-mode.md`。
+仓库身份契约由根目录 `yss-project.yaml` 和本文件共同声明。
 
 ## 2. 单一事实来源
 
@@ -108,15 +108,3 @@ README、用户指南、根目录 `CLAUDE.md` 和其他说明文档只引用或
 ## 12. 测试质量基线
 
 模板推荐值为 Domain / Application `>= 90%`、API `>= 80%`、前端组件 `>= 75%`、已明确的关键流程 `100% E2E`。只有项目实例在测试策略中明确采纳或覆盖后才构成 CI 门禁；未定义关键流程清单时，不声称其 E2E 覆盖率达到 100%。
-
-## Cursor Cloud specific instructions
-
-本仓库是 `template-source` Harness / 研发管理仓库，没有前端 / 后端运行时应用；可运行、可测试的表面只有 Node 工具链与治理校验脚本。
-
-- 依赖与工具链：Node `>=22 <27`（`.nvmrc` 固定 22）；`pnpm` 通过 `packageManager` 字段由 corepack 自动切换到 `10.15.0`，无需手工切换。Node 依赖只装在 `.template-source/tooling/node`，仓库根没有 `package.json`。本仓 wiki-root 为 `.template-source/wiki`。
-- 测试：`pnpm --dir .template-source/tooling/node test`（`node --test`，共 16 个用例）。
-- 构建 / lint：`pnpm --dir .template-source/tooling/node build:vendor` 与 `check:vendor` 维护 `scripts/vendor/*.mjs`；顶层 lint 是 `verify-template` 内对所有脚本执行的 `node --check`。
-- 完整发布门禁（相当于"运行应用"）：`scripts/verify-template`，成功输出 `模板发布校验通过`。它串联证据索引、`pnpm test`、`check:vendor` 和全部 `scripts/verify-*` 场景校验。
-- 非显然的坑：`scripts/verify-lifecycle-registry`（及其对应测试 `Node lifecycle registry verifier ...`）会 shell out 到 `python3` 并 `import jsonschema` 做 JSON Schema 校验。缺少该 Python 模块时测试会以 `ModuleNotFoundError: No module named 'jsonschema'` 失败，而不是代码问题；update script 已负责 `pip3 install jsonschema`。
-- `pnpm install` 输出的 `Ignored build scripts: esbuild` 警告可忽略：esbuild 0.28.2 在本平台自带二进制，`build:vendor` / `check:vendor` 无需 `pnpm approve-builds`。
-- 常用只读入口：`scripts/repository-mode`（返回仓库身份）、`scripts/generate-lifecycle-artifacts`（从 `docs/process/lifecycle-registry.yaml` 派生产物，输出应无 diff）、`scripts/export-yss-skills --output <dir>`（导出公开技能）。

package/template/docs/adr/README.md

@@ -0,0 +1,7 @@
+# 产品架构决策
+
+本目录只记录当前项目自身的架构决策，不承载 `yss-spec-project-template` 模板源仓库的治理决策。
+
+创建 ADR 时使用 [`docs/templates/adr-template.md`](../templates/adr-template.md)，并为每条决策补充状态、背景、取舍、后果和相关资产。
+
+模板源仓库的 ADR 保存在 `.template-source/adr/`，不会随 `create-yss-spec` 进入 `project-instance`。

package/template/docs/agents/skill-migrations.md

@@ -0,0 +1,16 @@
+# 技能迁移说明
+
+本文记录已退役技能入口的迁移路径。退役技能不保留物理目录、投影或 lock 条目；本文件是历史名称的唯一持久兼容说明。
+
+## high-fidelity-html-prototype
+
+`high-fidelity-html-prototype` 已退役，不再作为 Router alias、默认发现入口或独立物理技能存在。
+
+迁移到：
+
+- 阶段合同：`yss-prototype-stage`
+- Codex 产品设计主入口：`product-design:index`
+- Ant Design v6 事实与 CLI 证据：`yss-antd-design`
+- 独立低保真评审：`prototype-review`
+
+迁移时保留原型评审记录、AntD CLI 验证、浏览器验证和用户确认，并由 `yss-product-lifecycle` 裁决 `gate.prototype-reviewed`、`gate.prototype-verified` 和 `gate.user-confirmation`。不得创建同名兼容目录。