凌晨两点，Harness 里巡检的 AI Agent 醒了。这是 Harness Engineering 的典型场面：Agent 像魔法工厂里的小精灵，干活又快又不知疲倦，监控告警像缰绳，负责看住它们别乱跑。模型认证这一层我放在 TaoToken，注册和创建 Key 走 https://taotoken.net/?utm_source=taotoken_aicg_blog_end ，填进代码里的 Base URL 用 https://taotoken.net/api 。原文把 Harness 比作小精灵的缰绳，这个比喻挺准：小精灵本身聪明，但一群小精灵同时推进长会话、调工具、编排任务，缰绳松一寸，Token 就多烧一截。更麻烦的是模型认证常常散落在四五个脚本、两三个运行环境里，今天这个 Agent 的 Key 过期，明天那个 Agent 的地址被写死，等告警真的响起来，你先要花半小时确认到底是模型挂了还是认证挂了。
这篇文章按原文的节奏往下走：先讲 Harness 监控告警到底要盯哪几个信号，再把 Python 项目骨架搭起来，然后逐个落地 3σ、移动窗口统计、KNN、LOF 这些异常检测算法，最后才处理模型认证这一段——把 Harness 里多个 Agent 的模型请求统一收到一条兼容通道上，让检测逻辑安心处理数据，而不是被 401 打断。算法部分和原文一样占大头，认证部分只解决“请求能不能稳定发出去”这一件事。
1. 魔法工厂的小精灵与缰绳：Harness 监控告警先卡在哪
1.1 小精灵干活很勤，Token 账单也很勤
原文把小精灵比作自主推理的 Agent，这个类比放在成本上也成立。一个巡检 Agent 的典型循环是：拉一段时间窗口的指标、读几条日志、判断有没有异常、生成一句告警摘要、决定要不要升级通知。每一步都可能是一次模型调用，长会话累积上下文、多工具调用来回确认、任务编排里失败重试，Token 消耗是叠加上去的，而不是线性增长的。
真正让人头疼的不是单次调用贵，而是调用入口太散。指标采集脚本里写一份 Key，告警摘要服务里写一份，任务编排器里再写一份，模型名还各不相同。等到某个供应商通道抖动，你要挨个改配置文件；等到某把 Key 额度见底，告警正好在那一刻集体静默。小精灵跑得越勤，这种分散带来的风险就越大。
1.2 缰绳的两头：检测逻辑和模型出口要分开
Harness Engineering 的思路是把“看管”这件事拆成两层：一层是确定性的检测逻辑，比如阈值判断、统计检验、密度估计；另一层是需要语言能力的部分，比如把一堆指标翻译成一句人话、给值班同学写排查建议。前者必须稳定、可复现、不依赖外部服务；后者才是模型调用发生的地方。
所以本文的工程原则是：异常检测自己算，不经过任何模型通道；模型只负责解释和总结。这样即使模型侧短时间不可用，检测链路照样能跑，只是告警摘要会降级成模板文本。把这两层分开，后面配认证的时候，改动面就只剩一个出口地址和一个 Key。
2. 异常行为实时检测要看住哪三个信号
2.1 长会话：轮次、上下文与单次耗时
长会话是 Agent 最容易被忽略的异常源头。正常的一次任务，轮次大概在个位数；如果某个 Agent 的轮次连续爬升，通常意味着它陷入了自我确认——反复读同一批数据、反复要求工具返回同样的结果。可观测的量有三个：单位时间内的对话轮次、上下文 Token 估算值、单次模型调用耗时。这三个量放在同一个时间窗口里做移动统计，很容易看出漂移。
需要注意的是，轮次升高不一定是坏事。批量任务天然轮次多，所以要按 Agent 类型分组统计，再在组内比较，别拿巡检 Agent 和日报生成 Agent 直接对比，否则基线会被互相污染。
2.2 多工具：调用成功率与调用顺序
多工具场景里的异常更像“动作走形”。工具调用成功率突然下降、同一个工具在短时间内被反复调用、本该先查询再写入的顺序被打乱，这些都属于行为异常而不是指标异常。工程上可以给每次工具调用打两个标签：工具名和任务类型，然后统计单位时间内的调用次数、失败次数、以及相邻调用的重复率。
重复率这个指标特别实用。Agent 卡住的时候，往往表现为“同一个工具名 + 同样的参数摘要”被高频重复，重复率一上去，基本可以判定它在原地打转，不需要等它把预算烧完。
2.3 任务编排：重试、并发与死循环
任务编排层看的是一张更大的图：任务被领取的次数、失败后重试的次数、同一时刻并发的 Agent 数量、单个任务从开始到结束的时长分布。重试次数是死循环的早期信号，并发数量是资源争抢的信号，结束时长分布则能暴露个别任务拖后腿的问题。
这三类信号最后会被整理成一个特征向量，交给下一节的检测算法。特征维度不用多，五到八个就够，维度越低越容易解释，越容易给值班同学讲清楚“为什么这条告警值得看”。
3. 搭起骨架：venv、numpy、scikit-learn、prometheus-client
3.1 虚拟环境和依赖安装
原文在这一步创建虚拟环境并安装几个基础库，这里保持一致的做法，目的是把检测逻辑和系统 Python 隔开，避免版本互相踩。
python -m venv .venv source .venv/bin/activate pip install numpy scikit-learn prometheus-clientWindows 下激活命令换成.venv\Scripts\activate即可。装完之后建议先python -c "import numpy, sklearn, prometheus_client"跑一次，确认没有编译问题再写代码。这三个库的分工很清楚：numpy 做窗口统计，scikit-learn 出 KNN 和 LOF，prometheus-client 负责把指标和告警状态暴露出去。
3.2 指标口径和 /metrics 端口
先把指标定义清楚，后面所有算法都从这些指标里取数。计数器用于累计量，Gauge 用于瞬时值，Histogram 用于耗时分布。
from prometheus_client import Counter, Gauge, Histogram, start_http_server AGENT_TURNS = Counter("harness_agent_turns_total", "Agent 对话轮次", ["agent", "task"]) TOOL_CALLS = Counter("harness_tool_calls_total", "工具调用次数", ["agent", "tool"]) TOOL_FAILS = Counter("harness_tool_fails_total", "工具调用失败次数", ["agent", "tool"]) MODEL_LATENCY = Histogram("harness_model_latency_seconds", "单次模型调用耗时", ["agent"]) ANOMALY_SCORE = Gauge("harness_anomaly_score", "异常检测得分", ["agent", "method"]) start_http_server(9101)端口选一个没被占用的就行，跑起来之后curl localhost:9101/metrics能看到文本输出，说明采集侧通了。指标名尽量带上harness_前缀，避免和你已有的业务指标混在一起。
4. 异常检测算法落地：3σ、移动窗口、KNN 与 LOF 怎么分工
4.1 3σ 与移动窗口统计
3σ 是最省事的一层过滤，适合分布接近正态、量纲稳定的指标，比如单次调用耗时。移动窗口统计则解决基线漂移的问题：不用全量历史，只看最近 N 个点。
import numpy as np def rolling_stats(series, window=30): arr = np.asarray(series, dtype=float) if arr.size < window: return None recent = arr[-window:] return float(recent.mean()), float(recent.std(ddof=0)) def sigma_flag(series, window=30, k=3.0): stats = rolling_stats(series, window) if stats is None: return False mu, sigma = stats if sigma == 0: return False return abs(series[-1] - mu) > k * sigma窗口大小要按指标节奏定。分钟级采集用 30 个点代表半小时，采样频率变了窗口也要跟着变。标准差为 0 的情况要单独挡掉，否则除零或者恒定为真的判断会让告警一直挂着。
4.2 KNN 距离与 LOF 局部密度
3σ 管不了的场景，交给多特征方法。KNN 距离看的是“这个点离它最近的邻居有多远”，适合发现孤立的离群样本；LOF 看的是“这个点周围有多稀疏”，适合发现密度意义上的异常，两者视角不同，可以同时跑，得分一起进监控。
import numpy as np from sklearn.neighbors import NearestNeighbors, LocalOutlierFactor def knn_distance_scores(X, k=5): X = np.asarray(X, dtype=float) k = min(k, len(X)) nn = NearestNeighbors(n_neighbors=k).fit(X) dist, _ = nn.kneighbors(X) return dist[:, -1] def lof_scores(X, k=20): X = np.asarray(X, dtype=float) k = min(k, len(X) - 1) clf = LocalOutlierFactor(n_neighbors=k) labels = clf.fit_predict(X) return -clf.negative_outlier_factor_, labels特征向量按第 2 节的口径拼：轮次、上下文估算、单次耗时、工具调用次数、失败率、重复率、重试次数。样本量少的时候把 k 调小，LOF 的邻居数必须严格小于样本数，否则 sklearn 直接报错，这是很常见的第一次运行失败点。
4.3 从得分到告警：冷却与去重
算法输出的是分数，不是通知。分数要先转成布尔状态，再过一层冷却窗口和去重。冷却窗口的作用是避免同一个 Agent 在十分钟内反复触发；去重的作用是同一个根因只发一条通知，后续同源事件折叠进去。
这里就是模型值得出场的地方：把窗口内的特征、触发的方法名、最近的调用记录拼成一段上下文，让 Agent 生成一句人话摘要和两条排查建议。注意频率控制——异常风暴期间不要每个采集周期都调一次模型，按冷却窗口聚合后再调，一次覆盖多条事件，Token 消耗会低一个量级。另外，Agent 只负责读指标、生成摘要和排查建议，真正的诊断命令、脚本或 SQL 由值班同学在本地环境执行，再把输出贴回对话，不要让 Agent 越过这道桥直接碰生产环境。
5. 模型认证统一：在 TaoToken 创建 Key，客户端 Base URL 填 /api
5.1 先别写死通道，环境变量先行
检测链路跑通之后，再把模型出口接上。这一步的目标只有一个：让 Harness 里所有需要调模型的 Agent 走同一个入口，换模型、换 Key 只改一处。先打开 TaoToken 注册账号并创建 API Key，Key 只在控制台里复制一次，代码里用占位符YOUR_API_KEY表示，别直接写进仓库。
创建好之后，把 Base URL 指向https://taotoken.net/api，注意末尾不要加/v1。模型 ID 不要凭记忆写，去模型广场看当时的列表，以页面上显示的为准，因为可用模型会随时间调整，写死了过几周就会 404。
5.2 Python 客户端与 .env 可复制配置
配置放在.env里，代码只读环境变量。.env文件记得加进.gitignore。
TAOTOKEN_API_KEY=YOUR_API_KEY TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_MODEL=<以模型广场当时列表为准>客户端初始化部分，用兼容 OpenAI 的写法即可，参数直接来自环境变量：
import os from openai import OpenAI client = OpenAI( api_key=os.environ["TAOTOKEN_API_KEY"], base_url=os.environ["TAOTOKEN_BASE_URL"], ) def summarize_alert(prompt: str) -> str: resp = client.chat.completions.create( model=os.environ["TAOTOKEN_MODEL"], messages=[ {"role": "system", "content": "你是 Harness 告警摘要助手，只根据给定指标说话，不臆测。"}, {"role": "user", "content": prompt}, ], temperature=0.2, ) return resp.choices[0].message.content如果不想装 python-dotenv，测试阶段手动export TAOTOKEN_API_KEY=YOUR_API_KEY也能跑，但长期跑建议还是让进程自己加载，省得忘了导出导致 401。
5.3 多个 Agent 运行时共用同一个出口
Harness 里往往不止一个进程在调模型。除了 Python 检测服务，可能还有跑在终端里的编码助手，或者别的编排器。编排器和检测服务共用这套环境变量最省事；如果某个运行时是 Claude Code 这类命令行工具，就单独用它的环境变量指向同一个出口，下面是~/.claude/settings.json里的写法：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY", "ANTHROPIC_MODEL": "<以模型广场当时列表为准>" } }注意 Codex 用的是~/.codex/config.toml里的model_provider和base_url，不要把这几个ANTHROPIC_*变量套过去，两边的配置体系不一样。无论哪种运行时，改动点都只有地址、Key、模型名这三样，Key 统一从控制台创建，地址统一是https://taotoken.net/api。
6. 启动 Harness 做冒烟验证：模型先通，检测后跑
6.1 三步验证顺序
验证不要一上来就压测，按顺序来更省时间。第一步，手动调一次模型，确认 Key、地址、模型名三者都对；第二步，把指标采集跑起来，curl localhost:9101/metrics能看到harness_agent_turns_total之类的指标在动；第三步，喂一段历史数据给检测函数，看 3σ 和 LOF 得分是否落在合理区间。
第一步最容易被跳过，但它恰恰是排错成本最低的一步。发一条最简单的消息，能返回内容就说明认证层通了，后面的问题一定在业务逻辑里，不用再怀疑通道。
6.2 观察 /metrics 与告警事件
第二步跑通后，让检测循环按固定周期执行：取窗口数据、算三组得分、更新 Gauge、判断是否需要告警。观察两件事：harness_anomaly_score是否在正常区间小幅波动，以及告警事件是否在冷却窗口内被正确折叠。如果得分长期贴着阈值边缘，说明窗口或系数需要调，不是算法错了。
指标维度别开太多。agent和method两个标签已经够用，再加任务 ID 之类的会拉爆时序数量。告警摘要调用的次数和耗时也建议单独计数，这样能直观看到模型这一层的开销，顺便确认多条 Agent 的请求确实都从同一个出口发出去。
7. 排障对照：401、模型名不认、指标空窗、告警抖动
7.1 模型认证与地址类报错
401 大多数时候不是 Key 错了，而是进程没读到环境变量。先确认echo $TAOTOKEN_API_KEY有值，再确认客户端读的是同一个变量名。如果是.env方案，注意加载顺序，环境变量要先于客户端构造。
模型名不认识，一般有两种情况：写了自己臆想的模型 ID，或者模型已经下线。解决办法只有一个，去模型广场按当时的列表抄，别猜。还有一种常见错是把 Base URL 写成了官网地址或者多了/v1后缀，正确写法就是https://taotoken.net/api，末尾什么都不加。
7.2 检测与告警侧的问题
指标空窗先看端口，start_http_server起的端口被别的进程占了会静默失败，lsof -i:9101能查出来。如果指标有但数值不动，检查采集函数是不是被异常吃掉了。
告警抖动基本是参数问题。窗口太小会让基线跟着噪声走，k值太小会把正常波动判成异常；LOF 的邻居数大于等于样本数会直接抛异常，所以小样本阶段先把邻居数压到样本数的三分之一以下。3σ 在标准差为 0 时会恒真，这个也要提前挡掉。
8. 值班这件事，最后落在告警渠道和额度上
到这里，Harness 里的小精灵有了缰绳，缰绳上装了计分板，模型请求也收敛到一个出口。接下来最值得做的一件事，是拿同一把 Key 在 模型对话 里发一条测试消息，确认模型 ID 和地址填得没错；如果这套巡检要长期跑，去 Coding Plan 看看额度档位够不够用，Key 统一在 控制台 API Keys 里创建和轮换。
值班的同学还可以顺手接一次 Claude Code 接入文档 里的环境变量写法，把常用的排查工具也指到同一个出口。别忘了最后一步：打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 看一眼控制台里的调用记录，确认这次 Harness 冒烟测试的请求确实记上了账，没有静默失败，也没有重复计费。
