# Snow CLI 使用文档——无头模式

欢迎使用 Snow CLI！在终端中进行 Agentic 编程。

## 什么是无头模式

无头模式（Headless Mode）是 Snow CLI 的快速对话功能，允许您直接在命令行中提问并获得 AI 回复，无需进入交互式界面。它非常适合：

- 脚本自动化
- CI/CD 集成
- 快速咨询
- 第三方工具集成

## 基础用法

### 单次提问

```bash
snow --ask "你的问题"
```

示例：

```bash
snow --ask "帮我解释这段代码的作用"
snow --ask "如何优化这个SQL查询"
snow --ask "解释一下React的useState钩子"
```

### 连续对话

无头模式支持会话上下文保持，允许您进行连续对话：

```bash
# 第一次提问
snow --ask "帮我创建一个React组件"

# 输出会包含 SESSION_ID=abc-123-def-456

# 使用返回的 Session ID 继续对话
snow --ask "给这个组件添加样式" abc-123-def-456

# 继续对话
snow --ask "再添加一些交互功能" abc-123-def-456
```

## 特性说明

### 自动会话管理

- 每次对话都会自动创建会话并保存
- 会话 ID 会在输出末尾以 `SESSION_ID=<uuid>` 格式显示
- 历史消息会被加载并作为上下文传递给 AI
- 支持跨平台会话共享（同一项目）

### YOLO 模式

无头模式默认启用 YOLO 模式（自动批准工具调用）：

- 非敏感命令自动执行
- 敏感命令仍需手动确认
- 提高自动化效率

关于敏感命令配置，请参考：[敏感命令配置](./6.敏感命令配置.md)

### 文件引用

无头模式支持在问题中引用文件：

```bash
snow --ask "分析这个文件的问题 @src/App.tsx"
snow --ask "优化这段代码 @utils/helper.js"
```

### 彩色输出

无头模式提供友好的彩色终端输出：

- 用户查询：青色边框
- AI 响应：Markdown 渲染，代码高亮
- 工具执行：黄色/绿色/红色状态标识
- 会话信息：蓝色信息框

## 会话恢复机制

### 工作原理

1. **首次对话**：创建新会话，生成 UUID
2. **保存历史**：所有消息自动保存到 `~/.snow/sessions/`
3. **提供会话 ID**：在输出末尾显示 `SESSION_ID=<uuid>`
4. **恢复对话**：使用会话 ID 加载历史消息
5. **继续对话**：新消息追加到历史记录

### 会话格式

输出中的会话信息包含两部分：

1. **人类友好格式**（彩色框）：
   ```
   ┌─ Session Information
   │  Session ID: abc-123-def-456
   │  To continue this conversation, use:
   │  snow --ask "your next question" abc-123-def-456
   └─
   ```

2. **机器可解析格式**（纯文本）：
   ```
   SESSION_ID=abc-123-def-456
   ```

### 会话存储位置

- Windows: `%USERPROFILE%\.snow\sessions\<项目名>\<日期>\<UUID>.json`
- macOS/Linux: `~/.snow/sessions/<项目名>/<日期>/<UUID>.json`

会话按项目和日期自动分类，便于管理。

## 第三方集成

### Shell 脚本集成

```bash
#!/bin/bash

# 执行对话并提取 Session ID
output=$(snow --ask "创建一个API接口")
session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2)

# 使用 Session ID 继续对话
snow --ask "添加错误处理" "$session_id"
snow --ask "添加单元测试" "$session_id"
```

### Python 集成

```python
import subprocess
import re

# 执行对话
result = subprocess.run(
    ['snow', '--ask', '帮我分析这个错误'],
    capture_output=True,
    text=True
)

# 提取 Session ID
match = re.search(r'SESSION_ID=(.+)', result.stdout)
if match:
    session_id = match.group(1).strip()
    
    # 继续对话
    subprocess.run([
        'snow', '--ask', '如何修复这个问题', session_id
    ])
```

### Node.js 集成

```javascript
const { execSync } = require('child_process');

// 执行对话
const output = execSync('snow --ask "创建一个Express路由"', {
  encoding: 'utf-8'
});

// 提取 Session ID
const match = output.match(/SESSION_ID=(.+)/);
if (match) {
  const sessionId = match[1].trim();
  
  // 继续对话
  execSync(`snow --ask "添加中间件" ${sessionId}`);
}
```

### CI/CD 集成

在 GitHub Actions 中使用：

```yaml
name: AI Code Review

on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Setup Snow CLI
        run: npm install -g snow-ai
      
      - name: AI Review
        run: |
          # 分析变更的文件
          changed_files=$(git diff --name-only HEAD^)
          
          # 请求 AI 分析
          output=$(snow --ask "分析这些文件的变更：$changed_files")
          
          # 提取建议
          echo "$output" >> $GITHUB_STEP_SUMMARY
```

## 输出格式

### 标准输出结构

```
╭─────────────────────────────────────────────────────────╮
│                ❆ Snow AI CLI - Headless Mode ❆          │
╰─────────────────────────────────────────────────────────╯

┌─ Continuing Session  (如果是继续对话)
│  Session ID: abc-123-def-456
│  Previous messages: 4

┌─ User Query
│  你的问题内容

└─ Assistant Response

AI 的回复内容（Markdown 格式，代码高亮）

┌─ Session Information
│  Session ID: abc-123-def-456
│  To continue this conversation, use:
│  snow --ask "your next question" abc-123-def-456
└─

SESSION_ID=abc-123-def-456
```

### 解析建议

对于脚本和工具集成，推荐的解析方式：

1. **提取 Session ID**：
   - 使用正则表达式 `/SESSION_ID=(.+)/`
   - 或直接查找最后一行的 `SESSION_ID=` 前缀

2. **提取 AI 响应**：
   - 查找 `└─ Assistant Response` 之后的内容
   - 去除 ANSI 颜色代码（如需要）

3. **错误处理**：
   - 检查退出代码
   - 查找 `✗ Error:` 标记

## 使用场景

### 代码审查助手

```bash
# 快速代码审查
git diff | snow --ask "审查这些代码变更，指出潜在问题"

# 针对性审查
snow --ask "这段代码有性能问题吗 @src/utils/parser.ts"
```

### 文档生成

```bash
# 生成函数文档
snow --ask "为这个函数生成 JSDoc 注释 @src/api.ts"

# 生成 README
snow --ask "根据代码结构生成项目 README @src/"
```

### 快速咨询

```bash
# 技术问题
snow --ask "React 18 的并发特性如何使用"

# 调试建议
snow --ask "这个错误怎么解决：TypeError: Cannot read property 'map' of undefined"
```

### 自动化工作流

```bash
#!/bin/bash

# 自动化代码优化流程
output=$(snow --ask "分析项目依赖 @package.json")
session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2)

snow --ask "建议需要更新的依赖" "$session_id"
snow --ask "生成依赖更新脚本" "$session_id"
```

### 测试生成

```bash
# 生成单元测试
snow --ask "为这个函数生成单元测试 @src/calculator.ts"

# 生成测试数据
output=$(snow --ask "生成测试用的用户数据 JSON")
session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2)

snow --ask "再生成10个变体数据" "$session_id"
```

## 最佳实践

### 1. 清晰的问题描述

```bash
# 好的示例
snow --ask "优化这个 SQL 查询的性能，重点关注索引使用 @query.sql"

# 不够清晰
snow --ask "优化 @query.sql"
```

### 2. 合理使用会话上下文

```bash
# 建立上下文后的连续对话
output=$(snow --ask "创建一个用户认证系统")
session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2)

# 后续问题可以更简洁
snow --ask "添加密码重置功能" "$session_id"
snow --ask "添加邮箱验证" "$session_id"
```

### 3. 处理长时间任务

对于可能需要长时间思考的任务：

```bash
# 复杂任务可能需要更多时间
snow --ask "重构整个认证模块，使用最佳实践 @src/auth/"
```

等待 AI 完成思考和工具调用。

### 4. 结合命令注入

```bash
# 在问题中嵌入实时信息
snow --ask "分析当前 Git 分支状态 !`git status` 并提供建议"
```

关于命令注入，请参考：[命令注入模式](./10.命令注入模式.md)

### 5. 错误处理

```bash
#!/bin/bash

# 脚本中的错误处理
if ! output=$(snow --ask "你的问题" 2>&1); then
    echo "错误：AI 对话失败"
    echo "$output"
    exit 1
fi

# 检查是否成功生成 Session ID
if ! echo "$output" | grep -q "SESSION_ID="; then
    echo "警告：未能获取 Session ID"
fi
```

## 限制和注意事项

### 不支持的功能

1. **交互式工具**：
   - `askuser` 工具不可用
   - 无法在无头模式下请求用户输入

2. **Plan 模式**：
   - 无头模式不支持 Plan 模式
   - 所有工具调用立即执行（YOLO 模式）

3. **实时更新显示**：
   - 不支持实时流式输出到终端
   - 完成后一次性显示结果

### 安全考虑

1. **敏感命令确认**：
   - 即使在 YOLO 模式下，敏感命令仍需确认
   - 不适合完全无人值守的自动化

2. **API 密钥保护**：
   - 在 CI/CD 中使用时，确保 API 密钥安全存储
   - 使用环境变量或密钥管理服务

3. **输出内容审查**：
   - AI 输出可能包含敏感信息
   - 在公开日志中使用时注意过滤

### 性能注意事项

1. **会话大小**：
   - 长会话历史会增加 Token 消耗
   - 建议周期性开始新会话

2. **并发限制**：
   - 同时运行多个无头模式实例时注意 API 限流

3. **网络延迟**：
   - 响应时间取决于网络和 AI 服务
   - 考虑设置合理的超时

## 常见问题

**Q: 无头模式和交互式模式有什么区别？**

A: 无头模式是单次执行模式，执行完成后自动退出，适合脚本和自动化。交互式模式提供完整的 UI 界面，支持持续对话和更多高级功能。

**Q: Session ID 会过期吗？**

A: Session ID 不会过期，会话文件永久保存在本地。但是非常旧的会话可能因为上下文过大而影响性能。

**Q: 可以在不同项目间共享会话吗？**

A: 不可以。会话按项目路径分类存储，确保不同项目的对话不会混淆。

**Q: 如何查看所有历史会话？**

A: 会话保存在 `~/.snow/sessions/` 目录下，按项目和日期组织。您可以使用文件管理器浏览，或使用 `/resume` 查看会话。

**Q: Session ID 丢失了怎么办？**

A: 可以在会话存储目录中查找最近的会话文件，文件名即为 Session ID。或者使用交互式模式的 `/resume` 命令查看历史会话。

**Q: 无头模式支持文件上传吗？**

A: 支持通过 `@文件路径` 语法引用文件，但不支持图片上传。图片分析请使用交互式模式。

**Q: 如何在无头模式中使用不同的 API 配置？**

A: 无头模式使用全局配置文件（`~/.snow/profiles.json`）。如需切换配置，请先在交互式模式中切换 Profile，或直接编辑配置文件。

**Q: 输出的 ANSI 颜色代码如何去除？**

A: 
```bash
# 使用 sed 去除颜色代码
snow --ask "你的问题" | sed 's/\x1b\[[0-9;]*m//g'

# 或使用其他工具
snow --ask "你的问题" | ansi2txt
```

**Q: 可以重定向输出到文件吗？**

A: 可以，但会保留 ANSI 颜色代码：
```bash
snow --ask "你的问题" > output.txt

# 同时保存到文件和显示在终端
snow --ask "你的问题" | tee output.txt
```

## 配置文件位置

无头模式使用全局配置：

- **API 配置**: `~/.snow/profiles.json`
- **敏感命令**: `~/.snow/sensitive-commands.json`
- **会话存储**: `~/.snow/sessions/<项目名>/<日期>/`

配置方法请参考：[首次配置](./02.首次配置.md)

## 相关功能

- [命令注入模式](./10.命令注入模式.md) - 在问题中嵌入实时命令执行
- [敏感命令配置](./06.敏感命令配置.md) - 配置需要确认的危险命令
- [指令面板说明](./09.0.指令面板说明.md) - 了解交互式模式的更多功能

## 示例脚本

### 完整的自动化示例

```bash
#!/bin/bash

# 颜色定义
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# 错误处理
set -e
trap 'echo -e "${RED}脚本执行失败${NC}"' ERR

echo -e "${YELLOW}开始自动化代码审查...${NC}"

# 获取变更的文件
changed_files=$(git diff --name-only HEAD^ | tr '\n' ' ')

if [ -z "$changed_files" ]; then
    echo -e "${RED}没有检测到文件变更${NC}"
    exit 0
fi

echo -e "${GREEN}检测到变更文件: $changed_files${NC}"

# 初始审查
echo -e "${YELLOW}执行初始代码审查...${NC}"
output=$(snow --ask "审查这些文件的变更：$changed_files")

# 提取 Session ID
session_id=$(echo "$output" | grep "SESSION_ID=" | cut -d'=' -f2)

if [ -z "$session_id" ]; then
    echo -e "${RED}无法获取 Session ID${NC}"
    exit 1
fi

echo -e "${GREEN}Session ID: $session_id${NC}"

# 详细分析
echo -e "${YELLOW}请求安全分析...${NC}"
snow --ask "从安全角度分析这些变更" "$session_id"

echo -e "${YELLOW}请求性能分析...${NC}"
snow --ask "从性能角度分析这些变更" "$session_id"

echo -e "${GREEN}代码审查完成！${NC}"
```

这个脚本展示了如何：
- 错误处理和颜色输出
- Session ID 提取和验证
- 多轮连续对话
- 自动化工作流集成