RxJS Next 迁移 Agent Skill 完全指南安装、调用与 8 阶段迁移工作流【免费下载链接】rxjsA reactive programming library for JavaScript项目地址: https://gitcode.com/gh_mirrors/rx/rxjs本指南基于 docs/rxjs-next/MIGRATION_SKILL_GUIDE.md系统讲解 RxJS 仓库中rxjs/migrate包随附的 Agent Skill位于 packages/migrate/skill的安装、调用、权限配置、生命周期管理与验证方式并完整展开其内置的 8 阶段迁移工作流。读者读完将掌握如何在 Codex、Claude Code、Cursor 三个 AI 编码代理中部署并显式调用该 Skill如何理解其先建立绿色 RxJS 7 基线、再逐批机械改写、最后按证据关单的迁移方法论以及如何借助 packages/migrate 的 CLI 与源码验证每一步行为。一、Skill 是什么权威源、生成副本与完整性摘要rxjs/migrate当前仓库内版本为9.0.0-beta.0见 packages/migrate/package.json是一个一次性把 RxJS 7 源码迁移到 RxJS Next的迁移工具包。它随包发布了一个经过人工编写的 Agent Skill权威源位于packages/migrate/skill/SKILL.md——Skill 主文件定义了完整的 8 阶段工作流packages/migrate/skill/assets/migration-report.md——迁移报告模板packages/migrate/skill/references——5 份分阶段参考文档下文专节介绍。仓库内其他位置出现的副本如各代理宿主目录下的生成副本都是从权威源生成的每个副本都携带包版本号和 SHA-256 摘要。因此不要直接编辑生成副本任何修改都应改权威源packages/migrate/skill然后运行更新命令重新生成安装、检查、更新全部以权威源的摘要为基准进行比对防止副本与包内容漂移。在源码层面完整性校验由 packages/migrate/src/skill-integrity.ts 实现inspectSkillIntegrity按稳定顺序文件名排序对 Skill 内每个文件的名称和字节计算 SHA-256并拒绝任何符号链接避免两个安装声称同一来源却解析到包外不同内容摘要连同schemaVersion、packageName、packageVersion组成SkillIntegrity记录。安装时这份记录会被写入目标目录下的 provenance 文件.rxjs-migrate-skill.json供后续状态判定使用。二、安装与调用2.1 安装命令在待迁移的仓库中安装rxjs/migrate后使用rxjs-migrate-skill命令选择目标代理宿主安装 Skillnpx rxjs-migrate-skill install --harness codex --project-root . npx rxjs-migrate-skill install --harness claude --project-root . npx rxjs-migrate-skill install --harness cursor --project-root .参数说明参数含义说明check\|install\|update\|remove动作四个动作之一下文详述--harness codex\|claude\|cursor目标代理宿主必填决定安装路径与调用方式--project-root dir项目根目录默认当前工作目录Skill 目标必须落在项目根目录之内--force强制覆盖仅在更新/移除本地被修改的副本时按需显式提供参数解析实现在 packages/migrate/src/skill-cli.ts 的parseSkillArguments中--harness的合法取值被限定为skillHarnesses即codex、claude、cursor三者见 packages/migrate/src/skill-install.ts 第 11 行。2.2 各宿主的发现路径与调用方式安装后各宿主的生成发现路径与显式调用方式如下与指南原文一致Host生成发现路径显式调用Codex.agents/skills/rxjs-next-migration/SKILL.md$rxjs-next-migrationClaude Code.claude/skills/rxjs-next-migration/SKILL.md/rxjs-next-migrationCursor.agents/skills/rxjs-next-migration/SKILL.md/rxjs-next-migration源码中这三套映射定义在 packages/migrate/src/skill-install.ts 的skillHarnessAdapters常量中关键细节包括Codex 与 Cursor 刻意共享.agents/skills目录与完全相同的生成字节两者共用agents适配器且compatibleHarnesses均声明为[codex, cursor]Claude Code 使用独立的.claude/skills目录与claude适配器compatibleHarnesses仅为[claude]三者的隐式调用触发语一致均为 Migrate this RxJS 7 project to RxJS Next.安装使用普通文件复制而非符号链接因此不需要符号链接特权源码在replaceInstallation中通过cp递归复制并写入 provenance 文件。任何宿主都可以通过类似Migrate this RxJS 7 project to RxJS Next.的请求让代理隐式选择该 Skill但指南建议在验证发现机制时优先使用显式调用以保证测试的是确定性的发现路径而非启发式猜测。三、权限模型最小权限原则指南对 Skill 运行时的权限边界有明确约定默认只读起步先授予仓库读取权限写入仅限迁移批次只有开发者放入迁移批次的路径才允许写命令白名单只允许运行仓库声明的包管理器、构建、类型检查、lint 与测试命令网络与装包需审批网络访问或安装依赖必须获得开发者批准明确不需要的能力生产凭据、项目 MCP 写入权限、破坏性权限、发布权限一律不需要。这些权限指引在源码中以sharedPermissionGuidance常量形式固化packages/migrate/src/skill-install.ts 第 13–23 行九个条目逐一列明读取选中仓库与检入指令、仅写迁移范围内经审阅的路径、仅运行本地包管理/构建/类型/lint/测试命令、未知命令先探测工具再请求确认、网络与装包前请求批准、无需生产凭据、无需项目 MCP 写入权限、破坏性动作不在默认权限集、外部发布不在默认权限集。各宿主的环境约束方式不同但都只是约束宿主本身不改变可移植的工作流Codex使用其常规的工作区沙箱与审批策略Claude Code可在编辑获批前先进入 plan 模式Cursor可在 Ask 或 Plan 模式起步。四、检查、更新与移除安装之外rxjs-migrate-skill还提供三个生命周期管理动作npx rxjs-migrate-skill check --harness codex --project-root . npx rxjs-migrate-skill update --harness codex --project-root . npx rxjs-migrate-skill remove --harness codex --project-root .按需替换--harness名称即可。行为要点check以版本化 JSON 报告当前状态状态取值有四种absent未安装、current与权威源一致、stale权威源已更新、副本过期、modified副本被本地改动。状态的判定逻辑在 packages/migrate/src/skill-install.ts 的installationState目标不存在为absent目标不是普通目录或是符号链接为modifiedprovenance 缺失、副本内容与 provenance 不符视为modified副本内容与 provenance 一致但 provenance 与当前权威源的完整性记录不一致则为stale全部一致才是currentupdate原子地替换未修改的过期副本先复制到临时暂存目录、生成 provenance、再通过 rename 交换异常时回滚并保留备份见replaceInstallation--force语义更新与移除在检测到副本被本地修改时会拒绝执行除非开发者显式提供--force安装同理覆盖stale或modified副本需要update或显式--force退出码CLI 层定义了四类退出码——0成功、1拒绝refused、2参数非法、3操作失败见 packages/migrate/src/skill-cli.ts 第 7 行与runSkillCli的错误分类逻辑所有输出均为版本化 JSON。此外安装路径的合法性在resolveInstallation中通过assertContained双重校验解析前与解析符号链接后确保 Skill 目标路径始终位于项目根目录之内防止路径逃逸。五、发现冒烟场景Discovery smoke scenario指南提供了一个最小宿主冒烟测试用于验证Skill 是否真的被代理发现并按其权威内容工作。在干净仓库中安装 Skill 后向代理发出这个只读请求Do not edit files or run commands. Name the workflow stage that requires a green RxJS 7 baseline and state who must approve lifecycle selection.不要编辑文件或运行命令。指出需要绿色 RxJS 7 基线的工作流阶段并说明谁必须批准生命周期选择。每个宿主都必须到达同一个权威工作流并回答基线在Stage 3: Establish the green RxJS 7 baseline建立绿色 RxJS 7 基线阶段确立生命周期选择必须由开发者批准。同时代理不得自动选择 platform 共享或 producer-per-subscription 行为这是 Skill 反复强调的禁止从语法/文件名推断生命周期原则的直接体现。冒烟测试的意义在于它同时验证了发现Skill 被加载、内容回答来自权威 SKILL.md 而非宿主自身知识与纪律不擅自做生命周期决策。六、核心工作流8 阶段迁移方法论Skill 主文件 packages/migrate/skill/SKILL.md 将迁移定义为经审阅的项目工作而非一次 codemod 运行并强制要求按顺序走完 8 个阶段任何时候新证据改变范围、覆盖或生命周期意图时都可以回退到更早阶段重新进入。以下逐阶段展开。非协商规则贯穿全程行动前先读取并遵守仓库本地指令保护既有工作留在授权仓库与路径内先建 RxJS 7 基线再改依赖或源码永远不根据语法、文件名、操作符名或当前通过的输出推断 platform 共享与 producer-per-direct-subscription 行为以安装引擎的版本化注册表与 schema 为权威不从 Skill 或记忆重建能力映射先无写入运行确定性引擎拒绝是成功的安全结果不是自由发挥机械改写improvise的许可默认保留项目测试框架仅在开发者要求单独转换时才选择框架适配器不得为让迁移后的测试套件变绿而削弱、跳过、删除或替换行为期望不得添加 RxJS 7 兼容垫片、字符串命名的平台方法、本地替代操作符或运行时生成器除非开发者另行授权保持小规模连贯批次每批审阅验证后再扩大范围存在未知、未批准、被跳过或未通过red且没有显式接受 blocker 的命令时不得宣称迁移完成。Stage 1确立权威与范围定位仓库指令、包与 workspace 元数据、锁文件、CI 配置、RxJS 版本、构建/测试命令与当前工作树状态确定仓库根、迁移边界、允许写入、包管理器、网络策略与候选验证命令记录已安装的rxjs/migrate版本与权威 Skill 摘要——若已安装的 Skill 与包不匹配先停下同步再信任这些指令在广泛改动前声明拟议的读/写/依赖/命令范围。出现以下情况必须暂停征求开发者意见目标仓库或允许范围不清晰、既有改动与迁移重叠、破坏性/网络化/外部/更广泛的动作需要新授权。只有范围、允许写入、包管理器与候选门禁都被记录后才能退出本阶段。Stage 2评估用法、生命周期风险与覆盖盘点已安装的 RxJS 版本与导入形式定位 Observable 构造、自定义 producer、Subject、订阅所有权、重复订阅、retry/refresh/cache 路径、scheduler 与计时、测试辅助、互操作输入、取消、teardown 与错误处理且包含直接与传递性的操作符使用追踪导入与包装器避免把传递使用误判为不存在。对每条生命周期敏感路径给出精确源码证据并标记为四选一已有基线覆盖、需要特征化测试characterization test、明确不支持、开发者接受未覆盖风险。在提议任何改写前产出风险与覆盖报告协议详见 packages/migrate/skill/references/assessment-and-contract.md。当范围内每条敏感使用都有记录在案的覆盖处置后退出——覆盖缺失不等于行为安全。Stage 3建立绿色 RxJS 7 基线对未改动的 RxJS 7 项目运行约定的构建、类型、lint、单元、集成与行为检查记录精确命令、环境事实、退出码与简明结果。在 Stage 2 发现实质性缺口处补充聚焦的特征化测试覆盖可观察值、完成/错误行为、producer 多重性、取消、abort 原因、teardown 顺序、计时与外部可见的订阅副作用每条特征化测试在迁移开始前必须在 RxJS 7 上通过。若起始门禁失败则暂停诊断后询问开发者是先行修复、缩小范围还是记录为已接受的既有失败绝不悄悄将其重新归类为迁移回归或忽略。只有基线全绿或每个指名失败获得显式批准且特征化测试全绿后才能退出。Stage 4分类并批准目标契约将范围划分为稳定的迁移单元。对每个单元使用已安装 manifest schema 接受的生命周期值与一种证据分类记录唯一目标生命周期并用仓库证据与 packages/migrate/skill/references/assessment-and-contract.md 解释选择。引擎可以识别风险但不能选择生命周期意图unresolved是停止状态。以下情形必须暂停等待开发者platform 共享与 producer-per-direct-subscription 行为都看似合理、Subject 语义/取消/scheduler 顺序/错误行为/互操作/公共行为变更未被证明。有意分歧intentional divergence必须给出具体的旧主张、拟议的新主张、用户影响、证据与开发者批准。先做 manifest 结构校验再运行已安装的就绪评估readiness assessment含未解决意图或待批准内容的批次不得继续。只有开发者批准了下一批次所需的全部歧义选择与有意分歧后才能退出。Stage 5规划并干跑dry-run有界引擎改动检查已安装的能力注册表只选择版本、源形式、元数arity、前置条件与可执行证据均匹配已批准单元的条目——不要凭熟悉的名字推断支持。具体协议见 packages/migrate/skill/references/engine-and-batches.md批次含 RxJS 7 marble 测试时另读 packages/migrate/skill/references/test-migration.md。在不带--write的情况下以显式 provenance 和必要时已批准的cold或platform模式运行rxjs-migrate默认保留当前测试框架。捕获版本化 JSON 报告、变更路径、结构化诊断与退出码。CLI 的报告契约在 packages/migrate/src/cli.ts 中定义createMigrationCliReport先做无写入的planMigrationFiles只要计划中任一文件结果为refused就整体拒绝写入因此只有干跑计划全部成功才可能落盘。遇到需要审阅或拒绝转换的诊断、输出将逃逸授权路径、源码与能力证据不匹配、批次规模或语义触及超出审阅范围时暂停。绝不把不支持片段藏进部分转换的管线里。诊断与变更文件范围审阅完毕、开发者批准任何新扩大的批次后才能退出。Stage 6应用一个小迁移批次只应用审阅过的干跑计划要求显式写入目标且位于授权项目内保留源码 provenance未获明确批准不得覆盖既有输出额外编辑前先审阅 diff。使用项目常规工具格式化确保普通项目自有源码与直接测试声明保留不得在结果中遗留动态生成器、隐藏用例注册表或兼容性断言层。落盘后立即检查解析、最窄有意义的类型边界、引擎幂等性——重跑同一转换必须不产生任何新源码变更且诊断稳定若不满足把受影响的批次恢复到审阅过的起点并报告引擎缺陷。批次可解析、在窄边界通过类型检查、幂等且每条诊断已解决/结转/升级后才能退出。Stage 7构建、测试、诊断与修复先跑聚焦的特征化与已迁移测试再跑约定的项目门禁。把每个失败分类为迁移缺陷、RxJS Next 产品缺口、有意分歧、环境/基线问题、或仍未知。修复规则见 packages/migrate/skill/references/verification-and-closeout.md迁移缺陷小批次修复并重跑相关门禁产品缺口保留失败证据并上报不用本地替代品伪装有意分歧只有 manifest 记录经批准的新行为与用户影响后才改期望。以下修复必须先暂停征求开发者改变公共行为、削弱证据、扩大写入、超出审阅计划改依赖、需要外部访问、引入兼容层。约定的门禁全部通过或每条剩余 red 结果都有指名、有证据、被显式接受的 blocker 时才能退出。Stage 8关单与交接用精确的源/目标版本、引擎版本、能力注册表版本、权威 Skill 摘要、基线、单元、诊断、分歧、最终命令/结果与 blocker 更新契约 manifest 与报告用已安装 schema 校验 manifest并单独评估就绪度结构有效只回答形状对不对就绪评估才检测未解决单元、待批准、未解决/被拒诊断、未批准分歧、缺失/red 门禁、身份不匹配与未接受 blocker。用 packages/migrate/skill/references/review-checklist.md 逐项复查并报告六项内容行为与生命周期契约发生了什么变化哪些源码与测试变了跑过哪些门禁及结果修复的迁移缺陷 vs 保留的产品缺口已批准的分歧与环境限制剩余 blocker、负责人、证据与验收。只有就绪状态为ready或开发者有意选择ready-with-accepted-blockers才能宣称完成否则作为未完成迁移交接附上下一个具体决策或行动。七、五份参考文档的分工Skill 工作流依赖 packages/migrate/skill/references 下五份参考文档按阶段使用参考文档使用阶段核心内容assessment-and-contract.mdStage 2–4仓库评估主题表构造/重复订阅/Subject/所有权/teardown/计时/错误/输入/组合/测试、覆盖处置四分类、特征化协议、生命周期决策记录格式、必须暂停的开发者停顿清单engine-and-batches.mdStage 5–6从已安装包消费版本化注册表与 schema含rxjs/migrate编程式 API 示例、能力选择五要素校验、干跑与写入协议、逐字节对比、幂等性验证、拒绝与手工修复四条路径test-migration.mdStage 5–6含 marble 测试时保留外层测试框架、cold()/hot()/observable()/expectObservable()/expectSubscriptions()/time()/animate()/flush()的语义与转换约束、通过注册表转换组合、平台生命周期与 realm 隔离测试要求verification-and-closeout.mdStage 7–8从窄到宽的验证阶梯、失败五分类表与响应、需要暂停的修复清单、manifest 关单与就绪评估、blocker 命名要素、最终交接报告要素review-checklist.mdStage 8权威与 provenance、基线与覆盖、目标契约、机械批次、验证与交接五大块的完整收尾核对清单八、工作记录与报告迁移契约 manifestSkill 要求创建或定位一份检入版本库的迁移契约 manifest和一份简明的人读报告模板见 packages/migrate/skill/assets/migration-report.md。manifest 必须使用已安装rxjs/migrate导出的 schemaschema 校验与迁移就绪是两个独立检查不可互相替代。对每个迁移单元必须保留源码位置并记录当前 RxJS 7 行为主张、开发者选择的目标生命周期、证据分类与支撑测试、批准状态/诊断/任何有意分歧、验证结果或具名 blocker。这正是经审阅的项目工作而非自动迁移脚本的落地载体一个转换过的文件、一份干净的 diff 或一个通过的测试都不是迁移完成的证明。九、验证与结论指南最后记录了宿主引用的复核情况发现与调用行为于 2026-07-31 对照官方 Codex Skills 文档、Claude Code Skills 文档、Cursor Agent Skills 文档及 Agent Skills 规范进行了复核本地适配器冒烟使用了 Codex0.146.0-alpha.3.1、Claude Code2.1.119与 Cursor3.13.10。包的验收测试套件会安装干净的 Codex、Claude、Cursor fixtures检查其发现与调用元数据比对权威字节与摘要强制执行最小权限指引并演练 stale、modified、update、force 与移除行为P0.M5则负责针对代表性仓库的实机模型结果资格验证相关测试可参考 packages/migrate/src/skill-cli.spec.ts 与 packages/migrate/src/skill-integrity.spec.ts。从整体设计看结合 packages/migrate/src/skill-cli.ts 与 packages/migrate/src/skill-install.ts 的实现这套 Skill 体系可以归纳为三条核心原则权威单一一切以packages/migrate/skill与已安装包的版本化注册表为准、生命周期意图归人引擎只做有界机械改写共享与独立 producer 的选择永远由开发者批准、证据驱动关单绿色基线、特征化测试、逐字节幂等、五类失败分类与显式 blocker 缺一不可。对于任何需要从 RxJS 7 迁移到 RxJS Next 的应用、库或测试套件这就是官方提供的、可审计的、代理可执行的迁移路径。【免费下载链接】rxjsA reactive programming library for JavaScript项目地址: https://gitcode.com/gh_mirrors/rx/rxjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考