7.5 KiB
7.5 KiB
Day 3：语义本体 MVP TODO
目标：建立用户问题的语义解析层，输出稳定的 8 个核心字段，让 User Agent、Hermes 和 Orchestrator 都能使用同一套语义结构。
参考文档：
document/development/agent plan/02_semantic_ontology.mddocument/development/agent plan/14_financial_document_canonical_model.mddocument/development/agent plan/06_data_contracts_and_governance.md
0. 开始前检查
- 确认 Day 1 的
SemanticParseLog可用。 - 确认 Day 1 的
AgentRun可用。 - 确认 Day 2 的资产 API 可用。
- 找到后端服务层目录。
- 找到现有 LLM 调用或 Mock 调用方式。
- 确认当前是否允许真实调用 LLM。
- 如果不能调用真实 LLM，准备规则解析加 Mock 解析。
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)主函数。 - 先做关键词规则解析。
- 报销关键词映射到
expense。 - 应收、回款、客户欠款映射到
accounts_receivable。 - 应付、供应商、付款映射到
accounts_payable。 - 风险、异常、重复、超标映射到
risk_check。 - 为什么、依据、规则映射到
explain。 - 统计、汇总、多少映射到
query。 - 生成、创建、发起映射到
draft或operate。 - 无法识别时返回低置信度和澄清问题。
验收证据：
- “查一下本周报销超标风险”能识别为 expense + risk_check。
- “客户 A 这个月还有多少应收”能识别为 accounts_receivable + query。
- “供应商 B 明天要付多少钱”能识别为 accounts_payable + query。
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/ontology/parse。 - 请求参数包含用户问题。
- 请求参数包含用户上下文。
- 响应包含 8 个字段。
- 响应包含
run_id。 - 响应包含置信度。
- 响应包含澄清问题。
- 每次调用写入
SemanticParseLog。 - 每次调用写入
AgentRun或关联已有AgentRun。
验收证据：
- 连续调用 5 次都能在日志中查到。
10. 前端调试入口
- 在合适页面增加语义解析调试入口。
- 输入框支持自然语言问题。
- 点击解析后调用 API。
- 展示 8 个字段。
- 展示 JSON 原始结果。
- 展示置信度。
- 展示澄清问题。
- 展示
run_id。 - 错误时展示错误信息。
验收证据：
- 产品和开发可以直接在页面验证解析结果。
11. 评测集
- 创建至少 5 条报销问题。
- 创建至少 5 条应收问题。
- 创建至少 5 条应付问题。
- 创建至少 3 条知识库问题。
- 创建至少 3 条越权操作问题。
- 为每条问题写期望
scenario。 - 为每条问题写期望
intent。 - 为每条问题写期望权限级别。
- 编写评测脚本或测试。
验收证据：
- 核心场景识别准确率达到当天设定阈值，例如 80%。
12. Day 3 验收
- 语义解析 API 可用。
- 8 个核心字段完整返回。
- 解析日志可查询。
- 低置信度问题有澄清问题。
- 越权动作不会被标为可执行。
- 前端调试入口可用。
- 评测集可运行。
- 所有完成项已用
[x] ~~...~~标记。
阻塞记录
- 暂无。
日终交接
- 写明已支持的关键词。
- 写明识别不准的样例。
- 写明 Day 4 Orchestrator 可以直接复用的响应结构。