create-yss-spec 2.2.0 → 2.2.2

package/template/.agents/skills/frontend-commit/references/scope-and-examples.md

@@ -0,0 +1,111 @@
+# 前端 Type、Scope 与示例
+
+## 目录
+
+- [规则优先级](#规则优先级)
+- [Type 选择](#type-选择)
+- [Scope 选择](#scope-选择)
+- [原子提交边界](#原子提交边界)
+- [消息示例](#消息示例)
+- [前端验证](#前端验证)
+- [规范依据](#规范依据)
+
+## 规则优先级
+
+1. 仓库 commitlint 的 resolved config 和 hooks。
+2. 仓库 `AGENTS.md`、`CONTRIBUTING.md`、提交模板及明确文档。
+3. 当前 monorepo 的包或应用名称，以及目标路径近期的有效提交。
+4. 本参考的通用回退规则。
+
+仓库允许空 scope 时仍优先使用能帮助团队定位业务影响的 scope；跨全仓且没有清晰主域时可以省略。只有 commitlint 明确支持且团队历史稳定使用时才采用多 scope。
+
+## Type 选择
+
+| Type | 使用条件 | 不要用于 |
+|---|---|---|
+| `feat` | 增加用户、调用方或运维人员可感知的能力 | 纯重构或依赖升级 |
+| `fix` | 修复错误、回归、异常状态或不符合预期的行为 | 仅格式化代码 |
+| `docs` | 只修改文档 | 代码行为变化 |
+| `style` | 仅空格、格式、分号等，不改变语义 | UI 样式或视觉功能变更 |
+| `refactor` | 不增功能、不修 bug 的结构调整 | 性能优化或行为修复 |
+| `perf` | 有明确性能收益的代码变化 | 无证据的“优化”措辞 |
+| `test` | 只增加或修正测试 | 功能代码及其配套测试 |
+| `build` | 构建系统、外部依赖、打包或编译配置 | 一般业务配置 |
+| `ci` | CI/CD 配置和流水线脚本 | 本地构建配置 |
+| `chore` | 其他不改变产品行为的维护工作 | 无法理解改动时的兜底 |
+| `revert` | 明确回滚一个或多个既有提交 | 普通修复 |
+
+## Scope 选择
+
+按以下顺序选择首个清晰候选：
+
+1. **仓库限定值**：若 `scope-enum` 生效，只能使用允许值或按规则省略。
+2. **monorepo 包或应用**：`apps/admin-portal` 使用 `admin-portal`；`packages/design-system` 使用 `design-system`。
+3. **业务模块**：`views/DataPush`、相关 API、hook 和测试共同实现推送任务时使用 `data-push`，不使用 `views`。
+4. **共享能力**：确实跨业务复用时使用 `auth`、`router`、`store`、`i18n`、`api-client`、`design-system` 等已有名称。
+5. **工程边界**：依赖升级可用 `deps`，构建和 CI 可用 `build`、`ci`；scope 不应重复无意义信息。
+
+命名使用小写 kebab-case。优先采用仓库或产品已有术语，不自行翻译稳定模块名。`components`、`hooks`、`utils`、`views`、`index` 和具体文件名通常信息不足，只有它们本身就是对外包或仓库既定 scope 时才使用。
+
+## 原子提交边界
+
+- 同一功能的页面、API 适配、状态逻辑、测试和最小测试配置可以同提交。
+- `package.json` 与对应 lockfile 必须同提交；与业务功能无关的批量依赖升级单独使用 `build(deps)`。
+- 生成 API 客户端和消费端若共同实现同一契约能力，可按业务域提交；无关的大规模重新生成必须拆分。
+- 顺手格式化、调试日志、个人 IDE 配置和无关文件不要混入。
+- 两个独立业务模块或不同发布风险的改动应拆分；同一文件内无法安全分离时先请求用户决定。
+
+## 消息示例
+
+```text
+feat(data-push): 优化推送任务数据源与调度规则展示
+
+- 将英文星期转换为中文调度描述
+- 按数据源目录映射业务名称并补充单元测试
+```
+
+```text
+fix(auth): 修复令牌刷新并发请求重复跳转登录的问题
+
+- 复用进行中的刷新请求，避免多个失败响应重复触发跳转
+- 保持刷新失败后的退出流程不变
+```
+
+```text
+build(deps): 升级 Vue 与类型检查工具链
+```
+
+```text
+feat(api-client)!: 统一分页响应字段命名
+
+- 将列表响应统一为 items 和 total
+- 更新调用方与契约测试
+
+BREAKING CHANGE: 原 records 字段改为 items，所有自定义适配器需同步迁移
+```
+
+错误与修正：
+
+| 错误 | 修正方向 |
+|---|---|
+| `fix：修复问题` | 使用 ASCII 冒号并说明具体行为 |
+| `fixL 新增下载` | 选择合法 type，例如 `feat(download): 支持导出任务文件` |
+| `fix: useDataPushTasks.ts` | 描述修复结果，而不是文件名 |
+| `feat(views): 新增用户管理` | 优先使用 `feat(user-management): ...` |
+| `chore: 修改代码` | 先理解真实意图，再选择准确 type 和摘要 |
+
+## 前端验证
+
+- 根据 lockfile 选择 `pnpm`、`npm`、`yarn` 或 `bun`，优先运行 `package.json` 已有脚本。
+- 功能或修复至少运行相关测试；类型相关变更运行 type-check；lint、format 只使用不会意外重写无关文件的检查模式。
+- monorepo 优先运行受影响包的过滤命令，除非仓库要求全量检查。
+- 不把“hook 会跑”当作跳过必要验证的理由；也不要编造不存在的脚本。
+
+## 规范依据
+
+- [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
+- [commitlint：AI Agents](https://commitlint.js.org/guides/ai-agents.html)
+- [commitlint 官方 committing-with-commitlint skill](https://github.com/conventional-changelog/commitlint/tree/master/skills/committing-with-commitlint)
+- [Angular Commit Message Guidelines](https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md)
+- [Git SubmittingPatches](https://git-scm.com/docs/SubmittingPatches)
+

package/template/.agents/skills/java-backend-commit/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: java-backend-commit
+description: 分析并提交 Java、Spring Boot、Maven、Gradle、单体服务和多模块后端项目的 Git 改动；当用户要求生成 commit message、检查提交规范、拆分原子提交、暂存并执行 git commit，或修复 commitlint 与 commit-msg hook 拒绝时使用。读取仓库实际规则、模块结构和 diff，选择服务或业务域 scope，生成英文 type/scope 与中文标题和正文，并安全验证提交。
+---
+
+# Java 后端规范提交
+
+## 触发条件
+
+- 用户要求为 Java 后端项目生成 commit message、检查提交规范或执行 `git commit`。
+- 需要将跨层改动（接口、领域、持久化、迁移、测试）拆分为可独立构建和回滚的原子提交。
+- commitlint、`commit-msg` 或 `pre-commit` hook 拒绝提交，需要按规则修复。
+- 适用于 Java、Spring Boot、Maven、Gradle、单体服务和多模块后端仓库。
+
+## 不适用场景
+
+- Vue、React 等前端或微前端仓库：使用 `../frontend-commit/SKILL.md`。
+- yss-ui 组件库仓库自身的提交与发版：使用 `../commit-linting/SKILL.md`。
+- 仅请求代码实现，不涉及提交信息或 `git commit` 操作。
+- 无代码改动，或改动内容与提交请求不匹配。
+- 合并提交、发布提交、自动依赖机器人提交和数据库基线发布：遵循仓库专用流程，不套用本技能的常规模板。
+
+## 硬约束（禁止/必须）
+
+- 必须把仓库规则视为最高优先级：依次遵循 `AGENTS.md`、`CONTRIBUTING.md`、Git hooks、解析后的 commitlint 配置、本地配置和近期历史；通用规则只作回退。
+- 只在用户明确要求提交时执行暂存和 `git commit`；若仅要求提交信息或审查，只输出候选消息与依据。
+- 必须保留用户和他人的既有改动。禁止默认使用 `git add -A`、`git add .`、`git commit -a`、`--no-verify`，也不要自动 amend、rebase、push 或改写已发布历史。
+- 提交必须是可独立理解、构建和回滚的逻辑变更。不要按 `controller/service/repository` 技术分层拆成无法工作的提交。
+- 遇到密钥、令牌、私钥、证书、keystore、生产口令、`.env` 实值或意外大文件时停止提交并报告具体路径，不要在输出中泄露内容。
+- 已有暂存内容视为用户选择，除非用户授权，不要擅自取消暂存或混入其他文件。
+- 不提交 `target/`、`build/`、IDE 缓存、日志或本地运行产物。只提交项目本来就跟踪且由本次意图产生的生成源码。
+- 已在共享环境执行的版本化数据库迁移（Flyway、Liquibase）通常不可重写；发现修改既有迁移时先报告风险。
+- `fixup!` 只用于用户明确要求的评审或 autosquash 工作流；revert 优先使用 Git 生成的回滚信息并保留被回滚 SHA，不要把普通反向修改伪装成 revert。
+
+## 工作流
+
+### 1. 建立仓库契约
+
+1. 确认仓库根目录、当前分支和工作树状态。
+2. 搜索并读取仓库级说明、贡献指南、提交模板、commitlint 配置和 `commit-msg`、`pre-commit` hooks。
+3. 读取根 `pom.xml`、`settings.gradle` 或 `settings.gradle.kts` 以及相关模块构建文件，确认 Maven `artifactId`、Gradle 子项目、服务和限界上下文。
+4. 如果仓库使用 commitlint，优先使用本地依赖读取解析后的配置；不要为了校验联网安装依赖。没有 Node 工具时，直接读取 hook 和配置文件并按仓库命令验证。
+5. 查看相关模块近期的非 merge 提交，了解仓库已经形成的 scope、工单 footer、DCO 和语言习惯，但不要复制历史中的明显错误。
+
+### 2. 审查真实改动
+
+至少检查：
+
+```bash
+git status --short --branch
+git diff --cached --name-status
+git diff --cached
+git diff --name-status
+git diff
+git ls-files --others --exclude-standard
+```
+
+- 同时理解暂存区、未暂存区和未跟踪文件；结合 API、领域模型、持久化、配置和测试判断真实行为。
+- 将同一业务能力所需的接口、应用服务、领域逻辑、持久化、迁移和测试作为候选原子单元，而不是按目录机械拆分。
+- 检查 Flyway、Liquibase 等数据库变更是否触碰既有版本化迁移。
+- 若无改动、改动与请求不符、多个逻辑变更无法安全拆分，先说明并停止。需要逐行拆分同一文件时，不要靠猜测改写暂存区。
+
+### 3. 选择 type、scope 与正文
+
+先读取 `./references/scope-and-examples.md`，再按「标准代码骨架」的格式生成。
+
+- type 默认从 `feat/fix/docs/style/refactor/perf/test/chore/revert/build/ci` 中选择，但仓库枚举优先。
+- scope 优先级为：仓库枚举 → Maven artifactId 或 Gradle 子项目 → 服务或限界上下文 → 跨模块能力。使用小写 kebab-case；不要仅使用 `controller`、`service`、`repository` 或类名。
+- 标题使用英文 type/scope、ASCII `:` 和中文摘要；描述业务、调用方或运维可感知的结果，不写“修改代码”或单个 Java 类名。
+- 默认将完整 header 控制在 72 个字符内；仓库存在更严格限制时服从仓库。标题末尾不加句号，不用 emoji 或全角冒号。
+- 简单单文件变更可以没有 body；跨层实现、数据迁移、并发或事务修复、重要功能和行为变化使用 body 解释做了什么、为什么以及如何验证。
+- REST/GraphQL/RPC 契约、事件格式、公共 Java API、配置语义或数据库兼容性发生真实破坏时，使用 `!` 和 `BREAKING CHANGE:` 并写迁移方式。
+- 仅在已知编号或仓库要求时加入工单、DCO、`Signed-off-by` 等 footer，禁止编造；不要因为 Spring 项目采用 DCO 就推断所有 Java 项目都必须签署。
+
+### 4. 验证并提交
+
+1. 优先使用仓库 wrapper：Maven 使用 `./mvnw`，Gradle 使用 `./gradlew`；根据模块和变更运行已有的最小充分测试、编译、静态检查和格式检查。
+2. 通过仓库已有命令校验完整候选消息。commitlint 存在时使用 stdin 校验 header、body 和 footer；退出码为 0 才继续。
+3. 仅暂存属于当前原子提交的明确路径或安全 hunks，再重新检查 `git diff --cached --check`、`--name-status` 和完整 staged diff。
+4. 执行正常 `git commit`，允许 hooks 运行。
+5. hook 若格式化或修改文件，重新检查 staged 与 working tree，确认实际提交内容没有漂移。
+6. 提交成功后检查 `git show --stat --oneline --decorate HEAD` 和 `git status --short`，向用户报告 commit hash、消息、已运行检查以及剩余未提交改动。
+
+## 标准代码骨架
+
+```text
+type(scope)!: 中文行为摘要
+
+- 说明关键行为或原因
+- 说明兼容性、迁移、测试或必要约束
+
+BREAKING CHANGE: 说明不兼容影响和迁移方式
+Refs: 已知工单号
+```
+
+示例：
+
+```text
+fix(settlement): 修复重复回调导致结算流水重复入账的问题
+
+- 使用业务幂等键拦截已处理回调
+- 保留失败回调的可重试能力
+```
+
+## 交付检查清单
+
+- [ ] type 与 scope 通过仓库校验规则，完整消息经仓库命令校验通过。
+- [ ] scope 来自仓库枚举、构建模块或业务域，未使用 `controller`、`service`、`repository` 或类名兜底。
+- [ ] 标题为英文 type/scope + ASCII 冒号 + 中文摘要，完整 header 不超过 72 字符。
+- [ ] 提交可独立理解、构建和回滚；数据库迁移与对应实体、查询和测试同提交。
+- [ ] 暂存区不包含 `target/`、`build/`、日志或本地运行产物。
+- [ ] 已使用仓库 wrapper 运行与变更范围匹配的最小充分检查。
+- [ ] 提交后已核对 `git show --stat` 与 `git status --short`，并向用户报告 hash 与剩余改动。
+
+## 失败兜底策略
+
+- 无法区分 `feat`、`fix`、`refactor` 时继续检查需求和行为；仍有高影响歧义则询问用户，不自动降级为 `chore`。
+- hook 拒绝时按输出修正并重新校验，绝不使用 `--no-verify`。
+- 仓库 parser 或 hook 不支持标准破坏性标记时，不要绕过校验或静默删掉标记；报告规则冲突，并采用仓库明确批准的兼容方案。
+- 两个独立业务域或不同发布风险的改动无法安全拆分时，先给出拆分方案并停止；同一文件内无法分离时请求用户决定。
+- 发现修改既有版本化迁移、密钥或意外大文件时停止提交，报告具体路径并等待用户处理。

package/template/.agents/skills/java-backend-commit/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Java 后端规范提交"
+  short_description: "分析真实改动并生成、校验 Java 后端项目的规范化 Git 提交"
+  default_prompt: "使用 $java-backend-commit 检查当前 Java 后端改动并创建一条规范、原子的 Git 提交。"
+
+policy:
+  allow_implicit_invocation: true

package/template/.agents/skills/java-backend-commit/references/scope-and-examples.md

@@ -0,0 +1,118 @@
+# Java 后端 Type、Scope 与示例
+
+## 目录
+
+- [规则优先级](#规则优先级)
+- [Type 选择](#type-选择)
+- [Scope 选择](#scope-选择)
+- [原子提交边界](#原子提交边界)
+- [消息示例](#消息示例)
+- [Java 验证](#java-验证)
+- [规范依据](#规范依据)
+
+## 规则优先级
+
+1. 仓库 commitlint 的 resolved config 和 hooks。
+2. 仓库 `AGENTS.md`、`CONTRIBUTING.md`、提交模板及明确文档。
+3. Maven/Gradle 模块定义、稳定业务术语及目标路径近期的有效提交。
+4. 本参考的通用回退规则。
+
+仓库允许空 scope 时仍优先使用能说明服务或业务域的 scope；跨全仓且没有清晰主域时可以省略。只有仓库明确要求时才添加工单 footer、DCO 或签名。
+
+## Type 选择
+
+| Type | 使用条件 | 不要用于 |
+|---|---|---|
+| `feat` | 新增 API、业务能力、运维能力或可用配置 | 纯重构或依赖升级 |
+| `fix` | 修复错误结果、异常、回归、事务或并发缺陷 | 仅格式化代码 |
+| `docs` | 只修改文档或 Javadoc | 代码行为变化 |
+| `style` | 仅格式、空格、导入排序等，不改变语义 | 接口或 UI 风格变化 |
+| `refactor` | 不增功能、不修 bug 的结构调整 | 性能优化或行为修复 |
+| `perf` | 有明确性能收益的代码或查询变化 | 无证据的“优化”措辞 |
+| `test` | 只增加或修正测试 | 功能代码及其配套测试 |
+| `build` | Maven/Gradle、依赖、插件、打包或编译配置 | 一般业务配置 |
+| `ci` | CI/CD 配置和流水线脚本 | 本地构建配置 |
+| `chore` | 其他不改变产品行为的维护工作 | 无法理解改动时的兜底 |
+| `revert` | 明确回滚一个或多个既有提交 | 普通修复 |
+
+## Scope 选择
+
+按以下顺序选择首个清晰候选：
+
+1. **仓库限定值**：若 `scope-enum` 生效，只能使用允许值或按规则省略。
+2. **构建模块**：Maven 使用稳定的 `artifactId`，Gradle 使用子项目名，例如 `order-service`、`risk-engine`。
+3. **服务或限界上下文**：单模块项目按稳定业务域使用 `order`、`customer`、`settlement`、`valuation` 等名称。
+4. **跨模块能力**：确实横跨业务域时使用仓库已有的 `api`、`db`、`security`、`messaging`、`observability`、`deps`、`build` 或 `ci`。
+
+命名使用小写 kebab-case。优先采用 `pom.xml`、Gradle settings、包名和产品文档中的既有术语。`controller`、`service`、`repository`、`entity`、`common` 和具体类名通常不能表达业务影响，不应作为默认 scope。
+
+## 原子提交边界
+
+- 同一业务能力的 controller、application/domain service、repository、DTO、迁移和测试可以同提交，确保提交可构建和回滚。
+- 公共契约与所有必需调用方修改通常同提交；若仓库支持分阶段兼容迁移，则按兼容阶段拆分。
+- `pom.xml`、version catalog 或 Gradle 文件与其 lock/verification metadata 一起提交；无关依赖升级单独使用 `build(deps)`。
+- Flyway/Liquibase 新迁移与对应实体、查询和测试可同提交；不要顺手重写已发布版本化迁移。
+- 两个独立业务域、不同发布风险或不同回滚策略的改动应拆分；同一文件内无法安全分离时先请求用户决定。
+
+## 消息示例
+
+```text
+feat(order): 支持批量取消待支付订单
+
+- 增加批量取消接口并复用单笔状态校验
+- 保持已支付订单处理和审计记录不变
+- 补充事务回滚与部分非法状态测试
+```
+
+```text
+fix(settlement): 修复重复回调导致结算流水重复入账的问题
+
+- 使用业务幂等键拦截已处理回调
+- 保留失败回调的可重试能力
+```
+
+```text
+build(deps): 升级 Spring Boot 与数据库驱动
+```
+
+```text
+feat(customer-api)!: 统一客户查询响应结构
+
+- 将分页数据统一为 items 和 total
+- 更新 OpenAPI 契约与消费者测试
+
+BREAKING CHANGE: 原 records 字段改为 items，调用方需更新反序列化模型
+```
+
+```text
+perf(valuation): 批量加载估值参数以减少重复查询
+
+- 将逐条查询合并为按产品批量加载
+- 增加查询次数断言并验证计算结果保持一致
+```
+
+错误与修正：
+
+| 错误 | 修正方向 |
+|---|---|
+| `fix：修改 OrderService` | 使用 ASCII 冒号并描述修复结果 |
+| `feat(controller): 新增接口` | 使用服务、模块或业务域 scope |
+| `chore: 修改数据库` | 判断是功能、修复、性能还是构建变化 |
+| `fix(order): 修复 bug` | 说明错误场景和用户可感知结果 |
+
+## Java 验证
+
+- 优先使用 wrapper，避免依赖开发机全局 Maven 或 Gradle 版本。
+- Maven 多模块可基于真实模块使用 `./mvnw -pl <module> -am test`；Gradle 可使用 `./gradlew :<module>:test`。不要编造模块路径或任务。
+- API 变更运行契约或集成测试；数据库变更运行迁移和 repository 测试；并发、事务和性能变更运行能证明关键性质的测试。
+- 使用仓库已有 Checkstyle、SpotBugs、PMD、Error Prone、JaCoCo 或格式检查任务；不要擅自引入新工具。
+- 测试产生的 `target/`、`build/`、日志和报告不得进入提交。
+
+## 规范依据
+
+- [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
+- [commitlint：AI Agents](https://commitlint.js.org/guides/ai-agents.html)
+- [commitlint 官方 committing-with-commitlint skill](https://github.com/conventional-changelog/commitlint/tree/master/skills/committing-with-commitlint)
+- [Spring Framework CONTRIBUTING](https://github.com/spring-projects/spring-framework/blob/main/CONTRIBUTING.md)
+- [Git SubmittingPatches](https://git-scm.com/docs/SubmittingPatches)
+

package/template/.agents/skills/page-form-module/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: page-form-module
+description: 指导实现 YSS UI 新增、编辑和查看表单模块，覆盖 YFormily Schema、mode 0/1/2、详情渲染、数据回显与回填、表单值被意外清空排查、校验、提交 loading、弹窗销毁和列表刷新；当页面包含表单页、Modal 或 Drawer 表单，或编辑时回显丢失、提交后表单未重置时使用。
+---
+
+# Page Form Module Skill
+
+## 触发条件
+
+- 实现新增、编辑、查看表单页，或 Drawer/Modal 中的表单闭环。
+- 需要处理 Schema、mode 0/1/2、回填、校验、提交和成功后列表刷新。
+
+## 不适用场景
+
+- 页面只包含列表查询，不包含任何表单编辑。
+- 表单为分步流程：使用 `formily-step-flow`。
+- 仅修复单个联动表达式：使用 `formily-linkage-effects`。
+
+## 必读依赖
+
+- 表单基础：`../formily-foundation/SKILL.md`
+- 联动副作用：`../formily-linkage-effects/SKILL.md`
+- 模式与详情：`../formily-mode-slot-detail/SKILL.md`
+- 分步表单：`../formily-step-flow/SKILL.md`
+- 接口与错误处理：`../yss-api-integration/SKILL.md`
+
+## 文档检索
+
+1. MCP 可用时，先用 `get_component_docs` 查询 `YFormily` 的 `mode`、`detail-options`、实例提交与回填 API，再按场景用 `get_demo` 获取 `formily/modes`、`formily/group`、`formily/linkage` 或 `formily/steps` 示例。
+2. 精确查询无结果时，先用 `search_docs` 或 `list_components` 校正名称；仅在 MCP 不可用、调用失败或校正后仍无结果时，回退读取最新 `llms-full.txt`。文档版本与当前依赖不一致时，再核对当前源码、CodeGraph 和真实导出。
+3. 当前会话已经加载上述本地 Skill 时，不要再通过 MCP 重复查询同一 Skill；仅在依赖 Skill 缺失时使用 `list_skills`、`get_skill` 补齐规则。
+
+## 硬约束（禁止/必须）
+
+- 提交前必须调用 `formRef.submit()` 或 `Submit.onSubmit` 进入完整校验链路。
+- `open/mode/currentId/formModel/submitting` 和回填、提交、关闭方法收敛在同一 Hook。
+- **数据前置同步原则（必守）**：表单数据必须在 `openCreate`/`openEdit` 触发前**同步赋好 `formModel.value`**；**严禁**在弹窗/抽屉组件内部通过 `watch(visible) + await nextTick() + initForm()` 异步回填数据（会导致首次编辑正常，切换新增再编辑时因时序差读取到残留空对象导致回显变空白的经典 Bug）。
+- **单一信任源**：使用 `v-model="formModel"` + `ref="formRef"` 调用 `submit()` 驱动；**严禁**在组件顶层写 `const form = createForm()` 与 `v-model`、`form.setValues`、`form.reset` 混用。
+- **禁止滥用动态 `:key`**：**严禁**在 `YFormily`/`YssFormily` 上使用 `:key="isEdit ? 'edit' : 'create'"` 等强制 Remount，应直接通过 `:mode` 或响应式数据驱动。
+- **弹窗生命周期隔离**：Modal/Drawer 必须配置 `:destroy-on-close="true"`，且内部 `YFormily` 必须使用 `v-if="open"` 随容器打开挂载、关闭销毁，避免宽度为 0 导致栅格退化，并彻底回收脏状态。
+- 新增/编辑/查看使用 `YFormily :mode="mode"`，`mode=2` 不渲染保存按钮。
+- Drawer 默认使用响应式宽度；基础表单设置 `FormLayout { labelWidth: 140, labelAlign: 'right' }`。
+- Drawer/Modal 中的 `FormGrid` 默认使用 `maxColumns: 2`、`minColumns: 1`、`minWidth: 320~360`；禁止 `minColumns: 2` 锁死两列。
+- 备注、说明和长文本通过 `x-decorator-props.gridSpan` 跨满整行。
+- 下拉选择器异步数据源必须使用 `enum` 或 `x-reactions` / `field.dataSource` 注入，严禁写入 `x-component-props.options`；基础字典下拉优先在弹窗打开前 `await` 拉取完成或在页面初始化提前拉取。
+- **表单校验规则规范**：必填文本字段声明 `whitespace: true`（如 `{ required: true, whitespace: true, message: '请输入xxx' }`）；自定义长度与格式校验必须使用条件式函数，空值放行交由 `required` 报错，非空才校验具体规则，禁止多个自定义校验重复承担必填职责。YFormily 适配层虽会归一化反馈展示，但不能代替正确的 Schema 语义。
+- 长整型 ID 按字符串原样回填和提交，禁止 `Number()`/`parseInt()`；表单中的普通数值按生成 DTO 真实类型处理。
+- 禁止使用 `if (res?.success)` 包裹保存成功逻辑，也禁止在 `catch` 重复 `message.error`。
+
+## 标准代码骨架
+
+```typescript
+import { ref } from 'vue';
+
+/** 默认表单模型 */
+const createDefaultModel = () => ({
+  name: '',
+  code: '',
+  description: '',
+});
+
+/** YFormily 业务侧仅需的实例方法。 */
+interface FormilyFormRef {
+  submit: () => Promise<Record<string, unknown>>;
+}
+
+/** 管理表单的模式、可见性、数据模型与提交链路。 */
+export const useRuleForm = (onSuccess: () => void) => {
+  const open = ref(false);
+  const mode = ref<0 | 1 | 2>(0);
+  const currentId = ref<string>();
+  const formModel = ref(createDefaultModel());
+  const submitting = ref(false);
+  const formRef = ref<FormilyFormRef>();
+
+  /** 打开新增：同步赋空值 */
+  const openCreate = (): void => {
+    mode.value = 0;
+    currentId.value = undefined;
+    formModel.value = createDefaultModel();
+    open.value = true;
+  };
+
+  /** 打开编辑：同步赋目标行数据，前置完成回填 */
+  const openEdit = (record: Record<string, any>): void => {
+    mode.value = 1;
+    currentId.value = record.id;
+    formModel.value = {
+      name: record.name ?? '',
+      code: record.code ?? '',
+      description: record.description ?? '',
+    };
+    open.value = true;
+  };
+
+  /** 关闭并清理 */
+  const close = (): void => {
+    open.value = false;
+    formModel.value = createDefaultModel();
+  };
+
+  /** 校验并保存表单。 */
+  const submit = async (): Promise<void> => {
+    if (mode.value === 2 || submitting.value || !formRef.value) return;
+
+    submitting.value = true;
+    try {
+      const values = await formRef.value.submit();
+      await saveRule({ ...formModel.value, ...values, id: currentId.value });
+      close();
+      onSuccess();
+    } catch {
+      // Formily 校验反馈或 mutator 已展示错误，此处不重复 Toast。
+    } finally {
+      submitting.value = false;
+    }
+  };
+
+  return { open, mode, currentId, formModel, submitting, formRef, openCreate, openEdit, close, submit };
+};
+```
+
+`saveRule` 必须替换为当前 Orval 真实生成方法，不得照抄占位名。
+
+```vue
+<YFormily
+  v-if="open"
+  ref="formRef"
+  v-model="formModel"
+  :schema="schema"
+  :mode="mode"
+  :detail-options="{ bordered: true, maxColumns: 2, minColumns: 1, minWidth: 320 }"
+/>
+```
+
+```typescript
+/** Drawer 表单的基础布局 Schema。 */
+export const drawerFormLayout = {
+  type: 'void',
+  'x-component': 'FormLayout',
+  'x-component-props': { layout: 'horizontal', labelWidth: 140, labelAlign: 'right' },
+  properties: {
+    grid: {
+      type: 'void',
+      'x-component': 'FormGrid',
+      'x-component-props': { maxColumns: 2, minColumns: 1, minWidth: 340, columnGap: 24, rowGap: 16 },
+      properties: {},
+    },
+  },
+};
+```
+
+## 交付检查清单
+
+- [ ] `mode=0/1/2` 语义、回填和查看态渲染正确。
+- [ ] 提交先校验，又防重入，loading 始终在 `finally` 恢复。
+- [ ] Drawer/Modal 内 `YFormily` 按可见性条件挂载与销毁。
+- [ ] label 宽度和右对齐一致，FormGrid 能从 2 列响应式收缩为 1 列。
+- [ ] 长字段已跨行，长整型 ID 未转 number。
+- [ ] 没有 `if (res?.success)` 和重复错误 Toast。
+- [ ] 成功后关闭表单并通知上层刷新。
+- [ ] 业务层未导入 `@formily/antdv` UI 组件。
+
+## 失败兜底策略
+
+- 提交无响应时，先确认 `submit()` 是否实际调用并查看 Formily 校验反馈。
+- 编辑回填异常时，核对真实 DTO、字段路径与 Schema path，不在模板散落转换。
+- 表单过大时，拆分 Schema 生成函数、字典 Hook 和提交 Hook，保持 `index.vue` 不超过 150 行。

package/template/.agents/skills/page-list-module/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: page-list-module
+description: 指导实现 YSS UI 标准列表、远程分页、查询重置、YTable 工具栏、行操作、批量操作和左树右表模块；当页面需要查询、表格、分页或 CRUD 列表闭环时使用。
+---
+
+# Page List Module Skill
+
+## 触发条件
+
+- 实现查询、表格、分页、行操作或批量操作组合的业务列表。
+- 实现左树右表、远程分页、工具栏或列设置。
+
+## 不适用场景
+
+- 仅实现表单提交，没有列表或分页。
+- 仅展示本地静态数据，不涉及业务查询与列表操作。
+
+## 必读依赖
+
+- 组件选型：`../component-selection-imports/SKILL.md`
+- 表格 API：`../ytable-usage/SKILL.md`
+- 查询表单：`../yss-formily/SKILL.md`
+- 接口、错误链路和长整型：`../yss-api-integration/SKILL.md`
+- 左树右表高度：`../ytree-usage/SKILL.md`、`../yss-use-tree-height/SKILL.md`、`../yss-use-table-height/SKILL.md`
+
+## 文档检索
+
+1. MCP 可用时，按当前页面实际使用的能力调用 `get_component_docs` 查询 `YTable`、`YFormily`、`useTableHeight` 或 `useTreeHeight`，再用 `get_demo` 获取对应官方示例；不要只凭 Skill 内的静态片段推断 API。
+2. 精确查询无结果时，先用 `search_docs` 或 `list_components` 校正名称；仅在 MCP 不可用、调用失败或校正后仍无结果时，回退读取最新 `llms-full.txt`。文档版本与当前依赖不一致时，再核对当前源码、CodeGraph 和真实导出。
+3. 当前会话已经加载上述本地 Skill 时，不要再通过 MCP 重复查询同一 Skill；仅在依赖 Skill 缺失时使用 `list_skills`、`get_skill` 补齐规则。
+
+## 硬约束（禁止/必须）
+
+- 列表请求必须收敛在 `useXxxList`，模板不直接请求。
+- 后端查询参数可用 `pageIndex/pageSize`；YTable 分页状态必须使用 `current/pageSize/total`。
+- 远程分页必须配置 `pageable`、`pagination.remote = true`、`v-model:pagination` 和 `@page-change`；事件参数固定为 `{ current, pageSize }`，禁止读取 `currentPage`。
+- 禁止臆造 `request`/`search-params` 等 Prop，也禁止把实例 `refresh()` 当成远程重新查询；该方法只调用 vxe `updateData()` 刷新当前表格数据，远程查询/重置/刷新必须调用业务 Hook。
+- 查询区使用纵向 `search-content`：`YFormily` 仅渲染字段，查询/重置按钮在外部 `.xxx__search-actions` 独占下一行并右对齐。
+- 新增、导入、批量操作等主操作直接放入 `#toolbar-right` 插槽即可自动渲染；**无需配置 `:toolbar-config="{ custom: true }"`**，避免无端展示列设置图标；**仅在业务明确需要列设置时才传入 `:toolbar-config="{ custom: true }"`**。
+- 删除等危险操作默认使用 `actionConfig.buttons[].isConfirm` 按钮项气泡确认，禁止默认使用居中 `Modal.confirm`。
+- 列定义、状态映射和筛选配置放入 `constant.ts`；超过 10 行的列不得内联在 `index.vue`。
+- 长整型 ID 保持字符串透传，禁止 `Number()`/`parseInt()` 等会丢失精度的转换；页码、状态值等普通 number 按真实生成类型使用。
+- 禁止使用 `if (res?.success)` 包裹成功逻辑，也禁止在 `else`/`catch` 重复调用 `message.error`；mutator 已对 `success === false` 提示并 reject。
+
+## 标准代码骨架
+
+```typescript
+import { reactive, ref } from 'vue';
+
+/** 管理规则列表数据、查询条件和远程分页。 */
+export const useRuleList = () => {
+  const loading = ref(false);
+  const dataList = ref<RuleItem[]>([]);
+  const query = reactive<RuleQuery>({ pageIndex: 1, pageSize: 20, keyword: '' });
+  const pagination = reactive({ current: 1, pageSize: 20, total: 0, remote: true });
+
+  /** 请求规则列表；错误 Toast 由 mutator 处理。 */
+  const fetchData = async (): Promise<void> => {
+    loading.value = true;
+    try {
+      query.pageIndex = pagination.current;
+      query.pageSize = pagination.pageSize;
+      const res = await queryRuleList(query);
+      dataList.value = res.data ?? [];
+      pagination.total = res.totalCount ?? 0;
+    } catch {
+      dataList.value = [];
+      pagination.total = 0;
+    } finally {
+      loading.value = false;
+    }
+  };
+
+  /** 处理页码或每页数量变化。 */
+  const handlePageChange = ({ current, pageSize }: { current: number; pageSize: number }): void => {
+    pagination.current = current;
+    pagination.pageSize = pageSize;
+    void fetchData();
+  };
+
+  /** 从第一页执行查询。 */
+  const handleSearch = (): void => {
+    pagination.current = 1;
+    void fetchData();
+  };
+
+  /** 重置查询条件并回到第一页。 */
+  const handleReset = (): void => {
+    Object.assign(query, { pageIndex: 1, pageSize: pagination.pageSize, keyword: '' });
+    pagination.current = 1;
+    void fetchData();
+  };
+
+  return { loading, dataList, query, pagination, fetchData, handlePageChange, handleSearch, handleReset };
+};
+```
+
+`RuleItem`、`RuleQuery`、`queryRuleList` 必须替换为当前 Orval 生成类型和真实方法，禁止照抄占位名。
+
+```vue
+<YTable
+  v-if="isReady"
+  ref="tableRef"
+  v-model:selected-row-keys="selectedRowKeys"
+  :row-config="{ keyField: 'id', useKey: true }"
+  :data="dataList"
+  :columns="TABLE_COLUMNS"
+  :loading="loading"
+  :height="tableHeight"
+  pageable
+  v-model:pagination="pagination"
+  @page-change="handlePageChange"
+>
+  <template #toolbar-right>
+    <YButton :disabled="selectedRowKeys.length === 0" @click="handleBatchDelete">批量删除</YButton>
+    <YButton type="primary" @click="openCreate">新增</YButton>
+  </template>
+</YTable>
+```
+
+## 交付检查清单
+
+- [ ] 已确认真实 Orval 导出、查询 DTO 和响应字段。
+- [ ] 查询参数与 YTable 分页字段已映射，`page-change` 回调读取 `current/pageSize` 而非 `currentPage`。
+- [ ] 若包含批量操作，首列已配置 `type: 'checkbox'`，设置了 `:row-config="{ keyField: 'xxx', useKey: true }"`，批量按钮配置了 `:disabled="selectedRowKeys.length === 0"`，操作成功后已清空选中态。
+- [ ] 查询/重置会回到第一页，远程分页配置完整。
+- [ ] 主操作在 `#toolbar-right`，列设置已开启。
+- [ ] 删除使用气泡确认，操作按钮的 loading/close 在成功与失败后都会恢复。
+- [ ] 长整型 ID 未转 number，普通 number 仍符合真实类型。
+- [ ] 没有 `if (res?.success)` 和重复错误 Toast。
+- [ ] loading、空态和失败后数据状态可预期。
+
+## 失败兜底策略
+
+- 分页字段混乱时，在 Hook 中分离 YTable 状态和后端参数，不直接把 `pageIndex/totalCount` 绑到组件。
+- 列表逻辑过大时，拆分 `useListData` 和 `useListActions`，不得回填到 `index.vue`。
+- 响应字段不稳定时，在 Hook API 边界做最小映射，禁止在模板散落兼容分支。