开发者

aibutler 是开源的（Apache-2.0），代码在 GitHub。架构、记忆引擎的设计在仓库的 README 里有详细介绍。

从源码构建

需要 Node.js 20、22 或 24，推荐 22（仓库带 .nvmrc）。Node 26 暂不支持。

git clone https://github.com/fantasyxxj/aibutler.git
cd aibutler
npm install
npm run build:agent-sdk   # 构建自带的推理层
npm start                 # 开发模式启动

打包：

npm run dist:mac         # → release/*.dmg（本机架构）
npm run dist:mac:intel   # → release/*-x64-intel.dmg
npm run dist:win         # → release/*.exe

写插件

插件是一个 JSON 包：自带界面（html / css / js）、命令声明和本地状态。最小示例是出厂自带的计数器 core/config/plugins/counter.json。

• 放哪里：数据目录下的 packages.local/，一个插件一个 .json，放进去立即热装；自己写的插件不用签名。
• 两种形态：单屏小工具 ui，多步引导流程 workflow。
• 沙箱：界面跑在沙箱里，没有 require / fetch / eval / localStorage，只有一个 butlerUI 对象（onInit · onPush · call · setState · resize）。
• 原语：命令只能落在一组固定原语上：speak save_file state message db mail ai_access web secret record pron asset bus。
• 联网：用 web 原语，包顶层写 net 域名白名单；密钥用 secret 原语存进本机金库。
• 和人格联动：按钮可以把结构化结果送回人格；标注为 AI 可用的命令，人格可以直接调用。

高度固定的界面

画布游戏这类一开始高度就固定的界面，在 onInit 里调一次 butlerUI.resize(document.body.scrollHeight + 16)，稍后再补调一两次，确保窗口撑开。

本机接口：叫醒人格

在人格管理窗口里打开本机接口后，aibutler 只在 127.0.0.1 上监听（默认端口 8787）。脚本、定时任务、监控告警发一个 POST 就能叫醒指定人格：

curl -X POST http://127.0.0.1:8787/v1/poke \
  -H 'Content-Type: application/json' \
  -d '{"persona": "研究员", "text": "CI 夜间构建失败，查一下原因", "from": "ci-bot"}'

字段	必填	说明
persona	是	要叫醒的人格名
text	是	交给它的消息
from	否	来源标记
idempotency_key	否	同一个 key 重复投递只生效一次

Butler 引擎（agent-sdk）

agent-sdk/ 是自带的多模型 agent 引擎，导出的 query() / tool() / createSdkMcpServer() 与 Claude Agent SDK 同名同签名。联网搜索的引擎链在 agent-sdk/src/tools/search-engines.ts，加一种搜索引擎只要在那里登记一个函数，再在 core/search-keys.js 的 TYPES 加一项。