QM 源码分支同步与包部署升级指南:基于 update-qm 技能的完整实操手册

原创2026-09-21 19:35:591,636 阅读
文章标签:人工智能AI AgentAgent 框架Agent 编排多智能体工具调用MCP ClientsAgent 沙箱Agent 记忆后端前端桌面应用认证鉴权企业应用LLMOps

QM 源码分支同步与包部署升级指南:基于 update-qm 技能的完整实操手册

本文基于 QM 仓库内置的 Codex 技能 .codex/skills/update-qm/SKILL.md 展开。QM 是一个多人在线 Agent 协作框架("Multiplayer agent harness for work"),部署形态分为**源码分支(source fork)与包部署(package deployment)**两种。本文先帮你判断当前仓库属于哪种形态,再分别给出同步上游、解决冲突、验证、开 PR 的完整流程,并补充源码级佐证,让你在 "update qm"、"sync from upstream"、"pull in the latest qm" 这类请求到来时,能安全、规范地完成升级而不破坏本地定制。

前置判断:先分清源码分支还是包部署

在执行任何更新操作之前,第一步是判断当前检出(checkout)的形态:

  • 运行 git remote -v 并检查文件与提交历史。
  • 如果 origin 指向 yc-software/qm,说明这是上游本身,不是下游同步目标。
  • origin 不同不足以证明这是源码分支。真正的源码分支拥有 QM 源码树和与上游共享的历史;包部署则只有部署配置和一个固定版本的 @yc-software/qm 依赖。
  • 如果源码分支中嵌套了部署目录(deploy/layers/<org>/),除非请求明确针对某个嵌套的包版本,否则应更新源码本身。

QM 官方对这两种形态的定义见 README.md:"Config, tools, skills, and services" 使用部署仓库(包部署,无需源码副本);"Changes to QM itself" 则保留自己的源码分支,可以任意修改 core,是否把改动贡献回上游完全可选。

包部署升级:精确安装版本并全面校验

在主题分支上安装指定版本

包部署没有上游源码历史需要合并,操作路径是在主题分支上精确安装指定版本:

git switch -c qm-update-<yyyy-mm-dd>
npm install --save-exact @yc-software/qm@<version>

如果没有指定版本,先解析当前发布的最新版本再安装。--save-exact 保证 package.json 与 lockfile 锁定精确版本,避免漂移。

审查三类变更

安装后需要逐一审查:

  1. 包与 lockfile 的 diff:确认依赖树的实际变化。
  2. 部署契约(contract)变更:QM 的部署目录遵循一个显式版本契约。从源码看,cli/src/config.ts 定义了 export const CONTRACT_VERSION = 1 as const,配置文件中必须带有 "contract": 1 字段(见 config.ts)。加载配置时,config.ts 会严格校验:如果 contract 是整数但不是当前支持值,会直接抛出 unsupported contract major <contract>; this CLI supports contract <CONTRACT_VERSION>。同步升级可能抬高契约主版本号,旧 CLI 会直接拒绝旧的 layer 配置——这正是升级后必须用新版 CLI 重新校验 layer 的原因。
  3. 镜像覆盖(image overrides):检查 imageOverrides 配置。包升级不会自动刷新运行镜像,旧的 image overrides 可能让工作负载继续停留在旧镜像上。

生成物不会自动刷新:单独目录比对脚手架

包更新不会刷新已生成的 runbook、skills 或 vendored Terraform。正确做法是:

  1. 在独立的临时目录中安装该版本的脚手架(scaffold);
  2. 与现有部署目录逐项比对;
  3. 只合并必要变更,不要重新初始化或覆盖现有部署目录。

用安装版 CLI 做三道校验并开 PR

npm exec qm -- check --config <deployment-dir>/qm.config.jsonc
npm exec qm -- doctor --config <deployment-dir>/qm.config.jsonc
npm exec qm -- plan --config <deployment-dir>/qm.config.jsonc
  • 这三个命令(check、doctor、plan)来自安装的 CLI 包;包部署的完整工作流以 deployment.md 为权威依据,它在初始化时被 qm init 物化进每个组织的部署目录。
  • 校验通过后在部署仓库打开 PR。
  • 只在用户请求的范围内部署,遵循其部署 runbook 与 live checks(如 qm check --live)。
  • 不要给包部署添加上游源码 remote,也不要往包部署里合并源码。

为什么不能用源码检出里的 CLI

源码检出(source checkout)里 npm exec qm 不可用:工作区符号链接指向 cli/,而 cli/ 尚未构建。因此源码检出必须直接运行 node cli/bin/qm.ts(入口见 cli/bin/qm.ts,它调用 src/cli.ts 的 main)。这也解释了为什么包部署要用 npm exec qm、源码分支要用 node cli/bin/qm.ts,二者不能混用。

源码分支同步:Merge,绝不 Rebase

准备上游 remote

检查 upstream remote 是否指向 yc-software/qm,缺失时添加:

git remote add upstream git@github.com:yc-software/qm

合并前必须先确认与上游存在共享历史。永远不要把下游历史合并进上游。所有 gh 命令都要带 --repo 参数。注意:示例假设默认分支是 main,如果分支刻意用了其他名字,必须相应调整。

镜像种子仓库的陷阱

如果镜像种子(mirror-seeded)仓库的默认分支是一条过期的 feature 分支,同步前要先确定真正的基准分支:不要静默合并进过期分支,也不要删除已有 refs。README 的源码分支创建流程(README.md)明确要求只种子 main 并显式设置默认分支:

gh repo create <org>/qm-private --private
git clone --single-branch --branch main --no-tags git@github.com:yc-software/qm qm-private
git -C qm-private remote rename origin upstream
git -C qm-private remote add origin git@github.com:<org>/qm-private
git -C qm-private push -u origin main
gh repo edit <org>/qm-private --default-branch main

禁止用 git push --mirror 种子或更新源码分支:它会复制无关分支和标签、让默认分支选择隐式化,还可能删除目标仓库独有的 refs。

合并流程与提交范围记录

origin/main 是已发布的、部署和其他 clone 都在跟踪的历史。把它 rebase 到上游会重写这些提交,所以永远用 merge:

git switch main
git pull --ff-only origin main
git fetch upstream
git switch -c codex/sync-upstream-<yyyy-mm-dd>
git log --oneline main..upstream/main
git merge upstream/main

关键要点:

  • 先记录提交范围(main..upstream/main),PR 描述要能陈述它;
  • 如果 merge 报告 "Already up to date",删除分支并如实报告,而不是开一个空 PR;
  • 合并提交保留上游祖先,后续同步才不会重复处理已集成的历史。

解决冲突:保护本地定制,整合上游修复

冲突是预期维护,不是政策违规

  • 同时阅读冲突两侧的代码,以及解释本地定制的本地提交。
  • 保留有意的本地行为,同时整合上游修复。core 冲突是预期的维护工作,不是政策违规。
  • 部署数据尽量放在 layer 或独立的私有部署仓库中(见 deploy/layers/README.md)。
  • 不要仅仅因为某个 core 修改是组织特有的就丢弃它,也不要坚持要求它必须贡献给上游。

记录与请示

  • 在同步 PR 中记录:冲突点、解决方式、剩余的本地分歧(divergence)。
  • 当无法从代码、测试或历史中恢复意图时,先问操作者再选择行为。
  • 审查继承的 CI 与发布变更:为分支自己的账号和镜像仓库做适配,不要盲目启用上游工作流。

最忌:静默丢弃上游改动

禁止通过整体删除上游一侧来平息冲突。那会让 core 静默偏离上游,且分歧会在下一次同步时以更大的冲突卷土重来。

开 PR 前的验证:测试、类型检查与 lint

先装锁定依赖,再跑本地检查

从合并范围和冲突解决方式确定受影响测试,本地运行它们,外加类型检查和 lint;CLI 或部署契约变更还要包含 CLI 测试。无法确定影响范围时才跑完整本地套件,否则交给 CI:

npm ci
npm run typecheck
npm run lint

这两个脚本在 package.json 中定义:typecheck 执行 tsc --noEmit,lint 执行 eslint .(另有 typecheck:contract 用 tsconfig.contract.json 单独校验部署契约类型)。

用仓库内 CLI 检查每个组织 layer

同步可能抬高部署契约主版本,旧 CLI 会拒绝为旧契约编写的 layer 配置(源码依据:cli/src/config.ts 中的 unsupported contract major 错误)。因此要用仓库内 CLI 检查每个组织 layer:

node cli/bin/qm.ts check --config deploy/layers/<org>/qm.config.jsonc

检出之外的部署替换为各自的配置路径。如果配置报告不支持的契约主版本,适配它本身就是同步工作的一部分。

实机验证与镜像说明

  • 按 AGENTS.md 的要求("Verify non-trivial behavior changes in a live dev instance before opening a PR"),非平凡的改动要在 live dev instance 中验证。可用 npm run dev-instance:web / dev-instance:slack / dev-instance:both 启动(见 package.json 与 README.md)。
  • 合并源码并不会更新已发布的运行镜像。生产服务构建必须对本检出使用 --build-from(或刻意发布自定义镜像)。README 的源码部署流程给出了完整命令(README.md):
node cli/bin/qm.ts check --config <deployment-dir>/qm.config.jsonc
node cli/bin/qm.ts plan --config <deployment-dir>/qm.config.jsonc --build-from .
node cli/bin/qm.ts up --config <deployment-dir>/qm.config.jsonc --build-from .
node cli/bin/qm.ts check --config <deployment-dir>/qm.config.jsonc --live

打开同步 PR:--repo 参数是安全底线

git push -u origin codex/sync-upstream-<yyyy-mm-dd>
gh pr create --repo <source-fork> --base main \
  --title "Sync upstream qm through <short-sha>" \
  --body-file .generated/sync-body.md

为什么每个 gh 命令都要带 --repo

在私有分支中,不带 --repo 时 gh 会从 clone 的 remotes 里选一个基仓库,可能选中 upstream:于是同步 PR 被开到了 qm 上游,而 gh pr edit 1 会覆盖源仓库里的 1 号 PR。同样的风险适用于 gh pr view、gh pr list、gh issue。这是本技能反复强调的安全底线。

PR 描述应包含

  • 合并的上游提交范围(main..upstream/main);
  • 任何 deploy/layers/ 之外发生冲突的文件,以及解决方式;
  • 上述各项检查的结果。

落地方式:保住上游祖先

  • 授权落地源码同步 PR 时,用合并提交(gh pr merge --repo <source-fork> <pr> --merge)或保留祖先的 fast-forward。
  • 绝不 squash 或 rebase 源码同步 PR——即使仓库日常发布用 squash 也不行:那会丢失上游合并,导致后续同步反复处理已集成的历史。
  • 如果仓库设置禁止 merge commit,先解决该策略问题,不要退而求其次用 squash。
  • 包依赖 PR 可以遵循部署仓库的常规合并策略。
  • 如果私有分支从 main 部署,合并这个 PR 会把上游变更直接发布到生产——在有人能盯着的时候再合并。

CI 与密钥的现实

源码分支会在自己的账号里运行启用的 CI 工作流。同步新增或修改 CI,会改变下一个 PR 运行的内容;工作流需要分支从未收到的密钥时,会一直失败直到补齐。回顾 README 的忠告(README.md):在启用 Actions 或添加凭据前,审查继承的工作流,为自己的包与镜像仓库禁用或适配上游的 release / publishing 工作流。

红线清单:Never do these

  1. git push --mirror 种子或更新源码分支——会复制无关分支和标签、让默认分支选择隐式化、删除目标独有 refs;只种子 main 并显式设置默认分支。
  2. 把含组织提交的分支推给上游——upstream-pr 技能(.codex/skills/upstream-pr/SKILL.md)规定只从 upstream/main 新切的干净分支推送上游,且做过脱敏。
  3. 把 main rebase 到 upstream/main,或 force-push 私有分支的 main。
  4. 整体删除上游一侧来平息冲突——会静默偏离 core,并在下次同步以更大冲突回归。

与相邻技能的分工

  • update-qm(本文主题):把上游拉进源码分支,或升级包部署依赖。同步方向是"拉入"。
  • upstream-pr(.codex/skills/upstream-pr/SKILL.md):仅当你想把本地改动贡献回上游时使用;它从 upstream/main 切干净分支、逐提交扫描 deploy/layers/ 路径与组织标识符、核对每个二进制,再从上游视角写 PR 描述,防止泄露私有部署数据。两者方向相反、互为补充:上游 PR 合并后,再通过 update-qm 把成果带回下游,并在保留本地实现的前提下与新版本调和。
  • deploy-qm(.codex/skills/deploy-qm/SKILL.md):面向包部署的初始化与上线流程,使用安装的 @yc-software/qm 依赖,不需要源码检出。

三者构成 QM 定制化运维的完整闭环:fork → 定制 → 同步 →(可选)回馈。

总结

  • 先分类,后动手:源码分支合并上游并保留本地定制;包部署精确升级依赖并校验契约与镜像。
  • merge 优先于 rebase:origin/main 是已发布历史,合并保留祖先,让后续同步可追踪。
  • 契约与镜像要盯紧:部署契约主版本(cli/src/config.ts 的 CONTRACT_VERSION = 1)抬高会让旧 CLI 拒收旧配置;--build-from 才能让修改的源码真正进入运行时镜像。
  • --repo 常驻:私有分支上每个 gh 命令都显式指定仓库,避免 PR 误开上游或覆盖编号。
  • 红线不可越:不 mirror、不 rebase main、不把含组织历史的分支推上游、不整体删除上游侧。
登录后查看全文
qm