NapCat QQ for VS Code
在 VS Code 原生编辑器里聊 QQ。由 LimeLisest 维护的独立第三方客户端。基于 NapCat / OneBot v11，聊天记录默认以 C 风格代码显示，底部直接写草稿，沿用编辑器的字体、主题、行号、查找与分屏。
- 原生聊天：在编辑器底部写草稿，Enter 发送，Shift / Ctrl+Enter 换行；文字、图片、视频和文件按占位符顺序发送。
- 会话与提醒：统一列表、收藏置顶、内置搜索和收纳箱；@我、回复我、撤回消息分别高亮。
- 图片与表情：图片默认显示
[图片]，支持悬浮预览和引用到草稿；!表情 / ！表情 补全打开收藏表情面板。
- 资源复用：同一 VS Code 窗口内复制图片 / 视频占位符，粘贴到其他会话自动携带资源；外部图片按内容识别。
- 文件收发：拖入文件、上传进度、取消排队、失败重试、下载另存为。
- 回复与指令：可删除的回复 / @ 占位符，英文
/ 指令与中文说明，查询、群文件、申请处理和群管理。
- 本地恢复：独立草稿、未完成发送保存、重连补历史和附件缓存管理。
快速开始 · 界面预览 · 安装与连接 · 使用教程 · 配置说明 · 常见问题 · 开发与依赖
扩展标识：LimeLisest.limelisest-napcat-qq。本项目自制“消息气泡 + 代码符号”图标，不使用 QQ 企鹅或官方品牌图标。更新记录见 CHANGELOG，问题反馈见 SUPPORT，上架步骤见 Marketplace 发布说明。
快速开始
- 准备已登录 QQ 的 NapCatQQ，启用 OneBot v11 WebSocket 服务端，消息上报格式选择
array。
- 从 Releases 下载
.vsix，在 VS Code 中通过“从 VSIX 安装”安装，更新后重新加载窗口。
- 点击左侧 QQ 图标，在下方 设置 → 连接设置 填写 OneBot 地址和 Token，测试成功后“保存并连接”。
- 打开好友或群聊，在底部草稿区输入文字，按 Enter 发送。需要换行时按 Shift / Ctrl+Enter。
表情：输入 ! / ！ 后选择 !表情 / ！表情 补全；回复：单击消息正文；@成员：输入 @ 或单击发送者名称；更多操作：输入 /。
界面预览
以下四张图均来自 0.2.8 的真实 VS Code 扩展开发窗口，使用模拟账号与聊天内容，以 1600×1000 视口重新拍摄。使用单个聊天编辑器，已关闭右侧 Copilot / 第二侧边栏；点击图片可查看原尺寸。实际字体和配色跟随你的 VS Code 设置。
原生编辑器与消息高亮
自己发送的消息使用主题绿色，回复我显示淡蓝色，@我显示淡橙色；后两种颜色可以在设置页调整。收到撤回通知或 /recall 成功后，保留本地已接收的原文和图片，在消息块右花括号后同行显示 } // 已撤回，整段使用红字和淡红背景（优先于发送者和提醒颜色）；Python 风格使用 # 已撤回。撤回标记随聊天缓存保存。
连接设置与统一会话列表
页面提供连接地址、Token、聊天设置、高亮颜色和缓存管理。截图中的端口属于测试服务，实际连接请填写自己的 OneBot WebSocket 端口。
表情面板：收藏、最近使用与 QQ 表情
选择 !表情 / ！表情 补全，或输入 /emoji 打开面板，默认进入收藏表情。下图展示同一面板的 QQ 表情 页；支持方向键选择、Enter 插入，选完自动关闭。最近使用按插入顺序排列，最多 10 个。
安装与连接
1. 准备运行环境
使用 VSIX 安装包时，插件的 JavaScript 依赖已经打包，不需要另外安装 Node.js、Python 或 tuiqq。目前主要在 Windows 桌面版 VS Code 上验证；网页版不在支持范围内。
2. 安装 VSIX
在 VS Code 中打开扩展视图（Ctrl+Shift+X），点击右上角 … → 从 VSIX 安装… / Install from VSIX…，选择安装包。更新已有版本后，执行 Developer: Reload Window / 开发人员: 重新加载窗口。
早期本地安装包使用 rynxis.vscode-qq，当前发布者为 LimeLisest，内部名称为 limelisest-napcat-qq。VS Code 会将两者视为不同扩展；安装新版后请停用旧版，避免重复连接。原扩展的安全存储与聊天缓存不会自动迁移，需在新版重新配置连接。
也可以在能使用 code 命令的终端里安装：
code --install-extension ./artifacts/limelisest-napcat-qq-0.2.17.vsix --force
没有安装包时，安装 Node.js 22 或更高版本及 Git，在终端执行：
git clone https://github.com/limelisest/VSCodeQQ.git
cd VSCodeQQ
npm ci
npm run build
npm run package
默认生成开发包 artifacts/<name>-<version>-pre.vsix，带 VS Code 预发行标记，日常开发不递增版本号。明确发版时才更新版本并执行 npm run package -- --release 生成正式包。开发工具及其 GitHub 地址见开发与依赖。
3. 配置 NapCat
先按 NapCat 官方文档完成安装并登录 QQ，然后在 NapCat WebUI 的网络配置中新建 WebSocket 服务端（正向 WS），启用并保存。官方配置说明
本机部署可采用下面的配置：
| 配置项 |
示例 / 要求 |
| 网络类型 |
WebSocket 服务端（正向 WS） |
| 监听地址 |
127.0.0.1，用于与 VS Code 同机连接 |
| 端口 |
3001，也可以使用其他空闲端口 |
| 消息上报格式 |
array / 数组，用于解析图片、回复和 @ 等消息段 |
| Token |
设置 OneBot 服务的鉴权 Token，连接插件时填写相同值 |
| 上报自身消息 |
按需开启，以接收其他 QQ 客户端发出的自身消息 |
连接地址对应上表时为 ws://127.0.0.1:3001。NapCat WebUI 的管理地址、登录 Token，与 OneBot 服务的连接地址、Token 分开配置，请勿把 WebUI 页面地址填入插件。
NapCat 部署在另一台机器时，填写该机器可访问的地址，并配置对应监听地址、端口映射和鉴权。插件传输图片、文件时不要求 NapCat 直接读取 VS Code 的本地路径。
4. 连接插件
- 点击 VS Code 左侧的 QQ 消息图标。
- 在列表下方 设置 区点击 连接设置；也可点列表标题栏齿轮，或通过
Ctrl+Shift+P 运行 QQ: 连接设置。
- 填入 OneBot WebSocket 地址和 Access Token。
- 点击 测试连接，确认返回正确的登录账号。
- 点击 保存并连接，等待状态栏显示
QQ · 已连接。
- 在列表中选择群聊或好友，在聊天文档底部草稿区输入消息。
Token 保存在 VS Code SecretStorage。编辑配置时，Token 留空表示保持原值；需要移除时勾选“清除已保存的 Token”。“测试连接”使用临时连接，不保存表单，也不切换当前聊天账号。
已有 tuiqq 配置可通过 QQ: 导入 tuiqq 配置 选择 config.json，读取 ws_url、ws_token 和历史条数；导入后再保存并连接即可。
使用教程
英文 / 指令
在聊天文档的草稿区输入 /，使用方向键选择指令，Enter 执行。指令名全部英文，候选行直接显示中文说明；群管理只在群聊中出现。没有自动弹出时按 Ctrl+Space。
- 原有入口统一为
/emoji、/image、/video、/file、/mention；中文指令名已移除。
- 常用查询：
/status、/version、/login、/user、/group、/member、/members。
- 消息操作：
/reply、/recall、/forward、/merge_forward、/forward_info、/like、/poke、/react。
- 群功能：
/notices、/notice、/essence、/group_files、/ban、/card、/title、/requests。
/help 打开带中文说明的完整菜单，可按英文名或中文功能搜索。
选择后按提示填写参数或选择对象，Esc 取消。查询结果在本地只读编辑器中查看；变更操作会展示对象和参数供确认。取消不发送消息、不清空已有正文和回复。账号或连接变化会中止旧操作。
整个草稿只有一个已知英文指令（例如 /status）时，直接 Enter 也会执行指令，不会发到 QQ。混有普通正文时仍按聊天消息发送。
输入 ! 或 ！，原生补全只显示 !表情 或 ！表情 入口，不显示表情内容。选中补全后，移除本次触发文字并打开底部表情面板，默认显示收藏表情；方向键选图、Enter 插入当前光标处并自动关闭。只输入感叹号、手动输入完整文字或 Esc 取消补全，都不会自动打开面板，也不会自动发送。
回复时，草稿会显示 [回复:群名片]，悬浮查看原文和图片。直接删除标记就取消回复，撤销删除可恢复绑定；重新选择回复会替换原来的标记。发送时标记转为真实回复信息，不会作为文字发出；只写回复标记不能发送空消息。
完整指令清单、OneBot 标准接口对照、后端兼容范围见 OneBot 与 / 指令。
英文指令与中文说明预览（0.2.8，1600×1000）
文字、回复与 @成员
只在底部 草稿 分隔线下面输入。历史消息使用 C 风格语法展示，无需自己填写函数、引号或分号。
| 操作 |
方法 |
| 发送草稿 |
Enter |
| 换行 |
Shift+Enter 或 Ctrl+Enter；macOS 为 Cmd+Enter |
| 回复消息 |
单击消息正文（或 msg 字段）、右键菜单，或 Ctrl+Shift+R |
| 取消回复 |
删除草稿内 [回复:群名片]，或 /cancel_reply、命令 QQ: 取消回复 |
| @群成员 |
输入 @ 后从补全列表选择成员；也可用工具栏 @ 或 /mention 搜索选择 |
| 插入表情 |
输入 ! / ！ 后选择 !表情 / ！表情 补全入口；或使用 /emoji |
| 插入图片 |
/image、编辑器工具栏图片按钮，或粘贴剪贴板图片 |
| 插入视频 |
/video、命令 QQ: 插入视频，或拖入 / 粘贴视频文件 |
| 插入文件 |
/file、命令 QQ: 插入文件，或按住 Shift 拖入文件 |
| 复制原文 |
在消息上右键 → QQ: 复制消息原文 |
| 回到底部 |
编辑器工具栏向下箭头，或状态栏“返回最新 / 新消息” |
| 查看更早消息 |
命令 QQ: 加载更多记录 或工具栏历史按钮 |
如果补全列表未自动出现，可以按 Ctrl+Space 手动触发。补全列表打开时，Enter 先确认当前候选项。输入法组合输入期间不会发送。
群聊中可紧接中文输入 @，按群名片、昵称或 QQ 号筛选，方向键选择、Enter 确认；确认候选项不会发送消息。对历史消息右键选择 QQ: @这位发送者 可直接加入草稿。成员加载失败后，下次输入 @ 会重试。
@成员插入后显示为 [@:群名片]，发送时按绑定的 QQ 号转换为真实提及。单击聊天记录中的 @ 或发送者 name[] 的群名片，也可将该成员加入当前会话草稿；回复引用里的 @ 同样可点。同名成员会追加号码区分，改名和失败重试仍指向原成员。删除占位符就不发送该提及；旧的 @[QQ号] 草稿仍兼容。群成员列表在打开会话时加载，读取失败后再次输入 @ 会重试。
聊天记录示例：
#define CHAT_NAME "开发群"
#define GROUP_ID "123456"
#define DATE "2026-10-15 12:30:01"
void recv_10001(void) { // 管理员
char title[] = "调试员";
char name[] = "群名片"; // 备注：好友备注
char msg[] = "消息内容[图片]";
}
#define DATE "2026-10-15 12:30:05"
void send_reply_123456(void) { // 我
char name[] = "我的名片";
char replay[] = "群名片：消息内容[图片]";
char msg[] = "收到";
}
DATE 显示本地日期和时间（YYYY-MM-DD HH:mm:ss）。函数内的 title[] 是群头衔（没有则省略），name[] 是群名片 / 会话显示名称；好友备注放在 name[] 行末的注释中，与名称相同时不重复显示，也不再额外显示 QQ 昵称。管理员 / 群主标签仍放在函数行。引号、反斜杠、换行只在展示时进行转义，复制原文和发送使用实际消息内容。
左侧“列表”下方还有独立的 设置 区，可直接连接/断开 NapCat、选择代码风格、切换自动连接，或打开完整设置页。
代码语言风格
如果右侧打开了 Copilot / 聊天侧边栏，可以关闭该区域，为聊天记录留出更多宽度。插件也支持 VS Code 原生分屏。
在 QQ 设置页选择“代码语言风格”，或设置 qq.codeLanguage：支持 C（默认）、Python、JavaScript、TypeScript、Dart、Kotlin、Java、Swift。保存后刷新聊天记录，保留草稿、附件、回复对象和消息原文；隐藏的聊天重新显示时更新。文档继续使用专用 qq-chat 高亮，底部草稿分隔线保持固定格式。
单击正文会选中该条消息作为回复对象，并聚焦草稿；图片、文件和 @ 优先执行各自操作。消息正文支持拖选复制，键盘选择文本不会触发回复。
转发与合并转发
- 转发单条消息：在消息上右键选择 QQ: 转发这条消息，选择目标好友或群，再确认发送。草稿中执行
/forward 也可选择消息转发。
- 合并转发多条消息：右键 QQ: 选择消息合并转发，或执行
/merge_forward，勾选消息（最多 100 条），选择目标并确认。消息列表默认定位到最底部的最新消息，目标会话按最近收发消息时间排序。按原聊天记录顺序发送，保留原始消息引用。
- 查看收到的合并转发：点击聊天里的
[合并转发]，或使用链接打开手势（macOS 为 Cmd+单击）；也可通过 /forward_info 选择记录或输入合并转发 ID。在独立只读编辑器中显示发送者、时间和正文，图片可悬浮预览及打开，嵌套转发可继续点击查看。
取消选择或确认不会发送，原会话草稿、回复和附件保持不变。确认后，目标会话立即显示本地发送状态，并在回执到达后结算消息与列表摘要；详情补取失败不影响已确认的发送结果。未发送成功、已撤回的消息不可转发。超时会提示结果未确认，请检查目标会话后再决定是否重试。查看页最多保留 20 个，每份最多 500 条消息；账号切换或断线后清空，重新连接后可再次打开。视频可通过 [视频] 链接打开；文件和语音在查看页中仅显示占位内容。
合并转发前会检查每条来源消息是否仍能从 NapCat 读取；消息 ID 缓存失效时自动刷新来源会话历史。若仍有消息不可读取，会停止整个转发并提示重新加载历史，避免遗漏所选消息。
查看页仅将当前记录中唯一匹配的原始消息 ID 映射为回复目标；重复或缺失的目标保留“未加载”提示，嵌套记录分别映射，不向当前会话查询引用。
查看合并转发依赖 NapCat 返回内嵌内容或成功执行 get_forward_msg。若后端无法读取，插件会提示在 QQ 中查看，并将错误详情保留在“输出 → QQ 转发诊断”；错误不一定表示记录已过期。插件不会修改 NapCat 配置或修复其服务端能力。
复制图片、视频与草稿附件
在聊天记录中选中完整的 [图片]、[视频:文件名]、[文件:文件名]，或草稿中的 [图片:n]、[视频:n]、[文件:文件名]、[表情:n]，使用 Ctrl+C → 切换会话 → Ctrl+V。粘贴后自动分配新的占位符和资源绑定，可以连同周围文字一起复制；复制、粘贴本身不会发送消息。
资源复制适用于同一 VS Code 窗口、同一登录账号中的聊天文档，重新加载窗口后需要重新复制。外部应用粘回来的纯文字 [图片] 没有资源，不能恢复成图片。[@:成员] 仅在原会话粘贴时保留真实提及，跨会话转成普通 @成员 文字；回复占位符不携带回复绑定。
外部应用拖入 / 粘贴的本地图片、图片路径和剪贴板图片按文件内容识别，生成 [图片:n]，不会直接插入文件路径。拖入时按住 Shift 可使用 VS Code 的放置手势；需要强制作为普通文件发送时使用 /file。
视频
使用 /video 选择视频，或拖入 / 粘贴视频文件，在草稿中显示 [视频:n]。支持识别 MP4、MOV、WebM、MKV、AVI、FLV 容器；按 Enter 后立即清空本次草稿，在对应消息上显示上传进度和发送状态，发送为真正的 OneBot video 段。服务端是否接受某种编码及大小由 QQ / NapCat 决定，插件不转码。
正文保留 [视频:1] / [文件:1] 等简短引用，消息下方按原顺序列出资源；C 风格示例：
char msg[] = "视频[视频:1]，附件[文件:1]";
char *video_1 = "[视频:演示.mp4]";
char *file_1 = "[文件:录音.mp3]";
其他代码风格使用对应的字符串变量语法。拿不到原视频文件名时显示“未命名视频”。视频和文件链接继续支持打开 / 下载及复制到其他会话，消息中的编号不会影响真实发送内容。
聊天、回复引用和合并转发里的视频均保留资源链接。Ctrl+单击打开视频，首次打开时下载并缓存；使用 VS Code 的媒体预览，能否播放取决于当前 VS Code 支持的编码，MP4（H.264）兼容性较好。
图片与表情
收到的图片默认显示为高亮 [图片]。鼠标悬浮时等比例预览，通常限制在 240×160 内，窗口较矮时进一步缩小；通过链接手势（通常 Ctrl+单击）或悬浮窗中的“打开大图”进入 VS Code 图片预览。
复用聊天记录中的图片：悬浮在 [图片] 上，点击 引用到发送栏；也可以把光标放到该图片占位符上，右键选择 QQ: 图片引用到发送栏。图片会作为新的 [图片:序号] 插入本会话草稿；光标在历史区时追加到草稿末尾。已有文字和回复对象保留，按 Enter 才发送。回复的 char replay[] 中的图片同样支持预览、打开大图和引用到发送栏；原消息尚未加载时显示未加载提示。
发送图片时，先在草稿中插入占位符，例如：
这是修改前的截图：[图片:1]
这是修改后的截图：[图片:2]
发送顺序与占位符在文字中的顺序一致。删除占位符就不会发送该附件；重复放置同一个占位符会重复发送。不要手动编造没有导入过的占位符。
表情面板提供：
- 收藏表情：默认打开，读取当前 QQ 账号的收藏表情，支持刷新和加载更多。
- 最近使用：按最近插入顺序去重，最多 10 个，按账号保存。
- QQ 表情：内置常用表情入口。
方向键选择、Enter 插入、Esc 返回草稿。选完会自动关闭面板，选择表情本身不会发送消息；回到草稿后按 Enter 才发送。收藏表情作为图片表情发送，GIF 保持原文件。
文件发送与下载
- 输入
/file 选择文件，或按住 Shift 从本机文件管理器拖到草稿区。
- 等待出现
[文件:文件名] 占位符，悬浮可查看大小；文件夹请先压缩。
- 按 Enter 后草稿立即清空，聊天记录中出现待发送消息。
- 观察该条消息结束花括号后的进度、已传大小和平均速度。
同名文件的占位符自动加序号，上传文件名保持原样。文字、图片和文件混排时，文件会拆成独立消息，按原顺序依次发送；文件上传接口不携带引用，回复只用于文字 / 图片消息。
| 状态 |
含义与操作 |
| 等待发送 |
排在同一会话前面的消息之后，可点 [取消] |
| 上传到 NapCat |
显示分片回执进度，可取消尚未提交给 QQ 的文件 |
| 等待 QQ 确认 |
文件已传至 NapCat，等待最终上传接口返回；此时不提供取消 |
| 成功后无状态文字 |
收到成功回执后清除发送中提示 |
| 发送失败 |
点 [重试] 仅重试这一项 |
| 结果未确认 |
可能已经送达，先检查记录再决定是否重试 |
同一条消息的重发从确认到发送结束会加锁，连续点击只执行一次。连接、刷新、文件下载、转发、收藏表情读取及 / 云端指令也有防重复执行保护；操作结束或取消后可再次操作，不影响其他会话的新消息发送。
上传到 NapCat 的 100% 不等于 QQ 已确认送达。最终 QQ 上传阶段没有连续百分比。文件上传接口报错时，会用本次发送期间收到的新文件回显确认结果（同账号、会话、文件名和大小，且仅一个候选），匹配成功就直接显示成功；无法确认时才保留“结果未确认”，请检查目标会话后再决定是否重试。重试确认默认选中取消；确认重试后会重新传输该文件，不重发相邻的成功消息。
接收文件时，点击文件消息的 [文件:名称] 链接或悬浮操作，选择保存位置。下载完成后可打开所在文件夹。取消或下载失败时不覆盖目标文件；链接过期或后端接口不可用时会提示原因。
NapCat 上报在线文件传输回执时，私聊中会显示 // 时间 · 文件传输：对方已接收文件，也支持拒收和取消提示，并随聊天缓存保存。这类事件不提供文件名或文件 ID，因此提示显示在会话中，不关联到某个文件；离线文件等未上报回执的情况无法显示接收状态。
列表、收藏、未读与高亮
左侧使用一个统一的列表显示好友和群聊。收藏会话以前方星标置顶，其他会话前方使用 VS Code 的群聊 / 好友图标。未读气泡默认靠右；鼠标悬停会话行时隐藏气泡，并显示收藏和收纳按钮，按钮平时不占位。点击悬停出现的星标可收藏或取消收藏；右键还可标记已读、设为不提醒。下方是独立的设置区。
群聊行的收纳箱图标（或右键“放入 / 移出收纳箱”）可将群放入收纳箱。在“列表”顶部点击 收纳箱 进入，鼠标悬停群聊行，点击 移出收纳箱 图标可移出，再点顶部入口返回普通列表。收纳状态按 QQ 账号保存在本机，收藏群也可收纳。列表搜索会查找收纳箱里的群。收纳箱入口汇总全部未读；如果都来自不提醒的会话，汇总气泡同样变暗。
列表按**收藏置顶 → 普通未读 → 免打扰 / 不提醒未读与已读会话（同级混排）**排序；同层按最近消息时间排序。列表顶部有一个搜索框。搜索可匹配群名、好友备注、昵称和号码；空格分隔多个关键词，输入即筛选。方向键选择，Enter 打开会话并清空搜索、返回完整列表，Esc 或 × 清除；标题搜索按钮直接聚焦列表内的输入框。
| 消息类型 |
显示方式 |
| 自己发送 |
当前主题的绿色新增行底色与边线 |
| @我（含全体成员） |
默认淡橙色；标签名称前显示 @ |
| 回复我 |
默认淡蓝色；标签名称前显示 ↩ |
| 普通未读 |
标签名称前显示 ●，角标保留未读数量 |
| 已撤回 |
右花括号后显示 // 已撤回，整段红字和淡红背景 |
撤回样式优先于自己发送、@我和回复我；同时 @我和回复我时，优先显示 @我颜色；已读后仍保留消息高亮。可以在 QQ 设置页修改两种提醒色和弹窗范围。
所有群聊都显示本地未读数量；QQ 免打扰、未知提醒状态或手动设为不提醒的会话使用暗色数量气泡，不参与普通未读置顶。免打扰群的 @我和回复我仍作为例外提醒。免打扰例外按当前这条消息判断，后续无关消息不会沿用之前的 @/回复状态弹窗。手动“设为不提醒”的会话全部静默，但仍显示暗色未读数量。好友的 QQ 免打扰状态暂无法同步，可使用本地“设为不提醒”。
收到新消息和自动置底不会直接清除未读；主动打开会话、在底部操作聊天或标记已读后清除。未读状态仅在插件本地统计，不与 QQ 手机端同步。
撤回消息
输入 /recall，选择消息并确认后，插件请求 NapCat 撤回；能否撤回由 QQ 的权限和时间限制决定。收到其他人的撤回通知时，也会更新已加载的对应消息。
本地已接收的原文和图片会保留，消息结尾显示为：
#define DATE "2026-10-15 09:42:30"
void recv_10003(void) {
char name[] = "小周";
char msg[] = "这一条是重复发送的。";
} // 已撤回
整段标红，撤回标记随本地缓存保存；迟到的历史或详情响应不会覆盖该标记。插件不能恢复此前未接收、未缓存的消息原文。
自动跟随与恢复
在底部阅读或输入时，新消息到达会继续置底并保留草稿和选区。手动上翻后暂停跟随，状态栏显示新消息数量；点击返回最新后恢复跟随。加载更早历史时保持阅读位置。草稿底部默认留出 24px（约一行）空白，在草稿末尾换行时继续跟随到最新一行；编辑草稿中间内容时保持光标可见。
- 每个会话独立保存草稿；未完成发送独立保留，不受普通历史条数上限影响。
- 重载窗口后，未完成发送标为“结果未确认”，不会自动重发。
- 误删历史或分隔线时会自动修复，只保留草稿区域的有效编辑。
Ctrl+S 只保存，不发送。
- 必要时执行
QQ: 重建聊天文档（恢复已缓存草稿）。
- 断线自动重连；恢复标签时先显示本地缓存，优先读取当前及已打开会话的最近一页，再在后台补拉已打开及最近 20 个活跃会话的历史。慢请求不会独占所有加载名额，同一页请求去重；空会话会显示加载中或重试提示。
配置说明
点击 QQ 列表标题栏的齿轮，进入连接设置页。这里可以修改连接、通知、高亮、历史条数，查看附件缓存占用并清理无用副本；也可以在 VS Code 设置中搜索 qq。
| 配置 |
默认值 |
说明 |
qq.codeLanguage |
c |
聊天代码风格：C、Python、JavaScript、TypeScript、Dart、Kotlin、Java、Swift |
qq.wsUrl |
ws://127.0.0.1:3001 |
OneBot v11 正向 WebSocket 地址 |
qq.autoConnect |
true |
插件激活时自动连接 |
qq.historyCount |
50 |
初次读取历史数量，10～500 |
qq.messageLimit |
500 |
每个会话普通历史上限，50～2000；未完成发送另行保留 |
qq.notifications |
all |
弹窗范围：all / mentions / off |
qq.mentionColor |
#E5A030 |
@我高亮色，背景自动淡化 |
qq.replyColor |
#409CFF |
回复我高亮色，背景自动淡化 |
qq.cacheRetentionDays |
7 |
无引用附件保留天数，1～90 |
消息、草稿、收藏及媒体保存在 VS Code 插件全局存储目录中，按账号隔离。无引用附件按小时清理，保护草稿、有限撤销记录、未完成发送和历史图片引用；最近一小时导入的附件也有保护期。图片媒体缓存另按 128 MB / 7 天清理。
插件运行于本机 UI 扩展宿主。打开 WSL / SSH 工程时，连接地址中的 127.0.0.1 仍表示运行桌面 VS Code 的机器。
常见问题
连接失败或一直没有会话列表
确认 NapCat 已登录 QQ，启用的是 WebSocket 服务端，端口和 OneBot Token 与插件一致；消息上报格式选择 array。先使用“测试连接”，再“保存并连接”。详细错误可在 VS Code 输出 → QQ 查看。初始化失败会自动退避重试。
点击图片、文件或操作链接没有反应
图片、文件和重试等操作使用原生编辑器文档链接，通常通过 Ctrl+单击 打开；也可悬浮后操作。消息正文、发送者名称和 @ 支持单击回复或插入提及；回复还可使用右键菜单或 Ctrl+Shift+R。已撤回的正文不再提供点击回复入口。
输入感叹号没有打开表情面板
! / ！ 只触发补全候选，接受 !表情 / ！表情 补全后才打开面板。没有候选时按 Ctrl+Space；Esc 取消后会保留原文字。如需把感叹号原样发出去，先取消候选，再按 Enter。/emoji 也可打开同一个面板。
图片或收藏表情显示失败
先检查 NapCat 连接和图片地址是否可访问，再刷新表情列表；加载失败的表情格子可以点击重试。插件会尝试通过后端重新获取图片地址，已过期或被删除的媒体可能无法恢复。
文件上传提示接口不可用
文件发送使用 NapCat 的 upload_file_stream 及群 / 私聊上传接口，需要后端支持这些能力。请按 NapCat 文件处理文档 检查版本与配置。普通 OneBot v11 实现不一定支持本插件用到的 NapCat 扩展接口。
大小限制和暂未支持的内容
- 图片：单张及单条消息图片总大小上限为 16 MB，每条最多 8 个附件。
- 文件：插件不另设大小上限，实际受 QQ / NapCat、群空间和可用磁盘限制；导入会复制到本地缓存。
- 历史：读取范围受配置上限和后端可提供的记录限制，长时间断线不保证完整补齐。
- 语音、视频等在聊天正文中仍显示文字占位；合并转发支持点击查看，
/record_info 可查询语音文件信息。暂未提供录音、视频播放和全部消息段的发送界面。
开发与依赖
项目与依赖 GitHub
运行插件需要 VS Code 和已登录的 NapCat；下列 npm 库由构建流程安装并打包，使用者无需逐个下载。
image-size 的 GitHub 仓库已归档，维护地址为 Codeberg。依赖版本以 package.json 和 package-lock.json 为准；第三方声明见 THIRD_PARTY_NOTICES.txt。
模块职责、消息更新路径、发送约定和缓存兼容说明见 架构与维护约定。
构建与测试
npm ci
npm run build
npm test
npm run test:extension
npm run package
build：TypeScript 类型检查并生成 dist/。test：单元测试，运行前需要先构建。test:extension：打开独立 VS Code 测试窗口，连接模拟 NapCat，不向真实 QQ 联系人发送消息；报告和截图写入 .test-output/。需要桌面环境及可启动的 VS Code，可用 VSCODE_EXECUTABLE 指定可执行文件。screenshots：npm run screenshots 使用独立测试窗口和模拟数据，以 1600×1000 视口生成四张预览图，关闭右侧第二侧边栏，不发送 QQ 消息。输出位于 .test-output/previews/，逐张检查后再替换 docs/images/；当前脚本使用 Windows 桌面版 VS Code。package：将已有构建打包到 artifacts/，修改代码后先重新运行 build。
构建后，在 VS Code 打开本仓库，按 F5 启动扩展开发窗口。Windows 默认用户安装路径可使用 node scripts/install-extension.cjs 安装并校验本地 VSIX；其他路径使用 VS Code 的“从 VSIX 安装”入口。
使用已有 tuiqq 配置进行真实 NapCat 的只读验证：
node dist/test/live.cjs "path/to/tuiqq/config.json"
脚本不发送消息，结果写入 .test-output/live-result.json。请勿将包含 Token 的本地配置提交到仓库。
图标与项目身份
商店图标为本项目绘制的消息气泡与代码符号，提供 256×256 PNG；侧栏和聊天标签使用同一图形的 SVG 版本。图标源文件见 media/icon.svg。
本项目是独立的 NapCat / OneBot QQ 客户端。QQ、NapCat 等名称用于说明连接对象和兼容范围，不代表官方出品或合作关系。
许可证
本插件采用 MIT 许可证。NapCat 及其他依赖遵循各自项目的许可证。
