With WF_CLAUDE_COMMAND_SANDBOX=true, Claude Code also gets Bash, run in its built-in sandbox through --settings: - The sandbox must start (failIfUnavailable), and no command may run outside it (allowUnsandboxedCommands: false). - No network: an empty allowedDomains with strictAllowlist, since an absent allowlist leaves the network open. Local binding stays off, because it would also open every local port, Temporal's included. - Commands cannot read the home directories, the CLI's home or the worker's own directory, except the workspace, a per-run scratch directory and WF_CLAUDE_COMMAND_READ_PATHS; they write only to the workspace and the scratch directory; credential variables are unset. - WF_CLAUDE_COMMAND_ENV gives commands toolchain variables, such as the POC's read-only Go module cache. The executor probes the sandbox first (Seatbelt on macOS; bubblewrap and socat on Linux) and keeps file tools only where it cannot start, saying so on the timeline. The adapter now writes the execution contract into the prompt, for the tools the agent actually has. scripts/check-claude-command-sandbox.ts checks a machine with one short real session and judges each probe by its effect, not the agent's account. On the local Mac every probe was blocked; the login keychain remains reachable, because Claude Code's Seatbelt profile always allows the security server. That limit is documented. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
148 lines
9.7 KiB
Markdown
148 lines
9.7 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_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 节。这会删除所有本地数据。
|