OpenAgentPack Kit
SDK

广场与配额 Hooks

usePlaza、useQuota、useQuotaRequests 与 KitClient 提额申请接口

usePlaza 来自 @openagentpack/kit-sdk/agents/hooks, useQuota、useQuotaRequests 来自 @openagentpack/kit-sdk/usage/hooks, 可以显式传入稳定的 client,或在兼容 KitProvider 内运行。数据操作由公开 Client 的 operations 配置; 传给 useChat 的自建 ChatProvider 不会替换它们使用的 Client。

何时使用

这些是示例应用的目录、资源和用量接口,用户可以接自己的业务系统。 它们通过公开 Client/hooks 给组件提供 props,独立于 ChatProvider 的五项会话合同。

智能体资源与成员限额

接口输入返回与边界
useAgentResources(slug)Agent 目录 slug,null 时不查询工具、MCP、Skill 元数据及可选 memory_stores 名称/描述或 null;查询失败也返回 null,用于可选资源展示,不能据此作权限判断
useUsageLimits({ enabled?, days? })默认 enabled=true,days 指定逐日窗口data、loading、error、reload;使用当前 KitClient,不随显式 ChatProvider 切换
client.usageLimits({ days? }, signal?)窗口与可选取消信号本地成员限额视图;成功的 null 表示非本地成员,失败不能解释为不限量

本地成员使用服务端返回的日/月 Token 和执行时长限额;Credits 是匿名/外部身份的兼容模式。 超限阻止后续消费,已经运行的一轮可能继续消耗。用量采集不是最终账单。 资源、限额及历史附件元数据的可编译示例如下:

import { useAgentResources } from "@openagentpack/kit-sdk/agents/hooks";
import { useChat } from "@openagentpack/kit-sdk/chat/hooks";
import type { ChatProvider } from "@openagentpack/kit-sdk/providers";
import type { KitClient } from "@openagentpack/kit-sdk/providers/kit";
import { useSessionDetails } from "@openagentpack/kit-sdk/sessions/hooks";
import { useUsageLimits } from "@openagentpack/kit-sdk/usage/hooks";

// 数据 Hook 支持显式 Client,也可通过 Context 兼容接入。
export function AgentResourceSummary({ slug }: { slug: string | null }) {
	const resources = useAgentResources(slug);
	return (
		<div>
			<p>{resources?.skills?.map((skill) => skill.name).join("、") || "暂无技能信息"}</p>
			<p>{resources?.memory_stores?.map((store) => store.name).join("、") || "暂无记忆库"}</p>
		</div>
	);
}

export function MemberLimitSummary() {
	const limits = useUsageLimits({ days: 30 });
	if (limits.loading) return <p role="status">正在加载限额…</p>;
	if (limits.error) return <p role="alert">{String(limits.error)}</p>;
	if (!limits.data) return <p>当前身份不是 Kit 本地成员</p>;
	return (
		<button type="button" onClick={() => void limits.reload()}>
			刷新用量限制
		</button>
	);
}

// 文件关联记录来自应用元数据。
export function ChatWithFileMetadata({
	client,
	sessionId,
	provider,
}: {
	client: KitClient;
	sessionId: string;
	provider: ChatProvider;
}) {
	const chat = useChat({ sessionId, provider });
	const details = useSessionDetails({ client, sessionId, setMessageFiles: chat.setMessageFiles });
	return details.error ? <p role="alert">{details.error}</p> : <p>{chat.messages.length} 条消息</p>;
}

export async function readUploadStatus(client: KitClient, fileId: string) {
	const status = await client.fileStatus(fileId);
	// 文件就绪前保留草稿,服务端也会校验文件状态和归属。
	return { ready: status.available, status: status.status };
}
  • 展示 Agent 广场:精选、热门、分类与可进入的 Agent 目录。
  • 展示当月配额、加油包与用量分解,并在配额耗尽时禁用输入。
  • 引导用户显式提交提额申请,并在审批通过后刷新结果。

使用说明

广场与配额查询

usePlaza().view 包含 agents、featured、popular 与 categories。 精选和热门返回 slug 列表,页面负责按它们挑选卡片;分类只接受正式的 PlazaCategory, featured 是 UI tab 值,不能直接作为请求的 category。

配额与显式申请

服务端接受一轮 Turn 时消耗 1 Credit;403 quota_exceeded 表示未接受,不能自动重发。 月/日以 UTC 为准。quota.limit 不含加油包,展示总上限时需加上 packs 的 credits; unlimited=true 时使用不限量展示,不能将 remaining=-1 当作负余额。

提交提额申请使用 client.createQuotaRequest({ requestedCredits, reason? })。 申请成功不代表配额立即变更;审批通过后重新读取 quota()。配额申请与工具审批是两套业务, 不调用 submitApproval(),也不复用工具调用的 batch_id/call_id。

默认 Chat 可用 composerDisabled 禁用配额耗尽时的输入;自定义 Sender 传 disabled。 临时连接恢复和工具审批等待仍用 submitDisabled 保留草稿编辑,不能混淆两种禁用语义。

组合示例

以下源文件与 Skill 共享,展示查询、显式提交和提交后的刷新。

import { usePlaza } from "@openagentpack/kit-sdk/agents/hooks";
import { useKitClient } from "@openagentpack/kit-sdk/providers/kit/react";
import { useQuota, useQuotaRequests } from "@openagentpack/kit-sdk/usage/hooks";
import { useState } from "react";

// 与默认会话页挂载在同一个 KitProvider 内。
// 这些 Hook 使用 KitClient,显式 ChatProvider 只接管对话操作。
export function DiscoveryAndUsage() {
	const client = useKitClient();
	const plaza = usePlaza({ category: "general" });
	const usage = useQuota();
	const history = useQuotaRequests();
	const [pending, setPending] = useState(false);
	const [error, setError] = useState<string | null>(null);

	async function requestCredits() {
		if (pending) return;
		setPending(true);
		setError(null);
		try {
			await client.createQuotaRequest({ requestedCredits: 100, reason: "项目新增工作需要更多额度" });
			usage.reload();
			history.reload();
		} catch (cause) {
			setError(cause instanceof Error ? cause.message : "请求失败");
		} finally {
			setPending(false);
		}
	}

	return (
		<section>
			<h2>可用 Agent</h2>
			{plaza.error ? <p role="alert">{plaza.error}</p> : null}
			<ul>
				{plaza.view?.agents.map((agent) => (
					<li key={agent.slug}>{agent.display_name}</li>
				))}
			</ul>
			<h2>月度用量</h2>
			{usage.error ? <p role="alert">{usage.error}</p> : null}
			<p>{usage.quota ? `已用 ${usage.quota.used} Credits` : "正在加载用量"}</p>
			<button
				type="button"
				disabled={pending || usage.loading || !usage.quota || Boolean(usage.quota.pending_request)}
				onClick={() => void requestCredits()}
			>
				申请 100 Credits
			</button>
			{error ? <p role="alert">{error}</p> : null}
			<ul>
				{history.requests.map((request) => (
					<li key={request.id}>{request.status}</li>
				))}
			</ul>
		</section>
	);
}

展示组件见 广场与用量。Client 也可独立于 React 调用 plaza()、quota()、quotaRequests() 与 createQuotaRequest()。

API

Hook 参数与结果

Hook参数与结果
usePlaza({ category?, q? })返回 view、loading、error、reload;参数变化重新查询
useQuota()返回 quota、loading、error、reload,包括当月配额、加油包、按 Agent 分解、每日用量与待审批申请
useQuotaRequests()返回 requests、loading、reload;当前查询失败时清空为 [],没有独立 error 字段

本页目录