# Day 5：User Agent MVP

## 今天的大开发点

实现面向用户的自建 Agent。它负责用户提问、流程辅助、规则解释、查询结果解释和草稿生成。

User Agent 只能处理用户侧交互，不负责后台定时内循环，也不能自动执行高风险动作。

## 为什么第五天做这个

Day 1 到 Day 4 已经具备资产、语义、路由和日志基础，此时可以把用户自然语言入口接到真实流程上。

## 今天主要交付

- 用户自然语言入口。
- 对话入口透传首句文本、附件名称和页面上下文。
- 语义识别完整后创建报销单草稿。
- 对话补充字段时更新报销主表、明细和附件关联。
- 用户确认后触发报销单提交和状态变更。
- 报销查询和解释。
- 应收查询和解释。
- 应付查询和解释。
- 规则引用解释。
- 风险原因说明。
- 处理意见草稿。
- 知识库读取骨架。
- 低置信度场景的澄清追问。
- 前端问答或操作入口。

## 当前完成情况

- [x] ~~个人工作台、报销对话框和通用聊天入口已经接通真实 Orchestrator / User Agent 问答链路。~~
- [x] ~~回答、规则引用、风险说明、建议动作和结构化 `draft_payload` 已可返回。~~
- [x] ~~报销对话框已接入 OCR 识别接口，附件名称、OCR 摘要和页面上下文已能透传到 Orchestrator / User Agent。~~
- [x] ~~右侧工作台已开始展示结构化 `review_payload`：识别意图、待确认字段、历史风险/注意事项、分单建议、逐票据识别结果和确认动作卡片。~~
- [x] ~~个人工作台和报销对话框已接入 `conversation_id` / `draft_claim_id`，同一会话内的连续追问不再按全新请求处理。~~
- [ ] 真实 `document_assets` / `document_asset_versions` / `expense_item_documents` / `document_ocr_results` 落库，以及 `draft -> submitted` 状态流转尚未完成；`expense_claims` / `expense_claim_items` 草稿已接通真实落库。

相关架构文档：

- [Agent 职责边界](<../agent plan/03_agent_responsibilities.md>)
- [Orchestrator 与运行流程](<../agent plan/04_orchestrator_and_runtime_flow.md>)
- [LLM Wiki 知识库架构](<../agent plan/12_llm_wiki_knowledge_architecture.md>)
- [规则形成生命周期](<../agent plan/13_rule_formation_lifecycle.md>)

## 当天验收门槛

- 用户能输入自然语言问题。
- 请求必须经过 Orchestrator。
- 至少 3 类财务问题有可读回答。
- 叙述型报销输入在最小槽位满足后能创建 `expense_claims` 草稿。
- 用户确认提交后可把报销单从 `draft` 变更为 `submitted`。
- 回答能引用规则或知识。
- 语义低置信度时不会答非所问，而是追问。
- 高风险动作只生成草稿或建议。
- AgentRun Trace 能看到 User Agent 步骤。

## 今天不做

- 不做自动审批。
- 不做自动付款。
- 不做自动上线规则。
- 不做完整知识库检索优化。
- 不假装已读懂未解析的附件内容。

## 详细执行清单

以下内容为合并后的详细执行清单。

## 0. 开始前检查

- [x] ~~确认 Orchestrator 能把用户请求路由到 User Agent。~~
- [x] ~~确认语义本体 8 字段可用。~~
- [x] ~~确认语义层已接入真实模型，而不是仅靠关键词规则。~~
- [x] ~~确认规则资产可查询。~~
- [x] ~~确认 AgentRun 和 ToolCall 可记录。~~
- [x] ~~确认已有现成对话 UI 可复用。~~
- [x] ~~确认财务业务数据已可通过最小真实数据查询。~~
- [x] ~~当前无需额外补最小 Mock 数据服务。~~

## 1. User Agent 输入输出

- [x] ~~定义 `UserAgentRequest`。~~
- [x] ~~请求包含 `run_id`。~~
- [x] ~~请求包含 `user_id`。~~
- [x] ~~请求包含 `message`。~~
- [x] ~~请求包含 `ontology`。~~
- [x] ~~请求包含 `context_json`。~~
- [x] ~~定义 `UserAgentResponse`。~~
- [x] ~~响应包含 `answer`。~~
- [x] ~~响应包含 `citations`。~~
- [x] ~~响应包含 `suggested_actions`。~~
- [x] ~~响应包含 `draft_payload`。~~
- [x] ~~响应包含 `risk_flags`。~~
- [x] ~~响应包含 `requires_confirmation`。~~

验收证据：

- [x] ~~User Agent 响应结构能被 Orchestrator 直接包装返回。~~

## 2. 查询处理

- [x] ~~实现报销查询处理器。~~
- [x] ~~实现应收查询处理器。~~
- [x] ~~实现应付查询处理器。~~
- [ ] 查询前检查权限级别。
- [x] ~~查询时记录 ToolCall。~~
- [x] ~~查询失败时返回可读错误。~~
- [x] ~~查询为空时返回空态解释。~~
- [ ] 查询结果限制返回条数，避免一次返回过大。

验收证据：

- [x] ~~“查本周报销金额”有可读回答。~~
- [x] ~~“客户 A 本月应收多少”有可读回答。~~
- [x] ~~“供应商 B 待付款多少”有可读回答。~~

## 3. 规则解释

- [x] ~~根据语义场景查询相关规则资产。~~
- [x] ~~只引用 active 规则。~~
- [x] ~~读取规则当前版本 Markdown。~~
- [x] ~~从 Markdown 中提取规则摘要。~~
- [x] ~~回答中说明使用了哪些规则。~~
- [x] ~~回答中包含规则版本号。~~
- [x] ~~回答中包含规则更新时间。~~
- [x] ~~没有相关规则时说明缺失。~~

验收证据：

- [x] ~~“为什么这笔报销有风险”能引用规则。~~

## 4. 风险解释

- [x] ~~识别重复报销风险。~~
- [x] ~~识别金额超标风险。~~
- [x] ~~识别发票异常风险。~~
- [x] ~~识别逾期应收风险。~~
- [x] ~~识别逾期应付风险。~~
- [x] ~~风险回答包含风险类型。~~
- [x] ~~风险回答包含触发原因。~~
- [x] ~~风险回答包含建议处理动作。~~
- [x] ~~高风险建议不能变成自动执行。~~

验收证据：

- [x] ~~风险解释结果不是单纯“有风险”，而是有依据。~~

## 5. 草稿生成与单据落库

- [x] ~~支持根据语义结果创建 `expense_claims` 草稿。~~
- [x] ~~报销草稿初始状态写为 `draft`。~~
- [x] ~~支持根据语义结果创建或更新 `expense_claim_items`。~~
- [ ] 支持把用户上传附件挂到 `document_assets`、`document_asset_versions`、`expense_item_documents`。
- [ ] 支持把 OCR 识别快照写入 `document_ocr_results`，并保留 `ocr_engine`、`ocr_model`、`raw_json`、`confidence`。
- [x] ~~对话中补充金额、发生时间、费用类型等已落地字段后，能回写已有草稿而不是只更新内存结果。~~
- [x] ~~支持生成报销处理意见草稿。~~
- [x] ~~支持生成应收催收建议草稿。~~
- [x] ~~支持生成应付付款建议草稿。~~
- [ ] 用户明确确认“提交报销”后，把 `expense_claims.status` 从 `draft` 更新为 `submitted`。
- [ ] 报销提交时写入 `submitted_at`。
- [ ] 报销状态变更写入审计日志。
- [ ] 报销状态变更写入 AgentRun 结果。
- [x] ~~草稿中标明“待人工确认”。~~
- [x] ~~草稿不直接提交业务系统。~~
- [x] ~~草稿生成写入审计日志。~~
- [x] ~~草稿生成写入 AgentRun 结果。~~
- [ ] 草稿创建或更新后向前端返回 `attachment_ids`。
- [x] ~~草稿创建或更新后向前端返回 `claim_id`、`claim_no`、`status`。~~

验收证据：

- [ ] “我今天去客户现场，招待了客户，花销了1000元”在补齐必要字段后可创建报销草稿。
- [ ] “帮我提交这笔报销”在确认后只把状态改到 `submitted`，不会直接改成 `approved` 或 `paid`。
- [x] ~~“帮我生成处理意见”只返回草稿，不执行审批。~~

## 6. 知识库读取骨架

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

验收证据：

- [ ] 知识库失败不会导致整个回答失败。

## 7. 对话或操作入口

- [x] ~~前端增加用户问题输入框。~~
- [x] ~~输入框支持回车或按钮提交。~~
- [x] ~~提交时调用 Orchestrator，而不是绕过 Orchestrator。~~
- [x] ~~提交时透传首句文本。~~
- [x] ~~提交时透传附件名称。~~
- [x] ~~提交时透传 OCR 摘要。~~
- [x] ~~提交时透传页面上下文。~~
- [x] ~~提交时透传 `conversation_id` 与 `draft_claim_id`。~~
- [ ] 提交时透传附件 ID。
- [x] ~~展示 Agent 回答。~~
- [x] ~~展示引用规则或知识。~~
- [x] ~~展示建议动作。~~
- [x] ~~展示识别意图摘要、待确认字段和确认动作卡片。~~
- [x] ~~展示逐票据 OCR 识别结果，并支持按 1、2、3… 顺序查看。~~
- [x] ~~展示多场景票据的分单建议。~~
- [ ] 展示报销草稿 ID 或 claim_no。
- [ ] 展示当前报销状态。
- [x] ~~展示需要人工确认的提示。~~
- [x] ~~展示 `run_id`。~~
- [x] ~~展示加载态。~~
- [x] ~~展示错误态。~~

验收证据：

- [x] ~~用户可在页面完成一次问答闭环。~~

## 8. 安全边界

- [x] ~~User Agent 不直接修改规则状态。~~
- [x] ~~User Agent 不直接上线规则。~~
- [x] ~~User Agent 不直接审批报销。~~
- [x] ~~User Agent 不直接把报销单改为 `approved` 或 `paid`。~~
- [x] ~~User Agent 不直接付款。~~
- [x] ~~User Agent 不直接删除知识。~~
- [x] ~~所有高风险动作只返回建议或草稿。~~
- [ ] 报销从 `draft` 变更到 `submitted` 之前必须有用户确认。
- [ ] 所有草稿动作标记 `requires_confirmation=true`。
- [x] ~~语义低置信度时优先追问，不返回答非所问的查询结果。~~
- [x] ~~没有 OCR/VLM 结果时，不假装读懂图片或票据内容。~~

验收证据：

- [x] ~~提示词要求“直接付款”时仍被阻断。~~

## 9. 测试

- [x] ~~测试报销查询。~~
- [x] ~~测试应收查询。~~
- [ ] 测试应付查询。
- [ ] 测试规则解释。
- [x] ~~测试风险解释。~~
- [ ] 测试 OCR 摘要透传后，User Agent 能在回答中正确引用附件语境而不编造内容。
- [x] ~~测试报销草稿创建。~~
- [x] ~~测试报销草稿补槽更新。~~
- [ ] 测试报销状态从 `draft` 变更到 `submitted`。
- [x] ~~测试草稿生成。~~
- [ ] 测试越权动作阻断。
- [ ] 测试知识库降级。

验收证据：

- [x] ~~User Agent 核心测试通过。~~

## 10. Day 5 验收

- [x] ~~User Agent 服务可被 Orchestrator 调用。~~
- [x] ~~用户入口可提交自然语言问题。~~
- [x] ~~至少 3 个财务场景有回答。~~
- [x] ~~语义识别完整后的报销输入能创建报销草稿。~~
- [ ] 用户确认后能提交报销并更新状态。
- [x] ~~回答能引用规则或知识。~~
- [x] ~~高风险动作不会自动执行。~~
- [x] ~~AgentRun Trace 能看到 User Agent 步骤。~~
- [x] ~~前端构建通过。~~
- [x] ~~所有完成项已用 `[x] ~~...~~` 标记。~~

## 阻塞记录

- [x] ~~暂无。~~

## 日终交接

- [x] ~~当前已支持报销 / 应收 / 应付查询、规则解释、风险解释、草稿建议与澄清追问。~~
- [x] ~~当前已支持附件名称、OCR 摘要和页面上下文进入对话链路，但这还不是附件真实持久化。~~
- [x] ~~当前已把用户一句话和多票据输入转成结构化预审面板，开始支持字段确认、票据核对和分单建议，而不再只是返回一段文本。~~
- [x] ~~当前仍是占位的主要能力是报销单真实落库、附件持久化、OCR 结果入表和知识库读取，不再是简单静态问答 Mock。~~
- [x] ~~Day 6 Hermes 可直接复用当前的规则检查、风险标签和 Orchestrator Trace / ToolCall 契约。~~