pi-desktop-architecture.md 11 KB

基于 PI-Desktop 的案件分析与通用办公智能体架构设计

版本:v3.0 评审稿|日期:2026-11-10|状态:设计,尚未实施。 配套:详细开发文档。 本版取代 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),已提供会话、模型、工具、子代理、终端与插件权限网关;这正是不该重写的部分。

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
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

以上为代码与文档事实,未做运行验证。

4. 组件与职责

组成 职责 不承担
PI-Desktop 主程序 窗口、项目、会话、Agent 运行时、模型、终端、插件网关 案件业务
案件分析插件(我们写) 案件发现、快照作业、只读查询工具、案件视图、语义旁车 通用文件/Shell/子代理/会话
通用办公插件(我们写) 办公技能、模板、生成与回读脚本、办公视图 案件访问
快照导出程序(我们写) 只读导出与校验 DuckDB,独立于 Agent 任意模型代码执行
Pi 原生能力 推理、工具、模型、会话、子代理、压缩 不改

5. 业务与基座的接缝

5.1 一个工作区 = 一个项目

每个案件快照发布为独立目录,作为 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/
  • 项目根即 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 到新目标 读写打开源库、升级或恢复源库
被原系统持写锁 由持库方导出后交付文件 复制活库、调用旧开案流程

固定流程(待实测):

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),但不得照搬其主库推断、覆盖目标与"失败回退原库"。

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、ai_clean.sql:4-67),因此快照不自动携带语义。
  • 缺语义(如 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. 参考