docs: 新增agent开发文档和风险评估文档

2026-05-15 06:58:21 +00:00
parent 45abd36430
commit 4f3556a38b
35 changed files with 8257 additions and 0 deletions
--- a/document/development/agent/agent
+++ b/document/development/agent/agent
@@ -0,0 +1,284 @@
+# 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`，并已收敛为“识别结果专用区”：核心识别摘要、时间换算说明、逐票据识别结果、可能单据类型、建议归属费用和 OCR 置信度。~~
+- [x] ~~个人工作台和报销对话框已接入 `conversation_id` / `draft_claim_id`，同一会话内的连续追问不再按全新请求处理。~~
+- [x] ~~个人工作台已支持“继续会话 / 新建会话”，并可恢复最近一次用户会话或清空旧会话后重新开始。~~
+- [x] ~~报销核对流已切到产品化交互：正文区负责 AI 式核对提示、待补充信息、风险提醒和底部动作区，右侧只承载识别结果与票据识别明细，动作固定为“取消 / 修改识别信息 / 保存草稿或下一步”。~~
+- [ ] 真实 `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] ~~正文区改为简洁核对提示，不再堆叠调度结果或运行明细。~~
+- [x] ~~正文区待补充信息和风险提示已改为紧凑高亮样式，避免出现大段冗长说明。~~
+- [x] ~~展示逐票据 OCR 识别结果，并支持按 1、2、3… 顺序查看。~~
+- [x] ~~右侧逐票据结果已补充“可能单据类型 / 建议归属费用 / 识别置信度”等识别信息。~~
+- [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 契约。~~