source-hot-patch-development

Files (1)

• SKILL.md

SKILL.md (first lines)

# 源码热补丁开发

把热补丁作为原生默认更新路径，不增加额外开启步骤或逐模块许可。安装版 WebGUI 与独立 Web Bundle 同时核对[Web 热补丁](../../docs/web-hot-patches.md)；`webgui:watch` 使用生产构建，不把开发服务器作为安装版验收。代码、Web 与资源共同变化时核对联合提交边界，不能只发布其中一部分。

## 先读与边界

- 先读 [源码热补丁](../../docs/source-hot-patches.md)、[代码架构](../../docs/code-architecture.md) 和目标功能文档，再检查工作区差异与原 owner。支持矩阵以专题文档标明的当前版本能力、源码与运行回读为事实源；目标设计、构建通过和已部署分别举证。
- 默认评估热补丁，逐项检查依赖、导出、闭包、类布局、状态拥有者和生命周期。不能仅因修改后端、新增模块或未出现在旧清单中就要求重启；运行版本尚未具备的能力先补齐或报告具体限制，不写成全部已支持。
- 自动化验收包含未预先登记的新模块、声明与相对类型依赖变更、原子保存、编译中连续修改及非法声明修复。分别核对发现、编译、兼容拒绝与真正激活；发现成功不证明任意状态可迁移。跨模块自动发布复用两阶段事务。
- 不另建 Manager，不把编辑中的共享源码或构建目录直接覆盖运行服务，不用重复带查询参数的 `import()` 充当补丁，不重跑构造函数、初始化副作用或消费者来恢复状态。
- 状态结构变化必须通过 `HotPatchRuntime.applyWithStateMigration` 提供显式迁移函数；迁移失败必须保留旧版本并恢复调用方状态，禁止静默重建实例或部分激活。
- 编译产物是可信开发者的本机可执行代码，`node:vm` 不是安全沙箱。网络 API 只接受候选 hash，不能接受并执行任意源码或路径。

## 实施顺序

使用运行版本提供的原生发现、依赖分析和发布流程；可信源码根的定位由运行时合同负责，环境变量仅作已有配置或诊断信息，不作为用户需额外开启热补丁的步骤。发现范围应覆盖可信源码根内的现有与未来新增模块及关联类型、资源，不把旧清单当成固定名单，也不扫描任意用户目录。清单用于契约和显式依赖，不是逐模块功能许可。按实际支持矩阵处理初始化与迁移；能力缺口交原 owner 补齐，不靠重跑初始化强行接入。

文件变化经有界队列生成可信、不可变候选；源码或兼容性错误保留旧服务，新输入变化后重新校验，不能无限重试相同失败候选。`indeterminate` 冻结原操作，禁止重放或换 key。资源须纳入候选契约并证明请求版本隔离和状态迁移安全后才可自动应用。

1. 固定本轮源码、类型依赖、基线产物和对应契约；保留共享工作区他人改动。普通完整构建输出不是运行目录。
2. 用 `npm run hot-patch:compile -- --source <源码文件> --output-directory <候选目录> --baseline <基线候选文件>` 编译。类型诊断、状态/签名/依赖不兼容均先修复或明确迁移，不能绕过校验换一个基线冒充成功。
3. 先跑 `npm run test:hot-patches`，再 `npm run build`，最后 `npm run test:hot-patches:manager`。后者使用临时数据与隔离控制面，不操作安装版 Host；不能代替安装版验收。
4. 行为测试覆盖原请求跨补丁完成、新请求采用新实现、原回调和实例保留、显式状态迁移及失败恢复、错误与回滚、契约单独更新、资源释放；涉及生成器时覆盖排队 `next`、`throw`、`return` 和会继续产出的 `finally`。
5. 请求租约覆盖业务实际完成，不因客户端断开就释放在途写入。生成器须消费或显式完成清理；不能把遗弃迭代器、后台 Promise、定时器或事件监听器当作已排空。跨进程迭代先核对支持矩阵，缺少相应协议时明确拒绝。
6. 同步中英文专题文档及必要索引，准确区分源码、构建、隔离运行、安装版和真实业务验收。Skill 只保留流程，接口细节链接权威文档，不复制另一套状态表。

## 发布与核对

- 只有发布已获授权且相关在途写入和不确定操作已核对时才操作安装环境；按 [长期维护](../../docs/rabi-maintenance.md) 确认唯一发布 owner。源代码开发授权不自动提供共享实例切换窗口；已有明确维护或部署授权时按原范围执行，不重复申请。
- 用 `RabiRouteHost.exe --command status --json` 动态发现完整 `managerBaseUrl`、`applicationGenerationId`、`managerInstanceId`；调用须等待进程退出并读取完整 JSON，不能把空输出和 shell 退出码当成状态。再读 `/meta` 核对身份、`health.live=true`、`requiredReady=true`、`health.state=healthy|degraded` 和目标能力。不得固定端口、扫描端口或读取退役锁寻找服务。
- 使用 Host 的 `source-patch` 命令转发本地请求文件，不提取真实 Host token。源码实现存在不代表安装版已有该命令；先核对运行版本能力。
- 一次发布使用唯一稳定 `operationId` 与精确基线身份；查询原操作后判断 `state`、`commitState`。传输成功或 CLI `ok` 不等于提交成功。
- `pending`、`indeterminate`、断连或进程更换时冻结原载荷，不盲目重放、换键或直接改回执。正式 `source-patch-reconcile` 仅凭已有运行身份与持久证明核对；没有证明保持未知。
- 回滚不撤销已提交数据、邮件或消息；涉及状态迁移时同时验证反向迁移及失败恢复。回读原操作、契约、实际响应版本和代码 hash，验证原请求按旧租约完成、新请求采用新版，并核对 Manager 身份及相关 PID 未变、目标行为已生效，才报告热补丁运行验收通过。
- 仅在当前运行版本存在具体不可迁移的状态、依赖或进程生命周期边界时，说明影响范围、证据与回退方案，由唯一 owner 经 Host 受控切换。切换后重新发现身份并验证新版本；首次安装缺失的运行能力也按此处理，不能作为以后每次后端修改必须重启的理由。

## 跨模块变更

新增模块通过通用发现与注册流程接入，不手改热补丁核心的业务名称名单；需要显式契约的模块使用运行版本支持的声明方式。使用 `dependencies` 声明 JSON 初始状态与参数时，后续改变初值必须拒绝或通过模块拥有者的显式迁移完成，不能重置运行对象。插件消费统一的 `host.manager.source-patches@1` 服务，路由与权限仍由插件持有。新增模块验收覆盖无预先登记的新文件、运行后首次创建声明、独立坏模块、代码和资源更新、现有 Worker/PID 不变、注册中断冻结、正常重启恢复与回滚；除状态列表出现新 ID，还须证明目标调用确实使用新实现。

多个同进程模块必须通过 `HotPatchBundle` 先全部 `prepare`/`validate`，再提交；禁止直接循环调用各模块的公开发布入口。独立 Worker 不得伪装成同一原子事务，必须由上层明确 Worker 组、状态 owner、失败回滚和持久回执边界。

独立 Worker 发布必须使用 `HotPatchProcessBundle` 的两阶段协议；发生进程重建、通信超时或回滚失败时保持操作不确定，不自动重放候选。

同一 Worker 同时只能保留一个准备令牌；新候选必须先丢弃或提交旧令牌。

跨模块业务入口必须以 `HotPatchBundle.run(...)` 包住完整异步调用；只用 Bundle 发布、不用 Bundle 请求租约时，仍可能跨模块混用版本。

## 资源快照接入

资源监听负责捕获资源并把资源快照放进候选包。模块在源码中声明 `declare const __rabiResources`，通过运行时提供的 `read(path)` 或 `text(path)` 读取；读取自动使用当前请求的代码 revision。不能直接持有可变全局资源对象。资源结构变化必须提供显式迁移；无法证明旧请求与新资源隔离时，拒绝补丁而继续使用旧版本。

From vb2250158/RabiRoute, MIT.

More from vb2250158/RabiRoute