nodeskclaw / rules

# Runtime / Compute Provider 感知规则

## 核心原则

**所有涉及实例基础设施操作的代码，必须同时考虑 runtime 类型（OpenClaw / Hermes / ...）和 compute provider（K8s / Docker / Process）的差异。禁止硬编码任何 runtime 或 provider 特定的值。**

## Runtime 差异

不同 runtime 的基础参数不同，必须从 `RuntimeSpec`（`RUNTIME_REGISTRY`）查取：

| 参数 | OpenClaw | Hermes |
|------|----------|--------|
| Gateway 端口 | 18789 | 8642 |
| 数据目录 | `/root/.openclaw` | `/root/.hermes` |
| 配置文件格式 | JSON (JSONC) | YAML |
| 镜像仓库 key | `image_registry` | `image_registry_hermes` |

### 必须做

- **端口、数据目录、配置路径等 runtime 相关值必须从 `RuntimeSpec` 查取**，通过 `RUNTIME_REGISTRY.get(runtime_id)` 获取
- **新增 runtime 相关字段时**，必须在 `RuntimeSpec` dataclass 中添加字段，并在 `_register_builtins()` 中为所有已注册 runtime 设置值
- **端口传递链路**：`RuntimeSpec.gateway_port` -> `InstanceComputeConfig.gateway_port` -> 各 provider 使用
- **新增 runtime 时**，必须在 `_register_builtins()` 中注册完整的 `RuntimeSpec`，所有字段都要填写

### 严禁

- **禁止硬编码端口号**（如 `18789`、`8080`）在 provider 或 deploy 逻辑中
- **禁止硬编码数据目录路径**（如 `/root/.openclaw`）在通用逻辑中
- **禁止假设所有 runtime 行为一致**——端口、配置格式、日志路径、健康检查方式都可能不同

## Compute Provider 差异

同一操作在不同 provider 下的实现方式不同：

| 操作 | K8s | Docker | Process |
|------|-----|--------|---------|
| 文件访问 | `kubectl exec` (PodFS) | 宿主机路径 (DockerFS) | 直接本地路径 |
| 端口暴露 | Service + Ingress | Docker Compose ports | 直接绑定 |
| 日志获取 | `kubectl logs` | `docker logs` | stdout/stderr |
| 重启 | `kubectl rollout restart` | `docker compose restart` | 进程信号 |

### 必须做

- **新增文件系统操作时**，必须同时实现 `PodFS` 和 `DockerFS` 两套逻辑，保持接口签名和返回格式一致
- **新增 compute provider 操作时**，必须检查所有 provider 实现（`K8sAdapter`、`DockerComputeProvider`、`ProcessComputeProvider`）是否都已覆盖
- **接口方法签名变更时**，必须同步更新所有实现类

### 严禁

- **禁止只实现 K8s 路径**——Docker 和 Process provider 同样需要支持
- **禁止在通用 service 层假定 provider 类型**（如直接调用 `kubectl`），必须通过 `RemoteFS` 或 `ComputeProvider` 抽象层操作

## 自查清单

每次改动涉及实例操作时，必须自问：

1. **换个 runtime 还能跑吗？** 端口、路径、配置格式是否都从 RuntimeSpec 查取？
2. **换个 provider 还能跑吗？** K8s 实例能用，Docker 实例也能用吗？
3. **新增了 runtime 特有字段？** 是否已加到 `RuntimeSpec` 并为所有 runtime 设值？
4. **新增了文件系统操作？** `PodFS` 和 `DockerFS` 是否都实现了，签名和返回格式是否一致？

## 关键代码路径

| 组件 | 文件 |
|------|------|
| RuntimeSpec 定义与注册 | `nodeskclaw-backend/app/services/runtime/registries/runtime_registry.py` |
| ComputeConfig 定义 | `nodeskclaw-backend/app/services/runtime/compute/base.py` |
| K8s 部署 | `nodeskclaw-backend/app/services/deploy_service.py` (`_execute_deploy_inner`) |
| Docker 部署 | `nodeskclaw-backend/app/services/runtime/compute/docker_provider.py` |
| 文件系统抽象 | `nodeskclaw-backend/app/services/nfs_mount.py` (`PodFS` / `DockerFS`) |
| K8s 资源构建 | `nodeskclaw-backend/app/services/k8s/resource_builder.py` |