Windows AI 编程环境从零搭建指南[20260909]

Windows AI 编程环境从零搭建指南

一份文档讲完：装什么、为什么装、装几个、怎么用、出问题怎么救。 约定：软件安装包只给链接，双击 .exe/.msi 一路 Next 即可；本文只给命令与验证方式。

---

开始前：确认你的电脑够格

操作系统与架构

项目	要求	怎么查
操作系统	Windows 11（推荐）或 Windows 10 1809 及以上	Win+R → 输入 winver → 回车
架构	64 位（x64），少数新机为 ARM64	设置 → 系统 → 关于 → 看"系统类型"
包管理器	winget（Windows 11 及较新 Win10 自带）	终端输入 winget --version

⚠️ 必须是 64 位。 本指南的 Node.js 24、VS Code、PowerShell 7 均按 x64 给出下载项；32 位系统装不了 Node 24 ，请另寻 x86 旧版本说明。 不便打开设置的话，终端执行 echo %PROCESSOR_ARCHITECTURE%，返回 AMD64 即为 x64。

硬件建议

组件	最低	推荐	说明
内存	8 GB	16 GB 及以上	Agent 是常驻进程，还要缓存大量上下文；8G 能跑，复杂任务易卡
磁盘	10 GB 可用	20 GB 以上 SSD	工具链约 2--3 GB，项目和依赖另算
CPU	双核	四核及以上	不跑本地大模型，只影响构建与测试速度
网络	能访问 npm 源与 api.deepseek.com	---	国内建议配 npm 镜像加速

一个常见误解 ：这套方案不需要显卡，也不需要高性能 CPU。模型推理发生在 DeepSeek 云端，你的电脑只负责跑命令、存文件、显示结果。老笔记本一样能用。

关于"用哪个终端"

好消息：本指南 90% 的命令在 CMD 和 PowerShell 里都能跑，两者任选。

终端	打开方式	适合
CMD（命令提示符）	Win+R → cmd → 回车	命令短、启动快；本指南多数命令的首选
PowerShell 5.1	Win+R → powershell → 回车	Windows 自带，少数命令必须用它（见下）
PowerShell 7（pwsh）	Win+R → pwsh → 回车	推荐安装，见 Part 1.1，Codex 用户尤其建议
Windows Terminal	Microsoft Store 安装	多标签统一管理上述终端，体验最好

全文标记约定：

• 代码块标 bat = CMD 与 PowerShell 通用，两种终端随便挑
• 代码块标 powershell = ⚠️ 仅 PowerShell，会单独说明原因

真正需要 PowerShell 的只有 4 处，全文用 ⚠️ 标出：

1. DeepSeek Codex 一键配置脚本（用到 irm ... | iex）
2. 临时设置环境变量（CMD 用 set，PowerShell 用 $env:）
3. 激活 Python 虚拟环境的 .ps1 脚本（CMD 改用 .bat）
4. 修改脚本执行策略 Set-ExecutionPolicy

其余如 npm install、git commit、codex、claude、dsh web、code . 都是普通可执行程序，CMD 完全够用。

---

怎么用这份文档

如果你的状态	建议读法
完全新手，从零开始	按 Part 0 → 6 顺序读，全程约 50 分钟
已装好 Node / Git / VS Code	跳过 Part 1，从 Part 2 开始
只想赶紧跑起来	读 Part 0 选型 → Part 1 地基 → 选一套 Harness → Part 5 建项目
已经有环境，想搞清关系	只读 Part 0
不写 Python	Part 1.5 和整个 Part 3 都可跳过

一句话剧情 ：先装地基（Node + Git + VS Code，写 Python 的话加一个 Python）→ 学会用 Git 存档（后悔药）→ 装一套 AI 马具 → 在 VS Code 里让它干活。

---

Part 0 · 先看全局：这些软件到底是什么关系

强烈建议先读完这一章再动手。 很多人装完一堆才发现重复了、或者根本用不上。

0.1 一个比喻

模型是马，Harness 是马具。 马跑得快，但不知道该往哪儿去；马具不产生动力，却决定马听谁指挥、跑哪条路。两者结合，才是真正能干活的 Agent。

• DeepSeek = 马（提供推理能力，按 token 计费）
• Codex / Claude Code / dsh = 马具（Harness，把模型的想法变成读写文件、跑命令、跑测试的真实动作）
• Node.js / Git = 场地和护栏
• VS Code = 驾驶舱

0.2 分层结构

先看图建立直觉：自下而上是 L0 地基 → L1 包管理器 → L2 编辑器 → L3 Agent Harness → L4 模型后端，箭头方向表示"建立在......之上"。

依赖要点：

• Node.js 是唯一的硬性地基------它挂了，全链崩溃
• Git 是安全网------不装也能跑，但改崩了没法回滚
• VS Code 是可选外壳------不用它，纯 PowerShell 也能玩
• 三个 Harness 彼此平行 ------互不依赖，也不需要彼此

0.3 关系流向图

0.4 数据流：一条指令是怎么跑完的

理解这张图，你就知道 Agent 干活时每一秒在做什么、钱花在哪、以及你什么时候该插手。

三个关键位置值得留意：第 ③ 步是唯一花钱的环节 （每次循环都在烧 token），第 ⑤ 步是你能说"不"的地方 ，第 ⑦⑧⑨ 步之间那条回环才是 Agent 比普通聊天机器人强的原因------它会自己看报错、自己改，直到跑通。

0.5 ⚠️ 核心原则：Harness 只装一套

为什么不用全装

三者的本质结构完全一致，都是 上下文收集 + 工具调用 + 会话管理 + 权限审批 的四件套中间层。差别只在交互细节（Codex 偏自动化执行、Claude Code 偏计划审查、dsh 偏插件化与 Web 工作台），能力位面是重叠的，不是互补的。同时装 ≠ 能力叠加，只是多了几种按键方式。

全装的实际代价

问题	具体表现
上下文割裂	三套各有各的会话记录和项目记忆，互不共享。在 A 里讨论过的需求，B 完全不知道，你得重复讲一遍
配置分散	API Key 要配三处，改模型、调推理强度要改三个地方，极易漏改
权限策略打架	三套的审批模式和沙箱边界不同，你对 A 的信任习惯不等于对 B 也安全
成本翻倍	同一个任务在两套里各跑一遍，token 直接双份
磁盘与更新负担	三套 CLI + 依赖数百 MB，且都在快速迭代，要维护三份更新
提交历史混杂	不同 Harness 的代码风格、提交粒度不同，Git 历史变得难以追溯
学习成本	三套斜杠命令、三套快捷键、三套配置格式，新手极易记混

选一套，用熟它。 换一套的迁移成本极低（配置就那么几行），远低于同时维护三套的代价。 唯一合理的"全装"场景是对比评测------那也建议分时段、分项目试，用完就卸。

三套怎么选

场景	推荐	理由
新手首次体验	dsh （dsh web）	DeepSeek 官方出品，Web 界面最直观，填 Key、选工作区就能聊，零命令行压力
重自动化执行	Codex	--full-auto 一口气改完跑测试；一键脚本自动配 DeepSeek，最省心
重可控与审查	Claude Code	计划先给你看、改完给你 diff，每步可驳回；/init 自动生成项目记忆
键盘党 / 纯终端	dsh-TUI	全屏 TUI，双击 Esc 回滚会话，状态栏实时看 token 与上下文

一句话建议 ：先用 dsh web 感受 Agent 怎么干活，觉得命令行不碍事了，再按偏好换到 Codex 或 Claude Code 长期用。

0.6 最小可行装机清单

必装（3 个，缺一不可）

1. Node.js 24 LTS --- nodejs.org/zh-cn/downl...
2. Git for Windows --- git-scm.com/downloads/w...
3. VS Code --- code.visualstudio.com/Download

强烈建议（1 个）

• PowerShell 7 --- winget install --id Microsoft.PowerShell --source winget 与系统自带的 5.1 并存，不冲突。用 Codex 的话基本是刚需。

Harness（三者选一个，只装一个）

• npm install -g @deepseek-ai/dsh → dsh web
• 或 npm install -g @openai/codex → codex
• 或 npm install -g @anthropic-ai/claude-code → claude

按需

• Python 3.12 / 3.13 --- www.python.org/downloads/w... Python 项目才装，装时务必勾 Add to PATH）
• pnpm：只有装 dsh-TUI 时才需要
• VS Code AI 插件：装你所选 Harness 对应的那一个即可，不装也能用

账号

• DeepSeek 开放平台 API Key 一个（充值 20 元够用一周flash模型了，最近又回调价格了）

---

Part 1 · 打地基

版本提示：@deepseek-ai/dsh 要求 Node.js ^22.19.0 或 >=24.0.0（Node 23 明确不支持 ），建议直接装 Node 24 LTS，一步到位。

1.1 PowerShell 7（可选，但强烈推荐）

Windows 自带的是 PowerShell 5.1 （2016 年的老版本，跑在 .NET Framework 上）。而 PowerShell 7 （命令名 pwsh，跑在 .NET 8 上）是微软现在的跨平台主力版本。

为什么建议装：

• Codex 特别需要它 。Codex 生成的脚本是按 pwsh 语法写的，在 5.1 上容易出现中文输出乱码、引号解析错误、JSON/正则命令失败；OpenAI 官方也推荐 Windows 用户使用 PowerShell 7+。
• 默认 UTF-8 编码，中文路径、中文输出不再乱码
• 启动更快、命令预测补全、与 Linux/macOS 行为更一致（AI 生成的跨平台脚本更容易跑通）

放心，它不会覆盖 PowerShell 5.1------两者并存安装在不同目录，随时可以切回去。

安装方式（三选一）

1. winget（推荐，CMD 里就能跑）：

winget install --id Microsoft.PowerShell --source winget

winget（Windows Package Manager）是微软官方开源的命令行包管理器，可理解为 Windows 版的 apt / brew：一条命令完成软件的搜索、安装、升级、卸载，软件来自社区清单仓库和 Microsoft Store。 哪些系统自带：Windows 11 各版本、Windows Server 2025 随"应用安装程序（App Installer）"预装；Windows 10 需 1809（build 17763）及以上，且首次登录后由 Microsoft Store 异步注册才可用。 安装 / 修复：先在终端跑 winget --version 确认。没有的话，最优是到 Microsoft Store 搜"应用安装程序"安装或更新（此后可随商店自动更新）；商店打不开可从 GitHub 的 microsoft/winget-cli Releases 下载 .msixbundle 手动装；命令注册异常则执行 Add-AppxPackage -RegisterByFamilyName -MainPackage Microsoft.DesktopAppInstaller_8wekyb3d8bbwe。 升级与维护：winget upgrade 先预览可更新项，winget upgrade --all 一键全升（未知版本加 --include-unknown，不想被升的包用 pin 锁定）；winget 自身靠 winget upgrade Microsoft.AppInstaller 更新。日常用 list / search / uninstall 管理，export / import 可备份和迁移整机软件清单，settings.json 做进阶定制。

2. MSI 安装包 ：github.com/PowerShell/... → 下载 PowerShell-7.x.x-win-x64.msi → 双击一路 Next（安装时勾选 Add to PATH）
3. Microsoft Store：搜索 "PowerShell" → 安装，后续自动更新

想装 MSI 包而非默认的 MSIX 包，用：winget install --id Microsoft.PowerShell --source winget --installer-type wix

验证（重开终端）：

pwsh --version        :: 期望 PowerShell 7.x.x
where pwsh            :: 期望 C:\Program Files\PowerShell\7\pwsh.exe

之后在任意终端敲 pwsh 即可进入 PowerShell 7。建议在 Windows Terminal 设置里把「默认配置文件」改成 PowerShell（注意别选成"Windows PowerShell"，那是 5.1）。

不装行不行？ 行。除了 Codex 的一键配置脚本外，本文命令都能在 CMD 或 PowerShell 5.1 里跑通。但如果你打算长期用 Codex，强烈建议装上，能省掉大量编码和兼容性的来回折腾（顺带省 token）。

1.2 Node.js（必装）

• 下载 ：nodejs.org/zh-cn/downl... → 选 Windows 安装包 (.msi) / LTS 24.x（x64）
• 安装 ：双击 .msi 一路 Next，保持默认的 "Add to PATH" 勾选；装完重开一个终端
• 验证：

node -v      :: 期望 v24.x.x
npm -v       :: 期望 11.x.x

• 可选加速（国内网络建议先执行）：

npm config set registry https://registry.npmmirror.com

1.3 Git for Windows（必装，含 Git Bash）

• 下载 ：git-scm.com/downloads/w... → 点 "Click here to download" 拉取 64-bit Git for Windows Setup
• 国内镜像 ：registry.npmmirror.com/-/binary/gi...
• 安装：一路 Next（默认已勾选 Git Bash Here、加入 PATH、Git from the command line）
• 验证（重开终端）：

git --version        :: 期望 git version 2.x.x
bash --version       :: 期望 GNU bash, version 5.x.x

1.4 VS Code（编辑器，强烈建议装）

前两步装的是"引擎"，VS Code 是"驾驶舱"------代码高亮、终端、Git、AI 插件都在这里汇合，Agent 改完代码你也能立刻看清每一处 diff。

下载

• 官网：code.visualstudio.com/Download → 选 Windows x64 → User Installer（不需要管理员权限）
• 国内加速：点击下载后在浏览器下载任务里"复制链接地址"，把域名 az764295.vo.msecnd.net 替换成 vscode.cdn.azure.cn（微软 Azure 国内 CDN，内容一致），粘到新标签页回车即可满速下载

安装 ：双击 VSCodeUserSetup-x64-x.xx.x.exe 一路 Next。"选择附加任务"页务必勾选：

1. ✅ 添加到 PATH（code . 命令全靠它）
2. ✅ "Open with Code" 添加到资源管理器文件/目录右键菜单
3. 其余两项随意

验证（重开终端）：

code --version

VS Code 的 AI 插件配置见 Part 5------它取决于你在 Part 4 选了哪套 Harness，所以放在后面讲。

1.5 Python（可选，做 Python 项目才装）

不写 Python 就不用装。 本指南的练手案例用 Python，所以要做案例才需要它。

• 下载 ：www.python.org/downloads/w... → 选 Windows installer (64-bit)
• 版本建议 ：装 3.12 或 3.13。最新 3.14 也可以，但部分 AI/数据类库的预编译轮子还没完全跟上，新手没必要冒险
• 安装（关键一步） ：双击安装包，第一页底部的 "Add python.exe to PATH" 必须勾选 ------官方安装器默认不勾，装完 python 命令用不了，十有八九是这个原因。建议同时勾上 "Install launcher for all users"（装 py 启动器），然后点 Install Now 即可
• 安装末尾若出现 "Disable path length limit"，点它（解除 Windows 260 字符路径限制）

验证（重开终端）：

python --version     :: 期望 Python 3.12.x / 3.13.x
pip --version        :: 期望 pip 25.x.x from ...\Python313\Lib\site-packages\pip

若提示"不是内部或外部命令"：说明 PATH 没勾上。重新运行安装包 → 选 Modify → 补勾，或手动把 Python 安装目录及其 Scripts 子目录加进 PATH。 还有一个坑：如果敲 python 打开了 Microsoft Store，去「设置 → 应用 → 应用执行别名」里关掉 Python 的别名。

1.6 pnpm（按需，仅 dsh-TUI 需要 ≥10）

从这里开始，后面的软件都用命令行安装了。

npm install -g pnpm
pnpm -v              :: 期望 10.x 或更高

若提示命令不存在，改用：corepack enable 再 corepack prepare pnpm@latest --activate

1.7 地基验收清单

五条命令全部输出版本号，才算地基牢固：

node -v && npm -v && git --version && code --version

按需再补两条：

pwsh --version       :: 装了 PowerShell 7 的话
python --version     :: 装了 Python 的话

---

Part 2 · 先学会后悔药：Git 极简上手

为什么把 Git 放在 AI 之前讲？ 因为 Agent 会改你的代码，改得又快又多，也会改错、过度设计、把能跑的版本改崩。Git 是你唯一的后悔药。 只要提交过，无论项目被折腾成什么样，一步就能回到出事前。所以「让 AI 动手前先 commit」是这套工作流里唯一不可省略的安全底线。

2.1 心智模型：四个区域

工作区  ──add──>  暂存区  ──commit──>  本地仓库  ──push──>  远程仓库(GitHub)
(你改的文件)      (待提交清单)         (历史存档)            (云端备份)

• 工作区：你在 VS Code 里看到的文件夹
• 暂存区：挑出这次要提交哪些文件
• 本地仓库：提交后生成一个存档点（commit），有唯一 ID，随时可回
• 远程仓库：推到 GitHub/Gitee，换电脑、协作都靠它

绝大多数时间只在前三区打转，不联网也能完整使用 Git。

2.2 首次配置（只做一次）

git config --global user.name  "你的名字"
git config --global user.email "you@example.com"

可选但推荐（避免换行符和中文文件名乱码）：

git config --global core.autocrlf input
git config --global core.quotepath false

2.3 必记的 5 条命令

命令	作用	什么时候用
git init	把当前文件夹变成 Git 仓库	新项目开工第一件事
git status	看当前有哪些改动	拿不准就敲它，最常用
git add .	把所有改动加入待提交清单	提交前
git commit -m "说明"	生成一个存档点	每完成一个小目标就提交
git log --oneline	看历史存档列表	想回滚时找 ID

日常三步走：

git add .
git commit -m "feat: 新增番茄钟创建任务接口"
git status        :: 确认工作区干净

提交信息写清"做了什么"即可，中文完全没问题。

2.4 三档撤销（重点）

按破坏力从小到大排，优先用最温和的：

场景	命令	说明
文件改乱了，想丢弃改动	git restore 文件名	只丢这一个文件，最安全
想丢弃全部未提交改动	git restore .	回到最近一次提交的状态
已 add 但想撤回	git restore --staged 文件名	从清单里拿掉，文件本身不变
回到某个历史存档	git log --oneline 查 ID → git checkout <ID>	临时查看，别在这改代码
彻底回退到某存档	git reset --hard <ID>	⚠️ 之后的提交全部消失，慎用

口诀：能 restore 就别 reset，能 checkout 看就别 --hard。

2.5 分支：并行实验的安全区

想让 Agent 试一个大胆方案，又怕搞坏主线？开分支。

git branch                  :: 看有哪些分支（* 是当前所在）
git switch -c ai-refactor   :: 新建并切到 ai-refactor
:: ...让 Agent 随便折腾、提交...
git switch main             :: 切回主线
git merge ai-refactor       :: 满意就合并

不满意直接删掉，主线毫发无损：git branch -D ai-refactor

2.6 远程仓库：备份与同步

git remote add origin https://github.com/你的账号/仓库名.git   :: 首次关联
git push -u origin main        :: 首次推送（-u 之后可省略参数）
git pull                       :: 拉取远端最新
git clone <仓库地址>            :: 下载已有仓库

推送时若弹窗登录，用 GitHub 个人访问令牌（PAT） 代替密码，浏览器登录方式已逐步停用。

2.7 AI 协作两条铁律

1. 动手前先提交 ：git add . && git commit -m "before: AI 重构前快照"。改崩就 git restore . 一键还原。
2. 分阶段小步提交：别让 Agent 一口气改十个文件再提交。每完成一个小功能提交一次，出问题能精确定位是哪一步引入的。

.gitignore 用来声明"哪些文件不进版本库"。Python 项目至少写：

.venv/
__pycache__/
*.pyc

避免把几百 MB 的虚拟环境提交进去。

2.8 不背命令：VS Code 点鼠标完成 90% 操作

说实话，上面这些命令你一条都不用记。 VS Code 自带图形化 Git------左侧活动栏那个三圆点连线图标 就是「源代码管理」面板（Ctrl+Shift+G）。

你要做的事	在 VS Code 里怎么点
看改了哪些文件	打开源代码管理面板，改动文件自动列出（U=新增，M=修改，D=删除）
看具体改了什么	点文件名，右侧直接出并排 diff，红删绿加一目了然
暂存（add）	文件旁的 + 号；或「更改」标题栏的 + 一键全加
提交（commit）	上方输入框写说明 → 点 ✓ 提交
撤销改动（restore）	文件旁的 ↩ 放弃更改 按钮，会二次确认
看历史	装 GitLens 后点文件右上历史；或命令行 git log
建/切分支	点左下角分支名 → 新建分支 / 选择分支
合并分支	左下角 → 合并分支 → 选来源
推送/拉取	点左下角 同步更改（双向）或状态栏的 ↑↓ 数字
解决冲突	冲突文件里直接点「采用当前/传入/保留双方」三选一

两个增强插件：

• GitLens --- 每行代码右侧显示"谁、什么时候、为什么改的"（行内 blame），悬停看完整提交
• Git Graph --- 把提交历史画成可视化分支树，回滚、比较、打标签全靠点

建议用法 ：日常全用图形界面，只在两种情况下回命令行------需要 git reset --hard 这类破坏性操作（命令行更明确），或想批量处理（如 git restore . 一次丢弃全部改动）。

记住三个动作就够了：改之前看 status，改一段就 commit，改崩了点一下「放弃更改」。

---

Part 3 · Python 极简上手（可选）

只在你要写 Python 时才需要读这一章。若你打算用 JavaScript / Go / Java 做练手项目，整章可跳过。 本章约 1000 字，目标：会建环境、会装包、会跑脚本，仅此而已。

3.1 为什么 AI 编程案例多用 Python

不只是因为 Python 简单。更实际的原因是：几乎所有大模型都用过海量 Python 代码训练，AI 写 Python 的准确率明显更高 ；加上 Web 后端、数据处理、自动化测试三大场景的生态最成熟------FastAPI 起服务、pytest 跑测试、requests 调接口，几行命令就能验证 Agent 的活干得对不对。所以本指南的练手案例选了 Python。

3.2 两个概念：解释器与包仓库

• Python 解释器 ：执行 .py 文件的程序，就是你刚装的那个 python.exe
• PyPI（Python Package Index） ：官方包仓库 ，全球开发者发布的第三方库都在这里（目前上百万个包）。pip 就是从这个仓库下载安装包的工具

类比一下：PyPI 相当于 Python 世界的 npm，pip 相当于 npm install。

3.3 虚拟环境：每个项目一套独立依赖（重要）

为什么必须用它：如果所有项目共用一套库，A 项目要 Django 4、B 项目要 Django 5，必然打架；更糟的是 Agent 装了一堆实验性依赖后，把你的全局环境搞得乱七八糟。

虚拟环境就是在项目目录里建一个独立的 .venv 文件夹，这个项目装的所有库都只进这个文件夹，互不干扰。

cd D:\ai-lab\demo
python -m venv .venv      :: 创建（一个项目只需做一次）
pip install fastapi       :: 之后的 pip 都装进这个 .venv

激活虚拟环境（⚠️ 每次新开终端都要做）：

:: CMD
.venv\Scripts\activate.bat

# PowerShell
.\.venv\Scripts\Activate.ps1

激活成功后命令行前面会出现 (.venv) 前缀。看到这个前缀，说明你装包装对地方了。 退出用 deactivate。

把 .venv/ 写进 .gitignore------虚拟环境有几百 MB，不该进版本库。

3.4 pip 常用命令

pip install 包名              :: 安装最新版
pip install 包名==2.1.0       :: 装指定版本
pip install -U 包名           :: 升级
pip uninstall 包名            :: 卸载
pip list                      :: 看已装了什么
pip show 包名                 :: 看某个包的详情
pip install -r requirements.txt   :: 按清单批量安装
pip freeze > requirements.txt     :: 把当前环境导出成清单

requirements.txt 是什么 ：项目的依赖清单，记录了"跑起来需要哪些库、什么版本"。别人拿到你的项目，一条 pip install -r requirements.txt 就能复现环境。Agent 生成的 Python 项目通常会自动带上它。

顺手升级一下 pip 自己：python -m pip install -U pip

3.5 配置国内镜像源（国内必做）

PyPI 官方服务器在国外，直连经常几 KB 每秒甚至超时。换国内镜像后速度提升十倍不止。

永久配置（推荐，一次搞定）：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

配置会写入 %APPDATA%\pip\pip.ini，之后所有 pip install 自动生效。查看当前配置用 pip config list，恢复官方源用 pip config unset global.index-url。

临时使用（只对这一条命令生效，适合测试或装私有包）：

pip install 包名 -i https://mirrors.aliyun.com/pypi/simple/

2026 年实测可用的镜像：

镜像	地址	备注
清华 TUNA	https://pypi.tuna.tsinghua.edu.cn/simple	同步最快、包最全，首选
阿里云	https://mirrors.aliyun.com/pypi/simple/	企业稳定，全国速度均衡
腾讯云	https://mirrors.cloud.tencent.com/pypi/simple/	腾讯云环境最快
中科大	https://pypi.mirrors.ustc.edu.cn/simple/	教育网优势明显
华为云	https://repo.huaweicloud.com/repository/pypi/simple/	偶有限流，备选

⚠️ 老教程里的豆瓣源和网易源已经不可用了（连接重置 / SSL 超时），别再照抄。

3.6 跑起来

python main.py                      :: 运行脚本
python -m pytest                    :: 跑测试（推荐用 -m 前缀）
python -m uvicorn main:app --reload :: 起 Web 服务

为什么推荐 python -m xxx 而不是直接 xxx：前者能确保用的是当前虚拟环境里的版本，避免 PATH 里藏着另一个同名命令------这是新手最常见的"明明装了却跑不起来"。

3.7 在 VS Code 里写 Python

装微软官方的 Python 扩展（ms-python.python）和 Pylance 。首次打开 .py 文件时，按 Ctrl+Shift+P → 输入 Python: Select Interpreter → 选带 .venv 的那一项，让编辑器和终端用同一个环境。之后 F5 可断点调试，右上角 ▶ 直接运行。

给 Agent 的提示词里主动声明环境，能少走很多弯路：

项目使用 Python 3.13 + FastAPI，依赖已装在 .venv 里。所有命令请用 python -m xxx 形式执行。
一句话总结 ：每个项目一个 .venv，装包前先换国内镜像，跑脚本用 python -m，依赖写进 requirements.txt。

---

Part 4 · 装上马具：Agent Harness（三选一）

4.0 准备 API Key

三个 Harness 共用同一把钥匙：

1. 打开 platform.deepseek.com 注册登录
2. 左侧 API Keys → 创建 API key
3. 密钥只在创建那一刻显示一次，立刻复制存好
4. 充值 10 元足够日常试用（简单对话几分钱一次，复杂任务几毛）

⚠️ API Key 等于钱包钥匙：别截图外传、别明文写进代码、别提交到 GitHub。

---

4.1 方案 A：Codex + DeepSeek（推荐）

OpenAI 出品的编程 Agent，通过 Responses API 与模型交互，DeepSeek 原生支持该格式。

安装

npm install -g @openai/codex
codex --version

先跑一次 codex （让 C:\Users\<你的用户名>\.codex 目录生成），登录/退出随意，之后按 Ctrl+C 退出。

一键接入 DeepSeek

⚠️ 这一步必须用 PowerShell （PowerShell 5.1 或 7 均可，建议 7）。这条命令里的 irm 是 Invoke-RestMethod 的缩写、iex 是 Invoke-Expression，CMD 没有对应语法；且要执行的脚本本身是 .ps1 文件。 在 CMD 里先敲 powershell 回车进入 PowerShell 再执行即可。

irm https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.ps1 | iex

按菜单选模型（首次需输入 sk- 开头的 API Key），脚本会自动写好 models.json 和 config.toml。再次运行脚本可切换模型或恢复默认配置（菜单第 3 项）。

验证 ：进入任意项目目录执行 codex，启动信息显示 model: deepseek-v4-flash 即生效。

模型支持说明 ：目前仅 deepseek-v4-flash 支持接入 Codex，deepseek-v4-pro 预计 2026 年 8 月初支持。 一配全端 ：Codex CLI、ChatGPT 桌面端、VS Code 的 Codex 插件共用同一份 ~/.codex/config.toml，配一次即可在所有形态使用。

快速上手（200 字内） ：进入项目目录敲 codex 启动，底部显示 model: deepseek-v4-flash 即生效。用自然语言描述任务即可，如"给 src 目录补单元测试"。/model 切换模型，/status 看用量和会话，/approvals 调权限（默认改动文件会先问你）。加 --full-auto 让它自主改代码并执行命令，重要任务先 git commit 留回滚点。

---

4.2 方案 B：Claude Code + DeepSeek

Anthropic 出品的终端内 AI 编程助手，特点是每一步都可审查、可驳回。

安装

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

配置环境变量（当前窗口生效）

⚠️ 设置临时环境变量的写法因终端而异，两条命令作用完全一样，挑你正在用的那个：

CMD 里用 set：

set ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
set ANTHROPIC_AUTH_TOKEN=sk-你的APIKey
set ANTHROPIC_MODEL=deepseek-v4-pro[1m]
set ANTHROPIC_DEFAULT_OPUS_MODEL=deepseek-v4-pro[1m]
set ANTHROPIC_DEFAULT_SONNET_MODEL=deepseek-v4-pro[1m]
set ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-v4-flash

PowerShell 里用 $env:（5.1 与 7 都一样）：

$env:ANTHROPIC_BASE_URL = "https://api.deepseek.com/anthropic"
$env:ANTHROPIC_AUTH_TOKEN = "sk-你的APIKey"
$env:ANTHROPIC_MODEL = "deepseek-v4-pro[1m]"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "deepseek-v4-pro[1m]"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "deepseek-v4-pro[1m]"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "deepseek-v4-flash"

永久生效（写入用户环境变量，重开终端仍在）

setx 是 Windows 系统命令，CMD 与 PowerShell 通用：

setx ANTHROPIC_BASE_URL https://api.deepseek.com/anthropic
setx ANTHROPIC_AUTH_TOKEN sk-你的APIKey
setx ANTHROPIC_MODEL "deepseek-v4-pro[1m]"
setx ANTHROPIC_DEFAULT_HAIKU_MODEL deepseek-v4-flash

注意：setx 写入后对当前窗口不生效 ，需重开终端。想立刻在本窗口验证，就再用上面的 set / $env: 设一遍。

启动 ：cd D:\你的项目 然后 claude。

模型名映射 ：claude-opus* → deepseek-v4-pro；claude-sonnet* / claude-haiku* → deepseek-v4-flash。所以在 Claude Code 里选 Opus / Sonnet / Haiku 都行。

快速上手（200 字内） ：在项目根目录敲 claude 进入交互界面。首次建议先输入 /init，它会扫描仓库生成 CLAUDE.md 项目记忆，后续对话自动带上上下文。用 @文件名 精确指定要改的文件，/model 切模型，/compact 压缩长会话省 token，/clear 开新话题。写操作会弹确认，选 "Yes, and don't ask again" 可放行本轮。注意：它触发 Web Search 时会额外调用大模型总结搜索结果，产生额外 token 费用。

---

4.3 方案 C：dsh + dsh-TUI（DeepSeek 官方）

DeepSeek 自家开源的 Agent 运行时，命令行叫 dsh，理念是"一切皆插件"。默认入口是 Web 界面，dsh-TUI 是社区开发的 Claude Code 风格终端界面插件。

安装

npm install -g @deepseek-ai/dsh @deepseek-harness-tui/dsh-tui
dsh --version

配置 API Key

setx DEEPSEEK_API_KEY sk-你的APIKey

两种用法

dsh web        :: Web UI，浏览器打开 http://127.0.0.1:3080
dsh-tui        :: 终端界面，需 pnpm ≥10、交互式终端

Web 端首次进入必须做两件事：设置 → 模型里填 API Key；左侧「选择工作区」选中一个项目文件夹，否则输入框是锁死的。

快速上手（200 字内） ：推荐先 dsh web，浏览器里选好工作区就能对话；习惯键盘就 dsh-tui，进入后 Enter 发送、Shift+Enter 换行、@ 引用文件。常用斜杠命令：/new 新会话、/resume 恢复历史、/model 切模型、/preset 切预设（standard/code/minimal）、/doctor 自检环境、/compact 压缩上下文、/cost 看花费。输入框空着时双击 Esc 可回滚会话并分叉重来，Ctrl+C 中断当前回合。脚本场景用 dsh --profile headless "任务描述"。

---

Part 5 · 在 VS Code 里干活

5.1 怎么进命令行

• Ctrl + \`` （反引号，键盘左上角）开关集成终端；Ctrl+Shift+`` 新建一个
• 终端右上角下拉 → "选择默认配置文件" → 切成 PowerShell （装了 7 的话这里选带 7 的那个）、CMD 或 Git Bash （想要 ls、grep 等 Linux 命令时）
• 左侧资源管理器右键文件夹 → "在集成终端中打开"，直接定位到该目录
• 系统终端里进目录后敲 code .，用 VS Code 打开当前文件夹
• 集成终端里直接跑 codex / claude / dsh web，和外面终端完全一致

5.2 AI 编程插件清单

装你所选 Harness 对应的那一个即可，不需要全装。

插件	扩展 ID	说明
Chinese (Simplified) 语言包	ms-ceintl.vscode-language-pack-zh-hans	界面汉化，装完重启生效
Codex -- OpenAI's coding agent	openai.chatgpt	OpenAI 官方，直接复用 Part 4 的 ~/.codex/config.toml，接 DeepSeek 零额外配置
Claude Code for VS Code	anthropic.claude-code	Anthropic 官方，需 VS Code ≥ 1.98；走 DeepSeek 时在集成终端跑 claude 更稳
dsh-tui-vscode	社区	dsh-TUI 的编辑器伴侣扩展，选方案 C 时装
GitHub Copilot + Copilot Chat	github.copilot / github.copilot-chat	行内补全标杆，学生/开源作者可免费申请；与上面三套不冲突，属于补全而非 Agent
Continue / Cline / Roo Code（三选一）	continue.continue 等	开源 Agent，设置里填 DeepSeek 的 Key 与 https://api.deepseek.com 即可
CodeBuddy	腾讯	国内直连、中文语境友好，备选
GitLens / Git Graph	---	见 Part 2.8，看提交历史与分支树
Error Lens / Prettier / ESLint / Python	---	效率配套：行内报错、格式化、语法检查、Python 支持

怎么装插件（三种任选）

1. Ctrl+Shift+X 打开扩展面板 → 搜名字 → Install（认准"已验证/官方"徽标，仿冒插件不少）
2. 命令行一行装完：code --install-extension openai.chatgpt（把 ID 换成上表任意一行）
3. 项目根目录建 .vscode/extensions.json 写推荐清单，队友打开项目会提示一键安装

5.3 创建第一个小项目（Python + FastAPI 番茄钟）

mkdir D:\ai-lab\demo
cd D:\ai-lab\demo
code .                      :: 用 VS Code 打开当前目录

在 VS Code 的集成终端（`Ctrl+``）里继续（虚拟环境的细节见 Part 3.3）：

git init                    :: 建仓库，先留回滚点
python -m venv .venv        :: 建虚拟环境

激活虚拟环境（⚠️ 命令因终端而异；每次新开终端都要重做）：

:: CMD 用 .bat 脚本
.venv\Scripts\activate.bat

# PowerShell 用 .ps1 脚本
.\.venv\Scripts\Activate.ps1

若 PowerShell 报"禁止运行脚本"，先在 PowerShell 里执行一次（⚠️ 仅 PowerShell）： Set-ExecutionPolicy -Scope CurrentUser RemoteSigned 激活成功后，命令行前面会出现 (.venv) 前缀。

装依赖（国内先按 Part 3.5 配好镜像，否则可能极慢）：

pip install fastapi uvicorn pytest

左侧新建 main.py、tests/test_api.py、README.md、.gitignore（内容写 .venv/）。

然后按 Part 4 选的 Harness 上手：终端敲 claude 后先输 /init 生成 CLAUDE.md 项目记忆，或敲 codex 直接下任务，或另开终端 dsh web。

运行与调试 ：python -m uvicorn main:app --reload，浏览器打开 http://127.0.0.1:8000/docs 看接口；F5 可配断点调试。

收尾 ：git add . + git commit -m "init"。

---

Part 6 · 练手提示词

建议用 Part 5 建的 D:\ai-lab\demo，让 Agent 在里面折腾。

① 从零生成小项目（练全流程）

用 Python + FastAPI 写一个"番茄钟"后端：支持创建任务、开始/暂停、查询今日统计，数据存 SQLite。要求：项目结构清晰、带 requirements.txt、每个接口有单元测试，最后写 README 说明启动方式。完成后自己跑一遍测试并把结果贴给我。

② 读懂陌生仓库（练代码理解）

这是我从 GitHub 克隆的仓库（路径 ./xxx）。请先全局浏览，然后告诉我：1) 项目解决什么问题；2) 目录结构与核心模块职责；3) 从入口函数到数据库写入的完整调用链；4) 三个你认为最值得改进的地方。用 Markdown 输出，关键位置标注 文件:行号。

③ 修 Bug / 改报错（练调试）

运行 python main.py 报了下面的错误（粘贴完整 traceback）。请定位根因、解释为什么会触发，然后给出最小改动方案并执行修改。改完重跑验证，最后说明你改了哪几行、为什么这样改是安全的。

④ 重构与加测试（练质量意识）

对 src/utils.py 做重构：拆分超过 50 行的函数、消灭重复代码、补充类型注解和 docstring，保持对外接口不变。同时为公开函数补齐 pytest 测试，覆盖正常值、边界值和异常输入三类。重构前后分别运行测试，确认行为一致。

⑤ 跨文件大改（练多步自主）

把项目里所有 print() 调试输出替换成标准 logging 模块：统一日志格式（时间-级别-模块-消息）、按环境变量控制日志级别、保留原有输出内容不变。涉及的文件自己找全，改完 grep 确认没有遗漏，最后跑通全部测试。

⑥ 写文档与自动化（练交付）

为这个仓库生成一份中文 DEVELOP.md：包含环境要求、安装步骤、常用命令、目录说明、常见问题。再写一个 GitHub Actions 工作流，在 push 到 main 时自动执行 lint 和测试。
通用心法 ：任务描述里写清「目标 + 约束 + 验收标准 + 边界（不要动什么）」，比反复追加指令有效得多；每次动手前先 git commit，出问题一行回滚。

---

附录 A · 命令速查卡

除特别标注 ⚠️ 的外，以下命令在 CMD 与 PowerShell 中完全一致。

环境验证

node -v && npm -v && git --version && code --version
pwsh --version     :: 装了 PowerShell 7 的话
python --version   :: 装了 Python 的话

Git 五件套

git init
git status
git add .
git commit -m "说明"
git log --oneline

Git 撤销（由温和到激进）

git restore 文件名              :: 丢弃该文件改动
git restore .                   :: 丢弃全部未提交改动
git restore --staged 文件名     :: 撤回 add
git checkout <ID>               :: 临时查看历史版本
git reset --hard <ID>           :: ⚠️ 彻底回退，慎用

Harness 启动

codex              :: 或 codex --full-auto
claude             :: 首次建议先 /init
dsh web            :: http://127.0.0.1:3080
dsh-tui            :: 终端界面

Python 虚拟环境与 pip（详见 Part 3）

python -m venv .venv               :: 创建虚拟环境（一次）
.venv\Scripts\activate.bat         :: 激活（CMD）
pip install 包名                    :: 安装
pip install -r requirements.txt    :: 按清单批量装
pip freeze > requirements.txt      :: 导出清单
python -m pytest                   :: 跑测试
deactivate                         :: 退出虚拟环境

pip 换国内镜像（只需做一次，详见 Part 3.5）

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn
pip config list                    :: 查看当前配置

仅 PowerShell 的四条

irm https://cdn.deepseek.com/api-docs/codex-deepseek-setup-en.ps1 | iex   # Codex 一键配 DeepSeek
$env:DEEPSEEK_API_KEY = "sk-xxx"                                          # 临时环境变量
.\.venv\Scripts\Activate.ps1                                              # 激活 Python 虚拟环境
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned                       # 解除脚本执行限制

它们在 CMD 中的等价写法：

:: ① 一键脚本：先进 PowerShell 再执行
powershell

:: ② 临时环境变量用 set
set DEEPSEEK_API_KEY=sk-xxx

:: ③ 激活虚拟环境用 .bat
.venv\Scripts\activate.bat

:: ④ 执行策略：CMD 无对应概念，虚拟环境本来也不需要它

---

附录 B · Codex 手动配置（一键脚本失效时）

如果一键脚本跑不通，手动配两个文件即可。

第一步 ：创建 C:\Users\<你的用户名>\.codex\models.json，声明模型元数据（含 deepseek-v4-flash 与 deepseek-v4-pro 两项，字段为 context_length、reasoning_effort_levels、tool_calling_format，视觉模型另加 input_modalities）。完整内容以官方文档为准：api-docs.deepseek.com/zh-cn/quick...

第二步 ：编辑 ~/.codex/config.toml（不存在则新建）：

model = "deepseek-v4-flash"
model_provider = "deepseek"
preferred_auth_method = "apikey"
forced_login_method = "api"
model_reasoning_effort = "high"
model_catalog_json = "C:\\Users\\<你的用户名>\\.codex\\models.json"   # Windows 建议写绝对路径

[model_providers.deepseek]
name = "deepseek"
base_url = "https://api.deepseek.com/"
wire_api = "responses"
experimental_bearer_token = "sk-你的APIKey"

配置完成后，Codex CLI、ChatGPT 桌面端、VS Code 插件都会读取同一份文件，无需分别配置。

---

附录 C · 避坑清单

坑	表现	解法
Node 版本不对	dsh 安装失败或运行报错	必须 ^22.19.0 或 >=24.0.0，Node 23 不支持
装完命令找不到	"不是内部或外部命令"	重开终端；仍不行检查安装时是否勾选 Add to PATH
npm 下载慢	卡在 fetch	npm config set registry https://registry.npmmirror.com
VS Code 下 code . 无效	命令不存在	重装时勾选"添加到 PATH"，或装完重启
irm 不是可识别命令	CMD 里报语法错误	irm 是 PowerShell 命令，先敲 powershell 进入再执行
venv 激活报脚本禁用	"无法加载文件...禁止运行脚本"	PowerShell 里执行 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned；或改用 CMD 的 activate.bat
Codex 中文输出乱码	终端显示问号或方块	换 PowerShell 7（Part 1.1），5.1 默认编码非 UTF-8
Codex 脚本总跑不通	引号、JSON、正则命令报错	同上，换 PowerShell 7；Codex 生成的脚本按 pwsh 语法写
pwsh 命令找不到	装完仍提示不存在	重开终端；或确认安装路径 C:\Program Files\PowerShell\7\ 已在 PATH 中
dsh web 输入框锁死	打字没反应	没选工作区，左侧「选择工作区」选中一个文件夹即可
Claude Code 提示未登录	环境变量没继承	setx 后需重开终端；或用 code . 从终端启动 VS Code
Codex 选不到 v4-pro	菜单只列出 flash	官方说明 v4-pro 预计 2026 年 8 月初支持 Codex
敲 python 弹出应用商店	打开 Microsoft Store 而非运行	设置 → 应用 → 应用执行别名，关掉 Python 的两个别名
pip 不是可识别命令	装了 Python 却用不了 pip	安装时漏勾 Add to PATH；重跑安装包选 Modify 补勾
pip 下载极慢或超时	卡在 Downloading	按 Part 3.5 配清华源；豆瓣源、网易源已失效，别用
包装到全局去了	项目找不到刚装的库	没激活 .venv（命令行前应有 (.venv) 前缀）
AI 改崩回不去	项目跑不起来	git restore .；前提是你动手前提交过

三条长期习惯

1. Harness 只留一套------装一套用熟，比三套都装都半懂强得多。
2. API Key 只存一处 ------优先 setx 写进系统环境变量，别硬编码进代码、别提交到 GitHub。
3. 动手前先 commit------这是唯一不可省略的安全底线。Agent 会犯错，Git 是你唯一的后悔药。