小町 QQ 角色智能体 MagicIndex135731/Komachi-qq-aibot

小町 Komachi QQ AI Bot

把一个有性格、记得上下文、会使用工具的角色，放进你的 QQ 群。

小町可以接梗闲聊、读图、翻聊天记录、查网页、画图，也能从网页、X / Twitter 和小红书帖子取回图片、视频。你不必把每次交流都变成命令；她会在授权范围内判断何时接话、何时保持安静。

Python 3.12 · DeepSeek Harness SDK 0.1.5rc1 · OneBot 11 · Windows + WSL2 + Docker

工具清单与用法 · 部署指南 · 配置参考 · 架构说明

你可以怎样和她聊

@小町 昨天群里讨论的活动最终怎么定的？给出对应来源。
@小町 看看这份合并转发，概括几个人分别说了什么。
@小町 根据引用的图片画一个冬日版本。
@小町 帮我核对这个网页，不确定的地方再查资料。
@小町 把这个推文里的图片和视频都下载下来，打包发给我。

| 想做的事 | 小町怎样完成 |
| 有性格的日常陪伴 | 默认「嘴臭小町」，也可切换人格；表达样本和事实资料分别管理 |
| 接着以前的话题聊 | 检索消息、摘要和人物资料，按需展开真实来源；撤回与失效内容受校验 |
| 看图、看转发、画图 | 读取实际像素、按页展开合并转发；生成或编辑图片进入后台任务 |
| 查资料、下载原媒体 | 搜索与打开网页；网页图集、公开视频、X 单帖媒体按来源取回，多项按顺序合并转发 |
| 自主参与与空间活动 | 有限度地观察和插话；授权后发布空间、读取好友动态并评论，操作有真实账本 |
| 委派较复杂的工作 | 多页调研可交给只读子任务；主人可使用已启用的隔离计算和行动工具 |

功能和权限由部署者配置。公开模板默认关闭主动空间与计算；工具目录中的条目也不等于当前用户有执行权限。私聊支持获准好友的日常聊天与许可绘图，不开放宿主文件、Shell 或远程项目控制。

为长期运行做了哪些优化

把聊天上下文整理成不同用途。 固定角色规则与工具定义尽量保持稳定；当前提问、实际互动、临时群聊观察和长期事实分别处理。最近最多 30 条群消息只作为当轮观察，普通观察约 3000 token 软预算，明确提问和必要引用优先保留。成功的纯静默过程不会一轮轮堆进历史。

让记忆真正进入当前任务。 智能体从既有 V3 记忆中按需取回原文、事实和摘要，自动召回有独立预算，最终证据与来源一并准入；近期群聊由观察窗口提供。历史依赖单独追踪，累计读过 200 条消息不会因此清空会话。主对话在较长且稳定的历史上低频压缩，保留近期交互、任务目标和实际回复；撤回与事实更正仍优先处理。

让主对话继续聊天。 群聊和私聊可并行处理独立请求，慢任务不挡后续提问。绘图、图片和视频下载进入后台队列，复杂资料研究使用独立只读子任务。简单下载按原请求交付，需要分析或筛选才回主对话核对。空间巡检使用有界上下文；近期评论草稿、结果和明确保存的想法可按需查询，历史记录不自动触发补发。

媒体请求中，模型未选中已有候选时可在原预算内本地取回，下载失败继续后续候选，送达数量和类型足够后停止。直接取回的内容会注明尚未逐项核实；发送回执未知时停止续补，避免重复发送。具体限制见工具清单。

围绕目标组合工具。 群聊和私聊共享轻量目标与交付验收，链接可在本次授权内自行发现；工具返回搜索摘要、真实产物和发送回执时分别判断。卡住后按缺口换方法，必要时最多一次短复核；多步骤任务保留剩余项，允许如实交付部分结果。普通闲聊不增加规划或评审调用，确认交付后直接结束。

先判断有没有必要，再调用模型。 普通群消息先入库并本地合批。默认需 8 条有效新消息、至少 5 分钟才考虑主动观察，静默后逐步退避；通过后只做一次无工具轻量判断，值得参与才加载完整人格和记忆回复；判断和回复共用每群滚动一小时最多 6 次主动模型请求、3 次插话。明确互动优先响应，次数是上限，不是要求她用完的指标。

缓存与资源都有边界。 稳定工具目录配合服务端权限校验，减少因发言者变化重排模型前缀；下载媒体使用容量、时效和在用保护，失败清理半成品。监控分别展示请求、总输入、缓存输入和未缓存输入。

这些机制旨在减少重复输入、保持缓存前缀稳定、控制无效调用。缓存是否命中还取决于模型服务和请求间隔，异步任务也可能增加确认与回传请求；实际省下多少，以对应版本的自然 usage 和账单为准。了解执行分工与边界。

快速开始

准备一个 QQ 机器人账号、可用的文本/绘图 API，以及启用了 systemd 的 WSL2 Ubuntu 和 Docker/Compose。NVIDIA GPU 可选，用于本地向量推理。

1. 克隆项目，复制 环境配置模板 为私有 infra/wsl/.env，填入账号和服务配置。
2. 根据 配置参考 设置授权群、好友和功能开关；真实标识及密钥只放本地配置。
3. 在 Windows 项目根目录运行 start-xiaomachi-wsl.bat；首次启动会安装运行栈，之后启动已部署版本。
4. 按 WSL/Docker 部署与运维 完成 QQ 登录和 OneBot 配置。桥接管理入口统一在 infra/wsl/windows/；冷启动可能需要扫码。
5. 在授权群 @ 小町，或通过获准好友私聊开始使用。具体工具和使用条件见 工具清单。

源码、配置或人格修改后，用 rebuild 发布；start 不会更新已有镜像。首次部署、代理、GPU、备份与故障排查以部署指南为准。

根目录常用入口

| 入口 | 用途 |
| start-xiaomachi-wsl.bat | 首次安装或启动现有版本 |
| stop-xiaomachi-wsl.bat | 停止应用、侧车与看护服务 |
| status-xiaomachi-wsl.bat | 检查 QQ、应用和已启用组件 |
| rebuild-xiaomachi-wsl.bat | 发布当前工作区并重建应用，保留持久数据 |
| open-agent-monitor.cmd | 打开智能体现场监控 |
| switch-xiaomachi-model.cmd | 切换已有模型套餐 |
QQ 管理页、登录桌面、隐藏启动和中文监控别名在 infra/wsl/windows/；安装与运行脚本在 infra/wsl/scripts/；评估、回填、审计与维护脚本在 scripts/。日常状态检查不调用模型，深度探测可能产生一次受限真实请求。

文档导航

| 你想了解 | 去哪里 |
| 能调用哪些工具、怎么用、谁能用 | 工具清单与用法 |
| 上下文、缓存、任务协作与进程边界 | 工程架构与运行原理 |
| 参数、功能开关与权限 | 配置参考 |
| 记忆、人格与索引发布 | 记忆指南 |
| 安装、更新、备份、恢复与故障排查 | WSL/Docker 部署与运维 |
| 贡献代码、测试与扩展工具 | 开发与测试 |
| 隐私、密钥与公开发布 | 数据保护与安全发布 |

模型可能误解语义，QQ 桥接也可能断线或拒绝动作；排队、下载或生成完成都不等于消息已送达。聊天和产物保存在本地持久卷，但被选中的消息、记忆及图片会提交给你配置的服务。模型、搜索、绘图和部分更新可能产生费用。

参考与致谢

本项目参考了 fumingyang2004/Tulpa 关于持续群聊、Agent 工具协作、人格与资料授权边界的设计思路。感谢作者与贡献者公开分享实现与文档。

同时感谢 DeepSeek Harness、OneBot、SnowLuma、LLBot、NapCat、FastEmbed 与 sqlite-vec 等项目。小町自主代码采用 MIT License；第三方运行时、客户端、模型和服务遵循各自许可。