数字人配置入口：现在按设备在网站设置

接口账户与计费方式：
网站“客户与接口”→“接口设置 / 编辑”，选择该客户默认使用“平台接口 · 共用算力点”或“客户自备火山接口 · 不扣算力点”。
平台模式使用管理员服务器密钥，继续按原比例扣客户共享余额；自备模式由客户自行开通火山服务并充值。
客户的语音 API Key、方舟 API Key 可在同一窗口填写，留空保留。密钥只保存服务器，不回显、不发到本地。
“设备管理”→“设备配置”可选择继承客户模式，也可为单台设备指定模式。
自备密钥优先使用设备独立设置，其次使用所属客户密钥；都没有时停止调用，不回退平台密钥、不扣算力点。
资源 ID、音色和模型仍在设备配置中选择，必须在实际扣费的火山账户开通。可用窗口中的三个接口测试按钮确认。
两种模式都需要设备授权有效；自备模式也保留本机与服务器调用日志，实际费用以客户火山账单为准。
模式或密钥变更前先结束相关设备的对话（必要时退出客户端）；有进行中调用时网站会阻止保存。
本次改动在服务器生效，已经下载的新版客户端和安装包不用更换。

客户安装：
推荐使用 AIAvatar-Setup-1.0.5-Windows-x64.exe；也可完整解压 AIAvatar-Windows-Standalone-1.0.5.zip 后双击 Start.exe。
这两个版本内置 Python 与运行依赖，无需另外安装 Python，支持 Windows 10/11 64 位；需要 Chrome 或 Edge。
安装版默认安装到当前用户的 LocalAppData\Programs\CLCulture\AIAvatar，提供桌面、开始菜单和卸载入口。
升级保留 startup-config.json；卸载保留用户目录中的设备身份、缓存和消费日志。
不要单独复制 Start.exe，也不要删除 runtime 文件夹；内置环境损坏时请重新完整解压或重装。

OSS 版素材：
视频、图片、媒体规则、唤醒模型存放在私有 OSS，服务器数据库保存素材版本与校验信息。
首次启动下载并校验到本机缓存。版本不变不下载；更新只下载变化/缺失文件；损坏只修复损坏文件。
人设/知识库变化不重新下载未变化的视频；临时下载链接过期也不影响已保存素材。
媒体规则由管理员发布到服务器运行资源清单，OSS 版本地不再维护 keyword_media 素材文件夹。
新素材整组校验成功才启用；idle/talking 仍按配对版本管理。
素材缓存：%USERPROFILE%\.clculture\aiavatar\resource-cache；人像缓存：同目录 avatar-cache。
云服务密钥和 OSS 密钥都不会写入客户本地包。下载 OSS 时不携带设备授权 Token。

本地启动与显示（只修改 startup-config.json）：
双击 Start.exe：默认隐藏控制台，以 kiosk 模式全屏显示。
window_mode：kiosk = 全屏无地址栏；fullscreen = 普通全屏；normal = 普通窗口。
hide_console：true = 隐藏控制台；false = 显示控制台。
browser：auto = 优先 Chrome，回退 Edge；也可填 chrome 或 edge。
port：本机端口，默认 8765。不要在这里填写云 API Key。
microphone_name：录音设备名称，例如 USBAudio1.0；留空使用 Windows 默认输入。
多个麦克风时可填完整名称或唯一关键字；找不到或匹配多台时停止开启语音，不会静默换用其他设备。
修改后关闭数字人再启动。实际输入名称、唤醒模型状态及音量摘要记录在 .local/startup.log，不保存录音。
修改后按 Alt+F4 关闭专用浏览器，再重新启动。新启动的服务随其浏览器退出；复用已有服务时不关闭原服务。
启动后自动开启麦克风监听，不需要先点击画面。首次弹窗请选择“访问该网站时允许”，不要选“仅这次访问时允许”。
同一专用浏览器配置和本地地址通常会记住授权；清除浏览器数据、换浏览器或端口、撤销权限后可能需要重新允许。
浏览器和系统的麦克风权限不因全屏而跳过；开启失败会显示原因，可轻触画面重试。
浏览器独立配置在本包 .local/browser-profile，不改个人浏览器资料。
排错请双击 StartWeb.cmd；日志在本包 .local/startup.log。

1. 登录 https://license.clculture.com
2. 找到设备，点击这一行的“设备配置”。
3. 可分别设置：语音/方舟 Key、识别与合成资源、模型、音色、唤醒词、人设、知识库和对话节奏。
   唤醒词每行一个；知识库支持逐条添加、编辑和移除。
   密钥留空保留已有值，勾选“改用默认密钥”才恢复默认；密钥始终只保存在服务器。
4. 点击“保存并发布配置”。客户端下次启动时生效。

同步方式：
每次新启动联网验证授权，并从启动响应取得本设备配置版本。
版本未变：校验并使用本地缓存，不下载配置正文。
版本改变、首次使用或缓存损坏：下载一次签名配置，校验后原子保存。
下载内容包括唤醒词、人设、知识库、节奏和公开服务参数，不包括 API 密钥。
网站显示“待同步 / 已同步”及配置版本。保存相同配置不会重复升版本。
内容仅在新启动时同步；修改配置不影响授权额度，也不会停掉当前会话。
云接口参数和密钥影响新的云请求，建议发布后重启客户端统一使用新配置。

本地缓存：%USERPROFILE%\.clculture\aiavatar\device-config.json
这是自动缓存，不要手改。授权身份文件在同一目录，请勿删除。
本机断网不能新启动；已有缓存也不能绕过在线授权。

旧本地 wake-config.json、prompt.md、knowledge.md 已迁移到该设备的服务器配置并归档。
以后不用修改这些本地文件。开发源码中保留的同名文件仅用于测试和初始模板。

OSS 版素材由服务器发布，不再直接修改本地 keyword_media/rules.json、idle.mp4 或 talking.mp4。
请勿修改 managed-client.json、tokens.txt、*.onnx、*.pyd 或 web 文件夹。
网站默认云配置、域名、管理员凭据等全局设置仍由服务器 service.env 管理。
设备配置存于服务器 shared/data/license.sqlite3，服务自动读取，不用重启服务器。

形象库：
在网站“形象库”新建分组、填写名称，成对上传 idle / talking 两段 MP4（建议 H.264）。
每段最多 512MB。可改名或成对替换；视频仅允许已登录管理员或被分配该形象的已授权设备访问。
设备配置中选择形象，保存后重启客户端。配置版本变化时拉取清单，只有缺少、更新或损坏的视频才下载。
两段视频都通过 SHA-256 和长度校验后才启用；已下载内容保存在用户目录 .clculture/aiavatar/avatar-cache。
修改人设或知识库不会重复下载形象视频；旧版本文件保留以便复用，缓存不随发布包分发。
卡片分别显示“当前分配形象”和“本机已应用形象”，可判断是否等待重启同步。

设备资料与授权：
卡片显示服务器观察到的出口 IP、IP 估算城市坐标、最近连接、客户端版本、运行环境和备注。
IP 定位不是 GPS；可能显示代理/运营商出口城市。定位失败不会阻止授权启动。
“编辑备注”不改变配置版本、授权或启动额度。
“组合授权”可同时填写有效天数、北京时间截止时间、启动次数，任一限制先到即到期。
启动次数消耗最后一次后，该次启动仍可正常使用（仍受时间限制），之后不能新启动。
组合条件写入签名授权，服务器原子扣减次数并校验到期，修改本地文件或时间不能改写服务器额度。
算力点与调用日志（2026-11-13）
后台：license.clculture.com → 客户与算力点。
先新建客户，在设备卡片分配客户，再人工充值；同一客户下多台设备共享余额。
换算：0.80 元基准成本 = 100 点；100 点售价 1 元。点数保留 6 位小数。
余额不足、客户停用、未分配客户或资源未设置计价时，停止在线接口调用。
本机日志：用户主目录下 .clculture\aiavatar\logs\，包含 calls.sqlite3 和按 UTC 日期分组的 JSONL。
日志包含调用 ID、用量摘要、请求摘要、服务端签名回执和本机签名记录，不含云密钥、原始录音或完整对话。
本地 sent 字段表示发给网关；服务端 forwarded 字段表示实际发给火山。余额拦截时两者可不同。
掉线未收齐的回执在恢复联网、启动或定期检查时补拉；后台“本机已确认”表示当前回执已由设备签名确认。
未拿到完整用量的调用保留预留额度并进入待核对，由管理员按供应商账单核实后结算或释放。



每设备播放与语速（1.0.1 起）：
在授权网站“设备配置 → 形象”选择直接切换 / 淡入淡出，分别设置 idle、talking 速度（0.5～2 倍）。
“对话节奏”设置语音语速（0.5～2 倍，1 为原速）；云接口“试听音色”使用当前填写的语速。
保存发布后重启客户端同步；只修改这些参数不会重新下载未变化的视频。预录视频调速只能改善节奏，不保证逐字对口型。
唤醒词提示只在待唤醒时显示；“拜拜/再见”等结束语先播报“好的，有事再叫我。”再待唤醒。
无活动超时先播报“看您长时间没回复，我先退下了，有事再叫我。”再待唤醒；超时长度在“对话节奏”设置。
固定提示按内容、音色、合成服务和语速缓存；首次生成需要接口可用与相应余额/权限，后续同配置复用。
管理端密钥支持“显示输入”及“查看已保存”；已保存的密钥只在管理员主动查看时返回，30 秒后或关闭窗口时隐藏。

每次回到待唤醒状态，自动清空对话文字、实时字幕和临时提示，只保留顶部唤醒词提示。

1.0.2 起，“设备配置 → 人设 → 角色显示名”决定对话上方的称呼。显示名与人设分别填写，保存发布后重启同步；无需修改本地脚本。

1.0.4 起，音量升高只作活动候选，不再直接清空播放。流式识别确认有效新讲话后才打断，并启发式过滤与播报相似的回声。
安静时也可能有音箱残余回声；现场旁人的讲话仍可能作为输入。重复当前播报的同一句话可能被视为回声，建议用“等一下”或完整新问题插话。
本地 .local/startup.log 只记录中断原因、播放样本数和完成状态，不记录原始录音或对话正文。


语音识别热词与纠正（1.0.4 起）：
授权网站 → 设备管理 → 设备配置 → 识别热词。
填写品牌、人名、药材等少量专有名词，每行一个；也可从知识库标题生成候选，人工筛选后保存。
识别场景填一段简短说明即可，不要粘贴整个知识库。热词会优先引导识别，但不能保证 100% 正确。
纠错格式：干平常 => 甘平堂 | 你们, 药铺
竖线后是可选的语境，只在原句含其中任一词时替换；省略语境则命中即替换。
不要把“干品”等普通词设为药铺名，也不要按相似度强行替换药名。
纠正只执行一次，不会连锁替换；无额外大模型调用。原始和纠正文本都会经过回声判断。
保存发布后重启客户端：版本有变化才下载，未变化复用签名配置与素材缓存。
服务器注入热词兼容旧客户端；本地纠错和纠正后的字幕需 1.0.4 及以后版本。


1.0.5 授权码与启动提醒：
管理员先在网站“设备管理 → 新建设备”创建卡片并设置授权、客户和配置，复制授权码交给客户。
首次运行需要联网输入授权码；机器序列号自动获取。取消退出，校验失败保持窗口；授权通过后才启动。
后续每次启动在线检查，不用重复输入。次数少于 10 次、有效期不超过 5 天时提醒 5 秒后淡出。
归档设备保留数据并停止使用，可在“已归档”中恢复。详情见“授权码与设备归档说明.md”。
