供料接口

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

YZOS 只供料，不对话。所有活动、实体、知识、剪贴板、AI 工具状态的查询都必须走 MCP、HTTP API 或 CLI，并且必须返回真实数据。

1. 接口总览

接口	消费者	状态
MCP HTTP `/mcp`	Claude Code、Codex、Cursor	已落地
HTTP `/api/call`	Tauri 前端、CLI、脚本	已落地
CLI `yzos`	终端、CI、人工查询	进行中
Skill `yzos-data`	支持 SKILL.md 的 Agent	已落地

2. MCP HTTP

推荐使用 HTTP transport，地址：

http://127.0.0.1:17432/mcp

查看运行状态：

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

YZOS.app 退出时，/mcp 连接会被拒绝。重新打开 /Applications/YZOS.app 后即可恢复。

3. HTTP API

curl -s -X POST http://127.0.0.1:17432/api/call \
  -H 'Content-Type: application/json' \
  -d '{"method":"entity.list","params":{"kind":"project","limit":10}}'

Endpoint	说明
`GET /status`	runtime 与 preflight 状态
`GET /permissions`	macOS TCC 权限状态
`POST /api/call`	类型化方法调用
`/mcp`	MCP HTTP transport

4. MCP Tools

Tool	用途
`yzos_activity_summary`	日摘要
`yzos_activity_sessions`	activity session 列表（含 UI state 计数与 behavior events）
`yzos_activity_screen_segments`	session 内的屏幕录制分段与 OCR 文本（v0.5 新增）
`yzos_activity_screen_semantics`	session 内的 VLM 标签与区域语义（v0.5 计划中）
`yzos_ai_sessions`	AI 工具 session 列表
`yzos_ai_session_detail`	AI 工具 session 详情
`yzos_entity_list`	人物 / 项目 / 任务列表
`yzos_entity_get`	完整实体档案
`yzos_entity_search`	实体搜索
`yzos_entity_links`	实体关联关系
`yzos_knowledge_search`	OKF chunk 与 AI session prompt 的混合搜索
`yzos_knowledge_read`	OKF 原文
`yzos_clipboard_recent`	最近剪贴板记录
`yzos_clipboard_search`	剪贴板搜索
`yzos_ui_state_summary`	session 内 UI State 各表的行数摘要
`yzos_ui_state_behavior_events`	session 内的 behavior events 列表，含 evidence
`yzos_ui_state_behavior_event_detail`	单个 event 的完整证据链（v0.5 计划中）
`yzos_cron_create`	创建用户自定义 cron job
`yzos_cron_list`	列出维护任务与用户 cron job
`yzos_cron_delete`	删除用户 cron job
`yzos_cron_toggle`	启用或禁用 cron job
`yzos_cron_run_now`	立即运行某个 job

截至 v0.5，YZOS 通过 tools/list 暴露超过 20 个 MCP 工具。

5. CLI

yzos status
yzos entity list --kind person
yzos entity search "query"
yzos clipboard list
yzos clipboard search "query"
yzos paths show

CLI 是 HTTP client，不会直接连接 PostgreSQL。

6. 错误语义

情况	返回
YZOS.app 未运行	connection refused
Preflight 未通过	error 附带 preflight report
权限缺失	permission_denied 附带缺失的权限项
查询结果为空	返回空结果，不编造内容填补
方法不存在	method_not_found