LinkChat CLI

本地运行的 TypeScript 终端聊天客户端，直接通过 HTTPS / WebSocket 连接 LinkChat。采用统一无框消息布局、分钟时间、底部输入区及独立频道、成员和历史页面。

安装与启动

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

安装已发布的客户端：

npm install -g linkchat-cli --registry=https://registry.npmjs.org/
linkchat

当前正式版 0.6.3：npm 包页面。

也可以安装下载的包：npm install -g ./linkchat-cli-0.6.3.tgz。

也可以临时运行 npx linkchat-cli@latest。默认服务为 https://linkchat.online；私有服务使用 linkchat --server https://你的域名。仅本机开发允许 HTTP 地址。

首次进入选择登录或注册，成功后在本机保存会话令牌，不保存密码。再次启动自动恢复上次账号、服务器和频道。正常退出保留登录，/logout 注销并清除该账号缓存。令牌过期后重新登录；网络暂时不可用时可以只读浏览缓存。注册是否需要邀请码由服务器决定。

Beta 与可选游戏扩展

测试版安装与更新（需要 Node.js 24）：

npm install -g linkchat-cli@beta
linkchat extension install spire
linkchat

进入频道后输入 /spire，2–4 人创建或加入同一房间。游戏 UI 按需安装，正式后端已启用。更新扩展使用 linkchat extension update spire，卸载使用 linkchat extension remove spire，服务器存档保留。

linkchat update 仍检查正式版；更新 beta 请重复执行 npm install -g linkchat-cli@beta。返回稳定版使用 npm install -g linkchat-cli@latest，稳定版 0.6.3 不支持扩展。SSH 网关由管理员单独升级。

聊天

• /resume：打开独立频道选择器，退出后恢复聊天。
• /history：独立浏览历史消息；进入频道只显示最近 10 条。
• /reply：选择消息并引用回复。
• /thread：查看话题及其回复。
• /members：查看频道成员。
• /search：进入搜索菜单后输入关键词，自动搜索当前频道；多关键词同时匹配，每页 10 条；Enter 查看目标及前后各 5 条上下文，Esc 返回原搜索页与选中项。离线时仅搜索本地缓存，上下文可能不连续。
• /inbox：查看自己的提及和回复；底栏以 inbox N 显示未读提醒。打开目标消息后自动已读，退出列表不会清除未读；离线只读。
• /logout：注销并返回登录。
• /exit 或 Ctrl+D：退出客户端。Ctrl+C 清空输入。

多行输入

Enter 发送整条消息；Alt+Enter 换行，macOS 对应 Option+Return。支持扩展键盘上报的终端也可用 Shift+Enter 换行。客户端会主动请求修饰键上报，并在退出时恢复；终端若仍将组合键作为普通回车发送，需要配置其按键映射。Ctrl+J 也可换行。多行粘贴保留换行，粘贴结束后再按 Enter 发送。

频道选择

/resume 使用独立的紧凑列表：频道按 ID 固定排序，默认选中当前频道；直接输入名称或 ID 模糊搜索，上下方向键选择，PgUp/PgDn 翻页，Enter 进入，Esc 返回。选中行显示 › 和背景高亮；当前频道名称为绿色，右侧显示当前标记或非零未读数。

选择期间继续接收消息，暂缓聊天滚动，返回后补显示当前频道消息。选择当前频道直接收起，不重复加载历史；切换其他频道仍显示最近 10 条。未读数仅统计本次登录期间收到的消息，不跨设备或登录同步。

更新

linkchat --version
linkchat update --check
linkchat update

启动后异步查询 npm 最新稳定版本，超时 3 秒，检查结果缓存 24 小时，不影响登录。检查只发送公开包名，不发送账号、密码或聊天内容。使用 --no-update-check 或环境变量 LINKCHAT_NO_UPDATE_CHECK=1 禁用自动检查。

linkchat update 仅升级当前 npm 全局安装，安装已验证的精确版本，不自动提权。权限错误请修复自己的 npm 全局目录权限后重试。npx 用户重新运行 npx linkchat-cli@latest；项目内安装在项目目录执行 npm install linkchat-cli@latest。更新命令会显示新版的 Node.js 要求。

卸载

npm uninstall -g linkchat-cli

使用 linkchat cache info 查看聊天缓存位置、数据量和同步时间；linkchat cache clear 清理聊天缓存，保留登录信息。删除 update.json 可单独重置更新检查记录。

本地数据与自动同步

• 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 保存上次服务器与频道；令牌不进入聊天数据库、日志或发布包。
• SQLite 按消息 ID 保存正文和话题摘要，历史、回复选择、话题阅读共用消息；已经加载的连续区间可跨重启重新分页，不受原请求游标或 256 页数量限制。
• 每页显示 10 条。打开频道、话题列表或某个话题后，后台补齐最近 50 条消息、50 个话题摘要或 50 条回复；翻页时预读同方向相邻一页。仅在登录验证通过且联网时预读，不自动下载所有话题正文、全部历史或附件原文件，不保存输入草稿。
• 有完整缓存时先显示再后台核对；缺失或被淘汰的区间需要联网补齐，离线不会误报为“没有更多消息”。后台刷新保留选中项及阅读位置。过期游标会提示返回后重新打开。
• 缓存按服务器和账号隔离，30 天未访问淘汰，所有账号合计共享 50 MiB 逻辑数据预算（含实体及分页索引）。SQLite 数据库文件及 WAL 有额外开销；cache info 的 bytes 是预算占用，databaseBytes、walBytes 是实际文件大小，messages、topics 是实体数量。
• 升级首次访问账号时自动迁移有效的旧分页缓存，保留登录信息。升级程序不修改服务器消息；服务端删除或权限变化由后续同步校正。
• SSH 入口使用相同的分页逻辑和预读策略，但缓存仅保留在各自会话内存，断开后不持久化。
• 0.6.3 的动态列表和阅读页共用同步机制：打开和翻页时先显示可用缓存，再后台联网校验；每次最多预读相邻一页，首页更新检查不阻塞当前页。停留期间每 15 秒补查，相关实时事件触发合并刷新；关闭后停止补查。回复、话题和 Inbox 列表尚未操作时跟随最新，移动、筛选或翻页后保持选中目标并提示更新。Ctrl+R 刷新当前查询，不清空筛选；离线只读，服务端拒绝权限时清理相应缓存。
• 成员菜单首次显示在线成员优先的顶部。Home/End 跳到当前筛选结果首尾；回到首项并清空筛选后恢复跟随最新。翻页保留关键词，非 /search 列表只筛选当前页；选中项目移出结果后选择邻近有效项。更新提示区分新增、减少与重排，刷新期间按 Ctrl+R 会合并为一次补刷。
• 如果离线执行 /logout，本地凭证仍会删除，但服务端会话只能等待过期或在联网时另行注销。
• 会话凭证文件与缓存均位于用户目录，升级或重新安装 npm 包不会覆盖它们。

排错

运行 linkchat --help 查看参数。聊天必须在交互式终端运行；网络断开会自动重连，发送状态不确定的消息不会自动重发。客户端要求校验 TLS 证书，不支持 NODE_TLS_REJECT_UNAUTHORIZED=0。

包中只有本地客户端及运行依赖；SSH 服务端独立保留。安装客户端不会启动 SSH 服务。

ANSI 消息颜色

消息正文支持实际 ANSI SGR 颜色序列：标准 16 色、256 色（38/48;5;n）、RGB 真彩色（38/48;2;r;g;b），以及颜色重置（0、39、49）。实时消息和历史页均支持，颜色在消息边界重置。清屏、移动光标、OSC 链接及剪贴板控制不会执行。

通过 API 发送时，可在 JSON 消息正文中使用 \u001b[31m红色文字\u001b[0m；JSON 解码后才是真实转义字符。普通输入框中直接打出的 \x1b 字符串不会自动转换成颜色码。此版本仅支持颜色，不支持加粗、闪烁等其他 SGR 效果。

成员补全与消息布局

输入 @ 后按用户名或昵称筛选当前频道成员，↑↓ 选择，Tab 或回车补全，Esc 关闭；选择成员不会直接发送消息。所有消息采用统一无边框、无背景布局，消息之间空一行；自己的用户名为低饱和青色，其他用户名为浅灰色，日期时间统一暗灰色。用户名右侧统一显示完整日期时间，例如 Alice · 2026-09-09 15:24。

Markdown 消息

普通消息支持标题、粗体、斜体、删除线、行内代码、代码块、有序与无序列表、任务列表、引用、表格、链接。实时消息与历史页采用同一套渲染，标题、引用、列表与链接采用 Codex CLI 的终端排版风格；代码与链接使用终端 ANSI 青色、引用使用绿色，表头使用主题金色加粗；代码块隐藏围栏并保留缩进，数学公式保留源码。

支持 OSC 8 的终端可点击 HTTP、HTTPS 和邮件链接；其他终端显示 URL。显示器不执行 HTML、脚本、清屏或剪贴板控制。代码块在围栏后注明语言即可启用语法高亮，例如 javascript、typescript、python、bash、json、yaml、sql、html、css、rust、go、c、cpp。支持常用简称；未注明、不支持或过长的代码保持普通显示。

包含真实 ANSI 颜色码的消息继续按原始字符画显示，不执行 Markdown 排版。无颜色的字符画建议放在代码块中。表格的展示受终端可用宽度限制，窄屏会改为逐项显示。

发送本地图片

本地客户端输入 /image2ansi /Users/apple/Pictures/photo.png，或 /image2ansi "~/Pictures/my photo.png"。支持绝对路径、相对客户端启动目录的路径、~/ 和带空格的路径。

图片在本机转换为 ANSI 真彩色字符画后发送到当前频道，不上传原文件或文件路径。支持 PNG、JPEG、WebP、GIF、AVIF、TIFF；GIF 仅发送第一帧，不播放动画。透明区域使用深色背景。文件最大 16 MiB、输入最大 4000 万像素，输出自动限制宽度和 32 KiB 消息大小；细节较多时会降低分辨率。其他终端比发送端更窄时，图案仍可能折行。

此命令仅在本地客户端开放，SSH 入口无法读取客户端电脑上的图片。转换失败不会发送消息。

状态栏

单行显示 linkchat v0.6.1 · ~/Public · Admin · 5 online。品牌为浅金色，频道为低饱和绿色，账号昵称（无昵称时使用用户名）为青色 #7ed2c6，分隔点为暗灰色。在线人数数字为浅绿色 #abdfa7，online 为灰色 #808080；右侧发送提示为 Enter。窄窗口按可用宽度裁剪或隐藏部分信息。

连接断开显示 offline；已连接但人数不可用时显示 online unknown。在线人数按当前频道的用户去重，不包含 LinkBot。

在线人数与成员名单

输入 /members 打开当前频道成员名单。优先显示本机缓存，随后后台更新名单和在线状态；首次没有缓存时需要联网加载。缓存不保存在线标记，因此缓存名单中的 ? 表示状态未知。

• 输入昵称或用户名搜索，方向键浏览，Esc 或 Enter 返回聊天。
• 在线成员优先排列，绿色 ● 表示在线，灰色 ○ 表示离线，? 表示无法确认个人状态。
• 名单每 30 秒刷新，也可按 Ctrl+R 手动刷新；更新时保留搜索和选中目标。
• 离线时可浏览已有缓存，不把上次在线状态当作当前状态。私有服务若仅提供在线总数，成员个人状态显示为未知。

引用回复与话题

• /reply：从当前频道选择消息，左右键翻页，上下键选择；输入文字筛选当前页。Enter 选择后在输入框回复，Esc 取消引用并保留正文。
• /thread：选择已有回复的话题，独立浏览讨论。PgUp/PgDn 翻页，r 选择回复对象后返回频道输入框，Ctrl+R 刷新，Esc 返回。
• 每页 10 条。话题自动同步；阅读旧回复时保留位置，在底部时跟随新回复。普通正文、/send、/image2ansi 使用当前引用对象；成功后清除引用，失败保留草稿，结果不确定时请先检查历史。
• 此功能需要支持话题回复的后端，官方服务已支持。

版本显示与命名

左下角显示 linkchat v版本号 · ~/频道，与 linkchat --version 使用同一个包版本。 采用主版本、次版本、修订号三段格式：不兼容修改递增主版本，兼容的新功能递增次版本，问题修复递增修订号。内测使用 -alpha.N，公测使用 -beta.N，候选版使用 -rc.N，正式版不带测试后缀。 当前正式版为 0.6.1。

Ctrl+L 在聊天页重绘动态输入区，在列表和阅读页重绘当前页面；保留草稿、引用、搜索、选中项及阅读位置，不重新输出已提交的聊天消息，不触发网络刷新，也不清除缓存或终端滚动历史。列表和阅读页的 Ctrl+R 仍用于刷新数据。输入 / 查看聊天命令，linkchat --help 查看启动参数。

消息、输入区和底部状态栏左右各留两列空白，窄窗口自动缩小留白。连接提示、命令与 @ 补全、引用栏及多行输入统一参与输入区布局；区域收起时自然上移，不用旧消息填满空位。窗口缩放后，已写入终端历史的正文由终端保留；需要按新宽度浏览旧消息时可使用 /history。

输入显示说明

输入框左侧的 ❯ 和用于排版的留白仅用于显示，不会加入消息正文；用户实际输入的空格和换行属于消息内容。0.6.1 的多行续行可能与首行不对齐，仅影响显示。续行对齐修复目前仅在本机验证，尚未随 npm 版本发布。

输入框为空时按 ?，在输入框下方展开快捷键说明；再次按 ? 或 Esc 收起，继续输入也会收起。内容放不下时用 ↑↓ 查看。底栏右侧显示 ? for shortcuts，窄窗口优先隐藏提示。已有内容或粘贴中的问号作为普通消息文字保留。

搜索与提醒

0.6.2 支持消息搜索与提醒，正式服务已部署对应后端接口。私有服务需要安装对应后端补丁。通过 linkchat --version 查看版本；开发期间的本机补丁额外显示日期和内容指纹。

提醒按收件人和消息合并：同一消息同时提及与回复你，只产生一项；自己发出的消息不提醒自己，代码块、行内代码、链接目标和邮件地址中的 @ 不触发。只记录补丁部署后新产生的提醒。未读状态保存在服务端，通过私有事件及现有 30 秒同步周期同步到其他设备。

本轮不提供成员／日期搜索筛选、话题订阅、声音提醒、批量已读、编辑与撤回。话题订阅后续作为同一 Inbox 的提醒来源扩展。终端运行时标题设置为 linkchat，正常退出或收到退出信号时恢复原标题；终端自定义标题规则可能覆盖应用标题。