Xiaji-yu/agent-demo

一个模块化、可自托管的 QQ 智能体：OneBot v11 协议端 ↔ NoneBot2（反向 WebSocket）↔ 本项目。
LLM 走 OpenAI 兼容接口（从 .env 读取，不绑死任何供应商）；核心 agentcore 与平台解耦，
插件层只做协议适配，可单测、可替换。
核心能力
对话与路由：私聊直答；群聊只认唤醒词或 @机器人；防抖合并、群聊上下文、图片识图与引用/转发解析
记忆与知识：长期事实（按会话作用域隔离）、滚动摘要与对话时间线警示、pgvector 语义检索、每日蒸馏、MediaWiki 直查
工具与安全：命令白名单沙箱、权限三级制（low/medium/high）、不可信内容围栏与脱敏、SSH 只读诊断、文字/歌词渲染成项目风格长图
群组与运营：发言榜/词云、原文归档、定时提醒与内容推送、主动联系（沉默检测器）、Web 总览与全部设置、成本预算
可运维：三层记录保全（归档 + 备份 + 异地镜像）、性能与内存基线、启动自检
## 文档
| 文档 | 内容 |
| docs/configuration.md | 配置项详解：LLM（不绑死供应商）/ OneBot 反向 WS / 数据库 / 成本预算 |
| docs/features-messaging.md | 消息路由与唤醒词、防抖合并、群聊上下文、图片识别与引用/转发解析、长回复分层投递 |
| docs/features-memory-and-kb.md | 长期记忆、历史裁剪与滚动摘要、对话时间线、公共知识库（RAG）、MediaWiki 直查 |
| docs/features-community.md | 群发言榜与词云、群消息原文归档、定时提醒、定时内容推送、主动联系 |
| docs/features-skills.md | 工具集（skills）、LLM 沙箱工作区、SSH 只读诊断、权限级别与管理员动作、runshell、dbquery、自定义 .py 工具技能 |
| docs/features-interaction.md | 人格系统与成长层、点歌/放歌、Web 总览与全部设置、本机概览（戳一戳） |
| docs/operations.md | 日志归档与耗时排查（LLM step / skill done / [reply] 三层耗时）、记录保全（归档 + 备份 + 恢复）、性能/内存基线 |
| docs/deploy-nas.md | NAS 容器部署实操版（DX4600 实测：端口规划、一条命令自举、绿联 Docker UI 兼容、反向 WS 切换、验收清单） |
| docs/memory-and-persona.md | 记忆与人格详解（当前状态）：七路数据来源、system prompt 组装顺序即优先级 |
| docs/GENERAL-GUIDELINES.md | 从本仓库纪律提炼的通用工程规范（可迁移到其它项目） |
| AGENTS.md / CONTRIBUTING.md / BACKLOG.md | 接手者边界与不变量 / 提交流程 / 待办与已实证缺陷 |
| review/REVIEW-WORKFLOW.md | 增量评审规范与历史评审/修复索引 |
## 架构总览
QQ ──► OneBot v11 协议端 ──► NoneBot2（事件/权限/路由）
└─ qqagentadapter ──► agentcore
handle(request) → reply + sink(主动推送)
PostgreSQL(pgvector)：会话/消息/记忆向量/知识库/定时任务
设计原则：agentcore 是纯 Python 包，不感知 QQ；NoneBot 只当消息通道。将来想拆独立 HTTP 服务，只换壳，不动核心。
## 环境要求
Python >= 3.11
操作系统：Linux 一等公民（systemd / docker / /proc / 文件权限位均为 Linux 语义）；macOS 可跑核心对话、管理面部分降级；Windows 当前不支持（已知阻塞项见平台支持与移植边界）
ffmpeg（宿主机部署必需）：点歌功能的 silk 语音编码要调它（agentcore/music/silk.py 探测 PATH）。不装不会报错，但点歌技能整体不注册——属于静默降级，排查成本高。装：apt install ffmpeg（Debian/Ubuntu）。走 Docker 部署则镜像内已含，无需单独装
Docker & Docker Compose（可选，用于 PostgreSQL + pgvector）
OneBot v11 兼容协议端已运行，并配置为反向 WebSocket连到 NoneBot
## 平台支持与移植边界
一句话：为 Linux 部署设计；macOS 可开发/试用；Windows 有已知阻塞项，暂不支持。
### 各平台现状
| 能力 | Linux | macOS | Windows |
| 对话 / 记忆 / RAG / 调度 / Web 总览 | ✅ | ✅ | ⚠ 有阻塞项（见下） |
| 备份恢复（pgdump / JSONL） | ✅ | ✅（无 psql 时走 JSONL / docker） | ⚠ 文件锁降级 + 权限位语义缺失 |
| 运维技能（端口 / 进程 / systemctl） | ✅（/proc + systemd） | ⚠ 无 /proc → 端口列举/进程扫描返回空；无 systemctl → 服务控制不可用 | ⚠ 同 macOS |
| prockill / runshell | ✅ | ✅（POSIX 信号 / bash 可用） | ❌ 信号语义不同，未适配 |
| 点歌语音（silk） | ✅（ffmpeg） | ⚠ 需自编 silk-python（官方仅 cp312 manylinux x8664 wheel） | ⚠ 同上 |
| 文件权限不变量（落盘 0600 / 剥执行位） | ✅ | ✅ | ❌ Windows 无权限位语义，两条不变量静默失效 |
| Web 受控写入（.env + config.yaml 回写） | ✅ | ✅ | ❌ os.ONOFOLLOW 在 Windows 不存在，保存即 500 |
### 移植到其它聊天平台
agentcore/（引擎 / 记忆 / RAG / 技能 / 预算 / 安全）是平台无关的纯 Python；平台耦合全部收敛在 plugins/qqagentadapter/（OneBot v11 适配）。移植步骤：
1. 新写适配层替代 plugins/qqagentadapter/：入站消息 → payload（text / images / usertext / pingonly / sendercard…）→ engine.run(context, …)；出站复用 agentcore 的 sink / 节流 / 分层投递接口
2. ACL 层当前假设用户 ID 是纯数字（acl.py 的 isascii()+isdigit() 校验，防全角数字穿透）——用户 ID 含字母的平台需同步放宽
3. 群语义（唤醒词 / @bot / 群上下文 / 群文件上传 / 合并转发）是 OneBot 形态，需按目标平台重做；agentcore 的围栏 / 脱敏 / 工具循环可直接沿用
### 部署假设（换环境前先读）
一个进程服务一个 bot 账号：selfid 取连接中的协议端；/reboot 重启影响全部会话；预算是按日全局账本。多开请多进程 + 各自 .env / 数据目录 / 端口