@vibe-git/vibe-git

Vibe-Git 0.20

Vibe-Git 是一个 CLI 主导、网页观察 的多人 Codex 协作控制面。队长只启动一个 Host 和 Cloudflare Quick Tunnel；每位成员从自己的 Git 工作区连接，不需要填写项目名称、成员名字或固定 A/B/C 身份。

安装

需要 Node.js 24+、Git、Codex CLI。

npm ci
npm run build
npm link

npm link 后可直接使用 vibe-git。不想全局链接时，可将下文命令中的 vibe-git 替换为：

node .\apps\cli\dist\index.js

仓库根目录提供 Codex Skill：.agents/skills/vibe-git/SKILL.md。在本仓库使用 Codex 时可用 $vibe-git 调用；Skill 包含源码安装、队长与成员的 CLI 工作流，以及凭据处理约定。若要在其他项目也使用该 Skill，可将整个 .agents/skills/vibe-git 文件夹复制到个人 ~/.codex/skills/ 下。

$repoRoot = (git rev-parse --show-toplevel).Trim()
$skillHome = Join-Path $HOME ".codex\skills"
New-Item -ItemType Directory -Path $skillHome -Force | Out-Null
Copy-Item -LiteralPath (Join-Path $repoRoot ".agents\skills\vibe-git") -Destination $skillHome -Recurse

1. 队长启动

请先进入队长自己的 Git 工作区，再运行：

vibe-git host start

该命令会：

• 启动 Fastify Host（同源托管构建后的 React 页面）；
• 创建稳定 Captain 节点并启动隐藏后台守护进程；
• 安装/启动 Cloudflare Quick Tunnel；
• 输出成员可复制的 vibe-git connect <join-url>。

常用管理命令：

vibe-git host status
vibe-git invite show
vibe-git invite rotate
vibe-git open
vibe-git host stop

invite rotate 只让旧加入链接失效，不影响已经注册的节点。

2. 每位成员连接

每位成员先进入自己的 Git 工作区，再粘贴队长给出的命令：

vibe-git connect https://xxxx.trycloudflare.com/join/xxxxx

连接成功后会自动得到 Member-XXXX 和稳定节点 ID，并启动隐藏后台进程。不会上传主机名。

vibe-git status
vibe-git logs
vibe-git open
vibe-git disconnect

vibe-git open 创建只能使用一次的短期票据，浏览器再换取 HttpOnly 会话；网页没有身份切换器。

3. 绑定专用 Codex 审核池

队长和每位成员都建议执行：

vibe-git codex bind
vibe-git codex status

绑定使用官方 Codex device-auth，凭据单独保存在：

~/.vibe-git/audit-codex

它不会读取或覆盖日常 ~/.codex。Host 只收到“可用/不可用”和脱敏的 5h/周额度百分比，不接收账号、邮箱或 OAuth Token。

专用池只执行：

• 多份计划 Markdown 的需求对齐与任务拆分；
• 多份变更 Markdown 的冲突与影响范围审核。

真正的开发任务使用成员日常 Codex。默认 App Server 优先、CLI 回退：

vibe-git config set work.transport auto
# 也可明确指定 app-server 或 cli

解绑专用审核账号不会影响日常 Codex：

vibe-git codex unbind

4. 提交计划并对齐

成员只维护文件，不填写网页表单：

vibe-git plan submit .\我的方案.md

可以选择任意文件名的 .md。文件必须是 UTF-8、非空且不超过 256 KiB；原文件名会保留，提交入口会把它归类为“计划”。重复内容是幂等的，变更内容会形成新版本。

• 每个节点当前只展示自己的最新提案，再次执行 plan submit 即更新自己的提案；网页也会在自己的提案卡片上显示“更新我的提案”。
• 所有在线或离线成员的最新提案对整个团队可见，成员之间和队长都能查看、下载。
• 队长与其他成员只能读取别人的提案，不能代替所有者修改；更新接口使用版本号防止过期页面覆盖新版本。

队长决定何时冻结当前各节点最新计划并启动对齐：

vibe-git align start
vibe-git align status
vibe-git align show <alignment-id>          # 查看冲突卡片、选项与任务草稿
vibe-git align resolve <alignment-id> <issue-id> <option-id>
vibe-git align export <alignment-id>

审核池按“活动作业更少 → 额度更高 → 最久未使用”选择节点。对齐输出包括 alignment.md、tasks.md 和结构化任务。队长可以在发布前改派：

首次对齐只上传队长 Git HEAD、受限目录索引及配置键名；不会上传全仓源码或配置值。计划较长时按节点与章节分片提炼，冻结提案版本；实质冲突必须由队长用 align resolve 选择后才能发布。发布时再次校验队长 HEAD 是否仍与对齐快照一致。

vibe-git task assign <draft-task-id> <node-id>
vibe-git tasks publish <alignment-id>

5. 细化、开工、同步与完成

vibe-git task list
vibe-git task pull <task-id>                 # 默认写出 task.md
vibe-git task push <task-id> .\我的执行步骤.md
vibe-git task start <task-id>
vibe-git task sync <task-id>
vibe-git task done <task-id>

• 上传的任意 .md 会归类为该任务的执行细化，只能补充执行步骤、文件范围、验证命令和备注，不能覆盖正式目标、边界或验收。task pull 仍默认导出为 task.md，也可指定输出名。
• 发布任务不会自动抢跑；只有负责人执行 task start 才会向自己的 Codex App Server/CLI 发命令。
• 后台每 15 秒同步 Codex 阶段、Git 分支、完整 SHA 和 dirty 状态，不上传对话正文或工具记录。
• Codex 正常结束后状态为 WAITING_CONFIRMATION。负责人必须在结束后做一次新鲜同步，才能 task done。
• 离线节点的任务和消息会保留，重连后继续领取。

6. Vibe-Git Pull Request 与需求审核

这里的 Pull Request 是内部需求变更单，不会创建 GitHub PR：

vibe-git pr submit .\调整登录流程.md
vibe-git pr list

开发中可以持续提交。普通成员不能开启审核；所有任务完成后自动审核。队长若要开发中提前审核：

vibe-git review start --force
vibe-git review status
vibe-git review cancel <review-id>          # 取证中取消，变更回到待审队列

审核开始会向全员写入持久消息。各任务负责人先在自己的工作区生成受限 Git 路径索引；无法明确排除影响的任务再由本机专用审核 Codex 逐任务只读深查，最多两轮。主控 Agent 只接收路径、行号、版本指纹和结论，不接收源码正文或完整 diff。长文档按章节分片摘要，不静默截断。离线或仍缺证据的节点显示为 NEEDS_EVIDENCE，在证据齐全前不能应用；代码版本漂移会使旧证据和租约失效。明确无影响的任务继续开发。

主控给出逐份变更结论、受影响任务、替代任务与增量需求修订。队长应用后，修订以更高优先级附加到原需求，不会用摘要覆盖长篇旧需求。开发中只暂停真正受影响任务；阶段完成后的获批替代任务累积为下一阶段草稿，仍需队长发布。

结果不会自动应用，必须由队长确认：

vibe-git review apply <review-id>
vibe-git review reject <review-id>

上传的任意 .md 会由该入口归类为需求变更。审核期间新提交的变更文档自动进入下一批；阶段结束后获批的变更会形成下一阶段待发布草稿。

网页

运行 vibe-git open。页面只有六个区域：

• 节点与审核池；
• Plans；
• 对齐稿；
• 任务；
• 变更与审核；
• 持久消息。

Captain 页面显示队长按钮，成员页面只显示自己的操作。页面使用文件选择、下载、状态按钮、节点选择和确认按钮，不提供自由文本业务表单。

安全与数据

• 节点注册后使用独立随机凭据；旧的 x-member-id 信任模式已移除。
• 邀请密钥只用于首次注册，节点可由队长撤销。
• Markdown 以纯文本结构安全渲染，不执行 HTML 或脚本。
• SQLite 首次升级到 v0.20 前会自动备份到 data/v20/backups/。
• 旧表保留归档，但 v0.20 API 不再暴露；生产启动不会写入 demo seed。
• Quick Tunnel 是临时地址，重启后用 vibe-git host status 或 invite show 获取新地址。
• 分布式审核采用官方 Codex CLI/App Server 与隔离 CODEX_HOME；只借鉴 dsh-codex-connect 的本机凭据隔离、脱敏原则，不调用 ChatGPT 私有后端。

开发验证

npm run typecheck
npm test
npm run build

Host API 健康检查：GET /health。运行问题优先查看：

vibe-git logs
Get-Content "$HOME/.vibe-git/host.log" -Tail 100