From c7bd957e6fba391936f49d5c461375b0c9cf6527 Mon Sep 17 00:00:00 2001
From: xiang <xiang@example.com>
Date: Sat, 25 Jul 2026 23:45:09 +0800
Subject: [PATCH] first commit

---
 java-coding-style/SKILL.md                    | 116 +++++++++
 java-coding-style/agents/openai.yaml          |   4 +
 .../references/01-命名格式与注释.md           |  62 +++++
 .../references/02-类型OOP与API设计.md         |  49 ++++
 .../references/03-集合并发与时间.md           |  34 +++
 .../references/04-异常日志与安全.md           |  46 ++++
 .../references/05-工程分层与数据访问.md       |  38 +++
 .../references/06-测试审查与验证.md           |  67 ++++++
 vibe-coding-governance/SKILL.md               | 104 +++++++++
 vibe-coding-governance/agents/openai.yaml     |   4 +
 .../assets/templates/01-需求分析模板.md       |  74 ++++++
 .../assets/templates/02-技术实现方案模板.md   | 123 ++++++++++
 .../assets/templates/03-冒烟与逻辑验证模板.md |  91 ++++++++
 .../assets/templates/03-冒烟自测用例模板.md   |  38 +++
 .../assets/templates/04-技术实现记录模板.md   |  54 +++++
 .../assets/templates/05-代码Review报告模板.md |  52 +++++
 .../assets/templates/06-逻辑验证报告模板.md   |  55 +++++
 .../assets/templates/06-验收与交付报告模板.md |  54 +++++
 .../assets/templates/07-验收与交付报告模板.md |  51 ++++
 .../assets/templates/L1-精简变更日志模板.md   |  71 ++++++
 .../assets/templates/代码副本清单模板.md      |  11 +
 .../assets/templates/任务状态模板.md          |  40 ++++
 .../assets/templates/原始需求版本索引模板.md  |  16 ++
 .../assets/templates/大需求总览模板.md        |  36 +++
 .../assets/templates/归档记录模板.md          |  72 ++++++
 .../assets/templates/技术侧需求分析模板.md    |  50 ++++
 .../assets/templates/模板索引.md              |  21 ++
 .../references/01-分级与门禁.md               |  94 ++++++++
 .../references/02-L0与L1轻量流程.md           | 113 +++++++++
 .../references/03-需求管理.md                 | 144 ++++++++++++
 .../references/04-需求分析.md                 | 125 ++++++++++
 .../references/05-技术方案设计.md             | 133 +++++++++++
 .../references/06-冒烟与逻辑验证.md           | 119 ++++++++++
 .../references/06-冒烟自测.md                 | 104 +++++++++
 .../references/07-代码实现.md                 | 145 ++++++++++++
 .../references/08-代码审查与验证.md           | 127 ++++++++++
 .../references/09-交付与归档.md               | 128 ++++++++++
 vibe-coding-governance/references/目录索引.md |  32 +++
 .../scripts/init_vibe_task.py                 | 221 ++++++++++++++++++
 .../scripts/validate_vibe_docs.py             | 208 +++++++++++++++++
 vue-coding-style/SKILL.md                     | 108 +++++++++
 vue-coding-style/agents/openai.yaml           |   5 +
 vue-coding-style/references/architecture.md   | 107 +++++++++
 vue-coding-style/references/core-standards.md | 146 ++++++++++++
 vue-coding-style/references/examples.md       | 181 ++++++++++++++
 vue-coding-style/references/quality-gates.md  | 108 +++++++++
 .../references/review-checklist.md            |  89 +++++++
 47 files changed, 3870 insertions(+)
 create mode 100644 java-coding-style/SKILL.md
 create mode 100644 java-coding-style/agents/openai.yaml
 create mode 100644 java-coding-style/references/01-命名格式与注释.md
 create mode 100644 java-coding-style/references/02-类型OOP与API设计.md
 create mode 100644 java-coding-style/references/03-集合并发与时间.md
 create mode 100644 java-coding-style/references/04-异常日志与安全.md
 create mode 100644 java-coding-style/references/05-工程分层与数据访问.md
 create mode 100644 java-coding-style/references/06-测试审查与验证.md
 create mode 100644 vibe-coding-governance/SKILL.md
 create mode 100644 vibe-coding-governance/agents/openai.yaml
 create mode 100644 vibe-coding-governance/assets/templates/01-需求分析模板.md
 create mode 100644 vibe-coding-governance/assets/templates/02-技术实现方案模板.md
 create mode 100644 vibe-coding-governance/assets/templates/03-冒烟与逻辑验证模板.md
 create mode 100644 vibe-coding-governance/assets/templates/03-冒烟自测用例模板.md
 create mode 100644 vibe-coding-governance/assets/templates/04-技术实现记录模板.md
 create mode 100644 vibe-coding-governance/assets/templates/05-代码Review报告模板.md
 create mode 100644 vibe-coding-governance/assets/templates/06-逻辑验证报告模板.md
 create mode 100644 vibe-coding-governance/assets/templates/06-验收与交付报告模板.md
 create mode 100644 vibe-coding-governance/assets/templates/07-验收与交付报告模板.md
 create mode 100644 vibe-coding-governance/assets/templates/L1-精简变更日志模板.md
 create mode 100644 vibe-coding-governance/assets/templates/代码副本清单模板.md
 create mode 100644 vibe-coding-governance/assets/templates/任务状态模板.md
 create mode 100644 vibe-coding-governance/assets/templates/原始需求版本索引模板.md
 create mode 100644 vibe-coding-governance/assets/templates/大需求总览模板.md
 create mode 100644 vibe-coding-governance/assets/templates/归档记录模板.md
 create mode 100644 vibe-coding-governance/assets/templates/技术侧需求分析模板.md
 create mode 100644 vibe-coding-governance/assets/templates/模板索引.md
 create mode 100644 vibe-coding-governance/references/01-分级与门禁.md
 create mode 100644 vibe-coding-governance/references/02-L0与L1轻量流程.md
 create mode 100644 vibe-coding-governance/references/03-需求管理.md
 create mode 100644 vibe-coding-governance/references/04-需求分析.md
 create mode 100644 vibe-coding-governance/references/05-技术方案设计.md
 create mode 100644 vibe-coding-governance/references/06-冒烟与逻辑验证.md
 create mode 100644 vibe-coding-governance/references/06-冒烟自测.md
 create mode 100644 vibe-coding-governance/references/07-代码实现.md
 create mode 100644 vibe-coding-governance/references/08-代码审查与验证.md
 create mode 100644 vibe-coding-governance/references/09-交付与归档.md
 create mode 100644 vibe-coding-governance/references/目录索引.md
 create mode 100644 vibe-coding-governance/scripts/init_vibe_task.py
 create mode 100644 vibe-coding-governance/scripts/validate_vibe_docs.py
 create mode 100644 vue-coding-style/SKILL.md
 create mode 100644 vue-coding-style/agents/openai.yaml
 create mode 100644 vue-coding-style/references/architecture.md
 create mode 100644 vue-coding-style/references/core-standards.md
 create mode 100644 vue-coding-style/references/examples.md
 create mode 100644 vue-coding-style/references/quality-gates.md
 create mode 100644 vue-coding-style/references/review-checklist.md

diff --git a/java-coding-style/SKILL.md b/java-coding-style/SKILL.md
new file mode 100644
index 0000000..9919587
--- /dev/null
+++ b/java-coding-style/SKILL.md
@@ -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、框架、序列化协议和工具链机械套用。
diff --git a/java-coding-style/agents/openai.yaml b/java-coding-style/agents/openai.yaml
new file mode 100644
index 0000000..a58a633
--- /dev/null
+++ b/java-coding-style/agents/openai.yaml
@@ -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."
diff --git a/java-coding-style/references/01-命名格式与注释.md b/java-coding-style/references/01-命名格式与注释.md
new file mode 100644
index 0000000..f9b2ebc
--- /dev/null
+++ b/java-coding-style/references/01-命名格式与注释.md
@@ -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
+ */
+```
diff --git a/java-coding-style/references/02-类型OOP与API设计.md b/java-coding-style/references/02-类型OOP与API设计.md
new file mode 100644
index 0000000..48f357d
--- /dev/null
+++ b/java-coding-style/references/02-类型OOP与API设计.md
@@ -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` 不得暴露敏感字段，也不得触发懒加载或递归引用。
diff --git a/java-coding-style/references/03-集合并发与时间.md b/java-coding-style/references/03-集合并发与时间.md
new file mode 100644
index 0000000..09b672a
--- /dev/null
+++ b/java-coding-style/references/03-集合并发与时间.md
@@ -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` 或等价抽象，避免依赖当前时间造成不稳定测试。
+- **推荐**：日期边界、夏令时、闰年和跨时区转换要有针对性用例。
diff --git a/java-coding-style/references/04-异常日志与安全.md b/java-coding-style/references/04-异常日志与安全.md
new file mode 100644
index 0000000..79a4069
--- /dev/null
+++ b/java-coding-style/references/04-异常日志与安全.md
@@ -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、事件或补偿机制，不临时发明“先写库再发消息”的脆弱流程。
diff --git a/java-coding-style/references/05-工程分层与数据访问.md b/java-coding-style/references/05-工程分层与数据访问.md
new file mode 100644
index 0000000..7da67e8
--- /dev/null
+++ b/java-coding-style/references/05-工程分层与数据访问.md
@@ -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 与项目已有库；为一个简单方法引入大型依赖通常不合理。
+- **必须**：生成代码和资源遵循构建目录约定，不手改会被生成器覆盖的文件。
diff --git a/java-coding-style/references/06-测试审查与验证.md b/java-coding-style/references/06-测试审查与验证.md
new file mode 100644
index 0000000..e036256
--- /dev/null
+++ b/java-coding-style/references/06-测试审查与验证.md
@@ -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
+命令或检查：
+范围：
+结果：通过 / 失败 / 未执行
+证据摘要：
+失败或未执行原因：
+```
+
+只报告本次实际获得的证据。环境错误、既有失败和本次回归必须区分；无法确定归属时标记为待调查，不得猜测。
diff --git a/vibe-coding-governance/SKILL.md b/vibe-coding-governance/SKILL.md
new file mode 100644
index 0000000..17418e0
--- /dev/null
+++ b/vibe-coding-governance/SKILL.md
@@ -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
+用户本次明确指示
+→ 已确认的任务文档和门禁结论
+→ 作用域最近的项目指令
+→ 项目自动化规则和模块既有惯例
+→ 语言或框架通用惯例
+```
+
+这些来源发生实质冲突时，必须提出并请用户确认。项目级例外只有在明确记录后才能覆盖本流程。
diff --git a/vibe-coding-governance/agents/openai.yaml b/vibe-coding-governance/agents/openai.yaml
new file mode 100644
index 0000000..97b52df
--- /dev/null
+++ b/vibe-coding-governance/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Vibe Coding 开发规范"
+  short_description: "按 L0/L1/L2 分级门禁执行完整 Vibe Coding 开发流程"
+  default_prompt: "使用 $vibe-coding-governance 按约定的 Vibe Coding 规范评估并执行这个开发任务。"
diff --git a/vibe-coding-governance/assets/templates/01-需求分析模板.md b/vibe-coding-governance/assets/templates/01-需求分析模板.md
new file mode 100644
index 0000000..4326276
--- /dev/null
+++ b/vibe-coding-governance/assets/templates/01-需求分析模板.md
@@ -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)
diff --git a/vibe-coding-governance/assets/templates/02-技术实现方案模板.md b/vibe-coding-governance/assets/templates/02-技术实现方案模板.md
new file mode 100644
index 0000000..0bd641d
--- /dev/null
+++ b/vibe-coding-governance/assets/templates/02-技术实现方案模板.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. 需求追溯
+
+| 需求/功能 | 方案章节 | 工程 | 验收标准 | 验证用例 |
+|---|---|---|---|---|
diff --git a/vibe-coding-governance/assets/templates/03-冒烟与逻辑验证模板.md b/vibe-coding-governance/assets/templates/03-冒烟与逻辑验证模板.md
new file mode 100644
index 0000000..6789219
--- /dev/null
+++ b/vibe-coding-governance/assets/templates/03-冒烟与逻辑验证模板.md
@@ -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. 验证结论
+
+- 核心主流程是否通过：{{是/否}}
+- 范围内功能是否全部验证：{{是/否}}
+- 是否存在阻断问题：{{是/否}}
+- 未验证项：{{内容}}
+- 是否具备提测条件：{{是/否}}
diff --git a/vibe-coding-governance/assets/templates/03-冒烟自测用例模板.md b/vibe-coding-governance/assets/templates/03-冒烟自测用例模板.md
new file mode 100644
index 0000000..9a614a9
--- /dev/null
+++ b/vibe-coding-governance/assets/templates/03-冒烟自测用例模板.md
@@ -0,0 +1,38 @@
+# {{ST编号}} {{子任务名称}}冒烟自测用例
+
+## 1. 文档信息
+
+- 大需求编号：{{PM编号}}
+- 子任务编号：{{ST编号}}
+- 需求版本：{{版本}}
+- 技术方案版本：{{版本}}
+- 提测版本或 Commit：{{Commit}}
+- 测试环境：{{环境}}
+
+## 2. 自测范围
+
+- 核心主流程：{{流程}}
+- 本次功能点：{{功能}}
+- 关键回归：{{回归}}
+- 非本次自测范围：{{非范围}}
+
+## 3. 前置条件和测试数据
+
+## 4. 冒烟自测用例
+
+| 编号 | 功能点 | 验证场景 | 前置条件 | 操作步骤 | 预期结果 | 实际结果 | 状态 | 证据 |
+|---|---|---|---|---|---|---|---|---|
+| TC-001 | F-001 | {{场景}} | {{条件}} | {{步骤}} | {{预期}} | | 未执行 | |
+
+## 5. 功能覆盖检查
+
+| 功能编号 | 功能名称 | 对应用例 | 是否已验证 |
+|---|---|---|---|
+
+## 6. 自测结论
+
+- 核心主流程是否通过：{{是/否/未执行}}
+- 需求功能点是否全部验证：{{是/否}}
+- 是否存在阻断问题：{{是/否}}
+- 未通过或未验证项：{{内容}}
+- 是否具备提测条件：{{是/否}}
diff --git a/vibe-coding-governance/assets/templates/04-技术实现记录模板.md b/vibe-coding-governance/assets/templates/04-技术实现记录模板.md
new file mode 100644
index 0000000..eb45186
--- /dev/null
+++ b/vibe-coding-governance/assets/templates/04-技术实现记录模板.md
@@ -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 和差异：{{记录}}
diff --git a/vibe-coding-governance/assets/templates/05-代码Review报告模板.md b/vibe-coding-governance/assets/templates/05-代码Review报告模板.md
new file mode 100644
index 0000000..ce0405a
--- /dev/null
+++ b/vibe-coding-governance/assets/templates/05-代码Review报告模板.md
@@ -0,0 +1,52 @@
+# {{ST编号}} {{子任务名称}}代码 Review 报告
+
+## 1. Review 信息
+
+- 需求版本：{{版本}}
+- 技术方案版本：{{版本}}
+- 工程及分支：{{工程/分支}}
+- Review Commit：{{Commit}}
+- Review 范围：{{范围}}
+- 变更清单或差异来源：{{用户提供/本次编辑记录}}
+- Review 时间：{{时间}}
+
+## 2. 需求符合性
+
+| 检查项 | 结论 | 说明 |
+|---|---|---|
+| 需求功能覆盖 | | |
+| 技术方案符合 | | |
+| 影响范围处理 | | |
+| 无范围外实现 | | |
+
+## 3. 项目规范符合性
+
+| 检查项 | 结论 | 说明 |
+|---|---|---|
+| 架构与分层 | | |
+| 命名与代码风格 | | |
+| 异常、日志和错误码 | | |
+| 测试风格 | | |
+
+## 4. 核心架构变化
+
+| 检查项 | 是否变化 | 是否符合方案 | 结论 |
+|---|---|---|---|
+
+## 5. Review 问题
+
+| 编号 | 等级 | 工程及位置 | 问题 | 影响 | 处理状态 |
+|---|---|---|---|---|---|
+
+## 6. 问题修复及复查
+
+| 问题编号 | 修复内容 | 复查结果 | 证据 |
+|---|---|---|---|
+
+## 7. 未确认风险
+
+## 8. Review 结论
+
+- Critical/High 是否清零：{{是/否}}
+- 是否需要重开方案门禁：{{是/否}}
+- 结论：在本次检查范围内{{结论}}
diff --git a/vibe-coding-governance/assets/templates/06-逻辑验证报告模板.md b/vibe-coding-governance/assets/templates/06-逻辑验证报告模板.md
new file mode 100644
index 0000000..874cb60
--- /dev/null
+++ b/vibe-coding-governance/assets/templates/06-逻辑验证报告模板.md
@@ -0,0 +1,55 @@
+# {{ST编号}} {{子任务名称}}逻辑验证报告
+
+## 1. 验证信息
+
+- 需求版本：{{版本}}
+- 技术方案版本：{{版本}}
+- 验证工程和分支：{{工程/分支}}
+- 验证 Commit：{{Commit}}
+- 验证环境：{{环境}}
+- 验证时间：{{时间}}
+
+## 2. 静态检查与构建
+
+| 检查项 | 命令/方式 | 结果 | 证据或说明 |
+|---|---|---|---|
+
+## 3. 自动化测试
+
+| 测试类型 | 测试范围 | 通过 | 失败 | 结果 |
+|---|---|---|---|---|
+
+## 4. 冒烟自测
+
+| 用例编号 | 功能点 | 预期结果 | 实际结果 | 状态 | 证据 |
+|---|---|---|---|---|---|
+
+## 5. 关键回归
+
+| 回归编号 | 场景 | 结果 | 证据 |
+|---|---|---|---|
+
+## 6. 接口与数据验证
+
+- 接口：
+- 数据库：
+- Redis：
+- Elasticsearch：
+- 消息及异步任务：
+- 日志和监控：
+
+## 7. 失败与修复
+
+| 编号 | 失败 | 原因 | 修复 | 重验结果 |
+|---|---|---|---|---|
+
+## 8. 未执行项及原因
+
+## 9. 遗留问题和风险
+
+## 10. 验证结论
+
+- 核心主流程是否通过：{{是/否}}
+- 范围内功能是否全部验证：{{是/否}}
+- 是否存在阻断问题：{{是/否}}
+- 是否具备提测条件：{{是/否}}
diff --git a/vibe-coding-governance/assets/templates/06-验收与交付报告模板.md b/vibe-coding-governance/assets/templates/06-验收与交付报告模板.md
new file mode 100644
index 0000000..6395044
--- /dev/null
+++ b/vibe-coding-governance/assets/templates/06-验收与交付报告模板.md
@@ -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` 由用户执行；报告证据必须脱敏。
diff --git a/vibe-coding-governance/assets/templates/07-验收与交付报告模板.md b/vibe-coding-governance/assets/templates/07-验收与交付报告模板.md
new file mode 100644
index 0000000..cafc410
--- /dev/null
+++ b/vibe-coding-governance/assets/templates/07-验收与交付报告模板.md
@@ -0,0 +1,51 @@
+# {{ST编号}} {{子任务名称}}验收与交付报告
+
+## 1. 交付信息
+
+- 需求版本：{{版本}}
+- 涉及工程：{{工程}}
+- 开发分支：{{分支}}
+- 发布分支或 Tag：{{分支/Tag}}
+- 发布 Commit：{{Commit}}
+
+## 2. 开发交付内容
+
+## 3. 测试结果
+
+- 测试环境：{{环境}}
+- 测试时间：{{时间}}
+- 测试人员：{{人员}}
+- 测试结论：{{结论}}
+- 缺陷及处理情况：{{内容}}
+- 测试报告：{{链接或编号}}
+
+## 4. 发布记录
+
+- 发布时间：{{时间}}
+- 发布环境：{{环境}}
+- 发布版本：{{版本}}
+- 发布工程：{{工程}}
+- 数据脚本：{{脚本}}
+- 配置变化：{{配置}}
+- 实际发布顺序：{{顺序}}
+
+## 5. 上线验证
+
+| 检查项 | 验证方式 | 结果 | 证据 |
+|---|---|---|---|
+| 核心主流程 | | | |
+| 关键接口 | | | |
+| 数据库 | | | |
+| Redis | | | |
+| Elasticsearch | | | |
+| 消息及任务 | | | |
+| 日志和监控 | | | |
+
+## 6. 遗留问题
+
+## 7. 最终结论
+
+- 是否测试通过：{{是/否}}
+- 是否发布成功：{{是/否}}
+- 是否完成上线验证：{{是/否}}
+- 是否满足归档条件：{{是/否}}
diff --git a/vibe-coding-governance/assets/templates/L1-精简变更日志模板.md b/vibe-coding-governance/assets/templates/L1-精简变更日志模板.md
new file mode 100644
index 0000000..d724211
--- /dev/null
+++ b/vibe-coding-governance/assets/templates/L1-精简变更日志模板.md
@@ -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`：否
diff --git a/vibe-coding-governance/assets/templates/代码副本清单模板.md b/vibe-coding-governance/assets/templates/代码副本清单模板.md
new file mode 100644
index 0000000..f7d9902
--- /dev/null
+++ b/vibe-coding-governance/assets/templates/代码副本清单模板.md
@@ -0,0 +1,11 @@
+# 代码分析副本清单
+
+| 工程 | 本地目录 | 远端仓库 | 基准分支 | 当前 Commit | 更新时间 | 备注 |
+|---|---|---|---|---|---|---|
+
+## 异常记录
+
+| 时间 | 工程 | 异常 | 处理状态 |
+|---|---|---|---|
+
+> `code/` 只用于调查；需求开发在独立项目工作区完成。
diff --git a/vibe-coding-governance/assets/templates/任务状态模板.md b/vibe-coding-governance/assets/templates/任务状态模板.md
new file mode 100644
index 0000000..fe60480
--- /dev/null
+++ b/vibe-coding-governance/assets/templates/任务状态模板.md
@@ -0,0 +1,40 @@
+# {{PM编号}} 任务状态
+
+## 1. 大需求状态
+
+- 需求名称：{{名称}}
+- 当前需求版本：{{版本}}
+- 当前总体状态：{{状态}}
+- 当前主要阶段：{{阶段}}
+- 最后更新时间：{{时间}}
+- 当前阻塞项：{{阻塞或“无”}}
+
+## 2. 门禁状态
+
+| 门禁 | 状态 | 原始需求版本 | 确认文档及版本 | 代码版本标识 | 确认时间 | 确认来源 | 确认范围/说明 |
+|---|---|---|---|---|---|---|---|
+| G1 需求门禁 | 待确认 | | | 不适用 | | | |
+| G2 方案门禁 | 未开始 | | | | | | |
+| G3 开发交付门禁 | 未开始 | | | | | | |
+
+## 3. 子任务状态
+
+| 子任务 | 业务模块 | 当前阶段 | 当前状态 | 阻塞项 | 最后更新 |
+|---|---|---|---|---|---|
+
+## 4. 阶段完成情况
+
+| 子任务 | 需求分析 | 技术方案 | 验证计划 | 实现 | Review | 逻辑验证 | 测试 | 上线 |
+|---|---|---|---|---|---|---|---|---|---|
+
+## 5. 阻塞事项
+
+| 编号 | 子任务 | 阻塞内容 | 影响阶段 | 提出时间 | 处理方 | 状态 |
+|---|---|---|---|---|---|---|
+
+## 6. 状态变更历史
+
+| 时间 | 对象 | 原阶段/状态 | 新阶段/状态 | 变更原因 | 操作者 | 证据 |
+|---|---|---|---|---|---|---|
+
+> `STATUS.md` 是状态唯一事实来源。其他文档中的状态字段仅用于展示，发生冲突时以本文件为准。
diff --git a/vibe-coding-governance/assets/templates/原始需求版本索引模板.md b/vibe-coding-governance/assets/templates/原始需求版本索引模板.md
new file mode 100644
index 0000000..1b5582e
--- /dev/null
+++ b/vibe-coding-governance/assets/templates/原始需求版本索引模板.md
@@ -0,0 +1,16 @@
+# 原始需求版本索引
+
+| 版本 | 接收时间 | 需求来源 | 文件或目录 | 主要变化 | 状态 |
+|---|---|---|---|---|---|
+| v1 | {{时间}} | {{来源}} | [查看](./v1/) | 初始版本 | 当前版本 |
+
+## 补充需求记录
+
+| 编号 | 时间 | 来源 | 内容 | 是否进入正式版本 |
+|---|---|---|---|---|
+
+## 管理规则
+
+- 原始文件只读，不覆盖旧版本。
+- 每个版本尽量保存完整材料。
+- 新版本到达后进行差异和影响分析。
diff --git a/vibe-coding-governance/assets/templates/大需求总览模板.md b/vibe-coding-governance/assets/templates/大需求总览模板.md
new file mode 100644
index 0000000..84d4192
--- /dev/null
+++ b/vibe-coding-governance/assets/templates/大需求总览模板.md
@@ -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`，并在此补充链接。
diff --git a/vibe-coding-governance/assets/templates/归档记录模板.md b/vibe-coding-governance/assets/templates/归档记录模板.md
new file mode 100644
index 0000000..3df2daf
--- /dev/null
+++ b/vibe-coding-governance/assets/templates/归档记录模板.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. 归档结论
+
+{{最终结论}}
diff --git a/vibe-coding-governance/assets/templates/技术侧需求分析模板.md b/vibe-coding-governance/assets/templates/技术侧需求分析模板.md
new file mode 100644
index 0000000..96a1b2d
--- /dev/null
+++ b/vibe-coding-governance/assets/templates/技术侧需求分析模板.md
@@ -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. 子任务文档索引
diff --git a/vibe-coding-governance/assets/templates/模板索引.md b/vibe-coding-governance/assets/templates/模板索引.md
new file mode 100644
index 0000000..1b1d230
--- /dev/null
+++ b/vibe-coding-governance/assets/templates/模板索引.md
@@ -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` |
+
+复制后删除不适用的示例行，但保留必要章节；不适用的关键章节写明原因。
diff --git a/vibe-coding-governance/references/01-分级与门禁.md b/vibe-coding-governance/references/01-分级与门禁.md
new file mode 100644
index 0000000..7f6c3d2
--- /dev/null
+++ b/vibe-coding-governance/references/01-分级与门禁.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 或等价版本标识；
+- 确认时间、确认来源和确认范围。
+
+门禁通过后，确认对象发生实质修改时，将门禁改为“需要重新确认”，记录失效原因并停止进入下一阶段。仅修正错别字、链接等不改变语义的编辑可以保留门禁，但要写入状态历史。
+
+## 重开与升级
+
+出现以下情况时，暂停受影响工作并退回失效阶段：
+
+- 出现需求矛盾；
+- 必须改变已确认的业务规则；
+- 影响扩大到其他工程或核心功能；
+- 接口兼容、数据设计或架构发生实质变化；
+- 原方案不可行；
+- 需要破坏性或不可逆操作。
+
+新证据触发更高等级时必须升级，并在继续前补齐产物。只有用户明确确认后才能降级。
+
+不改变已确认行为、契约、数据、架构和影响范围的私有实现调整无需重开门禁，但要写入实现记录。
diff --git a/vibe-coding-governance/references/02-L0与L1轻量流程.md b/vibe-coding-governance/references/02-L0与L1轻量流程.md
new file mode 100644
index 0000000..9087a09
--- /dev/null
+++ b/vibe-coding-governance/references/02-L0与L1轻量流程.md
@@ -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`；暂存、提交和推送由用户完成。变更日志中的请求响应、日志和测试证据必须脱敏。
diff --git a/vibe-coding-governance/references/03-需求管理.md b/vibe-coding-governance/references/03-需求管理.md
new file mode 100644
index 0000000..27952ea
--- /dev/null
+++ b/vibe-coding-governance/references/03-需求管理.md
@@ -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` 为准。
+
+当前状态表：
+
+| 子任务 | 业务模块 | 当前阶段 | 当前状态 | 阻塞项 | 最后更新 |
+|---|---|---|---|---|---|
+
+历史表：
+
+| 时间 | 对象 | 原阶段/状态 | 新阶段/状态 | 原因 | 操作者 | 证据 |
+|---|---|---|---|---|---|---|
diff --git a/vibe-coding-governance/references/04-需求分析.md b/vibe-coding-governance/references/04-需求分析.md
new file mode 100644
index 0000000..cab5373
--- /dev/null
+++ b/vibe-coding-governance/references/04-需求分析.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` 并绑定上述版本。
diff --git a/vibe-coding-governance/references/05-技术方案设计.md b/vibe-coding-governance/references/05-技术方案设计.md
new file mode 100644
index 0000000..ae8155c
--- /dev/null
+++ b/vibe-coding-governance/references/05-技术方案设计.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；确认前不得开始实现。
diff --git a/vibe-coding-governance/references/06-冒烟与逻辑验证.md b/vibe-coding-governance/references/06-冒烟与逻辑验证.md
new file mode 100644
index 0000000..5843101
--- /dev/null
+++ b/vibe-coding-governance/references/06-冒烟与逻辑验证.md
@@ -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。
diff --git a/vibe-coding-governance/references/06-冒烟自测.md b/vibe-coding-governance/references/06-冒烟自测.md
new file mode 100644
index 0000000..45cc1c4
--- /dev/null
+++ b/vibe-coding-governance/references/06-冒烟自测.md
@@ -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 可采用：
+
+| 功能点 | 最低验证 |
+|---|---|
+| 新增 | 创建成功且数据结果正确 |
+| 修改 | 修改成功且查询结果正确 |
+| 查询 | 能查询到正确目标数据 |
+| 列表 | 核心筛选和分页可用 |
+| 删除 | 删除成功且后续结果符合规则 |
+
+只有明确关键的边界才增加用例，例如无权限、非法状态、重复提交、审核中禁止删除，或接口变更后的关键调用方回归。
+
+技术方案中的完整回归范围可以大于冒烟范围；冒烟只选择影响主流程、需求功能和提测质量的关键场景。
+
+## 通过结论
+
+只有以下条件同时满足，才能写“具备提测条件”：
+
+- 核心主流程通过；
+- 范围内功能点都有验证记录；
+- 没有阻断缺陷；
+- 接口变更影响的关键旧功能完成必要回归；
+- 未验证内容已明确且不阻断提测。
+
+环境、权限或依赖不足时标记“未验证”，禁止默认通过。
diff --git a/vibe-coding-governance/references/07-代码实现.md b/vibe-coding-governance/references/07-代码实现.md
new file mode 100644
index 0000000..d421fb3
--- /dev/null
+++ b/vibe-coding-governance/references/07-代码实现.md
@@ -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，不等于子任务最终完成。
diff --git a/vibe-coding-governance/references/08-代码审查与验证.md b/vibe-coding-governance/references/08-代码审查与验证.md
new file mode 100644
index 0000000..caf079c
--- /dev/null
+++ b/vibe-coding-governance/references/08-代码审查与验证.md
@@ -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。
diff --git a/vibe-coding-governance/references/09-交付与归档.md b/vibe-coding-governance/references/09-交付与归档.md
new file mode 100644
index 0000000..a0c8148
--- /dev/null
+++ b/vibe-coding-governance/references/09-交付与归档.md
@@ -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 的引入不得改变前置开发流程、文档编号、需求追溯和状态历史。
diff --git a/vibe-coding-governance/references/目录索引.md b/vibe-coding-governance/references/目录索引.md
new file mode 100644
index 0000000..f9e45b1
--- /dev/null
+++ b/vibe-coding-governance/references/目录索引.md
@@ -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
+```
+
+需求变化时，重新读取所有被影响阶段的参考文件，不得只更新最新一份文档。
diff --git a/vibe-coding-governance/scripts/init_vibe_task.py b/vibe-coding-governance/scripts/init_vibe_task.py
new file mode 100644
index 0000000..0b6770e
--- /dev/null
+++ b/vibe-coding-governance/scripts/init_vibe_task.py
@@ -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())
diff --git a/vibe-coding-governance/scripts/validate_vibe_docs.py b/vibe-coding-governance/scripts/validate_vibe_docs.py
new file mode 100644
index 0000000..a87a416
--- /dev/null
+++ b/vibe-coding-governance/scripts/validate_vibe_docs.py
@@ -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())
diff --git a/vue-coding-style/SKILL.md b/vue-coding-style/SKILL.md
new file mode 100644
index 0000000..912a6fc
--- /dev/null
+++ b/vue-coding-style/SKILL.md
@@ -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、构建或人工冒烟；
+- 未验证项、兼容性风险和剩余问题。
+
diff --git a/vue-coding-style/agents/openai.yaml b/vue-coding-style/agents/openai.yaml
new file mode 100644
index 0000000..34db9ba
--- /dev/null
+++ b/vue-coding-style/agents/openai.yaml
@@ -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."
+
diff --git a/vue-coding-style/references/architecture.md b/vue-coding-style/references/architecture.md
new file mode 100644
index 0000000..7be4be4
--- /dev/null
+++ b/vue-coding-style/references/architecture.md
@@ -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)
+
diff --git a/vue-coding-style/references/core-standards.md b/vue-coding-style/references/core-standards.md
new file mode 100644
index 0000000..b3ef346
--- /dev/null
+++ b/vue-coding-style/references/core-standards.md
@@ -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/)
+
diff --git a/vue-coding-style/references/examples.md b/vue-coding-style/references/examples.md
new file mode 100644
index 0000000..46205f7
--- /dev/null
+++ b/vue-coding-style/references/examples.md
@@ -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 等关键状态按变更补充断言。
+
diff --git a/vue-coding-style/references/quality-gates.md b/vue-coding-style/references/quality-gates.md
new file mode 100644
index 0000000..cb024c2
--- /dev/null
+++ b/vue-coding-style/references/quality-gates.md
@@ -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)
+
diff --git a/vue-coding-style/references/review-checklist.md b/vue-coding-style/references/review-checklist.md
new file mode 100644
index 0000000..27493c1
--- /dev/null
+++ b/vue-coding-style/references/review-checklist.md
@@ -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：低风险一致性、可读性或非阻断改进。
+
+若未发现可操作问题，明确说明“未发现问题”，并列出已检查范围与仍未验证的风险。