luckytri 1.0.0

package/public/plugin-kit/v1/bridge.js

@@ -0,0 +1,30 @@
+// The only way a plugin page, sealed in its sandbox, may speak to LuckyTri.
+// It cannot see the admin token. The studio page makes the request for it,
+// and only to this plugin's own routes.
+(function () {
+  const pending = new Map();
+  window.luckytri = {
+    request(method, path, body) {
+      const id = Math.random().toString(36).slice(2);
+      return new Promise((resolve, reject) => {
+        pending.set(id, { resolve, reject });
+        parent.postMessage(
+          { luckytri: 1, id, method, path, body },
+          location.origin,
+        );
+      });
+    },
+  };
+  window.addEventListener("message", (event) => {
+    if (event.origin !== location.origin) return;
+    const data = event.data || {};
+    if (data.luckytri === "theme" && data.css) {
+      document.documentElement.setAttribute("style", data.css);
+      return;
+    }
+    const wait = pending.get(data.id);
+    if (!wait) return;
+    pending.delete(data.id);
+    data.ok ? wait.resolve(data.result) : wait.reject(new Error(data.error || "failed"));
+  });
+})();

package/public/plugin-kit/v1/kit.css

@@ -0,0 +1,14 @@
+:root {
+  color: var(--ink, #2a241f);
+  background: transparent;
+  font-family: var(--font-ui, "Segoe UI", sans-serif);
+}
+body {
+  margin: 0;
+}
+button,
+input,
+textarea,
+select {
+  font: inherit;
+}

package/public/tutorial.en.md

@@ -0,0 +1,214 @@
+# LuckyTri · Getting Started
+
+LuckyTri runs on your own computer and meets people through QQ. QQ has two ways to connect, and you pick one: **OneBot 11** (you bring a connector, reverse WebSocket) or the **QQ official bot** (QQ Open Platform). With either, her memory, mood and behavior are exactly the same; only the way messages arrive differs. You configure the model API yourself.
+
+The top-right corner of the interface switches between "中文" and "English". Chinese is the default and your choice is remembered in this browser. What she says, writes in her diary and keeps as her own thoughts is never translated; that is her own content.
+
+## 1. Start
+
+You need Node.js 24.5 or newer. Install globally:
+
+```powershell
+node --version
+npm install -g luckytri
+luckytri
+```
+
+LuckyTri starts in the background and opens <http://127.0.0.1:3210>, creating local configuration on the first run. The package includes the built WebUI. The experimental-SQLite notice does not mean the start failed.
+
+Use `luckytri paths` to find `.env`, open it in a local editor and enter `ADMIN_TOKEN` in the studio. `luckytri --no-browser` launches without opening a browser, `luckytri start` runs in the foreground, and `luckytri stop` stops the service. Update with `luckytri stop`, `npm install -g luckytri@latest`, then `luckytri`. Your configuration and data stay intact. Default directories are listed in the [README](../../README.en.md#configuration-data-and-privacy).
+
+For source development, run `npm install`, `npm run setup`, `npm run build` and `npm start` in the checkout. Later examples using `npm run setup/stop/backup/recovery/plugin` apply to source checkouts; global users use the corresponding `luckytri setup/stop/backup/recovery/plugin` commands.
+
+On Windows you can double-click `启动LuckyTri.cmd` for daily use. If the service is already running, it only opens LuckyTri. Closing the browser does not stop the service; to stop it double-click `停止LuckyTri.cmd` or run `npm run stop` in the project folder. That command stops this project only and leaves other Node processes alone. When running in the foreground you can also press `Ctrl+C` in that terminal.
+
+LuckyTri is "TA's little world". The left navigation has three groups and ten entries:
+
+| Group      | Entry      | What is inside                                                                                                                                                  |
+| ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| TA         | Now        | TA's mood right now, what she is doing, what she said lately, what is on her mind and what she is waiting for; today's timeline, token usage and the status bar |
+| TA         | Inner life | The star map (TA's threads of self), notes she keeps in mind, the mood ribbon                                                                                   |
+| TA         | People     | The people galaxy, each person's detail page, how TA is in each group                                                                                           |
+| TA         | Lifetime   | The diary and TA on that day, reviews, "my road so far" and chapters, promises and anticipation, the bookshelf                                                  |
+| Daily life | Time       | The record of TA's actual life: today's activity, to-dos, works library, ongoing projects, experiences                                                          |
+| Daily life | Chat       | Session list, live chat and "why she said this", feedback, session settings, simulated messages, back to that moment (replay)                                   |
+| Daily life | Memory     | What TA remembers, the bookshelf                                                                                                                                |
+| Settings   | Nature     | Name and character (the glow beside it previews live), daily rhythm, TA's days, daily tokens, advanced prompts, trial chat                                      |
+| Settings   | System     | Connect QQ, model library, run switches                                                                                                                         |
+| Settings   | Plugins    | Enable, install and remove the ways she touches the world. See [Plugins](plugins.md)                                                                            |
+
+The colors, sky and motion follow TA's mood and rhythm: warm when she is happy, grey-blue when she is low, night once she is asleep. At the bottom left you can pin one theme or turn on "Reduce motion". The small TA at the bottom right answers a poke, a long press is a head-pat, and a double click or "Chat" opens the trial chat. These are interface animations only and never change her mind. On a phone the navigation sits at the bottom and the other entries are under "More".
+
+## 2. Local tokens
+
+Configuration is created on first launch. You can also initialize in advance:
+
+```powershell
+luckytri setup
+luckytri paths
+```
+
+When there is no `.env`, setup writes an admin token and an OneBot connection token. An existing `.env` is kept as it is.
+
+```dotenv
+HOST=127.0.0.1
+PORT=3210
+ADMIN_TOKEN=
+ONEBOT_TOKEN=
+LLM_API_KEY=
+```
+
+| Field                               | Purpose                                                                                                |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `ADMIN_TOKEN`                       | Opens LuckyTri and calls the HTTP API; the stop command uses it too                                    |
+| `ONEBOT_TOKEN`                      | The OneBot 11 connector uses it for `/onebot/v11/ws` (only needed for OneBot)                          |
+| `LLM_API_KEY`                       | Optional; when set it takes precedence over the model key saved in LuckyTri                            |
+| `LUCKYTRI_CHANNEL`                  | Optional; `onebot` or `qqbot`. When set, the connection method cannot be changed in the interface      |
+| `QQBOT_APP_ID` / `QQBOT_APP_SECRET` | Optional; credentials of the QQ official bot, they take precedence over what is saved in the interface |
+| `HOST` / `PORT`                     | Listen address and port; keep the defaults for local use                                               |
+
+The first time the page loads data it asks for `ADMIN_TOKEN`. The token stays in the current tab only. Restart after changing `.env`. Never give `ADMIN_TOKEN` to the QQ connector, and do not treat `ONEBOT_TOKEN` as the studio password.
+
+## 3. Try it in simulation mode first
+
+Simulation mode is on by default, so nothing is sent to QQ.
+
+1. Open "Chat", click "+ Add session" above the session list and enter a test group number and name.
+2. In the chat in the middle click "Simulated message", type an ordinary line as one of the group members and send it.
+3. Click "Why she said that" under TA's reply to see the reason. "TA glanced over it" and "TA looked but stayed quiet" show up as dividers in the chat.
+
+Without a model key, simulated replies use local samples and call no model. Once there is a key, the same path runs the real speaking flow, still without sending to QQ. Simulated messages go into a simulated session and never change TA's mood, relationships or memory.
+
+"Simulated message" is only available in simulation mode. The "Chat" of the small TA and the trial chat to the right of "Nature" are different: they go through the real pipeline and read TA's mind as it is now, and the Nature page can even include an unsaved draft, but nothing is written and nothing is sent to QQ.
+
+## 4. Connect a model
+
+Open "System → Model library", click "+ Add model" and choose a preset.
+
+- For the API address enter the root of the provider's compatible endpoint. The program appends `/chat/completions` itself; do not write the full path again.
+- For the model name enter a model ID the provider accepts.
+- Leaving the API key empty keeps the saved key.
+
+A preset only fills in a common address and model name; the real models are whatever your provider's console shows. Speaking decisions and replies need the model to return a JSON object.
+
+After saving, click "Test this model's connection". The test carries no group chat text. Test again after changing the address, model or key.
+
+You can also stay in simulation mode and trial-chat with TA under "Nature" to see how she speaks before letting her join real QQ.
+
+### Reading images
+
+Enable "Image understanding" in the model profile and use a model whose provider supports vision. Images can be read from QQ URLs, local cache files or the image-cache API. Originals up to 32 MiB and 80 million pixels are accepted by default, so ordinary photos and screenshots larger than 4 MiB are no longer rejected outright. Small images retain their bytes after decoding validation. Large screenshots first try lossless compression, then encoding compression or proportional resizing as needed. Photos are oriented correctly without cropping. Each image sent to the model defaults to at most 4 MiB, 8192 pixels on its longest side and 16 million output pixels. Originals stay unchanged and duplicate detection uses their original contents.
+
+Downloads have a 30-second timeout by default. An interrupted or damaged image fails independently of other images in the batch. AVIF is converted to a common format; animated images contribute their first frame, which does not establish the full animation. Large Base64 images returned by QQ's image-cache API no longer fall under the ordinary 1 MiB message limit; ordinary messages keep that limit.
+
+To adjust this, set `VISION_SOURCE_MAX_MB` (4–64, default 32), `VISION_MODEL_MAX_MB` (1–4, default 4) or `VISION_DOWNLOAD_TIMEOUT_SECONDS` (5–120, default 30) in `.env`, then restart. Interpretation still depends on the selected model's visual abilities and an available provider endpoint.
+
+## 5. Connect QQ
+
+Open "System → Connect QQ". There are two options at the top: **OneBot 11** and **QQ official bot**, and only one is used at a time. Switching drops the current connection; sessions from the previous method stay readable but can no longer be sent to. See `docs/en/connect.md` for how the two compare; the steps are below.
+
+### Option one: OneBot 11
+
+LuckyTri only implements the reverse-WebSocket side of OneBot 11. You prepare and manage the connector yourself.
+
+1. Set `ONEBOT_TOKEN` in the local `.env` and restart LuckyTri.
+2. In the connector's own network settings add an OneBot 11 reverse WebSocket client:
+
+| Item           | Value on this machine               |
+| -------------- | ----------------------------------- |
+| Protocol       | OneBot 11                           |
+| WebSocket URL  | `ws://127.0.0.1:3210/onebot/v11/ws` |
+| Token          | `ONEBOT_TOKEN` from `.env`          |
+| Message format | array                               |
+| Enabled        | on, then save                       |
+
+3. Log in to QQ in the connector. The account must already be in the target group; LuckyTri does not store QQ passwords.
+
+`3210` is LuckyTri's port. When the connector and LuckyTri are on different machines or in containers, `127.0.0.1` points at each own environment: replace it with LuckyTri's real address and configure `ADMIN_TOKEN` first.
+
+### Option two: QQ official bot
+
+No QQ account login and no extra connector are needed; LuckyTri connects to the QQ Open Platform by itself.
+
+1. On the QQ Open Platform create a bot, note its **AppID** and **AppSecret**, enable group and one-to-one messages as the platform requires, and add the bot to the group you test with or as a contact. The platform's entry points and review rules change over time; follow the Open Platform's current instructions.
+2. In "System → Connect QQ" choose "QQ official bot", fill in the AppID and AppSecret and save. You can also set `QQBOT_APP_ID` and `QQBOT_APP_SECRET` in `.env`. The AppSecret is never shown again after saving.
+3. When the status reads "Connected", @ her in the group or message her privately. For her to see every group message, enable "receive all messages" on the Open Platform; without it she only receives messages that @ her, and the connection page says so.
+4. The official interface gives no group names, so new sessions are shown by number. You can rename a session under "Chat".
+
+With both options, connected only means the transport works. After a message arrives from the target group, the session appears in the session list under "Chat"; newly discovered sessions are paused by default.
+
+## 6. Let TA join a session
+
+1. In "System → Run switches" confirm chatting is allowed, turn simulation mode off and save. The status bar under "Now" shows both.
+2. In "Chat" select the target group and click "Resume" under "This session" on the right, or flip the switch in the list.
+3. In QQ @ her, or just call TA by name.
+4. Go back to "Chat" to read the messages and "Why she said that".
+
+Whether she speaks is TA's own decision; there is no participation probability and no cooldown. When she is addressed by name, in a private chat, quoted, or a crisis signal appears, TA always looks closely and then chooses to answer, react briefly, say she does not feel like talking, or stay silent; the reason is shown under "Chat" and "Now → TA today". Ordinary group messages get a close look only when TA cares: she was just talking, someone asks everyone, the topic touches her interests, someone familiar is speaking, a lot of messages piled up. Otherwise she only glances, calls no model, and reads them together at the next close look. If she seems too quiet, raise "Proactive" under "Nature".
+
+TA sleeps at 02:00 and wakes at 08:00 by default. Drag the moon and the sun under "Nature → Daily rhythm" to change this, or turn it off. If she is called while asleep she looks once she wakes, and the whole interface turns to night. The per-minute limit on speaking turns stays, to prevent bursts of consecutive replies.
+
+Once "Image understanding" is on for a model, images in private chats, @ messages or quotes are read locally first and then shown to the model. When the main model cannot see images, pick another vision-capable model with image understanding on under "Chat → This session → Session settings". A model without image understanding never receives the picture.
+
+## 7. TA, memory and knowledge
+
+"Nature" is the only part you write: name, character, interests, boundaries, bottom lines and daily rhythm, saved as a new version each time. As you drag a character dial, the glow beside it follows: gentleness warms the color and lifts the corners of the mouth, liveliness makes it bounce faster.
+
+Everything else grows from experience: TA's self is the stars of the "Inner life" star map, her feeling for each person is under "People", and how she is in each group is in the group faces below "People". Open any of them to see where each change came from and undo what feels wrong; what was undone is never written back. Threads that have not been touched for a long time slowly fade into the "far away" of the map; they are not deleted and come back when talked about. The record of her time alone, her diary, night sorting, reviews and autobiography rewrites, together with what she is waiting for (arrangements others mentioned, things she promised; they can be undone), are all under "Lifetime". Daily token cap, background share, night sorting and the review interval are set under "Nature → TA's days".
+
+In "Memory" pick a session first; you can also filter by person.
+
+- TA has one memory across all sessions: what was learned elsewhere is only recalled when relevant; what was learned in a private chat is marked "known privately" and not said in public; what was asked to be kept secret stays in the original session. You can adjust discretion, lock or undo each memory. Memories about a person also appear on that person's detail page under "People".
+- When a group member says "remember, I…", it goes straight into what TA remembers (passwords, verification codes and the like are not remembered).
+- Reference material placed in a collection on the "Bookshelf" is searched within what the current session may see. Group chats never load other private chats' collections.
+- Clearing the context in "Chat" does not delete long-term memory.
+
+## 8. Backup and stop
+
+```powershell
+npm run backup
+npm run stop
+npm start
+```
+
+Backups go to `data/backups/`. The database holds chats, memories and any keys saved in it, so keep it like a private file. `.env` is not part of this backup.
+
+Everything of TA lives in this one database, so the service backs it up automatically while running: by default every 24 hours, in another process, it writes a `luckytri-auto-*.db`, keeps only the latest 7 and checks integrity afterwards. An automatic backup holds chats, memories, self, diary and relationships, but not model call records older than a day (each can be hundreds of KB and would make the backup more than ten times bigger), so "Why she said that" can only be looked back on for the last day. `npm run backup` is still the full backup. Adjust in `.env`:
+
+| Variable                | Meaning                                                | Default        |
+| ----------------------- | ------------------------------------------------------ | -------------- |
+| `BACKUP_INTERVAL_HOURS` | Interval between automatic backups, `0` turns them off | `24`           |
+| `BACKUP_KEEP`           | How many automatic backups to keep                     | `7`            |
+| `BACKUP_TRACE_DAYS`     | Days of call records kept inside a backup              | `1`            |
+| `BACKUP_DIR`            | Backup folder                                          | `data/backups` |
+
+To take an automatic backup right now: `node scripts/backup.js --auto --force`. A failed automatic backup is noted in the launcher window or `data/launcher.log` and retried after longer and longer pauses. A backup on the same disk as the database cannot survive disk failure; copy important backups elsewhere yourself.
+
+When `DB_PATH` points to a different database and `BACKUP_DIR` is unset, backups go into a `backups` folder beside that database, keeping separate instances apart.
+
+Under System → Data and backups, inspect each historical copy, set a daily cleanup time, maximum age and maximum count for full backups, or select individual copies for removal. By default, a daily check at 04:30 server local time selects full backups older than 14 days or beyond the newest two. Set the count to 0 to retain no full backups. Full and migration snapshots are no longer permanently locked and can all be selected manually. Automatic backups rotate only identifiable copies belonging to this instance, with the newest two reserved as restore points. Unidentifiable older copies, migration, older-version and pre-upgrade snapshots are removed only through manual selection.
+
+Cleanup verifies a retained automatic backup of this instance from the last 72 hours. If the newest copy is damaged, another one is tried. New manifests include a database identity so a different instance cannot provide the recovery guarantee. Older manifests can still be verified and restored, but a refreshed automatic backup is needed before they can guarantee cleanup. Backup and cleanup share a folder lock; the live database, hard links to it and copies with runtime sidecars cannot be removed. Partial failures list the remaining files and accurately report the space already freed. Copy historical restore points worth keeping to another disk together with their `.db.json` manifests first.
+
+To restore, stop the service, move the current `data/friend.db` and its `-wal` and `-shm` files away, then copy the chosen backup to `data/friend.db`. When `DB_PATH` is set, work on that path. Never keep an old WAL file next to a restored database. The safer way is `npm run recovery`, which verifies a backup and restores it into a brand new file; see `docs/en/recovery.md`.
+
+## 9. Troubleshooting
+
+| Symptom                           | Check first                                                                                                                              |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| The page does not open            | Is Node running, and is the address `127.0.0.1:3210`                                                                                     |
+| Port already in use               | Run `npm run stop` first; do not kill every node process                                                                                 |
+| Wrong token                       | Use `ADMIN_TOKEN`; restart after editing `.env`                                                                                          |
+| OneBot not connected              | Is the connector logged in; do the URL, port, path and `ONEBOT_TOKEN` all match                                                          |
+| Official bot not connected        | Are the AppID and AppSecret right, are group and one-to-one messages enabled for the bot, can the network reach the QQ Open Platform     |
+| Official bot only gets @ messages | Enable "receive all messages" on the Open Platform; this is a platform permission, not a LuckyTri limit                                  |
+| Connected but no sessions         | Send one more new message in QQ; with OneBot also check the message format is array                                                      |
+| No reply in a group               | Global switch, session switch, simulation mode, key; under "Chat", was it "TA glanced over it" or did TA look closely and choose silence |
+| No reply even when @-ed           | Is TA asleep (see "Now", the interface is night), the per-minute limit, today's tokens used up, a model error, or TA's own reason        |
+| Model 401 / 403                   | Key and permissions; an environment-variable key may override the one saved in LuckyTri                                                  |
+| Model 404                         | Do not append `/chat/completions` twice to the API address; check the model ID                                                           |
+| Model returns no JSON             | Use a model that supports JSON object output and run the connection test first                                                           |
+| Memory did not appear             | Was it an explicit "remember, I…", was it undone, is its discretion "keep secret" and you are not in the original session                |
+| Too much motion                   | "Reduce motion" at the bottom left; when the system asks for reduced motion, particles and morphing switch off automatically             |
+
+Never post API keys, `.env` or private chat text anywhere public.

package/public/tutorial.md

@@ -0,0 +1,214 @@
+# 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` 或私聊原文发到公开位置。