|
|
@@ -1,667 +0,0 @@
|
|
|
-# 2026-09-17
|
|
|
-
|
|
|
-## ★★ 全局接口返回空白：LicenseFilter 空壳过滤器吞掉所有请求（已修）
|
|
|
-
|
|
|
-用户报「`GET /sys/health` 返回内容空白」。排查后发现**不是单个接口的问题，是全站接口都返回空响应**。
|
|
|
-
|
|
|
-### 现象与实测（关键证据）
|
|
|
-| 请求 | 实测响应 |
|
|
|
-| --- | --- |
|
|
|
-| `GET /js/a/sys/health` | `200` + `Content-Length: 0`，**无 Content-Type** |
|
|
|
-| `GET /js/a/sys/info` / `/js/a/sys/code` / `/js/a/agent/model/list` | 同上 |
|
|
|
-| `GET /js/a/definitely-not-exist-xyz`（不存在的路径） | **同样是 `200` + `Content-Length: 0`** ← 决定性证据 |
|
|
|
-| `GET /sys/health`（漏了 context-path） | 正常 404（Tomcat 层，未进 context） |
|
|
|
-
|
|
|
-「不存在的路径也不返回 404」说明请求**根本没进 DispatcherServlet**，被 Servlet 过滤器链截断了。
|
|
|
-Controller 里 `Result.succeed("dsfsd")` 从头到尾没被执行。
|
|
|
-
|
|
|
-### 根因
|
|
|
-`ai-server/src/main/java/com/zsjz/ai/common/config/LicenseFilter.java`（2026-09-16 commit `6114881` 新增）：
|
|
|
-
|
|
|
-```java
|
|
|
-@Component // ← Spring Boot 自动注册为全局 Filter，URL 规则默认 /*
|
|
|
-public class LicenseFilter implements Filter {
|
|
|
- @Override
|
|
|
- public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) {
|
|
|
- // 方法体为空：没有 chain.doFilter(req, res)
|
|
|
- }
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-两个因素叠加：`@Component` + `implements jakarta.servlet.Filter` → 全局注册；`doFilter` 不放行 → 链终止，
|
|
|
-Tomcat 直接提交空 200。**日志无任何异常**，所以从日志侧完全看不出来。
|
|
|
-
|
|
|
-该文件是 Solon → Spring Boot 迁移的残留：真正的授权逻辑整段被注释掉，用的还是 Solon API
|
|
|
-（`Context`、`ctx.pathNew()`、`ctx.outputAsJson()`、`R.failure()`），这些在 Spring Boot 下不存在，
|
|
|
-所以只能注释、留了个空壳，没意识到空壳的副作用。`IGNORE_PATH` 里的 `/sys/health` 白名单也因此失去作用。
|
|
|
-
|
|
|
-### 修复（用户选定：透传但保留文件）
|
|
|
-`LicenseFilter.doFilter` 补上 `chain.doFilter(request, response)`；类头补了长注释说明踩坑点与
|
|
|
-「@Component + Filter 必须放行」的硬约束；`IGNORE_PATH` 保留并标注「供将来恢复全局拦截时使用」。
|
|
|
-
|
|
|
-### 排查手法（可复用）
|
|
|
-1. `curl -s -i` 看**是否有 Content-Type** —— 正常 Spring MVC 响应一定有；`200 + Content-Length: 0 + 无 Content-Type` 是「被过滤器吞掉」的指纹。
|
|
|
-2. **请求一个不存在的路径**：返回 404 = 已进 Spring；返回 200 空 = 卡在过滤器链。
|
|
|
-3. 全仓 grep `implements Filter|OncePerRequestFilter|FilterRegistrationBean` 找可疑过滤器（本项目只有这 1 个）。
|
|
|
-
|
|
|
-### 环境备忘
|
|
|
-- 本机后端**正在运行**（监听 8980，PID 16376），且运行的是**改动前**的构建 → 验证修复必须重启。
|
|
|
-- `curl` 记得加 `--noproxy '*'`（否则走沙箱代理拿到假象）；上下文路径是 `/js/a`。
|
|
|
-- 用户自行重启验证，未做运行期实测。
|
|
|
-
|
|
|
-### 相关
|
|
|
-- skill `qingjian-ai-dev` 已新增该陷阱（§9(h) 第 5 条是同一接口 `/sys/health` 的**另一个**原因：
|
|
|
- `@Controller` 无 `@ResponseBody` 导致 404 转发，两者别混淆）。
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-## ★★ 手动清洗后 tableRuleList 的 zf 字段被丢弃（2026-09-17，已定位）
|
|
|
-
|
|
|
-用户报：上传页点「手动清洗」，带过去的数据缺少 `zf` 字段；而上传页表格的接口是返回了的。
|
|
|
-
|
|
|
-### 实测证据（真机调接口，不是推断）
|
|
|
-开案：`POST /js/a/case/open` body `{"id":2,"pwd":"123456"}`（案件 2 密码就是 123456）。
|
|
|
-上传：`POST /js/a/dm/preFileUpload?batchId=999000111222&reClean=1`（multipart，`file` 字段；
|
|
|
-带 `reClean=1` 跳过 MD5 去重，否则重复文件返回 `data:null`）。
|
|
|
-响应：`data.children[0].tableRuleList` **30 条规则，30 条都带 `zf` 键**（本例全为 0），
|
|
|
-其中 MONEY 字段有 3 个：`transAmount` / `transBalance` / `otherBalance`（zf 均 0）。
|
|
|
-→ 用户说的「上传接口返回了 zf」属实。
|
|
|
-
|
|
|
-### 根因：`cleaning.vue` 的 `buildTableRuleListFromState` 只给「交易金额」写 zf
|
|
|
-`ai-frontend/src/case/views/data/cleaning.vue:3782`：
|
|
|
-```js
|
|
|
-const zf = isTransAmountTargetField(field) ? (recognitionAmountZfEnabled.value ? 1 : 0) : undefined;
|
|
|
-```
|
|
|
-- 非「交易金额」字段 → `zf: undefined` → `JSON.stringify` 直接把键丢掉；
|
|
|
-- 同函数里 `required`/`matched`/`matchedRequired`/`directionConf` 都走
|
|
|
- `pickFirstDefinedRuleFlagValue(模板字段值, 上一条规则值, 兜底)` 的**三级回退**，
|
|
|
- **只有 `zf` 是异类**：既不读 `previous.zf` 也不读 `templateFieldRecord.zf`。
|
|
|
-
|
|
|
-**触发时机（很关键）**：进清洗页即触发 —— `loadFileTree()` 选中首个节点 →
|
|
|
-`switchNodeState()` → `finally` 里 `syncActiveNodeStructure()` → `syncNodeStructure()` →
|
|
|
-`node.tableRuleList = buildTableRuleListFromState(...)` + `persistFileListToSessionStorage()`
|
|
|
-（`cleaning.vue:3863 / 3006 / 3057`）。所以一进清洗页，`case_clean_file_infos` 就被重写，
|
|
|
-首个 sheet 的非交易金额规则 zf 全部消失。切节点/点保存同理。
|
|
|
-
|
|
|
-### 影响：后端会 NPE（不只是少个字段）
|
|
|
-`ai-server/.../clean/impl/cleaner/` 里 4 处（`TransStdDataCleaner:71`、`TransStdDataCleaner1:79`、
|
|
|
-`TransInOutDataCleaner2:74`、`TransInOutDataCleaner5:70`）都是：
|
|
|
-```java
|
|
|
-switch (rule.getFieldType()) {
|
|
|
- case MONEY -> { ...; if (rule.getZf() == 1) { ... } } // Integer 与 int 比较 → 自动拆箱
|
|
|
-}
|
|
|
-```
|
|
|
-`getZf()` 返回 `Integer`，缺失时是 `null` → **自动拆箱 NPE**。
|
|
|
-而 `AbstractDataCleaner:84` 的 `tableRules` 就是 `sheet.getTableRuleList()` 过滤 `fileColIndex != null`，
|
|
|
-即**前端发什么就判什么**。所以 `transBalance` / `otherBalance` 这类 MONEY 字段只要被映射了、
|
|
|
-zf 又被前端抹掉，清洗就会抛 NPE（或 正负转换 静默失效）。
|
|
|
-
|
|
|
-### 修复（用户选定：前端 + 后端都改；交易金额保持「开关优先」）
|
|
|
-**前端** `cleaning.vue`：
|
|
|
-- 新增 `resolveStoredZfFlag(templateField, previous)`：模板字段 zf → 上一条规则 zf → 兜底 0，
|
|
|
- 保证**始终返回整数**；
|
|
|
-- `getRawRuleFlagValue` 的 key 联合类型加 `'zf'`；
|
|
|
-- `buildTableRuleListFromState` 里 `const zf = ...` 改为
|
|
|
- 「交易金额 → `recognitionAmountZfEnabled ? 1 : 0`；其余 → `resolveStoredZfFlag(templateFieldRecord, previous)`」，
|
|
|
- 并把该声明下移到 `templateFieldRecord` 之后（原来在它之前，拿不到模板字段）。
|
|
|
-
|
|
|
-**后端**：`AbstractDataCleaner` 新增
|
|
|
-`protected static boolean isZfEnabled(TableRuleDTO rule)`（`Integer.valueOf(1).equals(rule.getZf())`），
|
|
|
-`TransStdDataCleaner:71`、`TransStdDataCleaner1:79`、`TransInOutDataCleaner2:74`、`TransInOutDataCleaner5:70`
|
|
|
-4 处 `if (rule.getZf() == 1)` → `if (isZfEnabled(rule))`。
|
|
|
-
|
|
|
-### 验证（都做了）
|
|
|
-- 后端 `mvn -pl ai-server -B compile` → **BUILD SUCCESS**
|
|
|
-- 前端 `eslint cleaning.vue --max-warnings 0` → **0 错误**（先有一处 prettier 折行报错，已手工改单行）
|
|
|
-- `vue-tsc --noEmit` → cleaning.vue **0 错误**，全仓仍 **103**（与既有基线一致，无新增）
|
|
|
-- **用真实上传响应跑前后对比脚本**（`C:/Users/cc/AppData/Local/Temp/zfcheck.cjs`）：
|
|
|
- 修复前 `roundTrip` 后 **0/30** 条带 zf（3 个 MONEY 字段全丢）；修复后 **30/30** 条带 zf、
|
|
|
- 全为整数、再重建一次结果完全一致（幂等）。
|
|
|
- ★ 脚本第一版写错过：`{zf: undefined}` 的对象**自身仍有 zf 键**，必须补 `JSON.parse(JSON.stringify(x))`
|
|
|
- 这一步才能复现丢键，否则会误判"没丢"。
|
|
|
-
|
|
|
-### 同类地雷批量清理（2026-09-17，用户说"继续"后执行）
|
|
|
-`AbstractDataCleaner` 抽出三个 helper：`isFlagOn(Integer)`（通用 0/1 判断）、
|
|
|
-`isZfEnabled(TableRuleDTO)`、`isRequired(TableRuleDTO)`，后两者都走 `isFlagOn`。
|
|
|
-- **29 个清洗器 / 58 处** `rule.getRequired() == 1` → `isRequired(rule)`（用 Node 脚本按精确子串替换，
|
|
|
- 逐文件断言命中数=2、替换后长度 = 原长 − 命中数×(FROM.length−TO.length)，确保除目标子串外零改动）
|
|
|
-- `GlobalCache:204` `field.getMatched() == 1`（`TableField.matched` 是 Integer）→ `Integer.valueOf(1).equals(...)`
|
|
|
-- `FunRadix:33` `getRadixType() == 0`（Integer，默认 1）→ `Integer.valueOf(0).equals(...)`，null 走 else 与默认值 1 语义一致
|
|
|
-- `RagSchemaService:263/277` 已有 `!= null &&` 前置判断，安全，**刻意未动**
|
|
|
-- 验证：`mvn -pl ai-server -B clean compile` → **BUILD SUCCESS**（622 源文件）；
|
|
|
- 残留 `getRequired() == 1` 仅剩 AbstractDataCleaner 的 javadoc 示例；
|
|
|
- CRLF 保留（`tr -cd '\r' | wc -c` == `wc -l`，抽查 3 个文件）
|
|
|
-
|
|
|
-### 遗留（未改，已报用户，属别的模块）
|
|
|
-全仓还有一批「可空 Integer 直接 `== 数字`」**且无 null 前置判断**的写法：
|
|
|
-`CaseDataCache:55/57`（`PersonLibNo.libType`）、`SpecialDateService:37/69`、`IntimacyService:119`、
|
|
|
-`TrackExpressInfoService:72/82`、`TransFundFlowService:368/434/499/563`（`TransFlowGraphQuery.level`）、
|
|
|
-`DmService:748`、`AgentChatServiceImpl:214`。这些字段在各自业务里大多必填，属**潜伏**风险，
|
|
|
-动之前要先确认字段是否真会为 null。
|
|
|
-已带 `!= null &&` 前置判断的是安全的：`DataProfileService:225`、`TransRecordService:87/140`、
|
|
|
-`TableInfoController:34/35`、`DmService:287/380/597`、`TrackTogetherLiveService:165`。
|
|
|
-★ 排查手法：`grep -rn "get[A-Za-z0-9_]*() *[!=]= *[0-9]" src/main/java --include=*.java` 再回查字段声明类型。
|
|
|
-
|
|
|
-### 结论
|
|
|
-前端应保证每条规则都带**整数** `zf`（非交易金额字段沿用上传接口/模板的值，兜底 0），
|
|
|
-而不是只给交易金额写、其余置 undefined。已按「前端 + 后端都改」落地。
|
|
|
-
|
|
|
-### 复用要点
|
|
|
-- `table_field.zf`（平台库，`etl-2` / `zsjz-ai` 都有）语义 = 「开启正负转换」，只配在
|
|
|
- `transAmount` / MONEY 字段上（实测 16 行 zf=1，field_name_en 全是 `transAmount`）。
|
|
|
-- `PreDataListener.getTableRuleList()`（line 400-440）里 `zf` 取自**主模板**字段
|
|
|
- （`entityToDto(mainTable)`），而 `fieldNameCn`/`directionConf`/`matched`/`required`
|
|
|
- 会被**子模板**同名字段覆盖 —— `zf` 不在覆盖列表里，这是个潜在不一致点。
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-## 清洗流程三个页面统一为「独立全屏路由」（不套 LAYOUT）
|
|
|
-
|
|
|
-### 背景
|
|
|
-上传 → 手动清洗 → 清洗导入是同一条流程。此前只有 `upload.vue` 是独立全屏路由，
|
|
|
-`cleaning.vue` / `cleanProgress.vue` 挂在 `DataRoute`（`component: LAYOUT`）下，
|
|
|
-进流程后菜单/页签会重新冒出来，与上传页割裂。
|
|
|
-
|
|
|
-### 改动 1：`ai-frontend/src/core/router/routes/index.ts`
|
|
|
-- 从 `DataRoute.children` 删除 `cleaning`、`cleanProgress` 两个子路由（连同 `currentActiveMenu`）
|
|
|
-- 仿 `CaseUploadRoute` 新增 `CaseCleaningRoute` / `CaseCleanProgressRoute`，
|
|
|
- `path` 用 `PageEnum.BASE_CLEANING`(`/data/cleaning`) / `BASE_CLEAN_PROGRESS`(`/data/cleanProgress`)，
|
|
|
- `meta` 保留 `title` + `hideMenu: true` + `hideTab: true`
|
|
|
-- 两者加进 `basicRoutes`（放在 `CaseUploadRoute` 之后、`DataRoute` 之前）
|
|
|
-- 路由 `name` 未变（`CaseCleaning` / `CaseCleanProgress`），全仓无其它引用
|
|
|
-
|
|
|
-### 改动 2：两个页面的根样式（**脱离 LAYOUT 必须改，否则高度错**）
|
|
|
-- `cleaning.vue`：`height/max-height: calc(100vh - 100px)` → `100vh`。
|
|
|
- 那个 `100px` 是布局 header + tabs 的高度，脱离 LAYOUT 后不存在，扣掉会平白少一截。
|
|
|
-- `cleanProgress.vue`：`min-height/height: 100%` → `100vh`。
|
|
|
- 父级不再是有确定高度的布局内容容器，`100%` 会退化成 `auto`，页面塌成内容高度。
|
|
|
-- 两页背景由 `#fff` 改为 `#f0f2f5`（与 `upload.vue` 一致）。因为页内面板本身是
|
|
|
- 「白底 + 边框 + 阴影」的卡片（`.left-panel/.middle-panel/.right-panel`、`.progress-card`），
|
|
|
- 白底铺满会糊成一片；灰底才能让卡片浮起来。
|
|
|
-- 两页都没有暗色主题样式块（`upload.vue` 有），保持原样未补。
|
|
|
-
|
|
|
-### 关键判断依据（后续改路由前先看这些）
|
|
|
-- `basicRoutes` 是直接传给 `createRouter({ routes: basicRoutes })` 的**静态路由**，
|
|
|
- 所以独立全屏路由**刷新/直链也能命中**，不依赖 `permissionGuard` 的动态注入。
|
|
|
-- `hideMenu` 的过滤在 `core/router/helper/menuHelper.ts:41`（`if (node.meta.hideMenu) return;`），
|
|
|
- 与是否套 LAYOUT 无关，删掉 `currentActiveMenu` 无副作用。
|
|
|
-- `core/store/modules/multipleTab.ts:32` 的 `HIDDEN_FLOW_TAB_PATHS` 按 **path** 判断，
|
|
|
- 不依赖路由层级，**无需同步修改**；`hideTab: true` 也让 `addTab` 直接 early-return。
|
|
|
-- LAYOUT 内页面原高度参考：`.jeesite-layout-content` 有 `padding: 12px 12px 0` 且高度是 JS 算的
|
|
|
- （`useContentViewHeight`），所以布局内页面用 `calc(100vh - 100px)`，全屏页必须用 `100vh`。
|
|
|
-- `upload.vue` 的 `onBeforeRouteLeave` 靠 `to.path` 比对 `BASE_CLEANING`/`BASE_CLEAN_PROGRESS`
|
|
|
- 决定是否保留 sessionStorage 缓存 —— 路径没变，逻辑不受影响。
|
|
|
-
|
|
|
-### 验证（全部实测通过）
|
|
|
-- `eslint --max-warnings 0` 三个改动文件 → **0 错误**
|
|
|
-- `vue-tsc --noEmit --skipLibCheck` → 全仓 **103**（与基线一致），三个改动文件 **0 错误**
|
|
|
-- **UI 级验证**（`%TEMP%/ai-verify/ui-route-flow2.cjs` + `ui-route-flow3.cjs`，用 playwright-core
|
|
|
- 复用 agent-browser 下载的 chrome，1680×1000 视口）：
|
|
|
- - 深链直开 `/data/cleaning`、`/data/cleanProgress`、`/data/upload`
|
|
|
- → `.jeesite-default-layout` / `.jeesite-layout-content` / `.ant-layout-sider` 全为 **0**，
|
|
|
- 页面根 `getBoundingClientRect().height` **== window.innerHeight**，背景 `rgb(240,242,245)`；
|
|
|
- - 对照组深链直开 `/data/index` → 三者均为 1（有布局），证明判定方法有效；
|
|
|
- - 真实点击：`/data/index` 点「选择文件」→ `/data/upload?mode=single`（无布局、1000px 撑满）
|
|
|
- → 点「返回」→ `/data/index`（布局恢复、上传页已卸载）；
|
|
|
- - 全程 **0 条控制台错误**、无 4xx/5xx。
|
|
|
-- ★ 踩坑：`agent-browser` 守护进程在本机起不来（详见技能文档 §9.5(f)），
|
|
|
- 应直接用 **playwright-core**；我一开始没看技能文档，白试了三轮。
|
|
|
-
|
|
|
-### 环境备忘（本次新得）
|
|
|
-- 后端 context-path 是 `/js/a`，健康检查完整地址 = `http://127.0.0.1:8980/js/a/sys/health`
|
|
|
- → `{"code":200,"message":"","data":null}`。**直接访问 `/sys/health` 会 404，别误判后端没起来。**
|
|
|
-- 前端 dev server 在 **3100**。
|
|
|
-- ★ **路由模式分环境**：`routeHelper.ts:151` 按 `VITE_ROUTE_WEB_HISTORY` 决定 ——
|
|
|
- `.env.development` = `true`（**history**，真实 URL 形如 `http://localhost:3100/data/cleaning`），
|
|
|
- `.env.production` = `false`（**hash**），`.env.tomcat` = `true`。
|
|
|
- 所以**本地调试用不带 `#` 的路径**；写验证脚本时改 `location.hash` 是无效的（history 模式不响应），
|
|
|
- 必须用 `page.goto(BASE + '/data/xxx')` 或真实点击。
|
|
|
-- 案件数据页 `/data/index` 的「导入数据 / 导入文件」是 **页签**（`button.import-tabs__item`），
|
|
|
- 真正的上传入口是右上角 **「选择文件」按钮**（`handleUploadNavigate('single')` → `/data/upload?mode=single`）。
|
|
|
-
|
|
|
-### 模型管理页：对话/向量分类 Tab + 各自默认（2026-09-17）
|
|
|
-需求：模型管理页按用途类型分 Tab，且 llm 与 embedding **各自**维护一个默认模型。
|
|
|
-
|
|
|
-后端（编译通过 + 27 项纯逻辑断言通过）：
|
|
|
-- 新增 `common/enums/ModelTypeEnum`（LLM="llm" / EMBEDDING="embedding"，`fromCode` 把 null/未知值归一为 LLM）。
|
|
|
-- `AgentModelServiceImpl#setDefaultModel` 由「清空全表默认」改为**只清同类型**默认；
|
|
|
- `createModel` / `updateModel(defaultModel=true)` 同样走 `clearDefaultOfType`，避免同类型多个默认。
|
|
|
-- `getDefaultModelId()` 语义收紧为**默认对话模型**（type=llm，含 `type IS NULL` 历史行）；
|
|
|
- 新增 `getDefaultModelId(String type)`。两个 wrapper 的构建抽成包级静态方法
|
|
|
- `buildClearDefaultWrapper` / `buildDefaultQueryWrapper`，便于脱离 Spring/DB 断言。
|
|
|
-- `EmbeddingModelFactory.resolveDefault()` 改用枚举常量 + 次级排序（create_at DESC）保证确定性。
|
|
|
-- ★ 验证手法：`dependency:build-classpath -Dmdep.outputFile=...` 导出依赖 → 用 `target/classes` + 该
|
|
|
- classpath 跑 main → `TableInfoHelper.initTableInfo(assistant, AgentModel.class)` 初始化后打印
|
|
|
- `wrapper.getCustomSqlSegment()`，断言 and/or 括号组合。**不用起 Spring、不用连库。**
|
|
|
-
|
|
|
-前端：
|
|
|
-- `ai/views/aiModel/index.vue`：a-tabs 两个页签（对话模型 / 向量模型 + 数量角标），表格按 tab 过滤；
|
|
|
- 去掉冗余「类型」列；「设为默认」不再拦截 embedding（类型已隔离），已是默认时置灰为「已是默认」；
|
|
|
- summary 同时显示两类默认；新增按钮文案跟随当前 tab。
|
|
|
-- `ai/components/ModelFormModal.vue`：新增 `defaultType` prop（新增时类型跟随当前 tab）；
|
|
|
- 默认开关文案按类型区分，并提示「同类只能有一个默认」。
|
|
|
-- UI 级验证（playwright-core）：`tabs=["对话模型2","向量模型1"]`、列名无「类型」、
|
|
|
- 默认角标「默认对话」在「本地模型」上、弹窗类型默认「向量模型」、0 控制台错误 / 0 个 4xx。
|
|
|
-- ⚠️ 当时后端进程（PID 6980）跑的是改动前的代码，**需重启后端类型隔离才生效**（本次未擅自重启）。
|
|
|
-- ⚠️ 后端常驻进程是 **IDEA 以 Debug 模式**启动的（`jps` 可见 `com.zsjz.ai.App` + `-agentlib:jdwp`
|
|
|
- + IDEA captureAgent），**不要杀**：会丢进程内 DuckDB 案件状态、打断调试会话。改完后端代码需用户在 IDEA 里重启。
|
|
|
-- ★ 不重启后端的验证手法：JDBC 连库 → `setAutoCommit(false)` → 跑与代码等价的 SQL → 断言 → `rollback()`。
|
|
|
- 本次据此在真实 `agent_model` 上验证默认模型类型隔离（10 项全过，含"旧逻辑会误清另一类型"的对照），数据零变更。
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-## AI 对话界面（aiAnalysis）排版改造：对齐主流 AI 客户端
|
|
|
-
|
|
|
-需求：用户觉得对话输出排版"不好用"，要求参考 WorkBuddy / ChatGPT 重排。
|
|
|
-
|
|
|
-### 用户拍板的决策
|
|
|
-- 内容列宽 **900 → 1024px**（消息流 / 输入区 / 欢迎页共用同一列）
|
|
|
-- **用户消息 = 右对齐气泡；AI 消息 = 头像 + 内容列，不用气泡**
|
|
|
-- 思考 / 工具调用 → **默认折叠成一行弱化灰条**
|
|
|
-- 输入区重排（圆角容器 + 圆形发送/停止按钮 + 模型收成 chip）
|
|
|
-
|
|
|
-### 改动文件（全部在 `ai-frontend/src/ai/`）
|
|
|
-- `styles/ai.less`：新增令牌 `--ai-avatar:28px`、`--ai-radius-bubble:12px`，`--ai-content-max` 改 1024px；
|
|
|
- 新增 `.ai-turn`（grid：头像列 + minmax(0,1fr) 内容列）与 `.ai-process`（过程条基元 = 弱化灰条 +
|
|
|
- 展开区 2px 左轴）；`.ai-markdown` 重排（**去 h2 下边框**、行内 code 去边框、表格改发丝横线去斑马纹、
|
|
|
- 标题上间距 > 下间距）；**删除消息间分隔线**，改相邻选择器控制轮次节奏
|
|
|
- （assistant→user 28px / user→assistant 12px / assistant→assistant 20px）；
|
|
|
- 操作条显隐 = hover/focus 露出 + 最后一条 AI 常驻 + `@media (hover: none)` 常驻
|
|
|
-- `ChatMessageItem.vue`：拆成两个分支（用户气泡 / AI 头像+内容列），用户消息时间移到气泡下方，错误态加图标
|
|
|
-- `MessageToolbar.vue`：5 个文字按钮 → 30px mdi 图标按钮 + tooltip，删除加 Popconfirm 二次确认
|
|
|
-- `ThinkingPanel.vue` / `ToolCallPanel.vue`：换 `.ai-process` 外壳（自动展开/收起/滚底逻辑一行未改）
|
|
|
-- `ChatComposer.vue`：圆角 14px 容器、模型收成 chip（Dropdown + Menu）、圆形 32px 发送/停止、hint 移出容器
|
|
|
-- `views/aiAnalysis/index.vue`：新增 `__flow` 定位容器 + 「回到底部」按钮（距底 >200px 显示）
|
|
|
-- `uno.config.ts`：safelist 补 10 个 mdi 图标（sparkles / content-copy / check / tray-arrow-down /
|
|
|
- star / star-outline / alert-circle-outline / chip / arrow-up / arrow-down）
|
|
|
-
|
|
|
-### 关键陷阱（下次直接照做）
|
|
|
-- ★ **`Icon` 组件的类名是运行时拼的**（`i-mdi:xxx`），UnoCSS 静态扫描不到 →
|
|
|
- 新增图标**必须**加进 `uno.config.ts` 的 `safelist`，否则图标一片空白
|
|
|
-- ★ **输入区宽度要与消息内容列对齐**：`.ai-column` 自身有 24px 内边距，composer 的 box 必须
|
|
|
- `max-width: calc(var(--ai-content-max) - var(--ai-sp-5) * 2)`，否则输入框比正文宽 48px、左边不齐
|
|
|
-- `bodyRef` 只在 AI 分支存在（PDF 导出依赖它），用户消息的 toolbar 没有导出菜单所以安全
|
|
|
-- Tooltip 与 Dropdown 不要套在同一个按钮上（互相抢 click/hover 事件），导出按钮只留 Dropdown
|
|
|
-
|
|
|
-### 验证
|
|
|
-- `pnpm -C ai-frontend type:check` → `src/ai` **0 错误**
|
|
|
- （全仓既有基线是 `src/trans` 下约 100 条历史报错，与本次无关，别误判为自己引入）
|
|
|
-- `pnpm -C ai-frontend build` → **通过**（约 1m50s）
|
|
|
-
|
|
|
-### 追加：过程区改成「执行时间线」（第二轮，用户贴 WorkBuddy 截图后）
|
|
|
-用户反馈第一版"没啥变化"，并贴出 WorkBuddy 的过程展示 —— 他要的是**执行时间线**，
|
|
|
-不是"思考和工具各自折叠成一条灰条"（第一版方向错了）。
|
|
|
-
|
|
|
-- 新建 `components/ProcessTimeline.vue`（根类 `.ai-trace`）：
|
|
|
- - 折叠态 = 一行汇总「已完成 · 3 步工具调用 · 12s」/ 流式中「正在分析…」
|
|
|
- - 展开态 = 左侧一条细竖线 + 逐行流水，行 = 13px 图标 + 动作名 + 参数摘要
|
|
|
- - 思考行可展开全文（多段思考按 `\n\n` 拆成多行「深度思考」），工具行可展开入参/结果
|
|
|
- - 工具 → 图标映射见组件内 `TOOL_ICONS`；摘要从入参 JSON 里按 `ARG_KEYS` 取第一个字符串值截 72 字
|
|
|
-- `ChatMessageItem.vue`：用 ProcessTimeline 替掉 ThinkingPanel + ToolCallPanel；
|
|
|
- `StreamStatusBar` 改为仅在 `!hasTrace` 时显示（否则和时间线汇总行重复计时）
|
|
|
-- ai.less：删掉上一轮加的 `.ai-process` 基元（样式已收进组件 scoped）；`hover:none` 规则补 `.ai-trace__detail-btn`
|
|
|
-- ⚠️ **两个旧组件文件没删掉**：`ThinkingPanel.vue` / `ToolCallPanel.vue` 已无任何引用（grep 确认），
|
|
|
- 但本环境 bash 坏了（`dirname: command not found`）、PowerShell 的 `Remove-Item` 也被拦（exit 1 无输出），
|
|
|
- **需用户手动删除**或下次在正常 shell 里删
|
|
|
-- ★ 时序是**展示层近似**：后端只下发「思考全文 + toolEvents 数组」，无统一时序字段。
|
|
|
- 思考段数 M 与工具数 N 满足 M==N 或 M==N+1 时按 ReAct 常见形态交替排列，否则退化为"思考在前、工具在后"。
|
|
|
- 要精确还原需后端落库时一并保存事件顺序。
|
|
|
-- ★ 模板类型收窄陷阱：`<div v-if="a">…</div><pre v-if="a && b">…</pre><template v-else-if="c">` 里，
|
|
|
- 中间那个 v-if 会**截断联合类型收窄**，`item.step` 会报类型错。必须改成
|
|
|
- `<template v-if>` / `<template v-else>` 各包一整块。
|
|
|
-- ★ `watch(x, cb, { deep: true })` 在**程序化**修改时也会触发，会把手动标记误置位 ——
|
|
|
- "用户是否手动操作过"这类标记只在 click handler 里置位。
|
|
|
-- 验证：`type:check` → src/ai **0 错误**；`build` → **通过**
|
|
|
-
|
|
|
-### 图标白名单最终清单（`uno.config.ts` safelist 里 AI 相关部分）
|
|
|
-refresh / plus / send / stop / magnify / pin / pin-outline / pencil-outline / trash-can-outline /
|
|
|
-fullscreen / fullscreen-exit / phone-outline / bank-transfer / brain / chart-box-outline /
|
|
|
-sparkles / content-copy / check / tray-arrow-down / star / star-outline / alert-circle-outline /
|
|
|
-chip / arrow-up / arrow-down / chevron-right / chevron-down / chevron-up /
|
|
|
-database-search-outline / format-list-bulleted / table-search / language-python /
|
|
|
-graph-outline / folder-search-outline / tools
|
|
|
-
|
|
|
-### 追加（第三轮）：思考与工具的**顺序**错了 —— 根因是 store 把时序拍平了
|
|
|
-用户反馈："思考后不是调用工具吗？每一个思考过后的步骤要在一起，不是把工具和思考分开放。"
|
|
|
-
|
|
|
-**根因**：SSE 本身是**按真实顺序**下发的（thinking start → delta → end、tool_call、tool_input、
|
|
|
-tool_result，`chatStream.ts` 的回调也确实顺序触发），但 store 把它们**拍平**成
|
|
|
-「`thinking` 一段拼接全文 + `toolSteps` 一个数组」，顺序信息在拼接时就丢了。
|
|
|
-渲染端只能靠"思考段数与工具数是否匹配"去猜，猜不中就退化成"思考全堆前面、工具全堆后面"
|
|
|
-—— 用户看到的正是这个。
|
|
|
-
|
|
|
-**修法**：
|
|
|
-- `store/chatStream.ts`：新增 `TraceNode { kind: 'think' | 'tool'; text?; toolCallId? }` 与 `ChatMessage.trace`；
|
|
|
- `onThinking(phase=start)` push 一个思考节点、`onThinking(delta)` 用新加的 `appendToLastThink()` 填正文、
|
|
|
- `onToolCall` push 一个工具节点（带 toolCallId）→ **流式期间时序 100% 准确**
|
|
|
-- `ProcessTimeline`：新增 `trace` prop 并**优先使用** —— 按到达顺序渲染，每段思考后紧跟它引发的工具
|
|
|
-- 历史消息（无 trace）的近似算法重写：`思考 i → 工具 i`，多出来的顺序接末尾，
|
|
|
- **取消原来"不匹配就分两堆"的兜底分支**
|
|
|
-- `ChatMessageItem`：传 `:trace="message.trace"`
|
|
|
-
|
|
|
-**遗留（要彻底解决需改后端）**：刷新页面 / 重新打开历史会话时消息从后端重拉，
|
|
|
-`metadata` 只有 thinking 全文、`toolEvents` 只有工具数组，没有事件顺序 → 只能近似排列。
|
|
|
-彻底解决需后端落库时把事件顺序一并写进 metadata。
|
|
|
-
|
|
|
-**验证**：`type:check` → src/ai 0 错误；`build` → 通过。
|
|
|
-
|
|
|
-### 追加（第四轮）：工具详情恢复 + 输出用表格渲染
|
|
|
-用户："ToolCallPanel 还是要有啊。展示出工具入参和输出啊。输出的如果是 json 数据 要用表格渲染出来。"
|
|
|
-
|
|
|
-- 重建 `components/ToolCallPanel.vue`（**用 Write 直接覆盖旧文件**，顺带解决"旧文件删不掉"的问题）。
|
|
|
- 职责改为「单个工具的详情」：入参（格式化 JSON 的 pre）+ 输出（智能结构化）。
|
|
|
- 输出渲染优先级：
|
|
|
- 1. execute_sql 载荷 → 复用 `scanner.ts` 的 `isTablePayload()`，按 `columns` 定义渲染表格
|
|
|
- 2. 对象数组 `[{…}]` → 取键并集作列
|
|
|
- 3. 原始值数组 `[1,2,3]` → 单列
|
|
|
- 4. 普通对象 → 字段 / 值两列
|
|
|
- 5. 兜底 → 等宽 pre
|
|
|
- 表格形态保留「原始 JSON」切换按钮；> 20 行本地分页；`scroll: { x: 'max-content', y: 360 }`；
|
|
|
- 单元格里的对象/数组再 `JSON.stringify` 一次，避免 `[object Object]`
|
|
|
-- `ProcessTimeline`：工具行详情区改为 `<ToolCallPanel :step="item.step" />`，
|
|
|
- 删掉内联的入参/结果 pre 与 `pretty()`，样式删掉 `__detail-label` / `__pre`
|
|
|
-- ★ **删文件绕过沙箱的办法**：`Remove-Item`（PowerShell）与 bash `rm` 在本环境都被拦
|
|
|
- （exit 1 且无任何输出），但 **`[System.IO.File]::Delete('绝对路径')` 可用** ——
|
|
|
- `ThinkingPanel.vue` 已用这招成功删除。
|
|
|
-- 验证：`type:check` → src/ai 0 错误；`build` → 通过。
|
|
|
-
|
|
|
-### 追加（第五轮）：模型 ID 精度丢失（雪花 Long 被当 number）
|
|
|
-用户报："聊天发起会话 参数 模型id 会精度丢失。"
|
|
|
-
|
|
|
-**根因（前端，不是后端）**：
|
|
|
-`agent_model.id` 是 `@TableId(type = IdType.ASSIGN_ID)` 的雪花 Long（19 位）。
|
|
|
-后端**已经**做了防护 —— `common/utils/Json.java` 的静态块里给 Long 注册了 `ToStringSerializer`，
|
|
|
-且 `WebConfig.objectMapper()` 把这个 ObjectMapper 注册为 MVC 的 `ObjectMapper` bean。
|
|
|
-实测 `GET /js/a/models` 返回 `"id":"3087155156336591230"`（**字符串**）→ 后端这侧是对的。
|
|
|
-
|
|
|
-问题在第四轮我改 ChatComposer（a-select → Dropdown + Menu）时**引入了 `Number(key)`**：
|
|
|
-`Number("1759223390755964589")` === `1759223390755964608` → 末位被抹 → 传回后端就成了另一个模型。
|
|
|
-同类隐患还有 `aiAnalysis/index.vue` 的 `Number(userStore.getCaseInfo?.id || 0)`
|
|
|
-（本机案件 ID 恰好是 `2`，所以没暴露，但属于同一颗雷）。
|
|
|
-
|
|
|
-**修法：ID 全链路按字符串处理，并用 TS 类型钉死**
|
|
|
-- `api/types.ts`：`AiModel.id`、`ChatSession.id`、`ChatMessageVO.{id,sessionId,parentId,replyToMessageId}`、
|
|
|
- `CreateChatSessionParams.modelId`、`ChatStreamParams.modelId`、`SendMessageParams.sessionId`
|
|
|
- 全部 `number → string`（`CreateChatSessionParams.workspaceId` 用 `string | number` 兼容）
|
|
|
-- `api/modelApi.ts` / `api/chatApi.ts`：路径 id 参数 `number → string`
|
|
|
-- `store/chatStream.ts`：`workspaceId`、`activeSessionId`、所有 `sessionId` 参数改 string；
|
|
|
- 新增 `isTempId(id)`（负数前缀＝本地临时消息），`nextTempId()` 返回字符串
|
|
|
-- `ChatComposer.vue`：**删掉 `Number(key)`** → `String(key)`；props/emit 改 string；
|
|
|
- `currentModelName` 用 `String()` 比较
|
|
|
-- `SessionList.vue`：`activeId` / emits / `editingId` / rename 参数改 string
|
|
|
-- `MessageToolbar.vue`：`persisted` 判断改为 `!String(id).startsWith('-')`（不再用 `id > 0`）
|
|
|
-- `aiAnalysis/index.vue`：`modelId` ref 改 string，`workspaceId` 去掉 `Number()`，5 个 handler 的 id 改 string
|
|
|
-
|
|
|
-**验证**：`type:check` → src/ai **0 错误**（全仓 trans 的历史错误仍在，无关）；`build` → 通过。
|
|
|
-
|
|
|
-**遗留（需用户处理）**：之前用丢精度的 modelId 创建过的会话，`agent_chat_session.model_id`
|
|
|
-在库里存的是被抹掉末位的错值，需要核对/清理。
|
|
|
-
|
|
|
-**★ 排查手法**：`grep -rn "Number(" src/ai` + 对照后端返回的真实 JSON（用 curl 落盘再读，
|
|
|
-PowerShell 前台直接输出在本环境常被吞，写文件再 Read 才可靠）。
|
|
|
-
|
|
|
-### 第六轮：工具调用详情"看不到内容"——两个真因（2026-09-17，已定位未修）
|
|
|
-用户报"聊天界面展示工具调用记录时没有展示入参和返回结果，JSON 要变表格"。
|
|
|
-第五轮其实已实现 ToolCallPanel + 表格渲染，**问题在真机行为，不在有没有写代码**。
|
|
|
-
|
|
|
-**证据链（都是实测，不是推断）**
|
|
|
-1. 数据侧没问题：`GET /js/a/chat/sessions/1494404202000630103/messages` → 单条 assistant 的
|
|
|
- `toolEvents` 13 条工具调用，`input`/`result` 全在（result 最长 297KB）。
|
|
|
-2. ★★ **`result` 比 `input` 多编码了一层**（核心 bug）：
|
|
|
- - `input` = `{"sql": "SELECT ..."}` → `JSON.parse` 得 **object** ✓
|
|
|
- - `result` = `"{\"resultId\":\"...\",\"columns\":[...]}"` → `JSON.parse` 得 **string**，
|
|
|
- 要 parse **两次**才是表格对象（keys= resultId/sql/columns/rows/page/pageSize/totalRows/totalPages）
|
|
|
- - 后果：`ToolCallPanel` 里 `JSON.parse(step.result)` 拿到 string → `buildTable()` 恒返回 null
|
|
|
- → **JSON 表格从来没渲染成功过**，永远落回 `<pre>` 原始 JSON（还是带转义的样子）
|
|
|
-3. ★ UI 实测（playwright-core + headless chrome，dev 3100）：
|
|
|
- `detail button = exists opacity=0 display=flex size=18x18 visible=false`，
|
|
|
- hover 后 `opacity=1`（出现在 `.ai-trace__row:hover` 里）→ 那个详情按钮**默认完全不可见**，
|
|
|
- 用户根本发现不了要再点一次，表现就是"没有展示入参和输出"
|
|
|
- （脚手架脚本：`C:/Users/cc/AppData/Local/Temp/ai-verify/ui-tool-detail.cjs`，
|
|
|
- 直接复用案件 2 / 会话"端到端验证-已重命名"，全程只读、不烧 token）
|
|
|
-
|
|
|
-**Fix 方向（用户确认后执行）**
|
|
|
-- 后端 `AgentChatServiceImpl` 累加 `ToolResultTextDeltaEvent.getDelta()` 时做一次
|
|
|
- `unwrapJsonString()` 归一化（首尾 `"` 且能 readValue 成 String 就解一层、幂等），
|
|
|
- SSE 帧与落库同时修好；顺带修 409 行 `if (!result.isEmpty())` 的 NPE（无 delta 时 get() 为 null）
|
|
|
-- 前端 `parseToolEvents` / `onToolResult` / `ToolCallPanel` 统一做"最多解一层多余包装"的容错
|
|
|
- （历史数据已双重编码，必须兼容，否则老会话还是渲染不出表）
|
|
|
-- 交互：工具行整行可点、展开态常驻箭头、行内提示"入参 · 输出 N 行"，不要再靠 hover 才显形
|
|
|
-
|
|
|
-**复用要点**：`agentscope-2.0.0-sources.jar`（m2 里有 sources 包）可用 node 手工解析 zip
|
|
|
-中央目录（本地文件头 compSize=0，必须走中央目录）提取任意 `.java` 源码来核对框架行为。
|
|
|
-
|
|
|
-### 第六轮 · 已执行并验证通过（2026-09-17）
|
|
|
-
|
|
|
-计划文档 `tool-call-detail-plan.md`（仓库根）已按用户拍板执行。
|
|
|
-
|
|
|
-**后端** `AgentChatServiceImpl.java`
|
|
|
-- 新增 `private static String unwrapJsonString(String)`：首尾是 `"` 且 `MAPPER.readValue(v, String.class)`
|
|
|
- 成功就返回内层，否则原样返回；**幂等**（二次调用结果不变）。`MAPPER` 复用文件里已有的
|
|
|
- `private static final ObjectMapper MAPPER = new ObjectMapper();`（line 71），未新增字段。
|
|
|
-- `ToolResultTextDeltaEvent` 分支累加时套一层 `unwrapJsonString(e.getDelta())`。
|
|
|
-- 顺带修 `ToolResultEndEvent` 分支的 **NPE**：原来是 `if (!toolResults.get(id).toString().isEmpty())`，
|
|
|
- 无 delta 时 `get()` 返回 `null` → NPE。改成 `StringBuilder acc = ...; String text = acc == null ? "" : unwrapJsonString(acc.toString()); if (!text.isEmpty())`。
|
|
|
-- `buildToolEventsJson` 里 `ev.put("result", ...)` 同样走 `unwrapJsonString`。
|
|
|
-- **只在写入侧归一化**（SSE 帧 + 落库两条路径都过这方法），历史数据靠前端容错兼容。
|
|
|
-
|
|
|
-**前端**
|
|
|
-- `utils/parseMessageContent.ts` 新增两个工具函数：
|
|
|
- - `parseJsonPayload(raw)` —— parse 一次；结果是 string 就**再 parse 一次**（治双重编码），
|
|
|
- 返回 object/array 才算成功，否则 null。
|
|
|
- - `normalizeToolPayloadText(raw)` —— 双编码就返回内层 JSON 文本，否则原样；**幂等**。
|
|
|
- - `parseToolEvents` 对 input/result 都过 `normalizeToolPayloadText`；
|
|
|
- - `parseTableFromToolResult` 由 `try{JSON.parse}` 改为 `parseJsonPayload`。
|
|
|
-- `store/chatStream.ts`：`onToolInput` / `onToolResult` 都过 `normalizeToolPayloadText`（流式期间也治）。
|
|
|
-- `components/ToolCallPanel.vue` **重写**：
|
|
|
- - `payload` 用 `parseJsonPayload`；`isTablePayload`（`scanner.ts`）判表格；`truncated`（≥100000 字）；
|
|
|
- - `sqlText` 从 input 里抽 `.sql` 字段，**单独一个代码块**渲染 + 折叠/展开 + 「全部参数」切换；
|
|
|
- - 表格行 `withRowKeys()` 前置 `__key`，`rowKey = '__key'`（**常量字符串**，不是函数
|
|
|
- —— 修掉 ant-design-vue 的 `rowKey` 弃用告警）；
|
|
|
- - 表格形态保留「原始 JSON」切换；非表格不再给 `isJson/rawText/showRaw`，直接 pretty。
|
|
|
-- `components/ProcessTimeline.vue` **重写交互**：
|
|
|
- - `expanded = ref(true)`（过程区默认展开）；`watch(active)` **只展开、不收起**
|
|
|
- （原来自动折叠，用户手动操作过就尊重手动 —— `userToggled` 只在 click handler 里置位）。
|
|
|
- - `collapsedThinks = ref<Set<string>>(new Set())` —— **思考默认展开**（语义反转：集合里存的是"被手动折叠的"）。
|
|
|
- - 工具行**整行可点**（`<button class="ai-trace__row is-tool">`），行内 `detailHint` 显示「入参 · 输出 N 行」，
|
|
|
- caret 常驻 `opacity: 0.5`；删掉旧的 `.ai-trace__detail-btn`（原来 opacity:0 + 只在 hover 显形，
|
|
|
- 用户根本发现不了，这是「看不到内容」的第二真因）。
|
|
|
- - `openSteps` 自动选中一个工具：历史取第一个有 result 的，流式取最后一个有 result 的；`stepTouched` 防覆盖。
|
|
|
-- `components/blocks/DataTableBlock.vue`：`rowKey` 由函数改 `(row) => \`${page.value}-${rows.value.indexOf(row)}\``，同样为消告警。
|
|
|
-- `styles/ai.less`：`@media (hover: none)` 里删掉已不存在的 `.ai-trace__detail-btn`。
|
|
|
-
|
|
|
-**验证（全过）**
|
|
|
-- 后端 `mvn -pl ai-server -B clean compile` → **BUILD SUCCESS**
|
|
|
-- 前端 5 个改动文件 `eslint --max-warnings 0` → **0 错误**；
|
|
|
- `vue-tsc --noEmit --skipLibCheck` → 全仓 **103**（与既有基线一致），`src/ai` **0 错误**；
|
|
|
- `vite build` → **EXIT=0**（约 1m52s）
|
|
|
-- **真实数据脚本** `normalize.verify.cjs`：取 2 个真会话的 `toolEvents`（53 次工具调用，52 条双编码）
|
|
|
- → 修复前 **0 张表**；修复后 **27 张表 / 413 行 / 27 个 SQL 入参**；再跑一遍结果完全一致（**幂等 PASS**）。
|
|
|
- ★ 脚本第一版断言写错：不该要求 `singleParseOk === total` —— `execute`/`write_file` 这类工具
|
|
|
- 的 result 本来就是纯文本（如 `Exit code: 0`），16 条非对象是正常的。
|
|
|
-- **组件级 UI 验证** `ui-tool-component.cjs` → **PASS**：过程区默认展开、2 段思考都展开、工具行可点、
|
|
|
- 详情默认展开 1 个、表格 3 行表头正确、SQL 代码块在、原始 JSON 切换可用、流式结束后仍展开、手动折叠生效、**0 控制台错误**。
|
|
|
-- **真机会话 UI 验证** `ui-tool-detail.cjs`（案件 2 / 会话"端到端验证-已重命名"）：
|
|
|
- 5 个 trace 块 / 过程区展开 / **40 个工具行** / 旧 detail-btn **0** 个 / 默认展开详情 **5** 个 /
|
|
|
- 默认渲染表格 **4** 张 / SQL 代码块 **3** 个 / 行内提示「入参 · 输出 N 行」/ 点第 2 行详情变 6 / **0 控制台错误**。
|
|
|
-- ★ 反复踩的脚手架坑：`page.evaluate` 里引用外部变量必须作为**参数传入**
|
|
|
- （`page.evaluate(async (tablePayload) => {...}, tablePayload)`），否则 `tablePayload is not defined`。
|
|
|
-- ★ 断言数字要按真实 DOM 算：2 个工具行只切了第 1 个到原始 JSON，所以表格数应 `=== 1` 而不是 `0`。
|
|
|
-- ★ **dist 时间戳比对**：改动前先确认 `dist` 构建时间**早于** src 改动时间，才能断定「旧行为是真 bug，
|
|
|
- 不是构建过期」—— 这一步省掉会白改代码。
|
|
|
-
|
|
|
-### 关系图谱侧边栏两个入口按钮去掉背景色（2026-09-17）
|
|
|
-用户："聊天界面的关系图谱点击对象出来的侧边栏，通话记录和交易记录按钮都保持无背景色。"
|
|
|
-- 文件：`ai-frontend/src/ai/components/blocks/GraphBlock.vue`
|
|
|
-- 原逻辑：侧边栏（`.ai-graph__detail-actions`）里两个按钮会按 `activeNodeKind`
|
|
|
- （该节点关联边是否全是同一类型）给其中一个加 `is-primary`，表现为淡紫底 + 紫边框，
|
|
|
- 用户不想要这个"主入口"视觉。
|
|
|
-- 改动：模板去掉两处 `:class="{ 'is-primary': ... }"`（并顺手把两个 button 折成单行）；
|
|
|
- 删除仅此处使用的 `activeNodeKind` computed；删除 `.ai-graph__btn.is-primary` CSS 规则与注释。
|
|
|
- 按钮回到 `.ai-graph__btn` 默认态（`background: transparent` + 透明边框），仅 hover 时高亮。
|
|
|
-- 未动 `resolveEdgeKind`（另有调用点）与连线兜底菜单 `.ai-graph__chooser-item`。
|
|
|
-- 验证：`node node_modules/eslint/bin/eslint.js --max-warnings 0 GraphBlock.vue` → **EXIT=0**（0 警告），
|
|
|
- 说明删掉的 computed 无残留引用。
|
|
|
-- ★ 本机 bash 缺 coreutils（`tail` / `sed` / `dirname` / `uname` 全 not found，`pnpm` 脚本因此跑不了），
|
|
|
- 要跑前端 CLI 得用 `node node_modules/<pkg>/bin/<x>.js` 直调。
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-## 关系图谱节点标识实体类型 → 点击节点按类型查明细（2026-09-17）
|
|
|
-
|
|
|
-需求（用户原话）：`GraphRenderTool` 要"标识节点的类型（人 / 电话号码 / 银行卡号）"，
|
|
|
-因为"查看详情时传入的参数不同 —— 是 personName，还是 personCard / personOtherCard / personPhone / otherPhone"。
|
|
|
-
|
|
|
-### 先认清的事实：两个弹框接口真实支持哪些字段（这是本次的"契约基准"）
|
|
|
-前端 `CallRecordModal` / `TransRecordModal` 的 `buildQuery` 透传项，与后端逐条核对过：
|
|
|
-
|
|
|
-| 弹框 | 接口 | 人 | 号码 | 卡号 |
|
|
|
-|---|---|---|---|---|
|
|
|
-| 通话记录 | `POST /cr/getCallRecord`（`CallRecordQuery`） | `personName` / `otherName` | `personPhones[]` / `otherPhones[]`（`otherPhone` 单值） | **无**（只有 `personCertNo` 证件号，语义不同） |
|
|
|
-| 交易记录 | `POST /trans/getTransRecord`（`TransRecordQuery`） | `personName` / `otherName` | **无** | `personCardNo` / `otherCardNo` |
|
|
|
-
|
|
|
-- `personName` / `personNames` 在基类 `common/base/Query.java` 里（不在 `CallRecordQuery`）；
|
|
|
-- 两个 mapper 都**确实**把这些字段拼进了 WHERE（`CallRecordMapper.xml:75/130/141/152`、
|
|
|
- `TransRecordService` 的 lambda wrapper），所以不会出现"字段不认 → 退化成全表"的坑；
|
|
|
-- 卡号在通话记录、号码在交易记录**都没有对应字段** → 前端要置灰按钮并说明原因，而不是查出空表。
|
|
|
-
|
|
|
-### 后端改动
|
|
|
-- 新增 `common/enums/GraphNodeType.java`：`person` / `phone` / `card` / `other`，
|
|
|
- 照 `GraphEdgeType` 的写法带 `label` + `aliases` + `from()` + `allowedCodes()`；
|
|
|
- 归一化会去掉空白/下划线/连字符再比大小写，因此 `obj` `tel` `bank_card` `银行卡号` 都能认。
|
|
|
-- `GraphSpec.Node` 新增 `public String type`（**非必填**，`required=false`），`name` 的描述改为
|
|
|
- "同时是查询该节点明细的关键字"（卡号节点别写「张三的卡」）。
|
|
|
-- `GraphRenderTool.validateAndNormalize`：节点 type 归一化成 code 并**写回**（前端总能拿到）；
|
|
|
- 非法值报错列出取值；**缺失时按节点值兜底推断** —— 11 位手机号 → phone、
|
|
|
- 15-19 位纯数字（先去掉空格）→ card、其余 → person。人名不会长成这两种形态，所以推断很保守。
|
|
|
-- `@Tool.description`、`AgentService` 系统提示词（render prompt 第 3 条）、
|
|
|
- `GraphAnalysisTool#get_case_graph` 的字段映射说明（补 `clazz→type`：obj→person、tel→phone、card→card）
|
|
|
- 三处同步更新。
|
|
|
-
|
|
|
-### 前端 `ai/components/blocks/GraphBlock.vue`
|
|
|
-- 新增 `NodeType` / `NODE_TYPE_ALIASES` / `NODE_TYPE_LABELS` / `resolveNodeType()`（认不出按 person，与老图谱行为一致）。
|
|
|
-- 新增 `SIDE_FIELDS`：**弹框 × 节点类型 → { mine, theirs }** 字段映射，缺项＝该弹框查不了这种节点。
|
|
|
- `SideField.array` 标记数组字段（`personPhones`/`otherPhones` 后端是 `List<String>`）。
|
|
|
-- ★ `fetchPairRecords` 泛化成 `fetchMergedRecords(kind, conditions[], query)`：
|
|
|
- 条件组数组，每组一次请求再合并去重（原双向合并逻辑不变），`PAIR_FETCH_LIMIT` 改名 `MERGE_FETCH_LIMIT`；
|
|
|
- 公共 query 里要先删掉 `CONDITION_FIELDS`（9 个），否则每组条件都会被同一个值锁死。
|
|
|
-- `pairContext`（只存 a/b 两个名字）→ `mergeContext`（存 conditions 数组），因为条件表达式不再只有
|
|
|
- "personName + otherName" 一种形态。
|
|
|
-- **点击节点也变成两侧合并**：`[{personName:v},{otherName:v}]` / `[{personPhones:[v]},{otherPhones:[v]}]`
|
|
|
- / `[{personCardNo:v},{otherCardNo:v}]`。理由：卡号/号码既可能落在记录的本方也可能落在对方字段，
|
|
|
- 只查一侧会漏；项目图谱页对 card 节点本来就是"该卡作为本方卡或对方卡都算"（`GraphService#nodeDetail`）。
|
|
|
-- 点击连线：`{source.mine, target.theirs}` + `{target.mine, source.theirs}`；某端在该弹框没有字段时
|
|
|
- 退化成"只按能表达的那一端查"，而不是整条边查不了。
|
|
|
-- UI：侧边栏详情面板新增「类型」一行；两个入口按钮按类型 `disabled` + `title` 说明
|
|
|
- （卡号节点的"通话记录"、号码节点的"交易记录"置灰）；`chooser` 兜底菜单改存节点对象（原来存名字，拿不到类型）。
|
|
|
-
|
|
|
-### 行为变化（要记住）
|
|
|
-单节点明细查询从「服务端分页 + 只查本方字段」变成「两侧各查一次 + 客户端分页」，
|
|
|
-所以每组条件最多取 500 条（原双向合并的代价，现在扩大到了单节点场景）。
|
|
|
-
|
|
|
-### 验证
|
|
|
-- 后端 `mvn -pl ai-server -B test -Dtest=GraphRenderToolTest` → **Tests run: 15, Failures: 0**
|
|
|
- （新增 3 个：缺失 type 的兜底推断、中文/旧写法归一化、非法 type 报错；schema 断言补了节点 type 可选+描述）
|
|
|
-- 前端 `eslint GraphBlock.vue --max-warnings 0` → 0；`vue-tsc --noEmit` → `src/ai` **0 错误**（全仓仍 103 基线）；
|
|
|
- `vite build --mode production` → **EXIT=0**
|
|
|
-- ★ 顺手修掉一个**既有**编译错误：`GraphRenderToolTest` 里 `spec.edges.get(0).value = 3.5`
|
|
|
- 对 `Integer value` 赋值（HEAD 就这样，测试一直编译不过）→ 改成整数 35 并更新 DisplayName。
|
|
|
-
|
|
|
-### 环境备忘（新增，很关键）
|
|
|
-- ★ **本机 bash 里 `mvn` 跑不了**：`/d/soft/apache-maven-3.9.12-bin/bin/mvn` 依赖 `uname`/`dirname`，
|
|
|
- 而 Git Bash 缺 coreutils → `ClassNotFoundException: ...launcher`。**必须用 PowerShell 调 `mvn.cmd`**：
|
|
|
- `& "D:\soft\apache-maven-3.9.12-bin\bin\mvn.cmd" -pl ai-server -B test "-Dtest=xxx"`。
|
|
|
-- 跑长命令用 `> 日志文件 2>&1` 落盘再读；在 bash 里用 `node -e` 过滤日志时，正则里的 `\.java:\[`
|
|
|
- 会被 shell 转义搞坏（`Unterminated regexp literal`），别把复杂正则塞进命令行。
|
|
|
-
|
|
|
----
|
|
|
-
|
|
|
-## 持续联系页「AI 研判」功能 —— 设计文档（待用户确认，未编码）
|
|
|
-
|
|
|
-产出：`continuous-insight-plan.md`（仓库根）+ 4 张布局草图（show_widget 内联）。
|
|
|
-
|
|
|
-### 关键设计决策（用户确认后才动手）
|
|
|
-- **入口**：① 面板标题栏「AI 研判」主按钮（分析整个查询结果集，TOP 100）② 操作列「AI 解读」
|
|
|
- （单条关系对，操作列 120 → 176）。抽屉打开即自动发起首轮分析，不用敲字。
|
|
|
-- **面板形态**：右侧抽屉 640px（可拖拽 480–1000）+ 右上「全屏」复用同组件。不新建页面。
|
|
|
-- **结构化输出**：新增 ` ```insight ` 围栏 → 前端新增 `InsightBlock.vue` 渲染线索卡
|
|
|
- （等级/类型/证据/可疑点/动作按钮）+ 下一步思路清单。扩展点只有三处：
|
|
|
- `utils/constants.ts`（BlockKind + FENCE_BLOCK_MAP）、`scanner.ts`（查表自动覆盖）、
|
|
|
- `BlockRenderer.vue`（加分支）。解析失败退化为 Markdown，不空屏。
|
|
|
-- **存储独立**：新表 `agent_insight_session` / `agent_insight_message`（含 `context` jsonb、
|
|
|
- `output_json` jsonb 便于线索跨会话聚合），**完全不复用** `agent_chat_session` / `agent_message`。
|
|
|
-- **★ 动态系统提示词**：`sysPrompt = 静态人设(prompts/insight/CALL_CONTINUOUS_INSIGHT.md)
|
|
|
- ⊕ 动态上下文（案件+查询条件+数据口径说明+结果数据表）⊕ insight 围栏契约`。
|
|
|
- 创建会话时拼好并落库，**会话内不变**；追问不重新拼装。
|
|
|
-- **★ 必须新开 Agent 实例池**：现有 `AgentService#agentPool` 的 key 是
|
|
|
- `w{workspaceId}-a{agentRowId}-m{modelId}`，**没有 sysPrompt 维度** —— 复用会让动态提示词在
|
|
|
- 不同会话间串台。新池 key = `insight-s{sessionId}`，LRU 64 / 空闲 30min 回收。
|
|
|
-- **Agent 参数**：默认 LLM 模型；maxIters=6；不挂 Intent/Followup 中间件（Followup 的"下一步建议"
|
|
|
- 与本功能自带的 nextSteps 重复）；工具默认装备 `call` 组，其余组由模型自行 `reset_equipped_tools` 激活。
|
|
|
-- **需要的向后兼容改造**：`AgentToolRegistry#registerBusinessTools(Toolkit)` 增加重载
|
|
|
- `(Toolkit, List<String> activeGroups)`（原方法委托 `DEFAULT_ACTIVE_GROUPS`），现有调用方零改动。
|
|
|
-- **代码落位**：`module/agent/insight/`（不新建 `module/insight`，因 `AI_AGENT.md §4` 规定
|
|
|
- `<domain>` 固定取值集合，且强耦合 agent 子系统；"独立存储"由独立表满足）。
|
|
|
-- **接口**：`/insight/continuous/{sessions,stream,sessions/{id}/messages,clues}` +
|
|
|
- `GET /insight/continuous/messages/{messageId}/trace`（按需拉工具明细/思考）；
|
|
|
- **所有读接口一律 `id + case_id` 双条件**。SSE 与 `/chat/stream` **完全同构**（仅新增 `insight` 一帧），
|
|
|
- 前端解析器 100% 复用；`/insight/**` 与 `/chat/**` 一致走**裸返回**
|
|
|
- （有意偏离 AGENT.md §4 的 Result 约定，已文档化）。
|
|
|
-- **前端不复用 `ai/store/chatStream.ts`**（单例全局态，与 AI 分析页会互相搅乱）→ 新写
|
|
|
- `useContinuousInsight.ts` 组合式 hook；但把 SSE 解析器从 `chatApi.ts` 抽到 `ai/api/sse.ts` 共用。
|
|
|
-- **提示词硬约束**：线索 3–6 条、每条必须有可核验数字证据、必须给下一步核验动作、
|
|
|
- **无有效线索时必须显式说明原因禁止编造凑数**、禁止编造未提供数据、引用号码脱敏。
|
|
|
-
|
|
|
-### 用户已确认（2026-09-17）
|
|
|
-- **入口：只做面板级主按钮**，表格操作列不动；行级「AI 解读」本期不做（`scope=PAIR` 预留）。
|
|
|
-- **线索输出：结构化围栏 + 卡片**（P0 先出纯 Markdown 报告验收，P1 上 ` ```insight ` 与线索卡）。
|
|
|
-- **线索沉淀：预留接口不接页面**（后端落 `output_json` + `GET /insight/continuous/clues`；
|
|
|
- 「记入线索」与线索推送页对接留到后续需求）。
|
|
|
-- **后端落位：`module/agent/insight/` 子包**。
|
|
|
-- ★ **会话存储：入库，独立两张表（用户最终拍板）**。文档 §4.1 已整节重写为「数据库表设计」：
|
|
|
- - 表：`agent_insight_session`（id/case_id/biz_type/scope/agent_row_id/model_id/title/context jsonb/
|
|
|
- context_hash/sys_prompt/message_count/last_seq/total_tokens/last_message_at/pinned/status/create_at/update_at）
|
|
|
- + `agent_insight_message`（id/session_id/**case_id 冗余**/**seq**/role/content/content_type/message_type/
|
|
|
- metadata jsonb/tool_events jsonb/output_json jsonb/token_count/reply_to_message_id/starred/status/create_at）
|
|
|
- - **三层隔离**：独立表（与 `agent_chat_session` 物理分离）→ `case_id` 强制 where（硬边界）→
|
|
|
- `session_id + case_id` 双条件（消息表冗余 `case_id` 就是为了让这条能在 SQL 层面写出来）。
|
|
|
- - **三条不变量（要写成测试）**：① 不存在只按 `session_id` 查消息的 SQL；② 写消息前先校验会话归属；
|
|
|
- ③ `biz_type` 恒常量 `CALL_CONTINUOUS`。
|
|
|
- - ★ **滚动加载用「普通分页接口」，不用游标参数**（用户 2026-09-17 明确要求）：
|
|
|
- `GET .../sessions/{id}/messages?caseId=&page=&limit=`，**参数名沿用项目 `Query` 约定**
|
|
|
- （`common/base/Query.java`：`page` 默认 1、`limit` 默认 20），复用 **MyBatis-Plus `Page`**，
|
|
|
- 返回 `{records, total, size, current, pages}`；**排序 `ORDER BY seq DESC` 服务端写死**
|
|
|
- （忽略 `orderKey`/`sort`），第 1 页 = 最新 N 条。前端上滑到顶 `page+1` → `records.reverse()` →
|
|
|
- `unshift` + **滚动位置补偿**（记 scrollHeight 差值）；切会话/首屏都 `loadPage(1)`；
|
|
|
- **不做 5s 轮询补消息**（靠 SSE 增量）。
|
|
|
- - ⚠️ **MP 分页插件注册的方言是 `DbType.DUCKDB`**（`common/config/MybatisPlusConfig.java:20`）。
|
|
|
- PG 与 DuckDB 都是 `LIMIT ? OFFSET ?`，本表在 PG 上可分页；若报方言错就退回 XML 手写
|
|
|
- `LIMIT/OFFSET` + 单独 `count(*)`。
|
|
|
- - ★ **`seq` 仍然必须有**（列保留），因为它是唯一可靠的**排序列**：
|
|
|
- 实体虽标 `@TableId(ASSIGN_ID)`，但 `AgentChatServiceImpl` 显式 `setId(generateId())` 覆盖，
|
|
|
- 而 `generateId()` = `UUID.randomUUID().getMostSignificantBits() & Long.MAX_VALUE` —— **随机非单调**；
|
|
|
- `create_at` 同毫秒撞车。所以 `ORDER BY seq DESC`，`seq` 由
|
|
|
- `UPDATE agent_insight_session SET last_seq = last_seq + 1 ... RETURNING last_seq`
|
|
|
- （配合会话行级锁）**原子分配**，比 `SELECT max(seq)+1` 安全（READ COMMITTED 下会重号）。
|
|
|
- - ⚠️ **页码分页的已知取舍（已写进文档 §4.1.5 / §9.7）**：消息持续追加时会出现「同一条消息出现在两页」
|
|
|
- 的轻微重复 → 前端按 `id` 去重兜底，不为此把分页复杂化。
|
|
|
- - `page` / `limit` 要白名单校验（`page ≥ 1`、`limit ≤ 100`）。
|
|
|
- - ★ **列表查询绝不 select `tool_events` / `output_json`**（单条 result 实测可达 297KB）→
|
|
|
- **禁用 `SELECT *`**；点开「分析过程」走独立接口 `GET /insight/continuous/messages/{messageId}/trace`。
|
|
|
- - 并发：应用内 `ConcurrentHashMap` 锁 + `UPDATE ... SET status='STREAMING' WHERE status='ACTIVE'`
|
|
|
- 双保险（affectedRows=0 → 409）；`seq` 分配靠 DB 行锁；消息落库是**消息粒度不是 token 粒度**；
|
|
|
- 「UPDATE last_seq + INSERT + UPDATE message_count」同一事务。
|
|
|
- - 索引：`idx_ais_case_list (case_id, biz_type, last_message_at DESC)`、`idx_ais_ctx_hash (case_id, context_hash)`、
|
|
|
- `idx_aim_output (case_id, create_at DESC) WHERE output_json IS NOT NULL`；`uk_aim_session_seq` 已够
|
|
|
- 支持 `seq DESC` 排序翻页，**不需要**再加 `(session_id, seq DESC)`。
|
|
|
- - DDL 落 `sql/`；代码落位去掉 `store/` 文件包，改为 `entity/ AgentInsightSession|AgentInsightMessage`
|
|
|
- + `mapper/`（归属过滤收在方法签名里，如 `selectByIdAndCase`）。
|
|
|
- - 字段风格对齐现有实体：`jsonb` 用 `JsonbTypeHandler`、`create_at/update_at` 用 `FieldFill.INSERT/INSERT_UPDATE`
|
|
|
- 的 `LocalDateTime`（DDL 用 `TIMESTAMP`，不是 `TIMESTAMPTZ`）。
|
|
|
- - 钩子提醒：`ON DELETE CASCADE` 只在**物理删会话行**时生效；案件若是软删要另行处理。
|
|
|
-
|
|
|
-### 状态
|
|
|
-设计已定稿（`continuous-insight-plan.md` §8 记录了全部决策、§9 记录了 10 条风险），
|
|
|
-**用户尚未下达开工指令，未编码**。
|
|
|
-
|
|
|
-
|
