feature/<描述>      # 新功能
fix/<描述>          # bug 修复
doc/<描述>          # 文档更新
refactor/<描述>     # 重构（无功能变化）
perf/<描述>         # 性能优化
dependabot/<...>    # 依赖更新（自动）

# 创建 worktree
git worktree add ../zeroclaw-telegram-fix feature/telegram-fix

# 现在你有两个目录
# ./zeroclaw/          - main 分支
# ./zeroclaw-telegram-fix/ - telegram-fix 分支

# 你在修复一个 bug（分支 fix/memory-leak）
# 突然需要紧急处理另一个问题

# 传统方式：git stash + checkout
# 容易混乱，容易丢失 stash

# Worktree 方式
git worktree add ../zeroclaw-hotfix fix/urgent-crash
# 完全独立的工作目录，互不干扰

# 需要审查同事的 PR
git worktree add ../zeroclaw-review pr/123
cd ../zeroclaw-review
cargo test  # 在隔离环境测试

# 创建命名规范的 worktree 目录
mkdir -p ~/worktrees/zeroclaw
cd ~/worktrees/zeroclaw

# 为每个任务创建 worktree
git worktree add wt/telegram-fix feature/telegram-fix
git worktree add wt/doc-update doc/api-reference

# 完成后清理
git worktree remove wt/telegram-fix

<type>(<scope>): <description>

[optional body]

[optional footer]

# feat 提交 → 自动包含在 Features 部分
# fix 提交 → 自动包含在 Bug Fixes 部分
# BREAKING CHANGE → 自动包含在 Breaking Changes 部分

feat → minor bump (1.0.0 → 1.1.0)
fix → patch bump (1.0.0 → 1.0.1)
BREAKING CHANGE → major bump (1.0.0 → 2.0.0)

# 快速找到所有 bug 修复
git log --grep="fix:"

# 统计某范围的提交类型
git log --pretty=format:"%s" | grep -c "^feat"

fix bug
update
wip
test

fix(channels/telegram): handle network timeout in webhook handler

Previously, webhook handler would panic on network timeout.
Now it properly returns 503 and retries with exponential backoff.

Closes #123

# 获取变更文件列表
files=$(git diff --name-only main...HEAD)

# 高风险路径检查
if echo "$files" | grep -qE "^src/security/|^src/gateway/|^src/runtime/"; then
    echo "高风险：需要 2 人审查"
    exit 1
fi

## 问题
当前 Telegram webhook 在网络超时时会 panic，导致整个网关崩溃。

## 解决方案
添加超时处理，返回 503 状态码，触发指数退避重试。

## 变更内容
- `src/channels/telegram.rs`: 添加超时处理逻辑
- `src/channels/retry.rs`: 新增指数退避模块
- `tests/telegram_test.rs`: 添加超时场景测试

## 测试
- [x] 单元测试通过
- [x] 集成测试通过（Telegram sandbox）
- [x] 手动测试：模拟 10s 网络延迟，确认行为正确

## 风险与回滚
- 风险：可能影响正常响应延迟（最大重试 3 次）
- 回滚：revert 此 PR 即可

// ✅ 好的命名：描述行为和预期
#[test]
fn parse_config_returns_error_on_invalid_toml() { }

#[test]
fn tool_registry_returns_none_for_unknown_tool() { }

// ❌ 坏的命名：不描述行为
#[test]
fn test1() { }

#[test]
fn config_test() { }

#[cfg(test)]
mod tests {
    use super::*;

    // 给定-当-那么 (Given-When-Then) 模式
    #[test]
    fn execute_returns_tool_result_on_success() {
        // Given: 设置测试环境
        let tool = ShellTool::new();
        let args = json!({"command": "echo hello"});
        
        // When: 执行操作
        let result = tokio_test::block_on(tool.execute(args));
        
        // Then: 验证结果
        assert!(result.is_ok());
        assert_eq!(result.unwrap().output, "hello\n");
    }
}

// 定义 Mock
struct MockProvider {
    response: CompletionResponse,
}

#[async_trait]
impl Provider for MockProvider {
    async fn complete(&self, _: CompletionRequest) -> Result<CompletionResponse> {
        Ok(self.response.clone())
    }
}

#[tokio::test]
async fn agent_uses_tool_when_requested() {
    // 使用 Mock，不依赖网络
    let provider = MockProvider::new(CompletionResponse::with_tool_call("shell", json!({"command": "ls"})));
    let agent = Agent::new(Box::new(provider));
    
    let result = agent.process("list files").await;
    
    assert!(result.contains("file"));
}

// tests/channel_integration_test.rs
#[tokio::test]
async fn telegram_channel_sends_and_receives() {
    // 需要 TELEGRAM_BOT_TOKEN 环境变量
    let token = env::var("TELEGRAM_BOT_TOKEN").expect("need token");
    let channel = TelegramChannel::new(&token);
    
    // 发送测试消息
    let message = OutgoingMessage::text("test message");
    channel.send(message).await.expect("send failed");
    
    // 验证可以通过其他方式收到（如 API 查询）
    // ...
}

// 使用测试隔离
#[tokio::test]
async fn test_isolated() {
    let _guard = TEST_MUTEX.lock().await;  // 串行执行
    // ...
}

// 条件编译跳过
#[tokio::test]
#[ignore = "needs telegram token"]
async fn telegram_test() { }

// 运行：cargo test -- --ignored

# 启动 ZeroClaw
./target/release/zeroclaw service &
ZEROCALW_PID=$!

# 发送测试消息
curl -X POST http://localhost:8080/webhook \
  -H "Content-Type: application/json" \
  -d '{"message": "hello", "chat_id": "test"}'

# 验证响应
# ...

# 清理
kill $ZEROCALW_PID

# 格式检查
cargo fmt --all -- --check

# 静态分析
cargo clippy --all-targets -- -D warnings

# 安全检查
cargo audit
cargo deny check

# 测试
cargo test

# 文档检查
cargo doc --no-deps

// 如果某个 warning 是误报，可以显式允许
#[allow(clippy::too_many_arguments)]
fn some_function(a: A, b: B, c: C, ...) { }

# .git/hooks/pre-commit
#!/bin/bash

# 格式化
cargo fmt -- --check || exit 1

# 静态检查
cargo clippy -- -D warnings || exit 1

# 测试（只运行受影响的）
cargo test --lib || exit 1

echo "Pre-commit checks passed!"

# 生成覆盖率报告
cargo tarpaulin --out Html

# 查看报告
open tarpaulin-report.html

# 简化版 CI 流程
name: CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Swatinem/rust-cache@v2
      
      # 检查
      - run: cargo fmt --all -- --check
      - run: cargo clippy --all-targets -- -D warnings
      - run: cargo audit
      
      # 测试
      - run: cargo test --all-features
      
      # 构建
      - run: cargo build --release --locked
      
      # 上传产物
      - uses: actions/upload-artifact@v4
        with:
          name: zeroclaw-linux
          path: target/release/zeroclaw

strategy:
  matrix:
    include:
      - target: x86_64-unknown-linux-gnu
        os: ubuntu-22.04
      - target: aarch64-unknown-linux-gnu
        os: ubuntu-22.04
      - target: x86_64-apple-darwin
        os: macos-latest

# 使用相同环境
docker run -v $(pwd):/workspace -w /workspace rust:1.75 bash

# 在容器中运行 CI 命令
cargo build --release --locked

# 创建功能分支
git checkout -b feature/my-feature

# 开发循环
cargo build          # 快速编译
cargo test           # 运行测试
cargo fmt            # 格式化
git commit -m "feat(module): description"

# 提交前检查
./scripts/check.sh   # 运行所有检查

# 推送并创建 PR
git push origin feature/my-feature

## 变更类型
- [ ] feat: 新功能
- [ ] fix: bug 修复
- [ ] doc: 文档更新
- [ ] refactor: 重构
- [ ] perf: 性能优化

## 测试
- [ ] 单元测试通过
- [ ] 集成测试通过
- [ ] 手动测试验证

## 风险
- [ ] 低：文档/格式化
- [ ] 中：功能增强
- [ ] 高：安全/运行时变更