YG-Soft/X-Financial
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: 更新公司通信费规则表与 AI 意图规划/work-log 文档

Browse Source
This commit is contained in:
caoxiaozhu
2026-06-25 10:56:00 +08:00
parent 59353308a2
commit d321005044
78 changed files with 51 additions and 15182 deletions
Download Patch File Download Diff File Expand all files Collapse all files

146
document/development/AI意图规划器/CONCEPT.md
View File

@@ -1,146 +0,0 @@
# AI 意图规划器
## 功能一句话
把用户一句自然语言先交给大模型识别成“动作和步骤”的结构化计划，再由前端/后端确定性执行器逐步校验和执行；规则只作为模型不可用或结构非法时的兜底。
## 背景
用户真实表达往往不是一个简单关键词，而是一个目标：
```text
去上海出差，辅助国网仿生产服务器部署，交通火车，直接提交
```
这句话包含至少四层语义：
- 业务对象：差旅费用申请。
- 已给字段：地点、事由、交通方式。
- 用户动作：直接提交，不只是生成草稿。
- 执行步骤：生成申请核对表、校验必填字段、查重、提交审批。
如果继续用前端规则直接判断，会越来越像关键词路由；正确方向是让大模型先拆成结构化计划，系统只执行经过白名单校验的步骤。
## 目标
- 大模型作为复杂意图的主识别器，输出结构化 `intent plan`。
- `intent plan` 明确描述用户要执行的动作、业务字段、缺失字段和步骤列表。
- 执行器只认计划中的白名单步骤，不直接相信模型文本。
- 字段齐全且用户明确“直接提交”时，系统自动走完整链路。
- 字段缺失、风险阻断、重复申请或低置信度时，系统停在核对表或风险提示。
- 本地规则只作为 `rule_fallback`，不得伪装成模型判断。
## 非目标
- 不让大模型直接写数据库、提交审批或绑定附件。
- 不引入 LangChain 高层 Agent 来替代现有业务服务。
- 不让 LangGraph 直接接管模型供应商密钥、数据库写入或审批副作用。
- 不绕过已有申请预览、规则测算、重复申请核查和提交接口。
- 不把所有财务场景一次性改完；第一阶段先覆盖个人工作台 AI 模式里的差旅申请链路。
## 结构化计划契约
前端执行器消费统一结构：
```json
{
"source": "llm_function_call",
"intent": "create_travel_application",
"requestedAction": "submit",
"confidence": 0.91,
"sourceText": "去上海出差，辅助国网仿生产服务器部署，交通火车，直接提交",
"slots": {
"location": "上海",
"reason": "辅助国网仿生产服务器部署",
"transportMode": "火车"
},
"missingFields": [],
"steps": [
"build_application_preview",
"validate_required_fields",
"run_duplicate_precheck",
"submit_application"
]
}
```
## 步骤白名单
- `build_application_preview`：生成申请核对表，复用现有申请预览能力。
- `validate_required_fields`：用确定性代码校验必填字段和字段格式。
- `run_duplicate_precheck`：提交前查询同日期或重叠申请单。
- `submit_application`：调用现有申请提交动作；只有用户明确要求提交且前置校验通过才执行。
- `save_application_draft`：调用现有申请草稿保存能力。
- `create_reimbursement_draft`：调用现有报销草稿创建能力。
- `associate_attachments`：调用现有附件关联 runner；缺少 `receipt_ids` 或匹配不唯一时阻断，不能假成功。
- `link_existing_application`：调用现有报销草稿创建链路并写入申请关联 flag；申请单不存在、未审批或已被报销时阻断。
## 数据流
```text
用户输入
↓
steward LLM function calling
↓
模型计划归一化与白名单校验
↓
可执行 intent plan
↓
申请/报销/附件等确定性执行器
↓
核对表、风险提示、草稿或提交结果
```
当模型不可用、超时或返回不可执行结构时：
```text
模型失败
↓
本地 rule_fallback 生成保守计划
↓
同一个执行器继续处理
```
## 安全边界
- 模型只负责“理解”和“拆步骤”，不拥有副作用权限。
- 执行器必须校验 `intent` 和 `steps` 是否在白名单内；未知 action 必须阻断，不能调用业务服务。
- 提交前必须走 `readyToSubmit` 和重复申请 precheck。
- 提交类副作用必须带用户确认和 precheck 通过证据。
- 地点、日期、事由等字段仍由现有申请预览和规则校验模块判断。
- 模型置信度低、流程冲突或必填字段缺失时，不自动提交。
## 第一阶段落地
- 新增前端 planner model，把后端 `StewardPlanResponse` 映射成前端 `intent plan`。
- 个人工作台 AI 模式在命中差旅申请候选时，优先调用现有 `/steward/plans` 获取模型计划。
- 模型计划可执行时，按 `steps` 生成申请核对表并在条件满足时自动提交。
- 模型不可用或计划不可执行时，使用本地 `rule_fallback` 保持体验不倒退。
- 保留既有普通小财管家路径，用来处理无法直接执行或更复杂的多任务场景。
## LangGraph 迁移方向
后端小财管家的规划入口、槽位决策入口和运行时动作决策入口已经开始迁入 LangGraph。
后续不再继续把感知、规划、补字段、运行时动作判断堆进自研 `if/else` 编排，而是按 node 拆分：
- `model_intent_node`：模型 function calling 规划。
- `slot_tool_decision_node`：字段缺口与追问判断，失败时进入规则兜底。
- `runtime_memory_context_node`：合并前端运行时状态和持久化 `steward_state`。
- `runtime_tool_decision_node`：用户补充、确认、取消、继续执行等运行时判断。
- `runtime_action_decision_node`：已选流程确认等不需要模型的确定性行动路由。
- `action_plan_node`：生成白名单 `StewardActionStep`，当前已覆盖申请预览、保存草稿、直接提交和报销草稿。
- `human_review_node`：保存草稿、提交审批、关联申请单前的确认点。
- `action_execute_node`：调用现有确定性业务服务；当前已由 `/steward/actions/execute`、`StewardGraphActionRuntime` 和 `StewardActionExecutor` 提供 checkpoint、pending interrupt 和幂等重放。
- `persist_state_node`：合并 conversation state 和 steward state。
当前 `plans` 已返回服务端 `action_steps`，`slot-decisions` / `runtime-decisions` 已默认走 `StewardGraphRuntime`。
如果 LangGraph 图节点异常，服务端会退回原有 Agent 和规则兜底，避免框架层故障影响用户会话。
详细迁移计划见 `LANGGRAPH_RUNTIME_MIGRATION.md`。
## 测试策略
- planner model 单元测试：模型计划归一化、rule fallback、政策咨询排除。
- 前端静态接线测试：主流程必须先请求 steward plan，再 fallback。
- 申请预览回归测试：`直接提交` 不得污染事由；缺日期不得伪造字段。
- 构建验证：`npm --prefix web run build`。

420
document/development/AI意图规划器/LANGGRAPH_RUNTIME_MIGRATION.md
View File

@@ -1,420 +0,0 @@
# 小财管家 LangGraph Runtime 迁移计划
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** 把小财管家的感知、规划、记忆、确认和行动逐步迁到 LangGraph runtime，减少自研流程编排里的隐藏状态和分支 bug。
**Architecture:** 保留现有 FastAPI API、Pydantic schema、`RuntimeChatService` 模型供应商抽象和业务服务；LangGraph 只接管 agent 编排。副作用动作必须通过白名单 action node 调用现有业务服务，保存草稿、提交和关联单据都不能由模型文本直接触发。
**Tech Stack:** Python 3.11、FastAPI、Pydantic、LangGraph 1.x、SQLAlchemy、现有 `AgentConversationService` / `StewardFlowStateService`。
---
## 当前状态
已经完成第一阶段接入：
- `server/src/app/services/steward_graph_planner.py`
- 已新增 `StewardGraphPlannerService`。
- 已用 LangGraph `StateGraph` 编排 `prepare_context -> detect_model_intent -> done/off_topic/rule_fallback`。
- `server/src/app/services/steward_graph_runtime.py`
- 已新增 `StewardGraphRuntime`。
- 槽位决策已编排为 `slot_prepare_context -> slot_tool_decision -> done/rule_fallback`。
- 运行时决策已编排为 `runtime_memory_context -> runtime_action_decision/runtime_tool_decision -> done/rule_fallback`。
- 图内失败会降级到原有规则兜底；端点层图运行异常会回退旧 Agent。
- `server/src/app/services/steward_action_contracts.py`
- 已新增 `StewardActionPlanBuilder`。
- 已把申请、报销、保存草稿、直接提交规划成 `StewardActionStep` 白名单动作。
- `StewardGraphPlannerService` 已增加 `attach_action_steps` 节点，计划返回前统一补全动作列表。
- `server/src/app/services/steward_action_executor.py`
- 已新增 `StewardActionExecutor`。
- 已接入 `/steward/actions/execute`，支持未知动作拒绝、缺字段阻断、提交确认门禁、重复申请 precheck、申请/报销草稿真实执行、关联申请单和附件关联。
- 申请动作复用 `UserAgentService` 的申请保存/提交能力，报销草稿复用 `ExpenseClaimService.save_or_submit_from_ontology()`。
- `server/src/app/services/steward_graph_action_runtime.py`
- 已新增 `StewardGraphActionRuntime`。
- 已用 LangGraph `StateGraph` 编排 `action_checkpoint_load -> action_execute_node -> action_checkpoint_persist`。
- 已通过 `conversation_id + client_trace_id` 在 `AgentConversation.state_json` 中记录 checkpoint、pending interrupt 和幂等重放结果。
- `web/src/services/steward.js` / `web/src/views/scripts/stewardPlanModel.js`
- 前端已新增 `executeStewardAction()` 服务方法。
- steward suggested action 已携带服务端可执行 action step，旧申请预览流仍保留兜底。
- `web/src/composables/workbenchAiMode/useWorkbenchAiActionRouter.js`
- AI 工作台点击 `steward_execute_action` 时会调用 `/steward/actions/execute`。
- 直接提交会先执行 `run_duplicate_precheck`，precheck 通过后再提交申请。
- `server/src/app/api/v1/endpoints/steward.py`
- `/steward/plans` 和 `/steward/plans/stream` 默认使用 `StewardGraphPlannerService`。
- `/steward/slot-decisions` 和 `/steward/runtime-decisions` 默认使用 `StewardGraphRuntime`。
- `STEWARD_AGENT_RUNTIME=legacy` 可回退旧 `StewardPlannerService`。
- `server/pyproject.toml` / `server/uv.lock`
- 已加入 `langgraph>=1.2.0,<2.0.0`。
- `server/tests/test_steward_graph_planner.py`
- 已覆盖默认 LangGraph、显式 LangGraph、legacy 回退、模型成功计划和模型失败后规则兜底。
- `server/tests/test_steward_graph_runtime.py`
- 已覆盖槽位工具节点、图内规则兜底、运行时记忆合并、确定性行动选择和端点级 legacy 兜底。
- `server/tests/test_application_fact_resolver.py`
- 已覆盖 `交通火车` 不污染申请事由，以及 `高铁往返` 这类业务描述仍保留。
当前已完成规划入口、slot decision、runtime decision、基础 action contract、第一版 action executor、前端点击执行闭环，以及 action runtime 的 checkpoint / interrupt / 幂等重放。
真实外部模型连通性仍需要用当前 MiniMax / backup 配置再回放确认。
## 官方能力边界
LangGraph 官方文档强调它是低层 agent orchestration runtime，重点能力是 durable execution、streaming、human-in-the-loop 和 persistence。
本项目只采用这些底层编排能力：
- Graph API：用 state、node、edge 表达流程，node 可以是 LLM 调用，也可以是普通业务代码。
- Persistence：用 checkpointer 保存 thread scoped state，用 store 保存跨线程长期信息。
- Interrupt：在需要用户确认时暂停 graph，等待外部输入后恢复。
参考：
- <https://docs.langchain.com/oss/python/langgraph/overview>
- <https://docs.langchain.com/oss/python/langgraph/graph-api>
- <https://docs.langchain.com/oss/python/langgraph/persistence>
- <https://docs.langchain.com/oss/python/langgraph/interrupts>
## 总体目标架构
```text
用户输入 / 前端上下文 / 附件
↓
StewardGraphRuntime
├── prepare_context_node
├── model_intent_node
├── slot_decision_node
├── flow_guard_node
├── action_plan_node
├── human_review_node
├── action_execute_node
├── persist_state_node
└── response_adapter_node
↓
现有前端协议：StewardPlanResponse / StewardRuntimeDecisionResponse / StewardSlotDecisionResponse
```
关键原则：
- API 响应协议稳定，前端不因为 runtime 替换被迫大改。
- 模型只负责理解、拆步骤、给候选 action，不直接写库。
- 所有副作用节点必须调用现有业务服务，并保留确认和审计。
- `RuntimeChatService` 继续是唯一模型调用入口，LangGraph 不直接管理供应商密钥。
- `StewardFlowStateService` 和 `AgentConversationService` 是 checkpoint 落库的第一候选，不另起一套状态源。
## Runtime State 草案
第一版 graph state 用 `TypedDict`，后续需要持久化时再评估 Pydantic schema。
```python
class StewardGraphState(TypedDict, total=False):
request: StewardPlanRequest
conversation_id: str
thread_id: str
message: str
base_date: date
steward_state: dict[str, Any]
model_call_traces: list[dict[str, Any]]
intent_result: StewardIntentAgentResult | None
slot_decision: StewardSlotDecisionResponse | None
runtime_decision: StewardRuntimeDecisionResponse | None
action_plan: list[StewardActionStep]
pending_interrupt: dict[str, Any]
action_result: dict[str, Any]
response: StewardPlanResponse | StewardRuntimeDecisionResponse | StewardSlotDecisionResponse
fallback_reason: str
```
`thread_id` 推荐使用现有 `conversation_id`，这样 LangGraph checkpoint、业务会话和前端会话能对齐。
## 节点边界
### 感知节点
- `prepare_context_node`
- 输入：`StewardPlanRequest` 或 runtime decision request。
- 输出：清洗后的消息、base date、当前 conversation state。
- 禁止：模型调用、数据库写入。
- `model_intent_node`
- 调用：`StewardIntentAgent.detect()`。
- 约束：保留 `timeout_seconds=10`、`max_attempts=3`、`use_failure_cooldown=False`。
- 失败：只写入 `fallback_reason` 和 `model_call_traces`，不吞掉错误上下文。
### 决策节点
- `slot_decision_node`
- 迁移对象：`StewardSlotDecisionAgent.decide()`。
- 目标：让字段缺口判断进入同一个 graph state，不再由前端和后端多个入口各自推断。
- `runtime_decision_node`
- 迁移对象：`StewardRuntimeDecisionAgent.decide()`。
- 目标：用户补字段、确认流程、取消当前动作、继续下一任务都走 graph routing。
- `flow_guard_node`
- 负责申请/报销歧义、重复单据、时间重叠、低置信度、off-topic。
- 低置信度或强冲突必须进入确认或阻断，不允许继续 action 执行。
### 行动节点
- `action_plan_node`
- 输出白名单步骤，例如 `build_application_preview`、`save_application_draft`、`submit_application`。
- 禁止输出自由文本 action。
- `human_review_node`
- 对保存草稿、提交审批、关联申请单等副作用动作生成 interrupt payload。
- 第一阶段可继续返回前端确认动作；第二阶段再接 LangGraph `interrupt()`。
- `action_execute_node`
- 只能调用现有业务服务。
- 必须幂等，或在执行前检查动作是否已完成。
- 提交类动作必须检查 `confirmation_required` 和用户确认来源。
- `persist_state_node`
- 合并 `StewardFlowStateService.merge_plan()` / `merge_state()`。
- 后续接入 LangGraph checkpointer 后，这里负责业务状态与 checkpoint 的一致性。
### 响应节点
- `response_adapter_node`
- 输出现有 Pydantic response。
- 必须保留 `model_call_traces`、`planning_source`、`steward_state`。
## 分阶段计划
### Phase 0：规划入口接入 LangGraph
状态：已完成。
完成标准：
- [x] 默认 runtime 为 `langgraph`。
- [x] `STEWARD_AGENT_RUNTIME=legacy` 可回退。
- [x] `/steward/plans` 真实接口仍返回兼容的 `StewardPlanResponse`。
- [x] 模型失败后仍按 10s * 3 次再规则降级。
### Phase 1：修通模型成功路径
目标：让真实保存草稿话术至少能走一次 `llm_function_call` 成功路径。
文件：
- 修改：`server/src/app/services/runtime_chat.py`
- 修改：`server/src/app/services/settings.py`
- 修改：`server/tests/test_runtime_chat_service.py`
- 测试：`server/tests/test_steward_intent_agent.py`
步骤：
- [x] 写失败测试：模拟 main provider 超时但 backup provider 可用时，`complete_with_tool_call()` 返回 backup 的 tool call。
- [x] 确认 backup function calling 会在 main 失败后返回 tool call，不等待 main 重试结束。
- [ ] 写失败测试：MiniMax 返回非 OpenAI tool call 兼容格式时，服务端能记录清晰 trace 并降级。
- [x] 容器内运行：
```bash
docker exec -w /app -e SERVER_VENV_DIR=/tmp/x-financial-server-venv x-financial-local-linux \
timeout 60s /tmp/x-financial-server-venv/bin/pytest -q \
server/tests/test_runtime_chat_service.py \
server/tests/test_steward_intent_agent.py
```
验收：
- [ ] 真实 `/api/v1/steward/plans` 对保存草稿原句返回 `planning_source=llm_function_call`。
- [x] `model_call_traces` 能区分 main 失败、backup 成功或全失败。
### Phase 2：slot/runtime decision 迁入 graph
目标：把字段缺口和运行时动作判断从独立 agent 类迁进同一个 graph runtime。
状态：已完成。
文件：
- 已创建：`server/src/app/services/steward_graph_runtime.py`
- 已修改：`server/src/app/api/v1/endpoints/steward.py`
- 已测试：`server/tests/test_steward_graph_runtime.py`
- 保留测试：`server/tests/test_steward_slot_decision_agent.py`
- 保留测试：`server/tests/test_steward_runtime_decision_agent.py`
步骤：
- [x] 写失败测试：`StewardGraphRuntime.decide_slot()` 调用 slot node 后返回与现有 `StewardSlotDecisionAgent.decide()` 等价的 response。
- [x] 写失败测试：`StewardGraphRuntime.decide_runtime()` 在用户补充字段时合并 `steward_state`。
- [x] 把 `StewardSlotDecisionAgent` 包成 `slot_tool_decision` 节点。
- [x] 把 `StewardRuntimeDecisionAgent` 包成 `runtime_tool_decision` 节点。
- [x] 把已选流程确认和当前运行时记忆归一化拆成 `runtime_memory_context` / `runtime_action_decision` 节点。
- [x] endpoint 在 `STEWARD_AGENT_RUNTIME=langgraph` 时使用 graph runtime。
- [x] endpoint 在 graph runtime 异常时回退旧 Agent，避免框架层失效影响会话。
验收：
- [x] `slot-decisions`、`runtime-decisions` 和 `plans` 三个入口都由 LangGraph runtime 路由。
- [x] legacy 回退仍可用。
- [x] 图内工具节点失败时仍有可执行规则兜底。
### Phase 3：action node 标准化
目标：把保存草稿、提交审批、关联申请单这些副作用动作变成显式 action node。
状态：基础 action contract、第一版 action executor、前端点击执行闭环、LangGraph action node、checkpoint、pending interrupt 和幂等重放已完成；后续只剩 durable checkpointer 抽象与更完整 trace UI。
文件：
- 已创建：`server/src/app/services/steward_action_executor.py`
- 已创建：`server/src/app/services/steward_action_contracts.py`
- 已创建：`server/src/app/services/steward_graph_action_runtime.py`
- 已修改：`server/src/app/api/v1/endpoints/steward.py`
- 已修改：`server/src/app/services/steward_graph_planner.py`
- 已修改：`server/src/app/schemas/steward.py`
- 已修改：`web/src/services/steward.js`
- 已修改：`web/src/views/scripts/stewardPlanModel.js`
- 已修改：`web/src/composables/workbenchAiMode/useWorkbenchAiActionRouter.js`
- 已修改：`web/src/composables/workbenchAiMode/usePersonalWorkbenchAiMode.js`
- 已测试：`server/tests/test_steward_action_executor.py`
- 已测试：`server/tests/test_steward_graph_planner.py`
- 已测试：`server/tests/test_steward_planner.py`
- 已测试：`web/tests/workbench-ai-intent-planner-model.test.mjs`
- 已测试：`web/tests/steward-actions-service.test.mjs`
- 已测试：`web/tests/steward-plan-message-copy.test.mjs`
- 已测试：`web/tests/workbench-ai-action-router.test.mjs`
白名单 action：
- `build_application_preview`
- `save_application_draft`
- `submit_application`
- `link_existing_application`
- `create_reimbursement_draft`
- `associate_attachments`
步骤：
- [x] 写失败测试：申请直接提交计划必须输出 `fill_application_fields -> build_application_preview -> validate_required_fields -> run_duplicate_precheck -> submit_application`。
- [x] 写失败测试：保存草稿计划必须输出 `save_application_draft`，并在字段缺失时阻断后续副作用。
- [x] 写失败测试：报销计划必须输出 `fill_reimbursement_fields -> build_reimbursement_preview -> validate_required_fields -> create_reimbursement_draft`。
- [x] 在 `StewardTask` 和 `StewardPlanResponse` 中增加 `action_steps`。
- [x] 实现 `StewardActionPlanBuilder`，由服务端确定性生成白名单 action step。
- [x] 在 LangGraph planner 中新增 `attach_action_steps` 节点。
- [x] 前端 planner model 优先消费服务端 `task.action_steps`，旧响应才回退本地推导。
- [x] 写失败测试：未知 action step 被拒绝，不调用任何业务服务。
- [x] 写失败测试：`submit_application` 缺少确认来源时返回 `needs_confirmation`。
- [x] 写失败测试：`submit_application` 必须看到 precheck 通过后才允许真实提交。
- [x] 实现 action registry，只允许白名单 action。
- [x] 接入现有申请保存草稿、申请提交和报销草稿服务。
- [x] 前端新增 `executeStewardAction()` 并让 suggested action 携带服务端 action step。
- [x] AI 工作台点击 suggested action 时调用 `StewardActionExecutor`；直接提交先串行执行 precheck，再把结果交给 submit。
- [x] 接入 `link_existing_application` 和附件关联的真实执行。
- [x] 把 action executor 包成 LangGraph `action_execute_node`，并接入 checkpoint / interrupt 恢复。
验收：
- [x] 模型不能通过自由文本触发数据库写入，服务端只输出白名单 `StewardActionStep`。
- [x] 申请提交动作没有确认时返回 `needs_confirmation`，不会写库。
- [x] 申请提交动作没有 precheck 通过证据时被阻断。
- [x] 保存申请草稿和创建报销草稿通过现有业务服务真实入库，测试覆盖。
- [x] 前端点击可执行 steward action 会真实调用 executor，并把结果回写到会话消息。
- [x] 基础副作用动作有 `client_trace_id` 幂等键、conversation checkpoint 和 pending interrupt 记录。
### Phase 4：checkpoint 与 human-in-the-loop
目标：让 LangGraph 负责暂停、恢复和跨轮状态，而不是只靠前端消息状态。
文件：
- 已创建：`server/src/app/services/steward_graph_action_runtime.py`
- 已复用：`server/src/app/models/agent_conversation.py`
- 已测试：`server/tests/test_steward_action_executor.py`
步骤：
- [x] 设计 `conversation_id -> thread_id` 映射，当前直接以 `conversation_id` 作为 graph action thread。
- [x] 实现基于数据库的 checkpoint，先复用 `AgentConversation.state_json`。
- [x] 在提交审批缺确认时生成 pending interrupt payload。
- [x] 用户确认后用同一 `client_trace_id` / `conversation_id` 继续执行；终态请求会幂等重放。
验收：
- [x] 刷新页面后，后端仍保留当前等待确认的 action checkpoint。
- [x] 同一个 action 不会因为重复点击或重试重复写库。
- [ ] 前端完整恢复 UI 仍需继续把 checkpoint 状态展示为可恢复按钮。
### Phase 5：可观测性与 legacy 收敛
目标：让 agent 规划过程可解释、可测试、可回放，并逐步删除重复手写编排。
文件：
- 修改：`server/src/app/services/agent_traces.py`
- 修改：`server/src/app/models/agent_run.py`
- 修改：`document/development/Agent链路追踪中心/CONCEPT.md`
- 测试：`server/tests/test_agent_traces.py`
步骤：
- [ ] 每个 graph node 写入 trace event：输入摘要、输出摘要、耗时、错误。
- [ ] 前端显示“模型规划中 / 字段判断中 / 等待确认 / 执行动作”阶段。
- [ ] 对 legacy planner 增加废弃标记和删除条件。
- [ ] 删除重复的手写分支前，先保留至少一轮灰度开关。
验收：
- 任何一次用户请求都能从 trace 看出走过哪些 node。
- 删除 legacy 前，LangGraph 路径覆盖当前核心申请/报销链路测试。
## 回退策略
- 环境变量：
```bash
STEWARD_AGENT_RUNTIME=legacy
```
- 回退后：
- `/steward/plans` 使用旧 `StewardPlannerService`。
- 新 action node 和 checkpoint 不应影响 legacy。
- 回退原因必须写入当天工作日志。
## 验证矩阵
每个阶段至少跑：
```bash
docker exec -w /app -e SERVER_VENV_DIR=/tmp/x-financial-server-venv x-financial-local-linux \
timeout 60s /tmp/x-financial-server-venv/bin/pytest -q \
server/tests/test_steward_graph_planner.py \
server/tests/test_steward_planner.py \
server/tests/test_steward_intent_agent.py \
server/tests/test_runtime_chat_service.py
```
涉及前端执行器时补跑：
```bash
node --test web/tests/workbench-ai-intent-planner-model.test.mjs \
web/tests/workbench-ai-application-gate-model.test.mjs \
web/tests/steward-actions-service.test.mjs \
web/tests/steward-plan-message-copy.test.mjs
npm --prefix web run build
```
每次完成后执行：
```bash
git diff --check
docker exec -w /app -e SERVER_VENV_DIR=/tmp/x-financial-server-venv x-financial-local-linux \
/tmp/x-financial-server-venv/bin/python -m pip check
```
## 不做的事
- 不引入 LangChain 高层 Agent 来替代现有业务服务。
- 不让模型直接调用数据库写入、提交审批或绑定附件。
- 不为了接框架重写申请、报销、OCR、票据夹、审批规则。
- 不在没有测试覆盖时删除 legacy planner。
## 风险与处理
- 模型连通性不稳定：先修 provider 和 backup，再扩大 graph 节点。
- checkpoint 与业务 state 双写不一致：先复用 `AgentConversation.state_json`，不要新增第二个业务状态源。
- action node 副作用重复执行：每个 action 必须有幂等键和执行前状态检查。
- LangGraph 传递依赖影响 WebSocket：当前 `pip check` 通过；后续若流式接口异常，先核对 `websockets` 版本。
- 节点内继续堆大块逻辑：每个 node 只做一类事，超过 300 行先拆文件。

32
document/development/AI意图规划器/TODO.md
View File

@@ -1,32 +0,0 @@
# AI 意图规划器 TODO
## 第一阶段
- [x] 落地 AI 意图规划器概念文档，明确大模型负责拆计划、业务代码负责执行。
- [x] 新增前端 planner model，统一模型计划和本地 fallback 的输出结构。
- [x] 个人工作台 AI 模式先请求 steward 模型计划，再使用本地 fallback。
- [x] 差旅申请直提链路改为消费 `intent plan.steps`，不再直接消费正则识别结果。
- [x] 补齐 planner model 与主流程接线回归测试。
- [x] 跑前端构建和定向测试。
- [x] 后端 `/steward/plans` 增加 `requested_action` 输出，减少前端从原句推断“提交/保存”的比例。
- [x] 引入 LangGraph，并默认用 `StewardGraphPlannerService` 接管 `/steward/plans` 规划编排。
- [x] 落地 LangGraph runtime 迁移计划文档：`LANGGRAPH_RUNTIME_MIGRATION.md`。
- [x] 新增 `StewardGraphRuntime`，接管 `slot-decisions` 和 `runtime-decisions` 的 LangGraph 路由。
- [x] 为 LangGraph runtime 增加图内规则兜底和端点级 legacy Agent 兜底。
- [x] 为 `/steward/plans` 增加服务端白名单 `action_steps`，覆盖申请、报销、保存草稿和直接提交的基础动作规划。
- [x] 前端 planner model 优先消费服务端 `task.action_steps`，旧响应才回退本地步骤推导。
- [x] 新增 `/steward/actions/execute` 和 `StewardActionExecutor`，把未知 action 拒绝、提交确认门禁、precheck 阻断、申请草稿保存、申请提交和报销草稿创建接到现有业务服务。
- [x] 前端新增 `executeStewardAction()` 服务方法，并让 steward suggested action 携带服务端可执行 action step。
- [x] AI 工作台点击可执行 steward action 时调用 `/steward/actions/execute`；申请直接提交会先跑 `run_duplicate_precheck`，通过后再提交。
- [x] `complete_with_tool_call()` 增加 main 失败后 backup tool-call 成功路径测试，保证模型成功路径能从 backup 返回 `llm_function_call`。
- [x] 新增 `StewardGraphActionRuntime`，把 action executor 包成 LangGraph `action_execute_node`，并用 `conversation_id + client_trace_id` 在 `AgentConversation.state_json` 中持久化 checkpoint。
- [x] 对提交确认生成 pending interrupt；重复 client trace 直接重放 checkpoint，避免重复保存草稿或重复提交。
- [x] `link_existing_application` 接入现有报销草稿创建链路并写入申请关联 flag。
- [x] `associate_attachments` 接入现有附件关联 runner，按 receipt_ids 归集到可匹配报销草稿。
## 后续阶段
- [ ] 用真实 MiniMax / backup 配置再回放 `/steward/plans`，确认真实环境返回 `planning_source=llm_function_call`，不是规则兜底。
- [ ] 将当前 `AgentConversation.state_json` checkpoint 抽象为可替换的 durable checkpointer，并补恢复/清理策略。
- [ ] 为每个 LangGraph node 写入可追溯 trace，展示模型调用、规则降级、等待确认和动作执行结果。
- [ ] 在 LangGraph 路径覆盖申请/报销核心链路后，再逐步删除旧 `StewardPlannerService` 的重复编排。