# 需求澄清结果汇总

> 本文档汇总根据用户反馈对需求的澄清结果，以及新增的补充文档。

## 1. 已明确的问题与解决方案

### 1.1 operator 支持细节 ✅

**问题**：operator 参数生成缺少详细设计

**解决方案**：
- 已创建《07-operator参数生成提示词设计.md》
- 流程与 metric 类似，但区别在于：
  - 无固定系统参数（instant/start/end/step）
  - 支持复杂参数类型（对象/数组）
  - 抽取优先级：additional_context > object_instances > query > operator_schema
- 包含 8 个测试样例（涵盖简单参数、对象、数组、缺参等场景）

---

### 1.2 now_ms / timezone 默认行为 ✅

**问题**：文档中对 now_ms 的默认行为有矛盾说明

**明确方案**：
- **now_ms**：若调用方不传，**由服务端取当前时间戳**（毫秒）并在 debug 中返回实际使用值
- **timezone**：**暂不考虑**（后续需要时再补充）

**已更新文档**：
- 《03-方案设计.md》第 9.3 节

---

### 1.3 重试机制 ✅

**问题**：需要明确哪些环节支持重试

**明确方案**：
- **只重试 LLM 调用**：HTTP 429/5xx/超时，最多重试 2 次，指数退避（100ms → 200ms）
- **不重试其他依赖**：ontology-manager/ontology-query 调用失败直接返回错误给上游
- **缺参直接报错**：返回结构化缺参清单，交给上游处理（追问用户或补充 additional_context）

**已更新文档**：
- 《03-方案设计.md》第 9.2 节
- 《05-并发策略与超时配置.md》第 3 节

---

### 1.4 错误码体系 ✅

**问题**：缺少完整的错误码定义

**解决方案**：
- 已创建《06-错误码清单与处理策略.md》
- 定义了 10 个错误码：
  - 客户端错误（4xx）：INVALID_REQUEST / MISSING_INPUT_PARAMS / INVALID_PROPERTY / OBJECT_TYPE_NOT_FOUND
  - 服务端错误（5xx）：LLM_CALL_FAILED / LLM_OUTPUT_INVALID / ONTOLOGY_MANAGER_ERROR / ONTOLOGY_QUERY_ERROR / TIMEOUT / INTERNAL_ERROR
- 每个错误码包含：触发条件、返回示例、处理建议、是否可重试

---

### 1.5 对象类定义缓存策略 ✅

**问题**：需要明确是否缓存 ontology-manager 返回的对象类定义

**明确方案**：
- **暂不缓存，每次请求都获取**
- 后续可按需优化为按 kn_id+ot_id 缓存，配置 TTL

**已更新文档**：
- 《03-方案设计.md》第 6.1 节

---

### 1.6 并发策略 ✅

**问题**：需要给出简化的并发策略方案

**解决方案**：
- 已创建《05-并发策略与超时配置.md》
- 推荐参数：
  - `max_concurrency`: 4（默认），可根据 LLM 网关限流调整（3~8）
  - `llm_timeout`: 10s
  - `total_timeout`: 30s
  - `max_retry`: 2
- 选择依据：平衡 LLM 网关限流（如 10 QPS）与延迟收益
- 包含实现伪代码和可观测性指标建议

---

### 1.7 partial_success 支持 ✅

**问题**：需要明确是否支持部分成功

**明确方案**：
- **不支持部分成功**
- 任一属性缺参/生成失败 → 整体失败
- 简化实现复杂度，避免上游处理混合状态

**已更新文档**：
- 《03-方案设计.md》第 8.1 节"失败处理策略"
- 《kn-logic-property-resolver.openapi.yaml》移除了 `partial_success` 选项

---

### 1.8 MVP 交付清单 ✅

**问题**：MVP 清单过于简略

**明确方案**：
- **功能范围**：
  - ✅ 只支持 logic_properties 查询（不支持与 data_properties 混合）
  - ✅ 单对象类多实例（只支持单个 ot_id 下的多个 unique_identities）
  - ✅ 批量属性（支持多个 properties）
  - ✅ metric + operator 同时支持
- **不支持的特性**：
  - ❌ data_properties 和 logic_properties 混合查询
  - ❌ 跨对象类查询（多个 ot_id）
  - ❌ 分页（一次性返回所有结果）
  - ❌ 部分成功
  - ❌ dynamic_params 缓存
  - ❌ 对象类定义缓存

**已更新文档**：
- 《01-场景与需求梳理.md》第 6 节

---

## 2. 暂不处理的问题

### 2.1 additional_context 结构规范

**当前方案**：暂时保持"自由文本或 JSON 字符串均可"

**后续优化**：在使用过程中收集典型场景，再制定推荐的 JSON schema

---

### 2.2 提示词时间计算准确性

**当前方案**：完全交给 LLM 处理（不用代码实现）

**说明**：由用户人工调试提示词，确保时间计算准确性

---

## 3. 新增文档清单

| 文档名称 | 说明 |
|---------|------|
| 05-并发策略与超时配置.md | 并发参数推荐、超时配置、重试策略、实现伪代码 |
| 06-错误码清单与处理策略.md | 完整错误码定义、触发条件、处理建议、监控告警 |
| 07-operator参数生成提示词设计.md | operator 提示词设计（参照 metric，含 8 个测试样例） |
| 08-需求澄清结果汇总.md | 本文档，汇总所有澄清结果 |

---

## 4. 已更新文档清单

| 文档名称 | 更新内容 |
|---------|---------|
| 01-场景与需求梳理.md | 更新第 6 节 MVP 交付清单（明确功能范围和不支持的特性） |
| 03-方案设计.md | 更新第 6.1 节（缓存策略）、第 8.1 节（并发与失败处理）、第 9 节（缺参策略与重试机制） |
| kn-logic-property-resolver.openapi.yaml | 移除 `partial_success` 选项，更新 `max_concurrency` 说明 |

---

## 5. 待开发者实现的关键点

> **澄清**：ontology-manager、ontology-query、operator-platform 是已有服务，只需集成其客户端即可。

### 5.1 kn-logic-property-resolver 接口实现（核心开发工作）

- [ ] **接口骨架**：路由、请求/响应结构、参数校验
- [ ] **trace_id 生成与透传**：用于链路追踪

### 5.2 LLM 提示词实现（核心开发工作）

- [ ] **metric 参数生成提示词**：基于《04-metric参数生成提示词设计.md》
- [ ] **operator 参数生成提示词**：基于《07-operator参数生成提示词设计.md》
- [ ] **JSON 修复机制**：max_repair_rounds=1
- [ ] **参数校验**：step 枚举（day/week/month/quarter/year）、instant/step 组合

### 5.3 并发与重试（核心开发工作）

- [ ] **按 property 并发调用 LLM**：max_concurrency=4，使用并发池
- [ ] **LLM 调用重试**：max_retry=2，指数退避（100ms → 200ms）
- [ ] **超时控制**：llm_timeout=10s，total_timeout=30s

### 5.4 依赖接口集成（集成已有服务）

- [ ] **集成 ontology-manager 客户端**：调用获取对象类定义（暂不缓存）
- [ ] **集成 ontology-query 客户端**：调用批量查询逻辑属性值
- [ ] **集成 LLM 服务客户端**：调用生成 dynamic_params
- [ ] **（可选）集成 operator-platform 客户端**：获取 operator_schema

### 5.5 错误处理（核心开发工作）

- [ ] **实现所有错误码**：基于《06-错误码清单与处理策略.md》
  - INVALID_REQUEST / MISSING_INPUT_PARAMS / INVALID_PROPERTY / OBJECT_TYPE_NOT_FOUND
  - LLM_CALL_FAILED / LLM_OUTPUT_INVALID
  - ONTOLOGY_MANAGER_ERROR / ONTOLOGY_QUERY_ERROR
  - TIMEOUT / INTERNAL_ERROR
- [ ] **缺参错误结构化返回**：missing 清单 + hint

### 5.6 特殊逻辑处理（核心开发工作）

- [ ] **now_ms 服务端兜底**：若请求中未传 now_ms，服务端取当前时间戳（毫秒）
- [ ] **debug 信息返回**：在 return_debug=true 时返回实际使用的 now_ms、生成的 dynamic_params 等

### 5.7 可观测性（核心开发工作）

- [ ] **LLM 调用指标记录**：property/attempt/latency_ms/status/error_code/tokens
- [ ] **聚合指标计算**：P95 延迟/重试率/失败率/并发数
- [ ] **告警规则配置**：基于错误率和延迟

---

## 7. 需求澄清结果

| 问题 | 最终方案 | 相关文档 |
|------|---------|---------|
| operator 支持细节 | 已设计完整提示词（含 8 个测试样例） | 《07-operator参数生成提示词设计.md》 |
| now_ms/timezone | now_ms 服务端兜底；timezone 暂不考虑 | 《03-方案设计.md》第 9.3 节 |
| 重试机制 | 只重试 LLM（429/5xx/超时，最多 2 次） | 《05-并发策略与超时配置.md》 |
| 缺参处理 | 直接报错返回缺参清单，交给上游 | 《03-方案设计.md》第 9.1 节 |
| 错误码体系 | 已定义 10 个错误码 | 《06-错误码清单与处理策略.md》 |
| 缓存策略 | 暂不缓存，每次都获取 | 《03-方案设计.md》第 6.1 节 |
| 并发策略 | max_concurrency=4，按 property 并发 | 《05-并发策略与超时配置.md》 |
| partial_success | 不支持，任一失败则整体失败 | 《03-方案设计.md》第 8.1 节 |
| MVP 范围 | 只支持 logic_properties、单对象类多实例、不分页 | 《01-场景与需求梳理.md》第 6 节 |

---


## 9. 后续优化方向（不纳入 MVP）

- dynamic_params 缓存、对象类定义缓存
- 自适应并发、智能重试
- 代码规则增强（时间解析/业务参数抽取）
- 跨对象类查询、data_properties 混合查询
- 分页支持


