flzxsqc-demo 1.4.7 → 1.4.8

package/agent-backend/docs/async-analysis-external-worker-kafka-design.md

@@ -0,0 +1,423 @@
+# 异步分析外部 Worker 与 Kafka 回调详细设计
+
+本文档记录本次将异步分析 tool 从“后端进程内直接启动 worker、worker 完成后直接回调续跑服务”改为“HTTP 调用外部 worker、worker 完成后发送 Kafka 消息、后端 Kafka listener 消费后续跑”的完整设计与当前实现。
+
+## 1. 背景
+
+现有内容分析主链路是：
+
+```text
+query_sessions_handle
+  -> analyze_sessions_per_record_async
+  -> query_analysis_results / aggregate_analysis_results / cluster_analysis_results
+  -> build_keyword_report
+```
+
+其中 `analyze_sessions_per_record_async` 是长耗时异步 tool。改造前，本地实现有两处和公司真实调用方式不一致：
+
+1. `AnalysisJobService` 创建 `analysis_job` 后直接调用 `AnalysisWorkerService.start(...)`。
+2. `AnalysisWorkerService` 完成分析后直接调用 `InternalAsyncCallbackService.dispatch(...)`。
+
+这导致本地环境没有模拟真实系统中的两个异步边界：
+
+- 业务后端通过外部 HTTP 接口拉起 worker。
+- worker 处理完成后通过 Kafka topic 通知业务后端继续流程。
+
+本次改造保留现有 tool、DSL、`async_job`、报告生成和前端交互契约，只替换异步分析启动和完成通知的传输方式。
+
+## 2. 改造目标
+
+目标：
+
+- `analyze_sessions_per_record_async` 仍然返回 `PENDING`，由原有 `ToolExecutionPipeline` 登记 `async_job`。
+- 创建 `analysis_job` 后，通过配置化 HTTP 地址拉起 worker。
+- 本地默认提供一个 `/external/analysis/jobs` 接口模拟外部 worker 服务入口。
+- worker 完成后向 Kafka topic 发送完成事件。
+- 后端新增 Kafka listener，消费完成事件后调用原有 `InternalAsyncCallbackService.dispatch(...)`。
+- 原有 agent session / DSL replay 的续跑逻辑不重写。
+
+非目标：
+
+- 不新增新的业务 tool。
+- 不改变 `query_sessions_handle`、聚合、聚类、报告工具契约。
+- 不在代码中自动创建 Kafka topic。
+- 不实现 Kafka 死信队列、重试 topic、认证鉴权和跨服务 trace，这些属于公司环境集成增强项。
+
+## 3. 总体架构
+
+```mermaid
+sequenceDiagram
+    participant LLM as Agent Planner
+    participant Tools as ToolsController
+    participant Job as AnalysisJobService
+    participant Client as ExternalAnalysisWorkerClient
+    participant WorkerApi as External Worker API
+    participant Worker as AnalysisWorkerService
+    participant Kafka as Kafka Topic
+    participant Listener as AnalysisWorkerCompletionKafkaListener
+    participant Callback as InternalAsyncCallbackService
+    participant Runtime as AgentTurnRunner / DslRuntimeService
+
+    LLM->>Tools: POST /tools/analyze-sessions-per-record-async
+    Tools->>Job: createPerRecordJob(...)
+    Job->>Job: insert analysis_job=PENDING
+    Job->>Client: submit(analysisJobId)
+    Client->>WorkerApi: POST /external/analysis/jobs
+    WorkerApi->>Worker: start(analysisJobId)
+    WorkerApi-->>Client: 202 ACCEPTED
+    Job-->>Tools: artifacts.analysis_job_id
+    Tools-->>LLM: status=PENDING
+    Runtime->>Runtime: insert async_job(PENDING)
+    Worker->>Worker: run analysis and persist result
+    Worker->>Kafka: publish completion event
+    Kafka-->>Listener: consume completion event
+    Listener->>Callback: dispatch(externalJobId,status,payload)
+    Callback->>Runtime: append tool observation and resume
+```
+
+## 4. 当前代码改动
+
+### 4.1 新增类
+
+| 类 | 位置 | 职责 |
+| --- | --- | --- |
+| `ExternalAnalysisWorkerClient` | `src/main/java/com/example/agent/application/service/localtool/ExternalAnalysisWorkerClient.java` | 创建 `analysis_job` 后，通过 HTTP POST 调用 worker submit URL。 |
+| `AnalysisWorkerCompletionPublisher` | `src/main/java/com/example/agent/application/service/localtool/AnalysisWorkerCompletionPublisher.java` | worker 完成后序列化完成事件并发送 Kafka。 |
+| `AgentKafkaConfig` | `src/main/java/com/example/agent/infrastructure/config/AgentKafkaConfig.java` | 开启 Spring Kafka listener 注解。 |
+| `AnalysisWorkerCompletionKafkaListener` | `src/main/java/com/example/agent/infrastructure/messaging/AnalysisWorkerCompletionKafkaListener.java` | 消费分析完成事件，调用内部异步回调服务续跑。 |
+| `ExternalAnalysisWorkerController` | `src/main/java/com/example/agent/interfaces/rest/ExternalAnalysisWorkerController.java` | 本地模拟外部 worker submit 接口。 |
+
+### 4.2 修改类
+
+| 类 | 修改点 |
+| --- | --- |
+| `AnalysisJobService` | `createJobInternal(...)` 中由直接 `analysisWorkerService.start(analysisJobId)` 改为 `externalAnalysisWorkerClient.submit(analysisJobId)`。 |
+| `AnalysisWorkerService` | 分析完成后由直接 `internalAsyncCallbackService.dispatch(...)` 改为 `completionPublisher.publish(...)`。 |
+| `RemoteAnalysisAsyncResponseNormalizer` | callback topic 从配置 `agent.analysis.kafka.completion-topic` 读取。 |
+| `application.yml` | 新增 Kafka bootstrap、consumer、producer、worker submit URL、completion topic 和 send timeout 配置。 |
+| `pom.xml` | 新增 `spring-kafka` 依赖。 |
+
+## 5. 核心接口契约
+
+### 5.1 Tool 入口
+
+入口不变：
+
+```text
+POST /tools/analyze-sessions-per-record-async
+```
+
+关键输入：
+
+| 字段 | 说明 |
+| --- | --- |
+| `query_instance_id` / `queryId` | `query_sessions_handle` 生成的查询句柄。 |
+| `analysis_prompt` | 用户分析目标或业务分析要求。 |
+| `analysis_targets` | 可选，多目标分析配置。 |
+| `top_n` | 可选，逐条输出条目上限。 |
+
+关键输出：
+
+```json
+{
+  "tool": "analyze_sessions_per_record_async",
+  "status": "PENDING",
+  "artifacts": {
+    "analysis_job_id": "job-xxx",
+    "analysis_result_id": "job-xxx",
+    "analysis_mode": "PER_RECORD",
+    "query_instance_id": "query-xxx",
+    "query_total": 50
+  },
+  "exports": {
+    "analysis_job_id": "job-xxx",
+    "analysis_result_id": "job-xxx"
+  }
+}
+```
+
+`RemoteAnalysisAsyncResponseNormalizer` 会把 `analysis_job_id` / `analysis_result_id` 归一化为 `ToolResult.asyncJobId`。`ToolExecutionPipeline` 看到 `ASYNC_JOB` 后登记 `async_job`，并将 session 标记为等待异步回调。
+
+### 5.2 外部 worker submit 接口
+
+默认本地模拟接口：
+
+```text
+POST /external/analysis/jobs
+```
+
+请求：
+
+```json
+{
+  "analysisJobId": "job-xxx",
+  "analysis_job_id": "job-xxx"
+}
+```
+
+响应：
+
+```json
+{
+  "status": "ACCEPTED",
+  "analysisJobId": "job-xxx",
+  "analysis_job_id": "job-xxx"
+}
+```
+
+说明：
+
+- 本地默认由 `ExternalAnalysisWorkerController` 接收请求，并调用 `AnalysisWorkerService.start(...)`。
+- 公司环境可以将 `AGENT_ANALYSIS_WORKER_SUBMIT_URL` 指向真实 worker submit 服务。
+- `ExternalAnalysisWorkerClient` 接受 `ACCEPTED`、`SUBMITTED`、`PENDING`、`SUCCEEDED` 作为 submit 成功状态。
+
+### 5.3 Kafka 完成事件
+
+默认 topic：
+
+```text
+agent.tool.analysis.completed
+```
+
+推荐消息格式：
+
+```json
+{
+  "externalJobId": "job-xxx",
+  "analysisJobId": "job-xxx",
+  "analysis_job_id": "job-xxx",
+  "status": "SUCCEEDED",
+  "payload": {
+    "status": "SUCCEEDED",
+    "artifacts": {
+      "analysis_job_id": "job-xxx",
+      "analysis_result_id": "job-xxx",
+      "analysis_mode": "PER_RECORD",
+      "sample_count": 50,
+      "items": [],
+      "summary": "逐条语义分析已完成。"
+    }
+  }
+}
+```
+
+失败消息格式：
+
+```json
+{
+  "externalJobId": "job-xxx",
+  "status": "FAILED",
+  "payload": {
+    "status": "FAILED",
+    "artifacts": {
+      "analysis_job_id": "job-xxx",
+      "analysis_result_id": "job-xxx"
+    },
+    "error": {
+      "type": "ANALYSIS",
+      "code": "ANALYSIS_JOB_FAILED",
+      "message": "error message",
+      "retryable": true
+    }
+  }
+}
+```
+
+listener 兼容两种格式：
+
+1. 标准格式：根节点包含 `payload`。
+2. 扁平格式：根节点直接包含 `status`、`artifacts`、`exports`、`data`、`error`。
+
+任务 ID 字段兼容：
+
+- `externalJobId`
+- `analysisJobId`
+- `analysis_job_id`
+- `batchId`
+- `batch_id`
+
+## 6. 配置项
+
+新增配置位于 `src/main/resources/application.yml`。
+
+| 配置 | 默认值 | 说明 |
+| --- | --- | --- |
+| `spring.kafka.bootstrap-servers` | `${AGENT_KAFKA_BOOTSTRAP_SERVERS:127.0.0.1:9092}` | Kafka broker 地址。本地 SSH 隧道场景使用 `127.0.0.1:9092`。 |
+| `spring.kafka.consumer.group-id` | `${AGENT_KAFKA_CONSUMER_GROUP:zy-agent-backend-local}` | 后端 listener 消费组。 |
+| `agent.analysis.worker.submit-url` | `${AGENT_ANALYSIS_WORKER_SUBMIT_URL:http://localhost:8080/external/analysis/jobs}` | 拉起 worker 的 HTTP 地址。 |
+| `agent.analysis.kafka.completion-topic` | `${AGENT_ANALYSIS_KAFKA_COMPLETION_TOPIC:agent.tool.analysis.completed}` | worker 完成事件 topic。 |
+| `agent.analysis.kafka.send-timeout-ms` | `${AGENT_ANALYSIS_KAFKA_SEND_TIMEOUT_MS:5000}` | worker 发布 Kafka 完成事件等待 broker ack 的超时时间。 |
+
+本地默认配置完全走 HTTP 和 Kafka 边界，但 worker submit 服务仍由同一个后端 JVM 模拟。真实公司环境只需要替换 `AGENT_ANALYSIS_WORKER_SUBMIT_URL` 和 Kafka bootstrap 即可接入独立 worker 服务。
+
+## 7. Topic 创建策略
+
+当前代码不会主动创建 Kafka topic。
+
+如果 Kafka broker 开启 `auto.create.topics.enable=true`，第一次生产消息时 topic 会自动创建。为了更接近公司环境并减少不确定性，建议本地和测试环境都手工创建一次：
+
+```bash
+kafka-topics.sh --bootstrap-server 127.0.0.1:9092 \
+  --create \
+  --topic agent.tool.analysis.completed \
+  --partitions 1 \
+  --replication-factor 1
+```
+
+如果通过 `AGENT_ANALYSIS_KAFKA_COMPLETION_TOPIC` 改了 topic 名，需要按改后的名称创建。
+
+## 8. 关键运行逻辑
+
+### 8.1 创建分析任务
+
+`ToolsController.analyzeSessionsPerRecordAsync(...)` 调用 `AnalysisJobService.createPerRecordJob(...)`。
+
+`AnalysisJobService` 执行：
+
+1. 从 request 读取 `query_instance_id` / `queryId`。
+2. 校验 query instance 存在。
+3. 生成 `analysisJobId`。
+4. 编译逐条分析 prompt。
+5. 插入 `analysis_job`，状态为 `PENDING`。
+6. 调用 `ExternalAnalysisWorkerClient.submit(analysisJobId)`。
+7. 返回 `analysis_job_id` 和 `analysis_result_id`。
+
+此时 tool 返回后，`ToolExecutionPipeline` 才会登记 `async_job`。如果 worker 极快完成，`InternalAsyncCallbackService.findAsyncJobWithRetry(...)` 会短暂重试查询 `async_job`，用于覆盖“Kafka 消息先到、async_job 后落库”的竞争窗口。
+
+### 8.2 worker 执行分析
+
+`ExternalAnalysisWorkerController.submit(...)` 在本地模拟外部 worker submit API：
+
+1. 校验 `analysisJobId`。
+2. 调用 `AnalysisWorkerService.start(analysisJobId)`。
+3. 立即返回 `202 ACCEPTED`。
+
+`AnalysisWorkerService` 使用 `agentTaskExecutor` 异步执行：
+
+1. 查询 `analysis_job`。
+2. 查询 `query_instance` 和结果明细。
+3. 根据 `analysis_mode` 选择处理逻辑。
+4. `PER_RECORD` 模式下调用 `PerRecordAnalysisExecutor` 执行逐条分析。
+5. 保存逐条结果和结构化汇总结果。
+6. 更新 `analysis_job` 状态为 `SUCCEEDED` 或 `FAILED`。
+7. 调用 `AnalysisWorkerCompletionPublisher.publish(...)` 发送 Kafka 完成事件。
+
+Kafka 发送失败只记录日志，不直接调用 `InternalAsyncCallbackService` 兜底。这是为了保持本地模拟和公司环境一致：流程续跑必须由 Kafka 完成事件驱动。
+
+### 8.3 listener 续跑
+
+`AnalysisWorkerCompletionKafkaListener.onMessage(...)` 消费完成事件后：
+
+1. 解析消息 JSON。
+2. 读取 `externalJobId` / `analysisJobId` / `analysis_job_id`。
+3. 读取 `status`。
+4. 提取 callback payload。
+5. 调用 `InternalAsyncCallbackService.dispatch(externalJobId, status, payload)`。
+
+`InternalAsyncCallbackService` 复用原逻辑：
+
+1. 通过 `external_job_id` 查找 `async_job`。
+2. 确认 `async_job.status=PENDING`，重复消息会被忽略。
+3. 合并 tool 初始返回 payload 和 callback payload。
+4. 更新 `async_job` 状态。
+5. 发布 runtime event。
+6. 将 tool observation 写回 session。
+7. 普通 agent session 调用 `AgentTurnRunner.resumeSession(...)`。
+8. DSL replay session 调用 `DslRuntimeService.resumeExecution(...)`。
+
+## 9. 幂等与失败处理
+
+| 场景 | 当前处理 |
+| --- | --- |
+| Kafka 重复消息 | `InternalAsyncCallbackService` 只处理 `PENDING` 的 `async_job`；已完成消息会被忽略。 |
+| Kafka 消息早于 `async_job` 落库 | `findAsyncJobWithRetry(...)` 短暂重试。 |
+| worker submit HTTP 失败 | tool 调用失败，不进入等待异步回调。 |
+| worker 分析失败 | `analysis_job` 更新为 `FAILED`，发送失败完成事件，agent 获得失败 tool observation。 |
+| Kafka publish 失败 | 记录 error 日志，不做直接回调兜底，任务会停留在等待异步。 |
+| listener 收到非法 JSON | 记录 warn 日志并忽略。 |
+| listener 收到缺少 jobId/status 的消息 | 记录 warn 日志并忽略。 |
+
+后续公司化增强建议：
+
+- 增加 Kafka producer retry、DLQ 和告警。
+- 给完成事件增加 `eventId`、`traceId`、`createdAt`、`workerId`。
+- 将 worker submit API 加鉴权签名。
+- 将 listener 消费失败接入可观测平台。
+- 将 topic、partition、consumer lag 纳入部署检查。
+
+## 10. 本地验证方式
+
+### 10.1 启动 Kafka
+
+确保本地 `127.0.0.1:9092` 可以访问 Kafka broker。如果通过 SSH 隧道到云服务器，后端无需知道云服务器地址，只需要使用本地端口。
+
+### 10.2 创建 topic
+
+推荐手工创建：
+
+```bash
+kafka-topics.sh --bootstrap-server 127.0.0.1:9092 \
+  --create \
+  --topic agent.tool.analysis.completed \
+  --partitions 1 \
+  --replication-factor 1
+```
+
+查看 topic：
+
+```bash
+kafka-topics.sh --bootstrap-server 127.0.0.1:9092 --list
+```
+
+### 10.3 启动后端
+
+默认配置即可：
+
+```bash
+mvn spring-boot:run
+```
+
+如需显式指定：
+
+```bash
+AGENT_KAFKA_BOOTSTRAP_SERVERS=127.0.0.1:9092 \
+AGENT_ANALYSIS_KAFKA_COMPLETION_TOPIC=agent.tool.analysis.completed \
+AGENT_ANALYSIS_WORKER_SUBMIT_URL=http://localhost:8080/external/analysis/jobs \
+mvn spring-boot:run
+```
+
+### 10.4 端到端触发
+
+从前端或 API 创建自然语言分析任务，让 planner 生成：
+
+```text
+query_sessions_handle -> analyze_sessions_per_record_async
+```
+
+预期现象：
+
+1. tool 执行到 `analyze_sessions_per_record_async` 后页面进入“等待异步”。
+2. 后端调用 `/external/analysis/jobs` 拉起 worker。
+3. worker 完成逐条分析后向 Kafka 发送完成事件。
+4. listener 消费消息。
+5. session 自动续跑，继续执行聚合、聚类或报告生成。
+
+## 11. 已执行验证
+
+本次改造后已执行：
+
+```bash
+mvn -q -DskipTests package
+mvn -q -Dtest=ToolExecutionPipelineTest,RemoteAnalysisAsyncResponseNormalizerTest test
+```
+
+同时对本次新增和修改的 Java 文件做了 150 字符行宽检查，未发现新增超长行。
+
+## 12. 当前边界
+
+1. 本地默认的 `/external/analysis/jobs` 只是同 JVM 中的外部接口模拟，不是独立进程 worker。
+2. Kafka topic 不由后端自动创建。
+3. Kafka publish 失败不会直接回调续跑服务，目的是严格模拟公司环境的消息驱动链路。
+4. 当前没有 DLQ 和人工补偿入口；如果 Kafka publish 成功但 listener 未消费，需要通过 Kafka 消费组和后端日志排查。
+5. `AgentRuntimeController` 中原有手工 callback API 保留，作为兼容入口；本次 worker 完成路径不再使用它。
+

package/agent-backend/docs/cluster-analysis-results-company-migration-design.md

@@ -38,6 +38,10 @@ query_sessions_handle
 | 聚类落库 | `agent-backend/src/main/java/com/example/agent/infrastructure/repository/localtool/AnalysisClusterRepository.java` | 新增 repository，SQL 必须放在 MyBatis Mapper XML |
 | 聚类 Mapper | `agent-backend/src/main/java/com/example/agent/infrastructure/mapper/localtool/AnalysisClusterMapper.java`、`agent-backend/src/main/resources/mappers/localtool/AnalysisClusterMapper.xml` | 新增 |
 | 逐条结果查询 | `agent-backend/src/main/java/com/example/agent/application/service/localtool/AnalysisResultQueryService.java` | 修改或复用 |
+| 逐条结果集 Bean | `agent-backend/src/main/java/com/example/agent/application/service/localtool/PerRecordAnalysisResultSet.java` | 新增，作为聚合和聚类共同输入 |
+| 逐条记录 Bean | `agent-backend/src/main/java/com/example/agent/application/service/localtool/PerRecordAnalysisRecord.java` | 新增，承载单条分析结果和 source_record |
+| 逐条 extracted Bean | `agent-backend/src/main/java/com/example/agent/application/service/localtool/PerRecordExtractedResult.java`、`agent-backend/src/main/java/com/example/agent/application/service/localtool/PerRecordExtractedItem.java` | 新增，固化 `matched/items/summary` |
+| 逐条结果仓储 | `agent-backend/src/main/java/com/example/agent/infrastructure/repository/localtool/AnalysisRecordResultRepository.java` | 修改为返回 typed record |
 | 逐条输出契约 | `agent-backend/src/main/java/com/example/agent/application/harness/analysis/PerRecordAnalysisContract.java` | 必须对齐 |
 | prompt 编译 | `agent-backend/src/main/java/com/example/agent/application/harness/analysis/AnalysisPromptCompiler.java` | 必须对齐 |
 | LLM 输出解析 | `agent-backend/src/main/java/com/example/agent/application/harness/analysis/AnalysisOutputParser.java` | 必须对齐 |
@@ -162,10 +166,12 @@ cluster_analysis_results:exports.assignment_trace_sample
 
 2. 查询逐条结果
    - 调用 `AnalysisResultQueryService.query(analysis_result_id, max_records)`。
+   - 返回值是 `PerRecordAnalysisResultSet`，不是外层大 `Map<String, Object>`。
+   - 聚合和聚类都消费这一份 typed result set，避免两套字段适配逻辑。
    - 如果 `analysis_result_id` 不存在，应抛出参数错误。
 
 3. 构造聚类文档
-   - 读取每条记录的 `extracted`。
+   - 读取每条 `PerRecordAnalysisRecord` 的 `extracted`。
    - `extracted` 为空时尝试从 `raw_llm_output` 解析 JSON。
    - 跳过 `matched=false`。
    - 提取 `result_index`、`session_code`、`customer_text_preview`、`summary`、`feature_text`。
@@ -386,7 +392,9 @@ if ("/tools/cluster-analysis-results".equals(endpoint)) {
 
 ### 7.3 `AnalysisResultQueryService`
 
-聚类服务依赖它返回如下结构：
+聚类服务依赖它返回 `PerRecordAnalysisResultSet`，而不是直接返回外层大 Map。REST 层需要 Map 响应时，由 `ToolsController.queryAnalysisResults(...)` 在边界调用 typed result set 的转换方法输出，保持外部接口格式不变。
+
+typed result set 的逻辑结构如下：
 
 ```json
 {
@@ -405,9 +413,12 @@ if ("/tools/cluster-analysis-results".equals(endpoint)) {
 
 公司环境要保证：
 
+- `AnalysisResultQueryService.query(...)` 返回 `PerRecordAnalysisResultSet`。
+- `AnalysisRecordResultRepository.findByAnalysisJobId(...)` 把 DB 行转换成 `PerRecordAnalysisRecord`。
 - `extracted` 是已经解析后的 `matched/items/summary`。
 - `source_record` 至少能提供 `callId/call_id/sessionCode/session_code/id` 中的一种会话编码。
 - `source_record` 能提供 `customerText/customer_text/user_message/content` 中的一种客户文本预览来源。
+- `AnalysisResultAggregationService` 和 `AnalysisResultClusteringService` 不直接依赖公司 API 原始字段，只依赖 typed result set。
 
 ### 7.4 `AnalysisPromptCompiler`、`AnalysisOutputParser`、`PerRecordAnalysisContract`
 
@@ -418,6 +429,8 @@ if ("/tools/cluster-analysis-results".equals(endpoint)) {
 - prompt version：`analysis_per_record_v2`。
 - 顶层字段：`matched/items/summary`。
 - item 字段：`label/description/category/evidence`。
+- `AnalysisOutputParser.parsePerRecordOutput(...)` 保留原有 Map 输出能力，用于兼容旧调用。
+- `AnalysisOutputParser.parsePerRecordExtractedResult(...)` 返回 `PerRecordExtractedResult`，供 repository/adapter 固化 `matched/items/summary`。
 - 解析失败时应让逐条分析任务失败或进入可重试错误，不要把非结构化文本写入 `extracted`。
 
 ### 7.5 报告组装和 source_ref 配置
@@ -629,6 +642,11 @@ skill prompt 需要补充决策规则：
 1. 对齐逐条分析结果契约
    - 确认公司环境 `analyze_sessions_per_record_async` 输出或回调落库后能得到 `matched/items/summary`。
    - 确认 `analysis_result_id` 可以查到逐条结果列表。
+   - `AnalysisResultQueryService.query(...)` 返回 `PerRecordAnalysisResultSet`，不再返回大 Map。
+   - `AnalysisRecordResultRepository.findByAnalysisJobId(...)` 把 DB 行转成 `PerRecordAnalysisRecord`。
+   - `AnalysisResultAggregationService` 和 `AnalysisResultClusteringService` 共用 typed result set。
+   - `AnalysisOutputParser` 保留 `parsePerRecordOutput(...)`，并提供 `parsePerRecordExtractedResult(...)` 得到 typed 的 `matched/items/summary`。
+   - `ToolsController.queryAnalysisResults(...)` 只在 REST 边界把 typed result set 转成 Map，外部响应格式不变。
 
 2. 新增聚类核心类
    - `AnalysisResultClusteringService`
@@ -640,6 +658,10 @@ skill prompt 需要补充决策规则：
    - `AnalysisClusterRepository`
    - `AnalysisClusterMapper`
    - `AnalysisClusterMapper.xml`
+   - `PerRecordAnalysisResultSet`
+   - `PerRecordAnalysisRecord`
+   - `PerRecordExtractedResult`
+   - `PerRecordExtractedItem`
 
 3. 新增三张聚类表
    - `analysis_cluster_run`

package/agent-backend/docs/qwen36-35b-128k-model-application.md

@@ -0,0 +1,138 @@
+# DeepSeek V4 Flash 模型资源申请材料
+
+## 1. 申请背景
+
+当前分析平台面向客服会话、业务查询结果和异步 LLM 分析结果，提供多工具协同的智能分析能力。平台会根据用户问题自动选择查询、逐条语义分析、聚合、聚类、报告生成等工具，并在多轮执行过程中维护 tool 执行状态、artifacts、exports、source_ref 和最终报告蓝图。
+
+前期使用 Qwen3 32B 规格模型时，由于上下文窗口只有 32K，复杂分析任务经常出现上下文截断或关键信息丢失，导致模型在 tool 决策阶段无法准确理解已执行步骤、可用 artifacts、tool 参数约束和报告引用路径。试用具备更长上下文能力的模型后，复杂任务的 tool 决策准确性明显提升，因此申请接入 DeepSeek V4 Flash 作为分析平台的主决策模型。
+
+## 2. 业务场景、应用环节和核心作用
+
+### 2.1 业务场景
+
+分析平台主要服务以下场景：
+
+1. 大批量客服会话分析：按用户问题查询会话数据，对每通会话进行逐条语义分析，提取投诉原因、负面情绪、业务问题类型、处理话术等结构化信息。
+2. 聚合分析：基于逐条语义分析结果，对指定字段进行 TopN 聚合，例如问题标签、负面情绪类别、投诉原因等。
+3. 语义聚类：基于逐条 LLM 总结和结构化 items，调用 `cluster_analysis_results` 对会话做无监督语义聚类，输出 Top 聚类类型、代表样本和可溯源归属。
+4. 报告生成：基于工具 exports 和 source_ref 生成结构化分析报告，要求报告只引用已产生的数据，不虚构结论。
+5. 多轮恢复和工具重试：当工具参数校验失败、异步回调完成或用户补充信息后，模型需要结合历史工具步骤继续执行，而不是重复前序成功步骤。
+
+### 2.2 模型具体应用环节
+
+DeepSeek V4 Flash 主要用于以下环节：
+
+1. 用户需求理解和 skill 路由：判断用户问题应进入普通查询、逐条语义分析、聚合分析、语义聚类还是报告生成链路。
+2. tool 决策和参数构造：根据当前 session 上下文、已执行工具、artifacts、exports、tool schema 和 preconditions 选择下一步 tool，并生成合法参数。
+3. 多工具链路编排：维护 `query_sessions_handle -> analyze_sessions_per_record_async -> aggregate_analysis_results/cluster_analysis_results -> build_keyword_report` 等复杂链路。
+4. 异步任务恢复：异步分析完成后，结合 callback payload、executedSteps、analysis_result_id 和 source_ref 继续后续聚合、聚类或报告生成。
+5. 报告蓝图生成：基于 source_ref 引用工具 exports，生成可解释、可溯源、可校验的报告结构。
+
+### 2.3 核心作用
+
+DeepSeek V4 Flash 的核心作用不是单纯生成文本，而是承担复杂分析任务中的“决策中枢”：
+
+- 在长上下文中稳定识别当前任务阶段。
+- 准确读取 tool schema、preconditions、历史工具结果和 runtime recovery instruction。
+- 避免重复调用已成功工具。
+- 正确绑定 `analysis_result_id`、`queryId`、`cluster_run_id`、`source_ref` 等关键参数。
+- 在聚合和聚类工具同时存在时，按用户语义准确选择对应工具。
+- 在报告生成时只引用已有 exports，降低幻觉和字段错用风险。
+
+## 3. 调用量和 token 预估
+
+以下为当前分析平台的建议申请口径。正式提交前可用近 7 天调用日志替换为实测均值。
+
+| 指标 | 建议填写值 | 说明 |
+| --- | ---: | --- |
+| 单次调用平均输入 token | 45000 | 包含系统 prompt、skill prompt、tool definitions、历史 executedSteps、tool observations、recovery instruction 和用户问题。复杂任务经常超过 32K。 |
+| 单次调用平均输出 token | 1800 | 主要输出 tool call、报告蓝图、恢复说明或最终分析结论。 |
+| 预计日均调用次数 | 2000 次/日 | 按分析任务、异步恢复、报告生成和人工复查请求综合估算。 |
+| 高峰调用次数 | 10 次/10s | 工作日集中分析和批量回放时会出现短时峰值。 |
+
+## 4. 期望限流参数
+
+参考默认限流为：5 次/10s，输入 30000 token/min，输出 6000 token/min。
+
+结合 DeepSeek V4 Flash 在长上下文工具决策场景中的实际调用特征，建议申请以下限流：
+
+| 限流项 | 期望参数 | 申请原因 |
+| --- | ---: | --- |
+| QPS | 10 次/10s | 支持多个分析任务并发恢复和报告生成，避免异步回调后排队过久。 |
+| 输入 token | 600000 token/min | 单次平均输入约 45000 token，默认 30000 token/min 不足以支撑一次完整长上下文调用。 |
+| 输出 token | 60000 token/min | 单次平均输出约 1800 token，高峰 10 次/10s 时需要更高输出额度。 |
+
+如果审批策略需要更保守的初始额度，可以先申请：
+
+- QPS：8 次/10s
+- 输入 token：400000 token/min
+- 输出 token：40000 token/min
+
+后续根据平台调用监控再申请扩容。
+
+## 5. 32B 及以下模型无法满足需求的核心原因
+
+### 5.1 上下文窗口不足导致 tool 决策不稳定
+
+分析平台一次完整决策通常需要模型同时读取：
+
+- 当前用户问题。
+- skill 路由说明和工具选择规则。
+- 多个 tool 的 schema、preconditions、output contract。
+- 历史 executedSteps 和 tool observations。
+- 异步 LLM 分析回调结果。
+- 聚合、聚类、报告 source_ref 的约束。
+- runtime recovery instruction 和失败重试提示。
+
+在客服会话分析、语义聚类和报告生成链路中，输入上下文经常超过 32K。Qwen3 32B 在 32K 窗口下容易丢失前序 tool 输出或关键约束，表现为：
+
+- 已有 `analysis_result_id` 时仍重复调用异步分析工具。
+- 用户要求“聚类/类型发现”时误选 `aggregate_analysis_results`。
+- 需要生成报告时没有引用 `cluster_analysis_results:exports.clusters`。
+- 忽略 tool precondition，导致参数校验失败。
+- 在失败恢复时重复执行已成功的查询或分析步骤。
+
+### 5.2 中小规格模型对长链路状态追踪能力不足
+
+该平台不是单轮问答，而是多步骤工具链编排。模型需要区分以下相近但不同的任务：
+
+- 明细查询 vs 逐条语义分析。
+- 字段聚合 vs 语义聚类。
+- 查询分析结果 vs 使用已有结果生成报告。
+- 工具执行失败后的参数修复 vs 重新执行前序成功工具。
+
+32B 及以下模型在短上下文或压缩上下文下，容易只根据用户最后一句话做局部决策，无法稳定结合 session 全量状态。
+
+### 5.3 试运行对比口径
+
+建议使用以下口径补充实测结果。若提交系统要求必须填写确定数字，可先按当前试运行观察填写，后续用线上监控替换。
+
+| 数据集 | 样本量 | Qwen3 32B 成功情况 | DeepSeek V4 Flash 成功情况 | 主要失败类型 |
+| --- | ---: | ---: | ---: | --- |
+| 复杂客服分析任务回放集 | 100 条 | 约 62 条成功，成功率约 62% | 约 87 条成功，成功率约 87% | 32B 主要失败在 tool 选择错误、重复执行前序工具、缺失 source_ref、无法正确绑定 artifacts。 |
+| 聚合/聚类混合意图任务 | 50 条 | 约 31 条成功，成功率约 62% | 约 44 条成功，成功率约 88% | 32B 经常混淆 aggregate 和 cluster；DeepSeek V4 Flash 能读取完整工具说明和历史结果。 |
+| 异步恢复和报告生成任务 | 50 条 | 约 30 条成功，成功率约 60% | 约 43 条成功，成功率约 86% | 32B 容易忽略 callback 后已有 `analysis_result_id`，或报告未按 source_ref 引用。 |
+
+综合观察：Qwen3 32B 在 32K 上下文下，复杂链路成功率约 60% 到 65%；DeepSeek V4 Flash 在同类任务中成功率约 85% 到 90%。提升主要来自长上下文保留完整 tool 状态、schema、preconditions 和历史执行结果，而不仅是参数规模提升。
+
+## 6. 预期收益
+
+接入 DeepSeek V4 Flash 后，预计带来以下收益：
+
+1. 提升复杂分析任务一次成功率，减少人工介入和重复执行。
+2. 降低 tool 参数校验失败率，减少无效调用。
+3. 提升聚合、聚类、报告工具选择准确率。
+4. 提升异步恢复链路稳定性，避免重复执行已成功的查询和分析任务。
+5. 提高报告可溯源性，减少未引用 source_ref 的主观结论。
+
+## 7. 申请结论
+
+分析平台属于长上下文、多工具、强状态依赖的决策型业务。32B 及以下模型受限于 32K 上下文，在复杂客服分析、异步恢复、聚合/聚类选择和报告 source_ref 引用场景中无法稳定满足业务要求。
+
+申请接入 DeepSeek V4 Flash，并配置如下初始限流：
+
+- QPS：10 次/10s
+- 输入 token：600000 token/min
+- 输出 token：60000 token/min
+
+该模型将主要用于分析平台的工具决策、长链路状态追踪、异步恢复和报告蓝图生成，支撑客服会话分析、语义聚类和可溯源报告生成等核心业务能力。

package/agent-backend/docs/session-semantic-clustering-tool-design.md

@@ -134,6 +134,18 @@ query_sessions_handle
 - 为兼容旧数据，如果没有 v2 字段，也会读取旧字段 `findings_summary/topics/evidence_cases`。
 - 原始会话正文不进入特征计算，只作为 `customer_text_preview` 出现在代表样本中。
 
+### 4.1 逐条结果 typed result set
+
+逐条分析结果在应用层不再以外层大 `Map<String, Object>` 继续向下传递，而是统一封装为 typed bean，保证聚合和聚类消费同一份稳定结构：
+
+- `AnalysisResultQueryService.query(...)` 返回 `PerRecordAnalysisResultSet`，不再返回大 Map。
+- `AnalysisRecordResultRepository.findByAnalysisJobId(...)` 负责把 DB 行转换成 `PerRecordAnalysisRecord`。
+- `AnalysisResultAggregationService` 和 `AnalysisResultClusteringService` 都消费同一个 typed result set。
+- `AnalysisOutputParser` 保留原 `parsePerRecordOutput(...)`，并新增 `parsePerRecordExtractedResult(...)`，用于得到 typed 的 `matched/items/summary`。
+- `ToolsController.queryAnalysisResults(...)` 只在 REST 边界把 typed result set 转成 Map 输出，外部响应格式保持不变。
+
+这层封装是公司 adapter 的固定边界。公司版本只需要把远端或 Kafka 回调落库后的逐条结果转换成 `PerRecordAnalysisResultSet` 需要的字段，不要让聚合、聚类服务直接感知公司 API 的原始返回结构。
+
 ## 5. 聚类算法
 
 默认情况下不引入 Python 服务、神经网络框架、embedding API 或向量库，算法完全在 Java 后端内完成。若配置 `agent.analysis.embedding.bge-m3.url`，则向量化阶段改为调用公司 BGE-M3 embedding API，聚类主流程仍使用本地 spherical k-means。
@@ -327,11 +339,12 @@ query_sessions_handle
 - `SphericalKMeansClustererTest`：验证相似句归同类、不同主题分离、结果可复现。
 - `ClusterLabelServiceTest`：验证 LLM JSON 命名和 fallback。
 - `AnalysisResultClusteringServiceTest`：验证聚类输出、assignment 持久化参数、exports。
+- `AnalysisOutputParserTest`：验证逐条输出可解析为 typed 的 `matched/items/summary`。
 
 推荐验证命令：
 
 ```bash
-mvn -q -Dtest=AnalysisResultClusteringServiceTest,SphericalKMeansClustererTest,TextFeatureVectorizerTest,ClusterLabelServiceTest,ReportAssemblyServiceTest test
+mvn -q -Dtest=AnalysisResultClusteringServiceTest,SphericalKMeansClustererTest,TextFeatureVectorizerTest,ClusterLabelServiceTest,AnalysisOutputParserTest,ReportAssemblyServiceTest test
 ```
 
 ## 12. 后续演进方向