使用 IBM Bob 进行 AI 结对编程

启动 IBM Bob

启动 IBM Bob IDE。

打开 Bob 聊天界面

如果 Bob 聊天界面不可见，请通过选择导航栏旁边的 Bob 图标将其打开。你也可以在 Mac 上按 Option + Command + B，或在 Windows 和 Linux 上按 Ctrl + Alt + B。

打开空项目文件夹

创建一个名为 todo-api 的空文件夹，然后通过 File > Open Folder 在 Bob 中打开它。如果 Bob 询问你是否信任该文件夹中文件的作者，请选择 Yes, I trust the authors。

Bob 会将生成的应用程序写入此文件夹。本教程不需要已有的代码仓库。

禁用自动批准

打开 Permissions 并确认自动批准已关闭。关闭自动批准后，Bob 在读取文件、编辑文件或运行命令之前会请求你的许可。你可以掌控本教程中的每一项更改。

切换到 Plan 模式

打开 Bob 侧边栏底部的模式下拉菜单，然后选择 Plan。

Modes 遵循最小权限原则。在 Plan 模式下，Bob 读取你的代码并编写 Markdown 计划。Bob 不运行命令，也不做实现层面的更改。你在 Bob 编写任何应用程序代码之前审查方案。

定义应用程序需求

在 Bob 聊天界面中，输入以下提示：

Create a simple FastAPI To-Do API.

Requirements:

- Store tasks in a Python list.
- Each task should contain:
    - id
    - task_name

Implement these endpoints with explicit HTTP status codes:

- GET /tasks: list all tasks. Return 200.
- POST /tasks: create a task from a JSON body containing only task_name. Return 201 with the created task.
- DELETE /tasks/{task_id}: delete a task. Return 204 on success and 404 if no task has that id.

Use FastAPI and Pydantic. Use Pydantic model validation so an invalid request body returns 422.

Include a requirements.txt and a Dockerfile. The Dockerfile must start Uvicorn bound to 0.0.0.0 on port 8000 so the API is reachable through a published container port.

Save the plan as Markdown files in a folder named `plans`.

Put the FastAPI application in a single file named `main.py` at the project root.

Keep the implementation simple.

Don't install any dependencies locally or run local tests. Everything will run in a Docker container.

为了制定计划，Bob 会运行其规划 skill。出现提示时，选择 Approve skill tools for task 和 Approve subagent tools for task，让 Bob 能够研究工作区并起草计划。

完善计划

你可以在 Bob 编写任何代码之前修改计划。在 Bob 聊天界面中，输入后续提示：

Update the plan to reject a task whose task_name is empty or longer than 200 characters.

Bob 会修订计划，加入额外的输入验证。查看更新后的计划。

审查计划

Bob 会呈现一个有序计划，并可能将其作为 Markdown 文件保存到项目中。在继续之前请仔细审查：

• 范围： 计划涵盖你要求的每个端点和添加的验证规则，且没有你未要求的内容。
• 命名文件： 每个步骤都指明了它创建或更改的文件。
• 模糊语言： "适当处理错误"之类的表述隐藏了假设。请让 Bob 将其具体化。

你对这些设计决策负责。Bob 在你切换到 Agent 模式（见生成并审查应用程序）之前不会实现任何内容。

开启新的上下文窗口

在聊天框中选择 New task 或聊天面板顶部的 +，以开始新的上下文窗口。有关背景信息，请参阅创建新的上下文窗口。Bob 已将计划保存到 plans 文件夹，因此你不再需要在上下文中保留规划对话。干净的上下文让实现专注于已批准的计划。

切换到 Agent 模式并执行计划

打开 Bob 侧边栏底部的模式下拉菜单，然后选择 Agent。接着告诉 Bob 实现计划：

Implement the plan in the plans folder.
@plans/

Agent 模式允许 Bob 编写文件并运行命令。由于你禁用了自动批准，Bob 在每次更改之前会请求批准。在 Bob 执行计划时批准各个步骤。

审查生成的应用程序

实现完成后，审查生成的代码。由于 Bob 的输出具有概率性，你的代码风格和内部名称可能与此处示例有所不同。该应用程序由以下部分组成。

数据模型。 Bob 生成两个 Pydantic 模型：一个用于创建任务时的请求体，另一个用于已存储的任务。创建模型会强制执行你在规划阶段添加的长度规则：

class TaskCreate(BaseModel):
    task_name: Annotated[str, Field(min_length=1, max_length=200)]


class Task(BaseModel):
    id: int
    task_name: str

端点路径和状态码与你给 Bob 的需求一致，但模型类名和文件布局可能有所不同。本教程假设模型名称为 Task 和 TaskCreate。如果 Bob 选择了不同的名称，请相应调整后续提示。

内存数据存储。 Bob 将任务存储在一个空的 Python 列表中，并为每个新任务分配递增的 id：

tasks: list[dict] = []
id_counter = 0

API 操作。 应用程序提供以下端点：

• GET /tasks
• POST /tasks
• DELETE /tasks/{task_id}

POST /tasks 仅接受请求体中的 task_name，并以 201 状态码返回已创建的任务。DELETE /tasks/{task_id} 成功时返回 204，当不存在该 task_id 时返回 404。

依赖项。 Bob 生成一个列出 FastAPI、Uvicorn 和 Pydantic 的 requirements.txt 文件。

容器。 Bob 生成一个 Dockerfile，用于安装依赖项并通过 Uvicorn 在端口 8000 上运行 API。

HTTP 契约遵循需求提示，包括方法、路径和状态码。以下验证步骤按原样适用。

打开应用程序文件

打开 Bob 生成的 main.py 文件，并将光标放在文件末尾最后一个路由处理程序之后的空行上。

激活文学编程模式

在 Mac 上按 Command + I，或在 Windows 和 Linux 上按 Ctrl + I。你也可以选择编辑器工具栏中的魔法棒图标。

编写指令

在空行上输入以下指令。它会以与其余代码不同的颜色高亮显示。

Add a PUT /tasks/{task_id} endpoint that updates the task_name of an existing task, matching the style and conventions of the existing routes. Return 200 with the updated task, or 404 if no task has that id.

Bob 会从周围的代码推断参数名称、请求模型和错误处理，因此你只需指定方法和路径。

生成并接受代码

选择 Generate，或在 Mac 上按 Command + Enter，或在 Windows 和 Linux 上按 Ctrl + Enter。Bob 会用实现替换你的指令，并显示内联差异。

审查差异后，选择 Accept All 以应用更改。再次在 Mac 上按 Command + I，或在 Windows 和 Linux 上按 Ctrl + I，退出文学编程模式。

请 Bob 解释代码

用 New task 开启新的上下文窗口，然后从模式下拉菜单中选择 Ask。Ask 模式在不编辑文件的情况下回答问题和分析代码。当你希望获得解释而不做更改时，请使用它。

理解生成的代码是 AI 结对编程的重要组成部分。请问 Bob：

Explain the generated To-Do API.

Bob 可以解释应用程序架构、数据流、FastAPI 组件、Pydantic 模型、端点行为和设计决策。使用这些解释在修改或扩展代码之前，确认代码确实符合你的预期。

运行应用程序

切换回 Agent 模式，让 Bob 能够运行命令。请 Bob 在容器中构建并运行 API：

Build the Docker image and run the container with port 8000 mapped to the host. Confirm the API is reachable.

Bob 会运行构建和启动命令，并在容器运行时报告结果。

在浏览器中打开 http://localhost:8000/docs。

FastAPI 会在 /docs 提供交互式 Swagger UI。使用它来探索每个端点、检查请求和响应 schema，以及从浏览器运行 API 调用。

验证 API

使用 /docs 处的 Swagger UI 对每个操作进行测试。对于每个端点：

1. 展开其行并选择 Try it out。
2. 输入任何路径参数或请求体。
3. 选择 Execute。
4. 检查服务器响应代码和响应体。

添加任务

1. 展开 POST /tasks 并选择 Try it out。

2. 将请求体替换为：

   {
     "task_name": "My first API item!"
   }

3. 选择 Execute。确认响应代码为 201，响应体显示已分配 id 的已创建任务。

获取任务

1. 展开 GET /tasks 并选择 Try it out。
2. 选择 Execute。确认响应代码为 200，响应体列出了任务 My first API item! 及其在添加时分配的 id。

更新任务

1. 展开 PUT /tasks/{task_id} 并选择 Try it out。

2. 输入你创建的任务的 task_id。

3. 将请求体替换为：

   {
     "task_name": "Build and ship a To-Do API"
   }

4. 选择 Execute。确认响应代码为 200，返回的任务显示更新后的 task_name。

5. 将 task_id 更改为不存在的值，再次选择 Execute。确认响应代码为 404。

删除任务

1. 展开 DELETE /tasks/{task_id} 并选择 Try it out。
2. 输入你创建的任务的 task_id，然后选择 Execute。确认响应代码为 204。
3. 展开 GET /tasks，选择 Execute，并确认该任务不再出现在响应中。
4. 再次展开 DELETE /tasks/{task_id}，输入相同的 task_id，然后选择 Execute。确认响应代码为 404。

该实现满足原始需求，包括你通过文学编程添加的更新端点。

请 Bob 提出改进建议

用 New task 开启新的上下文窗口，然后输入：

Review the To-Do API and suggest improvements to code quality, error handling, and HTTP status codes.

Bob 会识别问题，例如缺少用于获取单个任务的端点、内存存储使用普通字典而非经过验证的 Task 模型，以及模块级 id_counter 难以重置或测试。

应用改进

请 Bob 实现你想保留的建议：

Add a GET /tasks/{task_id} endpoint that returns 404 when the task ID does not exist, and store tasks as Task models instead of dictionaries.

审查提议的更改并批准以应用它们。请 Bob 重新构建镜像并重启容器，然后重复验证步骤。确认 GET /tasks/{task_id} 对有效 ID 返回 200 及相应任务，对未知 ID 返回 404，并且现有端点的行为与之前相同。

生成单元测试

用 New task 开启新的上下文窗口，然后请问 Bob：

Generate pytest unit tests for this application. Add pytest and httpx to a dev requirements file, build a test image, and run the suite in a container.

Bob 会添加 pytest 和 httpx 测试依赖项，构建包含这些依赖项的镜像，在容器中运行测试套件，并报告结果。在容器中运行测试意味着你不需要本地 Python 环境。审查并完善生成的测试。

审查和维护生成的测试仍是你的责任。

生成技术文档

请问 Bob：

Generate technical documentation for this To-Do API.

Bob 可以生成应用程序概述、架构描述、端点摘要、请求和响应示例以及使用说明。此文档补充了 FastAPI 自动生成的 API 文档。