From ada67eb9c0ae3a98189cb61835fee05627bc0569 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8D=8E=E4=BD=97?= <huatuo@gentronhealth.com>
Date: Wed, 10 Jun 2026 09:12:00 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E9=93=81=E5=BE=8B19-?=
 =?UTF-8?q?22=EF=BC=88Bug=20#698=20=E6=95=99=E8=AE=AD=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 铁律19: 编译错误不区分来源
- 铁律20: 数据来源必须验证
- 铁律21: 外部配置值必须实测验证
- 铁律22: 端到端验证必须有实际输出证据
---
 AGENTS.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index ee3d53da1..1dec328d9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -106,6 +106,32 @@
 - 每次修改后必须 `mvn clean compile -DskipTests` 验证
 - **违规判定**: 因修改导致原有代码编译失败或运行报错，视为违反铁律18，必须立即回滚修复
 
+
+**铁律19: 编译错误不区分来源（Bug #698 教训）**
+- `mvn compile`、`vite build`、`vue-tsc` 等构建命令报错 = 不过关，**不管是自己引入的还是历史遗留的**
+- 禁止说"这是预存问题""不是我改的""原有bug"——构建通不过就不能宣称完成
+- 正确做法：定位错误 → 修复 → 重新构建确认通过 → 然后才能继续
+- **违规判定**: 构建命令有 ERROR 但未修复就报告"编译通过"，视为违反铁律
+
+**铁律20: 数据来源必须验证（Bug #698 教训）**
+- 涉及数据查询/提取时，必须先确认数据实际存储位置，不能假设
+- 案例：从 `raw_steps_html` 提取 fileID，而不是从 `steps`（纯文本，已被 strip）
+- 修复前必须：打印/检查原始数据结构 → 确认字段存在 → 再写提取逻辑
+- 禁止：凭代码推断数据位置、假设"应该在这里"
+
+**铁律21: 外部配置值必须实测验证（Bug #698 教训）**
+- 使用外部服务（API、模型、数据库）的配置值，必须实际调用验证，不能仅凭记忆或推测
+- 案例：模型名 `mino-v2.5` 应为 `mimo-v2.5`，拼写错误导致 400
+- 配置变更后必须：发起一次真实请求 → 确认返回 200 → 再宣称配置正确
+- 禁止：改完配置不测试、假设"应该能用"
+
+**铁律22: 端到端验证必须有实际输出证据（Bug #698 教训）**
+- 声称功能生效前，必须有实际的端到端输出证据
+- 不能仅凭代码路径推断"应该走了 vision"——必须看到实际返回内容
+- 验证方式：运行命令 → 检查输出中包含预期关键词（如 vision 分析结果、图片识别文字）
+- 禁止：只检查代码路径可达就算"验证通过"
+
+
 ### 🟡 P1 铁律 — 强烈建议
 
 **铁律9: 先分解再行动**