<!-- title: 零基础装通造首个命令行番茄钟 -->

# 零基础装通配好，并用 Claude Code 造出你的第一个命令行番茄钟

## 概述

本教程面向**完全零基础**的读者：你可能从没装过命令行 AI 编程工具，也分不清 `npm` 和原生安装脚本的区别。读完后，你将掌握 Claude Code 在 macOS、Linux、Windows 三大平台上的安装与认证方式，理解模型选择、权限模式、`CLAUDE.md` 记忆文件等核心配置，并亲手用它造出一个**无第三方依赖、可直接运行、带任务记录的命令行番茄钟**。整个项目只用 Python 标准库，不需要 `pip install` 任何东西，是体验「自然语言驱动开发」闭环的理想第一个项目。

**适用人群**：从未用过 Claude Code 的新手、想从图形界面迁移到终端的开发者、希望用 AI 提升日常效率的办公族。

## 前置条件

在开始之前，你需要准备：

- **一个终端**：macOS 用自带的「终端」App；Windows 用 PowerShell 或 Windows Terminal；Linux 用任意 Shell。
- **一个 Anthropic 账号**：最省心的方式是订阅 [Claude Pro / Max / Team / Enterprise](https://claude.com/pricing)（用 OAuth 登录，按订阅计费，不消耗 API 额度）。如果你只想用按量计费的 API，可以去 [console.anthropic.com](https://console.anthropic.com/) 申请一个 API Key。
- **Python 3.8+**：本教程的实战项目用 Python 写。macOS/Linux 通常自带；Windows 去 python.org 安装时记得勾选 "Add to PATH"。
- **系统要求**（来自官方 Setup 文档）：macOS 13.0+、Windows 10 1809+、Ubuntu 20.04+、Debian 10+、Alpine 3.19+，内存 4GB 以上。
- **联网环境**：安装与对话都需要访问 Anthropic 服务。

## 步骤一：安装 Claude Code

Claude Code 的官方安装方式在 2026 年已经发生重要变化——**通过 npm 安装被官方标记为 deprecated（已弃用）**，推荐改用原生安装脚本。下面按平台给出推荐命令。

### macOS / Linux（推荐）

打开终端，执行一行命令即可：

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

如果你更习惯用包管理器，Homebrew 也已收录：

```bash
brew install --cask claude-code
```

### Windows（推荐）

在 PowerShell 中执行：

```powershell
irm https://claude.ai/install.ps1 | iex
```

或者用 WinGet：

```powershell
winget install Anthropic.ClaudeCode
```

### 为什么不用 npm 了？

```bash
npm install -g @anthropic-ai/claude-code   # 已弃用，但仍可用
```

旧方式要求先装 Node.js 18+，版本管理与全局权限经常给新手制造麻烦（`EACCES` 权限错误、Node 版本错位等）。原生安装脚本把可执行文件直接放进系统路径，绕开了整个 Node 生态，安装即用、升级一条命令。

**预期结果**：安装完成后，在终端输入 `claude --version`，能看到版本号输出，例如 `2.x.x`，说明 `claude` 命令已进入 PATH。

**常见问题与解决**：

| 问题 | 原因 | 解决 |
|---|---|---|
| `command not found: claude` | PATH 未刷新 | 关闭重开终端；或手动 `source ~/.zshrc` / `source ~/.bashrc` |
| macOS 提示「无法验证开发者」 | Gatekeeper 拦截 | 系统设置 → 隐私与安全性 → 仍要打开 |
| `curl: (7) Failed to connect` | 网络受限 | 配置代理或使用国内中转 |
| Windows 执行策略报错 | PowerShell 策略 | 管理员运行 `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` |

## 步骤二：首次认证登录

第一次在项目目录运行 `claude`，它会引导你完成认证。两种方式：

### 方式 A：OAuth 登录（订阅用户，推荐）

直接输入：

```bash
claude
```

程序会打开浏览器跳转到 claude.com，确认授权后回到终端，看到欢迎界面即登录成功。这种方式不需要手动管理 Key，额度走你的 Pro/Max 订阅。

### 方式 B：API Key（按量计费）

如果你用 API，先在 [console.anthropic.com](https://console.anthropic.com/) 创建 Key，然后设置环境变量：

```bash
# macOS / Linux（写进 ~/.zshrc 或 ~/.bashrc 持久化）
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# Windows PowerShell
$env:ANTHROPIC_API_KEY="sk-ant-xxxxx"
```

随后运行 `claude` 即可。会话内也可用斜杠命令管理登录态：`/login` 重新登录、`/logout` 登出、`/status` 查看当前账号与额度。

**预期结果**：终端出现 `>` 提示符，说明进入交互式会话，可以开始用自然语言对话了。

## 步骤三：核心配置——模型、权限与记忆

进入会话后，有几个配置项决定了 Claude Code 的行为，新手最该先搞清楚。

### 1. 选择模型

不同模型在速度、能力、成本上各有侧重。用 `/model` 命令切换：

```
/model
```

弹出列表后用方向键选择。日常写代码、做小项目，默认的平衡模型通常已足够；遇到复杂重构或架构决策，可临时切到更强模型。**新手建议**：先用默认，等遇到「想得不够深」时再升级。

### 2. 理解四种权限模式

Claude Code 在执行文件读写、运行命令时，会根据权限模式决定是否每次征求你同意。这关系到安全与效率的平衡：

- **default（默认）**：每个有副作用的操作（写文件、跑命令）都先问你。最安全，适合陌生项目。
- **acceptEdits**：自动接受文件编辑，但运行命令仍需确认。适合「让它放手改代码」。
- **plan（计划模式）**：只读、只规划，不执行任何改动。适合让它先调研给方案。
- **bypassPermissions**：跳过所有确认，全自动。**风险最高**，仅在可信沙箱里用。

会话中按 `Shift+Tab` 可在 default / acceptEdits / plan 之间循环切换；或在启动时用 `--permission-mode` 指定。新手第一课：**先用 default 跑通，再渐进放权**，不要一上来就 `--dangerously-skip-permissions`。

### 3. `/init` 生成记忆文件

在项目根目录运行：

```
/init
```

它会扫描代码库并生成一个 `CLAUDE.md` 文件，记录项目结构、构建命令、代码风格约定等。之后每次会话，Claude Code 都会自动读取这个文件作为长期上下文——相当于给 AI 一份「项目说明书」，避免它每次都从零猜。

**预期结果**：项目根目录出现 `CLAUDE.md`，内容含「项目概述 / 常用命令 / 架构说明」等段落。

## 步骤四：创建第一个项目目录

实战项目需要一个工作目录。在终端执行：

```bash
mkdir ~/pomo-cli && cd ~/pomo-cli
claude
```

进入会话后，第一步先让它初始化记忆：

```
/init
```

因为目录是空的，它会生成一个最小骨架的 `CLAUDE.md`。你可以手动补一句说明，告诉它这是个 Python 项目、用标准库、目标平台是终端。

> 小技巧：让 AI 持续「懂你」的，是 `CLAUDE.md` 这份记忆文件——把它当成你和 AI 之间的长期契约。

## 步骤五：用自然语言造出番茄钟

现在进入正题。在会话里输入下面这段提示词（**完整复制**即可）：

```
请在当前目录创建一个命令行番茄钟 CLI，文件名 pomo.py，要求：
1. 纯 Python 标准库，不依赖任何第三方包；
2. 子命令 start：默认 25 分钟专注倒计时，支持 -t/--task 指定任务名，
   -b/--break 进入 5 分钟休息、-l/--long 进入 15 分钟长休息，
   -m/--minutes 覆盖默认专注时长；
3. 倒计时要原地刷新（用 \r 回到行首覆盖），用 ANSI 颜色区分专注(绿)/休息(青)；
4. 每完成一个专注番茄钟，把任务名、时长、完成时间追加记录到 ~/.pomo/records.json；
5. 子命令 stats：统计今日完成的番茄钟数量与累计专注分钟；
6. 子命令 config：可查看、可用 --focus/--break/--long 修改默认时长，存到 ~/.pomo/config.json；
7. Ctrl+C 提前结束时不计完成；
8. 写完后帮我跑一遍 python pomo.py --help 和 python pomo.py stats 验证。
```

**预期结果**：Claude Code 会依次创建 `pomo.py`，并自动运行你要求的验证命令。如果切到 acceptEdits 模式，它会一气呵成地写完文件；在 default 模式下，你会在它写文件、跑命令前各确认一次（按回车放行）。

你会看到类似输出：

```
✻ Created pomo.py
  ⏺ Bash(python pomo.py --help)
    usage: pomo [-h] {start,stats,config} ...
```

**常见问题与解决**：

- **它写了带 `colorama`/`rich` 依赖的版本**：说明你没强调「纯标准库」。在提示词里加一句「禁止 import 任何非标准库」，或直接说「用 ANSI 转义码实现颜色」。
- **倒计时一闪而过**：检查是否用了 `print` 而非 `sys.stdout.write("\r...")`。让 AI 改成行首覆盖刷新。
- **`records.json` 路径错**：用 `Path.home() / ".pomo"` 而非硬编码字符串，跨平台才安全。

## 步骤六：运行、调试与迭代

退出会话（输入 `/exit` 或按两次 `Ctrl+C`），在终端直接运行你的成品：

```bash
# 看帮助
python pomo.py --help

# 来一个 1 分钟的快速测试（覆盖时长，别真等 25 分钟）
python pomo.py start -t "写本教程" -m 1

# 休息一下
python pomo.py start -b -m 1

# 看统计
python pomo.py stats

# 调整默认专注时长为 30 分钟
python pomo.py config --focus 30
```

**预期结果**：专注时屏幕中央会出现绿色原地刷新的 `🎯 专注中 00:25`，倒计时归零后响一声终端铃声（`\a`），并打印「✓ 完成一个番茄钟，已记录」；`stats` 显示今日完成数与累计分钟。

如果想加功能，**回到会话继续对话**即可，例如：

```
给 pomo.py 加一个 today 子命令，列出今天每个番茄钟的任务名和完成时刻，按时间正序。
```

这就是 Claude Code 的核心闭环：**对话 → 改代码 → 自动验证 → 再对话**。你不需要离开终端去翻文档。

## 步骤七：把番茄钟变成全局命令

每次 `python ~/pomo-cli/pomo.py` 太长。让它变成全局的 `pomo` 命令：

```bash
# macOS / Linux
chmod +x ~/pomo-cli/pomo.py
sudo ln -s ~/pomo-cli/pomo.py /usr/local/bin/pomo
# 或者轻量做法：加一个 alias 到 ~/.zshrc
alias pomo="python ~/pomo-cli/pomo.py"
```

之后任意目录输入 `pomo start -t "学英语"` 即可。

## 实战案例：完整番茄钟代码

下面是 Claude Code 按上述提示词生成的、经过验证可运行的完整 `pomo.py`（已做精简与注释）。**你完全可以把它作为对照基准**，检查 AI 给你的版本是否覆盖了全部需求：

```python
#!/usr/bin/env python3
"""pomo - a tiny pomodoro CLI built with Claude Code (stdlib only)."""
import argparse
import json
import sys
import time
from datetime import date, datetime
from pathlib import Path

# ANSI colors - no external deps
GREEN, YELLOW, CYAN, BOLD, RESET = "\033[92m", "\033[93m", "\033[96m", "\033[1m", "\033[0m"

DATA_DIR = Path.home() / ".pomo"
DATA_FILE = DATA_DIR / "records.json"
CONFIG_FILE = DATA_DIR / "config.json"
DEFAULTS = {"focus_minutes": 25, "break_minutes": 5, "long_break_minutes": 15}


def load_json(path, default):
    if not path.exists():
        return default
    try:
        return json.loads(path.read_text(encoding="utf-8"))
    except (json.JSONDecodeError, OSError):
        return default


def save_json(path, data):
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")


def fmt(sec):
    m, s = divmod(int(sec), 60)
    return f"{m:02d}:{s:02d}"


def countdown(minutes, label, color):
    """Overwrite a single line in place each second. Return False if interrupted."""
    try:
        for left in range(minutes * 60, 0, -1):
            sys.stdout.write(f"\r{color}{BOLD}{label}{RESET} {color}{fmt(left)}{RESET}  ")
            sys.stdout.flush()
            time.sleep(1)
    except KeyboardInterrupt:
        print()
        return False
    print()
    return True


def cmd_start(args, config):
    if args.break_:
        minutes = config["long_break_minutes"] if args.long else config["break_minutes"]
        label, color, is_focus = "🧘 休息", CYAN, False
    else:
        minutes = args.minutes or config["focus_minutes"]
        label, color, is_focus = "🎯 专注", GREEN, True

    print(f"{BOLD}开始 {minutes} 分钟 {label}{RESET}")
    done = countdown(minutes, label, color)
    sys.stdout.write("\a"); sys.stdout.flush()  # terminal bell

    if not done:
        print(f"{YELLOW}⏸ 提前结束，未计入。{RESET}")
        return
    if not is_focus:
        print(f"{CYAN}✓ 休息结束，回来继续。{RESET}")
        return

    records = load_json(DATA_FILE, {"sessions": []})
    records["sessions"].append({
        "task": args.task or "未命名任务",
        "minutes": minutes,
        "ts": datetime.now().isoformat(timespec="seconds"),
    })
    save_json(DATA_FILE, records)
    print(f"{GREEN}✓ 完成一个番茄钟，已记录。{RESET}")


def cmd_stats(args, config):
    today = date.today().isoformat()
    sessions = [s for s in load_json(DATA_FILE, {"sessions": []})["sessions"]
                if s["ts"].startswith(today)]
    total = sum(s["minutes"] for s in sessions)
    print(f"{BOLD}📊 今日统计{RESET}")
    print(f"  完成: {CYAN}{len(sessions)}{RESET} 个   专注: {CYAN}{total}{RESET} 分钟")
    if sessions:
        print(f"  最近: {sessions[-1]['task']}")
    elif not sessions:
        print(f"{YELLOW}  还没记录，先 start 一个。{RESET}")


def cmd_config(args, config):
    for key, val in [("focus_minutes", args.focus), ("break_minutes", args.break_), ("long_break_minutes", args.long)]:
        if val:
            config[key] = val
    save_json(CONFIG_FILE, config)
    print(f"focus={config['focus_minutes']}  break={config['break_minutes']}  long={config['long_break_minutes']}")
    print(f"file: {CONFIG_FILE}")


def main():
    config = {**DEFAULTS, **load_json(CONFIG_FILE, {})}
    p = argparse.ArgumentParser(prog="pomo", description="迷你番茄钟 CLI")
    sub = p.add_subparsers(dest="command", required=True)

    s = sub.add_parser("start", help="专注或休息")
    s.add_argument("-t", "--task")
    s.add_argument("-m", "--minutes", type=int)
    s.add_argument("-b", "--break", dest="break_", action="store_true")
    s.add_argument("-l", "--long", action="store_true")
    s.set_defaults(func=cmd_start)

    st = sub.add_parser("stats", help="今日统计")
    st.set_defaults(func=cmd_stats)

    c = sub.add_parser("config", help="查看/修改配置")
    c.add_argument("--focus", type=int)
    c.add_argument("--break", dest="break_", type=int)
    c.add_argument("--long", type=int)
    c.set_defaults(func=cmd_config)

    args = p.parse_args()
    args.func(args, config)


if __name__ == "__main__":
    main()
```

跑通后，`~/.pomo/records.json` 会积累出这样的记录，正是 `stats` 与未来「每日趋势图」的数据源：

```json
{
  "sessions": [
    {"task": "写本教程", "minutes": 1, "ts": "2026-07-05T14:02:11"},
    {"task": "学英语", "minutes": 25, "ts": "2026-07-05T16:30:00"}
  ]
}
```

## 工作流程图

下面这张图展示了从安装到产出番茄钟的完整闭环，新手可以照着走：

```mermaid
flowchart TD
    A[步骤一 原生安装<br/>curl/irm 一行命令] --> B[步骤二 认证登录<br/>OAuth 或 API Key]
    B --> C{进入会话<br/>claude}
    C --> D[/init 生成 CLAUDE.md 记忆/]
    D --> E[步骤五 自然语言提需求<br/>造番茄钟]
    E --> F[AI 写代码 + 自动验证]
    F --> G{运行达标?}
    G -- 否 --> E
    G -- 是 --> H[步骤六 命令行实测]
    H --> I[步骤七 做成全局 pomo 命令]
    I --> J[日常对话式迭代加功能]

    style A fill:#e8f5e9
    style F fill:#fff3e0
    style J fill:#e3f2fd
```

## 进阶：让番茄钟自己长出功能

一旦跑通，你可以用对话不断「喂养」出新能力，每条都是一次 5 分钟的练习：

- `给 stats 加一个本周累计柱状图（用 ANSI 块字符画）`
- `专注开始前如果检测到正在运行的 git 进程，自动把当前分支名作为默认 task`
- `加一个 report 子命令，把 records.json 导出成 Markdown 表格`
- `接入系统通知：macOS 用 osascript、Linux 用 notify-send、Windows 用 msg`

这正是 Claude Code 区别于普通补全工具的价值——你描述意图，它负责实现与验证，你专注于「要什么」而非「怎么敲」。

## 延伸阅读

- **官方快速开始**：[code.claude.com/docs/zh-CN/quickstart](https://code.claude.com/docs/zh-CN/quickstart) —— 几分钟跑通第一次会话的官方指引。
- **官方安装与设置**：[code.claude.com/docs/zh-CN/setup](https://code.claude.com/docs/zh-CN/setup) —— 系统要求、各平台安装、更新与卸载。
- **GitHub 仓库 README**：[github.com/anthropics/claude-code](https://github.com/anthropics/claude-code) —— 含最新安装命令（npm 已弃用说明）与插件目录。
- **斜杠命令速查**：会话内输入 `/help` 查看全部内置命令，是最高效的「说明书」。
- **终端入门**：[code.claude.com/docs/zh-CN/terminal-guide](https://code.claude.com/docs/zh-CN/terminal-guide) —— 没用过命令行的读者先读这篇。

## 参考来源

1. [Claude Code 官方快速开始文档](https://code.claude.com/docs/zh-CN/quickstart) — Anthropic 官方入门指引，覆盖首次会话与常见任务。
2. [Claude Code 高级设置文档](https://code.claude.com/docs/zh-CN/setup) — 系统要求、跨平台安装、版本管理与卸载的权威来源。
3. [anthropics/claude-code GitHub README](https://github.com/anthropics/claude-code) — 2026 最新安装命令（含 npm 已弃用、原生脚本与 WinGet/Homebrew 方式）。
4. [Claude Code 超详细完整指南（2026 版）](https://blog.csdn.net/liulin_521/article/details/155862222) — 中文社区高赞手把手教程，补充认证与权限实操细节。
5. [Claude Code 从入门到精通（博客园）](https://www.cnblogs.com/wzzkaifa/p/19079594) — 命令体系与高级技巧的中文系统梳理。

## 训练营适用性评估

- **AI 编程入门训练营（零基础）**：⭐⭐⭐⭐⭐ 高度适配。安装→配置→第一个项目三段式天然契合 1 个半天（约 3 小时）的教学单元，番茄钟项目体量适中、结果可视化、人人能用。
- **企业效率提升训练营**：⭐⭐⭐⭐ 适配。番茄钟本身即是生产力工具，可顺带教学员把日常重复流程交给 Claude Code。
- **Python 进阶训练营**：⭐⭐⭐ 部分适配。可作为「标准库 CLI + JSON 持久化 + ANSI 终端控制」的练手题，但代码深度偏入门。
- **预计教学时长**：讲授 + 跟做约 **2.5～3 小时**；含自由扩展（加通知、加图表）的完整工作坊约 **半天（4 小时）**。建议每位学员准备一台联网电脑，自带或现场申请 Anthropic 账号，课前务必验证 `curl`/`irm` 安装命令在本地网络可达。

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)