Eric's Blog
← BackTech
agent-crew:在 Discord 上搭建家庭 AI 助理团队
10 月 31 日我写下 agent-crew 的第一版设计,到 11 月 21 日仓库里有 246 个提交。agent-crew 是一组运行在 Discord 上的 AI 助理,按职责分成生活助理、健身教练、日语老师、FE 考试老师、知识管家、财务专员和研读伙伴,每个角色对应一个频道。家里人在手机上给它们发消息,它们也会按计划主动发提醒。
这篇记录三件事:我想用它做什么,几个关键选择和背后的原因,以及消息、提醒和训练卡片在系统里怎么流转。
想解决的问题
在这之前,我用 Claude Code 的 Remote Control 从手机远程使用电脑上的 agent。它能用,但有两个问题一直存在。
- 每次对话都要重新交代背景,它对我和家里的情况一无所知,回答只能停留在通用层面。
- CLI 升级或 Mac 重启之后,wiki 的读写权限经常失效,需要回到电脑前处理。
因此 agent-crew 的设计围绕四个目标展开。
- 主动提醒。 每小时读一遍邮件和日历,把学校通知、快递、账单到期这类事整理成待办,在合适的时间提醒,并提前查好办理步骤。
- 长期记忆。 所有角色共用一个 Obsidian 知识库(LLM Wiki),训练记录、错题和读书笔记都写回这里,下次对话可以接着上次继续。
- 可以执行操作,但有边界。 角色可以建日程、起草邮件、修改自己负责的页面;发送邮件、邀请他人这类操作需要人工确认。
- 少回到电脑前。 系统出问题时可以在手机上找人修复,修改代码和部署也可以从手机发起。
整体架构

下面按模块说明几个关键选择和原因。
Discord 作为唯一前端
原因有三点。第一,我主要用手机,不希望在多个 App 之间切换;Discord 的频道、线程、按钮和身份组可以直接对应角色、话题、操作和权限。第二,Discord 原生支持语音消息,发来的语音会先转写成文字再交给角色,走路或训练时不方便打字也能用。第三,Discord 本身有服务器和身份组管理,把家里人或朋友拉进服务器、给一个身份组,就能一起使用(详见后文“多人使用”)。
一个 Bot 配合 Webhook 就能以不同角色的名字和头像回复,不需要为每个角色单独注册账号。
一个角色是一份 yaml 配置,每个任务启动一次 claude -p
角色不是常驻进程。
personas/coach.yaml 记录健身教练的提示词、模型、可用工具和可写的 wiki 页面。收到任务时,系统按这份配置启动一次 Claude Code CLI,任务结束进程退出。会话 ID 按“线程 + 角色”保存,同一个线程里的对话可以延续。这样做的原因是不需要自己实现 agent 循环,Claude Code 已有的工具调用、skill 和 MCP 可以直接复用,我平时在终端里用的 skill 角色也能用。进程没有常驻状态,随时可以重启。新话题开新线程和新会话,由代码挑选背景资料衔接;长会话消耗额度更多,也容易把无关话题混在一起。
运行在 Mac 上的 Kubernetes(OrbStack)里
目标是让服务在无人值守时自行恢复。期望状态写在仓库的 k8s 配置里,Pod 退出后会被重新拉起。任务先写入 SQLite 队列,重启后把未完成的任务放回队列;同一个任务连续失败 3 次才放弃,并通知发起人。这里只有一台机器,不追求高可用,只要求能自动恢复。
按钮操作不调用模型
做题、训练打卡、“完成”“今晚提醒我”这类按钮由普通代码处理。按钮的结果应该是确定的,交给代码处理更快、更可靠,也不消耗额度。
硬性限制写在代码里
每次工具调用前都有一个钩子(
guard)做检查。所有角色都不能执行 Bash;每个角色只能写自己名下的 wiki 页面;发送邮件、邀请外部人员要先在 Discord 里点确认,确认只对参数完全相同的那一次调用有效,30 分钟后过期;删除邮件一律禁止;单次任务和每天的修改次数都有上限。提示词里的规则模型可能不遵守,代码里的检查一定会执行。项目里有一条约定:同一类错误第二次出现时,优先改设计让它无法发生,其次加程序检查,最后才考虑写一条文字规则。
开发和运维放在 #projects,运行在 Pod 之外
改代码、部署、在 Mac 上操作这类工作,统一放在
#projects 频道里进行。每条消息开一个线程,由 Mac 本机上的 Engineer 接手。Engineer 在项目目录里运行 Claude Code,动手前先在线程里发分析、计划和预计时间,执行中同步进度,做完把结果发回线程。角色遇到自己做不到的事,也会把请求连同对话一起交到这里。系统需要一个不依赖自身的修复入口。Engineer 在 Pod 之外,服务停掉时仍然可以修复;角色本身也接触不到部署权限。相应的代价是 Discord 账号成了操作这台 Mac 的入口,所以代码里限定只有我和一位家庭成员可以触发。
Claude 调度其他 agent,把手上的额度都用起来
Engineer 接到的执行类工作,如果范围清楚、可以验收,会交给其他 coding agent 在独立的 git worktree 里完成。目前接入的是 agy(Google 的 Antigravity CLI),Codex 或其他命令行 agent 也可以用同样的方式接入。Claude 负责拆任务、写任务说明和验收结果,执行主要由其他 agent 承担。
这样安排的原因是我手上有不止一家的订阅额度,只用一家很容易用完。有一天 Claude 的额度用完了两次,复盘发现是开发会话自己在写功能。现在按 Claude 的用量分档:用得越多,越倾向于把执行交出去,自己只做分派和验收,接近上限时不再启动。被调度的 agent 也各自记录剩余额度,一边不够就换另一边。
其他几个决定
- 模型按档位分配。 角色配置里只写轻量、标准、高三个档位,具体对应哪个模型在一处统一配置,换模型不用改角色。直接给人看的内容至少用标准档:生活助理早期用轻量档,家人收到的第一份早间提醒就理解错了内容。高档和我写代码共用额度,消耗太快,所以也不作为默认。
- 网页走 Cloudflare Tunnel。 手机不需要安装任何客户端就能打开卡片和页面。Tailscale 留给以后的运维通道。
- 单个任务最长 30 分钟。 同时只能跑 2 个任务,也没有取消按钮;卡住的任务会一直占用名额,不设上限的话两个卡住的任务就能让整个系统停下来。
- wiki 放在 iCloud。 多个设备都能查看和编辑,同时有一层云端备份。
多人使用
agent-crew 从一开始就按多人设计。
- 身份由代码确定。 发送人按 Discord ID 识别,并写在提示词第一行,模型不需要猜测在和谁对话。
- 数据按人分开。 任务、训练卡片、答题进度、Gmail 和日历的令牌都按人隔离,每个人的会话只连接自己的账号。
- 加人只需要给身份组。 新成员进入服务器后,给对方
Crew 成员身份组即可使用;没有身份组的人发消息会被忽略。
需要说明的是,wiki 里的个人页面按 frontmatter 的
tenant 字段区分,角色能读到大部分页面,按人隔离依赖模型遵守规则,并不是权限控制。所以加人是需要明确决定的事。前端相关的代码集中在
discord_adapter 一个模块里,卡片的数据结构与平台无关。如果以后换成 Telegram 或 Slack,主要需要重写的是这一层,角色、任务队列和护栏可以保留。交互卡片:以健身训练为例
角色除了回复文字,还可以发出可以操作的卡片和网页。健身训练是用得最多的场景,完整的流程如下。

- 在
#fitness里问教练今天练什么,文字或语音都可以。
- 教练先用文字列出今天的安排,再调用
create_workout发出打卡卡片。重量的默认值来自上次的记录和计划里待执行的调整。
- 训练过程中在卡片上逐组勾选,记录重量、次数和 RIR。这一步由代码处理,点一次就更新,不需要等待模型。
- 训练结束后点“提交”。这是整个过程中第一次排队调用模型。
- 教练拿到完整记录,和计划对比,在线程里给出反馈。
- 记录写回 wiki 的训练日志,网页上可以看到训练趋势。
- 教练根据这次的数据调整下一次的计划。计划冲突时,身体不适的描述优先于计划里的数字。

上图是一次训练提交后的卡片,每组的重量、次数和 RIR 都已经记录下来。用卡片记录,数据是结构化的,教练评估的是真实记录,不依赖事后回忆。题卡也是同样的思路,做题过程由代码处理,只有“问老师”和“复盘”才调用模型,每周再按正确率最低的考点出下一组题。
一次性分享
有时需要把一个页面或一段讨论分享给别人,比如一份旅行行程、一页学习资料,或者把一次对话整理成文档。
在 Discord 里让角色把内容整理成 HTML 页面,它用
publish_page 发布到自己的域名下,经 Cloudflare Tunnel 访问,再把链接发回线程。页面不是单向展示,像 FE 题卡这样的页面上可以点“问老师”,问题会作为新任务回到对应角色那里,回答发在 Discord 线程里。家庭成员访问需要通过 Cloudflare Access 登录。需要给外部的人看时,用 share_page 生成一个带签名的链接,有效期可选 1 天、7 天或 30 天,过期后自动失效,也可以随时收回。另有一个只有家庭成员能进的控制面板,可以查看所有页面和有效的分享链接,收回分享或删除页面。一条消息怎么走

其中几处细节是实际使用后补上的。
- 连发的几条消息合成一个任务。 在手机上打字时习惯一句一发,系统先等 3 秒,把几条合起来只回复一次。
- 回复里的命令单独发一条。 手机上长按就能复制,不用在大段文字里选择。
- 转交有次数限制。 一个任务最多转交 3 次,转交链上已经出现过的角色不能再出现,避免角色之间来回转交。
- 话题分流可以不经过模型。
#inbox里没有 @ 任何角色的新消息,先交给 TypeSafe 的 Jev 做一次快速判断,把握达到 0.9 以上才直接转到对应的专题频道,否则仍由生活助理判断。
主动提醒的闭环
主动提醒是投入时间最多的部分。

分工原则是模型负责阅读和提议,代码负责决定。
- 扫描任务是一次只读的
claude -p。它读取邮件、日历和邮件中的链接,返回一个 JSON 列表。哪些条目可以存为待办、是否重复、已完成或被标为不重要的事项会不会重新出现,都由代码逐条检查。
- 待办的紧急程度由代码根据截止时间计算,不交给模型判断。
- 推送之前先做一次准备:在哪里办理、有哪些步骤、需要多少费用、官方页面在哪里,查好后写进卡片。
- 所有主动消息经由同一个发件箱发出。同一件事 24 小时内不重复发送,后续进展发在同一个线程里,21:00 到 08:00 之间不发送,每人每天有条数上限。
- 点“不重要”或“这类以后不用推”的条目会成为反例。每周日系统读取这些反例,重写 wiki 里的提醒偏好页,之后的扫描会参考这一页,跳过同类事项。

上图是某天早上 8 点
#inbox 收到的推送。上面一张卡片是邮件里读到、但不需要单独处理的事,每件都写了和家里的关系和建议;下面一张是当天的待办,紧急的那件已经附上准备好的问题,旁边有“完成”按钮。截图里的地点和家人的健康信息做了遮挡。适合与不适合
适合的工作:
- 生活中的日常事务。 学校通知、快递、预约、账单。单件事情都不复杂,需要的是不遗漏,并在合适的时间想起来。
- 学习陪练。 FE 考试和日语的题卡、错题本、到期复习提醒,以及每周按薄弱考点生成的新题组。
- 需要长期记录的事。 训练打卡、读书笔记、家庭账本。记录写回 wiki,之后的对话可以直接引用。
- 小范围的改进。 在手机上描述要改的地方,由 #projects 的 Engineer 修改代码、运行测试并部署。
不太适合的工作:
- 耗时很长的任务。 有 30 分钟的单任务上限和 2 个并发名额,目前也没有取消按钮。
- 需要严格隔离的多人场景。 wiki 的按人隔离依赖模型遵守规则。
- 对外提供服务。 现有设计假设用户只有家庭成员和少数受邀的人。
用反馈推动迭代
这三周里,家里人提出的每条反馈都记在 wiki 的反馈日志里,目前编号到 FB-045。每条记录原话、实际的问题、改了什么,并附一条回归测试,测试注释里写上反馈编号。
例如 FB-021。最初紧急待办每隔几小时就重复提醒一次,干扰太多。现在每件事最多提醒三次,分别在它变为紧急时、我说要处理的时间点、截止前两小时。类似的规则很难在设计阶段想全,主要来自实际使用。
还没有做的
- LLM Gateway。 最初的设计里有一层本地的 LLM 网关(magpie),对上提供统一的接口,对下连接多家模型服务,可以按路由组分配模型,某一家额度用完时自动切换。业务代码只认模型档位,不出现具体供应商的名字,这样可以去掉对单一 LLM 平台的依赖。这部分目前暂停,一是想先把官方 Claude 的使用方式稳定下来,二是部分供应商的条款限制订阅凭据在官方客户端之外使用,需要逐家确认。
- 从 Discord 交代长任务。 需要先解决 30 分钟上限、并发名额和取消按钮。
- 自动化验收。 把“在真实 Discord 和手机上验收”尽量自动化,同时控制额度消耗。
当前状态
自动测试全部通过,但在真实手机上的验收做得还不多。扫描是否准确、早间提醒是否有用,需要更长时间的使用才能判断。另外,Bot 使用的是个人订阅额度,这在服务条款上属于灰色地带。
这篇文章也是在终端里由 agent 通过 Notion MCP 写进博客数据库的,图由它绘制和上传,我负责审阅和发布。