首页 › tutorials › 零基础装通造首个命令行番茄钟

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

概述

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

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

前置条件

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

步骤一：安装 Claude Code

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

macOS / Linux（推荐）

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

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

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

brew install --cask claude-code

Windows（推荐）

在 PowerShell 中执行：

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

或者用 WinGet：

winget install Anthropic.ClaudeCode

为什么不用 npm 了？

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 登录（订阅用户，推荐）

直接输入：

claude

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

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

如果你用 API，先在 console.anthropic.com 创建 Key，然后设置环境变量：

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

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

3. /init 生成记忆文件

在项目根目录运行：

/init

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

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

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

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

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} ...

常见问题与解决：

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

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

# 看帮助
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 命令：

# 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 给你的版本是否覆盖了全部需求：

#!/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 与未来「每日趋势图」的数据源：

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

工作流程图

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

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 分钟的练习：

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

延伸阅读

参考来源

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

训练营适用性评估

[!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学通信知识星球海报-扫码加入

📎 本分类最新文章