@openbrt/tvctl 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# @openbrt/tvctl
+
+把文档、图片和文字推进**电视上的 ChatGPT kiosk**。
+
+电视上的 ChatGPT 网页版没有可用的文件入口——遥控器没有指针，输入区在 kiosk 里也被
+精简掉了，而 Live 语音模式本身就不接受附件。`tvctl` 补的就是这条缺失的投递通道。
+
+```bash
+npm i -g @openbrt/tvctl
+
+tvctl bind 192.168.8.179 --token 123456    # 配对码显示在电视上
+tvctl attach photo.png --prompt "用简单英语讲讲这张图"
+tvctl live start
+```
+
+## 传输
+
+**局域网 HTTP 直连**，kiosk 自己起一个小 server，CLI 直接把字节 POST 过去。
+不经过任何云端、对象存储或消息队列；手机和电视必须在同一个局域网。
+
+这条通道**只在电视上的 kiosk 活着并且在前台时才通**。电视关机、休眠或 App 被杀之后
+推不进去，也不排队——`tvctl` 会直接报连不上，不会假装成功。
+
+## 命令
+
+| 命令 | 作用 |
+|---|---|
+| `tvctl bind HOST[:PORT] --token CODE [--name NAME]` | 绑定一台电视，配对码来自电视屏幕 |
+| `tvctl devices` / `tvctl use NAME` | 多台电视时列出/切换 |
+| `tvctl inspect [--json]` | 电视当前状态和能力 |
+| `tvctl attach FILE... [--prompt TEXT] [--no-send]` | 把文件推进对话 |
+| `tvctl say TEXT [--no-send]` | 把文字推进对话 |
+| `tvctl live start\|stop` | 开始/结束 Live 语音 |
+| `tvctl doctor [--json]` | 连通性排查 |
+
+通用参数 `--host --port --token --device --json`；
+环境变量 `TVCTL_HOST TVCTL_PORT TVCTL_TOKEN TVCTL_DEVICE TVCTL_CONFIG_DIR`。
+
+配置存在 `~/.config/tvctl/config.json`（0600，里面有配对码）。
+
+## 给 AI Agent 用
+
+包里带 `agent-plugin.json`（`openbrt.agent_plugin.v1`），声明了能力、边界和
+自然语言任务映射。WorkBuddy / Claude Code / Codex / OpenClaw 这类 agent 读它，
+然后直接 shell 调 `tvctl`。
+
+```js
+import manifest from '@openbrt/tvctl/manifest' with { type: 'json' };
+```
+
+**一个必须知道的产品前提**：ChatGPT 的 Live 语音模式不接受附件。正确形态是
+「先 `attach` 把图/文档发进普通对话 → 再 `live start` 让人就着这个上下文说话」，
+而不是「Live 进行中塞一张图」。
+
+## 协议
+
+设备端要实现这四个路由（`Authorization: Bearer <配对码>`）：
+
+```
+GET  /v1/health   -> {ok, device{name,model}, app{package,version}, capabilities[], state{view,live,voice}}
+GET  /v1/state    -> {ok, state{...}}
+POST /v1/attach   multipart/form-data: file(可多个), prompt?, send=1|0
+POST /v1/say      application/json: {text, send}
+POST /v1/live     application/json: {action:"start"|"stop"}
+```
+
+除 health/state 外都返回回执 `{ok, status: "applied"|"rejected"|"failed", reason?}`。
+单文件上限 32 MB——电视那头内存很紧，超了先压缩，不要分片硬塞。
+
+参考实现：[chatgpt-tv-box](https://github.com/) 里的 `com.local.gvkiosk`（GeckoView kiosk）。
+
+## License
+
+MIT

package/agent-plugin.json

@@ -0,0 +1,95 @@
+{
+  "schema": "openbrt.agent_plugin.v1",
+  "id": "tvctl",
+  "name": "tvctl",
+  "package": "@openbrt/tvctl",
+  "bin": "tvctl",
+  "description": "Push documents, images and text from a phone or AI agent into a ChatGPT kiosk running on a TV box.",
+  "transport": "lan/http",
+  "why_this_exists": "电视上的 ChatGPT 网页版没有可用的文件入口——遥控器没有指针，输入区在 kiosk 里也被精简掉了，而 Live 语音模式本身就不接受附件。tvctl 补的就是这条缺失的投递通道：手机上的 agent 直接把字节推给电视，电视自己把它喂进对话。",
+  "hardware_abstraction": {
+    "agent_facing_type": "chat_kiosk_display",
+    "rule": "agent 只通过 tvctl inspect 返回的 capabilities 和回执理解设备；不要推断电视品牌、型号、Android 版本或厂商系统，也不要去搜索这些资料。"
+  },
+  "user_contract": "用户只需要给出电视的地址和配对码，以及「想让电视上的 ChatGPT 看什么」。agent 负责选文件、写提示词、决定发不发送，并根据回执报告结果。",
+  "transport_policy": {
+    "role": "data_plane_and_control",
+    "note": "字节直接走局域网 HTTP 推给电视，不经过任何云端、对象存储或消息队列。手机和电视必须在同一个局域网里。",
+    "agent_must_not": [
+      "不要把用户的文件上传到第三方图床或对象存储再让电视去拉——这条通道的全部意义就是不出局域网",
+      "不要写轮询循环反复调 tvctl inspect 去等状态；需要等结果就读 attach 的回执",
+      "不要在未获得用户明确同意时推送用户没有主动交给你的文件",
+      "不要假设电视关机、休眠或 kiosk 被杀之后还能收到推送——这条通道只在 App 活着时通"
+    ]
+  },
+  "preconditions": [
+    "电视上的 kiosk（com.local.gvkiosk）正在前台运行",
+    "手机/电脑与电视在同一局域网",
+    "已经跑过一次 tvctl bind，配对码来自电视屏幕"
+  ],
+  "device_classes": [
+    "chat_kiosk_display",
+    "tv_box",
+    "projector"
+  ],
+  "agents": [
+    "WorkBuddy",
+    "Claude Code",
+    "Codex",
+    "OpenClaw",
+    "Hermes",
+    "Gemini CLI",
+    "OpenCode"
+  ],
+  "capabilities": [
+    "chat.attach",
+    "chat.say",
+    "chat.send",
+    "live.start",
+    "live.stop",
+    "device.inspect",
+    "device.state.read"
+  ],
+  "limits": {
+    "max_file_bytes": 33554432,
+    "note": "电视那头内存很紧（实测常驻只剩 400MB 量级），单个文件上限 32MB。超了先压缩或裁剪，不要分片硬塞。"
+  },
+  "product_constraints": [
+    "ChatGPT 的 Live 语音模式本身不接受附件。正确形态是：先用 chat.attach 把图/文档发进普通对话，再用 live.start 让用户就着这个上下文说话。不要承诺「Live 进行中塞一张图」。",
+    "kiosk 的界面被精简过，用户在电视上看到的是滚动对话区 + 一个语音按钮。推进去的内容会出现在对话区里。"
+  ],
+  "natural_language_tasks": [
+    {
+      "intent": "把我手机里这张图发到电视上的 ChatGPT，让它讲讲里面的英文",
+      "primary_command": "tvctl attach IMAGE.png --prompt \"用简单英语讲讲这张图，然后问我一个问题\" --json",
+      "agent_strategy": "先运行 tvctl inspect --json 确认电视在线、kiosk 在前台。把文件路径和提示词一起交给 attach，默认会直接发送。回执里 status=applied 才算成功。如果用户接下来想开口说话，再运行 tvctl live start。",
+      "if_unbound": "只向用户要电视 IP 和电视屏幕上显示的配对码，然后运行 tvctl bind HOST --token CODE；不要要求用户理解端口、token 存在哪或局域网细节。",
+      "if_offline": "不要重试轮询。告诉用户这条通道只在电视上的 kiosk 活着时才通，请先把电视切到那个应用。"
+    },
+    {
+      "intent": "把这份 PDF 推到电视上，先别发，我自己在电视上看着再说",
+      "primary_command": "tvctl attach DOC.pdf --no-send --json",
+      "agent_strategy": "用 --no-send，文件只会挂在输入框上，不会发出去。回执 status=applied 表示附件已经挂上。"
+    },
+    {
+      "intent": "让电视上的 ChatGPT 开始跟我语音对话",
+      "primary_command": "tvctl live start --json",
+      "agent_strategy": "先 tvctl inspect --json 看 state.live。已经在 live 里就不要重复调用。结束用 tvctl live stop。"
+    },
+    {
+      "intent": "推不过去，帮我看看哪一环断了",
+      "primary_command": "tvctl doctor --json",
+      "agent_strategy": "doctor 会逐步报告配置、连通性和 kiosk 健康状态。最常见的两个原因是「电视上 kiosk 不在前台」和「手机不在家里的网」，先按这两条问用户，不要一上来怀疑配对码。"
+    }
+  ],
+  "commands": [
+    { "name": "bind", "usage": "tvctl bind HOST[:PORT] --token CODE [--name NAME]" },
+    { "name": "devices", "usage": "tvctl devices" },
+    { "name": "use", "usage": "tvctl use NAME" },
+    { "name": "inspect", "usage": "tvctl inspect --json" },
+    { "name": "attach", "usage": "tvctl attach FILE... [--prompt TEXT] [--no-send] --json" },
+    { "name": "say", "usage": "tvctl say TEXT [--no-send] --json" },
+    { "name": "live", "usage": "tvctl live start|stop --json" },
+    { "name": "doctor", "usage": "tvctl doctor --json" }
+  ]
+}

package/bin/tvctl.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import {
+  DEFAULT_PORT, loadConfig, saveConfig, resolveTarget, parseHost,
+  health, state, attach, say, live, TvctlError, baseUrl,
+} from '../lib/index.mjs';
+
+const USAGE = `tvctl —— 把文档、图片和文字推进电视上的 ChatGPT kiosk
+
+  tvctl bind <HOST[:PORT]> --token CODE [--name NAME]   绑定一台电视（配对码显示在电视上）
+  tvctl devices                                         列出已绑定的电视
+  tvctl use <NAME>                                      切换默认电视
+  tvctl inspect [--json]                                看电视当前状态和能力
+  tvctl attach <FILE...> [--prompt TEXT] [--no-send]    把文件推进对话
+  tvctl say <TEXT> [--no-send]                          把文字推进对话
+  tvctl live start|stop                                 开始/结束 Live 语音
+  tvctl doctor [--json]                                 连通性排查
+
+通用参数：--host HOST  --port PORT  --token TOKEN  --device NAME  --json
+环境变量：TVCTL_HOST  TVCTL_PORT  TVCTL_TOKEN  TVCTL_DEVICE  TVCTL_CONFIG_DIR
+`;
+
+function parseArgs(argv) {
+  const opts = {};
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') { rest.push(...argv.slice(i + 1)); break; }
+    if (a === '--json') opts.json = true;
+    else if (a === '--send') opts.send = true;
+    else if (a === '--no-send') opts.send = false;
+    else if (a === '--default') opts.default = true;
+    else if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq > 0) opts[a.slice(2, eq)] = a.slice(eq + 1);
+      else opts[a.slice(2)] = argv[++i];
+    } else rest.push(a);
+  }
+  return { opts, rest };
+}
+
+function out(opts, obj, human) {
+  if (opts.json) console.log(JSON.stringify(obj, null, 2));
+  else console.log(human);
+}
+
+function fail(opts, e) {
+  const msg = e instanceof TvctlError ? e.message : (e?.stack || String(e));
+  if (opts.json) console.log(JSON.stringify({ ok: false, error: String(e?.message || e) }, null, 2));
+  else console.error('✗ ' + msg);
+  process.exit(1);
+}
+
+async function main() {
+  const { opts, rest } = parseArgs(process.argv.slice(2));
+  const cmd = rest.shift();
+  if (!cmd || cmd === 'help' || opts.help) { console.log(USAGE); return; }
+
+  const cfg = await loadConfig();
+
+  if (cmd === 'bind') {
+    const where = rest[0];
+    if (!where) throw new TvctlError('用法：tvctl bind <HOST[:PORT]> --token CODE');
+    const { host, port } = parseHost(where);
+    const token = opts.token || process.env.TVCTL_TOKEN;
+    if (!token) {
+      throw new TvctlError('缺 --token。配对码显示在电视上（kiosk 的配对界面），六位。');
+    }
+    const name = opts.name || host;
+    const target = { name, host, port, token };
+    // 先连一下再落盘，别把一个连不通的配置存下来
+    const h = await health(target);
+    cfg.devices[name] = { host, port, token };
+    if (opts.default || !cfg.default) cfg.default = name;
+    const p = await saveConfig(cfg);
+    out(opts, { ok: true, name, host, port, health: h, config: p },
+      `✓ 已绑定 ${name} (${host}:${port})\n  ${h?.device?.name || ''} ${h?.app?.package || ''} ${h?.app?.version || ''}\n  配置写入 ${p}`);
+    return;
+  }
+
+  if (cmd === 'devices') {
+    const names = Object.keys(cfg.devices);
+    out(opts, { ok: true, default: cfg.default || null, devices: cfg.devices },
+      names.length
+        ? names.map((n) => `${n === cfg.default ? '*' : ' '} ${n}\t${cfg.devices[n].host}:${cfg.devices[n].port || DEFAULT_PORT}`).join('\n')
+        : '（还没绑定任何电视，先跑 tvctl bind）');
+    return;
+  }
+
+  if (cmd === 'use') {
+    const name = rest[0];
+    if (!cfg.devices[name]) throw new TvctlError(`没有叫 ${name} 的电视。tvctl devices 看看有哪些。`);
+    cfg.default = name;
+    await saveConfig(cfg);
+    out(opts, { ok: true, default: name }, `✓ 默认电视切到 ${name}`);
+    return;
+  }
+
+  const target = resolveTarget(cfg, opts);
+
+  if (cmd === 'inspect') {
+    const h = await health(target);
+    out(opts, h, [
+      `电视     ${h?.device?.name || '?'}  ${h?.device?.model || ''}`,
+      `应用     ${h?.app?.package || '?'} ${h?.app?.version || ''}`,
+      `当前     view=${h?.state?.view ?? '?'}  live=${h?.state?.live ?? '?'}  voice=${h?.state?.voice ?? '?'}`,
+      `能力     ${(h?.capabilities || []).join(', ')}`,
+    ].join('\n'));
+    return;
+  }
+
+  if (cmd === 'state') {
+    out(opts, await state(target), JSON.stringify(await state(target)));
+    return;
+  }
+
+  if (cmd === 'attach') {
+    if (!rest.length) throw new TvctlError('用法：tvctl attach <FILE...> [--prompt TEXT]');
+    const send = opts.send !== false;
+    const r = await attach(target, rest, { prompt: opts.prompt || '', send });
+    out(opts, r,
+      `✓ ${r.status || 'applied'}  ${r.files.map((f) => `${f.name} (${(f.bytes / 1024).toFixed(0)} KB)`).join(', ')}` +
+      (opts.prompt ? `\n  提示词：${opts.prompt}` : '') +
+      (send ? '\n  已发送' : '\n  已挂在输入框，没发送'));
+    return;
+  }
+
+  if (cmd === 'say') {
+    const text = rest.join(' ');
+    const r = await say(target, text, { send: opts.send !== false });
+    out(opts, r, `✓ ${r.status || 'applied'}  ${text}`);
+    return;
+  }
+
+  if (cmd === 'live') {
+    const action = rest[0];
+    const r = await live(target, action);
+    out(opts, r, `✓ ${r.status || 'applied'}  live ${action}`);
+    return;
+  }
+
+  if (cmd === 'doctor') {
+    const report = { ok: false, target: { host: target.host, port: target.port, device: target.name }, steps: [] };
+    if (!target.host) {
+      report.steps.push({ step: 'config', ok: false, detail: '还没绑定电视，先跑 tvctl bind' });
+      out(opts, report, '✗ 还没绑定电视，先跑 tvctl bind <电视IP> --token <配对码>');
+      process.exit(1);
+    }
+    report.steps.push({ step: 'config', ok: true, detail: baseUrl(target) });
+    try {
+      const h = await health(target);
+      report.steps.push({ step: 'health', ok: true, detail: h });
+      report.ok = true;
+      out(opts, report, `✓ ${baseUrl(target)} 通\n  ${h?.app?.package || ''} ${h?.app?.version || ''}  view=${h?.state?.view}`);
+    } catch (e) {
+      report.steps.push({ step: 'health', ok: false, detail: String(e.message || e) });
+      out(opts, report, `✗ ${baseUrl(target)} 不通\n  ${e.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  throw new TvctlError(`不认识的命令：${cmd}\n\n${USAGE}`);
+}
+
+const { opts } = parseArgs(process.argv.slice(2));
+main().catch((e) => fail(opts, e));

package/lib/index.mjs

@@ -0,0 +1,190 @@
+// @openbrt/tvctl —— 把文档、图片和文字推进电视上的 ChatGPT kiosk。
+//
+// 传输就是局域网 HTTP：kiosk 自己起一个小 server，CLI 直接把字节 POST 过去。
+// 不走对象存储、不走 MQTT、不需要公网——手机和电视本来就在同一个家里。
+
+import { createHash } from 'node:crypto';
+import { readFile, mkdir, writeFile, chmod } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+export const DEFAULT_PORT = 8770;
+export const API_PREFIX = '/v1';
+
+/** 单个文件的大小上限。电视那头只有 2~4GB 内存，别把大文件塞过去。 */
+export const MAX_FILE_BYTES = 32 * 1024 * 1024;
+
+export function configPath() {
+  const base = process.env.TVCTL_CONFIG_DIR ||
+    path.join(process.env.XDG_CONFIG_HOME || path.join(homedir(), '.config'), 'tvctl');
+  return path.join(base, 'config.json');
+}
+
+export async function loadConfig() {
+  try {
+    const raw = await readFile(configPath(), 'utf8');
+    const cfg = JSON.parse(raw);
+    if (!cfg || typeof cfg !== 'object') return { devices: {} };
+    if (!cfg.devices || typeof cfg.devices !== 'object') cfg.devices = {};
+    return cfg;
+  } catch {
+    return { devices: {} };
+  }
+}
+
+export async function saveConfig(cfg) {
+  const p = configPath();
+  await mkdir(path.dirname(p), { recursive: true });
+  await writeFile(p, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+  // 里面有 token，别让同机其他用户读到
+  await chmod(p, 0o600);
+  return p;
+}
+
+/**
+ * 解析出「这次要操作哪台设备」。
+ * 优先级：命令行 --host/--token > 环境变量 > 配置文件里 --device 指定的 > 默认设备。
+ */
+export function resolveTarget(cfg, opts = {}) {
+  const name = opts.device || process.env.TVCTL_DEVICE || cfg.default ||
+    Object.keys(cfg.devices || {})[0];
+  const saved = (name && cfg.devices && cfg.devices[name]) || {};
+  const host = opts.host || process.env.TVCTL_HOST || saved.host;
+  const port = Number(opts.port || process.env.TVCTL_PORT || saved.port || DEFAULT_PORT);
+  const token = opts.token || process.env.TVCTL_TOKEN || saved.token || '';
+  return { name: name || null, host: host || null, port, token };
+}
+
+export function parseHost(input) {
+  const s = String(input || '').trim().replace(/^https?:\/\//i, '').replace(/\/+$/, '');
+  if (!s) throw new Error('host 不能为空');
+  const m = /^(\[[^\]]+\]|[^:]+)(?::(\d+))?$/.exec(s);
+  if (!m) throw new Error(`认不出这个地址：${input}`);
+  return { host: m[1], port: m[2] ? Number(m[2]) : DEFAULT_PORT };
+}
+
+export function baseUrl(target) {
+  const host = target.host.includes(':') && !target.host.startsWith('[')
+    ? `[${target.host}]`
+    : target.host;
+  return `http://${host}:${target.port}${API_PREFIX}`;
+}
+
+class TvctlError extends Error {
+  constructor(message, extra = {}) {
+    super(message);
+    this.name = 'TvctlError';
+    Object.assign(this, extra);
+  }
+}
+export { TvctlError };
+
+async function request(target, route, { method = 'GET', body, headers = {}, timeoutMs = 20000 } = {}) {
+  if (!target.host) {
+    throw new TvctlError('还没绑定电视。先运行：tvctl bind <电视IP> --token <电视上显示的配对码>');
+  }
+  const url = baseUrl(target) + route;
+  const h = { ...headers };
+  if (target.token) h.Authorization = `Bearer ${target.token}`;
+
+  let res;
+  try {
+    res = await fetch(url, { method, body, headers: h, signal: AbortSignal.timeout(timeoutMs) });
+  } catch (e) {
+    const hint = e?.name === 'TimeoutError'
+      ? '超时。电视上的 kiosk 可能没在前台运行——这条通道只在 App 活着的时候通。'
+      : '连不上。确认手机/电脑和电视在同一个局域网，且 kiosk 正在运行。';
+    throw new TvctlError(`${url} ${hint}`, { cause: String(e?.message || e) });
+  }
+
+  const text = await res.text();
+  let data = null;
+  try { data = text ? JSON.parse(text) : null; } catch { /* 非 JSON 原样带回去 */ }
+
+  if (!res.ok) {
+    const reason = data?.reason || data?.error || text.slice(0, 200) || `HTTP ${res.status}`;
+    throw new TvctlError(
+      res.status === 401 ? `配对码不对或已失效：${reason}` : `电视拒绝了这条请求：${reason}`,
+      { status: res.status, body: data },
+    );
+  }
+  return data ?? { ok: true, raw: text };
+}
+
+export function sha256(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+const MIME = new Map(Object.entries({
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+  '.webp': 'image/webp', '.heic': 'image/heic', '.bmp': 'image/bmp',
+  '.pdf': 'application/pdf', '.txt': 'text/plain', '.md': 'text/markdown',
+  '.csv': 'text/csv', '.json': 'application/json',
+  '.doc': 'application/msword',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.xls': 'application/vnd.ms-excel',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  '.ppt': 'application/vnd.ms-powerpoint',
+  '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+}));
+
+export function guessMime(file) {
+  return MIME.get(path.extname(file).toLowerCase()) || 'application/octet-stream';
+}
+
+export async function health(target) {
+  return request(target, '/health', { timeoutMs: 8000 });
+}
+
+export async function state(target) {
+  return request(target, '/state', { timeoutMs: 8000 });
+}
+
+/**
+ * 把文件推进电视上的 ChatGPT 对话。
+ * send=true 时电视会连带把这条消息发出去；否则只挂上附件、等人在电视上继续。
+ */
+export async function attach(target, files, { prompt = '', send = true, timeoutMs = 120000 } = {}) {
+  if (!files || !files.length) throw new TvctlError('至少要给一个文件');
+  const form = new FormData();
+  const meta = [];
+  for (const f of files) {
+    const buf = await readFile(f);
+    if (buf.byteLength > MAX_FILE_BYTES) {
+      throw new TvctlError(
+        `${path.basename(f)} 有 ${(buf.byteLength / 1048576).toFixed(1)} MB，` +
+        `超过上限 ${MAX_FILE_BYTES / 1048576} MB。电视那头内存很紧，先压缩或裁剪。`,
+      );
+    }
+    const type = guessMime(f);
+    form.append('file', new Blob([buf], { type }), path.basename(f));
+    meta.push({ name: path.basename(f), bytes: buf.byteLength, sha256: sha256(buf), type });
+  }
+  if (prompt) form.append('prompt', prompt);
+  form.append('send', send ? '1' : '0');
+
+  const res = await request(target, '/attach', { method: 'POST', body: form, timeoutMs });
+  return { ...res, files: meta };
+}
+
+/** 往对话里打一段文字。默认直接发出去。 */
+export async function say(target, text, { send = true, timeoutMs = 30000 } = {}) {
+  if (!text || !String(text).trim()) throw new TvctlError('文字不能为空');
+  return request(target, '/say', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ text: String(text), send: !!send }),
+    timeoutMs,
+  });
+}
+
+/** 开始/结束电视上的 Live 语音。 */
+export async function live(target, action, { timeoutMs = 30000 } = {}) {
+  if (!['start', 'stop'].includes(action)) throw new TvctlError('action 只能是 start 或 stop');
+  return request(target, '/live', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ action }),
+    timeoutMs,
+  });
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@openbrt/tvctl",
+  "version": "0.1.0",
+  "description": "Push documents, images and text from a phone or AI agent into a ChatGPT kiosk running on a TV box.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "chatgpt",
+    "tv",
+    "android-tv",
+    "kiosk",
+    "geckoview",
+    "agent",
+    "openclaw",
+    "workbuddy",
+    "claude-code",
+    "codex"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "agent-plugin.json",
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "bin": {
+    "tvctl": "bin/tvctl.mjs"
+  },
+  "exports": {
+    ".": "./lib/index.mjs",
+    "./manifest": "./agent-plugin.json",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "check": "node --check lib/index.mjs && node --check bin/tvctl.mjs && node --test test/*.test.mjs"
+  }
+}