视频流不是 Agent 的记忆：用 ReflectWorld 把片段、实体与证据链留在本地
摄像头、屏幕录制和机器人视频正在变成 Agent 的新输入，但“能看一帧图”与“记得连续发生过什么”是两件不同的事。前者可以把当前画面送进视觉模型；后者要求系统知道事件发生的时间、重复出现的对象、语音上下文以及原始证据在哪里。若只把视频切成若干截图再让模型总结，下一次提问时通常只能得到一段脱离来源的文字，既难复查，也难判断它是否把两个相似场景混为一谈。
ReflectWorld 是一个 Apache-2.0 许可的本地优先视觉记忆运行时。它的定位不是“万能监控 Agent”，而是把摄像头流或视频文件转换成有时间锚点的观察记录，再向仪表盘和 Agent 工具暴露可检索的记忆。这个定位很重要：它试图解决的是视觉上下文的持久化与证据关联，而不是替代人工判断，更不是给模型一份可以无限保存、绝对正确的“第二大脑”。
先把视频处理拆成证据链
从公开架构看，ReflectWorld 的路径可以概括为：输入源进入 @reflectworld/cam，采集帧、音频和时间戳；分段器依据时间、运动和语音线索把流切成 moments；@reflectworld/percept 做视觉分析；随后由内存适配层写入记忆服务和 Qdrant 向量存储。仪表盘展示源、片段、实体、记忆和聊天状态，Agent 则从已写入的记忆中召回答案。
这种拆分带来两个工程收益。第一，查询结果可以回到片段、时间戳、帧、语音或记忆记录，而不是只保留“模型曾经说过什么”。第二，实体不是在某一次描述中被永久定性：系统把本地检测与再识别（ReID）当作证据，视觉模型给出人类可读描述，运行时在置信度足够时才把它们汇总为稳定的实体状态。对于办公室、实验室或设备巡检这类长时间场景，这比把每一帧独立问答更接近可维护的系统边界。
不过，证据链并不会自动保证事实正确。镜头遮挡、相似外观、光照变化和语音识别错误都可能让错误观察进入记忆；后续 Agent 若只检索文字摘要，可能进一步放大错误。因此，涉及告警、门禁、合规或生产操作时，应把回答中的片段链接、时间范围和原始媒体作为人工复核入口，而不是把聊天结果直接连接到执行动作。
最小启动：先跑通云端视觉模型路径
当前 Quick Start 要求 Node.js 22 或更高版本，以及来自 OpenAI 兼容服务或 Gemini 的视觉 API 凭据；README 标明 macOS 与 Linux 是支持平台。最短路径是创建 .env，再用 npm 包启动同一进程中的 Dashboard：
VLM_PROVIDER=openai
VLM_MODEL=gpt-5-mini
VLM_MODEL_LITE=gpt-5-mini
VLM_API_KEY="${VLM_API_KEY}"
VLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-5-mini
EMBEDDER_PROVIDER=openai
EMBEDDER_MODEL=text-embedding-3-small
EMBEDDER_API_KEY="${EMBEDDER_API_KEY}"
EMBEDDER_BASE_URL=https://api.openai.com/v1
EMBEDDING_DIMS=1536
npx @reflectworld/reflectworld start
服务默认将 Dashboard 暴露在 http://localhost:3210。在页面中添加输入源、上传视频或连接流之后，才会逐步看到片段、实体、记忆与聊天数据。首次运行有一个容易误判的失败模式：Dashboard 可能先启动，后台依赖仍在初始化，记忆功能会暂时显示为 starting。这时不应把空结果当作“视频没有内容”，应先等待后端就绪并检查模型配置和网络访问。
这里也要明确数据边界。“本地优先”指源文件、非 VLM 识别模型、媒体、身份相关证据和记忆默认保留在运行机器；它不等于“任何数据都绝不离开机器”。一旦配置远程 VLM、嵌入、语音转文字或聊天服务，项目文档说明相应请求负载可能包含帧、提示词或聊天文本、嵌入文本和语音窗口音频。部署前应按数据类型逐项确认供应商、区域、保留策略和访问权限。
Level 1 不是一个可以忽略许可证的开关
默认的 Level 0 走 VLM 分析；启用本地感知 Level 1 后，会在视觉推理前加入本地检测和 ReID 证据。官方提供的安装路径如下：
npx @reflectworld/reflectworld enable-level1 npx @reflectworld/reflectworld setup --level 1 --yes --accept-model-licenses
setup 会在本机获取或转换所需 ONNX 模型，而不会由 ReflectWorld 重新分发权重。但“在本机下载”不等于可以任意商用：文档列出的默认组合中，YOLO26m 权重涉及 AGPL-3.0，WIDER FACE 的 RetinaFace 权重为非商业用途，InsightFace 的 ArcFace 包也带非商业限制；Moonshine Tiny 则是 MIT。若项目要进入商业场景，应该先逐个审阅 THIRD_PARTY_NOTICES.md，并替换成与业务许可相符的模型，而不是把仓库自身的 Apache-2.0 许可证误读为全部模型和数据的许可证。
这也是视觉 Agent 与普通文本工具最大的不同之一：代码许可、模型权重许可、采集画面的授权和生物特征法规是四个独立问题。项目文档特别提示，当开启本地人脸再识别时可能处理人脸嵌入等生物特征信号；GDPR、CCPA、BIPA 等适用性、告知同意、删除请求和访问审计，都需要部署方自行负责。
让“记住”有上限，而不是一直积累
长期运行时，真正的成本不只来自模型调用。视频片段、生成媒体、本地 SQLite 状态和 Qdrant 向量都会增长；默认采集参数、每路源的并发、队列长度、录制配额和保存期限都应在试点阶段测量。官方配置参考中，摄像头默认片段长度为 30 秒、默认帧提取频率为每秒 1 帧、单摄像头录制配额为 2048 MB；这些是默认值而非对每个场景的推荐值。走廊中的稀疏事件、持续设备读数和高频人流，显然需要不同的分段与留存策略。
一个可复核的试点验收表
不要一开始就让 Agent 根据视觉记忆自动触发工单、门锁或生产控制。先选一段已知答案的脱敏录像，例如“某台设备在什么时候由待机变为运行”，用人工标注的时间范围做基准。每次测试记录提问、系统返回的片段时间、证据帧、实体关联和人工结论；若答案正确但无法定位到片段，也应视为没有通过可审计性验收。
可以把第一阶段收敛为四个问题：召回是否正确、证据是否可达、错误是否可纠正、成本是否可预测。 召回要检查相似物体或连续事件是否被错连；证据要检查操作者能否打开对应时段的原始或派生媒体；纠错要检查误判记录被删除或更正后，后续检索是否还会返回旧结论；成本则至少记录每小时片段数、远程模型请求数、磁盘增长和向量库体积。只有这四项都拿到本地测量值，再讨论扩大摄像头数量或接入实时 Agent。
这套验收也能避免一个常见误区：向量检索分数高，只表示当前嵌入空间中的文本或视觉表示相近，不代表事件身份已经被证明。对于人员、设备状态或安全事件，应该把“找到相似记录”与“确认同一对象、同一时间线”分成两个步骤。前者可以由系统协助，后者仍应保留给有权限的操作者复核。
一个更稳妥的落地顺序是：先用脱敏的历史录像验证“提问能否回到正确时间片”；再确认错认、漏检、延迟和存储增长；最后才接入实时流和 Agent 工具。对于敏感区域，至少把采集范围、原视频保留期、派生摘要保留期、谁能检索实体、谁能导出证据写成可执行规则。记忆服务能删除数据，并不意味着团队已经定义好了何时删除、由谁批准删除。
ReflectWorld 适合用来试验“视觉输入如何成为可追溯上下文”：它把捕获、分段、感知、记忆和召回明确拆开，也把本地数据与可选远程模型请求的边界写在配置层。它暂不适合作为无人值守的判断终点。把每条高风险结论保留为可回看片段的假设，把模型输出放在审批和复核之前，视觉记忆才会成为 Agent 的上下文基础设施，而不是新的黑箱。