qm

一款面向创业公司的多智能体工作平台——QM 深度解析

开篇：一个真实的痛点

想象一下：你们公司有 15 个人，都在用同一个 AI 助手处理日常事务。它知道所有人的邮件、文档、代码库权限，每次提问都像在办公室里大喊一声"谁能帮我查一下"——混乱、权限不清、历史记录互相覆盖。

YC Software 团队在开发 AI 应用时遇到了同样的困境：单人 AI Agent 设计简单，但要扩展到多人协作、权限隔离、共享上下文的工作场景，就成了一团乱麻。他们的解法是从头重新设计多智能体协作架构，这就是 QM（Query Manager）。

---

项目背景与起源

QM 由 YC Software 团队开发和维护，GitHub 地址 yc-software/qm，目前约 3,500+ Stars（PIFS 记录 3,359★），采用 MIT 开源许可证。

项目定位非常明确：面向创业公司（startups）的多智能体工作平台。与传统的"单人 AI 助手"不同，QM 从架构层面支持多人协作，每个员工拥有独立的隔离工作空间，同时可以在 Slack 频道、项目群组中与 AI 协同工作。

QM Web UI：两个并发会话同时运行，左侧栏包含个人文件、定时任务、密钥管理、部署管理、记忆和技能面板。

---

核心架构：三层解耦设计

QM 的架构可以分为三个核心层次：

1. 头部核心（Headless Core）

核心引擎完全跑在 Node.js 上，使用 Fastify 处理 HTTP 请求。关键特性：

• 多 Harness 支持：同一套核心可以驱动 Pi、OpenCode、Codex、Claude Code 四种主流 AI Coding Agent 引擎，部署不绑定任何单一厂商
• Agent Loop：每轮对话经过核心调度，调用相应 Harness 生成响应
• 策略引擎：内置安全策略，支持 Strict（每步人工审批）/ Moderate / Permissive 三档

2. 持久化层（Postgres）

QM 选择 Postgres 作为唯一数据库，存储：

• 用户会话（sessions）
• 记忆数据（memory）
• 任务队列（queue）

所有持久化通过 Postgres 实现，避免引入额外的数据存储依赖。

3. 沙箱层（Per-Scope Sandbox）

每个 Scope（个人/频道/项目）拥有独立的隔离沙箱：

• 独立文件系统
• 独立工具安装
• 独立已登录服务会话

Agent 执行命令时，运行在对应 Scope 的沙箱中，权限与该用户完全一致，所有操作均有审计日志。

---

类比解释：QM 像什么？

把 QM 想象成一个团队共享的 AI 中枢神经系统：

• 每个员工是一条神经纤维（独立 Scope）
• Slack 是传出神经（通知/对话入口）
• Web UI 是大脑皮层（可视化操作界面）
• Postgres 是海马体（记忆存储）
• 各种 AI Harness 是不同的"思维模式"（代码能力/对话能力/搜索能力）

---

核心功能一览

功能	说明
个人 + 共享双作用域	个人定制 AI，同时在频道中协作
Slack + Web 双入口	同一身份配置跨平台同步
后台任务（Crons & Watches）	定时自动执行，如"每天早 8 点整理邮件草稿"
Web Apps	团队内部工具，精准推送给需要的人
共享技能（Skills）	组织级技能库，可从 Git 仓库导入
密钥管理（Keychain）	安全的凭证存储与权限控制
记忆管理（Memory）	个人 + 共享两层记忆，精准检索

---

技术栈深度拆解

后端核心：

• 语言：TypeScript（Node.js >= 24.15.0）
• 框架：Fastify（HTTP API）
• 数据库：Postgres（会话/记忆/队列）
• 插件框架：模块化接口设计，生产环境通过 wiring.ts 注入

前端 UI：

• 构建工具：Vite
• 前端框架：Lit（Web Components）
• 运行方式：SPA 单页应用，可作为独立插件叠加在 Core HTTP API 之上

部署层：

• 本地：Docker（单容器）
• 云端：Fly.io（Fly Machines）/ AWS ECS Fargate
• 部署工具：qm CLI（npm exec qm -- init / up / plan / check）

测试体系：

• 单元测试：Node.js 内置测试框架 + 模拟模块
• E2E 测试：完整的端到端测试套件
• 哨兵测试（Smoke Tests）：覆盖 Pi/OpenCode/Git CLI/Google OAuth/AWS Sandbox 等关键路径

---

上手体验

Web UI 适合：日常对话、文件管理、查看部署状态、管理技能

Slack 适合：即时协作、频道讨论、项目追踪

开发/运维：qm CLI 完整覆盖 init → check → infra render → build → plan → up 全流程

最低硬件要求：

• 推荐 ARM64（Apple Silicon 或 AWS ARM 实例）
• 支持 x86_64
• 最低 8GB 内存

---

争议与局限

1. Node.js 版本要求激进：package.json 要求 node >= 24.15.0，这是极新的版本（截至 2025 年 7 月），主流 Linux 发行版的默认 Node 版本可能不满足，需要通过 nvm 或 volta 管理
2. 依赖复杂度高：大量内部模块（src/ 下 50+ 个子目录），初次阅读源码有一定门槛
3. 闭源倾向：项目本身 MIT 许可，但 @yc-software/qm CLI 包是私有的，部署流程对官方 CLI 有依赖
4. 企业级门槛：面向创业公司设计，中小型团队可能有过度工程之嫌

---

行业意义

QM 代表了 AI Agent 发展的一个新方向——从"单人助手"到"团队中枢"。随着 Claude Code、OpenCode、Codex 等工具成熟，AI Coding Agent 的个人使用已经标准化，但团队协作场景仍缺乏成熟方案。QM 在这个交叉点上提供了有价值的开源参考实现。

其多 Harness 架构（同一核心驱动不同 AI 模型）也值得关注：未来企业可以根据任务类型切换不同的 AI 引擎，而无需重建整个系统。

---

快速部署指南

# 1. 初始化部署目录
npm exec --yes --package=@yc-software/qm@latest -- \
  qm init . --org acme --target aws

# 2. 安装依赖
npm install

# 3. 本地 Docker 运行
npm exec qm -- check
npm exec qm -- doctor
npm exec qm -- up --yes