@numa-tech/numa 1.12.6 → 1.12.8

package/dist/ai-registry/commands.js

@@ -1,12 +1,16 @@
 import { readFile } from "node:fs/promises";
 import process from "node:process";
-import { cancel, confirm, isCancel, select, text } from "@clack/prompts";
 import { loadAppConfig } from "../app-config.js";
 import { loadConfig as loadPlatformConfig } from "../config.js";
 import { AiRegistryClient } from "./client.js";
+import { runMcpBridge } from "./bridge.js";
 import { AiRegistryError, sanitizeRegistryOutput } from "./errors.js";
-import { installMcpDefinition } from "./mcp-installer.js";
+import { installMcpClientDefinition, mcpDefinitionFromNacos } from "./mcp-installer.js";
+import { resolveRegistryNamespace } from "./namespace.js";
 import { installSkillArchive } from "./skill-installer.js";
+import { assertRouterHealth, lockRegistryWorkspace, portableInstallPath, resolveVersion, routerMcpDefinition, syncRegistryWorkspace } from "./sync.js";
+import { runRegistryTui } from "./tui.js";
+import { mergeMcpEntry, mergeSkillEntry, readRegistryLock, readRegistryManifest, registryWorkspaceAt, upsertLockResource, writeRegistryLock, writeRegistryManifest, canonicalSha256 } from "./workspace.js";
 // A selected profile must route this module independently from the platform API.
 const loadConfig = (..._args) => loadPlatformConfig("aiRegistry");
 function addExamples(command, examples) {
@@ -43,7 +47,10 @@ async function resolveInstance(client, value) {
     return matches[0];
 }
 async function resolveNamespace(client, options) {
-    return client.resolveNamespace(options.namespace, options.instance);
+    return (await resolveContext(client, options)).namespace;
+}
+async function resolveContext(client, options, requiredAction) {
+    return resolveRegistryNamespace(client, { ...options, requiredAction });
 }
 async function readObject(path) {
     try {
@@ -70,18 +77,86 @@ export function registerAiRegistryCommands(program) {
         .command("registry")
         .alias("ai-registry")
         .description("通过平台 Keycloak 授权安全管理私有 Nacos Skill 与 MCP Registry");
+    addExamples(registry.command("capabilities").description("列出当前用户可见 namespace、动作、Router 与客户端适配器")
+        .action(async (_options, command) => {
+        const result = await new AiRegistryClient(loadConfig("aiRegistry")).getCapabilities();
+        await output(command, { ok: true, capabilities: result }, result.namespaces.map((item) => `${item.namespaceKey}\t${item.environment}\t${item.router?.status ?? "NO_ROUTER"}\t${item.actions.join(",")}`).join("\n") || "没有可见 namespace");
+    }), ["numa registry capabilities --json"]);
+    addExamples(registry.command("init").description("创建可提交到版本库的 .numa/registry.json")
+        .requiredOption("-n, --namespace <key>", "namespaceKey")
+        .option("-i, --instance <id-or-code>", "显式绑定实例")
+        .option("--workspace <path>", "项目根目录", process.cwd())
+        .action(async (options, command) => {
+        const client = new AiRegistryClient(loadConfig("aiRegistry"));
+        const context = await resolveContext(client, options);
+        const files = registryWorkspaceAt(options.workspace);
+        const existing = await readRegistryManifest(options.workspace, false);
+        if (existing)
+            throw new AiRegistryError(`Registry manifest already exists at ${existing.files.manifestPath}.`, "ai_registry_manifest_exists");
+        await writeRegistryManifest(files, {
+            schemaVersion: 1,
+            namespaceKey: context.namespace.namespaceKey,
+            instanceCode: context.namespace.instanceCode,
+            skills: [],
+            mcpServers: []
+        });
+        await output(command, { ok: true, manifestPath: files.manifestPath, namespace: context.namespace }, `已创建 ${files.manifestPath}`);
+    }), ["numa registry init --namespace team-ai"]);
+    addExamples(registry.command("lock").description("解析 manifest 的标签并写入精确版本与 SHA-256")
+        .option("-n, --namespace <key>", "覆盖项目 namespace")
+        .option("-i, --instance <id-or-code>", "显式绑定实例")
+        .option("--workspace <path>", "项目目录", process.cwd())
+        .action(async (options, command) => {
+        const client = new AiRegistryClient(loadConfig("aiRegistry"));
+        const context = await resolveContext(client, options);
+        const result = await lockRegistryWorkspace(client, context, options.workspace);
+        await output(command, { ok: true, namespace: context.namespace, lock: result.lock, lockPath: result.files.lockPath }, `已锁定 ${result.lock.resources.length} 个资源: ${result.files.lockPath}`);
+    }), ["numa registry lock --json"]);
+    addExamples(registry.command("sync").description("严格按 lock 文件安装；不会解析标签或隐式升级")
+        .option("-n, --namespace <key>", "覆盖项目 namespace")
+        .option("-i, --instance <id-or-code>", "显式绑定实例")
+        .option("--workspace <path>", "项目目录", process.cwd())
+        .option("--force", "重新安装并保留适配器备份")
+        .action(async (options, command) => {
+        const client = new AiRegistryClient(loadConfig("aiRegistry"));
+        const context = await resolveContext(client, options);
+        const result = await syncRegistryWorkspace(client, context, options.workspace, { force: options.force });
+        await output(command, { ok: true, namespace: context.namespace, lock: result.lock, lockPath: result.files.lockPath }, `同步完成: ${result.lock.resources.filter((item) => item.install.status === "INSTALLED").length}/${result.lock.resources.length}`);
+    }), ["numa registry sync --json"]);
+    addExamples(registry.command("upgrade [names...]").description("显式重新解析跟踪标签、更新 lock 并同步")
+        .option("-n, --namespace <key>", "覆盖项目 namespace")
+        .option("-i, --instance <id-or-code>", "显式绑定实例")
+        .option("--workspace <path>", "项目目录", process.cwd())
+        .option("--no-sync", "只更新 lock，不安装")
+        .option("--force", "重新安装并保留适配器备份")
+        .action(async (names, options, command) => {
+        const client = new AiRegistryClient(loadConfig("aiRegistry"));
+        const context = await resolveContext(client, options);
+        const project = await readRegistryManifest(options.workspace, true);
+        if (!project)
+            throw new AiRegistryError("Registry manifest is required.", "ai_registry_manifest_not_found");
+        const previous = await readRegistryLock(project.files, false);
+        const knownNames = new Set([...project.manifest.skills, ...project.manifest.mcpServers].map((item) => item.name));
+        const selected = new Set(names.length ? names : [...knownNames]);
+        for (const name of selected)
+            if (!knownNames.has(name))
+                throw new AiRegistryError(`Manifest has no resource named ${name}.`, "ai_registry_input_invalid");
+        const result = await lockRegistryWorkspace(client, context, options.workspace, { previous, upgradeNames: selected });
+        const synced = options.sync ? await syncRegistryWorkspace(client, context, options.workspace, { force: options.force }) : result;
+        await output(command, { ok: true, namespace: context.namespace, upgraded: [...selected].sort(), lock: synced.lock, lockPath: synced.files.lockPath }, `已升级 ${selected.size} 个资源${options.sync ? "并同步安装" : ""}`);
+    }), ["numa registry upgrade", "numa registry upgrade release-helper --no-sync --json"]);
     addExamples(registry.command("tui").description("交互式浏览、安装和治理 Skill/MCP").action(runTui), ["numa registry tui"]);
     const instances = registry.command("instances").alias("services").description("管理数据库中的 Nacos 集群实例与 OIDC 配置");
     addExamples(instances.command("list").description("列出 Nacos 实例（不返回密文或明文 secret）").action(async (_options, command) => {
         const result = await new AiRegistryClient(loadConfig("aiRegistry")).listInstances();
         await output(command, { ok: true, instances: result }, result.map((item) => `${item.id}\t${item.code}\t${item.status}\t${item.credentialConfigured ? "credential-ready" : "credential-missing"}\t${item.displayName}`).join("\n") || "没有配置 Nacos 实例");
     }), ["numa registry instances list --json"]);
-    addExamples(instances.command("create <json>").description("创建实例；clientSecret 仅写入平台数据库密文表")
+    addExamples(instances.command("create <json>").description("创建实例；READER/MAINTAINER 凭据仅写入平台密文表")
         .action(async (file, _options, command) => {
         const result = await new AiRegistryClient(loadConfig("aiRegistry")).createInstance(await readObject(file));
         await output(command, { ok: true, instance: result }, `Nacos 实例已创建: ${result.id} ${result.code}`);
     }), ["numa registry instances create ./nacos-instance.json --json"]);
-    addExamples(instances.command("update <id-or-code> <json>").description("更新实例；JSON 必须包含当前 version，省略 clientSecret 表示保留")
+    addExamples(instances.command("update <id-or-code> <json>").description("更新实例；JSON 必须包含当前 version，省略某套凭据表示保留")
         .action(async (value, file, _options, command) => {
         const client = new AiRegistryClient(loadConfig("aiRegistry"));
         const instance = await resolveInstance(client, value);
@@ -143,7 +218,7 @@ export function registerAiRegistryCommands(program) {
     }), ["numa registry namespaces delete 7 --yes --json"]);
     const skill = registry.command("skill").description("查看、上传、治理和安装 Nacos Skills");
     addExamples(skill.command("list")
-        .requiredOption("-n, --namespace <key>", "namespaceKey")
+        .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .option("-q, --search <text>", "搜索关键词")
         .option("--page <number>", "页码", "1")
@@ -160,7 +235,7 @@ export function registerAiRegistryCommands(program) {
         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>")
-        .requiredOption("-n, --namespace <key>", "namespaceKey")
+        .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .action(async (name, options, command) => {
         const client = new AiRegistryClient(loadConfig("aiRegistry"));
@@ -169,7 +244,7 @@ export function registerAiRegistryCommands(program) {
         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>")
-        .requiredOption("-n, --namespace <key>", "namespaceKey")
+        .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .requiredOption("-a, --agent <agent>", "chatgpt|codex|claude|cursor|workbuddy|openclaw|agents|custom")
         .option("--scope <scope>", "project|user", "project")
@@ -180,19 +255,36 @@ export function registerAiRegistryCommands(program) {
         .option("--force", "备份并替换已有 Skill")
         .action(async (name, options, command) => {
         const client = new AiRegistryClient(loadConfig("aiRegistry"));
-        const targetNamespace = await resolveNamespace(client, options);
-        const download = await client.downloadSkill(targetNamespace.id, name, { version: options.version, label: options.label });
+        const context = await resolveContext(client, options);
+        const detail = await client.getSkill(context.namespace.id, name);
+        const trackedLabel = options.version ? undefined : options.label ?? "latest";
+        const version = resolveVersion(detail, options.version, trackedLabel, name);
+        const download = await client.downloadSkill(context.namespace.id, name, { version });
         const result = await installSkillArchive(download.bytes, {
             agent: skillAgent(options.agent), scope: installScope(options.scope), skillName: name,
             workspace: options.workspace, customRoot: options.customRoot, force: options.force
         });
-        await output(command, { ok: true, namespace: targetNamespace, download: { sha256: download.sha256, fileName: download.fileName }, installation: result }, `已安装 ${name}: ${result.installedPath}${result.backupPath ? `\n原版本备份: ${result.backupPath}` : ""}`);
+        const lock = await recordSkillInstallation(context, options.workspace, {
+            name, version: options.version, label: trackedLabel, agent: skillAgent(options.agent),
+            scope: installScope(options.scope), customRoot: options.customRoot
+        }, 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"
     ]);
+    addExamples(skill.command("draft <name>")
+        .option("-n, --namespace <key>", "namespaceKey")
+        .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
+        .option("--from-version <semver>", "从在线版本创建草稿")
+        .action(async (name, options, command) => {
+        const client = new AiRegistryClient(loadConfig("aiRegistry"));
+        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>")
-        .requiredOption("-n, --namespace <key>", "namespaceKey")
+        .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .option("--overwrite", "覆盖现有 draft")
         .option("--target-version <semver>", "目标版本")
@@ -205,10 +297,12 @@ export function registerAiRegistryCommands(program) {
     }), ["numa registry skill 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>`)
-            .requiredOption("-n, --namespace <key>", "namespaceKey")
+            .option("-n, --namespace <key>", "namespaceKey")
             .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
             .option("--version <semver>", "版本（publish 必填）")
             .action(async (name, options, command) => {
+            if (action === "publish" && !options.version)
+                throw new AiRegistryError("publish requires --version.", "ai_registry_input_invalid");
             const client = new AiRegistryClient(loadConfig("aiRegistry"));
             const targetNamespace = await resolveNamespace(client, options);
             const result = await client.skillAction(targetNamespace.id, name, action, { version: options.version });
@@ -216,7 +310,7 @@ export function registerAiRegistryCommands(program) {
         }), [`numa registry skill ${action} release-helper --namespace team-ai${action === "publish" ? " --version 1.0.0" : ""}`]);
     }
     addExamples(skill.command("scope <name> <scope>")
-        .requiredOption("-n, --namespace <key>", "namespaceKey")
+        .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .action(async (name, scope, options, command) => {
         const normalized = scope.toUpperCase();
@@ -228,7 +322,7 @@ export function registerAiRegistryCommands(program) {
         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...>")
-        .requiredOption("-n, --namespace <key>", "namespaceKey")
+        .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .action(async (name, tags, options, command) => {
         const normalized = [...new Set(tags.map((tag) => tag.trim()).filter(Boolean))];
@@ -240,8 +334,21 @@ export function registerAiRegistryCommands(program) {
         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...>")
+        .option("-n, --namespace <key>", "namespaceKey")
+        .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
+        .requiredOption("--version <semver>", "绑定标签的精确版本")
+        .action(async (name, labels, options, command) => {
+        const normalized = [...new Set(labels.map((label) => label.trim()).filter(Boolean))];
+        if (!normalized.length || normalized.length > 20)
+            throw new AiRegistryError("labels must contain 1-20 values.", "ai_registry_input_invalid");
+        const client = new AiRegistryClient(loadConfig("aiRegistry"));
+        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>")
-        .requiredOption("-n, --namespace <key>", "namespaceKey")
+        .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .option("--yes", "确认不可逆的远端删除")
         .action(async (name, options, command) => {
@@ -254,7 +361,7 @@ export function registerAiRegistryCommands(program) {
     }), ["numa registry skill delete obsolete-skill --namespace team-ai --yes --json"]);
     const mcp = registry.command("mcp").description("查看、维护和安装 Nacos MCP Servers");
     addExamples(mcp.command("list")
-        .requiredOption("-n, --namespace <key>", "namespaceKey")
+        .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .option("-q, --search <text>", "搜索关键词")
         .option("--page <number>", "页码", "1")
@@ -270,7 +377,7 @@ export function registerAiRegistryCommands(program) {
         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"]);
     addExamples(mcp.command("inspect <name>")
-        .requiredOption("-n, --namespace <key>", "namespaceKey")
+        .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .option("--version <semver>", "精确版本")
         .action(async (name, options, command) => {
@@ -280,29 +387,88 @@ export function registerAiRegistryCommands(program) {
         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"]);
     addExamples(mcp.command("install <name>")
-        .requiredOption("-n, --namespace <key>", "namespaceKey")
+        .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .requiredOption("-a, --agent <agent>", "chatgpt|codex|claude|cursor|workbuddy|openclaw|custom")
         .option("--scope <scope>", "project|user", "project")
         .option("--version <semver>", "精确版本")
+        .option("--label <label>", "首次安装时解析的标签", "latest")
+        .option("--transport <transport>", "auto|remote|bridge", "auto")
         .option("--workspace <path>", "项目根目录")
         .option("--custom-config <path>", "自定义 mcp.json 路径")
         .option("--force", "备份并替换 JSON 配置中的同名项")
         .action(async (name, options, command) => {
         const client = new AiRegistryClient(loadConfig("aiRegistry"));
-        const targetNamespace = await resolveNamespace(client, options);
-        const detail = await client.getMcpServer(targetNamespace.id, name, options.version);
-        const result = await installMcpDefinition(detail, {
-            agent: mcpAgent(options.agent), scope: installScope(options.scope), workspace: options.workspace,
+        const context = await resolveContext(client, options);
+        const trackedLabel = options.version ? undefined : options.label ?? "latest";
+        const detail = await client.getMcpServer(context.namespace.id, name, options.version ? { version: options.version } : { label: trackedLabel });
+        const version = resolveVersion(detail, options.version, trackedLabel, name);
+        const upstream = mcpDefinitionFromNacos(detail);
+        const entry = {
+            name, version: options.version, label: trackedLabel, agent: mcpAgent(options.agent),
+            scope: installScope(options.scope), transport: mcpTransport(options.transport), customConfig: options.customConfig
+        };
+        if (!context.capability.router?.endpoint || context.capability.router.status !== "READY") {
+            throw new AiRegistryError(`Namespace ${context.namespace.namespaceKey} has no ready enterprise Router.`, "ai_registry_router_unavailable");
+        }
+        assertRouterHealth(await client.checkRouter(context.namespace.id));
+        const result = await installMcpClientDefinition(name, routerMcpDefinition(context, entry), {
+            agent: entry.agent, scope: entry.scope, workspace: options.workspace,
             customConfig: options.customConfig, force: options.force
         });
+        const lock = await recordMcpInstallation(context, options.workspace, entry, version, canonicalSha256({ version, definition: upstream }), result.configPath ?? result.endpoint ?? `managed:${result.agent}`);
         const textResult = result.manualSteps
             ? `已生成 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: targetNamespace, installation: result }, textResult);
+        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"]);
+    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"]);
+    for (const action of ["online", "offline"]) {
+        addExamples(mcp.command(`${action} <name>`)
+            .option("-n, --namespace <key>", "namespaceKey")
+            .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
+            .option("--version <semver>", "精确版本")
+            .action(async (name, options, command) => {
+            const client = new AiRegistryClient(loadConfig("aiRegistry"));
+            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`]);
+    }
+    addExamples(mcp.command("tags <name> <tags...>")
+        .option("-n, --namespace <key>", "namespaceKey")
+        .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
+        .action(async (name, tags, options, command) => {
+        const normalized = [...new Set(tags.map((tag) => tag.trim()).filter(Boolean))];
+        if (!normalized.length || normalized.length > 20)
+            throw new AiRegistryError("tags must contain 1-20 values.", "ai_registry_input_invalid");
+        const client = new AiRegistryClient(loadConfig("aiRegistry"));
+        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"]);
+    const tools = mcp.command("tool").description("启用或禁用 MCP 工具");
+    for (const action of ["enable", "disable"]) {
+        addExamples(tools.command(`${action} <mcp-name> <tool-name>`)
+            .option("-n, --namespace <key>", "namespaceKey")
+            .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
+            .option("--version <number>", "乐观锁版本")
+            .action(async (mcpName, toolName, options, command) => {
+            const client = new AiRegistryClient(loadConfig("aiRegistry"));
+            const targetNamespace = await resolveNamespace(client, options);
+            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`]);
+    }
     addExamples(mcp.command("create <json>")
-        .requiredOption("-n, --namespace <key>", "namespaceKey")
+        .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .action(async (file, options, command) => {
         const client = new AiRegistryClient(loadConfig("aiRegistry"));
@@ -311,7 +477,7 @@ export function registerAiRegistryCommands(program) {
         await output(command, { ok: true, namespace: targetNamespace, result }, "MCP create 完成");
     }), ["numa registry mcp create ./mcp.json --namespace team-ai --json"]);
     addExamples(mcp.command("update <name> <json>")
-        .requiredOption("-n, --namespace <key>", "namespaceKey")
+        .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .action(async (name, file, options, command) => {
         const client = new AiRegistryClient(loadConfig("aiRegistry"));
@@ -320,7 +486,7 @@ export function registerAiRegistryCommands(program) {
         await output(command, { ok: true, namespace: targetNamespace, result }, "MCP update 完成");
     }), ["numa registry mcp update internal-docs ./mcp.json --namespace team-ai --json"]);
     addExamples(mcp.command("delete <name>")
-        .requiredOption("-n, --namespace <key>", "namespaceKey")
+        .option("-n, --namespace <key>", "namespaceKey")
         .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
         .option("--version <semver>", "精确版本")
         .option("--yes", "确认不可逆的远端删除")
@@ -332,93 +498,106 @@ export function registerAiRegistryCommands(program) {
         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"]);
-}
-async function runTui() {
-    if (!process.stdin.isTTY || !process.stdout.isTTY) {
-        throw new AiRegistryError("Registry TUI requires an interactive terminal.", "ai_registry_tui_required");
-    }
-    const client = new AiRegistryClient(loadConfig("aiRegistry"));
-    const namespaces = (await client.listNamespaces()).filter((namespace) => namespace.status === "ACTIVE" && namespace.instanceStatus === "ACTIVE");
-    if (!namespaces.length)
-        throw new AiRegistryError("No active Nacos namespace is configured.", "ai_registry_namespace_not_found");
-    const namespaceId = await select({
-        message: "选择 Nacos namespace",
-        options: namespaces.map((namespace) => ({
-            value: namespace.id,
-            label: namespace.displayName,
-            hint: `${namespace.namespaceKey} · ${namespace.instanceCode}${namespace.isDefault ? " · default" : ""}`
-        }))
-    });
-    if (isCancel(namespaceId))
-        return void cancel("已取消");
-    const domain = await select({ message: "选择资源", options: [{ value: "skill", label: "Skills" }, { value: "mcp", label: "MCP Servers" }] });
-    if (isCancel(domain))
-        return void cancel("已取消");
-    if (domain === "skill")
-        await skillTui(client, namespaceId);
-    else
-        await mcpTui(client, namespaceId);
-}
-async function skillTui(client, namespaceId) {
-    const page = await client.listSkills(namespaceId, { pageSize: 100 });
-    const items = pageItems(page);
-    if (!items.length)
-        return void process.stdout.write("没有可用 Skill。\n");
-    const name = await select({ message: "选择 Skill", options: items.map((item, index) => ({ value: itemName(item, `skill-${index + 1}`), label: itemName(item, `skill-${index + 1}`), hint: String(item.description ?? item.status ?? "") })) });
-    if (isCancel(name))
-        return void cancel("已取消");
-    const action = await select({ message: `对 ${name} 执行`, options: [
-            { value: "inspect", label: "查看详情" }, { value: "install", label: "安装到本机" },
-            { value: "submit", label: "提交审核" }, { value: "publish", label: "发布版本" },
-            { value: "online", label: "上线" }, { value: "offline", label: "下线" }
-        ] });
-    if (isCancel(action))
-        return void cancel("已取消");
-    if (action === "inspect")
-        return void process.stdout.write(`${JSON.stringify(sanitizeRegistryOutput(await client.getSkill(namespaceId, name)), null, 2)}\n`);
-    if (action === "install") {
-        const agent = await select({ message: "安装目标", options: ["chatgpt", "codex", "claude", "cursor", "workbuddy", "openclaw", "agents"].map((value) => ({ value, label: value })) });
-        if (isCancel(agent))
-            return void cancel("已取消");
-        const scope = await select({ message: "安装范围", options: [{ value: "project", label: "当前项目" }, { value: "user", label: "当前用户" }] });
-        if (isCancel(scope))
-            return void cancel("已取消");
-        const archive = await client.downloadSkill(namespaceId, name, { label: "latest" });
-        const result = await installSkillArchive(archive.bytes, { agent: skillAgent(agent), scope: installScope(scope), skillName: name });
-        return void process.stdout.write(`已安装: ${result.installedPath}\n`);
-    }
-    let version;
-    if (action === "publish") {
-        const answer = await text({ message: "输入要发布的 SemVer" });
-        if (isCancel(answer))
-            return void cancel("已取消");
-        version = answer;
+    const approvals = registry.command("approvals").description("查看、审核和发布两人制 release request");
+    addExamples(approvals.command("submit <type> <name>")
+        .option("-n, --namespace <key>", "namespaceKey")
+        .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
+        .requiredOption("--resource-version <version>", "提交审核的精确资源版本")
+        .requiredOption("--reason <reason>", "发布说明")
+        .option("--scanner-exemption <reason>", "仅非生产 Reviewer 可审批的扫描豁免原因")
+        .action(async (type, name, options, command) => {
+        const resourceType = type.toUpperCase();
+        if (resourceType !== "SKILL" && resourceType !== "MCP") {
+            throw new AiRegistryError("type must be skill or mcp.", "ai_registry_input_invalid");
+        }
+        const client = new AiRegistryClient(loadConfig("aiRegistry"));
+        const context = await resolveContext(client, options);
+        const result = await client.createReleaseRequest({
+            namespaceId: context.namespace.id,
+            resourceType,
+            resourceName: name,
+            resourceVersion: options.resourceVersion,
+            reason: options.reason,
+            ...(options.scannerExemption ? { scannerExemptionReason: options.scannerExemption } : {})
+        });
+        await output(command, { ok: true, namespace: context.namespace, result }, `${resourceType} ${name}@${options.resourceVersion}: submitted`);
+    }), ["numa registry approvals submit skill release-helper --resource-version 1.2.0 --reason 'ready for production' --json"]);
+    addExamples(approvals.command("list")
+        .option("-n, --namespace <key>", "namespaceKey")
+        .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
+        .option("--state <state>", "生命周期状态")
+        .option("--limit <number>", "每页 1-100", "20")
+        .action(async (options, command) => {
+        const client = new AiRegistryClient(loadConfig("aiRegistry"));
+        const context = await resolveContext(client, options);
+        const result = await client.listReleaseRequests({
+            namespaceId: context.namespace.id,
+            state: options.state,
+            limit: positiveInteger(options.limit, "limit", 20, 100)
+        });
+        await output(command, { ok: true, namespace: context.namespace, releaseRequests: result }, JSON.stringify(sanitizeRegistryOutput(result), null, 2));
+    }), ["numa registry approvals list --state SUBMITTED --json"]);
+    addExamples(approvals.command("review <request-id>")
+        .requiredOption("--decision <decision>", "APPROVED|REJECTED")
+        .requiredOption("--reason <reason>", "审核原因")
+        .option("--version <number>", "乐观锁版本")
+        .action(async (requestId, options, command) => {
+        const decision = options.decision.toUpperCase();
+        if (decision !== "APPROVED" && decision !== "REJECTED")
+            throw new AiRegistryError("decision must be APPROVED or REJECTED.", "ai_registry_input_invalid");
+        const result = await new AiRegistryClient(loadConfig("aiRegistry")).reviewReleaseRequest(requestId, {
+            decision,
+            reason: options.reason,
+            ...(options.version == null ? {} : { version: nonnegativeInteger(options.version, "version") })
+        });
+        await output(command, { ok: true, requestId, result }, `Release request ${requestId}: ${decision}`);
+    }), ["numa registry approvals review rr_123 --decision APPROVED --reason 'scan passed' --version 2 --json"]);
+    addExamples(approvals.command("publish <request-id>")
+        .option("--version <number>", "乐观锁版本")
+        .action(async (requestId, options, command) => {
+        const result = await new AiRegistryClient(loadConfig("aiRegistry")).publishReleaseRequest(requestId, {
+            ...(options.version == null ? {} : { version: nonnegativeInteger(options.version, "version") })
+        });
+        await output(command, { ok: true, requestId, result }, `Release request ${requestId}: publish started`);
+    }), ["numa registry approvals publish rr_123 --version 3 --json"]);
+    const router = registry.command("router").description("查看 namespace Router 绑定、连接和健康");
+    for (const action of ["inspect", "health", "reconcile"]) {
+        addExamples(router.command(action)
+            .option("-n, --namespace <key>", "namespaceKey")
+            .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
+            .action(async (options, command) => {
+            const client = new AiRegistryClient(loadConfig("aiRegistry"));
+            const context = await resolveContext(client, options);
+            const result = action === "inspect" ? await client.getRouter(context.namespace.id)
+                : action === "health" ? await client.checkRouter(context.namespace.id)
+                    : await client.reconcileNamespace(context.namespace.id);
+            await output(command, { ok: true, namespace: context.namespace, result }, JSON.stringify(sanitizeRegistryOutput(result), null, 2));
+        }), [`numa registry router ${action} --namespace team-ai --json`]);
     }
-    const approved = await confirm({ message: `确认执行 ${action}?`, initialValue: false });
-    if (isCancel(approved) || !approved)
-        return void cancel("已取消");
-    await client.skillAction(namespaceId, name, action, { version });
-    process.stdout.write(`${name}: ${action} 完成\n`);
+    addExamples(router.command("connect")
+        .option("-n, --namespace <key>", "namespaceKey")
+        .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
+        .option("--adapter <adapter>", "客户端适配器")
+        .action(async (options, command) => {
+        const client = new AiRegistryClient(loadConfig("aiRegistry"));
+        const context = await resolveContext(client, options);
+        const result = await client.connectRouter(context.namespace.id, { adapter: options.adapter });
+        await output(command, { ok: true, namespace: context.namespace, result }, `Router connection prepared for ${context.namespace.namespaceKey}`);
+    }), ["numa registry router connect --namespace team-ai --adapter codex --json"]);
+    addExamples(registry.command("audit").description("查询追加式 Registry 审计事件")
+        .option("-n, --namespace <key>", "namespaceKey")
+        .option("-i, --instance <id-or-code>", "同名 namespace 的实例消歧")
+        .option("--cursor <cursor>", "分页游标")
+        .option("--limit <number>", "每页 1-100", "20")
+        .action(async (options, command) => {
+        const client = new AiRegistryClient(loadConfig("aiRegistry"));
+        const context = await resolveContext(client, options);
+        const result = await client.listAuditEvents({ namespaceId: context.namespace.id, cursor: options.cursor, limit: positiveInteger(options.limit, "limit", 20, 100) });
+        await output(command, { ok: true, namespace: context.namespace, events: result }, JSON.stringify(sanitizeRegistryOutput(result), null, 2));
+    }), ["numa registry audit --namespace team-ai --json"]);
 }
-async function mcpTui(client, namespaceId) {
-    const page = await client.listMcpServers(namespaceId, { pageSize: 100 });
-    const items = pageItems(page);
-    if (!items.length)
-        return void process.stdout.write("没有可用 MCP Server。\n");
-    const name = await select({ message: "选择 MCP Server", options: items.map((item, index) => ({ value: itemName(item, `mcp-${index + 1}`), label: itemName(item, `mcp-${index + 1}`), hint: String(item.description ?? item.protocol ?? "") })) });
-    if (isCancel(name))
-        return void cancel("已取消");
-    const action = await select({ message: `对 ${name} 执行`, options: [{ value: "inspect", label: "查看详情" }, { value: "install", label: "安装到客户端" }] });
-    if (isCancel(action))
-        return void cancel("已取消");
-    const detail = await client.getMcpServer(namespaceId, name);
-    if (action === "inspect")
-        return void process.stdout.write(`${JSON.stringify(sanitizeRegistryOutput(detail), null, 2)}\n`);
-    const agent = await select({ message: "安装目标", options: ["chatgpt", "codex", "claude", "cursor", "workbuddy", "openclaw"].map((value) => ({ value, label: value })) });
-    if (isCancel(agent))
-        return void cancel("已取消");
-    const result = await installMcpDefinition(detail, { agent: mcpAgent(agent), scope: agent === "codex" || agent === "openclaw" ? "user" : "project" });
-    process.stdout.write(`已安装 MCP: ${result.configPath ?? "客户端 CLI 配置"}\n`);
+async function runTui() {
+    await runRegistryTui(new AiRegistryClient(loadConfig("aiRegistry")));
 }
 function skillAgent(value) {
     if (["chatgpt", "codex", "claude", "cursor", "workbuddy", "openclaw", "agents", "custom"].includes(value))
@@ -435,4 +614,80 @@ function installScope(value) {
         return value;
     throw new AiRegistryError("scope must be project or user.", "ai_registry_install_target_invalid");
 }
+function mcpTransport(value) {
+    if (value === "auto" || value === "remote" || value === "bridge")
+        return value;
+    throw new AiRegistryError("transport must be auto, remote, or bridge.", "ai_registry_install_target_invalid");
+}
+function nonnegativeInteger(value, label) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0 || parsed > Number.MAX_SAFE_INTEGER) {
+        throw new AiRegistryError(`${label} must be a non-negative integer.`, "ai_registry_input_invalid");
+    }
+    return parsed;
+}
+async function recordSkillInstallation(context, workspace, entry, version, sha256, installedPath) {
+    const project = await registryProjectForWrite(context, workspace);
+    const manifest = mergeSkillEntry(project.manifest, entry);
+    await writeRegistryManifest(project.files, manifest);
+    const lock = upsertLockResource(project.lock, {
+        type: "SKILL",
+        name: entry.name,
+        version,
+        ...(entry.label ? { trackedLabel: entry.label } : {}),
+        sha256,
+        source: { registry: "NACOS", namespaceKey: context.namespace.namespaceKey, instanceCode: context.namespace.instanceCode },
+        install: {
+            agent: entry.agent,
+            scope: entry.scope,
+            status: "INSTALLED",
+            path: portableInstallPath(installedPath, workspace ?? process.cwd(), entry.agent)
+        }
+    });
+    await writeRegistryLock(project.files, lock);
+    return { manifestPath: project.files.manifestPath, lockPath: project.files.lockPath };
+}
+async function recordMcpInstallation(context, workspace, entry, version, sha256, installedPath) {
+    const project = await registryProjectForWrite(context, workspace);
+    const manifest = mergeMcpEntry(project.manifest, entry);
+    await writeRegistryManifest(project.files, manifest);
+    const lock = upsertLockResource(project.lock, {
+        type: "MCP",
+        name: entry.name,
+        version,
+        ...(entry.label ? { trackedLabel: entry.label } : {}),
+        sha256,
+        source: { registry: "NACOS", namespaceKey: context.namespace.namespaceKey, instanceCode: context.namespace.instanceCode },
+        install: {
+            agent: entry.agent,
+            scope: entry.scope,
+            status: "INSTALLED",
+            path: portableInstallPath(installedPath, workspace ?? process.cwd(), entry.agent)
+        }
+    });
+    await writeRegistryLock(project.files, lock);
+    return { manifestPath: project.files.manifestPath, lockPath: project.files.lockPath };
+}
+async function registryProjectForWrite(context, workspace) {
+    const existing = await readRegistryManifest(workspace, false);
+    const files = existing?.files ?? registryWorkspaceAt(workspace);
+    const manifest = existing?.manifest ?? {
+        schemaVersion: 1,
+        namespaceKey: context.namespace.namespaceKey,
+        instanceCode: context.namespace.instanceCode,
+        skills: [],
+        mcpServers: []
+    };
+    if (manifest.namespaceKey !== context.namespace.namespaceKey || (manifest.instanceCode && manifest.instanceCode !== context.namespace.instanceCode)) {
+        throw new AiRegistryError("Existing registry manifest points to a different namespace binding.", "ai_registry_manifest_namespace_mismatch");
+    }
+    const lock = await readRegistryLock(files, false) ?? {
+        schemaVersion: 1,
+        namespaceKey: context.namespace.namespaceKey,
+        instanceCode: context.namespace.instanceCode,
+        policyRevision: context.capabilities.policyRevision,
+        resources: []
+    };
+    return { files, manifest, lock };
+}
 //# sourceMappingURL=commands.js.map