@futurelastic/colab-handbook 1.12.0 → 1.13.0-rc.10
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/README.md +248 -213
- package/README.vi.md +252 -186
- package/audit/audit.mjs +193 -10
- package/package.json +7 -1
- package/templates/README.md +30 -2
- package/templates/ci-laravel.yml +102 -21
- package/templates/ci-node.yml +61 -3
- package/templates/ci-python.yml +52 -3
- package/templates/deploy-adapter-portainer.mjs +206 -0
- package/templates/deploy-container-run.mjs +368 -0
- package/templates/deploy-container.yml +219 -0
- package/templates/dist-refs.yml +6 -0
- package/templates/docs-lint.mjs +1 -1
- package/templates/npx-launcher.mjs +118 -20
- package/templates/npx-service.mjs +828 -0
- package/templates/release-auto.yml +341 -32
- package/tools/colab +1902 -278
- package/tools/lib/adopt.js +373 -14
- package/tools/lib/branch-name.js +29 -1
- package/tools/lib/ci-cure.js +522 -31
- package/tools/lib/ci-grant.js +289 -22
- package/tools/lib/ci-wait.js +223 -0
- package/tools/lib/claim-comments.js +13 -64
- package/tools/lib/claim-identity.js +42 -7
- package/tools/lib/codec/claim.d.ts +41 -0
- package/tools/lib/codec/claim.js +153 -0
- package/tools/lib/codec/decision.d.ts +29 -0
- package/tools/lib/codec/decision.js +81 -0
- package/tools/lib/codec/grants.d.ts +82 -0
- package/tools/lib/codec/grants.js +268 -0
- package/tools/lib/codec/hold.d.ts +26 -0
- package/tools/lib/codec/hold.js +152 -0
- package/tools/lib/codec/index.d.ts +21 -0
- package/tools/lib/codec/index.js +32 -0
- package/tools/lib/codec/labels.d.ts +65 -0
- package/tools/lib/codec/labels.js +723 -0
- package/tools/lib/codec/markers.d.ts +35 -0
- package/tools/lib/codec/markers.js +138 -0
- package/tools/lib/codec/release.d.ts +17 -0
- package/tools/lib/codec/release.js +69 -0
- package/tools/lib/codec/samples.json +778 -0
- package/tools/lib/codeowners.js +68 -4
- package/tools/lib/container-close.js +38 -0
- package/tools/lib/cure-diff.js +198 -9
- package/tools/lib/decision-record.js +15 -39
- package/tools/lib/docs-only.js +15 -1
- package/tools/lib/exposure-shape.js +42 -8
- package/tools/lib/git.js +324 -42
- package/tools/lib/group-labels.js +65 -0
- package/tools/lib/install-check.js +14 -8
- package/tools/lib/install-route.js +139 -0
- package/tools/lib/instruction-file.js +1 -0
- package/tools/lib/labels.js +22 -647
- package/tools/lib/local-adopt.js +8 -4
- package/tools/lib/migration-grant.js +206 -104
- package/tools/lib/place.js +2 -2
- package/tools/lib/release-cut.js +199 -25
- package/tools/lib/release-finalize.js +111 -23
- package/tools/lib/release-policy.js +130 -22
- package/tools/lib/release-runner.js +125 -0
- package/tools/lib/release-tag.js +3 -1
- package/tools/lib/scratch-dirs.js +118 -0
- package/tools/lib/ship-batch.js +36 -1
- package/tools/lib/ship-human-door.js +76 -0
- package/tools/lib/stamp.js +7 -0
- package/tools/lib/tracker-fake.js +195 -0
- package/tools/lib/tracker-github.js +106 -0
- package/tools/lib/tracker-scenarios.json +206 -0
- package/tools/lib/tracker.js +64 -0
- package/tools/lib/tree-green.js +88 -0
- package/tools/lib/util.js +17 -1
- package/tools/lib/verify-runs.js +104 -0
- package/tools/lib/wake.js +8 -90
- package/tools/lib/workflow-triggers.js +48 -0
package/README.vi.md
CHANGED
|
@@ -8,11 +8,27 @@ người thật lẫn AI agent — mà không giẫm chân nhau.
|
|
|
8
8
|
**Nếu bạn là AI agent, dừng ở đây và đọc [`CLAUDE.md`](CLAUDE.md).**
|
|
9
9
|
File này dành cho con người.
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
11
|
+
## Bắt đầu nhanh
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
git clone https://github.com/futurelastic/colab-handbook.git ~/code/colab-handbook
|
|
15
|
+
cd ~/code/colab-handbook && ./install.sh --all # skills + CLI colab + hook, từ bản phát hành mới nhất; --dry để xem trước
|
|
16
|
+
cd /duong-dan/toi/repo-cua-ban
|
|
17
|
+
colab adopt # chỉ hỏi những gì không tự dò ra được, rồi ghi .github/project.yml
|
|
18
|
+
colab labels --ensure # tạo các label quy ước
|
|
19
|
+
colab register # đưa repo vào danh sách fleet của máy này
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Sau đó, trong một phiên agent ở repo đó, chạy `/code-start <số-issue>`. Có agent
|
|
23
|
+
trong tay thì `/handbook-sync` thay được ba lệnh cuối và làm nốt phần adopt còn
|
|
24
|
+
lại (xem [*Adopt vào một repo*](#adopt-vào-một-repo)). Cần có `git`, `node` ≥ 18
|
|
25
|
+
và `gh` ≥ 2.94 đã đăng nhập (`gh auth login`); gói `gh` của các distro thường cũ
|
|
26
|
+
hơn, nên hãy cài từ [cli.github.com](https://cli.github.com).
|
|
27
|
+
|
|
28
|
+
*([`CONVENTIONS.md`](CONVENTIONS.md) là tài liệu chuẩn tắc, viết bằng tiếng Anh
|
|
29
|
+
để agent và tool đọc được. File này và bản tiếng Anh [`README.md`](README.md)
|
|
30
|
+
chỉ là cửa vào. Khi hai bản nói khác nhau thì **cả hai đều sai** cho tới khi
|
|
31
|
+
khớp lại với `CONVENTIONS.md`.)*
|
|
16
32
|
|
|
17
33
|
## Đây là cái gì
|
|
18
34
|
|
|
@@ -21,10 +37,10 @@ merge vào đâu, release là gì, báo "tôi đang làm việc này" bằng cá
|
|
|
21
37
|
tình để **cách hiện thực** (phiên bản Node, test runner, file CI của bạn) cho
|
|
22
38
|
từng repo tự quyết.
|
|
23
39
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
40
|
+
Nó được chưng cất từ việc vận hành một fleet repo thật, trong đó có nhiều app
|
|
41
|
+
production được bảo trì gần như hoàn toàn bởi AI agent chạy song song trên nhiều
|
|
42
|
+
worktree. Mục anti-pattern không phải lý thuyết: từng mục là chuyện đã xảy ra
|
|
43
|
+
thật.
|
|
28
44
|
|
|
29
45
|
### Nó giải quyết vấn đề gì
|
|
30
46
|
|
|
@@ -48,19 +64,17 @@ sự thật về một repo lại nằm trong trí nhớ của ai đó thay vì
|
|
|
48
64
|
|
|
49
65
|
### Thực chất nó làm gì
|
|
50
66
|
|
|
51
|
-
Nó bắt mỗi repo tự trả lời
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
Mọi thứ còn lại suy ra từ mấy câu trả lời đó: merge vào nhánh nào, ở repo này
|
|
57
|
-
release nghĩa là gì, có bắt buộc phải có nhánh không, một phiên phải ghi lại
|
|
58
|
-
bao nhiêu trước khi dừng. Phiên làm việc không phải đoán, và hai repo không bao
|
|
59
|
-
giờ hiểu khác nhau về cùng một từ.
|
|
67
|
+
Nó bắt mỗi repo tự trả lời năm câu hỏi về chính mình, **một lần**, vào một file
|
|
68
|
+
mà mọi phiên đều đọc trước khi động vào bất cứ thứ gì (xem [*Năm câu
|
|
69
|
+
hỏi*](#năm-câu-hỏi)). Mọi thứ còn lại suy ra từ mấy câu trả lời đó: merge vào
|
|
70
|
+
nhánh nào, ở repo này release nghĩa là gì, có bắt buộc phải có nhánh không, một
|
|
71
|
+
phiên phải ghi lại bao nhiêu trước khi dừng.
|
|
60
72
|
|
|
61
|
-
Phần còn lại của repo
|
|
62
|
-
|
|
63
|
-
|
|
73
|
+
Phần còn lại của repo phục vụ điều đó: một CLI làm giúp phần cơ học, một audit
|
|
74
|
+
báo chỗ nào thực tế đã trôi khỏi thứ repo tự khai, và các luồng phiên làm việc
|
|
75
|
+
(skill) để phiên code ở đâu cũng mở ra và đóng lại giống nhau. Skill chỉ là văn
|
|
76
|
+
xuôi — một người ngồi terminal có thể làm theo mà không cần agent hay tool nào
|
|
77
|
+
khác.
|
|
64
78
|
|
|
65
79
|
### Nó không phải cái gì
|
|
66
80
|
|
|
@@ -70,49 +84,154 @@ làm việc mang đi được để phiên code ở đâu cũng mở ra và đó
|
|
|
70
84
|
- **Không phải hệ thống CI, cũng không có ý kiến gì về stack của bạn.** Ngôn
|
|
71
85
|
ngữ, test runner, pipeline — của bạn cả. Handbook chỉ yêu cầu pipeline cho ra
|
|
72
86
|
hai kết quả, và không bao giờ nói phải làm bằng cách nào.
|
|
73
|
-
- **
|
|
74
|
-
|
|
75
|
-
|
|
87
|
+
- **Phần lớn không phải lớp ép buộc.** Chuyện tuân thủ chỉ là cảnh báo. Vài thứ
|
|
88
|
+
ít ỏi thật sự chặn được liệt kê ở [*Vì sao ép buộc ít
|
|
89
|
+
vậy*](#vì-sao-ép-buộc-ít-vậy).
|
|
76
90
|
- **Không phải thang đo độ trưởng thành.** Không câu trả lời nào ở đây xếp repo
|
|
77
91
|
này trên repo kia. Một repo chưa có production không phải repo tệ hơn; nó là
|
|
78
92
|
repo có ít cổng hơn.
|
|
79
93
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
94
|
+
## Phiên làm việc đầu tiên
|
|
95
|
+
|
|
96
|
+
Mỗi đầu việc đi qua một vòng. Mỗi bước là một skill, gọi trong phiên agent bằng
|
|
97
|
+
slash command (`/code-start 42`), hoặc tự làm theo bằng tay từ
|
|
98
|
+
[`skills/`](skills/).
|
|
99
|
+
|
|
100
|
+
| Bước | Skill | Ai chạy | Để lại gì |
|
|
101
|
+
|---|---|---|---|
|
|
102
|
+
| 1. Chọn | `/code-triage` | điều phối | việc sẵn sàng theo thứ tự, label `group:` trên các issue phải chung một nhánh, `needs-plan` trên việc khó, lệnh để bắt đầu |
|
|
103
|
+
| 2. Mở | `/code-start <N>` | thợ | issue đã claim, nhánh cắt từ trunk và đã push, một worktree, một file plan ngắn |
|
|
104
|
+
| 3. Làm | — | thợ | commit trên nhánh |
|
|
105
|
+
| 4. Bàn giao | `/code-wrap` | thợ | điều học được ghi lên Issue, gate của repo đã chạy, nhánh đã push — rồi **dừng** |
|
|
106
|
+
| 5. Merge | `/code-ship` | điều phối, sau khi người đồng ý | một squash commit trên trunk kèm `Closes #N`, bằng chứng trên từng issue, claim đã nhả, worktree đã gỡ |
|
|
107
|
+
| 6. Dọn | `/code-sweep` | điều phối | việc đã xong được ship, claim và worktree cũ được dọn |
|
|
108
|
+
| 7. Release | release workflow, hoặc `/release-rung` | tự động, hoặc người khi tag là thứ deploy | một tag ứng viên, rồi bản final sau thời gian thử — chỉ khi `exposure` của repo có release |
|
|
109
|
+
|
|
110
|
+
Cũng trong [`skills/`](skills/): `code-plan` (plan đầy đủ cho issue khó, do
|
|
111
|
+
`code-start` gọi khi có cờ), `handbook-sync` (kéo một repo lên bản handbook mới
|
|
112
|
+
nhất), và `migration-review` (review migration của một nhánh, cho người/agent
|
|
113
|
+
được repo gán vai đó).
|
|
114
|
+
|
|
115
|
+
**Tự chạy vòng này bằng tay ở terminal?** Không có `--session` thì `colab` đặt
|
|
116
|
+
tên bạn là `person:<git user.email>/<host token>`, nên claim và bằng chứng ship
|
|
117
|
+
đều ghi rõ ai làm. Nếu làm nhiều đơn vị việc cùng lúc ở các shell khác nhau,
|
|
118
|
+
đặt cho mỗi shell một `COLAB_SESSION=<id ổn định bất kỳ>` để các hold không lẫn
|
|
119
|
+
vào nhau.
|
|
120
|
+
|
|
121
|
+
**Mấy từ sẽ gặp:**
|
|
122
|
+
|
|
123
|
+
- **Trunk** — nhánh các phiên merge vào (`trunk:` trong `project.yml`).
|
|
124
|
+
**Promotion** — merge trunk vào `main` khi trunk không phải `main`; ở repo
|
|
125
|
+
`live` thì chính cú promote *là* deploy.
|
|
126
|
+
- **Claim** — assignee + label `in-progress`, có nhánh đã push lên remote làm
|
|
127
|
+
bằng, lấy *trước khi* bắt tay vào làm.
|
|
128
|
+
- **Thợ / điều phối** (implementer / coordinator) — phiên viết code / phiên
|
|
129
|
+
chọn việc, merge và dọn dẹp. Một người có thể làm cả hai, ở hai thời điểm.
|
|
130
|
+
- **Phase A / Phase B** — `code-wrap` (nửa của thợ, dừng trước mọi cú merge) /
|
|
131
|
+
`code-ship` (nửa của điều phối: cú merge và mọi thứ sau đó).
|
|
132
|
+
- **Nấc (rung)** — phiên viết bao nhiêu plan: 0 không viết, 1 một khung năm
|
|
133
|
+
dòng, 2 plan đầy đủ từ `code-plan`.
|
|
134
|
+
|
|
135
|
+
Người mới: đọc [`CONVENTIONS.md` §1](CONVENTIONS.md#1-the-model-in-one-picture)
|
|
136
|
+
(mô hình) và [§11](CONVENTIONS.md#11-quick-reference) (tra nhanh) trước. Phần
|
|
137
|
+
còn lại của `CONVENTIONS.md` là tài liệu tra cứu — cần gì tra nấy, đừng đọc từ
|
|
138
|
+
đầu tới cuối.
|
|
84
139
|
|
|
85
140
|
## Năm câu hỏi
|
|
86
141
|
|
|
87
|
-
Adopt
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
2
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
142
|
+
Adopt nghĩa là trả lời mấy câu này về repo của bạn vào `.github/project.yml`.
|
|
143
|
+
`colab adopt` chỉ hỏi hai câu làm thay đổi cổng (1 và 3), dưới dạng menu đánh
|
|
144
|
+
số; ba câu còn lại là tuỳ chọn, trả lời lúc nào sau này cũng được:
|
|
145
|
+
|
|
146
|
+
| # | Câu hỏi | Ghi vào | Lúc adopt |
|
|
147
|
+
|---|---|---|---|
|
|
148
|
+
| 1 | **Hôm nay** (chứ không phải "sắp") đã có đích deploy chưa, và đến đó bằng đường nào — một tag, chính cú promote, một người chạy runbook, hay chưa có gì? | `production` + `deploy` | có hỏi |
|
|
149
|
+
| 2 | Còn ai khác làm ở đây — một mình bạn, một team, hay có cả người ngoài? | `room` | tuỳ chọn — `colab adopt --axis room` |
|
|
150
|
+
| 3 | Merge nhầm thì cái gì hỏng — không gì cả, chỉ những người đang có mặt, người dùng qua lần promote kế tiếp, hay người dùng/người adopt qua một artifact đã phát hành? | `exposure` | có hỏi — người thật trả lời |
|
|
151
|
+
| 4 | Một người có được commit thẳng vào trunk song song với các phiên worktree không — tự do, có khai ý định, hay không bao giờ? | `writes` | tuỳ chọn — `colab adopt --axis writes` |
|
|
152
|
+
| 5 | Code đi tới chỗ nó chạy bằng đường nào — một workflow CI, một git hook, một quy trình tay có ghi lại, một checkout đang sống, một artifact phát hành, dữ liệu của hệ thống khác, hay chưa có đường nào? | `channels` | tuỳ chọn — `colab adopt --axis channels` |
|
|
153
|
+
|
|
154
|
+
**Trả lời câu 3 là việc của người thật** khi câu trả lời là "không gì cả" hoặc
|
|
155
|
+
"chỉ những người đang có mặt". Agent làm được mọi phần còn lại; tới bước đó,
|
|
156
|
+
`colab adopt` in ra, ngay dòng đầu tiên, đúng một lệnh để người thật chạy.
|
|
157
|
+
|
|
158
|
+
Không câu nào hỏi cái repo đã tự nói sẵn — nhánh mặc định (`trunk`, giữ nguyên
|
|
159
|
+
như đang có: nhánh mặc định tên `master` vẫn hợp lệ, không cần đổi tên), toolchain,
|
|
160
|
+
port đều được tự dò. Số cổng, nghi thức release và việc có bắt buộc phải có
|
|
161
|
+
nhánh hay không đều suy ra từ câu trả lời. Mỗi câu trả lời quy về đâu, và vì
|
|
162
|
+
sao: [`CONVENTIONS.md` §2](CONVENTIONS.md#2-tiers) và
|
|
163
|
+
[§9](CONVENTIONS.md#9-adopting-this); từng field:
|
|
164
|
+
[`project.schema.md`](project.schema.md).
|
|
165
|
+
|
|
166
|
+
## Adopt vào một repo
|
|
167
|
+
|
|
168
|
+
**Đường mặc định: chạy `/handbook-sync` trong một phiên agent ngay trong repo
|
|
169
|
+
đó.** Nó nhận ra repo chưa adopt gì và đi hết đường adopt — descriptor (qua
|
|
170
|
+
`colab adopt`), label, block `CLAUDE.md`, CI từ template, và đăng ký trên máy
|
|
171
|
+
này. Chạy lại về sau, chính skill đó kéo một repo đã adopt lên bản handbook mới
|
|
172
|
+
nhất mà không làm mất phần bạn đã sửa.
|
|
173
|
+
|
|
174
|
+
Làm bằng tay thì cũng đúng các bước đó (checklist đầy đủ:
|
|
175
|
+
[`CONVENTIONS.md` §9](CONVENTIONS.md#9-adopting-this)):
|
|
176
|
+
|
|
177
|
+
1. `colab adopt` — trả lời hai câu hỏi về cổng và ghi `.github/project.yml`. Nó dừng ở
|
|
178
|
+
đó và in ra các bước còn lại.
|
|
179
|
+
2. `colab labels --ensure` — các label quy ước không có sẵn. Một check mà label
|
|
180
|
+
của nó chưa từng được tạo thì không bao giờ chạy được.
|
|
181
|
+
3. Dán [`templates/repo-CLAUDE-block.md`](templates/repo-CLAUDE-block.md) vào
|
|
182
|
+
`CLAUDE.md` của repo — đây là cách agent phát hiện ra bộ quy ước.
|
|
183
|
+
4. Đảm bảo CI đạt hai kết quả bắt buộc: quét secret và build, với phiên bản
|
|
184
|
+
toolchain **resolve từ manifest của chính repo**, không bao giờ hardcode.
|
|
185
|
+
Copy template từ [`templates/`](templates/) nếu thấy tiện.
|
|
186
|
+
5. `colab register` — đưa repo vào danh sách fleet của máy này, để cả audit lẫn
|
|
187
|
+
bộ cấp port đều biết tới nó.
|
|
188
|
+
|
|
189
|
+
Mấy flag của `colab adopt` nên biết:
|
|
190
|
+
|
|
191
|
+
- `--autonomy auto-trunk` — ghi lại quyền maintainer cấp cho agent tự hoàn tất
|
|
192
|
+
cú merge vào trunk qua `colab ship` (không bao giờ là release). Cần người.
|
|
193
|
+
- `--land` — commit những gì lần chạy này ghi thẳng vào trunk rồi push, để
|
|
194
|
+
nhánh feature đầu tiên được xét theo luật mới. Cần người (`COLAB_HUMAN=1`
|
|
195
|
+
kèm `--answered-by`).
|
|
196
|
+
- `--fork` — repo bám theo một upstream không phải của bạn (tự dò khi có remote
|
|
197
|
+
tên `upstream`); khi đó block `CLAUDE.md` chỉ được nối thêm, không bị cấu trúc
|
|
198
|
+
lại, và workflow agent riêng của upstream được nêu tên.
|
|
199
|
+
- `--local` — bạn hoàn toàn không commit được vào repo này; mọi thứ nằm trong
|
|
200
|
+
bản clone của bạn ([*Working in a repo you don't
|
|
201
|
+
own*](CONVENTIONS.md#working-in-a-repo-you-dont-own)).
|
|
202
|
+
|
|
203
|
+
Nhánh có sẵn từ trước được **giữ nguyên** (grandfathered). Đừng đổi tên gì cả.
|
|
204
|
+
|
|
205
|
+
## Tuỳ biến một skill cho repo của bạn
|
|
206
|
+
|
|
207
|
+
Muốn một skill chạy khác đi ở một repo — comment Issue bằng tiếng Nhật, thêm
|
|
208
|
+
một bước kiểm tra trước wrap? Đừng fork skill: bản fork không còn nhận cập nhật
|
|
209
|
+
từ handbook. Hãy viết phần khác biệt vào `.colab/skills/<skill>.md` (ví dụ
|
|
210
|
+
`.colab/skills/code-wrap.md`), bằng văn xuôi thường. Mỗi skill đọc file đó
|
|
211
|
+
trước các bước của chính nó, và nội dung file thắng phần chữ của skill trong
|
|
212
|
+
repo đó. Nó không bao giờ nới một cổng của `colab`: claim hay merge đã bị từ
|
|
213
|
+
chối thì vẫn bị từ chối. Hãy gọi bước bạn muốn chỉnh theo số của nó (`code-ship`
|
|
214
|
+
B1c, `code-sweep` §3): một skill lớn gồm một phần lõi ngắn cộng các file tham
|
|
215
|
+
chiếu, và phần lõi giữ số của mọi bước.
|
|
216
|
+
|
|
217
|
+
Claude Code tự nạp file vào skill. Các engine khác có một câu thường trong mỗi
|
|
218
|
+
skill bảo agent đọc file, cách này chạy được mà không cần engine hỗ trợ gì.
|
|
219
|
+
Vì file này ra lệnh cho agent, thay đổi trong nó không bao giờ được coi là
|
|
220
|
+
docs-only: nó merge bằng `auto-trunk` hoặc khi có người duyệt, giống một thay đổi
|
|
221
|
+
`CLAUDE.md`. Quy tắc:
|
|
222
|
+
[`CONVENTIONS.md` §8, *Local policy*](CONVENTIONS.md#local-policy--a-repo-refines-a-skill-without-forking-it-520).
|
|
223
|
+
|
|
224
|
+
## Tự động hoá tùy chọn, đặt lên trên
|
|
225
|
+
|
|
226
|
+
Không có gì ở đây giả định đã có dashboard, scheduler hay bot. Người adopt vẫn
|
|
227
|
+
có thể tự dựng: mở phiên từ một nút bấm, chạy vòng làm việc theo lịch, coi cú
|
|
228
|
+
bấm nút merge của một người là cái gật đầu mà `code-ship` đang chờ, hay đẩy
|
|
229
|
+
thông báo khi việc đổi trạng thái. Tool như vậy đọc đúng những artefact chung mà
|
|
230
|
+
con người đọc — `.github/project.yml`, label, claim trên từng Issue, file
|
|
231
|
+
`~/.colab/state.json` trên máy — và có thể nhận event của `colab` ở `notifyUrl`
|
|
232
|
+
([`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default)).
|
|
233
|
+
Nó không bao giờ thay đổi một cổng của `colab`: cái gật đầu trước khi merge và
|
|
234
|
+
quyền cấp trước khi chạy migration vẫn đứng vững dù có nó hay không.
|
|
116
235
|
|
|
117
236
|
## Cấu trúc repo
|
|
118
237
|
|
|
@@ -121,153 +240,100 @@ duy nhất** — mọi thứ còn lại trong repo chỉ phục vụ nó.
|
|
|
121
240
|
| [`CONVENTIONS.md`](CONVENTIONS.md) | Luật. Chuẩn tắc, nguồn sự thật duy nhất (EN). |
|
|
122
241
|
| [`CLAUDE.md`](CLAUDE.md) | Cửa vào cho AI agent — bản chưng cất vận hành (EN). |
|
|
123
242
|
| [`project.schema.md`](project.schema.md) | Tham chiếu field của `.github/project.yml`. |
|
|
124
|
-
| [`templates/`](templates/) | Điểm khởi đầu **copy-về-là-của-bạn**: CI, release, git hook (một bản quét secret và một bản quét danh tính), và block `CLAUDE.md` cho repo adopt.
|
|
125
|
-
| [`tools/`](tools/) | `colab` — một CLI nhỏ (tùy chọn): adopt một repo, claim issue, cấp port, quản lý worktree, và merge nhánh đã xong vào trunk khi repo cho phép. State JSON, không dependency. Tham chiếu
|
|
126
|
-
| [`audit/`](audit/) | Trình kiểm tra conformance từ bên ngoài. Đọc mọi repo của bạn — mọi owner, kể cả repo local-only — và báo drift trong một lần chạy. Chỉ cảnh báo
|
|
127
|
-
| [`skills/`](skills/) |
|
|
128
|
-
| [`install.sh`](install.sh) | Cài đặt cho **máy của bạn**: skills, CLI `colab`, hook pre-commit, danh sách
|
|
129
|
-
|
|
130
|
-
## Cài CLI từ npm
|
|
131
|
-
|
|
132
|
-
CLI `colab` còn được phát hành dạng package npm công khai **`@futurelastic/colab-handbook`**. Lệnh bạn gõ vẫn là `colab`.
|
|
133
|
-
|
|
134
|
-
```sh
|
|
135
|
-
npx @futurelastic/colab-handbook <lệnh> # chạy một lần, không cài gì, không cần tài khoản npm
|
|
136
|
-
npm i -g @futurelastic/colab-handbook # rồi: colab <lệnh>
|
|
137
|
-
npm i -g @futurelastic/colab-handbook@next # bản ứng viên (vX.Y.Z-rc.N) thay vì bản final
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
Package chỉ chứa những gì `colab` đọc lúc chạy — CLI, `lib/`, `templates/` và `audit/audit.mjs` — không gì khác; `colab template` và `colab adopt` chạy được từ bản trên registry và đóng dấu đúng version của package. Các skill **không** nằm trong đó: chúng cài bằng `./install.sh` từ một bản clone (xem bên dưới), vì phải symlink vào `~/.claude/skills/`. Mỗi tarball được CI đối chiếu từng file với allowlist (`scripts/check-pack-allowlist.mjs`).
|
|
243
|
+
| [`templates/`](templates/) | Điểm khởi đầu **copy-về-là-của-bạn**: CI, release, git hook (một bản quét secret và một bản quét danh tính), và block `CLAUDE.md` cho repo adopt. Không có gì được gọi từ xa — copy, sửa, sở hữu. |
|
|
244
|
+
| [`tools/`](tools/) | `colab` — một CLI nhỏ (tùy chọn): adopt một repo, claim issue, cấp port, quản lý worktree, và merge nhánh đã xong vào trunk khi repo cho phép. State JSON, không dependency. Tham chiếu các lệnh: [`tools/README.md`](tools/README.md). |
|
|
245
|
+
| [`audit/`](audit/) | Trình kiểm tra conformance từ bên ngoài. Đọc mọi repo của bạn — mọi owner, kể cả repo local-only — và báo drift trong một lần chạy. Chỉ cảnh báo. Thêm `--identity` thì quét cả description và topic của repo public — thứ mà không git hook nào nhìn thấy được. Ý nghĩa từng check: [`audit/README.md`](audit/README.md). |
|
|
246
|
+
| [`skills/`](skills/) | Luồng phiên làm việc — xem [*Phiên làm việc đầu tiên*](#phiên-làm-việc-đầu-tiên). `install.sh` cài chúng thành skill Claude Code. |
|
|
247
|
+
| [`install.sh`](install.sh) | Cài đặt cho **máy của bạn**: skills, CLI `colab`, hook pre-commit, danh sách fleet. Idempotent; `--dry` cho xem trước mọi thứ. |
|
|
141
248
|
|
|
142
249
|
## Cài đặt máy
|
|
143
250
|
|
|
144
|
-
Làm một lần cho mỗi máy
|
|
251
|
+
Làm một lần cho mỗi máy. Clone vào chỗ ở lâu dài — các skill là symlink trỏ
|
|
252
|
+
*thẳng vào working tree này*, nên repo đang checkout cái gì thì mọi phiên dùng
|
|
253
|
+
đúng bản skill đó. `install.sh` kiểm tra đủ điều kiện trước khi đụng vào gì,
|
|
254
|
+
không bao giờ ghi đè thứ nó không tạo ra, và `--dry` in kế hoạch ra trước.
|
|
145
255
|
|
|
146
|
-
**
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
256
|
+
**Bạn nhận phiên bản nào.** `main` chạy trước bản phát hành chính thức cuối
|
|
257
|
+
cùng, nên lần cài đầu tiên từ một bản clone mới sẽ checkout **tag phát hành
|
|
258
|
+
chính thức mới nhất** (`vX.Y.Z`, không bao giờ là bản ứng viên) rồi cài từ đó —
|
|
259
|
+
giống mặc định của npm. Muốn theo `main`, kể cả phần chưa phát hành, thì chạy
|
|
260
|
+
lần cài đầu với `--trunk`. Lần chạy nào cũng in ra bạn đang ở bản nào. Đổi về
|
|
261
|
+
sau đều phải chủ động:
|
|
152
262
|
|
|
153
|
-
|
|
154
|
-
|
|
263
|
+
- lên bản phát hành mới hơn: `./install.sh --release`;
|
|
264
|
+
- từ một bản phát hành quay về `main`: `git checkout main && ./install.sh --trunk`
|
|
265
|
+
(installer của bản phát hành cũ không biết `--trunk`, nên checkout `main` trước).
|
|
155
266
|
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
cd ~/code/colab-handbook
|
|
159
|
-
```
|
|
160
|
-
|
|
161
|
-
**Bản clone này là hạ tầng, không phải file tải về xem cho biết.** Các skill
|
|
162
|
-
được cài bằng symlink trỏ *thẳng vào working tree này*: xoá clone đi là mọi
|
|
163
|
-
phiên trên máy mất skill, và repo đang checkout nhánh nào thì mọi phiên dùng
|
|
164
|
-
đúng bản skill của nhánh đó. Nên khi không trực tiếp sửa handbook, hãy để nó ở
|
|
165
|
-
`main`. `install.sh` sẽ cảnh báo nếu thấy mình đang nằm trong `/tmp`,
|
|
166
|
-
`~/Downloads` hay `~/Desktop`.
|
|
167
|
-
|
|
168
|
-
**2. Cài.**
|
|
169
|
-
|
|
170
|
-
```sh
|
|
171
|
-
./install.sh --all --dry # xem trước sẽ làm gì; không thay đổi gì cả
|
|
172
|
-
./install.sh --all # skills + CLI colab + hook pre-commit + danh sách repo
|
|
173
|
-
```
|
|
174
|
-
|
|
175
|
-
`--all` là lựa chọn nên dùng cho lần chạy đầu. Mọi thứ nó làm đều là symlink
|
|
176
|
-
hoặc copy, chạy lại bao nhiêu lần cũng được, và không bao giờ ghi đè thứ nó
|
|
177
|
-
không tạo ra — skill của riêng bạn, hay `~/.colab/repos.txt` đã có sẵn, đều được
|
|
178
|
-
giữ nguyên kèm một dòng cảnh báo. Chạy trơn `./install.sh` thì chỉ cài skills,
|
|
179
|
-
nếu bạn thật sự chỉ cần bấy nhiêu.
|
|
267
|
+
Clone đang có thay đổi chưa commit thì không bao giờ bị chuyển, và chạy lại
|
|
268
|
+
không kèm flag nào thì giữ nguyên thứ đang checkout.
|
|
180
269
|
|
|
181
270
|
| Flag | Làm gì |
|
|
182
271
|
|---|---|
|
|
183
272
|
| *(không có)* | Symlink `skills/` vào `~/.claude/skills/`, để mở repo nào cũng có. |
|
|
184
|
-
| `--tools` |
|
|
185
|
-
| `--hooks` | Trỏ git của clone này vào `.githooks
|
|
186
|
-
| `--fleet` | Tạo `~/.colab/repos.txt`
|
|
273
|
+
| `--tools` | CLI `colab` cài hai lần: một **symlink** ở `~/.local/bin/colab` cho các phiên làm việc của bạn (in sẵn dòng `PATH` nếu cần), và một **bản đóng băng** có đóng dấu ở `~/.colab/bin/colab` cho các service luôn-bật. Đồng thời tạo `~/.colab/state.json` rỗng nếu chưa có. |
|
|
274
|
+
| `--hooks` | Trỏ git của clone này vào `.githooks/`: quét secret bằng gitleaks, và quét danh tính với danh sách từ khoá do bạn giữ NGOÀI mọi repo (xem [`templates/README.md`](templates/README.md)). |
|
|
275
|
+
| `--fleet` | Tạo `~/.colab/repos.txt` chỉ chứa ghi chú định dạng, nếu chưa có. Nó cố tình nằm trên máy vì nó ghi tên các repo private của bạn; `colab register` mới là thứ điền vào. |
|
|
187
276
|
| `--all` | `--tools --hooks --fleet`. |
|
|
188
|
-
| `--notify-url <url>` | Ghi `notifyUrl` vào `~/.colab/config.json
|
|
189
|
-
| `--
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
phục được quảng cáo lại copy *từ* chính cây làm việc đó — nên trên máy đang phát
|
|
210
|
-
triển handbook, nó khuyên các service nạp code chưa phát hành.) Nó không bao giờ
|
|
211
|
-
ghi đè bản copy, kể cả với `--apply`: đó là bộ công cụ mà các service đang chạy
|
|
212
|
-
của bạn đang thực thi. `colab --version` cho biết bạn đang nói chuyện với bản nào (hoặc `npm package` khi
|
|
213
|
-
cài qua `npx`/`npm i`), kèm phiên bản của chính bản đó.
|
|
214
|
-
|
|
215
|
-
**3. Kiểm lại, rồi chỉ cho audit biết phải soi repo nào.**
|
|
277
|
+
| `--notify-url <url>` | Ghi `notifyUrl` vào `~/.colab/config.json`, chỉ khi khoá đó chưa có. Xem [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
|
|
278
|
+
| `--release` | Checkout clone này về tag phát hành chính thức mới nhất, rồi cài. Là mặc định cho lần cài đầu từ một bản clone mới. |
|
|
279
|
+
| `--trunk` | Checkout `main` rồi cài, kể cả phần chưa phát hành — `@next` của bản clone. |
|
|
280
|
+
| `--dry` | In ra sẽ làm gì, không thay đổi gì. Ghép được với các flag trên. |
|
|
281
|
+
| `--check` | Báo cáo sức khoẻ **chỉ đọc** cho một lần cài trước đó — xem bên dưới. Không nhận flag nào khác; exit 1 nếu có dòng ✗. |
|
|
282
|
+
|
|
283
|
+
**Service luôn-bật (launch agent, daemon, runner headless) phải gọi
|
|
284
|
+
`~/.colab/bin/colab`, không gọi symlink**, vì symlink chạy theo đúng nhánh mà
|
|
285
|
+
clone này đang checkout. Bản đóng băng không bao giờ tự thay đổi: `colab update`
|
|
286
|
+
báo khi nó tụt sau một thay đổi CLI đã phát hành, và chạy lại `./install.sh
|
|
287
|
+
--tools` để làm mới. Vì sao lại làm vậy:
|
|
288
|
+
[`tools/README.md`](tools/README.md#install).
|
|
289
|
+
|
|
290
|
+
**Chỉ cần CLI, không cần skill** thì có trên npm: **`@futurelastic/colab-handbook`**.
|
|
291
|
+
Chưa có bản phát hành chính thức nào lên npm, nên tag mặc định `latest` chỉ là
|
|
292
|
+
bản giữ chỗ; hãy cài từ **`@next`**, các bản ứng viên: `npx
|
|
293
|
+
@futurelastic/colab-handbook@next <lệnh>`, hoặc `npm i -g
|
|
294
|
+
@futurelastic/colab-handbook@next`. Lệnh gõ vẫn là `colab`. Skill không nằm trong package; chúng cài từ một bản clone, vì phải
|
|
295
|
+
symlink vào `~/.claude/skills/`.
|
|
296
|
+
|
|
297
|
+
### Kiểm tra bản cài
|
|
216
298
|
|
|
217
299
|
```sh
|
|
218
|
-
colab --
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
colab update # các bản copy có đóng dấu đã tụt lại — kể cả CLI đóng băng
|
|
300
|
+
colab --version # colab nào đang trả lời — working tree, bản đóng băng hay npm package — và phiên bản của nó
|
|
301
|
+
./install.sh --check # chỉ đọc; exit 1 nếu có dòng ✗
|
|
302
|
+
node audit/audit.mjs # báo cáo conformance cho mọi repo đã đăng ký
|
|
303
|
+
colab update # các bản copy có đóng dấu đã tụt lại, kể cả CLI đóng băng
|
|
223
304
|
```
|
|
224
305
|
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
không phải "sắp có").
|
|
235
|
-
2. Thêm `.github/project.yml`. `colab adopt` hỏi năm câu rồi ghi file giùm bạn —
|
|
236
|
-
nó dừng ở phần descriptor và in ra phần còn lại của danh sách này, vì mấy
|
|
237
|
-
bước sau không phải việc của nó.
|
|
238
|
-
3. `colab labels --ensure` — các label quy ước không có sẵn, và không phải chỉ
|
|
239
|
-
một cái. Một check mà label của nó chưa từng được tạo thì không bao giờ chạy
|
|
240
|
-
được.
|
|
241
|
-
4. Dán [`templates/repo-CLAUDE-block.md`](templates/repo-CLAUDE-block.md) vào
|
|
242
|
-
`CLAUDE.md` của repo — đây là cách duy nhất để agent phát hiện ra bộ quy ước
|
|
243
|
-
này.
|
|
244
|
-
5. Đảm bảo CI đạt hai kết quả bắt buộc: quét secret và build, với phiên bản
|
|
245
|
-
toolchain **resolve từ manifest của chính repo** — không bao giờ hardcode.
|
|
246
|
-
Copy template nếu thấy tiện.
|
|
247
|
-
|
|
248
|
-
Nhánh có sẵn từ trước được **giữ nguyên** (grandfathered). Đừng đổi tên gì cả.
|
|
249
|
-
|
|
250
|
-
**Làm việc trong repo không phải của mình?** Nếu không thể commit các file này vào đó,
|
|
251
|
-
`colab adopt --local` giữ mọi thứ trong bản clone local của bạn, không có gì lọt vào lịch sử
|
|
252
|
-
của chủ repo — xem
|
|
253
|
-
[*Working in a repo you don't own*](CONVENTIONS.md#working-in-a-repo-you-dont-own).
|
|
306
|
+
`--check` báo bản đóng băng có tụt sau bản phát hành mới nhất không và lệnh nào
|
|
307
|
+
nó không chạy được, file state có tồn tại không, đã đăng ký repo nào chưa, cả
|
|
308
|
+
hai hooklet pre-commit có chạy được không, và `notifyUrl` có đang trống trong
|
|
309
|
+
khi một observer trên máy đã khai endpoint không. ✗ nghĩa là thứ đã cài đang cũ
|
|
310
|
+
hoặc không dùng được; ⚠ nghĩa là có thứ chưa từng được cài, có thể là cố ý hoặc
|
|
311
|
+
chỉ là chưa làm tới — nên một bản cài mới đúng, chưa đăng ký repo nào và chưa có
|
|
312
|
+
danh sách từ khoá danh tính, sẽ ra các dòng ⚠ và exit 0. Nó không bao giờ tự làm
|
|
313
|
+
mới gì cả. `--check` không có trong v1.11.0 trở về trước; ở những bản đó, hãy theo
|
|
314
|
+
`main` để có nó.
|
|
254
315
|
|
|
255
316
|
## Vì sao ép buộc ít vậy
|
|
256
317
|
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
**
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
một khi đã có người clone.
|
|
269
|
-
|
|
270
|
-
|
|
318
|
+
Không phải gói GitHub nào, owner nào trong một fleet cũng có branch protection,
|
|
319
|
+
nên handbook này không dựa vào nó. Thay vào đó nó làm cho việc **tuân thủ rẻ và
|
|
320
|
+
việc kiểm tra rẻ**: audit báo drift, còn quy ước giải thích *vì sao* từng luật
|
|
321
|
+
tồn tại để bạn tự phán đoán khi nào đáng phá luật. Khi phá, hãy sửa tài liệu
|
|
322
|
+
trong cùng thay đổi đó — một tài liệu mô tả một repo không tồn tại là thứ tệ
|
|
323
|
+
nhất trong nghề này.
|
|
324
|
+
|
|
325
|
+
**Một danh sách ngắn thì chặn thật, và là cố ý:**
|
|
326
|
+
|
|
327
|
+
- **Phát hành ra ngoài.** Git hook từ chối secret, và bản quét danh tính chặn
|
|
328
|
+
tên máy, đường dẫn home hay tên khách hàng lọt vào một repo public. History
|
|
329
|
+
không thu hồi lại được một khi đã có người clone.
|
|
330
|
+
- **Các cổng quanh cú merge**, do `colab` canh: người phải đồng ý trước khi
|
|
331
|
+
merge (trừ khi repo đã cấp `auto-trunk` hoặc thay đổi chỉ là docs), phải có
|
|
332
|
+
quyền cấp trước khi một migration được ship, và release không bao giờ đi kèm
|
|
333
|
+
cú merge.
|
|
334
|
+
|
|
335
|
+
Mọi thứ khác là mặc định — một cách làm tốt — vì sai một quy ước thì chỉ tốn
|
|
336
|
+
một cuộc trao đổi.
|
|
271
337
|
|
|
272
338
|
## Giấy phép
|
|
273
339
|
|