- 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>
6.2 KiB
6.2 KiB
仓库、分支与 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等待。 - 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)。它是可选的;没有它时只使用项目设置。
| 字段 | 作用 |
|---|---|
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 不能证明变更不含迁移,发布风险仍由验证器的变更分类决定。