API Surface

当前资料定义了 SAK 的产品能力与模块边界，但还没有给出稳定的请求/响应协议。本页先提供概念性 API 面，帮助开发者理解每个模块应该暴露什么能力。

Draft interface

下面的示例用于表达集成意图，不代表最终 SDK 或 HTTP 协议。

Identity APIs

Identity API 负责把用户身份、Agent Profile 和工具权限绑定到一个可审计的授权上下文中。

const authorization = await sak.genauth.delegate({
  userId: 'user_123',
  agentId: 'agent_researcher',
  scopes: ['web.search', 'mcp.gmail.read'],
  expiresIn: '30m'
})

关键问题：

• 谁拥有 root authority。
• Agent 能代表用户做什么。
• 授权何时过期，如何撤销。
• 审计日志如何查询。

Memory APIs

Memory API 负责写入、检索、解释和擦除用户上下文。

const context = await sak.gum.recall({
  userId: 'user_123',
  query: 'Find laptops for local LLM work',
  include: ['profile', 'chat', 'search', 'action']
})

关键问题：

• 记忆类型如何分层。
• 检索结果如何解释来源。
• 记忆冲突如何更新。
• 用户如何擦除特定记忆。

Web Data APIs

Web Data API 负责把开放网络转化为结构化输入，并在沙箱中执行浏览器动作。

const page = await sak.web.textify({
  url: 'https://example.com/report',
  format: 'markdown'
})

const result = await sak.web.search({
  query: 'agent memory benchmark',
  mode: 'research'
})

关键问题：

• 搜索结果如何排序、摘要和引用。
• 动态网页如何渲染和抽取。
• 沙箱执行如何隔离和追踪。
• 长任务如何监控变化。

Recommended integration order

1. 接入 GenAuth，建立用户和 Agent 的授权边界。
2. 接入 GUM，沉淀可解释的用户上下文。
3. 接入 Web Agent，让 Agent 连接真实网页数据。