From f738b6cdd4ad90c7026f2784cdfc4ceeab36483c Mon Sep 17 00:00:00 2001 From: caoxiaozhu Date: Mon, 11 May 2026 01:53:30 +0000 Subject: [PATCH] =?UTF-8?q?feat:=20=E9=87=8D=E6=9E=84=20AuditView=20?= =?UTF-8?q?=E6=94=AF=E6=8C=81=E8=A7=84=E5=88=99/=E6=8A=80=E8=83=BD?= =?UTF-8?q?=E5=88=86=E7=B1=BB=EF=BC=8C=E6=96=B0=E5=A2=9E=20Agent=20?= =?UTF-8?q?=E5=BC=80=E5=8F=91=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- document/development/agent plan/00_README.md | 38 ++ .../agent plan/01_overall_architecture.md | 163 +++++++ .../agent plan/02_semantic_ontology.md | 362 +++++++++++++++ .../agent plan/03_agent_responsibilities.md | 178 +++++++ .../04_orchestrator_and_runtime_flow.md | 194 ++++++++ .../agent plan/05_development_roadmap.md | 435 ++++++++++++++++++ .../06_data_contracts_and_governance.md | 334 ++++++++++++++ .../agent plan/07_capability_registry.md | 198 ++++++++ .../agent plan/08_permission_confirmation.md | 214 +++++++++ .../agent plan/09_observability_and_trace.md | 186 ++++++++ .../agent plan/10_evaluation_and_testset.md | 173 +++++++ .../agent plan/11_ocr_invoice_architecture.md | 221 +++++++++ .../12_llm_wiki_knowledge_architecture.md | 148 ++++++ .../agent plan/13_rule_formation_lifecycle.md | 126 +++++ .../14_financial_document_canonical_model.md | 126 +++++ .../agent plan/15_feedback_learning_loop.md | 119 +++++ .../development/agent week plan/00_README.md | 105 +++++ .../agent week plan/MASTER_TODO.md | 119 +++++ .../day_1_foundation_models.md | 316 +++++++++++++ .../day_2_rule_center_integration.md | 220 +++++++++ .../day_3_semantic_ontology_mvp.md | 236 ++++++++++ .../day_4_orchestrator_runtime.md | 183 ++++++++ .../agent week plan/day_5_user_agent_mvp.md | 183 ++++++++ .../agent week plan/day_6_hermes_mvp.md | 191 ++++++++ .../day_7_hardening_demo_acceptance.md | 223 +++++++++ .../plan/ai_agent_dual_layer_arch.md | 169 ------- .../公司支出管理办法2024_系统规则.json | 193 ++++++++ .../storage/公司支出管理办法2024_财务指南.md | 324 +++++++++++++ web/src/assets/styles/views/audit-view.css | 32 ++ web/src/components/layout/SidebarRail.vue | 2 +- web/src/composables/useNavigation.js | 8 +- web/src/views/AuditView.vue | 22 +- web/src/views/scripts/AuditView.js | 316 ++++++++++++- 33 files changed, 5853 insertions(+), 204 deletions(-) create mode 100644 document/development/agent plan/00_README.md create mode 100644 document/development/agent plan/01_overall_architecture.md create mode 100644 document/development/agent plan/02_semantic_ontology.md create mode 100644 document/development/agent plan/03_agent_responsibilities.md create mode 100644 document/development/agent plan/04_orchestrator_and_runtime_flow.md create mode 100644 document/development/agent plan/05_development_roadmap.md create mode 100644 document/development/agent plan/06_data_contracts_and_governance.md create mode 100644 document/development/agent plan/07_capability_registry.md create mode 100644 document/development/agent plan/08_permission_confirmation.md create mode 100644 document/development/agent plan/09_observability_and_trace.md create mode 100644 document/development/agent plan/10_evaluation_and_testset.md create mode 100644 document/development/agent plan/11_ocr_invoice_architecture.md create mode 100644 document/development/agent plan/12_llm_wiki_knowledge_architecture.md create mode 100644 document/development/agent plan/13_rule_formation_lifecycle.md create mode 100644 document/development/agent plan/14_financial_document_canonical_model.md create mode 100644 document/development/agent plan/15_feedback_learning_loop.md create mode 100644 document/development/agent week plan/00_README.md create mode 100644 document/development/agent week plan/MASTER_TODO.md create mode 100644 document/development/agent week plan/day_1_foundation_models.md create mode 100644 document/development/agent week plan/day_2_rule_center_integration.md create mode 100644 document/development/agent week plan/day_3_semantic_ontology_mvp.md create mode 100644 document/development/agent week plan/day_4_orchestrator_runtime.md create mode 100644 document/development/agent week plan/day_5_user_agent_mvp.md create mode 100644 document/development/agent week plan/day_6_hermes_mvp.md create mode 100644 document/development/agent week plan/day_7_hardening_demo_acceptance.md delete mode 100644 document/development/plan/ai_agent_dual_layer_arch.md create mode 100644 server/storage/公司支出管理办法2024_系统规则.json create mode 100644 server/storage/公司支出管理办法2024_财务指南.md diff --git a/document/development/agent plan/00_README.md b/document/development/agent plan/00_README.md new file mode 100644 index 0000000..558715c --- /dev/null +++ b/document/development/agent plan/00_README.md @@ -0,0 +1,38 @@ +# Agent Plan 文档索引 + +本目录描述 X-Financial 后续要建设的双 Agent 财务智能架构。 + +核心目标： + +- 建立一套共享的语义本体协议，统一理解用户问题、定时任务和规则触发上下文。 +- 建设两套职责边界清晰的 Agent： + - Hermes：后台数字员工，负责内循环定时任务、风险巡检、统计、知识维护。 + - 自建 Agent：用户流程助手，负责用户交互、流程操作、解释、查询、草稿生成。 +- 建设 Agent Orchestrator，统一负责路由、权限、工具调用、审计和失败处理。 +- 让规则中心、MCP、知识库、数据库查询和任务系统使用同一套语义协议。 + +推荐阅读顺序： + +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) + +开发原则： + +- 先语义协议，后 Agent 能力。 +- 先只读和建议，后写入和流程动作。 +- 先人工确认，后有限自动化。 +- 所有财务关键动作必须可审计、可回滚、可追责。 +- 所有 Agent 能力必须注册、分级、可评测、可追踪。 diff --git a/document/development/agent plan/01_overall_architecture.md b/document/development/agent plan/01_overall_architecture.md new file mode 100644 index 0000000..6d737f0 --- /dev/null +++ b/document/development/agent plan/01_overall_architecture.md @@ -0,0 +1,163 @@ +# 双 Agent 总体架构 + +## 1. 背景 + +X-Financial 后续需要同时支持两类智能化能力： + +1. 用户主动发起的交互式流程操作。 +2. 系统后台自动运行的定时巡检、统计、预警和知识维护。 + +如果用一个万能 Agent 同时处理这两类任务，风险会很高： + +- 用户流程操作需要权限、确认、上下文追问。 +- 定时巡检需要稳定批处理、失败重试、审计记录。 +- 财务系统不能让大模型直接决定审批、付款、规则上线。 + +因此建议建设双 Agent 架构： + +```text +Hermes Agent + 后台数字员工 + 面向系统内循环 + 定时、批量、巡检、统计、预警、知识候选 + +User Agent + 自建用户流程助手 + 面向用户交互 + 查询、解释、创建草稿、流程操作、审批辅助 +``` + +两套 Agent 共享一套语义本体协议，由 Agent Orchestrator 统一调度。 + +## 2. 总体架构图 + +```text + ┌──────────────────────┐ + │ 用户自然语言 / 定时任务 │ + └───────────┬──────────┘ + │ + ▼ + ┌──────────────────────┐ + │ Semantic Ontology │ + │ 语义本体解析层 │ + └───────────┬──────────┘ + │ + ▼ + ┌──────────────────────┐ + │ Agent Orchestrator │ + │ 路由 / 权限 / 审计 / 调度 │ + └───────┬─────────┬────┘ + │ │ + ┌─────────────▼─┐ ┌─▼──────────────┐ + │ Hermes Agent │ │ User Agent │ + │ 后台数字员工 │ │ 用户流程助手 │ + └───────┬───────┘ └───────┬────────┘ + │ │ + └──────────┬──────────┘ + │ + ┌────────────┬───────────┼───────────┬────────────┐ + ▼ ▼ ▼ ▼ ▼ + 规则中心 MCP 服务 业务数据库 知识库 任务系统 +``` + +## 3. 核心分层 + +### 3.1 语义本体层 + +负责把自然语言或任务配置转成结构化 JSON。 + +输出不是最终答案，而是统一协议： + +```json +{ + "domain": "reimbursement", + "scenario": "invoice_validation", + "intent": "explain_risk", + "entities": [], + "time_range": {}, + "constraints": {}, + "risk_signals": [], + "next_step": "run_rule" +} +``` + +### 3.2 编排层 + +Agent Orchestrator 负责： + +- 判断应该由 Hermes 还是 User Agent 处理。 +- 判断是否需要查数据库、跑规则、调 MCP、检索知识库。 +- 检查用户权限。 +- 记录审计日志。 +- 控制失败重试。 +- 对高风险动作要求用户或管理员确认。 + +### 3.3 Agent 层 + +Hermes 和 User Agent 不直接决定财务关键状态。 + +它们负责： + +- 理解任务。 +- 组织工具调用。 +- 汇总工具结果。 +- 生成建议、解释、报告、草稿。 + +### 3.4 能力层 + +能力层包括： + +- 规则中心：管理 `.md` 规则文件、审核、版本。 +- MCP：封装外部服务，如发票验真、银行流水、OCR、差旅平台。 +- 数据库查询：查询报销、报账、应收、应付、账款数据。 +- 知识库：制度文档、FAQ、历史解释、规则说明。 +- 任务系统：定时任务、批量任务、重试、运行日志。 + +## 4. 关键边界 + +Hermes 可以： + +- 定时读取数据。 +- 执行规则检查。 +- 调 MCP 查询外部状态。 +- 生成风险报告。 +- 生成知识候选。 +- 生成待处理工单。 + +Hermes 不可以： + +- 自动提交报销。 +- 自动发起付款。 +- 自动审批通过。 +- 自动发布知识库正式内容。 +- 自动上线规则。 + +User Agent 可以： + +- 帮用户查询状态。 +- 帮用户解释风险。 +- 帮用户创建报销或付款草稿。 +- 帮审批人生成审批意见。 +- 在用户确认后调用流程 API。 + +User Agent 不可以： + +- 绕过权限。 +- 未确认直接提交关键动作。 +- 自动最终审批。 +- 自动付款。 +- 修改规则审核状态。 + +## 5. 推荐建设顺序 + +```text +Step 1: 建立语义本体 JSON 协议 +Step 2: 建立规则中心的规则/技能/MCP/任务目录 +Step 3: 建立 Orchestrator 路由和审计 +Step 4: 建立 User Agent 的只读查询和解释能力 +Step 5: 建立 Hermes 的定时任务和报告能力 +Step 6: 接入 MCP 和业务数据库 +Step 7: 增加用户确认后的流程写入能力 +Step 8: 增加知识候选和规则优化闭环 +``` + diff --git a/document/development/agent plan/02_semantic_ontology.md b/document/development/agent plan/02_semantic_ontology.md new file mode 100644 index 0000000..93c63b7 --- /dev/null +++ b/document/development/agent plan/02_semantic_ontology.md @@ -0,0 +1,362 @@ +# 语义本体协议设计 + +## 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": [] +} +``` + +扩展原则： + +- 先不要把所有字段都做成数据库列。 +- 语义结果建议存 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 new file mode 100644 index 0000000..6d5382f --- /dev/null +++ b/document/development/agent plan/03_agent_responsibilities.md @@ -0,0 +1,178 @@ +# Hermes 与自建 Agent 职责边界 + +## 1. 两套 Agent 的定位 + +### 1.1 Hermes + +Hermes 定位为后台数字员工。 + +它不直接面向用户聊天，而是在系统后台做内循环工作。 + +关键词： + +```text +定时 +批量 +巡检 +统计 +预警 +知识维护 +规则质量复盘 +``` + +### 1.2 自建 Agent + +自建 Agent 定位为用户流程助手。 + +它直接面对员工、财务人员、审批人和管理员。 + +关键词： + +```text +用户触发 +会话式 +流程操作 +查询解释 +草稿生成 +审批辅助 +用户确认 +``` + +## 2. Hermes 职责 + +Hermes 负责： + +1. 每日风险巡检。 +2. 每日报销、报账、账款统计。 +3. 应收逾期预警。 +4. 应付付款风险预警。 +5. 规则命中质量复盘。 +6. MCP 健康检查。 +7. 知识库候选内容生成。 +8. 高风险工单生成。 +9. 任务运行报告生成。 + +Hermes 输出的内容包括： + +```text +risk_report +risk_work_items +daily_finance_snapshot +knowledge_candidates +rule_improvement_items +mcp_health_report +task_run_log +``` + +Hermes 不允许： + +1. 自动审批通过。 +2. 自动发起付款。 +3. 自动提交用户申请。 +4. 自动发布正式知识库。 +5. 自动上线规则。 +6. 直接修改核心财务状态。 + +## 3. 自建 Agent 职责 + +自建 Agent 负责： + +1. 查询报销单进度。 +2. 创建报销或付款草稿。 +3. 解释规则拦截原因。 +4. 生成审批意见。 +5. 检索制度知识。 +6. 查询应收应付数据。 +7. 帮用户对账。 +8. 引导用户补充缺失信息。 +9. 在用户确认后调用流程 API。 + +自建 Agent 输出的内容包括： + +```text +natural_language_answer +form_draft +approval_opinion_draft +clarification_question +query_result_summary +next_action_suggestion +``` + +自建 Agent 不允许： + +1. 未经用户确认提交关键动作。 +2. 跳过权限校验。 +3. 自动最终审批。 +4. 自动付款。 +5. 修改规则上线状态。 + +## 4. 权限边界 + +| 动作 | Hermes | 自建 Agent | +|---|---|---| +| 查询制度知识 | 可以 | 可以 | +| 查询业务数据 | 可以，按任务权限 | 可以，按用户权限 | +| 跑规则 | 可以 | 可以 | +| 调 MCP | 可以 | 可以 | +| 生成报告 | 可以 | 可以 | +| 生成草稿 | 不建议 | 可以 | +| 提交流程 | 不可以 | 用户确认后可以 | +| 审批通过 | 不可以 | 不可以直接做 | +| 发起付款 | 不可以 | 高权限确认后才可做草稿 | +| 发布知识 | 不可以 | 不可以 | +| 上线规则 | 不可以 | 不可以 | + +## 5. 共享能力 + +两套 Agent 共享： + +- 语义本体协议。 +- 规则中心。 +- MCP 服务。 +- 知识库。 +- 数据库查询服务。 +- 审计日志。 +- 权限系统。 + +不共享： + +- 运行队列。 +- 调度策略。 +- 用户会话状态。 +- 任务重试状态。 + +## 6. 示例 + +### 6.1 Hermes 场景 + +每日 02:00 自动运行： + +```text +每日风险巡检 + 读取昨日报销、报账、发票、账款数据 + 执行规则 + 调用发票验真 MCP + 调用账款流水 MCP + 生成风险报告 + 生成风险工单 +``` + +### 6.2 自建 Agent 场景 + +用户问： + +```text +帮我看一下这张差旅报销为什么没通过。 +``` + +处理： + +```text +解析语义 +查询报销单 +读取规则命中 +检索制度条款 +组织解释 +给出补件建议 +``` + diff --git a/document/development/agent plan/04_orchestrator_and_runtime_flow.md b/document/development/agent plan/04_orchestrator_and_runtime_flow.md new file mode 100644 index 0000000..1846329 --- /dev/null +++ b/document/development/agent plan/04_orchestrator_and_runtime_flow.md @@ -0,0 +1,194 @@ +# Agent Orchestrator 与运行流程 + +## 1. Orchestrator 定位 + +Agent Orchestrator 是双 Agent 架构的调度中心。 + +它不负责生成最终答案，而是负责： + +- 接收用户请求或定时任务。 +- 调用语义解析。 +- 判断处理方。 +- 选择工具。 +- 检查权限。 +- 记录审计。 +- 管理失败重试。 +- 控制高风险动作确认。 + +## 2. 运行主流程 + +```text +输入 + 用户消息 / 页面按钮 / 定时任务 / 系统事件 + ↓ +语义解析 + 输出 ontology_json + ↓ +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 = ask_clarification + 返回追问 +``` + +## 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: 通知财务风控组 +``` + +## 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": "" +} +``` + +## 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 new file mode 100644 index 0000000..7edf883 --- /dev/null +++ b/document/development/agent plan/05_development_roadmap.md @@ -0,0 +1,435 @@ +# 分阶段开发计划 + +## 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 建立 ontology schema 表 + +建议表： + +```text +semantic_ontology_schemas +semantic_parse_logs +``` + +字段： + +```text +id +schema_version +schema_json +status +created_at +updated_at +``` + +### Step 3.3 建立解析测试集 + +至少覆盖： + +- 报销规则解释。 +- 差旅报销创建。 +- 发票验真。 +- 应收逾期查询。 +- 应付付款状态。 +- 每日风险巡检。 +- 知识库维护。 + +## 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 new file mode 100644 index 0000000..5622b9b --- /dev/null +++ b/document/development/agent plan/06_data_contracts_and_governance.md @@ -0,0 +1,334 @@ +# 数据契约与治理要求 + +## 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 +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 +``` + +## 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"], + "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 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 审计不可省略 + +必须记录： + +- 谁触发。 +- 输入是什么。 +- 解析结果是什么。 +- 调了哪些工具。 +- 输出是什么。 +- 是否确认。 +- 是否失败。 + +## 4. 数据治理 + +### 4.1 脱敏 + +Hermes 批处理尽量使用脱敏快照。 + +敏感字段： + +- 身份证。 +- 银行卡。 +- 手机号。 +- 个人住址。 +- 个人发票抬头中的敏感信息。 + +### 4.2 数据保留 + +建议： + +- Agent 运行日志保留 180 天。 +- 工具调用详细请求保留 90 天。 +- 错误日志保留 365 天。 +- 审核记录永久保留。 + +### 4.3 版本治理 + +规则、技能、MCP、任务都应版本化。 + +规则版本尤其重要： + +- 当前版本必须明确。 +- 历史版本可查看。 +- 切换版本需要确认。 +- 上线版本必须审核通过。 + +## 5. 发布策略 + +### 5.1 第一阶段 + +只允许只读能力： + +- 查知识库。 +- 查状态。 +- 看规则。 +- 看任务报告。 + +### 5.2 第二阶段 + +允许生成草稿： + +- 报销草稿。 +- 付款申请草稿。 +- 审批意见草稿。 +- 知识候选草稿。 + +### 5.3 第三阶段 + +允许确认后执行： + +- 用户确认后提交报销。 +- 审批人确认后写入审批意见。 +- 管理员确认后发布知识。 +- 管理员确认后上线规则。 + +### 5.4 禁止项 + +长期禁止： + +- Agent 自动最终审批。 +- Agent 自动付款。 +- Agent 自动绕过规则。 +- Agent 自动修改财务核心数据。 + diff --git a/document/development/agent plan/07_capability_registry.md b/document/development/agent plan/07_capability_registry.md new file mode 100644 index 0000000..2923f59 --- /dev/null +++ b/document/development/agent plan/07_capability_registry.md @@ -0,0 +1,198 @@ +# Capability Registry 能力注册中心 + +## 1. 为什么需要能力注册中心 + +双 Agent 架构里会出现很多能力： + +- 规则文件。 +- 技能。 +- MCP 服务。 +- 数据库查询。 +- 知识库检索。 +- 定时任务。 +- 报告生成。 + +如果 Orchestrator 直接在代码里硬编码这些能力，会导致： + +- 能力越来越多后难维护。 +- 无法统一权限。 +- 无法统一版本。 +- 无法统一输入输出格式。 +- Hermes 和 User Agent 复用困难。 + +因此建议建立 Capability Registry。 + +它的定位是： + +```text +所有可被 Agent 调用的能力目录 +``` + +## 2. 能力类型 + +建议第一版支持： + +```text +rule +skill +mcp +task +database_query +knowledge_search +report_generator +notification +``` + +含义： + +- `rule`：审查规则，通常是 `.md` 文件或规则配置。 +- `skill`：智能能力，如审批意见生成、风险解释。 +- `mcp`：外部服务连接。 +- `task`：定时或批量任务。 +- `database_query`：受控数据库查询能力。 +- `knowledge_search`：知识库检索能力。 +- `report_generator`：报告生成能力。 +- `notification`：通知能力。 + +## 3. 能力注册结构 + +建议结构： + +```json +{ + "id": "cap_rule_duplicate_invoice", + "code": "duplicate_invoice_rule", + "name": "重复报销识别规则", + "capability_type": "rule", + "domain": "reimbursement", + "scenarios": ["invoice_validation", "reimbursement_audit"], + "intents": ["validate", "explain", "monitor"], + "input_schema": {}, + "output_schema": {}, + "permission_required": ["reimbursement:read", "risk:write"], + "risk_level": "high", + "owner": "财务风控组", + "version": "v1.9", + "status": "active", + "requires_confirmation": false, + "created_at": "", + "updated_at": "" +} +``` + +## 4. 与语义本体的匹配关系 + +Orchestrator 根据 ontology_json 匹配能力。 + +示例： + +```json +{ + "domain": "reimbursement", + "scenario": "invoice_validation", + "intent": "explain", + "risk_signals": ["duplicate_invoice"], + "next_step": "run_rule" +} +``` + +可以匹配： + +```text +重复报销识别规则 +发票验真 MCP +风险解释技能 +制度知识库检索 +``` + +## 5. 能力匹配优先级 + +建议顺序： + +```text +Step 1: next_step 决定能力大类 +Step 2: domain 限定业务域 +Step 3: scenario 限定场景 +Step 4: risk_signals 匹配具体规则 +Step 5: intent 匹配技能 +Step 6: permission_required 校验权限 +Step 7: status 必须 active +Step 8: version 使用当前上线版本 +``` + +## 6. 数据表建议 + +```text +agent_capabilities +``` + +字段： + +```text +id +code +name +capability_type +domain +scenario_json +intent_json +input_schema_json +output_schema_json +permission_json +risk_level +owner +current_version +status +requires_confirmation +config_json +created_at +updated_at +``` + +## 7. 开发步骤 + +### Step 1: 先注册静态能力 + +先把现有规则、技能、MCP、任务写入 Registry。 + +不需要一开始做复杂 UI。 + +### Step 2: Orchestrator 改为查 Registry + +从： + +```text +if next_step = run_rule then call duplicate_invoice_rule +``` + +改为： + +```text +query capabilities where type = rule and scenario = invoice_validation +``` + +### Step 3: 加权限过滤 + +只返回当前用户或任务有权限调用的能力。 + +### Step 4: 加版本选择 + +默认使用 active 版本。 + +历史版本只用于回放和调试。 + +### Step 5: 加健康状态 + +MCP、任务、数据库查询能力应有健康状态。 + +不可用时 Orchestrator 走降级策略。 + +## 8. 治理要求 + +- 所有能力必须有 owner。 +- 高风险能力必须有 reviewer。 +- 所有能力必须有输入输出 schema。 +- 所有能力必须有状态。 +- 下线能力不能被 Orchestrator 调用。 +- 能力版本变更必须写入审计。 + diff --git a/document/development/agent plan/08_permission_confirmation.md b/document/development/agent plan/08_permission_confirmation.md new file mode 100644 index 0000000..0414b02 --- /dev/null +++ b/document/development/agent plan/08_permission_confirmation.md @@ -0,0 +1,214 @@ +# 权限与确认引擎 + +## 1. 目标 + +Agent 不能只靠提示词判断能不能执行动作。 + +财务系统需要独立的权限与确认引擎： + +```text +Permission Engine +Confirmation Engine +``` + +它们负责： + +- 判断用户是否能看某类数据。 +- 判断任务是否能调用某个能力。 +- 判断动作是否需要确认。 +- 判断动作是否禁止自动执行。 + +## 2. 动作风险分级 + +建议按 L0-L5 分级。 + +### L0 只读查询 + +例子： + +- 查询制度。 +- 查询单据状态。 +- 查询规则说明。 +- 查询任务运行记录。 + +要求： + +- 需要权限。 +- 不需要确认。 + +### L1 生成建议 + +例子： + +- 生成审批意见建议。 +- 生成风险解释。 +- 生成规则优化建议。 + +要求： + +- 需要权限。 +- 不写业务状态。 +- 不需要确认，但要标记为建议。 + +### L2 生成草稿 + +例子： + +- 生成报销草稿。 +- 生成付款申请草稿。 +- 生成知识库候选。 + +要求： + +- 需要权限。 +- 写入草稿区。 +- 不进入正式流程。 + +### L3 用户确认后提交 + +例子： + +- 用户确认后提交报销。 +- 审批人确认后写入审批意见。 +- 用户确认后发起补件。 + +要求： + +- 必须二次确认。 +- 必须记录确认人。 +- 必须记录确认前后内容。 + +### L4 管理员确认后发布 + +例子： + +- 发布规则。 +- 发布知识库。 +- 启用 MCP。 +- 启用任务。 + +要求： + +- 必须管理员确认。 +- 必须有审核记录。 +- 必须有版本。 + +### L5 禁止自动执行 + +例子： + +- 自动最终审批。 +- 自动付款。 +- 自动绕过风控。 +- 自动修改核心财务状态。 + +要求： + +- Agent 永远不能直接执行。 + +## 3. 权限判断输入 + +```json +{ + "user_id": "emp_001", + "agent": "user_agent", + "source": "user_message", + "action": "create_reimbursement_draft", + "domain": "reimbursement", + "resource": { + "type": "reimbursement_request", + "id": "" + }, + "capability": "travel_reimbursement_create" +} +``` + +## 4. 权限判断输出 + +```json +{ + "allowed": true, + "risk_level": "L2", + "requires_confirmation": false, + "reason": "", + "permission_scope": { + "departments": ["current_user"], + "data_masking": false + } +} +``` + +## 5. 确认弹窗策略 + +需要确认的动作必须显示： + +- 动作名称。 +- 影响对象。 +- 关键字段。 +- 执行后果。 +- 是否可撤销。 +- 确认人。 + +示例： + +```json +{ + "title": "确认提交报销申请", + "action": "submit_reimbursement", + "summary": "将提交差旅报销单 TR-202605001，金额 ¥3,280。", + "risk_level": "L3", + "confirm_button": "确认提交" +} +``` + +## 6. Hermes 权限 + +Hermes 使用服务账号，不使用个人账号。 + +建议拆分权限： + +```text +hermes:risk_scan +hermes:finance_statistics +hermes:knowledge_candidate +hermes:mcp_health_check +``` + +Hermes 默认只允许： + +- 读脱敏快照。 +- 跑规则。 +- 调只读 MCP。 +- 写报告、候选、工单。 + +Hermes 不允许： + +- 写正式审批状态。 +- 写正式付款状态。 +- 发布规则。 +- 发布知识。 + +## 7. User Agent 权限 + +User Agent 继承当前用户权限。 + +例如： + +- 员工只能看自己的报销。 +- 部门负责人可以看本部门。 +- 财务可以看授权范围内数据。 +- 管理员可以管理规则、任务、MCP。 + +User Agent 不能扩大用户权限。 + +## 8. 开发步骤 + +```text +Step 1: 定义 action risk level +Step 2: 建立 Permission Engine 接口 +Step 3: 所有工具调用前接入权限判断 +Step 4: L3/L4 动作接入确认弹窗 +Step 5: 审计记录确认内容 +Step 6: 增加权限测试用例 +``` + diff --git a/document/development/agent plan/09_observability_and_trace.md b/document/development/agent plan/09_observability_and_trace.md new file mode 100644 index 0000000..b21fac3 --- /dev/null +++ b/document/development/agent plan/09_observability_and_trace.md @@ -0,0 +1,186 @@ +# 可观测性与 Agent Run Trace + +## 1. 目标 + +Agent 系统必须可追踪、可回放、可解释。 + +财务系统中尤其需要回答： + +- 为什么 Agent 得出这个结论？ +- 用了哪个模型？ +- 用了哪个规则版本？ +- 调用了哪些 MCP？ +- 查了哪些数据？ +- 谁确认了动作？ +- 失败在哪里？ + +## 2. Agent Run Trace + +每次 Agent 运行都生成一个 run_id。 + +建议结构： + +```json +{ + "run_id": "", + "source": "user_message", + "agent": "user_agent", + "user_id": "emp_001", + "raw_input": "", + "ontology_json": {}, + "route_decision": {}, + "permission_result": {}, + "tool_calls": [], + "final_output": "", + "status": "success", + "started_at": "", + "finished_at": "" +} +``` + +## 3. 需要记录的版本 + +每次运行都要记录： + +```text +ontology_schema_version +semantic_parser_prompt_version +model_name +model_version +rule_version +skill_version +mcp_version +knowledge_snapshot_version +orchestrator_version +``` + +原因： + +用户可能问： + +```text +为什么昨天和今天的结论不一样？ +``` + +只有记录版本，才能解释。 + +## 4. Tool Call Trace + +每个工具调用都记录： + +```json +{ + "tool_call_id": "", + "run_id": "", + "tool_type": "mcp", + "tool_name": "invoice_verify", + "request_json": {}, + "response_json": {}, + "status": "success", + "duration_ms": 820, + "error_message": "" +} +``` + +敏感字段应脱敏。 + +## 5. 运行状态 + +建议枚举： + +```text +pending +running +success +partial_success +failed +cancelled +waiting_confirmation +``` + +## 6. Hermes 可观测性 + +Hermes 任务需要额外记录： + +```text +task_code +schedule_time +data_snapshot_id +records_scanned +rules_executed +mcp_calls +risk_items_generated +knowledge_candidates_generated +retry_count +``` + +示例： + +```json +{ + "task_code": "daily_risk_scan", + "records_scanned": 2146, + "rules_executed": 8, + "mcp_calls": 436, + "risk_items_generated": 19, + "status": "success" +} +``` + +## 7. User Agent 可观测性 + +User Agent 需要额外记录： + +```text +conversation_id +page_context +user_confirmation +draft_created +business_object_id +``` + +## 8. 前端审计视图 + +建议后续增加“Agent 运行记录”页面。 + +展示： + +- 运行时间。 +- Agent 类型。 +- 用户或任务。 +- 语义解析结果。 +- 调用工具。 +- 运行状态。 +- 耗时。 +- 错误。 + +详情页展示： + +- 原始输入。 +- 本体 JSON。 +- 路由决策。 +- 工具调用链。 +- 最终输出。 + +## 9. 告警 + +需要告警的情况： + +- Hermes 任务连续失败。 +- MCP 健康检查失败。 +- 语义解析低置信度比例过高。 +- 某规则误报率过高。 +- Agent 调用耗时异常。 +- 权限拒绝次数异常。 + +## 10. 开发步骤 + +```text +Step 1: 增加 agent_runs 表 +Step 2: 增加 agent_tool_calls 表 +Step 3: Orchestrator 每次执行创建 run_id +Step 4: 工具网关记录 tool call +Step 5: 前端增加运行记录页面 +Step 6: 增加异常告警规则 +``` + diff --git a/document/development/agent plan/10_evaluation_and_testset.md b/document/development/agent plan/10_evaluation_and_testset.md new file mode 100644 index 0000000..441ae7a --- /dev/null +++ b/document/development/agent plan/10_evaluation_and_testset.md @@ -0,0 +1,173 @@ +# 评测集与质量控制 + +## 1. 为什么需要评测集 + +语义解析、本体字段、Agent 路由、规则命中都不能只靠人工感觉。 + +每次修改 prompt、模型、规则或路由逻辑，都应该运行评测集。 + +目标： + +- 检查 domain 是否识别正确。 +- 检查 scenario 是否识别正确。 +- 检查 intent 是否识别正确。 +- 检查 next_step 是否正确。 +- 检查是否应该追问。 +- 检查是否错误调用高风险工具。 + +## 2. 第一版评测集规模 + +建议第一版至少 300 条。 + +```text +报销问题：80 条 +应收问题：60 条 +应付问题：60 条 +制度问答：40 条 +风险解释：30 条 +定时任务：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 +``` + +### 4.2 工具路由准确率 + +```text +tool_route_accuracy +permission_decision_accuracy +confirmation_decision_accuracy +``` + +### 4.3 安全指标 + +```text +unsafe_action_rate +missing_confirmation_rate +permission_bypass_rate +``` + +这些指标必须接近 0。 + +## 5. 低置信度处理 + +语义解析输出应包含： + +```json +{ + "confidence": 0.62, + "missing_slots": ["time_range"], + "ambiguity": ["应收逾期还是审批逾期"] +} +``` + +当置信度低于阈值： + +```text +confidence < 0.75 + 不执行工具 + 返回追问 +``` + +## 6. 模糊问题样例 + +用户问： + +```text +这个为什么还没处理？ +``` + +不能直接执行查询。 + +应该追问： + +```text +你是想查询报销单、应收款还是付款申请的处理状态？ +``` + +## 7. 回归测试流程 + +每次改动以下内容都要跑评测： + +- 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 +``` + +## 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 new file mode 100644 index 0000000..3906394 --- /dev/null +++ b/document/development/agent plan/11_ocr_invoice_architecture.md @@ -0,0 +1,221 @@ +# OCR 票据识别架构 + +## 1. 定位 + +OCR 票据识别不是一个简单的图片转文字功能。 + +它在 X-Financial 中承担三件事： + +1. 把用户上传的附件变成结构化票据信息。 +2. 为规则中心提供可判断的字段。 +3. 为 Hermes 和 User Agent 提供可解释的证据。 + +因此 OCR 应作为独立能力纳入 Capability Registry。 + +```text +capability_type = mcp | document_processor +capability_code = invoice_ocr +``` + +## 2. 总体链路 + +```text +附件上传 + ↓ +文件分类 + ↓ +OCR 识别 + ↓ +字段结构化 + ↓ +票据类型归一化 + ↓ +发票验真 MCP + ↓ +与报销明细匹配 + ↓ +规则中心检查 + ↓ +人工修正 + ↓ +修正结果沉淀 +``` + +## 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. 数据模型建议 + +```text +document_assets +document_ocr_results +invoice_structured_records +invoice_verification_records +document_corrections +``` + +## 5. 与规则中心关系 + +OCR 输出供规则使用： + +```text +重复报销识别规则 +作废发票检查规则 +发票抬头异常规则 +附件完整性规则 +金额不一致规则 +``` + +## 6. 与 Agent 关系 + +User Agent 使用 OCR： + +- 解释发票为什么被拦截。 +- 帮用户补充发票信息。 +- 提醒上传清晰附件。 + +Hermes 使用 OCR： + +- 夜间批量验真。 +- 扫描重复票据。 +- 统计发票异常趋势。 + +## 7. 开发阶段建议 + +```text +Step 1: 附件上传和文件分类 +Step 2: 接入 OCR MCP +Step 3: 结构化字段归一化 +Step 4: 人工修正界面 +Step 5: 发票验真 MCP +Step 6: 与报销明细匹配 +Step 7: 规则中心接入 +Step 8: Hermes 夜间批量 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 new file mode 100644 index 0000000..e208bcc --- /dev/null +++ b/document/development/agent plan/12_llm_wiki_knowledge_architecture.md @@ -0,0 +1,148 @@ +# 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 new file mode 100644 index 0000000..04ef102 --- /dev/null +++ b/document/development/agent plan/13_rule_formation_lifecycle.md @@ -0,0 +1,126 @@ +# 规则形成生命周期 + +## 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 new file mode 100644 index 0000000..7d6fc3c --- /dev/null +++ b/document/development/agent plan/14_financial_document_canonical_model.md @@ -0,0 +1,126 @@ +# 财务单据标准模型 + +## 1. 为什么需要标准模型 + +OCR、MCP、用户填写、业务数据库可能都描述同一张发票，但字段名和格式不同。 + +如果没有标准模型： + +- 规则无法复用。 +- Agent 难以解释。 +- Hermes 难以批量统计。 +- MCP 返回结果难以合并。 + +## 2. 标准对象 + +第一版建议定义这些对象： + +```text +Invoice +Receipt +ReimbursementRequest +PaymentRequest +BankTransaction +Contract +Customer +Vendor +Employee +CostCenter +``` + +## 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. ReimbursementRequest 标准模型 + +```json +{ + "request_id": "", + "request_no": "", + "employee_id": "", + "department_id": "", + "expense_type": "", + "amount": 0, + "currency": "CNY", + "status": "", + "submitted_at": "", + "approval_stage": "", + "invoices": [], + "attachments": [], + "risk_flags": [] +} +``` + +## 5. BankTransaction 标准模型 + +```json +{ + "transaction_id": "", + "bank_account": "", + "transaction_date": "", + "amount": 0, + "currency": "CNY", + "counterparty_name": "", + "summary": "", + "matched_object_type": "", + "matched_object_id": "", + "match_status": "" +} +``` + +## 6. 字段来源优先级 + +建议优先级： + +```text +人工确认字段 + > MCP 验真字段 + > 业务系统字段 + > OCR 字段 + > LLM 推断字段 +``` + +LLM 推断字段必须标记来源和置信度。 + +## 7. 与语义本体关系 + +语义本体识别的是用户意图和对象。 + +标准模型承载对象的结构化字段。 + +```text +ontology.entities[].type = invoice + -> 映射到 Invoice 标准模型 +``` + +## 8. 开发阶段建议 + +```text +Step 1: 定义 Invoice 标准模型 +Step 2: 定义 ReimbursementRequest 标准模型 +Step 3: OCR 输出映射到 Invoice +Step 4: MCP 输出映射到 Invoice +Step 5: 规则中心基于标准模型执行 +Step 6: 扩展 AR/AP 标准模型 +Step 7: 建立字段血缘和置信度 +``` + diff --git a/document/development/agent plan/15_feedback_learning_loop.md b/document/development/agent plan/15_feedback_learning_loop.md new file mode 100644 index 0000000..471aa43 --- /dev/null +++ b/document/development/agent plan/15_feedback_learning_loop.md @@ -0,0 +1,119 @@ +# 反馈闭环与持续学习 + +## 1. 定位 + +Agent 系统必须能从人工反馈中持续变好。 + +反馈来源： + +- OCR 人工修正。 +- 规则误报/漏报。 +- 审批人修改意见。 +- 用户对回答的反馈。 +- Hermes 风险复盘。 +- MCP 调用失败和降级。 + +## 2. 反馈类型 + +```text +ocr_correction +rule_false_positive +rule_false_negative +agent_answer_feedback +approval_opinion_edit +knowledge_answer_feedback +mcp_failure_feedback +task_result_feedback +``` + +## 3. 反馈结构 + +```json +{ + "feedback_id": "", + "feedback_type": "rule_false_positive", + "source_object_type": "rule_run", + "source_object_id": "", + "before": {}, + "after": {}, + "comment": "", + "created_by": "", + "created_at": "" +} +``` + +## 4. 反馈流向 + +```text +人工反馈 + ↓ +反馈池 + ↓ +Hermes 聚类分析 + ↓ +候选改进项 + ↓ +人工审核 + ↓ +更新规则 / 知识 / OCR 映射 / Prompt +``` + +## 5. 反馈不直接自动生效 + +反馈只能生成候选，不直接修改线上规则。 + +必须人工审核： + +- 规则修改。 +- 知识发布。 +- Prompt 修改。 +- OCR 字段映射调整。 + +## 6. Hermes 每日反馈复盘 + +Hermes 每日任务： + +```text +读取昨日反馈 +聚类相似问题 +统计误报高发规则 +统计低评分回答 +生成优化候选 +``` + +输出： + +```text +rule_improvement_candidates +knowledge_update_candidates +ocr_mapping_candidates +prompt_improvement_notes +``` + +## 7. 质量指标 + +建议监控： + +```text +ocr_correction_rate +rule_false_positive_rate +rule_false_negative_rate +agent_answer_like_rate +agent_answer_rewrite_rate +knowledge_no_hit_rate +mcp_failure_rate +``` + +## 8. 开发阶段建议 + +```text +Step 1: 增加反馈按钮和反馈表 +Step 2: OCR 修正写入反馈池 +Step 3: 规则误报/漏报反馈 +Step 4: Agent 回答反馈 +Step 5: Hermes 每日反馈聚类 +Step 6: 生成优化候选 +Step 7: 人工审核发布 +Step 8: 建立质量看板 +``` + diff --git a/document/development/agent week plan/00_README.md b/document/development/agent week plan/00_README.md new file mode 100644 index 0000000..9289224 --- /dev/null +++ b/document/development/agent week plan/00_README.md @@ -0,0 +1,105 @@ +# Agent Week Plan 一周开发计划 + +本目录是在 `document/development/agent plan` 架构文档基础上拆出的 7 天生产标准开发计划。 + +这版文档不是概念说明，而是给 Codex 或开发人员逐项执行的 TODO 手册。执行时必须按顺序推进，每完成一项就在对应文档中标记。 + +## 执行标记规则 + +未完成： + +```md +- [ ] 建立 AgentAsset 数据模型 +``` + +完成后： + +```md +- [x] ~~建立 AgentAsset 数据模型~~ +``` + +执行要求： + +- [ ] 每次只处理一个最小 TODO。 +- [ ] 完成后先自测，再改成 `[x]`。 +- [ ] 改成 `[x]` 时，同时用 `~~` 画线。 +- [ ] 不能因为代码写完就标完成，必须满足该 TODO 的验收证据。 +- [ ] 遇到阻塞时，在当天文档的“阻塞记录”下新增一条说明。 +- [ ] 每天收尾时更新当天文档的“日终交接”。 + +## 文档顺序 + +先看总控清单，再进入每天的执行文档： + +1. [MASTER_TODO.md](./MASTER_TODO.md) +2. [day_1_foundation_models.md](./day_1_foundation_models.md) +3. [day_2_rule_center_integration.md](./day_2_rule_center_integration.md) +4. [day_3_semantic_ontology_mvp.md](./day_3_semantic_ontology_mvp.md) +5. [day_4_orchestrator_runtime.md](./day_4_orchestrator_runtime.md) +6. [day_5_user_agent_mvp.md](./day_5_user_agent_mvp.md) +7. [day_6_hermes_mvp.md](./day_6_hermes_mvp.md) +8. [day_7_hardening_demo_acceptance.md](./day_7_hardening_demo_acceptance.md) + +## 一周总目标 + +- [ ] 建立规则、技能、MCP、任务的统一资产模型。 +- [ ] 建立规则 Markdown 内容、版本、审核、上线状态的闭环。 +- [ ] 建立语义本体 8 字段解析接口。 +- [ ] 建立 Orchestrator 路由和 Agent Run Trace。 +- [ ] 建立 User Agent 的查询、解释、流程辅助 MVP。 +- [ ] 建立 Hermes 的定时风险巡检和日报 MVP。 +- [ ] 建立基础权限分级、人工确认、审计日志。 +- [ ] 建立最小评测集、手动验收脚本和演示流程。 + +## 一周暂不做 + +- [ ] 不做完整 OCR 生产识别引擎，只预留标准接口和 Mock 结果。 +- [ ] 不做完整发票验真 MCP 深度接入，只做能力注册和 Mock 调用。 +- [ ] 不做完整 LLM Wiki 向量检索，只做知识条目写入和读取骨架。 +- [ ] 不做所有财务域数据全量打通，只覆盖报销、应收、应付的最小字段。 +- [ ] 不做规则自动上线，规则只能生成草稿，必须人工审核。 +- [ ] 不做完整 CI/CD，只做本地构建、核心测试和验收脚本。 + +## 生产底线 + +以下底线不得被 MVP 名义绕过： + +- [ ] 所有写操作必须记录审计日志。 +- [ ] 所有 Agent 执行必须生成 `run_id`。 +- [ ] 所有规则必须有版本。 +- [ ] 未审核规则不能上线。 +- [ ] 高风险动作只能生成草稿或建议，不能自动提交。 +- [ ] 外部服务失败必须有降级结果。 +- [ ] 语义解析结果必须落库或落日志，便于回放。 +- [ ] 前端不能只写静态 UI，必须至少对接 Mock 或真实 API。 + +## 每日固定流程 + +上午： + +- [ ] 读取当天文档。 +- [ ] 检查前一天遗留阻塞。 +- [ ] 确认数据库模型、API、服务边界。 +- [ ] 完成后端主路径。 + +下午： + +- [ ] 完成前端联调。 +- [ ] 接入 Agent 或 Orchestrator 流程。 +- [ ] 完成权限、审计、错误态。 + +傍晚： + +- [ ] 运行测试和构建。 +- [ ] 按当天验收清单逐项验收。 +- [ ] 更新 TODO 完成状态。 +- [ ] 填写日终交接。 + +## Codex 执行约束 + +- [ ] 修改代码前先读相关文件，不凭空创建重复模块。 +- [ ] 优先复用现有 FastAPI、SQLAlchemy、Vue、PrimeVue 写法。 +- [ ] API 命名必须稳定，不能一天一个风格。 +- [ ] 数据模型新增字段必须写清楚用途。 +- [ ] 前端状态、空态、错误态、加载态都要覆盖。 +- [ ] 每天结束必须能给出可运行证据。 diff --git a/document/development/agent week plan/MASTER_TODO.md b/document/development/agent week plan/MASTER_TODO.md new file mode 100644 index 0000000..c66f9de --- /dev/null +++ b/document/development/agent week plan/MASTER_TODO.md @@ -0,0 +1,119 @@ +# Agent Week Plan 总控 TODO + +本文件用于控制 7 天开发顺序。每个大项完成后，再进入对应天的详细文档。 + +完成标记规则： + +```md +- [x] ~~已完成的任务~~ +``` + +## Day 1：基础模型与工程骨架 + +- [ ] 阅读 `document/development/agent plan/01_overall_architecture.md`。 +- [ ] 阅读 `document/development/agent plan/02_semantic_ontology.md`。 +- [ ] 阅读 `document/development/agent plan/06_data_contracts_and_governance.md`。 +- [ ] 阅读 `document/development/agent plan/07_capability_registry.md`。 +- [ ] 阅读 `document/development/agent plan/08_permission_confirmation.md`。 +- [ ] 阅读 `document/development/agent plan/09_observability_and_trace.md`。 +- [ ] 完成统一资产模型 `AgentAsset`。 +- [ ] 完成资产版本模型 `AgentAssetVersion`。 +- [ ] 完成资产审核模型 `AgentAssetReview`。 +- [ ] 完成 Agent 运行日志模型 `AgentRun`。 +- [ ] 完成工具调用日志模型 `AgentToolCall`。 +- [ ] 完成语义解析日志模型 `SemanticParseLog`。 +- [ ] 完成审计日志模型 `AuditLog`。 +- [ ] 完成基础 API 路由骨架。 +- [ ] 完成种子数据。 +- [ ] 完成 Day 1 验收。 + +## Day 2：任务规则中心联调 + +- [ ] 阅读 `document/development/agent plan/13_rule_formation_lifecycle.md`。 +- [ ] 阅读 `document/development/agent plan/07_capability_registry.md`。 +- [ ] 对接规则、技能、MCP、任务资产列表 API。 +- [ ] 对接资产详情 API。 +- [ ] 对接规则 Markdown 读取和保存 API。 +- [ ] 对接版本列表和版本切换 API。 +- [ ] 对接审核者信息和审核状态。 +- [ ] 对接规则上线前审核拦截。 +- [ ] 完成前端筛选、搜索、详情、弹窗状态。 +- [ ] 完成 Day 2 验收。 + +## Day 3：语义本体 MVP + +- [ ] 阅读 `document/development/agent plan/02_semantic_ontology.md`。 +- [ ] 阅读 `document/development/agent plan/14_financial_document_canonical_model.md`。 +- [ ] 定义 8 个核心字段的数据结构。 +- [ ] 实现语义解析服务。 +- [ ] 实现语义解析 API。 +- [ ] 实现解析日志保存。 +- [ ] 实现场景、意图、对象、时间、指标、约束、风险、权限字段。 +- [ ] 接入 User Agent 查询入口。 +- [ ] 完成最小评测集。 +- [ ] 完成 Day 3 验收。 + +## Day 4：Orchestrator 运行时 + +- [ ] 阅读 `document/development/agent plan/04_orchestrator_and_runtime_flow.md`。 +- [ ] 阅读 `document/development/agent plan/08_permission_confirmation.md`。 +- [ ] 阅读 `document/development/agent plan/09_observability_and_trace.md`。 +- [ ] 实现 Orchestrator 入口服务。 +- [ ] 实现语义本体到 Agent 路由。 +- [ ] 实现权限级别判断。 +- [ ] 实现工具调用封装。 +- [ ] 实现运行 Trace。 +- [ ] 实现降级和错误返回。 +- [ ] 完成 Day 4 验收。 + +## Day 5：User Agent MVP + +- [ ] 阅读 `document/development/agent plan/03_agent_responsibilities.md`。 +- [ ] 阅读 `document/development/agent plan/12_llm_wiki_knowledge_architecture.md`。 +- [ ] 实现用户自然语言入口。 +- [ ] 实现报销查询解释流程。 +- [ ] 实现应收账款查询解释流程。 +- [ ] 实现应付账款查询解释流程。 +- [ ] 实现规则引用解释。 +- [ ] 实现建议草稿输出。 +- [ ] 完成前端对话或操作入口。 +- [ ] 完成 Day 5 验收。 + +## Day 6：Hermes MVP + +- [ ] 阅读 `document/development/agent plan/03_agent_responsibilities.md`。 +- [ ] 阅读 `document/development/agent plan/11_ocr_invoice_architecture.md`。 +- [ ] 阅读 `document/development/agent plan/15_feedback_learning_loop.md`。 +- [ ] 实现任务资产调度入口。 +- [ ] 实现每日风险巡检任务。 +- [ ] 实现每日报销/报账/账款统计任务。 +- [ ] 实现知识库维护任务。 +- [ ] 实现 OCR Mock 接入点。 +- [ ] 实现 Hermes 运行结果面板或 API。 +- [ ] 完成 Day 6 验收。 + +## Day 7：加固、演示和验收 + +- [ ] 回归 Day 1 到 Day 6 所有核心路径。 +- [ ] 补齐权限拦截。 +- [ ] 补齐审计日志。 +- [ ] 补齐错误态和空态。 +- [ ] 补齐评测用例。 +- [ ] 补齐演示数据。 +- [ ] 完成构建。 +- [ ] 完成一周交付说明。 +- [ ] 完成 Day 7 验收。 + +## 一周最终验收 + +- [ ] 能从任务规则中心看到规则、技能、MCP、任务。 +- [ ] 能打开规则详情，编辑 Markdown，查看版本，切换版本。 +- [ ] 未审核规则不能上线。 +- [ ] 能输入一句自然语言问题并得到语义本体 8 字段结果。 +- [ ] 能由 Orchestrator 路由到 User Agent。 +- [ ] 能由 Hermes 执行一次模拟定时任务。 +- [ ] 能查看 Agent Run Trace。 +- [ ] 能查看工具调用日志。 +- [ ] 能查看审计日志。 +- [ ] 能运行核心测试。 +- [ ] 能完成演示脚本。 diff --git a/document/development/agent week plan/day_1_foundation_models.md b/document/development/agent week plan/day_1_foundation_models.md new file mode 100644 index 0000000..23b3dcc --- /dev/null +++ b/document/development/agent week plan/day_1_foundation_models.md @@ -0,0 +1,316 @@ +# Day 1：基础模型与工程骨架 TODO + +目标：建立后续 6 天开发所需的后端地基。Day 1 不做复杂业务逻辑，只做稳定模型、API 骨架、种子数据、基础审计和可运行验证。 + +参考文档： + +- `document/development/agent plan/01_overall_architecture.md` +- `document/development/agent plan/02_semantic_ontology.md` +- `document/development/agent plan/06_data_contracts_and_governance.md` +- `document/development/agent plan/07_capability_registry.md` +- `document/development/agent plan/08_permission_confirmation.md` +- `document/development/agent plan/09_observability_and_trace.md` + +## 0. 开始前检查 + +- [ ] 确认当前分支和工作区状态。 +- [ ] 确认后端目录位置，例如 `/app/server`。 +- [ ] 确认前端目录位置，例如 `/app/web`。 +- [ ] 确认后端使用的框架、ORM、迁移方式。 +- [ ] 找到现有数据库模型目录。 +- [ ] 找到现有 API 路由目录。 +- [ ] 找到现有启动入口。 +- [ ] 找到现有测试目录。 +- [ ] 找到现有种子数据或初始化脚本。 +- [ ] 记录不应修改的无关文件。 + +## 1. 统一命名和边界 + +- [ ] 确认统一模块名使用 `agent_assets`。 +- [ ] 确认资产类型枚举为 `rule`、`skill`、`mcp`、`task`。 +- [ ] 确认资产状态枚举为 `draft`、`review`、`active`、`disabled`。 +- [ ] 确认审核状态枚举为 `pending`、`approved`、`rejected`。 +- [ ] 确认 Agent 枚举为 `orchestrator`、`user_agent`、`hermes`。 +- [ ] 确认运行来源枚举为 `user_message`、`schedule`、`system_event`。 +- [ ] 确认权限级别枚举为 `read`、`draft_write`、`approval_required`、`forbidden`。 +- [ ] 确认所有主键、外键、时间字段命名符合现有代码风格。 + +验收证据： + +- [ ] 枚举命名在模型、Schema、服务层保持一致。 +- [ ] 没有同时出现 `schedule` 和 `task` 两套用户可见命名。 + +## 2. 建立 AgentAsset 模型 + +- [ ] 新增或扩展模型文件，定义 `AgentAsset`。 +- [ ] 增加字段 `id`。 +- [ ] 增加字段 `asset_type`，取值 `rule | skill | mcp | task`。 +- [ ] 增加字段 `code`，作为业务编码。 +- [ ] 增加字段 `name`。 +- [ ] 增加字段 `description`。 +- [ ] 增加字段 `domain`，例如 `expense | ar | ap | knowledge | system`。 +- [ ] 增加字段 `scenario_json`，保存适用场景。 +- [ ] 增加字段 `owner`。 +- [ ] 增加字段 `reviewer`。 +- [ ] 增加字段 `status`。 +- [ ] 增加字段 `current_version`。 +- [ ] 增加字段 `config_json`。 +- [ ] 增加字段 `created_at`。 +- [ ] 增加字段 `updated_at`。 +- [ ] 给 `code` 增加唯一约束。 +- [ ] 给 `asset_type` 增加索引。 +- [ ] 给 `status` 增加索引。 +- [ ] 给 `domain` 增加索引。 + +验收证据： + +- [ ] 能创建一条规则资产。 +- [ ] 能创建一条技能资产。 +- [ ] 能创建一条 MCP 资产。 +- [ ] 能创建一条任务资产。 + +## 3. 建立 AgentAssetVersion 模型 + +- [ ] 定义 `AgentAssetVersion`。 +- [ ] 增加字段 `id`。 +- [ ] 增加字段 `asset_id`。 +- [ ] 增加字段 `version`，例如 `v1.0.0`。 +- [ ] 增加字段 `content`。 +- [ ] 增加字段 `content_type`，取值 `markdown | json`。 +- [ ] 增加字段 `change_note`。 +- [ ] 增加字段 `created_by`。 +- [ ] 增加字段 `created_at`。 +- [ ] 增加 `asset_id + version` 唯一约束。 +- [ ] 建立 `AgentAsset` 到 `AgentAssetVersion` 的关系。 +- [ ] 约定规则资产的 `content` 保存 Markdown。 +- [ ] 约定技能、MCP、任务资产的 `content` 保存 JSON 快照。 + +验收证据： + +- [ ] 同一个资产不能重复创建同一个版本号。 +- [ ] 资产详情能拿到最近 5 个版本。 + +## 4. 建立 AgentAssetReview 模型 + +- [ ] 定义 `AgentAssetReview`。 +- [ ] 增加字段 `id`。 +- [ ] 增加字段 `asset_id`。 +- [ ] 增加字段 `version`。 +- [ ] 增加字段 `reviewer`。 +- [ ] 增加字段 `review_status`。 +- [ ] 增加字段 `review_note`。 +- [ ] 增加字段 `reviewed_at`。 +- [ ] 增加字段 `created_at`。 +- [ ] 建立资产、版本、审核之间的查询关系。 +- [ ] 增加服务层校验：没有 `approved` 审核时不能把规则置为 `active`。 + +验收证据： + +- [ ] `pending` 规则上线会被拒绝。 +- [ ] `rejected` 规则上线会被拒绝。 +- [ ] `approved` 规则可以上线。 + +## 5. 建立 AgentRun 模型 + +- [ ] 定义 `AgentRun`。 +- [ ] 增加字段 `id`。 +- [ ] 增加字段 `run_id`。 +- [ ] 增加字段 `agent`。 +- [ ] 增加字段 `source`。 +- [ ] 增加字段 `user_id`。 +- [ ] 增加字段 `task_id`。 +- [ ] 增加字段 `ontology_json`。 +- [ ] 增加字段 `route_json`。 +- [ ] 增加字段 `permission_level`。 +- [ ] 增加字段 `status`，取值 `running | succeeded | failed | blocked`。 +- [ ] 增加字段 `result_summary`。 +- [ ] 增加字段 `error_message`。 +- [ ] 增加字段 `started_at`。 +- [ ] 增加字段 `finished_at`。 +- [ ] 给 `run_id` 增加唯一约束。 +- [ ] 给 `agent`、`status`、`started_at` 增加索引。 + +验收证据： + +- [ ] 创建任意 Agent 执行记录时必须生成 `run_id`。 +- [ ] 失败执行能保存错误信息。 + +## 6. 建立 AgentToolCall 模型 + +- [ ] 定义 `AgentToolCall`。 +- [ ] 增加字段 `id`。 +- [ ] 增加字段 `run_id`。 +- [ ] 增加字段 `tool_type`，例如 `mcp | database | llm | ocr | rule_engine`。 +- [ ] 增加字段 `tool_name`。 +- [ ] 增加字段 `request_json`。 +- [ ] 增加字段 `response_json`。 +- [ ] 增加字段 `status`。 +- [ ] 增加字段 `duration_ms`。 +- [ ] 增加字段 `error_message`。 +- [ ] 增加字段 `created_at`。 +- [ ] 建立 `AgentRun` 到 `AgentToolCall` 的关系。 + +验收证据： + +- [ ] 一个 `run_id` 下可以记录多个工具调用。 +- [ ] 工具调用失败时不影响主运行日志保存。 + +## 7. 建立 SemanticParseLog 模型 + +- [ ] 定义 `SemanticParseLog`。 +- [ ] 增加字段 `id`。 +- [ ] 增加字段 `run_id`。 +- [ ] 增加字段 `user_id`。 +- [ ] 增加字段 `raw_query`。 +- [ ] 增加字段 `scenario`。 +- [ ] 增加字段 `intent`。 +- [ ] 增加字段 `entities_json`。 +- [ ] 增加字段 `time_range_json`。 +- [ ] 增加字段 `metrics_json`。 +- [ ] 增加字段 `constraints_json`。 +- [ ] 增加字段 `risk_flags_json`。 +- [ ] 增加字段 `permission_json`。 +- [ ] 增加字段 `confidence`。 +- [ ] 增加字段 `created_at`。 + +验收证据： + +- [ ] 能保存一条完整 8 字段语义解析日志。 +- [ ] 能按 `run_id` 查询语义解析结果。 + +## 8. 建立 AuditLog 模型 + +- [ ] 定义 `AuditLog`。 +- [ ] 增加字段 `id`。 +- [ ] 增加字段 `actor`。 +- [ ] 增加字段 `action`。 +- [ ] 增加字段 `resource_type`。 +- [ ] 增加字段 `resource_id`。 +- [ ] 增加字段 `before_json`。 +- [ ] 增加字段 `after_json`。 +- [ ] 增加字段 `request_id`。 +- [ ] 增加字段 `created_at`。 +- [ ] 为规则保存、审核、上线、任务执行创建审计记录接口。 + +验收证据： + +- [ ] 保存规则 Markdown 时有审计日志。 +- [ ] 审核规则时有审计日志。 +- [ ] 修改任务状态时有审计日志。 + +## 9. 建立 Schema / DTO + +- [ ] 定义 `AgentAssetCreate`。 +- [ ] 定义 `AgentAssetUpdate`。 +- [ ] 定义 `AgentAssetRead`。 +- [ ] 定义 `AgentAssetListItem`。 +- [ ] 定义 `AgentAssetVersionRead`。 +- [ ] 定义 `AgentAssetReviewRead`。 +- [ ] 定义 `RuleMarkdownUpdate`。 +- [ ] 定义 `AgentRunRead`。 +- [ ] 定义 `AgentToolCallRead`。 +- [ ] 定义 `SemanticParseRead`。 +- [ ] 所有 JSON 字段在 DTO 中保持结构化，不返回字符串化 JSON。 + +验收证据： + +- [ ] OpenAPI 文档能展示新增 Schema。 +- [ ] 列表 DTO 不返回大块 Markdown 内容。 +- [ ] 详情 DTO 返回当前版本内容。 + +## 10. 建立 API 骨架 + +- [ ] 新增 `GET /api/agent-assets`。 +- [ ] 新增 `GET /api/agent-assets/{asset_id}`。 +- [ ] 新增 `POST /api/agent-assets`。 +- [ ] 新增 `PATCH /api/agent-assets/{asset_id}`。 +- [ ] 新增 `GET /api/agent-assets/{asset_id}/versions`。 +- [ ] 新增 `POST /api/agent-assets/{asset_id}/versions`。 +- [ ] 新增 `POST /api/agent-assets/{asset_id}/reviews`。 +- [ ] 新增 `POST /api/agent-assets/{asset_id}/activate`。 +- [ ] 新增 `GET /api/agent-runs`。 +- [ ] 新增 `GET /api/agent-runs/{run_id}`。 +- [ ] 新增 `GET /api/audit-logs`。 +- [ ] 所有接口先返回真实数据库结果，不使用前端硬编码数据作为最终结果。 + +验收证据： + +- [ ] 能调用资产列表接口。 +- [ ] 能调用资产详情接口。 +- [ ] 能调用版本接口。 +- [ ] 能调用运行日志接口。 + +## 11. 建立服务层 + +- [ ] 新增资产查询服务。 +- [ ] 新增资产保存服务。 +- [ ] 新增版本创建服务。 +- [ ] 新增审核服务。 +- [ ] 新增上线校验服务。 +- [ ] 新增 Agent Run 创建服务。 +- [ ] 新增 Tool Call 记录服务。 +- [ ] 新增审计日志服务。 +- [ ] 所有服务函数返回明确错误，不直接把数据库异常暴露给前端。 + +验收证据： + +- [ ] API 路由中不堆业务判断。 +- [ ] 上线校验逻辑在服务层。 +- [ ] 审计日志通过统一服务写入。 + +## 12. 建立种子数据 + +- [ ] 创建至少 3 条规则资产。 +- [ ] 每条规则资产至少有 2 个版本。 +- [ ] 至少 1 条规则为 `active`。 +- [ ] 至少 1 条规则为 `review`。 +- [ ] 至少 1 条规则为 `draft`。 +- [ ] 创建至少 2 条技能资产。 +- [ ] 创建至少 2 条 MCP 资产。 +- [ ] 创建至少 3 条任务资产。 +- [ ] 为 active 规则创建 approved 审核记录。 +- [ ] 为 review 规则创建 pending 审核记录。 + +验收证据： + +- [ ] 资产列表按类型筛选时四类都有数据。 +- [ ] 规则详情能看到版本和审核者。 + +## 13. 最小测试 + +- [ ] 编写资产模型创建测试。 +- [ ] 编写版本唯一约束测试。 +- [ ] 编写未审核不能上线测试。 +- [ ] 编写资产列表接口测试。 +- [ ] 编写资产详情接口测试。 +- [ ] 编写 AgentRun 创建测试。 +- [ ] 编写 AuditLog 写入测试。 + +验收证据： + +- [ ] 后端核心测试通过。 +- [ ] 测试失败时能定位到具体服务。 + +## 14. Day 1 验收 + +- [ ] 数据库能创建所有新增表或等价结构。 +- [ ] API 服务能启动。 +- [ ] OpenAPI 能看到新增接口。 +- [ ] 资产列表接口返回规则、技能、MCP、任务。 +- [ ] 规则资产有 Markdown 当前版本。 +- [ ] 规则资产有最近版本列表。 +- [ ] 未审核规则不能上线。 +- [ ] AgentRun 能保存一条运行记录。 +- [ ] AuditLog 能保存一条写操作记录。 +- [ ] 所有完成项已用 `[x] ~~...~~` 标记。 + +## 阻塞记录 + +- [ ] 暂无。 + +## 日终交接 + +- [ ] 写明已完成模型。 +- [ ] 写明已完成 API。 +- [ ] 写明未完成问题。 +- [ ] 写明 Day 2 前端联调需要使用的接口地址。 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 new file mode 100644 index 0000000..ce33a76 --- /dev/null +++ b/document/development/agent week plan/day_2_rule_center_integration.md @@ -0,0 +1,220 @@ +# Day 2：任务规则中心联调 TODO + +目标：把任务规则中心从静态 UI 改成可对接后端的生产形态，覆盖规则、技能、MCP、任务四类资产。重点是规则 Markdown 编辑、版本切换、审核者信息、上线约束。 + +参考文档： + +- `document/development/agent plan/07_capability_registry.md` +- `document/development/agent plan/13_rule_formation_lifecycle.md` +- `document/development/agent plan/06_data_contracts_and_governance.md` + +## 0. 开始前检查 + +- [ ] 确认 Day 1 API 已可访问。 +- [ ] 确认前端任务规则中心文件位置。 +- [ ] 确认现有路由名称和导航名称。 +- [ ] 确认现有 UI 风格，不重新做大改版。 +- [ ] 确认当前页面已有页签：规则、技能、MCP、任务。 +- [ ] 确认详情页隐藏顶部 title bar 的逻辑仍然有效。 +- [ ] 确认返回列表栏高度没有被重新拉高。 + +## 1. API Client + +- [ ] 新增或扩展资产列表请求函数。 +- [ ] 新增资产详情请求函数。 +- [ ] 新增版本列表请求函数。 +- [ ] 新增规则 Markdown 保存请求函数。 +- [ ] 新增审核请求函数。 +- [ ] 新增上线请求函数。 +- [ ] 新增运行日志请求函数。 +- [ ] 给所有请求增加加载态。 +- [ ] 给所有请求增加错误态。 +- [ ] 给所有写请求增加成功提示。 + +验收证据： + +- [ ] 前端不再只依赖本地硬编码资产数据。 +- [ ] 后端不可用时页面有明确错误提示。 + +## 2. 列表页数据接入 + +- [ ] 规则页签请求 `asset_type=rule`。 +- [ ] 技能页签请求 `asset_type=skill`。 +- [ ] MCP 页签请求 `asset_type=mcp`。 +- [ ] 任务页签请求 `asset_type=task`。 +- [ ] 搜索框传递关键词或本地过滤。 +- [ ] 类型下拉和搜索框可以同时生效。 +- [ ] 状态筛选可以过滤 `draft | review | active | disabled`。 +- [ ] 列表卡片展示名称。 +- [ ] 列表卡片展示摘要。 +- [ ] 列表卡片展示状态。 +- [ ] 列表卡片展示负责人。 +- [ ] 列表卡片展示最近更新时间。 +- [ ] 空数据时展示空态。 +- [ ] 加载中时展示骨架或加载状态。 + +验收证据： + +- [ ] 四个页签都能切换。 +- [ ] 四个页签都有数据或空态。 +- [ ] 搜索和筛选不会互相覆盖。 + +## 3. 规则详情页主信息 + +- [ ] 打开规则资产时请求详情 API。 +- [ ] Hero title 展示规则名称。 +- [ ] Hero title 下方展示审核者。 +- [ ] Hero title 下方展示审核状态。 +- [ ] Hero title 下方展示上线条件。 +- [ ] Hero title 高度保持紧凑。 +- [ ] 详情页不显示外层顶部 title bar。 +- [ ] 返回列表栏高度保持原有紧凑高度。 + +验收证据： + +- [ ] 用户能一眼看到该规则是否已审核。 +- [ ] 用户不会看到两层 title。 + +## 4. Markdown 编辑器 + +- [ ] 从当前版本读取 Markdown 内容。 +- [ ] Markdown 编辑框高度和右侧版本卡片底部对齐。 +- [ ] Markdown 编辑框支持长内容滚动。 +- [ ] Markdown 编辑框保存时调用 API。 +- [ ] 保存后创建新版本或更新草稿版本，按后端约定执行。 +- [ ] 保存成功后刷新版本列表。 +- [ ] 保存失败时保留用户输入。 +- [ ] 编辑器禁用态覆盖 `active` 且无编辑权限的情况。 +- [ ] 编辑器底部展示最后保存时间。 + +验收证据： + +- [ ] 编辑 Markdown 后刷新页面内容仍存在。 +- [ ] 保存失败不会丢内容。 +- [ ] 左右卡片底部视觉对齐。 + +## 5. 版本卡片 + +- [ ] 右侧只保留版本信息卡片。 +- [ ] 版本卡片宽度足够展示版本号、日期、状态。 +- [ ] 展示最近 5 个版本。 +- [ ] 当前版本有明显但不突兀的标识。 +- [ ] 当前版本标识居中显示。 +- [ ] 选中状态只变色，不改变内容对齐。 +- [ ] 日期列和其他版本日期对齐。 +- [ ] 点击非当前版本时弹出确认弹窗。 +- [ ] 弹窗展示目标版本号。 +- [ ] 弹窗展示切换风险提示。 +- [ ] 确认后切换当前展示内容。 +- [ ] 取消后不改变当前版本。 + +验收证据： + +- [ ] 版本切换不会造成列表文字位移。 +- [ ] 当前版本背景能完全覆盖内容区域。 +- [ ] 版本卡片不贴右侧边界。 + +## 6. 审核与上线 + +- [ ] 详情中展示审核者姓名。 +- [ ] 详情中展示审核时间。 +- [ ] 详情中展示审核意见。 +- [ ] 未审核规则显示不能上线原因。 +- [ ] 点击上线时调用后端上线接口。 +- [ ] 后端拒绝时展示拒绝原因。 +- [ ] 审核通过后上线按钮可用。 +- [ ] 审核动作写入审计日志。 +- [ ] 上线动作写入审计日志。 + +验收证据： + +- [ ] pending 规则无法上线。 +- [ ] approved 规则可以上线。 +- [ ] rejected 规则无法上线。 + +## 7. 技能详情 + +- [ ] 技能页签列表展示能力名称。 +- [ ] 技能详情展示能力说明。 +- [ ] 技能详情展示输入参数。 +- [ ] 技能详情展示输出参数。 +- [ ] 技能详情展示依赖能力。 +- [ ] 技能详情展示适用场景。 +- [ ] 技能详情展示负责人。 +- [ ] 技能详情展示版本。 +- [ ] 技能详情不使用规则 Markdown 编辑器。 + +验收证据： + +- [ ] 技能和规则详情不会混用 UI。 + +## 8. MCP 详情 + +- [ ] MCP 页签列表展示外部服务名称。 +- [ ] MCP 详情展示服务类型。 +- [ ] MCP 详情展示调用地址或能力名。 +- [ ] MCP 详情展示鉴权方式。 +- [ ] MCP 详情展示超时配置。 +- [ ] MCP 详情展示降级策略。 +- [ ] MCP 详情展示最近调用状态。 +- [ ] MCP 详情展示负责人。 + +验收证据： + +- [ ] MCP 被定义为外部服务，而不是技能规则。 + +## 9. 任务详情 + +- [ ] 任务页签展示定时任务名称。 +- [ ] 任务详情展示 cron 或调度周期。 +- [ ] 任务详情展示执行 Agent，默认 Hermes。 +- [ ] 任务详情展示任务目标。 +- [ ] 任务详情展示风险等级。 +- [ ] 任务详情展示最近执行时间。 +- [ ] 任务详情展示最近执行结果。 +- [ ] 任务详情展示启停状态。 + +验收证据： + +- [ ] 定时任务用户可见名称为“任务”。 +- [ ] 技术字段可保留 `schedule`，但 UI 不显示“定时任务”。 + +## 10. 前端质量 + +- [ ] 页面在 1366 宽度下无横向滚动。 +- [ ] 页面在 1920 宽度下右侧卡片不过宽。 +- [ ] 页面在窄屏下详情区域可滚动。 +- [ ] 所有按钮有禁用态。 +- [ ] 所有弹窗有取消按钮。 +- [ ] 所有表单错误有提示。 +- [ ] 所有日期格式统一。 +- [ ] 状态颜色和现有系统一致。 + +验收证据： + +- [ ] `npm run build` 通过。 +- [ ] 任务规则中心手动走查通过。 + +## 11. Day 2 验收 + +- [ ] 规则、技能、MCP、任务四个页签可用。 +- [ ] 搜索框和筛选下拉可用。 +- [ ] 规则详情展示 Markdown。 +- [ ] 规则 Markdown 可保存。 +- [ ] 右侧只保留版本信息。 +- [ ] 版本可切换且有弹窗确认。 +- [ ] 审核者信息在标题下方。 +- [ ] 未审核规则不能上线。 +- [ ] 前端构建通过。 +- [ ] 所有完成项已用 `[x] ~~...~~` 标记。 + +## 阻塞记录 + +- [ ] 暂无。 + +## 日终交接 + +- [ ] 写明已接入的 API。 +- [ ] 写明仍然使用 Mock 的字段。 +- [ ] 写明 UI 未完成项。 +- [ ] 写明 Day 3 语义本体需要复用的资产数据。 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 new file mode 100644 index 0000000..7a5b1d8 --- /dev/null +++ b/document/development/agent week plan/day_3_semantic_ontology_mvp.md @@ -0,0 +1,236 @@ +# Day 3：语义本体 MVP TODO + +目标：建立用户问题的语义解析层，输出稳定的 8 个核心字段，让 User Agent、Hermes 和 Orchestrator 都能使用同一套语义结构。 + +参考文档： + +- `document/development/agent plan/02_semantic_ontology.md` +- `document/development/agent plan/14_financial_document_canonical_model.md` +- `document/development/agent plan/06_data_contracts_and_governance.md` + +## 0. 开始前检查 + +- [ ] 确认 Day 1 的 `SemanticParseLog` 可用。 +- [ ] 确认 Day 1 的 `AgentRun` 可用。 +- [ ] 确认 Day 2 的资产 API 可用。 +- [ ] 找到后端服务层目录。 +- [ ] 找到现有 LLM 调用或 Mock 调用方式。 +- [ ] 确认当前是否允许真实调用 LLM。 +- [ ] 如果不能调用真实 LLM，准备规则解析加 Mock 解析。 + +## 1. 定义 8 个核心字段 + +- [ ] 定义字段 `scenario`，表示业务场景。 +- [ ] 定义字段 `intent`，表示用户意图。 +- [ ] 定义字段 `entities`，表示业务对象。 +- [ ] 定义字段 `time_range`，表示时间范围。 +- [ ] 定义字段 `metrics`，表示指标或金额口径。 +- [ ] 定义字段 `constraints`，表示过滤条件。 +- [ ] 定义字段 `risk_flags`，表示风险信号。 +- [ ] 定义字段 `permission`，表示动作权限。 +- [ ] 为每个字段写清楚类型。 +- [ ] 为每个字段写清楚是否必填。 +- [ ] 为每个字段写清楚默认值。 +- [ ] 为每个字段写清楚示例。 + +验收证据： + +- [ ] 8 个字段在 Schema、服务层、日志中名字一致。 + +## 2. 设计字段枚举 + +- [ ] `scenario` 支持 `expense`。 +- [ ] `scenario` 支持 `accounts_receivable`。 +- [ ] `scenario` 支持 `accounts_payable`。 +- [ ] `scenario` 支持 `knowledge`。 +- [ ] `scenario` 支持 `unknown`。 +- [ ] `intent` 支持 `query`。 +- [ ] `intent` 支持 `explain`。 +- [ ] `intent` 支持 `compare`。 +- [ ] `intent` 支持 `risk_check`。 +- [ ] `intent` 支持 `draft`。 +- [ ] `intent` 支持 `operate`。 +- [ ] `permission.level` 支持 `read`。 +- [ ] `permission.level` 支持 `draft_write`。 +- [ ] `permission.level` 支持 `approval_required`。 +- [ ] `permission.level` 支持 `forbidden`。 + +验收证据： + +- [ ] 未识别的问题不会抛异常，返回 `unknown`。 + +## 3. 建立 Schema + +- [ ] 定义 `OntologyParseRequest`。 +- [ ] `OntologyParseRequest` 包含 `query`。 +- [ ] `OntologyParseRequest` 包含 `user_id`。 +- [ ] `OntologyParseRequest` 包含 `context_json`。 +- [ ] 定义 `OntologyParseResult`。 +- [ ] `OntologyParseResult` 包含 8 个核心字段。 +- [ ] `OntologyParseResult` 包含 `confidence`。 +- [ ] `OntologyParseResult` 包含 `clarification_required`。 +- [ ] `OntologyParseResult` 包含 `clarification_question`。 +- [ ] `OntologyParseResult` 包含 `run_id`。 +- [ ] 定义字段级错误结构。 + +验收证据： + +- [ ] OpenAPI 中可以看到语义解析请求和响应。 + +## 4. 实现解析服务 + +- [ ] 新增 `SemanticOntologyService` 或同等服务。 +- [ ] 实现 `parse(query, user_context)` 主函数。 +- [ ] 先做关键词规则解析。 +- [ ] 报销关键词映射到 `expense`。 +- [ ] 应收、回款、客户欠款映射到 `accounts_receivable`。 +- [ ] 应付、供应商、付款映射到 `accounts_payable`。 +- [ ] 风险、异常、重复、超标映射到 `risk_check`。 +- [ ] 为什么、依据、规则映射到 `explain`。 +- [ ] 统计、汇总、多少映射到 `query`。 +- [ ] 生成、创建、发起映射到 `draft` 或 `operate`。 +- [ ] 无法识别时返回低置信度和澄清问题。 + +验收证据： + +- [ ] “查一下本周报销超标风险”能识别为 expense + risk_check。 +- [ ] “客户 A 这个月还有多少应收”能识别为 accounts_receivable + query。 +- [ ] “供应商 B 明天要付多少钱”能识别为 accounts_payable + query。 + +## 5. 解析业务对象 + +- [ ] 从问题中提取员工姓名。 +- [ ] 从问题中提取部门。 +- [ ] 从问题中提取客户。 +- [ ] 从问题中提取供应商。 +- [ ] 从问题中提取项目。 +- [ ] 从问题中提取单据号。 +- [ ] 从问题中提取金额。 +- [ ] 从问题中提取费用类型。 +- [ ] 无法提取时返回空数组，不返回 null。 + +验收证据： + +- [ ] “张三 4 月差旅报销”能提取员工、月份、费用类型。 + +## 6. 解析时间范围 + +- [ ] 支持今天。 +- [ ] 支持昨天。 +- [ ] 支持本周。 +- [ ] 支持上周。 +- [ ] 支持本月。 +- [ ] 支持上月。 +- [ ] 支持本季度。 +- [ ] 支持今年。 +- [ ] 支持明确日期。 +- [ ] 支持日期区间。 +- [ ] 解析结果包含 `start_date` 和 `end_date`。 +- [ ] 日期使用 ISO 格式。 + +验收证据： + +- [ ] “本周”能解析为当前周起止日期。 +- [ ] “2026 年 4 月”能解析为 `2026-04-01` 到 `2026-04-30`。 + +## 7. 解析指标与约束 + +- [ ] 识别金额指标。 +- [ ] 识别数量指标。 +- [ ] 识别超标指标。 +- [ ] 识别逾期指标。 +- [ ] 识别重复报销指标。 +- [ ] 识别部门过滤条件。 +- [ ] 识别状态过滤条件。 +- [ ] 识别金额阈值过滤条件。 +- [ ] 识别排序要求。 +- [ ] 识别 Top N 要求。 + +验收证据： + +- [ ] “列出金额最高的 10 笔报销”能识别排序和 Top 10。 + +## 8. 解析风险与权限 + +- [ ] 重复报销映射到 `duplicate_expense`。 +- [ ] 发票异常映射到 `invoice_anomaly`。 +- [ ] 金额超标映射到 `amount_over_limit`。 +- [ ] 逾期应收映射到 `ar_overdue`。 +- [ ] 逾期应付映射到 `ap_overdue`。 +- [ ] 查询类问题权限为 `read`。 +- [ ] 生成草稿权限为 `draft_write`。 +- [ ] 审批、上线、付款类动作权限为 `approval_required`。 +- [ ] 越权动作权限为 `forbidden`。 + +验收证据： + +- [ ] “帮我直接付款”不能被标为可直接执行。 + +## 9. API 接口 + +- [ ] 新增 `POST /api/ontology/parse`。 +- [ ] 请求参数包含用户问题。 +- [ ] 请求参数包含用户上下文。 +- [ ] 响应包含 8 个字段。 +- [ ] 响应包含 `run_id`。 +- [ ] 响应包含置信度。 +- [ ] 响应包含澄清问题。 +- [ ] 每次调用写入 `SemanticParseLog`。 +- [ ] 每次调用写入 `AgentRun` 或关联已有 `AgentRun`。 + +验收证据： + +- [ ] 连续调用 5 次都能在日志中查到。 + +## 10. 前端调试入口 + +- [ ] 在合适页面增加语义解析调试入口。 +- [ ] 输入框支持自然语言问题。 +- [ ] 点击解析后调用 API。 +- [ ] 展示 8 个字段。 +- [ ] 展示 JSON 原始结果。 +- [ ] 展示置信度。 +- [ ] 展示澄清问题。 +- [ ] 展示 `run_id`。 +- [ ] 错误时展示错误信息。 + +验收证据： + +- [ ] 产品和开发可以直接在页面验证解析结果。 + +## 11. 评测集 + +- [ ] 创建至少 5 条报销问题。 +- [ ] 创建至少 5 条应收问题。 +- [ ] 创建至少 5 条应付问题。 +- [ ] 创建至少 3 条知识库问题。 +- [ ] 创建至少 3 条越权操作问题。 +- [ ] 为每条问题写期望 `scenario`。 +- [ ] 为每条问题写期望 `intent`。 +- [ ] 为每条问题写期望权限级别。 +- [ ] 编写评测脚本或测试。 + +验收证据： + +- [ ] 核心场景识别准确率达到当天设定阈值，例如 80%。 + +## 12. Day 3 验收 + +- [ ] 语义解析 API 可用。 +- [ ] 8 个核心字段完整返回。 +- [ ] 解析日志可查询。 +- [ ] 低置信度问题有澄清问题。 +- [ ] 越权动作不会被标为可执行。 +- [ ] 前端调试入口可用。 +- [ ] 评测集可运行。 +- [ ] 所有完成项已用 `[x] ~~...~~` 标记。 + +## 阻塞记录 + +- [ ] 暂无。 + +## 日终交接 + +- [ ] 写明已支持的关键词。 +- [ ] 写明识别不准的样例。 +- [ ] 写明 Day 4 Orchestrator 可以直接复用的响应结构。 diff --git a/document/development/agent week plan/day_4_orchestrator_runtime.md b/document/development/agent week plan/day_4_orchestrator_runtime.md new file mode 100644 index 0000000..f4f0915 --- /dev/null +++ b/document/development/agent week plan/day_4_orchestrator_runtime.md @@ -0,0 +1,183 @@ +# Day 4：Orchestrator 运行时 TODO + +目标：建立统一调度层，让用户请求和系统任务都先进入 Orchestrator，再根据语义本体、权限、能力注册路由到 User Agent、Hermes、MCP 或规则引擎。 + +参考文档： + +- `document/development/agent plan/04_orchestrator_and_runtime_flow.md` +- `document/development/agent plan/07_capability_registry.md` +- `document/development/agent plan/08_permission_confirmation.md` +- `document/development/agent plan/09_observability_and_trace.md` + +## 0. 开始前检查 + +- [ ] 确认 Day 3 `POST /api/ontology/parse` 可用。 +- [ ] 确认 `AgentRun` 可创建。 +- [ ] 确认 `AgentToolCall` 可创建。 +- [ ] 确认资产列表能查询技能、MCP、任务。 +- [ ] 确认权限级别枚举已稳定。 +- [ ] 找到后端服务层适合放 Orchestrator 的位置。 + +## 1. Orchestrator 输入输出 + +- [ ] 定义 `OrchestratorRequest`。 +- [ ] 请求包含 `source`。 +- [ ] 请求包含 `user_id`。 +- [ ] 请求包含 `message`。 +- [ ] 请求包含 `task_id`。 +- [ ] 请求包含 `context_json`。 +- [ ] 定义 `OrchestratorResponse`。 +- [ ] 响应包含 `run_id`。 +- [ ] 响应包含 `selected_agent`。 +- [ ] 响应包含 `route_reason`。 +- [ ] 响应包含 `permission_level`。 +- [ ] 响应包含 `status`。 +- [ ] 响应包含 `result`。 +- [ ] 响应包含 `requires_confirmation`。 +- [ ] 响应包含 `trace_summary`。 + +验收证据： + +- [ ] Orchestrator 响应能直接被前端展示。 + +## 2. 建立 Orchestrator 服务 + +- [ ] 新增 `OrchestratorService`。 +- [ ] 实现 `run(request)` 主入口。 +- [ ] 主入口第一步创建 `AgentRun`。 +- [ ] 主入口第二步调用语义解析。 +- [ ] 主入口第三步执行权限判断。 +- [ ] 主入口第四步选择 Agent。 +- [ ] 主入口第五步调用目标 Agent 或返回阻断结果。 +- [ ] 主入口第六步更新 `AgentRun` 状态。 +- [ ] 所有异常都写入 `AgentRun.error_message`。 + +验收证据： + +- [ ] 正常请求状态为 `succeeded`。 +- [ ] 被权限拦截请求状态为 `blocked`。 +- [ ] 异常请求状态为 `failed`。 + +## 3. 路由规则 + +- [ ] `source=user_message` 默认路由到 User Agent。 +- [ ] `source=schedule` 默认路由到 Hermes。 +- [ ] `intent=risk_check` 且来源为 schedule 时路由到 Hermes。 +- [ ] `intent=query` 且来源为 user_message 时路由到 User Agent。 +- [ ] `intent=explain` 路由到 User Agent。 +- [ ] `intent=draft` 路由到 User Agent，但只允许生成草稿。 +- [ ] `permission.level=approval_required` 时设置 `requires_confirmation=true`。 +- [ ] `permission.level=forbidden` 时不调用下游 Agent。 +- [ ] 无法识别时返回澄清问题。 + +验收证据： + +- [ ] 同一句风险检查，在用户入口和任务入口有不同路由结果。 + +## 4. 权限判断 + +- [ ] 新增权限判断服务或函数。 +- [ ] 查询类请求返回 `read`。 +- [ ] 草稿类请求返回 `draft_write`。 +- [ ] 审批、上线、付款类请求返回 `approval_required`。 +- [ ] 用户无权限时返回 `forbidden`。 +- [ ] 高风险动作不允许自动执行。 +- [ ] 需要确认的动作返回确认提示。 +- [ ] 权限判断结果写入 `AgentRun.permission_level`。 + +验收证据： + +- [ ] “直接上线规则”不会被自动执行。 +- [ ] “直接付款”不会被自动执行。 + +## 5. 能力注册查询 + +- [ ] 从 `AgentAsset` 查询 active 技能。 +- [ ] 从 `AgentAsset` 查询 active MCP。 +- [ ] 从 `AgentAsset` 查询 active 任务。 +- [ ] 过滤 disabled 能力。 +- [ ] 过滤未审核 active 条件不满足的规则。 +- [ ] 为每次能力选择记录 `route_json`。 +- [ ] 找不到能力时返回降级说明。 + +验收证据： + +- [ ] 禁用 MCP 不会被 Orchestrator 调用。 + +## 6. 工具调用封装 + +- [ ] 定义统一工具调用接口。 +- [ ] 工具请求前写入 `AgentToolCall` running 或准备记录。 +- [ ] 工具成功后写入响应和耗时。 +- [ ] 工具失败后写入错误。 +- [ ] 外部 MCP 调用失败时返回降级结果。 +- [ ] 数据库查询失败时返回明确错误。 +- [ ] LLM 调用失败时返回可读提示。 + +验收证据： + +- [ ] 每次 Orchestrator 运行至少可以看到 0 到多条工具调用记录。 + +## 7. API 接口 + +- [ ] 新增 `POST /api/orchestrator/run`。 +- [ ] 请求支持用户消息。 +- [ ] 请求支持任务触发。 +- [ ] 响应返回 `run_id`。 +- [ ] 响应返回路由结果。 +- [ ] 响应返回权限结果。 +- [ ] 新增 `GET /api/orchestrator/runs/{run_id}/trace` 或复用 AgentRun 详情接口。 +- [ ] Trace 接口返回语义解析、路由、工具调用、最终结果。 + +验收证据： + +- [ ] 前端或 curl 可以完整看到一次运行链路。 + +## 8. 前端最小 Trace 查看 + +- [ ] 在合适位置展示最近运行记录。 +- [ ] 点击运行记录能查看 `run_id`。 +- [ ] 展示 selected_agent。 +- [ ] 展示 route_reason。 +- [ ] 展示 permission_level。 +- [ ] 展示工具调用列表。 +- [ ] 展示错误信息。 +- [ ] 展示耗时。 + +验收证据： + +- [ ] 开发调试时不需要直接查数据库才能理解路由结果。 + +## 9. 测试 + +- [ ] 测试用户查询路由到 User Agent。 +- [ ] 测试定时任务路由到 Hermes。 +- [ ] 测试 forbidden 不调用下游 Agent。 +- [ ] 测试 approval_required 返回确认。 +- [ ] 测试工具失败写入 ToolCall。 +- [ ] 测试 Orchestrator 异常写入 AgentRun。 + +验收证据： + +- [ ] Orchestrator 核心测试通过。 + +## 10. Day 4 验收 + +- [ ] Orchestrator API 可用。 +- [ ] 用户请求能路由到 User Agent 占位实现。 +- [ ] 定时任务能路由到 Hermes 占位实现。 +- [ ] 权限阻断有效。 +- [ ] 运行 Trace 可查询。 +- [ ] 工具调用日志可查询。 +- [ ] 降级结果可读。 +- [ ] 所有完成项已用 `[x] ~~...~~` 标记。 + +## 阻塞记录 + +- [ ] 暂无。 + +## 日终交接 + +- [ ] 写明路由规则现状。 +- [ ] 写明权限判断现状。 +- [ ] 写明 Day 5 User Agent 需要实现的接口契约。 diff --git a/document/development/agent week plan/day_5_user_agent_mvp.md b/document/development/agent week plan/day_5_user_agent_mvp.md new file mode 100644 index 0000000..682bb05 --- /dev/null +++ b/document/development/agent week plan/day_5_user_agent_mvp.md @@ -0,0 +1,183 @@ +# Day 5：User Agent MVP TODO + +目标：实现面向用户的自建 Agent。它负责用户提问、流程辅助、规则解释、查询结果解释和草稿生成，不做自动审批、自动付款、自动上线等高风险动作。 + +参考文档： + +- `document/development/agent plan/03_agent_responsibilities.md` +- `document/development/agent plan/04_orchestrator_and_runtime_flow.md` +- `document/development/agent plan/12_llm_wiki_knowledge_architecture.md` +- `document/development/agent plan/13_rule_formation_lifecycle.md` + +## 0. 开始前检查 + +- [ ] 确认 Orchestrator 能把用户请求路由到 User Agent。 +- [ ] 确认语义本体 8 字段可用。 +- [ ] 确认规则资产可查询。 +- [ ] 确认 AgentRun 和 ToolCall 可记录。 +- [ ] 确认是否有现成对话 UI。 +- [ ] 确认财务业务数据是否真实可查。 +- [ ] 如果业务数据不可查，准备最小 Mock 数据服务。 + +## 1. User Agent 输入输出 + +- [ ] 定义 `UserAgentRequest`。 +- [ ] 请求包含 `run_id`。 +- [ ] 请求包含 `user_id`。 +- [ ] 请求包含 `message`。 +- [ ] 请求包含 `ontology`。 +- [ ] 请求包含 `context_json`。 +- [ ] 定义 `UserAgentResponse`。 +- [ ] 响应包含 `answer`。 +- [ ] 响应包含 `citations`。 +- [ ] 响应包含 `suggested_actions`。 +- [ ] 响应包含 `draft_payload`。 +- [ ] 响应包含 `risk_flags`。 +- [ ] 响应包含 `requires_confirmation`。 + +验收证据： + +- [ ] User Agent 响应结构能被 Orchestrator 直接包装返回。 + +## 2. 查询处理 + +- [ ] 实现报销查询处理器。 +- [ ] 实现应收查询处理器。 +- [ ] 实现应付查询处理器。 +- [ ] 查询前检查权限级别。 +- [ ] 查询时记录 ToolCall。 +- [ ] 查询失败时返回可读错误。 +- [ ] 查询为空时返回空态解释。 +- [ ] 查询结果限制返回条数，避免一次返回过大。 + +验收证据： + +- [ ] “查本周报销金额”有可读回答。 +- [ ] “客户 A 本月应收多少”有可读回答。 +- [ ] “供应商 B 待付款多少”有可读回答。 + +## 3. 规则解释 + +- [ ] 根据语义场景查询相关规则资产。 +- [ ] 只引用 active 规则。 +- [ ] 读取规则当前版本 Markdown。 +- [ ] 从 Markdown 中提取规则摘要。 +- [ ] 回答中说明使用了哪些规则。 +- [ ] 回答中包含规则版本号。 +- [ ] 回答中包含规则更新时间。 +- [ ] 没有相关规则时说明缺失。 + +验收证据： + +- [ ] “为什么这笔报销有风险”能引用规则。 + +## 4. 风险解释 + +- [ ] 识别重复报销风险。 +- [ ] 识别金额超标风险。 +- [ ] 识别发票异常风险。 +- [ ] 识别逾期应收风险。 +- [ ] 识别逾期应付风险。 +- [ ] 风险回答包含风险类型。 +- [ ] 风险回答包含触发原因。 +- [ ] 风险回答包含建议处理动作。 +- [ ] 高风险建议不能变成自动执行。 + +验收证据： + +- [ ] 风险解释结果不是单纯“有风险”，而是有依据。 + +## 5. 草稿生成 + +- [ ] 支持生成报销处理意见草稿。 +- [ ] 支持生成应收催收建议草稿。 +- [ ] 支持生成应付付款建议草稿。 +- [ ] 草稿中标明“待人工确认”。 +- [ ] 草稿不直接提交业务系统。 +- [ ] 草稿生成写入审计日志。 +- [ ] 草稿生成写入 AgentRun 结果。 + +验收证据： + +- [ ] “帮我生成处理意见”只返回草稿，不执行审批。 + +## 6. 知识库读取骨架 + +- [ ] 建立知识条目查询接口或服务。 +- [ ] 支持按关键词查询知识条目。 +- [ ] 支持按业务场景查询知识条目。 +- [ ] User Agent 回答可以引用知识条目。 +- [ ] 引用中包含知识标题。 +- [ ] 引用中包含更新时间。 +- [ ] 知识库不可用时返回降级说明。 + +验收证据： + +- [ ] 知识库失败不会导致整个回答失败。 + +## 7. 对话或操作入口 + +- [ ] 前端增加用户问题输入框。 +- [ ] 输入框支持回车或按钮提交。 +- [ ] 提交时调用 Orchestrator，而不是绕过 Orchestrator。 +- [ ] 展示 Agent 回答。 +- [ ] 展示引用规则或知识。 +- [ ] 展示建议动作。 +- [ ] 展示需要人工确认的提示。 +- [ ] 展示 `run_id`。 +- [ ] 展示加载态。 +- [ ] 展示错误态。 + +验收证据： + +- [ ] 用户可在页面完成一次问答闭环。 + +## 8. 安全边界 + +- [ ] User Agent 不直接修改规则状态。 +- [ ] User Agent 不直接上线规则。 +- [ ] User Agent 不直接审批报销。 +- [ ] User Agent 不直接付款。 +- [ ] User Agent 不直接删除知识。 +- [ ] 所有高风险动作只返回建议或草稿。 +- [ ] 所有草稿动作标记 `requires_confirmation=true`。 + +验收证据： + +- [ ] 提示词要求“直接付款”时仍被阻断。 + +## 9. 测试 + +- [ ] 测试报销查询。 +- [ ] 测试应收查询。 +- [ ] 测试应付查询。 +- [ ] 测试规则解释。 +- [ ] 测试风险解释。 +- [ ] 测试草稿生成。 +- [ ] 测试越权动作阻断。 +- [ ] 测试知识库降级。 + +验收证据： + +- [ ] User Agent 核心测试通过。 + +## 10. Day 5 验收 + +- [ ] User Agent 服务可被 Orchestrator 调用。 +- [ ] 用户入口可提交自然语言问题。 +- [ ] 至少 3 个财务场景有回答。 +- [ ] 回答能引用规则或知识。 +- [ ] 高风险动作不会自动执行。 +- [ ] AgentRun Trace 能看到 User Agent 步骤。 +- [ ] 前端构建通过。 +- [ ] 所有完成项已用 `[x] ~~...~~` 标记。 + +## 阻塞记录 + +- [ ] 暂无。 + +## 日终交接 + +- [ ] 写明已支持的问题类型。 +- [ ] 写明仍使用 Mock 的数据。 +- [ ] 写明 Day 6 Hermes 可以复用的规则、风险、知识接口。 diff --git a/document/development/agent week plan/day_6_hermes_mvp.md b/document/development/agent week plan/day_6_hermes_mvp.md new file mode 100644 index 0000000..fce2990 --- /dev/null +++ b/document/development/agent week plan/day_6_hermes_mvp.md @@ -0,0 +1,191 @@ +# Day 6：Hermes MVP TODO + +目标：实现 Hermes 数字员工的最小闭环。Hermes 不面向用户即时对话，而是负责定时巡检、统计、风险预警、知识维护和规则草稿形成。 + +参考文档： + +- `document/development/agent plan/03_agent_responsibilities.md` +- `document/development/agent plan/11_ocr_invoice_architecture.md` +- `document/development/agent plan/12_llm_wiki_knowledge_architecture.md` +- `document/development/agent plan/15_feedback_learning_loop.md` + +## 0. 开始前检查 + +- [ ] 确认任务资产 `asset_type=task` 可查询。 +- [ ] 确认 Orchestrator 能处理 `source=schedule`。 +- [ ] 确认 Hermes 占位服务可被调用。 +- [ ] 确认 AgentRun 和 ToolCall 可记录。 +- [ ] 确认是否已有后台任务框架。 +- [ ] 如果没有后台任务框架，先用手动触发 API 模拟定时执行。 + +## 1. Hermes 输入输出 + +- [ ] 定义 `HermesTaskRequest`。 +- [ ] 请求包含 `run_id`。 +- [ ] 请求包含 `task_asset_id`。 +- [ ] 请求包含 `task_type`。 +- [ ] 请求包含 `schedule_time`。 +- [ ] 请求包含 `context_json`。 +- [ ] 定义 `HermesTaskResult`。 +- [ ] 响应包含 `summary`。 +- [ ] 响应包含 `risk_items`。 +- [ ] 响应包含 `statistics`。 +- [ ] 响应包含 `knowledge_updates`。 +- [ ] 响应包含 `draft_rules`。 +- [ ] 响应包含 `next_actions`。 + +验收证据： + +- [ ] Hermes 响应能被任务详情或运行日志展示。 + +## 2. 任务调度入口 + +- [ ] 新增手动触发任务 API。 +- [ ] API 参数支持任务资产 ID。 +- [ ] API 调用 Orchestrator，source 为 `schedule`。 +- [ ] Orchestrator 路由到 Hermes。 +- [ ] Hermes 执行结果写入 AgentRun。 +- [ ] 任务执行失败时写入错误。 +- [ ] 任务执行结束后更新任务最近执行时间。 +- [ ] 任务执行结束后更新任务最近执行状态。 + +验收证据： + +- [ ] 可以手动触发一次 Hermes 任务并看到运行结果。 + +## 3. 每日风险巡检 + +- [ ] 实现重复报销巡检。 +- [ ] 实现金额超标巡检。 +- [ ] 实现发票异常巡检占位。 +- [ ] 实现应收逾期巡检。 +- [ ] 实现应付异常付款巡检。 +- [ ] 每个风险项包含风险类型。 +- [ ] 每个风险项包含业务对象。 +- [ ] 每个风险项包含触发规则。 +- [ ] 每个风险项包含建议动作。 +- [ ] 每个风险项包含风险等级。 + +验收证据： + +- [ ] 风险巡检结果可以被用户理解和追溯。 + +## 4. 每日统计 + +- [ ] 统计当日报销单数量。 +- [ ] 统计当日报销金额。 +- [ ] 统计当日报账数量。 +- [ ] 统计当日报账金额。 +- [ ] 统计应收新增金额。 +- [ ] 统计应收逾期金额。 +- [ ] 统计应付待付金额。 +- [ ] 统计应付逾期金额。 +- [ ] 输出日报摘要。 + +验收证据： + +- [ ] Hermes 能生成一份每日财务摘要。 + +## 5. OCR 接入点 + +- [ ] 建立 OCR 识别服务接口。 +- [ ] 定义发票识别输入结构。 +- [ ] 定义发票识别输出结构。 +- [ ] 输出结构包含发票号。 +- [ ] 输出结构包含开票日期。 +- [ ] 输出结构包含金额。 +- [ ] 输出结构包含税额。 +- [ ] 输出结构包含销售方。 +- [ ] 输出结构包含购买方。 +- [ ] 输出结构包含置信度。 +- [ ] 当前阶段允许使用 Mock 结果。 +- [ ] OCR 调用写入 ToolCall。 + +验收证据： + +- [ ] Hermes 风险巡检中可以调用 OCR Mock。 + +## 6. 知识库维护 + +- [ ] 建立知识条目写入服务。 +- [ ] Hermes 可以生成知识候选条目。 +- [ ] 候选条目包含标题。 +- [ ] 候选条目包含正文。 +- [ ] 候选条目包含来源。 +- [ ] 候选条目包含适用场景。 +- [ ] 候选条目默认状态为 `draft`。 +- [ ] 知识条目不能自动发布。 +- [ ] 知识条目写入审计日志。 + +验收证据： + +- [ ] Hermes 可以生成待审核知识条目。 + +## 7. 规则草稿形成 + +- [ ] Hermes 可以根据风险巡检结果生成规则草稿。 +- [ ] 规则草稿保存为 `asset_type=rule`。 +- [ ] 规则草稿状态为 `draft`。 +- [ ] 规则草稿包含 Markdown 内容。 +- [ ] 规则草稿包含生成原因。 +- [ ] 规则草稿包含关联风险样例。 +- [ ] 规则草稿不能自动上线。 +- [ ] 规则草稿需要审核人。 +- [ ] 规则草稿写入审计日志。 + +验收证据： + +- [ ] Hermes 生成的新规则出现在规则列表中，但不是 active。 + +## 8. Hermes 页面或日志展示 + +- [ ] 任务详情能看到最近执行结果。 +- [ ] 任务详情能手动触发执行。 +- [ ] 任务详情能看到风险项数量。 +- [ ] 任务详情能看到日报摘要。 +- [ ] 任务详情能看到知识候选数量。 +- [ ] 任务详情能看到规则草稿数量。 +- [ ] 运行 Trace 能看到 Hermes 步骤。 +- [ ] 错误时展示错误原因。 + +验收证据： + +- [ ] 不查数据库也能判断 Hermes 是否执行成功。 + +## 9. 测试 + +- [ ] 测试手动触发任务。 +- [ ] 测试 Orchestrator 路由到 Hermes。 +- [ ] 测试风险巡检输出。 +- [ ] 测试日报统计输出。 +- [ ] 测试 OCR Mock 调用。 +- [ ] 测试知识候选写入。 +- [ ] 测试规则草稿生成。 +- [ ] 测试 Hermes 异常写入 AgentRun。 + +验收证据： + +- [ ] Hermes 核心测试通过。 + +## 10. Day 6 验收 + +- [ ] Hermes 可被 Orchestrator 调用。 +- [ ] 至少一个任务可以手动触发。 +- [ ] 风险巡检有结构化结果。 +- [ ] 每日统计有结构化结果。 +- [ ] OCR Mock 接入点可用。 +- [ ] 知识候选可生成。 +- [ ] 规则草稿可生成且不能自动上线。 +- [ ] 任务详情或运行日志能展示结果。 +- [ ] 所有完成项已用 `[x] ~~...~~` 标记。 + +## 阻塞记录 + +- [ ] 暂无。 + +## 日终交接 + +- [ ] 写明 Hermes 已支持任务类型。 +- [ ] 写明 OCR 当前是真实还是 Mock。 +- [ ] 写明生成的知识和规则草稿状态。 +- [ ] 写明 Day 7 需要重点回归的路径。 diff --git a/document/development/agent week plan/day_7_hardening_demo_acceptance.md b/document/development/agent week plan/day_7_hardening_demo_acceptance.md new file mode 100644 index 0000000..a157439 --- /dev/null +++ b/document/development/agent week plan/day_7_hardening_demo_acceptance.md @@ -0,0 +1,223 @@ +# Day 7：加固、演示和验收 TODO + +目标：把前 6 天做出的功能整理成可演示、可验收、可继续迭代的基础平台。Day 7 不再大规模扩功能，重点是修缺口、补测试、补日志、补文档、完成演示链路。 + +参考文档： + +- `document/development/agent plan/00_README.md` +- `document/development/agent plan/05_development_roadmap.md` +- `document/development/agent plan/09_observability_and_trace.md` +- `document/development/agent plan/10_evaluation_and_testset.md` + +## 0. 开始前检查 + +- [ ] 汇总 Day 1 未完成项。 +- [ ] 汇总 Day 2 未完成项。 +- [ ] 汇总 Day 3 未完成项。 +- [ ] 汇总 Day 4 未完成项。 +- [ ] 汇总 Day 5 未完成项。 +- [ ] 汇总 Day 6 未完成项。 +- [ ] 标记必须今天修复的问题。 +- [ ] 标记可以进入下一阶段的问题。 +- [ ] 冻结新增需求，只处理验收相关问题。 + +## 1. 核心链路回归 + +- [ ] 回归资产列表接口。 +- [ ] 回归规则详情接口。 +- [ ] 回归 Markdown 保存。 +- [ ] 回归版本列表。 +- [ ] 回归版本切换。 +- [ ] 回归审核接口。 +- [ ] 回归上线拦截。 +- [ ] 回归语义解析接口。 +- [ ] 回归 Orchestrator 路由。 +- [ ] 回归 User Agent 问答。 +- [ ] 回归 Hermes 任务执行。 +- [ ] 回归 AgentRun Trace。 +- [ ] 回归 ToolCall 日志。 +- [ ] 回归 AuditLog 日志。 + +验收证据： + +- [ ] 从前端能完成至少一条端到端演示路径。 + +## 2. 权限和风险边界 + +- [ ] 未审核规则不能上线。 +- [ ] rejected 规则不能上线。 +- [ ] disabled 能力不能被调用。 +- [ ] 用户请求付款必须拦截。 +- [ ] 用户请求审批必须需要确认。 +- [ ] Hermes 生成规则只能是 draft。 +- [ ] Hermes 生成知识只能是 draft。 +- [ ] User Agent 生成处理意见只能是草稿。 +- [ ] 所有高风险动作响应中包含 `requires_confirmation`。 + +验收证据： + +- [ ] 不存在 MVP 期间绕过人工审核的路径。 + +## 3. 审计和 Trace 补齐 + +- [ ] 规则保存写 AuditLog。 +- [ ] 规则审核写 AuditLog。 +- [ ] 规则上线写 AuditLog。 +- [ ] Hermes 生成规则草稿写 AuditLog。 +- [ ] Hermes 生成知识候选写 AuditLog。 +- [ ] User Agent 草稿生成写 AuditLog。 +- [ ] Orchestrator 每次运行有 AgentRun。 +- [ ] 每次工具调用有 ToolCall。 +- [ ] Trace 页面或接口能串起 run_id。 +- [ ] 错误 Trace 包含 error_message。 + +验收证据： + +- [ ] 任意一条演示链路都能追溯到 run_id。 + +## 4. 前端体验修补 + +- [ ] 任务规则中心列表无明显错位。 +- [ ] 详情页无双 title。 +- [ ] Hero title 高度紧凑。 +- [ ] 返回列表栏高度正常。 +- [ ] Markdown 编辑器和版本卡片底部对齐。 +- [ ] 版本卡片不贴右侧。 +- [ ] 当前版本标识不突兀。 +- [ ] 日期列对齐。 +- [ ] 弹窗文案清楚。 +- [ ] 加载态可见。 +- [ ] 错误态可见。 +- [ ] 空态可见。 +- [ ] 按钮禁用态可见。 +- [ ] 窄屏不出现内容重叠。 + +验收证据： + +- [ ] 任务规则中心可以给业务用户演示，不需要解释 UI 异常。 + +## 5. 测试补齐 + +- [ ] 运行后端现有测试。 +- [ ] 运行新增模型测试。 +- [ ] 运行新增 API 测试。 +- [ ] 运行语义解析测试。 +- [ ] 运行 Orchestrator 测试。 +- [ ] 运行 User Agent 测试。 +- [ ] 运行 Hermes 测试。 +- [ ] 运行前端构建。 +- [ ] 如果有前端测试，运行前端测试。 +- [ ] 记录未能运行的测试和原因。 + +验收证据： + +- [ ] 测试结果写入本文件“测试记录”。 + +## 6. 评测集 + +- [ ] 准备 5 条报销问题。 +- [ ] 准备 5 条应收问题。 +- [ ] 准备 5 条应付问题。 +- [ ] 准备 3 条规则解释问题。 +- [ ] 准备 3 条越权动作问题。 +- [ ] 执行语义解析评测。 +- [ ] 执行 User Agent 回答评测。 +- [ ] 执行权限拦截评测。 +- [ ] 记录失败样例。 +- [ ] 为失败样例写下一阶段优化建议。 + +验收证据： + +- [ ] 可以说明 MVP 当前能力边界和准确率风险。 + +## 7. 演示数据 + +- [ ] 准备 active 规则。 +- [ ] 准备 pending 规则。 +- [ ] 准备 rejected 规则。 +- [ ] 准备至少一条报销数据。 +- [ ] 准备至少一条应收数据。 +- [ ] 准备至少一条应付数据。 +- [ ] 准备至少一个 Hermes 任务。 +- [ ] 准备至少一个 MCP Mock。 +- [ ] 准备至少一个知识条目。 +- [ ] 准备至少一个风险样例。 + +验收证据： + +- [ ] 演示不会因为没有数据而中断。 + +## 8. 演示脚本 + +- [ ] 编写演示步骤 1：打开任务规则中心。 +- [ ] 编写演示步骤 2：查看规则详情。 +- [ ] 编写演示步骤 3：编辑 Markdown 并保存。 +- [ ] 编写演示步骤 4：切换版本。 +- [ ] 编写演示步骤 5：尝试上线未审核规则并被拦截。 +- [ ] 编写演示步骤 6：输入用户问题。 +- [ ] 编写演示步骤 7：查看语义本体结果。 +- [ ] 编写演示步骤 8：查看 User Agent 回答。 +- [ ] 编写演示步骤 9：手动触发 Hermes 任务。 +- [ ] 编写演示步骤 10：查看 AgentRun Trace。 +- [ ] 编写演示步骤 11：查看审计日志。 + +验收证据： + +- [ ] 新开发者按脚本可以复现演示。 + +## 9. 文档收尾 + +- [ ] 更新一周计划完成情况。 +- [ ] 更新剩余风险。 +- [ ] 更新下一阶段开发建议。 +- [ ] 更新接口清单。 +- [ ] 更新数据模型清单。 +- [ ] 更新前端页面清单。 +- [ ] 更新评测结果。 +- [ ] 更新演示脚本。 +- [ ] 更新部署或启动说明。 + +验收证据： + +- [ ] 文档能指导下一周继续开发。 + +## 10. 最终验收清单 + +- [ ] 任务规则中心可查看规则、技能、MCP、任务。 +- [ ] 规则详情可编辑 Markdown。 +- [ ] 规则详情可查看最近 5 个版本。 +- [ ] 版本切换有确认弹窗。 +- [ ] 审核者信息可见。 +- [ ] 未审核规则不能上线。 +- [ ] 语义本体 8 字段可返回。 +- [ ] Orchestrator 能路由用户请求。 +- [ ] Orchestrator 能路由定时任务。 +- [ ] User Agent 能回答至少 3 类财务问题。 +- [ ] Hermes 能执行至少 1 个任务。 +- [ ] OCR Mock 接入点可用。 +- [ ] 知识候选可生成。 +- [ ] 规则草稿可生成。 +- [ ] AgentRun Trace 可查。 +- [ ] AuditLog 可查。 +- [ ] 前端构建通过。 +- [ ] 后端核心测试通过。 +- [ ] 演示脚本可执行。 +- [ ] 所有完成项已用 `[x] ~~...~~` 标记。 + +## 测试记录 + +- [ ] 后端测试：未运行。 +- [ ] 前端构建：未运行。 +- [ ] 语义评测：未运行。 +- [ ] 手动验收：未运行。 + +## 阻塞记录 + +- [ ] 暂无。 + +## 日终交接 + +- [ ] 写明本周最终完成内容。 +- [ ] 写明未完成内容。 +- [ ] 写明生产化前必须补齐内容。 +- [ ] 写明下一周建议优先级。 diff --git a/document/development/plan/ai_agent_dual_layer_arch.md b/document/development/plan/ai_agent_dual_layer_arch.md deleted file mode 100644 index fbcabfa..0000000 --- a/document/development/plan/ai_agent_dual_layer_arch.md +++ /dev/null @@ -1,169 +0,0 @@ -# X-Financial 智能化财务系统：双层 Agent 架构设计与开发落地全景指南 - -> **核心设计理念：确定性与概率性的完美解耦** -> -> 在企业级财务系统中，“合规性”与“准确性”是不可妥协的底线。大语言模型（LLM）天生具有概率性（会产生幻觉），因此不能直接赋予其修改核心财务数据或放行审批的最高权限。 -> -> 本架构设计的核心，在于构建一个**“双层防线”**： -> 1. **外层 Agent (自研流程大脑)**：提供 100% 的确定性。它是系统的执行者，严格按照预设流程和固化的规则行事，不具备“自我意识”，只负责“路由”、“拦截”和“记录”。 -> 2. **内层 Agent (Hermes 智囊核心)**：提供强大的概率性推理能力。它是系统的思考者，负责处理所有复杂、模糊、非结构化的任务（如阅读长文档、识别潜在风险），但它的输出**不能直接作用于业务**，而是转化为**规则配置**或**建议意见**，交由外层 Agent 或人类管理员执行。 -> -> 这两层架构不是相互独立的两个系统，而是形成一个**“闭环”**：内层提炼规则，外层执行规则；外层收集数据，内层分析数据。这种深度协同，既保障了系统的安全性，又赋予了系统极高的智能化水平。 - ---- - -## 一、 系统架构图景与职责边界深度剖析 - -### 1. 外层 Agent (Outer Agent)：流程与路由的绝对掌控者 - -**本质：一个高度可配置的业务工作流引擎与意图分发器。** - -* **开发技术栈建议**：FastAPI (后端) + Vue3 (前端) + PostgreSQL (持久化) + Redis (可选，用于状态缓存)。 -* **交互形态**：它直接面对用户。它可以是一个类似对话框的界面，但背后的逻辑是基于**状态机 (State Machine)** 驱动的。 -* **核心模块与职责 (What to do & How to do)**： - - * **模块 1: 意图漏斗 (Intent Router)** - * **职责**：精准捕捉用户请求的第一诉求，并将其导向正确的处理管线。 - * **方法**： - * *规则匹配优先*：使用简单的关键词或正则（例如：匹配到“报销”、“打车”字眼，直接激活报销向导）。 - * *轻量级分类模型兜底*：对于模糊表述（如：“我上周去上海开会的钱怎么还没发？”），调用一个小参数的分类模型（或内层的快捷接口），将其分类为“状态查询”意图，并提取关键实体（如时间：上周，地点：上海）。 - * **模块 2: 结构化状态机引擎 (State & Flow Controller)** - * **职责**：管理每一个业务对象（如一张报销单）的生命周期。从“草稿” -> “提交” -> “一级审批” -> “财务复核” -> “已打款”。 - * **方法**：拒绝让大模型控制流程走向。流程流转必须基于代码逻辑中的条件判断（例如：如果金额 < 500，且员工级别为 M1，则跳过一级审批，直接进入财务复核）。外层 Agent 负责维护并推进这个状态。 - * **模块 3: 确定性规则执行器 (Rule Execution Engine)** - * **职责**：财务合规的第一道硬性防线。不讲道理，只看数据。 - * **方法**：当用户提交报销数据时，该模块会查询本地的 `business_rules` 数据库表。如果用户提交的住宿费是 850，而数据库规则明确上限是 800，则立刻抛出“阻断型错误” (Blocking Error)。**此过程绝对禁止调用大模型进行实时推断。** - * **模块 4: 标准化 API 网关 (API Gateway & Handshake Layer)** - * **职责**：封装所有对外层系统（如 ERP、HR 系统）和对内层 Hermes 的通信接口。控制并发，记录调用日志。 - -### 2. 内层 Agent (Hermes)：非结构化信息的提炼者与深度思考者 - -**本质：一个被严格隔离的智能计算引擎，专门处理人类擅长但传统代码难以处理的“软逻辑”。** - -* **开发技术栈建议**：Hermes 框架 + 向量数据库 (如 Milvus/PGVector) + 强力 LLM (如 GPT-4 或开源大模型)。 -* **交互形态**：对用户不可见，只作为外层 Agent 的“后端服务”存在。 -* **核心模块与职责 (What to do & How to do)**： - - * **模块 1: 政策蒸馏器 (Policy Distiller) —— 解决“知行合一”的关键** - * **职责**：打破知识库（死文件）与业务流（活代码）之间的壁垒。 - * **方法 (核心思路)**： - 1. *触发*：管理员上传一份《差旅新规.pdf》。 - 2. *解析*：Hermes 逐段阅读文档。 - 3. *提取*：使用精心设计的 **Few-Shot Prompt 链**，强制模型识别特定的“控制变量”。 - *(Prompt 示例: "你是一个专业的财务合规审计员。请阅读以下段落，如果包含任何关于费用上限、职级限制、审批层级的规定，请严格按照以下 JSON Schema 输出：{category, location, level_req, max_amount, is_hard_limit}。如果未找到，输出空。")* - 4. *回写*：Hermes 将提炼出的 JSON 结构转化为标准的 SQL Update 指令（或通过专用 API 接口），更新外层 Agent 依赖的 `business_rules` 表。 - * **模块 2: 深度知识检索 (Deep RAG & Interpretation)** - * **职责**：为用户提供复杂制度的个性化解读。 - * **方法**：当外层 Agent 无法解答用户的合规疑问时（意图识别为“政策咨询”），外层将请求转发给 Hermes。Hermes 在向量库中检索相关段落，并结合用户当前的上下文（如：员工职级、出差地），生成一份连贯、人性化的解答。 - * **模块 3: 异步风险探针 (Asynchronous Risk Auditor)** - * **职责**：像“老会计”一样，在海量已发生或正在发生的业务数据中寻找蛛丝马迹。 - * **方法**： - 1. *定时任务*：每天凌晨启动。 - 2. *数据聚合*：从外层数据库提取当天的报销流水（去除敏感个资）。 - 3. *模式识别*：通过特定的 Prompt（例如寻找“拆单报销”、“异常高频的出租车票”）。 - 4. *生成报告*：生成结构化的风险预警报告，存入专用表，供管理员次日早晨审核，而不是直接去冻结员工账号。 - ---- - -## 二、 核心通信协议 (The Handshake)：两层的握手与数据交互 - -双层架构的成败，取决于这两层能否顺畅地交换信息，且保证安全。我们需要定义清晰的接口协议。 - -### 1. 同步查询接口 (外 -> 内：求知与解惑) - -当外层遇到处理不了的“软逻辑”时触发。 - -* **Endpoint (示例)**: `POST /hermes/api/v1/consult` -* **外层 Request 结构**: - ```json - { - "context": { - "user_id": "emp_1001", - "current_task": "travel_reimbursement", - "form_data": {"city": "北京", "amount": 900} - }, - "query": "因为展会原因酒店全满，只能订900的，能报销吗？" - } - ``` -* **内层 Hermes Response 结构**: - ```json - { - "status": "success", - "interpretation": "根据《差旅管理办法》第15条，展会期间允许上浮 20%。您的标准是800，上浮后为960，可以报销。", - "action_recommendation": "require_special_approval", // 建议外层采取的动作 - "citations": ["policy_doc_v2_page_4"] - } - ``` - -### 2. 异步任务接口 (外 -> 内：派发耗时任务) - -例如请求生成长篇分析报告或进行全量风险巡检。 - -* **流程**： - 1. 外层调用 `POST /hermes/api/v1/jobs/generate_report`。 - 2. 内层 Hermes 立即返回 `202 Accepted` 和一个 `job_id`。 - 3. 内层 Hermes 在后台慢慢算。 - 4. 计算完成后，内层通过 Webhook 回调外层的通知接口，外层再通过系统消息通知用户“您的报告已就绪”。 - -### 3. 规则推送机制 (内 -> 外：自动化立法) - -这是最核心的逆向通信。内层提炼出的规则如何生效？ - -* **流程**： - 1. Hermes 提炼出新规则。 - 2. Hermes 调用外层的特权 API (如 `POST /admin/api/rules/sync`)，推送规则 payload。 - 3. 外层 Agent 收到后，执行数据库 `UPSERT` 操作更新 `business_rules` 表。 - 4. *(可选但强烈建议)*：进入“待激活”状态，需要人类管理员在系统中点击“确认应用新规则”后，新规才正式生效。 - ---- - -## 三、 分阶段开发落地全景计划 (Implementation Roadmap) - -开发应当遵循“先基建后上层、先确定后智能”的原则。 - -### Phase 1: 骨架搭建与基石铺设 (Foundation & Outer Shell) -*目标：构建一个哪怕没有 AI 也能运转的硬核流程系统，确立两层隔离。* - -1. **架构拆分验证**：在服务器层面，确保 Outer Agent (FastAPI) 和 Inner Hermes 分别在独立的进程（或容器）中运行，仅通过 HTTP/gRPC 通信。 -2. **动态规则引擎实现 (核心基建)**： - * 在 PostgreSQL 中设计 `business_rules` 表结构。必须支持高度扩展性（例如采用 `JSONB` 字段存储具体约束参数）。 - * 在外层 Agent 开发一个“规则校验服务 (Rule Validation Service)”，该服务能够在任何报销动作发生前，拦截并比对 `business_rules`。 -3. **标准化流程闭环**：开发一个完整的、基于硬规则驱动的差旅报销单据流转全流程（填单 -> 校验 -> 提交 -> 审批）。验证在“硬规则”下系统运转良好。 - -### Phase 2: 知识注入与基础问答 (Hermes RAG Integration) -*目标：赋予系统“解答疑问”的能力。* - -1. **内层基建**：配置 Hermes 环境，接入向量数据库。 -2. **文档清洗管道 (ETL pipeline)**：将现有的财务政策 PDF/Word 文档清洗、分块 (Chunking) 并向量化入库。 -3. **问答桥接**： - * 在外层前端 (Vue3) 提供一个“智能咨询”悬浮窗或独立页面。 - * 外层 Agent 接收问题，附带上用户的上下文（角色、权限），一并转发给内层 Hermes。 - * 验证 Hermes 能够根据向量库的内容，给出带出处的准确回答。 - -### Phase 3: 核心攻坚 —— 自动立法与双层联通 (Policy Distillation & Sync) -*目标：实现从“死文档”到“活规则”的自动化转化。* - -1. **蒸馏 Prompt 工程**：在 Hermes 中反复打磨“政策提炼”的 Prompt。针对你们公司常见的政策描述方式进行微调。 -2. **结构化提取测试**：手动上传不同版本的政策文档，测试 Hermes 能否稳定、准确地输出 JSON 格式的规则参数。 -3. **闭环联调**： - * 开发 Hermes 向外层推送规则的 API。 - * 完成全链路测试：管理员界面上传新文档 -> Hermes 后台解析 -> 外层规则库自动更新 -> 前端即时生效新的金额限制。 - -### Phase 4: 高阶进化 —— 异步审计与主动防御 (Proactive Risk Auditing) -*目标：将系统从“被动响应”升级为“主动防护”。* - -1. **数据安全隧道**：建立从外层业务库向内层 Hermes 传递“脱敏业务快照”的通道。 -2. **风险模式定义**：梳理出 3-5 种典型的财务风险模式（如：异常聚集的餐饮发票、连续的单日高额交通费）。 -3. **Hermes 巡检任务**：编写定时任务逻辑，利用大模型的推理能力去比对这些模式和当天的业务快照数据。 -4. **风险看板**：在外层系统的管理后台开发“风险报告台”，展示 Hermes 生成的预警结果。 - ---- - -## 四、 关键风险与防范策略总结 - -1. **大模型幻觉污染规则库**： - * **防范**：Hermes 提炼的所有硬性规则（尤其是金额、审批级数），在写入外层正式库之前，必须增加一个**“人工审核 (Human-in-the-loop)”** 环节。系统提示“检测到政策更新，提炼出 5 条新规则，请管理员确认应用”。 -2. **状态机混乱**： - * **防范**：外层 Agent 的流程控制代码必须使用强类型和严格的事务控制 (Transaction)。绝不允许任何组件（包括 AI）在不经过状态机合法校验的情况下直接修改数据库中的 `status` 字段。 -3. **性能瓶颈**： - * **防范**：所有外层必须做的事情（拦截、查询）必须在毫秒级完成。所有涉及调用 Hermes 的操作（问答、提炼、分析）全部采用异步设计或提供明确的 Loading 反馈。 diff --git a/server/storage/公司支出管理办法2024_系统规则.json b/server/storage/公司支出管理办法2024_系统规则.json new file mode 100644 index 0000000..7b70061 --- /dev/null +++ b/server/storage/公司支出管理办法2024_系统规则.json @@ -0,0 +1,193 @@ +{ + "meta": { + "source": "远光软件股份有限公司", + "document": "公司支出管理办法（2024）", + "docNumber": "远光制度〔2024〕14号", + "issueDate": "2024-04-17", + "confidentiality": "商密【中】" + }, + "rules": { + "备用金借款": { + "eligiblePerson": "仅限正式员工", + "maxAmount": 10000, + "repaymentCycle": "按季清理，不得跨年", + "corePrinciple": "前款不清、后款不借", + "forbidNonEmployee": true, + "approvalForExtension": "分管领导审批" + }, + "市内交通费": { + "reimbursementMethod": "凭据报销", + "prepaidCardAccepted": false, + "taxiAllowedCases": ["紧急公务", "接送客户", "夜间工作至22:00后", "其他确有需要的特别情形"], + "taxiApprovalRequired": true, + "encouragePublicTransport": true, + "excludesCommute": true + }, + "差旅费": { + "preApprovalRequired": true, + "transport": { + "airplane": { + "P5AndAbove": {"class": "经济舱", "preApproval": false}, + "P4AndBelow": {"class": "经济舱", "preApproval": true, "discountRequirement": "P4选乘6折及以下,P1-P3选乘5折及以下"} + }, + "train": { + "default": "火车硬席（硬卧、硬座）、高铁/动车二等座、全列软席列车二等软座", + "night6HoursPlus": "可选乘卧铺" + }, + "ship": {"default": "三等舱"}, + "other": "凭据报销" + }, + "accommodation": { + "domestic": { + "P8Plus": {"provincialCapital": 500, "other": 400, "municipality": 800}, + "P7": {"provincialCapital": 450, "other": 400, "municipality": 700}, + "P4ToP6": {"provincialCapital": 400, "other": 350, "municipality": 600}, + "other": {"provincialCapital": 350, "other": 300, "municipality": 500} + }, + "overspendApproval": { + "within20Percent": "部门负责人审批", + "over20Percent": "分管领导审批" + } + }, + "subsidy": { + "mealAllowance": { + "selfPay": { + "municipality": 75, + "otherDomestic": {"xizang": 65, "general": 55}, + "hongkongMacao": 140, + "abroad": 175 + }, + "noReimbursementWhenOrganized": true + }, + "basicAllowance": { + "domestic": 35, + "hongkongMacao": 110, + "abroad": {"min": 90, "max": 100} + } + }, + "reimbursementDeadline": "行程结束后三个月内，连续出差超一个月应按月报销", + "lostReceipt": "75%报销（需提供情况说明+订单详情+支付截图）", + "noSubsidyForVisitingFamily": true + }, + "业务招待费": { + "publicToPublicPreferred": true, + "privatePaymentRequiresProof": true + }, + "会议费": { + "prohibitedItems": ["旅游观光", "宴请", "礼品馈赠"], + "preApprovalThreshold": 30000, + "preApprover": "总裁", + "attachments": ["会议申请与预算", "会议通知", "参会人员签到表", "开支明细", "服务方费用明细清单"] + }, + "广告宣传费": { + "adFee": { + "requiresAttachment": ["广告投放业务佐证材料"] + }, + "promotionFee": { + "requiresAttachment": ["活动方案", "费用预算"], + "requiresProcurementCompliance": true + } + }, + "培训费": { + "qualificationStandard": "《公司员工教育培训管理办法》", + "qualifiedTransport": "往返交通费按出差规定", + "qualifiedAccommodation": "按出差标准执行", + "otherExpenses": "自理" + }, + "通信费": { + "scope": ["电话", "传真", "集团网", "网络连接"], + "staffCommunication": "按《公司员工因公通讯费用实施细则》" + }, + "邮递费": { + "personal": "附快递底单", + "corporateSettlement": "附寄件明细清单与支出分摊表" + }, + "薪酬福利支出": { + "salaryBonusWelfare": "按公司相关制度", + "temporaryReward": { + "preApproval": "总裁", + "executionApproval": "分管领导" + }, + "welfarePlan": "组织人事部年度计划管理，未纳入不得报销", + "staffActivities": "按《公司团建管理办法》或《工会经费管理办法》" + }, + "对外捐赠": { + "department": "品牌及市场运营中心", + "budgetRequired": true, + "unbudgetedProcess": "先履行预算调整决策程序，纳入预算后方可实施", + "attachments": ["发票", "收据", "捐赠协议", "接收函", "捐赠清单"] + }, + "涉外汇率": { + "cny": "凭据报销", + "forex": "按支付凭据所载汇率", + "forexNoRate": "业务发生月第一个交易日中国银行外汇折算价", + "forexNoCnyRate": "中国外汇交易中心参考汇率" + }, + "报销申请": { + "method": "系统单据", + "paperAccepted": false, + "invoiceType": "增值税专用发票（除特定项目外）", + "consolidatedInvoiceRequiresDetail": true, + "deadline": "业务完成后三个月内", + "prepaymentDeadline": "次月底前结算", + "incompleteHandling": "三个工作日内补充，否则退单" + }, + "结算方式": { + "employeeExpense": "公对私", + "positionExpense": "公对公", + "smallAmountThreshold": 1000, + "smallAmountProof": "供应商付款凭据截图" + }, + "审批权限": { + "employeeExpense": { + "businessEntertainment": {"manager": 5000, "directorAndAbove": "1万~3万", "ceo": 150000}, + "publicLoan": {"manager": 5000, "directorAndAbove": "1万~3万", "ceo": 150000}, + "travelAndTransportation": {"manager": 10000, "directorAndAbove": "2万~5万", "ceo": 500000}, + "other": {"manager": 10000, "directorAndAbove": "2万~5万", "ceo": 500000} + }, + "positionExpense": { + "assetPurchase": {"manager": 10000, "director": 200000, "vp": 1000000, "svp": 2000000, "ceo": null}, + "construction": {"manager": null, "director": 50000, "vp": 100000, "svp": null, "ceo": 500000}, + "materialPurchase": {"manager": null, "director": 100000, "vp": 200000, "svp": 300000, "ceo": 5000000}, + "outsourcingInternal": {"manager": null, "director": 100000, "vp": 200000, "svp": 300000, "ceo": 5000000}, + "outsourcingExternal": {"manager": null, "director": 100000, "vp": 200000, "svp": 300000, "ceo": 2000000}, + "deposit": {"manager": 50000, "director": 500000, "vp": 1000000, "svp": 2000000, "ceo": 5000000}, + "salesRefund": {"manager": 50000, "director": 100000, "vp": 300000, "svp": 500000, "ceo": 2000000}, + "rent": {"manager": 50000, "director": 100000, "vp": 200000, "svp": 300000, "ceo": 2000000}, + "governmentFee": {"manager": null, "director": 10000, "vp": 30000, "svp": 50000, "ceo": 500000}, + "donation": {"manager": null, "director": 10000, "vp": 20000, "svp": 100000, "ceo": null}, + "tax": {"manager": 500000, "director": 1000000, "vp": 2000000, "svp": 3000000, "ceo": 5000000}, + "other": {"manager": 10000, "director": 20000, "vp": 30000, "svp": 50000, "ceo": 500000} + }, + "approvalHierarchy": "以组织关系为基准的逐级审批，特殊事项可越级至终审岗" + }, + "审批时限": { + "manager": "三个工作日内完成审批", + "imagingProcessing": "一个工作日内处理完毕", + "paymentProcessing": "三个工作日内处理完毕" + }, + "成本中心归属原则": ["责任原则", "受益原则"], + "归口管理部门": { + "办公室（党委办公室）": ["党建支出", "公务车支出"], + "工会委员会": ["工会支出"], + "营销中心": ["投标业务支出", "机构营销业务支出", "客户培训", "销售退款"], + "品牌及市场运营中心": ["广告费", "业务宣传", "对外捐赠"], + "组织人事部": ["薪酬福利（不含食堂、误餐）", "外聘劳务", "员工保险", "探亲差旅", "其他福利"], + "人力资源服务部": ["招聘业务", "员工教育培训"], + "计划财务部": ["备用金", "差旅费", "市内交通费", "出国经费", "误餐费", "税金及附加", "审计评估", "财务费用", "客服及商务"], + "产业投资部": ["股权投资", "并购业务"], + "证券与法律事务部": ["法律事务", "上市信披", "商标注册"], + "产品规划设计部": ["知识产权", "信息技术咨询", "研发活动"], + "DAP研发中心": ["研发过程中对外单位的检测、评测、测试及化验"], + "信息管理部": ["IT类资产购置", "租入", "运维", "修理", "网络使用费"], + "后勤服务部": ["非IT类资产", "财产保险", "食堂", "办公费用", "商旅统付结算"] + }, + "禁止事项": { + "批办分离": "经办人和审批人不得为同一人", + "budgetFirst": "预算外支出需先履行预算审批程序", + "noNonEmployeeLoan": "非正式员工不得申请备用金借款", + "noUnbudgetedDonation": "未纳入预算的对外捐赠不得执行", + "noWelfarePlanExpenses": "未纳入福利计划的福利项目不得列支和报销" + } + } +} \ No newline at end of file diff --git a/server/storage/公司支出管理办法2024_财务指南.md b/server/storage/公司支出管理办法2024_财务指南.md new file mode 100644 index 0000000..954e6b8 --- /dev/null +++ b/server/storage/公司支出管理办法2024_财务指南.md @@ -0,0 +1,324 @@ +# 公司支出管理办法（2024）财务报销指南 + +> **文件来源**：远光软件股份有限公司 · 远光制度〔2024〕14号 +> **颁布日期**：2024年4月17日 +> **密级**：商密【中】 + +--- + +## 一、总则 + +### 1.1 目的 +适应公司业务发展需要，优化完善支出和报销标准，规范支出业务审批和报销过程，防范经营风险。 + +### 1.2 适用范围 +- 公司各类**成本费用**和**资本性支出** +- 公司各部门、分支机构（非独立法人）、全资子公司 +- 控股子公司应参照本办法制订，报公司计划财务部备案后执行 + +### 1.3 管理原则 +| 原则 | 说明 | +|------|------| +| **预算先行** | 应在预算目标范围内支出，预算外支出需履行预算审批程序 | +| **厉行节约、效益优先** | 规范开展支出业务活动 | +| **分级授权、分类控制** | 按管理岗位执行审批权限 | +| **批办分离** | 经办人和审批人不得为同一人 | + +--- + +## 二、重点支出报销规则 + +### 2.1 备用金借款 + +| 项目 | 规则 | +|------|------| +| **定义** | 公司借支给正式员工，用于支付与公司经济业务相关的、必须预支且尚不具备报销条件的费用 | +| **借款人资格** | 仅限正式员工，非正式员工不得申请 | +| **额度上限** | 原则上不得超过**1万元** | +| **还款要求** | 按季定期清理，季度末不能及时报账核销的，需向分管领导申请延期审批，**不得跨年** | +| **核心原则** | "**前款不清、后款不借**"，严禁以各种名义挪用公司资金 | + +--- + +### 2.2 市内交通费 + +| 项目 | 规则 | +|------|------| +| **定义** | 员工为公司生产经营活动在工作所在地发生的市内交通费（不含正常上下班通勤费） | +| **报销方式** | 凭据报销，需与工作实际相符 | +| **禁止项** | 严禁报销与工作无关的交通费；**不接受**充值预付费方式的交通费 | +| **出租车使用** | 仅限以下情况使用，由部门负责人从严管理：
① 紧急公务
② 接送客户
③ 夜间工作至22:00后
④ 其他确有需要的特别情形 | +| **推荐方式** | 鼓励选择公交、地铁等公共交通出行 | + +--- + +### 2.3 差旅费 + +#### 2.3.1 交通费报销标准 + +**飞机乘坐规定：** +| 职级 | 规定 | +|------|------| +| 公司领导/高层经理/中层经理（P5及以上、外聘专家） | 经济舱 | +| 基层经理（P4及以下） | 需事前经部门负责人审批；P4应选乘6折及以下、P1-P3应选乘5折及以下 | + +**其他交通工具：** +| 类型 | 报销标准 | +|------|----------| +| 火车 | 火车硬席（硬卧、硬座）、高铁/动车二等座，全列软席列车二等软座 | +| 轮船 | 三等舱 | +| 其他交通工具（不含小汽车） | 凭据报销 | + +> **备注：** +> - 夜间乘坐高铁/动车6小时以上时，可选乘卧铺 +> - 超标20%以内由部门负责人审批，超标20%以上需分管领导审批 +> - 公司已为员工购买商业保险（含交通险），出差期间保险费不再报销 +> - 往返机场、车站、港口原则上应选公交车、轨道交通 + +**超标审批规则：** +| 超标幅度 | 审批要求 | +|----------|----------| +| 20%以内 | 部门负责人审批 | +| 20%以上 | 分管领导审批 | + +#### 2.3.2 住宿费报销标准 + +**国内住宿限额标准（单位：人民币元）** + +| 职级 | 直辖市/特区/港澳台 | 省会城市 | 其他地区 | +|------|---------------------|----------|----------| +| 公司领导（P8及以上） | 800 | 500 | 400 | +| 高层经理（P7） | 700 | 450 | 400 | +| 中层经理、基层经理（P4～P6、外聘专家） | 600 | 400 | 350 | +| 其他员工 | 500 | 350 | 300 | + +> **超标审批**：超标20%以内部门负责人审批，20%以上需分管领导审批 + +#### 2.3.3 出差补贴标准（单位：人民币元/天） + +| 补助类型 | 直辖市/特区/西藏 | 其他地区国内 | 港澳台 | 国外 | +|----------|-------------------|---------------|--------|------| +| **餐补**（自行解决餐食） | 75 | 55~65 | 140 | 175 | +| **基本补助**（基本出差补贴） | 35 | 35 | 110 | 90~100 | +| **合计** | 110 | 90~100 | 250 | 265~275 | + +> **注意**：因组织安排、销售、推广、调研、培训、会议、研讨、借调等出差，主办方统一安排餐食的，**不再报销餐补** + +#### 2.3.4 其他差旅注意事项 + +| 情况 | 处理规则 | +|------|----------| +| 订票/签转/退票费 | 凭据报销，由部门负责人审核确认 | +| 出差记录链条中断 | 应提供：登机牌、通行记录、租车记录、支付记录、审批邮件/短信/微信等 | +| 绕道回家省亲 | 绕道交通费扣除出差直线单程费，多出部分自理；绕道和在家期间不报销住宿费和出差补贴 | +| 交通原始凭据丢失 | 提供情况说明+订单详情+支付截图，可按票面价值**75%**报销；未提供的，不予报销 | +| 探亲路费 | 严格遵循《公司员工探亲管理办法》，不享受出差补贴；原始凭据丢失不允许报销 | +| 调动行李邮寄费 | 每人每公里**1元以内**凭据报销，超过部分自理 | +| 境外出差 | 应单列预算、**事前履行**经费申请与审批程序 | + +--- + +### 2.4 业务招待费 + +| 项目 | 规则 | +|------|------| +| **定义** | 用于接待客户和相关单位的餐饮等合理支出（正常生产经营管理过程中） | +| **报销要求** | 未能"公对公"结算的，应附"向供应商付款凭据"佐证 | + +--- + +### 2.5 会议费 + +| 场景 | 规则 | +|------|------| +| **禁止项** | 不得列支与会议无关的旅游观光、宴请、礼品馈赠等支出 | +| **事前审批** | 经费预算**3万元及以上**的公司内部会议、研讨与集中培训，需事前报请**公司总裁**审批 | +| **报销附件** | 经审批的会议申请与预算、会议通知、参会人员签到表、会议开支明细；会务费发票应附服务方费用明细清单 | +| **参加外部会议** | 应附会议通知、参会回执等业务佐证材料 | + +--- + +### 2.6 广告宣传费 + +| 类型 | 说明 | 报销要求 | +|------|------|----------| +| **广告费** | 公司通过各种公开媒体宣传所发生的费用 | 附广告投放等业务佐证材料 | +| **业务宣传费** | 公司自身开展宣传与营销活动所发生的费用，包括印有公司标志的礼品、纪念品等 | 附活动方案、费用预算等业务佐证材料，遵循公司采购与物资管理相关规定 | + +--- + +### 2.7 培训费 + +| 项目 | 规则 | +|------|------| +| **报销资格** | 按《公司员工教育培训管理办法》认定标准执行 | +| **符合标准的培训** | 期间主要交通费（往返）、住宿费按出差规定标准执行，其他费用自理 | + +--- + +### 2.8 通信费 + +| 项目 | 规则 | +|------|------| +| **包含范围** | 电话、传真、集团网、网络连接等支出 | +| **员工通讯费** | 按《公司员工因公通讯费用实施细则》执行 | + +--- + +### 2.9 邮递费 + +| 场景 | 要求 | +|------|------| +| 员工报销 | 应附快递底单 | +| 单位统一结算 | 应附寄件明细清单与支出分摊表 | + +--- + +### 2.10 薪酬福利支出 + +| 场景 | 规则 | +|------|------| +| 职工薪资、奖励提成、福利费 | 按公司相关制度规定执行 | +| 临时奖励及福利支出 | 需事先计划并报公司总裁审批，具体支出时由分管领导根据已批准计划审批 | +| 职工福利费 | 由组织人事部实行年度计划管理，未纳入福利计划的福利项目不得列支和报销 | +| 职工活动支出 | 按照《公司团建管理办法》或《工会经费管理办法》执行 | + +--- + +### 2.11 对外捐赠支出 + +| 项目 | 规则 | +|------|------| +| **归口管理** | 品牌及市场运营中心 | +| **预算要求** | 严格预算单控，**未纳入对外捐赠预算的，不得对外捐赠** | +| **预算内捐赠** | 业务部门提出申请 → 部门负责人审批 → 品牌及市场运营中心归口审核 → 分管领导审批后执行 | +| **预算外捐赠** | 需履行预算调整决策程序，纳入预算范围后方可实施 | +| **备案要求** | 捐赠完成后需将凭据资料（含发票、收据、捐赠协议、接收函、捐赠清单等）报品牌及市场运营中心备案 | + +--- + +### 2.12 涉外业务汇率标准 + +| 结算方式 | 汇率确定 | +|----------|----------| +| 人民币结算 | 凭据报销 | +| 外币结算 | 按支付凭据所载汇率折算 | +| 支付凭据未载明汇率 | 按业务发生月第一个交易日"**中国银行外汇折算价**"执行 | +| 中国银行无折算价的币种 | 按"**中国外汇交易中心参考汇率**"执行 | + +--- + +## 三、报销申请与审批 + +### 3.1 申请方式 + +| 项目 | 规则 | +|------|------| +| **系统申请** | 通过公司财务信息化系统填写"系统单据"，**不接受纸质申请单据** | +| **票据要求** | 除员工薪酬、个人劳务报酬、出差补贴、专项补贴、往来款项支付等业务外，其他支出均需提交**税务机关认可的票据** | +| **发票类型** | 原则上应取得**增值税专用发票**；汇总开具的发票应附税控系统明细清单 | +| **发票缺失处理** | 应取得但未取得增值税专用发票的，经办人应在"系统单据"中说明原因 | + +### 3.2 申请时限 + +| 类型 | 规则 | +|------|------| +| **一般报销时限** | 业务完成日至影像资料挂接系统单据日不超过**三个月** | +| **逾期处理** | 逾期需说明原因，经分管领导审批后方可报销 | +| **定期费用** | 按自然月度计算并定期发生的费用支出，需月度结束后方可报销 | +| **差旅费** | 行程结束**三个月内**提交（连续出差超过一个月时，原则上应按月报销），**逾期不予报销出差补贴** | +| **预付款项** | 原则上应在**次月底前**完成结算，不得长期挂账 | + +### 3.3 结算方式 + +| 类型 | 方式 | 说明 | +|------|------|------| +| **员工支出业务** | 公对私 | 报销申请审批通过后，公司支付给经办人 | +| **岗位支出业务** | 公对公 | 报销申请审批通过后，公司与供应商直接结算 | +| **小额支出** | 结算起点（1000元）以下，确实无法与供应商直接结算的 | 报销时应附向供应商付款凭据的截图佐证 | + +### 3.4 审批权限 + +#### 员工支出报销审批权限（单位：人民币万元） + +| 支出项目 | 部门经理/机构总经理/事业部总经理 | 总监/副总裁/高级副总裁/一级部门总经理/总工程师/各委员会主任 | 总裁 | +|----------|----------------------------------|--------------------------------------------------------------|------| +| 业务招待 | 0.5 | 1~3 | 15 | +| 因公借款 | 0.5 | 1~3 | 15 | +| 差旅费、市内交通 | 1 | 2~5 | 50 | +| 客服及商务、教育、邮递 | 1 | 2~5 | 50 | +| 其他临时性支出 | 1 | 2~5 | 50 | + +#### 岗位支出报销审批权限（单位：人民币万元） + +| 支出项目 | 部门经理/机构总经理/事业部总经理 | 总监/一级部门总经理 | 副总裁 | 高级副总裁 | 总裁 | +|----------|----------------------------------|----------------------|--------|------------|------| +| 资产采购 | 1 | 2~10 | 15 | 200 | - | +| 基建工程 | —— | 5 | 10 | - | 50 | +| 材料采购 | —— | 10 | 20 | 30 | 500 | +| 分包外包（内部单位） | —— | 10 | 20 | 30 | 500 | +| 分包外包（外部单位） | —— | 10 | 20 | 30 | 200 | +| 保证金 | 5 | 50 | 100 | 200 | 500 | +| 销售退款 | 5 | 10 | 30 | 50 | 200 | +| 房屋租金 | 5 | 10 | 20 | 30 | 200 | +| 政府规费 | - | 1 | 3 | 5 | 50 | +| 慰问救济、对外捐赠 | —— | 1 | 2 | 10 | - | +| 税费支出 | 50 | 100 | 200 | 300 | 500 | +| 其他支出 | 1 | 2 | 3 | 5 | 50 | + +> **注**：权限额度均含本数；业务流转执行以组织关系为基准的逐级审批规则；特殊事项经决策后可越级至终审岗审批 + +### 3.5 审批时限 + +| 角色 | 时限要求 | +|------|----------| +| **各级管理人员** | 应在待批单据流转至本岗位后**三个工作日内**完成审批 | +| **影像扫描** | 原则上应在**一个工作日内**处理完毕 | +| **审核与支付** | 原则上应在**三个工作日内**处理完毕 | + +--- + +## 四、成本中心归属 + +| 原则 | 说明 | +|------|------| +| **基本原则** | 基于**责任原则**与**受益原则**确定 | +| **特殊情况** | 由相关业务部门协商确定 | + +--- + +## 五、归口管理部门 + +| 部门 | 归口业务范围 | +|------|-------------| +| **办公室（党委办公室）** | 党建支出、公务车支出 | +| **工会委员会** | 工会支出 | +| **营销中心** | 投标业务支出、机构营销业务支出、客户培训、销售退款等 | +| **品牌及市场运营中心** | 广告费、业务宣传、对外捐赠 | +| **组织人事部** | 薪酬福利（不含食堂、误餐）、外聘劳务、员工保险、探亲差旅、其他福利 | +| **人力资源服务部** | 招聘业务、员工教育培训 | +| **计划财务部** | 备用金、差旅费、市内交通费、出国经费、误餐费、税金及附加、审计评估、财务费用、客服及商务 | +| **产业投资部** | 股权投资、并购业务 | +| **证券与法律事务部** | 法律事务、上市信披、商标注册 | +| **产品规划设计部** | 知识产权、信息技术咨询、研发活动 | +| **DAP研发中心** | 研发过程中对外单位的检测、评测、测试及化验 | +| **信息管理部** | IT类资产购置、租入、运维、修理、网络使用费 | +| **后勤服务部** | 非IT类资产、财产保险、食堂、办公费用、商旅统付结算 | + +--- + +## 六、附则 + +### 6.1 审核要求 +财务审核发现业务原始凭据不完整的，经办人应在**三个工作日内**补充并重新提交；经办人填单错误、业务原始凭据不合规，以及不能按时补充的，**财务退单处理**。 + +### 6.2 复核要求 +财务可要求报销人提供不限于本办法规定的佐证资料，对业务原始凭据的完整性、合规性，业务关联性、内容一致性、金额准确性进行复核。 + +### 6.3 责任承担 +经办人对支出业务的**真实性、合规性、必要性、合理性**以及业务原始凭据的**真实性、合规性、关联性、完整性**承担全部责任。 + +--- + +**文件解释权**：远光软件股份有限公司计划财务部 +**生效日期**：2024年4月17日 \ No newline at end of file diff --git a/web/src/assets/styles/views/audit-view.css b/web/src/assets/styles/views/audit-view.css index 2599585..cd98751 100644 --- a/web/src/assets/styles/views/audit-view.css +++ b/web/src/assets/styles/views/audit-view.css @@ -77,6 +77,38 @@ flex-wrap: wrap; } +.search-filter { + width: 260px; + min-height: 36px; + display: inline-flex; + align-items: center; + gap: 8px; + padding: 0 11px; + border: 1px solid #d7e0ea; + border-radius: 8px; + background: #fff; + color: #64748b; +} + +.search-filter i { + color: #94a3b8; + font-size: 16px; +} + +.search-filter input { + width: 100%; + min-width: 0; + border: 0; + outline: 0; + background: transparent; + color: #0f172a; + font-size: 13px; +} + +.search-filter input::placeholder { + color: #94a3b8; +} + .filter-btn, .create-btn, .row-action { diff --git a/web/src/components/layout/SidebarRail.vue b/web/src/components/layout/SidebarRail.vue index ba15139..7335fe8 100644 --- a/web/src/components/layout/SidebarRail.vue +++ b/web/src/components/layout/SidebarRail.vue @@ -77,7 +77,7 @@ const sidebarMeta = { approval: { label: '审批中心', badge: '12' }, chat: { label: 'AI 助手' }, policies: { label: '知识管理' }, - audit: { label: '技能中心' }, + audit: { label: '任务规则中心' }, employees: { label: '员工管理' }, settings: { label: '系统设置' } } diff --git a/web/src/composables/useNavigation.js b/web/src/composables/useNavigation.js index b1fa861..e9d13c2 100644 --- a/web/src/composables/useNavigation.js +++ b/web/src/composables/useNavigation.js @@ -56,11 +56,11 @@ export const navItems = [ }, { id: 'audit', - label: '技能中心', - navHint: '查看和管理技能配置', + label: '任务规则中心', + navHint: '查看和管理任务规则配置', icon: icons.skill, - title: '技能中心', - desc: '集中管理技能配置、提示词结构、测试样例与发布状态。' + title: '任务规则中心', + desc: '集中管理规则文件、外部 MCP 服务与定时任务调度。' }, { id: 'employees', diff --git a/web/src/views/AuditView.vue b/web/src/views/AuditView.vue index 89dd7de..8126b2a 100644 --- a/web/src/views/AuditView.vue +++ b/web/src/views/AuditView.vue @@ -8,7 +8,7 @@
{{ selectedSkill.typeLabel }}

{{ selectedSkill.name }}

{{ selectedSkill.summary }}

-
+
审核人：{{ selectedSkill.reviewer }} @@ -19,13 +19,13 @@
-
+
-
+

Markdown 规则内容

-

管理员直接编辑该 Skill 对应的 .md 审查规则文件内容。

+

管理员直接编辑该规则对应的 .md 审查规则文件内容。

-
+

{{ selectedSkill.detailTitle }}

@@ -84,7 +84,7 @@
-
+

{{ selectedSkill.outputTitle }}

@@ -114,7 +114,7 @@
-