版本:v3.0 评审稿|日期:2026-11-10|状态:开发规格,尚未实施。 上位约束:架构设计文档。 基座:
E:\workspace\ai\pi\PI-Desktopv0.21.0(Early Preview,LGPL-3.0)。 除标注"现有"外,所有插件 id、目录、工具名、接口均为拟新增,仓库中尚不存在。
案件分析:在 PI-Desktop 中选择现有案件 → 生成独立快照 → 自动创建快照项目 → Pi 用原生工具查询与计算 → 图表与成果展示在业务视图中。
办公:创建办公项目 → 放入材料 → Pi 用原生工具 + 办公技能生成文档 → 回读与预览。
验收时原案件数据库、元数据、登记文件、源目录均未被新应用修改。
/case/open,不写 table_info / table_field / ai_clean_*。| 编号 | 事实 | 证据 |
|---|---|---|
| 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 直接决定:长分析不能做成单次工具调用。
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/
{
"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_ 前缀,避免与原生及用户工具冲突。apps/desktop/resources/plugins/<id>/,随包分发。onLoad 注册工具与视图;onUnload 反注册,避免热重载残留。fs.requestDirectory 或面板内选择),不接受模型给出的路径。index/cases.tsv 与 cases/ 直接子目录的 case.json。caseId / name / ownerId / createdAt / dbPath / schemaVersion(CaseStorageManifest.java:44-50)。caseId 以字符串处理,避免超出 JS 安全整数。ownerId 仅作显示,不作授权依据。选案 → snapshotJobId → 暂存导出 → 校验 → 发布目录 → pi.project.create → 打开视图
状态机仅描述快照作业,不是 Agent 运行状态:
queued → exporting → validating → publishing → ready
任一非终态 → cancelling → cancelled / failed
由 bin/snapshot-worker 执行固定 SQL(见架构稿 6.1),要求:
schema.json、核对 semantics.json、计算摘要。F6 的 110 秒限制意味着:导出与校验必须作为后台 Service 执行,不能放在 Agent Tool 内。工具只做两件事:启动作业、查询作业状态。
| Tool | 作用 | 时长 |
|---|---|---|
qj_case_start_snapshot |
启动导出作业,返回 jobId | < 2s |
qj_case_snapshot_status |
查询状态与诊断 | < 2s |
快照发布后调用:
await pi.project.create({ path: workspaceRoot });
返回的 projectId 写入 .qj/workspace.json。创建项目不激活工作区,界面通过 activateProject 或项目列表进入。
每个业务工具执行时:
sessionId(F10)。pi.session.getActive() 或 pi.workspace.get(),以锁版行为为准)。<root>/.qj/workspace.json。workspaceId、snapshotId、快照目录存在、摘要匹配。BUSINESS_CONTEXT_INVALID,不回退到上一个案件。禁止从 UI 选中项、启动参数或缓存推断案件。
project.create。sourceId + caseId 分组展示多代工作区,标注快照时间。| 工具 | 输入 | 输出 | 限制 |
|---|---|---|---|
qj_case_snapshot_info |
无 | 案件名、快照时间、摘要、语义覆盖 | 不返回源路径 |
qj_case_schema |
可选 table | 表、字段、类型、中文名、缺失项 | 只读 |
qj_case_query |
SQL + 绑定参数 | 列、行、截断标记、结果文件路径 | 只读、单语句、行数上限 |
qj_case_start_snapshot |
无 | jobId | 后台执行 |
qj_case_snapshot_status |
jobId | 阶段、错误、耗时 | 只读 |
<root>/snapshot/<snapshotId>/case.duckdb,read_only=True。outputs/*.parquet|csv,返回预览与引用。read_file / write_file / run_python——Pi 已有原生工具。| 项 | 内容 |
|---|---|
| 项目 | 无快照,仅 inputs/、outputs/ |
| 技能 | spreadsheet.md、report.md |
| 脚本 | openpyxl / python-docx / python-pptx 的生成与回读 |
| 调用 | Pi 原生 bash 调本机 python.exe |
| 检查 | XLSX 回读表头/汇总;DOCX 回读标题/表格;PPTX 检查页数与文本 |
| 禁止 | 执行 VBA、刷新外链、访问案件快照 |
办公插件不声明 project.create 之外的案件相关权限,不引用案件工具。
views/workspace.html)window.pluginBridge 调用插件自身方法(onPanelInvoke)。| 目标 | 做法 | 是否改核心 |
|---|---|---|
| 新增"案件分析"入口 | contributes.views + ui.view |
否 |
| 选案与进度弹窗 | ui.panel |
否 |
| 应用名与图标 | apps/desktop/package.json 的 productName/appId + 图标 |
是(配置) |
| 主题色 | contributes.themes |
否 |
| 隐藏不需要的默认视图 | 用户侧禁用;必要时评估核心改动 | 视情况 |
改核心前必须遵守 AGENTS.md:不改协议、不改持久化语义、破坏性变更需 ADR。
.qj/artifacts.json,字段:artifactId、workspaceId、snapshotId、relativePath、sha256、sizeBytes、mediaType、createdAt、piSessionId?、sourceEntryId?。workspace.json、跨项目引用、越界路径全部拒绝。qj_case_query 拒绝 ATTACH/COPY TO/INSTALL/LOAD 与外部表函数。| 阶段 | 交付 | 出口 |
|---|---|---|
| P0 | 基座探针 | 在 PI-Desktop 中加载空插件、注册一个工具、打开一个视图,确认 SDK 行为 |
| P1 | 案件发现 + 快照作业 | 只读导出一条真实结构测试库,源不变 |
| P2 | 项目绑定 + 上下文解析 | project.create 后工具能定位正确快照 |
| P3 | 只读查询 + 分析技能 | 数值正确,结果可复核 |
| P4 | 案件视图 | 选案、进度、表结构、图表、成果 |
| P5 | 办公插件 | 独立完成文档生成与回读 |
| P6 | 品牌与界面调整、打包 | 内置插件随包分发,安装包在干净 Windows 验证 |
P4 与 P5 可并行,均依赖 P0。
| 风险 | 对策 |
|---|---|
| Early Preview 接口变动 | 锁版本,跟升级,接口差异单独评估 |
| 上游补丁重放 | 升级 Pi 前重放 patches/ 并回归 |
| LGPL-3.0 分发义务 | 法务确认组合方式,保留许可与修改说明 |
| 110 秒工具超时 | 长任务走后台 Service |
| 插件权限过宽 | manifest 精确声明 fs 与 net 作用域 |
| 快照锁冲突 | 首期明确报错,持库方导出另评估 |