6.1 KiB
6.1 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. 样式不对
| 症状 | 原因 | 修复 |
|---|---|---|
| 界面颜色和宿主不一致 / 深浅色切不过来 | 硬编码 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 |
7. 检验器对照
pnpm plugin:check <目录> 输出的每条 error/warn 都带修复指引；完整规则表见 L7。速记：
- error = 装不了或必然出问题（同步 IO、console.*、React 副本、hex、超尺寸、契约非法）
- warn = 应当修（缺 minContract、疑似 React 副本、三态缺失、阻塞对话框、icon 不在白名单、产物未构建）
8. 还不行？
pnpm plugin:check <目录>→ 0 error- 重载插件 → 看
userData/logs/main-*.log里plugin activated pluginId=<id>之后你自己的api.log输出 - 对照 L5 自诊断 的闭环流程补日志埋点，再重试