create-yss-spec 3.5.6 → 3.5.8

package/template/.cursor/skills/yss-formily-schema-generator/references/workflow.md

@@ -1,160 +1,41 @@
-# YssFormily Schema Conversion Workflow
+# YFormily Schema 转换工作流
 
-This reference is for converting text, images, and Figma designs into YssFormily artifacts.
+从文字、图片或 Figma 转换表单时，按当前输入读取相关部分。先由 [YFormily 场景路由](../../yss-formily/SKILL.md)选择必要专项；精确 API、三层布局、提交和错误处理仍由已安装的 `formily-foundation` 决定，联动、详情与分步由实际命中的原专项决定。
 
-## 1. Normalize the request
+公开技能包提供本工作流和所链接的公共路由、组件资料，不附带 `formily-foundation`、`formily-linkage-effects`、`formily-mode-slot-detail` 或 `formily-step-flow`。本地已安装时，原专项仍是对应规则的唯一所有者；公共路由和部分 Demo 不替代专项规范。必要专项缺失或不可读时，停止受影响的生产 schema / 渲染实现，报告缺失 Skill 与来源；从消费工程已登记的技能来源恢复，核验版本与项目基线一致并重新读取后再继续。
 
-Classify the target form first:
+## 确认用途与字段模型
 
-| Form type | Signals |
-| --- | --- |
-| 查询表单 | 筛选、搜索、重置、查询、导出 |
-| 新增表单 | 新建、创建、录入、保存 |
-| 编辑表单 | 编辑、更新、修改 |
-| 详情表单 | 查看、详情、只读、描述列表 |
-| 复合表单 | 同页同时支持新增/编辑/查看 |
+先确认目标是查询、新增、编辑、详情还是复合表单，以及输出是 schema、schema + 渲染示例，还是 schema + model + scope/effects 计划。
 
-Then decide the expected output:
+| 字段信息 | 要确认的含义 |
+|---|---|
+| key / title / type | 稳定业务字段名、显示标签与业务数据类型 |
+| component / required | 控件和已确认的必填规则 |
+| group / span | 分组位置与布局宽度 |
+| enum source / linkage | 静态或远程来源、依赖及影响的字段 |
+| custom render | 编辑 Slot 或 detail slot 的需要 |
 
-- schema only
-- schema + render snippet
-- schema + data model + scope/effects plan
+没有显式 key 时建议稳定业务名称，不使用 `input1`、`selectA`、`fieldLeft`。建议不替代冻结 DTO 和统一业务词汇。
 
-## 2. Extract a field table
+## 控件、分组与跨度
 
-Before writing schema, create a mental table with:
-
-| Item | Meaning |
-| --- | --- |
-| key | stable field name |
-| title | display label |
-| type | business data type |
-| component | YssFormily component |
-| required | whether mandatory |
-| group | section placement |
-| span | layout width |
-| enum source | static or remote |
-| linkage | depends on or affects other fields |
-| custom render | slot/detail slot needed or not |
-
-If a field key is not explicit, generate a stable domain name.
-Avoid UI-only names such as `input1`, `selectA`, `fieldLeft`.
-
-## 3. Component mapping heuristics
-
-Use these defaults:
-
-| Input clue | Preferred YssFormily component |
-| --- | --- |
-| 单行文本 | `Input` |
-| 多行说明 | `Input.TextArea` |
-| 单选下拉 | `Select` |
-| 单选按钮 | `Radio.Group` |
+| 输入线索 | 默认建议 |
+|---|---|
+| 单行 / 多行文本 | `Input` / `Input.TextArea` |
+| 单选下拉 / 单选按钮 | `Select` / `Radio.Group` |
 | 开关 | `Switch` |
-| 日期 | `DatePicker` |
-| 日期区间 | `DatePicker.RangePicker` |
+| 日期 / 日期区间 | `DatePicker` / `DatePicker.RangePicker` |
 | 数值 | `InputNumber` |
-| 多选标签 | `Select` with multiple mode |
-| 文件上传 | `Upload` |
+| 多选标签 | `Select` 多选模式 |
+| 上传 | `Upload` |
 | 可重复行 | `ArrayItems` |
 
-If the UI is clearly custom:
-
-- use `Slot` for edit mode
-- use `detail-*` slot for detail mode
-
-Typical custom cases:
-
-- SQL editor
-- code editor
-- rich text
-- complex helper panel
-- embedded table or tree selector
-
-## 4. Layout mapping heuristics
-
-Convert visual grouping to YssFormily structure:
-
-- page-level layout -> `FormLayout`
-- grid rows and columns -> `FormGrid`
-- section title -> `GroupHeader`
-- footer actions -> `AutoButtonGroup`
-
-Use `gridSpan` when:
-
-- field is visually full width
-- long text area spans across columns
-- custom editor needs horizontal space
-
-Conservative defaults:
-
-- ordinary field: `gridSpan: 1`
-- medium-wide field: `gridSpan: 2`
-- editor-like block: `gridSpan: 3` if page is wide enough
-
-## 5. Validation extraction
-
-Confidence levels:
-
-- high confidence:
-  required star, obvious numeric/date constraints, explicit helper text
-- medium confidence:
-  common business conventions such as name required, code length hint
-- low confidence:
-  hidden uniqueness checks, server-side validation, cross-form constraints
-
-Only encode low-confidence validation if the user explicitly described it.
-
-## 6. Linkage extraction
-
-Map visible interactions into one of these:
-
-| Situation | Mechanism |
-| --- | --- |
-| 简单显隐 | `x-visible` |
-| 简单禁用 | `x-disabled` |
-| 单字段依赖更新 | `x-reactions` |
-| 调接口更新选项 | `scope` handler |
-| 多字段协同或提交兜底 | `effects` |
-
-Examples:
+SQL、代码、富文本、复杂辅助区或嵌入表格 / 树选择器等自定义输入，编辑态用 `Slot`，查看态用 `detail-*` 插槽。实际是否可用仍核验目标版本与当前 schema 注册组件。
 
-- “选择数据源类型后才显示 JDBC 配置” -> `x-visible`
-- “切换开关后禁用描述字段” -> `x-disabled`
-- “选择省份后重置城市并更新选项” -> `x-reactions`
-- “输入编码后查重” -> `scope` or async validator
-- “提交失败统一 toast” -> `effects`
+页面布局映射为 `FormLayout`、栅格为 `FormGrid`、分组标题为 `GroupHeader`。纯表单底部动作可用 `AutoButtonGroup`；业务列表查询区按下一节单独处理。横向表单显式设置 `labelWidth` 与 `labelAlign: 'right'`，栅格保持响应式。
 
-## 7. Output template
-
-Preferred answer skeleton:
-
-```md
-理解
-
-假设
-
-字段模型
-
-```ts
-// schema
-...
-```
-
-```ts
-// initial model shape
-...
-```
-
-```vue
-<!-- optional render snippet -->
-...
-```
-```
-
-## 8. Schema skeleton
-
-Use this as the default starting point:
+普通字段可建议 `gridSpan: 1`，较宽字段为 `2`，宽屏编辑器可为 `3`；长文本、满宽字段和自定义编辑器的跨度必须与实际栅格列数及窄屏行为匹配，不能只复制示例数字。
 
 ```ts
 const schema: ISchema = {
@@ -163,14 +44,12 @@ const schema: ISchema = {
     layout: {
       type: 'void',
       'x-component': 'FormLayout',
-      'x-component-props': {
-        layout: 'horizontal',
-        labelWidth: 120,
-      },
+      'x-component-props': { layout: 'horizontal', labelWidth: 120, labelAlign: 'right' },
       properties: {
         grid: {
           type: 'void',
           'x-component': 'FormGrid',
+          'x-component-props': { maxColumns: 2, minColumns: 1, minWidth: 320 },
           properties: {},
         },
       },
@@ -179,62 +58,39 @@ const schema: ISchema = {
 };
 ```
 
-## 9. Query form special handling
-
-When the form is clearly a search form:
-
-- keep fields compact
-- avoid excessive required rules
-- place actions in `AutoButtonGroup`
-- include `Submit` and `Reset`
-- prefer light linkage over complex `effects`
+示例数字仅为起点，不决定目标页面的字段、列数或业务规则。
 
-Typical query output includes:
+## 查询与详情的分支
 
-- schema
-- initial filter model
-- submit/reset handlers through `scope`
+业务查询表单保持紧凑，保留已确认的必填规则，不因常见习惯新增必填。YFormily 渲染字段，外部 YButton 查询 / 重置由 Hook 的 `handleSearch/handleReset` 维护同一参数源、回第一页并执行请求。动作区按 [业务页面查询区规则](../../yss-ui-business-page-generation/SKILL.md)核对，基础表单约束仍由已加载的 `formily-foundation` 决定；不将 schema 内 `AutoButtonGroup + Submit/Reset` 当作 CRUD 查询区默认方案。
 
-## 10. Detail form special handling
+查询输出包含 schema、初始筛选 model 和查询 / 重置处理计划。单纯 Formily 表单提交仍可按基础规范使用 schema 内按钮组。
 
-If the target is read-only or mixed add/edit/detail:
+详情或新增 / 编辑 / 查看复合表单确认 mode，不只生成可编辑控件。默认描述列表足够时不另造渲染；富格式、数组标签、代码或富文本查看器需要自定义 detail slot 时，按 [模式与插槽路由](../../yss-formily/SKILL.md)加载已安装的 `formily-mode-slot-detail`，由原专项确定规范。
 
-- plan `mode`
-- check whether detail mode needs custom slots
-- do not generate editable controls only
-- leverage default descriptions rendering when enough
+## 校验与联动的依据
 
-Use custom detail slots only when:
+| 线索 | 如何处理 |
+|---|---|
+| 明确必填标记、数值 / 日期约束或 helper 文本 | 对照需求确认含义后编码 |
+| 常见业务习惯、名称必填或长度暗示 | 保留建议与待确认项，不仅凭习惯把规则写入 schema |
+| 隐藏唯一性、服务端或跨表校验 | 只有用户 / 权威需求已明确描述时编码 |
 
-- value needs rich formatting
-- arrays should render tags
-- code or rich text should render in a viewer
-
-## 11. Figma-specific notes
-
-When converting from Figma:
-
-- extract semantic labels, not layer IDs
-- ignore purely decorative layers
-- map helper text and required marks into schema rules
-- convert footer buttons into action area, not ordinary fields
-- infer full-width editors from large framed regions
-
-Do not preserve design-only names such as:
+| 当前任务 | 首选机制 |
+|---|---|
+| 简单显隐 / 禁用 | `x-visible` / `x-disabled` 表达式 |
+| 单字段依赖更新 | `x-reactions` |
+| 调接口更新选项或跨字段事件 | `scope` |
+| 表单级多字段协同 | `effects` |
 
-- `Frame 123`
-- `Input / Default`
-- `Group 14`
+例如数据源类型控制 JDBC 配置显示、开关控制字段禁用、省份控制城市选项与失效旧值，都需要确认字段路径和实际依赖。编码查重仅在已确认需求存在时实现。客户端提交校验失败反馈使用 `onFormSubmitValidateFailed`；API reject 仍由 mutator 统一提示，不能把“提交失败统一 toast”机械映射到通用 effects 失败回调。复杂或异步联动按 [联动场景路由](../../yss-formily/SKILL.md)加载已安装的 `formily-linkage-effects`，由原专项处理初始化、合法回填、竞态和卸载。
 
-Translate them into domain names and stable field keys.
+## Figma 与图片检查
 
-## 12. Image-specific notes
+Figma 读取语义标签，不沿用 `Frame 123`、`Input / Default`、`Group 14` 等设计图层名；忽略纯装饰层，把 helper 与必填提示作为需核对的规则线索。底部按钮转成动作区，宽框编辑器结合实际空间安排满宽。
 
-When converting from screenshots:
+截图先区分 placeholder 与标签，识别 Tab / 分段控制是否意味着条件区，确认大框是自定义编辑器还是 textarea。图像理解是近似的，低置信度时输出可审阅骨架并记录不确定项，不制造精确业务规则。
 
-- distinguish placeholder text from actual label text
-- watch for tabs or segmented controls that imply conditional sections
-- identify whether a box is a custom editor or just a textarea
-- keep uncertain parts in assumptions
+## 输出与自检
 
-If confidence is low, generate a clean schema baseline instead of fake precision.
+按“简短理解 → 假设 → 字段模型 → schema → 按需 model / 渲染示例”组织。JSON / TS 标识保持原样，假设与已确认规则分开。检查字段稳定、分组有业务含义、必填 / 可选和只读 / 联动与输入一致，所需 API 与插槽来自当前版本。只剩真正阻断正确性的未决问题时交回所有者；文档输出不改变原合同状态或批准。

package/template/.cursor/skills/yss-frontend-scaffold-generator/SKILL.md

@@ -7,7 +7,7 @@ description: Use when creating a new YSS frontend micro-application from the sta
 
 用于从标准 YSS 前端模板创建 0-1 前端微应用工程。它只在阶段 5 的 `work-unit.implementation-repository-preparation` 中消费生命周期批准、持久化且当前的 Project Scaffold Contract schema v4，执行 `controlled-generation`；不生成业务页面。
 
-## Template Source
+## 模板来源
 
 默认使用随 Skill 分发的 `assets/data-quality-v1/`，从 Data Quality 抽取工作区、主题与微应用模式，重建为通用空骨架。来源、差异、支持范围见 `references/data-quality-baseline.md`；`references/data-quality-v1.manifest.json` 是文件白名单与 SHA-256 依据。
 
@@ -17,22 +17,26 @@ description: Use when creating a new YSS frontend micro-application from the sta
 
 兼容已有 `{ repository, commit }` 合同：只有明确选择外部 Git 模板时传 `--template-checkout` 并核验 origin 与精确 40 位 commit；不再默认从私网浮动分支获取模板。
 
-## Inputs
+## 必要输入
 
 - `app_name`：应用名。
 - `microapp_name`：微应用注册名。
 - `base_route`：基础路由。
 - Project Scaffold Contract schema v4：包含用户确认的仓库 scope、目标路径、`init_git`、模板 manifest 摘要或 Git commit、应用参数、允许写路径和验证命令。
 - OpenAPI Freeze 记录：有 API 影响时提供已批准的冻结 YAML 版本和引用；无 API 影响时提供带原因的 `not-applicable`。
-- OpenAPI JSON 派生记录：`docs/.scratch/<feature>/api/<feature>-json-export.md`，包含 YAML / JSON SHA-256、Redocly CLI 版本和 lockfile 引用。
-- 冻结 JSON 产物：`docs/.scratch/<feature>/api/<feature>.json`；这是唯一允许交给既有前端代码生成流程的上游产物。
+- 有 API 影响时提供 OpenAPI JSON 派生记录：`docs/.scratch/<feature>/api/<feature>-json-export.md`，包含 YAML / JSON SHA-256、Redocly CLI 版本和 lockfile 引用。
+- 有 API 影响时提供冻结 JSON 产物：`docs/.scratch/<feature>/api/<feature>.json`；这是唯一允许交给既有前端代码生成流程的上游产物。无 API 影响时沿用带原因的 `not-applicable`，不生成占位 JSON 或 API client。
 - `target_git_url` 或 `output_dir`：目标实现仓库或本地输出目录。
 - `package_manager`：默认 pnpm。
 - `init_git`：是否初始化 Git；默认必须用户明确确认。
 
-## Workflow
+## 执行与停止条件
 
-采用专职前端 profile 或显式 `frontend_delivery` 绑定时，先按 `.template-spec/process/frontend-backend-delivery.md` 实际核验战略与后端联合交付。缺任一输入只能诊断和回交；输入通过后准备计划/合同，正式实现、生成和恢复仍须当前批准的 Slice Contract 冻结接收摘要。接口或部署版本漂移时重新接收，不复用旧成功输出。
+采用专职前端 profile 或显式 `frontend_delivery` 绑定时：
+
+- 按 `.template-spec/process/frontend-backend-delivery.md` 核验战略与后端联合交付；缺任一输入只能诊断和回交。
+- 输入通过后准备计划 / 合同；正式实现、生成和恢复仍须当前批准的 Slice Contract 冻结接收摘要。
+- 接口或部署版本漂移时重新接收，不复用旧成功输出。
 
 1. 确认当前任务已经通过 Harness 入口分诊、逐项目脚手架决定已由真实用户确认，且 schema v4 合同已由生命周期批准、持久化并保持当前。
 2. 确认目标是外部实现仓库；只有用户明确选择时才输出到 Harness 仓库的 `apps/frontend/<project>/`。`apps/frontend/` 只能作为项目容器，`app/frontend/`、`app/backend/` 及其子路径禁止作为输出位置。`git-submodule` 只能在已初始化且附加分支的子仓工作树生成；空 gitlink、detached HEAD、`--force` 覆盖挂载点不得当成普通目录。
@@ -44,7 +48,7 @@ description: Use when creating a new YSS frontend micro-application from the sta
 8. 企业 registry / 认证由目标环境用户级 npm 配置提供，禁止复制来源 `.npmrc` 或 token。实际执行并记录 `pnpm install --frozen-lockfile`、`pnpm lint:check`、`pnpm type-check`、`pnpm build`、`pnpm build:standalone` 的退出码和日志；缺失脚本只能由批准的工程基线提供替代命令。任何必需命令失败都阻断。
 9. 按 `.template-spec/templates/implementation-repo-registry-template.md` 回写前端实现仓库登记。
 
-## Expected Template Shape
+## 生成目录形态
 
 ```text
 DESIGN.md
@@ -60,7 +64,7 @@ package.json
 packages/package.json
 ```
 
-## Boundaries
+## 授权与技术边界
 
 - 不直接创建远端 Git 项目，除非用户明确要求。
 - 不保留模板 `.git` 或模板 remote；不在未获确认时执行 `git init`。
@@ -73,13 +77,13 @@ packages/package.json
 - 不把模板示例页面当作业务功能交付。
 - 生成后仍需使用 `yss-ui`、`yss-ui-business-page-generation`、`yss-api-integration` 以及实际命中的表格、树、Formily 等专项 skill 实现业务页面。
 
-## Output
+## 输出与证据
 
 - 前端工程生成位置或目标仓库信息。
 - 模板 baseline / manifest 摘要，或 Git repository / commit 证据。
 - 替换参数清单。
 - install / lint / type-check / build 命令，以及目标前端项目既有的手动客户端生成命令（如有）。
-- OpenAPI Freeze 记录、OpenAPI JSON 派生记录、JSON SHA-256 和 `openapi/openapi.json` 物化证据。
+- 有 API 影响时提供 OpenAPI Freeze 记录、OpenAPI JSON 派生记录、JSON SHA-256 和 `openapi/openapi.json` 物化证据；无 API 影响时提供带原因的 `not-applicable`。
 - Harness 实现仓库登记草案。
 - `.yss/scaffold-generation.json` Manifest v4 与 `scaffold-verification.json`。
 - 未覆盖项和 `TODO-HUMAN-REVIEW`。

package/template/.cursor/skills/yss-implementation-contract-compiler/SKILL.md

@@ -11,11 +11,7 @@ Slice v3 的当前执行结果须按 `references/yss-skill-execution-result.md`
 
 阶段 7 的实现合同编译器。它把已批准的生命周期资产、垂直切片、capability 和窄 Recipe 编译为 `Slice Implementation Contract` v3 草案；不批准合同、不写业务代码、不设置 `ready-for-agent`。
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
-
-## 文档写作
-
-撰写实现合同的解释正文和切片交接说明前，读取 `.template-spec/process/document-writing.md` 的共用写法及工程契约 / Ticket 指引；不改变结构化合同、批准状态或就绪条件。
+撰写实现合同解释正文或切片交接说明时，按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md` 的共用写法及工程契约 / Ticket 指引。作用域仅限当前产物；派发时传递条件及引用，不改变结构化合同、批准状态或就绪条件。
 
 ## 输入
 
@@ -41,7 +37,7 @@ Slice v3 的当前执行结果须按 `references/yss-skill-execution-result.md`
 采用专职前端 profile 或显式 `frontend_delivery` 绑定时，先按 `.template-spec/process/frontend-backend-delivery.md` 实际核验战略与后端联合交付。缺任一输入只能诊断和回交；输入通过后准备计划/合同，正式实现、生成和恢复仍须当前批准的 Slice Contract 冻结接收摘要。接口或部署版本漂移时重新接收，不复用旧成功输出。
 
 - 编译器不得输出 `approved`、`ready-for-agent` 或 `completed`。
-- Registry 和编译规则保持 schema v2；新 Slice 使用 v3，v2 按原规则读取和显式迁移。schema v1 一律拒绝，不自动升级，不提供旧技能名兼容。
+- Registry 使用其权威 schema v3，编译规则保持 schema v2；新 Slice 使用 v3，旧 Slice v2 按原规则读取和显式迁移。已停止支持的 schema 一律拒绝，不自动升级，不提供未登记的旧技能名兼容。
 - `required_capabilities` 与 `required_skills` 必须同时冻结；Registry 或编译器摘要变化后合同立即 `stale`，重新编译后仍须交生命周期重新批准。
 - UI 影响按来源分支核验：新设计保持正式原型确认与 Visual Baseline；无 UI 改动才允许 `existing-ui-baseline` v1，并须当前真实基线确认及 `case_id`。任一来源缺少当前批准或摘要绑定时，不得路由页面实现。模型必须先读 manifest 与语义引用，再查看对应 PNG；禁止目录 glob 和图片独立猜义。
 - Repository/数据模型影响缺少数据架构时，不得路由持久化实现。

package/template/.cursor/skills/yss-implementation-contract-compiler/references/yss-skill-execution-result.md

@@ -4,9 +4,13 @@
 
 后端结果顶层带与当前 resolution 完全一致的 `architecture_identity`；每条验证记录还须有整数 `exit_code`。身份缺失、Profile 未 supported、验证非零或没有执行时间均不得 accepted。
 
+以下为当前 Slice v3 的填写结构。后端身份复制当前 resolution；`project_root`、`dependency_roots` 仅按跨仓及来源解析合同填写。历史 Slice v2 使用末节所述兼容路径，不能把此示例当作自动迁移指令。
+
 ```yaml
 execution_result:
   schema_version: 2
+  evidence_binding_version: 1
+  architecture_identity: # 后端必须与当前 resolution 完全一致；其他工作单元按原合同
   skill:
   slice_id:
   work_unit_id:
@@ -15,6 +19,7 @@ execution_result:
     contract_ref:
     contract_id:
     contract_version:
+    contract_digest: # 已批准 Slice 文件原始字节 SHA-256
     registry_digest:
     compiler_contract_digest:
     component_bindings_digest: # 合同含 component_bindings 时必填
@@ -25,10 +30,19 @@ execution_result:
       contract_area: common | frontend | backend | contract | cross_repo
   evidence_files:
     - path:
+      digest: # 证据文件原始字节 SHA-256
       evidence_type: code | test | generated | review | verification
       behavior_ref:
+  source_bindings:
+    - path:
+      digest: # 实际消费的来源原始字节 SHA-256；删除使用 deleted: true, digest: null
   verification_results:
-    - command:
+    - verification_id:
+      acceptance_refs: [] # 对应验证项的完整稳定验收 ID
+      evidence_refs: [] # 覆盖全部关联验收及预期文件
+      command:
+      cwd:
+      exit_code: # 实际整数退出码
       result:
       executed_at:
   constraint_results:

package/template/.cursor/skills/yss-layered-mvc-scaffold-generator/SKILL.md

@@ -43,7 +43,7 @@ description: 在生命周期已批准的脚手架合同下生成通用 YSS 分
 
 ## 执行
 
-优先使用一键入口：
+优先使用一键入口。以下命令从 Skill 根目录执行；坐标、平台及合同参数消费当前批准输入，示例不授予生成或覆盖权限：
 
 ```bash
 node scripts/generate_and_verify_scaffold.mjs \

package/template/.cursor/skills/yss-mybatis/SKILL.md

@@ -7,6 +7,10 @@ description: 用于 YSS MyBatis / MyBatis-Plus 组件能力核验、接入决策
 
 本 Skill 只维护 `yss-component-persistence` 的组件能力、选择条件和排障顺序。PO、Repository、Convertor、Gateway/Query Adapter 的结构与生成边界由 `yss-repository` 负责。
 
+## 平台与源码门禁
+
+接入、修改、代码生成或提供精确类名/配置前，必须读取并执行 [共享平台与源码门禁](../yss-skill-source-index-refresh/references/backend-component-platform-compatibility.md)，以 `--skill yss-mybatis` 校验批准的平台线及匹配源码根。缺失、错配或漂移返回 `blocked`；不跨代回退，不在业务实现中升级、降级或替换组件。只读分诊可继续，但须标注未完成源码核验，不能据此宣称跨 Boot/JDK 兼容。
+
 ## 入口与前置
 
 1. 读取批准且当前的 `architecture_identity`、`persistence_profile`、实现仓登记和 Slice Implementation Contract。没有合同的故障诊断可以继续，但不得据此生成或改变架构。
@@ -74,10 +78,6 @@ description: 用于 YSS MyBatis / MyBatis-Plus 组件能力核验、接入决策
 - 使用项目根 `./mvnw ...` 记录实际命令、退出码和时间；H2 只证明本地/测试行为，不证明生产方言。
 - 按 [YSS Skill Execution Result v2](../yss-implementation-contract-compiler/references/yss-skill-execution-result.md) 返回证据、`seam_deferred`、`deviations`、`new_impacts`、`drift` 和 `violation`。
 
-## 平台与源码门禁
-
-接入、修改、代码生成或给出精确类名/配置前，读取 [后端组件平台与源码门禁](../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-mybatis --platform-line <line> --source-root <matching-root>` 运行统一 freshness 校验。平台线与源码根不匹配、组件 tree 不一致、组件子树 dirty、索引缺少平台信号，或 Manifest / 组件 GAV 缺少 verified 兼容证据时返回 `blocked`；不得回退另一代索引，也不在业务实现中升级、降级或替换 YSS 组件。既有工程只读分诊可继续，但不得据此宣称跨 Boot/JDK 兼容。
-
 ## 持久化选择记录
 
 在已有数据合同 / persistence_strategy 中记录：实际 Mapper 基类、组件源码与平台绑定、分页唯一责任者、主键与审计填充，以及命中批量时的 SQL 入口、分批大小和方言证据。`BaseMapper` 与组件扩展基类按所需能力选择，不因命名不同判违规；依赖存在和循环 insert 均不证明批量能力。未命中的能力不强制生成。

package/template/.cursor/skills/yss-openapi-draft-review/SKILL.md

@@ -9,6 +9,8 @@ description: "审查 YSS OpenAPI Draft 的需求覆盖、页面动作、响应
 
 Use this skill after OpenAPI Draft creation and before Engineering Baseline / YSS DDD Review. It is a fail-closed contract review skill for design-time OpenAPI files under `docs/.scratch/<feature>/api/`; it does not bundle JSON or generate Orval clients.
 
+先辨认当前批准协议。普通采用 YSS wrapper 的 HTTP/JSON 响应消费 DTO wire profile；下载、流式和第三方回调按批准协议审查媒体类型、状态、Header、错误及权限边界，不强套 wrapper。例外须有契约依据且仍通过本技能的结构和语义审查。
+
 ## Required Inputs
 
 - OpenAPI Draft under `docs/.scratch/<feature>/api/<feature>.yaml`，作为唯一权威的单一 OAS 3.1 YAML document；生命周期元数据和 Freeze 决策位于相邻 Markdown 记录。
@@ -26,7 +28,7 @@ Use this skill after OpenAPI Draft creation and before Engineering Baseline / YS
 
 - Automated checks own YAML single-document syntax, `$ref` resolution, path-parameter consistency, OpenAPI lint, and stable machine-checkable style rules.
 - `scripts/verify-openapi-draft-validation-record` owns validation-record shape, current-byte SHA binding, locked toolchain evidence and deterministic structural rechecks. It does not decide whether a business property correctly implements the Spec.
-- `scripts/verify-yss-dto-openapi-profile` owns the reusable DTO mapping invariants; the review still checks each endpoint's concrete schema, wrapper extension and evidence.
+- `scripts/verify-yss-dto-openapi-profile` owns the reusable DTO mapping invariants; the review checks every endpoint's approved protocol, concrete schema and evidence, including the wrapper extension when the endpoint uses the YSS wrapper.
 - Human or independent semantic review owns P0 traceability, page-action coverage, error behavior, concurrency/idempotency, scope downgrades, contract-test seams, and any explicitly specified authentication or authorization behavior.
 - Fresh passing automation evidence may be referenced by the semantic review; copying the same findings into a second checklist is unnecessary.
 - Re-run structural automation only when the Draft, ruleset, or referenced schema changes.
@@ -41,9 +43,9 @@ Block if any of these are true:
 - Multiple lifecycle operations reuse one schema even though requiredness or omission semantics differ and no explicit conditional contract resolves the difference.
 - A UI action has no endpoint/non-goal mapping.
 - A configurable rule or gate lacks a source, owner, fixed/default decision, or API representation.
-- Pagination does not align with the `PageResult` profile or documented exception, or exposes `offset` / `needTotalCount` / `tempTotalCount` as client input.
-- A response omits `x-yss-response-wrapper`, uses the compatibility `com.yss.cloud.dto.response` package for a new contract, writes Java generic notation as an OAS schema, or fails `YssResultMeta` + `allOf` + concrete `data` mapping.
-- `code` is modeled as arbitrary object, `dataType` loses explicit nullability, or computed fields such as `totalPages` lack target wire evidence.
+- Pagination does not align with the `PageResult` profile or documented exception, or an endpoint using the YSS pagination protocol exposes `offset` / `needTotalCount` / `tempTotalCount` as client input.
+- An ordinary response using the YSS wrapper omits `x-yss-response-wrapper`, uses the compatibility `com.yss.cloud.dto.response` package for a new wrapper contract, writes Java generic notation as an OAS schema, or fails `YssResultMeta` + `allOf` + concrete `data` mapping.
+- In a YSS wrapper, `code` is modeled as arbitrary object or `dataType` loses explicit nullability; or computed fields such as `totalPages` lack target wire evidence.
 - An in-scope behavior lacks a contract-test seam. Select import, mapping coverage, validation, review, publish, export or optimistic-locking seams only when the Spec/API actually includes that behavior; record a reasoned not-applicable for absent operations. A read-only query does not acquire write/import/publish requirements.
 - YAML contains lifecycle frontmatter / root metadata, or the proposed JSON client input is not explicitly deferred until Freeze and governance export.
 

package/template/.cursor/skills/yss-openapi-draft-review/references/review-output.md

@@ -4,6 +4,8 @@
 
 ## Output Contract
 
+Wrapper 与分页检查按实际协议填写：采用 YSS 协议时记录 profile 符合性；下载、流式、回调或已批准分页例外记录协议依据、适用性和实际检查，不生成空 wrapper 或用不适用跳过审查证据。
+
 ```markdown
 ### Review Result
 <Approved / Blocked>

package/template/.cursor/skills/yss-openapi-draft-review/references/semantic-review.md

@@ -9,8 +9,8 @@
 3. Check page action coverage: every action has `actionKey`, endpoint or explicit non-goal, state transition, idempotency/concurrency rule, and error codes. When the Spec explicitly changes authentication or authorization behavior, trace that behavior through the same matrix.
 4. Check object lifecycle coverage: manage/maintain/configure/create/update/archive/retry/cancel/publish/export/create-draft semantics have endpoints or explicit scope downgrades.
    When create/update or other lifecycle operations share one schema, verify that omission and requiredness semantics match for every operation; otherwise require split schemas or an explicit conditional contract. For credentials, distinguish create, update, masked readback, omit-to-preserve and explicit-clear behavior instead of imposing a universal required rule.
-5. Check YSS API baseline: REST shape, `x-yss-response-wrapper` values `SingleResult|MultiResult|PageResult`, `YssResultMeta` plus `allOf` concrete schemas, and stable DTO/schema names. The Java generic notation is a review shorthand only; it must not appear as an OpenAPI type or `$ref`.
-6. Check DTO wire shape against the profile: `success` is boolean, `dataType` is `string|null`, `code` is only `string|integer|null`, list/page `data` is an array, and single `data` points to the endpoint schema with explicit nullability. Check response/request direction separately.
-7. Check pagination input: only `pageIndex/pageSize/orderBy/orderDirection/groupBy` are client fields; `orderDirection` is `ASC|DESC`; `orderBy` / `groupBy` use endpoint whitelists; `offset`, `needTotalCount`, and `tempTotalCount` are negative assertions. `totalPages` is mapper-dependent and cannot enter a shared schema without fresh wire evidence.
+5. Check the approved API protocol: REST shape and stable DTO/schema names; ordinary responses using the YSS wrapper declare `x-yss-response-wrapper` values `SingleResult|MultiResult|PageResult` and `YssResultMeta` plus `allOf` concrete schemas. Download, streaming and third-party callback protocols retain their approved media types, status, headers and error boundaries without forced wrapping. The Java generic notation is a review shorthand only; it must not appear as an OpenAPI type or `$ref`.
+6. For endpoints using the YSS wrapper, check DTO wire shape against the profile: `success` is boolean, `dataType` is `string|null`, `code` is only `string|integer|null`, list/page `data` is an array, and single `data` points to the endpoint schema with explicit nullability. Check response/request direction separately. Other approved protocols retain their own concrete wire shape and evidence.
+7. For endpoints using the YSS pagination protocol, check input against its profile: only `pageIndex/pageSize/orderBy/orderDirection/groupBy` are client fields; `orderDirection` is `ASC|DESC`; `orderBy` / `groupBy` use endpoint whitelists; `offset`, `needTotalCount`, and `tempTotalCount` are negative assertions. Approved pagination exceptions retain their recorded boundary. `totalPages` is mapper-dependent and cannot enter a shared schema without fresh wire evidence.
 8. Check error contracts: field-level errors, model-level errors, disabled reasons, gate failures, and conflict responses. When the Spec explicitly changes authentication or authorization behavior, include its `401` / `403` and resource-filtering semantics here.
 9. Output a persistent review artifact under `docs/.scratch/<feature>/architecture/` or update the existing one.

package/template/.cursor/skills/yss-openapi-governance/SKILL.md

@@ -17,11 +17,9 @@ Spec / 设计输入 → OpenAPI YAML Draft → 审查与 Freeze → JSON 派生
 
 YSS DTO 的可复用 HTTP/JSON 映射由 `.agents/skills/yss-dto/references/openapi-wire-profile.yaml` 单一维护。它描述公开 wire shape，不是 Java 字段或 getter 清单；本 skill 必须消费 profile，不能在治理文档、feature YAML 和 JSON 中各自发明 `SingleResult`、`PageResult` 或 `PageQuery` 字段表。
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+先识别当前批准协议：普通已采用 YSS wrapper 的 HTTP/JSON 接口按 wire profile 检查；下载、流式和第三方回调按批准契约检查媒体类型、状态、Header、错误及权限边界，不强套 wrapper。协议差异须有可读依据，不能以“特殊接口”为由豁免 Draft、审查、Freeze 或验证。
 
-## 文档写作
-
-编写接口说明和契约评审交接正文前，读取 `.template-spec/process/document-writing.md` 的共用写法及工程契约指引；协议标识、schema、冻结状态和验证记录按原合同保存。
+编写接口说明或契约评审交接正文时，按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md` 的共用写法及工程契约指引。作用域仅限当前产物；派发时传递条件及引用，协议标识、schema、冻结状态和验证记录按原合同保存。
 
 ## 边界与职责
 
@@ -29,7 +27,7 @@ YSS DTO 的可复用 HTTP/JSON 映射由 `.agents/skills/yss-dto/references/open
 
 - 基于冻结前的 Spec、产品设计、架构约束创建或更新 `docs/.scratch/<feature>/api/<feature>.yaml`。
 - 保证 YAML 是单一 YAML document、根节点为 `openapi: 3.1.0`，且不把 `pipeline`、`stage`、`status`、`owner` 等生命周期元数据写入 OpenAPI 根节点。
-- 按 `yss-dto` wire profile 校验 `com.yss.cloud.dto.result` canonical 包、`YssResultMeta` 公共字段、具体 wrapper schema、请求 / 响应方向和分页负向字段。
+- 采用 YSS wrapper / 分页协议时，按 `yss-dto` wire profile 校验 `com.yss.cloud.dto.result` canonical 包、`YssResultMeta` 公共字段、具体 wrapper schema、请求 / 响应方向和分页负向字段；其他批准协议记录适用性及实际契约检查。
 - 运行受项目 lockfile 约束的 lint / bundle，检查 `$ref`、operationId、响应包装、错误、分页、幂等和契约测试 seam；只有 Spec 明确改变认证或授权行为时才检查对应契约。
 - 在 `docs/.scratch/<feature>/api/<feature>-validation.yaml` 持久化结构校验记录，并用 `scripts/verify-openapi-draft-validation-record` 复核当前 YAML SHA-256、锁定的 Redocly 版本、实际命令、退出码、执行时间和证据引用。
 - 在 OpenAPI Freeze 后，用锁定的 Redocly CLI 将 YAML bundle 为 JSON，并记录可重现证据。
@@ -61,8 +59,8 @@ YSS DTO 的可复用 HTTP/JSON 映射由 `.agents/skills/yss-dto/references/open
 - P0 操作缺请求、响应、错误、并发 / 幂等规则或可验证 seam；Spec 明确的认证或授权行为没有契约表示。
 - P0 写模型、配置模型或关键交互读模型没有追到 property path、嵌套形状、requiredness、约束、来源和 test seam；跨操作复用 schema 却没有证明省略与必填语义一致。
 - `$ref` 超出允许范围，或转换器版本、lockfile、命令、输入 YAML 无法识别。
-- `scripts/verify-yss-dto-openapi-profile` 失败、profile 版本未记录，或 Draft 未按 profile 建模 `x-yss-response-wrapper`、`YssResultMeta` / `allOf` 和具体 `data` schema。
-- 新契约引入 `com.yss.cloud.dto.response`、把 Java 泛型文字当成 OAS schema、把全局 `code` 放宽为任意 object，或把 `offset` / `needTotalCount` / `tempTotalCount` 作为客户端字段。
+- `scripts/verify-yss-dto-openapi-profile` 失败、profile 版本未记录，或采用 YSS wrapper 的 Draft 响应未按 profile 建模 `x-yss-response-wrapper`、`YssResultMeta` / `allOf` 和具体 `data` schema。
+- 新的 YSS wrapper 契约引入 `com.yss.cloud.dto.response`、把 Java 泛型文字当成 OAS schema、把全局 `code` 放宽为任意 object，或采用 YSS 分页协议的接口把 `offset` / `needTotalCount` / `tempTotalCount` 作为客户端字段。
 - `totalPages`、任何 computed getter 或 Lombok / `@JsonIgnore` 推导字段没有目标 mapper identity、代表性序列化 fixture 和 contract-test / 等价 HTTP 证据。
 - Freeze 记录、YAML SHA-256、JSON SHA-256、JSON 解析 / lint 证据缺失。
 - JSON 被手工编辑，或生成结果试图反向成为 YAML 的权威来源。

package/template/.cursor/skills/yss-openapi-governance/references/governance-output.md

@@ -1,5 +1,7 @@
 ## 输出契约
 
+Wrapper 与分页检查按实际协议填写：采用 YSS 协议时记录 profile 符合性；下载、流式、回调或已批准分页例外记录协议依据、适用性和实际检查，不生成空 wrapper 或用不适用跳过审查证据。
+
 ```markdown
 ### Governance Result
 <Draft / Approved for Freeze / Blocked / JSON Exported>

package/template/.cursor/skills/yss-openapi-governance/references/governance-workflow.md

@@ -15,9 +15,9 @@
    - 从 `.template-spec/api/templates/openapi-draft-validation-record-template.yaml` 创建 `<feature>-validation.yaml`，记录 YAML SHA-256 与 lint 工具链；运行 `scripts/verify-openapi-draft-validation-record --root <project-root> <record>`。自定义解析脚本可以补充诊断，但不能代替锁定的 Redocly lint evidence。
    - 对每个 P0 写模型、配置模型及影响关键交互的读模型建立字段级追踪：`Spec/交互来源 → operationId → request/response schema → property path → 类型与嵌套形状 → create/update requiredness → nullable/default/enum/format → error/test seam`。数组元素使用 `items[].property` 一类稳定 property path。
    - create/update 或其他不同生命周期操作复用同一写 schema 时，逐操作证明 requiredness 与省略语义一致；若不一致，拆分 schema 或明确条件契约。凭据类字段还要说明创建、更新、掩码回显、省略保留与显式清空语义，不能仅凭字段名统一设为必填。
-   - 先运行 `scripts/verify-yss-dto-openapi-profile`，并记录 profile 版本；检查 `/api/v1/` 版本策略（或记录例外）、`x-yss-response-wrapper`、`YssResultMeta` + `allOf` 具体 schema、统一错误结构、分页、幂等 / 乐观锁和契约测试 seam。
-   - 每个响应都必须落成具体 endpoint schema：`SingleResult` 的 `data` 是具体对象或显式 nullable schema，`MultiResult` / `PageResult` 的 `data` 是数组；Java 的 `SingleResult<T>` / `PageResult<T>` 只能作为语义说明，不能直接写成 OAS type 或 `$ref`。
-   - `code` 按 profile 只允许 `string | integer | null`，`dataType` 按 profile 为 `string | null`；`offset`、`needTotalCount`、`tempTotalCount` 不得进入客户端分页输入；`totalPages` 只有目标 HTTP mapper / fixture 证明后才能进入契约。Spec 明确改变认证或授权行为时，把对应 `401` / `403`、资源过滤和错误语义作为普通 API 行为检查。
+   - 先运行 `scripts/verify-yss-dto-openapi-profile`，并记录 profile 版本；检查 `/api/v1/` 版本策略（或记录例外）。普通采用 YSS wrapper 的接口检查 `x-yss-response-wrapper`、`YssResultMeta` + `allOf` 具体 schema；下载、流式和第三方回调检查其批准媒体类型、状态、Header 和错误边界。按实际协议检查分页、幂等 / 乐观锁和契约测试 seam，不强套 wrapper 或豁免证据。
+   - 每个响应按实际协议落成具体 endpoint schema。采用 YSS wrapper 时，`SingleResult` 的 `data` 是具体对象或显式 nullable schema，`MultiResult` / `PageResult` 的 `data` 是数组；Java 的 `SingleResult<T>` / `PageResult<T>` 只能作为语义说明，不能直接写成 OAS type 或 `$ref`。
+   - 采用 YSS wrapper 时，`code` 按 profile 只允许 `string | integer | null`，`dataType` 为 `string | null`；采用 YSS 分页协议时，`offset`、`needTotalCount`、`tempTotalCount` 不得进入客户端分页输入。`totalPages` 等计算字段只有目标 HTTP mapper / fixture 证明后才能进入契约。Spec 明确改变认证或授权行为时，把对应 `401` / `403`、资源过滤和错误语义作为普通 API 行为检查。
 
 3. **独立 Draft Review 与 Freeze**
    - 将通过 verifier 且 SHA-256 与当前 YAML 一致的 validation record 交给 `yss-openapi-draft-review`。缺锁定 lint 时可以先做语义预审，但独立 Review 总结果必须为 `Blocked`；不能用“Freeze 前补 lint”支持 `Approved`。