## 按链路定位，不一次改所有配置

```text
发现清单 → 版本和类别检查 → 加载资源 → 注册定义
→ 激活界面 → 调用接口 → 保存结果 → 正式发行
```

先确定问题发生在哪一段，再收集对应的最小日志和输入。下面的建议不会要求关闭完整性、路径或授权检查。

## 扫描后找不到组件

- manifest 是否直接放在组件根目录，是否多套了一层目录。
- JSON 是否有效，必填字段和引用文件是否存在。
- ID 是否合法且不与内置组件冲突。
- `category` 是否匹配当前扫描目录。
- 宿主是否满足 minAppVersion，是否被停用或卸载。
- 是否误拿正式版去加载普通源码目录。

目录名以点或下划线开头的项会被扫描器忽略。清单能读取，不等于入口脚本已经执行。

## 组件存在但窗口空白

先检查 scripts 的依赖顺序、main 文件和注册 ID，再看 activate 是否拿到容器、是否抛错。必要时用最小界面替换业务初始化，确认加载链成立后逐项恢复功能。

不要为了让页面显示而直接替换整个宿主 body；这会破坏窗口原有机制。

## 改了代码却还是旧行为

重新扫描不会撤销已执行的 JavaScript。先关闭对应窗口，再打开；全局定义或宿主入口变化时重启开发版。不要通过反复添加 script 标签“热修复”，容易引入双重事件。

## 文件路径或保存错误

区分文件不存在、当前窗口未授权、输入原件只读、输出目录不可写和协作连接中断。用用户选择或项目登记流程重新取得合法路径，不靠 trusted 标记绕过主进程。

保存失败时继续显示未保存；没有实际落盘，就不能把结果列表标成已完成。

## 第二次打开重复执行

检查是否在 activate 中反复绑定 document 事件、开启 timer、创建编辑器或订阅流，却没有在 deactivate 中清理。使用同一个具名函数移除监听，并核对事件接口是否真的返回取消函数。

## 任务卡住或取消无效

先判断是准备阶段超时、模型等待、本地工具启动失败，还是正常长计算。取消按钮要连接真实后台停止机制；仅修改状态文字或 runId 不能停止外部进程。

同时检查重计算是否堵住渲染线程，以及大文件是否在启动阶段被完整读入。

## 正式包失败而开发版成功

| 检查项 | 应核对 |
| --- | --- |
| 类别 | task / tool 与发行格式是否一致 |
| 版本 | 宿主最低版本、组件版本和当前登记记录 |
| 资源 | 包内相对地址是否仍有效，是否漏文件 |
| 运行环境 | Electron、原生或字节码要求是否配套 |
| 登记 | 内容摘要、签名、状态和授权范围是否正确 |
| 安装来源 | 是否实际使用最终发行包，而非源码 ZIP |

已发布同版本内容不能直接覆盖。应提升组件版本重新发行，或按受支持的撤回、恢复流程处理。

## 提交可复现问题

提供组件与宿主版本、最少输入、逐步操作、预期结果、实际阶段和脱敏日志。如果问题涉及某个文件，优先提供可公开的最小替代数据。

不要提交密码、API Key、Cookie、服务器密钥或未经许可的完整用户项目。