nemo-relay-migrate-from-flow

从 NeMo Flow 迁移到 NeMo Relay

当用户已有 NeMo Flow 代码或文档，并希望将其转换为 NeMo Relay 时，使用此技能。应将迁移视为机械式重命名加上特定语言的验证，而不是行为改写。 在执行广泛重命名前，先明确兼容性例外。

默认工作流

1. 检查工作树并确定涉及的部分：Rust、Python、Node.js、Go、C FFI、CLI/配置、文档或集成。
2. 将 SKILL_DIR 解析为包含此 SKILL.md 的绝对目录，并将 TARGET_PATH 解析为源代码仓库或目标项目。编辑前，以试运行模式运行附带的辅助脚本： python3 "$SKILL_DIR/scripts/migrate_from_nemo_flow.py" "$TARGET_PATH" --rename-paths
3. 与用户一起审查报告中的文本编辑、路径重命名和旧版项目配置警告。不要将项目本地的 .nemo-flow/config.toml 或 .nemo-flow/plugins.toml 迁移到 .nemo-relay。审查后，手动将这些设置移至受支持的用户级配置路径或显式配置路径。
4. 获取对已解析目标根目录的明确确认，然后使用 --write、--rename-paths 和 --confirm-root "$TARGET_PATH" 重新运行。
5. 针对特定语言清理包管理器锁文件、生成的产物和公共 API 示例。
6. 搜索残留的 Flow 名称，并验证受影响的语言部分。

机械式重命名映射

• 品牌和仓库：NeMo Flow -> NeMo Relay， NeMo-Flow -> NeMo-Relay
• Python：nemo-flow -> nemo-relay，nemo_flow -> nemo_relay， python/nemo_flow -> python/nemo_relay
• Rust：nemo-flow -> nemo-relay，nemo-flow-adaptive -> nemo-relay-adaptive，nemo_flow:: -> nemo_relay::
• Node.js：nemo-flow-node -> nemo-relay-node，包括相关入口点， 例如 /typed、/plugin、/adaptive 和 /observability
• Go：github.com/NVIDIA/NeMo-Flow/go/nemo_flow -> github.com/NVIDIA/NeMo-Relay/go/nemo_relay，包别名 nemo_flow -> nemo_relay，源目录 go/nemo_flow -> go/nemo_relay
• C FFI：nemo_flow.h -> nemo_relay.h，nemo_flow_* -> nemo_relay_*，NemoFlow* -> NemoRelay*，以及 NEMO_FLOW_* -> NEMO_RELAY_*
• CLI/配置：nemo-flow -> nemo-relay， ~/.config/nemo-flow -> ~/.config/nemo-relay，NEMO_FLOW_* -> NEMO_RELAY_*，以及 x-nemo-flow-* -> x-nemo-relay-*。不要盲目地将项目本地的 .nemo-flow/config.toml 或 .nemo-flow/plugins.toml 重命名为 .nemo-relay；这些文件需要手动迁移到受支持的用户级配置路径或显式配置路径。

不要替换单独出现的 flow、Flow 或 FlowError。它们可能是领域术语或有意保留的兼容名称。

语言清理

• Python：更新 pyproject.toml、导入语句、类型存根、集成包路径、附加项和原生模块名称。编辑源代码后，按照用户的包管理工作流重新生成或更新锁文件。
• Rust：更新 Cargo.toml 中的 crate 名称、工作区依赖、包引用，以及 use nemo_relay::... 导入语句。依赖发生变化时，让 Cargo 重新生成 Cargo.lock。
• Node.js：更新 package.json、工作区名称、package-lock 条目、原生扩展产物名称，以及从 nemo-relay-node 导入的内容。运行包管理器以更新锁文件。
• Go：更新 go.mod、导入路径、包声明、别名，以及 go/nemo_relay 下的任何本地目录布局。
• C FFI：更新头文件包含项、导出符号名称、状态和回调类型名称、宏常量、加载器路径以及下游绑定。
• 文档和示例：更新徽章、包安装命令、仓库链接、托管文档 URL、CLI 命令、配置路径和集成名称。

自动化辅助工具

首次编辑时使用 $SKILL_DIR/scripts/migrate_from_nemo_flow.py。该辅助工具：

• 除非传入 --write，否则以试运行模式运行
• 跳过常见的供应商、构建、缓存和生成目录
• 除非传入 --include-lockfiles，否则跳过锁文件
• 跳过符号链接和包含凭据的 dotenv 文件
• 检测项目本地的 .nemo-flow/config.toml 和 .nemo-flow/plugins.toml，保持不变，并报告这些文件需要手动迁移到受支持的用户配置路径或显式指定的配置路径
• 写入前要求通过 --confirm-root 再次指定经审核的目标根目录，并拒绝写入文件系统根目录或用户主目录
• 将写入和重命名操作绑定到经验证的目录句柄，且不跟随符号链接；在无法提供这些保证的平台上拒绝写入模式
• 使用原子且不覆盖现有路径的重命名；任何请求的修改失败时均以非零状态码退出
• 可通过 --rename-paths 报告或执行路径重命名
• 仅重写明确的 NeMo Flow 标识符、包名、仓库名、配置路径、标头、环境变量和 FFI 类型前缀

该辅助工具不会将任意 JSON、YAML、TOML 或 INI 文件判定为机密文件。检查试运行报告中的每个配置文件。如果报告中的任何文件未经审核或包含凭据，请勿对该根目录使用 --write。请手动应用经审核的更改，并保持包含机密的文件不变，不要读取或显示其中的值。

调用辅助工具前，请设置可安全用于 shell 的绝对路径。将示例值替换为已解析的技能目录，以及源代码仓库或用户的目标项目：

SKILL_DIR="/resolved/absolute/path/to/nemo-relay-migrate-from-flow"
TARGET_PATH="/resolved/absolute/path/to/target-project"

python3 "$SKILL_DIR/scripts/migrate_from_nemo_flow.py" "$TARGET_PATH" --rename-paths
python3 "$SKILL_DIR/scripts/migrate_from_nemo_flow.py" "$TARGET_PATH" \
  --write --rename-paths --confirm-root "$TARGET_PATH"

只有在用户希望直接编辑锁文件时才使用 --include-lockfiles；否则，请使用 Cargo、uv/pip、npm 或 Go 工具重新生成锁文件。

验证

• 搜索剩余的明确 Flow 标识符： rg -n "NeMo Flow|NeMo-Flow|nemo_flow|nemo-flow|NEMO_FLOW|NemoFlow|nemo_flow\\.h|nemo_flow_"
• 针对每种受影响的语言部分运行对应测试。
• 对于 Rust 更改，运行 cargo test 或仓库的 Rust 测试流程。
• 对于 Python 更改，在目标环境中运行相关导入检查和测试。
• 对于 Node.js 更改，运行包安装、类型检查和包测试。
• 对于 Go 更改，在更新后的模块目录中运行 go test ./...。
• 对于仅涉及文档的迁移，如果站点导航、安装命令或 API 参考发生更改，请构建文档或检查链接。

相关技能

• nemo-relay-get-started
• nemo-relay-instrument-calls
• nemo-relay-debug-runtime-integration