wishforge-ide/docs/reference/repository-contract.md
eust-w da1cfcea13 🔥 Remove the cloud IDE
The cluster never ran Theia or the IDE gateway, so every workspace stayed
"未配置" forever. The feature is gone instead of half-present:

- API: workspace, launch and lifecycle endpoints, the gateway identity and
  its internal routes, the dispatcher's workspace provisioning and the
  lifecycle worker. Migration 003 deletes stored workspaces and settles
  their pending outbox items.
- Provisioner: workspace provisioning and lifecycle for both backends.
- Web: the 云 IDE panel, the launch route, the start-branch picker that
  listed IDE branches, and the workspace count on usage.
- apps/ide, infra/oct, dev:ide and the CI job; IDE parts of local k3s,
  network policies, RBAC, docs and the architecture diagram.

A wish can still start from a pushed branch through the API (sourceBranch).
Plan files and stored entitlements may still carry maxWorkspaces; it is
accepted and ignored.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-11-04 12:43:02 +08:00

6.3 KiB
Raw Blame History

仓库、分支与 wishforge.yaml 约定

仓库与传输

  • 仓库地址只支持不带内嵌凭据、查询串与片段的 HTTPS。SSH 与 SCP 形式的地址在创建项目和启动执行器之前就被拒绝。开发模式下设置 WF_GIT_ALLOW_LOCAL_HTTP=true 后允许本机回环地址的 HTTP;生产模式拒绝。
  • Git 命令不读取全局与系统配置、不跟随 HTTP 重定向、不使用宿主机的凭据缓存。仓库范围的短期凭据通过进程环境中的请求头传入,不出现在 URL 中,只发给持有执行租约的身份:executor 只读,verifier 可写。
  • 不支持 Git LFS、子模块与 SSH agent。

基线与检查点

  • 新运行克隆仓库后,以 refs/remotes/origin/<targetBranch> 指向的 commit 为基线;愿望指定了起点分支(sourceBranch)时改用 refs/remotes/origin/<sourceBranch>。远端默认 HEAD 与同名标签不会被选中。目标分支不存在时明确报错(TARGET_BRANCH_UNAVAILABLE);起点分支不存在时运行进入 git_storage 等待(SOURCE_BRANCH_UNAVAILABLE),推送该分支后继续即可。起点分支不能是目标分支,也不能是平台自己的 wishforge/ 分支。分支名与引用表达式在创建项目与运行时都会校验。
  • 检查点是相对基线的增量 Git bundle(<base>..HEAD)加上二进制补丁及其摘要。bundle 与补丁各不超过 4 MiB;配置了对象存储时 bundle 存入对象存储(见 artifact-storage.md)。工作区没有变化时检查点不含 bundle。
  • 恢复检查点时,从项目仓库克隆基线 commit,再应用 bundle 并核对补丁摘要;恢复出的 commit 与检查点不一致时拒绝。基线已不在仓库中(例如目标分支被强制推送)时报 CHECKPOINT_BASE_UNAVAILABLE,运行进入等待。
  • 执行器安装依赖后,安装产生的未跟踪文件(如 node_modules/)写入 .git/info/exclude,不会进入检查点。

合入

  • 项目划出后端代码(codeReview.paths,glob;exceptPaths 为放行的前端与其他路径)时,验证通过后、合入前,改到后端代码(或运行从其他分支开始)、而提交人或补充过需求的人不能直接合入(许愿范围不是 full)的运行进入 code_review 等待,由有「审核代码」权限的人批准后才合入;批准绑定被审核的 commit 与需求版本。声明只改前端(frontendOnly)的愿望改到后端代码时不运行检查,失败类型为 scope:修复轮开始前平台把这些文件恢复到运行开始时的内容,Agent 只改前端重做。改动路径不做重命名识别,挪动的文件在新旧两个位置都算改到。
  • 撤销运行(revertOf)在目标分支最新代码上三方反向应用被撤销运行合入前后两个 commit 之间的改动,之后的提交保留;冲突时由执行器解决,之后照常验证与合入。
  • verifier 在独立的裸仓库(远端的缓存)中准备候选 commit:目标分支没有移动时直接使用已验证的 commit;否则把它合并到目标分支的最新提交上,并对合并结果重新验证。
  • 推送使用 --force-with-lease 并先做祖先检查;推送时目标分支又前进了,就基于新的提交重新准备候选,最多三次。
  • 合并结果未通过检查、而不带本次改动的目标分支同样未通过(运行的起点能通过)时,运行进入 target_broken 等待,由人修好目标分支后继续,不消耗修复轮数;其余情况按一轮修复处理。
  • 合并冲突时提交失败的集成证据(冲突文件与目标 commit),按一轮修复处理:修复轮先把最新目标分支合并进工作区,执行器解决冲突标记,检查点以该目标 commit 为基线。修复轮数用尽时运行进入 integration_conflict 等待。
  • 平台 Git 可以签发只能更新某个引用前缀(例如 refs/heads/ide/)的仓库令牌:pre-receive 钩子拒绝越界的引用,平台自己的合入不受这个限制。所有推送都只接受快进,也不能删除分支。管理接口 POST /refs({tenantId, projectId, prefix})按最近提交时间列出某个前缀下的分支。这两项原本服务于已移除的云 IDE,目前没有调用方。
  • 愿望可以从一个已推送到项目仓库的分支开始(API/MCP 的 sourceBranch),验证后合入目标分支,过程与 Agent 的改动相同。
  • GitHub 仓库走评审路径:只推送不可变的 wishforge/<运行>/<commit> 分支,控制面创建或对账对应的 PR 并等待合并(github_review);合并后在 GitHub 实际产生的合并 commit 上重新验证,再提交集成证据。未配置 GitHub App 的 GitHub 仓库不会退回直接推送(github_unconfigured)。安装令牌按仓库授权而不是按分支授权,目标分支仍需要分支保护。

wishforge.yaml V1

仓库根目录可以提交 wishforge.yaml(示例:examples/wishforge.yaml)。它是可选的;没有它时只使用项目设置。

字段 作用
dev.install 依赖安装命令(参数数组)。只在项目没有配置受保护的安装命令时使用,执行器开始前与验证前各运行一次,在 dev.workingDirectory 中执行
dev.runtime、dev.command 开发提示;平台不执行 dev.command
tests 补充测试,追加在受保护的验证命令与验收配置之后,不能替代它们
build Dockerfile 与构建上下文,必须与项目交付配置一致
ports、health 端口与健康检查,必须与项目交付配置一致
resources 资源请求,不能超过 provisioner 给出的上限
migrations 声明需要数据迁移时提高发布风险;迁移命令不会被自动执行

读取规则:只读取已提交的根目录 wishforge.yaml,并核对工作区 HEAD、Git 树条目与文件内容一致;文件必须是不超过 64 KiB 的普通 UTF-8 文件。符号链接、目录、YAML 别名、自定义标签、重复键、多文档、路径穿越与工作区漂移都会被拒绝;未知字段(包括试图授予环境、凭据、权限或审批豁免的字段)同样被拒绝。声明 migrations.required: false 不能证明变更不含迁移,发布风险仍由验证器的变更分类决定。