# 场景与需求梳理（当前共识版）

## 1. 问题定义（要解决什么）

用户提出**复合问题**时，系统通常先通过检索/查询拿到对象实例的**数据属性**（例如企业列表、主键、部分字段），但用户还希望继续获取这些对象实例的**逻辑属性**（`logic_properties`，包含 metric + operator）。

因此需要一个“逻辑属性值获取能力”，完成两件事：
- **把上下文解析成可执行请求**：基于 `query + object_instances + additional_context + now_ms/timezone` 等信息，为每个逻辑属性生成 `dynamic_params`
- **执行查询并返回结果**：调用底层 `ontology_query_object_proteries`，返回按对象实例对齐的逻辑属性值

典型例子（请保留）：
- “注册资金大于100万人民币的企业有哪些？想知道这些药企的药品上市情况，并且这些企业的健康度怎么样？”
  - 第一步：检索/筛选得到企业列表（含 company_id 等主键，及注册资金等字段）
  - 第二步：对这批企业批量查询逻辑属性：`approved_drug_count`（metric）+ `business_health_score`（operator）

## 2. 输入 / 输出（清晰说清楚）

### 2.1 输入（上游提供）

- **kn_id**：业务知识网络 ID
- **ot_id**：对象类 ID
- **query**：用户原始问题
- **unique_identities**：对象主键数组（可批量）
- **object_instances（可选但强烈建议）**：召回/筛选得到的对象实例数据（可包含部分 data_properties）
- **additional_context（可选）**：额外上下文信息，用于辅助动态参数生成，例如：
  - 结构化筛选条件（原先的 filters）：`注册资金>100万`、`行业=制药` 等
  - 已解析出的时间范围/粒度、用户偏好、业务约束、上游中间结果
- **now_ms / timezone（可选）**：用于时间语义可复现（“最近半年/当前”等）

### 2.2 输出（给上游回填/展示）

- **成功**：按 `unique_identities` 对齐的逻辑属性值结果（metric 返回 MetricPropertyValue；operator 返回对象/结构化结果）
- **失败（缺参/不合法）**：结构化错误清单，告诉上游缺哪些参数、属于哪个 property，以及建议补充哪些上下文

## 3. 端到端链路（Hybrid：Agent 编排 + 逻辑属性值获取工具）

1) 上游（Agent/检索/查询）：
   - 确定 `kn_id/ot_id`
   - 召回/筛选对象实例 → 构建 `unique_identities`（并可携带 `object_instances`）
   - 决定要补齐的逻辑属性 → `properties`
   - 组织上下文 → `query + object_instances + additional_context + now_ms/timezone ...`

2) 逻辑属性值获取工具（本版本需支持 metric + operator；正式命名见《03-方案设计》）：
   - 内部拉 ontology-manager 获取对象类定义（模式B），截取 `properties` 对应的 `logic_properties/parameters` 子集
   - 调用大模型生成 `dynamic_params`（覆盖 metric + operator）
   - 调用底层接口 `ontology_query_object_proteries` 获取逻辑属性值并返回

3) 上游回填：
   - 将逻辑属性结果 merge 回对象实例形成最终回答/展示
   - 若缺参：上游补充 `additional_context`（或追问用户）后重试

## 4. 需求边界与关键约束（本版本必须满足）

- **同时支持 metric + operator**
- **模式B**：工具内部拉 ontology-manager（不考虑 branch/version）
- 暂不做代码语义规则识别（时间/instant/step/业务参数抽取交给大模型）

metric 约束：
- 必须生成所有 `value_from:"input"` 参数；`instant/start/end/step` 是固定系统项
- step 枚举：`day/week/month/quarter/year`（固定 1 个单位）
- instant：`true` 即时（单点），`false` 趋势（范围/序列；此时必须带 step）

operator 约束：
- 必须生成其 `parameters` 中所有 `value_from:"input"` 参数（类型可为基础类型/对象/数组）

## 5. 缺参与补上下文（为什么会发生、怎么处理）

缺参的根因：某些 `value_from:"input"` 参数无法仅从自然语言 query 推断，必须依赖 `object_instances/additional_context/now_ms` 等上下文。

本版本建议的处理口径：
- **缺参直接报错**，返回缺参清单（property/param/type/hint）
- 上游通过补充 `additional_context`（或追问用户）后重试

## 6. MVP 交付清单（最小可落地）

### 6.1 功能范围

- **只支持 logic_properties 查询**：不支持 data_properties 和 logic_properties 混合查询
- **单对象类多实例**：只支持指定单个对象类(ot_id)下的多个对象实例(unique_identities)的逻辑属性查询
- **批量属性**：支持一次查询多个 logic_properties（properties 数组）
- **metric + operator 同时支持**：两种逻辑属性类型都需要在 MVP 中交付

### 6.2 核心能力

- LLM 生成 dynamic_params（按 property 并发，max_concurrency=4）
- JSON 修复（max_repair_rounds=1）
- step 枚举校验（day/week/month/quarter/year）
- 缺参结构化报错（返回缺参清单，由上游处理）
- LLM 调用重试（429/5xx/超时最多重试 2 次）

### 6.3 不支持的特性（后续增强）

- ❌ data_properties 和 logic_properties 混合查询
- ❌ 跨对象类查询（一次请求多个 ot_id）
- ❌ 分页（一次性返回所有结果）
- ❌ 部分成功（任一 property 失败则整体失败）
- ❌ dynamic_params 缓存（相同 query 重复查询需要重新生成）
- ❌ 对象类定义缓存（每次请求都拉取 ontology-manager）


