From 3a104fcce4f9be4dff10672ba611691db241b7d2 Mon Sep 17 00:00:00 2001 From: iomgaa Date: Thu, 6 Aug 2026 03:56:41 -0400 Subject: [PATCH] docs: record human approval of the issue #7 design All three open decisions were settled as proposed: a dedicated SourceNotConfiguredError so a misconfigured source reaches the dead letter queue instead of retrying forever, a 5 second retry_after_s so a backlog does not stampede a backend that is already down, and public export so callers can alarm on assembly defects specifically. --- .../2026-08-06-governance-backend-error-design.md | 14 ++++++++------ research-wiki/designs/governance-backend-error.md | 2 +- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/research-wiki/designs/2026-08-06-governance-backend-error-design.md b/research-wiki/designs/2026-08-06-governance-backend-error-design.md index 46c6d98..7723631 100644 --- a/research-wiki/designs/2026-08-06-governance-backend-error-design.md +++ b/research-wiki/designs/2026-08-06-governance-backend-error-design.md @@ -2,7 +2,7 @@ - **日期**: 2026-08-06 - **来源**: Gitea Issue #7(下游 CHSAnalyzer3 按异常类型分流失败,基于 1.0.1 源码核查) -- **状态**: 待人类审批 +- **状态**: **已批准(2026-08-06)**,待 `writing-plans` - **触发档位**: 强制(变更 `errors.py` 公共错误类型树 = 库对下游的承诺) - **方案范围**: 人类已选定方向 A′ 并明确要求单一方案,故本文不列平行备选,仅在 §4 记录被否决路线及否决理由 @@ -154,11 +154,13 @@ Issue 建议取 0。**否决**:下游 `schedule_retry(after_s=0)` 会立刻重 (编号用 Q 前缀,避免与 `ARCHITECTURE.md` 的架构决策 D1–D14 混淆) -| # | 决策 | 本文的选择 | 备选 | +**三点均已由人类拍板(2026-08-06),全部采纳本文的选择:** + +| # | 决策 | 裁定 | 被否决的备选及理由 | |---|---|---|---| -| Q1 | "未知源"归到哪 | 拆为 `SourceNotConfiguredError`,**不**在 `GatewayUnavailableError` 之下(§3.4) | ① 沿用 `GovernanceBackendError`——需接受"配置写错永不进死信";② 复用 `RequestRejectedError`——留在四分类内、治理行为(不重试不换源快速失败)恰好正确,但语义错位会引下游去修请求 | -| Q2 | `retry_after_s` 取值 | 常量 `5.0`(§3.2) | 可改为配置项或其他常量值;不建议取 0 | -| Q3 | 新类是否公共导出 | 是(进 `__init__.py`) | 若只作内部诊断可不导出 | +| Q1 | "未知源"归到哪 | ✅ **拆为 `SourceNotConfiguredError`**,不在 `GatewayUnavailableError` 之下(§3.4) | ① 沿用 `GovernanceBackendError`——配置写错的任务将无限重投、永不进死信、无人发现;② 复用 `RequestRejectedError`——治理行为与选定方案**完全等价**,但名称误导:下游会去查 prompt 而非配置文件 | +| Q2 | `retry_after_s` 取值 | ✅ **常量 `5.0`**(§3.2) | 取 0 会让积压任务零延迟同时冲击已挂掉的后端,把一次故障放大成风暴 | +| Q3 | 新类是否公共导出 | ✅ **导出**(进 `__init__.py`) | 不导出则下游无法给"配置写错"单独接告警,而导出无成本 | ## 10. 审批记录 @@ -166,7 +168,7 @@ Issue 建议取 0。**否决**:下游 `schedule_retry(after_s=0)` 会立刻重 |---|---| | Claude 自审 | 已完成(全部结论对应本会话内 grep/read 输出;§3.5 的 `self.args` 保全机制经 conda 环境实跑验证) | | Codex 独立审 | 已完成(2026-08-06),4 条意见逐条核验见下 | -| 人类审批 | **待执行**(强制档:变更 `errors.py` 公共错误类型树) | +| 人类审批 | ✅ **已批准(2026-08-06)**。方向 A′ 于设计前即由人类选定;Q1–Q3 三个决策点逐条拍板,全部采纳本文选择(见 §9)。可进入 `writing-plans` | ### 10.1 Codex 意见的核验结果 diff --git a/research-wiki/designs/governance-backend-error.md b/research-wiki/designs/governance-backend-error.md index 5970891..dd69201 100644 --- a/research-wiki/designs/governance-backend-error.md +++ b/research-wiki/designs/governance-backend-error.md @@ -7,7 +7,7 @@ date: 2026-08-06 # 治理后端故障归位为 scope 级不可用(Issue #7) -全文见 `2026-08-06-governance-backend-error-design.md`。来源: Gitea Issue #7(下游 CHSAnalyzer3 按异常类型分流失败)。**状态: 待人类审批。** +全文见 `2026-08-06-governance-backend-error-design.md`。来源: Gitea Issue #7(下游 CHSAnalyzer3 按异常类型分流失败)。**状态: 已批准(2026-08-06,人类逐条拍板 Q1/Q2/Q3),待 `writing-plans`。** 问题: 限流/熔断状态后端故障时库 fail-closed,一个请求都发不出去——语义上就是 scope 级不可用,但 `GovernanceBackendError` 是 `PolyGatewayError` 的**直接子类**,只写 `except GatewayUnavailableError` 的调用方接不住,于是 Redis 抖一下,积压任务一批批消耗业务失败预算进死信,而那是运维重启就好的故障。