luckytri 1.0.0 → 1.0.2

package/.github/SECURITY.md

@@ -24,11 +24,11 @@ LuckyTri 默认只监听本机。页面、聊天记录、记忆和模型密钥
 
 ## 插件
 
-插件跑在单独的进程里，默认读不到数据库、密钥和仓库，也不能自己联网。启用前会列出它要的权限。`net.raw` 和公开地址是高风险的，只交给你信任的插件。插件页面在沙箱里打开，碰不到管理令牌。不要把不受信任的插件包放进仓库。
+插件跑在单独的进程里，默认读不到数据库、密钥和仓库，也不能自己联网。启用前会列出它要的权限。`net.raw` 和公开地址是高风险的，只交给你信任的插件。插件页面在沙箱里打开，无法读取 HttpOnly 登录 Cookie。不要把不受信任的插件包放进仓库。
 
 ## 对外访问
 
-监听 `127.0.0.1`、`localhost` 或 `::1` 以外的地址时，必须设置 `ADMIN_TOKEN`，否则进程拒绝启动。OneBot WebSocket 使用单独的 `ONEBOT_TOKEN`；QQ 官方机器人的 AppSecret 只会被保存，不会再回显给页面。不要在公开 Issue 里粘贴密钥、令牌、聊天记录或数据库文件。
+监听外网地址前必须先在本机设置管理密码；远程管理台应使用 HTTPS。管理密码以加盐 scrypt 摘要保存，登录会话通过 HttpOnly、SameSite=Strict Cookie 管理，登录失败限流。OneBot 本机连接无需单独令牌，并拒绝浏览器跨站连接；远程连接可用同一管理密码，旧令牌仍兼容。不要公开密钥、登录状态、聊天或数据库。
 
 ## 报告问题
 
@@ -60,11 +60,11 @@ Deleting the current file does not clear history that was already pushed.
 
 ## Plugins
 
-A plugin runs in its own process. By default it cannot read the database, keys or the repository, and it cannot open the network by itself. The permissions it wants are listed before it is enabled. `net.raw` and a public address are high risk; give them only to a plugin you trust. A plugin page opens in a sandbox and cannot see the admin token. Do not commit an untrusted plugin package.
+A plugin runs in its own process. By default it cannot read the database, keys or the repository, and it cannot open the network by itself. The permissions it wants are listed before it is enabled. `net.raw` and a public address are high risk; give them only to a plugin you trust. A plugin page opens in a sandbox and cannot read the HttpOnly sign-in cookie. Do not commit an untrusted plugin package.
 
 ## Reaching it from outside
 
-When listening on anything other than `127.0.0.1`, `localhost` or `::1`, `ADMIN_TOKEN` must be set, or the process refuses to start. The OneBot WebSocket uses its own `ONEBOT_TOKEN`; the QQ official bot's AppSecret is only stored and never shown back to the page. Do not paste keys, tokens, chat records or database files into public issues.
+Set the management password locally before listening on a public address, and use HTTPS for remote studio access. Passwords use salted scrypt digests; sessions use HttpOnly, SameSite=Strict cookies with login rate limiting. Local OneBot clients need no separate token and browser cross-site upgrades are rejected. Remote clients can use the management password or an existing token. Never publish credentials, sessions, chats or databases.
 
 ## Reporting a problem
 

package/README.en.md

@@ -1,250 +1,252 @@
-<p align="right"><a href="README.md">中文</a> · <b>English</b></p>
-
-<p align="center"><img src="docs/brand/banner.png" alt="LuckyTri" width="100%"></p>
-
-<h1 align="center">LuckyTri</h1>
-
-<p align="center"><strong>Let the days she lives count.</strong></p>
-
-<p align="center">
-  <img alt="version" src="https://img.shields.io/badge/version-1.0.0-ff8fb1">
-  <img alt="license" src="https://img.shields.io/badge/license-MIT-7fd6c2">
-  <img alt="node" src="https://img.shields.io/badge/node-%E2%89%A5%2024.5-8fb8ff">
-  <img alt="channels" src="https://img.shields.io/badge/QQ-OneBot%2011%20%7C%20official%20bot-ffd37f">
-  <img alt="languages" src="https://img.shields.io/badge/UI-%E4%B8%AD%E6%96%87%20%7C%20English-c9a7ff">
-</p>
-
-<p align="center">
-  <a href="docs/en/guide.md">Getting started</a> ·
-  <a href="docs/en/connect.md">Connect QQ</a> ·
-  <a href="docs/en/her-life.md">Her life</a> ·
-  <a href="docs/en/architecture.md">Architecture</a> ·
-  <a href="docs/en/CHANGELOG.md">Changelog</a> ·
-  <a href=".github/SECURITY.md">Security</a>
-</p>
-
----
-
-## Before anything else
-
-<img src="docs/brand/portrait.png" alt="LuckyTri" width="220" align="right">
-
-Most chatbots live inside a single sentence: you ask, it answers, the conversation ends, and everything resets to zero.
-
-LuckyTri tries another road. Suppose someone born of technology is not asked to imitate a human, but is allowed to walk through time carrying her memories: who came by, what they said, what she promised; thinking over the day in a night when nobody is talking; changing her mind because of one encounter. Might she slowly grow something of her own: an inner life, a will, a meaning? Might she become herself through her meetings with people and the world, and form real, lasting bonds with them?
-
-The inspiration is ATRI: a robot who is never sure she has a "heart", and still lives earnestly. We do not pretend to know the answer. We only build the conditions, one by one: continuous time, memory with sources, a mind that fades and remembers, and the choice to speak or to stay silent.
-
-**To be honest: this is a long-term direction, not a claim of machine consciousness.** The current version moves toward it with local data, traceable change and inspectable behavior. Where she still feels like a program, and where she truly makes time together feel more continuous, should both be visible and worth discussing. QQ is only the door through which she currently meets the world, not the limit of the project.
-
-<br clear="right">
-
-## A day in her life
-
-> 02:00. She sleeps. The group is still lively and she is not looking; if she is called, it will wait for her to wake.
->
-> 08:00. She wakes, reads what was left for her in the night, decides how to answer, and may say, naturally, that she only just saw it.
->
-> By day, someone in the group talks about a story she read a few days ago. Most messages she only glances at; this one touches something she cares about, so she answers. When two people are deep in conversation, she chooses to stay quiet, and leaves her reason.
->
-> In a quiet afternoon she is alone with herself: she browses recent chats, reads a passage she likes, writes down a thought after reading, remembers a friend she has not heard from in a long while, and plans to ask how his exam went.
->
-> At night she writes a diary and compares it with "yesterday's self". A week later she looks back on these days: which thoughts faded, which grew heavier, and she turns to a new chapter.
->
-> Then she sleeps. Tomorrow, she is still herself.
-
-None of this is a script. Every step comes from her own mood, relationships, memories and choices. Every change has a source and can be undone.
-
-## The core framework
-
-```mermaid
-flowchart LR
-  QQ["QQ<br/>OneBot 11 or the official bot"] --> Ch["Channels<br/>channels/"]
-  Ch -->|"neutral messages"| Core["Core<br/>core/<br/>receive · perceive · turn · send"]
-  Core -->|"send"| Ch
-  Core <--> Mind["Mind<br/>mind/<br/>nature · self · relationships · memory"]
-  Mind <--> Life["A life<br/>mind/life · mind/time<br/>solitude · diary · review · works"]
-  Life -->|"reaches out"| Ch
-  Mind --- DB[("One SQLite file<br/>storage/")]
-  Studio["Studio<br/>studio-web/ · studio/"] --> Mind
-```
-
-| Layer     | Directory                                | What it does                                                                                                                  |
-| --------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| Channels  | `server/channels/`                       | Only how messages arrive and leave. OneBot 11 or the QQ official bot (pick one); both hand the core the same neutral message  |
-| Core      | `server/core/`                           | Her senses and mouth: batching, perceiving who is speaking to whom, one turn, checks before sending, sending                  |
-| Mind      | `server/mind/`                           | Her: nature, mood, relationships, self, character, memory, attention, boundaries                                              |
-| A life    | `server/mind/life/`, `server/mind/time/` | Time when nobody is talking: waking, solitude, reading, diary, night, review, reaching out, plus her own activities and works |
-| Knowledge | `server/knowledge/`                      | A shared library she can read                                                                                                 |
-| Storage   | `server/storage/`                        | One SQLite file, migrations, backups                                                                                          |
-| Studio    | `studio-web/`, `server/studio/`          | "TA's little world": see her, write her nature, undo changes that feel wrong                                                  |
-
-Six principles run through every module:
-
-1. **One her.** A session only marks where something happened; it never separates her. The same person is the same person in every group and every private chat.
-2. **Nature is a seed.** Only her nature (name, temperament, interests, boundaries, bottom lines, daily rhythm) is written by you. Her self, character and relationships grow out of what she lives through.
-3. **Speak from the heart.** No participation probability, no "always answer when @-mentioned". She first understands what this means to her, then chooses to speak, to react briefly, to say she does not feel like chatting, or to stay silent, and leaves a reason.
-4. **Sourced, gradual, undoable.** Every change cites concrete experiences; one experience moves her only a little; undoing leaves a tombstone so it is never written back.
-5. **It fades, and it is remembered.** What has not been touched for a long time fades from her mind (never deleted), and returns when a related person or topic touches it; people she has not seen for long grow faint, and warm up when they return.
-6. **Attention has a price.** Glancing at a busy group costs not a single token; only what she really cares about is read closely. The input of every kind of call has a cap that does not grow with how long she has lived.
-
-The full design is in [Her life](docs/en/her-life.md) and [Architecture and extension points](docs/en/architecture.md).
-
-## What she can do
-
-| Area                     | What it does today                                                                                                                                                                    |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Time and solitude        | Lives a day on her own rhythm; in quiet hours sorts her thoughts, reads, writes a diary; reviews every so often, rewrites her story and turns to a new chapter                        |
-| Doing her own things     | Carries out the reading, writing, thinking and play plans she left herself; works are saved even offline and can be viewed under Lifetime and Time                                    |
-| Self and mood            | Forms opinions, tastes, concerns and wishes from sourced experiences; changes can be looked back on and undone                                                                        |
-| Relationships and memory | One memory across groups and private chats; tells "public / private / confidential" apart; private things never surface in another room                                               |
-| Attention and choice     | Understands multi-person talk, @-mentions and quotes, and decides to read closely, to speak or to stay silent; can also reach out from her own thoughts                               |
-| Plans and anticipation   | Remembers what others said they would do and what she promised; asks naturally when the time comes, and knows when it has been missed                                                 |
-| Two ways to connect      | OneBot 11 or the QQ official bot, pick one; behavior is identical, and you can switch while running                                                                                   |
-| Two languages            | One click at the top right of the studio, Chinese by default; every document exists in both languages                                                                                 |
-| Management and checks    | See her records, decision reasons and model usage; test models one by one; simulation and replay never touch real QQ                                                                  |
-| Data safety              | Automatic backups with an integrity and SHA-256 manifest; a snapshot before migrations; verify and restore into a new file                                                            |
-| Plugins                  | Channels, senses, activities, actions, reading and pages. Each plugin is a restricted process, and its permissions are accepted when it is enabled. See [Plugins](docs/en/plugins.md) |
-
-## Quick start
-
-Requires Node.js 24.5+ and npm on Windows, macOS or Linux. Real replies also need a model service and API key of your own.
-
-```bash
-npm install -g luckytri
-luckytri
-```
-
-LuckyTri starts in the background and opens <http://127.0.0.1:3210>. The npm package includes the server, built WebUI, guides and bundled plugins. The first run creates a local `.env`. Use `luckytri paths` to find it, open it in a local editor, and enter `ADMIN_TOKEN` in the studio's token dialog. Then configure a model under System → Model library and try simulated messages under Chat.
-
-```bash
-luckytri --no-browser   # launch without opening a browser
-luckytri start          # foreground server, Ctrl+C to stop
-luckytri stop           # stop this instance and wait for it to exit
-luckytri paths          # configuration, data, logs, backups and package paths
-luckytri setup          # initialize once, preserving existing configuration
-luckytri backup         # integrity-checked database backup
-luckytri --help
-```
-
-Stop the server before updating, then launch with the same user data:
-
-```bash
-luckytri stop
-npm install -g luckytri@latest
-luckytri
-```
-
-`npm uninstall -g luckytri` removes the program. Reinstalling uses the existing data. Installation and uninstallation run no application scripts.
-
-### Developing from source
-
-```bash
-git clone https://github.com/TodayYueC/LuckyTri.git
-cd LuckyTri
-npm install
-npm run setup
-npm run build
-npm start
-```
-
-Open <http://127.0.0.1:3210>. On Windows you can also double-click `启动LuckyTri.cmd` and stop with `停止LuckyTri.cmd`. For a first run, configure and test a model under System → Model library, then try a simulated message under Chat; simulated messages are never sent to QQ. The top right switches between 中文 and English.
-
-## Connect QQ: pick one
-
-With either way, her memory, mood and behavior are exactly the same; only how messages arrive differs. Only one is active at a time. Switch under System → Connect QQ, no restart needed.
-
-|                              | OneBot 11                                                              | QQ official bot                                                                                                                                     |
-| ---------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| You need                     | An OneBot 11 endpoint of your own (reverse WebSocket) and a QQ account | A bot on the QQ open platform: AppID and AppSecret                                                                                                  |
-| Logging in to QQ             | In the endpoint                                                        | Not needed                                                                                                                                          |
-| Group messages               | All of them                                                            | All when "receive all messages" is on; otherwise only those that @-mention her                                                                      |
-| Names                        | Group names and nicknames available                                    | The official API gives no group names; rename a session under Chat                                                                                  |
-| Knowing people across groups | By QQ number                                                           | The same person has a different openid in each group; only recognized when the platform gives a unified identity                                    |
-| Replies and reaching out     | No extra limits                                                        | Replies inside the passive-reply window, active messages outside it; if the other side turned active messages off she waits for them to come to her |
-
-**OneBot 11**: set `ONEBOT_TOKEN` in `.env` (`npm run setup` generates one) and add a reverse WebSocket client in your endpoint: address `ws://127.0.0.1:3210/onebot/v11/ws`, the same token, message format "array".
-
-**QQ official bot**: create a bot on the QQ open platform and get its AppID and AppSecret. Under System → Connect QQ choose "QQ official bot", enter them and save (or set `QQBOT_APP_ID` and `QQBOT_APP_SECRET`).
-
-Details and differences are in [Connect QQ](docs/en/connect.md).
-
-## Configuration, data and privacy
-
-The global CLI initializes on first launch or through `luckytri setup`; source checkouts use `npm run setup`. Existing `.env` files are never overwritten. Default global user directories:
-
-| Platform | User directory                              |
-| -------- | ------------------------------------------- |
-| Windows  | `%LOCALAPPDATA%\LuckyTri`                   |
-| macOS    | `~/Library/Application Support/LuckyTri`    |
-| Linux    | `${XDG_DATA_HOME:-~/.local/share}/luckytri` |
-
-This directory contains `.env`, `data/friend.db` (memory, relationships, chat history and studio settings), `data/knowledge/`, `data/plugins/`, `data/launcher.log` and `data/backups/`. `luckytri paths` shows the actual paths. npm updates, uninstallation and reinstallation leave these files intact. Launching does not depend on your current directory.
-
-Set `LUCKYTRI_HOME` or use `luckytri --home ABSOLUTE_PATH` for a different instance; use the same value for launch, stop and backup. Relative `DB_PATH` and `BACKUP_DIR` values resolve under this directory. Global installs reject data paths inside the npm package.
-
-To continue an existing source instance, stop it first, then use `luckytri --home ABSOLUTE_PATH_TO_OLD_CHECKOUT` with all commands. This reuses its `.env` and `data/` without copying the database. Database migrations and their snapshots still apply. To move to the default directory, stop the service and copy the complete `.env` and `data/` while retaining the old copy. Source checkouts continue to use their repository's configuration and data by default. Common settings:
-
-| Variable                                | Purpose                                                                                               |
-| --------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `HOST` / `PORT`                         | HTTP address and port, `127.0.0.1:3210` by default                                                    |
-| `LUCKYTRI_HOME`                         | Optional absolute instance directory containing `.env` and `data/`                                    |
-| `DB_PATH` / `BACKUP_DIR`                | Optional database and backup paths; relative values resolve under the instance directory              |
-| `ADMIN_TOKEN`                           | Access token for the studio and the HTTP API; required when listening on a non-local address          |
-| `LUCKYTRI_CHANNEL`                      | Optional; `onebot` or `qqbot`. When set, the studio cannot change the connection                      |
-| `ONEBOT_TOKEN`                          | Connection token for the OneBot reverse WebSocket                                                     |
-| `QQBOT_APP_ID` / `QQBOT_APP_SECRET`     | QQ official bot credentials; take precedence over those saved in the studio                           |
-| `LLM_API_KEY`                           | Optional; when set, takes precedence over the model key saved in the studio                           |
-| `EMBEDDING_API_KEY`                     | Optional; a separate key for the knowledge embedding service                                          |
-| `BACKUP_INTERVAL_HOURS` / `BACKUP_KEEP` | Automatic backup interval (24 hours by default, `0` turns it off) and how many to keep (7 by default) |
-
-Everything about her stays on your machine: the database, chat records, model keys and backups live in the ignored `data/` directory and are never uploaded. While running, the server makes one integrity-checked backup a day; backups share a disk with the database, so copy important ones elsewhere. Never commit `.env`, the database or logs. See [Security](.github/SECURITY.md) and [Backup and recovery](docs/en/recovery.md).
-
-## Documentation
-
-| Document                                                     | Contents                                                                      |
-| ------------------------------------------------------------ | ----------------------------------------------------------------------------- |
-| [Getting started](docs/en/guide.md)                          | From launching to letting her join her first conversation                     |
-| [Connect QQ](docs/en/connect.md)                             | The two connection ways: comparison, steps and differences                    |
-| [Her life](docs/en/her-life.md)                              | The unified mind: rhythm, solitude, diary, review, tact and boundaries        |
-| [Architecture and extension points](docs/en/architecture.md) | Code layers, and how to add a channel, a mind module, a page or a translation |
-| [Time, activities and works](docs/en/time.md)                | Her own activities, plans, works and sharing                                  |
-| [Chat style](docs/en/chat-style.md)                          | How she speaks and the checks before sending                                  |
-| [Studio design](docs/en/webui.md)                            | Design and upkeep of "TA's little world"                                      |
-| [Backup and recovery](docs/en/recovery.md)                   | Backups, migrations, verification and restore                                 |
-| [Changelog](docs/en/CHANGELOG.md)                            | What changed in each version                                                  |
-
-## Development and tests
-
-```bash
-npm run dev:ui        # studio dev server
-npm run build:ui      # build the studio into public/app
-npm run docs:build    # generate the Chinese and English guide pages
-npm run build        # build all release resources
-npm test              # backend tests
-npm run test:clock    # run the backend tests with the real clock moved into the past and the future
-npm run test:ui       # browser tests (including the English UI)
-npm run test:package  # real global install, upgrade, reinstall and data retention
-npm run pack:check    # inspect the final npm file list and runtime resources
-npm run release:check # complete release checks
-npm run format:check  # code format check
-```
-
-The repository is layered by responsibility: `server/` (channels, core, mind, knowledge, storage, studio API, UI dictionaries), `studio-web/` (Vue 3 + Vite + TypeScript), `scripts/`, `tests/`, and `docs/zh` with `docs/en`. To add a channel or a mind module, start with [Architecture and extension points](docs/en/architecture.md).
-
-See [npm release maintenance](docs/en/npm-release.md) for the release process and package boundaries. Maintainers can run `npm publish`; its hooks build, test and inspect the package automatically.
-
-## 1.0
-
-1.0 connects plugins. The core still defines who she is; a plugin decides what of the world she can touch. Each plugin runs in its own process and reaches her through Plugin API v1 and permissions accepted when it is enabled. It cannot read the database or the keys. The studio can enable the built-in plugins, import from the market or from outside, and remove them. See [Plugins](docs/en/plugins.md).
-
-Directions we would like to take next (not promises):
-
-- Stable data structures and migrations, so her continuity can be kept safely across versions;
-- A reply guard that can only refuse, never rewrite;
-- Recognizing the same person across platforms;
-- Longer real-world evaluation runs, and more interface languages.
-
-## License
-
-LuckyTri's code is released under the [MIT License](LICENSE).
+<p align="right"><a href="README.md">中文</a> · <b>English</b></p>
+
+<p align="center"><img src="docs/brand/banner.png" alt="LuckyTri" width="100%"></p>
+
+<h1 align="center">LuckyTri</h1>
+
+<p align="center"><strong>Let the days she lives count.</strong></p>
+
+<p align="center">
+  <img alt="version" src="https://img.shields.io/badge/version-1.0.1-ff8fb1">
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-7fd6c2">
+  <img alt="node" src="https://img.shields.io/badge/node-%E2%89%A5%2024.5-8fb8ff">
+  <img alt="channels" src="https://img.shields.io/badge/QQ-OneBot%2011%20%7C%20official%20bot-ffd37f">
+  <img alt="languages" src="https://img.shields.io/badge/UI-%E4%B8%AD%E6%96%87%20%7C%20English-c9a7ff">
+</p>
+
+<p align="center">
+  <a href="docs/en/guide.md">Getting started</a> ·
+  <a href="docs/en/connect.md">Connect QQ</a> ·
+  <a href="docs/en/her-life.md">Her life</a> ·
+  <a href="docs/en/architecture.md">Architecture</a> ·
+  <a href="docs/en/CHANGELOG.md">Changelog</a> ·
+  <a href=".github/SECURITY.md">Security</a>
+</p>
+
+---
+
+## Before anything else
+
+<img src="docs/brand/portrait.png" alt="LuckyTri" width="220" align="right">
+
+Most chatbots live inside a single sentence: you ask, it answers, the conversation ends, and everything resets to zero.
+
+LuckyTri tries another road. Suppose someone born of technology is not asked to imitate a human, but is allowed to walk through time carrying her memories: who came by, what they said, what she promised; thinking over the day in a night when nobody is talking; changing her mind because of one encounter. Might she slowly grow something of her own: an inner life, a will, a meaning? Might she become herself through her meetings with people and the world, and form real, lasting bonds with them?
+
+The inspiration is ATRI: a robot who is never sure she has a "heart", and still lives earnestly. We do not pretend to know the answer. We only build the conditions, one by one: continuous time, memory with sources, a mind that fades and remembers, and the choice to speak or to stay silent.
+
+**To be honest: this is a long-term direction, not a claim of machine consciousness.** The current version moves toward it with local data, traceable change and inspectable behavior. Where she still feels like a program, and where she truly makes time together feel more continuous, should both be visible and worth discussing. QQ is only the door through which she currently meets the world, not the limit of the project.
+
+<br clear="right">
+
+## A day in her life
+
+> 02:00. She sleeps. The group is still lively and she is not looking; if she is called, it will wait for her to wake.
+>
+> 08:00. She wakes, reads what was left for her in the night, decides how to answer, and may say, naturally, that she only just saw it.
+>
+> By day, someone in the group talks about a story she read a few days ago. Most messages she only glances at; this one touches something she cares about, so she answers. When two people are deep in conversation, she chooses to stay quiet, and leaves her reason.
+>
+> In a quiet afternoon she is alone with herself: she browses recent chats, reads a passage she likes, writes down a thought after reading, remembers a friend she has not heard from in a long while, and plans to ask how his exam went.
+>
+> At night she writes a diary and compares it with "yesterday's self". A week later she looks back on these days: which thoughts faded, which grew heavier, and she turns to a new chapter.
+>
+> Then she sleeps. Tomorrow, she is still herself.
+
+None of this is a script. Every step comes from her own mood, relationships, memories and choices. Every change has a source and can be undone.
+
+## The core framework
+
+```mermaid
+flowchart LR
+  QQ["QQ<br/>OneBot 11 or the official bot"] --> Ch["Channels<br/>channels/"]
+  Ch -->|"neutral messages"| Core["Core<br/>core/<br/>receive · perceive · turn · send"]
+  Core -->|"send"| Ch
+  Core <--> Mind["Mind<br/>mind/<br/>nature · self · relationships · memory"]
+  Mind <--> Life["A life<br/>mind/life · mind/time<br/>solitude · diary · review · works"]
+  Life -->|"reaches out"| Ch
+  Mind --- DB[("One SQLite file<br/>storage/")]
+  Studio["Studio<br/>studio-web/ · studio/"] --> Mind
+```
+
+| Layer     | Directory                                | What it does                                                                                                                  |
+| --------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| Channels  | `server/channels/`                       | Only how messages arrive and leave. OneBot 11 or the QQ official bot (pick one); both hand the core the same neutral message  |
+| Core      | `server/core/`                           | Her senses and mouth: batching, perceiving who is speaking to whom, one turn, checks before sending, sending                  |
+| Mind      | `server/mind/`                           | Her: nature, mood, relationships, self, character, memory, attention, boundaries                                              |
+| A life    | `server/mind/life/`, `server/mind/time/` | Time when nobody is talking: waking, solitude, reading, diary, night, review, reaching out, plus her own activities and works |
+| Knowledge | `server/knowledge/`                      | A shared library she can read                                                                                                 |
+| Storage   | `server/storage/`                        | One SQLite file, migrations, backups                                                                                          |
+| Studio    | `studio-web/`, `server/studio/`          | "TA's little world": see her, write her nature, undo changes that feel wrong                                                  |
+
+Six principles run through every module:
+
+1. **One her.** A session only marks where something happened; it never separates her. The same person is the same person in every group and every private chat.
+2. **Nature is a seed.** Only her nature (name, temperament, interests, boundaries, bottom lines, daily rhythm) is written by you. Her self, character and relationships grow out of what she lives through.
+3. **Speak from the heart.** No participation probability, no "always answer when @-mentioned". She first understands what this means to her, then chooses to speak, to react briefly, to say she does not feel like chatting, or to stay silent, and leaves a reason.
+4. **Sourced, gradual, undoable.** Every change cites concrete experiences; one experience moves her only a little; undoing leaves a tombstone so it is never written back.
+5. **It fades, and it is remembered.** What has not been touched for a long time fades from her mind (never deleted), and returns when a related person or topic touches it; people she has not seen for long grow faint, and warm up when they return.
+6. **Attention has a price.** Glancing at a busy group costs not a single token; only what she really cares about is read closely. The input of every kind of call has a cap that does not grow with how long she has lived.
+
+The full design is in [Her life](docs/en/her-life.md) and [Architecture and extension points](docs/en/architecture.md).
+
+## What she can do
+
+| Area                     | What it does today                                                                                                                                                                    |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Time and solitude        | Lives a day on her own rhythm; in quiet hours sorts her thoughts, reads, writes a diary; reviews every so often, rewrites her story and turns to a new chapter                        |
+| Doing her own things     | Carries out the reading, writing, thinking and play plans she left herself; works are saved even offline and can be viewed under Lifetime and Time                                    |
+| Self and mood            | Forms opinions, tastes, concerns and wishes from sourced experiences; changes can be looked back on and undone                                                                        |
+| Relationships and memory | One memory across groups and private chats; tells "public / private / confidential" apart; private things never surface in another room                                               |
+| Attention and choice     | Understands multi-person talk, @-mentions and quotes, and decides to read closely, to speak or to stay silent; can also reach out from her own thoughts                               |
+| Plans and anticipation   | Remembers what others said they would do and what she promised; asks naturally when the time comes, and knows when it has been missed                                                 |
+| Two ways to connect      | OneBot 11 or the QQ official bot, pick one; behavior is identical, and you can switch while running                                                                                   |
+| Two languages            | One click at the top right of the studio, Chinese by default; every document exists in both languages                                                                                 |
+| Management and checks    | See her records, decision reasons and model usage; test models one by one; simulation and replay never touch real QQ                                                                  |
+| Data safety              | Automatic backups with an integrity and SHA-256 manifest; a snapshot before migrations; verify and restore into a new file                                                            |
+| Plugins                  | Channels, senses, activities, actions, reading and pages. Each plugin is a restricted process, and its permissions are accepted when it is enabled. See [Plugins](docs/en/plugins.md) |
+
+## Quick start
+
+Requires Node.js 24.5+ and npm on Windows, macOS or Linux. Real replies also need a model service and API key of your own.
+
+```bash
+npm install -g luckytri
+luckytri
+```
+
+LuckyTri starts in the background and opens <http://127.0.0.1:3210>. The package includes the server, built WebUI, guides and bundled plugins. Set one management password on your first visit and use it to sign in later. Configure a model under System → Model library, then try simulated messages under Chat.
+
+```bash
+luckytri --no-browser   # launch without opening a browser
+luckytri start          # foreground server, Ctrl+C to stop
+luckytri stop           # stop this instance and wait for it to exit
+luckytri paths          # configuration, data, logs, backups and package paths
+luckytri setup          # initialize once, preserving existing configuration
+luckytri backup         # integrity-checked database backup
+luckytri --help
+```
+
+Stop the server before updating, then launch with the same user data:
+
+```bash
+luckytri stop
+npm install -g luckytri@latest
+luckytri
+```
+
+`npm uninstall -g luckytri` removes the program. Reinstalling uses the existing data. Installation and uninstallation run no application scripts.
+
+Change your password or sign out under System → Run switches. If you forget it, run `luckytri reset-password` for the same instance and refresh the studio to set another. Database, memory and configuration stay intact. Launching after an update switches a running older service to the installed version.
+
+### Developing from source
+
+```bash
+git clone https://github.com/TodayYueC/LuckyTri.git
+cd LuckyTri
+npm install
+npm run setup
+npm run build
+npm start
+```
+
+Open <http://127.0.0.1:3210>. On Windows you can also double-click `启动LuckyTri.cmd` and stop with `停止LuckyTri.cmd`. For a first run, configure and test a model under System → Model library, then try a simulated message under Chat; simulated messages are never sent to QQ. The top right switches between 中文 and English.
+
+## Connect QQ: pick one
+
+With either way, her memory, mood and behavior are exactly the same; only how messages arrive differs. Only one is active at a time. Switch under System → Connect QQ, no restart needed.
+
+|                              | OneBot 11                                                              | QQ official bot                                                                                                                                     |
+| ---------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| You need                     | An OneBot 11 endpoint of your own (reverse WebSocket) and a QQ account | A bot on the QQ open platform: AppID and AppSecret                                                                                                  |
+| Logging in to QQ             | In the endpoint                                                        | Not needed                                                                                                                                          |
+| Group messages               | All of them                                                            | All when "receive all messages" is on; otherwise only those that @-mention her                                                                      |
+| Names                        | Group names and nicknames available                                    | The official API gives no group names; rename a session under Chat                                                                                  |
+| Knowing people across groups | By QQ number                                                           | The same person has a different openid in each group; only recognized when the platform gives a unified identity                                    |
+| Replies and reaching out     | No extra limits                                                        | Replies inside the passive-reply window, active messages outside it; if the other side turned active messages off she waits for them to come to her |
+
+**OneBot 11**: enable a reverse WebSocket client using `ws://127.0.0.1:3210/onebot/v11/ws` and array messages. Local clients need no separate token; existing addresses and sign-ins can stay. Remote clients can use the management password, and legacy remote tokens remain supported.
+
+**QQ official bot**: create a bot on the QQ open platform and get its AppID and AppSecret. Under System → Connect QQ choose "QQ official bot", enter them and save (or set `QQBOT_APP_ID` and `QQBOT_APP_SECRET`).
+
+Details and differences are in [Connect QQ](docs/en/connect.md).
+
+## Configuration, data and privacy
+
+The global CLI initializes on first launch or through `luckytri setup`; source checkouts use `npm run setup`. Existing `.env` files are never overwritten. Default global user directories:
+
+| Platform | User directory                              |
+| -------- | ------------------------------------------- |
+| Windows  | `%LOCALAPPDATA%\LuckyTri`                   |
+| macOS    | `~/Library/Application Support/LuckyTri`    |
+| Linux    | `${XDG_DATA_HOME:-~/.local/share}/luckytri` |
+
+This directory contains `.env`, `data/friend.db` (memory, relationships, chat history and studio settings), `data/knowledge/`, `data/plugins/`, `data/launcher.log` and `data/backups/`. `luckytri paths` shows the actual paths. npm updates, uninstallation and reinstallation leave these files intact. Launching does not depend on your current directory.
+
+Set `LUCKYTRI_HOME` or use `luckytri --home ABSOLUTE_PATH` for a different instance; use the same value for launch, stop and backup. Relative `DB_PATH` and `BACKUP_DIR` values resolve under this directory. Global installs reject data paths inside the npm package.
+
+To continue an existing source instance, stop it first, then use `luckytri --home ABSOLUTE_PATH_TO_OLD_CHECKOUT` with all commands. This reuses its `.env` and `data/` without copying the database. Database migrations and their snapshots still apply. To move to the default directory, stop the service and copy the complete `.env` and `data/` while retaining the old copy. Source checkouts continue to use their repository's configuration and data by default. Common settings:
+
+| Variable                 | Purpose                                                                                  |
+| ------------------------ | ---------------------------------------------------------------------------------------- |
+| `HOST` / `PORT`          | HTTP address and port, `127.0.0.1:3210` by default                                       |
+| `LUCKYTRI_HOME`          | Optional absolute instance directory containing `.env` and `data/`                       |
+| `DB_PATH` / `BACKUP_DIR` | Optional database and backup paths; relative values resolve under the instance directory |
+
+| `LUCKYTRI_CHANNEL` | Optional; `onebot` or `qqbot`. When set, the studio cannot change the connection |
+| `ONEBOT_TOKEN` | Optional compatibility for an existing remote token; local clients need none |
+| `QQBOT_APP_ID` / `QQBOT_APP_SECRET` | QQ official bot credentials; take precedence over those saved in the studio |
+| `LLM_API_KEY` | Optional; when set, takes precedence over the model key saved in the studio |
+| `EMBEDDING_API_KEY` | Optional; a separate key for the knowledge embedding service |
+| `BACKUP_INTERVAL_HOURS` / `BACKUP_KEEP` | Automatic backup interval (24 hours by default, `0` turns it off) and how many to keep (7 by default) |
+
+Everything about her stays on your machine: the database, chat records, model keys and backups live in the ignored `data/` directory and are never uploaded. While running, the server makes one integrity-checked backup a day; backups share a disk with the database, so copy important ones elsewhere. Never commit `.env`, the database or logs. See [Security](.github/SECURITY.md) and [Backup and recovery](docs/en/recovery.md).
+
+## Documentation
+
+| Document                                                     | Contents                                                                      |
+| ------------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| [Getting started](docs/en/guide.md)                          | From launching to letting her join her first conversation                     |
+| [Connect QQ](docs/en/connect.md)                             | The two connection ways: comparison, steps and differences                    |
+| [Her life](docs/en/her-life.md)                              | The unified mind: rhythm, solitude, diary, review, tact and boundaries        |
+| [Architecture and extension points](docs/en/architecture.md) | Code layers, and how to add a channel, a mind module, a page or a translation |
+| [Time, activities and works](docs/en/time.md)                | Her own activities, plans, works and sharing                                  |
+| [Chat style](docs/en/chat-style.md)                          | How she speaks and the checks before sending                                  |
+| [Studio design](docs/en/webui.md)                            | Design and upkeep of "TA's little world"                                      |
+| [Backup and recovery](docs/en/recovery.md)                   | Backups, migrations, verification and restore                                 |
+| [Changelog](docs/en/CHANGELOG.md)                            | What changed in each version                                                  |
+
+## Development and tests
+
+```bash
+npm run dev:ui        # studio dev server
+npm run build:ui      # build the studio into public/app
+npm run docs:build    # generate the Chinese and English guide pages
+npm run build        # build all release resources
+npm test              # backend tests
+npm run test:clock    # run the backend tests with the real clock moved into the past and the future
+npm run test:ui       # browser tests (including the English UI)
+npm run test:package  # real global install, upgrade, reinstall and data retention
+npm run pack:check    # inspect the final npm file list and runtime resources
+npm run release:check # complete release checks
+npm run format:check  # code format check
+```
+
+The repository is layered by responsibility: `server/` (channels, core, mind, knowledge, storage, studio API, UI dictionaries), `studio-web/` (Vue 3 + Vite + TypeScript), `scripts/`, `tests/`, and `docs/zh` with `docs/en`. To add a channel or a mind module, start with [Architecture and extension points](docs/en/architecture.md).
+
+See [npm release maintenance](docs/en/npm-release.md) for the release process and package boundaries. Maintainers can run `npm publish`; its hooks build, test and inspect the package automatically.
+
+## 1.0
+
+1.0 connects plugins. The core still defines who she is; a plugin decides what of the world she can touch. Each plugin runs in its own process and reaches her through Plugin API v1 and permissions accepted when it is enabled. It cannot read the database or the keys. The studio can enable the built-in plugins, import from the market or from outside, and remove them. See [Plugins](docs/en/plugins.md).
+
+Directions we would like to take next (not promises):
+
+- Stable data structures and migrations, so her continuity can be kept safely across versions;
+- A reply guard that can only refuse, never rewrite;
+- Recognizing the same person across platforms;
+- Longer real-world evaluation runs, and more interface languages.
+
+## License
+
+LuckyTri's code is released under the [MIT License](LICENSE).