# 漫画源本地调试

English: [Local Source Debugging](source_debugging.en.md)

接口定义见 [漫画源开发说明](../api/comic_source.zh.md) 和 [JavaScript API](../api/js.zh.md)。本文说明脚本导入、修改、重新加载和错误定位流程。

本文的统一添加、任务重载、编辑器保存重载和异步调试器改进属于当前主分支未发布功能；v1.16.0 仍使用旧的链接/文件导入入口。首次编写可复制[最小模板](../examples/minimal_source.js)，按[示例接口约定](../api/comic_source.zh.md#1-脚本与最小示例)替换虚构服务地址和字段。

## 导入与重试

1. 打开“漫画源 → 添加来源”，选择 JS 文件或粘贴原始脚本 URL/内容，在识别后的预览中安装。文件会自动识别；粘贴输入后需点击“识别并预览”。
2. 安装失败时，打开任务详情查看并复制完整错误。JavaScript 执行错误包含脚本路径和运行时提供的行号。
3. 修改并保存原文件后点击“重试”，会重新读取可访问的文件；URL 任务会重新下载。
4. 如果 `key` 已存在，任务提供“重新加载”。确认后以新脚本替换同一 `key`，无需先卸载。成功安装的文件/URL 任务也可继续用此操作调试。

部分移动端文件选择器提供的是临时副本，外部修改不会更新副本；这种情况下请重新选择文件。粘贴的脚本没有可重新读取的原文件，应通过“编辑脚本”修改，或重新粘贴导入。清除已完成任务后，可再次选择文件导入。仓库任务的正式升级仍使用源管理的“更新”。

## 编辑已安装的源

在源菜单选择“编辑脚本”：

- 桌面端尝试启动 VS Code，打开缓存目录 `source_edit/<key>.js` 中的草稿。每次在 VS Code 保存后，返回应用点击“重新加载”。对话框保持打开，可反复修改和重载。
- VS Code 不可用时，以及移动端，使用内置编辑器。点击“保存并重新加载”才会应用修改；离开未保存的脚本时可选择继续编辑或放弃修改。
- 语法、字段解析或 `init()` 失败时显示错误，保留原来的源对象、已安装脚本和初始化前的本地数据。编辑器中的错误草稿仍可修正后重试。
- 重新加载只替换当前源，其他源的运行状态保持不变。开发时保留稳定的 `key`，它也是收藏和历史关联的标识。

草稿供当前编辑会话使用；再次打开“编辑脚本”会从已安装脚本生成草稿。需要长期保留的开发代码请存放在自己的项目目录中。

显式安装和重载会等待 `init()`，最多 15 秒。初始化应简短，避免启动无终点的异步任务。应用启动时会先注册所有源，再分别启动初始化，单个源的网络等待不会阻塞其余源加载。

## JavaScript 调试器与日志

在“设置 → 调试”中使用 JS Evaluator。普通值直接显示，Promise 会等待结果，Map/List 会格式化展示，结果和错误均可复制。运行期间不能重复提交；等待超过 30 秒会显示超时。

例如验证异步结果显示：

```javascript
Promise.resolve({ chapters: 3, ready: true })
```

检查自己已安装的源（把 `example_source` 换成实际 `key`）：

```javascript
ComicSource.sources.example_source.version
```

需要多条异步语句时使用异步函数表达式：

```javascript
(async () => {
    const source = ComicSource.sources.example_source;
    const details = await source.comic.loadInfo("your-test-comic-id");
    return details;
})()
```

“重新加载配置”按源重新读取已安装脚本并汇总错误。它不会读取 VS Code 的编辑草稿；草稿请通过编辑对话框的“重新加载”应用。“打开日志”可查看请求和脚本错误。

脚本类声明允许缩进及跨行 `extends ComicSource`；必须有继承 `ComicSource` 的类，并提供 `name`、`key`、`version`。`key` 以字母或下划线开头，后续只含字母、数字或下划线。可选的 `search`、`account` 等部分可以省略。

## 追更调度与取消边界

追更检查全局最多并发 5 个，同一源最多 2 个，同源调用启动间隔至少 500 毫秒，不再每检查 5 本就暂停整个队列。每本检查最多等待 45 秒，包含桥接层的有限瞬时错误重试；追更层不再额外重复调用。

取消、关闭进度框或开始新一轮检查会停止旧队列和桥接重试，忽略迟到结果，阻止后续收藏更新；已完成的结果保留。关联到请求作用域的 HTTP 请求也会被取消。

当前 QuickJS 的异步任务调度不会始终保留 Dart 请求作用域，因此不能保证终止扩展在后续 JavaScript `await` 之后自行发出的所有子请求，也不能强制中断同步死循环。调试超时和初始化超时同样不等于杀死脚本；扩展自行产生的远端副作用无法回滚。请为内部请求设置有限等待和重试，避免在 `init()` 中安排脱离生命周期的数据写入。