ba28627f11
- Update 00_README.md: refresh week plan overview and structure - Update MASTER_TODO.md: update master todo list for new week - Update day_1_foundation_models.md: expand foundation models tasks - Update day_2_rule_center_integration.md: add rule center integration tasks - Update day_3_semantic_ontology_mvp.md: add semantic ontology tasks - Update day_4_orchestrator_runtime.md: add orchestrator runtime tasks - Update day_5_user_agent_mvp.md: add user agent tasks - Update day_6_hermes_mvp.md: add hermes agent tasks - Update day_7_hardening_demo_acceptance.md: add hardening tasks
9.6 KiB
9.6 KiB
Day 5：User Agent MVP
今天的大开发点
实现面向用户的自建 Agent。它负责用户提问、流程辅助、规则解释、查询结果解释和草稿生成。
User Agent 只能处理用户侧交互，不负责后台定时内循环，也不能自动执行高风险动作。
为什么第五天做这个
Day 1 到 Day 4 已经具备资产、语义、路由和日志基础，此时可以把用户自然语言入口接到真实流程上。
今天主要交付
- 用户自然语言入口。
- 对话入口透传首句文本、附件名称和页面上下文。
- 语义识别完整后创建报销单草稿。
- 对话补充字段时更新报销主表、明细和附件关联。
- 用户确认后触发报销单提交和状态变更。
- 报销查询和解释。
- 应收查询和解释。
- 应付查询和解释。
- 规则引用解释。
- 风险原因说明。
- 处理意见草稿。
- 知识库读取骨架。
- 低置信度场景的澄清追问。
- 前端问答或操作入口。
当前完成情况
个人工作台、报销对话框和通用聊天入口已经接通真实 Orchestrator / User Agent 问答链路。回答、规则引用、风险说明、建议动作和结构化draft_payload已可返回。- 真实
expense_claims/expense_claim_items/ 附件表落库，以及draft -> submitted状态流转尚未完成。
相关架构文档：
当天验收门槛
- 用户能输入自然语言问题。
- 请求必须经过 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。 - 对话中补充金额、事由、客户、参与人、票据后，能回写已有草稿而不是只更新内存结果。
支持生成报销处理意见草稿。支持生成应收催收建议草稿。支持生成应付付款建议草稿。- 用户明确确认“提交报销”后，把
expense_claims.status从draft更新为submitted。 - 报销提交时写入
submitted_at。 - 报销状态变更写入审计日志。
- 报销状态变更写入 AgentRun 结果。
草稿中标明“待人工确认”。草稿不直接提交业务系统。- 草稿生成写入审计日志。
草稿生成写入 AgentRun 结果。
验收证据：
- “我今天去客户现场，招待了客户，花销了1000元”在补齐必要字段后可创建报销草稿。
- “帮我提交这笔报销”在确认后只把状态改到
submitted，不会直接改成approved或paid。 “帮我生成处理意见”只返回草稿，不执行审批。
6. 知识库读取骨架
- 建立知识条目查询接口或服务。
- 支持按关键词查询知识条目。
- 支持按业务场景查询知识条目。
- User Agent 回答可以引用知识条目。
- 引用中包含知识标题。
- 引用中包含更新时间。
- 知识库不可用时返回降级说明。
验收证据：
- 知识库失败不会导致整个回答失败。
7. 对话或操作入口
前端增加用户问题输入框。输入框支持回车或按钮提交。提交时调用 Orchestrator，而不是绕过 Orchestrator。- 提交时透传首句文本、附件名称、附件 ID 和页面上下文。
展示 Agent 回答。展示引用规则或知识。展示建议动作。- 展示报销草稿 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. 测试
测试报销查询。测试应收查询。- 测试应付查询。
- 测试规则解释。
测试风险解释。- 测试报销草稿创建。
- 测试报销草稿补槽更新。
- 测试报销状态从
draft变更到submitted。 测试草稿生成。- 测试越权动作阻断。
- 测试知识库降级。
验收证据：
User Agent 核心测试通过。
10. Day 5 验收
User Agent 服务可被 Orchestrator 调用。用户入口可提交自然语言问题。至少 3 个财务场景有回答。- 语义识别完整后的报销输入能创建报销草稿。
- 用户确认后能提交报销并更新状态。
回答能引用规则或知识。高风险动作不会自动执行。AgentRun Trace 能看到 User Agent 步骤。前端构建通过。所有完成项已用[x] ~~...~~标记。
阻塞记录
暂无。
日终交接
当前已支持报销 / 应收 / 应付查询、规则解释、风险解释、草稿建议与澄清追问。当前仍是占位的主要能力是报销单真实落库、附件持久化和知识库读取，不再是简单静态问答 Mock。Day 6 Hermes 可直接复用当前的规则检查、风险标签和 Orchestrator Trace / ToolCall 契约。