使用 Agent 辅助你的编程！

前言

先回顾一下编程方式在过去几年的变化。

在 AI 出现之前，编程世界的两大信条是 RTFM（Read The Fucking Manual，去读手册）和 STFW（Search The Fucking Web，去搜网络）——这也是 PA 讲义里的高频词：遇到问题，先查一手资料，再自己动手解决。更"取巧"一点的，是去 GitHub 上借鉴前人的实现（课程不推荐，你很难判断代码质量，更会失去自己思考的机会）。助教刚好在"古法编程"时代的最后一年进入本科学习，亲眼见证了接下来这段变革的全过程：

今天，用不用 AI 已经不是问题，怎么用好 AI才是问题。本文档就来回答这个问题。

Agent = Model + Harness

一个 AI 编程 Agent 可以拆成两个部分：

• Model（模型）：Agent 的"大脑"。负责理解你的指令并生成回答。
• Harness（框架/载体）：Agent 的"身体"。负责给大脑装上"眼耳口鼻手足"——读文件、写文件、执行命令、调用工具、管理上下文、提供交互界面。

只有 Model 没有 Harness，你只能像用网页聊天一样一问一答，读写文件、跑命令都得自己手动代劳；只有 Harness 没有 Model，那只是一具没有大脑的空壳。两者结合起来，才是你将要使用的"AI 编程助手"。

Model

模型调用的本质

抛开一切炫酷的概念，调用一个模型本质上就是一次 HTTP 请求：你向一个 URL 发送一段 JSON（请求），模型返回一段 JSON（响应）。几乎所有主流模型都遵循 OpenAI 定义的接口格式（OpenAI 兼容格式）。

一次典型的请求长这样：

{
  "model": "deepseek-v4-flash",
  "messages": [
    { "role": "user", "content": "请用一句话介绍 RISC-V" }
  ]
}

响应（简化）长这样：

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "RISC-V 是一个基于精简指令集（RISC）思想的开源指令集架构。"
      }
    }
  ]
}

用命令行同样可以直接发起一次请求（以 curl 为例）：

curl http://<平台地址>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <你的 API Key>" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      { "role": "user", "content": "请用一句话介绍 RISC-V" }
    ]
  }'

这里涉及几个基本概念：

• Prompt（提示词）：你发送给模型的全部输入文本，包括系统提示、历史对话和当前问题。
• Response（响应）：模型根据 prompt 生成的输出文本。
• Token（词元）：模型处理文本的基本单位。模型不是按"字"理解文本，而是把文本切成更小的 token（大约一个 token 对应半个到一个汉字，或 3~4 个英文字符）。计费按 token 数计算。
• 上下文窗口（Context Window）：模型单次请求能"看到"的 token 总量上限，包含输入与输出。对话越长占用的上下文越多，超过上限后，过老的内容会被截断，或由 Harness 进行压缩摘要。

计费：输入 / 输出 / 缓存

一般的 API 计费按 token 分成三类：

• 输入 token（input）：你发送给模型的 prompt 中的全部 token。多轮对话中每轮都会重复发送历史，因此长对话的输入费用是主要开销。
• 输出 token（output）：模型生成的 token，通常单价高于输入。
• 缓存 token（cache）：当多轮对话中的历史内容命中服务端上下文缓存时，这部分输入 token 按更低的"缓存价"计费。同一会话中连续提问、不频繁重开会话，命中缓存越多，越省钱。

此外，不少服务采用峰谷计费：高峰时段（例如工作日白天）价格更贵，低谷时段（晚上、周末、清晨）更便宜。本课程平台的计费细节见下文「课程模型平台」一节。

Harness

Harness 是运行在 Model 之外的框架/工具，负责把模型变成真正能"干活"的助手。它通常提供以下能力：

• 文件操作：直接在项目里读写、编辑代码文件，而不是让你复制粘贴。
• 命令执行：在你的环境中运行编译、测试、git 等命令，并读取输出、根据报错自动修正。
• 工具调用：调用网页搜索、调试器等外部工具，扩展模型的能力边界。
• 上下文管理：自动压缩、摘要过长的历史对话，或只读入大文件的必要部分，以突破模型上下文窗口的限制。
• 任务规划与循环：把复杂任务拆成多步，执行 → 观察结果 → 再执行，直到完成。
• 交互界面：终端 UI 或 IDE 面板，让你实时看到模型在做什么、随时干预。
• 模型切换：主对话用强模型、后台杂活用便宜模型，钱花在刀刃上。

一个称手的 Harness 能让模型能力成倍放大；反过来，不借助 Harness，再强的模型在你手里也只是一个高级聊天窗口。

选择你的 Model

当下主流模型一览

国内模型与开源模型近年来发展极快。截至本文档编写时（2026 年），主流选择包括：

• DeepSeek 系列：性价比较高，课程平台当前验证的模型见下文；具体模型 ID、能力和价格以平台页面为准。
• 通义千问（Qwen）系列：阿里出品，开源生态完善，社区适配良好。
• 智谱 GLM 系列：清华系背景，综合能力均衡。
• 月之暗面 Kimi：长上下文表现突出。

各家模型在性能与价格上差异巨大，且迭代极快，本文档不逐一列举具体数值，请以各家官方定价页和课程平台页面为准。对本课程而言，我们只需关心一件事——性价比：PA 的任务（理解框架、写小模块、调试）并不需要顶配模型，够用且便宜才是王道。国外模型不在本文档的讨论范围内，感兴趣的同学可以自行了解。

课程模型平台

为了让每位同学都能用上模型，课程为选课同学提供了一定量的免费 Token 额度。使用方法如下：

1. 从课程主页进入我们自建的 Token 管理平台，用课程账号登录。
2. 平台提供了一系列价格合理的国产模型（对接 DeepSeek 官方 API 以及其他模型 API）。价格、额度和峰谷时段可能调整，以平台页面为准；不要把某个时段或单价当成永久规则。把批量任务安排在低价时段可以节省额度，但不推荐为了省额度熬夜。
3. 在平台上生成你的 API Key：登录后进入「令牌」页面，点击新建令牌，创建后立即复制保存（Key 务必妥善保管，避免泄露）。
4. 平台提供 OpenAI 兼容 和 Anthropic 兼容端点：<平台地址> 以平台页面显示的地址为准，通常是 http://主机:端口。两种兼容格式的路径和参数可能不同，配置时要使用对应端点，不要只把一个 URL 在所有工具中机械复用；模型名填平台上的模型 ID。

以 deepseek-v4-flash 为例，课程选择它作为主力模型主要是因为它在当前平台上的性价比较好。具体价格和额度消耗请以平台页面为准，不要根据本文中的示例估算预算。

从生成 Key 到第一次调用

以 deepseek-v4-flash 为例：

1. 登录平台，在「令牌」页面新建一个令牌，创建并复制你的 Key。
2. 用 curl 发起第一次请求。下面的写法把 Key 暂存在当前 shell 的环境变量中，避免把真实 Key 直接写进命令或文档：

read -r -s -p 'API Key: ' ICS_API_KEY
printf '\n'
ICS_BASE_URL='http://<平台地址>/v1'

curl --fail --silent --show-error "$ICS_BASE_URL/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ICS_API_KEY" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      { "role": "user", "content": "你好！请介绍一下你自己。" }
    ]
  }'

unset ICS_API_KEY

如果一切正常，你会收到一个 JSON 响应，其中 choices[0].message.content 就是模型的回答。到这里，你已经亲手完成了"用命令行调用模型"的全流程——所有 AI 编程工具，本质上都是在帮你自动重复这件事，再加上前面所说的 Harness 能力。你可以自由替换模型进行尝试。

选择你的 Harness

当下主流 Harness 一览

• opencode：开源终端编程 Agent，配置灵活、对模型开放，并内置了一批免费模型可供直接使用。
• Claude Code：Anthropic 官方终端 Agent，交互体验成熟，VSCode 扩展生态完善，编程能力强。
• Codex：OpenAI 官方的编程 Agent（APP、CLI 与 IDE 插件）。
• DeepSeek Harness：DeepSeek 最新发布的编程 Harness。

各工具各有取舍，但我们最推荐 opencode：开源、配置简单、免费模型多、对国产模型支持好。下面分别给出 opencode、Claude Code、Claude Code for VSCode 的配置方法。

配置 opencode

在 opencode 的配置文件中（全局配置 ~/.config/opencode/opencode.json，或项目内 .opencode/opencode.json）添加一个自定义 provider，把平台的模型都列出来。下面只展示配置思路；不同版本的字段名可能略有变化，请以配置文件中的 schema 和 opencode 官方文档 为准：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ics": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ICS 课程平台",
      "options": {
        "baseURL": "http://<平台地址>/v1",
        "apiKey": "{env:ICS_API_KEY}"
      },
      "models": {
        "deepseek-v4-flash": { "name": "DeepSeek V4 Flash" },
        "deepseek-v4-pro": { "name": "DeepSeek V4 Pro" },
        "其他模型调用名称": { "name": "其他模型的自定义显示名称" }
      }
    }
  }
}

先在当前 shell 中设置 ICS_API_KEY，或使用 opencode 的 /connect 管理凭据；不要把真实 Key 写进项目配置并提交到 Git。保存后重新打开 opencode，在 /model（部分版本为 /models）模型选择界面即可看到并选用 ics/deepseek-v4-flash 等模型。此外，opencode 还有两点值得利用：

• 内置了大量常见 provider（包括 DeepSeek 官方、OpenRouter 等），直接在 TUI 中用 /connect 命令粘贴对应平台的 Key 即可使用，无需手写配置。
• 自身提供了一批经过验证的免费模型，可用于日常问答等非关键任务，为课程额度省下宝贵的 token。

配置 Claude Code

Claude Code 通过环境变量来指定 API 地址、鉴权与模型映射。下面是一份经助教验证可用的变量清单（以 deepseek-v4-flash + deepseek-v4-pro 组合为例），你需要根据自己使用的 shell、VSCode 或其他启动方式把它转换成相应配置；它不是可以直接保存的完整 JSON 文件。把 <平台地址> 与 <你的 API Key> 替换为实际值：

{
  "name": "ANTHROPIC_BASE_URL",
  "value": "http://<平台地址>/v1"
},
{
  "name": "ANTHROPIC_AUTH_TOKEN",
  "value": "<你的 API Key>"
},
{
  "name": "ANTHROPIC_MODEL",
  "value": "deepseek-v4-pro"
},
{
  "name": "ANTHROPIC_DEFAULT_OPUS_MODEL",
  "value": "deepseek-v4-pro"
},
{
  "name": "ANTHROPIC_DEFAULT_SONNET_MODEL",
  "value": "deepseek-v4-pro"
},
{
  "name": "ANTHROPIC_DEFAULT_HAIKU_MODEL",
  "value": "deepseek-v4-flash"
},
{
  "name": "CLAUDE_CODE_SUBAGENT_MODEL",
  "value": "deepseek-v4-flash"
},
{
  "name": "CLAUDE_CODE_EFFORT_LEVEL",
  "value": "max"
}

各变量的含义：

• ANTHROPIC_BASE_URL：平台的 Anthropic 兼容端点。示例中写成 http://<平台地址>/v1，但具体是否包含 /v1 必须以课程平台页面的说明为准；不要把 OpenAI 兼容端点和 Anthropic 兼容端点的路径混用。
• ANTHROPIC_AUTH_TOKEN：你在平台上生成的 Key。
• ANTHROPIC_MODEL / ANTHROPIC_DEFAULT_OPUS_MODEL / ANTHROPIC_DEFAULT_SONNET_MODEL：Claude 的"主模型"（opus / sonnet 等档位）统一映射到 deepseek-v4-pro，负责主要对话。
• ANTHROPIC_DEFAULT_HAIKU_MODEL / CLAUDE_CODE_SUBAGENT_MODEL：Claude 的"小模型"（haiku 档位、子任务）映射到 deepseek-v4-flash，负责标题生成、快速补全等杂活，为额度省钱。
• CLAUDE_CODE_EFFORT_LEVEL：思考强度，设为 max 通常会消耗更多 token；建议先使用默认值，遇到确实需要深度推理的任务再提高。
• 你也可以全部设置为 deepseek-v4-pro/flash。

配置 Claude Code for VSCode

安装 Claude Code 的 VSCode 扩展后，在 VSCode 的用户设置（settings.json）中添加 claude-code.env 配置项，把上面的键值对原样粘贴进去即可：

{
  "claude-code.env": [
    { "name": "ANTHROPIC_BASE_URL", "value": "http://<平台地址>/v1" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "<你的 API Key>" },
    { "name": "ANTHROPIC_MODEL", "value": "deepseek-v4-pro" },
    { "name": "ANTHROPIC_DEFAULT_OPUS_MODEL", "value": "deepseek-v4-pro" },
    { "name": "ANTHROPIC_DEFAULT_SONNET_MODEL", "value": "deepseek-v4-pro" },
    { "name": "ANTHROPIC_DEFAULT_HAIKU_MODEL", "value": "deepseek-v4-flash" },
    { "name": "CLAUDE_CODE_SUBAGENT_MODEL", "value": "deepseek-v4-flash" },
    { "name": "CLAUDE_CODE_EFFORT_LEVEL", "value": "max" }
  ]
}

如果是命令行的 Claude Code，则在 shell 中 export 同样的环境变量（或写入 ~/.claude/settings.json 的 env 字段），效果相同。

更多参考

• 各类 Harness 的配置方式日新月异，本文档难以面面俱到。可以参考 DeepSeek API 文档 和 Claude Code 的网关配置文档，但要把其中的端点、模型名和鉴权方式与课程平台页面逐项对照，不能机械照抄。
• 进阶玩法：如果你使用 Claude Code，可以自行学习 CC Switch 工具——它提供了可视化的供应商/模型切换界面，方便你在不同供应商之间一键切换（GitHub 搜索 "cc-switch" 即可找到，文档中有详细说明）。

开始 AI 辅助编程！

一切就绪，下面是助教给你的使用建议。

一轮合格的 Agent 协作

把一次协作控制在一个能验证的闭环里：

1. 说明背景和目标：告诉 Agent 当前项目、相关文件、你已经观察到的现象，以及明确的完成条件。
2. 先让它读和计划：对于不熟悉的代码，先要求它列出调用链、假设和修改计划，暂时不要写文件。
3. 限制修改范围：一次只处理一个小问题，明确允许修改哪些文件，不要默认让它重构整个目录。
4. 运行验证并检查 diff：让 Agent 运行相关测试，但由你检查 git diff、边界条件和测试是否真的覆盖目标。
5. 复述关键结论：最后让 Agent 解释改动为什么正确；如果你无法用自己的话讲清楚，就说明这一轮还没有完成。

可以把下面的模板改成自己的问题：

背景：我正在完成 PA__，当前涉及 <文件/模块>。
现象：<报错、测试输出或我的推理>。
目标：<希望程序满足什么行为>。
约束：只允许修改 <文件>；不要改变接口；先不要写代码。
请先：梳理相关调用链，指出你需要进一步查看的文件，列出 2~3 个可能原因和验证方法。

等你看过计划并确认方向后，再让它实现一个小改动。这个模板的价值不在于格式本身，而在于逼自己先把问题说清楚。

出现问题时先定位在哪一层

配置问题优先用最小请求验证，代码问题优先用最小复现验证；不要把两类问题混在一轮对话里。

祝大家 PA 顺利！