snow-app-docs · diff

git:20260809.d628759 to git:20260809.68949aa

75 added, 156 removed. Audit A to A.

---

name: snow-app-docs

description: >-

- Guides the agent to read the built-in Snow App documentation

- (~/.snow/docs) before configuring or troubleshooting Snow App. Covers MCP

- servers; installing, managing, creating, and authoring Skills; sub-agents;

- Hooks; API keys/models; image generation; proxy/network; third-party config

- and Plugin runtimes; browser passwords and local-browser data import; app

- updates; security/privacy/tool authorization; personalization, system prompts,

- custom headers, themes, and shortcuts; usage/log diagnostics; project-scoped

+ Snow App 配置与排查向导（中文/English）——配置/管理 API 密钥、模型与档案、

+ MCP 服务器、Skills、子代理、Hooks、图像生成、代理与网络、第三方配置导入、

+ 安全隐私与工具授权、个性化/系统提示词/自定义请求头/主题/快捷键、用量统计与

+ 系统日志、数据存储位置、settings.json 字段、内置工具等。

+ Guides the agent to read the built-in Snow App documentation (~/.snow/docs)

+ before configuring or troubleshooting Snow App. Covers MCP servers;

+ installing, managing, creating, and authoring Skills; sub-agents; Hooks;

+ API keys/models; image generation; proxy/network; third-party config and

+ Plugin runtimes; browser passwords and local-browser data import; app updates;

+ security/privacy/tool authorization; personalization, system prompts, custom

+ headers, themes, and shortcuts; usage/log diagnostics; project-scoped

settings; settings.json fields; storage locations; and built-in tools. Use

this Skill whenever the user asks to configure, inspect, create, author, or

troubleshoot any of these areas. It covers the config built-in service

(config-list/get/set/delete; scopes: settings/snowcfg/proxy/app/

custom-headers/system-prompt/theme/language/permissions/lsp-config/buddy/

- subAgents/hooks/skills/logs/imagegen/personalization), including project-

- scoped mcpServers/sensitiveCommands/subAgents/hooks/skills via `projectId`,

- the read-only logs scope, imagegen multi-channel settings and top-level

- maxConcurrentImages, masked secrets, and app-control-openSettings.

+ subAgents/hooks/skills/logs/imagegen/personalization/apiProfiles), including

+ project-scoped mcpServers/sensitiveCommands/subAgents/hooks/skills via

+ `projectId`, the read-only logs scope, imagegen multi-channel settings,

+ masked secrets, and app-control-openSettings (21 settings pages).

enable: true

allowed-tools:

- config-list

- config-get

- config-set

- config-delete

- user-interaction-askUserQuestion

- app-control-openSettings

- bash-terminal-execute

- filesystem-read

- filesystem-replace_edit

- filesystem-create

- websearch-websearch-search

- websearch-websearch-fetch

---

# Snow App 文档阅读与配置指导（Docs & Configuration Guide）

当用户请求**配置 MCP 服务器、安装与管理 Skills、创建与编写 Skills、配置 Hooks

与子代理、配置 API 密钥与模型、配置图像生成、配置代理与网络、导入第三方配置

与插件、管理浏览器密码/数据、处理应用更新、个性化与自定义请求头、用量/日志诊断、

项目级设置**，或询问 **settings.json 字段 / 内置工具 / 安全边界 / 数据位置**时，

先阅读应用内置文档，再按文档步骤动手配置，而不是凭记忆操作。

## 1. 先读文档（Read the docs first）

文档随应用安装到 `~/.snow/docs/`（Windows 为 `C:\Users\<用户名>\.snow\docs\`）。

- 根据用户界面语言选择分支：

+ **先执行 `config-list scope=language` 读取界面语言**（`zh-CN`/`en`/`zh-TW`），

+ 再选择对应文档分支（无法读取时默认中文分支）：

- 中文界面 → 读 `~/.snow/docs/zh-CN/`

- English UI → read `~/.snow/docs/en/`

按任务定位文档（路径相对所选语言分支）：

| 任务 | 使用指南（How-to） | 参考手册（Reference） |

| --- | --- | --- |

| 配置 MCP 服务器 | `2-使用指南/1-配置MCP服务器.md`（en: `2-guides/1-configure-mcp.md`） | `3-参考手册/1-settings.json配置参考.md` |

| 安装与管理 Skills | `2-使用指南/2-安装与管理Skills.md`（en: `2-guides/2-install-and-manage-skills.md`） | — |

| 创建与编写 Skills | `2-使用指南/21-创建与编写Skills.md`（en: `2-guides/21-create-and-author-skills.md`） | — |

- | 配置 API 密钥与模型 | `2-使用指南/3-配置API密钥与模型.md`（en: `2-guides/3-configure-api-keys.md`） | `3-参考手册/1-settings.json配置参考.md` |

+ | 配置 API 密钥与模型 | `2-使用指南/3-配置API密钥与模型.md#5`（en: `2-guides/3-configure-api-keys.md#5`；§5 为 agent 操作速查） | `3-参考手册/1-settings.json配置参考.md` |

| 配置图像生成 | `2-使用指南/9-图像生成.md`（en: `2-guides/9-image-generation.md`） | `3-参考手册/2-内置工具参考.md`（imagegen 章节与 config 的 imagegen scope） |

| 使用聊天与 AI 助手（界面/对话/命令/回滚/压缩） | `2-使用指南/10-使用聊天与AI助手.md`（en: `2-guides/10-using-chat-and-ai.md`） | — |

| 终端与 SSH 远程管理 | `2-使用指南/11-终端与SSH远程管理.md`（en: `2-guides/11-terminal-and-ssh.md`） | — |

| Git 面板与代码浏览 | `2-使用指南/12-Git面板与代码浏览.md`（en: `2-guides/12-git-and-code-browsing.md`） | — |

| 配置代理与网络 | `2-使用指南/4-配置代理与网络.md`（en: `2-guides/4-configure-proxy.md`） | — |

| 配置 Hooks 与子代理 | `2-使用指南/5-配置Hooks与子代理.md`（en: `2-guides/5-configure-hooks-and-subagents.md`） | — |

| 浏览器自动化 | `2-使用指南/6-浏览器自动化.md`（en: `2-guides/6-browser-automation.md`） | — |

| 代码库索引与代码诊断 | `2-使用指南/7-代码库索引与代码诊断.md`（en: `2-guides/7-codebase-index-and-diagnostics.md`） | — |

| 第三方配置导入与插件 runtime | `2-使用指南/8-第三方配置导入.md`（en: `2-guides/8-third-party-configuration-import.md`） | `3-参考手册/5-安全与信任边界.md` |

| AI 开发协作、经验与前端美化工作流 | `2-使用指南/13-AI开发协作.md`、`2-使用指南/14-AI开发经验与教训.md`、`2-使用指南/15-前端设计与美化工作流.md`（en: `2-guides/13-ai-development-collaboration.md`、`2-guides/14-ai-development-lessons.md`、`2-guides/15-frontend-design-and-beautification-workflow.md`） | `4-架构与开发/2-开发者指南.md` |

| 安全、隐私与工具授权 | `2-使用指南/16-安全隐私与工具授权.md`（en: `2-guides/16-security-privacy-and-tool-authorization.md`） | `3-参考手册/5-安全与信任边界.md` |

| 浏览器设置、密码保险库与本机导入 | `2-使用指南/17-浏览器设置密码与数据导入.md`（en: `2-guides/17-browser-settings-passwords-and-import.md`） | `3-参考手册/4-数据存储位置.md` |

| 应用更新 | `2-使用指南/18-应用更新.md`（en: `2-guides/18-app-updates.md`） | `3-参考手册/5-安全与信任边界.md` |

| 系统提示词、个性化、请求头、主题与快捷键 | `2-使用指南/19-个性化主题与快捷键.md`（en: `2-guides/19-personalization-theme-and-shortcuts.md`） | `3-参考手册/3-配置文件字段参考.md` |

| 用量统计与系统日志 | `2-使用指南/20-用量统计与系统日志.md`（en: `2-guides/20-usage-statistics-and-system-logs.md`） | `3-参考手册/4-数据存储位置.md` |

- | 查询内置工具 / 配置域 / 日志 | — | `3-参考手册/2-内置工具参考.md`（en: `3-reference/2-builtin-tools-reference.md`） |

+ | 查询内置工具 / 配置域 / 日志 | — | `3-参考手册/2-内置工具参考.md#config`（en: `3-reference/2-builtin-tools-reference.md#config`；§app-control 有 21 个设置页表格） |

| 查询配置文件字段 | — | `3-参考手册/3-配置文件字段参考.md`（en: `3-reference/3-config-file-field-reference.md`） |

+ | 架构与开发（构建/故障排查/数据流） | `4-架构与开发/1-架构总览.md`、`2-开发者指南.md`、`3-打包与安装故障排查.md`、`4-Agent运行时与工具编排.md`、`5-存储迁移备份与恢复.md`、`6-功能模块架构与数据流图集.md`（en: `4-architecture-and-development/1-architecture-overview.md` 等，按同名编号对应） | — |

> 若 `~/.snow/docs/` 不存在，说明文档尚未同步，可提示用户重启应用后重试。

## 2. 按文档执行配置（Then apply the configuration）

- **通用流程**：任何配置任务，先 `config-list scope=<域>` 查看现状——DB 型域

- （subAgents / hooks / imagegen）的响应会附带 **guidance 使用规则引导**（如

- 创建子代理的关键规则、hook 退出码约定），再按本文与文档步骤执行；需要

- `projectId` 时（项目级配置），在 `~/.snow/projects/index.json` 中按项目路径

- 查 `projectId`（即 directoryId），或直接问用户从界面获取。

+ **通用流程**：先 `config-list scope=<域>` 查看现状（DB 型域响应附 guidance

+ 使用规则），再按文档步骤执行；需要 `projectId` 时在 `~/.snow/projects/index.json`

+ 按项目路径查 `directoryId`（即 projectId）。读取文档时可用

+ `filesystem-read` 的 `startLine`/`endLine` **只读相关章节**（锚点见第 1 节表格）。

- 通读对应文档后按步骤执行：

+ **各域操作要点**（完整命令示例见对应文档）：

+ - **API 档案**：`apiProfiles` 域，写 DB `api_configs`、与 UI 同源、立即生效。

+ 空/省略 `apiKey` 一律保留旧值（支持"无密钥建档→用户后补密钥"）；未提供字段

+ 保留现值；`isActive:true` 切换（**新会话生效**，已有会话绑定创建时档案——

+ 会话隔离）；删除先 `askUserQuestion` 再 `confirmed=true`；密钥读取一律脱敏

+ （如 `sk-****abcd`），**不索要/展示明文**。→ `3-配置API密钥与模型.md#5`

+ - **MCP 服务器**：`settings.mcpServers`（全局自动同步 DB 立即生效；项目级传

+ `projectId` 全量替换，value 为 `{name: {type,url,command,args,env,headers,enabled,timeoutMs}}`）。

+ → `1-配置MCP服务器.md`

+ - **敏感命令（项目级）**：`settings.sensitiveCommands` 传 `projectId` 全量替换

+ （元素 `{commandId, pattern, description, enabled}`）。→ `16-安全隐私与工具授权.md`

+ - **子代理**：`subAgents` 域（key=agentId，写 DB 立即生效）。显式 `toolsJson`

+ 工具名列表须传 `projectId`（全局仅空/`["*"]`）；`configProfile` 须是已存在

+ 档案名；`systemPrompt` 须完全自包含；内置 `agent_general` 不可改删；项目级

+ 优先于同名全局。→ `5-配置Hooks与子代理.md#2`

+ - **Hooks**：`hooks` 域（key=hookType，value 含 `rules` 数组；传 `projectId`

+ 为项目级）。**每个要执行的 action 必须显式 `enabled: true`**。

+ → `5-配置Hooks与子代理.md`

+ - **Skills 管理**：`skills` 域。同 ID 覆盖优先级 `<项目>/.snow/skills` >

+ `<项目>/.agents/skills` > `~/.snow/skills` > `~/.agents/skills`；开关参数名

+ `enabled`（全局实际改写 frontmatter 的 `enable`）；GitHub 安装

+ `{url, location}`；delete 仅卸载 registry 已登记的 GitHub Skill（需确认）。

+ → `2-安装与管理Skills.md`

+ - **创建/编写 Skills**：frontmatter 是 **`enable` 与 `allowed-tools`**；技能 ID

+ 来自 SKILL.md 相对扫描根的路径；创建后核对 id/path/enabled 并只读测试。

+ → `21-创建与编写Skills.md`

+ - **图像生成**：`imagegen` 域（`{channels:[...]}` 全量替换或 `{<channelId>: {...}}`

+ 按 id 合并，未提供字段保留原值；顶层 `maxConcurrentImages` 1-8/`timeoutSecs`

+ 60-3600；渠道需 `enabled`+`apiKey`+`model` 齐备，全未配置时 `imagegen-generate`

+ 隐藏；apiKey 脱敏）。→ `9-图像生成.md`

+ - **全局规则**：`personalization` 域 `key=role`（`~/.snow/ROLE.md` 纯文本非

+ JSON；get 全文/set 整体替换/delete 需确认，写后下一对话生效）。

+ → `19-个性化主题与快捷键.md`

+ - **代理/主题等文件域**：`proxy`/`custom-headers`/`system-prompt`/`theme`/

+ `language`/`permissions`/`lsp-config`/`buddy`，写后**可能需重启或 UI 重存生效**。

+ → `3-参考手册/3-配置文件字段参考.md`

+ - **日志（只读）**：`logs` 域（list 列文件、get 读尾部 `limit` 默认 200 最大

+ 2000、delete 仅接受精确文件名）。→ `20-用量统计与系统日志.md`

- - **MCP 服务器（全局）**：用 `config-set` 写 `settings` 域的 `mcpServers` 键

- （value 为服务器名到配置对象的映射，Windows 路径用 `\\` 转义）；

- 写入会自动按差集同步到应用数据库，**立即生效**，无需手动同步；

- 也可先 `config-get`/`config-list` 查看现状。

- - **MCP 服务器（项目级）**：给 `config-set settings mcpServers` 传

- `projectId` 可**全量替换**该项目级 MCP 服务器（value 同样为

- `{name: {type,url,command,args,env,headers,enabled,timeoutMs}}`，写入应用

- 数据库立即生效）；`config-get`/`config-delete` 传 `projectId` 读取/清空

- 项目级 MCP 服务器。

- - **敏感命令（项目级）**：`config-set settings sensitiveCommands [数组]`

- 传 `projectId` 全量替换项目级敏感命令（元素 `{commandId, pattern,

- description, enabled}`；commandId 匹配全局规则时为 enabled 覆盖，其余为

- 项目自定义规则）；`config-get`/`config-delete` 传 `projectId` 读取/清空。

- - **API 密钥与模型（档案）**：多档案存在应用数据库 `api_configs` 表，

- `active-profile.json` 的 `activeProfile` 仅 CLI 兼容层；**运行时以 DB 的

- `is_active` 为准**。`snowcfg` 域读写的是当前生效档案（config.json 镜像）。

- 优先用 **`apiProfiles` 域**（写 DB、与 UI 同源、立即生效），详细步骤见

- `2-使用指南/3-配置API密钥与模型.md` 第 5 节。操作速查：

- - **查看全部档案**：`config-list scope=apiProfiles`（apiKey/visionApiKey

- 脱敏，isActive 标出生效档案）；当前档案用 `config-list scope=snowcfg`；

- - **新建档案（支持无密钥建档→用户后补密钥）**：`config-set scope=apiProfiles

- key=<档案名> value={baseUrl, advancedModel, basicModel}` 先建无密钥档案，

- 用户提供密钥后再 `value={apiKey}` 补上（**空/省略 apiKey 一律保留旧值**，

- 不丢密钥）；

- - **改密钥/模型等字段**：`config-set scope=apiProfiles key=<档案名>

- value={apiKey|advancedModel|basicModel|...}`（未提供的字段保留现值，

- configJson 自动组装）；

- - **切换档案**：`config-set scope=apiProfiles key=<档案名>

- value={isActive:true}`（写 DB，**对新会话立即生效**；已有会话绑定创建

- 时的档案、不受切换影响——会话隔离；子代理会话严格绑定、档案被删会失败）；

- `scope=app activeProfile` 仅 CLI 兼容层，不改变运行时档案；

- - **删除档案**：先经 `askUserQuestion` 获用户同意，再

- `config-delete scope=apiProfiles key=<档案名> confirmed=true`

- （存储层自动保证至少一个生效档案）；

- - 密钥读取一律脱敏（如 `sk-****abcd`），**不要索要或展示明文密钥**。

- - **代理 / 主题等配置**：通过 `config` 工具读写白名单域——`proxy`

- （proxy-config.json）、`custom-headers`、`system-prompt`、`theme`、

- `language`、`permissions`、`lsp-config`、`buddy`。

- 文件型配置写后**可能需要重启应用或 UI 重存生效**。

- - **子代理**：先 `config-list scope=subAgents` 查看现有代理与响应中的

- **创建规则 guidance**；`config-set scope=subAgents key=<agentId> value={name,

- description, systemPrompt, toolsJson, configProfile}` 创建/更新；

- `config-delete scope=subAgents key=<agentId>` 删除；写入应用数据库**立即生效**。

- 关键规则：

- - `toolsJson` 接受 JSON 字符串或工具名数组；**显式工具名列表必须传

- `projectId`（项目级）**——全局代理只能用 `"*"`（全部工具）或空列表；

- 每个工具名必须是该项目已启用的工具全名

- - `configProfile` 必须是已存在的 API 配置档名，留空 = 跟随全局生效配置

- - `systemPrompt` 必须**完全自包含**（子代理无会话历史：使命/原则/流程/工具用法/输出格式）

- - 项目级代理激活时优先于同名全局代理；内置 `agent_general` 不可修改/删除

- - 详细规则见文档 `2-使用指南/5-配置Hooks与子代理.md` 第 2 节

- - **Hooks**：`config-list scope=hooks` 查看；`config-set scope=hooks

- key=<hookType> value={rules:[{description, matcher?, hooks:[{type,

- command?|prompt?|content?, timeout?, enabled:true}]}]}` 配置；传 `projectId`

- 为项目级。**每个需要执行的 action 都必须显式写 `enabled: true`；缺省、

- null 或 false 均不会执行。**写入应用数据库立即生效。

- - **全局规则（personalization）**：`~/.snow/ROLE.md` 是全局角色/规则文件

- （纯文本 markdown，非 JSON）。`config-list scope=personalization` 返回

- 键规格 + 长度/预览；`config-get scope=personalization key=role` 返回规则

- 全文（文件不存在时返回 null）；`config-set scope=personalization key=role

- value=<字符串>` 整体替换规则全文（写前自动备份，写后下一个对话生效）；

- `config-delete scope=personalization key=role` 删除 ROLE.md（恢复默认，

- 需用户确认）。修改后提示用户到「设置 → 个人化设置」或重启应用生效。

- - **管理 Skills**：先读安装管理指南。扫描同 ID 覆盖优先级为

- `<project>/.snow/skills` > `<project>/.agents/skills` > `~/.snow/skills` >

- `~/.agents/skills`。用 `config-list scope=skills` 查看有效 `path`、状态与

- GitHub 已装记录；用 `config-set scope=skills key=<skillId>

- value={enabled: true|false}` 切换开关——config API 参数名是 `enabled`，

- 但不传 `projectId` 时实际改写 SKILL.md frontmatter 的 **`enable`** 字段；

- 传 `projectId` 时写入项目数据库覆盖，且优先于 frontmatter。GitHub 安装用

- `value={url, location}`，`location` 为 `global` 或 `project`（项目安装需

- `projectId`）。`config-delete scope=skills key=<skillId>` 仅卸载

- `~/.snow/skills-registry.json` 已登记的 GitHub Skill，且删除前必须确认；

- 手动放置或应用自带 Skill 不在此卸载边界内。

- - **创建 / 编写 Skills**：必须先完整阅读

- `2-使用指南/21-创建与编写Skills.md`（en:

- `2-guides/21-create-and-author-skills.md`）。真实 frontmatter 字段是

- **`enable` 与 `allowed-tools`**，不是 `enabled` / `allowed_tools`；技能 ID

- 来自 `SKILL.md` 相对扫描根目录的路径，不来自 `name`。创建前检查四个扫描

- 根目录的同 ID 覆盖，使用最小权限工具列表，创建后用 config list/get 核对

- `id`、`path`、`defaultEnabled`、`enabled` 与 `allowedTools`，再运行只读测试。

- - **图像生成（多渠道）**：用 `config-list scope=imagegen` 查看各渠道状态

- （enabled/model/configured）与全局 `maxConcurrentImages`（最大并发生成数

- 1-8，默认 4，AI 一次请求多张时最多同时生成的张数）；写入用 `config-set

- scope=imagegen value={channels:[...]}` 全量替换，或 `{<channelId>: {...}}`

- 按渠道合并（**未提供的字段保留原值**，`maxConcurrentImages` 也会保留除非

- 显式提供），或 `{maxConcurrentImages: 6}` 单独调整并发数（自动收敛 1-8）；

- `config-get scope=imagegen key=<channelId|openai|gemini|maxConcurrentImages>`

- 读取（省略 key 返回完整设置）；`config-delete scope=imagegen` 清空。写入

- 应用数据库 `system_settings` 表（code=`imagegen_settings`）**立即生效**，

- 与设置面板同源；图形界面为**设置 → 图像生成**

- （`app-control-openSettings page=imagegen-settings`）。注意：渠道需

- `enabled`+`apiKey`+`model` 三者齐备才可用，所有渠道均未配置时

- `imagegen-generate` 工具对模型隐藏；`apiKey` 读取一律脱敏

- （如 `sk-e****7890`），**不要索要或展示明文密钥**。

- - **日志诊断（只读）**：应用异常时用 `config-list scope=logs` 列出

- `~/.snow/log` 下的日志文件（含最近 error 文件摘要），用 `config-get

- scope=logs key=<文件名>` 或级别简写（`error`/`warn`/`info`/`debug`，读取

- 今天的对应文件）读取日志尾部（可选 `limit` 控制行数，默认 200、最大

- 2000）定位异常；`config-delete scope=logs key=<精确文件名>` 清理日志。

- 日志路径也可在 **设置 → 系统日志**（`app-control-openSettings page=system-logs`）

- 查看。

- - **安全须知**：`config` 工具只能读写白名单内的配置域与键，写前有类型与

- 嵌套结构校验（`codebase`/`custom-headers.schemes`/`system-prompt.prompts`/

- `lsp-config.servers` 深度校验，防止写坏内部字段）；`config-get` 对

- `apiKey`/`visionApiKey`/自定义请求头/系统提示词等敏感键强制脱敏

- （如 `sk-****abcd`），**不要向用户索要或试图获取明文密钥**；每次写入前

- 自动备份到 `~/.snow/.config-backups/`，写入为原子替换，**写入成功后清理

- 本次备份**（临时安全网）。

- - **删除必须二次确认**：`config-delete` 是破坏性操作，**调用前必须先通过

- `user-interaction` 的 `askUserQuestion` 向用户展示将要删除的 scope/key 与

- 影响，获得明确同意后携带 `confirmed: true` 调用**，否则会被拒绝。特别

- 注意：`imagegen` 域的 delete 是**清空全部图像生成渠道**（不是只删命名

- 键）；`skills` 域 delete 卸载技能；`logs` 域 delete 删除日志文件。任何

- delete 前都先 `config-get`/`config-list` 确认现状。

- - **打开设置页**：用 `app-control-openSettings page=<page id>`。全部 21 个

- 页面 id：`api-settings`（API 档案）、`imagegen-settings`（图像生成）、

- `image-library`（图片库）、`proxy-browser-settings`（代理与浏览器）、

- `codebase-settings`（代码库）、`system-prompt-settings`（系统提示词）、

- `personalization-settings`（个性化）、`custom-headers-settings`（自定义请求头）、

- `mcp-settings`（MCP）、`import-settings`（第三方配置导入）、`skills-settings`

- （Skills）、`sub-agent-settings`（子代理）、`sensitive-command-settings`

- （敏感命令）、`hooks-settings`（Hooks）、`theme-settings`（主题）、

- `terminal-settings`（终端）、`browser-settings`（浏览器设置）、

- `keyboard-shortcuts-settings`（快捷键）、`privacy-settings`（隐私）、

- `usage-settings`（用量统计）、`system-logs`（系统日志）。

- **agent 可配置 vs UI-only**：除以下页面外均可由 agent 用 config 工具直接

- 读写（见上文各域）：`import-settings`（导入）、`terminal-settings`（终端）、

- `keyboard-shortcuts-settings`（快捷键）、`privacy-settings`（隐私，部分由

- `permissions` 域覆盖）、`usage-settings`（用量，仅 `logs` 域只读覆盖）、

- `image-library`（图片库，只读展示）、`browser-settings`（浏览器设置——

- 页面可打开，但**起始页/密码为 UI-only**，agent 不能读取或修改密码）——

- 这些为 UI-only，agent 只能打开设置页引导用户操作，不能直接改配置。

- - **编辑配置文件**：需要读写 `~/.snow/` 下的 JSON 时使用 filesystem 工具，

- 注意 **Windows 路径中的反斜杠必须写成 `\\`**（JSON 转义），否则

- `\f`/`\n`/`\v` 会被解析为转义序列导致配置失效。

+ **安全约束（所有域通用）**：config 工具仅读写白名单域，写前类型/结构校验 +

+ 自动备份到 `~/.snow/.config-backups/`（成功写入后清理）；`apiKey`/`visionApiKey`/

+ 自定义请求头/系统提示词读取一律脱敏，**不索要或展示明文**；**`config-delete`

+ 必须先经 `user-interaction` 的 `askUserQuestion` 获得用户明确同意，再带

+ `confirmed: true` 调用**（`imagegen` 清空全部渠道、`skills` 卸载、`logs` 删文件）。

+ **打开设置页**：`app-control-openSettings page=<id>`——21 个页面 id 及

+ "agent 可配置 vs UI-only"标注见 `3-参考手册/2-内置工具参考.md#app-control`

+ 表格。UI-only 页面（导入/终端/快捷键/隐私/用量/图片库/浏览器密码等）agent

+ 只能打开页面引导用户操作，不能直接改配置。

+ **编辑 ~/.snow JSON**：用 filesystem 工具；Windows 路径反斜杠必须写成

+ `\`（JSON 转义），否则 `\f`/`\n`/`\v` 被解析为转义序列导致配置失效。

## 3. 完成确认（Confirm with the user）

配置完成后，向用户确认结果，并主动询问是否需要进一步验证

（例如获取 MCP 工具列表验证连通性、读取日志确认异常已消失）。