第 1 课：Coding Agent 产品解剖

结论

高级 coding agent 不是“一个更会写代码的模型”，而是模型外面的一整套工程 harness。模型负责理解任务、规划和生成意图；harness 负责把这些意图接到代码库、上下文、工具、权限、会话、证据和交付物。

入口问题

当用户说“帮我修这个 bug 并提交 PR”时，系统到底要完成哪些工程动作，而不只是生成一段回答？

心智模型

• 模型层负责理解问题、生成下一步和决定是否调用工具。
• Agent loop 层负责把 assistant message、tool call、tool result 组织成一轮或多轮执行。
• Harness 层负责文件系统、终端命令、Git、权限、上下文、trace 和 session。
• 产品形态层决定它是终端协作、云端任务、IDE 插件还是 headless 服务。

源码推演（省略版）

下面不是完整源码，而是把本课主线压缩成可以在文档里直接阅读的关键形状。读者即使不打开本地源码，也应该能看出运行时如何组织职责。

type CodingAgent = {
  model: ModelAdapter;
  loop: AgentLoop;
  harness: EngineeringHarness;
  delivery: DeliveryChannel;
};

async function handleTask(task: UserTask) {
  const context = await harness.loadContext(task);
  const plan = await model.reason({ task, context });
  const evidence = await loop.run({ plan, tools: harness.tools });
  return delivery.package({ evidence, diff: harness.currentDiff() });
}

• 这段省略版源码故意把模型和 harness 分开：model.reason() 只产生意图，真正接触仓库的是 harness。
• loop.run() 是产品能力的分界点：没有工具、权限和证据，它就只是聊天；接上这些边界后才是 coding agent。
• 后续课程读 Pi 时，可以一直用这个模型判断某个能力属于哪一层。

课堂练习

把任意一个 coding agent 产品拆成四层，说明每层解决的问题和缺失后的后果。

掌握标准

• 能区分模型能力和工程 harness 能力。
• 能解释为什么 trace、权限、session、工具和交付链路不应该只靠 prompt。
• 能用运行位置、工具边界、上下文来源、交付物和可观测性拆解一个新产品。

课后习题

1. 实践题：基于本课的省略版源码，补出一个最小实现草图，要求写清输入、输出、副作用和错误处理。
2. 思考题：本课机制如果只靠 prompt 约束，而不放进 harness 或 runtime，会出现什么工程风险？