第 6 章 · 可观测性与会话清理

本章目标：理解为什么可观测性必须内置于 harness，掌握会话清理的最佳实践，确保每次会话留下干净状态。

6.1 黑盒的危险

智能体在运行，你看得见它在"思考"，但看不见它做了什么决策、调用了哪些工具、读了哪些文件。这种黑盒状态是危险的：

• 你不知道它是否偏离了路径
• 你不知道它是否卡在某个循环
• 你不知道它是否产生了有害副作用
• 出问题后你无法诊断

OpenAI 和 Anthropic 都强调：可观测性不应是事后添加的，必须内置于 harness 设计。

6.2 可观测性的五个层次

层次 1：执行日志

记录智能体的每一步操作：

## 2024-01-15 10:30:00
[START] 任务：添加用户偏好 API
[READ]  src/models/user.py
[READ]  src/api/routes.py  
[ACTION] 创建 src/api/preferences.py
[WRITE]  src/api/preferences.py (234 lines)
[TEST]   pytest tests/api/test_preferences.py
[RESULT]  5/5 passed
[COMMIT] abc1234 feat: add preferences API

层次 2：工具调用追踪

记录所有工具调用的输入输出：

{
  "tool": "read",
  "args": {"path": "src/main.py"},
  "output_length": 15234,
  "timestamp": "2024-01-15T10:30:05Z"
}

层次 3：资源使用监控

追踪 token 消耗、运行时间、API 调用次数：

# 实时监控
$ loop status
Token usage: 45,231 / 128,000 (35%)
Runtime: 12m 34s
API calls: 23
Estimated cost: $0.87

层次 4：异常检测

自动检测异常模式：

• 重复工具调用（可能循环）
• 长时间无输出（可能卡住）
• Token 使用异常（可能无限循环）
• 失败率突增

层次 5：事后分析

会话结束后生成报告：

## Session Report: 2024-01-15

**任务**: 添加用户偏好 API
**状态**: 完成 ✅

**统计**:
- Token 使用: 45,231 / 128,000 (35%)
- 运行时间: 12m 34s
- 工具调用: 23 次
- 文件变更: 5 个文件，+342/-12 lines
- 测试: 5/5 passed

**关键决策**:
1. 选择 FastAPI 路由而非类视图
2. 使用 Pydantic v2 model 而非 dict
3. 添加分页支持而非返回全部

**建议改进**:
- 可在第一次调用时加载 schema，节省后续 token

6.3 会话清理：留下干净状态

每个会话结束时必须做清理，确保下一个会话能无缝接续：

清理清单

## 会话结束检查
- [ ] 更新 PROGRESS.md
- [ ] 运行 make check 确认状态一致
- [ ] 提交所有完成的工作
- [ ] 清理临时文件
- [ ] 记录任何未解决的 risk/blocker
- [ ] 仓库处于可重启状态

清理脚本

#!/usr/bin/env bash
# cleanup.sh - 会话结束清理

echo "==> 检查测试状态..."
pytest tests/ --tb=short || echo "警告: 有测试失败"

echo "==> 检查类型..."
mypy src/ --strict || echo "警告: 类型检查失败"

echo "==> 清理临时文件..."
find . -name "*.tmp" -delete
find . -name "__pycache__" -exec rm -rf {} + 2>/dev/null

echo "==> 更新进度..."
python scripts/update_progress.py

echo "==> 完成清理"

6.4 失败后的清理

当会话因失败中断时，清理尤其重要：

## 失败清理流程
1. 保存当前工作状态到 FAILSAFE.md
2. 记录失败点和错误信息
3. 回滚可疑的未验证变更
4. 运行基线验证确认仓库状态
5. 更新 PROGRESS.md 标记受阻任务

6.5 可观测性与隐私的平衡

注意：可观测性不应泄露敏感信息。以下信息应脱敏：

• 用户数据（姓名、邮箱、token）
• API keys
• 商业机密
• 个人身份信息

使用日志过滤或采样策略：

# 敏感信息过滤
MASKED_KEYS = ['password', 'token', 'api_key', 'secret']

def sanitize_log(log_entry):
    for key in MASKED_KEYS:
        log_entry = re.sub(f'{key}[:\s]*\S+', f'{key}:***', log_entry)
    return log_entry

6.6 本章小结

• 可观测性必须内置于 harness，不应事后添加
• 五层可观测性：日志、工具追踪、资源监控、异常检测、事后分析
• 每次会话结束必须清理，留下干净状态
• 失败后要保存 work-in-progress 并回滚可疑变更
• 平衡可观测性与隐私，脱敏敏感信息

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. 可观测性的核心价值是什么？

2. 会话清理的首要目的是？

3. 失败后最重要的清理步骤是？

4. 可观测性与隐私冲突时，正确做法是？

🛠️ 动手实践

1. 为现有项目添加执行日志功能，记录智能体的关键操作。
2. 创建会话清理脚本 cleanup.sh，包含测试运行、临时文件清理、进度更新。
3. 实现失败保护：在 AGENTS.md 中添加失败清理流程说明。

下一章：大模型与提示工程概述