# 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`。~~