soloforge 1.1.37 → 1.1.40

package/templates/artifacts/existing-system//345/216/206/345/217/262/346/225/260/346/215/256/346/270/205/346/264/227/350/204/232/346/234/254/346/250/241/347/211/210.md

@@ -1,18 +1,15 @@
 ---
 name: historical-data-cleanup-script
 type: acceptance_template
-asset_kind: acceptance_template
-routes:
-  - analysis
-primary_triggers:
-  - 数据清洗
-  - 历史数据
-  - ETL
 scope: ['*']
 system_scope: ['existing-system']
 stages: ["联调验证"]
 lifecycle_status: active
 owner_mechanism_id: mc-existing-system-artifact
+companion_rules: []
+companion_gates: []
+requires_context: []
+consumes: []
 ---
 
 # 历史数据清洗脚本
@@ -39,10 +36,17 @@ CREATE TABLE <!-- 表名 -->_backup_YYYYMMDD AS SELECT * FROM <!-- 表名 -->;
 -- 验证
 SELECT COUNT(*) FROM <!-- 表名 --> WHERE <!-- 条件 -->;
 
+-- 验证通过标准
+-- 预期影响行数：<!-- N 行 -->
+-- 允许偏差：± <!-- X% -->
+-- 执行超时：<!-- 如 30 分钟 -->
+
 ```
 
 ## 4. 回滚方案
 ```sql
 -- 回滚
 INSERT INTO <!-- 表名 --> SELECT * FROM <!-- 表名 -->_backup_YYYYMMDD;
+
+-- 回滚前确认：备份表行数 = 清洗前原表行数
 ```

package/templates/artifacts/existing-system//345/216/206/345/217/262/351/201/227/347/225/231/351/233/267/345/214/272/346/270/205/345/215/225/346/250/241/347/211/210.md

@@ -1,18 +1,15 @@
 ---
 name: legacy-minefield-checklist
 type: acceptance_template
-asset_kind: acceptance_template
-routes:
-  - analysis
-primary_triggers:
-  - 雷区清单
-  - 历史遗留
-  - 风险
 scope: ['*']
 system_scope: ['existing-system']
-stages: ["编码与单元测试"]
+stages: ["现有系统分析", "编码与单元测试"]
 lifecycle_status: active
 owner_mechanism_id: mc-existing-system-artifact
+companion_rules: ["雷区反模式清单.md:check"]
+requires_context: []
+consumes: []
+triggers: ['雷区清单', '历史遗留', '反模式', 'minefield', '技术债']
 ---
 
 # 历史遗留雷区清单
@@ -25,23 +22,26 @@ owner_mechanism_id: mc-existing-system-artifact
 
 | # | 类型 | 严重程度 | 位置 | 描述 | 影响范围 |
 |---|---|---|---|---|---|
-| 1 | <!-- 反模式类型 --> | 高/中/低 | <!-- 文件:行号或模块 --> | <!-- 描述 --> | <!-- 影响的接口/服务 --> |
+| 1 | 数据库/代码/架构 | 高/中/低 | <!-- 文件:行号或模块 --> | <!-- 描述 --> | <!-- 影响的接口/服务 --> |
 
-## 3. 反模式分类
+## 3. 反模式分类（与规则对齐）
 
-### 高风险
-- 无索引大表
+> 分类标准与 `雷区反模式清单.md` 规则一致，按数据库/代码/架构三维度组织。
+
+### 数据库层面
+- 无索引大表（>10 万行）
+- 循环查库（N+1）
 - 全表扫描
-- 循环调用外部接口
-- 硬编码配置/密钥
+- 缺少事务
 
-### 中风险
-- 冗余索引
-- 未使用的代码/表
-- 不一致的错误处理
-- 缺少事务的写操作
+### 代码层面
+- 硬编码配置/密钥
+- 大函数/大类（>100 行 / >1000 行）
+- 循环调用外部接口
+- 吞异常
 
-### 低风险
-- 命名不规范
-- 缺少注释
-- 日志级别不当
+### 架构层面
+- 循环依赖
+- 共享数据库
+- 缺少降级
+- 同步阻塞

package/templates/artifacts/existing-system//345/220/221/345/220/216/345/205/274/345/256/271/346/200/247/345/220/210/350/247/204/346/212/245/345/221/212/346/250/241/347/211/210.md

@@ -1,18 +1,15 @@
 ---
 name: backward-compatibility-report
 type: acceptance_template
-asset_kind: acceptance_template
-routes:
-  - analysis
-primary_triggers:
-  - 兼容性
-  - 合规报告
-  - 向后兼容
 scope: ['*']
 system_scope: ['existing-system']
-stages: ["*"]
+stages: ["详细设计", "代码审查"]
 lifecycle_status: active
 owner_mechanism_id: mc-existing-system-artifact
+companion_rules: ["兼容性检查规则.md:check"]
+companion_gates: ["gate-详细设计.yaml"]
+requires_context: ["reference_trace"]
+consumes: []
 ---
 
 # 向后兼容性合规报告
@@ -23,18 +20,30 @@ owner_mechanism_id: mc-existing-system-artifact
 
 ## 2. 接口兼容性
 
-| 接口 | 检查项 | 兼容 | 说明 |
-|---|---|---|---|
-| <!-- 接口名 --> | 参数是否被删除/修改 | 是/否 | <!-- 说明 --> |
-| <!-- 接口名 --> | 返回结构是否破坏性变更 | 是/否 | <!-- 说明 --> |
+| 接口 | 检查项 | COMP 规则 | 兼容 | 说明 |
+|---|---|---|---|---|
+| <!-- 接口名 --> | 参数是否被删除 | COMP-API-01 | 是/否 | <!-- 说明 --> |
+| <!-- 接口名 --> | 参数类型是否窄化 | COMP-API-02 | 是/否 | <!-- 说明 --> |
+| <!-- 接口名 --> | 返回结构是否破坏性变更 | COMP-API-03 | 是/否 | <!-- 说明 --> |
 
 ## 3. 数据库兼容性
 
-| 表 | 检查项 | 兼容 | 说明 |
-|---|---|---|---|
-| <!-- 表名 --> | 变更对老数据是否兼容 | 是/否 | <!-- 说明 --> |
+| 表 | 检查项 | COMP 规则 | 兼容 | 说明 |
+|---|---|---|---|---|
+| <!-- 表名 --> | 是否删除列 | COMP-DB-01 | 是/否 | <!-- 说明 --> |
+| <!-- 表名 --> | 新增列是否有默认值 | COMP-DB-03 | 是/否 | <!-- 说明 --> |
+| <!-- 表名 --> | 变更对老数据是否兼容 | — | 是/否 | <!-- 说明 --> |
+
+## 3.5 行为兼容性
+
+| 功能 | 检查项 | COMP 规则 | 兼容 | 证据 |
+|------|--------|---------|------|------|
+| <!-- 功能 --> | 开关关闭时输出与老版本一致 | COMP-BEH-01 | 是/否 | 新老逻辑比对日志 |
+| <!-- 功能 --> | 新老逻辑可共存 | COMP-BEH-02 | 是/否 | Feature Toggle 切换测试 |
+| <!-- 功能 --> | 回滚后功能恢复正常 | COMP-BEH-03 | 是/否 | 回滚验证记录 |
 
 ## 4. 结论
-- **整体结论：** 通过/不通过
+- **兼容率：** 兼容项数 / 总检查项数 = <!-- 百分比 -->
+- **整体结论：** 通过（兼容率 100%）/ 不通过
 - **风险项：**
   - <!-- 风险描述 -->

package/templates/artifacts/existing-system//345/242/236/351/207/217/350/276/271/347/225/214/347/225/214/345/256/232/346/226/207/346/241/243/346/250/241/347/211/210.md

@@ -1,18 +1,15 @@
 ---
 name: incremental-boundary-document
 type: acceptance_template
-asset_kind: acceptance_template
-routes:
-  - analysis
-primary_triggers:
-  - 增量边界
-  - 边界界定
-  - 改造范围
 scope: ['*']
 system_scope: ['existing-system']
-stages: ["架构设计", "详细设计"]
+stages: ["需求分析", "架构设计", "详细设计"]
 lifecycle_status: active
 owner_mechanism_id: mc-existing-system-artifact
+requires_context: ["file_impact", "reference_trace"]
+companion_rules: []
+companion_gates: []
+consumes: []
 ---
 
 # 增量边界界定文档
@@ -23,18 +20,26 @@ owner_mechanism_id: mc-existing-system-artifact
 
 ## 2. 受影响模块
 
-| # | 模块 | 变更类型 | 说明 |
-|---|---|---|---|
-| 1 | <!-- 模块名 --> | 新增/修改/删除 | <!-- 说明 --> |
+| # | 模块 | 变更类型 | 关联需求 | 说明 |
+|---|------|---------|---------|------|
+| 1 | <!-- 模块名 --> | 新增/修改/删除 | REQ-NNN | <!-- 说明 --> |
+
+> 变更类型判定：纯新文件/函数/表 → 新增；已有文件中的新增字段/接口 → 修改；移除已有功能 → 删除
 
 ## 3. 受影响接口
 
-| # | 接口 | 变更类型 | 说明 |
-|---|---|---|---|
-| 1 | <!-- 接口名 --> | 新增/修改/废弃 | <!-- 说明 --> |
+| # | 接口 | 变更类型 | 关联需求 | 说明 |
+|---|------|---------|---------|------|
+| 1 | <!-- 接口名 --> | 新增/修改/废弃 | REQ-NNN | <!-- 说明 --> |
 
 ## 4. 纯新增功能
-<!-- 不涉及现有代码修改的纯新增部分 -->
+
+| # | 功能 | 关联需求 | 涉及模块 | 说明 |
+|---|------|---------|---------|------|
+| 1 | <!-- 功能描述 --> | REQ-NNN | <!-- 模块名 --> | <!-- 说明 --> |
 
 ## 5. 改造范围
-<!-- 需要修改现有代码的部分 -->
+
+| # | 改造项 | 原逻辑 | 改造目标 | 关联需求 | 风险等级 |
+|---|--------|--------|---------|---------|---------|
+| 1 | <!-- 改造描述 --> | <!-- 原有行为 --> | <!-- 改造后行为 --> | REQ-NNN | 高/中/低 |

package/templates/artifacts/existing-system//346/224/271/351/200/240/345/275/261/345/223/215/350/214/203/345/233/264/350/257/204/344/274/260/346/250/241/347/211/210.md

@@ -1,18 +1,15 @@
 ---
 name: refactoring-impact-assessment
 type: acceptance_template
-asset_kind: acceptance_template
-routes:
-  - analysis
-primary_triggers:
-  - 影响范围
-  - 改造评估
-  - 改动范围
 scope: ['*']
 system_scope: ['existing-system']
-stages: ["详细设计"]
+stages: ["架构设计", "详细设计"]
 lifecycle_status: active
 owner_mechanism_id: mc-existing-system-artifact
+requires_context: ["file_impact", "reference_trace"]
+consumes: []
+companion_gates: ["gate-架构设计.yaml"]
+triggers: ['改造影响评估', '影响范围', 'refactoring impact']
 ---
 
 # 改造影响范围评估
@@ -39,5 +36,18 @@ owner_mechanism_id: mc-existing-system-artifact
 - 关键风险点：
   - <!-- 风险描述 -->
 
+### 2.5 隐式不变量
+> 老系统中的"不可见约定"：未文档化的不变量、生产事件 workaround、伙伴系统假设。
+| # | 不变量描述 | 影响模块 | 破坏风险 | 验证方式 |
+|---|-----------|---------|---------|---------|
+
 ## 3. 约束条件
 <!-- 影响评估作为详细设计的约束条件 -->
+
+### 3.5 分阶段验证计划（高风险项必须）
+| 风险项 | 验证阶段 | 验证方式 | 通过标准 | 回退策略 |
+|--------|---------|---------|---------|---------|
+| | 架构设计 | 依赖图分析 | 无未预期依赖 | 调整架构方案 |
+| | 详细设计 | 兼容性检查 | 向后兼容 | 修改接口设计 |
+| | 编码 | 新老逻辑比对 | 一致率 100% | 修复代码 |
+| | 联调 | 试运行熔断 | 错误率 <5% | 一键回滚 |

package/templates/artifacts/existing-system//346/225/260/346/215/256/350/241/200/347/274/230/345/233/276/346/250/241/347/211/210.md

@@ -1,18 +1,16 @@
 ---
 name: data-lineage-diagram
 type: acceptance_template
-asset_kind: acceptance_template
-routes:
-  - analysis
-primary_triggers:
-  - 数据血缘
-  - 血缘图
-  - 数据流
 scope: ['*']
 system_scope: ['existing-system']
-stages: ["架构设计", "详细设计"]
+stages: ["现有系统分析", "架构设计", "详细设计"]
 lifecycle_status: active
 owner_mechanism_id: mc-existing-system-artifact
+companion_rules: []
+companion_gates: []
+requires_context: []
+consumes: ["docs/existing-system/增量边界界定文档.md"]
+triggers: ['数据血缘', '血缘图', '数据流向', '调用链', 'data lineage']
 ---
 
 # 全链路数据血缘图
@@ -38,3 +36,12 @@ owner_mechanism_id: mc-existing-system-artifact
 | 字段 | 读/写 | 来源接口 | 来源服务 |
 |---|---|---|---|
 | <!-- 字段名 --> | R/W | <!-- 接口 --> | <!-- 服务 --> |
+
+## 5. 覆盖验证
+
+- [ ] 所有受影响接口已在 §2 中列出
+- [ ] 所有服务调用链已追踪到数据库读写
+- [ ] 数据库读写映射覆盖所有受影响表
+- Evidence: 接口覆盖率 = 已覆盖接口数 / 受影响接口总数
+
+> 接口覆盖率须为 100%。受影响接口列表来源：阶段 1 产出增量边界界定文档 §3 受影响接口。

package/templates/artifacts/existing-system//346/226/260/350/200/201/351/200/273/350/276/221/346/257/224/345/257/271/346/227/245/345/277/227/346/250/241/347/211/210.md

@@ -1,18 +1,13 @@
 ---
 name: new-old-logic-comparison-log
 type: acceptance_template
-asset_kind: acceptance_template
-routes:
-  - analysis
-primary_triggers:
-  - 比对日志
-  - 新老比对
-  - 逻辑对比
 scope: ['*']
 system_scope: ['existing-system']
-stages: ["架构设计", "详细设计"]
+stages: ["编码与单元测试"]
 lifecycle_status: active
 owner_mechanism_id: mc-existing-system-artifact
+requires_context: ["file_impact"]
+consumes: []
 ---
 
 # 新老逻辑比对日志
@@ -31,3 +26,9 @@ owner_mechanism_id: mc-existing-system-artifact
 - 一致次数：<!-- 数量 -->
 - 不一致次数：<!-- 数量 -->
 - 一致率：<!-- 百分比 -->
+
+## 4. 自动化比对要求
+- 比对方式：Feature Toggle on/off，相同输入调用同一接口，对比新老逻辑输出
+- 一致率要求：100%（对应 COMP-BEH-01）
+- 不一致项处理：标记为阻断，须修复后重新比对，不得放行
+- 比对范围：每个切片涉及的所有接口端点均须执行新老逻辑比对

package/templates/artifacts/existing-system//347/264/247/346/200/245/345/233/236/346/273/232/346/211/213/345/206/214/346/250/241/347/211/210.md

@@ -1,18 +1,16 @@
 ---
 name: emergency-rollback-manual
 type: acceptance_template
-asset_kind: acceptance_template
-routes:
-  - analysis
-primary_triggers:
-  - 回滚手册
-  - 紧急回滚
-  - rollback
 scope: ['*']
 system_scope: ['existing-system']
-stages: ["联调验证"]
+stages: ["详细设计", "联调验证"]
 lifecycle_status: active
 owner_mechanism_id: mc-existing-system-artifact
+companion_rules: ["试运行熔断规则.md:execute"]
+requires_context: []
+consumes:
+  - 隔离适配器方案模版
+  - 一键开关配置模版
 ---
 
 # 紧急回滚手册
@@ -25,18 +23,53 @@ owner_mechanism_id: mc-existing-system-artifact
 ## 2. 回滚步骤
 
 ### 2.1 触发一键开关
-<!-- 读取一键开关配置，切换到回退目标 -->
+| 步骤 | 操作 | 命令/操作描述 | 验证 | Evidence |
+|------|------|-------------|------|---------|
+| 1 | 读取一键开关配置 | <!-- 命令 --> | 配置已切换 | 截图/日志 |
+| 2 | 确认切换目标版本 | <!-- 命令 --> | 版本号正确 | 版本号输出 |
+| 3 | 刷新 CDN/缓存（如适用） | <!-- 命令 --> | 缓存已清除 | 缓存命中率 |
 
 ### 2.2 数据回滚
-<!-- 如果有数据变更，如何回滚数据 -->
+| 步骤 | 操作 | 命令/操作描述 | 验证 | Evidence |
+|------|------|-------------|------|---------|
+| 1 | 执行回滚 SQL | <!-- U{version}__xxx.sql --> | 数据已恢复 | 数据行数校验 |
+| 2 | 验证数据一致性 | <!-- 校验查询 --> | 一致性通过 | 校验结果 |
 
 ### 2.3 服务回滚
-<!-- 服务版本回退步骤 -->
+| 步骤 | 操作 | 命令/操作描述 | 验证 | Evidence |
+|------|------|-------------|------|---------|
+| 1 | 部署回滚版本 | <!-- 部署命令 --> | 健康检查通过 | 健康检查输出 |
+| 2 | 验证老逻辑功能 | <!-- 冒烟测试 --> | 核心功能正常 | 测试结果 |
+
+## 2.4 回滚总时限
+- 全部回滚操作须在 5 分钟内完成
+- 超时时限未完成 → 执行升级步骤
+
+## 2.5 升级与通知
+| 场景 | 处理方式 |
+|------|---------|
+| 回滚超时 | 停止所有变更操作，保留现场，人工介入 |
+| 数据回滚失败 | 停止回滚，执行数据备份后人工修复 |
+| 服务回滚失败 | 回退到更早的已知稳定版本 |
 
 ## 3. 回滚验证
-- [ ] 老逻辑功能正常
-- [ ] 数据一致性校验通过
-- [ ] 监控指标恢复正常
+
+- [ ] 老逻辑功能正常 — Evidence: 冒烟测试结果
+- [ ] 数据一致性校验通过 — Evidence: 数据校验 SQL 结果
+- [ ] 监控指标恢复正常 — Evidence: 监控截图（错误率/P99 延迟）
+- [ ] 回滚总耗时 ≤ 5 分钟 — Evidence: 时间戳记录（开始→完成）
 
 ## 4. 回滚后处理
-<!-- 回滚后的数据清理、日志记录、团队通知 -->
+- 数据清理（临时表/备份表处理策略）
+- 日志记录（回滚原因/触发指标/执行步骤/耗时）
+- 团队通知（相关团队同步回滚信息）
+
+## 5. 回滚审计日志
+
+| 时间 | 操作 | 执行者 | 结果 | 备注 |
+|------|------|--------|------|------|
+| | 触发回滚 | AI建议/人工决定 | | |
+| | 执行步骤 2.1 | | | |
+| | 执行步骤 2.2 | | | |
+| | 执行步骤 2.3 | | | |
+| | 验证完成 | | | |

package/templates/artifacts/existing-system//351/232/224/347/246/273/351/200/202/351/205/215/345/231/250/346/226/271/346/241/210/346/250/241/347/211/210.md

@@ -1,18 +1,16 @@
 ---
 name: isolation-adapter-plan
 type: acceptance_template
-asset_kind: acceptance_template
-routes:
-  - analysis
-primary_triggers:
-  - 隔离适配器
-  - 适配器
-  - 绞杀者模式
 scope: ['*']
 system_scope: ['existing-system']
-stages: ["架构设计"]
+stages: ["架构设计", "详细设计"]
 lifecycle_status: active
 owner_mechanism_id: mc-existing-system-artifact
+companion_rules: ["耦合检测规则.md:check"]
+companion_gates: ["gate-架构设计.yaml", "gate-详细设计.yaml"]
+requires_context: ["reference_trace"]
+consumes: []
+triggers: ['隔离适配器', '适配器方案', '新老共存', 'isolation adapter']
 ---
 
 # 隔离适配器方案
@@ -29,7 +27,13 @@ owner_mechanism_id: mc-existing-system-artifact
 <!-- 新老数据库表之间的数据同步方案 -->
 
 ### 2.3 Feature Toggle 隔离
-<!-- 功能维度的开关隔离方案 -->
+| 开关名称 | 默认状态 | 金丝雀比例 | 观察时间 | 自动回滚阈值 | 回退目标 |
+|---------|---------|-----------|---------|------------|---------|
+| <!-- 功能名 --> | off | 10% | 30 分钟 | 错误率 >5% | 老逻辑 |
+
+### 2.4 API 语义差异
+| 老接口 | 新接口 | 语义差异 | 兼容策略 | 风险评估 |
+|--------|--------|---------|---------|---------|
 
 ## 3. 隔离架构图
 <!-- 新老系统的隔离边界示意 -->

package/templates/artifacts/shared/ADR/346/250/241/347/211/210.md

@@ -1,20 +1,30 @@
 ---
 name: adr-template
 type: acceptance_template
-asset_kind: acceptance_template
-routes:
-  - artifact_generation
-primary_triggers:
-  - ADR
-  - 架构决策
-  - 决策记录
 stages: ["架构设计"]
 lifecycle_status: active
 owner_mechanism_id: mc-generic-artifact
+authority: supporting
+priority: P2
+version: 1.2.0
+last_reviewed: '2026-06-04'
+scope:
+  - backend
+  - frontend
+products:
+  - '*'
+id: ka-artifact_template-adr
+companion_gates: ["gate-架构设计.yaml"]
+companion_rules: ["第一性原理推理规则.md:review"]
+requires_context: []
+consumes: []
+triggers: ['ADR', '架构决策', '技术选型', '决策记录']
 ---
 
 # ADR（架构决策记录）
 
+> **根本目标引用**：本产物的 `fundamental_need` 见需求分析文档 §1.3。若未声明，引用审查规则 FP-01。
+
 ## 决策标题
 <!-- 简短描述本次架构决策 -->
 

package/templates/artifacts/shared/API/346/216/245/345/217/243/350/247/204/346/240/274/346/226/207/346/241/243/346/250/241/347/211/210.md

@@ -1,7 +1,6 @@
 ---
 name: api-specification
 id: ka-artifact_template-api-specification
-asset_kind: acceptance_template
 lifecycle_status: active
 authority: supporting
 scope:
@@ -9,20 +8,9 @@ scope:
   - frontend
 products:
   - '*'
-routes:
-  - artifact_generation
-primary_triggers:
-  - API接口规格文档
-  - 接口规格
-  - API文档
-  - 接口设计
-  - API设计
-  - 接口文档
-  - 接口定义
 priority: P1
-specificity: 4
-version: 1.1.0
-last_reviewed: '2026-06-01'
+version: 1.2.0
+last_reviewed: '2026-06-04'
 owner_mechanism_id: mc-design-artifact-pack
 consumes:
   - docs/architecture/00-架构决策记录.md
@@ -35,54 +23,14 @@ required_evidence:
   - endpoint_field_tables
   - openapi_operation_coverage
 type: acceptance_template
-artifact_schema:
-  kind: api_spec
-  required_sections:
-    - 基本信息
-    - 请求 Header 字段
-    - 请求 Path
-    - 请求体字段
-    - 响应体字段
-    - 错误与副作用
-    - 验收场景
-    - 枚举值定义
-    - 页面交互映射
-  required_tables:
-    - 基本信息表
-    - 请求Header字段表
-    - 请求Path/Query字段表
-    - 请求体字段表
-    - 响应体字段表
-    - 错误与副作用表
-    - 验收场景表
-    - 枚举值定义表
-    - 页面交互映射表
-  required_fields:
-    基本信息表:
-      - endpoint_id
-      - 用途
-      - 调用端
-      - 权限
-      - 幂等
-    请求体字段表:
-      - 字段路径
-      - 类型
-      - 必填
-      - 枚举
-      - 数据映射
-      - 说明
-    响应体字段表:
-      - 字段路径
-      - 类型
-      - 必有
-      - 可空
-      - 数据来源
-      - 说明
-  required_artifacts:
-    - OpenAPI 文件
-  forbidden_gaps:
-    - endpoint缺请求或响应字段表
-stages: ["架构设计", "详细设计"]
+stages: ["详细设计"]
+requires_context: [file_impact, reference_trace]
+companion_gates:
+  - gate-详细设计.yaml
+companion_rules:
+  - 接口契约审查规则.md:review
+  - 一致性校验规则.md:check
+triggers: ['API', '接口规格', 'OpenAPI', '接口设计', 'REST', 'endpoint']
 ---
 
 # API 接口规格文档
@@ -91,52 +39,52 @@ OpenAPI 权威路径: `docs/api/openapi.yaml`
 
 ## Endpoint: `METHOD /api/v1/resource`
 
-### 基本信息
+### 基本信息 [Always — 每个 endpoint 必填]
 
 | endpoint_id | 用途 | 调用端 | 权限 | 幂等 | 限流 | 副作用 |
 |-------------|------|--------|------|------|------|--------|
 
-### 请求 Header 字段
+### 请求 Header 字段 [Ask first — 有认证/自定义 Header 时必填]
 
 | 字段路径 | 类型 | 必填 | 格式/约束 | 数据映射 | 说明 | 示例 |
 |----------|------|------|-----------|----------|------|------|
 
-### 请求 Path / Query 字段
+### 请求 Path / Query 字段 [Ask first — 有路径/查询参数时必填]
 
 | 字段路径 | 类型 | 必填 | 默认值 | 格式/约束 | 说明 | 示例 |
 |----------|------|------|--------|-----------|------|------|
 
-### 请求体字段
+### 请求体字段 [Ask first — 有请求体时必填]
 
 | 字段路径 | 类型 | 必填 | 可空 | 枚举/格式/校验 | 数据映射 | 说明 | 示例 |
 |----------|------|------|------|----------------|----------|------|------|
 
-### 响应体字段
+### 响应体字段 [Always — 每个 endpoint 必填]
 
 | 字段路径 | 类型 | 必有 | 可空 | 枚举/格式 | 数据来源 | 说明 | 示例 |
 |----------|------|------|------|-----------|----------|------|------|
 
-### 错误与副作用
+### 错误与副作用 [Always — 每个 endpoint 必填]
 
 | 业务码 | HTTP 状态 | 触发条件 | 用户提示 | 可重试 | 状态/数据副作用 |
 |--------|-----------|----------|----------|--------|-----------------|
 
-### 验收场景
+### 验收场景 [Always — 每个 endpoint 必填]
 
 | 场景 | 输入 | 预期响应 | 数据/状态变化 | 验证证据 |
 |------|------|----------|---------------|----------|
 
-### 枚举值定义
+### 枚举值定义 [Ask first — 有枚举字段时必填]
 
 | 枚举名 | 值 | 含义 |
 |--------|------|------|
 
-### 页面交互映射
+### 页面交互映射 [Ask first — 前端直接调用的接口必填]
 
 | 页面操作 | 触发接口 | 加载状态 | 成功行为 | 失败行为 |
 |---------|---------|---------|---------|---------|
 
-### 接口规范检查
+### 接口规范检查 [Always — 每个 endpoint 必填]
 
 - [ ] 是否定义了接口版本号和演进策略（如 /api/v1/）
 - [ ] 是否有幂等设计（写接口需标注幂等键或唯一约束）
@@ -144,3 +92,14 @@ OpenAPI 权威路径: `docs/api/openapi.yaml`
 - [ ] 是否有分页参数上限限制（防止恶意大翻页）
 - [ ] 是否有接口限流策略（QPS/并发上限）
 - [ ] 批量操作是否有数量上限（≤ 500 条）
+
+### AI Agent 格式校验 [Always — 每个 endpoint 必填]
+
+- [ ] 每个 endpoint_id 全局唯一且遵循命名规范（{资源}-{动作}）
+- [ ] 所有 数据映射 字段已精确到 表名.字段名 格式（禁止仅写表名）
+- [ ] 所有 类型 字段使用标准类型（string/integer/number/boolean/array/object/date/datetime/enum）
+- [ ] 所有 格式/约束 字段使用标准约束格式（min:0,max:100 或 pattern:regex）
+- [ ] 错误映射表中每个 HTTP 状态码至少对应一个业务码
+- [ ] 验收场景表中每行必须包含 验证证据（不得为空）
+- [ ] 枚举值定义覆盖了所有字段中出现的枚举类型
+- [ ] 页面交互映射覆盖了所有涉及前端调用的接口