# zsjz-ai 项目长期记忆

## 本机环境怪癖（每次会话都会遇到）

- **bash 工具可用**（2026-09-24 起实测 `ls/cat/grep/sed/find/rm/cp/comm/diff` 都正常）；
  早期会话的「shim 报 dirname not found」已不复现。仍优先用 Glob/Grep/Read 读文件。
- PowerShell 工具的 stdout **不回显**：要拿输出必须落盘再读。落盘务必用
  `... | Out-File -FilePath <f> -Encoding utf8`；**`>` 会写成 UTF-16**，Read 工具会当二进制拒绝。
- `Remove-Item` 被 safe-delete 钩子拦截 → 删文件用 `[System.IO.File]::Delete('绝对路径')`；bash `rm -f` 可以。
- 仓库根 = 主仓库 `E:\workspace\zsjz-ai`（git common dir）；当前 worktree 是
  `C:\Users\cc\WorkBuddy\Worktrees\zsjz-ai\dev-3-*`。**worktree 只有被跟踪的文件**，
  被 gitignore 的本地目录不会带过来（见下），缺东西时去主仓库拷。

### worktree 首次可用的初始化（2026-09-24 踩实）

1. **`frontend/` 是 pnpm 项目**：`pnpm install` 会因 esbuild postinstall 报
   `spawnSync node.exe EBUSY`（沙箱里孙进程 spawn node 被拦），**而且失败后 `node_modules/.bin`
   不会生成**，于是 `pnpm type:check / build` 全报「不是内部或外部命令」。
   → 解法：`pnpm install --ignore-scripts`。esbuild 真二进制在 `@esbuild/win32-x64`，
   postinstall 只是 `--version` 校验，跳过无害（实测 `require('esbuild').version` 正常）。
2. **`ai-electron/` 是 npm 项目**（只有 `package-lock.json`，node_modules 是扁平结构、无 `.pnpm`）：
   **不要用 pnpm 装**（会因 `esbuild@^0.28.0` 解析失败 —— 镜像元数据里 latest 还是 0.27.4）。
   正确姿势：从主仓库拷 `ai-electron/package-lock.json`（被 gitignore 了），再
   `npm install --ignore-scripts --no-audit --no-fund`（约 23s / 710 包）。
   校验命令：`npx tsc --noEmit`（= `npm run typecheck`）、`npm test`（vitest，91 用例）、
   `npm run build-electron`（产出 `public/electron/main.js`）。
3. 被 gitignore 误伤、worktree 里没有、缺了直接构建失败的目录（从主仓库 `cp -r` 过来，不会污染 git status）：
   - `ai-electron/frontend/build/`（根 `.gitignore:22` 的 `build/` 命中；vite.config.ts 要 `./build`）
   - `ai-electron/frontend/src/case/views/data/`（`ai-electron/.gitignore:7` 的 `data/` 命中，
     把源码目录也误伤了；路由 `routes/index.ts` 直接引用，51 个文件）
   - `ai-electron/package-lock.json`
4. 其余 5600+ 条「主仓库有、worktree 没有」都是运行时垃圾（`data/`、`out/`、`logs/`），不用管。

## 前端（`ai-electron/frontend/`）

- 技术栈：Vue 3 + `<script setup lang="ts">` + ant-design-vue + vite + less + pnpm。
- 常用命令（cwd 一律在 `ai-frontend/`）：
  - 构建：`pnpm build`（= `vite build --mode production`，**不做类型检查**，约 2 分钟）
  - 类型：`pnpm type:check`（= `vue-tsc --noEmit --skipLibCheck`，约 25 秒）
- **`pnpm type:check` 本来就过不了**：仓库有约 89 条既有报错，集中在
  `src/call/`、`src/trans/`、`src/graph/`、`src/otg/`、`src/person/` 等无关文件。
  判断自己有没有写坏，看的是「报错文件里有没有自己动的文件」，不是退出码。
- `tsconfig.json`：`isolatedModules: true`，无 `verbatimModuleSyntax`；`noUnusedLocals: false`（所以多余的 import 不报错）。
- **暗色主题的既有缺陷**：`vite-plugin-theme-vite3` 生成的
  `dist/assets/app-antd-dark-theme-style.*.css` 里，**自定义属性的 `--` 前缀被抹掉**
  （搜 `--codex-bg` / `--ai-text` 都是 0 处，只有 `codex-bg` / `ai-text`）。
  即暗色模式下 `--ai-*` / `--codex-*` / `--jeesite-*` 都不会被覆盖，页面沿用浅色 `:root` 值
  （antd 类名那部分正常）。全项目同等影响，v2.1 之前就存在；修它要动构建期主题插件，未动。
- 构建时那条 `WARN warnings when minifying css: Invalid character(s) '@charset UTF-8";` 是同一个
  主题插件的产物拼接问题，同样与业务代码无关。
- 路由 / 别名：`@/*` → `src/*`；路由表在 `src/core/router/routes/index.ts`。
- less 全局变量靠 `build/theme/modifyVars.ts` 里的
  `hack: 'true; @import (reference) "src/core/design/var/index.less";'` 注入，
  所以任意 `.vue` style 块和任意 `.less` 文件都能直接用 `@modal-header-bg-color` 这类变量，
  SFC 的 style 抽成独立 `.less` 再 `@import` 回来是安全的。
- ant-design-vue 的 Modal / Popover / Select 会 teleport 到 body，**样式必须全局（非 scoped）**，
  靠 `wrapClassName` + 全局类名命中。

## 新增页面 / 菜单入口机制（纯前端，不走后端）

- **菜单不在后端**：来自本地 `src/core/store/modules/menu.json`（`permission.ts` 直接 import 它当 RootRoute）。
  加页面 = 往对应父分组 `children` 里塞一条（`path`/`component`/`url` 三者同值，`name` 形如 `ViewsXxxYyy`，`id` 用递增号）。
- **视图映射在 `src/core/router/helper/routeHelper.ts` 的 `explicitDynamicViewMap`**（显式登记优先于 glob 兜底），
  格式：`'/xxx/yyy': () => import('@/xxx/views/yyy/index.vue')`。
- 页面外壳沿用 `.ai-page` 那套反冲手法：`width: calc(100% + 20px); margin: 0 -10px;`，留 2px 灰底 gutter。

## Codex 数据分析新包（`src/codex/`，2026-09-24 起）

- 需求：**全新包、不复用 `src/ai/` 聊天代码、所有文件 `codex` 前缀**（含视图入口 `views/codexAnalysis/codexAnalysis.vue`）。
- 计划文档：仓库根 `codex-analysis-plan.md`（v1.0.0 → v1.9.0，逐版本停下 review）。
- **v1.0.0 ~ v1.9.0 已全部落地**（骨架 / 会话 / 流式对话 / 富内容块 / 图表关系图 / 过程与审批 /
  产物 / 报告导出 / 恢复与诊断 / 打磨）。前端 31 个文件全 `codex` 前缀；主进程新增
  `codexArtifactService.ts` + `codexArtifactCtl.ts`（root 白名单落盘 + 路径穿越校验 + 只读不删），
  `codexCtl.ts` 增量：`threadStart` 返回 `cwd`、`turnRun` 登记可选 cwd、新增 `defaultWorkspace`。
- **关键实现约定**：事件按 threadId 缓存（同 id 覆盖、isDelta 追加）；turn/completed 决定回合结局；
  围栏协议 `echarts/graph/table/json/report`，解析失败回退成代码块；导出 md/html/xlsx/长图(png)；
  HTML 报告里的图表靠 `utils/codexVisualRegistry.ts`（内容哈希 → 图片提供者）内嵌真实图片。
- **工作目录优先级**（v2.0.5 起）：会话 cwd → 该案件的手动覆盖(`cwdOverrides`) → **案件工作空间** → 客户端默认。
  案件工作空间 = `<user.dir>/QingJian/workspace/<案件ID>`，由后端 `CaseInfo.workspacePath` 回传
  （`@TableField(exist = false)`，`CaseInfoService.fillWorkspacePath` 在 open/current/list 返回前置值）。
- **验证口径**：前端 `pnpm type:check`（89 条基线、本包 0 报错）+ `pnpm build`（exit 0）；
  主进程 `npx tsc --noEmit` + `npm test`（91 用例）+ `npm run build-electron`；
  后端 `mvn -o -DskipTests compile`（仓库根，多模块，`ai-server` 是子模块）。
- **基座事实**：主进程 `electron/controller/codexCtl.ts` + `service/codex/*` 已全量可用；IPC 封装现在
  唯一实现在 `src/codex/api/codexApi.ts`，`src/ai/api/codexApi.ts` 只剩一行 `export *`。渲染唯一输入是
  `AgentEvent`（映射见 `service/codex/eventMapper.ts`）。
- **协议参考**：官方 `https://developers.openai.com/codex/app-server`；本地 schema 全集在
  `E:\workspace\ai\Noobi.ai\schemas\codex\v2\*.json`。**布局可参考 Noobi.ai（React），但样式必须用本项目主题**。

## cleaning 页拆分工程（`src/case/views/data/cleaning.vue`）

**当前进度（2026-09-18）**：`12029 → 944 行`（−92%），30+ 新文件，type:check 0 报错 + build 通过。
依赖顺序（单向、无环）：`useCaseDataCleaningShared`（底层状态）→ `useCleaningRules / useFieldMapping / useRecognitionRules / useTemplateLibrary`
→ `useCaseDataCleaningActions`（叶子动作域，放在最后所以能直接用上游产物）。
剩余（压到 ≤400）：① 把顶层 `watch([...])` 移进 composable（watcher 在 composable 内注册仍绑定页面实例）→ 21 个退回声明可搬走；
② 清未使用 import（匹配标识符要允许 `...` 展开）；③ `useCaseDataCleaningActions`(1310) 可按域再拆成 useFileTree / usePreviewData / useColumnOps。

- **消环的唯一正确姿势**：底层共享状态收进**唯一一个 shared composable**，其余域全部单向依赖它（+ 已有 handle）；
  叶子域一定要放在所有上游之后。不要用「多个平级 composable 互相注入」——底层状态同时被多方需要，会形成真实的环，
  拓扑排序无解；破环退化成空壳 composable 就是垃圾。
- 生成器可复用件（写这类脚本直接照搬）：
  - 声明解析用「**找下一个顶层起点**」，顶层起点要包含 `watch(` / `provide(` / `onMounted(` 等**非声明的顶层语句**，否则上一个声明的范围会吞掉它们
  - 模板取词：`{{ }}` + `: / v- / @ / ref` 绑定值 + 标签名；表达式剥掉 `'…'`/`"…"` 但**保留 `${...}` 插值**
  - 抽出的 `.ts` 补 `export`；跨文件相对路径按新层级重算；deps 类型**显式写 interface**（否则类型循环 → `Object.entries(any)` → `[string, unknown][]`）
  - 接线模式：**页面在 setup 中实例化 composable + 同名解构**（页面代码/模板零改动），`provide` 放在 setup 末尾；
    wiring 插在「最后一个依赖声明」**之后**（锚点是依赖声明的最后一行）

- 方案文档：仓库根 `cleaning-refactor-plan.md`。已拍板：**路由不动**（cleaning.vue 留作入口）、
  通信走 **provide/inject + 领域 composable**、样式保持**全局 less 非 scoped**、**业务逻辑一律不许动**、
  **每阶段停下来 review**。
- 目录：`cleaning/{types,constants,context}.ts` + `cleaning/{utils,composables,components,styles}/`
- 沟通模式（Phase 3 起确定的**主力模式**，后续阶段照这个来）：
  - 领域逻辑放 `composables/useXxx.ts`，**由页面在 setup 里实例化**
  - 页面用**同名解构**接住返回值（`const { a, b } = useXxx(...)`）→ 页面原有代码与模板**零改动**
  - 页面把 `useXxx` 实例放进 `provide(CleaningContextKey, { ..., xxx })`，子组件从 context 取
  - `provide()` 放在 **setup 末尾**（避开 const 声明顺序的 TDZ）；composable 的调用位置 = 「最后一个依赖声明之后」
  - **composable 的 deps 必须显式声明类型**（写 interface），不要让 TS 从实参反推 —— 页面里有 decl 的签名依赖返回值时
    会形成类型循环，导致 deps 退化成 `Record<string, any>`，而 `Object.entries(<any>)` 会产出 `[string, unknown][]` 引发一片 unknown 报错
- **验证必须 type:check + build 双跑**：`vue-tsc` **抓不到 Vue 模板标签不平衡**，
  抽块边界写错（多删一个 `</div>`）时 type:check 是 0 报错、`pnpm build` 才报 `Element is missing end tag`。
  抽模板块时边界要取「配对的 `</div>` 行」，不要凭缩进猜（这个文件缩进本身不严格）。
- 已踩实的坑：
  - 抽出的 `.ts` 必须补 `export`（无 import/export 的 .ts 会被 TS 当全局脚本 → `TS2306`）
  - 抽出文件引用原页面的相对路径 import 时，要按新层级重算（`@/` 别名例外）
  - **页面级 `let`/`var` 标量不能注入**：跨文件是按值快照，两边各改一份（请求序号守卫之类会失效）
  - **声明解析要用「找下一个顶层起点」**，不要用括号深度（多行泛型 `ref<\n Record<...>` 会让深度中途归零、把声明切一半）
  - **模板取词要保留 `${...}` 插值**，只剥 `'…'` / `"…"`（整段 strip 会把 `` `is-${x}` `` 里的 x 抹掉）
  - 判定「setup 顶层立即求值」时**只扫 wiring 位置之前的行**（末尾的 `provide(...)` 也是顶层语句，会假阳性）；
    `watch([...refs])` 整条都算立即求值；「可搬集合 ↔ wiring 位置」要迭代到收敛
  - 算「页面还要解构哪些名字」时，扫描范围 = **整份模板 minus 被抽走的块**（别漏掉保留在页面里的部分，比如面板里的匹配条/外层 wrapper）
  - 依赖若是页面里 `const { x } = someComposable;` 解构出来的，类型要写成 `ReturnType<typeof someComposable>['x']`（否则退化成 any → `Object.entries(any)` → unknown）；
    依赖类型文本里出现的类型名（`Ref<TemplateTab>` 里的 `TemplateTab`）也要补 import

- **验证「重构没改业务逻辑」的可靠做法**：拿 `git show HEAD:<原文件>` 当基准，和「当前入口 + 抽出目录整棵树」做
  **逐行多集合比对**（归一化：去 `export ` 前缀 / 折叠空白 / 去行尾 `,;`，跳过注释与 import），
  判定条件 = 原始每行在当前树里的出现次数 ≥ 原始次数。本项目已验证 **script 丢失/被改动 = 0**。
  注意：扫描范围只圈自己那一棵（别把同目录其它页面算进来）、SFC 的 template 结束点是 `<script` 不是 `<style`、
  取原始文件用 node `execSync(...,{encoding:'buffer'})`（PowerShell `>` 会写成 UTF-16，且 `cmd /c` 被拦）。

## 用户偏好

- **直接干活，不要反复审计**。
- **业务逻辑不许动**：重构只做搬家/抽取，逐行原样搬运。
- **每个阶段停下来给 review**，确认后才进下一阶段。
- 大文件重构：先给方案文档（会被认真审），方案里要列清决策点。
- **别生成一堆垃圾文档**，编译/构建通过就是完成标准。
- 不要留临时脚本、临时日志在仓库里，做完自己清理。