把聊天框搬到桌面上：
here 项目实战

01 / THE PRODUCT QUESTION

重点不是“会聊天”，
而是“会在这里”

许多 AI 桌面应用的实际形态，仍然是一扇换了皮的聊天窗口：用户打开它，输入问题，得到回答，然后关闭。here 选择了另一条路线。它让角色有长期记忆、可视立绘、语音、日常生活状态，以及在合适时机主动联系用户的能力。

这个产品目标直接决定了工程形态。一次请求只需要模型调用；一个“常驻角色”还需要保存状态、排程、消息送达、角色素材和失败兜底。项目把 Hermes Agent 与内置 Internal Agent 放在统一后端边界内，同时把语音、ASR、生图、外部渠道做成独立服务，而不是把所有能力绑进聊天主流程。

项目实战的第一步不是接 API，而是先定义：什么状态要跨越一次对话，被安全地保存下来，并在下次重新参与体验？

02 / MINIMUM VIABLE RUN

先让桌面角色跑起来，
再逐项打开能力

源码运行统一交给 uv 管理。macOS 或 Linux 上，克隆项目后直接执行下面两条命令即可完成基础安装与启动。Windows 对应使用仓库内的 install.bat 和 start.bat，并建议把项目放到纯英文路径，避开音频、Qt 和嵌入式 Python 的路径兼容问题。

bash scripts/install.sh
bash scripts/start.sh

我建议不要一开始就执行 --full。基础体验成立后，再根据需求补齐对应的原生扩展：--with-asr 增加完整语音识别路径，--with-video 支持从视频抽帧制作角色动画，--with-background-removal 解决透明立绘，--with-hermes 才会将 Hermes Agent 装入当前环境。

想先验证什么

建议只启用什么

桌面角色 + 文本对话

基础安装，配置一个 Agent 后端

语音陪伴

按需安装 ASR，并在界面中选定 TTS / ASR

动态角色立绘

导入图片帧；仅视频素材时加 --with-video

主动状态照片

配置自拍生图服务与角色视觉身份

运行数据默认不会散落进源码目录：开发环境保存在项目下的 .local/here，打包应用则使用系统应用数据目录。需要隔离测试时，可用 HERE_APP_HOME 指到新的数据目录；这比把测试角色和真实对话混在一起可靠得多。

03 / ARCHITECTURE THAT CAN GROW

把“角色体验”拆成
可替换的边界

here 的目录划分值得直接借鉴。app/ 只负责桌面应用装配和入口；core/ 容纳运行时、消息处理、主动联系、投递与后端桥接；services/ 对接 ASR、TTS、生图、配置和国际化；ui/ 只处理 Qt 桌面界面。文件路径、日志与存储等平台问题则收在 infrastructure/。

层

在这里承担的职责

internal_agent/

内置 Agent 的记忆、会话与推理行为

core/agent/

Internal Agent、Hermes 等后端的适配桥

core/proactive/

计划生成与主动联系调度

core/delivery/

桌面与外部渠道的投递路由

services/t2i/

不同图像 API 的统一适配接口

这里最关键的取舍是：具体 Agent 留在 internal_agent/，而 core/agent/ 只做桥接。 这样未来增加新的模型后端时，只需添加一个适配器，不必让 UI、排程和记忆系统知道某家模型 SDK 的细节。对会持续加能力的桌面应用来说，这是避免“入口文件不断膨胀”的实际做法。

04 / FROM CHAT TO COMPANION

角色档案、日常状态、
主动联系，缺一不可

完成启动后，第一件值得做的不是调提示词，而是建立角色档案。here 的角色配置把身份、性格、说话方式、关系阶段、喜好、边界和情绪标签与立绘关联在一起。模型输出的文本并不直接决定屏幕上的一切，它还会经过情绪与立绘状态的解析，最终驱动对话 UI。

1. 先建立稳定身份明确角色如何称呼用户、说话长度、关系边界与情绪倾向，让首次对话就有一致语气。
2. 再接上记忆与日常状态跨会话要保留的内容进入记忆；一天内会变化的状态交给 life 与 proactive 调度模块。
3. 最后启用主动触达主动消息不是定时群发。它应依据角色状态形成计划，再通过桌面或外部渠道送达。

这条链路解释了为什么“主动联系”必须是独立模块：调度器负责什么时候值得联系，计划引擎负责联系什么，投递路由负责从哪个渠道送达。把这三件事全部塞进模型 prompt，会让行为不可预测，也无法测试。

05 / DELIVERY, SAFETY, AND LIMITS

让能力可配，
也让风险可控

图像能力在 here 中是主动联系的附件，而不是驱动排程的开关。角色可依据视觉身份、当前日常状态和可选参考图生成状态照片；底层可切换 image-api、Grok Imagine、GPT Image 及 OpenAI-compatible endpoint。适配器可换，主动联系的上层逻辑无需随服务商改变。

落地时有两条底线值得坚持：API Key 可以通过 UI 或环境变量提供，但本地配置不应提交进 Git；外部送达需要额外配置，也应该先在独立测试数据目录验证。项目使用 PolyForm Noncommercial 1.0.0 许可，未经单独书面授权不能商用，复用前要先确认你的使用场景。