@haiyangbg/buildbeat 4.2.2 → 4.2.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +8 -0
- package/README.en.md +105 -55
- package/README.md +105 -55
- package/docs/CAPABILITY-MATRIX.md +1 -1
- package/docs/RELEASING.md +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,8 +2,16 @@
|
|
|
2
2
|
|
|
3
3
|
> 本项目吃自己的狗粮(红线④:必更 CHANGELOG)。格式循 Keep a Changelog,倒序。
|
|
4
4
|
|
|
5
|
+
## v4.2.3 — 2026-10-11（补丁：README 改成「装好后跟 AI 说话」）
|
|
6
|
+
|
|
7
|
+
- README (zh/en) rewritten in plain words for people who hand the work to an AI (PRs #84–#87). The opening states the one pain (switch session, tool, computer or person and you explain everything again) and what BuildBeat keeps in the project and Git. Get started is a single prompt to paste into the AI coding tool: it checks the environment, installs or upgrades the runtime (with the 3.x rule), reads `SKILL.md` and the quickstart from the npm package and puts the templates in place; the Claude Code plugin sits in a collapsed block. Examples are short "you / AI" exchanges by situation (first time, starting a work, new session/computer/person, one more change, your own fix, stuck on the environment, several repositories), with the real `status` output collapsed. New sections explain what a work is (the smallest unit BuildBeat keeps records in) and the project's folder layout, including which folders travel with Git. The three promises, the boundaries section and most links to guides are gone; the facts that mattered are written into the page.
|
|
8
|
+
- `check:docs` requires only the quickstart, contributing and license links from the README and no longer requires the product-boundary or "end-to-end work package" phrases there; the facts stay in the capability matrix.
|
|
9
|
+
- GitHub About is bilingual and plain, with the npm page as homepage and `claude-code-plugin` / `code-review` topics.
|
|
10
|
+
|
|
5
11
|
## v4.2.2 — 2026-10-07（补丁：README 重新设计）
|
|
6
12
|
|
|
13
|
+
> **发布状态**：`@haiyangbg/buildbeat@4.2.2` 已于 2026-10-07 从 `main`（release PR #81，merge commit `3a43ae3`，tag `v4.2.2`）经 OIDC Trusted Publishing 发布到 dist-tag **`latest`**（run 37637179739，publish 与 verify 双 job 一次 success；所有者授权「合并并发 4.2.2」）。独立回读（直连 npmjs.org）：`latest` = 4.2.2、`dist.integrity` 与本地用 Node 24 + npm 11.19.0 打的候选逐字一致、注册表 tarball 解压后与候选逐字节相同、SLSA v1 provenance、隔离安装 `--version` = 4.2.2、裸调用零写入、`npm audit signatures` 通过；GitHub Release v4.2.2 标 Latest；证据见 [`docs/releases/V4.2.2-RELEASE-EVIDENCE-2026-10-07.md`](docs/releases/V4.2.2-RELEASE-EVIDENCE-2026-10-07.md)。同日所有者本人经 npm 两步验证把 dist-tag `next` 从 4.2.0 挪到 4.2.2；直连 npmjs.org 回读 `next` = `latest` = 4.2.2。
|
|
14
|
+
|
|
7
15
|
- README (zh/en) redesigned for reading: a hero picture, the name's meaning (every step is a note the agent plays; the played score stays in Git), a delivery-loop diagram in light and dark with a stacked layout for phones, the three promises as short sections, a real `status` excerpt at the merge decision, and which records travel with Git and which stay on this machine. Pictures live in `docs/assets/readme/` (the loop diagram is drawn by `diagrams.mjs`) and are linked through raw URLs so the npm page shows them too; `check:docs` now requires every README picture to exist, carry alt text and stay under 600 KB.
|
|
8
16
|
|
|
9
17
|
## v4.2.1 — 2026-10-07（补丁：审查没交报告当场停；成本按去向分开等待）
|
package/README.en.md
CHANGED
|
@@ -14,9 +14,9 @@
|
|
|
14
14
|
|
|
15
15
|
<p align="center"><a href="README.md">中文</a> · English</p>
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
When you code with AI, every switch of session, tool, computer or person means explaining everything from the start.
|
|
18
18
|
|
|
19
|
-
BuildBeat is for humans and AI sessions
|
|
19
|
+
BuildBeat is for humans and AI sessions. It keeps what needs doing, how far it got and what was decided in the project and Git, so whoever picks it up can carry on. Once the AI has written the code, it goes on to run the tests, review and fix problems, then stops and waits for your go-ahead.
|
|
20
20
|
|
|
21
21
|
## At a glance
|
|
22
22
|
|
|
@@ -27,41 +27,89 @@ BuildBeat is for humans and AI sessions: the work description, decisions and eac
|
|
|
27
27
|
<img src="https://raw.githubusercontent.com/HaiYangBG1/BuildBeat/main/docs/assets/readme/loop-en-light.png" width="100%" alt="The delivery loop: after work.md come build, verify and review; findings go to fix, verify and review again; then the run stops for you to decide; work.md, decisions, findings and each run's final record stay in Git">
|
|
28
28
|
</picture>
|
|
29
29
|
|
|
30
|
-
|
|
30
|
+
1. You say what you want; the AI first writes a `work.md` for you to read: goal, scope, what counts as done
|
|
31
|
+
2. You say yes; it writes the code in a separate copy and runs your project's own tests
|
|
32
|
+
3. Another read-only AI reviews it; findings get fixed, then tested and reviewed again
|
|
33
|
+
4. When it's done, it stops and waits for your go-ahead
|
|
31
34
|
|
|
32
|
-
|
|
35
|
+
BuildBeat reads the test results itself instead of relying on the AI's report. If it stops halfway, say "continue" and it carries on.
|
|
33
36
|
|
|
34
|
-
|
|
37
|
+
## Get started
|
|
35
38
|
|
|
36
|
-
|
|
39
|
+
Copy the text below into your AI coding tool (Claude Code, Codex or Cursor) and it installs and sets everything up itself:
|
|
37
40
|
|
|
38
|
-
|
|
41
|
+
```
|
|
42
|
+
Please set up BuildBeat (https://github.com/HaiYangBG1/BuildBeat) in this project:
|
|
43
|
+
|
|
44
|
+
1. Check that this machine has Node 20 or later and Git; if anything is missing, tell me how to install it.
|
|
45
|
+
2. Install or upgrade the BuildBeat runtime:
|
|
46
|
+
npm view @haiyangbg/buildbeat@latest version
|
|
47
|
+
npm install --global @haiyangbg/buildbeat@latest
|
|
48
|
+
buildbeat --version
|
|
49
|
+
If a 3.x version is installed and still has unfinished work, finish or cancel it with the old version before upgrading.
|
|
50
|
+
3. Read SKILL.md and docs/v2/guide/01-quickstart.en.md from the npm package (under $(npm root -g)/@haiyangbg/buildbeat/) and work the way SKILL.md describes from now on.
|
|
51
|
+
4. Following the quickstart, put the templates into this project and update .gitignore. By default, use the AI command-line tool already signed in on this machine for building, reviewing and fixing; ask me if unsure.
|
|
52
|
+
5. When you're done, tell me in a sentence or two that we can start. From then on I'll just tell you in plain words what I want, and you run the commands.
|
|
53
|
+
```
|
|
39
54
|
|
|
40
|
-
|
|
55
|
+
Once it's set up, just talk to it; common situations are under "What it looks like" below.
|
|
41
56
|
|
|
42
|
-
|
|
57
|
+
<details>
|
|
58
|
+
<summary>Using Claude Code? You can also install the plugin</summary>
|
|
43
59
|
|
|
44
|
-
|
|
60
|
+
```text
|
|
61
|
+
/plugin marketplace add HaiYangBG1/BuildBeat
|
|
62
|
+
/plugin install buildbeat@buildbeat-plugins
|
|
63
|
+
/buildbeat:buildbeat
|
|
64
|
+
```
|
|
45
65
|
|
|
46
|
-
|
|
66
|
+
</details>
|
|
47
67
|
|
|
48
|
-
|
|
68
|
+
To install step by step yourself, see the [quickstart](docs/v2/guide/01-quickstart.en.md).
|
|
49
69
|
|
|
50
|
-
|
|
51
|
-
npm view @haiyangbg/buildbeat@latest version
|
|
52
|
-
npm install --global @haiyangbg/buildbeat@latest
|
|
53
|
-
buildbeat --version
|
|
54
|
-
```
|
|
70
|
+
## What it looks like
|
|
55
71
|
|
|
56
|
-
|
|
57
|
-
buildbeat accept --repo . --work WORK-X --by owner
|
|
58
|
-
buildbeat run --config delivery/work/WORK-X/run-config.yaml
|
|
59
|
-
buildbeat status --repo . --work WORK-X
|
|
60
|
-
```
|
|
72
|
+
**First time**
|
|
61
73
|
|
|
62
|
-
|
|
74
|
+
- **You**: (paste the text above)
|
|
75
|
+
- **AI**: All set, we can start.
|
|
76
|
+
|
|
77
|
+
**Starting a work**
|
|
78
|
+
|
|
79
|
+
- **You**: Add CSV export to the ledger.
|
|
80
|
+
- **AI**: I wrote `work.md`: export the filtered entries, quote fields with commas, done when all tests pass. Look right?
|
|
81
|
+
- **You**: Yes, go.
|
|
82
|
+
|
|
83
|
+
**New session, computer or person**
|
|
84
|
+
|
|
85
|
+
- **You**: Where are we?
|
|
86
|
+
- **AI**: "CSV export" is done and waiting for your go-ahead. The first review found unquoted commas; that's fixed and retested, and the second review passed.
|
|
87
|
+
- **You**: Approve and merge it.
|
|
88
|
+
|
|
89
|
+
**One more change**
|
|
90
|
+
|
|
91
|
+
- **You**: Empty lists should export too.
|
|
92
|
+
- **AI**: OK, I'll keep going, test and review again, and call you when it passes.
|
|
93
|
+
|
|
94
|
+
**You changed something yourself**
|
|
63
95
|
|
|
64
|
-
|
|
96
|
+
- **You**: I reworded the button and committed it.
|
|
97
|
+
- **AI**: Got it, I'll test and review your change again.
|
|
98
|
+
|
|
99
|
+
**Stuck**
|
|
100
|
+
|
|
101
|
+
- **AI**: I've stopped: the local database isn't running. That's not a code problem, so I haven't touched the code.
|
|
102
|
+
- **You**: It's up, continue.
|
|
103
|
+
|
|
104
|
+
**Several repositories**
|
|
105
|
+
|
|
106
|
+
- **You**: Where are all the repos at?
|
|
107
|
+
- **AI**: Three works across two repos: one waits for your go-ahead, two are still running.
|
|
108
|
+
|
|
109
|
+
It only stops to find you in these cases: the work is done and waits for your go-ahead, the budget is used up, a review keeps finding new problems, or the environment is broken.
|
|
110
|
+
|
|
111
|
+
<details>
|
|
112
|
+
<summary>What the AI sees behind "Where are we?"</summary>
|
|
65
113
|
|
|
66
114
|
```text
|
|
67
115
|
$ buildbeat status --repo . --work WORK-CSV-EXPORT
|
|
@@ -78,43 +126,45 @@ work WORK-CSV-EXPORT:
|
|
|
78
126
|
next: buildbeat decide … --action fix --reason <what to repair> --by <you>
|
|
79
127
|
```
|
|
80
128
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
## Records and handoffs
|
|
84
|
-
|
|
85
|
-
End-to-end work packages keep the whole story of a work in the repository:
|
|
86
|
-
|
|
87
|
-
- `delivery/work/<ID>/` **travels with Git**: work.md, run config, decisions, review findings, each run's terminal record (outcome, cost, evidence digests and references)
|
|
88
|
-
- `.buildbeat/runtime/` **stays on this machine**: the run ledger, logs, screenshots and other raw evidence
|
|
89
|
-
- `.buildbeat/worktrees/` **stays on this machine**: the isolated worktrees that hold candidates
|
|
129
|
+
</details>
|
|
90
130
|
|
|
91
|
-
|
|
131
|
+
## What a work is
|
|
92
132
|
|
|
93
|
-
|
|
133
|
+
**What**: the smallest unit BuildBeat keeps records in. One result you can see, like "CSV export", is one work, with one folder.
|
|
94
134
|
|
|
95
|
-
|
|
135
|
+
**Why**: the AI doesn't remember things, and sessions change at any time. What the work is for, how far it got, what review found and what you decided all go into that folder, so whoever picks it up carries on from there, and later you can look back at how it got done.
|
|
96
136
|
|
|
97
|
-
|
|
137
|
+
## Files in your project
|
|
98
138
|
|
|
99
|
-
|
|
139
|
+
The first time, the AI puts these files in place from the templates:
|
|
100
140
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
/
|
|
141
|
+
```
|
|
142
|
+
your-project/
|
|
143
|
+
├── AGENTS.md, CLAUDE.md tell AI tools this project uses BuildBeat
|
|
144
|
+
├── .gitignore add the two .buildbeat/ folders below
|
|
145
|
+
├── delivery/ travels with Git
|
|
146
|
+
│ ├── envelope/
|
|
147
|
+
│ │ ├── worker.sh wraps an AI tool as a step BuildBeat can call
|
|
148
|
+
│ │ └── prompts/ prompts for build, review and fix
|
|
149
|
+
│ └── work/
|
|
150
|
+
│ └── WORK-X/ one folder per work
|
|
151
|
+
│ ├── work.md what to do and what counts as done
|
|
152
|
+
│ ├── run-config.yaml which AI, which tests, which folders it may change
|
|
153
|
+
│ ├── decisions.jsonl accept, approve, close and other decisions
|
|
154
|
+
│ ├── review-findings.jsonl problems the review found and your rulings
|
|
155
|
+
│ ├── releases.jsonl checks after going live (only if used)
|
|
156
|
+
│ └── runs/RUN-X-01/
|
|
157
|
+
│ └── run-record.json this run's outcome, evidence and cost
|
|
158
|
+
└── .buildbeat/
|
|
159
|
+
├── notify.yaml optional: webhook or DingTalk alerts when you're needed
|
|
160
|
+
├── runtime/ this machine only: live ledger, logs, screenshots
|
|
161
|
+
└── worktrees/ this machine only: isolated copies the AI works in
|
|
109
162
|
```
|
|
110
163
|
|
|
111
|
-
|
|
164
|
+
- `delivery/` goes into Git: switching sessions, tools, computers or people just means pulling the code and carrying on
|
|
165
|
+
- `.buildbeat/runtime/` and `.buildbeat/worktrees/` stay on this machine: a run in progress does not travel with Git, so finish or stop it where it started
|
|
166
|
+
- People and AI tools without BuildBeat installed can still read these files and draft `work.md`
|
|
112
167
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
| Talk to a session day to day | [How to talk](docs/v2/guide/00-how-to-talk.en.md) |
|
|
117
|
-
| Understand the fixed flow and the run config | [Workflow and configuration](docs/v2/guide/02-workflow-guide.en.md) |
|
|
118
|
-
| Approve, reject, read evidence | [Decisions and evidence](docs/v2/guide/07-approval-guide.en.md) |
|
|
119
|
-
| Hand over across sessions and people | [Session handoff](docs/v2/guide/11-session-handoff.en.md) |
|
|
120
|
-
| Contribute | [Contributing](CONTRIBUTING.md) · [MIT license](LICENSE) |
|
|
168
|
+
To contribute, see [Contributing](CONTRIBUTING.md); the code is open source under the [MIT license](LICENSE).
|
|
169
|
+
|
|
170
|
+
> **Why the name**: every step is a note, and the agent plays them beat by beat; the score it has played (context, decisions and outcomes) stays in Git, ready to read again.
|
package/README.md
CHANGED
|
@@ -14,9 +14,9 @@
|
|
|
14
14
|
|
|
15
15
|
<p align="center">中文 · <a href="README.en.md">English</a></p>
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
用 AI 写代码，换个会话、换个软件、换台电脑、换个人，事情都得从头讲一遍。
|
|
18
18
|
|
|
19
|
-
BuildBeat 面向人和 AI
|
|
19
|
+
BuildBeat 面向人和 AI 会话，把要做的事、做到哪、定过什么都记在项目和 Git 里，谁接手都能接着干。AI 写完代码，它会接着跑测试、做审查、修问题，最后停下来等你拍板。
|
|
20
20
|
|
|
21
21
|
## 一眼看懂
|
|
22
22
|
|
|
@@ -27,41 +27,89 @@ BuildBeat 面向人和 AI 会话：工作说明、决定和每轮结论留在项
|
|
|
27
27
|
<img src="https://raw.githubusercontent.com/HaiYangBG1/BuildBeat/main/docs/assets/readme/loop-zh-light.png" width="100%" alt="交付循环：work.md 之后依次是实现、验证、审查，审查有问题就修复、重验、再审，最后停下等你拍板；work.md、决定、审查问题和每轮运行的终态记录留在 Git 里">
|
|
28
28
|
</picture>
|
|
29
29
|
|
|
30
|
-
|
|
30
|
+
1. 你说要做什么，AI 先写一份 `work.md` 给你看：目标、范围、做到什么算完
|
|
31
|
+
2. 你点头，它在一个单独的副本里写代码、跑你项目自己的测试
|
|
32
|
+
3. 另一个只读的 AI 来审查；有问题就修，修完重新测、重新审
|
|
33
|
+
4. 做完了停下来，等你拍板
|
|
31
34
|
|
|
32
|
-
|
|
35
|
+
测试结果由 BuildBeat 自己去读，不靠 AI 汇报。中途断了，说一句「继续」就接着跑。
|
|
33
36
|
|
|
34
|
-
|
|
37
|
+
## 开始用
|
|
35
38
|
|
|
36
|
-
|
|
39
|
+
把下面这段复制给你的 AI 编程工具（Claude Code、Codex、Cursor 都行），它会自己装好、配好：
|
|
37
40
|
|
|
38
|
-
|
|
41
|
+
```
|
|
42
|
+
请帮我在这个项目里用上 BuildBeat（https://github.com/HaiYangBG1/BuildBeat）：
|
|
43
|
+
|
|
44
|
+
1. 检查本机有没有 Node 20 以上和 Git，缺了就告诉我怎么装。
|
|
45
|
+
2. 安装或升级 BuildBeat 运行时：
|
|
46
|
+
npm view @haiyangbg/buildbeat@latest version
|
|
47
|
+
npm install --global @haiyangbg/buildbeat@latest
|
|
48
|
+
buildbeat --version
|
|
49
|
+
如果本机已经装了 3.x，并且还有没跑完的工作，先用旧版跑完或取消，再升级。
|
|
50
|
+
3. 读一遍 npm 包里的 SKILL.md 和 docs/v2/guide/01-quickstart.md（在 $(npm root -g)/@haiyangbg/buildbeat/ 下），之后都按 SKILL.md 的方式干活。
|
|
51
|
+
4. 按快速开始把模板放进这个项目、补好 .gitignore。实现、审查、修复默认用本机已登录的 AI 命令行工具，拿不准就问我。
|
|
52
|
+
5. 弄好后用一两句话告诉我可以开始了。之后我只用平常的话跟你说要做什么，命令都由你来跑。
|
|
53
|
+
```
|
|
39
54
|
|
|
40
|
-
|
|
55
|
+
装好之后，就用平常的话跟它说，常见场景见下面「用起来是什么样」。
|
|
41
56
|
|
|
42
|
-
|
|
57
|
+
<details>
|
|
58
|
+
<summary>用 Claude Code？也可以装插件</summary>
|
|
43
59
|
|
|
44
|
-
|
|
60
|
+
```text
|
|
61
|
+
/plugin marketplace add HaiYangBG1/BuildBeat
|
|
62
|
+
/plugin install buildbeat@buildbeat-plugins
|
|
63
|
+
/buildbeat:buildbeat
|
|
64
|
+
```
|
|
45
65
|
|
|
46
|
-
|
|
66
|
+
</details>
|
|
47
67
|
|
|
48
|
-
|
|
68
|
+
想自己动手一步步装，见[快速开始](docs/v2/guide/01-quickstart.md)。
|
|
49
69
|
|
|
50
|
-
|
|
51
|
-
npm view @haiyangbg/buildbeat@latest version
|
|
52
|
-
npm install --global @haiyangbg/buildbeat@latest
|
|
53
|
-
buildbeat --version
|
|
54
|
-
```
|
|
70
|
+
## 用起来是什么样
|
|
55
71
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
72
|
+
**第一次用**
|
|
73
|
+
|
|
74
|
+
- **你**：（复制上面那段）
|
|
75
|
+
- **AI**：装好了，可以开始了。
|
|
76
|
+
|
|
77
|
+
**开始一项工作**
|
|
78
|
+
|
|
79
|
+
- **你**：给账本加个导出 CSV 的功能。
|
|
80
|
+
- **AI**：写好了 `work.md`：导出当前筛选的账目，带逗号的字段加引号，测试全过才算完。你看行吗？
|
|
81
|
+
- **你**：行，开工。
|
|
82
|
+
|
|
83
|
+
**换会话、换电脑、换人**
|
|
84
|
+
|
|
85
|
+
- **你**：到哪了？
|
|
86
|
+
- **AI**：「导出 CSV」做完了，等你拍板。第一轮审查发现带逗号没加引号，已经修好、重新测过，第二轮通过了。
|
|
87
|
+
- **你**：批准，合并吧。
|
|
88
|
+
|
|
89
|
+
**想再改改**
|
|
90
|
+
|
|
91
|
+
- **你**：空表也要能导出。
|
|
92
|
+
- **AI**：好，我接着改，重新测、重新审，过了再叫你。
|
|
93
|
+
|
|
94
|
+
**你自己动手改了**
|
|
61
95
|
|
|
62
|
-
|
|
96
|
+
- **你**：按钮文案我改了，已经提交。
|
|
97
|
+
- **AI**：看到了，我把你的改动重新测一遍、审一遍。
|
|
63
98
|
|
|
64
|
-
|
|
99
|
+
**卡住了**
|
|
100
|
+
|
|
101
|
+
- **AI**：停下来了：本地数据库没启动。这不是代码问题，我没改代码。
|
|
102
|
+
- **你**：开好了，继续。
|
|
103
|
+
|
|
104
|
+
**好几个仓库**
|
|
105
|
+
|
|
106
|
+
- **你**：所有仓库到哪了？
|
|
107
|
+
- **AI**：两个仓库一共三项工作：一项等你拍板，两项还在跑。
|
|
108
|
+
|
|
109
|
+
它会停下来找你的情况只有这几种：做完了等你拍板、预算用完、审查一直不收敛、环境出了问题。
|
|
110
|
+
|
|
111
|
+
<details>
|
|
112
|
+
<summary>「到哪了？」时 AI 背后看到的输出</summary>
|
|
65
113
|
|
|
66
114
|
```text
|
|
67
115
|
$ buildbeat status --repo . --work WORK-CSV-EXPORT
|
|
@@ -78,43 +126,45 @@ work WORK-CSV-EXPORT:
|
|
|
78
126
|
next: buildbeat decide … --action fix --reason <what to repair> --by <you>
|
|
79
127
|
```
|
|
80
128
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
## 记录与接续
|
|
84
|
-
|
|
85
|
-
端到端工作包把一项工作的来龙去脉留在仓库里：
|
|
86
|
-
|
|
87
|
-
- `delivery/work/<ID>/` **随 Git 走**：work.md、run 配置、决定、审查问题、每轮终态记录（结果、成本、证据摘要与引用）
|
|
88
|
-
- `.buildbeat/runtime/` **只在本机**：运行台账、日志、截图等原始证据
|
|
89
|
-
- `.buildbeat/worktrees/` **只在本机**：候选所在的隔离工作树
|
|
90
|
-
|
|
91
|
-
换会话前补齐未落盘事实；Git clone 不迁移活动进程和现场。没装运行时的人和工具也能读状态、写工作说明。
|
|
129
|
+
</details>
|
|
92
130
|
|
|
93
|
-
|
|
131
|
+
## 什么是一项工作
|
|
94
132
|
|
|
95
|
-
|
|
133
|
+
**是什么**：BuildBeat 记东西的最小单位。一个你能看到的结果，比如「导出 CSV」，就是一项工作，对应一个文件夹。
|
|
96
134
|
|
|
97
|
-
|
|
135
|
+
**为什么要有它**：AI 记不住事，会话也随时会换。把这件事要做什么、做到哪、审出过什么问题、你拍过什么板，都收进这个文件夹，谁接手都从这里接着干，回头也能翻出来看它是怎么做成的。
|
|
98
136
|
|
|
99
|
-
|
|
137
|
+
## 项目里的文件
|
|
100
138
|
|
|
101
|
-
|
|
139
|
+
第一次接入时，AI 会照模板把这些文件放好：
|
|
102
140
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
/
|
|
108
|
-
/
|
|
141
|
+
```
|
|
142
|
+
你的项目/
|
|
143
|
+
├── AGENTS.md、CLAUDE.md 告诉 AI 工具：这个项目用 BuildBeat
|
|
144
|
+
├── .gitignore 加上下面两行 .buildbeat/ 目录
|
|
145
|
+
├── delivery/ 跟着 Git 走
|
|
146
|
+
│ ├── envelope/
|
|
147
|
+
│ │ ├── worker.sh 把 AI 工具包成 BuildBeat 能调用的一步
|
|
148
|
+
│ │ └── prompts/ 实现、审查、修复各自的提示词
|
|
149
|
+
│ └── work/
|
|
150
|
+
│ └── WORK-X/ 一项工作一个文件夹
|
|
151
|
+
│ ├── work.md 要做什么、做到什么算完
|
|
152
|
+
│ ├── run-config.yaml 用哪个 AI、跑什么测试、能改哪些目录
|
|
153
|
+
│ ├── decisions.jsonl 接受、批准、关闭这些决定
|
|
154
|
+
│ ├── review-findings.jsonl 审查挑出的问题和你的裁决
|
|
155
|
+
│ ├── releases.jsonl 上线后的检查记录（用到才有）
|
|
156
|
+
│ └── runs/RUN-X-01/
|
|
157
|
+
│ └── run-record.json 这一轮的结果、证据和成本
|
|
158
|
+
└── .buildbeat/
|
|
159
|
+
├── notify.yaml 可选：等你拍板时发 webhook 或钉钉通知
|
|
160
|
+
├── runtime/ 只在本机：正在跑的台账、日志、截图
|
|
161
|
+
└── worktrees/ 只在本机：AI 干活用的隔离副本
|
|
109
162
|
```
|
|
110
163
|
|
|
111
|
-
|
|
164
|
+
- `delivery/` 进 Git：换会话、换软件、换电脑、换人，拉下代码就能接着干
|
|
165
|
+
- `.buildbeat/runtime/`、`.buildbeat/worktrees/` 只在本机：正在跑的那一轮不跟着 Git 走，要在原来那台机器上跑完或停掉
|
|
166
|
+
- 没装 BuildBeat 的人和 AI 也能读这些文件、起草 `work.md`
|
|
112
167
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
| 平时怎么和会话说 | [怎么和会话说话](docs/v2/guide/00-how-to-talk.md) |
|
|
117
|
-
| 理解固定流程和 run 配置 | [流程与配置](docs/v2/guide/02-workflow-guide.md) |
|
|
118
|
-
| 批准、拒绝、证据 | [决定与证据](docs/v2/guide/07-approval-guide.md) |
|
|
119
|
-
| 换会话、换人接手 | [跨会话接续](docs/v2/guide/11-session-handoff.md) |
|
|
120
|
-
| 参与贡献 | [贡献指南](CONTRIBUTING.md) · [MIT 许可证](LICENSE) |
|
|
168
|
+
参与贡献看[贡献指南](CONTRIBUTING.md)，代码以 [MIT 许可证](LICENSE)开源。
|
|
169
|
+
|
|
170
|
+
> **名字的由来**：每一步是一个音符，Agent 按节拍把它们演奏出来；演奏过的乐谱——上下文、决定和结论——留在 Git 里，随时翻阅。
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# BuildBeat capability matrix / 能力矩阵
|
|
2
2
|
|
|
3
|
-
Current release: 4.2.
|
|
3
|
+
Current release: 4.2.3. One product path: Skill → local runtime →
|
|
4
4
|
project records. The Claude Code plugin distributes the Skill and references;
|
|
5
5
|
install the runtime separately. Files remain readable without the runtime, but
|
|
6
6
|
manual work has no automatic loop, isolation, budget or approval enforcement;
|
package/docs/RELEASING.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
This runbook governs BuildBeat's public npm distribution. The canonical package is `@haiyangbg/buildbeat` in `HaiYangBG1/BuildBeat`; the only executable is `buildbeat`. No other package name or executable alias receives publications.
|
|
4
4
|
|
|
5
|
-
Release evidence at source package version `@haiyangbg/buildbeat@4.2.
|
|
5
|
+
Release evidence at source package version `@haiyangbg/buildbeat@4.2.3`; latest independently verified BuildBeat npm distribution `@haiyangbg/buildbeat@4.2.2` (dist-tags `latest` and `next`; the owner moved `next` from `4.2.0` to `4.2.2` with npm 2FA on 2026-10-07), anchored by annotated tag `v4.2.2` at commit `3a43ae3`, workflow run [37637179739](https://github.com/HaiYangBG1/BuildBeat/actions/runs/37637179739), and archived in [`V4.2.2-RELEASE-EVIDENCE-2026-10-07.md`](releases/V4.2.2-RELEASE-EVIDENCE-2026-10-07.md). The 4.2.1 chain (`latest` on 2026-10-07 until 4.2.2 took over the same day) stays archived in [`V4.2.1-RELEASE-EVIDENCE-2026-10-07.md`](releases/V4.2.1-RELEASE-EVIDENCE-2026-10-07.md). The 4.2.0 chain (`latest` on 2026-10-07 until 4.2.1 took over the same day; the owner moved `next` from `4.0.0` to `4.2.0` with npm 2FA that day) stays archived in [`V4.2.0-RELEASE-EVIDENCE-2026-10-07.md`](releases/V4.2.0-RELEASE-EVIDENCE-2026-10-07.md). The 4.1.0 chain (`latest` on 2026-10-07 until 4.2.0 took over the same day) stays archived in [`V4.1.0-RELEASE-EVIDENCE-2026-10-07.md`](releases/V4.1.0-RELEASE-EVIDENCE-2026-10-07.md). The 4.0.0 chain (`latest` from 2026-10-05 until 4.1.0 took over on 2026-10-07; the owner moved `next` from `3.3.1` to `4.0.0` with npm 2FA on 2026-10-05) stays archived in [`V4.0.0-RELEASE-EVIDENCE-2026-10-05.md`](releases/V4.0.0-RELEASE-EVIDENCE-2026-10-05.md). The 3.3.1 chain (`latest` from 2026-10-02 until 4.0.0 took over on 2026-10-05; the owner moved `next` from `3.3.0` to `3.3.1` with npm 2FA on 2026-10-02) stays archived in [`V3.3.1-RELEASE-EVIDENCE-2026-10-02.md`](releases/V3.3.1-RELEASE-EVIDENCE-2026-10-02.md). The 3.3.0 chain (`latest` on 2026-10-02 until 3.3.1 took over the same day; the owner moved `next` from `3.2.1` to `3.3.0` with npm 2FA that day) stays archived in [`V3.3.0-RELEASE-EVIDENCE-2026-10-02.md`](releases/V3.3.0-RELEASE-EVIDENCE-2026-10-02.md). The 3.2.1 chain (`latest` from 2026-09-26 until 3.3.0 took over on 2026-10-02; the owner moved `next` from `3.0.1` to `3.2.1` with npm 2FA on 2026-09-26) stays archived in [`V3.2.1-RELEASE-EVIDENCE-2026-09-26.md`](releases/V3.2.1-RELEASE-EVIDENCE-2026-09-26.md). The 3.2.0 chain (`latest` on 2026-09-26 until 3.2.1 took over the same day) stays archived in [`V3.2.0-RELEASE-EVIDENCE-2026-09-26.md`](releases/V3.2.0-RELEASE-EVIDENCE-2026-09-26.md). The 3.1.0 chain (`latest` on 2026-09-26 until 3.2.0 took over the same day) stays archived in [`V3.1.0-RELEASE-EVIDENCE-2026-09-26.md`](releases/V3.1.0-RELEASE-EVIDENCE-2026-09-26.md). The 3.0.1 chain (`latest` from 2026-09-09 until 3.1.0 took over on 2026-09-26) stays archived in [`V3.0.1-RELEASE-EVIDENCE-2026-09-09.md`](releases/V3.0.1-RELEASE-EVIDENCE-2026-09-09.md). The 3.0.0 chain (`latest` from 2026-09-09 until 3.0.1 took over the same day; the first version without the removed generation) stays archived in [`V3.0.0-RELEASE-EVIDENCE-2026-09-09.md`](releases/V3.0.0-RELEASE-EVIDENCE-2026-09-09.md). The 2.0.2 chain (`latest` from 2026-09-09 until 3.0.0 took over the same day; the last version carrying the removed generation) stays archived in [`V2.0.2-RELEASE-EVIDENCE-2026-09-09.md`](releases/V2.0.2-RELEASE-EVIDENCE-2026-09-09.md). The 2.0.1 chain (`latest` from 2026-09-06 until 2.0.2 took over on 2026-09-09) stays archived in [`V2.0.1-RELEASE-EVIDENCE-2026-09-06.md`](releases/V2.0.1-RELEASE-EVIDENCE-2026-09-06.md). The 2.0.0 chain (`latest` from 2026-09-05 until 2.0.1 took over on 2026-09-06) stays archived in [`V2.0.0-RELEASE-EVIDENCE-2026-09-05.md`](releases/V2.0.0-RELEASE-EVIDENCE-2026-09-05.md). The beta.5 chain stays archived in [`V2.0.0-BETA.5-RELEASE-EVIDENCE-2026-09-05.md`](releases/V2.0.0-BETA.5-RELEASE-EVIDENCE-2026-09-05.md). The beta.4 chain stays archived in [`V2.0.0-BETA.4-RELEASE-EVIDENCE-2026-09-03.md`](releases/V2.0.0-BETA.4-RELEASE-EVIDENCE-2026-09-03.md); the beta.3 chain in [`V2.0.0-BETA.3-RELEASE-EVIDENCE-2026-09-01.md`](releases/V2.0.0-BETA.3-RELEASE-EVIDENCE-2026-09-01.md). The beta.2 chain stays archived in [`V2.0.0-BETA.2-RELEASE-EVIDENCE-2026-08-28.md`](releases/V2.0.0-BETA.2-RELEASE-EVIDENCE-2026-08-28.md); the beta.1 chain stays archived in [`V2.0.0-BETA.1-RELEASE-EVIDENCE-2026-08-28.md`](releases/V2.0.0-BETA.1-RELEASE-EVIDENCE-2026-08-28.md). Earlier distributions and the retired legacy package name are archived in the dated evidence files under `docs/releases/`.
|
|
6
6
|
|
|
7
7
|
## Channels and branches
|
|
8
8
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@haiyangbg/buildbeat",
|
|
3
|
-
"version": "4.2.
|
|
3
|
+
"version": "4.2.3",
|
|
4
4
|
"description": "BuildBeat: Git-based AI delivery across models, tools, sessions, and people, with context in project files, build-test-review-fix loops, and human decisions.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|