排障与错误码

适用版本：StablEdge 桌面端 0.4.4

宿主返回的错误都带稳定的 code。插件逻辑请按 code 分支，不要匹配人类可读的 message。权限、schema、范围和输入类错误不可重试；不要把授权失败当作临时网络错误无限重试。

安装失败

按以下顺序检查打包或安装返回的错误码：

1. 清单 schema 和字段类型；
2. 入口文件是否存在；
3. files 是否封闭、哈希是否正确；
4. 有签名时，检查发布者密钥标识和签名；
5. 包内是否有重复条目、符号链接或路径跳转；
6. 包大小等资源限制。

安装时与包内容相关的错误码只有以下几种：文件集与 files 不符报 PLUGIN_PACKAGE_UNREADABLE；资源哈希不符报 PLUGIN_FILE_HASH_MISMATCH；清单有问题（包括 skills 超过 1 项、引用了不存在的 workspace）报 PLUGIN_MANIFEST_INVALID。

修改过 payload/ 后一定要重新打包。不要通过关闭 schema、哈希、签名、CSP 或权限校验来“解决”安装问题。

插件不在列表中

• 确认 .seplugin 确实安装成功，而不只是创建了源码；
• 查看插件的 id、版本和状态；新安装的插件默认停用，需要手动启用；
• 检查清单中的工作区或顶部栏贡献；
• 不要把插件市场的空状态误认为已安装列表。

工作区空白或崩溃

• 检查 index.html、脚本和样式都在 files 中；
• 检查是否用到了 CSP 禁止的行为：直接联网、eval、内联脚本；
• 确认在调用其他方法前等待了 ready()；
• 不要在初始化失败时直接 throw，在界面上显示错误面板。

文件拖放没有事件

• 检查工作区是否声明了 drops，且 extensions、max_files、max_bytes 三项齐全；
• 检查是否申请了 storage.blob；
• 扩展名要写成不带点的小写；任何一个文件不合规都会整批拒绝。

Agent 声称成功但界面没变化

逐项核对：Agent 是否真的读取了上下文、使用的动作是否来自 available_actions、是否真的调用了动作、宿主是否返回 applied=true、快照版本是否增长且 last_action.status 为 applied、界面是否重新渲染。

如果总是拿到 PLUGIN_WORKSPACE_SNAPSHOT_NOT_UPDATED：

• 先查动作处理函数是否在失败分支中 throw：异常不会传回，必须改为推进版本并发布 last_action 失败回执；
• 检查 publish 是否被防抖到超过了约 8 秒的生效窗口；
• 检查是否吞掉了 publish 的错误（限流和快照过大都会让版本不增长）；
• 频繁修改时提供批量动作，处理完只发布一次。

Worker 无法就绪

• stdout 是否只有 NDJSON 协议帧，没有横幅或调试打印；出现非 JSON 行时宿主返回 PLUGIN_WORKER_INVALID_RESPONSE；
• 握手是否原样回显了请求 id、plugin_id 和 worker_id，五个必填字段是否齐全；
• worker.health 是否返回 ready 或 degraded；
• stderr 中是否有依赖缺失之类的报错；
• 入口文件和平台是否正确。

Worker 频繁崩溃或被隔离

• PLUGIN_WORKER_QUARANTINED 冒号后面是最后一次退出时 stderr 的末尾，先按它修复；
• 握手被拒、健康检查非法、stdout 出现非 JSON 内容都算作一次退出；超时不算；
• 修复后“停用 → 启用”或覆盖安装一次即可清零计数，不需要等待。

调用超时后整组调用都失败

出现 PLUGIN_WORKER_UNRESPONSIVE 通常说明 Worker 主线程被卡死，与握手无关：

• 首先检查是否用了 child_process：沙箱中它会直接抛出 ERR_ACCESS_DENIED，不要再写 spawn、exec、fork 之类的调用；
• 其次检查主线程上的大文件同步读写、无界循环和同步等待；
• 不要通过加大 timeout_ms 来掩盖问题。

权限被拒

依次比较：清单中的申请、用户的授权、发行策略、当前会话。再区分界面侧 "worker": "host" 的授权和真实 Worker 的授权，两者不互通。

服务缺失或冲突

• 依赖是必需还是可选；
• API 主版本是否兼容；
• 服务是否已经单独安装并启用；
• 是否存在单例冲突。

错误码速查

Workspace Bridge 的错误码见 Workspace 与 Bridge API，Worker 自己返回的 JSON-RPC 错误码见 Worker。

安装与打包

错误码	含义
PLUGIN_PACKAGE_UNREADABLE	包无法读取：不是合法的包、包内文件集与 files 不符，或技能文件不符合规范。
PLUGIN_PACKAGE_TOO_LARGE	包超过大小限制。
PLUGIN_MANIFEST_INVALID	清单不符合 schema 或跨字段约束（权限组合、图标、词表、skills 超过 1 项、缺少引用的 workspace 等），message 说明具体项。
PLUGIN_FILE_HASH_MISMATCH	资源文件内容与 files 中的哈希不一致，通常是改了文件但没有重新打包。
PLUGIN_APP_VERSION_UNSUPPORTED	当前桌面端版本低于 minimum_app_version。
PLUGIN_PLATFORM_UNSUPPORTED	当前平台不在 platforms 中。
PLUGIN_SIGNATURE_INVALID	签名校验失败：签名后包内容被改动。重新打包签名，或生成未签名包。
PLUGIN_ICON_INVALID	图标资源不合法。
PLUGIN_I18N_INVALID	多语言声明不合法。
PLUGIN_TYPE_INVALID	plugin_type 不合法。
PLUGIN_UNSIGNED_INSTALL_DISABLED	未开启「允许安装未签名插件」。
PLUGIN_DEVELOPER_MODE_DISABLED	当前构建或设置不允许开发者来源的该项能力。
PLUGIN_PUBLISHER_CHANGED	升级时发布者发生变化。
PLUGIN_TRUSTED_WORKER_NOT_APPROVED	插件包含受信任 Worker，用户未勾选确认。
PLUGIN_PACK_FAILED	打包失败。
PLUGIN_INSTALL_FAILED	安装失败。
PLUGIN_BUILTIN_NOT_REMOVABLE	内置插件不能卸载。

Worker（宿主判定）

以下错误码由宿主判定，原样到达调用方，error.message 的格式为 CODE[:detail]。

错误码	含义
PLUGIN_WORKER_METHOD_NOT_DECLARED	调用的 operation 不在握手 methods 中，请求不会到达 Worker。
PLUGIN_WORKER_POLICY_DENIED	用户未授予所请求的执行策略（受信任或本电脑模式）。
PLUGIN_WORKER_ISOLATION_POLICY_MISMATCH	声明为 sandboxed_plugin 的 Worker 请求了本电脑模式。
PLUGIN_WORKER_EXITED	Worker 在应答前退出，冒号后是 stderr 末尾。
PLUGIN_WORKER_HANDSHAKE_INVALID	握手应答缺字段或身份不符，冒号后是字段名。
PLUGIN_WORKER_HEALTH_INVALID	健康检查的 status 不是 ready 或 degraded。
PLUGIN_WORKER_FRAME_TOO_LARGE	单个消息帧超过 32 MiB。Worker 写出的帧超限时进程被结束；Worker 读入的帧超限时只有本次调用失败；宿主应答超限时返回 JSON-RPC -32004。大数据改用文件令牌或 Blob 分块，见 Worker · 消息上限。
PLUGIN_WORKER_INVALID_RESPONSE	stdout 出现非 JSON 行，或帧是 JSON 但不是合法的应答。
PLUGIN_WORKER_IO	标准输入输出管道读写失败，进程被终止。
PLUGIN_WORKER_TIMEOUT	调用超时，但随后的健康检查有应答；进程保留。
PLUGIN_WORKER_UNRESPONSIVE	调用超时且健康检查也无应答；进程被终止。
PLUGIN_WORKER_CANCELLED	界面调用了 worker.cancel。
PLUGIN_WORKER_QUARANTINED	5 分钟内退出 3 次，已被隔离。
PLUGIN_WORKER_REMOTE_ERROR	Worker 返回了 JSON-RPC 错误，格式为 PLUGIN_WORKER_REMOTE_ERROR:<code>:<message>:<data>。
PLUGIN_WORKER_FAILED	兜底错误码，宿主拿到的不是稳定错误码；查看 message 原文。
PLUGIN_WORKER_FILE_TOKEN_EXPIRED	文件令牌已过期。
PLUGIN_WORKER_DEPENDENCY_MISSING	依赖的服务缺失。
PLUGIN_SCHEDULE_TRIGGER_NOT_DECLARED	host.schedule.* 操作的触发器未在清单中声明。
PLUGIN_SCHEDULE_INTERVAL_INVALID	间隔低于声明的最小值或超出范围。

网络与宿主服务

Worker 调用 host.net.fetch 出错时，宿主统一以 JSON-RPC 错误 -32010 返回，message 格式为 CODE:msg，其中 CODE 为下表中的错误码。

错误码	含义
PLUGIN_HOST_SERVICE_DENIED	services.invoke 或 net.fetch 被拒：插件未启用、未以 "worker": "host" 声明权限，或用户未授权。不可重试。
PLUGIN_WORKER_PERMISSION_DENIED	Worker 调用 host.net.fetch，但没有相应的 net.fetch 权限。不可重试。
PLUGIN_HOST_NET_DENIED	网址不是 http/https。
PLUGIN_HOST_NET_PRIVATE_TARGET	请求的目标或事件连接目标是局域网或本机地址，而插件没有 net.local 权限。处理：在清单中为同一个 worker 声明 net.local，并和 net.fetch 或 events.connect 一起声明，重新打包安装后让用户授权。拦截范围见局域网与本机地址。
PLUGIN_CREDENTIAL_ORIGIN_DENIED	带 credential_refs 的请求不是 https，或目标不在凭据的 allowed_origins 中。
PLUGIN_HOST_NET_INVALID_REQUEST	请求参数不合法。
PLUGIN_HOST_NET_REQUEST_BODY_ENCODING_INVALID	声明了 Base64 编码，但请求体不是合法的 Base64。
PLUGIN_HOST_NET_REQUEST_TOO_LARGE	请求体超过上限。
PLUGIN_HOST_NET_RESPONSE_TOO_LARGE	响应超过上限。
PLUGIN_HOST_NET_RESPONSE_NOT_TEXT	要求文本响应，但响应不是文本。
PLUGIN_HOST_NET_JSON_INVALID	要求 JSON 响应，但无法解析。
PLUGIN_HOST_NET_BLOB_UNAVAILABLE	要求 blob 响应，但没有活动工作区或 storage.blob 授权。
PLUGIN_HOST_NET_FAILED	请求失败（连接、超时等）。

全局服务

错误码	含义
SERVICE_NOT_FOUND	服务未安装。
SERVICE_VERSION_UNSATISFIED	服务版本不满足依赖范围。
SERVICE_SINGLETON_CONFLICT	单例服务冲突。
SERVICE_PERMISSION_DENIED	没有调用该服务的权限。
SERVICE_UNAVAILABLE	服务暂不可用。
SERVICE_DEADLINE_EXCEEDED	调用超时。
SERVICE_INVALID_REQUEST	请求不合法。

日志与隐私

插件日志和错误信息中不要包含令牌、凭据、绝对路径、完整的查询串、原始 RPC 载荷或用户正文。