YZOS 产品规格

本文档是 YZOS 产品的唯一真源。专题文档负责展开细节，如有冲突以本文为准。

平台：macOS 13 及以上（首期发布）许可：MIT，开源

1. YZOS 是什么

YZOS 是一套完全运行在你 Mac 本机的观察引擎、知识结晶层和 AI 数据供料站。它被动观察你在软件、AI 工具、聊天、语音和屏幕中的工作痕迹，在本地把这些信号归纳为人、项目、任务、知识和事件，再通过 MCP、Skill、CLI 把这些上下文供给 Claude Code、Codex、Cursor 等上层 AI 工具。

YZOS 不是聊天产品。它不要求你在 YZOS 里工作，也不替你执行任务。

2. YZOS 的承诺

零负担观察：继续使用你原本的软件，YZOS 在后台被动观察。
结构优先的行为识别：先读取 UI 结构，再按区域做 OCR 和视觉理解。
自动实体档案：人物、项目、任务自动发现，并持续更新到 OKF。
本地优先隐私：原始数据默认不出机，外部模型只会看到脱敏文本。
可带走的真源：OKF Markdown 是真源，PostgreSQL 只是索引。
供给上层 AI：Claude Code、Codex 通过 MCP 查询真实的本地数据。
可审查可修正：Tauri UI 让你查看观察结果、实体候选和维护日志。

3. YZOS 不做什么

不做内置聊天机器人：对话发生在你的上层 AI 工具里，不在 YZOS 里。
不做自动代办执行器：YZOS 不会替你发消息、填表单、跑 CI、提交 PR。
不做远程云服务：同步（如果使用）依赖你自己的 iCloud、WebDAV、SSH、S3 或 Git。
不是纯截图 OCR 工具：截图和视频只是证据层，不是行为识别的主路径。
不是通用桌面 RPA：观察和供料是目标，自动操控你的桌面不是。

4. 运行时架构

flowchart TD
  LA["LaunchAgent: com.yzos.autostart"] -->|"open -g at login"| APP["/Applications/YZOS.app"]
  APP --> DESK["yzos-desktop (com.yzos.desktop)"]
  DESK --> RT["yzos-runtime"]
  DESK --> PG[("PostgreSQL (embedded)")]
  DESK --> HTTP["HTTP 127.0.0.1:17432"]
  RT --> PRE
  subgraph PIPE["Data plane (single process)"]
    direction LR
    PRE["Preflight"] --> OBS["Observe"] --> CRY["Crystallize"] --> IDX["Index"] --> SUP["Supply"] --> MNT["Maintain"]
  end
  subgraph EP["HTTP endpoints"]
    S["/status"]
    P["/permissions"]
    A["/api/call"]
    M["/mcp"]
  end
  HTTP --> EP

唯一 app：/Applications/YZOS.app
Bundle id：com.yzos.desktop
运行体：src-tauri 链接 yzos-runtime
数据面：Observe、Crystallize、Index、Supply、Maintain 全部跑在同一进程
自启动：com.yzos.autostart 只负责在登录时打开 app
MCP：HTTP transport，路径 /mcp
CLI：yzos 是对同一进程的 HTTP client

5. 核心流水线

flowchart LR
  Preflight --> Observe --> Crystallize --> Index --> Supply --> Maintain

Preflight：校验安装、加载模型、对默认能力做 smoke test（无逐项开关，失败会优雅降级而不阻塞 Observe）
Observe：被动采集 app、窗口、UI 结构、AI 工具会话、聊天、剪贴板、屏幕、语音信号
Crystallize：会话结束后做证据 triage、抽取实体信号、写入知识
Index：OKF、PostgreSQL 全文搜索、pgvector 的混合索引
Supply：MCP、Skill、CLI 返回真实观察数据
Maintain：定时 rollup、实体一致性核对、归档、重建索引

Preflight 未通过前，Observe 和 Crystallize 不会启动。

6. 观察策略

YZOS 理解桌面采用结构优先的链路：

flowchart TD
  AW["Active app / window"] --> META["App metadata"]
  META --> AX["AX tree / DOM / app adapter"]
  AX --> REG["UI layout regions"]
  REG --> OCR["ROI OCR"]
  OCR --> VLM["VLM semantic labels"]
  VLM --> DIFF["Temporal diff"]
  DIFF --> EVT["Behavior event"]

App / Window：bundle id、PID、title、bounds、URL、repo path，用来判断当前工作上下文
UI Structure：AX 节点、DOM 节点、聚焦元素、选区、role/value，直接从可访问结构读取
Layout Regions：editor、terminal、sidebar、toolbar、input、chat、canvas、modal，为 OCR 和行为推断划分区域
ROI OCR：bbox、置信度、阅读顺序、段落，补齐 AX/DOM 读不到的文字
VLM：屏幕语义、视觉区域标签，补齐 Figma、图片、视频、canvas 内容的含义
Temporal Diff：前后 UI 快照的状态差异，识别编辑、搜索、发送、跑命令、切换文件

OCR 是补洞层，不是第一层。VLM 是低频语义补充，不是行为判断的最终裁决者。

7. 主要观察源

桌面活动：app 切换、窗口聚焦、屏幕分段、UI 状态
AI 工具：Claude Code、Codex、Cursor、Continue、Aider 等编码 agent 会话
剪贴板：文本历史，带脱敏和搜索
聊天软件：发送人、消息、会话线程、实体信号
语音：语音活动检测、ASR、说话人计数、声纹
OKF：memory、knowledge、entities

8. 行为事件

行为事件来自 UI 状态差异，并融合多源证据。

read：活动窗口稳定、滚动、无编辑差异
edit：编辑区域文本变化、选区、文件路径
run_command：终端提示符加命令加输出差异
send_message：聊天输入框清空、消息列表新增
copy：剪贴板事件加聚焦区域
paste：剪贴板事件后目标区域内容变化
select_file：文件树选择或标签页差异
switch_context：app/窗口/URL/repo 切换
design_adjust：画布区域变化加 Figma/app adapter 信号
review：diff 查看器、评论面板、PR URL、选区

9. 实体与知识

产物	真源	索引
Person	OKF entity 文件	PostgreSQL entities / sightings / links
Project	OKF entity 文件	PostgreSQL entities / repo path / AI sessions
Task	OKF entity 文件	PostgreSQL entities / status / 关联事件
Knowledge	OKF Markdown	PostgreSQL chunks + 全文搜索 + pgvector
Memory	OKF Markdown	PostgreSQL chunks + 全文搜索 + pgvector
Activity	PostgreSQL 事件表	PostgreSQL 时间序列索引

PostgreSQL 索引损坏时，从 OKF 核对重建。原始活动数据按可配置的保留策略留存。

10. 供料接口

HTTP MCP /mcp：Claude Code、Codex 等 MCP 客户端直接查询
/api/call：本机 HTTP API
CLI yzos：终端和脚本查询
Skill yzos-data：agent 触发的查询规则
Tauri UI：预览、设置、权限、实体审查

供料接口不编造数据。查询活动、实体、知识或剪贴板历史，一律基于 MCP、HTTP API 或 CLI 返回的真实本地数据。

11. 技术栈

组件	选型
App host	Tauri 2 + React
Runtime	Rust `yzos-runtime`
Core domain	Rust `yzos-core`
数据库	内嵌 PostgreSQL + pgvector
MCP	HTTP transport，路径 `/mcp`
LLM	llama.cpp / llama-server sidecar
OCR	macOS Vision framework
UI 结构	macOS Accessibility API、CGWindowList、浏览器/app adapter
屏幕采集	ScreenCaptureKit + mp4 分段
音频	sherpa-onnx
Embedding	multilingual-e5-small