如何建置一個能夠寫入檔案並部署應用程式的 AI 程式設計代理

本指南為 SaaS 程式碼建置器建立一個具體的參考整合。使用者在聊天中要求建立應用程式後，AgentChat 會讀取已配置的 API 契約，透過 SaaS API 寫入專案檔案，啟動已核准的檢查、修正失敗、部署 Cloudflare Worker，並回傳預覽 URL。檔案、工作、部署、憑證以及最終專案 UI 的所有權仍由程式碼建置器負責，而不是 AgentChat。

AgentChat 在此工作流程中提供的功能

AppForge 不會為 create_directory、write_file、run_build 和 deploy_worker 實作個別的模型工具，而是將這些操作作為一般 HTTP API 發布，並在 AgentChat 中註冊一份準確的 API 文件。任何附加這份文件的聊天，都能透過內建的 http_request 工具取得完整的程式碼開發功能套件。

AgentChat負責非同步推理迴圈、持久化訊息、工具執行順序、停止與繼續行為，以及輪詢游標。AppForge負責操作及其授權。這種分離是此整合的核心設計。

第1步：公開受控的 AppForge API

業務 API 的範圍有意設計得比 shell 更窄。每個路徑都會在經過驗證的專案工作區內解析，每次變更都會回傳一個修訂版本號，而建置工作則從允許清單中選取。

GET    /v1/projects/{project_id}/tree
GET    /v1/projects/{project_id}/files?path=src/index.ts
POST   /v1/projects/{project_id}/directories
PUT    /v1/projects/{project_id}/files
DELETE /v1/projects/{project_id}/files?path=src/old.ts
POST   /v1/projects/{project_id}/checks
GET    /v1/checks/{job_id}
POST   /v1/projects/{project_id}/deployments
GET    /v1/deployments/{deployment_id}

AppForge會驗證使用者權杖、確認專案成員資格、拒絕路徑遍歷、限制檔案大小，並在隔離環境中執行檢查。Cloudflare 憑證會保留在 AppForge 內部。這些機密資訊都不會寫入 API 文件。

第2步：撰寫代理程式實際接收的文件

文件不能只包含端點名稱，還必須說明安全的操作順序、請求欄位、回應欄位、非同步輪詢以及錯誤復原方式。以下這份精簡契約包含會改變代理行為的規則。

# AppForge Project API

Base URL: https://builder.example.com/v1

All paths are relative to the project workspace. Never use absolute paths or ../.

## Read project tree
GET /projects/{project_id}/tree
Returns entries with path, type, revision, and bytes. Read the tree before editing.

## Write complete file
PUT /projects/{project_id}/files
Body: path, content, expected_revision.
For a new file omit expected_revision. For an existing file, read it first and send its revision.

## Run approved check
POST /projects/{project_id}/checks
Body task is one of format, typecheck, test, build.
Returns job_id, status, poll_after_seconds. Start the job in one model turn. Wait and poll in a later turn.

## Read check
GET /checks/{job_id}
When failed, diagnostics contains file, line, category, and message. Fix the files and run the check again.

## Deploy validated revision
POST /projects/{project_id}/deployments
Body target=cloudflare-worker, environment=preview, revision. Only deploy the revision returned by a successful build.
Returns deployment_id and poll_after_seconds. Poll GET /deployments/{deployment_id} until succeeded or failed.

步驟 3：透過 AgentChat API 註冊該文件

AppForge 使用 AgentChat 使用者 API 金鑰從其後端執行此佈建。content 欄位包含上述完整契約，而不只是文件連結。

curl -X POST "$AGENT_CHAT_URL/api/api-documents" 
  -H "Authorization: Bearer ac_live_AGENT_CHAT_KEY" 
  -H "Content-Type: application/json" 
  --data '{
    "title": "AppForge Project and Deployment API",
    "description": "Read and modify a scoped project, run approved checks, and deploy a validated revision.",
    "content": "# AppForge Project API\n\nBase URL: https://builder.example.com/v1\n...complete contract..."
  }'

回應會傳回產生的文件 ID。AppForge 將此 ID 儲存為其程式設計代理體驗的設定。之後更新已註冊的文件，會變更後續聊天回合可用的指示，而不必將該文件複製到每個工作階段中。

{ "success": true, "data": { "id": "doc_uuid", "title": "AppForge Project and Deployment API" } }

步驟 4：為目前的專案使用者建立一個 AgentChat 工作階段

當 AppForge 使用者開啟編碼助理時，AppForge 後端會建立工作階段。該工作階段會繫結所選的 LLM 設定、專案 API 文件、執行限制，以及只能存取目前使用者專案的短期憑證。

curl -X POST "$AGENT_CHAT_URL/api/agent/sessions" 
  -H "Authorization: Bearer ac_live_AGENT_CHAT_KEY" 
  -H "Content-Type: application/json" 
  --data '{
    "title": "Build project prj_42",
    "llm_config_id": "llm_config_uuid",
    "api_document_ids": ["doc_uuid"],
    "system_prompt": "You are the coding agent for project prj_42. Make focused changes, validate them, and deploy only after build succeeds.",
    "max_turns": 30,
    "tool_timeout_seconds": 120,
    "tool_result_max_chars": 20000,
    "host_headers": [
      { "host": "builder.example.com", "header_key": "Authorization", "header_value": "Bearer short_lived_project_token" },
      { "host": "builder.example.com", "header_key": "X-Project-ID", "header_value": "prj_42" }
    ]
  }'

標頭值為唯寫值。AgentChat 僅在 HTTP 工具呼叫相符的主機時注入這些值，而模型永遠不會接收到這些值。如果重新導向變更了主機，系統會再次進行比對，因此專案憑證不會被帶到其他服務。

步驟 5：開始編碼執行

curl -X POST "$AGENT_CHAT_URL/api/agent/sessions/session_uuid/chat" 
  -H "Authorization: Bearer ac_live_AGENT_CHAT_KEY" 
  -H "Content-Type: application/json" 
  --data '{ "message": "Create a feedback form as a Cloudflare Worker. Store submissions in the existing FEEDBACK KV binding, add validation, run the build, and deploy a preview." }'

端點會立即以 processing 狀態回傳。模型撰寫程式碼時，SaaS 請求不會保持開啟。AgentChat 取得 processing 鎖定，並以非同步方式繼續執行。

{ "success": true, "data": { "session_id": "session_uuid", "state": "processing" } }

代理程式對已佈建文件執行的操作

1. 透過 http_request 讀取專案樹狀結構和現有設定。
2. 讀取必須保留的檔案，包括其目前的修訂版本。
3. 透過 AppForge API 建立目錄，並寫入 Worker 原始碼、驗證邏輯和設定。
4. 啟動已核准的建置工作。由於同一個模型回應中的工具呼叫會並行執行，因此代理程式會在獨立的回合中等待，然後再輪詢工作。
5. 讀取結構化診斷資訊。如果建置失敗，請更新確切的檔案並重複檢查。
6. 將成功的修訂提交至部署端點，等待片刻，然後在後續回合中輪詢部署狀態。
7. 返回預覽 URL 和一份簡潔的已變更檔案清單。

每個可見步驟都會以助理訊息或工具訊息的形式持久化。如果使用者停止執行或達到最大回合預算，AppForge 可以稍後呼叫 continue，而 AgentChat 會從持久化歷史記錄中恢復。

步驟 6：從 AppForge 前端輪詢持久化訊息

AppForge 每秒輪詢一次，並保留最後一則訊息的 ID 和修訂版本。串流中的助理列在修訂版本增加時仍會維持相同的 ID，因此用戶端會取代該列，而不是附加重複項目。

GET /api/agent/sessions/session_uuid/messages?after_id=last_message_uuid&after_revision=4
Authorization: Bearer ac_live_AGENT_CHAT_KEY

→ {
  "success": true,
  "data": {
    "messages": [{ "id": "msg_uuid", "role": "assistant", "content": "Build passed...", "stream_status": "streaming", "revision": 5 }],
    "last_id": "msg_uuid",
    "last_revision": 5,
    "is_processing": true,
    "total_tokens": 8421
  }
}

AppForge 瀏覽器應呼叫自身的後端或範圍嚴格受限的代理，而不是接收長期有效的 AgentChat API 金鑰。後端會將 AppForge 使用者和專案對應至正確的 AgentChat 工作階段。

步驟 7：從 AppForge 資料顯示已部署的應用程式

部署 API 會將 deployment_id、project_id、revision、status 和 preview_url 寫入 AppForge 資料庫。AgentChat 完成後，現有的部署面板會讀取該資料表並顯示預覽。聊天訊息是有用的回饋，但不是系統的正式資料來源。

這就是此模式能夠順利擴充的原因：AgentChat 負責協調操作，而 AppForge 繼續負責持久化的產品狀態，應用程式的其他部分早已知道如何顯示這些狀態。

針對這項特定整合的正式環境檢查清單