與 IBM Bob 進行 AI 協同程式設計

啟動 IBM Bob

啟動 IBM Bob IDE。

開啟 Bob 聊天介面

如果 Bob 聊天介面不可見，請選取導覽列旁的 Bob 圖示來開啟它。你也可以在 Mac 上按 Option + Command + B，或在 Windows 和 Linux 上按 Ctrl + Alt + B。

開啟空的專案資料夾

建立一個名為 todo-api 的空資料夾，然後在 Bob 中選擇 File > Open Folder 開啟它。如果 Bob 詢問你是否信任資料夾中檔案的作者，請選取 Yes, I trust the authors。

Bob 會將產生的應用程式寫入此資料夾。本教學不需要現有的 repository。

停用自動核准

開啟 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 模式之前不會實作任何內容。

開始新的 context window

在聊天框中選取 New task 或在聊天面板頂端點擊 +，開始全新的 context window。參閱建立新的 context window 了解背景說明。Bob 已將計畫儲存在 plans 資料夾中，因此你不再需要將規劃對話保留在 context 中。乾淨的 context 讓實作聚焦於已核准的計畫。

切換到 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 產生安裝相依套件並以 Uvicorn 在連接埠 8000 執行 API 的 Dockerfile。

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 會以實作取代你的指令，並顯示行內 diff。

審查 diff 後，選取 Accept All 套用變更。再次在 Mac 上按 Command + I，或在 Windows 和 Linux 上按 Ctrl + I，離開文學式程式設計模式。

請 Bob 解說程式碼

以 New task 開始新的 context window，然後從模式下拉選單選取 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. 檢查 Server response 的代碼和主體。

新增任務

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 開始新的 context window，然後輸入：

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 開始新的 context window，然後詢問 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 說明文件。