@numa-tech/numa 1.12.8 → 1.12.11

package/README.md

@@ -10,6 +10,7 @@
 - 包含 Realm 角色、Client 角色和用户组的个人信息页；
 - 使用服务端托管的 Codex 账号启动官方 Codex CLI，客户端不保存 refresh token；
 - 通过平台授权代理发现、治理并安装私有 Nacos Skills 与 MCP Servers；
+- 通过可恢复的 `app` 会话和统一 Web/API 契约创建新应用或录入存量仓库；
 - 通过领域化 `media` 命令安全调用平台托管的 TTS、视频、资产和素材库服务；
 - 兼容原有 stdio MCP 服务。
 
@@ -34,10 +35,10 @@ npm config set @numa-tech:registry=https://registry.npmjs.org/
 ```
 
 脚本会先检查 Git 工作区干净、当前分支与 upstream 完全同步，再于修改版本号之前检查公共
-npm 身份以及 `@tokensrc`、`@numa-tech` scope 权限。使用验证器 App 的
-本地交互发布会在公共 npm 推送前隐藏输入 6 位 OTP，并显式传给 `npm publish`；
-使用带 bypass 2FA 权限的 granular token 时直接回车即可。非交互环境可以临时提供
-`NUMA_PUBLIC_NPM_OTP`，更推荐使用 bypass 2FA granular token 或 npm trusted publishing。
+npm 身份以及 `@tokensrc`、`@numa-tech` scope 权限。发布认证默认完全交给 npm 处理；
+需要时 npm 会启动自己的浏览器认证或 2FA 流程，脚本不会额外询问 OTP。也可以临时通过
+`NUMA_PUBLIC_NPM_OTP` 显式提供 6 位 OTP；自动化发布更推荐使用带 bypass 2FA 权限的
+granular token 或 npm trusted publishing。
 
 首次从本机发布公共包，或公共登录已经过期时，先运行：
 
@@ -188,10 +189,13 @@ numa config \
 | `numa registry instances list/create/update/delete` | 需登录 | 管理数据库中的 Nacos 实例和 OIDC 配置；写操作需要 Registry admin |
 | `numa registry namespaces list/resolve/check/create/update/delete` | 需登录 | 管理多实例 namespace 路由与跨集群默认项；写操作需要 Registry admin |
 | `numa registry capabilities/init/lock/sync/upgrade` | 需登录 | 读取授权边界并以可提交的 manifest/lock 确定性安装 |
-| `numa registry skill list/inspect/install/upload/...` | 需登录 | 发现、安装和治理 Nacos Skills；服务端按团队、角色和生命周期授权 |
-| `numa registry mcp list/inspect/install/bridge/...` | 需登录 | 通过企业 Router 安装/桥接 MCP，并维护版本、标签和工具状态 |
+| `numa skills list/inspect/install/upload/...` | 需登录 | 发现、安装和治理 Nacos Skills；服务端按团队、角色和生命周期授权 |
+| `numa mcp list/inspect/install/bridge/...` | 需登录 | 通过企业 Router 安装/桥接 MCP，并维护版本、标签和工具状态 |
 | `numa registry approvals/router/audit` | 需登录 | 两人制发布、Router 健康/对账和追加式审计 |
 | `numa registry tui` | 需登录 | 打开 namespace、Skills、MCP、审批、Router、审计全屏工作台 |
+| `numa app onboard/apply/resume/inspect/list/tui` | 需登录 | 创建新应用、录入存量应用并恢复服务端入驻会话 |
+| `numa app options` | 需登录 | 查询应用归属所需的团队、系统、业务域和环境 ID |
+| `numa app candidate list/inspect/preview/review/adopt` | 需登录 | 审查应用发现候选并确认收录，服务端执行最终管理员授权和审计 |
 | `numa media capabilities` | 需登录 | 查询媒体 API、Provider 和版本能力 |
 | `numa media tts submit` | 需登录 | 提交 TTS 异步任务 |
 | `numa media video submit` | 需登录 | 提交视频生成异步任务 |
@@ -320,7 +324,8 @@ SSRF 安全策略仍由 `AI_REGISTRY_ALLOWED_UPSTREAM_HOSTS`、
 `AI_REGISTRY_ALLOWED_TOKEN_HOSTS` 控制，allow-list 为空时 fail closed；HTTP 只可通过
 `AI_REGISTRY_ALLOW_HTTP=true` 用于开发环境。
 
-Nacos 实例文件示例（凭据字段仅写入，实际字段以平台 capability/API revision 为准）：
+Nacos 实例文件示例（凭据字段仅写入，实际字段以平台 capability/API revision 为准）。完整的
+用户名密码认证模板见 `examples/ai-registry/nacos-instance.username-password.example.json`：
 
 ```json
 {
@@ -387,18 +392,18 @@ numa registry lock --json
 numa registry sync --json
 numa registry upgrade release-helper --json
 
-numa registry skill list --namespace team-ai --search deploy --json
-numa registry skill inspect release-helper --namespace team-ai --json
-numa registry skill install release-helper \
+numa skills list --namespace team-ai --search deploy --json
+numa skills inspect release-helper --namespace team-ai --json
+numa skills install release-helper \
   --namespace team-ai --agent cursor --scope project --label latest --json
 
-numa registry mcp list --namespace team-ai --json
-numa registry mcp inspect internal-docs --namespace team-ai --json
-numa registry mcp install internal-docs \
+numa mcp list --namespace team-ai --json
+numa mcp inspect internal-docs --namespace team-ai --json
+numa mcp install internal-docs \
   --namespace team-ai --instance cluster-b --agent claude --scope project --transport remote --json
 
 # 仅供 stdio Agent；复用 Numa 登录/刷新连接 Router
-numa registry mcp bridge --namespace team-ai
+numa mcp bridge --namespace team-ai
 
 # 也可使用终端交互界面
 numa registry tui
@@ -407,7 +412,7 @@ numa registry tui
 两人制发布生命周期：
 
 ```bash
-numa registry skill upload ./release-helper.zip \
+numa skills upload ./release-helper.zip \
   --namespace team-ai --target-version 1.0.0 --json
 numa registry approvals submit skill release-helper \
   --namespace team-ai --resource-version 1.0.0 --reason "scanner passed" --json
@@ -442,7 +447,7 @@ capability 发布且健康的企业 Router，不安装 Nacos 中的下游 endpoi
 | OpenClaw | `.openclaw/skills` | 调用官方 `openclaw mcp set`，仅 user scope |
 
 ChatGPT 不能启动本地 stdio bridge；它直接连接企业 Router 的远程 HTTPS OAuth resource。
-其他只支持 stdio 的 Agent 可运行 `numa registry mcp bridge`，由 Numa 获取/刷新用户 Token
+其他只支持 stdio 的 Agent 可运行 `numa mcp bridge`，由 Numa 获取/刷新用户 Token
 并只发送给 Router，不向 Nacos 或下游 MCP 透传。ChatGPT workspace 仍需管理员按计划和
 RBAC 开启 Developer mode。
 
@@ -451,6 +456,125 @@ RBAC 开启 Developer mode。
 Nacos token、绕过 403 或未经确认覆盖本地配置。对应场景评测在
 `skills/numa-ai-registry/evals/evals.json`。
 
+## 应用创建与存量录入
+
+`numa app` 使用 platform profile 的 `platform` service 和现有 `mcp-client` Keycloak 会话调用
+`/api/v1/application-onboarding`。Web、CLI 和 TUI 共享服务端 `sessionNo`、乐观锁 `revision`、
+`planHash` 和单调递增的 event sequence；CLI 只展示服务端状态，不会在本地推断任务已完成。
+
+交互终端直接运行 `numa app onboard` 会打开 Ink TUI，并可在同一服务端草稿中完成
+`MODE → BASIC_INFORMATION → OWNERSHIP → SOURCE_CONTROL → TECHNOLOGY → STANDARDIZATION → DELIVERY → REVIEW → EXECUTION`
+九步。`[` / `]` 切换步骤（切换时保存 `revision` 与稳定 `currentStep`），方向键选择字段和目录项，
+`Enter` / `e` 编辑，`s` 保存；`REVIEW` 中先按 `p` 查看阻断、警告与 `planHash`，再按 `a`、`y`
+二次确认执行。目录接口不可用时仍可手工输入实体 ID；仓库 Provider 返回 501 时会明确提示手工输入
+稳定 `externalId` 与 `expectedHead`，不会把 URL 或凭据写入草稿。
+
+非交互、CI 和 AI 调用必须提供 `--spec`。spec 使用 `schemaVersion: 1`，不得包含 Token、密码、
+SCM credential 或 secret ref：
+
+```bash
+# 只保存草稿并预检，不产生仓库、分支或 Jenkins 等外部副作用
+numa app onboard --spec onboarding.json --plan --json
+
+# 接续 Web/TUI 中已保存的同一草稿；使用服务端最新 revision，避免静默覆盖
+numa app onboard --session <session-no> --spec onboarding.json --plan --json
+
+# 一步式使用服务端最新 planHash 提交异步执行；幂等键为必填
+numa app onboard \
+  --spec onboarding.json \
+  --apply \
+  --idempotency-key app-order-20260819 \
+  --json
+```
+
+自动化更推荐先运行 `--plan`、保存返回的 `session_no`，再明确提交该会话。这样即使网络在
+apply 返回前中断，也可以对同一会话复用原幂等键，而不会重新创建草稿：
+
+```bash
+numa app apply <session-no> --idempotency-key app-order-20260819 --json
+numa app inspect <session-no> --watch --after-sequence 42
+numa app resume <session-no> --json
+numa app tui --session <session-no>
+```
+
+`inspect --watch` 每次都从最后已确认的 sequence 补拉，断线重连不会重复展示事件；Ctrl+C
+只停止本地观察，不取消服务端任务。取消必须显式执行 `numa app cancel <session-no> --yes`，
+且不会回滚已经完成的外部副作用。完整 spec schema、状态机和入驻流程由 DevOps 平台的
+Application Onboarding 契约定义。
+
+SCM 目录和连接诊断使用同一身份。仓库查询支持服务端 search/cursor 分页，返回稳定的
+`externalId`、`defaultBranch`、`headRevision`；向导选中仓库后会把 `headRevision` 固定为
+`expectedHead`。HTTP 429 会保留服务端 `Retry-After` 诊断，Provider 未安装（501）时 TUI
+明确退回手工填写稳定标识：
+
+```bash
+numa app scm list --provider codeup --json
+numa app scm inspect codeup-main --repositories --search order --limit 50 --json
+numa app scm inspect codeup-main --repositories --cursor '<next-cursor>' --limit 50 --json
+numa app scm probe codeup-main --json
+```
+
+SCM 管理接口位于 `/api/v1/admin/scm-connections`，最终权限始终由网关和后端按 canonical
+Client Role 校验。metadata JSON 只允许 provider、URL、组织、auth type 以及服务端托管的
+`aliyunAccountId`/`aliyunAssumeRoleId` 引用；Numa 不接收云 AK。CODEUP 必须引用
+`aliyunAccountId`，没有 access token 时直接使用服务端 Aliyun identity，不写入空 credential。
+GitHub App/PAT 或可选 Codeup access token 只能从 owner-only 文件或重定向 stdin 读取，禁止放在
+argv、环境变量和 metadata JSON 中，且不会出现在输出或错误中：
+
+```bash
+numa app scm create --input codeup.json --json
+chmod 600 github-app.private.json
+numa app scm create --input github.json --credential-file github-app.private.json --json
+numa app scm rotate github-main --revision 4 --credential-stdin --yes --json < github-pat.private.json
+numa app scm disable old-codeup --revision 7 --yes --json
+```
+
+## 应用候选收录
+
+Jenkins 发现任务只生成可审查的应用候选，不会直接创建正式应用。Numa 对外把后续动作称为
+“候选收录”（`adopt`）：候选可能创建新应用，也可能合并到已有应用，同时确认候选携带的
+Jenkins Job 绑定。“转正”容易与 npm 发布晋级、环境晋级或人员状态混淆，因此不作为 CLI
+命令和用户提示；服务端继续使用既有 `/promote` API 与审计事件，保持兼容。
+
+先查询候选和所需目录 ID：
+
+```bash
+numa app options team --search platform --json
+numa app options system --json
+numa profile --json
+
+numa app candidate list --status new --json
+numa app candidate inspect 123 --json
+```
+
+`candidate list` 仅返回 `APPLICATION` 类型候选；列表中的 `id` 是后续操作使用的稳定候选 ID，
+不等同于 Jenkins Job ID 或 Build Number。Job ID、环境层及绑定证据来自候选的
+`proposed_relationships`，CLI 不要求用户重复填写。
+
+收录必须先通过服务端预检，并在写入时显式确认：
+
+```bash
+numa app candidate preview 123 --json
+numa app candidate adopt 123 --yes --json
+
+# 最多批量处理 200 个候选；任一预检阻断时不会提交本批收录
+numa app candidate adopt 123 124 --yes --json
+```
+
+如果候选缺少名称、环境证据不明确，或需要合并到已有应用，先 `inspect` 获取完整候选与
+`version`，再用完整 review JSON 和乐观锁版本提交修复：
+
+```bash
+numa app candidate review 123 \
+  --input candidate-review.json \
+  --revision 4 \
+  --json
+```
+
+review JSON 必须包含 `operation`、`proposedFields`、`proposedRelationships` 和 `confidence`，
+且禁止嵌入凭据或 secret 引用。最终 Scope、候选状态、Job 时效性、CREATE/MERGE 冲突、逐候选
+事务和审计记录均由网关及 DevOps 后端校验，CLI 本地隐藏或显示命令不构成授权。
+
 ## Jenkins 流水线与生产操作
 
 `numa pipeline` 通过平台授权代理查询和操作 Jenkins。CLI 不接收 Jenkins 用户名、Token 或

package/dist/ai-registry/commands.js

@@ -216,8 +216,8 @@ export function registerAiRegistryCommands(program) {
         await new AiRegistryClient(loadConfig("aiRegistry")).deleteNamespace(namespaceId);
         await output(command, { ok: true, deleted: { id: namespaceId } }, `namespace 已删除: ${namespaceId}`);
     }), ["numa registry namespaces delete 7 --yes --json"]);
-    const skill = registry.command("skill").description("查看、上传、治理和安装 Nacos Skills");
-    addExamples(skill.command("list")
+    const skills = program.command("skills").description("查看、上传、治理和安装 Nacos Skills");
+    addExamples(skills.command("list")
         .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .option("-q, --search <text>", "搜索关键词")
@@ -233,8 +233,8 @@ export function registerAiRegistryCommands(program) {
         });
         const items = pageItems(result);
         await output(command, { ok: true, namespace: targetNamespace, skills: result }, items.map((item, index) => itemName(item, `skill-${index + 1}`)).join("\n") || "没有找到 Skill");
-    }), ["numa registry skill list --namespace team-ai --search deploy --json"]);
-    addExamples(skill.command("inspect <name>")
+    }), ["numa skills list --namespace team-ai --search deploy --json"]);
+    addExamples(skills.command("inspect <name>")
         .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .action(async (name, options, command) => {
@@ -242,8 +242,8 @@ export function registerAiRegistryCommands(program) {
         const targetNamespace = await resolveNamespace(client, options);
         const result = await client.getSkill(targetNamespace.id, name);
         await output(command, { ok: true, namespace: targetNamespace, skill: result }, JSON.stringify(sanitizeRegistryOutput(result), null, 2));
-    }), ["numa registry skill inspect release-helper --namespace team-ai --json"]);
-    addExamples(skill.command("install <name>")
+    }), ["numa skills inspect release-helper --namespace team-ai --json"]);
+    addExamples(skills.command("install <name>")
         .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .requiredOption("-a, --agent <agent>", "chatgpt|codex|claude|cursor|workbuddy|openclaw|agents|custom")
@@ -270,10 +270,10 @@ export function registerAiRegistryCommands(program) {
         }, version, download.sha256, result.installedPath);
         await output(command, { ok: true, namespace: context.namespace, resolvedVersion: version, download: { sha256: download.sha256, fileName: download.fileName }, installation: result, lock }, `已安装 ${name}@${version}: ${result.installedPath}${result.backupPath ? `\n原版本备份: ${result.backupPath}` : ""}`);
     }), [
-        "numa registry skill install release-helper --namespace team-ai --agent claude",
-        "numa registry skill install release-helper --namespace team-ai --instance cluster-b --agent cursor --scope user --label latest --json"
+        "numa skills install release-helper --namespace team-ai --agent claude",
+        "numa skills install release-helper --namespace team-ai --instance cluster-b --agent cursor --scope user --label latest --json"
     ]);
-    addExamples(skill.command("draft <name>")
+    addExamples(skills.command("draft <name>")
         .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .option("--from-version <semver>", "从在线版本创建草稿")
@@ -282,8 +282,8 @@ export function registerAiRegistryCommands(program) {
         const targetNamespace = await resolveNamespace(client, options);
         const result = await client.createSkillDraft(targetNamespace.id, name, { baseVersion: options.fromVersion });
         await output(command, { ok: true, namespace: targetNamespace, result }, `Skill ${name} 草稿已创建`);
-    }), ["numa registry skill draft release-helper --from-version 1.0.0 --json"]);
-    addExamples(skill.command("upload <zip>")
+    }), ["numa skills draft release-helper --from-version 1.0.0 --json"]);
+    addExamples(skills.command("upload <zip>")
         .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .option("--overwrite", "覆盖现有 draft")
@@ -294,9 +294,9 @@ export function registerAiRegistryCommands(program) {
         const targetNamespace = await resolveNamespace(client, options);
         const result = await client.uploadSkill(targetNamespace.id, zip, options);
         await output(command, { ok: true, namespace: targetNamespace, result }, `Skill ZIP 已上传到 ${targetNamespace.displayName}`);
-    }), ["numa registry skill upload ./release-helper.zip --namespace team-ai --target-version 1.0.0 --json"]);
+    }), ["numa skills upload ./release-helper.zip --namespace team-ai --target-version 1.0.0 --json"]);
     for (const action of ["submit", "publish", "online", "offline"]) {
-        addExamples(skill.command(`${action} <name>`)
+        addExamples(skills.command(`${action} <name>`)
             .option("-n, --namespace <key>", "namespaceKey")
             .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
             .option("--version <semver>", "版本（publish 必填）")
@@ -307,9 +307,9 @@ export function registerAiRegistryCommands(program) {
             const targetNamespace = await resolveNamespace(client, options);
             const result = await client.skillAction(targetNamespace.id, name, action, { version: options.version });
             await output(command, { ok: true, namespace: targetNamespace, result }, `Skill ${name}: ${action} 完成`);
-        }), [`numa registry skill ${action} release-helper --namespace team-ai${action === "publish" ? " --version 1.0.0" : ""}`]);
+        }), [`numa skills ${action} release-helper --namespace team-ai${action === "publish" ? " --version 1.0.0" : ""}`]);
     }
-    addExamples(skill.command("scope <name> <scope>")
+    addExamples(skills.command("scope <name> <scope>")
         .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .action(async (name, scope, options, command) => {
@@ -320,8 +320,8 @@ export function registerAiRegistryCommands(program) {
         const targetNamespace = await resolveNamespace(client, options);
         const result = await client.skillAction(targetNamespace.id, name, "scope", { scope: normalized });
         await output(command, { ok: true, namespace: targetNamespace, result }, `Skill ${name} scope 已更新为 ${normalized}`);
-    }), ["numa registry skill scope release-helper PRIVATE --namespace team-ai"]);
-    addExamples(skill.command("tags <name> <tags...>")
+    }), ["numa skills scope release-helper PRIVATE --namespace team-ai"]);
+    addExamples(skills.command("tags <name> <tags...>")
         .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .action(async (name, tags, options, command) => {
@@ -333,8 +333,8 @@ export function registerAiRegistryCommands(program) {
         const targetNamespace = await resolveNamespace(client, options);
         const result = await client.skillAction(targetNamespace.id, name, "biz-tags", { bizTags: normalized });
         await output(command, { ok: true, namespace: targetNamespace, result }, `Skill ${name} tags 已更新`);
-    }), ["numa registry skill tags release-helper deploy java --namespace team-ai --json"]);
-    addExamples(skill.command("labels <name> <labels...>")
+    }), ["numa skills tags release-helper deploy java --namespace team-ai --json"]);
+    addExamples(skills.command("labels <name> <labels...>")
         .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .requiredOption("--version <semver>", "绑定标签的精确版本")
@@ -346,8 +346,8 @@ export function registerAiRegistryCommands(program) {
         const targetNamespace = await resolveNamespace(client, options);
         const result = await client.skillAction(targetNamespace.id, name, "labels", { version: options.version, labels: normalized });
         await output(command, { ok: true, namespace: targetNamespace, result }, `Skill ${name}@${options.version} labels 已更新`);
-    }), ["numa registry skill labels release-helper latest stable --version 1.2.0 --json"]);
-    addExamples(skill.command("delete <name>")
+    }), ["numa skills labels release-helper latest stable --version 1.2.0 --json"]);
+    addExamples(skills.command("delete <name>")
         .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .option("--yes", "确认不可逆的远端删除")
@@ -358,8 +358,8 @@ export function registerAiRegistryCommands(program) {
         const targetNamespace = await resolveNamespace(client, options);
         const result = await client.skillAction(targetNamespace.id, name, "delete");
         await output(command, { ok: true, namespace: targetNamespace, result }, `Skill ${name} 已从远端删除`);
-    }), ["numa registry skill delete obsolete-skill --namespace team-ai --yes --json"]);
-    const mcp = registry.command("mcp").description("查看、维护和安装 Nacos MCP Servers");
+    }), ["numa skills delete obsolete-skill --namespace team-ai --yes --json"]);
+    const mcp = program.command("mcp").description("查看、维护和安装 Nacos MCP Servers");
     addExamples(mcp.command("list")
         .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
@@ -375,7 +375,7 @@ export function registerAiRegistryCommands(program) {
             pageSize: positiveInteger(options.limit, "limit", 20, 100)
         });
         await output(command, { ok: true, namespace: targetNamespace, mcpServers: result }, pageItems(result).map((item, index) => itemName(item, `mcp-${index + 1}`)).join("\n") || "没有找到 MCP Server");
-    }), ["numa registry mcp list --namespace team-ai --json"]);
+    }), ["numa mcp list --namespace team-ai --json"]);
     addExamples(mcp.command("inspect <name>")
         .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
@@ -385,7 +385,7 @@ export function registerAiRegistryCommands(program) {
         const targetNamespace = await resolveNamespace(client, options);
         const result = await client.getMcpServer(targetNamespace.id, name, options.version);
         await output(command, { ok: true, namespace: targetNamespace, mcpServer: result }, JSON.stringify(sanitizeRegistryOutput(result), null, 2));
-    }), ["numa registry mcp inspect internal-docs --namespace team-ai --json"]);
+    }), ["numa mcp inspect internal-docs --namespace team-ai --json"]);
     addExamples(mcp.command("install <name>")
         .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
@@ -421,14 +421,14 @@ export function registerAiRegistryCommands(program) {
             ? `已生成 ChatGPT MCP 安装指引: ${result.endpoint}\n${result.manualSteps.map((step, index) => `${index + 1}. ${step}`).join("\n")}`
             : `MCP ${name} 已安装${result.configPath ? `: ${result.configPath}` : "（由客户端 CLI 管理）"}${result.backupPath ? `\n原配置备份: ${result.backupPath}` : ""}`;
         await output(command, { ok: true, namespace: context.namespace, resolvedVersion: version, installation: result, lock }, textResult);
-    }), ["numa registry mcp install internal-docs --namespace team-ai --agent cursor"]);
+    }), ["numa mcp install internal-docs --namespace team-ai --agent cursor"]);
     addExamples(mcp.command("bridge").description("把 namespace 企业 Router 桥接为本地 stdio MCP")
         .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .option("--workspace <path>", "项目目录")
         .action(async (options) => {
         await runMcpBridge(new AiRegistryClient(loadConfig("aiRegistry")), options);
-    }), ["numa registry mcp bridge --namespace team-ai"]);
+    }), ["numa mcp bridge --namespace team-ai"]);
     for (const action of ["online", "offline"]) {
         addExamples(mcp.command(`${action} <name>`)
             .option("-n, --namespace <key>", "namespaceKey")
@@ -439,7 +439,7 @@ export function registerAiRegistryCommands(program) {
             const targetNamespace = await resolveNamespace(client, options);
             const result = await client.mcpAction(targetNamespace.id, name, action, { version: options.version });
             await output(command, { ok: true, namespace: targetNamespace, result }, `MCP ${name}: ${action} 完成`);
-        }), [`numa registry mcp ${action} internal-docs --version 1.0.0 --json`]);
+        }), [`numa mcp ${action} internal-docs --version 1.0.0 --json`]);
     }
     addExamples(mcp.command("tags <name> <tags...>")
         .option("-n, --namespace <key>", "namespaceKey")
@@ -452,7 +452,7 @@ export function registerAiRegistryCommands(program) {
         const targetNamespace = await resolveNamespace(client, options);
         const result = await client.mcpAction(targetNamespace.id, name, "biz-tags", { bizTags: normalized });
         await output(command, { ok: true, namespace: targetNamespace, result }, `MCP ${name} tags 已更新`);
-    }), ["numa registry mcp tags internal-docs knowledge search --json"]);
+    }), ["numa mcp tags internal-docs knowledge search --json"]);
     const tools = mcp.command("tool").description("启用或禁用 MCP 工具");
     for (const action of ["enable", "disable"]) {
         addExamples(tools.command(`${action} <mcp-name> <tool-name>`)
@@ -465,7 +465,7 @@ export function registerAiRegistryCommands(program) {
             const version = options.version == null ? undefined : nonnegativeInteger(options.version, "version");
             const result = await client.setMcpToolEnabled(targetNamespace.id, mcpName, toolName, action === "enable", version);
             await output(command, { ok: true, namespace: targetNamespace, result }, `MCP tool ${mcpName}/${toolName}: ${action} 完成`);
-        }), [`numa registry mcp tool ${action} internal-docs search --version 3 --json`]);
+        }), [`numa mcp tool ${action} internal-docs search --version 3 --json`]);
     }
     addExamples(mcp.command("create <json>")
         .option("-n, --namespace <key>", "namespaceKey")
@@ -475,7 +475,7 @@ export function registerAiRegistryCommands(program) {
         const targetNamespace = await resolveNamespace(client, options);
         const result = await client.createMcpServer(targetNamespace.id, await readObject(file));
         await output(command, { ok: true, namespace: targetNamespace, result }, "MCP create 完成");
-    }), ["numa registry mcp create ./mcp.json --namespace team-ai --json"]);
+    }), ["numa mcp create ./mcp.json --namespace team-ai --json"]);
     addExamples(mcp.command("update <name> <json>")
         .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
@@ -484,7 +484,7 @@ export function registerAiRegistryCommands(program) {
         const targetNamespace = await resolveNamespace(client, options);
         const result = await client.updateMcpServer(targetNamespace.id, name, await readObject(file));
         await output(command, { ok: true, namespace: targetNamespace, result }, "MCP update 完成");
-    }), ["numa registry mcp update internal-docs ./mcp.json --namespace team-ai --json"]);
+    }), ["numa mcp update internal-docs ./mcp.json --namespace team-ai --json"]);
     addExamples(mcp.command("delete <name>")
         .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
@@ -497,7 +497,7 @@ export function registerAiRegistryCommands(program) {
         const targetNamespace = await resolveNamespace(client, options);
         const result = await client.deleteMcpServer(targetNamespace.id, name, options.version);
         await output(command, { ok: true, namespace: targetNamespace, result }, `MCP ${name} 已从远端删除`);
-    }), ["numa registry mcp delete obsolete --namespace team-ai --yes --json"]);
+    }), ["numa mcp delete obsolete --namespace team-ai --yes --json"]);
     const approvals = registry.command("approvals").description("查看、审核和发布两人制 release request");
     addExamples(approvals.command("submit <type> <name>")
         .option("-n, --namespace <key>", "namespaceKey")