wishforge-ide/docs/development.md
eust-w 13ceca5c8f
Some checks failed
CI / Format, types and tests (pull_request) Has been cancelled
CI / PostgreSQL migrations and integration tests (pull_request) Has been cancelled
🔀 Merge review/overhaul into feat/wiki-copilot-diagnostics
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>
2026-11-12 00:39:05 +08:00

126 lines
9.3 KiB
Markdown
Raw Permalink 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。
- 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 的配置。