Add setup guide

This commit is contained in:
hwhung
2026-04-27 03:23:03 +08:00
parent 3c9a74fe37
commit 0bcbc07eeb
+117
View File
@@ -0,0 +1,117 @@
# Setup Guide (for future Replit Agents)
A short, copy-paste-friendly checklist to get this project running from a clean clone. Read this **before** restarting workflows or asking the user for credentials.
## What this project is
A pnpm monorepo with three artifacts:
| Artifact | Path | Port | Purpose |
| --- | --- | --- | --- |
| `api-server` | `artifacts/api-server` | `8080` | Express server. `/api/*` (health) + `/v1/*` OpenAI-compatible reverse proxy in front of OpenAI and Anthropic. |
| `api-portal` | `artifacts/api-portal` | `24927` | React + Vite frontend that shows connection info and CherryStudio setup. |
| `mockup-sandbox` | `artifacts/mockup-sandbox` | `8081` | Vite dev server for component previews. |
The proxy exposes `GET /v1/models` and `POST /v1/chat/completions`. Model variants are auto-generated by suffixing the base id with a reasoning effort, e.g. `gpt-5.2-low`, `claude-opus-4-6-high`. For Anthropic models the suffix maps to `thinking.budget_tokens`.
## Workflows (already configured in `.replit-artifact/artifact.toml` per artifact)
- `artifacts/api-portal: web` → `pnpm --filter @workspace/api-portal run dev`
- `artifacts/api-server: API Server` → `pnpm --filter @workspace/api-server run dev`
- `artifacts/mockup-sandbox: Component Preview Server` → `pnpm --filter @workspace/mockup-sandbox run dev`
Do **not** edit `artifact.toml` directly — use the artifacts skill helpers (`createArtifact`, `verifyAndReplaceArtifactToml`).
## Required env vars / secrets
The api-server instantiates the OpenAI and Anthropic SDKs at import time. If any of these are missing it crashes immediately on startup with `OpenAIError: Missing credentials` or similar.
| Name | How to set | Notes |
| --- | --- | --- |
| `AI_INTEGRATIONS_OPENAI_BASE_URL` | `setupReplitAIIntegrations({ providerSlug: "openai", ... })` | auto-set |
| `AI_INTEGRATIONS_OPENAI_API_KEY` | same call | auto-set (dummy string for SDK; works alongside BASE_URL) |
| `AI_INTEGRATIONS_ANTHROPIC_BASE_URL` | `setupReplitAIIntegrations({ providerSlug: "anthropic", ... })` | auto-set |
| `AI_INTEGRATIONS_ANTHROPIC_API_KEY` | same call | auto-set |
| `PROXY_API_KEY` | `requestEnvVar({ requestType: "secret", keys: ["PROXY_API_KEY"] })` | user-defined; bearer token clients send |
## One-shot setup script (in the JS sandbox)
```javascript
// 1. Provision OpenAI + Anthropic via Replit AI Integrations
await setupReplitAIIntegrations({
providerSlug: "openai",
providerUrlEnvVarName: "AI_INTEGRATIONS_OPENAI_BASE_URL",
providerApiKeyEnvVarName: "AI_INTEGRATIONS_OPENAI_API_KEY",
});
await setupReplitAIIntegrations({
providerSlug: "anthropic",
providerUrlEnvVarName: "AI_INTEGRATIONS_ANTHROPIC_BASE_URL",
providerApiKeyEnvVarName: "AI_INTEGRATIONS_ANTHROPIC_API_KEY",
});
// 2. Ask the user for their proxy bearer token (suggest a random one)
const crypto = await import("node:crypto");
const suggested = crypto.randomBytes(24).toString("base64url");
await requestEnvVar({
requestType: "secret",
keys: ["PROXY_API_KEY"],
userMessage: `Bearer token for /v1/* on the proxy. Suggested: ${suggested}`,
});
```
Then in the shell:
```bash
pnpm install
```
And restart all three workflows (in any order).
## Verification
```bash
# health
curl -s http://localhost:8080/api/healthz
# → {"status":"ok"}
# auth gate
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/v1/models
# → 401
# model list (replace with your secret)
curl -s -H "Authorization: Bearer $PROXY_API_KEY" http://localhost:8080/v1/models | head -c 200
# portal
curl -s http://localhost:24927/ | head -c 80
# → <!DOCTYPE html> ...
```
## Common gotchas
- **Port 8080 already in use after a crash loop.** Stale `node ./dist/index.mjs` processes from a previous failed start can hold the port. `ps -ef | grep dist/index.mjs` then `kill -9 <pid>` before restarting the workflow.
- **mockup-sandbox transient `Cannot find package 'vite'` on first start.** It's a vite restart race after `pnpm install` invalidates `.vite-temp/`. A second restart of the workflow clears it.
- **Do not edit `lib/integrations-*-server/src/client.ts`** if those packages are added later — the env-var wiring is auto-managed.
- **`PROXY_API_KEY` is a bearer token, not an OAuth secret.** It only gates `/v1/*`; pick anything. Clients send `Authorization: Bearer <PROXY_API_KEY>`.
- **Adding routes to the proxy:** the file is `artifacts/api-server/src/routes/proxy.ts`, mounted at `/v1` in `artifacts/api-server/src/app.ts`. Health/utility routes live under `artifacts/api-server/src/routes/` and are mounted at `/api`.
## File map (key paths)
```
artifacts/
api-server/
src/app.ts # express setup, mounts /api and /v1
src/routes/proxy.ts # /v1/models + /v1/chat/completions, OpenAI+Anthropic
src/routes/health.ts # /api/healthz
build.mjs # esbuild bundler
api-portal/
src/App.tsx # connection info + CherryStudio instructions
vite.config.ts
mockup-sandbox/
vite.config.ts
lib/
api-spec/openapi.yaml # OpenAPI source for codegen
api-zod/ # generated zod schemas
api-client-react/ # generated react-query hooks
db/ # drizzle schema (unused by the proxy itself)
replit.md # high-level project overview
```