# Hướng dẫn về Repository và Agents

- **Link Repo:** https://github.com/moltbot/moltbot
- **Giao tiếp trên GitHub:** Khi comment trên Issues hoặc PR, hãy dùng chuỗi nhiều dòng (literal multiline strings) hoặc `-F - <<'EOF'` (hoặc `$'...'`) để tạo dòng mới thực sự. Tuyệt đối không nhúng ký tự `\n` vào chuỗi.

## Cấu trúc Dự án & Tổ chức Module

- **Mã nguồn (`src/`):** Nơi chứa toàn bộ source code.
  - `src/cli`: Các file kết nối CLI.
  - `src/commands`: Logic các câu lệnh commands.
  - `src/provider-web.ts`: Nhà cung cấp dịch vụ web.
  - `src/infra`: Cơ sở hạ tầng.
  - `src/media`: Pipeline xử lý media.
- **Tests:** Các file test (`*.test.ts`) được đặt ngay cạnh file code tương ứng (colocated).
- **Tài liệu (`docs/`):** Chứa ảnh, tài liệu về hàng đợi (queue), cấu hình Pi. File build ra sẽ nằm trong `dist/`.
- **Plugins/Extensions:**
  - Nằm trong thư mục `extensions/*` (được quản lý như các gói workspace).
  - **Lưu ý quan trọng:** Chỉ thêm dependencies vào file `package.json` của extension đó, KHÔNG thêm vào `package.json` gốc của dự án trừ khi phần core thực sự cần dùng.
  - **Cài đặt:** Khi chạy install plugin, hệ thống sẽ chạy `npm install --omit=dev`. Do đó, các dependency cần thiết khi chạy (runtime) phải nằm trong `dependencies`.
  - Tránh dùng `workspace:*` trong `dependencies` vì sẽ gây lỗi khi `npm install`. Thay vào đó, hãy để `moltbot` trong `devDependencies` hoặc `peerDependencies`. Runtime sẽ tự động giải quyết `clawdbot/plugin-sdk` thông qua jiti alias.
- **Trình cài đặt (Installers):** Các file script cài đặt (`install.sh`, `install.ps1`...) nằm ở repo anh em `../molt.bot`.
- **Kênh nhắn tin (Channels):**
  - Khi sửa logic chung (routing, allowlists, pairing...), hãy nhớ kiểm tra ảnh hưởng đến **tất cả** các kênh (cả built-in và extensions).
  - Tài liệu kênh: `docs/channels/`
  - Code kênh core: `src/telegram`, `src/discord`, `src/slack`, v.v.
  - Extensions: `extensions/msteams`, `extensions/zalo`...

## Quy chuẩn Liên kết Tài liệu (Mintlify)

- **Website Docs:** [docs.molt.bot](https://docs.molt.bot).
- **Link nội bộ (trong thư mục `docs/`):** Sử dụng đường dẫn tương đối gốc (root-relative), KHÔNG có đuôi `.md`.
  - *Ví dụ đúng:* `[Cấu hình](/configuration)`
  - *Ví dụ sai:* `[Cấu hình](../configuration.md)`
- **Tham chiếu chéo (Anchor links):** Dùng anchor trên đường dẫn gốc. Ví dụ: `[Hooks](/configuration#hooks)`.
- **Tiêu đề:** Tránh dùng dấu gạch ngang dài (em dashes `—`) hoặc dấu nháy đơn `'` trong tiêu đề bài viết vì chúng làm hỏng cơ chế tạo link anchor của Mintlify.
- **Gửi link cho người khác:** Luôn dùng URL đầy đủ `https://docs.molt.bot/...`.
- **Trong README:** Luôn dùng link tuyệt đối để bấm được ngay trên GitHub.
- **Nội dung:** Viết chung chung, tránh lộ tên thiết bị/hostname cá nhân. Dùng `user@gateway-host` thay vì `hieu@may-cua-toi`.

## Vận hành VM (Dành cho nội bộ exe.dev)

- **Truy cập:** `ssh exe.dev` -> `ssh vm-name`.
- **Lưu ý:** SSH có thể chập chờn, nên dùng Shelley (web agent) hoặc giữ phiên `tmux` nếu chạy tác vụ lâu.
- **Cập nhật:** `sudo npm i -g moltbot@latest` (Cần quyền root vì cài global).
- **Cấu hình:** Dùng `moltbot config set ...` và đảm bảo `gateway.mode=local`.
- **Discord:** Lưu token thô, không cần tiền tố `DISCORD_BOT_TOKEN=`.
- **Khởi động lại (Restart):** Kill process cũ và chạy lại nohup.
- **Kiểm tra:** Dùng `moltbot channels status --probe` hoặc `tail` log.

## Lệnh Build, Test & Dev

- **Runtime:** Node **22+**. (Dự án vẫn hỗ trợ cả Node và Bun).
- **Cài đặt:** `pnpm install` (Ưu tiên). `bun install` cũng được hỗ trợ (nhớ đồng bộ `pnpm-lock.yaml`).
- **Dev:**
  - Chạy script/test: Dùng `bun` cho nhanh (`bun <file.ts>`).
  - Chạy CLI dev: `pnpm moltbot ...` (chạy qua bun/tsx) hoặc `pnpm dev`.
  - Chạy bản build (production): Dùng Node để chạy file trong `dist/`.
- **Check code:** `pnpm build` (tsc), `pnpm lint` (oxlint), `pnpm format` (oxfmt).
- **Test:** `pnpm test` (vitest).

## Phong cách Code (Coding Style)

- **Ngôn ngữ:** TypeScript (ESM). Bắt buộc dùng kiểu dữ liệu chặt chẽ (strict typing), hạn chế tối đa `any`.
- **Lint/Format:** Phải chạy `pnpm lint` trước khi commit.
- **Comment:** Viết chú thích ngắn gọn cho các đoạn logic "ảo diệu" hoặc khó hiểu.
- **Kích thước file:** Cố gắng giữ dưới ~700 dòng code. Tách nhỏ ra nếu file quá dài để dễ đọc và dễ test.
- **Đặt tên:**
  - **Moltbot**: Dùng cho tên sản phẩm, tiêu đề tài liệu.
  - `moltbot`: Dùng cho lệnh CLI, tên gói, đường dẫn file, key cấu hình.

## Kênh phát hành (Release Channels)

- **stable**: Chỉ dành cho bản release có gắn thẻ (`vYYYY.M.D`).
- **beta**: Bản thử nghiệm (`-beta.N`), có thể không có app macOS đi kèm.
- **dev**: Nhánh `main` đang phát triển.

## Hướng dẫn Test

- **Framework:** Vitest.
- **Ngưỡng coverage:** 70% (dòng, nhánh, hàm).
- **Tên file:** `*.test.ts` (unit test) và `*.e2e.test.ts` (end-to-end test).
- **Workers:** Tối đa 16 workers.
- **Live Test:** Test với key thật (API thật) dùng lệnh `CLAWDBOT_LIVE_TEST=1 pnpm test:live`.
- **Mobile:** Ưu tiên test trên thiết bị thật (iOS/Android) trước khi dùng giả lập.

## Quy trình Commit & PR

- **Tạo commit:** Dùng script `scripts/committer "<msg>" <file...>` thay vì `git commit` thủ công để đảm bảo quy chuẩn.
- **Thông điệp:** Ngắn gọn, bắt đầu bằng động từ (Ví dụ: `CLI: add verbose flag`).
- **PR:**
  - Mỗi PR nên tập trung vào một vấn đề. Đừng gom nhiều refactor không liên quan vào một PR.
  - **Review:** Dùng `gh pr view` hoặc `gh pr diff`. Đừng switch nhánh lung tung.
  - **Merge:** Ưu tiên **Rebase** để lịch sử đẹp. Nếu lịch sử quá rối rắm thì **Squash**.
  - Luôn thêm người đóng góp (PR author) vào danh sách co-contributor nếu squash.
  - Sau khi merge PR của người mới: Nhớ chạy script cập nhật danh sách contributors trong README.

## An toàn Đa Tác nhân (Multi-Agent Safety) 🤖

Khi làm việc trong môi trường có nhiều Agent cùng hoạt động:
1.  **Git Stash:** KHÔNG BAO GIỜ tự ý `git stash` hoặc `git pull --rebase --autostash` trừ khi được user yêu cầu. Agent khác có thể đang code dở.
2.  **Git Worktree:** KHÔNG tạo, xóa, sửa worktree nếu không được bảo.
3.  **Chuyển nhánh:** KHÔNG tự ý switch nhánh.
4.  **File lạ:** Nếu thấy file lạ (do agent khác tạo), cứ lờ đi và tập trung vào file của mình.
5.  **Sung đột:** Khi user bảo "push", có thể `git pull --rebase`. Khi "commit", chỉ commit file bạn sửa.

---

> **Mẹo nhỏ:** Moltbot được thiết kế rất linh hoạt. Hãy đọc kỹ code trước khi sửa, và luôn ưu tiên sự ổn định (stability) lên hàng đầu. Chúc bạn code vui vẻ! 🦞