@drewswiredin/后台-插件助手

您的开发者门户网站的 AI 助手 . 所有答案都来自你的目录和文档 每个后台动作都作为用户运行.

这是后台AI助理的前端插件,用于新建 前端系统: 一个可折叠的、多对调的聊天页面 /assistants, (中文(简体) ), 在任何一页旁打开并可以读取该一页的面板,为 主页,以及管理员创建助理的应用程序编辑器。 这个 对话使General UI: 窗体由您的脚手架领域构建 扩展名, 有全屏幕平板和缩放的美人鱼图, 下载芯片 已生成的文件,以及门牌的核准卡(Allow、永远允许、拒绝) 工具,它显示一个写给寄存器作为其分支、路径和diff. 每个用户使用用户自己的签名运行的 MCP 服务器连接的工具; a"Connect GitHub"芯片 旁边的模型取取器 把它们签入。 对于服务器 操作自己的OAuth 芯片打开服务器的签名在弹出,然后 显示 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ >\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 当MCP服务器停止中调用时 询问输入,这个问题作为表单出现在工具调用上。 它与:

• @drewswiredin/backstage-plugin-assistants-backend, (中文(简体) ), 后端( 需要)
• @drewswiredin/backstage-plugin-assistants-common, (中文(简体) ), 共享类型和权限(中途安装)

所需资源

• 后台1.56或后期,在新的前端系统上 (单位:千美元)@backstage/frontend-defaults createApp)和新的后端系统 (单位:千美元)@backstage/backend-defaults) (中文(简体) ).
• 节点22.12或后.
• 反应 18 和 react-router-dom ^ 6.30.2 (同属关系).
• 后端的插件数据库: SQLite, Postgres, 或 MySQL.
• 一个模型提供者和API密钥: OpenAI, Anthropic, Azure OpenAI / AI Foundary, 或 OpenAI 相容的端点, 如 打开路透社。 。 。 .
• 建议: @backstage/plugin-signals 在应用程序和 @backstage/plugin-signals-backend 在后端。 前端使用信号 当应用软件有它们时 进行现场调查时.

安装

从您的后台重播根 :

# in the app package
yarn --cwd packages/app add @drewswiredin/backstage-plugin-assistants

# in the backend package
yarn --cwd packages/backend add @drewswiredin/backstage-plugin-assistants-backend

这个 -common 软件包被调取为中转。 在释放日,钉上 版本 (yarn add @drewswiredin/backstage-plugin-assistants@<version>(三); Yarn的收件年龄门 否则就解决了之前的3个 几天时间.

连线

前端

将插件添加到您的应用功能中 。 它的"助理"导航项已注册 自动;不需要额外的导航代码 。 ()/alpha 是后台的导出 用于新前端系统插件的常规,而不是稳定性标记。 )

// packages/app/src/App.tsx
import { createApp } from '@backstage/frontend-defaults';
import assistantsPlugin from '@drewswiredin/backstage-plugin-assistants/alpha';

export default createApp({
  features: [
    assistantsPlugin,
    // ...your other features
  ],
});

页面挂载在 /assistants· ; ?assistant=<id> 在给定上打开 助理人员,以及 /assistants/threads/<id> 打开一个对话。 在应用程序中 与 app.packages: all,该插件在不包含 features 输入.

对于现场工作和未读状态,在app中添加信号(和 @backstage/plugin-signals-backend 到后端; 没有它,页面民调 每10秒钟:

import signalsPlugin from '@backstage/plugin-signals/alpha';

export default createApp({
  features: [assistantsPlugin, signalsPlugin],
});

小组讨论会

面板在每个页右下方放出一个浮动按钮. 它打开一个 侧面面板,一次一个交谈, 页面旁边而不是结束 它:页面内容为它提供了空间. "打开助手"移动 对话框到整页; 没有复制.

面板包装应用程序布局,这是应用程序插件自己的扩展 点,所以它作为舱载 app 插件 。 添加到您的特性 打开它:

import assistantsPlugin, {
  assistantsPanelModule,
} from '@drewswiredin/backstage-plugin-assistants/alpha';

export default createApp({
  features: [assistantsPlugin, assistantsPanelModule],
});

面板打开默认助手,每个登录用户得到的 (在编辑器中指定"Make默认"). 用户可以访问更多 而不是一个助手从菜单上 从助手的名字中选择另一个 面板头; 选择在浏览器中被记住并开始新的 谈话 如果被选中的助手走了, 面板掉回 默认。 标题中的历史按钮列出这位助手早先的列表 对话;选择一个在面板上继续。 模式和推理 努力的选手坐在作曲家的位置,就像在页面上.

Ctrl+/ (单位:千美元)⌘/ 切换面板。 点击页面或 Esc 把它倒到右边的条子上 它被钉住: 在页上工作的时候,头部的针把它打开, 例如,遵循它给你的步骤,并在此浏览器中被记住. 条条的左边缘被点燃 在助手的颜色; 它发光在页面上 在缓慢的脉冲中 当助手在工作 和保持光芒的同时 回复是未读的, 就像其图标上的点一样 。 关闭 (x) 取出条并带回按钮. 后台对话框 和抽屉,如实体检查员或库伯内特斯舱,打开旁边 面板而不是它,然后点击或打入面板留下它们 打开. 拖曳左边缘调整面板大小,双击后返回 默认宽度,并在平板宽度下填充屏幕。 面板会记住您在这个浏览器中最后的快速对话; 只有 "+"和"开放助理"开始新鲜. 工具、批准、表格和 附件与页面相同。 按钮隐藏在助理页面 用户使用 assistant.use。 。 。 .

面板告诉助手它坐在旁边的哪一页(路径,标题, 和目录实体,当页为一时,助手可以读取 页面本身与内置 read_current_page 工具:标题、文本、, 按钮、链接、标签、窗体字段、表格、提醒、图表标签、技术 内容,任何打开的对话框,以及一个术语周围的日志行。 所以"这是什么意思"和"哪个按钮我 按任意一页的工作,没有每页插件代码。 工具显示为芯片 它运行时的对话。 为了关闭整个应用程序:

app:
  extensions:
    - assistant-client-tool:assistants/read-current-page: false

助理也知道这个后台案例通过 内置 describe_portal 工具:已安装的插件,每页都有 路径和目录实体页面(Kubernetes, CI, API)上的标签 从应用程序树上读取每个新前端系统应用程序 建设。 "后台有什么" "哪里能找到我们的API文件" 答案,有链接,来自任何一页,没有可视化器插件。 转过来 同样的方式,与 assistant-client-tool:assistants/describe-portal: false。 。 。 .

主页

一个应用软件的作曲者 @backstage/plugin-home这是面板的 所以作曲家就是那个 页面和面板的使用。 第一个发送生成 对话并把它 切入面板,面板打开并继续,作曲者重新开始 一个没有面板的应用程序,对话将在助理页面上打开.

它在自己的入境点后面行驶, /home和需求 @backstage/plugin-home-react 在你的应用程序。 那个软件包是可选的对等点 依赖性, 所以插件从不拉进去, 和一个没有主页的应用程序 但您的软件包管理器也不会为你安装它。 添加 旁边 @backstage/plugin-home数字 :

yarn --cwd packages/app add @backstage/plugin-home-react

然后将模块添加到您的特性中:

import { assistantsHomeModule } from '@drewswiredin/backstage-plugin-assistants/home';

export default createApp({
  features: [assistantsPlugin, assistantsPanelModule, assistantsHomeModule],
});

模块增加了一个部件, AssistantComposer。它的外观设定为 variant数字 :

width 设定作曲家的宽度为卡片的百分比, 20至100: 100 默认 bar就像一个搜索吧, 和80为其他人.

配置部件并按其名称放在主页的网格上:

app:
  extensions:
    - home-page-widget:assistants/AssistantComposer:
        config:
          variant: bar
          width: 100
    - page:home:
        config:
          defaultConfig:
            - component: AssistantComposer
              column: 0
              row: 0
              width: 12
              height: 2 # the variant's grid rows

作曲家的提示文本是助手自己的"Composer 占位符",设置于 编辑,否则"询问你的服务, Docs, 或者后台的任何东西...". 给 bar一个占位符,比如"询问任何关于我们的系统..." 默认助理使其读取像一个搜索框. 用户保存了家用版式 胜过 defaultConfig 直到他们选择"Restore默认".

为了在别的地方制作,比如在自己的卡片或页面里,使用 构成切入点出口:

import { AssistantComposer } from '@drewswiredin/backstage-plugin-assistants/home';

<AssistantComposer variant="padded" width={90} />;

full 假设家用卡为 16 px 内容粘贴; 其他变体适合 任何容器.

后端

// packages/backend/src/index.ts
backend.add(import('@drewswiredin/backstage-plugin-assistants-backend'));

应用程序配置

添加一个 assistants 块到 app-config.yaml它支撑着平台表面 仅:供应商,MCP服务器,以及批准门. 一个微不足道的例子, 使用 OpenRouter 和内置目录/ TechDocs 读取工具 backend.actions.pluginSources 向助手披露这些工具的条目:

assistants:
  defaultModel: openrouter:anthropic/claude-sonnet-5
  builtinActions: true # registers the built-in catalog/TechDocs read tools
  providers:
    openrouter:
      type: openai-compatible
      apiKey: ${OPENROUTER_API_KEY}
      baseUrl: https://openrouter.ai/api/v1
      models:
        - name: anthropic/claude-sonnet-5
          contextWindow: 1000000

backend:
  actions:
    pluginSources:
      - assistants # plus catalog / scaffolder etc. for their actions

无 assistants 内 backend.actions.pluginSources,一个助手的工具 解析为空列表.

在您的环境中设置密钥( 绝不承诺 ) :

export OPENROUTER_API_KEY=sk-or-...

见 后端读取器 其他一切:模型供应商、MCP服务器、批准闸门和 权限。 辅助性设置(即时、访问、工具、模型)不是 配置;它们在应用程序编辑器中管理。 工具的可用性取决于 后端中安装的动作提供插件; 内置 阅读工具由 builtinActions。 。 。 .

首发

首先启动后端种子 1名助手 向每个注册用户开放, 与三个内置读取工具,并使其成为默认. 打开 /assistants 和它说话,或按 Ctrl+/ 如果面板是 已安装.

用户 assistant.manage 权限在聊天边栏中看到一个齿轮 打开编辑器创建、编辑和删除助手,并选择 带有“ 做默认” 的默认助手。 只有一个助手 默认: 它向每一个登录用户开放, 首先列出, 并且不能是 删除或限制,直到另一个被设定为默认。 下 创建- app 的默认许可政策 两者 assistant.use 财务报告和审定财务报表 assistant.manage; 给予正确的用户 您的许可政策 后端读取器。 。 。 .

自定义侧边栏

插件的导航条目有 ID page:assistants; 在习惯中 NavContentBlueprint, (中文(简体) ), take() 把它放在自己。 它的图标带有 活点: 当用户的谈话在工作时, 琥珀为红色 一个是未读的,无论它在哪里开始.

自动注册的导航条目没有权限:没有权限的用户 assistant.use "你不允许使用" 助手"的页面. 要完全隐藏插件, take() 条目 并把它变成一个 usePermission(assistantUsePermission) 检查 :

// packages/app/src/modules/nav/Sidebar.tsx
import type { ReactNode } from 'react';
import { Sidebar, SidebarItem } from '@backstage/core-components';
import { NavContentBlueprint } from '@backstage/plugin-app-react';
import { usePermission } from '@backstage/plugin-permission-react';
import { assistantUsePermission } from '@drewswiredin/backstage-plugin-assistants-common';

function IfAssistantsAllowed({ children }: { children: ReactNode }) {
  const { allowed } = usePermission({ permission: assistantUsePermission });
  return allowed ? <>{children}</> : null;
}

export const SidebarContent = NavContentBlueprint.make({
  params: {
    component: ({ navItems }) => {
      const nav = navItems.withComponent(item => (
        <SidebarItem icon={() => item.icon} to={item.href} text={item.title} />
      ));
      const assistants = nav.take('page:assistants');
      return (
        <Sidebar>
          {nav.take('page:catalog')}
          <IfAssistantsAllowed>{assistants}</IfAssistantsAllowed>
          {nav.rest({ sortBy: 'title' })}
        </Sidebar>
      );
    },
  },
});

你自建的边栏项目得到相同的点 <AssistantsNavIcon />。 。 。 .

参考文献

根条目导出

插件本身是默认导出 ./alpha 子路径, 也 出口 assistantsPanelModule (见 小组讨论会) (中文(简体) ). 这个 ./home 子路径 出口 assistantsHomeModule,则 AssistantComposer 及其组成部分 AssistantComposerVariant 类型(参见 主页) (中文(简体) ). 软件包根 输出主机应用程序需要整合的内容 :

聊天页面

• 对话:每个助手一个列表;一行菜单的重命名,平针,或 删除它,然后首先排序被绑定的对话.
• 助手细节:信息按钮显示助手的描述,工具 按来源和模型分类.
• 新的对话开启了欢迎 助理的描述和 其启动建议; 立即发出建议.
• 答复有副本,作为丰富的文本复制(对于团队、展望、电子邮件)和 再生,再生分枝之间有取取器. 原因显示a collapsible 块; 没有自己的UI 工具调用显示其输入和输出 在扩展.
• 作曲家掌握着模型和推理的选取者,拍摄图像 (选取或粘贴)以及文本和代码文件,每个最多7 MB,显示上下文 对模型的测量 contextWindow,并停止运行中的答复。 停止答复以“请求被打断”结束;a 与“ 连接已丢失 ” 已退出连接 .
• 附加图像和SVG文件在全屏泛和相片预览中打开.

遗传性UI

四个内置客户端工具总是可用,不需要配置 :

• render_form: 内在形式; 提交的值成为工具结果.
• download_file: 助手生成的文本文件的下载芯片 (CSV,JSON,Markdown,代码,SVG),有文本文件副本.
• read_current_page: 用户查看的页面,作为大纲(见 小组讨论会) (中文(简体) ). 一个应用可以关闭它.
• describe_portal: 此实例的插件、 页面和实体标签( 见 小组讨论会) (中文(简体) ). 一个应用可以关闭它.

美人鱼代码块以图表的形式渲染 它们是后台的光线或黑暗 模式,带有全屏泛和分镜视图。 标记下用 GitHub 制作 {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}所以表格 任务列表 和罢工通过.

表格和脚手架拾取器

助理可以显示内在窗体( render_form 工具)从 后台脚手架字段扩展(所有者、实体和取回器,加) 自定义字段),从应用程序运行时解决. 与 @backstage/plugin-scaffolder 已注册的拾取器从 编目;没有编目,则用简单的输入来制表.

一个脚手架模板的参数 使现在, ui:field 财务报告和审定财务报表 ui:options 包含,所以一个助手可以在对话中显示一个模板自己的形式和 使用已提交的值运行模板。 后端 README 覆盖 流动需要的行动。 。 。 .

客户工具

一个客户端工具在用户的浏览器中运行,带有用户自己的证书,所以 助手可以使用前端已经讲过的系统作为用户 (一个Kubernetes集群, Azure DevOps, GitHub, 一个内部API 后面的 用户的 OAuth 会话 。 任何插件或应用程序模块都提供一个 AssistantClientToolBlueprint; 助手插件发送声明 在每一个转弯的后端运行 execute 当模型称它,和 返回模型中的结果。 证书从不离开浏览器.

import { createFrontendModule } from '@backstage/frontend-plugin-api';
import { microsoftAuthApiRef } from '@backstage/core-plugin-api';
import { AssistantClientToolBlueprint } from '@drewswiredin/backstage-plugin-assistants';

const recentBuilds = AssistantClientToolBlueprint.make({
  name: 'recent-builds',
  params: defineParams =>
    defineParams<{ project: string; top?: number }, { builds: unknown[] }>({
      name: 'azure-devops__get_recent_builds',
      title: 'Recent builds',
      description: 'The latest Azure DevOps builds of a project.',
      inputSchema: {
        type: 'object',
        properties: {
          project: { type: 'string' },
          top: { type: 'number', description: 'How many; default 10.' },
        },
        required: ['project'],
      },
      attributes: { readOnly: true },
      auth: {
        kind: 'oauth',
        system: 'Azure DevOps',
        apiRef: microsoftAuthApiRef,
        scopes: ['499b84ac-1321-427f-aa17-267ca6975798/user_impersonation'],
      },
      execute: async ({ project, top = 10 }, { credential, signal }) => {
        const res = await fetch(
          `https://dev.azure.com/my-org/${project}/_apis/build/builds?$top=${top}&api-version=7.1`,
          { headers: { Authorization: `Bearer ${credential}` }, signal },
        );
        if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
        const { value } = await res.json();
        return {
          builds: value.map((b: any) => ({
            id: b.id,
            status: b.status,
            result: b.result,
          })),
        };
      },
    }),
});

export const assistantToolsModule = createFrontendModule({
  pluginId: 'assistants',
  extensions: [recentBuilds],
});

将模块添加到应用程序 features,然后通过 名称在编辑器工具部分,在"浏览器工具"下. 合同:

• name 实值 <namespace>__<tool>; 命名空间将插件的工具分开 从后台动作和MCP服务器. description (最多4 000人) 字符)和 inputSchema (一个JSON Schema对象,最多8个KB)是什么 模特儿看见了.
• attributes.readOnly 财务报告和审定财务报表 destructive 镜像后台动作属性. 不只读或破坏性的工具,请用户批准 每一次通话,都不允许。 仅读工具询问何时 备份 requireApproval 说吧.
• auth 是可选的. oauth a. 后台 OAuth API和瞄准镜; custom 供应a acquire({ apis, interactive }) 用于管理其插件 拥有证书(例如Kubernetes的认证提供者API)。 运行时间 首先悄悄地获得;当它不产生任何结果时,它显示连接 控制并获取点击时, 因此没有弹出被屏蔽 。 证书 仅达到 execute。 。 。 .
• execute(input, { apis, credential, signal }) 返回 JSON 序列大小 结果. apis 是应用程序的 API 持有人,所以工具可以调用任何前端 API (单位:千美元)catalogApiRef,一个插件本身的 API ) 而不是直接获取。 掷出 错误, 超时( e)timeoutMs,默认为 30 s, at 多数120 s),拒绝批准,或 连接每个成为一个 { _error: true, code, message } 结果 模型解释.
• render 工具可选 execute (电话别处显示) 其输入和输出),对于一个没有其卡片的工具的要求 提供结果 addResult;这就是如何 render_form 工作时.
• isAvailable({ apis }) 隐藏无法在此应用中工作的工具 .

保持成果小而明确:返回模型需要的字段,永远不要 原始物品被丢弃,从来就没有秘密 工具返回的每件事都是不可信的 输入到模型中.

拥有一个提供商自行运行工具循环的模型(代理SDK或CLI a) 后端模块已添加; 见 后端读取器, (中文(简体) ), 转弯不能暂停浏览器,所以它只能打开调用: a 工具的 execute 运行一次,结果返回同一转弯,a 诸如卡片工具 render_form 返回其 addResult一种工具,可以 首先询问( 写作 或需要连接 ) 模型,模型 被告知为什么。 后端的入门工具的批准卡 工作如常.

依赖性版本

这个 @assistant-ui/* 设定, assistant-cloud,和AI SDK (ai, (中文(简体) ), @ai-sdk/react)被宣布为与上游宣布的相匹配的护卫范围 因此,消费者可以解决每份单份。 上游移动 一家人被锁住,把他们打成一团.

许可证

阿帕奇2.0 (英语). 包括来自助手的麻省理工学院许可组件,列于 THIRD_PARTY_NOTICES.md,随此包裹一起运出.