8.3 KiB
8.3 KiB
附 · 常见错误速查（排障表）
面向「正在排障的 Agent/开发者」。症状 → 原因 → 修复三段式，按报错文本 grep 即可定位。 日志第一入口：
userData/logs/main-YYYY-MM-DD.log（scope=plugin 的行带 pluginId，见 L5）。 改完任何文件后跑pnpm plugin:check <插件目录>，再点插件页的「重载」。
1. 插件没出现在列表里
| 症状 | 原因 | 修复 |
|---|---|---|
| 设置 → 插件 → 对应作用域看不到插件 | 目录位置不对 | 只认三处：userData/plugins/<id>/、<工作区>/.pi/extensions/<id>/、~/.pi/agent/extensions/<id>/（工作区切换后项目级目录才同步） |
| 用户版构建下第三方区显示「装载已关闭」 | EXTERNAL_PLUGINS_ENABLED 仅开发版开启 |
用 dev 版，或启动加 ASO_EXTERNAL_PLUGINS=1 |
| 列表有但灰着 | 插件被禁用（aso-plugin-settings.json disabled 列表） |
打开「启动」开关 |
plugin:check 报 manifest 错误 |
缺字段 / version 非 semver / minContract 高于宿主契约 | 对照 docs/plugins.md manifest 表；宿主契约版本以 plugin-host.ts 的 HARNESS_CONTRACT_VERSION 为准 |
| 目录里有代码但永不装载 | 目录名/入口是 index.ts/index.js |
不要用这两个名字——那是 pi 原生扩展的自动发现名，会被 pi CLI 双重加载；用 main.mjs |
2. main.mjs 激活失败
| 症状 | 原因 | 修复 |
|---|---|---|
插件行红字「激活失败: …」，日志有 plugin activation failed |
工厂抛错 | 看 err 信息修代码；激活路径只做「注册」级工作 |
| 红字「激活失败: … 超时（10000ms）」 | 异步工厂挂死超过 10s | 网络等慢操作移到工具首次调用；必须等待时用 withTimeout 先于宿主超时 |
| 应用整体卡顿、聊天停摆 | main.mjs 里同步 IO（*Sync/execSync）阻塞主进程事件循环 |
一律换 node:fs/promises 与异步子进程；检验器会标 error |
| 日志里没有插件的任何输出 | 用了 console.*（不落盘） |
改 api.log.*（scope=plugin，带 pluginId） |
| 其他插件的胶囊/按钮全消失了 | 该插件激活抛错触发 clearPluginUi |
修复激活错误；胶囊/按钮在插件 dispose/出错时被宿主清理是预期行为 |
3. renderer 装载失败（React 组件）
| 症状 | 原因 | 修复 |
|---|---|---|
| 插件页/面板显示「插件界面装载失败」+ 重试按钮 | 读源或 import 失败（详见下方各行） | 按 title/description 里的 message 对照下几行 |
message 含 超时（8000ms） |
读源或 import 超过 8s | 瘦身 bundle；检查渲染层不 import 巨型依赖 |
Minified React error #310/Invalid hook call/hooks 全部报错 |
插件打包了自带 React 副本 | esbuild 加 --alias:react=./shims/react.js --alias:react/jsx-runtime=./shims/jsx-runtime.js（配方见 L4）；产物必须含 __ASO_PLUGIN_HOST__ |
Failed to fetch dynamically imported module / 相对导入报错 |
bundle 不自包含（相对导入无基路径，宿主用 Blob URL 装载） | --bundle 单文件产物；一切依赖打进包内（react 走别名除外） |
| 产物没被装载且无报错 | 超过 8MB 上限 | 瘦身；检查是否误打包 node_modules |
| 改了源码但界面没变 | 没重载 | 点插件行「重载」（或重开关插件）；renderer 只在列表变化/重载时重装 |
4. Agent 能力（工具/命令/事件）不生效
| 症状 | 原因 | 修复 |
|---|---|---|
| 工具/命令没出现 | 改完代码没重载 | plugins:reload 是宿主级：重扫全部目录 + 重建运行时，所有插件会短暂重激活——改了哪个插件都跑同一个「重载」 |
| 工具在列表里但 Agent 不调用 | description 不清晰 / 参数 schema 不合法 | 按 pi 工具规范写 description 与 parameters |
| 重载后工具重复/残留 | 插件在 dispose 里没清资源 | 返回 dispose 函数清理（宿主会自动清内联 UI，但 pi 注册的资源要自己管） |
5. 设置与导航
| 症状 | 原因 | 修复 |
|---|---|---|
| 插件行没有「入口」行 | 未声明 settings（items 为空 = 无配置页）或插件未启动 | api.ui.registerSettings 声明至少一项；启动插件 |
| 配置页改了值插件没收到 | 没挂 onSettingsChange |
激活时订阅；值由宿主持久化并实时回推 |
| 设置页按钮点了没反应 | 没挂 onSettingsAction |
按 key 订阅动作回调 |
| 左侧导航「Agent 能力」没有插件入口 | settingsNav 未开启 |
插件行 → 入口开关打开 |
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 §4） |
8. 样式不对
| 症状 | 原因 | 修复 |
|---|---|---|
| 界面颜色和宿主不一致 / 深浅色切不过来 | 硬编码 hex/rgb | 只用 token 类词汇（DESIGN.md §2）；plugin:check 会标 error |
| iframe 插件页没样式 | 未引宿主 token 表 | <head> 引 <link rel="stylesheet" href="peer://assets/tokens.css" />，并用同名 token 编译自己的 Tailwind |
| 暗色模式下页面发白 | 用了 prefers-color-scheme 自测 |
主题由宿主推送（useHarnessTheme），删掉自测 |
| 图标是拼图（fallback） | manifest.icon 不在 lucide 白名单 | 改成白名单内的 lucide 名（DESIGN.md §3；plugin:check 会 warn） |
| 按钮不是胶囊形 / 圆角不对 | 手写 rounded-control 当按钮 | renderer 用组件库 Button（pill 体系）；圆角体系 chip6/control8/card10/window14 |
9. 检验器对照
pnpm plugin:check <目录> 输出的每条 error/warn 都带修复指引；完整规则表见 L7。速记：
- error = 装不了或必然出问题（同步 IO、console.*、React 副本、hex、超尺寸、契约非法、依赖声明非法、用 db 未声明 schema、requirePlugin 未声明依赖）
- warn = 应当修（缺 minContract、疑似 React 副本、三态缺失、阻塞对话框、icon 不在白名单、产物未构建、声明依赖但 minContract 过低）
10. 还不行？
pnpm plugin:check <目录>→ 0 error- 重载插件 → 看
userData/logs/main-*.log里plugin activated pluginId=<id>之后你自己的api.log输出 - 对照 L5 自诊断 的闭环流程补日志埋点，再重试