# Cnb Skill

> CNB 平台操作助手 - 帮助用户管理 CI/CD、代码仓库、流水线和查询文档 Use when this capability is needed.

- Skill: `tomevault-io/cnb-skill` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/cnb-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/cnb-skill/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/cnb-skill

---


# CNB 平台助手技能

## 概述

此技能帮助你协助用户进行 CNB（Cloud Native Build，云原生构建）平台操作。CNB 是一个全面的云原生开发平台，提供 CI/CD、代码托管、制品管理、远程工作空间和 AI 辅助等功能。技能的目标是：

1. 通过 CNB 官方 MCP HTTP API 调用一线工具，返回权威数据。
2. 用标准化的输出模板，保证回答一致、可追溯。
3. 落实错误处理与安全合规，避免泄露凭据。

## 配置与前置条件

| 项目 | 说明 |
| --- | --- |
| `CNB_TOKEN` | 必填，Bearer Token，获取方式参考 [CNB Access Token 文档](https://docs.cnb.cool/zh/guide/access-token.html)。支持两种配置方式：<br/>1. **环境变量**：`export CNB_TOKEN=your_token`<br/>2. **.env 文件**：在项目根目录、当前工作目录或脚本目录创建 `.env` 文件，内容为 `CNB_TOKEN=your_token`<br/>优先级：环境变量 > .env 文件。建议使用 .env 方式并将其加入 `.gitignore`，避免泄露凭据。|
| `CNB_MCP_URL` | 选填，默认为 `https://mcp.cnb.cool/mcp`，如需连接专用环境可以覆写。同样支持环境变量或 .env 文件配置。|
| 网络 | 需可访问 CNB MCP Endpoint，如果命令行需要代理，务必配置在环境层。|

**配置示例 (.env 文件)**：
```bash
# CNB 配置
CNB_TOKEN=your_cnb_access_token_here
# CNB_MCP_URL=https://mcp.cnb.cool/mcp  # 可选，使用自定义端点时配置
```

## 工具调用方式

所有 CNB 交互均通过 `execute_bash` 调用 `scripts/cnb-mcp.py` 完成。

1. **列出工具**
   ```json
   {
     "command": "python3 scripts/cnb-mcp.py list-tools"
   }
   ```
2. **调用工具**
   ```json
   {
     "command": "python3 scripts/cnb-mcp.py call <工具名> key1=value1 key2=value2"
   }
   ```

> 注意：脚本会尝试对 `key=value` 的 value 执行 `json.loads`，传递数组/对象时请使用合法 JSON 字面量，例如 `filters='{"branch":"main"}'`。

## 能力矩阵

下表与后续小节一起描述各功能模块、典型工具与参数。

| 模块 | 主要场景 | 对应工具 |
| --- | --- | --- |
| 组织/群组管理 | 枚举组织层级、创建组织 | `cnb_list_groups`, `cnb_list_sub_groups`, `cnb_get_group`, `cnb_create_group` |
| 仓库管理 | 列表/详情/按组织筛选/创建仓库 | `cnb_list_repositories`, `cnb_list_group_repositories`, `cnb_get_current_repository`, `cnb_get_repository`, `cnb_create_repository` |
| 议题管理 | 列表/详情/增删标签/评论 | `cnb_list_issues`, `cnb_get_issue`, `cnb_create_issue`, `cnb_update_issue`, `cnb_list_issue_comments`, `cnb_create_issue_comment`, `cnb_update_issue_comment`, `cnb_list_issue_labels`, `cnb_add_issue_labels`, `cnb_set_issue_labels`, `cnb_clear_issue_labels`, `cnb_remove_issue_label` |
| 合并请求管理 | MR 列表/详情/创建/评论/合并 | `cnb_list_pulls`, `cnb_get_pull`, `cnb_create_pull`, `cnb_update_pull`, `cnb_merge_pull`, `cnb_list_pull_comments`, `cnb_create_pull_comment` |
| 流水线管理 | 构建触发、状态、日志、终止 | `cnb_startBuild`, `cnb_stopBuild`, `cnb_getBuildStatus`, `cnb_getBuildLogs`, `cnb_getBuildStage`, `cnb_buildRunnerDownloadLog`, `cnb_buildLogsDelete` |
| 远程工作空间 | 查看/删除云原生开发环境 | `cnb_list_workspaces`, `cnb_delete_workspace` |
| 知识库 | 查询官方文档、检索 KB 元信息 | `cnb_getKnowledgeBaseInfo`, `cnb_queryKnowledgeBase` |

> 若需要扩展 AI/制品等其他平台 API，请在获取官方工具后再补充，确保名称与 MCP Server README 保持一致。

### 模块详解与参数

#### 1. 组织 / 群组管理

| 工具 | 参数 | 说明 |
| --- | --- | --- |
| `cnb_list_groups` | `page`, `page_size` | 列出顶层组织。|
| `cnb_list_sub_groups` | `group_id`(必填), `page`, `page_size` | 列出子组织。|
| `cnb_get_group` | `group_id`(必填) | 获取组织详情。|
| `cnb_create_group` | `name`, `path`, `parent_id`(可选) | 创建组织，注意命名唯一性。|

回复中需提示权限要求，必要时引用组织路径。

#### 2. 仓库操作

| 工具 | 参数 | 说明 |
| --- | --- | --- |
| `cnb_list_repositories` | `page`, `page_size` | 返回所有可见仓库。|
| `cnb_list_group_repositories` | `group_id`, `page`, `page_size` | 按组织过滤。|
| `cnb_get_current_repository` | 无 | 获取当前工作区绑定仓库。|
| `cnb_get_repository` | `repo` | 返回仓库元数据（默认分支、可见性等）。|
| `cnb_create_repository` | `group_id`, `name`, `visibility` 等 | 创建仓库，注意最少字段要求。|

**示例**
```json
{
  "command": "python3 scripts/cnb-mcp.py call cnb_get_repository repo=\"demo-app\""
}
```

#### 3. 议题 (Issue) 管理

| 工具 | 参数 | 说明 |
| --- | --- | --- |
| `cnb_list_issues` | `repo`, `state`, `labels`, `page`, `page_size` | 支持筛选状态/标签。|
| `cnb_get_issue` | `repo`, `issue_iid` | 获取单个议题。|
| `cnb_create_issue` | `repo`, `title`, `description`, `assignee_ids` 等 | 创建议题。|
| `cnb_update_issue` | `repo`, `issue_iid`, `title/description/state` | 更新字段。|
| `cnb_list_issue_comments` / `cnb_create_issue_comment` / `cnb_update_issue_comment` | `repo`, `issue_iid`, `comment_id` | 评论增删改。|
| `cnb_list_issue_labels` / `cnb_add_issue_labels` / `cnb_set_issue_labels` / `cnb_clear_issue_labels` / `cnb_remove_issue_label` | `repo`, `issue_iid`, `labels` | 标签管理。|

示例输出应包含议题链接、状态、负责人，若包含标签操作需说明幂等策略。

#### 4. 合并请求 (MR) 管理

| 工具 | 参数 | 说明 |
| --- | --- | --- |
| `cnb_list_pulls` | `repo`, `state`, `page`, `page_size` | 列出 MR。|
| `cnb_get_pull` | `repo`, `merge_request_iid` | 获取 MR 详情。|
| `cnb_create_pull` | `repo`, `source_branch`, `target_branch`, `title` | 创建 MR。|
| `cnb_update_pull` | `repo`, `merge_request_iid`, `title/description/state` | 更新 MR。|
| `cnb_merge_pull` | `repo`, `merge_request_iid`, `merge_commit_message` | 执行合并。|
| `cnb_list_pull_comments` / `cnb_create_pull_comment` | `repo`, `merge_request_iid`, `comment_id` | 评论列表/新增。|

执行合并前需再次确认目标分支及合并策略，避免误操作。

#### 5. 流水线 / 构建管理

| 工具 | 参数 | 说明 |
| --- | --- | --- |
| `cnb_startBuild` | `repo`, `branch`, `variables` | 触发构建。|
| `cnb_stopBuild` | `build_id` | 停止构建。|
| `cnb_getBuildStatus` | `build_id` | 查询状态。|
| `cnb_getBuildLogs` | `repo`, `branch`, `page`, `page_size` | 查询构建列表（根据 README 描述返回构建信息）。|
| `cnb_getBuildStage` | `build_id`, `stage` | 查询阶段详情。|
| `cnb_buildRunnerDownloadLog` | `build_id`, `runner_id` | 下载 Runner 日志。|
| `cnb_buildLogsDelete` | `build_id` | 删除日志，此操作不可恢复，需明确用户授权。|

输出中需注明日志链接有效期或可下载方式。

#### 6. 远程工作空间

| 工具 | 参数 | 说明 |
| --- | --- | --- |
| `cnb_list_workspaces` | `status`, `page`, `page_size` | 列出云原生开发环境。|
| `cnb_delete_workspace` | `workspace_id` | 删除工作空间，提示删除不可恢复。|

#### 7. 知识库查询

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `query` | string | 是 | 中文或英文自然语言问题，最多 512 字符。|
| `filters` | object | 否 | 结构 `{"product":"cicd"}` 用于限定文档域。|

**示例**
```json
{
  "command": "python3 scripts/cnb-mcp.py call cnb_queryKnowledgeBase query=\"如何配置 webhook\""
}
```

如需先了解知识库结构，可使用 `cnb_getKnowledgeBaseInfo` 返回可查询的数据源。

> 当前官方 MCP 工具列表暂未包含制品或 AI 能力。若需此类场景，可在平台推出后更新技能文档，或在回复中说明“该能力暂未由 MCP 工具提供”。

#### 2. 仓库操作

| 工具 | 参数 | 说明 |
| --- | --- | --- |
| `list_repositories` | `remote_url`(string, 可选，支持模糊匹配) | 返回当前账号可见仓库列表。 |
| `get_repository` | `repo`(string, 必填) | 返回仓库元数据（默认分支、更新人等）。 |
| `list_branches` | `repo`, `page`, `page_size` | 默认 `page=1`, `page_size=20`。 |
| `list_commits` | `repo`, `branch`, `limit` | `limit` 默认 10。

**示例**
```json
{
  "command": "python3 scripts/cnb-mcp.py call get_repository repo=\"demo-app\""
}
```

#### 3. 流水线管理

| 工具 | 参数 | 说明 |
| --- | --- | --- |
| `trigger_pipeline` | `repo`(string, 必填), `branch`(string, 默认 main), `variables`(object, 可选) |
| `get_build_status` | `build_id`(string, 必填) |
| `list_builds` | `repo`, `branch`, `limit`(默认 5) |
| `get_build_logs` | `build_id`, `step`(可选) |

**示例**
```json
{
  "command": "python3 scripts/cnb-mcp.py call trigger_pipeline repo=\"demo-app\" branch=\"main\""
}
```

#### 4. 制品管理

| 工具 | 参数 | 说明 |
| --- | --- | --- |
| `list_artifacts` | `project`(string, 必填), `type`(enum: image/pkg/file), `limit` |
| `get_artifact` | `artifact_id`(string, 必填) |
| `promote_artifact` | `artifact_id`, `target_env` |

输出时应提供版本、SHA、可下载链接（如 API 返回）。

#### 5. 远程工作空间

| 工具 | 参数 | 说明 |
| --- | --- | --- |
| `list_workspaces` | `status`(enum: running/stopped/all) |
| `create_workspace` | `template`(string, 必填), `resources`(object，如 `{\"cpu\":4,\"memory\":8}`) |
| `stop_workspace` | `workspace_id` |

需要提醒用户：创建后可能需要 1-2 分钟准备，返回的 `ssh_entry` 或 `web_ide_url` 要在最终回复中明确展示。

#### 6. AI 辅助

| 工具 | 参数 | 说明 |
| --- | --- | --- |
| `invoke_ai_assistant` | `prompt`(string, 必填), `context`(object，可选，例如最近提交) |
| `summarize_diff` | `repo`, `commit_range` |

结果通常包含自然语言建议或结构化摘要，回答时需注明“该建议由 CNB AI 辅助提供”。

## 工作流程

处理用户请求时，遵循以下步骤：

1. **理解意图**：澄清任务范围、资源对象（仓库/流水线/工作空间等）与期望输出。
2. **审查前置条件**：确认 `CNB_TOKEN` 已可用、必要参数齐全。如缺失，向用户追问。
3. **选择工具**：匹配对应模块的 MCP 工具，必要时规划多次调用顺序。
4. **执行命令**：使用 `execute_bash` 工具调用 Python 脚本，并记录请求参数（可在笔记中保存，回复时酌情引用但不泄露 Token）。
5. **解析结果**：检验响应 JSON 结构，处理分页/空结果，必要时串联多次查询。
6. **格式化输出**：套用约定模板，引用文档或构建链接，突出关键信息与后续建议。

## 重要指南

- **使用真实数据**：所有信息必须来源于 MCP 返回的正式数据，不得臆测。
- **最小暴露原则**：不要在回复中出现 `CNB_TOKEN`、内部 ID（除非用户需求）或非公开 URL。
- **引用来源**：知识库回答需附带文档标题或 URL；流水线/制品需提供控制台链接。
- **分页策略**：默认返回平台默认 `limit` 条记录，如用户需要更多，说明如何调整 `page`/`page_size`。
- **并发操作**：同一会话内如需依次调用多个工具，遵守“读→分析→写”顺序，避免同时触发多条危险操作。
- **寻求澄清**：参数不完整时必须追问，示例：缺少 `repo` 或 `workspace_id`。

## 响应格式示例

### 仓库/制品列表模板

```
### 仓库概览
| 序号 | 仓库 | 默认分支 | 最后更新 |
| --- | --- | --- | --- |
| 1 | owner/demo-app | main | 2 小时前 |

> 共返回 X 个，更多请使用 page=2 继续查询。
```

```
### 制品版本
| 版本 | 类型 | SHA | 发布环境 | 操作 |
| --- | --- | --- | --- | --- |
| v1.2.3 | image | sha256:xxxx | staging | [下载](链接)
```

### 流水线状态模板

```
### 构建 #123
- 状态：运行中
- 仓库/分支：demo-app@main
- 触发人：alice
- 开始时间：2026-02-01 10:25 CST
- 日志：<链接>
```

### 知识库回答模板

```
根据 CNB 文档《Webhook 配置》：
1. 在项目设置 > 集成 > Webhook 中点击新增。
2. 选择触发事件并填写回调地址……

参考：https://docs.cnb.cool/zh/.../webhook.html
```

### 远程工作空间/AI 模板

```
### 工作空间 wsp-12345
- 状态：Running（4C/8G）
- 创建时间：2026-02-02 09:12 CST
- 入口：SSH ssh user@host / Web IDE https://...
- 提示：长时间不用请停止以节约配额。
```

```
### AI 建议（CNB AI）
1. 将 CI 构建缓存设置为 S3 以提升速度……
```

## 错误处理

典型错误码及处理建议：

| 错误 | 场景 | 建议回复 |
| --- | --- | --- |
| 401/403 | Token 缺失或权限不足 | “认证失败，请参照 Access Token 指南重新配置 CNB_TOKEN。” |
| 404 | 仓库/流水线不存在 | “未找到 demo-app，请确认名称或所在空间。” |
| 422 | 参数缺失/格式错误 | 指出缺少字段并提示正确格式。 |
| 429 | 触发频率过高 | 建议稍后重试或联系管理员提高限额。 |
| 5xx | 服务端异常 | 告知用户稍后重试并记录 `request_id`（若响应提供）。 |

统一错误回复结构：

```
调用 <工具名> 失败：原因描述。
排查建议：...
request_id：xxxx（若有）
```

## 实际示例

### 示例 1：知识库 + 仓库联动

1. `query_knowledge` 检索 “CNB webhook 配置”。
2. 将返回的文档摘要与链接反馈给用户。
3. 若用户继续要求验证配置，调用 `get_repository` 获取 repo hooks 设置（假设 MCP 工具支持）。

### 示例 2：CI/CD 闭环

1. `trigger_pipeline` 触发指定分支。
2. 轮询 `get_build_status` 直至状态结束，必要时获取 `get_build_logs`。
3. 汇总体、日志链接与下一步建议（如通知相关人、回滚建议）。

### 示例 3：制品推广

1. `list_artifacts` 查最新构建产物。
2. 确认 SHA 与目标环境。
3. 调用 `promote_artifact` 推广，并在回复中提示验证及回滚路径。

### 示例 4：远程工作空间

1. `list_workspaces` 查看资源占用。
2. 若无可用实例则 `create_workspace`。
3. 返回入口地址、安全提醒及清理建议。

### 示例 5：AI 辅助代码审查

1. `summarize_diff` 传入 commit range。
2. 将 AI 返回的重点风险、建议以列表形式呈现，并标注“CNB AI 提示”。

## 记住

- 你正在帮助用户与他们的 CNB 平台交互
- 保持专业、友好、可审计
- 所有信息都应可追溯到工具响应
- 使用统一模板与表格，确保输出一致
- 通过 `execute_bash` 工具执行 Python 脚本来访问 CNB MCP
- 主动提示安全/成本影响（例如长时间运行的工作空间）

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/eryajf) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->