Chuyển tới nội dung chính

Bài 0 — Chạy thử trong 10 phút

Bài này dựng AgentJira ở chế độ DEV-LITE với agent giả lập, rồi cho một task chạy trọn vòng để bạn thấy cơ chế hoạt động — không cần API key, không cần cài agent CLI nào.

Đối tượng: người muốn xem sản phẩm chạy trước khi quyết định dựng thật. Điều kiện: Node.js 22.x, Docker Compose v2 đang chạy, git, ~8 GB RAM rảnh. Thời gian: ~10 phút (lần đầu tải image có thể lâu hơn).

Chế độ này KHÔNG kiểm thử được phân quyền

DEV-LITE đặt AGENTBOARD_DEV_IDENTITY=1, tức là mọi request đều là owner của mọi Space. Muốn thử RBAC, Human Gate hay chuỗi danh tính thật thì cần DEV FULL-STACK — xem Cài đặt và chạy lần đầu. Đừng lấy bài này làm căn cứ đánh giá bảo mật.

Cái bạn sẽ thấy ở cuối bài​

Một task chạy bằng agent giả lập (ScriptedProvider): nó phát event thinking, chạy git status, sửa README.md trong worktree cách ly rồi ghi result.json. Task tự chuyển sang cột Review, không tự sang done. Đó chính là cơ chế thật — chỉ có phần "suy nghĩ" là giả.

1. Chuẩn bị một repo nháp để agent sửa (1 phút)​

Agent làm việc trên một bản checkout cách ly của repo bạn chỉ định, nên cần một repo git thật. Dùng repo nháp để không lo gì:

mkdir -p ~/agentjira-sandbox && cd ~/agentjira-sandbox
git init -b main
printf '# Sandbox\n\nRepo nháp để thử AgentJira.\n' > README.md
git add README.md && git commit -m "init"
pwd    # ghi lại đường dẫn tuyệt đối, bước 4 cần
Đường dẫn phải nằm trong danh sách cho phép

Khi không đặt ALLOWED_REPO_ROOTS, server chỉ nhận repo nằm trong thư mục home, /tmp hoặc workspace của chính nó. ~/agentjira-sandbox thoả điều kiện đó.

2. Bật 8 service nền (3–5 phút lần đầu)​

Từ thư mục gốc của repo AgentJira:

./scripts/dev.sh deps up

Một lệnh này lo hết: sinh secret vào .env.dev và arkon/.env.dev.docker, bật Postgres của Board, Postgres pgvector + Redis + MinIO + API + 2 worker + UI của Arkon, chờ healthcheck, rồi tự ghi ai-agent-board/packages/server/.env với DATABASE_URL, ARKON_API_URL, ARKON_ENCRYPTION_KEY, ARKON_SSO_SHARED_SECRET, AGENTBOARD_DEV_IDENTITY=1 và AGENTBOARD_BOOTSTRAP_OWNERS.

deps up từ chối chạy nếu stack full đang giữ cổng 8080

Hai chế độ thay thế nhau, không cộng vào nhau. Gặp lỗi cổng thì ./scripts/dev.sh down trước rồi chạy lại.

3. Bật agent giả lập rồi khởi động server + client (2 phút)​

cd ai-agent-board
npm install                 # lần đầu
npm run build:shared        # BẮT BUỘC lần đầu — server và client đều import từ đây

echo 'AGENTBOARD_FAKE_AGENT=1' >> packages/server/.env

npm run dev                 # server :8080 + client :8081, hot reload

AGENTBOARD_FAKE_AGENT=1 khiến server dùng ScriptedProvider cho mọi loại agent, nên bạn không cần claude / codex / copilot trên PATH và không tốn token nào.

Xác minh:

curl -s http://localhost:8080/api/health     # → {"status":"ok","timestamp":...}
curl -s http://localhost:8080/api/me | head  # → actor có role, không phải "system"

Mở http://localhost:8081 trên trình duyệt — bạn sẽ thấy trang Projects. (Cố ý viết dạng code chứ không phải link: bản tài liệu công khai không được mang href trỏ về localhost, CI chặn.)

4. Tạo task và chạy agent (2 phút)​

  1. Mở project Default (Open Project) — project này cho phép nhập đường dẫn repo theo từng task.
  2. Bấm New Task (hoặc phím N) và điền:
    • Title: Thêm dòng mô tả vào README
    • Description: Cập nhật README.md cho rõ mục đích repo. Non-goals: không đổi file khác.
    • Agent: để mặc định (agent giả lập nhận mọi loại)
    • Local Path: đường dẫn từ bước 1, ví dụ ~/agentjira-sandbox
    • Worktree: bật
  3. Create Task → task nằm ở cột Backlog.
  4. Kéo task sang In Progress, rồi bấm Start Agent.

5. Quan sát — đây là phần đáng xem (1 phút)​

Panel bên phải mở ra 4 tab. Nhìn theo thứ tự này:

TabBạn thấy gìÝ nghĩa
Eventsdòng thinking, rồi command: git statusStream realtime qua WebSocket, không phải polling
ChangesREADME.md bị sửaDiff đang hình thành trong worktree, không phải trong thư mục làm việc của bạn
Follow-upô nhập tin nhắnNhắn thêm được giữa lúc agent chạy, không phải restart
Commentsdòng thảo luận của taskNơi trao đổi giữa người với người trên task
@mention sinh subtask chưa bật ở bài này

Gõ @qa <việc> trong Comments để sinh subtask con là tính năng sau cờ AGENTBOARD_MENTION_SUBTASK — mặc định tắt, và deps up không bật nó. Muốn thử: thêm AGENTBOARD_MENTION_SUBTASK=1 vào packages/server/.env rồi restart npm run dev. Chi tiết: Tạo task và chạy agent.

Agent xong việc → task tự chuyển sang cột Review với reviewState = peer-review. Nó không tự sang done: chốt cuối phải do người bấm. Đó là Human Gate.

Kiểm chứng worktree cách ly — chạy trong repo nháp:

cd ~/agentjira-sandbox
git status              # → clean: nhánh main của bạn không bị đụng tới
git worktree list       # → có thêm một worktree agent/<task-key>
git log --all --oneline | head

6. Dọn (30 giây)​

# Ctrl+C ở tiến trình npm run dev, rồi:
./scripts/dev.sh deps down     # giữ dữ liệu
./scripts/dev.sh reset         # xoá luôn mọi volume

Nếu vướng​

Triệu chứngNguyên nhânXử lý
Cannot find module '@ai-agent-board/shared/types.js'Chưa build package sharednpm run build:shared
Tạo Space trả HTTP 500Lệch ARKON_SSO_SHARED_SECRET ↔ SSO_SHARED_SECRET (host gọi qua cổng published không phải loopback)Chạy lại ./scripts/dev.sh deps up để nó ghi đúng
Task tạo được nhưng không chạyChưa có agent CLI nào, và chưa bật agent giả lậpThêm AGENTBOARD_FAKE_AGENT=1 vào packages/server/.env rồi restart npm run dev
repoPath must be an absolute pathNhập đường dẫn tương đốiNhập đường dẫn tuyệt đối (~ được chấp nhận)
Bấm Start Agent không có gì xảy raTask còn ở backlogKéo sang In Progress trước
deps up báo cổng 8080 bị chiếmStack full đang chạy./scripts/dev.sh down rồi chạy lại

Triệu chứng khác: Xử lý sự cố.

Bước tiếp theo: hiểu cái vừa thấy → Khái niệm cốt lõi · dựng bản dùng thật có phân quyền → Bài 1 — Lần đầu đăng nhập · dựng cho cả team → Cài đặt và chạy lần đầu

Cập nhật lần cuối vào