YZOS 系统架构

完整规格见 00-product-spec.md。

1. 总览

flowchart TD
  App["/Applications/YZOS.app"] --> Desktop["yzos-desktop"]
  Desktop --> Runtime["yzos-runtime"]
  Desktop --> PG[("PostgreSQL embedded")]
  Desktop --> Sidecars["sidecars"]
  Desktop --> HTTP["HTTP 127.0.0.1:17432"]
  Runtime --> Preflight["Preflight"]
  Runtime --> Observe["Observe"]
  Runtime --> Crystallize["Crystallize"]
  Runtime --> Index["Index"]
  Runtime --> Supply["Supply"]
  Runtime --> Maintain["Maintain"]
  Sidecars --> LLM["yzos-llm"]
  Sidecars --> FFMPEG["ffmpeg"]
  HTTP --> Status["/status"]
  HTTP --> Perms["/permissions"]
  HTTP --> ApiCall["/api/call"]
  HTTP --> Mcp["/mcp"]

YZOS 是单 bundle、单运行时架构。yzos-desktop 是 Tauri host，它链接 yzos-runtime，由后者承担观察、结晶、索引、供料和维护。你退出 YZOS.app 后，运行时和 MCP 端点都会下线。

2. 进程与组件

组件	形态	责任
yzos-desktop	Tauri app binary	app host、菜单栏图标、前端窗口、权限弹窗
yzos-runtime	Rust 库	HTTP、MCP、observe loop、crystallize loop、maintenance
yzos-core	Rust 库	领域逻辑、实体、OKF、Preflight、推理调度、平台能力
PostgreSQL	内嵌子进程	activity、entities、jobs 的索引
yzos-llm	sidecar	llama-server 文本和 VLM 请求
ffmpeg	sidecar	屏幕分段抽帧、视频处理
yzos-cli	binary	HTTP client
yzos-mcp	adapter binary	兼容 stdio MCP client，主路径仍是 HTTP MCP

3. 启动生命周期

flowchart TD
  Launch["App Launch"] --> Config["load config"]
  Config --> Logs["init logs"]
  Logs --> PG["start embedded PostgreSQL"]
  PG --> Migrate["run migrations"]
  Migrate --> HTTP["start HTTP"]
  HTTP --> Preflight["Preflight"]
  Preflight --> Ready["Ready"]
  Ready --> Observe["Observe"]

状态	含义
booting	app 进程启动中，PostgreSQL 和 HTTP 初始化中
preflight	校验权限、模型、sidecar、平台能力
ready	默认能力的 Preflight 已通过，可以开始观察
observing	observe / crystallize / maintain 正常运行
degraded	某个默认能力的 Preflight 失败（该能力降级，但不阻塞 Observe）
suspended	休眠或关键依赖不可用，恢复后重跑 Preflight

4. Observe 数据流

flowchart TD
  Events["macOS platform events"] --> AppTracker["app/window tracker"]
  Events --> UIState["UI state engine"]
  Events --> Recorder["screen segment recorder"]
  Events --> Importer["AI tool importer"]
  Events --> Clipboard["clipboard watcher"]
  Events --> ChatAudio["chat/audio watchers"]
  AppTracker --> Builder["activity session builder"]
  UIState --> Builder
  Recorder --> Builder
  Importer --> Builder
  Clipboard --> Builder
  ChatAudio --> Builder

Observe 只采集事实，不直接产出长期总结。高频数据写入 PostgreSQL，原始文件写入 paths.observations。

5. UI State Engine

准确的行为识别依赖 UI State Engine。

flowchart TD
  Active["active app/window"] --> Metadata["metadata"]
  Metadata --> Structure["structure sources"]
  Structure --> Regions["layout regions"]
  Regions --> OCR["ROI OCR"]
  OCR --> VLM["VLM labels"]
  VLM --> Diff["temporal diff"]
  Diff --> Event["behavior event"]
  Metadata -.- Mdetail["bundle id / pid / title / bounds / url / repo / document path"]
  Structure -.- S1["AX tree"]
  Structure -.- S2["DOM / browser adapter"]
  Structure -.- S3["app-specific adapter"]
  Regions -.- Rdetail["editor / terminal / sidebar / toolbar / input / chat / canvas / modal"]

5.1 结构源优先级

优先级	来源	示例
1	App adapter	Claude Code jsonl、Cursor workspace、Figma API、browser CDP
2	AX tree	role、label、value、聚焦元素、选区、bounds
3	DOM / accessibility tree	web app、浏览器标签页、URL、选中节点
4	ROI OCR	AX/DOM 读不到的文本区域
5	VLM	canvas、图片、视频、设计稿、无 OCR 文本的区域

OCR 只填补 layout region 内的缺口，不会对整屏做无差别 OCR。

5.2 行为事件推断

输入	输出
ui_snapshot(t) + ui_snapshot(t+1)	状态差异
状态差异 + 剪贴板事件	copy / paste
状态差异 + terminal region	run_command
状态差异 + chat input	send_message
状态差异 + editor/file path	edit
app/窗口/url 差异	switch_context

每个行为事件都带证据，YZOS 不会只存一个没有依据的 LLM 判断。

6. 屏幕采集

ScreenCaptureKit 负责落地连续的屏幕证据，默认写为 mp4 分段：

flowchart TD
  SCStream["SCStream"] --> Writer["segment writer"]
  Writer --> Segments["activity_screen_segments"]
  Segments --> Keyframe["keyframe extraction"]
  Keyframe --> OCRVLM["ROI OCR / VLM"]

视频不是行为识别的主路径。它用于审计、回放、OCR 补洞和 VLM 视觉补充。

7. Crystallize 数据流

flowchart TD
  Ended["activity session ended"] --> Collect["collect evidence"]
  Collect --> Triage["LLM triage"]
  Triage --> Signal["entity signal extraction"]
  Signal --> OKF["OKF write/update"]
  OKF --> Index["PostgreSQL index"]
  Collect -.- E1["activity events"]
  Collect -.- E2["UI behavior events"]
  Collect -.- E3["AI tool sessions"]
  Collect -.- E4["clipboard signals"]
  Collect -.- E5["OCR text"]
  Collect -.- E6["screen semantics"]

Crystallize 不会把未脱敏的敏感原文发给外部服务。本地模型可以读取原始上下文，远程模型只会收到脱敏后的文本。

8. Supply 层

flowchart LR
  Clients["Claude Code / Codex / Cursor"] --> MCP["MCP HTTP /mcp"]
  MCP --> Runtime["yzos-runtime"]
  Runtime --> Handlers["supply handlers"]
  Handlers --> Store[("PostgreSQL + OKF")]

Supply 不直连模型，也不编造观察数据。

9. 模块边界

模块	可以做	不可以做
Observe	采集事实、写入 activity 表	生成长期结论
UI State Engine	结构化 UI、比较状态差异、产出行为事件	替用户操作 UI
OCR	对感兴趣区域输出文本框	作为整屏理解的主入口
VLM	生成简短的视觉语义标签	直接产出最终的 triage JSON
Crystallize	结晶知识、实体、任务	编造没有证据的事实
Supply	查询 PostgreSQL / OKF	替用户直接对接外部服务