# Snow CLI 使用文档——官方文档工具（snow-docs）

Snow CLI 内置了 **snow-docs** 能力，让 Agent 在安装、配置、排错 Snow 本身时，优先查询**当前版本自带的官方使用文档**，而不是依赖模型记忆或临时抓取 GitHub。

该能力由两部分组成：

1. **内置技能（Skill）**：`snow-docs`
2. **内置只读工具（Built-in tools）**：`snow-docs-list` / `snow-docs-search` / `snow-docs-get`

## 适用场景

当用户询问以下主题时，Agent 应优先使用 snow-docs：

- 首次配置 / Profile / API / 模型选择
- MCP 安装、启用、禁用与排错
- Skills、Hooks、子代理、敏感命令
- 代理 / 浏览器 / 第三方中转 / 自定义请求头
- LSP / ACE、Team 模式、SSE、隐私设置、插件等

不适用于：与 Snow 配置无关的普通项目编码任务。

## 设计原则

- **渐进式披露（Progressive Disclosure）**：先 list/search，再 get 单篇文档，禁止一次加载全部手册
- **只读**：文档工具不会写入配置；改配置仍走正常文件/UI 流程
- **版本同步**：文档随 CLI 包一起发布（`bundle/docs/usage`），与安装版本一致
- **可禁用**：支持通过 `disabledSkills` / `disabledBuiltInServices` 关闭

## 内置技能 snow-docs

- **技能 ID**：`snow-docs`
- **来源**：`builtin`（随 CLI 打包，无需手动从 GitHub 安装）
- **作用**：提供触发条件、工作流约定、允许工具列表
- **allowed-tools**（技能声明）：
  - `snow-docs-list`
  - `snow-docs-search`
  - `snow-docs-get`
  - `filesystem-read`
  - `askuser-ask_question`

### 如何查看

- 使用 `/skills-` 打开技能选择器，可看到 `snow-docs`，位置标记为 `builtin`
- 使用 `/skills -l` 可在技能列表中启用/禁用该技能

### 禁用技能

在项目或全局设置中，将 `snow-docs` 加入 `disabledSkills`：

```json
{
  "disabledSkills": ["snow-docs"]
}
```

常见位置：

- 项目：`<project>/.snow/settings.json`
- 也可在技能列表面板中直接禁用

## 内置工具

服务名（built-in service）：`snow-docs`

| 工具名 | 作用 | 关键参数 |
| --- | --- | --- |
| `snow-docs-list` | 仅返回文档目录（id / title / 摘要） | 无（可选 `locale`） |
| `snow-docs-search` | 关键词搜索，返回命中 id 与短片段 | `query` |
| `snow-docs-get` | 按 id/path 获取单篇文档正文 | `path` |

### 推荐调用顺序

1. `tool_search(query="snow-docs")`（若启用了渐进式工具发现）
2. `snow-docs-list` 或 `snow-docs-search`
3. `snow-docs-get` 读取**一篇**相关文档
4. 再按文档说明检查/修改本地配置

### 参数说明

- `locale`（可选）：`zh` 或 `en`
  - 默认跟随语言设置：`zh` / `zh-TW` → 中文文档，其他 → 英文文档
- `query`：搜索关键词，例如 `MCP`、`hooks`、`skills`、`敏感命令`
- `path`：文档 id，例如 `14.MCP配置.md`、`14.MCP Configuration.md`，也支持 `zh/14.MCP配置.md`
- `maxResults`（search 可选）：默认 8，最大 12
- `maxChars`（get 可选）：默认约 24000，超长会截断并标记 `truncated`

### 示例

列出中文目录：

```text
snow-docs-list
locale: zh
```

搜索 MCP：

```text
snow-docs-search
query: MCP
locale: zh
```

读取单篇：

```text
snow-docs-get
path: 14.MCP配置.md
locale: zh
```

## 文档来源与打包位置

- 开发仓库：`docs/usage/zh`、`docs/usage/en`
- 安装后（随 npm 包）：`bundle/docs/usage/...`
- 内置技能文件：`bundle/skills/snow-docs/SKILL.md`

运行时会从 CLI 包/工作区向上解析 `docs/usage`，确保读到的是当前安装版本文档。

## 禁用内置工具服务

若只想关闭文档工具（保留其他能力），将 `snow-docs` 加入 `disabledBuiltInServices`：

```json
{
  "disabledBuiltInServices": ["snow-docs"]
}
```

也可在：

- 隐私设置（Privacy Settings）
- 子代理配置（Sub-Agent Configuration）

的工具组列表中管理 **Snow 官方文档工具 / Snow Docs Tools**。

说明：

- 禁用 **技能** `snow-docs`：减少主动触发与技能注入
- 禁用 **服务** `snow-docs`：`snow-docs-list/search/get` 将不可用
- 两者可单独或同时禁用

## 与外部 MCP 的区别

| 项目 | snow-docs | 外部 MCP |
| --- | --- | --- |
| 类型 | CLI 内置 skill + built-in tools | 用户配置的外部服务 |
| 安装 | 随 Snow CLI 自带 | 需在 `mcp-config` 中配置 |
| 数据源 | 本地打包 `docs/usage` | 远程/本地外部进程 |
| 写入能力 | 只读文档 | 取决于外部服务 |
| 禁用方式 | `disabledSkills` / `disabledBuiltInServices` | MCP 配置 `enabled` 或面板切换 |

## 安全约定

- 文档工具只读，不会自动改配置
- 涉及 API Key、关闭安全策略、敏感命令等高风险变更时，应向用户确认
- 不要静默改写全局配置
- 不要把整本手册一次性塞进上下文

## 相关文档

- [Skills 指令详细说明](./18.Skills指令详细说明.md)
- [MCP 配置](./14.MCP配置.md)
- [隐私设置指南](./24.隐私设置指南.md)
- [子代理设置](./05.子代理设置.md)
- [首次配置](./02.首次配置.md)