API 总览

当前公开接口

下面的示例与 @qoniai/qoni@0.4.0 的公开 SDK 接口一致。此页用于展示能力边界；完整参数、返回类型和错误处理见 Qoni SDK。

import { Qoni, QoniScopes } from '@qoniai/qoni'

const qoni = new Qoni({
  accessKey: process.env.QONI_ACCESS_KEY!,
  secretKey: process.env.QONI_SECRET_KEY!,
})

身份 API

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

const { data: authorization } = await qoni.delegateToken({
  mode: 'interactive',
  agent: 'agent_researcher',
  scopes: [QoniScopes.WEB_SEARCH_READ, QoniScopes.WEB_SEARCH_MANAGE],
  redirectUri: 'http://localhost:3000/qoni/callback',
  state: crypto.randomUUID(),
  expiresIn: 1800, // 秒
})

console.log(authorization.authorizationUrl)

权威契约

Identity 的完整端点、字段与错误码见 GenAuth 的 API Reference 与 SDK Reference——那两页与代码逐项核对。

关键问题：

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

记忆 API

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

下面的 token 来自 completeDelegateToken({ grantId, code, state }) 完成后的 data.token：

const { data: context } = await qoni.gumem.recall({
  token,
  sessionId: 'daily-assistant',
  query: 'Find laptops for local LLM work'
})

关键问题：

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

网页数据 API

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

const extractRun = await qoni.doAnything.run({
  token,
  prompt: 'Open https://example.com/report and return the main content as Markdown.'
})
const page = await extractRun.wait()

const searchRun = await qoni.webSearch.run({
  token,
  prompt: 'agent memory benchmark',
  maxResultsPerQuery: 5,
})
const result = await searchRun.wait()

关键问题：

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

推荐接入顺序

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