X-Financial/document/development/agent week plan/day_5_user_agent_mvp.md

Day 5：User Agent MVP TODO

目标：实现面向用户的自建 Agent。它负责用户提问、流程辅助、规则解释、查询结果解释和草稿生成，不做自动审批、自动付款、自动上线等高风险动作。

参考文档：

• document/development/agent plan/03_agent_responsibilities.md
• document/development/agent plan/04_orchestrator_and_runtime_flow.md
• document/development/agent plan/12_llm_wiki_knowledge_architecture.md
• document/development/agent plan/13_rule_formation_lifecycle.md

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. 草稿生成

• 支持生成报销处理意见草稿。
• 支持生成应收催收建议草稿。
• 支持生成应付付款建议草稿。
• 草稿中标明“待人工确认”。
• 草稿不直接提交业务系统。
• 草稿生成写入审计日志。
• 草稿生成写入 AgentRun 结果。

验收证据：

• “帮我生成处理意见”只返回草稿，不执行审批。

6. 知识库读取骨架

• 建立知识条目查询接口或服务。
• 支持按关键词查询知识条目。
• 支持按业务场景查询知识条目。
• User Agent 回答可以引用知识条目。
• 引用中包含知识标题。
• 引用中包含更新时间。
• 知识库不可用时返回降级说明。

验收证据：

• 知识库失败不会导致整个回答失败。

7. 对话或操作入口

• 前端增加用户问题输入框。
• 输入框支持回车或按钮提交。
• 提交时调用 Orchestrator，而不是绕过 Orchestrator。
• 展示 Agent 回答。
• 展示引用规则或知识。
• 展示建议动作。
• 展示需要人工确认的提示。
• 展示 run_id。
• 展示加载态。
• 展示错误态。

验收证据：

• 用户可在页面完成一次问答闭环。

8. 安全边界

• User Agent 不直接修改规则状态。
• User Agent 不直接上线规则。
• User Agent 不直接审批报销。
• User Agent 不直接付款。
• User Agent 不直接删除知识。
• 所有高风险动作只返回建议或草稿。
• 所有草稿动作标记 requires_confirmation=true。

验收证据：

• 提示词要求“直接付款”时仍被阻断。

9. 测试

• 测试报销查询。
• 测试应收查询。
• 测试应付查询。
• 测试规则解释。
• 测试风险解释。
• 测试草稿生成。
• 测试越权动作阻断。
• 测试知识库降级。

验收证据：

• User Agent 核心测试通过。

10. Day 5 验收

• User Agent 服务可被 Orchestrator 调用。
• 用户入口可提交自然语言问题。
• 至少 3 个财务场景有回答。
• 回答能引用规则或知识。
• 高风险动作不会自动执行。
• AgentRun Trace 能看到 User Agent 步骤。
• 前端构建通过。
• 所有完成项已用 [x] ~~...~~ 标记。

阻塞记录

• 暂无。

日终交接

• 写明已支持的问题类型。
• 写明仍使用 Mock 的数据。
• 写明 Day 6 Hermes 可以复用的规则、风险、知识接口。