BuildBeat

BuildBeat

**简体中文** | [English](README.en.md)

**会话随时换，项目接着干。** 上下文存进文件，协作围绕 Git，工作持续推进。

BuildBeat 是以 Git 和项目文件为基础的 AI 交付工作流，面向人和 AI 会话。目标、计划、决定与交付记录保存在项目里，换模型、换工具、换会话，或换一个人接手，都有继续工作的依据。Loop 推进实现、验证、审查与修复；进度和证据由内核从 Git 与真实命令回读，不靠会话自述；关键决定由人掌握。

[使用指南](docs/v2/guide/README.md) · [跨会话接续](docs/v2/guide/11-session-handoff.md) · [npm](https://www.npmjs.com/package/@haiyangbg/buildbeat) · [CI](https://github.com/HaiYangBG1/BuildBeat/actions/workflows/ci.yml) · [MIT](LICENSE)

告别祖传上下文

不用再抱着一个越来越长的“祖传会话”不放。上下文满了，开个新会话；想换模型或工具，从项目记录接着做；今天交给同事，接手的人也能从文件了解进度和下一步。目标、约束、计划、决定和交付记录都应落在文件系统中，新会话不必依赖旧聊天历史来判断下一步。

下面是已配置项目的**使用情景示意**，不是一次实测运行记录：

时刻	你说什么	会话做什么
会话 A：开始	“给导出功能加日期筛选，先定计划。”	读取项目约束，把目标与计划写入 Work；接受后启动执行
准备离开	“把决定和未完成事项落盘，我要关闭这个会话。”	补齐项目记录，核对运行状态与未提交改动，说明下一步
新会话接手	“读取项目的 BuildBeat 入口，接着做日期筛选。”	读取 Work、Git 与运行台账，查清已完成、未验证、待批和阻塞
继续推进	“按当前已接受的计划继续。”	根据实况继续执行、处理恢复或等待决定，带证据停在合并决定前

新会话可以由自己打开，也可以交给另一位有项目权限的人；换人或换机器时，同步记录与候选，并核对原 Run 的执行环境。

**关键上下文落盘后，旧聊天可以关闭或删除。** 未保存的讨论不会自动变成项目记忆；删除聊天时应保留项目、候选分支和所需运行文件。具体步骤见 [跨会话接续](docs/v2/guide/11-session-handoff.md)。

上下文就在项目里

Git 管理需要长期保留的项目事实；本机文件保存运行中的状态。BuildBeat 读取这些事实来回答“做到哪了”，而不是让每个会话重新写一份进度猜测。

文件与目录	保存什么	怎样使用
AGENTS.md、项目规范与契约	项目入口、约束、角色和写入边界	新会话从入口读取，按任务深入相关文件
delivery/work//	目标、计划、配置、决定、审查裁决与终态运行记录	纳入 Git，作为同一项工作的接续依据
.buildbeat/runtime/	在途事件、检查点、锁与原始日志	留在本机，不进 Git；恢复活动 Run 时需要
.buildbeat/worktrees/	Run 的隔离工作树	保留候选代码与现场，不作为聊天缓存清理

落在文件系统不等于每个文件都应该提交到 Git。秘密留在受保护的本地环境中；终态记录保存证据摘要和引用，原始日志需要按项目要求另行保留。详见 [证据指南](docs/v2/guide/06-evidence-guide.md)。

换个方式，继续同一项工作

继续工作所需的上下文由项目文件承载。装载了 BuildBeat 的新会话可以读取同一份目标、决定和当前状态；负责执行的 Worker 通过命令接入，模型选择与鉴权由所用 AI 工具处理。

• 跨会话：关闭旧聊天，用干净上下文接续同一个 Work。
• 跨工具与模型：按目标工具的方式加载 Skill、配置执行命令和输出合同，复用项目记录。
• 跨人接手：有项目访问权限的人，同步上下文、候选与必要证据后，可以在职责和授权范围内继续；有效的既有决定继续保留。
• 跨时间与地点：同步已提交的项目文件后，可在准备好环境的另一台机器重新接手；活动 Run 的运行状态和工作树不会随普通 Git clone 自动迁移。

**随时随地接手的基础，是记录可达、环境