# Snow CLI 使用文档——隐私设置指南

隐私设置用于在 Snow CLI 调用部分工具后，对工具返回内容进行本地隐私过滤 API 脱敏，再把脱敏后的内容交给模型。该能力适合在代码、日志、终端输出、文件内容或搜索结果中可能出现姓名、邮箱、电话号码等个人可识别信息时使用。

## 功能概览

Snow CLI 的隐私过滤当前主要作用于工具结果内容：

- 读取文件、代码搜索、终端输出等工具结果可按配置进行脱敏。
- 脱敏服务由用户自行部署，Snow CLI 只调用你配置的 HTTP API。
- 支持项目级配置和全局配置；项目级配置优先于全局配置。
- 支持为不同工具选择是否启用工具结果脱敏。
- 如果隐私过滤 API 不可用、返回异常或未配置 URL，Snow CLI 会保留原始内容继续工作。

默认推荐配合本地部署项目使用：

```text
https://github.com/MayDay-wpf/privacy-filter-api
```

该项目基于 Hugging Face Transformers.js 在本机加载 OpenAI 发布的 `openai/privacy-filter` ONNX 模型，提供本地 PII 检测与文本脱敏接口，不需要把待处理文本发送到远程推理服务。

## privacy-filter-api 功能调查结论

`privacy-filter-api` 是一个本地 HTTP API 服务，核心能力如下：

| 能力 | 说明 |
| --- | --- |
| 本地模型 | 使用 `openai/privacy-filter`，通过 Transformers.js 加载本地 ONNX 模型文件。 |
| PII 检测 | `POST /detect` 返回识别到的实体列表，包括 `label`、`score`、`text`、`start`、`end`。 |
| 文本脱敏 | `POST /mask` 返回 `masked_text`，可使用 `mask_token` 控制占位格式。 |
| 健康检查 | `GET /health` 返回服务状态、模型名、模型是否已加载、鉴权状态。 |
| API 文档 | `/docs` 提供 Swagger UI，`/openapi.json` 提供 OpenAPI JSON。 |
| 鉴权 | 支持 `x-api-key` 请求头，也支持 `Authorization: Bearer <API_KEY>`。 |
| 部署 | 支持 npm 启动、PM2 守护和 Docker 部署。 |
| 模型精度 | 可选择 `fp32`、`fp16`、`q4`、`q4f16`、`quantized` 等下载精度。 |

Snow CLI 调用脱敏接口时会向配置的 URL 发送：

```json
{
  "text": "待脱敏文本",
  "aggregation_strategy": "simple",
  "mask_token": "[{label}]"
}
```

期望服务返回：

```json
{
  "model": "openai/privacy-filter",
  "masked_text": "脱敏后的文本",
  "entities": []
}
```

因此在 Snow CLI 中配置 URL 时，应填写 `/mask` 接口完整地址，例如：

```text
http://127.0.0.1:3000/mask
```

## 快速部署隐私过滤 API

### 环境要求

部署机器需要：

- Git
- Node.js 20 或更高版本
- npm
- Python 3，仅首次下载 Hugging Face 模型时需要

### 一键安装并使用 PM2 守护

从任意目录执行：

```bash
git clone https://github.com/MayDay-wpf/privacy-filter-api.git privacy-filter-api
cd privacy-filter-api
npm install
npm run install:daemon
```

脚本会安装依赖、检查本地模型、按需询问下载模型精度，并用 PM2 启动 `privacy-filter-api` 服务。

常用参数：

```bash
npm run install:daemon -- --precision fp16
npm run install:daemon -- --dir /opt/privacy-filter-api --precision fp16
npm run install:daemon -- --yes
npm run install:daemon -- --no-startup
```

建议首次使用选择 `fp16`：体积和速度通常比较均衡。如果追求更高精度可选 `fp32`；资源较紧张时可尝试 `q4` 或 `q4f16`。

安装完成后可查看状态：

```bash
pm2 status
pm2 logs privacy-filter-api
pm2 restart privacy-filter-api
```

### 手动下载模型并启动

如果希望手动控制模型精度，可执行：

```bash
git clone https://github.com/MayDay-wpf/privacy-filter-api.git privacy-filter-api
cd privacy-filter-api
npm install
npm run download:model -- fp16
npm run start:model -- fp16
```

服务默认监听：

```text
http://127.0.0.1:3000
```

健康检查：

```bash
curl http://127.0.0.1:3000/health
```

首次调用 `/detect` 或 `/mask` 时才会真正加载模型，因此健康检查里出现 `loaded:false` 属于正常现象。

### 配置 API Key

复制环境变量示例：

```bash
cp .env.example .env
```

建议设置 API Key：

```env
API_KEY=your-secret-key
API_KEY_HEADER=x-api-key
TRANSFORMERS_DTYPE=fp16
LOCAL_FILES_ONLY=true
```

设置后 `/detect` 与 `/mask` 需要携带 API Key；`/health`、`/docs`、`/openapi.json` 不需要 API Key。

Snow CLI 会同时发送：

```text
x-api-key: your-secret-key
Authorization: Bearer your-secret-key
```

因此只要在 Snow CLI 的隐私设置里填写相同 API Key 即可。

## 在 Snow CLI 中配置隐私设置

### 进入设置页面

1. 启动 Snow CLI。
2. 在欢迎界面选择 `隐私设置`。
3. 根据需要选择配置位置、启用隐私过滤、填写 API 配置并选择需要脱敏的工具结果。

### 配置位置

隐私设置支持两种位置：

| 位置 | 说明 |
| --- | --- |
| 项目配置 | 保存到当前项目的设置中，仅当前工作目录生效。适合只想保护某个项目输出的情况。 |
| 全局配置 | 保存到用户级设置中，对没有项目级覆盖的工作目录生效。适合所有项目共用同一个本地隐私过滤服务。 |

项目配置优先级高于全局配置。也就是说，如果当前项目设置了 `privacy.enabled`、API URL 或工具列表，Snow CLI 会优先使用项目配置；项目配置缺失的字段才会回退到全局配置。

### 启用隐私过滤

在 `启用隐私过滤` 项中切换启用状态：

- `Enabled`：工具结果会根据后续配置进入隐私过滤流程。
- `Disabled`：不调用隐私过滤 API，工具结果保持原样。

注意：启用后仍需要配置有效的 API URL，否则不会进行脱敏。

### API 配置

进入 `API 配置` 后填写：

| 字段 | 示例 | 说明 |
| --- | --- | --- |
| URL | `http://127.0.0.1:3000/mask` | 必须填写 `/mask` 接口完整地址。 |
| API Key | `your-secret-key` | 可选；如果服务端设置了 `API_KEY`，这里必须填写同一个值。 |
| Model | `openai/privacy-filter` | 模型名，默认值为 `openai/privacy-filter`。当前主要用于记录和界面展示。 |

推荐配置：

```text
URL: http://127.0.0.1:3000/mask
API Key: your-secret-key
Model: openai/privacy-filter
```

### 检测工具结果配置

进入 `检测工具结果配置` 后，可以选择哪些工具的返回内容需要脱敏。

默认启用的工具包括：

```text
filesystem-read
ace-search
terminal-execute
```

常见建议：

- `filesystem-read`：建议启用。文件内容可能包含姓名、邮箱、Token、路径或客户信息。
- `ace-search`：建议启用。搜索结果可能包含源码片段和注释中的敏感信息。
- `terminal-execute`：建议启用。命令输出可能包含环境变量、日志、用户名、路径、接口返回等。
- `websearch-*`：按需启用。公开网页内容通常不需要脱敏，但如果搜索内容可能带出用户输入，可启用。
- MCP 工具：按业务判断。对会返回客户数据、工单、数据库查询结果的 MCP 工具建议启用。

## 测试脱敏服务

可以先用 curl 验证服务是否可用：

```bash
curl -X POST http://127.0.0.1:3000/mask \
  -H 'content-type: application/json' \
  -H 'x-api-key: your-secret-key' \
  -d '{"text":"My name is Harry Potter and my email is harry.potter@hogwarts.edu.","mask_token":"[{label}]"}'
```

正常返回示例：

```json
{
  "model": "openai/privacy-filter",
  "masked_text": "My name is [private_person] and my email is [private_email].",
  "entities": [
    {
      "label": "private_person",
      "score": 0.9999,
      "text": " Harry Potter",
      "start": 10,
      "end": 23
    },
    {
      "label": "private_email",
      "score": 0.9999,
      "text": " harry.potter@hogwarts.edu",
      "start": 40,
      "end": 67
    }
  ]
}
```

如果 curl 成功，再把同一个 `/mask` URL 和 API Key 填入 Snow CLI。

## Docker 部署示例

构建镜像：

```bash
docker build -t privacy-filter-api .
```

运行容器并挂载本地模型目录：

```bash
docker run --rm \
  -p 3000:3000 \
  -e API_KEY=your-secret-key \
  -e TRANSFORMERS_DTYPE=fp16 \
  -e LOCAL_FILES_ONLY=true \
  -v "$PWD/models:/app/models" \
  -v "$PWD/.cache:/app/.cache" \
  privacy-filter-api
```

如果构建镜像时已经预下载模型，也可以不挂载 `models` 目录。

## 故障排除

### Snow CLI 没有脱敏

检查：

1. `启用隐私过滤` 是否为 Enabled。
2. API URL 是否填写为完整 `/mask` 地址，而不是服务根地址。
3. 当前工具是否在 `检测工具结果配置` 中被选中。
4. 项目级配置是否覆盖了全局配置。
5. API Key 是否和服务端 `.env` 中的 `API_KEY` 一致。

### 服务健康检查正常，但第一次脱敏很慢

这是正常现象。`privacy-filter-api` 在第一次调用 `/detect` 或 `/mask` 时才加载模型，首次请求会比后续请求慢。

### 返回 401 Unauthorized

说明服务端启用了 API Key 鉴权，但 Snow CLI 中填写的 API Key 不正确或为空。请确认：

```env
API_KEY=your-secret-key
API_KEY_HEADER=x-api-key
```

然后在 Snow CLI `API 配置` 中填写同一个 `your-secret-key`。

### 返回原始内容没有变化

可能原因：

- 文本中没有被模型识别出的 PII。
- 隐私过滤 API 请求失败，Snow CLI 为避免中断工作流保留了原文。
- URL 填写错误，未指向 `/mask`。
- 模型精度或本地模型文件与 `TRANSFORMERS_DTYPE` 不匹配。

### 生产环境建议

- 尽量部署在本机或可信内网。
- 设置 `API_KEY`，不要把未鉴权服务暴露到公网。
- 保持 `LOCAL_FILES_ONLY=true`，避免运行时从远程下载模型。
- 使用防火墙或反向代理限制访问来源。
- 对高敏感项目优先使用项目级配置，明确选择需要脱敏的工具。