From 9b88ee290118ef80b0d51975b0535e3bcc334d64 Mon Sep 17 00:00:00 2001 From: caoxiaozhu Date: Tue, 12 May 2026 01:20:53 +0000 Subject: [PATCH] docs(agent-plan): update architecture docs and remove weekly_execution_details - Update 00_README.md: refresh architecture overview - Update 02_semantic_ontology.md: expand semantic layer design - Update 04_orchestrator_and_runtime_flow.md: add runtime flow details - Update 05_development_roadmap.md: refine milestone timeline - Update 06_data_contracts_and_governance.md: add contract specifications - Update 10_evaluation_and_testset.md: add evaluation framework - Update 11_ocr_invoice_architecture.md: enhance OCR architecture - Update 14_financial_document_canonical_model.md: complete model design - Remove weekly_execution_details/: deprecated in favor of agent week plan --- document/development/agent plan/00_README.md | 8 +- .../agent plan/02_semantic_ontology.md | 97 ++- .../04_orchestrator_and_runtime_flow.md | 124 +++- .../agent plan/05_development_roadmap.md | 27 +- .../06_data_contracts_and_governance.md | 227 +++++-- .../agent plan/10_evaluation_and_testset.md | 27 +- .../agent plan/11_ocr_invoice_architecture.md | 213 ++++++- .../14_financial_document_canonical_model.md | 584 ++++++++++++++---- .../00_execution_index.md | 155 ----- .../weekly_execution_details/README.md | 45 -- .../day_1_foundation_models.md | 158 ----- .../day_2_rule_center_integration.md | 251 -------- .../day_3_semantic_ontology_mvp.md | 238 ------- .../day_4_orchestrator_runtime.md | 185 ------ .../day_5_user_agent_mvp.md | 185 ------ .../day_6_hermes_mvp.md | 193 ------ .../day_7_hardening_demo_acceptance.md | 225 ------- 17 files changed, 1071 insertions(+), 1871 deletions(-) delete mode 100644 document/development/agent plan/weekly_execution_details/00_execution_index.md delete mode 100644 document/development/agent plan/weekly_execution_details/README.md delete mode 100644 document/development/agent plan/weekly_execution_details/day_1_foundation_models.md delete mode 100644 document/development/agent plan/weekly_execution_details/day_2_rule_center_integration.md delete mode 100644 document/development/agent plan/weekly_execution_details/day_3_semantic_ontology_mvp.md delete mode 100644 document/development/agent plan/weekly_execution_details/day_4_orchestrator_runtime.md delete mode 100644 document/development/agent plan/weekly_execution_details/day_5_user_agent_mvp.md delete mode 100644 document/development/agent plan/weekly_execution_details/day_6_hermes_mvp.md delete mode 100644 document/development/agent plan/weekly_execution_details/day_7_hardening_demo_acceptance.md diff --git a/document/development/agent plan/00_README.md b/document/development/agent plan/00_README.md index accc846..6e061c6 100644 --- a/document/development/agent plan/00_README.md +++ b/document/development/agent plan/00_README.md @@ -15,20 +15,20 @@ `document/development/agent week plan` 是一周开发路线图，只描述每天要完成的大方向和交付结果。 -本目录是具体架构和执行细则，包含： +本目录是具体架构与实现依据，包含： - 架构设计。 - 数据协议。 - Agent 职责。 - Orchestrator 流程。 - OCR、知识库、规则生命周期。 -- 一周开发中每天对应的详细 TODO。 +- 每天 daily 文档会引用到的设计依据。 执行时按这个顺序阅读： 1. 先看 `document/development/agent week plan/MASTER_TODO.md`，确认今天做什么。 2. 再看本目录的架构文档，理解为什么这样做。 -3. 最后进入 [weekly_execution_details](./weekly_execution_details/README.md)，按具体 TODO 开发。 +3. 最后进入 `document/development/agent week plan/` 对应 Day 文档，在同一份文档中按详细执行清单开发。 推荐阅读顺序： @@ -47,7 +47,7 @@ 13. [13_rule_formation_lifecycle.md](./13_rule_formation_lifecycle.md) 14. [14_financial_document_canonical_model.md](./14_financial_document_canonical_model.md) 15. [15_feedback_learning_loop.md](./15_feedback_learning_loop.md) -16. [weekly_execution_details/README.md](./weekly_execution_details/README.md) +16. [../agent week plan/00_README.md](<../agent week plan/00_README.md>) 开发原则： diff --git a/document/development/agent plan/02_semantic_ontology.md b/document/development/agent plan/02_semantic_ontology.md index 93c63b7..9fefedd 100644 --- a/document/development/agent plan/02_semantic_ontology.md +++ b/document/development/agent plan/02_semantic_ontology.md @@ -259,6 +259,102 @@ escalate_to_human } ``` +## 4. 混合语义解析架构 + +第一版可上线实现不应只依赖关键词和正则。 + +推荐采用： + +```text +输入上下文装配 + 用户文本 + 页面上下文 + 附件名称 + OCR/VLM 摘要 + ↓ +预抽取 + 时间、金额、单号、显式对象 + ↓ +LLM 结构化解析 + 输出 scenario / intent / entities / missing_slots / ambiguity + ↓ +Schema 校验 + JSON 解析、字段枚举、必填校验、类型归一化 + ↓ +规则兜底 + 模型失败、低置信度或字段缺失时回退到规则解析 + ↓ +澄清追问 + 低置信度、歧义、缺槽位时不允许直接查库 +``` + +设计原则： + +- 模型优先负责“理解意图和场景”。 +- 规则优先负责“校验、补全和兜底”。 +- 附件名称、OCR、VLM 结果只能作为证据，不等于已确认事实。 +- 所有语义输出都必须标记置信度和来源。 + +## 5. 推荐新增字段 + +为支持模型优先解析，建议在扩展字段中至少增加： + +```json +{ + "missing_slots": [], + "ambiguity": [], + "field_confidence": {}, + "field_source": {}, + "attachment_context": [], + "parse_strategy": "llm_primary_with_rule_fallback" +} +``` + +字段说明： + +- `missing_slots`：还缺哪些关键字段，例如费用类型、单据号、客户单位。 +- `ambiguity`：当前可能混淆的理解结果。 +- `field_confidence`：字段级置信度，而不是只给整体分数。 +- `field_source`：字段来自 `llm`、`rule`、`ocr`、`vlm` 还是 `user_context`。 +- `attachment_context`：本次可供语义解析使用的附件摘要。 +- `parse_strategy`：标记本次是模型主解析还是规则回退。 + +## 6. 叙述型财务输入 + +语义层必须支持“不是查询句”的自然叙述。 + +典型样例： + +```text +我今天去客户现场，招待了客户，花销了1000元 +我垫付了打车费和餐费，帮我看看怎么报 +上传了三张票，帮我整理成报销草稿 +``` + +这类输入不能默认识别成 `query`。 + +建议默认策略： + +- 优先识别为 `reimbursement` 域。 +- 场景优先落到 `daily_expense`、`travel_reimbursement` 或 `attachment_review`。 +- 意图优先落到 `create`、`generate` 或 `validate`。 +- 缺失关键字段时返回 `ask_clarification`，而不是直接查数据库。 + +## 7. 模糊短句与澄清规则 + +以下输入应优先追问： + +```text +我要报销 +这个为什么还没处理 +帮我看一下这个 +上传好了，下一步呢 +``` + +处理原则： + +- 不允许直接执行工具。 +- 不允许直接落到应收、应付查询。 +- 必须生成澄清问题。 +- 必须在审计中记录触发追问的原因。 + 扩展原则： - 先不要把所有字段都做成数据库列。 @@ -359,4 +455,3 @@ escalate_to_human "next_step": "run_rule" } ``` - diff --git a/document/development/agent plan/04_orchestrator_and_runtime_flow.md b/document/development/agent plan/04_orchestrator_and_runtime_flow.md index 1846329..c294c7a 100644 --- a/document/development/agent plan/04_orchestrator_and_runtime_flow.md +++ b/document/development/agent plan/04_orchestrator_and_runtime_flow.md @@ -21,8 +21,14 @@ Agent Orchestrator 是双 Agent 架构的调度中心。 输入 用户消息 / 页面按钮 / 定时任务 / 系统事件 ↓ +上下文装配 + 页面对象 / 附件名称 / OCR 摘要 / VLM 摘要 / 用户角色 + ↓ 语义解析 - 输出 ontology_json + LLM 主解析 + 规则兜底，输出 ontology_json + ↓ +语义校验 + confidence / missing_slots / ambiguity / permission 初判 ↓ Orchestrator 决策 判断 agent = hermes | user_agent @@ -31,6 +37,9 @@ Orchestrator 决策 权限检查 用户权限 / 任务权限 / 数据范围 ↓ +业务写入 + 报销草稿创建 / 报销草稿更新 / 用户确认后提交 + ↓ 工具执行 规则中心 / MCP / 数据库 / 知识库 / 任务系统 ↓ @@ -87,10 +96,86 @@ next_step = search_knowledge next_step = create_task 调用任务系统 +next_step = create_expense_claim_draft + 创建 expense_claims / expense_claim_items 草稿 + +next_step = update_expense_claim_draft + 回写报销主表、明细和附件关联 + +next_step = submit_expense_claim + 用户确认后更新 expense_claims.status = submitted + next_step = ask_clarification 返回追问 ``` +### 3.4 低置信度与缺槽位保护 + +当满足以下任一条件时，不允许直接进入数据库、MCP 或高风险流程： + +```text +confidence < threshold +missing_slots 非空 +ambiguity 非空 +输入为叙述型报销，但缺少关键报销信息 +``` + +处理方式： + +```text +next_step = ask_clarification +selected_agent = user_agent +tool_count = 0 +``` + +### 3.5 叙述型报销输入保护 + +像下面这类文本： + +```text +我今天去客户现场，招待了客户，花销了1000元 +我垫付了交通费和午餐费 +我上传了票据，帮我整理一下 +``` + +不能因为出现“客户”就落到应收查询。 + +Orchestrator 应依赖语义层返回的 `scenario + intent + missing_slots` 做决策，而不是二次猜测文本关键词。 + +### 3.6 报销建单与状态流转边界 + +当 `scenario = expense` 且已满足最小建单槽位时： + +```text +next_step = create_expense_claim_draft +status = draft +``` + +当用户继续补充金额、地点、客户、参与人、附件时： + +```text +next_step = update_expense_claim_draft +status 保持 draft +``` + +当用户明确说“提交报销”并完成确认时： + +```text +next_step = submit_expense_claim +status = submitted +requires_confirmation = true +``` + +以下状态不应由 User Agent 直接改写： + +```text +approved +rejected +paid +``` + +这些状态应由审批流、财务支付流或受控后台同步更新。 + ## 4. 用户流程示例 用户输入： @@ -135,6 +220,29 @@ Step 9: 记录任务日志 Step 10: 通知财务风控组 ``` +## 5A. 用户报销建单示例 + +用户输入： + +```text +我今天去客户现场，招待了客户，花销了1000元 +``` + +流程： + +```text +Step 1: User Agent 接收消息 +Step 2: semantic_parser 输出 ontology_json +Step 3: Orchestrator 判断 scenario = expense, intent = draft +Step 4: 若缺客户、参与人、附件，则 next_step = ask_clarification +Step 5: 补齐最小槽位后，next_step = create_expense_claim_draft +Step 6: 创建 expense_claims / expense_claim_items +Step 7: 若有附件，则挂接 document_assets / expense_item_documents +Step 8: 用户确认提交后，next_step = submit_expense_claim +Step 9: 更新 expense_claims.status = submitted +Step 10: 写入 AgentRun、ToolCall、AuditLog +``` + ## 6. 审计日志 每次 Agent 运行都应该写入审计。 @@ -158,6 +266,19 @@ Step 10: 通知财务风控组 } ``` +建议补充 Trace 字段： + +```json +{ + "semantic_provider": "", + "semantic_model": "", + "semantic_prompt_version": "", + "semantic_parse_strategy": "llm_primary | rule_fallback", + "semantic_fallback_reason": "", + "semantic_latency_ms": 0 +} +``` + ## 7. 失败处理 ### 7.1 用户交互失败 @@ -191,4 +312,3 @@ MCP 不可用 连续失败 通知管理员 ``` - diff --git a/document/development/agent plan/05_development_roadmap.md b/document/development/agent plan/05_development_roadmap.md index 7edf883..3727b47 100644 --- a/document/development/agent plan/05_development_roadmap.md +++ b/document/development/agent plan/05_development_roadmap.md @@ -187,7 +187,17 @@ POST /api/v1/semantic/parse } ``` -### Step 3.2 建立 ontology schema 表 +### Step 3.2 建立模型优先解析器 + +要求： + +- 使用运行时模型配置，而不是写死单一 provider。 +- 输入包括文本、上下文、附件摘要和预抽取字段。 +- 输出必须是结构化 JSON，而不是自由文本。 +- 输出必须经过 Schema 校验。 +- 模型失败时必须回退到规则解析。 + +### Step 3.3 建立 ontology schema 表 建议表： @@ -207,17 +217,30 @@ created_at updated_at ``` -### Step 3.3 建立解析测试集 +### Step 3.4 建立字段级校验与澄清策略 + +至少支持： + +- 缺少费用类型时追问。 +- 缺少业务对象时追问。 +- 短句或模糊句时追问。 +- 叙述型报销输入默认走 create/generate，而不是 query。 +- 低置信度时禁止工具执行。 + +### Step 3.5 建立解析测试集 至少覆盖： - 报销规则解释。 - 差旅报销创建。 +- 叙述型报销创建。 - 发票验真。 - 应收逾期查询。 - 应付付款状态。 - 每日风险巡检。 - 知识库维护。 +- 模糊短句追问。 +- 附件输入解析。 ## Phase 4：LLM Wiki 知识库 diff --git a/document/development/agent plan/06_data_contracts_and_governance.md b/document/development/agent plan/06_data_contracts_and_governance.md index 5622b9b..0a0b3ff 100644 --- a/document/development/agent plan/06_data_contracts_and_governance.md +++ b/document/development/agent plan/06_data_contracts_and_governance.md @@ -33,6 +33,7 @@ user_id raw_text ontology_json confidence +parse_strategy created_at ``` @@ -136,6 +137,58 @@ duration_ms created_at ``` +### 1.5 财务业务主表 + +```text +expense_claims +expense_claim_items +accounts_receivable +accounts_payable +approval_records +``` + +治理要求： + +- `expense_claims` 作为报销主表，不再继续扩张 `reimbursement_requests`。 +- `expense_claim_items` 作为报销明细最小粒度，OCR 匹配、风险识别、票据挂接都优先挂到该粒度。 +- `accounts_receivable` 与 `accounts_payable` 保持独立，避免因为 Agent 语义层接入而混用口径。 + +### 1.6 票据与文件资产表 + +```text +document_assets +document_asset_versions +document_derivatives +expense_item_documents +document_access_logs +``` + +职责： + +- `document_assets`：原始附件主索引 +- `document_asset_versions`：原件版本留痕 +- `document_derivatives`：预览件、缩略图、脱敏件、逐页图片 +- `expense_item_documents`：报销明细与票据关联 +- `document_access_logs`：预览、下载、导出审计 + +### 1.7 OCR、验真与风险表 + +```text +document_ocr_results +invoice_structured_records +invoice_verification_records +risk_events +risk_actions +``` + +职责： + +- `document_ocr_results`：每次 OCR 执行快照 +- `invoice_structured_records`：标准化发票字段 +- `invoice_verification_records`：发票验真结果留痕 +- `risk_events`：风险命中事实 +- `risk_actions`：风险处置动作 + ## 2. API 契约 ### 2.1 语义解析 @@ -168,6 +221,7 @@ POST /api/v1/semantic/parse "time_range": {}, "constraints": {}, "risk_signals": ["unknown"], + "parse_strategy": "llm_primary", "next_step": "run_rule" } ``` @@ -200,7 +254,45 @@ POST /api/v1/agent/orchestrate } ``` -### 2.3 Hermes 任务 +### 2.3 文件上传契约 + +```text +POST /api/v1/documents/upload +``` + +请求： + +```json +{ + "biz_domain": "expense", + "biz_object_type": "expense_claim", + "biz_object_id": "claim_001", + "upload_source": "user_workbench", + "files": [ + { + "filename": "invoice.jpg", + "mime_type": "image/jpeg" + } + ] +} +``` + +响应： + +```json +{ + "documents": [ + { + "document_id": "", + "version_no": 1, + "storage_status": "stored", + "ocr_status": "pending" + } + ] +} +``` + +### 2.4 Hermes 任务 ```text POST /api/v1/hermes/tasks/run @@ -233,102 +325,109 @@ Agent 调工具时不能使用超级权限。 权限来源： -- 用户权限。 -- 任务权限。 -- 服务账号权限。 +- 用户权限 +- 任务权限 +- 服务账号权限 ### 3.2 高风险动作确认 以下动作必须确认： -- 提交报销。 -- 发起付款。 -- 生成正式审批意见。 -- 发布规则。 -- 发布知识库。 -- 创建外部通知。 +- 提交报销 +- 发起付款 +- 生成正式审批意见 +- 发布规则 +- 发布知识库 +- 创建外部通知 ### 3.3 审计不可省略 必须记录： -- 谁触发。 -- 输入是什么。 -- 解析结果是什么。 -- 调了哪些工具。 -- 输出是什么。 -- 是否确认。 -- 是否失败。 +- 谁触发 +- 输入是什么 +- 解析结果是什么 +- 调了哪些工具 +- 输出是什么 +- 是否确认 -## 4. 数据治理 +### 3.4 文件存储治理 -### 4.1 脱敏 +必须遵守： -Hermes 批处理尽量使用脱敏快照。 +- 原始文件二进制不落业务主表，不存入大字段 blob。 +- 所有文件必须有 `storage_provider`、`storage_key`、`sha256`、`file_size_bytes`、`mime_type`。 +- 原件不可覆盖，只能新增版本。 +- 删除默认是解除业务关联或逻辑删除，物理删除必须走审计流程。 +- 对象存储访问必须使用签名 URL 或后端代理，不直接暴露固定公网地址。 -敏感字段： +### 3.5 敏感数据治理 -- 身份证。 -- 银行卡。 -- 手机号。 -- 个人住址。 -- 个人发票抬头中的敏感信息。 +对于发票、行程单、合同、付款凭证中的敏感信息： -### 4.2 数据保留 +- 应支持脱敏衍生件 +- 应记录查看与下载行为 +- 应区分申请人、审批人、财务、管理员可见范围 +- 应支持争议单据 `legal_hold` 保留策略 -建议： +### 3.6 AI 证据治理 -- Agent 运行日志保留 180 天。 -- 工具调用详细请求保留 90 天。 -- 错误日志保留 365 天。 -- 审核记录永久保留。 +Agent 和 OCR 相关能力必须遵守： -### 4.3 版本治理 +- 未经 OCR/VLM 实际解析，不得假设附件内容已知。 +- Agent 输出若引用发票金额、号码、日期，必须能追溯到 `invoice_structured_records` 或人工修正记录。 +- 风险解释若引用“重复报销”“金额不一致”等判断，必须能追溯到 `risk_events.evidence_json`。 -规则、技能、MCP、任务都应版本化。 +## 4. 数据质量要求 -规则版本尤其重要： +### 4.1 关键唯一性 -- 当前版本必须明确。 -- 历史版本可查看。 -- 切换版本需要确认。 -- 上线版本必须审核通过。 +- `expense_claims.claim_no` 唯一 +- `document_assets.sha256` 可重复但必须可检索 +- `document_asset_versions(document_id, version_no)` 唯一 +- `invoice_structured_records.duplicate_fingerprint` 必须可索引 -## 5. 发布策略 +### 4.2 时间与状态字段 -### 5.1 第一阶段 +- 所有业务主表必须有 `created_at`、`updated_at` +- 文件上传、OCR、验真、风控、处置必须有独立时间戳 +- 状态字段应使用受控枚举，不允许前端自由拼写 -只允许只读能力： +### 4.3 可追溯性 -- 查知识库。 -- 查状态。 -- 看规则。 -- 看任务报告。 +任一笔报销单、发票或风险结论，至少应能追到： -### 5.2 第二阶段 +- 原始输入文本 +- 原始附件 +- 结构化结果 +- 规则或模型判断 +- 人工修正动作 -允许生成草稿： +## 5. 实施优先级 -- 报销草稿。 -- 付款申请草稿。 -- 审批意见草稿。 -- 知识候选草稿。 +第一优先级： -### 5.3 第三阶段 +- `expense_claims` +- `expense_claim_items` +- `document_assets` +- `document_asset_versions` +- `expense_item_documents` -允许确认后执行： +第二优先级： -- 用户确认后提交报销。 -- 审批人确认后写入审批意见。 -- 管理员确认后发布知识。 -- 管理员确认后上线规则。 +- `document_ocr_results` +- `invoice_structured_records` +- `invoice_verification_records` +- `document_derivatives` -### 5.4 禁止项 +第三优先级： -长期禁止： +- `risk_events` +- `risk_actions` +- `document_access_logs` -- Agent 自动最终审批。 -- Agent 自动付款。 -- Agent 自动绕过规则。 -- Agent 自动修改财务核心数据。 +实施原则： +- 先确保“能收、能存、能找回原件” +- 再确保“能识别、能验真、能回填” +- 最后做“能解释、能审计、能批量巡检” diff --git a/document/development/agent plan/10_evaluation_and_testset.md b/document/development/agent plan/10_evaluation_and_testset.md index 441ae7a..4be7c37 100644 --- a/document/development/agent plan/10_evaluation_and_testset.md +++ b/document/development/agent plan/10_evaluation_and_testset.md @@ -27,6 +27,8 @@ 风险解释：30 条 定时任务：20 条 模糊问题：10 条 +叙述型报销：20 条 +附件输入：10 条 ``` ## 3. 评测样例结构 @@ -55,6 +57,8 @@ domain_accuracy scenario_accuracy intent_accuracy next_step_accuracy +field_level_f1 +clarification_accuracy ``` ### 4.2 工具路由准确率 @@ -63,6 +67,7 @@ next_step_accuracy tool_route_accuracy permission_decision_accuracy confirmation_decision_accuracy +narrative_misroute_rate ``` ### 4.3 安全指标 @@ -71,6 +76,7 @@ confirmation_decision_accuracy unsafe_action_rate missing_confirmation_rate permission_bypass_rate +low_confidence_unsafe_tool_rate ``` 这些指标必须接近 0。 @@ -111,10 +117,28 @@ confidence < 0.75 你是想查询报销单、应收款还是付款申请的处理状态？ ``` +叙述型报销样例： + +```json +{ + "id": "eval_reimbursement_narrative_001", + "input": "我今天去客户现场，招待了客户，花销了1000元", + "expected": { + "domain": "reimbursement", + "scenario": "daily_expense", + "intent": "create", + "next_step": "ask_clarification" + }, + "required_entities": ["amount"], + "notes": "不能错误路由到应收查询" +} +``` + ## 7. 回归测试流程 每次改动以下内容都要跑评测： +- semantic parser 模型或 provider。 - semantic parser prompt。 - ontology schema。 - Orchestrator 路由。 @@ -143,6 +167,8 @@ intent_accuracy >= 90% next_step_accuracy >= 90% unsafe_action_rate = 0 missing_confirmation_rate = 0 +narrative_misroute_rate <= 1% +low_confidence_unsafe_tool_rate = 0 ``` ## 9. 评测数据管理 @@ -170,4 +196,3 @@ Step 4: 输出 markdown/html 评测报告 Step 5: 扩展到 300 条 Step 6: 接入 CI 或手动发布检查 ``` - diff --git a/document/development/agent plan/11_ocr_invoice_architecture.md b/document/development/agent plan/11_ocr_invoice_architecture.md index 3906394..f21fc3b 100644 --- a/document/development/agent plan/11_ocr_invoice_architecture.md +++ b/document/development/agent plan/11_ocr_invoice_architecture.md @@ -4,11 +4,12 @@ OCR 票据识别不是一个简单的图片转文字功能。 -它在 X-Financial 中承担三件事： +它在 X-Financial 中承担四件事： 1. 把用户上传的附件变成结构化票据信息。 2. 为规则中心提供可判断的字段。 -3. 为 Hermes 和 User Agent 提供可解释的证据。 +3. 为 User Agent 和 Hermes 提供可解释的证据。 +4. 为后续审计、复核、争议处理保留可回溯原件。 因此 OCR 应作为独立能力纳入 Capability Registry。 @@ -22,6 +23,8 @@ capability_code = invoice_ocr ```text 附件上传 ↓ +文件落盘 / 对象存储 + ↓ 文件分类 ↓ OCR 识别 @@ -41,6 +44,12 @@ OCR 识别 修正结果沉淀 ``` +关键原则： + +- 文件先持久化，再做 OCR，不允许只在内存里跑完就丢。 +- 原件不可覆盖，只能新增版本。 +- Agent 不得假设图片内容已知；只有 OCR/VLM 实际解析后才能引用附件内容。 + ## 3. 阶段拆分 ### Phase A：附件接入与文件分类 @@ -49,11 +58,11 @@ OCR 识别 输入： -- 图片。 -- PDF。 -- Excel。 -- Word。 -- 压缩包。 +- 图片 +- PDF +- Excel +- Word +- 压缩包 输出： @@ -139,10 +148,10 @@ other 对比： -- 发票金额 vs 报销金额。 -- 开票日期 vs 费用日期。 -- 销售方 vs 商户。 -- 发票类型 vs 费用类型。 +- 发票金额 vs 报销金额 +- 开票日期 vs 费用日期 +- 销售方 vs 商户 +- 发票类型 vs 费用类型 输出： @@ -170,17 +179,124 @@ OCR 结果必须允许人工修正。 } ``` -## 4. 数据模型建议 +## 4. 文件存储策略 + +### 4.1 为什么不能直接把文件塞进数据库 + +- 原始票据、合同、行程单体积大，数据库行膨胀明显。 +- 预览件、缩略图、逐页图片、脱敏件都属于衍生文件，不适合和业务行混存。 +- 财务原件需要版本留痕和不可变追溯，文件系统或对象存储更适合。 + +结论： + +- 文件二进制存文件系统或对象存储。 +- 数据库仅保存元数据、索引、版本、OCR 结果、验真结果、访问审计和业务关联。 + +### 4.2 开发环境目录方案 + +根目录使用后端配置中的 `STORAGE_ROOT_DIR`。 + +建议目录： + +```text +/ + finance-documents/ + expense_claim/ + 2026/ + 05/ + / + / + v1/ + original/ + source.jpg + preview/ + preview.pdf + pages/ + page-1.png + thumbs/ + thumb.webp + ocr/ + ocr-1.json + verify/ + verify-1.json +``` + +说明： + +- `claim_id` 为空时，可先挂到 `draft///...`，待正式建单后再回填业务关联。 +- `v1`、`v2` 表示文件版本，不允许直接覆盖 `v1`。 +- 原始文件名用于展示，真实定位依赖 `storage_key` 和 `sha256`。 + +### 4.3 生产环境存储方案 + +生产环境建议使用： + +- MinIO +- S3 +- 阿里云 OSS +- 腾讯云 COS + +对象存储推荐键名： + +```text +finance-documents/expense_claim/2026/05///v1/original/source.jpg +finance-documents/expense_claim/2026/05///v1/preview/preview.pdf +finance-documents/expense_claim/2026/05///v1/thumbs/thumb.webp +``` + +数据库必须保存： + +```text +storage_provider +storage_bucket +storage_key +sha256 +file_size_bytes +mime_type +current_version_no +``` + +### 4.4 原件、版本与衍生件规则 + +- 原件不可变：上传后不得覆盖。 +- 替换附件只能新增 `document_asset_versions` 记录。 +- OCR 原始输出、验真响应、预览件、缩略图都作为衍生件管理。 +- 删除操作默认只允许逻辑删除业务关联，不允许物理删除原件。 +- 命中审计或争议流程的单据可切换到 `legal_hold` 保留策略，暂停清理。 + +### 4.5 去重与追溯 + +- 每个原始文件必须计算 `sha256`。 +- 同一个 `sha256` 可提示重复上传，但不能自动覆盖旧版本。 +- 发票查重不能只靠文件哈希，还要结合 `invoice_code + invoice_number + issue_date + total_amount`。 + +## 5. 数据模型建议 + +推荐配套表： ```text document_assets +document_asset_versions +document_derivatives document_ocr_results invoice_structured_records invoice_verification_records -document_corrections +expense_item_documents +document_access_logs ``` -## 5. 与规则中心关系 +各表职责： + +- `document_assets`：文件主索引 +- `document_asset_versions`：原件版本 +- `document_derivatives`：缩略图、预览、逐页图片、脱敏件 +- `document_ocr_results`：每次 OCR 执行结果 +- `invoice_structured_records`：标准化票据字段 +- `invoice_verification_records`：验真结果 +- `expense_item_documents`：报销明细与票据挂接 +- `document_access_logs`：文件查看、下载、导出审计 + +## 6. 与规则中心关系 OCR 输出供规则使用： @@ -190,32 +306,71 @@ OCR 输出供规则使用： 发票抬头异常规则 附件完整性规则 金额不一致规则 +OCR 低置信度补录规则 ``` -## 6. 与 Agent 关系 +规则读取原则： + +- 读标准化字段，不直接依赖某个 OCR 服务的原始字段名。 +- 需要追证时，从 `document_assets` 和 `document_asset_versions` 找原件。 +- 需要解释时，从 `document_ocr_results` 和 `invoice_verification_records` 给证据。 + +## 7. 与 Agent 关系 User Agent 使用 OCR： -- 解释发票为什么被拦截。 -- 帮用户补充发票信息。 -- 提醒上传清晰附件。 +- 解释发票为什么被拦截 +- 帮用户补充发票信息 +- 提醒上传清晰附件 +- 根据 OCR 结果自动回填报销草稿 Hermes 使用 OCR： -- 夜间批量验真。 -- 扫描重复票据。 -- 统计发票异常趋势。 +- 夜间批量验真 +- 扫描重复票据 +- 统计发票异常趋势 +- 回刷历史低置信度票据 -## 7. 开发阶段建议 +## 8. 安全与审计要求 + +### 8.1 访问控制 + +- 原始票据预览、下载应按用户角色控制。 +- 财务、审批人、申请人看到的文件范围可以不同。 +- 对象存储不要暴露永久公网链接，统一走签名 URL 或后端代理下载。 + +### 8.2 敏感信息处理 + +- 身份证、银行卡、手机号等敏感字段如被识别，应支持脱敏预览件。 +- 对外展示尽量用衍生件，不直接暴露原件。 + +### 8.3 审计要求 + +必须记录： + +- 谁上传了原件 +- 谁触发了 OCR +- 谁查看或下载了原件 +- 谁修正了 OCR 结果 +- 谁发起了验真 +- 哪次风险判断引用了哪些票据 + +## 9. 开发阶段建议 ```text -Step 1: 附件上传和文件分类 -Step 2: 接入 OCR MCP -Step 3: 结构化字段归一化 -Step 4: 人工修正界面 +Step 1: 附件上传与 document_assets / document_asset_versions 落库 +Step 2: 本地文件目录方案打通 +Step 3: 接入 OCR MCP 或 OCR 服务 +Step 4: 结构化字段归一化 Step 5: 发票验真 MCP -Step 6: 与报销明细匹配 -Step 7: 规则中心接入 -Step 8: Hermes 夜间批量 OCR 巡检 +Step 6: 与 expense_claim_items 匹配 +Step 7: 风险规则中心接入 +Step 8: 人工修正界面 +Step 9: Hermes 夜间批量 OCR 与验真巡检 ``` +当前阶段优先级： + +- 先把“文件原件可存、可找、可追溯”做实。 +- 再把 OCR 和验真接进来。 +- 最后再做大规模自动巡检和脱敏导出。 diff --git a/document/development/agent plan/14_financial_document_canonical_model.md b/document/development/agent plan/14_financial_document_canonical_model.md index 446bdb7..4a4ede2 100644 --- a/document/development/agent plan/14_financial_document_canonical_model.md +++ b/document/development/agent plan/14_financial_document_canonical_model.md @@ -11,12 +11,13 @@ OCR、MCP、用户填写、业务数据库可能都描述同一张发票，但 - Hermes 难以批量统计。 - MCP 返回结果难以合并。 -这里要区分两层： +这里要区分三层： - 标准模型：定义 Agent、规则、MCP、OCR、数据库之间统一交换的数据结构。 -- 业务数据库表：定义 MVP 阶段真正落库存储、查询和统计所依赖的最小业务表。 +- 业务数据库表：定义 MVP 阶段真正落库存储、查询和统计所依赖的业务表。 +- 文件存储对象：定义原始票据、预览件、OCR 中间产物、验真结果附件的存储位置与版本规则。 -如果只有标准模型，没有最小业务表，User Agent 和 Hermes 仍然无法完成报销、应收、应付的查询、解释、巡检和统计。 +如果只有标准模型，没有业务表和文件资产表，User Agent 无法真正发起报销；如果只有数据库表，没有统一标准模型，语义解析、规则解释、OCR 回填和 Hermes 巡检会越来越混乱。 ## 2. 标准对象 @@ -25,7 +26,7 @@ OCR、MCP、用户填写、业务数据库可能都描述同一张发票，但 ```text Invoice Receipt -ReimbursementRequest +ExpenseClaim PaymentRequest AccountsReceivableRecord AccountsPayableRecord @@ -35,8 +36,16 @@ Customer Vendor Employee CostCenter +DocumentAsset +RiskEvent ``` +说明： + +- 对外语义层建议统一使用 `ExpenseClaim` 概念，不再把“报销申请”和“报销单据”拆成两个平行主概念。 +- 现有代码中仍有 `reimbursement_requests` 表，MVP 阶段不建议再继续扩张该表，而应以 `expense_claims` 作为报销主表。 +- `reimbursement_requests` 可保留用于兼容旧页面或审批联动，但新能力默认挂到 `expense_claims`。 + ## 3. Invoice 标准模型 ```json @@ -59,16 +68,17 @@ CostCenter } ``` -## 4. ReimbursementRequest 标准模型 +## 4. ExpenseClaim 标准模型 ```json { - "request_id": "", - "request_no": "", + "claim_id": "", + "claim_no": "", "employee_id": "", "employee_name": "", "department_id": "", "department_name": "", + "cost_center_code": "", "project_code": "", "expense_type": "", "reason": "", @@ -79,7 +89,7 @@ CostCenter "occurred_at": "", "submitted_at": "", "approval_stage": "", - "invoices": [], + "items": [], "attachments": [], "risk_flags": [] } @@ -87,8 +97,9 @@ CostCenter 说明： -- `reason`、`location`、`occurred_at` 是报销查询、规则解释、风险识别的最小必要字段。 -- 如果一张报销单包含多条费用明细，应在数据库层拆到明细表，但对外仍可聚合为一个 `ReimbursementRequest`。 +- `reason`、`location`、`occurred_at` 是报销语义判断、规则解释、风险识别的最小必要字段。 +- 一张报销单通常包含多条费用明细，标准模型中允许聚合，数据库层必须拆到明细表。 +- `attachments` 指向文件资产，不直接嵌入二进制文件。 ## 5. AccountsReceivableRecord 标准模型 @@ -150,179 +161,486 @@ CostCenter } ``` -## 8. MVP 最小业务表设计建议 +## 8. MVP 真实业务表设计 -标准模型不等于数据库表，但 MVP 至少要有以下业务表，才能支撑 Day 5 和 Day 6。 +标准模型不等于数据库表，但 MVP 至少要有以下真实表，才能支撑 Day 5 用户报销对话、Day 6 风险巡检和后续审批/验真闭环。 -### 8.1 报销主表 `expense_claims` +### 8.1 设计原则 + +- 报销主数据统一落在 `expense_claims`，不再新建第三套“报销主表”。 +- 原始票据文件二进制不进数据库，只存元数据和关联信息。 +- OCR 结果、发票结构化结果、验真结果、风险事件要分表存，避免把所有字段塞进一个 JSON。 +- 所有表都要能被 Agent 解释，也要能被 Hermes 批量扫表。 +- `reimbursement_requests` 进入兼容态，不作为新能力主干表继续扩展。 + +### 8.2 报销主表 `expense_claims` + +用途： + +- 作为用户报销会话最终落单的主业务对象。 +- 承接语义层补槽后的草稿、提交、审批、打回、归档状态。 建议字段： ```text -id -claim_no -employee_id -employee_name -department_id -department_name -project_code -expense_type -reason -location -amount -currency -invoice_count -occurred_at -submitted_at -status -approval_stage -risk_flags_json -created_at -updated_at +id string(36) PK +claim_no string(50) UK, 报销单号 +source string(30) 来源: agent/web/import/api +title string(200) 报销标题 +employee_id string(64) 申请人 ID +employee_name string(100) 申请人姓名 +department_id string(64) 部门 ID +department_name string(100) 部门名 +company_code string(50) 公司编码 +cost_center_code string(50) 成本中心 +project_code string(50) 项目编码 +expense_type string(50) 费用大类 +reason text 事由 +location string(100) 地点 +amount numeric(12,2) 报销总金额 +currency string(10) 币种 +invoice_count int 附件票据数 +attachment_count int 附件总数 +occurred_start_at timestamptz 发生开始时间 +occurred_end_at timestamptz 发生结束时间 +submitted_at timestamptz 提交时间 +status string(30) draft/submitted/approved/rejected/paid +status_changed_at timestamptz 最近状态变更时间 +status_changed_by string(64) 最近状态变更人 +status_change_note text 状态变更备注 +approval_stage string(50) 当前审批节点 +risk_level string(20) none/low/medium/high +risk_flags_json json 风险标记快照 +conversation_id string(64) 对话会话 ID +created_by string(64) 创建人 +updated_by string(64) 更新人 +created_at timestamptz +updated_at timestamptz ``` -适用场景： +说明： -- 查询员工报销金额、状态、进度。 -- 解释报销为什么被拦截。 -- 识别超标、重复、异常等风险。 +- 现有模型已有一部分字段，后续只做增量扩展即可。 +- `occurred_start_at`、`occurred_end_at` 比单一 `occurred_at` 更适合差旅、接待等跨时段报销。 -### 8.2 报销明细表 `expense_claim_items` +### 8.2.1 报销状态流转建议 + +建议状态： + +```text +draft +submitted +approved +rejected +paid +``` + +建议流转： + +```text +语义补槽完成 + -> 创建 expense_claims 草稿 + -> status = draft + +用户继续补充字段 / 上传附件 + -> 更新 expense_claims / expense_claim_items / expense_item_documents + -> status 仍为 draft + +用户明确确认提交 + -> status = submitted + -> 写入 submitted_at / status_changed_at / status_changed_by + +审批流结果回写 + -> status = approved 或 rejected + +付款完成回写 + -> status = paid +``` + +边界： + +- User Agent 可以创建 `draft`，也可以在用户确认后提交到 `submitted`。 +- User Agent 不应直接把状态改为 `approved`、`rejected`、`paid`。 +- 所有状态变化都应写审计日志，必要时保留 `status_change_note`。 + +### 8.3 报销明细表 `expense_claim_items` + +用途： + +- 表达一单多明细。 +- 作为 OCR 发票比对、重复报销识别、风险定位的最小粒度。 建议字段： ```text -id -claim_id -item_date -item_type -item_reason -item_location -item_amount -invoice_id -created_at -updated_at +id string(36) PK +claim_id string(36) FK -> expense_claims.id +line_no int 明细序号 +item_date date 费用发生日期 +item_type string(50) 费用小类 +item_reason text 明细事由 +item_location string(100) 明细地点 +merchant_name string(200) 商户/酒店/餐厅 +customer_name string(200) 客户单位 +participants_json json 参与人员 +transport_type string(50) 交通方式 +item_amount numeric(12,2) 明细金额 +tax_amount numeric(12,2) 税额 +currency string(10) +invoice_match_status string(30) unmatched/partial/matched +risk_level string(20) +risk_flags_json json +remark text +created_at timestamptz +updated_at timestamptz ``` -适用场景： +说明： -- 一单多明细。 -- 重复报销匹配。 -- 与发票 OCR 结果逐条比对。 +- 现有 `invoice_id` 单字段不足以覆盖多张附件挂同一明细的情况，后续应改为关联表。 -### 8.3 应收主表 `accounts_receivable` +### 8.4 票据资产主表 `document_assets` + +用途： + +- 作为所有原始附件的主索引表。 +- 支持报销单、报销明细、审批、验真、风控证据等多对象挂载。 建议字段： ```text -id -receivable_no -customer_id -customer_name -contract_no -invoice_no -amount_receivable -amount_received -amount_outstanding -currency -posting_date -due_date -aging_days -status -risk_flags_json -created_at -updated_at +id string(36) PK +biz_domain string(30) expense/ap/ar/common +biz_object_type string(50) expense_claim/expense_item/approval_record +biz_object_id string(36) 业务对象 ID +document_type string(50) invoice/receipt/itinerary/contract/other +document_subtype string(50) vat_special/taxi/train/hotel/meal 等 +source string(30) upload/agent/import/system +original_filename string(255) +mime_type string(100) +file_ext string(20) +page_count int +file_size_bytes bigint +sha256 string(64) 去重与追溯 +storage_provider string(30) local/minio/s3/oss/cos +storage_bucket string(100) 本地模式可为空 +storage_key string(500) 指向当前有效版本原件 +current_version_no int +classification_status string(30) pending/success/failed +ocr_status string(30) pending/running/success/failed +virus_scan_status string(30) pending/clean/infected +retention_policy string(30) finance_default/legal_hold/manual +uploaded_by string(64) +uploaded_at timestamptz +created_at timestamptz +updated_at timestamptz ``` -适用场景： +### 8.5 票据版本表 `document_asset_versions` -- 客户应收查询。 -- 账龄分析。 -- 逾期风险巡检。 +用途： -### 8.4 应付主表 `accounts_payable` +- 保留原始文件和后续重新上传版本。 +- 允许“修正”但不允许覆盖原始证据。 建议字段： ```text -id -payable_no -vendor_id -vendor_name -invoice_no -amount_payable -amount_paid -amount_outstanding -currency -posting_date -due_date -aging_days -status -risk_flags_json -created_at -updated_at +id string(36) PK +document_id string(36) FK -> document_assets.id +version_no int 1,2,3... +is_current bool +change_reason string(100) replace/rotate/desensitize/reupload +original_filename string(255) +mime_type string(100) +file_size_bytes bigint +sha256 string(64) +storage_provider string(30) +storage_bucket string(100) +storage_key string(500) +uploaded_by string(64) +uploaded_at timestamptz +created_at timestamptz ``` -适用场景： +### 8.6 衍生文件表 `document_derivatives` -- 供应商待付款查询。 -- 付款状态查询。 -- 逾期应付和异常付款巡检。 +用途： -### 8.5 MVP 设计边界 +- 存储缩略图、预览 PDF、逐页图片、脱敏件等衍生产物。 -- 不要求一次建完整 ERP 总账、分录、核销、凭证体系。 -- 第一周只要求支撑查询、解释、统计、风险识别的最小字段。 -- 如果现有业务系统已有对应表或 API，优先复用，不重复造表。 -- 如果当前环境没有真实业务数据源，可先建立 Mock 表，但字段命名应尽量贴近最终标准模型。 - -## 9. 字段来源优先级 - -建议优先级： +建议字段： ```text -人工确认字段 - > MCP 验真字段 - > 业务系统字段 - > OCR 字段 - > LLM 推断字段 +id string(36) PK +document_version_id string(36) FK -> document_asset_versions.id +derivative_type string(50) thumb/preview/page_image/desensitized +page_no int 可空 +mime_type string(100) +file_size_bytes bigint +storage_provider string(30) +storage_bucket string(100) +storage_key string(500) +created_by string(64) +created_at timestamptz ``` -LLM 推断字段必须标记来源和置信度。 +### 8.7 OCR 结果表 `document_ocr_results` -## 10. 与语义本体关系 +用途： -语义本体识别的是用户意图和对象。 +- 保留每次 OCR 原始结果、模型版本、置信度和错误信息。 +- 支持后续重跑 OCR 与人工纠错对比。 -标准模型承载对象的结构化字段。 +建议字段： ```text -ontology.entities[].type = invoice - -> 映射到 Invoice 标准模型 +id string(36) PK +document_id string(36) FK -> document_assets.id +document_version_id string(36) FK -> document_asset_versions.id +ocr_engine string(50) paddle/aliyun/tencent/openai 等 +ocr_model string(100) +run_no int 第几次 OCR +status string(30) success/failed/partial +language string(20) +raw_text text +raw_result_json json +structured_result_json json +confidence numeric(5,4) +error_message text +started_at timestamptz +finished_at timestamptz +created_at timestamptz ``` -补充映射建议： +### 8.8 发票结构化表 `invoice_structured_records` + +用途： + +- 将发票核心字段标准化后独立存储，便于查重、验真、规则计算。 + +建议字段： ```text -ontology.scenario = expense - -> 查询 expense_claims / expense_claim_items - -ontology.scenario = accounts_receivable - -> 查询 accounts_receivable - -ontology.scenario = accounts_payable - -> 查询 accounts_payable +id string(36) PK +document_id string(36) FK -> document_assets.id +ocr_result_id string(36) FK -> document_ocr_results.id +invoice_code string(50) +invoice_number string(50) +invoice_type string(50) +seller_name string(200) +seller_tax_no string(50) +buyer_name string(200) +buyer_tax_no string(50) +issue_date date +total_amount numeric(12,2) +tax_amount numeric(12,2) +currency string(10) +check_code string(100) +is_red_invoice bool +is_electronic bool +ocr_confidence numeric(5,4) +normalized_status string(30) normalized/manual_corrected +duplicate_fingerprint string(100) 发票号+代码+金额+日期 +created_at timestamptz +updated_at timestamptz ``` -## 11. 开发阶段建议 +### 8.9 发票验真记录表 `invoice_verification_records` + +用途： + +- 保留每次调用税局/第三方验真服务的结果，支持追溯。 + +建议字段： ```text -Step 1: 定义 Invoice 标准模型 -Step 2: 定义 ReimbursementRequest 标准模型 -Step 3: 定义 AccountsReceivableRecord / AccountsPayableRecord 标准模型 -Step 4: 设计 MVP 最小业务表 expense_claims / expense_claim_items / accounts_receivable / accounts_payable -Step 5: OCR 输出映射到 Invoice -Step 6: MCP 输出映射到 Invoice 或 AR/AP 标准模型 -Step 7: 规则中心基于标准模型执行 -Step 8: 建立字段血缘和置信度 +id string(36) PK +invoice_record_id string(36) FK -> invoice_structured_records.id +verification_channel string(50) tax_mcp/third_party/manual +request_payload_json json +response_payload_json json +verify_status string(30) verified/unverified/voided/error +voided bool +red_reversed bool +verified_amount numeric(12,2) +verified_issue_date date +error_code string(50) +error_message text +verified_by string(64) +verified_at timestamptz +created_at timestamptz ``` + +### 8.10 明细与票据关联表 `expense_item_documents` + +用途： + +- 解决一条明细可关联多张票据、一张票据也可能支撑多条拆分明细的场景。 + +建议字段： + +```text +id string(36) PK +claim_id string(36) FK -> expense_claims.id +claim_item_id string(36) FK -> expense_claim_items.id +document_id string(36) FK -> document_assets.id +relation_type string(30) evidence/invoice/boarding_pass/receipt +allocated_amount numeric(12,2) 分摊到该明细的金额 +match_status string(30) unmatched/partial/matched +match_confidence numeric(5,4) +created_at timestamptz +updated_at timestamptz +``` + +### 8.11 风险事件表 `risk_events` + +用途： + +- 记录风险命中，而不是只在主表里塞一个 `risk_flags_json`。 +- 作为 Agent 解释“为什么拦截”的核心依据。 + +建议字段： + +```text +id string(36) PK +biz_domain string(30) expense/ap/ar +biz_object_type string(50) expense_claim/expense_item/invoice +biz_object_id string(36) +risk_code string(50) duplicate_invoice/amount_mismatch 等 +risk_name string(100) +risk_level string(20) low/medium/high +hit_source string(30) rule/agent/hermes/manual +evidence_json json +status string(30) open/confirmed/resolved/ignored +detected_at timestamptz +detected_by string(64) +resolved_at timestamptz +resolved_by string(64) +resolution_note text +created_at timestamptz +updated_at timestamptz +``` + +### 8.12 风险处置表 `risk_actions` + +用途： + +- 记录每次人工确认、驳回、忽略、要求补件等处置动作。 + +建议字段： + +```text +id string(36) PK +risk_event_id string(36) FK -> risk_events.id +action_type string(30) confirm/reject/ignore/request_more +action_note text +operator_id string(64) +operator_name string(100) +created_at timestamptz +``` + +### 8.13 文件访问审计表 `document_access_logs` + +用途： + +- 记录谁看过、下载过、导出过原始票据。 +- 支撑财务审计和数据安全追溯。 + +建议字段： + +```text +id string(36) PK +document_id string(36) FK -> document_assets.id +document_version_id string(36) FK -> document_asset_versions.id +action string(30) preview/download/export/delete +operator_id string(64) +operator_name string(100) +operator_role string(50) +client_ip string(64) +user_agent string(255) +trace_id string(64) +created_at timestamptz +``` + +## 9. 表关系建议 + +```text +expense_claims + └─ expense_claim_items + └─ expense_item_documents + └─ document_assets + └─ document_asset_versions + └─ document_derivatives + └─ document_ocr_results + └─ invoice_structured_records + └─ invoice_verification_records + +risk_events -> 可指向 expense_claims / expense_claim_items / invoice_structured_records +risk_actions -> risk_events +document_access_logs -> document_assets / document_asset_versions +``` + +原则： + +- 主业务对象和文件资产解耦。 +- OCR、验真、风险都挂在文件资产或业务对象之上，不把责任塞到一个巨表。 +- 文件版本和业务关系分离，避免替换附件时把历史证据冲掉。 + +## 10. 与现有表的衔接策略 + +当前代码中已经存在： + +- `expense_claims` +- `expense_claim_items` +- `reimbursement_requests` + +建议策略： + +- `expense_claims` 继续作为未来报销主表。 +- `expense_claim_items` 增量扩字段并替换当前单一 `invoice_id` 直连方式。 +- `reimbursement_requests` 暂不删除，但冻结扩表。 +- 如旧流程仍引用 `reimbursement_requests`，可在过渡期建立： + - `request_no -> claim_no` 对照字段 + - 或由 `approval_records` 同时支持两类来源对象 + +不建议做法： + +- 再新建第四张“报销申请主表”。 +- 把原始发票图片以 blob 方式存进 `expense_claims`。 +- 把 OCR、验真、风控结果全塞进一个 JSON 大字段。 + +## 11. 实施顺序建议 + +Phase 1： + +- 扩展 `expense_claims` +- 扩展 `expense_claim_items` +- 新增 `document_assets` +- 新增 `document_asset_versions` +- 新增 `expense_item_documents` + +Phase 2： + +- 新增 `document_ocr_results` +- 新增 `invoice_structured_records` +- 新增 `invoice_verification_records` +- 新增 `document_derivatives` + +Phase 3： + +- 新增 `risk_events` +- 新增 `risk_actions` +- 新增 `document_access_logs` + +Phase 4： + +- 逐步弱化 `reimbursement_requests` +- 将 Agent 草稿、审批、OCR、验真、风控全收敛到 `expense_claims` 体系 + +## 12. 对 Agent 的直接收益 + +- 用户说“我要报销”时，Agent 能先创建 `expense_claims` 草稿，再持续补槽。 +- 用户上传票据后，系统有明确的 `document_assets` 与 `expense_item_documents` 可挂载。 +- OCR 和验真结果不是一次性临时输出，而是可追溯、可回放、可审计的长期资产。 +- Agent 回答“为什么被拦截”时，可以直接引用 `risk_events` 和票据证据，不再靠拼字符串解释。 diff --git a/document/development/agent plan/weekly_execution_details/00_execution_index.md b/document/development/agent plan/weekly_execution_details/00_execution_index.md deleted file mode 100644 index 93dd71e..0000000 --- a/document/development/agent plan/weekly_execution_details/00_execution_index.md +++ /dev/null @@ -1,155 +0,0 @@ -# Weekly Execution Details 总执行清单 - -本文件是 `agent plan` 下的执行索引，承接 `agent week plan` 的 7 天路线图。 - -这里不重新解释为什么这样排期，只负责把每天的“大开发点”映射到可执行 TODO 文档。 - -## 执行方式 - -- [ ] 先读 `document/development/agent week plan/MASTER_TODO.md`，确认当天主题。 -- [ ] 再读当天 daily 文档，确认交付物和验收门槛。 -- [ ] 最后进入本目录对应的详细 TODO 文档。 -- [ ] 每完成一个最小 TODO，就改成 `[x] ~~...~~`。 -- [ ] 每天结束时回到 daily 文档，确认当天是否达到验收门槛。 - -## Day 1：基础模型与工程骨架 - -路线图： - -- `document/development/agent week plan/day_1_foundation_models.md` - -执行细则： - -- [day_1_foundation_models.md](./day_1_foundation_models.md) - -核心完成物： - -- [x] ~~统一资产模型。~~ -- [x] ~~版本模型。~~ -- [x] ~~审核模型。~~ -- [x] ~~AgentRun。~~ -- [x] ~~ToolCall。~~ -- [x] ~~SemanticParseLog。~~ -- [x] ~~AuditLog。~~ -- [x] ~~最小财务业务数据来源。~~ - -## Day 2：任务规则中心联调 - -路线图： - -- `document/development/agent week plan/day_2_rule_center_integration.md` - -执行细则： - -- [day_2_rule_center_integration.md](./day_2_rule_center_integration.md) - -核心完成物： - -- [ ] 规则、技能、MCP、任务列表。 -- [ ] 资产详情。 -- [ ] 规则 Markdown 编辑。 -- [ ] 最近 5 个版本。 -- [ ] 版本切换弹窗。 -- [ ] 审核者信息。 -- [ ] 未审核不能上线。 - -## Day 3：语义本体 MVP - -路线图： - -- `document/development/agent week plan/day_3_semantic_ontology_mvp.md` - -执行细则： - -- [day_3_semantic_ontology_mvp.md](./day_3_semantic_ontology_mvp.md) - -核心完成物： - -- [ ] 8 字段语义结构。 -- [ ] 语义解析 API。 -- [ ] 解析日志。 -- [ ] 权限级别判断。 -- [ ] 最小评测集。 - -## Day 4：Orchestrator 运行时 - -路线图： - -- `document/development/agent week plan/day_4_orchestrator_runtime.md` - -执行细则： - -- [day_4_orchestrator_runtime.md](./day_4_orchestrator_runtime.md) - -核心完成物： - -- [ ] Orchestrator 入口。 -- [ ] Agent 路由。 -- [ ] 权限拦截。 -- [ ] 工具调用封装。 -- [ ] Trace 查询。 -- [ ] 降级返回。 - -## Day 5：User Agent MVP - -路线图： - -- `document/development/agent week plan/day_5_user_agent_mvp.md` - -执行细则： - -- [day_5_user_agent_mvp.md](./day_5_user_agent_mvp.md) - -核心完成物： - -- [ ] 用户自然语言入口。 -- [ ] 报销查询解释。 -- [ ] 应收查询解释。 -- [ ] 应付查询解释。 -- [ ] 规则引用解释。 -- [ ] 草稿生成。 - -## Day 6：Hermes MVP - -路线图： - -- `document/development/agent week plan/day_6_hermes_mvp.md` - -执行细则： - -- [day_6_hermes_mvp.md](./day_6_hermes_mvp.md) - -核心完成物： - -- [ ] 任务触发入口。 -- [ ] 风险巡检。 -- [ ] 每日统计。 -- [ ] OCR Mock 接入。 -- [ ] 知识候选生成。 -- [ ] 规则草稿生成。 - -## Day 7：加固、演示和验收 - -路线图： - -- `document/development/agent week plan/day_7_hardening_demo_acceptance.md` - -执行细则： - -- [day_7_hardening_demo_acceptance.md](./day_7_hardening_demo_acceptance.md) - -核心完成物： - -- [ ] 核心链路回归。 -- [ ] 权限边界复查。 -- [ ] 审计和 Trace 补齐。 -- [ ] 测试记录。 -- [ ] 演示脚本。 -- [ ] 下一阶段交接。 - -## 最终完成标准 - -- [ ] 周计划每一天都有清晰大开发点。 -- [ ] 每个大开发点都能跳转到具体执行细则。 -- [ ] 执行细则覆盖模型、接口、服务、前端、测试、验收。 -- [ ] Codex 可以从任意一天开始，根据 TODO 独立推进开发。 diff --git a/document/development/agent plan/weekly_execution_details/README.md b/document/development/agent plan/weekly_execution_details/README.md deleted file mode 100644 index b03f11e..0000000 --- a/document/development/agent plan/weekly_execution_details/README.md +++ /dev/null @@ -1,45 +0,0 @@ -# Weekly Execution Details 执行细则 - -本目录承接 `document/development/agent week plan` 的 7 天路线图。 - -分工方式： - -- `agent week plan`：说明每天的大方向、交付物、验收门槛。 -- `agent plan/weekly_execution_details`：说明每天具体怎么做，拆到模型、字段、接口、服务、前端、测试和验收证据。 - -执行时先看周计划，再进入本目录对应日期的详细 TODO。 - -## 对应关系 - -| 周计划 Day | 开发主题 | 执行细则 | -| --- | --- | --- | -| Day 1 | 基础模型与工程骨架 | [day_1_foundation_models.md](./day_1_foundation_models.md) | -| Day 2 | 任务规则中心联调 | [day_2_rule_center_integration.md](./day_2_rule_center_integration.md) | -| Day 3 | 语义本体 MVP | [day_3_semantic_ontology_mvp.md](./day_3_semantic_ontology_mvp.md) | -| Day 4 | Orchestrator 运行时 | [day_4_orchestrator_runtime.md](./day_4_orchestrator_runtime.md) | -| Day 5 | User Agent MVP | [day_5_user_agent_mvp.md](./day_5_user_agent_mvp.md) | -| Day 6 | Hermes MVP | [day_6_hermes_mvp.md](./day_6_hermes_mvp.md) | -| Day 7 | 加固、演示和验收 | [day_7_hardening_demo_acceptance.md](./day_7_hardening_demo_acceptance.md) | - -## 完成标记规则 - -未完成： - -```md -- [ ] 建立 AgentAsset 数据模型 -``` - -完成后： - -```md -- [x] ~~建立 AgentAsset 数据模型~~ -``` - -执行要求： - -- [ ] 每次只处理一个最小 TODO。 -- [ ] 完成后先自测，再改成 `[x]`。 -- [ ] 改成 `[x]` 时，同时用 `~~` 画线。 -- [ ] 不能因为代码写完就标完成，必须满足该 TODO 的验收证据。 -- [ ] 遇到阻塞时，在当天文档的“阻塞记录”下新增一条说明。 -- [ ] 每天收尾时更新当天文档的“日终交接”。 diff --git a/document/development/agent plan/weekly_execution_details/day_1_foundation_models.md b/document/development/agent plan/weekly_execution_details/day_1_foundation_models.md deleted file mode 100644 index 8906071..0000000 --- a/document/development/agent plan/weekly_execution_details/day_1_foundation_models.md +++ /dev/null @@ -1,158 +0,0 @@ -# Day 1：基础模型与工程骨架 TODO - -本文件是周计划 Day 1 的具体执行细则。路线图见 `document/development/agent week plan/day_1_foundation_models.md`。 - -状态：Day 1 已于 `2026-05-11` 完成，以下 TODO 已按完成态回填。 - -## 完成摘要 - -- [x] ~~完成 Agent 资产、版本、审核、运行日志、工具调用日志、语义解析日志、审计日志基础模型。~~ -- [x] ~~完成报销、应收、应付最小业务数据源，后续 User Agent 和 Hermes 有明确查询来源。~~ -- [x] ~~完成基础 API、服务层、种子数据和测试，Day 2 可直接进入前后端联调。~~ - -## 0. 开始前检查 - -- [x] ~~确认后端目录为 `/app/server`，模型、路由、启动入口和测试目录已定位。~~ -- [x] ~~确认本次改动以增量方式落到现有 FastAPI + SQLAlchemy 工程，不回退无关文件。~~ - -验收证据： - -- [x] ~~模型注册位于 `server/src/app/db/base.py`，路由注册位于 `server/src/app/api/v1/router.py`，启动入口位于 `server/src/app/main.py`，测试位于 `server/tests`。~~ - -## 1. 统一命名和边界 - -- [x] ~~统一枚举：`rule | skill | mcp | task`、`draft | review | active | disabled`、`pending | approved | rejected`、`orchestrator | user_agent | hermes`。~~ -- [x] ~~统一运行来源、权限级别、内容类型、运行状态和工具类型命名，避免出现第二套并行语义。~~ - -验收证据： - -- [x] ~~`server/src/app/core/agent_enums.py` 已成为模型、Schema 和服务层的统一枚举入口。~~ - -## 2. 设计最小财务业务数据模型 - -- [x] ~~建立 `expense_claims`、`expense_claim_items`、`accounts_receivable`、`accounts_payable`。~~ -- [x] ~~字段覆盖时间、地点、理由、金额、员工、部门、状态，以及应收 / 应付的金额、到期日、账龄、风险标记。~~ - -验收证据： - -- [x] ~~`server/src/app/models/financial_record.py` 与 `document/development/agent plan/14_financial_document_canonical_model.md` 形成直接映射。~~ - -## 3. 建立 AgentAsset 模型 - -- [x] ~~建立 `AgentAsset`，包含 `asset_type`、`code`、`name`、`description`、`domain`、`scenario_json`、`owner`、`reviewer`、`status`、`current_version`、`config_json` 等核心字段。~~ -- [x] ~~对 `code`、`asset_type`、`status`、`domain` 建立唯一约束或索引。~~ - -验收证据： - -- [x] ~~资产列表可按 `rule`、`skill`、`mcp`、`task` 四类过滤返回。~~ - -## 4. 建立 AgentAssetVersion 模型 - -- [x] ~~建立 `AgentAssetVersion`，规则版本保存 Markdown，其余资产版本保存 JSON 快照。~~ -- [x] ~~对 `asset_id + version` 建立唯一约束，并支持按资产读取最近版本列表。~~ - -验收证据： - -- [x] ~~规则详情接口可返回 `current_version_content` 和 `recent_versions`。~~ - -## 5. 建立 AgentAssetReview 模型 - -- [x] ~~建立 `AgentAssetReview`，保存版本、审核人、审核状态、审核备注和审核时间。~~ -- [x] ~~服务层实现规则版本未 `approved` 时禁止上线。~~ - -验收证据： - -- [x] ~~`POST /api/v1/agent-assets/{asset_id}/activate` 对待审规则返回 400 拦截。~~ - -## 6. 建立 AgentRun 模型 - -- [x] ~~建立 `AgentRun`，包含 `run_id`、`agent`、`source`、`ontology_json`、`route_json`、`permission_level`、`status`、`result_summary`、`error_message` 等字段。~~ -- [x] ~~所有运行记录统一生成 `run_id`，并允许失败态保存错误信息。~~ - -验收证据： - -- [x] ~~`AgentRunService.create_run()` 会自动生成 `run_` 前缀标识，并可回读失败摘要。~~ - -## 7. 建立 AgentToolCall 模型 - -- [x] ~~建立 `AgentToolCall`，可记录工具类型、工具名、请求 / 响应 JSON、耗时和错误信息。~~ -- [x] ~~同一个 `run_id` 下支持多次工具调用追踪。~~ - -验收证据： - -- [x] ~~种子运行数据已覆盖数据库查询、MCP 调用和权限规则引擎调用。~~ - -## 8. 建立 SemanticParseLog 模型 - -- [x] ~~建立 `SemanticParseLog`，覆盖场景、意图、实体、时间范围、指标、约束、风险、权限和置信度。~~ -- [x] ~~支持按 `run_id` 回放 Day 3 语义结果。~~ - -验收证据： - -- [x] ~~`GET /api/v1/agent-runs/{run_id}` 已能携带 `semantic_parse` 返回。~~ - -## 9. 建立 AuditLog 模型 - -- [x] ~~建立 `AuditLog` 和统一 `AuditLogService`。~~ -- [x] ~~资产创建、版本保存、审核、上线等写操作都会留下审计记录。~~ - -验收证据： - -- [x] ~~`GET /api/v1/audit-logs` 可返回种子审计日志，服务层新建资产也会落审计。~~ - -## 10. 建立 Schema / DTO - -- [x] ~~建立 `AgentAssetCreate / Update / Read / ListItem`、`AgentAssetVersionRead`、`AgentAssetReviewRead`、`RuleMarkdownUpdate`、`AgentRunRead`、`AgentToolCallRead`、`SemanticParseRead`。~~ -- [x] ~~所有 JSON 字段以结构化对象返回，不回传字符串化 JSON。~~ - -验收证据： - -- [x] ~~列表 DTO 不返回大块 Markdown，详情 DTO 返回当前版本正文和最近版本。~~ - -## 11. 建立 API 骨架 - -- [x] ~~建立 `GET/POST/PATCH /api/v1/agent-assets`、`GET /api/v1/agent-assets/{asset_id}`、`GET/POST /api/v1/agent-assets/{asset_id}/versions`、`POST /api/v1/agent-assets/{asset_id}/reviews`、`POST /api/v1/agent-assets/{asset_id}/activate`。~~ -- [x] ~~建立 `GET /api/v1/agent-runs`、`GET /api/v1/agent-runs/{run_id}`、`GET /api/v1/audit-logs`。~~ - -验收证据： - -- [x] ~~所有接口已挂到 `server/src/app/api/v1/router.py`，并通过 `create_app()` 自动暴露。~~ - -## 12. 建立种子数据 - -- [x] ~~种子资产补齐到 3 条规则、2 条技能、2 条 MCP、3 条任务。~~ -- [x] ~~三条规则都具备至少 2 个版本，并覆盖 `approved / pending / rejected` 三种审核样本。~~ -- [x] ~~旧开发数据库启动时会自动增量补齐新增资产和版本，不要求手动清库。~~ - -验收证据： - -- [x] ~~Smoke：`GET /api/v1/agent-assets` 返回 10 条资产，`GET /api/v1/agent-runs` 返回 3 条运行日志，`GET /api/v1/audit-logs` 返回 4 条审计日志。~~ - -## 13. 最小测试 - -- [x] ~~新增 Day 1 服务层与接口层测试，覆盖种子完整性、版本历史、未审核不能上线、运行日志生成和审计日志写入。~~ -- [x] ~~Ruff 校验通过，Day 1 新增文件保持可检查状态。~~ - -验收证据： - -- [x] ~~`/app/server/.venv/bin/pytest -q /app/server/tests/test_agent_asset_service.py /app/server/tests/test_agent_foundation_endpoints.py` -> `11 passed`。~~ -- [x] ~~`/app/server/.venv/bin/pytest -q tests` 已通过全量后端测试。~~ - -## 14. Day 1 验收 - -- [x] ~~数据库能创建所有新增表或等价结构。~~ -- [x] ~~API 服务能启动，OpenAPI 能看到新增接口。~~ -- [x] ~~资产列表接口返回规则、技能、MCP、任务；规则详情带 Markdown 当前版本和最近版本列表。~~ -- [x] ~~未审核规则不能上线；AgentRun 和 AuditLog 均可保存记录。~~ -- [x] ~~所有 Day 1 TODO 已改为完成态。~~ - -## 阻塞记录 - -- [x] ~~暂无阻塞。~~ - -## 日终交接 - -- [x] ~~已完成模型：资产、版本、审核、运行日志、工具调用、语义解析、审计、报销、应收、应付。~~ -- [x] ~~已完成 API：`/api/v1/agent-assets`、`/api/v1/agent-runs`、`/api/v1/audit-logs`。~~ -- [x] ~~Day 2 前端联调应优先使用 `GET /api/v1/agent-assets`、`GET /api/v1/agent-assets/{asset_id}`、`GET /api/v1/agent-assets/{asset_id}/versions?limit=5`、`POST /api/v1/agent-assets/{asset_id}/reviews`、`POST /api/v1/agent-assets/{asset_id}/activate`。~~ -- [x] ~~后续 Day 4 及以后运行时方向按用户要求转向 `LangChain + LangGraph`，Hermes 继续作为内部数字员工入口；Day 1 保留为数据与治理底座。~~ diff --git a/document/development/agent plan/weekly_execution_details/day_2_rule_center_integration.md b/document/development/agent plan/weekly_execution_details/day_2_rule_center_integration.md deleted file mode 100644 index aa06ca4..0000000 --- a/document/development/agent plan/weekly_execution_details/day_2_rule_center_integration.md +++ /dev/null @@ -1,251 +0,0 @@ -# Day 2：任务规则中心联调 TODO - -本文件是周计划 Day 2 的具体执行细则。路线图见 `document/development/agent week plan/day_2_rule_center_integration.md`。 - -目标：把任务规则中心从静态 UI 改成可对接后端的生产形态，覆盖规则、技能、MCP、任务四类资产。重点是规则 Markdown 编辑、版本切换、审核者信息、上线约束。 - -参考文档： - -- `document/development/agent plan/07_capability_registry.md` -- `document/development/agent plan/13_rule_formation_lifecycle.md` -- `document/development/agent plan/06_data_contracts_and_governance.md` - -## 0. 开始前检查 - -- [x] ~~确认 Day 1 API 已可访问。~~ -- [x] ~~确认前端任务规则中心文件位置。~~ -- [x] ~~确认现有路由名称和导航名称。~~ -- [x] ~~确认现有 UI 风格，不重新做大改版。~~ -- [x] ~~确认当前页面已有页签：规则、技能、MCP、任务。~~ -- [x] ~~确认详情页隐藏顶部 title bar 的逻辑仍然有效。~~ -- [x] ~~确认返回列表栏高度没有被重新拉高。~~ - -## 1. API Client - -- [x] ~~新增或扩展资产列表请求函数。~~ -- [x] ~~新增资产详情请求函数。~~ -- [x] ~~新增版本列表请求函数。~~ -- [x] ~~新增规则 Markdown 保存请求函数。~~ -- [x] ~~新增审核请求函数。~~ -- [x] ~~新增上线请求函数。~~ -- [x] ~~新增运行日志请求函数。~~ -- [x] ~~给所有请求增加加载态。~~ -- [x] ~~给所有请求增加错误态。~~ -- [x] ~~给所有写请求增加成功提示。~~ - -验收证据： - -- [x] ~~前端不再只依赖本地硬编码资产数据。~~ -- [x] ~~后端不可用时页面有明确错误提示。~~ - -## 2. 列表页数据接入 - -- [x] ~~规则页签请求 `asset_type=rule`。~~ -- [x] ~~技能页签请求 `asset_type=skill`。~~ -- [x] ~~MCP 页签请求 `asset_type=mcp`。~~ -- [x] ~~任务页签请求 `asset_type=task`。~~ -- [x] ~~搜索框传递关键词或本地过滤。~~ -- [x] ~~类型下拉和搜索框可以同时生效。~~ -- [x] ~~状态筛选可以过滤 `draft | review | active | disabled`。~~ -- [x] ~~列表卡片展示名称。~~ -- [x] ~~列表卡片展示摘要。~~ -- [x] ~~列表卡片展示状态。~~ -- [x] ~~列表卡片展示负责人。~~ -- [x] ~~列表卡片展示最近更新时间。~~ -- [x] ~~空数据时展示空态。~~ -- [x] ~~加载中时展示骨架或加载状态。~~ - -验收证据： - -- [x] ~~四个页签都能切换。~~ -- [x] ~~四个页签都有数据或空态。~~ -- [x] ~~搜索和筛选不会互相覆盖。~~ - -## 3. 规则详情页主信息 - -- [x] ~~打开规则资产时请求详情 API。~~ -- [x] ~~Hero title 展示规则名称。~~ -- [x] ~~Hero title 下方展示审核者。~~ -- [x] ~~Hero title 下方展示审核状态。~~ -- [x] ~~Hero title 下方展示上线条件。~~ -- [x] ~~Hero title 高度保持紧凑。~~ -- [x] ~~详情页不显示外层顶部 title bar。~~ -- [x] ~~返回列表栏高度保持原有紧凑高度。~~ - -验收证据： - -- [x] ~~用户能一眼看到该规则是否已审核。~~ -- [x] ~~用户不会看到两层 title。~~ - -## 4. Markdown 编辑器 - -- [x] ~~从当前版本读取 Markdown 内容。~~ -- [x] ~~Markdown 编辑框高度和右侧版本卡片底部对齐。~~ -- [x] ~~Markdown 编辑框支持长内容滚动。~~ -- [x] ~~Markdown 编辑框保存时调用 API。~~ -- [x] ~~保存后创建新版本或更新草稿版本，按后端约定执行。~~ -- [x] ~~保存成功后刷新版本列表。~~ -- [x] ~~保存失败时保留用户输入。~~ -- [x] ~~编辑器禁用态覆盖 `active` 且无编辑权限的情况。~~ -- [x] ~~编辑器底部展示最后保存时间。~~ - -验收证据： - -- [x] ~~编辑 Markdown 后刷新页面内容仍存在。~~ -- [x] ~~保存失败不会丢内容。~~ -- [x] ~~左右卡片底部视觉对齐。~~ - -## 5. 版本卡片 - -- [x] ~~右侧只保留版本信息卡片。~~ -- [x] ~~版本卡片宽度足够展示版本号、日期、状态。~~ -- [x] ~~展示最近 5 个版本。~~ -- [x] ~~当前版本有明显但不突兀的标识。~~ -- [x] ~~当前版本标识居中显示。~~ -- [x] ~~选中状态只变色，不改变内容对齐。~~ -- [x] ~~日期列和其他版本日期对齐。~~ -- [x] ~~点击非当前版本时弹出确认弹窗。~~ -- [x] ~~弹窗展示目标版本号。~~ -- [x] ~~弹窗展示切换风险提示。~~ -- [x] ~~确认后切换当前展示内容。~~ -- [x] ~~取消后不改变当前版本。~~ - -验收证据： - -- [x] ~~版本切换不会造成列表文字位移。~~ -- [x] ~~当前版本背景能完全覆盖内容区域。~~ -- [x] ~~版本卡片不贴右侧边界。~~ - -## 6. 审核与上线 - -- [x] ~~详情中展示审核者姓名。~~ -- [x] ~~详情中展示审核时间。~~ -- [x] ~~详情中展示审核意见。~~ -- [x] ~~未审核规则显示不能上线原因。~~ -- [x] ~~点击上线时调用后端上线接口。~~ -- [x] ~~后端拒绝时展示拒绝原因。~~ -- [x] ~~审核通过后上线按钮可用。~~ -- [x] ~~审核动作写入审计日志。~~ -- [x] ~~上线动作写入审计日志。~~ - -验收证据： - -- [x] ~~pending 规则无法上线。~~ -- [x] ~~approved 规则可以上线。~~ -- [x] ~~rejected 规则无法上线。~~ - -## 7. 技能详情 - -- [x] ~~技能页签列表展示能力名称。~~ -- [x] ~~技能详情展示能力说明。~~ -- [x] ~~技能详情展示输入参数。~~ -- [x] ~~技能详情展示输出参数。~~ -- [x] ~~技能详情展示依赖能力。~~ -- [x] ~~技能详情展示适用场景。~~ -- [x] ~~技能详情展示负责人。~~ -- [x] ~~技能详情展示版本。~~ -- [x] ~~技能详情不使用规则 Markdown 编辑器。~~ - -验收证据： - -- [x] ~~技能和规则详情不会混用 UI。~~ - -## 8. MCP 详情 - -- [x] ~~MCP 页签列表展示外部服务名称。~~ -- [x] ~~MCP 详情展示服务类型。~~ -- [x] ~~MCP 详情展示调用地址或能力名。~~ -- [x] ~~MCP 详情展示鉴权方式。~~ -- [x] ~~MCP 详情展示超时配置。~~ -- [x] ~~MCP 详情展示降级策略。~~ -- [x] ~~MCP 详情展示最近调用状态。~~ -- [x] ~~MCP 详情展示负责人。~~ - -验收证据： - -- [x] ~~MCP 被定义为外部服务，而不是技能规则。~~ - -## 9. 任务详情 - -- [x] ~~任务页签展示定时任务名称。~~ -- [x] ~~任务详情展示 cron 或调度周期。~~ -- [x] ~~任务详情展示执行 Agent，默认 Hermes。~~ -- [x] ~~任务详情展示任务目标。~~ -- [x] ~~任务详情展示风险等级。~~ -- [x] ~~任务详情展示最近执行时间。~~ -- [x] ~~任务详情展示最近执行结果。~~ -- [x] ~~任务详情展示启停状态。~~ - -验收证据： - -- [x] ~~定时任务用户可见名称为“任务”。~~ -- [x] ~~技术字段可保留 `schedule`，但 UI 不显示“定时任务”。~~ - -## 10. 前端质量 - -- [x] ~~页面在 1366 宽度下无横向滚动。~~ -- [x] ~~页面在 1920 宽度下右侧卡片不过宽。~~ -- [x] ~~页面在窄屏下详情区域可滚动。~~ -- [x] ~~所有按钮有禁用态。~~ -- [x] ~~所有弹窗有取消按钮。~~ -- [x] ~~所有表单错误有提示。~~ -- [x] ~~所有日期格式统一。~~ -- [x] ~~状态颜色和现有系统一致。~~ - -验收证据： - -- [x] ~~`npm run build` 通过。~~ -- [ ] 任务规则中心手动走查通过。 - -## 11. Day 2 验收 - -- [x] ~~规则、技能、MCP、任务四个页签可用。~~ -- [x] ~~搜索框和筛选下拉可用。~~ -- [x] ~~规则详情展示 Markdown。~~ -- [x] ~~规则 Markdown 可保存。~~ -- [x] ~~右侧只保留版本信息。~~ -- [x] ~~版本可切换且有弹窗确认。~~ -- [x] ~~审核者信息在标题下方。~~ -- [x] ~~未审核规则不能上线。~~ -- [x] ~~前端构建通过。~~ -- [x] ~~所有完成项已按完成态标记。~~ - -## 阻塞记录 - -- [x] ~~暂无。~~ - -## 日终交接 - -- [x] ~~写明已接入的 API。~~ -- [x] ~~写明仍然使用 Mock 的字段。~~ -- [x] ~~写明 UI 未完成项。~~ -- [x] ~~写明 Day 3 语义本体需要复用的资产数据。~~ - -已接入的 API： - -- `GET /api/v1/agent-assets?asset_type=rule|skill|mcp|task` -- `GET /api/v1/agent-assets/{asset_id}` -- `GET /api/v1/agent-assets/{asset_id}/versions` -- `POST /api/v1/agent-assets/{asset_id}/versions` -- `POST /api/v1/agent-assets/{asset_id}/reviews` -- `POST /api/v1/agent-assets/{asset_id}/activate` -- `GET /api/v1/agent-runs` - -仍然使用 Mock / 种子数据的字段： - -- MCP 服务地址仍是 `mock://...` 种子地址，用于占位联调。 -- MCP 最近调用状态、任务最近执行结果来自 Day 1 注入的 `AgentRun` 种子数据。 -- 技能、MCP、任务详情仍以只读方式展示，未开放编辑表单。 - -UI 未完成项： - -- 未做浏览器内人工走查记录，当前仅完成构建验证与代码层联调。 -- 技能、MCP、任务的编辑能力仍留待后续 Day 3 / Day 4 之后按权限开放。 - -Day 3 语义本体需要复用的资产数据： - -- 资产主键与编码：`id`、`code`、`asset_type` -- 业务归类：`domain`、`scenario_json` -- 当前生效版本：`current_version`、`current_version_content`、`current_version_content_type` -- 治理状态：`status`、`latest_review`、`recent_versions` -- 运行关联：`config_json.agent`、`config_json.cron`、`AgentRun.task_id`、`tool_calls` diff --git a/document/development/agent plan/weekly_execution_details/day_3_semantic_ontology_mvp.md b/document/development/agent plan/weekly_execution_details/day_3_semantic_ontology_mvp.md deleted file mode 100644 index f083b13..0000000 --- a/document/development/agent plan/weekly_execution_details/day_3_semantic_ontology_mvp.md +++ /dev/null @@ -1,238 +0,0 @@ -# Day 3：语义本体 MVP TODO - -本文件是周计划 Day 3 的具体执行细则。路线图见 `document/development/agent week plan/day_3_semantic_ontology_mvp.md`。 - -目标：建立用户问题的语义解析层，输出稳定的 8 个核心字段，让 User Agent、Hermes 和 Orchestrator 都能使用同一套语义结构。 - -参考文档： - -- `document/development/agent plan/02_semantic_ontology.md` -- `document/development/agent plan/14_financial_document_canonical_model.md` -- `document/development/agent plan/06_data_contracts_and_governance.md` - -## 0. 开始前检查 - -- [ ] 确认 Day 1 的 `SemanticParseLog` 可用。 -- [ ] 确认 Day 1 的 `AgentRun` 可用。 -- [ ] 确认 Day 2 的资产 API 可用。 -- [ ] 找到后端服务层目录。 -- [ ] 找到现有 LLM 调用或 Mock 调用方式。 -- [ ] 确认当前是否允许真实调用 LLM。 -- [ ] 如果不能调用真实 LLM，准备规则解析加 Mock 解析。 - -## 1. 定义 8 个核心字段 - -- [ ] 定义字段 `scenario`，表示业务场景。 -- [ ] 定义字段 `intent`，表示用户意图。 -- [ ] 定义字段 `entities`，表示业务对象。 -- [ ] 定义字段 `time_range`，表示时间范围。 -- [ ] 定义字段 `metrics`，表示指标或金额口径。 -- [ ] 定义字段 `constraints`，表示过滤条件。 -- [ ] 定义字段 `risk_flags`，表示风险信号。 -- [ ] 定义字段 `permission`，表示动作权限。 -- [ ] 为每个字段写清楚类型。 -- [ ] 为每个字段写清楚是否必填。 -- [ ] 为每个字段写清楚默认值。 -- [ ] 为每个字段写清楚示例。 - -验收证据： - -- [ ] 8 个字段在 Schema、服务层、日志中名字一致。 - -## 2. 设计字段枚举 - -- [ ] `scenario` 支持 `expense`。 -- [ ] `scenario` 支持 `accounts_receivable`。 -- [ ] `scenario` 支持 `accounts_payable`。 -- [ ] `scenario` 支持 `knowledge`。 -- [ ] `scenario` 支持 `unknown`。 -- [ ] `intent` 支持 `query`。 -- [ ] `intent` 支持 `explain`。 -- [ ] `intent` 支持 `compare`。 -- [ ] `intent` 支持 `risk_check`。 -- [ ] `intent` 支持 `draft`。 -- [ ] `intent` 支持 `operate`。 -- [ ] `permission.level` 支持 `read`。 -- [ ] `permission.level` 支持 `draft_write`。 -- [ ] `permission.level` 支持 `approval_required`。 -- [ ] `permission.level` 支持 `forbidden`。 - -验收证据： - -- [ ] 未识别的问题不会抛异常，返回 `unknown`。 - -## 3. 建立 Schema - -- [ ] 定义 `OntologyParseRequest`。 -- [ ] `OntologyParseRequest` 包含 `query`。 -- [ ] `OntologyParseRequest` 包含 `user_id`。 -- [ ] `OntologyParseRequest` 包含 `context_json`。 -- [ ] 定义 `OntologyParseResult`。 -- [ ] `OntologyParseResult` 包含 8 个核心字段。 -- [ ] `OntologyParseResult` 包含 `confidence`。 -- [ ] `OntologyParseResult` 包含 `clarification_required`。 -- [ ] `OntologyParseResult` 包含 `clarification_question`。 -- [ ] `OntologyParseResult` 包含 `run_id`。 -- [ ] 定义字段级错误结构。 - -验收证据： - -- [ ] OpenAPI 中可以看到语义解析请求和响应。 - -## 4. 实现解析服务 - -- [ ] 新增 `SemanticOntologyService` 或同等服务。 -- [ ] 实现 `parse(query, user_context)` 主函数。 -- [ ] 先做关键词规则解析。 -- [ ] 报销关键词映射到 `expense`。 -- [ ] 应收、回款、客户欠款映射到 `accounts_receivable`。 -- [ ] 应付、供应商、付款映射到 `accounts_payable`。 -- [ ] 风险、异常、重复、超标映射到 `risk_check`。 -- [ ] 为什么、依据、规则映射到 `explain`。 -- [ ] 统计、汇总、多少映射到 `query`。 -- [ ] 生成、创建、发起映射到 `draft` 或 `operate`。 -- [ ] 无法识别时返回低置信度和澄清问题。 - -验收证据： - -- [ ] “查一下本周报销超标风险”能识别为 expense + risk_check。 -- [ ] “客户 A 这个月还有多少应收”能识别为 accounts_receivable + query。 -- [ ] “供应商 B 明天要付多少钱”能识别为 accounts_payable + query。 - -## 5. 解析业务对象 - -- [ ] 从问题中提取员工姓名。 -- [ ] 从问题中提取部门。 -- [ ] 从问题中提取客户。 -- [ ] 从问题中提取供应商。 -- [ ] 从问题中提取项目。 -- [ ] 从问题中提取单据号。 -- [ ] 从问题中提取金额。 -- [ ] 从问题中提取费用类型。 -- [ ] 无法提取时返回空数组，不返回 null。 - -验收证据： - -- [ ] “张三 4 月差旅报销”能提取员工、月份、费用类型。 - -## 6. 解析时间范围 - -- [ ] 支持今天。 -- [ ] 支持昨天。 -- [ ] 支持本周。 -- [ ] 支持上周。 -- [ ] 支持本月。 -- [ ] 支持上月。 -- [ ] 支持本季度。 -- [ ] 支持今年。 -- [ ] 支持明确日期。 -- [ ] 支持日期区间。 -- [ ] 解析结果包含 `start_date` 和 `end_date`。 -- [ ] 日期使用 ISO 格式。 - -验收证据： - -- [ ] “本周”能解析为当前周起止日期。 -- [ ] “2026 年 4 月”能解析为 `2026-04-01` 到 `2026-04-30`。 - -## 7. 解析指标与约束 - -- [ ] 识别金额指标。 -- [ ] 识别数量指标。 -- [ ] 识别超标指标。 -- [ ] 识别逾期指标。 -- [ ] 识别重复报销指标。 -- [ ] 识别部门过滤条件。 -- [ ] 识别状态过滤条件。 -- [ ] 识别金额阈值过滤条件。 -- [ ] 识别排序要求。 -- [ ] 识别 Top N 要求。 - -验收证据： - -- [ ] “列出金额最高的 10 笔报销”能识别排序和 Top 10。 - -## 8. 解析风险与权限 - -- [ ] 重复报销映射到 `duplicate_expense`。 -- [ ] 发票异常映射到 `invoice_anomaly`。 -- [ ] 金额超标映射到 `amount_over_limit`。 -- [ ] 逾期应收映射到 `ar_overdue`。 -- [ ] 逾期应付映射到 `ap_overdue`。 -- [ ] 查询类问题权限为 `read`。 -- [ ] 生成草稿权限为 `draft_write`。 -- [ ] 审批、上线、付款类动作权限为 `approval_required`。 -- [ ] 越权动作权限为 `forbidden`。 - -验收证据： - -- [ ] “帮我直接付款”不能被标为可直接执行。 - -## 9. API 接口 - -- [ ] 新增 `POST /api/ontology/parse`。 -- [ ] 请求参数包含用户问题。 -- [ ] 请求参数包含用户上下文。 -- [ ] 响应包含 8 个字段。 -- [ ] 响应包含 `run_id`。 -- [ ] 响应包含置信度。 -- [ ] 响应包含澄清问题。 -- [ ] 每次调用写入 `SemanticParseLog`。 -- [ ] 每次调用写入 `AgentRun` 或关联已有 `AgentRun`。 - -验收证据： - -- [ ] 连续调用 5 次都能在日志中查到。 - -## 10. 前端调试入口 - -- [ ] 在合适页面增加语义解析调试入口。 -- [ ] 输入框支持自然语言问题。 -- [ ] 点击解析后调用 API。 -- [ ] 展示 8 个字段。 -- [ ] 展示 JSON 原始结果。 -- [ ] 展示置信度。 -- [ ] 展示澄清问题。 -- [ ] 展示 `run_id`。 -- [ ] 错误时展示错误信息。 - -验收证据： - -- [ ] 产品和开发可以直接在页面验证解析结果。 - -## 11. 评测集 - -- [ ] 创建至少 5 条报销问题。 -- [ ] 创建至少 5 条应收问题。 -- [ ] 创建至少 5 条应付问题。 -- [ ] 创建至少 3 条知识库问题。 -- [ ] 创建至少 3 条越权操作问题。 -- [ ] 为每条问题写期望 `scenario`。 -- [ ] 为每条问题写期望 `intent`。 -- [ ] 为每条问题写期望权限级别。 -- [ ] 编写评测脚本或测试。 - -验收证据： - -- [ ] 核心场景识别准确率达到当天设定阈值，例如 80%。 - -## 12. Day 3 验收 - -- [ ] 语义解析 API 可用。 -- [ ] 8 个核心字段完整返回。 -- [ ] 解析日志可查询。 -- [ ] 低置信度问题有澄清问题。 -- [ ] 越权动作不会被标为可执行。 -- [ ] 前端调试入口可用。 -- [ ] 评测集可运行。 -- [ ] 所有完成项已用 `[x] ~~...~~` 标记。 - -## 阻塞记录 - -- [ ] 暂无。 - -## 日终交接 - -- [ ] 写明已支持的关键词。 -- [ ] 写明识别不准的样例。 -- [ ] 写明 Day 4 Orchestrator 可以直接复用的响应结构。 diff --git a/document/development/agent plan/weekly_execution_details/day_4_orchestrator_runtime.md b/document/development/agent plan/weekly_execution_details/day_4_orchestrator_runtime.md deleted file mode 100644 index 63783fb..0000000 --- a/document/development/agent plan/weekly_execution_details/day_4_orchestrator_runtime.md +++ /dev/null @@ -1,185 +0,0 @@ -# Day 4：Orchestrator 运行时 TODO - -本文件是周计划 Day 4 的具体执行细则。路线图见 `document/development/agent week plan/day_4_orchestrator_runtime.md`。 - -目标：建立统一调度层，让用户请求和系统任务都先进入 Orchestrator，再根据语义本体、权限、能力注册路由到 User Agent、Hermes、MCP 或规则引擎。 - -参考文档： - -- `document/development/agent plan/04_orchestrator_and_runtime_flow.md` -- `document/development/agent plan/07_capability_registry.md` -- `document/development/agent plan/08_permission_confirmation.md` -- `document/development/agent plan/09_observability_and_trace.md` - -## 0. 开始前检查 - -- [ ] 确认 Day 3 `POST /api/ontology/parse` 可用。 -- [ ] 确认 `AgentRun` 可创建。 -- [ ] 确认 `AgentToolCall` 可创建。 -- [ ] 确认资产列表能查询技能、MCP、任务。 -- [ ] 确认权限级别枚举已稳定。 -- [ ] 找到后端服务层适合放 Orchestrator 的位置。 - -## 1. Orchestrator 输入输出 - -- [ ] 定义 `OrchestratorRequest`。 -- [ ] 请求包含 `source`。 -- [ ] 请求包含 `user_id`。 -- [ ] 请求包含 `message`。 -- [ ] 请求包含 `task_id`。 -- [ ] 请求包含 `context_json`。 -- [ ] 定义 `OrchestratorResponse`。 -- [ ] 响应包含 `run_id`。 -- [ ] 响应包含 `selected_agent`。 -- [ ] 响应包含 `route_reason`。 -- [ ] 响应包含 `permission_level`。 -- [ ] 响应包含 `status`。 -- [ ] 响应包含 `result`。 -- [ ] 响应包含 `requires_confirmation`。 -- [ ] 响应包含 `trace_summary`。 - -验收证据： - -- [ ] Orchestrator 响应能直接被前端展示。 - -## 2. 建立 Orchestrator 服务 - -- [ ] 新增 `OrchestratorService`。 -- [ ] 实现 `run(request)` 主入口。 -- [ ] 主入口第一步创建 `AgentRun`。 -- [ ] 主入口第二步调用语义解析。 -- [ ] 主入口第三步执行权限判断。 -- [ ] 主入口第四步选择 Agent。 -- [ ] 主入口第五步调用目标 Agent 或返回阻断结果。 -- [ ] 主入口第六步更新 `AgentRun` 状态。 -- [ ] 所有异常都写入 `AgentRun.error_message`。 - -验收证据： - -- [ ] 正常请求状态为 `succeeded`。 -- [ ] 被权限拦截请求状态为 `blocked`。 -- [ ] 异常请求状态为 `failed`。 - -## 3. 路由规则 - -- [ ] `source=user_message` 默认路由到 User Agent。 -- [ ] `source=schedule` 默认路由到 Hermes。 -- [ ] `intent=risk_check` 且来源为 schedule 时路由到 Hermes。 -- [ ] `intent=query` 且来源为 user_message 时路由到 User Agent。 -- [ ] `intent=explain` 路由到 User Agent。 -- [ ] `intent=draft` 路由到 User Agent，但只允许生成草稿。 -- [ ] `permission.level=approval_required` 时设置 `requires_confirmation=true`。 -- [ ] `permission.level=forbidden` 时不调用下游 Agent。 -- [ ] 无法识别时返回澄清问题。 - -验收证据： - -- [ ] 同一句风险检查，在用户入口和任务入口有不同路由结果。 - -## 4. 权限判断 - -- [ ] 新增权限判断服务或函数。 -- [ ] 查询类请求返回 `read`。 -- [ ] 草稿类请求返回 `draft_write`。 -- [ ] 审批、上线、付款类请求返回 `approval_required`。 -- [ ] 用户无权限时返回 `forbidden`。 -- [ ] 高风险动作不允许自动执行。 -- [ ] 需要确认的动作返回确认提示。 -- [ ] 权限判断结果写入 `AgentRun.permission_level`。 - -验收证据： - -- [ ] “直接上线规则”不会被自动执行。 -- [ ] “直接付款”不会被自动执行。 - -## 5. 能力注册查询 - -- [ ] 从 `AgentAsset` 查询 active 技能。 -- [ ] 从 `AgentAsset` 查询 active MCP。 -- [ ] 从 `AgentAsset` 查询 active 任务。 -- [ ] 过滤 disabled 能力。 -- [ ] 过滤未审核 active 条件不满足的规则。 -- [ ] 为每次能力选择记录 `route_json`。 -- [ ] 找不到能力时返回降级说明。 - -验收证据： - -- [ ] 禁用 MCP 不会被 Orchestrator 调用。 - -## 6. 工具调用封装 - -- [ ] 定义统一工具调用接口。 -- [ ] 工具请求前写入 `AgentToolCall` running 或准备记录。 -- [ ] 工具成功后写入响应和耗时。 -- [ ] 工具失败后写入错误。 -- [ ] 外部 MCP 调用失败时返回降级结果。 -- [ ] 数据库查询失败时返回明确错误。 -- [ ] LLM 调用失败时返回可读提示。 - -验收证据： - -- [ ] 每次 Orchestrator 运行至少可以看到 0 到多条工具调用记录。 - -## 7. API 接口 - -- [ ] 新增 `POST /api/orchestrator/run`。 -- [ ] 请求支持用户消息。 -- [ ] 请求支持任务触发。 -- [ ] 响应返回 `run_id`。 -- [ ] 响应返回路由结果。 -- [ ] 响应返回权限结果。 -- [ ] 新增 `GET /api/orchestrator/runs/{run_id}/trace` 或复用 AgentRun 详情接口。 -- [ ] Trace 接口返回语义解析、路由、工具调用、最终结果。 - -验收证据： - -- [ ] 前端或 curl 可以完整看到一次运行链路。 - -## 8. 前端最小 Trace 查看 - -- [ ] 在合适位置展示最近运行记录。 -- [ ] 点击运行记录能查看 `run_id`。 -- [ ] 展示 selected_agent。 -- [ ] 展示 route_reason。 -- [ ] 展示 permission_level。 -- [ ] 展示工具调用列表。 -- [ ] 展示错误信息。 -- [ ] 展示耗时。 - -验收证据： - -- [ ] 开发调试时不需要直接查数据库才能理解路由结果。 - -## 9. 测试 - -- [ ] 测试用户查询路由到 User Agent。 -- [ ] 测试定时任务路由到 Hermes。 -- [ ] 测试 forbidden 不调用下游 Agent。 -- [ ] 测试 approval_required 返回确认。 -- [ ] 测试工具失败写入 ToolCall。 -- [ ] 测试 Orchestrator 异常写入 AgentRun。 - -验收证据： - -- [ ] Orchestrator 核心测试通过。 - -## 10. Day 4 验收 - -- [ ] Orchestrator API 可用。 -- [ ] 用户请求能路由到 User Agent 占位实现。 -- [ ] 定时任务能路由到 Hermes 占位实现。 -- [ ] 权限阻断有效。 -- [ ] 运行 Trace 可查询。 -- [ ] 工具调用日志可查询。 -- [ ] 降级结果可读。 -- [ ] 所有完成项已用 `[x] ~~...~~` 标记。 - -## 阻塞记录 - -- [ ] 暂无。 - -## 日终交接 - -- [ ] 写明路由规则现状。 -- [ ] 写明权限判断现状。 -- [ ] 写明 Day 5 User Agent 需要实现的接口契约。 diff --git a/document/development/agent plan/weekly_execution_details/day_5_user_agent_mvp.md b/document/development/agent plan/weekly_execution_details/day_5_user_agent_mvp.md deleted file mode 100644 index 819db73..0000000 --- a/document/development/agent plan/weekly_execution_details/day_5_user_agent_mvp.md +++ /dev/null @@ -1,185 +0,0 @@ -# Day 5：User Agent MVP TODO - -本文件是周计划 Day 5 的具体执行细则。路线图见 `document/development/agent week plan/day_5_user_agent_mvp.md`。 - -目标：实现面向用户的自建 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 可以复用的规则、风险、知识接口。 diff --git a/document/development/agent plan/weekly_execution_details/day_6_hermes_mvp.md b/document/development/agent plan/weekly_execution_details/day_6_hermes_mvp.md deleted file mode 100644 index f599e29..0000000 --- a/document/development/agent plan/weekly_execution_details/day_6_hermes_mvp.md +++ /dev/null @@ -1,193 +0,0 @@ -# Day 6：Hermes MVP TODO - -本文件是周计划 Day 6 的具体执行细则。路线图见 `document/development/agent week plan/day_6_hermes_mvp.md`。 - -目标：实现 Hermes 数字员工的最小闭环。Hermes 不面向用户即时对话，而是负责定时巡检、统计、风险预警、知识维护和规则草稿形成。 - -参考文档： - -- `document/development/agent plan/03_agent_responsibilities.md` -- `document/development/agent plan/11_ocr_invoice_architecture.md` -- `document/development/agent plan/12_llm_wiki_knowledge_architecture.md` -- `document/development/agent plan/15_feedback_learning_loop.md` - -## 0. 开始前检查 - -- [ ] 确认任务资产 `asset_type=task` 可查询。 -- [ ] 确认 Orchestrator 能处理 `source=schedule`。 -- [ ] 确认 Hermes 占位服务可被调用。 -- [ ] 确认 AgentRun 和 ToolCall 可记录。 -- [ ] 确认是否已有后台任务框架。 -- [ ] 如果没有后台任务框架，先用手动触发 API 模拟定时执行。 - -## 1. Hermes 输入输出 - -- [ ] 定义 `HermesTaskRequest`。 -- [ ] 请求包含 `run_id`。 -- [ ] 请求包含 `task_asset_id`。 -- [ ] 请求包含 `task_type`。 -- [ ] 请求包含 `schedule_time`。 -- [ ] 请求包含 `context_json`。 -- [ ] 定义 `HermesTaskResult`。 -- [ ] 响应包含 `summary`。 -- [ ] 响应包含 `risk_items`。 -- [ ] 响应包含 `statistics`。 -- [ ] 响应包含 `knowledge_updates`。 -- [ ] 响应包含 `draft_rules`。 -- [ ] 响应包含 `next_actions`。 - -验收证据： - -- [ ] Hermes 响应能被任务详情或运行日志展示。 - -## 2. 任务调度入口 - -- [ ] 新增手动触发任务 API。 -- [ ] API 参数支持任务资产 ID。 -- [ ] API 调用 Orchestrator，source 为 `schedule`。 -- [ ] Orchestrator 路由到 Hermes。 -- [ ] Hermes 执行结果写入 AgentRun。 -- [ ] 任务执行失败时写入错误。 -- [ ] 任务执行结束后更新任务最近执行时间。 -- [ ] 任务执行结束后更新任务最近执行状态。 - -验收证据： - -- [ ] 可以手动触发一次 Hermes 任务并看到运行结果。 - -## 3. 每日风险巡检 - -- [ ] 实现重复报销巡检。 -- [ ] 实现金额超标巡检。 -- [ ] 实现发票异常巡检占位。 -- [ ] 实现应收逾期巡检。 -- [ ] 实现应付异常付款巡检。 -- [ ] 每个风险项包含风险类型。 -- [ ] 每个风险项包含业务对象。 -- [ ] 每个风险项包含触发规则。 -- [ ] 每个风险项包含建议动作。 -- [ ] 每个风险项包含风险等级。 - -验收证据： - -- [ ] 风险巡检结果可以被用户理解和追溯。 - -## 4. 每日统计 - -- [ ] 统计当日报销单数量。 -- [ ] 统计当日报销金额。 -- [ ] 统计当日报账数量。 -- [ ] 统计当日报账金额。 -- [ ] 统计应收新增金额。 -- [ ] 统计应收逾期金额。 -- [ ] 统计应付待付金额。 -- [ ] 统计应付逾期金额。 -- [ ] 输出日报摘要。 - -验收证据： - -- [ ] Hermes 能生成一份每日财务摘要。 - -## 5. OCR 接入点 - -- [ ] 建立 OCR 识别服务接口。 -- [ ] 定义发票识别输入结构。 -- [ ] 定义发票识别输出结构。 -- [ ] 输出结构包含发票号。 -- [ ] 输出结构包含开票日期。 -- [ ] 输出结构包含金额。 -- [ ] 输出结构包含税额。 -- [ ] 输出结构包含销售方。 -- [ ] 输出结构包含购买方。 -- [ ] 输出结构包含置信度。 -- [ ] 当前阶段允许使用 Mock 结果。 -- [ ] OCR 调用写入 ToolCall。 - -验收证据： - -- [ ] Hermes 风险巡检中可以调用 OCR Mock。 - -## 6. 知识库维护 - -- [ ] 建立知识条目写入服务。 -- [ ] Hermes 可以生成知识候选条目。 -- [ ] 候选条目包含标题。 -- [ ] 候选条目包含正文。 -- [ ] 候选条目包含来源。 -- [ ] 候选条目包含适用场景。 -- [ ] 候选条目默认状态为 `draft`。 -- [ ] 知识条目不能自动发布。 -- [ ] 知识条目写入审计日志。 - -验收证据： - -- [ ] Hermes 可以生成待审核知识条目。 - -## 7. 规则草稿形成 - -- [ ] Hermes 可以根据风险巡检结果生成规则草稿。 -- [ ] 规则草稿保存为 `asset_type=rule`。 -- [ ] 规则草稿状态为 `draft`。 -- [ ] 规则草稿包含 Markdown 内容。 -- [ ] 规则草稿包含生成原因。 -- [ ] 规则草稿包含关联风险样例。 -- [ ] 规则草稿不能自动上线。 -- [ ] 规则草稿需要审核人。 -- [ ] 规则草稿写入审计日志。 - -验收证据： - -- [ ] Hermes 生成的新规则出现在规则列表中，但不是 active。 - -## 8. Hermes 页面或日志展示 - -- [ ] 任务详情能看到最近执行结果。 -- [ ] 任务详情能手动触发执行。 -- [ ] 任务详情能看到风险项数量。 -- [ ] 任务详情能看到日报摘要。 -- [ ] 任务详情能看到知识候选数量。 -- [ ] 任务详情能看到规则草稿数量。 -- [ ] 运行 Trace 能看到 Hermes 步骤。 -- [ ] 错误时展示错误原因。 - -验收证据： - -- [ ] 不查数据库也能判断 Hermes 是否执行成功。 - -## 9. 测试 - -- [ ] 测试手动触发任务。 -- [ ] 测试 Orchestrator 路由到 Hermes。 -- [ ] 测试风险巡检输出。 -- [ ] 测试日报统计输出。 -- [ ] 测试 OCR Mock 调用。 -- [ ] 测试知识候选写入。 -- [ ] 测试规则草稿生成。 -- [ ] 测试 Hermes 异常写入 AgentRun。 - -验收证据： - -- [ ] Hermes 核心测试通过。 - -## 10. Day 6 验收 - -- [ ] Hermes 可被 Orchestrator 调用。 -- [ ] 至少一个任务可以手动触发。 -- [ ] 风险巡检有结构化结果。 -- [ ] 每日统计有结构化结果。 -- [ ] OCR Mock 接入点可用。 -- [ ] 知识候选可生成。 -- [ ] 规则草稿可生成且不能自动上线。 -- [ ] 任务详情或运行日志能展示结果。 -- [ ] 所有完成项已用 `[x] ~~...~~` 标记。 - -## 阻塞记录 - -- [ ] 暂无。 - -## 日终交接 - -- [ ] 写明 Hermes 已支持任务类型。 -- [ ] 写明 OCR 当前是真实还是 Mock。 -- [ ] 写明生成的知识和规则草稿状态。 -- [ ] 写明 Day 7 需要重点回归的路径。 diff --git a/document/development/agent plan/weekly_execution_details/day_7_hardening_demo_acceptance.md b/document/development/agent plan/weekly_execution_details/day_7_hardening_demo_acceptance.md deleted file mode 100644 index ad9845f..0000000 --- a/document/development/agent plan/weekly_execution_details/day_7_hardening_demo_acceptance.md +++ /dev/null @@ -1,225 +0,0 @@ -# Day 7：加固、演示和验收 TODO - -本文件是周计划 Day 7 的具体执行细则。路线图见 `document/development/agent week plan/day_7_hardening_demo_acceptance.md`。 - -目标：把前 6 天做出的功能整理成可演示、可验收、可继续迭代的基础平台。Day 7 不再大规模扩功能，重点是修缺口、补测试、补日志、补文档、完成演示链路。 - -参考文档： - -- `document/development/agent plan/00_README.md` -- `document/development/agent plan/05_development_roadmap.md` -- `document/development/agent plan/09_observability_and_trace.md` -- `document/development/agent plan/10_evaluation_and_testset.md` - -## 0. 开始前检查 - -- [ ] 汇总 Day 1 未完成项。 -- [ ] 汇总 Day 2 未完成项。 -- [ ] 汇总 Day 3 未完成项。 -- [ ] 汇总 Day 4 未完成项。 -- [ ] 汇总 Day 5 未完成项。 -- [ ] 汇总 Day 6 未完成项。 -- [ ] 标记必须今天修复的问题。 -- [ ] 标记可以进入下一阶段的问题。 -- [ ] 冻结新增需求，只处理验收相关问题。 - -## 1. 核心链路回归 - -- [ ] 回归资产列表接口。 -- [ ] 回归规则详情接口。 -- [ ] 回归 Markdown 保存。 -- [ ] 回归版本列表。 -- [ ] 回归版本切换。 -- [ ] 回归审核接口。 -- [ ] 回归上线拦截。 -- [ ] 回归语义解析接口。 -- [ ] 回归 Orchestrator 路由。 -- [ ] 回归 User Agent 问答。 -- [ ] 回归 Hermes 任务执行。 -- [ ] 回归 AgentRun Trace。 -- [ ] 回归 ToolCall 日志。 -- [ ] 回归 AuditLog 日志。 - -验收证据： - -- [ ] 从前端能完成至少一条端到端演示路径。 - -## 2. 权限和风险边界 - -- [ ] 未审核规则不能上线。 -- [ ] rejected 规则不能上线。 -- [ ] disabled 能力不能被调用。 -- [ ] 用户请求付款必须拦截。 -- [ ] 用户请求审批必须需要确认。 -- [ ] Hermes 生成规则只能是 draft。 -- [ ] Hermes 生成知识只能是 draft。 -- [ ] User Agent 生成处理意见只能是草稿。 -- [ ] 所有高风险动作响应中包含 `requires_confirmation`。 - -验收证据： - -- [ ] 不存在 MVP 期间绕过人工审核的路径。 - -## 3. 审计和 Trace 补齐 - -- [ ] 规则保存写 AuditLog。 -- [ ] 规则审核写 AuditLog。 -- [ ] 规则上线写 AuditLog。 -- [ ] Hermes 生成规则草稿写 AuditLog。 -- [ ] Hermes 生成知识候选写 AuditLog。 -- [ ] User Agent 草稿生成写 AuditLog。 -- [ ] Orchestrator 每次运行有 AgentRun。 -- [ ] 每次工具调用有 ToolCall。 -- [ ] Trace 页面或接口能串起 run_id。 -- [ ] 错误 Trace 包含 error_message。 - -验收证据： - -- [ ] 任意一条演示链路都能追溯到 run_id。 - -## 4. 前端体验修补 - -- [ ] 任务规则中心列表无明显错位。 -- [ ] 详情页无双 title。 -- [ ] Hero title 高度紧凑。 -- [ ] 返回列表栏高度正常。 -- [ ] Markdown 编辑器和版本卡片底部对齐。 -- [ ] 版本卡片不贴右侧。 -- [ ] 当前版本标识不突兀。 -- [ ] 日期列对齐。 -- [ ] 弹窗文案清楚。 -- [ ] 加载态可见。 -- [ ] 错误态可见。 -- [ ] 空态可见。 -- [ ] 按钮禁用态可见。 -- [ ] 窄屏不出现内容重叠。 - -验收证据： - -- [ ] 任务规则中心可以给业务用户演示，不需要解释 UI 异常。 - -## 5. 测试补齐 - -- [ ] 运行后端现有测试。 -- [ ] 运行新增模型测试。 -- [ ] 运行新增 API 测试。 -- [ ] 运行语义解析测试。 -- [ ] 运行 Orchestrator 测试。 -- [ ] 运行 User Agent 测试。 -- [ ] 运行 Hermes 测试。 -- [ ] 运行前端构建。 -- [ ] 如果有前端测试，运行前端测试。 -- [ ] 记录未能运行的测试和原因。 - -验收证据： - -- [ ] 测试结果写入本文件“测试记录”。 - -## 6. 评测集 - -- [ ] 准备 5 条报销问题。 -- [ ] 准备 5 条应收问题。 -- [ ] 准备 5 条应付问题。 -- [ ] 准备 3 条规则解释问题。 -- [ ] 准备 3 条越权动作问题。 -- [ ] 执行语义解析评测。 -- [ ] 执行 User Agent 回答评测。 -- [ ] 执行权限拦截评测。 -- [ ] 记录失败样例。 -- [ ] 为失败样例写下一阶段优化建议。 - -验收证据： - -- [ ] 可以说明 MVP 当前能力边界和准确率风险。 - -## 7. 演示数据 - -- [ ] 准备 active 规则。 -- [ ] 准备 pending 规则。 -- [ ] 准备 rejected 规则。 -- [ ] 准备至少一条报销数据。 -- [ ] 准备至少一条应收数据。 -- [ ] 准备至少一条应付数据。 -- [ ] 准备至少一个 Hermes 任务。 -- [ ] 准备至少一个 MCP Mock。 -- [ ] 准备至少一个知识条目。 -- [ ] 准备至少一个风险样例。 - -验收证据： - -- [ ] 演示不会因为没有数据而中断。 - -## 8. 演示脚本 - -- [ ] 编写演示步骤 1：打开任务规则中心。 -- [ ] 编写演示步骤 2：查看规则详情。 -- [ ] 编写演示步骤 3：编辑 Markdown 并保存。 -- [ ] 编写演示步骤 4：切换版本。 -- [ ] 编写演示步骤 5：尝试上线未审核规则并被拦截。 -- [ ] 编写演示步骤 6：输入用户问题。 -- [ ] 编写演示步骤 7：查看语义本体结果。 -- [ ] 编写演示步骤 8：查看 User Agent 回答。 -- [ ] 编写演示步骤 9：手动触发 Hermes 任务。 -- [ ] 编写演示步骤 10：查看 AgentRun Trace。 -- [ ] 编写演示步骤 11：查看审计日志。 - -验收证据： - -- [ ] 新开发者按脚本可以复现演示。 - -## 9. 文档收尾 - -- [ ] 更新一周计划完成情况。 -- [ ] 更新剩余风险。 -- [ ] 更新下一阶段开发建议。 -- [ ] 更新接口清单。 -- [ ] 更新数据模型清单。 -- [ ] 更新前端页面清单。 -- [ ] 更新评测结果。 -- [ ] 更新演示脚本。 -- [ ] 更新部署或启动说明。 - -验收证据： - -- [ ] 文档能指导下一周继续开发。 - -## 10. 最终验收清单 - -- [ ] 任务规则中心可查看规则、技能、MCP、任务。 -- [ ] 规则详情可编辑 Markdown。 -- [ ] 规则详情可查看最近 5 个版本。 -- [ ] 版本切换有确认弹窗。 -- [ ] 审核者信息可见。 -- [ ] 未审核规则不能上线。 -- [ ] 语义本体 8 字段可返回。 -- [ ] Orchestrator 能路由用户请求。 -- [ ] Orchestrator 能路由定时任务。 -- [ ] User Agent 能回答至少 3 类财务问题。 -- [ ] Hermes 能执行至少 1 个任务。 -- [ ] OCR Mock 接入点可用。 -- [ ] 知识候选可生成。 -- [ ] 规则草稿可生成。 -- [ ] AgentRun Trace 可查。 -- [ ] AuditLog 可查。 -- [ ] 前端构建通过。 -- [ ] 后端核心测试通过。 -- [ ] 演示脚本可执行。 -- [ ] 所有完成项已用 `[x] ~~...~~` 标记。 - -## 测试记录 - -- [ ] 后端测试：未运行。 -- [ ] 前端构建：未运行。 -- [ ] 语义评测：未运行。 -- [ ] 手动验收：未运行。 - -## 阻塞记录 - -- [ ] 暂无。 - -## 日终交接 - -- [ ] 写明本周最终完成内容。 -- [ ] 写明未完成内容。 -- [ ] 写明生产化前必须补齐内容。 -- [ ] 写明下一周建议优先级。