create-yss-spec 3.5.6 → 3.5.9

package/template/.agents/skills/yss-ui/references/quick-recipes.md

@@ -1,280 +1,25 @@
-# yss-ui Quick Recipes
+# YSS UI 场景与示例入口
 
-## 使用说明
+新建页面时，按当前任务选择下面的示例；重构时依次核对列与插槽、请求与分页、路由和交付证据。示例用于说明组件组合，不决定业务字段、接口包装或实现资格。先消费批准合同、目标 lockfile、类型和真实导出；本地快照与目标版本不同的部分需重新核验。
 
-- 当任务是“新建页面”时，优先选用最接近的模板再改字段与交互。
-- 当任务是“重构页面”时，按“列定义 -> 插槽 -> 请求 -> 分页 -> 路由”顺序迁移。
-- 模板默认基于 Vue 3 + TypeScript + `@yss-ui/components`。
-- 组件与 Demo 先对照 `../assets/reference-index.md` 和 `../assets/demos/*` 再编码。
+## 专项技能的可用性
 
----
+下表链接的公共路由、API 资料和 Demo 随公开包提供；`ytable-usage`、`ytree-usage`、`formily-*`、`file-export-download`、`theme-token-usage` 专项不随该包附带。任务命中时仍加载消费工程已安装的对应专项，由原专项持有唯一规则；部分组件资料、Demo 或 Blob 响应说明不能替代完整专项与批准合同。
 
-## 组件样例速查（docs 对照）
+必要专项未安装或不可读时，停止受影响的实现，记录缺失 Skill 与来源；从消费工程已登记的技能来源恢复，核验版本与项目基线一致并重新读取后再继续。只读诊断可以使用随包资料确认组件事实，不据此跳过必需专项或批准输入。分步场景仍由 `formily-step-flow` 决定，不以快照中的 FormStep Demo 替代其方案。
 
-- YTable：`../assets/demos/table/*`
-- YEditTable：`../assets/demos/edit-table/*`
-- YssFormily：`../assets/demos/formily/*`
-- YTree：`../assets/demos/tree/*`
-- SplitPane：`../assets/demos/split-pane/*`
-- YMonaco：`../assets/demos/monaco/*`
-- YEcharts：`../assets/demos/echarts/*`
-- YFileImport：`../assets/demos/file-import/*`
-- YConditionBuilder：`../assets/demos/condition-builder/*`
-- YCron：`../assets/demos/cron/*`
-- YCard：`../assets/demos/card/*`
-- YButton：`../assets/demos/button/*`
+## 按场景读取
 
----
+| 当前任务 | 按需读取 | 必须保留的场景差异 |
+|---|---|---|
+| 列表管理：选择、分页、状态和操作 | [YTable 组件 API](../assets/docs/components/table.md) 与 [列表请求及分页](../../yss-hook/references/list-pagination.md)；选择和批量操作由已加载的 `ytable-usage` 核对 | `pageable`、`pagination.remote` 和 `@page-change` 单对象 `{ current, pageSize }`；危险操作确认与成功后选择态清理 |
+| 待办审批：列表与详情抽屉 | [业务页面生成](../../yss-ui-business-page-generation/SKILL.md) 与 [模式及插槽路由](../../yss-formily/SKILL.md)，按命中条件加载 `formily-mode-slot-detail` | 抽屉打开前准备记录，关闭时清理临时状态；同意、拒绝等行为消费冻结规则与当前权限 |
+| 分步创建与步骤中的节点列表 | [分步场景路由](../../yss-formily/SKILL.md)加载 `formily-step-flow`；节点列表再按已安装的 YTable 专项 | 当前步骤校验成功才前进，前序数据跨步骤保留，编辑弹层保存后回填源数据，确认步骤不另造提交数据源 |
+| 列表请求与 Mock 接入 | [API 集成](../../yss-api-integration/SKILL.md) 与 [列表分页 Hook](../../yss-hook/references/list-pagination.md) | 请求、响应与 Mock 均遵循目标冻结 DTO，分页字段在 Hook 边界映射；不固定 `page`、`data.list` 或响应包装 |
+| 左树右表 | [YTree 组件 API](../assets/docs/components/tree.md) 与 [页面组合](../../yss-ui-business-page-generation/references/page-composition-example.md)；树与删除确认由已加载的 `ytree-usage` 核对 | `YSplitPane + YCard + YTree + YTable`，树选中后右表回第一页，高度偏移只扣实际启用区域 |
+| 同一表单新增、编辑与查看 | [三态与插槽路由](../../yss-formily/SKILL.md)加载 `formily-mode-slot-detail` | 新代码使用 `YFormily`；历史 `YssFormily` 只在真实兼容导出已确认时维护；详情路径与编辑 Slot 分开 |
+| 文件导入两步流 | [YFileImport 边界](specialized-components.md#yfileimport) 与 [导入 Demo](../assets/demos/file-import/basic.vue) | 文件选择 / 结果确认、`nextStep` / `finalImport` / `exportErrorData`；下载失败数据时先加载已安装的 `file-export-download`，响应边界另核对 [API 集成](../../yss-api-integration/SKILL.md)的 Blob 契约 |
 
-## 模板 1：列表管理页（带勾选、分页、状态、操作）
+完整组件与 Demo 入口见 [场景索引](../assets/scenario-index.md)和[文档索引](../assets/reference-index.md)。仅加载当前使用的表格、编辑表格、Formily、树、分栏、Monaco、图表、文件导入、条件构建、Cron、Card 或 Button；不预读所有示例。
 
-```ts
-import { reactive, ref } from "vue";
-import { YTable, type YTableColumn } from "@yss-ui/components";
-
-const loading = ref(false);
-const tableData = ref<any[]>([]);
-const pagination = reactive({
-  current: 1,
-  pageSize: 10,
-  total: 0,
-  showSizeChanger: true,
-  showQuickJumper: true,
-});
-
-const columns = reactive<YTableColumn[]>([
-  { type: "checkbox", width: 50, align: "center" },
-  { type: "seq", title: "序号", width: 60, align: "center" },
-  { field: "name", title: "名称", minWidth: 180 },
-  { field: "owner", title: "负责人", width: 120 },
-  { field: "updatedAt", title: "更新时间", width: 180 },
-  { field: "status", title: "状态", width: 110 },
-  { field: "action", title: "操作", width: 180, fixed: "right" as const },
-]);
-```
-
-```vue
-<YTable
-  :columns="columns"
-  :row-config="{ keyField: 'id' }"
-  :data="tableData"
-  :loading="loading"
-  :pagination="pagination"
-  :checkbox-config="{ highlight: true }"
-  @change="handlePageChange"
->
-  <template #status="{ row }">
-    <span :class="['status-dot', row.status === 'ENABLED' ? 'enabled' : 'disabled']"></span>
-    {{ row.status === "ENABLED" ? "启用" : "停用" }}
-  </template>
-  <template #action="{ row }">
-    <a @click="handleEdit(row)">编辑</a>
-    <a @click="handleDetail(row)">详情</a>
-    <a style="color: #ff4d4f" @click="handleDelete(row)">删除</a>
-  </template>
-</YTable>
-```
-
----
-
-## 模板 2：待办审批页（列表 + 详情抽屉）
-
-```ts
-import { ref, reactive } from "vue";
-import { YTable, type YTableColumn } from "@yss-ui/components";
-
-const detailVisible = ref(false);
-const activeRecord = ref<any>(null);
-
-const columns = reactive<YTableColumn[]>([
-  { type: "checkbox", width: 50, align: "center" },
-  { type: "seq", title: "序号", width: 60, align: "center" },
-  { field: "approvalName", title: "审批名称", width: 220 },
-  { field: "submitter", title: "提交人", width: 120 },
-  { field: "submittedAt", title: "提交时间", width: 180 },
-  { field: "status", title: "状态", width: 110 },
-  { field: "action", title: "操作", width: 220, fixed: "right" as const },
-]);
-```
-
-```vue
-<YTable :columns="columns" :row-config="{ keyField: 'id' }" :data="tableData">
-  <template #approvalName="{ row }">
-    <a @click="openDetail(row)">{{ row.approvalName }}</a>
-  </template>
-  <template #action="{ row }">
-    <a @click="handleApprove(row)">同意</a>
-    <a style="color: #ff4d4f" @click="handleReject(row)">拒绝</a>
-    <a @click="openDetail(row)">详情</a>
-  </template>
-</YTable>
-```
-
----
-
-## 模板 3：步骤创建页（步骤二节点表格）
-
-```ts
-import { reactive, ref } from "vue";
-import { YTable, type YTableColumn } from "@yss-ui/components";
-
-const nodeList = ref<any[]>([]);
-
-const nodeColumns = reactive<YTableColumn[]>([
-  { type: "seq", title: "序号", width: 70, align: "center" },
-  { field: "nodeName", title: "节点名称", minWidth: 160 },
-  { field: "taskType", title: "任务策略类型", width: 140 },
-  { field: "approverType", title: "审批人类型", width: 140 },
-  { field: "approvers", title: "审批人", minWidth: 220 },
-  { field: "action", title: "操作", width: 130, fixed: "right" as const },
-]);
-```
-
-```vue
-<YTable
-  :columns="nodeColumns"
-  :row-config="{ keyField: 'id' }"
-  :data="nodeList"
-  :border="true"
->
-  <template #taskType="{ row }">
-    {{ row.taskType === "AUTO" ? "自动通过审批" : "人工审批" }}
-  </template>
-  <template #approvers="{ row }">
-    {{ row.approvers.join("、") || "-" }}
-  </template>
-  <template #action="{ row }">
-    <a @click="openEditDrawer(row)">编辑</a>
-    <a style="color: #ff4d4f" @click="removeNode(row.id)">删除</a>
-  </template>
-</YTable>
-```
-
----
-
-## 模板 4：列表请求 + API 接入
-
-```ts
-const fetchData = async () => {
-  loading.value = true;
-  try {
-    const res = await getListApi({
-      page: pagination.current,
-      pageSize: pagination.pageSize,
-      keyword: query.keyword || undefined,
-      status: query.status || undefined,
-    });
-    tableData.value = res?.data?.list || [];
-    pagination.total = res?.data?.total || 0;
-  } finally {
-    loading.value = false;
-  }
-};
-
-const handleSearch = () => {
-  pagination.current = 1;
-  fetchData();
-};
-
-const handlePageChange = (page: number, size: number) => {
-  pagination.current = page;
-  pagination.pageSize = size;
-  fetchData();
-};
-```
-
-Mock 返回建议结构：
-
-```json
-{
-  "code": 200,
-  "message": "success",
-  "data": {
-    "list": [],
-    "total": 0,
-    "page": 1,
-    "pageSize": 10
-  }
-}
-```
-
----
-
-## 模板 5：树表页面（YTree + useTreeHeight + SplitPane）
-
-```ts
-import { ref } from "vue";
-import { useTreeHeight, YTREE_SEARCH_HEIGHT } from "@yss-ui/hooks";
-
-const treeWrapRef = ref<HTMLDivElement>();
-const selectedKeys = ref<(string | number)[]>([]);
-const searchValue = ref("");
-const { treeHeight } = useTreeHeight(treeWrapRef, {
-  extraOffset: YTREE_SEARCH_HEIGHT,
-});
-```
-
-```vue
-<div class="layout">
-  <YSplitPane :initial-width="300" :min-width="240" :max-width="480">
-    <template #left>
-      <div ref="treeWrapRef" class="tree-wrap">
-        <YTree
-          v-model:searchValue="searchValue"
-          v-model:selectedKeys="selectedKeys"
-          :height="treeHeight"
-          :tree-data="treeData"
-          filterable
-          @select="handleTreeSelect"
-        />
-      </div>
-    </template>
-    <template #right>
-      <YTable :columns="columns" :data="tableData" :row-config="{ keyField: 'id' }" />
-    </template>
-  </YSplitPane>
-</div>
-```
-
----
-
-## 模板 6：YssFormily 模式切换（新增/编辑/查看）
-
-```ts
-const mode = ref<0 | 1 | 2>(0);
-const formData = ref<Record<string, any>>({});
-```
-
-```vue
-<YssFormily v-model="formData" :schema="schema" :mode="mode">
-  <template #detail-owner="{ value }">
-    <a-tag color="blue">{{ value || "-" }}</a-tag>
-  </template>
-</YssFormily>
-```
-
-规则要点：
-
-- 查看态插槽固定命名：`detail-<字段路径>`，路径中的 `.` 改为 `-`
-- 输入类事件优先 `onUpdate:value`，跨字段逻辑优先 `x-reactions/effects`
-
----
-
-## 模板 7：文件导入两步流（YFileImport）
-
-```vue
-<YFileImport
-  v-model="visible"
-  :file-type-list="['xls', 'xlsx', 'csv']"
-  :import-result="importResult"
-  @nextStep="handleNextStep"
-  @finalImport="handleFinalImport"
-  @exportErrorData="handleExportErrorData"
-/>
-```
-
-要点：
-
-- 走“选择文件 -> 结果确认”两步交互
-- 失败数据通过 `exportErrorData` 下载回溯
-- 与表单联动时可复用 `formily.vue` 示例模式
+样例中的视觉表达消费 [设计系统](../../yss-design-system/SKILL.md)和[主题、Locale 与浮层基线](theme-locale-overlay.md)；涉及 Token 实现与换肤时仍加载已安装的 `theme-token-usage`，由原专项决定规则。错误提示服从项目 mutator，操作失败不能继续执行成功动作。页面验收保留当前 Slice 的 `frontend_implementation_plan` / `frontend_implementation_verification`，以及所需截图、交互、console warning 和实际 `pnpm` 退出码。

package/template/.agents/skills/yss-ui/references/specialized-components.md

@@ -13,7 +13,7 @@
 - 根值是 `ConditionGroup`；叶子保持字段、操作符和值的标准模型。接口 DSL 的序列化、恢复与错误兜底放入 Hook。
 - 字段切换需要动态操作符或候选值时使用组件公开的加载入口；提交前执行公开校验。
 - 默认严格校验，只有明确允许未完成草稿时才关闭；展示态使用 `disabled`，不使用已废弃的 `readonly`。
-- 组件资料见 `../assets/component-docs/condition-builder-*`，实现前仍须核对目标项目安装版本。
+- 组件资料见 [条件构建器快照](../assets/docs/components/conditionBuilder.md)，实现前仍须核对目标项目安装版本。
 
 ## YMonthCalendar
 
@@ -27,7 +27,7 @@
 - 文件选择、预检、结果回显和最终确认组成两步流程；业务上传与校验由 `nextStep` / `finalImport` 接入。
 - 默认 `beforeUpload=false`，不能期待 `action` 自动上传；直传只通过 `upload-props.customRequest`。
 - `importResult` 展示结果，失败数据通过 `exportErrorData` 下载。弹窗配置与上传器配置保持分离。
-- 组件资料见 `../assets/component-docs/file-import-*`。
+- 组件资料见 [文件导入快照](../assets/docs/components/fileImport.md)。
 
 ## YMonaco / YMonacoDiff
 
@@ -46,7 +46,7 @@
 - 初始化后只通过公开 Facade API 修改工作簿，并通过公开保存入口取值；不得直接修改工作簿原始数据对象。
 - 卸载时释放实例，接入前确认 Univer、React、RxJS 等可选依赖及包体影响。
 
-## YssEcharts
+## YEcharts
 
 - option、更新策略和容器尺寸以目标版本手册与项目已验证实践为准。
 - 不在页面层重复原生 ECharts 初始化、销毁或 ResizeObserver 管理。

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

@@ -87,7 +87,7 @@ description: "生成或改造完整 YSS UI CRUD、列表、表单、详情或左
 ## 交付检查清单
 
 - [ ] 已优先复用 `@yss-ui/components`、`@yss-ui/hooks`、`@yss-ui/utils`。
-- [ ] `index.vue` 不超过 150 行，业务逻辑、常量、列配置和样式已按职责拆分。
+- [ ] `index.vue` 负责 Hook 组合、视图编排和事件转发；业务逻辑、常量、列配置和样式已按职责拆分。
 - [ ] 未出现未导出的 Y 前缀组件。
 - [ ] 未导入 `@formily/antd-v3`、`@formily/antd` 或业务层 `@formily/antdv` UI 组件。
 - [ ] `YTable` 分页字段为 `current/pageSize/total`。

package/template/.agents/skills/yss-up-springboot3/SKILL.md

@@ -5,15 +5,13 @@ description: "审查或迁移 YSS Spring Boot 2 到 3 的依赖、Jakarta 与 Sp
 
 # yss-up-springboot3
 
-Use this skill for catalog-driven YSS backend upgrade analysis and approved migrations from an exact Spring Boot 2 platform to an exact Spring Boot 3 platform.
+本 Skill 从精确 Spring Boot 2 平台分析并执行已批准的 Spring Boot 3 迁移，不替代具体组件 Skill。源平台、目标平台和组件能力只从 `.template-spec/engineering/backend-platforms.json`、批准的 `platform_configuration`、工程 Manifest、effective POM 与实际依赖树解析，不按版本记忆或源码可编译状态推断兼容。
 
-中文说明：这个技能是平台迁移编排入口，不替代具体组件 Skill。源平台、目标平台和组件能力只从 `.template-spec/engineering/backend-platforms.json`、批准的 `platform_configuration`、工程 Manifest、effective POM 与实际依赖树解析，不按版本记忆或源码可编译状态推断兼容。
+## 何时使用
 
-## When To Use
-
-- The user asks to assess or migrate a YSS backend from Spring Boot 2 to Spring Boot 3.
-- The task mentions `javax.*` to `jakarta.*`, Spring Security migration, validation changes, Servlet API changes, Gateway/OpenFeign compatibility, or dependency BOM changes.
-- The task involves checking whether a YSS component can run on Spring Boot 3.
+- 评估或迁移 YSS 后端的 Spring Boot 2 → 3 平台。
+- 平台迁移涉及 `javax.*` → `jakarta.*`、Spring Security、Validation、Servlet、Gateway/OpenFeign 或依赖 BOM。
+- 核验 YSS 组件在指定 Spring Boot 3 平台的兼容状态。
 
 ## 准入与阻断
 
@@ -22,7 +20,7 @@ Use this skill for catalog-driven YSS backend upgrade analysis and approved migr
 - 既有工程的源码编译、单元测试或 `javax`→`jakarta` 替换不等于平台认证。没有目标架构的真实构件、启动和组件 seam 证据时不得宣称迁移完成。
 - 平台迁移不得夹带业务重构、架构族转换或组件替换。发现这些影响时返回 `new_impacts`，交实现合同编译器重新路由。
 
-## Workflow
+## 迁移流程
 
 1. 从工程登记、Manifest、父/BOM、effective POM 和依赖树冻结源 `platform_configuration`、架构 Profile、全部 YSS GAV、组件绑定及基线验证命令；缺失或相互冲突时停止。
 2. 从平台目录选择一个精确 Spring Boot 3 目标 profile，记录 compatibility id/digest；不得使用 `3.x`、`latest`、范围版本或自行拼装父/BOM。
@@ -33,22 +31,22 @@ Use this skill for catalog-driven YSS backend upgrade analysis and approved migr
 7. 使用工程根 `./mvnw` 记录 effective POM、依赖树、`validate`、`test`、`package`、随机端口启动和真实组件 seam；DDD 与 MVC 证据不可互相代替。
 8. 重新解析全部组件绑定并比较摘要；通过只表示该工程的批准迁移结果，不自动把共享平台或其他工程标记为 verified。
 
-## Common Checks
+## 适用检查
 
-- Maven BOM and plugin versions are aligned before changing code.
-- `javax.*` imports are migrated only where the target framework expects Jakarta APIs.
-- Spring Security configuration no longer depends on removed `WebSecurityConfigurerAdapter` patterns.
-- Validation annotations and exception handlers still map to the expected DTO/Result contract.
-- MyBatis interceptors, auto configurations, and starter metadata are compatible with Spring Boot 3 auto-configuration loading.
-- Tests or sample modules are updated together with framework code.
+- 改代码前核对 Maven BOM 与插件版本。
+- 仅目标框架要求 Jakarta 的 API 迁移 `javax.*` import。
+- Spring Security 配置不依赖已移除的 `WebSecurityConfigurerAdapter` 模式。
+- Validation 注解与异常处理仍映射到冻结 DTO/Result 合同。
+- MyBatis 拦截器、自动配置与 starter metadata 符合目标 Boot 3 装载机制。
+- 受影响测试或样例模块与框架代码同步。
 - Jackson 2 的 Result/PageResult、日期、枚举、nullability 和错误响应 wire fixture 与冻结 OpenAPI 一致。
 - `spring.factories` 与 `AutoConfiguration.imports` 的目标机制以真实 starter 为准，不能仅移动文件名后宣称自动配置生效。
 - 输出包含源/目标 profile、compatibility digest、组件逐项结论、阻塞项、实际命令与回滚点。
 
-## Do Not
+## 修改边界
 
-- Do not blindly rewrite all `javax.*` imports without checking whether the dependency still uses the old namespace.
-- Do not mix unrelated business refactors into migration patches.
-- Do not assume component compatibility from memory; inspect source and specialist skill indexes.
-- Do not bypass a blocked component by excluding its starter, copying component code into the service, or substituting an unapproved third-party dependency.
-- Do not execute a Boot 4 migration under this Skill or reuse Boot 3 evidence for Boot 4.
+- 先核验依赖实际命名空间，不批量替换全部 `javax.*`。
+- 迁移不夹带无关业务重构。
+- 组件兼容结论使用源码、专项索引和平台证据，不使用版本记忆。
+- 不能通过排除 starter、复制组件源码到服务或换未批准第三方依赖绕过组件阻断。
+- Boot 4 另行路由，不复用 Boot 3 证据执行其迁移。

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

@@ -5,52 +5,46 @@ description: "接入或排查 YSS CurrentUserProvider、已认证 SecurityContex
 
 # yss-userinfo
 
-Use this skill for YSS 用户信息组件. Keep implementation grounded in the local project and resolvable YSS backend component source.
+处理已认证当前用户、受信网关适配、自定义 `CurrentUserProvider` 和后台空上下文；身份来源须符合当前平台契约。
 
-中文说明：本技能用于 YSS 用户信息组件。执行时优先读取源码索引，避免凭记忆猜类名、配置项或接入方式。
+## 平台与源码门禁
 
-## Source Index First
+接入、修改、代码生成或提供精确类名/配置前，必须读取并执行 [共享平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，以 `--skill yss-userinfo` 校验批准的平台线及匹配源码根。缺失、错配或漂移返回 `blocked`；不跨代回退，不在业务实现中升级、降级或替换组件。只读分诊可继续，但须标注未完成源码核验，不能据此宣称跨 Boot/JDK 兼容。
 
-- Backend source location is environment-specific; resolve it with `yss-skill-source-index-refresh/references/source-location.md`.
-- Generated index: `references/source-index.md`
-- Component path hints: `yss-microservice-components/yss-component-userinfo-starter`
+## 源码定位
 
-Read `references/source-index.md` as a path-hint index whenever the task depends on exact modules, annotations, auto configuration, properties, controllers, clients, repositories, DTOs, handlers, or troubleshooting.
+按 [源码定位策略](../yss-skill-source-index-refresh/references/source-location.md) 确认真实位置，再从 [平台索引](references/source-index.md) 定位当前任务需要的源码。`yss-microservice-components/yss-component-userinfo-starter` 仅是模块路径提示。
 
-## Workflow
+## 工作流
 
 1. 先按已批准平台线读取对应索引；以下当前行为针对 `boot3-java17`，Boot 2 旧工程只按其独立索引做只读分诊和迁移。
-2. Identify whether the task is authenticated current-user lookup, an explicitly trusted gateway adapter, a custom `CurrentUserProvider`, or non-REST/background fallback behavior.
-3. Read `references/source-index.md`, then inspect `CurrentUserProvider`, `SecurityContextCurrentUserProvider`, `TrustedGatewayHeaderCurrentUserProvider`, `AuthUserInfoUtil`, `DmUser`, and `DmUserDetails`.
+2. 区分已认证当前用户、显式受信网关、自定义 `CurrentUserProvider` 与非 REST/后台 fallback。
+3. 按所选任务核验 `CurrentUserProvider`、对应 provider、兼容 facade `AuthUserInfoUtil` 及 `DmUser` / `DmUserDetails`，不无条件读取所有实现。
 4. 默认使用 `SecurityContextCurrentUserProvider`，只消费 Spring Security 已认证且非 anonymous 的 `Authentication`。JWT 的 signature、issuer、audience、expiry 与算法校验必须在资源服务器认证链完成。
 5. `AuthUserInfoUtil` 是由 `CurrentUserProvider` 驱动的兼容 facade；业务代码可继续调用 `userInfo()`、`userName()`、`userCode()` 或 `currentUserJson()`，但不得自行解析 Header、JWT payload 或 Redis 身份缓存。
 6. 只有显式启用 `yss.userinfo.trusted-gateway.enabled` 且配置非空 `trusted-proxies` 时，才启用 `TrustedGatewayHeaderCurrentUserProvider`；它只接受 remote address 在 allow-list 中的请求，并且 SecurityContext 结果优先。
-7. For scheduled/background tasks, an empty provider result causes the compatibility facade to return the distinct `system` fallback; do not represent it as an authenticated system principal.
-
-## Source-Backed Notes
+7. 定时/后台任务的 provider 为空时，兼容 facade 返回独立的 `system` fallback；它不是已认证 system principal。
 
-- `SecurityContextCurrentUserProvider` supports a `UserInfo` principal and an authenticated `OAuth2AuthenticatedPrincipal`; claim mapping happens only after authentication.
-- Trusted gateway header names are `X-Username`, `X-Usercode`, and `X-LoginDisplayName`; the adapter requires a trusted proxy allow-list and a nonblank username.
-- `UserInfoAutoConfiguration` installs SecurityContext as the default and composes the optional gateway provider behind it. A project-supplied `CurrentUserProvider` remains the explicit extension seam.
-- The Boot 3 component does not parse an unverified Bearer payload and does not use Redis as an authentication fallback. Cache behavior is outside this identity provider contract.
+## 平台行为核验
 
-## Checklist
+- `SecurityContextCurrentUserProvider` 支持 `UserInfo` principal 与已认证的 `OAuth2AuthenticatedPrincipal`；claim 映射在认证后进行。
+- 受信网关 Header 为 `X-Username`、`X-Usercode` 和 `X-LoginDisplayName`；适配器要求可信代理 allow-list 与非空 username。
+- `UserInfoAutoConfiguration` 默认使用 SecurityContext，再组合可选网关 provider；工程自定义 `CurrentUserProvider` 是显式扩展 seam。
+- Boot 3 不解析未验证 Bearer payload，不以 Redis 作为认证 fallback；缓存行为不属于此身份 provider 合同。
 
-- Required dependency or starter module is present.
-- Request context exists before relying on servlet headers.
-- Spring Security has authenticated the request before the provider reads the principal.
-- When trusted gateway mode is enabled, at least one proxy address is allow-listed and untrusted remote addresses are rejected.
-- Business code does not duplicate JWT or header parsing logic.
-- SecurityContext/gateway/background precedence and empty-result behavior are covered by tests; `system` fallback is distinguished from an authenticated system user.
-- User info propagation is tested for REST calls and async/background execution separately.
+## 验收
 
-## Do Not
+- 核验所需依赖或 starter 已进入实际工程。
+- 使用 Servlet Header 前核验 request context 存在。
+- Provider 读取 principal 前，Spring Security 已完成请求认证。
+- 受信网关启用时，至少一个代理地址进入 allow-list，且拒绝不可信 remote address。
+- 业务代码不重复 JWT 或 Header 解析。
+- 测试覆盖 SecurityContext/网关/后台的优先级与空结果，区分 `system` fallback 和已认证 system 用户。
+- REST 与异步/后台执行分别验证用户信息传播。
 
-- Do not invent class names or configuration keys without checking the source index.
-- Do not replace component extension points with business-local framework code.
-- Do not treat raw `Authorization` payloads or gateway headers as authenticated identity.
-- Do not broaden the task into unrelated YSS components unless the user asks.
-
-## 平台与源码门禁
+## 修改边界
 
-接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，从批准的 `platform_configuration.component_platform_line` 选择 `source-index.boot2-java8.md` 或 `source-index.boot3-java17.md`，并以 `--skill yss-userinfo --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。
+- 类名和配置 key 先核验当前索引与源码，不凭记忆补造。
+- 使用组件已有扩展 seam，不以业务本地框架代码替换。
+- 原始 `Authorization` payload 与网关 Header 不能直接作为已认证身份。
+- 保持当前组件任务范围；扩展到其他组件须有用户要求或重新路由依据。

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

@@ -5,52 +5,46 @@ description: "接入或排查 YSS Bean Validation、校验消息与校验错误
 
 # yss-validation
 
-Use this skill for YSS 校验组件. Keep implementation grounded in the local project and resolvable YSS backend component source.
+处理 YSS Bean Validation 注解、消息资源和校验失败映射；先区分 DTO 校验与当前不可用的历史 EL/parser 请求。
 
-中文说明：本技能用于 YSS 校验组件。执行时优先读取源码索引，避免凭记忆猜类名、配置项或接入方式。
+## 平台与源码门禁
 
-## Source Index First
+接入、修改、代码生成或提供精确类名/配置前，必须读取并执行 [共享平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，以 `--skill yss-validation` 校验批准的平台线及匹配源码根。缺失、错配或漂移返回 `blocked`；不跨代回退，不在业务实现中升级、降级或替换组件。只读分诊可继续，但须标注未完成源码核验，不能据此宣称跨 Boot/JDK 兼容。
 
-- Backend source location is environment-specific; resolve it with `yss-skill-source-index-refresh/references/source-location.md`.
-- Generated index: `references/source-index.md`
-- Component path hints: `yss-microservice-components/yss-component-validation-jsr303`
+## 源码定位
 
-Read `references/source-index.md` as a path-hint index whenever the task depends on exact modules, annotations, auto configuration, properties, controllers, clients, repositories, DTOs, handlers, or troubleshooting.
+按 [源码定位策略](../yss-skill-source-index-refresh/references/source-location.md) 确认真实位置，再从 [平台索引](references/source-index.md) 定位当前任务需要的源码。`yss-microservice-components/yss-component-validation-jsr303` 仅是模块路径提示。
 
-## Workflow
+## 工作流
 
-1. Identify whether the task is JSR-303 annotation validation or an expression/EL parser request.
-2. Select the approved platform index and inspect the actual POM, validation message resources, consuming Controller annotations and matching exception Advice. The current module README is empty; do not treat reading it as prerequisite evidence.
+1. 区分 JSR-303 注解校验与表达式/EL parser 请求。
+2. 从批准平台索引核验实际 POM、校验消息资源、消费 Controller 注解及匹配的异常 Advice。当前模块 README 为空，不作为前置证据。
 3. 当前组件仓不存在历史 `yss-component-validation-engine-parent`；表达式、LiteFlow EL 或 `ExpressParserFactory` 请求返回 `blocked`，先确认真实组件来源和生命周期影响，不以旧索引或通用知识生成实现。
-4. Keep validation failures mapped to the service/API error contract used by the local project.
+4. 校验失败映射保持当前工程的 service/API 错误合同。
 5. 消费工程基线选择 javax/jakarta，不自行升级 Java/Boot。MVC 输入校验放在 server/client，业务不变量由 service/core 验证；不生成 DDD Domain。HTTP 失败形态由 server 的合同测试验证。
 
-## Capability Split
+## 能力边界
 
-- `validation-jsr303`: currently a dependency/message-resource aggregation module; it has no local Validator, Advice, or auto-configuration Java implementation.
+- `validation-jsr303` 当前聚合依赖与消息资源，没有本地 Validator、Advice 或自动配置 Java 实现。
 - 历史 `validation-el-parser` / `ExpressParserFactory`：当前源码根不存在，状态为 `blocked`，不得作为可用 capability。
 
-## Troubleshooting Notes
-
-- If an EL/parser capability is requested, stop and resolve its actual repository/module instead of assuming the removed path.
-- If validation annotations do not fire, check controller/service validation annotations and Spring validation starter wiring before editing parser code.
-- The component README is empty; use the POM, message resources, Controller annotations, and `GlobalExceptionAdvice` as current evidence.
-- If behavior differs between expression validation and DTO validation, route the problem to the correct submodule first.
+## 排障
 
-## Checklist
+- EL/parser 请求停止实施并确认真实仓库/模块，不假设已移除路径仍存在。
+- 注解未生效时先检查 Controller/service 校验注解和 Spring validation starter 装配，不先改 parser 代码。
+- 当前证据使用 POM、消息资源、Controller 注解和 `GlobalExceptionAdvice`。
+- 表达式校验与 DTO 校验行为不一致时先确认对应模块，再路由问题。
 
-- Required dependency or starter module is present.
-- JSR-303 and unavailable expression-validation requests are not mixed in the same fix.
-- No class, parser or configuration is attributed to the absent historical module.
-- Validation errors preserve readable messages for Chinese business users.
-- Existing project conventions are reused before adding new wrappers.
+## 验收
 
-## Do Not
+- 核验所需依赖或 starter 已进入实际工程。
+- JSR-303 与不可用的表达式校验不混入同一整改。
+- 不将类、parser 或配置归给不存在的历史模块。
+- 校验错误保留中文业务用户可理解的消息。
+- 新增包装前先复用工程既有约定。
 
-- Do not invent class names or configuration keys without checking the source index.
-- Do not replace component extension points with business-local framework code.
-- Do not broaden the task into unrelated YSS components unless the user asks.
-
-## 平台与源码门禁
+## 修改边界
 
-接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，从批准的 `platform_configuration.component_platform_line` 选择 `source-index.boot2-java8.md` 或 `source-index.boot3-java17.md`，并以 `--skill yss-validation --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。
+- 类名和配置 key 先核验当前索引与源码，不凭记忆补造。
+- 使用组件已有扩展 seam，不以业务本地框架代码替换。
+- 保持当前组件任务范围；扩展到其他组件须有用户要求或重新路由依据。