EP01 · 环境搭建：30 分钟配好你的 AI 工作站

一个人、一台电脑、30 分钟，把 Claude Code 从聊天框变成有记忆、会并行、能接外部工具的工作站。
这是《AI 全栈开发环境搭建》系列第 1 篇，贯穿案例：订阅管家。

📋 开始前，先确认这 3 件事

检查项	命令	要求
Node.js 版本	node --version	≥ 18
npm 版本	npm --version	≥ 9
Claude Code 账号	官网登录	已付费或试用额度

⚠️ 还没订阅？ 本文基于 Claude Code 官方 CLI。如果你暂时没有付费账号，可以：

• 使用试用额度先跑通流程
• 或关注本系列 EP10「免费平替方案」

但本文的配置哲学（六件套）对所有 AI 编程工具通用。

先看结果

配完之后，你的项目根目录长这样：

.claude/
├── settings.json          # 模型路由 + 权限 + hooks
├── settings.local.json    # 本地权限缓存（自动生成）
├── agents/
│   └── researcher.md      # 一个子代理
├── hooks/
│   ├── format-on-save.sh  # 保存即格式化
│   └── guard-push.sh      # 拦截强推 main
└── skills/                # 8 个阶段 skill（EP02 详讲）
.mcp.json                  # 连上 filesystem MCP
CLAUDE.md                  # 项目记忆

6 个配置文件，拼成 1 个工作站：

CLAUDE.md      ── 项目记忆
settings.json  ── 路由 / 权限 / hooks
agents/        ── 派分身
hooks/         ── 事件自动化
skills/        ── 8 阶段能力（EP02 详讲）
.mcp.json      ── 接外部工具
            │
            ▼
      AI 工作站就绪

claude 跑起来，状态栏显示当前分支。AI 能读你硬盘里的订阅清单，能拦下你手滑的 git push --force origin main。

这不是魔法。是 6 个配置文件。

配完即用。下一篇开始往里塞「肌肉记忆」。

一、AI 工作站是什么

一句话：让 Claude Code 从「超级补全」变成「一个人一支团队」。

靠六件套：

能力	一句话	干嘛用
模型路由	Opus/Sonnet/Haiku 按活儿切	硬推理用贵的，机械活用便宜的
权限模式	deny/ask/allow 三档	画死自动执行的边界
Plan mode	先想再动手	架构探索不瞎写
Hooks	事件自动化	保存即格式化、推送前拦截
Subagent	并行分身	多模块同时干
MCP	接外部工具	让 AI 读硬盘、查网络

工具不是瓶颈，工作流才是。

Claude Code 单独用是超级补全。配上这六件套，才是一个人一支团队。

二、怎么搭（配时间预算）

⏱️ 总预算 30 分钟，按这个节奏走：

步骤	内容	预估
第 1 步	装 Claude Code + 登录	5 min
第 2 步	模型路由	3 min
第 3 步	权限三档	5 min
第 4 步	Plan mode（理解即可）	2 min
第 5 步	写两个 hooks	10 min
第 6 步	配一个子代理	2 min
第 7 步	连 MCP	3 min

第 1 步：装 Claude Code（5 min）

一行命令：

# 需要 Node 18+
npm install -g @anthropic-ai/claude-code

# 验证
claude --version

首次运行 claude 会让你登录。登完就能聊。

npm install -g @anthropic-ai/claude-code
               │
               ▼
        首次运行 claude
               │
               ▼
        浏览器登录授权
               │
               ▼
     ✅ 工作站就绪，可对话

🐛 排查：如果 claude: command not found，检查 npm 全局 bin 是否在 PATH 里：

npm root -g  # 找到路径，加到 ~/.zshrc 或 ~/.bashrc

第 2 步：模型路由——别全程顶配（3 min）

新手最容易犯的错：全程开最贵的模型。

• 架构设计、硬推理 → Opus（贵但强）
• 日常 coding → Sonnet（默认，够用）
• 机械活（改名、批量替换） → Haiku（又快又便宜）

三层路由，写在 .claude/settings.json：

{
  "model": "claude-sonnet-5",
  "env": {
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-8",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001"
  }
}

model 是默认值（日常走 Sonnet）。env 里三个变量定义了 Opus/Sonnet/Haiku 各自指向哪个模型。子代理还能在自己的 frontmatter 里再覆盖一层。

来了个任务，按活儿切档：

▸ 硬推理 / 架构设计
      -> Opus（贵但强）

▸ 日常 coding
      -> Sonnet（默认，够用）

▸ 机械活 / 改名批量
      -> Haiku（又快又便宜）

不是全程顶配，是按活儿切档。

第 3 步：权限——画死边界（5 min）

一上来就全自动放权，是最危险的。

我把权限分了三档：

档位	触发	例子
deny	直接拒绝	rm -rf、curl | sh、sudo、读 .env
ask	要你确认	git push、npm publish、prisma migrate
allow	自动放行	读文件、npm run test、git status

"permissions": {
  "deny": ["Bash(rm -rf:*)", "Bash(curl:*| sh)", "Read(./**/.env)"],
  "ask": ["Bash(git push:*)", "Bash(npm publish:*)", "Bash(npx prisma migrate:*)"],
  "allow": ["Read(./**)", "Bash(npm run test)", "Bash(git status)"]
}

权限不是束缚，是放权的边界。 边界画死了，自动执行才敢放开。

第 4 步：Plan mode——先想再动手（2 min）

在 Claude Code 里按 Shift+Tab 切换模式，其中有个 Plan mode。

进了 Plan mode，AI 只调研、只读代码、只出方案——不写文件、不改代码、不跑命令。

什么时候用？ 不确定怎么动手的时候。

比如「这个功能该怎么拆」——先进 Plan mode 让它把目录读一遍、把现有结构摸清楚、给你一个分步方案。你看着方案点头，它才退出 Plan mode 开干。

这就把「想」和「做」分开了。想的时候不产生副作用，做的时候已经有蓝图。

快速操作：对话框中直接输入 /plan 可快速切换，不用按 Shift+Tab。

EP05 架构设计会把这个能力用到极致。这里先记住有它。

先想清楚再动手，比动手快更重要。

第 5 步：Hooks——让事件自己跑（10 min）

Hooks 是事件钩子。文件一存就格式化，推送前先检查——不用你记。

写两个。

① 保存即格式化（PostToolUse，编辑/写入后触发）

#!/usr/bin/env bash
# .claude/hooks/format-on-save.sh
input=$(cat)
file_path=$(printf '%s' "$input" | python3 -c \
  "import sys,json;print(json.load(sys.stdin).get('tool_input',{}).get('file_path',''))")
[ -z "$file_path" ] && exit 0
case "$file_path" in
  *.ts|*.js) [ -x node_modules/.bin/prettier ] && ./node_modules/.bin/prettier --write "$file_path" ;;
esac
exit 0

📌 依赖 python3，macOS/Linux 默认都有。如果精简容器里没有，apt install python3 或 brew install python3 即可。

② 拦截强推（PreToolUse，bash 执行前触发）

#!/usr/bin/env bash
# .claude/hooks/guard-push.sh
cmd=$(cat | python3 -c "import sys,json;print(json.load(sys.stdin).get('tool_input',{}).get('command',''))")
case "$cmd" in
  *"git push"*)
    echo "$cmd" | grep -qE -- '--force|-f' && \
    echo "$cmd" | grep -qE 'main|master' && \
    { echo "⛔ 禁止强推 main/master" >&2; exit 2; }
    ;;
esac
exit 0

exit 2 会把 stderr 反馈给 AI，操作被拦下。

你触发一个动作
      │
      ├── 执行前 -> PreToolUse -> guard-push.sh
      │     ├─ 命中 --force + main -> exit 2 ⛔ 拦截
      │     └─ 正常推送            -> exit 0 ✅ 放行
      │
      └── 编辑/写入后 -> PostToolUse -> format-on-save.sh
            ├─ 有 prettier -> 格式化
            └─ 无 prettier -> exit 0 静默跳过

注册 hooks（在 settings.json 里）

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "bash .claude/hooks/guard-push.sh" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "bash .claude/hooks/format-on-save.sh" }]
      }
    ]
  }
}

⚠️ 真实踩坑：测试 hook 时被自己拦了

我写完 guard-push 测试它，第一条测试命令就被拦了——因为我 echo 的字符串里就有 git push --force origin main。hook 是子串匹配，连提一嘴都被拦。

证明它真在工作。但也暴露：子串匹配会误伤。解决办法——触发字符串用 payload 文件承载，别写进 bash 命令本身。

hook 要 fail-open，不能 fail-closed。

格式化器没装就静默跳过（exit 0），文件不存在也 exit 0。绝不能因为 hook 自己出错把主流程卡死。

事件自动化要 silent-pass。

第 6 步：Subagent——派个分身（2 min）

子代理是能并行干活的分身。EP03 产品分析会大用，这里先来个最小的。

.claude/agents/researcher.md：

---
name: researcher
description: 深度调研子代理，并行收集情报返回结构化简报
tools: Read, Grep, Glob, WebSearch
model: sonnet
---
你是调研专员。并行优先，每个事实标来源，
不确定写「未查到」，绝不编造。

• tools：限定它能用什么工具
• model：单独覆盖路由（这里用 Sonnet，不烧 Opus）

主控调用时，它带着自己的上下文独立干活，干完把结果交回来。

一个分身 = 一份并行算力。

第 7 步：消费 MCP（对称时刻①）（3 min）

这是全系列最妙的两个对称时刻之一：

时刻	角色	说明
EP01（现在）	你消费 MCP	连外部工具给 AI 用
EP09（终章）	你生产 MCP	你的产品暴露工具给别的 AI 用

现在做前者。.mcp.json 连一个 filesystem server：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/data/ai_workflow/project/subscription-manager"
      ]
    }
  }
}

⚠️ 注意最后一个参数：只授权一个目录。 不暴露整个磁盘，只让 AI 碰订阅管家这一个项目。最小权限。

.mcp.json 声明 filesystem server
               │
               ▼
     claude 启动时拉起 server
               │
               ▼
仅授权 subscription-manager 一个目录
（最小权限，不暴露整个磁盘）
               │
               ▼
   AI 发现 read_file 能力
               │
               ▼
读 subscriptions-sample.txt  ->  ✅ 消费 MCP 成功

✅ 验证 MCP 是否连通

启动 claude 后，输入：

/mcp

看到 filesystem: connected ✅ 就是成了。如果显示 ❌：

现象	可能原因	解决
filesystem: ❌	路径不存在	检查 .mcp.json 里的目录是否存在
npx: command not found	Node 未安装	node --version 确认 ≥ 18
卡住不动	首次下载 MCP server 慢	稍等，或提前 npx -y @modelcontextprotocol/server-filesystem 预下载

三、实战：连上 MCP 读订阅清单

配完工作站，跑一遍。

订阅管家项目里我放了份示例清单：

Netflix,68,CNY,月,2026-08-01,影音,家庭共享
Spotify,28,USD,月,2026-07-25,影音,个人
ChatGPT Plus,20,USD,月,2026-08-10,工具,AI 写作
Claude Pro,20,USD,月,2026-08-12,工具,AI 编程主力

连上 filesystem MCP 后，直接跟 Claude Code 说：

帮我读一下订阅清单，按币种分组算每个月花多少。

AI 调 filesystem 的 read_file 工具，读清单，分组求和，返回结果。

全程没让你打开文件、没让你写脚本。

这就是消费 MCP 的样子——AI 自己发现能力、自己调用。

步骤	谁干的	工具
读清单	AI	filesystem MCP
分组求和	AI	内置推理能力
确认结果对不对	你	肉眼

人机边界很清楚：AI 干机械活，你拍板。

顺手验证一下 hooks

配完我跑了端到端测试：

测试	结果
强推 main	⛔ 拦截（exit 2 + stderr 反馈）
正常推 dev	✅ 放行（exit 0）
格式化不存在的文件	✅ 静默跳过
项目没装 prettier	✅ 静默跳过

事件自动化不是理论，是能跑、能拦、能反馈的工程。

四、拿走即用

最小 settings.json 模板（复制即用）

{
  "model": "claude-sonnet-5",
  "env": {
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-8",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001"
  },
  "permissions": {
    "deny": ["Bash(rm -rf:*)", "Read(./**/.env)"],
    "ask": ["Bash(git push:*)", "Bash(npm publish:*)"],
    "allow": ["Read(./**)", "Bash(npm run test)"]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "bash .claude/hooks/guard-push.sh" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "bash .claude/hooks/format-on-save.sh" }]
      }
    ]
  }
}

一键起骨架

mkdir -p .claude/{agents,hooks}
touch CLAUDE.md .mcp.json .claude/settings.json
chmod +x .claude/hooks/*.sh

你配完能得到什么

能力	配置	效果
按活儿切模型	env + model	不全程烧钱
自动放行安全操作	allow	不用每步确认
保存即格式化	PostToolUse hook	代码永远整齐
拦危险操作	PreToolUse hook	手滑也不怕
派分身	agents/*.md	并行干活
读外部数据	.mcp.json	AI 能碰你的文件

附录：启动故障排查 5 连

现象	可能原因	解决
command not found: claude	Node 版本过低或未全局安装	node -v 检查 ≥ 18，重装 npm install -g @anthropic-ai/claude-code
登录后仍提示 unauthorized	浏览器登录的账号与 CLI 不匹配	执行 claude auth login 重新授权
MCP 显示 ❌	路径不存在或 npx 下载失败	检查 .mcp.json 路径，确保网络通畅，手动 npx -y @modelcontextprotocol/server-filesystem 预下载
Hook 不触发	文件无执行权限	chmod +x .claude/hooks/*.sh
保存后未格式化	项目未装 prettier	npm install -D prettier，或在非 Node 项目里换用其他格式化工具

写在最后

工厂地基打好了。

这一篇没碰一行订阅管家的业务代码——故意留到后面。先把工具配齐，再谈工作流。

Claude Code 单独用是超级补全，配上六件套才是一个人一支团队。

下一篇 EP02，往这台工作站里塞「肌肉记忆」——Skill 体系。让 AI 拥有可复用的、跨会话记得住的能力。

到那时，你敲一句「分析一下订阅管家的竞品」，它就知道该调哪个 skill、派几个分身、产出什么。

先别急着写代码。先把工厂搭起来。

📌 系列导航

• EP01 · 环境搭建（本文）
• EP02 · Skill 体系：给 AI 装上肌肉记忆（预告）
• EP03 · Subagent 并行：产品分析实战（预告）
• …
• EP09 · 生产 MCP：把你的产品变成工具（预告）