# 基于 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//`,随包分发。 - `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. 读取 `/.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 查询实现 - 固定连接 `/snapshot//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)