如何构建一个能够写入文件并部署应用的 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 继续负责持久化的产品状态，应用程序的其他部分已经能够显示这些状态。

针对这一具体集成的生产环境检查清单