wishforge-ide/docs/development.md
eust-w 6d2dcebe65 feat(ide): clone the project into IDE workspaces and push back through Git (FR-H2)
While someone has a workspace open, the gateway asks the API for a 15-minute
write token for the project's platform repository on behalf of that person
(membership and role checked each time) and delivers it to the workspace
backend. The backend writes it to a Git config file outside the repository
(a memory volume in Kubernetes) that the clone includes, and on the first
delivery clones the target branch into a folder named after the project. The
workspace cannot mint credentials itself, so access ends with the last
session.

- People commit and push to the target branch like with any Git server; the
  platform only accepts fast-forwards, and the next wish starts from that
  commit (covered end to end in the local loop test).
- Commits are authored by whoever opened the latest session, from the name and
  email in their sign-in; their own git config overrides it.
- Only the gateway can reach the delivery endpoint: it needs Theia's
  connection token, and the gateway refuses the path for browsers.
- The provisioner pins the workspace to its repository and lets the pod reach
  the Git service; the Kubernetes baseline admits that traffic. External
  repositories are not cloned.
- The local shared Theia clones each project into its own folder.
- The Theia image installs Git, and its stage is named theia: the default
  build target of that Dockerfile is the gateway.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 18:52:37 +08:00

7.4 KiB
Raw Blame History

本地开发

本文说明如何在本机运行完整的 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. 跑通第一个愿望

  1. 打开 http://localhost:3000,进入「项目空间」,创建一个项目,仓库地址留空。平台会在本地 Git 服务上创建仓库并初始化 main 分支。
  2. 打开「项目设置」,填写验证命令(每行一个 JSON 参数数组,例如 ["node","--test"]);需要安装依赖时再填写安装命令,例如 ["npm","ci"]。也可以不填安装命令,改在仓库的 wishforge.yaml 中声明 dev.install。
  3. 进入「执行器」,为 Codex 保存你的 OpenAI API Key。没有 Key 时,运行会停在「等待:缺少执行器凭据」。
  4. 进入「运行记录」,提交愿望:写清目标和至少一条验收标准。
  5. 在运行详情页观察:
    • 实现:Agent 的消息、执行的命令和修改的文件会实时出现在事件里。
    • 验证:每条验证命令的退出码和输出;失败时 Agent 会带着失败输出自动修复。
    • 合入:验证通过的 commit 推送到 main。未配置交付的项目到这里运行即成功。
  6. 再次提交愿望时,提示词会自动带上该项目沉淀的经验,可以在项目页的「项目经验」中查看。

每个运行代次的工作目录位于 .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 中提交并 git push 到目标分支后,再提交的愿望就从这个 commit 开始;令牌只在 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 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 节。这会删除所有本地数据。