X-Financial/document/development/agent week plan/day_3_semantic_ontology_mvp.md

Day 3：语义本体 MVP

今天的大开发点

建立模型优先的语义解析层，把自然语言问题转换成统一的 8 个核心字段。

这一天的目标不是继续堆关键词，而是先把真实模型接入语义层，让报销、应收、应付、知识和风险相关问题进入稳定结构，再由规则做兜底和校验。

为什么第三天做这个

Orchestrator 不能直接根据原始文本做可靠路由。它需要先拿到结构化语义，再决定调用 User Agent、Hermes、规则、MCP 或知识库。

今天主要交付

• 语义本体 8 字段结构。
• 场景识别：报销、应收、应付、知识、未知。
• 意图识别：查询、解释、对比、风险检查、草稿、操作。
• 业务对象提取：员工、客户、供应商、部门、项目、单据、金额。
• 时间范围解析。
• 指标和约束解析。
• 风险信号和权限级别判断。
• LLM 结构化解析 Prompt。
• Schema 校验与 JSON 清洗。
• 规则回退解析。
• 低置信度追问和缺槽位追问。
• 语义解析 API。
• 解析日志和最小评测集。

当前完成情况

• /api/v1/ontology/parse 已上线，8 字段语义结构、缺槽位、歧义、权限和澄清问题均可返回。
• 语义层已切到“模型优先 + 规则回退”，并把结果写入 AgentRun / SemanticParseLog。
• 附件名称、附件数量、OCR 摘要和 OCR 文档摘要已能作为上下文带入语义层。
• 最小会话历史、上一轮场景/意图和 draft_claim_id 已能作为上下文带入语义层，用于识别“改成 800”“继续补充”这类追问。
• 叙述型报销语义已补强：客户 + 吃饭/请客/宴请/招待 优先归类为业务招待费，不再误打到应收查询。
• 相对时间已支持标准化展示：今天 / 昨天 / 本月 / 4 月 会换算成绝对日期，同时保留原始表达。
• 前端调试入口与核心评测测试已完成并通过。
• 叙述型报销样本、附件/OCR 带入样本和模糊短句追问样本仍需继续扩充。

相关架构文档：

• 语义本体
• 财务单据标准模型
• 数据契约与治理

当天验收门槛

• 输入自然语言问题能返回 8 个字段。
• 模型解析失败时能自动回退到规则解析。
• 低置信度问题能返回澄清问题。
• 越权动作不会被标记为可直接执行。
• 解析结果能写入日志。
• 至少覆盖报销、应收、应付三个场景。
• 叙述型报销输入不会被错误路由到应收或应付。

今天不做

• 不做复杂多轮对话记忆。
• 不做完整 Agent 自主规划。
• 不做自动执行业务流程。

详细执行清单

以下内容为合并后的详细执行清单。

0. 开始前检查

• 确认 Day 1 的 SemanticParseLog 可用。
• 确认 Day 1 的 AgentRun 可用。
• 确认 Day 2 的资产 API 可用。
• 找到后端服务层目录。
• 找到现有 LLM 调用或 Mock 调用方式。
• 确认当前是否允许真实调用 LLM。
• 确认当前运行时模型槽位可用于语义解析。
• 如果真实模型不可用，已准备规则解析回退路径。

1. 定义 8 个核心字段

• 定义字段 scenario，表示业务场景。
• 定义字段 intent，表示用户意图。
• 定义字段 entities，表示业务对象。
• 定义字段 time_range，表示时间范围。
• 定义字段 metrics，表示指标或金额口径。
• 定义字段 constraints，表示过滤条件。
• 定义字段 risk_flags，表示风险信号。
• 定义字段 permission，表示动作权限。
• 为每个字段写清楚类型。
• 为每个字段写清楚是否必填。
• 为每个字段写清楚默认值。
• 为每个字段写清楚示例。

验收证据：

• 8 个字段在 Schema、服务层、日志中名字一致。

2. 设计字段枚举

• scenario 支持 expense。
• scenario 支持 accounts_receivable。
• scenario 支持 accounts_payable。
• scenario 支持 knowledge。
• scenario 支持 unknown。
• intent 支持 query。
• intent 支持 explain。
• intent 支持 compare。
• intent 支持 risk_check。
• intent 支持 draft。
• intent 支持 operate。
• permission.level 支持 read。
• permission.level 支持 draft_write。
• permission.level 支持 approval_required。
• permission.level 支持 forbidden。

验收证据：

• 未识别的问题不会抛异常，返回 unknown。

3. 建立 Schema

• 定义 OntologyParseRequest。
• OntologyParseRequest 包含 query。
• OntologyParseRequest 包含 user_id。
• OntologyParseRequest 包含 context_json。
• 定义 OntologyParseResult。
• OntologyParseResult 包含 8 个核心字段。
• OntologyParseResult 包含 confidence。
• OntologyParseResult 包含 clarification_required。
• OntologyParseResult 包含 clarification_question。
• OntologyParseResult 包含 run_id。
• 定义字段级错误结构。

验收证据：

• OpenAPI 中可以看到语义解析请求和响应。

4. 实现解析服务

• 新增 SemanticOntologyService 或同等服务。
• 实现 parse(query, user_context) 主函数。
• 增加上下文装配层，输入文本、页面上下文、附件摘要和预抽取字段。
• 实现模型优先的结构化语义解析。
• 约束模型只输出 JSON。
• 对模型输出做清洗、提取和 Schema 校验。
• 模型失败时自动回退到规则解析。
• 在结果中记录本次使用了 llm_primary 还是 rule_fallback。
• 报销关键词映射到 expense。
• 应收、回款、客户欠款映射到 accounts_receivable。
• 应付、供应商、付款映射到 accounts_payable。
• 风险、异常、重复、超标映射到 risk_check。
• 为什么、依据、规则映射到 explain。
• 统计、汇总、多少映射到 query。
• 生成、创建、发起映射到 draft 或 operate。
• 无法识别时返回低置信度和澄清问题。
• 叙述型报销输入优先识别为创建/草稿，而不是查询。

验收证据：

• “查一下本周报销超标风险”能识别为 expense + risk_check。
• “客户 A 这个月还有多少应收”能识别为 accounts_receivable + query。
• “供应商 B 明天要付多少钱”能识别为 accounts_payable + query。
• “我今天去客户现场，招待了客户，花销了1000元”不会错误识别为应收查询。
• “昨天请客户吃饭花了 200 元”会优先识别为报销草稿语义，并保留绝对日期 + 原文日期。

5. 解析业务对象

• 从问题中提取员工姓名。
• 从问题中提取部门。
• 从问题中提取客户。
• 从问题中提取供应商。
• 从问题中提取项目。
• 从问题中提取单据号。
• 从问题中提取金额。
• 从问题中提取费用类型。
• 无法提取时返回空数组，不返回 null。

验收证据：

• “张三 4 月差旅报销”能提取员工、月份、费用类型。

6. 解析时间范围

• 支持今天。
• 支持昨天。
• 支持本周。
• 支持上周。
• 支持本月。
• 支持上月。
• 支持本季度。
• 支持今年。
• 支持明确日期。
• 支持日期区间。
• 解析结果包含 start_date 和 end_date。
• 日期使用 ISO 格式。

验收证据：

• “本周”能解析为当前周起止日期。
• “2026 年 4 月”能解析为 2026-04-01 到 2026-04-30。

7. 解析指标与约束

• 识别金额指标。
• 识别数量指标。
• 识别超标指标。
• 识别逾期指标。
• 识别重复报销指标。
• 识别部门过滤条件。
• 识别状态过滤条件。
• 识别金额阈值过滤条件。
• 识别排序要求。
• 识别 Top N 要求。

验收证据：

• “列出金额最高的 10 笔报销”能识别排序和 Top 10。

8. 解析风险与权限

• 重复报销映射到 duplicate_expense。
• 发票异常映射到 invoice_anomaly。
• 金额超标映射到 amount_over_limit。
• 逾期应收映射到 ar_overdue。
• 逾期应付映射到 ap_overdue。
• 查询类问题权限为 read。
• 生成草稿权限为 draft_write。
• 审批、上线、付款类动作权限为 approval_required。
• 越权动作权限为 forbidden。

验收证据：

• “帮我直接付款”不能被标为可直接执行。

9. API 接口

• 新增 POST /api/v1/ontology/parse。
• 请求参数包含用户问题。
• 请求参数包含用户上下文。
• 响应包含 8 个字段。
• 响应包含 run_id。
• 响应包含置信度。
• 响应包含澄清问题。
• 每次调用写入 SemanticParseLog。
• 每次调用写入 AgentRun 或关联已有 AgentRun。

验收证据：

• 连续调用多次都能在日志中查到。

10. 前端调试入口

• 在合适页面增加语义解析调试入口。
• 输入框支持自然语言问题。
• 点击解析后调用 API。
• 展示 8 个字段。
• 展示 JSON 原始结果。
• 展示置信度。
• 展示澄清问题。
• 展示 run_id。
• 错误时展示错误信息。

验收证据：

• 产品和开发可以直接在页面验证解析结果。

11. 评测集

• 创建至少 5 条报销问题。
• 创建至少 5 条叙述型报销问题。
• 创建至少 3 条附件 / OCR 摘要带入的报销问题。
• 创建至少 5 条应收问题。
• 创建至少 5 条应付问题。
• 创建至少 3 条知识库问题。
• 创建至少 3 条越权操作问题。
• 创建至少 3 条模糊短句追问问题。
• 为每条问题写期望 scenario。
• 为每条问题写期望 intent。
• 为每条问题写期望权限级别。
• 编写评测脚本或测试。

验收证据：

• 当前评测样本集已通过，覆盖样本准确率达到当天设定阈值。

12. Day 3 验收

• 语义解析 API 可用。
• 8 个核心字段完整返回。
• 解析日志可查询。
• 低置信度问题有澄清问题。
• 越权动作不会被标为可执行。
• 前端调试入口可用。
• 评测集可运行。
• 所有完成项已用 [x] ~~...~~ 标记。

阻塞记录

• 暂无。

日终交接

• 已支持报销 / 应收 / 应付 / 知识 / 风险 / 草稿 / 越权动作等核心场景关键词、实体与权限解析。
• 语义层已可接收附件名称、附件数量和 OCR 摘要上下文，但这些样本仍需继续扩到评测集。
• 当前仍需继续扩充的弱样本主要是叙述型报销长句、附件/OCR 带入和模糊短句追问。
• Day 4 可直接复用 scenario / intent / entities / time_range / metrics / constraints / risk_flags / permission / confidence / missing_slots / ambiguity / parse_strategy / clarification_required / clarification_question / run_id。