组件参考
按对象查找 PraxisKit 属性、方法、事件与默认行为。
<praxis-agent> 在网页中呈现智能体对话。入口为 element.setOptions(options)；本页按属性、方法、事件排列，完整接入步骤见嵌入到网页。
初始化
首次设置必须包含 api.url、agent.name，以及 api.getToken 或 api.publishableKey。缺少时抛出 TypeError。登录用户选择 getToken，匿名访客选择 publishableKey，请二选一；同时提供时使用 publishable key，不调用 getToken。
下面是 Develop 的匿名页面示例。先在该环境创建可公开 key、保存嵌入策略并允许宿主来源，再替换 PRAXIS_PUBLISHABLE_KEY，从该来源提供 HTML。公开 key 不是服务器 API Key。脚本地址、版本和完整性值须使用同一发布版本。
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Course assistant</title>
<script type="module"
src="https://kit-develop.praxisusercontent.com/v0.2.8/praxis-kit.js"
integrity="sha384-vey+VZZcFIWJq9Fmv/nmLxspKtXRiL8XiDOfg2g2QFvwZi5MA+tkiQvPBtoMS8eU"
crossorigin="anonymous"></script>
<praxis-agent style="display:block;height:600px;width:100%"></praxis-agent>
<p id="status" role="status"></p>
<script type="module">
await customElements.whenDefined('praxis-agent');
const agent = document.querySelector('praxis-agent');
const status = document.querySelector('#status');
agent.addEventListener('praxis.ready', () => { status.textContent = 'Interface mounted'; });
agent.addEventListener('praxis.error', () => { status.textContent = 'Check the failed network request'; });
agent.setOptions({
api: {
url: 'https://api-develop.deepraxis.com',
publishableKey: 'PRAXIS_PUBLISHABLE_KEY',
},
agent: { name: 'Course assistant' },
locale: 'en',
});
</script>
</html>预期结果： 页面显示聊天界面，发送问题后收到真实回复。Interface mounted 只表示挂载；验证还要检查回复和用户隔离。
属性
api 与 agent
| 属性 | 类型 | 语义 |
|---|---|---|
api.url | string | 必填，API 源站或以 /agent/v1 结尾的基础地址；初始化后不可变 |
api.getToken | (current: string | null) => Promise<string> | 返回嵌入令牌；首次 current 为 null，刷新时传当前令牌。后端每次重新确认宿主登录态 |
api.publishableKey | string | 匿名令牌入口，替代 getToken；初始化后不可变。访客身份由组件保存的私有 visitor_secret 延续 |
agent.name | string | 必填，界面显示名称，不用于选择智能体 |
agent.avatar | string | 头像 URL；实际访问的智能体由凭证决定 |
onClientTool | (call: { id, name, input }) => unknown | Promise<unknown> | 元素属性，不放入 setOptions。处理前端工具，未知工具应抛错 |
布局与内容
| 属性 | 类型 / 默认值 | 效果 |
|---|---|---|
layout | inline、sidebar、popup、modal；默认 inline | 对话容器形态 |
width | number；400 CSS 像素 | sidebar 宽度 |
launcher.type | none、bubble、mascot | 提供 launcher 时必填；默认 inline 为 none，其他布局为 bubble |
launcher.image、launcher.label | string | 启动按钮图片与文字 |
launcher.position | bottom-right、bottom-left | 启动按钮位置，默认右下 |
header.title、header.subtitle | string | 标题与副标题；标题默认使用 agent.name |
header.icon | string | 支持的 Lucide 图标名或图片 URL |
header.actions | { id: string; icon: string; label: string }[] | 自定义顶栏按钮，点击发出事件 |
history.enabled | boolean；默认 true | 历史入口；关闭时 showHistory() 不生效 |
startScreen.greeting | string | 空会话问候语 |
startScreen.prompts | { label: string; prompt: string }[] | 显示前 4 个；点击发送对应 prompt |
composer.placeholder | string | 默认随语言显示输入提示 |
composer.attachments.enabled | boolean；默认 true | 是否允许选择、粘贴或拖入附件 |
disclaimer、footer | string | 对话说明与底部文字 |
autoScroll | boolean | 新内容到达时是否自动滚动 |
locale | zh、en | 未指定时依次取宿主页面语言、浏览器语言；以 zh 开头用中文，否则英文；无语言信息用英文 |
theme
| 属性 | 值 / 限制 |
|---|---|
colorScheme | light、dark、system；未设置时为浅色，system 跟随浏览器 |
accent、surface | 明确且不透明的 CSS 颜色；拒绝 var()、currentcolor、透明色，抛 TypeError |
grayscale | neutral、warm、cool |
radius | none、sm、md、lg、full；基础圆角依次为 0、4、10、18、9999 CSS 像素 |
density | compact、normal、spacious；基础间距依次为 3、4、5 CSS 像素 |
fontFamily | 非空字体族字符串，不能含 ; { } < >，否则抛 TypeError |
fontSize | 正的有限数字，单位 CSS 像素；否则抛 RangeError |
未设置 accent 时，浅色默认 #167A43，深色默认 #30a46c。颜色前景按对比度选择。
React 属性
React 的 PraxisAgent 使用以下属性。当前 React 绑定仍要求顶层 getToken，即使 options.api 的类型包含 publishableKey；匿名接入可直接使用上面的 Web Component。
| 属性 / 返回对象 | 语义 |
|---|---|
getToken | 必填，与 api.getToken 相同的函数签名 |
options | 上述选项，但不含 api.getToken；省略时呈现未配置元素 |
layout、launcher | 分别覆盖 options.layout、options.launcher.type；launcher 取 none/bubble/mascot |
className、style、children | 宿主元素样式与 React 子元素 |
onClientTool | 前端工具回调；与元素属性同义 |
ref / usePraxisAgent() | ref 提供控制句柄；hook 返回稳定的 { ref, control } |
方法
| 方法 | 返回 / 行为 |
|---|---|
setOptions(partial) | 初始化或合并选项 |
sendUserMessage(text) | Promise<"accepted" | "rejected" | "unknown">；空白、超长、等待审批或无法提交时可拒绝；accepted 不代表回复成功，unknown 时先检查会话，不要盲目重发 |
setComposerValue(text) | 替换草稿，不发送 |
focusComposer() | 聚焦输入框；历史面板打开时不生效 |
setThreadId(id) | 切换会话并关闭历史；null 回到空会话，不切换用户身份 |
showHistory()、hideHistory() | 打开、关闭历史面板 |
open()、close()、toggle() | 展开、收起或切换面板；inline 下无效果 |
setReadable(name, value) | 注册页面上下文；名称 1–64 字符，仅字母、数字与 _ . : -；值为字符串或可 JSON 序列化值 |
removeReadable(name) | 删除该页面上下文值 |
React 控制句柄包含上表从 sendUserMessage 到 toggle 的方法。onReady 前或卸载后调用会抛出未就绪错误，不会排队。React 页面上下文与工具用 usePraxisReadable、usePraxisTool，需要共享注册范围时使用 PraxisProvider，见下方指南。
事件
事件均为可冒泡、可穿过 Shadow DOM 的 CustomEvent。React 回调收到同一个事件对象，通过 event.detail 读取内容。
| 事件 / React 回调 | detail 与时机 |
|---|---|
praxis.ready / onReady | 无；界面已挂载，不代表认证或网络成功 |
praxis.error / onError | KitError（code、status、retryable、message）或仅 { message }；先检查字段是否存在 |
praxis.thread.change / onThreadChange | { threadId: string | null }；当前会话变化 |
praxis.response.start / onResponseStart | 无；开始忙碌处理 |
praxis.response.end / onResponseEnd | 无；结束忙碌处理，不是成功断言 |
praxis.open、praxis.close / onOpen、onClose | 无；面板展开、收起 |
praxis.history.open、praxis.history.close / onHistoryOpen、onHistoryClose | 无；历史面板打开、关闭 |
praxis.header.action / onHeaderAction | { id: string }；点击顶栏自定义按钮 |
praxis.tool.change / onToolChange | { id, name, status: "start" | "end", isError? }；前端工具执行变化 |
praxis.log / onLog | { level: "info" | "warn" | "error", message, data? }；上下文裁剪或工具诊断 |
praxis.frame.close | 无；请求宿主关闭 iframe；React 无对应回调属性 |
默认行为与生命周期
setOptions 递归合并对象、整体替换数组；显式 undefined 重置字段。api.url 和 api.publishableKey 初始化后不能改，变更会抛 TypeError；换后端或用户时销毁旧元素并重新创建。移除元素会释放连接与刷新计时器，不会撤销已签发令牌。
页面上下文快照最多 32 项、4096 UTF-8 字节，超出时从最早注册项开始省略并发出 log。Kit 的这些运行时选项与控制台保存的 iframe/Hosted 外观不是同一个配置入口，持久化外观有自己的字段与大小限制。