novu/human 实战指南为 AI Agent 构建人类介入通道的 CLI 全解析【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novunovu/human仓库路径 packages/human是 Novu 开源通信基础设施中面向 Agent 的人类 API它让运行在服务器、CI、容器或无人值守环境中的 AI Agent用一行命令即可在 Telegram、Slack、Email 上触达真人并阻塞等待其答复。本文以该包的官方 README 为主体结合仓库源码index.ts、config.ts、interact.ts、setup.ts 等深入讲解安装、接入、四种交互命令、退出码契约、无头运行与技能注入读完你即可在自己的 Agent 工作流中接入安全可靠的人工审批环节。一、为什么需要人类 APIAgent 与真人的最后一公里Agent 已能连接一切——数据库、API、CI、云服务——唯独连接不上它所服务的人类。novu/human的定位正是补齐这一环给 Agent 一条一行命令触达真人、并阻塞等待其回应的通道。它不是一个聊天机器人框架而是一个面向自动化流程的人在环内human-in-the-loop基础设施。从 package.json 可以看到该包以human作为 bin 入口bin: { human: ./dist/src/index.js }核心依赖仅有commanderCLI 解析、axiosHTTP 调用、qrcodeTelegram 二维码渲染和picocolors终端着色轻量、无需常驻服务非常适合嵌入各种 Agent 运行时。当前版本v0.3.0支持 Telegram最快的私有 Bot 通道、Slack工作区 App 安装与 Email按钮邮件 回复即回答通道能力不断扩展中。核心交互模型非常简单Agent 发起一次交互 → 消息带操作按钮投递到真人 → 真人通过点击按钮或直接回复作答 → CLI 解析结果、进程继续执行。二、快速上手从 setup 到第一次人工审批2.1 一次性设置由真人完成setup是整个体系的起点必须由真实的人类来执行。它负责三件事创建一个免密钥keyless的 Novu 环境无需注册账号、部署一个隐藏的 relay 中转 Agent、把你的个人通道与你的 subscriber 身份绑定。# 一次性操作交互式选择通道或直接指定通道名 npx novu/human setup npx novu/human setup telegram npx novu/human setup slack npx novu/human setup email三种通道的接入方式各有不同源码见 setup.tsTelegram需要先在 BotFather 创建一个私有 Bot 并拿到 token格式为123456:ABC-...源码promptForBotToken会做格式校验。CLI 生成一个移动端 deep link终端渲染 QR 码扫码后在 Telegram 点Start即完成绑定随后 CLI 轮询等待 channel endpoint 生效。Slack通过 Slack App 安装OAuth 授权接入。若集成尚无凭据CLI 会引导生成App Configuration Tokenxoxe.xoxp-...格式并做严格的 token 类型校验拒绝xoxb-bot token、xapp-app-level token 等误用支持交互粘贴、--slack-config-token直传以及无头模式下发放安全配置页等待回填。Email无需链接舞蹈——relay 获得一个共享入站邮箱地址你的身份即订阅者上的 email 字段审批类交互以按钮邮件送达回答类交互直接回复邮件即可。setup完成后会向刚绑定的通道发送一条冒烟测试消息源码中createInteraction的tell调用并提示你可以立即尝试human approve Deploy to production?。2.2 之后的一切Agent 一行命令触达真人设置完成后机器上的任何 Agent 都可以直接使用human ask Which environment should I deploy to? human approve Delete 342 stale records from prod? human choose Pick a release strategy --option canary --option blue-green human tell Nightly build finished — 0 failures.每次调用都会投递一条一次性消息必要时携带操作按钮并阻塞直到人类回答、--ttl过期或--timeout超时答案通过按钮点击或普通回复回流CLI 解析后进程继续。2.3 链接更多人类invite 与 contactsinvite用于把另一个不同的订阅者接入同一环境与 Slack/Telegram 的 connect 流程一致OAuth 或 deep link → 通道端点。被邀请者打开你发给他的 URL 即可完成绑定不会改变你本地~/.novu/human.json中的身份human invite alice --via slack --name Alice Chen human invite bob --via telegram --async human invite carol --via email --email carolacme.com--name会拆分为 firstName/lastName源码splitName按首个空格切分用于在contacts中按名字展示--async表示只打印连接 URL 立即返回不阻塞等待对方完成绑定。contacts则列出环境中所有 Agent 可用--to寻址的订阅者相当于目录而非可达性检查human contacts human contacts --json--json输出{ data, next }每行携带self: true标记你自己分页默认 50 条--limit范围 1–100见 contacts.ts有下一页时用human contacts --after next继续翻页。如果向某人投递失败并提示 no linked endpoint说明对方尚未连接该通道需要用human invite id --via channel邀请后再试。三、四种交互原语ask / approve / choose / tellnovu/human的交互能力收敛为四种原语InteractionKind定义见 api/human.ts覆盖 Agent 与人类打交道的全部典型场景命令用途交互形式阻塞行为ask提出开放性问题普通消息人类自由回复阻塞至回复approve请求批准高风险操作Approve/Deny 按钮阻塞至点击choose多选一决策选项按钮阻塞至选择tell单向通知普通消息投递成功即返回不阻塞源码中四个命令共用同一个执行引擎runInteractioninteract.ts通过kind区分行为。choose要求--option至少 2 个、最多 10 个CLI 层校验超出应改为普通提问ask/choose的答案以纯文本返回 stdoutapprove/choose投递可点击按钮。值得一提的实现细节tell与--async在交互创建后立即返回源码process.exit(emitResult(created, ...))而其余情况进入waitForResolution轮询循环——每 2 秒轮询一次交互状态POLL_INTERVAL_MS 2000而非长连接挂起因此 Ctrl-C 可以即时干净地中断不留服务端泄漏的连接。四、阻塞、超时与恢复等待语义全解默认情况下四个交互命令都会阻塞等待人类答复并在 stderr 上显示实时 spinnerstdout 保持干净以利于脚本解析。围绕等待有三个关键参数--timeout 10m本次调用最多阻塞多久。超时后 CLI 打印交互 id 并以退出码11结束后续可用human wait id恢复等待。--async完全不阻塞立即打印交互 id稍后用human wait id或human list检查结果。--ttl 2h请求保持可答复的时长默认 24h最大 72h。--ttl决定消息存活多久--timeout决定本次进程等多久两者独立。等待相关辅助命令human list # 列出最近交互--status 过滤 pending/answered/denied 等默认 20 条 human wait id # 恢复阻塞等待一个 pending 交互 human cancel id # 撤销 pending 请求按钮随之失效human wait id内部先拉取当前状态getInteraction若已非 pending 则直接输出结果仍 pending 则复用同一轮询引擎继续等待wait.ts。human cancel通过POST /v1/human/interactions/{id}/cancel使交互进入canceled状态。五、退出码契约Agent 分支判断的稳定协议对于自动化调用方基于退出码分支而非解析人类可读文本——这是 README 强调的稳定契约。定义见 output.ts退出码含义对应交互状态0已答复 / 已批准 / 已选择 / 已投递answered、approved、deliveredchoose的answered亦为 010被拒绝denied11等待超时——仍 pending可用human wait id恢复默认其余所有 pending 情况12已过期或已取消expired、canceled1错误未设置、参数错误、网络/鉴权失败—Shell 中的典型用法if human approve Deploy to production?; then echo approved, proceeding else code$? if [ $code -eq 10 ]; then echo denied, stopping; exit 1; fi if [ $code -eq 11 ]; then echo no answer yet, will resume: human wait id; fi fi需要结构化数据时给任意命令加--json即可拿到完整交互对象id、status、prompt、options、response、respondedBy、时间戳等字段定义见 api/human.ts 的Interaction接口避免解析 stdout 文本。六、常用参数详解--from deploy-bot— 展示给人类的署名Requested by deploy-bot。有稳定身份时务必设置临时 ad hoc 调用可省略。--ttl 2h— 请求保持可答复时长默认 24h、最大 72h。时间敏感的操作应缩短 TTL防止几天后仍可执行一个过期的批准。--timeout 10m— 本次调用最大阻塞时长超时打印交互 id 以便human wait id恢复。--async— 不阻塞立即打印交互 id。--json— 输出完整交互对象便于程序化解析。--to humanId— 指定已链接的人类human contacts查找、human invite新增。支持逗号分隔多人如alice,bob最多 50 人任意一人答复即生效见 interact.ts 的MAX_HUMAN_TO。--via platform— 指定投递通道telegram、slack、email覆盖默认通道偏好。关于--to的解析有一个严谨的细节parseHumanToOption会先去重new Set、剔除空段再校验非空与上限 50非法输入直接报错退出防止 Agent 传入脏数据。七、通道无关的架构设计路由是人的偏好不是 Agent 的事novu/human有一个刻意设计的原则Agent 保持通道盲channel-blind。Agent 不需要知道人类此刻在 Telegram 还是 Slack 上——路由决策是人类的偏好。setup时第一次绑定的通道会成为本地默认通道偏好再次运行setup绑定新通道即可叠加。已链接的通道保存在服务端relay 集成 endpoint本地human.json只记录默认偏好。human channels --default slack可随时切换本地默认偏好影响所有未显式传--via的交互。--via telegram|slack|email在 ask/approve 等命令上只是罕见的按调用覆盖delivery override不是 onboarding 新人的方式——绑定新通道永远走setup或invite。配置结构中defaultChannel字段的注释也印证了这一点Linked channels themselves live on the server — this is only a local preferenceconfig.ts。八、认证与无头运行从 keyless 演示到生产环境8.1 认证方式setup将凭据存储在~/.novu/human.json可用NOVU_HUMAN_CONFIG环境变量覆盖路径见 config.ts 的configPath()。文件以0600权限写入包含apiUrl、authkeyless或apiKey模式、relayAgentIdentifier、subscriberId、defaultChannel等字段。对于已有 Novu 环境的用户可以跳过setup直接设置export NOVU_SECRET_KEYsk_... # 使用现有 Novu 环境 # 可选export NOVU_API_URLhttps://api.novu.co8.2 keyless 演示环境与配额上限setup创建的 keyless 环境是免费演示环境带有少量消息额度。当额度耗尽时下一条命令不会投递消息而是以退出码1退出并输出注册链接同一个链接也会发送到你的已绑定通道上。对应的错误识别逻辑在 interact.ts 的getKeylessCapDetails中HTTP 429 错误码KEYLESS_HUMAN_CAP_REACHED。恢复方式真人注册账号并认领演示环境——你的通道和 relay 会迁移到自己的 Development 环境用human setup --secret-key key或NOVU_SECRET_KEY让 CLI 指向新环境。8.3 容器 / 沙箱 / CI 中的纯环境变量运行在没有任何配置文件存在的容器、沙箱和 CI 中CLI 可以仅凭环境变量完整运行docker run -e NOVU_SECRET_KEY... -e HUMAN_TOalice -e HUMAN_VIAslack agent \ npx novu/human approve Deploy to prod?两个关键环境变量HUMAN_TO— 默认接收者 subscriberId 列表逗号分隔语义同--to上限 50。HUMAN_VIA— 默认通道telegram、slack、email语义同--via非法值会直接报错源码resolveVia校验。优先级永远是CLI 参数 环境变量 ~/.novu/human.json且环境变量值永远不会回写配置文件。resolveConfigconfig.ts的实现印证了这一点NOVU_SECRET_KEY存在时直接构造apiKey模式配置覆盖文件中的 keyless 模式resolveTo中--to优先于HUMAN_TO优先于配置文件subscriberId。这也是 CI 中无需在本机执行human setup即可无头运行的机制保证。九、教你的编码 Agent 使用它skill 注入机制novu/human还内置了一套技能注入机制教 Claude Code、Cursor 等编码 Agent何时应该调用human而不是在活跃会话中直接问用户。setup结束时会在 TTY 上询问是否安装技能[Y/n]提示也可随时显式管理human setup # 结束时提示安装 skill human skill install # 任意时刻显式安装/重装 human skill install --host claude cursor # 指定目标宿主setup支持--skill/--no-skill强制指定非交互场景必须显式传入否则静默跳过——源码注释明确说明在无头运行中向 CI 检出目录写入文件是意外行为。skill install支持--host指定claude, cursor, windsurf, copilot, gemini, roo, opencode, kiro, agents等宿主默认自动检测项目中的.claude/、.cursor/等配置目录未检测到时回退到常见宿主install-skills.ts。技能内容采用 agentskills.io其核心教导是——何时该用human而非直接在聊天中提问无人值守运行时后台任务、定时/cron 任务、自主循环、CI 步骤——没有活跃聊天可供提问风险或不可逆操作删除数据、部署生产、花钱、发送对外可见内容——即使正在交互会话中也应显式human approve留下谁在何时批准了什么的审计轨迹真正的多向决策用choose而非默默猜测或自问自答长任务完成后的告知用tell单向通知不阻塞等待回复。同时它明确告诫 Agent不要在活跃会话中用human逃避自己能力范围内的常规判断也不要用它转发日志已能呈现的简单状态更新未设置时命令以退出码 1 报出明确指引No human connected yet...Agent 应把该信息呈现给可触达的人而不是静默放弃或循环重试。十、从源码看实现脉络把上述行为串起来看novu/human的整体实现非常清晰index.tscommander程序入口注册全部命令ask/approve/choose/tell/wait/list/cancel/setup/invite/contacts/channels/skillwithCommonOptions统一挂载--to/--via/--from/--ttl/--timeout/--async/--json通用参数并通过--help附加说明环境变量与优先级。config.ts配置读写、keyless/apiKey 双模式、默认 API 地址https://api.novu.co、默认 relay 标识human-relay、配置迁移逻辑。interact.ts四命令共用的交互引擎、2 秒轮询、时长解析支持90、90s、10m、2h、1d格式裸数字按秒、keyless 配额识别。api/human.ts与 Novu API 的 REST 契约——POST /v1/human/interactions创建交互、GET /v1/human/interactions/{id}查询、GET /v1/human/contacts通讯录、POST /v1/human/setuprelay 与订阅者初始化。output.ts退出码映射与结果输出prose 或--json。SKILL.mdAgent 使用决策指南与 README 的实战要点互为印证。配套测试覆盖了核心行为包括contacts.spec.ts、interact.spec.ts、invite.spec.ts、link-channel.spec.ts、setup.spec.ts等见 packages/human/src/commands 目录可作为理解各命令边界行为的补充参考。结语novu/human用极小的体积为 Agent 世界补上了人这一环一条命令触达、阻塞等待、稳定退出码、环境变量无头运行、技能注入教会 Agent 何时求助——这套组合让人工审批从人工约定变成了可审计、可恢复、可编程的工程原语。无论你是运行无人值守任务的 DevOps 脚本、需要生产部署审批的 CI 流水线还是自主决策的编码 Agent都可以把npx novu/human作为你的标准人工闸门接入方案。【免费下载链接】novuThe open-source communication infrastructure for agents and products项目地址: https://gitcode.com/GitHub_Trending/no/novu创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
