Operations, development and architecture docs, the reference pages and the component READMEs were rewritten against the code: every documented variable exists, and the settings operators need (runtime image, Git service, listen addresses, Runner targets, single-tenant gateway and provisioner bindings) are documented. Gaps the docs used to present as working are now stated as such: IDE workspaces do not clone the project yet (FR-H2), and in Kubernetes mode dependency installs and image builds have no network path until an egress proxy and builder access exist. The Kubernetes README describes what the provisioner creates, what the Runner needs in a target namespace, and the cluster acceptance that is still outstanding. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
7.2 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 时,运行会停在「等待:缺少执行器凭据」。
- 进入「运行记录」,提交愿望:写清目标和至少一条验收标准。
- 在运行详情页观察:
- 实现: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 目录;工作区不会自动克隆项目仓库(FR-H2,尚未实现)。
多人协作需要额外启动 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 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 经模型代理的协议测试(使用本地假上游,不消耗额度) |
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 节。这会删除所有本地数据。