feat: 重构 AuditView 支持规则/技能分类，新增 Agent 开发文档

2026-05-11 01:53:30 +00:00
parent 0c6ac50b31
commit f738b6cdd4
33 changed files with 5853 additions and 204 deletions
--- a/plan/09_observability_and_trace.md
+++ b/plan/09_observability_and_trace.md
@@ -0,0 +1,186 @@
+# 可观测性与 Agent Run Trace
+
+## 1. 目标
+
+Agent 系统必须可追踪、可回放、可解释。
+
+财务系统中尤其需要回答：
+
+- 为什么 Agent 得出这个结论？
+- 用了哪个模型？
+- 用了哪个规则版本？
+- 调用了哪些 MCP？
+- 查了哪些数据？
+- 谁确认了动作？
+- 失败在哪里？
+
+## 2. Agent Run Trace
+
+每次 Agent 运行都生成一个 run_id。
+
+建议结构：
+
+```json
+{
+  "run_id": "",
+  "source": "user_message",
+  "agent": "user_agent",
+  "user_id": "emp_001",
+  "raw_input": "",
+  "ontology_json": {},
+  "route_decision": {},
+  "permission_result": {},
+  "tool_calls": [],
+  "final_output": "",
+  "status": "success",
+  "started_at": "",
+  "finished_at": ""
+}
+```
+
+## 3. 需要记录的版本
+
+每次运行都要记录：
+
+```text
+ontology_schema_version
+semantic_parser_prompt_version
+model_name
+model_version
+rule_version
+skill_version
+mcp_version
+knowledge_snapshot_version
+orchestrator_version
+```
+
+原因：
+
+用户可能问：
+
+```text
+为什么昨天和今天的结论不一样？
+```
+
+只有记录版本，才能解释。
+
+## 4. Tool Call Trace
+
+每个工具调用都记录：
+
+```json
+{
+  "tool_call_id": "",
+  "run_id": "",
+  "tool_type": "mcp",
+  "tool_name": "invoice_verify",
+  "request_json": {},
+  "response_json": {},
+  "status": "success",
+  "duration_ms": 820,
+  "error_message": ""
+}
+```
+
+敏感字段应脱敏。
+
+## 5. 运行状态
+
+建议枚举：
+
+```text
+pending
+running
+success
+partial_success
+failed
+cancelled
+waiting_confirmation
+```
+
+## 6. Hermes 可观测性
+
+Hermes 任务需要额外记录：
+
+```text
+task_code
+schedule_time
+data_snapshot_id
+records_scanned
+rules_executed
+mcp_calls
+risk_items_generated
+knowledge_candidates_generated
+retry_count
+```
+
+示例：
+
+```json
+{
+  "task_code": "daily_risk_scan",
+  "records_scanned": 2146,
+  "rules_executed": 8,
+  "mcp_calls": 436,
+  "risk_items_generated": 19,
+  "status": "success"
+}
+```
+
+## 7. User Agent 可观测性
+
+User Agent 需要额外记录：
+
+```text
+conversation_id
+page_context
+user_confirmation
+draft_created
+business_object_id
+```
+
+## 8. 前端审计视图
+
+建议后续增加“Agent 运行记录”页面。
+
+展示：
+
+- 运行时间。
+- Agent 类型。
+- 用户或任务。
+- 语义解析结果。
+- 调用工具。
+- 运行状态。
+- 耗时。
+- 错误。
+
+详情页展示：
+
+- 原始输入。
+- 本体 JSON。
+- 路由决策。
+- 工具调用链。
+- 最终输出。
+
+## 9. 告警
+
+需要告警的情况：
+
+- Hermes 任务连续失败。
+- MCP 健康检查失败。
+- 语义解析低置信度比例过高。
+- 某规则误报率过高。
+- Agent 调用耗时异常。
+- 权限拒绝次数异常。
+
+## 10. 开发步骤
+
+```text
+Step 1: 增加 agent_runs 表
+Step 2: 增加 agent_tool_calls 表
+Step 3: Orchestrator 每次执行创建 run_id
+Step 4: 工具网关记录 tool call
+Step 5: 前端增加运行记录页面
+Step 6: 增加异常告警规则
+```
+