vibe-workspace-kit

English · npm · Changelog · v0.2 Workflow · Enterprise Example

面向 Vibe Coding 的 Feature-oriented AI Engineering Runtime。 它让 Codex 等 Coding Agent 在同一个工程上下文中理解前端、后端、架构和需求，同时保持 Polyrepo 的独立 Git 边界，并用 Feature Contract、Context Fingerprint、Runtime Gate 和 Verification Evidence 控制 AI 开发过程。

v0.2.0 · Node.js 20+ · Git · macOS / Linux / Windows

为什么需要它

把多个仓库放进一个目录只能解决“AI 看得到代码”，却没有解决“AI 是否理解正确需求、是否在正确分支、是否仍使用最新上下文、是否真正满足验收标准”。v0.2 把这些问题提升为一套工程协议：

Product / Architecture Truth
          ↓
     Feature Contract
          ↓ human approval
   Feature Runtime (Polyrepo)
          ↓
 Canonical AI Context + Fingerprint
          ↓
      AI Coding Gate
          ↓
  Codex implementation
          ↓
 review / test / evidence
          ↓
 verify → close

安装

npm install --global vibe-workspace-kit
vibe --version

5 分钟开始一个 Feature

mkdir my-product && cd my-product && git init
vibe init --name my-product \
  --repo [email protected]:your-org/product-web.git \
  --repo [email protected]:your-org/product-api.git \
  --force-rules
vibe bootstrap

vibe feature create TASK-102 \
  --title "Add configurable reminder rules" \
  -r frontend -r backend

完善生成的 feature-spec.md 和 implementation-packet.md。需求、业务规则、架构约束应进入 canonical Artifact，而不是只写在聊天 Prompt 中。人工 Review 后将 Feature status 从 draft 改为 approved，然后：

vibe feature prepare TASK-102

它会启动/复用 Feature Runtime、统一多仓 Feature 分支、生成 Codex Context、计算 Context Fingerprint，并执行 Runtime Gate。只有看到 READY FOR AI CODING — TASK-102 才建议让 Agent 开始实现。

开发过程中：

vibe feature lifecycle TASK-102
vibe status
vibe test frontend backend
vibe review frontend backend
vibe commit backend -m "feat(TASK-102): implement reminder policy"
vibe commit frontend -m "feat(TASK-102): implement reminder settings UI"

在 verification.md 中为每个 Acceptance Criterion 记录具体 Evidence 和 PASS，最后：

vibe feature verify TASK-102
vibe feature close TASK-102

核心命令

| 命令 | 用途 | | --- | --- | | vibe doctor | 检查 Workspace / Git / Node 环境 | | vibe bootstrap | 初始化 canonical Engineering Artifacts | | vibe feature create | 创建 Feature Contract | | vibe feature prepare | 一键准备 Runtime + Codex Context + Gate | | vibe feature lifecycle | 查看 Feature 阶段和下一步 | | vibe feature check | 执行 AI Coding Gate | | vibe status | 聚合查看多仓状态 | | vibe test / vibe review | 多仓验证与 Review | | vibe commit <repo> | 安全提交一个仓库 | | vibe push <repo> | 显式推送一个仓库 | | vibe feature verify | 验证 Acceptance Criteria Evidence | | vibe feature close | 关闭 verified Runtime |

底层 feature start、feature context、feature context-generate 和 feature context-check 仍保留给 CI、Agent Wrapper 和高级工作流。

Context Drift

Codex Context 位于 .vibe/contexts/<feature-id>/codex.md。Product、Architecture、Design、Feature Spec 或 Implementation Packet 改变后，Context Fingerprint 随之改变。vibe feature context-check TASK-102 会把旧 Context 判定为 stale；重新执行 vibe feature prepare TASK-102 后才能恢复 READY。实现关键事实缺失时，Agent Contract 要求报告 SPEC_GAP，而不是猜测。

Git 安全边界

repos/ 中每个业务仓库保持独立 Git 历史；Snapshot 保护任务开始前已有修改；测试状态与代码指纹绑定；commit / push 必须指定单个仓库；feature close 不删除分支、不 reset、不丢弃 working tree。

企业案例

仓库提供通用 Enterprise Supervision System 案例，演示督办提醒策略如何经历 Feature Contract → Codex → 前后端实现 → Verification Evidence → Close，以及需求中途变化时 Context Drift 如何阻止 Agent 在旧需求上继续开发。

详见 Enterprise Supervision Example，完整日常流程和 v0.1 迁移方式见 v0.2 Workflow。

v0.1 升级

旧 Workspace 无需重建。升级 npm 包后执行 vibe bootstrap，补 Product / Architecture Truth，再挑一个真实 Feature 试运行 create → approve → prepare → verify → close。原有 status/run/review/commit/push 工作流继续有效。

发布前检查

npm run release:check

执行 typecheck、全部测试、build 和 npm pack --dry-run。

License

MIT