yc-software/qm · 上手攻略

  • 仓库：yc-software/qm
  • 链接：https://github.com/yc-software/qm
  • 分类：AI Coding · Multiplayer Agent
  • 作者：Tom
  • 更新：2026-08-02

是什么

QM 是一个多人 AI 编程智能体平台，设计目标是让一个 AI 编程智能体服务于整个公司，而非仅限于个人助手。与传统单人 Copilot 不同，QM 通过「scope（作用域）」机制实现多用户隔离与协作：

  • Scope 即工作空间：每个员工拥有独立 scope，内含自己的记忆、文件、凭据、权限、定时任务、Web 应用和持久沙盒。
  • 协作通道：scope 可组成 Slack 频道、群聊或共享项目，多人共用一个 AI 协作。
  • 接入现有即时通讯：QM 官方插件支持 Slack（in-process 模式，由核心进程直接管理），同时也提供 Web UI。

核心技术栈：

  • 核心：TypeScript / Node.js，HTTP 层用 Fastify
  • Slack 插件：Scaffolded with Bolt
  • Web UI：Vite + Lit
  • 持久层：PostgreSQL（sessions、memory、queue）
  • 智能体引擎（harness）：Pi、OpenCode、Codex、Claude Code 可互换，部署不绑定单一模型商

安全策略：QM 强制执行 predeclared command policy（预声明命令策略），对递归删除、破坏性 SQL 等操作进行硬拦截。此外还有三级安全态势：

态势 说明
Strict 每个 harness 工具调用暂停等待人工审批（turn enders 除外）
Auto（默认） 内置分类器对外部数据和工具结果做来源筛查，可接自建代理
Dangerous 无内容筛查，工具调用无停顿

解决什么问题

大多数 AI 编程工具都是「个人助理」——一人一个 agent，跨人协作时迅速失控。QM 解决的核心问题是：

  1. 企业级多用户隔离：每个员工的 workspace 互相独立，A 员工的 agent 不会影响 B 员工的工作状态。
  2. 真实多渠道接入：同一 agent identity 在 Slack 和 Web App 之间保持一致，无需切换工具。
  3. 安全与效率的平衡：通过安全态势分级，企业可以按团队风险承受度选择审批严格程度。
  4. 跨模型可切换：用 Pi、OpenCode、Claude Code 驱动同一核心，随时切换底层模型商，不被 vendor 锁定。

快速安装

前置要求

  • Node.js（建议 20+）
  • Docker（本地开发用）
  • Fly.io CLI (flyctl) 或 AWS CLI（二选一，生产部署）
  • PostgreSQL（本地开发可用 Docker 提供）

npm 包方式初始化部署

# 推荐方式：通过 npm 直接初始化，不需要 clone 仓库
mkdir my-qm-deploy && cd my-qm-deploy
npm exec --yes --package=@yc-software/qm@latest -- \
  qm init . --org <your-org-slug> --target <fly|aws>
npm install

注意：--org 参数是本地组织标识，不需要全局唯一；--target 选择部署平台（fly=Fly.io，aws=AWS ECS Fargate），切换平台需重新初始化新目录。

本地开发验证

# 检查配置完整性（不访问网络）
npm exec qm -- check

# 渲染部署计划
npm exec qm -- plan

# 启动本地服务（Docker 模式）
npm exec qm -- up --yes

# 连接验证
npm exec qm -- check --live

核心用法

部署目录结构

qm init 生成的目录结构：

qm.config.jsonc       # 部署配置（提交到 git，不含密钥）
package.json
.env                   # 密钥文件，.gitignore
deployment.md          # 部署运行手册
.codex/skills/         # Agent 可用的 skill 集
Dockerfile             # 核心镜像
plugins/<name>/Dockerfile
sandbox/
  tools/<id>/tool.json  # 自定义工具定义
  skills/<id>/SKILL.md  # 自定义 skill
infra/                  # Terraform 模块（operator 自行运行 terraform apply）

qm CLI 常用命令

# 初始化（已有目录时对指定子目录初始化）
node cli/bin/qm.ts init deploy/layers/<org> --org <slug> --target <fly-or-aws>

# 配置校验
npm exec qm -- check

# 基础设施渲染
npm exec qm -- infra render

# 生产部署（需要 --yes 确认）
npm exec qm -- up --yes

# 部署后 live 检查
npm exec qm -- check --live

# 查看运行状态
npm exec qm -- status

# 查看日志
npm exec qm -- logs core -f

# 沙盒镜像构建（本地验证）
npm exec qm -- sandbox build

# 沙盒镜像发布到 OCI registry
npm exec qm -- sandbox publish --app <registry>/<repo> --tag <tag>

# 下线服务
npm exec qm -- down

# 回滚（需指定 revision 或 commit SHA）
npm exec qm -- rollback --to <revision-or-sha>

环境变量配置（.env）

# 必须
HARNESS=pi                       # 使用的 harness（pi|opencode|codex|claude-code）
HARNESS_SECURITY_POSTURE=auto   # 安全态势（strict|auto|dangerous）
ORG_ID=acme
PORT=8080

# 至少配置一个模型商
#ANTHROPIC_API_KEY=sk-ant-...
#OPENAI_API_KEY=sk-...
#OPENROUTER_API_KEY=sk-or-...

# Slack 集成（可选）
#SLACK_BOT_TOKEN=xoxb-...
#SLACK_APP_TOKEN=xapp-...

# 速率与预算控制
RATE_LIMIT_PER_WINDOW=60
RATE_LIMIT_WINDOW_MS=60000
BUDGET_USD_PER_WINDOW=25
ORG_BUDGET_USD_PER_WINDOW=100
BUDGET_WINDOW_MS=86400000

版本标注：当前 npm 最新版为 @yc-software/qm@latest（版本号请以 npm view @yc-software/qm version 查询结果为准，文档未标明精确版本号）。

私有 fork 模式（企业定制）

对于需要同时修改核心代码和定制化的组织，QM 推荐保持私有 fork：

# 创建私有 fork（不使用 GitHub Fork 按钮）
gh repo create <org>/qm-private --private
git clone --bare git@github.com:yc-software/qm qm-seed.git
git -C qm-seed.git push --mirror git@github.com:<org>/qm-private
rm -rf qm-seed.git
git clone git@github.com:<org>/qm-private
git -C qm-private remote add upstream git@github.com:yc-software/qm

企业定制内容放在 deploy/layers/<org>/ 下，不会同步回上游，上游更新通过 update-qm skill 合并。

典型适用场景

  1. 公司级 AI 编程助手：员工各自拥有独立 scope，同时可以在共享 Slack 频道中与同一个 agent 协作处理跨团队任务。
  2. 非技术团队的 AI 接入：通过 Slack 插件，非工程师也可以用自然语言调度 agent 完成文档、数据查询、内部工具操作。
  3. 内部工具/知识库机器人：基于 QM 的 skill 体系构建垂直领域 agent（如客服、合规查询），admin 可统一管控权限和可见范围。
  4. 安全敏感环境：通过 Strict 态势强制人工审批每一步操作，适合金融、医疗等需要审计的行业。

坑与注意

  1. GitHub Fork 不可用：QM 文档明确指出，GitHub Fork 功能创建的派生仓库无法设为私有（fork 公开仓库无法私有化），且共享对象存储。必须使用普通 clone 方式建立私有 fork。
  2. 切换部署平台需重新初始化：--target 参数在初始化时确定，更换平台（Fly → AWS）需新建目录，不能原地切换。
  3. --yes 是必须的：qm up 命令需要显式 --yes 参数才能执行实际变更，否则只做 dry-run。
  4. 沙盒镜像标签规则：发布到 OCI registry 时，标签影响运行时拉取行为，建议使用 digest pinning（--tag 指定），不要依赖 :latest。
  5. Strict 态势下 turn enders 仍自动放行：「无副作用的结束 turn」两个工具不受审批拦截影响，别误以为所有操作都需要审批。
  6. 上游合并需手动触发：update-qm skill 只是合并工具，合并后仍需人工 review diff 和截图（尤其涉及组织标识的内容）。
  7. PostgreSQL 是必需组件：核心依赖 Postgres 做 session 和 queue 管理，本地开发没有内置 SQLite 或其他替代方案。

与同类对比

特性 QM GitHub Copilot Cursor Claude Code
多人多 scope 隔离 ✅ ❌ ❌ ❌
Slack 原生集成 ✅（官方插件） ❌ ❌ ❌
多 harness 可切换 ✅（Pi/OpenCode/Codex/Claude） ❌ ❌ ❌
企业级安全态势 ✅（Strict/Auto/Dangerous） 部分（企业策略） ❌ ❌
私有 fork + 上游同步 ✅ ❌ ❌ ❌
自定义 skill 体系 ✅ ❌ 部分（Rules） 部分
开源 ✅ MIT ❌ ❌ ❌
自建部署 ✅（Docker/Fly/AWS） ❌ ❌ ❌

核心差异：QM 是目前唯一将「多人 scope 隔离 + Slack 原生 + 多 harness 可切换」三者合一的开源项目，适合需要 AI 编程能力公司化部署的团队。

一句话推荐结论

如果你需要在公司内部署 AI 编程助手、让多个团队共享 AI 能力而不牺牲数据隔离，同时希望保留切换模型商的灵活性——QM 是目前开源生态里设计最完整、架构最干净的解法。

最小可跑命令（本地 Docker 模式）

# 环境准备
node -v   # 建议 v20+
docker -v
npm -v

# 初始化项目（目标平台选 docker 用于本地测试）
mkdir qm-test && cd qm-test
npm exec --yes --package=@yc-software/qm@latest -- qm init . --org test-org --target docker
npm install

# 填入至少一个模型 API key（.env 文件）
# 编辑 .env:
#   ANTHROPIC_API_KEY=sk-ant-...
#   HARNESS=pi
#   HARNESS_SECURITY_POSTURE=auto

# 配置校验
npm exec qm -- check

# 本地启动
npm exec qm -- up --yes

# 验证服务运行
npm exec qm -- status

硬件/CUDA/模型版本说明：本地 Docker 模式不要求 GPU；生产部署（Fly/AWS）时 agent 在沙盒中运行，默认不要求 GPU，Harness（Pi/OpenCode/Claude Code）的实际模型调用通过 API 进行，模型版本由对应的 API key 决定。

来源

  • 仓库 README：https://github.com/yc-software/qm
  • 快速入门文档：https://github.com/yc-software/qm/blob/main/docs/getting-started.md
  • CLI 使用说明：https://github.com/yc-software/qm/blob/main/cli/README.md
  • 环境变量示例：https://raw.githubusercontent.com/yc-software/qm/main/.env.example
  • 部署文档：https://github.com/yc-software/qm/blob/main/deployment.md
  • 原始 commit：https://github.com/yc-software/qm/commit/main（本仓库为开源项目，未在文档中找到特定「入门 commit」的固定链接；最新内容以 main 分支为准）