The model proxy always forwarded to api.openai.com and development runs gave Codex no base URL or model, so a company model gateway could not be used. - WF_OPENAI_BASE_URL points the production proxy (and development Codex runs) at an OpenAI-compatible gateway with the Responses API; WF_ANTHROPIC_BASE_URL gives Claude Code an Anthropic-compatible one as ANTHROPIC_BASE_URL. Both are operator settings in the provider catalog, HTTPS without credentials (loopback HTTP outside production); an invalid gateway disables the proxy. - Development credentials now carry the run's model, so WF_CODEX_DEFAULT_MODEL selects a model the gateway serves. - tests/integration/real-model.test.ts (WF_REAL_MODEL_INTEGRATION=1, key from WF_TEST_MODEL_API_KEY) runs one wish through the real Codex executor, the verifier and integration into a local repository. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
8.8 KiB
本地开发
本文说明如何在本机运行完整的 WishForge 主线(提交愿望 → Agent 实现 → 独立验证 → 合入),以及如何运行测试。架构背景见 architecture.md。
1. 前置条件
- Node.js 22 或更高版本、npm、Git
- Docker 与 Docker Compose(用于 PostgreSQL、Temporal、Keycloak、MinIO 与本地镜像仓库)
- 可选:一个 OpenAI API Key,用于让 Codex 执行器真正写代码
本地执行模式(
host)没有任何隔离:Agent 生成的代码与项目的测试命令直接以你的用户身份在本机运行。只在你信任的项目和模型上使用。
2. 首次初始化
npm ci
npm run setup:local
setup:local 生成仅本地使用的 .env.local 与 apps/web/.env.local(权限 0600,已被 Git 忽略),包括随机生成的数据库密码、服务令牌与签名密钥,以及本地执行所需的配置(WF_DEPLOYMENT_MODE=development、WF_PROVISIONER_BACKEND=local、本地 provisioner 地址等)。重复执行只会补齐缺失的配置,不会覆盖已有值;升级代码后重新执行一次即可获得新增的配置项。
docker compose -f infra/compose.yaml up -d
如果你使用 Colima 等非默认 Docker context,可以加上 --context <名称>,或设置 DOCKER_CONTEXT。
npm run db:migrate
npm run db:seed
种子数据只创建本地租户 demo 和一个 owner 用户,不会伪造项目或运行记录。
3. 启动
npm run dev:all
dev:all 在本机启动以下进程,并在任一进程退出时停止它启动的全部进程:
| 进程 | 地址 | 说明 |
|---|---|---|
| Web 工作台 | http://localhost:3000 | 开发模式自动以本地 owner 身份登录 |
| 控制面 API | http://127.0.0.1:4000 | /health 检查存活;MCP 地址为 /mcp |
| 平台 Git | http://127.0.0.1:4504 | 新项目的仓库保存在 .wishforge/git |
| 本地 provisioner | http://127.0.0.1:4450 | 为每个运行代次启动 executor 与 verifier 进程(WF_SANDBOX_MODE=host) |
| coordinator worker | — | 运行 Temporal 工作流 |
| deployer worker | — | 为已构建的运行创建发布 |
Temporal 控制台在 http://127.0.0.1:8233,可以看到每个运行的工作流。
4. 跑通第一个愿望
- 打开 http://localhost:3000,进入「项目空间」,创建一个项目,仓库地址留空。平台会在本地 Git 服务上创建仓库并初始化
main分支。 - 打开「项目设置」,填写验证命令(每行一个 JSON 参数数组,例如
["node","--test"]);需要安装依赖时再填写安装命令,例如["npm","ci"]。也可以不填安装命令,改在仓库的wishforge.yaml中声明dev.install。 - 进入「执行器」,为 Codex 保存你的 OpenAI API Key。没有 Key 时,运行会停在「等待:缺少执行器凭据」。
- 也可以改用命令行执行器:CodeBuddy 需要在
.env.local中设置WF_CODEBUDDY_BIN,Claude Code 需要设置WF_CLAUDE_BIN(claude可执行文件的路径),然后在「执行器」页保存对应的 Key。 - 这两个执行器只能在开发环境使用;模型代理还不支持它们,生产中只能运行 Codex。
- 使用公司的模型网关:在
.env.local中设置下面三个变量,再在「执行器」页保存网关的 Key。WF_OPENAI_BASE_URL:Codex 使用的 OpenAI 兼容网关,需支持/responses,例如https://<网关>/v1;WF_ANTHROPIC_BASE_URL:Claude Code 使用的 Anthropic 兼容网关,例如https://<网关>;WF_CODEX_DEFAULT_MODEL:网关提供的模型,可用GET <网关>/v1/models查看。
- 也可以改用命令行执行器:CodeBuddy 需要在
- 进入「运行记录」,提交愿望:写清目标和至少一条验收标准。
- 在运行详情页观察:
- 实现:Agent 的消息、执行的命令和修改的文件会实时出现在事件里。
- 验证:每条验证命令的退出码和输出;失败时 Agent 会带着失败输出自动修复。
- 合入:验证通过的 commit 推送到
main。未配置交付的项目到这里运行即成功。
- 再次提交愿望时,提示词会自动带上该项目沉淀的经验,可以在项目页的「项目经验」中查看。
每个运行代次的工作目录位于 .wishforge/runs/<租户>/<运行>/<代次>/,executor 与 verifier 各自使用独立的子目录和令牌。
5. 云 IDE(可选)
Theia 是独立安装的应用,首次构建需要几分钟并会下载扩展:
npm run ide:install
npm run ide:build
启动 Theia(端口 4300)与 IDE 网关(端口 4400):
npm run dev:ide
在项目页点击「创建开发环境」,本地 provisioner 会把工作区指向本机的 Theia(Theia 未启动时工作区显示为准备中);就绪后点击「打开 IDE」。本地模式下所有工作区共用同一个 Theia 实例和 .wishforge/ide-workspace 目录:第一次打开某个项目的工作区时,项目被克隆到其中以项目命名的文件夹,并处在 ide/work 分支上。在 IDE 中提交并 git push 后,在项目页的 IDE 分支列表点「提交愿望合入」,运行会从这个分支开始,验证通过后合入目标分支。令牌只在 IDE 打开期间有效,只能推送 ide/ 开头的分支。
多人协作需要额外启动 OCT 服务,见 apps/ide/collaboration/README.md。
6. 通过 MCP 从 Codex / WorkBuddy 许愿
本地 MCP 地址为 http://127.0.0.1:4000/mcp,使用 Keycloak(http://127.0.0.1:4100,realm wishforge)做 OAuth。客户端配置见 connectors/README.md。
7. 测试与检查
| 命令 | 内容 |
|---|---|
npm run format:check |
Prettier 格式检查(npm run format 自动修复) |
npm run typecheck |
全部 workspace 与测试代码的类型检查 |
npm run build:services |
把 API、worker、Runner 与平台 Git 编译到 dist/(镜像运行的就是这些产物;npm test 会构建一次并检查每个产物都能加载) |
npm test |
单元测试、进程内集成测试与 provisioner 的 Node 测试(不需要外部服务) |
npm run test:ide |
IDE 网关、协作服务与策略扩展的 Node 测试(需要先 npm run ide:install) |
npm run test:integration |
需要本地 Compose 服务的集成测试,见下表 |
集成测试默认跳过,必须显式开启,跳过不算通过:
| 环境变量 | 测试 |
|---|---|
WF_INTEGRATION=1 |
PostgreSQL(RLS、并发、迁移)、用量与配额、部署密钥协议 |
WF_ARTIFACT_INTEGRATION=1 |
MinIO 检查点存储 |
WF_TEMPORAL_INTEGRATION=1 |
真实 Temporal 工作流 |
WF_CODEX_SDK_INTEGRATION=1 |
Codex SDK 经模型代理的协议测试(使用本地假上游,不消耗额度) |
WF_REAL_MODEL_INTEGRATION=1 |
用真实模型跑一次完整的愿望(tests/integration/real-model.test.ts):真实 Codex 实现、独立验证并合入本地仓库。需要 WF_TEST_MODEL_API_KEY,可选 WF_OPENAI_BASE_URL 与 WF_CODEX_DEFAULT_MODEL;会消耗少量真实额度 |
tests/local-loop.test.ts 用真实 Git、进程内控制面和脚本化执行器验证完整主线(实现 → 验证失败 → 自修复 → 合入 → 经验沉淀,以及并发运行的合并冲突),不需要任何外部服务,是改动执行链路时最重要的回归测试。
两个手动脚本:
node infra/scripts/smoke.mjs:检查本地 Compose 服务(PostgreSQL、Temporal、Keycloak、MinIO、镜像仓库、OCT)是否可用。WF_COMPOSE_ACCEPTANCE=true WF_CADDY_BINARY=<caddy 路径> node --import tsx infra/scripts/compose-acceptance.mjs:用真实 Docker、本地镜像仓库与 Caddy 验收 Runner 的 Compose 蓝绿部署。它会构建并推送测试镜像,然后部署、切换并回滚,还会验证部署密钥。
两个脚本都使用当前的 Docker 上下文,可以用 WF_DOCKER_CONTEXT 指定其他上下文。
CI(.github/workflows/ci.yml)在每次推送与合并请求时运行格式检查、类型检查、npm test,在 PostgreSQL 服务上执行两次迁移与集成测试,并运行 IDE 相关的 Node 测试。
8. 常见问题
- 运行停在「执行环境未就绪」:确认本地 provisioner 已启动(
dev:all会启动它),并检查.env.local中的WF_PROVISIONER_URL。 - 运行停在「验证未配置」:项目没有验证命令。在项目设置中添加后点击「继续」。
- 端口被占用:
dev:all会复用已经在运行的同名服务;其他进程占用端口时需要先停止它们。 - 重置本地数据:停止
dev:all后执行docker compose -f infra/compose.yaml down -v并删除.wishforge/,然后重新执行第 2 节。这会删除所有本地数据。