大牛交付文档

设备怎么用，出问题怎么退出来

这份文档写给客户和维护人员。客户只看前两部分；维护人员重点看小屏、麦克风、网络和日志。

客户只需要会开机、说话、打开 App。维护人员必须知道如何退出小屏、授权麦克风、重启服务。量产版本要固定签名和固定 IP，减少现场授权和网络问题。

当前版本的重要提示

小屏全屏后普通用户不一定能退出。现场维护请先接键盘，使用 Command + Option + Esc 强制退出，或按文档命令关闭 kiosk。

客户看到的版本小屏终端麦克风网络沉淀资料维护人员

客户看到的版本

拿到设备后怎么用

大牛设备默认插电启动，进入小屏眼睛界面。用户不用进入 macOS，也不用打开开发工具。

正常使用

接通电源，等待小屏出现大牛眼睛。看到待命状态后，直接对着麦克风说话；大牛会语音回答，也可以在局域网电脑打开 App 文字对话。

电脑访问

电脑和大牛在同一个局域网时，浏览器打开 http://设备IP:3000。进入 App 后可以问大牛、沉淀资料、查看牛大脑。

手机访问

当前阶段建议先连同一个 Wi-Fi 访问。后续如果要外网访问，需要单独配置穿透或企业 VPN。

小屏终端

全屏眼睛和语音交互

小屏是大牛的实体交互入口。它应该像家电一样开机即用，但仍然需要维护人员知道如何退出。

眼睛状态

待命时轻微呼吸，听到声音会聚焦，思考时扫描，回答时会有说话动作。异常或麦克风未授权时会进入阻塞状态。

退出全屏

接键盘后按 Command + Option + Esc，选择 Daniu Display 或 daniu-display，点击强制退出。

命令退出

如果强制退出窗口打不开，打开 Terminal 执行下面命令。

维护命令

launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/cn.daniu.kiosk.plist 2>/dev/null || true
launchctl disable gui/$(id -u)/cn.daniu.kiosk
pkill -f DaniuDisplay.app
pkill -x daniu-display

重新启用小屏

维护完成后可重新加载小屏终端。

维护命令

launchctl enable gui/$(id -u)/cn.daniu.kiosk
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/cn.daniu.kiosk.plist 2>/dev/null || true
launchctl kickstart -k gui/$(id -u)/cn.daniu.kiosk

麦克风

授权和无反应排查

语音终端依赖 macOS 麦克风权限。只要 Daniu Voice 被重新编译或替换，系统可能再次要求授权。

打开权限设置

系统设置里进入隐私与安全性，找到麦克风，打开 Daniu Voice。

维护命令

open "x-apple.systempreferences:com.apple.preference.security?Privacy_Microphone"

重启语音服务

授权后重启语音守护进程，让权限立即生效。

维护命令

launchctl kickstart -k gui/$(id -u)/cn.daniu.voice

判断是否正常

正常状态应该显示大牛待命。若仍然等待授权，说明权限没有打开或 App 被系统重新识别。

维护命令

curl -sS http://127.0.0.1:3000/api/terminal/state

客户交付建议

量产版本必须使用稳定签名，不要每次部署都重签语音 App；企业批量交付可考虑 MDM/PPPC 预授权。

网络

访问不到设备怎么办

大牛是本地设备，优先保证局域网稳定。访问不到时先判断 IP、网线、Wi-Fi 和服务状态。

确认 IP

在 Mac 上查看当前 IP，或从路由器后台看大牛设备分配到的地址。建议交付时绑定固定 IP。

维护命令

ipconfig getifaddr en0 || ipconfig getifaddr en1

检查 Web 服务

本机打开健康检查，能返回 ok 说明 App 服务在跑。

维护命令

curl -sS http://127.0.0.1:3000/api/health

重启 Web 服务

如果 3000 不通，重启大牛主服务。

维护命令

sudo launchctl kickstart -k system/cn.daniu.app

远程维护

开启远程登录后，维护人员可用 SSH 进入设备。客户环境建议只开放给内网或 VPN。

沉淀资料

资料导入和经验资产原则

老板不应该理解复杂配置。资料模块的目标是拖进去、自动去重、自动整理、整理好就能问。

推荐导入

优先导入产品手册、报价规则、售后案例、项目方案、制度流程。图片、音频、视频会先保存，配置 OCR/ASR 后再后台补齐。

大批量导入

一次几千份资料时，系统会分批处理、去重和跳过不支持格式。不要把 .git、node_modules、系统缓存目录拖进去。

重复文件

同名不代表重复，系统以内容指纹为准；重复资料会跳过，不应该反复进入队列。

资料回答

默认不展示出处，只有用户明确问依据、来源、哪份资料时才显示引用。语音终端会进一步压缩答案。

维护人员

生产交付检查清单

每次交付前按这份清单过一遍，避免客户拿到设备后卡在授权、网络或服务启动上。

开机自启

重启设备后，应自动进入小屏眼睛页面，Web 服务、资料整理 worker、处理器和语音守护进程都应运行。

核心检查命令

确认 App、处理器和语音状态。

维护命令

curl -sS http://127.0.0.1:3000/api/health
curl -sS http://127.0.0.1:8100/health
curl -sS http://127.0.0.1:3000/api/terminal/state

日志位置

出现异常先看日志，不要盲目重装。

维护命令

tail -f /var/log/daniu/app.err.log
tail -f /var/log/daniu/worker.err.log
tail -f ~/Library/Logs/Daniu/voice.log
tail -f ~/Library/Logs/Daniu/kiosk.err.log

下一版必须补齐

后台应提供一键维护模式、隐藏退出手势、远程关闭小屏、服务状态面板和客户可读的错误提示。

后续产品化建议

这份文档解决“知道怎么处理”。下一步应该在系统里做“一键维护模式”，让现场人员不用记命令。

进入 App