---
name: numa-nacos
metadata:
  version: "1.1.0"
description: 通过 Numa 和 DevOps 平台管理或排查 Nacos 连接、实例凭据配置状态、namespace、默认路由及企业 MCP Router 绑定和健康。用户提到 Nacos 实例接入、空间路由、Registry 上游 502、Router 不可用或凭据轮换时使用。Skills/MCP 资源安装与发布交给 numa-cli；不将现有 Registry CLI 冒充通用 Nacos 配置中心或服务发现管理工具。
---

# Numa Nacos 连接与路由

## 加载基础 Skill（必读）

本 Skill 依赖同来源的 `numa-cli@1.4.1`。业务操作前先加载基础 Skill；缺失时按 [依赖恢复指引](references/cli-bootstrap.md) 询问用户是否立即安装，不静默安装。命令示例使用 npx，无需全局安装；执行时将示例中的 `latest` 换为基础 Skill 已确认的具体版本，同一任务沿用同一入口。

负责控制台 `/integrations/nacos/registry` 对应的基础设施能力。Nacos 服务发现入口是 `/integrations/nacos`，能力范围不同。当前兼容命令仍是 `npx -y @numa-tech/numa@latest registry instances/namespaces/router`，不是 `npx -y @numa-tech/numa@latest nacos`。

## 先核对边界

1. 运行 `npx -y @numa-tech/numa@latest --cli-version`、`npx -y @numa-tech/numa@latest auth status --json`、`npx -y @numa-tech/numa@latest config --show --json`，确认身份和平台环境。PRD API 为 `https://apps-gw-prd.mcisaas.com/mci-devops-platform`，issuer 为 `https://kc.mcisaas.com/auth/realms/numa-realm`，CLI client 为 `mcp-client`；上游 namespace 名不能用于推断或切换登录 realm。
2. 读取 `npx -y @numa-tech/numa@latest registry capabilities --json`。用平台支持的身份登录；不读 token 文件、不借用浏览器 cookie，不因 403 改用直连 Nacos 或其他凭据绕过授权。
3. 列出实例与空间，resolve 精确 namespace/instance 后检查健康。显式目标优先于项目、用户和 profile 默认；同名消歧，错误默认不得自动回退。记录 namespace ID/key、实例 code、环境、状态及乐观锁 version。
4. 平台基础设施管理要求 `mci-devops-platform` 所有的稳定 `mci-devops-platform-ops-admin` 身份，并由后端执行。Skills namespace 授权不等于实例管理权；不要通过修改 accessPolicy 为资源安装补权限。

命令见 [command-contract.md](references/command-contract.md)。先检查安装版本的 exact subcommand `--help`。现有 CLI 没有 Router 绑定写入或通用 Nacos 配置/服务管理命令时，使用已提供的控制台或已核实的受支持 API；若未具备能力，明确报告缺口，不编造命令。

## 管理连接、凭据和空间

- 创建前检查实例 code 和 namespace 路由，复用已有目标，不创建重复实例或猜测 namespace ID。更新前读取最新 version，省略凭据表示保留；变更前说明受影响的空间和资源连接。
- 平台管理 READER/MAINTAINER 两套凭据并加密存储，只读接口仅展示已配置标志。`LEGACY_BOTH` 是迁移状态；只有两套新凭据明确配置并验证后才完成迁移，不擅自清除旧凭据。
- 不向对话索取明文 secret、Nacos token 或密码。需要凭据轮换时使用平台安全写入界面，或用户已经准备好的受保护输入文件；不回显文件内容，不把内容放到命令参数、Git 或日志中。创建后确认 configured 标志和健康，不尝试读取保存的 secret。
- namespace allowlist 的 `*`、Admin API 启用、默认路由和空间访问策略具有较大影响，只按用户明确授权的目标变更；读取不是授权范围扩大的理由。
- 删除必须先检查依赖：实例不能仍绑定空间，空间删除可能影响资源和 Router；仅在精确目标获授权后使用 `--yes`。不要级联删除 Skills/MCP 来强行满足条件。

## Router 与故障定位

使用 inspect/health/reconcile 和审计区分平台到 Nacos、namespace 路由、Router 可用性、OAuth/绑定 client 等问题。`router reconcile` 当前返回对账快照，不应声称它自动修复了绑定或重启服务。

Router 管理校验专用机器角色与绑定 client；普通 Skills 使用权限不赋予 Router 管理能力。客户端连接、MCP 安装和本地 stdio bridge 交给 `$numa-cli`，只使用企业 Router，不能将 Nacos/下游地址交给客户端绕过治理。

上游 502：保留脱敏 request ID，检查 namespace health 和实例状态；仅在用户授权且环境确认时读取集群日志。报告根因需要服务端证据，不能由 502 推断“密码错误”并盲目轮换。更新超时后先回读目标版本、状态与审计，确认未生效才重试。

## 交付

报告目标平台环境、instance code、namespace ID/key、配置版本、连接和 Router 健康、变更影响及脱敏错误/request ID。通过当前 CLI 与 capabilities 的实际 API 契约访问 Skills/Nacos；不要硬编码已废弃的 `/api/v1/ai-registry/**` 路径。`aiRegistry` 配置字段与 `registry` CLI 名称可能仍为兼容契约，不由 Skill 擅自重命名。