版本:v3.0 评审稿|日期:2026-11-10|状态:设计,尚未实施。 配套:详细开发文档。 本版取代 v1.x/v2.x 的"从零新建 Electron + Pi 承载层"方案:改为以 PI-Desktop 为桌面基座,只开发业务插件。
采用 E:\workspace\ai\pi\PI-Desktop(v0.21.0)作为产品基座,在其上开发两个业务插件:
不再新建桌面应用、不自研 Agent 运行时、不重写会话/模型/工具/子代理/终端。我们只写:案件发现、快照导出与校验、业务工具、业务视图、办公技能与模板、必要的界面与品牌调整。
依据:PI-Desktop 的 Agent 运行时直接依赖 @earendil-works/pi-agent-core / pi-ai / pi-coding-agent 1.5.0(package.json:34-36),已提供会话、模型、工具、子代理、终端与插件权限网关;这正是不该重写的部分。
| 维度 | 从零方案(v2) | 本版(PI-Desktop 基座) |
|---|---|---|
| Agent 运行时 | 自己承载 CLI/PTY,自己对齐能力 | 已有,且已打补丁支持多 Provider |
| 会话/分支/压缩/子代理 | 依赖原版 CLI 行为,界面难对齐 | 已有原生实现与 UI |
| 插件机制 | 自己设计业务扩展加载 | 已有 manifest.json + 权限网关 |
| 业务开发量 | 桌面 + 承载 + 业务 | 仅业务插件 + 界面调整 |
| 风险 | 承载层兼容性全自担 | 上游 Early Preview 演进风险 |
代价必须承认:PI-Desktop 是 Early Preview(README 自述),插件 API 仍会演进;我们的业务需要跟随其接口升级。
| 事实 | 影响 | 证据 |
|---|---|---|
| 进程模型冻结为 Renderer → Preload → Main → Host Core / Agent Runtime → pi | 业务必须落在插件或既有扩展点,不能绕过 | AGENTS.md:143-155 |
| Renderer 不得直连 SQLite,Agent 执行不得进 renderer | 插件视图只能走 pluginBridge |
同上 |
| 插件入口跑独立 Node 进程;面板是沙箱、无 Node 集成 | 业务脚本放插件进程,禁止在面板里跑 | plugin-development.md:63-67 |
权限网关只管 pi.* API,不是 OS 沙箱 |
不能宣称任意代码被隔离 | 同上 |
| Agent Tool 有 110 秒插件侧超时,默认在 Plan/Goal 隐藏 | 长任务必须放后台 Service,不塞工具 | plugin-development.md:355-362 |
| Agent Tool 的文件域以调用会话的项目根为准 | 快照工作区必须是真的项目根 | plugin-development.md:466-467 |
可用 pi.project.create({path}) 程序化绑定项目 |
业务可自动创建快照项目 | index.ts:1384-1386 |
内置插件随 resources/plugins 打包,不可卸载 |
业务可作为随包插件交付 | host-process.ts:53-60 |
pi-ai 有 75 处补丁、pi-coding-agent 39 处 |
升级上游需重放补丁,不能盲目更新 | patches/ 目录 |
| 许可 LGPL-3.0 | 分发修改版需履行 LGPL 义务 | LICENSE |
以上为代码与文档事实,未做运行验证。
| 组成 | 职责 | 不承担 |
|---|---|---|
| PI-Desktop 主程序 | 窗口、项目、会话、Agent 运行时、模型、终端、插件网关 | 案件业务 |
| 案件分析插件(我们写) | 案件发现、快照作业、只读查询工具、案件视图、语义旁车 | 通用文件/Shell/子代理/会话 |
| 通用办公插件(我们写) | 办公技能、模板、生成与回读脚本、办公视图 | 案件访问 |
| 快照导出程序(我们写) | 只读导出与校验 DuckDB,独立于 Agent | 任意模型代码执行 |
| Pi 原生能力 | 推理、工具、模型、会话、子代理、压缩 | 不改 |
每个案件快照发布为独立目录,作为 PI-Desktop 的一个 Project:
<app-data>/qj-workspaces/<workspaceId>/
.qj/workspace.json # 业务描述:来源、caseId、snapshotId
.qj/artifacts.json # 业务成果索引
snapshot/<snapshotId>/
case.duckdb
schema.json
semantics.json
snapshot.json
outputs/
.qj/workspace.json。snapshot/,只有 inputs/ 与 outputs/。workspaceId、snapshotId 由我们生成;PI-Desktop 的 projectId 由宿主生成,仅在业务描述中记录映射。sessionId、turnId),不自建影子 ID。piSessionId + sourceEntryId(若宿主公开),拿不到就留空并标注不可关联。| 原库状态 | 方式 | 禁止 |
|---|---|---|
| 可被新进程只读打开 | 可信固定程序 READ_ONLY ATTACH 源库,COPY FROM DATABASE 到新目标 |
读写打开源库、升级或恢复源库 |
| 被原系统持写锁 | 由持库方导出后交付文件 | 复制活库、调用旧开案流程 |
固定流程(待实测):
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、CaseDataSourceRegistry.java:244-254),但不得照搬其主库推断、覆盖目标与"失败回退原库"。
schema.json、校验语义旁车、计算摘要、写 snapshot.json。pi.project.create 绑定项目。case.json、原索引。| 类型 | 来源 | 处理 |
|---|---|---|
| 物理结构 | 快照自身 | 提取到 schema.json |
| 业务语义 | 原 PG 模板表、静态结构说明 | 授权后只读复制为 semantics.json |
| 分析标注 | 会话内临时口径 | 只写工作区,不回写原元数据 |
c0/c1)必须阻断相关结论,不让模型猜。| 项 | 案件分析 | 通用办公 |
|---|---|---|
| 项目 | 含快照 | 仅材料 |
| 工具 | qj_case_* 只读查询 + Pi 原生 |
Pi 原生 + 办公技能 |
| 视图 | 快照信息、图表、成果 | 材料、成果 |
| 完成标准 | 数值正确、口径可复核 | 文档生成、回读、预览 |
优先用插件能力,避免改核心:
| 需求 | 手段 |
|---|---|
| 案件分析主界面 | 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。
agent.tool.register、fs.read/write、project.create、background.service 均为高风险,必须在 manifest 中精确声明 fs 作用域与 net.domains。| 层面 | 关键断言 |
|---|---|
| 原生能力 | 未因引入插件而降级:模型、会话、子代理、终端、MCP 行为与同版本原版一致 |
| 快照 | 正常流程前后源目录、原库、元数据不变;失败不回退原库 |
| 上下文 | 业务工具只读当前项目根描述,伪造描述/跨项目引用被拒 |
| 数值 | DECIMAL 精度、大整数、前导零、时区口径正确 |
| 业务独立 | 分析插件不加载办公技能,反之亦然 |
| 成果 | 仅登记工作区内稳定文件,可预览、可追溯快照版本 |
pi-ai 75 处、pi-coding-agent 39 处补丁,升级 Pi 需重放并回归。manifest.fs 才能让业务工具只碰项目根,越界规则须实测。