diff --git a/document/development/agent plan/00_README.md b/document/development/agent plan/00_README.md deleted file mode 100644 index 6e061c6..0000000 --- a/document/development/agent plan/00_README.md +++ /dev/null @@ -1,58 +0,0 @@ -# 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 plan/01_overall_architecture.md b/document/development/agent plan/01_overall_architecture.md deleted file mode 100644 index 6d737f0..0000000 --- a/document/development/agent plan/01_overall_architecture.md +++ /dev/null @@ -1,163 +0,0 @@ -# 双 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 plan/02_semantic_ontology.md b/document/development/agent plan/02_semantic_ontology.md deleted file mode 100644 index 9fefedd..0000000 --- a/document/development/agent plan/02_semantic_ontology.md +++ /dev/null @@ -1,457 +0,0 @@ -# 语义本体协议设计 - -## 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 plan/03_agent_responsibilities.md b/document/development/agent plan/03_agent_responsibilities.md deleted file mode 100644 index 6d5382f..0000000 --- a/document/development/agent plan/03_agent_responsibilities.md +++ /dev/null @@ -1,178 +0,0 @@ -# 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 plan/04_orchestrator_and_runtime_flow.md b/document/development/agent plan/04_orchestrator_and_runtime_flow.md deleted file mode 100644 index 6f81628..0000000 --- a/document/development/agent plan/04_orchestrator_and_runtime_flow.md +++ /dev/null @@ -1,357 +0,0 @@ -# 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 -``` - -### 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: 通知财务风控组 -``` - -## 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 plan/05_development_roadmap.md b/document/development/agent plan/05_development_roadmap.md deleted file mode 100644 index 3727b47..0000000 --- a/document/development/agent plan/05_development_roadmap.md +++ /dev/null @@ -1,458 +0,0 @@ -# 分阶段开发计划 - -## 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 plan/06_data_contracts_and_governance.md b/document/development/agent plan/06_data_contracts_and_governance.md deleted file mode 100644 index 0a0b3ff..0000000 --- a/document/development/agent plan/06_data_contracts_and_governance.md +++ /dev/null @@ -1,433 +0,0 @@ -# 数据契约与治理要求 - -## 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 -} -``` - -响应： - -```json -{ - "run_id": "", - "status": "accepted" -} -``` - -## 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 plan/07_capability_registry.md b/document/development/agent plan/07_capability_registry.md deleted file mode 100644 index 2923f59..0000000 --- a/document/development/agent plan/07_capability_registry.md +++ /dev/null @@ -1,198 +0,0 @@ -# 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 plan/08_permission_confirmation.md b/document/development/agent plan/08_permission_confirmation.md deleted file mode 100644 index 0414b02..0000000 --- a/document/development/agent plan/08_permission_confirmation.md +++ /dev/null @@ -1,214 +0,0 @@ -# 权限与确认引擎 - -## 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 plan/09_observability_and_trace.md b/document/development/agent plan/09_observability_and_trace.md deleted file mode 100644 index b21fac3..0000000 --- a/document/development/agent plan/09_observability_and_trace.md +++ /dev/null @@ -1,186 +0,0 @@ -# 可观测性与 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 plan/10_evaluation_and_testset.md b/document/development/agent plan/10_evaluation_and_testset.md deleted file mode 100644 index 4be7c37..0000000 --- a/document/development/agent plan/10_evaluation_and_testset.md +++ /dev/null @@ -1,198 +0,0 @@ -# 评测集与质量控制 - -## 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 plan/11_ocr_invoice_architecture.md b/document/development/agent plan/11_ocr_invoice_architecture.md deleted file mode 100644 index f21fc3b..0000000 --- a/document/development/agent plan/11_ocr_invoice_architecture.md +++ /dev/null @@ -1,376 +0,0 @@ -# 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 plan/12_llm_wiki_knowledge_architecture.md b/document/development/agent plan/12_llm_wiki_knowledge_architecture.md deleted file mode 100644 index e208bcc..0000000 --- a/document/development/agent plan/12_llm_wiki_knowledge_architecture.md +++ /dev/null @@ -1,148 +0,0 @@ -# LLM Wiki 知识库架构 - -## 1. 定位 - -LLM Wiki 不是简单的文件库。 - -它是给 Agent 使用的知识底座，负责把制度、FAQ、审批经验、规则说明转成可检索、可引用、可版本化的知识。 - -## 2. 总体链路 - -```text -文档上传 - ↓ -格式解析 - ↓ -正文抽取 - ↓ -分块 Chunking - ↓ -元数据标注 - ↓ -向量索引 - ↓ -条款抽取 - ↓ -知识候选 - ↓ -人工审核 - ↓ -发布 Wiki - ↓ -Agent 检索引用 -``` - -## 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 页" -} -``` - -该结果不直接变成规则，先进入规则候选池。 - -## 6. Wiki 发布流程 - -```text -草稿知识 - ↓ -Hermes 生成候选 - ↓ -知识管理员审核 - ↓ -发布 - ↓ -Agent 可检索 -``` - -## 7. 与 User Agent 的关系 - -User Agent 用 Wiki： - -- 回答制度问题。 -- 给风险解释提供条款依据。 -- 给审批意见生成引用。 -- 帮用户理解流程。 - -## 8. 与 Hermes 的关系 - -Hermes 用 Wiki： - -- 每日知识候选生成。 -- 发现制度与规则不一致。 -- 生成规则优化建议。 -- 生成 FAQ 候选。 - -## 9. 数据模型建议 - -```text -knowledge_documents -knowledge_chunks -knowledge_embeddings -knowledge_candidates -knowledge_reviews -knowledge_versions -``` - -## 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 plan/13_rule_formation_lifecycle.md b/document/development/agent plan/13_rule_formation_lifecycle.md deleted file mode 100644 index 04ef102..0000000 --- a/document/development/agent plan/13_rule_formation_lifecycle.md +++ /dev/null @@ -1,126 +0,0 @@ -# 规则形成生命周期 - -## 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" -} -``` - -## 4. 规则 Markdown 推荐结构 - -```markdown -# 规则名称 - -## 目标 - -## 适用范围 - -## 输入字段 - -## 判断规则 - -## 输出 - -## 测试样例 - -## 管理员备注 -``` - -## 5. 审核要求 - -规则上线必须满足： - -- 有审核人。 -- 有版本。 -- 有测试样例。 -- 有来源依据。 -- 有回滚方案。 - -## 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 plan/14_financial_document_canonical_model.md b/document/development/agent plan/14_financial_document_canonical_model.md deleted file mode 100644 index 4a4ede2..0000000 --- a/document/development/agent plan/14_financial_document_canonical_model.md +++ /dev/null @@ -1,646 +0,0 @@ -# 财务单据标准模型 - -## 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 plan/15_feedback_learning_loop.md b/document/development/agent plan/15_feedback_learning_loop.md deleted file mode 100644 index 471aa43..0000000 --- a/document/development/agent plan/15_feedback_learning_loop.md +++ /dev/null @@ -1,119 +0,0 @@ -# 反馈闭环与持续学习 - -## 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 week plan/00_README.md b/document/development/agent week plan/00_README.md deleted file mode 100644 index 8099ff4..0000000 --- a/document/development/agent week plan/00_README.md +++ /dev/null @@ -1,77 +0,0 @@ -# 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 week plan/MASTER_TODO.md b/document/development/agent week plan/MASTER_TODO.md deleted file mode 100644 index cbdc81b..0000000 --- a/document/development/agent week plan/MASTER_TODO.md +++ /dev/null @@ -1,73 +0,0 @@ -# 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 week plan/day_1_foundation_models.md b/document/development/agent week plan/day_1_foundation_models.md deleted file mode 100644 index 6d932de..0000000 --- a/document/development/agent week plan/day_1_foundation_models.md +++ /dev/null @@ -1,221 +0,0 @@ -# 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 week plan/day_2_rule_center_integration.md b/document/development/agent week plan/day_2_rule_center_integration.md deleted file mode 100644 index 5ba8c66..0000000 --- a/document/development/agent week plan/day_2_rule_center_integration.md +++ /dev/null @@ -1,296 +0,0 @@ -# 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 week plan/day_3_semantic_ontology_mvp.md b/document/development/agent week plan/day_3_semantic_ontology_mvp.md deleted file mode 100644 index bb48609..0000000 --- a/document/development/agent week plan/day_3_semantic_ontology_mvp.md +++ /dev/null @@ -1,304 +0,0 @@ -# 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 week plan/day_4_orchestrator_runtime.md b/document/development/agent week plan/day_4_orchestrator_runtime.md deleted file mode 100644 index 0cc3152..0000000 --- a/document/development/agent week plan/day_4_orchestrator_runtime.md +++ /dev/null @@ -1,254 +0,0 @@ -# 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 week plan/day_5_user_agent_mvp.md b/document/development/agent week plan/day_5_user_agent_mvp.md deleted file mode 100644 index 68e0766..0000000 --- a/document/development/agent week plan/day_5_user_agent_mvp.md +++ /dev/null @@ -1,284 +0,0 @@ -# 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 week plan/day_6_hermes_mvp.md b/document/development/agent week plan/day_6_hermes_mvp.md deleted file mode 100644 index 5559587..0000000 --- a/document/development/agent week plan/day_6_hermes_mvp.md +++ /dev/null @@ -1,230 +0,0 @@ -# Day 6：Hermes MVP - -## 今天的大开发点 - -实现 Hermes 数字员工的最小闭环。Hermes 负责后台内循环：定时巡检、统计日报、风险预警、知识维护、规则草稿形成。 - -## 为什么第六天做这个 - -Hermes 依赖前几天已经建立的资产、规则、语义、Orchestrator、Trace 和权限体系。放在第六天做，可以避免它变成孤立脚本。 - -## 今天主要交付 - -- 任务资产调度入口。 -- 手动触发任务 API。 -- 每日风险巡检。 -- 每日报销、报账、账款统计。 -- OCR Mock 接入点。 -- 知识候选条目生成。 -- 规则草稿生成。 -- 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 深度集成。 -- 不做自动发布知识。 -- 不做自动上线规则。 - -## 详细执行清单 - -以下内容为合并后的详细执行清单。 - -## 0. 开始前检查 - -- [ ] 确认任务资产 `asset_type=task` 可查询。 -- [ ] 确认 Orchestrator 能处理 `source=schedule`。 -- [ ] 确认 Hermes 占位服务可被调用。 -- [ ] 确认 AgentRun 和 ToolCall 可记录。 -- [ ] 确认是否已有后台任务框架。 -- [ ] 如果没有后台任务框架，先用手动触发 API 模拟定时执行。 - -## 1. Hermes 输入输出 - -- [ ] 定义 `HermesTaskRequest`。 -- [ ] 请求包含 `run_id`。 -- [ ] 请求包含 `task_asset_id`。 -- [ ] 请求包含 `task_type`。 -- [ ] 请求包含 `schedule_time`。 -- [ ] 请求包含 `context_json`。 -- [ ] 定义 `HermesTaskResult`。 -- [ ] 响应包含 `summary`。 -- [ ] 响应包含 `risk_items`。 -- [ ] 响应包含 `statistics`。 -- [ ] 响应包含 `knowledge_updates`。 -- [ ] 响应包含 `draft_rules`。 -- [ ] 响应包含 `next_actions`。 - -验收证据： - -- [ ] Hermes 响应能被任务详情或运行日志展示。 - -## 2. 任务调度入口 - -- [ ] 新增手动触发任务 API。 -- [ ] API 参数支持任务资产 ID。 -- [ ] API 调用 Orchestrator，source 为 `schedule`。 -- [ ] Orchestrator 路由到 Hermes。 -- [ ] Hermes 执行结果写入 AgentRun。 -- [ ] 任务执行失败时写入错误。 -- [ ] 任务执行结束后更新任务最近执行时间。 -- [ ] 任务执行结束后更新任务最近执行状态。 - -验收证据： - -- [ ] 可以手动触发一次 Hermes 任务并看到运行结果。 - -## 3. 每日风险巡检 - -- [ ] 实现重复报销巡检。 -- [ ] 实现金额超标巡检。 -- [ ] 实现发票异常巡检占位。 -- [ ] 实现应收逾期巡检。 -- [ ] 实现应付异常付款巡检。 -- [ ] 每个风险项包含风险类型。 -- [ ] 每个风险项包含业务对象。 -- [ ] 每个风险项包含触发规则。 -- [ ] 每个风险项包含建议动作。 -- [ ] 每个风险项包含风险等级。 - -验收证据： - -- [ ] 风险巡检结果可以被用户理解和追溯。 - -## 4. 每日统计 - -- [ ] 统计当日报销单数量。 -- [ ] 统计当日报销金额。 -- [ ] 统计当日报账数量。 -- [ ] 统计当日报账金额。 -- [ ] 统计应收新增金额。 -- [ ] 统计应收逾期金额。 -- [ ] 统计应付待付金额。 -- [ ] 统计应付逾期金额。 -- [ ] 输出日报摘要。 - -验收证据： - -- [ ] Hermes 能生成一份每日财务摘要。 - -## 5. OCR 接入点 - -- [ ] 原始票据先落 `document_assets` 和 `document_asset_versions`，不直接以内存临时文件参与流程。 -- [ ] 建立 OCR 识别服务接口。 -- [ ] 定义发票识别输入结构。 -- [ ] 定义发票识别输出结构。 -- [ ] 输出结构包含发票号。 -- [ ] 输出结构包含开票日期。 -- [ ] 输出结构包含金额。 -- [ ] 输出结构包含税额。 -- [ ] 输出结构包含销售方。 -- [ ] 输出结构包含购买方。 -- [ ] 输出结构包含置信度。 -- [ ] OCR 输入可通过 `storage_key` 或等价文件定位字段读取原件。 -- [ ] 当前阶段允许使用 Mock 结果。 -- [ ] OCR 调用写入 ToolCall。 - -验收证据： - -- [ ] Hermes 风险巡检中可以调用 OCR Mock。 - -## 6. 知识库维护 - -- [ ] 建立知识条目写入服务。 -- [ ] Hermes 可以生成知识候选条目。 -- [ ] 候选条目包含标题。 -- [ ] 候选条目包含正文。 -- [ ] 候选条目包含来源。 -- [ ] 候选条目包含适用场景。 -- [ ] 候选条目默认状态为 `draft`。 -- [ ] 知识条目不能自动发布。 -- [ ] 知识条目写入审计日志。 - -验收证据： - -- [ ] Hermes 可以生成待审核知识条目。 - -## 7. 规则草稿形成 - -- [ ] Hermes 可以根据风险巡检结果生成规则草稿。 -- [ ] 规则草稿保存为 `asset_type=rule`。 -- [ ] 规则草稿状态为 `draft`。 -- [ ] 规则草稿包含 Markdown 内容。 -- [ ] 规则草稿包含生成原因。 -- [ ] 规则草稿包含关联风险样例。 -- [ ] 规则草稿不能自动上线。 -- [ ] 规则草稿需要审核人。 -- [ ] 规则草稿写入审计日志。 - -验收证据： - -- [ ] Hermes 生成的新规则出现在规则列表中，但不是 active。 - -## 8. Hermes 页面或日志展示 - -- [ ] 任务详情能看到最近执行结果。 -- [ ] 任务详情能手动触发执行。 -- [ ] 任务详情能看到风险项数量。 -- [ ] 任务详情能看到日报摘要。 -- [ ] 任务详情能看到知识候选数量。 -- [ ] 任务详情能看到规则草稿数量。 -- [ ] 运行 Trace 能看到 Hermes 步骤。 -- [ ] 错误时展示错误原因。 - -验收证据： - -- [ ] 不查数据库也能判断 Hermes 是否执行成功。 - -## 9. 测试 - -- [ ] 测试手动触发任务。 -- [ ] 测试 Orchestrator 路由到 Hermes。 -- [ ] 测试风险巡检输出。 -- [ ] 测试日报统计输出。 -- [ ] 测试 OCR Mock 调用。 -- [ ] 测试知识候选写入。 -- [ ] 测试规则草稿生成。 -- [ ] 测试 Hermes 异常写入 AgentRun。 - -验收证据： - -- [ ] Hermes 核心测试通过。 - -## 10. Day 6 验收 - -- [ ] Hermes 可被 Orchestrator 调用。 -- [ ] 至少一个任务可以手动触发。 -- [ ] 风险巡检有结构化结果。 -- [ ] 每日统计有结构化结果。 -- [ ] OCR Mock 接入点可用。 -- [ ] 知识候选可生成。 -- [ ] 规则草稿可生成且不能自动上线。 -- [ ] 任务详情或运行日志能展示结果。 -- [ ] 所有完成项已用 `[x] ~~...~~` 标记。 - -## 阻塞记录 - -- [ ] 暂无。 - -## 日终交接 - -- [ ] 写明 Hermes 已支持任务类型。 -- [ ] 写明 OCR 当前是真实还是 Mock。 -- [ ] 写明生成的知识和规则草稿状态。 -- [ ] 写明 Day 7 需要重点回归的路径。 diff --git a/document/development/agent week plan/day_7_hardening_demo_acceptance.md b/document/development/agent week plan/day_7_hardening_demo_acceptance.md deleted file mode 100644 index 4146d5d..0000000 --- a/document/development/agent week plan/day_7_hardening_demo_acceptance.md +++ /dev/null @@ -1,260 +0,0 @@ -# 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_week_plan_html/day-1.html b/document/development/agent_week_plan_html/day-1.html deleted file mode 100644 index c215609..0000000 --- a/document/development/agent_week_plan_html/day-1.html +++ /dev/null @@ -1,137 +0,0 @@ - - - - - - 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_week_plan_html/day-2.html b/document/development/agent_week_plan_html/day-2.html deleted file mode 100644 index 0cea4d5..0000000 --- a/document/development/agent_week_plan_html/day-2.html +++ /dev/null @@ -1,132 +0,0 @@ - - - - - - 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_week_plan_html/day-3.html b/document/development/agent_week_plan_html/day-3.html deleted file mode 100644 index 7946f9b..0000000 --- a/document/development/agent_week_plan_html/day-3.html +++ /dev/null @@ -1,132 +0,0 @@ - - - - - - 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_week_plan_html/day-4.html b/document/development/agent_week_plan_html/day-4.html deleted file mode 100644 index 2307dc0..0000000 --- a/document/development/agent_week_plan_html/day-4.html +++ /dev/null @@ -1,133 +0,0 @@ - - - - - - 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_week_plan_html/day-5.html b/document/development/agent_week_plan_html/day-5.html deleted file mode 100644 index 2ccde41..0000000 --- a/document/development/agent_week_plan_html/day-5.html +++ /dev/null @@ -1,133 +0,0 @@ - - - - - - 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_week_plan_html/day-6.html b/document/development/agent_week_plan_html/day-6.html deleted file mode 100644 index 178fe9f..0000000 --- a/document/development/agent_week_plan_html/day-6.html +++ /dev/null @@ -1,133 +0,0 @@ - - - - - - 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_week_plan_html/day-7.html b/document/development/agent_week_plan_html/day-7.html deleted file mode 100644 index 60331f7..0000000 --- a/document/development/agent_week_plan_html/day-7.html +++ /dev/null @@ -1,132 +0,0 @@ - - - - - - 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_week_plan_html/index.html b/document/development/agent_week_plan_html/index.html deleted file mode 100644 index 1877979..0000000 --- a/document/development/agent_week_plan_html/index.html +++ /dev/null @@ -1,181 +0,0 @@ - - - - - - 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_week_plan_html/styles.css b/document/development/agent_week_plan_html/styles.css deleted file mode 100644 index 0db90b9..0000000 --- a/document/development/agent_week_plan_html/styles.css +++ /dev/null @@ -1,426 +0,0 @@ -: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/server/src/app/api/v1/endpoints/knowledge.py b/server/src/app/api/v1/endpoints/knowledge.py index 0077f6e..f8cfd46 100644 --- a/server/src/app/api/v1/endpoints/knowledge.py +++ b/server/src/app/api/v1/endpoints/knowledge.py @@ -1,21 +1,33 @@ from __future__ import annotations +from datetime import UTC, datetime from typing import Annotated from fastapi import APIRouter, Body, Depends, HTTPException, Query, status from fastapi.responses import FileResponse +from sqlalchemy import select +from sqlalchemy.orm import Session -from app.api.deps import CurrentUserContext, get_current_user, require_admin_user +from app.api.deps import CurrentUserContext, get_current_user, get_db, require_admin_user +from app.core.agent_enums import AgentName, AgentPermissionLevel, AgentRunSource, AgentRunStatus +from app.models.agent_asset import AgentAsset from app.schemas.common import ErrorResponse from app.schemas.knowledge import ( KnowledgeActionResponse, KnowledgeDocumentDetailRead, KnowledgeLibraryRead, + LlmWikiDocumentDetailRead, + LlmWikiIndexRead, + LlmWikiSummaryUpdateWrite, KnowledgeOnlyOfficeCallbackRead, KnowledgeOnlyOfficeCallbackWrite, KnowledgeOnlyOfficeConfigRead, + LlmWikiSyncRead, + LlmWikiSyncWrite, ) +from app.services.agent_runs import AgentRunService from app.services.knowledge import KnowledgeService +from app.services.llm_wiki import LlmWikiService router = APIRouter(prefix="/knowledge") @@ -38,6 +50,176 @@ def get_knowledge_library( return KnowledgeService().list_library() +@router.get( + "/llm-wiki", + response_model=LlmWikiIndexRead, + summary="查询 LLM Wiki 索引", + description="返回知识库解析目录中的文档索引和同步次数，仅供管理员查看知识候选与规则候选草稿。", + responses={ + status.HTTP_401_UNAUTHORIZED: { + "model": ErrorResponse, + "description": "未提供知识库访问用户头。", + }, + status.HTTP_403_FORBIDDEN: { + "model": ErrorResponse, + "description": "只有管理员可以查看 LLM Wiki 草稿内容。", + }, + }, +) +def get_llm_wiki_index( + _: Annotated[CurrentUserContext, Depends(require_admin_user)], + db: Annotated[Session, Depends(get_db)], +) -> LlmWikiIndexRead: + return LlmWikiService(db).get_index() + + +@router.get( + "/llm-wiki/documents/{document_id}", + response_model=LlmWikiDocumentDetailRead, + summary="读取 LLM Wiki 文档解析结果", + description="返回指定知识文档的解析文本、分块、知识候选与规则候选，仅供管理员查看。", + responses={ + status.HTTP_401_UNAUTHORIZED: { + "model": ErrorResponse, + "description": "未提供知识库访问用户头。", + }, + status.HTTP_403_FORBIDDEN: { + "model": ErrorResponse, + "description": "只有管理员可以查看 LLM Wiki 草稿内容。", + }, + status.HTTP_404_NOT_FOUND: { + "model": ErrorResponse, + "description": "指定文档尚未生成 LLM Wiki。", + }, + }, +) +def get_llm_wiki_document_detail( + document_id: str, + _: Annotated[CurrentUserContext, Depends(require_admin_user)], + db: Annotated[Session, Depends(get_db)], +) -> LlmWikiDocumentDetailRead: + try: + return LlmWikiService(db).get_document_detail(document_id) + except FileNotFoundError as exc: + raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="指定文档尚未生成 LLM Wiki。") from exc + + +@router.patch( + "/llm-wiki/documents/{document_id}", + response_model=LlmWikiDocumentDetailRead, + summary="更新 LLM Wiki 知识总结", + description="管理员可修改指定知识文档的 LLM Wiki 知识总结预览，不直接改动原始文件。", + responses={ + status.HTTP_401_UNAUTHORIZED: { + "model": ErrorResponse, + "description": "未提供知识库访问用户头。", + }, + status.HTTP_403_FORBIDDEN: { + "model": ErrorResponse, + "description": "只有管理员可以修改 LLM Wiki 草稿内容。", + }, + status.HTTP_404_NOT_FOUND: { + "model": ErrorResponse, + "description": "指定文档尚未生成 LLM Wiki。", + }, + }, +) +def update_llm_wiki_document_summary( + document_id: str, + payload: LlmWikiSummaryUpdateWrite, + _: Annotated[CurrentUserContext, Depends(require_admin_user)], + db: Annotated[Session, Depends(get_db)], +) -> LlmWikiDocumentDetailRead: + try: + return LlmWikiService(db).update_document_summary(document_id, payload) + except FileNotFoundError as exc: + raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="指定文档尚未生成 LLM Wiki。") from exc + except ValueError as exc: + raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc + + +@router.post( + "/llm-wiki/sync", + response_model=LlmWikiSyncRead, + summary="触发 Hermes 形成 LLM Wiki 与规则草稿", + description="按知识库文档变化情况增量触发系统 Hermes，形成知识候选和规则草稿。", + responses={ + status.HTTP_401_UNAUTHORIZED: { + "model": ErrorResponse, + "description": "未提供知识库访问用户头。", + }, + status.HTTP_403_FORBIDDEN: { + "model": ErrorResponse, + "description": "只有管理员可以触发 LLM Wiki 同步。", + }, + }, +) +def sync_llm_wiki( + payload: LlmWikiSyncWrite, + current_user: Annotated[CurrentUserContext, Depends(require_admin_user)], + db: Annotated[Session, Depends(get_db)], +) -> LlmWikiSyncRead: + run_service = AgentRunService(db) + task_asset = db.scalar( + select(AgentAsset).where(AgentAsset.code == "task.hermes.llm_wiki_rule_formation") + ) + run = run_service.create_run( + agent=AgentName.HERMES.value, + source=AgentRunSource.SCHEDULE.value, + user_id=current_user.username, + task_id=task_asset.id if task_asset is not None else None, + permission_level=AgentPermissionLevel.READ.value, + status=AgentRunStatus.RUNNING.value, + result_summary="Hermes 正在形成 LLM Wiki 与规则草稿。", + ) + + try: + result = LlmWikiService(db).sync_folder( + folder=payload.folder, + current_user=current_user, + document_ids=payload.document_ids, + force=payload.force, + ) + run_service.record_tool_call( + run_id=run.run_id, + tool_type="llm", + tool_name="system_hermes_llm_wiki_sync", + request_json=payload.model_dump(), + response_json=result.model_dump(), + status="succeeded", + duration_ms=0, + ) + run_service.update_run( + run.run_id, + status=AgentRunStatus.SUCCEEDED.value, + result_summary=result.summary, + finished_at=datetime.now(UTC), + ) + return result + except Exception as exc: + run_service.record_tool_call( + run_id=run.run_id, + tool_type="llm", + tool_name="system_hermes_llm_wiki_sync", + request_json=payload.model_dump(), + response_json={"error": str(exc)}, + status="failed", + duration_ms=0, + error_message=str(exc), + ) + run_service.update_run( + run.run_id, + status=AgentRunStatus.FAILED.value, + error_message=str(exc), + finished_at=datetime.now(UTC), + ) + if isinstance(exc, ValueError): + raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc + if isinstance(exc, FileNotFoundError): + raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc + raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(exc)) from exc + + @router.get( "/documents/{document_id}", response_model=KnowledgeDocumentDetailRead, diff --git a/server/src/app/schemas/knowledge.py b/server/src/app/schemas/knowledge.py index 6839a4a..a3e132b 100644 --- a/server/src/app/schemas/knowledge.py +++ b/server/src/app/schemas/knowledge.py @@ -1,5 +1,6 @@ -from __future__ import annotations - +from __future__ import annotations + +from datetime import datetime from typing import Any from pydantic import BaseModel, ConfigDict, Field @@ -28,17 +29,18 @@ class KnowledgePreviewPageRead(BaseModel): blocks: list[KnowledgePreviewBlockRead] = Field(default_factory=list) -class KnowledgeDocumentRead(BaseModel): - id: str - name: str - folder: str - tag: str - time: str - version: str - state: str - stateTone: str - owner: str - icon: str +class KnowledgeDocumentRead(BaseModel): + id: str + name: str + folder: str + tag: str + time: str + version: str + stateCode: int = 1 + state: str + stateTone: str + owner: str + icon: str fileType: str fileTypeLabel: str summary: str @@ -75,6 +77,106 @@ class KnowledgeLibraryRead(BaseModel): documents: list[KnowledgeDocumentRead] = Field(default_factory=list) -class KnowledgeActionResponse(BaseModel): - ok: bool = True - detail: str +class KnowledgeActionResponse(BaseModel): + ok: bool = True + detail: str + + +class LlmWikiChunkRead(BaseModel): + chunk_id: str + title: str + content: str + source_page: int | None = None + word_count: int = 0 + tags: list[str] = Field(default_factory=list) + + +class LlmWikiKnowledgeCandidateRead(BaseModel): + candidate_id: str + title: str + content: str + domain: str = "expense" + scenario: str = "reimbursement_policy" + tags: list[str] = Field(default_factory=list) + source_document_id: str + source_document_name: str + source_chunk_ids: list[str] = Field(default_factory=list) + evidence: list[str] = Field(default_factory=list) + confidence: float = 0.0 + status: str = "draft" + created_by: str = "hermes" + created_at: datetime | None = None + + +class LlmWikiRuleCandidateRead(BaseModel): + candidate_id: str + source_type: str = "policy_document" + template_key: str + template_label: str + domain: str = "expense" + scenario: str = "reimbursement_policy" + suggested_rule_name: str + summary: str = "" + template_sections: dict[str, Any] = Field(default_factory=dict) + rule_markdown_draft: str + runtime_rule: dict[str, Any] = Field(default_factory=dict) + evidence: list[str] = Field(default_factory=list) + confidence: float = 0.0 + source_document_id: str + source_document_name: str + source_chunk_ids: list[str] = Field(default_factory=list) + generated_asset_id: str | None = None + generated_asset_code: str | None = None + generated_version: str | None = None + validation_status: str = "valid" + validation_errors: list[str] = Field(default_factory=list) + status: str = "draft" + created_by: str = "hermes" + created_at: datetime | None = None + + +class LlmWikiDocumentRead(BaseModel): + document_id: str + document_name: str + folder: str + document_version: str = "v1.0" + checksum: str = "" + extracted_text_path: str + chunk_count: int = 0 + knowledge_candidate_count: int = 0 + rule_candidate_count: int = 0 + updated_at: datetime | None = None + + +class LlmWikiDocumentDetailRead(LlmWikiDocumentRead): + knowledge_summary_markdown: str = "" + chunks: list[LlmWikiChunkRead] = Field(default_factory=list) + knowledge_candidates: list[LlmWikiKnowledgeCandidateRead] = Field(default_factory=list) + rule_candidates: list[LlmWikiRuleCandidateRead] = Field(default_factory=list) + + +class LlmWikiIndexRead(BaseModel): + documents: list[LlmWikiDocumentRead] = Field(default_factory=list) + sync_run_count: int = 0 + + +class LlmWikiSyncWrite(BaseModel): + folder: str = Field(default="报销制度", min_length=1) + document_ids: list[str] = Field(default_factory=list) + force: bool = False + + +class LlmWikiSyncRead(BaseModel): + ok: bool = True + run_id: str + folder: str + document_count: int = 0 + knowledge_candidate_count: int = 0 + rule_candidate_count: int = 0 + generated_rule_count: int = 0 + generated_rule_asset_ids: list[str] = Field(default_factory=list) + summary: str = "" + + +class LlmWikiSummaryUpdateWrite(BaseModel): + knowledge_summary_markdown: str = Field(min_length=1) diff --git a/server/src/app/services/knowledge.py b/server/src/app/services/knowledge.py index e075d67..e2dd2d7 100644 --- a/server/src/app/services/knowledge.py +++ b/server/src/app/services/knowledge.py @@ -1,13 +1,15 @@ from __future__ import annotations -import hashlib -import json -import mimetypes -import re -from dataclasses import dataclass -from datetime import UTC, datetime -from pathlib import Path -from typing import Any +import hashlib +import json +import mimetypes +import re +import shutil +import subprocess +from dataclasses import dataclass +from datetime import UTC, datetime +from pathlib import Path +from typing import Any from urllib.request import Request, urlopen from uuid import uuid4 from xml.etree import ElementTree @@ -16,8 +18,8 @@ from zipfile import BadZipFile, ZipFile import jwt from app.api.deps import CurrentUserContext -from app.core.config import get_settings -from app.core.logging import get_logger +from app.core.config import get_settings +from app.core.logging import get_logger from app.schemas.knowledge import ( KnowledgeDocumentDetailRead, KnowledgeDocumentRead, @@ -64,7 +66,20 @@ IMAGE_EXTENSIONS = {"png", "jpg", "jpeg", "gif", "bmp", "webp", "svg"} ARCHIVE_EXTENSIONS = {"zip", "rar", "7z"} STRUCTURED_PREVIEW_EXTENSIONS = {"docx", "xlsx", "pptx"} | TEXT_EXTENSIONS INLINE_PREVIEW_EXTENSIONS = {"pdf"} | IMAGE_EXTENSIONS -ONLYOFFICE_EDITABLE_EXTENSIONS = {"docx", "xlsx", "pptx"} +ONLYOFFICE_EDITABLE_EXTENSIONS = {"docx", "xlsx", "pptx"} +KNOWLEDGE_INGEST_SYNC_STALE_SECONDS = 90 + +KNOWLEDGE_INGEST_STATUS_PUBLISHED = 1 +KNOWLEDGE_INGEST_STATUS_SYNCING = 2 +KNOWLEDGE_INGEST_STATUS_INGESTED = 3 +KNOWLEDGE_INGEST_STATUS_FAILED = 4 + +KNOWLEDGE_INGEST_STATUS_META = { + KNOWLEDGE_INGEST_STATUS_PUBLISHED: ("待归纳", "muted"), + KNOWLEDGE_INGEST_STATUS_SYNCING: ("正归纳", "warning"), + KNOWLEDGE_INGEST_STATUS_INGESTED: ("已归纳", "success"), + KNOWLEDGE_INGEST_STATUS_FAILED: ("归纳失败", "danger"), +} @dataclass(slots=True) @@ -78,24 +93,40 @@ def prepare_knowledge_library() -> None: KnowledgeService().ensure_library_ready() -class KnowledgeService: - def __init__(self, storage_root: Path | None = None) -> None: - settings = get_settings() - self.storage_root = Path(storage_root or settings.resolved_storage_root_dir) - self.library_root = self.storage_root / "knowledge" - self.index_path = self.library_root / ".index.json" - - def ensure_library_ready(self) -> None: - self.library_root.mkdir(parents=True, exist_ok=True) - for folder_name in FIXED_KNOWLEDGE_FOLDERS: - (self.library_root / folder_name).mkdir(parents=True, exist_ok=True) - - if not self.index_path.exists(): - self._save_index({"version": 1, "documents": []}) - - index = self._load_index() - if self._reconcile_index(index): - self._save_index(index) +class KnowledgeService: + def __init__(self, storage_root: Path | None = None) -> None: + settings = get_settings() + self.storage_root = Path(storage_root or settings.resolved_storage_root_dir) + self.library_root = self.storage_root / "knowledge" + self.index_path = self.library_root / ".index.json" + self.llm_wiki_root = self.library_root / ".llm_wiki" + self.llm_wiki_documents_root = self.llm_wiki_root / "documents" + self.llm_wiki_index_path = self.llm_wiki_root / "index.json" + self.llm_wiki_sync_runs_path = self.llm_wiki_root / "sync_runs.json" + + def ensure_library_ready(self) -> None: + self.library_root.mkdir(parents=True, exist_ok=True) + for folder_name in FIXED_KNOWLEDGE_FOLDERS: + (self.library_root / folder_name).mkdir(parents=True, exist_ok=True) + + self.llm_wiki_documents_root.mkdir(parents=True, exist_ok=True) + + if not self.index_path.exists(): + self._save_index({"version": 1, "documents": []}) + if not self.llm_wiki_index_path.exists(): + self.llm_wiki_index_path.write_text( + json.dumps({"documents": []}, ensure_ascii=False, indent=2), + encoding="utf-8", + ) + if not self.llm_wiki_sync_runs_path.exists(): + self.llm_wiki_sync_runs_path.write_text( + json.dumps({"runs": []}, ensure_ascii=False, indent=2), + encoding="utf-8", + ) + + index = self._load_index() + if self._reconcile_index(index): + self._save_index(index) def list_library(self) -> KnowledgeLibraryRead: documents = self._load_documents() @@ -109,21 +140,23 @@ class KnowledgeService: ] return KnowledgeLibraryRead(folders=folders, documents=documents) - def get_document_detail(self, document_id: str) -> KnowledgeDocumentDetailRead: - self.ensure_library_ready() - index = self._load_index() - entry = self._require_entry(index, document_id) - preview_kind, preview_pages = self._build_preview(entry) - document = self._serialize_document(entry) + def get_document_detail(self, document_id: str) -> KnowledgeDocumentDetailRead: + self.ensure_library_ready() + index = self._load_index() + if self._reconcile_document_ingest_statuses(index, document_ids=[document_id]): + self._save_index(index) + entry = self._require_entry(index, document_id) + preview_kind, preview_pages = self._build_preview(entry) + document = self._serialize_document(entry) return KnowledgeDocumentDetailRead( **document.model_dump(), previewKind=preview_kind, previewPages=preview_pages, ) - def upload_document( - self, - folder: str, + def upload_document( + self, + folder: str, filename: str, content: bytes, current_user: CurrentUserContext, @@ -162,22 +195,23 @@ class KnowledgeService: checksum = hashlib.sha256(content).hexdigest() extension = self._extract_extension(normalized_name) - if existing_entry is None: - entry = { - "id": document_id, - "folder": normalized_folder, - "original_name": normalized_name, + if existing_entry is None: + entry = { + "id": document_id, + "folder": normalized_folder, + "original_name": normalized_name, "stored_name": stored_name, "mime_type": mime_type, "extension": extension, "size_bytes": len(content), "sha256": checksum, - "created_at": now, - "updated_at": now, - "uploaded_by": current_user.name, - "version_number": 1, - } - index["documents"].append(entry) + "created_at": now, + "updated_at": now, + "uploaded_by": current_user.name, + "version_number": 1, + "ingest_status": KNOWLEDGE_INGEST_STATUS_PUBLISHED, + } + index["documents"].append(entry) logger.info( "Knowledge document uploaded id=%s folder=%s filename=%s by=%s", document_id, @@ -193,12 +227,13 @@ class KnowledgeService: "extension": extension, "size_bytes": len(content), "sha256": checksum, - "updated_at": now, - "uploaded_by": current_user.name, - "version_number": int(existing_entry.get("version_number", 1)) + 1, - } - ) - entry = existing_entry + "updated_at": now, + "uploaded_by": current_user.name, + "version_number": int(existing_entry.get("version_number", 1)) + 1, + "ingest_status": KNOWLEDGE_INGEST_STATUS_PUBLISHED, + } + ) + entry = existing_entry logger.info( "Knowledge document updated id=%s folder=%s filename=%s by=%s", document_id, @@ -222,16 +257,86 @@ class KnowledgeService: self._save_index(index) logger.info("Knowledge document deleted id=%s filename=%s", document_id, entry["original_name"]) - def get_document_content(self, document_id: str) -> tuple[Path, str, str]: - self.ensure_library_ready() - index = self._load_index() - entry = self._require_entry(index, document_id) + def get_document_content(self, document_id: str) -> tuple[Path, str, str]: + self.ensure_library_ready() + index = self._load_index() + entry = self._require_entry(index, document_id) file_path = self._resolve_document_path(entry) if not file_path.exists(): raise FileNotFoundError(entry["original_name"]) - - return file_path, entry["mime_type"], entry["original_name"] + + return file_path, entry["mime_type"], entry["original_name"] + + def list_folder_documents(self, folder: str | None = None) -> list[dict[str, Any]]: + self.ensure_library_ready() + index = self._load_index() + if self._reconcile_document_ingest_statuses(index): + self._save_index(index) + documents = list(index.get("documents") or []) + if folder is None: + return documents + normalized_folder = self._normalize_folder(folder) + return [item for item in documents if item.get("folder") == normalized_folder] + + def get_document_entry(self, document_id: str) -> dict[str, Any]: + self.ensure_library_ready() + index = self._load_index() + if self._reconcile_document_ingest_statuses(index, document_ids=[document_id]): + self._save_index(index) + return dict(self._require_entry(index, document_id)) + + def set_document_ingest_statuses(self, document_ids: list[str], status_code: int) -> None: + self.ensure_library_ready() + normalized_ids = {str(item).strip() for item in document_ids if str(item).strip()} + if not normalized_ids: + return + + index = self._load_index() + changed = False + updated_at = datetime.now(UTC).isoformat() + for entry in index.get("documents", []): + if str(entry.get("id") or "").strip() not in normalized_ids: + continue + if self._normalize_ingest_status_code(entry.get("ingest_status")) == status_code: + continue + entry["ingest_status"] = status_code + entry["ingest_status_updated_at"] = updated_at + changed = True + + if changed: + self._save_index(index) + + def refresh_document_ingest_statuses( + self, + document_ids: list[str] | None = None, + *, + preserve_syncing: bool = True, + ) -> None: + self.ensure_library_ready() + index = self._load_index() + if self._reconcile_document_ingest_statuses( + index, + document_ids=document_ids, + preserve_syncing=preserve_syncing, + ): + self._save_index(index) + + def get_llm_wiki_root(self) -> Path: + self.ensure_library_ready() + return self.llm_wiki_root + + def extract_document_text(self, document_id: str) -> str: + self.ensure_library_ready() + entry = self.get_document_entry(document_id) + file_path = self._resolve_document_path(entry) + if not file_path.exists(): + raise FileNotFoundError(entry["original_name"]) + return self._extract_document_text_from_path( + file_path=file_path, + original_name=str(entry.get("original_name") or file_path.name), + mime_type=str(entry.get("mime_type") or "application/octet-stream"), + ) def build_onlyoffice_config( self, @@ -365,33 +470,41 @@ class KnowledgeService: actor_name = callback.users[0] if callback.users else "ONLYOFFICE" self._replace_document_content(document_id, content, actor_name=actor_name) - def _load_documents(self) -> list[KnowledgeDocumentRead]: - self.ensure_library_ready() - index = self._load_index() - self._reconcile_index(index) - self._save_index(index) - - documents = [self._serialize_document(entry) for entry in index["documents"]] - return sorted(documents, key=lambda item: item.time, reverse=True) - - def _serialize_document(self, entry: dict[str, Any]) -> KnowledgeDocumentRead: + def _load_documents(self) -> list[KnowledgeDocumentRead]: + self.ensure_library_ready() + index = self._load_index() + changed = self._reconcile_index(index) + changed = self._reconcile_document_ingest_statuses(index) or changed + if changed: + self._save_index(index) + + documents = [self._serialize_document(entry) for entry in index["documents"]] + return sorted(documents, key=lambda item: item.time, reverse=True) + + def _serialize_document(self, entry: dict[str, Any]) -> KnowledgeDocumentRead: extension = entry.get("extension") or self._extract_extension(entry["original_name"]) - file_type = self._resolve_file_type(extension) - size_bytes = int(entry.get("size_bytes") or 0) - updated_at = self._format_time(entry.get("updated_at") or entry.get("created_at")) - - return KnowledgeDocumentRead( - id=entry["id"], - name=entry["original_name"], - folder=entry["folder"], - tag=f"{entry['folder']} / {extension.upper() or 'FILE'}", - time=updated_at, - version=f"v{int(entry.get('version_number', 1))}.0", - state="已发布", - stateTone="success", - owner=entry.get("uploaded_by") or "系统导入", - icon=ICON_BY_TYPE.get(file_type, ICON_BY_TYPE["binary"]), - fileType=file_type, + file_type = self._resolve_file_type(extension) + size_bytes = int(entry.get("size_bytes") or 0) + updated_at = self._format_time(entry.get("updated_at") or entry.get("created_at")) + state_code = self._normalize_ingest_status_code(entry.get("ingest_status")) + state_label, state_tone = KNOWLEDGE_INGEST_STATUS_META.get( + state_code, + KNOWLEDGE_INGEST_STATUS_META[KNOWLEDGE_INGEST_STATUS_PUBLISHED], + ) + + return KnowledgeDocumentRead( + id=entry["id"], + name=entry["original_name"], + folder=entry["folder"], + tag=f"{entry['folder']} / {extension.upper() or 'FILE'}", + time=updated_at, + version=f"v{int(entry.get('version_number', 1))}.0", + stateCode=state_code, + state=state_label, + stateTone=state_tone, + owner=entry.get("uploaded_by") or "系统导入", + icon=ICON_BY_TYPE.get(file_type, ICON_BY_TYPE["binary"]), + fileType=file_type, fileTypeLabel=self._resolve_file_type_label(file_type), summary=f"{entry['folder']} · {extension.upper() or 'FILE'} · {self._format_size(size_bytes)}", mimeType=entry.get("mime_type") or "application/octet-stream", @@ -551,27 +664,31 @@ class KnowledgeService: encoding="utf-8", ) - def _reconcile_index(self, index: dict[str, Any]) -> bool: - changed = False - documents = index.setdefault("documents", []) + def _reconcile_index(self, index: dict[str, Any]) -> bool: + changed = False + documents = index.setdefault("documents", []) known_by_stored = { (item["folder"], item["stored_name"]): item for item in documents if item.get("folder") and item.get("stored_name") } - existing_items: list[dict[str, Any]] = [] - for item in documents: - file_path = self._resolve_document_path(item) - if file_path.exists(): - item["size_bytes"] = file_path.stat().st_size - item["extension"] = self._extract_extension(item["original_name"]) - item["mime_type"] = item.get("mime_type") or ( - mimetypes.guess_type(item["original_name"])[0] or "application/octet-stream" - ) - existing_items.append(item) - else: - changed = True + existing_items: list[dict[str, Any]] = [] + for item in documents: + file_path = self._resolve_document_path(item) + if file_path.exists(): + item["size_bytes"] = file_path.stat().st_size + item["extension"] = self._extract_extension(item["original_name"]) + item["mime_type"] = item.get("mime_type") or ( + mimetypes.guess_type(item["original_name"])[0] or "application/octet-stream" + ) + normalized_status = self._normalize_ingest_status_code(item.get("ingest_status")) + if item.get("ingest_status") != normalized_status: + item["ingest_status"] = normalized_status + changed = True + existing_items.append(item) + else: + changed = True for folder_name in FIXED_KNOWLEDGE_FOLDERS: folder_path = self.library_root / folder_name @@ -596,18 +713,128 @@ class KnowledgeService: "extension": self._extract_extension(original_name), "size_bytes": stat.st_size, "sha256": "", - "created_at": datetime.fromtimestamp(stat.st_ctime, tz=UTC).isoformat(), - "updated_at": datetime.fromtimestamp(stat.st_mtime, tz=UTC).isoformat(), - "uploaded_by": "系统导入", - "version_number": 1, - } - ) - changed = True + "created_at": datetime.fromtimestamp(stat.st_ctime, tz=UTC).isoformat(), + "updated_at": datetime.fromtimestamp(stat.st_mtime, tz=UTC).isoformat(), + "uploaded_by": "系统导入", + "version_number": 1, + "ingest_status": KNOWLEDGE_INGEST_STATUS_PUBLISHED, + } + ) + changed = True - if changed or len(existing_items) != len(documents): - index["documents"] = existing_items - return True - return False + if changed or len(existing_items) != len(documents): + index["documents"] = existing_items + return True + return False + + def _reconcile_document_ingest_statuses( + self, + index: dict[str, Any], + *, + document_ids: list[str] | None = None, + preserve_syncing: bool = True, + ) -> bool: + changed = False + target_ids = {str(item).strip() for item in document_ids or [] if str(item).strip()} + wiki_index = self._load_llm_wiki_index() + wiki_by_document_id = { + str(item.get("document_id") or "").strip(): item + for item in list(wiki_index.get("documents") or []) + if str(item.get("document_id") or "").strip() + } + + for entry in index.get("documents", []): + document_id = str(entry.get("id") or "").strip() + if target_ids and document_id not in target_ids: + continue + + current_status = self._normalize_ingest_status_code(entry.get("ingest_status")) + if entry.get("ingest_status") != current_status: + entry["ingest_status"] = current_status + changed = True + + if ( + current_status == KNOWLEDGE_INGEST_STATUS_SYNCING + and preserve_syncing + and not self._is_syncing_status_stale(entry) + ): + continue + + desired_status = ( + KNOWLEDGE_INGEST_STATUS_INGESTED + if self._has_ingested_llm_wiki_document(entry, wiki_by_document_id.get(document_id)) + else KNOWLEDGE_INGEST_STATUS_PUBLISHED + ) + if current_status == KNOWLEDGE_INGEST_STATUS_FAILED and desired_status != KNOWLEDGE_INGEST_STATUS_INGESTED: + continue + if current_status != desired_status: + entry["ingest_status"] = desired_status + changed = True + + return changed + + def _load_llm_wiki_index(self) -> dict[str, Any]: + try: + payload = json.loads(self.llm_wiki_index_path.read_text(encoding="utf-8")) + except (FileNotFoundError, json.JSONDecodeError): + payload = {"documents": []} + payload.setdefault("documents", []) + return payload + + def _has_ingested_llm_wiki_document( + self, + entry: dict[str, Any], + wiki_document: dict[str, Any] | None, + ) -> bool: + if not isinstance(wiki_document, dict): + return False + if int(wiki_document.get("knowledge_candidate_count") or 0) <= 0: + return False + + current_signature = self._build_llm_wiki_document_signature(entry) + wiki_signature = wiki_document.get("signature") + if isinstance(wiki_signature, dict): + return wiki_signature == current_signature + + return ( + str(wiki_document.get("document_id") or "").strip() == str(entry.get("id") or "").strip() + and str(wiki_document.get("checksum") or "").strip() == str(entry.get("sha256") or "").strip() + ) + + @staticmethod + def _build_llm_wiki_document_signature(entry: dict[str, Any]) -> dict[str, Any]: + return { + "document_id": str(entry.get("id") or ""), + "original_name": str(entry.get("original_name") or ""), + "stored_name": str(entry.get("stored_name") or ""), + "sha256": str(entry.get("sha256") or ""), + "version_number": int(entry.get("version_number") or 1), + "updated_at": str(entry.get("updated_at") or ""), + } + + @staticmethod + def _normalize_ingest_status_code(value: Any) -> int: + try: + status_code = int(value) + except (TypeError, ValueError): + return KNOWLEDGE_INGEST_STATUS_PUBLISHED + if status_code not in KNOWLEDGE_INGEST_STATUS_META: + return KNOWLEDGE_INGEST_STATUS_PUBLISHED + return status_code + + @staticmethod + def _is_syncing_status_stale(entry: dict[str, Any]) -> bool: + raw_value = str(entry.get("ingest_status_updated_at") or "").strip() + if not raw_value: + return True + try: + updated_at = datetime.fromisoformat(raw_value) + except ValueError: + return True + if updated_at.tzinfo is None: + updated_at = updated_at.replace(tzinfo=UTC) + age_seconds = (datetime.now(UTC) - updated_at.astimezone(UTC)).total_seconds() + return age_seconds >= KNOWLEDGE_INGEST_SYNC_STALE_SECONDS def _require_entry(self, index: dict[str, Any], document_id: str) -> dict[str, Any]: for entry in index["documents"]: @@ -746,27 +973,109 @@ class KnowledgeService: def _can_preview(extension: str) -> bool: return extension in INLINE_PREVIEW_EXTENSIONS or extension in STRUCTURED_PREVIEW_EXTENSIONS - @staticmethod - def _read_text_preview(file_path: Path) -> str: - encodings = ("utf-8", "utf-8-sig", "gbk") - for encoding in encodings: - try: + @staticmethod + def _read_text_preview(file_path: Path) -> str: + encodings = ("utf-8", "utf-8-sig", "gbk") + for encoding in encodings: + try: return file_path.read_text(encoding=encoding) except UnicodeDecodeError: continue return "当前文本文件编码暂不支持在线解析。" @staticmethod - def _extract_docx_text(file_path: Path) -> str: - try: - with ZipFile(file_path) as archive: - xml_content = archive.read("word/document.xml") - except (BadZipFile, KeyError): - return "当前 Word 文件解析失败。" + def _extract_docx_text(file_path: Path) -> str: + try: + with ZipFile(file_path) as archive: + xml_content = archive.read("word/document.xml") + except (BadZipFile, KeyError): + return "当前 Word 文件解析失败。" root = ElementTree.fromstring(xml_content) - texts = [node.text.strip() for node in root.iter() if node.tag.endswith("}t") and node.text] - return "\n".join(texts) + texts = [node.text.strip() for node in root.iter() if node.tag.endswith("}t") and node.text] + return "\n".join(texts) + + def _extract_document_text_from_path( + self, + *, + file_path: Path, + original_name: str, + mime_type: str, + ) -> str: + extension = self._extract_extension(original_name) + if extension in TEXT_EXTENSIONS: + return self._normalize_extracted_text(self._read_text_preview(file_path)) + if extension == "docx": + return self._normalize_extracted_text(self._extract_docx_text(file_path)) + if extension == "pdf": + text = self._normalize_extracted_text(self._extract_pdf_text(file_path)) + if text: + return text + return self._normalize_extracted_text( + self._extract_text_with_ocr( + file_path=file_path, + original_name=original_name, + mime_type=mime_type, + ) + ) + if extension in IMAGE_EXTENSIONS: + return self._normalize_extracted_text( + self._extract_text_with_ocr( + file_path=file_path, + original_name=original_name, + mime_type=mime_type, + ) + ) + return "" + + @staticmethod + def _normalize_extracted_text(text: str) -> str: + normalized = str(text or "").replace("\r\n", "\n").replace("\r", "\n") + normalized = re.sub(r"\n{3,}", "\n\n", normalized) + return normalized.strip() + + @staticmethod + def _extract_pdf_text(file_path: Path) -> str: + pdftotext_bin = shutil.which("pdftotext") + if not pdftotext_bin: + return "" + + completed = subprocess.run( + [pdftotext_bin, str(file_path), "-"], + capture_output=True, + text=True, + timeout=40, + check=False, + ) + if completed.returncode != 0: + return "" + return str(completed.stdout or "") + + @staticmethod + def _extract_text_with_ocr( + *, + file_path: Path, + original_name: str, + mime_type: str, + ) -> str: + try: + from app.services.ocr import OcrService + + result = OcrService().recognize_files( + [(original_name, file_path.read_bytes(), mime_type)] + ) + except Exception: + return "" + + parts: list[str] = [] + for document in result.documents: + text = str(getattr(document, "text", "") or "").strip() + summary = str(getattr(document, "summary", "") or "").strip() + if text: + parts.append(text) + elif summary: + parts.append(summary) + return "\n\n".join(part for part in parts if part) @staticmethod def _extract_xlsx_sheets(file_path: Path) -> list[tuple[str, list[list[str]]]]: diff --git a/web/src/services/knowledge.js b/web/src/services/knowledge.js index 906456c..f2da89f 100644 --- a/web/src/services/knowledge.js +++ b/web/src/services/knowledge.js @@ -1,12 +1,23 @@ import { apiRequest } from './api.js' -export function fetchKnowledgeLibrary() { - return apiRequest('/knowledge/library') -} - -export function fetchKnowledgeDocument(documentId) { - return apiRequest(`/knowledge/documents/${documentId}`) -} +export function fetchKnowledgeLibrary() { + return apiRequest('/knowledge/library') +} + +export function fetchLlmWikiDocumentDetail(documentId) { + return apiRequest(`/knowledge/llm-wiki/documents/${documentId}`) +} + +export function updateLlmWikiDocumentSummary(documentId, payload) { + return apiRequest(`/knowledge/llm-wiki/documents/${documentId}`, { + method: 'PATCH', + body: JSON.stringify(payload) + }) +} + +export function fetchKnowledgeDocument(documentId) { + return apiRequest(`/knowledge/documents/${documentId}`) +} export function fetchKnowledgeOnlyOfficeConfig(documentId) { return apiRequest(`/knowledge/documents/${documentId}/onlyoffice-config`) @@ -23,15 +34,26 @@ export function uploadKnowledgeDocument({ folder, file }) { ) } -export function deleteKnowledgeDocument(documentId) { - return apiRequest(`/knowledge/documents/${documentId}`, { - method: 'DELETE' - }) -} - -export function fetchKnowledgeDocumentBlob(documentId, disposition = 'inline') { - return apiRequest(`/knowledge/documents/${documentId}/content?disposition=${disposition}`, { - responseType: 'blob', +export function deleteKnowledgeDocument(documentId) { + return apiRequest(`/knowledge/documents/${documentId}`, { + method: 'DELETE' + }) +} + +export function syncKnowledgeDocumentToLlmWiki({ folder, documentId, force = false }) { + return apiRequest('/knowledge/llm-wiki/sync', { + method: 'POST', + body: JSON.stringify({ + folder, + document_ids: documentId ? [documentId] : [], + force + }) + }) +} + +export function fetchKnowledgeDocumentBlob(documentId, disposition = 'inline') { + return apiRequest(`/knowledge/documents/${documentId}/content?disposition=${disposition}`, { + responseType: 'blob', contentType: null }) }