# 使用指南

本文档详细说明如何使用 Kaka 系统。

## 目录

- [触发方式](#触发方式)
- [工作流程](#工作流程)
- [查看日志](#查看日志)
- [Dashboard 使用](#dashboard-使用)

---

## 触发方式

### 方式 1: 标签触发（推荐）

1. 在 GitHub Issue 中添加 `ai-dev` 标签
2. 系统自动接收 Webhook 并开始处理

```
Issue #123: 修复登录 Bug
Labels: ai-dev, bug
```

### 方式 2: 评论触发

1. 在 GitHub Issue 中评论 `/ai develop`
2. 系统自动接收评论事件并开始处理

```
User123: /ai develop
```

---

## 工作流程

```
┌─────────────────────────────────────────────────────────────────────┐
│                        自动化开发流程                                │
└─────────────────────────────────────────────────────────────────────┘

1. 触发事件
   ├─ 标签触发: 添加 ai-dev 标签
   └─ 评论触发: 发送 /ai develop 命令

2. Webhook 接收
   ├─ 验证签名（HMAC-SHA256）
   ├─ 解析事件类型和数据
   └─ 验证触发条件

3. 任务创建
   ├─ 生成分支名: ai/feature-{issue_number}-{timestamp}
   ├─ 创建 Commit 信息
   └─ 初始化任务队列

4. AI 开发
   ├─ Claude Code CLI 分析需求
   ├─ 自动编写代码
   ├─ 运行测试（如果启用）
   └─ 提交代码

5. Git 操作
   ├─ 创建新分支
   ├─ 提交代码
   └─ 推送到远程仓库

6. PR 创建
   ├─ 生成 PR 标题和描述
   ├─ 关联原 Issue
   └─ 通知相关人员

7. 完成
   └─ 返回任务结果和日志
```

---

## 查看日志

### 实时日志

```bash
# 查看实时日志
tail -f logs/kaka.log

# 或使用 CLI 工具
kaka logs

# 使用开发模式启动（日志输出到控制台）
kaka start --reload
```

### 日志级别

日志级别在 `config/config.yaml` 中配置：

- `DEBUG`: 详细的调试信息
- `INFO`: 一般信息（默认）
- `WARNING`: 警告信息
- `ERROR`: 错误信息
- `CRITICAL`: 严重错误

### 日志格式

```
2024-01-08 10:30:45 - app.main - INFO - ➤ POST /webhook/github
2024-01-08 10:30:45 - app.services.webhook_handler - INFO - 收到 Webhook: delivery=123456-7890, event=labeled
2024-01-08 10:30:46 - app.services.github_service - INFO - Issue #123: 修复登录 Bug
2024-01-08 10:30:47 - app.services.git_service - INFO - 创建分支: ai/feature-123-1704685847
```

---

## Dashboard 使用

### 访问 Dashboard

启动服务后，访问：
```
http://localhost:8000/dashboard
```

### 功能说明

#### 1. 统计卡片

- **总任务**: 显示所有任务总数
- **运行中**: 当前正在执行的任务
- **已完成**: 成功完成的任务
- **失败**: 执行失败的任务

#### 2. 任务列表

显示所有任务的详细信息：

| 列 | 说明 |
|------|------|
| **任务 ID** | 唯一任务标识符 |
| **Issue** | GitHub Issue 链接 |
| **标题** | Issue 标题 |
| **状态** | pending/running/completed/failed/cancelled |
| **创建时间** | 任务创建时间 |
| **执行时间** | 任务执行耗时 |
| **操作** | 查看详情、取消、重试 |

#### 3. 状态筛选

可以通过下拉框筛选不同状态的任务：
- 全部
- 待处理
- 运行中
- 已完成
- 失败
- 已取消

#### 4. 操作按钮

- **查看详情**: 打开日志流模态框，查看实时日志
- **取消**: 取消正在运行的任务
- **重试**: 重新执行失败的任务

### 快捷键

- **R**: 刷新页面
- **C**: 打开配置向导
- **W**: 复制 Webhook URL
- **?**: 显示帮助
- **ESC**: 关闭模态框

### 自动刷新

- 默认每 10 秒自动刷新任务列表
- 可通过复选框控制自动刷新开关
- 点击"立即刷新"按钮手动刷新

---

## 常见操作

### 查看任务详情

1. 在任务列表中点击"查看详情"
2. 打开日志流模态框
3. 实时查看任务执行日志
4. 对于运行中的任务，支持实时日志流
5. 对于已完成的任务，显示历史日志

### 取消任务

**方式 1**: 在任务列表中点击"取消"按钮

**方式 2**: 在日志流模态框中点击"取消"按钮

注意：只有运行中或待处理的任务可以取消。

### 重试失败任务

**方式 1**: 在任务列表中点击"重试"按钮

**方式 2**: 在日志流模态框中点击"重试"按钮

注意：只有失败或已取消的任务可以重试。

### 复制 Webhook URL

在 Dashboard 顶部点击"📋 复制 Webhook URL"按钮。

---

## CLI 命令

### 服务管理

```bash
# 启动服务
kaka start

# 启动开发服务器（自动重载）
kaka start --reload

# 查看服务状态
kaka status

# 查看日志
kaka logs
```

### 配置管理

```bash
# 打开配置向导
kaka configure

# 导出配置
kaka config export > config-backup.json

# 导入配置
kaka config import < config-backup.json

# 验证配置
kaka config validate
```

---

## 开发者命令

### Makefile 命令

```bash
# 开发相关
make dev              # 启动开发服务器
make test             # 运行测试
make coverage         # 生成覆盖率报告

# 日志相关
make logs             # 查看实时日志
make logs-recent      # 查看最近 50 行日志
make logs-error       # 查看错误日志

# 代码质量
make lint             # 代码检查
make format           # 代码格式化
make check            # 运行所有检查
```

---

## 下一步

- [配置说明](CONFIGURATION.md) - 详细配置指南
- [开发指南](DEVELOPMENT.md) - 开发者文档
- [日志系统](LOGGING.md) - 日志配置和使用
