12 KiB
12 KiB
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。