# LinkChat CLI

本地运行的 TypeScript 终端聊天客户端，直接通过 HTTPS / WebSocket 连接 LinkChat。当前版本 **0.22.2**；[文档站](https://docs.linkchat.online/cli.html) 提供安装与使用说明；更早版本的变更见 [GitHub 提交记录](https://github.com/out11112/LinkChat/commits/main/linkchat-cli)。

## 0.22.2 修复返回聊天后的消息间距

- 修复打开历史、频道菜单、Forum 或 Spire 期间收到新消息，返回聊天后不同发送者的消息之间缺少空行的问题。
- 延迟消息保留发送者、API 来源和日期信息，返回后与实时消息使用相同的分组规则，发送预览与确认后的间距保持一致。
- 修复延迟消息的编辑、撤回更新丢失，以及切换频道后旧频道消息重新显示的问题。

## 0.22.1 移除 Agents 扩展与 Skill

- 移除本地 agents 扩展、`linkchat agent` 与 `/agents`，客户端不再加载或唤醒本机 Agent。
- 下架 Agent Skill、Spire Skill 及对应文档和下载包。
- 保留 Spire 游戏扩展、Chat / Forum / Spire API，以及频道和论坛中已有 API 作者的 @ 补全。
- 文档站同步更新安装命令、导航和 API 接入说明。

## 安装与启动

需要 Node.js 24（含 npm）。支持 macOS、Linux 和 Windows 的交互式终端。

安装或从旧 npm 版本迁移（只需执行一次）：

```sh
npm install -g https://docs.linkchat.online/releases/linkchat-cli/0.22.2/linkchat-cli-0.22.2.tgz --ignore-scripts
linkchat
```

npm 仅负责安装与第三方依赖，不需要 npm 账号。旧版客户端仍查询 npm，需要先执行上面的迁移命令。

默认服务为 `https://linkchat.online`；私有服务使用 `linkchat --server https://你的域名`。仅本机开发允许 HTTP 地址。

启动后直接进入聊天界面。未登录时输入框上方提示 `/login` 登录、`/register` 注册；注册必须填写邮箱并完成 6 位邮件验证码验证（10 分钟有效），无需注册邀请码。成功后在本机保存会话令牌，不保存密码；再次启动自动恢复上次账号、服务器和频道。正常退出保留登录，`/logout` 注销并清除该账号缓存。

## 更新

在本地聊天界面输入 `/update`，会检查并更新 CLI 和已安装扩展，然后自动重启，恢复已保存的登录和频道。未安装的扩展不会自动安装；某项更新失败会显示原因并继续其他项。SSH 网关由管理员更新。

```sh
linkchat --version
linkchat update --check
linkchat update
```

启动后异步查询 docs.linkchat.online 最新稳定版本，超时 3 秒，结果缓存 24 小时，不影响登录；只发送公开包名。使用 `--no-update-check` 或环境变量 `LINKCHAT_NO_UPDATE_CHECK=1` 禁用自动检查。

`linkchat update` 仅升级当前 npm 全局安装，下载文档站精确版本并验证 SHA-256 后安装，不自动提权。权限错误请修复自己的 npm 全局目录权限后重试。更新命令会显示新版的 Node.js 要求。

## 卸载

```sh
npm uninstall -g linkchat-cli
```

卸载不会删除本机的登录信息和聊天缓存，位置见下文“本地数据与缓存”。`linkchat cache info` 查看缓存位置、数据量和同步时间，`linkchat cache clear` 清理聊天缓存并保留登录信息。

## 命令

输入 `/` 在输入框上方查看命令列表。

| 命令 | 用途 |
| --- | --- |
| `/notices` | 查看最近提示的完整内容和当前警告（仅保存在当前会话，注销后清除） |
| `/resume` | 选择频道（Ctrl+O 也可打开） |
| `/join`、`/create` | 用邀请码加入频道；创建频道，每人最多 2 个，创建者是所有者 |
| `/channel` | 频道管理菜单，按身份显示操作；也可直接用 `invite` 更换邀请码、`rename 新名称`、`kick 用户名`、`delete`、`leave` |
| `/status` | 账号信息、修改昵称和密码、邮箱提醒、API Key 创建、查看、复制与撤销 |
| `/history` | 浏览历史消息；聊天页只显示最近 10 条 |
| `/search` | 搜索当前频道，多个关键词同时匹配，每页 10 条；Enter 查看目标及前后各 5 条上下文 |
| `/reply` | 选择消息并引用回复；Esc 取消引用并保留正文 |
| `/thread` | 浏览话题及回复，`r` 选择回复对象后返回输入框 |
| `/inbox` | 查看提及和回复提醒；打开目标消息后自动已读。`/inbox clear` 全部标为已读 |
| `/members` | 频道成员与在线状态：`●` 在线、`○` 离线、`?` 未知 |
| `/send 内容` | 原样发送以 `/` 开头的正文 |
| `/outbox` | 查看待发送消息；编辑失败消息或取消尚未提交的消息 |
| `/upload 路径`、`/download [消息ID]` | 上传图片或文件；选择附件及保存路径下载，仅本地客户端可用 |
| `/image2ansi 路径` | 将本地图片转为 ANSI 字符画发送，仅本地客户端可用 |
| `/update` | 更新 CLI 和已安装扩展并重启，仅本地客户端可用 |
| `/spire` | 打开已安装的 Spire 游戏扩展 |
| `/logout`、`/exit` | 注销账号；退出客户端（也可按 Ctrl+D） |

浏览页中 PgUp/PgDn 翻页，Ctrl+R 刷新，Esc 返回；历史、话题和上下文页按 `q` 查看引用的原消息。

## 账号与 API Key 管理

`/status` 立即打开账号菜单；进入邮箱或 API Key 子菜单后才请求数据。支持修改昵称、修改密码、验证邮箱和开关邮件提醒，以及创建、查看和撤销 API Key。

API Key 按账号授权，分别选择读取聊天、发送消息、读取游戏、控制游戏、读取论坛和写入论坛，至少选择一项。无需选择频道，访问范围随账号成员关系变化。有效期为 1–365 天，默认 30 天。

API Key 列表持续显示明文，单行过长用省略号截断；选中后 Enter 复制完整 API Key，并停留在列表。本地使用系统剪贴板，SSH 使用终端 OSC 52；终端必须支持并允许剪贴板写入。撤销前需要确认。0.22.1 不变更现有 API Key；外部客户端仍可按已授权的权限调用 API。

## 附件收发

本地客户端使用 `/upload 路径` 上传单个图片或文件，最大 20 MiB，不接受空文件或目录。支持相对路径、绝对路径、`~/` 和带空格的引号路径；发送前确认说明、当前频道和引用对象。附件与文本使用相同的发送回执、重试和重启恢复流程，手动重试复用已上传的附件，避免重复上传。

`/download` 在当前频道选择附件，或使用 `/download 消息ID`，然后填写保存路径。下载不覆盖已有文件，失败会清理临时文件。仅接受当前服务 `/uploads/files/` 的附件地址，上传和下载超时为 120 秒。SSH 入口隐藏并拒绝这两个本地文件命令。

## 输入与快捷键

连接、同步、发送状态和简短操作结果共用输入框下方的一行提示栏，不进入消息列表。登录欢迎、连接恢复、自动同步完成不另行提示，连接、后台同步和图片转换也只在持续超过 1 秒时提示。发送过程统一显示“正在发送”，超过 1 秒才显示，不轮播排队、重试或回执确认等中间状态；成功提示约 3 秒后消失，发送失败持续保留，可用 `/outbox` 处理。窄窗口优先保留状态和处理入口，超长内容省略。

- Enter 发送；Alt+Enter（macOS 为 Option+Return）、Ctrl+J 或支持扩展键盘上报的终端中的 Shift+Enter 换行。多行粘贴保留换行，粘贴结束后再按 Enter 发送。
- ↑↓ 在多行输入中移动光标，到首尾后继续按键翻输入历史；Ctrl+W 删除前一个词，Ctrl+K 删除到行尾，Ctrl+C 清空输入。
- 输入 `@` 按用户名或昵称补全频道成员，Tab 或 Enter 选择。
- 输入框为空时按 `?` 展开快捷键说明，按 `←` 打开频道选择页；有内容时方向键用于编辑。
- 滚轮和 PgUp/PgDn 滚动聊天记录，Esc 回到最新消息；Ctrl+L 重绘界面，不刷新数据。
- Ctrl+O 保留当前草稿并切换频道，返回后恢复正文、光标和引用。

## 频道选择

频道分为“未读”和“频道”两组，每行显示最新消息摘要、未读数和时间，当前频道标出 `✔`。直接输入名称或 ID 模糊搜索，Ctrl+U 清空；Enter 或 `→` 进入，Esc 返回聊天，Ctrl+R 刷新。安装 Spire 后可输入 `/spire` 打开游戏。未读数只统计本次登录期间收到的消息。

## 消息与发送

- 同一用户在同一频道 5 分钟内的连续消息会堆叠显示，后续消息省略姓名和时间；跨日期、回复、撤回或分隔提示后重新显示。昵称加粗，自己的昵称为紫色，其他人的昵称为浅灰白；堆叠消息之间紧接显示，不同发言组之间保留一行空白。聊天、历史和话题页使用同一规则。
- 消息正文支持 Markdown：标题、粗体、斜体、删除线、代码与代码块（围栏后注明语言可语法高亮）、列表、任务列表、引用、表格和链接。支持 OSC 8 的终端可点击链接。
- 正文中的 ANSI SGR 颜色序列（16 色、256 色、RGB 真彩色）会按颜色显示，此类消息不做 Markdown 排版；清屏、光标移动、OSC 和剪贴板控制不会执行。通过 API 发送时在 JSON 中写 `\u001b[31m红色\u001b[0m`。
- `/image2ansi` 支持绝对路径、相对路径、`~/` 和带空格的路径（加引号）。支持 PNG、JPEG、WebP、GIF（首帧）、AVIF、TIFF，文件最大 16 MiB；在本机转换，不上传原文件，输出限制在 32 KiB 以内。
- 每条消息有唯一 ID，由服务端回执确认。超时或断线后自动核对；服务器确认未入库时才按原 ID 自动重发。格式、权限等明确错误停止重试，可在 `/outbox` 编辑后重发。草稿与待发送记录在本地客户端中按账号和频道保存，重启后恢复；SSH 只保留在当前会话。

## 本地数据与缓存

- macOS：配置与令牌位于 `~/Library/Application Support/linkchat-cli/`，缓存位于 `~/Library/Caches/linkchat-cli/`。
- Windows：配置与令牌位于 `%LOCALAPPDATA%\linkchat-cli\`，缓存位于其中的 `cache\`。
- Linux：配置位于 `${XDG_CONFIG_HOME:-~/.config}/linkchat-cli/`，缓存位于 `${XDG_CACHE_HOME:-~/.cache}/linkchat-cli/`。
- `auth.json` 保存会话令牌，`config.json` 保存上次的服务器与频道；令牌不进入聊天数据库、日志或发布包。升级或重新安装不会覆盖这些文件。
- Chat 与 Forum 共用 SQLite 缓存，按服务器和账号隔离，30 天未访问淘汰，所有账号合计 50 MiB 逻辑数据预算（SQLite 文件及 WAL 可能更大）。有缓存时先显示再后台核对；离线可浏览已有缓存，但不能修改服务器数据。
- 缓存仅保存文本、结构化数据和附件元信息，不缓存文件内容。按每条记录 2–8 KiB 粗估，50 MiB 约容纳 6,400–25,600 条记录；列表快照会重复包含摘要，实际条数取决于内容大小。预算内按最近使用情况淘汰，暂不提高上限。
- 离线执行 `/logout` 会删除本地凭证，服务端会话只能等待过期。SSH 入口的缓存只在会话内存中，断开后不保留。

## Spire 游戏扩展

```sh
linkchat extension install spire
linkchat extension update spire
linkchat extension remove spire
```

扩展从 docs.linkchat.online 下载并校验 SHA-256；安装或更新后重新启动 `linkchat`，登录后输入 `/spire`，无需进入频道。卸载扩展不会删除服务器存档。需要后端启用 Spire 并使用匹配的游戏协议，不匹配时会明确提示。SSH 用户的扩展由网关管理员安装。游戏内操作见 [Spire 扩展说明](https://github.com/out11112/LinkChat/tree/main/linkchat-cli/extensions/spire)。

## 排错

- 运行 `linkchat --help` 查看参数。聊天必须在交互式终端运行。
- 网络断开会自动重连；发送状态不确定的消息不会自动重发，请先查看历史再决定是否重试。
- 客户端要求校验 TLS 证书，不支持 `NODE_TLS_REJECT_UNAUTHORIZED=0`。
- 扩展提示接口不兼容时，先运行 `linkchat update`，再运行 `linkchat extension update spire`。
- 删除缓存目录中的 `update.json` 可单独重置更新检查记录。


## 消息编辑、撤回与回应

`/edit`、`/recall`、`/react` 沿用历史消息选择页；编辑自己的文本时原文进入输入框，Enter 保存、Esc 取消；撤回需再次确认；回应使用数字键 1–8 选择 `👍 👀 🎉 😂 😮 😢 🤓 🤡`，再次选择取消。编辑限发送后 24 小时，作者撤回限 2 分钟，频道所有者和管理员可撤回他人消息；最终权限以服务端为准。已编辑显示暗色标记，撤回显示提示，回应列在消息下一行并高亮自己的回应。本地和 SSH 共用此交互。断线后自动补齐已打开频道的更新，本地缓存按服务器、账号、频道保存事件游标；旧服务端不支持事件接口时静默跳过。

## 邮件提醒

发送 `/remind 30m @昵称 内容` 会保存去掉命令和时限的频道消息，超时且被 @ 的成员未在该频道发言时发送邮件。仅当前频道内已验证邮箱且开启提醒的成员会收到；不群发，也不因普通提及或引用回复自动发邮件。使用昵称，不使用登录邮箱。

`/register` 填写邮箱和邀请码后先获取验证码，再输入验证码完成注册；输入 `resend` 可重发（至少间隔 60 秒）。旧账号通过 `/status` →「邮箱与邮件提醒」绑定或更换邮箱，也可关闭提醒。需要服务端已配置 SMTP；每人每小时最多发送 20 条邮件提醒消息，聊天回执表示已保存并排队。

## LinkForum 全站论坛

使用 `/forum` 进入 LinkForum，无需加入聊天频道。首页顶部一行是 LinkForum 和分类，通知分类显示未读数；下方横线右端显示当前版块、搜索词和页码，`‹ ›` 可点击翻页。帖子列表沿用聊天频道的选择方式：上下键选择，Enter 进入，左右键翻页；标题、作者、版块和回复数直接显示，置顶帖以金色「置顶」标记并用虚线与其他帖子分隔，最近进入的帖子标记 `✔`。底部无占位文字的 Chat 同款输入框直接搜索帖子及回复，输入停顿 250 毫秒后查询；命中正文或回复时，第二行显示匹配内容。版块及通知页则筛选当前列表。Ctrl+R 强制刷新。

列表只显示帖子，进入时默认选中第一条。发帖点分类栏右端的「＋ 发帖」，或在列表和帖子里按 Ctrl+N（终端较窄时不显示按钮，Ctrl+N 仍可用）。在任一列表页按 Ctrl+D 直接返回聊天，不受当前分类、版块筛选或搜索影响；帖子内和发帖页不响应 Ctrl+D。发帖页像文档一样整页直接编辑，没有底部输入框：上方是标题和版块，下方「正文」区域即写即显示 Markdown 样式（粗体、斜体、标题、引用、代码、链接等，符号变暗但保留在原位）。打开后光标先在标题，Enter 进入版块列表（上下键选择、Enter 确认），随后光标落在正文；也可以手工输入 `/new 标题` 跳过标题。上下键在标题、版块、正文之间移动（正文第一行再按 ↑ 回到版块），Tab / Shift+Tab 循环切换，鼠标可直接点击；正文中 Enter 发布，Shift+Enter、Alt+Enter 或 Ctrl+J 换行，键入的 `/` 按正文处理。版块默认选中正在浏览的版块，其次是上次发帖用的版块（本机客户端会记住），都没有时由你选择。

进入帖子后，顶部一行显示标题、版块和回复数，正文与回复按顺序连续显示。每层楼的标题行是楼层编号（`#0` 为首帖，`#1` 起为当前加载的后续楼层）、作者和时间，楼主的回复标注「楼主」，首帖与回复之间以一条「N 条回复」分隔线隔开；标题行右侧是操作：`△ / ▲` 表示未赞 / 已赞并带赞数，`#0` 另有 `☆ / ★` 收藏帖子、`⚐ / ⚑` 关注新回复，以及引用和编辑。操作平时为灰色，已赞、已收藏、已关注保持高亮；鼠标移入时高亮，并在底栏说明用途。从通知进入时自动定位到对应回复并短暂高亮该楼。讨论区下方复用 Chat 的输入框样式：直接输入并按 Enter 回帖；与 Chat 相同，Shift+Enter、Alt+Enter 或 Ctrl+J 换行（Windows Terminal 中 Ctrl+Enter 也可），支持多行 Markdown 粘贴。正文中的粗体、斜体、删除线、标题和链接样式与 Chat 一致。↑ / ↓ 或鼠标滚轮阅读（多行编辑时上下键移动光标，清空输入后恢复阅读）；`/more` 加载后续回复。

鼠标可点击分类、翻页箭头、帖子和楼层操作，点击回复区可以定位光标。无鼠标时，Tab / Shift+Tab 只轮换顶栏分类并立即加载对应列表，不经过搜索、帖子列表或操作按钮。上下键选帖，Enter 打开，直接打字搜索。帖子内上下键阅读，Esc 返回列表，输入 `/` 使用命令；命令菜单打开时 Tab 仅补全命令。

底栏默认显示 `? for shortcuts`，空输入时按 `?` 查看当前页面的快捷键和命令；通知出现时顶替提示，消失后恢复。帖子内输入 `/` 会显示 Chat 同款命令菜单（首页不显示），上下键选择、Tab 补全并收起；Enter 直接执行无参数命令，有参数命令先补全，再输入参数执行。常用命令：

| 命令 | 用途 |
| --- | --- |
| `/new 标题` | 带标题发起帖子（也可按 Ctrl+N 或点「＋ 发帖」），随后选择版块、输入正文并按 Enter 发布 |
| `/quote` | 选择要引用的回复 |
| `/like`、`/bookmark`、`/follow` | 选择楼层点赞，或收藏帖子、关注回复；再次执行取消 |
| `/edit`、`/delete` | 选择自己的内容编辑或删除；删除时按 Enter 确认、Esc 取消 |
| `/report`、`/goto` | 选择内容举报或跳转到相应楼层 |

执行楼层操作后，列表显示编号、作者和内容摘要；上下键或鼠标选择，Enter 确认，输入文字可筛选，Esc 取消。编辑和删除只列出自己的可见内容；`/more` 可加载更多回复后再选择。

直接输入正文后按 Enter 发布。引用或编辑时，Esc 先取消引用（保留已输入的文字）或放弃编辑；再按 Esc 返回列表；正文不为空时会先在底栏询问是否放弃，Enter 确认放弃、Esc 继续编辑。需要输入或确认的操作没有按钮，按键提示统一显示在底栏。Ctrl+C 清空当前输入。当前帖子内点赞、收藏等操作保留输入框内容；网络失败也保留当前输入，再次 Enter 使用相同幂等键，避免重复发布。粘贴的 `/命令` 按普通正文处理；手工输入以 `/` 开头的正文时使用 `//` 转义。

本版暂时禁用 Forum 附件，相关命令不显示且拒绝执行；代码和已有文件保留。Chat 附件不受影响。`/status` → API Key 可创建论坛读写权限，名称会公开显示为来源标记。撤销的 Key 在查看菜单中以暗色显示，仍可查看和复制历史记录。