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 --text "请尽情吩咐妲己，主人~"            # 纯数字 iid 未指定 --issue/--pr 时自动探测
npctalk comment 1 --issue --text "请尽情吩咐妲己，主人~"  # 也可 --issue / --pr 显式指定类型
npctalk comment https://cnb.cool/beilinmo/CNB-NightStar/qemu-cnb/-/pulls/23 --text "LGTM"

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

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

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

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

自动 @ NPC：若 --text 首行未以 @ 开头，会自动在首行前插入 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