AI Toolkit

概述

AI Toolkit 为编辑器添加了三个相互关联的界面：

• Ask AI——从工具栏启动的对话框，提供七种一键模式（校对、改写、缩短、扩写、总结、翻译、说明理由），可在选区/文档范围之间切换，并在应用之前进行内联预览。
• AI Chat——一个用于多轮请求的停靠式侧边面板。能感知作用范围，提供快捷提示，每条 AI 回复都带有复制/应用/插入/替换操作。
• AI Review——一个持久化的队列，存放待处理、已接受和已拒绝的建议。可选择与服务器台账同步，实现跨会话审阅。

这三者共用同一个 aiToolkitResolver 钩子和同一套操作约定，因此在一个界面中预览的建议，可以在另一个界面中被接受、拒绝或进一步处理。

演示模式。未配置解析器时，插件附带一个确定性的 defaultResolveAction，因此无需 API 密钥、无需网络调用，就能在本地运行 Ask AI、Chat 和 Review，并得到可预测的输出。

安装

在核心编辑器包之后加载 AI Toolkit 的样式表和脚本。默认情况下，插件加载时会自动在内置的 default、basic、full 和 mobile 工具栏预设中注入一个 Ask AI 按钮。

<link rel="stylesheet" href="/richtexteditor/rte_theme_default.css" />
<link rel="stylesheet" href="/richtexteditor/plugins/aitoolkit.css" />

<script src="/richtexteditor/rte.js"></script>
<script src="/richtexteditor/plugins/all_plugins.js"></script>
<!-- aitoolkit.js is bundled inside all_plugins.js.
     Include it separately only if you are loading plugins piecemeal. -->

<div id="editor"></div>
<script>
  var editor = new RichTextEditor("#editor", {
    toolbar: "full",
    aiToolkitPersistenceKey: "my-editor-ai"
  });
</script>

配置。您下载的 rte.js 顶部有一个以纯文本形式编写、可以编辑的 RTE_DefaultConfig 块——打开它，就能与其他所有编辑器设置一起修改 AI 默认值（持久化键、标签、解析器端点等）。不需要另外加载配置文件。只要 AI 按钮可能被渲染（即使使用默认工具栏），就必须有 aitoolkit.css，否则 AI 下拉菜单的尺寸会不正确。如果想保持 AI 启用但不自动注入按钮，请设置 aiToolkitAutoToolbarButtons: false，然后只在需要的工具栏中添加 aiassist。

var editor = new RichTextEditor("#editor", {
  toolbar: "default",
  aiToolkitAutoToolbarButtons: false
});

三个界面

内置模式

每种模式都是 config.aiToolkitDialogModes 中的一个 { id, title, description } 条目。它们出现在 Ask AI 对话框的 Action 下拉菜单中，也可以通过 runQuickAction(id) 调用。

这些是演示解析器中的确定性桩实现。一旦接入 aiToolkitResolver，每种模式如何处理就由您的函数决定。您还可以注册新的模式——请参阅自定义操作。

aiToolkitResolver 钩子

这是唯一的扩展点。解析器接收一个结构化的请求，返回一个结果（或者一个解析为结果的 Promise）。渲染、预览、审阅和应用都由编辑器处理。

var editor = new RichTextEditor("#editor", {
  toolbar: "full",
  aiToolkitResolver: async function (request) {
    var reply = await fetch("/api/ai", {
      method: "POST",
      body: JSON.stringify({
        mode: request.mode,
        text: request.source,
        language: request.language
      })
    }).then(function (r) { return r.json(); });

    return {
      result: reply.text,             // string: the AI output
      reason: reply.explanation,      // string: why this change
      operations: [{                  // structured plan (optional)
        type: "preview-suggestion",
        text: reply.text,
        reason: reply.explanation
      }]
    };
  }
});

请求结构

响应结构

返回一个包含以下任意字段的普通对象。所有字段都是可选的；不需要的可以省略。

也可以返回一个字符串或一个 Promise。字符串会变成 { result: <that string> }；Promise 会被等待。

操作类型

操作是解析器可以返回的结构化计划。编辑器会按顺序执行它们（或者由用户在计划面板中逐个执行）。

可以用 editor.aiToolkit.registerOperationHandler(type, handler) 注册自定义操作类型。

editor.aiToolkit.registerOperationHandler("insert-callout", function (op, ctx) {
  // ctx = { snapshot, resolved, request, action, editor }
  ctx.editor.insertHTML(
    '<aside class="callout">' + ctx.editor.htmlEncode(op.text) + '</aside>'
  );
  return true; // mark the operation as handled
});

编程 API

所有界面都可以通过 editor.aiToolkit 从代码中打开和控制。

// Open the Ask AI dialog
editor.aiToolkit.openDialog({ presetMode: "rewrite", autoRun: false });

// Quick actions (no dialog) - target: selection if present, else whole document
editor.aiToolkit.runQuickAction("proofread");
editor.aiToolkit.runQuickAction("translate", { language: "spanish" });

// Panels
editor.aiToolkit.openChatPanel({ focusComposer: true });
editor.aiToolkit.openReviewPanel({ focusPanel: true });
editor.aiToolkit.closeChatPanel();
editor.aiToolkit.closeReviewPanel();
editor.aiToolkit.toggleChatPanel();
editor.aiToolkit.toggleReviewPanel();

// Resolve without rendering - useful for tests + headless flows
editor.aiToolkit.resolveAction("rewrite", { source: "hello world" })
  .then(function (resolved) { console.log(resolved.result); });

// Swap the resolver at runtime
editor.aiToolkit.setResolver(myResolver);

// Review queue
var pending = editor.aiToolkit.getSuggestions();
editor.aiToolkit.clearSuggestions();
editor.aiToolkit.saveSuggestionLedger();
editor.aiToolkit.loadSuggestionLedger();

自定义操作和模式

注册面向特定领域的操作（例如 SEO 改写、法律条款检查、语气匹配）。它们会接入同一套对话框、聊天和审阅界面。

// Add a new dialog mode (appears in the Action dropdown)
editor.aiToolkit.registerDialogMode({
  id: "seo",
  title: "SEO rewrite",
  description: "Rewrite for stronger keyword coverage while preserving meaning."
});

// Register the action with a target (where output goes by default)
editor.aiToolkit.registerAction({
  id: "seo",
  title: "SEO rewrite",
  target: "selection-preview",
  resolverMode: "seo"          // passed as request.mode to your resolver
});

// Your resolver handles it just like built-in modes
config.aiToolkitResolver = function (request) {
  if (request.mode === "seo") { /* call your SEO service */ }
  /* ... */
};

持久化与远程台账

AI Review 抽屉中的建议会以您控制的键持久化到 localStorage。设置 aiToolkitPersistenceKey，可以按编辑器实例（例如按文档）划分作用范围。

new RichTextEditor("#editor", {
  aiToolkitPersistenceKey: "doc-42-review",     // localStorage scope
  aiToolkitSuggestionLedgerUrl: "/api/ai/ledger", // optional GET/POST for cross-session sync
  aiToolkitReviewLogUrl: "/api/ai/review-log",    // optional activity feed endpoint
  aiToolkitReviewSyncInterval: 15000               // ms between sync polls (default 15s)
});

设置了台账 URL 后，插件会在打开时发送 GET，在接受/拒绝时发送 POST，使审阅队列能够跨会话保留，并在审阅人之间共享。

BYOK（自带密钥）

重要：编辑器不接受也不存储 API 密钥。密钥应保存在服务器端的密钥管理系统中。

推荐的 BYOK 模式：

1. 您的管理界面让租户选择服务商并粘贴密钥。表单 POST 到您的后端。
2. 您的后端把密钥写入密钥管理系统，按租户划分作用范围。
3. 编辑器的 aiToolkitResolver 带着会话 Cookie POST 到 /api/ai。浏览器中没有密钥。
4. 您的后端查找该租户的密钥，调用服务商，并返回精简后的响应。

可用的管理表单、带路由的解析器和 Express 风格的服务器草图，请参阅 BYOK 演示。

配置参考

试用

上面的每个界面都可以在公开演示中无需 API 密钥运行：

• AI Toolkit 演示——Ask AI、快捷操作、Chat、Review 抽屉
• BYOK 演示——管理设置表单 + 带路由的解析器 + 服务器端草图
• AI Toolkit 概览——带有实时编辑器模型的产品介绍页