群聊智能体 xiuxianjs/alemonjs-agent-link

AgentLink 🐟

会聊天、能查网页、记得住事，也守得住边界。

QQ Bot / OneBot 11 · Node.js 22.13+ · DSH 沙箱会话 · 单进程 · MIT

快速开始 · 运行模型 · 能做什么 · 命令速查 · 文档首页 · 配置指南

在群里 @ 它、喊一声“肥鱼”，或者直接 /提问，就能收到一段带上下文、会用工具的回答。每个群有自己的会话、Worker、工具权限和额度；私聊里它记得你说过的事。

AgentLink 是 AlemonJS 插件：消息编排、状态库、预算、工具权限都在 Node 里，模型执行交给本机 DSH Worker，每个群一份独立的沙箱与人格。

项目状态：可用，但边界明确。 代码路径、模拟收发和本地状态已有测试覆盖；真实 QQ 收发、群管理权限与部分外部服务仍要在你的账号上验收，见能力建设与验收。只支持一个 Node 进程连接同一个机器人，暂不支持多副本。

运行模型

AgentLink 运行模型：QQ 接入、Node 编排、本机 Bridge、每群 Worker

QQ / OneBot 11
→ Node 编排：去重、限流、会话代际、群内串行 → 本机 Bridge：临时令牌鉴权，限制体积，Worker 拿不到真实 Key → 每群 Worker：DSH chat-only 会话，独立 home 与沙箱

沙箱未就绪时自动降级为纯聊天，并在后台按 30 秒至 5 分钟退避重试；网页工具等沙箱恢复后再开放，终端对所有身份始终禁止。完整拆解见架构与开发。

能做什么

| 能力 | 说明 |
| 💬 群聊与私聊 | @、称呼、引用、/提问 唤醒；群内串行、去重、取消与排队上限 |
| 🎭 人格与心情 | 内置大肥鱼与助手人格，按会话切换；主人可追加设定、选三种表达程度 |
| 🧠 长期记忆 | 手动 /记住 与自动整理，关键词检索、可选语义重排、来源核对、冲突恢复与删除 |
| ❓ 问答库 | “为什么/为何”与指令用法先查已确认答案，未命中自动记录，按会话隔离 |
| 🗣️ 气泡与节奏 | 三竖线分条、最多 5 条、代码与列表不拆，打字间隔可调 |
| 🌐 工具与沙箱 | 每群独立 Worker；网页与文件按 /工具策略 开放，终端永久禁止 |
| 🖼️ 媒体 | 识图、GIF 抽帧、语音输入与合成、生图、搜图、表情收藏与配字二创 |
| 🗂️ 表情工坊 | 回环 token 面板管理素材，QQ 收藏导入/同步，按标签发送、统计与淘汰 |
| 💰 额度与模型池 | 每日预算、三本账、多 Key 端点轮转、余额查询与探活 |
| 🔑 自带 Key | 私聊个人 Key、群管理员群 Key；密文保存，只经 Bridge 内存使用 |
| 📣 主动搭话 | 主人私聊订阅，免打扰与次数上限；绑定个人 Key 后自动拉满 |
| 🧩 模块与插件 | 本地模块热更新、模型工具调用，可发现同实例其他插件的 Expose 能力 |
| 🛠️ 群管理 | OneBot 禁言、踢人、头衔、公告与戳一戳，操作回执可核对 |
| 📰 可选业务 | QQ 空间日记与互动、B 站阅读、主人评论与评论回复读取，默认只在明确请求时执行 |

群聊里它怎么接话

- 明确找它：@ 机器人、/提问、引用它的消息，或说“肥鱼，帮我……”——一定进入回答流程；句首直接叫名字、引用它的消息不再等待分类模型。
- 普通讨论：默认用 groupChat.activity: active 的积极节奏，除呼唤与话题续接外，允许模型判断是否适合加入当前公开闲聊；不会仅因消息有用、有人报错就插话。安静与均衡模式仍以呼唤和话题续接为主。再叠加冷却与每小时上限；不想开放时设 groupChat.enabled: false，@ 与命令仍可用。
- 怎么合并：短暂停顿 1.2 秒后回复，持续发言时最多聚合 4 秒；近期参考默认保留最近 20 条、15 分钟，压缩后提供给模型。
- 不会无限接：同一发送者重复内容、机器人互聊迹象与突发刷屏有本地熔断；判断本身不启动沙箱，也不写模型会话。

细节与每个参数的默认值见群聊参与策略。

快速开始

只需要 Node.js 22.13+。运行时依赖随安装包安装，不需要自己准备 Redis、Docker、Python 或 Git。

1. 准备模型 Key：默认 DeepSeek，填在 alemonjs-agent-link.apiKey。
2. 启动：

npx alemonjs-agent-link

首次会在固定用户目录生成 alemon.config.yaml 并显示绝对路径。填好 Key 后重跑同一条命令，按终端二维码完成 QQ 授权。已有 AppID 与密钥可以直接填写，跳过扫码。npx 入口需要包含新启动器的发布版本；本仓库内运行见下方命令。

3. 验证：群里 @ 机器人或私聊 /提问 你好；发送 /状态 查看实际运行情况。

遇到问题先跑离线检查，它不会连接 QQ、模型或安装依赖：

bash
npx alemonjs-agent-link doctor

本仓库使用 npm run doctor

在本仓库运行则执行： bash
npm install
npm run build
npm start # 之后直接 npm start

配置与数据默认保存在固定用户目录，换工作目录不会另建空库；需要便携目录用 --portable，指定配置用 --config 路径。

第一次设置主人：私聊机器人发送 /我是主人，到服务端日志查看 6 位验证码，再私聊回复 /我的主人 验证码。验证码仅存内存、5 分钟有效、最多尝试 5 次。验证通过后写入 master_key，群管理、模型与额度命令才会生效。

常用命令

| 谁 | 命令 | 作用 |
| 群成员 | @机器人 帮我总结一下、/提问 … | 发起提问 |
| 群成员 | /取消 | 停止自己的请求 |
| 群成员 | /状态、/额度、/群记忆、/人格、/帮助 | 状态、额度、记忆与人格 |
| 群管理员或主人 | /新会话、/聊天参考 清除、/忘记群记忆 | 换话题、清参考、删群记忆 |
| 机器人主人 | /关闭 原因、/开启 | 全局暂停与恢复 AI 请求 |
| 机器人主人 | /工具策略 网页 开启、/额度轮转、/清除群数据 | 工具权限、端点与数据清理 |

完整语法、权限门槛和二次确认见命令速查。机器人气泡上的按钮只把指令填进输入框，需要你手动发送。

数据与安全

- 默认开放：聊天、网页查询、会话目录内的文件、长期记忆、主动搭话、自动语音与表情、B 站阅读、QQ 空间读取。
- 始终禁止：终端，包括主人；配置和策略命令都不能重新开启。
- 文件边界：只能访问当前会话分配目录内的相对路径，拒绝穿越、绝对路径、符号链接与硬链接。
- 状态与清理：默认本地文件状态库，检测到框架 db.redis 时继续使用 Redis；群 Agent 数据无活动 30 天后清理，/清除群数据 需 60 秒内二次确认。
- 凭证：alemon.config.yaml 必须留在版本控制之外；日志不记录用户请求、模型输出与 Key。

详见安全与数据。

文档

- 文档导航：按使用、接入、运维和设计查找专题。
- 配置指南 · 配置字段参考 · 配置示例
- 命令速查 · 能力建设与验收
- 个人账户扫码登录（试验）：需要 Google Chrome，沙箱工作区暂不支持，QQ 实机链路待验收。

状态与已知边界

- 单进程：缺少分布式租约，多副本会破坏群内顺序、取消和首次隔离迁移。
- 平台条件：macOS 需要 sandbox-exec，Linux 需要 Bubblewrap，Windows 走 WSL2 运行完整服务；缺依赖时降级为纯聊天。平台支持
- 尚未全量验收：真实 QQ 附件与 GIF 抽帧、引用与转发、群管理执行回执、语音与生图服务、语义召回的实际嵌入服务、B 站评论/回复读取与空间发布，都要在自己的账号与网络下复核；能力表逐项标注。
- 第三方与费用：OneBot 网关、模型服务与生图服务由你自行选择，可能单独计费或调整额度；仓库不承诺免费或长期兼容。
- 信号风控：使用账号协议接入时，平台风控与账号风险由使用者承担，建议先用测试账号和小范围群。

参与与许可

欢迎提交 Issue 和 Pull Request。反馈时请提供版本、系统、复现步骤与脱敏错误，不要上传 Key、完整配置、真实聊天或登录二维码。

代码使用 MIT License。仓库不含任何可用的账号、Key、二维码或私聊原文；演示只使用占位数据。头图与架构图为项目自绘示意图，不是真实聊天或界面截图。