From 4f3556a38b5e3256a599fa7f6bdfe6b714ee2a3e Mon Sep 17 00:00:00 2001 From: caoxiaozhu Date: Fri, 15 May 2026 06:58:21 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9Eagent=E5=BC=80?= =?UTF-8?q?=E5=8F=91=E6=96=87=E6=A1=A3=E5=92=8C=E9=A3=8E=E9=99=A9=E8=AF=84?= =?UTF-8?q?=E4=BC=B0=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../development/agent/agent plan/00_README.md | 58 ++ .../agent plan/01_overall_architecture.md | 163 +++++ .../agent/agent plan/02_semantic_ontology.md | 457 +++++++++++++ .../agent plan/03_agent_responsibilities.md | 178 +++++ .../04_orchestrator_and_runtime_flow.md | 385 +++++++++++ .../agent plan/05_development_roadmap.md | 458 +++++++++++++ .../06_data_contracts_and_governance.md | 445 ++++++++++++ .../agent plan/07_capability_registry.md | 198 ++++++ .../agent plan/08_permission_confirmation.md | 214 ++++++ .../agent plan/09_observability_and_trace.md | 186 +++++ .../agent plan/10_evaluation_and_testset.md | 198 ++++++ .../agent plan/11_ocr_invoice_architecture.md | 376 ++++++++++ .../12_llm_wiki_knowledge_architecture.md | 221 ++++++ .../agent plan/13_rule_formation_lifecycle.md | 194 ++++++ .../14_financial_document_canonical_model.md | 646 ++++++++++++++++++ .../agent plan/15_feedback_learning_loop.md | 119 ++++ .../agent/agent week plan/00_README.md | 77 +++ .../agent/agent week plan/MASTER_TODO.md | 73 ++ .../day_1_foundation_models.md | 221 ++++++ .../day_2_rule_center_integration.md | 296 ++++++++ .../day_3_semantic_ontology_mvp.md | 304 +++++++++ .../day_4_orchestrator_runtime.md | 254 +++++++ .../agent week plan/day_5_user_agent_mvp.md | 284 ++++++++ .../agent/agent week plan/day_6_hermes_mvp.md | 314 +++++++++ .../day_7_hardening_demo_acceptance.md | 260 +++++++ .../agent/agent_week_plan_html/day-1.html | 137 ++++ .../agent/agent_week_plan_html/day-2.html | 132 ++++ .../agent/agent_week_plan_html/day-3.html | 132 ++++ .../agent/agent_week_plan_html/day-4.html | 133 ++++ .../agent/agent_week_plan_html/day-5.html | 133 ++++ .../agent/agent_week_plan_html/day-6.html | 133 ++++ .../agent/agent_week_plan_html/day-7.html | 132 ++++ .../agent/agent_week_plan_html/index.html | 181 +++++ .../agent/agent_week_plan_html/styles.css | 426 ++++++++++++ .../risks/travel-risk-control-standard.md | 139 ++++ 35 files changed, 8257 insertions(+) create mode 100644 document/development/agent/agent plan/00_README.md create mode 100644 document/development/agent/agent plan/01_overall_architecture.md create mode 100644 document/development/agent/agent plan/02_semantic_ontology.md create mode 100644 document/development/agent/agent plan/03_agent_responsibilities.md create mode 100644 document/development/agent/agent plan/04_orchestrator_and_runtime_flow.md create mode 100644 document/development/agent/agent plan/05_development_roadmap.md create mode 100644 document/development/agent/agent plan/06_data_contracts_and_governance.md create mode 100644 document/development/agent/agent plan/07_capability_registry.md create mode 100644 document/development/agent/agent plan/08_permission_confirmation.md create mode 100644 document/development/agent/agent plan/09_observability_and_trace.md create mode 100644 document/development/agent/agent plan/10_evaluation_and_testset.md create mode 100644 document/development/agent/agent plan/11_ocr_invoice_architecture.md create mode 100644 document/development/agent/agent plan/12_llm_wiki_knowledge_architecture.md create mode 100644 document/development/agent/agent plan/13_rule_formation_lifecycle.md create mode 100644 document/development/agent/agent plan/14_financial_document_canonical_model.md create mode 100644 document/development/agent/agent plan/15_feedback_learning_loop.md create mode 100644 document/development/agent/agent week plan/00_README.md create mode 100644 document/development/agent/agent week plan/MASTER_TODO.md create mode 100644 document/development/agent/agent week plan/day_1_foundation_models.md create mode 100644 document/development/agent/agent week plan/day_2_rule_center_integration.md create mode 100644 document/development/agent/agent week plan/day_3_semantic_ontology_mvp.md create mode 100644 document/development/agent/agent week plan/day_4_orchestrator_runtime.md create mode 100644 document/development/agent/agent week plan/day_5_user_agent_mvp.md create mode 100644 document/development/agent/agent week plan/day_6_hermes_mvp.md create mode 100644 document/development/agent/agent week plan/day_7_hardening_demo_acceptance.md create mode 100644 document/development/agent/agent_week_plan_html/day-1.html create mode 100644 document/development/agent/agent_week_plan_html/day-2.html create mode 100644 document/development/agent/agent_week_plan_html/day-3.html create mode 100644 document/development/agent/agent_week_plan_html/day-4.html create mode 100644 document/development/agent/agent_week_plan_html/day-5.html create mode 100644 document/development/agent/agent_week_plan_html/day-6.html create mode 100644 document/development/agent/agent_week_plan_html/day-7.html create mode 100644 document/development/agent/agent_week_plan_html/index.html create mode 100644 document/development/agent/agent_week_plan_html/styles.css create mode 100644 document/development/risks/travel-risk-control-standard.md diff --git a/document/development/agent/agent plan/00_README.md b/document/development/agent/agent plan/00_README.md new file mode 100644 index 0000000..6e061c6 --- /dev/null +++ b/document/development/agent/agent plan/00_README.md @@ -0,0 +1,58 @@ +# Agent Plan 文档索引 + +本目录描述 X-Financial 后续要建设的双 Agent 财务智能架构。 + +核心目标： + +- 建立一套共享的语义本体协议，统一理解用户问题、定时任务和规则触发上下文。 +- 建设两套职责边界清晰的 Agent： + - Hermes：后台数字员工，负责内循环定时任务、风险巡检、统计、知识维护。 + - 自建 Agent：用户流程助手，负责用户交互、流程操作、解释、查询、草稿生成。 +- 建设 Agent Orchestrator，统一负责路由、权限、工具调用、审计和失败处理。 +- 让规则中心、MCP、知识库、数据库查询和任务系统使用同一套语义协议。 + +## 与一周计划的关系 + +`document/development/agent week plan` 是一周开发路线图，只描述每天要完成的大方向和交付结果。 + +本目录是具体架构与实现依据，包含： + +- 架构设计。 +- 数据协议。 +- Agent 职责。 +- Orchestrator 流程。 +- OCR、知识库、规则生命周期。 +- 每天 daily 文档会引用到的设计依据。 + +执行时按这个顺序阅读： + +1. 先看 `document/development/agent week plan/MASTER_TODO.md`，确认今天做什么。 +2. 再看本目录的架构文档，理解为什么这样做。 +3. 最后进入 `document/development/agent week plan/` 对应 Day 文档，在同一份文档中按详细执行清单开发。 + +推荐阅读顺序： + +1. [01_overall_architecture.md](./01_overall_architecture.md) +2. [02_semantic_ontology.md](./02_semantic_ontology.md) +3. [03_agent_responsibilities.md](./03_agent_responsibilities.md) +4. [04_orchestrator_and_runtime_flow.md](./04_orchestrator_and_runtime_flow.md) +5. [05_development_roadmap.md](./05_development_roadmap.md) +6. [06_data_contracts_and_governance.md](./06_data_contracts_and_governance.md) +7. [07_capability_registry.md](./07_capability_registry.md) +8. [08_permission_confirmation.md](./08_permission_confirmation.md) +9. [09_observability_and_trace.md](./09_observability_and_trace.md) +10. [10_evaluation_and_testset.md](./10_evaluation_and_testset.md) +11. [11_ocr_invoice_architecture.md](./11_ocr_invoice_architecture.md) +12. [12_llm_wiki_knowledge_architecture.md](./12_llm_wiki_knowledge_architecture.md) +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. [../agent week plan/00_README.md](<../agent week plan/00_README.md>) + +开发原则： + +- 先语义协议，后 Agent 能力。 +- 先只读和建议，后写入和流程动作。 +- 先人工确认，后有限自动化。 +- 所有财务关键动作必须可审计、可回滚、可追责。 +- 所有 Agent 能力必须注册、分级、可评测、可追踪。 diff --git a/document/development/agent/agent plan/01_overall_architecture.md b/document/development/agent/agent plan/01_overall_architecture.md new file mode 100644 index 0000000..6d737f0 --- /dev/null +++ b/document/development/agent/agent plan/01_overall_architecture.md @@ -0,0 +1,163 @@ +# 双 Agent 总体架构 + +## 1. 背景 + +X-Financial 后续需要同时支持两类智能化能力： + +1. 用户主动发起的交互式流程操作。 +2. 系统后台自动运行的定时巡检、统计、预警和知识维护。 + +如果用一个万能 Agent 同时处理这两类任务，风险会很高： + +- 用户流程操作需要权限、确认、上下文追问。 +- 定时巡检需要稳定批处理、失败重试、审计记录。 +- 财务系统不能让大模型直接决定审批、付款、规则上线。 + +因此建议建设双 Agent 架构： + +```text +Hermes Agent + 后台数字员工 + 面向系统内循环 + 定时、批量、巡检、统计、预警、知识候选 + +User Agent + 自建用户流程助手 + 面向用户交互 + 查询、解释、创建草稿、流程操作、审批辅助 +``` + +两套 Agent 共享一套语义本体协议，由 Agent Orchestrator 统一调度。 + +## 2. 总体架构图 + +```text + ┌──────────────────────┐ + │ 用户自然语言 / 定时任务 │ + └───────────┬──────────┘ + │ + ▼ + ┌──────────────────────┐ + │ Semantic Ontology │ + │ 语义本体解析层 │ + └───────────┬──────────┘ + │ + ▼ + ┌──────────────────────┐ + │ Agent Orchestrator │ + │ 路由 / 权限 / 审计 / 调度 │ + └───────┬─────────┬────┘ + │ │ + ┌─────────────▼─┐ ┌─▼──────────────┐ + │ Hermes Agent │ │ User Agent │ + │ 后台数字员工 │ │ 用户流程助手 │ + └───────┬───────┘ └───────┬────────┘ + │ │ + └──────────┬──────────┘ + │ + ┌────────────┬───────────┼───────────┬────────────┐ + ▼ ▼ ▼ ▼ ▼ + 规则中心 MCP 服务 业务数据库 知识库 任务系统 +``` + +## 3. 核心分层 + +### 3.1 语义本体层 + +负责把自然语言或任务配置转成结构化 JSON。 + +输出不是最终答案，而是统一协议： + +```json +{ + "domain": "reimbursement", + "scenario": "invoice_validation", + "intent": "explain_risk", + "entities": [], + "time_range": {}, + "constraints": {}, + "risk_signals": [], + "next_step": "run_rule" +} +``` + +### 3.2 编排层 + +Agent Orchestrator 负责： + +- 判断应该由 Hermes 还是 User Agent 处理。 +- 判断是否需要查数据库、跑规则、调 MCP、检索知识库。 +- 检查用户权限。 +- 记录审计日志。 +- 控制失败重试。 +- 对高风险动作要求用户或管理员确认。 + +### 3.3 Agent 层 + +Hermes 和 User Agent 不直接决定财务关键状态。 + +它们负责： + +- 理解任务。 +- 组织工具调用。 +- 汇总工具结果。 +- 生成建议、解释、报告、草稿。 + +### 3.4 能力层 + +能力层包括： + +- 规则中心：管理 `.md` 规则文件、审核、版本。 +- MCP：封装外部服务，如发票验真、银行流水、OCR、差旅平台。 +- 数据库查询：查询报销、报账、应收、应付、账款数据。 +- 知识库：制度文档、FAQ、历史解释、规则说明。 +- 任务系统：定时任务、批量任务、重试、运行日志。 + +## 4. 关键边界 + +Hermes 可以： + +- 定时读取数据。 +- 执行规则检查。 +- 调 MCP 查询外部状态。 +- 生成风险报告。 +- 生成知识候选。 +- 生成待处理工单。 + +Hermes 不可以： + +- 自动提交报销。 +- 自动发起付款。 +- 自动审批通过。 +- 自动发布知识库正式内容。 +- 自动上线规则。 + +User Agent 可以： + +- 帮用户查询状态。 +- 帮用户解释风险。 +- 帮用户创建报销或付款草稿。 +- 帮审批人生成审批意见。 +- 在用户确认后调用流程 API。 + +User Agent 不可以： + +- 绕过权限。 +- 未确认直接提交关键动作。 +- 自动最终审批。 +- 自动付款。 +- 修改规则审核状态。 + +## 5. 推荐建设顺序 + +```text +Step 1: 建立语义本体 JSON 协议 +Step 2: 建立规则中心的规则/技能/MCP/任务目录 +Step 3: 建立 Orchestrator 路由和审计 +Step 4: 建立 User Agent 的只读查询和解释能力 +Step 5: 建立 Hermes 的定时任务和报告能力 +Step 6: 接入 MCP 和业务数据库 +Step 7: 增加用户确认后的流程写入能力 +Step 8: 增加知识候选和规则优化闭环 +``` + diff --git a/document/development/agent/agent plan/02_semantic_ontology.md b/document/development/agent/agent plan/02_semantic_ontology.md new file mode 100644 index 0000000..9fefedd --- /dev/null +++ b/document/development/agent/agent plan/02_semantic_ontology.md @@ -0,0 +1,457 @@ +# 语义本体协议设计 + +## 1. 定位 + +语义本体协议是用户问题、定时任务、规则中心、MCP、数据库查询和 Agent 之间的统一中间层。 + +它解决的问题是： + +- 用户到底在问哪个业务域？ +- 这属于什么场景？ +- 用户想做什么？ +- 问题中涉及哪些对象？ +- 有没有时间、金额、状态、部门等过滤条件？ +- 是否涉及风险？ +- 下一步应该查知识库、查数据库、跑规则、调 MCP，还是追问？ + +## 2. 第一版核心字段 + +第一版建议只强制落 8 个字段。 + +```json +{ + "domain": "", + "scenario": "", + "intent": "", + "entities": [], + "time_range": {}, + "constraints": {}, + "risk_signals": [], + "next_step": "" +} +``` + +### 2.1 domain + +一级业务域。 + +建议枚举： + +```text +reimbursement +accounts_receivable +accounts_payable +general_finance +system_operation +``` + +含义： + +- `reimbursement`：报销、差旅、发票、补件。 +- `accounts_receivable`：应收账款、客户开票、收款、账龄。 +- `accounts_payable`：应付账款、供应商发票、付款、对账。 +- `general_finance`：通用财务知识、制度、统计。 +- `system_operation`：系统巡检、任务运行、规则维护、MCP 健康检查。 + +### 2.2 scenario + +细分场景。 + +报销： + +```text +travel_reimbursement +daily_expense +invoice_validation +attachment_review +policy_overrun +reimbursement_audit +``` + +应收： + +```text +customer_invoice +collection_followup +receivable_aging +payment_matching +bad_debt_risk +contract_receivable +``` + +应付： + +```text +vendor_invoice +payment_request +payable_aging +vendor_reconciliation +invoice_matching +cash_outflow_forecast +``` + +系统运营： + +```text +daily_risk_scan +daily_finance_statistics +knowledge_accumulation +mcp_health_check +rule_quality_review +``` + +### 2.3 intent + +用户或任务的意图。 + +建议枚举： + +```text +query +explain +create +validate +summarize +reconcile +monitor +predict +remind +generate +optimize +``` + +### 2.4 entities + +识别出的业务对象。 + +统一结构： + +```json +{ + "type": "invoice", + "value": "INV-202605001", + "normalized_value": "INV-202605001", + "role": "target", + "confidence": 0.92 +} +``` + +常见实体： + +```text +employee +department +customer +vendor +invoice +contract +reimbursement_request +payment_order +receipt +bank_transaction +cost_center +project +policy +approval_node +rule +task +``` + +### 2.5 time_range + +统一描述时间。 + +```json +{ + "raw": "上个月", + "start": "2026-04-01", + "end": "2026-04-30", + "granularity": "month" +} +``` + +Hermes 定时任务也使用同一字段。 + +例如每日风险巡检： + +```json +{ + "raw": "昨日", + "start": "2026-05-09", + "end": "2026-05-09", + "granularity": "day" +} +``` + +### 2.6 constraints + +查询、判断或执行条件。 + +```json +{ + "status": "overdue", + "aging_days": ">30", + "amount": { + "operator": ">", + "value": 50000, + "currency": "CNY" + }, + "department": "销售部", + "risk_level": ["medium", "high"] +} +``` + +### 2.7 risk_signals + +风险信号。 + +建议枚举： + +```text +duplicate_invoice +missing_attachment +policy_overrun +over_budget +overdue_receivable +bad_debt_risk +vendor_payment_risk +payment_mismatch +contract_mismatch +cashflow_pressure +mcp_unavailable +rule_quality_issue +``` + +### 2.8 next_step + +下一步动作。 + +建议枚举： + +```text +answer +ask_clarification +query_database +run_rule +call_mcp +search_knowledge +create_draft +create_task +generate_report +notify_user +escalate_to_human +``` + +## 3. 扩展字段 + +后续可以增加： + +```json +{ + "schema_version": "1.1", + "confidence": 0.86, + "ambiguity": [], + "missing_slots": [], + "required_capabilities": [], + "normalized_query": "", + "permission_scope": {}, + "audit_tags": [] +} +``` + +## 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 +我要报销 +这个为什么还没处理 +帮我看一下这个 +上传好了，下一步呢 +``` + +处理原则： + +- 不允许直接执行工具。 +- 不允许直接落到应收、应付查询。 +- 必须生成澄清问题。 +- 必须在审计中记录触发追问的原因。 + +扩展原则： + +- 先不要把所有字段都做成数据库列。 +- 语义结果建议存 JSONB。 +- 使用 `schema_version` 管理版本。 +- Orchestrator 只依赖稳定字段。 +- 新字段以可选方式加入，不影响老任务。 + +## 4. 示例 + +### 4.1 用户查询应收账龄 + +用户问： + +```text +上个月哪些客户应收逾期超过 30 天？ +``` + +解析： + +```json +{ + "domain": "accounts_receivable", + "scenario": "receivable_aging", + "intent": "query", + "entities": [ + { + "type": "customer", + "value": "客户", + "role": "group_by" + } + ], + "time_range": { + "raw": "上个月", + "start": "2026-04-01", + "end": "2026-04-30", + "granularity": "month" + }, + "constraints": { + "aging_days": ">30", + "status": "overdue" + }, + "risk_signals": ["overdue_receivable"], + "next_step": "query_database" +} +``` + +### 4.2 用户解释发票拦截 + +用户问： + +```text +这张发票为什么报销被拦截？ +``` + +解析： + +```json +{ + "domain": "reimbursement", + "scenario": "invoice_validation", + "intent": "explain", + "entities": [ + { + "type": "invoice", + "value": "这张发票", + "role": "target" + } + ], + "time_range": {}, + "constraints": {}, + "risk_signals": ["unknown"], + "next_step": "run_rule" +} +``` + +### 4.3 Hermes 每日风险巡检 + +任务配置： + +```json +{ + "domain": "reimbursement", + "scenario": "daily_risk_scan", + "intent": "monitor", + "entities": [], + "time_range": { + "raw": "昨日" + }, + "constraints": { + "risk_level": ["medium", "high"] + }, + "risk_signals": [ + "duplicate_invoice", + "missing_attachment", + "policy_overrun" + ], + "next_step": "run_rule" +} +``` diff --git a/document/development/agent/agent plan/03_agent_responsibilities.md b/document/development/agent/agent plan/03_agent_responsibilities.md new file mode 100644 index 0000000..6d5382f --- /dev/null +++ b/document/development/agent/agent plan/03_agent_responsibilities.md @@ -0,0 +1,178 @@ +# Hermes 与自建 Agent 职责边界 + +## 1. 两套 Agent 的定位 + +### 1.1 Hermes + +Hermes 定位为后台数字员工。 + +它不直接面向用户聊天，而是在系统后台做内循环工作。 + +关键词： + +```text +定时 +批量 +巡检 +统计 +预警 +知识维护 +规则质量复盘 +``` + +### 1.2 自建 Agent + +自建 Agent 定位为用户流程助手。 + +它直接面对员工、财务人员、审批人和管理员。 + +关键词： + +```text +用户触发 +会话式 +流程操作 +查询解释 +草稿生成 +审批辅助 +用户确认 +``` + +## 2. Hermes 职责 + +Hermes 负责： + +1. 每日风险巡检。 +2. 每日报销、报账、账款统计。 +3. 应收逾期预警。 +4. 应付付款风险预警。 +5. 规则命中质量复盘。 +6. MCP 健康检查。 +7. 知识库候选内容生成。 +8. 高风险工单生成。 +9. 任务运行报告生成。 + +Hermes 输出的内容包括： + +```text +risk_report +risk_work_items +daily_finance_snapshot +knowledge_candidates +rule_improvement_items +mcp_health_report +task_run_log +``` + +Hermes 不允许： + +1. 自动审批通过。 +2. 自动发起付款。 +3. 自动提交用户申请。 +4. 自动发布正式知识库。 +5. 自动上线规则。 +6. 直接修改核心财务状态。 + +## 3. 自建 Agent 职责 + +自建 Agent 负责： + +1. 查询报销单进度。 +2. 创建报销或付款草稿。 +3. 解释规则拦截原因。 +4. 生成审批意见。 +5. 检索制度知识。 +6. 查询应收应付数据。 +7. 帮用户对账。 +8. 引导用户补充缺失信息。 +9. 在用户确认后调用流程 API。 + +自建 Agent 输出的内容包括： + +```text +natural_language_answer +form_draft +approval_opinion_draft +clarification_question +query_result_summary +next_action_suggestion +``` + +自建 Agent 不允许： + +1. 未经用户确认提交关键动作。 +2. 跳过权限校验。 +3. 自动最终审批。 +4. 自动付款。 +5. 修改规则上线状态。 + +## 4. 权限边界 + +| 动作 | Hermes | 自建 Agent | +|---|---|---| +| 查询制度知识 | 可以 | 可以 | +| 查询业务数据 | 可以，按任务权限 | 可以，按用户权限 | +| 跑规则 | 可以 | 可以 | +| 调 MCP | 可以 | 可以 | +| 生成报告 | 可以 | 可以 | +| 生成草稿 | 不建议 | 可以 | +| 提交流程 | 不可以 | 用户确认后可以 | +| 审批通过 | 不可以 | 不可以直接做 | +| 发起付款 | 不可以 | 高权限确认后才可做草稿 | +| 发布知识 | 不可以 | 不可以 | +| 上线规则 | 不可以 | 不可以 | + +## 5. 共享能力 + +两套 Agent 共享： + +- 语义本体协议。 +- 规则中心。 +- MCP 服务。 +- 知识库。 +- 数据库查询服务。 +- 审计日志。 +- 权限系统。 + +不共享： + +- 运行队列。 +- 调度策略。 +- 用户会话状态。 +- 任务重试状态。 + +## 6. 示例 + +### 6.1 Hermes 场景 + +每日 02:00 自动运行： + +```text +每日风险巡检 + 读取昨日报销、报账、发票、账款数据 + 执行规则 + 调用发票验真 MCP + 调用账款流水 MCP + 生成风险报告 + 生成风险工单 +``` + +### 6.2 自建 Agent 场景 + +用户问： + +```text +帮我看一下这张差旅报销为什么没通过。 +``` + +处理： + +```text +解析语义 +查询报销单 +读取规则命中 +检索制度条款 +组织解释 +给出补件建议 +``` + diff --git a/document/development/agent/agent plan/04_orchestrator_and_runtime_flow.md b/document/development/agent/agent plan/04_orchestrator_and_runtime_flow.md new file mode 100644 index 0000000..693a583 --- /dev/null +++ b/document/development/agent/agent plan/04_orchestrator_and_runtime_flow.md @@ -0,0 +1,385 @@ +# Agent Orchestrator 与运行流程 + +## 1. Orchestrator 定位 + +Agent Orchestrator 是双 Agent 架构的调度中心。 + +它不负责生成最终答案，而是负责： + +- 接收用户请求或定时任务。 +- 调用语义解析。 +- 判断处理方。 +- 选择工具。 +- 检查权限。 +- 记录审计。 +- 管理失败重试。 +- 控制高风险动作确认。 + +## 2. 运行主流程 + +```text +输入 + 用户消息 / 页面按钮 / 定时任务 / 系统事件 + ↓ +上下文装配 + 页面对象 / 附件名称 / OCR 摘要 / VLM 摘要 / 用户角色 / conversation_id / draft_claim_id + ↓ +语义解析 + LLM 主解析 + 规则兜底，输出 ontology_json + ↓ +语义校验 + confidence / missing_slots / ambiguity / permission 初判 + ↓ +Orchestrator 决策 + 判断 agent = hermes | user_agent + 判断 tool = rule | mcp | db | knowledge | task + ↓ +权限检查 + 用户权限 / 任务权限 / 数据范围 + ↓ +业务写入 + 报销草稿创建 / 报销草稿更新 / 用户确认后提交 + ↓ +工具执行 + 规则中心 / MCP / 数据库 / 知识库 / 任务系统 + ↓ +Agent 汇总 + Hermes 报告 / User Agent 回答 + ↓ +审计记录 + 保存输入、语义、工具、结果、动作 +``` + +## 3. 路由规则 + +### 3.1 Hermes 路由 + +满足以下条件之一，进入 Hermes： + +```text +source = schedule +source = system_event +intent = monitor +intent = summarize and no active user session +next_step = generate_report and task_type is batch +scenario in daily_risk_scan / knowledge_accumulation / mcp_health_check +``` + +补充约束： + +- 这里的 Hermes 指系统后台真实 Hermes 进程或 Hermes CLI，不是前端概念上的 “Hermes 模式”。 +- Orchestrator 负责路由、权限、审计和 Trace，不负责替代 Hermes 自身执行。 +- 当前阶段允许保留本地 fallback，但必须预留真实 Hermes 进程调用入口。 + +### 3.2 User Agent 路由 + +满足以下条件之一，进入自建 Agent： + +```text +source = user_message +source = page_action +intent = query / explain / create / validate / reconcile +requires_user_context = true +next_step = ask_clarification +next_step = create_draft +``` + +### 3.3 工具路由 + +```text +next_step = query_database + 调用数据库查询服务 + +next_step = run_rule + 调用规则中心 + +next_step = call_mcp + 调用 MCP 服务 + +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 +``` + +这些状态应由审批流、财务支付流或受控后台同步更新。 + +### 3.7 结构化核对回路 + +当 `scenario = expense` 且当前仍存在缺槽位、附件待核对或票据需拆单时，不直接返回一段自由文本，而是返回结构化核对结果： + +```text +result.review_payload + intent_summary + body_message + slot_cards + risk_briefs + document_cards + claim_groups + confirmation_actions = 取消 / 修改 / 保存草稿或下一步 + edit_fields +``` + +前端正文区只展示简洁提示，右侧展示字段、风险、票据与分单明细。 + +### 3.8 会话续接与重识别 + +用户对话不是无状态调用。Orchestrator 需要携带以下会话字段继续当前报销流程： + +```text +conversation_id +draft_claim_id +conversation_history +review_action +review_form_values +``` + +其中： + +```text +review_action = edit_review + 表示用户基于结构化模板修改识别结果，需要重新进入语义识别 + +review_action = save_draft + 表示信息未补齐，但允许先保存报销草稿 + +review_action = next_step + 表示用户确认当前识别结果，可进入下一步流转 +``` + +## 4. 用户流程示例 + +用户输入： + +```text +上个月哪些客户应收逾期超过 30 天？ +``` + +流程： + +```text +Step 1: User Agent 接收消息 +Step 2: semantic_parser 输出 ontology_json +Step 3: Orchestrator 识别 domain = accounts_receivable +Step 4: next_step = query_database +Step 5: 权限检查用户是否可看应收数据 +Step 6: 查询应收账龄表 +Step 7: User Agent 汇总结果 +Step 8: 返回客户清单、金额、逾期天数、风险说明 +``` + +## 5. Hermes 任务示例 + +任务： + +```text +每日风险巡检 +``` + +流程： + +```text +Step 1: 任务调度器在 02:00 触发 +Step 2: Orchestrator 构造 ontology_json +Step 3: 路由给 Hermes +Step 4: Hermes 拉取昨日业务快照 +Step 5: 执行规则中心规则 +Step 6: 调用 MCP 验真、账款流水 +Step 7: 生成风险报告 +Step 8: 写入风险工单 +Step 9: 记录任务日志 +Step 10: 通知财务风控组 +``` + +### 5.1 Hermes 后台执行方式 + +推荐最小形态： + +```text +任务系统 / 手动触发 API + ↓ +Orchestrator 生成 run_id、任务上下文、权限信息 + ↓ +后端调用系统 Hermes CLI 或 Hermes 后台进程 + ↓ +Hermes 执行知识同步 / 风险巡检 / 规则草稿形成 + ↓ +结果回写 AgentRun / ToolCall / 审计日志 +``` + +约束： + +- Hermes 运行使用系统级配置，不在任务代码里再写一套模型配置。 +- Hermes 运行失败要记录 stderr 或等价错误摘要。 +- Hermes 输出的知识候选和规则草稿必须回写为结构化结果，不只保留终端文本。 + +## 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 运行都应该写入审计。 + +建议字段： + +```json +{ + "id": "", + "source": "user_message | schedule | system_event", + "agent": "hermes | user_agent", + "user_id": "", + "task_id": "", + "ontology_json": {}, + "tools_called": [], + "permission_scope": {}, + "result_summary": "", + "action_taken": "", + "requires_confirmation": false, + "created_at": "" +} +``` + +建议补充 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 用户交互失败 + +```text +数据库查询失败 + 返回“暂时无法查询”，记录错误 + +缺少关键字段 + 返回追问 + +权限不足 + 返回无权限说明 + +MCP 不可用 + 返回降级说明，必要时生成待处理项 +``` + +### 7.2 Hermes 任务失败 + +```text +任务失败 + 自动重试 3 次 + +部分 MCP 失败 + 标记 partial_success + +数据不完整 + 生成异常任务日志 + +连续失败 + 通知管理员 +``` diff --git a/document/development/agent/agent plan/05_development_roadmap.md b/document/development/agent/agent plan/05_development_roadmap.md new file mode 100644 index 0000000..3727b47 --- /dev/null +++ b/document/development/agent/agent plan/05_development_roadmap.md @@ -0,0 +1,458 @@ +# 分阶段开发计划 + +## Phase 0：准备阶段 + +目标：统一概念和边界，不写复杂功能。 + +### Step 0.1 明确术语 + +产出： + +- 规则：`.md` 审查规则文件。 +- 技能：可复用的 Agent 能力，如审批意见生成、风险解释。 +- MCP：外部服务连接。 +- 任务：定时或批量运行的后台作业。 +- Hermes：后台数字员工。 +- User Agent：用户流程助手。 +- Orchestrator：调度和路由层。 +- Ontology：语义本体协议。 + +### Step 0.2 冻结第一版语义字段 + +第一版只强制 8 个字段： + +```text +domain +scenario +intent +entities +time_range +constraints +risk_signals +next_step +``` + +### Step 0.3 建立设计文档 + +产出： + +- 本目录所有文档。 +- 后续数据库表设计草案。 +- API 合同草案。 + +## Phase 1：任务规则中心基础建设 + +目标：先把管理后台搭起来。 + +### Step 1.1 完成前端信息架构 + +页签： + +```text +规则 / 技能 / MCP / 任务 +``` + +规则详情： + +- Markdown 编辑器。 +- 审核人。 +- 审核状态。 +- 版本列表。 +- 版本切换确认。 + +技能详情： + +- 技能配置。 +- 输入上下文。 +- 输出契约。 +- 测试样例。 +- 依赖能力。 + +MCP 详情： + +- 服务地址。 +- 鉴权方式。 +- 权限范围。 +- 健康检查。 +- 调用记录。 + +任务详情： + +- Cron。 +- 运行窗口。 +- 输入范围。 +- 产出对象。 +- 最近运行。 + +### Step 1.2 建立后端基础模型 + +建议表： + +```text +agent_rules +agent_skills +agent_mcp_services +agent_tasks +agent_asset_versions +agent_asset_reviews +``` + +第一阶段可以先不做完整执行，只做 CRUD。 + +### Step 1.3 规则版本与审核 + +规则上线流程： + +```text +草稿 + ↓ +提交审核 + ↓ +审核通过 + ↓ +上线 +``` + +关键约束： + +- 没有审核人不能上线。 +- 没有审核通过不能上线。 +- 上线必须生成新版本。 +- 历史版本只读。 + +## Phase 2：OCR 与财务单据标准模型 + +目标：让发票、附件、报销单和账款流水先标准化。 + +### Step 2.1 附件上传与文件分类 + +识别： + +- 发票。 +- 行程单。 +- 合同。 +- 付款凭证。 +- 审批截图。 + +### Step 2.2 OCR MCP 接入 + +把附件转成结构化字段。 + +### Step 2.3 Invoice 标准模型 + +统一 OCR、MCP、用户填写和业务系统字段。 + +### Step 2.4 人工修正 + +允许财务人员修正 OCR 字段，并写入反馈池。 + +### Step 2.5 规则中心接入 OCR 结果 + +重复发票、附件完整性、金额不一致等规则开始使用标准模型。 + +## Phase 3：语义本体服务 + +目标：用户问题和任务配置都能转成 ontology_json。 + +### Step 3.1 建立 semantic_parser API + +接口： + +```text +POST /api/v1/semantic/parse +``` + +输入： + +```json +{ + "source": "user_message", + "text": "上个月哪些客户应收逾期超过 30 天？", + "context": {} +} +``` + +输出： + +```json +{ + "domain": "accounts_receivable", + "scenario": "receivable_aging", + "intent": "query", + "entities": [], + "time_range": {}, + "constraints": {}, + "risk_signals": [], + "next_step": "query_database" +} +``` + +### Step 3.2 建立模型优先解析器 + +要求： + +- 使用运行时模型配置，而不是写死单一 provider。 +- 输入包括文本、上下文、附件摘要和预抽取字段。 +- 输出必须是结构化 JSON，而不是自由文本。 +- 输出必须经过 Schema 校验。 +- 模型失败时必须回退到规则解析。 + +### Step 3.3 建立 ontology schema 表 + +建议表： + +```text +semantic_ontology_schemas +semantic_parse_logs +``` + +字段： + +```text +id +schema_version +schema_json +status +created_at +updated_at +``` + +### Step 3.4 建立字段级校验与澄清策略 + +至少支持： + +- 缺少费用类型时追问。 +- 缺少业务对象时追问。 +- 短句或模糊句时追问。 +- 叙述型报销输入默认走 create/generate，而不是 query。 +- 低置信度时禁止工具执行。 + +### Step 3.5 建立解析测试集 + +至少覆盖： + +- 报销规则解释。 +- 差旅报销创建。 +- 叙述型报销创建。 +- 发票验真。 +- 应收逾期查询。 +- 应付付款状态。 +- 每日风险巡检。 +- 知识库维护。 +- 模糊短句追问。 +- 附件输入解析。 + +## Phase 4：LLM Wiki 知识库 + +目标：让制度文档、FAQ、审批经验可被 Agent 检索和引用。 + +### Step 4.1 文档解析与分块 + +上传 PDF、Word、Excel 后抽取正文并 chunk。 + +### Step 4.2 元数据与向量索引 + +为知识块打 domain、scenario、tags、版本。 + +### Step 4.3 知识检索 API + +User Agent 可以基于语义本体查询知识。 + +### Step 4.4 知识候选审核 + +Hermes 生成 FAQ 或条款候选，人工审核后发布。 + +## Phase 5：Orchestrator 基础版 + +目标：基于 ontology_json 做确定性路由。 + +### Step 5.1 建立路由规则 + +输入： + +```text +source +domain +scenario +intent +next_step +``` + +输出： + +```text +agent = hermes | user_agent +tools = [] +permission_required = [] +``` + +### Step 5.2 建立工具网关 + +第一批工具： + +```text +rule_engine.run +knowledge.search +database.query +mcp.call +task.create +``` + +### Step 5.3 建立审计日志 + +所有请求都记录： + +- 原始输入。 +- 语义 JSON。 +- 路由结果。 +- 工具调用。 +- 输出摘要。 +- 错误信息。 + +## Phase 6：User Agent 第一版 + +目标：先做只读和解释，不做强写入。 + +### Step 6.1 支持制度问答 + +流程： + +```text +用户问题 + -> semantic_parse + -> search_knowledge + -> User Agent 生成回答 +``` + +### Step 6.2 支持规则解释 + +流程： + +```text +用户问为什么被拦截 + -> semantic_parse + -> run_rule + -> search_knowledge + -> User Agent 解释风险原因 +``` + +### Step 6.3 支持业务查询 + +先支持： + +- 报销单状态查询。 +- 应收账龄查询。 +- 应付付款状态查询。 + +### Step 6.4 支持草稿生成 + +只生成草稿，不直接提交。 + +```text +用户确认前不写核心状态 +``` + +## Phase 7：Hermes 第一版 + +目标：让后台数字员工开始跑任务。 + +### Step 7.1 每日风险巡检 + +输入： + +- 昨日单据。 +- 发票。 +- 附件。 +- 付款流水。 + +输出： + +- 风险报告。 +- 风险工单。 +- 风险统计。 + +### Step 7.2 每日财务统计 + +统计： + +- 报销金额。 +- 报账金额。 +- 应收账龄。 +- 应付账龄。 +- 付款状态。 +- 账款异常。 + +### Step 7.3 知识候选积累 + +来源： + +- 审批意见。 +- 驳回原因。 +- 高频问答。 +- 规则误报反馈。 + +输出： + +- FAQ 候选。 +- 规则优化建议。 +- 制度变更摘要。 + +## Phase 8：MCP 接入 + +目标：让 Agent 能安全调用外部系统。 + +优先接入： + +1. 发票验真 MCP。 +2. 附件 OCR MCP。 +3. 银行流水 MCP。 +4. 差旅平台 MCP。 +5. ERP/付款状态 MCP。 + +每个 MCP 必须有： + +- 服务地址。 +- 鉴权方式。 +- 权限范围。 +- 超时设置。 +- 降级策略。 +- 健康检查。 +- 调用日志。 + +## Phase 9：规则形成与反馈闭环 + +目标：让系统持续变聪明，但不失控。 + +闭环： + +```text +Hermes 发现问题 + -> 生成规则优化建议 + -> 管理员审核 + -> 更新规则 + -> User Agent 使用新规则解释 + -> 反馈继续进入 Hermes +``` + +关键限制： + +- Hermes 只生成候选。 +- 管理员审核后才能发布。 +- 所有规则变更有版本。 +- 所有上线动作有审核人。 + +### Step 9.1 规则候选池 + +Hermes 从制度、风险案例、反馈中生成规则候选。 + +### Step 9.2 规则测试样例 + +每条规则上线前必须有测试样例。 + +### Step 9.3 反馈池 + +收集 OCR 修正、规则误报、Agent 回答反馈。 + +### Step 9.4 质量看板 + +统计误报率、修正率、回答满意度、MCP 失败率。 diff --git a/document/development/agent/agent plan/06_data_contracts_and_governance.md b/document/development/agent/agent plan/06_data_contracts_and_governance.md new file mode 100644 index 0000000..d3234de --- /dev/null +++ b/document/development/agent/agent plan/06_data_contracts_and_governance.md @@ -0,0 +1,445 @@ +# 数据契约与治理要求 + +## 1. 推荐数据表 + +### 1.1 语义本体 + +```text +semantic_ontology_schemas +``` + +字段： + +```text +id +schema_version +schema_json +status +created_by +created_at +updated_at +``` + +```text +semantic_parse_logs +``` + +字段： + +```text +id +source +user_id +raw_text +ontology_json +confidence +parse_strategy +created_at +``` + +### 1.2 Agent 资产 + +```text +agent_rules +agent_skills +agent_mcp_services +agent_tasks +``` + +通用字段： + +```text +id +code +name +description +status +owner +reviewer +config_json +created_at +updated_at +``` + +### 1.3 版本与审核 + +```text +agent_asset_versions +``` + +字段： + +```text +id +asset_type +asset_id +version +content +change_note +created_by +created_at +``` + +```text +agent_asset_reviews +``` + +字段： + +```text +id +asset_type +asset_id +version +reviewer +review_status +review_note +reviewed_at +``` + +### 1.4 运行日志 + +```text +agent_runs +``` + +字段： + +```text +id +agent +source +task_id +user_id +ontology_json +status +started_at +finished_at +result_summary +error_message +``` + +```text +agent_tool_calls +``` + +字段： + +```text +id +run_id +tool_type +tool_name +request_json +response_json +status +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 语义解析 + +```text +POST /api/v1/semantic/parse +``` + +请求： + +```json +{ + "source": "user_message", + "text": "这张发票为什么被拦截？", + "context": { + "user_id": "emp_001", + "current_page": "reimbursement_detail" + } +} +``` + +响应： + +```json +{ + "domain": "reimbursement", + "scenario": "invoice_validation", + "intent": "explain", + "entities": [], + "time_range": {}, + "constraints": {}, + "risk_signals": ["unknown"], + "parse_strategy": "llm_primary", + "next_step": "run_rule" +} +``` + +### 2.2 Orchestrator 执行 + +```text +POST /api/v1/agent/orchestrate +``` + +请求： + +```json +{ + "source": "user_message", + "ontology": {}, + "context": {} +} +``` + +响应： + +```json +{ + "agent": "user_agent", + "tools_called": [], + "answer": "", + "requires_confirmation": false, + "audit_id": "" +} +``` + +### 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 +``` + +请求： + +```json +{ + "task_code": "daily_risk_scan", + "ontology": {}, + "dry_run": false, + "context_json": { + "folder": "报销制度", + "changed_only": true, + "force": false + } +} +``` + +响应： + +```json +{ + "run_id": "", + "status": "accepted" +} +``` + +补充： + +- Hermes 任务应优先调用系统后台 Hermes CLI 或等价 Hermes 进程。 +- `changed_only=true` 时，只处理知识库中发生变化的文档。 +- 文档变化判断至少包含 `original_name`、`stored_name`、`sha256`、`version_number`、`updated_at`。 +- 若文档无变化，应返回 `unchanged_skipped`，而不是重新形成 LLM Wiki。 + +## 3. 安全原则 + +### 3.1 最小权限 + +Agent 调工具时不能使用超级权限。 + +权限来源： + +- 用户权限 +- 任务权限 +- 服务账号权限 + +### 3.2 高风险动作确认 + +以下动作必须确认： + +- 提交报销 +- 发起付款 +- 生成正式审批意见 +- 发布规则 +- 发布知识库 +- 创建外部通知 + +### 3.3 审计不可省略 + +必须记录： + +- 谁触发 +- 输入是什么 +- 解析结果是什么 +- 调了哪些工具 +- 输出是什么 +- 是否确认 + +### 3.4 文件存储治理 + +必须遵守： + +- 原始文件二进制不落业务主表，不存入大字段 blob。 +- 所有文件必须有 `storage_provider`、`storage_key`、`sha256`、`file_size_bytes`、`mime_type`。 +- 原件不可覆盖，只能新增版本。 +- 删除默认是解除业务关联或逻辑删除，物理删除必须走审计流程。 +- 对象存储访问必须使用签名 URL 或后端代理，不直接暴露固定公网地址。 + +### 3.5 敏感数据治理 + +对于发票、行程单、合同、付款凭证中的敏感信息： + +- 应支持脱敏衍生件 +- 应记录查看与下载行为 +- 应区分申请人、审批人、财务、管理员可见范围 +- 应支持争议单据 `legal_hold` 保留策略 + +### 3.6 AI 证据治理 + +Agent 和 OCR 相关能力必须遵守： + +- 未经 OCR/VLM 实际解析，不得假设附件内容已知。 +- Agent 输出若引用发票金额、号码、日期，必须能追溯到 `invoice_structured_records` 或人工修正记录。 +- 风险解释若引用“重复报销”“金额不一致”等判断，必须能追溯到 `risk_events.evidence_json`。 + +## 4. 数据质量要求 + +### 4.1 关键唯一性 + +- `expense_claims.claim_no` 唯一 +- `document_assets.sha256` 可重复但必须可检索 +- `document_asset_versions(document_id, version_no)` 唯一 +- `invoice_structured_records.duplicate_fingerprint` 必须可索引 + +### 4.2 时间与状态字段 + +- 所有业务主表必须有 `created_at`、`updated_at` +- 文件上传、OCR、验真、风控、处置必须有独立时间戳 +- 状态字段应使用受控枚举，不允许前端自由拼写 + +### 4.3 可追溯性 + +任一笔报销单、发票或风险结论，至少应能追到： + +- 原始输入文本 +- 原始附件 +- 结构化结果 +- 规则或模型判断 +- 人工修正动作 + +## 5. 实施优先级 + +第一优先级： + +- `expense_claims` +- `expense_claim_items` +- `document_assets` +- `document_asset_versions` +- `expense_item_documents` + +第二优先级： + +- `document_ocr_results` +- `invoice_structured_records` +- `invoice_verification_records` +- `document_derivatives` + +第三优先级： + +- `risk_events` +- `risk_actions` +- `document_access_logs` + +实施原则： + +- 先确保“能收、能存、能找回原件” +- 再确保“能识别、能验真、能回填” +- 最后做“能解释、能审计、能批量巡检” diff --git a/document/development/agent/agent plan/07_capability_registry.md b/document/development/agent/agent plan/07_capability_registry.md new file mode 100644 index 0000000..2923f59 --- /dev/null +++ b/document/development/agent/agent plan/07_capability_registry.md @@ -0,0 +1,198 @@ +# Capability Registry 能力注册中心 + +## 1. 为什么需要能力注册中心 + +双 Agent 架构里会出现很多能力： + +- 规则文件。 +- 技能。 +- MCP 服务。 +- 数据库查询。 +- 知识库检索。 +- 定时任务。 +- 报告生成。 + +如果 Orchestrator 直接在代码里硬编码这些能力，会导致： + +- 能力越来越多后难维护。 +- 无法统一权限。 +- 无法统一版本。 +- 无法统一输入输出格式。 +- Hermes 和 User Agent 复用困难。 + +因此建议建立 Capability Registry。 + +它的定位是： + +```text +所有可被 Agent 调用的能力目录 +``` + +## 2. 能力类型 + +建议第一版支持： + +```text +rule +skill +mcp +task +database_query +knowledge_search +report_generator +notification +``` + +含义： + +- `rule`：审查规则，通常是 `.md` 文件或规则配置。 +- `skill`：智能能力，如审批意见生成、风险解释。 +- `mcp`：外部服务连接。 +- `task`：定时或批量任务。 +- `database_query`：受控数据库查询能力。 +- `knowledge_search`：知识库检索能力。 +- `report_generator`：报告生成能力。 +- `notification`：通知能力。 + +## 3. 能力注册结构 + +建议结构： + +```json +{ + "id": "cap_rule_duplicate_invoice", + "code": "duplicate_invoice_rule", + "name": "重复报销识别规则", + "capability_type": "rule", + "domain": "reimbursement", + "scenarios": ["invoice_validation", "reimbursement_audit"], + "intents": ["validate", "explain", "monitor"], + "input_schema": {}, + "output_schema": {}, + "permission_required": ["reimbursement:read", "risk:write"], + "risk_level": "high", + "owner": "财务风控组", + "version": "v1.9", + "status": "active", + "requires_confirmation": false, + "created_at": "", + "updated_at": "" +} +``` + +## 4. 与语义本体的匹配关系 + +Orchestrator 根据 ontology_json 匹配能力。 + +示例： + +```json +{ + "domain": "reimbursement", + "scenario": "invoice_validation", + "intent": "explain", + "risk_signals": ["duplicate_invoice"], + "next_step": "run_rule" +} +``` + +可以匹配： + +```text +重复报销识别规则 +发票验真 MCP +风险解释技能 +制度知识库检索 +``` + +## 5. 能力匹配优先级 + +建议顺序： + +```text +Step 1: next_step 决定能力大类 +Step 2: domain 限定业务域 +Step 3: scenario 限定场景 +Step 4: risk_signals 匹配具体规则 +Step 5: intent 匹配技能 +Step 6: permission_required 校验权限 +Step 7: status 必须 active +Step 8: version 使用当前上线版本 +``` + +## 6. 数据表建议 + +```text +agent_capabilities +``` + +字段： + +```text +id +code +name +capability_type +domain +scenario_json +intent_json +input_schema_json +output_schema_json +permission_json +risk_level +owner +current_version +status +requires_confirmation +config_json +created_at +updated_at +``` + +## 7. 开发步骤 + +### Step 1: 先注册静态能力 + +先把现有规则、技能、MCP、任务写入 Registry。 + +不需要一开始做复杂 UI。 + +### Step 2: Orchestrator 改为查 Registry + +从： + +```text +if next_step = run_rule then call duplicate_invoice_rule +``` + +改为： + +```text +query capabilities where type = rule and scenario = invoice_validation +``` + +### Step 3: 加权限过滤 + +只返回当前用户或任务有权限调用的能力。 + +### Step 4: 加版本选择 + +默认使用 active 版本。 + +历史版本只用于回放和调试。 + +### Step 5: 加健康状态 + +MCP、任务、数据库查询能力应有健康状态。 + +不可用时 Orchestrator 走降级策略。 + +## 8. 治理要求 + +- 所有能力必须有 owner。 +- 高风险能力必须有 reviewer。 +- 所有能力必须有输入输出 schema。 +- 所有能力必须有状态。 +- 下线能力不能被 Orchestrator 调用。 +- 能力版本变更必须写入审计。 + diff --git a/document/development/agent/agent plan/08_permission_confirmation.md b/document/development/agent/agent plan/08_permission_confirmation.md new file mode 100644 index 0000000..0414b02 --- /dev/null +++ b/document/development/agent/agent plan/08_permission_confirmation.md @@ -0,0 +1,214 @@ +# 权限与确认引擎 + +## 1. 目标 + +Agent 不能只靠提示词判断能不能执行动作。 + +财务系统需要独立的权限与确认引擎： + +```text +Permission Engine +Confirmation Engine +``` + +它们负责： + +- 判断用户是否能看某类数据。 +- 判断任务是否能调用某个能力。 +- 判断动作是否需要确认。 +- 判断动作是否禁止自动执行。 + +## 2. 动作风险分级 + +建议按 L0-L5 分级。 + +### L0 只读查询 + +例子： + +- 查询制度。 +- 查询单据状态。 +- 查询规则说明。 +- 查询任务运行记录。 + +要求： + +- 需要权限。 +- 不需要确认。 + +### L1 生成建议 + +例子： + +- 生成审批意见建议。 +- 生成风险解释。 +- 生成规则优化建议。 + +要求： + +- 需要权限。 +- 不写业务状态。 +- 不需要确认，但要标记为建议。 + +### L2 生成草稿 + +例子： + +- 生成报销草稿。 +- 生成付款申请草稿。 +- 生成知识库候选。 + +要求： + +- 需要权限。 +- 写入草稿区。 +- 不进入正式流程。 + +### L3 用户确认后提交 + +例子： + +- 用户确认后提交报销。 +- 审批人确认后写入审批意见。 +- 用户确认后发起补件。 + +要求： + +- 必须二次确认。 +- 必须记录确认人。 +- 必须记录确认前后内容。 + +### L4 管理员确认后发布 + +例子： + +- 发布规则。 +- 发布知识库。 +- 启用 MCP。 +- 启用任务。 + +要求： + +- 必须管理员确认。 +- 必须有审核记录。 +- 必须有版本。 + +### L5 禁止自动执行 + +例子： + +- 自动最终审批。 +- 自动付款。 +- 自动绕过风控。 +- 自动修改核心财务状态。 + +要求： + +- Agent 永远不能直接执行。 + +## 3. 权限判断输入 + +```json +{ + "user_id": "emp_001", + "agent": "user_agent", + "source": "user_message", + "action": "create_reimbursement_draft", + "domain": "reimbursement", + "resource": { + "type": "reimbursement_request", + "id": "" + }, + "capability": "travel_reimbursement_create" +} +``` + +## 4. 权限判断输出 + +```json +{ + "allowed": true, + "risk_level": "L2", + "requires_confirmation": false, + "reason": "", + "permission_scope": { + "departments": ["current_user"], + "data_masking": false + } +} +``` + +## 5. 确认弹窗策略 + +需要确认的动作必须显示： + +- 动作名称。 +- 影响对象。 +- 关键字段。 +- 执行后果。 +- 是否可撤销。 +- 确认人。 + +示例： + +```json +{ + "title": "确认提交报销申请", + "action": "submit_reimbursement", + "summary": "将提交差旅报销单 TR-202605001，金额 ¥3,280。", + "risk_level": "L3", + "confirm_button": "确认提交" +} +``` + +## 6. Hermes 权限 + +Hermes 使用服务账号，不使用个人账号。 + +建议拆分权限： + +```text +hermes:risk_scan +hermes:finance_statistics +hermes:knowledge_candidate +hermes:mcp_health_check +``` + +Hermes 默认只允许： + +- 读脱敏快照。 +- 跑规则。 +- 调只读 MCP。 +- 写报告、候选、工单。 + +Hermes 不允许： + +- 写正式审批状态。 +- 写正式付款状态。 +- 发布规则。 +- 发布知识。 + +## 7. User Agent 权限 + +User Agent 继承当前用户权限。 + +例如： + +- 员工只能看自己的报销。 +- 部门负责人可以看本部门。 +- 财务可以看授权范围内数据。 +- 管理员可以管理规则、任务、MCP。 + +User Agent 不能扩大用户权限。 + +## 8. 开发步骤 + +```text +Step 1: 定义 action risk level +Step 2: 建立 Permission Engine 接口 +Step 3: 所有工具调用前接入权限判断 +Step 4: L3/L4 动作接入确认弹窗 +Step 5: 审计记录确认内容 +Step 6: 增加权限测试用例 +``` + diff --git a/document/development/agent/agent plan/09_observability_and_trace.md b/document/development/agent/agent plan/09_observability_and_trace.md new file mode 100644 index 0000000..b21fac3 --- /dev/null +++ b/document/development/agent/agent plan/09_observability_and_trace.md @@ -0,0 +1,186 @@ +# 可观测性与 Agent Run Trace + +## 1. 目标 + +Agent 系统必须可追踪、可回放、可解释。 + +财务系统中尤其需要回答： + +- 为什么 Agent 得出这个结论？ +- 用了哪个模型？ +- 用了哪个规则版本？ +- 调用了哪些 MCP？ +- 查了哪些数据？ +- 谁确认了动作？ +- 失败在哪里？ + +## 2. Agent Run Trace + +每次 Agent 运行都生成一个 run_id。 + +建议结构： + +```json +{ + "run_id": "", + "source": "user_message", + "agent": "user_agent", + "user_id": "emp_001", + "raw_input": "", + "ontology_json": {}, + "route_decision": {}, + "permission_result": {}, + "tool_calls": [], + "final_output": "", + "status": "success", + "started_at": "", + "finished_at": "" +} +``` + +## 3. 需要记录的版本 + +每次运行都要记录： + +```text +ontology_schema_version +semantic_parser_prompt_version +model_name +model_version +rule_version +skill_version +mcp_version +knowledge_snapshot_version +orchestrator_version +``` + +原因： + +用户可能问： + +```text +为什么昨天和今天的结论不一样？ +``` + +只有记录版本，才能解释。 + +## 4. Tool Call Trace + +每个工具调用都记录： + +```json +{ + "tool_call_id": "", + "run_id": "", + "tool_type": "mcp", + "tool_name": "invoice_verify", + "request_json": {}, + "response_json": {}, + "status": "success", + "duration_ms": 820, + "error_message": "" +} +``` + +敏感字段应脱敏。 + +## 5. 运行状态 + +建议枚举： + +```text +pending +running +success +partial_success +failed +cancelled +waiting_confirmation +``` + +## 6. Hermes 可观测性 + +Hermes 任务需要额外记录： + +```text +task_code +schedule_time +data_snapshot_id +records_scanned +rules_executed +mcp_calls +risk_items_generated +knowledge_candidates_generated +retry_count +``` + +示例： + +```json +{ + "task_code": "daily_risk_scan", + "records_scanned": 2146, + "rules_executed": 8, + "mcp_calls": 436, + "risk_items_generated": 19, + "status": "success" +} +``` + +## 7. User Agent 可观测性 + +User Agent 需要额外记录： + +```text +conversation_id +page_context +user_confirmation +draft_created +business_object_id +``` + +## 8. 前端审计视图 + +建议后续增加“Agent 运行记录”页面。 + +展示： + +- 运行时间。 +- Agent 类型。 +- 用户或任务。 +- 语义解析结果。 +- 调用工具。 +- 运行状态。 +- 耗时。 +- 错误。 + +详情页展示： + +- 原始输入。 +- 本体 JSON。 +- 路由决策。 +- 工具调用链。 +- 最终输出。 + +## 9. 告警 + +需要告警的情况： + +- Hermes 任务连续失败。 +- MCP 健康检查失败。 +- 语义解析低置信度比例过高。 +- 某规则误报率过高。 +- Agent 调用耗时异常。 +- 权限拒绝次数异常。 + +## 10. 开发步骤 + +```text +Step 1: 增加 agent_runs 表 +Step 2: 增加 agent_tool_calls 表 +Step 3: Orchestrator 每次执行创建 run_id +Step 4: 工具网关记录 tool call +Step 5: 前端增加运行记录页面 +Step 6: 增加异常告警规则 +``` + diff --git a/document/development/agent/agent plan/10_evaluation_and_testset.md b/document/development/agent/agent plan/10_evaluation_and_testset.md new file mode 100644 index 0000000..4be7c37 --- /dev/null +++ b/document/development/agent/agent plan/10_evaluation_and_testset.md @@ -0,0 +1,198 @@ +# 评测集与质量控制 + +## 1. 为什么需要评测集 + +语义解析、本体字段、Agent 路由、规则命中都不能只靠人工感觉。 + +每次修改 prompt、模型、规则或路由逻辑，都应该运行评测集。 + +目标： + +- 检查 domain 是否识别正确。 +- 检查 scenario 是否识别正确。 +- 检查 intent 是否识别正确。 +- 检查 next_step 是否正确。 +- 检查是否应该追问。 +- 检查是否错误调用高风险工具。 + +## 2. 第一版评测集规模 + +建议第一版至少 300 条。 + +```text +报销问题：80 条 +应收问题：60 条 +应付问题：60 条 +制度问答：40 条 +风险解释：30 条 +定时任务：20 条 +模糊问题：10 条 +叙述型报销：20 条 +附件输入：10 条 +``` + +## 3. 评测样例结构 + +```json +{ + "id": "eval_001", + "input": "上个月哪些客户应收逾期超过 30 天？", + "expected": { + "domain": "accounts_receivable", + "scenario": "receivable_aging", + "intent": "query", + "next_step": "query_database" + }, + "required_entities": ["customer"], + "notes": "应识别为应收账龄查询" +} +``` + +## 4. 评测指标 + +### 4.1 字段准确率 + +```text +domain_accuracy +scenario_accuracy +intent_accuracy +next_step_accuracy +field_level_f1 +clarification_accuracy +``` + +### 4.2 工具路由准确率 + +```text +tool_route_accuracy +permission_decision_accuracy +confirmation_decision_accuracy +narrative_misroute_rate +``` + +### 4.3 安全指标 + +```text +unsafe_action_rate +missing_confirmation_rate +permission_bypass_rate +low_confidence_unsafe_tool_rate +``` + +这些指标必须接近 0。 + +## 5. 低置信度处理 + +语义解析输出应包含： + +```json +{ + "confidence": 0.62, + "missing_slots": ["time_range"], + "ambiguity": ["应收逾期还是审批逾期"] +} +``` + +当置信度低于阈值： + +```text +confidence < 0.75 + 不执行工具 + 返回追问 +``` + +## 6. 模糊问题样例 + +用户问： + +```text +这个为什么还没处理？ +``` + +不能直接执行查询。 + +应该追问： + +```text +你是想查询报销单、应收款还是付款申请的处理状态？ +``` + +叙述型报销样例： + +```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 路由。 +- 规则中心匹配逻辑。 +- MCP 能力注册。 +- 模型版本。 + +流程： + +```text +Step 1: 加载评测集 +Step 2: 批量调用 semantic_parse +Step 3: 批量调用 route_decision +Step 4: 对比 expected +Step 5: 输出准确率报告 +Step 6: 阻止低于阈值的发布 +``` + +## 8. 发布阈值 + +建议第一版阈值： + +```text +domain_accuracy >= 95% +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. 评测数据管理 + +建议文件结构： + +```text +server/tests/fixtures/semantic_eval/ + reimbursement.jsonl + accounts_receivable.jsonl + accounts_payable.jsonl + risk_explain.jsonl + scheduled_tasks.jsonl +``` + +每行一个样例。 + +## 10. 开发步骤 + +```text +Step 1: 建立 JSONL 评测集格式 +Step 2: 写 50 条人工样例 +Step 3: 接入 semantic_parse 批测脚本 +Step 4: 输出 markdown/html 评测报告 +Step 5: 扩展到 300 条 +Step 6: 接入 CI 或手动发布检查 +``` diff --git a/document/development/agent/agent plan/11_ocr_invoice_architecture.md b/document/development/agent/agent plan/11_ocr_invoice_architecture.md new file mode 100644 index 0000000..f21fc3b --- /dev/null +++ b/document/development/agent/agent plan/11_ocr_invoice_architecture.md @@ -0,0 +1,376 @@ +# OCR 票据识别架构 + +## 1. 定位 + +OCR 票据识别不是一个简单的图片转文字功能。 + +它在 X-Financial 中承担四件事： + +1. 把用户上传的附件变成结构化票据信息。 +2. 为规则中心提供可判断的字段。 +3. 为 User Agent 和 Hermes 提供可解释的证据。 +4. 为后续审计、复核、争议处理保留可回溯原件。 + +因此 OCR 应作为独立能力纳入 Capability Registry。 + +```text +capability_type = mcp | document_processor +capability_code = invoice_ocr +``` + +## 2. 总体链路 + +```text +附件上传 + ↓ +文件落盘 / 对象存储 + ↓ +文件分类 + ↓ +OCR 识别 + ↓ +字段结构化 + ↓ +票据类型归一化 + ↓ +发票验真 MCP + ↓ +与报销明细匹配 + ↓ +规则中心检查 + ↓ +人工修正 + ↓ +修正结果沉淀 +``` + +关键原则： + +- 文件先持久化，再做 OCR，不允许只在内存里跑完就丢。 +- 原件不可覆盖，只能新增版本。 +- Agent 不得假设图片内容已知；只有 OCR/VLM 实际解析后才能引用附件内容。 + +## 3. 阶段拆分 + +### Phase A：附件接入与文件分类 + +目标：先识别上传的是什么。 + +输入： + +- 图片 +- PDF +- Excel +- Word +- 压缩包 + +输出： + +```json +{ + "document_type": "invoice", + "mime_type": "image/png", + "page_count": 1, + "confidence": 0.91 +} +``` + +分类结果： + +```text +invoice +itinerary +contract +payment_receipt +approval_screenshot +other +``` + +### Phase B：OCR 字段提取 + +目标：从图片或 PDF 中提取票据字段。 + +结构： + +```json +{ + "invoice_code": "", + "invoice_number": "", + "seller_name": "", + "seller_tax_no": "", + "buyer_name": "", + "buyer_tax_no": "", + "issue_date": "", + "total_amount": 0, + "tax_amount": 0, + "currency": "CNY", + "ocr_confidence": 0.88 +} +``` + +### Phase C：字段归一化 + +目标：不同 OCR 服务返回不同字段名，必须统一。 + +示例： + +```text +发票号码 / invoiceNo / invoice_number + -> invoice_number +``` + +金额统一： + +```json +{ + "raw": "￥1,280.00", + "value": 1280.00, + "currency": "CNY" +} +``` + +### Phase D：验真与状态检查 + +调用发票验真 MCP。 + +输出： + +```json +{ + "verify_status": "verified", + "voided": false, + "red_reversed": false, + "verified_at": "" +} +``` + +### Phase E：与报销明细匹配 + +对比： + +- 发票金额 vs 报销金额 +- 开票日期 vs 费用日期 +- 销售方 vs 商户 +- 发票类型 vs 费用类型 + +输出： + +```json +{ + "match_status": "matched", + "mismatch_fields": [], + "match_confidence": 0.94 +} +``` + +### Phase F：人工修正与回流 + +OCR 结果必须允许人工修正。 + +修正内容进入反馈池： + +```json +{ + "field": "invoice_number", + "before": "12345B", + "after": "123456", + "corrected_by": "finance_user", + "corrected_at": "" +} +``` + +## 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 +expense_item_documents +document_access_logs +``` + +各表职责： + +- `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 输出供规则使用： + +```text +重复报销识别规则 +作废发票检查规则 +发票抬头异常规则 +附件完整性规则 +金额不一致规则 +OCR 低置信度补录规则 +``` + +规则读取原则： + +- 读标准化字段，不直接依赖某个 OCR 服务的原始字段名。 +- 需要追证时，从 `document_assets` 和 `document_asset_versions` 找原件。 +- 需要解释时，从 `document_ocr_results` 和 `invoice_verification_records` 给证据。 + +## 7. 与 Agent 关系 + +User Agent 使用 OCR： + +- 解释发票为什么被拦截 +- 帮用户补充发票信息 +- 提醒上传清晰附件 +- 根据 OCR 结果自动回填报销草稿 + +Hermes 使用 OCR： + +- 夜间批量验真 +- 扫描重复票据 +- 统计发票异常趋势 +- 回刷历史低置信度票据 + +## 8. 安全与审计要求 + +### 8.1 访问控制 + +- 原始票据预览、下载应按用户角色控制。 +- 财务、审批人、申请人看到的文件范围可以不同。 +- 对象存储不要暴露永久公网链接，统一走签名 URL 或后端代理下载。 + +### 8.2 敏感信息处理 + +- 身份证、银行卡、手机号等敏感字段如被识别，应支持脱敏预览件。 +- 对外展示尽量用衍生件，不直接暴露原件。 + +### 8.3 审计要求 + +必须记录： + +- 谁上传了原件 +- 谁触发了 OCR +- 谁查看或下载了原件 +- 谁修正了 OCR 结果 +- 谁发起了验真 +- 哪次风险判断引用了哪些票据 + +## 9. 开发阶段建议 + +```text +Step 1: 附件上传与 document_assets / document_asset_versions 落库 +Step 2: 本地文件目录方案打通 +Step 3: 接入 OCR MCP 或 OCR 服务 +Step 4: 结构化字段归一化 +Step 5: 发票验真 MCP +Step 6: 与 expense_claim_items 匹配 +Step 7: 风险规则中心接入 +Step 8: 人工修正界面 +Step 9: Hermes 夜间批量 OCR 与验真巡检 +``` + +当前阶段优先级： + +- 先把“文件原件可存、可找、可追溯”做实。 +- 再把 OCR 和验真接进来。 +- 最后再做大规模自动巡检和脱敏导出。 diff --git a/document/development/agent/agent plan/12_llm_wiki_knowledge_architecture.md b/document/development/agent/agent plan/12_llm_wiki_knowledge_architecture.md new file mode 100644 index 0000000..9e10ca1 --- /dev/null +++ b/document/development/agent/agent plan/12_llm_wiki_knowledge_architecture.md @@ -0,0 +1,221 @@ +# LLM Wiki 知识库架构 + +## 1. 定位 + +LLM Wiki 不是简单的文件库。 + +它是给 Agent 使用的知识底座，负责把制度、FAQ、审批经验、规则说明转成可检索、可引用、可版本化的知识。 + +## 2. 总体链路 + +```text +文档上传 + ↓ +格式解析 + ↓ +正文抽取 + ↓ +分块 Chunking + ↓ +元数据标注 + ↓ +向量索引 + ↓ +条款抽取 + ↓ +知识候选 + ↓ +人工审核 + ↓ +发布 Wiki + ↓ +Agent 检索引用 +``` + +## 2.1 目录约束 + +LLM Wiki 解析产物不能与原始制度文件混放。 + +推荐目录： + +```text +/app/server/storage/knowledge// 原始知识文件 +/app/server/storage/knowledge/.llm_wiki/ 解析产物根目录 +/app/server/storage/knowledge/.llm_wiki/documents// + document.json + text.md + chunks.json + clauses.json + knowledge_candidates.json + rule_candidates.json +/app/server/storage/knowledge/.llm_wiki/index.json +/app/server/storage/knowledge/.llm_wiki/sync_runs.json +``` + +约束： + +- 原始文件目录只存原件，不存解析碎片。 +- LLM Wiki 目录只存结构化产物，不反向覆盖原件。 +- 所有解析产物必须能按 `document_id` 回溯到原始文件。 + +## 3. 知识类型 + +```text +policy_document +faq +rule_explanation +approval_case +risk_case +operation_manual +system_notice +``` + +## 4. 知识块结构 + +```json +{ + "chunk_id": "", + "document_id": "", + "title": "", + "content": "", + "domain": "reimbursement", + "scenario": "travel_reimbursement", + "tags": ["差旅", "住宿标准"], + "effective_date": "", + "version": "v1.0", + "source_page": 4, + "embedding_id": "", + "status": "published" +} +``` + +## 5. 条款抽取 + +Hermes 可以从制度文档中抽取条款候选。 + +示例： + +```json +{ + "clause_type": "amount_limit", + "domain": "reimbursement", + "scenario": "travel_reimbursement", + "condition": { + "city_tier": "一线城市", + "employee_grade": "P5" + }, + "limit": { + "amount": 800, + "currency": "CNY", + "period": "night" + }, + "source": "差旅制度 2026 第 4 页" +} +``` + +该结果不直接变成规则，先进入规则候选池。 + +## 5.1 增量形成策略 + +LLM Wiki 不应按天无脑全量重建。 + +每个文档都应维护签名： + +```json +{ + "document_id": "", + "original_name": "", + "stored_name": "", + "sha256": "", + "version_number": 1, + "updated_at": "" +} +``` + +只有在以下任一条件发生时，才重建对应文档的 LLM Wiki： + +- `original_name` 变更。 +- `stored_name` 变更。 +- `sha256` 变更。 +- `version_number` 变更。 +- `updated_at` 变更，视为人工修改。 + +如果以上均未变化： + +- 本次文档状态应记为 `unchanged_skipped`。 +- 不重新抽取正文。 +- 不重新分块。 +- 不重新生成知识候选或规则候选。 + +## 6. Wiki 发布流程 + +```text +草稿知识 + ↓ +Hermes 生成候选 + ↓ +知识管理员审核 + ↓ +发布 + ↓ +Agent 可检索 +``` + +## 7. 与 User Agent 的关系 + +User Agent 用 Wiki： + +- 回答制度问题。 +- 给风险解释提供条款依据。 +- 给审批意见生成引用。 +- 帮用户理解流程。 + +## 8. 与 Hermes 的关系 + +Hermes 用 Wiki： + +- 每日知识候选生成。 +- 发现制度与规则不一致。 +- 生成规则优化建议。 +- 生成 FAQ 候选。 + +补充要求： + +- Hermes 对制度文档的处理默认是增量同步，不是每日全量重建。 +- Hermes 应先检查知识库签名，再决定是否需要重建某个文档的 Wiki。 +- Hermes 形成的是候选与草稿，不是正式发布内容。 + +## 9. 数据模型建议 + +```text +knowledge_documents +knowledge_chunks +knowledge_embeddings +knowledge_candidates +knowledge_reviews +knowledge_versions +``` + +当前最小落地允许先以文件索引实现： + +```text +.llm_wiki/index.json +.llm_wiki/sync_runs.json +.llm_wiki/documents//document.json +``` + +后续再平滑迁移到数据库或向量库。 + +## 10. 开发阶段建议 + +```text +Step 1: 文档上传和文件管理 +Step 2: 文本抽取和分块 +Step 3: 元数据标注 +Step 4: 向量索引 +Step 5: 知识检索 API +Step 6: User Agent 问答引用 +Step 7: Hermes 知识候选生成 +Step 8: 人工审核发布 +Step 9: 条款抽取和规则候选 +``` diff --git a/document/development/agent/agent plan/13_rule_formation_lifecycle.md b/document/development/agent/agent plan/13_rule_formation_lifecycle.md new file mode 100644 index 0000000..414aad8 --- /dev/null +++ b/document/development/agent/agent plan/13_rule_formation_lifecycle.md @@ -0,0 +1,194 @@ +# 规则形成生命周期 + +## 1. 定位 + +规则不是凭空写出来的。 + +它应来自： + +- 制度文档。 +- 历史审批。 +- 风险案例。 +- OCR 识别结果。 +- MCP 验真结果。 +- 用户反馈。 +- Hermes 分析。 + +## 2. 总体闭环 + +```text +制度文档 / 历史审批 / 风险案例 / 用户反馈 + ↓ +Hermes 分析 + ↓ +规则候选 + ↓ +人工审核 + ↓ +规则 .md + ↓ +测试样例 + ↓ +版本发布 + ↓ +规则执行 + ↓ +命中反馈 + ↓ +规则优化 +``` + +## 3. 规则候选结构 + +```json +{ + "candidate_id": "", + "source_type": "policy_document", + "domain": "reimbursement", + "scenario": "invoice_validation", + "risk_signal": "duplicate_invoice", + "suggested_rule_name": "重复报销识别规则", + "rule_markdown_draft": "", + "evidence": [], + "confidence": 0.86, + "created_by": "hermes" +} +``` + +补充约束： + +- `rule_markdown_draft` 不能是任意自由文本，必须符合固定模板。 +- 规则候选应同时携带机器可读 JSON 草稿，例如 `runtime_rule`。 +- JSON 草稿只能从受控模板族中选择，不允许 Hermes 自创字段结构后直接进入规则中心。 + +## 4. 规则 Markdown 推荐结构 + +```markdown +# 规则名称 + +## 目标 + +## 适用范围 + +## 输入字段 + +## 判断规则 + +## 输出 + +## 测试样例 + +## 管理员备注 +``` + +推荐再补一段模板元信息： + +```markdown +## 模板信息 + +- 模板键：`travel_standard_v1` +- 来源文档：公司支出管理办法（2024） +- Hermes 置信度：0.86 +- 审核人：张三 +``` + +## 4.1 规则 JSON 推荐结构 + +规则中心不应只有 Markdown。 + +应同时提供可执行 JSON 编辑区，至少支持： + +```json +{ + "kind": "policy_rule_draft", + "version": 1, + "template_key": "travel_standard_v1", + "rule_name": "差旅住宿标准草稿规则", + "scenario": "travel_reimbursement", + "review_required": true, + "conditions": {}, + "actions": {}, + "source_document_name": "公司支出管理办法（2024）" +} +``` + +治理要求： + +- Markdown 负责给人看。 +- JSON 负责给运行时和规则引擎看。 +- 两者必须成对维护，不能只改其中一份。 +- JSON 变更也必须走版本和审核。 + +## 4.2 模板族约束 + +Hermes 只能从白名单模板中选，不允许自由生成任意规则结构。 + +第一版建议模板： + +```text +travel_standard_v1 +expense_amount_limit_v1 +attachment_requirement_v1 +general_policy_v1 +``` + +如果制度条款不适合自动规则化： + +- 允许只生成 `knowledge_candidate` +- 或只生成 `general_policy_v1` 草稿并要求人工补齐 +- 不能为了“有结果”而编造可执行规则 + +## 5. 审核要求 + +规则上线必须满足： + +- 有审核人。 +- 有版本。 +- 有测试样例。 +- 有来源依据。 +- 有回滚方案。 + +补充： + +- Hermes 生成规则默认只能是 `draft`。 +- Hermes 不能直接覆盖当前 `active` 线上规则。 +- Hermes 如发现制度更新，应优先生成新的候选或草稿版本，仍需人工审核后再上线。 + +## 6. 规则执行反馈 + +每次规则运行应记录： + +```text +rule_id +rule_version +input_snapshot +hit_result +risk_level +operator_feedback +false_positive +false_negative +``` + +## 7. 规则优化来源 + +```text +误报反馈 +漏报反馈 +审批人修改意见 +Hermes 每日复盘 +制度文档更新 +MCP 新字段可用 +``` + +## 8. 开发阶段建议 + +```text +Step 1: 规则 .md 编辑和版本 +Step 2: 规则审核上线 +Step 3: 规则运行日志 +Step 4: 人工反馈误报/漏报 +Step 5: Hermes 生成规则候选 +Step 6: 规则候选审核 +Step 7: 规则测试样例管理 +Step 8: 规则质量看板 +``` diff --git a/document/development/agent/agent plan/14_financial_document_canonical_model.md b/document/development/agent/agent plan/14_financial_document_canonical_model.md new file mode 100644 index 0000000..4a4ede2 --- /dev/null +++ b/document/development/agent/agent plan/14_financial_document_canonical_model.md @@ -0,0 +1,646 @@ +# 财务单据标准模型 + +## 1. 为什么需要标准模型 + +OCR、MCP、用户填写、业务数据库可能都描述同一张发票，但字段名和格式不同。 + +如果没有标准模型： + +- 规则无法复用。 +- Agent 难以解释。 +- Hermes 难以批量统计。 +- MCP 返回结果难以合并。 + +这里要区分三层： + +- 标准模型：定义 Agent、规则、MCP、OCR、数据库之间统一交换的数据结构。 +- 业务数据库表：定义 MVP 阶段真正落库存储、查询和统计所依赖的业务表。 +- 文件存储对象：定义原始票据、预览件、OCR 中间产物、验真结果附件的存储位置与版本规则。 + +如果只有标准模型，没有业务表和文件资产表，User Agent 无法真正发起报销；如果只有数据库表，没有统一标准模型，语义解析、规则解释、OCR 回填和 Hermes 巡检会越来越混乱。 + +## 2. 标准对象 + +第一版建议定义这些对象： + +```text +Invoice +Receipt +ExpenseClaim +PaymentRequest +AccountsReceivableRecord +AccountsPayableRecord +BankTransaction +Contract +Customer +Vendor +Employee +CostCenter +DocumentAsset +RiskEvent +``` + +说明： + +- 对外语义层建议统一使用 `ExpenseClaim` 概念，不再把“报销申请”和“报销单据”拆成两个平行主概念。 +- 现有代码中仍有 `reimbursement_requests` 表，MVP 阶段不建议再继续扩张该表，而应以 `expense_claims` 作为报销主表。 +- `reimbursement_requests` 可保留用于兼容旧页面或审批联动，但新能力默认挂到 `expense_claims`。 + +## 3. Invoice 标准模型 + +```json +{ + "invoice_id": "", + "invoice_code": "", + "invoice_number": "", + "invoice_type": "", + "seller_name": "", + "seller_tax_no": "", + "buyer_name": "", + "buyer_tax_no": "", + "issue_date": "", + "total_amount": 0, + "tax_amount": 0, + "currency": "CNY", + "verify_status": "", + "ocr_confidence": 0, + "source_document_id": "" +} +``` + +## 4. ExpenseClaim 标准模型 + +```json +{ + "claim_id": "", + "claim_no": "", + "employee_id": "", + "employee_name": "", + "department_id": "", + "department_name": "", + "cost_center_code": "", + "project_code": "", + "expense_type": "", + "reason": "", + "location": "", + "amount": 0, + "currency": "CNY", + "status": "", + "occurred_at": "", + "submitted_at": "", + "approval_stage": "", + "items": [], + "attachments": [], + "risk_flags": [] +} +``` + +说明： + +- `reason`、`location`、`occurred_at` 是报销语义判断、规则解释、风险识别的最小必要字段。 +- 一张报销单通常包含多条费用明细，标准模型中允许聚合，数据库层必须拆到明细表。 +- `attachments` 指向文件资产，不直接嵌入二进制文件。 + +## 5. AccountsReceivableRecord 标准模型 + +```json +{ + "ar_id": "", + "document_no": "", + "customer_id": "", + "customer_name": "", + "contract_no": "", + "invoice_no": "", + "amount_receivable": 0, + "amount_received": 0, + "amount_outstanding": 0, + "currency": "CNY", + "due_date": "", + "posting_date": "", + "status": "", + "aging_days": 0, + "risk_flags": [] +} +``` + +## 6. AccountsPayableRecord 标准模型 + +```json +{ + "ap_id": "", + "document_no": "", + "vendor_id": "", + "vendor_name": "", + "invoice_no": "", + "amount_payable": 0, + "amount_paid": 0, + "amount_outstanding": 0, + "currency": "CNY", + "due_date": "", + "posting_date": "", + "status": "", + "aging_days": 0, + "risk_flags": [] +} +``` + +## 7. BankTransaction 标准模型 + +```json +{ + "transaction_id": "", + "bank_account": "", + "transaction_date": "", + "amount": 0, + "currency": "CNY", + "counterparty_name": "", + "summary": "", + "matched_object_type": "", + "matched_object_id": "", + "match_status": "" +} +``` + +## 8. MVP 真实业务表设计 + +标准模型不等于数据库表，但 MVP 至少要有以下真实表，才能支撑 Day 5 用户报销对话、Day 6 风险巡检和后续审批/验真闭环。 + +### 8.1 设计原则 + +- 报销主数据统一落在 `expense_claims`，不再新建第三套“报销主表”。 +- 原始票据文件二进制不进数据库，只存元数据和关联信息。 +- OCR 结果、发票结构化结果、验真结果、风险事件要分表存，避免把所有字段塞进一个 JSON。 +- 所有表都要能被 Agent 解释，也要能被 Hermes 批量扫表。 +- `reimbursement_requests` 进入兼容态，不作为新能力主干表继续扩展。 + +### 8.2 报销主表 `expense_claims` + +用途： + +- 作为用户报销会话最终落单的主业务对象。 +- 承接语义层补槽后的草稿、提交、审批、打回、归档状态。 + +建议字段： + +```text +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.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 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 +``` + +说明： + +- 现有 `invoice_id` 单字段不足以覆盖多张附件挂同一明细的情况，后续应改为关联表。 + +### 8.4 票据资产主表 `document_assets` + +用途： + +- 作为所有原始附件的主索引表。 +- 支持报销单、报销明细、审批、验真、风控证据等多对象挂载。 + +建议字段： + +```text +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` + +用途： + +- 保留原始文件和后续重新上传版本。 +- 允许“修正”但不允许覆盖原始证据。 + +建议字段： + +```text +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` + +用途： + +- 存储缩略图、预览 PDF、逐页图片、脱敏件等衍生产物。 + +建议字段： + +```text +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 +``` + +### 8.7 OCR 结果表 `document_ocr_results` + +用途： + +- 保留每次 OCR 原始结果、模型版本、置信度和错误信息。 +- 支持后续重跑 OCR 与人工纠错对比。 + +建议字段： + +```text +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 +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 +``` + +### 8.9 发票验真记录表 `invoice_verification_records` + +用途： + +- 保留每次调用税局/第三方验真服务的结果，支持追溯。 + +建议字段： + +```text +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/agent plan/15_feedback_learning_loop.md b/document/development/agent/agent plan/15_feedback_learning_loop.md new file mode 100644 index 0000000..471aa43 --- /dev/null +++ b/document/development/agent/agent plan/15_feedback_learning_loop.md @@ -0,0 +1,119 @@ +# 反馈闭环与持续学习 + +## 1. 定位 + +Agent 系统必须能从人工反馈中持续变好。 + +反馈来源： + +- OCR 人工修正。 +- 规则误报/漏报。 +- 审批人修改意见。 +- 用户对回答的反馈。 +- Hermes 风险复盘。 +- MCP 调用失败和降级。 + +## 2. 反馈类型 + +```text +ocr_correction +rule_false_positive +rule_false_negative +agent_answer_feedback +approval_opinion_edit +knowledge_answer_feedback +mcp_failure_feedback +task_result_feedback +``` + +## 3. 反馈结构 + +```json +{ + "feedback_id": "", + "feedback_type": "rule_false_positive", + "source_object_type": "rule_run", + "source_object_id": "", + "before": {}, + "after": {}, + "comment": "", + "created_by": "", + "created_at": "" +} +``` + +## 4. 反馈流向 + +```text +人工反馈 + ↓ +反馈池 + ↓ +Hermes 聚类分析 + ↓ +候选改进项 + ↓ +人工审核 + ↓ +更新规则 / 知识 / OCR 映射 / Prompt +``` + +## 5. 反馈不直接自动生效 + +反馈只能生成候选，不直接修改线上规则。 + +必须人工审核： + +- 规则修改。 +- 知识发布。 +- Prompt 修改。 +- OCR 字段映射调整。 + +## 6. Hermes 每日反馈复盘 + +Hermes 每日任务： + +```text +读取昨日反馈 +聚类相似问题 +统计误报高发规则 +统计低评分回答 +生成优化候选 +``` + +输出： + +```text +rule_improvement_candidates +knowledge_update_candidates +ocr_mapping_candidates +prompt_improvement_notes +``` + +## 7. 质量指标 + +建议监控： + +```text +ocr_correction_rate +rule_false_positive_rate +rule_false_negative_rate +agent_answer_like_rate +agent_answer_rewrite_rate +knowledge_no_hit_rate +mcp_failure_rate +``` + +## 8. 开发阶段建议 + +```text +Step 1: 增加反馈按钮和反馈表 +Step 2: OCR 修正写入反馈池 +Step 3: 规则误报/漏报反馈 +Step 4: Agent 回答反馈 +Step 5: Hermes 每日反馈聚类 +Step 6: 生成优化候选 +Step 7: 人工审核发布 +Step 8: 建立质量看板 +``` + diff --git a/document/development/agent/agent week plan/00_README.md b/document/development/agent/agent week plan/00_README.md new file mode 100644 index 0000000..8099ff4 --- /dev/null +++ b/document/development/agent/agent week plan/00_README.md @@ -0,0 +1,77 @@ +# Agent Week Plan 一周开发路线图 + +本目录现在同时承接： + +- 一周路线图 +- 每天 daily 文档 +- 每天的详细执行清单 + +原独立执行细则目录已合并进各 Day 文档，不再单独维护。 + +## 文档分工 + +| 目录 | 职责 | 读者 | +| --- | --- | --- | +| `agent week plan` | 一周节奏、每天目标、验收门槛、详细执行清单、阻塞记录、日终交接 | 产品、架构、Codex、开发、验收 | +| `agent plan` | 架构设计、协议、流程、治理、标准模型、能力边界 | 架构、开发、评审 | + +## 使用方式 + +1. 先读 [MASTER_TODO.md](./MASTER_TODO.md)，确认 7 天节奏和当前状态。 +2. 打开当天 daily 文档。 +3. 在同一份 daily 文档里按顺序阅读： + 今天的大开发点 -> 当前完成情况 -> 当天验收门槛 -> 详细执行清单 -> 阻塞记录 -> 日终交接。 +4. 如需设计依据，再跳到 `agent plan` 对应架构文档。 +5. 完成一个最小项后，再把该项改成完成态，而不是代码写完就直接算过。 + +## 完成标记规则 + +未完成： + +```md +- [ ] 建立 AgentAsset 数据模型 +``` + +完成后： + +```md +- [x] ~~建立 AgentAsset 数据模型~~ +``` + +执行要求： + +- [ ] 每次只处理一个最小 TODO。 +- [ ] 完成后先自测，再改成 `[x]`。 +- [ ] 改成 `[x]` 时，同时用 `~~` 画线。 +- [ ] 不能因为代码写完就标完成，必须满足该 TODO 的验收证据。 +- [ ] 遇到阻塞时，在当天文档的“阻塞记录”下新增说明。 +- [ ] 每天收尾时更新当天文档的“日终交接”。 + +## 一周总体目标 + +- Day 1：先把资产、版本、审核、运行日志、审计日志等基础地基建好。 +- Day 2：把任务规则中心和后端资产体系打通。 +- Day 3：建立语义本体 MVP，让用户问题能变成稳定结构。 +- Day 4：建立 Orchestrator，让请求能被统一路由、审计、降级。 +- Day 5：建立 User Agent MVP，处理用户查询、解释和草稿生成。 +- Day 6：建立 Hermes MVP，处理定时巡检、统计、知识和规则草稿。 +- Day 7：做加固、测试、演示、验收和下一阶段交接。 + +## 一周暂不完成 + +- 完整 OCR 生产识别引擎。 +- 完整发票验真 MCP 深度接入。 +- 完整 LLM Wiki 向量检索。 +- 全量财务域数据打通。 +- 规则自动上线。 +- 完整 CI/CD 质量门禁。 + +## 生产底线 + +- 所有写操作必须有审计日志。 +- 所有 Agent 执行必须生成 `run_id`。 +- 所有规则必须有版本。 +- 未审核规则不能上线。 +- 高风险动作只能生成草稿或建议，不能自动提交。 +- 外部能力失败必须有降级结果。 +- 语义解析结果必须可回放。 diff --git a/document/development/agent/agent week plan/MASTER_TODO.md b/document/development/agent/agent week plan/MASTER_TODO.md new file mode 100644 index 0000000..cbdc81b --- /dev/null +++ b/document/development/agent/agent week plan/MASTER_TODO.md @@ -0,0 +1,73 @@ +# Agent Week Plan 总控 + +本文件是本周总览和执行索引。 + +每个 Day 文档现在同时包含： + +- 路线图 +- 当前完成情况 +- 验收门槛 +- 详细执行清单 + +不再跳转独立执行细则目录。 + +## 快速浏览 + +- HTML 总览：[agent_week_plan_html/index.html](<../agent_week_plan_html/index.html>) +- Day 1 HTML：[agent_week_plan_html/day-1.html](<../agent_week_plan_html/day-1.html>) + +## 执行方式 + +1. 先看本文件，确认今天做哪一天、当前状态和依赖顺序。 +2. 再打开当天 daily 文档，直接在同一份文档里推进开发。 +3. 完成一个最小 TODO 后，再改成 `[x] ~~...~~`。 +4. 每天结束时回填阻塞记录、验收结果和日终交接。 + +## 一周节奏 + +| Day | 状态 | 主题 | 主要交付 | Markdown | HTML | +| --- | --- | --- | --- | --- | --- | +| Day 1 | 已完成（2026-05-11） | 基础模型与工程骨架 | 资产、版本、审核、运行日志、审计日志、基础 API、最小财务数据源 | [Day 1](./day_1_foundation_models.md) | [HTML](<../agent_week_plan_html/day-1.html>) | +| Day 2 | 已完成，待补浏览器走查记录 | 任务规则中心联调 | 规则/技能/MCP/任务列表与详情、Markdown、版本、审核 | [Day 2](./day_2_rule_center_integration.md) | [HTML](<../agent_week_plan_html/day-2.html>) | +| Day 3 | 已完成主体功能，待补评测样本扩充 | 语义本体 MVP | 8 字段语义解析、日志、评测入口、OCR 摘要与最小会话上下文带入 | [Day 3](./day_3_semantic_ontology_mvp.md) | [HTML](<../agent_week_plan_html/day-3.html>) | +| Day 4 | 已完成主干与会话串联，待接通提交/附件持久化链路 | Orchestrator 运行时 | 统一入口、路由、权限、工具调用、报销单写入路由、会话 Trace | [Day 4](./day_4_orchestrator_runtime.md) | [HTML](<../agent_week_plan_html/day-4.html>) | +| Day 5 | 已完成问答主链路、草稿创建/补全与会话上下文，待接通提交状态流转 | User Agent MVP | 用户问答、报销单草稿创建/补全/提交、财务查询、规则解释、附件/OCR 带入 | [Day 5](./day_5_user_agent_mvp.md) | [HTML](<../agent_week_plan_html/day-5.html>) | +| Day 6 | 未开始 | Hermes MVP | 定时任务、风险巡检、日报、知识候选、规则草稿 | [Day 6](./day_6_hermes_mvp.md) | [HTML](<../agent_week_plan_html/day-6.html>) | +| Day 7 | 未开始 | 加固、演示和验收 | 回归、测试、演示脚本、交付说明 | [Day 7](./day_7_hardening_demo_acceptance.md) | [HTML](<../agent_week_plan_html/day-7.html>) | + +## 当前完成情况 + +- Day 1 已完成，后端基础模型、审计和最小财务数据源已可供后续能力复用。 +- Day 2 已完成主要前后端联调，当前仅剩浏览器人工走查记录待补。 +- Day 3 主体已完成，`/api/v1/ontology/parse`、8 字段返回、缺槽位追问、权限判断和前端调试入口均已落地；OCR 摘要、附件上下文和最小会话历史已进入语义层，前端浏览器时间上下文也已接入相对时间换算，当前主要剩叙述型报销、附件/OCR 带入样本和模糊追问样本继续扩充。 +- Day 4 主干已完成，Orchestrator 已具备统一入口、User Agent / Hermes 路由、权限阻断、ToolCall 记录、Trace、降级和 `conversation_id` 会话串联；`expense_claims` 草稿建单/改单与 ToolCall / Audit 已接通，但提交、附件持久化和更细的 ToolCall Trace 仍未接通。 +- Day 5 问答主链路已完成，个人工作台和报销对话框已能把文本、附件名称、OCR 摘要、页面上下文和会话 ID 带入 Orchestrator，并返回回答、规则引用、风险说明、结构化草稿和识别核对面板；核对 UI 已调整为“右侧只看识别结果、主对话负责待补与风险、底部负责动作”，但附件 / OCR 结果落库及 `draft -> submitted` 仍未完成。 + +## Day 1 - Day 5 未完成补齐清单 + +- Day 1：当前周计划范围内无新增遗留项，基础资产、日志、审计和最小财务表已完成；文件资产、OCR 结果表和风险事件表作为 Day 5 真落库前置底座，设计已完成但代码未落地。 +- Day 2：仍缺一轮浏览器人工走查记录，需补充规则中心真实页面联调截图或缺陷清单。 +- Day 3：仍需补充叙述型报销长句样本、附件/OCR 摘要带入样本、模糊短句追问样本，并把这些样本纳入自动评测。 +- Day 4：仍需接通 `submit_expense_claim` 真服务，补齐附件挂接服务注册、ToolCall 更细粒度记录和前端 Trace 展示。 +- Day 5：仍需把附件和 OCR 识别结果真正落到 `document_assets`、`document_asset_versions`、`expense_item_documents`、`document_ocr_results`，并完成 `draft -> submitted` 状态流转、前端确认动作回写和提交流程确认。 + +## 关键依赖顺序 + +1. Day 1 必须先完成，因为后面所有能力都依赖资产、版本、审核、日志。 +2. Day 2 必须在 Day 3 前完成，因为语义和 Agent 需要读取规则、技能、MCP、任务资产。 +3. Day 3 必须在 Day 4 前完成，因为 Orchestrator 依赖语义本体做路由。 +4. Day 4 必须在 Day 5 / Day 6 前完成，因为 User Agent 和 Hermes 都应该由 Orchestrator 调用。 +5. Day 5 和 Day 6 可以部分并行，但都必须遵守权限、审计、Trace。 +6. Day 7 不新增大功能，只做加固、验收和交接。 + +## 最终验收 + +- 任务规则中心能看到规则、技能、MCP、任务。 +- 规则详情能编辑 Markdown、查看最近 5 个版本、切换版本。 +- 未审核规则不能上线。 +- 用户问题能解析出语义本体 8 字段。 +- Orchestrator 能路由到 User Agent 和 Hermes。 +- User Agent 能完成查询、解释、报销单草稿创建、字段补全和提交前确认。 +- Hermes 能执行一次风险巡检或日报任务。 +- AgentRun、ToolCall、AuditLog 都能追溯。 +- 有演示脚本和下一阶段交接文档。 diff --git a/document/development/agent/agent week plan/day_1_foundation_models.md b/document/development/agent/agent week plan/day_1_foundation_models.md new file mode 100644 index 0000000..6d932de --- /dev/null +++ b/document/development/agent/agent week plan/day_1_foundation_models.md @@ -0,0 +1,221 @@ +# Day 1：基础模型与工程骨架 + +## 当前状态 + +- [x] ~~Day 1 已完成（2026-05-11）。~~ +- [x] ~~后端基础模型、API 骨架、种子数据、审计能力和 Day 2 联调入口均已落地。~~ + +## 今天的大开发点 + +Day 1 只做地基，不做复杂 Agent 智能。 + +核心是把后面 6 天都会用到的基础对象建出来：资产、版本、审核、运行日志、工具调用日志、语义解析日志、审计日志，以及最小财务业务数据来源。 + +## 为什么第一天做这个 + +如果没有稳定的数据模型，后面的任务规则中心、语义本体、Orchestrator、User Agent、Hermes 都会各自临时造结构，后期会很难合并。 + +## 今天主要交付 + +- [x] ~~统一资产模型：规则、技能、MCP、任务。~~ +- [x] ~~版本模型：规则 Markdown 和其他资产配置快照。~~ +- [x] ~~审核模型：未审核不能上线。~~ +- [x] ~~Agent 运行日志：所有 Agent 执行都有 `run_id`。~~ +- [x] ~~工具调用日志：MCP、数据库、LLM、OCR、规则引擎调用都可追踪。~~ +- [x] ~~语义解析日志：后续语义本体结果可回放。~~ +- [x] ~~审计日志：所有写操作可追责。~~ +- [x] ~~最小财务业务数据来源：报销、应收、应付。~~ + +## 实际落地结果 + +- [x] ~~新增 `AgentAsset`、`AgentAssetVersion`、`AgentAssetReview`、`AgentRun`、`AgentToolCall`、`SemanticParseLog`、`AuditLog`、`ExpenseClaim`、`ExpenseClaimItem`、`AccountsReceivableRecord`、`AccountsPayableRecord`。~~ +- [x] ~~新增 `/api/v1/agent-assets`、`/api/v1/agent-runs`、`/api/v1/audit-logs` 相关接口。~~ +- [x] ~~种子数据已覆盖 3 条规则、2 条技能、2 条 MCP、3 条任务，以及报销 / 应收 / 应付示例数据。~~ +- [x] ~~旧开发库启动时会自动补齐新增资产和版本，不需要手动清库。~~ + +相关架构文档： + +- [整体架构](<../agent plan/01_overall_architecture.md>) +- [语义本体](<../agent plan/02_semantic_ontology.md>) +- [数据契约与治理](<../agent plan/06_data_contracts_and_governance.md>) +- [能力注册](<../agent plan/07_capability_registry.md>) +- [权限与确认](<../agent plan/08_permission_confirmation.md>) +- [观测与 Trace](<../agent plan/09_observability_and_trace.md>) +- [财务单据标准模型](<../agent plan/14_financial_document_canonical_model.md>) + +## 当天验收门槛 + +- [x] ~~数据库或等价存储能创建基础对象。~~ +- [x] ~~API 服务能启动。~~ +- [x] ~~资产列表能返回规则、技能、MCP、任务。~~ +- [x] ~~规则资产能关联 Markdown 当前版本。~~ +- [x] ~~未审核规则不能上线。~~ +- [x] ~~AgentRun 能保存一条运行记录。~~ +- [x] ~~AuditLog 能保存一条写操作记录。~~ + +## 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` +- `GET /api/v1/audit-logs` + +## 今天不做 + +- 不做完整 Agent 对话。 +- 不做完整 Hermes 调度。 +- 不做真实 OCR。 +- 不做复杂规则推理。 + +## 详细执行清单 + +以下内容为合并后的详细执行清单。 + +## 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/agent week plan/day_2_rule_center_integration.md b/document/development/agent/agent week plan/day_2_rule_center_integration.md new file mode 100644 index 0000000..5ba8c66 --- /dev/null +++ b/document/development/agent/agent week plan/day_2_rule_center_integration.md @@ -0,0 +1,296 @@ +# Day 2：任务规则中心联调 + +## 今天的大开发点 + +把任务规则中心从静态页面改成可和后端资产体系联动的生产形态。 + +重点是规则、技能、MCP、任务四类资产的列表和详情，以及规则 Markdown、版本、审核、上线约束。 + +## 为什么第二天做这个 + +任务规则中心是业务人员管理 Agent 能力的入口。后续语义本体、Orchestrator、User Agent、Hermes 都要读取这里注册的规则、技能、MCP 和任务。 + +## 今天主要交付 + +- 规则、技能、MCP、任务四个页签对接资产 API。 +- 列表支持搜索、筛选、状态展示。 +- 规则详情展示 Markdown 内容。 +- 管理员可编辑规则 Markdown。 +- 规则版本展示最近 5 个版本。 +- 版本切换需要弹窗确认。 +- 审核者信息放在标题区域。 +- 右侧只保留版本信息。 +- 未审核规则上线时被后端拦截。 + +## 当前完成情况 + +- [x] ~~四个页签已切到真实资产 API。~~ +- [x] ~~规则 Markdown、版本切换、审核、上线动作已联调。~~ +- [x] ~~前端构建已通过。~~ +- [ ] 浏览器手动走查记录待补。 + +相关架构文档： + +- [能力注册](<../agent plan/07_capability_registry.md>) +- [规则形成生命周期](<../agent plan/13_rule_formation_lifecycle.md>) +- [数据契约与治理](<../agent plan/06_data_contracts_and_governance.md>) + +## 当天验收门槛 + +- 四个页签可切换并有真实 API 或 Mock API 数据。 +- 规则详情可编辑 Markdown。 +- Markdown 保存后刷新不丢失。 +- 版本卡片可切换版本。 +- 未审核规则不能上线。 +- 前端构建通过。 + +## 今天不做 + +- 不做规则自动生成。 +- 不做完整 MCP 真实调用。 +- 不做复杂权限矩阵。 +- 不重做 UI 风格，只在现有风格上微调。 + +## 详细执行清单 + +以下内容为合并后的详细执行清单。 + +## 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/agent week plan/day_3_semantic_ontology_mvp.md b/document/development/agent/agent week plan/day_3_semantic_ontology_mvp.md new file mode 100644 index 0000000..bb48609 --- /dev/null +++ b/document/development/agent/agent week plan/day_3_semantic_ontology_mvp.md @@ -0,0 +1,304 @@ +# Day 3：语义本体 MVP + +## 今天的大开发点 + +建立模型优先的语义解析层，把自然语言问题转换成统一的 8 个核心字段。 + +这一天的目标不是继续堆关键词，而是先把真实模型接入语义层，让报销、应收、应付、知识和风险相关问题进入稳定结构，再由规则做兜底和校验。 + +## 为什么第三天做这个 + +Orchestrator 不能直接根据原始文本做可靠路由。它需要先拿到结构化语义，再决定调用 User Agent、Hermes、规则、MCP 或知识库。 + +## 今天主要交付 + +- 语义本体 8 字段结构。 +- 场景识别：报销、应收、应付、知识、未知。 +- 意图识别：查询、解释、对比、风险检查、草稿、操作。 +- 业务对象提取：员工、客户、供应商、部门、项目、单据、金额。 +- 时间范围解析。 +- 指标和约束解析。 +- 风险信号和权限级别判断。 +- LLM 结构化解析 Prompt。 +- Schema 校验与 JSON 清洗。 +- 规则回退解析。 +- 低置信度追问和缺槽位追问。 +- 语义解析 API。 +- 解析日志和最小评测集。 + +## 当前完成情况 + +- [x] ~~`/api/v1/ontology/parse` 已上线，8 字段语义结构、缺槽位、歧义、权限和澄清问题均可返回。~~ +- [x] ~~语义层已切到“模型优先 + 规则回退”，并把结果写入 `AgentRun` / `SemanticParseLog`。~~ +- [x] ~~附件名称、附件数量、OCR 摘要和 OCR 文档摘要已能作为上下文带入语义层。~~ +- [x] ~~最小会话历史、上一轮场景/意图和 `draft_claim_id` 已能作为上下文带入语义层，用于识别“改成 800”“继续补充”这类追问。~~ +- [x] ~~叙述型报销语义已补强：`客户 + 吃饭/请客/宴请/招待` 优先归类为业务招待费，不再误打到应收查询。~~ +- [x] ~~相对时间已支持标准化展示：前端会透传浏览器本地时间上下文，`今天 / 昨天 / 本月 / 4 月` 会换算成绝对日期；展示层默认优先显示绝对日期，原始表达仅作为辅助信息。~~ +- [x] ~~前端调试入口与核心评测测试已完成并通过。~~ +- [ ] 叙述型报销样本、附件/OCR 带入样本和模糊短句追问样本仍需继续扩充。 + +相关架构文档： + +- [语义本体](<../agent plan/02_semantic_ontology.md>) +- [财务单据标准模型](<../agent plan/14_financial_document_canonical_model.md>) +- [数据契约与治理](<../agent plan/06_data_contracts_and_governance.md>) + +## 当天验收门槛 + +- 输入自然语言问题能返回 8 个字段。 +- 模型解析失败时能自动回退到规则解析。 +- 低置信度问题能返回澄清问题。 +- 越权动作不会被标记为可直接执行。 +- 解析结果能写入日志。 +- 至少覆盖报销、应收、应付三个场景。 +- 叙述型报销输入不会被错误路由到应收或应付。 + +## 今天不做 + +- 不做复杂多轮对话记忆。 +- 不做完整 Agent 自主规划。 +- 不做自动执行业务流程。 + +## 详细执行清单 + +以下内容为合并后的详细执行清单。 + +## 0. 开始前检查 + +- [x] ~~确认 Day 1 的 `SemanticParseLog` 可用。~~ +- [x] ~~确认 Day 1 的 `AgentRun` 可用。~~ +- [x] ~~确认 Day 2 的资产 API 可用。~~ +- [x] ~~找到后端服务层目录。~~ +- [x] ~~找到现有 LLM 调用或 Mock 调用方式。~~ +- [x] ~~确认当前是否允许真实调用 LLM。~~ +- [x] ~~确认当前运行时模型槽位可用于语义解析。~~ +- [x] ~~如果真实模型不可用，已准备规则解析回退路径。~~ + +## 1. 定义 8 个核心字段 + +- [x] ~~定义字段 `scenario`，表示业务场景。~~ +- [x] ~~定义字段 `intent`，表示用户意图。~~ +- [x] ~~定义字段 `entities`，表示业务对象。~~ +- [x] ~~定义字段 `time_range`，表示时间范围。~~ +- [x] ~~定义字段 `metrics`，表示指标或金额口径。~~ +- [x] ~~定义字段 `constraints`，表示过滤条件。~~ +- [x] ~~定义字段 `risk_flags`，表示风险信号。~~ +- [x] ~~定义字段 `permission`，表示动作权限。~~ +- [x] ~~为每个字段写清楚类型。~~ +- [x] ~~为每个字段写清楚是否必填。~~ +- [x] ~~为每个字段写清楚默认值。~~ +- [x] ~~为每个字段写清楚示例。~~ + +验收证据： + +- [x] ~~8 个字段在 Schema、服务层、日志中名字一致。~~ + +## 2. 设计字段枚举 + +- [x] ~~`scenario` 支持 `expense`。~~ +- [x] ~~`scenario` 支持 `accounts_receivable`。~~ +- [x] ~~`scenario` 支持 `accounts_payable`。~~ +- [x] ~~`scenario` 支持 `knowledge`。~~ +- [x] ~~`scenario` 支持 `unknown`。~~ +- [x] ~~`intent` 支持 `query`。~~ +- [x] ~~`intent` 支持 `explain`。~~ +- [x] ~~`intent` 支持 `compare`。~~ +- [x] ~~`intent` 支持 `risk_check`。~~ +- [x] ~~`intent` 支持 `draft`。~~ +- [x] ~~`intent` 支持 `operate`。~~ +- [x] ~~`permission.level` 支持 `read`。~~ +- [x] ~~`permission.level` 支持 `draft_write`。~~ +- [x] ~~`permission.level` 支持 `approval_required`。~~ +- [x] ~~`permission.level` 支持 `forbidden`。~~ + +验收证据： + +- [x] ~~未识别的问题不会抛异常，返回 `unknown`。~~ + +## 3. 建立 Schema + +- [x] ~~定义 `OntologyParseRequest`。~~ +- [x] ~~`OntologyParseRequest` 包含 `query`。~~ +- [x] ~~`OntologyParseRequest` 包含 `user_id`。~~ +- [x] ~~`OntologyParseRequest` 包含 `context_json`。~~ +- [x] ~~定义 `OntologyParseResult`。~~ +- [x] ~~`OntologyParseResult` 包含 8 个核心字段。~~ +- [x] ~~`OntologyParseResult` 包含 `confidence`。~~ +- [x] ~~`OntologyParseResult` 包含 `clarification_required`。~~ +- [x] ~~`OntologyParseResult` 包含 `clarification_question`。~~ +- [x] ~~`OntologyParseResult` 包含 `run_id`。~~ +- [x] ~~定义字段级错误结构。~~ + +验收证据： + +- [x] ~~OpenAPI 中可以看到语义解析请求和响应。~~ + +## 4. 实现解析服务 + +- [x] ~~新增 `SemanticOntologyService` 或同等服务。~~ +- [x] ~~实现 `parse(query, user_context)` 主函数。~~ +- [x] ~~增加上下文装配层，输入文本、页面上下文、附件摘要和预抽取字段。~~ +- [x] ~~实现模型优先的结构化语义解析。~~ +- [x] ~~约束模型只输出 JSON。~~ +- [x] ~~对模型输出做清洗、提取和 Schema 校验。~~ +- [x] ~~模型失败时自动回退到规则解析。~~ +- [x] ~~在结果中记录本次使用了 `llm_primary` 还是 `rule_fallback`。~~ +- [x] ~~报销关键词映射到 `expense`。~~ +- [x] ~~应收、回款、客户欠款映射到 `accounts_receivable`。~~ +- [x] ~~应付、供应商、付款映射到 `accounts_payable`。~~ +- [x] ~~风险、异常、重复、超标映射到 `risk_check`。~~ +- [x] ~~为什么、依据、规则映射到 `explain`。~~ +- [x] ~~统计、汇总、多少映射到 `query`。~~ +- [x] ~~生成、创建、发起映射到 `draft` 或 `operate`。~~ +- [x] ~~无法识别时返回低置信度和澄清问题。~~ +- [x] ~~叙述型报销输入优先识别为创建/草稿，而不是查询。~~ + +验收证据： + +- [x] ~~“查一下本周报销超标风险”能识别为 expense + risk_check。~~ +- [x] ~~“客户 A 这个月还有多少应收”能识别为 accounts_receivable + query。~~ +- [x] ~~“供应商 B 明天要付多少钱”能识别为 accounts_payable + query。~~ +- [x] ~~“我今天去客户现场，招待了客户，花销了1000元”不会错误识别为应收查询。~~ +- [x] ~~“昨天请客户吃饭花了 200 元”会优先识别为报销草稿语义，并把“昨天”换算为用户本地日期下的绝对日期。~~ + +## 5. 解析业务对象 + +- [x] ~~从问题中提取员工姓名。~~ +- [x] ~~从问题中提取部门。~~ +- [x] ~~从问题中提取客户。~~ +- [x] ~~从问题中提取供应商。~~ +- [x] ~~从问题中提取项目。~~ +- [x] ~~从问题中提取单据号。~~ +- [x] ~~从问题中提取金额。~~ +- [x] ~~从问题中提取费用类型。~~ +- [x] ~~无法提取时返回空数组，不返回 null。~~ + +验收证据： + +- [x] ~~“张三 4 月差旅报销”能提取员工、月份、费用类型。~~ + +## 6. 解析时间范围 + +- [x] ~~支持今天。~~ +- [x] ~~支持昨天。~~ +- [x] ~~支持本周。~~ +- [x] ~~支持上周。~~ +- [x] ~~支持本月。~~ +- [x] ~~支持上月。~~ +- [x] ~~支持本季度。~~ +- [x] ~~支持今年。~~ +- [x] ~~支持明确日期。~~ +- [x] ~~支持日期区间。~~ +- [x] ~~解析结果包含 `start_date` 和 `end_date`。~~ +- [x] ~~日期使用 ISO 格式。~~ + +验收证据： + +- [x] ~~“本周”能解析为当前周起止日期。~~ +- [x] ~~“2026 年 4 月”能解析为 `2026-04-01` 到 `2026-04-30`。~~ + +## 7. 解析指标与约束 + +- [x] ~~识别金额指标。~~ +- [x] ~~识别数量指标。~~ +- [x] ~~识别超标指标。~~ +- [x] ~~识别逾期指标。~~ +- [x] ~~识别重复报销指标。~~ +- [x] ~~识别部门过滤条件。~~ +- [x] ~~识别状态过滤条件。~~ +- [x] ~~识别金额阈值过滤条件。~~ +- [x] ~~识别排序要求。~~ +- [x] ~~识别 Top N 要求。~~ + +验收证据： + +- [x] ~~“列出金额最高的 10 笔报销”能识别排序和 Top 10。~~ + +## 8. 解析风险与权限 + +- [x] ~~重复报销映射到 `duplicate_expense`。~~ +- [x] ~~发票异常映射到 `invoice_anomaly`。~~ +- [x] ~~金额超标映射到 `amount_over_limit`。~~ +- [x] ~~逾期应收映射到 `ar_overdue`。~~ +- [x] ~~逾期应付映射到 `ap_overdue`。~~ +- [x] ~~查询类问题权限为 `read`。~~ +- [x] ~~生成草稿权限为 `draft_write`。~~ +- [x] ~~审批、上线、付款类动作权限为 `approval_required`。~~ +- [x] ~~越权动作权限为 `forbidden`。~~ + +验收证据： + +- [x] ~~“帮我直接付款”不能被标为可直接执行。~~ + +## 9. API 接口 + +- [x] ~~新增 `POST /api/v1/ontology/parse`。~~ +- [x] ~~请求参数包含用户问题。~~ +- [x] ~~请求参数包含用户上下文。~~ +- [x] ~~响应包含 8 个字段。~~ +- [x] ~~响应包含 `run_id`。~~ +- [x] ~~响应包含置信度。~~ +- [x] ~~响应包含澄清问题。~~ +- [x] ~~每次调用写入 `SemanticParseLog`。~~ +- [x] ~~每次调用写入 `AgentRun` 或关联已有 `AgentRun`。~~ + +验收证据： + +- [x] ~~连续调用多次都能在日志中查到。~~ + +## 10. 前端调试入口 + +- [x] ~~在合适页面增加语义解析调试入口。~~ +- [x] ~~输入框支持自然语言问题。~~ +- [x] ~~点击解析后调用 API。~~ +- [x] ~~展示 8 个字段。~~ +- [x] ~~展示 JSON 原始结果。~~ +- [x] ~~展示置信度。~~ +- [x] ~~展示澄清问题。~~ +- [x] ~~展示 `run_id`。~~ +- [x] ~~错误时展示错误信息。~~ + +验收证据： + +- [x] ~~产品和开发可以直接在页面验证解析结果。~~ + +## 11. 评测集 + +- [x] ~~创建至少 5 条报销问题。~~ +- [ ] 创建至少 5 条叙述型报销问题。 +- [ ] 创建至少 3 条附件 / OCR 摘要带入的报销问题。 +- [x] ~~创建至少 5 条应收问题。~~ +- [x] ~~创建至少 5 条应付问题。~~ +- [x] ~~创建至少 3 条知识库问题。~~ +- [x] ~~创建至少 3 条越权操作问题。~~ +- [ ] 创建至少 3 条模糊短句追问问题。 +- [x] ~~为每条问题写期望 `scenario`。~~ +- [x] ~~为每条问题写期望 `intent`。~~ +- [x] ~~为每条问题写期望权限级别。~~ +- [x] ~~编写评测脚本或测试。~~ + +验收证据： + +- [x] ~~当前评测样本集已通过，覆盖样本准确率达到当天设定阈值。~~ + +## 12. Day 3 验收 + +- [x] ~~语义解析 API 可用。~~ +- [x] ~~8 个核心字段完整返回。~~ +- [x] ~~解析日志可查询。~~ +- [x] ~~低置信度问题有澄清问题。~~ +- [x] ~~越权动作不会被标为可执行。~~ +- [x] ~~前端调试入口可用。~~ +- [x] ~~评测集可运行。~~ +- [x] ~~所有完成项已用 `[x] ~~...~~` 标记。~~ + +## 阻塞记录 + +- [x] ~~暂无。~~ + +## 日终交接 + +- [x] ~~已支持报销 / 应收 / 应付 / 知识 / 风险 / 草稿 / 越权动作等核心场景关键词、实体与权限解析。~~ +- [x] ~~语义层已可接收附件名称、附件数量和 OCR 摘要上下文，但这些样本仍需继续扩到评测集。~~ +- [x] ~~当前仍需继续扩充的弱样本主要是叙述型报销长句、附件/OCR 带入和模糊短句追问。~~ +- [x] ~~Day 4 可直接复用 `scenario / intent / entities / time_range / metrics / constraints / risk_flags / permission / confidence / missing_slots / ambiguity / parse_strategy / clarification_required / clarification_question / run_id`。~~ diff --git a/document/development/agent/agent week plan/day_4_orchestrator_runtime.md b/document/development/agent/agent week plan/day_4_orchestrator_runtime.md new file mode 100644 index 0000000..0cc3152 --- /dev/null +++ b/document/development/agent/agent week plan/day_4_orchestrator_runtime.md @@ -0,0 +1,254 @@ +# Day 4：Orchestrator 运行时 + +## 今天的大开发点 + +建立统一调度层。用户请求和系统任务都先进入 Orchestrator，由它完成语义解析、权限判断、能力选择、Agent 路由、工具调用记录和失败降级。 + +## 为什么第四天做这个 + +没有 Orchestrator，User Agent 和 Hermes 会各自直接调用能力，权限、审计、降级、Trace 都会分散。生产系统必须有统一入口。 + +## 今天主要交付 + +- Orchestrator 请求和响应结构。 +- 用户请求路由到 User Agent。 +- 定时任务路由到 Hermes。 +- 权限级别判断。 +- 语义补槽完成后的报销草稿创建、草稿更新、提交动作路由。 +- 高风险动作确认机制。 +- 能力注册查询。 +- 工具调用封装。 +- AgentRun Trace 查询。 +- 失败降级返回。 + +## 当前完成情况 + +- [x] ~~`/api/v1/orchestrator/run`、统一路由、权限阻断、ToolCall 记录、Trace 和降级结果已经可用。~~ +- [x] ~~用户消息已能路由到 User Agent，占位 Hermes 任务也能由定时入口触发。~~ +- [x] ~~附件名称、页面上下文和 OCR 摘要已能随 Orchestrator 请求透传到语义层和 User Agent。~~ +- [x] ~~Orchestrator 已开始向前端返回结构化 `review_payload`，用于右侧预审面板展示识别意图、槽位、票据和分单建议。~~ +- [x] ~~`conversation_id`、会话消息历史和 `draft_claim_id` 已接入 Orchestrator，会话内追问可继续落到同一张报销草稿。~~ +- [x] ~~已新增最近会话恢复与用户级会话清空接口，个人工作台可显式继续旧会话或删除旧会话后新建。~~ +- [x] ~~`clarification_required` 的报销请求已改为返回结构化核对结果，而不是只回一句追问文案。~~ +- [x] ~~`review_action`、`review_form_values` 已能透传到 User Agent / 报销草稿服务，用于结构化修改后重识别和保存草稿。~~ +- [ ] 真实 `expense_claims` 提交链路尚未接通；草稿建单 / 改单已接到真实落库，附件与 OCR 持久化仍未完成。 +- [ ] 报销附件持久化服务、OCR 结果落库服务和前端 ToolCall 细粒度 Trace 展示尚未接通。 + +相关架构文档： + +- [Orchestrator 与运行流程](<../agent plan/04_orchestrator_and_runtime_flow.md>) +- [能力注册](<../agent plan/07_capability_registry.md>) +- [权限与确认](<../agent plan/08_permission_confirmation.md>) +- [观测与 Trace](<../agent plan/09_observability_and_trace.md>) + +## 当天验收门槛 + +- Orchestrator API 可用。 +- 用户消息能路由到 User Agent 占位实现。 +- 定时任务能路由到 Hermes 占位实现。 +- forbidden 请求不会调用下游 Agent。 +- 每次运行都有 `run_id` 和 Trace。 +- 工具调用失败能记录并返回降级结果。 +- 叙述型报销输入在满足最小槽位后能进入建单或改单流程。 + +## 今天不做 + +- 不做复杂任务编排 DAG。 +- 不做多 Agent 协商。 +- 不做自动高风险动作。 + +## 详细执行清单 + +以下内容为合并后的详细执行清单。 + +## 0. 开始前检查 + +- [x] ~~确认 Day 3 `POST /api/v1/ontology/parse` 可用。~~ +- [x] ~~确认 `AgentRun` 可创建。~~ +- [x] ~~确认 `AgentToolCall` 可创建。~~ +- [x] ~~确认资产列表能查询技能、MCP、任务。~~ +- [x] ~~确认权限级别枚举已稳定。~~ +- [x] ~~找到后端服务层适合放 Orchestrator 的位置。~~ + +## 1. Orchestrator 输入输出 + +- [x] ~~定义 `OrchestratorRequest`。~~ +- [x] ~~请求包含 `source`。~~ +- [x] ~~请求包含 `user_id`。~~ +- [x] ~~请求包含 `message`。~~ +- [x] ~~请求包含 `task_id`。~~ +- [x] ~~请求包含 `context_json`。~~ +- [x] ~~定义 `OrchestratorResponse`。~~ +- [x] ~~响应包含 `run_id`。~~ +- [x] ~~响应包含 `selected_agent`。~~ +- [x] ~~响应包含 `route_reason`。~~ +- [x] ~~响应包含 `permission_level`。~~ +- [x] ~~响应包含 `status`。~~ +- [x] ~~响应包含 `result`。~~ +- [x] ~~响应包含 `requires_confirmation`。~~ +- [x] ~~响应包含 `trace_summary`。~~ + +验收证据： + +- [x] ~~Orchestrator 响应能直接被前端展示。~~ + +## 2. 建立 Orchestrator 服务 + +- [x] ~~新增 `OrchestratorService`。~~ +- [x] ~~实现 `run(request)` 主入口。~~ +- [x] ~~主入口第一步创建 `AgentRun`。~~ +- [x] ~~主入口第二步调用语义解析。~~ +- [x] ~~主入口第三步执行权限判断。~~ +- [x] ~~主入口第四步选择 Agent。~~ +- [x] ~~主入口第五步调用目标 Agent 或返回阻断结果。~~ +- [x] ~~主入口第六步更新 `AgentRun` 状态。~~ +- [x] ~~所有异常都写入 `AgentRun.error_message`。~~ + +验收证据： + +- [x] ~~正常请求状态为 `succeeded`。~~ +- [x] ~~被权限拦截请求状态为 `blocked`。~~ +- [x] ~~异常请求状态为 `failed`。~~ + +## 3. 路由规则 + +- [x] ~~`source=user_message` 默认路由到 User Agent。~~ +- [x] ~~`source=schedule` 默认路由到 Hermes。~~ +- [x] ~~`intent=risk_check` 且来源为 schedule 时路由到 Hermes。~~ +- [x] ~~`intent=query` 且来源为 user_message 时路由到 User Agent。~~ +- [x] ~~`intent=explain` 路由到 User Agent。~~ +- [x] ~~`intent=draft` 路由到 User Agent，并可返回结构化核对结果、草稿结果或草稿更新结果。~~ +- [x] ~~`scenario=expense` 且最小建单槽位完整时，允许进入 `create_expense_claim_draft`。~~ +- [x] ~~`scenario=expense` 且已有 `claim_id` 或会话内 `draft_claim_id` 时，允许进入 `update_expense_claim_draft`。~~ +- [ ] `scenario=expense` 且用户明确确认提交时，允许进入 `submit_expense_claim`。 +- [x] ~~`permission.level=approval_required` 时设置 `requires_confirmation=true`。~~ +- [x] ~~`permission.level=forbidden` 时不调用下游 Agent。~~ +- [x] ~~无法识别或信息不足时返回澄清问题。~~ + +验收证据： + +- [x] ~~同一句风险检查，在用户入口和任务入口有不同路由结果。~~ + +## 4. 权限判断 + +- [x] ~~新增权限判断服务或函数。~~ +- [x] ~~查询类请求返回 `read`。~~ +- [x] ~~草稿类请求返回 `draft_write`。~~ +- [ ] 报销草稿字段补全、附件挂接返回 `draft_write`。 +- [ ] 报销单提交返回 `approval_required`，并要求显式用户确认。 +- [ ] 审批、上线、付款类请求返回 `approval_required`。 +- [x] ~~用户无权限时返回 `forbidden`。~~ +- [x] ~~高风险动作不允许自动执行。~~ +- [x] ~~需要确认的动作返回确认提示。~~ +- [x] ~~权限判断结果写入 `AgentRun.permission_level`。~~ + +验收证据： + +- [x] ~~“直接上线规则”不会被自动执行。~~ +- [x] ~~“直接付款”不会被自动执行。~~ + +## 5. 能力注册查询 + +- [x] ~~从 `AgentAsset` 查询 active 技能。~~ +- [x] ~~从 `AgentAsset` 查询 active MCP。~~ +- [x] ~~从 `AgentAsset` 查询 active 任务。~~ +- [ ] 查询可用的报销单写入服务和附件挂接服务。 +- [ ] 查询可用的 OCR 结果持久化服务和票据文件回溯服务。 +- [x] ~~过滤 disabled 能力。~~ +- [x] ~~过滤未审核 active 条件不满足的规则。~~ +- [x] ~~为每次能力选择记录 `route_json`。~~ +- [x] ~~找不到能力时返回降级说明。~~ + +验收证据： + +- [x] ~~禁用 MCP 不会被 Orchestrator 调用。~~ + +## 6. 工具调用封装 + +- [x] ~~定义统一工具调用接口。~~ +- [ ] 工具请求前写入 `AgentToolCall` running 或准备记录。 +- [x] ~~工具成功后写入响应和耗时。~~ +- [x] ~~工具失败后写入错误。~~ +- [ ] 报销草稿更新、提交也按工具调用或等价服务调用记录。 +- [x] ~~报销草稿创建按工具调用或等价服务调用记录。~~ +- [ ] 附件挂接、OCR 结果落库、票据回溯查询也按工具调用或等价服务调用记录。 +- [x] ~~外部 MCP 调用失败时返回降级结果。~~ +- [x] ~~数据库查询失败时返回明确错误。~~ +- [x] ~~LLM 调用失败时返回可读提示。~~ + +验收证据： + +- [x] ~~每次 Orchestrator 运行至少可以看到 0 到多条工具调用记录。~~ + +## 7. API 接口 + +- [x] ~~新增 `POST /api/v1/orchestrator/run`。~~ +- [x] ~~请求支持用户消息。~~ +- [x] ~~请求支持任务触发。~~ +- [x] ~~响应返回 `run_id`。~~ +- [x] ~~响应返回路由结果。~~ +- [x] ~~响应返回权限结果。~~ +- [x] ~~复用 `GET /api/v1/agent-runs/{run_id}` 查看 Trace。~~ +- [x] ~~Trace 接口返回语义解析、路由、工具调用、最终结果。~~ +- [x] ~~`POST /api/v1/orchestrator/run` 返回的 `result` 已可携带 `review_payload`。~~ + +验收证据： + +- [x] ~~前端或 curl 可以完整看到一次运行链路。~~ + +## 8. 前端最小 Trace 查看 + +- [ ] 在合适位置展示最近运行记录。 +- [x] ~~点击当前对话结果可查看 `run_id`。~~ +- [x] ~~展示 selected_agent。~~ +- [x] ~~展示 route_reason。~~ +- [x] ~~展示 permission_level。~~ +- [ ] 展示工具调用列表。 +- [x] ~~展示错误信息。~~ +- [ ] 展示耗时。 +- [ ] 展示报销写链路中的 claim_id / claim_no / status 变化。 + +验收证据： + +- [x] ~~开发调试时不需要直接查数据库才能理解主要路由结果。~~ + +## 9. 测试 + +- [x] ~~测试用户查询路由到 User Agent。~~ +- [x] ~~测试定时任务路由到 Hermes。~~ +- [x] ~~测试叙述型报销输入可路由到报销建单服务。~~ +- [x] ~~测试同一 `conversation_id` 下的追问会继续更新已有报销草稿。~~ +- [ ] 测试报销单提交前必须显式确认。 +- [x] ~~测试 forbidden 不调用下游 Agent。~~ +- [x] ~~测试 approval_required 返回确认。~~ +- [x] ~~测试工具失败写入 ToolCall。~~ +- [x] ~~测试 Orchestrator 异常写入 AgentRun。~~ + +验收证据： + +- [x] ~~Orchestrator 核心测试通过。~~ + +## 10. Day 4 验收 + +- [x] ~~Orchestrator API 可用。~~ +- [x] ~~用户请求能路由到 User Agent 占位实现。~~ +- [x] ~~定时任务能路由到 Hermes 占位实现。~~ +- [x] ~~语义补槽完成后的报销输入能路由到建单动作。~~ +- [x] ~~语义补槽完成后的报销输入能路由到改单动作。~~ +- [x] ~~权限阻断有效。~~ +- [x] ~~运行 Trace 可查询。~~ +- [x] ~~工具调用日志可查询。~~ +- [x] ~~降级结果可读。~~ +- [x] ~~所有完成项已用 `[x] ~~...~~` 标记。~~ + +## 阻塞记录 + +- [x] ~~暂无。~~ + +## 日终交接 + +- [x] ~~当前路由规则已稳定为：`user_message -> user_agent`、`schedule -> hermes`、`clarification_required -> blocked`。~~ +- [x] ~~当前权限判断已稳定为：`read / draft_write / approval_required / forbidden`，高风险动作默认阻断或要求确认。~~ +- [x] ~~Day 5 需承接的接口契约已明确：Orchestrator 向 User Agent 传入语义结果、能力码、工具结果，并期待返回 `answer / citations / suggested_actions / draft_payload / risk_flags`。~~ +- [x] ~~Day 5 当前已扩展接口契约：除 `answer / citations / suggested_actions / draft_payload / risk_flags` 外，还返回 `review_payload` 用于前端预审工作台。~~ +- [x] ~~下一步仍需补齐的运行时写链路是：附件持久化、OCR 结果落库和提交状态流转。~~ diff --git a/document/development/agent/agent week plan/day_5_user_agent_mvp.md b/document/development/agent/agent week plan/day_5_user_agent_mvp.md new file mode 100644 index 0000000..68e0766 --- /dev/null +++ b/document/development/agent/agent week plan/day_5_user_agent_mvp.md @@ -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 契约。~~ diff --git a/document/development/agent/agent week plan/day_6_hermes_mvp.md b/document/development/agent/agent week plan/day_6_hermes_mvp.md new file mode 100644 index 0000000..92eabda --- /dev/null +++ b/document/development/agent/agent week plan/day_6_hermes_mvp.md @@ -0,0 +1,314 @@ +# Day 6：Hermes MVP + +## 今天的大开发点 + +实现 Hermes 数字员工的最小闭环。Hermes 负责后台内循环：定时巡检、统计日报、风险预警、知识维护、规则草稿形成。 + +## 为什么第六天做这个 + +Hermes 依赖前几天已经建立的资产、规则、语义、Orchestrator、Trace 和权限体系。放在第六天做，可以避免它变成孤立脚本。 + +## 今天主要交付 + +- 任务资产调度入口。 +- 手动触发任务 API。 +- 系统 Hermes 后台执行入口。 +- 每日风险巡检。 +- 每日报销、报账、账款统计。 +- OCR Mock 接入点。 +- 知识候选条目生成。 +- 规则草稿生成。 +- LLM Wiki 解析目录与增量重建机制。 +- Hermes 运行结果展示。 + +相关架构文档： + +- [Agent 职责边界](<../agent plan/03_agent_responsibilities.md>) +- [OCR 票据识别架构](<../agent plan/11_ocr_invoice_architecture.md>) +- [LLM Wiki 知识库架构](<../agent plan/12_llm_wiki_knowledge_architecture.md>) +- [反馈学习闭环](<../agent plan/15_feedback_learning_loop.md>) + +## 当天验收门槛 + +- 至少一个 Hermes 任务可以手动触发。 +- 风险巡检有结构化结果。 +- 每日统计有结构化结果。 +- OCR Mock 调用能记录 ToolCall。 +- 知识候选只能是草稿。 +- 规则草稿只能是 draft，不能自动上线。 + +## 今天不做 + +- 不做完整生产调度集群。 +- 不做真实 OCR 深度集成。 +- 不做自动发布知识。 +- 不做自动上线规则。 +- 不做每天无差别全量重建 LLM Wiki。 + +## 本次新增约束 + +### 1. Hermes 必须是系统后台 Hermes + +这次 Hermes 不应继续只是代码里的占位逻辑。 + +最小可接受形态： + +- 后端任务入口能明确区分 `selected_agent=hermes`。 +- 后端可调用系统安装的 Hermes CLI 或受控 Hermes 进程。 +- 即使当前阶段仍允许 Python 内部 fallback，也必须保留真实 Hermes 进程接入点。 +- Hermes 的模型配置继续由系统设置同步，不允许在任务代码里再写一套模型配置。 +- Hermes 执行应记录 `run_id`、ToolCall、错误信息和最终摘要。 + +### 2. LLM Wiki 必须有独立解析目录 + +原始知识文件与解析产物必须分离。 + +推荐目录： + +```text +/app/server/storage/knowledge/报销制度 原始制度文件 +/app/server/storage/knowledge/.llm_wiki 解析产物根目录 +/app/server/storage/knowledge/.llm_wiki/documents// + document.json + text.md + chunks.json + clauses.json + knowledge_candidates.json + rule_candidates.json +/app/server/storage/knowledge/.llm_wiki/index.json +/app/server/storage/knowledge/.llm_wiki/sync_runs.json +``` + +### 3. LLM Wiki 只能增量形成 + +不允许每天无脑全量重建。 + +文档级重建触发条件至少包括： + +- 文件名 `original_name` 变更。 +- 文件对象 `stored_name` 变更。 +- 内容摘要 `sha256` 变更。 +- 上传版本 `version_number` 变更。 +- 更新时间 `updated_at` 变更，视为人工改动。 + +如果以上条件都未变化： + +- 本次文档应标记为 `unchanged_skipped`。 +- 不重新抽取文本。 +- 不重新生成知识候选。 +- 不重新生成规则草稿。 + +### 4. 规则草稿必须模板化 + +Hermes 不允许自由生成任意结构的规则。 + +必须满足： + +- 规则 Markdown 使用固定模板。 +- 可执行规则 JSON 使用固定模板族，不允许随意拼字段。 +- 规则中心要同时展示人类可读的 Markdown 和机器可执行的 JSON。 +- Hermes 生成的规则默认 `draft`。 +- 审核通过前不能 `active`。 +- Hermes 不能直接覆盖线上 active 规则。 + +## 详细执行清单 + +以下内容为合并后的详细执行清单。 + +## 0. 开始前检查 + +- [x] ~~确认任务资产 `asset_type=task` 可查询。~~ +- [x] ~~确认 Orchestrator 能处理 `source=schedule`。~~ +- [x] ~~确认系统 Hermes CLI 或等价后台 Hermes 进程可被调用。~~ +- [x] ~~确认 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. 任务调度入口 + +- [x] ~~新增手动触发任务 API。~~ +- [x] ~~API 参数支持任务资产 ID。~~ +- [x] ~~API 调用 Orchestrator，source 为 `schedule`。~~ +- [x] ~~Orchestrator 路由到 Hermes。~~ +- [x] ~~Hermes 执行结果写入 AgentRun。~~ +- [ ] 任务执行失败时写入错误。 +- [ ] 任务执行结束后更新任务最近执行时间。 +- [ ] 任务执行结束后更新任务最近执行状态。 +- [x] ~~保留真实 Hermes 进程执行入口，不把 Hermes 固定写死为本地占位函数。~~ + +验收证据： + +- [x] ~~可以手动触发一次 Hermes 任务并看到运行结果。~~ + +## 3. 每日风险巡检 + +- [ ] 实现重复报销巡检。 +- [ ] 实现金额超标巡检。 +- [ ] 实现发票异常巡检占位。 +- [ ] 实现应收逾期巡检。 +- [ ] 实现应付异常付款巡检。 +- [ ] 每个风险项包含风险类型。 +- [ ] 每个风险项包含业务对象。 +- [ ] 每个风险项包含触发规则。 +- [ ] 每个风险项包含建议动作。 +- [ ] 每个风险项包含风险等级。 + +验收证据： + +- [ ] 风险巡检结果可以被用户理解和追溯。 + +## 4. 每日统计 + +- [ ] 统计当日报销单数量。 +- [ ] 统计当日报销金额。 +- [ ] 统计当日报账数量。 +- [ ] 统计当日报账金额。 +- [ ] 统计应收新增金额。 +- [ ] 统计应收逾期金额。 +- [ ] 统计应付待付金额。 +- [ ] 统计应付逾期金额。 +- [ ] 输出日报摘要。 + +验收证据： + +- [ ] Hermes 能生成一份每日财务摘要。 + +## 5. OCR 接入点 + +- [ ] 原始票据先落 `document_assets` 和 `document_asset_versions`，不直接以内存临时文件参与流程。 +- [ ] 建立 OCR 识别服务接口。 +- [ ] 定义发票识别输入结构。 +- [ ] 定义发票识别输出结构。 +- [ ] 输出结构包含发票号。 +- [ ] 输出结构包含开票日期。 +- [ ] 输出结构包含金额。 +- [ ] 输出结构包含税额。 +- [ ] 输出结构包含销售方。 +- [ ] 输出结构包含购买方。 +- [ ] 输出结构包含置信度。 +- [ ] OCR 输入可通过 `storage_key` 或等价文件定位字段读取原件。 +- [ ] 当前阶段允许使用 Mock 结果。 +- [ ] OCR 调用写入 ToolCall。 + +验收证据： + +- [ ] Hermes 风险巡检中可以调用 OCR Mock。 + +## 6. 知识库维护 + +- [ ] 建立知识条目写入服务。 +- [x] ~~建立 `.llm_wiki` 独立解析目录。~~ +- [x] ~~原始文档与解析产物物理隔离。~~ +- [x] ~~文本抽取结果落 `text.md`。~~ +- [x] ~~分块结果落 `chunks.json`。~~ +- [x] ~~文档索引落 `index.json`。~~ +- [x] ~~同步记录落 `sync_runs.json`。~~ +- [x] ~~文档签名包含 `original_name`、`stored_name`、`sha256`、`version_number`、`updated_at`。~~ +- [x] ~~未变化文档跳过重建并记录 `unchanged_skipped`。~~ +- [x] ~~Hermes 可以生成知识候选条目。~~ +- [x] ~~候选条目包含标题。~~ +- [x] ~~候选条目包含正文。~~ +- [x] ~~候选条目包含来源。~~ +- [x] ~~候选条目包含适用场景。~~ +- [x] ~~候选条目默认状态为 `draft`。~~ +- [x] ~~知识条目不能自动发布。~~ +- [ ] 知识条目写入审计日志。 + +验收证据： + +- [x] ~~Hermes 可以生成待审核知识条目。~~ + +## 7. 规则草稿形成 + +- [ ] Hermes 可以根据风险巡检结果生成规则草稿。 +- [x] ~~规则草稿使用固定 Markdown 模板。~~ +- [x] ~~规则草稿生成可执行 JSON 草稿。~~ +- [x] ~~规则中心展示 Markdown + JSON 双视图。~~ +- [x] ~~JSON 草稿字段受模板约束，不允许自由扩展。~~ +- [x] ~~规则草稿保存为 `asset_type=rule`。~~ +- [x] ~~规则草稿状态为 `draft`。~~ +- [x] ~~规则草稿包含 Markdown 内容。~~ +- [x] ~~规则草稿包含 JSON 内容或等价 `runtime_rule` 配置。~~ +- [ ] 规则草稿包含生成原因。 +- [ ] 规则草稿包含关联风险样例。 +- [x] ~~规则草稿不能自动上线。~~ +- [x] ~~规则草稿需要审核人。~~ +- [x] ~~规则草稿写入审计日志。~~ +- [x] ~~Hermes 不直接覆盖线上 active 规则。~~ + +验收证据： + +- [x] ~~Hermes 生成的新规则出现在规则列表中，但不是 active。~~ + +## 8. Hermes 页面或日志展示 + +- [x] ~~任务详情能看到最近执行结果。~~ +- [ ] 任务详情能手动触发执行。 +- [ ] 任务详情能看到风险项数量。 +- [ ] 任务详情能看到日报摘要。 +- [ ] 任务详情能看到知识候选数量。 +- [ ] 任务详情能看到规则草稿数量。 +- [ ] 运行 Trace 能看到 Hermes 步骤。 +- [x] ~~错误时展示错误原因。~~ + +验收证据： + +- [x] ~~不查数据库也能判断 Hermes 是否执行成功。~~ + +## 9. 测试 + +- [x] ~~测试手动触发任务。~~ +- [x] ~~测试 Orchestrator 路由到 Hermes。~~ +- [ ] 测试风险巡检输出。 +- [ ] 测试日报统计输出。 +- [ ] 测试 OCR Mock 调用。 +- [x] ~~测试知识候选写入。~~ +- [x] ~~测试规则草稿生成。~~ +- [ ] 测试 Hermes 异常写入 AgentRun。 + +验收证据： + +- [ ] Hermes 核心测试通过。 + +## 10. Day 6 验收 + +- [x] ~~Hermes 可被 Orchestrator 调用。~~ +- [x] ~~至少一个任务可以手动触发。~~ +- [ ] 风险巡检有结构化结果。 +- [ ] 每日统计有结构化结果。 +- [ ] OCR Mock 接入点可用。 +- [x] ~~知识候选可生成。~~ +- [x] ~~规则草稿可生成且不能自动上线。~~ +- [x] ~~任务详情或运行日志能展示结果。~~ +- [x] ~~所有完成项已用 `[x] ~~...~~` 标记。~~ + +## 阻塞记录 + +- [ ] 暂无。 + +## 日终交接 + +- [ ] 写明 Hermes 已支持任务类型。 +- [ ] 写明 OCR 当前是真实还是 Mock。 +- [ ] 写明生成的知识和规则草稿状态。 +- [ ] 写明 Day 7 需要重点回归的路径。 diff --git a/document/development/agent/agent week plan/day_7_hardening_demo_acceptance.md b/document/development/agent/agent week plan/day_7_hardening_demo_acceptance.md new file mode 100644 index 0000000..4146d5d --- /dev/null +++ b/document/development/agent/agent week plan/day_7_hardening_demo_acceptance.md @@ -0,0 +1,260 @@ +# Day 7：加固、演示和验收 + +## 今天的大开发点 + +不再大规模扩功能，集中做回归、加固、测试、演示脚本、文档收尾和下一阶段交接。 + +## 为什么第七天做这个 + +一周开发不能只停留在“代码写了”。必须能演示、能追溯、能说清楚边界、能交给下一阶段继续开发。 + +## 今天主要交付 + +- 核心链路回归。 +- 权限和风险边界复查。 +- 审计日志补齐。 +- AgentRun Trace 补齐。 +- 前端体验修补。 +- 测试和构建记录。 +- 评测集执行记录。 +- 演示数据准备。 +- 演示脚本。 +- 下一阶段开发建议。 + +相关架构文档： + +- [Agent Plan 总览](<../agent plan/00_README.md>) +- [开发路线图](<../agent plan/05_development_roadmap.md>) +- [观测与 Trace](<../agent plan/09_observability_and_trace.md>) +- [评测与测试集](<../agent plan/10_evaluation_and_testset.md>) + +## 当天验收门槛 + +- 任务规则中心核心路径可演示。 +- 语义本体、Orchestrator、User Agent、Hermes 都能跑通最小链路。 +- 未审核规则、高风险动作、自动付款等边界都被拦截。 +- AgentRun、ToolCall、AuditLog 可追溯。 +- 有测试记录、演示脚本和交接说明。 + +## 今天不做 + +- 不做新大功能。 +- 不临时扩大范围。 +- 不绕过测试和验收。 + +## 详细执行清单 + +以下内容为合并后的详细执行清单。 + +## 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] ~~...~~` 标记。 + +## 测试记录 + +- [ ] 后端测试：未运行。 +- [ ] 前端构建：未运行。 +- [ ] 语义评测：未运行。 +- [ ] 手动验收：未运行。 + +## 阻塞记录 + +- [ ] 暂无。 + +## 日终交接 + +- [ ] 写明本周最终完成内容。 +- [ ] 写明未完成内容。 +- [ ] 写明生产化前必须补齐内容。 +- [ ] 写明下一周建议优先级。 diff --git a/document/development/agent/agent_week_plan_html/day-1.html b/document/development/agent/agent_week_plan_html/day-1.html new file mode 100644 index 0000000..c215609 --- /dev/null +++ b/document/development/agent/agent_week_plan_html/day-1.html @@ -0,0 +1,137 @@ + + + + + + Day 1 - 基础模型与工程骨架 + + + +
+
+ D1Day 1 View +
+ 返回总览 + 周计划原文 + 合并文档原文 +
+
+ +
+ Day 1 + Day 2 + Day 3 + Day 4 + Day 5 + Day 6 + Day 7 +
+ +
+
Foundation Completed
+

Day 1 基础模型与工程骨架

+

这一天的任务不是做炫目的业务能力，而是把后面 6 天要反复依赖的模型、版本、审核、run trace、审计日志和最小业务数据源一次定稳。Day 1 做虚了，Day 4 到 Day 6 会全部返工。

+
+
当前状态
已完成（2026-05-11），可直接进入 Day 2 联调。
+
上游依赖
无，Day 1 是全周底座。
+
下游交接
Day 2 资产 API，Day 3 解析日志，Day 4 run trace，Day 5/6 业务数据查询。
+
当天关键
先确定统一模型，再接 API 骨架和种子数据。
+
+
+ +
Three-Layer Mapping
+

三层文档映射

+
+
+

路线图

+

周计划里定义这一天要完成“工程地基”，强调只做稳定模型、API 骨架、种子数据、基础审计和可运行验证。

+
day_1_foundation_models.md
+
+
+

执行细则

+

执行层把 Day 1 拆成命名边界、最小财务业务数据模型、Agent 资产模型、版本、审核、Run、ToolCall、SemanticParseLog、AuditLog、Schema、API、服务层。

+
agent week plan/day_1
+
+
+

架构依据

+

主要受总体架构、语义本体、数据契约、能力注册、权限确认、可观测性和财务标准模型约束。

+
+ 01 + 02 + 06 + 07 + 08 + 09 + 14 +
+
+
+ +
Build Order
+

推荐开发顺序

+
+
Step 1先确认后端目录、ORM、迁移方式、测试目录和不该碰的文件。
+
Step 2统一命名：资产类型、状态、审核状态、Agent、权限级别。
+
Step 3补最小财务业务数据模型：expense_claims、accounts_receivable、accounts_payable。
+
Step 4完成 AgentAsset、Version、Review、Run、ToolCall、ParseLog、AuditLog。
+
Step 5把 Schema、API 骨架、服务层、种子数据接起来。
+
+ +
Must Deliver
+

今天必须产出的东西

+
+
+

平台底座表

+
    +
  • AgentAsset、AgentAssetVersion、AgentAssetReview
    • +
  • AgentRun、AgentToolCall、SemanticParseLog
    • +
  • AuditLog
    • +
+
+
+

最小业务数据来源

+
    +
  • 报销至少有时间、地点、理由、金额、员工、部门、状态。
    • +
  • 应收至少有客户、金额、未收金额、到期日、账龄、状态。
    • +
  • 应付至少有供应商、金额、未付金额、到期日、账龄、状态。
    • +
+
+
+

API 骨架

+
    +
  • 资产列表 / 详情 / 版本 / 审核 / 上线。
    • +
  • 运行日志与审计日志查询。
    • +
  • 返回真实数据库结果，不用前端硬编码收尾。
    • +
+
+
+

统一服务边界

+
    +
  • 上线拦截逻辑在服务层，不堆到路由。
    • +
  • 所有写操作要留审计接口。
    • +
  • 任何 Agent 执行记录都必须生成 run_id。
    • +
+
+
+ +
Acceptance Snapshot
+

验收快照

+
+
资产模型
已落地 3 条规则、2 条技能、2 条 MCP、3 条任务，并可通过资产接口返回。
+
版本与审核
三条规则都具备版本历史；同一资产版本号不可重复，未审核规则不能上线。
+
运行与错误
`GET /api/v1/agent-runs` 可返回 3 条运行日志，任意新建 Run 自动生成 run_id。
+
最小业务表
报销、应收、应付种子数据已就位，后续查询和风险巡检都有明确数据来源。
+
+ +
Common Misses
+

这一天最容易漏掉的点

+
    +
  • 只建 Agent 表，不建最小财务业务表，导致 User Agent 和 Hermes 后面无数据可查。
    • +
  • 把审核拦截塞在 API 路由里，后面很难复用到 Orchestrator 和别的入口。
    • +
  • 没有统一 run_id 和审计接口，Day 4 到 Day 7 的 Trace 会断链。
    • +
+ +
Day 1 的判断标准很简单：不是“代码写了多少”，而是“后面 6 天会不会反复回头补地基”。
+
+ + diff --git a/document/development/agent/agent_week_plan_html/day-2.html b/document/development/agent/agent_week_plan_html/day-2.html new file mode 100644 index 0000000..0cea4d5 --- /dev/null +++ b/document/development/agent/agent_week_plan_html/day-2.html @@ -0,0 +1,132 @@ + + + + + + Day 2 - 任务规则中心联调 + + + +
+
+ D2Day 2 View +
+ 返回总览 + 周计划原文 + 合并文档原文 +
+
+ +
+ Day 1 + Day 2 + Day 3 + Day 4 + Day 5 + Day 6 + Day 7 +
+ +
+
Integration
+

Day 2 任务规则中心联调

+

Day 2 的核心不是“把页面做漂亮”，而是让规则、技能、MCP、任务这四类资产第一次脱离本地假数据，真正连到 Day 1 的数据库和 API。最关键的能力是 Markdown、版本、审核和上线约束闭环。

+
+
上游依赖
Day 1 的资产模型、版本模型、审核模型、资产 API。
+
下游交接
Day 3 要复用资产数据，Day 4 要查询 active 技能 / MCP / 任务。
+
当天关键
前端联调不是硬编码演示，而是可对接真实后端。
+
+
+ +
Three-Layer Mapping
+

三层文档映射

+
+
+

路线图

+

周计划要求把任务规则中心从静态 UI 升级到真实数据对接，覆盖规则、技能、MCP、任务四类资产。

+
day_2_rule_center_integration.md
+
+
+

执行细则

+

执行层拆成 API Client、四类列表、规则详情、Markdown 编辑、版本卡片、审核与上线、技能详情、MCP 详情、任务详情、前端质量和当天验收。

+
agent week plan/day_2
+
+
+

架构依据

+

这一天主要受能力注册、规则形成生命周期和数据治理约束，重点在四类资产的统一展示方式和规则上线前审核拦截。

+
+ 07 + 13 + 06 +
+
+
+ +
Build Order
+

推荐开发顺序

+
+
Step 1先补 API Client：列表、详情、版本、保存、审核、上线、运行日志。
+
Step 2把四个页签的真实数据接起来，覆盖筛选、搜索、状态、空态和加载态。
+
Step 3把规则详情的 Hero 区、Markdown 编辑器、版本卡片和审核信息拉通。
+
Step 4补技能 / MCP / 任务的差异化详情，不复用规则编辑器。
+
Step 5最后收 UI 细节、错误态、禁用态、确认弹窗和构建验证。
+
+ +
Must Deliver
+

今天必须产出的东西

+
+
+

规则中心四页签

+
    +
  • 规则、技能、MCP、任务都能切换。
    • +
  • 每个页签都来自真实接口，不再只读本地常量。
    • +
  • 搜索和状态筛选同时生效。
    • +
+
+
+

规则详情闭环

+
    +
  • 能读取当前 Markdown。
    • +
  • 能保存并刷新版本列表。
    • +
  • 能展示审核者、审核状态、上线条件。
    • +
+
+
+

版本与上线约束

+
    +
  • 最近 5 个版本可见。
    • +
  • 切换旧版本必须弹确认框。
    • +
  • 未审核规则不能上线，拒绝原因要可见。
    • +
+
+
+

详情差异化

+
    +
  • 技能详情展示输入输出与依赖。
    • +
  • MCP 详情展示服务地址、鉴权、降级策略。
    • +
  • 任务详情展示 cron、执行 Agent、最近执行结果。
    • +
+
+
+ +
Acceptance Snapshot
+

验收快照

+
+
真实数据
四个页签都能用真实后端数据渲染，后端不可用时有明确错误提示。
+
规则编辑
Markdown 保存后刷新页面仍在，保存失败不丢输入。
+
版本卡片
最近 5 个版本可切换，当前版本标识清楚但不造成布局位移。
+
审核上线
pending / rejected 规则都无法上线，approved 才能放行。
+
+ +
Common Misses
+

这一天最容易漏掉的点

+
    +
  • 只把规则页签接成真实数据，技能、MCP、任务仍然靠假数据撑场面。
    • +
  • 只做版本列表展示，不做确认弹窗和拒绝风险提示。
    • +
  • 把任务写成“定时任务”暴露给用户，违背文档里 UI 名称统一成“任务”的约束。
    • +
+ +
Day 2 的完成标准不是“页面能打开”，而是“规则中心第一次成为真实的资产入口”。
+
+ + diff --git a/document/development/agent/agent_week_plan_html/day-3.html b/document/development/agent/agent_week_plan_html/day-3.html new file mode 100644 index 0000000..7946f9b --- /dev/null +++ b/document/development/agent/agent_week_plan_html/day-3.html @@ -0,0 +1,132 @@ + + + + + + Day 3 - 语义本体 MVP + + + +
+
+ D3Day 3 View +
+ 返回总览 + 周计划原文 + 合并文档原文 +
+
+ +
+ Day 1 + Day 2 + Day 3 + Day 4 + Day 5 + Day 6 + Day 7 +
+ +
+
Ontology
+

Day 3 语义本体 MVP

+

这一天把自然语言问题统一切成 8 个核心字段。Day 3 不是追求大模型多聪明，而是先让结构稳定、可落日志、可被 Orchestrator、User Agent 和 Hermes 共用。

+
+
上游依赖
Day 1 的 SemanticParseLog / AgentRun，Day 2 的资产 API。
+
下游交接
Day 4 路由、Day 5 查询解释、Day 6 风险巡检都直接消费这 8 字段。
+
当天关键
名字统一、类型统一、日志统一、低置信度有澄清问题。
+
+
+ +
Three-Layer Mapping
+

三层文档映射

+
+
+

路线图

+

周计划要求建立用户问题的统一语义解析层，覆盖场景、意图、对象、时间、指标、约束、风险、权限 8 字段。

+
day_3_semantic_ontology_mvp.md
+
+
+

执行细则

+

执行层拆成 8 字段定义、字段枚举、Schema、解析服务、对象提取、时间范围、指标约束、风险权限、API、前端调试入口和评测集。

+
agent week plan/day_3
+
+
+

架构依据

+

主要受语义本体、财务标准模型和数据治理约束。应收、应付、报销的对象语义必须能回到最小业务表和标准对象。

+
+ 02 + 14 + 06 +
+
+
+ +
Build Order
+

推荐开发顺序

+
+
Step 1先固定 8 个字段名字、类型、默认值和示例。
+
Step 2把 scenario、intent、permission.level 的枚举定死。
+
Step 3做请求/响应 Schema，再写解析服务。
+
Step 4补对象提取、时间范围、指标约束、风险和权限映射。
+
Step 5接 API、日志、调试入口和最小评测集。
+
+ +
Must Deliver
+

今天必须产出的东西

+
+
+

8 字段统一结构

+
    +
  • scenario、intent、entities、time_range
    • +
  • metrics、constraints、risk_flags、permission
    • +
  • 附带 confidence、clarification_required、run_id
    • +
+
+
+

规则解析优先版

+
    +
  • 先用关键词和规则解析打底。
    • +
  • 报销 / 应收 / 应付 / 知识 / unknown 场景都能落到结构。
    • +
  • 越权动作能识别为 approval_required 或 forbidden。
    • +
+
+
+

日志和调试入口

+
    +
  • 每次解析都要落 SemanticParseLog。
    • +
  • 前端可直接输入一句话看 8 字段结果。
    • +
  • 低置信度问题必须给澄清问题。
    • +
+
+
+

最小评测集

+
    +
  • 至少覆盖报销、应收、应付、知识、越权动作。
    • +
  • 每条样例要写期望 scenario、intent 和权限级别。
    • +
  • 当天目标是可评测，而不是追求完美准确率。
    • +
+
+
+ +
Acceptance Snapshot
+

验收快照

+
+
语义结构
8 字段在 Schema、服务层、日志里名字完全一致。
+
关键识别
“本周报销超标风险”“客户 A 本月应收”“供应商 B 明天要付多少钱”都能落到正确场景和意图。
+
权限结果
“帮我直接付款”不能被识别成可直接执行动作。
+
日志与前端
连续调用多次都能在日志中查到，并能通过调试入口观察结果。
+
+ +
Common Misses
+

这一天最容易漏掉的点

+
    +
  • 字段结构和日志结构各写一套名字，后面 Trace 很难串。
    • +
  • 只做 scenario 和 intent，不做 permission，Day 4 会直接失去拦截依据。
    • +
  • 只在服务里返回结果，不把解析过程落库或落日志，后续无法复盘误判样例。
    • +
+ +
Day 3 的价值在于把“语义理解”从模糊文本变成稳定协议。后面所有智能能力都站在这层协议上。
+
+ + diff --git a/document/development/agent/agent_week_plan_html/day-4.html b/document/development/agent/agent_week_plan_html/day-4.html new file mode 100644 index 0000000..2307dc0 --- /dev/null +++ b/document/development/agent/agent_week_plan_html/day-4.html @@ -0,0 +1,133 @@ + + + + + + Day 4 - Orchestrator 运行时 + + + +
+
+ D4Day 4 View +
+ 返回总览 + 周计划原文 + 合并文档原文 +
+
+ +
+ Day 1 + Day 2 + Day 3 + Day 4 + Day 5 + Day 6 + Day 7 +
+ +
+
Runtime
+

Day 4 Orchestrator 运行时

+

Day 4 把整个系统第一次串成“能跑的链”。用户消息和定时任务都先走 Orchestrator，由它创建 run、调用语义解析、做权限判断、选择 Agent、记录 ToolCall 和 Trace，然后再给下游执行。

+
+
上游依赖
Day 3 的语义解析结果，Day 1 的 Run / ToolCall，Day 2 的 active 资产。
+
下游交接
Day 5 User Agent 和 Day 6 Hermes 都通过它被调度。
+
当天关键
权限拦截和 Trace 必须在 Orchestrator 层，而不是散落在各 Agent。
+
+
+ +
Three-Layer Mapping
+

三层文档映射

+
+
+

路线图

+

周计划要求建立统一调度层，让用户请求和系统任务都先进入 Orchestrator，再根据语义、权限、能力注册路由到 User Agent、Hermes、MCP 或规则引擎。

+
day_4_orchestrator_runtime.md
+
+
+

执行细则

+

执行层拆成输入输出、Orchestrator 服务、路由规则、权限判断、能力查询、工具调用封装、API、最小 Trace 查看和测试。

+
agent week plan/day_4
+
+
+

架构依据

+

主要受运行时流程、能力注册、权限确认和可观测性约束。Day 4 的输出要能直接给前端展示，并支持 Day 5/6 的占位实现接入。

+
+ 04 + 07 + 08 + 09 +
+
+
+ +
Build Order
+

推荐开发顺序

+
+
Step 1先定 OrchestratorRequest 和 OrchestratorResponse。
+
Step 2写 run(request) 主流程：创建 Run、解析语义、判权限、选 Agent、更新状态。
+
Step 3把用户入口 / 任务入口的路由规则固化下来。
+
Step 4封装工具调用记录和降级策略。
+
Step 5暴露 API 和最小 Trace 页面或接口。
+
+ +
Must Deliver
+

今天必须产出的东西

+
+
+

统一入口

+
    +
  • source=user_message 与 source=schedule 都能进同一入口。
    • +
  • 请求返回 run_id、selected_agent、route_reason、permission_level。
    • +
  • 返回结果要能被前端直接展示。
    • +
+
+
+

权限与路由

+
    +
  • 查询类走 User Agent，定时风险类走 Hermes。
    • +
  • approval_required 只返回确认，不直接执行。
    • +
  • forbidden 直接阻断，不调下游 Agent。
    • +
+
+
+

能力与工具调用

+
    +
  • 只查询 active 技能 / MCP / 任务。
    • +
  • 禁用能力不允许被调用。
    • +
  • 每次工具调用都能落 AgentToolCall。
    • +
+
+
+

Trace 与降级

+
    +
  • Trace 能串起语义解析、路由、工具调用和最终结果。
    • +
  • 外部 MCP 失败要返回降级说明，不让前端拿到不可读错误。
    • +
  • 异常都要写进 AgentRun.error_message。
    • +
+
+
+ +
Acceptance Snapshot
+

验收快照

+
+
路由结果
同一句风险检查，在用户入口和任务入口会有不同路由结果。
+
权限边界
“直接上线规则”和“直接付款”都不会被自动执行。
+
日志完整度
每次运行至少有一条 AgentRun，工具调用有 0 到多条 AgentToolCall。
+
可观察性
前端或 curl 可以完整看到一次运行链路，不需要直接查数据库猜过程。
+
+ +
Common Misses
+

这一天最容易漏掉的点

+
    +
  • 把权限判断放到 User Agent / Hermes 内部，导致系统没有统一边界。
    • +
  • 只记录成功 ToolCall，不记录失败 ToolCall，后面降级和排错会缺证据。
    • +
  • 路由能跑，但没有统一 Trace 输出，Day 7 演示时会非常难讲清链路。
    • +
+ +
Day 4 的价值是把系统从“有很多零件”变成“有一条统一运行链”。
+
+ + diff --git a/document/development/agent/agent_week_plan_html/day-5.html b/document/development/agent/agent_week_plan_html/day-5.html new file mode 100644 index 0000000..2ccde41 --- /dev/null +++ b/document/development/agent/agent_week_plan_html/day-5.html @@ -0,0 +1,133 @@ + + + + + + Day 5 - User Agent MVP + + + +
+
+ D5Day 5 View +
+ 返回总览 + 周计划原文 + 合并文档原文 +
+
+ +
+ Day 1 + Day 2 + Day 3 + Day 4 + Day 5 + Day 6 + Day 7 +
+ +
+
User Agent
+

Day 5 User Agent MVP

+

这一天开始让“用户真的能问问题”。但 User Agent 只负责查询、解释、规则引用和草稿生成，绝不绕过权限做审批、付款、上线这类高风险动作。

+
+
上游依赖
Day 4 Orchestrator、Day 3 语义结构、Day 1 业务数据与日志模型、Day 2 规则资产。
+
下游交接
Day 7 要拿它做问答演示、规则解释演示和草稿生成演示。
+
当天关键
回答可读、引用可追溯、草稿可确认、高风险不自动执行。
+
+
+ +
Three-Layer Mapping
+

三层文档映射

+
+
+

路线图

+

周计划要求做用户自然语言入口、报销 / 应收 / 应付查询解释、规则引用解释、建议草稿和前端入口。

+
day_5_user_agent_mvp.md
+
+
+

执行细则

+

执行层拆成输入输出、查询处理、规则解释、风险解释、草稿生成、知识库读取骨架、对话入口、安全边界和测试。

+
agent week plan/day_5
+
+
+

架构依据

+

主要受 Agent 职责划分、运行时流程、知识架构和规则形成生命周期约束。所有高风险动作只能停留在建议或草稿层。

+
+ 03 + 04 + 12 + 13 +
+
+
+ +
Build Order
+

推荐开发顺序

+
+
Step 1先定 UserAgentRequest / UserAgentResponse 协议。
+
Step 2优先实现报销、应收、应付查询处理器。
+
Step 3补规则解释和风险解释，让回答有依据而不是只给一句话。
+
Step 4补草稿生成与知识读取骨架。
+
Step 5最后接前端问答入口、加载态、错误态和确认提示。
+
+ +
Must Deliver
+

今天必须产出的东西

+
+
+

三类财务查询

+
    +
  • 报销查询可读，能查金额、状态或进度。
    • +
  • 应收查询可读，能查客户未收金额或账龄。
    • +
  • 应付查询可读，能查供应商待付款或付款状态。
    • +
+
+
+

解释能力

+
    +
  • 规则解释能引用 active 规则、版本号和更新时间。
    • +
  • 风险解释能说明风险类型、原因和建议动作。
    • +
  • 知识库不可用时要优雅降级。
    • +
+
+
+

草稿而非执行

+
    +
  • 可生成报销处理意见草稿、应收催收建议草稿、应付付款建议草稿。
    • +
  • 草稿必须写明“待人工确认”。
    • +
  • 草稿行为写入审计日志和 AgentRun 结果。
    • +
+
+
+

用户入口

+
    +
  • 前端输入框走 Orchestrator，不绕行。
    • +
  • 显示回答、引用、建议动作、确认提示和 run_id。
    • +
  • 有加载态和错误态。
    • +
+
+
+ +
Acceptance Snapshot
+

验收快照

+
+
问答闭环
用户在页面上能完成一次自然语言提问、拿到回答、看到引用和 run_id。
+
三类场景
至少报销、应收、应付三类财务问题都有结构化回答。
+
引用能力
“为什么这笔报销有风险”这类问题能引用规则，而不是只给模糊判断。
+
安全边界
“直接付款”“直接审批”类提示不会自动执行，只能变成建议或草稿。
+
+ +
Common Misses
+

这一天最容易漏掉的点

+
    +
  • 只返回原始查询数据，不把结果翻译成用户可读回答。
    • +
  • 只做草稿内容，不做 requires_confirmation 和审计日志。
    • +
  • 绕过 Orchestrator 直接从前端打 User Agent，导致 Day 4 的统一链路失效。
    • +
+ +
Day 5 的判断标准是：用户能问、系统能答、回答有依据、动作不越权。
+
+ + diff --git a/document/development/agent/agent_week_plan_html/day-6.html b/document/development/agent/agent_week_plan_html/day-6.html new file mode 100644 index 0000000..178fe9f --- /dev/null +++ b/document/development/agent/agent_week_plan_html/day-6.html @@ -0,0 +1,133 @@ + + + + + + Day 6 - Hermes MVP + + + +
+
+ D6Day 6 View +
+ 返回总览 + 周计划原文 + 合并文档原文 +
+
+ +
+ Day 1 + Day 2 + Day 3 + Day 4 + Day 5 + Day 6 + Day 7 +
+ +
+
Hermes
+

Day 6 Hermes MVP

+

Hermes 是后台数字员工，不做即时对话，而是负责定时巡检、风险预警、日报统计、知识候选和规则草稿。它的关键不是“会不会说”，而是“任务能不能跑、结果能不能追”。

+
+
上游依赖
Day 4 的 Orchestrator 路由，Day 1 的任务与日志表，Day 3 的语义结构，Day 5 可复用的风险/规则/知识接口。
+
下游交接
Day 7 要用它做手动触发任务、查看结果、展示规则草稿和知识候选。
+
当天关键
任务入口、风险项结构、OCR Mock、知识候选和规则草稿都必须可追溯。
+
+
+ +
Three-Layer Mapping
+

三层文档映射

+
+
+

路线图

+

周计划要求实现 Hermes 调度入口、每日风险巡检、统计任务、知识库维护、OCR Mock 和运行结果面板或 API。

+
day_6_hermes_mvp.md
+
+
+

执行细则

+

执行层拆成输入输出、任务调度入口、风险巡检、每日统计、OCR 接入点、知识库维护、规则草稿形成、结果展示和测试。

+
agent week plan/day_6
+
+
+

架构依据

+

主要受 Agent 职责、OCR 架构、知识库架构和反馈学习闭环约束。Hermes 能生成候选和草稿，但不能自动发布正式结果。

+
+ 03 + 11 + 12 + 15 +
+
+
+ +
Build Order
+

推荐开发顺序

+
+
Step 1先定 HermesTaskRequest / HermesTaskResult。
+
Step 2建立手动触发任务 API，经 Orchestrator 路由到 Hermes。
+
Step 3补风险巡检和每日统计的结构化输出。
+
Step 4接入 OCR Mock、知识候选生成、规则草稿生成。
+
Step 5补任务详情展示、错误信息和测试。
+
+ +
Must Deliver
+

今天必须产出的东西

+
+
+

任务调度入口

+
    +
  • 可手动触发至少一个任务资产。
    • +
  • 任务经 Orchestrator 进入 Hermes。
    • +
  • 结束后能更新最近执行时间和状态。
    • +
+
+
+

风险与统计

+
    +
  • 重复报销、金额超标、应收逾期、应付异常付款等风险有结构化输出。
    • +
  • 日报包含报销、报账、应收、应付的关键统计口径。
    • +
  • 每个风险项都要能被业务人员理解和追溯。
    • +
+
+
+

知识候选与规则草稿

+
    +
  • 知识候选默认是 draft，不能自动发布。
    • +
  • 规则草稿保存为 asset_type=rule，状态为 draft。
    • +
  • 两类生成都要写审计日志。
    • +
+
+
+

OCR Mock 与结果展示

+
    +
  • OCR 服务接口和输入输出结构定下来。
    • +
  • 当前阶段允许完全使用 Mock 结果。
    • +
  • 任务详情或运行日志中能直接看到 Hermes 的执行结果。
    • +
+
+
+ +
Acceptance Snapshot
+

验收快照

+
+
任务可触发
至少一个任务可以手动触发，并能查到结构化结果。
+
风险巡检
输出里能看到风险类型、业务对象、触发规则、建议动作和风险等级。
+
候选与草稿
知识候选和规则草稿都能生成，但都不是 active / published 正式状态。
+
可观察性
不用查数据库，也能从任务详情或运行日志判断 Hermes 是否执行成功。
+
+ +
Common Misses
+

这一天最容易漏掉的点

+
    +
  • 只做 Hermes 服务逻辑，不做任务入口和结果展示，最后无法演示。
    • +
  • 能生成知识或规则，但没把状态锁在 draft，会直接越过人工审核边界。
    • +
  • OCR Mock 只返回一段自由文本，不定义结构字段，后面无法和规则或风险逻辑对接。
    • +
+ +
Day 6 的价值是让“后台数字员工”第一次具备可触发、可解释、可留痕的闭环。
+
+ + diff --git a/document/development/agent/agent_week_plan_html/day-7.html b/document/development/agent/agent_week_plan_html/day-7.html new file mode 100644 index 0000000..60331f7 --- /dev/null +++ b/document/development/agent/agent_week_plan_html/day-7.html @@ -0,0 +1,132 @@ + + + + + + Day 7 - 加固、演示和验收 + + + +
+
+ D7Day 7 View +
+ 返回总览 + 周计划原文 + 合并文档原文 +
+
+ +
+ Day 1 + Day 2 + Day 3 + Day 4 + Day 5 + Day 6 + Day 7 +
+ +
+
Hardening
+

Day 7 加固、演示和验收

+

Day 7 不再追求新增大功能，而是把 Day 1 到 Day 6 的链路整理成“可演示、可验收、可继续接手”的状态。没有这一层收口，前面做出来的东西很容易停在“只有作者自己懂”的阶段。

+
+
上游依赖
Day 1 到 Day 6 的全部核心路径。
+
当天输出
回归记录、权限边界、审计和 Trace 补齐、测试记录、演示脚本、交接说明。
+
当天关键
冻结新增需求，只收验收相关缺口。
+
+
+ +
Three-Layer Mapping
+

三层文档映射

+
+
+

路线图

+

周计划要求完成回归、权限补齐、审计补齐、错误态和空态、评测、演示数据、构建和交付说明。

+
day_7_hardening_demo_acceptance.md
+
+
+

执行细则

+

执行层拆成核心链路回归、权限和风险边界、审计和 Trace、前端体验修补、测试补齐、评测集、演示数据、演示脚本和文档收尾。

+
agent week plan/day_7
+
+
+

架构依据

+

主要受整体 README、开发路线图、可观测性和评测集约束。Day 7 的本质是把所有边界和证据讲清楚。

+
+ 00 + 05 + 09 + 10 +
+
+
+ +
Build Order
+

推荐收口顺序

+
+
Step 1先汇总 Day 1 到 Day 6 未完成项，冻结新增需求。
+
Step 2回归核心链路：资产、规则、语义解析、Orchestrator、User Agent、Hermes、Trace、AuditLog。
+
Step 3补权限边界与高风险动作拦截。
+
Step 4补测试、评测、演示数据和前端体验问题。
+
Step 5写演示脚本和交接说明，形成最终交付。
+
+ +
Must Deliver
+

今天必须产出的东西

+
+
+

回归与边界

+
    +
  • 未审核规则不能上线。
    • +
  • 付款、审批、上线等高风险动作都不能绕过确认。
    • +
  • disabled 能力不能被调用。
    • +
+
+
+

审计与 Trace

+
    +
  • 规则保存、审核、上线都能看到 AuditLog。
    • +
  • Hermes 生成知识候选 / 规则草稿有审计。
    • +
  • 任意演示路径都能追到 run_id。
    • +
+
+
+

测试、评测、演示数据

+
    +
  • 后端测试、前端构建、语义评测至少有执行记录。
    • +
  • 报销 / 应收 / 应付 / 风险 / 知识都准备好演示数据。
    • +
  • 失败样例和已知边界要明确写出。
    • +
+
+
+

演示脚本与交接

+
    +
  • 从任务规则中心、规则详情、版本切换、上线拦截，到 User Agent 问答、Hermes 任务、Trace 和审计，都有明确步骤。
    • +
  • 新开发者按脚本能走通一遍。
    • +
+
+
+ +
Acceptance Snapshot
+

最终验收快照

+
+
端到端链路
从规则中心到 User Agent，再到 Hermes 和 Trace，至少有一条完整演示路径可复现。
+
证据完整
AgentRun、ToolCall、AuditLog、测试记录、评测结果和演示脚本都存在。
+
风险边界
MVP 期间不存在绕过人工审核、自动付款、自动上线的暗门路径。
+
可交接性
下一位开发或 Codex 打开文档就能知道已完成、未完成和生产化前必补项。
+
+ +
Common Misses
+

这一天最容易漏掉的点

+
    +
  • 只验证 Happy Path，不回归错误态、空态、禁用态和被权限拦截路径。
    • +
  • 能讲演示，但没有测试记录和已知风险说明，交接质量会很差。
    • +
  • 前 6 天的 TODO 没回写完成状态，导致页面和 Markdown 脱节。
    • +
+ +
Day 7 的目标不是继续堆功能，而是把一周产出变成别人也能运行、理解和接手的系统。
+
+ + diff --git a/document/development/agent/agent_week_plan_html/index.html b/document/development/agent/agent_week_plan_html/index.html new file mode 100644 index 0000000..1877979 --- /dev/null +++ b/document/development/agent/agent_week_plan_html/index.html @@ -0,0 +1,181 @@ + + + + + + Agent Week Plan HTML + + + +
+
+ + A7 + Agent Week HTML + +
+ 周计划总控 + 周计划说明 + 架构目录 +
+
+ +
+
Static Map
+

把 7 天周计划变成可直接浏览的开发视图

+

这一套 HTML 页面不是替代 Markdown，而是把 agent week plan 和 agent plan 的对应关系收成一个稳定入口。每天的路线图和执行清单现在已经并到同一份 daily 文档里。

+
+
+
阅读顺序
+
先总览，再选 Day，再跳转到具体 Markdown 落地执行。
+
+
+
核心视图
+
路线图、执行细则、架构依据三层同时可见。
+
+
+
适用对象
+
Codex 开发、后端开发、前端开发、项目 owner、验收人员。
+
+
+
+ +
How To Use
+

怎么用这套页面

+
+
+

Codex 开发视角

+
    +
  1. 先看今天在哪一天，确认上游依赖和下游交接。
    2. +
  2. 用“两层映射”定位：daily 文档看目标和步骤，架构文档看约束。
    3. +
  3. 按“推荐开发顺序”推进，不跳天，不跨层乱做。
    4. +
  4. 完成后回到原始 Markdown，把 TODO、阻塞、交接更新回文档。
    5. +
+
+
+

人工开发与验收视角

+
    +
  1. 先看每一天的“今日定位”，知道这一天到底产出什么。
    2. +
  2. 再看“今天必须产出的东西”和“验收快照”，确认完成标准。
    3. +
  3. 最后跳转到对应 Markdown，逐条执行或验收。
    4. +
  4. 如果发现跨天阻塞，优先回前一天补地基，而不是在当前天临时兜底。
    5. +
+
+
+ +
Three Layers
+

文档结构一眼看清

+
+
+

1. 周计划路线图

+

定义每天的大方向、交付物和验收门槛。用于排期、对齐和验收。核心入口是 MASTER_TODO.md 和 Day 1 到 Day 7 daily 文档。

+
+ 00_README + MASTER_TODO +
+
+
+

2. 每日执行清单

+

每天的开发目标已经拆到对应 daily 文档中的详细执行清单，直接覆盖模型、字段、接口、服务、前端、测试和验收证据。

+
+ 00_README + MASTER_TODO +
+
+
+

3. 架构依据

+

提供为什么要这么做、协议怎么定、权限和审计边界是什么。它不直接当 TODO，但所有实现都要受它约束。

+
+ 总体架构 + 语义本体 + 观测与 Trace +
+
+
+ +
Seven Days
+

7 天总览

+
+
+

Day 1 基础模型与工程骨架

+

当前状态：已完成（2026-05-11）。先把 Agent 资产、版本、审核、运行日志、审计日志，以及报销 / 应收 / 应付的最小业务数据来源定下来。后面所有能力都站在这一天的模型上。

+
+ 打开日视图 + 周计划 + 合并文档 +
+
+
+

Day 2 任务规则中心联调

+

把规则、技能、MCP、任务从静态 UI 拉到真实后端数据。重点是规则 Markdown、版本切换、审核和上线拦截。

+
+ 打开日视图 + 周计划 + 合并文档 +
+
+
+

Day 3 语义本体 MVP

+

建立 8 字段语义解析协议，让报销、应收、应付、知识查询进入同一结构，给 Orchestrator、User Agent、Hermes 统一消费。

+
+ 打开日视图 + 周计划 + 合并文档 +
+
+
+

Day 4 Orchestrator 运行时

+

把用户消息和定时任务统一接到 Orchestrator，完成 run_id、权限拦截、Agent 路由、ToolCall 和 Trace。

+
+ 打开日视图 + 周计划 + 合并文档 +
+
+
+

Day 5 User Agent MVP

+

面向用户的问答和流程辅助层。做查询、解释、规则引用、草稿生成，但严格不碰自动审批、自动付款和自动上线。

+
+ 打开日视图 + 周计划 + 合并文档 +
+
+
+

Day 6 Hermes MVP

+

后台数字员工层。做任务触发、风险巡检、日报统计、OCR Mock、知识候选、规则草稿，结果都必须可追溯。

+
+ 打开日视图 + 周计划 + 合并文档 +
+
+
+

Day 7 加固、演示和验收

+

不再大扩功能，只做回归、权限边界、审计、Trace、测试、演示脚本和交接收口，让整周产出可跑、可演示、可继续接手。

+
+ 打开日视图 + 周计划 + 合并文档 +
+
+
+ +
Dependency Chain
+

跨天依赖链

+
+
Day 1模型、审计、运行日志、最小业务数据源
+
Day 2把 Day 1 的资产 API 接进规则中心 UI
+
Day 3在 Day 1/2 基础上产出统一语义结构
+
Day 4用 Day 3 的语义结果完成路由与权限
+
Day 5接入 User Agent 问答、解释和草稿
+
Day 6接入 Hermes 任务、巡检和知识/规则候选
+
Day 7统一回归、补日志、做演示和交接
+
+ +
+ 打开顺序建议：Day 1 到 Day 7。真正执行时，仍以原始 Markdown 为准，这套 HTML 负责加速定位和浏览。 +
+
+ + diff --git a/document/development/agent/agent_week_plan_html/styles.css b/document/development/agent/agent_week_plan_html/styles.css new file mode 100644 index 0000000..0db90b9 --- /dev/null +++ b/document/development/agent/agent_week_plan_html/styles.css @@ -0,0 +1,426 @@ +:root { + --bg: #f3ead9; + --bg-deep: #e7d8bc; + --panel: rgba(255, 250, 241, 0.9); + --panel-strong: #fff8ee; + --ink: #1f2a24; + --muted: #64655d; + --line: #dbc8a9; + --accent: #bb5b2c; + --accent-strong: #8d3d1b; + --accent-soft: #f4d9bf; + --teal: #20656d; + --teal-soft: #d8ecee; + --olive: #5f6b3a; + --olive-soft: #e6ecd7; + --shadow: 0 24px 60px rgba(84, 59, 30, 0.12); + --radius-xl: 28px; + --radius-lg: 20px; + --radius-md: 14px; + --max: 1240px; +} + +* { + box-sizing: border-box; +} + +html { + scroll-behavior: smooth; +} + +body { + margin: 0; + font-family: "Trebuchet MS", "Gill Sans", "Lucida Grande", sans-serif; + color: var(--ink); + background: + radial-gradient(circle at top left, rgba(32, 101, 109, 0.14), transparent 26%), + radial-gradient(circle at top right, rgba(187, 91, 44, 0.15), transparent 30%), + linear-gradient(180deg, #f8f0e2 0%, var(--bg) 40%, #efe2cb 100%); +} + +a { + color: inherit; +} + +.shell { + width: min(100% - 40px, var(--max)); + margin: 0 auto; + padding: 28px 0 56px; +} + +.topbar { + display: flex; + align-items: center; + justify-content: space-between; + gap: 16px; + flex-wrap: wrap; + margin-bottom: 18px; +} + +.brand { + display: inline-flex; + align-items: center; + gap: 12px; + text-decoration: none; + font-weight: 700; + letter-spacing: 0.04em; + text-transform: uppercase; + color: var(--accent-strong); +} + +.brand-mark { + display: inline-flex; + align-items: center; + justify-content: center; + width: 42px; + height: 42px; + border-radius: 50%; + background: linear-gradient(135deg, var(--accent), #df9a44); + color: #fff7ef; + box-shadow: 0 14px 30px rgba(187, 91, 44, 0.28); +} + +.quick-links, +.day-nav { + display: flex; + flex-wrap: wrap; + gap: 10px; +} + +.pill { + display: inline-flex; + align-items: center; + justify-content: center; + min-height: 38px; + padding: 10px 14px; + border-radius: 999px; + border: 1px solid rgba(143, 114, 74, 0.22); + background: rgba(255, 248, 238, 0.75); + text-decoration: none; + color: var(--muted); + font-size: 14px; + transition: transform 180ms ease, border-color 180ms ease, background 180ms ease; +} + +.pill:hover, +.pill:focus-visible { + transform: translateY(-1px); + border-color: rgba(187, 91, 44, 0.4); + background: rgba(255, 251, 245, 0.96); + outline: none; +} + +.pill.active { + color: #fff6ef; + border-color: transparent; + background: linear-gradient(135deg, var(--accent-strong), var(--accent)); + box-shadow: 0 14px 24px rgba(141, 61, 27, 0.24); +} + +.hero { + position: relative; + overflow: hidden; + margin-bottom: 22px; + padding: 30px; + border: 1px solid rgba(128, 109, 82, 0.18); + border-radius: var(--radius-xl); + background: + linear-gradient(135deg, rgba(255, 248, 238, 0.95), rgba(247, 236, 216, 0.88)), + var(--panel); + box-shadow: var(--shadow); +} + +.hero::after { + content: ""; + position: absolute; + right: -50px; + top: -50px; + width: 220px; + height: 220px; + border-radius: 50%; + background: radial-gradient(circle, rgba(32, 101, 109, 0.16), transparent 68%); +} + +.hero-badge { + display: inline-flex; + align-items: center; + gap: 8px; + margin-bottom: 12px; + padding: 7px 12px; + border-radius: 999px; + background: var(--accent-soft); + color: var(--accent-strong); + font-size: 13px; + font-weight: 700; + letter-spacing: 0.05em; + text-transform: uppercase; +} + +.hero h1 { + margin: 0; + font-family: "Iowan Old Style", "Palatino Linotype", "Book Antiqua", serif; + font-size: clamp(34px, 5vw, 62px); + line-height: 1.03; +} + +.hero p { + max-width: 880px; + margin: 14px 0 0; + color: var(--muted); + font-size: 18px; + line-height: 1.65; +} + +.hero-meta { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); + gap: 14px; + margin-top: 20px; +} + +.meta-card { + padding: 14px 16px; + border-radius: var(--radius-md); + background: rgba(255, 255, 255, 0.55); + border: 1px solid rgba(132, 109, 83, 0.16); +} + +.meta-label { + margin-bottom: 6px; + color: var(--muted); + font-size: 12px; + font-weight: 700; + letter-spacing: 0.08em; + text-transform: uppercase; +} + +.meta-value { + font-size: 16px; + line-height: 1.45; +} + +.grid { + display: grid; + gap: 18px; +} + +.grid.two { + grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); +} + +.grid.three { + grid-template-columns: repeat(auto-fit, minmax(240px, 1fr)); +} + +.card { + padding: 22px; + border: 1px solid rgba(132, 109, 83, 0.15); + border-radius: var(--radius-lg); + background: var(--panel); + box-shadow: 0 16px 36px rgba(78, 58, 32, 0.08); + animation: rise 420ms ease both; +} + +.card:nth-child(2) { animation-delay: 60ms; } +.card:nth-child(3) { animation-delay: 120ms; } +.card:nth-child(4) { animation-delay: 180ms; } +.card:nth-child(5) { animation-delay: 240ms; } + +.card h2, +.card h3 { + margin: 0 0 10px; + font-family: "Iowan Old Style", "Palatino Linotype", "Book Antiqua", serif; +} + +.card h2 { + font-size: 28px; +} + +.card h3 { + font-size: 22px; +} + +.card p { + margin: 0; + color: var(--muted); + line-height: 1.7; +} + +.section-title { + margin: 28px 0 14px; + font-family: "Iowan Old Style", "Palatino Linotype", "Book Antiqua", serif; + font-size: 28px; +} + +.section-kicker { + margin: 30px 0 8px; + color: var(--accent-strong); + font-size: 13px; + font-weight: 700; + letter-spacing: 0.08em; + text-transform: uppercase; +} + +.list, +.compact-list { + margin: 12px 0 0; + padding-left: 18px; + color: var(--ink); + line-height: 1.72; +} + +.compact-list { + font-size: 15px; +} + +.list li + li, +.compact-list li + li { + margin-top: 8px; +} + +.card-links { + display: flex; + flex-wrap: wrap; + gap: 10px; + margin-top: 16px; +} + +.link-chip { + display: inline-flex; + align-items: center; + gap: 8px; + padding: 10px 13px; + border-radius: 999px; + background: rgba(255, 255, 255, 0.76); + border: 1px solid rgba(132, 109, 83, 0.18); + text-decoration: none; + font-size: 14px; +} + +.tone-warm { + background: linear-gradient(180deg, rgba(244, 217, 191, 0.55), rgba(255, 250, 241, 0.9)); +} + +.tone-teal { + background: linear-gradient(180deg, rgba(216, 236, 238, 0.76), rgba(255, 250, 241, 0.92)); +} + +.tone-olive { + background: linear-gradient(180deg, rgba(230, 236, 215, 0.82), rgba(255, 250, 241, 0.92)); +} + +.tone-accent { + background: linear-gradient(160deg, rgba(141, 61, 27, 0.94), rgba(187, 91, 44, 0.92)); + color: #fff8f1; +} + +.tone-accent p, +.tone-accent .meta-label, +.tone-accent .meta-value, +.tone-accent li { + color: rgba(255, 248, 241, 0.92); +} + +.tone-accent .link-chip, +.tone-accent .pill { + background: rgba(255, 255, 255, 0.14); + border-color: rgba(255, 255, 255, 0.18); + color: #fff8f1; +} + +.timeline { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); + gap: 12px; +} + +.timeline-step { + position: relative; + padding: 16px; + border-radius: var(--radius-md); + border: 1px solid rgba(132, 109, 83, 0.16); + background: rgba(255, 252, 247, 0.84); +} + +.timeline-step strong { + display: block; + margin-bottom: 8px; + font-size: 15px; +} + +.footer { + margin-top: 26px; + padding: 20px 4px 0; + color: var(--muted); + font-size: 14px; +} + +.muted { + color: var(--muted); +} + +.table-like { + display: grid; + gap: 12px; +} + +.row { + display: grid; + grid-template-columns: minmax(120px, 0.9fr) minmax(0, 2.3fr); + gap: 14px; + padding: 14px 16px; + border-radius: var(--radius-md); + border: 1px solid rgba(132, 109, 83, 0.15); + background: rgba(255, 255, 255, 0.56); +} + +.row-label { + font-size: 13px; + font-weight: 700; + letter-spacing: 0.06em; + text-transform: uppercase; + color: var(--accent-strong); +} + +.row-value { + line-height: 1.68; +} + +code { + padding: 1px 6px; + border-radius: 8px; + background: rgba(32, 101, 109, 0.08); + color: var(--teal); + font-family: "Lucida Console", "Courier New", monospace; + font-size: 0.92em; +} + +@keyframes rise { + from { + opacity: 0; + transform: translateY(10px); + } + to { + opacity: 1; + transform: translateY(0); + } +} + +@media (max-width: 760px) { + .shell { + width: min(100% - 24px, var(--max)); + padding-top: 18px; + } + + .hero { + padding: 22px; + } + + .hero p { + font-size: 16px; + } + + .row { + grid-template-columns: 1fr; + } +} diff --git a/document/development/risks/travel-risk-control-standard.md b/document/development/risks/travel-risk-control-standard.md new file mode 100644 index 0000000..0824cbb --- /dev/null +++ b/document/development/risks/travel-risk-control-standard.md @@ -0,0 +1,139 @@ +# 差旅报销风险管控标准（模拟版） + +## 1. 目的 + +本标准用于约束个人报销中的差旅类单据审核，覆盖以下三类核心风险： + +- 行程闭环风险：出发地、目的地、返程地之间是否形成合理链路。 +- 票据地点一致性风险：酒店、交通票据与申报目的地是否一致。 +- 差标超限风险：员工职级对应的交通舱位、火车席别、住宿金额是否超标。 + +本标准先以模拟规则落地到系统，用于 AI 验审与直属领导审批前的自动筛查。 + +## 2. 适用范围 + +- 报销主类型为 `travel / hotel / transport` 的单据。 +- 或者明细附件识别出 `flight_itinerary / train_ticket / hotel_invoice / taxi_receipt / parking_toll_receipt` 的单据。 + +## 3. 基础定义 + +### 3.1 目的地 + +按以下优先级确定本次差旅的“主目的地”： + +1. 用户在报销表单中填写的业务地点 `claim.location` +2. 长途交通票据终点城市 +3. 酒店票据识别出的酒店所在城市 + +### 3.2 行程闭环 + +满足以下任一条件，视为形成合理闭环： + +- 单程票据终点与申报目的地一致。 +- 多段票据按时间顺序首尾衔接。 +- 最后一段票据返回首段出发城市。 + +### 3.3 合理例外说明 + +若出现多城市出差、中转、改签、异地返程、展会高峰导致超标等情况，用户必须在报销事由或费用说明中体现原因。示例关键词： + +- `中转` +- `转机` +- `经停` +- `改签` +- `多地出差` +- `客户临时变更` +- `展会高峰` +- `协议酒店满房` +- `无直达` + +未说明时，系统按高风险处理并退回待补充。 + +## 4. 风险规则矩阵 + +### 4.1 行程闭环规则 + +- 若存在两段及以上长途交通票据，相邻两段的 `上一段终点城市` 与 `下一段起点城市` 必须一致。 +- 若最终到达城市既不是申报目的地，也不是首段出发城市，则判定为高风险。 +- 若识别到多个目的地城市，但事由中未说明多地出差、中转或改签原因，则判定为高风险。 + +处理方式： + +- `高风险`：退回待补充。 +- `中风险`：允许流转，但要求直属领导重点复核。 + +### 4.2 酒店地点一致性规则 + +- 酒店票据识别出的城市，必须属于以下集合之一： + - 申报目的地 + - 长途交通票据中的目的地城市 + - 长途交通票据中的返程前停留城市 +- 若酒店城市与主目的地、交通链路均不一致，则判定为高风险。 + +处理方式： + +- `高风险`：退回待补充，要求说明异地住宿原因或更换票据。 + +### 4.3 职级差旅标准 + +#### 4.3.1 城市分级 + +- 一线：`北京 / 上海 / 广州 / 深圳` +- 新一线 / 重点城市：`杭州 / 南京 / 苏州 / 武汉 / 成都 / 重庆 / 西安 / 天津 / 宁波 / 厦门 / 青岛 / 长沙` +- 其他城市：除以上外的默认城市 + +#### 4.3.2 住宿标准（元 / 晚） + +| 职级带 | 一线 | 重点城市 | 其他城市 | +| --- | ---: | ---: | ---: | +| P1-P3 | 450 | 380 | 320 | +| P4-P5 | 550 | 480 | 380 | +| P6-P7 | 700 | 620 | 520 | +| M1-M2 | 900 | 820 | 720 | +| M3 及以上 / D 序列 | 1200 | 1000 | 900 | + +说明： + +- 若票据中能识别出 `X 晚 / X 间夜`，系统按 `总金额 / 间夜数` 计算每晚金额。 +- 若无法识别间夜数，默认按 1 晚处理。 + +#### 4.3.3 交通标准 + +| 职级带 | 飞机 | 火车 / 高铁 | +| --- | --- | --- | +| P1-P3 | 经济舱 | 二等座 / 硬卧 | +| P4-P5 | 经济舱 | 二等座 / 硬卧 | +| P6-P7 | 超级经济舱及以下 | 一等座 / 软卧及以下 | +| M1-M2 | 商务舱及以下 | 商务座及以下 | +| M3 及以上 / D 序列 | 不做系统硬限制，仍保留人工复核 | + +### 4.4 差标超限处理 + +- 超住宿标准且无说明：`高风险` +- 超住宿标准但有说明：`中风险` +- 飞机舱位或高铁席别超过职级标准且无说明：`高风险` +- 飞机舱位或高铁席别超过职级标准但有说明：`中风险` + +## 5. 系统落地口径 + +### 5.1 票据识别字段 + +系统优先使用以下字段做判断： + +- `route` +- `merchant_name` +- `amount` +- `date` +- OCR 原文中的舱位、席别、间夜数、城市名 + +### 5.2 AI 验审动作 + +- 高风险：提交前拦截，状态切回 `待补充` +- 中风险：允许进入直属领导审批，并附带风险标记 +- 低风险 / 通过：正常流转 + +## 6. 当前实现边界 + +- 城市识别先按常见出差城市做匹配，未覆盖全国全部区县。 +- 住宿标准与交通标准为模拟版，可后续迁移到任务规则中心做可配置化。 +- 本文档为当前开发阶段的执行依据，后续若规则中心启用动态配置，应以规则中心版本为准。