# Snow CLI 使用文档——异步任务管理

异步任务功能允许你在后台运行耗时的 AI 任务，同时继续使用终端进行其他工作。任务会在独立进程中运行，不会阻塞你的操作。

## 什么是异步任务

异步任务适用于以下场景：

- 需要长时间运行的代码分析和重构
- 批量文件处理和转换
- 生成详细的项目文档
- 执行复杂的多步骤操作

你可以创建任务后让它在后台执行，稍后查看结果，或在需要时审批敏感操作。

## 创建后台任务

在终端中使用 `--task` 参数创建后台任务：

```bash
snow --task "分析项目代码并生成架构文档"
```

执行后会显示任务信息并立即返回：

```text
Task created: abc-123-def-456
Title: 分析项目代码并生成架构文档
Use "snow --task-list" to view task status
```

任务会在后台独立进程中运行，你可以继续使用终端做其他事情。

## 打开任务管理器

有两种方式打开任务管理器查看和管理后台任务：

### 1、命令行启动

```bash
snow --task-list
```

### 2、欢迎页菜单

启动 Snow CLI 后，在主菜单中选择"任务管理器"选项。

## 查看任务列表

进入任务管理器后，你会看到所有任务的列表，每个任务显示：

- 状态图标和颜色
- 任务标题（提示词的前 50 个字符）
- 最后更新时间
- 消息数量

### 任务状态

- `○` 黄色 - 待执行：任务已创建但还未开始
- `◐` 青色 - 运行中：任务正在后台执行
- `⏸` 洋红色 - 已暂停：检测到敏感命令，等待你审批
- `●` 绿色 - 已完成：任务执行成功
- `✗` 红色 - 失败：任务执行出错

## 操作快捷键

### 在任务列表中

- `↑` `↓` - 上下移动选择
- `Space` - 标记/取消标记任务（用于批量删除）
- `Enter` - 查看任务详情
- `D` - 删除任务
  - 单个删除：选中后按 `D`，再按 `D` 确认
  - 批量删除：先用 `Space` 标记多个任务，按 `D`，再按 `D` 确认
- `R` - 刷新任务列表
- `Esc` - 退出任务管理器

### 在任务详情页

- `C` - 将任务转为会话继续对话
  - 按一次 `C` 显示提示
  - 再按一次 `C` 确认转换
- `A` - 同意执行敏感命令（仅暂停状态可用）
- `R` - 拒绝敏感命令（仅暂停状态可用）
- `Esc` - 返回任务列表

## 审批敏感命令

当后台任务需要执行危险操作时（如删除文件、重置代码等），会自动暂停并等待你的审批。

### 审批步骤

1. 在任务列表中看到暂停图标 `⏸` 和洋红色状态
2. 按 `Enter` 进入任务详情
3. 查看黄色警告框中显示的具体命令
4. 根据情况选择：
   - 按 `A` - 同意执行，任务继续运行
   - 按 `R` - 拒绝执行

### 拒绝命令并说明原因

1. 在暂停任务详情页按 `R`
2. 进入输入模式，光标显示为 █
3. 输入拒绝原因，例如："权限不足，请手动执行"
4. 按 `Enter` 提交
5. 按 `Esc` 取消输入

拒绝后，AI 会收到你的原因并据此调整后续操作。

### 配置敏感命令

你可以自定义哪些命令需要审批，详见[敏感命令配置](./06.敏感命令配置.md)。

## 将任务转为会话

完成的任务可以转换为普通会话，这样你就能继续与 AI 对话，询问更多细节或请求修改。

### 转换方法

1. 在任务列表中选择任务
2. 按 `Enter` 查看详情
3. 按 `C` 键（显示确认提示）
4. 再按 `C` 确认
5. 自动跳转到聊天界面

### 注意事项

- 转换后原任务会被删除
- 所有消息历史会保留到新会话
- 未完成的任务也可以转换，但会有警告提示
- 转换操作不可撤销

## 查看任务日志

每个任务都有独立的日志文件，记录详细的执行过程。

### 日志位置

创建任务时会显示日志路径：

```text
Task abc-123-def-456 started in background (PID: 12345)
Logs: /Users/username/.snow/task-logs/abc-123-def-456.log
```

### 查看日志

使用任何文本编辑器或命令行工具：

```bash
# 实时查看日志
tail -f ~/.snow/task-logs/abc-123-def-456.log

# 查看完整日志
cat ~/.snow/task-logs/abc-123-def-456.log
```

日志包含：

- 任务启动和结束时间
- 所有输出信息
- 错误信息和堆栈
- 执行过程跟踪

## 使用场景示例

### 场景 1：长时间代码分析

```bash
# 创建后台任务
snow --task "全面分析项目代码，生成架构文档和优化建议"

# 继续其他工作
cd other-project
git pull

# 稍后查看结果
snow --task-list
```

### 场景 2：批量文件重构

```bash
# 后台执行重构
snow --task "重构 src/components 下所有组件，统一使用 TS 严格模式"

# 任务检测到删除文件操作会暂停
# 打开任务管理器审批即可
```

### 场景 3：生成报告并继续讨论

```bash
# 创建分析任务
snow --task "分析最近一周的 Git 提交，生成代码质量报告"

# 任务完成后
snow --task-list
# 选择任务 → Enter → C → C 转为会话
# 然后可以继续问："重点优化哪些部分？"
```

## 常见问题

### Q：任务状态一直是"运行中"？

A：可能是任务正在执行耗时操作，可以：

- 查看日志了解当前进度
- 等待更长时间
- 如果确认卡住，可以删除任务重新创建

### Q：任务失败了怎么办？

A：

1. 查看日志找出错误原因
2. 检查提示词是否合理
3. 确认系统资源是否充足
4. 修改后重新创建任务

### Q：如何删除多个任务？

A：

1. 用 `Space` 键标记要删除的任务（会显示标记数量）
2. 按 `D` 键
3. 再按 `D` 确认批量删除

### Q：敏感命令没有暂停？

A：检查是否在[敏感命令配置](./06.敏感命令配置.md)中添加了该命令模式。

### Q：可以同时运行多少个任务？

A：理论上没有限制，但每个任务会占用系统资源，建议根据机器性能控制在合理数量。

## 实用技巧

1. **明确任务目标** - 创建任务时提供清晰具体的提示词，让 AI 知道要做什么
2. **定期清理** - 删除不需要的已完成任务，保持列表整洁
3. **善用标记** - 批量标记不需要的任务一次性删除
4. **检查日志** - 长时间运行的任务可以通过日志了解进度
5. **转为会话** - 重要任务完成后转为会话，方便后续查询和修改

## 相关文档

- [敏感命令配置](./06.敏感命令配置.md) - 配置需要审批的危险命令
- [无头模式](./12.无头模式.md) - 另一种非交互式执行方式
- [指令面板说明](./09.0.指令面板说明.md) - 了解更多管理指令