NoaCG Broadcast Graphics and Playout

@noacg/cli

NoaCG CLI——通往 NoaCG Studio 的 Agent 入口。通过编码 Agent 或自己的终端为 NoaCG 制作广播图形：搭建脚手架、验证、检查、截图、打包、保存——适用于任何 NoaCG 部署。完整说明见仓库中的 docs/AGENT_CLI.md。

软件包名是 @noacg/cli；安装后使用的命令是 noacg。 因此，运行 npm i -g @noacg/cli 后，就可以使用 noacg validate …，下方的命令均按实际输入方式书写。

一个工具，三种入口。 MCP 服务不是另一个需要二选一的东西。noacg mcp 会将同一软件包作为 MCP 服务运行，而 Claude Code / Codex 插件包含 noacg-graphic 技能，通过终端驱动同一软件包。选择 Agent 使用的入口即可：

入口	适用对象	安装
插件	Claude Code、Codex	如下方所示，运行两条命令——它会引入技能（在 Claude Code 中为 /noacg:graphic），且在开始制作图形前不会运行任何内容；可选的 noacg-mcp 插件会添加常驻的 MCP 服务
MCP 服务	任何 MCP 客户端	通过标准输入输出运行 npx -y @noacg/cli mcp
终端	能运行 Shell 命令的 Agent，以及你	npm i -g @noacg/cli

无论选择哪种入口，noacg-graphic 技能的内容都相同：NoaCG 图形必须提供的内容，以及实现目标的工作循环。它是约定，而非设计指南。

将 NoaCG Playout 连接到 CasparCG 服务需要使用另一款工具 NoaCG Bridge，可从 noacg.studio/downloads 下载（也可从仓库的 Releases 页面 下载最新版本的 Bridge）。它与创作无关，有自己的版本号，也不需要此软件包中的任何内容。

将以下内容粘贴给你的 Agent

最简单的入门方式：在当前打开的会话中，通过一条提示词使用 npx 运行此 CLI，无需预先安装任何内容。如果需要，Agent 会检查环境并在浏览器中连接你的 NoaCG 账户，然后询问要制作什么，并将每个完成的图形连同链接保存到你的资料库中。从 noacg.studio/downloads 复制提示词；其中指定了要运行的确切 CLI 版本。

下方列出了它运行的命令，供希望手动运行命令的人参考。

安装

npx @noacg/cli doctor                 # no install: runs the published build
npm i -g @noacg/cli                   # or install it once

Claude Code：noacg 插件以 /noacg:graphic 的形式提供该技能，无需预先安装；该技能会从终端运行此 CLI。可选的 noacg-mcp 插件会添加常驻 MCP 服务（cli/plugin-mcp/README.md 说明了相关成本）。 在 Claude Code 会话中（2.1.275 或更高版本），只需一条命令即可添加市场、让你确认，并完成安装：

/plugin install noacg --marketplace NoaCG/NoaCG-Studio

在终端或设置脚本中，同样的安装只需两条命令：

claude plugin marketplace add NoaCG/NoaCG-Studio
claude plugin install noacg@noacg-studio

如果只需要 MCP 服务：claude mcp add noacg -- npx -y @noacg/cli mcp。

从此市场安装的插件不会自动更新，除非你主动操作。 Claude Code 只会为 Anthropic 自己的市场启用自动更新，因此技能文本会保持为你安装的版本。在 /plugin、Marketplaces、noacg-studio、Enable auto-update 中启用一次，新版本便会在会话开始时到达。或者手动更新： claude plugin marketplace update noacg-studio && claude plugin update noacg@noacg-studio。 如果已安装版本落后于正在运行的 CLI，noacg doctor 会指出这一点。

Codex：来自同一仓库的同一插件。codex plugin add 会安装该技能，因此无需手动复制；codex plugin add noacg-mcp@noacg-studio 会以相同方式添加可选的常驻服务。

codex plugin marketplace add NoaCG/NoaCG-Studio
codex plugin add noacg@noacg-studio

Codex 也一样，只是命令写法不同：codex plugin marketplace upgrade noacg-studio && codex plugin add noacg@noacg-studio。

对于不支持 codex plugin 的 Codex，请改用较繁琐的方式：将此软件包中的 skill/noacg-graphic/ 复制到 ~/.codex/skills/noacg-graphic/， 然后运行 codex mcp add noacg -- npx -y @noacg/cli mcp。

任何 MCP 客户端：将 npx -y @noacg/cli mcp 作为 stdio 服务运行——命令为 npx，参数为 -y @noacg/cli mcp。

使用

npx @noacg/cli types
npx @noacg/cli scaffold --type scoreboard --design neutral --name "Football scoreboard" --out ./football-scoreboard
#  ...design it: edit football_scoreboard.html, css/template.css, js/template.js ...
#  (the html is named after the GRAPHIC, not the folder: the name's spaces become underscores)
npx @noacg/cli validate ./football-scoreboard --screenshots ./shots
npx @noacg/cli inspect ./football-scoreboard
npx @noacg/cli login                  # once per machine: a scoped key that can only create graphics in your library
npx @noacg/cli save ./football-scoreboard

命令	功能
doctor	显示此工具将使用的浏览器和 NoaCG 部署（NOACG_URL）、找到的桥接版本，以及是否持有密钥；此外，如果已安装插件的技能版本落后于此 CLI，会显示一行提示；如果 CLI 版本落后于 npm 的 latest，也会显示一行提示。没有需要更新的内容时，这两行提示都不会显示。
types	显示部署支持的图形类型：字段、操作员事件、设计、中性脚手架。
scaffold --type <id> [--design <id>|neutral] [--name N] [--set key=value]... --out <dir>	根据类型生成完整且有效的包：目录底盘或 NEUTRAL 脚手架（在纯脊柱上包含字段、机器、控件和运行时）。
scaffold --fields "Label:kind[=value],..." [--name N] --out <dir>	生成一个无类型图形，其中恰好包含你声明的字段。
validate <dir|zip> [--no-bench] [--no-house-contract] [--screenshots <dir>]	执行静态门禁和实时运行时测试台，将每项发现作为教学提示显示，列出就绪情况，并可选生成离线／播出／压力状态的画面；同时根据源文件重新生成包中自动生成的部分。第三方 OGraf 包：检查清单一致性，并执行由宿主驱动的生命周期检查。
inspect <dir|zip>	显示 NoaCG 根据图形自身的契约推导出的操作员界面（输入、按钮、步骤）。
screenshot <dir|zip> --state off|onair|stress --out <png>	生成一张透明背景画面。
pack <dir|zip>... --name N [--save] [--out <file.noacgpack.json>] [--rundown <cues.json>] [--layer n]...	将多个图形打包为一个包，其中包含图层以及可选的提示列表。--save 会先验证图形，然后将包发送到你的 NoaCG Home；包会在 Home → Productions 中等待，你可以点击 Install 按钮创建制作；--out 会将包写入文件，供“导入包”卡片使用。使用 --save 时，如果希望分享，还可以添加 --share --license cc-by-4.0 --shown-as S --description D，将包（不含提示）发送至 Community packs 进行审核。
docs [topic]	查看技能的参考文本。
mcp	通过 stdio 以 MCP 服务的形式提供相同的动词。
login [--name N] [--no-browser] [--key <noacg_ak_…>]	为此计算机获取一个限定范围的 Agent 密钥：打开 NoaCG 授权页面，通过环回监听器接收一次性代码，并兑换该代码。此密钥只能在你的库中创建图形；可在 Settings → Account → Agent access 中撤销，或使用 logout 撤销。CI 可使用 NOACG_AGENT_KEY。
logout [--local] / whoami	撤销并删除此计算机上的密钥／显示当前持有的密钥及其是否仍然有效。
save <dir|zip>... [--name N] [--folder F] [--no-bench]	执行验证（门禁 + 测试台），遇到错误时拒绝保存，然后一次性将图形放入你的 NoaCG 库，并打印每个 #/graphic/<id> 链接。要么全部保存，要么一个也不保存；中断后再次运行相同命令会继续操作，绝不会保存重复副本。保存到库中，不会保存到制作中。
bridge [--port 8899] [--origin URL]… [--no-open] [--quiet]	NoaCG Bridge：在浏览器无法直接访问的环回 HTTP 接口上持有 AMCP 套接字，NoaCG 页面通过该接口使用播出协议。它会打开一个链接，只需点击一次即可将浏览器配对；仅绑定 127.0.0.1，拒绝其他地址；拒绝非 NoaCG 来源。请保持其运行。caspar agent 是它的旧名称，仍可运行此命令。
caspar status|send|play|stop [--server HOST] [--amcp-port 5250]	无需浏览器即可使用相同的 AMCP：检查服务、发送一条命令，或将制作的输出 URL 放到某个通道上（play --url <output URL> --channel 1 --layer 20）。
在任意命令后添加 --json，即可将一个 JSON 对象输出到 stdout。退出码：0 表示无问题，1 表示发现问题或拒绝执行，2 表示用法／IO 错误。环境变量：NOACG_URL（默认值为 https://noacg.studio；可使用开发服务器或自托管服务）、NOACG_BROWSER（Chromium 可执行文件；否则使用系统中的 Chrome／Edge 或通过 Playwright 安装的 Chromium）、NOACG_AGENT_KEY（供 CI 使用的密钥，优先于已存储的密钥）、NOACG_CREDENTIALS_DIR（login 存放密钥的目录，适用于同一账户进行多次登录；默认为每用户配置目录）。

磁盘上的软件包

<slug>/
  SOURCES - edit these                  GENERATED - never edit; `noacg validate` rebuilds them
    <slug>.html                            <slug>.ograf.json   the OGraf v1 manifest (+ v_noacg)
    css/template.css                       graphic.mjs         the OGraf Web Component
    js/template.js                         FIELDS.md  README.md  controlpanel.html
    js/gsap.min.js  images/  fonts/

一个文件夹就是有效的 EBU OGraf v1 Graphic、SPX/CasparCG 软件包，也是你编辑的工作区。将其打包为 Zip，即可通过工作室的导入入口导入；将其放入 OGraf 渲染器，即可播放。这两种用途都由该文件夹原位满足；图形本身是纯 HTML、CSS 和 JS，NoaCG 则可从相同源文件将其导出为 OBS/vMix 叠加层、H2R 或 LiveOS。通过 NoaCG 导入，输出到任何地方。

MCP

通过 stdio 使用相同的动词：npx -y @noacg/cli mcp。只有一个工具 noacg，采用终端命令的语法：command 是动词（types、scaffold、validate、inspect、screenshot、docs、save——最后一个需在 noacg login 后使用），其他参数则是该动词的标志，因此 { "command": "validate", "path": "./my-graphic", "screenshots": true } 会以图像形式返回各帧。技能的参考资料也作为资源提供（noacg://docs/<topic>）。noacg-graphic 技能位于 skill/ 目录中。

只提供一个工具，而非七个，是因为每次配置 MCP 服务时，MCP 客户端都会在每个会话中将所有工具的架构放入模型上下文，无论该会话是否涉及图形。与被它取代的七工具方案约 1,160 个 token 相比，这种设计约占 590 个 token。指导内容放在技能中，仅在创建图形时加载。

bridge 和 caspar 刻意不作为 MCP 工具提供：它们会驱动正在运行的播出硬件，这属于操作员的决策，而非创作 Agent 的决策。

开发

npm install
npm run build                                # generates the plugin's skill copy, then tsc
NOACG_URL=http://localhost:5174 npm test     # against a NoaCG dev server's /bridge
npm run check:skill                          # every shipped copy of the skill matches cli/skill/

许可证

Apache-2.0——这与 NoaCG Studio 本身所采用的 AGPL-3.0-only 刻意不同。本工具是编码 Agent 进入 NoaCG 的入口，因此采用宽松许可证，可安装在任何地方，无需进行政策审查：许可证宽松，明确授予专利许可，且不会将 copyleft 条款延伸到你用它构建的任何内容。工作室上的 AGPL 保护托管应用；它从来就不是为了限制与之通信的客户端。

你创建的图形归你所有。两种许可证均不适用于本工具生成的模板，也不适用于你导出并用于播出的内容。

另外说明一项第三方授权，因为生成的软件包会包含它：图形中打包的动画运行时（js/gsap.min.js）是 GreenSock 的 GSAP，采用其标准许可证，而非我们的许可证。它不属于此 npm 软件包，而是随部署生成的图形一同提供。