Replit AI Proxy Build Brief

这个 README 是给新 agent 的直接执行说明。目标不是讨论方案，而是在当前 Replit pnpm monorepo 上一次性完成 OpenAI + Anthropic 双兼容反代 API、前端门户和发布准备。

工作方式

• 先阅读仓库现状，再补齐缺失实现，不要重置用户已有改动。
• 优先复用现有 artifacts/api-server，不要新建第二个 API artifact。
• 前端门户使用独立 artifact：artifacts/api-portal。
• 如果某项已经完成，只补验证和缺口，不要重复重构。

目标

在当前项目中完成以下交付：

1. 在 Replit Integrations 中接入 OpenAI 和 Anthropic。
2. 在 artifacts/api-server 下提供 /v1/models、/v1/chat/completions、/v1/messages 三个代理端点。
3. 在 artifacts/api-portal 中提供可视化 API 门户。
4. 完成 workflow 重启、接口验证、artifact 展示和部署建议。

必须执行的 Replit Agent 操作

1. 环境准备

• 调用 setupReplitAIIntegrations 添加：
  • OpenAI
  • Anthropic AI
• 这些集成会自动注入以下环境变量，不要要求用户手动提供 API Key：
  • AI_INTEGRATIONS_OPENAI_BASE_URL
  • AI_INTEGRATIONS_OPENAI_API_KEY
  • AI_INTEGRATIONS_ANTHROPIC_BASE_URL
  • AI_INTEGRATIONS_ANTHROPIC_API_KEY
• 通过 requestEnvVar 请求 Secret：
  • PROXY_API_KEY
• 如果 SESSION_SECRET 已存在则跳过，不存在时按项目既有机制补齐。

2. artifact 操作

• 用 createArtifact({ artifactType: "react-vite", slug: "api-portal", previewPath: "/", title: "API Portal" }) 创建前端门户 artifact。
• 用 verifyAndReplaceArtifactToml 更新 artifacts/api-server/.replit-artifact/artifact.toml，确保 paths 包含 "/v1"。
• 完成后执行：
  • presentArtifact({ artifactId: "artifacts/api-portal" })
  • suggestDeploy()

API Server 改造

文件

• artifacts/api-server/src/routes/proxy.ts
• artifacts/api-server/src/app.ts
• artifacts/api-server/.replit-artifact/artifact.toml
• artifacts/api-server/package.json

依赖

在 artifacts/api-server/package.json 的 dependencies 中确保存在：

• openai: ^6
• @anthropic-ai/sdk: ^0.82

app.ts 要求

确保：

app.use(express.json({ limit: "50mb" }));
app.use(express.urlencoded({ extended: true, limit: "50mb" }));
app.use("/api", router);
app.use("/v1", proxyRouter);

模型列表

GET /v1/models

• 校验 Authorization: Bearer ${PROXY_API_KEY}
• 成功时返回模型列表：

OpenAI:

• gpt-5.2
• gpt-5-mini
• gpt-5-nano
• o4-mini
• o3

Anthropic:

• claude-opus-4-6
• claude-sonnet-4-6
• claude-haiku-4-5

OpenAI 兼容接口

POST /v1/chat/completions

• 校验 Authorization: Bearer ${PROXY_API_KEY}，失败返回 401
• 根据 model 分发：
  • gpt- / o* 开头 -> OpenAI client
  • claude- 开头 -> Anthropic client

Tool Call 支持

• OpenAI：
  • 原样透传 tools
  • 原样透传 tool_choice
• Anthropic：
  • 工具格式双向转换：
    • function.parameters <-> input_schema
  • tool_choice 映射：
    • required -> any
    • 具体函数 -> { type: "tool" }

消息转换

• role: "tool" -> Anthropic tool_result 内容块
• assistant.tool_calls -> Anthropic tool_use 内容块
• function.arguments 需要解析 JSON，作为 input 对象传给 Anthropic

响应转换

• Anthropic tool_use 内容块 -> OpenAI tool_calls
• stop_reason: "tool_use" -> finish_reason: "tool_calls"

流式

当 stream=true 时：

• 设置：
  • Content-Type: text/event-stream
  • X-Accel-Buffering: no
• 调用 res.flushHeaders()
• 每 5 秒发送一次 keepalive：

: keepalive

• req.on("close") 时 clearInterval
• 用 try/finally 保证清理，避免 500

OpenAI 流：

• 直接透传 chunk
• 每块都 res.flush()

Anthropic 流：

• 把 content_block_start / content_block_delta / content_block_stop 转成 OpenAI chunk 格式
• 工具调用流式时，将 input_json_delta 转成 function.arguments 的增量
• 每块都 res.flush()

非流式

• OpenAI：直接返回原始响应
• Anthropic：内部始终使用 messages.stream().finalMessage() 缓冲
  • 原因：Anthropic 长请求非流式可能在 10 分钟后报 500
• 最终返回 OpenAI 兼容 JSON

Anthropic 原生接口

POST /v1/messages

• 同样校验 Authorization: Bearer ${PROXY_API_KEY}
• 接受 Anthropic Messages API 原生请求格式：
  • system
  • messages
  • tools
  • tool_choice
  • max_tokens
  • stream

Claude 模型

• 直接透传到 Anthropic
• 非流式仍使用 stream().finalMessage()
• 流式转发所有原生 SSE 事件：
  • message_start
  • content_block_start
  • content_block_delta
  • content_block_stop
  • ping
  • message_delta
  • message_stop

OpenAI 模型

• 消息格式转换：
  • Anthropic messages -> OpenAI messages
  • tool_result -> role: "tool"
  • tool_use -> tool_calls
• 工具格式转换：
  • input_schema -> parameters
• tool_choice 做双向映射
• 响应格式转换：
  • OpenAI response -> Anthropic Message 格式
  • 包含 content[]
  • 包含 stop_reason
  • 包含 usage.input_tokens/output_tokens

OpenAI -> Anthropic SSE 合成

当 /v1/messages 使用 OpenAI 模型且 stream=true 时：

• 合成完整 Anthropic SSE 事件序列
• 必须支持工具调用块：
  • content_block_start with type: "tool_use"
  • input_json_delta

前端门户

创建方式

使用：

createArtifact({
  artifactType: "react-vite",
  slug: "api-portal",
  previewPath: "/",
  title: "API Portal",
})

UI 约束

• 文件：artifacts/api-portal/src/App.tsx
• 只用纯内联样式
• 深色主题主背景：hsl(222,47%,11%)
• 不依赖外部 UI 组件库

页面内容

Header

• 图标
• 标题
• 在线状态指示器
  • 通过 fetch("/api/healthz") 检测
  • 绿色/红色状态点
  • 带光晕效果

Connection Details

• 展示 Base URL：window.location.origin
• 展示 Auth Header 使用说明
• 两项都要有复制按钮

API Endpoints

列出三个端点：

• GET /v1/models
• POST /v1/chat/completions
• POST /v1/messages

每个端点都要展示：

• METHOD badge
  • GET 绿色
  • POST 紫色
• 完整 URL
• 接口类型标签
  • OpenAI 蓝色
  • Anthropic 橙色
  • 两者兼容灰色
• 复制按钮
• 说明文字，清楚区分 OpenAI 兼容格式和 Anthropic 原生格式

Available Models

• Grid 布局
• 每个 model 展示：
  • 模型 ID
  • 提供商标签
    • OpenAI 蓝色
    • Anthropic 橙色

CherryStudio 指引

提供 4 步设置说明：

• 圆形序号
• 渐变色
• 标题
• 描述

第 2 步必须注明：

• 提供商类型可选 OpenAI 或 Anthropic

Quick Test

• 提供 curl 示例
• 代码块有语法高亮风格
• 整块可复制

复制交互

• 使用 navigator.clipboard.writeText
• 提供 fallback
• 复制成功后显示 "Copied!"，持续 2 秒

Footer

• 展示技术栈说明

发布与验证

workflow

重启：

• artifacts/api-server: API Server
• artifacts/api-portal: web

验证

必须验证：

curl localhost:80/v1/models -H "Authorization: Bearer $PROXY_API_KEY"

预期：

• 返回模型列表

还要验证：

curl localhost:80/v1/models

预期：

• 返回 401

完成标准

以下条件全部满足才算完成：

1. /v1/models、/v1/chat/completions、/v1/messages 可用。
2. OpenAI 和 Anthropic 两种格式都可通过同一反代访问。
3. Tool call 在非流式和流式都能工作。
4. /v1 已加入 API artifact 路由。
5. API Portal 可访问并展示模型、端点、认证说明和 curl 示例。
6. 已完成 artifact 展示和 deploy 建议。
7. 已执行 curl 验证，并在最终回复中说明结果。

建议执行顺序

1. 读取并理解现有 artifacts/api-server 和 artifacts/api-portal 状态。
2. 先完成环境和 Secret。
3. 再完成 API server 代理逻辑。
4. 然后补齐 API portal 页面。
5. 更新 artifact 配置与依赖。
6. 重启 workflow 并验证。
7. 展示 artifact 并给出部署建议。

给新 Agent 的最终回复要求

• 直接说明做了什么。
• 明确列出是否已完成：
  • 集成
  • Secret
  • API 路由
  • 前端门户
  • 验证
  • 发布建议
• 如果有未完成项，必须指出卡点和下一步。