cnb-skill

name	cnb-skill
description	CNB 平台操作助手 - 帮助用户管理 CI/CD、代码仓库、流水线和查询文档

CNB 平台助手技能

概述

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

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

配置与前置条件

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

配置示例 (.env 文件)：

# CNB 配置
CNB_TOKEN=your_cnb_access_token_here
# CNB_MCP_URL=https://mcp.cnb.cool/mcp  # 可选，使用自定义端点时配置

工具调用方式

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

1. 列出工具

   {
     "command": "python3 scripts/cnb-mcp.py list-tools"
   }
   

2. 调用工具

   {
     "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 等	创建仓库，注意最少字段要求。

示例

{
  "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"} 用于限定文档域。

示例

{
  "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。

示例

{
  "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(可选)

示例

{
  "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
• 主动提示安全/成本影响（例如长时间运行的工作空间）