52 lines
3.2 KiB
Markdown
52 lines
3.2 KiB
Markdown
# Proposal: single-react-rag-log-projections
|
|
|
|
## Problem
|
|
|
|
阶段 3A 已提供统一 `ToolBoundary` 和 canonical invocation store，但 RAG 与 `query_logs` 仍只有旧工具输出。旧输出包含检索轨迹、上下文打包、基础设施字段、实例信息和未受约束的日志内容，不能直接作为单体 Diagnosis Agent 的 ACI evidence projection。若分别实现状态机或存储，会重新引入重复的生命周期、Run ownership 和错误处理逻辑。
|
|
|
|
## Proposed change
|
|
|
|
- 新增 RAG result projector，将旧 `LookupKnowledgeTool` JSON 转换为冻结的 `RagToolResult`。
|
|
- 新增 query-log result projector，将现有 Mock `QueryLogsTools` JSON 转换为冻结的 `QueryLogsToolResult`。
|
|
- projector 负责精确摘录、文档去重、证据/事件/模式数量上限、整体字符预算、时间线抽样和脱敏。
|
|
- projector 由请求感知适配层调用，使 `topic`、`query` 和 `lookback_minutes` 保留在完整 `scope` 中；不扩展 Agent request，不让 raw response 直接进入 Agent。
|
|
- 两个适配器均通过阶段 3A `ToolBoundary` 执行，沿用框架 `tool_call_id`、RunContext、canonical store、`PROJECTING/READY/ERROR` 与 `EVIDENCE_FOUND/NO_EVIDENCE/ERROR` 语义。
|
|
- 保留旧工具、旧 recorder、Chat/AIOps、Controller 和公开协议不变；本阶段只新增投影/适配层与 focused tests。
|
|
|
|
## Scope
|
|
|
|
### In scope
|
|
|
|
- RAG projector and adapter.
|
|
- Query-log projector and adapter for existing Mock source.
|
|
- Request-aware projection entry point required to preserve log scope.
|
|
- Contract, sanitization, deduplication, truncation, no-evidence and boundary integration tests.
|
|
|
|
### Out of scope
|
|
|
|
- Real CLS/MCP log integration.
|
|
- MySQL projector (stage 3C).
|
|
- Diagnosis Agent cutover, Guards, Chat use-case cutover, SSE changes, or legacy recorder cleanup.
|
|
- Changes to the frozen ACI DTO field names.
|
|
|
|
## Constraints and risks
|
|
|
|
- Raw payload remains Harness-only canonical data and is never returned to the Agent.
|
|
- `NO_EVIDENCE` is scoped to the recorded query and time window; it is not a health claim.
|
|
- Log messages may contain credentials, hostnames, pod IDs, SQL literals, or stack traces; projection must redact these before Agent exposure.
|
|
- A projector must not silently truncate raw data. It may bound Agent-facing collections and excerpts while setting `truncated=true`.
|
|
- The existing generic `ToolResultProjector` API has no request argument. The adapter will carry the typed request alongside the projector invocation, keeping the generic boundary reusable and avoiding a raw JSON scope convention.
|
|
|
|
## Acceptance direction
|
|
|
|
- Serialized RAG output contains only the frozen fields and bounded exact excerpts.
|
|
- Serialized log output contains complete logical scope, `source_kind=MOCK`, bounded patterns/events, distinct match and returned counts, and no infrastructure controls.
|
|
- Both projectors produce `NO_EVIDENCE` for successful empty results and `ERROR` for malformed/unsafe input.
|
|
- Boundary tests prove framework ID preservation, canonical lifecycle reuse, raw isolation, and safe errors.
|
|
|
|
## Context sources
|
|
|
|
- ISS-014 stage 3B requirements.
|
|
- `aci-evidence-tool-contracts` and `canonical-tool-invocation-store` specifications.
|
|
- Existing `LookupKnowledgeTool`, `QueryLogsTools`, and frozen contract tests.
|