npcplay

一个用于 CNB 平台的 Node.js CLI，可通过评论召唤 NPC，并监控一个或多个 NPC 构建状态。

当前仓库已经完成首版 CLI 骨架和核心流程实现。

当前 npm 包名与 CLI 可执行名统一使用 npcplay。

快速开始

1. 准备配置文件：

cp .env.npc.example .env.npc

2. 填写至少这些配置：

CNB_API_ENDPOINT=https://api.cnb.cool
CNB_WEB_ENDPOINT=https://cnb.cool
CNB_REPO_SLUG=beilinmo/CNB-NightStar/qemu-cnb
CNB_TOKEN=your_cnb_token_here
# 或使用 CNB_TOKEN_FILE=/path/to/token-file，从文件读取 token，优先级高于 CNB_TOKEN
CNB_NPC_NAME=@XMZZUZHI/SuperNPC(妲己)

3. 直接运行：

npx npcplay --help

常用命令：

# 新建 issue
npx npcplay create-issue --title "构建日志接口异常" --file ./issue.md
npx npcplay ci -T "构建日志接口异常" -f ./issue.md

# 新建 issue 默认会自动召唤 NPC
npx npcplay create-issue --title "请分析这个问题" --file ./issue.md
npx npcplay ci -T "请分析这个问题" -f ./issue.md

# 如果不想召唤 NPC
npx npcplay create-issue --title "普通问题" --file ./issue.md --without-npc
npx npcplay ci -T "普通问题" -f ./issue.md -W


# 列出 PR / Issues
npx npcplay list-prs --state open --page 1 --page-size 20
npx npcplay list-issues --state open --page 1 --page-size 20
npx npcplay lp -s open -p 1 -n 20
npx npcplay li -s open -p 1 -n 20

# 给 PR / Issue 发评论
npx npcplay comment --pr 23 --file ./comment.md
npx npcplay comment --issue 15 --file ./issue-comment.md
npx npcplay c -p 23 -f ./comment.md
npx npcplay c -i 15 -f ./issue-comment.md
npx npcplay c -p 23 -t "请检查最近的变更"

# 评论后等待 NPC 构建完成
printf '请帮我检查最近的变更' | npx npcplay comment --pr 23 --wait
printf '请帮我检查最近的变更' | npx npcplay c -p 23 -w

# 监控构建
npx npcplay watch --pr 23
npx npcplay watch --build 123456789
npx npcplay watch --pr 23 --all-running
npx npcplay w -p 23
npx npcplay w -b 123456789
npx npcplay w -p 23 -a

# 辅助调试
npx npcplay resolve-target --pr "https://cnb.cool/foo/bar/-/pulls/23"
npx npcplay builds --pr 23 --debug
npx npcplay rt -p "https://cnb.cool/foo/bar/-/pulls/23"
npx npcplay b -p 23 -d

简写别名

为方便高频使用，CLI 现在同时支持命令别名和短参数：

• comment -> c
• create-issue -> ci
• list-prs -> lp
• list-issues -> li
• watch -> w
• resolve-target -> rt
• builds -> b

常用短参数：

• -e = --env-file
• -p = --pr 或当前命令内的 --page
• -i = --issue
• -b = --build
• -f = --file
• -t = --text（comment 与 create-issue）
• -T = create-issue --title
• -r = --repo
• -s = --state
• -n = --page-size
• -w = --wait
• -a = --all-running
• -d = --debug
• -W = --without-npc
• -j = --json

位置参数简写

除短参数外，部分命令还支持位置参数简写，便于快速输入：

• #123 作为最后一个位置参数时，等价于 --pr 123 / --issue 123： CLI 会自动探测该 IID 是 PR 还是 Issue（先查 Issue，再查 PR）。 需要 CNB_REPO_SLUG 或显式的 --pr/--issue URL 提供仓库上下文。
• comment 与 create-issue 允许额外传入一段字符串作为正文， 等价于 --text "..."，例如 npcplay comment #123 "请帮我检查这段变更"。

注意：# 在多数 shell 中是注释符号，作为位置参数使用时需用引号包裹， 例如 npcplay c '#15' "请帮我检查这段变更"。

规则与冲突处理：

• # 简写与 --pr/--issue 互斥，同时传入会报错。
• 至多允许一个 # 简写参数。
• 当同时传入位置正文与 --text/--file 时会报错，二者只能选其一。
• create-issue 不接收 # 目标简写（它用于新建 Issue）。

示例：

# 等价：npcplay comment --issue 15 --text "请帮我检查这段变更"
npx npcplay c #15 "请帮我检查这段变更"

# 等价：npx npcplay watch --pr 23
npx npcplay w #23

# 等价：npx npcplay builds --issue 9 --debug
npx npcplay b #9 --debug

安装与运行

已发布到 npm，可直接运行：

npx npcplay --help

本地开发运行：

npm install
npm run build
npx npcplay --help

辅助调试命令：

npx npcplay resolve-target --pr "https://cnb.cool/foo/bar/-/pulls/23"
npx npcplay builds --pr 23
npx npcplay builds --pr 23 --all-running
npx npcplay builds --pr 23 --debug

开发态直接运行源码：

npm run dev -- --help

如果后续需要兼容旧名称，再补充别名入口。

配置文件

项目支持在当前工作目录放置 .env.npc，也支持通过全局参数 --env-file 或环境变量 NPC_CFG_ENV 指定配置文件路径。

可以直接从示例文件开始：

cp .env.npc.example .env.npc

当前实现按下面顺序解析配置文件，未声明的字段再回退到进程环境变量和 CNB_* 环境变量：

• --env-file <path>
• NPC_CFG_ENV
• 当前工作目录下的 .env.npc

示例：

npx npcplay --env-file ./.config/npc.dev.env comment --pr 23 --file ./comment.md
NPC_CFG_ENV=./envs/test.npc.env npx npcplay watch --pr 23

示例文件：

CNB_API_ENDPOINT=https://api.cnb.cool
CNB_WEB_ENDPOINT=https://cnb.cool
CNB_REPO_SLUG=beilinmo/CNB-NightStar/qemu-cnb
CNB_TOKEN=your_cnb_token_here
# CNB_TOKEN_FILE=/path/to/token-file
CNB_NPC_NAME=@XMZZUZHI/SuperNPC(妲己)
NPC_DEFAULT_POLL_INTERVAL_MS=5000
NPC_DEFAULT_TIMEOUT_MS=1800000

字段说明：

• CNB_API_ENDPOINT: CNB HTTP API 地址
• CNB_WEB_ENDPOINT: CNB Web 地址，用于生成构建日志链接
• CNB_REPO_SLUG: 当前默认仓库路径，使用纯 IID 时必须依赖它解析目标
• CNB_TOKEN: CNB 访问令牌，用于评论、读取 comments、读取构建状态和日志
• CNB_TOKEN_FILE: CNB 访问令牌文件路径；设置后从文件读取 token，优先级高于 CNB_TOKEN
• CNB_NPC_NAME: 默认 NPC mention；当 comment 正文首行未以该完整 mention 开始时会自动插入；构建发现也只接受以该 mention 开始的评论
• NPC_DEFAULT_POLL_INTERVAL_MS: watch 轮询间隔，单位毫秒
• NPC_DEFAULT_TIMEOUT_MS: watch 总超时，单位毫秒

默认 NPC mention 为：

@XMZZUZHI/SuperNPC(妲己)

预期使用方式

1. 评论交互

新建 Issue：

npx npcplay create-issue --title "构建日志接口异常" --file ./issue.md

通过 --text 直接输入 Issue 正文：

npx npcplay create-issue --title "构建日志接口异常" --text "构建日志接口在 watch 期间返回 502。"

创建 Issue 时默认自动召唤 NPC：

npx npcplay create-issue --title "请分析这个问题" --file ./issue.md

如果不想召唤 NPC：

npx npcplay create-issue --title "普通问题" --file ./issue.md --without-npc

通过 stdin 新建 Issue：

printf '构建日志接口在 watch 期间返回 502。' | npx npcplay create-issue --title "构建日志接口异常"

列出仓库 PR：

npx npcplay list-prs --state open --page 1 --page-size 20

列出仓库 Issues：

npx npcplay list-issues --state open --page 1 --page-size 20

list-issues 会查询关联的 NPC 调用；每个调用显示分发结果或关联构建状态（pending、running、success、failed、canceled、skipped）。

对 PR 评论：

npx npcplay comment --pr 23 --file ./comment.md

通过文件输入评论内容：

npx npcplay comment --pr 23 --file ./comment.md

通过 --text 直接输入评论内容：

npx npcplay comment --pr 23 --text "请帮我检查最近的变更"
npx npcplay c -p 23 -t "请帮我检查最近的变更"

--text 与 --file 不能同时使用；两者都未提供时，从 stdin 读取评论内容。

通过 stdin 输入评论内容：

printf '请帮我检查最近的变更' | npx npcplay comment --pr 23

评论后等待这次触发的 NPC build 结束：

printf '请帮我检查最近的变更' | npx npcplay comment --pr 23 --wait

真实验证过的 PR 评论命令：

printf '请帮我测试一下 npcplay 的评论和构建发现链路。' | npx npcplay comment --pr 27

对 Issue 评论：

npx npcplay comment --issue 15 --file ./issue-comment.md

通过 URL 指定目标：

npx npcplay comment --pr "https://cnb.cool/beilinmo/CNB-NightStar/qemu-cnb/-/pulls/23" --file ./comment.md

2. 监控 NPC 运行状态

监控某个 PR 相关构建：

npx npcplay watch --pr 23

真实验证过的 PR watch 命令：

npx npcplay watch --pr 27

监控某个 Issue 触发的 NPC 构建：

npx npcplay watch --issue 15

按构建号监控：

npx npcplay watch --build 123456789

真实验证过的 build watch 命令：

npx npcplay watch --build cnb-4ko-1jrp7aqji

监控多个构建：

npx npcplay watch --build 123 --build 456 --build 789

监控某个 PR / Issue 下所有未完成 NPC 构建：

npx npcplay watch --pr 23 --all-running

当前状态

以下链路已经在真实 CNB 仓库中验证通过：

• .env.npc 配置加载
• comment 从 stdin 或 --file 读取正文
• create-issue 从 stdin 或 --file 读取正文
• 未提供 --file 且未使用管道时，可直接在控制台输入多行正文，并使用 Ctrl-D 结束输入
• list-prs 支持按状态分页列出 PR
• list-issues 支持按状态分页列出 Issue，并显示关联 NPC 调用及构建状态
• 若正文首行没有完整的 CNB_NPC_NAME mention，则自动插入该 mention
• PR comment 写入
• PR comments 回读
• 按完整的配置 NPC mention 识别构建关联评论
• 从 comments 中提取真实 build SN
• watch --build <sn>
• watch --pr <iid>
• 构建状态摘要和最近日志摘要输出

当前已在真实环境验证通过的命令形态：

printf '请帮我测试一下 npcplay 的评论和构建发现链路。' | npx npcplay comment --pr 27
printf '请帮我测试一下 npcplay 的评论和构建发现链路。' | npx npcplay comment --pr 27 --wait
npx npcplay builds --pr 27 --debug
npx npcplay watch --pr 27
npx npcplay watch --build cnb-4ko-1jrp7aqji

当前限制：

• watch --pr 当前主要通过 comments 中的 build SN 做关联
• watch --issue 还未完成真实环境验证
• watch --pr/--issue --all-running 的“列出当前目标下所有未完成构建”仍在继续适配 CNB 的真实构建列表接口
• 构建列表相关 HTTP endpoint 目前未完全收紧，必要时会回退 cnb CLI