wishforge-ide/apps/ide/README.md
eust-w 0bcfbc13dd feat(ide): push IDE work to ide/ branches and merge it through a verified wish
People's changes now reach the target branch the same way the agent's do. The
IDE credential carries a ref prefix and the Git service runs a pre-receive hook
on every push that refuses updates outside it, so the IDE can push only
`ide/` branches; the platform's own integration is unaffected.

- A wish may name a source branch. The run starts from that branch's head, the
  agent builds on it, and verification, repair rounds, merging onto a moved
  target and conflict repair work as before. A missing branch makes the run
  wait (git_storage) until it is pushed.
- Release risk is now computed from the target branch before integration, not
  from where the run started: a migration committed on the source branch would
  otherwise have been missed and could have skipped approval.
- Clones work on `ide/work`; a plain `git push` publishes it.
- The console lists a project's IDE branches with a button to submit a wish
  that merges one, and the new-wish form has a starting-point field; MCP
  `submit_wish` accepts `sourceBranch`. The Git service lists branches under
  a prefix for this (`POST /refs`).

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

6.0 KiB
Raw Blame History

云 IDE(Theia)

基于 Eclipse Theia 1.76.0 的浏览器 IDE,包含 @theia/collaboration。它是独立的 npm 包(自己的 package-lock.json),不属于根目录的 npm workspaces,因为 Theia 依赖树很大且含原生模块。

目录 内容
src-gen/、lib/ Theia 构建产物(npm run ide:build 生成)
policy/ 策略扩展:扩展白名单、按工作区隔离的协作,见 policy/README.md
gateway/ IDE 网关:浏览器访问 Theia 的唯一入口,见 gateway/README.md
collaboration/ 每个工作区独立的 OCT 协作服务,见 collaboration/README.md
scripts/ 启动脚本、扩展下载与校验
plugins/ 镜像内固定的扩展(plugins:download 生成)

本地运行

npm run ide:install
npm run ide:build
npm run dev:ide

dev:ide 启动 Theia(http://127.0.0.1:4300,只能经网关访问)与网关(http://127.0.0.1:4400),所有工作区共用 .wishforge/ide-workspace 目录,每个项目克隆到其中以项目命名的文件夹(工作分支 ide/work),仓库令牌放在 .wishforge/ide-credentials。原生模块的编译需要 Python、make/C++ 与系统开发库(Linux 依赖见 Dockerfile)。

在项目页创建开发环境后点击「打开 IDE」。

  • 克隆:平台托管仓库的项目第一次打开时会被克隆到以项目命名的文件夹,通常几秒内出现在资源管理器中,并处在 ide/work 分支上。外部仓库(如 GitHub)不克隆,那里的改动应走 PR。
  • 推送:提交后直接 git push(或 Git 面板的「发布分支」),推送到 ide/work。也可以建其他 ide/ 开头的分支;推送目标分支或其他分支会被平台 Git 拒绝。
  • 合入:在项目页的 IDE 分支列表点「提交愿望合入」,或提交愿望时把「起点」选成这个分支。运行从分支的最新提交开始,Agent 在上面继续实现,验证通过后一并合入目标分支;验证失败时照常进入修复轮。
  • 同步:Agent 合入了新的改动后,用 git pull origin <目标分支> 把它们拉进 ide/work。
  • 凭据:会话期间网关持续送来 15 分钟的仓库令牌,存放在仓库之外(见 policy/README.md)。没有人打开 IDE 时令牌会过期,git push 也随之失败。
  • 提交身份:取最近打开会话的用户,用 git config user.name、git config user.email 可以改成自己的。

IDE 与 Agent 之间只通过 Git commit 交接,不存在 IDE 快照之类的旁路。

扩展

只能使用镜像中预置并校验过的扩展,运行时的安装、卸载、启用与停用请求都会被后端拒绝(EXTENSIONS_MANAGED_BY_ADMIN)。

  • 内置扩展来自官方 vscode-builtin-extensions 1.108.2 归档(SHA-256 05a20cf3e671c8d328b04d9ce72b25688b0e762e4a3f5592f31a21ee38280367),提供 Git、语言支持与 JavaScript 调试,每个扩展的 ID、版本与内容摘要记录在 policy/managed-plugins.lock.json;node scripts/catalog-builtin-plugins.mjs <归档> 在校验归档后重新生成该清单。
  • Python 支持:ms-python.python 2026.4.0、ms-python.debugpy 2026.6.0(调试器)、ms-pyright.pyright 1.1.402(补全、悬停与诊断),在 scripts/python-debugger.lock.json 中为 Linux x64/ARM64 与 macOS x64/ARM64 固定了官方 VSIX 的校验和;其他平台明确失败。Python 解释器本身需要在工作区镜像或项目虚拟环境中提供。
npm run plugins:download --prefix apps/ide
npm run plugins:verify --prefix apps/ide

离线构建时可以把已下载的 VSIX 传给 npm run plugins:download:python -- --archive <debugpy.vsix> --python-archive <python.vsix> --pyright-archive <pyright.vsix>。下载脚本校验 SHA-256、包身份、大小与解压路径,并原子地解包(Theia 的 local-dir 加载器不会加载未解包的 VSIX)。缺少、多出或被修改的扩展都会让启动失败。

镜像

apps/ide/Dockerfile 以 apps/ide 为构建上下文,运维提供 NODE_IMAGE 与 NODE_SLIM_IMAGE:

  • theia 目标:Theia 工作区(含 Git)。应用、扩展与清单归 root 所有,只有 /workspace 交给运行用户;生产还需要 provisioner 设置只读根文件系统。
  • gateway 目标:IDE 网关。它是最后一个阶段,所以不指定 --target 时构建的是网关。

生产边界

  • 不要直接暴露 4300 端口:终端、文件、插件与调试接口都必须在网关之后。启动脚本在 NODE_ENV=production 时要求 WISHFORGE_GATEWAY_ENFORCED=true——这只是运维的声明,真正的保护来自网关与网络策略。
  • 只有项目的 owner/admin/developer 能进入编辑会话或协作房间;viewer 不会拿到 IDE 会话。Theia 内置协作的只读控制并不完整,隐藏按钮不是授权边界。
  • OCT 0.3.1 的房间状态只在内存中:服务重启后需要新建房间,未保存的编辑可能丢失。
  • Theia 后端与用户终端以同一个系统用户运行,同一工作区内的协作者之间没有隔离;工作区只应授予可信成员编辑权限。

测试

npm run test:ide

运行网关、协作客户端与策略扩展的 Node 测试(需要先 npm run ide:install)。Theia 的界面行为(编辑器、终端、调试、Python 语言服务)没有自动化测试,修改依赖或扩展后需要在浏览器中手动验证。

参考:Theia 架构、Theia 1.76 协作源码、OCT 0.3.1、内置扩展发布。