create-yss-spec 3.0.0 → 3.1.0

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

@@ -1,57 +0,0 @@
-# 参考资料
-
-本文档详细介绍了 `yss-component-mybatis-starter` 模块中的核心类和配置类，这些类构成了通用 MyBatis 模式的基础。
-
-## 核心类 (Core Classes)
-
-### 1. BaseRepository.java
-**位置**: `../assets/BaseRepository.java`
-
-`BaseRepository<T, D>` 是通用 MyBatis 模式下的核心 Mapper 接口，所有业务 Repository 都应继承它。
-
-**主要特性**:
-- **继承链**: 继承了 `io.mybatis.mapper.BaseMapper` (基础 CRUD), `io.mybatis.mapper.list.ListMapper` (批量操作), 和 `com.baomidou.mybatisplus.core.mapper.Mapper` (兼容性)。
-- **通用方法**:
-  - `insert`, `update`, `delete`: 标准的单表操作。
-  - `selectBatchIds`, `deleteBatchIds`: 批量操作。
-  - `selectByMap`, `selectMaps`, `selectObjs`: 基于 Map 和 Wrapper 的查询。
-- **扩展点**: 允许用户通过继承此接口，获得开箱即用的 CRUD 能力，无需编写 XML。
-
-### 2. EntityQueryAspect.java
-**位置**: `../assets/EntityQueryAspect.java`
-
-这是一个 AOP 切面，用于实现非侵入式的自动分页功能。
-
-**工作原理**:
-- **切点**: 拦截所有 Repository 层 (`@Repository`) 和 Gateway 实现层的方法。
-- **条件**: 方法参数中必须包含 `com.yss.cloud.dto.page.PageQuery` 对象。
-- **逻辑**:
-  1. 检查 `PageQuery` 参数是否非空。
-  2. 调用 `PageHelper.offsetPage(offset, pageSize)` 开启分页。
-  3. 执行目标方法。
-  4. 获取分页结果的总记录数 (`page.getTotal()`)。
-  5. 将总数回填到 `PageQuery.tempTotalCount` 字段中。
-
-### 3. MybatisBaseConfiguration.java
-**位置**: `../assets/MybatisBaseConfiguration.java`
-
-MyBatis 基础配置类，负责加载核心组件。
-
-**主要功能**:
-- **导入配置**: 导入了 `PageQueryEntityConfigration`，确保分页切面生效。
-- **启用属性**: 启用了 `PrimaryDataSourceProperties`, `MybatisPlusGlobalProperties`, `YssMybatisMapperProperties` 等配置属性类。
-
-### 4. PageQueryEntityConfigration.java
-**位置**: `../assets/PageQueryEntityConfigration.java`
-
-负责注册分页查询切面。
-
-**主要功能**:
-- 定义了 `entityQueryAspect` Bean，使其受 Spring 容器管理，从而激活自动分页拦截功能。
-
-## 使用建议
-
-当您在开发中使用通用 MyBatis 模式时：
-1. **定义 Repository**: 直接继承 `BaseRepository<Entity, ID>`。
-2. **分页查询**: 在方法参数中添加 `PageQuery`，框架会自动处理分页逻辑。
-3. **批量操作**: 使用 `insertList`, `updateList` 等方法进行高效的数据处理。

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

@@ -1,93 +0,0 @@
-# yss-mybatis Source Index
-
-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.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
-
-- `yss-microservice-components/yss-component-persistence` (existed when indexed)
-
-## Documentation Files
-
-- `yss-microservice-components/yss-component-persistence/HELP.md`
-- `yss-microservice-components/yss-component-persistence/README.md`
-- `yss-microservice-components/yss-component-persistence/TECHNICAL_DESIGN.md`
-
-## Maven Modules
-
-- `yss-microservice-components/yss-component-persistence`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter`
-- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common`
-
-## Key Java Entry Points
-
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/config/defaults/UserConfig.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/config/spring/SpringEnvAutoConfiguration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/BaseMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/Mapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/base/EntityMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/config/MapperUserConfig.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/example/ExampleMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/fn/FnMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/list/ListMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/logical/LogicalColumn.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/logical/LogicalMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/mapper/logical/LogicalProvider.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/EntityColumnFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/EntityFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/EntityInfoMapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/EntityTableFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlCache.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlScript.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlScriptWrapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlSourceCustomize.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/SqlWrapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/config/ProviderUserConfig.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/AnnotationSqlScriptWrapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/AnnotationSqlWrapper.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/CachingEntityTableFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/DefaultEntityColumnFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/DefaultEntityColumnFactoryChain.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/DefaultEntityTableFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/DefaultEntityTableFactoryChain.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/defaults/GenericTypeResolver.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/jpa/JpaEntityColumnFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/jpa/JpaEntityTableFactory.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/jpa/SimpleTypeUtil.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/GenId.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/GenIdKeyGenerator.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/GenIdSqlSource.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/KeySqlMsCustomize.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-mapper/src/main/java/io/mybatis/provider/keysql/KeySqlSqlSourceCustomize.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/MybatisPlusConfiguration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/MybatisPlusGlobalProperties.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/PageInterceptorProperties.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/YssMybatisMapperProperties.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/BatchSqlInjector.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MapperConfiguration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/config/MybatisPlusConfig.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis/support/BasePlusRepository.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/LogbackImpl.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/MybatisBaseConfiguration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/aop/EntityQueryAspect.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/config/PageQueryEntityConfigration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis/support/BaseRepository.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceConfiguration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceHolder.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/MultiDataSourceProperties.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/PrimaryDataSourceConfiguration.java`
-- `yss-microservice-components/yss-component-persistence/yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis/PrimaryDataSourceProperties.java`
-
-## 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.

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

@@ -1,82 +0,0 @@
----
-name: yss-openapi-draft-review
-description: Use when reviewing a `docs/.scratch/<feature>/api/` OpenAPI Draft before Engineering Baseline, YSS DDD Review, architecture/Spec Delta design, OpenAPI Freeze, vertical slicing, frontend/backend implementation, or when checking P0 requirement coverage, page action to endpoint mapping, YSS response wrappers, errors, pagination, optimistic locking, and contract test seams.
----
-
-# YSS OpenAPI Draft Review
-
-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.
-
-## Required Inputs
-
-- 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 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
-
-1. Consume fresh automated evidence for YAML parsing, single-document OAS 3.1 shape, `$ref`, path parameters, and lint. Generate it once with the Draft or when the Draft changes; do not manually repeat unchanged structural checks.
-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, `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.
-
-## Blocking Rules
-
-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 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.
-
-## Output Contract
-
-```markdown
-### Review Result
-<Approved / Blocked>
-
-### Blocking Findings
-- <file:line grounded finding>
-
-### Non-Blocking Suggestions
-- <can wait until architecture/design>
-
-### Contract Coverage
-- <P0 requirement -> endpoint/schema/error/test mapping summary>
-
-### YSS Baseline
-- <`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
-- <return to OpenAPI Draft / enter Engineering Baseline / architecture design / request YAML-to-JSON export after Freeze>
-```
-
-Prefer `docs/api/templates/openapi-draft-review-checklist.md` when a tabular checklist is useful.

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

@@ -1,130 +0,0 @@
----
-name: yss-openapi-governance
-description: Use when creating, governing, linting, freezing, or exporting YSS OpenAPI 3.1 design-time contracts. The frozen YAML is the only authority; this skill produces the reviewed JSON derivative consumed by frontend client generation.
----
-
-# YSS OpenAPI Governance
-
-本 skill 负责 YSS OpenAPI 的 **YAML-first** 工作流：
-
-```text
-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 派生记录。
-- Spec Delta 影响存在时，在 `docs/.scratch/<feature>/spec-delta/` 记录与冻结 YAML 的关系；没有影响时明确记录 `not-applicable`。
-
-不使用本 skill 来替代：
-
-- `yss-openapi-draft-review`：独立、fail-closed 的语义评审与 P0 追踪。
-- `yss-api-integration`：消费已派生的 JSON，并在目标前端实现仓库中接入既有客户端生成流程。
-- `to-tickets`：在 Freeze 后正式化垂直切片。
-
-## 受控工具链
-
-在持有冻结 YAML 与派生记录的项目工作区中，将 `@redocly/cli` 固定在 `devDependencies` 并提交对应的 pnpm lockfile。使用项目脚本或下列等价命令；不得使用浮动 `npx --yes`、全局安装或未记录版本的转换器。
-
-```bash
-pnpm exec redocly lint docs/.scratch/<feature>/api/<feature>.yaml
-
-pnpm exec redocly bundle \
-  docs/.scratch/<feature>/api/<feature>.yaml \
-  --output docs/.scratch/<feature>/api/<feature>.json \
-  --ext json \
-  --component-renaming-conflicts-severity=error \
-  --metafile docs/.scratch/<feature>/api/<feature>.bundle-metafile.json
-```
-
-默认 bundle 保留内部 `$ref`，不要为图省事加入 `--dereferenced`；递归模型或循环引用需要保留其可表示的 `$ref` 结构。若项目将命令包装为 `pnpm openapi:bundle`，该脚本必须实际执行上述 `redocly bundle` 语义，并在记录中写明脚本和已锁定的包版本。
-
-`$ref` 默认只允许引用本 feature API 目录内的相对文件；禁止远程 URL、绝对路径以及越出该目录的路径遍历。需要共享组件或例外时，先在治理 / 架构记录中列出允许位置、所有者与 Freeze 影响，再执行 bundle。
-
-## 治理流程
-
-1. **建立或读取 YAML Draft**
-   - 读取 Spec、产品设计 / 状态矩阵、架构约束和既有 Freeze 记录。
-   - 在 `docs/.scratch/<feature>/api/<feature>.yaml` 创建或更新单一 OAS 3.1 文档；生命周期状态写入相邻 Markdown 记录，不写入 YAML 前置元数据。
-   - 所有操作使用稳定、可生成客户端的 `operationId`；页面动作可通过 `x-yss-action-key` 或同路径的追踪矩阵关联。
-
-2. **运行结构与治理校验**
-   - 先执行项目锁定的 `pnpm exec redocly lint` 或等价 CI 脚本。
-   - 检查 YAML 可解析、`$ref` 可解析、路径参数完整、operationId 唯一、examples 合法、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 行为检查。
-
-3. **独立 Draft Review 与 Freeze**
-   - 将 fresh lint 证据交给 `yss-openapi-draft-review`；阻断项未关闭前，YAML 仍是 review-only Draft，不得生成生产客户端。
-   - Freeze 记录必须引用 YAML 路径、Git ref（如适用）和 YAML SHA-256。冻结后 API 行为变更必须先回到 YAML Draft 与审查。
-
-4. **从冻结 YAML 派生 JSON**
-   - 使用上面的锁定 `redocly bundle` 命令生成 `docs/.scratch/<feature>/api/<feature>.json`，JSON 不纳入人工编辑面。
-   - 对输出 JSON 重新执行解析 / lint（按项目工具链），确认 bundle 未产生组件重名冲突或无法解析的引用。
-   - 写入 `docs/.scratch/<feature>/api/<feature>-json-export.md`，可从 `docs/api/templates/openapi-json-export-record-template.md` 创建。
-   - 记录 YAML SHA-256、JSON SHA-256、OAS 版本、Redocly CLI 版本与 lockfile 引用、完整命令、metafile、`$ref` 例外以及结果。
-
-5. **交给下游前端**
-   - 仅当 Freeze、JSON 派生记录和 JSON 校验均通过时，才把派生 JSON 交给 `yss-api-integration` 与目标前端实现仓库。
-   - JSON 的治理产物固定为 `docs/.scratch/<feature>/api/<feature>.json`。跨仓库时只能由批准的 Cross-repo 子合同或项目脚本将同一字节内容物化为 `<frontend>/openapi/openapi.json`，并记录两端相同的 SHA-256 与交接路径。
-   - 本模板不读取、修改或验证目标前端项目的客户端生成配置，不执行客户端生成，也不把生成动作加入 CI；目标前端项目在需要时手动运行其既有代码生成命令。
-   - 接口调整回写 YAML，而不是编辑 JSON 或生成的 TypeScript。
-
-## 阻断规则
-
-阻断 OpenAPI Freeze 或 JSON 导出，若：
-
-- YAML 不是单一 OAS 3.1 document，或其根节点混入生命周期元数据。
-- 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 的权威来源。
-
-## 输出契约
-
-```markdown
-### Governance Result
-<Draft / Approved for Freeze / Blocked / JSON Exported>
-
-### YAML Authority
-- YAML: <docs/.scratch/<feature>/api/<feature>.yaml>
-- OAS: 3.1.0
-- YAML SHA-256: <sha256>
-- Freeze record: <path / ref>
-
-### 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>
-
-### JSON Derivative
-- JSON: <docs/.scratch/<feature>/api/<feature>.json>
-- JSON SHA-256: <sha256>
-- Redocly CLI / lockfile: <version and lock reference>
-- Bundle command and metafile: <command / path>
-- JSON validation result: <pass / blocked>
-
-### Downstream Handoff
-- Canonical JSON / frontend materialization SHA-256: <same sha / blocked>
-- Frontend materialization path: <frontend/openapi/openapi.json / blocked>
-- Existing frontend code generation: <manual command in target repository / blocked reason>
-- Template boundary: <no frontend configuration, code-generation execution, or CI change>
-```

package/template/.hermes/skills/yss-openapi-governance/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "YSS OpenAPI Governance"
-  short_description: "Govern YAML-first OpenAPI and export frozen JSON"
-  default_prompt: "Use $yss-openapi-governance to govern an OpenAPI YAML Draft, freeze it, and export its reviewed JSON derivative."

package/template/.hermes/skills/yss-page-module-development/SKILL.md

@@ -1,165 +0,0 @@
----
-name: yss-page-module-development
-description: 指导创建标准 Vue 3 YSS 业务页面模块，覆盖 CRUD、列表、表单、详情、左树右表、组件选型、Orval 接口、主题 Token、原型还原和交付验证。
----
-
-# YSS Page Module Development
-
-> **核心路由说明**：新页面生成开发请优先以 `../yss-ui-business-page-generation/SKILL.md` 为统一主规则与硬约束。当前会话可用 yss-ui MCP 时，生成业务代码前必须先调用 `get_codegen_rules`。本技能作为兼容旧触发名与流程编排入口保留。
-
-Use this skill when the user asks for a business page, CRUD module, tree-table page, detail page, or any standard YSS Vue 3 page module.
-
-## Authoritative Docs And Skill Boundaries
-
-- YSS UI components: `http://192.168.164.27:3200/components`
-- YSS UI hooks: `http://192.168.164.27:3200/hooks`
-- YSS UI skills: `http://192.168.164.27:3200/skills`
-- Local reference index: `references/frontend-docs.md`
-
-This skill orchestrates page/module creation. Load narrower skills only when their details are needed:
-
-中文说明：这个技能负责“建页面模块的流程编排”。遇到具体组件、接口、Hook、高度、Formily 细节时，再补充加载更窄的专项技能。
-
-- `yss-components` for layout, YTable/YTree/YssFormily/YSplitPane component specifics.
-- `yss-hook` for request, pagination, parameter, and mapping logic.
-- `yss-api-integration` for Orval-generated APIs and submit/list/detail flows.
-- `yss-use-table-height` and `yss-use-tree-height` for height calculation.
-- `yss-formily` for detailed schema behavior.
-
-## What this skill produces
-
-- a page folder with predictable structure
-- a clear split between page composition and hook logic
-- YSS-aligned query, table, tree, and layout wiring
-- code that follows the existing app conventions instead of ad hoc UI assembly
-
-## Recommended workflow
-
-1. Identify the page type: list, tree-table, detail, or mixed.
-2. Decide whether the page needs `YssFormily`, `YTable`, `YTree`, `YSplitPane`, or custom blocks.
-3. Create the page folder structure.
-4. Move request and parameter logic into hooks.
-5. Assemble the page with minimal logic in `index.vue`.
-6. Verify loading, empty, and error states.
-
-## Standard structure
-
-```text
-views/PageName/
-  components/
-    XxxBlock/
-      index.vue
-      style.less
-      type.ts
-  hooks/
-    usePageTable.ts
-    usePageTree.ts
-  schemas/
-    searchSchema.ts
-  index.vue
-  style.less
-```
-
-Rules:
-
-- `index.vue` is for composition only.
-- `hooks/` holds request, parameter, selection, and mapping logic.
-- `components/` holds reusable blocks and view fragments.
-- `schemas/` holds YssFormily schema definitions.
-
-## Component priority
-
-1. Prefer `@yss-ui/components`.
-2. Use `ant-design-vue` only when YSS does not provide the needed control.
-3. Reuse existing page patterns before inventing a new layout.
-
-## Layout rules
-
-For left-tree-right-content pages:
-
-- use `YSplitPane` or an equivalent flexible split layout
-- keep the right side ordered as Header -> Query -> Data
-- make the content area flexible, not fixed height
-- provide a clear empty state when nothing is selected
-
-For non-split pages:
-
-- keep the main region responsive
-- avoid nested fixed-height containers that fight scrolling
-
-## Height hooks
-
-Use `useTableHeight` and `useTreeHeight` when the page needs available-height calculation.
-
-- bind the ref to the container, not to the table/tree itself
-- include pagination or toolbar offsets when they exist
-- keep the container `flex: 1; overflow: hidden`
-
-## Query and data regions
-
-### YssFormily
-
-- use schema-driven queries
-- keep action buttons in the schema
-- keep local helper logic in `scope`
-
-### YTable
-
-- use `field/type` column definitions
-- prefer named slots for custom cells
-- keep pagination and loading state driven by hook state
-
-### YTree
-
-- keep tree data and selection logic in hooks
-- use search offsets and height helpers when search is present
-
-## Page coding rules
-
-- use `<script setup lang="ts">`
-- keep `index.vue` thin
-- move data transformation out of templates
-- keep action handlers small and explicit
-- preserve existing route, menu, and permission conventions in the repo
-
-## YSS business page contract
-
-- 页面实现前先按 `component-selection-imports` 判定真实导出；已封装能力优先从 `@yss-ui/components`、`@yss-ui/hooks`、`@yss-ui/utils` 导入。
-- 标准列表使用 `YTable` 的真实 `data`、`columns`、`loading`、`pageable`、`v-model:pagination` 和 `@page-change`；主操作放在 `#toolbar-right`，只有确实需要列设置时才启用 `toolbar-config.custom`。
-- 查询区使用 `YFormily` 渲染字段，查询/重置按钮位于表单外部并在窄屏下保持右下对齐；表单、表格、树和导出细节分别加载 `yss-formily`、`ytable-usage`、`ytree-usage` 和 `file-export-download`。
-- 页面有原型或旧页面参考时先读取 `prototype-page-acceptance`，建立视觉、状态、交互和响应式验收清单；交付时必须逐项对照。
-- 页面和组件的颜色、状态色及暗色模式遵循 `theme-token-usage`，不得硬编码品牌色。
-- Orval API 必须使用当前生成导出和 DTO；错误由 mutator 统一处理，业务 Hook 不重复判断 `success` 或重复提示错误。
-- 列表/树高度按实际分页、工具栏和搜索状态选择 `yss-use-table-height` / `yss-use-tree-height`，不得用固定魔法高度替代。
-
-## Deliverables
-
-When implementing a page module, the result should usually include:
-
-- page shell
-- hook file(s)
-- schema file(s)
-- block components if needed
-- styles
-
-## Checklist
-
-- the page structure matches the chosen pattern
-- request logic is isolated in hooks
-- query, pagination, and selection state have one source of truth
-- empty, loading, and error states are covered
-- custom blocks are extracted only when they improve clarity or reuse
-
-## Do not
-
-- do not put large request flows in `index.vue`
-- do not duplicate parameter handling across page and hook
-- do not bypass YSS components when a project-standard control exists
-- do not over-split a simple page into unnecessary files
-
-## Stage 7 Contract
-
-- Require an approved `Slice Implementation Contract`, requirement freeze, low-fidelity review, Ant Design v6 theme/visual-standard high-fidelity HTML prototype, schema v2 semantic mapping/browser/accessibility evidence, user confirmation, and state matrix for UI-impact work; production APIs still come from YSS UI + the actual Ant Design Vue 4.x lockfile.
-- Bind page, hooks, schema, blocks, generated API client, component tests, and E2E paths to contract fields and `allowed_write_paths`.
-- User-visible loading, empty, error, permission, selection, pagination, and action behavior use `behavior-tdd`; purely mechanical page scaffolding may use documented `controlled-generation`.
-- Return the shared `YSS Skill Execution Result`. A prototype mismatch, new API, new permission state, path overrun, or missing evidence must produce `drift`, `violation`, or `new_impacts`, not `implemented`.

package/template/.hermes/skills/yss-page-module-development/agents/openai.yaml

@@ -1,5 +0,0 @@
-version: 1
-interface:
-  display_name: "YSS Page Module"
-  short_description: "标准业务页面模块、分区布局与 Hook 开发实践规范"
-  default_prompt: "Use $yss-page-module-development to scaffold a YSS Vue 3 page module with hooks, schemas, and split layout."

package/template/.hermes/skills/yss-page-module-development/examples/AdvancedFormPage/constant.ts

@@ -1,32 +0,0 @@
-/**
- * 复杂表单页面 - 常量配置
- */
-
-/** 步骤枚举 */
-export enum RULE_STEPS {
-  BASE_INFO = 1,
-  RULE_CONFIG = 2,
-  RULE_RESULT = 3,
-}
-
-/** 步骤配置 */
-export const QUALITY_RULE_STEPS = [
-  { value: RULE_STEPS.BASE_INFO, title: '基本信息' },
-  { value: RULE_STEPS.RULE_CONFIG, title: '规则配置' },
-  { value: RULE_STEPS.RULE_RESULT, title: '规则结果' },
-];
-
-/** 条件组节点接口 */
-export interface ConditionGroup {
-  id: string;
-  type: 'GROUP' | 'LEAF';
-  logicalOp: 'AND' | 'OR';
-  children: any[];
-}
-
-/** 表单选项接口 */
-export interface FormOptions {
-  intensity: Array<{ label: string; value: any }>;
-  errorStorageType: Array<{ label: string; value: string }>;
-  [key: string]: any;
-}