docs(plugins): 依赖与存储文档（L8/L9）+ 检验器入库并升级契约 0.3.0 规则

docs/plugins/09-troubleshooting.md

@@ -52,7 +52,30 @@
 | 设置页按钮点了没反应 | 没挂 `onSettingsAction` | 按 key 订阅动作回调 |
 | 左侧导航「Agent 能力」没有插件入口 | `settingsNav` 未开启 | 插件行 → 入口开关打开 |
 
-## 6. 样式不对
+## 6. 依赖与互调（契约 0.3.0）
+
+| 症状 | 原因 | 修复 |
+|---|---|---|
+| 行红字「缺少依赖插件 x（^1.0.0），请安装后重载」 | 必需依赖未安装 | 把依赖插件放入任一插件目录，点「重载」；宿主不自动安装 |
+| 行红字「依赖插件 x 已停用，请先启用」 | 必需依赖被禁用 | 到该依赖插件行打开「启动」；启用后本插件自动恢复 |
+| 行红字「依赖插件 x 需要 ^2.0，当前 v1.4.0」 | 版本不满足范围 | 升级依赖插件，或放宽自己 manifest 的范围 |
+| 行红字「循环依赖: a → b → a」 | 必需依赖成环 | 解环（改为 optionalDependencies 或重构边界） |
+| `requirePlugin` 抛「未声明对 x 的依赖」 | 未在 dependencies/optionalDependencies 声明 | 依赖声明即访问授权——manifest 里加上，并满足其 `minContract` |
+| `requirePlugin` 返回 undefined（可选依赖） | 可选依赖缺失/停用/未就绪 | 预期行为；走降级路径 |
+| 改了依赖方代码，依赖方行为没变 | 没重载 | 重载是宿主级动作，点同一个「重载」即可 |
+
+## 7. 存储（SQLite）
+
+| 症状 | 原因 | 修复 |
+|---|---|---|
+| `plugin:check` 报「使用了 api.storage.db 但未调用 declareSchema」 | 用了 SQLite 却没声明机器可读 schema | 激活期调用 `api.storage.declareSchema`，表/字段 description 写清楚（Agent 内省与设置页展示同源） |
+| `api.storage.*` 报「存储操作超时（…5000ms）」 | worker 挂死或查询过重 | 检查 SQL 是否全表扫描/锁表；重启应用可恢复 worker |
+| 报「database is locked」 | 跨进程/工具直接打开了同一个 data.db | 用宿主 API 访问，不要同时用外部 sqlite 工具长连接 |
+| KV 读回来的值不对 | value 不可 JSON 序列化（Date/Map） | 存前转 JSON 兼容类型；大二进制放文件、路径存 KV |
+| 想彻底重来 | — | 设置 → 插件 → 二级页「存储区」→ 清除数据（二次确认，整目录删除） |
+| 表结构要改 | — | `PRAGMA user_version` 自管迁移（见 [L9](./11-storage.md) §4） |
+
+## 8. 样式不对
 
 | 症状 | 原因 | 修复 |
 |---|---|---|
@@ -62,14 +85,14 @@
 | 图标是拼图（fallback） | manifest.icon 不在 lucide 白名单 | 改成白名单内的 lucide 名（DESIGN.md §3；`plugin:check` 会 warn） |
 | 按钮不是胶囊形 / 圆角不对 | 手写 rounded-control 当按钮 | renderer 用组件库 `Button`（pill 体系）；圆角体系 chip6/control8/card10/window14 |
 
-## 7. 检验器对照
+## 9. 检验器对照
 
 `pnpm plugin:check <目录>` 输出的每条 error/warn 都带修复指引；完整规则表见 [L7](./08-performance.md)。速记：
 
-- error = 装不了或必然出问题（同步 IO、console.*、React 副本、hex、超尺寸、契约非法）
-- warn = 应当修（缺 minContract、疑似 React 副本、三态缺失、阻塞对话框、icon 不在白名单、产物未构建）
+- error = 装不了或必然出问题（同步 IO、console.*、React 副本、hex、超尺寸、契约非法、依赖声明非法、用 db 未声明 schema、requirePlugin 未声明依赖）
+- warn = 应当修（缺 minContract、疑似 React 副本、三态缺失、阻塞对话框、icon 不在白名单、产物未构建、声明依赖但 minContract 过低）
 
-## 8. 还不行？
+## 10. 还不行？
 
 1. `pnpm plugin:check <目录>` → 0 error
 2. 重载插件 → 看 `userData/logs/main-*.log` 里 `plugin activated pluginId=<id>` 之后你自己的 `api.log` 输出