使用 Agent 模式构建您的第一个应用
本指南是一个总结性演练，串联了本系列中涵盖的所有内容。你将使用“代理优先”开发模式，从零开始构建一个 URL 缩短器。我们将使用 FastAPI 构建 API，使用 Python 的 sqlite3 作为数据库，搭配简单的 HTML 前端，并引用本系列前面提到的 base62 编码器。
你将亲眼见证模型选择器、规划代理、自动驾驶、文件变更视图、会话分叉以及代理调试日志是如何协同运作的。
选择合适的模型
对于跨越多个文件（数据库模式、API 路由、前端及它们之间的集成）的项目，请将思维强度（thinking effort）设置为“高”。在编写代码之前，模型会对各部分如何衔接进行更深入的推理。
打开一个新的聊天会话，点击模型选择器，并将思维强度设置为“高”。
使用规划代理（Plan agent）进行规划
对于涉及多个动态部件的项目，请先使用规划代理。它会强制代理在编写代码之前生成结构化大纲并提出设计问题。
切换到规划代理，并使用如下详细的提示词：
Build a URL shortener with FastAPI, Python's built-in sqlite3, and a simple HTML frontend served by FastAPI StaticFiles. Use uv for project management with Python 3.13. Use the existing base62 encoder in main.py to generate short codes from the database row ID. The API needs two endpoints. POST /shorten accepts a JSON body with a url field and returns the short code. GET /{code} redirects to the original URL. The frontend is a single index.html with a form to submit URLs and a section that displays the shortened link. Keep it minimal.
此提示词明确了框架、数据库方案、具体端点、项目管理工具，并引用了现有代码。具体的提示词能为规划代理划定清晰的边界。
审查计划
预期计划会将工作分解为多个阶段，例如使用 uv 进行项目设置、将 base62 编码器提取到独立模块、构建 sqlite3 数据库层、配置 API 端点、创建 HTML 前端以及进行验证。
它还可能在“进一步考虑”部分提出设计问题，例如是否保留命令行界面（CLI）、重复的 URL 是否应获得相同的短码、以及在缩短前是否验证 URL。在开始实施之前，请直接解决这些问题。
直接回答这些问题，例如：
Drop the CLI, we don't need it anymore. New short code each time and yes add URL validation.
三个清晰的回答，没有歧义。在编写任何代码之前，设计问题已得到解决。
移交给代理模式（Agent mode）
审查计划后，你可以选择以下三种选项之一：
| 选项 | 功能说明 |
|---|---|
| 开始实施 | 以默认批准方式开始构建。 |
| 通过自动驾驶开始 | 使用自动驾驶开始构建。 |
| 在编辑器中打开 | 将计划保存为文件，以便手动参考。 |
对于已经过审查且范围明确的计划，自动驾驶通常是正确的选择。
观察自动驾驶（Autopilot）的工作过程
即使在自动驾驶模式下，每个操作都会在聊天面板中显示为工具调用。
典型的构建序列如下所示：
- 创建一个待办事项列表以跟踪进度。
- 运行
uv add fastapi uvicorn[standard]以安装依赖项。 - 将
main.py重命名为base62.py，并仅保留编码和解码逻辑。 - 并行创建
database.py、app.py、static/index.html和.gitignore。 - 在后台启动服务器。
- 运行验证脚本以端到端测试端点。
自动驾驶在多步骤设置中表现出色，因为代理可以安装依赖、创建文件、启动服务并验证结果，而无需为每一步暂停以等待批准。验证步骤非常重要。一个强大的代理运行不会止步于文件编写，它会在标记任务完成前对应用程序进行端到端验证。
检查上下文窗口
在会话过程中打开上下文窗口指示器，并将其与早期的单文件会话进行比较。
- 系统信息（工具定义和指令）保持大致不变。
- 随着规划消息、工具结果和服务器日志的积累，用户上下文会逐渐增长。
如果预算已满，请运行 /compact 来总结对话历史，或者开启一个新的会话，并引用之前的会话以获取上下文。
审查变更文件
构建完成后，“变更文件”栏会显示代理创建或修改的每个文件。
仔细审查每个文件。
base62.py：从原始文件中干净利落地提取了编码和解码逻辑。app.py：包含POST /shorten、GET /{code}和GET /的 FastAPI 应用程序。database.py：用于存储和查找 URL 的sqlite3辅助工具。static/index.html：包含表单、结果部分和 JavaScript。
使用箭头控件浏览编辑内容。根据需要撤销单个更改，或者在一切看起来正确时选择全部保留。
在现有的应用程序上进行迭代
核心应用运行正常后，通过有针对性的后续提示词进行迭代。
Add a lookup section to the frontend and a GET /lookup/{code} endpoint that returns the original URL as JSON instead of redirecting. The frontend should have a second form where I paste a short code and see the original URL displayed below it.
代理应仅更新相关文件，而不是重建整个项目。
通过分叉（Forking）探索不同方向
在添加查找功能后，先分叉会话，然后再探索测试套件。
在分叉后的会话中使用如下提示词：
Add a test suite using pytest. Test the base62 encode/decode functions and the API endpoints including /lookup/{code}, using FastAPI TestClient. Use uv to add pytest and httpx as dev dependencies.
原始会话在“代理会话”侧边栏中保持不变。现在有了两个分支：一个用于功能开发，一个用于测试。
在实践中，这是分叉的强大应用。它实现了关注点分离：在一个对话分支中进行功能工作，在另一个分支中进行测试，每个分支都从相同的已知良好检查点开始。
阅读代理调试日志
自动驾驶运行后，打开代理调试日志。
- 日志视图显示了事件序列、自定义加载、LLM 请求、工具调用、终端命令、并行文件创建和验证过程。
- 摘要视图显示了模型轮次、工具调用、令牌（tokens）和事件的总数。
- 代理流程图可视化展示了会话的结构。
在分叉后拥有两个会话的情况下，可以并排比较日志。
你还可以附加调试快照并询问直接问题，例如 #debugEventsSnapshot 这个会话进行了多少次工具调用？
你构建的内容
你通过“代理优先”开发模式成功构建了一个可用的 URL 缩短器。
- 针对多文件项目，使用高思维强度的模型选择器。
- 使用规划代理在编码前勾勒架构。
- 使用自动驾驶无中断地构建应用程序。
- 使用代理调试日志检查执行过程。
- 使用上下文窗口指示器监控预算。
- 使用“变更文件”视图审查并接受编辑。
- 通过后续提示词扩展应用程序。
- 通过分叉在不丢失功能工作的情况下创建测试套件。
你的挑战
创建我们在本系列中构建的 URL 缩短器，利用我们用过的提示词（或者发挥你的创意！），然后对其进行扩展。
创意建议：
- 自定义后缀（Custom slugs），以便用户选择自己的短码。
- 过期日期，自动禁用旧链接。
- 分析页面，按点击次数显示热门 URL。
使用规划代理来限定工作范围，使用代理模式进行构建，并检查代理调试日志以了解代理的操作。
完成时，打开上下文窗口指示器并查看会话统计信息，看看工作量如何影响了你的上下文预算。
这就是“代理优先”开发的基础：协调、模型、上下文、工具、提示词。这五者协同工作。练习越多，效果越好。
敬请关注后续章节，涵盖 MCP、自定义指令与技能以及更高级的代理模式。祝编码愉快！