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

feat(server): 扩展知识库服务，添加knowledge API端点和schema定义，前端新增knowledge服务模块

Browse Source
This commit is contained in:
caoxiaozhu
2026-05-15 06:56:17 +00:00
parent 7209c75ad8
commit 4b1dae7ebc
38 changed files with 774 additions and 8012 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

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

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

@@ -1,163 +0,0 @@
# 双 Agent 总体架构
## 1. 背景
X-Financial 后续需要同时支持两类智能化能力：
1. 用户主动发起的交互式流程操作。
2. 系统后台自动运行的定时巡检、统计、预警和知识维护。
如果用一个万能 Agent 同时处理这两类任务，风险会很高：
- 用户流程操作需要权限、确认、上下文追问。
- 定时巡检需要稳定批处理、失败重试、审计记录。
- 财务系统不能让大模型直接决定审批、付款、规则上线。
因此建议建设双 Agent 架构：
```text
Hermes Agent
后台数字员工
面向系统内循环
定时、批量、巡检、统计、预警、知识候选
User Agent
自建用户流程助手
面向用户交互
查询、解释、创建草稿、流程操作、审批辅助
```
两套 Agent 共享一套语义本体协议，由 Agent Orchestrator 统一调度。
## 2. 总体架构图
```text
┌──────────────────────┐
│ 用户自然语言 / 定时任务 │
└───────────┬──────────┘
│
▼
┌──────────────────────┐
│ Semantic Ontology │
│ 语义本体解析层 │
└───────────┬──────────┘
│
▼
┌──────────────────────┐
│ Agent Orchestrator │
│ 路由 / 权限 / 审计 / 调度 │
└───────┬─────────┬────┘
│ │
┌─────────────▼─┐ ┌─▼──────────────┐
│ Hermes Agent │ │ User Agent │
│ 后台数字员工 │ │ 用户流程助手 │
└───────┬───────┘ └───────┬────────┘
│ │
└──────────┬──────────┘
│
┌────────────┬───────────┼───────────┬────────────┐
▼ ▼ ▼ ▼ ▼
规则中心 MCP 服务 业务数据库 知识库 任务系统
```
## 3. 核心分层
### 3.1 语义本体层
负责把自然语言或任务配置转成结构化 JSON。
输出不是最终答案，而是统一协议：
```json
{
"domain": "reimbursement",
"scenario": "invoice_validation",
"intent": "explain_risk",
"entities": [],
"time_range": {},
"constraints": {},
"risk_signals": [],
"next_step": "run_rule"
}
```
### 3.2 编排层
Agent Orchestrator 负责：
- 判断应该由 Hermes 还是 User Agent 处理。
- 判断是否需要查数据库、跑规则、调 MCP、检索知识库。
- 检查用户权限。
- 记录审计日志。
- 控制失败重试。
- 对高风险动作要求用户或管理员确认。
### 3.3 Agent 层
Hermes 和 User Agent 不直接决定财务关键状态。
它们负责：
- 理解任务。
- 组织工具调用。
- 汇总工具结果。
- 生成建议、解释、报告、草稿。
### 3.4 能力层
能力层包括：
- 规则中心：管理 `.md` 规则文件、审核、版本。
- MCP：封装外部服务，如发票验真、银行流水、OCR、差旅平台。
- 数据库查询：查询报销、报账、应收、应付、账款数据。
- 知识库：制度文档、FAQ、历史解释、规则说明。
- 任务系统：定时任务、批量任务、重试、运行日志。
## 4. 关键边界
Hermes 可以：
- 定时读取数据。
- 执行规则检查。
- 调 MCP 查询外部状态。
- 生成风险报告。
- 生成知识候选。
- 生成待处理工单。
Hermes 不可以：
- 自动提交报销。
- 自动发起付款。
- 自动审批通过。
- 自动发布知识库正式内容。
- 自动上线规则。
User Agent 可以：
- 帮用户查询状态。
- 帮用户解释风险。
- 帮用户创建报销或付款草稿。
- 帮审批人生成审批意见。
- 在用户确认后调用流程 API。
User Agent 不可以：
- 绕过权限。
- 未确认直接提交关键动作。
- 自动最终审批。
- 自动付款。
- 修改规则审核状态。
## 5. 推荐建设顺序
```text
Step 1: 建立语义本体 JSON 协议
Step 2: 建立规则中心的规则/技能/MCP/任务目录
Step 3: 建立 Orchestrator 路由和审计
Step 4: 建立 User Agent 的只读查询和解释能力
Step 5: 建立 Hermes 的定时任务和报告能力
Step 6: 接入 MCP 和业务数据库
Step 7: 增加用户确认后的流程写入能力
Step 8: 增加知识候选和规则优化闭环
```

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

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

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

@@ -1,178 +0,0 @@
# Hermes 与自建 Agent 职责边界
## 1. 两套 Agent 的定位
### 1.1 Hermes
Hermes 定位为后台数字员工。
它不直接面向用户聊天，而是在系统后台做内循环工作。
关键词：
```text
定时
批量
巡检
统计
预警
知识维护
规则质量复盘
```
### 1.2 自建 Agent
自建 Agent 定位为用户流程助手。
它直接面对员工、财务人员、审批人和管理员。
关键词：
```text
用户触发
会话式
流程操作
查询解释
草稿生成
审批辅助
用户确认
```
## 2. Hermes 职责
Hermes 负责：
1. 每日风险巡检。
2. 每日报销、报账、账款统计。
3. 应收逾期预警。
4. 应付付款风险预警。
5. 规则命中质量复盘。
6. MCP 健康检查。
7. 知识库候选内容生成。
8. 高风险工单生成。
9. 任务运行报告生成。
Hermes 输出的内容包括：
```text
risk_report
risk_work_items
daily_finance_snapshot
knowledge_candidates
rule_improvement_items
mcp_health_report
task_run_log
```
Hermes 不允许：
1. 自动审批通过。
2. 自动发起付款。
3. 自动提交用户申请。
4. 自动发布正式知识库。
5. 自动上线规则。
6. 直接修改核心财务状态。
## 3. 自建 Agent 职责
自建 Agent 负责：
1. 查询报销单进度。
2. 创建报销或付款草稿。
3. 解释规则拦截原因。
4. 生成审批意见。
5. 检索制度知识。
6. 查询应收应付数据。
7. 帮用户对账。
8. 引导用户补充缺失信息。
9. 在用户确认后调用流程 API。
自建 Agent 输出的内容包括：
```text
natural_language_answer
form_draft
approval_opinion_draft
clarification_question
query_result_summary
next_action_suggestion
```
自建 Agent 不允许：
1. 未经用户确认提交关键动作。
2. 跳过权限校验。
3. 自动最终审批。
4. 自动付款。
5. 修改规则上线状态。
## 4. 权限边界
| 动作 | Hermes | 自建 Agent |
|---|---|---|
| 查询制度知识 | 可以 | 可以 |
| 查询业务数据 | 可以，按任务权限 | 可以，按用户权限 |
| 跑规则 | 可以 | 可以 |
| 调 MCP | 可以 | 可以 |
| 生成报告 | 可以 | 可以 |
| 生成草稿 | 不建议 | 可以 |
| 提交流程 | 不可以 | 用户确认后可以 |
| 审批通过 | 不可以 | 不可以直接做 |
| 发起付款 | 不可以 | 高权限确认后才可做草稿 |
| 发布知识 | 不可以 | 不可以 |
| 上线规则 | 不可以 | 不可以 |
## 5. 共享能力
两套 Agent 共享：
- 语义本体协议。
- 规则中心。
- MCP 服务。
- 知识库。
- 数据库查询服务。
- 审计日志。
- 权限系统。
不共享：
- 运行队列。
- 调度策略。
- 用户会话状态。
- 任务重试状态。
## 6. 示例
### 6.1 Hermes 场景
每日 02:00 自动运行：
```text
每日风险巡检
读取昨日报销、报账、发票、账款数据
执行规则
调用发票验真 MCP
调用账款流水 MCP
生成风险报告
生成风险工单
```
### 6.2 自建 Agent 场景
用户问：
```text
帮我看一下这张差旅报销为什么没通过。
```
处理：
```text
解析语义
查询报销单
读取规则命中
检索制度条款
组织解释
给出补件建议
```

357
document/development/agent plan/04_orchestrator_and_runtime_flow.md
View File

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

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

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

433
document/development/agent plan/06_data_contracts_and_governance.md
View File

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

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

@@ -1,198 +0,0 @@
# Capability Registry 能力注册中心
## 1. 为什么需要能力注册中心
双 Agent 架构里会出现很多能力：
- 规则文件。
- 技能。
- MCP 服务。
- 数据库查询。
- 知识库检索。
- 定时任务。
- 报告生成。
如果 Orchestrator 直接在代码里硬编码这些能力，会导致：
- 能力越来越多后难维护。
- 无法统一权限。
- 无法统一版本。
- 无法统一输入输出格式。
- Hermes 和 User Agent 复用困难。
因此建议建立 Capability Registry。
它的定位是：
```text
所有可被 Agent 调用的能力目录
```
## 2. 能力类型
建议第一版支持：
```text
rule
skill
mcp
task
database_query
knowledge_search
report_generator
notification
```
含义：
- `rule`：审查规则，通常是 `.md` 文件或规则配置。
- `skill`：智能能力，如审批意见生成、风险解释。
- `mcp`：外部服务连接。
- `task`：定时或批量任务。
- `database_query`：受控数据库查询能力。
- `knowledge_search`：知识库检索能力。
- `report_generator`：报告生成能力。
- `notification`：通知能力。
## 3. 能力注册结构
建议结构：
```json
{
"id": "cap_rule_duplicate_invoice",
"code": "duplicate_invoice_rule",
"name": "重复报销识别规则",
"capability_type": "rule",
"domain": "reimbursement",
"scenarios": ["invoice_validation", "reimbursement_audit"],
"intents": ["validate", "explain", "monitor"],
"input_schema": {},
"output_schema": {},
"permission_required": ["reimbursement:read", "risk:write"],
"risk_level": "high",
"owner": "财务风控组",
"version": "v1.9",
"status": "active",
"requires_confirmation": false,
"created_at": "",
"updated_at": ""
}
```
## 4. 与语义本体的匹配关系
Orchestrator 根据 ontology_json 匹配能力。
示例：
```json
{
"domain": "reimbursement",
"scenario": "invoice_validation",
"intent": "explain",
"risk_signals": ["duplicate_invoice"],
"next_step": "run_rule"
}
```
可以匹配：
```text
重复报销识别规则
发票验真 MCP
风险解释技能
制度知识库检索
```
## 5. 能力匹配优先级
建议顺序：
```text
Step 1: next_step 决定能力大类
Step 2: domain 限定业务域
Step 3: scenario 限定场景
Step 4: risk_signals 匹配具体规则
Step 5: intent 匹配技能
Step 6: permission_required 校验权限
Step 7: status 必须 active
Step 8: version 使用当前上线版本
```
## 6. 数据表建议
```text
agent_capabilities
```
字段：
```text
id
code
name
capability_type
domain
scenario_json
intent_json
input_schema_json
output_schema_json
permission_json
risk_level
owner
current_version
status
requires_confirmation
config_json
created_at
updated_at
```
## 7. 开发步骤
### Step 1: 先注册静态能力
先把现有规则、技能、MCP、任务写入 Registry。
不需要一开始做复杂 UI。
### Step 2: Orchestrator 改为查 Registry
从：
```text
if next_step = run_rule then call duplicate_invoice_rule
```
改为：
```text
query capabilities where type = rule and scenario = invoice_validation
```
### Step 3: 加权限过滤
只返回当前用户或任务有权限调用的能力。
### Step 4: 加版本选择
默认使用 active 版本。
历史版本只用于回放和调试。
### Step 5: 加健康状态
MCP、任务、数据库查询能力应有健康状态。
不可用时 Orchestrator 走降级策略。
## 8. 治理要求
- 所有能力必须有 owner。
- 高风险能力必须有 reviewer。
- 所有能力必须有输入输出 schema。
- 所有能力必须有状态。
- 下线能力不能被 Orchestrator 调用。
- 能力版本变更必须写入审计。

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

@@ -1,214 +0,0 @@
# 权限与确认引擎
## 1. 目标
Agent 不能只靠提示词判断能不能执行动作。
财务系统需要独立的权限与确认引擎：
```text
Permission Engine
Confirmation Engine
```
它们负责：
- 判断用户是否能看某类数据。
- 判断任务是否能调用某个能力。
- 判断动作是否需要确认。
- 判断动作是否禁止自动执行。
## 2. 动作风险分级
建议按 L0-L5 分级。
### L0 只读查询
例子：
- 查询制度。
- 查询单据状态。
- 查询规则说明。
- 查询任务运行记录。
要求：
- 需要权限。
- 不需要确认。
### L1 生成建议
例子：
- 生成审批意见建议。
- 生成风险解释。
- 生成规则优化建议。
要求：
- 需要权限。
- 不写业务状态。
- 不需要确认，但要标记为建议。
### L2 生成草稿
例子：
- 生成报销草稿。
- 生成付款申请草稿。
- 生成知识库候选。
要求：
- 需要权限。
- 写入草稿区。
- 不进入正式流程。
### L3 用户确认后提交
例子：
- 用户确认后提交报销。
- 审批人确认后写入审批意见。
- 用户确认后发起补件。
要求：
- 必须二次确认。
- 必须记录确认人。
- 必须记录确认前后内容。
### L4 管理员确认后发布
例子：
- 发布规则。
- 发布知识库。
- 启用 MCP。
- 启用任务。
要求：
- 必须管理员确认。
- 必须有审核记录。
- 必须有版本。
### L5 禁止自动执行
例子：
- 自动最终审批。
- 自动付款。
- 自动绕过风控。
- 自动修改核心财务状态。
要求：
- Agent 永远不能直接执行。
## 3. 权限判断输入
```json
{
"user_id": "emp_001",
"agent": "user_agent",
"source": "user_message",
"action": "create_reimbursement_draft",
"domain": "reimbursement",
"resource": {
"type": "reimbursement_request",
"id": ""
},
"capability": "travel_reimbursement_create"
}
```
## 4. 权限判断输出
```json
{
"allowed": true,
"risk_level": "L2",
"requires_confirmation": false,
"reason": "",
"permission_scope": {
"departments": ["current_user"],
"data_masking": false
}
}
```
## 5. 确认弹窗策略
需要确认的动作必须显示：
- 动作名称。
- 影响对象。
- 关键字段。
- 执行后果。
- 是否可撤销。
- 确认人。
示例：
```json
{
"title": "确认提交报销申请",
"action": "submit_reimbursement",
"summary": "将提交差旅报销单 TR-202605001，金额 ¥3,280。",
"risk_level": "L3",
"confirm_button": "确认提交"
}
```
## 6. Hermes 权限
Hermes 使用服务账号，不使用个人账号。
建议拆分权限：
```text
hermes:risk_scan
hermes:finance_statistics
hermes:knowledge_candidate
hermes:mcp_health_check
```
Hermes 默认只允许：
- 读脱敏快照。
- 跑规则。
- 调只读 MCP。
- 写报告、候选、工单。
Hermes 不允许：
- 写正式审批状态。
- 写正式付款状态。
- 发布规则。
- 发布知识。
## 7. User Agent 权限
User Agent 继承当前用户权限。
例如：
- 员工只能看自己的报销。
- 部门负责人可以看本部门。
- 财务可以看授权范围内数据。
- 管理员可以管理规则、任务、MCP。
User Agent 不能扩大用户权限。
## 8. 开发步骤
```text
Step 1: 定义 action risk level
Step 2: 建立 Permission Engine 接口
Step 3: 所有工具调用前接入权限判断
Step 4: L3/L4 动作接入确认弹窗
Step 5: 审计记录确认内容
Step 6: 增加权限测试用例
```

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

@@ -1,186 +0,0 @@
# 可观测性与 Agent Run Trace
## 1. 目标
Agent 系统必须可追踪、可回放、可解释。
财务系统中尤其需要回答：
- 为什么 Agent 得出这个结论？
- 用了哪个模型？
- 用了哪个规则版本？
- 调用了哪些 MCP？
- 查了哪些数据？
- 谁确认了动作？
- 失败在哪里？
## 2. Agent Run Trace
每次 Agent 运行都生成一个 run_id。
建议结构：
```json
{
"run_id": "",
"source": "user_message",
"agent": "user_agent",
"user_id": "emp_001",
"raw_input": "",
"ontology_json": {},
"route_decision": {},
"permission_result": {},
"tool_calls": [],
"final_output": "",
"status": "success",
"started_at": "",
"finished_at": ""
}
```
## 3. 需要记录的版本
每次运行都要记录：
```text
ontology_schema_version
semantic_parser_prompt_version
model_name
model_version
rule_version
skill_version
mcp_version
knowledge_snapshot_version
orchestrator_version
```
原因：
用户可能问：
```text
为什么昨天和今天的结论不一样？
```
只有记录版本，才能解释。
## 4. Tool Call Trace
每个工具调用都记录：
```json
{
"tool_call_id": "",
"run_id": "",
"tool_type": "mcp",
"tool_name": "invoice_verify",
"request_json": {},
"response_json": {},
"status": "success",
"duration_ms": 820,
"error_message": ""
}
```
敏感字段应脱敏。
## 5. 运行状态
建议枚举：
```text
pending
running
success
partial_success
failed
cancelled
waiting_confirmation
```
## 6. Hermes 可观测性
Hermes 任务需要额外记录：
```text
task_code
schedule_time
data_snapshot_id
records_scanned
rules_executed
mcp_calls
risk_items_generated
knowledge_candidates_generated
retry_count
```
示例：
```json
{
"task_code": "daily_risk_scan",
"records_scanned": 2146,
"rules_executed": 8,
"mcp_calls": 436,
"risk_items_generated": 19,
"status": "success"
}
```
## 7. User Agent 可观测性
User Agent 需要额外记录：
```text
conversation_id
page_context
user_confirmation
draft_created
business_object_id
```
## 8. 前端审计视图
建议后续增加“Agent 运行记录”页面。
展示：
- 运行时间。
- Agent 类型。
- 用户或任务。
- 语义解析结果。
- 调用工具。
- 运行状态。
- 耗时。
- 错误。
详情页展示：
- 原始输入。
- 本体 JSON。
- 路由决策。
- 工具调用链。
- 最终输出。
## 9. 告警
需要告警的情况：
- Hermes 任务连续失败。
- MCP 健康检查失败。
- 语义解析低置信度比例过高。
- 某规则误报率过高。
- Agent 调用耗时异常。
- 权限拒绝次数异常。
## 10. 开发步骤
```text
Step 1: 增加 agent_runs 表
Step 2: 增加 agent_tool_calls 表
Step 3: Orchestrator 每次执行创建 run_id
Step 4: 工具网关记录 tool call
Step 5: 前端增加运行记录页面
Step 6: 增加异常告警规则
```

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

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

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

@@ -1,376 +0,0 @@
# OCR 票据识别架构
## 1. 定位
OCR 票据识别不是一个简单的图片转文字功能。
它在 X-Financial 中承担四件事：
1. 把用户上传的附件变成结构化票据信息。
2. 为规则中心提供可判断的字段。
3. 为 User Agent 和 Hermes 提供可解释的证据。
4. 为后续审计、复核、争议处理保留可回溯原件。
因此 OCR 应作为独立能力纳入 Capability Registry。
```text
capability_type = mcp | document_processor
capability_code = invoice_ocr
```
## 2. 总体链路
```text
附件上传
↓
文件落盘 / 对象存储
↓
文件分类
↓
OCR 识别
↓
字段结构化
↓
票据类型归一化
↓
发票验真 MCP
↓
与报销明细匹配
↓
规则中心检查
↓
人工修正
↓
修正结果沉淀
```
关键原则：
- 文件先持久化，再做 OCR，不允许只在内存里跑完就丢。
- 原件不可覆盖，只能新增版本。
- Agent 不得假设图片内容已知；只有 OCR/VLM 实际解析后才能引用附件内容。
## 3. 阶段拆分
### Phase A：附件接入与文件分类
目标：先识别上传的是什么。
输入：
- 图片
- PDF
- Excel
- Word
- 压缩包
输出：
```json
{
"document_type": "invoice",
"mime_type": "image/png",
"page_count": 1,
"confidence": 0.91
}
```
分类结果：
```text
invoice
itinerary
contract
payment_receipt
approval_screenshot
other
```
### Phase B：OCR 字段提取
目标：从图片或 PDF 中提取票据字段。
结构：
```json
{
"invoice_code": "",
"invoice_number": "",
"seller_name": "",
"seller_tax_no": "",
"buyer_name": "",
"buyer_tax_no": "",
"issue_date": "",
"total_amount": 0,
"tax_amount": 0,
"currency": "CNY",
"ocr_confidence": 0.88
}
```
### Phase C：字段归一化
目标：不同 OCR 服务返回不同字段名，必须统一。
示例：
```text
发票号码 / invoiceNo / invoice_number
-> invoice_number
```
金额统一：
```json
{
"raw": "￥1,280.00",
"value": 1280.00,
"currency": "CNY"
}
```
### Phase D：验真与状态检查
调用发票验真 MCP。
输出：
```json
{
"verify_status": "verified",
"voided": false,
"red_reversed": false,
"verified_at": ""
}
```
### Phase E：与报销明细匹配
对比：
- 发票金额 vs 报销金额
- 开票日期 vs 费用日期
- 销售方 vs 商户
- 发票类型 vs 费用类型
输出：
```json
{
"match_status": "matched",
"mismatch_fields": [],
"match_confidence": 0.94
}
```
### Phase F：人工修正与回流
OCR 结果必须允许人工修正。
修正内容进入反馈池：
```json
{
"field": "invoice_number",
"before": "12345B",
"after": "123456",
"corrected_by": "finance_user",
"corrected_at": ""
}
```
## 4. 文件存储策略
### 4.1 为什么不能直接把文件塞进数据库
- 原始票据、合同、行程单体积大，数据库行膨胀明显。
- 预览件、缩略图、逐页图片、脱敏件都属于衍生文件，不适合和业务行混存。
- 财务原件需要版本留痕和不可变追溯，文件系统或对象存储更适合。
结论：
- 文件二进制存文件系统或对象存储。
- 数据库仅保存元数据、索引、版本、OCR 结果、验真结果、访问审计和业务关联。
### 4.2 开发环境目录方案
根目录使用后端配置中的 `STORAGE_ROOT_DIR`。
建议目录：
```text
<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 和验真接进来。
- 最后再做大规模自动巡检和脱敏导出。

148
document/development/agent plan/12_llm_wiki_knowledge_architecture.md
View File

@@ -1,148 +0,0 @@
# LLM Wiki 知识库架构
## 1. 定位
LLM Wiki 不是简单的文件库。
它是给 Agent 使用的知识底座，负责把制度、FAQ、审批经验、规则说明转成可检索、可引用、可版本化的知识。
## 2. 总体链路
```text
文档上传
↓
格式解析
↓
正文抽取
↓
分块 Chunking
↓
元数据标注
↓
向量索引
↓
条款抽取
↓
知识候选
↓
人工审核
↓
发布 Wiki
↓
Agent 检索引用
```
## 3. 知识类型
```text
policy_document
faq
rule_explanation
approval_case
risk_case
operation_manual
system_notice
```
## 4. 知识块结构
```json
{
"chunk_id": "",
"document_id": "",
"title": "",
"content": "",
"domain": "reimbursement",
"scenario": "travel_reimbursement",
"tags": ["差旅", "住宿标准"],
"effective_date": "",
"version": "v1.0",
"source_page": 4,
"embedding_id": "",
"status": "published"
}
```
## 5. 条款抽取
Hermes 可以从制度文档中抽取条款候选。
示例：
```json
{
"clause_type": "amount_limit",
"domain": "reimbursement",
"scenario": "travel_reimbursement",
"condition": {
"city_tier": "一线城市",
"employee_grade": "P5"
},
"limit": {
"amount": 800,
"currency": "CNY",
"period": "night"
},
"source": "差旅制度 2026 第 4 页"
}
```
该结果不直接变成规则，先进入规则候选池。
## 6. Wiki 发布流程
```text
草稿知识
↓
Hermes 生成候选
↓
知识管理员审核
↓
发布
↓
Agent 可检索
```
## 7. 与 User Agent 的关系
User Agent 用 Wiki：
- 回答制度问题。
- 给风险解释提供条款依据。
- 给审批意见生成引用。
- 帮用户理解流程。
## 8. 与 Hermes 的关系
Hermes 用 Wiki：
- 每日知识候选生成。
- 发现制度与规则不一致。
- 生成规则优化建议。
- 生成 FAQ 候选。
## 9. 数据模型建议
```text
knowledge_documents
knowledge_chunks
knowledge_embeddings
knowledge_candidates
knowledge_reviews
knowledge_versions
```
## 10. 开发阶段建议
```text
Step 1: 文档上传和文件管理
Step 2: 文本抽取和分块
Step 3: 元数据标注
Step 4: 向量索引
Step 5: 知识检索 API
Step 6: User Agent 问答引用
Step 7: Hermes 知识候选生成
Step 8: 人工审核发布
Step 9: 条款抽取和规则候选
```

126
document/development/agent plan/13_rule_formation_lifecycle.md
View File

@@ -1,126 +0,0 @@
# 规则形成生命周期
## 1. 定位
规则不是凭空写出来的。
它应来自：
- 制度文档。
- 历史审批。
- 风险案例。
- OCR 识别结果。
- MCP 验真结果。
- 用户反馈。
- Hermes 分析。
## 2. 总体闭环
```text
制度文档 / 历史审批 / 风险案例 / 用户反馈
↓
Hermes 分析
↓
规则候选
↓
人工审核
↓
规则 .md
↓
测试样例
↓
版本发布
↓
规则执行
↓
命中反馈
↓
规则优化
```
## 3. 规则候选结构
```json
{
"candidate_id": "",
"source_type": "policy_document",
"domain": "reimbursement",
"scenario": "invoice_validation",
"risk_signal": "duplicate_invoice",
"suggested_rule_name": "重复报销识别规则",
"rule_markdown_draft": "",
"evidence": [],
"confidence": 0.86,
"created_by": "hermes"
}
```
## 4. 规则 Markdown 推荐结构
```markdown
# 规则名称
## 目标
## 适用范围
## 输入字段
## 判断规则
## 输出
## 测试样例
## 管理员备注
```
## 5. 审核要求
规则上线必须满足：
- 有审核人。
- 有版本。
- 有测试样例。
- 有来源依据。
- 有回滚方案。
## 6. 规则执行反馈
每次规则运行应记录：
```text
rule_id
rule_version
input_snapshot
hit_result
risk_level
operator_feedback
false_positive
false_negative
```
## 7. 规则优化来源
```text
误报反馈
漏报反馈
审批人修改意见
Hermes 每日复盘
制度文档更新
MCP 新字段可用
```
## 8. 开发阶段建议
```text
Step 1: 规则 .md 编辑和版本
Step 2: 规则审核上线
Step 3: 规则运行日志
Step 4: 人工反馈误报/漏报
Step 5: Hermes 生成规则候选
Step 6: 规则候选审核
Step 7: 规则测试样例管理
Step 8: 规则质量看板
```

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

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

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

@@ -1,119 +0,0 @@
# 反馈闭环与持续学习
## 1. 定位
Agent 系统必须能从人工反馈中持续变好。
反馈来源：
- OCR 人工修正。
- 规则误报/漏报。
- 审批人修改意见。
- 用户对回答的反馈。
- Hermes 风险复盘。
- MCP 调用失败和降级。
## 2. 反馈类型
```text
ocr_correction
rule_false_positive
rule_false_negative
agent_answer_feedback
approval_opinion_edit
knowledge_answer_feedback
mcp_failure_feedback
task_result_feedback
```
## 3. 反馈结构
```json
{
"feedback_id": "",
"feedback_type": "rule_false_positive",
"source_object_type": "rule_run",
"source_object_id": "",
"before": {},
"after": {},
"comment": "",
"created_by": "",
"created_at": ""
}
```
## 4. 反馈流向
```text
人工反馈
↓
反馈池
↓
Hermes 聚类分析
↓
候选改进项
↓
人工审核
↓
更新规则 / 知识 / OCR 映射 / Prompt
```
## 5. 反馈不直接自动生效
反馈只能生成候选，不直接修改线上规则。
必须人工审核：
- 规则修改。
- 知识发布。
- Prompt 修改。
- OCR 字段映射调整。
## 6. Hermes 每日反馈复盘
Hermes 每日任务：
```text
读取昨日反馈
聚类相似问题
统计误报高发规则
统计低评分回答
生成优化候选
```
输出：
```text
rule_improvement_candidates
knowledge_update_candidates
ocr_mapping_candidates
prompt_improvement_notes
```
## 7. 质量指标
建议监控：
```text
ocr_correction_rate
rule_false_positive_rate
rule_false_negative_rate
agent_answer_like_rate
agent_answer_rewrite_rate
knowledge_no_hit_rate
mcp_failure_rate
```
## 8. 开发阶段建议
```text
Step 1: 增加反馈按钮和反馈表
Step 2: OCR 修正写入反馈池
Step 3: 规则误报/漏报反馈
Step 4: Agent 回答反馈
Step 5: Hermes 每日反馈聚类
Step 6: 生成优化候选
Step 7: 人工审核发布
Step 8: 建立质量看板
```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

230
document/development/agent week plan/day_6_hermes_mvp.md
View File

@@ -1,230 +0,0 @@
# Day 6：Hermes MVP
## 今天的大开发点
实现 Hermes 数字员工的最小闭环。Hermes 负责后台内循环：定时巡检、统计日报、风险预警、知识维护、规则草稿形成。
## 为什么第六天做这个
Hermes 依赖前几天已经建立的资产、规则、语义、Orchestrator、Trace 和权限体系。放在第六天做，可以避免它变成孤立脚本。
## 今天主要交付
- 任务资产调度入口。
- 手动触发任务 API。
- 每日风险巡检。
- 每日报销、报账、账款统计。
- OCR Mock 接入点。
- 知识候选条目生成。
- 规则草稿生成。
- Hermes 运行结果展示。
相关架构文档：
- [Agent 职责边界](<../agent plan/03_agent_responsibilities.md>)
- [OCR 票据识别架构](<../agent plan/11_ocr_invoice_architecture.md>)
- [LLM Wiki 知识库架构](<../agent plan/12_llm_wiki_knowledge_architecture.md>)
- [反馈学习闭环](<../agent plan/15_feedback_learning_loop.md>)
## 当天验收门槛
- 至少一个 Hermes 任务可以手动触发。
- 风险巡检有结构化结果。
- 每日统计有结构化结果。
- OCR Mock 调用能记录 ToolCall。
- 知识候选只能是草稿。
- 规则草稿只能是 draft，不能自动上线。
## 今天不做
- 不做完整生产调度集群。
- 不做真实 OCR 深度集成。
- 不做自动发布知识。
- 不做自动上线规则。
## 详细执行清单
以下内容为合并后的详细执行清单。
## 0. 开始前检查
- [ ] 确认任务资产 `asset_type=task` 可查询。
- [ ] 确认 Orchestrator 能处理 `source=schedule`。
- [ ] 确认 Hermes 占位服务可被调用。
- [ ] 确认 AgentRun 和 ToolCall 可记录。
- [ ] 确认是否已有后台任务框架。
- [ ] 如果没有后台任务框架，先用手动触发 API 模拟定时执行。
## 1. Hermes 输入输出
- [ ] 定义 `HermesTaskRequest`。
- [ ] 请求包含 `run_id`。
- [ ] 请求包含 `task_asset_id`。
- [ ] 请求包含 `task_type`。
- [ ] 请求包含 `schedule_time`。
- [ ] 请求包含 `context_json`。
- [ ] 定义 `HermesTaskResult`。
- [ ] 响应包含 `summary`。
- [ ] 响应包含 `risk_items`。
- [ ] 响应包含 `statistics`。
- [ ] 响应包含 `knowledge_updates`。
- [ ] 响应包含 `draft_rules`。
- [ ] 响应包含 `next_actions`。
验收证据：
- [ ] Hermes 响应能被任务详情或运行日志展示。
## 2. 任务调度入口
- [ ] 新增手动触发任务 API。
- [ ] API 参数支持任务资产 ID。
- [ ] API 调用 Orchestrator，source 为 `schedule`。
- [ ] Orchestrator 路由到 Hermes。
- [ ] Hermes 执行结果写入 AgentRun。
- [ ] 任务执行失败时写入错误。
- [ ] 任务执行结束后更新任务最近执行时间。
- [ ] 任务执行结束后更新任务最近执行状态。
验收证据：
- [ ] 可以手动触发一次 Hermes 任务并看到运行结果。
## 3. 每日风险巡检
- [ ] 实现重复报销巡检。
- [ ] 实现金额超标巡检。
- [ ] 实现发票异常巡检占位。
- [ ] 实现应收逾期巡检。
- [ ] 实现应付异常付款巡检。
- [ ] 每个风险项包含风险类型。
- [ ] 每个风险项包含业务对象。
- [ ] 每个风险项包含触发规则。
- [ ] 每个风险项包含建议动作。
- [ ] 每个风险项包含风险等级。
验收证据：
- [ ] 风险巡检结果可以被用户理解和追溯。
## 4. 每日统计
- [ ] 统计当日报销单数量。
- [ ] 统计当日报销金额。
- [ ] 统计当日报账数量。
- [ ] 统计当日报账金额。
- [ ] 统计应收新增金额。
- [ ] 统计应收逾期金额。
- [ ] 统计应付待付金额。
- [ ] 统计应付逾期金额。
- [ ] 输出日报摘要。
验收证据：
- [ ] Hermes 能生成一份每日财务摘要。
## 5. OCR 接入点
- [ ] 原始票据先落 `document_assets` 和 `document_asset_versions`，不直接以内存临时文件参与流程。
- [ ] 建立 OCR 识别服务接口。
- [ ] 定义发票识别输入结构。
- [ ] 定义发票识别输出结构。
- [ ] 输出结构包含发票号。
- [ ] 输出结构包含开票日期。
- [ ] 输出结构包含金额。
- [ ] 输出结构包含税额。
- [ ] 输出结构包含销售方。
- [ ] 输出结构包含购买方。
- [ ] 输出结构包含置信度。
- [ ] OCR 输入可通过 `storage_key` 或等价文件定位字段读取原件。
- [ ] 当前阶段允许使用 Mock 结果。
- [ ] OCR 调用写入 ToolCall。
验收证据：
- [ ] Hermes 风险巡检中可以调用 OCR Mock。
## 6. 知识库维护
- [ ] 建立知识条目写入服务。
- [ ] Hermes 可以生成知识候选条目。
- [ ] 候选条目包含标题。
- [ ] 候选条目包含正文。
- [ ] 候选条目包含来源。
- [ ] 候选条目包含适用场景。
- [ ] 候选条目默认状态为 `draft`。
- [ ] 知识条目不能自动发布。
- [ ] 知识条目写入审计日志。
验收证据：
- [ ] Hermes 可以生成待审核知识条目。
## 7. 规则草稿形成
- [ ] Hermes 可以根据风险巡检结果生成规则草稿。
- [ ] 规则草稿保存为 `asset_type=rule`。
- [ ] 规则草稿状态为 `draft`。
- [ ] 规则草稿包含 Markdown 内容。
- [ ] 规则草稿包含生成原因。
- [ ] 规则草稿包含关联风险样例。
- [ ] 规则草稿不能自动上线。
- [ ] 规则草稿需要审核人。
- [ ] 规则草稿写入审计日志。
验收证据：
- [ ] Hermes 生成的新规则出现在规则列表中，但不是 active。
## 8. Hermes 页面或日志展示
- [ ] 任务详情能看到最近执行结果。
- [ ] 任务详情能手动触发执行。
- [ ] 任务详情能看到风险项数量。
- [ ] 任务详情能看到日报摘要。
- [ ] 任务详情能看到知识候选数量。
- [ ] 任务详情能看到规则草稿数量。
- [ ] 运行 Trace 能看到 Hermes 步骤。
- [ ] 错误时展示错误原因。
验收证据：
- [ ] 不查数据库也能判断 Hermes 是否执行成功。
## 9. 测试
- [ ] 测试手动触发任务。
- [ ] 测试 Orchestrator 路由到 Hermes。
- [ ] 测试风险巡检输出。
- [ ] 测试日报统计输出。
- [ ] 测试 OCR Mock 调用。
- [ ] 测试知识候选写入。
- [ ] 测试规则草稿生成。
- [ ] 测试 Hermes 异常写入 AgentRun。
验收证据：
- [ ] Hermes 核心测试通过。
## 10. Day 6 验收
- [ ] Hermes 可被 Orchestrator 调用。
- [ ] 至少一个任务可以手动触发。
- [ ] 风险巡检有结构化结果。
- [ ] 每日统计有结构化结果。
- [ ] OCR Mock 接入点可用。
- [ ] 知识候选可生成。
- [ ] 规则草稿可生成且不能自动上线。
- [ ] 任务详情或运行日志能展示结果。
- [ ] 所有完成项已用 `[x] ~~...~~` 标记。
## 阻塞记录
- [ ] 暂无。
## 日终交接
- [ ] 写明 Hermes 已支持任务类型。
- [ ] 写明 OCR 当前是真实还是 Mock。
- [ ] 写明生成的知识和规则草稿状态。
- [ ] 写明 Day 7 需要重点回归的路径。

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

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

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

@@ -1,137 +0,0 @@
<!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_week_plan_html/day-2.html
View File

@@ -1,132 +0,0 @@
<!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_week_plan_html/day-3.html
View File

@@ -1,132 +0,0 @@
<!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_week_plan_html/day-4.html
View File

@@ -1,133 +0,0 @@
<!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_week_plan_html/day-5.html
View File

@@ -1,133 +0,0 @@
<!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_week_plan_html/day-6.html
View File

@@ -1,133 +0,0 @@
<!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_week_plan_html/day-7.html
View File

@@ -1,132 +0,0 @@
<!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_week_plan_html/index.html
View File

@@ -1,181 +0,0 @@
<!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_week_plan_html/styles.css
View File

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

184
server/src/app/api/v1/endpoints/knowledge.py
View File

@@ -1,21 +1,33 @@
from __future__ import annotations
from datetime import UTC, datetime
from typing import Annotated
from fastapi import APIRouter, Body, Depends, HTTPException, Query, status
from fastapi.responses import FileResponse
from sqlalchemy import select
from sqlalchemy.orm import Session
from app.api.deps import CurrentUserContext, get_current_user, require_admin_user
from app.api.deps import CurrentUserContext, get_current_user, get_db, require_admin_user
from app.core.agent_enums import AgentName, AgentPermissionLevel, AgentRunSource, AgentRunStatus
from app.models.agent_asset import AgentAsset
from app.schemas.common import ErrorResponse
from app.schemas.knowledge import (
KnowledgeActionResponse,
KnowledgeDocumentDetailRead,
KnowledgeLibraryRead,
LlmWikiDocumentDetailRead,
LlmWikiIndexRead,
LlmWikiSummaryUpdateWrite,
KnowledgeOnlyOfficeCallbackRead,
KnowledgeOnlyOfficeCallbackWrite,
KnowledgeOnlyOfficeConfigRead,
LlmWikiSyncRead,
LlmWikiSyncWrite,
)
from app.services.agent_runs import AgentRunService
from app.services.knowledge import KnowledgeService
from app.services.llm_wiki import LlmWikiService
router = APIRouter(prefix="/knowledge")
@@ -38,6 +50,176 @@ def get_knowledge_library(
return KnowledgeService().list_library()
@router.get(
"/llm-wiki",
response_model=LlmWikiIndexRead,
summary="查询 LLM Wiki 索引",
description="返回知识库解析目录中的文档索引和同步次数，仅供管理员查看知识候选与规则候选草稿。",
responses={
status.HTTP_401_UNAUTHORIZED: {
"model": ErrorResponse,
"description": "未提供知识库访问用户头。",
},
status.HTTP_403_FORBIDDEN: {
"model": ErrorResponse,
"description": "只有管理员可以查看 LLM Wiki 草稿内容。",
},
},
)
def get_llm_wiki_index(
_: Annotated[CurrentUserContext, Depends(require_admin_user)],
db: Annotated[Session, Depends(get_db)],
) -> LlmWikiIndexRead:
return LlmWikiService(db).get_index()
@router.get(
"/llm-wiki/documents/{document_id}",
response_model=LlmWikiDocumentDetailRead,
summary="读取 LLM Wiki 文档解析结果",
description="返回指定知识文档的解析文本、分块、知识候选与规则候选，仅供管理员查看。",
responses={
status.HTTP_401_UNAUTHORIZED: {
"model": ErrorResponse,
"description": "未提供知识库访问用户头。",
},
status.HTTP_403_FORBIDDEN: {
"model": ErrorResponse,
"description": "只有管理员可以查看 LLM Wiki 草稿内容。",
},
status.HTTP_404_NOT_FOUND: {
"model": ErrorResponse,
"description": "指定文档尚未生成 LLM Wiki。",
},
},
)
def get_llm_wiki_document_detail(
document_id: str,
_: Annotated[CurrentUserContext, Depends(require_admin_user)],
db: Annotated[Session, Depends(get_db)],
) -> LlmWikiDocumentDetailRead:
try:
return LlmWikiService(db).get_document_detail(document_id)
except FileNotFoundError as exc:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="指定文档尚未生成 LLM Wiki。") from exc
@router.patch(
"/llm-wiki/documents/{document_id}",
response_model=LlmWikiDocumentDetailRead,
summary="更新 LLM Wiki 知识总结",
description="管理员可修改指定知识文档的 LLM Wiki 知识总结预览，不直接改动原始文件。",
responses={
status.HTTP_401_UNAUTHORIZED: {
"model": ErrorResponse,
"description": "未提供知识库访问用户头。",
},
status.HTTP_403_FORBIDDEN: {
"model": ErrorResponse,
"description": "只有管理员可以修改 LLM Wiki 草稿内容。",
},
status.HTTP_404_NOT_FOUND: {
"model": ErrorResponse,
"description": "指定文档尚未生成 LLM Wiki。",
},
},
)
def update_llm_wiki_document_summary(
document_id: str,
payload: LlmWikiSummaryUpdateWrite,
_: Annotated[CurrentUserContext, Depends(require_admin_user)],
db: Annotated[Session, Depends(get_db)],
) -> LlmWikiDocumentDetailRead:
try:
return LlmWikiService(db).update_document_summary(document_id, payload)
except FileNotFoundError as exc:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="指定文档尚未生成 LLM Wiki。") from exc
except ValueError as exc:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
@router.post(
"/llm-wiki/sync",
response_model=LlmWikiSyncRead,
summary="触发 Hermes 形成 LLM Wiki 与规则草稿",
description="按知识库文档变化情况增量触发系统 Hermes，形成知识候选和规则草稿。",
responses={
status.HTTP_401_UNAUTHORIZED: {
"model": ErrorResponse,
"description": "未提供知识库访问用户头。",
},
status.HTTP_403_FORBIDDEN: {
"model": ErrorResponse,
"description": "只有管理员可以触发 LLM Wiki 同步。",
},
},
)
def sync_llm_wiki(
payload: LlmWikiSyncWrite,
current_user: Annotated[CurrentUserContext, Depends(require_admin_user)],
db: Annotated[Session, Depends(get_db)],
) -> LlmWikiSyncRead:
run_service = AgentRunService(db)
task_asset = db.scalar(
select(AgentAsset).where(AgentAsset.code == "task.hermes.llm_wiki_rule_formation")
)
run = run_service.create_run(
agent=AgentName.HERMES.value,
source=AgentRunSource.SCHEDULE.value,
user_id=current_user.username,
task_id=task_asset.id if task_asset is not None else None,
permission_level=AgentPermissionLevel.READ.value,
status=AgentRunStatus.RUNNING.value,
result_summary="Hermes 正在形成 LLM Wiki 与规则草稿。",
)
try:
result = LlmWikiService(db).sync_folder(
folder=payload.folder,
current_user=current_user,
document_ids=payload.document_ids,
force=payload.force,
)
run_service.record_tool_call(
run_id=run.run_id,
tool_type="llm",
tool_name="system_hermes_llm_wiki_sync",
request_json=payload.model_dump(),
response_json=result.model_dump(),
status="succeeded",
duration_ms=0,
)
run_service.update_run(
run.run_id,
status=AgentRunStatus.SUCCEEDED.value,
result_summary=result.summary,
finished_at=datetime.now(UTC),
)
return result
except Exception as exc:
run_service.record_tool_call(
run_id=run.run_id,
tool_type="llm",
tool_name="system_hermes_llm_wiki_sync",
request_json=payload.model_dump(),
response_json={"error": str(exc)},
status="failed",
duration_ms=0,
error_message=str(exc),
)
run_service.update_run(
run.run_id,
status=AgentRunStatus.FAILED.value,
error_message=str(exc),
finished_at=datetime.now(UTC),
)
if isinstance(exc, ValueError):
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
if isinstance(exc, FileNotFoundError):
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(exc)) from exc
@router.get(
"/documents/{document_id}",
response_model=KnowledgeDocumentDetailRead,

134
server/src/app/schemas/knowledge.py
View File

@@ -1,5 +1,6 @@
from __future__ import annotations
from __future__ import annotations
from datetime import datetime
from typing import Any
from pydantic import BaseModel, ConfigDict, Field
@@ -28,17 +29,18 @@ class KnowledgePreviewPageRead(BaseModel):
blocks: list[KnowledgePreviewBlockRead] = Field(default_factory=list)
class KnowledgeDocumentRead(BaseModel):
id: str
name: str
folder: str
tag: str
time: str
version: str
state: str
stateTone: str
owner: str
icon: str
class KnowledgeDocumentRead(BaseModel):
id: str
name: str
folder: str
tag: str
time: str
version: str
stateCode: int = 1
state: str
stateTone: str
owner: str
icon: str
fileType: str
fileTypeLabel: str
summary: str
@@ -75,6 +77,106 @@ class KnowledgeLibraryRead(BaseModel):
documents: list[KnowledgeDocumentRead] = Field(default_factory=list)
class KnowledgeActionResponse(BaseModel):
ok: bool = True
detail: str
class KnowledgeActionResponse(BaseModel):
ok: bool = True
detail: str
class LlmWikiChunkRead(BaseModel):
chunk_id: str
title: str
content: str
source_page: int | None = None
word_count: int = 0
tags: list[str] = Field(default_factory=list)
class LlmWikiKnowledgeCandidateRead(BaseModel):
candidate_id: str
title: str
content: str
domain: str = "expense"
scenario: str = "reimbursement_policy"
tags: list[str] = Field(default_factory=list)
source_document_id: str
source_document_name: str
source_chunk_ids: list[str] = Field(default_factory=list)
evidence: list[str] = Field(default_factory=list)
confidence: float = 0.0
status: str = "draft"
created_by: str = "hermes"
created_at: datetime | None = None
class LlmWikiRuleCandidateRead(BaseModel):
candidate_id: str
source_type: str = "policy_document"
template_key: str
template_label: str
domain: str = "expense"
scenario: str = "reimbursement_policy"
suggested_rule_name: str
summary: str = ""
template_sections: dict[str, Any] = Field(default_factory=dict)
rule_markdown_draft: str
runtime_rule: dict[str, Any] = Field(default_factory=dict)
evidence: list[str] = Field(default_factory=list)
confidence: float = 0.0
source_document_id: str
source_document_name: str
source_chunk_ids: list[str] = Field(default_factory=list)
generated_asset_id: str | None = None
generated_asset_code: str | None = None
generated_version: str | None = None
validation_status: str = "valid"
validation_errors: list[str] = Field(default_factory=list)
status: str = "draft"
created_by: str = "hermes"
created_at: datetime | None = None
class LlmWikiDocumentRead(BaseModel):
document_id: str
document_name: str
folder: str
document_version: str = "v1.0"
checksum: str = ""
extracted_text_path: str
chunk_count: int = 0
knowledge_candidate_count: int = 0
rule_candidate_count: int = 0
updated_at: datetime | None = None
class LlmWikiDocumentDetailRead(LlmWikiDocumentRead):
knowledge_summary_markdown: str = ""
chunks: list[LlmWikiChunkRead] = Field(default_factory=list)
knowledge_candidates: list[LlmWikiKnowledgeCandidateRead] = Field(default_factory=list)
rule_candidates: list[LlmWikiRuleCandidateRead] = Field(default_factory=list)
class LlmWikiIndexRead(BaseModel):
documents: list[LlmWikiDocumentRead] = Field(default_factory=list)
sync_run_count: int = 0
class LlmWikiSyncWrite(BaseModel):
folder: str = Field(default="报销制度", min_length=1)
document_ids: list[str] = Field(default_factory=list)
force: bool = False
class LlmWikiSyncRead(BaseModel):
ok: bool = True
run_id: str
folder: str
document_count: int = 0
knowledge_candidate_count: int = 0
rule_candidate_count: int = 0
generated_rule_count: int = 0
generated_rule_asset_ids: list[str] = Field(default_factory=list)
summary: str = ""
class LlmWikiSummaryUpdateWrite(BaseModel):
knowledge_summary_markdown: str = Field(min_length=1)

561
server/src/app/services/knowledge.py
View File

@@ -1,13 +1,15 @@
from __future__ import annotations
import hashlib
import json
import mimetypes
import re
from dataclasses import dataclass
from datetime import UTC, datetime
from pathlib import Path
from typing import Any
import hashlib
import json
import mimetypes
import re
import shutil
import subprocess
from dataclasses import dataclass
from datetime import UTC, datetime
from pathlib import Path
from typing import Any
from urllib.request import Request, urlopen
from uuid import uuid4
from xml.etree import ElementTree
@@ -16,8 +18,8 @@ from zipfile import BadZipFile, ZipFile
import jwt
from app.api.deps import CurrentUserContext
from app.core.config import get_settings
from app.core.logging import get_logger
from app.core.config import get_settings
from app.core.logging import get_logger
from app.schemas.knowledge import (
KnowledgeDocumentDetailRead,
KnowledgeDocumentRead,
@@ -64,7 +66,20 @@ IMAGE_EXTENSIONS = {"png", "jpg", "jpeg", "gif", "bmp", "webp", "svg"}
ARCHIVE_EXTENSIONS = {"zip", "rar", "7z"}
STRUCTURED_PREVIEW_EXTENSIONS = {"docx", "xlsx", "pptx"} | TEXT_EXTENSIONS
INLINE_PREVIEW_EXTENSIONS = {"pdf"} | IMAGE_EXTENSIONS
ONLYOFFICE_EDITABLE_EXTENSIONS = {"docx", "xlsx", "pptx"}
ONLYOFFICE_EDITABLE_EXTENSIONS = {"docx", "xlsx", "pptx"}
KNOWLEDGE_INGEST_SYNC_STALE_SECONDS = 90
KNOWLEDGE_INGEST_STATUS_PUBLISHED = 1
KNOWLEDGE_INGEST_STATUS_SYNCING = 2
KNOWLEDGE_INGEST_STATUS_INGESTED = 3
KNOWLEDGE_INGEST_STATUS_FAILED = 4
KNOWLEDGE_INGEST_STATUS_META = {
KNOWLEDGE_INGEST_STATUS_PUBLISHED: ("待归纳", "muted"),
KNOWLEDGE_INGEST_STATUS_SYNCING: ("正归纳", "warning"),
KNOWLEDGE_INGEST_STATUS_INGESTED: ("已归纳", "success"),
KNOWLEDGE_INGEST_STATUS_FAILED: ("归纳失败", "danger"),
}
@dataclass(slots=True)
@@ -78,24 +93,40 @@ def prepare_knowledge_library() -> None:
KnowledgeService().ensure_library_ready()
class KnowledgeService:
def __init__(self, storage_root: Path | None = None) -> None:
settings = get_settings()
self.storage_root = Path(storage_root or settings.resolved_storage_root_dir)
self.library_root = self.storage_root / "knowledge"
self.index_path = self.library_root / ".index.json"
def ensure_library_ready(self) -> None:
self.library_root.mkdir(parents=True, exist_ok=True)
for folder_name in FIXED_KNOWLEDGE_FOLDERS:
(self.library_root / folder_name).mkdir(parents=True, exist_ok=True)
if not self.index_path.exists():
self._save_index({"version": 1, "documents": []})
index = self._load_index()
if self._reconcile_index(index):
self._save_index(index)
class KnowledgeService:
def __init__(self, storage_root: Path | None = None) -> None:
settings = get_settings()
self.storage_root = Path(storage_root or settings.resolved_storage_root_dir)
self.library_root = self.storage_root / "knowledge"
self.index_path = self.library_root / ".index.json"
self.llm_wiki_root = self.library_root / ".llm_wiki"
self.llm_wiki_documents_root = self.llm_wiki_root / "documents"
self.llm_wiki_index_path = self.llm_wiki_root / "index.json"
self.llm_wiki_sync_runs_path = self.llm_wiki_root / "sync_runs.json"
def ensure_library_ready(self) -> None:
self.library_root.mkdir(parents=True, exist_ok=True)
for folder_name in FIXED_KNOWLEDGE_FOLDERS:
(self.library_root / folder_name).mkdir(parents=True, exist_ok=True)
self.llm_wiki_documents_root.mkdir(parents=True, exist_ok=True)
if not self.index_path.exists():
self._save_index({"version": 1, "documents": []})
if not self.llm_wiki_index_path.exists():
self.llm_wiki_index_path.write_text(
json.dumps({"documents": []}, ensure_ascii=False, indent=2),
encoding="utf-8",
)
if not self.llm_wiki_sync_runs_path.exists():
self.llm_wiki_sync_runs_path.write_text(
json.dumps({"runs": []}, ensure_ascii=False, indent=2),
encoding="utf-8",
)
index = self._load_index()
if self._reconcile_index(index):
self._save_index(index)
def list_library(self) -> KnowledgeLibraryRead:
documents = self._load_documents()
@@ -109,21 +140,23 @@ class KnowledgeService:
]
return KnowledgeLibraryRead(folders=folders, documents=documents)
def get_document_detail(self, document_id: str) -> KnowledgeDocumentDetailRead:
self.ensure_library_ready()
index = self._load_index()
entry = self._require_entry(index, document_id)
preview_kind, preview_pages = self._build_preview(entry)
document = self._serialize_document(entry)
def get_document_detail(self, document_id: str) -> KnowledgeDocumentDetailRead:
self.ensure_library_ready()
index = self._load_index()
if self._reconcile_document_ingest_statuses(index, document_ids=[document_id]):
self._save_index(index)
entry = self._require_entry(index, document_id)
preview_kind, preview_pages = self._build_preview(entry)
document = self._serialize_document(entry)
return KnowledgeDocumentDetailRead(
**document.model_dump(),
previewKind=preview_kind,
previewPages=preview_pages,
)
def upload_document(
self,
folder: str,
def upload_document(
self,
folder: str,
filename: str,
content: bytes,
current_user: CurrentUserContext,
@@ -162,22 +195,23 @@ class KnowledgeService:
checksum = hashlib.sha256(content).hexdigest()
extension = self._extract_extension(normalized_name)
if existing_entry is None:
entry = {
"id": document_id,
"folder": normalized_folder,
"original_name": normalized_name,
if existing_entry is None:
entry = {
"id": document_id,
"folder": normalized_folder,
"original_name": normalized_name,
"stored_name": stored_name,
"mime_type": mime_type,
"extension": extension,
"size_bytes": len(content),
"sha256": checksum,
"created_at": now,
"updated_at": now,
"uploaded_by": current_user.name,
"version_number": 1,
}
index["documents"].append(entry)
"created_at": now,
"updated_at": now,
"uploaded_by": current_user.name,
"version_number": 1,
"ingest_status": KNOWLEDGE_INGEST_STATUS_PUBLISHED,
}
index["documents"].append(entry)
logger.info(
"Knowledge document uploaded id=%s folder=%s filename=%s by=%s",
document_id,
@@ -193,12 +227,13 @@ class KnowledgeService:
"extension": extension,
"size_bytes": len(content),
"sha256": checksum,
"updated_at": now,
"uploaded_by": current_user.name,
"version_number": int(existing_entry.get("version_number", 1)) + 1,
}
)
entry = existing_entry
"updated_at": now,
"uploaded_by": current_user.name,
"version_number": int(existing_entry.get("version_number", 1)) + 1,
"ingest_status": KNOWLEDGE_INGEST_STATUS_PUBLISHED,
}
)
entry = existing_entry
logger.info(
"Knowledge document updated id=%s folder=%s filename=%s by=%s",
document_id,
@@ -222,16 +257,86 @@ class KnowledgeService:
self._save_index(index)
logger.info("Knowledge document deleted id=%s filename=%s", document_id, entry["original_name"])
def get_document_content(self, document_id: str) -> tuple[Path, str, str]:
self.ensure_library_ready()
index = self._load_index()
entry = self._require_entry(index, document_id)
def get_document_content(self, document_id: str) -> tuple[Path, str, str]:
self.ensure_library_ready()
index = self._load_index()
entry = self._require_entry(index, document_id)
file_path = self._resolve_document_path(entry)
if not file_path.exists():
raise FileNotFoundError(entry["original_name"])
return file_path, entry["mime_type"], entry["original_name"]
return file_path, entry["mime_type"], entry["original_name"]
def list_folder_documents(self, folder: str | None = None) -> list[dict[str, Any]]:
self.ensure_library_ready()
index = self._load_index()
if self._reconcile_document_ingest_statuses(index):
self._save_index(index)
documents = list(index.get("documents") or [])
if folder is None:
return documents
normalized_folder = self._normalize_folder(folder)
return [item for item in documents if item.get("folder") == normalized_folder]
def get_document_entry(self, document_id: str) -> dict[str, Any]:
self.ensure_library_ready()
index = self._load_index()
if self._reconcile_document_ingest_statuses(index, document_ids=[document_id]):
self._save_index(index)
return dict(self._require_entry(index, document_id))
def set_document_ingest_statuses(self, document_ids: list[str], status_code: int) -> None:
self.ensure_library_ready()
normalized_ids = {str(item).strip() for item in document_ids if str(item).strip()}
if not normalized_ids:
return
index = self._load_index()
changed = False
updated_at = datetime.now(UTC).isoformat()
for entry in index.get("documents", []):
if str(entry.get("id") or "").strip() not in normalized_ids:
continue
if self._normalize_ingest_status_code(entry.get("ingest_status")) == status_code:
continue
entry["ingest_status"] = status_code
entry["ingest_status_updated_at"] = updated_at
changed = True
if changed:
self._save_index(index)
def refresh_document_ingest_statuses(
self,
document_ids: list[str] | None = None,
*,
preserve_syncing: bool = True,
) -> None:
self.ensure_library_ready()
index = self._load_index()
if self._reconcile_document_ingest_statuses(
index,
document_ids=document_ids,
preserve_syncing=preserve_syncing,
):
self._save_index(index)
def get_llm_wiki_root(self) -> Path:
self.ensure_library_ready()
return self.llm_wiki_root
def extract_document_text(self, document_id: str) -> str:
self.ensure_library_ready()
entry = self.get_document_entry(document_id)
file_path = self._resolve_document_path(entry)
if not file_path.exists():
raise FileNotFoundError(entry["original_name"])
return self._extract_document_text_from_path(
file_path=file_path,
original_name=str(entry.get("original_name") or file_path.name),
mime_type=str(entry.get("mime_type") or "application/octet-stream"),
)
def build_onlyoffice_config(
self,
@@ -365,33 +470,41 @@ class KnowledgeService:
actor_name = callback.users[0] if callback.users else "ONLYOFFICE"
self._replace_document_content(document_id, content, actor_name=actor_name)
def _load_documents(self) -> list[KnowledgeDocumentRead]:
self.ensure_library_ready()
index = self._load_index()
self._reconcile_index(index)
self._save_index(index)
documents = [self._serialize_document(entry) for entry in index["documents"]]
return sorted(documents, key=lambda item: item.time, reverse=True)
def _serialize_document(self, entry: dict[str, Any]) -> KnowledgeDocumentRead:
def _load_documents(self) -> list[KnowledgeDocumentRead]:
self.ensure_library_ready()
index = self._load_index()
changed = self._reconcile_index(index)
changed = self._reconcile_document_ingest_statuses(index) or changed
if changed:
self._save_index(index)
documents = [self._serialize_document(entry) for entry in index["documents"]]
return sorted(documents, key=lambda item: item.time, reverse=True)
def _serialize_document(self, entry: dict[str, Any]) -> KnowledgeDocumentRead:
extension = entry.get("extension") or self._extract_extension(entry["original_name"])
file_type = self._resolve_file_type(extension)
size_bytes = int(entry.get("size_bytes") or 0)
updated_at = self._format_time(entry.get("updated_at") or entry.get("created_at"))
return KnowledgeDocumentRead(
id=entry["id"],
name=entry["original_name"],
folder=entry["folder"],
tag=f"{entry['folder']} / {extension.upper() or 'FILE'}",
time=updated_at,
version=f"v{int(entry.get('version_number', 1))}.0",
state="已发布",
stateTone="success",
owner=entry.get("uploaded_by") or "系统导入",
icon=ICON_BY_TYPE.get(file_type, ICON_BY_TYPE["binary"]),
fileType=file_type,
file_type = self._resolve_file_type(extension)
size_bytes = int(entry.get("size_bytes") or 0)
updated_at = self._format_time(entry.get("updated_at") or entry.get("created_at"))
state_code = self._normalize_ingest_status_code(entry.get("ingest_status"))
state_label, state_tone = KNOWLEDGE_INGEST_STATUS_META.get(
state_code,
KNOWLEDGE_INGEST_STATUS_META[KNOWLEDGE_INGEST_STATUS_PUBLISHED],
)
return KnowledgeDocumentRead(
id=entry["id"],
name=entry["original_name"],
folder=entry["folder"],
tag=f"{entry['folder']} / {extension.upper() or 'FILE'}",
time=updated_at,
version=f"v{int(entry.get('version_number', 1))}.0",
stateCode=state_code,
state=state_label,
stateTone=state_tone,
owner=entry.get("uploaded_by") or "系统导入",
icon=ICON_BY_TYPE.get(file_type, ICON_BY_TYPE["binary"]),
fileType=file_type,
fileTypeLabel=self._resolve_file_type_label(file_type),
summary=f"{entry['folder']} · {extension.upper() or 'FILE'} · {self._format_size(size_bytes)}",
mimeType=entry.get("mime_type") or "application/octet-stream",
@@ -551,27 +664,31 @@ class KnowledgeService:
encoding="utf-8",
)
def _reconcile_index(self, index: dict[str, Any]) -> bool:
changed = False
documents = index.setdefault("documents", [])
def _reconcile_index(self, index: dict[str, Any]) -> bool:
changed = False
documents = index.setdefault("documents", [])
known_by_stored = {
(item["folder"], item["stored_name"]): item
for item in documents
if item.get("folder") and item.get("stored_name")
}
existing_items: list[dict[str, Any]] = []
for item in documents:
file_path = self._resolve_document_path(item)
if file_path.exists():
item["size_bytes"] = file_path.stat().st_size
item["extension"] = self._extract_extension(item["original_name"])
item["mime_type"] = item.get("mime_type") or (
mimetypes.guess_type(item["original_name"])[0] or "application/octet-stream"
)
existing_items.append(item)
else:
changed = True
existing_items: list[dict[str, Any]] = []
for item in documents:
file_path = self._resolve_document_path(item)
if file_path.exists():
item["size_bytes"] = file_path.stat().st_size
item["extension"] = self._extract_extension(item["original_name"])
item["mime_type"] = item.get("mime_type") or (
mimetypes.guess_type(item["original_name"])[0] or "application/octet-stream"
)
normalized_status = self._normalize_ingest_status_code(item.get("ingest_status"))
if item.get("ingest_status") != normalized_status:
item["ingest_status"] = normalized_status
changed = True
existing_items.append(item)
else:
changed = True
for folder_name in FIXED_KNOWLEDGE_FOLDERS:
folder_path = self.library_root / folder_name
@@ -596,18 +713,128 @@ class KnowledgeService:
"extension": self._extract_extension(original_name),
"size_bytes": stat.st_size,
"sha256": "",
"created_at": datetime.fromtimestamp(stat.st_ctime, tz=UTC).isoformat(),
"updated_at": datetime.fromtimestamp(stat.st_mtime, tz=UTC).isoformat(),
"uploaded_by": "系统导入",
"version_number": 1,
}
)
changed = True
"created_at": datetime.fromtimestamp(stat.st_ctime, tz=UTC).isoformat(),
"updated_at": datetime.fromtimestamp(stat.st_mtime, tz=UTC).isoformat(),
"uploaded_by": "系统导入",
"version_number": 1,
"ingest_status": KNOWLEDGE_INGEST_STATUS_PUBLISHED,
}
)
changed = True
if changed or len(existing_items) != len(documents):
index["documents"] = existing_items
return True
return False
if changed or len(existing_items) != len(documents):
index["documents"] = existing_items
return True
return False
def _reconcile_document_ingest_statuses(
self,
index: dict[str, Any],
*,
document_ids: list[str] | None = None,
preserve_syncing: bool = True,
) -> bool:
changed = False
target_ids = {str(item).strip() for item in document_ids or [] if str(item).strip()}
wiki_index = self._load_llm_wiki_index()
wiki_by_document_id = {
str(item.get("document_id") or "").strip(): item
for item in list(wiki_index.get("documents") or [])
if str(item.get("document_id") or "").strip()
}
for entry in index.get("documents", []):
document_id = str(entry.get("id") or "").strip()
if target_ids and document_id not in target_ids:
continue
current_status = self._normalize_ingest_status_code(entry.get("ingest_status"))
if entry.get("ingest_status") != current_status:
entry["ingest_status"] = current_status
changed = True
if (
current_status == KNOWLEDGE_INGEST_STATUS_SYNCING
and preserve_syncing
and not self._is_syncing_status_stale(entry)
):
continue
desired_status = (
KNOWLEDGE_INGEST_STATUS_INGESTED
if self._has_ingested_llm_wiki_document(entry, wiki_by_document_id.get(document_id))
else KNOWLEDGE_INGEST_STATUS_PUBLISHED
)
if current_status == KNOWLEDGE_INGEST_STATUS_FAILED and desired_status != KNOWLEDGE_INGEST_STATUS_INGESTED:
continue
if current_status != desired_status:
entry["ingest_status"] = desired_status
changed = True
return changed
def _load_llm_wiki_index(self) -> dict[str, Any]:
try:
payload = json.loads(self.llm_wiki_index_path.read_text(encoding="utf-8"))
except (FileNotFoundError, json.JSONDecodeError):
payload = {"documents": []}
payload.setdefault("documents", [])
return payload
def _has_ingested_llm_wiki_document(
self,
entry: dict[str, Any],
wiki_document: dict[str, Any] | None,
) -> bool:
if not isinstance(wiki_document, dict):
return False
if int(wiki_document.get("knowledge_candidate_count") or 0) <= 0:
return False
current_signature = self._build_llm_wiki_document_signature(entry)
wiki_signature = wiki_document.get("signature")
if isinstance(wiki_signature, dict):
return wiki_signature == current_signature
return (
str(wiki_document.get("document_id") or "").strip() == str(entry.get("id") or "").strip()
and str(wiki_document.get("checksum") or "").strip() == str(entry.get("sha256") or "").strip()
)
@staticmethod
def _build_llm_wiki_document_signature(entry: dict[str, Any]) -> dict[str, Any]:
return {
"document_id": str(entry.get("id") or ""),
"original_name": str(entry.get("original_name") or ""),
"stored_name": str(entry.get("stored_name") or ""),
"sha256": str(entry.get("sha256") or ""),
"version_number": int(entry.get("version_number") or 1),
"updated_at": str(entry.get("updated_at") or ""),
}
@staticmethod
def _normalize_ingest_status_code(value: Any) -> int:
try:
status_code = int(value)
except (TypeError, ValueError):
return KNOWLEDGE_INGEST_STATUS_PUBLISHED
if status_code not in KNOWLEDGE_INGEST_STATUS_META:
return KNOWLEDGE_INGEST_STATUS_PUBLISHED
return status_code
@staticmethod
def _is_syncing_status_stale(entry: dict[str, Any]) -> bool:
raw_value = str(entry.get("ingest_status_updated_at") or "").strip()
if not raw_value:
return True
try:
updated_at = datetime.fromisoformat(raw_value)
except ValueError:
return True
if updated_at.tzinfo is None:
updated_at = updated_at.replace(tzinfo=UTC)
age_seconds = (datetime.now(UTC) - updated_at.astimezone(UTC)).total_seconds()
return age_seconds >= KNOWLEDGE_INGEST_SYNC_STALE_SECONDS
def _require_entry(self, index: dict[str, Any], document_id: str) -> dict[str, Any]:
for entry in index["documents"]:
@@ -746,27 +973,109 @@ class KnowledgeService:
def _can_preview(extension: str) -> bool:
return extension in INLINE_PREVIEW_EXTENSIONS or extension in STRUCTURED_PREVIEW_EXTENSIONS
@staticmethod
def _read_text_preview(file_path: Path) -> str:
encodings = ("utf-8", "utf-8-sig", "gbk")
for encoding in encodings:
try:
@staticmethod
def _read_text_preview(file_path: Path) -> str:
encodings = ("utf-8", "utf-8-sig", "gbk")
for encoding in encodings:
try:
return file_path.read_text(encoding=encoding)
except UnicodeDecodeError:
continue
return "当前文本文件编码暂不支持在线解析。"
@staticmethod
def _extract_docx_text(file_path: Path) -> str:
try:
with ZipFile(file_path) as archive:
xml_content = archive.read("word/document.xml")
except (BadZipFile, KeyError):
return "当前 Word 文件解析失败。"
def _extract_docx_text(file_path: Path) -> str:
try:
with ZipFile(file_path) as archive:
xml_content = archive.read("word/document.xml")
except (BadZipFile, KeyError):
return "当前 Word 文件解析失败。"
root = ElementTree.fromstring(xml_content)
texts = [node.text.strip() for node in root.iter() if node.tag.endswith("}t") and node.text]
return "\n".join(texts)
texts = [node.text.strip() for node in root.iter() if node.tag.endswith("}t") and node.text]
return "\n".join(texts)
def _extract_document_text_from_path(
self,
*,
file_path: Path,
original_name: str,
mime_type: str,
) -> str:
extension = self._extract_extension(original_name)
if extension in TEXT_EXTENSIONS:
return self._normalize_extracted_text(self._read_text_preview(file_path))
if extension == "docx":
return self._normalize_extracted_text(self._extract_docx_text(file_path))
if extension == "pdf":
text = self._normalize_extracted_text(self._extract_pdf_text(file_path))
if text:
return text
return self._normalize_extracted_text(
self._extract_text_with_ocr(
file_path=file_path,
original_name=original_name,
mime_type=mime_type,
)
)
if extension in IMAGE_EXTENSIONS:
return self._normalize_extracted_text(
self._extract_text_with_ocr(
file_path=file_path,
original_name=original_name,
mime_type=mime_type,
)
)
return ""
@staticmethod
def _normalize_extracted_text(text: str) -> str:
normalized = str(text or "").replace("\r\n", "\n").replace("\r", "\n")
normalized = re.sub(r"\n{3,}", "\n\n", normalized)
return normalized.strip()
@staticmethod
def _extract_pdf_text(file_path: Path) -> str:
pdftotext_bin = shutil.which("pdftotext")
if not pdftotext_bin:
return ""
completed = subprocess.run(
[pdftotext_bin, str(file_path), "-"],
capture_output=True,
text=True,
timeout=40,
check=False,
)
if completed.returncode != 0:
return ""
return str(completed.stdout or "")
@staticmethod
def _extract_text_with_ocr(
*,
file_path: Path,
original_name: str,
mime_type: str,
) -> str:
try:
from app.services.ocr import OcrService
result = OcrService().recognize_files(
[(original_name, file_path.read_bytes(), mime_type)]
)
except Exception:
return ""
parts: list[str] = []
for document in result.documents:
text = str(getattr(document, "text", "") or "").strip()
summary = str(getattr(document, "summary", "") or "").strip()
if text:
parts.append(text)
elif summary:
parts.append(summary)
return "\n\n".join(part for part in parts if part)
@staticmethod
def _extract_xlsx_sheets(file_path: Path) -> list[tuple[str, list[list[str]]]]:

54
web/src/services/knowledge.js
View File

@@ -1,12 +1,23 @@
import { apiRequest } from './api.js'
export function fetchKnowledgeLibrary() {
return apiRequest('/knowledge/library')
}
export function fetchKnowledgeDocument(documentId) {
return apiRequest(`/knowledge/documents/${documentId}`)
}
export function fetchKnowledgeLibrary() {
return apiRequest('/knowledge/library')
}
export function fetchLlmWikiDocumentDetail(documentId) {
return apiRequest(`/knowledge/llm-wiki/documents/${documentId}`)
}
export function updateLlmWikiDocumentSummary(documentId, payload) {
return apiRequest(`/knowledge/llm-wiki/documents/${documentId}`, {
method: 'PATCH',
body: JSON.stringify(payload)
})
}
export function fetchKnowledgeDocument(documentId) {
return apiRequest(`/knowledge/documents/${documentId}`)
}
export function fetchKnowledgeOnlyOfficeConfig(documentId) {
return apiRequest(`/knowledge/documents/${documentId}/onlyoffice-config`)
@@ -23,15 +34,26 @@ export function uploadKnowledgeDocument({ folder, file }) {
)
}
export function deleteKnowledgeDocument(documentId) {
return apiRequest(`/knowledge/documents/${documentId}`, {
method: 'DELETE'
})
}
export function fetchKnowledgeDocumentBlob(documentId, disposition = 'inline') {
return apiRequest(`/knowledge/documents/${documentId}/content?disposition=${disposition}`, {
responseType: 'blob',
export function deleteKnowledgeDocument(documentId) {
return apiRequest(`/knowledge/documents/${documentId}`, {
method: 'DELETE'
})
}
export function syncKnowledgeDocumentToLlmWiki({ folder, documentId, force = false }) {
return apiRequest('/knowledge/llm-wiki/sync', {
method: 'POST',
body: JSON.stringify({
folder,
document_ids: documentId ? [documentId] : [],
force
})
})
}
export function fetchKnowledgeDocumentBlob(documentId, disposition = 'inline') {
return apiRequest(`/knowledge/documents/${documentId}/content?disposition=${disposition}`, {
responseType: 'blob',
contentType: null
})
}