被否掉的、没底的、还没做的

《ops-agent 建造笔记》第 12 篇（终） 代码基线：v0.1.0-rc.1，提交 d897d2c95e70（2026-10-25 发布的候选版） 对照实现：core.py、execution.py、agent/tools.py、agent/schedule.py 与发布/验收文档

同一个内核，四个壳

《ops-agent 建造笔记》第 10 篇 代码基线：v0.1.0-rc.1，提交 d897d2c95e70（2026-10-25 发布的候选版） 对照实现：opsagent、agent/loop.py、agent/session.py、agent/rpc.py、mcp_server.py

0. 一个我答不上来的问题

日志页里躺着一条记录：状态 200，耗时 28 秒，token 数正常。然后有人问了一个特别自然的问题——这 28 秒花在哪了？

0. 连续五次失败，但这不是 flaky

我有一条每夜跑的 E2E：起一套完整的 compose（MySQL、Redis、所有服务），然后用 Playwright 跑管理后台的关键路径。

0. 两次看起来相反的判断

这篇讲两个性能决策，它们的结论看起来是相反的。

0. 这篇是给"想照抄这套结构"的人写的

前面 24 篇讲的是"我为什么这么做"。这一篇不一样——它讲具体怎么做。

0. 症状：服务端很快，但页面就是慢

有一段时间我觉得管理后台"卡"。具体表现是：点侧边栏切到 /dashboard、/usage、/admin/logs，要等大约一秒才出内容。

0. 我给自己做了一次代码审查，然后否决了它的大部分方案

有一阵子我觉得代码里积了不少问题——文件越来越大、有几处逻辑我自己都记不清了。于是我让一个模型对 develop 做了一轮系统性审查，产出一份问题清单。

0. 一个差点被我当成"样式问题"的许可证问题

这次重设计的起点不是"界面不好看"，是一件更实际的事：字体没覆盖中文。

0. 这个页面的难点不在聊天界面

做一个"在浏览器里调模型"的 Playground，聊天界面本身没什么难的：一个输入框、一个消息列表、一个流式渲染。

0. 第一版对账：全是误报

我第一版的对账逻辑很简单：把钱包余额和账本净额比一下，不一致就报出来。

0. 差点发生的事：审计日志一条都没记

这段代码注释是我在 review 自己的时候发现的，编号 platform-L9：

0. 两个现象，一个共同的形状

这篇复盘两次问题。它们表面上看没有关系：

0. 一个接口设计的取舍：用户没订阅，算不算错误

做这个接口的时候遇到的第一个问题不是技术问题，是语义问题。

0. 问题：缓存怎么知道该失效了

第 12 篇讲了三层缓存，但留了一个尾巴没讲：缓存什么时候该失效。

0. 一个数字让我决定加缓存

第 1 篇里算过一笔账：relay-gateway 处理一个请求，要打四次下游 gRPC——identity 鉴权、channel 选路、billing 预扣、billing 结算，外加写日志。

0. 一个编号，两种假设

我第一版迁移就是一个编号序列：001_xxx.sql、002_xxx.sql……每个文件一个号，跑的时候按号排序。

0. 一个看起来很简单的问题，答案不简单

用户买了一个月的套餐，付了 20 块。用了 10 天，要求退款。

摘要

这套结构里真正需要照抄的东西不多，但如果不照抄那几样，后面就很难改回来。这篇分成两部分：第一天必须有的（不做后面会痛），和可以后补的（做早了是浪费）。然后走一遍"加一个资源"的完整步骤。

摘要

一个看起来很简单的问题，答案不简单：用户买了一个月套餐、用了 10 天、要求退款，退多少钱？而这只是开始——订阅怎么处理、已经消耗的额度怎么算、续过费先退哪个、账本上怎么写。这篇讲我怎么处理这三个操作，以及一个跨所有操作的机制：购买时的套餐快照。

摘要

做网关时我一开始想"给每个上游接口写一个适配器"，列完清单就停住了：embeddings、moderations、images、audio 这些接口的内容我根本不需要理解，原样转发就行。对它们写适配器等于为每个接口维护一套可能与上游产生分歧的结构体。这篇讲这条路——代码只有几十行，但有几个我认为值得说的决定。

摘要

两个看起来相反的结论：一个被微基准证明"变慢了 2.1 倍"的优化我最后保留了；一个 P95 回归 69.7% 但成功率反而更好的重构我回滚了。它们背后的标准是同一条——我要的改善必须出现在真实负载的请求级指标上，而不是出现在任何可以被我解释的局部数字里。

摘要

我给自己做了一次代码审查，然后否决了它的大部分方案。因为那份清单是在没有读全部代码的情况下写的——比如它说我 domain/ 目录"名不副实"，但那条不符合我在仓库规范里定义的准入标准。这篇讲逐条复核的过程：哪些我认了、哪些我否了、哪些我决定什么都不做。

摘要

我第一版的对账逻辑很简单：把钱包余额和账本净额比一下，不一致就报出来。跑起来之后几乎每个用户都进了异常列表——因为我没想清楚"余额"到底是什么。这篇讲七类核对分别在查什么、为什么它们的容差不一样，以及我为什么坚持让它只报告不修复。

0. 一个把我绕进去的概念冲突

做订阅功能的时候，我脑子里只有一个"额度"概念：用户买了套餐，每个月能用 20 美元，超过就停。

0. 先说结论：只有四家需要真正写代码

接上游 provider 这件事，我一开始以为是"一家一个适配器"。写了才发现不是：三十多个渠道类型里，真正需要单独写协议转换逻辑的只有四家，其余二十多家全是同一个适配器的不同配置。

0. 一个第一次写 OAuth 刷新很容易漏掉的事

我第一版的 token 刷新逻辑大概是这样的：

0. 一个迟早要面对的问题

订阅账号会有各种"暂时不能用"的情况：被上游限流了、额度用完了、凭据过期了、上游在抖动。这些状态都要有退出机制——总不能因为一次 429 就永远不再用这个账号。

摘要

有一段时间我的审计日志一条都没记下来，而且无法通过看日志发现——因为日志系统本身没接上。空手而归和从未出发，在观测上是一样的。这篇讲这件事，以及我在指标、审计、追踪这三套东西上的其他取舍。

摘要

订阅账号会遇到各种"暂时不能用"：被限流、额度用完、凭据过期。这些状态都要有退出机制。自然的做法是定时扫一遍把该恢复的恢复——但 channel-service 有多个副本，于是四个副本会同时扫。这篇讲我怎么把"多副本并发"当成默认前提来设计这两个 sweeper。

摘要

第 12 篇讲了三层缓存却留了个尾巴：缓存什么时候该失效。纯 TTL 的答案是"一个被禁用的 token 最多还能用 5 分钟"，我不太能接受。这篇讲我最后怎么做的——没有引入消息队列，而是用了一张表加 Redis Streams，以及这条路上踩到的几个坑。

摘要

relay 处理一个请求要打四次下游 gRPC，而用户 token、渠道配置这些数据的变更频率是"每分钟几次"、读取频率是"每秒上千次"。这篇讲我怎么搭这个缓存，其中有一个我一开始想错的地方——我一度把"缓存命中"当成了"授权通过"。

摘要

我最初以为"额度"只有一个概念：用户买了套餐，每月能用多少，超了就停。写下去才发现上游也在算额度，而且它算的跟我不一样——它报百分比，我记美元；它按自己的 5h/7d 窗口，我按用户的日/周/月。这篇讲我最后怎么同时维护这两套账，以及它们各自最容易出错的地方。

摘要

接上游 provider 这件事，我一开始以为是"一家一个适配器"。写到第十家才发现，真正需要单独写协议转换逻辑的只有四家，其余二十多家全是同一个适配器的不同配置。这篇讲这个拆分怎么形成的，以及我在接外部地址时踩到的两条边界——SSRF 防护和流式超时，两条我都做错过。

摘要

有一批请求要的模型在所有渠道上都没配置，channel-service 全部返回"没有可用渠道"。这个错误跨 gRPC 回来是 codes.Unknown，而我的熔断器把它算作失败——于是用户传错一个模型名，整个网关的流量都被熔断器拒了。这篇讲这次之后我怎么重排错误分类，以及跨服务降级的其他几处取舍。

摘要

并发一上来，上游返回 429，而我当时的逻辑把 429 当失败，重试几次就把一个完全健康的账号标记成不健康、从候选里摘掉。这就是"用满"和"用坏"没分开的后果。这篇讲我最后怎么在限流器、冷却时长、重试策略、健康记录、指标标签每一处把它们分开。

摘要

选路这件事比我想的难。优先级相同的渠道怎么分流量、重试该换谁、换的时候会不会误伤别的渠道、授权要不要再验一次、一个渠道坏到什么程度该被摘掉——这篇按我实际动手的顺序讲，中间有两次返工，还有一个后来 review 时自己揪出来的、后果比较严重的 bug。

摘要

从一次我自己撞的墙讲起：网关把上游的 4xx 改写成了 502，而终止分支缺日志，我完全看不到发生了什么。顺着这个坑，我把 /v1/chat/completions 这条链路从头到尾捋了一遍，这篇记录其中的选择——哪些是当初顺手写下的、哪些是返工回来的、哪些我到现在也还没底。

摘要

这个项目还没上线。我在开发过程中把结构翻了一遍，而且方向还相反：第一次是把一个 2391 行的 internal/relay/server/http.go 拆开，第二次是把拆出去的九个服务收进 Kratos 大仓结构、抽出共享层，并写脚本卡住服务之间互相 import。这篇讲哪些线是我真的按需要切的，哪些只是抄了微服务的目录形状。