教程概述
系列索引: gstack 教程系列
安全第一：/careful、/freeze、/guard 防止意外。然后用 Conductor 协调 10-15 个同时工作的代理。
你将学到
- ✅
/careful破坏性命令警告 - ✅
/freeze目录编辑锁定 - ✅
/guard组合安全模式 - ✅
/investigate系统化调试 - ✅
/unfreeze释放锁定 - ✅ Conductor 并行 sprint 协调
为什么需要安全护栏？
强大 AI 的危险
flowchart LR
A[AI 代理] --> B[rm -rf]
B --> C[文件消失]
C --> D[无备份]
style B fill:#ffcccc
style D fill:#ffcccc
保护层
flowchart TD
A[用户请求] --> B{破坏性?}
B -->|是| C[/careful 警告]
C --> D{用户确认?}
D -->|否| E[中止]
D -->|是| F{在冻结中?}
F -->|是| G[/freeze 检查]
G --> H{正确目录?}
H -->|否| E
H -->|是| I[执行]
F -->|否| I
style C fill:#fff3e0
style E fill:#e8f5e9
style G fill:#ffebee
/careful — 破坏性命令保护
阻止什么
| 命令类别 | 示例 | 保护 |
|---|---|---|
| 文件删除 | rm -rf、rmdir |
需要确认 |
| 数据库 | DROP TABLE、DELETE FROM |
需要确认 |
| Git | git push --force、git reset --hard |
需要确认 |
| 环境 | rm .env、truncate 文件 |
需要确认 |
| 系统 | sudo、chmod 777 |
需要确认 |
使用
/careful
输出：
┌────────────────────────────────────────────┐
│ CAREFUL 模式已激活 │
├────────────────────────────────────────────┤
│ 受保护的命令： │
│ ✅ rm -rf │
│ ✅ git push --force │
│ ✅ DROP TABLE │
│ ✅ DELETE FROM │
│ ✅ truncate │
│ ✅ sudo 命令 │
│ │
│ 这些命令需要确认。 │
└────────────────────────────────────────────┘
确认提示
当检测到危险命令：
⚠️ 检测到破坏性命令
命令: rm -rf node_modules
这将永久删除 node_modules 及所有内容。
输入 'CONFIRM' 继续，或 'CANCEL' 中止：
始终开启的保护
/careful 在 gstack 中默认启用。禁用：
/careful off
（不推荐 — 每次确认更安全）
/freeze — 目录编辑锁定
它做什么
将所有编辑锁定到单个目录。防止焦点区域外的意外更改。
使用
/freeze src/auth
输出：
┌────────────────────────────────────────────┐
│ FREEZE 已激活 │
├────────────────────────────────────────────┤
│ 编辑锁定: src/auth/ │
│ │
│ 所有编辑必须在以下范围内： │
│ - src/auth/login.ts │
│ - src/auth/session.ts │
│ - src/auth/middleware.ts │
│ │
│ 被阻止的目录： │
│ ❌ src/api/ │
│ ❌ src/components/ │
│ ❌ tests/ │
│ ❌ 任何其他路径 │
│ │
│ 用 /unfreeze 释放。 │
└────────────────────────────────────────────┘
被阻止时
尝试在冻结外编辑：
❌ FREEZE 违规
尝试编辑: src/api/users.ts
冻结锁定到: src/auth/
文件 src/api/users.ts 在冻结目录之外。
要编辑此文件：
1. /unfreeze 释放当前锁定
2. /freeze src/api 锁定到新目录
3. 或继续专注于 src/auth/
使用场景
| 场景 | 为什么冻结 |
|---|---|
| Bug 调查 | 专注于受影响模块 |
| 重构 | 防止范围蔓延 |
| 功能开发 | 待在自己的区域 |
| 并行代理 | 每个代理有自己的目录 |
/guard — 组合安全
包含什么
/guard = /careful + /freeze
/guard src/auth
输出：
┌────────────────────────────────────────────┐
│ GUARD 模式已激活 │
├────────────────────────────────────────────┤
│ 🔒 编辑锁定: src/auth/ │
│ ⚠️ 破坏性命令保护: 开启 │
│ │
│ 完整安全已启用： │
│ - 编辑限制在 src/auth/ │
│ - 破坏性命令需要确认 │
│ - Git force 操作被阻止 │
│ │
│ 用 /unfreeze 释放。 │
└────────────────────────────────────────────┘
何时使用
- 调查生产问题
- 处理关键代码路径
- 并行代理协调
- 学习新代码库（防止意外）
/investigate — 系统化调试
它做什么
- 自动激活
/freeze到受影响目录 - 系统化追踪问题
- 记录发现
- 基于证据提出修复
使用
/investigate "OAuth 用户登录静默失败"
输出：
开始调查: "OAuth 用户登录静默失败"
┌────────────────────────────────────────────┐
│ 调查模式 │
├────────────────────────────────────────────┤
│ 🔒 自动冻结: src/auth/ │
│ 📋 假设跟踪: 开启 │
│ 📝 证据日志: .gstack/investigate.md │
└────────────────────────────────────────────┘
步骤 1: 重现问题
─────────────────────────────
正在测试 OAuth 登录流程...
❌ 确认: 登录返回 200 但会话未创建
用户被重定向到仪表板但显示为登出
步骤 2: 追踪代码路径
─────────────────────────────
src/auth/oauth.ts:45 → handleOAuthCallback()
src/auth/session.ts:23 → createSession()
⚠️ 发现: createSession() 在用户存在于 DB 前被调用
步骤 3: 检查会话创建
─────────────────────────────
src/auth/session.ts:23-35
```typescript
async function createSession(userId: string) {
const user = await getUser(userId); // 用户未创建时返回 null
if (!user) {
return null; // 静默失败！
}
return Session.create(userId);
}
步骤 4: 根本原因已识别 ───────────────────────────── 问题: OAuth 回调和用户创建之间的竞态条件
时间线：
- OAuth 提供者返回成功
- createSession() 立即被调用
- 用户记录尚未插入
- 会话静默失败
- 用户被重定向但未登录
步骤 5: 建议修复 ───────────────────────────── 选项 A: 在会话前等待用户创建（推荐） 选项 B: 带退避重试会话创建 选项 C: 返回显式错误而非静默失败
是否要我实现选项 A？
### 调查日志
所有发现保存到 `.gstack/investigate.md`：
```markdown
# 调查: OAuth 用户登录静默失败
日期: 2026-04-07
## 问题
登录返回 200 但 OAuth 用户会话未创建。
## 根本原因
src/auth/session.ts:23 中的竞态条件
createSession() 在用户记录存在前被调用。
## 证据
- 已重现: 是
- 受影响文件: src/auth/oauth.ts, src/auth/session.ts
- 追踪路径: oauth callback → session creation
## 修复选项
A) 等待用户创建（推荐）
B) 带退避重试
C) 显式错误
## 状态
等待用户决定修复方法。
/unfreeze — 释放锁定
使用
/unfreeze
输出：
┌────────────────────────────────────────────┐
│ FREEZE 已释放 │
├────────────────────────────────────────────┤
│ 之前锁定: src/auth/ │
│ │
│ 所有目录现在可编辑。 │
│ 破坏性命令保护: 仍开启 │
│ │
│ 用 /freeze <目录> 再次锁定。 │
└────────────────────────────────────────────┘
Conductor — 并行 Sprint 协调
它做什么
协调 10-15 个并行 Claude Code 会话，处理代码库的不同部分。
架构
flowchart TD
A[Conductor] --> B[代理 1: Auth]
A --> C[代理 2: API]
A --> D[代理 3: UI]
A --> E[代理 4: 测试]
A --> F[代理 5: 文档]
A --> G[... 还有 10 个]
B --> H[src/auth/]
C --> I[src/api/]
D --> J[src/components/]
E --> K[tests/]
F --> L[docs/]
style A fill:#e1f5ff
设置
/conductor start --agents 10
输出：
┌─────────────────────────────────────────────────────────────┐
│ CONDUCTOR: 并行 SPRINT 协调 │
├─────────────────────────────────────────────────────────────┤
│ 代理: 10 │
│ 模式: 隔离（各有自己的 worktree） │
│ │
│ 代理分配： │
│ ─────────────────────────────────────────────────────────────│
│ 代理 1: src/auth/ → 实现 OAuth2 │
│ 代理 2: src/api/ → 添加速率限制 │
│ 代理 3: src/components/ → 仪表板重设计 │
│ 代理 4: tests/ → Auth 测试覆盖 │
│ 代理 5: docs/ → API 文档 │
│ 代理 6: src/db/ → 迁移脚本 │
│ 代理 7: src/utils/ → 重构 helpers │
│ 代理 8: tests/ → 集成测试 │
│ 代理 9: src/api/ → 端点验证 │
│ 代理 10: src/auth/ → 会话管理 │
│ │
│ 安全: 每个代理冻结到分配的目录 │
│ 通信: 共享任务板在 .gstack/tasks/ │
│ │
│ 命令： │
│ /conductor status - 检查进度 │
│ /conductor review <代理> - 审查代理工作 │
│ /conductor merge - 合并完成的工作 │
│ /conductor stop - 结束 sprint │
└─────────────────────────────────────────────────────────────┘
Sprint 已开始。代理并行工作中。
检查状态: /conductor status
检查状态
/conductor status
输出：
┌─────────────────────────────────────────────────────────────┐
│ CONDUCTOR 状态 │
├─────────────────────────────────────────────────────────────┤
│ Sprint: feature/auth-system │
│ 持续时间: 2h 34m │
│ │
│ 代理进度： │
│ ─────────────────────────────────────────────────────────────│
│ 1. Auth ████████████████████ 100% ✅ 完成 │
│ 2. API ████████████████░░░░ 80% 🔄 测试中 │
│ 3. UI ████████████████████ 100% ✅ 完成 │
│ 4. Tests ████████████░░░░░░░░ 60% 🔄 进行中 │
│ 5. Docs ████████████████████ 100% ✅ 完成 │
│ 6. DB ████████████████████ 100% ✅ 完成 │
│ 7. Utils ████████████████░░░░ 85% 🔄 最后调整 │
│ 8. Tests ████████░░░░░░░░░░░░ 40% 🔄 进行中 │
│ 9. API ████████████████████ 100% ✅ 完成 │
│ 10. Auth ████████████████░░░░ 75% 🔄 合并中 │
│ │
│ 概要： │
│ 完成: 5/10 │
│ 进行中: 5/10 │
│ 阻塞: 0/10 │
│ │
│ 预计完成时间: 45 分钟 │
└─────────────────────────────────────────────────────────────┘
审查代理工作
/conductor review agent-2
输出：
┌─────────────────────────────────────────────────────────────┐
│ 代理 2 审查: API 速率限制 │
├─────────────────────────────────────────────────────────────┤
│ 变更文件: 4 │
│ 添加行: 127 │
│ 删除行: 23 │
│ │
│ 变更： │
│ ─────────────────────────────────────────────────────────────│
│ src/api/middleware/rateLimit.ts (新建) │
│ - Token bucket 实现 │
│ - 按 IP 和按用户限制 │
│ - 分布式系统的 Redis 支持 │
│ │
│ src/api/index.ts │
│ - 给所有路由添加速率限制中间件 │
│ │
│ tests/api/rateLimit.test.ts (新建) │
│ - Token bucket 单元测试 │
│ - 速率限制集成测试 │
│ │
│ docs/api/rate-limiting.md (新建) │
│ - 使用文档 │
│ - 配置选项 │
│ │
│ 审查状态: 待定 │
│ │
│ [A]批准 | [R]请求变更 | [V]查看文件 │
└─────────────────────────────────────────────────────────────┘
合并完成的工作
/conductor merge
输出：
正在合并已完成的代理工作...
┌─────────────────────────────────────────────────────────────┐
│ CONDUCTOR 合并 │
├─────────────────────────────────────────────────────────────┤
│ 正在检查冲突... │
│ ✅ 未检测到冲突 │
│ │
│ 按顺序合并： │
│ ─────────────────────────────────────────────────────────────│
│ 1. 代理 6 (DB) → 基础 │
│ 2. 代理 1 (Auth) → 干净合并 │
│ 3. 代理 10 (Auth) → 干净合并 │
│ 4. 代理 9 (API) → 干净合并 │
│ 5. 代理 3 (UI) → 干净合并 │
│ 6. 代理 5 (Docs) → 干净合并 │
│ │
│ 剩余（未就绪）： │
│ - 代理 2 (API): 80% 完成 │
│ - 代理 4 (Tests): 60% 完成 │
│ - 代理 7 (Utils): 85% 完成 │
│ - 代理 8 (Tests): 40% 完成 │
│ │
│ ✅ 已合并 6 个代理到 main │
│ │
│ 继续前运行测试： │
│ npm test │
└─────────────────────────────────────────────────────────────┘
语音输入触发
AquaVoice 和 Whisper 友好
说这些短语来触发技能：
| 说这个 | 触发 |
|---|---|
| “be careful” | /careful |
| “freeze this directory” | /freeze <当前> |
| “guard mode” | /guard <当前> |
| “investigate this bug” | /investigate |
| “unfreeze” | /unfreeze |
| “start parallel sprint” | /conductor start |
| “check conductor status” | /conductor status |
主动技能建议
上下文感知推荐
gstack 根据上下文建议技能：
┌────────────────────────────────────────────┐
│ 技能建议 │
├────────────────────────────────────────────┤
│ 检测到: 多次登录失败尝试 │
│ │
│ 考虑运行： │
│ /investigate "auth failures" │
│ │
│ 这将： │
│ - 冻结到 src/auth/ │
│ - 追踪失败路径 │
│ - 记录发现 │
└────────────────────────────────────────────┘
技能快速参考
| 命令 | 用途 | 范围 |
|---|---|---|
/careful |
破坏性命令保护 | 全局 |
/careful off |
禁用保护 | 不推荐 |
/freeze <目录> |
锁定编辑到目录 | 指定目录 |
/unfreeze |
释放目录锁定 | 全局 |
/guard <目录> |
组合安全模式 | 指定目录 |
/investigate <问题> |
系统化调试 | 自动冻结 |
/conductor start |
开始并行 sprint | 多代理 |
/conductor status |
检查 sprint 进度 | 所有代理 |
/conductor merge |
合并完成的工作 | 就绪代理 |
总结
gstack 中的安全和并行协调提供：
- 破坏性命令保护 — 删除前三思
- 目录冻结 — 待在自己的区域
- 组合守卫模式 — 最大安全
- 系统化调查 — 带证据调试
- 并行 sprint — 10-15 个代理，一个代码库
关键要点
- ✅ 始终保持
/careful开启 - ✅ 专注一个区域时用
/freeze - ✅ 关键工作时用
/guard - ✅ 复杂 bug 用
/investigate - ✅ 并行功能开发用 Conductor
系列导航：
- ← 上一篇: 教程 11：文档与回顾
- 返回: 系列索引