# 雪艺小艺使用指南

按“简介 → 安装 → 配置与使用 → 故障排除 → 关于”查找需要的说明。

## 简介

### 01 / 什么是小艺

小艺是在电脑上运行的工作助手。它围绕当前工作区阅读资料、整理文件、生成内容，并在你启用后调用本机工具与插件。使用在线模型时，相关请求会发给所选模型服务商。

桌面版适用于 Apple 芯片 Mac 和 Windows x64；Linux x86_64 服务器另有只提供公司账户登录与文字对话的终端版。可用能力取决于账户权限、模型、插件和本机环境。

### 02 / 快速开始

先完成安装与登录，再用一个可核验的小任务确认模型和工作区是否选对。

1. 从下载中心获取对应系统的安装包；Linux 服务器按下文安装终端版。
2. 公司用户登录管理员开通的账户；桌面个人模式可自行配置模型 API Key。
3. 桌面版选择工作区，再输入明确的任务，例如“阅读 README，整理启动步骤，先不要修改文件”。
4. 检查过程和输出。文件修改、外部发送及重要业务结果需要按实际影响复核。

## 安装

### 03 / 安装前检查

官网下载安装区从已验收安装包清单读取当前版本。下载安装包后可用同卡片的 SHA-256 校验文件核对完整性；客户端增量更新包与首次安装包分别发布。

Mac 需要 Apple 芯片及 macOS 15 或更新版本；Windows 桌面版面向 Windows 10 / 11 x64。Linux 终端版需要 Linux x86_64、Python 3.9+，以及访问公司账户服务和已授权模型服务商的网络。

- Mac 安装包尚未完成 Apple Developer ID 签名与公证；Windows 安装包尚未完成发布者签名，均供公司内部测试。
- 安装包不附带公司账户密码、模型 API Key 或免费额度。

### 04 / macOS 桌面版

可以从下载中心取得 DMG，打开后把“雪艺小艺.app”拖入“应用程序”。也可以在尚未安装小艺的 Apple 芯片 Mac 上使用以下命令；脚本会核对文件大小和 SHA-256，安装到当前用户的“应用程序”目录。

命令行首次安装尚未在全新 Mac 上完成整条实机验收。已有小艺时，安装脚本会拒绝覆盖，请在应用内检查更新。

**Mac 终端 · 首次安装**

```sh
curl -fsSL https://8.163.48.125:9445/install/desktop-macos.sh | sh
```

### 05 / Windows 桌面版

从下载中心取得 EXE 并按向导安装；公司内部 Windows 11 x64 测试机已验证安装、启动、登录、重装后数据保留与当前版检查更新。

也可在 PowerShell 使用下列安装命令。脚本会核对安装包大小和 SHA-256 后运行安装程序；这条 PowerShell 命令本身尚未在 Windows 实机执行验收。安装前先保存内容并完全退出正在运行的小艺。

**PowerShell · 安装**

```sh
irm https://8.163.48.125:9445/install/desktop-windows.ps1 | iex
```

### 06 / Linux 终端版

终端版适合没有桌面环境的 Linux x86_64 服务器。安装脚本会校验发布文件的大小和 SHA-256，并放到当前用户的 ~/.local/bin；不需要安装桌面客户端。广州 Linux x86_64 服务器已完成一键安装与启动验证。

首版仅支持公司账户登录和文字对话。登录时交互输入密码；终端版按当前账户的模型权限与个人额度使用，不在发布包内保存公司密钥。

**Linux shell · 安装**

```sh
curl -fsSL https://8.163.48.125:9445/install/terminal-linux-x86_64.sh | sh
```

**登录并开始对话**

```sh
~/.local/bin/xiaoyi login
~/.local/bin/xiaoyi models
~/.local/bin/xiaoyi chat
```

- 单轮提问：~/.local/bin/xiaoyi ask '你好'；切换已开通模型：~/.local/bin/xiaoyi use 模型ID。
- 命令找不到时，直接使用 ~/.local/bin/xiaoyi，或把 ~/.local/bin 加入 PATH。
- 令牌仅保存在当前用户的 ~/.config/xiaoyi-cli/account.json；请勿共享该目录或把密码写进命令行参数。

## 配置与使用

### 07 / 工作区与任务

桌面版围绕当前工作区处理任务，可按权限读取、搜索和修改文件。开始前确认工作区与任务权限；需要只看不改时选择只读。

将不同客户项目和私人资料放在不同工作区。会话可继续已有对话，生成的文件应按会话核对，关键输出请在原应用中复核。

### 08 / 模型选择

桌面版可分别选择对话模型和读图模型；发送含图片的消息时使用可读图的模型，后续纯文字消息使用对话模型。可选模型取决于公司后台开通情况。

终端版用 xiaoyi models 查看当前账户获准的模型，用 xiaoyi use 模型ID 选择文字对话模型。终端版暂不支持读图、插件和桌面操作。

### 09 / 知识库

知识库是你选定的本机 Markdown 文件夹。可以使用已有笔记目录，包括 Obsidian 目录；小艺不会要求你先把资料搬到官网。

在小艺的“工作位置与知识库”里选择文件夹后，可按目录浏览笔记，使用全文搜索、标签、双向链接和反向链接找回相关内容。Markdown 文件仍保存在该文件夹。

1. 选择一个本机文件夹，先放入少量常用资料或现有笔记。
2. 按项目或主题整理目录；在笔记中写清标题、来源与需要复用的内容。
3. 使用搜索和笔记链接找到资料，再将核实过的结果用于任务。

### 10 / 办公插件

内置插件覆盖 Excel 表格、Word 文档、价格复核、合同模板、图片处理和微信长图。打开插件库选择能力，再提供需要处理的文件和目标。

- Excel：读取 XLSX / CSV，整理、合并和去重；复杂公式仍需在 Excel 或 WPS 中复核。
- Word：提取 DOCX 正文，生成包含标题、段落和表格的新文档。
- 价格复核：复算数量与金额，对照你提供的同口径参考价。
- 合同模板：按你提供的模板和字段生成新合同，业务条款仍需人工确认。
- 图片与长图：处理常见图片，或把 Markdown 与本地配图导出为 PNG / HTML；不会自动发布到公众号。

### 11 / 公司账户与额度

管理员在公司后台开通用户、可用模型和每周预算。桌面版与 Linux 终端版使用同一公司账户；终端版按该用户的权限与额度预留、结算用量。

管理员可查看账户与用量统计。金额依据后台配置的价格估算，实际费用以服务商账单为准。

[打开管理后台](https://8.163.48.125:9444/admin)

### 12 / 文件与云端存档

会话、工作区和知识库资料主要保存在你的电脑。使用在线模型或第三方工具时，相关输入会按任务需要发送给所选服务；处理敏感资料前请确认模型和工具设置。

个人云端存档需要主动开启，使用客户端持有的密钥加密项目快照。换电脑恢复时，须保留同一把密钥；关闭电脑后云端不会继续执行任务。公司账户服务器保存身份、权限和用量元数据。

- 退出或更新应用前，先保存正在编辑的内容。
- 迁移电脑前，备份本机数据目录和需要继续使用的密钥。
- 知识库本机文件夹和云端快照是两种不同的保存方式。

### 13 / 软件更新

桌面版可在“设置 → 软件更新”检查公司签名的兼容更新。下载安装包和客户端增量更新包分别发布；官网只展示已验收的首次安装包版本。

更新准备好后，先保存草稿、结束正在运行的任务，再按界面提示安装。若旧版只显示“更新已就绪”，正常退出并重新打开，旧版更新器会在启动时处理已下载的更新。

- 下载尚未完成时不要强制关闭应用。
- 更新失败时记录时间与日志，并保留上一版安装包。
- 历史变更及验收状态请查看更新记录。

[查看更新记录](/updates)

## 故障排除

### 14 / 常见问题

应用打不开：检查操作系统、处理器和安装包 SHA-256 是否匹配；Windows 先确认已保存内容并退出旧进程。

无法登录或调用模型：检查网络、账户状态、获准模型与剩余额度。不要把密码、完整 API Key 或令牌发给其他人。

找不到文件：检查当前工作区和知识库目录，以及文件是否仍在本机。

终端版提示命令找不到：使用 ~/.local/bin/xiaoyi；提示平台不支持时，核对 Linux x86_64 与 Python 3.9+。

## 关于

### 15 / 更新记录与反馈

更新记录按组件与日期区分桌面客户端、官网、终端版和后台，不把代码提交当作已上线版本。每条记录注明验收状态与仍待验证的部分。

遇到问题时，请记录操作步骤、系统和版本、发生时间以及不含敏感信息的日志，再交给公司管理员。

[查看最近更新](/updates)