|
|
@@ -0,0 +1,704 @@
|
|
|
+# 持续联系 · AI 研判功能 设计文档
|
|
|
+
|
|
|
+> 范围：`ai-frontend/src/call/views/continuous/`（持续联系页）新增「AI 研判」能力
|
|
|
+> 目标：把当前查询结果交给专用 Agent 解读，产出**有价值的线索** + **下一步思路**
|
|
|
+> 状态：设计待确认，未开始编码
|
|
|
+>
|
|
|
+> 关键决策速览：入口只做面板级主按钮（§2.1）｜右抽屉面板（§2.2）｜结构化围栏 + 卡片（§3）｜
|
|
|
+> **会话与消息入库，独立两张表 + 普通分页滚动加载（§4.1）** ｜后端落 `module/agent/insight/`（§4.2）｜
|
|
|
+> 独立 Agent 实例池 + 动态 sysPrompt（§4.3）
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 1. 功能定位
|
|
|
+
|
|
|
+一句话：**在"持续联系对象汇总"表格旁边，开一个能读懂这批数据的研判助手。**
|
|
|
+
|
|
|
+它不做通用问答，只干四件事：
|
|
|
+
|
|
|
+| # | 产出 | 说明 |
|
|
|
+|---|---|---|
|
|
|
+| 1 | **解读摘要** | 这批持续联系关系的整体特征：覆盖几人、最长/最短关系、月均密度分布、异常点在哪 |
|
|
|
+| 2 | **价值线索（Clues）** | 分级（高/中/低）的可落地线索，每条带**具体数字证据** + **可疑理由** + **建议核验动作** |
|
|
|
+| 3 | **下一步思路（Next Steps）** | 可执行动作清单，每条指明"在哪做"（跳转到对应页面/工具） |
|
|
|
+| 4 | **追问下钻** | 对任一条线索继续追问，走普通对话流（复用现有富渲染块） |
|
|
|
+
|
|
|
+### 1.1 线索类型（沿用 `AI_AGENT.md` 领域术语）
|
|
|
+
|
|
|
+| 线索类型 | 触发特征（从持续联系数据可判） |
|
|
|
+|---|---|
|
|
|
+| 通联异常 | 深夜/凌晨占比显著偏高；月数很长但月内次数极低（"养号式"维系）；单向高频 |
|
|
|
+| 攻守同盟 | 星型结构：多个对象 → 同一对方号码，或同一对方 ↔ 多个本方 |
|
|
|
+| 身份不明对手 | `otherName = 未知对手` / `otherPhone = 未知号码`，但持续多月高频联系 |
|
|
|
+| 反常断联 | 连续多月后在某月骤停（可能对应被采取强制措施、外逃、换号） |
|
|
|
+| 敏感日期命中 | 特殊日期仍保持联系（**需交叉验证**，激活 `call` 组下钻） |
|
|
|
+| 白手套 / 时空伴随 | 需跨域佐证（`trans` / `track` 组），由 Agent 自行按需激活工具组 |
|
|
|
+
|
|
|
+> 最后两类**不能只凭本表推断**，Agent 必须先调工具取数再下结论——这一点写进提示词硬约束。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 2. 交互与入口设计
|
|
|
+
|
|
|
+### 2.1 入口：面板级主按钮（**已定：本期只做主按钮**）
|
|
|
+
|
|
|
+| 编号 | 入口位置 | 语义 | 携带上下文 |
|
|
|
+|---|---|---|---|
|
|
|
+| **E1 主入口** | 「持续联系对象汇总」卡片标题栏右侧 —— `AI 研判` 主按钮（描边高亮 + `i-mdi:auto-fix` 图标） | 分析**当前整个查询结果集** | 完整查询条件 + 结果快照（按持续月数降序取 TOP N，默认 100） |
|
|
|
+| **E2 空态引导** | 未查询时的 `EmptyState` 下方一行小字 + 按钮 | 引导先查询 | 无 |
|
|
|
+
|
|
|
+- **表格操作列保持原样**（仍是 `buildTableActionColumn`，只有「查看详情」，列宽不动）。
|
|
|
+- E1 禁用态：`!hasSearched || !tableData.length`，tooltip 提示原因（"请先查询" / "当前无数据"）。
|
|
|
+- 无默认模型 / 未打开案件 → 按钮禁用 + 明确文案，不发请求。
|
|
|
+
|
|
|
+> **行级入口（单条关系对「AI 解读」）本期不做。**
|
|
|
+> 表结构保留 `scope` 字段（`BATCH` / 预留 `PAIR`），后续要加行级入口时只需补一个按钮，
|
|
|
+> 后端 Service 与存储无需改动。
|
|
|
+
|
|
|
+### 2.2 面板形态：三个方案对比
|
|
|
+
|
|
|
+| 方案 | 形态 | 优点 | 缺点 | 结论 |
|
|
|
+|---|---|---|---|---|
|
|
|
+| **A 右侧抽屉** ✅ | 从右滑出，宽 640px（可拖拽 480–1000） | 表格保留在左侧，可**边看边问**；不丢上下文；实现成本最低 | 横向空间有限，长报告需滚动 | **推荐** |
|
|
|
+| B 内嵌右分栏 | 表格右侧常驻 380–420px | 零点击即见 | 本页筛选条 + 6 列表格已很满，1680 宽以下横向挤压；AI 区大部分时间是空的 | 否 |
|
|
|
+| C 独立全屏页 | 跳 `/call/continuous/insight` | 空间大，适合长报告 | 割裂，丢失"边看边问"；且与 AI 数据分析页的会话混在一起（与"独立存储"诉求相悖） | 否（保留为升级路径） |
|
|
|
+| D 底部气泡/悬浮球 | 悬浮面板 | 存在感低 | 不适合需要长阅读与翻页表格的报告 | 否 |
|
|
|
+
|
|
|
+**采纳 A，并在抽屉右上角留「全屏」按钮**：全屏复用同一组件铺满容器（CSS 切换），不新建页面。
|
|
|
+
|
|
|
+### 2.3 抽屉内部五段结构（自上而下）
|
|
|
+
|
|
|
+```
|
|
|
+┌─ ① Header ──────────────────────────────────────────────┐
|
|
|
+│ AI 研判 · 持续联系 [↻重新分析][▤历史][⛶全屏][✕] │
|
|
|
+├─ ② ContextBar（固定，不可滚）────────────────────────────┤
|
|
|
+│ ◈ 对象 3 人 ◈ 月数 ≥2 ◈ 2024-01-01~2024-12-31 ◈ 128 对 │
|
|
|
+│ 已按持续月数降序取前 100 对进行研判 │
|
|
|
+├─ ③ Report / ④ Chat（滚动区）────────────────────────────┤
|
|
|
+│ [结论摘要卡] │
|
|
|
+│ ┌ 线索卡 #1 ●高价值 通联异常 ─────────────────────────┐ │
|
|
|
+│ │ 标题 / 证据 / 可疑点 / 建议核验 │ │
|
|
|
+│ │ [查看话单][地图][深挖][记入线索] │ │
|
|
|
+│ └──────────────────────────────────────────────────────┘ │
|
|
|
+│ ┌ 线索卡 #2 … ┐ │
|
|
|
+│ [下一步思路 · 编号清单 + 跳转按钮] │
|
|
|
+│ [▸ 分析过程（默认折叠，含工具调用时间线）] │
|
|
|
+│ ─── 以下为追问对话（复用现有消息组件）─── │
|
|
|
+├─ ⑤ Composer（固定底）──────────────────────────────────┤
|
|
|
+│ [预设追问 chip ×3] ┌──────────────────────┐ [发送] │
|
|
|
+│ │ 追问… │ │
|
|
|
+└─────────────────────────────────────────────────────────┘
|
|
|
+```
|
|
|
+
|
|
|
+**关键交互**
|
|
|
+
|
|
|
+1. **打开即自动分析**：不用敲字。抽屉开启 → 调 `POST /insight/continuous/sessions` → 立刻 `POST /insight/continuous/stream`（首轮 message 为空，服务端注入固定首轮指令）。
|
|
|
+2. **首轮流式体验**：骨架屏 → 过程时间线（"正在统计分布 / 正在比对同案基线…"）→ 逐段吐字。过程区默认折叠，不喧宾夺主。
|
|
|
+3. **结构化优先**：首轮由 `` ```insight `` 围栏输出结构化 JSON → 前端渲染成卡片；模型若未吐围栏则**自动降级**为 Markdown 报告（不空屏）。
|
|
|
+4. **`maskClosable=false`**：防止误点遮罩丢流；关闭时若有流在跑，先中止（复用现有 `AbortController` 语义）。
|
|
|
+5. **条件变更不打断**：抽屉开着时用户改了筛选条件并查询 → ContextBar 顶部浮出「条件已变更，可重新分析」提示条，点「重新分析」才开新会话。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 3. 结构化输出契约（```insight 围栏）
|
|
|
+
|
|
|
+这是"线索 + 下一步思路"能被**渲染成可用 UI**（而不是一坨文字）的前提。
|
|
|
+
|
|
|
+```jsonc
|
|
|
+{
|
|
|
+ "summary": "本次识别 128 对持续联系关系，覆盖 7 名对象；最长一对连续 14 个月……",
|
|
|
+ "metrics": [
|
|
|
+ { "label": "关系对", "value": "128" },
|
|
|
+ { "label": "平均持续", "value": "4.2 月" },
|
|
|
+ { "label": "身份不明对手", "value": "9" }
|
|
|
+ ],
|
|
|
+ "clues": [
|
|
|
+ {
|
|
|
+ "id": "C1",
|
|
|
+ "level": "high", // high | medium | low
|
|
|
+ "type": "通联异常",
|
|
|
+ "title": "张三 ↔ 138****1111 连续 11 个月深夜联系",
|
|
|
+ "subjects": { "self": "张三", "otherName": "李四", "otherPhone": "138xxxx1111" },
|
|
|
+ "evidence": [
|
|
|
+ "连续 11 个月（2024-01 ~ 2024-11）",
|
|
|
+ "通话 218 次，62% 落在 23:00–03:00"
|
|
|
+ ],
|
|
|
+ "reason": "深夜占比显著高于同案关系对均值 12%，且持续时长与通话密度背离常理",
|
|
|
+ "nextActions": ["拉取该对全部话单核对基站落点", "核验 138****1111 的实名人"],
|
|
|
+ "links": [
|
|
|
+ { "label": "查看话单", "action": "openCallRecord", "params": { "personName": "张三", "otherPhones": ["138..."], "startDate": "2024-01-01", "endDate": "2024-11-30" } }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+ ],
|
|
|
+ "nextSteps": [
|
|
|
+ {
|
|
|
+ "order": 1,
|
|
|
+ "title": "对 3 个高价值关系对做基站时空碰撞",
|
|
|
+ "purpose": "确认持续联系是否伴随线下见面",
|
|
|
+ "entry": { "label": "时空碰撞", "route": "/track/meet" }
|
|
|
+ }
|
|
|
+ ],
|
|
|
+ "caveats": ["本表为汇总口径，未含通话时长与基站信息；结论需下钻话单核验"]
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**落地要点**
|
|
|
+
|
|
|
+- 后端在新 Agent 的 sysPrompt 里追加**专属**渲染契约（不复用也不污染 `AgentService#appendRenderPrompt` 的通用契约）。
|
|
|
+- 前端扩展点（三处小改，纯增量）：
|
|
|
+ - `ai/utils/constants.ts`：`BlockKind` 加 `'insight'`；`FENCE_BLOCK_MAP` 加 `insight: 'insight'`
|
|
|
+ - `ai/utils/scanner.ts`：围栏识别自动覆盖（按 map 查表）
|
|
|
+ - `ai/components/BlockRenderer.vue`：加一个分支 → 新组件 `blocks/InsightBlock.vue`
|
|
|
+- **校验与降级**：解析后做轻量结构校验（`clues` 是数组、每条有 `title/evidence`）；不合法或未解析 → 保留原始 Markdown 文本渲染，绝不白屏。
|
|
|
+- SSE 额外下发一帧 `insight`（结构化对象）：前端不必等 token 拼完就能先渲染卡片骨架，体验更稳。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 4. 后端设计
|
|
|
+
|
|
|
+### 4.1 会话存储：数据库表设计（**已定：入库，独立于现有 agent 三表**）
|
|
|
+
|
|
|
+> 本节是本设计的重点。会话与消息**入库**，但**不复用** `agent_chat_session` / `agent_message`，
|
|
|
+> 另建两张独立表 `agent_insight_session` / `agent_insight_message`。
|
|
|
+> 「隔离」由**独立表 + `case_id` 归属 + 外键级联 + 强制 where** 建立；
|
|
|
+> 「滚动加载」由**普通分页接口 + 会话内单调 `seq` 稳定排序**支撑。
|
|
|
+
|
|
|
+#### 4.1.1 隔离策略
|
|
|
+
|
|
|
+本项目已移除用户体系（`AgentChatServiceImpl.RUNTIME_USER_ID = "default"`），因此**不需要用户维度**。
|
|
|
+实际生效的是三层：
|
|
|
+
|
|
|
+| 层 | 隔离对象 | 靠什么 |
|
|
|
+|---|---|---|
|
|
|
+| **1. 表级** | 与通用对话分开 | 独立表名 `agent_insight_*`，与 `agent_chat_session` / `agent_message` **物理分离**；两边 Service / Mapper 零交叉引用，也不共用 `AgentService` 的会话方法 |
|
|
|
+| **2. 案件级** | **硬边界** | 会话行必带 `case_id`；所有列表查询**强制** `WHERE case_id = ?`；案件删除时 `ON DELETE CASCADE` 连带清理 |
|
|
|
+| **3. 会话级** | 分析单元 | 消息行必带 `session_id`，且查询**必须同时命中 `case_id`**（见下方不变量） |
|
|
|
+
|
|
|
+**三条不变量（写成测试，不靠 code review）：**
|
|
|
+
|
|
|
+1. **不存在只按 `session_id` 查消息的 SQL** —— 消息列表/详情一律
|
|
|
+ `WHERE session_id = ? AND case_id = ?`。因此消息表**冗余一列 `case_id`**，让这条约束在 SQL 层面就能写出来。
|
|
|
+2. **写消息前先校验会话归属** —— 先取 `agent_insight_session.case_id` 与入参比对，不一致直接 `403`，再落库。
|
|
|
+3. **`biz_type` 恒为常量** —— 首期恒 `'CALL_CONTINUOUS'`，作为「同表将来扩其它研判场景」的预留维度；
|
|
|
+ 所有查询默认带上它，避免将来多场景共表时串数据。
|
|
|
+
|
|
|
+> **为什么消息表冗余 `case_id`（违背范式）**：只靠 `session_id` JOIN 会话表也能过滤 `case_id`，
|
|
|
+> 但那让每个新写的查询都有「忘记带 case_id」的机会。冗余一列 + 联合索引，代价极小，
|
|
|
+> 换来「越权查询在 SQL 层面就写不出来」的强约束 —— 这正是文件方案（§4.1.8 对比）拿不到的保护网。
|
|
|
+
|
|
|
+#### 4.1.2 表结构
|
|
|
+
|
|
|
+DDL 落 `sql/`（沿用项目现有目录与命名习惯）。字段风格**对齐现有的 `agent_chat_session` / `agent_message`**：
|
|
|
+时间列用 `create_at` / `update_at`（`LocalDateTime`，`@TableField(fill = FieldFill.INSERT / INSERT_UPDATE)`），
|
|
|
+半结构化数据用 `jsonb`（`@TableField(typeHandler = JsonbTypeHandler.class, jdbcType = JdbcType.OTHER)`）。
|
|
|
+字段命名也与 `agent_message` 保持一致（`role` / `content` / `content_type` / `token_count` / `metadata` /
|
|
|
+`tool_events` / `message_type` / `reply_to_message_id` / `starred`），便于对照与复用既有前端解析逻辑 ——
|
|
|
+本表只**新增** `seq` / `case_id` / `output_json` / `status` 四个字段。
|
|
|
+
|
|
|
+```sql
|
|
|
+-- ============================================================
|
|
|
+-- AI 研判 · 会话表（独立于 agent_chat_session）
|
|
|
+-- ============================================================
|
|
|
+CREATE TABLE agent_insight_session (
|
|
|
+ id BIGINT PRIMARY KEY, -- 应用侧生成（见 §4.1.3 注意点）
|
|
|
+ case_id BIGINT NOT NULL, -- ★ 案件级硬隔离边界
|
|
|
+ biz_type VARCHAR(32) NOT NULL DEFAULT 'CALL_CONTINUOUS',
|
|
|
+ scope VARCHAR(16) NOT NULL DEFAULT 'BATCH', -- BATCH | PAIR(预留)
|
|
|
+ agent_row_id BIGINT, -- 使用的 agent 配置行
|
|
|
+ model_id BIGINT NOT NULL, -- 创建时定的默认模型，会话内不变
|
|
|
+ title VARCHAR(128), -- 「持续联系研判 · 2024-12-01 14:32」
|
|
|
+ context JSONB NOT NULL, -- ★ 查询条件 + 结果快照（动态 sysPrompt 的数据源）
|
|
|
+ context_hash VARCHAR(64) NOT NULL, -- context 的 sha256，用于同条件复用/去重提示
|
|
|
+ sys_prompt TEXT NOT NULL, -- ★ 实际使用的完整 sysPrompt，会话内不可变
|
|
|
+ message_count INT NOT NULL DEFAULT 0, -- 消息条数（列表页直读，不 count(*)）
|
|
|
+ last_seq BIGINT NOT NULL DEFAULT 0, -- ★ 会话内消息序号水位（原子分配用）
|
|
|
+ total_tokens BIGINT NOT NULL DEFAULT 0,
|
|
|
+ last_message_at TIMESTAMP, -- 最后活动时间（列表排序用）
|
|
|
+ pinned BOOLEAN NOT NULL DEFAULT FALSE,
|
|
|
+ status VARCHAR(16) NOT NULL DEFAULT 'ACTIVE', -- ACTIVE | STREAMING | ARCHIVED
|
|
|
+ create_at TIMESTAMP NOT NULL DEFAULT now(),
|
|
|
+ update_at TIMESTAMP NOT NULL DEFAULT now()
|
|
|
+);
|
|
|
+CREATE INDEX idx_ais_case_list ON agent_insight_session (case_id, biz_type, last_message_at DESC);
|
|
|
+CREATE INDEX idx_ais_ctx_hash ON agent_insight_session (case_id, context_hash);
|
|
|
+
|
|
|
+COMMENT ON TABLE agent_insight_session IS 'AI研判会话（独立存储，不复用通用对话表）';
|
|
|
+COMMENT ON COLUMN agent_insight_session.context IS '查询条件+结果快照，动态系统提示词的数据源';
|
|
|
+COMMENT ON COLUMN agent_insight_session.last_seq IS '会话内消息序号水位，消息 seq 由它原子分配';
|
|
|
+
|
|
|
+-- ============================================================
|
|
|
+-- AI 研判 · 消息表
|
|
|
+-- ============================================================
|
|
|
+CREATE TABLE agent_insight_message (
|
|
|
+ id BIGINT PRIMARY KEY,
|
|
|
+ session_id BIGINT NOT NULL,
|
|
|
+ case_id BIGINT NOT NULL, -- ★ 冗余，保证消息查询永远可带 case_id
|
|
|
+ seq BIGINT NOT NULL, -- ★ 会话内递增，分页排序列
|
|
|
+ role VARCHAR(16) NOT NULL, -- user | assistant | system
|
|
|
+ content TEXT, -- 正文
|
|
|
+ content_type VARCHAR(16) NOT NULL DEFAULT 'text', -- text | insight
|
|
|
+ message_type VARCHAR(16) NOT NULL DEFAULT 'chat', -- chat | first_round(首轮自动分析) | followup
|
|
|
+ metadata JSONB, -- 思考过程/中断标记/耗时等轻量字段
|
|
|
+ tool_events JSONB, -- ★ 工具调用明细（大，列表查询不 select）
|
|
|
+ output_json JSONB, -- ★ ```insight 结构化产物（首轮 assistant 才有）
|
|
|
+ token_count INT NOT NULL DEFAULT 0,
|
|
|
+ reply_to_message_id BIGINT, -- 追问指向的首轮消息（UI 分组用）
|
|
|
+ starred BOOLEAN NOT NULL DEFAULT FALSE,
|
|
|
+ status VARCHAR(16) NOT NULL DEFAULT 'DONE', -- DONE | INTERRUPTED
|
|
|
+ create_at TIMESTAMP NOT NULL DEFAULT now(),
|
|
|
+
|
|
|
+ CONSTRAINT uk_aim_session_seq UNIQUE (session_id, seq),
|
|
|
+ CONSTRAINT fk_aim_session FOREIGN KEY (session_id)
|
|
|
+ REFERENCES agent_insight_session (id) ON DELETE CASCADE
|
|
|
+);
|
|
|
+
|
|
|
+-- 线索聚合（为「线索推送」页预留）：按案件捞有结构化产物的消息
|
|
|
+CREATE INDEX idx_aim_output ON agent_insight_message (case_id, create_at DESC)
|
|
|
+ WHERE output_json IS NOT NULL;
|
|
|
+
|
|
|
+COMMENT ON COLUMN agent_insight_message.seq IS '会话内单调序号，分页排序列（勿用 create_at/id 排序）';
|
|
|
+COMMENT ON COLUMN agent_insight_message.case_id IS '冗余自会话表：保证消息查询永远可带 case_id 过滤';
|
|
|
+```
|
|
|
+
|
|
|
+**字段取舍说明**
|
|
|
+
|
|
|
+| 决策 | 理由 |
|
|
|
+|---|---|
|
|
|
+| **不给工具事件单独建表** | 工具事件只是「一段挂在消息上的展示数据」，从来没有独立查询它的需求；`jsonb` 一列足够。单独建表会引入「逐条追加/更新事件行」的额外写放大，收益为零 |
|
|
|
+| **`sys_prompt` 存全量文本** | 它是「同一条会话为什么给出这个结论」的复现依据（含口径说明）。**不通过任何接口下发**，仅运维/追溯读 |
|
|
|
+| **大字段不拆表** | `tool_events` / `output_json` 留在同表：PG 大字段走 TOAST 行外存储，**列表查询不 select 它就不会被读出来**，性能损失可忽略；拆表反而让「拉一条消息 + 拉它的事件」变成两次往返 |
|
|
|
+| **不存 token 级增量** | 正文只保留终态（见 §4.1.6），避免流式过程中每分钟数百次 UPDATE |
|
|
|
+| **`idx_aim_output` 用部分索引** | 只有首轮 assistant 消息有 `output_json`，占总量不到 10%；部分索引体积小、命中准 |
|
|
|
+
|
|
|
+#### 4.1.3 排序为什么必须有 `seq`（而不是 `id` / `create_at`）
|
|
|
+
|
|
|
+**分页接口用普通分页（`page` / `pageSize`），但 `ORDER BY` 必须落在一个可靠的列上** —— 本项目两个现成方案都不行：
|
|
|
+
|
|
|
+| 候选 | 为什么不能用 |
|
|
|
+|---|---|
|
|
|
+| `id` | 实体虽然标了 `@TableId(type = IdType.ASSIGN_ID)`，但现有代码在 `AgentChatServiceImpl` 里**显式 `setId(generateId())` 覆盖掉**，而 `generateId()` = `UUID.randomUUID().getMostSignificantBits() & Long.MAX_VALUE` —— **随机、非单调**。拿它 `ORDER BY` 会让消息顺序彻底乱掉 |
|
|
|
+| `create_at` | 首轮一次落 2 条、追问落 1 条，**同毫秒极常见** → `ORDER BY create_at` 顺序不确定，翻页会重复或漏行；时钟抖动还会让顺序跳变 |
|
|
|
+| **`seq`** ✅ | 会话内**严格单调 + 唯一**（`uk_aim_session_seq`），分页顺序稳定、不重不漏 |
|
|
|
+
|
|
|
+> 顺带说明：即使某些场景下 `id` 走的是 MP 雪花（时间有序），它也**不是会话内的连续序号** ——
|
|
|
+> 「这个会话的第几条消息」这个语义只有 `seq` 能表达。而且分页顺序若依赖 ID 生成策略，
|
|
|
+> 换个生成器就悄悄坏掉，属于埋雷。
|
|
|
+
|
|
|
+**`seq` 的原子分配**（并发写同一会话不会重号，也不需要应用侧加锁）：
|
|
|
+
|
|
|
+```sql
|
|
|
+-- 与 INSERT 消息放在同一个事务里，一行完成「加水位 + 拿号」
|
|
|
+UPDATE agent_insight_session
|
|
|
+ SET last_seq = last_seq + 1, update_at = now()
|
|
|
+ WHERE id = #{sessionId}
|
|
|
+RETURNING last_seq;
|
|
|
+```
|
|
|
+
|
|
|
+依赖 PG 的**行级排他锁**：并发时第二个事务阻塞在这条 `UPDATE` 上，直到第一个提交，因此拿到的号天然不重复。
|
|
|
+比「先 `SELECT max(seq)` 再 `+1`」安全 —— 后者在 READ COMMITTED 下会重号。
|
|
|
+
|
|
|
+> **会话 ID 复用同款生成器**：`agent_insight_session.id` / `message.id` 沿用项目现有的 `generateId()` 即可。
|
|
|
+> 它是随机的，**只做主键、不做排序** —— 这正是要用 `seq` 单独扛排序的原因。
|
|
|
+
|
|
|
+#### 4.1.4 查询与索引映射
|
|
|
+
|
|
|
+| 场景 | SQL 要点 | 用到的索引 |
|
|
|
+|---|---|---|
|
|
|
+| 历史列表（抽屉「历史」下拉） | `WHERE case_id=? AND biz_type=? ORDER BY pinned DESC, last_message_at DESC LIMIT 50`，**不 select `context` / `sys_prompt`** | `idx_ais_case_list` |
|
|
|
+| 会话详情 | `WHERE id=? AND case_id=?` | PK + 归属校验 |
|
|
|
+| 消息列表（首屏，最新一页） | MP `Page` + `WHERE session_id=? AND case_id=? ORDER BY seq DESC`，取第 1 页；**不 select 大字段** | `uk_aim_session_seq` 反向扫描 |
|
|
|
+| 消息列表（上滑加载更早） | 同上，`page = 2, 3, ...`（顺序仍是 `ORDER BY seq DESC`） | 同上 |
|
|
|
+| 单条消息 trace | `SELECT tool_events, metadata FROM agent_insight_message WHERE id=? AND case_id=?`，**独立接口按需拉** | PK |
|
|
|
+| 线索聚合（预留） | `WHERE case_id=? AND output_json IS NOT NULL [AND 分级条件] ORDER BY create_at DESC` | `idx_aim_output` |
|
|
|
+| 删除会话 | `DELETE FROM agent_insight_session WHERE id=? AND case_id=?`，消息由 FK 级联 | PK + FK |
|
|
|
+
|
|
|
+> **列表查询绝不 select `tool_events` / `output_json`**。实测单条 assistant 消息的 `toolEvents.result`
|
|
|
+> 最长可达 **297KB**（2026-09-17 工具详情排查记录）；20 条一起 select 就是几 MB。
|
|
|
+> Mapper 里**显式列清单或 `resultMap`，禁止 `SELECT *`**；
|
|
|
+> 前端点开「分析过程」时才走 trace 接口单独取。
|
|
|
+>
|
|
|
+> 唯一索引 `uk_aim_session_seq (session_id, seq)` 已经能支撑 `seq DESC` 分页排序
|
|
|
+> —— PG 可以**反向扫描** B-tree，**不需要**再建 `(session_id, seq DESC)` 冗余索引。
|
|
|
+
|
|
|
+#### 4.1.5 消息分页接口契约
|
|
|
+
|
|
|
+**用普通分页（`page` + `limit`），复用项目既有的分页约定与 MyBatis-Plus 的 `Page`** —— 不引入游标参数。
|
|
|
+
|
|
|
+```
|
|
|
+GET /insight/continuous/sessions/{id}/messages?caseId=&page=1&limit=20
|
|
|
+```
|
|
|
+
|
|
|
+| 参数 | 语义 |
|
|
|
+|---|---|
|
|
|
+| `page` | 页码，**从 1 开始**（第 1 页 = 最新的 N 条），默认 `1` |
|
|
|
+| `limit` | 每页条数，默认 `20`（`message-page-size`），上限 `100` |
|
|
|
+| 排序 | **固定 `ORDER BY seq DESC`（服务端写死，忽略 `orderKey` / `sort`）** |
|
|
|
+
|
|
|
+> **参数名用 `page` + `limit`**，与项目既有约定一致（`common/base/Query.java`：`page` 默认 1、`limit` 默认 20）。
|
|
|
+> 查询入参可直接继承 `Query` 或另写 `InsightMessageQuery extends Query`，避免再造一套命名。
|
|
|
+
|
|
|
+**第 1 页返回最新的 N 条、第 2 页是更早的 N 条**，前端把每页 `unshift` 到列表头部。
|
|
|
+
|
|
|
+返回结构（直接用 MP `Page` 的形状，不另造壳）：
|
|
|
+
|
|
|
+```jsonc
|
|
|
+{
|
|
|
+ "records": [ /* InsightMessageVO[]，按 seq 降序；前端 unshift 前先 reverse 成升序 */ ],
|
|
|
+ "total": 42, // MP 自动 count(*)
|
|
|
+ "size": 20,
|
|
|
+ "current": 1,
|
|
|
+ "pages": 3
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+> `total` 由 MP 的 `count` 查询得出；会话列表页显示「N 条消息」仍读 `session.message_count`，两者用途不同、互不替代。
|
|
|
+
|
|
|
+> ⚠️ **方言注意点**：`MybatisPlusConfig:20` 注册分页插件时传的是 `DbType.DUCKDB`。
|
|
|
+> PG 与 DuckDB 的分页 SQL 都是 `LIMIT ? OFFSET ?`，本表在 PG（master）上**可以正常分页**；
|
|
|
+> 但若实测出现方言报错，就直接在 XML 里手写 `ORDER BY seq DESC LIMIT #{limit} OFFSET #{offset}` + 单独 `count(*)`，不折腾插件。
|
|
|
+
|
|
|
+**前端滚动实现**（`InsightMessageList.vue`）：
|
|
|
+- 容器挂 `@scroll`（节流 100ms）；当 `scrollTop < 80 && page < pages && !loading` 时 `page += 1` 拉下一页 →
|
|
|
+ `records.reverse()` 后 `unshift(...)`，再**补偿滚动位置**（先记 `scrollHeight`，插完 `scrollTop += 新 - 旧`），防止内容跳顶。
|
|
|
+- **首屏/切会话时重置 `page = 1`**，避免带着上个会话的页码请求。
|
|
|
+- **不上虚拟列表**（消息含富块、行高不定，成本高于收益；单会话几十条的量级不需要）。
|
|
|
+- **不做轮询补新消息**：流式期间靠 SSE 增量；流结束后若担心漏消息，用户手动刷新/重开抽屉即可 —— 不做 5s 轮询，省一层定时器与状态（见 §5.4）。
|
|
|
+- ⚠️ **已知取舍**：消息持续追加时，页码分页会出现「同一条消息在两页都出现」的轻微重复（新消息把内容往后挤）。本项目单会话几十条、且追加只发生在自己发问时，实际影响可忽略；前端按 `id` 去重兜底即可。
|
|
|
+
|
|
|
+#### 4.1.6 并发与一致性
|
|
|
+
|
|
|
+| 场景 | 机制 |
|
|
|
+|---|---|
|
|
|
+| 同一会话并发两条流（两个页签 / 重复点「重新分析」） | **双保险**：先 `ConcurrentHashMap<String, Lock>` 拦一道；再 `UPDATE agent_insight_session SET status='STREAMING' WHERE id=? AND status='ACTIVE'`，`affectedRows=0` → 返回 `409 该分析正在进行中`。流结束/异常在 `finally` 复位 `ACTIVE` |
|
|
|
+| `seq` 并发分配 | 由 DB 行锁解决（§4.1.3），**不需要**应用锁 |
|
|
|
+| 消息落库粒度 | **消息粒度，不是 token 粒度**：流开始 → insert 一条 `role=user`；流结束 → insert 一条完整 assistant；中止/异常 → insert 一条 `status=INTERRUPTED` 的 assistant（保留已生成正文）。**不做 token 级 UPDATE**，否则写放大几十倍 |
|
|
|
+| 流中预览 | 正文只在前端内存里长，落库是**流末一次写入**。刷新页面不丢（最后一条是已完成消息），与现有 `/chat` 的 partial 落库语义一致 |
|
|
|
+| 事务边界 | 「`UPDATE last_seq ... RETURNING` + `INSERT message` + `UPDATE message_count`」在**同一事务**；失败则整体回滚，seq 不留空洞 |
|
|
|
+| 配额 | 单案会话数上限（默认 500）：新建前 `SELECT count(*)`（`idx_ais_case_list` 可覆盖），超限拒绝并提示清理历史。DB 方案下不再需要「目录总大小」类配额 |
|
|
|
+| 留存 | 可配 `retentionDays`（默认 0 = 不自动清理）；开启后按 `last_message_at` 清理，消息随 FK 级联删除 |
|
|
|
+
|
|
|
+#### 4.1.7 配置项
|
|
|
+
|
|
|
+```yaml
|
|
|
+zsjz:
|
|
|
+ insight:
|
|
|
+ max-sessions-per-case: 500
|
|
|
+ retention-days: 0 # 0 = 不自动清理
|
|
|
+ message-page-size: 20 # 消息分页 limit 默认值（Query.limit 默认也是 20）
|
|
|
+ message-page-size-max: 100 # limit 上限，超出直接截断（不报错）
|
|
|
+ session-lock-timeout-ms: 3000
|
|
|
+```
|
|
|
+
|
|
|
+落 `InsightProperties`（`@ConfigurationProperties("zsjz.insight")`），照 `EtlProperties` / `RagProperties` 的写法。
|
|
|
+
|
|
|
+#### 4.1.8 入库换来的东西（与文件方案的账）
|
|
|
+
|
|
|
+| 文件方案得自己补的 | 入库后 DB 直接给 |
|
|
|
+|---|---|
|
|
|
+| 目录层级 + 路径解析 + 越界校验 | `case_id` 列 + 强制 where 条件 |
|
|
|
+| 会话锁 / 索引锁 / 原子替换 | DB 事务 + 行级锁 |
|
|
|
+| 手写 `index.json` / 配额 / 孤儿目录 / tmp 清理 | 索引、级联删除、`count(*)` |
|
|
|
+| 「同条件是否已分析过」要扫目录比对 | `context_hash` 一列直接比对 |
|
|
|
+| 跨案件线索聚合要遍历 `output.json` | 走 `idx_aim_output` 部分索引，一条 SQL |
|
|
|
+
|
|
|
+> 代价是**多两张表 + 一段 DDL**，以及一条要注意的钩子：
|
|
|
+> `ON DELETE CASCADE` 只保证「删**会话行**时消息一起删」，
|
|
|
+> **不保证业务上会去删这张表** —— 若案件删除是软删（`status=DELETED`），需要在查询侧过滤 `case_id`
|
|
|
+> 或在案件删除事件里显式清理。实现时先确认案件删除的实际语义。
|
|
|
+
|
|
|
+### 4.2 代码落位
|
|
|
+
|
|
|
+**决策：放在 `module/agent/insight/` 子包，不新建 `module/insight`。**
|
|
|
+
|
|
|
+理由：`AI_AGENT.md` §4 规定 `<domain>` 为固定取值集合（`agent/call/dm/.../trans`），`insight` 不在其中；且该能力与 agent 子系统强耦合（复用 `HarnessAgent`、`AgentStateStore`、工具与 `SqlResultStore`）。**「独立存储」的诉求由独立的两张表满足**，模块不必强行拆。
|
|
|
+
|
|
|
+```
|
|
|
+ai-server/src/main/java/com/zsjz/ai/module/agent/insight/
|
|
|
+├─ controller/ ContinuousInsightController # /insight/continuous/**
|
|
|
+├─ service/ ContinuousInsightService / ...Impl
|
|
|
+├─ agent/ InsightAgentFactory # ★ 独立实例池 + 动态 sysPrompt 装配
|
|
|
+├─ prompt/ InsightPromptBuilder # ★ 动态系统提示词拼装
|
|
|
+├─ context/ InsightContextBuilder / InsightContext # 查询条件 + 结果快照 → context 快照
|
|
|
+├─ entity/ AgentInsightSession / AgentInsightMessage # ★ 独立两张表
|
|
|
+├─ mapper/ AgentInsightSessionMapper / AgentInsightMessageMapper
|
|
|
+└─ dto/vo/ InsightCreateDTO / InsightStreamDTO / InsightSessionVO
|
|
|
+ InsightMessageQuery(继承 Query，page/limit) / InsightMessageVO / InsightContextVO
|
|
|
+ # 分页返回直接用 MP 的 Page<InsightMessageVO>，不另造 Page DTO
|
|
|
+
|
|
|
+ai-server/src/main/java/com/zsjz/ai/module/agent/insight/config/ InsightProperties
|
|
|
+ai-server/src/main/resources/mapper/insight/AgentInsight*.xml # 显式列清单，禁 SELECT *
|
|
|
+ai-server/src/main/resources/prompts/insight/CALL_CONTINUOUS_INSIGHT.md # 静态人设 + 输出契约
|
|
|
+sql/ insight_agent_tables.sql # 两张表 DDL（§4.1.2）
|
|
|
+```
|
|
|
+
|
|
|
+> **归属过滤统一收在 Mapper 方法签名里** —— 方法名形如 `selectByIdAndCase` / `selectPageBySessionAndCase` /
|
|
|
+> `insertMessage`（内部先校验会话归属）。Service 只调这些方法，**不自己拼 where**，
|
|
|
+> 这样「忘了带 case_id」在编译期就写不出来。
|
|
|
+> **不再加一层 `InsightStore`**：DB 方案下 Mapper 已承担这个职责，再加一层只是空转发。
|
|
|
+
|
|
|
+### 4.3 ★ 动态系统提示词机制
|
|
|
+
|
|
|
+这是本功能的技术核心，也是与现有 Agent 最大的差异点。
|
|
|
+
|
|
|
+#### 4.3.1 提示词结构
|
|
|
+
|
|
|
+```
|
|
|
+sysPrompt(session) =
|
|
|
+ ① 静态人设 + 输出契约 ← prompts/insight/CALL_CONTINUOUS_INSIGHT.md（可运维改，不发版）
|
|
|
+ ⊕ ② 动态数据上下文块 ← InsightContextBuilder 按 context 快照实时拼装
|
|
|
+ ⊕ ③ 专属渲染契约块 ← ```insight 围栏的 JSON Schema 说明
|
|
|
+ ⊕ ④ RAG 指引（可选） ← 复用 ragSchemaService.isAvailable()
|
|
|
+```
|
|
|
+
|
|
|
+**② 动态数据上下文块的内容：**
|
|
|
+
|
|
|
+```
|
|
|
+## 本次分析的数据上下文（系统自动注入，勿向用户复述）
|
|
|
+
|
|
|
+### 案件与分析模式
|
|
|
+- 案件：${caseName}（caseId=${caseId}）
|
|
|
+- 模式：${BATCH=对本批结果集整体研判 | PAIR=对单条关系对深度研判（预留）}
|
|
|
+
|
|
|
+### 用户查询条件
|
|
|
+- 分析对象：${personNames 或「全案对象人员」}
|
|
|
+- 持续联系月数阈值：≥ ${monthVal}
|
|
|
+- 联系日期范围：${startDate} ~ ${endDate}
|
|
|
+- 对方筛选：${otherName / otherPhone / 无}
|
|
|
+- 结果规模：命中 ${total} 对，本次提供 ${provided} 对（按持续月数降序 TOP ${topN}）
|
|
|
+
|
|
|
+### 数据口径（务必按此理解，禁止自创口径）
|
|
|
+- pairContMonthCount：该对关系「连续」通话的月份数；连续 = 相邻月份不间断，
|
|
|
+ 断月会切成多段分别计数，本表为各段求和
|
|
|
+- pairTotalCalls：上述连续段内的通话总次数
|
|
|
+- continuousStartMonth / continuousEndMonth：连续段起止月份
|
|
|
+- otherName = "未知对手" / otherPhone = "未知号码"：原始话单该字段为空，
|
|
|
+ **这本身是一条线索**（长期联系但身份不明）
|
|
|
+- 本表一行 = 一对（本方, 对方）的**汇总**，不是单通电话；
|
|
|
+ 想知道单通明细必须调用 get_call_records
|
|
|
+
|
|
|
+### 结果数据（TOP ${topN}，按持续月数降序）
|
|
|
+| 本方 | 对方 | 对方号码 | 连续月数 | 通话次数 | 起止月份 |
|
|
|
+|------|------|----------|----------|----------|----------|
|
|
|
+| … | … | … | … | … | … |
|
|
|
+```
|
|
|
+
|
|
|
+#### 4.3.2 生成时机与实例池（关键工程决策）
|
|
|
+
|
|
|
+| 问题 | 决策 | 原因 |
|
|
|
+|---|---|---|
|
|
|
+| sysPrompt 何时生成 | **创建会话时**由服务端拼好，与 context 快照一起写进 `agent_insight_session.sys_prompt`；**会话内不再变化** | 保证同一会话内模型行为稳定；追问时上下文与首轮一致，避免 sysPrompt 抖动导致结论翻烧饼。落库也便于「这个结论是怎么来的」事后复现 |
|
|
|
+| Agent 实例怎么管 | **独立池**，key = `insight-s{sessionId}`，LRU 64 / 空闲 30 分钟回收 | ★ **必须新开池**：现有 `agentPool` 的 key 是 `w{ws}-a{agent}-m{model}`，**没有 sysPrompt 维度** —— 复用会让动态提示词在不同会话间串台 |
|
|
|
+| 状态槽位 | 复用同一 `AgentStateStore`，槽位 = `(default, insight-{sessionId})` | 记忆按会话隔离，与实例无关（沿用官方"sandboxed stateless engine"模式） |
|
|
|
+| 上下文变更 | 用户重新查询后点「重新分析」→ **新建会话**，不改老会话的 sysPrompt | 语义干净：一次分析 = 一个会话 = 一份上下文 |
|
|
|
+
|
|
|
+#### 4.3.3 Agent 构建参数
|
|
|
+
|
|
|
+| 项 | 取值 | 说明 |
|
|
|
+|---|---|---|
|
|
|
+| `name` | `call-continuous-insight` | — |
|
|
|
+| `model` | **默认 LLM 模型**：`AgentModelService#getDefaultModelId()` | 取不到 → 抛 `ServerException(400, "未配置默认模型…")`，前端提示去模型管理页设置 |
|
|
|
+| `sysPrompt` | 见 §4.3.1 | 动态 |
|
|
|
+| `maxIters` | **6**（现有默认通常更高） | 解读任务，避免长循环烧 token |
|
|
|
+| 基础设施工具 | `search_table_schema`（RAG 可用时）、`execute_sql`、`list_tables`、`render_chart`、`render_graph` | 与现有 Agent 同源 |
|
|
|
+| 业务工具组 | **默认装备 `call` 组**（含 `stat_call_continuous_summary/detail`、话单明细），其余组（`person`/`trans`/`track`/`graph`）由模型按需 `reset_equipped_tools` 激活 | 交叉验证能力保留，但不把 24 份 person schema 每轮塞进上下文 |
|
|
|
+| `enableMetaTool` | `true` | 允许模型自行切组 |
|
|
|
+| 中间件 | **不挂** `IntentMiddleware` / `FollowupMiddleware` | 意图识别是通用对话的产物；Followup 的"下一步建议"与本功能自带的 `nextSteps` 重复，会造成双重建议 |
|
|
|
+| `stateStore` | 复用 `AgentStateStore` | — |
|
|
|
+| `workspace` | `PathConst.ROOT_PATH/.agentscope` | 与现有一致 |
|
|
|
+
|
|
|
+**需要的向后兼容小改造**：`AgentToolRegistry#registerBusinessTools(Toolkit)` → 增加重载
|
|
|
+`registerBusinessTools(Toolkit, List<String> activeGroups)`，原方法委托 `DEFAULT_ACTIVE_GROUPS`。
|
|
|
+`createGroup` 的 `active` 参数由传入的 `activeGroups` 决定。现有调用方零改动。
|
|
|
+
|
|
|
+### 4.4 接口清单
|
|
|
+
|
|
|
+| 方法 | 路径 | 说明 |
|
|
|
+|---|---|---|
|
|
|
+| POST | `/insight/continuous/sessions` | 创建分析会话。入参：`caseId`、`scope`（本期恒 `BATCH`）、`filters`（`CallContinuousQuery` 可见字段）、`rows`（结果快照）、`topN`。返回 `sessionId` + 上下文摘要（供 ContextBar 渲染） |
|
|
|
+| POST | `/insight/continuous/stream` | **SSE**。入参 `{ sessionId, caseId, message? }`；首轮 `message` 为空 → 服务端注入固定首轮指令。**进入前抢会话锁**（应用锁 + `status` 状态位），抢不到返回 409 |
|
|
|
+| GET | `/insight/continuous/sessions?caseId=&scope=` | 历史分析记录（抽屉「历史」下拉）——`WHERE case_id=?` 单表查，**不 select `context` / `sys_prompt`** |
|
|
|
+| GET | `/insight/continuous/sessions/{id}?caseId=` | 会话详情（含上下文摘要）。按 `id + case_id` 查，不匹配即 404 |
|
|
|
+| GET | `/insight/continuous/sessions/{id}/messages?caseId=&page=&limit=` | ★ **普通分页消息列表**（滚动加载，契约见 §4.1.5）。`page`/`limit` 沿用 `Query` 约定，`ORDER BY seq DESC` 服务端写死；返回轻量字段，**不含 `tool_events` / `output_json`** |
|
|
|
+| GET | `/insight/continuous/messages/{messageId}/trace?caseId=` | ★ **按需拉单条消息的工具明细 + 思考过程**（点开「分析过程」时调） |
|
|
|
+| DELETE | `/insight/continuous/sessions/{id}?caseId=` | 删除会话行（消息随 FK 级联）+ 清 agent 池 |
|
|
|
+| GET | `/insight/continuous/clues?caseId=&level=` | ★ 线索聚合，查该案件下带 `output_json` 的消息，为「线索推送」页预留 |
|
|
|
+
|
|
|
+> **所有读接口一律 `id + case_id` 双条件**。DB 方案下 `case_id` 就是一个 where 条件，
|
|
|
+> 不存在文件方案那种「拼进路径」的越权风险；但 **不允许任何方法只按 `session_id` 查**（§4.1.1 不变量 1）。
|
|
|
+> 若嫌每个接口都带 `caseId` 啰嗦，可在 Mapper 层把它做成强制参数 —— **不给默认值**。
|
|
|
+
|
|
|
+**SSE 事件与 `/chat/stream` 完全同构**：`tool_call` / `tool_input` / `tool_result` / `token` / `thinking` / `done` / `error`，
|
|
|
+仅**新增 `insight`** 一帧（结构化产物解析成功时下发）→ 前端 SSE 解析器可 100% 复用。
|
|
|
+
|
|
|
+**返回形态**：`/insight/**` 与 `/chat/**` 一致采用**裸返回**（不走 `Result<T>` 包装），
|
|
|
+理由：前端 `aiHttp.*Raw`（`isTransformResponse:false`）可直接复用，避免两套取值逻辑。
|
|
|
+（这是对 `AI_AGENT.md` §4「新增代码一律用 Result」的**有意偏离**，与既有 `/chat/**` 保持同一风格，文档化在此。）
|
|
|
+
|
|
|
+### 4.5 静态人设提示词要点（`prompts/insight/CALL_CONTINUOUS_INSIGHT.md`）
|
|
|
+
|
|
|
+**人格**：资深通联行为研判员（不是通用助手，不寒暄、不复述问题）。
|
|
|
+
|
|
|
+**硬性输出契约**：
|
|
|
+1. 先输出**唯一一个** `` ```insight `` 围栏 JSON（结构见 §3），再输出一段 Markdown 供人阅读。
|
|
|
+2. 线索 **3–6 条**；每条 ≥1 条**可核验的数字证据**（必须引用上下文表格中的具体数值）。
|
|
|
+ 禁止"可能存在""疑似有问题""建议进一步核实"这类无信息量表述。
|
|
|
+3. 每条线索必须给出「下一步怎么核」（1–2 个动作）。
|
|
|
+4. **无有效线索时必须显式说明"本轮未发现异常，原因是……"**，禁止编造凑数 —— 研判工具的底线。
|
|
|
+5. 禁止编造未提供的数据（人数、次数、日期、金额）；需要更多数据**必须先调工具取数**再下结论。
|
|
|
+6. 术语用领域词：通联异常、攻守同盟、白手套、时空伴随。
|
|
|
+7. 不确定的结论标注置信度 `high/medium/low`。
|
|
|
+8. 引用号码时按 `138****1111` 形式脱敏展示。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 5. 前端设计
|
|
|
+
|
|
|
+### 5.1 文件落位
|
|
|
+
|
|
|
+```
|
|
|
+ai-frontend/src/
|
|
|
+├─ call/api/insightApi.ts # 会话 CRUD + SSE
|
|
|
+├─ call/api/types/insight.ts # InsightSession/Message/Payload/SSE 回调类型
|
|
|
+├─ call/views/continuous/components/
|
|
|
+│ ├─ ContinuousInsightDrawer.vue # ★ 抽屉主体
|
|
|
+│ ├─ InsightContextBar.vue # 上下文芯片条 + 「条件已变更」提示
|
|
|
+│ ├─ InsightReport.vue # 报告容器（摘要卡 + 线索列表 + 下一步 + 过程折叠）
|
|
|
+│ ├─ InsightMessageList.vue # ★ 消息列表 + 滚动加载（普通分页 + 滚动位置补偿）
|
|
|
+│ ├─ InsightClueCard.vue # 单条线索卡
|
|
|
+│ ├─ InsightNextSteps.vue # 下一步思路清单
|
|
|
+│ └─ InsightHistoryPopover.vue # 历史分析记录
|
|
|
+├─ call/views/continuous/hooks/
|
|
|
+│ ├─ useContinuousInsight.ts # ★ 流式状态机（独立，不碰全局 store）
|
|
|
+│ └─ useInsightContext.ts # filters + tableData → 上下文快照
|
|
|
+├─ ai/api/sse.ts # ★ 从 chatApi.ts 抽出 SSE 解析器（纯重构）
|
|
|
+├─ ai/components/blocks/InsightBlock.vue # 新渲染块
|
|
|
+└─ ai/utils/{constants.ts,scanner.ts} + components/BlockRenderer.vue # 三处增量扩展
|
|
|
+```
|
|
|
+
|
|
|
+**为什么新写 hook 而不复用 `ai/store/chatStream.ts`**：该 store 是 `defineStore` **单例**，
|
|
|
+`workspaceId / sessions / messages` 均为全局态，AI 数据分析页正在使用；抽屉里再驱动它会把两处消息流搅在一起。
|
|
|
+抽屉用独立组合式 hook 持状态，但**复用** `chatApi` 的 SSE 解析器 —— 把 `createParser` / `streamChat` 抽到
|
|
|
+`ai/api/sse.ts`，`chatApi.ts` 与 `insightApi.ts` 共用（纯重构、零行为变化）。
|
|
|
+
|
|
|
+### 5.2 `continuous/index.vue` 改动点
|
|
|
+
|
|
|
+| 位置 | 改动 |
|
|
|
+|---|---|
|
|
|
+| `columns` 操作列 | **不改动** —— 仍是 `buildTableActionColumn`（只有「查看详情」） |
|
|
|
+| `panel-header` | 右侧新增 `AI 研判` 主按钮（`:disabled="!hasSearched \|\| !tableData.length"`） |
|
|
|
+| 模板末尾 | 新增 `<ContinuousInsightDrawer v-model:open="insightOpen" :filters="filters" :rows="tableData" />` |
|
|
|
+| `<style>` | 抽屉样式与页面 `.continuous-page` 变量对齐，复用 `trans-analysis-table-ui.less` 的色板与圆角 |
|
|
|
+
|
|
|
+**图标（踩坑点）**：`AI 研判` 用 `i-mdi:auto-fix`、线索卡等级用 `i-mdi:alert-decagram-outline` 等，
|
|
|
+**必须**在 `uno.config.ts` 的 `safelist` 中登记（`AI_AGENT.md` §8 坑 1 —— `menu.json` / 动态拼类名不会被扫描）。
|
|
|
+
|
|
|
+### 5.3 状态机（`useContinuousInsight`）
|
|
|
+
|
|
|
+```
|
|
|
+idle → creating（建会话）→ streaming（首轮/追问）→ done
|
|
|
+ ↘ error（模型未配置 / 网络 / 超限 / 409 进行中）
|
|
|
+```
|
|
|
+
|
|
|
+- 持有：`sessionId`、`messages`（按 `seq` 升序）、`page` / `pages` / `total`、`insightPayload`（结构化产物）、`toolSteps`、`thinking`、`streaming`、`abortController`
|
|
|
+- **消息加载**：`loadPage(page)` 拉第 N 页（`ORDER BY seq DESC`）→ `reverse()` 后 `unshift` + 滚动补偿；首屏与切会话都走 `loadPage(1)`
|
|
|
+- 复用现有富内容解析：`parseMessageBlocksIncremental` / `parseToolEvents` / `parseThinkingFromMetadata`
|
|
|
+ （节流重扫 + 已完成块冻结，避免长回答 O(n²)）
|
|
|
+- 追问走同一 `sessionId`；`stop()` = `abortController.abort()`
|
|
|
+
|
|
|
+### 5.4 降级与兜底
|
|
|
+
|
|
|
+| 场景 | 行为 |
|
|
|
+|---|---|
|
|
|
+| 无默认模型 | 抽屉内提示「请先在 AI 模型管理中设置默认模型」+ 跳转按钮，不发请求 |
|
|
|
+| 未打开案件（无 `caseId`） | 入口禁用 + tooltip |
|
|
|
+| `` ```insight `` 解析失败 | 退化为 Markdown 渲染（报告区不空屏） |
|
|
|
+| 结果为空 | 允许分析（模型应回答"无数据"），入口文案提示"当前结果为空" |
|
|
|
+| 结果数 > topN | ContextBar 明示「已按持续月数降序取前 100 对」，避免误以为全量 |
|
|
|
+| SSE 中断 | 落库为 `status=INTERRUPTED` 的 assistant 消息（沿用现有 partial 落库语义）；前端保留已收内容并给「继续」提示 |
|
|
|
+| 会话被并发打开 | 抢不到锁 / `status=STREAMING` → 409，提示「该分析正在进行中」，不静默排队 |
|
|
|
+| 滚动加载失败 | 保留已有消息与滚动位置，列表底部给「加载失败，点击重试」，**不回退 `page`**、不重置列表 |
|
|
|
+| 分页轻微重复 | 按消息 `id` 去重后再入列表（页码分页的已知取舍，见 §4.1.5） |
|
|
|
+| DB 不可用 | 明确报错（不做静默降级到内存），避免出现「本次分析刷新就没了」的静默数据丢失 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 6. 分阶段实施
|
|
|
+
|
|
|
+| 阶段 | 内容 | 可独立验收 |
|
|
|
+|---|---|---|
|
|
|
+| **P0** | **两张表 DDL + entity/Mapper + `seq` 原子分配 + 消息分页接口** + 后端会话与流式 + **动态 sysPrompt** + 前端抽屉（主按钮入口）+ 纯 Markdown 报告 | ✅ 能一键出解读，刷新后消息还在 |
|
|
|
+| **P1** | `` ```insight `` 围栏 + `InsightBlock` 卡片化（线索卡 / 下一步思路 / 跳转按钮） | ✅ 结构化线索可用 |
|
|
|
+| **P2** | 历史分析列表（抽屉「历史」下拉）+ `InsightMessageList` 滚动加载 + trace 按需拉取 + 后端 `GET /clues`（**仅预留，不接页面**） | ✅ 结果可回溯、长会话可翻 |
|
|
|
+| **后续（不在本次范围）** | 对接「线索推送」页 + 线索卡「记入线索」+ 行级「AI 解读」入口（`scope=PAIR`） | — |
|
|
|
+
|
|
|
+> P0 的存储层是**纯基础设施**，可以脱离 AI 单独验证：用单元测试覆盖
|
|
|
+> 「`seq` 并发分配不重号 / 分页排序稳定不重不漏 / 列表查询不含大字段 / `case_id` 归属校验拦越权 / 级联删除生效」即可。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 7. 提交前检查清单
|
|
|
+
|
|
|
+- [ ] 后端 `mvn -pl ai-server -am clean compile` 通过
|
|
|
+- [ ] 前端 `pnpm type:check` + `pnpm lint:eslint` 无错
|
|
|
+- [ ] **新增两张表**：`agent_insight_session` / `agent_insight_message`，DDL 落 `sql/`；
|
|
|
+ 确认**未改动** `agent_chat_session` / `agent_message` / 元数据三表
|
|
|
+- [ ] **`uk_aim_session_seq (session_id, seq)` 唯一约束到位**；`seq` 由 `UPDATE ... RETURNING last_seq` 原子分配
|
|
|
+- [ ] **没有任何 SQL 只按 `session_id` 查**（消息查询一律带 `case_id`），并有测试覆盖
|
|
|
+- [ ] 列表/分页查询**显式列清单，无 `SELECT *`**，不取 `tool_events` / `output_json`
|
|
|
+- [ ] 消息分页：`page` / `limit` 白名单校验（`page ≥ 1`、`limit ≤ 100`），**排序 `ORDER BY seq DESC` 服务端写死、忽略 `orderKey`/`sort`**
|
|
|
+- [ ] 会话锁 + `status` 状态位在 `finally` 复位；409 语义正确
|
|
|
+- [ ] 「`UPDATE last_seq` + `INSERT message` + `UPDATE message_count`」在同一 `@Transactional` 内
|
|
|
+- [ ] 不污染现有 `.agentscope`（框架工作区），不复用 `AgentService` 的 `agentPool` 与 `appendRenderPrompt`
|
|
|
+- [ ] 新 Agent 提示词契约与前端 `scanner.ts` / `BlockRenderer` 同步（改契约必须两头改）
|
|
|
+- [ ] `sys_prompt` / `context` 不通过任何接口原样下发（`context` 可下发；`sys_prompt` **不下发**）
|
|
|
+- [ ] 抽屉关闭 / 切换会话时 `AbortController` 与滚动监听已清理（防泄漏）
|
|
|
+- [ ] 无密钥 / 真实库密码 / 内网地址硬编码
|
|
|
+- [ ] 新图标已进 `uno.config.ts` safelist
|
|
|
+- [ ] 中文注释齐全，无调试残留
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 8. 已确认的设计决策
|
|
|
+
|
|
|
+| 决策点 | 结论 |
|
|
|
+|---|---|
|
|
|
+| **入口形态** | **只做面板级主按钮**。表格操作列不动；行级「AI 解读」本期不做，`scope=PAIR` 预留 |
|
|
|
+| **线索输出形态** | **结构化围栏 + 卡片**。P0 先出纯 Markdown 报告验收，P1 上 `` ```insight `` 围栏与线索卡 |
|
|
|
+| **线索沉淀** | **预留接口，暂不接页面**。后端把结构化产物写进消息行 `output_json` + 提供 `GET /insight/continuous/clues`；「记入线索」与「线索推送」页对接留到后续需求 |
|
|
|
+| **后端落位** | **`module/agent/insight/` 子包**（不新建 `module/insight`） |
|
|
|
+| **会话存储** | **入库，独立两张表** `agent_insight_session` / `agent_insight_message`（不复用 `agent_chat_session` / `agent_message`）。隔离三层：独立表 → `case_id` 强制过滤 → `session_id + case_id` 双条件；详见 §4.1 |
|
|
|
+| **消息滚动加载** | **普通分页接口**（`?page=&limit=`，沿用 `Query` 约定 + MP `Page`），`ORDER BY seq DESC` 服务端写死；前端上滑到顶 `page+1` + `unshift` + 滚动补偿。**不用游标参数** |
|
|
|
+| **面板形态** | 右侧抽屉 640px（可拖拽 480–1000）+ 右上「全屏」复用同组件 |
|
|
|
+| **模型** | 默认 LLM 模型（`getDefaultModelId()`），maxIters=6 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 9. 风险与注意点
|
|
|
+
|
|
|
+1. **动态提示词必须换池**。`AgentService#agentPool` 的 key 不含 sysPrompt 维度，一旦图省事复用现有池，
|
|
|
+ 动态提示词会在不同分析会话之间串台 —— 这是本功能最容易踩的坑。
|
|
|
+2. **提示词契约与前端渲染必须同步改**。改 `` ```insight `` 结构时，`scanner.ts` / `BlockRenderer.vue` /
|
|
|
+ `InsightBlock.vue` 要一起动，否则结构化块静默失效（退化成 Markdown，不报错，很难发现）。
|
|
|
+3. **token 成本**。结果快照 TOP 100 行按 6 列估算约 3–5k token，加人设与口径说明，单次首轮约 6–8k 输入。
|
|
|
+ TOP N 建议做成可配置（配置项或抽屉里的轻量开关），别硬编码。
|
|
|
+4. **模型稳定性**。围栏 JSON 输出依赖模型遵循能力；提示词里要给出完整 schema 示例，
|
|
|
+ 并明确「必须唯一一个围栏、必须合法 JSON」，否则解析失败率会偏高。
|
|
|
+5. **研判底线**。无有效线索时必须显式说明原因 —— 这条要写死在提示词里，否则模型会为凑数编造线索，
|
|
|
+ 在纪检/经侦场景下是严重问题。
|
|
|
+6. ★ **排序列的选择是本设计最容易做错的一处**。`id` 是随机 UUID 派生（非单调）、`create_at` 会同毫秒撞车，
|
|
|
+ 所以**必须 `ORDER BY seq`**。三条要写成测试：
|
|
|
+ - `UNIQUE(session_id, seq)` 约束在 DDL 里真实存在（不能只写在文档里）；
|
|
|
+ - `seq` 走 `UPDATE ... RETURNING last_seq` 原子分配，**不许**用 `SELECT max(seq)+1`（READ COMMITTED 下会重号）；
|
|
|
+ - 分页排序稳定：同一会话连续翻页不重不漏（`ORDER BY seq DESC` + `page/pageSize`）。
|
|
|
+7. **分页接口的取舍要认账**。用 `page` / `pageSize` 比游标简单、能直接复用 MP `Page`，
|
|
|
+ 但消息持续追加时会出现「同一条消息出现在两页」的轻微重复。本项目单会话几十条、追加只发生在用户自己发问时，
|
|
|
+ 实际影响可忽略；**前端按 `id` 去重兜底**，不要为此把分页复杂化。
|
|
|
+8. **「隔离」在 DB 方案下靠「强制 where」**，它比文件方案的路径校验安全（写错了静态能查出来），
|
|
|
+ 但仍有漏洞可钻：**只要有人新写一个 `selectBySessionId(sessionId)` 就破了**。对策是把 `case_id`
|
|
|
+ 做成 Mapper 方法的**必填签名参数**，并加一条测试断言「不存在只按 `session_id` 查消息的调用路径」。
|
|
|
+8. **大字段是列表接口的隐形地雷**。`tool_events` 单条可达数百 KB（实测 297KB），一旦列表接口 `SELECT *`
|
|
|
+ 或误带 `output_json`，首屏就会变成几 MB 响应。**列表查询禁用 `SELECT *`**，`output_json` 只在首轮消息详情/线索聚合里取。
|
|
|
+9. **流式落库是「流末一次写」**，不是 token 级 UPDATE。要确认产品上接受「流中断时消息状态为
|
|
|
+ `INTERRUPTED` 但正文已保存」，与现有 `/chat` 行为一致；不要为了「实时存」引入写放大。
|
|
|
+10. **案件删除的语义要先确认**。`ON DELETE CASCADE` 只在**物理删除**会话行时生效；
|
|
|
+ 若案件删除是软删（`status=DELETED`），需要在案件删除事件里显式清理本表，或在查询侧过滤 —— 这是最容易漏的一环。
|
