awesome-agentic-ai-zh

主题

繁體中文 | 简体中文 | English

🚀 從零開始 — 給沒有開發背景的設定指南 ​

← 回主路線 README

預估時程：30-45 分鐘。你會申請第一個 API key、裝好 Python / uv，並跑出第一個 LLM hello world。 這份文件寫給「想學 AI agent，但還沒寫過 code」的人。已經熟 Python / git / CLI 的開發者，可以直接跳 Stage 1。

先選你的入門方式 ​

依「想花多少時間 setup」由淺到深排序。完全沒接觸過 LLM 直接從 1️⃣ 開始就好。

1️⃣ 網頁版（最簡單，免費可試，零 setup） ​

打開瀏覽器就能用，第一次接觸 LLM 最推薦這條。免費 tier 通常夠你試一個禮拜。

服務網址備註
Claudehttps://claude.aiAnthropic 官方。免費 tier 每天額度有限，付費版 $20/月
ChatGPThttps://chatgpt.comOpenAI 官方。免費可用 GPT-5（基本款），付費 $20/月升 Plus
Geminihttps://gemini.google.comGoogle 官方。免費 tier 寬鬆，整合 Google 服務
Le Chathttps://chat.mistral.aiMistral（歐洲開源 LLM）。免費、隱私導向

2️⃣ 桌面 App（免費，跨應用整合更好） ​

跑在你電腦上的原生 app——比網頁多了系統 shortcut、跟剪貼簿 / 截圖整合、可以拖拉檔案。

App下載平台
Claude Desktophttps://claude.ai/downloadmacOS / Windows
ChatGPT Desktophttps://openai.com/chatgpt/downloadmacOS / Windows
Gemini暫無原生 desktop app（用網頁版即可）
LM Studiohttps://lmstudio.aimacOS / Windows / Linux — 跑本機 LLM 的桌面 app，零成本但要 GPU/RAM

3️⃣ IDE 內建 AI（在 code editor 裡邊寫 code 邊有 AI 助手） ​

跑在 IDE / code editor 裡——你正常寫 code，AI 在旁邊 suggest、修改、回答問題。已經有寫 code 習慣、想把 IDE 升級成 AI-native 的人這條最順。

工具下載形態
Cursorhttps://cursor.com獨立 IDE（VS Code fork）
Windsurfhttps://codeium.com/windsurf獨立 IDE（Codeium 出）
Clinehttps://cline.botVS Code extension（agentic 風格）
Continuehttps://continue.devVS Code / JetBrains extension（開源）
Roo Codehttps://github.com/RooCodeInc/Roo-CodeVS Code extension（Cline fork，社群活躍）
Zedhttps://zed.dev獨立 editor，內建 AI assistant
GitHub Copilothttps://github.com/features/copilotVS Code / JetBrains 等多 IDE extension

→ 詳細比較 → branches/for-developer.md

4️⃣ CLI Agent（terminal，能讀寫檔案、跑指令、操作 git） ​

裝在 terminal 的 agent——你下一個 prompt（譬如「重構這個 module」），agent 自己讀檔、改檔、跑指令、commit。比 IDE 模式更自主、可以處理多步驟任務，但 setup 稍複雜（需要先有 Node.js 或 Python，看下面 B / D）。

CLI Agent安裝 / 文件主要 LLM
Claude Codehttps://docs.anthropic.com/en/docs/claude-code/quickstartClaude
Codex CLIhttps://github.com/openai/codexGPT 系列
Gemini CLIhttps://github.com/google-gemini/gemini-cliGemini
OpenCodehttps://github.com/sst/opencode任意（多 provider）
goosehttps://block.github.io/goose任意
Aiderhttps://aider.chat任意（git-native）
Hermes Agenthttps://github.com/NousResearch/hermes-agent200+（model-neutral）

→ 想看 7 個 CLI 完整比較 → cli-agents-guide.md → Claude Code 第一次裝的詳細步驟 → 本指南 D

💡 IDE-based 跟 CLI agent 怎麼選？ 邊寫 code 邊要 AI 幫忙 → IDE；下單一 prompt 讓 agent 自己跑完一整個任務 → CLI。兩個可以並用。

5️⃣ API + 自己寫 code（最進階，能 batch、整合任何工具） ​

想自己寫 Python script、跑 batch job、把 LLM 接到自己的 app／automation？接下來的 A-C 就是給你的。

💡 API key 是什麼：簡單講就是「讓程式呼叫模型的密碼」。請把它當成信用卡資料一樣保管。

A — 申請第一個 API key（約 10 分鐘） ​

Anthropic Claude（推薦第一次） ​

  1. 開 https://console.anthropic.com/
  2. 用 Google、GitHub 或 email 註冊。
  3. 進帳號後找到 API Keys，按 Create Key。
  4. 立刻複製顯示出的 key。多數平台只會顯示一次。
  5. 先放在本機密碼管理器，或短暫放在本機文字檔；下一節會移到 .env。

⚠️ API key 三不規則

  • 不貼到 chat 視窗、群組、email 或截圖。
  • 不上傳到 git；GitHub 可能掃到後自動撤銷。
  • 不放雲端硬碟純文字檔；同步到其他裝置等於多一份風險。

其他 LLM 選項 ​

西方 cloud（美區友善、英文場景） ​

  • OpenAI：https://platform.openai.com/api-keys ChatGPT Plus 和 API key 是兩件事；訂閱 Plus 仍要另外申請 API key。
  • Google AI Studio：https://aistudio.google.com/ 適合先試 Gemini API，免費額度會依地區和帳號狀態不同。
  • NVIDIA NIM：https://build.nvidia.com/托管多個開源 model（Llama / Mistral / DeepSeek-R1 + R2 lineage / Qwen / Gemma 等）、OpenAI-compatible API、新帳號送 1000 credits。適合「想試多個 open-source model 但沒 GPU」的情境。base_url=https://integrate.api.nvidia.com/v1。

中國 / 中文場景（地區友善、價格極便宜） ​

中國大陸使用者連 Anthropic / OpenAI 有困難、或想試中文 native 模型，從這邊開始。這些 API 都 OpenAI-compatible、改 base_url 跟 model name 就能跑同一份練習。

本機（不付 API 費、完全 offline） ​

  • Ollama 本機模型：不用 API key。走本機路線請看 Cookbook Recipe 6。 本 repo 的「Path A」預設就是 Ollama；所有 Stage 1-7 練習都能用 gemma4:e4b（Stage 1-2）或 qwen2.5:3b（Stage 3+）跑通、$0/run。

💡 怎麼挑第一個：

  • 想學 agent / production、美區帳號OK → Anthropic Claude（curriculum canonical）
  • 想學 agent / production、中國地區或想試中文模型 → DeepSeek（最便宜 cloud option、OpenAI-compat、中文很強）
  • 想試多個 model 但沒 GPU → NVIDIA NIM（送 1000 credit、托管 10+ open model）
  • 隱私敏感 / 完全免費 / 中國大陸無 cloud → Ollama（本機、curriculum 全套都能跑、$0）

B — 裝本機環境（約 10 分鐘） ​

裝 Python 3.10+ ​

  • macOS：開 Terminal，輸入 brew install python@3.12。如果還沒有 Homebrew，先看 https://brew.sh。
  • Windows：到 https://www.python.org/downloads/ 下載 installer，安裝時一定要勾 Add Python to PATH。
  • Linux：Ubuntu 用 sudo apt install python3 python3-venv，Fedora 用 sudo dnf install python3。
  • 驗證：macOS / Linux 輸入 python3 --version；Windows 輸入 py --version。看到 Python 3.10 以上即可。

裝 uv ​

uv 是 Python 套件管理工具。你可以把它想成「幫你臨時裝好需要套件再執行」的工具。

bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
irm https://astral.sh/uv/install.ps1 | iex

驗證：

bash
uv --version

建立第一個 .env 檔 ​

在你要跑 script 的資料夾裡，建立一個檔名叫 .env 的檔案：

bash
ANTHROPIC_API_KEY=sk-ant-...貼上你剛才複製的 key

.env 是專門放本機祕密資訊的檔案。程式會讀它，但你不應該把它上傳到 GitHub。

加上 .gitignore ​

同一個資料夾建立 .gitignore：

gitignore
.env
__pycache__/
*.pyc

這樣 git 就不會把 .env 收進版本紀錄。

C — 跑第一個 hello-claude.py（約 5 分鐘） ​

建立 hello-claude.py：

python
from anthropic import Anthropic
from dotenv import load_dotenv

load_dotenv()
client = Anthropic() # 自動讀取 ANTHROPIC_API_KEY

msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=100,
    messages=[{"role": "user", "content": "Hello, who are you?"}],
)

print(msg.content[0].text)

執行：

bash
uv run --with anthropic --with python-dotenv python hello-claude.py

看到 Claude 回覆自我介紹，就代表你的 API key、Python、套件都通了。

常見錯誤 ​

錯誤訊息常見原因解法
401 UnauthorizedAPI key 沒讀到或打錯回 A 重新複製，確認 .env 檔名和內容
429 Rate limit太快送太多請求等幾秒或幾分鐘再跑
connection refused連線或防火牆問題確認網路、公司或學校防火牆
ModuleNotFoundError套件沒有被安裝確認執行的是上面的 uv run --with ... 指令

D — 第一次裝 Claude Code（約 10 分鐘；Stage 5 / for-developer 會用到） ​

先裝 Node.js ​

💡 Node.js 是什麼：跑 JavaScript 的 runtime（類似 Python interpreter 但是給 JS 用）。npm 是它附帶的「套件管理器」（package manager）—— 跟 Python 的 pip 同角色、用來安裝別人寫好的工具（如下面的 Claude Code）。npm install -g X 表示「全域裝 X、之後在任何資料夾都能用」。

  • macOS / Linux：brew install node，或從 https://nodejs.org 下載。
  • Windows：從 https://nodejs.org 下載 installer。
  • 驗證：輸入 node --version，看到 v18 以上即可。

裝 Claude Code ​

bash
npm install -g @anthropic-ai/claude-code

第一次認證 ​

bash
claude

第一次啟動時通常會讓你選：

  • Claude subscription：用 Claude.ai 帳號登入，對初學者最省事。
  • API key：貼上 A 申請到的 key。

建立第一份 CLAUDE.md ​

在你的 project 根目錄建立 CLAUDE.md。Claude Code 啟動時會讀它，理解你希望它怎麼協助。

markdown
# 你是誰
我是 [你的名字]，[你的領域，例如：教師 / 研究者 / 寫作者]。

# Code style
- 註解用繁體中文寫，code 用英文
- 寫 function 時優先加 type hint
- 不要主動 commit；改完讓我手動 git add

# 不准做的事
- 不要連網查資料，除非我明確說可以
- 不要動 `.env` 或 `.gitignore`
- 不要刪資料夾，包括子資料夾

E — 第一個 Skill 範例（約 5 分鐘；Stage 5.3 會用到） ​

Skill 是 Claude Code 的「可重用 prompt 包」。當你的訊息符合描述，Claude Code 會自動載入那份指示。

建立 .claude/skills/hello-skill/SKILL.md：

markdown
---
name: hello-skill
description: 第一個 hello skill。當使用者說「請打招呼」或「say hi」時觸發。
---

當使用者請你打招呼時，回三件事：

1. 用繁體中文跟英文各說一次 hello
2. 提現在的日期（用 system 時間）
3. 給一個今日小提醒（隨機選健康 / 學習 / 心情建議）

跑 claude，輸入「請打招呼」。如果 Claude 回覆三件事，就代表 Skill 被載入了。

想看更完整的 Skill 設計：看 Stage 5.3 — Skills。 想看可以照做的範例：看 Cookbook。

接下來去哪 ​

你現在的狀態下一步
想正式理解 LLM、API、tokenStage 1 — LLM 基礎
想直接挑身分分支日常使用者 / 教師 / 知識工作者 / 研究者 / 開發者
想看 Claude Code 完整生態Stage 5 — Claude Code 生態系
想本機 LLM、不用雲端 keyCookbook Recipe 6
想比較 CLI agentCLI Agents 比較指南
不懂某個用詞Glossary