跳到主要内容

生态周边：徽章、任务集、CLI、OpenAPI

平台本身的能力讲完了。这篇收几个"用起来才知道好用"的周边。

一、徽章：让 README 自己说话​

构建状态、覆盖率都能做成 SVG 徽章嵌进 README。路径格式：

latest：      https://cnb.cool/{组织}/{仓库}/-/badge/git/latest/{metrics}
指定分支：    https://cnb.cool/{组织}/{仓库}/-/badge/git/latest/{metrics}?branch=main
指定 commit： https://cnb.cool/{组织}/{仓库}/-/badge/git/{sha前8位}/{metrics}

常用 metrics：

metrics是什么
ci/status/pushpush 事件构建状态与耗时
ci/status/pull_requestPR 构建状态
ci/status/tag_pushTag 构建状态
coverage全量覆盖率

sha 位置填 latest 时不指定 branch 就取默认分支最新 commit。

二、任务集：跨仓库的看板​

仓库多了之后，Issue 散在十个仓库里没法管。任务集就是解决这个的。

创建时选数据范围（哪几个仓库），之后它会把那些仓库的 Issue/PR 聚合过来。

三种视图各有用途：

  • 表格：批量改属性、筛选、排序、导出
  • 看板：按状态流转，拖拽改优先级
  • 甘特：排期，规划 Issue 起止时间

几个实用功能：

功能场景
导出视图数据按当前筛选条件导出，给周报用
分组排序按数量/名称升降序，看清分布
颜色管理按标签颜色快速筛选（表格）/ 改时间轴颜色（甘特）
自定义属性补充仓库属性维度，跨仓库同 key 会合并
快速预览不跳转看事项详情

权限模型要理解清楚：要访问任务集需同时满足"你是任务集成员"和"你是关联仓库成员"。在任务集里对某个 Issue 的操作权限，跟你在它所属仓库里的权限一致。

成员角色分「任务集成员」和「外部协作者」，后者适合临时参与的人。

三、CNB CLI：命令行调平台​

底层是 OpenAPI 的封装，提供 cnb 命令。在 NPC 运行时镜像里它就是基础依赖。

装法：

npm install -g @cnbcool/cnb-cli

它也是 Skills 的底座——AI 通过 cnb 命令调平台能力。

四、OpenAPI：自己写集成​

服务地址和文档在同一处，认证就一行 Header：

curl -X "GET" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <你的令牌>" \
  "https://api.cnb.cool/user/groups?page=1&page_size=10"

两篇文档值得先看：

  • Open API：地址、认证、调用方式
  • 仓库动态：按时间回溯仓库里发生了什么

五、仓库动态：做审计和活跃度分析​

/events/{repo_path}/-/{date} 能按小时或按天查事件。支持的事件类型挺全：

CreateEvent、DeleteEvent、ForkEvent、IssueCommentEvent、IssueEvent、MemberEvent、PublicEvent、PullRequestEvent、PullRequestReviewEvent、PullRequestReviewCommentEvent、PushEvent、ReleaseEvent、WatchEvent

curl -H "Authorization: Bearer <token>" \
  "https://api.cnb.cool/events/my-group/my-repo/-/2025-09-11-7"

:::warning 按天查有滞后 按小时查是实时的；按天查当天只能拿到前一天的聚合数据，有一天延迟。 :::

适合做：代码审计、把 PR/Issue 变更同步到自建系统、统计仓库活跃度。

六、几个"知道了能省事"的细节​

默认权限要看清

令牌创建后，公开资源默认只读，私有资源默认无权限。很多人第一次调 API 返回 403 就是这个原因。

部署令牌 ≠ 访问令牌

部署令牌访问令牌
权限仅只读可配读写/只读
用户属性无，仅关联资源关联用户，继承其权限
适用CI/CD 拉代码、只读脚本日常操作、写操作

部署令牌适合放在 CI 里做无人值守拉取：

git clone https://cnb:${DEPLOY_KEY}@cnb.cool/my-group/my-repo

Skills 也能自己写

在项目的 .codebuddy/skills/ 下建目录，放一个 SKILL.md 描述能力和用法，NPC 会自动识别加载。

.codebuddy/skills/
  my-skill/
    SKILL.md

注意同名时全局级覆盖项目级——仓库里的旧副本不会顶掉镜像里的新版本。

七、这一段旅程的收尾​

从注册到自动化发布，这套东西的核心其实只有一句话：

把"靠人记住的流程"变成"写在仓库里的代码"。

.cnb.yml、.cnb/settings.yml、.ide/Dockerfile、.cnb/ISSUE_TEMPLATE/——这些文件合起来，就是一个项目的"运作说明书"。它跟着代码一起版本化、一起评审、一起演进。

新人 clone 下来，不需要有人带，环境、构建、发布规则全都在里面。

这才是 CI/CD 真正的价值：不是省几次点击，而是让流程本身可传承。