RxJS 7 到 RxJS Next 迁移收尾审查清单Migration Closeout Checklist完整指南【免费下载链接】rxjsA reactive programming library for JavaScript项目地址: https://gitcode.com/gh_mirrors/rx/rxjs迁移从“代码改完、测试变绿”到“可以宣告完成”中间隔着一次系统性的收尾审查。本文以 RxJS 仓库中.agents/skills/rxjs-next-migration技能套件的收尾清单review-checklist.md为核心骨架结合 SKILL.md 定义的八阶段工作流、rxjs/migrate包源码与 migration-report.md 报告模板逐条讲解迁移收尾时必须验证的五个维度权限与来源Authority and provenance、基线与覆盖Baseline and coverage、目标契约Target contract、机械批次Mechanical batches、验证与交接Verification and handoff。读完本文你将掌握一套可执行的收尾审查协议——知道在什么条件下迁移才算真正完成什么情况下必须挂起blocker以及如何产出既通过模式校验、又通过就绪评估的迁移契约。适用前提本清单面向使用 Agent 主导工作流、以rxjs/migrate确定性引擎执行有界改写bounded rewrite的 RxJS 7 → RxJS Next 迁移项目。清单中引用的命令、版本与 schema 均以当前仓库实际安装的包为准。收尾审查在迁移流程中的位置在审查清单之前先明确它属于整个工作流的哪一环。技能套件将迁移划分为八个阶段且要求按顺序推进、随时可回退重入Stage 1建立权限与范围authority and scopeStage 2评估用法、生命周期风险与覆盖assessmentStage 3建立绿色 RxJS 7 基线green baselineStage 4分类并批准目标契约target contractStage 5规划并试运行有界引擎变更dry-runStage 6应用一个小迁移批次write batchStage 7构建、测试、诊断与修复verify repairStage 8收尾与交接close out and hand off收尾清单正是Stage 8 的强制入口——SKILL.md 明确要求更新契约清单与报告后必须逐项审查 review-checklist.md并如实报告“行为与生命周期契约改了什么、源码与测试改了什么、跑过哪些门禁及结果、修复的迁移缺陷与遗留的产品缺口、已批准的偏差与环境限制、剩余阻塞项及其负责人与验收状态”。只有在就绪评估返回ready或开发者明确选择的ready-with-accepted-blockers时才允许宣告完成否则只能作为未完成迁移移交并给出下一步具体决策或动作。核心立场贯穿始终这是一项经过评审的项目工作不是一次 codemod 运行。一个被转换的文件、一份干净的 diff、一个通过的测试都不足以证明迁移完成。一、权限与来源Authority and Provenance这一小节回答“我们凭什么改、改的是什么版本、工具链是否自洽”。清单要求四个可核验事实1.1 仓库指令、范围与策略在动手前就已记录仓库级指令repository instructions、允许写入的范围、包管理器package manager与网络策略network policy必须在任何大规模变更前记录在案既有工作existing work必须受保护每个被修改的文件都必须落在授权的迁移边界migration boundary之内变更涉及读取、写入、依赖与命令范围时需在动手前明确声明。对应到流程SKILL.md 的 Stage 1 要求定位仓库指令、包与 workspace 元数据、lockfile、CI 配置、RxJS 版本、构建/测试命令与当前工作树状态当目标仓库或允许范围不清晰、既有改动与迁移重叠、或需要破坏性/联网/外部/更广权限的动作时必须暂停征求开发者意见。1.2 版本与指纹完全可复现清单要求以下身份信息精确且可复现源仓库source repository与修订版本revisionRxJS 版本来源版本 RxJS 7 与目标版本 RxJS Next引擎版本engine version与注册表版本registry version规范 Skill 摘要canonical Skill digest。报告模板在 migration-report.md 中为“工具与依赖身份”专门设计了一张表格逐项填写Source RxJS、Target RxJS Next、rxjs/migrateengine、Capability registry、Canonical Skill、Contract schema 的版本或摘要及证据位置。这些字段在 Stage 8 收尾时不允许留空。1.3 已安装 Skill 与已安装包必须一致“已安装的 Skill 内容必须与已安装的rxjs/migrate包匹配”。如果发现不匹配流程要求停止并先同步之后才允许信任这些指令。这一条防止用“记忆中的能力表”代替“安装版注册表”进行判断——后文“机械批次”一节还会反复强调能力判定必须来自安装的版本化注册表而不是从 Skill 或记忆中重建。二、基线与覆盖Baseline and Coverage没有基线就没有迁移。这一小节确保迁移开始前的 RxJS 7 是绿的任何失败都被显式记录且每条生命周期敏感路径都有明确的覆盖处置。2.1 未变更源码上的门禁全部通过清单要求约定的构建、类型、lint、测试与行为门禁build, type, lint, test, behavior gates必须在未修改的 RxJS 7 源码上运行。对应 SKILL.md 的 Stage 3记录精确命令、环境事实、退出码与简明结果起始门禁失败时暂停由开发者决定“先修复”“缩小范围”还是“记录为已接受的既有失败”严禁静默改判为迁移回归或忽略。2.2 每个基线失败都有明确归属每个基线失败要么被修复要么被显式记录为“既有失败”并获得开发者接受developer acceptance。不允许“本地能过”这种没有命令与环境支撑的口头结论——verification-and-closeout.md 规定未记录命令和环境的 “Passed locally” 不构成验证记录。2.3 生命周期敏感路径的覆盖处置每条生命周期敏感路径必须关联以下四者之一既有测试覆盖existing coverage——有命名测试证明相关行为特征化测试characterization——迁移前新增的聚焦 RxJS 7 测试显式不支持explicit unsupported status——没有可接受的 Next 表面能保留该声明保留证据并记录为产品缺口开发者接受的未覆盖风险accepted uncovered risk——记录批准人、时间、理由与影响。assessment-and-contract.md 给出了覆盖处置的完整定义并建议对重复订阅、副作用、共享、迟到订阅者、取消、teardown、时序、错误或公共 API 行为在现有测试无法证明时优先补充特征化测试。缺覆盖不等于行为安全——“Missing coverage is not evidence that behavior is safe”。2.4 特征化测试必须在依赖迁移前于 RxJS 7 上通过“特征化测试必须在依赖/源码迁移之前于 RxJS 7 上通过。”特征化测试的要点见 assessment-and-contract.md 的 Characterization protocol 一节新增能证明外部可观测声明的最窄测试优先断言值、完成/错误、生产者启动次数、并发与迟到观察、取消归属、abort 原因、teardown 顺序、虚拟或宿主时序与可见副作用避免锁定无关的 RxJS 7 内部实现。迁移依赖后才补的特征化测试不构成 RxJS 7 基线除非能针对固定源码环境单独演示。三、目标契约Target Contract目标契约把“把代码改成什么”落成可审查、可批准的决策记录。这是整份清单中最强调“意图必须显式”的部分。3.1 每个单元必须有完整档案清单要求每个迁移单元migration unit都具备稳定的源码位置stable source locations行为声明behavioral claim一个目标生命周期one target lifecycle一个证据分类evidence classification支撑证据supporting evidence。对应 SKILL.md 的工作记录要求为每个单元保留源码位置并记录其当前 RxJS 7 行为声明、开发者选择的目标生命周期、证据分类与支撑测试、批准状态/诊断/任何有意偏差、验证结果或具名阻塞项。报告模板的 “Target contract units” 表则要求逐行填写Unit ID、Source locations、RxJS 7 claim、Target lifecycle、Evidence classification、Approval、Evidence。3.2 没有单元可停留在未决状态“没有必需单元保持未解决unresolved或待批准pending approval。”引擎可以识别风险但不能替开发者选择生命周期意图——unresolved是停止状态。当平台共享行为platform-shared与每次直接订阅各起生产者producer-per-direct-subscription两种解释都成立或 Subject 语义、取消、调度器顺序、错误行为、互操作或公共行为变化未被证明时必须暂停征求开发者。3.3 生命周期选择必须基于意图而非语法推断“平台共享与每次直接订阅各起生产者的行为是有意选择的而非从语法推断的。”SKILL.md 将其列为不可谈判规则绝不根据语法、文件名、运算符名称或当前通过的输出来推断平台共享 vs. 每次订阅独立生产者的行为。可接受的生命周期取值以安装版契约清单 schema 为准包括活跃平台生产者共享并在存在观察者时引用计数、通过显式 Next API 按直接订阅创建生产者工作、有意的热 Subject 行为、无生产者生命周期、所需行为不支持、意图仍未解决。同时禁止用笼统的 “hot/cold” 标签描述平台 Observable——正确的行为描述是首个观察者启动活跃生产者并发观察者加入最后离开的观察者触发 teardown后续观察者可以启动新的一轮。3.4 需重点审查的行为维度清单点名要求逐项审查如适用Subjects、重复订阅、取消cancellation、teardown、时序timing、错误errors与输入转换input conversion。这些维度与 verification-and-closeout.md 中生命周期敏感代码的验证清单一一对应生产者激活次数与重启、并发与迟到观察、单独与最终取消、abort 原因与上游关闭、Subject 当前值/重放/终态行为、teardown 顺序、时间与调度顺序、错误投递与迟到/未处理错误行为、输入转换接受或显式拒绝。3.5 有意偏差必须完整记录每个有意偏差intentional divergence必须记录旧声明与新声明、用户影响user impact、证据、批准人approver、时间戳与理由rationale。且偏差的批准有先后顺序——先做结构校验schema validation再跑就绪评估readiness assessment两者是独立检查不能互相替代清单“验证与交接”一节再次强调。含未决意图或待批准单元的批次不得继续推进。四、机械批次Mechanical Batches这一小节约束引擎改写过程本身能力判定、dry-run、写入与幂等性。4.1 能力判定来自安装版注册表“能力决策来自已安装的版本化注册表installed versioned registry不使用复制的运算符清单或仅名称匹配。”engine-and-batches.md 要求从项目安装的包读取引擎数据公开 API 导出默认能力注册表、注册表与清单 schema、迁移函数、契约就绪评估、引擎/schema 版本而不是从提示词、Skill 或 harness 适配器里复制清单。选择转换前必须核对注册表 schema/版本与引擎版本匹配安装包、源导入绑定确为引擎识别的绑定且未被遮蔽或复用、调用形态/元数/调度器与结果选择器形态/管道上下文满足全部声明的前置条件、fixture 证据覆盖目标映射与证据类别、迁移单元已有批准的生命周期契约。名称相似、TypeScript 签名兼容或转换后测试变绿都不足以替代上述检查。仓库中的公开 API 在 packages/migrate/src/index.ts 可直接印证它导出defaultCapabilityRegistry、defaultTestSchedulerCapabilities、capabilityMappingSchema、capabilityRegistrySchema、migrationContractManifestSchema、assessMigrationContractReadiness、parseCapabilityRegistry、parseMigrationContractManifest、migrateTestSchedulerSemantics、migrateTestSource以及capabilityRegistryVersion、migrationContractSchemaVersion、migrationEngineVersion等版本常量。本地检查可以用类似 engine-and-batches.md 给出的形态遍历注册表并校验清单import { assessMigrationContractReadiness, defaultCapabilityRegistry, migrationContractManifestSchema } from rxjs/migrate; for (const capability of defaultCapabilityRegistry.capabilities) { // Review id, legacy/source name, target Symbol, adapter, arity, // preconditions, status, and fixture evidence for this exact package. } const parsed migrationContractManifestSchema.safeParse(manifest); if (parsed.success) { const readiness assessMigrationContractReadiness(parsed.data, { expectedSkillDigest, }); }expectedSkillDigest从已安装适配器的完整性检查或 Node-only 的rxjs/migrate/skillAPI 获取精确签名以安装的 TypeScript 声明为准。4.2 每个引擎操作先 dry-run“每个引擎操作先以精确来源信息 dry-run必要时使用显式的生命周期模式。”CLI 的 dry-run 形态来自 engine-and-batches.mdrxjs-migrate \ --source-root authorized-root \ --source-repo source-repository \ --source-sha exact-revision \ --mode approved-cold-or-platform-mode \ --framework preserve \ selected-files要点选中源码不需要生命周期选择时省略--mode绝不让目录名或包装器隐式选择它框架适配器只在开发者单独批准框架变更时使用。不带--write时CLI 返回版本化 JSON 报告且不执行任何写入需记录其引擎版本、注册表版本、操作、文件结果、有序诊断与退出状态——当前 CLI 契约区分完成、结构化拒绝、无效参数与运行失败四种结果。4.3 dry-run 范围、诊断与变更路径必须在写入前审查“写入前审查 dry-run 范围、诊断与变更路径。”所有诊断都要审阅包括源码跨度source span、严重性severity、处置disposition、拒绝范围refusal scope、分类classification、下一步动作next action与能力 IDcapability ID。被拒绝的批次必须保持源与目标均不变。4.4 被拒绝或不支持的源码必须保持可见“被拒绝或不支持的源码保持可见不得通过部分转换偷运smuggled through。”engine-and-batches.md 的拒绝与人工修复一节给出四条出路收窄批次到可独立安全的单元补特征化测试、获得开发者决策并在引擎声称输出之外做受审语义编辑报告 RxJS Next 产品缺口保留源码并接受具名阻塞项。禁止通过绕开诊断把被拒语法伪装成机械输出。人工工作同样受基线、生命周期、审查与验证门禁约束且不得被描述为 fixture 证明的引擎输出。4.5 写入受控且不覆盖本地内容写入阶段的命令形态同样来自 engine-and-batches.mdrxjs-migrate \ --source-root authorized-root \ --source-repo source-repository \ --source-sha exact-revision \ --mode approved-cold-or-platform-mode \ --framework preserve \ --write --out-dir authorized-destination \ selected-files引擎在写入前规划整个批次并拒绝词法、规范或符号链接路径逃逸lexical, canonical, or symlink path escape不得用手工批量写入绕过包含containment与不覆盖no-overwrite行为。若受审目标就是当前源码树必须显式声明该范围与覆盖决策并保持可恢复性。写入报告与 dry-run 报告在契约要求处逐字节比对随后不带写入地重跑同一转换第二次结果必须不变且诊断稳定——任何输出或诊断漂移都视为引擎缺陷停止批次并保留复现。4.6 输出必须保留项目自有代码与测试“输出保留项目自有源码、直接测试、断言与所选框架。”对应 SKILL.md Stage 6 的要求通过项目常规工具格式化确保项目自有源码与直接测试声明保留不在结果中遗留动态生成器、隐藏用例注册表或兼容断言层立即检查解析、最窄类型边界与引擎幂等性不满足则恢复该批次到受审起点并上报引擎缺陷。测试迁移的细节规则见 test-migration.md默认保留外层框架describe/it/test、钩子、断言库、spies 与配置框架变更视为独立适配器TestScheduler.run(...)包装器替换为一次直接rxTest调用并返回/等待其Promisevoidcold()表示每次订阅各起生产者的证据hot()表示类 Subject 的绝对时间线observable()表示共享引用计数的平台生产者expectObservable()保留订阅弹珠带来的取消flush()是异步的必须 await。调度器参数仅在安装版目标能力与 fixture 能证明宿主时序映射、且rxTest可虚拟化时才移除。4.7 每个已应用的转换必须可解析、可在窄边界类型检查、幂等且诊断稳定这是对“应用过”本身的验收标准可解析parseable、在其最窄边界可类型检查type-checkable at its narrow boundary、幂等idempotent、诊断稳定stable diagnostics。清单原句“Every applied transform is parseable, type-checkable at its narrow boundary, and idempotent with stable diagnostics.”五、验证与交接Verification and Handoff收尾清单的最后一节回答“凭什么说做完了、交给谁、缺口怎么带”。5.1 聚焦测试与全部约定门禁用精确命令运行“聚焦特征化/迁移测试与所有约定项目门禁都以精确命令、环境、退出码与结果运行。”verification-and-closeout.md 给出验证阶梯由窄到宽保证失败可诊断解析并格式化变更文件运行聚焦类型检查运行特征化与直接迁移的测试运行受影响包或 workspace 的构建、类型、lint 与测试门禁运行约定的集成、浏览器、native/polyfill 或仓库级门禁重跑诊断期间环境发生变化的任何命令。每次都要记录精确命令、相关环境事实、退出码、状态与简明摘要。5.2 失败分类不得为了“绿色报告”而改标签失败必须分类为迁移缺陷migration defects、产品缺口product gaps、有意偏差intentional divergences、基线/环境问题baseline/environment issues或未解决unresolved——不得为了一份全绿的报告而重新贴标签。四类失败的标准应对见 verification-and-closeout.md 的失败分类表分类含义必需响应迁移缺陷编辑破坏了语法、类型、测试意图、映射或所选契约小批次修复并重跑受影响门禁RxJS Next 产品缺口已接受的目标表面无法满足保留的证据保留证据可见报告产品缺口有意偏差已批准的 Next 行为不同于 RxJS 7 声明先记录新旧声明、影响、证据与批准再改期望基线/环境失败在迁移前就存在或所需运行时/工具不可用保留其原始状态记录限制或已接受失败未知证据尚无法定位原因调查或暂停绝不图方便改标签允许的修复是澄清或修正迁移代码、加强特征化、或修复已证明的迁移缺陷且不破坏已批准契约。以下动作必须暂停征求开发者删除/跳过/隔离/弱化测试改变公共行为声明添加本地运算符、调度器、兼容门面或断言垫片改变平台行为以模仿 RxJS 7超出受审范围的广泛依赖或配置变更接受红色或未运行的必需门禁。5.3 任何测试不得在无批准下被弱化“没有测试在未经明确开发者批准与记录契约变更的情况下被弱化、跳过、删除或替换。”这直接呼应 SKILL.md 的不可谈判规则不得仅为让迁移后的套件变绿而弱化、跳过、删除或替换行为期望。5.4 结构校验与就绪评估必须同时运行“schema 校验与就绪评估都运行一个不能替代另一个。”结构校验只回答“形状是否正确”就绪评估则要检出未解决的生命周期单元、待批准事项、未解决或被拒的诊断、未批准的偏差、缺失或红色的门禁、身份不匹配与未接受的阻塞项见 verification-and-closeout.md 的 Manifest closeout 一节。清单manifest必须依据安装包导出的确切 schema 构建至少记录该版本要求的 schema 与引擎身份、能力注册表版本、规范 Skill 摘要、精确的源/目标 RxJS 版本、基线检查、迁移单元、诊断、有意偏差、验证结果与阻塞项。对应源码在 packages/migrate/src/index.ts 中可见migrationContractManifestSchema、assessMigrationContractReadiness、parseMigrationContractManifest均作为公开 API 导出。5.5 所有诊断必须已解决、有负责人或由显式接受的阻塞项代表“所有诊断已解决、带有负责人或由显式接受的阻塞项代表。”一个被接受的阻塞项必须具名列出负责人owner与理由reason、受影响单元affected units、支撑证据evidence、其阻止的行为/环境/发布声明prevented outcome、显式开发者接受acceptance。报告模板的 “Accepted blockers” 表即为这五列设计。不得用阻塞项掩盖无法解释的回归。5.6 最终报告只陈述测得结果与局限“最终报告陈述测得结果与局限不声称通用自动迁移。”verification-and-closeout.md 的最终交接要求用报告资产即 migration-report.md 模板汇总范围与来源引擎/注册表/Skill/源 RxJS/目标 RxJS 身份RxJS 7 基线与特征化证据生命周期决策与批准按连贯批次划分的源码与测试变更精确的最终命令与结果诊断及其解决或携带方式修复的迁移缺陷遗留的产品缺口、偏差与环境限制阻塞项归属与下一步动作。禁止报告 “automatic migration succeeded”。只能陈述测得项目结果及其局限。这也是收尾清单整份文件想要防住的最后一件事用“一次通过”粉饰迁移而不是用“我测量了什么、我限制了什么、谁在为什么负责”来诚实交接。附收尾审查速查表维度核心问题判定为通过的最低标准权限与来源谁授权改、改到哪、版本可复现吗范围/包管理器/网络策略已记录变更均在授权边界内源修订、RxJS 版本、引擎/注册表版本、Skill 摘要精确可复现Skill 与安装包匹配基线与覆盖迁移前是绿的吗、风险都有人管吗未改动 RxJS 7 上约定门禁通过或既有失败被接受特征化测试在迁移前于 RxJS 7 上通过每条生命周期敏感路径都有覆盖/特征化/不支持/接受风险的处置目标契约每个单元要变成什么、谁批准的每单元有位置/声明/生命周期/证据分类/证据无未决或待批准单元生命周期为有意选择偏差记录新旧声明、影响、证据、批准人、时间与理由机械批次引擎用得对吗、写入受控吗能力来自安装版注册表dry-run 先于写入且诊断被审查拒绝源码保持可见写入在批准目标内且不覆盖重跑幂等且诊断稳定验证与交接测过什么、缺口怎么带走聚焦测试与全部门禁以精确命令运行失败按五类如实分类无测试被无批准弱化schema 校验与就绪评估都运行诊断已解决/有主/被接受阻塞项代表报告只陈述测得结果与局限按此清单逐项核对后就绪评估返回ready或ready-with-accepted-blockers才可宣告完成否则连同“下一步具体决策或动作”一起移交给开发者——这正是 RxJS 7 → RxJS Next 迁移收尾该有的样子。【免费下载链接】rxjsA reactive programming library for JavaScript项目地址: https://gitcode.com/gh_mirrors/rx/rxjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 RxJS 7 到 RxJS Next 迁移收尾审查清单（Migration Closeout Checklist）完整指南
RxJS 7 到 RxJS Next 迁移收尾审查清单Migration Closeout Checklist完整指南【免费下载链接】rxjsA reactive programming library for JavaScript项目地址: https://gitcode.com/gh_mirrors/rx/rxjs迁移从“代码改完、测试变绿”到“可以宣告完成”中间隔着一次系统性的收尾审查。本文以 RxJS 仓库中.agents/skills/rxjs-next-migration技能套件的收尾清单review-checklist.md为核心骨架结合 SKILL.md 定义的八阶段工作流、rxjs/migrate包源码与 migration-report.md 报告模板逐条讲解迁移收尾时必须验证的五个维度权限与来源Authority and provenance、基线与覆盖Baseline and coverage、目标契约Target contract、机械批次Mechanical batches、验证与交接Verification and handoff。读完本文你将掌握一套可执行的收尾审查协议——知道在什么条件下迁移才算真正完成什么情况下必须挂起blocker以及如何产出既通过模式校验、又通过就绪评估的迁移契约。适用前提本清单面向使用 Agent 主导工作流、以rxjs/migrate确定性引擎执行有界改写bounded rewrite的 RxJS 7 → RxJS Next 迁移项目。清单中引用的命令、版本与 schema 均以当前仓库实际安装的包为准。收尾审查在迁移流程中的位置在审查清单之前先明确它属于整个工作流的哪一环。技能套件将迁移划分为八个阶段且要求按顺序推进、随时可回退重入Stage 1建立权限与范围authority and scopeStage 2评估用法、生命周期风险与覆盖assessmentStage 3建立绿色 RxJS 7 基线green baselineStage 4分类并批准目标契约target contractStage 5规划并试运行有界引擎变更dry-runStage 6应用一个小迁移批次write batchStage 7构建、测试、诊断与修复verify repairStage 8收尾与交接close out and hand off收尾清单正是Stage 8 的强制入口——SKILL.md 明确要求更新契约清单与报告后必须逐项审查 review-checklist.md并如实报告“行为与生命周期契约改了什么、源码与测试改了什么、跑过哪些门禁及结果、修复的迁移缺陷与遗留的产品缺口、已批准的偏差与环境限制、剩余阻塞项及其负责人与验收状态”。只有在就绪评估返回ready或开发者明确选择的ready-with-accepted-blockers时才允许宣告完成否则只能作为未完成迁移移交并给出下一步具体决策或动作。核心立场贯穿始终这是一项经过评审的项目工作不是一次 codemod 运行。一个被转换的文件、一份干净的 diff、一个通过的测试都不足以证明迁移完成。一、权限与来源Authority and Provenance这一小节回答“我们凭什么改、改的是什么版本、工具链是否自洽”。清单要求四个可核验事实1.1 仓库指令、范围与策略在动手前就已记录仓库级指令repository instructions、允许写入的范围、包管理器package manager与网络策略network policy必须在任何大规模变更前记录在案既有工作existing work必须受保护每个被修改的文件都必须落在授权的迁移边界migration boundary之内变更涉及读取、写入、依赖与命令范围时需在动手前明确声明。对应到流程SKILL.md 的 Stage 1 要求定位仓库指令、包与 workspace 元数据、lockfile、CI 配置、RxJS 版本、构建/测试命令与当前工作树状态当目标仓库或允许范围不清晰、既有改动与迁移重叠、或需要破坏性/联网/外部/更广权限的动作时必须暂停征求开发者意见。1.2 版本与指纹完全可复现清单要求以下身份信息精确且可复现源仓库source repository与修订版本revisionRxJS 版本来源版本 RxJS 7 与目标版本 RxJS Next引擎版本engine version与注册表版本registry version规范 Skill 摘要canonical Skill digest。报告模板在 migration-report.md 中为“工具与依赖身份”专门设计了一张表格逐项填写Source RxJS、Target RxJS Next、rxjs/migrateengine、Capability registry、Canonical Skill、Contract schema 的版本或摘要及证据位置。这些字段在 Stage 8 收尾时不允许留空。1.3 已安装 Skill 与已安装包必须一致“已安装的 Skill 内容必须与已安装的rxjs/migrate包匹配”。如果发现不匹配流程要求停止并先同步之后才允许信任这些指令。这一条防止用“记忆中的能力表”代替“安装版注册表”进行判断——后文“机械批次”一节还会反复强调能力判定必须来自安装的版本化注册表而不是从 Skill 或记忆中重建。二、基线与覆盖Baseline and Coverage没有基线就没有迁移。这一小节确保迁移开始前的 RxJS 7 是绿的任何失败都被显式记录且每条生命周期敏感路径都有明确的覆盖处置。2.1 未变更源码上的门禁全部通过清单要求约定的构建、类型、lint、测试与行为门禁build, type, lint, test, behavior gates必须在未修改的 RxJS 7 源码上运行。对应 SKILL.md 的 Stage 3记录精确命令、环境事实、退出码与简明结果起始门禁失败时暂停由开发者决定“先修复”“缩小范围”还是“记录为已接受的既有失败”严禁静默改判为迁移回归或忽略。2.2 每个基线失败都有明确归属每个基线失败要么被修复要么被显式记录为“既有失败”并获得开发者接受developer acceptance。不允许“本地能过”这种没有命令与环境支撑的口头结论——verification-and-closeout.md 规定未记录命令和环境的 “Passed locally” 不构成验证记录。2.3 生命周期敏感路径的覆盖处置每条生命周期敏感路径必须关联以下四者之一既有测试覆盖existing coverage——有命名测试证明相关行为特征化测试characterization——迁移前新增的聚焦 RxJS 7 测试显式不支持explicit unsupported status——没有可接受的 Next 表面能保留该声明保留证据并记录为产品缺口开发者接受的未覆盖风险accepted uncovered risk——记录批准人、时间、理由与影响。assessment-and-contract.md 给出了覆盖处置的完整定义并建议对重复订阅、副作用、共享、迟到订阅者、取消、teardown、时序、错误或公共 API 行为在现有测试无法证明时优先补充特征化测试。缺覆盖不等于行为安全——“Missing coverage is not evidence that behavior is safe”。2.4 特征化测试必须在依赖迁移前于 RxJS 7 上通过“特征化测试必须在依赖/源码迁移之前于 RxJS 7 上通过。”特征化测试的要点见 assessment-and-contract.md 的 Characterization protocol 一节新增能证明外部可观测声明的最窄测试优先断言值、完成/错误、生产者启动次数、并发与迟到观察、取消归属、abort 原因、teardown 顺序、虚拟或宿主时序与可见副作用避免锁定无关的 RxJS 7 内部实现。迁移依赖后才补的特征化测试不构成 RxJS 7 基线除非能针对固定源码环境单独演示。三、目标契约Target Contract目标契约把“把代码改成什么”落成可审查、可批准的决策记录。这是整份清单中最强调“意图必须显式”的部分。3.1 每个单元必须有完整档案清单要求每个迁移单元migration unit都具备稳定的源码位置stable source locations行为声明behavioral claim一个目标生命周期one target lifecycle一个证据分类evidence classification支撑证据supporting evidence。对应 SKILL.md 的工作记录要求为每个单元保留源码位置并记录其当前 RxJS 7 行为声明、开发者选择的目标生命周期、证据分类与支撑测试、批准状态/诊断/任何有意偏差、验证结果或具名阻塞项。报告模板的 “Target contract units” 表则要求逐行填写Unit ID、Source locations、RxJS 7 claim、Target lifecycle、Evidence classification、Approval、Evidence。3.2 没有单元可停留在未决状态“没有必需单元保持未解决unresolved或待批准pending approval。”引擎可以识别风险但不能替开发者选择生命周期意图——unresolved是停止状态。当平台共享行为platform-shared与每次直接订阅各起生产者producer-per-direct-subscription两种解释都成立或 Subject 语义、取消、调度器顺序、错误行为、互操作或公共行为变化未被证明时必须暂停征求开发者。3.3 生命周期选择必须基于意图而非语法推断“平台共享与每次直接订阅各起生产者的行为是有意选择的而非从语法推断的。”SKILL.md 将其列为不可谈判规则绝不根据语法、文件名、运算符名称或当前通过的输出来推断平台共享 vs. 每次订阅独立生产者的行为。可接受的生命周期取值以安装版契约清单 schema 为准包括活跃平台生产者共享并在存在观察者时引用计数、通过显式 Next API 按直接订阅创建生产者工作、有意的热 Subject 行为、无生产者生命周期、所需行为不支持、意图仍未解决。同时禁止用笼统的 “hot/cold” 标签描述平台 Observable——正确的行为描述是首个观察者启动活跃生产者并发观察者加入最后离开的观察者触发 teardown后续观察者可以启动新的一轮。3.4 需重点审查的行为维度清单点名要求逐项审查如适用Subjects、重复订阅、取消cancellation、teardown、时序timing、错误errors与输入转换input conversion。这些维度与 verification-and-closeout.md 中生命周期敏感代码的验证清单一一对应生产者激活次数与重启、并发与迟到观察、单独与最终取消、abort 原因与上游关闭、Subject 当前值/重放/终态行为、teardown 顺序、时间与调度顺序、错误投递与迟到/未处理错误行为、输入转换接受或显式拒绝。3.5 有意偏差必须完整记录每个有意偏差intentional divergence必须记录旧声明与新声明、用户影响user impact、证据、批准人approver、时间戳与理由rationale。且偏差的批准有先后顺序——先做结构校验schema validation再跑就绪评估readiness assessment两者是独立检查不能互相替代清单“验证与交接”一节再次强调。含未决意图或待批准单元的批次不得继续推进。四、机械批次Mechanical Batches这一小节约束引擎改写过程本身能力判定、dry-run、写入与幂等性。4.1 能力判定来自安装版注册表“能力决策来自已安装的版本化注册表installed versioned registry不使用复制的运算符清单或仅名称匹配。”engine-and-batches.md 要求从项目安装的包读取引擎数据公开 API 导出默认能力注册表、注册表与清单 schema、迁移函数、契约就绪评估、引擎/schema 版本而不是从提示词、Skill 或 harness 适配器里复制清单。选择转换前必须核对注册表 schema/版本与引擎版本匹配安装包、源导入绑定确为引擎识别的绑定且未被遮蔽或复用、调用形态/元数/调度器与结果选择器形态/管道上下文满足全部声明的前置条件、fixture 证据覆盖目标映射与证据类别、迁移单元已有批准的生命周期契约。名称相似、TypeScript 签名兼容或转换后测试变绿都不足以替代上述检查。仓库中的公开 API 在 packages/migrate/src/index.ts 可直接印证它导出defaultCapabilityRegistry、defaultTestSchedulerCapabilities、capabilityMappingSchema、capabilityRegistrySchema、migrationContractManifestSchema、assessMigrationContractReadiness、parseCapabilityRegistry、parseMigrationContractManifest、migrateTestSchedulerSemantics、migrateTestSource以及capabilityRegistryVersion、migrationContractSchemaVersion、migrationEngineVersion等版本常量。本地检查可以用类似 engine-and-batches.md 给出的形态遍历注册表并校验清单import { assessMigrationContractReadiness, defaultCapabilityRegistry, migrationContractManifestSchema } from rxjs/migrate; for (const capability of defaultCapabilityRegistry.capabilities) { // Review id, legacy/source name, target Symbol, adapter, arity, // preconditions, status, and fixture evidence for this exact package. } const parsed migrationContractManifestSchema.safeParse(manifest); if (parsed.success) { const readiness assessMigrationContractReadiness(parsed.data, { expectedSkillDigest, }); }expectedSkillDigest从已安装适配器的完整性检查或 Node-only 的rxjs/migrate/skillAPI 获取精确签名以安装的 TypeScript 声明为准。4.2 每个引擎操作先 dry-run“每个引擎操作先以精确来源信息 dry-run必要时使用显式的生命周期模式。”CLI 的 dry-run 形态来自 engine-and-batches.mdrxjs-migrate \ --source-root authorized-root \ --source-repo source-repository \ --source-sha exact-revision \ --mode approved-cold-or-platform-mode \ --framework preserve \ selected-files要点选中源码不需要生命周期选择时省略--mode绝不让目录名或包装器隐式选择它框架适配器只在开发者单独批准框架变更时使用。不带--write时CLI 返回版本化 JSON 报告且不执行任何写入需记录其引擎版本、注册表版本、操作、文件结果、有序诊断与退出状态——当前 CLI 契约区分完成、结构化拒绝、无效参数与运行失败四种结果。4.3 dry-run 范围、诊断与变更路径必须在写入前审查“写入前审查 dry-run 范围、诊断与变更路径。”所有诊断都要审阅包括源码跨度source span、严重性severity、处置disposition、拒绝范围refusal scope、分类classification、下一步动作next action与能力 IDcapability ID。被拒绝的批次必须保持源与目标均不变。4.4 被拒绝或不支持的源码必须保持可见“被拒绝或不支持的源码保持可见不得通过部分转换偷运smuggled through。”engine-and-batches.md 的拒绝与人工修复一节给出四条出路收窄批次到可独立安全的单元补特征化测试、获得开发者决策并在引擎声称输出之外做受审语义编辑报告 RxJS Next 产品缺口保留源码并接受具名阻塞项。禁止通过绕开诊断把被拒语法伪装成机械输出。人工工作同样受基线、生命周期、审查与验证门禁约束且不得被描述为 fixture 证明的引擎输出。4.5 写入受控且不覆盖本地内容写入阶段的命令形态同样来自 engine-and-batches.mdrxjs-migrate \ --source-root authorized-root \ --source-repo source-repository \ --source-sha exact-revision \ --mode approved-cold-or-platform-mode \ --framework preserve \ --write --out-dir authorized-destination \ selected-files引擎在写入前规划整个批次并拒绝词法、规范或符号链接路径逃逸lexical, canonical, or symlink path escape不得用手工批量写入绕过包含containment与不覆盖no-overwrite行为。若受审目标就是当前源码树必须显式声明该范围与覆盖决策并保持可恢复性。写入报告与 dry-run 报告在契约要求处逐字节比对随后不带写入地重跑同一转换第二次结果必须不变且诊断稳定——任何输出或诊断漂移都视为引擎缺陷停止批次并保留复现。4.6 输出必须保留项目自有代码与测试“输出保留项目自有源码、直接测试、断言与所选框架。”对应 SKILL.md Stage 6 的要求通过项目常规工具格式化确保项目自有源码与直接测试声明保留不在结果中遗留动态生成器、隐藏用例注册表或兼容断言层立即检查解析、最窄类型边界与引擎幂等性不满足则恢复该批次到受审起点并上报引擎缺陷。测试迁移的细节规则见 test-migration.md默认保留外层框架describe/it/test、钩子、断言库、spies 与配置框架变更视为独立适配器TestScheduler.run(...)包装器替换为一次直接rxTest调用并返回/等待其Promisevoidcold()表示每次订阅各起生产者的证据hot()表示类 Subject 的绝对时间线observable()表示共享引用计数的平台生产者expectObservable()保留订阅弹珠带来的取消flush()是异步的必须 await。调度器参数仅在安装版目标能力与 fixture 能证明宿主时序映射、且rxTest可虚拟化时才移除。4.7 每个已应用的转换必须可解析、可在窄边界类型检查、幂等且诊断稳定这是对“应用过”本身的验收标准可解析parseable、在其最窄边界可类型检查type-checkable at its narrow boundary、幂等idempotent、诊断稳定stable diagnostics。清单原句“Every applied transform is parseable, type-checkable at its narrow boundary, and idempotent with stable diagnostics.”五、验证与交接Verification and Handoff收尾清单的最后一节回答“凭什么说做完了、交给谁、缺口怎么带”。5.1 聚焦测试与全部约定门禁用精确命令运行“聚焦特征化/迁移测试与所有约定项目门禁都以精确命令、环境、退出码与结果运行。”verification-and-closeout.md 给出验证阶梯由窄到宽保证失败可诊断解析并格式化变更文件运行聚焦类型检查运行特征化与直接迁移的测试运行受影响包或 workspace 的构建、类型、lint 与测试门禁运行约定的集成、浏览器、native/polyfill 或仓库级门禁重跑诊断期间环境发生变化的任何命令。每次都要记录精确命令、相关环境事实、退出码、状态与简明摘要。5.2 失败分类不得为了“绿色报告”而改标签失败必须分类为迁移缺陷migration defects、产品缺口product gaps、有意偏差intentional divergences、基线/环境问题baseline/environment issues或未解决unresolved——不得为了一份全绿的报告而重新贴标签。四类失败的标准应对见 verification-and-closeout.md 的失败分类表分类含义必需响应迁移缺陷编辑破坏了语法、类型、测试意图、映射或所选契约小批次修复并重跑受影响门禁RxJS Next 产品缺口已接受的目标表面无法满足保留的证据保留证据可见报告产品缺口有意偏差已批准的 Next 行为不同于 RxJS 7 声明先记录新旧声明、影响、证据与批准再改期望基线/环境失败在迁移前就存在或所需运行时/工具不可用保留其原始状态记录限制或已接受失败未知证据尚无法定位原因调查或暂停绝不图方便改标签允许的修复是澄清或修正迁移代码、加强特征化、或修复已证明的迁移缺陷且不破坏已批准契约。以下动作必须暂停征求开发者删除/跳过/隔离/弱化测试改变公共行为声明添加本地运算符、调度器、兼容门面或断言垫片改变平台行为以模仿 RxJS 7超出受审范围的广泛依赖或配置变更接受红色或未运行的必需门禁。5.3 任何测试不得在无批准下被弱化“没有测试在未经明确开发者批准与记录契约变更的情况下被弱化、跳过、删除或替换。”这直接呼应 SKILL.md 的不可谈判规则不得仅为让迁移后的套件变绿而弱化、跳过、删除或替换行为期望。5.4 结构校验与就绪评估必须同时运行“schema 校验与就绪评估都运行一个不能替代另一个。”结构校验只回答“形状是否正确”就绪评估则要检出未解决的生命周期单元、待批准事项、未解决或被拒的诊断、未批准的偏差、缺失或红色的门禁、身份不匹配与未接受的阻塞项见 verification-and-closeout.md 的 Manifest closeout 一节。清单manifest必须依据安装包导出的确切 schema 构建至少记录该版本要求的 schema 与引擎身份、能力注册表版本、规范 Skill 摘要、精确的源/目标 RxJS 版本、基线检查、迁移单元、诊断、有意偏差、验证结果与阻塞项。对应源码在 packages/migrate/src/index.ts 中可见migrationContractManifestSchema、assessMigrationContractReadiness、parseMigrationContractManifest均作为公开 API 导出。5.5 所有诊断必须已解决、有负责人或由显式接受的阻塞项代表“所有诊断已解决、带有负责人或由显式接受的阻塞项代表。”一个被接受的阻塞项必须具名列出负责人owner与理由reason、受影响单元affected units、支撑证据evidence、其阻止的行为/环境/发布声明prevented outcome、显式开发者接受acceptance。报告模板的 “Accepted blockers” 表即为这五列设计。不得用阻塞项掩盖无法解释的回归。5.6 最终报告只陈述测得结果与局限“最终报告陈述测得结果与局限不声称通用自动迁移。”verification-and-closeout.md 的最终交接要求用报告资产即 migration-report.md 模板汇总范围与来源引擎/注册表/Skill/源 RxJS/目标 RxJS 身份RxJS 7 基线与特征化证据生命周期决策与批准按连贯批次划分的源码与测试变更精确的最终命令与结果诊断及其解决或携带方式修复的迁移缺陷遗留的产品缺口、偏差与环境限制阻塞项归属与下一步动作。禁止报告 “automatic migration succeeded”。只能陈述测得项目结果及其局限。这也是收尾清单整份文件想要防住的最后一件事用“一次通过”粉饰迁移而不是用“我测量了什么、我限制了什么、谁在为什么负责”来诚实交接。附收尾审查速查表维度核心问题判定为通过的最低标准权限与来源谁授权改、改到哪、版本可复现吗范围/包管理器/网络策略已记录变更均在授权边界内源修订、RxJS 版本、引擎/注册表版本、Skill 摘要精确可复现Skill 与安装包匹配基线与覆盖迁移前是绿的吗、风险都有人管吗未改动 RxJS 7 上约定门禁通过或既有失败被接受特征化测试在迁移前于 RxJS 7 上通过每条生命周期敏感路径都有覆盖/特征化/不支持/接受风险的处置目标契约每个单元要变成什么、谁批准的每单元有位置/声明/生命周期/证据分类/证据无未决或待批准单元生命周期为有意选择偏差记录新旧声明、影响、证据、批准人、时间与理由机械批次引擎用得对吗、写入受控吗能力来自安装版注册表dry-run 先于写入且诊断被审查拒绝源码保持可见写入在批准目标内且不覆盖重跑幂等且诊断稳定验证与交接测过什么、缺口怎么带走聚焦测试与全部门禁以精确命令运行失败按五类如实分类无测试被无批准弱化schema 校验与就绪评估都运行诊断已解决/有主/被接受阻塞项代表报告只陈述测得结果与局限按此清单逐项核对后就绪评估返回ready或ready-with-accepted-blockers才可宣告完成否则连同“下一步具体决策或动作”一起移交给开发者——这正是 RxJS 7 → RxJS Next 迁移收尾该有的样子。【免费下载链接】rxjsA reactive programming library for JavaScript项目地址: https://gitcode.com/gh_mirrors/rx/rxjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考