luckytri 1.0.0

package/.github/SECURITY.md

@@ -0,0 +1,71 @@
+<p align="right"><b>中文</b> · <a href="#security">English</a></p>
+
+# 安全说明
+
+LuckyTri 默认只监听本机。页面、聊天记录、记忆和模型密钥都在本地，不会上传。
+
+## 不要提交
+
+这些内容已由 `.gitignore` 排除，只应留在本机：
+
+- `.env`、`ADMIN_TOKEN`、`ONEBOT_TOKEN`、`QQBOT_APP_SECRET` 和模型 API Key
+- `data/` 下的数据库、备份、日志和聊天内容
+- 接入端的登录状态、二维码、Cookie 和运行日志
+
+仓库里的 `.env.example` 只有空字段。仓库有一个卫生测试（`tests/repo-hygiene.test.js`），会扫描已发布的文件，查找常见格式的密钥、本机路径和不该出现的记录。
+
+## 密钥进了 Git
+
+1. 在服务商后台撤销该密钥并换新密钥。
+2. 更新本机 `.env` 或 LuckyTri 中的模型配置。
+3. 从 Git 历史里去掉泄露内容后再推送。
+
+删除当前文件不会清除已经推送过的历史。
+
+## 插件
+
+插件跑在单独的进程里，默认读不到数据库、密钥和仓库，也不能自己联网。启用前会列出它要的权限。`net.raw` 和公开地址是高风险的，只交给你信任的插件。插件页面在沙箱里打开，碰不到管理令牌。不要把不受信任的插件包放进仓库。
+
+## 对外访问
+
+监听 `127.0.0.1`、`localhost` 或 `::1` 以外的地址时，必须设置 `ADMIN_TOKEN`，否则进程拒绝启动。OneBot WebSocket 使用单独的 `ONEBOT_TOKEN`；QQ 官方机器人的 AppSecret 只会被保存，不会再回显给页面。不要在公开 Issue 里粘贴密钥、令牌、聊天记录或数据库文件。
+
+## 报告问题
+
+发现安全问题时，请不要在公开 Issue 里贴出细节，也不要贴出任何密钥或聊天内容。可以通过仓库主页上的联系方式私下告诉维护者。
+
+---
+
+# Security
+
+LuckyTri listens on the local machine only by default. The pages, chat records, memories and model keys all stay on your machine and are never uploaded.
+
+## Never commit
+
+These are excluded by `.gitignore` and should only live on your machine:
+
+- `.env`, `ADMIN_TOKEN`, `ONEBOT_TOKEN`, `QQBOT_APP_SECRET` and model API keys
+- The database, backups, logs and chat content under `data/`
+- Login state, QR codes, cookies and run logs of your connection endpoint
+
+`.env.example` in the repository holds empty fields only. A hygiene test (`tests/repo-hygiene.test.js`) scans the published files for common secret formats, local paths and records that must not appear.
+
+## If a key reached Git
+
+1. Revoke the key at your provider and issue a new one.
+2. Update your local `.env` or the model settings inside LuckyTri.
+3. Remove the leaked content from Git history before pushing.
+
+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.
+
+## 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.
+
+## Reporting a problem
+
+If you find a security problem, do not post the details in a public issue, and never include any key or chat content. Tell the maintainer privately through the contact on the repository profile.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LuckyTri Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,250 @@
+<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).

package/README.md

@@ -0,0 +1,250 @@
+<p align="right"><b>中文</b> · <a href="README.en.md">English</a></p>
+
+<p align="center"><img src="docs/brand/banner.png" alt="LuckyTri" width="100%"></p>
+
+<h1 align="center">LuckyTri</h1>
+
+<p align="center"><strong>让她走过的日子算数。</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%20%E5%AE%98%E6%96%B9%E6%9C%BA%E5%99%A8%E4%BA%BA-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/zh/guide.md">上手教程</a> ·
+  <a href="docs/zh/connect.md">连接 QQ</a> ·
+  <a href="docs/zh/her-life.md">她的一生</a> ·
+  <a href="docs/zh/architecture.md">架构</a> ·
+  <a href="docs/zh/CHANGELOG.md">版本记录</a> ·
+  <a href=".github/SECURITY.md">安全说明</a>
+</p>
+
+---
+
+## 写在前面
+
+<img src="docs/brand/portrait.png" alt="LuckyTri" width="220" align="right">
+
+大多数聊天机器人活在一句话里：你问，它答，对话结束，一切归零。
+
+LuckyTri 想试另一条路。如果一个由技术诞生的「她」，不被要求去模仿人类，而是被允许带着记忆走过时间——记得谁来过、说过什么、答应过什么；在没人说话的夜里想一想今天；因为一次相遇，改变了原来的想法——那么她会不会渐渐有一点属于自己的内在、意志与意义？她能不能在与人和世界的相遇中慢慢成为自己，并和人建立真实而长久的连接？
+
+灵感来自 ATRI：一个不确定自己有没有「心」，却仍然认真生活的机器人。我们不假装知道答案，只是把条件一点一点造出来：连续的时间，有来源的记忆，会淡去也会想起的心，可以开口也可以沉默的选择。
+
+**诚实地说：这是一个长期的方向，不是对机器意识的宣称。** 当前版本用本地数据、可追溯的变化和可检查的行为来推进它；哪些地方仍像程序，哪些地方真的让相处更有连续性，都应该能被看见，也值得被讨论。QQ 只是她目前遇见世界的一扇门，不是项目的边界。
+
+<br clear="right">
+
+## 她的一天
+
+> 02:00，她睡了。群里还很热闹，她没有看——被叫到的话，会等她醒来。
+>
+> 08:00，她醒来，先读夜里留给她的话，决定怎么回，也许自然地说一句「刚看到」。
+>
+> 白天，群里有人聊起她前几天读过的故事。大多数消息她只是扫一眼；这一句碰到了她在意的事，她接了一句。两个人聊得正欢的时候，她选择不出声，并留下了理由。
+>
+> 安静下来的午后，她独处：翻翻最近的聊天，读一段喜欢的资料，写下一句读后的想法，想起一个很久没说话的朋友，打算过阵子问问他考试的结果。
+>
+> 夜里，她写日记，和「昨天的自己」对照。过了一周，她回顾这段日子：哪些念头淡了，哪些变重了，翻开新的一章。
+>
+> 然后她睡了。明天，她仍然是她。
+
+这些不是脚本。每一步都由她自己的心境、关系、记忆和选择决定，每一次变化都有来源，也都可以撤销。
+
+## 核心框架
+
+```mermaid
+flowchart LR
+  QQ["QQ<br/>OneBot 11 或官方机器人"] --> Ch["通道<br/>channels/"]
+  Ch -->|"中性消息"| Core["核心<br/>core/<br/>接收 · 感知 · 回合 · 发送"]
+  Core -->|"send"| Ch
+  Core <--> Mind["心智<br/>mind/<br/>天性 · 自我 · 关系 · 记忆"]
+  Mind <--> Life["一生<br/>mind/life · mind/time<br/>独处 · 日记 · 回顾 · 作品"]
+  Life -->|"主动联系"| Ch
+  Mind --- DB[("一个 SQLite 文件<br/>storage/")]
+  Studio["工作室<br/>studio-web/ · studio/"] --> Mind
+```
+
+| 层     | 目录                                     | 做什么                                                                                 |
+| ------ | ---------------------------------------- | -------------------------------------------------------------------------------------- |
+| 通道   | `server/channels/`                       | 只管消息怎么来、怎么去。OneBot 11 与 QQ 官方机器人二选一，向核心交出同一种中性消息     |
+| 核心   | `server/core/`                           | 感官与嘴：聚合、感知谁在对谁说、一次回合调用、发出前校验、发送                         |
+| 心智   | `server/mind/`                           | 她：天性、心境、关系、自我、面貌、记忆、注意力、底线                                   |
+| 一生   | `server/mind/life/`、`server/mind/time/` | 没人说话时的时间：醒来、独处、阅读、日记、夜里、回顾、主动联系，以及她自己的活动与作品 |
+| 资料   | `server/knowledge/`                      | 她可以阅读的共享资料库                                                                 |
+| 存储   | `server/storage/`                        | 一个 SQLite 文件、迁移、备份                                                           |
+| 工作室 | `studio-web/`、`server/studio/`          | 「TA 的小世界」：看见她、编写天性、撤销不对的变化                                      |
+
+六条原则贯穿所有模块：
+
+1. **一个她。** 会话只标记事情发生在哪里，不隔开她。同一个人在所有群和私聊里是同一个人。
+2. **天性是种子。** 只有天性（名字、性格、兴趣、边界、底线、作息）由你写；自我、面貌、关系由她从经历里长出来。
+3. **由心开口。** 没有参与概率和「被 @ 必回」。她先理解这对她意味着什么，再选择说、简短反应、说不想聊或不出声，并留下理由。
+4. **有来源、渐进、可撤销。** 每一次变化都引用具体的经历；一次经历只让她变一点点；撤销会留下墓碑，之后不会被写回。
+5. **会淡去，也会想起。** 很久没被触及的东西从心上淡出（从不删除），被相关的人或话题碰到时重新想起；久别的人变淡，重逢时回暖。
+6. **注意力有代价。** 扫一眼群聊不花一个 Token，只有真的在意才细看；每类调用的输入都有上限，不随她活得多久而增长。
+
+完整设计见 [她的一生](docs/zh/her-life.md) 与 [架构与扩展点](docs/zh/architecture.md)。
+
+## 能力一览
+
+| 方面         | 现在能做什么                                                                                              |
+| ------------ | --------------------------------------------------------------------------------------------------------- |
+| 时间与独处   | 按自己的作息过一天；安静时整理想法、阅读资料、写日记；每隔一段时间回顾，改写自传、翻开新的一章            |
+| 做自己的事   | 执行自己留下的阅读、写作、思考与游玩计划；作品离线也能保存，在「一生」「时间」里查看                      |
+| 自我与心境   | 从有来源的经历里形成看法、喜好、关注和想做的事；变化可以回看和撤销                                        |
+| 关系与记忆   | 一份跨群、跨私聊的记忆；区分「公开 / 私下 / 保密」；私下的事不会出现在别的房间                            |
+| 注意力与选择 | 理解多人对话、@ 与引用关系，决定细看、开口或沉默；也能从自己的念头出发主动联系                            |
+| 约定与期待   | 记得别人说过的安排和自己答应的事，到点自然问一句，错过了也会知道                                          |
+| 两种连接方式 | OneBot 11 或 QQ 官方机器人二选一，行为完全一致，运行中可切换                                              |
+| 中英双语     | 工作室右上角一键切换，默认中文；所有文档中英各一份                                                        |
+| 管理与验证   | 查看她的记录、决策依据、模型用量；逐个测试模型；模拟模式与回放不碰真实 QQ                                 |
+| 数据保障     | 自动备份附带完整性与 SHA-256 清单；迁移前留快照；可验证并恢复到新文件                                     |
+| 插件         | 通道、感官、活动、行动、资料和页面。每个插件一个受限进程，权限在启用时同意。见 [插件](docs/zh/plugins.md) |
+
+## 快速开始
+
+需要 Node.js 24.5+ 与 npm，支持 Windows、macOS、Linux。真实回复还需要你自己的模型服务与 API Key。
+
+```bash
+npm install -g luckytri
+luckytri
+```
+
+LuckyTri 会在后台启动并打开 <http://127.0.0.1:3210>。npm 包已包含 Server、构建好的 WebUI、教程和内置插件。首次运行自动生成本机 `.env`；运行 `luckytri paths` 查看位置，在本机编辑器中取得 `ADMIN_TOKEN`，填入管理台的令牌窗口。随后在「系统 → 模型库」配置模型，在「对话」里试用模拟消息；模拟消息不会发到 QQ。
+
+```bash
+luckytri --no-browser   # 后台启动，不打开浏览器
+luckytri start          # 前台运行，Ctrl+C 停止
+luckytri stop           # 停止当前实例，等待服务退出
+luckytri paths          # 查看配置、数据库、日志、备份和安装位置
+luckytri setup          # 提前生成配置，保留已有文件
+luckytri backup         # 创建经过完整性校验的数据库备份
+luckytri --help
+```
+
+更新前先停止服务，更新后使用同一用户数据目录：
+
+```bash
+luckytri stop
+npm install -g luckytri@latest
+luckytri
+```
+
+`npm uninstall -g luckytri` 只卸载程序，再次安装会继续使用原有数据。安装与卸载都不执行应用脚本。
+
+### 从源码开发
+
+```bash
+git clone https://github.com/TodayYueC/LuckyTri.git
+cd LuckyTri
+npm install
+npm run setup
+npm run build
+npm start
+```
+
+打开 <http://127.0.0.1:3210>。Windows 也可双击 `启动LuckyTri.cmd`，停止时双击 `停止LuckyTri.cmd`。首次使用建议先在「系统 → 模型库」配置并测试模型，再到「对话」用模拟消息试一试；模拟消息不会发到 QQ。右上角可以切换中文与 English。
+
+## 连接 QQ：二选一
+
+两种方式下她的记忆、心情和行为完全一致，区别只在消息怎么到达。同一时间只启用一个，在「系统 → 连接 QQ」里切换，运行中不需要重启。
+
+|                | OneBot 11                                           | QQ 官方机器人                                                              |
+| -------------- | --------------------------------------------------- | -------------------------------------------------------------------------- |
+| 需要           | 自备的 OneBot 11 接入端（反向 WebSocket）与 QQ 账号 | QQ 开放平台的机器人：AppID 与 AppSecret                                    |
+| 登录 QQ        | 在接入端里登录                                      | 不需要                                                                     |
+| 群消息范围     | 全部                                                | 开启「接收所有消息」时全部，否则只有 @ 她的                                |
+| 名字           | 群名与昵称都能取到                                  | 官方不提供群名，可在「对话」里给会话改名                                   |
+| 跨群认人       | 以 QQ 号为准                                        | 同一个人在不同群的 openid 不同，平台给出统一身份时才能认出                 |
+| 回复与主动联系 | 无额外限制                                          | 被动回复窗口内回复，窗口外改发主动消息；对方关闭主动消息时她会等对方来找她 |
+
+**OneBot 11**：在 `.env` 里设置 `ONEBOT_TOKEN`（`npm run setup` 会生成），在接入端添加反向 WebSocket 客户端：地址 `ws://127.0.0.1:3210/onebot/v11/ws`，令牌同上，消息格式选「数组」。
+
+**QQ 官方机器人**：在 QQ 开放平台创建机器人并取得 AppID 与 AppSecret，在「系统 → 连接 QQ」选择「QQ 官方机器人」填入并保存（或设置 `QQBOT_APP_ID` 与 `QQBOT_APP_SECRET`）。
+
+细节与差异见 [连接 QQ](docs/zh/connect.md)。
+
+## 配置、数据与隐私
+
+全局版首次启动自动初始化，也可运行 `luckytri setup`；源码版使用 `npm run setup`。已有 `.env` 不会被覆盖。全局版默认用户目录：
+
+| 平台    | 用户目录                                    |
+| ------- | ------------------------------------------- |
+| Windows | `%LOCALAPPDATA%\LuckyTri`                   |
+| macOS   | `~/Library/Application Support/LuckyTri`    |
+| Linux   | `${XDG_DATA_HOME:-~/.local/share}/luckytri` |
+
+该目录下 `.env` 保存环境配置，`data/friend.db` 保存数据库、记忆、关系、聊天和界面配置，`data/knowledge/` 保存资料，`data/plugins/` 保存插件与插件数据，`data/launcher.log` 保存后台日志，`data/backups/` 保存备份。运行 `luckytri paths` 查看实际路径。npm 更新、卸载与重装都不删除这些文件；启动不依赖当前工作目录。
+
+用 `LUCKYTRI_HOME` 环境变量或 `luckytri --home 绝对路径` 指定实例目录，后续启动、停止、备份都应使用同一个值。相对 `DB_PATH` / `BACKUP_DIR` 以实例目录为基准，绝对路径直接使用。全局版拒绝将数据写进 npm 安装目录。
+
+旧源码实例停止后，可用 `luckytri --home 原仓库的绝对路径` 继续使用原 `.env` 与 `data/`，无需复制数据库；其他操作也带上同一 `--home`。版本升级复用现有数据库迁移与迁移前快照。迁移到默认目录时，先停止服务，再复制完整 `.env` 和 `data/`，保留旧副本。源码版默认仍使用仓库内的配置与数据。常用配置：
+
+| 变量                                    | 用途                                                       |
+| --------------------------------------- | ---------------------------------------------------------- |
+| `HOST` / `PORT`                         | HTTP 监听地址与端口，默认 `127.0.0.1:3210`                 |
+| `LUCKYTRI_HOME`                         | 可选；实例目录的绝对路径，包含 `.env` 和 `data/`           |
+| `DB_PATH` / `BACKUP_DIR`                | 可选；数据库和备份位置，相对路径以实例目录为基准           |
+| `ADMIN_TOKEN`                           | 管理界面与 HTTP API 的访问令牌；监听非本机地址时必须设置   |
+| `LUCKYTRI_CHANNEL`                      | 可选；`onebot` 或 `qqbot`，设置后界面里不能更改连接方式    |
+| `ONEBOT_TOKEN`                          | OneBot 反向 WebSocket 的连接令牌                           |
+| `QQBOT_APP_ID` / `QQBOT_APP_SECRET`     | QQ 官方机器人凭据，优先于界面里保存的                      |
+| `LLM_API_KEY`                           | 可选；设置后优先于界面里保存的模型密钥                     |
+| `EMBEDDING_API_KEY`                     | 可选；独立的知识向量服务密钥                               |
+| `BACKUP_INTERVAL_HOURS` / `BACKUP_KEEP` | 自动备份间隔（默认 24 小时，`0` 关闭）与保留份数（默认 7） |
+
+她的一切都在本机：数据库、聊天记录、模型密钥和备份保存在被忽略的 `data/` 目录，不会上传。服务运行时每天自动做一份经过完整性检查的备份；备份和数据库在同一块磁盘上，重要的请自己复制到别处。不要提交 `.env`、数据库或日志。详见 [安全说明](.github/SECURITY.md) 与 [数据备份与恢复](docs/zh/recovery.md)。
+
+## 文档
+
+| 文档                                    | 内容                                               |
+| --------------------------------------- | -------------------------------------------------- |
+| [上手教程](docs/zh/guide.md)            | 从启动到让她参与第一个会话                         |
+| [连接 QQ](docs/zh/connect.md)           | 两种连接方式的对比、步骤与差异                     |
+| [她的一生](docs/zh/her-life.md)         | 统一心智的设计：作息、独处、日记、回顾、分寸与底线 |
+| [架构与扩展点](docs/zh/architecture.md) | 代码分层，以及如何新增通道、心智模块、页面与翻译   |
+| [时间、行动与作品](docs/zh/time.md)     | 她自己的活动、待办、作品与分享                     |
+| [聊天口吻](docs/zh/chat-style.md)       | 她怎么说话，发出前做哪些检查                       |
+| [工作室设计](docs/zh/webui.md)          | 「TA 的小世界」的设计与维护                        |
+| [备份与恢复](docs/zh/recovery.md)       | 备份、迁移、校验与恢复                             |
+| [版本记录](docs/zh/CHANGELOG.md)        | 每个版本的变化                                     |
+
+## 开发与测试
+
+```bash
+npm run dev:ui        # 工作室开发服务器
+npm run build:ui      # 构建工作室到 public/app
+npm run docs:build    # 生成中英文教程页
+npm run build        # 构建完整发布资源
+npm test              # 后端测试
+npm run test:clock    # 把真实时钟拨到过去和未来各跑一遍后端测试
+npm run test:ui       # 浏览器测试（含英文界面）
+npm run test:package  # 真实全局安装、更新、重装与数据保留测试
+npm run pack:check    # 检查 npm 最终文件清单与运行资源
+npm run release:check # 完整发布前检查
+npm run format:check  # 代码格式检查
+```
+
+仓库按职责分层：`server/`（通道、核心、心智、资料、存储、管理 API、界面词典）、`studio-web/`（Vue 3 + Vite + TypeScript）、`scripts/`、`tests/`、`docs/zh` 与 `docs/en`。想新增一个通道或心智模块，从 [架构与扩展点](docs/zh/architecture.md) 开始。
+
+发布流程与包内容边界见 [npm 发布与维护](docs/zh/npm-release.md)。维护者可直接运行 `npm publish`，发布钩子会自动构建、测试并检查包内容。
+
+## 1.0
+
+1.0 接上了插件。核心仍然定义她是谁；插件决定她能接触什么世界。每个插件跑在自己的进程里，经 Plugin API v1 和一份在启用时同意的权限接触她，读不到数据库和密钥。工作室里可以启用内置插件、从市场或外部导入，也可以卸载。说明见 [插件](docs/zh/plugins.md)。
+
+接下来想做的方向（不是承诺）：
+
+- 稳定数据结构与迁移，让她的连续性可以放心地跨版本保存；
+- 只能否决、不能改写的回复守卫；
+- 跨平台认出同一个人；
+- 更长时间的真实运行评测，以及更多界面语言。
+
+## 许可
+
+LuckyTri 的代码采用 [MIT License](LICENSE)。