wishforge-ide/docs/development.md
eust-w 86649af4d6 docs: rewrite architecture and restructure documentation
- docs/architecture.md replaces system-design.md: component map,
  run state machine with an explicit waiting-reason catalogue, key
  sequences (dispatch, execute/verify/repair, integrate, release,
  IDE launch, lessons), data model, API surface, identity and trust
  model, isolation modes (host for local development, kata for
  production), deployment topology, ADRs, known limitations and a
  requirement-to-test verification matrix.
- docs/development.md: local setup, one-command start, first wish,
  IDE, MCP and the test matrix (integration toggles are explicit).
- docs/operations.md: production prerequisites, explicit deployment
  mode, component configuration, Kubernetes provisioner, tenants and
  quotas, IDE gateway routing and lifecycle, delivery, monitoring,
  backup/restore, incident handling and known risks. Merges the former
  observability, recovery, billing-entitlements and runbook documents.
- Contract documents move to docs/reference/; evidence narratives that
  pointed at machine-local /private/tmp files are removed and the UI
  reference is rewritten for the target console.
- Delete docs for removed scope: workspace snapshot handoff and private
  application access.
- README rewritten as a concise entry point.

The documents describe the target state that the following
implementation commits realise.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 13:29:46 +08:00

6.0 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_SANDBOX_MODE=host、本地 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 进程
coordinator worker — 运行 Temporal 工作流
deployer worker — 为已构建的运行创建发布

Temporal 控制台在 http://127.0.0.1:8233,可以看到每个运行的工作流。

4. 跑通第一个愿望

  1. 打开 http://localhost:3000,进入「项目空间」,创建一个项目,仓库地址留空。平台会在本地 Git 服务上创建仓库并初始化 main 分支。
  2. 在项目设置中填写验证命令,例如 node --test;如需安装依赖,再填写安装命令,例如 npm ci。
  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;然后点击「打开 IDE」。本地模式下所有工作区共用同一个 Theia 实例和 .wishforge/ide-workspace 目录。

多人协作需要额外启动 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 单元测试与进程内集成测试(不需要外部服务)
npm run test:ide IDE 网关、provisioner、策略扩展的 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、进程内控制面和脚本化执行器验证完整主线(实现 → 验证失败 → 自修复 → 合入 → 经验沉淀),不需要任何外部服务,是改动执行链路时最重要的回归测试。

8. 常见问题

  • 运行停在「执行环境未就绪」:确认本地 provisioner 已启动(dev:all 会启动它),并检查 .env.local 中的 WF_PROVISIONER_URL。
  • 运行停在「验证未配置」:项目没有验证命令。在项目设置中添加后点击「继续」。
  • 端口被占用:dev:all 会复用已经在运行的同名服务;其他进程占用端口时需要先停止它们。
  • 重置本地数据:停止 dev:all 后执行 docker compose -f infra/compose.yaml down -v 并删除 .wishforge/,然后重新执行第 2 节。这会删除所有本地数据。