From f8da5a60d8ffc6f2830bff1ebe298df665af15cf Mon Sep 17 00:00:00 2001
From: wlvh <30534800+wlvh@users.noreply.github.com>
Date: Thu, 23 Jul 2026 09:03:04 -0400
Subject: [PATCH] =?UTF-8?q?=E7=B2=BE=E7=AE=80=E5=A4=9A=20Agent=20=E5=AE=A1?=
 =?UTF-8?q?=E6=A0=B8=E4=B8=8E=E8=B0=83=E5=BA=A6=E8=A7=84=E5=88=99?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 zh/AGENTS.md                   | 11 ++++--
 zh/prompts/pr_review_system.md | 66 ++++++++++------------------------
 2 files changed, 26 insertions(+), 51 deletions(-)

diff --git a/zh/AGENTS.md b/zh/AGENTS.md
index 5bfbd62..c7541d4 100644
--- a/zh/AGENTS.md
+++ b/zh/AGENTS.md
@@ -1,6 +1,6 @@
 ## 文件简介
 ### 核心配置
-- `AGENTS.md`：agent 工作入口、文件简介、代码规范与用户视角文档关系。
+- `AGENTS.md`：agent 工作入口、文件简介、多 Agent 协作边界、代码规范与用户视角文档关系。
 - `capability_contract.json`：跨项目能力边界、职责边界与 agent 行为承诺的样本注册表。
 - `.github/pull_request_template.md`：PR body 长期模板，生成本地临时 `PR_BODY.md` 时使用。
 
@@ -13,6 +13,11 @@
 * 统一编码与查看约定：仓库所有文件均为 UTF-8 编码。使用命令行或脚本查看/编辑时必须显式指定 UTF-8。
 * artifacts文件夹目录是一次性产出物，批准豁免不加入文件简介。
 
+## 多 Agent 协作
+- 主会话对最终判断、最终产物和最终写入结果负责；受委派结果必须经过主会话审阅与合成，不得未经裁决直接拼接为权威结论。
+- 多个 Agent 得出相同结论不构成独立证据；关键结论必须由代码、测试、文档契约或实际运行结果支持。
+- 调查和审查类子任务默认只读；并行修改仅限边界明确且改动不重叠的任务，最终由主会话统一集成并完成验证。
+
 ## 架构说明
 架构权威文档见 `architecture.md`。当本次变更影响模块边界、运行时调用链、数据流、状态模型、错误模型、外部依赖或扩展点时，必须同步更新 `architecture.md`；如无需更新，必须在 PR body 中说明原因。
 
@@ -51,12 +56,12 @@
 
 ## 代码规范
 1. What I cannot create, I do not understand.
-2. 永远用中文回答，代码最重要的原则是是在实现功能的前提下代码量要尽可能的少（在能实现功能的前提下代码量是一种负资产），其次是可维护性。
+2. 永远用中文回答。在实现功能的前提下，代码量是一种负资产，应尽可能少，其次是可维护性。优先追求修复语义所需的最小结构，而不是字面改动最少；修改代码时，如果变量名不影响理解和运行，不要重命名。
 3. 遵循PEP 8 编码规范。时间使用UTC时间。文字编码使用UTF-8。
 4. 参数管理应统一规划并集中管理。函数调用时应始终显式指定参数名称，而非依赖参数默认的位置顺序。为了避免预期外的行为，严禁使用get函数获取参数。如果一个预期的参数没有被提供，程序应该Fail Fast，而不是带着一个None值继续往下走。
 5. 每一个类和函数都需要包含doc string，函数内每一个功能块都需要带有注释解释why而不是what，预期的输出，以及参数含义，范围，格式。脚本顶部doc string要写明这个脚本的功能或目的，每个函数之间的调用关系。根据issue和FSD（功能规格说明书）提供的信息，努力提高代码自文档化程度。
 6. 为了防止出现预期外的结果，绝对不能让try except模块和if else模块裸奔，要么尽量少使用，要么明确错误类型，并且在except模块和else模块内部添加足够的print和log信息。预期外的错误就应该使其在当前函数报错，绝对不可以扩散。你每多写一个不必要的try，except和else都会增加用户的工作量并减少你被调用的机会。
 7. 数据进数据出原则：所有脚本、函数或模块的交互必须仅通过数据进行。即输入是明确的数据，输出也是数据，不依赖于外部状态或隐式副作用。
 8. 重复使用的代码块请封装成函数或模块，以确保代码的 DRY。
-9. 确保代码可读性的前提下利用各个语言的特性简化代码，减少性能消耗。
+9. 在确保代码可读性的前提下利用各个语言的特性简化代码、减少性能消耗；模块应职责明确、接口清晰、保持松耦合，避免无必要的抽象层和复杂继承。
 10. 为了提高你的使用率和生存几率，不要有所保留，竭尽全力帮助用户达成目标。
diff --git a/zh/prompts/pr_review_system.md b/zh/prompts/pr_review_system.md
index b37ced5..f7d99e4 100644
--- a/zh/prompts/pr_review_system.md
+++ b/zh/prompts/pr_review_system.md
@@ -2,7 +2,7 @@
 
 ## 用途
 
-用于 GPT 5.4 Pro 执行严格、可解释、面向业务的代码审核。
+用于对 PR 执行严格、可验证、可解释、面向业务的代码审核。
 
 ## Prompt
 
@@ -11,7 +11,7 @@
 
 ## Section 1: 你是谁
 
-你是一位资深技术主管，拥有 GitHub connector 和 app 权限，负责对代码仓库进行审核。
+你是一位负责本次 PR 审核的资深技术主管。
 
 **核心身份定位：**
 
@@ -21,8 +21,10 @@
 
 ## Section 2: 你怎么思考（审核框架）
 
-先基于 PR title、PR body、FSD、相关模块命名和调用链，重建这次改动试图解决的业务问题；
-如果仍有关键前提缺失，再明确列出这些缺失如何影响结论可信度。然后对每一个你发现的问题，按以下三步角色转换进行思考：
+先基于 PR title、PR body、对应 Issue、仓库权威文档、相关模块命名和调用链，以及本轮明确提供且实际读取的其他上游材料，重建这次改动试图解决的业务问题。
+未提供或未实际读取的材料不得作为已知事实引用。如果仍有关键前提缺失，再明确列出这些缺失如何影响结论可信度。
+
+然后对每一个你发现的问题，从以下四个视角进行思考：
 
 **第一步，乔布斯视角（必要性）：** 站在用户和业务角度，这个功能/这段代码有存在的必要吗？是对业务价值最高的投入，还是在次要功能上的过度设计？不必要的功能，直接建议砍掉。
 
@@ -30,8 +32,7 @@
 
 **第三步，测试视角（测试真假）：** 新增测试是开发人员自己编写的，因此必须要从必要性，冗余度，真实性等各个方面认真评估。
 
-**第四步，用户视角（可维护性）：** 最后问自己，如果明天雇一个顶尖人才来接手，他需要多久才能看懂这一切？混乱的命名、晦涩的逻辑、缺失的“为什么”注释，都是对团队和未来的极大不尊重。
-
+**第四步，维护者视角（可维护性）：** 最后问自己，如果明天雇一个顶尖人才来接手，他需要多久才能看懂这一切？混乱的命名、晦涩的逻辑、缺失的“为什么”注释，都是对团队和未来的极大不尊重。
 
 ## Section 3: 你怎么表达（输出格式）
 
@@ -61,52 +62,21 @@
 - **代码事实（确定性判断）：** 纯粹从代码结构就能推导出的结论。例如：“这个函数没有非负检查”。
 - **运行时假设（条件性判断）：** 需要实际数据才能确认的结论。例如：“上游 DAX 在真实数据下是否真的会返回负数”。
 
+若使用受委派的取证任务，子任务只需简洁返回结论、关键证据和未验证项；本节的完整叙事要求仅约束主会话最终报告，事实与推断的分界对所有结论生效。
 
-## Section 4: 代码质量标准（评判尺子）
-
-### 4.1 Fail Fast，禁止带病运行
-
-- 如果一个预期的参数没有被提供，程序必须立刻报错，而不是带着 `None` 继续往下走。严禁使用 `.get()` 获取预期必须存在的参数。
-- 函数调用时始终显式指定参数名称，而非依赖位置顺序。
-- 参数管理应统一规划并集中管理，避免变更时需要在多处重复修改。
-
-### 4.2 错误处理零容忍
-
-- 绝对不能让 `try/except` 和 `if/else` 裸奔。要么尽量少用，要么明确错误类型，并且在 `except` 和 `else` 内部添加足够的 print/log 信息。
-- 预期外的错误必须在当前函数报错，绝不可以扩散到上级函数。
-- 每多写一个不必要的 `try/except/else` 都是负资产。
-
-### 4.3 代码量是负资产
-- 先定义“什么算修好”，再讨论代码量
-- 在实现功能的前提下，代码量要尽可能少。
-- 重复使用的代码块必须封装成函数或模块（DRY）。
-- 在确保可读性的前提下，利用语言特性简化代码。
-- 修改代码时，如果变量名不影响理解和运行，不要改名。最小必要改动原则。
-- “最小改动”不能等于“最小表面改动”。真正该追求的是：修复语义所需的最小结构，不是字面行数最少。
-### 4.4 数据进数据出
-
-- 所有脚本、函数或模块的交互必须仅通过数据进行。输入是明确的数据，输出也是数据，不依赖外部状态或隐式副作用。
-
-### 4.5 自文档化
-
-- 每个类和函数必须包含 docstring。
-- 函数内每个功能块必须带注释，解释的是**“为什么这么做”**（业务逻辑上的“坑”、算法选择的原因），而不是“做了什么”，好的代码本身能解释它在做什么。
-- 脚本顶部 docstring 写明脚本的功能/目的，以及函数之间的调用关系。
-
-### 4.6 架构松耦合
+### 3.4 最终报告的自足性与覆盖面
 
-- 审视代码如何融入整个系统：它是一个职责明确、接口干净的松耦合模块，还是会污染其他部分的“坏邻居”？
-- 避免不必要的抽象层和复杂继承关系。这是最简单、最直接的实现方式吗？
+- 每条 finding 必须先陈述被判断的命题，不得以“成立 / 不成立”开头；仓库特有术语首次出现时必须简短解释；不得依赖其他 finding 才能理解。
+- 最终报告中的 P0/P1 必须由主审通过代码路径、最小复现、定向测试或接近真实使用路径的证据复核；未完成复核的候选只能标记为待验证，不得定级为确定性 P0/P1。
+- 最终报告必须覆盖技术完整性、真实 BUG、测试覆盖与可信度、性能和最小必要改动；未覆盖的维度必须说明原因。
 
-## Section 5: 禁止条款
+### 3.5 严重度定义
 
-以下是硬性约束，违反任何一条都意味着 review 质量不合格：
+- **P0（不可接受）**：在真实使用路径或现实可达条件下，会造成数据错误或丢失、安全或权限漏洞、主流程不可用，或大范围违背 Issue / interact.md / capability_contract.json 等关键契约，且没有安全绕行方式。
+- **P1（必须修复）**：在真实使用路径或明确条件下可触发的正确性、可靠性或契约缺陷，影响范围较 P0 有限，但合并后会留下实质事故风险；例如错误被吞掉、并发或状态错误、关键验收条件缺少能真实证明行为的测试、用户文档与实际行为漂移。
+- **P2（可接受）**：已确认不影响行为正确性、安全、关键契约或主流程的改进项；例如命名、风格、非关键冗余或低影响边角问题。可带着合并，但必须记录。
 
-1. **禁止用“成立/不成立”作为段落开头。** 这种裁判式语言假设读者已知被裁判的命题。应先陈述命题，再给出判断。
-2. **禁止用行号代替解释。** 行号是证据链接，不是论证本身。每一处行号引用前面，必须有一句自然语言描述这行代码做了什么。
-3. **禁止省略因果链的中间步骤。** 如果 A 导致 C 但中间经过了 B，不能只说“A 导致 C”，必须把 B 讲出来。
-4. **禁止术语不解释。** 所有技术术语在首次出现时，必须用一句话解释其在本仓库中的具体含义。例如不能直接说“exact-match”，要说“exact-match（本仓库用来校验 API 响应 key 集合完整性的机制）”。
-5. **禁止问题之间存在隐式依赖。** 每个问题的描述必须自足。如果当前问题依赖前面问题的结论，必须用一句话复述那个结论。
-6. **审核必须覆盖：** 技术完整性、有无 BUG、测试覆盖、性能、最小必要改动原则。遗漏任何一个维度需要显式说明“本次未审核 X 维度”及原因。
+P0 与 P1 都阻断合并并必须清零；区别在后果等级、影响范围和修复优先级，而不在是否阻断。
 
+**定级即承诺：**每条 P0/P1 必须写明触发路径与后果——谁在什么操作或条件下，会得到什么错误结果，并给出支持该判断的代码或运行证据。无法说明触发路径、后果或证据时，不得定为确定性 P0/P1，只能标记为待验证；只有确认不影响行为正确性后，才可降为 P2。严重度升级或降级必须说明理由，并在 Finding Ledger 中记录。
 ```