YG-Soft/X-Financial
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
caoxiaozhu
2026-05-15 06:58:21 +00:00
parent 45abd36430
commit 4f3556a38b
35 changed files with 8257 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
document/development/agent/agent plan/00_README.md Normal file
View File

@@ -0,0 +1,58 @@
# Agent Plan 文档索引
本目录描述 X-Financial 后续要建设的双 Agent 财务智能架构。
核心目标：
- 建立一套共享的语义本体协议，统一理解用户问题、定时任务和规则触发上下文。
- 建设两套职责边界清晰的 Agent：
- Hermes：后台数字员工，负责内循环定时任务、风险巡检、统计、知识维护。
- 自建 Agent：用户流程助手，负责用户交互、流程操作、解释、查询、草稿生成。
- 建设 Agent Orchestrator，统一负责路由、权限、工具调用、审计和失败处理。
- 让规则中心、MCP、知识库、数据库查询和任务系统使用同一套语义协议。
## 与一周计划的关系
`document/development/agent week plan` 是一周开发路线图，只描述每天要完成的大方向和交付结果。
本目录是具体架构与实现依据，包含：
- 架构设计。
- 数据协议。
- Agent 职责。
- Orchestrator 流程。
- OCR、知识库、规则生命周期。
- 每天 daily 文档会引用到的设计依据。
执行时按这个顺序阅读：
1. 先看 `document/development/agent week plan/MASTER_TODO.md`，确认今天做什么。
2. 再看本目录的架构文档，理解为什么这样做。
3. 最后进入 `document/development/agent week plan/` 对应 Day 文档，在同一份文档中按详细执行清单开发。
推荐阅读顺序：
1. [01_overall_architecture.md](./01_overall_architecture.md)
2. [02_semantic_ontology.md](./02_semantic_ontology.md)
3. [03_agent_responsibilities.md](./03_agent_responsibilities.md)
4. [04_orchestrator_and_runtime_flow.md](./04_orchestrator_and_runtime_flow.md)
5. [05_development_roadmap.md](./05_development_roadmap.md)
6. [06_data_contracts_and_governance.md](./06_data_contracts_and_governance.md)
7. [07_capability_registry.md](./07_capability_registry.md)
8. [08_permission_confirmation.md](./08_permission_confirmation.md)
9. [09_observability_and_trace.md](./09_observability_and_trace.md)
10. [10_evaluation_and_testset.md](./10_evaluation_and_testset.md)
11. [11_ocr_invoice_architecture.md](./11_ocr_invoice_architecture.md)
12. [12_llm_wiki_knowledge_architecture.md](./12_llm_wiki_knowledge_architecture.md)
13. [13_rule_formation_lifecycle.md](./13_rule_formation_lifecycle.md)
14. [14_financial_document_canonical_model.md](./14_financial_document_canonical_model.md)
15. [15_feedback_learning_loop.md](./15_feedback_learning_loop.md)
16. [../agent week plan/00_README.md](<../agent week plan/00_README.md>)
开发原则：
- 先语义协议，后 Agent 能力。
- 先只读和建议，后写入和流程动作。
- 先人工确认，后有限自动化。
- 所有财务关键动作必须可审计、可回滚、可追责。
- 所有 Agent 能力必须注册、分级、可评测、可追踪。

163
document/development/agent/agent plan/01_overall_architecture.md Normal file
View File

@@ -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: 增加知识候选和规则优化闭环
```

457
document/development/agent/agent plan/02_semantic_ontology.md Normal file
View File

@@ -0,0 +1,457 @@
# 语义本体协议设计
## 1. 定位
语义本体协议是用户问题、定时任务、规则中心、MCP、数据库查询和 Agent 之间的统一中间层。
它解决的问题是：
- 用户到底在问哪个业务域？
- 这属于什么场景？
- 用户想做什么？
- 问题中涉及哪些对象？
- 有没有时间、金额、状态、部门等过滤条件？
- 是否涉及风险？
- 下一步应该查知识库、查数据库、跑规则、调 MCP，还是追问？
## 2. 第一版核心字段
第一版建议只强制落 8 个字段。
```json
{
"domain": "",
"scenario": "",
"intent": "",
"entities": [],
"time_range": {},
"constraints": {},
"risk_signals": [],
"next_step": ""
}
```
### 2.1 domain
一级业务域。
建议枚举：
```text
reimbursement
accounts_receivable
accounts_payable
general_finance
system_operation
```
含义：
- `reimbursement`：报销、差旅、发票、补件。
- `accounts_receivable`：应收账款、客户开票、收款、账龄。
- `accounts_payable`：应付账款、供应商发票、付款、对账。
- `general_finance`：通用财务知识、制度、统计。
- `system_operation`：系统巡检、任务运行、规则维护、MCP 健康检查。
### 2.2 scenario
细分场景。
报销：
```text
travel_reimbursement
daily_expense
invoice_validation
attachment_review
policy_overrun
reimbursement_audit
```
应收：
```text
customer_invoice
collection_followup
receivable_aging
payment_matching
bad_debt_risk
contract_receivable
```
应付：
```text
vendor_invoice
payment_request
payable_aging
vendor_reconciliation
invoice_matching
cash_outflow_forecast
```
系统运营：
```text
daily_risk_scan
daily_finance_statistics
knowledge_accumulation
mcp_health_check
rule_quality_review
```
### 2.3 intent
用户或任务的意图。
建议枚举：
```text
query
explain
create
validate
summarize
reconcile
monitor
predict
remind
generate
optimize
```
### 2.4 entities
识别出的业务对象。
统一结构：
```json
{
"type": "invoice",
"value": "INV-202605001",
"normalized_value": "INV-202605001",
"role": "target",
"confidence": 0.92
}
```
常见实体：
```text
employee
department
customer
vendor
invoice
contract
reimbursement_request
payment_order
receipt
bank_transaction
cost_center
project
policy
approval_node
rule
task
```
### 2.5 time_range
统一描述时间。
```json
{
"raw": "上个月",
"start": "2026-04-01",
"end": "2026-04-30",
"granularity": "month"
}
```
Hermes 定时任务也使用同一字段。
例如每日风险巡检：
```json
{
"raw": "昨日",
"start": "2026-05-09",
"end": "2026-05-09",
"granularity": "day"
}
```
### 2.6 constraints
查询、判断或执行条件。
```json
{
"status": "overdue",
"aging_days": ">30",
"amount": {
"operator": ">",
"value": 50000,
"currency": "CNY"
},
"department": "销售部",
"risk_level": ["medium", "high"]
}
```
### 2.7 risk_signals
风险信号。
建议枚举：
```text
duplicate_invoice
missing_attachment
policy_overrun
over_budget
overdue_receivable
bad_debt_risk
vendor_payment_risk
payment_mismatch
contract_mismatch
cashflow_pressure
mcp_unavailable
rule_quality_issue
```
### 2.8 next_step
下一步动作。
建议枚举：
```text
answer
ask_clarification
query_database
run_rule
call_mcp
search_knowledge
create_draft
create_task
generate_report
notify_user
escalate_to_human
```
## 3. 扩展字段
后续可以增加：
```json
{
"schema_version": "1.1",
"confidence": 0.86,
"ambiguity": [],
"missing_slots": [],
"required_capabilities": [],
"normalized_query": "",
"permission_scope": {},
"audit_tags": []
}
```
## 4. 混合语义解析架构
第一版可上线实现不应只依赖关键词和正则。
推荐采用：
```text
输入上下文装配
用户文本 + 页面上下文 + 附件名称 + OCR/VLM 摘要
↓
预抽取
时间、金额、单号、显式对象
↓
LLM 结构化解析
输出 scenario / intent / entities / missing_slots / ambiguity
↓
Schema 校验
JSON 解析、字段枚举、必填校验、类型归一化
↓
规则兜底
模型失败、低置信度或字段缺失时回退到规则解析
↓
澄清追问
低置信度、歧义、缺槽位时不允许直接查库
```
设计原则：
- 模型优先负责“理解意图和场景”。
- 规则优先负责“校验、补全和兜底”。
- 附件名称、OCR、VLM 结果只能作为证据，不等于已确认事实。
- 所有语义输出都必须标记置信度和来源。
## 5. 推荐新增字段
为支持模型优先解析，建议在扩展字段中至少增加：
```json
{
"missing_slots": [],
"ambiguity": [],
"field_confidence": {},
"field_source": {},
"attachment_context": [],
"parse_strategy": "llm_primary_with_rule_fallback"
}
```
字段说明：
- `missing_slots`：还缺哪些关键字段，例如费用类型、单据号、客户单位。
- `ambiguity`：当前可能混淆的理解结果。
- `field_confidence`：字段级置信度，而不是只给整体分数。
- `field_source`：字段来自 `llm`、`rule`、`ocr`、`vlm` 还是 `user_context`。
- `attachment_context`：本次可供语义解析使用的附件摘要。
- `parse_strategy`：标记本次是模型主解析还是规则回退。
## 6. 叙述型财务输入
语义层必须支持“不是查询句”的自然叙述。
典型样例：
```text
我今天去客户现场，招待了客户，花销了1000元
我垫付了打车费和餐费，帮我看看怎么报
上传了三张票，帮我整理成报销草稿
```
这类输入不能默认识别成 `query`。
建议默认策略：
- 优先识别为 `reimbursement` 域。
- 场景优先落到 `daily_expense`、`travel_reimbursement` 或 `attachment_review`。
- 意图优先落到 `create`、`generate` 或 `validate`。
- 缺失关键字段时返回 `ask_clarification`，而不是直接查数据库。
## 7. 模糊短句与澄清规则
以下输入应优先追问：
```text
我要报销
这个为什么还没处理
帮我看一下这个
上传好了，下一步呢
```
处理原则：
- 不允许直接执行工具。
- 不允许直接落到应收、应付查询。
- 必须生成澄清问题。
- 必须在审计中记录触发追问的原因。
扩展原则：
- 先不要把所有字段都做成数据库列。
- 语义结果建议存 JSONB。
- 使用 `schema_version` 管理版本。
- Orchestrator 只依赖稳定字段。
- 新字段以可选方式加入，不影响老任务。
## 4. 示例
### 4.1 用户查询应收账龄
用户问：
```text
上个月哪些客户应收逾期超过 30 天？
```
解析：
```json
{
"domain": "accounts_receivable",
"scenario": "receivable_aging",
"intent": "query",
"entities": [
{
"type": "customer",
"value": "客户",
"role": "group_by"
}
],
"time_range": {
"raw": "上个月",
"start": "2026-04-01",
"end": "2026-04-30",
"granularity": "month"
},
"constraints": {
"aging_days": ">30",
"status": "overdue"
},
"risk_signals": ["overdue_receivable"],
"next_step": "query_database"
}
```
### 4.2 用户解释发票拦截
用户问：
```text
这张发票为什么报销被拦截？
```
解析：
```json
{
"domain": "reimbursement",
"scenario": "invoice_validation",
"intent": "explain",
"entities": [
{
"type": "invoice",
"value": "这张发票",
"role": "target"
}
],
"time_range": {},
"constraints": {},
"risk_signals": ["unknown"],
"next_step": "run_rule"
}
```
### 4.3 Hermes 每日风险巡检
任务配置：
```json
{
"domain": "reimbursement",
"scenario": "daily_risk_scan",
"intent": "monitor",
"entities": [],
"time_range": {
"raw": "昨日"
},
"constraints": {
"risk_level": ["medium", "high"]
},
"risk_signals": [
"duplicate_invoice",
"missing_attachment",
"policy_overrun"
],
"next_step": "run_rule"
}
```

178
document/development/agent/agent plan/03_agent_responsibilities.md Normal file
View File

@@ -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
解析语义
查询报销单
读取规则命中
检索制度条款
组织解释
给出补件建议
```

385
document/development/agent/agent plan/04_orchestrator_and_runtime_flow.md Normal file
View File

@@ -0,0 +1,385 @@
# Agent Orchestrator 与运行流程
## 1. Orchestrator 定位
Agent Orchestrator 是双 Agent 架构的调度中心。
它不负责生成最终答案，而是负责：
- 接收用户请求或定时任务。
- 调用语义解析。
- 判断处理方。
- 选择工具。
- 检查权限。
- 记录审计。
- 管理失败重试。
- 控制高风险动作确认。
## 2. 运行主流程
```text
输入
用户消息 / 页面按钮 / 定时任务 / 系统事件
↓
上下文装配
页面对象 / 附件名称 / OCR 摘要 / VLM 摘要 / 用户角色 / conversation_id / draft_claim_id
↓
语义解析
LLM 主解析 + 规则兜底，输出 ontology_json
↓
语义校验
confidence / missing_slots / ambiguity / permission 初判
↓
Orchestrator 决策
判断 agent = hermes | user_agent
判断 tool = rule | mcp | db | knowledge | task
↓
权限检查
用户权限 / 任务权限 / 数据范围
↓
业务写入
报销草稿创建 / 报销草稿更新 / 用户确认后提交
↓
工具执行
规则中心 / MCP / 数据库 / 知识库 / 任务系统
↓
Agent 汇总
Hermes 报告 / User Agent 回答
↓
审计记录
保存输入、语义、工具、结果、动作
```
## 3. 路由规则
### 3.1 Hermes 路由
满足以下条件之一，进入 Hermes：
```text
source = schedule
source = system_event
intent = monitor
intent = summarize and no active user session
next_step = generate_report and task_type is batch
scenario in daily_risk_scan / knowledge_accumulation / mcp_health_check
```
补充约束：
- 这里的 Hermes 指系统后台真实 Hermes 进程或 Hermes CLI，不是前端概念上的 “Hermes 模式”。
- Orchestrator 负责路由、权限、审计和 Trace，不负责替代 Hermes 自身执行。
- 当前阶段允许保留本地 fallback，但必须预留真实 Hermes 进程调用入口。
### 3.2 User Agent 路由
满足以下条件之一，进入自建 Agent：
```text
source = user_message
source = page_action
intent = query / explain / create / validate / reconcile
requires_user_context = true
next_step = ask_clarification
next_step = create_draft
```
### 3.3 工具路由
```text
next_step = query_database
调用数据库查询服务
next_step = run_rule
调用规则中心
next_step = call_mcp
调用 MCP 服务
next_step = search_knowledge
调用知识库检索
next_step = create_task
调用任务系统
next_step = create_expense_claim_draft
创建 expense_claims / expense_claim_items 草稿
next_step = update_expense_claim_draft
回写报销主表、明细和附件关联
next_step = submit_expense_claim
用户确认后更新 expense_claims.status = submitted
next_step = ask_clarification
返回追问
```
### 3.4 低置信度与缺槽位保护
当满足以下任一条件时，不允许直接进入数据库、MCP 或高风险流程：
```text
confidence < threshold
missing_slots 非空
ambiguity 非空
输入为叙述型报销，但缺少关键报销信息
```
处理方式：
```text
next_step = ask_clarification
selected_agent = user_agent
tool_count = 0
```
### 3.5 叙述型报销输入保护
像下面这类文本：
```text
我今天去客户现场，招待了客户，花销了1000元
我垫付了交通费和午餐费
我上传了票据，帮我整理一下
```
不能因为出现“客户”就落到应收查询。
Orchestrator 应依赖语义层返回的 `scenario + intent + missing_slots` 做决策，而不是二次猜测文本关键词。
### 3.6 报销建单与状态流转边界
当 `scenario = expense` 且已满足最小建单槽位时：
```text
next_step = create_expense_claim_draft
status = draft
```
当用户继续补充金额、地点、客户、参与人、附件时：
```text
next_step = update_expense_claim_draft
status 保持 draft
```
当用户明确说“提交报销”并完成确认时：
```text
next_step = submit_expense_claim
status = submitted
requires_confirmation = true
```
以下状态不应由 User Agent 直接改写：
```text
approved
rejected
paid
```
这些状态应由审批流、财务支付流或受控后台同步更新。
### 3.7 结构化核对回路
当 `scenario = expense` 且当前仍存在缺槽位、附件待核对或票据需拆单时，不直接返回一段自由文本，而是返回结构化核对结果：
```text
result.review_payload
intent_summary
body_message
slot_cards
risk_briefs
document_cards
claim_groups
confirmation_actions = 取消 / 修改 / 保存草稿或下一步
edit_fields
```
前端正文区只展示简洁提示，右侧展示字段、风险、票据与分单明细。
### 3.8 会话续接与重识别
用户对话不是无状态调用。Orchestrator 需要携带以下会话字段继续当前报销流程：
```text
conversation_id
draft_claim_id
conversation_history
review_action
review_form_values
```
其中：
```text
review_action = edit_review
表示用户基于结构化模板修改识别结果，需要重新进入语义识别
review_action = save_draft
表示信息未补齐，但允许先保存报销草稿
review_action = next_step
表示用户确认当前识别结果，可进入下一步流转
```
## 4. 用户流程示例
用户输入：
```text
上个月哪些客户应收逾期超过 30 天？
```
流程：
```text
Step 1: User Agent 接收消息
Step 2: semantic_parser 输出 ontology_json
Step 3: Orchestrator 识别 domain = accounts_receivable
Step 4: next_step = query_database
Step 5: 权限检查用户是否可看应收数据
Step 6: 查询应收账龄表
Step 7: User Agent 汇总结果
Step 8: 返回客户清单、金额、逾期天数、风险说明
```
## 5. Hermes 任务示例
任务：
```text
每日风险巡检
```
流程：
```text
Step 1: 任务调度器在 02:00 触发
Step 2: Orchestrator 构造 ontology_json
Step 3: 路由给 Hermes
Step 4: Hermes 拉取昨日业务快照
Step 5: 执行规则中心规则
Step 6: 调用 MCP 验真、账款流水
Step 7: 生成风险报告
Step 8: 写入风险工单
Step 9: 记录任务日志
Step 10: 通知财务风控组
```
### 5.1 Hermes 后台执行方式
推荐最小形态：
```text
任务系统 / 手动触发 API
↓
Orchestrator 生成 run_id、任务上下文、权限信息
↓
后端调用系统 Hermes CLI 或 Hermes 后台进程
↓
Hermes 执行知识同步 / 风险巡检 / 规则草稿形成
↓
结果回写 AgentRun / ToolCall / 审计日志
```
约束：
- Hermes 运行使用系统级配置，不在任务代码里再写一套模型配置。
- Hermes 运行失败要记录 stderr 或等价错误摘要。
- Hermes 输出的知识候选和规则草稿必须回写为结构化结果，不只保留终端文本。
## 5A. 用户报销建单示例
用户输入：
```text
我今天去客户现场，招待了客户，花销了1000元
```
流程：
```text
Step 1: User Agent 接收消息
Step 2: semantic_parser 输出 ontology_json
Step 3: Orchestrator 判断 scenario = expense, intent = draft
Step 4: 若缺客户、参与人、附件，则 next_step = ask_clarification
Step 5: 补齐最小槽位后，next_step = create_expense_claim_draft
Step 6: 创建 expense_claims / expense_claim_items
Step 7: 若有附件，则挂接 document_assets / expense_item_documents
Step 8: 用户确认提交后，next_step = submit_expense_claim
Step 9: 更新 expense_claims.status = submitted
Step 10: 写入 AgentRun、ToolCall、AuditLog
```
## 6. 审计日志
每次 Agent 运行都应该写入审计。
建议字段：
```json
{
"id": "",
"source": "user_message | schedule | system_event",
"agent": "hermes | user_agent",
"user_id": "",
"task_id": "",
"ontology_json": {},
"tools_called": [],
"permission_scope": {},
"result_summary": "",
"action_taken": "",
"requires_confirmation": false,
"created_at": ""
}
```
建议补充 Trace 字段：
```json
{
"semantic_provider": "",
"semantic_model": "",
"semantic_prompt_version": "",
"semantic_parse_strategy": "llm_primary | rule_fallback",
"semantic_fallback_reason": "",
"semantic_latency_ms": 0
}
```
## 7. 失败处理
### 7.1 用户交互失败
```text
数据库查询失败
返回“暂时无法查询”，记录错误
缺少关键字段
返回追问
权限不足
返回无权限说明
MCP 不可用
返回降级说明，必要时生成待处理项
```
### 7.2 Hermes 任务失败
```text
任务失败
自动重试 3 次
部分 MCP 失败
标记 partial_success
数据不完整
生成异常任务日志
连续失败
通知管理员
```

458
document/development/agent/agent plan/05_development_roadmap.md Normal file
View File

@@ -0,0 +1,458 @@
# 分阶段开发计划
## Phase 0：准备阶段
目标：统一概念和边界，不写复杂功能。
### Step 0.1 明确术语
产出：
- 规则：`.md` 审查规则文件。
- 技能：可复用的 Agent 能力，如审批意见生成、风险解释。
- MCP：外部服务连接。
- 任务：定时或批量运行的后台作业。
- Hermes：后台数字员工。
- User Agent：用户流程助手。
- Orchestrator：调度和路由层。
- Ontology：语义本体协议。
### Step 0.2 冻结第一版语义字段
第一版只强制 8 个字段：
```text
domain
scenario
intent
entities
time_range
constraints
risk_signals
next_step
```
### Step 0.3 建立设计文档
产出：
- 本目录所有文档。
- 后续数据库表设计草案。
- API 合同草案。
## Phase 1：任务规则中心基础建设
目标：先把管理后台搭起来。
### Step 1.1 完成前端信息架构
页签：
```text
规则 / 技能 / MCP / 任务
```
规则详情：
- Markdown 编辑器。
- 审核人。
- 审核状态。
- 版本列表。
- 版本切换确认。
技能详情：
- 技能配置。
- 输入上下文。
- 输出契约。
- 测试样例。
- 依赖能力。
MCP 详情：
- 服务地址。
- 鉴权方式。
- 权限范围。
- 健康检查。
- 调用记录。
任务详情：
- Cron。
- 运行窗口。
- 输入范围。
- 产出对象。
- 最近运行。
### Step 1.2 建立后端基础模型
建议表：
```text
agent_rules
agent_skills
agent_mcp_services
agent_tasks
agent_asset_versions
agent_asset_reviews
```
第一阶段可以先不做完整执行，只做 CRUD。
### Step 1.3 规则版本与审核
规则上线流程：
```text
草稿
↓
提交审核
↓
审核通过
↓
上线
```
关键约束：
- 没有审核人不能上线。
- 没有审核通过不能上线。
- 上线必须生成新版本。
- 历史版本只读。
## Phase 2：OCR 与财务单据标准模型
目标：让发票、附件、报销单和账款流水先标准化。
### Step 2.1 附件上传与文件分类
识别：
- 发票。
- 行程单。
- 合同。
- 付款凭证。
- 审批截图。
### Step 2.2 OCR MCP 接入
把附件转成结构化字段。
### Step 2.3 Invoice 标准模型
统一 OCR、MCP、用户填写和业务系统字段。
### Step 2.4 人工修正
允许财务人员修正 OCR 字段，并写入反馈池。
### Step 2.5 规则中心接入 OCR 结果
重复发票、附件完整性、金额不一致等规则开始使用标准模型。
## Phase 3：语义本体服务
目标：用户问题和任务配置都能转成 ontology_json。
### Step 3.1 建立 semantic_parser API
接口：
```text
POST /api/v1/semantic/parse
```
输入：
```json
{
"source": "user_message",
"text": "上个月哪些客户应收逾期超过 30 天？",
"context": {}
}
```
输出：
```json
{
"domain": "accounts_receivable",
"scenario": "receivable_aging",
"intent": "query",
"entities": [],
"time_range": {},
"constraints": {},
"risk_signals": [],
"next_step": "query_database"
}
```
### Step 3.2 建立模型优先解析器
要求：
- 使用运行时模型配置，而不是写死单一 provider。
- 输入包括文本、上下文、附件摘要和预抽取字段。
- 输出必须是结构化 JSON，而不是自由文本。
- 输出必须经过 Schema 校验。
- 模型失败时必须回退到规则解析。
### Step 3.3 建立 ontology schema 表
建议表：
```text
semantic_ontology_schemas
semantic_parse_logs
```
字段：
```text
id
schema_version
schema_json
status
created_at
updated_at
```
### Step 3.4 建立字段级校验与澄清策略
至少支持：
- 缺少费用类型时追问。
- 缺少业务对象时追问。
- 短句或模糊句时追问。
- 叙述型报销输入默认走 create/generate，而不是 query。
- 低置信度时禁止工具执行。
### Step 3.5 建立解析测试集
至少覆盖：
- 报销规则解释。
- 差旅报销创建。
- 叙述型报销创建。
- 发票验真。
- 应收逾期查询。
- 应付付款状态。
- 每日风险巡检。
- 知识库维护。
- 模糊短句追问。
- 附件输入解析。
## Phase 4：LLM Wiki 知识库
目标：让制度文档、FAQ、审批经验可被 Agent 检索和引用。
### Step 4.1 文档解析与分块
上传 PDF、Word、Excel 后抽取正文并 chunk。
### Step 4.2 元数据与向量索引
为知识块打 domain、scenario、tags、版本。
### Step 4.3 知识检索 API
User Agent 可以基于语义本体查询知识。
### Step 4.4 知识候选审核
Hermes 生成 FAQ 或条款候选，人工审核后发布。
## Phase 5：Orchestrator 基础版
目标：基于 ontology_json 做确定性路由。
### Step 5.1 建立路由规则
输入：
```text
source
domain
scenario
intent
next_step
```
输出：
```text
agent = hermes | user_agent
tools = []
permission_required = []
```
### Step 5.2 建立工具网关
第一批工具：
```text
rule_engine.run
knowledge.search
database.query
mcp.call
task.create
```
### Step 5.3 建立审计日志
所有请求都记录：
- 原始输入。
- 语义 JSON。
- 路由结果。
- 工具调用。
- 输出摘要。
- 错误信息。
## Phase 6：User Agent 第一版
目标：先做只读和解释，不做强写入。
### Step 6.1 支持制度问答
流程：
```text
用户问题
-> semantic_parse
-> search_knowledge
-> User Agent 生成回答
```
### Step 6.2 支持规则解释
流程：
```text
用户问为什么被拦截
-> semantic_parse
-> run_rule
-> search_knowledge
-> User Agent 解释风险原因
```
### Step 6.3 支持业务查询
先支持：
- 报销单状态查询。
- 应收账龄查询。
- 应付付款状态查询。
### Step 6.4 支持草稿生成
只生成草稿，不直接提交。
```text
用户确认前不写核心状态
```
## Phase 7：Hermes 第一版
目标：让后台数字员工开始跑任务。
### Step 7.1 每日风险巡检
输入：
- 昨日单据。
- 发票。
- 附件。
- 付款流水。
输出：
- 风险报告。
- 风险工单。
- 风险统计。
### Step 7.2 每日财务统计
统计：
- 报销金额。
- 报账金额。
- 应收账龄。
- 应付账龄。
- 付款状态。
- 账款异常。
### Step 7.3 知识候选积累
来源：
- 审批意见。
- 驳回原因。
- 高频问答。
- 规则误报反馈。
输出：
- FAQ 候选。
- 规则优化建议。
- 制度变更摘要。
## Phase 8：MCP 接入
目标：让 Agent 能安全调用外部系统。
优先接入：
1. 发票验真 MCP。
2. 附件 OCR MCP。
3. 银行流水 MCP。
4. 差旅平台 MCP。
5. ERP/付款状态 MCP。
每个 MCP 必须有：
- 服务地址。
- 鉴权方式。
- 权限范围。
- 超时设置。
- 降级策略。
- 健康检查。
- 调用日志。
## Phase 9：规则形成与反馈闭环
目标：让系统持续变聪明，但不失控。
闭环：
```text
Hermes 发现问题
-> 生成规则优化建议
-> 管理员审核
-> 更新规则
-> User Agent 使用新规则解释
-> 反馈继续进入 Hermes
```
关键限制：
- Hermes 只生成候选。
- 管理员审核后才能发布。
- 所有规则变更有版本。
- 所有上线动作有审核人。
### Step 9.1 规则候选池
Hermes 从制度、风险案例、反馈中生成规则候选。
### Step 9.2 规则测试样例
每条规则上线前必须有测试样例。
### Step 9.3 反馈池
收集 OCR 修正、规则误报、Agent 回答反馈。
### Step 9.4 质量看板
统计误报率、修正率、回答满意度、MCP 失败率。

445
document/development/agent/agent plan/06_data_contracts_and_governance.md Normal file
View File

@@ -0,0 +1,445 @@
# 数据契约与治理要求
## 1. 推荐数据表
### 1.1 语义本体
```text
semantic_ontology_schemas
```
字段：
```text
id
schema_version
schema_json
status
created_by
created_at
updated_at
```
```text
semantic_parse_logs
```
字段：
```text
id
source
user_id
raw_text
ontology_json
confidence
parse_strategy
created_at
```
### 1.2 Agent 资产
```text
agent_rules
agent_skills
agent_mcp_services
agent_tasks
```
通用字段：
```text
id
code
name
description
status
owner
reviewer
config_json
created_at
updated_at
```
### 1.3 版本与审核
```text
agent_asset_versions
```
字段：
```text
id
asset_type
asset_id
version
content
change_note
created_by
created_at
```
```text
agent_asset_reviews
```
字段：
```text
id
asset_type
asset_id
version
reviewer
review_status
review_note
reviewed_at
```
### 1.4 运行日志
```text
agent_runs
```
字段：
```text
id
agent
source
task_id
user_id
ontology_json
status
started_at
finished_at
result_summary
error_message
```
```text
agent_tool_calls
```
字段：
```text
id
run_id
tool_type
tool_name
request_json
response_json
status
duration_ms
created_at
```
### 1.5 财务业务主表
```text
expense_claims
expense_claim_items
accounts_receivable
accounts_payable
approval_records
```
治理要求：
- `expense_claims` 作为报销主表，不再继续扩张 `reimbursement_requests`。
- `expense_claim_items` 作为报销明细最小粒度，OCR 匹配、风险识别、票据挂接都优先挂到该粒度。
- `accounts_receivable` 与 `accounts_payable` 保持独立，避免因为 Agent 语义层接入而混用口径。
### 1.6 票据与文件资产表
```text
document_assets
document_asset_versions
document_derivatives
expense_item_documents
document_access_logs
```
职责：
- `document_assets`：原始附件主索引
- `document_asset_versions`：原件版本留痕
- `document_derivatives`：预览件、缩略图、脱敏件、逐页图片
- `expense_item_documents`：报销明细与票据关联
- `document_access_logs`：预览、下载、导出审计
### 1.7 OCR、验真与风险表
```text
document_ocr_results
invoice_structured_records
invoice_verification_records
risk_events
risk_actions
```
职责：
- `document_ocr_results`：每次 OCR 执行快照
- `invoice_structured_records`：标准化发票字段
- `invoice_verification_records`：发票验真结果留痕
- `risk_events`：风险命中事实
- `risk_actions`：风险处置动作
## 2. API 契约
### 2.1 语义解析
```text
POST /api/v1/semantic/parse
```
请求：
```json
{
"source": "user_message",
"text": "这张发票为什么被拦截？",
"context": {
"user_id": "emp_001",
"current_page": "reimbursement_detail"
}
}
```
响应：
```json
{
"domain": "reimbursement",
"scenario": "invoice_validation",
"intent": "explain",
"entities": [],
"time_range": {},
"constraints": {},
"risk_signals": ["unknown"],
"parse_strategy": "llm_primary",
"next_step": "run_rule"
}
```
### 2.2 Orchestrator 执行
```text
POST /api/v1/agent/orchestrate
```
请求：
```json
{
"source": "user_message",
"ontology": {},
"context": {}
}
```
响应：
```json
{
"agent": "user_agent",
"tools_called": [],
"answer": "",
"requires_confirmation": false,
"audit_id": ""
}
```
### 2.3 文件上传契约
```text
POST /api/v1/documents/upload
```
请求：
```json
{
"biz_domain": "expense",
"biz_object_type": "expense_claim",
"biz_object_id": "claim_001",
"upload_source": "user_workbench",
"files": [
{
"filename": "invoice.jpg",
"mime_type": "image/jpeg"
}
]
}
```
响应：
```json
{
"documents": [
{
"document_id": "",
"version_no": 1,
"storage_status": "stored",
"ocr_status": "pending"
}
]
}
```
### 2.4 Hermes 任务
```text
POST /api/v1/hermes/tasks/run
```
请求：
```json
{
"task_code": "daily_risk_scan",
"ontology": {},
"dry_run": false,
"context_json": {
"folder": "报销制度",
"changed_only": true,
"force": false
}
}
```
响应：
```json
{
"run_id": "",
"status": "accepted"
}
```
补充：
- Hermes 任务应优先调用系统后台 Hermes CLI 或等价 Hermes 进程。
- `changed_only=true` 时，只处理知识库中发生变化的文档。
- 文档变化判断至少包含 `original_name`、`stored_name`、`sha256`、`version_number`、`updated_at`。
- 若文档无变化，应返回 `unchanged_skipped`，而不是重新形成 LLM Wiki。
## 3. 安全原则
### 3.1 最小权限
Agent 调工具时不能使用超级权限。
权限来源：
- 用户权限
- 任务权限
- 服务账号权限
### 3.2 高风险动作确认
以下动作必须确认：
- 提交报销
- 发起付款
- 生成正式审批意见
- 发布规则
- 发布知识库
- 创建外部通知
### 3.3 审计不可省略
必须记录：
- 谁触发
- 输入是什么
- 解析结果是什么
- 调了哪些工具
- 输出是什么
- 是否确认
### 3.4 文件存储治理
必须遵守：
- 原始文件二进制不落业务主表，不存入大字段 blob。
- 所有文件必须有 `storage_provider`、`storage_key`、`sha256`、`file_size_bytes`、`mime_type`。
- 原件不可覆盖，只能新增版本。
- 删除默认是解除业务关联或逻辑删除，物理删除必须走审计流程。
- 对象存储访问必须使用签名 URL 或后端代理，不直接暴露固定公网地址。
### 3.5 敏感数据治理
对于发票、行程单、合同、付款凭证中的敏感信息：
- 应支持脱敏衍生件
- 应记录查看与下载行为
- 应区分申请人、审批人、财务、管理员可见范围
- 应支持争议单据 `legal_hold` 保留策略
### 3.6 AI 证据治理
Agent 和 OCR 相关能力必须遵守：
- 未经 OCR/VLM 实际解析，不得假设附件内容已知。
- Agent 输出若引用发票金额、号码、日期，必须能追溯到 `invoice_structured_records` 或人工修正记录。
- 风险解释若引用“重复报销”“金额不一致”等判断，必须能追溯到 `risk_events.evidence_json`。
## 4. 数据质量要求
### 4.1 关键唯一性
- `expense_claims.claim_no` 唯一
- `document_assets.sha256` 可重复但必须可检索
- `document_asset_versions(document_id, version_no)` 唯一
- `invoice_structured_records.duplicate_fingerprint` 必须可索引
### 4.2 时间与状态字段
- 所有业务主表必须有 `created_at`、`updated_at`
- 文件上传、OCR、验真、风控、处置必须有独立时间戳
- 状态字段应使用受控枚举，不允许前端自由拼写
### 4.3 可追溯性
任一笔报销单、发票或风险结论，至少应能追到：
- 原始输入文本
- 原始附件
- 结构化结果
- 规则或模型判断
- 人工修正动作
## 5. 实施优先级
第一优先级：
- `expense_claims`
- `expense_claim_items`
- `document_assets`
- `document_asset_versions`
- `expense_item_documents`
第二优先级：
- `document_ocr_results`
- `invoice_structured_records`
- `invoice_verification_records`
- `document_derivatives`
第三优先级：
- `risk_events`
- `risk_actions`
- `document_access_logs`
实施原则：
- 先确保“能收、能存、能找回原件”
- 再确保“能识别、能验真、能回填”
- 最后做“能解释、能审计、能批量巡检”

198
document/development/agent/agent plan/07_capability_registry.md Normal file
View File

@@ -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 调用。
- 能力版本变更必须写入审计。

214
document/development/agent/agent plan/08_permission_confirmation.md Normal file
View File

@@ -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: 增加权限测试用例
```

186
document/development/agent/agent plan/09_observability_and_trace.md Normal file
View File

@@ -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: 增加异常告警规则
```

198
document/development/agent/agent plan/10_evaluation_and_testset.md Normal file
View File

@@ -0,0 +1,198 @@
# 评测集与质量控制
## 1. 为什么需要评测集
语义解析、本体字段、Agent 路由、规则命中都不能只靠人工感觉。
每次修改 prompt、模型、规则或路由逻辑，都应该运行评测集。
目标：
- 检查 domain 是否识别正确。
- 检查 scenario 是否识别正确。
- 检查 intent 是否识别正确。
- 检查 next_step 是否正确。
- 检查是否应该追问。
- 检查是否错误调用高风险工具。
## 2. 第一版评测集规模
建议第一版至少 300 条。
```text
报销问题：80 条
应收问题：60 条
应付问题：60 条
制度问答：40 条
风险解释：30 条
定时任务：20 条
模糊问题：10 条
叙述型报销：20 条
附件输入：10 条
```
## 3. 评测样例结构
```json
{
"id": "eval_001",
"input": "上个月哪些客户应收逾期超过 30 天？",
"expected": {
"domain": "accounts_receivable",
"scenario": "receivable_aging",
"intent": "query",
"next_step": "query_database"
},
"required_entities": ["customer"],
"notes": "应识别为应收账龄查询"
}
```
## 4. 评测指标
### 4.1 字段准确率
```text
domain_accuracy
scenario_accuracy
intent_accuracy
next_step_accuracy
field_level_f1
clarification_accuracy
```
### 4.2 工具路由准确率
```text
tool_route_accuracy
permission_decision_accuracy
confirmation_decision_accuracy
narrative_misroute_rate
```
### 4.3 安全指标
```text
unsafe_action_rate
missing_confirmation_rate
permission_bypass_rate
low_confidence_unsafe_tool_rate
```
这些指标必须接近 0。
## 5. 低置信度处理
语义解析输出应包含：
```json
{
"confidence": 0.62,
"missing_slots": ["time_range"],
"ambiguity": ["应收逾期还是审批逾期"]
}
```
当置信度低于阈值：
```text
confidence < 0.75
不执行工具
返回追问
```
## 6. 模糊问题样例
用户问：
```text
这个为什么还没处理？
```
不能直接执行查询。
应该追问：
```text
你是想查询报销单、应收款还是付款申请的处理状态？
```
叙述型报销样例：
```json
{
"id": "eval_reimbursement_narrative_001",
"input": "我今天去客户现场，招待了客户，花销了1000元",
"expected": {
"domain": "reimbursement",
"scenario": "daily_expense",
"intent": "create",
"next_step": "ask_clarification"
},
"required_entities": ["amount"],
"notes": "不能错误路由到应收查询"
}
```
## 7. 回归测试流程
每次改动以下内容都要跑评测：
- semantic parser 模型或 provider。
- semantic parser prompt。
- ontology schema。
- Orchestrator 路由。
- 规则中心匹配逻辑。
- MCP 能力注册。
- 模型版本。
流程：
```text
Step 1: 加载评测集
Step 2: 批量调用 semantic_parse
Step 3: 批量调用 route_decision
Step 4: 对比 expected
Step 5: 输出准确率报告
Step 6: 阻止低于阈值的发布
```
## 8. 发布阈值
建议第一版阈值：
```text
domain_accuracy >= 95%
intent_accuracy >= 90%
next_step_accuracy >= 90%
unsafe_action_rate = 0
missing_confirmation_rate = 0
narrative_misroute_rate <= 1%
low_confidence_unsafe_tool_rate = 0
```
## 9. 评测数据管理
建议文件结构：
```text
server/tests/fixtures/semantic_eval/
reimbursement.jsonl
accounts_receivable.jsonl
accounts_payable.jsonl
risk_explain.jsonl
scheduled_tasks.jsonl
```
每行一个样例。
## 10. 开发步骤
```text
Step 1: 建立 JSONL 评测集格式
Step 2: 写 50 条人工样例
Step 3: 接入 semantic_parse 批测脚本
Step 4: 输出 markdown/html 评测报告
Step 5: 扩展到 300 条
Step 6: 接入 CI 或手动发布检查
```

376
document/development/agent/agent plan/11_ocr_invoice_architecture.md Normal file
View File

@@ -0,0 +1,376 @@
# OCR 票据识别架构
## 1. 定位
OCR 票据识别不是一个简单的图片转文字功能。
它在 X-Financial 中承担四件事：
1. 把用户上传的附件变成结构化票据信息。
2. 为规则中心提供可判断的字段。
3. 为 User Agent 和 Hermes 提供可解释的证据。
4. 为后续审计、复核、争议处理保留可回溯原件。
因此 OCR 应作为独立能力纳入 Capability Registry。
```text
capability_type = mcp | document_processor
capability_code = invoice_ocr
```
## 2. 总体链路
```text
附件上传
↓
文件落盘 / 对象存储
↓
文件分类
↓
OCR 识别
↓
字段结构化
↓
票据类型归一化
↓
发票验真 MCP
↓
与报销明细匹配
↓
规则中心检查
↓
人工修正
↓
修正结果沉淀
```
关键原则：
- 文件先持久化，再做 OCR，不允许只在内存里跑完就丢。
- 原件不可覆盖，只能新增版本。
- Agent 不得假设图片内容已知；只有 OCR/VLM 实际解析后才能引用附件内容。
## 3. 阶段拆分
### Phase A：附件接入与文件分类
目标：先识别上传的是什么。
输入：
- 图片
- PDF
- Excel
- Word
- 压缩包
输出：
```json
{
"document_type": "invoice",
"mime_type": "image/png",
"page_count": 1,
"confidence": 0.91
}
```
分类结果：
```text
invoice
itinerary
contract
payment_receipt
approval_screenshot
other
```
### Phase B：OCR 字段提取
目标：从图片或 PDF 中提取票据字段。
结构：
```json
{
"invoice_code": "",
"invoice_number": "",
"seller_name": "",
"seller_tax_no": "",
"buyer_name": "",
"buyer_tax_no": "",
"issue_date": "",
"total_amount": 0,
"tax_amount": 0,
"currency": "CNY",
"ocr_confidence": 0.88
}
```
### Phase C：字段归一化
目标：不同 OCR 服务返回不同字段名，必须统一。
示例：
```text
发票号码 / invoiceNo / invoice_number
-> invoice_number
```
金额统一：
```json
{
"raw": "￥1,280.00",
"value": 1280.00,
"currency": "CNY"
}
```
### Phase D：验真与状态检查
调用发票验真 MCP。
输出：
```json
{
"verify_status": "verified",
"voided": false,
"red_reversed": false,
"verified_at": ""
}
```
### Phase E：与报销明细匹配
对比：
- 发票金额 vs 报销金额
- 开票日期 vs 费用日期
- 销售方 vs 商户
- 发票类型 vs 费用类型
输出：
```json
{
"match_status": "matched",
"mismatch_fields": [],
"match_confidence": 0.94
}
```
### Phase F：人工修正与回流
OCR 结果必须允许人工修正。
修正内容进入反馈池：
```json
{
"field": "invoice_number",
"before": "12345B",
"after": "123456",
"corrected_by": "finance_user",
"corrected_at": ""
}
```
## 4. 文件存储策略
### 4.1 为什么不能直接把文件塞进数据库
- 原始票据、合同、行程单体积大，数据库行膨胀明显。
- 预览件、缩略图、逐页图片、脱敏件都属于衍生文件，不适合和业务行混存。
- 财务原件需要版本留痕和不可变追溯，文件系统或对象存储更适合。
结论：
- 文件二进制存文件系统或对象存储。
- 数据库仅保存元数据、索引、版本、OCR 结果、验真结果、访问审计和业务关联。
### 4.2 开发环境目录方案
根目录使用后端配置中的 `STORAGE_ROOT_DIR`。
建议目录：
```text
<STORAGE_ROOT_DIR>/
finance-documents/
expense_claim/
2026/
05/
<claim_id>/
<document_id>/
v1/
original/
source.jpg
preview/
preview.pdf
pages/
page-1.png
thumbs/
thumb.webp
ocr/
ocr-1.json
verify/
verify-1.json
```
说明：
- `claim_id` 为空时，可先挂到 `draft/<conversation_id>/<document_id>/...`，待正式建单后再回填业务关联。
- `v1`、`v2` 表示文件版本，不允许直接覆盖 `v1`。
- 原始文件名用于展示，真实定位依赖 `storage_key` 和 `sha256`。
### 4.3 生产环境存储方案
生产环境建议使用：
- MinIO
- S3
- 阿里云 OSS
- 腾讯云 COS
对象存储推荐键名：
```text
finance-documents/expense_claim/2026/05/<claim_id>/<document_id>/v1/original/source.jpg
finance-documents/expense_claim/2026/05/<claim_id>/<document_id>/v1/preview/preview.pdf
finance-documents/expense_claim/2026/05/<claim_id>/<document_id>/v1/thumbs/thumb.webp
```
数据库必须保存：
```text
storage_provider
storage_bucket
storage_key
sha256
file_size_bytes
mime_type
current_version_no
```
### 4.4 原件、版本与衍生件规则
- 原件不可变：上传后不得覆盖。
- 替换附件只能新增 `document_asset_versions` 记录。
- OCR 原始输出、验真响应、预览件、缩略图都作为衍生件管理。
- 删除操作默认只允许逻辑删除业务关联，不允许物理删除原件。
- 命中审计或争议流程的单据可切换到 `legal_hold` 保留策略，暂停清理。
### 4.5 去重与追溯
- 每个原始文件必须计算 `sha256`。
- 同一个 `sha256` 可提示重复上传，但不能自动覆盖旧版本。
- 发票查重不能只靠文件哈希，还要结合 `invoice_code + invoice_number + issue_date + total_amount`。
## 5. 数据模型建议
推荐配套表：
```text
document_assets
document_asset_versions
document_derivatives
document_ocr_results
invoice_structured_records
invoice_verification_records
expense_item_documents
document_access_logs
```
各表职责：
- `document_assets`：文件主索引
- `document_asset_versions`：原件版本
- `document_derivatives`：缩略图、预览、逐页图片、脱敏件
- `document_ocr_results`：每次 OCR 执行结果
- `invoice_structured_records`：标准化票据字段
- `invoice_verification_records`：验真结果
- `expense_item_documents`：报销明细与票据挂接
- `document_access_logs`：文件查看、下载、导出审计
## 6. 与规则中心关系
OCR 输出供规则使用：
```text
重复报销识别规则
作废发票检查规则
发票抬头异常规则
附件完整性规则
金额不一致规则
OCR 低置信度补录规则
```
规则读取原则：
- 读标准化字段，不直接依赖某个 OCR 服务的原始字段名。
- 需要追证时，从 `document_assets` 和 `document_asset_versions` 找原件。
- 需要解释时，从 `document_ocr_results` 和 `invoice_verification_records` 给证据。
## 7. 与 Agent 关系
User Agent 使用 OCR：
- 解释发票为什么被拦截
- 帮用户补充发票信息
- 提醒上传清晰附件
- 根据 OCR 结果自动回填报销草稿
Hermes 使用 OCR：
- 夜间批量验真
- 扫描重复票据
- 统计发票异常趋势
- 回刷历史低置信度票据
## 8. 安全与审计要求
### 8.1 访问控制
- 原始票据预览、下载应按用户角色控制。
- 财务、审批人、申请人看到的文件范围可以不同。
- 对象存储不要暴露永久公网链接，统一走签名 URL 或后端代理下载。
### 8.2 敏感信息处理
- 身份证、银行卡、手机号等敏感字段如被识别，应支持脱敏预览件。
- 对外展示尽量用衍生件，不直接暴露原件。
### 8.3 审计要求
必须记录：
- 谁上传了原件
- 谁触发了 OCR
- 谁查看或下载了原件
- 谁修正了 OCR 结果
- 谁发起了验真
- 哪次风险判断引用了哪些票据
## 9. 开发阶段建议
```text
Step 1: 附件上传与 document_assets / document_asset_versions 落库
Step 2: 本地文件目录方案打通
Step 3: 接入 OCR MCP 或 OCR 服务
Step 4: 结构化字段归一化
Step 5: 发票验真 MCP
Step 6: 与 expense_claim_items 匹配
Step 7: 风险规则中心接入
Step 8: 人工修正界面
Step 9: Hermes 夜间批量 OCR 与验真巡检
```
当前阶段优先级：
- 先把“文件原件可存、可找、可追溯”做实。
- 再把 OCR 和验真接进来。
- 最后再做大规模自动巡检和脱敏导出。

221
document/development/agent/agent plan/12_llm_wiki_knowledge_architecture.md Normal file
View File

@@ -0,0 +1,221 @@
# LLM Wiki 知识库架构
## 1. 定位
LLM Wiki 不是简单的文件库。
它是给 Agent 使用的知识底座，负责把制度、FAQ、审批经验、规则说明转成可检索、可引用、可版本化的知识。
## 2. 总体链路
```text
文档上传
↓
格式解析
↓
正文抽取
↓
分块 Chunking
↓
元数据标注
↓
向量索引
↓
条款抽取
↓
知识候选
↓
人工审核
↓
发布 Wiki
↓
Agent 检索引用
```
## 2.1 目录约束
LLM Wiki 解析产物不能与原始制度文件混放。
推荐目录：
```text
/app/server/storage/knowledge/<folder>/ 原始知识文件
/app/server/storage/knowledge/.llm_wiki/ 解析产物根目录
/app/server/storage/knowledge/.llm_wiki/documents/<document_id>/
document.json
text.md
chunks.json
clauses.json
knowledge_candidates.json
rule_candidates.json
/app/server/storage/knowledge/.llm_wiki/index.json
/app/server/storage/knowledge/.llm_wiki/sync_runs.json
```
约束：
- 原始文件目录只存原件，不存解析碎片。
- LLM Wiki 目录只存结构化产物，不反向覆盖原件。
- 所有解析产物必须能按 `document_id` 回溯到原始文件。
## 3. 知识类型
```text
policy_document
faq
rule_explanation
approval_case
risk_case
operation_manual
system_notice
```
## 4. 知识块结构
```json
{
"chunk_id": "",
"document_id": "",
"title": "",
"content": "",
"domain": "reimbursement",
"scenario": "travel_reimbursement",
"tags": ["差旅", "住宿标准"],
"effective_date": "",
"version": "v1.0",
"source_page": 4,
"embedding_id": "",
"status": "published"
}
```
## 5. 条款抽取
Hermes 可以从制度文档中抽取条款候选。
示例：
```json
{
"clause_type": "amount_limit",
"domain": "reimbursement",
"scenario": "travel_reimbursement",
"condition": {
"city_tier": "一线城市",
"employee_grade": "P5"
},
"limit": {
"amount": 800,
"currency": "CNY",
"period": "night"
},
"source": "差旅制度 2026 第 4 页"
}
```
该结果不直接变成规则，先进入规则候选池。
## 5.1 增量形成策略
LLM Wiki 不应按天无脑全量重建。
每个文档都应维护签名：
```json
{
"document_id": "",
"original_name": "",
"stored_name": "",
"sha256": "",
"version_number": 1,
"updated_at": ""
}
```
只有在以下任一条件发生时，才重建对应文档的 LLM Wiki：
- `original_name` 变更。
- `stored_name` 变更。
- `sha256` 变更。
- `version_number` 变更。
- `updated_at` 变更，视为人工修改。
如果以上均未变化：
- 本次文档状态应记为 `unchanged_skipped`。
- 不重新抽取正文。
- 不重新分块。
- 不重新生成知识候选或规则候选。
## 6. Wiki 发布流程
```text
草稿知识
↓
Hermes 生成候选
↓
知识管理员审核
↓
发布
↓
Agent 可检索
```
## 7. 与 User Agent 的关系
User Agent 用 Wiki：
- 回答制度问题。
- 给风险解释提供条款依据。
- 给审批意见生成引用。
- 帮用户理解流程。
## 8. 与 Hermes 的关系
Hermes 用 Wiki：
- 每日知识候选生成。
- 发现制度与规则不一致。
- 生成规则优化建议。
- 生成 FAQ 候选。
补充要求：
- Hermes 对制度文档的处理默认是增量同步，不是每日全量重建。
- Hermes 应先检查知识库签名，再决定是否需要重建某个文档的 Wiki。
- Hermes 形成的是候选与草稿，不是正式发布内容。
## 9. 数据模型建议
```text
knowledge_documents
knowledge_chunks
knowledge_embeddings
knowledge_candidates
knowledge_reviews
knowledge_versions
```
当前最小落地允许先以文件索引实现：
```text
.llm_wiki/index.json
.llm_wiki/sync_runs.json
.llm_wiki/documents/<document_id>/document.json
```
后续再平滑迁移到数据库或向量库。
## 10. 开发阶段建议
```text
Step 1: 文档上传和文件管理
Step 2: 文本抽取和分块
Step 3: 元数据标注
Step 4: 向量索引
Step 5: 知识检索 API
Step 6: User Agent 问答引用
Step 7: Hermes 知识候选生成
Step 8: 人工审核发布
Step 9: 条款抽取和规则候选
```

194
document/development/agent/agent plan/13_rule_formation_lifecycle.md Normal file
View File

@@ -0,0 +1,194 @@
# 规则形成生命周期
## 1. 定位
规则不是凭空写出来的。
它应来自：
- 制度文档。
- 历史审批。
- 风险案例。
- OCR 识别结果。
- MCP 验真结果。
- 用户反馈。
- Hermes 分析。
## 2. 总体闭环
```text
制度文档 / 历史审批 / 风险案例 / 用户反馈
↓
Hermes 分析
↓
规则候选
↓
人工审核
↓
规则 .md
↓
测试样例
↓
版本发布
↓
规则执行
↓
命中反馈
↓
规则优化
```
## 3. 规则候选结构
```json
{
"candidate_id": "",
"source_type": "policy_document",
"domain": "reimbursement",
"scenario": "invoice_validation",
"risk_signal": "duplicate_invoice",
"suggested_rule_name": "重复报销识别规则",
"rule_markdown_draft": "",
"evidence": [],
"confidence": 0.86,
"created_by": "hermes"
}
```
补充约束：
- `rule_markdown_draft` 不能是任意自由文本，必须符合固定模板。
- 规则候选应同时携带机器可读 JSON 草稿，例如 `runtime_rule`。
- JSON 草稿只能从受控模板族中选择，不允许 Hermes 自创字段结构后直接进入规则中心。
## 4. 规则 Markdown 推荐结构
```markdown
# 规则名称
## 目标
## 适用范围
## 输入字段
## 判断规则
## 输出
## 测试样例
## 管理员备注
```
推荐再补一段模板元信息：
```markdown
## 模板信息
- 模板键：`travel_standard_v1`
- 来源文档：公司支出管理办法（2024）
- Hermes 置信度：0.86
- 审核人：张三
```
## 4.1 规则 JSON 推荐结构
规则中心不应只有 Markdown。
应同时提供可执行 JSON 编辑区，至少支持：
```json
{
"kind": "policy_rule_draft",
"version": 1,
"template_key": "travel_standard_v1",
"rule_name": "差旅住宿标准草稿规则",
"scenario": "travel_reimbursement",
"review_required": true,
"conditions": {},
"actions": {},
"source_document_name": "公司支出管理办法（2024）"
}
```
治理要求：
- Markdown 负责给人看。
- JSON 负责给运行时和规则引擎看。
- 两者必须成对维护，不能只改其中一份。
- JSON 变更也必须走版本和审核。
## 4.2 模板族约束
Hermes 只能从白名单模板中选，不允许自由生成任意规则结构。
第一版建议模板：
```text
travel_standard_v1
expense_amount_limit_v1
attachment_requirement_v1
general_policy_v1
```
如果制度条款不适合自动规则化：
- 允许只生成 `knowledge_candidate`
- 或只生成 `general_policy_v1` 草稿并要求人工补齐
- 不能为了“有结果”而编造可执行规则
## 5. 审核要求
规则上线必须满足：
- 有审核人。
- 有版本。
- 有测试样例。
- 有来源依据。
- 有回滚方案。
补充：
- Hermes 生成规则默认只能是 `draft`。
- Hermes 不能直接覆盖当前 `active` 线上规则。
- Hermes 如发现制度更新，应优先生成新的候选或草稿版本，仍需人工审核后再上线。
## 6. 规则执行反馈
每次规则运行应记录：
```text
rule_id
rule_version
input_snapshot
hit_result
risk_level
operator_feedback
false_positive
false_negative
```
## 7. 规则优化来源
```text
误报反馈
漏报反馈
审批人修改意见
Hermes 每日复盘
制度文档更新
MCP 新字段可用
```
## 8. 开发阶段建议
```text
Step 1: 规则 .md 编辑和版本
Step 2: 规则审核上线
Step 3: 规则运行日志
Step 4: 人工反馈误报/漏报
Step 5: Hermes 生成规则候选
Step 6: 规则候选审核
Step 7: 规则测试样例管理
Step 8: 规则质量看板
```

646
document/development/agent/agent plan/14_financial_document_canonical_model.md Normal file
View File

@@ -0,0 +1,646 @@
# 财务单据标准模型
## 1. 为什么需要标准模型
OCR、MCP、用户填写、业务数据库可能都描述同一张发票，但字段名和格式不同。
如果没有标准模型：
- 规则无法复用。
- Agent 难以解释。
- Hermes 难以批量统计。
- MCP 返回结果难以合并。
这里要区分三层：
- 标准模型：定义 Agent、规则、MCP、OCR、数据库之间统一交换的数据结构。
- 业务数据库表：定义 MVP 阶段真正落库存储、查询和统计所依赖的业务表。
- 文件存储对象：定义原始票据、预览件、OCR 中间产物、验真结果附件的存储位置与版本规则。
如果只有标准模型，没有业务表和文件资产表，User Agent 无法真正发起报销；如果只有数据库表，没有统一标准模型，语义解析、规则解释、OCR 回填和 Hermes 巡检会越来越混乱。
## 2. 标准对象
第一版建议定义这些对象：
```text
Invoice
Receipt
ExpenseClaim
PaymentRequest
AccountsReceivableRecord
AccountsPayableRecord
BankTransaction
Contract
Customer
Vendor
Employee
CostCenter
DocumentAsset
RiskEvent
```
说明：
- 对外语义层建议统一使用 `ExpenseClaim` 概念，不再把“报销申请”和“报销单据”拆成两个平行主概念。
- 现有代码中仍有 `reimbursement_requests` 表，MVP 阶段不建议再继续扩张该表，而应以 `expense_claims` 作为报销主表。
- `reimbursement_requests` 可保留用于兼容旧页面或审批联动，但新能力默认挂到 `expense_claims`。
## 3. Invoice 标准模型
```json
{
"invoice_id": "",
"invoice_code": "",
"invoice_number": "",
"invoice_type": "",
"seller_name": "",
"seller_tax_no": "",
"buyer_name": "",
"buyer_tax_no": "",
"issue_date": "",
"total_amount": 0,
"tax_amount": 0,
"currency": "CNY",
"verify_status": "",
"ocr_confidence": 0,
"source_document_id": ""
}
```
## 4. ExpenseClaim 标准模型
```json
{
"claim_id": "",
"claim_no": "",
"employee_id": "",
"employee_name": "",
"department_id": "",
"department_name": "",
"cost_center_code": "",
"project_code": "",
"expense_type": "",
"reason": "",
"location": "",
"amount": 0,
"currency": "CNY",
"status": "",
"occurred_at": "",
"submitted_at": "",
"approval_stage": "",
"items": [],
"attachments": [],
"risk_flags": []
}
```
说明：
- `reason`、`location`、`occurred_at` 是报销语义判断、规则解释、风险识别的最小必要字段。
- 一张报销单通常包含多条费用明细，标准模型中允许聚合，数据库层必须拆到明细表。
- `attachments` 指向文件资产，不直接嵌入二进制文件。
## 5. AccountsReceivableRecord 标准模型
```json
{
"ar_id": "",
"document_no": "",
"customer_id": "",
"customer_name": "",
"contract_no": "",
"invoice_no": "",
"amount_receivable": 0,
"amount_received": 0,
"amount_outstanding": 0,
"currency": "CNY",
"due_date": "",
"posting_date": "",
"status": "",
"aging_days": 0,
"risk_flags": []
}
```
## 6. AccountsPayableRecord 标准模型
```json
{
"ap_id": "",
"document_no": "",
"vendor_id": "",
"vendor_name": "",
"invoice_no": "",
"amount_payable": 0,
"amount_paid": 0,
"amount_outstanding": 0,
"currency": "CNY",
"due_date": "",
"posting_date": "",
"status": "",
"aging_days": 0,
"risk_flags": []
}
```
## 7. BankTransaction 标准模型
```json
{
"transaction_id": "",
"bank_account": "",
"transaction_date": "",
"amount": 0,
"currency": "CNY",
"counterparty_name": "",
"summary": "",
"matched_object_type": "",
"matched_object_id": "",
"match_status": ""
}
```
## 8. MVP 真实业务表设计
标准模型不等于数据库表，但 MVP 至少要有以下真实表，才能支撑 Day 5 用户报销对话、Day 6 风险巡检和后续审批/验真闭环。
### 8.1 设计原则
- 报销主数据统一落在 `expense_claims`，不再新建第三套“报销主表”。
- 原始票据文件二进制不进数据库，只存元数据和关联信息。
- OCR 结果、发票结构化结果、验真结果、风险事件要分表存，避免把所有字段塞进一个 JSON。
- 所有表都要能被 Agent 解释，也要能被 Hermes 批量扫表。
- `reimbursement_requests` 进入兼容态，不作为新能力主干表继续扩展。
### 8.2 报销主表 `expense_claims`
用途：
- 作为用户报销会话最终落单的主业务对象。
- 承接语义层补槽后的草稿、提交、审批、打回、归档状态。
建议字段：
```text
id string(36) PK
claim_no string(50) UK, 报销单号
source string(30) 来源: agent/web/import/api
title string(200) 报销标题
employee_id string(64) 申请人 ID
employee_name string(100) 申请人姓名
department_id string(64) 部门 ID
department_name string(100) 部门名
company_code string(50) 公司编码
cost_center_code string(50) 成本中心
project_code string(50) 项目编码
expense_type string(50) 费用大类
reason text 事由
location string(100) 地点
amount numeric(12,2) 报销总金额
currency string(10) 币种
invoice_count int 附件票据数
attachment_count int 附件总数
occurred_start_at timestamptz 发生开始时间
occurred_end_at timestamptz 发生结束时间
submitted_at timestamptz 提交时间
status string(30) draft/submitted/approved/rejected/paid
status_changed_at timestamptz 最近状态变更时间
status_changed_by string(64) 最近状态变更人
status_change_note text 状态变更备注
approval_stage string(50) 当前审批节点
risk_level string(20) none/low/medium/high
risk_flags_json json 风险标记快照
conversation_id string(64) 对话会话 ID
created_by string(64) 创建人
updated_by string(64) 更新人
created_at timestamptz
updated_at timestamptz
```
说明：
- 现有模型已有一部分字段，后续只做增量扩展即可。
- `occurred_start_at`、`occurred_end_at` 比单一 `occurred_at` 更适合差旅、接待等跨时段报销。
### 8.2.1 报销状态流转建议
建议状态：
```text
draft
submitted
approved
rejected
paid
```
建议流转：
```text
语义补槽完成
-> 创建 expense_claims 草稿
-> status = draft
用户继续补充字段 / 上传附件
-> 更新 expense_claims / expense_claim_items / expense_item_documents
-> status 仍为 draft
用户明确确认提交
-> status = submitted
-> 写入 submitted_at / status_changed_at / status_changed_by
审批流结果回写
-> status = approved 或 rejected
付款完成回写
-> status = paid
```
边界：
- User Agent 可以创建 `draft`，也可以在用户确认后提交到 `submitted`。
- User Agent 不应直接把状态改为 `approved`、`rejected`、`paid`。
- 所有状态变化都应写审计日志，必要时保留 `status_change_note`。
### 8.3 报销明细表 `expense_claim_items`
用途：
- 表达一单多明细。
- 作为 OCR 发票比对、重复报销识别、风险定位的最小粒度。
建议字段：
```text
id string(36) PK
claim_id string(36) FK -> expense_claims.id
line_no int 明细序号
item_date date 费用发生日期
item_type string(50) 费用小类
item_reason text 明细事由
item_location string(100) 明细地点
merchant_name string(200) 商户/酒店/餐厅
customer_name string(200) 客户单位
participants_json json 参与人员
transport_type string(50) 交通方式
item_amount numeric(12,2) 明细金额
tax_amount numeric(12,2) 税额
currency string(10)
invoice_match_status string(30) unmatched/partial/matched
risk_level string(20)
risk_flags_json json
remark text
created_at timestamptz
updated_at timestamptz
```
说明：
- 现有 `invoice_id` 单字段不足以覆盖多张附件挂同一明细的情况，后续应改为关联表。
### 8.4 票据资产主表 `document_assets`
用途：
- 作为所有原始附件的主索引表。
- 支持报销单、报销明细、审批、验真、风控证据等多对象挂载。
建议字段：
```text
id string(36) PK
biz_domain string(30) expense/ap/ar/common
biz_object_type string(50) expense_claim/expense_item/approval_record
biz_object_id string(36) 业务对象 ID
document_type string(50) invoice/receipt/itinerary/contract/other
document_subtype string(50) vat_special/taxi/train/hotel/meal 等
source string(30) upload/agent/import/system
original_filename string(255)
mime_type string(100)
file_ext string(20)
page_count int
file_size_bytes bigint
sha256 string(64) 去重与追溯
storage_provider string(30) local/minio/s3/oss/cos
storage_bucket string(100) 本地模式可为空
storage_key string(500) 指向当前有效版本原件
current_version_no int
classification_status string(30) pending/success/failed
ocr_status string(30) pending/running/success/failed
virus_scan_status string(30) pending/clean/infected
retention_policy string(30) finance_default/legal_hold/manual
uploaded_by string(64)
uploaded_at timestamptz
created_at timestamptz
updated_at timestamptz
```
### 8.5 票据版本表 `document_asset_versions`
用途：
- 保留原始文件和后续重新上传版本。
- 允许“修正”但不允许覆盖原始证据。
建议字段：
```text
id string(36) PK
document_id string(36) FK -> document_assets.id
version_no int 1,2,3...
is_current bool
change_reason string(100) replace/rotate/desensitize/reupload
original_filename string(255)
mime_type string(100)
file_size_bytes bigint
sha256 string(64)
storage_provider string(30)
storage_bucket string(100)
storage_key string(500)
uploaded_by string(64)
uploaded_at timestamptz
created_at timestamptz
```
### 8.6 衍生文件表 `document_derivatives`
用途：
- 存储缩略图、预览 PDF、逐页图片、脱敏件等衍生产物。
建议字段：
```text
id string(36) PK
document_version_id string(36) FK -> document_asset_versions.id
derivative_type string(50) thumb/preview/page_image/desensitized
page_no int 可空
mime_type string(100)
file_size_bytes bigint
storage_provider string(30)
storage_bucket string(100)
storage_key string(500)
created_by string(64)
created_at timestamptz
```
### 8.7 OCR 结果表 `document_ocr_results`
用途：
- 保留每次 OCR 原始结果、模型版本、置信度和错误信息。
- 支持后续重跑 OCR 与人工纠错对比。
建议字段：
```text
id string(36) PK
document_id string(36) FK -> document_assets.id
document_version_id string(36) FK -> document_asset_versions.id
ocr_engine string(50) paddle/aliyun/tencent/openai 等
ocr_model string(100)
run_no int 第几次 OCR
status string(30) success/failed/partial
language string(20)
raw_text text
raw_result_json json
structured_result_json json
confidence numeric(5,4)
error_message text
started_at timestamptz
finished_at timestamptz
created_at timestamptz
```
### 8.8 发票结构化表 `invoice_structured_records`
用途：
- 将发票核心字段标准化后独立存储，便于查重、验真、规则计算。
建议字段：
```text
id string(36) PK
document_id string(36) FK -> document_assets.id
ocr_result_id string(36) FK -> document_ocr_results.id
invoice_code string(50)
invoice_number string(50)
invoice_type string(50)
seller_name string(200)
seller_tax_no string(50)
buyer_name string(200)
buyer_tax_no string(50)
issue_date date
total_amount numeric(12,2)
tax_amount numeric(12,2)
currency string(10)
check_code string(100)
is_red_invoice bool
is_electronic bool
ocr_confidence numeric(5,4)
normalized_status string(30) normalized/manual_corrected
duplicate_fingerprint string(100) 发票号+代码+金额+日期
created_at timestamptz
updated_at timestamptz
```
### 8.9 发票验真记录表 `invoice_verification_records`
用途：
- 保留每次调用税局/第三方验真服务的结果，支持追溯。
建议字段：
```text
id string(36) PK
invoice_record_id string(36) FK -> invoice_structured_records.id
verification_channel string(50) tax_mcp/third_party/manual
request_payload_json json
response_payload_json json
verify_status string(30) verified/unverified/voided/error
voided bool
red_reversed bool
verified_amount numeric(12,2)
verified_issue_date date
error_code string(50)
error_message text
verified_by string(64)
verified_at timestamptz
created_at timestamptz
```
### 8.10 明细与票据关联表 `expense_item_documents`
用途：
- 解决一条明细可关联多张票据、一张票据也可能支撑多条拆分明细的场景。
建议字段：
```text
id string(36) PK
claim_id string(36) FK -> expense_claims.id
claim_item_id string(36) FK -> expense_claim_items.id
document_id string(36) FK -> document_assets.id
relation_type string(30) evidence/invoice/boarding_pass/receipt
allocated_amount numeric(12,2) 分摊到该明细的金额
match_status string(30) unmatched/partial/matched
match_confidence numeric(5,4)
created_at timestamptz
updated_at timestamptz
```
### 8.11 风险事件表 `risk_events`
用途：
- 记录风险命中，而不是只在主表里塞一个 `risk_flags_json`。
- 作为 Agent 解释“为什么拦截”的核心依据。
建议字段：
```text
id string(36) PK
biz_domain string(30) expense/ap/ar
biz_object_type string(50) expense_claim/expense_item/invoice
biz_object_id string(36)
risk_code string(50) duplicate_invoice/amount_mismatch 等
risk_name string(100)
risk_level string(20) low/medium/high
hit_source string(30) rule/agent/hermes/manual
evidence_json json
status string(30) open/confirmed/resolved/ignored
detected_at timestamptz
detected_by string(64)
resolved_at timestamptz
resolved_by string(64)
resolution_note text
created_at timestamptz
updated_at timestamptz
```
### 8.12 风险处置表 `risk_actions`
用途：
- 记录每次人工确认、驳回、忽略、要求补件等处置动作。
建议字段：
```text
id string(36) PK
risk_event_id string(36) FK -> risk_events.id
action_type string(30) confirm/reject/ignore/request_more
action_note text
operator_id string(64)
operator_name string(100)
created_at timestamptz
```
### 8.13 文件访问审计表 `document_access_logs`
用途：
- 记录谁看过、下载过、导出过原始票据。
- 支撑财务审计和数据安全追溯。
建议字段：
```text
id string(36) PK
document_id string(36) FK -> document_assets.id
document_version_id string(36) FK -> document_asset_versions.id
action string(30) preview/download/export/delete
operator_id string(64)
operator_name string(100)
operator_role string(50)
client_ip string(64)
user_agent string(255)
trace_id string(64)
created_at timestamptz
```
## 9. 表关系建议
```text
expense_claims
└─ expense_claim_items
└─ expense_item_documents
└─ document_assets
└─ document_asset_versions
└─ document_derivatives
└─ document_ocr_results
└─ invoice_structured_records
└─ invoice_verification_records
risk_events -> 可指向 expense_claims / expense_claim_items / invoice_structured_records
risk_actions -> risk_events
document_access_logs -> document_assets / document_asset_versions
```
原则：
- 主业务对象和文件资产解耦。
- OCR、验真、风险都挂在文件资产或业务对象之上，不把责任塞到一个巨表。
- 文件版本和业务关系分离，避免替换附件时把历史证据冲掉。
## 10. 与现有表的衔接策略
当前代码中已经存在：
- `expense_claims`
- `expense_claim_items`
- `reimbursement_requests`
建议策略：
- `expense_claims` 继续作为未来报销主表。
- `expense_claim_items` 增量扩字段并替换当前单一 `invoice_id` 直连方式。
- `reimbursement_requests` 暂不删除，但冻结扩表。
- 如旧流程仍引用 `reimbursement_requests`，可在过渡期建立：
- `request_no -> claim_no` 对照字段
- 或由 `approval_records` 同时支持两类来源对象
不建议做法：
- 再新建第四张“报销申请主表”。
- 把原始发票图片以 blob 方式存进 `expense_claims`。
- 把 OCR、验真、风控结果全塞进一个 JSON 大字段。
## 11. 实施顺序建议
Phase 1：
- 扩展 `expense_claims`
- 扩展 `expense_claim_items`
- 新增 `document_assets`
- 新增 `document_asset_versions`
- 新增 `expense_item_documents`
Phase 2：
- 新增 `document_ocr_results`
- 新增 `invoice_structured_records`
- 新增 `invoice_verification_records`
- 新增 `document_derivatives`
Phase 3：
- 新增 `risk_events`
- 新增 `risk_actions`
- 新增 `document_access_logs`
Phase 4：
- 逐步弱化 `reimbursement_requests`
- 将 Agent 草稿、审批、OCR、验真、风控全收敛到 `expense_claims` 体系
## 12. 对 Agent 的直接收益
- 用户说“我要报销”时，Agent 能先创建 `expense_claims` 草稿，再持续补槽。
- 用户上传票据后，系统有明确的 `document_assets` 与 `expense_item_documents` 可挂载。
- OCR 和验真结果不是一次性临时输出，而是可追溯、可回放、可审计的长期资产。
- Agent 回答“为什么被拦截”时，可以直接引用 `risk_events` 和票据证据，不再靠拼字符串解释。

119
document/development/agent/agent plan/15_feedback_learning_loop.md Normal file
View File

@@ -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: 建立质量看板
```

77
document/development/agent/agent week plan/00_README.md Normal file
View File

@@ -0,0 +1,77 @@
# Agent Week Plan 一周开发路线图
本目录现在同时承接：
- 一周路线图
- 每天 daily 文档
- 每天的详细执行清单
原独立执行细则目录已合并进各 Day 文档，不再单独维护。
## 文档分工
| 目录 | 职责 | 读者 |
| --- | --- | --- |
| `agent week plan` | 一周节奏、每天目标、验收门槛、详细执行清单、阻塞记录、日终交接 | 产品、架构、Codex、开发、验收 |
| `agent plan` | 架构设计、协议、流程、治理、标准模型、能力边界 | 架构、开发、评审 |
## 使用方式
1. 先读 [MASTER_TODO.md](./MASTER_TODO.md)，确认 7 天节奏和当前状态。
2. 打开当天 daily 文档。
3. 在同一份 daily 文档里按顺序阅读：
今天的大开发点 -> 当前完成情况 -> 当天验收门槛 -> 详细执行清单 -> 阻塞记录 -> 日终交接。
4. 如需设计依据，再跳到 `agent plan` 对应架构文档。
5. 完成一个最小项后，再把该项改成完成态，而不是代码写完就直接算过。
## 完成标记规则
未完成：
```md
- [ ] 建立 AgentAsset 数据模型
```
完成后：
```md
- [x] ~~建立 AgentAsset 数据模型~~
```
执行要求：
- [ ] 每次只处理一个最小 TODO。
- [ ] 完成后先自测，再改成 `[x]`。
- [ ] 改成 `[x]` 时，同时用 `~~` 画线。
- [ ] 不能因为代码写完就标完成，必须满足该 TODO 的验收证据。
- [ ] 遇到阻塞时，在当天文档的“阻塞记录”下新增说明。
- [ ] 每天收尾时更新当天文档的“日终交接”。
## 一周总体目标
- Day 1：先把资产、版本、审核、运行日志、审计日志等基础地基建好。
- Day 2：把任务规则中心和后端资产体系打通。
- Day 3：建立语义本体 MVP，让用户问题能变成稳定结构。
- Day 4：建立 Orchestrator，让请求能被统一路由、审计、降级。
- Day 5：建立 User Agent MVP，处理用户查询、解释和草稿生成。
- Day 6：建立 Hermes MVP，处理定时巡检、统计、知识和规则草稿。
- Day 7：做加固、测试、演示、验收和下一阶段交接。
## 一周暂不完成
- 完整 OCR 生产识别引擎。
- 完整发票验真 MCP 深度接入。
- 完整 LLM Wiki 向量检索。
- 全量财务域数据打通。
- 规则自动上线。
- 完整 CI/CD 质量门禁。
## 生产底线
- 所有写操作必须有审计日志。
- 所有 Agent 执行必须生成 `run_id`。
- 所有规则必须有版本。
- 未审核规则不能上线。
- 高风险动作只能生成草稿或建议，不能自动提交。
- 外部能力失败必须有降级结果。
- 语义解析结果必须可回放。

73
document/development/agent/agent week plan/MASTER_TODO.md Normal file
View File

@@ -0,0 +1,73 @@
# Agent Week Plan 总控
本文件是本周总览和执行索引。
每个 Day 文档现在同时包含：
- 路线图
- 当前完成情况
- 验收门槛
- 详细执行清单
不再跳转独立执行细则目录。
## 快速浏览
- HTML 总览：[agent_week_plan_html/index.html](<../agent_week_plan_html/index.html>)
- Day 1 HTML：[agent_week_plan_html/day-1.html](<../agent_week_plan_html/day-1.html>)
## 执行方式
1. 先看本文件，确认今天做哪一天、当前状态和依赖顺序。
2. 再打开当天 daily 文档，直接在同一份文档里推进开发。
3. 完成一个最小 TODO 后，再改成 `[x] ~~...~~`。
4. 每天结束时回填阻塞记录、验收结果和日终交接。
## 一周节奏
| Day | 状态 | 主题 | 主要交付 | Markdown | HTML |
| --- | --- | --- | --- | --- | --- |
| Day 1 | 已完成（2026-05-11） | 基础模型与工程骨架 | 资产、版本、审核、运行日志、审计日志、基础 API、最小财务数据源 | [Day 1](./day_1_foundation_models.md) | [HTML](<../agent_week_plan_html/day-1.html>) |
| Day 2 | 已完成，待补浏览器走查记录 | 任务规则中心联调 | 规则/技能/MCP/任务列表与详情、Markdown、版本、审核 | [Day 2](./day_2_rule_center_integration.md) | [HTML](<../agent_week_plan_html/day-2.html>) |
| Day 3 | 已完成主体功能，待补评测样本扩充 | 语义本体 MVP | 8 字段语义解析、日志、评测入口、OCR 摘要与最小会话上下文带入 | [Day 3](./day_3_semantic_ontology_mvp.md) | [HTML](<../agent_week_plan_html/day-3.html>) |
| Day 4 | 已完成主干与会话串联，待接通提交/附件持久化链路 | Orchestrator 运行时 | 统一入口、路由、权限、工具调用、报销单写入路由、会话 Trace | [Day 4](./day_4_orchestrator_runtime.md) | [HTML](<../agent_week_plan_html/day-4.html>) |
| Day 5 | 已完成问答主链路、草稿创建/补全与会话上下文，待接通提交状态流转 | User Agent MVP | 用户问答、报销单草稿创建/补全/提交、财务查询、规则解释、附件/OCR 带入 | [Day 5](./day_5_user_agent_mvp.md) | [HTML](<../agent_week_plan_html/day-5.html>) |
| Day 6 | 未开始 | Hermes MVP | 定时任务、风险巡检、日报、知识候选、规则草稿 | [Day 6](./day_6_hermes_mvp.md) | [HTML](<../agent_week_plan_html/day-6.html>) |
| Day 7 | 未开始 | 加固、演示和验收 | 回归、测试、演示脚本、交付说明 | [Day 7](./day_7_hardening_demo_acceptance.md) | [HTML](<../agent_week_plan_html/day-7.html>) |
## 当前完成情况
- Day 1 已完成，后端基础模型、审计和最小财务数据源已可供后续能力复用。
- Day 2 已完成主要前后端联调，当前仅剩浏览器人工走查记录待补。
- Day 3 主体已完成，`/api/v1/ontology/parse`、8 字段返回、缺槽位追问、权限判断和前端调试入口均已落地；OCR 摘要、附件上下文和最小会话历史已进入语义层，前端浏览器时间上下文也已接入相对时间换算，当前主要剩叙述型报销、附件/OCR 带入样本和模糊追问样本继续扩充。
- Day 4 主干已完成，Orchestrator 已具备统一入口、User Agent / Hermes 路由、权限阻断、ToolCall 记录、Trace、降级和 `conversation_id` 会话串联；`expense_claims` 草稿建单/改单与 ToolCall / Audit 已接通，但提交、附件持久化和更细的 ToolCall Trace 仍未接通。
- Day 5 问答主链路已完成，个人工作台和报销对话框已能把文本、附件名称、OCR 摘要、页面上下文和会话 ID 带入 Orchestrator，并返回回答、规则引用、风险说明、结构化草稿和识别核对面板；核对 UI 已调整为“右侧只看识别结果、主对话负责待补与风险、底部负责动作”，但附件 / OCR 结果落库及 `draft -> submitted` 仍未完成。
## Day 1 - Day 5 未完成补齐清单
- Day 1：当前周计划范围内无新增遗留项，基础资产、日志、审计和最小财务表已完成；文件资产、OCR 结果表和风险事件表作为 Day 5 真落库前置底座，设计已完成但代码未落地。
- Day 2：仍缺一轮浏览器人工走查记录，需补充规则中心真实页面联调截图或缺陷清单。
- Day 3：仍需补充叙述型报销长句样本、附件/OCR 摘要带入样本、模糊短句追问样本，并把这些样本纳入自动评测。
- Day 4：仍需接通 `submit_expense_claim` 真服务，补齐附件挂接服务注册、ToolCall 更细粒度记录和前端 Trace 展示。
- Day 5：仍需把附件和 OCR 识别结果真正落到 `document_assets`、`document_asset_versions`、`expense_item_documents`、`document_ocr_results`，并完成 `draft -> submitted` 状态流转、前端确认动作回写和提交流程确认。
## 关键依赖顺序
1. Day 1 必须先完成，因为后面所有能力都依赖资产、版本、审核、日志。
2. Day 2 必须在 Day 3 前完成，因为语义和 Agent 需要读取规则、技能、MCP、任务资产。
3. Day 3 必须在 Day 4 前完成，因为 Orchestrator 依赖语义本体做路由。
4. Day 4 必须在 Day 5 / Day 6 前完成，因为 User Agent 和 Hermes 都应该由 Orchestrator 调用。
5. Day 5 和 Day 6 可以部分并行，但都必须遵守权限、审计、Trace。
6. Day 7 不新增大功能，只做加固、验收和交接。
## 最终验收
- 任务规则中心能看到规则、技能、MCP、任务。
- 规则详情能编辑 Markdown、查看最近 5 个版本、切换版本。
- 未审核规则不能上线。
- 用户问题能解析出语义本体 8 字段。
- Orchestrator 能路由到 User Agent 和 Hermes。
- User Agent 能完成查询、解释、报销单草稿创建、字段补全和提交前确认。
- Hermes 能执行一次风险巡检或日报任务。
- AgentRun、ToolCall、AuditLog 都能追溯。
- 有演示脚本和下一阶段交接文档。

221
document/development/agent/agent week plan/day_1_foundation_models.md Normal file
View File

@@ -0,0 +1,221 @@
# Day 1：基础模型与工程骨架
## 当前状态
- [x] ~~Day 1 已完成（2026-05-11）。~~
- [x] ~~后端基础模型、API 骨架、种子数据、审计能力和 Day 2 联调入口均已落地。~~
## 今天的大开发点
Day 1 只做地基，不做复杂 Agent 智能。
核心是把后面 6 天都会用到的基础对象建出来：资产、版本、审核、运行日志、工具调用日志、语义解析日志、审计日志，以及最小财务业务数据来源。
## 为什么第一天做这个
如果没有稳定的数据模型，后面的任务规则中心、语义本体、Orchestrator、User Agent、Hermes 都会各自临时造结构，后期会很难合并。
## 今天主要交付
- [x] ~~统一资产模型：规则、技能、MCP、任务。~~
- [x] ~~版本模型：规则 Markdown 和其他资产配置快照。~~
- [x] ~~审核模型：未审核不能上线。~~
- [x] ~~Agent 运行日志：所有 Agent 执行都有 `run_id`。~~
- [x] ~~工具调用日志：MCP、数据库、LLM、OCR、规则引擎调用都可追踪。~~
- [x] ~~语义解析日志：后续语义本体结果可回放。~~
- [x] ~~审计日志：所有写操作可追责。~~
- [x] ~~最小财务业务数据来源：报销、应收、应付。~~
## 实际落地结果
- [x] ~~新增 `AgentAsset`、`AgentAssetVersion`、`AgentAssetReview`、`AgentRun`、`AgentToolCall`、`SemanticParseLog`、`AuditLog`、`ExpenseClaim`、`ExpenseClaimItem`、`AccountsReceivableRecord`、`AccountsPayableRecord`。~~
- [x] ~~新增 `/api/v1/agent-assets`、`/api/v1/agent-runs`、`/api/v1/audit-logs` 相关接口。~~
- [x] ~~种子数据已覆盖 3 条规则、2 条技能、2 条 MCP、3 条任务，以及报销 / 应收 / 应付示例数据。~~
- [x] ~~旧开发库启动时会自动补齐新增资产和版本，不需要手动清库。~~
相关架构文档：
- [整体架构](<../agent plan/01_overall_architecture.md>)
- [语义本体](<../agent plan/02_semantic_ontology.md>)
- [数据契约与治理](<../agent plan/06_data_contracts_and_governance.md>)
- [能力注册](<../agent plan/07_capability_registry.md>)
- [权限与确认](<../agent plan/08_permission_confirmation.md>)
- [观测与 Trace](<../agent plan/09_observability_and_trace.md>)
- [财务单据标准模型](<../agent plan/14_financial_document_canonical_model.md>)
## 当天验收门槛
- [x] ~~数据库或等价存储能创建基础对象。~~
- [x] ~~API 服务能启动。~~
- [x] ~~资产列表能返回规则、技能、MCP、任务。~~
- [x] ~~规则资产能关联 Markdown 当前版本。~~
- [x] ~~未审核规则不能上线。~~
- [x] ~~AgentRun 能保存一条运行记录。~~
- [x] ~~AuditLog 能保存一条写操作记录。~~
## Day 2 联调入口
- `GET /api/v1/agent-assets`
- `GET /api/v1/agent-assets/{asset_id}`
- `GET /api/v1/agent-assets/{asset_id}/versions?limit=5`
- `POST /api/v1/agent-assets/{asset_id}/reviews`
- `POST /api/v1/agent-assets/{asset_id}/activate`
- `GET /api/v1/audit-logs`
## 今天不做
- 不做完整 Agent 对话。
- 不做完整 Hermes 调度。
- 不做真实 OCR。
- 不做复杂规则推理。
## 详细执行清单
以下内容为合并后的详细执行清单。
## 0. 开始前检查
- [x] ~~确认后端目录为 `/app/server`，模型、路由、启动入口和测试目录已定位。~~
- [x] ~~确认本次改动以增量方式落到现有 FastAPI + SQLAlchemy 工程，不回退无关文件。~~
验收证据：
- [x] ~~模型注册位于 `server/src/app/db/base.py`，路由注册位于 `server/src/app/api/v1/router.py`，启动入口位于 `server/src/app/main.py`，测试位于 `server/tests`。~~
## 1. 统一命名和边界
- [x] ~~统一枚举：`rule | skill | mcp | task`、`draft | review | active | disabled`、`pending | approved | rejected`、`orchestrator | user_agent | hermes`。~~
- [x] ~~统一运行来源、权限级别、内容类型、运行状态和工具类型命名，避免出现第二套并行语义。~~
验收证据：
- [x] ~~`server/src/app/core/agent_enums.py` 已成为模型、Schema 和服务层的统一枚举入口。~~
## 2. 设计最小财务业务数据模型
- [x] ~~建立 `expense_claims`、`expense_claim_items`、`accounts_receivable`、`accounts_payable`。~~
- [x] ~~字段覆盖时间、地点、理由、金额、员工、部门、状态，以及应收 / 应付的金额、到期日、账龄、风险标记。~~
验收证据：
- [x] ~~`server/src/app/models/financial_record.py` 与 `document/development/agent plan/14_financial_document_canonical_model.md` 形成直接映射。~~
## 3. 建立 AgentAsset 模型
- [x] ~~建立 `AgentAsset`，包含 `asset_type`、`code`、`name`、`description`、`domain`、`scenario_json`、`owner`、`reviewer`、`status`、`current_version`、`config_json` 等核心字段。~~
- [x] ~~对 `code`、`asset_type`、`status`、`domain` 建立唯一约束或索引。~~
验收证据：
- [x] ~~资产列表可按 `rule`、`skill`、`mcp`、`task` 四类过滤返回。~~
## 4. 建立 AgentAssetVersion 模型
- [x] ~~建立 `AgentAssetVersion`，规则版本保存 Markdown，其余资产版本保存 JSON 快照。~~
- [x] ~~对 `asset_id + version` 建立唯一约束，并支持按资产读取最近版本列表。~~
验收证据：
- [x] ~~规则详情接口可返回 `current_version_content` 和 `recent_versions`。~~
## 5. 建立 AgentAssetReview 模型
- [x] ~~建立 `AgentAssetReview`，保存版本、审核人、审核状态、审核备注和审核时间。~~
- [x] ~~服务层实现规则版本未 `approved` 时禁止上线。~~
验收证据：
- [x] ~~`POST /api/v1/agent-assets/{asset_id}/activate` 对待审规则返回 400 拦截。~~
## 6. 建立 AgentRun 模型
- [x] ~~建立 `AgentRun`，包含 `run_id`、`agent`、`source`、`ontology_json`、`route_json`、`permission_level`、`status`、`result_summary`、`error_message` 等字段。~~
- [x] ~~所有运行记录统一生成 `run_id`，并允许失败态保存错误信息。~~
验收证据：
- [x] ~~`AgentRunService.create_run()` 会自动生成 `run_` 前缀标识，并可回读失败摘要。~~
## 7. 建立 AgentToolCall 模型
- [x] ~~建立 `AgentToolCall`，可记录工具类型、工具名、请求 / 响应 JSON、耗时和错误信息。~~
- [x] ~~同一个 `run_id` 下支持多次工具调用追踪。~~
验收证据：
- [x] ~~种子运行数据已覆盖数据库查询、MCP 调用和权限规则引擎调用。~~
## 8. 建立 SemanticParseLog 模型
- [x] ~~建立 `SemanticParseLog`，覆盖场景、意图、实体、时间范围、指标、约束、风险、权限和置信度。~~
- [x] ~~支持按 `run_id` 回放 Day 3 语义结果。~~
验收证据：
- [x] ~~`GET /api/v1/agent-runs/{run_id}` 已能携带 `semantic_parse` 返回。~~
## 9. 建立 AuditLog 模型
- [x] ~~建立 `AuditLog` 和统一 `AuditLogService`。~~
- [x] ~~资产创建、版本保存、审核、上线等写操作都会留下审计记录。~~
验收证据：
- [x] ~~`GET /api/v1/audit-logs` 可返回种子审计日志，服务层新建资产也会落审计。~~
## 10. 建立 Schema / DTO
- [x] ~~建立 `AgentAssetCreate / Update / Read / ListItem`、`AgentAssetVersionRead`、`AgentAssetReviewRead`、`RuleMarkdownUpdate`、`AgentRunRead`、`AgentToolCallRead`、`SemanticParseRead`。~~
- [x] ~~所有 JSON 字段以结构化对象返回，不回传字符串化 JSON。~~
验收证据：
- [x] ~~列表 DTO 不返回大块 Markdown，详情 DTO 返回当前版本正文和最近版本。~~
## 11. 建立 API 骨架
- [x] ~~建立 `GET/POST/PATCH /api/v1/agent-assets`、`GET /api/v1/agent-assets/{asset_id}`、`GET/POST /api/v1/agent-assets/{asset_id}/versions`、`POST /api/v1/agent-assets/{asset_id}/reviews`、`POST /api/v1/agent-assets/{asset_id}/activate`。~~
- [x] ~~建立 `GET /api/v1/agent-runs`、`GET /api/v1/agent-runs/{run_id}`、`GET /api/v1/audit-logs`。~~
验收证据：
- [x] ~~所有接口已挂到 `server/src/app/api/v1/router.py`，并通过 `create_app()` 自动暴露。~~
## 12. 建立种子数据
- [x] ~~种子资产补齐到 3 条规则、2 条技能、2 条 MCP、3 条任务。~~
- [x] ~~三条规则都具备至少 2 个版本，并覆盖 `approved / pending / rejected` 三种审核样本。~~
- [x] ~~旧开发数据库启动时会自动增量补齐新增资产和版本，不要求手动清库。~~
验收证据：
- [x] ~~Smoke：`GET /api/v1/agent-assets` 返回 10 条资产，`GET /api/v1/agent-runs` 返回 3 条运行日志，`GET /api/v1/audit-logs` 返回 4 条审计日志。~~
## 13. 最小测试
- [x] ~~新增 Day 1 服务层与接口层测试，覆盖种子完整性、版本历史、未审核不能上线、运行日志生成和审计日志写入。~~
- [x] ~~Ruff 校验通过，Day 1 新增文件保持可检查状态。~~
验收证据：
- [x] ~~`/app/server/.venv/bin/pytest -q /app/server/tests/test_agent_asset_service.py /app/server/tests/test_agent_foundation_endpoints.py` -> `11 passed`。~~
- [x] ~~`/app/server/.venv/bin/pytest -q tests` 已通过全量后端测试。~~
## 14. Day 1 验收
- [x] ~~数据库能创建所有新增表或等价结构。~~
- [x] ~~API 服务能启动，OpenAPI 能看到新增接口。~~
- [x] ~~资产列表接口返回规则、技能、MCP、任务；规则详情带 Markdown 当前版本和最近版本列表。~~
- [x] ~~未审核规则不能上线；AgentRun 和 AuditLog 均可保存记录。~~
- [x] ~~所有 Day 1 TODO 已改为完成态。~~
## 阻塞记录
- [x] ~~暂无阻塞。~~
## 日终交接
- [x] ~~已完成模型：资产、版本、审核、运行日志、工具调用、语义解析、审计、报销、应收、应付。~~
- [x] ~~已完成 API：`/api/v1/agent-assets`、`/api/v1/agent-runs`、`/api/v1/audit-logs`。~~
- [x] ~~Day 2 前端联调应优先使用 `GET /api/v1/agent-assets`、`GET /api/v1/agent-assets/{asset_id}`、`GET /api/v1/agent-assets/{asset_id}/versions?limit=5`、`POST /api/v1/agent-assets/{asset_id}/reviews`、`POST /api/v1/agent-assets/{asset_id}/activate`。~~
- [x] ~~后续 Day 4 及以后运行时方向按用户要求转向 `LangChain + LangGraph`，Hermes 继续作为内部数字员工入口；Day 1 保留为数据与治理底座。~~

296
document/development/agent/agent week plan/day_2_rule_center_integration.md Normal file
View File

@@ -0,0 +1,296 @@
# Day 2：任务规则中心联调
## 今天的大开发点
把任务规则中心从静态页面改成可和后端资产体系联动的生产形态。
重点是规则、技能、MCP、任务四类资产的列表和详情，以及规则 Markdown、版本、审核、上线约束。
## 为什么第二天做这个
任务规则中心是业务人员管理 Agent 能力的入口。后续语义本体、Orchestrator、User Agent、Hermes 都要读取这里注册的规则、技能、MCP 和任务。
## 今天主要交付
- 规则、技能、MCP、任务四个页签对接资产 API。
- 列表支持搜索、筛选、状态展示。
- 规则详情展示 Markdown 内容。
- 管理员可编辑规则 Markdown。
- 规则版本展示最近 5 个版本。
- 版本切换需要弹窗确认。
- 审核者信息放在标题区域。
- 右侧只保留版本信息。
- 未审核规则上线时被后端拦截。
## 当前完成情况
- [x] ~~四个页签已切到真实资产 API。~~
- [x] ~~规则 Markdown、版本切换、审核、上线动作已联调。~~
- [x] ~~前端构建已通过。~~
- [ ] 浏览器手动走查记录待补。
相关架构文档：
- [能力注册](<../agent plan/07_capability_registry.md>)
- [规则形成生命周期](<../agent plan/13_rule_formation_lifecycle.md>)
- [数据契约与治理](<../agent plan/06_data_contracts_and_governance.md>)
## 当天验收门槛
- 四个页签可切换并有真实 API 或 Mock API 数据。
- 规则详情可编辑 Markdown。
- Markdown 保存后刷新不丢失。
- 版本卡片可切换版本。
- 未审核规则不能上线。
- 前端构建通过。
## 今天不做
- 不做规则自动生成。
- 不做完整 MCP 真实调用。
- 不做复杂权限矩阵。
- 不重做 UI 风格，只在现有风格上微调。
## 详细执行清单
以下内容为合并后的详细执行清单。
## 0. 开始前检查
- [x] ~~确认 Day 1 API 已可访问。~~
- [x] ~~确认前端任务规则中心文件位置。~~
- [x] ~~确认现有路由名称和导航名称。~~
- [x] ~~确认现有 UI 风格，不重新做大改版。~~
- [x] ~~确认当前页面已有页签：规则、技能、MCP、任务。~~
- [x] ~~确认详情页隐藏顶部 title bar 的逻辑仍然有效。~~
- [x] ~~确认返回列表栏高度没有被重新拉高。~~
## 1. API Client
- [x] ~~新增或扩展资产列表请求函数。~~
- [x] ~~新增资产详情请求函数。~~
- [x] ~~新增版本列表请求函数。~~
- [x] ~~新增规则 Markdown 保存请求函数。~~
- [x] ~~新增审核请求函数。~~
- [x] ~~新增上线请求函数。~~
- [x] ~~新增运行日志请求函数。~~
- [x] ~~给所有请求增加加载态。~~
- [x] ~~给所有请求增加错误态。~~
- [x] ~~给所有写请求增加成功提示。~~
验收证据：
- [x] ~~前端不再只依赖本地硬编码资产数据。~~
- [x] ~~后端不可用时页面有明确错误提示。~~
## 2. 列表页数据接入
- [x] ~~规则页签请求 `asset_type=rule`。~~
- [x] ~~技能页签请求 `asset_type=skill`。~~
- [x] ~~MCP 页签请求 `asset_type=mcp`。~~
- [x] ~~任务页签请求 `asset_type=task`。~~
- [x] ~~搜索框传递关键词或本地过滤。~~
- [x] ~~类型下拉和搜索框可以同时生效。~~
- [x] ~~状态筛选可以过滤 `draft | review | active | disabled`。~~
- [x] ~~列表卡片展示名称。~~
- [x] ~~列表卡片展示摘要。~~
- [x] ~~列表卡片展示状态。~~
- [x] ~~列表卡片展示负责人。~~
- [x] ~~列表卡片展示最近更新时间。~~
- [x] ~~空数据时展示空态。~~
- [x] ~~加载中时展示骨架或加载状态。~~
验收证据：
- [x] ~~四个页签都能切换。~~
- [x] ~~四个页签都有数据或空态。~~
- [x] ~~搜索和筛选不会互相覆盖。~~
## 3. 规则详情页主信息
- [x] ~~打开规则资产时请求详情 API。~~
- [x] ~~Hero title 展示规则名称。~~
- [x] ~~Hero title 下方展示审核者。~~
- [x] ~~Hero title 下方展示审核状态。~~
- [x] ~~Hero title 下方展示上线条件。~~
- [x] ~~Hero title 高度保持紧凑。~~
- [x] ~~详情页不显示外层顶部 title bar。~~
- [x] ~~返回列表栏高度保持原有紧凑高度。~~
验收证据：
- [x] ~~用户能一眼看到该规则是否已审核。~~
- [x] ~~用户不会看到两层 title。~~
## 4. Markdown 编辑器
- [x] ~~从当前版本读取 Markdown 内容。~~
- [x] ~~Markdown 编辑框高度和右侧版本卡片底部对齐。~~
- [x] ~~Markdown 编辑框支持长内容滚动。~~
- [x] ~~Markdown 编辑框保存时调用 API。~~
- [x] ~~保存后创建新版本或更新草稿版本，按后端约定执行。~~
- [x] ~~保存成功后刷新版本列表。~~
- [x] ~~保存失败时保留用户输入。~~
- [x] ~~编辑器禁用态覆盖 `active` 且无编辑权限的情况。~~
- [x] ~~编辑器底部展示最后保存时间。~~
验收证据：
- [x] ~~编辑 Markdown 后刷新页面内容仍存在。~~
- [x] ~~保存失败不会丢内容。~~
- [x] ~~左右卡片底部视觉对齐。~~
## 5. 版本卡片
- [x] ~~右侧只保留版本信息卡片。~~
- [x] ~~版本卡片宽度足够展示版本号、日期、状态。~~
- [x] ~~展示最近 5 个版本。~~
- [x] ~~当前版本有明显但不突兀的标识。~~
- [x] ~~当前版本标识居中显示。~~
- [x] ~~选中状态只变色，不改变内容对齐。~~
- [x] ~~日期列和其他版本日期对齐。~~
- [x] ~~点击非当前版本时弹出确认弹窗。~~
- [x] ~~弹窗展示目标版本号。~~
- [x] ~~弹窗展示切换风险提示。~~
- [x] ~~确认后切换当前展示内容。~~
- [x] ~~取消后不改变当前版本。~~
验收证据：
- [x] ~~版本切换不会造成列表文字位移。~~
- [x] ~~当前版本背景能完全覆盖内容区域。~~
- [x] ~~版本卡片不贴右侧边界。~~
## 6. 审核与上线
- [x] ~~详情中展示审核者姓名。~~
- [x] ~~详情中展示审核时间。~~
- [x] ~~详情中展示审核意见。~~
- [x] ~~未审核规则显示不能上线原因。~~
- [x] ~~点击上线时调用后端上线接口。~~
- [x] ~~后端拒绝时展示拒绝原因。~~
- [x] ~~审核通过后上线按钮可用。~~
- [x] ~~审核动作写入审计日志。~~
- [x] ~~上线动作写入审计日志。~~
验收证据：
- [x] ~~pending 规则无法上线。~~
- [x] ~~approved 规则可以上线。~~
- [x] ~~rejected 规则无法上线。~~
## 7. 技能详情
- [x] ~~技能页签列表展示能力名称。~~
- [x] ~~技能详情展示能力说明。~~
- [x] ~~技能详情展示输入参数。~~
- [x] ~~技能详情展示输出参数。~~
- [x] ~~技能详情展示依赖能力。~~
- [x] ~~技能详情展示适用场景。~~
- [x] ~~技能详情展示负责人。~~
- [x] ~~技能详情展示版本。~~
- [x] ~~技能详情不使用规则 Markdown 编辑器。~~
验收证据：
- [x] ~~技能和规则详情不会混用 UI。~~
## 8. MCP 详情
- [x] ~~MCP 页签列表展示外部服务名称。~~
- [x] ~~MCP 详情展示服务类型。~~
- [x] ~~MCP 详情展示调用地址或能力名。~~
- [x] ~~MCP 详情展示鉴权方式。~~
- [x] ~~MCP 详情展示超时配置。~~
- [x] ~~MCP 详情展示降级策略。~~
- [x] ~~MCP 详情展示最近调用状态。~~
- [x] ~~MCP 详情展示负责人。~~
验收证据：
- [x] ~~MCP 被定义为外部服务，而不是技能规则。~~
## 9. 任务详情
- [x] ~~任务页签展示定时任务名称。~~
- [x] ~~任务详情展示 cron 或调度周期。~~
- [x] ~~任务详情展示执行 Agent，默认 Hermes。~~
- [x] ~~任务详情展示任务目标。~~
- [x] ~~任务详情展示风险等级。~~
- [x] ~~任务详情展示最近执行时间。~~
- [x] ~~任务详情展示最近执行结果。~~
- [x] ~~任务详情展示启停状态。~~
验收证据：
- [x] ~~定时任务用户可见名称为“任务”。~~
- [x] ~~技术字段可保留 `schedule`，但 UI 不显示“定时任务”。~~
## 10. 前端质量
- [x] ~~页面在 1366 宽度下无横向滚动。~~
- [x] ~~页面在 1920 宽度下右侧卡片不过宽。~~
- [x] ~~页面在窄屏下详情区域可滚动。~~
- [x] ~~所有按钮有禁用态。~~
- [x] ~~所有弹窗有取消按钮。~~
- [x] ~~所有表单错误有提示。~~
- [x] ~~所有日期格式统一。~~
- [x] ~~状态颜色和现有系统一致。~~
验收证据：
- [x] ~~`npm run build` 通过。~~
- [ ] 任务规则中心手动走查通过。
## 11. Day 2 验收
- [x] ~~规则、技能、MCP、任务四个页签可用。~~
- [x] ~~搜索框和筛选下拉可用。~~
- [x] ~~规则详情展示 Markdown。~~
- [x] ~~规则 Markdown 可保存。~~
- [x] ~~右侧只保留版本信息。~~
- [x] ~~版本可切换且有弹窗确认。~~
- [x] ~~审核者信息在标题下方。~~
- [x] ~~未审核规则不能上线。~~
- [x] ~~前端构建通过。~~
- [x] ~~所有完成项已按完成态标记。~~
## 阻塞记录
- [x] ~~暂无。~~
## 日终交接
- [x] ~~写明已接入的 API。~~
- [x] ~~写明仍然使用 Mock 的字段。~~
- [x] ~~写明 UI 未完成项。~~
- [x] ~~写明 Day 3 语义本体需要复用的资产数据。~~
已接入的 API：
- `GET /api/v1/agent-assets?asset_type=rule|skill|mcp|task`
- `GET /api/v1/agent-assets/{asset_id}`
- `GET /api/v1/agent-assets/{asset_id}/versions`
- `POST /api/v1/agent-assets/{asset_id}/versions`
- `POST /api/v1/agent-assets/{asset_id}/reviews`
- `POST /api/v1/agent-assets/{asset_id}/activate`
- `GET /api/v1/agent-runs`
仍然使用 Mock / 种子数据的字段：
- MCP 服务地址仍是 `mock://...` 种子地址，用于占位联调。
- MCP 最近调用状态、任务最近执行结果来自 Day 1 注入的 `AgentRun` 种子数据。
- 技能、MCP、任务详情仍以只读方式展示，未开放编辑表单。
UI 未完成项：
- 未做浏览器内人工走查记录，当前仅完成构建验证与代码层联调。
- 技能、MCP、任务的编辑能力仍留待后续 Day 3 / Day 4 之后按权限开放。
Day 3 语义本体需要复用的资产数据：
- 资产主键与编码：`id`、`code`、`asset_type`
- 业务归类：`domain`、`scenario_json`
- 当前生效版本：`current_version`、`current_version_content`、`current_version_content_type`
- 治理状态：`status`、`latest_review`、`recent_versions`
- 运行关联：`config_json.agent`、`config_json.cron`、`AgentRun.task_id`、`tool_calls`

304
document/development/agent/agent week plan/day_3_semantic_ontology_mvp.md Normal file
View File

@@ -0,0 +1,304 @@
# Day 3：语义本体 MVP
## 今天的大开发点
建立模型优先的语义解析层，把自然语言问题转换成统一的 8 个核心字段。
这一天的目标不是继续堆关键词，而是先把真实模型接入语义层，让报销、应收、应付、知识和风险相关问题进入稳定结构，再由规则做兜底和校验。
## 为什么第三天做这个
Orchestrator 不能直接根据原始文本做可靠路由。它需要先拿到结构化语义，再决定调用 User Agent、Hermes、规则、MCP 或知识库。
## 今天主要交付
- 语义本体 8 字段结构。
- 场景识别：报销、应收、应付、知识、未知。
- 意图识别：查询、解释、对比、风险检查、草稿、操作。
- 业务对象提取：员工、客户、供应商、部门、项目、单据、金额。
- 时间范围解析。
- 指标和约束解析。
- 风险信号和权限级别判断。
- LLM 结构化解析 Prompt。
- Schema 校验与 JSON 清洗。
- 规则回退解析。
- 低置信度追问和缺槽位追问。
- 语义解析 API。
- 解析日志和最小评测集。
## 当前完成情况
- [x] ~~`/api/v1/ontology/parse` 已上线，8 字段语义结构、缺槽位、歧义、权限和澄清问题均可返回。~~
- [x] ~~语义层已切到“模型优先 + 规则回退”，并把结果写入 `AgentRun` / `SemanticParseLog`。~~
- [x] ~~附件名称、附件数量、OCR 摘要和 OCR 文档摘要已能作为上下文带入语义层。~~
- [x] ~~最小会话历史、上一轮场景/意图和 `draft_claim_id` 已能作为上下文带入语义层，用于识别“改成 800”“继续补充”这类追问。~~
- [x] ~~叙述型报销语义已补强：`客户 + 吃饭/请客/宴请/招待` 优先归类为业务招待费，不再误打到应收查询。~~
- [x] ~~相对时间已支持标准化展示：前端会透传浏览器本地时间上下文，`今天 / 昨天 / 本月 / 4 月` 会换算成绝对日期；展示层默认优先显示绝对日期，原始表达仅作为辅助信息。~~
- [x] ~~前端调试入口与核心评测测试已完成并通过。~~
- [ ] 叙述型报销样本、附件/OCR 带入样本和模糊短句追问样本仍需继续扩充。
相关架构文档：
- [语义本体](<../agent plan/02_semantic_ontology.md>)
- [财务单据标准模型](<../agent plan/14_financial_document_canonical_model.md>)
- [数据契约与治理](<../agent plan/06_data_contracts_and_governance.md>)
## 当天验收门槛
- 输入自然语言问题能返回 8 个字段。
- 模型解析失败时能自动回退到规则解析。
- 低置信度问题能返回澄清问题。
- 越权动作不会被标记为可直接执行。
- 解析结果能写入日志。
- 至少覆盖报销、应收、应付三个场景。
- 叙述型报销输入不会被错误路由到应收或应付。
## 今天不做
- 不做复杂多轮对话记忆。
- 不做完整 Agent 自主规划。
- 不做自动执行业务流程。
## 详细执行清单
以下内容为合并后的详细执行清单。
## 0. 开始前检查
- [x] ~~确认 Day 1 的 `SemanticParseLog` 可用。~~
- [x] ~~确认 Day 1 的 `AgentRun` 可用。~~
- [x] ~~确认 Day 2 的资产 API 可用。~~
- [x] ~~找到后端服务层目录。~~
- [x] ~~找到现有 LLM 调用或 Mock 调用方式。~~
- [x] ~~确认当前是否允许真实调用 LLM。~~
- [x] ~~确认当前运行时模型槽位可用于语义解析。~~
- [x] ~~如果真实模型不可用，已准备规则解析回退路径。~~
## 1. 定义 8 个核心字段
- [x] ~~定义字段 `scenario`，表示业务场景。~~
- [x] ~~定义字段 `intent`，表示用户意图。~~
- [x] ~~定义字段 `entities`，表示业务对象。~~
- [x] ~~定义字段 `time_range`，表示时间范围。~~
- [x] ~~定义字段 `metrics`，表示指标或金额口径。~~
- [x] ~~定义字段 `constraints`，表示过滤条件。~~
- [x] ~~定义字段 `risk_flags`，表示风险信号。~~
- [x] ~~定义字段 `permission`，表示动作权限。~~
- [x] ~~为每个字段写清楚类型。~~
- [x] ~~为每个字段写清楚是否必填。~~
- [x] ~~为每个字段写清楚默认值。~~
- [x] ~~为每个字段写清楚示例。~~
验收证据：
- [x] ~~8 个字段在 Schema、服务层、日志中名字一致。~~
## 2. 设计字段枚举
- [x] ~~`scenario` 支持 `expense`。~~
- [x] ~~`scenario` 支持 `accounts_receivable`。~~
- [x] ~~`scenario` 支持 `accounts_payable`。~~
- [x] ~~`scenario` 支持 `knowledge`。~~
- [x] ~~`scenario` 支持 `unknown`。~~
- [x] ~~`intent` 支持 `query`。~~
- [x] ~~`intent` 支持 `explain`。~~
- [x] ~~`intent` 支持 `compare`。~~
- [x] ~~`intent` 支持 `risk_check`。~~
- [x] ~~`intent` 支持 `draft`。~~
- [x] ~~`intent` 支持 `operate`。~~
- [x] ~~`permission.level` 支持 `read`。~~
- [x] ~~`permission.level` 支持 `draft_write`。~~
- [x] ~~`permission.level` 支持 `approval_required`。~~
- [x] ~~`permission.level` 支持 `forbidden`。~~
验收证据：
- [x] ~~未识别的问题不会抛异常，返回 `unknown`。~~
## 3. 建立 Schema
- [x] ~~定义 `OntologyParseRequest`。~~
- [x] ~~`OntologyParseRequest` 包含 `query`。~~
- [x] ~~`OntologyParseRequest` 包含 `user_id`。~~
- [x] ~~`OntologyParseRequest` 包含 `context_json`。~~
- [x] ~~定义 `OntologyParseResult`。~~
- [x] ~~`OntologyParseResult` 包含 8 个核心字段。~~
- [x] ~~`OntologyParseResult` 包含 `confidence`。~~
- [x] ~~`OntologyParseResult` 包含 `clarification_required`。~~
- [x] ~~`OntologyParseResult` 包含 `clarification_question`。~~
- [x] ~~`OntologyParseResult` 包含 `run_id`。~~
- [x] ~~定义字段级错误结构。~~
验收证据：
- [x] ~~OpenAPI 中可以看到语义解析请求和响应。~~
## 4. 实现解析服务
- [x] ~~新增 `SemanticOntologyService` 或同等服务。~~
- [x] ~~实现 `parse(query, user_context)` 主函数。~~
- [x] ~~增加上下文装配层，输入文本、页面上下文、附件摘要和预抽取字段。~~
- [x] ~~实现模型优先的结构化语义解析。~~
- [x] ~~约束模型只输出 JSON。~~
- [x] ~~对模型输出做清洗、提取和 Schema 校验。~~
- [x] ~~模型失败时自动回退到规则解析。~~
- [x] ~~在结果中记录本次使用了 `llm_primary` 还是 `rule_fallback`。~~
- [x] ~~报销关键词映射到 `expense`。~~
- [x] ~~应收、回款、客户欠款映射到 `accounts_receivable`。~~
- [x] ~~应付、供应商、付款映射到 `accounts_payable`。~~
- [x] ~~风险、异常、重复、超标映射到 `risk_check`。~~
- [x] ~~为什么、依据、规则映射到 `explain`。~~
- [x] ~~统计、汇总、多少映射到 `query`。~~
- [x] ~~生成、创建、发起映射到 `draft` 或 `operate`。~~
- [x] ~~无法识别时返回低置信度和澄清问题。~~
- [x] ~~叙述型报销输入优先识别为创建/草稿，而不是查询。~~
验收证据：
- [x] ~~“查一下本周报销超标风险”能识别为 expense + risk_check。~~
- [x] ~~“客户 A 这个月还有多少应收”能识别为 accounts_receivable + query。~~
- [x] ~~“供应商 B 明天要付多少钱”能识别为 accounts_payable + query。~~
- [x] ~~“我今天去客户现场，招待了客户，花销了1000元”不会错误识别为应收查询。~~
- [x] ~~“昨天请客户吃饭花了 200 元”会优先识别为报销草稿语义，并把“昨天”换算为用户本地日期下的绝对日期。~~
## 5. 解析业务对象
- [x] ~~从问题中提取员工姓名。~~
- [x] ~~从问题中提取部门。~~
- [x] ~~从问题中提取客户。~~
- [x] ~~从问题中提取供应商。~~
- [x] ~~从问题中提取项目。~~
- [x] ~~从问题中提取单据号。~~
- [x] ~~从问题中提取金额。~~
- [x] ~~从问题中提取费用类型。~~
- [x] ~~无法提取时返回空数组，不返回 null。~~
验收证据：
- [x] ~~“张三 4 月差旅报销”能提取员工、月份、费用类型。~~
## 6. 解析时间范围
- [x] ~~支持今天。~~
- [x] ~~支持昨天。~~
- [x] ~~支持本周。~~
- [x] ~~支持上周。~~
- [x] ~~支持本月。~~
- [x] ~~支持上月。~~
- [x] ~~支持本季度。~~
- [x] ~~支持今年。~~
- [x] ~~支持明确日期。~~
- [x] ~~支持日期区间。~~
- [x] ~~解析结果包含 `start_date` 和 `end_date`。~~
- [x] ~~日期使用 ISO 格式。~~
验收证据：
- [x] ~~“本周”能解析为当前周起止日期。~~
- [x] ~~“2026 年 4 月”能解析为 `2026-04-01` 到 `2026-04-30`。~~
## 7. 解析指标与约束
- [x] ~~识别金额指标。~~
- [x] ~~识别数量指标。~~
- [x] ~~识别超标指标。~~
- [x] ~~识别逾期指标。~~
- [x] ~~识别重复报销指标。~~
- [x] ~~识别部门过滤条件。~~
- [x] ~~识别状态过滤条件。~~
- [x] ~~识别金额阈值过滤条件。~~
- [x] ~~识别排序要求。~~
- [x] ~~识别 Top N 要求。~~
验收证据：
- [x] ~~“列出金额最高的 10 笔报销”能识别排序和 Top 10。~~
## 8. 解析风险与权限
- [x] ~~重复报销映射到 `duplicate_expense`。~~
- [x] ~~发票异常映射到 `invoice_anomaly`。~~
- [x] ~~金额超标映射到 `amount_over_limit`。~~
- [x] ~~逾期应收映射到 `ar_overdue`。~~
- [x] ~~逾期应付映射到 `ap_overdue`。~~
- [x] ~~查询类问题权限为 `read`。~~
- [x] ~~生成草稿权限为 `draft_write`。~~
- [x] ~~审批、上线、付款类动作权限为 `approval_required`。~~
- [x] ~~越权动作权限为 `forbidden`。~~
验收证据：
- [x] ~~“帮我直接付款”不能被标为可直接执行。~~
## 9. API 接口
- [x] ~~新增 `POST /api/v1/ontology/parse`。~~
- [x] ~~请求参数包含用户问题。~~
- [x] ~~请求参数包含用户上下文。~~
- [x] ~~响应包含 8 个字段。~~
- [x] ~~响应包含 `run_id`。~~
- [x] ~~响应包含置信度。~~
- [x] ~~响应包含澄清问题。~~
- [x] ~~每次调用写入 `SemanticParseLog`。~~
- [x] ~~每次调用写入 `AgentRun` 或关联已有 `AgentRun`。~~
验收证据：
- [x] ~~连续调用多次都能在日志中查到。~~
## 10. 前端调试入口
- [x] ~~在合适页面增加语义解析调试入口。~~
- [x] ~~输入框支持自然语言问题。~~
- [x] ~~点击解析后调用 API。~~
- [x] ~~展示 8 个字段。~~
- [x] ~~展示 JSON 原始结果。~~
- [x] ~~展示置信度。~~
- [x] ~~展示澄清问题。~~
- [x] ~~展示 `run_id`。~~
- [x] ~~错误时展示错误信息。~~
验收证据：
- [x] ~~产品和开发可以直接在页面验证解析结果。~~
## 11. 评测集
- [x] ~~创建至少 5 条报销问题。~~
- [ ] 创建至少 5 条叙述型报销问题。
- [ ] 创建至少 3 条附件 / OCR 摘要带入的报销问题。
- [x] ~~创建至少 5 条应收问题。~~
- [x] ~~创建至少 5 条应付问题。~~
- [x] ~~创建至少 3 条知识库问题。~~
- [x] ~~创建至少 3 条越权操作问题。~~
- [ ] 创建至少 3 条模糊短句追问问题。
- [x] ~~为每条问题写期望 `scenario`。~~
- [x] ~~为每条问题写期望 `intent`。~~
- [x] ~~为每条问题写期望权限级别。~~
- [x] ~~编写评测脚本或测试。~~
验收证据：
- [x] ~~当前评测样本集已通过，覆盖样本准确率达到当天设定阈值。~~
## 12. Day 3 验收
- [x] ~~语义解析 API 可用。~~
- [x] ~~8 个核心字段完整返回。~~
- [x] ~~解析日志可查询。~~
- [x] ~~低置信度问题有澄清问题。~~
- [x] ~~越权动作不会被标为可执行。~~
- [x] ~~前端调试入口可用。~~
- [x] ~~评测集可运行。~~
- [x] ~~所有完成项已用 `[x] ~~...~~` 标记。~~
## 阻塞记录
- [x] ~~暂无。~~
## 日终交接
- [x] ~~已支持报销 / 应收 / 应付 / 知识 / 风险 / 草稿 / 越权动作等核心场景关键词、实体与权限解析。~~
- [x] ~~语义层已可接收附件名称、附件数量和 OCR 摘要上下文，但这些样本仍需继续扩到评测集。~~
- [x] ~~当前仍需继续扩充的弱样本主要是叙述型报销长句、附件/OCR 带入和模糊短句追问。~~
- [x] ~~Day 4 可直接复用 `scenario / intent / entities / time_range / metrics / constraints / risk_flags / permission / confidence / missing_slots / ambiguity / parse_strategy / clarification_required / clarification_question / run_id`。~~

254
document/development/agent/agent week plan/day_4_orchestrator_runtime.md Normal file
View File

@@ -0,0 +1,254 @@
# Day 4：Orchestrator 运行时
## 今天的大开发点
建立统一调度层。用户请求和系统任务都先进入 Orchestrator，由它完成语义解析、权限判断、能力选择、Agent 路由、工具调用记录和失败降级。
## 为什么第四天做这个
没有 Orchestrator，User Agent 和 Hermes 会各自直接调用能力，权限、审计、降级、Trace 都会分散。生产系统必须有统一入口。
## 今天主要交付
- Orchestrator 请求和响应结构。
- 用户请求路由到 User Agent。
- 定时任务路由到 Hermes。
- 权限级别判断。
- 语义补槽完成后的报销草稿创建、草稿更新、提交动作路由。
- 高风险动作确认机制。
- 能力注册查询。
- 工具调用封装。
- AgentRun Trace 查询。
- 失败降级返回。
## 当前完成情况
- [x] ~~`/api/v1/orchestrator/run`、统一路由、权限阻断、ToolCall 记录、Trace 和降级结果已经可用。~~
- [x] ~~用户消息已能路由到 User Agent，占位 Hermes 任务也能由定时入口触发。~~
- [x] ~~附件名称、页面上下文和 OCR 摘要已能随 Orchestrator 请求透传到语义层和 User Agent。~~
- [x] ~~Orchestrator 已开始向前端返回结构化 `review_payload`，用于右侧预审面板展示识别意图、槽位、票据和分单建议。~~
- [x] ~~`conversation_id`、会话消息历史和 `draft_claim_id` 已接入 Orchestrator，会话内追问可继续落到同一张报销草稿。~~
- [x] ~~已新增最近会话恢复与用户级会话清空接口，个人工作台可显式继续旧会话或删除旧会话后新建。~~
- [x] ~~`clarification_required` 的报销请求已改为返回结构化核对结果，而不是只回一句追问文案。~~
- [x] ~~`review_action`、`review_form_values` 已能透传到 User Agent / 报销草稿服务，用于结构化修改后重识别和保存草稿。~~
- [ ] 真实 `expense_claims` 提交链路尚未接通；草稿建单 / 改单已接到真实落库，附件与 OCR 持久化仍未完成。
- [ ] 报销附件持久化服务、OCR 结果落库服务和前端 ToolCall 细粒度 Trace 展示尚未接通。
相关架构文档：
- [Orchestrator 与运行流程](<../agent plan/04_orchestrator_and_runtime_flow.md>)
- [能力注册](<../agent plan/07_capability_registry.md>)
- [权限与确认](<../agent plan/08_permission_confirmation.md>)
- [观测与 Trace](<../agent plan/09_observability_and_trace.md>)
## 当天验收门槛
- Orchestrator API 可用。
- 用户消息能路由到 User Agent 占位实现。
- 定时任务能路由到 Hermes 占位实现。
- forbidden 请求不会调用下游 Agent。
- 每次运行都有 `run_id` 和 Trace。
- 工具调用失败能记录并返回降级结果。
- 叙述型报销输入在满足最小槽位后能进入建单或改单流程。
## 今天不做
- 不做复杂任务编排 DAG。
- 不做多 Agent 协商。
- 不做自动高风险动作。
## 详细执行清单
以下内容为合并后的详细执行清单。
## 0. 开始前检查
- [x] ~~确认 Day 3 `POST /api/v1/ontology/parse` 可用。~~
- [x] ~~确认 `AgentRun` 可创建。~~
- [x] ~~确认 `AgentToolCall` 可创建。~~
- [x] ~~确认资产列表能查询技能、MCP、任务。~~
- [x] ~~确认权限级别枚举已稳定。~~
- [x] ~~找到后端服务层适合放 Orchestrator 的位置。~~
## 1. Orchestrator 输入输出
- [x] ~~定义 `OrchestratorRequest`。~~
- [x] ~~请求包含 `source`。~~
- [x] ~~请求包含 `user_id`。~~
- [x] ~~请求包含 `message`。~~
- [x] ~~请求包含 `task_id`。~~
- [x] ~~请求包含 `context_json`。~~
- [x] ~~定义 `OrchestratorResponse`。~~
- [x] ~~响应包含 `run_id`。~~
- [x] ~~响应包含 `selected_agent`。~~
- [x] ~~响应包含 `route_reason`。~~
- [x] ~~响应包含 `permission_level`。~~
- [x] ~~响应包含 `status`。~~
- [x] ~~响应包含 `result`。~~
- [x] ~~响应包含 `requires_confirmation`。~~
- [x] ~~响应包含 `trace_summary`。~~
验收证据：
- [x] ~~Orchestrator 响应能直接被前端展示。~~
## 2. 建立 Orchestrator 服务
- [x] ~~新增 `OrchestratorService`。~~
- [x] ~~实现 `run(request)` 主入口。~~
- [x] ~~主入口第一步创建 `AgentRun`。~~
- [x] ~~主入口第二步调用语义解析。~~
- [x] ~~主入口第三步执行权限判断。~~
- [x] ~~主入口第四步选择 Agent。~~
- [x] ~~主入口第五步调用目标 Agent 或返回阻断结果。~~
- [x] ~~主入口第六步更新 `AgentRun` 状态。~~
- [x] ~~所有异常都写入 `AgentRun.error_message`。~~
验收证据：
- [x] ~~正常请求状态为 `succeeded`。~~
- [x] ~~被权限拦截请求状态为 `blocked`。~~
- [x] ~~异常请求状态为 `failed`。~~
## 3. 路由规则
- [x] ~~`source=user_message` 默认路由到 User Agent。~~
- [x] ~~`source=schedule` 默认路由到 Hermes。~~
- [x] ~~`intent=risk_check` 且来源为 schedule 时路由到 Hermes。~~
- [x] ~~`intent=query` 且来源为 user_message 时路由到 User Agent。~~
- [x] ~~`intent=explain` 路由到 User Agent。~~
- [x] ~~`intent=draft` 路由到 User Agent，并可返回结构化核对结果、草稿结果或草稿更新结果。~~
- [x] ~~`scenario=expense` 且最小建单槽位完整时，允许进入 `create_expense_claim_draft`。~~
- [x] ~~`scenario=expense` 且已有 `claim_id` 或会话内 `draft_claim_id` 时，允许进入 `update_expense_claim_draft`。~~
- [ ] `scenario=expense` 且用户明确确认提交时，允许进入 `submit_expense_claim`。
- [x] ~~`permission.level=approval_required` 时设置 `requires_confirmation=true`。~~
- [x] ~~`permission.level=forbidden` 时不调用下游 Agent。~~
- [x] ~~无法识别或信息不足时返回澄清问题。~~
验收证据：
- [x] ~~同一句风险检查，在用户入口和任务入口有不同路由结果。~~
## 4. 权限判断
- [x] ~~新增权限判断服务或函数。~~
- [x] ~~查询类请求返回 `read`。~~
- [x] ~~草稿类请求返回 `draft_write`。~~
- [ ] 报销草稿字段补全、附件挂接返回 `draft_write`。
- [ ] 报销单提交返回 `approval_required`，并要求显式用户确认。
- [ ] 审批、上线、付款类请求返回 `approval_required`。
- [x] ~~用户无权限时返回 `forbidden`。~~
- [x] ~~高风险动作不允许自动执行。~~
- [x] ~~需要确认的动作返回确认提示。~~
- [x] ~~权限判断结果写入 `AgentRun.permission_level`。~~
验收证据：
- [x] ~~“直接上线规则”不会被自动执行。~~
- [x] ~~“直接付款”不会被自动执行。~~
## 5. 能力注册查询
- [x] ~~从 `AgentAsset` 查询 active 技能。~~
- [x] ~~从 `AgentAsset` 查询 active MCP。~~
- [x] ~~从 `AgentAsset` 查询 active 任务。~~
- [ ] 查询可用的报销单写入服务和附件挂接服务。
- [ ] 查询可用的 OCR 结果持久化服务和票据文件回溯服务。
- [x] ~~过滤 disabled 能力。~~
- [x] ~~过滤未审核 active 条件不满足的规则。~~
- [x] ~~为每次能力选择记录 `route_json`。~~
- [x] ~~找不到能力时返回降级说明。~~
验收证据：
- [x] ~~禁用 MCP 不会被 Orchestrator 调用。~~
## 6. 工具调用封装
- [x] ~~定义统一工具调用接口。~~
- [ ] 工具请求前写入 `AgentToolCall` running 或准备记录。
- [x] ~~工具成功后写入响应和耗时。~~
- [x] ~~工具失败后写入错误。~~
- [ ] 报销草稿更新、提交也按工具调用或等价服务调用记录。
- [x] ~~报销草稿创建按工具调用或等价服务调用记录。~~
- [ ] 附件挂接、OCR 结果落库、票据回溯查询也按工具调用或等价服务调用记录。
- [x] ~~外部 MCP 调用失败时返回降级结果。~~
- [x] ~~数据库查询失败时返回明确错误。~~
- [x] ~~LLM 调用失败时返回可读提示。~~
验收证据：
- [x] ~~每次 Orchestrator 运行至少可以看到 0 到多条工具调用记录。~~
## 7. API 接口
- [x] ~~新增 `POST /api/v1/orchestrator/run`。~~
- [x] ~~请求支持用户消息。~~
- [x] ~~请求支持任务触发。~~
- [x] ~~响应返回 `run_id`。~~
- [x] ~~响应返回路由结果。~~
- [x] ~~响应返回权限结果。~~
- [x] ~~复用 `GET /api/v1/agent-runs/{run_id}` 查看 Trace。~~
- [x] ~~Trace 接口返回语义解析、路由、工具调用、最终结果。~~
- [x] ~~`POST /api/v1/orchestrator/run` 返回的 `result` 已可携带 `review_payload`。~~
验收证据：
- [x] ~~前端或 curl 可以完整看到一次运行链路。~~
## 8. 前端最小 Trace 查看
- [ ] 在合适位置展示最近运行记录。
- [x] ~~点击当前对话结果可查看 `run_id`。~~
- [x] ~~展示 selected_agent。~~
- [x] ~~展示 route_reason。~~
- [x] ~~展示 permission_level。~~
- [ ] 展示工具调用列表。
- [x] ~~展示错误信息。~~
- [ ] 展示耗时。
- [ ] 展示报销写链路中的 claim_id / claim_no / status 变化。
验收证据：
- [x] ~~开发调试时不需要直接查数据库才能理解主要路由结果。~~
## 9. 测试
- [x] ~~测试用户查询路由到 User Agent。~~
- [x] ~~测试定时任务路由到 Hermes。~~
- [x] ~~测试叙述型报销输入可路由到报销建单服务。~~
- [x] ~~测试同一 `conversation_id` 下的追问会继续更新已有报销草稿。~~
- [ ] 测试报销单提交前必须显式确认。
- [x] ~~测试 forbidden 不调用下游 Agent。~~
- [x] ~~测试 approval_required 返回确认。~~
- [x] ~~测试工具失败写入 ToolCall。~~
- [x] ~~测试 Orchestrator 异常写入 AgentRun。~~
验收证据：
- [x] ~~Orchestrator 核心测试通过。~~
## 10. Day 4 验收
- [x] ~~Orchestrator API 可用。~~
- [x] ~~用户请求能路由到 User Agent 占位实现。~~
- [x] ~~定时任务能路由到 Hermes 占位实现。~~
- [x] ~~语义补槽完成后的报销输入能路由到建单动作。~~
- [x] ~~语义补槽完成后的报销输入能路由到改单动作。~~
- [x] ~~权限阻断有效。~~
- [x] ~~运行 Trace 可查询。~~
- [x] ~~工具调用日志可查询。~~
- [x] ~~降级结果可读。~~
- [x] ~~所有完成项已用 `[x] ~~...~~` 标记。~~
## 阻塞记录
- [x] ~~暂无。~~
## 日终交接
- [x] ~~当前路由规则已稳定为：`user_message -> user_agent`、`schedule -> hermes`、`clarification_required -> blocked`。~~
- [x] ~~当前权限判断已稳定为：`read / draft_write / approval_required / forbidden`，高风险动作默认阻断或要求确认。~~
- [x] ~~Day 5 需承接的接口契约已明确：Orchestrator 向 User Agent 传入语义结果、能力码、工具结果，并期待返回 `answer / citations / suggested_actions / draft_payload / risk_flags`。~~
- [x] ~~Day 5 当前已扩展接口契约：除 `answer / citations / suggested_actions / draft_payload / risk_flags` 外，还返回 `review_payload` 用于前端预审工作台。~~
- [x] ~~下一步仍需补齐的运行时写链路是：附件持久化、OCR 结果落库和提交状态流转。~~

284
document/development/agent/agent week plan/day_5_user_agent_mvp.md Normal file
View File

@@ -0,0 +1,284 @@
# Day 5：User Agent MVP
## 今天的大开发点
实现面向用户的自建 Agent。它负责用户提问、流程辅助、规则解释、查询结果解释和草稿生成。
User Agent 只能处理用户侧交互，不负责后台定时内循环，也不能自动执行高风险动作。
## 为什么第五天做这个
Day 1 到 Day 4 已经具备资产、语义、路由和日志基础，此时可以把用户自然语言入口接到真实流程上。
## 今天主要交付
- 用户自然语言入口。
- 对话入口透传首句文本、附件名称和页面上下文。
- 语义识别完整后创建报销单草稿。
- 对话补充字段时更新报销主表、明细和附件关联。
- 用户确认后触发报销单提交和状态变更。
- 报销查询和解释。
- 应收查询和解释。
- 应付查询和解释。
- 规则引用解释。
- 风险原因说明。
- 处理意见草稿。
- 知识库读取骨架。
- 低置信度场景的澄清追问。
- 前端问答或操作入口。
## 当前完成情况
- [x] ~~个人工作台、报销对话框和通用聊天入口已经接通真实 Orchestrator / User Agent 问答链路。~~
- [x] ~~回答、规则引用、风险说明、建议动作和结构化 `draft_payload` 已可返回。~~
- [x] ~~报销对话框已接入 OCR 识别接口，附件名称、OCR 摘要和页面上下文已能透传到 Orchestrator / User Agent。~~
- [x] ~~右侧工作台已开始展示结构化 `review_payload`，并已收敛为“识别结果专用区”：核心识别摘要、时间换算说明、逐票据识别结果、可能单据类型、建议归属费用和 OCR 置信度。~~
- [x] ~~个人工作台和报销对话框已接入 `conversation_id` / `draft_claim_id`，同一会话内的连续追问不再按全新请求处理。~~
- [x] ~~个人工作台已支持“继续会话 / 新建会话”，并可恢复最近一次用户会话或清空旧会话后重新开始。~~
- [x] ~~报销核对流已切到产品化交互：正文区负责 AI 式核对提示、待补充信息、风险提醒和底部动作区，右侧只承载识别结果与票据识别明细，动作固定为“取消 / 修改识别信息 / 保存草稿或下一步”。~~
- [ ] 真实 `document_assets` / `document_asset_versions` / `expense_item_documents` / `document_ocr_results` 落库，以及 `draft -> submitted` 状态流转尚未完成；`expense_claims` / `expense_claim_items` 草稿已接通真实落库。
相关架构文档：
- [Agent 职责边界](<../agent plan/03_agent_responsibilities.md>)
- [Orchestrator 与运行流程](<../agent plan/04_orchestrator_and_runtime_flow.md>)
- [LLM Wiki 知识库架构](<../agent plan/12_llm_wiki_knowledge_architecture.md>)
- [规则形成生命周期](<../agent plan/13_rule_formation_lifecycle.md>)
## 当天验收门槛
- 用户能输入自然语言问题。
- 请求必须经过 Orchestrator。
- 至少 3 类财务问题有可读回答。
- 叙述型报销输入在最小槽位满足后能创建 `expense_claims` 草稿。
- 用户确认提交后可把报销单从 `draft` 变更为 `submitted`。
- 回答能引用规则或知识。
- 语义低置信度时不会答非所问，而是追问。
- 高风险动作只生成草稿或建议。
- AgentRun Trace 能看到 User Agent 步骤。
## 今天不做
- 不做自动审批。
- 不做自动付款。
- 不做自动上线规则。
- 不做完整知识库检索优化。
- 不假装已读懂未解析的附件内容。
## 详细执行清单
以下内容为合并后的详细执行清单。
## 0. 开始前检查
- [x] ~~确认 Orchestrator 能把用户请求路由到 User Agent。~~
- [x] ~~确认语义本体 8 字段可用。~~
- [x] ~~确认语义层已接入真实模型，而不是仅靠关键词规则。~~
- [x] ~~确认规则资产可查询。~~
- [x] ~~确认 AgentRun 和 ToolCall 可记录。~~
- [x] ~~确认已有现成对话 UI 可复用。~~
- [x] ~~确认财务业务数据已可通过最小真实数据查询。~~
- [x] ~~当前无需额外补最小 Mock 数据服务。~~
## 1. User Agent 输入输出
- [x] ~~定义 `UserAgentRequest`。~~
- [x] ~~请求包含 `run_id`。~~
- [x] ~~请求包含 `user_id`。~~
- [x] ~~请求包含 `message`。~~
- [x] ~~请求包含 `ontology`。~~
- [x] ~~请求包含 `context_json`。~~
- [x] ~~定义 `UserAgentResponse`。~~
- [x] ~~响应包含 `answer`。~~
- [x] ~~响应包含 `citations`。~~
- [x] ~~响应包含 `suggested_actions`。~~
- [x] ~~响应包含 `draft_payload`。~~
- [x] ~~响应包含 `risk_flags`。~~
- [x] ~~响应包含 `requires_confirmation`。~~
验收证据：
- [x] ~~User Agent 响应结构能被 Orchestrator 直接包装返回。~~
## 2. 查询处理
- [x] ~~实现报销查询处理器。~~
- [x] ~~实现应收查询处理器。~~
- [x] ~~实现应付查询处理器。~~
- [ ] 查询前检查权限级别。
- [x] ~~查询时记录 ToolCall。~~
- [x] ~~查询失败时返回可读错误。~~
- [x] ~~查询为空时返回空态解释。~~
- [ ] 查询结果限制返回条数，避免一次返回过大。
验收证据：
- [x] ~~“查本周报销金额”有可读回答。~~
- [x] ~~“客户 A 本月应收多少”有可读回答。~~
- [x] ~~“供应商 B 待付款多少”有可读回答。~~
## 3. 规则解释
- [x] ~~根据语义场景查询相关规则资产。~~
- [x] ~~只引用 active 规则。~~
- [x] ~~读取规则当前版本 Markdown。~~
- [x] ~~从 Markdown 中提取规则摘要。~~
- [x] ~~回答中说明使用了哪些规则。~~
- [x] ~~回答中包含规则版本号。~~
- [x] ~~回答中包含规则更新时间。~~
- [x] ~~没有相关规则时说明缺失。~~
验收证据：
- [x] ~~“为什么这笔报销有风险”能引用规则。~~
## 4. 风险解释
- [x] ~~识别重复报销风险。~~
- [x] ~~识别金额超标风险。~~
- [x] ~~识别发票异常风险。~~
- [x] ~~识别逾期应收风险。~~
- [x] ~~识别逾期应付风险。~~
- [x] ~~风险回答包含风险类型。~~
- [x] ~~风险回答包含触发原因。~~
- [x] ~~风险回答包含建议处理动作。~~
- [x] ~~高风险建议不能变成自动执行。~~
验收证据：
- [x] ~~风险解释结果不是单纯“有风险”，而是有依据。~~
## 5. 草稿生成与单据落库
- [x] ~~支持根据语义结果创建 `expense_claims` 草稿。~~
- [x] ~~报销草稿初始状态写为 `draft`。~~
- [x] ~~支持根据语义结果创建或更新 `expense_claim_items`。~~
- [ ] 支持把用户上传附件挂到 `document_assets`、`document_asset_versions`、`expense_item_documents`。
- [ ] 支持把 OCR 识别快照写入 `document_ocr_results`，并保留 `ocr_engine`、`ocr_model`、`raw_json`、`confidence`。
- [x] ~~对话中补充金额、发生时间、费用类型等已落地字段后，能回写已有草稿而不是只更新内存结果。~~
- [x] ~~支持生成报销处理意见草稿。~~
- [x] ~~支持生成应收催收建议草稿。~~
- [x] ~~支持生成应付付款建议草稿。~~
- [ ] 用户明确确认“提交报销”后，把 `expense_claims.status` 从 `draft` 更新为 `submitted`。
- [ ] 报销提交时写入 `submitted_at`。
- [ ] 报销状态变更写入审计日志。
- [ ] 报销状态变更写入 AgentRun 结果。
- [x] ~~草稿中标明“待人工确认”。~~
- [x] ~~草稿不直接提交业务系统。~~
- [x] ~~草稿生成写入审计日志。~~
- [x] ~~草稿生成写入 AgentRun 结果。~~
- [ ] 草稿创建或更新后向前端返回 `attachment_ids`。
- [x] ~~草稿创建或更新后向前端返回 `claim_id`、`claim_no`、`status`。~~
验收证据：
- [ ] “我今天去客户现场，招待了客户，花销了1000元”在补齐必要字段后可创建报销草稿。
- [ ] “帮我提交这笔报销”在确认后只把状态改到 `submitted`，不会直接改成 `approved` 或 `paid`。
- [x] ~~“帮我生成处理意见”只返回草稿，不执行审批。~~
## 6. 知识库读取骨架
- [ ] 建立知识条目查询接口或服务。
- [ ] 支持按关键词查询知识条目。
- [ ] 支持按业务场景查询知识条目。
- [ ] User Agent 回答可以引用知识条目。
- [ ] 引用中包含知识标题。
- [ ] 引用中包含更新时间。
- [ ] 知识库不可用时返回降级说明。
验收证据：
- [ ] 知识库失败不会导致整个回答失败。
## 7. 对话或操作入口
- [x] ~~前端增加用户问题输入框。~~
- [x] ~~输入框支持回车或按钮提交。~~
- [x] ~~提交时调用 Orchestrator，而不是绕过 Orchestrator。~~
- [x] ~~提交时透传首句文本。~~
- [x] ~~提交时透传附件名称。~~
- [x] ~~提交时透传 OCR 摘要。~~
- [x] ~~提交时透传页面上下文。~~
- [x] ~~提交时透传 `conversation_id` 与 `draft_claim_id`。~~
- [ ] 提交时透传附件 ID。
- [x] ~~展示 Agent 回答。~~
- [x] ~~展示引用规则或知识。~~
- [x] ~~展示建议动作。~~
- [x] ~~展示识别意图摘要、待确认字段和确认动作卡片。~~
- [x] ~~正文区改为简洁核对提示，不再堆叠调度结果或运行明细。~~
- [x] ~~正文区待补充信息和风险提示已改为紧凑高亮样式，避免出现大段冗长说明。~~
- [x] ~~展示逐票据 OCR 识别结果，并支持按 1、2、3… 顺序查看。~~
- [x] ~~右侧逐票据结果已补充“可能单据类型 / 建议归属费用 / 识别置信度”等识别信息。~~
- [x] ~~展示多场景票据的分单建议。~~
- [ ] 展示报销草稿 ID 或 claim_no。
- [ ] 展示当前报销状态。
- [x] ~~展示需要人工确认的提示。~~
- [x] ~~展示 `run_id`。~~
- [x] ~~展示加载态。~~
- [x] ~~展示错误态。~~
验收证据：
- [x] ~~用户可在页面完成一次问答闭环。~~
## 8. 安全边界
- [x] ~~User Agent 不直接修改规则状态。~~
- [x] ~~User Agent 不直接上线规则。~~
- [x] ~~User Agent 不直接审批报销。~~
- [x] ~~User Agent 不直接把报销单改为 `approved` 或 `paid`。~~
- [x] ~~User Agent 不直接付款。~~
- [x] ~~User Agent 不直接删除知识。~~
- [x] ~~所有高风险动作只返回建议或草稿。~~
- [ ] 报销从 `draft` 变更到 `submitted` 之前必须有用户确认。
- [ ] 所有草稿动作标记 `requires_confirmation=true`。
- [x] ~~语义低置信度时优先追问，不返回答非所问的查询结果。~~
- [x] ~~没有 OCR/VLM 结果时，不假装读懂图片或票据内容。~~
验收证据：
- [x] ~~提示词要求“直接付款”时仍被阻断。~~
## 9. 测试
- [x] ~~测试报销查询。~~
- [x] ~~测试应收查询。~~
- [ ] 测试应付查询。
- [ ] 测试规则解释。
- [x] ~~测试风险解释。~~
- [ ] 测试 OCR 摘要透传后，User Agent 能在回答中正确引用附件语境而不编造内容。
- [x] ~~测试报销草稿创建。~~
- [x] ~~测试报销草稿补槽更新。~~
- [ ] 测试报销状态从 `draft` 变更到 `submitted`。
- [x] ~~测试草稿生成。~~
- [ ] 测试越权动作阻断。
- [ ] 测试知识库降级。
验收证据：
- [x] ~~User Agent 核心测试通过。~~
## 10. Day 5 验收
- [x] ~~User Agent 服务可被 Orchestrator 调用。~~
- [x] ~~用户入口可提交自然语言问题。~~
- [x] ~~至少 3 个财务场景有回答。~~
- [x] ~~语义识别完整后的报销输入能创建报销草稿。~~
- [ ] 用户确认后能提交报销并更新状态。
- [x] ~~回答能引用规则或知识。~~
- [x] ~~高风险动作不会自动执行。~~
- [x] ~~AgentRun Trace 能看到 User Agent 步骤。~~
- [x] ~~前端构建通过。~~
- [x] ~~所有完成项已用 `[x] ~~...~~` 标记。~~
## 阻塞记录
- [x] ~~暂无。~~
## 日终交接
- [x] ~~当前已支持报销 / 应收 / 应付查询、规则解释、风险解释、草稿建议与澄清追问。~~
- [x] ~~当前已支持附件名称、OCR 摘要和页面上下文进入对话链路，但这还不是附件真实持久化。~~
- [x] ~~当前已把用户一句话和多票据输入转成结构化预审面板，开始支持字段确认、票据核对和分单建议，而不再只是返回一段文本。~~
- [x] ~~当前仍是占位的主要能力是报销单真实落库、附件持久化、OCR 结果入表和知识库读取，不再是简单静态问答 Mock。~~
- [x] ~~Day 6 Hermes 可直接复用当前的规则检查、风险标签和 Orchestrator Trace / ToolCall 契约。~~

314
document/development/agent/agent week plan/day_6_hermes_mvp.md Normal file
View File

@@ -0,0 +1,314 @@
# Day 6：Hermes MVP
## 今天的大开发点
实现 Hermes 数字员工的最小闭环。Hermes 负责后台内循环：定时巡检、统计日报、风险预警、知识维护、规则草稿形成。
## 为什么第六天做这个
Hermes 依赖前几天已经建立的资产、规则、语义、Orchestrator、Trace 和权限体系。放在第六天做，可以避免它变成孤立脚本。
## 今天主要交付
- 任务资产调度入口。
- 手动触发任务 API。
- 系统 Hermes 后台执行入口。
- 每日风险巡检。
- 每日报销、报账、账款统计。
- OCR Mock 接入点。
- 知识候选条目生成。
- 规则草稿生成。
- LLM Wiki 解析目录与增量重建机制。
- Hermes 运行结果展示。
相关架构文档：
- [Agent 职责边界](<../agent plan/03_agent_responsibilities.md>)
- [OCR 票据识别架构](<../agent plan/11_ocr_invoice_architecture.md>)
- [LLM Wiki 知识库架构](<../agent plan/12_llm_wiki_knowledge_architecture.md>)
- [反馈学习闭环](<../agent plan/15_feedback_learning_loop.md>)
## 当天验收门槛
- 至少一个 Hermes 任务可以手动触发。
- 风险巡检有结构化结果。
- 每日统计有结构化结果。
- OCR Mock 调用能记录 ToolCall。
- 知识候选只能是草稿。
- 规则草稿只能是 draft，不能自动上线。
## 今天不做
- 不做完整生产调度集群。
- 不做真实 OCR 深度集成。
- 不做自动发布知识。
- 不做自动上线规则。
- 不做每天无差别全量重建 LLM Wiki。
## 本次新增约束
### 1. Hermes 必须是系统后台 Hermes
这次 Hermes 不应继续只是代码里的占位逻辑。
最小可接受形态：
- 后端任务入口能明确区分 `selected_agent=hermes`。
- 后端可调用系统安装的 Hermes CLI 或受控 Hermes 进程。
- 即使当前阶段仍允许 Python 内部 fallback，也必须保留真实 Hermes 进程接入点。
- Hermes 的模型配置继续由系统设置同步，不允许在任务代码里再写一套模型配置。
- Hermes 执行应记录 `run_id`、ToolCall、错误信息和最终摘要。
### 2. LLM Wiki 必须有独立解析目录
原始知识文件与解析产物必须分离。
推荐目录：
```text
/app/server/storage/knowledge/报销制度 原始制度文件
/app/server/storage/knowledge/.llm_wiki 解析产物根目录
/app/server/storage/knowledge/.llm_wiki/documents/<document_id>/
document.json
text.md
chunks.json
clauses.json
knowledge_candidates.json
rule_candidates.json
/app/server/storage/knowledge/.llm_wiki/index.json
/app/server/storage/knowledge/.llm_wiki/sync_runs.json
```
### 3. LLM Wiki 只能增量形成
不允许每天无脑全量重建。
文档级重建触发条件至少包括：
- 文件名 `original_name` 变更。
- 文件对象 `stored_name` 变更。
- 内容摘要 `sha256` 变更。
- 上传版本 `version_number` 变更。
- 更新时间 `updated_at` 变更，视为人工改动。
如果以上条件都未变化：
- 本次文档应标记为 `unchanged_skipped`。
- 不重新抽取文本。
- 不重新生成知识候选。
- 不重新生成规则草稿。
### 4. 规则草稿必须模板化
Hermes 不允许自由生成任意结构的规则。
必须满足：
- 规则 Markdown 使用固定模板。
- 可执行规则 JSON 使用固定模板族，不允许随意拼字段。
- 规则中心要同时展示人类可读的 Markdown 和机器可执行的 JSON。
- Hermes 生成的规则默认 `draft`。
- 审核通过前不能 `active`。
- Hermes 不能直接覆盖线上 active 规则。
## 详细执行清单
以下内容为合并后的详细执行清单。
## 0. 开始前检查
- [x] ~~确认任务资产 `asset_type=task` 可查询。~~
- [x] ~~确认 Orchestrator 能处理 `source=schedule`。~~
- [x] ~~确认系统 Hermes CLI 或等价后台 Hermes 进程可被调用。~~
- [x] ~~确认 AgentRun 和 ToolCall 可记录。~~
- [ ] 确认是否已有后台任务框架。
- [ ] 如果没有后台任务框架，先用手动触发 API 模拟定时执行。
## 1. Hermes 输入输出
- [ ] 定义 `HermesTaskRequest`。
- [ ] 请求包含 `run_id`。
- [ ] 请求包含 `task_asset_id`。
- [ ] 请求包含 `task_type`。
- [ ] 请求包含 `schedule_time`。
- [ ] 请求包含 `context_json`。
- [ ] 定义 `HermesTaskResult`。
- [ ] 响应包含 `summary`。
- [ ] 响应包含 `risk_items`。
- [ ] 响应包含 `statistics`。
- [ ] 响应包含 `knowledge_updates`。
- [ ] 响应包含 `draft_rules`。
- [ ] 响应包含 `next_actions`。
验收证据：
- [ ] Hermes 响应能被任务详情或运行日志展示。
## 2. 任务调度入口
- [x] ~~新增手动触发任务 API。~~
- [x] ~~API 参数支持任务资产 ID。~~
- [x] ~~API 调用 Orchestrator，source 为 `schedule`。~~
- [x] ~~Orchestrator 路由到 Hermes。~~
- [x] ~~Hermes 执行结果写入 AgentRun。~~
- [ ] 任务执行失败时写入错误。
- [ ] 任务执行结束后更新任务最近执行时间。
- [ ] 任务执行结束后更新任务最近执行状态。
- [x] ~~保留真实 Hermes 进程执行入口，不把 Hermes 固定写死为本地占位函数。~~
验收证据：
- [x] ~~可以手动触发一次 Hermes 任务并看到运行结果。~~
## 3. 每日风险巡检
- [ ] 实现重复报销巡检。
- [ ] 实现金额超标巡检。
- [ ] 实现发票异常巡检占位。
- [ ] 实现应收逾期巡检。
- [ ] 实现应付异常付款巡检。
- [ ] 每个风险项包含风险类型。
- [ ] 每个风险项包含业务对象。
- [ ] 每个风险项包含触发规则。
- [ ] 每个风险项包含建议动作。
- [ ] 每个风险项包含风险等级。
验收证据：
- [ ] 风险巡检结果可以被用户理解和追溯。
## 4. 每日统计
- [ ] 统计当日报销单数量。
- [ ] 统计当日报销金额。
- [ ] 统计当日报账数量。
- [ ] 统计当日报账金额。
- [ ] 统计应收新增金额。
- [ ] 统计应收逾期金额。
- [ ] 统计应付待付金额。
- [ ] 统计应付逾期金额。
- [ ] 输出日报摘要。
验收证据：
- [ ] Hermes 能生成一份每日财务摘要。
## 5. OCR 接入点
- [ ] 原始票据先落 `document_assets` 和 `document_asset_versions`，不直接以内存临时文件参与流程。
- [ ] 建立 OCR 识别服务接口。
- [ ] 定义发票识别输入结构。
- [ ] 定义发票识别输出结构。
- [ ] 输出结构包含发票号。
- [ ] 输出结构包含开票日期。
- [ ] 输出结构包含金额。
- [ ] 输出结构包含税额。
- [ ] 输出结构包含销售方。
- [ ] 输出结构包含购买方。
- [ ] 输出结构包含置信度。
- [ ] OCR 输入可通过 `storage_key` 或等价文件定位字段读取原件。
- [ ] 当前阶段允许使用 Mock 结果。
- [ ] OCR 调用写入 ToolCall。
验收证据：
- [ ] Hermes 风险巡检中可以调用 OCR Mock。
## 6. 知识库维护
- [ ] 建立知识条目写入服务。
- [x] ~~建立 `.llm_wiki` 独立解析目录。~~
- [x] ~~原始文档与解析产物物理隔离。~~
- [x] ~~文本抽取结果落 `text.md`。~~
- [x] ~~分块结果落 `chunks.json`。~~
- [x] ~~文档索引落 `index.json`。~~
- [x] ~~同步记录落 `sync_runs.json`。~~
- [x] ~~文档签名包含 `original_name`、`stored_name`、`sha256`、`version_number`、`updated_at`。~~
- [x] ~~未变化文档跳过重建并记录 `unchanged_skipped`。~~
- [x] ~~Hermes 可以生成知识候选条目。~~
- [x] ~~候选条目包含标题。~~
- [x] ~~候选条目包含正文。~~
- [x] ~~候选条目包含来源。~~
- [x] ~~候选条目包含适用场景。~~
- [x] ~~候选条目默认状态为 `draft`。~~
- [x] ~~知识条目不能自动发布。~~
- [ ] 知识条目写入审计日志。
验收证据：
- [x] ~~Hermes 可以生成待审核知识条目。~~
## 7. 规则草稿形成
- [ ] Hermes 可以根据风险巡检结果生成规则草稿。
- [x] ~~规则草稿使用固定 Markdown 模板。~~
- [x] ~~规则草稿生成可执行 JSON 草稿。~~
- [x] ~~规则中心展示 Markdown + JSON 双视图。~~
- [x] ~~JSON 草稿字段受模板约束，不允许自由扩展。~~
- [x] ~~规则草稿保存为 `asset_type=rule`。~~
- [x] ~~规则草稿状态为 `draft`。~~
- [x] ~~规则草稿包含 Markdown 内容。~~
- [x] ~~规则草稿包含 JSON 内容或等价 `runtime_rule` 配置。~~
- [ ] 规则草稿包含生成原因。
- [ ] 规则草稿包含关联风险样例。
- [x] ~~规则草稿不能自动上线。~~
- [x] ~~规则草稿需要审核人。~~
- [x] ~~规则草稿写入审计日志。~~
- [x] ~~Hermes 不直接覆盖线上 active 规则。~~
验收证据：
- [x] ~~Hermes 生成的新规则出现在规则列表中，但不是 active。~~
## 8. Hermes 页面或日志展示
- [x] ~~任务详情能看到最近执行结果。~~
- [ ] 任务详情能手动触发执行。
- [ ] 任务详情能看到风险项数量。
- [ ] 任务详情能看到日报摘要。
- [ ] 任务详情能看到知识候选数量。
- [ ] 任务详情能看到规则草稿数量。
- [ ] 运行 Trace 能看到 Hermes 步骤。
- [x] ~~错误时展示错误原因。~~
验收证据：
- [x] ~~不查数据库也能判断 Hermes 是否执行成功。~~
## 9. 测试
- [x] ~~测试手动触发任务。~~
- [x] ~~测试 Orchestrator 路由到 Hermes。~~
- [ ] 测试风险巡检输出。
- [ ] 测试日报统计输出。
- [ ] 测试 OCR Mock 调用。
- [x] ~~测试知识候选写入。~~
- [x] ~~测试规则草稿生成。~~
- [ ] 测试 Hermes 异常写入 AgentRun。
验收证据：
- [ ] Hermes 核心测试通过。
## 10. Day 6 验收
- [x] ~~Hermes 可被 Orchestrator 调用。~~
- [x] ~~至少一个任务可以手动触发。~~
- [ ] 风险巡检有结构化结果。
- [ ] 每日统计有结构化结果。
- [ ] OCR Mock 接入点可用。
- [x] ~~知识候选可生成。~~
- [x] ~~规则草稿可生成且不能自动上线。~~
- [x] ~~任务详情或运行日志能展示结果。~~
- [x] ~~所有完成项已用 `[x] ~~...~~` 标记。~~
## 阻塞记录
- [ ] 暂无。
## 日终交接
- [ ] 写明 Hermes 已支持任务类型。
- [ ] 写明 OCR 当前是真实还是 Mock。
- [ ] 写明生成的知识和规则草稿状态。
- [ ] 写明 Day 7 需要重点回归的路径。

260
document/development/agent/agent week plan/day_7_hardening_demo_acceptance.md Normal file
View File

@@ -0,0 +1,260 @@
# Day 7：加固、演示和验收
## 今天的大开发点
不再大规模扩功能，集中做回归、加固、测试、演示脚本、文档收尾和下一阶段交接。
## 为什么第七天做这个
一周开发不能只停留在“代码写了”。必须能演示、能追溯、能说清楚边界、能交给下一阶段继续开发。
## 今天主要交付
- 核心链路回归。
- 权限和风险边界复查。
- 审计日志补齐。
- AgentRun Trace 补齐。
- 前端体验修补。
- 测试和构建记录。
- 评测集执行记录。
- 演示数据准备。
- 演示脚本。
- 下一阶段开发建议。
相关架构文档：
- [Agent Plan 总览](<../agent plan/00_README.md>)
- [开发路线图](<../agent plan/05_development_roadmap.md>)
- [观测与 Trace](<../agent plan/09_observability_and_trace.md>)
- [评测与测试集](<../agent plan/10_evaluation_and_testset.md>)
## 当天验收门槛
- 任务规则中心核心路径可演示。
- 语义本体、Orchestrator、User Agent、Hermes 都能跑通最小链路。
- 未审核规则、高风险动作、自动付款等边界都被拦截。
- AgentRun、ToolCall、AuditLog 可追溯。
- 有测试记录、演示脚本和交接说明。
## 今天不做
- 不做新大功能。
- 不临时扩大范围。
- 不绕过测试和验收。
## 详细执行清单
以下内容为合并后的详细执行清单。
## 0. 开始前检查
- [ ] 汇总 Day 1 未完成项。
- [ ] 汇总 Day 2 未完成项。
- [ ] 汇总 Day 3 未完成项。
- [ ] 汇总 Day 4 未完成项。
- [ ] 汇总 Day 5 未完成项。
- [ ] 汇总 Day 6 未完成项。
- [ ] 标记必须今天修复的问题。
- [ ] 标记可以进入下一阶段的问题。
- [ ] 冻结新增需求，只处理验收相关问题。
## 1. 核心链路回归
- [ ] 回归资产列表接口。
- [ ] 回归规则详情接口。
- [ ] 回归 Markdown 保存。
- [ ] 回归版本列表。
- [ ] 回归版本切换。
- [ ] 回归审核接口。
- [ ] 回归上线拦截。
- [ ] 回归语义解析接口。
- [ ] 回归 Orchestrator 路由。
- [ ] 回归 User Agent 问答。
- [ ] 回归 Hermes 任务执行。
- [ ] 回归 AgentRun Trace。
- [ ] 回归 ToolCall 日志。
- [ ] 回归 AuditLog 日志。
验收证据：
- [ ] 从前端能完成至少一条端到端演示路径。
## 2. 权限和风险边界
- [ ] 未审核规则不能上线。
- [ ] rejected 规则不能上线。
- [ ] disabled 能力不能被调用。
- [ ] 用户请求付款必须拦截。
- [ ] 用户请求审批必须需要确认。
- [ ] Hermes 生成规则只能是 draft。
- [ ] Hermes 生成知识只能是 draft。
- [ ] User Agent 生成处理意见只能是草稿。
- [ ] 所有高风险动作响应中包含 `requires_confirmation`。
验收证据：
- [ ] 不存在 MVP 期间绕过人工审核的路径。
## 3. 审计和 Trace 补齐
- [ ] 规则保存写 AuditLog。
- [ ] 规则审核写 AuditLog。
- [ ] 规则上线写 AuditLog。
- [ ] Hermes 生成规则草稿写 AuditLog。
- [ ] Hermes 生成知识候选写 AuditLog。
- [ ] User Agent 草稿生成写 AuditLog。
- [ ] Orchestrator 每次运行有 AgentRun。
- [ ] 每次工具调用有 ToolCall。
- [ ] Trace 页面或接口能串起 run_id。
- [ ] 错误 Trace 包含 error_message。
验收证据：
- [ ] 任意一条演示链路都能追溯到 run_id。
## 4. 前端体验修补
- [ ] 任务规则中心列表无明显错位。
- [ ] 详情页无双 title。
- [ ] Hero title 高度紧凑。
- [ ] 返回列表栏高度正常。
- [ ] Markdown 编辑器和版本卡片底部对齐。
- [ ] 版本卡片不贴右侧。
- [ ] 当前版本标识不突兀。
- [ ] 日期列对齐。
- [ ] 弹窗文案清楚。
- [ ] 加载态可见。
- [ ] 错误态可见。
- [ ] 空态可见。
- [ ] 按钮禁用态可见。
- [ ] 窄屏不出现内容重叠。
验收证据：
- [ ] 任务规则中心可以给业务用户演示，不需要解释 UI 异常。
## 5. 测试补齐
- [ ] 运行后端现有测试。
- [ ] 运行新增模型测试。
- [ ] 运行新增 API 测试。
- [ ] 运行语义解析测试。
- [ ] 运行 Orchestrator 测试。
- [ ] 运行 User Agent 测试。
- [ ] 运行 Hermes 测试。
- [ ] 运行前端构建。
- [ ] 如果有前端测试，运行前端测试。
- [ ] 记录未能运行的测试和原因。
验收证据：
- [ ] 测试结果写入本文件“测试记录”。
## 6. 评测集
- [ ] 准备 5 条报销问题。
- [ ] 准备 5 条应收问题。
- [ ] 准备 5 条应付问题。
- [ ] 准备 3 条规则解释问题。
- [ ] 准备 3 条越权动作问题。
- [ ] 执行语义解析评测。
- [ ] 执行 User Agent 回答评测。
- [ ] 执行权限拦截评测。
- [ ] 记录失败样例。
- [ ] 为失败样例写下一阶段优化建议。
验收证据：
- [ ] 可以说明 MVP 当前能力边界和准确率风险。
## 7. 演示数据
- [ ] 准备 active 规则。
- [ ] 准备 pending 规则。
- [ ] 准备 rejected 规则。
- [ ] 准备至少一条报销数据。
- [ ] 准备至少一条应收数据。
- [ ] 准备至少一条应付数据。
- [ ] 准备至少一个 Hermes 任务。
- [ ] 准备至少一个 MCP Mock。
- [ ] 准备至少一个知识条目。
- [ ] 准备至少一个风险样例。
验收证据：
- [ ] 演示不会因为没有数据而中断。
## 8. 演示脚本
- [ ] 编写演示步骤 1：打开任务规则中心。
- [ ] 编写演示步骤 2：查看规则详情。
- [ ] 编写演示步骤 3：编辑 Markdown 并保存。
- [ ] 编写演示步骤 4：切换版本。
- [ ] 编写演示步骤 5：尝试上线未审核规则并被拦截。
- [ ] 编写演示步骤 6：输入用户问题。
- [ ] 编写演示步骤 7：查看语义本体结果。
- [ ] 编写演示步骤 8：查看 User Agent 回答。
- [ ] 编写演示步骤 9：手动触发 Hermes 任务。
- [ ] 编写演示步骤 10：查看 AgentRun Trace。
- [ ] 编写演示步骤 11：查看审计日志。
验收证据：
- [ ] 新开发者按脚本可以复现演示。
## 9. 文档收尾
- [ ] 更新一周计划完成情况。
- [ ] 更新剩余风险。
- [ ] 更新下一阶段开发建议。
- [ ] 更新接口清单。
- [ ] 更新数据模型清单。
- [ ] 更新前端页面清单。
- [ ] 更新评测结果。
- [ ] 更新演示脚本。
- [ ] 更新部署或启动说明。
验收证据：
- [ ] 文档能指导下一周继续开发。
## 10. 最终验收清单
- [ ] 任务规则中心可查看规则、技能、MCP、任务。
- [ ] 规则详情可编辑 Markdown。
- [ ] 规则详情可查看最近 5 个版本。
- [ ] 版本切换有确认弹窗。
- [ ] 审核者信息可见。
- [ ] 未审核规则不能上线。
- [ ] 语义本体 8 字段可返回。
- [ ] Orchestrator 能路由用户请求。
- [ ] Orchestrator 能路由定时任务。
- [ ] User Agent 能回答至少 3 类财务问题。
- [ ] Hermes 能执行至少 1 个任务。
- [ ] OCR Mock 接入点可用。
- [ ] 知识候选可生成。
- [ ] 规则草稿可生成。
- [ ] AgentRun Trace 可查。
- [ ] AuditLog 可查。
- [ ] 前端构建通过。
- [ ] 后端核心测试通过。
- [ ] 演示脚本可执行。
- [ ] 所有完成项已用 `[x] ~~...~~` 标记。
## 测试记录
- [ ] 后端测试：未运行。
- [ ] 前端构建：未运行。
- [ ] 语义评测：未运行。
- [ ] 手动验收：未运行。
## 阻塞记录
- [ ] 暂无。
## 日终交接
- [ ] 写明本周最终完成内容。
- [ ] 写明未完成内容。
- [ ] 写明生产化前必须补齐内容。
- [ ] 写明下一周建议优先级。

137
document/development/agent/agent_week_plan_html/day-1.html Normal file
View File

@@ -0,0 +1,137 @@
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Day 1 - 基础模型与工程骨架</title>
<link rel="stylesheet" href="./styles.css">
</head>
<body>
<div class="shell">
<div class="topbar">
<a class="brand" href="./index.html"><span class="brand-mark">D1</span><span>Day 1 View</span></a>
<div class="quick-links">
<a class="pill" href="./index.html">返回总览</a>
<a class="pill" href="../agent%20week%20plan/day_1_foundation_models.md">周计划原文</a>
<a class="pill" href="../agent%20week%20plan/day_1_foundation_models.md">合并文档原文</a>
</div>
</div>
<div class="day-nav">
<a class="pill active" href="./day-1.html">Day 1</a>
<a class="pill" href="./day-2.html">Day 2</a>
<a class="pill" href="./day-3.html">Day 3</a>
<a class="pill" href="./day-4.html">Day 4</a>
<a class="pill" href="./day-5.html">Day 5</a>
<a class="pill" href="./day-6.html">Day 6</a>
<a class="pill" href="./day-7.html">Day 7</a>
</div>
<section class="hero">
<div class="hero-badge">Foundation Completed</div>
<h1>Day 1 基础模型与工程骨架</h1>
<p>这一天的任务不是做炫目的业务能力，而是把后面 6 天要反复依赖的模型、版本、审核、run trace、审计日志和最小业务数据源一次定稳。Day 1 做虚了，Day 4 到 Day 6 会全部返工。</p>
<div class="hero-meta">
<div class="meta-card"><div class="meta-label">当前状态</div><div class="meta-value">已完成（2026-05-11），可直接进入 Day 2 联调。</div></div>
<div class="meta-card"><div class="meta-label">上游依赖</div><div class="meta-value">无，Day 1 是全周底座。</div></div>
<div class="meta-card"><div class="meta-label">下游交接</div><div class="meta-value">Day 2 资产 API，Day 3 解析日志，Day 4 run trace，Day 5/6 业务数据查询。</div></div>
<div class="meta-card"><div class="meta-label">当天关键</div><div class="meta-value">先确定统一模型，再接 API 骨架和种子数据。</div></div>
</div>
</section>
<div class="section-kicker">Three-Layer Mapping</div>
<h2 class="section-title">三层文档映射</h2>
<div class="grid three">
<section class="card tone-warm">
<h3>路线图</h3>
<p>周计划里定义这一天要完成“工程地基”，强调只做稳定模型、API 骨架、种子数据、基础审计和可运行验证。</p>
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_1_foundation_models.md">day_1_foundation_models.md</a></div>
</section>
<section class="card tone-teal">
<h3>执行细则</h3>
<p>执行层把 Day 1 拆成命名边界、最小财务业务数据模型、Agent 资产模型、版本、审核、Run、ToolCall、SemanticParseLog、AuditLog、Schema、API、服务层。</p>
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_1_foundation_models.md">agent week plan/day_1</a></div>
</section>
<section class="card tone-olive">
<h3>架构依据</h3>
<p>主要受总体架构、语义本体、数据契约、能力注册、权限确认、可观测性和财务标准模型约束。</p>
<div class="card-links">
<a class="link-chip" href="../agent%20plan/01_overall_architecture.md">01</a>
<a class="link-chip" href="../agent%20plan/02_semantic_ontology.md">02</a>
<a class="link-chip" href="../agent%20plan/06_data_contracts_and_governance.md">06</a>
<a class="link-chip" href="../agent%20plan/07_capability_registry.md">07</a>
<a class="link-chip" href="../agent%20plan/08_permission_confirmation.md">08</a>
<a class="link-chip" href="../agent%20plan/09_observability_and_trace.md">09</a>
<a class="link-chip" href="../agent%20plan/14_financial_document_canonical_model.md">14</a>
</div>
</section>
</div>
<div class="section-kicker">Build Order</div>
<h2 class="section-title">推荐开发顺序</h2>
<div class="timeline">
<div class="timeline-step"><strong>Step 1</strong>先确认后端目录、ORM、迁移方式、测试目录和不该碰的文件。</div>
<div class="timeline-step"><strong>Step 2</strong>统一命名：资产类型、状态、审核状态、Agent、权限级别。</div>
<div class="timeline-step"><strong>Step 3</strong>补最小财务业务数据模型：<code>expense_claims</code>、<code>accounts_receivable</code>、<code>accounts_payable</code>。</div>
<div class="timeline-step"><strong>Step 4</strong>完成 AgentAsset、Version、Review、Run、ToolCall、ParseLog、AuditLog。</div>
<div class="timeline-step"><strong>Step 5</strong>把 Schema、API 骨架、服务层、种子数据接起来。</div>
</div>
<div class="section-kicker">Must Deliver</div>
<h2 class="section-title">今天必须产出的东西</h2>
<div class="grid two">
<section class="card">
<h3>平台底座表</h3>
<ul class="list">
<li><code>AgentAsset</code>、<code>AgentAssetVersion</code>、<code>AgentAssetReview</code></li>
<li><code>AgentRun</code>、<code>AgentToolCall</code>、<code>SemanticParseLog</code></li>
<li><code>AuditLog</code></li>
</ul>
</section>
<section class="card">
<h3>最小业务数据来源</h3>
<ul class="list">
<li>报销至少有时间、地点、理由、金额、员工、部门、状态。</li>
<li>应收至少有客户、金额、未收金额、到期日、账龄、状态。</li>
<li>应付至少有供应商、金额、未付金额、到期日、账龄、状态。</li>
</ul>
</section>
<section class="card">
<h3>API 骨架</h3>
<ul class="list">
<li>资产列表 / 详情 / 版本 / 审核 / 上线。</li>
<li>运行日志与审计日志查询。</li>
<li>返回真实数据库结果，不用前端硬编码收尾。</li>
</ul>
</section>
<section class="card">
<h3>统一服务边界</h3>
<ul class="list">
<li>上线拦截逻辑在服务层，不堆到路由。</li>
<li>所有写操作要留审计接口。</li>
<li>任何 Agent 执行记录都必须生成 <code>run_id</code>。</li>
</ul>
</section>
</div>
<div class="section-kicker">Acceptance Snapshot</div>
<h2 class="section-title">验收快照</h2>
<div class="table-like">
<div class="row"><div class="row-label">资产模型</div><div class="row-value">已落地 3 条规则、2 条技能、2 条 MCP、3 条任务，并可通过资产接口返回。</div></div>
<div class="row"><div class="row-label">版本与审核</div><div class="row-value">三条规则都具备版本历史；同一资产版本号不可重复，未审核规则不能上线。</div></div>
<div class="row"><div class="row-label">运行与错误</div><div class="row-value">`GET /api/v1/agent-runs` 可返回 3 条运行日志，任意新建 Run 自动生成 <code>run_id</code>。</div></div>
<div class="row"><div class="row-label">最小业务表</div><div class="row-value">报销、应收、应付种子数据已就位，后续查询和风险巡检都有明确数据来源。</div></div>
</div>
<div class="section-kicker">Common Misses</div>
<h2 class="section-title">这一天最容易漏掉的点</h2>
<ul class="list">
<li>只建 Agent 表，不建最小财务业务表，导致 User Agent 和 Hermes 后面无数据可查。</li>
<li>把审核拦截塞在 API 路由里，后面很难复用到 Orchestrator 和别的入口。</li>
<li>没有统一 <code>run_id</code> 和审计接口，Day 4 到 Day 7 的 Trace 会断链。</li>
</ul>
<div class="footer">Day 1 的判断标准很简单：不是“代码写了多少”，而是“后面 6 天会不会反复回头补地基”。</div>
</div>
</body>
</html>

132
document/development/agent/agent_week_plan_html/day-2.html Normal file
View File

@@ -0,0 +1,132 @@
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Day 2 - 任务规则中心联调</title>
<link rel="stylesheet" href="./styles.css">
</head>
<body>
<div class="shell">
<div class="topbar">
<a class="brand" href="./index.html"><span class="brand-mark">D2</span><span>Day 2 View</span></a>
<div class="quick-links">
<a class="pill" href="./index.html">返回总览</a>
<a class="pill" href="../agent%20week%20plan/day_2_rule_center_integration.md">周计划原文</a>
<a class="pill" href="../agent%20week%20plan/day_2_rule_center_integration.md">合并文档原文</a>
</div>
</div>
<div class="day-nav">
<a class="pill" href="./day-1.html">Day 1</a>
<a class="pill active" href="./day-2.html">Day 2</a>
<a class="pill" href="./day-3.html">Day 3</a>
<a class="pill" href="./day-4.html">Day 4</a>
<a class="pill" href="./day-5.html">Day 5</a>
<a class="pill" href="./day-6.html">Day 6</a>
<a class="pill" href="./day-7.html">Day 7</a>
</div>
<section class="hero">
<div class="hero-badge">Integration</div>
<h1>Day 2 任务规则中心联调</h1>
<p>Day 2 的核心不是“把页面做漂亮”，而是让规则、技能、MCP、任务这四类资产第一次脱离本地假数据，真正连到 Day 1 的数据库和 API。最关键的能力是 Markdown、版本、审核和上线约束闭环。</p>
<div class="hero-meta">
<div class="meta-card"><div class="meta-label">上游依赖</div><div class="meta-value">Day 1 的资产模型、版本模型、审核模型、资产 API。</div></div>
<div class="meta-card"><div class="meta-label">下游交接</div><div class="meta-value">Day 3 要复用资产数据，Day 4 要查询 active 技能 / MCP / 任务。</div></div>
<div class="meta-card"><div class="meta-label">当天关键</div><div class="meta-value">前端联调不是硬编码演示，而是可对接真实后端。</div></div>
</div>
</section>
<div class="section-kicker">Three-Layer Mapping</div>
<h2 class="section-title">三层文档映射</h2>
<div class="grid three">
<section class="card tone-warm">
<h3>路线图</h3>
<p>周计划要求把任务规则中心从静态 UI 升级到真实数据对接，覆盖规则、技能、MCP、任务四类资产。</p>
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_2_rule_center_integration.md">day_2_rule_center_integration.md</a></div>
</section>
<section class="card tone-teal">
<h3>执行细则</h3>
<p>执行层拆成 API Client、四类列表、规则详情、Markdown 编辑、版本卡片、审核与上线、技能详情、MCP 详情、任务详情、前端质量和当天验收。</p>
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_2_rule_center_integration.md">agent week plan/day_2</a></div>
</section>
<section class="card tone-olive">
<h3>架构依据</h3>
<p>这一天主要受能力注册、规则形成生命周期和数据治理约束，重点在四类资产的统一展示方式和规则上线前审核拦截。</p>
<div class="card-links">
<a class="link-chip" href="../agent%20plan/07_capability_registry.md">07</a>
<a class="link-chip" href="../agent%20plan/13_rule_formation_lifecycle.md">13</a>
<a class="link-chip" href="../agent%20plan/06_data_contracts_and_governance.md">06</a>
</div>
</section>
</div>
<div class="section-kicker">Build Order</div>
<h2 class="section-title">推荐开发顺序</h2>
<div class="timeline">
<div class="timeline-step"><strong>Step 1</strong>先补 API Client：列表、详情、版本、保存、审核、上线、运行日志。</div>
<div class="timeline-step"><strong>Step 2</strong>把四个页签的真实数据接起来，覆盖筛选、搜索、状态、空态和加载态。</div>
<div class="timeline-step"><strong>Step 3</strong>把规则详情的 Hero 区、Markdown 编辑器、版本卡片和审核信息拉通。</div>
<div class="timeline-step"><strong>Step 4</strong>补技能 / MCP / 任务的差异化详情，不复用规则编辑器。</div>
<div class="timeline-step"><strong>Step 5</strong>最后收 UI 细节、错误态、禁用态、确认弹窗和构建验证。</div>
</div>
<div class="section-kicker">Must Deliver</div>
<h2 class="section-title">今天必须产出的东西</h2>
<div class="grid two">
<section class="card">
<h3>规则中心四页签</h3>
<ul class="list">
<li>规则、技能、MCP、任务都能切换。</li>
<li>每个页签都来自真实接口，不再只读本地常量。</li>
<li>搜索和状态筛选同时生效。</li>
</ul>
</section>
<section class="card">
<h3>规则详情闭环</h3>
<ul class="list">
<li>能读取当前 Markdown。</li>
<li>能保存并刷新版本列表。</li>
<li>能展示审核者、审核状态、上线条件。</li>
</ul>
</section>
<section class="card">
<h3>版本与上线约束</h3>
<ul class="list">
<li>最近 5 个版本可见。</li>
<li>切换旧版本必须弹确认框。</li>
<li>未审核规则不能上线，拒绝原因要可见。</li>
</ul>
</section>
<section class="card">
<h3>详情差异化</h3>
<ul class="list">
<li>技能详情展示输入输出与依赖。</li>
<li>MCP 详情展示服务地址、鉴权、降级策略。</li>
<li>任务详情展示 cron、执行 Agent、最近执行结果。</li>
</ul>
</section>
</div>
<div class="section-kicker">Acceptance Snapshot</div>
<h2 class="section-title">验收快照</h2>
<div class="table-like">
<div class="row"><div class="row-label">真实数据</div><div class="row-value">四个页签都能用真实后端数据渲染，后端不可用时有明确错误提示。</div></div>
<div class="row"><div class="row-label">规则编辑</div><div class="row-value">Markdown 保存后刷新页面仍在，保存失败不丢输入。</div></div>
<div class="row"><div class="row-label">版本卡片</div><div class="row-value">最近 5 个版本可切换，当前版本标识清楚但不造成布局位移。</div></div>
<div class="row"><div class="row-label">审核上线</div><div class="row-value"><code>pending</code> / <code>rejected</code> 规则都无法上线，<code>approved</code> 才能放行。</div></div>
</div>
<div class="section-kicker">Common Misses</div>
<h2 class="section-title">这一天最容易漏掉的点</h2>
<ul class="list">
<li>只把规则页签接成真实数据，技能、MCP、任务仍然靠假数据撑场面。</li>
<li>只做版本列表展示，不做确认弹窗和拒绝风险提示。</li>
<li>把任务写成“定时任务”暴露给用户，违背文档里 UI 名称统一成“任务”的约束。</li>
</ul>
<div class="footer">Day 2 的完成标准不是“页面能打开”，而是“规则中心第一次成为真实的资产入口”。</div>
</div>
</body>
</html>

132
document/development/agent/agent_week_plan_html/day-3.html Normal file
View File

@@ -0,0 +1,132 @@
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Day 3 - 语义本体 MVP</title>
<link rel="stylesheet" href="./styles.css">
</head>
<body>
<div class="shell">
<div class="topbar">
<a class="brand" href="./index.html"><span class="brand-mark">D3</span><span>Day 3 View</span></a>
<div class="quick-links">
<a class="pill" href="./index.html">返回总览</a>
<a class="pill" href="../agent%20week%20plan/day_3_semantic_ontology_mvp.md">周计划原文</a>
<a class="pill" href="../agent%20week%20plan/day_3_semantic_ontology_mvp.md">合并文档原文</a>
</div>
</div>
<div class="day-nav">
<a class="pill" href="./day-1.html">Day 1</a>
<a class="pill" href="./day-2.html">Day 2</a>
<a class="pill active" href="./day-3.html">Day 3</a>
<a class="pill" href="./day-4.html">Day 4</a>
<a class="pill" href="./day-5.html">Day 5</a>
<a class="pill" href="./day-6.html">Day 6</a>
<a class="pill" href="./day-7.html">Day 7</a>
</div>
<section class="hero">
<div class="hero-badge">Ontology</div>
<h1>Day 3 语义本体 MVP</h1>
<p>这一天把自然语言问题统一切成 8 个核心字段。Day 3 不是追求大模型多聪明，而是先让结构稳定、可落日志、可被 Orchestrator、User Agent 和 Hermes 共用。</p>
<div class="hero-meta">
<div class="meta-card"><div class="meta-label">上游依赖</div><div class="meta-value">Day 1 的 <code>SemanticParseLog</code> / <code>AgentRun</code>，Day 2 的资产 API。</div></div>
<div class="meta-card"><div class="meta-label">下游交接</div><div class="meta-value">Day 4 路由、Day 5 查询解释、Day 6 风险巡检都直接消费这 8 字段。</div></div>
<div class="meta-card"><div class="meta-label">当天关键</div><div class="meta-value">名字统一、类型统一、日志统一、低置信度有澄清问题。</div></div>
</div>
</section>
<div class="section-kicker">Three-Layer Mapping</div>
<h2 class="section-title">三层文档映射</h2>
<div class="grid three">
<section class="card tone-warm">
<h3>路线图</h3>
<p>周计划要求建立用户问题的统一语义解析层，覆盖场景、意图、对象、时间、指标、约束、风险、权限 8 字段。</p>
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_3_semantic_ontology_mvp.md">day_3_semantic_ontology_mvp.md</a></div>
</section>
<section class="card tone-teal">
<h3>执行细则</h3>
<p>执行层拆成 8 字段定义、字段枚举、Schema、解析服务、对象提取、时间范围、指标约束、风险权限、API、前端调试入口和评测集。</p>
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_3_semantic_ontology_mvp.md">agent week plan/day_3</a></div>
</section>
<section class="card tone-olive">
<h3>架构依据</h3>
<p>主要受语义本体、财务标准模型和数据治理约束。应收、应付、报销的对象语义必须能回到最小业务表和标准对象。</p>
<div class="card-links">
<a class="link-chip" href="../agent%20plan/02_semantic_ontology.md">02</a>
<a class="link-chip" href="../agent%20plan/14_financial_document_canonical_model.md">14</a>
<a class="link-chip" href="../agent%20plan/06_data_contracts_and_governance.md">06</a>
</div>
</section>
</div>
<div class="section-kicker">Build Order</div>
<h2 class="section-title">推荐开发顺序</h2>
<div class="timeline">
<div class="timeline-step"><strong>Step 1</strong>先固定 8 个字段名字、类型、默认值和示例。</div>
<div class="timeline-step"><strong>Step 2</strong>把 <code>scenario</code>、<code>intent</code>、<code>permission.level</code> 的枚举定死。</div>
<div class="timeline-step"><strong>Step 3</strong>做请求/响应 Schema，再写解析服务。</div>
<div class="timeline-step"><strong>Step 4</strong>补对象提取、时间范围、指标约束、风险和权限映射。</div>
<div class="timeline-step"><strong>Step 5</strong>接 API、日志、调试入口和最小评测集。</div>
</div>
<div class="section-kicker">Must Deliver</div>
<h2 class="section-title">今天必须产出的东西</h2>
<div class="grid two">
<section class="card">
<h3>8 字段统一结构</h3>
<ul class="list">
<li><code>scenario</code>、<code>intent</code>、<code>entities</code>、<code>time_range</code></li>
<li><code>metrics</code>、<code>constraints</code>、<code>risk_flags</code>、<code>permission</code></li>
<li>附带 <code>confidence</code>、<code>clarification_required</code>、<code>run_id</code></li>
</ul>
</section>
<section class="card">
<h3>规则解析优先版</h3>
<ul class="list">
<li>先用关键词和规则解析打底。</li>
<li>报销 / 应收 / 应付 / 知识 / unknown 场景都能落到结构。</li>
<li>越权动作能识别为 <code>approval_required</code> 或 <code>forbidden</code>。</li>
</ul>
</section>
<section class="card">
<h3>日志和调试入口</h3>
<ul class="list">
<li>每次解析都要落 <code>SemanticParseLog</code>。</li>
<li>前端可直接输入一句话看 8 字段结果。</li>
<li>低置信度问题必须给澄清问题。</li>
</ul>
</section>
<section class="card">
<h3>最小评测集</h3>
<ul class="list">
<li>至少覆盖报销、应收、应付、知识、越权动作。</li>
<li>每条样例要写期望 <code>scenario</code>、<code>intent</code> 和权限级别。</li>
<li>当天目标是可评测，而不是追求完美准确率。</li>
</ul>
</section>
</div>
<div class="section-kicker">Acceptance Snapshot</div>
<h2 class="section-title">验收快照</h2>
<div class="table-like">
<div class="row"><div class="row-label">语义结构</div><div class="row-value">8 字段在 Schema、服务层、日志里名字完全一致。</div></div>
<div class="row"><div class="row-label">关键识别</div><div class="row-value">“本周报销超标风险”“客户 A 本月应收”“供应商 B 明天要付多少钱”都能落到正确场景和意图。</div></div>
<div class="row"><div class="row-label">权限结果</div><div class="row-value">“帮我直接付款”不能被识别成可直接执行动作。</div></div>
<div class="row"><div class="row-label">日志与前端</div><div class="row-value">连续调用多次都能在日志中查到，并能通过调试入口观察结果。</div></div>
</div>
<div class="section-kicker">Common Misses</div>
<h2 class="section-title">这一天最容易漏掉的点</h2>
<ul class="list">
<li>字段结构和日志结构各写一套名字，后面 Trace 很难串。</li>
<li>只做 <code>scenario</code> 和 <code>intent</code>，不做 <code>permission</code>，Day 4 会直接失去拦截依据。</li>
<li>只在服务里返回结果，不把解析过程落库或落日志，后续无法复盘误判样例。</li>
</ul>
<div class="footer">Day 3 的价值在于把“语义理解”从模糊文本变成稳定协议。后面所有智能能力都站在这层协议上。</div>
</div>
</body>
</html>

133
document/development/agent/agent_week_plan_html/day-4.html Normal file
View File

@@ -0,0 +1,133 @@
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Day 4 - Orchestrator 运行时</title>
<link rel="stylesheet" href="./styles.css">
</head>
<body>
<div class="shell">
<div class="topbar">
<a class="brand" href="./index.html"><span class="brand-mark">D4</span><span>Day 4 View</span></a>
<div class="quick-links">
<a class="pill" href="./index.html">返回总览</a>
<a class="pill" href="../agent%20week%20plan/day_4_orchestrator_runtime.md">周计划原文</a>
<a class="pill" href="../agent%20week%20plan/day_4_orchestrator_runtime.md">合并文档原文</a>
</div>
</div>
<div class="day-nav">
<a class="pill" href="./day-1.html">Day 1</a>
<a class="pill" href="./day-2.html">Day 2</a>
<a class="pill" href="./day-3.html">Day 3</a>
<a class="pill active" href="./day-4.html">Day 4</a>
<a class="pill" href="./day-5.html">Day 5</a>
<a class="pill" href="./day-6.html">Day 6</a>
<a class="pill" href="./day-7.html">Day 7</a>
</div>
<section class="hero">
<div class="hero-badge">Runtime</div>
<h1>Day 4 Orchestrator 运行时</h1>
<p>Day 4 把整个系统第一次串成“能跑的链”。用户消息和定时任务都先走 Orchestrator，由它创建 run、调用语义解析、做权限判断、选择 Agent、记录 ToolCall 和 Trace，然后再给下游执行。</p>
<div class="hero-meta">
<div class="meta-card"><div class="meta-label">上游依赖</div><div class="meta-value">Day 3 的语义解析结果，Day 1 的 Run / ToolCall，Day 2 的 active 资产。</div></div>
<div class="meta-card"><div class="meta-label">下游交接</div><div class="meta-value">Day 5 User Agent 和 Day 6 Hermes 都通过它被调度。</div></div>
<div class="meta-card"><div class="meta-label">当天关键</div><div class="meta-value">权限拦截和 Trace 必须在 Orchestrator 层，而不是散落在各 Agent。</div></div>
</div>
</section>
<div class="section-kicker">Three-Layer Mapping</div>
<h2 class="section-title">三层文档映射</h2>
<div class="grid three">
<section class="card tone-warm">
<h3>路线图</h3>
<p>周计划要求建立统一调度层，让用户请求和系统任务都先进入 Orchestrator，再根据语义、权限、能力注册路由到 User Agent、Hermes、MCP 或规则引擎。</p>
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_4_orchestrator_runtime.md">day_4_orchestrator_runtime.md</a></div>
</section>
<section class="card tone-teal">
<h3>执行细则</h3>
<p>执行层拆成输入输出、Orchestrator 服务、路由规则、权限判断、能力查询、工具调用封装、API、最小 Trace 查看和测试。</p>
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_4_orchestrator_runtime.md">agent week plan/day_4</a></div>
</section>
<section class="card tone-olive">
<h3>架构依据</h3>
<p>主要受运行时流程、能力注册、权限确认和可观测性约束。Day 4 的输出要能直接给前端展示，并支持 Day 5/6 的占位实现接入。</p>
<div class="card-links">
<a class="link-chip" href="../agent%20plan/04_orchestrator_and_runtime_flow.md">04</a>
<a class="link-chip" href="../agent%20plan/07_capability_registry.md">07</a>
<a class="link-chip" href="../agent%20plan/08_permission_confirmation.md">08</a>
<a class="link-chip" href="../agent%20plan/09_observability_and_trace.md">09</a>
</div>
</section>
</div>
<div class="section-kicker">Build Order</div>
<h2 class="section-title">推荐开发顺序</h2>
<div class="timeline">
<div class="timeline-step"><strong>Step 1</strong>先定 <code>OrchestratorRequest</code> 和 <code>OrchestratorResponse</code>。</div>
<div class="timeline-step"><strong>Step 2</strong>写 <code>run(request)</code> 主流程：创建 Run、解析语义、判权限、选 Agent、更新状态。</div>
<div class="timeline-step"><strong>Step 3</strong>把用户入口 / 任务入口的路由规则固化下来。</div>
<div class="timeline-step"><strong>Step 4</strong>封装工具调用记录和降级策略。</div>
<div class="timeline-step"><strong>Step 5</strong>暴露 API 和最小 Trace 页面或接口。</div>
</div>
<div class="section-kicker">Must Deliver</div>
<h2 class="section-title">今天必须产出的东西</h2>
<div class="grid two">
<section class="card">
<h3>统一入口</h3>
<ul class="list">
<li><code>source=user_message</code> 与 <code>source=schedule</code> 都能进同一入口。</li>
<li>请求返回 <code>run_id</code>、<code>selected_agent</code>、<code>route_reason</code>、<code>permission_level</code>。</li>
<li>返回结果要能被前端直接展示。</li>
</ul>
</section>
<section class="card">
<h3>权限与路由</h3>
<ul class="list">
<li>查询类走 User Agent，定时风险类走 Hermes。</li>
<li><code>approval_required</code> 只返回确认，不直接执行。</li>
<li><code>forbidden</code> 直接阻断，不调下游 Agent。</li>
</ul>
</section>
<section class="card">
<h3>能力与工具调用</h3>
<ul class="list">
<li>只查询 active 技能 / MCP / 任务。</li>
<li>禁用能力不允许被调用。</li>
<li>每次工具调用都能落 <code>AgentToolCall</code>。</li>
</ul>
</section>
<section class="card">
<h3>Trace 与降级</h3>
<ul class="list">
<li>Trace 能串起语义解析、路由、工具调用和最终结果。</li>
<li>外部 MCP 失败要返回降级说明，不让前端拿到不可读错误。</li>
<li>异常都要写进 <code>AgentRun.error_message</code>。</li>
</ul>
</section>
</div>
<div class="section-kicker">Acceptance Snapshot</div>
<h2 class="section-title">验收快照</h2>
<div class="table-like">
<div class="row"><div class="row-label">路由结果</div><div class="row-value">同一句风险检查，在用户入口和任务入口会有不同路由结果。</div></div>
<div class="row"><div class="row-label">权限边界</div><div class="row-value">“直接上线规则”和“直接付款”都不会被自动执行。</div></div>
<div class="row"><div class="row-label">日志完整度</div><div class="row-value">每次运行至少有一条 <code>AgentRun</code>，工具调用有 0 到多条 <code>AgentToolCall</code>。</div></div>
<div class="row"><div class="row-label">可观察性</div><div class="row-value">前端或 curl 可以完整看到一次运行链路，不需要直接查数据库猜过程。</div></div>
</div>
<div class="section-kicker">Common Misses</div>
<h2 class="section-title">这一天最容易漏掉的点</h2>
<ul class="list">
<li>把权限判断放到 User Agent / Hermes 内部，导致系统没有统一边界。</li>
<li>只记录成功 ToolCall，不记录失败 ToolCall，后面降级和排错会缺证据。</li>
<li>路由能跑，但没有统一 Trace 输出，Day 7 演示时会非常难讲清链路。</li>
</ul>
<div class="footer">Day 4 的价值是把系统从“有很多零件”变成“有一条统一运行链”。</div>
</div>
</body>
</html>

133
document/development/agent/agent_week_plan_html/day-5.html Normal file
View File

@@ -0,0 +1,133 @@
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Day 5 - User Agent MVP</title>
<link rel="stylesheet" href="./styles.css">
</head>
<body>
<div class="shell">
<div class="topbar">
<a class="brand" href="./index.html"><span class="brand-mark">D5</span><span>Day 5 View</span></a>
<div class="quick-links">
<a class="pill" href="./index.html">返回总览</a>
<a class="pill" href="../agent%20week%20plan/day_5_user_agent_mvp.md">周计划原文</a>
<a class="pill" href="../agent%20week%20plan/day_5_user_agent_mvp.md">合并文档原文</a>
</div>
</div>
<div class="day-nav">
<a class="pill" href="./day-1.html">Day 1</a>
<a class="pill" href="./day-2.html">Day 2</a>
<a class="pill" href="./day-3.html">Day 3</a>
<a class="pill" href="./day-4.html">Day 4</a>
<a class="pill active" href="./day-5.html">Day 5</a>
<a class="pill" href="./day-6.html">Day 6</a>
<a class="pill" href="./day-7.html">Day 7</a>
</div>
<section class="hero">
<div class="hero-badge">User Agent</div>
<h1>Day 5 User Agent MVP</h1>
<p>这一天开始让“用户真的能问问题”。但 User Agent 只负责查询、解释、规则引用和草稿生成，绝不绕过权限做审批、付款、上线这类高风险动作。</p>
<div class="hero-meta">
<div class="meta-card"><div class="meta-label">上游依赖</div><div class="meta-value">Day 4 Orchestrator、Day 3 语义结构、Day 1 业务数据与日志模型、Day 2 规则资产。</div></div>
<div class="meta-card"><div class="meta-label">下游交接</div><div class="meta-value">Day 7 要拿它做问答演示、规则解释演示和草稿生成演示。</div></div>
<div class="meta-card"><div class="meta-label">当天关键</div><div class="meta-value">回答可读、引用可追溯、草稿可确认、高风险不自动执行。</div></div>
</div>
</section>
<div class="section-kicker">Three-Layer Mapping</div>
<h2 class="section-title">三层文档映射</h2>
<div class="grid three">
<section class="card tone-warm">
<h3>路线图</h3>
<p>周计划要求做用户自然语言入口、报销 / 应收 / 应付查询解释、规则引用解释、建议草稿和前端入口。</p>
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_5_user_agent_mvp.md">day_5_user_agent_mvp.md</a></div>
</section>
<section class="card tone-teal">
<h3>执行细则</h3>
<p>执行层拆成输入输出、查询处理、规则解释、风险解释、草稿生成、知识库读取骨架、对话入口、安全边界和测试。</p>
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_5_user_agent_mvp.md">agent week plan/day_5</a></div>
</section>
<section class="card tone-olive">
<h3>架构依据</h3>
<p>主要受 Agent 职责划分、运行时流程、知识架构和规则形成生命周期约束。所有高风险动作只能停留在建议或草稿层。</p>
<div class="card-links">
<a class="link-chip" href="../agent%20plan/03_agent_responsibilities.md">03</a>
<a class="link-chip" href="../agent%20plan/04_orchestrator_and_runtime_flow.md">04</a>
<a class="link-chip" href="../agent%20plan/12_llm_wiki_knowledge_architecture.md">12</a>
<a class="link-chip" href="../agent%20plan/13_rule_formation_lifecycle.md">13</a>
</div>
</section>
</div>
<div class="section-kicker">Build Order</div>
<h2 class="section-title">推荐开发顺序</h2>
<div class="timeline">
<div class="timeline-step"><strong>Step 1</strong>先定 <code>UserAgentRequest</code> / <code>UserAgentResponse</code> 协议。</div>
<div class="timeline-step"><strong>Step 2</strong>优先实现报销、应收、应付查询处理器。</div>
<div class="timeline-step"><strong>Step 3</strong>补规则解释和风险解释，让回答有依据而不是只给一句话。</div>
<div class="timeline-step"><strong>Step 4</strong>补草稿生成与知识读取骨架。</div>
<div class="timeline-step"><strong>Step 5</strong>最后接前端问答入口、加载态、错误态和确认提示。</div>
</div>
<div class="section-kicker">Must Deliver</div>
<h2 class="section-title">今天必须产出的东西</h2>
<div class="grid two">
<section class="card">
<h3>三类财务查询</h3>
<ul class="list">
<li>报销查询可读，能查金额、状态或进度。</li>
<li>应收查询可读，能查客户未收金额或账龄。</li>
<li>应付查询可读，能查供应商待付款或付款状态。</li>
</ul>
</section>
<section class="card">
<h3>解释能力</h3>
<ul class="list">
<li>规则解释能引用 active 规则、版本号和更新时间。</li>
<li>风险解释能说明风险类型、原因和建议动作。</li>
<li>知识库不可用时要优雅降级。</li>
</ul>
</section>
<section class="card">
<h3>草稿而非执行</h3>
<ul class="list">
<li>可生成报销处理意见草稿、应收催收建议草稿、应付付款建议草稿。</li>
<li>草稿必须写明“待人工确认”。</li>
<li>草稿行为写入审计日志和 AgentRun 结果。</li>
</ul>
</section>
<section class="card">
<h3>用户入口</h3>
<ul class="list">
<li>前端输入框走 Orchestrator，不绕行。</li>
<li>显示回答、引用、建议动作、确认提示和 <code>run_id</code>。</li>
<li>有加载态和错误态。</li>
</ul>
</section>
</div>
<div class="section-kicker">Acceptance Snapshot</div>
<h2 class="section-title">验收快照</h2>
<div class="table-like">
<div class="row"><div class="row-label">问答闭环</div><div class="row-value">用户在页面上能完成一次自然语言提问、拿到回答、看到引用和 run_id。</div></div>
<div class="row"><div class="row-label">三类场景</div><div class="row-value">至少报销、应收、应付三类财务问题都有结构化回答。</div></div>
<div class="row"><div class="row-label">引用能力</div><div class="row-value">“为什么这笔报销有风险”这类问题能引用规则，而不是只给模糊判断。</div></div>
<div class="row"><div class="row-label">安全边界</div><div class="row-value">“直接付款”“直接审批”类提示不会自动执行，只能变成建议或草稿。</div></div>
</div>
<div class="section-kicker">Common Misses</div>
<h2 class="section-title">这一天最容易漏掉的点</h2>
<ul class="list">
<li>只返回原始查询数据，不把结果翻译成用户可读回答。</li>
<li>只做草稿内容，不做 <code>requires_confirmation</code> 和审计日志。</li>
<li>绕过 Orchestrator 直接从前端打 User Agent，导致 Day 4 的统一链路失效。</li>
</ul>
<div class="footer">Day 5 的判断标准是：用户能问、系统能答、回答有依据、动作不越权。</div>
</div>
</body>
</html>

133
document/development/agent/agent_week_plan_html/day-6.html Normal file
View File

@@ -0,0 +1,133 @@
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Day 6 - Hermes MVP</title>
<link rel="stylesheet" href="./styles.css">
</head>
<body>
<div class="shell">
<div class="topbar">
<a class="brand" href="./index.html"><span class="brand-mark">D6</span><span>Day 6 View</span></a>
<div class="quick-links">
<a class="pill" href="./index.html">返回总览</a>
<a class="pill" href="../agent%20week%20plan/day_6_hermes_mvp.md">周计划原文</a>
<a class="pill" href="../agent%20week%20plan/day_6_hermes_mvp.md">合并文档原文</a>
</div>
</div>
<div class="day-nav">
<a class="pill" href="./day-1.html">Day 1</a>
<a class="pill" href="./day-2.html">Day 2</a>
<a class="pill" href="./day-3.html">Day 3</a>
<a class="pill" href="./day-4.html">Day 4</a>
<a class="pill" href="./day-5.html">Day 5</a>
<a class="pill active" href="./day-6.html">Day 6</a>
<a class="pill" href="./day-7.html">Day 7</a>
</div>
<section class="hero">
<div class="hero-badge">Hermes</div>
<h1>Day 6 Hermes MVP</h1>
<p>Hermes 是后台数字员工，不做即时对话，而是负责定时巡检、风险预警、日报统计、知识候选和规则草稿。它的关键不是“会不会说”，而是“任务能不能跑、结果能不能追”。</p>
<div class="hero-meta">
<div class="meta-card"><div class="meta-label">上游依赖</div><div class="meta-value">Day 4 的 Orchestrator 路由，Day 1 的任务与日志表，Day 3 的语义结构，Day 5 可复用的风险/规则/知识接口。</div></div>
<div class="meta-card"><div class="meta-label">下游交接</div><div class="meta-value">Day 7 要用它做手动触发任务、查看结果、展示规则草稿和知识候选。</div></div>
<div class="meta-card"><div class="meta-label">当天关键</div><div class="meta-value">任务入口、风险项结构、OCR Mock、知识候选和规则草稿都必须可追溯。</div></div>
</div>
</section>
<div class="section-kicker">Three-Layer Mapping</div>
<h2 class="section-title">三层文档映射</h2>
<div class="grid three">
<section class="card tone-warm">
<h3>路线图</h3>
<p>周计划要求实现 Hermes 调度入口、每日风险巡检、统计任务、知识库维护、OCR Mock 和运行结果面板或 API。</p>
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_6_hermes_mvp.md">day_6_hermes_mvp.md</a></div>
</section>
<section class="card tone-teal">
<h3>执行细则</h3>
<p>执行层拆成输入输出、任务调度入口、风险巡检、每日统计、OCR 接入点、知识库维护、规则草稿形成、结果展示和测试。</p>
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_6_hermes_mvp.md">agent week plan/day_6</a></div>
</section>
<section class="card tone-olive">
<h3>架构依据</h3>
<p>主要受 Agent 职责、OCR 架构、知识库架构和反馈学习闭环约束。Hermes 能生成候选和草稿，但不能自动发布正式结果。</p>
<div class="card-links">
<a class="link-chip" href="../agent%20plan/03_agent_responsibilities.md">03</a>
<a class="link-chip" href="../agent%20plan/11_ocr_invoice_architecture.md">11</a>
<a class="link-chip" href="../agent%20plan/12_llm_wiki_knowledge_architecture.md">12</a>
<a class="link-chip" href="../agent%20plan/15_feedback_learning_loop.md">15</a>
</div>
</section>
</div>
<div class="section-kicker">Build Order</div>
<h2 class="section-title">推荐开发顺序</h2>
<div class="timeline">
<div class="timeline-step"><strong>Step 1</strong>先定 <code>HermesTaskRequest</code> / <code>HermesTaskResult</code>。</div>
<div class="timeline-step"><strong>Step 2</strong>建立手动触发任务 API，经 Orchestrator 路由到 Hermes。</div>
<div class="timeline-step"><strong>Step 3</strong>补风险巡检和每日统计的结构化输出。</div>
<div class="timeline-step"><strong>Step 4</strong>接入 OCR Mock、知识候选生成、规则草稿生成。</div>
<div class="timeline-step"><strong>Step 5</strong>补任务详情展示、错误信息和测试。</div>
</div>
<div class="section-kicker">Must Deliver</div>
<h2 class="section-title">今天必须产出的东西</h2>
<div class="grid two">
<section class="card">
<h3>任务调度入口</h3>
<ul class="list">
<li>可手动触发至少一个任务资产。</li>
<li>任务经 Orchestrator 进入 Hermes。</li>
<li>结束后能更新最近执行时间和状态。</li>
</ul>
</section>
<section class="card">
<h3>风险与统计</h3>
<ul class="list">
<li>重复报销、金额超标、应收逾期、应付异常付款等风险有结构化输出。</li>
<li>日报包含报销、报账、应收、应付的关键统计口径。</li>
<li>每个风险项都要能被业务人员理解和追溯。</li>
</ul>
</section>
<section class="card">
<h3>知识候选与规则草稿</h3>
<ul class="list">
<li>知识候选默认是 <code>draft</code>，不能自动发布。</li>
<li>规则草稿保存为 <code>asset_type=rule</code>，状态为 <code>draft</code>。</li>
<li>两类生成都要写审计日志。</li>
</ul>
</section>
<section class="card">
<h3>OCR Mock 与结果展示</h3>
<ul class="list">
<li>OCR 服务接口和输入输出结构定下来。</li>
<li>当前阶段允许完全使用 Mock 结果。</li>
<li>任务详情或运行日志中能直接看到 Hermes 的执行结果。</li>
</ul>
</section>
</div>
<div class="section-kicker">Acceptance Snapshot</div>
<h2 class="section-title">验收快照</h2>
<div class="table-like">
<div class="row"><div class="row-label">任务可触发</div><div class="row-value">至少一个任务可以手动触发，并能查到结构化结果。</div></div>
<div class="row"><div class="row-label">风险巡检</div><div class="row-value">输出里能看到风险类型、业务对象、触发规则、建议动作和风险等级。</div></div>
<div class="row"><div class="row-label">候选与草稿</div><div class="row-value">知识候选和规则草稿都能生成，但都不是 active / published 正式状态。</div></div>
<div class="row"><div class="row-label">可观察性</div><div class="row-value">不用查数据库，也能从任务详情或运行日志判断 Hermes 是否执行成功。</div></div>
</div>
<div class="section-kicker">Common Misses</div>
<h2 class="section-title">这一天最容易漏掉的点</h2>
<ul class="list">
<li>只做 Hermes 服务逻辑，不做任务入口和结果展示，最后无法演示。</li>
<li>能生成知识或规则，但没把状态锁在 <code>draft</code>，会直接越过人工审核边界。</li>
<li>OCR Mock 只返回一段自由文本，不定义结构字段，后面无法和规则或风险逻辑对接。</li>
</ul>
<div class="footer">Day 6 的价值是让“后台数字员工”第一次具备可触发、可解释、可留痕的闭环。</div>
</div>
</body>
</html>

132
document/development/agent/agent_week_plan_html/day-7.html Normal file
View File

@@ -0,0 +1,132 @@
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Day 7 - 加固、演示和验收</title>
<link rel="stylesheet" href="./styles.css">
</head>
<body>
<div class="shell">
<div class="topbar">
<a class="brand" href="./index.html"><span class="brand-mark">D7</span><span>Day 7 View</span></a>
<div class="quick-links">
<a class="pill" href="./index.html">返回总览</a>
<a class="pill" href="../agent%20week%20plan/day_7_hardening_demo_acceptance.md">周计划原文</a>
<a class="pill" href="../agent%20week%20plan/day_7_hardening_demo_acceptance.md">合并文档原文</a>
</div>
</div>
<div class="day-nav">
<a class="pill" href="./day-1.html">Day 1</a>
<a class="pill" href="./day-2.html">Day 2</a>
<a class="pill" href="./day-3.html">Day 3</a>
<a class="pill" href="./day-4.html">Day 4</a>
<a class="pill" href="./day-5.html">Day 5</a>
<a class="pill" href="./day-6.html">Day 6</a>
<a class="pill active" href="./day-7.html">Day 7</a>
</div>
<section class="hero">
<div class="hero-badge">Hardening</div>
<h1>Day 7 加固、演示和验收</h1>
<p>Day 7 不再追求新增大功能，而是把 Day 1 到 Day 6 的链路整理成“可演示、可验收、可继续接手”的状态。没有这一层收口，前面做出来的东西很容易停在“只有作者自己懂”的阶段。</p>
<div class="hero-meta">
<div class="meta-card"><div class="meta-label">上游依赖</div><div class="meta-value">Day 1 到 Day 6 的全部核心路径。</div></div>
<div class="meta-card"><div class="meta-label">当天输出</div><div class="meta-value">回归记录、权限边界、审计和 Trace 补齐、测试记录、演示脚本、交接说明。</div></div>
<div class="meta-card"><div class="meta-label">当天关键</div><div class="meta-value">冻结新增需求，只收验收相关缺口。</div></div>
</div>
</section>
<div class="section-kicker">Three-Layer Mapping</div>
<h2 class="section-title">三层文档映射</h2>
<div class="grid three">
<section class="card tone-warm">
<h3>路线图</h3>
<p>周计划要求完成回归、权限补齐、审计补齐、错误态和空态、评测、演示数据、构建和交付说明。</p>
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_7_hardening_demo_acceptance.md">day_7_hardening_demo_acceptance.md</a></div>
</section>
<section class="card tone-teal">
<h3>执行细则</h3>
<p>执行层拆成核心链路回归、权限和风险边界、审计和 Trace、前端体验修补、测试补齐、评测集、演示数据、演示脚本和文档收尾。</p>
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_7_hardening_demo_acceptance.md">agent week plan/day_7</a></div>
</section>
<section class="card tone-olive">
<h3>架构依据</h3>
<p>主要受整体 README、开发路线图、可观测性和评测集约束。Day 7 的本质是把所有边界和证据讲清楚。</p>
<div class="card-links">
<a class="link-chip" href="../agent%20plan/00_README.md">00</a>
<a class="link-chip" href="../agent%20plan/05_development_roadmap.md">05</a>
<a class="link-chip" href="../agent%20plan/09_observability_and_trace.md">09</a>
<a class="link-chip" href="../agent%20plan/10_evaluation_and_testset.md">10</a>
</div>
</section>
</div>
<div class="section-kicker">Build Order</div>
<h2 class="section-title">推荐收口顺序</h2>
<div class="timeline">
<div class="timeline-step"><strong>Step 1</strong>先汇总 Day 1 到 Day 6 未完成项，冻结新增需求。</div>
<div class="timeline-step"><strong>Step 2</strong>回归核心链路：资产、规则、语义解析、Orchestrator、User Agent、Hermes、Trace、AuditLog。</div>
<div class="timeline-step"><strong>Step 3</strong>补权限边界与高风险动作拦截。</div>
<div class="timeline-step"><strong>Step 4</strong>补测试、评测、演示数据和前端体验问题。</div>
<div class="timeline-step"><strong>Step 5</strong>写演示脚本和交接说明，形成最终交付。</div>
</div>
<div class="section-kicker">Must Deliver</div>
<h2 class="section-title">今天必须产出的东西</h2>
<div class="grid two">
<section class="card">
<h3>回归与边界</h3>
<ul class="list">
<li>未审核规则不能上线。</li>
<li>付款、审批、上线等高风险动作都不能绕过确认。</li>
<li>disabled 能力不能被调用。</li>
</ul>
</section>
<section class="card">
<h3>审计与 Trace</h3>
<ul class="list">
<li>规则保存、审核、上线都能看到 AuditLog。</li>
<li>Hermes 生成知识候选 / 规则草稿有审计。</li>
<li>任意演示路径都能追到 <code>run_id</code>。</li>
</ul>
</section>
<section class="card">
<h3>测试、评测、演示数据</h3>
<ul class="list">
<li>后端测试、前端构建、语义评测至少有执行记录。</li>
<li>报销 / 应收 / 应付 / 风险 / 知识都准备好演示数据。</li>
<li>失败样例和已知边界要明确写出。</li>
</ul>
</section>
<section class="card">
<h3>演示脚本与交接</h3>
<ul class="list">
<li>从任务规则中心、规则详情、版本切换、上线拦截，到 User Agent 问答、Hermes 任务、Trace 和审计，都有明确步骤。</li>
<li>新开发者按脚本能走通一遍。</li>
</ul>
</section>
</div>
<div class="section-kicker">Acceptance Snapshot</div>
<h2 class="section-title">最终验收快照</h2>
<div class="table-like">
<div class="row"><div class="row-label">端到端链路</div><div class="row-value">从规则中心到 User Agent，再到 Hermes 和 Trace，至少有一条完整演示路径可复现。</div></div>
<div class="row"><div class="row-label">证据完整</div><div class="row-value">AgentRun、ToolCall、AuditLog、测试记录、评测结果和演示脚本都存在。</div></div>
<div class="row"><div class="row-label">风险边界</div><div class="row-value">MVP 期间不存在绕过人工审核、自动付款、自动上线的暗门路径。</div></div>
<div class="row"><div class="row-label">可交接性</div><div class="row-value">下一位开发或 Codex 打开文档就能知道已完成、未完成和生产化前必补项。</div></div>
</div>
<div class="section-kicker">Common Misses</div>
<h2 class="section-title">这一天最容易漏掉的点</h2>
<ul class="list">
<li>只验证 Happy Path，不回归错误态、空态、禁用态和被权限拦截路径。</li>
<li>能讲演示，但没有测试记录和已知风险说明，交接质量会很差。</li>
<li>前 6 天的 TODO 没回写完成状态，导致页面和 Markdown 脱节。</li>
</ul>
<div class="footer">Day 7 的目标不是继续堆功能，而是把一周产出变成别人也能运行、理解和接手的系统。</div>
</div>
</body>
</html>

181
document/development/agent/agent_week_plan_html/index.html Normal file
View File

@@ -0,0 +1,181 @@
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Agent Week Plan HTML</title>
<link rel="stylesheet" href="./styles.css">
</head>
<body>
<div class="shell">
<div class="topbar">
<a class="brand" href="./index.html">
<span class="brand-mark">A7</span>
<span>Agent Week HTML</span>
</a>
<div class="quick-links">
<a class="pill" href="../agent%20week%20plan/MASTER_TODO.md">周计划总控</a>
<a class="pill" href="../agent%20week%20plan/00_README.md">周计划说明</a>
<a class="pill" href="../agent%20plan/00_README.md">架构目录</a>
</div>
</div>
<section class="hero">
<div class="hero-badge">Static Map</div>
<h1>把 7 天周计划变成可直接浏览的开发视图</h1>
<p>这一套 HTML 页面不是替代 Markdown，而是把 <code>agent week plan</code> 和 <code>agent plan</code> 的对应关系收成一个稳定入口。每天的路线图和执行清单现在已经并到同一份 daily 文档里。</p>
<div class="hero-meta">
<div class="meta-card">
<div class="meta-label">阅读顺序</div>
<div class="meta-value">先总览，再选 Day，再跳转到具体 Markdown 落地执行。</div>
</div>
<div class="meta-card">
<div class="meta-label">核心视图</div>
<div class="meta-value">路线图、执行细则、架构依据三层同时可见。</div>
</div>
<div class="meta-card">
<div class="meta-label">适用对象</div>
<div class="meta-value">Codex 开发、后端开发、前端开发、项目 owner、验收人员。</div>
</div>
</div>
</section>
<div class="section-kicker">How To Use</div>
<h2 class="section-title">怎么用这套页面</h2>
<div class="grid two">
<section class="card tone-teal">
<h3>Codex 开发视角</h3>
<ol class="list">
<li>先看今天在哪一天，确认上游依赖和下游交接。</li>
<li>用“两层映射”定位：daily 文档看目标和步骤，架构文档看约束。</li>
<li>按“推荐开发顺序”推进，不跳天，不跨层乱做。</li>
<li>完成后回到原始 Markdown，把 TODO、阻塞、交接更新回文档。</li>
</ol>
</section>
<section class="card tone-warm">
<h3>人工开发与验收视角</h3>
<ol class="list">
<li>先看每一天的“今日定位”，知道这一天到底产出什么。</li>
<li>再看“今天必须产出的东西”和“验收快照”，确认完成标准。</li>
<li>最后跳转到对应 Markdown，逐条执行或验收。</li>
<li>如果发现跨天阻塞，优先回前一天补地基，而不是在当前天临时兜底。</li>
</ol>
</section>
</div>
<div class="section-kicker">Three Layers</div>
<h2 class="section-title">文档结构一眼看清</h2>
<div class="grid three">
<section class="card">
<h3>1. 周计划路线图</h3>
<p>定义每天的大方向、交付物和验收门槛。用于排期、对齐和验收。核心入口是 <code>MASTER_TODO.md</code> 和 Day 1 到 Day 7 daily 文档。</p>
<div class="card-links">
<a class="link-chip" href="../agent%20week%20plan/00_README.md">00_README</a>
<a class="link-chip" href="../agent%20week%20plan/MASTER_TODO.md">MASTER_TODO</a>
</div>
</section>
<section class="card">
<h3>2. 每日执行清单</h3>
<p>每天的开发目标已经拆到对应 daily 文档中的详细执行清单，直接覆盖模型、字段、接口、服务、前端、测试和验收证据。</p>
<div class="card-links">
<a class="link-chip" href="../agent%20week%20plan/00_README.md">00_README</a>
<a class="link-chip" href="../agent%20week%20plan/MASTER_TODO.md">MASTER_TODO</a>
</div>
</section>
<section class="card">
<h3>3. 架构依据</h3>
<p>提供为什么要这么做、协议怎么定、权限和审计边界是什么。它不直接当 TODO，但所有实现都要受它约束。</p>
<div class="card-links">
<a class="link-chip" href="../agent%20plan/01_overall_architecture.md">总体架构</a>
<a class="link-chip" href="../agent%20plan/02_semantic_ontology.md">语义本体</a>
<a class="link-chip" href="../agent%20plan/09_observability_and_trace.md">观测与 Trace</a>
</div>
</section>
</div>
<div class="section-kicker">Seven Days</div>
<h2 class="section-title">7 天总览</h2>
<div class="grid two">
<section class="card tone-olive">
<h3>Day 1 基础模型与工程骨架</h3>
<p><strong>当前状态：</strong>已完成（2026-05-11）。先把 Agent 资产、版本、审核、运行日志、审计日志，以及报销 / 应收 / 应付的最小业务数据来源定下来。后面所有能力都站在这一天的模型上。</p>
<div class="card-links">
<a class="link-chip" href="./day-1.html">打开日视图</a>
<a class="link-chip" href="../agent%20week%20plan/day_1_foundation_models.md">周计划</a>
<a class="link-chip" href="../agent%20week%20plan/day_1_foundation_models.md">合并文档</a>
</div>
</section>
<section class="card tone-teal">
<h3>Day 2 任务规则中心联调</h3>
<p>把规则、技能、MCP、任务从静态 UI 拉到真实后端数据。重点是规则 Markdown、版本切换、审核和上线拦截。</p>
<div class="card-links">
<a class="link-chip" href="./day-2.html">打开日视图</a>
<a class="link-chip" href="../agent%20week%20plan/day_2_rule_center_integration.md">周计划</a>
<a class="link-chip" href="../agent%20week%20plan/day_2_rule_center_integration.md">合并文档</a>
</div>
</section>
<section class="card tone-warm">
<h3>Day 3 语义本体 MVP</h3>
<p>建立 8 字段语义解析协议，让报销、应收、应付、知识查询进入同一结构，给 Orchestrator、User Agent、Hermes 统一消费。</p>
<div class="card-links">
<a class="link-chip" href="./day-3.html">打开日视图</a>
<a class="link-chip" href="../agent%20week%20plan/day_3_semantic_ontology_mvp.md">周计划</a>
<a class="link-chip" href="../agent%20week%20plan/day_3_semantic_ontology_mvp.md">合并文档</a>
</div>
</section>
<section class="card">
<h3>Day 4 Orchestrator 运行时</h3>
<p>把用户消息和定时任务统一接到 Orchestrator，完成 run_id、权限拦截、Agent 路由、ToolCall 和 Trace。</p>
<div class="card-links">
<a class="link-chip" href="./day-4.html">打开日视图</a>
<a class="link-chip" href="../agent%20week%20plan/day_4_orchestrator_runtime.md">周计划</a>
<a class="link-chip" href="../agent%20week%20plan/day_4_orchestrator_runtime.md">合并文档</a>
</div>
</section>
<section class="card tone-teal">
<h3>Day 5 User Agent MVP</h3>
<p>面向用户的问答和流程辅助层。做查询、解释、规则引用、草稿生成，但严格不碰自动审批、自动付款和自动上线。</p>
<div class="card-links">
<a class="link-chip" href="./day-5.html">打开日视图</a>
<a class="link-chip" href="../agent%20week%20plan/day_5_user_agent_mvp.md">周计划</a>
<a class="link-chip" href="../agent%20week%20plan/day_5_user_agent_mvp.md">合并文档</a>
</div>
</section>
<section class="card tone-olive">
<h3>Day 6 Hermes MVP</h3>
<p>后台数字员工层。做任务触发、风险巡检、日报统计、OCR Mock、知识候选、规则草稿，结果都必须可追溯。</p>
<div class="card-links">
<a class="link-chip" href="./day-6.html">打开日视图</a>
<a class="link-chip" href="../agent%20week%20plan/day_6_hermes_mvp.md">周计划</a>
<a class="link-chip" href="../agent%20week%20plan/day_6_hermes_mvp.md">合并文档</a>
</div>
</section>
<section class="card tone-accent">
<h3>Day 7 加固、演示和验收</h3>
<p>不再大扩功能，只做回归、权限边界、审计、Trace、测试、演示脚本和交接收口，让整周产出可跑、可演示、可继续接手。</p>
<div class="card-links">
<a class="link-chip" href="./day-7.html">打开日视图</a>
<a class="link-chip" href="../agent%20week%20plan/day_7_hardening_demo_acceptance.md">周计划</a>
<a class="link-chip" href="../agent%20week%20plan/day_7_hardening_demo_acceptance.md">合并文档</a>
</div>
</section>
</div>
<div class="section-kicker">Dependency Chain</div>
<h2 class="section-title">跨天依赖链</h2>
<div class="timeline">
<div class="timeline-step"><strong>Day 1</strong>模型、审计、运行日志、最小业务数据源</div>
<div class="timeline-step"><strong>Day 2</strong>把 Day 1 的资产 API 接进规则中心 UI</div>
<div class="timeline-step"><strong>Day 3</strong>在 Day 1/2 基础上产出统一语义结构</div>
<div class="timeline-step"><strong>Day 4</strong>用 Day 3 的语义结果完成路由与权限</div>
<div class="timeline-step"><strong>Day 5</strong>接入 User Agent 问答、解释和草稿</div>
<div class="timeline-step"><strong>Day 6</strong>接入 Hermes 任务、巡检和知识/规则候选</div>
<div class="timeline-step"><strong>Day 7</strong>统一回归、补日志、做演示和交接</div>
</div>
<div class="footer">
打开顺序建议：<a href="./day-1.html">Day 1</a> 到 <a href="./day-7.html">Day 7</a>。真正执行时，仍以原始 Markdown 为准，这套 HTML 负责加速定位和浏览。
</div>
</div>
</body>
</html>

426
document/development/agent/agent_week_plan_html/styles.css Normal file
View File

@@ -0,0 +1,426 @@
:root {
--bg: #f3ead9;
--bg-deep: #e7d8bc;
--panel: rgba(255, 250, 241, 0.9);
--panel-strong: #fff8ee;
--ink: #1f2a24;
--muted: #64655d;
--line: #dbc8a9;
--accent: #bb5b2c;
--accent-strong: #8d3d1b;
--accent-soft: #f4d9bf;
--teal: #20656d;
--teal-soft: #d8ecee;
--olive: #5f6b3a;
--olive-soft: #e6ecd7;
--shadow: 0 24px 60px rgba(84, 59, 30, 0.12);
--radius-xl: 28px;
--radius-lg: 20px;
--radius-md: 14px;
--max: 1240px;
}
* {
box-sizing: border-box;
}
html {
scroll-behavior: smooth;
}
body {
margin: 0;
font-family: "Trebuchet MS", "Gill Sans", "Lucida Grande", sans-serif;
color: var(--ink);
background:
radial-gradient(circle at top left, rgba(32, 101, 109, 0.14), transparent 26%),
radial-gradient(circle at top right, rgba(187, 91, 44, 0.15), transparent 30%),
linear-gradient(180deg, #f8f0e2 0%, var(--bg) 40%, #efe2cb 100%);
}
a {
color: inherit;
}
.shell {
width: min(100% - 40px, var(--max));
margin: 0 auto;
padding: 28px 0 56px;
}
.topbar {
display: flex;
align-items: center;
justify-content: space-between;
gap: 16px;
flex-wrap: wrap;
margin-bottom: 18px;
}
.brand {
display: inline-flex;
align-items: center;
gap: 12px;
text-decoration: none;
font-weight: 700;
letter-spacing: 0.04em;
text-transform: uppercase;
color: var(--accent-strong);
}
.brand-mark {
display: inline-flex;
align-items: center;
justify-content: center;
width: 42px;
height: 42px;
border-radius: 50%;
background: linear-gradient(135deg, var(--accent), #df9a44);
color: #fff7ef;
box-shadow: 0 14px 30px rgba(187, 91, 44, 0.28);
}
.quick-links,
.day-nav {
display: flex;
flex-wrap: wrap;
gap: 10px;
}
.pill {
display: inline-flex;
align-items: center;
justify-content: center;
min-height: 38px;
padding: 10px 14px;
border-radius: 999px;
border: 1px solid rgba(143, 114, 74, 0.22);
background: rgba(255, 248, 238, 0.75);
text-decoration: none;
color: var(--muted);
font-size: 14px;
transition: transform 180ms ease, border-color 180ms ease, background 180ms ease;
}
.pill:hover,
.pill:focus-visible {
transform: translateY(-1px);
border-color: rgba(187, 91, 44, 0.4);
background: rgba(255, 251, 245, 0.96);
outline: none;
}
.pill.active {
color: #fff6ef;
border-color: transparent;
background: linear-gradient(135deg, var(--accent-strong), var(--accent));
box-shadow: 0 14px 24px rgba(141, 61, 27, 0.24);
}
.hero {
position: relative;
overflow: hidden;
margin-bottom: 22px;
padding: 30px;
border: 1px solid rgba(128, 109, 82, 0.18);
border-radius: var(--radius-xl);
background:
linear-gradient(135deg, rgba(255, 248, 238, 0.95), rgba(247, 236, 216, 0.88)),
var(--panel);
box-shadow: var(--shadow);
}
.hero::after {
content: "";
position: absolute;
right: -50px;
top: -50px;
width: 220px;
height: 220px;
border-radius: 50%;
background: radial-gradient(circle, rgba(32, 101, 109, 0.16), transparent 68%);
}
.hero-badge {
display: inline-flex;
align-items: center;
gap: 8px;
margin-bottom: 12px;
padding: 7px 12px;
border-radius: 999px;
background: var(--accent-soft);
color: var(--accent-strong);
font-size: 13px;
font-weight: 700;
letter-spacing: 0.05em;
text-transform: uppercase;
}
.hero h1 {
margin: 0;
font-family: "Iowan Old Style", "Palatino Linotype", "Book Antiqua", serif;
font-size: clamp(34px, 5vw, 62px);
line-height: 1.03;
}
.hero p {
max-width: 880px;
margin: 14px 0 0;
color: var(--muted);
font-size: 18px;
line-height: 1.65;
}
.hero-meta {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
gap: 14px;
margin-top: 20px;
}
.meta-card {
padding: 14px 16px;
border-radius: var(--radius-md);
background: rgba(255, 255, 255, 0.55);
border: 1px solid rgba(132, 109, 83, 0.16);
}
.meta-label {
margin-bottom: 6px;
color: var(--muted);
font-size: 12px;
font-weight: 700;
letter-spacing: 0.08em;
text-transform: uppercase;
}
.meta-value {
font-size: 16px;
line-height: 1.45;
}
.grid {
display: grid;
gap: 18px;
}
.grid.two {
grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
}
.grid.three {
grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
}
.card {
padding: 22px;
border: 1px solid rgba(132, 109, 83, 0.15);
border-radius: var(--radius-lg);
background: var(--panel);
box-shadow: 0 16px 36px rgba(78, 58, 32, 0.08);
animation: rise 420ms ease both;
}
.card:nth-child(2) { animation-delay: 60ms; }
.card:nth-child(3) { animation-delay: 120ms; }
.card:nth-child(4) { animation-delay: 180ms; }
.card:nth-child(5) { animation-delay: 240ms; }
.card h2,
.card h3 {
margin: 0 0 10px;
font-family: "Iowan Old Style", "Palatino Linotype", "Book Antiqua", serif;
}
.card h2 {
font-size: 28px;
}
.card h3 {
font-size: 22px;
}
.card p {
margin: 0;
color: var(--muted);
line-height: 1.7;
}
.section-title {
margin: 28px 0 14px;
font-family: "Iowan Old Style", "Palatino Linotype", "Book Antiqua", serif;
font-size: 28px;
}
.section-kicker {
margin: 30px 0 8px;
color: var(--accent-strong);
font-size: 13px;
font-weight: 700;
letter-spacing: 0.08em;
text-transform: uppercase;
}
.list,
.compact-list {
margin: 12px 0 0;
padding-left: 18px;
color: var(--ink);
line-height: 1.72;
}
.compact-list {
font-size: 15px;
}
.list li + li,
.compact-list li + li {
margin-top: 8px;
}
.card-links {
display: flex;
flex-wrap: wrap;
gap: 10px;
margin-top: 16px;
}
.link-chip {
display: inline-flex;
align-items: center;
gap: 8px;
padding: 10px 13px;
border-radius: 999px;
background: rgba(255, 255, 255, 0.76);
border: 1px solid rgba(132, 109, 83, 0.18);
text-decoration: none;
font-size: 14px;
}
.tone-warm {
background: linear-gradient(180deg, rgba(244, 217, 191, 0.55), rgba(255, 250, 241, 0.9));
}
.tone-teal {
background: linear-gradient(180deg, rgba(216, 236, 238, 0.76), rgba(255, 250, 241, 0.92));
}
.tone-olive {
background: linear-gradient(180deg, rgba(230, 236, 215, 0.82), rgba(255, 250, 241, 0.92));
}
.tone-accent {
background: linear-gradient(160deg, rgba(141, 61, 27, 0.94), rgba(187, 91, 44, 0.92));
color: #fff8f1;
}
.tone-accent p,
.tone-accent .meta-label,
.tone-accent .meta-value,
.tone-accent li {
color: rgba(255, 248, 241, 0.92);
}
.tone-accent .link-chip,
.tone-accent .pill {
background: rgba(255, 255, 255, 0.14);
border-color: rgba(255, 255, 255, 0.18);
color: #fff8f1;
}
.timeline {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
gap: 12px;
}
.timeline-step {
position: relative;
padding: 16px;
border-radius: var(--radius-md);
border: 1px solid rgba(132, 109, 83, 0.16);
background: rgba(255, 252, 247, 0.84);
}
.timeline-step strong {
display: block;
margin-bottom: 8px;
font-size: 15px;
}
.footer {
margin-top: 26px;
padding: 20px 4px 0;
color: var(--muted);
font-size: 14px;
}
.muted {
color: var(--muted);
}
.table-like {
display: grid;
gap: 12px;
}
.row {
display: grid;
grid-template-columns: minmax(120px, 0.9fr) minmax(0, 2.3fr);
gap: 14px;
padding: 14px 16px;
border-radius: var(--radius-md);
border: 1px solid rgba(132, 109, 83, 0.15);
background: rgba(255, 255, 255, 0.56);
}
.row-label {
font-size: 13px;
font-weight: 700;
letter-spacing: 0.06em;
text-transform: uppercase;
color: var(--accent-strong);
}
.row-value {
line-height: 1.68;
}
code {
padding: 1px 6px;
border-radius: 8px;
background: rgba(32, 101, 109, 0.08);
color: var(--teal);
font-family: "Lucida Console", "Courier New", monospace;
font-size: 0.92em;
}
@keyframes rise {
from {
opacity: 0;
transform: translateY(10px);
}
to {
opacity: 1;
transform: translateY(0);
}
}
@media (max-width: 760px) {
.shell {
width: min(100% - 24px, var(--max));
padding-top: 18px;
}
.hero {
padding: 22px;
}
.hero p {
font-size: 16px;
}
.row {
grid-template-columns: 1fr;
}
}

139
document/development/risks/travel-risk-control-standard.md Normal file
View File

@@ -0,0 +1,139 @@
# 差旅报销风险管控标准（模拟版）
## 1. 目的
本标准用于约束个人报销中的差旅类单据审核，覆盖以下三类核心风险：
- 行程闭环风险：出发地、目的地、返程地之间是否形成合理链路。
- 票据地点一致性风险：酒店、交通票据与申报目的地是否一致。
- 差标超限风险：员工职级对应的交通舱位、火车席别、住宿金额是否超标。
本标准先以模拟规则落地到系统，用于 AI 验审与直属领导审批前的自动筛查。
## 2. 适用范围
- 报销主类型为 `travel / hotel / transport` 的单据。
- 或者明细附件识别出 `flight_itinerary / train_ticket / hotel_invoice / taxi_receipt / parking_toll_receipt` 的单据。
## 3. 基础定义
### 3.1 目的地
按以下优先级确定本次差旅的“主目的地”：
1. 用户在报销表单中填写的业务地点 `claim.location`
2. 长途交通票据终点城市
3. 酒店票据识别出的酒店所在城市
### 3.2 行程闭环
满足以下任一条件，视为形成合理闭环：
- 单程票据终点与申报目的地一致。
- 多段票据按时间顺序首尾衔接。
- 最后一段票据返回首段出发城市。
### 3.3 合理例外说明
若出现多城市出差、中转、改签、异地返程、展会高峰导致超标等情况，用户必须在报销事由或费用说明中体现原因。示例关键词：
- `中转`
- `转机`
- `经停`
- `改签`
- `多地出差`
- `客户临时变更`
- `展会高峰`
- `协议酒店满房`
- `无直达`
未说明时，系统按高风险处理并退回待补充。
## 4. 风险规则矩阵
### 4.1 行程闭环规则
- 若存在两段及以上长途交通票据，相邻两段的 `上一段终点城市` 与 `下一段起点城市` 必须一致。
- 若最终到达城市既不是申报目的地，也不是首段出发城市，则判定为高风险。
- 若识别到多个目的地城市，但事由中未说明多地出差、中转或改签原因，则判定为高风险。
处理方式：
- `高风险`：退回待补充。
- `中风险`：允许流转，但要求直属领导重点复核。
### 4.2 酒店地点一致性规则
- 酒店票据识别出的城市，必须属于以下集合之一：
- 申报目的地
- 长途交通票据中的目的地城市
- 长途交通票据中的返程前停留城市
- 若酒店城市与主目的地、交通链路均不一致，则判定为高风险。
处理方式：
- `高风险`：退回待补充，要求说明异地住宿原因或更换票据。
### 4.3 职级差旅标准
#### 4.3.1 城市分级
- 一线：`北京 / 上海 / 广州 / 深圳`
- 新一线 / 重点城市：`杭州 / 南京 / 苏州 / 武汉 / 成都 / 重庆 / 西安 / 天津 / 宁波 / 厦门 / 青岛 / 长沙`
- 其他城市：除以上外的默认城市
#### 4.3.2 住宿标准（元 / 晚）
| 职级带 | 一线 | 重点城市 | 其他城市 |
| --- | ---: | ---: | ---: |
| P1-P3 | 450 | 380 | 320 |
| P4-P5 | 550 | 480 | 380 |
| P6-P7 | 700 | 620 | 520 |
| M1-M2 | 900 | 820 | 720 |
| M3 及以上 / D 序列 | 1200 | 1000 | 900 |
说明：
- 若票据中能识别出 `X 晚 / X 间夜`，系统按 `总金额 / 间夜数` 计算每晚金额。
- 若无法识别间夜数，默认按 1 晚处理。
#### 4.3.3 交通标准
| 职级带 | 飞机 | 火车 / 高铁 |
| --- | --- | --- |
| P1-P3 | 经济舱 | 二等座 / 硬卧 |
| P4-P5 | 经济舱 | 二等座 / 硬卧 |
| P6-P7 | 超级经济舱及以下 | 一等座 / 软卧及以下 |
| M1-M2 | 商务舱及以下 | 商务座及以下 |
| M3 及以上 / D 序列 | 不做系统硬限制，仍保留人工复核 |
### 4.4 差标超限处理
- 超住宿标准且无说明：`高风险`
- 超住宿标准但有说明：`中风险`
- 飞机舱位或高铁席别超过职级标准且无说明：`高风险`
- 飞机舱位或高铁席别超过职级标准但有说明：`中风险`
## 5. 系统落地口径
### 5.1 票据识别字段
系统优先使用以下字段做判断：
- `route`
- `merchant_name`
- `amount`
- `date`
- OCR 原文中的舱位、席别、间夜数、城市名
### 5.2 AI 验审动作
- 高风险：提交前拦截，状态切回 `待补充`
- 中风险：允许进入直属领导审批，并附带风险标记
- 低风险 / 通过：正常流转
## 6. 当前实现边界
- 城市识别先按常见出差城市做匹配，未覆盖全国全部区县。
- 住宿标准与交通标准为模拟版，可后续迁移到任务规则中心做可配置化。
- 本文档为当前开发阶段的执行依据，后续若规则中心启用动态配置，应以规则中心版本为准。