@numa-tech/numa 1.12.7 → 1.12.10

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。
 
 首次从本机发布公共包，或公共登录已经过期时，先运行：
 
@@ -187,9 +188,14 @@ numa config \
 | `numa admin context` | 需角色 | 要求 `platform-admin` 或 `numa-admin` |
 | `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 skill list/inspect/install/upload/...` | 需登录 | 发现、安装和治理 Nacos Skills；发布类操作需要 Registry admin |
-| `numa registry mcp list/inspect/install/create/update/delete` | 需登录 | 发现、安装和维护 Nacos MCP Servers；写操作需要 Registry admin |
-| `numa registry tui` | 需登录 | 在终端交互浏览、安装和治理 Skill/MCP |
+| `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 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` | 需登录 | 提交视频生成异步任务 |
@@ -232,6 +238,8 @@ CLI 的本地角色检查用于快速反馈和隐藏无权限入口，不能替
 - `profileUrl`：完整的公开 client-configuration URL；设置后各模块只使用该
   profile 声明的 service 与 authority；
 - `profileId`：可选的 profile 标识锁定；远端返回其他标识时拒绝启用；
+- `aiRegistryDefaultNamespaceKey`：用户级 Registry 默认 namespace；优先级低于命令行和
+  项目 `.numa/registry.json`，高于 profile 默认值；
 - `registryUrl`：npm registry，默认公共 npm，也可配置公司私有 registry；
 - `checkUpdates`：是否检查 CLI 更新。
 
@@ -268,9 +276,9 @@ numa login --no-console --no-config --json
 ```
 
 控制台展示当前身份、Realm/Client 角色、AI Registry、ChatGPT 账号、基础配置和机器可读命令目录。
-AI Registry 页按“namespace → Skill/MCP → 详情/动作”组织，支持搜索、详情、安装以及 Skill
-提交/发布/上下线。发布按钮是否可用只是界面提示，实际权限始终由平台 Keycloak Policy
-Enforcer 决定。
+AI Registry 页包含目录、发布收件箱、实例/双凭据、Namespace/Profile、Router、权限/审计六个
+工作区，并展示 capability 返回的环境、动作和 Router 状态。按钮是否可用只是界面提示，实际
+权限、两人制和生命周期始终由平台服务端决定。
 ChatGPT 账号页先读取 `codex-multi-auth` 的本地账号与额度缓存并立即展示，再使用当前
 Keycloak 会话连接平台补充当前用户可用账号、剩余 limit 和同步状态。平台不可用时页面
 保留本地结果并明确显示“远程同步失败”，不会把 access token 或 refresh token 返回给页面。
@@ -287,20 +295,27 @@ CSP。OIDC access/refresh token 始终保留在 CLI 进程及私有缓存中，
 
 ## 私有 Nacos AI Registry
 
-`numa registry` 对接 `mci-devops-platform` 的 `/api/v1/ai-registry` 类型化 API。客户端只携带
-当前用户 Keycloak Bearer Token；平台从自己的数据库解析 Nacos 实例、namespace 和该实例的
-OIDC client-credentials，再访问目标 Nacos。Nacos token、OIDC client secret 和 endpoint
-credential 不写入 Numa 配置，也不由读取 API 返回。
+`numa registry` 对接 `mci-devops-platform` 的 `/api/v1/ai-registry` 类型化 API。Nacos 是
+Skill/MCP 内容、版本、标签和上下线状态的主仓库；平台只维护组织、团队、权限、审批、profile、
+Router 绑定、对账和审计。Numa 只携带当前用户 Keycloak Bearer Token，且 capability 响应若
+包含 Nacos 地址、token、secret、password 或 credential 字段会被客户端拒绝。
+
+`GET /api/v1/ai-registry/capabilities` 返回当前用户可见 namespace、环境、动作、Router
+Streamable HTTP/OAuth resource 和客户端适配器。profile v1 可追加
+`services.aiRegistry.capabilityUrl` 与
+`services.aiRegistry.configuration.defaultNamespaceKey`，旧客户端会忽略这些字段。
 
 权限契约：
 
-- `mci-devops-platform-ai-registry-reader`：`view`，可列出、检查、下载和安装；
-- `mci-devops-platform-ai-registry-admin`：`view` + `edit`，作为操作管理员管理实例、namespace、Skill 和 MCP；
-- 平台 operations admin 同时拥有 `view` + `edit`。
+- 团队 `MEMBER+` 可使用已授权 namespace；
+- 团队 `MAINTAINER/ADMIN/OWNER` 可维护本团队草稿；
+- `ai-registry-reviewer` 可审核发布申请，且不得审核或发布自己的申请；
+- `ai-registry-admin` 管理 Registry，`ops-admin` 才能执行 `*` allowlist、Admin API 和紧急操作。
 
-Nacos 的 `baseUrl`、token URI、client ID、client secret 和 scope 全部按实例保存在
-`mci-devops-platform` 数据库。client secret 使用 AES-256-GCM 密文存储，读取接口只返回
-`credentialConfigured`，不会返回明文或密文。平台部署只需从 Secret/KMS 注入数据库密文的
+每个 Nacos 实例分别配置 `READER` 和 `MAINTAINER` 凭据，可使用 OIDC client credentials 或
+Nacos username/password，并为每套凭据设置精确 namespace allowlist。凭据使用 AES-256-GCM
+密文存储，读取接口只返回 configured 状态，不返回明文或密文。旧单凭据作为 `LEGACY_BOTH`
+继续工作，管理员验证两套新凭据后再显式停用。平台部署从 Secret/KMS 注入数据库密文的
 主密钥环 `AI_REGISTRY_SECRET_ENCRYPTION_KEYS` 与当前 key ID
 `AI_REGISTRY_SECRET_CURRENT_KEY_ID`；这两项是密钥管理材料，不是某个 Nacos 实例的配置。
 密钥环格式为逗号分隔的 `keyId=Base64(32-byte-key)`；轮换时先加入新 key 并切换当前 key ID，
@@ -309,25 +324,35 @@ SSRF 安全策略仍由 `AI_REGISTRY_ALLOWED_UPSTREAM_HOSTS`、
 `AI_REGISTRY_ALLOWED_TOKEN_HOSTS` 控制，allow-list 为空时 fail closed；HTTP 只可通过
 `AI_REGISTRY_ALLOW_HTTP=true` 用于开发环境。
 
-Nacos 实例文件示例（`clientSecret` 仅写入）：
+Nacos 实例文件示例（凭据字段仅写入，实际字段以平台 capability/API revision 为准）：
 
 ```json
 {
   "code": "cluster-a",
   "displayName": "Nacos Cluster A",
   "baseUrl": "https://nacos.internal.example:8848",
-  "authenticationType": "OIDC_CLIENT_CREDENTIALS",
-  "tokenUri": "https://sso.internal.example/realms/mci/protocol/openid-connect/token",
-  "clientId": "nacos-registry-broker",
-  "clientSecret": "write-only-secret",
-  "scope": "openid",
+  "credentials": {
+    "reader": {
+      "authenticationType": "OIDC_CLIENT_CREDENTIALS",
+      "tokenUri": "https://sso.internal.example/realms/mci/protocol/openid-connect/token",
+      "clientId": "nacos-registry-reader",
+      "clientSecret": "write-only-secret",
+      "namespaceAllowlist": ["team-ai"]
+    },
+    "maintainer": {
+      "authenticationType": "NACOS_USERNAME_PASSWORD",
+      "username": "registry-maintainer",
+      "password": "write-only-password",
+      "namespaceAllowlist": ["team-ai"]
+    }
+  },
   "description": "A 集群",
   "status": "ACTIVE"
 }
 ```
 
-`instances update` 必须带列表结果中的当前 `version`，用于乐观锁保护；省略 `clientSecret`
-表示保留已有密文。建议让包含明文 secret 的输入文件仅对当前用户可读，并在写入后安全删除。
+`instances update` 必须带列表结果中的当前 `version`，用于乐观锁保护；省略某套凭据表示保留
+已有密文。建议让包含明文 secret 的输入文件仅对当前用户可读，并在写入后安全删除。
 
 namespace 文件示例：
 
@@ -343,13 +368,13 @@ namespace 文件示例：
 ```
 
 `namespaceKey` 是客户端使用的稳定名称，`namespaceId` 是该 Nacos 实例中的真实 ID。同一个
-`namespaceKey` 可以存在于多个实例；其中最多一个 ACTIVE 路由可设为 `isDefault=true`。
-客户端只传 `--namespace team-ai` 时，平台会选择唯一匹配项或默认项；同名且没有默认项时返回
-`AI_REGISTRY_NAMESPACE_AMBIGUOUS`，此时必须加 `--instance cluster-b` 消歧。
+`namespaceKey` 可以存在于多个实例。Numa 的选择顺序固定为 `--namespace` → 最近的
+`.numa/registry.json` → 用户 `aiRegistryDefaultNamespaceKey` → profile 默认值；选择结果必须
+存在于 capability 授权列表。同名绑定必须由 manifest/`--instance` 消歧，默认值无效时明确失败，
+不会切换到其他可用 namespace。旧 `isDefault` 仅供迁移期兼容客户端使用。
 
-V34 会把旧服务行拆成实例和 namespace，但旧 `credentialRef` 无法自动转换为数据库密文，
-所以迁移后的实例会先置为 `DISABLED`。管理员写入完整 OIDC 配置和 `clientSecret` 后再启用；
-跨集群重复的旧 namespace 不会自动猜测默认项。
+profile 管理员发布 `defaultNamespaceKey` 且满足最低客户端版本后，才可逐步移除旧 `isDefault`
+fallback。服务器端数据库迁移必须从当前版本新增 Flyway migration，不修改历史迁移。
 
 先发现实例和 namespace，再通过 namespace 操作资源：
 
@@ -359,6 +384,13 @@ numa registry namespaces list --namespace team-ai --json
 numa registry namespaces resolve team-ai --json
 numa registry namespaces check team-ai --json
 
+numa registry capabilities --json
+numa registry init --namespace team-ai --instance cluster-b --json
+# 编辑 .numa/registry.json 后：
+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 \
@@ -367,50 +399,237 @@ numa registry skill install release-helper \
 numa registry mcp list --namespace team-ai --json
 numa registry mcp inspect internal-docs --namespace team-ai --json
 numa registry mcp install internal-docs \
-  --namespace team-ai --instance cluster-b --agent claude --scope project --json
+  --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 registry tui
 ```
 
-Skill 发布生命周期：
+两人制发布生命周期：
 
 ```bash
 numa registry skill upload ./release-helper.zip \
   --namespace team-ai --target-version 1.0.0 --json
-numa registry skill submit release-helper --namespace team-ai --json
-numa registry skill publish release-helper \
-  --namespace team-ai --version 1.0.0 --json
-numa registry skill online release-helper --namespace team-ai --json
-numa registry skill scope release-helper PRIVATE --namespace team-ai --json
-numa registry skill tags release-helper deploy java --namespace team-ai --json
+numa registry approvals submit skill release-helper \
+  --namespace team-ai --resource-version 1.0.0 --reason "scanner passed" --json
+# 必须由另一位 reviewer 执行
+numa registry approvals review rr_123 \
+  --decision APPROVED --reason "reviewed" --version 1 --json
+numa registry approvals publish rr_123 --version 2 --json
+numa registry audit --namespace team-ai --json
 ```
 
+生命周期由服务端统一为
+`DRAFT → SUBMITTED → APPROVED/REJECTED → PUBLISHING → PUBLISHED/FAILED → OFFLINE`。
+生产及企业默认 namespace 的 Skill 不允许绕过 scanner；非生产豁免也必须带原因并由 Reviewer
+审批。MCP 发布由服务端执行协议、工具 schema、禁用工具和 Endpoint 健康预检。
+
 远端删除必须带 `--yes`。本地同名 Skill/MCP 默认拒绝覆盖；用户明确同意后才使用
 `--force`，支持原子替换的适配器会先保留时间戳备份。Skill 下载必须通过平台返回的
 SHA-256 校验，ZIP 在解压前会检查根 `SKILL.md`、路径穿越、符号链接、重复路径、文件数和
-膨胀大小。MCP 定义中的敏感 env/header 只能使用 `${ENV_VAR}` 占位符，不能携带明文密钥。
+膨胀大小。`.numa/registry.lock.json` 保存解析后的精确版本、Nacos 来源、SHA-256 和安装状态；
+普通 `sync` 不解析标签，只有首次 `lock` 或显式 `upgrade` 会变更版本。MCP 客户端只安装
+capability 发布且健康的企业 Router，不安装 Nacos 中的下游 endpoint。
 
 ### 客户端安装适配
 
 | 客户端 | Skill | MCP Server |
 | --- | --- | --- |
-| ChatGPT / Codex coding workspace | `.codex/skills` | ChatGPT 仅接受远程 HTTPS MCP App；Numa 返回 Developer mode/App 创建指引，不会冒充修改工作区设置 |
+| ChatGPT / Codex coding workspace | `.codex/skills` | ChatGPT 连接企业 Router 的远程 HTTPS OAuth resource；Numa 返回 App 创建指引 |
 | Codex | `.codex/skills` | 调用官方 `codex mcp add`，仅 user scope |
 | Claude | `.claude/skills` | 项目 `.mcp.json`；user scope 使用 `~/.claude.json` |
 | Cursor | `.cursor/skills` | `.cursor/mcp.json` |
 | WorkBuddy | `.workbuddy/skills` | `.workbuddy/mcp.json`；目录可通过 custom adapter 调整 |
 | OpenClaw | `.openclaw/skills` | 调用官方 `openclaw mcp set`，仅 user scope |
 
-ChatGPT 本身不能直接连接本地 stdio MCP。Numa 对 `--agent chatgpt` 只为远程 HTTPS endpoint
-生成受控安装指引；私网或本机 MCP 需要先发布为远程服务，或使用 ChatGPT 支持的 Secure
-MCP Tunnel。ChatGPT workspace 还需管理员按其计划和 RBAC 开启 Developer mode。
+ChatGPT 不能启动本地 stdio bridge；它直接连接企业 Router 的远程 HTTPS OAuth resource。
+其他只支持 stdio 的 Agent 可运行 `numa registry mcp bridge`，由 Numa 获取/刷新用户 Token
+并只发送给 Router，不向 Nacos 或下游 MCP 透传。ChatGPT workspace 仍需管理员按计划和
+RBAC 开启 Developer mode。
 
 仓库内置的自用 Skill 位于 `skills/numa-ai-registry/SKILL.md`，并随 npm 包发布。它指导 AI
 按“认证 → 服务解析 → inspect → 安装/治理 → 复查”的顺序使用 Registry，同时明确禁止索取
 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 或
+URL；生产 build、retry 和 stop 由服务端再次校验 `ops-admin` 与审批依据。
+
+三个容易混淆的标识含义不同：
+
+| 标识 | 生成方 | 用途 | 重试规则 |
+| --- | --- | --- | --- |
+| `requestId` | 平台 | 标识已创建的构建任务，用于 status、log、stop、retry | 新任务产生新值 |
+| `idempotency-key` | CLI 或调用者 | 判断重复提交是否属于同一次部署 | 同一次提交重试必须复用；新部署使用新值 |
+| `approve-id` | 审批流程或管理员 | 记录生产操作依据 | 按审批范围使用，不是任务标识 |
+
+`idempotency-key` 是可选参数。不传时 CLI 会自动生成 UUID，并在成功结果中以
+`idempotency_key` 返回。生产部署和自动化脚本建议显式指定：如果网络中断导致结果不明，
+使用原值重新提交，平台会返回原任务或拒绝内容不一致的冲突，不会无意创建第二个构建。
+
+```bash
+numa pipeline inspect mci-devops-platform --json
+
+numa pipeline build mci-devops-platform \
+  --tier production \
+  --branch main \
+  --approve-id OPS-APPROVAL-20260818-001 \
+  --idempotency-key mci-devops-platform-prd-20260818-001 \
+  --wait \
+  --json
+```
+
+生产操作必须提供 `--approve-id` 或至少 10 个字符的 `--production-reason`。CLI 将二者作为
+独立治理字段提交；不能使用 `--param APPROVE_ID=...` 绕过治理。平台保存两者及审计记录，
+仅在生产 trigger/retry 时把经过验证的 `approveId` 映射为 Jenkins `APPROVE_ID`；
+`productionReason` 不会转发给 Jenkins。
+
+`--wait` 和 `status --watch` 约每 2 秒轮询一次，当前没有默认超时，会持续到 `SUCCESS`、
+`FAILED`、`ABORTED`、`CANCELLED` 或 `NOT_BUILT`。按 `Ctrl+C` 或遇到网络错误只会结束本地
+等待，不会停止 Jenkins 构建；真正停止任务需要显式执行 `pipeline stop ... --yes`。
+`build --wait` 仅在 `SUCCESS` 时返回退出码 0，其他终态返回非零。
+
+保存 build 返回的 `requestId`，可以随时恢复查询：
+
+```bash
+numa pipeline status req_01ABC --watch
+numa pipeline log req_01ABC --follow
+```
+
+如果没有保存 `requestId`，先按应用和环境检索构建记录，再使用返回的 `requestId`：
+
+```bash
+numa pipeline builds --app mci-devops-platform --tier production --limit 20 --json
+```
+
+`pipeline builds` 使用游标分页：`--limit` 是每页条数，不是页码；下一页应把上一页响应中的
+`next_cursor` 传给 `--cursor`。面向 AI 和自动化的同一套操作语义也包含在 `numa commands --json` 的
+`operationalNotes` 字段中，因此基本流水线操作不依赖额外 Skill。
+
 ## 平台媒体服务
 
 自 1.8.0 起，`numa media` 通过当前 Keycloak 会话调用 `/api/v1/media`。第三方

package/dist/ai-registry/bridge.d.ts

@@ -0,0 +1,8 @@
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { AiRegistryClient } from "./client.js";
+export declare function runMcpBridge(client: AiRegistryClient, options: {
+    namespace?: string;
+    instance?: string;
+    workspace?: string;
+}): Promise<void>;
+export declare function bridgeMcpTransports(local: Transport, remote: Transport): Promise<void>;

package/dist/ai-registry/bridge.js

@@ -0,0 +1,63 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { loadConfig } from "../config.js";
+import { fetchWithKeycloakIdentity } from "../oauth.js";
+import { AiRegistryError, redactRegistryText } from "./errors.js";
+import { resolveRegistryNamespace } from "./namespace.js";
+export async function runMcpBridge(client, options) {
+    const context = await resolveRegistryNamespace(client, options);
+    const router = context.capability.router;
+    if (!router?.endpoint || router.status !== "READY") {
+        throw new AiRegistryError(`Namespace ${context.namespace.namespaceKey} has no ready enterprise Router.`, "ai_registry_router_unavailable");
+    }
+    const endpoint = new URL(router.endpoint);
+    const local = ["localhost", "127.0.0.1", "::1", "[::1]"].includes(endpoint.hostname);
+    if (endpoint.protocol !== "https:" && !(endpoint.protocol === "http:" && local)) {
+        throw new AiRegistryError("Enterprise Router endpoint must use HTTPS.", "ai_registry_router_invalid");
+    }
+    await client.checkRouter(context.namespace.id);
+    const authConfig = loadConfig("aiRegistry");
+    const remote = new StreamableHTTPClientTransport(endpoint, {
+        fetch: async (input, init) => fetchWithKeycloakIdentity(authConfig, String(input), () => ({ ...init, headers: new Headers(init?.headers) }))
+    });
+    await bridgeMcpTransports(new StdioServerTransport(), remote);
+}
+export async function bridgeMcpTransports(local, remote) {
+    let closed = false;
+    let resolveClosed;
+    let rejectClosed;
+    const completed = new Promise((resolvePromise, rejectPromise) => {
+        resolveClosed = resolvePromise;
+        rejectClosed = rejectPromise;
+    });
+    const fail = (error) => {
+        if (closed)
+            return;
+        closed = true;
+        rejectClosed?.(new AiRegistryError(`MCP bridge failed: ${redactRegistryText(error.message)}`, "ai_registry_bridge_failed"));
+        void Promise.allSettled([local.close(), remote.close()]);
+    };
+    const finish = () => {
+        if (closed)
+            return;
+        closed = true;
+        resolveClosed?.();
+        void Promise.allSettled([local.close(), remote.close()]);
+    };
+    local.onmessage = (message) => { void remote.send(message).catch(fail); };
+    remote.onmessage = (message) => { void local.send(message).catch(fail); };
+    local.onerror = fail;
+    remote.onerror = fail;
+    local.onclose = finish;
+    remote.onclose = finish;
+    try {
+        await remote.start();
+        await local.start();
+        await completed;
+    }
+    catch (error) {
+        fail(error instanceof Error ? error : new Error(String(error)));
+        await completed;
+    }
+}
+//# sourceMappingURL=bridge.js.map

package/dist/ai-registry/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../../src/ai-registry/bridge.ts"],"names":[],"mappings":"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"}

package/dist/ai-registry/client.d.ts

@@ -1,6 +1,6 @@
 import type { AuthConfig } from "../config.js";
 import { type KeycloakTokenProvider } from "../oauth.js";
-import { type JsonObject, type RegistryInstance, type RegistryNamespace } from "./schemas.js";
+import { type JsonObject, type RegistryCapabilities, type RegistryInstance, type RegistryNamespace, type RegistryRouter } from "./schemas.js";
 export interface AiRegistryClientDependencies {
     fetch?: typeof fetch;
     tokenProvider?: KeycloakTokenProvider;
@@ -9,6 +9,7 @@ export interface SkillDownload {
     bytes: Buffer;
     fileName: string;
     sha256: string;
+    version?: string;
 }
 export declare class AiRegistryClient {
     private readonly config;
@@ -18,6 +19,7 @@ export declare class AiRegistryClient {
     private authenticatedFetch;
     private json;
     listInstances(): Promise<RegistryInstance[]>;
+    getCapabilities(): Promise<RegistryCapabilities>;
     createInstance(input: JsonObject): Promise<RegistryInstance>;
     updateInstance(instanceId: number, input: JsonObject): Promise<RegistryInstance>;
     deleteInstance(instanceId: number): Promise<void>;
@@ -48,17 +50,41 @@ export declare class AiRegistryClient {
         commitMsg?: string;
         uploadAction?: string;
     }): Promise<unknown>;
-    skillAction(namespaceId: number, skillName: string, action: "submit" | "publish" | "online" | "offline" | "scope" | "biz-tags" | "delete", body?: Record<string, unknown>): Promise<unknown>;
+    skillAction(namespaceId: number, skillName: string, action: "submit" | "publish" | "online" | "offline" | "scope" | "biz-tags" | "labels" | "delete", body?: Record<string, unknown>): Promise<unknown>;
     listMcpServers(namespaceId: number, options?: {
         search?: string;
         mcpName?: string;
         pageNo?: number;
         pageSize?: number;
     }): Promise<JsonObject>;
-    getMcpServer(namespaceId: number, mcpName: string, version?: string): Promise<JsonObject>;
+    getMcpServer(namespaceId: number, mcpName: string, versionOrOptions?: string | {
+        version?: string;
+        label?: string;
+    }): Promise<JsonObject>;
     createMcpServer(namespaceId: number, specification: JsonObject): Promise<unknown>;
     updateMcpServer(namespaceId: number, mcpName: string, specification: JsonObject): Promise<unknown>;
     deleteMcpServer(namespaceId: number, mcpName: string, version?: string): Promise<unknown>;
+    mcpAction(namespaceId: number, mcpName: string, action: "online" | "offline" | "biz-tags", body?: Record<string, unknown>): Promise<unknown>;
+    setMcpToolEnabled(namespaceId: number, mcpName: string, toolName: string, enabled: boolean, version?: number): Promise<unknown>;
+    createSkillDraft(namespaceId: number, skillName: string, body?: Record<string, unknown>): Promise<unknown>;
+    listReleaseRequests(options?: {
+        namespaceId?: number;
+        state?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<JsonObject>;
+    createReleaseRequest(body: JsonObject): Promise<unknown>;
+    reviewReleaseRequest(requestId: string, body: JsonObject): Promise<unknown>;
+    publishReleaseRequest(requestId: string, body?: JsonObject): Promise<unknown>;
+    getRouter(namespaceId: number): Promise<RegistryRouter>;
+    connectRouter(namespaceId: number, body?: JsonObject): Promise<unknown>;
+    checkRouter(namespaceId: number): Promise<JsonObject>;
+    reconcileNamespace(namespaceId: number): Promise<JsonObject>;
+    listAuditEvents(options?: {
+        namespaceId?: number;
+        cursor?: string;
+        limit?: number;
+    }): Promise<JsonObject>;
     private object;
     private instanceResponse;
     private namespaceResponse;