嵌入编辑器

让你的客户在你的应用内创建、编辑、测试和部署他们的决策——从后端创建嵌入会话、@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 会显示在编辑器和智能体聊天中,并计入智能体的按人限制。请从你自己的会话中获取它。

本页内容