月璃 · 文档¶
月璃是一台装在你自己机器上的程序：装好之后她跑在你本地，记忆存在你自己的硬盘里。 这份文档分两套——用户手册 讲怎么装、怎么配、怎么用； 开发手册 讲代码怎么组织、要改哪里。
从这三处开始¶
用户手册¶
安装与部署¶
| 文档 | 内容 |
|---|---|
| 手册首页 | 新手从这里开始：三条路线怎么选，各自要走哪几页 |
| 把安装交给 AI | 交给 AI 执行的安装规格：硬约束、完成判据、出错判定表 |
| 环境要求 | 系统、Python、Node、磁盘、内存、网络，以及要准备的两个账号 |
| 下载与安装 | 装 uv、拿代码、uv sync、可选的前端构建 |
| 第一次启动与配置 | 同意协议、生成配置、填 API Key、看到面板 |
| 桌面桌宠 | 前端构建、托盘各项、拖动穿透、开机自启与退出边界 |
| 无头部署 | 服务器上只跑 QQ 与面板，含 systemd 单元与 SSH 隧道 |
| 升级与回退 | 配置版本升级、数据库迁移与备份、回退旧库 |
配置¶
| 文档 | 内容 |
|---|---|
| 配置总览 | 五份 TOML 的分工、单向引用链、配置模板在哪 |
| bot.toml | 名字与别名、用户关系、人格提示词、会话记忆、群聊触发、桌宠开关 |
| models.toml | 模型目录、任务分档、挑选策略、超时、思考开关 |
| providers.toml | 厂商条目、预设标识与地址、鉴权、超时与重试 |
| features.toml | 语音、视觉与感知出口、向量召回、反馈纠错、表情包库 |
| 适配器配置 | adapter.toml 与插件目录下的 config.toml |
功能¶
| 文档 | 内容 |
|---|---|
| 功能总览 | 哪些默认开、哪些要显式打开、彼此的依赖 |
| 记忆 | 她记住什么、怎么召回、会忘掉什么、你怎么查和改 |
| 表达方式与黑话 | 学什么、从哪学、怎么审核与撤销 |
| 表情包 | 收录、语义标签、发送配额与内容审核 |
| 主动搭话 | 什么时候会主动开口、怎么调频率、怎么关 |
| 人格与状态 | 好感度按人漂移，精力与心情如何影响表达 |
| 日程与睡眠 | 一天的节奏怎么生成、睡着时什么能叫醒她 |
| 屏幕感知 | 两个正交开关、各出口的开放范围 |
| 生图管线 | 从一张参考图跑出整套角色素材 |
接入 QQ¶
| 文档 | 内容 |
|---|---|
| 接入总览 | 协议端怎么选、去哪儿下载、两个 QQ 号的分工、白名单与点名 |
| NapCat | 装协议端、建正向 WebSocket、必改项、连不上的常见原因 |
| SnowLuma | 同上，另含地址与容器的填法 |
管理面板¶
| 文档 | 内容 |
|---|---|
| 面板总览 | 怎么进、各页做什么、监听范围与鉴权 |
| 会话观察 | 阶段板、事件账本、提示词工作台、实时日志 |
| 模型与厂商 | 厂商与模型目录、任务候选与采样参数 |
| 人物与关系 | 她记住的人、关系状态与事实 |
| 黑话词表 | 学到的群内说法与命中情况 |
| 表达方式 | 学到的说话方式与被选用次数 |
| 记忆联想网络 | 记忆之间的边与扩散路径 |
| 检索调优 | 召回参数扫描与效果对照 |
| 导入中心 | 资料入知识层、按批预览与撤销 |
| 记忆管理 | 按人看事实、失效与取代、冲突裁决 |
| 表情包库 | 目录与语义标签 |
| 月璃设置 | 五份 TOML 的读改存 |
| 开发者命令 | 聊天里可用的命令与通道开关 |
出问题了¶
常见问题 —— 按症状查：启动、面板、模型调用、QQ、桌宠、数据。
开发手册¶
| 文档 | 内容 |
|---|---|
| 架构总览 | 分层、目录形状、进程关系与三条硬性边界 |
| 一次回合的完整链路 | 从入站消息到出站气泡，中间经过哪些判定 |
| 记忆系统 | 三层记忆、召回、遗忘曲线与联想扩散 |
| 平台抽象与适配器 | 出口契约、适配器插件协议、消息归属解析 |
| 可观测性 | 日志分层、事件账本、回合追踪与重放 |
| 配置体系 | 五份 TOML 的职责、交叉校验与版本升级 |
按目录逐个说明职责、对外接口与依赖关系： core/agent · core/memory · core/services · core/db · core/config · core/platform_io · core/logging 与 observe · electron · webui · adapters · scripts
开发流程：开发与验证 · 写一个工具插件 · Electron 侧的三个坑
在线站点与本地预览¶
这套文档发布在 https://docs.yuelibot.org/，
由 .github/workflows/docs.yml 在 main 分支上构建后推送到 Cloudflare Workers 静态资源。
站点配置在仓库根的 zensical.toml，域名与路由在 wrangler.toml，产物目录 site/ 不入库。
本地预览与校验不需要安装全局依赖：
uvx zensical@0.0.60 serve # 起本地服务，改 Markdown 即时刷新
uvx zensical@0.0.60 build --clean --strict # CI 用的严格构建，断链与失效锚点会直接失败
注意事项：
- 导航在
zensical.toml的nav中显式声明。新增页面时，上面的目录与本页的登记要同步修改。 - 指向
docs/之外的文件（配置模板、脚本、协议正文）一律写 GitHub 绝对链接。docs_dir之外的文件不会进入站点产物，仓库内相对路径在站上必然是死链，严格构建会拦下。 - 样式与动画在
docs/stylesheets/extra.css，图标与立绘在docs/images/。装饰性动效 一律包在prefers-reduced-motion里，改样式时不要破坏这条。