嵌入编辑器
让你的客户在你的应用内创建、编辑、测试和部署他们的决策——从后端创建嵌入会话、@dcision/embed 脚本、权限和事件。
你的终端用户可以在你的应用内使用 Dcision 的决策页面:决策列表、模板、用智能体创建、编辑器和可视化构建器、playground、部署以及每个决策的执行记录。他们只能在自己的子工作区中操作,永远看不到 API 密钥、计费或设置。
1. 打开会话(你的后端)
当已登录的用户打开页面时,你的后端使用你的 API 密钥调用 POST /v1/embed/sessions——永远不要从浏览器调用:
// POST /api/dcision/session in your backend — the user and their workspace come from YOUR session, never the request.
const session = await dcision.embed.createSession({
workspace: { external_id: currentWorkspace.id, name: currentWorkspace.name },
user: { id: currentUser.id, name: currentUser.name },
permissions: canEdit ? undefined : ["decisions:read", "executions:read"],
start_path: body.path, // where the user was (sent back by the embed after a session expires)
locale: "pt",
});
return { url: session.url };url 是一个一次性启动链接,有效期 60 秒。会话本身持续 ttl_seconds(默认 1 小时,最多 12 小时)。
2. 挂载(你的页面)
import { mount } from "@dcision/embed";
const embed = await mount(document.getElementById("decisions")!, {
getSession: ({ path }) => fetch("/api/dcision/session", { method: "POST", body: JSON.stringify({ path }) }).then((r) => r.json()),
onEvent: (event) => {
if (event.type === "decision.deployed") refreshStrategies();
},
});- iframe 会随内容增高(
height: "auto"),并在会话过期时自行在用户所在的页面重新打开会话。 embed.navigate("/decisions/new")打开一个页面;embed.setTheme("dark")切换主题。- 在你的 Content-Security-Policy 中允许该框架:
frame-src https://app.dcision.io。 - 在
@dcision/embed发布到 npm 之前,请从 Dcision 仓库(packages/embed)复制其源码:它没有任何依赖。
权限
| 权限 | 允许用户 |
|---|---|
decisions:read | 查看决策、版本、概览和智能体对话 |
decisions:write | 创建(基于模板)、编辑、复制,以及在 playground 中测试 |
decisions:deploy | 部署、停用和启用 |
decisions:delete | 删除决策 |
executions:read | 查看执行记录和目的地投递 |
agent | 用智能体创建和编辑 |
默认:全部权限。根据你自己的角色进行映射——例如查看者获得 decisions:read 和 executions:read。
事件
嵌入组件会向你的页面发送以下消息(仅发送到你允许的来源)。它们携带 id、slug、版本和路径——从不包含令牌或输入。
| 事件 | 何时 |
|---|---|
ready、navigate | 嵌入组件已加载,或用户切换到了另一个页面(path) |
resize | 内容高度发生变化(height) |
decision.created · decision.updated · decision.deleted | 创建了决策、保存了其草稿,或删除了决策 |
decision.deployed · decision.enabled · decision.disabled | 生产环境运行的内容发生了变化(version) |
session.expiring · session.expired | 会话将在 2 分钟后结束 / 已结束(脚本会重新打开它) |
安全
- 只有在设置 → 合作伙伴中允许的来源才能把编辑器放进框架,且仅在会话有效期内。在 iframe 之外打开时,链接不显示任何内容。
- 你的 API 密钥保留在你的服务器上。使用
DELETE /v1/embed/sessions/{id}撤销一个会话,或使用POST /v1/embed/sessions/revoke撤销某个用户的所有会话;撤销或重新生成创建这些会话的 API 密钥也会关闭它们。 - 你发送的
user会显示在编辑器和智能体聊天中,并计入智能体的按人限制。请从你自己的会话中获取它。