luckytri 1.0.0 → 1.0.1

package/docs/zh/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 # 版本记录
 
+## 1.0.1 — 2026-10-05
+
+- 全局 npm 安装后直接运行 `luckytri`，服务端、WebUI、教程和内置插件一并安装；用户数据独立保存，更新和重装继续使用。
+- 管理台首次进入时设置一个密码，支持登录保持、改密、退出与本机命令重置，不再要求查找随机管理令牌；密码只保存加盐校验摘要。
+- 本机 OneBot 反向客户端无需额外令牌，已有地址和登录可接续；远程使用管理密码或已有令牌，拒绝浏览器跨站接入。
+- 启动命令自动重启仍在运行的旧版本；保留现有配置、数据库、备份与迁移流程。
+- 增加实际 npm 包安装、升级、重装、密码与连接回归，以及 Windows/macOS/Linux CI；补充敏感文件和临时数据库的忽略规则。
+
 ## 1.0.0 — 2026-10-04
 
 插件。核心仍然定义她是谁；插件决定她能接触什么世界。

package/docs/zh/connect.md

@@ -8,17 +8,17 @@ LuckyTri 通过「通道」与 QQ 相遇。通道只管消息怎么到达、怎
 
 ## 怎么选
 
-| | OneBot 11 | QQ 官方机器人 |
-| --- | --- | --- |
-| 需要什么 | 自备的 OneBot 11 接入端（支持反向 WebSocket 客户端）与一个 QQ 账号 | QQ 开放平台里的机器人：AppID 与 AppSecret |
-| 连接方向 | 接入端连到 LuckyTri 的 `/onebot/v11/ws` | LuckyTri 连到开放平台的 WebSocket 网关 |
-| 登录 QQ | 在接入端里登录 | 不需要 |
-| 群消息范围 | 全部群消息 | 在开放平台开启「接收所有消息」时是全部；否则只有 @ 她的消息 |
-| 名字 | 群名和昵称都能取到 | 官方接口不提供群名，单聊昵称常为空；可以在「对话」里给会话改名 |
-| 跨群认人 | 以 QQ 号为准，跨群、私聊都是同一个人 | 同一个人在不同群里的 openid 不同；平台给出统一身份（`union_openid`）时才能认出是同一个人 |
-| 回复 | 随时回复 | 在被动回复窗口内（群 5 分钟、单聊 60 分钟）按原消息回复，每个气泡递增序号；超出窗口改发主动消息 |
-| 主动联系 | 没有额外限制 | 发主动消息；对方或群关闭了机器人的主动消息时，她会等对方来找她 |
-| 图片 | 通过接入端取图 | 附件地址走同一条视觉链路，只放行官方媒体域名 |
+|            | OneBot 11                                                          | QQ 官方机器人                                                                                   |
+| ---------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| 需要什么   | 自备的 OneBot 11 接入端（支持反向 WebSocket 客户端）与一个 QQ 账号 | QQ 开放平台里的机器人：AppID 与 AppSecret                                                       |
+| 连接方向   | 接入端连到 LuckyTri 的 `/onebot/v11/ws`                            | LuckyTri 连到开放平台的 WebSocket 网关                                                          |
+| 登录 QQ    | 在接入端里登录                                                     | 不需要                                                                                          |
+| 群消息范围 | 全部群消息                                                         | 在开放平台开启「接收所有消息」时是全部；否则只有 @ 她的消息                                     |
+| 名字       | 群名和昵称都能取到                                                 | 官方接口不提供群名，单聊昵称常为空；可以在「对话」里给会话改名                                  |
+| 跨群认人   | 以 QQ 号为准，跨群、私聊都是同一个人                               | 同一个人在不同群里的 openid 不同；平台给出统一身份（`union_openid`）时才能认出是同一个人        |
+| 回复       | 随时回复                                                           | 在被动回复窗口内（群 5 分钟、单聊 60 分钟）按原消息回复，每个气泡递增序号；超出窗口改发主动消息 |
+| 主动联系   | 没有额外限制                                                       | 发主动消息；对方或群关闭了机器人的主动消息时，她会等对方来找她                                  |
+| 图片       | 通过接入端取图                                                     | 附件地址走同一条视觉链路，只放行官方媒体域名                                                    |
 
 没有哪一种更「正确」：想看到全部群消息、愿意自己维护接入端，选 OneBot 11；不想登录 QQ、也不想维护接入端，选官方机器人，并在开放平台开启「接收所有消息」。
 
@@ -26,14 +26,14 @@ LuckyTri 通过「通道」与 QQ 相遇。通道只管消息怎么到达、怎
 
 LuckyTri 只实现 OneBot 11 的反向 WebSocket 接口，不包含接入端。
 
-| 项目 | 填写 |
-| --- | --- |
-| 协议 | OneBot 11 |
+| 项目                | 填写                                                          |
+| ------------------- | ------------------------------------------------------------- |
+| 协议                | OneBot 11                                                     |
 | 反向 WebSocket 地址 | `ws://127.0.0.1:3210/onebot/v11/ws`（端口以你的 `PORT` 为准） |
-| Token | `.env` 里的 `ONEBOT_TOKEN` |
-| 消息格式 | 数组 |
+| Token               | 本机无需填写；远程可使用管理密码，旧远程令牌仍兼容            |
+| 消息格式            | 数组                                                          |
 
-接入端与 LuckyTri 不在同一台机器时，把 `127.0.0.1` 换成 LuckyTri 的可达地址，并先配置 `ADMIN_TOKEN`。会话键形如 `onebot:<账号>:group:<群号>`、`onebot:<账号>:private:<QQ号>`；早期的 `group:<群号>` 写法仍然识别。
+远程或容器接入请使用 LuckyTri 的可达地址，并先在本机设置管理密码。本机连接可直接沿用原地址和 QQ 登录。
 
 ## QQ 官方机器人
 

package/docs/zh/guide.md

@@ -1,216 +1,192 @@
-<p align="right"><b>中文</b> · <a href="../en/guide.md">English</a></p>
-
-# LuckyTri · 从零上手教程
-
-LuckyTri 在你的电脑上运行，通过 QQ 与人相遇。QQ 有两种连接方式，二选一：**OneBot 11**（自备接入端，反向 WebSocket）或 **QQ 官方机器人**（QQ 开放平台）。两种方式下她的记忆、心情和行为完全一致，区别只在消息怎么到达。模型 API 由你自行配置。
-
-界面右上角可以在「中文」与「English」之间切换，默认中文，选择会记在这个浏览器里。她自己说的话、写的日记和留下的念头不翻译，那是她自己的内容。
-
-## 1. 启动
-
-需要 Node.js 24.5 或更高版本。普通用户直接全局安装：
-
-```powershell
-node --version
-npm install -g luckytri
-luckytri
-```
-
-LuckyTri 在后台启动并打开 <http://127.0.0.1:3210>，首次运行自动生成配置。无需下载仓库或构建 WebUI。终端里的 SQLite 实验性提示不表示启动失败，以能否打开 LuckyTri 为准。
-
-运行 `luckytri paths` 查看本机 `.env`，在本机编辑器中取得 `ADMIN_TOKEN` 并填入管理台。`luckytri --no-browser` 只后台启动，`luckytri start` 前台运行，`luckytri stop` 停止服务。更新使用 `luckytri stop` → `npm install -g luckytri@latest` → `luckytri`，配置与数据会保留；默认目录见 [README](../../README.md#配置数据与隐私)。
-
-从源码开发时，在仓库中执行 `npm install`、`npm run setup`、`npm run build`、`npm start`。下文的 `npm run setup/stop/backup/recovery/plugin` 面向源码用户；全局用户使用对应的 `luckytri setup/stop/backup/recovery/plugin`。
-
-Windows 日常使用可以双击 `启动LuckyTri.cmd`。服务已在运行时，它只打开 LuckyTri。关闭浏览器不会停止服务；停止时双击 `停止LuckyTri.cmd`，或在项目目录执行 `npm run stop`。这条命令只停止当前项目，不会结束其他 Node 进程。前台运行时也可以在该终端按 `Ctrl+C`。
-
-LuckyTri 是「TA 的小世界」，左侧导航分三组、十个入口：
-
-| 分组 | 入口 | 里面有什么                                                                                      |
-| ---- | ---- | ----------------------------------------------------------------------------------------------- |
-| TA   | 此刻 | TA 此刻的心情、正在做什么、最近说的话、放在心上和在等的事；今天的时间线、Token 用量和运行状态条 |
-| TA   | 内心 | 心灵星图（TA 的自我线索）、放在心上的便签、心情彩带                                             |
-| TA   | 人际 | 人物星系、每个人的详情、TA 在各群的样子                                                         |
-| TA   | 一生 | 日记本与那天的 TA、回顾、我的来路与章节、约定与期待、书架                                       |
-| 日常 | 时间 | TA 实际生活的记录：今日的活动、待办、作品库、持续项目、体验记录                                 |
-| 日常 | 对话 | 会话列表、实时聊天与「为什么这么说」、反馈、会话设置、模拟消息、回到那一刻（回放）              |
-| 日常 | 记忆 | TA 记得的事、资料书架                                                                           |
-| 设置 | 天性 | 名字与性格（旁边的光团实时预览）、作息、TA 的日子、每日 Token、高级指令、试聊                   |
-| 设置 | 系统 | 连接 QQ、模型库、运行开关                                                                       |
-| 设置 | 插件 | 启用、安装和卸下她接触世界的方式。见 [插件](plugins.md)                                         |
-
-界面的颜色、天空和动效跟着 TA 的心情与作息变化：开心时暖、低落时灰蓝、睡着后变成夜晚。左下角可以把主题固定成某一种，也可以「减少动画」。右下角的小 TA 戳一下会回应一句，按住是摸摸头，双击或点「聊聊」打开试聊；这些只是界面动画，不会改变 TA 的心智。手机上导航在底部，其余入口在「更多」里。
-
-## 2. 本机令牌
-
-首次启动已生成配置；也可以提前初始化：
-
-```powershell
-luckytri setup
-luckytri paths
-```
-
-没有 `.env` 时，setup 会写入管理令牌和 OneBot 连接令牌。已有 `.env` 会原样保留。
-
-```dotenv
-HOST=127.0.0.1
-PORT=3210
-ADMIN_TOKEN=
-ONEBOT_TOKEN=
-LLM_API_KEY=
-```
-
-| 字段                                | 用途                                                            |
-| ----------------------------------- | --------------------------------------------------------------- |
-| `ADMIN_TOKEN`                       | 打开 LuckyTri 和调用 HTTP API；停止命令也会使用                 |
-| `ONEBOT_TOKEN`                      | OneBot 11 接入端连接 `/onebot/v11/ws`（只用 OneBot 方式时需要） |
-| `LLM_API_KEY`                       | 可选；非空时优先于 LuckyTri 里保存的模型密钥                    |
-| `LUCKYTRI_CHANNEL`                  | 可选；`onebot` 或 `qqbot`。设置后在界面里不能更改连接方式       |
-| `QQBOT_APP_ID` / `QQBOT_APP_SECRET` | 可选；QQ 官方机器人的凭据，优先于界面里保存的                   |
-| `HOST` / `PORT`                     | 监听地址和端口；本机使用保持默认                                |
-
-页面第一次取数据时会弹出窗口要求输入 `ADMIN_TOKEN`。令牌只留在当前标签页。修改 `.env` 后必须重启。不要把 `ADMIN_TOKEN` 填给 QQ 接入端，也不要把 `ONEBOT_TOKEN` 当成管理台密码。
-
-## 3. 先在模拟模式试聊
-
-默认开启模拟模式，消息不会发到 QQ。
-
-1. 打开「对话」，点会话列表上方的「＋ 添加会话」，填写测试群号和名称。
-2. 在中间的聊天里点「模拟消息」，以一位群友的身份输入一句普通消息并发送。
-3. 点 TA 回复下面的「为什么这么说」查看理由；「TA 扫了一眼」「TA 看了，没出声」会显示成聊天里的分隔条。
-
-没有模型密钥时，模拟回复使用本地样例，不调用模型。有密钥后，同一条路径会走真实发言流程，但仍然不发 QQ。模拟消息写进模拟会话，不会改变 TA 的心情、关系和记忆。
-
-「模拟消息」只在模拟模式下可用。右下角小 TA 的「聊聊」和「天性」右侧的试聊是另一回事：走真实链路，读取 TA 此刻的心智，天性页还可以带上没保存的草稿，但什么都不写入，也不发 QQ。
-
-## 4. 连接模型
-
-打开「系统 → 模型库」，点「＋ 新增模型」选择一个预设。
-
-- API 地址填写服务商的兼容接口根路径。程序会自己拼接 `/chat/completions`，不要把完整路径再写一遍。
-- 模型名称填写服务商接受的模型 ID。
-- API Key 留空表示保留已保存的密钥。
-
-预设只填入常见地址和模型名，以服务商控制台里的实际模型为准。发言决策和回复生成需要模型返回 JSON 对象。
-
-保存后点「测试此模型连接」。测试不携带群聊原文。更换地址、模型或密钥后需要重新测试。
-
-也可以先保持模拟模式，在「天性」里和 TA 试聊，确认 TA 说话的样子后再让 TA 参加真实 QQ。
-
-### 图片读取
-
-在模型档案里开启「图片理解」，并使用服务商支持视觉的模型。图片从 QQ 地址、本地缓存或图片缓存接口读取，默认接受不超过 32 MiB、8000 万像素的源图，不再把超过 4 MiB 的普通照片和截图直接拒绝。小图经过解码验证后保持原样；大截图先尝试无损压缩，必要时再压缩编码或按比例缩小，照片按方向信息转正，不裁切画面。提交模型的每张图片默认不超过 4 MiB，最长边不超过 8192 像素，像素总量不超过 1600 万；原图不被修改，重复图片仍按原内容识别。
-
-下载默认最多等待 30 秒，读取过程中断或图片损坏只影响该图片，不会阻止同一批其他正常图片。AVIF 会转换成通用格式；动态图本轮读取第一帧，不能据此判断完整动画。QQ 缓存接口返回大 Base64 图片不会再受到普通消息 1 MiB 限制，但普通消息仍保持原有上限。
-
-需要调整时，可在 `.env` 设置 `VISION_SOURCE_MAX_MB`（4–64，默认 32）、`VISION_MODEL_MAX_MB`（1–4，默认 4）和 `VISION_DOWNLOAD_TIMEOUT_SECONDS`（5–120，默认 30），重启生效。图片能否理解还取决于所选模型的视觉能力和服务商接口是否可用。
-
-## 5. 连接 QQ
-
-打开「系统 → 连接 QQ」，顶部有两个选项：**OneBot 11** 与 **QQ 官方机器人**，同一时间只使用一个。切换后会断开当前连接；原来方式下的会话仍可查看，但不能再向它们发送消息。两种方式的差别见 `docs/zh/connect.md`，下面是操作步骤。
-
-### 方式一：OneBot 11
-
-LuckyTri 只实现 OneBot 11 的反向 WebSocket 接口，接入端需要你自行准备和管理。
-
-1. 在本机 `.env` 中设置 `ONEBOT_TOKEN`，修改后重启 LuckyTri。
-2. 在接入端自己的网络设置里添加 OneBot 11 反向 WebSocket 客户端：
-
-| 项目          | 本机填写                            |
-| ------------- | ----------------------------------- |
-| 协议          | OneBot 11                           |
-| WebSocket URL | `ws://127.0.0.1:3210/onebot/v11/ws` |
-| Token         | `.env` 里的 `ONEBOT_TOKEN`          |
-| 消息格式      | 数组                                |
-| 启用          | 开启并保存                          |
-
-3. 在接入端完成 QQ 登录。小号需要已加入目标群；LuckyTri 不保存 QQ 密码。
-
-这里的 `3210` 是 LuckyTri 的端口。接入端和 LuckyTri 不在同一台机器或放在容器里时，`127.0.0.1` 指向各自环境，需要改成 LuckyTri 的实际地址，并先配置 `ADMIN_TOKEN`。
-
-### 方式二：QQ 官方机器人
-
-不需要登录 QQ 账号，也不需要额外的接入端，LuckyTri 自己连接 QQ 开放平台。
-
-1. 在 QQ 开放平台创建机器人，记下 **AppID** 与 **AppSecret**，并按平台要求开通群聊与单聊消息、把机器人加入要测试的群或添加为联系人。平台的入口和审核规则会调整，以开放平台当前说明为准。
-2. 在「系统 → 连接 QQ」选择「QQ 官方机器人」，填写 AppID 和 AppSecret，点击保存。也可以在 `.env` 里设置 `QQBOT_APP_ID` 与 `QQBOT_APP_SECRET`。AppSecret 保存后不会再显示。
-3. 状态显示「已连接」后，到群里 @ 她或私聊一句。想让她看到群里的全部消息，需要在开放平台开启「接收所有消息」；没有开启时她只能收到 @ 她的消息，连接页会提示这一点。
-4. 官方接口不提供群名，新会话会以编号显示，可以在「对话」里给会话改名。
-
-两种方式都是：已连接只表示传输通了。到目标群发一条消息后，会话会出现在「对话」的会话列表里，新发现的会话默认暂停参与。
-
-## 6. 让 TA 参与会话
-
-1. 在「系统 → 运行开关」确认允许参与聊天，关闭模拟模式并保存。「此刻」的状态条也能看到这两项。
-2. 在「对话」选中目标群，在右侧「这个会话」里点「开启参与」，或直接拨动列表里的开关。
-3. 在 QQ 里 @ 她，或直接叫 TA 的名字。
-4. 回到「对话」查看消息和「为什么这么说」。
-
-开不开口由 TA 自己决定，没有参与概率和冷却。被点名、私聊、引用 TA 或出现危机信号时，TA 一定会细看，然后选择回答、简短反应、说不想聊或不出声；理由显示在「对话」和「此刻 → 今天的 TA」。普通群消息只在 TA 在意时细看——刚聊过、有人问大家、聊到 TA 的兴趣、熟人在说话、攒了不少消息——其余只扫一眼，不调用模型，下次细看时一起读。觉得 TA 太安静，可以在「天性」里提高「主动」。
-
-TA 默认 02:00 睡、08:00 醒，在「天性 → 作息」里拖动月亮和太阳修改，或者关闭。睡着时被叫到，会等醒来再看；这时整个界面会变成夜晚。每分钟发言轮数限制仍然保留，用来避免短时间连续发言。
-
-在模型里打开「图片理解」后，私聊、@ 或引用里的图片会先由本机读取，再交给模型看画面。主模型不能看图时，在「对话 → 这个会话 → 会话设置」里另选一个打开了图片理解的视觉兼容模型。没有打开图片理解的模型不会收到画面。
-
-## 7. TA、记忆和知识
-
-「天性」是唯一由你编写的部分：名字、性格、兴趣、边界、底线和作息，每次保存为新的一版。拖动性格刻度时，旁边的光团会跟着变：温柔让颜色变暖、嘴角上扬，活泼让它跳得更快。
-
-其余的都从经历里长出来：TA 的自我是「内心」星图里的一颗颗星，TA 对每个人的感觉在「人际」，TA 在各群的样子在「人际」下方的群像里。点开可以看到每次变化的来源，觉得不对可以撤销；撤销过的内容之后不会被写回来。很久没被触及的线索会慢慢淡出，退到星图的「远方」；它们没有被删除，被聊到时会重新想起。TA 独处、写日记、夜里整理、回顾和改写自传的记录，以及 TA 在等的事（别人说的安排、TA 答应的事，可以撤销），都在「一生」。每日 Token 上限、后台份额、夜里整理和回顾间隔在「天性 → TA 的日子」里设置。
-
-「记忆」里先选择会话，也可以按人筛选。
-
-- TA 对所有会话只有一份记忆：别处知道的事只在相关时想起；私聊里知道的标为「私下知道」，不当众说；被要求保密的只在原来的会话里。可以在每条记忆上调整分寸、锁定或撤销。关于某个人的记忆也会出现在「人际」的人物详情里。
-- 群友说「记住，我……」会直接成为 TA 记得的事（密码、验证码之类不会记）。
-- 资料放进「资料书架」的集合后按当前会话的可见范围检索。群聊不会装入其他私聊集合。
-- 清空「对话」里的上下文不会删除长期记忆。
-
-## 8. 备份与停止
-
-```powershell
-npm run backup
-npm run stop
-npm start
-```
-
-备份写到 `data/backups/`。数据库里有聊天、记忆和保存在库中的密钥，按私密文件保管。`.env` 不在这份备份里。
-
-TA 的一切都存在这一个数据库里，所以服务运行时会自动备份：默认每 24 小时在另一个进程里做一份 `luckytri-auto-*.db`，只保留最近 7 份，做完会检查完整性。自动备份里有聊天、记忆、自我、日记和关系，但不带一天以前的模型调用记录（每条动辄几百 KB，会让备份大上十几倍），所以「为什么这么说」只能回看最近一天的。`npm run backup` 仍然是完整备份。可以在 `.env` 里调整：
-
-| 变量                    | 含义                         | 默认           |
-| ----------------------- | ---------------------------- | -------------- |
-| `BACKUP_INTERVAL_HOURS` | 自动备份间隔，`0` 关闭       | `24`           |
-| `BACKUP_KEEP`           | 保留几份自动备份             | `7`            |
-| `BACKUP_TRACE_DAYS`     | 备份里保留最近几天的调用记录 | `1`            |
-| `BACKUP_DIR`            | 备份目录                     | `data/backups` |
-
-想立刻做一份自动备份：`node scripts/backup.js --auto --force`。自动备份失败会记在启动窗口或 `data/launcher.log`，并隔越来越久才重试。备份和数据库放在同一块磁盘上，防不了磁盘损坏；重要的备份请自己复制到别处。
-
-设置 `DB_PATH` 使用另一份数据库时，若未指定 `BACKUP_DIR`，备份默认写到该数据库旁的 `backups` 目录，避免多个实例的副本混在一起。
-
-在「系统 → 数据与备份」可以查看每份历史数据库副本的大小，设置每天的整理时间、完整备份保留天数和最多份数，也可以逐份勾选后手动清理。默认每天服务器本地时间 04:30 检查，完整备份超过 14 天或多于 2 份就会列入整理；数量可设为 0，表示定时不保留完整备份。完整备份和迁移快照没有固定硬锁，可以手动选择全部清理。自动备份继续按上面的独立规则轮换，只轮换本实例有身份的副本，最新两份作为恢复点保留；无法确认身份的旧副本、迁移、旧版本和升级前快照仅手动清理。
-
-执行前必须留下本实例近 72 小时内校验通过的自动备份，最新一份损坏时会尝试另一份。新备份清单带有数据库身份，防止另一实例的副本冒充当前实例的恢复保障；旧清单仍可验证和恢复，但需要更新自动备份后才能作为清理保障。备份和清理共用目录锁，运行库、同一文件的硬链接与正在使用的副本不能清理。清理失败时会列出失败文件，并准确统计已释放空间。要长期保留的历史恢复点，请先连同 `.db.json` 清单复制到另一块磁盘。
-
-恢复时先停止服务，把当前 `data/friend.db` 及同名 `-wal`、`-shm` 移开，再把选中的备份复制为 `data/friend.db`。设置了 `DB_PATH` 时操作该路径。不要把旧的 WAL 文件和恢复后的数据库放在一起。更稳妥的做法是用 `npm run recovery` 校验并恢复到一个全新的文件，见 `docs/zh/recovery.md`。
-
-## 9. 常见问题
-
-| 现象                      | 先检查                                                                                             |
-| ------------------------- | -------------------------------------------------------------------------------------------------- |
-| 页面打不开                | Node 是否在运行，地址是否为 `127.0.0.1:3210`                                                       |
-| 端口已被占用              | 先 `npm run stop`，不要结束所有 node 进程                                                          |
-| 令牌错误                  | 使用 `ADMIN_TOKEN`；改 `.env` 后重启                                                               |
-| OneBot 未连接             | 接入端是否登录，URL、端口、路径和 `ONEBOT_TOKEN` 是否一致                                          |
-| 官方机器人未连接          | AppID 与 AppSecret 是否正确，机器人是否已开通群聊与单聊消息，网络能否访问 QQ 开放平台              |
-| 官方机器人只收到 @ 的消息 | 在开放平台开启「接收所有消息」；这是平台权限，不是 LuckyTri 的限制                                 |
-| 连接成功但没有会话        | 在 QQ 再发一条新消息；OneBot 方式下检查消息格式是否为数组                                          |
-| 群里不回复                | 全局开关、会话开关、模拟模式、密钥；「对话」里是「TA 扫了一眼」还是 TA 细看后选择了不出声          |
-| @ 了也不回                | TA 是否睡着了（「此刻」，界面是夜晚）、每分钟限速、今日 Token 是否用完、模型错误，或 TA 自己的理由 |
-| 模型 401 / 403            | 密钥和权限；环境变量密钥可能覆盖 LuckyTri 里保存的密钥                                             |
-| 模型 404                  | API 地址不要重复拼接 `/chat/completions`，核对模型 ID                                              |
-| 模型不返回 JSON           | 换支持 JSON 对象输出的模型，先做连接测试                                                           |
-| 记忆没有出现              | 是否是明确的「记住，我……」，是否被撤销，分寸是否为「要 TA 保密」而当前不在原来的会话               |
-| 界面动得太多              | 左下角「减少动画」；系统开启了减少动态效果时会自动关闭粒子和形变                                   |
-
-不要把 API 密钥、`.env` 或私聊原文发到公开位置。
+<p align="right"><b>中文</b> · <a href="../en/guide.md">English</a></p>
+
+# LuckyTri · 从零上手教程
+
+LuckyTri 在你的电脑上运行，通过 QQ 与人相遇。QQ 有两种连接方式，二选一：**OneBot 11**（自备接入端，反向 WebSocket）或 **QQ 官方机器人**（QQ 开放平台）。两种方式下她的记忆、心情和行为完全一致，区别只在消息怎么到达。模型 API 由你自行配置。
+
+界面右上角可以在「中文」与「English」之间切换，默认中文，选择会记在这个浏览器里。她自己说的话、写的日记和留下的念头不翻译，那是她自己的内容。
+
+## 1. 启动
+
+需要 Node.js 24.5 或更高版本。普通用户直接全局安装：
+
+```powershell
+node --version
+npm install -g luckytri
+luckytri
+```
+
+LuckyTri 在后台启动并打开 <http://127.0.0.1:3210>，首次运行自动生成配置。无需下载仓库或构建 WebUI。终端里的 SQLite 实验性提示不表示启动失败，以能否打开 LuckyTri 为准。
+
+首次进入管理台时设置一个密码即可。`luckytri --no-browser` 只后台启动，`luckytri start` 前台运行，`luckytri stop` 停止服务。更新使用 `luckytri stop` → `npm install -g luckytri@latest` → `luckytri`，密码、配置与数据会保留。
+
+从源码开发时，在仓库中执行 `npm install`、`npm run setup`、`npm run build`、`npm start`。下文的 `npm run setup/stop/backup/recovery/plugin` 面向源码用户；全局用户使用对应的 `luckytri setup/stop/backup/recovery/plugin`。
+
+Windows 日常使用可以双击 `启动LuckyTri.cmd`。服务已在运行时，它只打开 LuckyTri。关闭浏览器不会停止服务；停止时双击 `停止LuckyTri.cmd`，或在项目目录执行 `npm run stop`。这条命令只停止当前项目，不会结束其他 Node 进程。前台运行时也可以在该终端按 `Ctrl+C`。
+
+LuckyTri 是「TA 的小世界」，左侧导航分三组、十个入口：
+
+| 分组 | 入口 | 里面有什么                                                                                      |
+| ---- | ---- | ----------------------------------------------------------------------------------------------- |
+| TA   | 此刻 | TA 此刻的心情、正在做什么、最近说的话、放在心上和在等的事；今天的时间线、Token 用量和运行状态条 |
+| TA   | 内心 | 心灵星图（TA 的自我线索）、放在心上的便签、心情彩带                                             |
+| TA   | 人际 | 人物星系、每个人的详情、TA 在各群的样子                                                         |
+| TA   | 一生 | 日记本与那天的 TA、回顾、我的来路与章节、约定与期待、书架                                       |
+| 日常 | 时间 | TA 实际生活的记录：今日的活动、待办、作品库、持续项目、体验记录                                 |
+| 日常 | 对话 | 会话列表、实时聊天与「为什么这么说」、反馈、会话设置、模拟消息、回到那一刻（回放）              |
+| 日常 | 记忆 | TA 记得的事、资料书架                                                                           |
+| 设置 | 天性 | 名字与性格（旁边的光团实时预览）、作息、TA 的日子、每日 Token、高级指令、试聊                   |
+| 设置 | 系统 | 连接 QQ、模型库、运行开关                                                                       |
+| 设置 | 插件 | 启用、安装和卸下她接触世界的方式。见 [插件](plugins.md)                                         |
+
+界面的颜色、天空和动效跟着 TA 的心情与作息变化：开心时暖、低落时灰蓝、睡着后变成夜晚。左下角可以把主题固定成某一种，也可以「减少动画」。右下角的小 TA 戳一下会回应一句，按住是摸摸头，双击或点「聊聊」打开试聊；这些只是界面动画，不会改变 TA 的心智。手机上导航在底部，其余入口在「更多」里。
+
+## 2. 设置管理密码
+
+首次打开管理台时设置一个至少 8 个字符的密码，确认后进入。以后用同一个密码登录，不需要打开 `.env` 查找管理令牌。浏览器登录状态会保留；更新和重装不会重置密码。
+
+在「系统 → 运行开关」可以修改密码或退出登录。密码只以加盐校验摘要保存，现有环境配置和模型密钥保留。
+
+## 3. 先在模拟模式试聊
+
+默认开启模拟模式，消息不会发到 QQ。
+
+1. 打开「对话」，点会话列表上方的「＋ 添加会话」，填写测试群号和名称。
+2. 在中间的聊天里点「模拟消息」，以一位群友的身份输入一句普通消息并发送。
+3. 点 TA 回复下面的「为什么这么说」查看理由；「TA 扫了一眼」「TA 看了，没出声」会显示成聊天里的分隔条。
+
+没有模型密钥时，模拟回复使用本地样例，不调用模型。有密钥后，同一条路径会走真实发言流程，但仍然不发 QQ。模拟消息写进模拟会话，不会改变 TA 的心情、关系和记忆。
+
+「模拟消息」只在模拟模式下可用。右下角小 TA 的「聊聊」和「天性」右侧的试聊是另一回事：走真实链路，读取 TA 此刻的心智，天性页还可以带上没保存的草稿，但什么都不写入，也不发 QQ。
+
+## 4. 连接模型
+
+打开「系统 → 模型库」，点「＋ 新增模型」选择一个预设。
+
+- API 地址填写服务商的兼容接口根路径。程序会自己拼接 `/chat/completions`，不要把完整路径再写一遍。
+- 模型名称填写服务商接受的模型 ID。
+- API Key 留空表示保留已保存的密钥。
+
+预设只填入常见地址和模型名，以服务商控制台里的实际模型为准。发言决策和回复生成需要模型返回 JSON 对象。
+
+保存后点「测试此模型连接」。测试不携带群聊原文。更换地址、模型或密钥后需要重新测试。
+
+也可以先保持模拟模式，在「天性」里和 TA 试聊，确认 TA 说话的样子后再让 TA 参加真实 QQ。
+
+### 图片读取
+
+在模型档案里开启「图片理解」，并使用服务商支持视觉的模型。图片从 QQ 地址、本地缓存或图片缓存接口读取，默认接受不超过 32 MiB、8000 万像素的源图，不再把超过 4 MiB 的普通照片和截图直接拒绝。小图经过解码验证后保持原样；大截图先尝试无损压缩，必要时再压缩编码或按比例缩小，照片按方向信息转正，不裁切画面。提交模型的每张图片默认不超过 4 MiB，最长边不超过 8192 像素，像素总量不超过 1600 万；原图不被修改，重复图片仍按原内容识别。
+
+下载默认最多等待 30 秒，读取过程中断或图片损坏只影响该图片，不会阻止同一批其他正常图片。AVIF 会转换成通用格式；动态图本轮读取第一帧，不能据此判断完整动画。QQ 缓存接口返回大 Base64 图片不会再受到普通消息 1 MiB 限制，但普通消息仍保持原有上限。
+
+需要调整时，可在 `.env` 设置 `VISION_SOURCE_MAX_MB`（4–64，默认 32）、`VISION_MODEL_MAX_MB`（1–4，默认 4）和 `VISION_DOWNLOAD_TIMEOUT_SECONDS`（5–120，默认 30），重启生效。图片能否理解还取决于所选模型的视觉能力和服务商接口是否可用。
+
+## 5. 连接 QQ
+
+打开「系统 → 连接 QQ」，顶部有两个选项：**OneBot 11** 与 **QQ 官方机器人**，同一时间只使用一个。切换后会断开当前连接；原来方式下的会话仍可查看，但不能再向它们发送消息。两种方式的差别见 `docs/zh/connect.md`，下面是操作步骤。
+
+### 方式一：OneBot 11
+
+LuckyTri 只实现 OneBot 11 的反向 WebSocket 接口，接入端需要你自行准备和管理。
+
+1. 本机连接无需单独令牌，保留已有的接入地址和 QQ 登录。
+2. 在接入端自己的网络设置里添加 OneBot 11 反向 WebSocket 客户端：
+
+| 项目          | 本机填写                                           |
+| ------------- | -------------------------------------------------- |
+| 协议          | OneBot 11                                          |
+| WebSocket URL | `ws://127.0.0.1:3210/onebot/v11/ws`                |
+| Token         | 本机无需填写；远程可使用管理密码，旧远程令牌仍兼容 |
+| 消息格式      | 数组                                               |
+| 启用          | 开启并保存                                         |
+
+3. 在接入端完成 QQ 登录。小号需要已加入目标群；LuckyTri 不保存 QQ 密码。
+
+容器或另一台电脑中的 `127.0.0.1` 指向自身。远程接入使用 LuckyTri 的可达地址，并先在本机设置管理密码；对外提供管理台时使用 HTTPS。
+
+### 方式二：QQ 官方机器人
+
+不需要登录 QQ 账号，也不需要额外的接入端，LuckyTri 自己连接 QQ 开放平台。
+
+1. 在 QQ 开放平台创建机器人，记下 **AppID** 与 **AppSecret**，并按平台要求开通群聊与单聊消息、把机器人加入要测试的群或添加为联系人。平台的入口和审核规则会调整，以开放平台当前说明为准。
+2. 在「系统 → 连接 QQ」选择「QQ 官方机器人」，填写 AppID 和 AppSecret，点击保存。也可以在 `.env` 里设置 `QQBOT_APP_ID` 与 `QQBOT_APP_SECRET`。AppSecret 保存后不会再显示。
+3. 状态显示「已连接」后，到群里 @ 她或私聊一句。想让她看到群里的全部消息，需要在开放平台开启「接收所有消息」；没有开启时她只能收到 @ 她的消息，连接页会提示这一点。
+4. 官方接口不提供群名，新会话会以编号显示，可以在「对话」里给会话改名。
+
+两种方式都是：已连接只表示传输通了。到目标群发一条消息后，会话会出现在「对话」的会话列表里，新发现的会话默认暂停参与。
+
+## 6. 让 TA 参与会话
+
+1. 在「系统 → 运行开关」确认允许参与聊天，关闭模拟模式并保存。「此刻」的状态条也能看到这两项。
+2. 在「对话」选中目标群，在右侧「这个会话」里点「开启参与」，或直接拨动列表里的开关。
+3. 在 QQ 里 @ 她，或直接叫 TA 的名字。
+4. 回到「对话」查看消息和「为什么这么说」。
+
+开不开口由 TA 自己决定，没有参与概率和冷却。被点名、私聊、引用 TA 或出现危机信号时，TA 一定会细看，然后选择回答、简短反应、说不想聊或不出声；理由显示在「对话」和「此刻 → 今天的 TA」。普通群消息只在 TA 在意时细看——刚聊过、有人问大家、聊到 TA 的兴趣、熟人在说话、攒了不少消息——其余只扫一眼，不调用模型，下次细看时一起读。觉得 TA 太安静，可以在「天性」里提高「主动」。
+
+TA 默认 02:00 睡、08:00 醒，在「天性 → 作息」里拖动月亮和太阳修改，或者关闭。睡着时被叫到，会等醒来再看；这时整个界面会变成夜晚。每分钟发言轮数限制仍然保留，用来避免短时间连续发言。
+
+在模型里打开「图片理解」后，私聊、@ 或引用里的图片会先由本机读取，再交给模型看画面。主模型不能看图时，在「对话 → 这个会话 → 会话设置」里另选一个打开了图片理解的视觉兼容模型。没有打开图片理解的模型不会收到画面。
+
+## 7. TA、记忆和知识
+
+「天性」是唯一由你编写的部分：名字、性格、兴趣、边界、底线和作息，每次保存为新的一版。拖动性格刻度时，旁边的光团会跟着变：温柔让颜色变暖、嘴角上扬，活泼让它跳得更快。
+
+其余的都从经历里长出来：TA 的自我是「内心」星图里的一颗颗星，TA 对每个人的感觉在「人际」，TA 在各群的样子在「人际」下方的群像里。点开可以看到每次变化的来源，觉得不对可以撤销；撤销过的内容之后不会被写回来。很久没被触及的线索会慢慢淡出，退到星图的「远方」；它们没有被删除，被聊到时会重新想起。TA 独处、写日记、夜里整理、回顾和改写自传的记录，以及 TA 在等的事（别人说的安排、TA 答应的事，可以撤销），都在「一生」。每日 Token 上限、后台份额、夜里整理和回顾间隔在「天性 → TA 的日子」里设置。
+
+「记忆」里先选择会话，也可以按人筛选。
+
+- TA 对所有会话只有一份记忆：别处知道的事只在相关时想起；私聊里知道的标为「私下知道」，不当众说；被要求保密的只在原来的会话里。可以在每条记忆上调整分寸、锁定或撤销。关于某个人的记忆也会出现在「人际」的人物详情里。
+- 群友说「记住，我……」会直接成为 TA 记得的事（密码、验证码之类不会记）。
+- 资料放进「资料书架」的集合后按当前会话的可见范围检索。群聊不会装入其他私聊集合。
+- 清空「对话」里的上下文不会删除长期记忆。
+
+## 8. 备份与停止
+
+```powershell
+npm run backup
+npm run stop
+npm start
+```
+
+备份写到 `data/backups/`。数据库里有聊天、记忆和保存在库中的密钥，按私密文件保管。`.env` 不在这份备份里。
+
+TA 的一切都存在这一个数据库里，所以服务运行时会自动备份：默认每 24 小时在另一个进程里做一份 `luckytri-auto-*.db`，只保留最近 7 份，做完会检查完整性。自动备份里有聊天、记忆、自我、日记和关系，但不带一天以前的模型调用记录（每条动辄几百 KB，会让备份大上十几倍），所以「为什么这么说」只能回看最近一天的。`npm run backup` 仍然是完整备份。可以在 `.env` 里调整：
+
+| 变量                    | 含义                         | 默认           |
+| ----------------------- | ---------------------------- | -------------- |
+| `BACKUP_INTERVAL_HOURS` | 自动备份间隔，`0` 关闭       | `24`           |
+| `BACKUP_KEEP`           | 保留几份自动备份             | `7`            |
+| `BACKUP_TRACE_DAYS`     | 备份里保留最近几天的调用记录 | `1`            |
+| `BACKUP_DIR`            | 备份目录                     | `data/backups` |
+
+想立刻做一份自动备份：`node scripts/backup.js --auto --force`。自动备份失败会记在启动窗口或 `data/launcher.log`，并隔越来越久才重试。备份和数据库放在同一块磁盘上，防不了磁盘损坏；重要的备份请自己复制到别处。
+
+设置 `DB_PATH` 使用另一份数据库时，若未指定 `BACKUP_DIR`，备份默认写到该数据库旁的 `backups` 目录，避免多个实例的副本混在一起。
+
+在「系统 → 数据与备份」可以查看每份历史数据库副本的大小，设置每天的整理时间、完整备份保留天数和最多份数，也可以逐份勾选后手动清理。默认每天服务器本地时间 04:30 检查，完整备份超过 14 天或多于 2 份就会列入整理；数量可设为 0，表示定时不保留完整备份。完整备份和迁移快照没有固定硬锁，可以手动选择全部清理。自动备份继续按上面的独立规则轮换，只轮换本实例有身份的副本，最新两份作为恢复点保留；无法确认身份的旧副本、迁移、旧版本和升级前快照仅手动清理。
+
+执行前必须留下本实例近 72 小时内校验通过的自动备份，最新一份损坏时会尝试另一份。新备份清单带有数据库身份，防止另一实例的副本冒充当前实例的恢复保障；旧清单仍可验证和恢复，但需要更新自动备份后才能作为清理保障。备份和清理共用目录锁，运行库、同一文件的硬链接与正在使用的副本不能清理。清理失败时会列出失败文件，并准确统计已释放空间。要长期保留的历史恢复点，请先连同 `.db.json` 清单复制到另一块磁盘。
+
+恢复时先停止服务，把当前 `data/friend.db` 及同名 `-wal`、`-shm` 移开，再把选中的备份复制为 `data/friend.db`。设置了 `DB_PATH` 时操作该路径。不要把旧的 WAL 文件和恢复后的数据库放在一起。更稳妥的做法是用 `npm run recovery` 校验并恢复到一个全新的文件，见 `docs/zh/recovery.md`。
+
+## 9. 常见问题
+
+| 现象                      | 先检查                                                                                             |
+| ------------------------- | -------------------------------------------------------------------------------------------------- |
+| 页面打不开                | Node 是否在运行，地址是否为 `127.0.0.1:3210`                                                       |
+| 端口已被占用              | 先 `npm run stop`，不要结束所有 node 进程                                                          |
+| 密码错误                  | 使用首次设置的管理密码；可在系统运行开关中修改                                                     |
+| OneBot 未连接             | 确认接入端已登录、反向客户端启用、地址端口路径一致；本机无需额外令牌                               |
+| 官方机器人未连接          | AppID 与 AppSecret 是否正确，机器人是否已开通群聊与单聊消息，网络能否访问 QQ 开放平台              |
+| 官方机器人只收到 @ 的消息 | 在开放平台开启「接收所有消息」；这是平台权限，不是 LuckyTri 的限制                                 |
+| 连接成功但没有会话        | 在 QQ 再发一条新消息；OneBot 方式下检查消息格式是否为数组                                          |
+| 群里不回复                | 全局开关、会话开关、模拟模式、密钥；「对话」里是「TA 扫了一眼」还是 TA 细看后选择了不出声          |
+| @ 了也不回                | TA 是否睡着了（「此刻」，界面是夜晚）、每分钟限速、今日 Token 是否用完、模型错误，或 TA 自己的理由 |
+| 模型 401 / 403            | 密钥和权限；环境变量密钥可能覆盖 LuckyTri 里保存的密钥                                             |
+| 模型 404                  | API 地址不要重复拼接 `/chat/completions`，核对模型 ID                                              |
+| 模型不返回 JSON           | 换支持 JSON 对象输出的模型，先做连接测试                                                           |
+| 记忆没有出现              | 是否是明确的「记住，我……」，是否被撤销，分寸是否为「要 TA 保密」而当前不在原来的会话               |
+| 界面动得太多              | 左下角「减少动画」；系统开启了减少动态效果时会自动关闭粒子和形变                                   |
+
+不要把 API 密钥、`.env` 或私聊原文发到公开位置。

package/docs/zh/npm-release.md

@@ -1,33 +1,33 @@
-# npm 发布与维护
-
-发布复用 LuckyTri 当前 Git 仓库和 `package.json`，包名为 `luckytri`，版本继续由 `server/version.js` 从根 `package.json` 读取。
-
-## 结构与启动
-
-`server/` 是无需转译的 ESM 服务端，运行依赖为 Express、ws 和 sharp；SQLite 使用 Node.js 内置的 `node:sqlite`，最低 Node.js 24.5。`studio-web/` 使用 Vue 与 Vite，发布前构建到 `public/app/`。教程从中英文 `docs/*/guide.md` 生成到 `public/`。
-
-`bin/luckytri.js` 提供全局命令，分派到既有启动、停止、备份、恢复与插件脚本。`scripts/runtime.js` 复用 `scripts/setup.js` 的随机令牌初始化，并保留已有配置。`server/paths.js` 将包内资源与实例数据分开；源码默认继续使用仓库的 `.env` 和 `data/`，npm 安装默认使用独立用户目录。相对数据库和备份路径以实例目录为基准，后台进程和自动备份子进程继承相同的绝对路径。服务身份以实例目录确认，更新程序安装位置后仍能定位原实例。
-
-数据库、心智、聊天、界面配置继续使用原 SQLite 存储与迁移；知识文件、插件安装与插件数据、日志和备份都在实例目录中。启动锁保留到服务退出，阻止重复打开同一实例。Windows、macOS、Linux 分别使用系统浏览器打开方式；无桌面环境可使用 `--no-browser`。
-
-## 包内容边界
-
-`package.json.files` 白名单只包含 CLI、服务端、运行脚本、构建后的 WebUI、教程、插件桥接资源、内置天气插件、SDK 和公开文档。`.npmignore` 再排除敏感及本地文件。安装和卸载没有应用生命周期脚本，普通用户无需前端构建工具。
-
-`npm run pack:check` 使用 npm 实际生成的最终文件清单，先检查路径，再检查经过批准的源码内容，拒绝配置、秘密文件、数据库、聊天、日志、备份、开发文件和意外新增文件。它还校验 CLI shebang、关键资源、WebUI 资源引用及源代码中的常见秘密格式。不要使用 `--ignore-scripts` 从未经验证的源码直接发布。
-
-## 发布流程
-
-维护者需要开发依赖和 Playwright 浏览器。Windows 默认使用已安装的 Edge；Linux/macOS 可用 `npx playwright install chromium` 安装测试浏览器。
-
-```bash
-npm ci
-npm run release:check
-npm publish
-```
-
-`release:check` 构建完整资源、运行全部后端与 WebUI 测试、检查实际包并验证全局安装。`prepublishOnly` 自动执行构建、后端测试和实际包安装测试；`prepack` 自动构建并检查最终包内容。发新版本前同时更新 `package.json` 与 lockfile，并更新版本记录；已发布的版本不可覆盖。
-
-包测试使用临时 npm 全局前缀和模拟数据，检查含空格、中文的任意调用目录、WebUI 浏览器加载、内置插件、数据库备份及恢复检查，再安装测试版本并卸载重装，确认配置、记忆、关系、聊天、知识文件、日志、备份和插件数据保留。测试版本只存在于本机临时压缩包，不发布。测试清单和经过验证的正式压缩包输出到被 Git 忽略的 `workspace/npm-release/`。完成检查后也可直接发布该目录中的正式 `.tgz`，保证上传的是已经检查和安装过的同一份包。
-
-首次发布需要 npm 注册与登录。发布命令使用 npm 自己的登录流程，不读取或输出登录凭据文件；如果 npm 要求二次验证，由账号本人完成认证后继续发布。
+# npm 发布与维护
+
+发布复用 LuckyTri 当前 Git 仓库和 `package.json`，包名为 `luckytri`，版本继续由 `server/version.js` 从根 `package.json` 读取。
+
+## 结构与启动
+
+`server/` 是无需转译的 ESM 服务端，运行依赖为 Express、ws 和 sharp；SQLite 使用 Node.js 内置的 `node:sqlite`，最低 Node.js 24.5。`studio-web/` 使用 Vue 与 Vite，发布前构建到 `public/app/`。教程从中英文 `docs/*/guide.md` 生成到 `public/`。
+
+`bin/luckytri.js` 提供全局命令，分派到既有启动、停止、备份、恢复与插件脚本。`scripts/runtime.js` 复用 `scripts/setup.js` 的本机环境初始化与管理台首次密码设置，并保留已有配置。`server/paths.js` 将包内资源与实例数据分开；源码默认继续使用仓库的 `.env` 和 `data/`，npm 安装默认使用独立用户目录。相对数据库和备份路径以实例目录为基准，后台进程和自动备份子进程继承相同的绝对路径。服务身份以实例目录确认，更新程序安装位置后仍能定位原实例。
+
+数据库、心智、聊天、界面配置继续使用原 SQLite 存储与迁移；知识文件、插件安装与插件数据、日志和备份都在实例目录中。启动锁保留到服务退出，阻止重复打开同一实例。Windows、macOS、Linux 分别使用系统浏览器打开方式；无桌面环境可使用 `--no-browser`。
+
+## 包内容边界
+
+`package.json.files` 白名单只包含 CLI、服务端、运行脚本、构建后的 WebUI、教程、插件桥接资源、内置天气插件、SDK 和公开文档。`.npmignore` 再排除敏感及本地文件。安装和卸载没有应用生命周期脚本，普通用户无需前端构建工具。
+
+`npm run pack:check` 使用 npm 实际生成的最终文件清单，先检查路径，再检查经过批准的源码内容，拒绝配置、秘密文件、数据库、聊天、日志、备份、开发文件和意外新增文件。它还校验 CLI shebang、关键资源、WebUI 资源引用及源代码中的常见秘密格式。不要使用 `--ignore-scripts` 从未经验证的源码直接发布。
+
+## 发布流程
+
+维护者需要开发依赖和 Playwright 浏览器。Windows 默认使用已安装的 Edge；Linux/macOS 可用 `npx playwright install chromium` 安装测试浏览器。
+
+```bash
+npm ci
+npm run release:check
+npm publish
+```
+
+`release:check` 构建完整资源、运行全部后端与 WebUI 测试、检查实际包并验证全局安装。`prepublishOnly` 自动执行构建、后端测试和实际包安装测试；`prepack` 自动构建并检查最终包内容。发新版本前同时更新 `package.json` 与 lockfile，并更新版本记录；已发布的版本不可覆盖。
+
+包测试使用临时 npm 全局前缀和模拟数据，检查含空格、中文的任意调用目录、WebUI 浏览器加载、内置插件、数据库备份及恢复检查，再安装测试版本并卸载重装，确认配置、记忆、关系、聊天、知识文件、日志、备份和插件数据保留。测试版本只存在于本机临时压缩包，不发布。测试清单和经过验证的正式压缩包输出到被 Git 忽略的 `workspace/npm-release/`。完成检查后也可直接发布该目录中的正式 `.tgz`，保证上传的是已经检查和安装过的同一份包。
+
+首次发布需要 npm 注册与登录。发布命令使用 npm 自己的登录流程，不读取或输出登录凭据文件；如果 npm 要求二次验证，由账号本人完成认证后继续发布。