create-yss-spec 2.1.5 → 2.1.7

package/template/.hermes/skills/yss-dto/agents/openai.yaml

@@ -2,4 +2,4 @@ version: 1
 interface:
   display_name: "YSS DTO"
   short_description: "统一响应、分页查询、Command 与 DTO 设计规范"
-  default_prompt: "Use $yss-dto to define YSS-style DTOs, page queries, commands, and unified response models."
+  default_prompt: "Use $yss-dto to define YSS-style DTOs, page queries, commands, unified response models, and their OpenAPI HTTP/JSON wire shapes."

package/template/.hermes/skills/yss-dto/references/README.md

@@ -1,6 +1,6 @@
 # 参考资料
 
-本文档详细介绍了 `yss-component-dto` 组件的核心数据传输对象（DTO）。这些 DTO 类被广泛应用于各个服务项目，用于规范数据交互格式。
+本文档详细介绍了 `yss-component-dto` 组件的核心数据传输对象（DTO）。这些 DTO 类被广泛应用于各个服务项目，用于规范数据交互格式。公开 HTTP/JSON 的可复用映射以 `openapi-wire-profile.yaml` 为准；本文不把 Java 字段或 getter 自动等同于 wire shape。
 
 ## 核心类 (Core Classes)
 
@@ -13,7 +13,7 @@
 **核心字段**:
 
 - `success`: 操作是否成功 (boolean)
-- `code`: 状态码 (Object, 默认 "DM-A0001")
+- `code`: Java 内部类型为 `Object`；公开 wire contract 仅允许 `string | integer | null`
 - `message`: 消息描述 (String, 默认 "数据返回正常")
 - `dataType`: 返回数据格式
 - `tips`: 提示消息
@@ -44,6 +44,13 @@
 - 提供了链式调用的 Setter 方法 (`setPageIndex`, `setPageSize` 等)。
 - 自动计算偏移量 `getOffset()`。
 
+## HTTP/JSON 映射边界
+
+- 新契约使用 `com.yss.cloud.dto.result`；`com.yss.cloud.dto.response` 只作为 legacy / compatibility 线索。
+- 公共响应 schema 使用 `YssResultMeta`，具体 endpoint schema 使用 `allOf` 组合，并声明 `x-yss-response-wrapper`。
+- `MultiResult.data` 和 `PageResult.data` 为数组；`SingleResult.data` 绑定具体 endpoint schema。不要把 `SingleResult<T>`、`MultiResult<T>` 或 `PageResult<T>` 的 Java 泛型文字直接写成 OpenAPI schema。
+- `PageQuery` 的客户端字段是 `pageIndex/pageSize/orderBy/orderDirection/groupBy`；`offset`、`needTotalCount`、`tempTotalCount` 不属于客户端输入。`totalPages` 只有目标 mapper / contract evidence 证明后才进入响应契约。
+
 ### 3. CommandDTO.java & QueryDTO.java
 
 **位置**: `../assets/CommandDTO.java`, `../assets/QueryDTO.java`

package/template/.hermes/skills/yss-dto/references/openapi-wire-profile.yaml

@@ -0,0 +1,181 @@
+schema_version: 1
+kind: yss-dto-openapi-wire-profile
+
+# This profile is the reusable mapping source consumed by the OpenAPI skills.
+# It describes the public HTTP/JSON shape, not every Java field or getter.
+canonical:
+  java_package: com.yss.cloud.dto.result
+  type_parameter:
+    name: T
+    java_bound: java.io.Serializable
+  openapi:
+    response_meta_schema: YssResultMeta
+    concrete_schema_composition: allOf
+    response_wrapper_extension: x-yss-response-wrapper
+    literal_java_generic_schema: false
+
+compatibility_packages:
+  - java_package: com.yss.cloud.dto.response
+    status: legacy-or-compatibility
+    use_for_new_contracts: false
+    policy: do-not-introduce-in-new-contracts
+
+common_response:
+  schema_name: YssResultMeta
+  fields:
+    success:
+      direction: response
+      wire_types: [boolean]
+      nullable: false
+      required: true
+    dataType:
+      direction: response
+      wire_types: [string, "null"]
+      nullable: true
+      required: true
+    code:
+      direction: response
+      wire_types: [string, integer, "null"]
+      nullable: true
+      required: true
+      policy: do-not-widen-global-wrapper
+    message:
+      direction: response
+      wire_types: [string, "null"]
+      nullable: true
+      required: true
+    tips:
+      direction: response
+      wire_types: [string, "null"]
+      nullable: true
+      required: true
+
+wrappers:
+  SingleResult:
+    java_type: com.yss.cloud.dto.result.SingleResult<T>
+    response_kind: single
+    data:
+      direction: response
+      wire_shape: endpoint-schema-or-null
+      nullable: true
+      required: true
+  MultiResult:
+    java_type: com.yss.cloud.dto.result.MultiResult<T>
+    response_kind: non-page-list
+    data:
+      direction: response
+      wire_types: [array]
+      items: endpoint-schema
+      nullable: false
+      required: true
+      empty_value: []
+  PageResult:
+    java_type: com.yss.cloud.dto.result.PageResult<T>
+    response_kind: page
+    fields:
+      totalCount:
+        direction: response
+        wire_types: [integer]
+        format: int64
+        minimum: 0
+        nullable: false
+        required: true
+      pageSize:
+        direction: response
+        wire_types: [integer]
+        format: int32
+        minimum: 1
+        nullable: false
+        required: true
+      pageIndex:
+        direction: response
+        wire_types: [integer]
+        format: int32
+        minimum: 1
+        nullable: false
+        required: true
+      data:
+        direction: response
+        wire_types: [array]
+        items: endpoint-schema
+        nullable: false
+        required: true
+        empty_value: []
+    computed_fields:
+      totalPages:
+        java_getter: getTotalPages
+        status: mapper-dependent
+        policy: include-only-with-target-wire-evidence
+
+page_query:
+  java_type: com.yss.cloud.dto.page.PageQuery
+  request_direction: query
+  fields:
+    pageIndex:
+      direction: request
+      wire_types: [integer]
+      format: int32
+      minimum: 1
+      default: 1
+      nullable: false
+      required: false
+    pageSize:
+      direction: request
+      wire_types: [integer]
+      format: int32
+      minimum: 1
+      default: 10
+      nullable: false
+      required: false
+    orderBy:
+      direction: request
+      wire_types: [string, "null"]
+      nullable: true
+      required: false
+      policy: endpoint-whitelist-required
+    orderDirection:
+      direction: request
+      wire_types: [string]
+      enum: [ASC, DESC]
+      default: DESC
+      nullable: false
+      required: false
+    groupBy:
+      direction: request
+      wire_types: [string, "null"]
+      nullable: true
+      required: false
+      policy: endpoint-whitelist-required
+  forbidden_client_fields:
+    - offset
+    - needTotalCount
+    - tempTotalCount
+  computed_fields:
+    offset:
+      java_getter: getOffset
+      status: computed
+      policy: exclude-from-client-input
+    needTotalCount:
+      java_getter: isNeedTotalCount
+      status: internal-or-ignored
+      policy: exclude-from-client-input
+    tempTotalCount:
+      java_getter: getTempTotalCount
+      status: internal-or-ignored
+      policy: exclude-from-client-input
+
+request_bases:
+  command:
+    java_type: com.yss.cloud.dto.CommandDTO
+    direction: request
+  query:
+    java_type: com.yss.cloud.dto.QueryDTO
+    direction: request
+    extends: command
+
+wire_evidence:
+  required_before_freeze:
+    - target-http-mapper-identity
+    - representative-serialization-fixtures
+    - contract-test-or-equivalent-http-evidence
+  rule: Java fields and computed getters are not public wire facts until target-boundary evidence confirms them.

package/template/.hermes/skills/yss-dto/references/source-index.md

@@ -1,11 +1,11 @@
 # yss-dto Source Index
 
-Generated: 2026-08-08T15:43:04+00:00
-Source commit: `a34644e2dfc4eb2bfa2b0a1c69dc6b61cc98539a`
+Generated: 2026-08-17T12:03:37.436Z
+Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.py`. Do not hand-edit generated sections.
+This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 
 Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
 
@@ -33,9 +33,12 @@ Paths below are source path hints captured at refresh time. If they do not exist
 - `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/audit/message/AuditOperationType.java`
 - `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/audit/message/AuditResourceType.java`
 - `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/audit/message/EventMessage.java`
-- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/camel/RouteInfo.java`
 - `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/page/PageQuery.java`
 - `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/page/PageRequestFactory.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/response/MultiResult.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/response/PageResult.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/response/Result.java`
+- `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/response/SingleResult.java`
 - `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/result/MultiResult.java`
 - `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/result/PageResult.java`
 - `yss-microservice-components/yss-component-dto/src/main/java/com/yss/cloud/dto/result/Result.java`

package/template/.hermes/skills/yss-excel-mvc/references/source-index.md

@@ -1,11 +1,11 @@
 # yss-excel-mvc Source Index
 
-Generated: 2026-08-08T15:43:04+00:00
-Source commit: `a34644e2dfc4eb2bfa2b0a1c69dc6b61cc98539a`
+Generated: 2026-08-17T12:03:37.436Z
+Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.py`. Do not hand-edit generated sections.
+This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 
 Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
 

package/template/.hermes/skills/yss-exception/references/source-index.md

@@ -1,11 +1,11 @@
 # yss-exception Source Index
 
-Generated: 2026-08-08T15:43:04+00:00
-Source commit: `a34644e2dfc4eb2bfa2b0a1c69dc6b61cc98539a`
+Generated: 2026-08-17T12:03:37.436Z
+Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.py`. Do not hand-edit generated sections.
+This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 
 Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
 

package/template/.hermes/skills/yss-hook/references/frontend-docs.md

@@ -1,6 +1,6 @@
 # yss-hook Frontend Documentation
 
-Generated: 2026-06-29T16:11:14+00:00
+Generated: 2026-08-17T12:03:37.436Z
 
 Use these YSS UI documentation entry points as authoritative references when local repo examples are insufficient.
 

package/template/.hermes/skills/yss-jdbc/references/source-index.md

@@ -1,11 +1,11 @@
 # yss-jdbc Source Index
 
-Generated: 2026-08-08T15:43:04+00:00
-Source commit: `a34644e2dfc4eb2bfa2b0a1c69dc6b61cc98539a`
+Generated: 2026-08-17T12:03:37.436Z
+Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.py`. Do not hand-edit generated sections.
+This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 
 Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
 

package/template/.hermes/skills/yss-log/references/source-index.md

@@ -1,11 +1,11 @@
 # yss-log Source Index
 
-Generated: 2026-08-08T15:43:04+00:00
-Source commit: `a34644e2dfc4eb2bfa2b0a1c69dc6b61cc98539a`
+Generated: 2026-08-17T12:03:37.436Z
+Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.py`. Do not hand-edit generated sections.
+This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 
 Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
 

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

@@ -61,7 +61,7 @@ description: 用于 YSS MyBatis 与 MyBatis-Plus 持久层规范、配置和排
 
 - 不要同时引入两套分页机制而不说明谁生效。
 - 不要在已有 Repository 基类体系之外再造一套 Mapper 抽象。
-- 若用户只是要生成持久层骨架，优先衔接 `yss-db2mybatis`。
+- 若用户只是要生成持久层骨架，优先衔接 `yss-repository`。
 
 ## 按需读取
 

package/template/.hermes/skills/yss-mybatis/references/source-index.md

@@ -1,11 +1,11 @@
 # yss-mybatis Source Index
 
-Generated: 2026-08-08T15:43:04+00:00
-Source commit: `a34644e2dfc4eb2bfa2b0a1c69dc6b61cc98539a`
+Generated: 2026-08-17T12:03:37.436Z
+Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.py`. Do not hand-edit generated sections.
+This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 
 Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
 

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

@@ -12,7 +12,8 @@ Use this skill after OpenAPI Draft creation and before Engineering Baseline / YS
 - OpenAPI Draft under `docs/.scratch/<feature>/api/<feature>.yaml`，作为唯一权威的单一 OAS 3.1 YAML document；生命周期元数据和 Freeze 决策位于相邻 Markdown 记录。
 - Calibrated Spec.
 - Interaction spec / prototype review when UI exists.
-- YSS engineering baseline rules, especially `SingleResult<T>`, `MultiResult<T>`, and `PageResult<T>`.
+- YSS engineering baseline rules and `.agents/skills/yss-dto/references/openapi-wire-profile.yaml`；先运行 `scripts/verify-yss-dto-openapi-profile`。
+- 若 Draft 包含 computed getter（例如 `totalPages`），必须提供目标 HTTP mapper identity、代表性序列化 fixture 和 contract-test / 等价 HTTP evidence。
 
 ## Review Flow
 
@@ -20,13 +21,16 @@ Use this skill after OpenAPI Draft creation and before Engineering Baseline / YS
 2. Build a P0 traceability matrix from Spec functional requirements and interaction actions to OpenAPI paths, schemas, errors, and contract tests. Each UI action must map to a stable `operationId` and `x-yss-action-key` or an equivalent traceability entry.
 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.
-5. Check YSS API baseline: REST shape, `SingleResult<T>` for single objects, `MultiResult<T>` for non-page lists, `PageResult<T>` for pagination, and stable DTO/schema names.
-6. 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.
-7. Output a persistent review artifact under `docs/.scratch/<feature>/architecture/` or update the existing one.
+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.
+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.
 
 ## Automation Boundary
 
 - Automated checks own YAML single-document syntax, `$ref` resolution, path-parameter consistency, OpenAPI lint, and stable machine-checkable style rules.
+- `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.
 - 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.
@@ -38,7 +42,9 @@ Block if any of these are true:
 - A P0 requirement has no endpoint, schema, error contract, or explicit non-goal.
 - 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 YSS `PageResult<T>` or documented exception.
+- 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.
 - Draft has no contract test seam for import, mapping coverage, validation, review, publish, export, and optimistic locking.
 - YAML contains lifecycle frontmatter / root metadata, or the proposed JSON client input is not explicitly deferred until Freeze and governance export.
 
@@ -58,9 +64,15 @@ Block if any of these are true:
 - <P0 requirement -> endpoint/schema/error/test mapping summary>
 
 ### YSS Baseline
-- <response wrappers, DDD boundary implications, implementation feasibility>
+- <`x-yss-response-wrapper` map and `YssResultMeta` / `allOf` conformance>
+- <profile version, concrete `data` schemas, nullability, request/response direction and computed-field evidence>
+- <DDD boundary implications, implementation feasibility>
 
 ### Contract Test Checklist
+- <wrapper meta fields: success/code/message/tips/dataType, including code string/integer/null cases>
+- <single object, non-page list empty array, page empty array and page boundary cases>
+- <PageQuery allowed fields, ASC/DESC and endpoint whitelist; negative assertions for offset/needTotalCount/tempTotalCount>
+- <target HTTP mapper identity and computed-field fixture, if totalPages or another getter is included>
 - <minimum contract tests before OpenAPI Freeze>
 
 ### Next Action

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

@@ -13,12 +13,15 @@ Spec / 设计输入 → OpenAPI YAML Draft → 审查与 Freeze → JSON 派生
 
 `docs/.scratch/<feature>/api/<feature>.yaml` 是唯一权威的 OpenAPI 3.1 契约。JSON 只能由冻结后的 YAML 可复现地产生，用于前端代码生成或分发；不得手写、不得反向覆盖 YAML、不得把运行时代码当成设计契约来源。
 
+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` 字段表。
+
 ## 边界与职责
 
 使用 `yss-openapi-governance`：
 
 - 基于冻结前的 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、请求 / 响应方向和分页负向字段。
 - 运行受项目 lockfile 约束的 lint / bundle，检查 `$ref`、operationId、响应包装、错误、分页、幂等和契约测试 seam；只有 Spec 明确改变认证或授权行为时才检查对应契约。
 - 在 OpenAPI Freeze 后，用锁定的 Redocly CLI 将 YAML bundle 为 JSON，并记录可重现证据。
 - 维护治理记录、Freeze 记录和 JSON 派生记录。
@@ -59,7 +62,9 @@ pnpm exec redocly bundle \
 2. **运行结构与治理校验**
    - 先执行项目锁定的 `pnpm exec redocly lint` 或等价 CI 脚本。
    - 检查 YAML 可解析、`$ref` 可解析、路径参数完整、operationId 唯一、examples 合法、schema 命名稳定。
-   - 检查 `/api/v1/` 版本策略（或记录例外）、`SingleResult<T>` / `MultiResult<T>` / `PageResult<T>`、统一错误结构、分页、幂等 / 乐观锁和契约测试 seam。Spec 明确改变认证或授权行为时，把对应 `401` / `403`、资源过滤和错误语义作为普通 API 行为检查。
+   - 先运行 `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 行为检查。
 
 3. **独立 Draft Review 与 Freeze**
    - 将 fresh lint 证据交给 `yss-openapi-draft-review`；阻断项未关闭前，YAML 仍是 review-only Draft，不得生成生产客户端。
@@ -85,6 +90,9 @@ pnpm exec redocly bundle \
 - YAML / `$ref` / lint 不通过，operationId 不稳定或不唯一，或路径参数、schema、examples 无法解析。
 - P0 操作缺请求、响应、错误、并发 / 幂等规则或可验证 seam；Spec 明确的认证或授权行为没有契约表示。
 - `$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` 作为客户端字段。
+- `totalPages`、任何 computed getter 或 Lombok / `@JsonIgnore` 推导字段没有目标 mapper identity、代表性序列化 fixture 和 contract-test / 等价 HTTP 证据。
 - Freeze 记录、YAML SHA-256、JSON SHA-256、JSON 解析 / lint 证据缺失。
 - JSON 被手工编辑，或生成结果试图反向成为 YAML 的权威来源。
 
@@ -102,6 +110,8 @@ pnpm exec redocly bundle \
 
 ### Validation
 - Lint command and result: <locked pnpm command / result>
+- YSS DTO wire profile: <`.agents/skills/yss-dto/references/openapi-wire-profile.yaml`, schema_version, verifier result>
+- Wrapper conformance: <`x-yss-response-wrapper`, `YssResultMeta`, `allOf`, concrete data schema, direction and forbidden-field result>
 - `$ref` policy / approved exceptions: <details>
 - Blocking findings: <file:line grounded finding>
 

package/template/.hermes/skills/yss-page-module-development/references/frontend-docs.md

@@ -1,6 +1,6 @@
 # yss-page-module-development Frontend Documentation
 
-Generated: 2026-06-29T16:11:14+00:00
+Generated: 2026-08-17T12:03:37.436Z
 
 Use these YSS UI documentation entry points as authoritative references when local repo examples are insufficient.
 

package/template/.hermes/skills/yss-product-lifecycle/SKILL.md

@@ -33,6 +33,8 @@ YSS 仓库以本 skill 为直接入口，不机械嵌套调用 `ask-matt`。`ask
 - 安全 / 权限不设独立生命周期资料、专属门禁或 `not-applicable` 记录。只有需求或冻结资产明确要求改变认证、授权、租户隔离、敏感数据或合规行为时，才把该行为写入普通 Spec、API、架构、验收和测试 seam，并仅按实际 UI、API、Backend、Data、High-risk 影响触发既有门禁；普通 action 注册、沿用认证中间件、未变化的 `401` / `403`、一般字段、SQL / DDL / 迁移和上传 / 下载本身不触发安全 / 权限流程。
 - 有效 `yss-project.yaml` 存在时，`ask-matt` 和 `setup-matt-pocock-skills` 只能作为子流程；最终入口、仓库身份和模式裁决归本编排器。
 - `template-source` 命中产品 flow 时必须返回 `blocked`（`template-source-product-artifact-forbidden`），不得继续到产品资产或 Ticket 生成。
+- `template-source` 迁移共享工具或验证器前，先区分维护侧构建资产、实例分发面和实例运行资产；冻结公开入口、运行时前提、旧实现处置和跨仓消费者契约后，才可改写实现。
+- 替换自身验证门禁时，不得只用候选门禁自证；必须保留独立 baseline oracle 或同一 fixture 的双跑证据。涉及共享运行资产时，只有生成/同步实例、失败回滚和跨仓消费者的 fresh evidence 齐备，才能声明生态完成或可发布。
 - 文件存在不等于就绪。按内容、审查结论和上游新鲜度评估资产。
 - 父 Ticket/checkpoint 的状态只是索引；与真实资产冲突时，以权威资产为准并修复索引。
 - 上游变化按依赖图精准传播 `stale`；不要无条件重跑完整阶段。

package/template/.hermes/skills/yss-repository/SKILL.md

@@ -23,7 +23,7 @@ description: Use when generating or refactoring YSS persistence models, BaseRepo
 
 1. 先确认输入来源：领域模型、metadata、数据库表、DDL。
 2. 探测持久化 profile：新 DDD 默认 `PO <-> Domain Model`；legacy YSS 常见 `Entity + BaseRepository + GatewayImpl`。沿用现有工程命名，不混用两套模型。
-3. 如果 metadata 不完整，优先转到 `yss-db2mybatis` 提取。
+3. 如果 metadata 不完整，先补齐 metadata、数据库表结构或 DDL 输入。
 4. 涉及 POJO 字段、getter/setter、constructor、builder 或日志时，必须加载并遵守 `lombok`。
 5. 涉及持久化模型与 Domain/VO/CMD 转换时，必须加载并遵守 `mapstruct`。
 6. 生成代码时严格保持 Domain 与 Infrastructure 分层边界。
@@ -57,7 +57,7 @@ description: Use when generating or refactoring YSS persistence models, BaseRepo
 
 ## 协同顺序
 
-- metadata 提取：`yss-db2mybatis`
+- metadata / DDL 输入准备：确认输入完整
 - 领域建模：`yss-domain`
 - POJO 样板代码：`lombok`
 - 对象转换：`mapstruct`

package/template/.hermes/skills/yss-resilience4j/references/source-index.md

@@ -1,11 +1,11 @@
 # yss-resilience4j Source Index
 
-Generated: 2026-08-08T15:43:04+00:00
-Source commit: `a34644e2dfc4eb2bfa2b0a1c69dc6b61cc98539a`
+Generated: 2026-08-17T12:03:37.436Z
+Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.py`. Do not hand-edit generated sections.
+This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 
 Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
 

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

@@ -26,7 +26,6 @@ Default for a new page: first verify the approved product design, state matrix,
 - `yss-backend-scaffold-application`: Application use cases, transaction boundaries, and cross-aggregate orchestration.
 - `yss-repository`: Persistence implementation, PO, Repository, Convertor, GatewayImpl.
 - `yss-web-controller`: REST adapter layer, request/response DTOs, VO, web convertor.
-- `yss-db2mybatis`: Generate persistence artifacts from database metadata or DDL.
 - `yss-mybatis`: Framework behavior for MyBatis/MyBatis-Plus, BaseRepository, pagination, mapper scanning, batch, datasource issues.
 - `yss-dto`: Result/PageQuery/CommandDTO/QueryDTO and unified API contract objects.
 
@@ -48,9 +47,7 @@ Default for end-to-end backend CRUD: include Domain, Application, Infrastructure
 - `yss-validation`: Validation engine and JSR-303 integration.
 - `yss-security-algorithm`: RSA/AES/SM/JWT/JWK/password-encoding compatibility and production key-management safety gates.
 - `yss-userinfo`: Current-user info propagation and starter integration.
-- `yss-variable`: Variable component APIs and variable resolution.
 - `yss-exception`: Exception component and unified exception handling.
-- `yss-valuation`: Valuation component behavior.
 
 Component skills should inspect generated `references/source-index.md` before changing code when the task depends on exact class or config names.
 

package/template/.hermes/skills/yss-security-algorithm/references/source-index.md

@@ -1,11 +1,11 @@
 # yss-security-algorithm Source Index
 
-Generated: 2026-08-08T15:43:04+00:00
-Source commit: `a34644e2dfc4eb2bfa2b0a1c69dc6b61cc98539a`
+Generated: 2026-08-17T12:03:37.436Z
+Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.py`. Do not hand-edit generated sections.
+This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 
 Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
 

package/template/.hermes/skills/yss-source-index/SKILL.md

@@ -24,7 +24,7 @@ Run:
 ```bash
 export YSS_SKILLS_ROOT="/path/to/.agents/skills"
 export YSS_SOURCE_ROOT="/path/to/yss-cloud-microservice"
-python3 "$YSS_SKILLS_ROOT/yss-source-index/scripts/refresh-yss-skill-index.py"
+node "$YSS_SKILLS_ROOT/yss-source-index/scripts/refresh-yss-skill-index.mjs"
 ```
 
 Backend-only refreshes may set `YSS_REFRESH_FRONTEND=false` to avoid unrelated frontend timestamp churn.
@@ -56,8 +56,8 @@ Before exact class/config/security guidance, compare the index `Source commit` w
 
 ## After Refresh
 
-Validate changed skills with:
+Validate the migrated Node helper with:
 
 ```bash
-python3 /path/to/skill-creator/scripts/quick_validate.py /path/to/.agents/skills/yss-source-index
+node --test "$YSS_SKILLS_ROOT/yss-source-index/scripts/refresh-yss-skill-index.test.mjs"
 ```

package/template/.hermes/skills/yss-source-index/references/source-map-config.md

@@ -20,9 +20,7 @@ The refresh script maps component source path hints to skill references. These p
 | `yss-validation` | `yss-microservice-components/yss-component-validation-engine-parent`, `yss-microservice-components/yss-component-validation-jsr303` |
 | `yss-security-algorithm` | `yss-microservice-components/yss-component-security-algorithm` |
 | `yss-userinfo` | `yss-microservice-components/yss-component-userinfo-starter` |
-| `yss-variable` | `yss-microservice-components/yss-component-variable` |
 | `yss-exception` | `yss-microservice-components/yss-component-exception` |
-| `yss-valuation` | `yss-microservice-components/yss-component-valuation` |
 
 Frontend docs are written to these skills:
 

package/template/.hermes/skills/yss-source-index/scripts/refresh-yss-skill-index.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { access, mkdir, readdir, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const BACKEND = {"yss-cache":["yss-microservice-components/yss-component-cache-parent"],"yss-mybatis":["yss-microservice-components/yss-component-persistence"],"yss-dto":["yss-microservice-components/yss-component-dto"],"yss-audit-log":["yss-microservice-components/yss-component-audit-log"],"yss-excel-mvc":["yss-microservice-components/yss-component-excel-mvc","yss-microservice-components/yss-component-excel-starter"],"yss-distributed-id":["yss-microservice-components/yss-component-distributed-id","yss-microservice-components/yss-component-leaf"],"yss-jdbc":["yss-microservice-components/yss-component-jdbc"],"yss-dictionary":["yss-microservice-components/yss-component-dictionary-parent"],"yss-log":["yss-microservice-components/yss-component-log-starter"],"yss-resilience4j":["yss-microservice-components/yss-component-resilience4j-starter"],"yss-taskflow":["yss-microservice-components/yss-component-taskflow"],"yss-validation":["yss-microservice-components/yss-component-validation-engine-parent","yss-microservice-components/yss-component-validation-jsr303"],"yss-security-algorithm":["yss-microservice-components/yss-component-security-algorithm"],"yss-userinfo":["yss-microservice-components/yss-component-userinfo-starter"],"yss-exception":["yss-microservice-components/yss-component-exception"]};
+const FRONTEND={"yss-ui":["components","hooks","skills"],"yss-components":["components"],"yss-hook":["hooks"],"yss-page-module-development":["components","hooks","skills"],"yss-use-table-height":["hooks"],"yss-use-tree-height":["hooks"]};
+const URLS={components:"http://192.168.164.27:3200/components",hooks:"http://192.168.164.27:3200/hooks",skills:"http://192.168.164.27:3200/skills"};
+const KEYS=["Audit","Cache","Clear","Command","Configuration","Controller","DTO","Data","Enable","Excel","Handler","Interceptor","Jdbc","Mapper","Mybatis","Page","Properties","Query","Repository","Request","Response","Result","Update","Aspect","Leaf","Id","Dir","Dic","Dictionary","File","Upload","Log","Message","Mail","Liquibase","Circuit","Breaker","Sql","Tpl","Tag","Task","Flow","Report","Validation","Validator","Security","Crypto","User","Variable","Quality","Search","Similarity","Scheduler","Runner","Duck","Dynamic","Factory","Client","Feign","Gateway","Convertor","Adapter","Advice","Bridge","Route","Uploader","Sftp","Minio","Parser","Express","Rule","Template","Generator","Importer","Engine","Event","Submitter","Executor","Context","Status","Type","State"];
+const DOCS=new Set(["README.md","readme.md","HELP.md","TECHNICAL_DESIGN.md"]);
+const exists=async p=>{try{await access(p);return true}catch{return false}};
+async function walk(root){if(!await exists(root))return[];const out=[];for(const item of await readdir(root,{withFileTypes:true})){const p=path.join(root,item.name);if(item.isDirectory())out.push(...await walk(p));else if(item.isFile())out.push(p)}return out}
+const relative=(root,p)=>{const value=path.relative(root,p);return value&&!value.startsWith("..")?value:p};
+function state(root){try{const run=args=>execFileSync("git",["-C",root,...args],{encoding:"utf8",stdio:["ignore","pipe","ignore"]}).trim();return[run(["rev-parse","HEAD"]),run(["status","--porcelain"])?"dirty":"clean"]}catch{return["unavailable","unknown"]}}
+async function sourceRoot(){if(process.env.YSS_SOURCE_ROOT){const root=path.resolve(process.env.YSS_SOURCE_ROOT);if(await exists(path.join(root,"yss-microservice-components")))return root;throw new Error(`YSS_SOURCE_ROOT must point to the repository root containing \`yss-microservice-components\`: ${root}`)}const home=os.homedir(),candidates=[process.cwd(),...ancestors(process.cwd()),path.join(home,"Documents/yss-project/yss-cloud-microservice"),path.join(home,"Documents/yss-project"),path.join(home,"Projects/yss-cloud-microservice"),path.join(home,"Projects")];for(const base of [path.join(home,"Projects"),path.join(home,"Documents"),path.join(home,"Documents/yss-project")])if(await exists(base))for(const entry of await readdir(base,{withFileTypes:true}))if(entry.isDirectory())candidates.push(path.join(base,entry.name));for(const root of candidates)if(await exists(path.join(root,"yss-microservice-components")))return path.resolve(root);throw new Error("Could not find a YSS source repository containing `yss-microservice-components`. Export YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice and rerun.")}
+function ancestors(start){const out=[];let current=path.resolve(start);while(path.dirname(current)!==current){current=path.dirname(current);out.push(current)}return out}
+async function files(bases){const out={docs:[],poms:[],java:[]};for(const base of bases)for(const p of await walk(base)){if(DOCS.has(path.basename(p)))out.docs.push(p);else if(path.basename(p)==="pom.xml")out.poms.push(p);else if(p.endsWith(".java")&&p.includes(`${path.sep}src${path.sep}main${path.sep}java${path.sep}`))out.java.push(p)}for(const a of Object.values(out))a.sort();return out}
+export async function refresh({skillsRoot,source,now=new Date().toISOString(),frontend=true}){const [commit,worktree]=state(source);for(const [skill,parts]of Object.entries(BACKEND)){const bases=parts.map(item=>path.join(source,item));const found=await files(bases);const java=found.java.filter(p=>KEYS.some(key=>path.basename(p,".java").includes(key))).slice(0,120);const list=(items,map,empty)=>items.length?items.map(map):[empty];const baseHints=await Promise.all(bases.map(async p=>`- \`${relative(source,p)}\` (${await exists(p)?"existed":"missing"} when indexed)`));const lines=[`# ${skill} Source Index`,``,`Generated: ${now}`,`Source commit: \`${commit}\``,`Source worktree: \`${worktree}\``,`Indexed source root: resolved at refresh time; set \`YSS_SOURCE_ROOT\` to reproduce or refresh.`,``,`This file is generated by \`yss-source-index/scripts/refresh-yss-skill-index.mjs\`. Do not hand-edit generated sections.`,``,`Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using \`YSS_SOURCE_ROOT\`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.`,``,`## Component Path Hints`,``,...baseHints,``,`## Documentation Files`,``,...list(found.docs,p=>`- \`${relative(source,p)}\``,"- No component documentation files found."),``,`## Maven Modules`,``,...list(found.poms,p=>`- \`${relative(source,path.dirname(p))}\``,"- No Maven modules found."),``,`## Key Java Entry Points`,``,...list(java,p=>`- \`${relative(source,p)}\``,"- No key Java entry points matched the configured name patterns."),``,`## Recommended Next Reads`,``,`- Start with the documentation files above when learning component usage.`,`- Search the key Java entry points for annotations, auto configuration, properties, aspects, interceptors, handlers, and result objects before changing application code.`,`- Prefer existing component extension points over rewriting framework logic in business modules.`,``];const target=path.join(skillsRoot,skill,"references","source-index.md");await mkdir(path.dirname(target),{recursive:true});await writeFile(target,lines.join("\n"),"utf8")}
+ if(frontend)for(const[skill,keys]of Object.entries(FRONTEND)){if(!await exists(path.join(skillsRoot,skill)))continue;const target=path.join(skillsRoot,skill,"references","frontend-docs.md");await mkdir(path.dirname(target),{recursive:true});await writeFile(target,[`# ${skill} Frontend Documentation`,``,`Generated: ${now}`,``,`Use these YSS UI documentation entry points as authoritative references when local repo examples are insufficient.`,``,...keys.map(key=>`- ${key}: ${URLS[key]}`),``,`When documentation and local code differ, inspect the current project code before editing and prefer established local usage.`,``].join("\n"),"utf8")}
+ return{backend:Object.keys(BACKEND).length,frontend:frontend?Object.keys(FRONTEND).length:0}}
+async function main(){try{const script=path.dirname(fileURLToPath(import.meta.url));const result=await refresh({skillsRoot:path.resolve(process.env.YSS_SKILLS_ROOT||path.join(script,"../..")),source:await sourceRoot(),frontend:!["0","false","no"].includes((process.env.YSS_REFRESH_FRONTEND||"true").toLowerCase())});console.log(`Updated ${result.backend} backend indexes and ${result.frontend} frontend doc references.`)}catch(error){console.error(error.message);process.exitCode=1}}
+if(process.argv[1]===fileURLToPath(import.meta.url))await main();