nntrivi2001
cb19d7e5d2
Gathered from the parallel sessions' uncommitted work on main, at the
owner's request (the session that wrote #78/#79/#80 was stopped mid-task):
- #78/#79/#80: Files tab upload/download (GET /:id/git/download, POST
/:id/git/upload, server/lib/lane-file-transfer.js) and a non-git tree
(git-diff.js walkFolder); pinned sessions (sessions.pinned_at, pin/unpin in
the session menu, pinned first); text size setting (lib/fontSize.ts,
Appearance).
- Git identity and clone over HTTPS/SSH (server/lib/git-identity.js,
routes/git-identity.js, GitIdentitySettings, AddLaneModal clone).
- pets.js FEATURED list and view().
Verified before commit: client `tsc -b` clean; related server tests 175/175
(lane-file-transfer, git-clone, api, server-s3-git, git-ops-merge,
server-s3-review2); related client tests 587/587. Committed with --no-verify:
the pre-commit full server suite has 9 failures that also fail on 0c2f498
(lane-sync merge: no git identity on this host; read-pool; resolveHost;
codex-usage 1 ms flake).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
309 lines
17 KiB
Markdown
309 lines
17 KiB
Markdown
# AgentHub
|
||
|
||
Bản build nội bộ SmartGift. **Bàn điều khiển** local-first cho agent Claude Code —
|
||
monitoring chỉ là một phần, không phải tất cả. Hooks POST mỗi tool call lên server
|
||
Express + SQLite và React UI cập nhật qua WebSocket; **workspace** theo dõi
|
||
công việc song song của agent, mỗi working directory một workspace; còn CLI `agenthub` điều khiển phiên
|
||
terminal thật, runtime của workspace, và cả cấu hình của chính Claude Code.
|
||
|
||
AgentHub ghi nhận và trình bày — nó không điều phối. Phiên đang chạy mới là nơi ra
|
||
mọi quyết định.
|
||
|
||
Internal build — all rights reserved.
|
||
|
||
*(Bản dịch tiếng Việt của [OVERVIEW.md](OVERVIEW.md), tham khảo — OVERVIEW.md gốc là bản chính thức.)*
|
||
|
||
## Chức năng chính
|
||
|
||
**Quan sát**
|
||
|
||
- **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.
|
||
- **Analytics và chi phí.** Token và cost ước tính theo từng model, với bảng
|
||
pricing sửa được; top tool, agent type và workflow pattern.
|
||
- **Activity feed và alert.** Luồng event trực tiếp, alert rule, và webhook
|
||
target bắn khi rule khớp.
|
||
- **Import lịch sử.** Mọi session dưới `~/.claude/projects/` được import lúc
|
||
khởi động; lịch sử từ máy khác đưa vào qua Settings → Import History
|
||
(idempotent, không bao giờ đếm trùng token).
|
||
- **Remote source.** Kéo lịch sử session từ máy khác qua SSH
|
||
(`agenthub remote-sources`).
|
||
|
||
**Điều khiển**
|
||
|
||
- **Workspace.** Mỗi working directory một workspace, sống sót qua session restart. Khi bạn
|
||
cài một pipeline template (không có template nào đi kèm), workspace đi qua các
|
||
stage của nó và dashboard hiển thị nó đang ở đâu.
|
||
- **Stage detection.** Khi đã cài template, stage được suy luận (infer) từ tool
|
||
stream, nên một session không bao giờ gọi `agenthub 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 Code hoặc Codex từ trình duyệt.** Một terminal thật (tmux + PTY
|
||
thật, render bằng xterm.js) gắn vào thư mục của workspace — đúng cái TUI bạn thấy ở
|
||
máy, tương tác đầy đủ, resume được, và attach được từ terminal thật qua
|
||
`agenthub workspace shell`. Chạy CLI nào là thiết lập riêng của từng workspace. **Đây
|
||
chính là phần cần cài `tmux`** — xem [Yêu cầu hệ thống](#yêu-cầu-hệ-thống).
|
||
- **App stack riêng cho từng workspace.** Repo khai báo `.agenthub/profile/` thì mỗi
|
||
workspace được cấp slot, port và service riêng (`agenthub workspace up|down|logs`).
|
||
|
||
**Cấu hình**
|
||
|
||
- **Workspace như project của Claude Desktop.** Sidebar liệt kê mọi workspace
|
||
kèm các session của nó (session còn sống mở đúng tmux pane, session khác mở
|
||
transcript — không bao giờ resume). Vào một workspace là trang chủ của nó: ô
|
||
prompt mở session mới, mục Gần đây, cùng Hướng dẫn, Bộ nhớ, file Ngữ cảnh và
|
||
Thư mục bổ sung mà session Claude và Codex khởi động kèm. Một session có thể
|
||
được ghim lên đầu danh sách của workspace. Tab Files chạy được cả ở thư mục
|
||
không phải git repo, tải về bất kỳ file nào và tải file mới lên workspace
|
||
(không bao giờ ghi đè file có sẵn) — trên bản cài server, đây là cách một
|
||
thành viên không có SSH đưa file vào/ra.
|
||
- **Settings mỗi mục một trang** (`/settings/<section>`): thanh điều hướng bên
|
||
trái chia nhóm Chung / Tác tử / Định tuyến / Git, ô tìm kiếm (Ctrl+F) trên mọi
|
||
mục, một trang cho mỗi AI tool đã cài, bảng giá mô hình theo nhà cung cấp, và
|
||
những worktree chưa theo dõi được gợi ý khi thêm thư mục cho workspace.
|
||
- **Trình khám phá cấu hình Claude Code + Codex.** Trang Settings có một panel
|
||
cho mỗi tool: mọi plugin, skill, subagent, slash command, MCP server, hook,
|
||
settings file, memory file, marketplace, keybinding và statusline mà Claude
|
||
Code biết — đọc được tất cả, còn sửa/tạo/xóa thì chỉ cho các bề mặt dạng file
|
||
text (skill, agent, command, output style, `CLAUDE.md`). Plugin, MCP, hook và
|
||
`settings.json` để read-only: chúng tranh ghi với CLI đang chạy.
|
||
- **Giao diện.** Settings → Appearance chọn font của terminal workspace và cỡ
|
||
chữ của nó (11–20 px, mặc định 13), áp dụng ngay cho terminal đang mở, cùng
|
||
**Cỡ chữ** giao diện (Nhỏ / Mặc định / Lớn / Lớn hơn: cỡ chữ gốc 14 / 16 / 17
|
||
/ 18 px mà mọi chữ trong UI co giãn theo). Lưu vào tài khoản.
|
||
- **Cập nhật.** Phát hiện bản mới dựa trên release, kèm nút **Update all** ngay
|
||
trong UI (marketplace → mọi plugin → AgentHub sau cùng → reload session).
|
||
- **CLI cho toàn bộ** (`agenthub`, và `agenthub repl`), cài được như PWA, UI có
|
||
tiếng Anh, Việt, Trung và Hàn.
|
||
|
||
## Yêu cầu hệ thống
|
||
|
||
| Cần | Phiên bản | Dùng cho |
|
||
|---|---|---|
|
||
| **Node.js** | >= 20 (>= 22.5 nếu cài qua plugin) | Tất cả. Cả hai test suite verify xanh trên Node **24** và **26** |
|
||
| **npm** | 9+ | Đi kèm Node |
|
||
| **git** | bất kỳ | Clone repo, và mọi thao tác workspace (worktree, đọc branch/status) |
|
||
| **tmux** | 3.x | Run console trên trình duyệt, `agenthub workspace shell`, gõ `/reload-plugins` vào pane đang sống |
|
||
| **Claude Code** | 2.x | Hook ingestion — toàn bộ phần monitoring |
|
||
| **Codex CLI** | bất kỳ | Tùy chọn — chỉ cho workspace dùng `codex` |
|
||
| **GitHub CLI (`gh`)** | bất kỳ | Tùy chọn — chỉ cho `agenthub workspace ci status` |
|
||
| **systemd (user)** | — | Tùy chọn — chỉ cho `agenthub service install` (tự khởi động khi boot, Linux) |
|
||
|
||
Node **25** là bản duy nhất nên tránh: nó làm gãy 6 test server do lệch ABI
|
||
`better-sqlite3` và 20 test client do thay đổi global `localStorage`. Tới 26 thì
|
||
cả hai đã hết (1712 test server + 488 test client xanh trên v26.8.1).
|
||
|
||
### Cài tmux
|
||
|
||
Dashboard gọi thẳng binary `tmux`, không có bản dự phòng đi kèm, nên thiếu nó
|
||
thì **Start Run** và `agenthub workspace shell` sẽ lỗi. Phần còn lại (session,
|
||
analytics, workspace, stage detection, CLI) vẫn chạy bình thường.
|
||
|
||
```bash
|
||
sudo apt install tmux # Debian / Ubuntu
|
||
sudo dnf install tmux # Fedora / RHEL
|
||
brew install tmux # macOS
|
||
sudo pacman -S tmux # Arch
|
||
```
|
||
|
||
Windows không có tmux native — chạy AgentHub trong WSL2 và cài tmux ở trong đó.
|
||
|
||
macOS (đã rà soát code, chưa kiểm thử trên máy Mac): `brew install node git tmux`
|
||
(Node >= 22.5 cho bản plugin), thêm `~/.local/bin` vào `PATH` trong `~/.zshrc`.
|
||
Không có systemd, nên dashboard chạy đến khi đăng xuất/khởi động lại và tự lên
|
||
lại ở phiên Claude Code kế tiếp, hoặc chạy tay bằng `agenthub start`. Chi tiết
|
||
và checklist kiểm tra: [INSTALL.md § macOS](../INSTALL.md#macos).
|
||
|
||
Kiểm tra, cả từ shell của bạn lẫn từ góc nhìn của server:
|
||
|
||
```bash
|
||
tmux -V # ví dụ: tmux 3.4
|
||
curl -s localhost:4820/api/run/tmux # {"available":true}
|
||
```
|
||
|
||
Mỗi workspace chạy trong một tmux session tên `agenthub-lane-<id>`, nên terminal
|
||
trên trình duyệt và `tmux attach -t agenthub-lane-<id>` (hoặc `agenthub workspace
|
||
shell`) ở máy là hai client trên cùng một pane — chúng đồng bộ với nhau, và tắt
|
||
dashboard không bao giờ giết run đang chạy. Detach bằng `Ctrl-b d`.
|
||
|
||
## 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 https://git.smartgift.io.vn/Smartgift-AI/AgentHub.git
|
||
/plugin install agenthub@agenthub
|
||
```
|
||
|
||
Lần session-start đầu tiên sẽ cài hooks, boot server, đưa `agenthub` vào PATH và
|
||
chạy detached nên session không phải chờ. `/agenthub-doctor`
|
||
báo trạng thái, `/agenthub-open` build UI và in URL, `/agenthub-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`](PLUGINS.md).
|
||
|
||
## Cài từ checkout
|
||
|
||
```bash
|
||
npm run setup # cài dependency cho root và client
|
||
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 `agenthub` đã cài, không thì mỗi
|
||
event bị đếm hai lần.
|
||
|
||
### Chạy như một service (tự khởi động khi boot máy)
|
||
|
||
`npm start` chỉ chạy khi terminal đó (hoặc tiến trình nền của `agenthub start`)
|
||
còn sống — reboot máy là mất. Trên Linux, `agenthub service install` dựng một
|
||
systemd `--user` service thay vào đó, để `:4820` tự động chạy lại sau mỗi lần
|
||
reboot, không cần thao tác thủ công và không cần Claude Code (hay AI tool
|
||
nào) để kích hoạt:
|
||
|
||
```bash
|
||
npm run build # service serve client đã build, giống npm start
|
||
agenthub service install # ghi + enable ~/.config/systemd/user/agenthub.service
|
||
agenthub service status # systemctl --user status agenthub
|
||
agenthub service uninstall # disable và gỡ bỏ
|
||
```
|
||
|
||
`agenthub service install` cũng thử chạy `loginctl enable-linger` để service khởi
|
||
động được cả khi cold boot (chưa ai login); nếu máy cần quyền cao hơn, lệnh
|
||
này sẽ in ra `sudo loginctl enable-linger <user>` để bạn tự chạy một lần.
|
||
Trong dashboard cũng có công tắc tương ứng — Settings → Hệ thống → **Tự động khởi
|
||
động AgentHub** (mặc định tắt; chỉ enable/disable unit, không bao giờ dừng
|
||
server đang chạy). Bản cài qua plugin chỉ được tự khởi động khi công tắc này
|
||
bật — xem
|
||
[Auto-start on boot](PLUGINS.md#auto-start-on-boot) trong
|
||
`docs/PLUGINS.md`.
|
||
|
||
## CLI
|
||
|
||
`agenthub` được link sẵn bởi `npm run setup`; không thì gọi `node bin/agenthub.js`.
|
||
|
||
```bash
|
||
agenthub status # dashboard có đang chạy không
|
||
agenthub start # start ngầm (background) và chờ tới khi healthy
|
||
agenthub service install # tự khởi động khi boot máy qua systemd --user (Linux)
|
||
agenthub sessions # session gần đây
|
||
agenthub workspaces # danh sách workspace kèm stage và progress
|
||
agenthub workspace pipeline # pipeline template của lane này, hoặc đổi nó
|
||
agenthub workspace node <id> # chạy riêng command của MỘT node (không có id: liệt kê)
|
||
agenthub stage <name> # khai báo stage hiện tại của lane
|
||
agenthub tail # xem live event feed
|
||
```
|
||
|
||
`agenthub --help` liệt kê phần còn lại.
|
||
|
||
## Workspace
|
||
|
||
Workspace 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
|
||
agenthub workspace add --cwd /path/to/repo --title "My feature" # adopt
|
||
agenthub workspace add --repo /path/to/repo --slug my-feature # managed worktree
|
||
```
|
||
|
||
Mỗi workspace còn mang theo CLI điều khiển nó — `claude` (mặc định) hoặc `codex` —
|
||
chọn trong modal Add workspace và cố định suốt vòng đời của workspace. Workspace Codex có panel
|
||
chạy với các lựa chọn riêng của Codex (sandbox, approval, reasoning effort) và
|
||
resume bằng `codex resume --last`. Codex không bắn hook của dashboard này, nên
|
||
workspace Codex vẫn ghi lịch sử chạy nhưng không xuất hiện ở Sessions và Analytics.
|
||
Workspace Codex cũng **không có pipeline** — không stage, không pipeline map, không
|
||
suy luận hay tự nhảy stage; dashboard chỉ phản ánh trạng thái running/idle từ
|
||
rollout journal của chính Codex trên đĩa (`$CODEX_HOME/sessions/**/rollout-*.jsonl`,
|
||
poll mỗi `DASHBOARD_CODEX_POLL_MS` ms, mặc định 15000).
|
||
|
||
**Pipeline đang tạm ngưng (dormant).** AgentHub không đi kèm pipeline template
|
||
nào, nên workspace không có stage cho tới khi bạn thả một file template JSON vào
|
||
`DASHBOARD_PIPELINES_DIR` (xem
|
||
[`docs/LANES.md`](LANES.md#custom-pipeline-templates)); trước đó
|
||
`agenthub stage` trả về `ENOPIPELINE` và trang Workspace ẩn pipeline map. Phần
|
||
này sẽ được phát triển tiếp.
|
||
|
||
Stage khai báo (declared) đến từ `agenthub 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 workspace 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 workspace có thể đổi sau khi tạo — `agenthub workspace
|
||
pipeline <template>` từ terminal, hoặc dùng picker chọn pipeline-template
|
||
cạnh tiêu đề workspace 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 workspace 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.
|
||
|
||
Workspace cũng có thể chạy **application stack riêng của nó**, cô lập theo từng
|
||
workspace, khi repository của nó khai báo một profile tại `<repo>/.agenthub/profile/`
|
||
— một file `profile.env` khai báo cộng shell hooks mà dashboard gọi. Mỗi workspace
|
||
được cấp một slot, port và thư mục riêng theo workspace được suy ra từ đó:
|
||
|
||
```bash
|
||
agenthub workspace up # boot stack của lane sở hữu thư mục hiện tại
|
||
agenthub workspace runtime # slot, port, tình trạng service
|
||
agenthub workspace logs api # tail log của một service
|
||
agenthub workspace down
|
||
```
|
||
|
||
Service chạy hoàn toàn detached, nên restart dashboard không bao giờ dừng
|
||
workspace đang chạy. Đây là namespacing tài nguyên trên host, không phải
|
||
container: các workspace chạy chung user và share network.
|
||
|
||
[`docs/LANES.md`](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 (`.husky/pre-commit`)
|
||
chạy Prettier, rồi chạy những test mà commit cần: cả hai bộ đầy đủ cho commit
|
||
lớn hoặc rủi ro (hơn 10 file code, đổi dependency, cấu hình build/test hay
|
||
chính hook, có xoá file), chỉ test liên quan cho commit nhỏ (`vitest related`
|
||
cho `client/`, các file test server có nhắc tới module được stage), và không
|
||
chạy test nào nếu chỉ sửa tài liệu. `AGENTHUB_FULL_TESTS=1 git commit …` buộc
|
||
chạy cả hai bộ đầy đủ.
|
||
|
||
## Cấu trúc thư mục
|
||
|
||
| Đường dẫn | Là gì |
|
||
|---|---|
|
||
| `server/` | Express API, schema SQLite, hook ingest, thư viện workspace và worktree |
|
||
| `client/` | Dashboard React 18 + Vite + Tailwind |
|
||
| `bin/agenthub.js` | CLI |
|
||
| `docs/` | Architecture, API, workspaces, 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`](LANES.md) — workspace, pipeline, stage detection
|
||
- [`docs/API.md`](API.md) — REST endpoint (`openapi.yaml` được generate tự động)
|
||
- [`docs/DATABASE.md`](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
|