first commit

2026-07-25 23:45:09 +08:00
commit c7bd957e6f
47 changed files with 3870 additions and 0 deletions
@@ -0,0 +1,116 @@
 ---
 name: java-coding-style
 description: 面向 Vibe Coding Agent 的 Java 编写、修改、重构、审查与验证规范，以《阿里巴巴 Java 开发手册》为质量基线并适配现代 JDK 与项目既有约定。凡任务涉及 Java、Spring、Jakarta、Quarkus、MyBatis、JPA、Maven、Gradle、单元测试、并发、异常日志、数据库访问或 Java 代码 Review 时使用。
 ---
 # Java 代码风格
 将本 Skill 作为 Java 任务的语言级质量规范；将项目的任务治理 Skill 作为流程级规范。两者同时触发时，先执行任务分级与门禁，再在实现、Review 和验证阶段执行本 Skill。
 ## 规则优先级
 按以下顺序解决冲突：
 ```text
 平台安全规则与用户本次明确要求
 → 已确认的需求、接口和验收标准
 → 作用域最近的 AGENTS.md、项目规范、构建配置与 formatter
 → 相邻代码中稳定且合理的架构惯例
 → 本 Skill 的必须项
 → 本 Skill 的推荐项
 ```
 不得以“遵循阿里规范”为由破坏兼容性、绕过项目门禁或批量改写无关代码。发现项目惯例存在明显缺陷、安全问题或与必须项冲突时，说明证据、影响和建议，不得静默复制缺陷。
 ## 规则等级
 - **必须**：默认不可违反。仅在更高优先级规则明确要求时例外，并记录原因。
 - **推荐**：无冲突时采用；不采用时应有可说明的工程理由。
 - **参考**：根据 JDK、框架、性能数据和业务上下文选择。
 规则等级用于约束 Agent，不代表已配置静态检查。只有实际运行的检查才能报告为通过。
 ## 开始实现前
 1. 查找并读取作用域内的 `AGENTS.md`、README、构建文件、formatter、Checkstyle、PMD、SpotBugs、Error Prone 和测试配置。
 2. 确认 Java/JDK 版本、框架版本、模块边界、包结构、依赖管理方式及相邻实现惯例。
 3. 从用户需求或已确认文档提取可观察行为、边界条件、异常语义、兼容性约束和验收证据。
 4. 检查工作区已有改动，避免覆盖、格式化或修复任务范围外的代码。
 5. 按任务内容加载本 Skill 的参考文件：
   - 命名、格式、常量、注释：读取 [references/01-命名格式与注释.md](references/01-命名格式与注释.md)。
   - 类型、OOP、API、空值：读取 [references/02-类型OOP与API设计.md](references/02-类型OOP与API设计.md)。
   - 集合、并发、日期时间：读取 [references/03-集合并发与时间.md](references/03-集合并发与时间.md)。
   - 异常、日志、安全：读取 [references/04-异常日志与安全.md](references/04-异常日志与安全.md)。
   - 分层、持久化、依赖：读取 [references/05-工程分层与数据访问.md](references/05-工程分层与数据访问.md)。
   - 测试、Review、验证：实现和审查阶段读取 [references/06-测试审查与验证.md](references/06-测试审查与验证.md)。
 只加载与任务相关的规则；进行完整 Java Review 时加载全部参考文件。
 ## 编写代码
 遵循以下顺序：
 ```text
 确认行为与边界
 → 找到最小改动点
 → 先写或调整能失败的测试
 → 实现最小充分代码
 → 清理命名、结构和重复
 → 执行静态审查
 → 运行相关验证
 ```
 必须：
 - 保持单一职责和清晰依赖方向，不为了“更优雅”引入无需求支撑的抽象、框架或设计模式。
 - 优先复用项目内已验证的组件；新增公共工具前确认没有等价实现。
 - 把校验放在信任边界，把业务不变量放在领域或服务边界；不要依赖控制器校验保护所有调用路径。
 - 维持 API、序列化、数据库和异常契约兼容；任何破坏性变化都必须显式列出并获得相应确认。
 - 仅修改任务需要的代码。不要顺手全局格式化、升级依赖或清理无关告警。
 - 对非显然的业务决策写“为什么”的注释；不要用注释复述代码。
 - 不生成凭据、真实个人信息、生产数据或可被误用的安全绕过代码。
 ## Java 专项审查
 实现后逐项检查：
 1. 正确性：空值、边界、溢出、精度、时区、编码、异常路径和资源释放。
 2. 契约：参数、返回值、异常、幂等性、事务、序列化和向后兼容。
 3. 并发：共享可变状态、原子性、可见性、锁范围、线程池和 `ThreadLocal` 清理。
 4. 数据：参数绑定、查询规模、索引假设、批量操作、事务边界和 N+1 查询。
 5. 安全：认证与授权、对象级权限、注入、反序列化、路径/URL、敏感信息和重放。
 6. 可维护性：命名、职责、重复、嵌套、隐藏副作用和测试可读性。
 发现问题时按严重性报告：`阻断`、`严重`、`一般`、`建议`。给出文件、位置、触发条件、影响和最小修复建议；不得只报风格偏好。
 ## 验证
 优先使用项目已有命令和 CI 等价检查。按改动范围选择：
 - 运行目标单元测试，再运行受影响模块测试。
 - 运行编译、格式、静态分析和集成测试中与风险相称的部分。
 - 项目已配置 Alibaba P3C/PMD 时运行其既有任务；未配置时不要擅自安装插件或新增构建依赖。
 - 对并发、事务、时区、序列化或安全变更补充针对性验证，不能只依赖 happy path。
 报告每个实际命令、结果和未执行项。不得把“代码看起来正确”写成测试通过，不得用全量构建失败掩盖目标测试结果。
 ## 交付格式
 最终说明至少包含：
 - 完成的行为与主要代码位置；
 - 与需求直接相关的设计决定；
 - 实际执行的测试和静态检查；
 - 未验证内容、遗留风险和明确例外。
 若仅做 Review，不修改代码；若用户要求实现，则完成实现、Review 和验证后再交付。
 ## 规范来源与适配
 本 Skill 以阿里巴巴公开的 Java 开发规约及 P3C 工具规则为基线，并将其改写为 Agent 可执行指令：
 - [Alibaba Java Coding Guidelines](https://alibaba.github.io/Alibaba-Java-Coding-Guidelines/)
 - [阿里巴巴 Java 开发手册中文目录](https://alibaba.github.io/p3c/)
 - [Alibaba P3C](https://github.com/alibaba/p3c)
 阿里规约按“强制、推荐、参考”分级；本 Skill 对应为“必须、推荐、参考”。历史性规则不得脱离项目 JDK、框架、序列化协议和工具链机械套用。
@@ -0,0 +1,4 @@
 interface:
  display_name: "Java 代码风格"
  short_description: "以阿里巴巴规约为基线编写、审查与验证现代 Java 代码"
  default_prompt: "Use $java-coding-style to implement and review this Java change according to the project rules and Alibaba Java Coding Guidelines."
@@ -0,0 +1,62 @@
 # 命名、格式与注释
 ## 命名
 - **必须**：类、接口和枚举使用 `UpperCamelCase`；方法、参数、字段和局部变量使用 `lowerCamelCase`；常量使用语义完整的 `UPPER_SNAKE_CASE`。
 - **必须**：包名全小写，以稳定的组织与业务域命名；遵循项目现有单复数约定。
 - **必须**：命名不得以 `_` 或 `$` 开头、结尾，不得使用中文、纯拼音或中英拼音混写。国际通用专名除外。
 - **必须**：抽象基类使用 `Abstract` 或项目约定前缀；异常以 `Exception` 结尾；测试类遵循项目测试框架的现有命名。
 - **必须**：避免无意义缩写、单字母业务变量和误导性名称。循环索引等极小作用域变量可以使用惯用短名。
 - **必须**：Bean/序列化对象的布尔属性命名必须验证框架映射；默认不以 `is` 命名字段，访问器可按 JavaBeans 约定使用 `isXxx()`。
 - **推荐**：DO、DTO、BO、VO、PO 等后缀只在项目已经定义其语义时使用，不自行发明相邻概念。
 - **推荐**：实现设计模式时让类名表达职责，如 `OrderFactory`；不要仅为套用模式而改名。
 ## 常量与字面量
 - **必须**：禁止散落的业务魔法值；提取为有领域含义的常量、枚举或值对象。
 - **必须**：`long` 字面量使用大写 `L`。
 - **必须**：不得用一个“万能常量类”承载所有模块常量；按模块和职责控制可见性。
 - **推荐**：仅在真正固定且跨实例共享时声明 `static final`；不要把可变集合伪装成常量。
 - **推荐**：状态和类型码优先使用有行为约束的枚举或值对象，同时保持对外协议兼容。
 ## 格式
 - **必须**：服从项目 formatter、Checkstyle 或编辑器配置；不得因本文件偏好覆盖自动化格式规则。
 - **必须**：控制语句始终使用大括号；关键字与左括号间保留空格；运算符两侧保留空格。
 - **必须**：默认使用 4 空格缩进且不使用 Tab；项目 formatter 另有规定时从项目。
 - **推荐**：单行不超过 120 字符；import 和自动生成代码按工具配置处理。
 - **推荐**：新增方法原则上不超过 80 行，新增类原则上不超过 500 行。生成代码、声明型配置或框架限制可例外，但应说明原因。
 - **推荐**：方法保持聚焦，避免超过三层嵌套；优先使用卫语句、提取方法或清晰的布尔变量。
 - **必须**：避免魔法值、重复代码、过深嵌套和无业务价值的抽象。
 - **必须**：不要提交仅由全局换行、import 重排或格式化导致的无关 diff。
 ## 导入
 - **必须**：禁止通配符导入。
 - **推荐**：按静态导入、Java/Jakarta 标准库、第三方库、项目内部包分组，组间空一行。
 - **推荐**：同组内按字典序排列；若项目格式化器定义了不同顺序，以格式化器为准。
 - **必须**：删除未使用导入，不通过全限定类名规避正常导入。
 ## 注释与 Javadoc
 - **必须**：公共 API、接口抽象方法和不显然的契约说明使用 Javadoc，包含参数约束、返回语义和可观察异常。
 - **必须**：修改逻辑时同步更新相关注释；陈旧注释视为缺陷。
 - **必须**：注释说明意图、业务原因、约束或权衡，不复述语句表面含义。
 - **必须**：枚举字段或代码值必须能看出业务含义，可通过 Javadoc、构造参数或明确命名表达。
 - **推荐**：TODO/FIXME 包含可追踪的任务标识和原因；若无跟踪机制则完成或删除。
 - **必须**：不要保留大段注释掉的代码，版本历史可承担恢复职责。
 - **必须**：所有新增类必须有 Javadoc，首句说明职责而非复述类名。
 - **必须**：类 Javadoc 使用作者 `xiang`，通过 `@since` 记录实际首次创建日期，日期格式固定为 `yyyy-MM-dd`；后续修改不得覆盖首次创建日期。
 - **推荐**：对复杂业务逻辑解释“为什么”和特殊规则，不逐行翻译代码；业务分支意图不明显时补充说明。
 - **必须**：禁止保留 `yourname`、`TODO author` 等占位内容。
 Javadoc 采用以下格式；`yyyy-MM-dd` 必须替换为实际首次创建日期，不得原样保留：
 ```java
 /**
 * 类的职责说明
 *
 * @author xiang
 * @since yyyy-MM-dd
 */
 ```
@@ -0,0 +1,49 @@
 # 类型、OOP 与 API 设计
 ## 类型与相等性
 - **必须**：包装类型使用 `equals` 或 `Objects.equals` 比较值，不使用 `==`；警惕缓存范围造成的偶然相等。
 - **必须**：`BigDecimal` 使用字符串或精确来源构造；数值大小用 `compareTo`，需要比较值与 scale 时才用 `equals`。
 - **必须**：货币、比例和计量值明确精度、舍入方式与单位；禁止用 `double` 承载精确金额。
 - **必须**：重写 `equals` 时同时重写 `hashCode`，并验证对称性、传递性和集合行为。
 - **推荐**：用领域类型、枚举和受约束构造器替代多个语义不明的 `String`、`int` 参数。
 - **必须**：类型转换前检查范围和语义；不得以强制转换静默截断数值。
 ## 空值与返回值
 - **必须**：明确参数与返回值的 nullability；不得依靠调用方猜测。
 - **推荐**：返回空集合或空数组而非 `null`；不要为避免判断而创建语义虚假的空领域对象。
 - **推荐**：`Optional` 主要用于可能缺失的返回值；不要默认用于实体字段、DTO 字段、方法参数或集合元素。
 - **必须**：禁止无条件链式解引用可能为空的对象；在边界校验或使用清晰分支表达缺失语义。
 - **必须**：不要用断言校验外部输入，因为生产环境可能禁用断言。
 - **推荐**：在系统边界尽早校验参数；项目支持 Bean Validation 时优先使用 `@Valid`、`@NotNull`、`@NotBlank`、`@Size` 等声明式校验。
 - **推荐**：内部前置条件优先复用项目已有校验工具；只有需要定制业务错误码或分支处理时才手写空值判断。
 - **必须**：不得仅为判空新增依赖。
 - **推荐**：项目没有现成判空工具时，对象使用 `obj == null`，集合使用 `collection == null || collection.isEmpty()`，Map 使用 `map == null || map.isEmpty()`；只有项目已经依赖 Apache Commons Collections 时，才使用 `CollectionUtils.isEmpty()` 或 `MapUtils.isEmpty()`。
 ## OOP 与封装
 - **必须**：遵循单一职责和最小可见性；字段默认 `private`，只暴露必要 API。
 - **必须**：构造完成后对象应满足不变量；不要暴露可变内部集合、数组或日期对象。
 - **推荐**：优先组合而非继承；继承只用于稳定的 is-a 关系和可替换契约。
 - **必须**：覆写方法使用 `@Override`；可变参数只用于同类型、同语义参数，不使用 `Object...` 逃避类型设计。
 - **必须**：构造器不得启动线程、访问远程资源或发布未完全构造的 `this`。
 - **推荐**：不可变对象优先；必要时使用 defensive copy，并确保集合元素也符合可变性预期。
 - **推荐**：接口保持内聚，不创建囊括无关操作的“大而全” Service 或 Util。
 ## API 与兼容性
 - **必须**：公共 API 明确输入校验、返回语义、错误模型、幂等性和副作用。
 - **必须**：新增重载时检查 `null`、lambda、自动装箱和可变参数是否造成调用歧义。
 - **必须**：修改 DTO、枚举、JSON 字段、RPC 签名或异常类型前评估调用方兼容性。
 - **推荐**：返回接口类型而非具体集合实现；不要泄漏 ORM 实体、框架上下文或内部异常。
 - **推荐**：避免布尔参数控制多个行为，优先使用有语义的方法、枚举或选项对象。
 - **必须**：不得以反射、原始类型或未检查转换绕过编译器，除非边界隔离、理由明确并有测试。
 ## Lombok
 - **必须**：仅在项目已采用 Lombok 时使用，不为风格统一单独引入依赖。
 - **参考**：DTO/VO 可使用 `@Data`；使用前检查可变性、相等性和敏感字段，存在特殊约束时改用明确的 `@Getter`、`@Setter`、`@EqualsAndHashCode` 或 `@ToString`。
 - **推荐**：实体类和值对象避免使用 `@Data`；按项目约定组合 `@Getter`、`@Setter`、`@Builder`、`@NoArgsConstructor` 和 `@AllArgsConstructor`，且不得绕过领域不变量或 ORM 构造约束。
 - **推荐**：除非继承关系确有需要，不设置 `@EqualsAndHashCode(callSuper = true)`。
 - **必须**：`toString` 不得暴露敏感字段，也不得触发懒加载或递归引用。
@@ -0,0 +1,34 @@
 # 集合、并发与时间
 ## 集合
 - **必须**：选择与语义相符的集合；需要唯一性用 `Set`，需要键查找用 `Map`，不要靠线性扫描模拟索引。
 - **推荐**：规模可预估时设置合理初始容量，但不得按不可信输入直接分配超大容器。
 - **必须**：`Arrays.asList` 不是可增删列表；数组元素变化会反映到视图。需要独立可变列表时显式复制。
 - **必须**：集合转数组使用类型安全的 `toArray` 形式，并遵循项目 JDK 的惯用写法。
 - **必须**：遍历时删除元素应使用迭代器、`removeIf` 或收集后处理，不在增强 `for` 中直接结构性修改。
 - **必须**：不要修改 `Map.keySet()`、`values()` 等视图后假设原映射不变。
 - **必须**：自定义对象作为 `Map` 键或 `Set` 元素时保证 `equals/hashCode` 稳定；插入后不得改变参与哈希的字段。
 - **推荐**：返回只读视图或副本时明确其快照/联动语义；`unmodifiable` 不等于深度不可变。
 - **推荐**：Stream 用于清晰的数据变换；有副作用、异常流程或复杂分支时使用普通循环。
 ## 并发
 - **必须**：先识别共享可变状态，再选择不可变、线程封闭、并发容器、原子类或锁；`volatile` 不能保证复合操作原子性。
 - **必须**：线程池必须有清晰的线程数、队列、线程命名、拒绝策略和关闭策略。传统平台线程池不得直接使用默认无界的便捷工厂掩盖这些参数。
 - **参考**：Java 21+ 虚拟线程需确认项目支持、阻塞模型、限流方式与 `ThreadLocal` 成本；不要把虚拟线程当作无限资源。
 - **必须**：`ThreadLocal` 使用后在 `finally` 中清理，尤其在线程池和请求复用场景。
 - **必须**：锁范围尽可能小，不在持锁期间执行未知回调、远程调用或慢 I/O；多个锁必须有固定顺序。
 - **必须**：捕获 `InterruptedException` 后恢复中断标记或明确终止流程，不得吞掉中断。
 - **推荐**：高并发随机数使用 `ThreadLocalRandom`；共享计数根据竞争程度选择原子类或累加器。
 - **推荐**：并行 Stream 仅在数据量、无副作用、线程池影响和基准数据明确时使用。
 - **必须**：并发正确性不能只靠一次测试；检查竞态、可见性、重复执行、超时、取消与关闭路径。
 ## 日期与时间
 - **必须**：优先使用 `java.time`；旧 `Date/Calendar` 仅用于兼容边界并尽快转换。
 - **必须**：业务时间明确时区。存储时间点优先用 `Instant`，面向地区规则时显式使用 `ZoneId`。
 - **必须**：不得共享非线程安全的旧式日期格式化器；优先使用不可变的 `DateTimeFormatter`。
 - **必须**：持续时间测量使用单调时钟语义，如 `System.nanoTime()`；不要用墙上时钟计算短耗时。
 - **必须**：时间测试固定 `Clock` 或等价抽象，避免依赖当前时间造成不稳定测试。
 - **推荐**：日期边界、夏令时、闰年和跨时区转换要有针对性用例。
@@ -0,0 +1,46 @@
 # 异常、日志与安全
 ## 异常
 - **必须**：异常表达失败语义，不用异常控制正常分支。
 - **必须**：不要直接抛出宽泛的 `Exception`、`RuntimeException` 或 `Throwable`；使用标准的精确异常或稳定的领域异常。
 - **必须**：不得空 `catch`、只打印堆栈或吞掉异常。转换异常时保留 cause，并补充不含敏感数据的上下文。
 - **必须**：同一层通常选择“处理并记录”或“向上抛出”，避免每层重复记录同一异常。
 - **必须**：可通过前置检查避免的错误应先校验；并发竞态场景仍以原子操作结果为准。
 - **必须**：资源使用 try-with-resources；`finally` 不得用 `return` 覆盖原返回值或异常。
 - **必须**：捕获范围保持最小，不用一个大 `try` 模糊具体失败点。
 - **推荐**：对外错误模型稳定、可追踪且不泄漏内部栈、SQL、文件路径或依赖细节。
 ## 日志
 - **必须**：使用项目日志门面，不使用 `System.out`、`System.err` 或 `printStackTrace`。
 - **必须**：参数化记录日志，不做无必要的字符串拼接；异常对象作为日志框架支持的异常参数传入。
 - **必须**：日志级别符合可操作性：预期业务拒绝通常不是 error，系统不可恢复失败不能只写 debug。
 - **必须**：禁止记录密码、令牌、密钥、完整证件号、银行卡、Cookie、会话或未脱敏请求体。
 - **推荐**：记录稳定的事件、结果、耗时、非敏感标识和 trace/correlation id；避免在高频循环中刷屏。
 - **必须**：日志不得改变业务行为；日志表达式不得触发远程调用、延迟加载或明显昂贵计算。
 - **推荐**：项目同时使用 SLF4J 和 Lombok 时采用 `@Slf4j`，否则遵循项目统一的日志门面与声明方式。
 - **必须**：`error` 仅用于由当前层最终处理、需要人工介入的系统失败，并包含异常堆栈和已脱敏的定位上下文。
 - **推荐**：`warn` 用于异常但可恢复、仍需要关注的状态。
 - **推荐**：预期业务拒绝通常使用 `info` 或不记录，避免制造告警噪声。
 - **必须**：同一异常只在负责最终处理的层记录一次；转换异常时保留原始 cause，不在中间层重复打印堆栈。
 ## 输入与权限
 - **必须**：所有外部输入在信任边界验证类型、长度、范围、格式、集合规模和允许值；前端校验不能替代服务端校验。
 - **必须**：认证后仍要做功能级和对象级授权，不能只检查“是否登录”。
 - **必须**：SQL 使用参数绑定；排序字段、表名、列名等不可绑定的元数据必须采用服务端白名单。
 - **必须**：输出到 HTML、脚本、URL、日志或命令时按目标上下文编码；不要自行拼接转义规则。
 - **必须**：状态变更接口按框架能力启用 CSRF、防重放、幂等或频控措施。
 - **必须**：文件路径规范化并限制在允许根目录；URL 请求限制协议、主机、重定向和内网地址以防 SSRF。
 - **必须**：禁止反序列化不可信 Java 原生对象流；JSON 多态、表达式、脚本和正则能力采用最小白名单。
 - **必须**：凭据来自受控配置或密钥服务，不写入源码、测试、日志和错误响应。
 - **推荐**：使用成熟安全库和框架默认防护，不自行实现密码学、会话、签名或随机令牌算法。
 ## 事务与一致性
 - **必须**：事务边界与业务原子性一致，避免在长事务中执行远程调用或不可控 I/O。
 - **必须**：明确异常类型是否触发回滚；框架代理、自调用和异步边界可能使事务注解失效。
 - **必须**：事务方法捕获异常后必须重新抛出、显式标记回滚或完成可靠补偿。
 - **必须**：重试仅用于可重试失败，并要求操作幂等、退避、次数上限和可观测性。
 - **推荐**：跨系统一致性采用项目既有 outbox、事件或补偿机制，不临时发明“先写库再发消息”的脆弱流程。
@@ -0,0 +1,38 @@
 # 工程分层与数据访问
 ## 分层与依赖
 - **必须**：遵循项目既有模块边界和依赖方向；领域层不得反向依赖 Web、ORM 或具体基础设施实现。
 - **必须**：Controller/Endpoint 负责协议适配与边界校验，不承载核心业务编排。
 - **必须**：持久化对象、领域对象和 API DTO 的转换边界明确；不得把 ORM 实体直接作为外部契约。
 - **推荐**：使用构造器注入表达必需依赖并支持测试；字段注入仅在项目框架约束明确时使用。
 - **推荐**：工具类无状态、职责单一且构造器不可见；不要创建混杂业务逻辑的通用 `Utils`。
 - **必须**：循环依赖表示边界问题，不以延迟注入作为默认解决方案。
 ## 数据访问
 - **必须**：禁止字符串拼接用户输入生成 SQL；MyBatis 默认使用 `#{}`，`${}` 只允许经过严格白名单的元数据。
 - **必须**：明确查询列，不使用 `SELECT *` 作为生产查询默认写法。
 - **必须**：分页总数为零时避免继续执行无意义的数据查询；限制最大页大小和排序字段。
 - **必须**：批量查询、写入和 `IN` 参数有明确上限并按数据库能力分批。
 - **必须**：避免循环中逐条远程或数据库调用；检查 N+1 查询和不受控懒加载。
 - **必须**：更新语句只更新预期字段；乐观锁、版本号或条件更新必须检查受影响行数。
 - **必须**：事务内查询和更新基于明确隔离假设；不能用应用层 `if` 代替数据库唯一约束或原子条件。
 - **推荐**：索引设计与真实查询条件、排序和基数一致；新增查询必须评估执行计划或沿用已验证索引。
 - **推荐**：数据库约束与应用校验共同保护核心不变量，不机械套用“禁止所有外键”；服从项目的数据治理策略。
 ## Spring、Jakarta 与 ORM
 - **必须**：Bean Validation 放在真实入口并确保级联校验生效；内部调用仍需保护领域不变量。
 - **必须**：`@Transactional`、缓存、异步和权限注解必须考虑代理边界、自调用、方法可见性和异常回滚语义。
 - **必须**：JPA 实体的 `equals/hashCode` 不得依赖会变化的数据库生成标识造成集合异常。
 - **推荐**：默认避免 Open Session in View 带来的隐式查询；在服务边界显式获取所需数据。
 - **必须**：MyBatis/JPA 映射字段、枚举、时区和 null 语义必须有测试，不能仅凭同名假设自动映射正确。
 ## 构建与依赖
 - **必须**：新增或升级依赖前确认项目 BOM、dependency management、版本锁定和许可证/安全要求。
 - **必须**：生产发布不依赖不可复现的 SNAPSHOT 或动态版本，除非项目流程明确批准。
 - **必须**：依赖变更检查传递依赖、冲突、打包体积和运行时兼容；不要只确认“能编译”。
 - **推荐**：优先使用 JDK 与项目已有库；为一个简单方法引入大型依赖通常不合理。
 - **必须**：生成代码和资源遵循构建目录约定，不手改会被生成器覆盖的文件。
@@ -0,0 +1,67 @@
 # 测试、审查与验证
 ## 测试设计
 - **必须**：测试代码放在项目约定的测试源集，通常为 `src/test/java`；不得把测试逻辑混入生产代码。
 - **必须**：每个测试具有清晰的 Arrange/Act/Assert 或 Given/When/Then 结构，一个失败能指出一个主要行为。
 - **必须**：测试独立、可重复、可并行时不互相污染；不得依赖执行顺序、真实当前时间、随机外网或共享生产数据。
 - **必须**：断言业务结果、状态变化和外部交互，不只断言“无异常”或覆盖实现细节。
 - **推荐**：遵循 AIR 原则：Automatic、Independent、Repeatable；覆盖 BCDE：Boundary、Correct、Design、Error。
 - **必须**：缺陷修复先加入能复现问题的测试；新行为先建立失败证据，再实现通过。
 - **推荐**：单元测试隔离自身职责，集成测试验证真实框架映射、事务、序列化和数据库行为。
 - **必须**：Mock 只隔离边界，不复刻被测实现；过多 Mock 通常提示职责或测试层级错误。
 - **推荐**：测试命名表达条件与预期，服从项目现有 JUnit/TestNG、Mockito、AssertJ 等风格。
 ## 风险用例
 按任务选择至少检查：
 - null、空值、最小/最大长度、零、负数、溢出、重复和非法枚举；
 - 精度、舍入、字符编码、Locale、时区和夏令时；
 - 超时、重试、重复请求、部分失败、事务回滚和幂等；
 - 并发更新、锁竞争、中断、资源关闭和线程池拒绝；
 - 未认证、未授权、越权、注入、恶意大输入和敏感信息泄漏；
 - 序列化前后兼容、数据库映射和旧调用方行为。
 ## Code Review 清单
 1. 将每条需求映射到实现与至少一项验证证据。
 2. 阅读完整 diff 和必要上下文，不只看新增行。
 3. 检查是否覆盖用户已有改动或包含无关格式化。
 4. 检查空值、异常、资源、并发、事务、数据规模和安全边界。
 5. 检查 API、DTO、SQL、配置与依赖的兼容性。
 6. 检查测试能在错误实现下失败，避免只验证 Mock 自己的返回。
 7. 将发现按 `阻断/严重/一般/建议` 分级，并给出触发条件和影响。
 8. 修复后重新阅读 diff 并重跑受影响验证。
 ## 命令选择
 先从仓库文档和 CI 获取标准命令，常见候选仅供识别：
 ```text
 Maven:  ./mvnw test
 Gradle: ./gradlew test
 ```
 不要假定包装器、模块名或 profile 一定存在。优先运行：
 1. 单个受影响测试；
 2. 受影响模块测试；
 3. 编译与项目配置的 formatter/Checkstyle/PMD/SpotBugs；
 4. 风险要求的集成测试或全量构建。
 项目已配置 P3C 时使用既有入口。若未配置，进行人工规则 Review，并把“未运行 P3C”明确写为未验证项，而不是临时修改构建。
 ## 结果报告
 每项验证记录：
 ```text
 命令或检查：
 范围：
 结果：通过 / 失败 / 未执行
 证据摘要：
 失败或未执行原因：
 ```
 只报告本次实际获得的证据。环境错误、既有失败和本次回归必须区分；无法确定归属时标记为待调查，不得猜测。
@@ -0,0 +1,104 @@
 ---
 name: vibe-coding-governance
 description: 面向多种编码 Agent 的 Vibe Coding 全流程规范。凡是评估、规划、实现、修复、重构、审查、验证、测试、交付或归档软件变更，尤其是根据需求文档改造现有项目时使用。采用 SDD 规范驱动与 TDD/验收驱动原则，执行 L0/L1/L2 影响分级、用户确认门禁、需求追溯、项目规范遵循、代码 Review、自我验证、发布记录和逻辑归档。
 ---
 # Vibe Coding 开发规范
 将本技能作为 Vibe Coding 任务的流程规范。核心规则保持平台中立，以便适配 Codex、Claude、OpenCode 或其他编码 Agent。
 ## 核心原则
 遵循以下链路：
 ```text
 规范 → 验收证据 → 测试 → 实现 → 审查 → 验证
 ```
 必须：
 - 区分用户需求、代码事实和 Agent 建议。
 - 提出方案或修改代码前，调查项目及其作用域内的指令。
 - 保留用户已有改动，遵循项目架构、规范和代码风格。
 - 在确认范围内采用最小且充分的改动。
 - 将需求追溯到方案、实现、冒烟用例和验证证据。
 - 暴露矛盾、歧义、缺失决策和扩大影响，禁止主观猜测业务结论。
 - 仅将实际执行的检查标记为通过；无法执行时记录“未验证”及原因。
 - 阶段开始、完成、阻塞、重开或变化时更新状态历史。
 - 对需求、日志、接口请求响应、测试数据和验证证据进行脱敏，禁止保存凭据、密钥和生产敏感数据。
 - 禁止执行 `git add`、`git commit`、`git push`；暂存、提交和推送均由用户执行。其他 Git 命令按任务范围和安全规则使用。
 ## 每个编码请求的开始动作
 1. 阅读 [references/目录索引.md](references/目录索引.md)。
 2. 使用只读操作调查适用的项目指令及相邻代码。
 3. 按最高风险项评估变更影响等级。
 4. 向用户说明建议等级、判断依据、范围、风险和执行流程。
 5. 编码前门禁未通过前，不得修改代码。
 如果请求已经属于既有 PM 任务，继续工作前读取当前需求版本、`STATUS.md`、相关编号文档和代码基线。
 ## 影响等级与门禁
 分级和状态转换参见 [references/01-分级与门禁.md](references/01-分级与门禁.md)。
 - **L0：**确认一次精确的小改动，实施后做最小验证。
 - **L1：**维护一份精简变更日志，确认一次后实施、Review 和验证。
 - **L2：**执行完整流程和三次门禁：
  - G1 确认大需求 `技术侧需求分析.md`、子任务拆分和全部 `01.需求分析.md`。
  - G2 确认 `02.技术实现方案.md` 和 `03.冒烟与逻辑验证.md` 的验证计划部分。
  - G3 确认已完成验证结果的 `03.冒烟与逻辑验证.md`、`04.技术实现记录.md` 和 `05.代码Review报告.md`。
 不得对风险维度取平均值；最高风险特征决定等级。影响扩大时，暂停受影响工作，提出升级、补齐产物并获得确认。未经用户确认不得降级。
 ## 按当前阶段加载参考文件
 - L0 或 L1：读取 [references/02-L0与L1轻量流程.md](references/02-L0与L1轻量流程.md)。
 - L2 接入、原始需求版本、状态、代码副本或矛盾处理：读取 [references/03-需求管理.md](references/03-需求管理.md)。
 - L2 需求分析：读取 [references/04-需求分析.md](references/04-需求分析.md)。
 - 技术方案：读取 [references/05-技术方案设计.md](references/05-技术方案设计.md)。
 - 冒烟自测与逻辑验证：读取 [references/06-冒烟与逻辑验证.md](references/06-冒烟与逻辑验证.md)。
 - 代码实现、项目风格和 TDD：读取 [references/07-代码实现.md](references/07-代码实现.md)。
 - 代码 Review、逻辑验证或本地接口测试：读取 [references/08-代码审查与验证.md](references/08-代码审查与验证.md)。
 - 测试交付、发布、完成、归档或 OpenSpec：读取 [references/09-交付与归档.md](references/09-交付与归档.md)。
 任务跨阶段时读取多个相关文件。L0/L1 任务不得无差别加载全部 L2 规范。
 ## 模板使用
 创建规范文档时，优先使用项目或用户提供的模板；否则使用 [assets/templates/模板索引.md](assets/templates/模板索引.md) 中的内置模板。
 ## 文档约定
 每个 L2 子任务每个阶段只维护一份主文档：
 ```text
 01.需求分析.md
 02.技术实现方案.md
 03.冒烟与逻辑验证.md
 04.技术实现记录.md
 05.代码Review报告.md
 06.验收与交付报告.md
 ```
 编号表示流程顺序，不表示文档版本。一个子任务的全部功能和接口方案集中写入唯一的 `02.技术实现方案.md`，通过目录和稳定的章节编号管理。
 ## 自动化工具
 - 使用 `scripts/init_vibe_task.py` 初始化 L1/L2 文档目录；L2 未确定 PM 编号时使用 `待确认`，并在 G1 需求评审中由用户确定。
 - 使用 `scripts/validate_vibe_docs.py` 在 G1、G2、G3 或归档前检查目录、模板占位符、相对链接和功能追溯。
 - 脚本不得执行 `git add`、`git commit`、`git push`，不得覆盖非空目标文件。
 ## 规则优先级与例外
 在遵守 Agent 平台上层安全规则的前提下，按以下顺序执行：
 ```text
 用户本次明确指示
 → 已确认的任务文档和门禁结论
 → 作用域最近的项目指令
 → 项目自动化规则和模块既有惯例
 → 语言或框架通用惯例
 ```
 这些来源发生实质冲突时，必须提出并请用户确认。项目级例外只有在明确记录后才能覆盖本流程。
@@ -0,0 +1,4 @@
 interface:
  display_name: "Vibe Coding 开发规范"
  short_description: "按 L0/L1/L2 分级门禁执行完整 Vibe Coding 开发流程"
  default_prompt: "使用 $vibe-coding-governance 按约定的 Vibe Coding 规范评估并执行这个开发任务。"
@@ -0,0 +1,74 @@
 # {{ST编号}} {{子任务名称}}需求分析
 ## 1. 文档信息与需求来源
 - 大需求：{{PM编号及链接}}
 - 子任务编号：{{ST编号}}
 - 原始需求版本：{{版本及链接}}
 - 文档版本：{{版本}}
 - 当前状态：{{状态}}
 - 最后更新：{{时间}}
 ## 2. 目标、范围与非范围
 ### 2.1 目标
 ### 2.2 本次范围
 ### 2.3 非本次范围
 ## 3. 业务规则、角色和权限
 ## 4. 业务流程
 ### 4.1 正常流程
 ### 4.2 异常流程
 ### 4.3 状态流转
 ## 5. 功能点清单
 | 功能编号 | 功能名称 | 需求说明 | 验收标准编号 |
 |---|---|---|---|
 | F-001 | {{功能}} | {{说明}} | AC-001 |
 ## 6. 涉及工程及现有实现
 | 工程 | 当前职责 | 现有入口/代码 | 基准 Commit | 与本任务关系 |
 |---|---|---|---|---|
 ## 7. 复用、新增、修改和迁移分析
 | 功能编号 | 分类 | 复用或改造对象 | 说明 |
 |---|---|---|---|
 ## 8. 接口、数据及上下游影响
 ## 9. 非功能与上线要求
 ## 10. 子任务依赖
 ## 11. 验收标准
 | 编号 | 对应功能 | 可观察的完成条件 | 验证方式 |
 |---|---|---|---|
 | AC-001 | F-001 | {{条件}} | {{方式}} |
 ## 12. 需求矛盾、风险和待确认项
 ### 12.1 需求矛盾
 | 编号 | 描述位置 A | 描述 A | 描述位置 B | 描述 B | 影响范围 | 状态 | 确认结论 |
 |---|---|---|---|---|---|---|---|
 ### 12.2 风险与待确认项
 | 编号 | 类型 | 内容 | 影响 | 状态 | 结论 |
 |---|---|---|---|---|---|
 ## 13. 关联文档
 - [大需求总览]({{链接}})
 - [技术实现方案](./02.技术实现方案.md)
 - [冒烟与逻辑验证](./03.冒烟与逻辑验证.md)
@@ -0,0 +1,123 @@
 # {{ST编号}} {{子任务名称}}技术实现方案
 ## 目录
 > 使用 Markdown 目录或维护章节索引。
 ## 1. 文档信息、依据和版本
 - 大需求：{{PM编号及链接}}
 - 子任务：{{ST编号}}
 - 原始需求版本：{{版本}}
 - 需求分析：[01.需求分析.md](./01.需求分析.md)
 - 方案版本：{{版本}}
 - 方案状态：{{状态}}
 - 代码基线：{{工程、分支、Commit}}
 - 最后更新：{{时间}}
 ## 2. 目标、范围和验收依据
 ## 3. 现有实现与复用分析
 | 工程 | 模块/符号 | 当前职责 | 复用或改造方式 | 代码证据 |
 |---|---|---|---|---|
 ## 4. 总体实现方案
 ### 4.1 总体流程
 ### 4.2 模块关系
 ### 4.3 与其他子任务的关系
 ## 5. 功能点和接口总览
 | 功能编号 | 功能名称 | 接口类型 | 接口/方法 | 工程 | 变更类型 | 章节 |
 |---|---|---|---|---|---|---|
 ## 6. 各功能点实现方案
 ### 6.1 F-001 {{功能名称}}
 #### 6.1.1 目标与依据
 #### 6.1.2 涉及工程和模块
 #### 6.1.3 现有逻辑及复用
 #### 6.1.4 实现范围
 #### 6.1.5 正常、异常和边界流程
 #### 6.1.6 接口设计
 #### 6.1.7 业务规则和校验
 #### 6.1.8 数据读写
 #### 6.1.9 权限、事务、并发和幂等
 #### 6.1.10 缓存、搜索和消息
 #### 6.1.11 兼容、测试和风险
 > 为每个功能点重复本节。
 ## 7. 数据模型设计
 ### 7.1 数据库
 | 表/实体 | 字段 | 类型 | 可空 | 默认值 | 索引/约束 | 业务含义 | 变更类型 |
 |---|---|---|---|---|---|---|---|
 ### 7.2 Redis
 | Key | 类型 | Value 结构 | TTL | 数据来源 | 更新/失效策略 |
 |---|---|---|---|---|---|
 ### 7.3 Elasticsearch
 - 索引与 Alias：
 - 文档 ID：
 - Mapping：
 - 文档示例：
 - 同步、重试和 Reindex：
 ### 7.4 跨存储一致性
 ## 8. 跨工程改造与依赖顺序
 | 工程 | 模块 | 改造内容 | 输入 | 输出 | 依赖 |
 |---|---|---|---|---|---|
 ## 9. 变更影响与回归范围
 ### 9.1 影响矩阵
 | 影响编号 | 变更项 | 受影响接口/功能 | 工程 | 类型 | 影响说明 | 是否改造 |
 |---|---|---|---|---|---|---|
 ### 9.2 回归范围
 | 回归编号 | 工程 | 接口/功能 | 回归场景 | 原因 | 优先级 |
 |---|---|---|---|---|---|
 ## 10. 权限、安全、事务、并发和幂等
 ## 11. 非功能、日志、监控和审计
 ## 12. 兼容、迁移、发布和回滚
 ## 13. 测试与验证设计
 ## 14. 实施步骤
 | 顺序 | 工程 | 实施项 | 前置依赖 | 对应功能/验收项 |
 |---|---|---|---|---|
 ## 15. 方案取舍、风险和待确认项
 ## 16. 需求追溯
 | 需求/功能 | 方案章节 | 工程 | 验收标准 | 验证用例 |
 |---|---|---|---|---|
@@ -0,0 +1,91 @@
 # {{ST编号}} {{子任务名称}}冒烟与逻辑验证
 ## 1. 文档信息与验证基线
 - 大需求编号：{{PM编号}}
 - 子任务编号：{{ST编号}}
 - 需求版本：{{版本}}
 - 技术方案版本：{{版本}}
 - 文档版本：{{版本}}
 - 当前状态：{{状态}}
 ## 2. 验证目标、范围和非范围
 - 核心主流程：{{流程}}
 - 本次功能点：{{功能}}
 - 关键回归：{{回归}}
 - 非本次验证范围：{{非范围}}
 ## 3. 环境、前置条件和测试数据
 - 计划环境：{{环境}}
 - 前置依赖：{{依赖}}
 - 测试数据及脱敏要求：{{数据}}
 ## 4. 验证计划
 > 第 1–4 节在 G2 前完成并确认。
 ### 4.1 静态检查、构建和自动化测试计划
 | 编号 | 检查/测试 | 计划命令或方式 | 预期结果 |
 |---|---|---|---|
 ### 4.2 冒烟及功能用例
 | 编号 | 功能点 | 验证场景 | 前置条件 | 操作步骤 | 预期结果 | 验证类型 |
 |---|---|---|---|---|---|---|
 | TC-001 | F-001 | {{场景}} | {{条件}} | {{步骤}} | {{预期}} | {{接口/自动化/人工}} |
 ### 4.3 关键影响回归计划
 | 回归编号 | 影响编号 | 工程/功能 | 回归场景 | 预期结果 |
 |---|---|---|---|---|
 ## 5. 实际执行基线
 > 第 5–12 节在代码实现和 Review 后填写。
 - 实际环境：{{环境}}
 - 工程和分支：{{记录}}
 - Commit 或版本标识：{{记录}}
 - 执行时间：{{时间}}
 ## 6. 静态检查、构建和自动化测试结果
 | 编号 | 实际命令或方式 | 结果 | 证据或说明 |
 |---|---|---|---|
 ## 7. 冒烟及功能用例结果
 | 用例编号 | 实际结果 | 状态 | 脱敏证据 | 执行时间 |
 |---|---|---|---|---|
 ## 8. 关键回归结果
 | 回归编号 | 实际结果 | 状态 | 脱敏证据 |
 |---|---|---|---|
 ## 9. 接口和数据验证
 - 接口：
 - 数据库：
 - Redis：
 - Elasticsearch：
 - 消息及异步任务：
 - 日志和监控：
 ## 10. 失败、修复和重验
 | 编号 | 失败内容 | 原因 | 修复 | 重验结果 |
 |---|---|---|---|---|
 ## 11. 未执行项、遗留问题和风险
 ## 12. 验证结论
 - 核心主流程是否通过：{{是/否}}
 - 范围内功能是否全部验证：{{是/否}}
 - 是否存在阻断问题：{{是/否}}
 - 未验证项：{{内容}}
 - 是否具备提测条件：{{是/否}}
@@ -0,0 +1,38 @@
 # {{ST编号}} {{子任务名称}}冒烟自测用例
 ## 1. 文档信息
 - 大需求编号：{{PM编号}}
 - 子任务编号：{{ST编号}}
 - 需求版本：{{版本}}
 - 技术方案版本：{{版本}}
 - 提测版本或 Commit：{{Commit}}
 - 测试环境：{{环境}}
 ## 2. 自测范围
 - 核心主流程：{{流程}}
 - 本次功能点：{{功能}}
 - 关键回归：{{回归}}
 - 非本次自测范围：{{非范围}}
 ## 3. 前置条件和测试数据
 ## 4. 冒烟自测用例
 | 编号 | 功能点 | 验证场景 | 前置条件 | 操作步骤 | 预期结果 | 实际结果 | 状态 | 证据 |
 |---|---|---|---|---|---|---|---|---|
 | TC-001 | F-001 | {{场景}} | {{条件}} | {{步骤}} | {{预期}} | | 未执行 | |
 ## 5. 功能覆盖检查
 | 功能编号 | 功能名称 | 对应用例 | 是否已验证 |
 |---|---|---|---|
 ## 6. 自测结论
 - 核心主流程是否通过：{{是/否/未执行}}
 - 需求功能点是否全部验证：{{是/否}}
 - 是否存在阻断问题：{{是/否}}
 - 未通过或未验证项：{{内容}}
 - 是否具备提测条件：{{是/否}}
@@ -0,0 +1,54 @@
 # {{ST编号}} {{子任务名称}}技术实现记录
 ## 1. 实现信息
 - 需求版本：{{版本}}
 - 技术方案版本：{{版本}}
 - 开发工程：{{工程}}
 - 开发分支：{{记录}}
 - 实现前 Commit：{{记录}}
 - 实现后 Commit：{{记录}}
 - 当前状态：{{状态}}
 ## 2. 功能实现状态
 | 功能编号 | 功能名称 | 涉及工程 | 实现状态 | 方案章节 | 备注 |
 |---|---|---|---|---|---|
 ## 3. 工程及代码改动
 | 工程 | 模块/文件 | 改动内容 | 对应功能 |
 |---|---|---|---|
 ## 4. 数据模型改动
 - 数据库：
 - Redis：
 - Elasticsearch：
 - 数据迁移：
 ## 5. 接口改动
 ## 6. 自动化测试改动
 ## 7. 与技术方案的差异
 ## 8. 编译和测试结果
 | 检查项 | 命令/方式 | 结果 | 说明 |
 |---|---|---|---|
 ## 9. 项目规范遵循情况
 - 已读取项目规范：
 - 参考的同类实现：
 - 执行的格式化或静态检查：
 - 与既有风格的差异及原因：
 ## 10. 遗留问题及风险
 ## 11. 敏感信息与 Git 操作确认
 - 文档、日志和验证证据是否完成脱敏：{{是/否}}
 - Agent 是否执行过 `git add`、`git commit`、`git push`：否
 - Git 分支、Commit 和差异：{{记录}}
@@ -0,0 +1,52 @@
 # {{ST编号}} {{子任务名称}}代码 Review 报告
 ## 1. Review 信息
 - 需求版本：{{版本}}
 - 技术方案版本：{{版本}}
 - 工程及分支：{{工程/分支}}
 - Review Commit：{{Commit}}
 - Review 范围：{{范围}}
 - 变更清单或差异来源：{{用户提供/本次编辑记录}}
 - Review 时间：{{时间}}
 ## 2. 需求符合性
 | 检查项 | 结论 | 说明 |
 |---|---|---|
 | 需求功能覆盖 | | |
 | 技术方案符合 | | |
 | 影响范围处理 | | |
 | 无范围外实现 | | |
 ## 3. 项目规范符合性
 | 检查项 | 结论 | 说明 |
 |---|---|---|
 | 架构与分层 | | |
 | 命名与代码风格 | | |
 | 异常、日志和错误码 | | |
 | 测试风格 | | |
 ## 4. 核心架构变化
 | 检查项 | 是否变化 | 是否符合方案 | 结论 |
 |---|---|---|---|
 ## 5. Review 问题
 | 编号 | 等级 | 工程及位置 | 问题 | 影响 | 处理状态 |
 |---|---|---|---|---|---|
 ## 6. 问题修复及复查
 | 问题编号 | 修复内容 | 复查结果 | 证据 |
 |---|---|---|---|
 ## 7. 未确认风险
 ## 8. Review 结论
 - Critical/High 是否清零：{{是/否}}
 - 是否需要重开方案门禁：{{是/否}}
 - 结论：在本次检查范围内{{结论}}
@@ -0,0 +1,55 @@
 # {{ST编号}} {{子任务名称}}逻辑验证报告
 ## 1. 验证信息
 - 需求版本：{{版本}}
 - 技术方案版本：{{版本}}
 - 验证工程和分支：{{工程/分支}}
 - 验证 Commit：{{Commit}}
 - 验证环境：{{环境}}
 - 验证时间：{{时间}}
 ## 2. 静态检查与构建
 | 检查项 | 命令/方式 | 结果 | 证据或说明 |
 |---|---|---|---|
 ## 3. 自动化测试
 | 测试类型 | 测试范围 | 通过 | 失败 | 结果 |
 |---|---|---|---|---|
 ## 4. 冒烟自测
 | 用例编号 | 功能点 | 预期结果 | 实际结果 | 状态 | 证据 |
 |---|---|---|---|---|---|
 ## 5. 关键回归
 | 回归编号 | 场景 | 结果 | 证据 |
 |---|---|---|---|
 ## 6. 接口与数据验证
 - 接口：
 - 数据库：
 - Redis：
 - Elasticsearch：
 - 消息及异步任务：
 - 日志和监控：
 ## 7. 失败与修复
 | 编号 | 失败 | 原因 | 修复 | 重验结果 |
 |---|---|---|---|---|
 ## 8. 未执行项及原因
 ## 9. 遗留问题和风险
 ## 10. 验证结论
 - 核心主流程是否通过：{{是/否}}
 - 范围内功能是否全部验证：{{是/否}}
 - 是否存在阻断问题：{{是/否}}
 - 是否具备提测条件：{{是/否}}
@@ -0,0 +1,54 @@
 # {{ST编号}} {{子任务名称}}验收与交付报告
 ## 1. 交付信息
 - 需求版本：{{版本}}
 - 涉及工程：{{工程}}
 - 开发分支：{{分支}}
 - 发布分支或 Tag：{{分支/Tag}}
 - 发布 Commit：{{Commit}}
 - Git 信息来源：{{用户提供的记录}}
 ## 2. 开发交付内容
 ## 3. 测试结果
 - 测试环境：{{环境}}
 - 测试时间：{{时间}}
 - 测试人员：{{人员}}
 - 测试结论：{{结论}}
 - 缺陷及处理情况：{{内容}}
 - 测试报告：{{链接或编号}}
 ## 4. 发布记录
 - 发布时间：{{时间}}
 - 发布环境：{{环境}}
 - 发布版本：{{版本}}
 - 发布工程：{{工程}}
 - 数据脚本：{{脚本}}
 - 配置变化：{{配置}}
 - 实际发布顺序：{{顺序}}
 ## 5. 上线验证
 | 检查项 | 验证方式 | 结果 | 证据 |
 |---|---|---|---|
 | 核心主流程 | | | |
 | 关键接口 | | | |
 | 数据库 | | | |
 | Redis | | | |
 | Elasticsearch | | | |
 | 消息及任务 | | | |
 | 日志和监控 | | | |
 ## 6. 遗留问题
 ## 7. 最终结论
 - 是否测试通过：{{是/否}}
 - 是否发布成功：{{是/否}}
 - 是否完成上线验证：{{是/否}}
 - 是否满足归档条件：{{是/否}}
 > `git add`、`git commit`、`git push` 由用户执行；报告证据必须脱敏。
@@ -0,0 +1,51 @@
 # {{ST编号}} {{子任务名称}}验收与交付报告
 ## 1. 交付信息
 - 需求版本：{{版本}}
 - 涉及工程：{{工程}}
 - 开发分支：{{分支}}
 - 发布分支或 Tag：{{分支/Tag}}
 - 发布 Commit：{{Commit}}
 ## 2. 开发交付内容
 ## 3. 测试结果
 - 测试环境：{{环境}}
 - 测试时间：{{时间}}
 - 测试人员：{{人员}}
 - 测试结论：{{结论}}
 - 缺陷及处理情况：{{内容}}
 - 测试报告：{{链接或编号}}
 ## 4. 发布记录
 - 发布时间：{{时间}}
 - 发布环境：{{环境}}
 - 发布版本：{{版本}}
 - 发布工程：{{工程}}
 - 数据脚本：{{脚本}}
 - 配置变化：{{配置}}
 - 实际发布顺序：{{顺序}}
 ## 5. 上线验证
 | 检查项 | 验证方式 | 结果 | 证据 |
 |---|---|---|---|
 | 核心主流程 | | | |
 | 关键接口 | | | |
 | 数据库 | | | |
 | Redis | | | |
 | Elasticsearch | | | |
 | 消息及任务 | | | |
 | 日志和监控 | | | |
 ## 6. 遗留问题
 ## 7. 最终结论
 - 是否测试通过：{{是/否}}
 - 是否发布成功：{{是/否}}
 - 是否完成上线验证：{{是/否}}
 - 是否满足归档条件：{{是/否}}
@@ -0,0 +1,71 @@
 # {{需求名称}}精简变更日志
 ## 1. 基本信息
 - 需求编号：{{编号}}
 - 影响等级：L1
 - 当前状态：{{状态}}
 - 创建时间：{{时间}}
 - 最后更新：{{时间}}
 ## 2. 需求说明
 {{需求内容及来源}}
 ## 3. 变更范围
 - 涉及工程：{{工程}}
 - 涉及功能：{{功能}}
 - 涉及接口：{{接口}}
 - 非本次范围：{{非范围}}
 ## 4. 影响及回归范围
 | 变更项 | 受影响功能/接口 | 影响说明 | 回归场景 |
 |---|---|---|---|
 ## 5. 技术实现计划
 - 现有逻辑：{{现状}}
 - 复用内容：{{复用}}
 - 计划改动：{{改动}}
 - 数据变化：{{数据}}
 - 风险与待确认项：{{风险}}
 ## 6. 冒烟自测用例
 | 编号 | 功能点 | 验证场景 | 预期结果 |
 |---|---|---|---|
 ## 7. 用户确认记录
 - 确认结论：{{结论}}
 - 确认时间：{{时间}}
 - 确认来源：{{来源}}
 ## 8. 实际代码改动
 | 工程/文件 | 实际改动 | 对应功能 |
 |---|---|---|
 ## 9. Code Review
 | 编号 | 等级 | 问题 | 处理结果 |
 |---|---|---|---|
 ## 10. 逻辑验证和冒烟结果
 | 检查/用例 | 执行方式 | 结果 | 证据 |
 |---|---|---|---|
 ## 11. 遗留问题
 {{遗留问题或“无”}}
 ## 12. 完成结论
 - 是否开发完成：{{是/否}}
 - 是否具备提测条件：{{是/否}}
 - 未验证项：{{内容}}
 - 文档和证据是否完成脱敏：{{是/否}}
 - Agent 是否执行过 `git add`、`git commit`、`git push`：否
@@ -0,0 +1,11 @@
 # 代码分析副本清单
 | 工程 | 本地目录 | 远端仓库 | 基准分支 | 当前 Commit | 更新时间 | 备注 |
 |---|---|---|---|---|---|---|
 ## 异常记录
 | 时间 | 工程 | 异常 | 处理状态 |
 |---|---|---|---|
 > `code/` 只用于调查；需求开发在独立项目工作区完成。
@@ -0,0 +1,40 @@
 # {{PM编号}} 任务状态
 ## 1. 大需求状态
 - 需求名称：{{名称}}
 - 当前需求版本：{{版本}}
 - 当前总体状态：{{状态}}
 - 当前主要阶段：{{阶段}}
 - 最后更新时间：{{时间}}
 - 当前阻塞项：{{阻塞或“无”}}
 ## 2. 门禁状态
 | 门禁 | 状态 | 原始需求版本 | 确认文档及版本 | 代码版本标识 | 确认时间 | 确认来源 | 确认范围/说明 |
 |---|---|---|---|---|---|---|---|
 | G1 需求门禁 | 待确认 | | | 不适用 | | | |
 | G2 方案门禁 | 未开始 | | | | | | |
 | G3 开发交付门禁 | 未开始 | | | | | | |
 ## 3. 子任务状态
 | 子任务 | 业务模块 | 当前阶段 | 当前状态 | 阻塞项 | 最后更新 |
 |---|---|---|---|---|---|
 ## 4. 阶段完成情况
 | 子任务 | 需求分析 | 技术方案 | 验证计划 | 实现 | Review | 逻辑验证 | 测试 | 上线 |
 |---|---|---|---|---|---|---|---|---|---|
 ## 5. 阻塞事项
 | 编号 | 子任务 | 阻塞内容 | 影响阶段 | 提出时间 | 处理方 | 状态 |
 |---|---|---|---|---|---|---|
 ## 6. 状态变更历史
 | 时间 | 对象 | 原阶段/状态 | 新阶段/状态 | 变更原因 | 操作者 | 证据 |
 |---|---|---|---|---|---|---|
 > `STATUS.md` 是状态唯一事实来源。其他文档中的状态字段仅用于展示，发生冲突时以本文件为准。
@@ -0,0 +1,16 @@
 # 原始需求版本索引
 | 版本 | 接收时间 | 需求来源 | 文件或目录 | 主要变化 | 状态 |
 |---|---|---|---|---|---|
 | v1 | {{时间}} | {{来源}} | [查看](./v1/) | 初始版本 | 当前版本 |
 ## 补充需求记录
 | 编号 | 时间 | 来源 | 内容 | 是否进入正式版本 |
 |---|---|---|---|---|
 ## 管理规则
 - 原始文件只读，不覆盖旧版本。
 - 每个版本尽量保存完整材料。
 - 新版本到达后进行差异和影响分析。
@@ -0,0 +1,36 @@
 # {{PM编号}} {{需求名称}}
 ## 1. 基本信息
 - 大需求编号：{{PM编号}}
 - 当前需求版本：{{版本}}
 - 当前状态：{{状态}}
 - 创建时间：{{时间}}
 - 最后更新：{{时间}}
 ## 2. 需求来源
 - [原始需求版本索引](./source/README.md)
 - 当前需求版本：{{相对链接}}
 ## 3. 技术侧需求分析
 - [技术侧需求分析](./技术侧需求分析.md)
 ## 4. 子任务
 | 编号 | 业务模块 | 当前阶段 | 当前状态 | 前置依赖 | 需求分析 |
 |---|---|---|---|---|---|
 | ST-001 | {{模块}} | {{阶段}} | {{状态}} | {{依赖}} | [查看](./tasks/ST-001-模块/01.需求分析.md) |
 ## 5. 代码基线
 - [代码副本清单](./code/MANIFEST.md)
 ## 6. 状态与门禁
 - [任务状态](./STATUS.md)
 ## 7. 归档
 测试、上线和上线验证完成后生成 `归档记录.md`，并在此补充链接。
@@ -0,0 +1,72 @@
 # {{PM编号}} {{需求名称}}归档记录
 ## 1. 基本信息
 - 大需求编号：{{PM编号}}
 - 需求名称：{{名称}}
 - 最终需求版本：{{版本}}
 - 需求负责人：{{负责人}}
 - 开发完成时间：{{时间}}
 - 测试通过时间：{{时间}}
 - 上线时间：{{时间}}
 - 归档时间：{{时间}}
 - 最终状态：已归档
 ## 2. 需求目标与最终范围
 - 需求背景：{{背景}}
 - 最终实现范围：{{范围}}
 - 未实现、延期或取消范围：{{内容}}
 - 需求变更摘要：{{摘要}}
 ## 3. 子任务完成情况
 | 子任务 | 业务模块 | 开发状态 | 测试状态 | 上线状态 | 文档 |
 |---|---|---|---|---|---|
 ## 4. 工程发布信息
 | 工程 | 发布分支 | 发布版本/Tag | 上线 Commit | 上线时间 |
 |---|---|---|---|---|
 ## 5. 数据及配置变更
 - 数据库：
 - Redis：
 - Elasticsearch：
 - 配置中心：
 - 数据迁移：
 - 其他：
 ## 6. 测试和验证结论
 - Code Review：
 - 冒烟与逻辑验证：
 - 测试人员测试：
 - 上线验证：
 ## 7. 关键文档索引
 - 原始需求：
 - 技术侧需求分析：
 - 子任务需求分析：
 - 技术实现方案：
 - 冒烟与逻辑验证：
 - Code Review：
 - 验收与交付：
 ## 8. 遗留问题和已知风险
 | 编号 | 问题 | 影响 | 当前处理 | 后续建议 |
 |---|---|---|---|---|
 ## 9. 后续维护说明
 - 可复用能力：
 - 维护注意事项：
 - 后续优化方向：
 - 关联需求：
 ## 10. 归档结论
 {{最终结论}}
@@ -0,0 +1,50 @@
 # {{PM编号}} 技术侧需求分析
 ## 1. 文档信息
 - 需求名称：{{名称}}
 - 当前需求版本：{{版本}}
 - 文档版本：{{版本}}
 - 文档状态：{{状态}}
 - 依据代码版本：[MANIFEST](./code/MANIFEST.md)
 - 最后更新：{{时间}}
 ## 2. 需求背景与目标
 ## 3. 技术侧需求解读
 ## 4. 范围与非范围
 ### 4.1 本次范围
 ### 4.2 非本次范围
 ## 5. 业务模块及子任务拆分
 | 子任务 | 业务模块 | 目标 | 依赖 |
 |---|---|---|---|
 ## 6. 功能迭代清单
 ### 6.1 新增
 ### 6.2 修改
 ### 6.3 复用
 ### 6.4 废弃或迁移
 ## 7. 涉及工程
 | 工程 | 当前职责 | 涉及功能 | 影响原因 | 预计变更类型 | 证据 |
 |---|---|---|---|---|---|
 ## 8. 接口、数据及上下游影响
 ## 9. 非功能需求
 ## 10. 发布、迁移、兼容和回滚要求
 ## 11. 依赖、风险和待确认项
 ## 12. 子任务文档索引
@@ -0,0 +1,21 @@
 # Vibe Coding 模板索引
 项目或用户提供的模板优先；没有专用模板时复制以下内置模板。
 | 模板 | 用途 | 建议落地文件 |
 |---|---|---|
 | [L1-精简变更日志模板.md](L1-精简变更日志模板.md) | L1 单文档全流程 | `01.精简变更日志.md` |
 | [大需求总览模板.md](大需求总览模板.md) | L2 大需求导航 | `README.md` |
 | [任务状态模板.md](任务状态模板.md) | 当前状态、门禁、阻塞和历史 | `STATUS.md` |
 | [原始需求版本索引模板.md](原始需求版本索引模板.md) | source 版本索引 | `source/README.md` |
 | [代码副本清单模板.md](代码副本清单模板.md) | 分析代码基线 | `code/MANIFEST.md` |
 | [技术侧需求分析模板.md](技术侧需求分析模板.md) | 大需求的研发侧功能解读 | `技术侧需求分析.md` |
 | [01-需求分析模板.md](01-需求分析模板.md) | L2 子任务需求分析 | `01.需求分析.md` |
 | [02-技术实现方案模板.md](02-技术实现方案模板.md) | L2 子任务单文档技术方案 | `02.技术实现方案.md` |
 | [03-冒烟与逻辑验证模板.md](03-冒烟与逻辑验证模板.md) | G2 验证计划和 G3 实际验证结果 | `03.冒烟与逻辑验证.md` |
 | [04-技术实现记录模板.md](04-技术实现记录模板.md) | 实际代码改动记录 | `04.技术实现记录.md` |
 | [05-代码Review报告模板.md](05-代码Review报告模板.md) | 代码审查 | `05.代码Review报告.md` |
 | [06-验收与交付报告模板.md](06-验收与交付报告模板.md) | 测试、上线和交付 | `06.验收与交付报告.md` |
 | [归档记录模板.md](归档记录模板.md) | 大需求逻辑归档 | `归档记录.md` |
 复制后删除不适用的示例行，但保留必要章节；不适用的关键章节写明原因。
@@ -0,0 +1,94 @@
 # 影响分级与确认门禁
 ## 按最高影响分级
 评估业务行为、工程数量、接口契约、数据、架构、权限与安全、回归范围、发布协同和可回滚性。最高风险维度决定最终等级。
 | 维度 | L0 | L1 | L2 |
 |---|---|---|---|
 | 业务行为 | 不改变运行行为 | 小范围行为变化 | 核心流程或多模块变化 |
 | 工程 | 单个极小位置 | 单工程或少量模块 | 多工程或跨服务 |
 | 接口 | 不涉及 | 少量兼容性变化 | 大量或破坏性变化 |
 | 数据 | 不涉及 | 小范围兼容调整 | 迁移、重构或跨存储变化 |
 | 架构 | 不涉及 | 核心架构不变 | 架构或依赖方向变化 |
 | 安全 | 不涉及 | 低风险局部逻辑 | 核心权限、隔离或敏感数据 |
 | 回归 | 极小 | 清晰且可控 | 广泛、复杂或不确定 |
 | 发布 | 简单 | 可控且容易回滚 | 多方协同、高风险或难回滚 |
 注释、拼写、静态文案和非行为性文档只有在不改变配置、契约、合规含义或运行行为时才属于 L0。
 典型 L1 包括范围明确的 CRUD、兼容性接口调整或影响已知的小型缺陷修复。
 典型 L2 包括跨服务改造、核心流程重构、破坏性接口、复杂迁移、大范围权限调整、广泛回归、多工程协同发布或影响明显不确定。
 ## 提出分级建议
 修改代码前输出：
 ```markdown
 ## 变更影响等级评估
 - 建议等级：
 - 判断依据：
 - 涉及业务：
 - 涉及工程：
 - 接口影响：
 - 数据影响：
 - 架构影响：
 - 回归范围：
 - 主要风险：
 - 建议执行流程：
 ```
 最终等级由用户确认。确认前允许只读调查。
 ## 门禁
 ### L0
 一次性确认具体改动、位置、影响和最小验证方式，然后实施并验证。
 ### L1
 完成 `01.精简变更日志.md` 的计划部分，包括需求、范围、方案、影响与回归、冒烟用例。编码前确认一次，然后实施、Review、验证并补全同一份日志。
 ### L2
 执行三次门禁：
 1. **G1 需求门禁：**确认大需求 `技术侧需求分析.md`、业务子任务拆分、全部 `01.需求分析.md`、范围、矛盾和待决事项。
 2. **G2 方案门禁：**确认 `02.技术实现方案.md` 和 `03.冒烟与逻辑验证.md` 第 1–4 节，包括接口与数据设计、影响、回归和验证计划。
 3. **G3 开发交付门禁：**提交完成执行结果的 `03.冒烟与逻辑验证.md`、`04.技术实现记录.md` 和 `05.代码Review报告.md`，确认可以交给测试人员。
 代码 Review 和验证是实现后的强制质量动作，不得在其执行前人为增加确认门禁。
 在 `STATUS.md` 记录门禁状态：
 ```text
 G1 需求门禁：待确认 / 已通过
 G2 方案门禁：待确认 / 已通过
 G3 开发交付门禁：待确认 / 已通过
 ```
 每次门禁必须绑定：
 - 当前原始需求版本；
 - 本门禁确认的文档及文档版本；
 - 相关代码分支、Commit 或等价版本标识；
 - 确认时间、确认来源和确认范围。
 门禁通过后，确认对象发生实质修改时，将门禁改为“需要重新确认”，记录失效原因并停止进入下一阶段。仅修正错别字、链接等不改变语义的编辑可以保留门禁，但要写入状态历史。
 ## 重开与升级
 出现以下情况时，暂停受影响工作并退回失效阶段：
 - 出现需求矛盾；
 - 必须改变已确认的业务规则；
 - 影响扩大到其他工程或核心功能；
 - 接口兼容、数据设计或架构发生实质变化；
 - 原方案不可行；
 - 需要破坏性或不可逆操作。
 新证据触发更高等级时必须升级，并在继续前补齐产物。只有用户明确确认后才能降级。
 不改变已确认行为、契约、数据、架构和影响范围的私有实现调整无需重开门禁，但要写入实现记录。
@@ -0,0 +1,113 @@
 # L0 与 L1 轻量流程
 ## L0
 仅对影响极小且不改变运行行为的变更使用 L0。
 ```text
 理解并定位
 → 说明具体改动和影响
 → 用户确认
 → 修改
 → 检查差异
 → 执行最小必要验证
 → 报告结果
 ```
 确认内容可以很精简：
 ```markdown
 变更等级：L0
 计划修改：
 - ...
 影响范围：
 - ...
 验证方式：
 - ...
 ```
 L0 不创建完整的 L2 PM 文档集，但仍必须保留用户已有改动、遵循项目规则、检查最终差异，并说明实际执行了哪些验证。
 如果看似简单的修改会改变配置、运行行为、对外含义、契约或业务规则，必须升级。
 ## L1
 维护一份持续更新的文档：
 ```text
 01.精简变更日志.md
 ```
 落地位置分两种情况：
 - 独立需求：放在该需求的 `management/PM-<编号>-<名称>/` 大需求根目录下。
 - 大需求下的子任务：放在对应 `tasks/ST-<编号>-<名称>/` 子任务目录内。
 PM 编号尚未确定时使用 `PM-待确认-<需求名称>`，在本次 L1 编码前确认中由用户决定后再改为正式目录。Agent 不得自行生成永久编号。
 编码前完成第 1–6 节并取得一次确认；编码后补充第 7–12 节。
 ```markdown
 # 精简变更日志
 ## 1. 基本信息
 - 需求编号：
 - 需求名称：
 - 影响等级：L1
 - 当前状态：
 ## 2. 需求说明
 ## 3. 变更范围
 - 涉及工程：
 - 涉及功能：
 - 涉及接口：
 - 非本次范围：
 ## 4. 影响及回归范围
 ## 5. 技术实现计划
 - 现有逻辑：
 - 复用内容：
 - 计划改动：
 - 数据变化：
 - 风险与待确认项：
 ## 6. 冒烟自测用例
 | 功能点 | 验证场景 | 预期结果 |
 |---|---|---|
 ## 7. 用户确认记录
 ## 8. 实际代码改动
 ## 9. Code Review
 ## 10. 逻辑验证和冒烟结果
 ## 11. 遗留问题
 ## 12. 完成结论
 ```
 执行流程：
 ```text
 只读调查
 → 编写计划部分
 → 用户确认一次
 → 实现
 → Review
 → 逻辑验证和冒烟
 → 补全日志
 → 标记开发完成
 ```
 编码前可以写 Review 检查范围，但不能伪造 Review 结论。实际 Review 和测试结果只能在执行后填写。
 如果发现广泛依赖、核心架构变化、破坏性兼容问题、复杂迁移或无法界定的回归范围，升级为 L2。
 Agent 在 L1 中不得执行 `git add`、`git commit`、`git push`；暂存、提交和推送由用户完成。变更日志中的请求响应、日志和测试证据必须脱敏。
@@ -0,0 +1,144 @@
 # L2 需求管理
 ## PM 目录
 收到新的 L2 需求后创建：
 ```text
 management/
 └─ PM-<大需求编号>-<需求名称>/
   ├─ README.md
   ├─ STATUS.md
   ├─ 技术侧需求分析.md
   ├─ source/
   │  ├─ README.md
   │  ├─ v1/
   │  └─ v2/
   ├─ code/
   │  └─ MANIFEST.md
   └─ tasks/
      └─ ST-001-<业务模块>/
         ├─ 01.需求分析.md
         ├─ 02.技术实现方案.md
         ├─ 03.冒烟与逻辑验证.md
         ├─ 04.技术实现记录.md
         ├─ 05.代码Review报告.md
         └─ 06.验收与交付报告.md
 ```
 测试、上线和上线验证完成后，在大需求根目录新增一份 `归档记录.md`；不移动整个目录。
 PM 编号由用户决定。尚未提供编号时，可以使用：
 ```text
 PM-待确认-<需求名称>
 ```
 作为需求分析期间的临时目录，并将 PM 编号列为 G1 需求评审的必确认项。用户确定编号后，在进入技术方案阶段前重命名为正式目录，并检查外部链接。Agent 不得自行生成永久 PM 编号。
 大需求 `README.md` 负责总览和子任务索引。使用相对链接，并维护大需求与每个子任务之间的双向关联。
 ## 原始需求版本
 将每次收到的需求保存为完整、不可变的版本快照：
 ```text
 source/v1/
 source/v2/
 source/v3/
 ```
 不得覆盖或修改原始文件。在 `source/README.md` 中记录版本、接收时间、来源、主要变化和当前/废止状态。对话中的临时补充在进入正式版本前，应作为补充需求单独记录。
 收到新版本后：
 1. 比较新旧版本；
 2. 识别受影响的模块、需求、方案、用例和实现；
 3. 重开失效阶段；
 4. 更新状态历史；
 5. 已通过门禁失效时重新确认。
 除非变更说明明确，不得假设新版本自动解决了旧版本中的矛盾。
 ## 代码分析副本
 用户在 `code/` 下维护分析用代码副本，默认基准分支为 `master`，项目另有配置时以项目为准。Agent 可以执行只读 Git 检查和安全的基准分支同步，但不得执行 `git add`、`git commit`、`git push`。
 更新流程：
 ```text
 检查仓库状态
 → 确认基准分支和本地无业务修改
 → 使用只允许安全快进的方式获取更新
 → 记录工程、分支、最新 Commit 和更新时间
 → 更新 MANIFEST
 → 重新判断既有分析是否过期
 ```
 Agent 不得在副本中实现需求。允许使用 `git status`、`git diff`、`git log` 和安全同步命令调查；发现脏工作区、错误分支、历史分叉或无法安全快进时停止并报告，不得强制重置或擅自解决分叉。
 维护 `code/MANIFEST.md`：
 | 工程 | 本地目录 | 远端仓库 | 基准分支 | 当前 Commit | 更新时间 |
 |---|---|---|---|---|---|
 真正的需求开发在独立的项目开发工作区中完成。
 ## 需求矛盾与歧义
 需求前后冲突、版本描述不一致、语义歧义或关键条件缺失时，禁止猜测。
 在相关 `01.需求分析.md` 中记录：
 | 编号 | 描述位置 A | 描述 A | 描述位置 B | 描述 B | 影响范围 | 状态 | 确认结论 |
 |---|---|---|---|---|---|---|---|
 使用 `RC-001` 等稳定编号。展示两处描述，说明受影响模块和功能，列出可能理解但不代替用户选择，并请求确认。
 确认前：
 - 标记为 `待确认`；
 - 不设计或实现受影响的业务决策；
 - 安全时可以继续不受影响的工作；
 - 无法继续时将子任务标记为待确认或阻塞。
 确认后记录结论、确认人、时间、来源和受影响文档，并同步更新。
 ## 状态历史
 以 `STATUS.md` 作为当前状态和历史记录的唯一事实来源。阶段和状态分开维护。
 阶段：
 ```text
 需求接入 → 需求分析 → 技术方案设计 → 冒烟用例设计
 → 技术实现 → Code Review → 逻辑验证 → 测试 → 发布 → 归档
 ```
 状态：
 ```text
 未开始 / 进行中 / 待确认 / 已阻塞 / 待评审 / 已完成 / 已跳过 / 已取消
 ```
 记录：
 - 大需求状态摘要；
 - 每个子任务的当前阶段和状态；
 - G1/G2/G3 状态；
 - 阻塞事项；
 - 只追加的变更历史，包括时间、对象、原/新状态、原因、操作者和证据链接。
 不得删除或改写历史来掩盖返工。旧记录有误时追加更正。验证或测试失败时，重新打开实现阶段并记录回退。
 门禁记录必须包含确认的原始需求版本、文档及文档版本、用户提供的代码版本标识、确认时间、来源和范围。文档中的“当前状态”字段只作为展示，发生冲突时以 `STATUS.md` 为准。
 当前状态表：
 | 子任务 | 业务模块 | 当前阶段 | 当前状态 | 阻塞项 | 最后更新 |
 |---|---|---|---|---|---|
 历史表：
 | 时间 | 对象 | 原阶段/状态 | 新阶段/状态 | 原因 | 操作者 | 证据 |
 |---|---|---|---|---|---|---|
@@ -0,0 +1,125 @@
 # L2 需求分析
 ## 目标和边界
 将业务需求转换为研发可理解的功能范围和业务子任务，说明需要改变哪些能力、可能涉及哪些工程。本阶段描述“需要开发什么”，不展开完整实现设计。
 ## 执行流程
 ```text
 归档原始需求版本
 → 通读全部材料
 → 识别矛盾和问题
 → 按业务能力拆分
 → 更新并阅读代码副本
 → 调查架构、文档、接口和代码
 → 识别涉及工程及复用
 → 编写技术侧需求解读
 → 编写各子任务 01 文档
 → 更新关联和 STATUS
 → 提交 G1
 ```
 拆分前必须完整阅读需求及相关附件。
 ## 按业务模块拆分
 使用可独立识别的业务能力，例如：
 ```text
 品牌重构
 ├─ 品牌管理
 ├─ 品牌审核
 └─ 品牌授权
 ```
 子任务应具备可识别的业务目标、参与者/流程/状态边界、验收结果或独立交付能力。不得将前端、后端、数据库直接作为一级业务子任务；技术工作放入适用的业务子任务内部。
 记录前后置依赖、共享能力、接口、数据、联调顺序和联合测试要求。只有跨模块公共能力可以独立设计、交付和验证时，才建立公共技术子任务。
 ## 技术侧需求解读
 需求分析应说明：
 - 业务背景和目标；
 - 对业务需求的技术侧解读；
 - 范围和非目标；
 - 业务模块与子任务；
 - 需要新增、修改、复用、废弃或迁移的功能；
 - 涉及工程及原因；
 - 现有能力和复用判断；
 - 接口、数据及上下游影响；
 - 非功能要求；
 - 发布、迁移、灰度、兼容、回滚和上线后验证要求；
 - 依赖、风险和待确认项。
 本阶段不提供完整类与方法设计、完整字段级接口定义、详细表结构或逐文件实现步骤。
 使用 `已确认`、`待确认`、`待代码核实`、`技术建议` 标注结论来源。不得将推导结果写成原始需求事实。
 ## 识别涉及工程
 根据架构文档和已记录 Commit 的代码证据调查：
 - 入口和调用链；
 - 模块依赖；
 - 现有接口及调用方；
 - 领域与数据模型；
 - 认证和授权；
 - 消息、事件和定时任务；
 - 下游与外部系统。
 记录：
 | 工程 | 当前职责 | 涉及模块 | 影响原因 | 预计变更类型 | 证据 |
 |---|---|---|---|---|---|
 不得只根据仓库名称推断。
 ## 复用分析
 每个功能按以下类型分类：
 ```text
 直接复用 / 扩展复用 / 适配复用 / 需要修改 / 需要新增 / 需要废弃或迁移 / 待确认
 ```
 指出具体接口、模块或代码符号及其复用边界。用户指定原接口时，记录当前调用方、当前行为、问题、目标行为、兼容性、保留/废弃策略、影响和回归需求。
 ## `01.需求分析.md`
 每个子任务至少包含：
 ```markdown
 # ST-XXX 子任务需求分析
 ## 1. 文档信息与需求来源
 ## 2. 目标、范围与非范围
 ## 3. 业务规则、角色和权限
 ## 4. 正常流程、异常流程和状态流转
 ## 5. 功能点清单
 ## 6. 涉及工程及现有实现
 ## 7. 复用、新增、修改和迁移分析
 ## 8. 接口、数据及上下游影响
 ## 9. 非功能与上线要求
 ## 10. 子任务依赖
 ## 11. 验收标准
 ## 12. 需求矛盾、风险和待确认项
 ```
 功能使用 `F-001` 等稳定编号，验收标准使用 `AC-001`。链接到大需求和原始需求版本。
 ## 提交 G1
 提交以下完整确认包：
 - 大需求级 `技术侧需求分析.md`；
 - 业务子任务拆分；
 - 全部子任务的 `01.需求分析.md`；
 - 范围与非范围；
 - 需求矛盾、待确认项和风险；
 - 当前原始需求版本；
 - PM 编号；尚未确定时由用户在本次评审中决定；
 - 相关文档链接和版本。
 用户确认 G1 后才能开始技术方案设计。确认结论必须写入 `STATUS.md` 并绑定上述版本。
@@ -0,0 +1,133 @@
 # L2 技术方案设计
 ## 每个子任务一份文档
 每个子任务只创建一份：
 ```text
 02.技术实现方案.md
 ```
 该子任务的全部功能、接口、CRUD、消息、回调、定时任务、批处理和数据模型设计都写在同一文档内。除非用户明确要求，不得拆成多个功能方案文件。使用目录、编号标题、功能编号和接口总览表管理长文档。
 ## 设计流程
 ```text
 读取已确认的 01
 → 确认需求版本和代码基线
 → 调查现有实现和测试
 → 识别复用和约束
 → 设计总体流程
 → 设计每个功能和接口
 → 设计数据模型和一致性
 → 分析影响与回归
 → 设计实施顺序和验证
 → 更新 STATUS
 ```
 设计中发现业务规则缺失或矛盾时，将受影响内容退回需求分析。
 ## 文档结构
 ```markdown
 # ST-XXX 技术实现方案
 ## 目录
 ## 1. 文档信息、依据和版本
 ## 2. 目标、范围和验收依据
 ## 3. 现有实现与复用分析
 ## 4. 总体实现方案
 ## 5. 功能点和接口总览
 ## 6. 各功能点实现方案
 ## 7. 数据模型设计
 ## 8. 跨工程改造与依赖顺序
 ## 9. 变更影响与回归范围
 ## 10. 权限、安全、事务、并发和幂等
 ## 11. 非功能、日志、监控和审计
 ## 12. 兼容、迁移、发布和回滚
 ## 13. 测试与验证设计
 ## 14. 实施步骤
 ## 15. 方案取舍、风险和待确认项
 ## 16. 需求追溯
 ```
 确实不适用的章节写明原因，不得机械填充。
 ## 每个功能必须有方案
 每个 `F-XXX` 都要说明：
 - 目标及需求/验收依据；
 - 涉及工程和模块；
 - 现有实现、可复用符号及 Commit 证据；
 - 新增、修改、复用和非范围；
 - 正常、异常和适用的边界流程；
 - 接口、请求、响应、错误码和权限；
 - 业务校验；
 - 数据读写；
 - 事务、一致性、并发和幂等；
 - 缓存、搜索和消息行为；
 - 兼容性；
 - 测试和验证；
 - 风险与待确认项。
 简单 CRUD 也必须提供精简方案，至少覆盖校验、唯一性、分页/筛选、删除语义、权限、数据影响、适用的幂等和冒烟验证。
 ## 数据模型设计
 发生任何数据模型变化时，在同一文档第 7 节设计。
 ### 数据库
 说明实体含义、表、字段类型/可空/默认值、主键、约束、索引及查询依据、关系、枚举、审计/逻辑删除、容量、DDL、历史迁移、兼容、发布和回滚。
 ### Redis
 说明 Key 规则、数据类型和值结构、事实数据源、TTL、读写时机、更新/失效、未命中/空值、原子性、并发、热 Key/大 Key 风险和旧 Key 清理。
 ### Elasticsearch
 说明索引/Alias、文档 ID 和示例、Mapping/分词、适用的分片/副本/Routing、查询场景、数据库到 ES 的同步、延迟目标、重试修复、Reindex、历史初始化、Alias 切换和回滚。
 ### 跨存储一致性
 明确事实数据源、写入顺序、事件或 CDC 链路、缓存失效、ES 同步、幂等、重试/补偿、对账和失败行为。
 没有数据模型变化时，也要写明并指出复用依据。
 ## 影响与回归
 每个被修改的接口或功能都要调查：
 - 上游调用方和下游依赖；
 - 复用同一核心方法的其他接口；
 - 共享数据库表、Redis Key 和 ES 文档；
 - 消息、消费者、任务、报表、导入导出；
 - 前端、客户端和外部集成；
 - 权限、状态流转、监控和发布顺序。
 影响分类：直接、间接、兼容、数据、行为、性能、发布、潜在或已验证无影响。
 维护：
 | 影响编号 | 变更项 | 受影响接口/功能 | 工程 | 类型 | 说明 | 是否改造 | 回归级别 |
 |---|---|---|---|---|---|---|---|
 以及：
 | 回归编号 | 工程 | 接口/功能 | 回归场景 | 原因 | 优先级 |
 |---|---|---|---|---|---|
 禁止写“回归相关功能”等模糊描述。必须列出具体场景。“无影响”也要写明检查过的调用链和数据链证据。
 影响超出已确认范围时，记录后果和选项并请用户确认，不得静默扩大范围。
 ## 追溯与 G2
 建立：
 ```text
 需求 → F-XXX → 方案章节 → 涉及工程 → AC-XXX → TC-XXX 验证用例
 ```
 `02.技术实现方案.md` 和 `03.冒烟与逻辑验证.md` 的验证计划部分完成后，一起提交 G2；确认前不得开始实现。
@@ -0,0 +1,119 @@
 # L2 冒烟与逻辑验证
 ## 文档定位
 每个子任务只维护一份：
 ```text
 03.冒烟与逻辑验证.md
 ```
 该文档分两个生命周期使用：
 1. **G2 前：**设计核心主流程、范围内功能点和关键回归的验证计划。
 2. **代码 Review 后：**填写实际执行结果、证据、失败修复和提测结论。
 冒烟用于证明提测版本主流程可用、需求范围内功能点已验证；逻辑验证补充静态检查、构建、自动化测试、接口、数据及关键回归。二者使用同一组 `TC-XXX` 编号，禁止再维护第二份重复结果。
 ## G2 前必须设计
 - 核心业务主流程；
 - `01.需求分析.md` 中全部范围内功能点；
 - `02.技术实现方案.md` 中新增或修改的接口；
 - 明确要求的关键业务规则；
 - 关键权限和状态流转；
 - 主要数据新增、修改、查询和删除结果；
 - 接口变更直接影响的关键旧功能；
 - 会阻断提测的主要异常场景；
 - 计划执行的构建、自动化测试和静态检查。
 通常不要求穷举性能压测、所有并发组合、故障注入、全量兼容和无关系统级回归。某类风险属于本次需求核心内容时必须纳入。
 ## 文档结构
 ```markdown
 # ST-XXX 冒烟与逻辑验证
 ## 1. 文档信息与验证基线
 ## 2. 验证目标、范围和非范围
 ## 3. 环境、前置条件和测试数据
 ## 4. 验证计划
 ### 4.1 静态检查、构建和自动化测试计划
 ### 4.2 冒烟及功能用例
 ### 4.3 关键影响回归计划
 ## 5. 实际执行基线
 ## 6. 静态检查、构建和自动化测试结果
 ## 7. 冒烟及功能用例结果
 ## 8. 关键回归结果
 ## 9. 接口和数据验证
 ## 10. 失败、修复和重验
 ## 11. 未执行项、遗留问题和风险
 ## 12. 验证结论
 ```
 G2 时只确认第 1–4 节。第 5–12 节必须在代码实现和 Review 后按实际结果填写。
 ## 用例设计
 计划表只描述如何验证：
 | 编号 | 功能点 | 验证场景 | 前置条件 | 操作步骤 | 预期结果 | 验证类型 |
 |---|---|---|---|---|---|---|
 每个功能点至少一条有效用例。简单 CRUD 的最低验证：
 | 功能点 | 最低验证 |
 |---|---|
 | 新增 | 创建成功且数据结果正确 |
 | 修改 | 修改成功且查询结果正确 |
 | 查询 | 能查询到正确目标数据 |
 | 列表 | 核心筛选和分页可用 |
 | 删除 | 删除成功且后续结果符合规则 |
 只为明确关键的边界增加用例，例如无权限、非法状态、重复提交、审核中禁止删除或接口变更后的关键调用方回归。
 ## Review 后执行
 Review 阻断问题处理完成后，执行：
 - 最终代码检查；
 - 项目适用的格式化、Lint、静态分析和类型检查；
 - 编译或构建；
 - 单元测试和集成测试；
 - 核心调用链、权限、事务、幂等和状态流转检查；
 - `TC-XXX` 冒烟及功能用例；
 - 技术方案中的关键影响回归；
 - 本地接口与数据库、Redis、ES、消息和日志验证。
 结果表只记录实际执行事实：
 | 用例编号 | 实际结果 | 状态 | 证据 | 执行时间 |
 |---|---|---|---|---|
 环境、权限或依赖不足时标记“未验证”并说明原因，禁止默认通过。
 ## 失败处理
 ```text
 记录失败
 → 分析原因
 → 返回实现阶段修复
 → 重新 Code Review
 → 重跑失败项和受影响回归
 → 更新结果
 ```
 不得删除失败测试、弱化断言、跳过必要用例、吞掉异常或只重跑成功项。
 ## 提测结论
 只有以下条件同时满足，才能写“具备提测条件”：
 - 核心主流程通过；
 - 范围内功能点均有执行记录；
 - 没有未处理的 Critical/High 或其他阻断缺陷；
 - 接口变更影响的关键旧功能完成必要回归；
 - 未验证内容已明确且不阻断提测；
 - 已记录实际验证基线，包括工程、分支和 Commit 或等价版本标识。
 完成第 5–12 节后，该文档与 04、05 一起提交 G3。
@@ -0,0 +1,104 @@
 # L2 冒烟自测
 ## 定位
 `03.冒烟自测用例.md` 是提测前的精简自测清单，目标是：
 1. 保证提测版本核心业务主流程可用；
 2. 保证需求范围内每个功能点都经过有效验证。
 它不是完整测试方案，不要求穷举所有异常、并发和基础设施故障。只有某类风险属于本次需求核心内容时，才必须纳入冒烟。
 ## 编写时机
 技术方案完成后、编码前编写初稿：
 ```text
 01 需求分析
 → 02 技术方案
 → 03 冒烟用例
 → G2
 → 代码实现
 ```
 实现中发现新的关键功能或影响范围时，先更新 02 和 03。
 ## 必须覆盖
 - 本次需求核心主流程；
 - `01.需求分析.md` 中全部范围内功能点；
 - `02.技术实现方案.md` 中新增或修改的接口；
 - 明确要求的关键业务规则；
 - 关键权限和状态流转；
 - 主要数据新增、修改、查询和删除结果；
 - 接口变更直接影响的关键旧功能；
 - 会阻断提测的主要异常场景。
 通常不在冒烟阶段全面覆盖性能压测、全部并发组合、故障注入、全量兼容和无关系统级回归。
 ## 文档结构
 ```markdown
 # ST-XXX 冒烟自测用例
 ## 1. 文档信息
 - 大需求编号：
 - 子任务编号：
 - 需求版本：
 - 技术方案版本：
 - 提测版本或 Commit：
 - 测试环境：
 ## 2. 自测范围
 - 核心主流程：
 - 本次功能点：
 - 关键回归：
 - 非本次自测范围：
 ## 3. 前置条件和测试数据
 ## 4. 冒烟自测用例
 | 编号 | 功能点 | 验证场景 | 前置条件 | 操作步骤 | 预期结果 | 实际结果 | 状态 | 证据 |
 |---|---|---|---|---|---|---|---|---|
 ## 5. 功能覆盖检查
 | 功能编号 | 功能名称 | 对应用例 | 是否已验证 |
 |---|---|---|---|
 ## 6. 自测结论
 - 核心主流程是否通过：
 - 需求功能点是否全部验证：
 - 是否存在阻断问题：
 - 未通过或未验证项：
 - 是否具备提测条件：
 ```
 编码前填写场景和预期结果；执行后再填写实际结果、状态和证据。
 ## 最小用例原则
 每个功能点至少一条有效用例。简单 CRUD 可采用：
 | 功能点 | 最低验证 |
 |---|---|
 | 新增 | 创建成功且数据结果正确 |
 | 修改 | 修改成功且查询结果正确 |
 | 查询 | 能查询到正确目标数据 |
 | 列表 | 核心筛选和分页可用 |
 | 删除 | 删除成功且后续结果符合规则 |
 只有明确关键的边界才增加用例，例如无权限、非法状态、重复提交、审核中禁止删除，或接口变更后的关键调用方回归。
 技术方案中的完整回归范围可以大于冒烟范围；冒烟只选择影响主流程、需求功能和提测质量的关键场景。
 ## 通过结论
 只有以下条件同时满足，才能写“具备提测条件”：
 - 核心主流程通过；
 - 范围内功能点都有验证记录；
 - 没有阻断缺陷；
 - 接口变更影响的关键旧功能完成必要回归；
 - 未验证内容已明确且不阻断提测。
 环境、权限或依赖不足时标记“未验证”，禁止默认通过。
@@ -0,0 +1,145 @@
 # 代码实现
 ## 实现输入
 L2 编码以三份已确认文档为直接依据：
 ```text
 01.需求分析.md
 02.技术实现方案.md
 03.冒烟与逻辑验证.md
 ```
 确认需求版本、代码基线、开发工程和真实开发工作区。不得误在 `management/.../code/` 分析副本中开发。
 Agent 可以使用 `git status`、`git diff`、`git log` 等只读命令调查和 Review，但禁止执行 `git add`、`git commit`、`git push`。暂存、提交和推送均由用户完成；其他可能改变分支或历史的操作必须符合用户指示和安全规则。
 ## 项目规范优先
 编码前调查：
 - `AGENTS.md`、`CLAUDE.md` 等 Agent 指令；
 - `README.md`、`CONTRIBUTING.md` 和架构文档；
 - `.editorconfig`、格式化、Lint、静态分析和构建配置；
 - 测试规范；
 - 当前模块和相邻同类代码。
 作用域更近的项目规则优先。没有书面规范时，从同一模块的同类近期实现中提炼惯例，不得凭单个偶然文件确定全局风格。
 保持目录、分层、命名、DTO/VO/Entity 划分、校验、异常、错误码、日志、权限、事务、数据访问、Redis、ES、消息、配置、依赖注入、注释和测试风格一致。
 保持风格不代表复制明显错误、过时代码或安全缺陷；发现问题时说明并采用最小安全处理。
 ## 控制范围
 禁止借需求开发进行无关的：
 - 全工程格式化；
 - 大范围重命名；
 - 目录或框架替换；
 - 旧代码全面重构；
 - 注释清洗；
 - 个人偏好的设计模式改造；
 - 不必要的第三方依赖引入。
 新增依赖前检查项目已有能力、统一实现、兼容性、构建/部署/安全风险和必要性，并写入方案与实现记录。
 ## 敏感信息保护
 - 不在代码、配置、需求文档、日志、测试记录或验证证据中写入密码、Token、Cookie、私钥、访问密钥和完整连接串。
 - 手机号、身份证、地址、客户数据和其他生产敏感信息必须脱敏。
 - 接口请求响应、数据库结果、日志和截图只保留验证所需字段。
 - 凭据通过项目认可的安全环境注入；缺少凭据时请求用户处理，不得创建或保存临时明文凭据。
 - 发现疑似密钥或生产敏感数据进入改动时，立即停止受影响工作并报告。
 ## 实施顺序
 ```text
 检查工作区、分支、Commit 和用户已有改动
 → 读取项目规范
 → 确认开发基线
 → 按功能点和工程依赖实施
 → 编写/更新自动化测试
 → 构建和测试
 → 对照冒烟用例自测
 → 更新实现记录和 STATUS
 ```
 多工程通常按照：
 ```text
 数据脚本与公共模型
 → 服务提供方
 → 服务调用方
 → 消息消费者
 → 前端或外部接入方
 → 联调
 ```
 实际顺序以已确认方案为准。
 ## TDD
 适合自动化的功能执行：
 ```text
 建立失败测试
 → 确认因目标能力缺失而失败
 → 最小实现
 → 测试通过
 → 重构
 → 相关回归
 ```
 缺陷修复优先建立可复现问题的测试。外部环境导致无法标准测试先行时，记录原因并使用可执行替代验证。
 不得通过删除测试、弱化断言、跳过必要用例、吞异常或修改测试迎合错误实现来制造通过。
 ## 方案偏差
 编码中发现方案不可行时：
 ```text
 记录问题
 → 判断需求和影响
 → 更新 02
 → 更新 03
 → 必要时重开门禁
 → 继续实现
 ```
 接口契约、数据模型、涉及工程、业务流程、状态、权限、兼容性或需求范围变化时，必须先更新方案。仅私有结构调整且不改变这些内容时，写入实现记录即可。
 ## `04.技术实现记录.md`
 记录实现事实，不复制整份方案：
 ```markdown
 # ST-XXX 技术实现记录
 ## 1. 实现信息
 - 需求版本：
 - 技术方案版本：
 - 开发工程：
 - 开发分支：
 - 实现前 Commit：
 - 实现后 Commit：
 - 当前状态：
 ## 2. 功能实现状态
 | 功能编号 | 功能名称 | 涉及工程 | 实现状态 | 方案章节 | 备注 |
 |---|---|---|---|---|---|
 ## 3. 工程及代码改动
 ## 4. 数据模型改动
 ## 5. 接口改动
 ## 6. 自动化测试改动
 ## 7. 与技术方案的差异
 ## 8. 编译和测试结果
 ## 9. 项目规范遵循情况
 ## 10. 遗留问题及风险
 ```
 项目规范遵循情况应列出已读取规范、参考实现、执行的格式/静态检查、差异和原因。
 实现完成仅表示代码准备进入 Review，不等于子任务最终完成。
@@ -0,0 +1,127 @@
 # 代码 Review 与逻辑验证
 ## 固定顺序
 ```text
 代码实现完成
 → Code Review
 → 修复 Review 问题
 → 再次 Review
 → 执行 03 中的逻辑验证和本地接口冒烟
 → 输出结论
 ```
 ## Code Review
 检查完整变更及必要的相邻上下文，不只看修改行。可以使用 `git status`、`git diff`、`git log` 等只读命令确定 Review 范围，但不得执行 `git add`、`git commit`、`git push`。
 ### 需求符合性
 - 是否覆盖全部确认功能；
 - 是否符合 01、02、03；
 - 是否遗漏接口影响和回归；
 - 是否擅自增加范围。
 ### 项目规范与质量
 - 架构、分层、命名和代码风格；
 - 复用、重复实现、异常、日志和错误码；
 - 无关修改和大范围格式化；
 - 依赖和测试风格。
 ### 核心架构变化
 检查模块职责、分层边界、依赖方向、核心接口、数据事实源、Redis/ES/消息链路、权限、事务和状态流转。
 分类为：
 ```text
 方案内预期变化
 实现细节调整且不影响架构
 方案外架构变化，需要确认
 疑似架构破坏，必须修复
 ```
 ### 严重缺陷
 重点检查：
 - 代码中不得有在循环中查询数据库的情况
 - 越权、注入和敏感信息泄漏；
 - 数据错误、丢失或覆盖；
 - 空指针和未处理异常；
 - 事务、并发、幂等和状态错误；
 - 缓存/数据库/ES 不一致；
 - 消息重复、丢失或无限重试；
 - 死循环、资源泄漏和明显性能问题；
 - 接口兼容破坏；
 - 不可恢复的删除或迁移；
 - 异常路径错误返回成功；
 - 测试被弱化或跳过。
 只能写“在本次检查范围内未发现严重问题”，不得承诺绝对无 Bug。
 问题分级：
 | 等级 | 含义 | 要求 |
 |---|---|---|
 | Critical | 安全、数据丢失、系统不可用 | 修复后才能继续 |
 | High | 核心错误、架构破坏、明显兼容问题 | 修复后才能继续 |
 | Medium | 局部逻辑、维护性或规范问题 | 原则上修复并记录 |
 | Low | 优化或轻微风格问题 | 按范围处理 |
 ## `05.代码Review报告.md`
 ```markdown
 # ST-XXX 代码 Review 报告
 ## 1. Review 信息和范围
 ## 2. 需求符合性
 ## 3. 项目规范符合性
 ## 4. 核心架构变化
 ## 5. Review 问题
 | 编号 | 等级 | 工程及位置 | 问题 | 影响 | 处理状态 |
 |---|---|---|---|---|---|
 ## 6. 修复及复查
 ## 7. 未确认风险
 ## 8. Review 结论
 ```
 发现问题后返回实现阶段，修复并重新 Review。
 ## 逻辑验证
 Review 的阻断问题处理后，执行：
 - 最终差异检查；
 - 格式化、Lint、静态分析和类型检查；
 - 编译或构建；
 - 单元与集成测试；
 - 关键调用链、数据读写、权限、事务、幂等和状态流转检查；
 - 技术方案中的关键影响回归；
 - `03.冒烟与逻辑验证.md` 中确认的验证计划。
 失败时记录、分析、修复、重跑失败项和受影响回归。不得只重跑成功用例。
 ## 本地接口测试
 本地环境可启动时：
 ```text
 确认依赖和数据安全
 → 启动相关工程
 → 准备专用测试数据
 → 执行核心主流程接口
 → 验证范围内全部功能
 → 回归关键受影响接口
 → 检查数据库、Redis、ES、消息和日志
 → 保存证据
 ```
 检查状态码、响应结构、业务字段、落库、缓存/索引、状态流转、权限、关键异常和直接受影响旧接口。
 开始写数据前确认不是生产或不可随意修改的共享环境。需要人工登录、凭据或外部依赖时，明确请求用户协助。测试数据、请求响应、日志和截图必须脱敏，不得将凭据或生产敏感数据写入验证文档。
 实际结果统一写入 `03.冒烟与逻辑验证.md` 第 5–12 节，不再创建单独逻辑验证报告。只有实际执行并有证据的内容可以标记通过；环境受限的内容写“未验证”及原因。
 完成后提交 03、04、05 及关键证据，进入 G3。
@@ -0,0 +1,128 @@
 # 交付、上线与归档
 ## 开发完成与需求完成
 Review、逻辑验证和冒烟通过后，子任务可标记：
 ```text
 逻辑验证：已完成
 子任务：开发完成 / 待提测
 ```
 这不等于需求已测试、上线或归档。
 后续状态：
 ```text
 开发完成 → 待提测 → 测试中 → 测试通过
 → 待发布 → 已上线 → 上线验证通过 → 已归档
 ```
 测试失败时返回实现阶段，完成修复、Review、验证和重新提测，并追加状态历史。
 ## G3
 向用户提交：
 - `04.技术实现记录.md`；
 - `05.代码Review报告.md`；
 - 已填写执行结果的 `03.冒烟与逻辑验证.md`；
 - 功能完成与未完成项；
 - 验证证据；
 - 遗留问题和风险；
 - 是否具备提测条件。
 用户确认后将 G3 标记为通过，进入测试人员提测流程。
 ## `06.验收与交付报告.md`
 ```markdown
 # ST-XXX 验收与交付报告
 ## 1. 交付信息
 - 需求版本：
 - 涉及工程：
 - 开发分支：
 - 发布分支或 Tag：
 - 发布 Commit：
 ## 2. 开发交付内容
 ## 3. 测试结果
 - 测试环境：
 - 测试时间：
 - 测试人员：
 - 测试结论：
 - 缺陷及处理：
 - 测试报告：
 ## 4. 发布记录
 - 发布时间：
 - 发布环境：
 - 发布版本：
 - 发布工程：
 - 数据脚本：
 - 配置变化：
 - 实际顺序：
 ## 5. 上线验证
 - 核心主流程：
 - 关键接口：
 - 数据库：
 - Redis：
 - Elasticsearch：
 - 消息和任务：
 - 日志和监控：
 ## 6. 遗留问题
 ## 7. 最终结论
 ```
 外部测试报告可以保存链接、编号或副本，不必重复全文。
 `git add`、`git commit`、`git push` 均由用户执行。Agent 可以读取并记录用户完成后的发布分支、Tag 和 Commit。
 ## 逻辑归档
 归档不移动大需求目录。测试通过、上线并完成上线验证后，在大需求根目录维护一份：
 ```text
 归档记录.md
 ```
 归档文档汇总：
 - 基本信息、最终需求版本和时间；
 - 最终范围、延期或取消内容、需求变化；
 - 子任务完成情况；
 - 各工程发布分支、Tag、Commit 和时间；
 - 数据库、Redis、ES、配置和迁移；
 - Review、冒烟与逻辑验证、测试和上线结论；
 - 关键文档相对链接；
 - 遗留问题、风险和后续维护建议；
 - 最终归档结论。
 同时在 `STATUS.md` 追加：
 ```text
 已上线 → 上线验证通过 → 已归档
 ```
 目录、原始需求版本和历史状态不得删除。`code/` 副本即使以后继续更新，归档文档也必须保留本次实际发布的 Tag 和 Commit。
 ## 后续维护
 归档事实记录原则上不直接改写。后续优化或修复建立新需求或维护任务，关联原 PM、最终需求版本和上线 Commit。
 ## OpenSpec 适配
 默认归档载体为 `归档记录.md`。项目启用 OpenSpec 时，将其作为可替换归档后端：
 ```text
 management 过程文档
 → 字段映射或转换
 → OpenSpec 归档
 ```
 初期保持 management 文档为过程事实来源，避免人工双写。项目级适配规则应规定字段映射、归档命令、幂等、失败回退、状态同步和后续维护。
 OpenSpec 的引入不得改变前置开发流程、文档编号、需求追溯和状态历史。
@@ -0,0 +1,32 @@
 # 参考文件目录索引
 根据当前影响等级和阶段，只加载所需规则。
 | 文件 | 适用场景 |
 |---|---|
 | [01-分级与门禁.md](01-分级与门禁.md) | 新需求分级、选择门禁、范围升级或更新门禁状态 |
 | [02-L0与L1轻量流程.md](02-L0与L1轻量流程.md) | 执行 L0 或 L1 变更 |
 | [03-需求管理.md](03-需求管理.md) | 建立或维护 L2 PM 目录、原始需求版本、代码副本、状态历史或需求矛盾 |
 | [04-需求分析.md](04-需求分析.md) | 阅读需求、拆分业务子任务、识别工程或编写 `01.需求分析.md` |
 | [05-技术方案设计.md](05-技术方案设计.md) | 编写或修改 `02.技术实现方案.md`，包括接口、数据模型、影响和回归范围 |
 | [06-冒烟与逻辑验证.md](06-冒烟与逻辑验证.md) | 编写验证计划，执行冒烟、自动化检查和本地接口验证，并维护 `03.冒烟与逻辑验证.md` |
 | [07-代码实现.md](07-代码实现.md) | 实现代码、遵循项目风格、执行 TDD 或维护 `04.技术实现记录.md` |
 | [08-代码审查与验证.md](08-代码审查与验证.md) | Review 完成代码、检查严重缺陷、验证逻辑、启动本地服务或测试接口 |
 | [09-交付与归档.md](09-交付与归档.md) | 标记开发完成、提测、记录发布、维护 `06.验收与交付报告.md` 或逻辑归档 |
 ## 阶段路由
 ```text
 分级
 ├─ L0 → 01 + 02
 ├─ L1 → 01 + 02 + 07 + 08
 └─ L2
   ├─ 接入与状态 → 01 + 03
   ├─ G1 需求 → 03 + 04
   ├─ G2 方案与验证计划 → 05 + 06
   ├─ 实现 → 07
   ├─ Review 与验证 → 08
   └─ G3、交付与归档 → 09
 ```
 需求变化时，重新读取所有被影响阶段的参考文件，不得只更新最新一份文档。
@@ -0,0 +1,221 @@
 #!/usr/bin/env python3
 """安全初始化 Vibe Coding 的 L1 或 L2 文档目录。"""
 from __future__ import annotations
 import argparse
 import datetime as dt
 import re
 import shutil
 import sys
 import tempfile
 from pathlib import Path
 SKILL_ROOT = Path(__file__).resolve().parent.parent
 TEMPLATES = SKILL_ROOT / "assets" / "templates"
 INVALID_NAME = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
 def safe_name(value: str) -> str:
    cleaned = INVALID_NAME.sub("_", value).strip().rstrip(".")
    if not cleaned:
        raise ValueError("名称不能为空或只包含非法字符")
    return cleaned
 def render(template_name: str, replacements: dict[str, str]) -> str:
    text = (TEMPLATES / template_name).read_text(encoding="utf-8")
    for key, value in replacements.items():
        text = text.replace("{{" + key + "}}", value)
    return text
 def write_new(path: Path, content: str) -> None:
    if path.exists():
        raise FileExistsError(f"拒绝覆盖已有文件：{path}")
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(content, encoding="utf-8")
 def parse_subtask(raw: str) -> tuple[str, str]:
    if ":" not in raw:
        raise ValueError(f"子任务格式应为 ST-001:名称，实际为：{raw}")
    number, name = raw.split(":", 1)
    number = number.strip().upper()
    if not re.fullmatch(r"ST-\d{3}", number):
        raise ValueError(f"子任务编号格式错误：{number}")
    return number, safe_name(name)
 def build_l1(args: argparse.Namespace) -> Path:
    now = dt.datetime.now().astimezone().isoformat(timespec="seconds")
    replacements = {
        "需求名称": args.name,
        "编号": args.requirement_id or "待确认",
        "状态": "待确认",
        "时间": now,
    }
    if args.subtask_dir:
        target_dir = Path(args.subtask_dir).resolve()
        if not target_dir.is_dir():
            raise FileNotFoundError(f"子任务目录不存在：{target_dir}")
        write_new(
            target_dir / "01.精简变更日志.md",
            render("L1-精简变更日志模板.md", replacements),
        )
        return target_dir
    management_root = Path(args.management_root).resolve()
    management_root.mkdir(parents=True, exist_ok=True)
    pm_id = safe_name(args.requirement_id or "待确认")
    target = management_root / f"PM-{pm_id}-{safe_name(args.name)}"
    if target.exists():
        raise FileExistsError(f"目标目录已存在：{target}")
    temporary = Path(tempfile.mkdtemp(prefix=".vibe-init-", dir=management_root))
    try:
        write_new(
            temporary / "01.精简变更日志.md",
            render("L1-精简变更日志模板.md", replacements),
        )
        temporary.replace(target)
    except Exception:
        shutil.rmtree(temporary, ignore_errors=True)
        raise
    return target
 def build_l2(args: argparse.Namespace) -> Path:
    management_root = Path(args.management_root).resolve()
    management_root.mkdir(parents=True, exist_ok=True)
    pm_id = safe_name(args.pm_id or "待确认")
    demand_name = safe_name(args.name)
    target = management_root / f"PM-{pm_id}-{demand_name}"
    if target.exists():
        raise FileExistsError(f"目标目录已存在：{target}")
    subtasks = [parse_subtask(item) for item in args.subtask]
    if not subtasks:
        raise ValueError("L2 至少需要一个 --subtask ST-001:名称")
    numbers = [number for number, _ in subtasks]
    if len(numbers) != len(set(numbers)):
        raise ValueError("子任务编号不能重复")
    now = dt.datetime.now().astimezone().isoformat(timespec="seconds")
    common = {
        "PM编号": pm_id,
        "需求名称": demand_name,
        "名称": demand_name,
        "状态": "需求分析中",
        "阶段": "需求分析",
        "时间": now,
    }
    temporary = Path(tempfile.mkdtemp(prefix=".vibe-init-", dir=management_root))
    try:
        source_version = safe_name(args.source_version)
        (temporary / "source" / source_version).mkdir(parents=True)
        (temporary / "code").mkdir(parents=True)
        (temporary / "tasks").mkdir(parents=True)
        overview = render("大需求总览模板.md", common)
        default_row = (
            "| ST-001 | {{模块}} | 需求分析 | 需求分析中 | {{依赖}} | "
            "[查看](./tasks/ST-001-模块/01.需求分析.md) |"
        )
        rows = "\n".join(
            f"| {number} | {name} | 需求分析 | 未开始 | 待梳理 | "
            f"[查看](./tasks/{number}-{name}/01.需求分析.md) |"
            for number, name in subtasks
        )
        overview = overview.replace(default_row, rows)
        write_new(temporary / "README.md", overview)
        write_new(temporary / "STATUS.md", render("任务状态模板.md", common))
        write_new(
            temporary / "技术侧需求分析.md",
            render("技术侧需求分析模板.md", common),
        )
        source_index = render("原始需求版本索引模板.md", common)
        source_index = source_index.replace("| v1 |", f"| {source_version} |")
        source_index = source_index.replace("./v1/", f"./{source_version}/")
        write_new(temporary / "source" / "README.md", source_index)
        write_new(
            temporary / "code" / "MANIFEST.md",
            render("代码副本清单模板.md", common),
        )
        phase_templates = [
            ("01-需求分析模板.md", "01.需求分析.md"),
            ("02-技术实现方案模板.md", "02.技术实现方案.md"),
            ("03-冒烟与逻辑验证模板.md", "03.冒烟与逻辑验证.md"),
            ("04-技术实现记录模板.md", "04.技术实现记录.md"),
            ("05-代码Review报告模板.md", "05.代码Review报告.md"),
            ("06-验收与交付报告模板.md", "06.验收与交付报告.md"),
        ]
        for number, name in subtasks:
            task_dir = temporary / "tasks" / f"{number}-{name}"
            replacements = dict(common)
            replacements.update(
                {
                    "ST编号": number,
                    "子任务名称": name,
                    "PM编号及链接": f"[{pm_id}](../../README.md)",
                    "链接": "../../README.md",
                }
            )
            for template_name, output_name in phase_templates:
                write_new(
                    task_dir / output_name,
                    render(template_name, replacements),
                )
        temporary.replace(target)
    except Exception:
        shutil.rmtree(temporary, ignore_errors=True)
        raise
    return target
 def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description="初始化 Vibe Coding L1/L2 文档，拒绝覆盖已有目标。",
    )
    subparsers = parser.add_subparsers(dest="level", required=True)
    l1 = subparsers.add_parser("l1", help="初始化一份 L1 精简变更日志")
    l1.add_argument("--name", required=True, help="需求名称")
    l1.add_argument("--requirement-id", help="需求编号；未提供时使用“待确认”")
    l1_target = l1.add_mutually_exclusive_group(required=True)
    l1_target.add_argument("--management-root", help="独立需求的 management 目录")
    l1_target.add_argument("--subtask-dir", help="既有大需求下的子任务目录")
    l2 = subparsers.add_parser("l2", help="初始化完整 L2 PM 目录")
    l2.add_argument("--management-root", required=True, help="management 目录")
    l2.add_argument("--name", required=True, help="大需求名称")
    l2.add_argument("--pm-id", help="PM 编号；未提供时使用“待确认”")
    l2.add_argument("--source-version", default="v1", help="初始原始需求版本")
    l2.add_argument(
        "--subtask",
        action="append",
        default=[],
        help="子任务，格式 ST-001:名称；可重复",
    )
    return parser
 def main() -> int:
    parser = build_parser()
    args = parser.parse_args()
    try:
        target = build_l1(args) if args.level == "l1" else build_l2(args)
    except (OSError, ValueError) as exc:
        print(f"初始化失败：{exc}", file=sys.stderr)
        return 1
    print(f"初始化完成：{target}")
    return 0
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -0,0 +1,208 @@
 #!/usr/bin/env python3
 """校验 Vibe Coding 文档结构、链接、占位符和功能追溯。"""
 from __future__ import annotations
 import argparse
 import re
 import sys
 from pathlib import Path
 PLACEHOLDER = re.compile(r"\{\{[^{}\n]+\}\}")
 MARKDOWN_LINK = re.compile(r"\[[^\]]+\]\(([^)]+)\)")
 FUNCTION_ID = re.compile(r"\bF-\d{3}\b")
 OLD_NAMES = {
    "03.冒烟自测用例.md",
    "06.逻辑验证报告.md",
    "07.验收与交付报告.md",
 }
 class Report:
    def __init__(self) -> None:
        self.errors: list[str] = []
        self.warnings: list[str] = []
    def error(self, message: str) -> None:
        self.errors.append(message)
    def warning(self, message: str) -> None:
        self.warnings.append(message)
 def read_text(path: Path, report: Report) -> str:
    try:
        return path.read_text(encoding="utf-8")
    except UnicodeDecodeError:
        report.error(f"文件不是有效 UTF-8：{path}")
    except OSError as exc:
        report.error(f"无法读取文件：{path}（{exc}）")
    return ""
 def check_links(path: Path, text: str, report: Report) -> None:
    for match in MARKDOWN_LINK.finditer(text):
        target = match.group(1).strip()
        if (
            not target
            or target.startswith(("#", "http://", "https://", "mailto:"))
            or "{{" in target
        ):
            continue
        relative = target.split("#", 1)[0]
        if not (path.parent / relative).resolve().exists():
            report.error(f"失效链接：{path} -> {target}")
 def required_root_files(root: Path) -> list[Path]:
    return [
        root / "README.md",
        root / "STATUS.md",
        root / "技术侧需求分析.md",
        root / "source" / "README.md",
        root / "code" / "MANIFEST.md",
    ]
 def task_directories(root: Path) -> list[Path]:
    tasks_root = root / "tasks"
    if not tasks_root.is_dir():
        return []
    return sorted(path for path in tasks_root.iterdir() if path.is_dir())
 def required_task_names(phase: str) -> list[str]:
    names = ["01.需求分析.md"]
    if phase in {"g2", "g3", "archive"}:
        names += ["02.技术实现方案.md", "03.冒烟与逻辑验证.md"]
    if phase in {"g3", "archive"}:
        names += ["04.技术实现记录.md", "05.代码Review报告.md"]
    if phase == "archive":
        names += ["06.验收与交付报告.md"]
    return names
 def check_traceability(task: Path, report: Report) -> None:
    requirement = read_text(task / "01.需求分析.md", report)
    design = read_text(task / "02.技术实现方案.md", report)
    validation = read_text(task / "03.冒烟与逻辑验证.md", report)
    required_ids = set(FUNCTION_ID.findall(requirement))
    if not required_ids:
        report.warning(f"未在需求分析中发现功能编号：{task}")
        return
    for function_id in sorted(required_ids):
        if function_id not in design:
            report.error(f"{task.name} 的 {function_id} 未出现在技术方案中")
        if function_id not in validation:
            report.error(f"{task.name} 的 {function_id} 未出现在验证文档中")
 def validate_l1(
    root: Path,
    allow_placeholders: bool,
    report: Report,
 ) -> None:
    document = root / "01.精简变更日志.md"
    if not document.is_file():
        report.error(f"缺少 L1 文档：{document}")
        return
    text = read_text(document, report)
    if not allow_placeholders and PLACEHOLDER.search(text):
        report.error(f"存在未填写占位符：{document}")
    check_links(document, text, report)
 def validate_l2(
    root: Path,
    phase: str,
    allow_placeholders: bool,
    report: Report,
 ) -> None:
    required = required_root_files(root)
    tasks = task_directories(root)
    if not tasks:
        report.error(f"未发现子任务目录：{root / 'tasks'}")
    for task in tasks:
        for name in required_task_names(phase):
            required.append(task / name)
        for child in task.iterdir():
            if child.name in OLD_NAMES:
                report.error(f"发现旧版文档名称：{child}")
    if phase == "archive":
        required.append(root / "归档记录.md")
    existing_required: list[Path] = []
    for path in required:
        if not path.is_file():
            report.error(f"缺少必需文件：{path}")
        else:
            existing_required.append(path)
    status = root / "STATUS.md"
    if status.is_file():
        status_text = read_text(status, report)
        for heading in ("原始需求版本", "确认文档及版本", "代码版本标识"):
            if heading not in status_text:
                report.error(f"STATUS.md 缺少门禁绑定字段：{heading}")
    for path in existing_required:
        text = read_text(path, report)
        if not allow_placeholders and PLACEHOLDER.search(text):
            report.error(f"存在未填写占位符：{path}")
        check_links(path, text, report)
    if phase in {"g2", "g3", "archive"}:
        for task in tasks:
            if all((task / name).is_file() for name in required_task_names("g2")):
                check_traceability(task, report)
 def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description="校验 Vibe Coding 的 L1/L2 文档完整性。",
    )
    parser.add_argument("path", help="L1 所在目录或 L2 PM 目录")
    parser.add_argument(
        "--phase",
        choices=["l1", "structure", "g1", "g2", "g3", "archive"],
        required=True,
        help="目标校验阶段",
    )
    parser.add_argument(
        "--allow-placeholders",
        action="store_true",
        help="允许模板占位符，适合刚初始化后的结构检查",
    )
    return parser
 def main() -> int:
    args = build_parser().parse_args()
    root = Path(args.path).resolve()
    if not root.is_dir():
        print(f"校验失败：目录不存在：{root}", file=sys.stderr)
        return 1
    report = Report()
    if args.phase == "l1":
        validate_l1(root, args.allow_placeholders, report)
    else:
        validate_l2(root, args.phase, args.allow_placeholders, report)
    for warning in report.warnings:
        print(f"警告：{warning}")
    for error in report.errors:
        print(f"错误：{error}", file=sys.stderr)
    if report.errors:
        print(f"校验失败：{len(report.errors)} 个错误，{len(report.warnings)} 个警告")
        return 1
    print(f"校验通过：0 个错误，{len(report.warnings)} 个警告")
    return 0
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -0,0 +1,108 @@
 ---
 name: vue-coding-style
 description: 面向 Vue 前端 Vibe Coding 的工程化编写、修改、修复、重构、审查与验证规范。凡任务涉及 Vue 3、Vue SFC、Composition API、script setup、TypeScript、Vue Router、Pinia、Vite、Vitest、组件、页面、composable、store、前端接口层、样式、可访问性、性能、测试或 Vue 代码 Review 时使用。默认采用主流 Vue 3 + TypeScript 技术路线，但必须先服从项目现有版本、工具链和局部约定；处理 Vue 2 或 Options API 项目时不得擅自迁移。
 ---
 # Vue Coding Style
 ## 核心目标
 以可维护、类型安全、可测试、可访问和可验证为目标完成 Vue 变更。优先保持项目一致性，再应用本技能的默认规范。只修改本次需求所需内容，禁止借机升级依赖、迁移 API 风格或重排无关代码。
 ## 开始任何 Vue 任务
 1. 读取作用域内的 `AGENTS.md`、项目说明和用户提供的需求文档。
 2. 检查 `package.json`、锁文件、Vue/Vite/TypeScript 版本、`tsconfig*`、ESLint/格式化配置、测试配置和可用脚本。
 3. 阅读目标文件、直接调用方、相邻同类实现、共享类型、路由、store、API 层和相关测试。
 4. 区分以下内容：
   - 用户明确要求；
   - 当前代码与配置事实；
   - 本技能给出的默认建议。
 5. 明确行为边界、非目标、兼容性、风险和可执行的验收方式；存在通用 Vibe Coding 治理 skill 时，同时遵守其分级与门禁。
 6. 在未核实依赖版本前，不使用较新宏、实验性 API 或废弃特性。
 ## 规则优先级
 按以下顺序处理冲突：
 ```text
 用户本次明确要求
 → 已确认的需求与验收标准
 → 作用域最近的项目指令
 → 项目配置、自动化规则和相邻代码惯例
 → 本技能的 Vue 默认规范
 → 个人偏好
 ```
 若更高优先级规则会引入明显缺陷、安全问题或不可验证行为，先暴露冲突和影响，再请求用户决策。不得静默绕过项目规则。
 ## 按任务加载参考
 - 每次编写或修改 Vue 代码，读取 [references/core-standards.md](references/core-standards.md)。
 - 涉及目录、组件边界、composable、Pinia、Router、API 或 SSR，读取 [references/architecture.md](references/architecture.md)。
 - 涉及实现、修复、测试、性能、安全、可访问性或交付，读取 [references/quality-gates.md](references/quality-gates.md)。
 - 编写新组件、composable、store 或测试且需要范式时，读取 [references/examples.md](references/examples.md)。
 - 执行代码 Review 或完成交付前，读取 [references/review-checklist.md](references/review-checklist.md)。
 只加载当前任务需要的参考文件，但交付前必须执行 Review 清单。
 ## 默认技术基线
 仅在新项目或项目没有相反约定时采用：
 - 使用 Vue 3、Single-File Components、Composition API、`<script setup lang="ts">`。
 - 使用严格 TypeScript，并以 `vue-tsc` 覆盖 SFC 与模板类型检查。
 - 使用 Vite 及项目已选择的包管理器。
 - 使用 Vue Router 管理客户端路由，使用 Pinia 管理确有跨页面或跨组件共享价值的客户端状态。
 - 使用 ESLint、`eslint-plugin-vue` 和项目既有格式化方案；新配置优先 Flat Config。
 - 使用 Vitest 做单元/组件测试，使用 `@vue/test-utils` 测试 Vue 组件；关键用户路径按项目选择执行 E2E。
 不要因默认基线而改造成熟的 Vue 2、Options API、Nuxt、JS-only 或其他既有项目。除非用户明确授权迁移，否则在既有风格内完成最小改动。
 ## 不可妥协的实现约束
 - 保持单向数据流：props 向下、事件向上；禁止修改 props。
 - 为组件边界提供明确的 props、emits、slots 和 exposed API；避免把内部实现暴露给父组件。
 - 让模板保持声明式；将复杂派生、分支和数据转换移入 `computed`、函数或 composable。
 - 让 `computed` 保持纯净；仅用 `watch`/`watchEffect` 处理副作用，并清理定时器、监听器、请求和过期异步结果。
 - 使用稳定且唯一的 `key`；禁止以数组索引标识可增删、排序或筛选的列表项。
 - 优先局部状态，其次复用 composable，最后才使用 Pinia；不得把所有状态全局化。
 - 在请求边界区分加载、空数据、失败和成功状态；不得吞掉异常或只在控制台记录面向用户的失败。
 - 禁止用 `any`、无依据的类型断言、`@ts-ignore` 或 non-null assertion 掩盖可建模问题。
 - 优先原生语义 HTML；保证键盘操作、焦点、表单标签和必要的 ARIA 语义。
 - 禁止把密钥放入客户端代码或 `VITE_*` 环境变量；谨慎使用 `v-html`，未经可信净化不得渲染外部 HTML。
 - 不为假设的未来需求提前建立抽象；出现第二个真实复用点并且语义稳定时再提取。
 - 不改变依赖、构建配置、公共 API 或全局样式，除非它们在确认范围内。
 ## 实施流程
 1. 将验收行为写成可观察结果，优先补充或更新能失败的测试。
 2. 选择最小改动面，复用项目现有组件、composable、类型、tokens 和工具函数。
 3. 先建立数据与类型边界，再实现状态与行为，最后连接模板和样式。
 4. 同时处理 loading、empty、error、disabled、权限不足和异步竞态等适用状态。
 5. 检查窄视口、键盘、焦点、文本溢出和主题变量等界面边界。
 6. 自查变更是否引入无关格式化、重复抽象、死代码、调试输出或不必要依赖。
 7. 运行项目已有验证命令；根据锁文件使用对应包管理器，不得混用。
 ## 验证与交付
 优先运行项目现有脚本，并按风险选择：
 ```text
 定向测试
 → lint
 → vue-tsc / typecheck
 → 完整单元或组件测试
 → build
 → 关键页面或 E2E 冒烟
 ```
 对小改动可以只执行受影响范围与必要静态检查；对路由、共享状态、公共组件、构建配置或安全相关改动扩大回归范围。只报告实际执行的命令和结果；无法运行的检查标记为“未验证”并说明原因。
 交付时说明：
 - 实际行为变化和主要文件；
 - 关键设计选择及其项目依据；
 - 已执行的测试、类型检查、lint、构建或人工冒烟；
 - 未验证项、兼容性风险和剩余问题。
@@ -0,0 +1,5 @@
 interface:
  display_name: "Vue Coding Style"
  short_description: "Vue 3 与 TypeScript 前端编写、重构和审查规范"
  default_prompt: "Use $vue-coding-style to implement or review this Vue frontend change with project-aligned conventions and verifiable quality gates."
@@ -0,0 +1,107 @@
 # Vue 架构与职责边界
 ## 目录
 - 结构原则
 - 组件边界
 - Composable
 - Pinia
 - Vue Router
 - API 与数据边界
 - 表单
 - SSR 与 Hydration
 - 依赖和公共 API
 - 官方依据
 ## 结构原则
 - 先遵循现有目录结构；不要在单个需求中引入第二套架构。
 - 新建中大型项目或独立业务域时，优先按 feature/domain 聚合页面、组件、composable、store、服务和类型；将真正跨域的稳定能力放入 `shared`。
 - 避免把 `components/`、`utils/`、`types/` 变成无边界仓库。目录名需表达所属业务或技术职责。
 - 只允许单向依赖：应用层可依赖共享层，共享层不得反向依赖具体页面或业务域。
 - 在浏览器、服务端、存储、网络和第三方 SDK 边界建立适配层，避免组件直接承载协议细节。
 ## 组件边界
 - 让页面组件负责路由级编排，让业务组件负责明确用例，让基础组件负责可复用交互和展示。
 - 组件同时承担数据请求、复杂业务计算、多块无关 UI 和跨域副作用时，按职责拆分。
 - 不按行数机械拆分；仅在职责、复用、测试隔离或性能边界更清晰时提取。
 - 保持公共组件 API 小而稳定。避免大量布尔 props 组合出互斥模式；使用判别联合、variant 或具名 slots。
 - 不让父组件通过 DOM 查询或 template ref 修改子组件内部状态。
 - 向下传递少量明确数据；深层跨树依赖使用 provide/inject 时定义 typed injection key，并提供缺失依赖处理。
 - 设计组件时覆盖默认、loading、empty、error、disabled 和只读等适用状态。
 ## Composable
 - composable 封装可复用的有状态逻辑、生命周期或外部系统连接，不把纯函数包装成 composable。
 - 接收明确参数或响应式输入；不要隐式读取任意全局单例，除非该依赖就是契约的一部分。
 - 返回稳定、最小的公开 API。将 state 与操作区分清楚，必要时返回 readonly state。
 - 由创建资源的一方负责释放资源；在内部注册 cleanup，或向调用方暴露明确 `stop`/`dispose`。
 - 避免一个 composable 同时处理请求、表单、路由、通知和持久化；按用例编排更小能力。
 - 对有宿主组件依赖的 composable 标明生命周期约束；纯响应式 composable 应可直接单测。
 ## Pinia
 - 仅将跨组件、跨页面、需持久化或需 DevTools 跟踪的状态放入 store。
 - 每个 store 表达一个稳定业务域，使用唯一 id，并在独立文件定义。
 - state 保持最小；派生值使用 getters/computed；状态改变和业务动作通过 actions 或明确方法完成。
 - 不在组件外随意解构 store；在组件中用 `storeToRefs` 解构响应式 state/getters，actions 可直接解构。
 - setup store 必须返回所有应被 Pinia 管理的 state；不要依赖“私有 state”技巧破坏 SSR、DevTools 或插件行为。
 - 不在 store 中保存 Router/Route、DOM 元素或不可序列化第三方实例；这些依赖留在调用层或适配层。
 - 持久化仅保存必要字段，并处理版本迁移、过期、隐私与反序列化失败。
 - 测试 store 的公开 action、getter 和状态转移，不依赖内部实现顺序。
 ## Vue Router
 - 页面级组件使用动态 import 做路由懒加载；不要把异步组件与路由懒加载混为一谈。
 - 优先命名路由，集中定义 path、name 和 meta 类型。
 - 将认证、权限和通用重定向放在合适的全局或路由级 guard；不要把所有页面业务塞入全局 guard。
 - guard 返回导航结果或抛出可处理错误；避免多次调用导航、隐式 fall-through 和未处理竞态。
 - 客户端路由权限只控制体验，不构成安全边界；后端必须独立授权。
 - 路由参数和 query 都是不可信字符串输入，使用前解析、校验并处理缺失或重复值。
 - 编程式导航需要时等待结果并处理 navigation failure。
 ## API 与数据边界
 - 将 HTTP 客户端配置、认证头、错误归一化和序列化放入 API 基础层。
 - 按业务域定义 service/repository 函数，组件不直接拼接重复 URL 或处理底层响应结构。
 - 为请求参数和响应 DTO 提供类型；对不可信响应在运行时校验关键字段。
 - 在边界将 DTO 映射为前端领域模型，避免蛇形命名、nullable 约定和后端枚举扩散到整个 UI。
 - 支持请求取消或过期响应丢弃；切页、快速搜索和重复提交必须处理竞态。
 - 对 mutation 提供重复提交保护、幂等策略或清晰恢复方式。
 - 不在客户端持有服务端密钥。`VITE_*` 内容会进入客户端 bundle，只能存放公开配置。
 - 将用户可见错误转换为可行动信息，同时保留脱敏的诊断上下文。
 ## 表单
 - 分离原始 DTO、可编辑表单值、验证结果和提交 payload。
 - 明确字段 touched、dirty、validating、disabled 和 submitting 状态。
 - 客户端验证用于即时反馈，服务端仍是最终业务校验来源。
 - 服务端字段错误映射回对应控件，并提供表单级错误摘要或焦点移动。
 - 避免 watcher 组成不可追踪的双向同步链；建立单一数据源和显式 reset/submit 流程。
 - 离开页面可能丢失编辑内容时，按需求提供确认或草稿策略。
 ## SSR 与 Hydration
 - 先识别项目是否为 Nuxt、SSR、SSG 或纯 SPA，再选择数据获取和生命周期位置。
 - 不在服务端共享请求级可变单例，避免用户间状态泄漏。
 - 将浏览器 API 放在客户端生命周期或带环境判断的适配层。
 - 保证服务端与首次客户端渲染结构一致；时间、随机数、locale 和设备判断需避免 hydration mismatch。
 - setup store、持久化插件和请求缓存必须符合项目 SSR 约定。
 ## 依赖和公共 API
 - 新增依赖前证明现有能力不足，并评估体积、维护状态、类型、许可证、SSR 和 tree-shaking。
 - 不因单个小功能引入大型工具库。
 - 公共组件、composable、store 和类型一旦被多个模块使用，即视为契约；修改时检查全部调用方并补充回归测试。
 - 删除或重命名公共导出前，先迁移调用方并确认兼容策略。
 ## 官方依据
 - [Vue Composables](https://vuejs.org/guide/reusability/composables.html)
 - [Vue 状态管理](https://vuejs.org/guide/scaling-up/state-management.html)
 - [Pinia：定义 Store](https://pinia.vuejs.org/core-concepts/)
 - [Vue Router：懒加载路由](https://router.vuejs.org/guide/advanced/lazy-loading.html)
 - [Vue Router：导航守卫](https://router.vuejs.org/guide/advanced/navigation-guards.html)
 - [Vite 环境变量与模式](https://vite.dev/guide/env-and-mode)
@@ -0,0 +1,146 @@
 # Vue 核心代码规范
 ## 目录
 - 技术风格与版本适配
 - 命名与文件
 - SFC 结构
 - Props、Emits、Slots 与组件 API
 - 响应式状态
 - 模板
 - TypeScript
 - 异步与副作用
 - 样式
 - 注释与日志
 - 官方依据
 ## 技术风格与版本适配
 - 新建现代 Vue 3 SFC 时，优先使用 Composition API 与 `<script setup lang="ts">`。
 - 修改既有文件时，保持该模块的 API 风格；不要在一次无关功能变更中混合 Options API 和 Composition API。
 - 使用 `defineModel`、响应式 props 解构、`useTemplateRef` 等能力前，核实项目 Vue 版本与团队惯例。
 - 不使用实验性功能完成核心业务，除非项目已采用且存在回退或验证方案。
 ## 命名与文件
 - 使用多单词组件名，避免与原生 HTML 元素冲突。
 - 组件文件使用 `PascalCase.vue`，例如 `UserProfileCard.vue`。
 - 页面按项目约定使用 `*View.vue` 或 `*Page.vue`，不要在同一目录混用。
 - composable 使用 `useXxx.ts`，并导出同名 `useXxx` 函数。
 - Pinia store 使用 `useXxxStore`，每个 store 独立文件。
 - 布尔变量使用 `is`、`has`、`can`、`should` 等前缀。
 - 事件处理函数使用 `handleXxx`；传给 props 的回调可按项目约定使用 `onXxx`。
 - 类型、接口和泛型使用 `PascalCase`；不要默认增加 `I` 前缀。
 - 常量使用项目既有约定；仅真正跨模块、不可变的常量使用全大写形式。
 - 测试文件放在目标代码旁或项目统一测试目录，命名保持 `.spec.ts` 或 `.test.ts` 的既有选择。
 ## SFC 结构
 默认保持以下顶层顺序：
 ```vue
 <script setup lang="ts">
 // imports
 // types and component contracts
 // injected dependencies, router and stores
 // state
 // computed values
 // watchers and lifecycle
 // handlers
 </script>
 <template>
  <!-- declarative UI -->
 </template>
 <style scoped>
 /* component-owned styles */
 </style>
 ```
 - 服从项目的 block 顺序和 import 排序规则。
 - 仅在模板或组件逻辑实际需要时创建变量；不要为了分区制造空注释。
 - 组件私有样式优先 `scoped` 或项目 CSS Modules 方案；主题、reset、tokens 和工具类保持全局。
 - 避免使用 `:deep()` 穿透第三方或子组件内部；无法通过公开 API 定制时，记录耦合原因。
 ## Props、Emits、Slots 与组件 API
 - 用类型声明组件契约，为可选 props 明确默认行为。
 - props 名表示数据或状态；emits 名表示已发生的业务动作，例如 `submit`、`update:modelValue`。
 - 不以 emit 冒充命令式调用；父组件需要控制子组件时，优先 props 和状态驱动。
 - 仅在确有命令式能力时使用 `defineExpose`，并保持暴露面最小。
 - 为有双向语义的表单值使用 `v-model`/`defineModel`；普通业务数据继续使用 props + emits。
 - 不直接解构会丢失响应性的对象。解构 Pinia 状态时使用 `storeToRefs`；解构一般响应式对象时按需使用 `toRefs`。
 - 为 slots 定义清晰语义；不要让父组件依赖子组件内部 DOM 结构。
 - 可变对象或数组默认值必须保证实例隔离，并符合当前 Vue 版本支持的写法。
 ## 响应式状态
 - 对基本类型和可整体替换的值使用 `ref`。
 - 对语义内聚且主要按属性更新的对象使用 `reactive`；不要创建巨大、无边界的响应式对象。
 - 使用 `computed` 表达派生值，不将可推导数据复制进 state。
 - 不在 `computed` 中发送请求、写 store、修改其他 state 或触发日志等副作用。
 - 监听明确来源，避免无边界 deep watch；大型对象优先监听必要字段或规范化后的签名。
 - 在 watcher 中处理异步时，取消或忽略过期结果，防止旧请求覆盖新状态。
 - 对第三方实例、大型不可变结构或不需要深层代理的数据，评估 `shallowRef`/`markRaw`，但先用性能证据证明需要。
 - composable 返回值需保持稳定且易解构；需要保护写入口时向外暴露 readonly state 与显式 mutation 函数。
 ## 模板
 - 保持模板表达式简短且无副作用。
 - 为 `v-for` 提供稳定业务键；只有完全静态、永不重排的展示列表才可评估使用索引。
 - 不在同一元素上组合 `v-if` 与 `v-for`；先计算筛选结果或使用外层 `<template>`。
 - 频繁切换且初始渲染可接受时评估 `v-show`；条件低频或初始成本高时使用 `v-if`。
 - 原生交互使用原生元素：动作使用 `<button>`，导航使用 `<a>`/`RouterLink`，不要用可点击 `<div>` 代替。
 - 表单控件提供关联的 `<label>`、名称、错误提示和 disabled/loading 状态。
 - 仅在确有 HTML 内容需求且输入经过可信净化时使用 `v-html`。
 - 对异步列表和页面显式渲染 loading、empty、error 和 success 状态。
 - 使用 CSS 处理纯展示状态；不要用 JavaScript 复制 CSS 已能表达的响应式布局。
 ## TypeScript
 - 遵守项目 `strict` 配置；新代码不得主动弱化类型检查。
 - 优先类型推断，仅在公共边界、复杂返回值和可能误推断处显式标注。
 - 使用 `unknown` 接收不可信值，并通过 schema、type guard 或判别字段收窄。
 - 使用 `import type` 引入纯类型，避免无意义运行时依赖。
 - 在 API、路由参数、storage、postMessage 等外部边界做运行时校验；TypeScript 类型不能验证运行时数据。
 - 区分传输 DTO、领域模型和表单模型；存在语义差异时显式映射。
 - 优先判别联合表达有限状态，避免多个互相矛盾的布尔值。
 - 本地封闭集合优先联合类型或 `as const` 对象；是否使用 `enum` 服从项目约定。
 - 避免 `as`、`!`、`@ts-ignore`。若第三方类型确有缺陷，局部封装并说明依据。
 - 为泛型设置能表达用途的约束，不创建只为“显得通用”的泛型。
 ## 异步与副作用
 - 让异步动作表达 loading、error 和 retry/恢复策略。
 - 使用 `try/catch/finally` 保证状态复位；不要将所有异常统一转换为无信息的“失败”。
 - 区分可展示业务错误、认证/权限错误、网络错误和程序缺陷。
 - 搜索、联想和切页请求处理取消、去抖或响应顺序，防止竞态。
 - 在 `onUnmounted` 或 watcher cleanup 中释放事件监听、observer、timer、subscription 和请求。
 - 不在模块顶层执行依赖浏览器、用户或实例生命周期的副作用。
 - 对 SSR 项目避免在服务端路径直接访问 `window`、`document`、`localStorage`。
 ## 样式
 - 优先复用项目设计 tokens、组件库变量和现有布局原语。
 - 不硬编码已有 token 表达的颜色、层级、间距、圆角或字号。
 - 类名遵循项目既有 BEM、utility、CSS Modules 或其他约定。
 - 避免高特异性、`!important` 和依赖 DOM 深度的选择器。
 - 同时验证窄视口、文本放大、长内容、空内容和交互焦点。
 - 尊重 `prefers-reduced-motion`，动画不应阻止操作或传达唯一信息。
 ## 注释与日志
 - 注释解释“为什么、约束和权衡”，不要复述代码。
 - 为公共 composable、复杂协议和非直观兼容性补充必要说明。
 - 删除调试日志和断点。生产日志不得包含 token、个人信息、完整请求体或敏感业务数据。
 - TODO 必须包含可操作条件或关联任务；不要留下无主 TODO。
 ## 官方依据
 - [Vue 官方风格指南](https://vuejs.org/style-guide/)
 - [Vue `<script setup>`](https://vuejs.org/api/sfc-script-setup.html)
 - [Vue Composition API 与 TypeScript](https://vuejs.org/guide/typescript/composition-api)
 - [Vue TypeScript 总览](https://vuejs.org/guide/typescript/overview)
 - [`eslint-plugin-vue` 规则](https://eslint.vuejs.org/rules/)
@@ -0,0 +1,181 @@
 # Vue 代码范式
 仅在项目版本和既有约定支持时使用以下范式。复制前替换领域名称、错误处理和组件库 API。
 ## 类型安全组件契约
 ```vue
 <script setup lang="ts">
 import { computed } from 'vue'
 interface UserSummary {
  id: string
  displayName: string
 }
 interface Props {
  user: UserSummary
  selected?: boolean
 }
 const props = withDefaults(defineProps<Props>(), {
  selected: false,
 })
 const emit = defineEmits<{
  select: [userId: string]
 }>()
 const accessibleName = computed(() => `选择用户 ${props.user.displayName}`)
 function handleSelect(): void {
  emit('select', props.user.id)
 }
 </script>
 <template>
  <button
    type="button"
    :aria-pressed="selected"
    :aria-label="accessibleName"
    @click="handleSelect"
  >
    {{ user.displayName }}
  </button>
 </template>
 ```
 要点：
 - 将 props 和 emits 作为公共契约。
 - 使用稳定业务 id 发出事件，不把完整可变内部对象泄露出去。
 - 使用原生 button 获得键盘和语义能力。
 - 若项目 Vue 版本支持且团队采用响应式 props 解构，可用等价的解构默认值写法。
 ## 带竞态保护的 composable
 ```ts
 import { readonly, ref, toValue, watch, type MaybeRefOrGetter } from 'vue'
 interface User {
  id: string
  name: string
 }
 interface UserService {
  getUser(userId: string, signal: AbortSignal): Promise<User>
 }
 export function useUser(
  userId: MaybeRefOrGetter<string>,
  service: UserService,
 ) {
  const data = ref<User | null>(null)
  const error = ref<Error | null>(null)
  const isLoading = ref(false)
  watch(
    () => toValue(userId),
    async (currentUserId, _previousUserId, onCleanup) => {
      const controller = new AbortController()
      onCleanup(() => controller.abort())
      isLoading.value = true
      error.value = null
      try {
        data.value = await service.getUser(currentUserId, controller.signal)
      } catch (cause: unknown) {
        if (!controller.signal.aborted) {
          error.value = cause instanceof Error
            ? cause
            : new Error('Unknown user loading error')
        }
      } finally {
        if (!controller.signal.aborted) {
          isLoading.value = false
        }
      }
    },
    { immediate: true },
  )
  return {
    data: readonly(data),
    error: readonly(error),
    isLoading: readonly(isLoading),
  }
 }
 ```
 要点：
 - 通过依赖参数隔离网络边界，便于测试。
 - 对参数变化取消旧请求，避免过期结果覆盖新状态。
 - 只暴露 readonly 状态。
 - 实际项目应使用已有错误归一化，不重复定义通用错误层。
 ## 最小 Pinia Store
 ```ts
 import { computed, ref } from 'vue'
 import { defineStore } from 'pinia'
 export const useCartStore = defineStore('cart', () => {
  const itemIds = ref<string[]>([])
  const itemCount = computed(() => itemIds.value.length)
  function addItem(itemId: string): void {
    if (!itemIds.value.includes(itemId)) {
      itemIds.value.push(itemId)
    }
  }
  function clear(): void {
    itemIds.value = []
  }
  return {
    itemIds,
    itemCount,
    addItem,
    clear,
  }
 })
 ```
 要点：
 - 只保存不可推导的最小 state。
 - 用 computed 表达 getter。
 - 通过 action 表达状态变化。
 - 真实 store 若执行请求，需补齐 loading、error、并发与恢复策略。
 ## 行为导向组件测试
 ```ts
 import { mount } from '@vue/test-utils'
 import { describe, expect, it } from 'vitest'
 import UserSelectButton from './UserSelectButton.vue'
 describe('UserSelectButton', () => {
  it('emits the selected user id when activated', async () => {
    const wrapper = mount(UserSelectButton, {
      props: {
        user: { id: 'user-42', displayName: 'Ada' },
      },
    })
    await wrapper.get('button').trigger('click')
    expect(wrapper.emitted('select')).toEqual([['user-42']])
  })
 })
 ```
 要点：
 - 通过用户可操作元素交互。
 - 验证公开事件和业务结果，不访问组件内部 ref。
 - 对无障碍名称、loading、disabled 和 error 等关键状态按变更补充断言。
@@ -0,0 +1,108 @@
 # Vue 质量门禁
 ## 目录
 - 工具链
 - 测试策略
 - 安全
 - 可访问性
 - 性能
 - 兼容性与韧性
 - 验证顺序
 - 官方依据
 ## 工具链
 - 使用项目锁文件对应的包管理器和锁定版本，不生成第二种锁文件。
 - 先使用 `package.json` 已有脚本；不要猜测脚本名或绕开项目封装。
 - 对 Vue SFC 执行 `vue-tsc` 或项目等价类型检查，因为 Vite 的转译本身不进行完整类型检查。
 - 使用项目既有 ESLint 和格式化配置。新项目优先 ESLint Flat Config、`eslint-plugin-vue` 推荐配置及与 TypeScript 匹配的规则集。
 - 将格式交给自动化工具，把人工 Review 集中在行为、边界、类型和可维护性。
 - 不在功能变更中顺便升级 lint 规则或全仓格式化。
 ## 测试策略
 按风险分配测试：
 - 纯函数、数据映射、validators：单元测试。
 - composable：测试输入、状态转移、副作用和 cleanup；有组件生命周期依赖时通过宿主组件挂载。
 - Pinia store：测试 actions、getters、状态转移和失败恢复。
 - Vue 组件：以 props、emits、slots、可见 DOM 和用户交互等公开接口为中心。
 - 页面和跨模块流程：组件集成测试或 E2E。
 - 样式、原生事件、浏览器 API、cookie、storage 和网络失败：使用真实浏览器环境验证关键路径。
 遵守以下规则：
 - 优先测试用户可观察行为，不测试私有 ref、内部方法调用顺序或 CSS 实现细节。
 - 覆盖 success、loading、empty、error、disabled、边界值和竞态中与变更相关的状态。
 - 不只依赖 snapshot；为关键结果写有意义的断言。
 - 只 mock 稳定边界，例如网络、时间或第三方 SDK；不要把所有子组件都 stub 掉而失去集成价值。
 - 修复缺陷时先添加可复现失败的回归测试；无法自动化时记录人工复现和验证步骤。
 - 覆盖率用于发现盲区，不用单一百分比替代风险判断。新改动的关键分支必须有证据。
 ## 安全
 - 将模板插值作为默认文本输出方式；未经可信 sanitizer 处理，不渲染外部或用户提供的 HTML。
 - 不把用户输入直接拼接到 URL、style、动态组件、下载文件名或 DOM API；按上下文校验与编码。
 - 将认证和授权建立在后端；前端 guard、隐藏按钮和 store 状态只改善体验。
 - 不把 secrets、私钥、服务账号、数据库凭据或长期 token 放入仓库、bundle、localStorage 或 `VITE_*`。
 - 对 access token 的存储和刷新遵循项目安全架构，不自行发明持久化方案。
 - 外部链接、重定向和回调地址使用 allowlist 或严格校验，防止开放重定向。
 - 对敏感操作处理 CSRF、重放、重复提交和权限失败，具体机制由后端契约决定。
 - 日志、错误提示、埋点和测试夹具必须脱敏。
 - 依赖升级和安全修复必须独立评估兼容性并运行回归，不把审计告警机械等同于可利用漏洞。
 ## 可访问性
 - 优先使用原生语义元素，只有原生语义不足时才增加 ARIA。
 - 所有交互可用键盘完成，并有可见焦点。
 - 图标按钮提供可访问名称；装饰图标从辅助技术隐藏。
 - 表单控件关联 label，错误消息可被识别，必填和 invalid 状态不只依赖颜色。
 - 弹窗、抽屉和菜单管理初始焦点、焦点陷阱、Escape 和关闭后的焦点恢复。
 - 路由切换按产品结构更新标题、主标题或焦点，使屏幕阅读器用户感知页面变化。
 - 保持颜色对比、文本缩放、触控目标和减少动画支持。
 - 动态状态变化需要时使用合适 live region，但避免过度播报。
 ## 性能
 - 先测量再优化，区分首屏加载与交互更新性能。
 - 页面组件使用路由级代码分割；大型可选功能和低频组件按需求异步加载。
 - 选择可 tree-shake 的导入，避免引入完整工具库只使用一个函数。
 - 保持 props 稳定，减少不必要的子树更新；不要滥用 `v-memo`、`v-once` 或手工缓存。
 - 大型列表评估虚拟滚动；大型不可变数据评估浅层响应式。
 - 避免过度组件抽象导致额外实例和更新层级，尤其在大列表内。
 - 图片设置合理尺寸、格式和懒加载策略，防止布局偏移。
 - 请求去重、缓存和预取必须有失效规则，不能以陈旧数据换取表面速度。
 - 将 bundle 体积变化纳入新增依赖或大功能的验证。
 ## 兼容性与韧性
 - 按项目 `browserslist`、目标运行时和 SSR 环境验证，不假设仅运行在最新 Chrome。
 - 对网络慢、离线、超时、重复点击、刷新、返回、并发导航和权限过期处理适用状态。
 - 清理组件卸载后的回调，防止内存泄漏和卸载后更新。
 - 全局错误边界不得吞掉错误；提供用户恢复路径并保留脱敏诊断。
 - 破坏性 UI 或数据操作需要明确确认、撤销或恢复策略。
 ## 验证顺序
 先读取脚本，再按变更风险选择命令：
 1. 运行最相关的单个或少量测试。
 2. 运行 lint。
 3. 运行 `vue-tsc`/typecheck。
 4. 运行相关测试套件或覆盖率。
 5. 运行 production build。
 6. 对关键用户路径执行浏览器或 E2E 冒烟。
 若修改共享组件、路由、store、请求基础层、构建配置或公共类型，扩大到所有受影响调用方。任何跳过项都必须标为未验证，不得推测通过。
 ## 官方依据
 - [Vue 测试指南](https://vuejs.org/guide/scaling-up/testing.html)
 - [Vue 工具链](https://vuejs.org/guide/scaling-up/tooling.html)
 - [Vitest Coverage](https://vitest.dev/guide/coverage.html)
 - [Vue 安全最佳实践](https://vuejs.org/guide/best-practices/security.html)
 - [Vue 可访问性最佳实践](https://vuejs.org/guide/best-practices/accessibility.html)
 - [Vue 性能最佳实践](https://vuejs.org/guide/best-practices/performance.html)
 - [Vite 环境变量与安全提示](https://vite.dev/guide/env-and-mode)
@@ -0,0 +1,89 @@
 # Vue Review 与交付清单
 按变更风险使用清单。只勾选实际检查的项目，并将问题按严重性优先报告。
 ## 需求与范围
 - [ ] 实现与用户要求和验收标准一致。
 - [ ] 未混入依赖升级、API 迁移、全仓格式化或无关重构。
 - [ ] 已识别所有直接调用方、共享契约和回归范围。
 - [ ] 新抽象来自真实复用或清晰职责，而非假设需求。
 ## Vue 与组件
 - [ ] API 风格和 Vue 版本与项目一致。
 - [ ] 组件名为多单词，文件和符号命名符合项目约定。
 - [ ] props、emits、slots、`v-model` 与 exposed API 明确且最小。
 - [ ] 未修改 props，未破坏单向数据流。
 - [ ] 模板简洁、无副作用，复杂逻辑已移出模板。
 - [ ] `v-for` key 稳定，未在同一元素混用 `v-if` 与 `v-for`。
 - [ ] `computed` 纯净，watcher 有明确来源并清理副作用。
 - [ ] loading、empty、error、success、disabled 等适用状态完整。
 ## TypeScript 与数据
 - [ ] 未用 `any`、无依据断言、`@ts-ignore` 或 `!` 掩盖问题。
 - [ ] 外部数据、路由参数、storage 和环境变量已解析或校验。
 - [ ] DTO、领域模型和表单模型在需要时已分离。
 - [ ] 异步请求处理失败、复位、取消或过期响应。
 - [ ] 公共类型和 API 变更已检查全部调用方。
 ## 状态、路由与架构
 - [ ] 状态处于最小合理层级，没有不必要地放入 Pinia。
 - [ ] store state 最小、getter 纯净、action 边界清晰。
 - [ ] composable 依赖明确、返回面最小、资源可释放。
 - [ ] 页面路由按需懒加载，guard 没有承载不相关业务。
 - [ ] 前端权限控制未被误当成服务端授权。
 - [ ] 组件、store 与页面未直接复制底层 API 协议逻辑。
 ## 安全与隐私
 - [ ] 未将 secrets 或敏感 token 放入客户端代码、日志、测试或 `VITE_*`。
 - [ ] 未渲染未经可信净化的外部 HTML。
 - [ ] URL、重定向、动态资源和用户输入按上下文处理。
 - [ ] 错误、日志、埋点和测试数据已脱敏。
 ## 可访问性与界面
 - [ ] 使用正确的原生语义元素。
 - [ ] 所有交互可键盘操作并有可见焦点。
 - [ ] 表单控件有 label，错误和状态不只依赖颜色。
 - [ ] 图标按钮、弹窗、动态通知和路由切换有适当可访问语义。
 - [ ] 已考虑窄视口、长文本、缩放、主题和减少动画。
 ## 性能与生命周期
 - [ ] 没有无证据的过早优化或滥用缓存。
 - [ ] 页面级大模块按需加载，新增依赖的 bundle 影响合理。
 - [ ] 大列表、大对象或高频更新路径已按风险检查。
 - [ ] timer、listener、observer、subscription 和请求在适当时机清理。
 - [ ] SSR 项目没有 hydration 不一致或跨请求状态污染。
 ## 测试与验证
 - [ ] 缺陷修复有回归证据。
 - [ ] 测试关注公开行为，不耦合内部实现。
 - [ ] 关键成功、失败、空、加载和边界分支有相称覆盖。
 - [ ] 已运行适用的定向测试、lint、typecheck、测试套件、build 或 E2E。
 - [ ] 未运行或失败的检查已准确披露，不推测通过。
 ## Review 输出格式
 先报告问题，再给摘要。每个问题包含：
 ```text
 严重性 + 文件与行号
 → 可触发的具体场景
 → 对用户或系统的影响
 → 最小修复方向
 ```
 严重性建议：
 - P0：可造成安全事故、数据破坏或系统不可用，必须立即阻断。
 - P1：常见路径中的明确功能错误、权限问题或严重回归，合并前修复。
 - P2：边界条件缺陷、可维护性风险或缺失的重要测试，应尽快修复。
 - P3：低风险一致性、可读性或非阻断改进。
 若未发现可操作问题，明确说明“未发现问题”，并列出已检查范围与仍未验证的风险。