npctalk

npctalk

CNB 交互 CLI —— 通过 issue/PR 评论与 NPC 交互，刷新 build logs 监控 NPC 运行状态。

直接用 npx 运行：

npx npctalk <command> [options]

功能

每个命令均提供单字母短别名，可用别名代替完整命令名，少敲几个字（如 npctalk c = npctalk comment）：

1. comment (c) —— 在 issue / PR 下添加评论，与 NPC 交互
2. issue (i) —— 创建 Issue，工作模式默认开启（work-mode）
3. watch (w) —— 刷新 build logs，监控一个或多个 NPC（构建）的运行状态
4. status (s) —— 一次性查询构建状态
5. list (l) —— 列出未关闭的 issues / prs

安装

只需安装 Node.js（≥ 18）。 装好后即可直接用 npx 运行，无需全局安装：

npx npctalk <command> [options]

首次运行 npx 会提示是否安装 npctalk，回车确认即可，后续直接使用缓存。

如需全局安装（可选）：

npm install -g npctalk
npctalk <command> [options]

开发期未发布时，可 npm run build && node dist/cli.js ... 或 npm link 本地运行。

配置

npctalk 通过以下方式获取 CNB 项目信息，优先级从高到低：

1. CLI 参数（--repo / --token / --endpoint / --npc-name / --config）
2. 当前目录下的 .env.npc 文件（优先于环境变量）
3. CNB_* 环境变量
4. 默认值

.env.npc 示例（复制 .env.npc.example 为 .env.npc 并填值）：

CNB_TOKEN=your_cnb_token_here
CNB_API_ENDPOINT=https://api.cnb.cool
CNB_REPO_SLUG=beilinmo/CNB-NightStar/npctalk
NPC_DEFAULT_EVENT=@npc
NPC_POLL_INTERVAL=5

变量	说明	默认
CNB_TOKEN	CNB API 认证 Token（必填）	-
CNB_API_ENDPOINT	CNB API 基础地址	https://api.cnb.cool
CNB_REPO_SLUG	默认仓库 slug（组织名/仓库名）	-
NPC_DEFAULT_EVENT	watch / status 默认按触发方式过滤的 event 子串	@npc
NPC_POLL_INTERVAL	watch 轮询间隔（秒）	5
CNB_NPC_NAME	comment 自动 @ 的 NPC 名称（body 首行未以 @ 开头时插入）	@XMZZUZHI/SuperNPC(妲己)

命令

短别名：每个命令均支持单字母别名 —— c=comment、i=issue、w=watch、s=status、l=list。下文示例统一用完整命令名，别名完全等价。

comment —— 与 NPC 交互

# 目标可以是 iid 数字或完整 URL（自动解析 repo+type+iid）
npctalk comment 1 --body "请尽情吩咐妲己，主人~"            # 纯数字 iid 未指定 --type 时自动探测
npctalk comment 1 --type issue --body "请尽情吩咐妲己，主人~"  # 也可显式指定类型
npctalk comment https://cnb.cool/beilinmo/CNB-NightStar/qemu-cnb/-/pulls/23 --body "LGTM"

# 从文件读取
npctalk comment 1 -t issue --body @./reply.md

# 从 stdin 读取（管道）
echo "body text" | npctalk comment 1 -t issue --body -
echo "body text" | npctalk comment 1 -t issue        # --body 缺省时自动读 stdin

# 工作模式默认开启（仅 issue 评论支持；PR 评论将忽略并提示）
npctalk comment 1 -t issue --body "开始干活"
# --no-work-mode 关闭工作模式
npctalk comment 1 -t issue --body "随便聊聊" --no-work-mode

参数	说明
<target>	iid 数字 或 完整 URL
-t, --type <issue|pr>	可选；纯数字 iid 未指定时自动探测，URL 自动识别
-b, --body <text|@file|->	评论内容；@file 读文件，- 或缺省读 stdin
--no-work-mode	关闭工作模式（默认开启；仅 issue 评论支持；PR 评论将忽略并提示）

自动 @ NPC：若 --body 首行未以 @ 开头，会自动在首行前插入 CNB_NPC_NAME（默认 @XMZZUZHI/SuperNPC(妲己)，可用 --npc-name 覆盖），确保评论能触发对应 NPC；传 --npc-name "" 可禁用。

watch —— 监控 NPC 运行状态

NPC 运行 = 一次流水线 build，监控 build 状态即监控 NPC。

# 监控指定构建（sn），全部到达终态后自动退出
npctalk watch cnb-5bo-1jrp5a8d5 cnb-cno-1jrp4gf8j

# 不传 sn：按触发方式过滤 pending 构建（默认 @npc，即监控所有 NPC 触发的构建）
npctalk watch
npctalk watch --event issue.comment      # 只看 issue 评论触发的构建
npctalk watch --event push                # 只看 push 触发的构建
npctalk watch --all                       # 不过滤，监控全部 pending
npctalk watch --once                      # 只快照一次，不轮询
npctalk watch --interval 10               # 每 10s 轮询一次

参数	说明
[sn...]	一个或多个构建 SN；不传则进入列表过滤模式
-e, --event <pattern>	按触发方式（event 字段）过滤，子串匹配；默认 @npc
-a, --all	不过滤，监控全部 pending 构建
-i, --interval <sec>	轮询间隔（秒），默认取 NPC_POLL_INTERVAL（5）
-o, --once	只快照一次，不轮询

关于"触发方式"过滤：CNB build 的 event 字段记录触发方式，如 issue.comment@npc（issue 评论 @NPC 触发）、pull_request.comment@npc、push、tag 等。--event 做子串匹配，例如 @npc 覆盖所有 NPC 触发的构建，issue.comment 覆盖所有 issue 评论触发的构建。

status —— 一次性查询

npctalk status cnb-5bo-1jrp5a8d5           # 查指定构建状态
npctalk status                             # 按触发方式列出最近构建（默认 @npc）
npctalk status --all                        # 列出全部最近构建

list —— 列出未关闭的 issues / prs

默认列出未关闭（state=open）的 issues 与 prs，可限定范围或切换状态。

npctalk list                       # 列出未关闭的 issues + prs
npctalk list issues                 # 只列未关闭的 issues
npctalk list prs                    # 只列未关闭的 prs
npctalk list --state closed         # 改列已关闭的
npctalk list --state all            # 列出全部（含已关闭）
npctalk list --limit 50             # 每类最多 50 条
npctalk list issues --label bug      # 按标签过滤（可多次传入或逗号分隔）
npctalk list prs --author yuxin      # 按作者过滤
npctalk list --repo beilinmo/CNB-NightStar/npctalk

参数	说明
[scope]	可选：issues | prs（缺省两者都列）
-s, --state <open|closed|all>	状态过滤，默认 open（未关闭）
-n, --limit <n>	每类最多返回条数（默认 30）
-l, --label <name>	标签过滤（可多次传入，也可逗号分隔）
-A, --author <name>	作者过滤，多个用英文逗号分隔
-a, --assignee <name>	处理人过滤（可多次传入，也可逗号分隔）
-r, --repo <slug>	CNB 仓库 slug，覆盖 CNB_REPO_SLUG

issue —— 创建 Issue

创建 Issue 与 NPC 交互，工作模式默认开启（work-mode）。

# 最简：标题必填，body 支持 @file / - / stdin（工作模式默认开启）
npctalk issue --title "开启上班模式" --text "请尽情吩咐妲己，主人~"

# body 从文件读取；--no-work-mode 关闭工作模式
npctalk issue --title "开启上班模式" --no-work-mode --text @./body.md

# 指定仓库、标签、处理人、优先级（label/assignee 可多次传入）
npctalk issue --repo beilinmo/CNB-NightStar/npctalk \
  --title "上线监控" --label monitoring --label p1 \
  --assignee yuxin --priority P1

# 从 stdin 读取 body
echo "正文内容" | npctalk issue --title "标题"

# 不自动在 body 首行插入 @npc_name
npctalk issue --title "纯文本记录" --without-npc --text "仅记录，不@NPC"

参数	说明
-T, --title <title>	Issue 标题（必填，长度 2-255）
-t, --text <text|@file|->	Issue 内容；@file 读文件，- 或缺省读 stdin
--no-work-mode	关闭工作模式（默认开启）
--without-npc	不自动在 body 首行插入 @npc_name（默认开启自动插入）
-r, --repo <slug>	CNB 仓库 slug，覆盖 CNB_REPO_SLUG
-l, --label <name>	Issue 标签（可多次传入，最多 10）
-a, --assignee <name>	Issue 处理人（可多次传入，最多 8）
-p, --priority <p>	优先级：-2P / -1P / P0 / P1 / P2 / P3

自动 @ NPC：若 --text 首行未以 @ 开头，会自动在首行前插入 CNB_NPC_NAME（默认 @XMZZUZHI/SuperNPC(妲己)，可用 --npc-name 覆盖），确保创建的 Issue 能触发对应 NPC；传 --without-npc 可禁用。--text 缺省（空 body）时仅插入 @npc_name。

work-mode 说明：work_mode 是 CNB「创建 issue 评论」「创建 issue」接口的请求体 boolean 字段（PR 评论接口不支持）。缺省即为 true（通知 NPC 进入工作模式），传 --no-work-mode 置为 false 关闭。

全局参数

参数	说明
--config <path>	指定 .env.npc 路径
--repo <slug>	覆盖 CNB_REPO_SLUG
--token <token>	覆盖 CNB_TOKEN
--endpoint <url>	覆盖 CNB_API_ENDPOINT
--npc-name <name>	覆盖 CNB_NPC_NAME（评论自动 @ 的 NPC 名称）
-v, --version	版本
-h, --help	帮助

技术栈

• TypeScript + tsup 打包（发布为单文件零运行时依赖）
• commander（CLI 框架）
• Node 内置 fetch（要求 Node >= 18）

开发

npm install
npm run build        # 构建 dist/cli.js
npm run typecheck    # 类型检查
npm run dev          # watch 模式构建

版本与发布

版本采用简单的 x.x.x 语义化版本号（见 package.json 的 version 字段），由 .cnb.yml 流水线自动发布到 npmjs.org。

发布规则：

• push 到 main 分支时，流水线读取 package.json 的 version，检查该版本是否已在 npmjs.org 发布过：
  • 版本未变化（已发布过） → 自动跳过发布，不会重复推送。
  • 版本未发布（新版本号） → 执行 npm publish --access public。
• 不使用 dev 预发布版本号，也无需打 git tag。

如何发版：需要发布新版本时，把 package.json 的 version 加一位（如 1.2.1 → 1.2.2），提交并 push 到 main 即可，流水线会自动检测到新版本并发布。

例如当前已发布 1.2.1，将 version 改为 1.2.2 后 push，流水线检测到 1.2.2 未发布即发布；若 version 仍为 1.2.1，则自动跳过。

License

MIT