Brings the branch up to the current base (executor settings, project skills, Chinese run messages, cloud IDE removal, wish attachments) and resolves the ten conflicted files, keeping both sides: - wish-refiner: the tenant's executor settings pick the models first, then the Copilot model setting; the tenant credential still goes before the operator's login - worker providers: executor settings apply, and a run with its own credential still gets an empty home - main.ts: Copilot screenshot uploads and wish attachments each keep their own body limit - contracts, http, web types: default budget and skill auto-activation, Copilot and attachment entity kinds, ./text and ./attachments exports - globals.css: Copilot styles and attachment styles, one after the other - tests: the canceled-release reason is Chinese; the refiner's default models have no [1m] suffix, as this branch names them Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
126 lines
9.3 KiB
Markdown
126 lines
9.3 KiB
Markdown
# 本地开发
|
||
|
||
本文说明如何在本机运行完整的 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。
|
||
- Claude Code 只有文件工具(读、改、写、查找),不能执行命令,安装与测试由验证器完成。CodeBuddy 执行命令时没有沙箱,只能在 `host` 模式中运行。
|
||
- 想让 Claude Code 自己构建和测试:先运行 `node --env-file=.env.local --import tsx scripts/check-claude-command-sandbox.ts`(一次小的真实模型调用,逐项检查沙箱确实挡住了网络、本机端口、工作区外的读写与凭据),全部通过后在 `.env.local` 中设置 `WF_CLAUDE_COMMAND_SANDBOX=true`。命令在 Claude Code 自带的沙箱中运行,没有网络;工具链放在用户主目录下时,用 `WF_CLAUDE_COMMAND_READ_PATHS`(用 `:` 分隔的绝对路径)放行只读访问,用 `WF_CLAUDE_COMMAND_ENV`(JSON 对象)设置变量。
|
||
- **使用公司的模型网关**:在 `.env.local` 中设置下面三个变量,再在「执行器」页保存网关的 Key。
|
||
- `WF_OPENAI_BASE_URL`:Codex 使用的 OpenAI 兼容网关,需支持 `/responses`,例如 `https://<网关>/v1`;
|
||
- `WF_ANTHROPIC_BASE_URL`:Claude Code 使用的 Anthropic 兼容网关,例如 `https://<网关>`;
|
||
- `WF_COPILOT_MODEL`:项目 Copilot 与愿望优化使用的模型,默认 `deepseek-flash@latest`(旧名 `WF_CLAUDE_ASK_MODEL`,见 `docs/copilot.md`);
|
||
- `WF_CODEX_DEFAULT_MODEL`:网关提供的模型,可用 `GET <网关>/v1/models` 查看。
|
||
4. 进入「运行记录」,提交愿望:写清目标和至少一条验收标准。
|
||
5. 在运行详情页观察:
|
||
- **实现**:Agent 的消息、执行的命令和修改的文件会实时出现在事件里。
|
||
- **验证**:每条验证命令的退出码和输出;失败时 Agent 会带着失败输出自动修复。
|
||
- **合入**:验证通过的 commit 推送到 `main`。未配置交付的项目到这里运行即成功。
|
||
6. 再次提交愿望时,提示词会自动带上该项目沉淀的项目技能(含踩坑记录),可以在「知识库」中查看。
|
||
|
||
每个运行代次的工作目录默认位于 `~/.local/share/wishforge/runs/<租户>/<运行>/<代次>/`,executor 与 verifier 各自使用独立的子目录和令牌。`WF_LOCAL_RUN_ROOT` 可以改到别处,但不能放在本仓库目录下:Node/TypeScript 会沿父目录查找依赖,项目会意外继承平台的类型定义,本地 provisioner 会拒绝这种配置。
|
||
|
||
## 5. 通过 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)。
|
||
|
||
## 6. 测试与检查
|
||
|
||
| 命令 | 内容 |
|
||
|---|---|
|
||
| `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: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、镜像仓库)是否可用。
|
||
- `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 服务上执行两次迁移与集成测试。
|
||
|
||
在本地 k3s 上以 Kubernetes 方式运行整个平台(每次运行独立的 Pod、网络策略、模型代理),见 [local-k3s.md](local-k3s.md)。
|
||
|
||
## 7. 常见问题
|
||
|
||
- **运行停在「执行环境未就绪」**:确认本地 provisioner 已启动(`dev:all` 会启动它),并检查 `.env.local` 中的 `WF_PROVISIONER_URL`。
|
||
- **运行停在「验证未配置」**:项目没有验证命令。在项目设置中添加后点击「继续」。
|
||
- **端口被占用**:`dev:all` 会复用已经在运行的同名服务;其他进程占用端口时需要先停止它们。
|
||
- **重置本地数据**:先停止 `dev:all`(使用本机 POC 时执行 `node scripts/local-poc-service.mjs stop`),再执行 `docker compose -f infra/compose.yaml down -v`,这会删除数据库与对象存储中的全部数据;然后删除运行目录(默认 `~/.local/share/wishforge/runs`,即 `WF_LOCAL_RUN_ROOT`)和本地 Git 服务的仓库 `.wishforge/git`,最后重新执行第 2 节。不要整个删除 `.wishforge/`:本机 POC 的项目绑定、登录凭据、Runner 密钥与状态、部署回执和检查缓存都在其中,删除后要重新执行本机 POC 的配置。
|