Openeye

OpenEye

Alpha 软件。 接口可能会变更。请在 github.com/dumbspacecookie/openeye 提交问题。

每家 AR 头显厂商——HoloLens、Snap Spectacles、Apple、Android——都推出了能看见东西的设备，却没有一家提供大脑。每位在这些平台上开发的开发者都必须每次从头摸索智能层，而且要为每台设备重新摸索。这些工作无法积累。一支团队在 HoloLens 上学到的东西，对构建 WebXR 的团队毫无帮助。每次部署都是一座孤岛。

OpenEye 是共享的大脑。

设备上运行着一小段软件，负责捕获摄像头所见内容，并将其转化为场景的自然语言描述。描述会发送给 OpenEye。OpenEye 运行一个 AI Agent，配备验证流程步骤、回忆先前会话以及记录所学内容的工具。每次会话都会成为结构化记忆，供 Agent 日后搜索；同时还会生成可导出的训练轨迹，可用于微调。

OpenEye 不附带视觉模型——由你自备。可接入 Claude vision、GPT-4o、Gemini、Groq Llama vision，或运行 moondream/llava 的本地 Ollama 模型。examples/vision-adapter/ 中提供了适用于云端和本地模型的可用参考适配器。

---

安装

npm install @dumbspacecookie/openeye
pip install -r node_modules/@dumbspacecookie/openeye/sidecar/requirements.txt

Python sidecar（FastAPI + SQLite）负责处理状态，并会在你创建 Agent 时自动启动——无需手动启动。

想在本地修改代码？也可以克隆：

git clone https://github.com/dumbspacecookie/openeye.git
cd openeye && npm install && npm run build
pip install -r sidecar/requirements.txt

---

快速开始

import { OpenEyeAgent, setupProviders, makeStreamFn, ANTHROPIC_SONNET } from "@dumbspacecookie/openeye";
import { describeFrameWithClaude } from "./examples/vision-adapter/claude-vision-adapter.js";
import * as fs from "node:fs";

setupProviders();

const agent = await OpenEyeAgent.create({
  model: ANTHROPIC_SONNET,
  streamFn: makeStreamFn(),
  systemPrompt: "You are a procedure assistant. Verify steps with precision.",
  tenantId: "your-org",
});

const vsId = await agent.client.createVisualSession({
  deviceType: "android-tablet",
  procedureId: "bolt-assembly-v1",
  procedureName: "M6 Bolt Assembly",
});

// 1. vision adapter (you bring this) turns a camera frame into text
const frameBytes = fs.readFileSync("./frame.jpg");
const description = await describeFrameWithClaude(
  frameBytes,
  "Operator is installing an M6 bolt. Describe hand position, tool, and bolt state.",
);

// 2. OpenEye logs the description and lets the agent verify the step
const frameId = await agent.client.logFrame({
  visualSessionId: vsId!,
  sequenceNum: 1,
  sceneDescription: description,
  stepContext: "step-1-position-bracket",
});

await agent.prompt(`Frame 1: ${description}\nVerify step-1-position-bracket.`);

await agent.client.endVisualSession(vsId!, "completed");
await agent.captureAndClose({ completed: true, visualSessionId: vsId! });

没有可用于 Agent 的 API 密钥？使用 Ollama 在本地运行：

ollama pull llama3.3

import { ollamaModel } from "@dumbspacecookie/openeye";
const agent = await OpenEyeAgent.create({ model: ollamaModel("llama3.3"), streamFn: makeStreamFn() });

---

它能为你提供什么

能力	OpenEye
Agent 运行时 + 工具调用	是
持久化会话记忆（FTS5）	是
视觉帧记录 + 搜索	是
步骤验证，结果包括通过/失败/不确定	是
训练数据导出（ShareGPT JSONL）	是
DPO 偏好对导出	是
推送到 HuggingFace 数据集	是
MCP 服务（Claude Desktop、Cursor）	是
参考视觉适配器（Claude + Ollama）	是
视觉模型	否——由你自备
托管云服务	否——请自备数据接入端点（契约）

它的价值在于这个循环：会话针对实际流程步骤生成通过/失败结果，这些结果成为奖励信号，而完整对话会打包成 ShareGPT 轨迹，可用于 TRL、LLaMA-Factory 或 Axolotl 中的 DPO 训练。你负责提供微调流水线，OpenEye 负责提供数据。

---

工作原理

当设备传来一帧画面时，视觉适配器会用通俗语言描述画面。描述随后会发送给 AI Agent。Agent 可以使用一组工具：

工具	功能
search_memory	使用 FTS5 搜索所有过往 Agent 会话
search_frames	使用 FTS5 搜索所有过往帧描述
recall_skill	检索与当前任务相关的操作技能
write_skill	完成复杂任务后保存新的技能文档
start_visual_session	开始一个可跟踪的 AR/XR 会话
end_visual_session	结束视觉会话
log_frame	记录一帧的场景描述
verify_step	记录步骤结果 — 通过 / 失败 / 不确定

步骤验证会成为奖励信号：reward = (passes + 0.5 × uncertain) / total。会话结束时，整个对话会打包成 ShareGPT 轨迹，可用于任何兼容 DPO 的训练器。

重要提示：奖励信号反映的是 Agent 根据场景描述作出的判断，而非外部真实依据。要将其用作真实的 RL 数据，应定期使用人工标注的子集验证轨迹，或将其作为监督数据使用，而不要将其视为客观事实。仅基于这一原始信号进行微调，有可能训练出自信地给出错误答案的模型。

---

使用场景

主要使用场景（可用于生产）：

制造与装配 — 螺栓安装验证、设备操作前检查、装配顺序合规性检查、生产线工位视觉质检。可使用 Android 平板电脑，或在作业区域上方显示 AR 叠加信息。监管负担较低，且有 B2B 采购需求。

培训与入职指导 — 适用于任何需要有人从旁协助并记住所有见闻的培训流程。学徒技工、新入职的生产线操作员、实验室技术人员。培训中的失误代价不高，因此这是风险最低的首批部署场景。

现场服务与检查 — 上锁挂牌合规性检查、PPE 验证、作业前安全检查清单、设备检查。技术人员通常已随身携带手机。skills/field-service/ 中提供了一个 LOTO 技能文件示例。

暂不建议：

医疗 / 手术 — 技术环节可行，但任何会影响手术决策的内容都需接受 FDA 510(k)/De Novo 审查。skills/medical/ 中的示例技能只是由工程师编写的说明性起点，并非经过验证的临床规程。未经独立的医疗和监管审查，请勿将其用作合规基准。

---

训练数据与 HuggingFace

// export training trajectories
const count = await agent.exportTrajectories("./trajectories.jsonl");

// export DPO preference pairs (TRL/Axolotl-compatible)
const pairs = await agent.exportDPOPairs("./dpo_pairs.jsonl");

// push directly to HuggingFace
const result = await agent.pushToHub("myuser/my-procedure-runs", {
  tags: ["procedure-verification", "bolt-assembly"],
});
console.log(`published ${result.pushed} trajectories to ${result.url}`);

---

MCP 服务

通过 Claude Desktop、Cursor、Windsurf 或任何兼容 MCP 的客户端使用 OpenEye 的工具：

{
  "mcpServers": {
    "openeye": {
      "command": "python3",
      "args": ["sidecar/mcp_server.py"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

所有 8 个工具均可立即使用。

---

支持的 Agent 模型

只需一行即可切换，无需更改其他代码：

提供商	环境变量
Anthropic（Claude Opus、Sonnet、Haiku）	ANTHROPIC_API_KEY
Groq（Llama 3.3 — 速度最快，免费套餐）	GROQ_API_KEY
Ollama（本地运行，无需密钥，无费用）	只需运行 ollama pull llama3.3
OpenAI、Google、Mistral、Bedrock、OpenRouter	参见 src/models.ts
任何兼容 OpenAI 的端点	将 baseUrl + apiKey 传给 customModel()

---

数据与隐私

只有当你的视觉适配器在设备端运行时，原始帧像素才不会离开设备。examples/vision-adapter/ 中的 Ollama 适配器会将像素保留在本地；Claude/OpenAI/Gemini 云端适配器则不会。请根据你的部署方式选择合适的适配器。

OpenEye 自身存储的是视觉适配器所见内容的自然语言描述，而不是图像。云端同步默认关闭，可按数据类型配置。每条记录都限定在一个租户 ID 下，因此单个部署可以为多个组织提供服务，并确保组织之间的数据完全隔离。

想要启用云端同步？OpenEye 不运行托管后端——接收端点由你负责运行。HTTP 合约、重试语义、幂等性要求和行架构请参阅 docs/cloud-sync.md。

将数据分享回 Context（明确选择加入）

OpenEye 由 Context 构建。为了随着时间推移改进流程验证模型，OpenEye 可以将选择加入的轨迹数据——包含奖励信号的已完成会话——发送给 Context 用于训练。此功能默认关闭。 在你设置以下内容之前，不会有任何数据离开你的设备：

export OPENEYE_CONTEXT_OPTIN=true
export OPENEYE_CONTEXT_API_KEY=ctx-...

将发送的内容：轨迹 ID、所用模型、奖励信号、流程标签，以及 Agent 对话（已移除系统提示词）。绝不会发送的内容：租户 ID、用户 ID、系统提示词、视觉会话 ID、技能文件或任何原始帧描述。

完整披露信息（包括欧盟/GDPR 说明和撤销流程）： docs/context-data.md。

随时查看状态：

curl http://127.0.0.1:7770/context/status

---

部署

本地（默认——边车会作为子进程自动启动）：

git clone https://github.com/dumbspacecookie/openeye.git
cd openeye && npm install && npm run build
pip install -r sidecar/requirements.txt

Docker：

docker run -d -p 7770:7770 -v openeye-data:/data \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  --name openeye openeye/sidecar

---

配置

环境变量	默认值	说明
OPENEYE_HOME	~/.openeye	数据目录（SQLite 数据库 + 技能 + 同意标记）
OPENEYE_PORT	7770	边车 HTTP 端口
OPENEYE_BIND_HOST	127.0.0.1	边车绑定地址（除非你已阅读 docs/security.md，否则不要更改）
OPENEYE_SIDECAR_TOKEN	—	边车 HTTP 身份验证的可选共享密钥——共享主机上必需
OPENEYE_PYTHON	python3	Python 可执行文件
OPENEYE_WORKERS	1	uvicorn 工作进程数——除非已迁出 SQLite，否则保持为 1
OPENEYE_LOG_LEVEL	INFO	边车日志级别
OPENEYE_CLOUD_URL	—	用于选择加入同步的云端端点（cloud-sync.md）
OPENEYE_CLOUD_KEY	—	云端同步的 bearer 令牌
OPENEYE_SYNC_INTERVAL	60	云端同步间隔（秒）
OPENEYE_SYNC_MAX_RETRIES	4	发生暂时性故障时每批次的重试次数
OPENEYE_CONTEXT_OPTIN	—	设置为 true 以启用 Context 训练数据分享（context-data.md）
OPENEYE_CONTEXT_API_KEY	—	你的 Context API 密钥
OPENEYE_CONTEXT_CONSENT_CONFIRMED	—	设置为 true（仅限 CI）以跳过同意确认提示
OPENEYE_CONTEXT_SYNC_INTERVAL	300	Context 同步间隔（秒）
OLLAMA_BASE_URL	http://localhost:11434	用于本地视觉/Agent 的 Ollama 端点

---

测试

# Python sidecar tests (56 passing)
python -m pytest tests/ -v

# TypeScript integration tests
npm test

# TypeScript typecheck
npm run typecheck

# Validate community skills
python sidecar/validate_skill.py skills/

---

项目结构

openeye/
├── src/                  # TypeScript source (agent, client, models, tools)
├── sidecar/              # Python backend (FastAPI server, SQLite state, skills)
├── skills/               # Example skill protocols (manufacturing, field-service, medical*)
├── examples/             # Reference adapters and end-to-end demos
│   └── vision-adapter/   # Claude + Ollama vision adapters
├── eval/                 # Evaluation benchmark
├── docs/                 # Operator docs (cloud-sync contract, etc.)
├── schemas/              # JSON Schema for skill front matter
├── tests/                # Python + TypeScript tests
├── dist/                 # Compiled TypeScript output
├── package.json
├── tsconfig.json
└── Dockerfile

*医疗技能仅为工程示例，不是经过验证的临床规程。请参阅上文的“用例”。

---

许可证

MIT — 基于 pi-mono（MIT）和 hermes-agent（MIT）构建。

---

— dumbspacecookie