Bắt đầu

Cài đặt decode, trỏ nó vào một mô hình và chạy phiên đầu tiên của bạn — trong khoảng 5 phút.

Hướng dẫn này đủ để thiết lập chế độ decode tương tác cần thiết cho hai bài học đầu tiên.

0. Bắt đầu nhanh

# 0. install uv first:  curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/decodingai-magazine/building-a-coding-agent-from-scratch-course.git
cd building-a-coding-agent-from-scratch-course
make install
cp .env.example .env      # then set GEMINI_API_KEY (free: https://aistudio.google.com/apikey)
uv run decode

1. Điều kiện tiên quyết

Được hỗ trợ trên macOS, Linux và Windows thông qua WSL2. Windows gốc (PowerShell / cmd) chưa được kiểm tra - các tổ hợp phím TUI giả định một vỏ POSIX.

Đó là toàn bộ danh sách. Docker và gcloud được yêu cầu cho các bài học sau — 04_sandboxing.md và 07_infra.md sẽ hướng dẫn bạn cách thiết lập.

****** Điểm kiểm tra** — uv --version in một phiên bản. Nếu nó nói command not found, uv đã được cài đặt nhưng chưa có trên PATH của bạn: khởi động lại shell của bạn.

2. Cài đặt

git clone https://github.com/decodingai-magazine/building-a-coding-agent-from-scratch-course.git
cd building-a-coding-agent-from-scratch-course
make install        # uv sync + wire git hooks   (or just: uv sync)

Sau đó cài đặt decode như một công cụ CLI:

make install-cli    # uv tool install --editable .  — the command tracks your source

Nếu decode không được tìm thấy sau đó, hãy chạy uv tool update-shell và khởi động lại Shell của bạn. Gỡ cài đặt với make uninstall-cli.

****** Điểm kiểm tra** — decode --version bản in decode, version <x.y.z>. Điều đó chứng tỏ venv, Python được ghim và điểm vào đều giải quyết được. Nó cần không cần khóa API — --version thoát trước khi bất kỳ nhà cung cấp nào được xây dựng.

3. decode điểm tại mô hình

Để kết thúc quá trình cài đặt, bạn cần định cấu hình một vài biến môi trường.

Từ thư mục gốc repo, hãy chạy:

cp .env.example .env

Bây giờ hãy điền một trong ba nhà cung cấp mô hình:

• 3a. Modal — những gì chúng tôi đề xuất. Bạn tự phục vụ mô hình trọng lượng mở nên không có giới hạn tỷ lệ nào cần đạt: khoản tín dụng đăng ký $30 mua khoảng 7 giờ trên 1×H100 mà chế độ chạy mặc định tiếp tục, đủ để chạy toàn bộ khóa học. Bạn cũng có thể xem mô hình tạ mở của riêng mình điều khiển dây đai mà bạn đã chế tạo, thay vì hộp đen đằng sau API của ai đó.
• 3b. OpenRouter — được lưu trữ, vẫn miễn phí. Một phím, không cần quản lý GPU; bộ định tuyến miễn phí truyền bá cuộc gọi của bạn trên các mô hình có khả năng sử dụng công cụ miễn phí. Giới hạn hàng ngày ở mức thấp cho đến khi bạn thêm tín dụng - $10 sẽ tăng số tiền đó.
• 3c. Song Tử — lần chạy đầu tiên nhanh nhất. Một khóa và đó là nhà cung cấp mặc định nên không cần đặt gì khác. Thật không may, bạn sẽ nhanh chóng đạt đến giới hạn tốc độ của nó, điều này gây khó chịu khi sử dụng.

Chuyển đổi sau đó là một vài dòng trong .env và không thay đổi mã — vì vậy hãy bắt đầu ở bất cứ nơi nào bạn sẽ chạy trong 60 giây, sau đó chúng tôi khuyên bạn nên chuyển sang Modal khi giới hạn tốc độ bắt đầu khiến bạn mất thời gian.

3a. Modal — mô hình nguồn mở của riêng bạn (được khuyến nghị)

Bạn phân phát một mô hình trọng lượng mở trên GPU và decode các cuộc đàm phán với nó qua điểm cuối tương thích với OpenAI. Ba lệnh và ba vars env:

# 1. authenticate the CLI ($30 credits on signup: https://modal.com?source=decodingai&campaign=harnesseng)
uv run modal token set --token-id <your-token-id> --token-secret <your-token-secret>

# 2. serve the course default — Modal picks the GPU + serving recipe and prints the endpoint URL
uv run modal endpoint create --model Qwen/Qwen3.6-35B-A3B-FP8 --env main

# 3. mint a token pair so your endpoint isn't open to the world
uv run modal workspace proxy-tokens create   # → Modal-Key: wk-... / Modal-Secret: ws-...

Tại sao uv run modal? Cái modal CLI là phần phụ thuộc của dự án, không phải thứ bạn cài đặt riêng biệt — make install đã đặt nó vào venv rồi, vậy nên uv tìm thấy nó từ thư mục gốc repo. Một trần modal … chỉ hoạt động nếu bạn đã tự kích hoạt venv. Bước 1 là một lần: nó viết ~/.modal.toml trong thư mục chính của bạn và sau đó uv run modal … nhặt nó lên.

Sau đó đặt điểm cuối vào .env:

LLM_PROVIDER=modal

MODAL_TOKEN_ID=ak-...
MODAL_TOKEN_SECRET=as-...

MODAL_ENDPOINT_URL=https://your-workspace--your-app.modal.run   # decode calls {url}/v1
MODAL_ENDPOINT_MODEL=Qwen/Qwen3.6-35B-A3B-FP8

MODAL_PROXY_TOKEN_ID=wk-...          # both, or neither (an --unauthenticated endpoint)
MODAL_PROXY_TOKEN_SECRET=ws-...

Bị mất URL? uv run modal endpoint list --env main.

Hai token tài khoản, hai token điểm cuối — không trộn lẫn chúng. MODAL_TOKEN_ID / MODAL_TOKEN_SECRET xác thực CLI; chúng không decode cài đặt, vì vậy hãy đặt chúng vào .env không làm gì cả - modal token set (viết ~/.modal.toml) hoặc xuất chúng trong shell của bạn mới là điều quan trọng. các MODAL_PROXY_TOKEN_* cặp ở trên là một thứ khác: đó là cách decode calls mô hình được cung cấp của bạn và nó là cả hai hoặc không (cặp nửa đặt là một lỗi khởi động thân thiện, không bao giờ là 401 im lặng).

Xem các khoản tín dụng của bạn. GPU giúp bạn giữ ấm hóa đơn khi không sử dụng. Tự động điều chỉnh Tối thiểu 0 (mặc định) tỷ lệ về 0 giữa các phiên — bạn trả tiền cho lần khởi động nguội đầu tiên thay vì số giờ không hoạt động. Dừng điểm cuối mà bạn đã hoàn thành: uv run modal endpoint stop <endpoint-id> --env main.

Nếu lượt đầu tiên chậm, đó là nguyên nhân khiến GPU bắt đầu bị đánh thức. Cài đặt COMPACTION_CONTEXT_WINDOW_TOKENS=262144 bỏ qua quá trình thăm dò khởi động của decode /v1/models, đây là một yêu cầu phải đợi ở điểm cuối nguội - decode nếu không thì đọc cửa sổ từ điểm cuối, sau đó là bảng tĩnh, sau đó giả sử một giá trị bảo thủ 200000.

Việc chọn một mô hình khác, điều chỉnh điểm cuối, tự động điều chỉnh quy mô, điểm chuẩn và thang chi phí/khả năng đều có trong 02_modal_endpoints.md. Giá trị mặc định ở trên là giá trị mà mỗi bài học được xây dựng và thử nghiệm.

****** Điểm kiểm tra** — điều này trả về id mô hình của bạn và chứng minh URL và cả hai token proxy đều đúng:

curl "$MODAL_ENDPOINT_URL/v1/models" \
  -H "Modal-Key: $MODAL_PROXY_TOKEN_ID" \
  -H "Modal-Secret: $MODAL_PROXY_TOKEN_SECRET"

3b. OpenRouter - mô hình lưu trữ miễn phí

Một khóa tại openrouter.ai, hai dòng trong .env:

LLM_PROVIDER=openrouter
OPENROUTER_API_KEY=sk-or-...
# OPENROUTER_MODEL=openrouter/free   # the default — leave it alone unless you want a specific model

Mặc định openrouter/free là Bộ định tuyến mô hình miễn phí: nó tự động định tuyến trên các mô hình có khả năng sử dụng công cụ miễn phí, vì vậy một mô hình ngược dòng bị tắc nghẽn không thể chặn vòng lặp của bạn. Các mô hình miễn phí có giá 0 USD; việc thêm 10 đô la tín dụng sẽ tăng giới hạn miễn phí hàng ngày (~50 → ~1000 yêu cầu/ngày) mà không phải trả phí cho các mô hình miễn phí.

Ghim một mô hình cụ thể với OPENROUTER_MODEL=<slug> — nhưng hãy kiểm tra xem nó có hỗ trợ gọi công cụ trước không, nếu không sẽ bị ngắt vòng lặp.

****** Điểm kiểm tra** — grep -c '^OPENROUTER_API_KEY=sk-or-' .env bản in 1.

3c. Song Tử - một chìa khóa (bắt đầu nhanh nhất)

LLM_PROVIDER=gemini
GEMINI_API_KEY=your-key-here     # free at https://aistudio.google.com/apikey
# GEMINI_MODEL=gemini-3.5-flash  # the default — leave it alone unless you want a specific model

Thế thôi - gemini là nhà cung cấp mặc định, vì vậy không LLM_PROVIDER dòng là cần thiết. Mong đợi 429 khi bạn bắt đầu lặp lại khó khăn; đó là giới hạn mỗi phút của bậc miễn phí và lý do khóa học khuyến nghị Modal.

****** Điểm kiểm tra** — grep -c '^GEMINI_API_KEY=.\+' .env bản in 1. decode xử lý phần giữ chỗ chưa được điền (changeme, hoặc để trống) dưới dạng unset và dừng khi khởi động với một dòng đặt tên biến, do đó, một dòng được điền một nửa .env không bao giờ đến tay nhà cung cấp.

Ma trận nhà cung cấp

4. Bật theo dõi (tùy chọn, 30 giây)

Theo dõi là công cụ biến vòng lặp từ một bức tường văn bản được truyền trực tuyến thành thứ mà bạn có thể kiểm tra: mỗi lượt được gửi dưới dạng dấu vết, mọi lệnh gọi mô hình và công cụ dưới dạng một khoảng với token, độ trễ và chi phí. Khi người đại diện làm điều gì đó đáng ngạc nhiên, đây là lúc bạn tìm hiểu lý do.

Nhận key: đăng ký tại comet.com (Opik là sản phẩm có khả năng quan sát LLM của Comet), sau đó sao chép khóa API của bạn từ Cài đặt → Khóa API.

OPIK_API_KEY=your-key

Nó vẫn miễn phí. Gói miễn phí của Opik bao gồm 25.000 lượt/tháng — nhiều hơn nhu cầu của khóa học này.

****** Điểm kiểm tra** — chạy một lượt, sau đó mở dự án Opik của bạn: lượt này xuất hiện dưới dạng dấu vết với khoảng thời gian cho mỗi lệnh gọi mô hình/công cụ.

5. Chạy

Cách dễ nhất là chạy decode từ bên trong building-a-coding-agent-from-scratch-course repo bạn vừa nhân bản.

decode

Bạn nhận được REPL tương tác: nhập tin nhắn, nhân viên sẽ gửi câu trả lời và mọi công cụ đều sử dụng yêu cầu phê duyệt trước.

Mọi thứ decode tạo ra đều được lưu trong <cwd>/.decode/ (được bỏ qua): sessions/*.jsonl (phiên có thể phát lại), MEMORY.md (bộ nhớ phiên chéo), logs/decode.log (nhật ký ở ngoài terminal).

****** Điểm kiểm tra** — loại what files are in this directory? và nhấn Enter. Hoạt động trông giống như: agent yêu cầu chạy một công cụ chỉ đọc, truyền ngược lại danh sách và .decode/sessions/ bây giờ nắm giữ một .jsonl bản ghi. Nếu câu trả lời không bao giờ phát trực tuyến, hãy xem 00_troubleshooting.md.

Tiếp tục một phiên

Mỗi phiên là một bản ghi JSONL có thể phát lại trong .decode/sessions/, được khóa theo id phiên:

decode --resume               # continue the most recent session in this directory
decode --resume <session-id>  # continue a specific one (the id is the filename stem)

Bộ nhớ

decode hỗ trợ tiêu chuẩn AGENTS.md.

Ngoài ra, .decode/MEMORY.md tải vào ngữ cảnh khi khởi động và decode thêm một câu tóm tắt về phiên khi thoát — vì vậy, phiên mới đã biết phiên cuối cùng đã làm gì.

Hãy thử một kỹ năng

Chúng tôi đã chuẩn bị một bộ kỹ năng mặc định theo .decode/skills/ dưới dạng bản demo, vì vậy bạn có thể thử coding agent trên thứ gì đó quen thuộc.

cd building-a-coding-agent-from-scratch-course
decode
/demo-1-terminal-arcade    # the agent builds a playable Snake game

Hai kỹ năng (/commit, /review-diff) gửi bên trong gói và làm việc từ bất kỳ thư mục nào. Để sử dụng các bản demo trong dự án của riêng bạn, hãy sao chép chúng qua: cp -r <course-repo>/.decode/skills/. ~/my-project/.decode/skills/.

****** Điểm kiểm tra** — loại / và menu hoàn thành liệt kê các bản demo. Một menu trống có nghĩa là decode đã được khởi chạy ở đâu đó mà không có .decode/skills/ thư mục.

Có gì đó không hoạt động? Mọi lỗi đã biết và cách khắc phục đều có trong 00_troubleshooting.md.

phát triển

make test            # full test suite (unit + integration)
make unit-tests      # unit only
make lint-check      # ruff check        (lint-fix to auto-fix)
make format-check    # ruff format check (format-fix to apply)
make pre-commit      # format + lint + unit tests (the fast gate)
make ci              # what CI runs: lockfile check + format + lint + full suite
make help            # all targets