nntrivi2001
e972267a42
The ten `agenthub-*` plugins were listed by the marketplace but could never be
installed — two schema mistakes present since the entries were first authored
(57dc915), both invisible until you actually run `claude plugin install`:
- marketplace entries used `"path": "plugins/<name>"`; the CLI only accepts
`"source"`, so every one failed with
`This plugin's marketplace entry is invalid: source: Invalid input`
- each `plugin.json` carried npm's `"repository": { "type", "url" }` object;
the schema wants a plain string, so the next attempt failed with
`Validation errors: repository: Invalid input`
Verified by installing all 11 entries into a throwaway CLAUDE_CONFIG_DIR:
1/11 before, 11/11 after. `plugins-marketplace.test.js` was asserting the
broken shape, which is why CI stayed green — it now asserts `source` and
rejects `path`.
Marketplace renamed `claude-code-agent-monitor-plugins` -> `agenthub`, so the
install line is `agenthub@agenthub`. ARCHITECTURE.md documented a marketplace
name (`smartgift-claude-code-monitor`) that never existed in any revision.
The documented `/plugin marketplace add Smartgift-AI/Claude-Code-Monitor` also
never worked: the `owner/repo` shorthand resolves to github.com only, and this
repo is self-hosted on Gitea. Confirmed the CLI rejects `host/owner/repo` and
ignores GH_HOST / GITHUB_HOST / CLAUDE_CODE_MARKETPLACE_URL, so the full
https:// clone URL is the only supported form. Same GitHub-habit class fixed
elsewhere: raw.githubusercontent.com icon URLs (404, and the repo ships
favicon.svg not favicon.ico — the client had the same dead /favicon.ico),
a smartgift.github.io docs link (404), and Gitea `/blob/<ref>/` paths that
must be `/src/branch/<ref>/`.
Repository renamed to Smartgift-AI/AgentHub throughout. Gitea 301-redirects
the old name, so these were stale rather than broken; `docs/superpowers/`
keeps the old name because those are dated decision records.
Adds `repo-links.test.js` to guard both classes (it runs under the existing
pre-commit gate) plus an openapi.yaml drift check — the committed spec had
silently fallen a minor version behind package.json. `generate-openapi-yaml.js`
now exports `render()` so the test compares against one definition of the dump
options instead of a second copy.
203 lines
9.8 KiB
Markdown
203 lines
9.8 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; **lane** (làn đường) theo dõi
|
|
công việc song song của agent qua một pipeline; còn CLI `agenthub` điều khiển phiên
|
|
terminal thật, runtime của lane, 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 [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 `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 lane — đú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 lanes shell`. Chạy CLI nào là thiết lập riêng của từng lane.
|
|
- **Analytics (tab trong dashboard), alert và workflow view**, cộng thêm 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 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`](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 `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.
|
|
Bản cài qua plugin cũng được tự khởi động tương tự — xem
|
|
[Auto-start on boot](docs/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 lanes # danh sách lane kèm stage và progress
|
|
agenthub lanes pipeline # pipeline template của lane này, hoặc đổi nó
|
|
agenthub lanes node <id> # chạy riêng command của MỘT node (không có id: liệt kê)
|
|
# (trong session: /intake, /qc, /ship-full, /ship-quick …)
|
|
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.
|
|
|
|
## 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
|
|
agenthub lanes add --cwd /path/to/repo --title "My feature" # adopt
|
|
agenthub lanes add --repo /path/to/repo --slug my-feature # managed worktree
|
|
```
|
|
|
|
Mỗi lane còn mang theo CLI điều khiển nó — `claude` (mặc định) hoặc `codex` —
|
|
chọn trong modal Add lane và cố định suốt vòng đời của lane. Lane 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
|
|
lane Codex vẫn ghi lịch sử chạy nhưng không xuất hiện ở Sessions và Analytics.
|
|
**Stage detection thì vẫn chạy**, đọc 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) — thứ lane Codex không tự có là stage **khai báo**, vì chỉ chính
|
|
session đó mới gọi được `agenthub stage`.
|
|
|
|
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 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 — `agenthub 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>/.agenthub/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
|
|
agenthub lanes up # boot stack của lane sở hữu thư mục hiện tại
|
|
agenthub lanes runtime # slot, port, tình trạng service
|
|
agenthub lanes logs api # tail log của một service
|
|
agenthub 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/agenthub.js` | CLI |
|
|
| `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
|