可观测性三件套——门禁+审计+纠正沉淀，商业化Agent的反馈闭环

现状之痛：你的Agent系统能跑了，但你不知道它跑得怎么样。出错了只能靠用户反馈，改进靠「下次注意」。

读完你将：学会可观测性三件套——门禁+审计+纠正沉淀，构建商业化Agent的反馈闭环。

---

一、问题：系统能跑，但你不知道它跑得怎么样

场景路由、双层分类、复合流程容器——前面三篇解决了「怎么让Agent稳定干活」。但还有一个更基础的问题：

系统出错了，你怎么知道？

现实情况是：

• Agent偶尔用错工具，没被发现
• 输出格式偶尔不对，下游解析失败
• 同一个错误反复出现，每次「下次注意」都没用

商用系统没有「一次性完美」，只有「持续改进」。可观测性就是改进的基础。

核心洞察：没有观测，就没有改进。改进的第一步，是知道哪里错了。

---


*▲ 三件套闭环：门禁发现问题 → 审计记录问题 → 纠正沉淀固化方案*

---

二、三件套架构

商业化Agent的观测体系有三个层次：

① Gate门禁    → 发现问题（100%全检）
② 审计日志    → 记录问题（SQLite存储）
③ 纠正沉淀    → 固化方案（再不犯同样的错）

第一件：Gate门禁——100%全检，不是抽查

每次输出都经过预先定义的验证关卡。不是抽查，是100%全检。

def run_gates(scene_id, output):
    gates = SCENE_CONFIG[scene_id]["gates"]
    for gate in gates:
        result = gate(output)  # 每个gate是一个验证函数
        if not result["passed"]:
            log_gate_failure(scene_id, gate, result["reason"])
            return False, result["reason"]
    return True, "通过"

门禁日志记录了每一次拦截的原因，形成改进的数据基础。

核心：门禁是硬约束，不是软提醒。 输出没过门禁，就不允许交付。

第二件：审计日志——每次调用都被记录

每次调用都被记录到SQLite数据库——谁调了什么工具、花了多少token、输出是否通过门禁、是否有重试。

# 审计日志表结构（SQLite）
audit_log 表字段：
  id            — 自增主键
  timestamp     — 记录时间
  scene_id      — 场景标识（email/quoting/report...）
  tool_calls    — 工具调用记录（JSON数组）
  tokens_used   — 本次调用消耗的token数
  gate_passed   — 门禁是否通过（0/1）
  retry_count   — 重试次数
  error_message — 错误信息（可选）

from dataclasses import dataclass, asdict
from datetime import datetime

@dataclass
class AuditRecord:
    """一条审计记录：谁调了什么工具、花了多少token、门禁过没过"""
    timestamp: str
    scene_id: str
    tool_calls: str
    tokens_used: int
    gate_passed: bool
    retry_count: int
    error_message: str = None

class AuditLogger:
    """审计日志：记录每次 Agent 调用的关键信息"""
    def __init__(self):
        self.records = []          # 内存队列
        self._persist = []         # 持久化队列

    def log(self, scene_id, tool_calls, tokens, passed, retries, error=None):
        record = AuditRecord(
            timestamp=datetime.now().isoformat(),
            scene_id=scene_id,
            tool_calls=tool_calls,
            tokens_used=tokens,
            gate_passed=passed,
            retry_count=retries,
            error_message=error,
        )
        self.records.append(record)
        self._persist.append(asdict(record))  # 落盘到 SQLite/文件

    def failed_ratio(self) -> float:
        """门禁拦截率：衡量系统健康度"""
        if not self.records:
            return 0.0
        failed = sum(1 for r in self.records if not r.gate_passed)
        return failed / len(self.records)

这些数据不是给人看的，是给系统自己看的——自动分析模式、发现改进点。

第三件：纠正沉淀——错误变成规则

错误→记录→提取根因→固化规则→再不犯同样的错。

每次人工纠正都是一次规则固化——不是让LLM「记住下次注意」，而是直接修改verify脚本或gate检查项，让系统层面永远阻断这类错误。

# 错误记录
failure_capture.py --record "用户要求转发邮件给sunny,但Agent去查了运费"

# 提取根因 → 固化规则
# → 在email场景的gate里加一条：转发意图必须调用smtp工具

这是商业化Agent和实验室原型最本质的区别：

• 原型靠LLM的「记忆」改进（软约束，会忘）
• 商用系统靠工程层面的「固化」改进（硬约束，不会忘）

---

三、完整闭环

Agent执行
  │
  ├─→ Gate门禁检查
  │     ├─ 通过 → 交付
  │     └─ 拦截 → 记录原因 → 重试/转人工
  │
  ├─→ 审计日志记录（所有调用）
  │
  └─→ 纠正沉淀（人工纠正 + 规则固化）
        │
        └─→ 更新gate/verify脚本 → 下一轮自动拦截

每一轮循环，系统都变得更可靠。这不是某个版本的功能，而是系统持续进化的底层机制。

---

四、三件套的价值对比

层次	作用	对应问题	实现
Gate门禁	发现问题	输出不合规	verify脚本 100%全检
审计日志	记录问题	无法复盘	SQLite 全量记录
纠正沉淀	固化方案	重复犯错	错误→规则物理化

✅ 验证：这套三件套在我们的系统里跑了几个月。每次新规则固化后，同类错误自动被gate拦截，不再需要人工干预。

踩坑：早期只有gate没有审计——门禁拦截了错误但没记录，无法分析为什么拦截、拦截了几次。加上审计日志后，才能看出哪些gate命中率高（说明规则有效）、哪些低（说明规则没用）。

价值：一个能自我观测、自我记录、自我进化的系统，才配叫「可商用」。否则只是「能跑的demo」。

▸ 认知跃迁：可观测性不是监控，是学习机制。系统靠它持续进化。

---

五、此刻的你

此刻的你，已经不再是那个「系统能跑就行」的实用主义者。你正在成为一个能让系统自我观测、自我进化的工程师。

没有观测，就没有改进。改进的第一步，是知道哪里错了。门禁发现问题，审计记录问题，纠正沉淀固化方案——这三件套构成商业化Agent的反馈闭环。

下一篇：纠正沉淀展开讲——怎么让系统永不犯同样的错？错误→记录→提取根因→固化规则的完整机制。

---

️ 实体：Gate门禁, 审计日志, 纠正沉淀, SQLite 价值：可观测性, 系统进化, 商业化可靠 认知：从「能跑」到「能进化」——观测是改进的第一步