147 lines
6.5 KiB
Markdown
147 lines
6.5 KiB
Markdown
# 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`。
|