柚子是一个长期运行的个人 QQ Bot，经由 NapCat 接入 QQ。它最初是作者学习编程时逐步长出来的系统，自 2022 年起已经跨越 Windows、Linux 和多台设备持续运行。当前生产部署和宿主机能力以 Linux 为主；仓库通过 .gitattributes 把已追踪文本统一为 LF，早期 Windows 运行经历不再意味着保留 CRLF。
这个项目不追求整齐划一的框架。它是一个“混乱但能稳定运行和维护”的长期系统：在聊天窗口里提供一个可编程、可持续积累、能修改自身并快速恢复的个人环境。它偏爱极简核心与普通函数组合，而不是把权限、参数、消息和并发全部固化进框架对象。看似杂乱的命令、持久数据和动态反应共同组成了它的实际产品形态，而不是等待被框架化抹平的偶然残渣。
它最直接的起因是 QQ 自带聊天记录检索不够好用，而现成 Bot 总有不顺手的地方。更长期的兴趣则是：编程语言和自然语言是否只是两种不同的表达系统，而 QQ Bot 恰好位于两者交叉处。于是，能记录聊天、理解自然语言、执行代码、远程修改并重启自己的 Bot，逐渐成了同一个设计方向。“不用源码运行的 Bot 没有灵魂”是早期文档里夸张但准确的自我描述：可读、可改、可由聊天控制的源码，本来就是产品的一部分。
- 交互模型与设计哲学：命令优先级、上下文延续、状态范围，以及“修改后重启”为什么是有意的设计。
- 设计原则与重写判断：维护者如何评估抽象、直接能力、数据透明性和从零重写；架构讨论应先读这里。
- 运行架构：平级
mods、两阶段加载、命令注册、线性 link、动态环境和退出顺序。 - chatlog 记录格式：聊天历史的行格式协议——记录形状、v0/v1 版本切线、通知句式，以及哪些字段是事实、推导、缺省或猜测。改动它即破坏性变更。
- 演进历史：从学习 OneBot、早期
.py/.link到 HTTP、WebSocket、go-cqhttp 与 NapCat 的变迁，以及哪些旧设计已经被替换。 - 原始历史文档：旧仓库的开发记录、0.4 使用说明和背景文章；用于追溯，不作为当前契约。
- 功能与命令目录：按功能族说明公开命令、扩展运行环境和主要状态。
- LLM 聊天与工具调用：上下文构建、模型配置、函数工具、自动调用循环和当前信任边界。
- 运行边界与交互测试：NapCat 接入、真实消息路径，以及如何避免测试影响正在运行的实例。
- 当前维护队列：已经确认要修的缺陷、接受的现行约束，以及仍可选的加固项。
- 旧代码组织调查：切换前
main.py、funcs.py、动态名称环境和 import 副作用的历史摘要。 - 设计与迁移记录：已完成但尚待部署/重启的中心 reader 收束记录、已完成的 Mods 切换记录，以及仍未实现的 Storage 历史、异常日志、权限和多项目共存提案；代码已实现不等于当前运行进程已切换。
- 当前 link 反应快照：
data/storage/links.json中当前动态反应的可读索引；它是会随在线配置变化的工作快照。 - 命令开发指南：新增命令时使用的实现级资料。预期交互语义以交互文档为准，当前精确语法以命令 docstring/
.help为准；若代码与设计意图冲突，应记录差异，而不是静默任选一边。
普通命令插件提供稳定入口，.py 和语言扩展提供临时计算环境，.link 把聊天变成可现场编程的反应网络，.cave 承载群体记忆，.search 把积累下来的聊天记录变成可检索的历史（这正是项目最初的起因），中心 agent 把多个聊天窗口中主动读入的消息接成一条全局经历，而 .file、.edit、.reboot 则让 Bot 能通过聊天修改并重新加载自身。
在仓库根目录建立锁定环境并启动监督进程：
uv sync --frozen
uv run --frozen python run.py -a默认 OneBot API 端口是 5700，事件监听端口是 5701；-q 和 -p 可覆盖。生产数据、配置、聊天记录和密钥都属于本机运行状态，具体边界见运行文档。
本项目按 GNU General Public License v3.0 发布。旧仓库使用的 LICENCE 文件名保持不变。