create-yss-spec 3.5.6 → 3.5.8

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

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

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

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

package/template/.agents/skills/yss-web-controller/SKILL.md

@@ -5,13 +5,17 @@ description: "按冻结合同与稳定 Application 接口生成或重构 YSS Con
 
 # yss-web-controller
 
-## 架构分流（先执行）
+## 任务分流
 
-读取当前合同的 architecture_identity 并与工程基线、仓库登记及 Manifest 核对；再且只读取 `references/profiles/<architecture_profile>.md`。生成式分支为 target-domain-model、layered-mvc-service、mvc-data-analysis-v1；既有工程分支为 existing-domain-driven-maven、existing-layered-mvc-maven。成熟度以注册表为准，不能把 draft 称为受支持。MVC 不执行下文 DDD 专属规则，也不加载其旧分层 guide；组件、安全、批准合同、允许路径及执行证据规则仍共用。
+- 只读审计读取实际入口和现有契约，缺用例 seam、契约或批准证据时记录缺口；不要求先补 Slice、生成 Manifest 或 metadata。
+- 既有整改消费批准且当前的 Slice、冻结 API/no-impact 与稳定用例 seam；缺必要输入回实现合同编译器补齐。
+- 仅新建 CRUD 要求 Web generation contract、metadata 并调用 initialize-only 生成器。认证、回调、Cookie、下载或流式接口可手工适配，不强制 CRUD 脚本或 metadata。
 
-以下 Application / Domain Gateway / Infrastructure / Web module 叙述仅适用于 target-domain-model；MVC 的 service/core/repository/server/client 所有权由所选 Profile 引用定义。
+## 架构分流
+
+将 `architecture_identity` 与当前工程基线和仓库登记核对；仅生成式来源核对脚手架 Manifest，既有来源使用登记及独立工程观测。再且只读取 `references/profiles/<architecture_profile>.md`。生成式分支为 target-domain-model、layered-mvc-service、mvc-data-analysis-v1；既有分支为 existing-domain-driven-maven、existing-layered-mvc-maven。成熟度以注册表为准，不能把 draft 称为受支持。MVC 不执行下文 DDD 专属规则，也不加载其分层 guide；组件、安全、批准合同、允许路径及执行证据规则共用。
 
-本 Skill 同时支持只读审计、既有整改和新建 CRUD 生成。审计读取实际入口和现有契约，缺证据只记录缺口；整改消费批准 Slice、冻结 API/no-impact 与稳定用例 seam；仅新建 CRUD 才要求 Web generation contract、metadata 并调用 initialize-only 生成器。
+以下 Application / Domain Gateway / Infrastructure / Web module 叙述仅适用于 target-domain-model；MVC 的 service/core/repository/server/client 所有权由所选 Profile 引用定义。
 
 ## 何时使用
 
@@ -19,46 +23,9 @@ description: "按冻结合同与稳定 Application 接口生成或重构 YSS Con
 - 用户要根据冻结 OpenAPI 字段合同、metadata 和稳定 Application 接口生成 Request / Response / Controller / WebConvertor。
 - 用户要求统一 Web Adapter 风格、返回值和接口路径。
 
-手工认证、回调、Cookie、下载或流式接口适用本 Skill，但不强制使用 CRUD 脚本或 metadata。
-
-## 实施前置与审计边界
-
-- 只读审计可以记录用例 seam 或契约缺失。既有整改缺少批准 Slice、稳定用例 seam 或接口契约时，回实现合同编译器补齐；仅新建 CRUD 生成要求 metadata，不因缺 metadata 拒绝既有代码审计或手工接口整改。
-
-## 新建 CRUD 生成流程
-
-1. 先确认冻结 OpenAPI、批准且版本当前的 Web generation contract schema v2、Application Service 接口、metadata、基础包、模块名、领域 segment 和 web 落盘目录；合同必须绑定 Slice `contract_id` / `contract_version` / `slice_id`、`yss-dto` wire profile 引用与 digest、允许写路径、证据与验证命令。
-2. 加载并遵守 `yss-dto` 与 `yss-validation`；错误映射影响命中时再加载 `yss-exception`。
-3. 涉及 DTO / VO / CMD / Query POJO 样板代码时，加载并遵守 `lombok`。
-4. 涉及 Domain / Application Result 到 VO / DTO 或 CMD / Query 到输入模型的转换时，加载并遵守 `mapstruct`。
-5. 运行 `node scripts/generate_controller.mjs`。
-6. 生成后检查路径、命名、返回值包装、Application Service 引用、`@Valid`、Lombok 注解和 MapStruct WebConvertor 是否对齐项目。
-7. 对复杂接口做少量手工修正，不在 skill 中承诺自动覆盖全部业务逻辑。
-
-## 推荐命令
-
-```bash
-node scripts/generate_controller.mjs \
-  --metadata-file /path/metadata.json \
-  --contract-file /path/approved-web-generation-contract.json \
-  --dto-wire-profile-file /path/to/yss-dto/references/openapi-wire-profile.yaml \
-  --scaffold-manifest-file /path/service/.yss/scaffold-generation.json \
-  --base-package com.yss.demo \
-  --module-name demo \
-  --domain-segment example \
-  --web-project-dir /path/demo-adapter/demo-web \
-  --application-service-package com.yss.demo.application.service \
-  --validation-namespace <resolved-platform-namespace>
-```
-
-## 输出预期
-
-- `rest/dto/request/*CreateRequest.java`
-- `rest/dto/request/*UpdateRequest.java`
-- `rest/dto/request/*PageRequest.java`
-- `rest/dto/response/*Response.java`
-- `rest/*Controller.java`
-- `rest/convertor/*WebConvertor.java`
+## 新建 CRUD 生成
+
+仅新建 CRUD 在输入齐备后必须读取 [生成流程与命令](references/crud-generation.md)，核验 schema v2 Web generation contract、metadata、绑定的 wire profile 与允许路径，再运行 initialize-only 生成器并检查完整输出。复杂接口仍按批准合同补足实现，不以生成成功替代行为验证。
 
 ## 约束
 

package/template/.agents/skills/yss-web-controller/references/crud-generation.md

@@ -0,0 +1,38 @@
+# 新建 CRUD 生成与核验
+
+仅在新建 CRUD 且入口的批准合同、冻结 API 与稳定用例 seam 已齐备时读取。只读审计、既有整改和手工协议适配不运行初始化生成器。以下命令从 Skill 根目录执行；参数消费当前合同与工程平台解析值，示例不授予写入或覆盖权限。
+
+## 新建 CRUD 生成流程
+
+1. 先确认冻结 OpenAPI、批准且版本当前的 Web generation contract schema v2、Application Service 接口、metadata、基础包、模块名、领域 segment 和 web 落盘目录；合同必须绑定 Slice `contract_id` / `contract_version` / `slice_id`、`yss-dto` wire profile 引用与 digest、允许写路径、证据与验证命令。
+2. 加载并遵守 `yss-dto` 与 `yss-validation`；错误映射影响命中时再加载 `yss-exception`。
+3. 涉及 DTO / VO / CMD / Query POJO 样板代码时，加载并遵守 `lombok`。
+4. 涉及 Domain / Application Result 到 VO / DTO 或 CMD / Query 到输入模型的转换时，加载并遵守 `mapstruct`。
+5. 运行 `node scripts/generate_controller.mjs`。
+6. 生成后检查路径、命名、返回值包装、Application Service 引用、`@Valid`、Lombok 注解和 MapStruct WebConvertor 是否对齐项目。
+7. 对复杂接口做少量手工修正，不在 skill 中承诺自动覆盖全部业务逻辑。
+
+## 推荐命令
+
+```bash
+node scripts/generate_controller.mjs \
+  --metadata-file /path/metadata.json \
+  --contract-file /path/approved-web-generation-contract.json \
+  --dto-wire-profile-file /path/to/yss-dto/references/openapi-wire-profile.yaml \
+  --scaffold-manifest-file /path/service/.yss/scaffold-generation.json \
+  --base-package com.yss.demo \
+  --module-name demo \
+  --domain-segment example \
+  --web-project-dir /path/demo-adapter/demo-web \
+  --application-service-package com.yss.demo.application.service \
+  --validation-namespace <resolved-platform-namespace>
+```
+
+## 输出预期
+
+- `rest/dto/request/*CreateRequest.java`
+- `rest/dto/request/*UpdateRequest.java`
+- `rest/dto/request/*PageRequest.java`
+- `rest/dto/response/*Response.java`
+- `rest/*Controller.java`
+- `rest/convertor/*WebConvertor.java`

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

@@ -33,7 +33,7 @@ description: "配置或修复 YSS UI YTable 的列表查询、列、分页、行
 - 行键使用 `:row-config="{ keyField: 'id', useKey: true }"`，不臆造 `row-key` Prop。
 - 新增、导入、批量操作等主按钮直接放入 `#toolbar-right` 或 `#toolbar-left` 插槽即可自动渲染工具栏；**无需配置 `:toolbar-config="{ custom: true }"`**，避免无端展示列设置图标；**仅在业务明确需要列设置时才传入 `:toolbar-config="{ custom: true }"`**。
 - 删除、启停、发布等危险操作使用 `actionConfig.buttons[].isConfirm = true`，不默认使用 `Modal.confirm`。
-- 列配置超过 10 行时放入 `constant.ts`；需要调用组件 Hook 的操作配置使用工厂函数注入回调，禁止在 `constant.ts` 直接引用组件局部的 `openEdit/deleteItem`。
+- 纯列配置集中到 `constant.ts`；需要调用组件 Hook 的操作配置使用工厂函数注入回调，禁止在 `constant.ts` 直接引用组件局部的 `openEdit/deleteItem`。按职责和依赖拆分，不用配置行数决定拆分。
 - 远程筛选必须提供稳定 `filters`，设置 `filterMethod: () => true` 禁用本地二次过滤，并监听 `filter-change`。
 - 自适应滚动列表绑定 `:height="tableHeight"`；`pageable`、工具栏分别对应 `withPagination: true`、`withToolbar: true`。纯短表不强制引入高度 Hook。
 - `mutator.ts` 已对网络错误和 `success === false` 统一 `message.error` 并 reject。API Hook 不再检查 `success === false`，不在 `else/catch` 重复 `message.error`；用 `finally` 恢复 loading，让异常继续中断流程。
@@ -55,7 +55,7 @@ description: "配置或修复 YSS UI YTable 的列表查询、列、分页、行
 ## 交付检查清单
 
 - [ ] 分页状态和 `page-change` 参数均使用 `current/pageSize`，未使用 `currentPage`；`filter-change` 与 YTable 真实 API 一致。
-- [ ] 多选列已配置 `type: 'checkbox'`，已设置 `:row-config="{ keyField: 'xxx', useKey: true }"`，批量按钮绑定了 `selectedRowKeys.length === 0` 禁用。
+- [ ] 启用多选时，列已配置 `type: 'checkbox'`，已设置 `:row-config="{ keyField: 'xxx', useKey: true }"`，批量按钮绑定了 `selectedRowKeys.length === 0` 禁用。
 - [ ] 批量成功后，所有实际受控选择字段与表格可见勾选均已清空；内部缓存存在时已通过 `clearSelection()` 清除。
 - [ ] 未使用虚构 `request/searchParams/row-key` Props，也未把 `refresh()` 当成远程请求。
 - [ ] 工具栏、字典翻译、操作确认与高度偏移均与实际开关一致。

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

@@ -36,87 +36,9 @@ description: "配置或修复 YSS UI YTree 的字段映射、搜索、选中与
 - 左树右表优先组合 `YSplitPane + YCard + YTree + YTable`；切换节点时同步查询条件并把右表分页重置为第 1 页。
 - 节点删除 API 的错误由 `mutator.ts` 统一提示并 reject；不在 `else/catch` 重复 `message.error`。
 
-## 标准代码骨架
+## 按需示例
 
-```vue
-<script setup lang="ts">
-import { ref } from 'vue';
-import { YTree, type YTreeActionItem } from '@yss-ui/components';
-import { useTreeHeight, YTREE_SEARCH_HEIGHT } from '@yss-ui/hooks';
-
-/** 树节点数据。 */
-interface TreeNode {
-  id: string;
-  name: string;
-  children?: TreeNode[];
-}
-
-const emit = defineEmits<{
-  create: [node: TreeNode];
-  edit: [node: TreeNode];
-}>();
-const treeAreaRef = ref<HTMLDivElement>();
-const treeData = ref<TreeNode[]>([]);
-const searchValue = ref('');
-const selectedKeys = ref<Array<string | number>>([]);
-const { treeHeight } = useTreeHeight(treeAreaRef, {
-  extraOffset: YTREE_SEARCH_HEIGHT,
-});
-
-/** 生成当前节点的非危险操作。 */
-const getNodeActions = (): YTreeActionItem[] => [
-  { key: 'add', label: '新增子节点' },
-  { key: 'edit', label: '编辑' },
-];
-
-/** 处理 YTree 动作事件。 */
-const handleTreeAction = ({ key, node }: { key: string; node: TreeNode }) => {
-  if (key === 'add') emit('create', node);
-  if (key === 'edit') emit('edit', node);
-};
-</script>
-
-<template>
-  <div ref="treeAreaRef" class="tree-area">
-    <YTree
-      :height="treeHeight"
-      :tree-data="treeData"
-      :field-names="{ title: 'name', key: 'id', children: 'children' }"
-      filterable
-      show-actions
-      v-model:searchValue="searchValue"
-      v-model:selectedKeys="selectedKeys"
-      :get-node-actions="getNodeActions"
-      @action="handleTreeAction"
-    />
-  </div>
-</template>
-
-<style scoped lang="less">
-@import './style.less';
-</style>
-```
-
-```less
-/* style.less */
-.tree-area {
-  flex: 1;
-  min-height: 0;
-  overflow: hidden;
-}
-```
-
-## 删除确认边界
-
-```vue
-<template #node-suffix="{ node }">
-  <Popconfirm title="确认删除该节点吗？" ok-text="确定" cancel-text="取消" @confirm="handleDelete(node)">
-    <YButton type="link" @click.stop>删除</YButton>
-  </Popconfirm>
-</template>
-```
-
-`Popconfirm` 从 `ant-design-vue` 导入，`YButton` 从 `@yss-ui/components` 导入。如果每个节点都展示删除会过密，把同样的 `Popconfirm` 放到选中节点的页面工具栏。
+首次组合受控树、高度与节点动作，或实现删除确认时，读取 [树与删除确认示例](references/tree-and-confirmation-example.md)。简单字段映射修改无需加载整段示例。
 
 ## 交付检查清单
 

package/template/.agents/skills/ytree-usage/references/tree-and-confirmation-example.md

@@ -0,0 +1,81 @@
+## 标准代码骨架
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { YTree, type YTreeActionItem } from '@yss-ui/components';
+import { useTreeHeight, YTREE_SEARCH_HEIGHT } from '@yss-ui/hooks';
+
+/** 树节点数据。 */
+interface TreeNode {
+  id: string;
+  name: string;
+  children?: TreeNode[];
+}
+
+const emit = defineEmits<{
+  create: [node: TreeNode];
+  edit: [node: TreeNode];
+}>();
+const treeAreaRef = ref<HTMLDivElement>();
+const treeData = ref<TreeNode[]>([]);
+const searchValue = ref('');
+const selectedKeys = ref<Array<string | number>>([]);
+const { treeHeight } = useTreeHeight(treeAreaRef, {
+  extraOffset: YTREE_SEARCH_HEIGHT,
+});
+
+/** 生成当前节点的非危险操作。 */
+const getNodeActions = (): YTreeActionItem[] => [
+  { key: 'add', label: '新增子节点' },
+  { key: 'edit', label: '编辑' },
+];
+
+/** 处理 YTree 动作事件。 */
+const handleTreeAction = ({ key, node }: { key: string; node: TreeNode }) => {
+  if (key === 'add') emit('create', node);
+  if (key === 'edit') emit('edit', node);
+};
+</script>
+
+<template>
+  <div ref="treeAreaRef" class="tree-area">
+    <YTree
+      :height="treeHeight"
+      :tree-data="treeData"
+      :field-names="{ title: 'name', key: 'id', children: 'children' }"
+      filterable
+      show-actions
+      v-model:searchValue="searchValue"
+      v-model:selectedKeys="selectedKeys"
+      :get-node-actions="getNodeActions"
+      @action="handleTreeAction"
+    />
+  </div>
+</template>
+
+<style scoped lang="less">
+@import './style.less';
+</style>
+```
+
+```less
+/* style.less */
+.tree-area {
+  flex: 1;
+  min-height: 0;
+  overflow: hidden;
+}
+```
+
+## 删除确认边界
+
+```vue
+<template #node-suffix="{ node }">
+  <Popconfirm title="确认删除该节点吗？" ok-text="确定" cancel-text="取消" @confirm="handleDelete(node)">
+    <YButton type="link" @click.stop>删除</YButton>
+  </Popconfirm>
+</template>
+```
+
+`Popconfirm` 从 `ant-design-vue` 导入，`YButton` 从 `@yss-ui/components` 导入。如果每个节点都展示删除会过密，把同样的 `Popconfirm` 放到选中节点的页面工具栏。

package/template/.codex/skills/alibaba-java-code-style/SKILL.md

@@ -3,50 +3,44 @@ name: alibaba-java-code-style
 description: 应用阿里巴巴 Java 手册审查或实现 Java 代码；按当前项目框架与数据库基线选择适用规范。
 ---
 
-# Alibaba Java Code Style
+# 阿里巴巴 Java 规范
 
-This skill distills the provided `阿里巴巴 Java 开发手册` 1.4.0 PDF into execution rules for Codex. Treat rules marked mandatory as review blockers unless the repository's own `AGENTS.md`, security constraints, or existing framework conventions explicitly require a different pattern.
+本 Skill 从用户提供的《阿里巴巴 Java 开发手册》1.4.0 提炼适用规范。`mandatory` 违规阻断审查，除非仓库 `AGENTS.md`、安全约束或现有框架约定明确要求不同模式；例外须有依据。`recommended` / `reference` 保留建议等级，不因进入下文检查提要变为强制规则。
 
-## Workflow
+## 工作流
 
-1. Identify the touched surface:
-   - Java source, naming, constants, OOP, collections, concurrency, control flow, comments: read `references/java-programming.md`.
-   - Exceptions, logging, unit tests, or security: read `references/reliability-test-security.md`.
-   - MySQL, ORM/MyBatis, Maven dependencies, layering, server/JVM settings, or design artifacts: read `references/database-engineering-design.md`.
-2. Apply mandatory rules first, then use recommended rules to improve maintainability, performance, and readability.
-3. When reviewing, report mandatory violations as findings. Mention recommended violations when they create real risk or are already in the changed area.
-4. When implementing, prefer the repository's existing framework helpers and code generation skills over inventing new local infrastructure.
-5. For auth, payment, encryption, SQL, migrations or public-library changes, check the current contract and actual authorization. Continue an already authorized repair with its required verification; produce a draft or `TODO-HUMAN-REVIEW` only for a real missing decision or approval, and identify that gap.
+1. 按影响面读取对应规范：Java 命名、常量、OOP、集合、并发、控制流和注释读 [Java 编程](references/java-programming.md)；异常、日志、测试或安全读 [可靠性与安全](references/reliability-test-security.md)；MySQL、ORM/MyBatis、Maven、分层、服务器/JVM 或设计资产读 [工程与数据库](references/database-engineering-design.md)。
+2. 先执行适用 mandatory，再按实际风险采用 recommended；审查报告保留规则等级。建议仅在产生真实风险或处于本次范围时报告。
+3. 实现优先复用工程框架与已有生成能力，不新增重复基础设施。
+4. 认证、付款、加密、SQL、迁移或公共库变更先核验当前合同及实际授权。已授权修复继续完成适用验证；仅真实缺决定或批准时形成草案 / `TODO-HUMAN-REVIEW`，并说明缺口。
 
-## Core Priorities
+## 适用原则
 
 - 先消费 architecture_identity 与工程 Java/数据库基线。MVC 分层按 `.template-spec/agents/backend-architecture-profiles.md`；MySQL 专属方言规则仅对批准的 MySQL 存储生效，不能要求 H2 骨架引入 MySQL 驱动。YSS 包装、命名及处理器差异逐项记录基线例外，安全、权限、敏感信息与 SQL 参数绑定不得豁免。
-- Keep names readable, English, and consistent with Java layer conventions.
-- Avoid null, equality, wrapper comparison, collection, and concurrency traps that compile cleanly but fail at runtime.
-- Make logs useful without wasting CPU, disk, or alert budget.
-- Keep unit tests automatic, independent, repeatable, and close to public behavior.
-- Bind SQL parameters, define explicit ORM mappings, and never rely on string-concatenated SQL.
-- Preserve layering: web/controller code validates and adapts; service/manager code owns business orchestration; DAO/repository code owns persistence.
-
-## Review Checklist
-
-- Naming and formatting are consistent: camel case, constants, package names, braces, spacing, line length, UTF-8/Unix line endings.
-- POJO, DTO, DO, VO, Query, enum, interface, implementation, and test names follow the expected suffixes and boolean naming rules.
-- `equals`, `hashCode`, wrapper comparisons, `toString`, `serialVersionUID`, constructors, access modifiers, and getters/setters avoid known pitfalls.
-- Collection code avoids unsafe `subList`, `Arrays.asList`, raw `toArray`, foreach removal, null-unsafe maps, and invalid comparators.
-- Thread code uses named thread pools, avoids `Executors` factories in production code, and handles locking order, date formatting, and scheduled tasks safely.
-- Exceptions are handled at the right layer, logged once with context and stack, and never swallowed or used for normal control flow.
-- Tests use assertions, avoid external dependence, live under `src/test/java`, and cover boundaries, correct cases, design cases, and error cases.
-- Security-sensitive inputs are validated, authorized, escaped, CSRF-protected, rate-limited, and never concatenated into SQL.
-- MySQL DDL/SQL/ORM code uses explicit fields, mappings, indexes, timestamps, `#{}`
-  parameter binding, and avoids dangerous cascades, stored procedures, `select *`, and uncontrolled pagination.
-
-## Source
-
-Based on the user-provided PDF: `阿里巴巴 Java 开发手册` version 1.4.0, Alibaba Group technical team, update date 2018-05-20.
+- 名称使用清晰英文标识并遵循当前 Java 分层约定。
+- 核验 null、相等、包装类型比较、集合和并发的运行时边界，不能以编译通过代替行为正确。
+- 日志有诊断用途，并控制 CPU、磁盘和告警成本。
+- 单元测试自动、独立、可重复，围绕公开行为验证。
+- SQL 使用参数绑定与显式 ORM 映射，不依赖字符串拼接。
+- 按已登记架构保持职责：Web/controller 校验和适配，service/manager 编排业务，DAO/repository 持有持久化。
+
+## 检查提要
+
+- 命名与格式：camel case、常量、包名、括号、间距、行长、UTF-8/Unix 换行；类型后缀和 boolean 命名符合适用规范。
+- 对象语义：`equals/hashCode`、包装类型比较、`toString`、`serialVersionUID`、构造器、可见性和访问器。
+- 集合：`subList`、`Arrays.asList`、`toArray`、foreach 删除、null map 和 comparator 的边界。
+- 并发：命名线程池、生产 `Executors` 工厂限制、锁顺序、日期格式和定时任务。
+- 异常：正确分层、上下文与堆栈、避免重复日志、不吞异常、不用于普通控制流。
+- 测试：断言、外部依赖隔离、`src/test/java` 与边界/正确/设计/错误场景。
+- 安全：按真实输入与认证方式核验校验、授权、转义、CSRF、限流和 SQL 参数绑定，不能泛用某项检查豁免其他风险。
+- MySQL：仅适用存储核验显式字段、映射、索引、时间戳与 `#{}` 绑定，以及危险级联、存储过程、`select *` 和分页边界。
+
+## 来源
+
+用户提供的《阿里巴巴 Java 开发手册》1.4.0，阿里巴巴集团技术团队，更新于 2018-05-20；具体条款等级保留在对应 references 中。
 
 ## 阶段 7 执行结果
 
 - 消费当前合同版本、changed files 和 verification results，只审查合同允许范围。
-- 必须把 mandatory violation 返回为 `violation`，并提供文件/位置/规则证据；高风险项保留 `TODO-HUMAN-REVIEW`。
+- 适用 mandatory violation 返回 `violation`，附文件/位置/规则证据；高风险项仅在当前合同确有未满足人工决定或批准要求时保留 `TODO-HUMAN-REVIEW`。
 - 按统一 `YSS Skill Execution Result` 返回审查证据、偏离和新增安全/SQL/公共 API 影响，不得仅输出“符合规范”。

package/template/.codex/skills/archify/SKILL.md

@@ -25,10 +25,10 @@ When the current repository contains `yss-project.yaml`, these rules override th
   node .agents/skills/archify/scripts/yss-safe-deliver.mjs <type> docs/architecture/diagrams/<diagram-id>/<diagram-id>.archify.json docs/architecture/diagrams/<diagram-id>/<diagram-id>.html --quality showcase
 
   # template-source
-  node .agents/skills/archify/scripts/yss-safe-deliver.mjs <type> .template-source/evidence/maintenance/diagrams/<diagram-id>/<diagram-id>.archify.json .template-source/evidence/maintenance/diagrams/<diagram-id>/<diagram-id>.html --quality showcase
+  node .agents/skills/archify/scripts/yss-safe-deliver.mjs <type> "$(scripts/maintenance-path diagrams/<diagram-id>/<diagram-id>.archify.json)" "$(scripts/maintenance-path diagrams/<diagram-id>/<diagram-id>.html)" --quality showcase
   ```
 
-- For a `project-instance`, stable source and output must be the matching pair `docs/architecture/diagrams/<diagram-id>/<diagram-id>.archify.json` and `<diagram-id>.html`. For a `template-source`, use `.template-source/evidence/maintenance/diagrams/<diagram-id>/`. The wrapper writes `<diagram-id>.receipt.json` only after successful delivery. Temporary exploration may target the operating-system temporary directory.
+- For a `project-instance`, stable source and output must be the matching pair `docs/architecture/diagrams/<diagram-id>/<diagram-id>.archify.json` and `<diagram-id>.html`. For a `template-source`, use the current workspace's external `maintenance:diagrams/<diagram-id>/` (resolve with `scripts/maintenance-path`). The wrapper writes `<diagram-id>.receipt.json` only after successful delivery. Temporary exploration may target the operating-system temporary directory.
 - The safe wrapper rejects `--open`, non-HTML targets, symlink escapes, unrelated existing files, and stable source/output pairs outside those roots. Do not bypass it with the raw `deliver` or `preview` commands in a YSS repository.
 
 ## Fast authoring path

package/template/.codex/skills/archify/scripts/yss-safe-deliver.mjs

@@ -4,7 +4,7 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
 const skillRoot = path.resolve(scriptDirectory, '..');
@@ -93,11 +93,12 @@ function assertReplaceableReceipt(receipt) {
   if (parsed?.yssArchifyReceipt !== true) fail(`拒绝覆盖非 YSS Archify receipt: ${receipt}`);
 }
 
-function stableContract(projectRoot, mode, input, output) {
+async function stableContract(projectRoot, mode, input, output) {
   const relativeBase = mode === 'project-instance'
     ? 'docs/architecture/diagrams'
-    : '.template-source/evidence/maintenance/diagrams';
-  const base = path.join(projectRoot, relativeBase);
+    : 'maintenance:diagrams';
+  const base = mode === 'project-instance' ? path.join(projectRoot, relativeBase)
+    : (await import(pathToFileURL(path.join(projectRoot, 'scripts/lib/maintenance-storage.mjs')).href)).resolveMaintenanceOutput(relativeBase, { root: projectRoot });
   const relativeOutput = path.relative(base, output);
   const segments = relativeOutput.split(path.sep);
   if (segments.length !== 2 || !diagramIdPattern.test(segments[0])) {
@@ -139,7 +140,10 @@ const temporaryBase = fs.realpathSync(os.tmpdir());
 // parent symlink resolves into the OS temporary directory. Otherwise the
 // temporary-delivery exception could be used to escape the stable output root.
 const requestedWithinProject = requestedProjectRoot !== null;
-const isTemporary = !requestedWithinProject && isWithin(temporaryBase, output);
+const projectMode = projectRoot ? repositoryMode(projectRoot) : null;
+const templateDiagramBase = projectMode === 'template-source'
+  ? (await import(pathToFileURL(path.join(projectRoot, 'scripts/lib/maintenance-storage.mjs')).href)).resolveMaintenanceOutput('maintenance:diagrams', { root: projectRoot }) : null;
+const isTemporary = !requestedWithinProject && isWithin(temporaryBase, output) && !(templateDiagramBase && isWithin(templateDiagramBase, output));
 let mode = null;
 let receipt;
 let allowedBase;
@@ -150,7 +154,7 @@ if (isTemporary) {
 } else {
   if (!projectRoot) fail('稳定交付必须从包含 yss-project.yaml 的仓库内运行');
   mode = repositoryMode(projectRoot);
-  const contract = stableContract(projectRoot, mode, input, output);
+  const contract = await stableContract(projectRoot, mode, input, output);
   allowedBase = contract.base;
   receipt = contract.receipt;
 }