@@ -0,0 +1,76 @@
# 附 · 常见错误速查（排障表）
> 面向「正在排障的 Agent/开发者」。**症状 → 原因 → 修复**三段式，按报错文本 grep 即可定位。
> 日志第一入口：`userData/logs/main-YYYY-MM-DD.log`（
> 改完任何文件后跑 `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 ](../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.*` （ ）
| 其他插件的胶囊/按钮全消失了 | 该插件激活抛错触发 `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 ](./05-renderer-components.md )）；产物必须含 `__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） ； `plugin:check` 会 warn）
| 按钮不是胶囊形 / 圆角不对 | 手写 rounded-control 当按钮 | renderer 用组件库 `Button` （pill 体系）；圆角体系 chip6/control8/card10/window14 |
## 7. 检验器对照
`pnpm plugin:check <目录>` 输出的每条 error/warn 都带修复指引；完整规则表见 [L7 ](./08-performance.md )。速记：
- error = 装不了或必然出问题（同步 IO、console.*、React 副本、hex、超尺寸、契约非法）
- warn = 应当修（缺 minContract、疑似 React 副本、三态缺失、阻塞对话框、icon 不在白名单、产物未构建）
## 8. 还不行？
1. `pnpm plugin:check <目录>` → 0 error
2. 重载插件 → 看 `userData/logs/main-*.log` 里 `plugin activated pluginId=<id>` 之后你自己的 `api.log` 输出
3. 对照 [L5 自诊断 ](./06-self-diagnosis.md ) 的闭环流程补日志埋点，再重试
Rick Ye