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（基础），Plus $20/月
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.zh-Hans.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.zh-Hans.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 / 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 下载安装包。
  • 验证：输入 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