cc 1 неделя назад
Родитель
Сommit
2b10f0182f

+ 218 - 0
docs/design/pi-agent-feasibility.md

@@ -0,0 +1,218 @@
+# pi agent 底座可行性分析
+
+> 场景技能:`architecture-visualization:evolution-planner`;图源格式:`architecture-visualization:graphviz`
+> 状态:**决策稿,未实施**。目标态节点全部标注 proposed。
+> 日期:2026-11-10 | 配套图源:`docs/design/pi-agent-migration.dot`
+
+## 1. 结论
+
+**可行,且比 dsh 更贴合「二开一套」这个诉求**——但形态与 dsh 方案根本不同:
+
+- **dsh 路线**:加载 dsh 自带的 Web UI,我们写 **React** 插件塞进它的界面。UI 白送,定制受它的插槽/版本约束。
+- **pi 路线**:pi 作为 **headless 子进程**,我们**自己写 Vue agent 窗口**,经 stdio JSONL RPC 驱动。UI 全部自建,但完全掌控、且与既有 Vue3 技术栈一致。
+
+pi 的 RPC 文档开篇即写明用途:「language-independent integrations, process isolation, IDEs, and **custom user interfaces**」(`packages/coding-agent/docs/rpc.md`)。我们要做的正是官方指定场景,不是 hack。
+
+**推荐**:选 pi 做底座,接受「自建 agent 窗口 UI」这一最大成本项。理由是它同时满足四个硬条件:MIT 无商标约束、Windows 原生支持、扩展点是 TypeScript + SKILL.md(与既有资产同构)、核心极小(agent-core 仅 6 个源文件)。
+
+**但必须明确**:换 pi **不能**解决后端退役 AgentScope 的两个难题(embedding 与 Java 侧 LLM 传输),详见 §6。后端清理与选 pi 还是 dsh 无关,可并行推进。
+
+## 2. 证据与置信度
+
+所有 pi 侧结论取自 `earendil-works/pi` **main 分支原始文件**(注意:文档在 `packages/coding-agent/docs/`,**根 `docs/` 不存在**)。
+
+| 事实 | 证据 | 置信度 |
+|---|---|---|
+| MIT、TypeScript、121,112 stars、pushed 2026-11-10 | GitHub API `/repos/earendil-works/pi` | high(本机实测) |
+| `badlogic/pi-mono` 已迁移至同一 repo | GitHub API 301 → repo id 1035029907 | high(子代理实测) |
+| RPC = 长驻子进程 + stdin/stdout JSONL,四族记录,可选 `id` 关联 | `packages/coding-agent/docs/rpc.md` | high(本机实测) |
+| 启动式 `pi --mode rpc --no-session`;TS 侧有导出 `RpcClient`;进程内集成用 SDK | 同上 + `docs/sdk.md` | high |
+| 对话框子协议:`select/confirm/input/editor` → `extension_ui_request`,回 `extension_ui_response`(匹配 id),可带 timeout 由 agent 侧自动兜底 | `docs/rpc-extension-ui.md` | high(本机实测) |
+| RPC 下 `custom()` 返回 undefined、`setTheme()` 失败、footer/header/autocomplete/editor component 全 no-op | 同上 | high(本机实测) |
+| **无内置权限/审批系统** | 根 `README.md:90`「Pi does not include a built-in permission system for restricting filesystem, process, network, or credential access」 | high(本机实测) |
+| **无 sub-agents / plan mode** | 根 `README.md:19` | high(本机实测) |
+| **pi-ai 无 embedding**:`ModelTypeMap` 只有 `chat / image / classifier` | `packages/ai/src/types.ts:915-919` | high(本机实测) |
+| `createReadOnlyTools()` 存在;`ToolName` 含 `powershell` | `packages/coding-agent/src/core/tools/index.ts:204`、`:95` | high(本机实测) |
+| Windows 原生默认 Git Bash,可选 `powershell` 工具;解析序 `shellPath` → `%ProgramFiles%\Git\bin\bash.exe` → … | `docs/windows.md` | high(本机实测) |
+| 读 `AGENTS.md` / `CLAUDE.md` / `AGENTS.override.md`,来自 agent 目录、cwd 及其父目录 | `docs/configuration.md:18,41-45` | high(本机实测) |
+| **先解析 project trust 再加载项目设置与资源** | `docs/how-pi-works.md:49` | high(本机实测) |
+| 项目技能目录 `.pi/skills/`;实现 agentskills.io 规范;另支持 `~/.agents/skills/`、`.agents/skills/`(从 cwd 向祖先找至 repo 根) | `docs/configuration.md:35`、`docs/skills.md:7,61` | high(本机实测) |
+| agent-core `src/` 仅 6 文件(agent-loop/agent/types/proxy/stream-fn/index) | GitHub contents API | high(本机实测) |
+| `apps/p2` 标注 EXPERIMENTAL、「Do not build on it」 | `apps/p2/README.md` 顶部 WARNING | high(本机实测) |
+| v1.5.1(2026-11-09)、lockstep 版本、约周更 | GitHub `/releases` | medium(子代理实测,本人未复核) |
+| pi-web-ui 已删(曾为 Lit3 组件库,非可启动应用);pi-proxy 已删(曾为 CORS 转发器,非 LLM 网关) | commit `b141e1fa24`、`0f98decf65`;npm registry | medium(子代理实测) |
+| **零 Office 能力**(含官方 `badlogic/pi-skills` 集合) | 子代理全树检索 | medium(本人未独立复核) |
+| MCP 支持 stdio + streamable HTTP,**明确拒绝 legacy SSE** | `docs/mcp.md` | medium(子代理实测) |
+| extensions 为 TS 模块,`~/.pi/agent/extensions/` 或 `.pi/extensions/`,`/reload` 热重载 | `docs/extensions.md` | medium(子代理实测) |
+| 会话为 JSONL 树,`--session-dir` / `PI_CODING_AGENT_SESSION_DIR` 可改;workspace 概念 = cwd | `docs/session-format.md`、`docs/sdk.md` | medium(子代理实测) |
+| 新贡献者 issue/PR 默认自动关闭,需 maintainer `lgtm` | `CONTRIBUTING.md` | medium(子代理实测) |
+
+本仓侧结论均为本机 grep/读文件实测,路径行号见各节。
+
+## 3. 现状(current,有证据)
+
+- **agent 编排**:AgentScope `HarnessAgent`,`ai-server/.../module/agent/` 共 28 个子目录;`insight` 独占 25 个文件;45 个文件 import `io.agentscope`。
+- **前端**:`ai-electron/frontend/src/ai/`(aiWorkbench / aiPlugin / aiModel / 聊天组件),经 SSE `/chat/stream` 消费;`/workbench` 入口统一由 `frontend/src/core/router/guard/index.ts:69` 转成开窗。
+- **窗口**:`electron/service/window/smartWindow.ts` 已是独立顶层单例窗口;`electron/config/windowOptions.ts:25` 刻意不设 parent(VS Code Agents window 式)。Electron 侧现仅 window/download/os/setting 四类 service。
+- **案件库**:`cases/{caseId}/db/case.duckdb`(`common/storage/StorageLayout.java:142`);Java 持写锁,外部进程连 read_only 都打不开。
+- **副本机制已存在**:`common/datasource/DuckdbSnapshot.java:58` 用 `ATTACH + COPY FROM DATABASE` + 临时文件原子替换;入口 `CaseDataSourceRegistry.java:244` `exportSnapshot(caseId, target)`;指纹缓存与「失败不回退原库」策略见 `module/agent/python/PythonExecutor.java:685`。
+- **外部解释器已就绪**:`qingjian/system/python/python.exe` = Python 3.14.10 + **duckdb 1.5.6**(本机实测)。
+- **既有技能资产**:`ai-server/src/main/resources/skills/xlsx/SKILL.md`、`skills/report/SKILL.md`。
+- **承重墙(删 AgentScope 会打断)**:`aiclean/match/AiTemplateMatcher.java:16`、`aiclean/index/AiCleanTemplateVectorIndex.java:15`、`dm/ai/FileRecognitionService.java:10`、`knowledge/KnowledgeDocIndexer.java:5`、`knowledge/service/KnowledgeBaseService.java:7`、`plat/service/CaseDataCleanupService.java:4`。
+- **关键缺失**:agent 模块外 grep `OkHttpClient|WebClient|HttpClient|RestTemplate|chat/completions|embeddings` **零命中**——仓内没有任何非 AgentScope 的 HTTP LLM 客户端。
+
+## 4. 目标形态(proposed,未实施)
+
+```
+主窗口 Vue(既有业务界面)        agent 窗口 Vue(新建·独立顶层 BrowserWindow)
+                                 ├─ 案件空间选择器
+                                 ├─ 模式切换:数据分析 / 通用办公
+                                 ├─ 消息流 + 工具调用卡片 + 产物预览
+                                 └─ 审批对话框 ← extension_ui_request
+                                          ↕ IPC
+Electron 主进程 ── spawn pi --mode rpc --no-session
+                   cwd        = cases/{id}/ai/pi/{userId}/
+                   sessionDir = 同上(按案件+用户隔离)
+                   JSONL stdin/stdout,id 关联,回合结束等 agent_settled
+                                          ↓ 工具
+                   read / bash / powershell(分析模式可收窄为只读集)
+                   → qingjian/system/python/python.exe + duckdb 只读开副本
+                                          ↑
+ai-server(Java,保留)── POST /case/pi-workspace
+                          调既有 exportSnapshot 导副本 + 从 PG 导元数据
+                          + 生成 AGENTS.md / .pi/skills/ / 返回工作区路径
+```
+
+案件工作区布局(proposed):
+
+```
+cases/{caseId}/ai/pi/{userId}/
+├── AGENTS.md                 ← pi 自动加载:副本路径、只读约束、python 命令、快照时间
+├── .pi/
+│   ├── extensions/           ← 自建:审批拦截、案件工具、模式装配
+│   └── skills/               ← 按 cwd 解析,避开 .agents/skills 的 repo-root 截断
+│       ├── case-sql/SKILL.md
+│       ├── xlsx/SKILL.md     ← 从 ai-server resources/skills 迁移
+│       └── report/SKILL.md   ← 同上
+├── data/case.duckdb          ← exportSnapshot 副本
+├── data/schema.json          ← PG 侧 table_info / ai_clean_template 元数据
+└── outputs/                  ← 产物
+```
+
+**为什么不用案件根目录当 cwd**:pi 无内置权限系统(`README.md:90`),工具以启动用户的 OS 权限运行。案件根含原库、`imports/`、`materials/` 原始证据,必须把 cwd 收窄到独立子目录,再叠加自建审批 extension。
+
+**为什么用 `.pi/skills/` 而非 `.agents/skills/`**:后者从 cwd 向祖先发现并**止于 repo 根**(`docs/skills.md:61`);存储根 `./qingjian/data` 物理在仓库工作树内(`.gitignore:39` 忽略但仍在树内),会被截断到 `E:\workspace\zsjz-ai`。`.pi/skills/` 是项目级、按 cwd 解析,不受此影响。
+
+## 5. pi vs dsh 决策矩阵
+
+针对本项目的六个硬需求:
+
+| 需求 | pi | dsh | 判断 |
+|---|---|---|---|
+| 独立顶层 agent 窗口,两窗口互不影响 | 无现成 GUI;**自建 Vue 窗口** + RPC 子进程(官方指定场景) | 现成 Web UI,新 BrowserWindow 顶层加载;**不能 iframe**(拒绝 cross-site + SameSite=Strict) | dsh 省 UI 工;pi 省技术栈切换 |
+| UI 技术栈与既有一致 | **Vue 自由**(RPC 语言无关,只约定 JSONL) | 客户端插件**只能 React**(`dsh.client` + ui-slots) | **pi 胜**(既有前端是 Vue3) |
+| 选择案件空间 | cwd + `--session-dir` 直接映射;无 workspace 注册表需要维护 | `workspace.create({path})` + `session.create({workspaceId})` Remote API | pi 更简单 |
+| 两种模式切换 | **无 preset 概念**,需自建(extension + skill 集 + systemPrompt + 工具集,切换时 respawn 或改配置) | **agent-preset 是会话级原语**,同进程多组合、空白会话可 select | **dsh 胜** |
+| 数据分析(DuckDB 副本) | 无 SQL 工具;`bash`/`powershell` 调自带 python+duckdb;`createReadOnlyTools()` 可收窄 | 同样无 SQL 工具;Windows 上 `run_code` 不可用(standard preset 不含 PTC,python runtime 仅 mac/Linux),只能 `pwsh` | 平手,pi 略优(有只读工具集工厂) |
+| 通用办公(Word/Excel/PPT) | **零内置 Office**,需自建 skill;但既有 xlsx/report SKILL.md 同规范可迁移 | **自带 `skill-office`**(Word/PPT/Excel 工作流 + 文件结构检查) | **dsh 明显胜** |
+
+其他决策因素:
+
+| 因素 | pi | dsh |
+|---|---|---|
+| 许可/品牌 | 纯 MIT,**无商标附加条款** | MIT + `BRAND_GUIDELINES.zh.md` 商标约束(产品名避免全称) |
+| 核心复杂度 | agent-core **6 文件**;但复用 CLI 机制要吃下 coding-agent 265 文件 | Cordis 全插件树,定制面在无稳定性承诺的内部约定上 |
+| 上游节奏 | lockstep 约周更,v1.5.1;无 semver 承诺;durable/p2 Experimental | developer preview,明确声明 breaking change;client 要求 Host version+commit 全等 |
+| 定制可否上游化 | 新贡献者 PR 默认自动关闭 → 定制只能自维护 package/extension | 树外 bundle + `dsh plugin add` 官方支持 |
+| 审批/权限 | **无内置**,须自写 `tool_call` 拦截 extension | base 默认 `workspace-write + ask`,fs-sandbox 只围栏写 |
+| 子代理 | **故意不做**;pi-durable 有但 Experimental | 有 subagent/team |
+| embedding | **不支持**(ModelType 只有 chat/image/classifier) | 未查证 |
+
+## 6. 关键缺口与代价(诚实评估)
+
+1. **UI 全部自建是最大成本项**。pi 只给事件流 + 对话框子协议。会话列表、消息流渲染、工具卡片、审批交互、案件选择器、模式切换、产物预览都要自己写。RPC 下 `custom()`/footer/header/autocomplete/editor component 全不可用,别指望复用它的 TUI 组件。
+2. **通用办公模式要从零建 skill**。pi 零 Office 能力。缓解:既有 `resources/skills/{xlsx,report}/SKILL.md` 与 pi 同为 agentskills.io 规范,可迁移;docx/pptx 需新写。
+3. **pi 不解决 embedding**。`ModelTypeMap` 只有 chat/image/classifier(`packages/ai/src/types.ts:915`)。清洗向量索引与知识库索引所需的文本向量化,pi-ai 帮不上,Java 侧仍须自研或暂留 agentscope embedding 扩展。
+4. **pi 不解决 Java 侧 LLM 传输**。pi-ai 是纯 TS,无 JVM 绑定;pi-proxy 已删除且原本只是 CORS 转发器,不是 OpenAI 兼容服务端。`packages/agent/src/proxy.ts` 是**客户端** streamFn,服务端要自写。所以 `LlmService` 脱 AgentScope 仍须 Java 自研 HTTP 客户端(流式 SSE + 重试 + usage + 三家 provider)。**不建议**让 Java 经 Node sidecar 调 pi-ai:多一跳、且与清洗单并发闸门冲突。
+5. **无权限系统 = 敏感案件数据的裸露风险**。必须自写审批 extension + 只读工具集 + cwd 收窄三重防护。原库因 Java 持锁天然打不开,但副本与 `imports/`、`materials/` 需 explicit 保护。
+6. **功能退化需明确接受**:删掉 AgentScope 的 subagent(9 文件)与后台任务后,pi 默认不补;plan mode 也没有。
+7. **project trust 是隐藏门槛**:pi 先解析项目信任再加载项目设置与资源(`docs/how-pi-works.md:49`)。新建案件工作区首次可能不被信任 → `.pi/skills/` 与 extension 不加载。必须在 S0 验证并设计自动信任策略。
+8. **上游不可依赖**:周更 + 无稳定性承诺 + PR 默认自动关闭 → 锁精确版本,定制全部收敛进自有 pi package,升级整包回归。
+
+## 7. 迁移切片
+
+每片含:保护/解锁的业务路径 + 验证信号 + 可回退性。图源见 `pi-agent-migration.dot`。
+
+### S0 可行性验证(零改动,先做)
+- **动作**:手工导一份案件快照到**仓库外**目录;写 `AGENTS.md` + `.pi/skills/case-sql/SKILL.md`;用最小 RPC 客户端(Node 或 Python)跑 `pi --mode rpc --no-session`,问「这个库里有哪些表」。
+- **保护的业务路径**:不动任何既有代码,清洗/上传/知识库零风险。
+- **验证信号**:① 返回真实表名且与 PG `table_info` 登记一致 ② project trust 不阻断资源加载 ③ 原库确实打不开(预期失败)④ `agent_settled` 能正确判定回合结束 ⑤ 自带 python+duckdb 能被 bash/powershell 调起。
+- **可回退**:完全可回退(纯外部实验)。
+- **未通过则**:停止,回到 dsh 方案或维持现状。
+
+### S1 Electron 载体 + Vue agent 窗口骨架
+- **动作**:新 `piWindow` service(照 `smartWindow.ts` 的单例/bounds 落盘/崩溃重建,**不复用** `/workbench` 单例);主进程 spawn + JSONL 解析 + id 关联 + 生命周期绑窗口;Vue 侧消息流/工具卡片/对话框桥。
+- **保护的业务路径**:主窗口既有业务界面与窗口角色解析(`appWindow.ts`)不受影响。
+- **验证信号**:两窗口互不影响(关主窗口不杀 agent 进程 / 反之);`extension_ui_request` 能渲染成 Vue 对话框并正确回 `extension_ui_response`;渲染进程崩溃后重建;stdin 关闭优雅退出。
+- **可回退**:新增文件为主,入口未切换前可整体摘除。
+
+### S2 案件工作区端点 + 副本 + 元数据 + 技能迁移
+- **动作**:ai-server 新增 `POST /case/pi-workspace`(**新增 controller,不改既有链路**):调 `exportSnapshot` 导副本 + 从 PG 导 `table_info`/`ai_clean_template` 成 schema.json + 生成 AGENTS.md/.pi/skills + 返回路径;迁移既有 xlsx/report SKILL.md。
+- **保护的业务路径**:案件开案/退案/删案、数据上传、清洗执行层全部只读接管,不改其逻辑。
+- **验证信号**:切案后 cwd 与 sessionDir 按 caseId+userId 正确隔离;副本指纹随原库 WAL 变化刷新;导出失败显式报错不回退原库;元数据表清单与 `list_tables` 口径一致。
+- **可回退**:新端点可直接下线;副本目录可删。
+
+### S3 双模式 + 只读工具集 + 审批 extension
+- **动作**:数据分析模式(案件工具 + case-sql skill + 只读集 + 严格审批);通用办公模式(office skill + 可写工具 + 用户选目录,不绑案件)。自建 `tool_call` 拦截 extension。
+- **保护的业务路径**:原始证据数据(原库/imports/materials)不可被模型修改;办公模式不得触达案件数据。
+- **验证信号**:办公模式工具清单里无案件工具;分析模式写操作被 block 并给出原因;越界写(cwd 之外)被拦;审批超时按拒绝收尾。
+- **可回退**:模式装配是配置/extension,可退回单模式。
+
+### S4 抽出共用件到中立模块(后端,与 pi/dsh 选择无关)
+- **动作**:`llm/` 4 类 → `common/llm`;`rag/EmbeddingProvider`+`EmbeddingModelFactory`+`RagProperties`+`WaForensicsSchemaCatalog` → `common/embedding`;`AgentModelFactory`+模型实体/mapper/`/models` controller → `common/model`;`attachment/AttachmentDocIndexer` → `common/docindex`;`RagVectorMapper` 中注明仅供 aiclean 使用的方法一并迁出;前端 `src/ai/views/aiModel`+`ModelFormModal.vue`+`api/modelApi.ts` 抽到中立目录。
+- **保护的业务路径**:AI 清洗模板匹配、清洗向量索引、数据上传文件识别、知识库索引、模型管理选模型。
+- **验证信号**:**行为不变**——清洗侧只改 import 路径;录制现有 LlmService 真实请求/响应 payload,迁移后逐条回放对齐;清洗全链路回归通过。
+- **可回退**:纯移动 + import 改写,可 revert。
+
+### S5 脱 AgentScope(最高风险)
+- **动作**:Java 自研 LLM 传输(流式 SSE + 非流式、重试、usage、dashscope/openai/ollama)与 embedding 三家适配,替换 `io.agentscope.core.model.Model` / `core.embedding.*`。
+- **保护的业务路径**:AI 清洗判定链路(含单并发闸门与 180s 超时重试)、文件识别、知识库向量化。
+- **验证信号**:payload 回放**逐条等价**(不是跑通就算过);单并发与超时重试行为不变;pgvector 召回结果与迁移前一致。
+- **可回退**:保留 agentscope 依赖至验收通过后再摘;此片失败则停在 S4 状态(AgentScope 仅作为 LLM/embedding 库存在)。
+
+### S6 删除编排层 + insight + 前端聊天 UI
+- **动作**:删 `module/agent` 的 service/tools(26)/middleware/intent/followup/subagent(9)/skill(5)/state/memory/prompt/render/registry/usage/analysis/artifact/python(3)/**insight(25)** 及相关 controller/entity/mapper/dto/vo;删前端 `src/ai`(模型管理除外)与 `src/graph/insight` 整目录 + `graph/views/g6Editor/index.vue:548` 的 InsightDrawer 挂载;连带清 `CaseDataCleanupService` 的 agent 清理分支、`KnowledgeBaseService:170` 的 `detachKnowledgeBase`、`StorageLayout.insightWorkspace`、`sql/insight_agent_tables*.sql` 与 `sql/agent_{expert,tool,tool_pack,skill,prompt_python_first}.sql`、pom agentscope 依赖、`agent.*`/`subagent.*`/`analysis.*` 配置段、58 个相关测试。
+- **保留**:`common/datasource/DuckdbSnapshot` + `exportSnapshot`(S2 已在用)、StorageLayout 案件布局、模型管理全链路。
+- **保护的业务路径**:删案清理不留孤儿分支;图谱页去掉研判入口后其余功能正常;清洗/上传/知识库不受影响。
+- **验证信号**:全量编译 + 清理后测试全绿;删案后无残留表/目录引用;`/workbench` 入口经 `router/guard/index.ts:69` 重定向到新 agent 窗口,数据页 CTA 与清洗完成页无需逐个改。
+- **可回退**:此片不可逆,**必须在 S0–S5 全部验收通过后执行**。
+
+### 排序依据
+S0 先做(零风险证伪)→ S1–S3 建立新能力(可回退)→ S4–S5 后端解耦(行为等价验收)→ S6 不可逆删除放最后。S4–S6 与 pi/dsh 选择无关,可与 S1–S3 并行。
+
+## 8. 风险登记
+
+| 风险 | 影响 | 缓解 |
+|---|---|---|
+| 自建 Vue UI 工作量被低估 | S1/S3 延期 | S0 后先做 UI 工作量评估;必要时先只支持单模式 |
+| project trust 阻断资源加载 | 案件技能/extension 不生效,agent 盲查 | S0 必须验证;设计自动信任或显式信任步骤 |
+| 无审批系统导致误写证据数据 | 数据完整性事故 | cwd 收窄 + 只读工具集 + 自建拦截三重防护;S3 验证越界写被拦 |
+| Office 能力从零建 | 通用办公模式不可用 | 先迁既有 xlsx/report;docx/pptx 参照 agentskills.io 规范新写 |
+| S5 自研 LLM 传输行为漂移 | 清洗判定结果变化、批次拖死 | 录制回放逐条对齐 + 单并发/超时行为回归 |
+| pi 周更 breaking change | 升级即坏 | 锁精确版本 + 定制收敛进自有 package + 升级整包回归 |
+| 上游不接受定制 PR | 长期自维护负担 | 从设计上就不依赖上游合入,全部走 extension/package |
+
+## 9. 未验证点(需 S0 收口)
+
+- pi 在 **Windows + Electron 主进程 spawn** 下的实际行为(Git Bash 解析、powershell 工具、路径引号)
+- `--mode rpc` 的完整命令集与 `agent_settled` 语义(`docs/rpc-commands.md`、`docs/json.md` 未逐条读)
+- project trust 的判定与自动化方式
+- 模式切换能否不 respawn(RPC 是否支持运行时改工具集/skill/systemPrompt)
+- 既有 `resources/skills/{xlsx,report}/SKILL.md` 的 frontmatter 与 agentskills.io 规范的字段兼容性
+- pi 会话 JSONL 在多用户/多案件下的隔离与清理策略
+- pi 是否有 compaction(`docs/compaction.md` 存在但未读)以支撑长分析任务
+- Office 零能力这一结论本人未独立复核(子代理全树检索)
+
+## 10. 下一步
+
+先执行 **S0**(零改动、可证伪)。S0 通过后再决定 S1 的 UI 投入规模;S4–S6 后端退役轨道可独立立项并行推进。

+ 106 - 0
docs/design/pi-agent-migration.dot

@@ -0,0 +1,106 @@
+// pi agent 迁移切片与验收门
+// 场景技能: architecture-visualization:evolution-planner
+// 格式技能: architecture-visualization:graphviz
+// 生成日期: 2026-11-10
+// 回答的问题: 迁移怎么切片、每片验收什么、哪片不可逆、两条轨道如何并行
+// 证据与置信度: docs/design/pi-agent-feasibility.md §2 §7
+// 状态: 全部 target/slice 节点均为 proposed,未实施
+// 重新生成: 手工维护本文件;dot -Tsvg pi-agent-migration.dot -o pi-agent-migration.svg
+
+digraph pi_migration {
+  rankdir=TB;
+  compound=true;
+  fontname="Helvetica";
+  node [fontname="Helvetica", fontsize=11, shape=box, style="rounded,filled", fillcolor="#ffffff"];
+  edge [fontname="Helvetica", fontsize=9];
+
+  // ===== 现状(有证据,非 proposed)=====
+  subgraph cluster_current {
+    label="现状 current(本机实测证据)";
+    style="rounded,dashed"; color="#888888"; fontsize=12;
+    cur_agentscope [label="AgentScope 编排层\nmodule/agent 28 子目录\n45 文件 import io.agentscope", fillcolor="#eeeeee"];
+    cur_shared [label="共用承重件\nllm / rag / AgentModelFactory\nattachment / RagVectorMapper", fillcolor="#fff3cd"];
+    cur_consumers [label="非 agent 消费方\nAI清洗模板匹配+向量索引\n上传文件识别 / 知识库索引\n删案清理", fillcolor="#eeeeee"];
+    cur_vue [label="前端 src/ai(Vue3)\naiWorkbench / aiPlugin / aiModel\n+ src/graph/insight", fillcolor="#eeeeee"];
+    cur_snapshot [label="副本机制(保留)\nDuckdbSnapshot.export\nCaseDataSourceRegistry:244", fillcolor="#d4edda"];
+    cur_python [label="自带解释器(实测)\nPython 3.14.10 + duckdb 1.5.6", fillcolor="#d4edda"];
+
+    cur_shared -> cur_agentscope [label="同模块内", style=dashed];
+    cur_consumers -> cur_shared [label="依赖(删除会打断)", color="#cc0000"];
+  }
+
+  // ===== 轨道 A:前端 / 载体 =====
+  subgraph cluster_track_a {
+    label="轨道 A · 新能力(proposed,可回退)";
+    style="rounded"; color="#0d6efd"; fontsize=12;
+
+    s0 [label="S0 可行性验证\n零改动 · 仓库外手工实验\npi --mode rpc + AGENTS.md + .pi/skills", fillcolor="#cfe2ff"];
+    g0 [label="验收门 G0\n表名与 PG 登记一致 / trust 不阻断\n原库打不开(预期)/ agent_settled 可判定", shape=ellipse, fillcolor="#e2f0d9"];
+    decide [label="G0 通过?", shape=diamond, fillcolor="#fff3cd"];
+    fallback [label="停止:回 dsh 方案\n或维持现状", fillcolor="#f8d7da"];
+
+    s1 [label="S1 Electron 载体 + Vue agent 窗口\n新 piWindow service(不复用 /workbench 单例)\nspawn + JSONL + id 关联 + 对话框桥", fillcolor="#cfe2ff"];
+    g1 [label="验收门 G1\n两窗口互不影响 / 崩溃重建\nextension_ui_request→Vue→response 回包", shape=ellipse, fillcolor="#e2f0d9"];
+
+    s2 [label="S2 案件工作区端点\nPOST /case/pi-workspace(新增 controller)\n副本 + schema.json + 技能迁移", fillcolor="#cfe2ff"];
+    g2 [label="验收门 G2\ncaseId+userId 隔离 / 指纹刷新\n导出失败不回退原库", shape=ellipse, fillcolor="#e2f0d9"];
+
+    s3 [label="S3 双模式 + 只读工具集 + 审批 extension\n数据分析 / 通用办公", fillcolor="#cfe2ff"];
+    g3 [label="验收门 G3\n办公模式无案件工具 / 写操作被 block\n越界写被拦 / 审批超时按拒绝", shape=ellipse, fillcolor="#e2f0d9"];
+
+    s0 -> g0;
+    g0 -> decide;
+    decide -> fallback [label="否", color="#cc0000"];
+    decide -> s1 [label="是"];
+    s1 -> g1 -> s2 -> g2 -> s3 -> g3;
+  }
+
+  // ===== 轨道 B:后端退役(与 pi/dsh 选择无关)=====
+  subgraph cluster_track_b {
+    label="轨道 B · 后端退役 AgentScope(proposed,可与轨道 A 并行)";
+    style="rounded"; color="#6f42c1"; fontsize=12;
+
+    s4 [label="S4 抽出共用件到中立模块\ncommon/llm · common/embedding\ncommon/model · common/docindex\n前端模型管理页抽出", fillcolor="#e2d9f3"];
+    g4 [label="验收门 G4\n行为不变:清洗侧只改 import\n录制 payload 逐条回放对齐", shape=ellipse, fillcolor="#e2f0d9"];
+
+    s5 [label="S5 脱 AgentScope(最高风险)\nJava 自研 LLM 流式传输 + embedding 三家适配\npi 不解决此片(无 embedding / 无 JVM 绑定)", fillcolor="#e2d9f3"];
+    g5 [label="验收门 G5\npayload 逐条等价(非跑通即过)\n单并发闸门 + 180s 超时重试不变\npgvector 召回一致", shape=ellipse, fillcolor="#e2f0d9"];
+
+    s6 [label="S6 删除(不可逆)\n编排层 + insight(25) + 前端聊天 UI\n+ 表 + pom 依赖 + 配置段 + 58 测试\n连带清 CaseDataCleanup / detachKnowledgeBase", fillcolor="#f8d7da", color="#cc0000", penwidth=2];
+    g6 [label="验收门 G6\n全量编译 + 测试全绿 / 删案无残留\n/workbench 经 guard:69 重定向新窗口", shape=ellipse, fillcolor="#e2f0d9"];
+
+    s4 -> g4 -> s5 -> g5 -> s6 -> g6;
+  }
+
+  // ===== 目标态 =====
+  subgraph cluster_target {
+    label="目标态 target(proposed,未实施)";
+    style="rounded,dashed"; color="#198754"; fontsize=12;
+    tgt_window [label="agent 窗口 Vue(自建)\n独立顶层 BrowserWindow\n案件选择器 + 模式切换 + 审批对话框", fillcolor="#d1e7dd"];
+    tgt_pi [label="pi 子进程(headless)\n--mode rpc --no-session\ncwd/sessionDir = cases/{id}/ai/pi/{userId}", fillcolor="#d1e7dd"];
+    tgt_ws [label="案件工作区\nAGENTS.md + .pi/skills + .pi/extensions\ndata/case.duckdb(副本)+ schema.json + outputs", fillcolor="#d1e7dd"];
+    tgt_server [label="ai-server(保留)\n副本导出 + PG 元数据 + 模型配置\ncommon/llm + common/embedding(已脱 AgentScope)", fillcolor="#d1e7dd"];
+    tgt_biz [label="既有业务不回归\n清洗 / 上传 / 知识库 / 图谱(去研判)", fillcolor="#d1e7dd"];
+
+    tgt_window -> tgt_pi [label="IPC → JSONL stdin/stdout"];
+    tgt_pi -> tgt_ws [label="read/bash/powershell 只读副本"];
+    tgt_ws -> tgt_server [label="副本由持锁进程导出"];
+    tgt_pi -> tgt_server [label="模型配置 / 元数据"];
+  }
+
+  // ===== 跨簇依赖 =====
+  cur_snapshot -> s2 [label="复用既有 exportSnapshot", style=dashed, color="#198754"];
+  cur_python -> s0 [label="S0 实测调起", style=dashed, color="#198754"];
+  cur_shared -> s4 [label="抽出对象", style=dashed, color="#6f42c1"];
+  cur_vue -> s6 [label="删除对象(模型管理页除外)", style=dashed, color="#cc0000"];
+  cur_agentscope -> s6 [label="删除对象", style=dashed, color="#cc0000"];
+
+  g3 -> tgt_window [label="交付", style=dashed, color="#198754"];
+  g6 -> tgt_server [label="交付", style=dashed, color="#198754"];
+  g3 -> s6 [label="前置:S0–S5 全验收通过\n才允许不可逆删除", color="#cc0000", style=bold];
+  g5 -> s6 [label="前置", color="#cc0000"];
+
+  // ===== 待验证未知(不画成确定路径)=====
+  unknown [label="Unknown · 需 S0 收口\nWindows+Electron spawn 行为 / project trust 判定\n模式切换能否不 respawn / RPC 完整命令集\n既有 SKILL.md frontmatter 兼容性", shape=note, fillcolor="#f5f5f5", color="#888888"];
+  s0 -> unknown [label="暴露", style=dotted, color="#888888"];
+}

+ 196 - 0
docs/design/pi-desktop-architecture.md

@@ -0,0 +1,196 @@
+# 基于 PI-Desktop 的案件分析与通用办公智能体架构设计
+
+> 版本:v3.0 评审稿|日期:2026-11-10|状态:设计,尚未实施。
+> 配套:[详细开发文档](pi-desktop-development.md)。
+> 本版取代 v1.x/v2.x 的"从零新建 Electron + Pi 承载层"方案:改为**以 PI-Desktop 为桌面基座,只开发业务插件**。
+
+## 1. 结论
+
+采用 `E:\workspace\ai\pi\PI-Desktop`(v0.21.0)作为产品基座,在其上开发两个业务插件:
+
+- **案件分析插件**:选择现有案件 → 生成独立只读 DuckDB 快照 → 以快照工作区为项目 → Pi 用原生工具完成分析 → 图表与成果展示。
+- **通用办公插件**:独立办公项目 + 办公技能与模板 → Pi 原生工具处理办公材料。
+
+不再新建桌面应用、不自研 Agent 运行时、不重写会话/模型/工具/子代理/终端。我们只写:案件发现、快照导出与校验、业务工具、业务视图、办公技能与模板、必要的界面与品牌调整。
+
+依据:PI-Desktop 的 Agent 运行时直接依赖 `@earendil-works/pi-agent-core / pi-ai / pi-coding-agent` 1.5.0([package.json:34-36](../../../ai/pi/PI-Desktop/packages/agent-runtime/package.json#L34)),已提供会话、模型、工具、子代理、终端与插件权限网关;这正是不该重写的部分。
+
+## 2. 为什么改为基座 + 插件
+
+| 维度 | 从零方案(v2) | 本版(PI-Desktop 基座) |
+| --- | --- | --- |
+| Agent 运行时 | 自己承载 CLI/PTY,自己对齐能力 | 已有,且已打补丁支持多 Provider |
+| 会话/分支/压缩/子代理 | 依赖原版 CLI 行为,界面难对齐 | 已有原生实现与 UI |
+| 插件机制 | 自己设计业务扩展加载 | 已有 `manifest.json` + 权限网关 |
+| 业务开发量 | 桌面 + 承载 + 业务 | 仅业务插件 + 界面调整 |
+| 风险 | 承载层兼容性全自担 | 上游 Early Preview 演进风险 |
+
+代价必须承认:PI-Desktop 是 Early Preview(README 自述),插件 API 仍会演进;我们的业务需要跟随其接口升级。
+
+## 3. 已核实事实与边界
+
+| 事实 | 影响 | 证据 |
+| --- | --- | --- |
+| 进程模型冻结为 Renderer → Preload → Main → Host Core / Agent Runtime → pi | 业务必须落在插件或既有扩展点,不能绕过 | [AGENTS.md:143-155](../../../ai/pi/PI-Desktop/AGENTS.md#L143) |
+| Renderer 不得直连 SQLite,Agent 执行不得进 renderer | 插件视图只能走 `pluginBridge` | 同上 |
+| 插件入口跑独立 Node 进程;面板是沙箱、无 Node 集成 | 业务脚本放插件进程,禁止在面板里跑 | [plugin-development.md:63-67](../../../ai/pi/PI-Desktop/docs/plugin-development.md#L63) |
+| 权限网关只管 `pi.*` API,**不是 OS 沙箱** | 不能宣称任意代码被隔离 | 同上 |
+| Agent Tool 有 110 秒插件侧超时,默认在 Plan/Goal 隐藏 | 长任务必须放后台 Service,不塞工具 | [plugin-development.md:355-362](../../../ai/pi/PI-Desktop/docs/plugin-development.md#L355) |
+| Agent Tool 的文件域以调用会话的项目根为准 | 快照工作区必须是真的项目根 | [plugin-development.md:466-467](../../../ai/pi/PI-Desktop/docs/plugin-development.md#L466) |
+| 可用 `pi.project.create({path})` 程序化绑定项目 | 业务可自动创建快照项目 | [index.ts:1384-1386](../../../ai/pi/PI-Desktop/packages/plugin-sdk/src/index.ts#L1384) |
+| 内置插件随 `resources/plugins` 打包,不可卸载 | 业务可作为随包插件交付 | [host-process.ts:53-60](../../../ai/pi/PI-Desktop/apps/desktop/electron/main/host-process.ts#L53) |
+| `pi-ai` 有 75 处补丁、`pi-coding-agent` 39 处 | 升级上游需重放补丁,不能盲目更新 | `patches/` 目录 |
+| 许可 LGPL-3.0 | 分发修改版需履行 LGPL 义务 | [LICENSE](../../../ai/pi/PI-Desktop/LICENSE) |
+
+以上为代码与文档事实,未做运行验证。
+
+## 4. 组件与职责
+
+| 组成 | 职责 | 不承担 |
+| --- | --- | --- |
+| PI-Desktop 主程序 | 窗口、项目、会话、Agent 运行时、模型、终端、插件网关 | 案件业务 |
+| 案件分析插件(我们写) | 案件发现、快照作业、只读查询工具、案件视图、语义旁车 | 通用文件/Shell/子代理/会话 |
+| 通用办公插件(我们写) | 办公技能、模板、生成与回读脚本、办公视图 | 案件访问 |
+| 快照导出程序(我们写) | 只读导出与校验 DuckDB,独立于 Agent | 任意模型代码执行 |
+| Pi 原生能力 | 推理、工具、模型、会话、子代理、压缩 | 不改 |
+
+## 5. 业务与基座的接缝
+
+### 5.1 一个工作区 = 一个项目
+
+每个案件快照发布为独立目录,作为 PI-Desktop 的一个 Project:
+
+```text
+<app-data>/qj-workspaces/<workspaceId>/
+  .qj/workspace.json          # 业务描述:来源、caseId、snapshotId
+  .qj/artifacts.json          # 业务成果索引
+  snapshot/<snapshotId>/
+    case.duckdb
+    schema.json
+    semantics.json
+    snapshot.json
+  outputs/
+```
+
+- 项目根即 Pi 的 cwd,满足 Agent Tool 文件域"以调用会话项目根为准"的规则。
+- 刷新 = 新快照 + 新目录 + 新项目;旧项目与其会话、分支保持不动。
+- 业务工具不接受路径、caseId 参数,只依据调用上下文解析当前项目根的 `.qj/workspace.json`。
+- 办公项目无 `snapshot/`,只有 `inputs/` 与 `outputs/`。
+
+### 5.2 业务身份
+
+- `workspaceId`、`snapshotId` 由我们生成;PI-Desktop 的 `projectId` 由宿主生成,仅在业务描述中记录映射。
+- 会话身份、轮次身份一律用宿主提供值(`sessionId`、`turnId`),不自建影子 ID。
+- 成果关联保存 `piSessionId` + `sourceEntryId`(若宿主公开),拿不到就留空并标注不可关联。
+
+## 6. 案件快照
+
+### 6.1 两种来源
+
+| 原库状态 | 方式 | 禁止 |
+| --- | --- | --- |
+| 可被新进程只读打开 | 可信固定程序 READ_ONLY ATTACH 源库,`COPY FROM DATABASE` 到新目标 | 读写打开源库、升级或恢复源库 |
+| 被原系统持写锁 | 由持库方导出后交付文件 | 复制活库、调用旧开案流程 |
+
+固定流程(待实测):
+
+```sql
+ATTACH '<validated-source>' AS source_case (READ_ONLY);
+ATTACH '<staging-target>' AS target_snapshot;
+BEGIN TRANSACTION;
+COPY FROM DATABASE source_case TO target_snapshot;
+COMMIT;
+DETACH target_snapshot;
+DETACH source_case;
+```
+
+现有 Java 侧已有导出实现可作思路参考([DuckdbSnapshot.java:58-108](../../ai-server/src/main/java/com/zsjz/ai/common/datasource/DuckdbSnapshot.java#L58)、[CaseDataSourceRegistry.java:244-254](../../ai-server/src/main/java/com/zsjz/ai/common/datasource/CaseDataSourceRegistry.java#L244)),但**不得照搬**其主库推断、覆盖目标与"失败回退原库"。
+
+### 6.2 发布门槛
+
+1. 关闭目标句柄后由固定程序只读校验。
+2. 提取结构与外部依赖,不执行未知视图/宏。
+3. 依赖不可判定即拒绝发布。
+4. 生成 `schema.json`、校验语义旁车、计算摘要、写 `snapshot.json`。
+5. 发布目录后才调用 `pi.project.create` 绑定项目。
+
+### 6.3 不变性
+
+- 不写原 DuckDB、原 PostgreSQL 元数据、原 `case.json`、原索引。
+- 不改快照表结构、不补注释。
+- 摘要用于发现篡改,不宣称 OS 禁写。
+
+## 7. 元数据
+
+| 类型 | 来源 | 处理 |
+| --- | --- | --- |
+| 物理结构 | 快照自身 | 提取到 `schema.json` |
+| 业务语义 | 原 PG 模板表、静态结构说明 | 授权后只读复制为 `semantics.json` |
+| 分析标注 | 会话内临时口径 | 只写工作区,不回写原元数据 |
+
+- 中文字段与动态列映射不在案件库内([plat.sql:46-74](../../sql/plat.sql#L46)、[ai_clean.sql:4-67](../../sql/ai_clean.sql#L4)),因此快照不自动携带语义。
+- 缺语义(如 `c0/c1`)必须阻断相关结论,不让模型猜。
+- DuckDB 与 PG 不共享事务,分别记录时间与摘要。
+
+## 8. 两条业务独立
+
+| 项 | 案件分析 | 通用办公 |
+| --- | --- | --- |
+| 项目 | 含快照 | 仅材料 |
+| 工具 | `qj_case_*` 只读查询 + Pi 原生 | Pi 原生 + 办公技能 |
+| 视图 | 快照信息、图表、成果 | 材料、成果 |
+| 完成标准 | 数值正确、口径可复核 | 文档生成、回读、预览 |
+
+- 两插件分别声明、分别启用,互不加载对方技能。
+- 不自动委派、不自动流转成果。
+- 用户自己的 Pi 扩展、MCP、模型配置不受我们干预。
+
+## 9. 界面调整范围
+
+优先用插件能力,避免改核心:
+
+| 需求 | 手段 |
+| --- | --- |
+| 案件分析主界面 | Work Panel View(`contributes.views`,`ui.view`) |
+| 选案/快照进度弹层 | Panel(`ui.panel`,隔离窗口) |
+| 品牌名称/图标 | `apps/desktop/package.json` 的 `appId` / `productName` 与图标资源 |
+| 主题 | `contributes.themes` |
+| 输入框快捷入口 | Composer suggestion / 自定义 Command |
+| 侧栏入口 | Command + View 注册 |
+
+只有插件能力无法满足时才改 `apps/desktop/src`,且须遵循其根 `AGENTS.md`:不改协议、不改持久化语义、破坏性变更需 ADR。
+
+## 10. 安全边界
+
+- 插件权限须最小化:`agent.tool.register`、`fs.read/write`、`project.create`、`background.service` 均为高风险,必须在 manifest 中精确声明 `fs` 作用域与 `net.domains`。
+- 权限网关不是 OS 沙箱:插件进程拥有当前用户权限,代码审查与来源可信是前提。
+- 本机 Python 由 Pi 原生 bash 调用,无容器/WSL;不宣称隔离。
+- 源系统令牌只用于快照下载,不写入 Pi 环境、技能或提示词。
+- 预览禁用脚本与外链,不执行文档内宏。
+
+## 11. 验收
+
+| 层面 | 关键断言 |
+| --- | --- |
+| 原生能力 | 未因引入插件而降级:模型、会话、子代理、终端、MCP 行为与同版本原版一致 |
+| 快照 | 正常流程前后源目录、原库、元数据不变;失败不回退原库 |
+| 上下文 | 业务工具只读当前项目根描述,伪造描述/跨项目引用被拒 |
+| 数值 | DECIMAL 精度、大整数、前导零、时区口径正确 |
+| 业务独立 | 分析插件不加载办公技能,反之亦然 |
+| 成果 | 仅登记工作区内稳定文件,可预览、可追溯快照版本 |
+
+## 12. 风险
+
+1. **Early Preview**:插件 SDK 与 UI slot 可能变更,需锁定版本并跟升级。
+2. **上游补丁**:`pi-ai` 75 处、`pi-coding-agent` 39 处补丁,升级 Pi 需重放并回归。
+3. **LGPL-3.0**:修改分发需履行 LGPL;业务插件与主程序的组合方式需法务确认。
+4. **插件权限粒度**:需要精确 `manifest.fs` 才能让业务工具只碰项目根,越界规则须实测。
+5. **110 秒工具超时**:长时间分析必须走后台 Service 或分批工具调用。
+6. **快照锁冲突**:源库被持锁时只能走持库方导出,首期需确认是否支持。
+
+## 13. 参考
+
+- [PI-Desktop README](../../../ai/pi/PI-Desktop/README.zh-CN.md)
+- [PI-Desktop 插件开发指南](../../../ai/pi/PI-Desktop/docs/plugin-development.md)
+- [插件 SDK 类型](../../../ai/pi/PI-Desktop/packages/plugin-sdk/src/index.ts)
+- [DuckDB 多库与事务](https://duckdb.org/2024/01/26/multi-database-support-in-duckdb.html)

+ 324 - 0
docs/design/pi-desktop-development.md

@@ -0,0 +1,324 @@
+# 基于 PI-Desktop 的业务插件详细开发文档
+
+> 版本:v3.0 评审稿|日期:2026-11-10|状态:开发规格,尚未实施。
+> 上位约束:[架构设计文档](pi-desktop-architecture.md)。
+> 基座:`E:\workspace\ai\pi\PI-Desktop` v0.21.0(Early Preview,LGPL-3.0)。
+> 除标注"现有"外,所有插件 id、目录、工具名、接口均为拟新增,仓库中尚不存在。
+
+## 1. 目标与不做
+
+### 1.1 首条验收链路
+
+案件分析:在 PI-Desktop 中选择现有案件 → 生成独立快照 → 自动创建快照项目 → Pi 用原生工具查询与计算 → 图表与成果展示在业务视图中。
+
+办公:创建办公项目 → 放入材料 → Pi 用原生工具 + 办公技能生成文档 → 回读与预览。
+
+验收时原案件数据库、元数据、登记文件、源目录均未被新应用修改。
+
+### 1.2 不做
+
+- 不新建桌面壳、不自研 Agent 运行时、不复刻会话/模型/工具/子代理 UI。
+- 不接入旧 AgentScope 的会话、工具、SSE、技能库。
+- 不调用旧 `/case/open`,不写 `table_info` / `table_field` / `ai_clean_*`。
+- 不复制活库、不在快照失败时回退原库。
+- 不把模型代码放进 renderer 或面板沙箱执行。
+
+## 2. 基座事实(必须先读)
+
+| 编号 | 事实 | 证据 |
+| --- | --- | --- |
+| F1 | agent-runtime 依赖 `@earendil-works/pi-agent-core/pi-ai/pi-coding-agent` 1.5.0 | [package.json:34-36](../../../ai/pi/PI-Desktop/packages/agent-runtime/package.json#L34) |
+| F2 | 进程模型冻结:Renderer → Preload → Main → HostCore/AgentRuntime → pi | [AGENTS.md:143-155](../../../ai/pi/PI-Desktop/AGENTS.md#L143) |
+| F3 | Renderer 不直连 SQLite;Agent 执行不得进 renderer | 同上 |
+| F4 | 插件入口为独立 Node 进程;面板为沙箱窗口,无 Node 集成 | [plugin-development.md:63-67](../../../ai/pi/PI-Desktop/docs/plugin-development.md#L63) |
+| F5 | 权限网关只约束 `pi.*`,非 OS 沙箱 | 同上 |
+| F6 | Agent Tool 插件侧超时 110 秒,默认不在 Plan/Goal 启用 | [plugin-development.md:355-362](../../../ai/pi/PI-Desktop/docs/plugin-development.md#L355) |
+| F7 | Agent Tool 文件域按调用会话的项目根 | [plugin-development.md:466-467](../../../ai/pi/PI-Desktop/docs/plugin-development.md#L466) |
+| F8 | `pi.project.create({path})` 程序化绑定项目 | [index.ts:1384-1386](../../../ai/pi/PI-Desktop/packages/plugin-sdk/src/index.ts#L1384) |
+| F9 | 内置插件由 `resources/plugins` 打包,不可卸载但可禁用 | [host-process.ts:53-60](../../../ai/pi/PI-Desktop/apps/desktop/electron/main/host-process.ts#L53) |
+| F10 | Tool 执行上下文:`sessionId`、`turnId`、`mode`、`signal`、`log` | [index.ts:971-981](../../../ai/pi/PI-Desktop/packages/plugin-sdk/src/index.ts#L971) |
+| F11 | 权限等级:`agent.tool.register`、`project.create`、`fs.write` 为 High | [plugin-development.md:1198-1200](../../../ai/pi/PI-Desktop/docs/plugin-development.md#L1198) |
+
+F6 直接决定:**长分析不能做成单次工具调用**。
+
+## 3. 插件工程
+
+### 3.1 目录
+
+```text
+plugins/
+  qj-case/                      # 案件分析插件
+    manifest.json
+    src/main.ts                 # 插件进程入口(onLoad/onUnload)
+    src/sources.ts              # 案件发现
+    src/snapshot.ts             # 快照作业编排
+    src/tools.ts                # Agent Tool 注册
+    src/views/                  # 视图 HTML/JS
+    skills/case-analysis.md
+    bin/snapshot-worker         # 固定导出/校验程序(非 Agent)
+  qj-office/                    # 通用办公插件
+    manifest.json
+    src/main.ts
+    src/views/
+    skills/spreadsheet.md
+    skills/report.md
+    templates/
+    scripts/
+```
+
+### 3.2 manifest 要点(案件插件)
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "com.zsjz.case",
+  "name": "案件分析",
+  "version": "0.1.0",
+  "main": "dist/main.js",
+  "permissions": [
+    "agent.tool.register",
+    "agent.prompt.inject",
+    "ui.view",
+    "ui.panel",
+    "fs.read",
+    "fs.write",
+    "project.create",
+    "background.service"
+  ],
+  "contributes": {
+    "agentTools": [
+      { "name": "qj_case_snapshot_info", "description": "读取当前案件快照信息", "risk": "low", "schema": { "type": "object", "properties": {} } },
+      { "name": "qj_case_schema", "description": "读取当前快照表与字段结构", "risk": "low", "schema": { "type": "object", "properties": { "table": { "type": "string" } } } },
+      { "name": "qj_case_query", "description": "对当前案件快照执行只读查询", "risk": "medium", "schema": { "type": "object", "properties": { "sql": { "type": "string" } }, "required": ["sql"] } }
+    ],
+    "views": [{ "id": "workspace", "title": "案件分析", "entry": "views/workspace.html" }],
+    "skills": ["skills/case-analysis.md"]
+  },
+  "fs": { "read": ["."], "write": ["outputs", "work"] },
+  "engines": { "piDesktop": ">=0.21.0" }
+}
+```
+
+- `fs` 作用域必须显式声明,缺省等于无权限。
+- 工具名统一 `qj_case_` 前缀,避免与原生及用户工具冲突。
+- 办公插件独立 manifest,不复用案件权限。
+
+### 3.3 加载与生命周期
+
+- 开发期:插件页"New plugin from template"或指定目录加载。
+- 交付期:放入 `apps/desktop/resources/plugins/<id>/`,随包分发。
+- `onLoad` 注册工具与视图;`onUnload` 反注册,避免热重载残留。
+
+## 4. 案件发现
+
+1. 用户通过系统选择器指定案件根目录(`fs.requestDirectory` 或面板内选择),不接受模型给出的路径。
+2. 只读 `index/cases.tsv` 与 `cases/` 直接子目录的 `case.json`。
+3. 字段按真实结构解析:`caseId / name / ownerId / createdAt / dbPath / schemaVersion`([CaseStorageManifest.java:44-50](../../ai-server/src/main/java/com/zsjz/ai/common/storage/CaseStorageManifest.java#L44))。
+4. `caseId` 以字符串处理,避免超出 JS 安全整数。
+5. 冲突、坏行、未知版本、越界路径:报错并保留诊断,**不重建索引、不修复清单**。
+6. `ownerId` 仅作显示,不作授权依据。
+
+## 5. 快照作业
+
+### 5.1 编排
+
+```text
+选案 → snapshotJobId → 暂存导出 → 校验 → 发布目录 → pi.project.create → 打开视图
+```
+
+状态机仅描述快照作业,不是 Agent 运行状态:
+
+```text
+queued → exporting → validating → publishing → ready
+任一非终态 → cancelling → cancelled / failed
+```
+
+### 5.2 导出
+
+由 `bin/snapshot-worker` 执行固定 SQL(见架构稿 6.1),要求:
+
+1. 只读 ATTACH 源库,仅目标可写。
+2. 源别名固定,不从内存主库推断。
+3. 不升级源库、不处理源 WAL、不执行 CHECKPOINT。
+4. 失败只清理自身暂存,绝不回退到分析原库。
+5. 目标先写暂存目录,成功后再发布。
+
+### 5.3 校验
+
+- 另起进程只读打开目标,提取 catalog/schema/table/column。
+- 检查视图、宏、外部文件与网络依赖;不可判定即拒绝发布。
+- 对已审定物理表做代表性查询、DECIMAL 与跨表不变量验证。
+- 生成 `schema.json`、核对 `semantics.json`、计算摘要。
+
+### 5.4 工具超时约束
+
+F6 的 110 秒限制意味着:导出与校验**必须**作为后台 Service 执行,不能放在 Agent Tool 内。工具只做两件事:启动作业、查询作业状态。
+
+| Tool | 作用 | 时长 |
+| --- | --- | --- |
+| `qj_case_start_snapshot` | 启动导出作业,返回 jobId | < 2s |
+| `qj_case_snapshot_status` | 查询状态与诊断 | < 2s |
+
+## 6. 项目与上下文
+
+### 6.1 绑定
+
+快照发布后调用:
+
+```ts
+await pi.project.create({ path: workspaceRoot });
+```
+
+返回的 `projectId` 写入 `.qj/workspace.json`。创建项目不激活工作区,界面通过 `activateProject` 或项目列表进入。
+
+### 6.2 上下文解析
+
+每个业务工具执行时:
+
+1. 取调用上下文 `sessionId`(F10)。
+2. 通过宿主接口取该会话的项目根(`pi.session.getActive()` 或 `pi.workspace.get()`,以锁版行为为准)。
+3. 读取 `<root>/.qj/workspace.json`。
+4. 校验 `workspaceId`、`snapshotId`、快照目录存在、摘要匹配。
+5. 不匹配或缺失 → 返回 `BUSINESS_CONTEXT_INVALID`,不回退到上一个案件。
+
+**禁止**从 UI 选中项、启动参数或缓存推断案件。
+
+### 6.3 刷新
+
+- 新快照 = 新目录 + 新 `project.create`。
+- 旧项目、旧会话、旧分支不改写。
+- 界面上按 `sourceId + caseId` 分组展示多代工作区,标注快照时间。
+
+## 7. 业务工具
+
+### 7.1 清单
+
+| 工具 | 输入 | 输出 | 限制 |
+| --- | --- | --- | --- |
+| `qj_case_snapshot_info` | 无 | 案件名、快照时间、摘要、语义覆盖 | 不返回源路径 |
+| `qj_case_schema` | 可选 table | 表、字段、类型、中文名、缺失项 | 只读 |
+| `qj_case_query` | SQL + 绑定参数 | 列、行、截断标记、结果文件路径 | 只读、单语句、行数上限 |
+| `qj_case_start_snapshot` | 无 | jobId | 后台执行 |
+| `qj_case_snapshot_status` | jobId | 阶段、错误、耗时 | 只读 |
+
+### 7.2 查询实现
+
+- 固定连接 `<root>/snapshot/<snapshotId>/case.duckdb`,`read_only=True`。
+- 拒绝 DDL、DML、ATTACH、COPY TO、INSTALL、LOAD:用 DuckDB 解析器判定,不用正则。
+- 拒绝外部文件/网络表函数与不可判定的视图依赖。
+- 值用绑定参数;标识符先对照目录校验。
+- 大结果写 `outputs/*.parquet|csv`,返回预览与引用。
+- DECIMAL 保持精度,BIGINT 与账号以字符串返回。
+
+### 7.3 不做什么
+
+- 不注册通用 `read_file` / `write_file` / `run_python`——Pi 已有原生工具。
+- 不在工具里跑长任务(F6)。
+- 不拦截原生工具的文件访问(Pi 原生能力保持完整,见架构稿 10)。
+
+## 8. 办公插件
+
+| 项 | 内容 |
+| --- | --- |
+| 项目 | 无快照,仅 `inputs/`、`outputs/` |
+| 技能 | `spreadsheet.md`、`report.md` |
+| 脚本 | openpyxl / python-docx / python-pptx 的生成与回读 |
+| 调用 | Pi 原生 bash 调本机 python.exe |
+| 检查 | XLSX 回读表头/汇总;DOCX 回读标题/表格;PPTX 检查页数与文本 |
+| 禁止 | 执行 VBA、刷新外链、访问案件快照 |
+
+办公插件不声明 `project.create` 之外的案件相关权限,不引用案件工具。
+
+## 9. 视图与界面
+
+### 9.1 案件视图(`views/workspace.html`)
+
+- 通过 `window.pluginBridge` 调用插件自身方法(`onPanelInvoke`)。
+- 展示:案件名、快照时间、表清单、最近查询、图表、成果列表。
+- 图表用类型化数据渲染,不执行模型中给出的 JS formatter。
+- 不直连数据库:所有数据经插件进程转发。
+
+### 9.2 界面调整清单
+
+| 目标 | 做法 | 是否改核心 |
+| --- | --- | --- |
+| 新增"案件分析"入口 | `contributes.views` + `ui.view` | 否 |
+| 选案与进度弹窗 | `ui.panel` | 否 |
+| 应用名与图标 | `apps/desktop/package.json` 的 `productName`/`appId` + 图标 | 是(配置) |
+| 主题色 | `contributes.themes` | 否 |
+| 隐藏不需要的默认视图 | 用户侧禁用;必要时评估核心改动 | 视情况 |
+
+改核心前必须遵守 [AGENTS.md](../../../ai/pi/PI-Desktop/AGENTS.md):不改协议、不改持久化语义、破坏性变更需 ADR。
+
+## 10. 成果
+
+- 索引文件 `.qj/artifacts.json`,字段:`artifactId`、`workspaceId`、`snapshotId`、`relativePath`、`sha256`、`sizeBytes`、`mediaType`、`createdAt`、`piSessionId?`、`sourceEntryId?`。
+- 只登记项目根内稳定可读文件;拒绝符号链接、设备文件与控制文件。
+- 不从终端文本解析"已生成"。
+- 本期只在新工作区保存,不提供回写原案件或外部另存。
+
+## 11. 测试
+
+### 11.1 源不变
+
+- 正常发现/导出/查询流程前后,比对源目录清单、文件摘要、DuckDB schema 与数据。
+- 源被原系统并发写时,检查我们的写路径与事务不变量,不要求整体哈希不变。
+- 用例:空源、坏索引、越界路径、写锁、需恢复的 WAL、引擎版本不符。
+
+### 11.2 快照
+
+- 并发 DDL、持续写入下的一致导出或明确失败。
+- 中途杀进程:无半成品发布、无覆盖旧快照。
+- 视图/宏外部依赖:拒绝并可诊断。
+
+### 11.3 工具与上下文
+
+- 伪造 `workspace.json`、跨项目引用、越界路径全部拒绝。
+- `qj_case_query` 拒绝 ATTACH/COPY TO/INSTALL/LOAD 与外部表函数。
+- 110 秒边界:长任务必须走后台,工具不阻塞。
+
+### 11.4 原生能力不回退
+
+- 引入插件后,模型切换、会话恢复、子代理、终端、MCP 与未装插件时行为一致。
+- 插件禁用后无残留工具与视图。
+
+### 11.5 业务独立
+
+- 仅装案件插件时无办公技能;仅装办公插件时无案件工具与快照访问。
+- 两插件同时启用时互不注入对方技能。
+
+### 11.6 前端
+
+- 视图与面板逐屏在真实运行的应用内截图验证。
+- 快照进度、失败态、空态、长表、图表均需验证。
+
+## 12. 分期
+
+| 阶段 | 交付 | 出口 |
+| --- | --- | --- |
+| P0 | 基座探针 | 在 PI-Desktop 中加载空插件、注册一个工具、打开一个视图,确认 SDK 行为 |
+| P1 | 案件发现 + 快照作业 | 只读导出一条真实结构测试库,源不变 |
+| P2 | 项目绑定 + 上下文解析 | `project.create` 后工具能定位正确快照 |
+| P3 | 只读查询 + 分析技能 | 数值正确,结果可复核 |
+| P4 | 案件视图 | 选案、进度、表结构、图表、成果 |
+| P5 | 办公插件 | 独立完成文档生成与回读 |
+| P6 | 品牌与界面调整、打包 | 内置插件随包分发,安装包在干净 Windows 验证 |
+
+P4 与 P5 可并行,均依赖 P0。
+
+## 13. 风险与对策
+
+| 风险 | 对策 |
+| --- | --- |
+| Early Preview 接口变动 | 锁版本,跟升级,接口差异单独评估 |
+| 上游补丁重放 | 升级 Pi 前重放 `patches/` 并回归 |
+| LGPL-3.0 分发义务 | 法务确认组合方式,保留许可与修改说明 |
+| 110 秒工具超时 | 长任务走后台 Service |
+| 插件权限过宽 | manifest 精确声明 `fs` 与 `net` 作用域 |
+| 快照锁冲突 | 首期明确报错,持库方导出另评估 |
+
+## 14. 参考
+
+- [插件开发指南](../../../ai/pi/PI-Desktop/docs/plugin-development.md)
+- [插件 SDK 类型](../../../ai/pi/PI-Desktop/packages/plugin-sdk/src/index.ts)
+- [仓库策略](../../../ai/pi/PI-Desktop/AGENTS.md)