Agent 可观测性 - 打开黑箱

安装内容

安装步骤

步骤 1 — 复制文件

WORKSPACE="${OPENCLAW_WORKSPACE:-$(pwd)}"

cp references/throughput-dashboard.js  "$WORKSPACE/scripts/"
cp references/decision-audit.js        "$WORKSPACE/lib/"
cp references/failure-tracer.js        "$WORKSPACE/lib/"
cp references/drift-guard-auto.js      "$WORKSPACE/scripts/"

或手动从本技能的 references/ 目录中复制每个文件。

步骤 2 — 添加到心跳/每周定时任务

在你的心跳脚本或每周 cron 任务中添加：

node "$WORKSPACE/scripts/throughput-dashboard.js" "$WORKSPACE"
node "$WORKSPACE/scripts/drift-guard-auto.js" "$WORKSPACE"

步骤 3 — 将 decision-audit 集成到高风险决策中

const { logDecision } = require('./lib/decision-audit');

logDecision({
  task_type: 'code_generation',
  decision: 'spawn CoderAgent',
  reasoning_summary: '多文件编辑阻塞聊天 >5秒',
  session_channel: 'discord'  // 可选
}, workspaceRoot);

步骤 4 — 将 failure-tracer 集成到质量验证中（可选）

当在评估子代理输出后调用时，failure-tracer 会自动触发：

const { captureFailureTrace } = require('./lib/failure-tracer');

// 在评估任何子代理输出后调用
if (qualityScore < 7) {
  captureFailureTrace('AgentLabel-task', qualityScore, agentOutput, workspaceRoot);
}

数据读取方式

查询示例

# 最近的决策记录
tail -20 memory/decisions-audit.jsonl | jq .

# 所有失败追踪记录
ls memory/traces/

# 最新的偏移报告
cat memory/drift-reports/$(ls memory/drift-reports/ | tail -1)

工具说明

throughput-dashboard.js

聚合每周指标：任务分发数量、子代理启动次数、估算成本、质量比率、路由分布。从 session-metrics.js（如已安装）和 drift-guard-auto.js 读取数据。若数据源缺失，会降级处理——每个模块独立运行。

decision-audit.js

在 memory/decisions-audit.jsonl 中写入追加式 JSONL 日志。每条记录包含：id, ts, task_type, decision, reasoning_summary, outcome, session_channel。使用 updateOutcome(id, 'success', workspaceRoot) 在决策完成后补全结果状态。

failure-tracer.js

当质量评分低于 7 时触发。将结构化 JSON 写入 memory/traces/。每条追踪包含：工具调用序列提示、输出片段、推断出的失败原因。用于事后分析子代理表现不佳的原因。

drift-guard-auto.js

对近期代理输出进行行为规则评分（如奉承、社交缓冲、未被要求的解释、幻觉倾向）。若已安装 INTENT.md，则读取其中自定义标准。每周生成报告并写入 memory/drift-reports/。

参考资料

• references/throughput-dashboard.js — 完整脚本实现
• references/decision-audit.js — 完整库实现
• references/failure-tracer.js — 完整库实现
• references/drift-guard-auto.js — 完整脚本实现