Ba Guan

Safety Rules

参见 _shared/core/safety-rules.md — 所有安全规则从共享层加载。

把关 (Pre-Publish Review)

Release Risk Taxonomy

Audit Layers

发布前核弹级审查。三层审查确保发布质量。 Nuclear-grade pre-publish review. Three-layer review ensures release quality.

Quick Commands

三层审查架构/Three-Layer Review

┌─────────────────────────────────────────────────────────────────────┐
│                    发布前三层审查/Pre-Publish Review                 │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  Phase 0: 检测变更 + AI 归属/Detect Changes + AI Attribution         │
│  ├── 变更列表/Change list                                            │
│  ├── AI trailer 解析/Parse Co-Authored-By & Assisted-by              │
│  └── AI 参与度计算/Compute AI participation ratio                    │
│                                                                      │
│  Layer 1: 逐变更审查/Per-Change (最多 10 个智能体)                      │
│  ├── 变更组 A 深度分析/Group A deep analysis                         │
│  ├── 变更组 B 深度分析/Group B deep analysis                         │
│  └── ... (含 AI 归属字段 + 风险乘数)                                   │
│                                                                      │
│  Layer 2: 整体审查/Holistic (5 角色并行/5 roles)                       │
│  ├── 架构师/Architect: 架构合规性                                     │
│  ├── 开发者/Developer: 代码质量                                       │
│  ├── 测试员/Tester: 测试覆盖                                          │
│  ├── 安全专家/Security: 安全检查                                      │
│  └── 文档/Docs: 文档完整性                                            │
│                                                                      │
│  Layer 3: 综合评估/Synthesis (1 个智能体)                               │
│  ├── 风险加权评分/Risk-weighted scoring (AI 参与度 × 基础债务)           │
│  ├── 审查分级路由/Review-tier routing (auto/standard/elevated)        │
│  └── 汇总所有审查结果，给出发行建议/Summary & recommendation           │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

审查流程/Review Workflow

Phase 0: 检测未发布变更 + AI 归属/Detect Changes + AI Attribution

# 获取已发布版本/Get published version
PUBLISHED=$(npm view package-name version 2>/dev/null || echo "not published")

# 获取本地版本/Get local version
LOCAL=$(node -p "require('./package.json').version" 2>/dev/null || echo "unknown")

# 获取变更列表/Get commit list
git log "v${PUBLISHED}"..HEAD --oneline

# 获取变更文件/Get changed files
git diff --name-only "v${PUBLISHED}"..HEAD

# 获取变更统计/Get diff stats
git diff "v${PUBLISHED}"..HEAD --stat

# AI 归属检测/AI attribution detection
git log "v${PUBLISHED}"..HEAD --grep="Co-Authored-By.*noreply" --grep="Assisted-by.*Claude\|Copilot\|GPT\|Gemini\|Aider\|Qwen\|DeepSeek\|Kimi\|Doubao\|Baichuan\|GLM\|Zhipu" --oneline

归属信号解析详见 rules/ai-attribution.md。

Phase 1: 变更分组/Group Changes

## 变更分组/Change Groups

### 新功能/Features (feat)
| 范围/Scope | 文件/Files | 行数/Lines | 复杂度/Complexity |
|-----------|-----------|-----------|-----------------|
| auth | +150/-30 | +120 | 中/Medium |

### Bug 修复/Bug Fixes (fix)
| 范围/Scope | 文件/Files | 行数/Lines | 复杂度/Complexity |
|-----------|-----------|-----------|-----------------|
| api | +20/-15 | +5 | 低/Low |

### 重构/Refactoring (refactor)
...

### 文档/Documentation (docs)
...

Phase 2: Per-Change Review (Up to 10 Agents)

Each change group gets its own parallel review agent. Agents receive only their group's diff.

## Per-Change Review: {GROUP_NAME}

**变更类型/Type**: {feat/fix/refactor/docs}
**影响文件/Files**: {file_list}
**Release Layer**: {npm|pypi|generic}

### Correctness / 正确性
- [ ] Logic correct for 3+ scenarios — trace through the code
- [ ] Edge cases handled (empty/null/large/concurrent)
- [ ] Error handling proper — no empty catch, no swallowed promises
- [ ] Breaking changes? If YES, what breaks and for whom?
- [ ] Hardcoded credentials or secrets? BLOCK immediately

### Test Coverage / 测试覆盖
- [ ] Unit tests for new/changed behavior
- [ ] Tests meaningful (not coverage padding)
- [ ] Regression tests for bug fixes

### Code Quality / 代码质量
- [ ] Type safety — no `as any`, `@ts-ignore`, `@ts-expect-error`
- [ ] Follows existing patterns in the file/package
- [ ] No introduced duplication
- [ ] Imports/exports clean — no side effects

### Evidence Links / 证据链接
- [文件](https://github.com/...)#L10-L50 — specific changed code
- [提交](https://github.com/.../commit/abc) — relevant commit

### Verdict / 判定
**{PASS | FAIL | CAUTION}**
**Risk: {SAFE | CAUTION | RISKY | BLOCK}**
**Has Breaking Changes: {YES | NO}**

### Blocking Issues / 阻塞问题
[Issues that MUST be fixed before publish. Empty if PASS.]

Phase 3: 整体审查/Holistic Review

## 整体审查报告/Holistic Review

### 架构审查/Architecture
**通过/Pass**:
- ✅ 架构设计合理/Design reasonable
- ✅ 模块划分清晰/Modules clear

**改进/Improve**:
- ⚠️ 建议增加配置层/Add config layer

### 代码审查/Code
**通过/Pass**:
- ✅ 代码风格一致/Consistent style
- ✅ 无严重问题/No critical issues

**改进/Improve**:
- ⚠️ 部分函数过长/Some functions too long

### 测试审查/Tests
**通过/Pass**:
- ✅ 核心功能有测试/Core tested

**改进/Improve**:
- ⚠️ 边界测试不足/Edge tests insufficient

### 安全审查/Security
...

### 文档审查/Docs
...

Phase 4: 综合评估/Synthesis

## 发布综合评估/Release Assessment

**版本建议/Version**: {patch/minor/major}
**发布风险/Risk**: {低/Low/中/Medium/高/High}
**AI 参与度/AI Participation**: {X}/{Y} commits ({percentage}%)
**AI 风险乘数/AI Risk Multiplier**: {1.0x ~ 1.5x}
**审查分级/Review Tier**: {auto/standard/elevated}

### 审查汇总/Summary
| 层次/Layer | 状态/Status | 问题数/Issues | AI 参与/AI |
|-----------|------------|--------------|-----------|
| 逐变更/Per-Change | ✅/⚠️ | {count} | {percentage}% |
| 整体/Holistic | ✅/⚠️ | {count} | — |
| 综合/Synthesis | ✅/⚠️ | {count} | — |

### 风险加权评分/Risk-Weighted Score
技术债 = (基础债务) × (AI 风险乘数)
- 基础债务: {base_debt} (高危×3 + 中危×1 + 覆盖率缺口×0.5 + 重复×0.3)
- AI 乘数: {multiplier} (基于 {percentage}% AI 参与度)
- 最终得分: {final_score} (越低越好，0 = 无债务)

### 审查分级路由/Review Tier Routing
- Tier: {auto | standard | elevated}
- 理由: {为何路由到此分级}
- 动作: {auto-merge | standard review | request extra reviewers}

### 发布清单/Checklist
- [ ] 所有 P0 问题已解决/All P0 resolved
- [ ] 测试覆盖率达标/Coverage达标
- [ ] 文档已更新/Docs updated
- [ ] 版本号已升级/Version bumped
- [ ] AI 归属已确认/AI attribution verified

### 决策/Decision
{可以发布/Ready / 需要修复/Fix needed / 不建议发布/Not ready}

版本建议规则/Version Rules

【版本升级/Version Bump】

Major (主版本):
- 有破坏性变更/Breaking changes
- API 不兼容/API incompatible

Minor (次版本):
- 有新功能/New features
- 向后兼容/Backward compatible

Patch (修订号):
- 只有 Bug 修复/Bug fixes only
- 文档更新/Docs only

输出报告/Output Reports

/tmp/{YYYYMMDD-HHmmss}/
├── changes.md        # 变更分析/Change analysis
├── per-change-*.md   # 逐变更审查/Per-change review
├── holistic.md       # 整体审查/Holistic review
└── release-review.md # 综合报告/Final report

使用示例/Examples

用户/User: /把关

→ Phase 0: 检测变更 + AI 归属/Detect changes + AI attribution
→ Phase 1: 变更分组（含 AI 归属字段）/Group changes with attribution
→ Phase 2: 逐变更审查/Per-change review (parallel, with risk multiplier)
→ Phase 3: 整体审查/Holistic review (5 roles)
→ Phase 4: 综合评估 + 风险加权评分 + 审查分级路由/Synthesis + scoring + routing
→ 输出发行建议/Output recommendation

Integration with Other Skills / 与其他技能集成

• Use /architect review from master-architect for architectural review during the Layer 2 holistic phase. Run /architect review to validate module cohesion, interface contracts, and test coverage alongside ba-guan's own multi-role analysis.
• Use /安检 from an-jian for security audit. Run /安检 scan as a dedicated security pass, then feed results into ba-guan's Layer 2 security review for the final report.
• Use /审视 <URL> from shen-shi for GitHub-based code review patterns. Apply /审视 to analyze related PRs and issues before finalizing the release assessment, borrowing evidence-based review methodology.
• Use /iterate <n> from iteration-manager for iterative improvement cycles after review. When ba-guan's report identifies issues, run /iterate 3 to fix them and re-verify before the final /把关 decision.

Rules

• rules/change-detection.md - 变更检测/Change Detection
• rules/ai-attribution.md - AI 归属检测/AI Attribution Detection
• rules/review-roles.md - 审查角色/Review Roles
• rules/version-bump.md - 版本规则/Version Rules
• rules/anti-aigc.md - 分析报告反AIGC检测规则

配置选项/Configuration

Anti-Patterns / 反模式

Verdict Logic / 判定逻辑

BLOCK if:
  - Any per-change agent found CRITICAL blocking issues
  - Holistic review failed on security or correctness
  - Breaking changes without migration plan
  - AI 参与安全文件(auth/permissions/crypto)且无人工确认 — elevated tier 必须

RISKY if:
  - Multiple per-change agents returned FAIL or CAUTION
  - Holistic review passed but with significant findings
  - Large surface area changes (>500 lines)
  - AI 参与度 > 60% 且有中危以上 issue

CAUTION if:
  - A few minor issues flagged
  - Holistic review passed cleanly
  - Medium surface area (100-500 lines)
  - AI 参与度 > 30% 但无高危 issue → standard tier

SAFE if:
  - All per-change agents passed
  - Holistic review passed on all roles
  - Small surface area (<100 lines) OR well-tested
  - AI 参与度 < 30% 且无高危 → auto tier 候选

Review Tier Routing / 审查分级路由

基于 AI 参与度和质量信号，自动路由审查等级（详见 rules/ai-attribution.md）：

核心原则：用 AI 不是罪。 AI 参与度只作为风险乘数（1.0~1.5x），不直接判定 BLOCK。 干净的 100% AI 变更（无 issue、测试充分）得分接近 0，可走 auto tier。

常见问题与排查 / Troubleshooting

审查无变更可发现 / No changes detected

• 症状/Symptom: /把关 check 报告0个变更 / reports zero changes
• 解决/Fix: 检查 git diff --stat 是否有变更；确认分支追踪正确；使用 /把关 check --unstaged 包含未暂存变更

审查角色冲突建议 / Conflicting review recommendations

• 症状/Symptom: 架构师和开发者给出相反建议 / Architect and Developer give opposite recommendations
• 解决/Fix: 使用 /把关 --synthesize 触发综合器汇总；手动审查冲突点；设定优先级：安全 > 架构 > 测试 > 文档

逐变更审查超时 / Per-change review timeout

• 症状/Symptom: 单次变更审查超过5分钟上限 / Single change review exceeds 5min limit
• 解决/Fix: 减少每个变更组的文件数；使用 /把关 --max-files 5 限制每组文件数；增加 --timeout 参数

边界情况 / Edge Cases

• 空仓库首次发布: 绕过错层分析，只做整体评审和文档检查
• 大量变更(>100文件): 自动分组到10个智能体上限；超过部分排队处理
• Monorepo发布: 使用 --scope <package> 限定审查范围到单个包
• 紧急发布: 使用 /把关 --urgent 跳过文档审查层，仅做安全+架构审查
• 回滚发布: 比较回滚前后的diff，标记回滚引入的新风险

AIGC-Aware Output / AIGC检测意识

Review reports must contain specific evidence (file paths, line numbers) and actionable fixes, not generic "needs improvement" statements. Every finding must have priority P0/P1/P2 classification. See rules/anti-aigc.md for complete anti-AIGC detection rules.

核心要求：

• 每个问题必须附文件路径和行号
• 不写"建议改进代码质量"，写"core/auth.py:47 的SQL注入，攻击者可绕过认证——P0，必须修了再上线"
• 重要问题5段话详细分析，次要问题1句带过
• 修复建议必须可操作，包含具体命令或代码修改

版本历史 / Version History

See Also / 相关技能

• /安检 from an-jian — 整体审查中的安全审计层 / Security audit layer in holistic review
• /architect review from master-architect — 整体审查中的架构审查层 / Architecture review layer in holistic review
• /合并 from he-bing — 审查通过后的 PR 工作流 / PR workflow after review passes
• /审视 from shen-shi — 基于 GitHub 的代码审查模式 / GitHub-based code review patterns