[Discussion] 插件文件权限：隔离边界与设计方向 / Plugin file permission boundaries

[Tioit-Wang]

Summary / 摘要

插件已有文件能力，但没有一套能同时回答「用户看见什么、插件实际能碰什么、离 OS 隔离还差多少」的模型。
本 issue 只对齐设计方向，不排实现；具体来源导入见 #134，会话写入契约见 #169。

---

现状 / Current state

能力	现状
插件私有数据	pi.plugin.getDataPath() → plugins/data/<pluginId>
外部目录	pi.fs.requestDirectory()：用户选目录，内存 grant，随插件进程结束
越界访问	Native consent：Deny / Allow once / Allow this session
路径范围	manifest.fs（workspace / userSelected + scope）
安全闸门	权限 ∩ containment ∩ deny-list ∩ scope（04-plugin-security.md §6）
未完成	capability sandbox：插件进程仍可 require("node:fs") / node:sqlite"（ADR 0008 D009）

pi.* 权限管的是 API，不是 进程。这是下面所有困局的根。

---

困局 / Dilemma

1. 授权 ≠ 隔离
   对恶意插件，requestAccess / Always allow 可被 raw Node 绕过。若 UI 不说明，就是在误导用户。

2. 「目录」答不好「文件型资源」
   用户真正要同意的是「读这个 SQLite 库」「读这个 PDF」，不是「读整个 ~/.zcode/cli/db」。目录 grant 过宽，单文件 grant 又撑不起解析器。

3. 持久授权与 ADR 0088 冲突
   ADR 0088 §4：consent never more durable than the session，nothing is persisted。
   Always allow 必须显式取代该条，并配套查看 / 撤销 UI。

4. 连续弹窗伤害体验
   批量操作会连环确认。需要单飞队列、同 target 合并、拒绝冷却，而不是简单多弹几次。

5. 用户心智只有两类
   「插件自己的数据」和「其他文件」。现有 workspace / userSelected 是实现细节，不应作为第三种资源展示。

---

需要讨论收敛的点 / Open questions

1. 信任分级
   bundled / 受信插件与 marketplace 第三方，能力是否相同？sandbox 前对外表述应是「用户同意 + 审计」还是别的？

2. 资源分类
   是否确认用户可见只有 pluginData / other；workspace / userSelected 降为路径解析细节。

3. 结构化只读 API
   是否引入 pi.db.*（SQLite）、pi.document.*（PDF）；还是受信插件继续用原生 Node（[Feature] 支持从 ZCode 导入本地会话 / Add ZCode session import support #134 现行方案）。

4. 授权生命周期
   once / process / persistent；persistent 是否本期做；撤销 UI 最小形态。

5. 连续审批 UX
   单飞队列、同 target 合并、拒绝冷却；错误码是否引入 USER_DENIED（与 PERMISSION_DENIED 区分）。

6. 不可绕过清单
   deny-list 与 host-reserved 必须继承现行规范，且 grant 不得绕过——是否有人反对。

---

非目标 / Non-goals

• 不实现 ZCode 或任何具体来源插件。
• 不开放 host SQLite、通用 SQL、任意 host RPC。
• capability sandbox（D009）仍是独立长期项，本 issue 不替代它。

---

关联 / Related

• [Feature] 支持从 ZCode 导入本地会话 / Add ZCode session import support #134 ZCode 导入：权限基建前，读外部库用原生 Node 只读，不被本讨论阻塞。
• [Feature] 插件会话 API：查 / 导 / 改 / 删（含批量导入） / Plugin session API #169 插件会话 API（查 / 导 / 改 / 删 + 批量导入）。

---

English summary

Plugin file access exists today (requestDirectory, consent, manifest.fs, deny-list) but cannot honestly state what a grant means while raw Node remains reachable in the plugin process. This issue collects direction only: trust tiers, two user-visible resource kinds (pluginData / other), structured read-only APIs (pi.db.* / pi.document.*) vs native Node for trusted plugins, grant lifetimes (and whether to supersede ADR 0088 §4), consent UX for consecutive prompts, and a non-bypassable deny-list. Discussion first; no implementation here. Source importers (#134) and the session write contract (#169) are tracked separately.

[muzimu217]

从「多来源只读导入」插件的实际需求补一份数据点：

• 我们的一次「扫描本机工具」要只读触达 6 个家目录位置（~/.zcode、~/.workbuddy、~/.claude、~/.codex、~/.opencode、~/.pi）。在现有目录 grant 模型下，用户要么面对 6 次目录授权，要么 manifest 声明 6 个 fs 范围再整体确认——两条路体验都不理想。
• 支持引入结构化只读 API 的方向（pi.db.* 对 SQLite 尤其有价值：ZCode 及同类 IDE 工具都是 SQLite 存储，只读 + 参数化查询能天然挡住写破坏）；短期内若能做到「多路径只读 manifest + 单次合并审批」，对扫描类插件也是显著改善。
• 认同「用户心智只有两类」。补充一个观察：只读扫描类（导入器、统计、审计）与读写类（编辑器、生成器）的信任要求差异巨大，信任分级里值得给 read-only 单列一条快速通道（低弹窗成本 + 高可解释性）。

[muzimu217]

以「目前唯一把插件跑到读外部 sqlite + 写会话库」的作者身份，交一份真实数据上的结论，供方向对齐参考。

1. 只读打开外部库这条路是通的，不必阻塞。 Electron 43 / Node 24.18.1 的 node:sqlite DatabaseSync 以 readOnly 打开真实 ~/.zcode/cli/db/db.sqlite 正常，一次扫描拿到 66 个会话；WorkBuddy / Claude Code / Codex 同源方式分别 126 / 62 / 767。零原生依赖这个诉求可以满足。

2. 真正的痛点不是「能不能读」，是授权粒度。 真实规模下一次扫描要触碰上千个会话文件。当前的越界 consent（Deny / Allow once / Allow this session）在这个量级上不可用——按文件弹窗会直接打断批量任务。建议按目录级一次性授权 + 明确生命周期（本次会话 / 永久记住该目录），而不是逐文件授权。

3. 从插件作者视角，最小权限不是「给文件」，而是「给结构化只读查询」。 我们只需要「按来源取会话列表 / 消息」，并不想也不需要拿到整库路径。结构化接口（pi.db.* 那类）长期看是最干净的解法；但短期不阻塞——先用 node:sqlite + 目录级授权也能交付，我们就是这么上线的。

另：插件私有目录 pi.plugin.getDataPath() 已经够用，测试数据和缓存落盘不需要任何外部写权限。