qm

用途

QM 是一个面向工作的多人智能体运行框架（multiplayer agent harness），可在 Slack 和 Web 两个界面中使用。它专为初创公司设计：大多数智能体被当作个人助理构建，难以服务整个公司；QM 则让每位员工拥有完全隔离的自己的智能体工作空间，同时支持在频道、群组消息和项目中进行协作。

主要能力

• 个人与共享作用域：每个人和每个房间（频道/项目）都有自己作用域内的记忆、文件、密钥链视图、权限、定时任务、Web 应用和持久沙箱。员工可以个性化自己的智能体，同时在 Slack 频道和项目中协同使用。
• Slack 与 Web 统一身份：同一套身份和配置在 Slack 与 Web 应用之间保持一致。
• 管理控制：设置组织级配置、安全与共享姿态，选择可用的运行框架和模型。
• Web 应用：可创建自定义内部应用并发布给合适的人员。
• 共享技能：技能归作用域所有，可通过授权共享，经管理员审批后可推广至整个组织，并支持从 git 仓库导入技能包。
• 后台工作：定时任务（crons）、监视（watches）和入站 webhook 在你离开时也能持续工作。
• 可执行的任务示例：联合搜索内部笔记、邮件、文档、数据库和网络；构建并发布内部应用；学习你的写作风格并按计划分类收件箱（含标签和回复草稿）；在现有仓库中工作（运行测试、提交 PR、监控 CI、查看系统日志）；在共享频道中跟踪项目并发布更新与跟进。

使用方式

部署流程：创建一个依赖 @yc-software/qm 的组织自有部署仓库。初始化会为一个智能体生成部署技能，并逐步引导完成基础设施、Web 登录、连接器凭据、可选的 Slack 访问、部署和实时验证，无需检出源码。每次部署都运行在运营方自己的云账号中；初始化不会生成或启用部署 CI，该仓库也没有生产部署工作流。

快速启动命令：

• 告诉你的编码智能体：“Let's deploy https://github.com/yc-software/qm”，它会遵循仓库中的部署指南。
• 也可尝试第三方托管版本。

开发与运行：

• 从源码检出后，用 npm ci 安装依赖，并使用仓库内 CLI。
• 为持久化，设置 DATABASE_URL 和 SESSION_STORE=postgres。
• 针对真实模型和真实 Postgres 测试分支：Web/管理端运行 npm run dev-instance:web，Slack 运行 npm run dev-instance:slack，两者一起测试运行 npm run dev-instance:both。
• 不带参数的 npm run dev-instance 对新实例默认使用 web，重载时保留当前界面。
• 修改 CLI 本身时，需使用该检出的 CLI 并显式指定 --build-from，否则正常部署路径会选择已发布镜像。

架构：每一轮对话都经过中央核心（core），核心可使用多种模型和运行框架生成响应。Postgres 持久层保存用户数据、会话历史和其他持久状态。智能体拥有一个固定的小型工具面；其中一个工具是 execute，在作用域自己的隔离沙箱（持久计算机，已安装工具保持存在）中运行命令。Web UI 和管理面板共用一个服务；门户和可选的内置认证代理共用另一个服务。这些模块通过核心的 HTTP API 与其通信。Slack 是一个可选的过程内插件，由核心通过直接服务客户端启动和监督。

适用场景

• 初创公司或组织内为每位员工提供隔离的智能体工作空间
• 在 Slack 频道和项目中进行多人协作的智能体使用
• 需要管理员统一控制模型、运行框架、安全与共享设置的组织
• 希望自托管在自己的云账号中、使用自己的模型和密钥的团队

安全与密钥模型

QM 的做法与 OpenCode、Codex、Claude Code 等本地编码智能体一致：智能体作为所服务的人行事，使用其凭据和权限，一切操作都被审计。组织选择一种安全姿态，更窄的作用域只能收紧它：

• Strict：每个运行框架工具调用都暂停等待人工批准，仅两个无副作用的回合结束器除外。
• Auto（默认）：阻止私有网络访问。
• Dangerous：无工具批准门，内容筛查仅观察。

内容筛查是部署设置，securityScreen.mode 可选 off（默认）、observe 或 enforce，securityScreen.classifier 选择内置模型或外部代理。开启后，它在每种姿态下都会对外部内容分类。observe 仅在审计日志中记录判定；enforce 将标记内容隔离并等待发布批准，Dangerous 下筛查上限为 observe。

预先声明的命令策略（批准规则和硬性拒绝，如递归删除或破坏性 SQL）在所有姿态下均适用，包括 Dangerous。

共享姿态独立：

• Isolated（默认）：资源保留在其作用域内，除非明确共享。
• Open：在实时认证的内部人类回合中，发言者选择加入的个人文件、工件、技能和记忆可在选择加入的共享房间中被读取。

SECURITY.md 包含威胁模型、运营方假设和已知限制。

限制

• 未设置 DATABASE_URL 和 SESSION_STORE=postgres 时，会话仅存于进程内存，重启即丢失。
• 初始化不生成或启用部署 CI；该仓库没有生产部署工作流。
• 修改源码后，若不使用 --build-from，正常部署路径仍会选择已发布镜像，编辑源码不会改变已部署运行时。
• 使用 git push --mirror 作为种子会复制无关的上游分支和标签，隐式保留默认分支选择，并可能在后续推送时删除目标独有引用，因此不推荐。
• 公开仓库的 GitHub Fork 无法设为私有；私有工作应放在该网络之外。
• 贡献以人类撰写的文本形式提交，而非代码。

定制

• 配置、工具、技能和服务：使用上述部署仓库，它固定 @yc-software/qm 版本并使用该版本的运行时镜像，无需复制源码。
• 修改 QM 本身：保留自己的源码分支（公开或私有），可修改核心的任何部分，包括运行时、插件、CLI、文档和 CI。将更改贡献回上游是可选的。

创建私有源码分支：创建一个独立的私有仓库，位于 GitHub 的 fork 网络之外，仅播种 main 并显式设为默认分支。不要用 git push --mirror 播种。上游远程提供源码更新，而不会将这些引用复制到你的仓库。

源码分支中，将部署配置、工具、技能、插件镜像和基础设施保留在私有的 deploy/layers/<org>/ 中，或当源码公开时保留在单独的私有部署仓库中。切勿提交密钥。参见 deploy/layers/README.md 了解初始化和布局。

保持更新：源码分支使用 update-qm 合并上游更改，同时保留有意的本地行为。合并同步 PR 时保持合并谱系完整，切勿压缩或变基。冲突是预期的维护工作，而非丢弃定制的理由。仅在希望贡献通用更改时使用 upstream-pr。

包部署：升级确切的 @yc-software/qm 依赖和锁文件，审查合约变更和生成的资产，然后验证并部署。没有上游源码历史需要合并。

文档与许可

• docs/getting-started.md：首次运行，端到端
• cli/README.md：qm CLI 和部署目录合约
• docs/deploy-directory.md：完整的部署目录
• docs/principal-links.md：一个人多个登录：关联主体
• docs/porter.md：在 Porter 上运行 qm
• docs/superserve.md：使用 Superserve 作为智能体沙箱
• .env.example：每个配置项，就地文档化
• docs/swarms.md：持久智能体池、作用域消息和空白 Modal worker
• docs/model-gateway.md：通过网关发现和路由模型
• plugins/：各界面（Slack、Web UI、管理端、门户）

除另有说明外，QM 采用 MIT 许可。