6137bb5cdc
- MASTER_TODO.md: update master todo list - day_3_semantic_ontology_mvp.md: update semantic ontology tasks - day_5_user_agent_mvp.md: update user agent tasks
12 KiB
12 KiB
Day 5：User Agent MVP
今天的大开发点
实现面向用户的自建 Agent。它负责用户提问、流程辅助、规则解释、查询结果解释和草稿生成。
User Agent 只能处理用户侧交互，不负责后台定时内循环，也不能自动执行高风险动作。
为什么第五天做这个
Day 1 到 Day 4 已经具备资产、语义、路由和日志基础，此时可以把用户自然语言入口接到真实流程上。
今天主要交付
- 用户自然语言入口。
- 对话入口透传首句文本、附件名称和页面上下文。
- 语义识别完整后创建报销单草稿。
- 对话补充字段时更新报销主表、明细和附件关联。
- 用户确认后触发报销单提交和状态变更。
- 报销查询和解释。
- 应收查询和解释。
- 应付查询和解释。
- 规则引用解释。
- 风险原因说明。
- 处理意见草稿。
- 知识库读取骨架。
- 低置信度场景的澄清追问。
- 前端问答或操作入口。
当前完成情况
个人工作台、报销对话框和通用聊天入口已经接通真实 Orchestrator / User Agent 问答链路。回答、规则引用、风险说明、建议动作和结构化draft_payload已可返回。报销对话框已接入 OCR 识别接口，附件名称、OCR 摘要和页面上下文已能透传到 Orchestrator / User Agent。右侧工作台已开始展示结构化review_payload，并已收敛为“识别结果专用区”：核心识别摘要、时间换算说明、逐票据识别结果、可能单据类型、建议归属费用和 OCR 置信度。个人工作台和报销对话框已接入conversation_id/draft_claim_id，同一会话内的连续追问不再按全新请求处理。个人工作台已支持“继续会话 / 新建会话”，并可恢复最近一次用户会话或清空旧会话后重新开始。报销核对流已切到产品化交互：正文区负责 AI 式核对提示、待补充信息、风险提醒和底部动作区，右侧只承载识别结果与票据识别明细，动作固定为“取消 / 修改识别信息 / 保存草稿或下一步”。- 真实
document_assets/document_asset_versions/expense_item_documents/document_ocr_results落库，以及draft -> submitted状态流转尚未完成；expense_claims/expense_claim_items草稿已接通真实落库。
相关架构文档：
当天验收门槛
- 用户能输入自然语言问题。
- 请求必须经过 Orchestrator。
- 至少 3 类财务问题有可读回答。
- 叙述型报销输入在最小槽位满足后能创建
expense_claims草稿。 - 用户确认提交后可把报销单从
draft变更为submitted。 - 回答能引用规则或知识。
- 语义低置信度时不会答非所问，而是追问。
- 高风险动作只生成草稿或建议。
- AgentRun Trace 能看到 User Agent 步骤。
今天不做
- 不做自动审批。
- 不做自动付款。
- 不做自动上线规则。
- 不做完整知识库检索优化。
- 不假装已读懂未解析的附件内容。
详细执行清单
以下内容为合并后的详细执行清单。
0. 开始前检查
确认 Orchestrator 能把用户请求路由到 User Agent。确认语义本体 8 字段可用。确认语义层已接入真实模型，而不是仅靠关键词规则。确认规则资产可查询。确认 AgentRun 和 ToolCall 可记录。确认已有现成对话 UI 可复用。确认财务业务数据已可通过最小真实数据查询。当前无需额外补最小 Mock 数据服务。
1. User Agent 输入输出
定义UserAgentRequest。请求包含run_id。请求包含user_id。请求包含message。请求包含ontology。请求包含context_json。定义UserAgentResponse。响应包含answer。响应包含citations。响应包含suggested_actions。响应包含draft_payload。响应包含risk_flags。响应包含requires_confirmation。
验收证据：
User Agent 响应结构能被 Orchestrator 直接包装返回。
2. 查询处理
实现报销查询处理器。实现应收查询处理器。实现应付查询处理器。- 查询前检查权限级别。
查询时记录 ToolCall。查询失败时返回可读错误。查询为空时返回空态解释。- 查询结果限制返回条数，避免一次返回过大。
验收证据：
“查本周报销金额”有可读回答。“客户 A 本月应收多少”有可读回答。“供应商 B 待付款多少”有可读回答。
3. 规则解释
根据语义场景查询相关规则资产。只引用 active 规则。读取规则当前版本 Markdown。从 Markdown 中提取规则摘要。回答中说明使用了哪些规则。回答中包含规则版本号。回答中包含规则更新时间。没有相关规则时说明缺失。
验收证据：
“为什么这笔报销有风险”能引用规则。
4. 风险解释
识别重复报销风险。识别金额超标风险。识别发票异常风险。识别逾期应收风险。识别逾期应付风险。风险回答包含风险类型。风险回答包含触发原因。风险回答包含建议处理动作。高风险建议不能变成自动执行。
验收证据：
风险解释结果不是单纯“有风险”，而是有依据。
5. 草稿生成与单据落库
支持根据语义结果创建expense_claims草稿。报销草稿初始状态写为draft。支持根据语义结果创建或更新expense_claim_items。- 支持把用户上传附件挂到
document_assets、document_asset_versions、expense_item_documents。 - 支持把 OCR 识别快照写入
document_ocr_results，并保留ocr_engine、ocr_model、raw_json、confidence。 对话中补充金额、发生时间、费用类型等已落地字段后，能回写已有草稿而不是只更新内存结果。支持生成报销处理意见草稿。支持生成应收催收建议草稿。支持生成应付付款建议草稿。- 用户明确确认“提交报销”后，把
expense_claims.status从draft更新为submitted。 - 报销提交时写入
submitted_at。 - 报销状态变更写入审计日志。
- 报销状态变更写入 AgentRun 结果。
草稿中标明“待人工确认”。草稿不直接提交业务系统。草稿生成写入审计日志。草稿生成写入 AgentRun 结果。- 草稿创建或更新后向前端返回
attachment_ids。 草稿创建或更新后向前端返回claim_id、claim_no、status。
验收证据：
- “我今天去客户现场，招待了客户，花销了1000元”在补齐必要字段后可创建报销草稿。
- “帮我提交这笔报销”在确认后只把状态改到
submitted，不会直接改成approved或paid。 “帮我生成处理意见”只返回草稿，不执行审批。
6. 知识库读取骨架
- 建立知识条目查询接口或服务。
- 支持按关键词查询知识条目。
- 支持按业务场景查询知识条目。
- User Agent 回答可以引用知识条目。
- 引用中包含知识标题。
- 引用中包含更新时间。
- 知识库不可用时返回降级说明。
验收证据：
- 知识库失败不会导致整个回答失败。
7. 对话或操作入口
前端增加用户问题输入框。输入框支持回车或按钮提交。提交时调用 Orchestrator，而不是绕过 Orchestrator。提交时透传首句文本。提交时透传附件名称。提交时透传 OCR 摘要。提交时透传页面上下文。提交时透传conversation_id与draft_claim_id。- 提交时透传附件 ID。
展示 Agent 回答。展示引用规则或知识。展示建议动作。展示识别意图摘要、待确认字段和确认动作卡片。正文区改为简洁核对提示，不再堆叠调度结果或运行明细。正文区待补充信息和风险提示已改为紧凑高亮样式，避免出现大段冗长说明。展示逐票据 OCR 识别结果，并支持按 1、2、3… 顺序查看。右侧逐票据结果已补充“可能单据类型 / 建议归属费用 / 识别置信度”等识别信息。展示多场景票据的分单建议。- 展示报销草稿 ID 或 claim_no。
- 展示当前报销状态。
展示需要人工确认的提示。展示run_id。展示加载态。展示错误态。
验收证据：
用户可在页面完成一次问答闭环。
8. 安全边界
User Agent 不直接修改规则状态。User Agent 不直接上线规则。User Agent 不直接审批报销。User Agent 不直接把报销单改为approved或paid。User Agent 不直接付款。User Agent 不直接删除知识。所有高风险动作只返回建议或草稿。- 报销从
draft变更到submitted之前必须有用户确认。 - 所有草稿动作标记
requires_confirmation=true。 语义低置信度时优先追问，不返回答非所问的查询结果。没有 OCR/VLM 结果时，不假装读懂图片或票据内容。
验收证据：
提示词要求“直接付款”时仍被阻断。
9. 测试
测试报销查询。测试应收查询。- 测试应付查询。
- 测试规则解释。
测试风险解释。- 测试 OCR 摘要透传后，User Agent 能在回答中正确引用附件语境而不编造内容。
测试报销草稿创建。测试报销草稿补槽更新。- 测试报销状态从
draft变更到submitted。 测试草稿生成。- 测试越权动作阻断。
- 测试知识库降级。
验收证据：
User Agent 核心测试通过。
10. Day 5 验收
User Agent 服务可被 Orchestrator 调用。用户入口可提交自然语言问题。至少 3 个财务场景有回答。语义识别完整后的报销输入能创建报销草稿。- 用户确认后能提交报销并更新状态。
回答能引用规则或知识。高风险动作不会自动执行。AgentRun Trace 能看到 User Agent 步骤。前端构建通过。所有完成项已用[x] ~~...~~标记。
阻塞记录
暂无。
日终交接
当前已支持报销 / 应收 / 应付查询、规则解释、风险解释、草稿建议与澄清追问。当前已支持附件名称、OCR 摘要和页面上下文进入对话链路，但这还不是附件真实持久化。当前已把用户一句话和多票据输入转成结构化预审面板，开始支持字段确认、票据核对和分单建议，而不再只是返回一段文本。当前仍是占位的主要能力是报销单真实落库、附件持久化、OCR 结果入表和知识库读取，不再是简单静态问答 Mock。Day 6 Hermes 可直接复用当前的规则检查、风险标签和 Orchestrator Trace / ToolCall 契约。