企业官网建设流程全解析

1. 项目概述：为什么一份 Agent 上线 Checklist 比写一百行代码还重要

你有没有遇到过这样的场景：花两周时间把一个智能体（Agent）的核心逻辑调通了，本地跑 demo 时效果惊艳，连测试数据都挑不出毛病；可一上生产环境，它就开始“装死”——响应延迟飙升、任务莫名中断、日志里全是看不懂的空指针堆栈，偏偏监控面板一片空白，连问题出在调度层、工具调用层还是记忆模块都定位不了。更糟的是，运维同学一句“没看到你的服务注册”，直接把你卡在发布流程外。这不是个别现象，而是当前 Agent 工程化落地中最普遍、最隐蔽的“上线失能症”。

这个标题里的Agent 上线 Checklist，不是一份走形式的签字表，而是一套覆盖“能跑→能稳→能观→能管”全链路的实战验证协议。它把抽象的“Agent 可用性”拆解成可测量、可执行、可回溯的 27 个原子动作，其中门禁（Gatekeeping）是第一道生死线——它不让你的 Agent 带着未初始化的记忆、硬编码的密钥、缺失健康检查端点的缺陷进入集群；可观测性埋点（Observability Instrumentation）是第二道生命线——它确保每个 Tool 调用耗时、每轮 LLM 请求 Token 分布、每次状态机跳转都被结构化采集，而不是靠翻三屏日志猜问题；而AgentOps 落地则是最终交付标准——它要求你的 Agent 不仅自己能干活，还能被统一配置中心下发参数、被灰度平台控制流量、被故障注入系统验证韧性。这三者环环相扣：没有门禁，可观测性就是给定时炸弹装摄像头；没有可观测性，AgentOps 就是蒙眼开车。

我带过的三个跨部门 Agent 项目里，平均有 68% 的线上 P0 级故障，根源不在模型或提示词，而在 Checklist 第 5 条“健康检查端点返回码校验”和第 14 条“OpenTelemetry trace context 透传验证”这两项被跳过。这次分享的不是理论框架，而是我们压测环境实测通过、已支撑日均 230 万次 Agent 调用的 Checklist 实战模板，附带开箱即用的 Python 验证脚本——它会自动扫描你的 Agent 服务，生成带红黄绿灯标识的合规报告，并定位到具体哪一行代码违反了哪条规则。接下来，我会带你逐条拆解这 27 项中真正卡脖子的 12 个核心项，解释为什么它们必须存在、怎么验证才算过关、以及我踩过的那些让团队加班到凌晨三点的坑。

2. 核心设计逻辑：门禁、可观测性与 AgentOps 为何必须三位一体

2.1 门禁不是拦截器，而是“出厂质检流水线”

很多人把门禁理解成 CI/CD 流水线里加个 if 判断：“如果 config.yaml 缺少 api_key 字段，就 fail”。这是对门禁最大的误解。真正的门禁，是模拟生产环境对 Agent 的第一次“体检”，它必须覆盖三个维度：

• 配置完备性：不只是字段是否存在，而是值是否符合运行时约束。比如timeout_seconds: 30在开发环境够用，但在高并发下会导致连接池耗尽；max_retries: 3看似合理，但若下游服务 SLA 是 99.95%，实际重试窗口需按指数退避公式30 * (2^3 - 1) = 210s计算，远超业务容忍阈值。门禁脚本必须加载真实配置，调用validate_config()方法执行动态校验，而非静态 JSON Schema 检查。

• 依赖可达性：Agent 启动时不能只检查 Redis 连接字符串语法，而要执行PING命令并验证响应时间 < 50ms、错误率 < 0.1%。我们曾因门禁只校验 Kafka broker 地址格式，未验证 SASL 认证，导致 Agent 在预发环境启动后立即陷入无限重连循环，日志刷屏“SASL authentication failed”。

• 接口契约合规性：Agent 对外暴露的/health端点，必须返回标准 JSON 结构{"status": "UP", "checks": [{"name": "redis", "status": "UP"}]}，且 HTTP 状态码严格为 200。某次升级 Spring Boot 版本后，/actuator/health默认返回 503（当任意子检查失败），而我们的负载均衡器只认 200，结果所有流量被切走——门禁必须用 curl 模拟 LB 行为，校验状态码与 body 结构双重合规。

提示：门禁脚本应独立于 Agent 主进程运行，在容器ENTRYPOINT中作为前置步骤。我们采用 Bash + Python 混合方案：Bash 负责环境探测（nc -z redis 6379），Python 负责深度校验（调用 Agent 内部HealthChecker类）。这样既保证轻量，又避免将门禁逻辑耦合进业务代码。

2.2 可观测性埋点不是“打日志”，而是构建 Agent 的“神经反射弧”

可观测性常被简化为“加几个 log.info()”，但这对 Agent 是灾难性的。Agent 的决策链是动态的：A 工具调用触发 B 工具，B 的输出决定是否调用 C，C 的失败又可能触发 D 的降级逻辑。传统日志无法表达这种因果关系。真正的可观测性埋点，必须建立三层反射弧：

• Trace 层（神经通路）：每个 Agent 执行周期必须生成唯一trace_id，并在所有 Tool 调用、LLM 请求、数据库查询中透传。我们强制使用 OpenTelemetry 的contextvars机制，而非传递trace_id参数——因为 Agent 的调用栈常跨越异步协程、线程池、消息队列，手动传递极易丢失。实测发现，当trace_id透传率低于 99.9%，分布式追踪的断链率会指数级上升，根本无法定位跨服务问题。

• Metrics 层（生理指标）：不只记录“调用成功/失败”，而要捕获决策质量。例如：agent_tool_call_duration_seconds_bucket{tool="search_api",le="1.0"}记录耗时分布；agent_llm_token_usage_total{model="gpt-4-turbo",role="assistant"}统计输出 Token；最关键的agent_decision_entropy_gauge——基于每轮 Action Space 的概率分布计算香农熵，熵值持续低于 0.3 说明 Agent 在机械复读，高于 2.5 则提示决策失控，这比单纯看错误率更能预警模型退化。

• Log 层（意识快照）：日志必须携带结构化上下文。我们禁止logger.info(f"User {user_id} got result {result}")，强制要求logger.info("Tool execution completed", extra={"user_id": user_id, "tool_name": "search_api", "result_length": len(result), "decision_entropy": entropy})。这样在 Loki 中可直接用{job="agent"} | json | user_id="U123" | __error__=""精准过滤，无需正则解析。

注意：埋点代码必须与业务逻辑解耦。我们采用装饰器模式：@instrument_tool("search_api")自动注入 trace、计时、错误捕获。这样新增 Tool 时，只需加一行装饰器，无需修改任何埋点逻辑。

2.3 AgentOps 不是运维，而是 Agent 的“操作系统内核”

AgentOps 常被等同于“用 K8s 部署 Agent”，这是认知降维。真正的 AgentOps，是为 Agent 构建一套运行时操作系统，它包含四个内核能力：

• 动态配置热加载：Agent 不能重启才能生效新 prompt。我们通过长连接监听配置中心（如 Apollo）的变更事件，当prompt_version更新时，自动重新编译 PromptTemplate 并替换内存中的prompt_engine实例。实测热加载耗时 < 80ms，期间 Agent 仍可处理请求，旧 prompt 与新 prompt 的请求被路由到不同实例，实现无感切换。

• 细粒度流量治理：不止是“全量/灰度”，而是支持按用户画像分流。例如：if user_tier == "premium": route_to_agent_v2 else: route_to_agent_v1。这要求网关层能解析 JWT 中的tier字段，并与 Agent 的 metadata 关联。门禁 Checklist 第 19 条“Metadata 注册校验”即检查 Agent 是否向注册中心上报了supported_user_tiers: ["free", "premium"]。

• 韧性策略编排：当 LLM 服务不可用时，Agent 应自动降级为规则引擎，而非直接报错。我们定义 YAML 格式的韧性策略：fallback_on_failure: {llm_timeout: "rule_engine", llm_unavailable: "cache_response"}，AgentOps 控制面实时下发策略，Agent 运行时按策略执行降级逻辑。

• 生命周期事件总线：Agent 启动、配置更新、异常熔断、优雅退出等事件，必须发布到统一事件总线（如 Kafka Topicagent-lifecycle-events）。运维平台订阅此 Topic，自动生成拓扑图、触发告警、驱动自动化修复——这才是 AgentOps 的价值闭环。

这三者缺一不可：门禁是准入门槛，确保上线的 Agent 具备基本健康体征；可观测性是感官系统，让运维者能“看见”Agent 的每一次心跳与思考；AgentOps 是中枢神经，赋予 Agent 动态适应环境的能力。脱离任一环节，Agent 都只是实验室玩具。

3. 核心 Checklist 实操解析：12 个卡点项的验证方法与代码实现

3.1 门禁卡点：健康检查端点必须通过 LB 探针模拟（Checklist #5）

这是上线被拒的最高频原因。K8s 的livenessProbe默认用 HTTP GET 访问/health，但很多 Agent 为省事直接返回{"status": "OK"}，而 LB 探针要求：

• HTTP 状态码必须为 200（非 200/503）
• 响应头Content-Type必须为application/json
• 响应体必须是合法 JSON，且包含status字段值为"UP"

验证脚本（health_check_validator.py）：

import requests import json import sys def validate_health_endpoint(url: str, timeout: float = 5.0): try: # 模拟 LB 探针：强制要求 200 状态码 resp = requests.get(f"{url.rstrip('/')}/health", timeout=timeout) # 检查状态码 if resp.status_code != 200: print(f"❌ 失败：HTTP 状态码 {resp.status_code}，期望 200") return False # 检查 Content-Type content_type = resp.headers.get('Content-Type', '') if 'application/json' not in content_type: print(f"❌ 失败：Content-Type '{content_type}'，期望 application/json") return False # 解析 JSON 并检查 status 字段 try: data = resp.json() except json.JSONDecodeError: print("❌ 失败：响应体不是合法 JSON") return False if not isinstance(data, dict) or data.get('status') != 'UP': print(f"❌ 失败：status 字段值为 '{data.get('status')}'，期望 'UP'") return False print("✅ 通过：健康检查端点符合 LB 探针要求") return True except requests.exceptions.Timeout: print(f"❌ 失败：请求超时（>{timeout}s）") return False except requests.exceptions.ConnectionError: print("❌ 失败：无法连接到服务") return False except Exception as e: print(f"❌ 失败：未知错误 {e}") return False if __name__ == "__main__": if len(sys.argv) < 2: print("用法: python health_check_validator.py <agent_url>") sys.exit(1) url = sys.argv[1] success = validate_health_endpoint(url) sys.exit(0 if success else 1)

实操心得：我们曾因 Flask 默认的jsonify({"status": "OK"})返回 200 OK，但status值是"OK"而非"UP"，导致 K8s 重启 Agent 数十次。现在门禁脚本强制校验status == "UP"，并在 CI 中作为必过项。

3.2 门禁卡点：敏感配置必须从环境变量注入（Checklist #7）

硬编码api_key: "sk-xxx"是安全红线。但更隐蔽的问题是：配置文件中写api_key: ${API_KEY}，却未在容器启动时注入API_KEY环境变量，导致 Agent 启动时报KeyError。门禁必须验证环境变量是否存在且非空。

验证脚本（env_var_validator.py）：

import os import sys import json def validate_env_vars(required_vars: list): missing = [] empty = [] for var in required_vars: value = os.getenv(var) if value is None: missing.append(var) elif not value.strip(): empty.append(var) if missing: print(f"❌ 失败：缺失环境变量 {missing}") return False if empty: print(f"❌ 失败：环境变量为空 {empty}") return False print(f"✅ 通过：必需环境变量 {required_vars} 均存在且非空") return True # 从配置文件提取必需变量（示例） REQUIRED_VARS = ["REDIS_URL", "LLM_API_KEY", "OTEL_EXPORTER_OTLP_ENDPOINT"] if __name__ == "__main__": success = validate_env_vars(REQUIRED_VARS) sys.exit(0 if success else 1)

注意事项：不要只校验变量名，要校验值的有效性。例如REDIS_URL必须匹配redis://[:password@]host:port/db正则；LLM_API_KEY长度应 > 20 字符。我们在门禁中增加validate_redis_url()函数，用redis.from_url()尝试连接，失败则报错。

3.3 可观测性卡点：Trace Context 必须 100% 透传（Checklist #14）

Agent 调用 Tool 时，若trace_id断裂，整个调用链就失效。我们要求：从 Agent 入口（如/ask）开始，到每个 Tool 的execute()方法结束，trace_id必须一致。

验证方法（trace_context_tester.py）：

import time from opentelemetry import trace from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import SimpleSpanProcessor from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter # 初始化内存导出器用于测试 exporter = InMemorySpanExporter() provider = TracerProvider() provider.add_span_processor(SimpleSpanProcessor(exporter)) trace.set_tracer_provider(provider) def test_trace_propagation(): tracer = trace.get_tracer(__name__) with tracer.start_as_current_span("agent_entry") as span: entry_trace_id = span.context.trace_id # 模拟调用 Tool A with tracer.start_as_current_span("tool_a_execute") as tool_span: tool_trace_id = tool_span.context.trace_id if tool_trace_id != entry_trace_id: print(f"❌ 失败：Tool A trace_id {tool_trace_id} != 入口 {entry_trace_id}") return False # 模拟调用 Tool B（跨线程） import threading def call_tool_b(): nonlocal entry_trace_id with tracer.start_as_current_span("tool_b_execute") as b_span: b_trace_id = b_span.context.trace_id if b_trace_id != entry_trace_id: print(f"❌ 失败：Tool B trace_id {b_trace_id} != 入口 {entry_trace_id}") return False thread = threading.Thread(target=call_tool_b) thread.start() thread.join() print("✅ 通过：Trace Context 在同步/异步调用中均正确透传") return True if __name__ == "__main__": success = test_trace_propagation() sys.exit(0 if success else 1)

关键技巧：使用opentelemetry-context库的attach()和detach()确保跨线程 context 传递。在 Tool 的execute()方法开头，必须调用context.attach(context)获取父 span，否则新线程会生成新 trace_id。

3.4 可观测性卡点：LLM Token 使用量必须精确统计（Checklist #17）

很多 Agent 用len(prompt)估算 Token，但不同模型 tokenizer 差异巨大（如 GPT-4 用 tiktoken，Claude 用 anthropic-tokens）。门禁必须验证 Token 统计是否调用真实 tokenizer。

验证脚本（token_counter_validator.py）：

import tiktoken from opentelemetry import metrics # 初始化指标 meter = metrics.get_meter(__name__) token_counter = meter.create_counter( "llm.token_usage", description="Number of tokens used in LLM requests", unit="1" ) def validate_token_counting(): # 使用真实 tokenizer enc = tiktoken.encoding_for_model("gpt-4-turbo") test_prompt = "Hello, world! This is a test prompt." expected_tokens = len(enc.encode(test_prompt)) # 模拟 Agent 的 token 统计逻辑 # ❌ 错误：len(test_prompt) -> 42 # ✅ 正确：enc.encode(test_prompt) -> 11 actual_tokens = len(enc.encode(test_prompt)) if actual_tokens != expected_tokens: print(f"❌ 失败：Token 统计错误，期望 {expected_tokens}，得到 {actual_tokens}") return False # 验证指标是否记录 try: token_counter.add(actual_tokens, {"model": "gpt-4-turbo", "role": "user"}) print("✅ 通过：Token 统计准确且指标已记录") return True except Exception as e: print(f"❌ 失败：指标记录失败 {e}") return False if __name__ == "__main__": success = validate_token_counting() sys.exit(0 if success else 1)

避坑指南：不要信任第三方库的count_tokens()方法，务必用目标模型对应的官方 tokenizer。我们曾因使用通用len(prompt)导致 Token 预估偏差 300%，引发配额超限告警。

3.5 AgentOps 卡点：配置热加载必须零停机（Checklist #22）

Agent 接收新配置后，必须在 < 100ms 内完成加载，且期间不拒绝请求。

验证脚本（config_hot_reload_tester.py）：

import time import threading import json from unittest.mock import patch # 模拟 Agent 的配置管理器 class ConfigManager: def __init__(self): self.config = {"prompt_version": "v1", "temperature": 0.7} self.load_time = 0 def load_config(self, new_config: dict): start = time.time() # 模拟加载耗时 time.sleep(0.05) # 50ms self.config.update(new_config) self.load_time = time.time() - start def get_config(self): return self.config.copy() def test_hot_reload(): manager = ConfigManager() # 启动一个持续请求线程 stop_event = threading.Event() request_count = [0] def request_worker(): while not stop_event.is_set(): config = manager.get_config() request_count[0] += 1 time.sleep(0.01) # 每秒 100 次请求 worker = threading.Thread(target=request_worker) worker.start() # 触发热加载 time.sleep(0.1) start_reload = time.time() manager.load_config({"prompt_version": "v2", "temperature": 0.5}) reload_time = time.time() - start_reload # 等待一段时间后停止 time.sleep(0.2) stop_event.set() worker.join() if reload_time > 0.1: print(f"❌ 失败：热加载耗时 {reload_time:.3f}s，超过 100ms 限制") return False if request_count[0] < 10: # 确保有请求发生 print("❌ 失败：未检测到请求，测试无效") return False print(f"✅ 通过：热加载耗时 {reload_time:.3f}s，期间处理 {request_count[0]} 次请求") return True if __name__ == "__main__": success = test_hot_reload() sys.exit(0 if success else 1)

实操心得：热加载必须用读写锁（threading.RLock）保护配置对象，读操作不加锁（高频），写操作加锁（低频）。我们曾因用threading.Lock导致读请求阻塞，P99 延迟飙升至 2s。

3.6 AgentOps 卡点：Agent 必须向注册中心上报 Metadata（Checklist #19）

AgentOps 平台需要知道每个 Agent 实例支持哪些用户分层、使用什么模型、具备什么能力，才能做精准路由。门禁必须验证注册时是否上报完整 metadata。

验证脚本（metadata_validator.py）：

import json import requests import sys def validate_metadata_registration(service_url: str, expected_metadata: dict): try: # 查询注册中心（模拟 Consul API） # 实际中可能是 GET http://consul:8500/v1/health/service/{service_name} # 这里简化为检查 Agent 的 /metadata 端点 resp = requests.get(f"{service_url.rstrip('/')}/metadata", timeout=5) if resp.status_code != 200: print(f"❌ 失败：/metadata 端点返回 {resp.status_code}") return False metadata = resp.json() # 检查必需字段 for key, expected_value in expected_metadata.items(): if key not in metadata: print(f"❌ 失败：缺失 metadata 字段 '{key}'") return False if metadata[key] != expected_value: print(f"❌ 失败：metadata['{key}'] = {metadata[key]}，期望 {expected_value}") return False print("✅ 通过：Agent 已正确上报必需 metadata") return True except Exception as e: print(f"❌ 失败：验证 metadata 时出错 {e}") return False EXPECTED_METADATA = { "supported_user_tiers": ["free", "premium"], "llm_models": ["gpt-4-turbo", "claude-3-haiku"], "capabilities": ["search", "summarize", "translate"] } if __name__ == "__main__": if len(sys.argv) < 2: print("用法: python metadata_validator.py <agent_url>") sys.exit(1) url = sys.argv[1] success = validate_metadata_registration(url, EXPECTED_METADATA) sys.exit(0 if success else 1)

关键细节：Metadata 必须包含last_updated_timestamp字段，AgentOps 平台据此判断实例是否存活。我们要求该时间戳每 30 秒更新一次，门禁脚本会检查其是否在 60 秒内更新。

4. 完整 Checklist 执行流程与自动化集成

4.1 27 项 Checklist 的分类与执行顺序

我们将 27 项 Checklist 按执行阶段分为四类，形成不可逆的流水线：

执行顺序不可颠倒：例如 #14（Trace 透传）必须在 #19（Metadata 上报）之前验证，因为 Metadata 上报本身就是一个 Trace Span，若透传失败，上报事件就无法关联到 Agent 启动链路。

4.2 自动化集成：CI/CD 流水线中的 Checklist 执行

我们使用 GitLab CI 将 Checklist 集成到标准流水线中，关键 stage 配置如下：

stages: - validate - build - test - deploy validate-checklist: stage: validate image: python:3.11-slim before_script: - pip install requests opentelemetry-api opentelemetry-sdk tiktoken script: - python health_check_validator.py $AGENT_URL - python env_var_validator.py - python trace_context_tester.py - python token_counter_validator.py allow_failure: false rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event" build-image: stage: build image: docker:24.0.7 services: - docker:24.0.7-dind script: - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG . - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG rules: - if: $CI_COMMIT_TAG deploy-to-staging: stage: deploy image: bitnami/kubectl:1.28 script: - kubectl apply -f k8s/staging/ - sleep 30 # 等待 Pod 启动 - python metadata_validator.py $STAGING_URL rules: - if: $CI_COMMIT_TAG

关键设计：

• validate-checklist仅在 MR（Merge Request）时运行，避免污染主干构建速度；
• sleep 30后执行metadata_validator.py，确保 Pod 已 Ready；
• 所有验证脚本返回非 0 码时，CI 自动失败，阻止合并。

4.3 可运行代码包结构与使用指南

本次分享的代码包已开源，结构清晰，开箱即用：

agent-checklist-kit/ ├── README.md # 快速入门与原理说明 ├── checklist/ # 27 项 Checklist 详细文档（Markdown） │ ├── 01_pre_build.md │ ├── 05_post_build.md │ └── ... ├── scripts/ # 验证脚本（本文所有代码均在此） │ ├── health_check_validator.py │ ├── env_var_validator.py │ ├── trace_context_tester.py │ ├── token_counter_validator.py │ ├── config_hot_reload_tester.py │ └── metadata_validator.py ├── examples/ # 各框架 Agent 的集成示例 │ ├── langchain-agent/ # LangChain Agent 的 instrumentor 装饰器 │ ├── llama-index-agent/ # LlamaIndex Agent 的 trace hook │ └── custom-agent/ # 纯 Python Agent 的最小化实现 └── docker-compose.yml # 本地一键启动测试环境（含 mock Redis、Mock LLM）

本地快速验证步骤：

1. git clone https://github.com/xxx/agent-checklist-kit.git
2. cd agent-checklist-kit && docker-compose up -d（启动 mock 服务）
3. cd scripts && python health_check_validator.py http://localhost:8000
4. 查看输出，绿色 ✅ 即表示通过

注意事项：所有脚本均设计为“无副作用”，不修改任何配置、不重启服务、不产生脏数据。它们只做读取与验证，符合门禁“只检查、不干预”的原则。

5. 常见问题排查与独家避坑经验

5.1 问题速查表：27 项中最高频的 8 个失败项

5.2 独家避坑经验：那些文档不会写的细节

坑一：OpenTelemetry 的contextvars在异步环境中失效
现象：FastAPI Agent 中，async def ask()内的trace_id在await tool.execute()后丢失。
原因：contextvars在 asyncio 任务切换时不自动继承。
解决方案：使用opentelemetry-instrumentation-fastapi的FastAPIInstrumentor().instrument()，它会自动 patchasync函数。手动 patch 代码：

from opentelemetry.context import attach, detach, Context from opentelemetry import trace async def execute_with_context(self, *args, **kwargs): ctx = trace.get_current_span().get_span_context() token = attach(Context(trace_context=ctx)) # 显式附加 try: return await self._original_execute(*args, **kwargs) finally: detach(token)

坑二：K8s Readiness Probe 与 Liveness Probe 的语义混淆
现象：Agent 启动慢，Readiness Probe 失败导致流量被切走，但 Liveness Probe 未失败，Pod 不重启。
真相：Readiness 应检查“能否接收流量”（如依赖服务就绪），Liveness 应检查“是否存活”（如内存泄漏）。
正确配置：

readinessProbe: httpGet: path: /health/ready port: 8000 initialDelaySeconds: 30 # 给足启动时间 livenessProbe: httpGet: path: /health/live port: 8000 initialDelaySeconds: 60

/health/ready检查 Redis、LLM 连接；/health/live只检查进程是否僵死。

坑三：AgentOps 的“配置热加载”被误认为“动态 Prompt”
现象：运营同学修改 prompt 后，Agent 未生效，以为热加载失败。
根因：Prompt 变更需触发PromptTemplate重新编译，而不仅是更新字符串。
正确做法：

class PromptEngine: def __init__(self): self._template = None self._compiled = None def load_prompt(self, template_str: str): self._template = template_str # 必须重新编译！ self._compiled = jinja2.Template(template_str) # 或其他模板引擎

门禁 Checklist #22 必须验证self._compiled是否为新实例，而非仅检查字符串是否更新。

坑四：可观测性埋点导致性能下降 300%
现象：开启 OpenTelemetry 后，Agent P99 延迟从