docs(vi): sync Vietnamese docs with English
This commit is contained in:
Loc Duong
parent
1da6bf80df
commit
f9171f9bb0
19
README_VN.md
19
README_VN.md
|
|
@ -2,14 +2,14 @@
|
|||
|
||||
[](https://www.npmjs.com/package/bmad-method)
|
||||
[](LICENSE)
|
||||
[](https://nodejs.org)
|
||||
[](https://nodejs.org)
|
||||
[](https://www.python.org)
|
||||
[](https://docs.astral.sh/uv/)
|
||||
[](https://discord.gg/gk8jAdXWmj)
|
||||
|
||||
[English](README.md) | [简体中文](README_CN.md) | Tiếng Việt
|
||||
|
||||
**Build More Architect Dreams** - một mô-đun khung phát triển hướng AI trong hệ sinh thái BMad, có khả năng thích ứng theo quy mô từ sửa lỗi nhỏ đến các hệ thống doanh nghiệp.
|
||||
**Build More Architect Dreams** - một mô-đun phát triển agile hướng AI trong hệ sinh thái module BMad Method, framework phát triển Agile AI Driven tốt nhất và toàn diện nhất, với trí thông minh thích ứng thật sự theo quy mô từ sửa lỗi nhỏ đến các hệ thống doanh nghiệp.
|
||||
|
||||
**100% miễn phí và mã nguồn mở.** Không có tường phí. Không có nội dung bị khóa. Không có Discord giới hạn quyền truy cập. Chúng tôi tin vào việc trao quyền cho mọi người, không chỉ cho những ai có thể trả tiền để vào một cộng đồng hay khóa học khép kín.
|
||||
|
||||
|
|
@ -20,7 +20,7 @@ Các công cụ AI truyền thống thường làm thay phần suy nghĩ của b
|
|||
- **Trợ giúp AI thông minh** - Gọi skill `bmad-help` bất kỳ lúc nào để biết bước tiếp theo
|
||||
- **Thích ứng theo quy mô và miền bài toán** - Tự động điều chỉnh độ sâu lập kế hoạch theo độ phức tạp của dự án
|
||||
- **Quy trình có cấu trúc** - Dựa trên các thực hành tốt nhất của agile xuyên suốt phân tích, lập kế hoạch, kiến trúc và triển khai
|
||||
- **Agent chuyên biệt** - Hơn 12 chuyên gia theo vai trò như PM, Architect, Developer, UX, Scrum Master và nhiều vai trò khác
|
||||
- **Agent chuyên biệt** - Hơn 12 chuyên gia theo vai trò như PM, Architect, Developer, UX và nhiều vai trò khác
|
||||
- **Party Mode** - Đưa nhiều persona agent vào cùng một phiên để cộng tác và thảo luận
|
||||
- **Vòng đời hoàn chỉnh** - Từ động não ý tưởng cho đến triển khai
|
||||
|
||||
|
|
@ -38,7 +38,7 @@ Các công cụ AI truyền thống thường làm thay phần suy nghĩ của b
|
|||
|
||||
## Bắt đầu nhanh
|
||||
|
||||
**Điều kiện tiên quyết**: [Node.js](https://nodejs.org) v20+ · [Python](https://www.python.org) 3.10+ · [uv](https://docs.astral.sh/uv/)
|
||||
**Điều kiện tiên quyết**: [Node.js](https://nodejs.org) v20.12+ · [Python](https://www.python.org) 3.10+ · [uv](https://docs.astral.sh/uv/)
|
||||
|
||||
```bash
|
||||
npx bmad-method install
|
||||
|
|
@ -54,6 +54,15 @@ Làm theo các lời nhắc của trình cài đặt, sau đó mở AI IDE của
|
|||
npx bmad-method install --directory /path/to/project --modules bmm --tools claude-code --yes
|
||||
```
|
||||
|
||||
Ghi đè bất kỳ tùy chọn cấu hình module nào bằng `--set <module>.<key>=<value>` (có thể lặp lại). Chạy `--list-options [module]` để xem các key chính thức mà máy hiện biết (module tích hợp sẵn cộng với mọi module chính thức bên ngoài đã được cache trên máy này):
|
||||
|
||||
```bash
|
||||
npx bmad-method install --yes \
|
||||
--modules bmm --tools claude-code \
|
||||
--set bmm.project_knowledge=research \
|
||||
--set bmm.user_skill_level=expert
|
||||
```
|
||||
|
||||
[Xem toàn bộ tùy chọn cài đặt](https://docs.bmad-method.org/vi-vn/how-to/non-interactive-installation/)
|
||||
|
||||
> **Chưa chắc nên làm gì?** Hãy hỏi `bmad-help` - nó sẽ cho bạn biết chính xác bước nào tiếp theo và bước nào là tùy chọn. Bạn cũng có thể hỏi kiểu như `bmad-help Tôi vừa hoàn thành phần kiến trúc, tiếp theo tôi cần làm gì?`
|
||||
|
|
@ -106,4 +115,4 @@ Giấy phép MIT - xem [LICENSE](LICENSE) để biết chi tiết.
|
|||
|
||||
[](https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors)
|
||||
|
||||
Xem [CONTRIBUTORS.md](CONTRIBUTORS.md) để biết thông tin về những người đóng góp.
|
||||
Xem [CONTRIBUTORS.md](CONTRIBUTORS.md) để biết thông tin về những người đóng góp.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,94 @@
|
|||
---
|
||||
title: "Điều tra pháp chứng"
|
||||
description: Cách bmad-investigate đối xử với mọi vấn đề như một hiện trường, chấm cấp bằng chứng và tạo hồ sơ vụ án có cấu trúc để engineer hành động
|
||||
sidebar:
|
||||
order: 6
|
||||
---
|
||||
|
||||
Bạn đưa cho `bmad-investigate` một crash log, stack trace, hoặc chỉ một câu "trước đây chạy được, giờ thì không". Skill sẽ tiếp quản kỷ luật của điều tra viên trong suốt lần chạy. Nó không lao vào sửa. Nó mở một hồ sơ vụ án.
|
||||
|
||||
Mọi phát hiện đều được chấm cấp. Mọi giả thuyết đều có trạng thái. Những hướng đi sai được giữ lại, không bị xóa. Đầu ra là một tài liệu mà một engineer khác có thể mở ra và hiểu ngay dù chưa có bối cảnh trước đó.
|
||||
|
||||
Trang này giải thích vì sao điều tra là một kỷ luật riêng, và skill đem lại điều gì mà workflow dev thông thường không có.
|
||||
|
||||
## Vấn đề của "cứ debug đi"
|
||||
|
||||
Debug thông thường trộn ba việc: nhìn bằng chứng, suy luận nguyên nhân và đổi code để thử lý thuyết. Khi ba việc này bị trộn lẫn, hai kiểu lỗi hay xuất hiện.
|
||||
|
||||
Thứ nhất là **khóa chặt vào câu chuyện ban đầu**. Câu chuyện hợp lý đầu tiên trở thành giả thuyết làm việc, rồi mọi quan sát bị uốn theo nó. Bug vẫn không sửa được cho tới khi ai đó bỏ cuộc và bắt đầu lại. Vài giờ sau.
|
||||
|
||||
Thứ hai là **mất trí nhớ bằng chứng**. Bạn đã truy vết một hướng, đã loại nó ra, nhưng không ghi lại vì sao. Hai ngày sau, với góc nhìn mới, bạn lại truy vết đúng hướng đó. Hoặc tệ hơn, một đồng nghiệp nhận bug và chạy lại đúng ngõ cụt bạn đã loại bỏ.
|
||||
|
||||
Thiết kế của skill là phản ứng trực tiếp với cả hai vấn đề này.
|
||||
|
||||
## Chấm cấp bằng chứng
|
||||
|
||||
Mọi phát hiện trong một cuộc điều tra thuộc một trong ba loại.
|
||||
|
||||
- **Đã xác nhận.** Được quan sát trực tiếp trong log, code hoặc dump; có trích dẫn cụ thể như `path:line`, timestamp log hoặc commit hash. Nếu ai hỏi "làm sao bạn biết?", bạn chỉ vào citation.
|
||||
- **Được suy ra.** Theo logic từ bằng chứng đã xác nhận; chuỗi suy luận được trình bày. Nếu một bước trong chuỗi sai, kết luận suy ra sai, và bạn thấy chính xác bước nào.
|
||||
- **Giả thuyết.** Hợp lý nhưng chưa được xác nhận. Nêu rõ bằng chứng nào sẽ xác nhận hoặc bác bỏ, và nói trước điều gì sẽ khép lại giả thuyết. Giả thuyết rõ ràng *không phải sự thật*.
|
||||
|
||||
Việc chấm cấp không phải để tỏ ra khiêm tốn. Nó giúp hồ sơ vụ án dễ đọc. Người đọc có thể quét phần Đã xác nhận để biết điều gì là thật, phần Được suy ra để biết điều gì kéo theo từ đó, và phần Giả thuyết để biết điều gì còn mở. Lẫn lộn ba loại này là lý do phổ biến nhất khiến điều tra xoáy vòng.
|
||||
|
||||
## Bám vào cứ điểm trước
|
||||
|
||||
Điều tra không bắt đầu từ một lý thuyết. Nó bắt đầu từ một mẩu bằng chứng đã xác nhận rồi mở rộng ra. Bằng chứng đó có thể là một thông báo lỗi cụ thể, một stack frame hoặc một dòng log có timestamp.
|
||||
|
||||
Điều này ngược với cách điều tra thường diễn ra. Ai đó có linh cảm, dựng lý thuyết, rồi săn bằng chứng ủng hộ. Linh cảm có thể đúng; *phương pháp* thì mong manh vì nó biến thiên kiến xác nhận thành mặc định.
|
||||
|
||||
Cứ điểm là một sự thật bạn có thể quay lại khi suy luận trở nên mơ hồ. Nếu một suy luận đưa bạn tới chỗ kỳ lạ, bạn có thể lần ngược về cứ điểm rồi thử một nhánh khác. Không có cứ điểm, bạn không biết phải hoàn tác bước nào.
|
||||
|
||||
Khi bằng chứng thưa thớt, skill nói rõ điều đó và chuyển sang khám phá theo giả thuyết: lập giả thuyết từ những gì đang có, xác định cách kiểm tra từng giả thuyết, rồi đưa ra danh sách thu thập dữ liệu theo ưu tiên. Thiếu bằng chứng tự nó cũng là một phát hiện.
|
||||
|
||||
## Kỷ luật giả thuyết
|
||||
|
||||
Giả thuyết không bao giờ bị xóa khỏi hồ sơ vụ án. Khi bằng chứng xác nhận hoặc bác bỏ một giả thuyết, trường **Status** đổi từ Open sang Confirmed hoặc Refuted, và phần **Resolution** giải thích bằng chứng nào đã kết luận nó.
|
||||
|
||||
Quy tắc này có chi phí thật: hồ sơ dài ra. Lợi ích cũng thật. Toàn bộ lịch sử suy luận trở thành một phần của đầu ra. Sáu tháng sau, khi một bug tương tự xuất hiện, người điều tra tiếp theo có thể đọc hồ sơ cũ và thấy hướng nào đã bị loại, vì sao. Không có lịch sử đó, mỗi điều tra viên mới lại chạy lại cùng các ngõ cụt.
|
||||
|
||||
Nó cũng rèn kỷ luật cho điều tra viên hiện tại. Nếu không thể xóa một giả thuyết sai, bạn phải bác bỏ nó bằng bằng chứng có citation. Lặng lẽ bỏ nó đi khi nó bất tiện không còn là lựa chọn.
|
||||
|
||||
## Thách thức tiền đề
|
||||
|
||||
Mô tả vấn đề của người dùng là một giả thuyết, không phải sự thật. "Cache bị hỏng" là điều người dùng *tin*. Trước khi skill xây cuộc điều tra quanh nó, các khẳng định kỹ thuật được xác minh độc lập. Nếu bằng chứng mâu thuẫn với tiền đề, báo cáo nói thẳng.
|
||||
|
||||
Đó là bản năng pháp chứng: lời khai của nhân chứng là dữ liệu, không phải chân lý. Đôi khi bug được báo là thật nhưng bị đặt nhãn sai. Đôi khi triệu chứng được mô tả lại là hệ quả downstream của nguyên nhân khác. Những cuộc điều tra coi tiền đề là chân lý sẽ chẩn đoán sai lỗi, và bug quay lại dưới hình thức hơi khác.
|
||||
|
||||
## Một bước đi được hiệu chỉnh
|
||||
|
||||
Skill là một quy trình duy nhất, không phải hai chế độ. Nó hiệu chỉnh liên tục mức độ cần săn lỗi cụ thể so với mức độ cần khám phá khu vực hệ thống.
|
||||
|
||||
Một case có triệu chứng như ticket, crash, thông báo lỗi hoặc "trước đây chạy được" sẽ nghiêng về theo dõi giả thuyết, dựng timeline và hướng sửa. Một case không có triệu chứng như hiểu một module trước khi đụng vào, đánh giá khả năng tái sử dụng hoặc xây mô hình tinh thần sẽ nghiêng về mapping input/output, lọc control flow và lập kế hoạch xác minh. Phần lớn case thật nằm giữa hai đầu, và hồ sơ phản ánh đúng sự cân bằng mà bằng chứng đòi hỏi.
|
||||
|
||||
Kỷ luật giữ nguyên dù case nằm ở đâu trên phổ đó: cứ điểm trước, chấm cấp bằng chứng, theo dõi giả thuyết, không xóa. Đầu ra luôn nằm ở `{implementation_artifacts}/investigations/{slug}-investigation.md`, với các phần không áp dụng cho case cụ thể được để trống hoặc bỏ qua.
|
||||
|
||||
Khi một bug sâu đòi hỏi hiểu subsystem rộng hơn, quy trình sẽ gộp các kỹ thuật mapping input/output, lọc control flow, lần ngược từ output và truy vết ranh giới giữa component ngay trong cùng hồ sơ. Mô hình khu vực hệ thống cũng nằm trong hồ sơ vụ án đó. Không có chuyển chế độ.
|
||||
|
||||
## Phương pháp nằm trong skill
|
||||
|
||||
Kỷ luật điều tra là thuộc tính của chính skill. Bất kỳ ai gọi `bmad-investigate` đều nhận lấy phương pháp và phong cách giao tiếp của nó trong lần chạy đó: chính xác lâm sàng, ngôn ngữ đặt bằng chứng trước, không nói lấp lửng, framing như hồ sơ vụ án. Khi skill kết thúc, người gọi quay lại giọng nói trước đó. Không đổi persona, chỉ đổi sắc thái theo nguyên tắc của skill.
|
||||
|
||||
Điều này quan trọng vì điều tra và triển khai thưởng cho hai bản năng khác nhau. Điều tra viên chậm và chính xác. Người triển khai nhanh và tự tin. Cùng một bộ não làm cả hai trong một phiên thường làm không trọn cả hai. Skill tạo ra tư thế điều tra ngay trong luồng làm việc, không cần đổi sang một danh tính riêng.
|
||||
|
||||
## Bạn nhận được gì
|
||||
|
||||
Một hồ sơ điều tra hoàn chỉnh:
|
||||
|
||||
- Tách phát hiện Đã xác nhận (có citation) khỏi Suy luận và Giả thuyết
|
||||
- Giữ mọi giả thuyết từng được lập, cùng Status và Resolution cuối cùng
|
||||
- Dựng lại timeline sự kiện từ nhiều nguồn bằng chứng
|
||||
- Xác định lỗ hổng dữ liệu và điều chúng có thể giải quyết
|
||||
- Đưa ra kết luận có thể hành động, dựa trên bằng chứng
|
||||
- Bao gồm kế hoạch tái hiện khi đã xác định root cause
|
||||
- Duy trì backlog điều tra cho các hướng còn cần khám phá
|
||||
|
||||
Đưa nó cho một engineer không có mặt trong phiên, họ hiểu chuyện gì đã xảy ra, điều gì đã biết và điều gì vẫn còn bất định. Đó là tiêu chuẩn.
|
||||
|
||||
## Ý tưởng lớn hơn
|
||||
|
||||
Phần lớn "AI debugging" hiện nay trộn bằng chứng, suy luận và thay đổi code vào một dòng văn bản nghe có vẻ hợp lý. Tín hiệu khó tìm, ngõ cụt lặp lại, và hồ sơ vụ án, nếu có, chỉ là chat log không ai muốn đọc.
|
||||
|
||||
`bmad-investigate` coi điều tra là một kỷ luật với đầu ra riêng. Bằng chứng có cấp. Giả thuyết có trạng thái. Hướng đi sai được ghi lại, không bị xóa. Hồ sơ vụ án sống lâu hơn phiên làm việc.
|
||||
|
||||
Khi bug tiếp theo xuất hiện và trông giống một bug bạn từng thấy, bạn có chỗ để bắt đầu thay vì một prompt trắng.
|
||||
|
|
@ -84,7 +84,7 @@ Ngoài ra còn có một bề mặt tùy chỉnh thứ hai cho các mối quan t
|
|||
Để xem toàn bộ bề mặt tùy chỉnh và ví dụ thực tế:
|
||||
|
||||
- [Cách tùy chỉnh BMad](../how-to/customize-bmad.md): tài liệu tham chiếu cho những gì có thể tùy chỉnh và merge diễn ra thế nào
|
||||
- [Cách mở rộng BMad cho tổ chức của bạn](../how-to/expand-bmad-for-your-org.md): năm recipe hoàn chỉnh trải từ quy tắc ở cấp agent, convention workflow, publish ra hệ thống ngoài, thay template đầu ra đến tùy chỉnh roster agent
|
||||
- [Cách mở rộng BMad cho tổ chức của bạn](../how-to/expand-bmad-for-your-org.md): sáu recipe hoàn chỉnh trải từ quy tắc ở cấp agent, convention workflow, publish ra hệ thống ngoài, thay template đầu ra, tùy chỉnh roster agent đến các mẫu tích hợp nâng cao
|
||||
- Skill `bmad-customize`: trợ lý soạn cấu hình (authoring helper) có hướng dẫn để biến ý định thành một file override đúng chỗ và đã được kiểm chứng
|
||||
|
||||
## Ý tưởng lớn hơn phía sau
|
||||
|
|
|
|||
|
|
@ -370,7 +370,7 @@ Trong cùng một dự án, bạn hoàn toàn có thể dùng đồng thời c
|
|||
|
||||
## Ví dụ thực chiến
|
||||
|
||||
Để xem các recipe thiên về doanh nghiệp như định hình một agent trên mọi workflow mà nó dispatch, ép workflow tuân thủ convention nội bộ, publish output lên Confluence và Jira, tùy chỉnh agent roster, hoặc thay template đầu ra bằng template riêng của tổ chức, hãy xem [Cách mở rộng BMad cho tổ chức của bạn](./expand-bmad-for-your-org.md).
|
||||
Để xem các recipe thiên về doanh nghiệp như định hình một agent trên mọi workflow mà nó dispatch, ép workflow tuân thủ convention nội bộ, publish output lên Confluence và Jira, tùy chỉnh agent roster, thay template đầu ra bằng template riêng của tổ chức, hoặc cấu hình các mẫu tích hợp nâng cao, hãy xem [Cách mở rộng BMad cho tổ chức của bạn](./expand-bmad-for-your-org.md).
|
||||
|
||||
## Khắc phục sự cố
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
---
|
||||
title: 'Cách mở rộng BMad cho tổ chức của bạn'
|
||||
description: Năm mẫu tùy chỉnh giúp thay đổi BMad mà không cần fork, gồm quy tắc ở cấp agent, quy ước workflow, xuất bản ra hệ thống ngoài, thay template và điều chỉnh danh sách agent
|
||||
description: Sáu mẫu tùy chỉnh giúp thay đổi BMad mà không cần fork, gồm quy tắc ở cấp agent, quy ước workflow, xuất bản ra hệ thống ngoài, thay template, điều chỉnh danh sách agent và các mẫu tích hợp nâng cao
|
||||
sidebar:
|
||||
order: 9
|
||||
---
|
||||
|
||||
Bề mặt tùy chỉnh của BMad cho phép một tổ chức định hình lại hành vi mà không phải sửa file đã cài hay fork skill. Hướng dẫn này trình bày năm công thức mẫu (recipe) bao phủ phần lớn nhu cầu ở môi trường doanh nghiệp.
|
||||
Bề mặt tùy chỉnh của BMad cho phép một tổ chức định hình lại hành vi mà không phải sửa file đã cài hay fork skill. Hướng dẫn này trình bày sáu công thức mẫu (recipe) bao phủ phần lớn nhu cầu ở môi trường doanh nghiệp.
|
||||
|
||||
:::note[Điều kiện tiên quyết]
|
||||
|
||||
|
|
@ -235,9 +235,79 @@ Chỉ một câu, nhưng được nạp ở mọi phiên. Nó kết hợp với
|
|||
|
||||
Hãy giữ file hướng dẫn của IDE **ngắn gọn**. Một tá dòng được chọn kỹ sẽ hiệu quả hơn một danh sách dài lê thê. Model phải đọc file đó ở mọi lượt, và càng nhiều nhiễu thì càng ít tín hiệu.
|
||||
|
||||
## Recipe 6: mẫu tích hợp nâng cao
|
||||
|
||||
Một số workflow BMad mở ra bề mặt cấu hình phong phú hơn các phần cơ bản trong Recipe 1-5. Những mẫu này, gồm nguồn tri thức theo nhu cầu, tự động publish output, chuẩn tài liệu lúc finalize và template có thể thay thế, xuất hiện trong nhiều workflow. Hãy kiểm tra `customize.toml` của workflow để biết nó expose những field nào; các ví dụ dưới đây dùng `bmad-prd` vì workflow này expose đủ các field, nhưng cùng pattern áp dụng ở mọi nơi có field tương ứng.
|
||||
|
||||
### Nguồn tri thức theo nhu cầu (`external_sources`)
|
||||
|
||||
Kết nối workflow với knowledge base nội bộ, cơ sở dữ liệu cạnh tranh hoặc tài liệu compliance. Agent chỉ tham khảo các nguồn này khi cuộc trò chuyện chạm tới nhu cầu phù hợp, không gọi trước một cách vô điều kiện.
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-prd.toml (cùng pattern áp dụng cho mọi workflow expose external_sources)
|
||||
|
||||
[workflow]
|
||||
external_sources = [
|
||||
"Khi người dùng nhắc tới đối thủ hoặc phân khúc thị trường, hãy query corp:competitive_db (category={project_name}) trước khi viết phần differentiation.",
|
||||
"Với domain có yếu tố pháp lý như healthcare, fintech, education, hãy tham khảo corp:compliance_reference trước khi viết các phần domain-specific.",
|
||||
]
|
||||
```
|
||||
|
||||
Mỗi entry là một chỉ dẫn ngôn ngữ tự nhiên nêu tên MCP tool, điều kiện kích hoạt và các field tool cần. Nếu tool không có sẵn lúc chạy, workflow fallback về hành vi chuẩn và ghi nhận khoảng trống đó.
|
||||
|
||||
### Tự động publish output (`external_handoffs`)
|
||||
|
||||
Đưa artifact đã hoàn tất sang các hệ thống nguồn sự thật bên ngoài sau khi workflow finalize. Khác với `on_complete` ở Recipe 3, `external_handoffs` là một mảng append chuyên dụng: entry của team được chồng thêm, và từng handoff chạy độc lập với graceful degradation nếu tool không có sẵn.
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-prd.toml (cùng pattern áp dụng cho mọi workflow expose external_handoffs)
|
||||
|
||||
[workflow]
|
||||
external_handoffs = [
|
||||
"Sau khi finalize, upload prd.md và addendum.md lên Confluence qua corp:confluence_upload (space_key='PROD', parent_page='PRDs', label='prd', author={user_name}). Lưu và hiển thị URL trang được trả về.",
|
||||
"Mirror sang Notion qua notion:create_page (database_id='abc123', title='PRD: ' + {project_name}).",
|
||||
]
|
||||
```
|
||||
|
||||
Nếu một tool được nêu tên không có sẵn, handoff đó bị bỏ qua và được đánh dấu; các file local vẫn luôn tồn tại.
|
||||
|
||||
### Chuẩn tài liệu lúc finalize (`doc_standards`)
|
||||
|
||||
Áp dụng chuẩn viết của tổ chức cho tài liệu dành cho con người ở thời điểm finalize, sau khi nội dung đã hoàn tất nhưng trước khi người dùng nhìn thấy output. Mỗi entry là một chỉ dẫn `skill:`, `file:` hoặc plain-text; các lượt kiểm tra chạy bằng subagent song song.
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-prd.toml (cùng pattern áp dụng cho mọi workflow expose doc_standards)
|
||||
|
||||
[workflow]
|
||||
doc_standards = [
|
||||
"file:{project-root}/docs/enterprise/voice-and-tone.md",
|
||||
"Mọi ngày tháng phải dùng định dạng ISO 8601 (YYYY-MM-DD).",
|
||||
"Thay mọi lần dùng 'leverage' bằng 'use'.",
|
||||
]
|
||||
```
|
||||
|
||||
`doc_standards` là mảng append; entry của team chồng lên mọi mặc định mà workflow đi kèm. Các lượt kiểm tra cấu trúc rộng nên chạy trước các lượt chỉnh văn phong hẹp.
|
||||
|
||||
### Template và checklist có thể thay thế
|
||||
|
||||
Các workflow tạo tài liệu có cấu trúc thường expose đường dẫn template và checklist dưới dạng scalar có thể override. Trỏ chúng tới file do tổ chức sở hữu dưới `{project-root}` để ép cấu trúc khác mà không phải sửa source.
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-prd.toml
|
||||
|
||||
[workflow]
|
||||
# Cấu trúc PRD cho ngành chịu quản lý
|
||||
prd_template = "{project-root}/docs/enterprise/prd-template-hipaa.md"
|
||||
|
||||
# Tiêu chí validation riêng của tổ chức
|
||||
validation_checklist = "{project-root}/docs/enterprise/prd-checklist-regulated.md"
|
||||
```
|
||||
|
||||
Agent thích ứng với bất kỳ cấu trúc nào template định nghĩa. Hãy giữ template trong `{project-root}/docs/` hoặc `{project-root}/_bmad/custom/templates/` để chúng được version cùng file override. Với repo đa tổ chức, dùng `.user.toml` để từng team có thể trỏ tới template riêng mà không đụng vào file dùng chung.
|
||||
|
||||
## Kết hợp các recipe
|
||||
|
||||
Cả năm recipe này có thể kết hợp song song. Một cấu hình doanh nghiệp thực tế cho `bmad-product-brief` hoàn toàn có thể đặt `persistent_facts` theo Recipe 2, `on_complete` theo Recipe 3 và `brief_template` theo Recipe 4 trong cùng một file. Quy tắc ở cấp agent theo Recipe 1 sẽ nằm trong file của agent tương ứng, còn cấu hình trung tâm theo Recipe 5 thì ghim roster và thiết lập chung. Tất cả cùng hoạt động đồng thời.
|
||||
Cả sáu recipe này có thể kết hợp song song. Một cấu hình doanh nghiệp thực tế cho `bmad-product-brief` hoàn toàn có thể đặt `persistent_facts` theo Recipe 2, `on_complete` theo Recipe 3 và `brief_template` theo Recipe 4 trong cùng một file. Quy tắc ở cấp agent theo Recipe 1 sẽ nằm trong file của agent tương ứng, cấu hình trung tâm theo Recipe 5 thì ghim roster và thiết lập chung, còn các mẫu tích hợp nâng cao theo Recipe 6 cấu hình external sources và handoff. Tất cả cùng hoạt động đồng thời.
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-product-brief.toml (cấp workflow)
|
||||
|
|
|
|||
|
|
@ -1,116 +1,266 @@
|
|||
---
|
||||
title: "Cách cài đặt BMad"
|
||||
description: Hướng dẫn từng bước để cài đặt BMad vào dự án của bạn
|
||||
title: 'Cách cài đặt BMad'
|
||||
description: Cài đặt, cập nhật và ghim phiên bản BMad cho phát triển local, team và CI
|
||||
sidebar:
|
||||
order: 1
|
||||
---
|
||||
|
||||
Sử dụng lệnh `npx bmad-method install` để thiết lập BMad trong dự án của bạn với các module và công cụ AI theo lựa chọn.
|
||||
|
||||
Nếu bạn muốn dùng trình cài đặt không tương tác và cung cấp toàn bộ tùy chọn ngay trên dòng lệnh, xem [hướng dẫn này](./non-interactive-installation.md).
|
||||
Dùng `npx bmad-method install` để thiết lập BMad trong dự án của bạn. Một lệnh xử lý cả cài đặt lần đầu, nâng cấp, đổi channel và chạy bằng script cho CI. Trang này bao quát toàn bộ các trường hợp đó.
|
||||
|
||||
## Khi nào nên dùng
|
||||
|
||||
- Bắt đầu một dự án mới với BMad
|
||||
- Thêm BMad vào một codebase hiện có
|
||||
- Cập nhật bản cài đặt BMad hiện tại
|
||||
- Thêm hoặc gỡ module trên một bản cài hiện có
|
||||
- Chuyển một module sang main-HEAD hoặc ghim vào một bản phát hành cụ thể
|
||||
- Script hóa cài đặt cho pipeline CI, Dockerfile hoặc triển khai doanh nghiệp
|
||||
|
||||
:::note[Điều kiện tiên quyết]
|
||||
- **Node.js** 20.12+ (bắt buộc cho trình cài đặt)
|
||||
- **Git** (khuyến nghị)
|
||||
- **Công cụ AI** (Claude Code, Cursor, hoặc tương tự)
|
||||
|
||||
- **Node.js** 20.12+ (trình cài đặt yêu cầu phiên bản này)
|
||||
- **Git** (để clone các module bên ngoài)
|
||||
- **Một công cụ AI** như Claude Code hoặc Cursor (chạy `npx bmad-method install --list-tools` để xem mọi công cụ được hỗ trợ)
|
||||
|
||||
:::
|
||||
|
||||
## Các bước thực hiện
|
||||
|
||||
### 1. Chạy trình cài đặt
|
||||
## Cài lần đầu (đường nhanh)
|
||||
|
||||
```bash
|
||||
npx bmad-method install
|
||||
```
|
||||
|
||||
:::tip[Muốn dùng bản prerelease mới nhất?]
|
||||
Sử dụng dist-tag `next`:
|
||||
Luồng tương tác sẽ hỏi bạn năm thứ:
|
||||
|
||||
1. Thư mục cài đặt (mặc định là thư mục làm việc hiện tại)
|
||||
2. Module cần cài (checkbox cho core, bmm, bmb, cis, gds, tea)
|
||||
3. **"Ready to install (all stable)?"** — chọn Yes để nhận tag phát hành mới nhất cho mọi module bên ngoài
|
||||
4. Công cụ AI/IDE cần tích hợp (claude-code, cursor và các công cụ khác)
|
||||
5. Cấu hình theo từng module (tên, ngôn ngữ, thư mục output)
|
||||
|
||||
Chấp nhận mặc định là bạn sẽ có bản stable mới nhất của mọi module, đã cấu hình cho công cụ bạn chọn.
|
||||
|
||||
:::tip[Chỉ muốn bản prerelease mới nhất?]
|
||||
|
||||
```bash
|
||||
npx bmad-method@next install
|
||||
```
|
||||
|
||||
Cách này giúp bạn nhận các thay đổi mới sớm hơn, đổi lại khả năng biến động cao hơn bản cài đặt mặc định.
|
||||
Lệnh này chạy trình cài prerelease, đi kèm snapshot mới hơn của core và bmm. Đổi lại là biến động nhiều hơn, nhưng ít độ trễ hơn giữa phát triển và phát hành.
|
||||
:::
|
||||
|
||||
:::tip[Bản rất mới]
|
||||
Để cài đặt trực tiếp từ nhánh `main` mới nhất (có thể không ổn định):
|
||||
## Chọn một phiên bản cụ thể
|
||||
|
||||
Có hai trục độc lập quyết định thứ gì được ghi xuống đĩa.
|
||||
|
||||
### Trục 1: channel của module bên ngoài
|
||||
|
||||
Mọi module bên ngoài như bmb, cis, gds, tea và các module cộng đồng đều được cài trên một trong ba channel:
|
||||
|
||||
| Channel | Nội dung được cài | Ai nên chọn |
|
||||
| ------------------ | ---------------------------------------------------------------------------- | --------------------------------------- |
|
||||
| `stable` (mặc định) | Tag semver đã phát hành cao nhất. Các prerelease như `v2.0.0-alpha.1` bị loại trừ. | Phần lớn người dùng |
|
||||
| `next` | HEAD của nhánh main tại thời điểm cài | Contributor, người dùng sớm |
|
||||
| `pinned` | Một tag cụ thể do bạn chỉ định | Cài đặt doanh nghiệp, CI cần tái lập |
|
||||
|
||||
Channel được chọn theo từng module. Bạn có thể để bmb chạy `next` trong khi cis vẫn ở `stable`; các cờ bên dưới cho phép trộn tự do.
|
||||
|
||||
### Trục 2: phiên bản binary của trình cài đặt
|
||||
|
||||
Gói npm `bmad-method` có hai dist-tag:
|
||||
|
||||
| Lệnh | Bạn nhận được gì |
|
||||
| ------------------------------------- | ----------------------------------------------------------------- |
|
||||
| `npx bmad-method install` (`@latest`) | Bản stable mới nhất của trình cài |
|
||||
| `npx bmad-method@next install` | Bản prerelease mới nhất của trình cài, tự động publish ở mỗi lần push lên main |
|
||||
|
||||
**Binary của trình cài quyết định phiên bản core và bmm.** Hai module này được đóng gói sẵn bên trong package trình cài thay vì clone từ repo riêng.
|
||||
|
||||
### Vì sao core và bmm chưa có channel riêng
|
||||
|
||||
Chúng gắn liền với binary trình cài bạn chạy:
|
||||
|
||||
- `npx bmad-method install` → core và bmm stable mới nhất
|
||||
- `npx bmad-method@next install` → core và bmm prerelease
|
||||
- `node /path/to/local-checkout/tools/installer/bmad-cli.js install` → đúng nội dung trong checkout local của bạn
|
||||
|
||||
`--pin bmm=v6.3.0` và `--next=bmm` không có hiệu lực với module bundled, và trình cài sẽ cảnh báo khi bạn thử. Một bản phát hành trong tương lai sẽ tách bmm khỏi package trình cài; khi đó bmm sẽ có bộ chọn channel đúng nghĩa giống bmb hiện nay.
|
||||
|
||||
## Cập nhật bản cài hiện có
|
||||
|
||||
Chạy `npx bmad-method install` trong thư mục đã có `_bmad/` sẽ hiển thị một menu:
|
||||
|
||||
| Lựa chọn | Tác dụng |
|
||||
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Quick Update** | Chạy lại cài đặt với cấu hình hiện có. Làm mới file, áp dụng patch và nâng cấp minor stable, từ chối nâng cấp major. Nhanh và không tương tác. |
|
||||
| **Modify Install** | Luồng tương tác đầy đủ. Thêm hoặc gỡ module, cấu hình lại thiết lập, tùy chọn xem và đổi channel cho module hiện có. |
|
||||
|
||||
### Prompt nâng cấp
|
||||
|
||||
Khi Modify phát hiện tag stable mới hơn cho một module đang ở `stable`, nó phân loại diff và hỏi theo bảng sau:
|
||||
|
||||
| Kiểu nâng cấp | Ví dụ | Mặc định |
|
||||
| ------------ | --------------- | ------- |
|
||||
| Patch | v1.7.0 → v1.7.1 | Y |
|
||||
| Minor | v1.7.0 → v1.8.0 | Y |
|
||||
| Major | v1.7.0 → v2.0.0 | **N** |
|
||||
|
||||
Major mặc định là N vì breaking change thường bị cảm nhận như "bất ổn" khi người dùng không chờ đợi nó. Prompt có kèm URL release notes trên GitHub để bạn đọc trước khi chấp nhận.
|
||||
|
||||
Khi dùng `--yes`, nâng cấp patch và minor được áp dụng tự động. Major vẫn bị giữ nguyên; truyền `--pin <code>=<new-tag>` để chấp nhận không tương tác.
|
||||
|
||||
### Đổi channel của một module
|
||||
|
||||
**Tương tác:** chọn Modify → trả lời **Yes** cho "Review channel assignments?" → mỗi module bên ngoài sẽ có lựa chọn Keep, Switch to stable, Switch to next hoặc Pin to a tag.
|
||||
|
||||
**Qua cờ:** các recipe ở phần tiếp theo bao phủ những trường hợp thường gặp.
|
||||
|
||||
## Headless CI installs
|
||||
|
||||
### Bảng cờ
|
||||
|
||||
| Cờ | Mục đích |
|
||||
| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `--yes`, `-y` | Bỏ qua mọi prompt; nhận giá trị từ cờ và mặc định |
|
||||
| `--directory <path>` | Cài vào thư mục này (mặc định là thư mục làm việc hiện tại) |
|
||||
| `--modules <a,b,c>` | Tập module chính xác. Core được tự thêm. Đây không phải delta; hãy liệt kê mọi module bạn muốn giữ. |
|
||||
| `--tools <a,b>` | Chọn IDE/công cụ. Bắt buộc với bản cài mới dùng `--yes`. Chạy `--list-tools` để xem ID hợp lệ. |
|
||||
| `--list-tools` | In mọi ID công cụ/IDE được hỗ trợ (kèm thư mục đích) rồi thoát. |
|
||||
| `--action <type>` | `install`, `update` hoặc `quick-update`. Mặc định dựa trên trạng thái cài đặt hiện có. |
|
||||
| `--custom-source <urls>` | Cài module tùy chỉnh từ Git URL hoặc đường dẫn local |
|
||||
| `--channel <stable\|next>` | Áp dụng cho mọi module bên ngoài (alias là `--all-stable` / `--all-next`) |
|
||||
| `--all-stable` | Alias cho `--channel=stable` |
|
||||
| `--all-next` | Alias cho `--channel=next` |
|
||||
| `--next=<code>` | Đặt một module lên next. Có thể lặp lại. |
|
||||
| `--pin <code>=<tag>` | Ghim một module vào tag cụ thể. Có thể lặp lại. |
|
||||
| `--set <module>.<key>=<value>` | Đặt bất kỳ tùy chọn cấu hình module nào không tương tác (khuyến nghị; xem [Ghi đè cấu hình module](#ghi-đè-cấu-hình-module)). Có thể lặp lại. |
|
||||
| `--list-options [module]` | In mọi key `--set` cho module tích hợp và module chính thức đã cache local, rồi thoát. Truyền mã module để chỉ xem module đó. |
|
||||
| `--user-name`, `--communication-language`, `--document-output-language`, `--output-folder` | Shortcut cũ tương đương `--set core.<key>=<value>` (vẫn được hỗ trợ) |
|
||||
|
||||
Độ ưu tiên khi các cờ chồng nhau: `--pin` thắng `--next=`, thắng `--channel` / `--all-*`, thắng mặc định registry (`stable`).
|
||||
|
||||
:::note[Ví dụ resolve]
|
||||
`--all-next --pin cis=v0.2.0` đặt bmb, gds và tea lên next, đồng thời ghim cis vào v0.2.0.
|
||||
:::
|
||||
|
||||
### Recipe
|
||||
|
||||
**Cài mặc định — stable mới nhất cho mọi thứ:**
|
||||
|
||||
```bash
|
||||
npx github:bmad-code-org/BMAD-METHOD install
|
||||
```
|
||||
:::
|
||||
|
||||
### 2. Chọn vị trí cài đặt
|
||||
|
||||
Trình cài đặt sẽ hỏi bạn muốn đặt các tệp BMad ở đâu:
|
||||
|
||||
- Thư mục hiện tại (khuyến nghị cho dự án mới nếu bạn tự tạo thư mục và chạy lệnh từ bên trong nó)
|
||||
- Đường dẫn tùy chọn
|
||||
|
||||
### 3. Chọn công cụ AI
|
||||
|
||||
Chọn các công cụ AI bạn đang dùng:
|
||||
|
||||
- Claude Code
|
||||
- Cursor
|
||||
- Các công cụ khác
|
||||
|
||||
Mỗi công cụ có cách tích hợp skill riêng. Trình cài đặt sẽ tạo các tệp prompt nhỏ để kích hoạt workflow và agent, và đặt chúng vào đúng vị trí mà công cụ của bạn mong đợi.
|
||||
|
||||
:::note[Kích hoạt skill]
|
||||
Một số nền tảng yêu cầu bật skill trong cài đặt trước khi chúng xuất hiện. Nếu bạn đã cài BMad mà chưa thấy skill, hãy kiểm tra cài đặt của nền tảng hoặc hỏi trợ lý AI cách bật skill.
|
||||
:::
|
||||
|
||||
### 4. Chọn module
|
||||
|
||||
Trình cài đặt sẽ hiện các module có sẵn. Chọn những module bạn cần - phần lớn người dùng chỉ cần **BMad Method** (module phát triển phần mềm).
|
||||
|
||||
### 5. Làm theo các prompt
|
||||
|
||||
Trình cài đặt sẽ hướng dẫn các bước còn lại - cài đặt, tích hợp công cụ, và các tùy chọn khác.
|
||||
|
||||
## Bạn nhận được gì
|
||||
|
||||
```text
|
||||
du-an-cua-ban/
|
||||
├── _bmad/
|
||||
│ ├── bmm/ # Các module bạn đã chọn
|
||||
│ │ └── config.yaml # Cài đặt module (nếu bạn cần thay đổi sau này)
|
||||
│ ├── core/ # Module core bắt buộc
|
||||
│ └── ...
|
||||
├── _bmad-output/ # Các artifact được tạo ra
|
||||
├── .claude/ # Claude Code skills (nếu dùng Claude Code)
|
||||
│ └── skills/
|
||||
│ ├── bmad-help/
|
||||
│ ├── bmad-persona/
|
||||
│ └── ...
|
||||
└── .cursor/ # Cursor skills (nếu dùng Cursor)
|
||||
└── skills/
|
||||
└── ...
|
||||
npx bmad-method install --yes --modules bmm,bmb,cis --tools claude-code
|
||||
```
|
||||
|
||||
## Xác minh cài đặt
|
||||
**Ghim cho doanh nghiệp — tái lập từng byte:**
|
||||
|
||||
Chạy `bmad-help` để xác minh mọi thứ hoạt động và xem bạn nên làm gì tiếp theo.
|
||||
```bash
|
||||
npx bmad-method install --yes \
|
||||
--modules bmm,bmb,cis \
|
||||
--pin bmb=v1.7.0 --pin cis=v0.2.0 \
|
||||
--tools claude-code
|
||||
```
|
||||
|
||||
**BMad-Help là công cụ hướng dẫn thông minh** sẽ:
|
||||
- Xác nhận bản cài đặt hoạt động đúng
|
||||
- Hiển thị những gì có sẵn dựa trên module đã cài
|
||||
- Đề xuất bước đầu tiên của bạn
|
||||
**Bleeding edge — module bên ngoài ở main HEAD:**
|
||||
|
||||
Bạn cũng có thể hỏi nó:
|
||||
```text
|
||||
bmad-help Tôi vừa cài xong, giờ nên làm gì đầu tiên?
|
||||
bmad-help Tôi có những lựa chọn nào cho một dự án SaaS?
|
||||
```bash
|
||||
npx bmad-method install --yes --modules bmm,bmb --all-next --tools claude-code
|
||||
```
|
||||
|
||||
**Thêm module vào bản cài hiện có** (giữ mọi thứ khác):
|
||||
|
||||
```bash
|
||||
npx bmad-method install --yes --action update \
|
||||
--modules bmm,bmb,gds
|
||||
```
|
||||
|
||||
`--tools` được bỏ có chủ ý vì `--action update` dùng lại các công cụ đã cấu hình ở lần cài đầu.
|
||||
|
||||
**Trộn channel — bmb ở next, gds ở stable:**
|
||||
|
||||
```bash
|
||||
npx bmad-method install --yes --action update \
|
||||
--modules bmm,bmb,cis,gds \
|
||||
--next=bmb
|
||||
```
|
||||
|
||||
### Ghi đè cấu hình module
|
||||
|
||||
`--set <module>.<key>=<value>` cho phép đặt bất kỳ tùy chọn cấu hình module nào không tương tác. Cờ này có thể lặp lại và mở rộng được cho mọi module hiện tại lẫn tương lai. Nó được áp dụng như một patch sau cài đặt: trình cài chạy luồng bình thường trước, sau đó `--set` upsert từng giá trị vào `_bmad/config.toml` (scope team) hoặc `_bmad/config.user.toml` (scope user), và vào `_bmad/<module>/config.yaml` để các giá trị đã khai báo được giữ cho lần cài sau.
|
||||
|
||||
**Ví dụ — cài bmm với project knowledge và skill level rõ ràng:**
|
||||
|
||||
```bash
|
||||
npx bmad-method install --yes \
|
||||
--modules bmm \
|
||||
--tools claude-code \
|
||||
--set bmm.project_knowledge=research \
|
||||
--set bmm.user_skill_level=expert
|
||||
```
|
||||
|
||||
**Khám phá các key có sẵn cho một module:**
|
||||
|
||||
```bash
|
||||
npx bmad-method install --list-options bmm
|
||||
```
|
||||
|
||||
`--list-options` không có tham số sẽ liệt kê mọi key mà trình cài tìm thấy local: module tích hợp (`core`, `bmm`) cộng với các module chính thức đang được cache. Cache là theo từng máy và có thể bị xóa, nên các module chính thức từng cài sẽ không xuất hiện trên checkout mới hoặc CI worker tạm thời cho đến khi chúng được cài lại. Module cộng đồng và tùy chỉnh không được liệt kê ở đây; hãy đọc trực tiếp `module.yaml` của module để xem các key nó khai báo.
|
||||
|
||||
**Cách hoạt động:**
|
||||
|
||||
- **Routing.** Bước patch tìm `[modules.<module>] <key>` (hoặc `[core] <key>`) trong `config.user.toml` trước; nếu đã có ở đó, nó cập nhật file đó. Nếu không, nó ghi vào `config.toml` scope team. Vì vậy các key scope user như `core.user_name`, `bmm.user_skill_level` đi vào `config.user.toml`, còn key scope team đi vào `config.toml`, khớp với cách trình cài phân vùng cấu hình.
|
||||
- **Giá trị nguyên văn.** Giá trị được ghi đúng như bạn truyền vào, không render template `result:`. Nếu muốn dạng đã render như `{project-root}/research`, hãy truyền chính xác giá trị đó: `--set bmm.project_knowledge='{project-root}/research'`.
|
||||
- **Giữ lại, key đã khai báo.** Giá trị cho key được khai báo trong `module.yaml` sống sót qua các lần cài sau vì cũng được ghi vào `_bmad/<module>/config.yaml`, nơi trình cài đọc làm mặc định cho prompt tiếp theo.
|
||||
- **Giữ lại, key chưa khai báo.** Giá trị cho key mà schema module không khai báo sẽ nằm trong `config.toml` cho lần cài hiện tại nhưng không được phát lại ở lần cài sau (manifest writer phân vùng nghiêm theo schema và bỏ key lạ). Hãy truyền lại `--set` nếu bạn cần nó bền, hoặc sửa trực tiếp `_bmad/config.toml`.
|
||||
- **Không validate.** Giá trị `single-select` không được kiểm tra với danh sách cho phép, và key lạ không bị từ chối; bạn khẳng định gì thì giá trị đó được ghi.
|
||||
- **Module không nằm trong `--modules`.** Đặt giá trị cho module bạn không cài sẽ in cảnh báo và bỏ giá trị đó, không tạo file cho module chưa cài.
|
||||
|
||||
Các shortcut core cũ như `--user-name`, `--output-folder` vẫn hoạt động và vẫn được ghi lại để tương thích ngược, nhưng `--set core.user_name=...` là tương đương.
|
||||
|
||||
:::note[Hoạt động với quick-update]
|
||||
`--set` là patch sau cài đặt, nên nó áp dụng giống nhau bất kể action type. Khi chạy `bmad install --action quick-update` (hoặc `--yes` trên bản cài hiện có, nơi quick-update là mặc định), `--set` patch các file cấu hình trung tâm ở cuối giống một lần cài thường.
|
||||
:::
|
||||
|
||||
:::caution[Rate limit trên IP dùng chung]
|
||||
Các API call GitHub ẩn danh bị giới hạn 60/giờ cho mỗi IP. Một lần cài gọi API một lần cho mỗi module bên ngoài để resolve tag stable. Văn phòng sau NAT, pool CI runner và VPN có thể cùng nhau dùng hết hạn mức này.
|
||||
|
||||
Đặt `GITHUB_TOKEN=<personal access token>` trong môi trường để nâng hạn mức lên 5000/giờ cho mỗi tài khoản. PAT đọc public repo là đủ, không cần scope.
|
||||
:::
|
||||
|
||||
## Những gì đã được cài
|
||||
|
||||
Sau mọi lần cài, `_bmad/_config/manifest.yaml` ghi lại chính xác nội dung trên đĩa:
|
||||
|
||||
```yaml
|
||||
modules:
|
||||
- name: bmb
|
||||
version: v1.7.0 # tag, hoặc "main" nếu là next
|
||||
channel: stable # stable | next | pinned
|
||||
sha: 86033fc9aeae2ca6d52c7cdb675c1f4bf17fc1c1
|
||||
source: external
|
||||
repoUrl: https://github.com/bmad-code-org/bmad-builder
|
||||
```
|
||||
|
||||
Trường `sha` được ghi cho các module dựa trên git (external, community và custom bằng URL). Module bundled (core, bmm) và module custom từ đường dẫn local không có trường này; code của chúng đi cùng binary trình cài hoặc filesystem của bạn, không phải một ref có thể clone.
|
||||
|
||||
Để tái lập giữa nhiều máy, đừng dựa vào việc chạy lại cùng lệnh `--modules`. Cài trên stable channel resolve sang tag đã phát hành cao nhất **tại thời điểm cài**, nên lần chạy sau có thể nhận bản mới hơn. Hãy chuyển các tag đã ghi trong `manifest.yaml` thành cờ `--pin` rõ ràng trên máy đích, ví dụ:
|
||||
|
||||
```bash
|
||||
npx bmad-method install --yes --modules bmb,cis \
|
||||
--pin bmb=v1.7.0 --pin cis=v0.4.2 --tools claude-code
|
||||
```
|
||||
|
||||
## Khắc phục sự cố
|
||||
|
||||
**Trình cài đặt báo lỗi** - Sao chép toàn bộ output vào trợ lý AI của bạn và để nó phân tích.
|
||||
### "Could not resolve stable tag" hoặc "API rate limit exceeded"
|
||||
|
||||
**Cài đặt xong nhưng sau đó có thứ không hoạt động** - AI của bạn cần bối cảnh BMad để hỗ trợ. Xem [Cách tìm câu trả lời về BMad](./get-answers-about-bmad.md) để biết cách cho AI truy cập đúng nguồn thông tin.
|
||||
Bạn đã chạm giới hạn 60/giờ của GitHub khi gọi ẩn danh. Đặt `GITHUB_TOKEN` rồi thử lại. Nếu đã có token, token đó có thể đã hết hạn hoặc hết budget rate limit; hãy thử token khác hoặc chờ reset theo giờ.
|
||||
|
||||
### "Tag 'vX.Y.Z' not found"
|
||||
|
||||
Tag bạn truyền cho `--pin` không tồn tại trong repo module. Kiểm tra trang releases của repo trên GitHub để xem tag hợp lệ.
|
||||
|
||||
### Bản cài đã ghim vẫn cứ nâng cấp
|
||||
|
||||
Bản cài pinned không nâng cấp. Quick-update chỉ áp dụng patch và minor trên stable channel; nó không đụng tới `pinned` hoặc `next`. Nếu bản cài pinned thay đổi, mở `_bmad/_config/manifest.yaml`: `channel: pinned` cùng `version` và `sha` cố định phải giữ nguyên qua các lần chạy, trừ khi bạn override rõ bằng cờ.
|
||||
|
||||
### `--pin bmm=X` không làm gì
|
||||
|
||||
bmm là module bundled, nên `--pin` và `--next=` không áp dụng. Dùng `npx bmad-method@next install` để lấy prerelease core/bmm, hoặc checkout repo bmad-bmm và chạy trình cài local để lấy thay đổi chưa phát hành.
|
||||
|
|
|
|||
|
|
@ -1,194 +1,10 @@
|
|||
---
|
||||
title: Cài đặt không tương tác
|
||||
description: Cài đặt BMad bằng các cờ dòng lệnh cho pipeline CI/CD và triển khai tự động
|
||||
description: Tài liệu cài đặt headless / CI đã được chuyển sang trang mới
|
||||
sidebar:
|
||||
order: 2
|
||||
---
|
||||
|
||||
Sử dụng các cờ dòng lệnh để cài đặt BMad mà không cần tương tác. Cách này hữu ích cho:
|
||||
|
||||
## Khi nào nên dùng
|
||||
|
||||
- Triển khai tự động và pipeline CI/CD
|
||||
- Cài đặt bằng script
|
||||
- Cài đặt hàng loạt trên nhiều dự án
|
||||
- Cài đặt nhanh với cấu hình đã biết trước
|
||||
|
||||
:::note[Điều kiện tiên quyết]
|
||||
Yêu cầu [Node.js](https://nodejs.org) v20.12+ và `npx` (đi kèm với npm).
|
||||
:::
|
||||
|
||||
## Các cờ khả dụng
|
||||
|
||||
### Tùy chọn cài đặt
|
||||
|
||||
| Cờ | Mô tả | Ví dụ |
|
||||
|------|-------------|---------|
|
||||
| `--directory <path>` | Thư mục cài đặt | `--directory ~/projects/myapp` |
|
||||
| `--modules <modules>` | Danh sách ID module, cách nhau bởi dấu phẩy | `--modules bmm,bmb` |
|
||||
| `--tools <tools>` | Danh sách ID công cụ/IDE, cách nhau bởi dấu phẩy (dùng `none` để bỏ qua) | `--tools claude-code,cursor` hoặc `--tools none` |
|
||||
| `--action <type>` | Hành động cho bản cài đặt hiện có: `install` (mặc định), `update`, hoặc `quick-update` | `--action quick-update` |
|
||||
| `--custom-source <sources>` | Danh sách Git URL hoặc đường dẫn cục bộ cho module tùy chỉnh, cách nhau bởi dấu phẩy | `--custom-source /path/to/module` |
|
||||
|
||||
### Cấu hình cốt lõi
|
||||
|
||||
| Cờ | Mô tả | Mặc định |
|
||||
|------|-------------|---------|
|
||||
| `--user-name <name>` | Tên để agent sử dụng | Tên người dùng hệ thống |
|
||||
| `--communication-language <lang>` | Ngôn ngữ giao tiếp của agent | Tiếng Anh |
|
||||
| `--document-output-language <lang>` | Ngôn ngữ đầu ra tài liệu | Tiếng Anh |
|
||||
| `--output-folder <path>` | Đường dẫn thư mục output (xem quy tắc resolve bên dưới) | `_bmad-output` |
|
||||
|
||||
#### Quy tắc resolve đường dẫn output folder
|
||||
|
||||
Giá trị truyền vào `--output-folder` (hoặc nhập ở chế độ tương tác) sẽ được resolve theo các quy tắc sau:
|
||||
|
||||
| Loại đầu vào | Ví dụ | Được resolve thành |
|
||||
|------|-------------|---------|
|
||||
| Đường dẫn tương đối (mặc định) | `_bmad-output` | `<project-root>/_bmad-output` |
|
||||
| Đường dẫn tương đối có traversal | `../../shared-outputs` | Đường dẫn tuyệt đối đã được chuẩn hóa, ví dụ `/Users/me/shared-outputs` |
|
||||
| Đường dẫn tuyệt đối | `/Users/me/shared-outputs` | Giữ nguyên như đã nhập, **không** thêm project root vào trước |
|
||||
|
||||
Đường dẫn sau khi resolve là đường dẫn mà agent và workflow sẽ dùng lúc runtime để ghi file đầu ra. Việc dùng đường dẫn tuyệt đối hoặc đường dẫn tương đối có traversal cho phép bạn chuyển toàn bộ artifact sinh ra sang một thư mục nằm ngoài cây dự án, hữu ích với thư mục dùng chung hoặc cấu trúc monorepo.
|
||||
|
||||
### Tùy chọn khác
|
||||
|
||||
| Cờ | Mô tả |
|
||||
|------|-------------|
|
||||
| `-y, --yes` | Chấp nhận toàn bộ mặc định và bỏ qua prompt |
|
||||
| `-d, --debug` | Bật output debug cho quá trình tạo manifest |
|
||||
|
||||
## ID module
|
||||
|
||||
Những ID module có thể dùng với cờ `--modules`:
|
||||
|
||||
- `bmm` - BMad Method Master
|
||||
- `bmb` - BMad Builder
|
||||
|
||||
Kiểm tra [BMad registry](https://github.com/bmad-code-org) để xem các module ngoài được hỗ trợ.
|
||||
|
||||
## ID công cụ/IDE
|
||||
|
||||
Những ID công cụ có thể dùng với cờ `--tools`:
|
||||
|
||||
**Khuyến dùng:** `claude-code`, `cursor`
|
||||
|
||||
Chạy `npx bmad-method install` một lần ở chế độ tương tác để xem danh sách đầy đủ hiện tại của các công cụ được hỗ trợ, hoặc xem [cấu hình platform codes](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/tools/installer/ide/platform-codes.yaml).
|
||||
|
||||
## Các chế độ cài đặt
|
||||
|
||||
| Chế độ | Mô tả | Ví dụ |
|
||||
|------|-------------|---------|
|
||||
| Hoàn toàn không tương tác | Cung cấp đầy đủ cờ để bỏ qua tất cả prompt | `npx bmad-method install --directory . --modules bmm --tools claude-code --yes` |
|
||||
| Bán tương tác | Cung cấp một số cờ, BMad hỏi thêm phần còn lại | `npx bmad-method install --directory . --modules bmm` |
|
||||
| Chỉ dùng mặc định | Chấp nhận tất cả giá trị mặc định với `-y` | `npx bmad-method install --yes` |
|
||||
| Chỉ dùng custom source | Chỉ cài core và module tùy chỉnh | `npx bmad-method install --directory . --custom-source /path/to/module --tools claude-code --yes` |
|
||||
| Không cấu hình công cụ | Bỏ qua cấu hình công cụ/IDE | `npx bmad-method install --modules bmm --tools none` |
|
||||
|
||||
## Ví dụ
|
||||
|
||||
### Cài đặt cho pipeline CI/CD
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# install-bmad.sh
|
||||
|
||||
npx bmad-method install \
|
||||
--directory "${GITHUB_WORKSPACE}" \
|
||||
--modules bmm \
|
||||
--tools claude-code \
|
||||
--user-name "CI Bot" \
|
||||
--communication-language English \
|
||||
--document-output-language English \
|
||||
--output-folder _bmad-output \
|
||||
--yes
|
||||
```
|
||||
|
||||
### Cập nhật bản cài đặt hiện có
|
||||
|
||||
```bash
|
||||
npx bmad-method install \
|
||||
--directory ~/projects/myapp \
|
||||
--action update \
|
||||
--modules bmm,bmb,custom-module
|
||||
```
|
||||
|
||||
### Quick Update (giữ nguyên cài đặt)
|
||||
|
||||
```bash
|
||||
npx bmad-method install \
|
||||
--directory ~/projects/myapp \
|
||||
--action quick-update
|
||||
```
|
||||
|
||||
### Cài từ custom source
|
||||
|
||||
Cài một module từ đường dẫn cục bộ hoặc từ bất kỳ Git host nào:
|
||||
|
||||
```bash
|
||||
npx bmad-method install \
|
||||
--directory . \
|
||||
--custom-source /path/to/my-module \
|
||||
--tools claude-code \
|
||||
--yes
|
||||
```
|
||||
|
||||
Kết hợp cùng module chính thức:
|
||||
|
||||
```bash
|
||||
npx bmad-method install \
|
||||
--directory . \
|
||||
--modules bmm \
|
||||
--custom-source https://gitlab.com/myorg/my-module \
|
||||
--tools claude-code \
|
||||
--yes
|
||||
```
|
||||
|
||||
:::note[Hành vi của `custom-source`]
|
||||
Khi dùng `--custom-source` mà không kèm `--modules`, hệ thống chỉ cài core và các module tùy chỉnh. Nếu muốn cài cả module chính thức, hãy thêm `--modules`. Xem thêm [Cài đặt module tùy chỉnh và module cộng đồng](./install-custom-modules.md) để biết chi tiết.
|
||||
:::
|
||||
|
||||
## Bạn nhận được gì
|
||||
|
||||
- Thư mục `_bmad/` đã được cấu hình đầy đủ trong dự án của bạn
|
||||
- Agent và workflow đã được cấu hình theo module và công cụ bạn chọn
|
||||
- Thư mục `_bmad-output/` để lưu các artifact được tạo
|
||||
|
||||
## Kiểm tra và xử lý lỗi
|
||||
|
||||
BMad sẽ kiểm tra tất cả các cờ được cung cấp:
|
||||
|
||||
- **Directory** - Phải là đường dẫn hợp lệ và có quyền ghi
|
||||
- **Modules** - Cảnh báo nếu ID module không hợp lệ (nhưng không thất bại)
|
||||
- **Tools** - Cảnh báo nếu ID công cụ không hợp lệ (nhưng không thất bại)
|
||||
- **Action** - Phải là một trong: `install`, `update`, `quick-update`
|
||||
|
||||
Giá trị không hợp lệ sẽ dẫn đến một trong các trường hợp sau:
|
||||
1. Hiện lỗi và thoát (với các tùy chọn quan trọng như directory)
|
||||
2. Hiện cảnh báo và bỏ qua (với mục tùy chọn)
|
||||
3. Quay lại hỏi interactive (với giá trị bắt buộc bị thiếu)
|
||||
|
||||
:::tip[Thực hành tốt]
|
||||
- Dùng đường dẫn tuyệt đối cho `--directory` để tránh nhầm lẫn
|
||||
- Dùng đường dẫn tuyệt đối cho `--output-folder` khi bạn muốn ghi artifact ra ngoài cây dự án, ví dụ vào một thư mục output dùng chung trong monorepo
|
||||
- Thử nghiệm cờ ở máy local trước khi đưa vào pipeline CI/CD
|
||||
- Kết hợp với `-y` nếu bạn muốn cài đặt hoàn toàn không cần can thiệp
|
||||
- Dùng `--debug` nếu gặp vấn đề trong quá trình cài đặt
|
||||
:::
|
||||
|
||||
## Khắc phục sự cố
|
||||
|
||||
### Cài đặt thất bại với lỗi "Invalid directory"
|
||||
|
||||
- Thư mục đích phải tồn tại (hoặc thư mục cha của nó phải tồn tại)
|
||||
- Bạn cần quyền ghi
|
||||
- Đường dẫn phải là tuyệt đối, hoặc tương đối đúng với thư mục hiện tại
|
||||
|
||||
### Không tìm thấy module
|
||||
|
||||
- Xác minh ID module có đúng không
|
||||
- Module bên ngoài phải có sẵn trong registry
|
||||
|
||||
:::note[Vẫn bị mắc?]
|
||||
Chạy với `--debug` để xem output chi tiết, thử chế độ interactive để cô lập vấn đề, hoặc báo cáo tại <https://github.com/bmad-code-org/BMAD-METHOD/issues>.
|
||||
:::note[Trang này đã được chuyển]
|
||||
Các cờ cài đặt headless và CI, cách chọn channel, và pin phiên bản hiện nằm trong hướng dẫn hợp nhất [Cách cài đặt BMad](./install-bmad.md). Hãy chuyển tới mục [Cài đặt headless / CI](./install-bmad.md#headless-ci-installs) để xem bảng cờ và các recipe có thể sao chép dùng ngay.
|
||||
:::
|
||||
|
|
|
|||
Loading…
Reference in New Issue