feat: 扩展风险规则体系、审批动态路由与预算中心列表化改造

- 新增 25+ 条风险规则（预算/报销/申请/通用类），完善风险规则模拟与反馈发布机制 - 引入费用审批动态路由、平台风险分级、预审与风险阶段管理 - 预算中心列表化改造，优化票据夹仪表盘与数字员工工作看板 - 新增 Hermes 风险线索收集器、Agent 链路追踪中心 - 扩展数字员工能力库（18 个领域 Skill）与交通费用自动预估 - 完善报销申请快速预览、权限控制与前端测试覆盖
2026-06-01 17:07:14 +08:00
parent 7989f3a159
commit 92444e7eae
285 changed files with 25075 additions and 2986 deletions
--- a/document/development/Agent链路追踪中心/CONCEPT.md
+++ b/document/development/Agent链路追踪中心/CONCEPT.md
@@ -0,0 +1,132 @@
+# Agent链路追踪中心 概念文档
+
+## 功能一句话
+
+为 Orchestrator 全链路运行提供统一 trace 采集、查询和前端回放入口，让管理员能按 `run_id` 或 `conversation_id` 还原一次 Agent 对话从意图识别到最终回复的全过程。
+
+## 背景与问题
+
+- 当前现状：系统已有 `agent_runs`、`agent_tool_calls`、`semantic_parse_logs` 和对话消息，但它们分散在运行记录、工具调用、语义解析与系统日志中。
+- 用户痛点：线上 Agent 回答异常时，只能看局部日志或 Hermes 工作记录，难以判断问题出在意图路由、知识检索、规则引擎、数字员工任务还是回复生成。
+- 业务影响：Agent 链路越长，排障成本越高；没有可重放视图会影响交付、演示和运维可信度。
+
+## 目标与非目标
+
+### 目标
+
+- [G1] 后端沉淀统一的 Agent trace 事件模型，按运行顺序记录关键阶段输入、输出、状态、耗时和错误。
+- [G2] 提供 trace 查询接口，支持按 `run_id` 查看单次运行，按 `conversation_id` 查看多轮会话链路。
+- [G3] 前端新增 Agent Trace Center 入口，展示运行时间线、工具调用、语义解析、路由上下文和最终回复。
+- [G4] 保留现有 Agent Run / ToolCall 数据结构，避免破坏数字员工工作记录和系统日志页面。
+
+### 非目标
+
+- [NG1] 本轮不做重新执行真实业务动作的“调试重跑”，只做历史重放。
+- [NG2] 本轮不接入 OpenTelemetry、Jaeger 等外部分布式追踪系统。
+- [NG3] 本轮不改造总账、预算、报销审批等业务语义。
+- [NG4] 本轮不做跨服务链路采样策略和海量归档策略。
+
+## 用户与场景
+
+- 目标用户：系统管理员、财务系统运维、Agent 能力开发者、实施顾问。
+- 使用入口：系统日志详情、数字员工工作记录、报销助手消息中的 `run_id`、新增 Trace Center 页面。
+- 核心场景：
+  - 管理员打开某次异常回复，查看每一步输入输出和耗时。
+  - 实施人员按会话查看多轮上下文，判断上下文是否被错误继承。
+  - 开发者定位工具调用失败、语义识别降级或路由选错 Agent 的原因。
+- 异常场景：
+  - 运行失败但没有工具调用时，仍展示已记录的 orchestration 阶段。
+  - 旧数据没有 trace event 时，接口回退展示 `agent_runs`、`semantic_parse`、`tool_calls`。
+
+## 功能能力
+
+- [C1] 输入能力：接收 `run_id`、`conversation_id`、Agent、状态、来源、关键字等查询条件。
+- [C2] 采集能力：记录 `received`、`context_hydrated`、`semantic_parsed`、`agent_selected`、`capability_selected`、`tool_invoked`、`response_built`、`conversation_updated`、`failed` 等事件。
+- [C3] 输出能力：返回 trace 摘要、事件时间线、工具调用、语义解析、路由 JSON、最终回复和关联会话消息。
+- [C4] 状态与权限：复用现有登录与页面权限，管理员/可访问设置页用户可查看全量 trace。
+- [C5] 边界与降级：旧运行没有 trace events 时，按现有 run/tool/semantic 数据合成最小时间线。
+
+## 方案设计
+
+### 前端
+
+- 页面/组件：
+  - 新增 `AgentTraceCenterView` 或设置页内 Trace Center 分区。
+  - 新增 trace 详情组件，复用现有日志详情的直角企业级视觉。
+  - 从日志详情、数字员工工作记录、报销助手操作反馈中可跳转到 trace 详情。
+- 交互状态：
+  - 列表支持关键字、状态、Agent、来源筛选。
+  - 详情展示左侧时间线、右侧输入输出 JSON、顶部摘要。
+  - 支持加载、空态、错误态和刷新。
+- 展示规则：
+  - 事件按 `started_at`、`sequence` 升序展示。
+  - 失败事件突出错误信息。
+  - 大 JSON 使用可滚动代码块，避免撑破页面。
+
+### 后端
+
+- 接口/服务：
+  - `GET /api/v1/agent-traces`：查询 trace 列表。
+  - `GET /api/v1/agent-traces/{run_id}`：读取单次运行 trace。
+  - `GET /api/v1/agent-traces/conversations/{conversation_id}`：读取会话 trace。
+- 权限与校验：
+  - 复用当前 API 依赖和系统登录态。
+  - 不允许通过 trace 接口修改业务数据。
+- 持久化：
+  - 新增 `agent_trace_events` 表。
+  - 通过 `AgentTraceService` 封装记录、查询、合成旧数据时间线。
+
+### 算法与规则
+
+- 规则输入：Agent 运行阶段、工具调用结果、语义解析结果和会话消息。
+- 规则流程：
+  - 采集阶段按固定事件名记录。
+  - 查询阶段按事件序列合并 run、semantic、tool、conversation。
+  - 无事件时从历史 run 数据合成 fallback timeline。
+- 结果解释：
+  - 每个事件输出 `title`、`summary`、`status`、`duration_ms`、`input_json`、`output_json`、`error_message`。
+
+## 算法与公式
+
+当前功能不涉及评分、预算或风控公式，只涉及耗时统计：
+
+$$
+duration\_ms = finished\_at - started\_at
+$$
+
+变量说明：
+
+- $duration\_ms$：阶段耗时，单位毫秒。
+- $finished\_at$：阶段结束时间。
+- $started\_at$：阶段开始时间。
+
+## 测试方案
+
+- 单元测试：覆盖 `AgentTraceService` 记录事件、查询详情、旧 run fallback 时间线。
+- 接口测试：覆盖 trace 列表、单 run 详情、会话详情。
+- 前端交互测试：覆盖 trace 数据归一化、状态文案、空态和错误态。
+- 端到端测试：通过一次 Orchestrator 用户消息生成 `run_id`，验证详情接口能返回语义解析、路由和至少一个事件。
+- 回归测试：确认原 `agent-runs` 接口、数字员工工作记录、系统日志详情不破坏。
+- 手工验证：在浏览器打开 Trace Center，检查列表、详情和 JSON 展示。
+
+## 指标与验收
+
+- [A1] 功能验收：一次 Orchestrator 调用后，能通过 `run_id` 查询到完整 trace 详情。
+- [A2] 性能指标：单次 trace 详情查询在常规数据量下不引入明显慢查询；默认列表限制数量。
+- [A3] 质量指标：后端定向测试在 Docker `x-financial-main` 容器内 60s 超时内通过。
+- [A4] 安全/权限指标：trace 接口只读，不触发业务动作或副作用。
+- [A5] 可观测性：失败运行也能看到最后成功事件和失败事件。
+
+## 风险与开放问题
+
+- 风险：当前工作树已有大量未提交改动，本轮实现必须避免覆盖既有业务改动。
+- 已处理依赖：新增 trace 模型已纳入 `Base` 导入，`AgentTraceService.ensure_storage_ready()` 会按需创建 trace 事件表。
+- 待确认：后续是否需要接 OpenTelemetry、跨容器 trace 或长期归档策略。
+- 降级策略：没有 trace event 的旧 run 通过 `semantic_parse`、`tool_calls` 和 `route_json` 合成只读时间线。
+
+## 本轮实现记录
+
+- 后端已完成 `AgentTraceEvent`、`AgentTraceService` 和 `/api/v1/agent-traces` 只读接口。
+- Orchestrator 已在接收请求、会话补全、语义识别、路由、工具调用、会话写回、最终回复和失败路径写入 trace event。
+- 前端已在系统设置中新增 Agent Trace Center，并从日志详情、数字员工工作记录跳转到指定 `run_id`。
+- 本轮保持非目标不变：不做真实业务重跑、不接 OpenTelemetry、不处理 GL/总账体系和前端统一状态管理。
--- a/document/development/Agent链路追踪中心/TODO.md
+++ b/document/development/Agent链路追踪中心/TODO.md
@@ -0,0 +1,55 @@
+# Agent链路追踪中心 开发 TODO
+
+## 使用规则
+
+- 每个 TODO 必须对应 `CONCEPT.md` 中的目标、能力或验收点。
+- 只有完成并验证后，才能把 `[ ]` 改成 `[x]`。
+- 勾选时在任务后补充简短证据，例如文件、接口、命令或验证结果。
+- 如果需求发生变化，先更新 `CONCEPT.md`，再调整本 TODO。
+
+## 1. 调研与边界
+
+- [x] [CONCEPT: 背景与问题] 阅读相关页面、接口、服务、测试和历史文档，记录当前实现事实。证据：已确认 `agent_runs`、`agent_tool_calls`、`semantic_parse_logs`、`LogDetailView`、`DigitalEmployeeWorkRecords` 现状。
+- [x] [CONCEPT: 目标与非目标] 确认本轮开发范围，写清楚不做项。证据：`CONCEPT.md` 明确只做历史重放，不做调试重跑和 OpenTelemetry。
+- [x] [CONCEPT: 风险与开放问题] 标记无法立即确认的依赖、风险和假设。证据：`CONCEPT.md` 风险章节记录脏工作树和数据库初始化依赖。
+
+## 2. 契约与设计
+
+- [x] [CONCEPT: 功能能力] 定义输入、输出、状态、权限和边界条件。证据：`CONCEPT.md` 功能能力章节。
+- [x] [CONCEPT: 方案设计] 明确前端、后端、算法、数据的职责边界。证据：`CONCEPT.md` 方案设计章节。
+- [x] [CONCEPT: 算法与公式] 补全耗时公式和变量解释。证据：`CONCEPT.md` 算法与公式章节。
+- [x] [CONCEPT: 指标与验收] 把验收标准转成可验证的检查点。证据：`CONCEPT.md` 指标与验收章节。
+
+## 3. 后端实现
+
+- [x] [CONCEPT: 后端] 新增 trace 事件模型、schema、repository/service。证据：`AgentTraceEvent`、`agent_trace.py`、`AgentTraceService`。
+- [x] [CONCEPT: 后端] 新增 `agent-traces` 只读接口和路由注册。证据：`agent_traces.py` endpoint 与 `router.py` 注册。
+- [x] [CONCEPT: 后端] 在 Orchestrator 关键节点写入 trace event。证据：`orchestrator.py` 记录接收、会话、语义、路由、回复、失败事件；`orchestrator_execution.py` 记录工具调用事件。
+- [x] [CONCEPT: 数据] 实现旧 run fallback 时间线，避免旧数据详情为空。证据：`AgentTraceService.get_trace()` 在无事件时由 `AgentRun`、`SemanticParseLog`、`AgentToolCall` 合成只读时间线。
+
+## 4. 算法/规则实现
+
+- [x] [CONCEPT: 算法与规则] 实现 trace 事件排序、耗时计算和状态归一化。证据：`AgentTraceService._next_sequence()`、`_resolve_duration_ms()`、`agentTraceViewModel.js`。
+- [x] [CONCEPT: 结果解释] 输出可读事件标题、摘要、输入输出和错误信息。证据：Trace event schema 与 `AgentTraceCenterView.vue` 详情面板。
+
+## 5. 前端实现
+
+- [x] [CONCEPT: 前端] 新增 trace 服务 API 和数据归一化工具。证据：`agentTraces.js`、`agentTraceViewModel.js`。
+- [x] [CONCEPT: 前端] 新增 Trace Center 列表与详情视图。证据：`AgentTraceCenterView.vue`。
+- [x] [CONCEPT: 前端] 从现有日志详情和工作记录补充 trace 跳转入口。证据：`LogDetailView.vue`、`DigitalEmployeeWorkRecords.vue`。
+- [x] [CONCEPT: 前端] 实现加载、空态、错误态和刷新。证据：`AgentTraceCenterView.vue` 列表/详情状态与刷新按钮。
+- [x] [CONCEPT: 前端] 对齐现有企业级直角、低饱和、密集信息风格。证据：`agent-trace-center-view.css` 使用面板、表格、状态徽标和紧凑信息布局。
+
+## 6. 测试与验证
+
+- [x] [CONCEPT: 测试方案] 补充后端 service/API 定向测试。证据：`test_agent_trace_service.py` 覆盖事件记录、fallback、接口列表和详情。
+- [x] [CONCEPT: 测试方案] 补充前端数据归一化测试或可构建验证。证据：`npm.cmd --prefix web run build` 通过。
+- [x] [CONCEPT: 测试方案] 在 60s 超时内运行 Docker 后端定向验证。证据：`docker exec ... pytest -q server/tests/test_agent_trace_service.py server/tests/test_agent_runs_service.py`，7 passed。
+- [x] [CONCEPT: 测试方案] 运行 `npm.cmd --prefix web run build`。证据：Vite build 成功。
+- [x] [CONCEPT: 指标与验收] 记录验证命令、结果和未覆盖风险。证据：后端测试 7 passed、Vite build 成功、重启后 `/api/v1/agent-traces/{run_id}` live 返回 8 个 fallback 事件；浏览器插件后续不可用，未完成最终截图巡检。
+
+## 7. 文档收尾
+
+- [x] [CONCEPT: 指标与验收] 回看所有验收点，确认均有实现或验证证据。证据：后端 service/API 测试、前端构建、入口接入均已完成。
+- [x] [CONCEPT: 风险与开放问题] 更新剩余风险、后续任务和明确不做项。证据：`CONCEPT.md` 保留 OpenTelemetry、跨容器 trace、长期归档为后续待定。
+- [x] [CONCEPT: 功能一句话] 确认最终实现没有偏离原始目标。证据：本轮只做 Agent Trace Center，未处理 GL/前端状态管理两项待定问题。