wishforge-ide/docs/development.md
eust-w 975b880ae7 feat: run the whole platform on a local k3s cluster
infra/k8s/local describes a development cluster in a Colima VM: PostgreSQL,
Temporal, the platform Git service, the API (migrating and seeding in init
containers), the coordinator and deployer workers, and the Kubernetes
provisioner with a service-account kubeconfig, a Role in the tenant namespace
and a default-deny policy there. Wishes run in per-run pods under the
provisioner's network policies, and models are reached through the API's
run-scoped proxy and the configured gateway.

scripts/k3s-local.mjs starts the VM and a local registry, builds and pushes the
images by digest, renders the manifest with generated secrets kept in
.wishforge/k3s, stores the gateway key over stdin, and runs a smoke wish. Every
command names the colima-wishforge context, never the current one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 01:00:41 +08:00

146 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 本地开发
本文说明如何在本机运行完整的 WishForge 主线(提交愿望 → Agent 实现 → 独立验证 → 合入),以及如何运行测试。架构背景见 [architecture.md](architecture.md)。
## 1. 前置条件
- Node.js 22 或更高版本、npm、Git
- Docker 与 Docker Compose(用于 PostgreSQL、Temporal、Keycloak、MinIO 与本地镜像仓库)
- 可选:一个 OpenAI API Key,用于让 Codex 执行器真正写代码
> 本地执行模式(`host`)**没有任何隔离**:Agent 生成的代码与项目的测试命令直接以你的用户身份在本机运行。只在你信任的项目和模型上使用。
## 2. 首次初始化
```bash
npm ci
```
```bash
npm run setup:local
```
`setup:local` 生成仅本地使用的 `.env.local` 与 `apps/web/.env.local`(权限 0600,已被 Git 忽略),包括随机生成的数据库密码、服务令牌与签名密钥,以及本地执行所需的配置(`WF_DEPLOYMENT_MODE=development`、`WF_PROVISIONER_BACKEND=local`、本地 provisioner 地址等)。重复执行只会补齐缺失的配置,不会覆盖已有值;升级代码后重新执行一次即可获得新增的配置项。
```bash
docker compose -f infra/compose.yaml up -d
```
如果你使用 Colima 等非默认 Docker context,可以加上 `--context <名称>`,或设置 `DOCKER_CONTEXT`。
```bash
npm run db:migrate
```
```bash
npm run db:seed
```
种子数据只创建本地租户 `demo` 和一个 owner 用户,不会伪造项目或运行记录。
## 3. 启动
```bash
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 时,运行会停在「等待:缺少执行器凭据」。
- 也可以改用命令行执行器: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` 查看。
4. 进入「运行记录」,提交愿望:写清目标和至少一条验收标准。
5. 在运行详情页观察:
- **实现**:Agent 的消息、执行的命令和修改的文件会实时出现在事件里。
- **验证**:每条验证命令的退出码和输出;失败时 Agent 会带着失败输出自动修复。
- **合入**:验证通过的 commit 推送到 `main`。未配置交付的项目到这里运行即成功。
6. 再次提交愿望时,提示词会自动带上该项目沉淀的经验,可以在项目页的「项目经验」中查看。
每个运行代次的工作目录位于 `.wishforge/runs/<租户>/<运行>/<代次>/`,executor 与 verifier 各自使用独立的子目录和令牌。
## 5. 云 IDE(可选)
Theia 是独立安装的应用,首次构建需要几分钟并会下载扩展:
```bash
npm run ide:install
```
```bash
npm run ide:build
```
启动 Theia(端口 4300)与 IDE 网关(端口 4400):
```bash
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](../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](../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 测试。
在本地 k3s 上以 Kubernetes 方式运行整个平台(每次运行独立的 Pod、网络策略、模型代理),见 [local-k3s.md](local-k3s.md)。
## 8. 常见问题
- **运行停在「执行环境未就绪」**:确认本地 provisioner 已启动(`dev:all` 会启动它),并检查 `.env.local` 中的 `WF_PROVISIONER_URL`。
- **运行停在「验证未配置」**:项目没有验证命令。在项目设置中添加后点击「继续」。
- **端口被占用**:`dev:all` 会复用已经在运行的同名服务;其他进程占用端口时需要先停止它们。
- **重置本地数据**:停止 `dev:all` 后执行 `docker compose -f infra/compose.yaml down -v` 并删除 `.wishforge/`,然后重新执行第 2 节。这会删除所有本地数据。