docs: add README.vi.md Vietnamese translation, document pipeline picker
Adds README.vi.md as the Vietnamese translation of README.md, and documents the pipeline-template picker/CLI switch (ccam lanes pipeline) added in the previous feature.
This commit is contained in:
+161
@@ -0,0 +1,161 @@
|
||||
# Claude Code Monitor
|
||||
|
||||
Bản build nội bộ SmartGift. Dashboard local-first cho Claude Code: hooks POST mỗi
|
||||
tool call lên server Express + SQLite, React UI cập nhật qua WebSocket, và
|
||||
**lane** (làn đường) theo dõi công việc song song của agent qua một pipeline.
|
||||
|
||||
Internal build — all rights reserved.
|
||||
|
||||
*(Bản dịch tiếng Việt của [README.md](README.md), tham khảo — README.md gốc là bản chính thức.)*
|
||||
|
||||
## Làm được gì
|
||||
|
||||
- **Session, agent, event.** Mọi thứ Claude Code emit ra, ghi lại và tìm kiếm
|
||||
được: tool call, token usage, cost, cây subagent, transcript.
|
||||
- **Lane.** Mỗi working directory một lane, sống sót qua session restart. Lane
|
||||
đi qua các pipeline stage và dashboard hiển thị nó đang ở đâu.
|
||||
- **Stage detection.** Stage được suy luận (infer) từ tool stream, nên một
|
||||
session không bao giờ gọi `ccam stage` vẫn hiển thị progress — render dạng
|
||||
viền chấm màu hổ phách (amber) và không bao giờ hiện `done`, vì suy luận
|
||||
không phải bằng chứng.
|
||||
- **Chạy Claude từ trình duyệt.** Spawn session trong thư mục của lane, stream
|
||||
output, gửi follow-up, resume session cũ bất kỳ.
|
||||
- **Analytics, alert, Kanban và workflow view**, cộng thêm MCP server và CLI.
|
||||
|
||||
## Yêu cầu
|
||||
|
||||
Node **>= 20** (`engines` trong `package.json`). Node **24** là bản test suite
|
||||
được verify — node 25 hiện đang làm gãy 6 test server do lệch ABI
|
||||
`better-sqlite3` và 20 test client do thay đổi global `localStorage`.
|
||||
|
||||
## Cài như Claude Code plugin
|
||||
|
||||
Hai lệnh, trên máy chỉ có Claude Code, không cần clone repo, không cần
|
||||
`npm run setup`:
|
||||
|
||||
```
|
||||
/plugin marketplace add Smartgift-AI/Claude-Code-Monitor
|
||||
/plugin install ccam@claude-code-agent-monitor-plugins
|
||||
```
|
||||
|
||||
Lần session-start đầu tiên sẽ cài hooks, boot server, đưa `ccam` vào PATH và
|
||||
kết nối MCP tools; chạy detached nên session không phải chờ. `/ccam-doctor`
|
||||
báo trạng thái, `/ccam-open` build UI và in URL, `/ccam-update` refresh sau
|
||||
khi plugin update. Đường này cần Node **>= 22.5** (không dùng
|
||||
`better-sqlite3` native, server dùng `node:sqlite`). Chi tiết, kể cả những gì
|
||||
cần xóa lúc uninstall: [`docs/PLUGINS.md`](docs/PLUGINS.md).
|
||||
|
||||
## Cài từ checkout
|
||||
|
||||
```bash
|
||||
npm run setup # cài dependency cho root, client và vscode-extension
|
||||
npm run build # build client vào client/dist
|
||||
npm start # serve client đã build + API trên :4820
|
||||
```
|
||||
|
||||
Mở <http://localhost:4820>.
|
||||
|
||||
Development, có hot reload:
|
||||
|
||||
```bash
|
||||
npm run dev # server trên :4820, Vite client trên :5173
|
||||
```
|
||||
|
||||
`DASHBOARD_PORT` override port, `DASHBOARD_CLIENT_DIST` override nơi UI đã
|
||||
build được serve (mặc định `client/dist`; bản cài qua plugin trỏ vào runtime
|
||||
directory riêng của nó). `postinstall` ghi các hook entry Claude Code để nạp
|
||||
dữ liệu cho dashboard — đừng chạy nó khi plugin `ccam` đã cài, không thì mỗi
|
||||
event bị đếm hai lần.
|
||||
|
||||
## CLI
|
||||
|
||||
`ccam` được link sẵn bởi `npm run setup`; không thì gọi `node bin/ccam.js`.
|
||||
|
||||
```bash
|
||||
ccam status # dashboard có đang chạy không
|
||||
ccam start # start ngầm (background) và chờ tới khi healthy
|
||||
ccam sessions # session gần đây
|
||||
ccam lanes # danh sách lane kèm stage và progress
|
||||
ccam lanes pipeline # pipeline template của lane này, hoặc đổi nó
|
||||
ccam stage <name> # khai báo stage hiện tại của lane
|
||||
ccam tail # xem live event feed
|
||||
```
|
||||
|
||||
`ccam --help` liệt kê phần còn lại.
|
||||
|
||||
## Lane
|
||||
|
||||
Lane là một working directory mà dashboard theo dõi. Hai loại:
|
||||
|
||||
- **adopted** (nhận nuôi) — một thư mục bạn đã có sẵn. Dashboard chỉ đọc nó;
|
||||
không bao giờ reset hay xóa.
|
||||
- **managed** (tự quản lý) — git worktree do dashboard tạo dưới `LANES_ROOT`.
|
||||
Dashboard sở hữu toàn bộ vòng đời và có thể reset/xóa nó, phía sau một guard
|
||||
ba lớp kiểm tra khi hủy (destroy guard) và một bước preflight đếm số mà bên
|
||||
gọi phải echo lại.
|
||||
|
||||
```bash
|
||||
ccam lanes add --cwd /path/to/repo --title "My feature" # adopt
|
||||
ccam lanes add --repo /path/to/repo --slug my-feature # managed worktree
|
||||
```
|
||||
|
||||
Stage khai báo (declared) đến từ `ccam stage`. Stage suy luận (inferred) đến
|
||||
từ tool event và hết hạn sau `DETECTION_TTL_MS` (mặc định 5 phút), nên lane có
|
||||
thể lùi lại giữa các work session. Detection không bao giờ ghi đè stage khai
|
||||
báo, và node suy luận không bao giờ render thành `done`.
|
||||
|
||||
Pipeline template của lane có thể đổi sau khi tạo — `ccam lanes
|
||||
pipeline <template>` từ terminal, hoặc dùng picker chọn pipeline-template
|
||||
cạnh tiêu đề lane trong panel chi tiết của trang Workspace. Cả hai đều
|
||||
re-resolve lại stage đã khai báo hiện tại của lane theo node-list của template
|
||||
mới, và cảnh báo nếu nó không còn khớp node nào.
|
||||
|
||||
Lane cũng có thể chạy **application stack riêng của nó**, cô lập theo từng
|
||||
lane, khi repository của nó khai báo một profile tại `<repo>/.ccam/profile/`
|
||||
— một file `profile.env` khai báo cộng shell hooks mà dashboard gọi. Mỗi lane
|
||||
được cấp một slot, port và thư mục riêng theo lane được suy ra từ đó:
|
||||
|
||||
```bash
|
||||
ccam lanes up # boot stack của lane sở hữu thư mục hiện tại
|
||||
ccam lanes runtime # slot, port, tình trạng service
|
||||
ccam lanes logs api # tail log của một service
|
||||
ccam lanes down
|
||||
```
|
||||
|
||||
Service chạy hoàn toàn detached, nên restart dashboard không bao giờ dừng
|
||||
lane đang chạy. Đây là namespacing tài nguyên trên host, không phải
|
||||
container: các lane chạy chung user và share network.
|
||||
|
||||
[`docs/LANES.md`](docs/LANES.md) có mô hình pipeline, destroy guard, hợp đồng
|
||||
(contract) preflight, trang Workspace, `GET /api/lanes/:id/git`, và toàn bộ
|
||||
hợp đồng runtime/profile.
|
||||
|
||||
## Test
|
||||
|
||||
```bash
|
||||
npm run test:server # node:test
|
||||
npm run test:client # Vitest
|
||||
```
|
||||
|
||||
Cả hai phải xanh (pass) trước khi commit; pre-commit hook chạy chúng cộng
|
||||
thêm Prettier.
|
||||
|
||||
## Cấu trúc thư mục
|
||||
|
||||
| Đường dẫn | Là gì |
|
||||
|---|---|
|
||||
| `server/` | Express API, schema SQLite, hook ingest, thư viện lane và worktree |
|
||||
| `client/` | Dashboard React 18 + Vite + Tailwind |
|
||||
| `bin/ccam.js` | CLI |
|
||||
| `mcp/` | MCP server expose các tool đọc dữ liệu dashboard (read-only) |
|
||||
| `docs/` | Architecture, API, lanes, database |
|
||||
| `plugins/` | Các Claude Code plugin đi kèm dashboard |
|
||||
|
||||
## Tài liệu
|
||||
|
||||
- [`ARCHITECTURE.md`](ARCHITECTURE.md) — luồng request, schema, bề mặt WebSocket
|
||||
- [`docs/LANES.md`](docs/LANES.md) — lane, pipeline, stage detection
|
||||
- [`docs/API.md`](docs/API.md) — REST endpoint (`openapi.yaml` được generate tự động)
|
||||
- [`docs/DATABASE.md`](docs/DATABASE.md) — bảng và migration
|
||||
- [`INSTALL.md`](INSTALL.md)
|
||||
- [`CLAUDE.md`](CLAUDE.md) — quy tắc agent làm việc trong repo này phải tuân theo
|
||||
Reference in New Issue
Block a user