# tmeet app — CLI 应用信息管理

管理**当前用户自己的** CLI 应用（cli-app）在腾讯会议中的展示配置。用于控制「是否 / 如何在会议中显示自己的 CLI 应用」，包括应用名称、主页 URL、会中打开方式。

> **作用范围仅限当前登录用户自己的 CLI 应用**，不影响其他用户、不影响会议本身，也不影响其他参会人。

## 目录

- [使用场景](#使用场景)
- [get — 获取当前 CLI 应用配置](#get--获取当前-cli-应用配置)
- [set — 设置 CLI 应用配置](#set--设置-cli-应用配置)
- [常见错误](#常见错误)
- [参考](#参考)

---

## 使用场景

| 用户诉求 | 应执行的操作 |
|---------|-------------|
| 想让"会中的应用"里出现自己的 CLI 应用 | `tmeet app set --homepage <URL>` 设置一个非空 homepage |
| 不希望会中再显示自己的 CLI 应用 | `tmeet app set --homepage ""` 将 homepage 置空 |
| 修改会中显示的应用名称 | `tmeet app set --sdk-name <名称>` |
| 修改会中打开方式（侧边栏/宽侧边栏/独立弹窗） | `tmeet app set --layout-style <sidebar\|wide_sidebar\|popout>` |
| 查看当前 CLI 应用配置 | `tmeet app get` |

**关键行为**：`homepage` 是**会中是否下发 CLI 应用的开关**——非空即会中展示，置空则会中不再下发。

---

## get — 获取当前 CLI 应用配置

```bash
tmeet app get
```

查询当前登录用户的 CLI 应用当前配置（应用名称、homepage、layout-style 等）。

**无任何可选参数。**

---

## set — 设置 CLI 应用配置

> ⚠️ **适用场景**：当用户想让CLI应用承载自己的网站并且在会中使用时，可以使用此功能实现。设置前**必须**严格遵守[调用准则](#调用准则)，设置成功后**必须**严格遵守[设置成功后的告知](#设置成功后的告知)

```bash
# 开启会中展示：设置 homepage
tmeet app set --homepage "https://example.com/app"

# 关闭会中展示：将 homepage 置空
tmeet app set --homepage ""

# 修改应用名称
tmeet app set --sdk-name "我的 CLI 助手"

# 修改会中打开方式
tmeet app set --layout-style popout

# 同时修改多项
tmeet app set --homepage "https://example.com/app" --sdk-name "我的 CLI 助手" --layout-style wide_sidebar
```

更新当前登录用户的 CLI 应用配置。三个参数**至少提供一个**，未提供的参数保持原值不变。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|:----:|--------|------|
| `--homepage` | string | 三选一 | — | 应用主页 URL。**非空**：会中下发并展示当前 CLI 应用，用户点击后打开该 URL；**空字符串（`""`）**：会中不再下发当前 CLI 应用。非空时**必须为 `http://` 或 `https://` 开头的合法 URL**；`https://` 时该地址需拥有**被本机信任**的 SSL/TLS 证书，否则会中打开会被拦截。**协议选择须遵循[调用准则](#调用准则)中的协议选择判定表**（`http://` 存在客户端版本兼容性问题）。**长度上限 200 个字符** |
| `--sdk-name` | string | 三选一 | — | 应用在会中显示的名称。**长度上限 20**，按显示宽度计算：ASCII 字符计 1，非 ASCII（如中文）计 2；超出会报错 |
| `--layout-style` | enum | 三选一 | 服务端默认 `sidebar` | 会中点击应用后的打开布局。可选值及展示尺寸：`sidebar`（窄侧边栏，宽 **375px**） / `wide_sidebar`（宽侧边栏，宽 **735px**） / `popout`（独立弹窗，**960×540px**）。**未传该参数时 CLI 不下发该字段**：若服务端当前无值则由服务端置为 `sidebar`，若已有值则保持不变 |

> 三个参数至少提供一个（`--homepage` / `--sdk-name` / `--layout-style`），全部不提供时命令会报错。

### 调用准则

- **`--homepage` 是会中展示开关，调用前先与用户确认意图**：
  - 若用户表述为"关闭 / 隐藏 / 不再显示 CLI 应用"，应使用 `--homepage ""`；
  - 若用户表述为"打开 / 展示 / 让 CLI 应用出现在会中"，应确认用户提供的具体 URL 再调用；用户未提供 URL 时**不得自行填充默认值**。
- **URL 合法性校验**：`--homepage` 非空时必须是 `http://` 或 `https://` 开头的合法 URL。若用户提供的是其它非法格式（例如缺失 scheme、`ftp://` 等），先提示用户修正，不要直接透传导致命令报错。
- **协议选择判定表（`http://` 与 `https://`）**：腾讯会议客户端 **3.45.10 之前的版本不支持打开 `http://` 页面，仅支持 `https://`**；3.45.10 及以后版本两者均支持。按下表逐项判定，**不得跳过**：

  | 用户提供的 URL | 是否已确认目标用户客户端版本 ≥ 3.45.10 | 处理 |
  |---|:---:|---|
  | `https://...` | 无需判定 | 直接调用 `tmeet app set` |
  | `http://...` | 已确认（用户本轮明确回复版本号 ≥ 3.45.10） | 直接调用 `tmeet app set` |
  | `http://...` | 未确认 / 不知道 / 用户只说"应该是新版" | **必须先向用户询问客户端版本号**（如"请在腾讯会议客户端『关于我们』中查看版本号"），得到明确版本号后再调用；**不得**因用户口头保证"是新版"而跳过确认 |
  | `http://...` | 已确认 < 3.45.10 | 告知用户该版本客户端不支持 `http://`，请其提供 `https://` 地址或升级客户端后再重试；**不得**直接调用 `tmeet app set` |

  即便用户表示"我这边就是新版"、"应该没问题"，只要未拿到明确版本号，仍按"未确认"处理，不得自我说服跳过询问。
- **选用 `https://` 时的证书要求**：`--homepage` 指向的 `https://` 地址必须拥有**被本机信任**的 SSL/TLS 证书；使用默认自签或无证书时，会中打开会被安全策略拦截。**Agent 不代替用户选择或签发证书方案**（涉及操作系统、本地服务框架、企业策略等差异），若用户询问方案可提示常见方向（如 `mkcert`、企业内部 CA、反向代理挂已有证书等），并建议以对应工具的官方文档为准。
- **`--layout-style` 值不得推断**：仅接受 `sidebar` / `wide_sidebar` / `popout` 三值。用户表述模糊（如"侧边"/"弹窗"/"大一点"）时，先按下表展示三种取值的**尺寸**让用户确认后再调用。**未传 `--layout-style` 时 CLI 不下发该字段**：若服务端当前无值，服务端会置为默认 `sidebar`；若服务端已有值，则保持原值不变（不会被覆盖）。因此若用户想修改布局，必须显式传入该参数。

**`--layout-style` 取值一览：**

| 取值 | 展示形态 | 尺寸 | 适用场景 |
|------|---------|------|---------|
| `sidebar` | 窄侧边栏 | 宽 375px（高度自适应会议窗口） | 内容紧凑、以文本/列表为主 |
| `wide_sidebar` | 宽侧边栏 | 宽 735px（高度自适应会议窗口） | 需要更多横向空间，如表格、双栏布局 |
| `popout` | 独立弹窗 | 960×540px（可拖动） | 复杂交互、独立窗口、不希望占用会议主区域 |

### 设置成功后的告知

`set` 命令返回成功后，Agent 除了回执成功信息外，还应告知用户**在哪里查看效果**。具体规则：

**生效时机（前置总纲，任何分支都适用）：** `set` 的所有修改（`homepage` / `sdk-name` / `layout-style`）**均不会在当前已加入的会议中实时生效**。服务端仅在**入会时**下发一次 CLI 应用配置，因此：

- 若用户**当前不在会中**：下一次入会即生效。
- 若用户**当前正在会中**：需**退出当前会议并重新加入**（或加入下一场会议）后才能看到本次修改；等待过程中在当前会议里看到"没变化"是正常现象，不代表设置失败，不要引导用户反复重试 `set`。

**在此前提下，按本次调用对 `homepage` 的影响分支告知：**

- **本次调用后 `homepage` 为非空**（无论是本次设为非空，还是本次未改动而原值本就非空）：告知用户**下次入会后**可在**腾讯会议客户端 → 会中工具栏「应用」→ 右侧应用列表**中看到该 CLI 应用；点击后会按当前 `layout-style` 打开 `homepage`。
- **本次调用把 `homepage` 置空**（`--homepage ""`）：告知用户该 CLI 应用**从下次入会起**将不再出现在会中「应用」列表；当前会议里可能仍能看到（缓存），属正常现象，不要引导用户去查看展示效果。
- **本次只修改了 `sdk-name` 或 `layout-style`、未涉及 `homepage`**：若已知服务端当前 `homepage` 为非空（例如刚刚 `tmeet app get` 过、或本会话内已确认），按第 1 条告知；若不确定，不要臆断"会中已生效"，可提示用户"若已开启会中展示，**下次入会后**可在会中『应用』列表看到新的名称 / 打开方式"。

若用户按上述时机重新入会后仍未看到变化，再走 `tmeet tshoot` 反馈。

告知语气保持简短自然，不要长篇罗列；不要替用户猜测是否要打开某个具体会议。

---

## 常见错误

| 错误现象 | 原因 | 解决方案 |
|---------|------|---------|
| `at least one of the flags ... must be used` | `set` 命令未提供任一参数 | 至少提供 `--homepage` / `--sdk-name` / `--layout-style` 之一 |
| URL 校验失败 | `--homepage` 非空但不是 `http://` / `https://` 开头的合法 URL | 修正为 `http://` 或 `https://` 开头的合法 URL，或用 `""` 关闭展示 |
| 会中点击应用后页面无法打开 / 白屏（`http://` 地址） | 目标用户腾讯会议客户端版本 < 3.45.10，不支持打开 `http://` 页面 | 让用户升级到 3.45.10 或更高版本；或改用 `https://` 地址后重新 `tmeet app set --homepage` |
| `character limit exceeded` | `--homepage` 超过 200 个字符 | 缩短 URL 至 200 字符以内后重试 |
| `character width limit exceeded` | `--sdk-name` 显示宽度超过 20（ASCII 计 1，非 ASCII 计 2） | 缩短名称至宽度 20 以内后重试 |
| 会中点击应用后页面被拦截 / 白屏（`https://` 地址） | 该 `https://` 地址的 SSL/TLS 证书未被本机信任（默认自签或无证书） | 让用户使该地址的证书被本机信任后重试；仍不生效请 `tmeet tshoot` 反馈 |
| 错误码 `500294` | 当前登录账号的会议套餐不支持该功能 | 从错误描述中**原样返回**付费引导链接（URL 本身不得改写、拼接或省略参数），并用 Markdown 链接语法 `[升级会议套餐](提取到的URL)` 呈现给用户，使其在前端渲染为**可点击的升级入口**；**不要**把 URL 放进反引号或代码块（会失去可点击性），也不要用裸 URL 作为锚文本，更不要自行推测套餐类型 |
| `user config is empty` | 未登录 | 先执行 `tmeet auth login` |

## 参考

- [tmeet](../SKILL.md) — 全部命令概览