jacobcy/vibe-instruction

/vibe-instruction - 项目导览

这是所有 agent 的入口导览技能。用于快速了解项目结构、可用命令和开发工作流。

---

项目结构概览

Vibe Center 包含两个并行实现：

vibe-center/
  bin/vibe          # V2 Shell 入口 (重定向到 V3)
  lib/              # V2 Shell 核心逻辑
  config/shell/aliases.sh # V2 alias 定义
  src/vibe3/        # V3 Python 实现 (当前核心)
  skills/           # AI agent 技能集 (Markdown)
  .agent/           # 规则、规范、工作流、Supervisor 上下文

---

V2 Shell 部分（vibe2）

V2 提供底层 alias 和环境工具。

使用原则：

• vibe / bin/vibe 主要用于 V2 shell 环境、alias、keys、tooling 入口。
• 不要把 vibe 当成 V3 orchestration / flow / task / PR 的主入口。
• 遇到 V3 语义时，优先使用 vibe3 或 uv run python src/vibe3/cli.py ...。

核心 alias：

| alias | 含义 | | ---------------- | ----------------------------------- | | wtnew <branch> | 创建新 worktree（git worktree add） | | vup | 更新主仓库 + 当前 worktree |

V2 环境命令：

bin/vibe check          # 验证环境 (V2 版)
bin/vibe tool           # 工具管理
bin/vibe keys <list|set|get|init>  # 密钥管理

---

V3 Python 部分（vibe3）

V3 是当前的人机协作编排层，负责 issue / branch / PR 的创联与本地 flow / handoff 协作增强。

运行方式：

# 推荐给 agent / tmux / server 子进程使用仓库真源入口
uv run python src/vibe3/cli.py <command>
# 人类本地交互可以继续使用 alias
vibe3 <command>

命令使用原则：

• agent、tmux、后台子进程、server、脚本里优先使用 uv run python src/vibe3/cli.py ...。
• 人类本地交互可以使用 vibe3 ... alias。
• 文档里首次提到命令时，优先区分 vibe（V2 shell）和 vibe3（V3 orchestration / flow / task / PR）。
• vibe 继续负责 shell 环境、alias、keys、tooling；vibe3 负责 flow / task / orchestra / PR / review。
• 不要把 vibe check 和 vibe3 check 混为一谈；前者是 V2 环境检查，后者是 flow/task 同步审计。

核心命令组

status - 全局看板（主入口）

vibe3 task status             # 查看所有活跃 flow、Orchestra 追踪进度及环境状态

补充语义：

• task status 是当前 runtime scene 的主观察入口。
• orchestra ready queue、active issues、blocked issues 优先通过这里看。
• 需要看”主线现在能不能继续调试”，先看 task status。
• 注意：CLI 有一个隐藏的顶层 status 命令（兼容性保留），实际等同于 task status。

flow - 逻辑现场管理

uv run python src/vibe3/cli.py flow show          # [高频] 查看当前分支绑定的 task、PR、milestone 及 Timeline
uv run python src/vibe3/cli.py flow status        # 仅查看活跃 flow 列表
uv run python src/vibe3/cli.py flow update        # [高频] 注册当前分支为 flow，或更新其 metadata
uv run python src/vibe3/cli.py flow bind <issue>  # [高频] 绑定 issue 到当前 flow (role: task/related/dependency)
uv run python src/vibe3/cli.py flow blocked       # 标记当前 flow 为阻塞，并记录原因

补充语义：

• flow show 看当前分支是不是已注册 flow，以及该 flow 的 PR / task / handoff 现场。
• flow status 看全局 flow 列表，不替代 task status 的 orchestra 看板作用。
• 如果当前分支尚未注册 flow，先 flow update，再继续把它当作正式现场。

check / resume - 审计与恢复

uv run python src/vibe3/cli.py check                  # 检查 flow 和 task 是否同步
uv run python src/vibe3/cli.py task resume 456        # 恢复特定 issue（默认 --label auto）
uv run python src/vibe3/cli.py task resume 456 --label auto  # 显式指定自动推断恢复
uv run python src/vibe3/cli.py task resume --blocked  # 批量恢复所有 blocked issues（谨慎使用）
uv run python src/vibe3/cli.py flow rebuild 456       # 显式重建，删除并重建 flow/worktree

补充语义：

• check 是同步审计，不是默认的”看现场”命令。
• task resume <issue-number> 用于恢复特定 issue，清除 blocked 状态并推断恢复 label，不删除现场。
• task resume --blocked 批量恢复所有 blocked issues（谨慎使用，可能影响多个现场）。
• flow rebuild 用于显式删除并重建 flow scene，是 destructive 操作。
• task resume 不再表示重建；它默认是 --label auto。
• 需要删除 flow/worktree 时使用 flow rebuild，不要用 task resume 隐式触发。

settings - 治理真源

cat config/v3/loc_limits.yaml

补充语义：

• config/v3/loc_limits.yaml 是代码总量、单文件 LOC 限制和 exception 的真源。
• 总量命中阈值时，默认动作不是机械阻断，而是触发一轮代码质量复查。
• 单文件命中默认或 max 限制时，先判断是否值得拆分；若不值得拆分，再进入 exception 流程。
• 任何”允许提升总量”或”允许单文件例外”的判断，都应回写到 config/v3/loc_limits.yaml 并附 reason。

run - Agent 执行引擎

vibe3 run --branch <branch>              # 执行 flow 的 plan（自动读取 plan_ref）
vibe3 run --branch <branch> --no-async   # 同步执行（阻塞）
vibe3 run --branch <branch> --publish    # 提交模式：创建 commit + PR
vibe3 run --skill <name>                 # 派发特定 skill 执行
vibe3 run "指令描述"                      # 派发自定义指令执行（lightweight 模式）

补充语义：

• 默认异步执行（在 tmux session 中），无需指定 --async。
• --branch 可接受分支名或 issue 编号（如 2428 或 dev/issue-2428）。
• 无 --plan 参数时，自动从 flow_state.plan_ref 读取计划。
• --publish 模式会自动创建 commit 和 PR。
• --skill 和 --publish 互斥。

plan - 计划生成

vibe3 plan --branch <branch>        # 基于 issue/branch 现场生成实现计划
vibe3 plan --spec <spec-ref>        # 基于 spec 文件、issue number 或 @spec 生成实现计划

handoff - 协作交接记录

vibe3 handoff status                      # 查看当前分支的 agent 交接链
vibe3 handoff show @plan --branch <b>     # 读取计划 artifact
vibe3 handoff show @report --branch <b>   # 读取执行报告
vibe3 handoff show @audit --branch <b>    # 读取审查报告
vibe3 handoff show @current               # 读取当前分支的 handoff
vibe3 handoff append "..." --kind note    # 记录关键发现或里程碑

补充语义：

• @plan、@report、@audit、@spec 是特殊别名，从 flow_state 的对应 ref 字段解析。
• @current 读取当前分支的 current.md。
• 其他路径（如 @task-xxx/run.md）为共享 artifact，忽略 --branch。

inspect - 代码智能分析

vibe3 inspect symbols <file>:<symbol> # 跨文件查找符号引用
vibe3 inspect base origin/main        # 分析当前分支与主干的结构差异
vibe3 inspect files <path>            # 统计文件 LOC、方法数与内部依赖

pr - Pull Request 管理

vibe3 pr create --base main --yes     # 创建 PR
vibe3 pr show                         # 查看 PR 详情和变更分析
vibe3 pr ready                        # 标记 PR 为 ready for review

review - 代码审查

vibe3 review --branch <branch>         # 审查 issue 实现（orchestra-driven）
vibe3 review base origin/main          # 审查本地变更 vs base branch（对比快照）

snapshot - 项目级结构跟踪（持久化）

vibe3 snapshot build                    # 构建当前结构（仅内存）
vibe3 snapshot save --as-baseline       # 持久化结构并设为基线
vibe3 snapshot list                     # 列出所有保存的快照
vibe3 snapshot show                     # 显示快照详情
vibe3 snapshot diff                     # 与基线比较结构

补充语义：

• 用于跟踪项目结构演进、模块/依赖/LOC 增长。
• 单文件分析优先使用 vibe3 inspect。

scan - 治理和监督扫描

vibe3 scan governance    # 运行治理扫描
vibe3 scan supervisor    # 运行监督扫描
vibe3 scan all           # 运行所有扫描

补充语义：

• 不启动服务器的情况下运行一次性扫描。

serve - Orchestra 服务器

vibe3 serve start     # 启动 Orchestra 服务器
vibe3 serve status    # 显示服务器状态、FailedGate 状态和近期活动
vibe3 serve stop      # 停止服务器
vibe3 serve resume    # 清除 FailedGate，允许 orchestra 恢复
vibe3 serve logs      # 显示服务器日志

补充语义：

• Orchestra 是后台服务，通过心跳轮询自动处理 Webhook 事件。
• vibe3 task status 是它的主展示面。

mcp - MCP 服务器

vibe3 mcp run  # 在 stdio 模式下运行 MCP 服务器（用于 MCP 客户端集成）

ask - 项目知识问答

vibe3 ask "问题内容"  # 询问关于项目的问题

---

标准开发工作流

完整的 vibe3 工作流由 /vibe-continue 定义。以下是核心步骤：

1. 启动任务

/vibe-new <issue-number>        # 创建 flow/branch/worktree，完成后指引到 /vibe-continue
/vibe-continue                  # 恢复已有 branch，查看工作流方法

2. 执行工作流（详见 /vibe-continue）

vibe3 plan --branch <branch>                    # 1. 生成计划
vibe3 handoff show @plan --branch <branch>      # 2. 检查计划
vibe3 run --branch <branch>                     # 3. 执行实现
vibe3 handoff show @report --branch <branch>    # 4. 检查执行结果
vibe3 review --branch <branch>                  # 5. 代码审查
vibe3 handoff show @audit --branch <branch>     # 6. 检查审查结果
vibe3 flow show --branch <branch>               # 7. 查看整体进度
vibe3 run --publish --branch <branch>           # 8. 提交并创建 PR

注意：--branch 可接受分支名或 issue 编号。

3. 提交与收口

/vibe-commit                     # 整理变更并推送到 PR
/vibe-integrate                  # 等待 CI 与 Review，直到 merge-ready
/vibe-done                       # PR 进入终态后做 issue / handoff / 现场收口

---

核心边界与误区

1. flow ≠ branch：flow 是绑定在 branch 上的逻辑上下文；branch 生命周期优先由 git / gh 管理。
2. 真源在 .git/vibe3/handoff.db：所有 worktree 共享该 SQLite 数据库，由主仓库的 git common dir 承载。
3. 不再有 flow new / flow done / 顶层 status：V3 只保留最小共享状态入口；branch / issue / PR 常规生命周期优先直接使用 git / gh。
4. handoff 不是数据库：.git/vibe3/handoff/ 存储的是 Markdown 交接文件，用于人机协作；状态流转以 SQLite 库为准。
   • handoff status 看当前 flow 的交接现场。
   • handoff show <artifact-path> 读取共享 artifact，不再把 handoff show 当成状态总览入口。
5. 恢复已有 branch 统一用 /vibe-continue：/vibe-start 已不再作为现行入口。
6. Orchestra 是后台服务：vibe3 serve 启动心跳轮询，自动处理 Webhook 事件，vibe3 task status 是它的主展示面。
7. 现场判断顺序有主次：先 task status / flow status / flow show 看现场，再用 check 核对同步；blocked 用 task resume 恢复，坏现场用 flow rebuild 重建。

---

故障排查

• 先看现场：运行 vibe3 task status，必要时补 vibe3 flow status / vibe3 flow show。
• 状态不一致：运行 vibe3 check 进行同步审计。
• 恢复特定 blocked issue：运行 vibe3 task resume <issue-number> --label auto。
• 批量恢复 blocked issues：运行 vibe3 task resume --blocked（谨慎使用，会恢复所有 blocked issues）。
• 代码总量 / 单文件超限：先看 config/v3/loc_limits.yaml 的阈值与 exceptions，再决定是否进入质量复查或 exception 处理。
• 环境配置：查看 config/v3/settings.yaml。
• 调用追踪：任何命令加 --trace 可查看内部调用栈。
• 权限/API 错误：运行 bin/vibe keys list 检查 Token 有效性。