01下载与安装
HanCore AI 工作站目前支持 Windows 10 及以上系统（x64）。安装包内置了 CPU 和 Vulkan 推理后端，安装后即可使用，无需额外下载。
下载安装包
从铭瀚芯官网下载 AIWorkstation-Setup-x.x.x.exe（NSIS 安装包，约 400MB）。
Electron 桌面应用 + Python 离线运行时 + llama.cpp 推理引擎（CPU + Vulkan）。NVIDIA 显卡用户首启动后会自动下载 CUDA 后端。
运行安装程序
双击 .exe 安装包，按提示完成安装。建议安装到纯英文路径（如 D:\AIWorkstation）。
llama.cpp 在 Windows 下不能稳定读取中文路径。请确保安装路径、GGUF 模型文件路径、Chat 模板路径、mmproj 路径全部为纯英文。例如：D:/Models/Qwen2.5-32B.gguf ✓ D:/模型/Qwen.gguf ✗
首次启动
安装完成后，从开始菜单启动 AIWorkstation。首次启动会自动初始化 Python 运行时（约 10-30 秒），无需联网。
启动完成后，你会看到 License 激活界面。
02激活 License
首次启动 HanCore 需要输入 License Key 完成激活。License 绑定你的机器硬件指纹，激活后离线也可使用。
输入 License Key
在 License 激活界面输入你购买的授权密钥，点击「验证」。
系统会联网验证 Key 有效性，并将授权信息绑定到你的机器。
验证通过后进入主界面
验证成功后，License 信息会持久化存储在系统目录（非浏览器缓存，清除浏览器数据不会丢失激活状态）。
之后每次启动，如果检测到已激活的 License，将直接进入主界面。
License 首次激活需要联网。激活成功后，后续使用完全离线——系统会通过本地公钥验签 + 硬件指纹比对来验证授权。
03加载第一个模型
HanCore 使用 GGUF 格式的开源大模型。你需要先下载一个 GGUF 模型文件，然后在工作站中添加它。
推荐模型
| 模型 | 参数量 | 最低 VRAM | 推荐场景 |
|---|---|---|---|
| Qwen2.5-32B | 32B | 8 GB | 综合能力最强，128K 上下文 |
| Qwen2.5-14B | 14B | 4 GB | 均衡选择，速度与质量兼顾 |
| GLM-4-9B | 9B | 3 GB | 中文场景表现优秀 |
| Llama-3-8B | 8B | 2 GB | 英文场景，轻量快速 |
| Qwen2-VL | 7B | 3 GB | 视觉模型（图片理解） |
添加模型步骤
打开模型中心
在左侧导航栏点击「本地模型」图标，进入模型管理页面。
点击「添加模型」
在卡片网格中点击虚线框的「添加」卡片，打开模型配置抽屉。
填写模型信息
在右侧 Sheet 抽屉中填写以下字段：
| 字段 | 说明 |
|---|---|
| 名称 | 模型的显示名称（如 Qwen2.5-32B） |
| 模型路径 | GGUF 文件路径，点「选择文件」浏览（纯英文路径！） |
| 上下文长度 | 默认 131072（128K），最低不可低于此值 |
| 并行槽位 | 默认 2，影响同时处理的请求数 |
| 后端偏好 | auto（推荐）/ cuda12 / vulkan / cpu |
保存并启动
点击「保存」，模型卡片出现在列表中。点击卡片上的「启动」按钮，工作站会：
- 自动检测你的 GPU 并选择最优后端（CUDA/Vulkan/CPU）
- 启动 llama-server 推理进程
- 将推理端点注册到 Hermes 对话引擎
- 状态变为「运行中」🆕
如果你已有一目录的 GGUF 文件，可以在模型中心使用「扫描目录」功能，自动发现目录下所有 .gguf 文件，然后逐个配置添加。
04开始第一次对话
模型启动后，点击左侧导航的「对话」进入聊天界面。你现在可以和本地 AI 对话了——所有推理在你的 CPU/GPU 上完成，文件不上传任何服务器。
试试这些操作
- 直接聊天：输入消息，AI 回复。和 ChatGPT 类似，但全程本地。
- 上传文件：拖入 PDF / DOCX / TXT / 代码文件，AI 能读取并分析内容。
- 写代码：要求 AI 编写/修改代码，如果激活了编程专家角色，它还能直接执行终端命令。
- 分析数据：拖入 Excel/CSV 文件，AI 读取并生成分析报告。
HanCore 默认配置 128K 上下文窗口。如果对话超长导致 AI "遗忘"前文，可以尝试增大 上下文长度 参数（但需更多 VRAM）。
05模型管理进阶
模型参数详解
| 参数 | 默认值 | 说明 |
|---|---|---|
| contextLength | 131072 | 单 slot 上下文长度。Hermes agent 需要 ≥128K。注意：实际单会话 = ctx ÷ parallel |
| parallelSlots | 2 | 并行推理槽位数。--parallel N 将 ctx 分成 N 份 |
| backendPreference | auto | auto 自动选择；可手动指定 cuda12/vulkan/cpu |
| reasoningMode | off | 推理链模式：off/auto/on。某些模型开启后会输出思考过程 |
| isVisualModel | false | 视觉模型需额外指定 mmprojPath（投影文件路径） |
| chatTemplatePath | — | Jinja 模板路径，特殊模型可能需要自定义对话模板 |
GPU 后端选择
HanCore 自动检测你的 GPU 并选择最优后端。如果你想手动指定（例如测试或排查问题）：
| GPU 品牌 | 推荐后端 | 说明 |
|---|---|---|
| NVIDIA | cuda12 | 最佳性能。需要 CUDA 运行时（首启动自动下载） |
| AMD | vulkan | Vulkan 通用 GPU 加速，随安装包内置 |
| Intel | vulkan | 同上 |
| 无独立显卡 | cpu | CPU 推理，速度较慢但功能完整 |
VRAM 与上下文调优
--ctx-size 是每个 slot 的上下文，不是总量。--parallel N 会把 ctx 分成 N 个 slot。
如果你设置 ctx-size=65536 + parallel=2，那么单次对话只能使用 32768 tokens 的上下文。而 Hermes agent 处理复杂任务时 input 可能达到 40-50K tokens，导致溢出。
建议：保持默认 ctx-size=131072。如需降低，参考下表。
| VRAM | 推荐配置 | 适用模型 |
|---|---|---|
| 16 GB | ctx 65536 + parallel 1 | Qwen2.5-32B（量化） |
| 32 GB+ | ctx 131072 + parallel 2 | Qwen2.5-32B / GLM-4 |
| 8 GB | ctx 32768 + parallel 1 | Qwen2.5-14B / 8B 模型 |
| 无 GPU | ctx 32768 + parallel 1 | 8B 以下模型（CPU 推理） |
VRAM 紧张时可添加 --cache-type-k q8_0 参数对 KV Cache 进行量化，减少显存占用（略微影响质量）。此功能需要通过自定义模型配置添加。
06智能体：安装你的 AI 助手
AIWS 支持多种 AI 桌面助手（Hermes、OpenClaw、OpenCode 等），统一在「智能体」页管理：安装状态、版本信息与运行情况一目了然。各智能体定位详见 产品功能介绍 · 智能体阵容。
安装与启停
打开智能体管理
在左侧导航点击「智能体」，进入智能体管理页面；已安装与未安装的智能体分列展示。
一键安装
选择需要的智能体（如 OpenCode），点击「安装」，安装完成后状态显示为已安装、待启动。
启动
点击「启动」即可运行该智能体；运行中的智能体可一键停止。安装与运行状态在卡片上即时更新。
停止 / 卸载
点击「停止」让智能体下线；如不再需要，可在管理页卸载，配置与数据目录会按提示处理。
同一时间只能有一个桌面模式的智能体处于运行状态，启动新的智能体时会自动停止之前的智能体；网关模式的接入（如微信机器人）独立运行，不受此限制。
配置工具与技能
安装智能体后，点击卡片的配置按钮打开右侧抽屉，可以精细控制其权限。
工具集（Toolsets）
| 工具 | 能力 |
|---|---|
| file | 读写本地文件 |
| web | 联网搜索和网页抓取 |
| terminal | 执行终端/命令行命令 |
| browser | 浏览器自动化操作 |
| code_execution | 沙箱内执行 Python 代码 |
| vision | 图片理解和分析 |
| image_gen | 图片生成 |
| video_gen | 视频生成 |
| skills | 调用已安装的 AI 技能 |
| todo | 任务管理和清单 |
| memory | 长期记忆存储 |
| delegation | 委派任务给其他智能体 |
| tts | 语音合成（文字转语音） |
根据智能体定位按需勾选。例如编程类助手通常需要 file + terminal + web。
行为准则定制（SOUL.md）
部分智能体的行为准则由 SOUL.md 文件定义，启动时写入工作目录；可按需修改，调整其回复风格与边界。
07微信接入（Gateway 模式）
微信接入通过独立网关进程运行，为 Hermes / OpenClaw 接入微信机器人；新联系人首次对话需经你批准。
微信接入需要安装额外的 Python 依赖包（aiohttp 和 cryptography）。首次绑定时会自动检查并提示安装。
安装微信接入
在「AI 辅助」页安装微信接入。微信接入为 gateway 模式，拥有独立的网关进程。
扫码绑定
点击微信助手的「渠道绑定」按钮，打开 3 步向导：
- 依赖检查 — 确认 aiohttp / cryptography 已安装
- QR 扫码 — 用手机微信扫描屏幕上的二维码，等待确认
- 访问策略 — 配置私聊策略（dmPolicy）和群聊策略（groupPolicy）
扫码确认后，微信凭证会自动写入配置文件。
激活并启动 Gateway
绑定成功后，激活微信助手。系统会自动：
- 确保 llama-server 推理引擎就绪（ctx ≥ 131072）
- 写入 SOUL.md（客服人格设定）
- 配置工具权限和技能
- 启动 Gateway Python 进程
- 状态变为 working
测试收发消息
用另一个微信号给你的 AI 微信号发消息，AI 会自动回复。你可以在对话界面查看消息记录和回复内容。
停止微信助手时，Gateway 进程会自动退出。
08多平台接入（陆续开放）
微信、飞书接入已上线可用；WhatsApp / Gmail / Outlook / Telegram / Discord / Google Chat 处于待接入状态，将陆续开放。以下流程以已上线平台为准。
除了微信，HanCore 还支持通过凭证表单快速接入其他主流即时通讯平台。Hermes 引擎内置了 24+ 平台适配器，零改动复用。
钉钉（DingTalk）
- 在钉钉开放平台创建自定义机器人，获取
client_id和client_secret - 在渠道绑定面板中选择「钉钉」，填入凭证
- 保存后激活即可
飞书（Feishu）
- 在飞书开发者后台创建应用，获取
app_id和app_secret - 在渠道绑定面板中选择「飞书」，填入凭证
- 保存后激活即可
Telegram
- 在 Telegram 中找
@BotFather创建 Bot，获取bot_token - 在渠道绑定面板中选择「Telegram」，填入 Bot Token
- 保存后激活即可
HanCore 的消息平台采用适配器架构（PlatformAdapter 接口）。开发者可以实现新平台的适配器并注册，无需修改核心 Gateway 代码。
09常见问题排查
模型启动失败
症状：模型启动时报路径错误或直接崩溃。
解决：检查 GGUF 文件路径、Chat 模板路径、mmproj 路径是否包含中文字符。将模型文件移动到纯英文目录，如 D:/Models/。
症状：模型加载到一半报错，或推理时崩溃。
解决：
- 降低
contextLength（如从 131072 降到 65536 或 32768） - 设置
parallelSlots为 1 - 使用参数量更小的模型（如 14B 代替 32B）
- 使用量化版本（如 Q4_K_M 而非 FP16）
对话响应异常
原因：上下文窗口不足。实际单会话可用 = ctx ÷ parallel。
解决：增大 contextLength 或将 parallelSlots 设为 1。注意 VRAM 消耗会相应增加。
原因：模型切换仅影响新会话。已有的对话窗口不会自动切换。
解决：开一个新对话即可使用新模型。
进程残留
原因：程序崩溃或强制关闭后，子进程可能仍在后台运行。
解决：HanCore 在启动时会自动检测并清理残留进程。如需手动清理：
# 查找残留的 llama-server 进程
tasklist | findstr llama-server
# 强制终止
taskkill /F /IM llama-server.exe微信绑定问题
可能原因：
- 网络问题导致轮询超时——检查网络连接
- 微信版本过低——更新到最新版微信
- 凭证已过期——重新扫码绑定