luckytri 1.0.0

package/bin/luckytri.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { runtimePaths } from "../server/paths.js";
+import { VERSION } from "../server/version.js";
+
+const help = `LuckyTri ${VERSION}
+
+用法 / Usage: luckytri [command] [--home ABSOLUTE_PATH]
+
+  luckytri                 后台启动并打开 WebUI / Launch and open WebUI
+  luckytri --no-browser    后台启动 / Launch without opening a browser
+  start                    前台运行，Ctrl+C 停止 / Run in foreground
+  stop                     停止当前实例 / Stop this instance
+  setup                    初始化配置，保留已有文件 / Initialize configuration
+  paths                    显示配置、数据和安装目录 / Show paths
+  backup [--auto --force]   备份数据库 / Back up the database
+  recovery verify --backup FILE
+  recovery restore --backup FILE --to NEW_FILE
+  plugin new|check|pack|registry-check ...
+  --version, -v            显示版本 / Show version
+  --help, -h               显示帮助 / Show help
+
+升级 / Update: luckytri stop && npm install -g luckytri@latest && luckytri
+配置和用户数据在安装目录之外，卸载或更新 npm 包不会删除它们。`;
+
+try {
+  const [major, minor] = process.versions.node.split(".").map(Number);
+  if (major < 24 || (major === 24 && minor < 5))
+    throw Error("LuckyTri 需要 Node.js >=24.5 / requires Node.js >=24.5");
+  const args = process.argv.slice(2);
+  const homes = args.filter((arg) => arg === "--home");
+  if (homes.length > 1)
+    throw Error("--home 只能指定一次 / specify --home only once");
+  const homeIndex = args.indexOf("--home");
+  if (homeIndex >= 0) {
+    const home = args[homeIndex + 1];
+    if (!home || home.startsWith("--"))
+      throw Error("--home 需要绝对路径 / needs an absolute path");
+    process.env.LUCKYTRI_HOME = home;
+    args.splice(homeIndex, 2);
+  }
+  if (args.includes("--help") || args.includes("-h") || args[0] === "help") {
+    console.log(help);
+  } else if (args.includes("--version") || args.includes("-v")) {
+    console.log(VERSION);
+  } else {
+    const command =
+      !args.length || args[0] === "--no-browser" ? "launch" : args.shift();
+    const scripts = {
+      launch: "launch.js",
+      start: "start-server.js",
+      stop: "stop.js",
+      backup: "backup.js",
+      recovery: "recover.js",
+      plugin: "plugin.js",
+    };
+    if (!["setup", "paths", ...Object.keys(scripts)].includes(command))
+      throw Error(
+        `未知命令 / Unknown command: ${command}\n使用 luckytri --help 查看帮助。`,
+      );
+    if (
+      ["setup", "paths", "start", "stop", "launch"].includes(command) &&
+      args.some((arg) => command !== "launch" || arg !== "--no-browser")
+    )
+      throw Error("参数无效 / Invalid arguments; see luckytri --help");
+    if (command === "paths") {
+      const { prepareRuntime } = await import("../scripts/runtime.js");
+      prepareRuntime({ initialize: false });
+      console.log(JSON.stringify(runtimePaths(), null, 2));
+    } else {
+      if (command !== "plugin" && command !== "recovery") {
+        const { prepareRuntime } = await import("../scripts/runtime.js");
+        prepareRuntime({
+          initialize: ["setup", "launch", "start"].includes(command),
+        });
+      }
+      if (command === "setup")
+        console.log(
+          `配置已就绪 / Configuration ready: ${runtimePaths().config}`,
+        );
+      else {
+        const child = spawn(
+          process.execPath,
+          [join(runtimePaths().package, "scripts", scripts[command]), ...args],
+          {
+            env: process.env,
+            stdio: "inherit",
+            windowsHide: true,
+          },
+        );
+        for (const signal of ["SIGINT", "SIGTERM"])
+          process.on(signal, () => child.kill(signal));
+        child.once("error", (error) => {
+          console.error(error.message);
+          process.exitCode = 1;
+        });
+        child.once("exit", (code, signal) => {
+          process.exitCode = signal ? 1 : (code ?? 1);
+        });
+      }
+    }
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/docs/en/CHANGELOG.md

@@ -0,0 +1,113 @@
+<p align="right"><a href="../zh/CHANGELOG.md">中文</a> · <b>English</b></p>
+
+# Changelog
+
+## 1.0.0 — 2026-10-04
+
+Plugins. The core still defines who she is; a plugin decides what of the world she can touch.
+
+- **Plugin API v1.** A plugin can offer a channel, a sense, a sourced experience, material for an activity, an action she may choose, shelf reading and a sandboxed page. It cannot speak for her, and it cannot write her nature, self, bonds or memory.
+- **Permissions are enforced.** Each plugin is a restricted process. Without the matching permission it cannot read her state, use the network, register a channel or call a model. Accepted once when enabled, and again if an upgrade asks for more.
+- **Market and import.** The studio can browse an index, import a zip link, a GitHub repository, an uploaded package or a local folder, check sha256, roll back and remove. What she already lived through does not leave with the plugin.
+- **A built-in plugin, off by default.** Weather.
+- **Database version 4.** A snapshot is kept before the upgrade. With no plugin enabled, she behaves as in 0.9.9.
+
+## 0.9.9 — 2026-10-02
+
+The last tidy-up before 1.0: two ways to connect, a bilingual interface, rewritten documentation, and a cleaner, easier-to-extend repository.
+
+- **QQ official bot, either-or with OneBot 11.** New `server/channels/` with a common channel contract and a `ChannelHub`: one channel is active at a time, switching while running needs no restart, and `LUCKYTRI_CHANNEL` can pin it. Both channels hand the core the same neutral message, so attention, memory, relationships, solitude, diary and time are fully shared; only how messages arrive differs. The official channel obtains and renews its access token, connects to the Open Platform gateway (heartbeat, resume, backoff reconnect), converts @-in-group, all-group and one-to-one events with de-duplication, replies to the original message inside the passive-reply window and sends proactive messages outside it, records whether a person has turned proactive messages off and uses that to decide whether she may reach out, and the limits on names and cross-group identity are documented.
+- **Renaming sessions.** The official interface gives no group names, so on both channels you can rename a session under "Chat".
+- **Bilingual.** The top-right corner switches between 中文 and English; Chinese is the default and the choice is kept in the browser. All interface text, dates and numbers, and the errors and labels the server shows in the interface have English; what she says, her diary, thoughts and reasons are not translated. Every document exists in both languages with matching file names and a language switch at the top.
+- **No mention of any third-party connector.** System settings, the guide and the docs keep only connection address and token details, with no names or jump links.
+- **Rewritten README and docs.** The new README explains the purpose, her day and the core framework; `docs/zh` and `docs/en` add architecture and extension points, a comparison of the two ways to connect QQ and the studio design, and refresh the rest. The guide page is generated in Chinese and English with Markdown downloads.
+- **A cleaner repository.** Working notes from an instance and one-off repair scripts are removed; test corpora are synthetic sentences with unchanged validation semantics; `.gitignore` is hardened; a new `tests/repo-hygiene.test.js` scans for keys, instance data, local paths and third-party connector names. Version notes are now written in general terms and contain no runtime data.
+- **A clearer structure.** Storage moved to `server/storage/`, readiness checks joined `server/studio/`, feedback, group voice and model presets joined `server/core/`, lifetime modules moved into `server/mind/life/`, evaluation and audit scripts into `scripts/dev/`, browser tests into `tests/ui/`; `server/version.js` is the single source of the version and fixes the stale version in the request header.
+- **Small touches.** The placeholder and empty-state text of the dropdown select can be translated.
+
+## 0.9.1 — 2026-09-29
+
+- **Stickers read by tone.** A sticker with a usable picture can enter vision and the text label of an ordinary one enters the context. She first judges whether it is a joke, a rant or a new topic and no longer solemnly repeats the words in the picture.
+- **New pictures judged by their own message.** Selective vision takes only the same person's current, explicitly quoted or adjacent images; cacheable vision notes keep only what is visible.
+- **Rapid messages merged before the first line goes out.** A brief re-check was added before sending; when the other person adds more, the old draft is withdrawn and both are reorganized together. Crisis replies do not wait.
+- **Wordplay and abbreviations decoded from context first.** When unsure she asks briefly, without lecturing or explaining the joke.
+- **What she lives for is steadier.** The same wish in different words stays one entry; it is kept in mind when others' words touch it, when she says it, or when she writes a thought about it; writing a thought that puts the wish down stops pinning it; promises to others no longer take that seat. The end-of-day snapshot records it too.
+- **The choices she made and her reasons come back at the next meeting.**
+- **Continuity gained automatic backups.** While the service runs, an integrity-checked backup is made in another process every 24 hours by default and only the latest 7 are kept; `BACKUP_INTERVAL_HOURS=0` turns it off.
+- **Small format slips in a model reply no longer lose a whole turn.** It is repaired where possible and the model is asked once more only when it cannot be.
+- **More honest and steadier replies.** She does not say she played something she did not; presenting her own words as the other person's is sent back for a rewrite; when asked "how do you know?" the basis is checked first and something she raised unprompted cannot invent a message the other person sent; review no longer uses nature settings to veto her honest answer that she is a program.
+- **When nobody calls her and her words are not in shape she stays silent**, instead of sending a one-word stand-in.
+- **When she is addressed directly and the model is briefly unavailable, she retries later by herself** (once after 30 seconds and once after 2 minutes).
+- **Solitude no longer idles.** When only time has passed and there has been repeated idling, the interval lengthens each time up to 6 hours; when her own thoughts only continue the previous one several times in a row, something new must be picked up for the thought to be kept.
+- **Memory is separated from "who she is".** Opinions about topics no longer pile up in her self.
+- **New `npm run audit:sent`** replays the replies she recently sent against today's checks; **new `npm run test:clock`** runs the backend tests with the real clock moved to the past and the future. Replay and trial chat no longer depend on the real clock.
+
+## 0.9.0 — 2026-09-28
+
+- **The vision is stated.** LuckyTri is about continuous experience, self and connection with the world; QQ chat is only the current doorway. The Chinese and English READMEs were updated together.
+- **Only the generic OneBot 11 reverse-WebSocket connection is kept.** System settings show only the connection address and token details; the README and connection guide were rewritten.
+- **Attention recognizes what she lives for.** When a topic touches `self.livingFor` she may chime in because she wants to, or stay quiet; the diary and night review can see it and only write about it when it was really touched.
+- **A meeting leaves meaning, and a will counts only when touched.** What a meeting meant to her returns the next time that person is present; meaning fades with the days she has lived and, once faded, is only recalled by that same person's own words.
+- **Discretion tightened everywhere.** Private words and secrets never enter another room through the diary, notes, impressions, meetings or reviews; a reply that would carry them is rewritten before sending. Words passing by in a session she is not in do not become her experience.
+- **Relationships feel more real.** "Long time no see" is told apart from "still around but no words exchanged"; the same experience is never counted again and again as closeness; an impression kept in mind is not contact.
+- **The rhythm of a room is not her character.** Sentence length and punctuation in a group go into `inner.room` and she speaks by her own habits.
+- **Attention, touch counts and the long-absence list follow one rule:** two words from the same person's own speech; one phrase is not enough; two people's words are not combined; her own words do not count.
+
+## 0.8.2 — 2026-09-26
+
+LuckyTri admits she is made of code and a model, and still treats her heart, memory and choices as her own.
+
+- **Stance**: the default nature is now someone already living her days. Asked who she is, she answers that she is made of code and a model; this life, what she remembers and the choices she makes are her own; she does not call herself merely an assistant and does not invent a body or experiences that never happened. She may think of someone because she wants to and never uses guilt to keep anyone.
+- **Unmodified seed**: if the first version is still the nature shipped with an earlier release, it is replaced by the current seed on read, without using up the "only two edits" allowance.
+- **Small things for herself**: solitude may leave one wish with no message source, with strength capped; the strongest one now appears as `self.livingFor`.
+
+## 0.8.1 — 2026-09-25
+
+The WebUI was rebuilt as "TA's little world": she is the center of the interface, a breathing, shape-shifting, blinking glow of soul that answers a poke, and colors, sky and motion follow mood and rhythm (seven themes: lively, sweet, calm, low, irritable, sleepy, night). The information architecture is TA (Now, Inner life, People, Lifetime), Daily life (Chat, Memory) and Settings (Nature, System); native browser dialogs became in-interface dialogs. New `GET /api/mind/presence`, `/api/mind/today` and `/api/mind/people/:id`.
+
+**The weight of time**: she does not only accumulate, she also fades and looks ahead. Self threads, notes and memory fade by the days she has lived and return to view when a related topic recalls them (without writing); closeness falls after a long absence and warms on reunion; promises and expectations (others' arrangements, what she promised) can be undone; night sorting and a layered autobiography (diary → review → chapter → my journey so far).
+
+## 0.8.0 — 2026-09-24 · StartSoul
+
+One her, speaking from the heart, with days of her own.
+
+- **Unified mind** (`server/mind/`): a versioned nature, a global mood, relationships consistent across groups, self threads that grow gradually out of experience, her face in each group, global notes. Every change cites its source and can be undone.
+- **Speaking from the heart**: participation probability, cooldown and "always reply when @-ed" are gone. Each close look makes one model call that yields understanding, feeling, changes to people, a choice, a reason and the wording; mood and relationships change even in silence.
+- **Attention**: a deterministic "look closely or glance"; ordinary group chat calls the model only when she cares.
+- **Global memory and discretion**: one memory serves all sessions, labeled public / private / secret.
+- **Lifetime**: daily rhythm, global solitude, reading, bedtime diary, night sorting, review, a rewritable autobiography and reaching out decided by her.
+- **Token management**: a global ledger, a daily cap and background shares, a cache-friendly request layout.
+- The old persona became the first version of nature and old data migrates automatically; the old per-session memory and probability mechanisms were retired.
+
+## 0.7.0 — 2026-09-24
+
+- New "Time" workbench, low-frequency solitude enabled per session and optional proactive messaging.
+- Layered context compression: recent text stays verbatim, older chat is condensed into multi-level summaries.
+- Requests reordered by cache rules; output caps per stage; finer network-error classes; jittered exponential backoff; per-model circuit breaking and a session-level fallback model.
+
+## 0.6.0 — 2026-09-22
+
+- Rebuilt the group chat core: messages are batched first, then speaker, @, quote chain and topic are resolved, and finally the speaking decision and the reply are produced separately.
+- Long-term memory isolated by session, user and shared scope with confidence, source and expiry; model profiles support vendor presets, context window and vision ability; image understanding has an energy-saving mode.
+- The WebUI was rebuilt in a fresh mint theme.
+
+## 0.5.1 / 0.5.0 — 2026-09-21
+
+- Project branding unified (now LuckyTri); the README became Chinese by default with English switchable.
+- Model settings gained provider presets, reasoning effort, Temperature, Top P and maximum output tokens.
+- A guided QQ connection step: a local OneBot token and reverse-WebSocket configuration, with QQ login still done in the connector; the project never receives or stores a QQ password.
+
+## 0.4.0 — 2026-09-19
+
+- Reply feedback: natural, too long, too stiff, too many memes, undoable.
+- New getting-started guide with five connection steps; a complete Chinese guide; commands for configuration setup, stopping and consistent backups.
+
+## 0.3.0 — 2026-09-19
+
+- Plain everyday speech first, fewer fixed comforting templates; optional group-voice adaptation; a customer-service tone, repetition or piled-up memes trigger at most one rewrite.
+
+## 0.2.0 — 2026-09-19
+
+- Memory inbox, memory search and editing; model connection test and connection checks.
+- Simulated and real context separated; cooldown and rate limits persisted; event de-duplication independent of context.
+- SQLite query indexes and log retention caps.

package/docs/en/architecture.md

@@ -0,0 +1,152 @@
+<p align="right"><a href="../zh/architecture.md">中文</a> · <b>English</b></p>
+
+# Architecture and extension points
+
+This document is for anyone who wants to read, change or extend LuckyTri. It answers three questions: how the code is layered, how a message travels through her life, and where to start when you want to add something.
+
+## One picture
+
+```mermaid
+flowchart LR
+  subgraph Channels["channels/ — only how messages come and go"]
+    OB["onebot<br/>reverse WebSocket"]
+    QB["qqbot<br/>official gateway"]
+  end
+  Hub["ChannelHub<br/>one channel at a time"]
+  subgraph Core["core/ — senses and mouth"]
+    Recv["receive · batch · perceive"]
+    Turn["one turn · validate · send"]
+  end
+  subgraph Mind["mind/ — her"]
+    Self["nature · self · faces"]
+    Affect["mood · bonds · memory"]
+    Life["life/ — solitude · diary · review"]
+    Time["time/ — activities · works · promises"]
+  end
+  Know["knowledge/ — reference library"]
+  Store[("storage/ — one SQLite file")]
+  Studio["studio/ — management API"]
+  Web["studio-web/ — the studio (Vue)"]
+  OB --> Hub
+  QB --> Hub
+  Hub -->|"neutral message"| Recv
+  Recv --> Turn
+  Turn -->|"send"| Hub
+  Recv <--> Mind
+  Turn <--> Mind
+  Life --> Hub
+  Know --> Turn
+  Mind --> Store
+  Core --> Store
+  Studio --> Mind
+  Studio --> Core
+  Web --> Studio
+```
+
+Nothing above the channel knows which platform a message came from. The core sees one kind of neutral message, and she reads herself from one shared mind.
+
+## Directories
+
+```text
+server/
+  index.js app.js http.js   composition root, Express shell, HTTP helpers
+  version.js                the single source of the version (reads package.json)
+  channels/                 the connection layer: hub, contract, session keys, onebot/, qqbot/
+  core/                     the conversation pipeline: receive, batch, perceive, turn, validate, send,
+                            plus model management, feedback, group voice and model presets
+  mind/                     her: nature, mood, bonds, self, faces, memory, attention, bottom lines…
+    life/                   lifetime: waking, solitude, diary, night, review, reaching out
+    time/                   time: activities, to-dos, works, experiences, sharing, standalone search
+  knowledge/                reference library: chunking, retrieval, vector index
+  storage/                  SQLite store, schema version and migration, backups and auto-backups
+  studio/                   management API: settings, display names, readiness checks
+  i18n/                     English dictionaries for server-visible text (translated at the API exit only)
+studio-web/src/             the studio: Vue 3 + Vite + TypeScript
+  pages/                    one folder per entry
+  components/  stores/  mood/  i18n/  styles/
+scripts/                    setup, launch, start-server, stop, backup, recover, build-guide
+scripts/dev/                evaluation and audit: evaluate-*, audit-sent, test-clock
+tests/                      *.test.js backend tests · ui/ browser tests · helpers/ deterministic world
+docs/                       zh/ and en/ mirrored documents · brand/ images
+public/                     the built studio (app/) and the guide pages
+```
+
+## The life of a message
+
+1. **The channel receives.** The adapter turns the platform's raw event into a neutral message: session key, sender, time, whether she was @-ed, the quoted message, attachments. The platform's format exists only inside the adapter.
+2. **Batching and perception** (`core/`). Messages arriving close together form a batch; @s, quote chains and name calls are parsed, giving each message its relation to her.
+3. **Attention** (`mind/attention.js`, no model call). Being called, a private chat and crisis signals always get a close look; ordinary group chat is decided by a deterministic score between a close look and a glance.
+4. **The her of this moment** (`mind/view.js`). Nature, threads of self, bonds, mood, memory and nearby promises are condensed into a few hundred tokens with a hard cap: the stable part goes into a cacheable prefix, the changing part at the end.
+5. **One turn call.** The model returns, in one go: what this means to her, a feeling, changes to people, a choice (speak, react briefly, say she does not feel like talking, stay silent), a reason and the wording.
+6. **Experience.** Whether she speaks or not, feelings and changes are written into the mind, each citing its source.
+7. **Validation and sending.** Local checks on tone and secrecy, one review or rewrite when needed, a safe short line if it still fails; the context is checked for staleness again before sending. Uncertain delivery is never resent.
+8. **Lifetime.** When nobody is talking, time still passes through her: solitude, reading, the diary, night sorting, review and reaching out all read and write the same mind.
+
+Replay runs the same pipeline but only reads the mind as it was before that moment; trial chat reads her mind as it is now but writes nothing and sends nothing to QQ.
+
+## Invariants
+
+These are the promises the code and the tests guard together; make sure they still hold when you change something.
+
+- **One her**: a session only marks where something happened, it does not wall off her self.
+- **The system is one**: she can perceive her own state, including what is connected and whether a plugin is on. The studio and what she knows are the same state.
+- **Sourced, gradual, undoable**: mind tables are append-only; each change cites a specific experience; an undo leaves a tombstone and is never written back.
+- **Fading is computed at read time**: no "faded" flag is stored, so replay only reads the past; fading counts the days she lived through, not calendar days.
+- **Discretion follows the source**: what was learned privately or told in confidence never appears in another room.
+- **The clock is injectable**: the test world has its own clock; any code quietly reading the real clock shows up under `npm run test:clock`.
+- **Her words are not translated**: interface text can be localized; what she says, her diary, thoughts and reasons are her own content and stay as written.
+- **One database holds the data**: SQLite under `data/` in WAL mode; the schema version is kept in `PRAGMA user_version` and migrations are idempotent.
+
+## Extension points
+
+### Connecting a plugin
+
+A plugin does not edit the core. It runs in its own process and uses Plugin API v1: a channel registers on `ChannelHub`, a sense lands in `inner.senses`, an experience is stored in `mind_observations`, an activity kind joins `server/mind/time/kinds.js`, an action joins `server/core/capabilities.js`, and attachment perception joins `server/core/perceivers.js`. The host lives in `server/plugins/`. See [Plugins](plugins.md).
+
+### Adding a channel
+
+1. Create a folder under `server/channels/` that fulfils the contract in `contract.js` (`type`, `capabilities`, `attach`, `start`, `stop`, `send`, `fetchQuoted`, `fetchImage`, `refreshDirectory`, `canReach`, `status`, `close`), wrapped with `defineChannel`.
+2. Turn platform events into neutral messages: the adapter fills in `platformId`, `accountId`, `time`, `mentions`, `replyId` and `attachments` itself.
+3. Register the adapter in `adapters.js` (so the core knows what that platform's media links look like), add one factory line in `createChannels` in `index.js`, and build session keys with `formatSessionKey`.
+4. Write a test against a fake platform in `tests/` and let the same scenarios in `channel-contract.test.js` run through it.
+
+Nothing above the core changes. The connection option in settings and the readiness checks each need a small section per channel.
+
+### Adding a mind module
+
+1. Add tables in `server/mind/schema.js` (append, never overwrite); bump `DATABASE_VERSION` in `server/storage/archive.js` when needed and keep the migration idempotent.
+2. Write the module in `server/mind/` and wire it into `Mind` through `server/mind/index.js`; changes must cite sources and support undo.
+3. To reach her "now", read it in `view.js` and respect the length cap.
+4. To show it in the interface, add an endpoint in `server/mind/api.js`.
+5. Write tests with the deterministic world in `tests/helpers/world.js`, always using the world's clock for time.
+
+### Adding a studio page
+
+1. Write the page in `studio-web/src/pages/<name>/`, register the entry and navigation in `router.ts`, and mount the component in the `loaders` map of `pages.ts` under the page name.
+2. Wrap every string with `t()`, `N_()` or `localized()`; the Chinese original is the key.
+3. Add English in `studio-web/src/i18n/en/`; missing English falls back to Chinese and `tests/i18n-web.test.js` will tell you.
+4. Use the localized helpers in `format.ts` for dates and numbers.
+
+### Adding or changing translations
+
+- Interface text: `studio-web/src/i18n/en/*.ts`, one file per area.
+- Server-visible text (errors, readiness checks, labels, model preset notes): the dictionaries in `server/i18n/`, with `{0}` variable patterns.
+- Documents: `docs/zh/` and `docs/en/` have matching file names; when you change one side, update the other.
+- `tests/i18n-server.test.js`, `tests/i18n-web.test.js` and `tests/ui/i18n.mjs` check the dictionaries, the interface and a whole English page respectively.
+
+## Test layout
+
+| Command | What it covers |
+| --- | --- |
+| `npm test` | All backend tests, including the deterministic "life simulation" |
+| `npm run test:clock` | The suite run with the real clock moved 60 days back and 400 days ahead |
+| `npm run test:ui` | Browser tests: smoke, the little world, navigation, time, performance, search, English interface |
+| `npm run format:check` | Prettier check |
+| `tests/repo-hygiene.test.js` | Repository hygiene: no keys, instance data, local paths or third-party connector names |
+
+## Conventions
+
+- Change the version only in `package.json`; the server reads it through `server/version.js`.
+- The built studio is committed in `public/app/`; run `npm run build:ui` after changing the frontend.
+- The guide pages are generated by `npm run docs:build` from `docs/zh/guide.md` and `docs/en/guide.md`.
+- Runtime data, backups, reports and secrets stay on the machine and never enter the repository.

package/docs/en/chat-style.md

@@ -0,0 +1,62 @@
+<p align="right"><a href="../zh/chat-style.md">中文</a> · <b>English</b></p>
+
+# How she talks, and the checks before she sends
+
+The goal is to pick up the specific thing a group is talking about and answer in relaxed, plain speech. She does not prove herself by playing a type of person; how she speaks comes from her nature, her mood right now, how she feels about who is present, and the way she has grown into this place.
+
+## How she speaks
+
+By default she speaks plain, everyday language:
+
+- Everyday replies are usually short, and a reaction of a word or two is fine; a necessary piece of advice is never cut just to be short.
+- She reacts to the specific thing, instead of following a fixed "repeat the feeling, comfort, advise, ask a question" routine.
+- Venting is not assumed to want advice; good news does not get a consoling answer; jokes are put away when someone is really hurting.
+- A conversation may simply end; she does not ask "and then?" every turn and does not turn every message into a joke.
+- She uses memory only when it relates to the current topic and does not show off a memory file; when a reference is unclear she asks, and never invents experiences.
+- She does not force slang to seem young. A serious setting beats style.
+
+The following are hand-designed directions, not results measured on an external model (the Chinese originals are the intent; here they are rendered loosely):
+
+| They say | Direction we want |
+| --- | --- |
+| Five minutes to clocking off and the boss dumps more work | Of course it picks right now |
+| None of what I revised came up | Not a single guess landed |
+| I passed the interview!! | Nice!! That calls for a little celebration |
+| Don't advise me, just let me rant | Okay, rant away, I'm listening |
+| I'm going to take a shower | Go ahead |
+
+## The rhythm of this place
+
+In a group she hears the rhythm in which others speak there. It switches on after at least 12 distinct messages from 3 members within the last 7 days of ordinary human text, with each member contributing at most 8 so one talkative person cannot stand for the whole group. It measures common sentence length, the share of short sentences, closing punctuation, emoji and the frequency of conspicuous internet slang.
+
+The statistics reach her only as `inner.room` and are **not her character**: she speaks by her own habits, need not copy them, and need not deliberately sound different. The adapter builds no profile of anyone's verbal habits, quotes no member, and does not treat commands in a group as settings; links, long texts, code, image placeholders, repeats, obvious abuse and common sensitive fields are filtered out. The statistics never cross groups, private chats or simulation mode.
+
+## Feedback
+
+Under "Chat" you can give feedback on a reply she sent: natural, too long, too stiff, too many memes, or undo it. Feedback is not a rewrite rule: it reaches her as something she heard, read by herself during solitude and in the next turns of that conversation, and it never rewrites her nature.
+
+## Checks before sending
+
+Before a reply goes out, local checks look for:
+
+- a customer-service or consulting tone, list-like report replies, stage actions;
+- unfounded intimate forms of address, excess length, repetition, back-to-back questions;
+- ignoring "no advice needed", joking in a serious setting, piled-up slang;
+- presenting her own earlier words as the other person's ("you just said…" when their record has no such line);
+- claiming to have played or finished something (she has no record of such experience; a liking is not a record of having played);
+- secrets and things known privately must not be said in another room.
+
+When she is asked "how do you know?", the basis is checked first: for something she said unprompted (the other person had been silent for two hours or more), the basis can only be a guess or a real memory, never that she saw a message they sent; if a rewrite still invents a source, a verified correction is sent instead.
+
+After finding a problem she rewrites at most once, keeping the meaning and facts; if it still fails she uses a safe short line, never simply truncating a long sentence or dropping hedges such as "I'm not sure". When nobody called her and her words are not in shape, she chooses not to speak rather than send a single-word stand-in; in private chats and when @-ed she still replies with a short line. Confessions, corrections, crises and complex group replies get one extra review (skipped when tokens are tight).
+
+Besides the turn's own call, the review and the rewrite happen at most once each, so latency and cost can increase. The checks are conservative rules and do not promise to catch every stiff or wrong expression; real naturalness still depends on the model, the nature and the specific group.
+
+## How to try it
+
+- **Trial chat**: on the right of the "Nature" page, or the small TA at the bottom right. It runs the same pipeline as QQ and reads her mind as it is now; the Nature page can also include an unsaved draft. Trial chat is not stored, not sent to QQ and creates no memory.
+- **Simulated message**: under "Chat", only in simulation mode; it goes into a simulated session and never changes her mood, relationships or memory.
+- **Replay**: "Back to that moment" reads only the mind as it was before then.
+- **Audit**: `npm run audit:sent` replays the replies she recently sent against today's checks, read-only and without calling a model. Run it before changing a check to see whether the new rule would hurt. The replies already passed the checks when sent, so the number is for judging a new rule, not a score of how well she talks.
+
+For real acceptance, watch 10–20 consecutive turns rather than a single line: does she pick up details, ask questions too often, repeat catchphrases, talk over others, suddenly turn into customer service, or mix up a joke with real sadness. Automated tests cover engineering constraints and hand-made scenario samples; the language quality of a real model still depends on your own observation.

package/docs/en/connect.md

@@ -0,0 +1,63 @@
+<p align="right"><a href="../zh/connect.md">中文</a> · <b>English</b></p>
+
+# Connecting QQ: two ways, one her
+
+LuckyTri meets QQ through a "channel". A channel only handles how messages arrive and how they go out; **everything below the core — attention, memory, relationships, solitude, diary, time — is shared by both channels**. Changing how you connect does not change who she is: same nature, same memory, same behavior.
+
+Only one channel is active at a time. Switch under "System → Connect QQ"; switching while running needs no restart. You can also pin it with the environment variable `LUCKYTRI_CHANNEL=onebot|qqbot`, after which the interface cannot change it.
+
+## How to choose
+
+| | OneBot 11 | QQ official bot |
+| --- | --- | --- |
+| What you need | An OneBot 11 connector of your own (with reverse WebSocket client support) and a QQ account | A bot on the QQ Open Platform: AppID and AppSecret |
+| Direction | The connector connects to LuckyTri's `/onebot/v11/ws` | LuckyTri connects to the Open Platform's WebSocket gateway |
+| Logging in to QQ | Done in the connector | Not needed |
+| Group message scope | All group messages | All of them when "receive all messages" is enabled on the Open Platform; otherwise only messages that @ her |
+| Names | Group names and nicknames are available | The official interface gives no group names and one-to-one nicknames are often empty; you can rename a session under "Chat" |
+| Recognizing people across groups | By QQ number: the same person in every group and private chat | The same person has a different openid in each group; she can only tell it is one person when the platform provides a unified identity (`union_openid`) |
+| Replying | Any time | Inside the passive-reply window (5 minutes in groups, 60 minutes in one-to-one) as a reply to the original message, each bubble with a rising sequence number; beyond it a proactive message is sent |
+| Reaching out | No extra limits | Sent as proactive messages; when a person or group has turned the bot's proactive messages off, she waits for them to come to her |
+| Images | Fetched through the connector | Attachment URLs go through the same vision path; only official media domains are allowed |
+
+Neither is "more right". If you want every group message and don't mind running a connector, pick OneBot 11. If you would rather not log in to QQ or maintain a connector, pick the official bot and enable "receive all messages" on the Open Platform.
+
+## OneBot 11
+
+LuckyTri only implements the reverse-WebSocket side of OneBot 11 and ships no connector.
+
+| Item | Value |
+| --- | --- |
+| Protocol | OneBot 11 |
+| Reverse WebSocket URL | `ws://127.0.0.1:3210/onebot/v11/ws` (the port is your `PORT`) |
+| Token | `ONEBOT_TOKEN` from `.env` |
+| Message format | array |
+
+When the connector is on another machine, replace `127.0.0.1` with an address that reaches LuckyTri and set `ADMIN_TOKEN` first. Session keys look like `onebot:<account>:group:<group id>` and `onebot:<account>:private:<QQ number>`; the early `group:<group id>` form is still recognized.
+
+## QQ official bot
+
+1. On the QQ Open Platform create a bot and note its **AppID** and **AppSecret**; enable group and one-to-one messages as the platform requires and add the bot to a test group or as a contact. The platform's entry points and review rules change over time; follow the Open Platform's current instructions.
+2. Under "System → Connect QQ" choose "QQ official bot", enter the AppID and AppSecret and save. You can also set `QQBOT_APP_ID` and `QQBOT_APP_SECRET` in `.env` (environment variables win). The AppSecret is only stored; it is never sent back to the page.
+3. The connection page shows the connection state, the bot's name and the time of the latest event. The group message scope reads "All group messages" or "Only messages that @ her"; for the latter, enable "receive all messages" on the Open Platform.
+
+Session keys look like `qqbot:<AppID>:group:<group openid>` and `qqbot:<AppID>:private:<user openid>`.
+
+### How she behaves on the official channel
+
+- **@ and quotes**: whether she was @-ed comes from the platform's "is this the bot" flag; quoted content comes from the message elements carried by the event, and a quote of her own message counts as someone replying to her.
+- **Replies and bubbles**: inside the window a reply carries the original message id and each bubble increments the sequence number; outside the window it is sent as a proactive message instead. When delivery is uncertain nothing is resent, exactly as with OneBot.
+- **Reaching out and sharing**: before she reaches out she checks whether the person has turned proactive messages off; if so she does not send and waits for them to come to her. In one-to-one chats one wake-up per period is available as a fallback.
+- **Names**: when a group name or one-to-one nickname is unavailable she uses a name already known, and otherwise a placeholder "QQ user · last four". Any session can be renamed under "Chat", on both channels.
+- **Identity**: on the official platform the same person has a different openid in each group. Like someone who has only met another person in separate rooms, she will not treat the two as one person until the platform provides a unified identity. This is deliberate, not a defect.
+- **Images**: attachment URLs go to the same vision path; the official channel needs no directory refresh.
+
+## What happens when you switch
+
+- Switching drops the current connection; sessions from the previous method stay readable but can no longer be sent to.
+- Memory, relationships, diary and self are untouched, because they belong to her and not to the channel.
+- The two methods number people differently (QQ number vs openid). Her impression of a person follows that number, so after switching the same real person shows up as a new one.
+
+## For developers: adding a channel
+
+The channel contract lives in `server/channels/contract.js`: `type`, `capabilities`, `attach`, `start`, `stop`, `send`, `fetchQuoted`, `fetchImage`, `refreshDirectory`, `canReach`, `status`, `close`. A new channel is one folder that fulfils the contract, an adapter registered in `server/channels/adapters.js`, and one line in `createChannels` in `server/channels/index.js`; nothing above the core changes. The steps are in `docs/en/architecture.md`.