pi-desktop-development.md 14 KB

基于 PI-Desktop 的业务插件详细开发文档

版本:v3.0 评审稿|日期:2026-11-10|状态:开发规格,尚未实施。 上位约束:架构设计文档。 基座: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
F2 进程模型冻结:Renderer → Preload → Main → HostCore/AgentRuntime → pi AGENTS.md:143-155
F3 Renderer 不直连 SQLite;Agent 执行不得进 renderer 同上
F4 插件入口为独立 Node 进程;面板为沙箱窗口,无 Node 集成 plugin-development.md:63-67
F5 权限网关只约束 pi.*,非 OS 沙箱 同上
F6 Agent Tool 插件侧超时 110 秒,默认不在 Plan/Goal 启用 plugin-development.md:355-362
F7 Agent Tool 文件域按调用会话的项目根 plugin-development.md:466-467
F8 pi.project.create({path}) 程序化绑定项目 index.ts:1384-1386
F9 内置插件由 resources/plugins 打包,不可卸载但可禁用 host-process.ts:53-60
F10 Tool 执行上下文:sessionId、turnId、mode、signal、log index.ts:971-981
F11 权限等级:agent.tool.register、project.create、fs.write 为 High plugin-development.md:1198-1200

F6 直接决定:长分析不能做成单次工具调用。

3. 插件工程

3.1 目录

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 要点(案件插件)

{
  "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)。
  4. caseId 以字符串处理,避免超出 JS 安全整数。
  5. 冲突、坏行、未知版本、越界路径:报错并保留诊断,不重建索引、不修复清单。
  6. ownerId 仅作显示,不作授权依据。

5. 快照作业

5.1 编排

选案 → snapshotJobId → 暂存导出 → 校验 → 发布目录 → pi.project.create → 打开视图

状态机仅描述快照作业,不是 Agent 运行状态:

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

快照发布后调用:

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:不改协议、不改持久化语义、破坏性变更需 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. 参考