wishforge-ide/docs/reference/repository-contract.md
eust-w addf330b10 ✨ Add account types and enforce per-user wish permissions
- Provide six account types and custom combinations of wish, code review,
  release and management permissions, applied on each authenticated request.
- Enforce frontend-only accounts when submitting, answering, widening and
  reverting wishes; require every contributor to have full access before
  skipping backend code review.
- Gate code review and release decisions by their specific permissions.
- Rework member management to create and edit account types, permissions and
  project access, and reflect those permissions throughout the console.
- Update the manual and architecture docs with permission tests and
  end-to-end coverage.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-10-28 12:07:08 +08:00

43 lines
6.2 KiB
Markdown
Raw 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.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](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` 等待。
- IDE 工作区(FR-H2):有编辑会话时得到 15 分钟的仓库令牌,令牌里写明只能更新 `refs/heads/ide/`。平台 Git 对每次推送运行 pre-receive 钩子,越界的引用被拒绝;平台自己的合入不受这个限制。所有推送都只接受快进,也不能删除分支。IDE 分支经由从它开始的愿望进入目标分支,过程与 Agent 的改动相同。
- 平台 Git 的管理接口 `POST /refs`(`{tenantId, projectId, prefix}`)按最近提交时间列出某个前缀下的分支,工作台据此列出 IDE 分支。
- GitHub 仓库走评审路径:只推送不可变的 `wishforge/<运行>/<commit>` 分支,控制面创建或对账对应的 PR 并等待合并(`github_review`);合并后在 GitHub 实际产生的合并 commit 上重新验证,再提交集成证据。未配置 GitHub App 的 GitHub 仓库不会退回直接推送(`github_unconfigured`)。安装令牌按仓库授权而不是按分支授权,目标分支仍需要分支保护。
## wishforge.yaml V1
仓库根目录可以提交 `wishforge.yaml`(示例:[examples/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` 不能证明变更不含迁移,发布风险仍由验证器的变更分类决定。