# 插件维护：更新、热重载与公告

0.3.0 修复了宿主直接调用 `eac_library_list` 时的严格 JSON 返回错误，将内置 MG 模板加入 `library_read`，并提供真正的维护入口。Harness「设置 → EAC design world」直接打开维护中心；独立工作台通过顶部导航「插件维护」进入，制作设置页不再重复挂载维护面板。

## 运行版本与安装版本

- **运行版本**是当前已经载入的代码，不随磁盘文件变化而改变。
- **安装版本**来自当前插件目录的 package.json。
- 两者不一致时面板明确提示，不能把覆盖源码当成已经生效。
- 插件启动时发现端口被其他版本 EAC 占用会报 `EAC_STALE_RUNTIME`，不会悄悄连接旧接口，避免“新版界面、旧版后端”的混用。

0.1.0 没有维护接口，因此首次切换到 0.3.0 必须安装新文件并让 Harness 重新加载此插件一次。新代码不能通过尚不存在的旧接口让旧插件自我重载。无需删除原 `.eac`、项目、素材或重新创建配置。

## 插件内更新

维护中心提供「检查更新」和显式安装按钮。远程渠道使用本项目专用 `updates` 分支的 `feed/manifest.json`（该分支存放预构建运行文件，包含 dist，而不是直接使用未构建的 main 源码），不会因公告链接改变而执行其他代码。更新顺序为：下载暂存 → Ed25519 签名及逐文件 SHA-256 校验 → 备份现有可部署文件 → 替换 → 读回校验 → 宿主热重载 → 确认运行版本。更新与重载由用户点击触发，检查更新不会自动安装。

- 用户数据、`.eac/`、`node_modules/`、可选 `vendor/motion-web/` 和 `vendor/onetake/` 以及可选大媒体不被更新包拥有，也不会被回滚清理。
- 正在排队或运行的制作任务会阻止更新、重载和回滚；维护进行中会阻止提交新制作任务。
- 更新状态、备份和操作记录写入当前数据目录下的 `maintenance/`。更新失败会恢复磁盘文件；运行时恢复失败则标记需要恢复，保留错误和备份，不谎报成功。
- 维护中心显示备份回滚入口。只有确认保留备份可用后才允许回滚。
- 独立 `npm start` 没有 Harness 的模块加载器，页面会明确显示宿主重载不可用。刷新浏览器不算后端热重载。

发布时，签名清单和预构建文件一起推送到 `updates` 分支。公告从主分支读取；公告刷新与代码更新相互独立。

## 本地更新

下载并解压 `eac-design-world-v0.3.0-update.zip`，在维护中心填写其中 `manifest.json` 的完整路径。同目录 `files/` 是完整文件集，需与清单一起保留。路径所指的清单给出相对文件基址，所有文件同样执行哈希校验与备份恢复。

签名包使用插件内置的本项目公钥验证。不带可信签名的本地包默认拒绝，只有明确勾选“信任未签名本地包”后才可安装。这个确认只适用于用户选定的本地文件，不用于远程来源。

## 热重载

实现移植自 MIT 项目 [dsh-our-free-model](https://github.com/Ebony-Vinyl/dsh-our-free-model)，保留许可证。使用 Harness 的 loader、registry、fiber 生命周期清理本插件模块缓存并重新注册，不结束整个 Harness 应用，不修改其他插件配置。

- 「热重载」会读取磁盘上的新代码，保留插件配置和数据目录。
- 导入或激活新代码失败时，尝试恢复旧模块与注册，并报告恢复结果。
- 「自动监听源码变化」默认关闭；启用后只关注源码、构建资源和配置文件，忽略项目数据、渲染输出、依赖及可选库目录，避免文件写入触发无限重载。
- 客户端以真实运行实例、版本和最终操作记录判断结果，不能用页面刷新当作成功证据。宿主客户端若不能自动重新装载资源，需按提示刷新宿主界面；后端结果仍由运行版本确认。

宿主版本必须提供 loader、registry 和普通注册的插件 fiber。缺少这些条件会显示不可用或失败原因，而不是调用未验证的内部接口冒充完成。

## 公告

维护者编辑 `feed/announcements.json`，在正式发布时推送到本项目仓库。每条公告包含唯一 ID、标题、等级、发布时间、HTML 正文和可选来源链接。插件定期拉取，也可手动刷新；断网使用最后一次缓存。公告已读 ID 单独保存在维护设置中，刷新 feed 不会清空已读状态，过期公告会被过滤。

公告正文经过受限渲染，不执行脚本。公告入口不具备替换代码或更改更新信任根的能力。

## 构建与维护者签名

首次签名密钥已在当前机器的 `.eac/keys/` 中生成；私钥未写入源码或更新包。必须安全备份私钥，丢失后现有安装无法信任新的签名者。公钥位于 `src/maintenance-key.mjs`。

```powershell
npm run build
npm test
python scripts/build-release.py --working-tree --plugin-only --output release/v0.3.0
node scripts/build-update-manifest.mjs --root "已准备好的插件目录" --output "更新包目录/manifest.json" --base "./files/" --copy-to "更新包目录/files" --key ".eac/keys/release-private.pem" --notes "本次变更说明"
```

`--working-tree` 只将未被忽略的新源码加入本地包，不自动暂存、提交或推送。公开发布前仍需审查具体文件及许可。签名 manifest 必须在最终构建完成后生成；任何内容修改都需要重新构建签名。公告和更新文件只有经维护者实际发布后，其他用户才能从网络取得。

## 验证范围

测试包括真实 engine 经 `createToolRegistrations.execute` 的严格 JSON 往返、内置/可选模板读取、维护 HTTP 的来源限制、异步操作状态、任务互斥、公告缓存与已读、签名/篡改拒绝、本地安装、磁盘及运行时回滚。热重载测试单独验证缓存清除、配置保留、fibers 替换和恢复，报告真实宿主验证与模拟生命周期的边界。