chore(task): archive 05-12-glm-429-cooldown-thinking-fallback

Author: mudssky

.trellis/tasks/archive/2026-05/05-12-glm-429-cooldown-thinking-fallback/check.jsonl

@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}

.trellis/tasks/archive/2026-05/05-12-glm-429-cooldown-thinking-fallback/implement.jsonl

@@ -0,0 +1 @@
+{"_example": "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. Put spec/research files only — no code paths. Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. Delete this line once real entries are added."}

.trellis/tasks/archive/2026-05/05-12-glm-429-cooldown-thinking-fallback/prd.md

@@ -0,0 +1,161 @@
+# brainstorm: 优化 GLM 429 冷却与 fallback thinking 处理
+
+## Goal
+
+优化 Claude Code 通过 LiteLLM 使用 GLM Coding Plan 时的 429 处理：GLM 的额度窗口是 5 小时，而当前固定 1 小时 `cooldown_time` 会导致窗口内反复探测；同时把现有单用途 callback 演进为可组合的 LiteLLM callback adapter 框架，让 DeepSeek thinking sanitizer、GLM cooldown 等逻辑可以独立配置、独立测试、独立扩展。
+
+## What I already know
+
+* 用户提供的 GLM 429 示例会在错误体中返回中文重置时间：`已达到 5 小时的使用上限。您的限额将在 2026-05-08 05:32:56 重置。`
+* 用户期望按错误体中的恢复时间再往后延 1 分钟恢复，避免中途多次多余请求。
+* 当前 `ai/gateway/litellm/litellm.local.yaml` 中 `cc-glmplan-opus` / `cc-glmplan-haiku` 都配置 `cooldown_time: 3600`。
+* `ai/gateway/litellm/newapi.yaml` 中对应配置同样是 `cooldown_time: 3600`，若改配置应同步。
+* DeepSeek sanitizer 已迁移为 `callbacks.gateway_callback.proxy_handler_instance` 下的 adapter，旧单用途 callback 入口已删除。
+* sanitizer 不是只在 fallback 时调用；LiteLLM 会按 callback 生命周期调用 hook，当前代码再用 call_type 与 DeepSeek deployment/api_base 过滤实际清理范围。
+* GLM 正常路径不会被 sanitizer 清理；GLM fallback 到 DeepSeek 或直接调用 `claude-code-deepseek-*` 时会被清理。
+* 当前 fallback thinking 报错更像是 DeepSeek 收到必须回传的 signed/redacted thinking 丢失或请求体未被正确清理导致；现有 spec 已要求保留带 `signature` / `data` 的 thinking 块。
+* 用户希望基于 callback 全生命周期特性开发一个可兼容多种配置的框架，GLM cooldown 适配逻辑应能单独抽出。
+
+## Assumptions (temporary)
+
+* GLM 429 reset 时间使用 Asia/Shanghai 语义，错误体没有显式时区。
+* “恢复时间 + 1 分钟”只针对智谱 GLM Coding Plan 5 小时额度 429，不应影响其它供应商或普通 429。
+* 当前 LiteLLM YAML 没有直接支持“解析上游错误 body 后动态设置 deployment cooldown 到指定时间”的配置项。
+
+## Open Questions
+
+* 无。
+
+## Requirements (evolving)
+
+* 减少 GLM 5 小时额度窗口内的重复请求探测。
+* 保持 `cc-glmplan-opus` fallback 到 `claude-code-deepseek-v4-pro`，`cc-glmplan-haiku` fallback 到 `claude-code-deepseek-v4-flash`。
+* 保持 DeepSeek sanitizer 当前“按 DeepSeek Anthropic deployment 触发”的边界，不改成只看 fallback。
+* 文档说明 callback 的生命周期含义：不是 fallback-only，fallback 只是其中一个会命中 DeepSeek 清理条件的场景。
+* 新增 callback adapter 框架：LiteLLM 仍只挂载一个 `CustomLogger` 入口，该入口把各生命周期 hook 分发给多个 adapter。
+* DeepSeek thinking sanitizer 作为一个 adapter 接入框架，保持现有行为不回退。
+* GLM cooldown 作为独立 adapter 接入框架，负责识别 GLM 429 reset 时间并提供恢复时间策略。
+* adapter 必须可以按配置启用/禁用，并能表达适用范围，例如 model group、deployment、provider、api_base 或错误码。
+* 如果修改配置，`litellm.local.yaml` 与 `newapi.yaml` 需要保持预期一致。
+
+## Acceptance Criteria (evolving)
+
+* [x] GLM Claude Code 入口不再使用 1 小时冷却导致 5 小时窗口内反复探测。
+* [x] 429 示例中的 reset 时间策略被记录或实现为“reset + 60 秒”。
+* [x] LiteLLM 配置只需挂载统一 callback hub，具体行为由 adapter 注册/配置决定。
+* [x] DeepSeek thinking sanitizer adapter 与 GLM cooldown adapter 可以单独测试。
+* [x] DeepSeek fallback 的 thinking sanitizer 行为不回退：当前 top-level thinking/effort 保留，历史不兼容 thinking 清理，signed/redacted opaque thinking 保留。
+* [x] 文档解释 callback 不是只在 fallback 时调用，并说明当前代码的过滤条件。
+* [x] YAML 可被解析，相关 sanitizer 回归测试通过。
+
+## Definition of Done
+
+* Tests added/updated where behavior changes.
+* `pnpm qa` 通过，或记录无法运行的原因。
+* 若改动涉及 pwsh 相关内容，按项目规则额外执行对应 pwsh 测试。
+* Docs/spec updated if behavior changes.
+* Rollout/rollback considered if risky.
+
+## Research References
+
+* [`research/litellm-callback-router.md`](research/litellm-callback-router.md) — LiteLLM callback 生命周期与 Router 固定冷却能力调研。
+
+## Research Notes
+
+### Feasible approaches
+
+**Approach A: 固定 5 小时冷却**
+
+* How it works: 把两个 GLM Claude Code 入口的 `cooldown_time` 从 3600 改成 18000，并同步 `litellm.md` 与 Trellis spec。
+* Pros: 改动小，能直接覆盖 5 小时窗口，减少中途多余请求。
+* Cons: 不能利用错误体里的精确 reset 时间；如果 reset 时间与固定窗口不一致，仍可能早探测或晚恢复。
+
+**Approach B: 动态解析 GLM reset 时间**
+
+* How it works: 捕获 GLM 429 错误体，解析 reset 时间，按 reset + 60 秒让后续请求避让 GLM，期间直接使用 DeepSeek fallback。
+* Pros: 最贴合真实上游返回，恢复更精准。
+* Cons: LiteLLM 文档未暴露直接 YAML 配置，可能需要研究/使用内部 Router cooldown API 或本地缓存拦截，复杂度更高。
+
+**Approach C: Callback hub + 独立 adapters（推荐）**
+
+* How it works: 新增统一 callback hub 实现 LiteLLM `CustomLogger`，把生命周期 hook 分发给多个 adapter；现有 DeepSeek sanitizer 迁移为 request-mutation adapter，GLM cooldown 新增为 error/cooldown adapter。
+* Pros: 结构清晰，后续可继续加入 provider-specific 兼容逻辑；GLM cooldown 不污染 DeepSeek sanitizer；每个 adapter 可以独立测试和配置。
+* Cons: 初次改动比单纯改 YAML 大，需要设计 adapter 协议、配置读取、错误隔离与日志规范。
+
+### Callback framework shape
+
+**Recommended shape: hub + adapter registry**
+
+* LiteLLM YAML 中挂载一个统一入口，例如 `callbacks.gateway_callback.proxy_handler_instance`。
+* `GatewayCallbackHub(CustomLogger)` 实现 LiteLLM 常用 hook，并按顺序调用启用的 adapter。
+* adapter 可以只实现自己关心的 hook；未实现的 hook 自动跳过。
+* 单个 adapter 异常不能拖垮其它 adapter；框架记录安全日志，并按 adapter 标记决定是否 fail-open。
+* 默认 adapter 列表由本地 Python 注册，配置负责启用/禁用和传入范围参数，避免在 YAML 中写 Python import 细节。
+
+### Adapter lifecycle model
+
+* `GatewayCallbackHub` 实现 LiteLLM 的生命周期 hook，并把同一个 hook 分发给所有启用且实现了该 hook 的 adapter。
+* 所有 adapter 共享一个轻量 `GatewayCallbackAdapter` 协议/抽象基类，定义 `name`、`enabled`、异常策略与可选生命周期 hook。
+* `SanitizerAdapter` 属于请求改写类 adapter，主要运行在 `async_pre_call_deployment_hook`，必要时在 `log_pre_api_call` 做诊断/兜底。
+* `CooldownAdapter` 属于限流状态类 adapter，通常至少需要两个阶段：失败后 hook 解析 GLM 429 reset 时间并记录 `cooldown_until`；请求前 hook 根据 `cooldown_until` 决定是否避让 GLM 或提示 Router 不要选中该部署。
+* `SanitizerAdapter` 和 `CooldownAdapter` 应作为分类抽象或 mixin 存在，沉淀该类别必须实现/推荐实现的 hook、配置模型与测试契约；具体实现例如 `DeepSeekThinkingSanitizerAdapter`、`GlmCooldownAdapter`。
+* adapter 是可组合的：同一个生命周期阶段可以串行调用多个 adapter，不同职责的 adapter 不互相替代。
+* adapter 是可替换的：例如未来可以把 `GlmCooldownAdapter` 替换成更通用的 `ProviderCooldownAdapter`，也可以把 DeepSeek sanitizer 替换成其它实现；替换范围限于同一职责/协议，不是用 cooldown 取代 sanitizer。
+
+## Expansion Sweep
+
+### Future evolution
+
+* 后续可把 GLM 429 reset 时间缓存成 per-model-group 的恢复时间，让多个进程或容器共享状态。
+* 如果其它供应商也返回可解析 reset 时间，可抽象为 provider-specific cooldown parser。
+* callback adapter 框架可继续承接供应商参数修正、响应 header 注入、错误转换与观测日志。
+
+### Related scenarios
+
+* `cc-glmplan-opus` 与 `cc-glmplan-haiku` 应保持一致，否则 subagent/haiku 流量仍会撞额度。
+* `litellm.local.yaml` 与 `newapi.yaml` 的模型配置要同步，避免本地与模板行为漂移。
+
+### Failure & edge cases
+
+* 429 body 可能不是 JSON，或中文 reset 时间格式变化；解析失败时应回退到固定 5 小时冷却。
+* reset 时间可能已经过去；恢复时间应至少有一个很短的保护窗口，避免立即重试风暴。
+* callback 诊断日志不能输出 prompt、API key、完整 headers 或完整 request body。
+* 单个 adapter 出错时应默认 fail-open，除非该 adapter 明确声明该错误必须阻断请求。
+
+## Technical Approach
+
+推荐采用 `GatewayCallbackHub + adapters`：
+
+* `DeepSeekThinkingSanitizerAdapter` 复用现有 sanitizer core/logging，接入 `async_pre_call_deployment_hook` 与 `log_pre_api_call`。
+* `GlmCooldownAdapter` 实现 GLM 429 reset 时间解析、恢复时间计算与安全日志；运行时通过 failure hook 记录 cooldown，并在请求进入 Router 前把冷却中的 `cc-glmplan-*` 改写到对应 DeepSeek fallback。
+* 配置层已迁移到统一 callback hub；旧单用途入口删除，避免 callback 顶层继续混杂实现细节。
+
+## Decision (ADR-lite)
+
+**Context**: LiteLLM callback 是全生命周期扩展点，单独挂载 `deepseek_thinking_sanitizer` 会把不同供应商兼容逻辑继续堆在单用途 callback 里；GLM cooldown 与 DeepSeek thinking sanitizer 的职责、触发阶段和状态需求不同。
+
+**Decision**: 采用代码注册 adapter、配置只控制启用状态和策略参数的 `GatewayCallbackHub`。LiteLLM YAML 挂载统一 callback hub；DeepSeek sanitizer 与 GLM cooldown 作为独立 adapter 接入。
+
+**Consequences**: 第一版配置稳定且容易测试；后续新增 provider-specific adapter 不需要改变 LiteLLM callback 挂载方式。代价是 adapter 列表不做完全 YAML 动态声明，如需新增 adapter 需要改 Python registry。
+
+## Out of Scope
+
+* 不改变 DeepSeek Claude Code 兜底路由的 thinking/effort 参数保留策略。
+* 不处理非 GLM 供应商的动态冷却。
+* 不在第一版引入跨容器共享状态，除非实现动态 cooldown 必须依赖数据库或外部缓存。
+
+## Technical Notes
+
+* 相关文件：
+  * `ai/gateway/litellm/litellm.local.yaml`
+  * `ai/gateway/litellm/newapi.yaml`
+  * `ai/gateway/litellm/callbacks/gateway_callback.py`
+  * `ai/gateway/litellm/callbacks/framework/hub.py`
+  * `ai/gateway/litellm/callbacks/framework/adapters.py`
+  * `ai/gateway/litellm/callbacks/adapters/deepseek/thinking_sanitizer.py`
+  * `ai/gateway/litellm/callbacks/adapters/deepseek/thinking_sanitizer_core.py`
+  * `ai/gateway/litellm/callbacks/adapters/glm/cooldown.py`
+  * `ai/gateway/litellm/callbacks/tests/`
+  * `ai/gateway/litellm/litellm.md`
+  * `.trellis/spec/infra/litellm-gateway.md`
+* Context7 使用 `/websites/litellm_ai` 查询 LiteLLM callback 与 Router 文档。

.trellis/tasks/archive/2026-05/05-12-glm-429-cooldown-thinking-fallback/research/litellm-callback-router.md

@@ -0,0 +1,67 @@
+# LiteLLM callback 与 Router 冷却调研
+
+## 结论
+
+* `litellm_settings.callbacks` 注册的是 LiteLLM Proxy 的调用生命周期 hook，不是只在 fallback 时触发。
+* 本仓库的 `DeepSeekThinkingSanitizer` 在 hook 内部通过 `call_type == CallTypes.anthropic_messages` 与 DeepSeek deployment/model/api_base 判断是否实际清理；因此正常 GLM 请求会进入生命周期，但不会执行清理逻辑。
+* `async_pre_call_deployment_hook` 是 Router 选中具体 deployment 后、provider 构造请求体前的请求改写点，适合做 DeepSeek fallback 的 messages 清理。
+* `log_pre_api_call` 是 provider 发起 HTTP 请求前的 logging hook，可作为诊断与兜底，但不应作为唯一改写点。
+* LiteLLM 文档暴露的 `cooldown_time` 是固定冷却时长；Context7 文档未显示可直接按 429 响应体里的重置时间动态设置 deployment cooldown 的 YAML 配置。
+* 文档显示 Router 支持 `retry_policy`、`allowed_fails_policy`、`cooldown_time` 与 `retry_after`，但这些更像固定策略或重试等待，不等同于“解析上游错误 body 后冷却到指定时间”。
+
+## 仓库现状
+
+* `ai/gateway/litellm/litellm.local.yaml` 和 `ai/gateway/litellm/newapi.yaml` 中 `cc-glmplan-opus` / `cc-glmplan-haiku` 当前都配置 `cooldown_time: 3600`。
+* 文档 `ai/gateway/litellm/litellm.md` 当前也说明 GLM 两个 Claude Code 入口失败后冷却 1 小时。
+* `.trellis/spec/infra/litellm-gateway.md` 已要求 sanitizer 的触发边界以 Router 选中的目标部署是否为 DeepSeek Anthropic 兼容端点为准，而不是只依赖 `fallback_depth`。
+* sanitizer 当前实现已经符合“不是只在 fallback 时清理，而是只在 DeepSeek Anthropic 请求上清理”的设计：直接调用 `claude-code-deepseek-*` 时同样受保护。
+
+## 可行方案
+
+### 方案 A：固定冷却改成 5 小时
+
+* 做法：把两个 GLM Claude Code 入口的 `cooldown_time` 从 3600 改为 18000，并同步文档。
+* 优点：实现最小，贴合 GLM 5 小时额度窗口，立刻减少中途多余探测请求。
+* 缺点：如果 429 响应明确给出更早或更晚的恢复时间，固定 5 小时仍不够精确；也无法自然表达“恢复时间 + 1 分钟”。
+
+### 方案 B：新增 GLM 429 重置时间感知逻辑
+
+* 做法：在 LiteLLM 可用 hook 或本地兼容层中识别 GLM 429 错误体，解析 `您的限额将在 YYYY-MM-DD HH:mm:ss 重置`，按该时间加 60 秒设置后续请求避让。
+* 优点：最贴近用户描述，能避免 GLM 窗口内重复探测，也能在额度提前恢复时及时切回。
+* 缺点：需要确认 LiteLLM 当前运行版本是否有可写的 deployment cooldown API；如果没有，可能要通过外部缓存/请求前拦截实现，复杂度和回归风险更高。
+
+### 方案 C：先固定 5 小时，同时预留动态解析测试
+
+* 做法：本次先把 cooldown 改为 18000，文档明确这是临时保守策略；同时新增纯函数和测试，用于解析 GLM 429 reset 时间，后续接入 Router 冷却 API。
+* 优点：兼顾当前止血和后续演进，测试先锁定中文错误格式。
+* 缺点：会留下暂未接入运行链路的解析代码，除非下一步马上补齐动态冷却。
+
+### 方案 D：统一 callback hub + 独立 adapter
+
+* 做法：LiteLLM YAML 只挂载一个统一 `CustomLogger` 实例，由 hub 分发生命周期 hook；DeepSeek thinking sanitizer 与 GLM cooldown 都作为 adapter 接入。
+* 优点：符合 callback 全生命周期扩展点的实际模型；不同供应商兼容逻辑可以独立启用、配置、测试。
+* 缺点：需要先定义 adapter 协议、配置加载方式、异常隔离策略和安全日志边界。
+
+## callback hub 设计建议
+
+* 保持 LiteLLM 配置简单：`litellm_settings.callbacks` 中只挂载一个 hub。
+* adapter 由 Python registry 管理，避免在 YAML 中直接散落多个 Python import 路径。
+* 配置只负责声明 adapter 是否启用、适用范围和少量策略参数，例如：
+  * `deepseek_thinking_sanitizer.enabled`
+  * `glm_cooldown.enabled`
+  * `glm_cooldown.model_groups`
+  * `glm_cooldown.reset_buffer_seconds`
+  * `glm_cooldown.fallback_cooldown_seconds`
+* 每个 adapter 只实现自己需要的 hook；hub 对缺失 hook 自动跳过。
+* adapter 默认 fail-open：记录安全日志，但不因为某个辅助逻辑失败拖垮请求链路。
+* 对请求改写类 adapter，应明确 hook 阶段和可修改对象；例如 DeepSeek sanitizer 仍应在 `async_pre_call_deployment_hook` 做主改写。
+
+## callback 问题回答
+
+历史配置 `callbacks: - callbacks.deepseek_thinking_sanitizer.proxy_handler_instance` 表示 LiteLLM 启动时加载这个 `CustomLogger` 实例，并在请求生命周期对应阶段调用它实现的 hook。它不是 fallback 专用配置。当前实现已迁移到统一 `callbacks.gateway_callback.proxy_handler_instance`，再由 DeepSeek sanitizer adapter 通过以下条件缩小实际影响范围：
+
+* `async_pre_call_deployment_hook` 只处理 `CallTypes.anthropic_messages`。
+* `is_deepseek_anthropic_request(kwargs)` 必须识别到 DeepSeek 模型、DeepSeek deployment，或 DeepSeek Anthropic api_base。
+* `fallback_depth` 只出现在日志诊断中，用于确认是否来自 Router fallback，不作为触发条件。
+
+因此：正常 GLM 主路由不会被 sanitizer 清理；GLM 429 后 fallback 到 DeepSeek 会清理；用户直接调用 `claude-code-deepseek-*` 也会清理，因为同样是 DeepSeek Anthropic 请求。

.trellis/tasks/archive/2026-05/05-12-glm-429-cooldown-thinking-fallback/task.json

@@ -0,0 +1,26 @@
+{
+  "id": "glm-429-cooldown-thinking-fallback",
+  "name": "glm-429-cooldown-thinking-fallback",
+  "title": "brainstorm: 优化 GLM 429 冷却与 fallback thinking 处理",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "mudssky",
+  "assignee": "mudssky",
+  "createdAt": "2026-05-12",
+  "completedAt": "2026-05-12",
+  "branch": null,
+  "base_branch": "master",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}