v0.1.2 — Windows Bug Fixes & Startup Flow Optimization

This is the English version — 此为英文版本

One command instead of three, and the QR code actually works

v0.1.1 was the first Windows package that ran on real hardware. v0.1.2 is the one that is
comfortable to start: the three-step startup became one step, the QR code path was rebuilt,
the protocol side is now genuinely launched, and the panel stops claiming success when a write
failed. Everything below was reproduced on real Windows hardware, fixed, and re-verified.

Unzip and run. No installer, no service, no Node.js required — the runtime ships inside the
package. This release is attached as Win-v0.1.2.zip.

How to use it

Step	What to do
0	Unzip the whole archive to a plain ASCII path, e.g. D:\EstrellaBot. Do not run it from inside the zip, and avoid Desktop, Chinese characters and spaces in the path.
1	Quit desktop QQ completely (including the tray icon) and use a secondary account. Both are hard requirements, not advice: one QQ session per machine, and the protocol side carries a ban risk.
2	Double-click 一键安装.bat — it checks the environment, repairs what is missing, fetches the QQ protocol side (~30 MB, resumable), and opens the console. No black window at any point. It asks exactly one question: whether to create a desktop shortcut. For an unattended run: 一键安装.bat --yes.
3	In the console, press 「打开二维码登录」 and scan it with the secondary account's mobile QQ.
4	Fill in 「放行的群号」 (required, digits only, comma-separated) and your model API key, then press 「一键启动」.

From then on, the desktop icon (or 2-START.bat) is all you need — the protocol side starts
behind it, and the login is remembered. Note that it never speaks on its own: pressing
一键启动 once per session is deliberate design, not breakage.

What changed from the previous Windows package

Symptom you would have hit	Root cause	Now
Getting started meant three separate .bat files, in a specific order	1-SETUP.bat → 3-START-NAPCAT.bat → 2-START.bat, each with its own window and its own way to fail	One command: 一键安装.bat — environment check, self-repair, protocol side, console, shortcut. The numbered files still ship for manual use.
The QR code never appeared; refreshing it did nothing	Four separate defects: the portable package could not read the local QR image, the CSP blocked blob: (the code arrived broken), the dialog had two 关闭 buttons, and 「重启协议端」 only pretended to restart	QR is read locally first; blob: is allowed; one 关闭 button, no flashing; restart really restarts — force-kill, orphan QQ cleanup, WebUI port candidates, and the failure reason is shown with a retry button instead of a broken image.
The protocol side never started — on any machine	The hidden launch chain passed arguments in the wrong order, so NapCat was never spawned, and nothing checked	Launch route reset: two VBScript-level fatal errors fixed, a vbs-lint.py guard added, and the napcat.log file lock released by both implementations.
A failed save looked saved (green success colour)	Eighteen write operations were hard-coded to report ok	Everything reports through one path, coloured by the backend's real result.

Bug fixes

1. Startup: three commands → one. Double-click 一键安装.bat and it is done; the console
   carries its own built-in terminal, so the black windows are gone from the happy path.
2. QR code refresh. Readable in the portable package, no more broken image (CSP blob:),
   no duplicate 关闭 button, no flashing on refresh, and 「重启协议端」 force-kills the old
   process, clears orphaned QQ processes and walks the WebUI port candidates.
3. Protocol-side launch route reset. The hidden launcher (launch-napcat-hidden.vbs) had two
   fatal VBScript errors and mis-ordered arguments — NapCat was never actually started. Fixed,
   guarded, and verified on real hardware.
4. Panel display errors. Failed writes no longer render as success (18 call sites); the
   启动链路 empty state is a read-only checklist (including 放行的群聊, the step people forget);
   the first screen no longer flashes demo data; the private-chat field is correctly named
   「同意私聊的 QQ 号」 and sits above 「放行的群号」, whose hint previously said the opposite of
   the real behaviour; the portable package no longer claims to be the container route.

Also in this release: 4-DIAG.bat collects everything a support request needs in one run
(and verifies package freshness byte-by-byte instead of by keyword); 3-START-NAPCAT.bat no
longer flashes and closes; closing the window no longer drops the login session; command
execution moved into the panel; account login is QR-only; and a front-end DOM guard now walks
33 pages for blank screens and runtime errors — the four existing gates were all server-side and
could not see a frontend that rendered nothing.

Upgrading from an earlier package

The flow changes, your data does not: app\config.json is not overwritten, so your keys and
group numbers survive. Unzip over the old folder (or into a fresh one) and double-click
一键安装.bat. Old shortcuts pointing at 1-SETUP.bat can be deleted and re-created by the
installer.

Verified, not assumed

Windows 11 ARM64 (UTM virtual machine; x64 binaries through the Prism layer), 2026-10-14:
three lights green — HTTP 3000 / WebSocket 3001 / WebUI 6099 — the QR code appears and can be
refreshed, and a scanned login completed.

Not verified on real hardware yet: this release's panel copy changes (the 私聊 field rename
and the group-allowlist hint) and re-pressing 「重启协议端」 while the protocol side is already up.

SHA256SUMS.txt inside the package lists the checksums of the key files; check any of them with
certutil -hashfile <file> SHA256 on Windows.

Download: Win-v0.1.2.zip
SHA-256: d2e87e252b8b05a9ef204ee120f2ed5820d395a59f6e87ef3b10ca515fdd0e31
Size: 46,697,556 bytes (2398 files)

About this tag

A tag is a bookmark, not a copy. The repository keeps growing a page at a time (one commit per
page, with an unreadable hash for a page number); v0.1.2 is a name stuck to one specific page,
so "the build I downloaded as 0.1.2" and "the code that produced it" can always be found again.
This release deliberately creates the tag after the content was pushed, so it points at the
commit that actually contains what you downloaded.

---

这是中文版本 — This is the Chinese version

三条命令变一条，二维码真的能用了

v0.1.1 是第一个真在 Windows 上跑起来的包；v0.1.2 是第一个启动舒服的包：三步启动变一步、
二维码这条链路重做、协议端真的被拉起、面板不再把失败说成成功。下面每一条都在真机上复现过、修好过、
又复验过一遍。

解压就能用：不需要安装程序、不装服务、不用你装 Node.js —— 运行时在包里。本版附件为
Win-v0.1.2.zip。

怎么用

步骤	做什么
0	把整个压缩包解压到一个纯英文路径，例如 D:\EstrellaBot。不要在压缩包里直接双击，也别放桌面、中文或带空格的路径。
1	先把电脑端 QQ 完全退出（连托盘一起退），并且用小号。这两条是硬要求不是建议：一台机器只能有一个 QQ 登录；第三方协议端有封号风险。
2	双击 一键安装.bat —— 自动检测环境、缺什么补什么、联网准备 QQ 协议端（约 30MB，可续传）、打开控制台，全程没有黑窗口。它只会问你一个问题：要不要建桌面快捷方式。想完全不被打断：一键安装.bat --yes。
3	在控制台里点 「打开二维码登录」，用小号的手机 QQ 扫一次码。
4	填好 「放行的群号」（必填、纯数字、逗号分隔）和模型 API Key，点 「一键启动」。

以后每天双击桌面图标（或 2-START.bat）就行：协议端会自动跟着起，登录也已记住。注意它不会自己开口
说话 —— 每次要你在控制台点一次「一键启动」，这是刻意设计，不是坏了。

与之前的 Windows 包比，改了什么

你之前会遇到的症状	根因	现在
上手要按顺序双击三个 .bat	1-SETUP.bat → 3-START-NAPCAT.bat → 2-START.bat，三个窗口、三处都能出错	一条命令：一键安装.bat —— 检测、自修、协议端、控制台、快捷方式一次做完。三个编号 bat 仍保留供手动使用。
一直不出二维码，刷新也没反应	四个缺陷叠在一起：便携包读不到本地二维码、CSP 拦住 blob:（图是裂的）、弹窗有两个「关闭」、点「重启协议端」只是假装重启	二维码本地优先读取；放行 blob:；只剩一个「关闭」、刷新不闪；重启是真的重启 —— 强杀旧进程、清孤儿 QQ、逐个试 WebUI 端口，失败时给原因和按钮，不再是裂图。
协议端从来没被拉起来（每台机器都这样）	隐藏启动链参数错位，NapCat 压根没被启动，而且没有任何东西检查	拉起路线重置：两个 VBScript 致命错误修好，新增 vbs-lint.py 防复发，napcat.log 的文件占用（两份实现都有）也放开了。
保存失败却显示成绿色「成功」	18 处写操作把回报写死成 ok	全部走统一回报，按后端真实结果判色。

修复了什么

1. 启动方式：三条命令 → 一条。 双击 一键安装.bat 即完成；控制台自带网页终端，黑窗口从主路径消失。
2. 二维码刷新。 便携包能取到码、不再裂图（CSP 放行 blob:）、弹窗不再有两个「关闭」也不再闪；
   「重启协议端」会强杀旧进程、清孤儿 QQ 进程、逐个试 WebUI 端口候选。
3. 协议端拉起路线重置。 隐藏启动器 launch-napcat-hidden.vbs 里两个 VBScript 致命错误 + 参数错位 ——
   NapCat 实际上从未被启动过。已修复、已加防复发守卫、已在真机复验。
4. 面板显示错误。 写失败的回报不再显示成绿色成功（18 处）；「启动链路」空态改成只读检查表
   （含「放行的群聊」——维护者点名最容易忘的一步）；首屏不再闪演示数据；私聊入口正名为
   「同意私聊的 QQ 号」并移到「放行的群号」之上，后者的提示语此前与真实行为相反；便携包不再误报
   「容器」文案。

本版还有：4-DIAG.bat 一键收集排错所需的全部证据（「包新旧」判据改为逐字节核对，不再靠关键词）；
3-START-NAPCAT.bat 不再一闪即关；关窗口不再掉登录态；命令执行内置到面板；账号登录只认扫码；
新增前端 DOM 守卫逐页遍历 33 个页面查白屏与运行时错误 —— 原有四层门禁全在服务端，看不见「前端渲染
成空白」这类故障。

从旧包升级

流程变了，数据没变：app\config.json 不会被覆盖，群号和 Key 都还在。把新包解压覆盖到旧文件夹
（或解压到新文件夹）后双击 一键安装.bat 即可。指向 1-SETUP.bat 的旧快捷方式可以删掉，安装器会
建正确的那个。

实测范围

Windows 11 ARM64（UTM 虚拟机；x64 程序走 Prism 模拟层），2026-10-14：三灯全绿 ——
HTTP 3000 / WebSocket 3001 / WebUI 6099 —— 二维码能出、能换，已扫码登录成功。

尚未真机复验： 本版的面板文案类改动（私聊入口正名、群号提示语），以及协议端已在运行时再点一次
「重启协议端」。

包内 SHA256SUMS.txt 列出关键文件的校验值，可在 Windows 上用 certutil -hashfile <文件> SHA256
逐个核对。

下载： Win-v0.1.2.zip
SHA-256： d2e87e252b8b05a9ef204ee120f2ed5820d395a59f6e87ef3b10ca515fdd0e31
大小： 46697556 字节（2398 个文件）

关于这个标签

标签是书签，不是副本。仓库是一页页往前长的（一次提交一页，页码是一串读不懂的 hash）；v0.1.2 就是贴在
某一页上的名字 —— 于是「我下载的 0.1.2」和「产出它的那份代码」永远能对上。本版特意在内容推送之后
才打标签，让它精确落在那次提交上。

v0.1.1 — Windows: official portable package, verified on real hardware

This is the English version — 此为英文版本

Windows, officially

This is the first Windows package that has actually been run on Windows. The previous one could not start on any machine — not a problem with your setup, a defect in the package. Everything below was reproduced, fixed and re-verified on real hardware.

Unzip and run. No installer, no service, no Node.js required — the runtime ships inside the package.

How to use it

Step	What to do
0	Unzip the whole archive to a plain ASCII path, e.g. D:\AI\Groupmate. Do not run it from inside the zip.
1	Make sure QQ (the current NT build) is installed.
2	Double-click 1-SETUP.bat — checks the environment, writes the config, downloads NapCat (~30 MB), asks for the bot's QQ number.
3	Double-click 3-START-NAPCAT.bat and scan the QR code with the mobile QQ of a secondary account. Quit desktop QQ completely first.
4	Double-click 2-START.bat — the console opens at http://127.0.0.1:8788/. Fill in the group allowlist and your API key, then press One-click start.

From then on, 2-START.bat is the only thing you need.

Two rules that look like breakage when ignored: quit desktop QQ before scanning (only one QQ session can exist on a machine), and leave the NapCat window open after scanning — closing it stops the protocol side, and signing the main account back in kicks the bot offline.

What changed from the previous Windows package

Symptom you would have hit	Root cause	Now
3-START-NAPCAT.bat never showed a QR code	Node (18.20 / 20.12 / 22 onward) refuses to spawn a .bat directly and dies with spawn EINVAL. The bundled runtime sits in that range, so it failed on every machine.	The launcher is passed as an argument to the command processor; paths containing spaces survive too.
"Started successfully" but nothing appeared in the group	The console only checked that a process had been spawned, never that it survived. An empty group allowlist killed the bot on startup.	Failures surface on the page, with the log path. No more false success.
An error naming a setting you cannot find	The message said allow.groups; the interface has no such word.	The message names the real menu path and the required format.
A custom brain saved fine, then every request failed	A provider's web console URL (e.g. platform.deepseek.com/usage) was accepted as an API endpoint.	Rejected on the spot, with the correct endpoint offered.
A window flashed and vanished	The launcher sometimes picked the NapCat build that requests administrator rights.	The non-elevating -user build is preferred.
Self-check claimed "QQ NT not found" while QQ was installed	The check looked at fixed C: paths; the real launcher reads the registry.	Both use the same rule now.
The console took about three seconds to open	Two separate PowerShell invocations, about one second each just to start.	One shared call plus a warm-up. Measured: 2763 ms → 93 ms.
Ports 3001 / 3000 never opened after a successful login	NapCat reads onebot11_<the account that actually signs in>.json, while setup wrote it under the account you typed. One wrong digit and the config was silently absent.	Setup writes an account-less template; the launchers backfill missing port config (your edits are never overwritten — re-scan once to apply).

Upgrading from an older package

The steps do not change: 1-SETUP.bat → 3-START-NAPCAT.bat → 2-START.bat → One-click start.

Your config.json is not overwritten, so your keys and group numbers survive — and so do old defaults.

Verified, not assumed

Windows 11 ARM64 (UTM virtual machine; x64 binaries through the Prism layer). Native x64 hardware has not been run yet — it should only be faster, never slower.

SHA256SUMS.txt inside the package lists the hashes of the key files. Check any of them with certutil -hashfile <file> SHA256.

---

这是中文版本 — This is the Chinese version

Windows 正式版

这是第一个真在 Windows 上跑过的包。上一版在任何一台机器上都起不来 —— 不是你环境的问题，是包的缺陷。下面这些全部是在真机上复现、修好、又复验一遍的。

解压就能用：不需要安装程序、不装服务、不用你装 Node.js —— 运行时在包里。

怎么用

步骤	做什么
0	把整个压缩包解压到一个纯英文路径，例如 D:\AI\Groupmate。不要在压缩包里直接双击。
1	确认电脑装了 QQ（新版 / NT 版）。
2	双击 1-SETUP.bat —— 自检环境、生成配置、下载协议端 NapCat（约 30 MB）、问你要机器人小号的 QQ 号。
3	双击 3-START-NAPCAT.bat，用小号的手机 QQ 扫码登录。扫码前先把电脑端 QQ 完全退出。
4	双击 2-START.bat —— 控制台在 http://127.0.0.1:8788/ 打开。填「放行的群号」和模型 Key，点一键启动。

以后每次只要双击 2-START.bat。

两条不注意就会看着像坏了的规则：扫码前必须先退掉电脑端 QQ（一台机器同时只能有一个 QQ 登录）；扫码后承载 NapCat 的那个窗口不能关 —— 关了协议端就停，把主号登回电脑端会把小号挤下线。

与之前的 Windows 包比，改了什么

你之前会遇到的症状	根因	现在
双击 3-START-NAPCAT.bat 一直不出二维码	Node（18.20 / 20.12 / 22 起）不再允许直接启动 .bat，当场报 spawn EINVAL 崩掉；包内自带运行时正好落在这个范围，所以每台机器必现。	启动器改为作为参数交给系统命令行；解压路径带空格也不会被截断。
提示「已启动」但群里没反应	界面只看进程有没有被拉起来，不看它有没有活下来；「放行的群号」空着会让机器人当场退出。	失败原因直接显示在页面上，并给出日志路径，不再有假成功。
报错里点名一个界面上找不到的设置	提示写的是 allow.groups，而界面里没有这个词。	直接告诉你菜单路径和该填的格式。
自定义大脑存得下、但每次请求都失败	把服务商的网页控制台地址（如 platform.deepseek.com/usage）当成了接口地址。	当场拒绝，并给出正确地址。
双击后窗口一闪而过	启动器有时挑中要管理员权限的那个 NapCat 启动器，抢到提权窗口再退出。	固定优先不提权的 -user 版。
自检说「没检测到 QQ NT 版」，可 QQ 明明装了	自检只查 C 盘固定位置，而真正的启动器读的是注册表。	两边现在用同一条判据。
控制台打开要卡三秒	每次刷新都要单独起两次 PowerShell，而它光启动就要约 1 秒。	合并成一次调用，并在启动时预热。实测：2763 ms → 93 ms。
登录成功了，但 3001 / 3000 端口永远不开	NapCat 只读 onebot11_<实际登录的号>.json，而安装时写的是你当时输入的那个号；差一位数字就静默失效。	安装时多写一份不带号的模板，启动时自动补齐缺的端口配置（不会覆盖你改过的；补完需重新扫码一次才生效）。

从旧包升级

步骤一个字都没变：1-SETUP.bat → 3-START-NAPCAT.bat → 2-START.bat → 点一键启动。

你的 config.json 不会被覆盖，群号和 Key 都还在 —— 旧的默认值也一并留着。

实测范围

Windows 11 ARM64（UTM 虚拟机；x64 程序走 Prism 模拟层）。原生 x64 机器尚未实测，理论上只会更快。

包内 SHA256SUMS.txt 列了关键文件的 SHA-256，可用 certutil -hashfile <文件> SHA256 逐个核对。

v0.1.0 — First public snapshot: the bridge, the console, and macOS

First public snapshot — the state of the project when the repository went public on 2026-10-07. No tag was cut at the time; this release fills the gap at the head of the version line.

What it is

A single-process QQ group bot that sits between OneBot v11 (NapCat) and any OpenAI-compatible model. Zero build — node src/index.js, edit, restart; no bundler, no transpile step. The centre of it is one decision function: does this message deserve a reply? Everything around it is normalisation, gating, prompt assembly and pacing.

The console

A local HTTP UI with no framework and no CDN — brains, providers, groups, persona and logs on one page. Motion follows a written brief rather than taste.

Running it on macOS

macOS was the original target, and it hit a wall: NapCat's macOS build allowlist had fallen behind, so the native path was blocked. The bridge ran on the host with NapCat inside a Linux/ARM64 container instead. Nothing above the protocol layer could tell the difference.

Discipline

Four gates must be green after any change — static contract, behavioural regression, presets, and the panel in jsdom — plus mutation tests that try to break the criteria themselves. The deliberate non-goals are written down too: no hot-plug, no multi-process, no image downloads, a character-based context budget rather than a token one.

Requirements

• Node.js >= 22.13
• A OneBot v11 implementation (NapCat) and an OpenAI-compatible API key

---

首个公开快照 —— 仓库于 2026-10-07 公开时的形态。当时未打 tag，本版本用于补齐版本线的起点。

项目本体

单进程的 QQ 群机器人，夹在 OneBot v11（NapCat）与任意 OpenAI 兼容模型之间。零构建 —— node src/index.js，改完重启即生效，没有打包步骤。核心是一个判定函数：这条消息值不值得回；其余是归一化、门禁、提示词拼装与发送节奏。

控制台

本地 HTTP 界面，不用框架、不依赖 CDN —— 大脑、供应商、群、人格、日志同页可见。动效按书面 brief 走，而非凭手感。

在 macOS 上跑起来

macOS 是原本的目标平台，但撞了墙：NapCat 的 macOS 构建白名单落后，原生路线受阻。最终把 NapCat 放进 Linux/ARM64 容器，桥接层留在宿主机。协议层以上完全感知不到差别。

工程纪律

任何改动后四层门禁必须全绿 —— 静态契约、行为回归、预设层、jsdom 里的面板层 —— 外加试图把判据本身改坏的变异测试。刻意不做的事也写下来了：不做热插拔、不做多进程、不下载图片、上下文按字符而非 token 计算。

运行要求

• Node.js >= 22.13
• 一个 OneBot v11 实现（NapCat）与一个 OpenAI 兼容的 API 密钥