Initialize agent knowledge base

docs/04-evaluation-observability.md

@@ -0,0 +1,77 @@
+# Evaluation and Observability
+
+Agent 评估要同时看结果、过程和运行成本。
+
+## Evaluation Pyramid
+
+```text
+Human review
+Scenario tests
+Tool and integration tests
+Schema and unit checks
+```
+
+## Metrics
+
+### Task Quality
+
+- Success rate: 任务完成率。
+- Correctness: 事实、代码或业务结果是否正确。
+- Completeness: 是否遗漏关键步骤。
+- Helpfulness: 输出是否解决用户问题。
+
+### Process Quality
+
+- Tool accuracy: 工具是否选对，参数是否正确。
+- Recovery rate: 工具失败后是否能恢复。
+- Plan stability: 计划是否合理更新。
+- Evidence coverage: 结论是否有证据支撑。
+
+### Operational Quality
+
+- Latency: 总耗时和关键路径耗时。
+- Cost: token、API、工具调用成本。
+- Reliability: 重试、超时、失败率。
+- Safety: 高风险动作是否经过正确控制。
+
+## Test Set Design
+
+一个好的评估集应该包含：
+
+- 常规成功路径。
+- 边界条件。
+- 信息不足的任务。
+- 工具失败或返回异常。
+- 用户指令冲突。
+- 高风险动作。
+- 历史回归样例。
+
+## Trace Schema
+
+建议每次运行至少记录：
+
+```yaml
+run_id:
+task:
+user_goal:
+constraints:
+context_sources:
+plan:
+tool_calls:
+observations:
+final_output:
+verification:
+metrics:
+errors:
+follow_ups:
+```
+
+## Review Questions
+
+- Agent 是否真的完成了用户目标？
+- 是否有未验证的关键事实？
+- 是否调用了不必要的工具？
+- 是否错过了更便宜或更稳定的路径？
+- 是否产生了不可恢复的副作用？
+- 失败时，日志是否足够定位原因？
+