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:
2026-08-12 16:37:59 +07:00
parent f4dc6a0730
commit 251a18dc39
2 changed files with 170 additions and 0 deletions
+9
View File
@@ -6,6 +6,8 @@ tool call to an Express + SQLite server, a React UI updates over WebSocket, and
Internal build — all rights reserved. Internal build — all rights reserved.
*(Tiếng Việt: [README.vi.md](README.vi.md))*
## What it does ## What it does
- **Sessions, agents, events.** Everything Claude Code emits, recorded and - **Sessions, agents, events.** Everything Claude Code emits, recorded and
@@ -75,6 +77,7 @@ ccam status # is the dashboard up
ccam start # start it in the background and wait for healthy ccam start # start it in the background and wait for healthy
ccam sessions # recent sessions ccam sessions # recent sessions
ccam lanes # lanes with stage and progress ccam lanes # lanes with stage and progress
ccam lanes pipeline # this lane's pipeline template, or switch it
ccam stage <name> # declare the current lane's stage ccam stage <name> # declare the current lane's stage
ccam tail # live event feed ccam tail # live event feed
``` ```
@@ -101,6 +104,12 @@ events and expires after `DETECTION_TTL_MS` (default 5 minutes), so a lane can
move backwards between work sessions. Detection never writes the declared stage, move backwards between work sessions. Detection never writes the declared stage,
and an inferred node never renders as done. and an inferred node never renders as done.
A lane's pipeline template can be switched after creation — `ccam lanes
pipeline <template>` from the terminal, or the pipeline-template picker next to
the lane's title in the Workspace detail panel. Both re-resolve the lane's
current declared stage against the new template's nodes and warn if it no
longer matches one.
A lane can also run **its own application stack**, isolated per lane, when its A lane can also run **its own application stack**, isolated per lane, when its
repository declares a profile at `<repo>/.ccam/profile/` — a `profile.env` of repository declares a profile at `<repo>/.ccam/profile/` — a `profile.env` of
declarations plus shell hooks the dashboard calls. Each lane gets a slot, and its declarations plus shell hooks the dashboard calls. Each lane gets a slot, and its
+161
View File
@@ -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