vibe

Vibe Skill

用途： 这段代码可以发布了吗？

循环位置

在操作循环的 第 6 步（通过证明验收来关闭 bead） 中，作为每个切片的质量门禁（操作循环）。输入切片的变更；输出关于复杂度、架构、安全性和意图契合度的 PASS/WARN/FAIL。Vibe 回答“这个切片是否已准备好计入切片验证汇总？”——它不能替代切片的第一个失败测试（测试证明行为；vibe 评判实现该行为的代码）。

三个步骤：

1. 复杂度分析 — 找出热点（radon、gocyclo）
2. Bug 搜寻审计 — 系统地检查具体 bug
3. 评审团验证 — 多模型评判

---

快速开始

/vibe                                    # validates recent changes
/vibe recent                             # same as above
/vibe src/auth/                          # validates specific path
/vibe --quick recent                     # fast inline check, no agent spawning
/vibe --structured recent                # 6-phase verification report (build→types→lint→tests→security→diff)
/vibe --deep recent                      # 3 judges instead of 2
/vibe --sweep recent                     # deep audit: per-file explorers + council
/vibe --mixed recent                     # cross-vendor (Claude + Codex)
/vibe --preset=security-audit src/auth/  # security-focused review
/vibe --explorers=2 recent               # judges with explorer sub-agents
/vibe --debate recent                    # two-round adversarial review
/vibe --tier=quality recent              # use quality tier for council calls

---

执行步骤

步骤 0：加载先前评审上下文

评审前，提取先前代码评审中的相关经验和已知模式：

if command -v ao &>/dev/null; then
    ao lookup --query "<target-scope> code review patterns" --limit 3 2>/dev/null || true
fi

应用检索到的知识（返回结果时必须执行）：

如果返回了经验或模式，请勿仅将其作为被动上下文加载。对每个返回项：

1. 检查：这条经验是否适用于正在评审的代码？（回答是或否）
2. 如果适用：在评审中将其列为 known_risk——说明该模式、需要检查的内容，以及代码是否存在该问题
3. 如果某条发现受到该经验影响，请在评审输出中引用其文件名

应用后，记录引用：

ao metrics cite "<learning-path>" --type applied 2>/dev/null || true

如果 ao 不可用或没有返回结果，则静默跳过。

项目评审者配置： 如果 .agents/reviewer-config.md 存在，其完整配置（reviewers、plan_reviewers、skip_reviewers）会传递给 council，用于选择评审者。参见 skills/council/SKILL.md 的步骤 1b。

Crank 检查点检测

通过 git diff 扫描变更文件之前，检查是否存在 crank 检查点：

if [ -f .agents/vibe-context/latest-crank-wave.json ]; then
    echo "Crank checkpoint found — using files_changed from checkpoint"
    FILES_CHANGED=$(jq -r '.files_changed[]' .agents/vibe-context/latest-crank-wave.json 2>/dev/null)
    WAVE_COUNT=$(jq -r '.wave' .agents/vibe-context/latest-crank-wave.json 2>/dev/null)
    echo "Wave $WAVE_COUNT checkpoint: $(echo "$FILES_CHANGED" | wc -l | tr -d ' ') files changed"
fi

如果存在 crank 检查点，请使用其中的 files_changed 列表，而不是通过 git diff 重新检测。这样可以确保 vibe 验证的文件与 crank 修改的文件完全一致。

步骤 1：确定目标

如果提供了目标： 直接使用。

如果未提供目标或目标为“recent”： 从 git 自动检测：

# Check recent commits
git diff --name-only HEAD~3 2>/dev/null | head -20

如果未找到任何内容，请询问用户。

预检：如果未找到文件： 立即返回：“PASS（无变更需要评审）——未检测到已修改的文件。” 空文件列表时请勿启动 Agent。

步骤 1.5a：结构化验证路径（--structured 模式）

如果设置了 --structured 标记， 则运行包含 6 个阶段的机械化验证流水线，而不是评审团流程。该流程会生成机器可读的验证报告，适用于 PR 门禁和 CI 集成。

阶段：构建 → 类型检查 → Lint → 测试 → 安全性 → Diff 评审。

阅读 references/verification-report.md，了解完整的报告模板和各阶段命令。每个阶段都采用失败即停止策略——如果构建失败，则跳过剩余阶段并报告 NOT READY。

所有阶段完成后，将结构化报告写入 .agents/council/YYYY-MM-DD-verification-<target>.md，并向用户输出汇总表。

适用场景： PR 前门禁、CI 集成，以及需要机械化通过/失败结果而非基于判断的评审时。

步骤 1.5：快速路径（--quick 模式）

如果设置了 --quick 标记， 则跳过步骤 2a 至 2e 的繁重预处理，以及步骤 2.5 和 2f，并在执行步骤 2.3、2.4、2g 和步骤 3 后，直接跳到步骤 4，进行内联评审团评审。领域检查清单、编译防护项加载、测试金字塔盘点和内联产品上下文成本低且价值高，因此快速模式下仍会执行。复杂度分析（步骤 2）仍会执行——它成本低且信息丰富。

原因： 步骤 2.5 和 2a–2f 会增加 30–90 秒的预处理时间，主要用于为多评审者评审团准备材料。在 --quick 模式下（单个内联 Agent），这些输入不值得花费相应成本，但测试金字塔和产品上下文检查仍能显著影响内联评审结果。

Step 2：运行复杂度分析

需要语言检测预检、各语言的分析器命令（radon/gocyclo）和分数解读表时，请阅读 references/complexity-analysis.md。运行任何分析器之前，先按差异中出现的语言进行筛选。

Step 2.3：加载特定领域的检查清单

检测目标文件中的代码模式，并从 standards/references/ 加载匹配的特定领域检查清单：

触发条件	检查清单	检测方式
SQL/ORM 代码	sql-safety-checklist.md	文件包含 SQL 查询、ORM 导入（database/sql、sqlalchemy、prisma、activerecord、gorm、knex），或变更集中包含迁移文件
LLM/AI 代码	llm-trust-boundary-checklist.md	文件导入 anthropic、openai、google.generativeai，或匹配 *llm*、*prompt*、*completion* 模式
并发代码	race-condition-checklist.md	文件使用 goroutine、threading、asyncio、multiprocessing、sync.Mutex、concurrent.futures，或共享文件 I/O 模式
Codex 技能	codex-skill.md	文件位于 skills-codex/ 下，或匹配 *codex*SKILL.md、convert.sh、skills-codex-overrides/，或转换器脚本

对于每个匹配的检查清单，使用 Read 工具加载，并将相关条目作为 context.domain_checklists 纳入 council 数据包。可同时加载多个检查清单。

如果没有匹配的模式，则静默跳过。此步骤在 --quick 和完整模式下都会运行（领域检查清单加载成本低且价值高）。

Steps 2.4-2f、2h、3-3.6（深度检查与会前准备）： 阅读 references/deep-checks.md，了解编译预防、过往发现、会前深度分析检查、产品背景、规范加载、抑制项、事前分析关联和模型成本级别。除非设置了 --quick 模式，否则会自动加载。在 --quick 模式下，直接跳至 Step 2g。

编译预防输入： 如果可用，则加载 .agents/pre-mortem-checks/ 和 .agents/planning-rules/。这些编译产物包含来自过往发现的 known_risks，可为审查提供参考；将匹配的发现 ID 带入 council 上下文，以便评审者判断反馈循环是否避免了重复发现。

Step 2a：检查过往发现

如果使用 --quick，则跳过。 从 .agents/findings/registry.jsonl 加载过往发现。

Step 2b：约束测试

如果使用 --quick，则跳过。 运行 .agents/constraints/ 中的编译约束测试。

Step 2c：元数据检查

如果使用 --quick，则跳过。 验证文件元数据的一致性。

Step 2.5：OL 验证

如果使用 --quick，则跳过。 运行组织规范检查。

Step 2d：知识搜索

如果使用 --quick，则跳过。 通过 ao lookup 搜索相关的过往经验。

Step 2e：查找漏洞或深度审计扫描

如果使用 --quick，则跳过。

路径 A — 深度审计扫描（--deep 或 --sweep）：

阅读 references/deep-audit-protocol.md 了解完整流程。概要如下：

1. 按行数将目标文件分成每批 3-5 个文件
2. 并行调度最多 8 个 Explore Agent，每个 Agent 都必须对每个文件使用包含 8 个类别的检查清单
3. 将所有探索者的发现合并到 .agents/council/sweep-manifest.md 中的扫描清单
4. 将扫描清单纳入 council 数据包，以便评审者转入裁定模式

原因： 通才评审者容易产生满足偏差——无论实际问题数量多少，发现少量问题后就会停止。使用逐文件探索者和分类检查清单，可以减少这种偏差，并在 council 裁定前发现具体到行的问题。

路径 B — 轻量级漏洞查找（默认，不使用 --deep/--sweep）：

对目标文件主动开展漏洞审计。

Step 2f：Codex 审查

如果使用 --quick，则跳过。 当使用 --mixed 且 Codex CLI 可用时，将差异的前 2000 个字符发送给 Codex 并行审查。将输入限制为 2000 个字符，以控制在 Codex 上下文预算内。

步骤 3：产品背景

如果使用 --quick，请跳过此步骤，因为它是单独的评审分流步骤。 当 PRODUCT.md 存在且用户未显式传入 --preset 覆盖项时，快速模式仍会在单 Agent 评审中内联加载 DX 预期。在非快速模式下，添加一名 DX（开发者体验）评审：2 名独立评审 + 1 名 DX 评审（共 3 名评审）。DX 评审会评估代码是否符合产品声明的用户画像和价值主张。

步骤 2g：测试金字塔清单（必须执行）

需要完整的清单流程时，请阅读 references/test-pyramid-inventory.md：按模块检查 L0–L3 覆盖率、检查 BF1–BF5 边界、weighted_score 公式、满意度得分的呈现方式、评审委员会数据包的 test_pyramid JSON 结构，以及判定规则。在 --quick 和完整模式下都会运行——检查文件是否存在的成本很低。L0–L1 按 1 倍加权，L2 按 3 倍加权，L3+ 按 5 倍加权；如果只有 L0–L1 且 weighted_score < 0.3，则发出 WARN。

步骤 2g.1：场景→测试覆盖率（切片包含场景时必须执行）

测试金字塔清单（2g）会检查测试是否存在以及结构是否合理——但它不会检查切片中的每个验收场景是否都映射到测试。对此进行把关的末端门禁是 scripts/check-bead-scenario-coverage.sh（C2，ag-9jle.4）。它会解析 bead 的 ## Scenarios 区块（或 .feature 文件），如果任何场景缺少 @covered-by:<test-path> 链接，就会失败——也就是说，它是从行为向前检查，而不是从覆盖率百分比向后检查。

# When validating a tracked bead with a ## Scenarios block:
bash scripts/check-bead-scenario-coverage.sh --bead <bead-id> --json

# When validating a .feature directly:
bash scripts/check-bead-scenario-coverage.sh skills/<skill>/references/<name>.feature --json

此处失败属于氛围门禁，不是 WARN：“测试存在”或覆盖率百分比都不够——每个场景都必须声明一个覆盖它的测试。将 @covered-by:<test-path>（可选添加 ::<TestName>）直接放在每个尚未覆盖的 Scenario: 上方。仅当切片不包含任何场景时才跳过（必须先将自由文本验收条件提升为场景——请参阅工作流约定）。如果当前检出版本中可以运行覆盖测试，优先使用 --run，要求测试实际通过，而不只是存在。

步骤 4：运行评审委员会验证

找到规格说明时——使用 code-review 预设：

/council --preset=code-review validate <target>

• error-paths：追踪每条错误处理路径。有哪些错误未被捕获？有哪些情况会静默失败？
• api-surface：审查每个公共接口。契约是否清晰？是否存在破坏性变更？
• spec-compliance：对照规格说明检查实现。缺少了什么？有哪些不一致？

规格说明内容会注入评审委员会数据包的上下文，以便 spec-compliance 评审能够与实现进行对照。

未找到规格说明时——2 名独立评审（无评审视角）：

/council validate <target>

2 名独立评审（不标注评审视角）。对于高风险评审，使用 --deep 启用 3 名评审。可使用 --quick（内联单 Agent 检查）或 --mixed（与 Codex 跨供应商）覆盖。

评审委员会会收到：

• 要审查的文件
• 复杂度热点（来自步骤 2）
• Git diff 上下文
• 规格说明内容（找到时，位于 context.spec）
• 扫描清单（使用 --deep 或 --sweep 时，位于 context.sweep_manifest——评审人员会切换到裁决模式，请参阅 references/deep-audit-protocol.md）

所有评审委员会标志都会透传：--quick（内联）、--mixed（跨供应商）、--preset=<name>（覆盖评审视角）、--explorers=N、--debate（对抗式两轮评审）、--tier=<name>（模型成本档位：quality/balanced/budget）。请参阅 Quick Start 示例和 /council 文档。

步骤 4.5：禁止自我评分不变量（作者 ≠ 验证者）

验收结论绝不能由产物自身的作者评分。由作者上下文得出的结论存在自相关性——导致 bug 被提交的同样盲点也会让它通过检查。这就是禁止自我评分不变量（ag-lmdx.4）：用于保护 evidenced->validated 转换的独立信任域检查。

规则：评审者上下文必须与作者上下文不同。验证可以在创作会话中运行，但评审者必须是盲审子 Agent——一个全新、上下文隔离的 Agent，按自己没有创作上下文来行事。记录 judge_id（隔离的子 Agent 上下文），并使其不同于 author_id（创作上下文）。如果第 4 步中生成的委员会评审者是上下文隔离的子 Agent，则符合此要求；由创作 Agent 在行内自行评审则不符合。

盲审子 Agent 评审者的启动方式（该机制在创作会话中进行验证时为强制要求）：

如果结论是在编写代码的同一会话中得出的，就必须将验收评审者作为全新上下文的子 Agent 启动——不得在行内评分。具体而言：

1. 通过 Agent/Task 工具启动评审者（即第 4 步委员会所用的同类上下文隔离子 Agent）。子 Agent 是评审者；负责编排的创作 Agent 不是。
2. 只向盲审评审者提供验收输入——绝不能提供创作对话、计划或推理：
   • 待评审的差异/产物（已更改文件及 git diff），
   • 验收场景（bead 的 ## Scenarios 块或 .feature 文件）以及任何规格、复杂度热点和领域检查清单，
   • 结论契约（skills/council/schemas/verdict.json）。 不要传递创作记录、中间设计笔记，也不要加入“这是我认为它正确的原因”之类的说明。评审者应按自己没有创作上下文来行事。
3. 将子 Agent 的 PASS/WARN/FAIL 用作验收结论。将 judge_id（隔离的子 Agent 上下文）和 author_id（创作上下文）记录到 ao turn verify 使用的 turn-input 中（见下文“强制执行”）。

这正是同一会话内验证可信的原因：结论由未创作该产物的上下文得出，因此作者的盲点不会让它通过检查。

如果评审者上下文与作者上下文相同（judge_id == author_id），即没有启动盲审子 Agent、而由创作 Agent 自行评分，则拒绝给出 PASS 结论。应改由盲审子 Agent 评审者重新进行结论评定。

例外：--allow-self（默认关闭）仅在行内备用方案中豁免此不变量（例如没有可用的子 Agent 运行时）。使用此选项会将结论标记为自我评分；下游 ao turn verify 会将其报告为已豁免，而非独立验证。

强制执行：ao turn verify <bead> 根据 turn-input 文件中的 author_id/judge_id 评估 author_neq_validator 谓词；对于自我评分的结论，它会判定 Evidenced-Turn DoD 失败，除非传入 --allow-self。evidenced->validated 守卫会拒绝自我评分的结论。

步骤 5：委员会检查

每位评审者都应检查以下方面：

方面	检查内容
正确性	代码是否实现了所声称的功能？
安全性	注入、身份验证问题、机密信息
边界情况	空值处理、边界、错误
质量	死代码、重复、清晰度
复杂度	高圈复杂度、深层嵌套
架构	耦合、抽象、模式

步骤 6：解读结论

委员会结论：

委员会结论	Vibe 结果	操作
PASS	可交付	合并/部署
WARN	存在需评审的问题	处理问题或接受风险
FAIL	尚未就绪	修复问题

步骤 7：编写 Vibe 报告

写入： .agents/council/YYYY-MM-DD-vibe-<target>.md（使用 date +%Y-%m-%d）

阅读 references/report-format.md，了解完整的 Vibe 报告 Markdown 模板。报告包括：复杂度分析、评审委员会结论表、共同发现／关键发现／信息性发现、所有发现（使用 --deep/--sweep 时）、建议和决策复选框。

步骤 8：向用户报告

告知用户：

1. 复杂度热点（如有）
2. 评审委员会结论（PASS/WARN/FAIL）
3. 主要问题
4. Vibe 报告的位置

步骤 9：记录 Ratchet 进度与步骤 9.5：将发现纳入飞轮

需要了解 PASS/WARN/FAIL ratchet 记录规则、失败重试发现的提取格式，以及 .agents/findings/registry.jsonl 写入约定（dedup_key、applicable_when 词汇、原子重命名规则）和后续的 hooks/finding-compiler.sh 时，请阅读 references/post-verdict-actions.md。

步骤 10：清理测试 Bead

验证完成后，通过 bd close 清理过时的测试 bead（bd list --status=open | grep -iE "test bead|test quest"），以防 bead 污染。如果 bd 不可用，则跳过。

---

与工作流集成

/implement issue-123
    │
    ▼
(coding, quick lint/test as you go)
    │
    ▼
/vibe                      ← You are here
    │
    ├── Complexity analysis (find hotspots)
    ├── Bug hunt audit (find concrete bugs)
    └── Council validation (multi-model judgment)
    │
    ├── PASS → ship it
    ├── WARN → review, then ship or fix
    └── FAIL → fix, re-run /vibe

---

示例

用户说：“对最新更改运行一次快速验证。”

操作：

/vibe recent

验证最近的更改

/vibe recent

对最近的更改运行复杂度分析，然后由评审委员会进行审查。

验证指定目录

/vibe src/auth/

对 auth 目录进行复杂度分析和评审委员会审查。

深度审查

/vibe --deep recent

进行复杂度分析，并由 3 位评审者进行全面审查。

跨供应商共识

/vibe --mixed recent

进行复杂度分析，并由 Claude 和 Codex 评审。

更多示例请参阅 references/examples.md：包含规范合规性检查的安全审计、使用 PRODUCT.md 的开发者体验代码审查，以及快速内联检查。

---

故障排除

问题	原因	解决方案
"COMPLEXITY SKIPPED: radon not installed"	缺少 Python 复杂度分析器	使用 pip install radon 安装，或跳过复杂度分析（评审委员会仍会运行）。
"COMPLEXITY SKIPPED: gocyclo not installed"	缺少 Go 复杂度分析器	使用 go install github.com/fzipp/gocyclo/cmd/gocyclo@latest 安装，或跳过。
Vibe 返回 PASS，但约束测试失败	评审委员会使用的大模型未发现机械性违规	检查 .agents/council/<timestamp>-vibe-*.md 中的约束测试结果。约束检查失败时，以失败结果为准，不采用评审委员会的 PASS。修复违规后重新运行。
跳过 Codex 审查	未传入 --mixed、Codex CLI 不在 PATH 中，或没有未提交的更改	Codex 审查为可选功能——传入 --mixed 即可启用。此外，还需要确保 Codex CLI 在 PATH 中且存在未提交的更改。
"No modified files detected"	工作树干净，没有最近的提交	进行更改，或明确指定目标路径：/vibe src/auth/。
未启动规范合规性评审者	beads 或 plans 中没有规范	在提交信息中引用 bead ID，或在 .agents/plans/ 中创建计划文档。如果没有规范，Vibe 会使用 2 位独立评审者（使用 --deep 时为 3 位）。

---

写入时质量钩子

hooks/write-time-quality.sh PostToolUse 钩子会在每次调用 Write/Edit 工具后自动运行，在编辑时而非审查时捕获常见反模式。它会检查：

• **Go：**未检查的错误、库代码中的 fmt.Print
• **Python：**裸 except:、eval/exec、公开函数缺少类型提示
• **Shell：**缺少 set -euo pipefail、未加引号的变量

该钩子不会阻塞操作（始终以 0 退出），并通过 JSON 输出警告。完整设计请参阅 references/write-time-quality.md。

另请参阅

• skills/council/SKILL.md — 多模型验证委员会
• skills/complexity/SKILL.md — 独立复杂度分析
• skills/bug-hunt/SKILL.md — 主动代码审计与 Bug 调查
• .agents/specs/conflict-resolution-algorithm.md — Agent 发现结果之间的冲突解决
• 测试 — 测试生成与覆盖率分析
• 性能 — 性能分析与基准测试

参考文档

• references/vibe.feature — 可执行规范：委员会裁决（复杂度／架构／安全性／意图契合度）、CRITICAL 时阻止、verdict.json（soc-qk4b）
• references/complexity-analysis.md
• references/deep-checks.md
• references/post-verdict-actions.md
• references/test-pyramid-inventory.md
• references/verification-report.md
• references/write-time-quality.md
• references/deep-audit-protocol.md
• references/examples.md
• references/go-patterns.md
• references/go-standards.md
• references/json-standards.md
• references/markdown-standards.md
• references/patterns.md
• references/python-standards.md
• references/report-format.md
• references/rust-standards.md
• references/shell-standards.md
• references/typescript-standards.md
• references/vibe-coding.md
• references/vibe-suppressions.md
• references/test-pyramid-weighting.md
• references/yaml-standards.md