macOS 平台指南

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

1. 平台目标

YZOS 运行在 macOS 13+。唯一的授权和运行主体是 /Applications/YZOS.app，bundle id 为 com.yzos.desktop。系统设置弹窗显示名称为 YZOS。

2. 运行时布局

flowchart TD
  Agent["LaunchAgent (com.yzos.autostart)"] -->|open -g -a| Desktop
  subgraph App["/Applications/YZOS.app"]
    Desktop["yzos-desktop (com.yzos.desktop)"]
    Runtime[yzos-runtime]
    Desktop --> Runtime
    Runtime --> HTTP["HTTP 127.0.0.1:17432"]
    Runtime --> PG[embedded PostgreSQL]
    Runtime --> Loops["Observe / Crystallize / Maintain"]
  end

com.yzos.autostart 仅在登录时打开 app，不读取任何受保护资源，不需要 TCC 授权。

3. 权限

权限	用途	TCC 主体
Screen Recording	ScreenCaptureKit、窗口截图、OCR 补洞	com.yzos.desktop
Accessibility	AXUIElement 读取 UI tree、focus、selection	com.yzos.desktop
Microphone	语音观察	com.yzos.desktop
Full Disk Access	部分 IM 或 app 的本地数据库	com.yzos.desktop

查看权限状态：

curl -s http://127.0.0.1:17432/permissions | python3 -m json.tool

4. UI 结构读取

能力	macOS API	用途
当前 app	NSWorkspace	bundle id、localized name、active app
窗口列表	CGWindowListCopyWindowInfo	window id、title、bounds、z-order
UI tree	AXUIElement	role、label、value、focus、selection、bounds
屏幕采集	ScreenCaptureKit	mp4 segments、keyframes、审计证据
OCR	Vision.framework	ROI OCR，返回 text boxes
麦克风	AVFoundation	permission request、audio capture

结构源优先级：

flowchart LR
  Adapter[app adapter] -->|fallback| AX[AX tree]
  AX -->|fallback| DOM[browser adapter / DOM]
  DOM -->|fallback| OCR[ROI OCR]
  OCR -->|fallback| VLM[VLM]

5. ScreenCaptureKit

屏幕采集使用 SCStream，按 segment 落地为 mp4。

flowchart LR
  SCStream[SCStream] --> Writer[segment writer]
  Writer --> Seg[activity_screen_segments]
  Seg --> KF[ffmpeg keyframes]
  KF --> Out[ROI OCR / VLM]

OCR 抽帧频率低于采集 fps，以避免后台功耗过高。

6. Accessibility

AX 读取目标：

字段	说明
role / subrole	button、text area、table、window、group
title / label	可见控件名称
value	输入框、文本区域、选中值
focused	当前焦点元素
selected text	编辑器或输入框的选择内容
bounds	节点位置，用于 layout regions

AX 读取不到的区域会进入 OCR 或 VLM。Electron 应用、自绘 canvas、Figma 类画布需要额外的 app adapter 或视觉补洞。

7. 开发安装

mise trust && mise install
mise run doctor
mise run dev-install

8. 签名验证

codesign -dvvv /Applications/YZOS.app 2>&1 | grep -E 'Identifier|TeamIdentifier|Authority'

预期结果：

Identifier=com.yzos.desktop
TeamIdentifier=T45WM76P25

9. 本机接口

接口	作用
GET /status	runtime state、preflight checks
GET /permissions	macOS TCC 权限状态
POST /permissions/request	权限请求或引导
POST /api/call	本机 API
/mcp	MCP HTTP transport