本地推理栈与依赖版本

完整规格见 00-product-spec.md。模态分工见 15-modality-models.md。

1. 决策摘要

层级	macOS arm64（默认）	macOS Intel	Windows（远期）
LLM	llama-server, Metal, GGUF Q4	llama-server, AVX2, GGUF Q4	llama-server, Vulkan, GGUF Q4
VLM	llama-server vision profile	同左	同左
Embedding	fastembed + ort CoreML EP	fastembed, CPU	fastembed + ort DirectML EP
OCR	Vision.framework	Vision.framework	WinRT OCR
PII	规则 + ort NER	同左	规则 + ort NER
Audio	sherpa-onnx	sherpa-onnx	sherpa-onnx
PG	embedded PostgreSQL + pgvector	同左	同左

2. 推理原则

原则	说明
Preflight 先行	默认能力（voice、vlm、screen、ocr、clipboard、llm、embed）必须完成安装校验、加载、smoke test；失败则该能力 SKIP，runtime 仍可进入 Observe（degraded 模式）
Scheduler 统一调度	LLM、VLM、OCR、Embed、Audio 统一经 InferenceScheduler
结构源优先	UI 结构、app adapter、AX、DOM 优先于 OCR
OCR 补洞	OCR 只处理 layout region 的缺口
VLM 低频	VLM 只补充 screen_semantics 和视觉区域标签
Text-only triage	最终 triage JSON 由文本 LLM 加 grammar 产出
本地优先	原始观察数据默认不出机

3. 结构优先推理链

flowchart TD
  AW["Active app / window"] --> AX["App adapter / AX / DOM"]
  AX --> SNAP["ui_snapshots / ui_regions"]
  SNAP --> OCR["ROI OCR text boxes"]
  OCR --> VLM["VLM semantic labels"]
  VLM --> EV["Evidence bundle"]
  EV --> TRI["Text-only LLM triage"]
  TRI --> OUT["OKF / entities / tasks"]

4. Preflight

Check	验收标准
paths	home、models、database、observations 目录可读写
database	embedded PG 启动，migrations 完成
permissions	/permissions 返回 app_path /Applications/YZOS.app
OCR	Vision.framework 对测试帧返回结果（或明确的空结果）
LLM	llama-server 启动，grammar JSON smoke test 通过
VLM	默认能力；对测试图返回短 caption；缺 mmproj weights 时 SKIP
embedding	dummy text 返回当前维度的向量
PII	规则和 NER smoke test 通过
audio	默认能力；sherpa 管线 smoke test 通过；缺模型时 SKIP

Preflight 关键 check（paths、database、permissions、llm）失败时进入 degraded，不得写入新的 Observe 事件。非关键 check（VLM、audio）SKIP 时 runtime 不停止；对应模态降级，其余部分继续 observing。

5. InferenceScheduler

Lane	任务	并发
llm	triage、summary、entity body、merge text	单 slot
vlm	keyframe caption、screen_semantics	与 LLM 互斥或受 profile 控制
ocr	ROI OCR、keyframe OCR	小并发
embed	OKF chunks、entities、search index	小并发
audio	VAD、ASR、speaker pipeline	stream queue

所有模块提交 InferenceJob，不得直接调用 sidecar 或模型运行时。

6. OCR 与 VLM 调度

OCR 触发条件：

• AX、DOM、app adapter 均读不到文本。
• layout region 类型是 canvas、image、browser_content、unknown。
• screen segment 需要 OCR 用于审计。
• 用户打开 Activity 详情，需要补齐可见文本证据。

VLM 触发条件：

• OCR 字符数低于阈值，且 session 时长超过阈值。
• active app 属于视觉重应用类别。
• layout region 中含 canvas、image、design_surface。
• triage evidence 缺少场景语义。

VLM 输出只能作为 evidence 进入 text-only triage，不能直接写入最终 JSON。

7. 验收与验证

验收项	命令或证据
workspace tests	mise exec -- cargo test --workspace -- --test-threads=1
frontend build	pnpm run build
supply	./scripts/verify-supply.sh
goal	./scripts/verify-goal-e2e.sh
status	curl -s http://127.0.0.1:17432/status
permissions	curl -s http://127.0.0.1:17432/permissions
OCR	activity_screen_segments.ocr_status=done 且 text boxes 可追溯
UI state	ui_snapshots、ui_regions、ui_behavior_events 有样本