机体（EVA）使用说明书（详尽版）¶

本说明书面向最终用户与技术向用户，涵盖安装部署、界面操作、模式与状态、工具与增殖、知识库构建、语音/视觉、多模态输入、速度/记忆显示、常见问题与排障、以及“解压即用”打包建议。

1. 安装与首次启动¶

系统需求：
Windows 10/11 或主流 Linux 桌面（x86_64/arm64）；
显卡可选：NVIDIA（CUDA）、任意（Vulkan/OpenCL）或 CPU；
Qt 5.15 运行时已随程序打包；无需手动安装。
解压即用布局（建议）：
程序：build/bin/eva(.exe)
后端：EVA_BACKEND/<arch>/<os>/<device>/<project>/（例如：EVA_BACKEND/x86_64/cuda/llama.cpp/llama-server.exe）
模型（可选）：EVA_MODELS/{llm,embedding,speech2text,text2speech,text2image}/...
数据：首次运行在同级创建 EVA_TEMP/，保存配置/历史/中间产物。
首次启动行为：
若 EVA_TEMP/eva_config.ini 不存在，自动扫描 EVA_MODELS/** 并为各功能选择“最小/合适”的默认模型路径（LLM/Embedding/Whisper/tts.cpp/SD），写回配置。
Windows 首次运行会自动生成桌面/开始菜单快捷方式（AppImage 模式同理）。

2. 界面与五个按钮¶

装载：选择“本地模式/链接模式”；本地模式选择 gguf 模型并启动本地服务；链接模式填写 endpoint/key/model 切换远端。
约定：设置系统提示词、昵称；挂载工具（勾选）并可设置“工程师工作目录”。
设置：采样参数（温度/top_k/top_p/n_predict 等）、后端参数（设备/nctx/ngl/线程/并发/端口等）；必要时重启本地服务并恢复 UI。
重置：终止当前推理；再次点击清空并开始新对话。
发送：将当前输入/选中图像/音频封装为 OpenAI 兼容消息发送；工具挂载时将进入“工具调用循环”。
状态机：
装载前：仅“装载”可用；
装载中：五按钮禁用；
正常：全部可用；
推理中：仅“重置”可用；
录音中：F2 控制，结束后转写回填输入。
快捷键：F1 截图、F2 录音、Ctrl+Enter 发送。

3. 模式与多模态¶

两种模式：
本地：托管 llama.cpp tools/server，统一通过 HTTP+SSE 推理。
链接：OpenAI 兼容端点（/v1/chat/completions 或 /completions）。
两种状态：
对话：常规多轮（system+user/assistant），支持图像/音频。
补完：将输出区文本作为 prompt 一次性补全。
图像：拖拽/右击上传/F1 截图；作为 image_url 内嵌；本地+视觉模式可“预解码”。
音频：上传 wav/mp3/ogg/flac，发送前自动转换为 input_audio 结构；F2 录音→whisper 转写。

4. 加速与设备选择¶

设备：自动/CPU/CUDA/Vulkan/OpenCL；“自动”将按 cuda>vulkan>opencl>cpu 选择已打包后端。
GPU offload（ngl）：
首次装载将按“模型体积 vs 当前可用显存（vfree）”估算是否全量 offload（ngl=999），>95% VRAM 将回退；
装载完得到 n_layer+1 后自动修正滑条最大值；
CPU/OpenCL 选择时禁用 ngl 滑条。

5. 工具（Agent）与工程师工作流¶

原理：系统指令中注入“工具协议”；模型以 <tool_call>{name,arguments}</tool_call> 发起调用；EVA 执行并以 tool_response: ... 继续推理。
常用工具：
计算器：表达式求值。
工程师链：execute_command/read_file/write_file/replace_in_file/edit_in_file/list_files/search_content/ptc/MCP。
ptc（programmatic_tool_calling）：当命令行变得冗长时，直接提供脚本文件名、运行目录（默认为 .）和 Python 内容，EVA 会将脚本写入工作区的 ptc_temp 目录并立即执行，把 stdout/stderr 结果回填给模型。
知识库：查询向量数据库，返回 Top-N 文本片段。
桌面控制器：执行行动序列，返回当前截图（需谨慎使用）。
文生图：交由“增殖-文生图”执行，完成后在输出区展示图片。
MCP：连接外部 MCP 服务并路由 service@tool 调用。
技能系统（Skills）：
在“约定”面板勾选“系统工程师”后会显示“技能挂载”区域，可将技能 .zip 包拖拽到此区域完成安装，复选框控制启用/禁用，右键可卸载；安装内容默认保存在应用目录的 EVA_SKILLS/<skill-id>。
EVA 会在工程师工具激活时自动同步内置技能，并把已启用技能的 SKILL.md 路径写入系统提示，模型会遵循其中的操作流程；如需查看指引，可通过“读文件”工具打开对应 SKILL.md。
建议从 参考项目/skills-main 等来源获取技能，导入前确认许可证与脚本安全，必要时在工程工作目录预先准备运行脚本所需的依赖。
工程师工作目录：在“约定”面板勾选“系统工程师”后出现，点击“浏览”设置；工程师工具默认只在该目录下读写，所有路径会被归一化回该根。
安全边界：
execute_command/ptc/文件写入具有破坏性；默认限制在 EVA_WORK；
桌面控制器需模型具备视觉；强风险工具请手动挂载并确认动作。

6. 增殖（Expend）能力¶

视觉：在设置中选择 mmproj；拖拽/上传/截图后点击“发送”进行预解码，再进行问答。
声转文（Whisper）：在“增殖-声转文”选择 whisper 模型；按 F2 开始/结束录音，自动转写回填。
文转声（TTS）：系统语音或 tts.cpp；选择后自动朗读模型输出，或手动输入文本生成音频并播放。
知识库：
启动嵌入服务（选择嵌入模型→启动），逐段调用 /v1/embeddings 入库，维度会从服务日志自动识别；
“知识库”工具开启后，模型可发起语义检索，返回相似片段。
文生图：配置 SD/Flux，支持 prompt 风格模板；生成后自动展示图片。

7. 速度与记忆显示¶

速度：
single decode = 生成速度（predicted_per_second），batch decode = 上文处理速度（prompt_per_second）；
源于 SSE JSON 的 timings；若缺失相应字段显示为 --。
记忆进度条（KV）：
本地模式基于 server 日志矫正（n_ctx_slot/kv cache rm/prompt done/stop processing）；
链接模式按流式 tokens 近似更新（本轮基础上累加）。

8. 常见问题与排障¶

装载卡住：查看“模型日志”页是否出现 listening on/at；检查模型路径/权限；LoRA 尝试关闭 mmap；GPU 端尝试减小 ngl 或先 CPU 验证。
链接无响应：检查 endpoint 是否是 /v1 根；证书是否受信；SSE 是否被代理/防火墙拦截；模型名是否存在。
工具链循环：确认工具停词是否在非 think 区域；必要时在策略中增加 answer 步骤；
速度与记忆：输出结束时状态区会打印 single/batch 速度；记忆进度条工具提示展示 used/max token。
Windows 找不到 python3：优先安装 Python Launcher（py -3）或创建 .venv；程序会自动探测并使用。

9. 数据与文件¶

EVA_TEMP：保存 eva_config.ini、历史会话（EVA_TEMP/history//{meta.json,messages.jsonl}）、截图缓存、临时音频等。
EVA_BACKEND：随包分发第三方可执行与依赖；
EVA_MODELS：按功能归类模型，便于首次自动发现与用户配置。

10. 打包建议（中央教条）¶

将可执行、EVA_BACKEND、必要 thirdparty 与资源、可选 EVA_MODELS 一并打包；
统一使用纯英文路径与短路径兼容（Windows）；
Linux AppImage：可选启用 BODY_PACK 并结合 linuxdeploy 完成打包；
首次启动在同级创建 EVA_TEMP，后续启动自动读取配置。

11. 版本与升级¶

建议在“设置-后端”中查看当前设备后端与线程/并发参数；
升级后端或模型：覆盖 EVA_BACKEND/ 或替换 EVA_MODELS/ 对应文件夹；如遇问题，先清空 EVA_TEMP/ 重新启动进行自动发现与初始化。