handoffgen

handoffgen

一个 Agent 在任务中途停止后，痕迹会散落在三个地方：刚刚提交的 commit、仍在等待审核的 pull request，以及过程中记录的 TODO。接手工作的下一个 Agent 必须先还原这些痕迹，才能安全地继续。handoffgen 会将你提供的信息整理成一份冷启动简报：一份简短的 Markdown 文档，新 Agent 从头读完后即可正确开始工作，无需从零重新推导当前状态。

你提供事实。近期 commit 按输入顺序呈现，每个哈希都用反引号括起，并紧邻其主题。未关闭的 pull request 也按输入顺序排列；任何标记为受阻的 pull request 都会带有醒目的 [blocked] 标记，避免有人浪费时间重新发现阻塞问题。TODO 按优先级分组——先列出所有高优先级项目，再列出普通项目，最后列出低优先级项目；每组内保留你提供的顺序。高优先级项目会加上 [high] 前缀；如果某个项目注明了所在位置（例如文件路径），则会在其文本后面的括号中标出该来源。如果你添加了自由文本上下文备注，它会原样置于简报开头，与你写下的内容完全一致；空白或仅包含空格的备注视为未提供备注。同一规则也用于判断 TODO 是否显示来源。

空输入不会被默默忽略。没有 commit 时，简报会在标题下写明 "No commits supplied."；没有 pull request 或 TODO 时，也会分别显示对应的提示行。除 Markdown 外，结果还会包含相关计数：commit 数、未关闭的 pull request 数、其中受阻的数量、TODO 数，以及高优先级 TODO 数。不会获取、执行或推断任何信息——不会读取代码仓库，不会查询托管服务，也不会猜测状态。简报只包含你提供的事实，并按便于新接手者阅读的方式排列。

格式错误的输入——缺少 commits、open_prs 或 todos，或这些字段不是数组；某个项目不是对象；哈希、主题、标题或 TODO 文本为空或不是字符串；pull request 编号不是大于等于 1 的整数；blocked 不是布尔值；source 或 context 不是字符串；或 priority 不在 "high"、"normal" 和 "low" 之中——都会导致验证错误，并指出出错路径，且不会返回部分结果。未知的额外字段会被忽略，包括项目内的字段。未提供 priority 时按 "normal" 处理，未提供 blocked 时按 false 处理。

命令行界面

npx @reneturcios/handoffgen build --input args.json
npx @reneturcios/handoffgen --version

args.json 包含完整的参数对象：

{
  "context": "Parser is stable; cache work is mid-flight.",
  "commits": [
    { "hash": "abc1234", "subject": "Add parser" },
    { "hash": "def5678", "subject": "Fix flaky test" }
  ],
  "open_prs": [
    { "number": 12, "title": "Wire up cache" },
    { "number": 13, "title": "Bump deps", "blocked": true }
  ],
  "todos": [
    {
      "text": "Write migration notes",
      "source": "docs/migration.md",
      "priority": "high"
    },
    { "text": "Tidy README" },
    { "text": "Polish icons", "priority": "low" }
  ]
}

结果以 JSON 格式打印：

{
  "brief": "# Handoff brief\n\n## Context\nParser is stable; cache work is mid-flight.\n\n## Recent commits\n- `abc1234` Add parser\n- `def5678` Fix flaky test\n\n## Open pull requests\n- #12 Wire up cache\n- #13 Bump deps [blocked]\n\n## TODOs\n- [high] Write migration notes (docs/migration.md)\n- Tidy README\n- Polish icons",
  "counts": {
    "commits": 2,
    "open_prs": 2,
    "blocked_prs": 1,
    "todos": 3,
    "high_priority_todos": 1
  }
}

退出码：成功时为 0，运行时错误时为 1（包括输入文件无法读取、输入文件无效或输入无效），用法错误时为 2。

MCP 服务

npx -y @reneturcios/handoffgen mcp

MCP 客户端配置：

{
  "mcpServers": {
    "handoffgen": {
      "command": "npx",
      "args": ["-y", "@reneturcios/handoffgen", "mcp"]
    }
  }
}

工具

• build_handoff_brief — 根据调用方提供的 commit、未关闭的 pull request 和 TODO 项，为下一个 Agent 构建冷启动交接简报。

  • commits（数组，必需，可以为空）— 按输入顺序排列的近期 commit；每个项目的格式为 {hash, subject}，两个字符串都不能为空
  • open_prs（数组，必需，可以为空）— 按输入顺序排列的未关闭 pull request；每个项目的格式为 {number, title, blocked?}，其中 number 是大于等于 1 的整数，title 不能为空，且如果提供 blocked，其值必须为布尔值
  • todos（数组，必需，可以为空）— 尚未完成的 TODO 项；每个项目的格式为 {text, source?, priority?}，其中 text 不能为空；如果提供 source，其值必须为字符串；如果提供 priority，其值必须为 "high"、"normal" 或 "low"（未提供时按 "normal" 处理）
  • context（字符串，可选）— 当前状态的自由文本备注；如果视为已提供，则会原样包含

  返回 {brief, counts}，其中 counts 的格式为 {commits, open_prs, blocked_prs, todos, high_priority_todos}。

Docker

docker run -i ghcr.io/cloudcorprecords/handoffgen
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/handoffgen build --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios