让开源，少一点语言距离。
npm包中文文档

@drewswiredin/backstage-plugin-assistants-common

中文文档
0.19.0发布于 2026/10/27Apache-2.0TypeScriptESM + CJS近 30 天下载 2419

Shared types and permissions for AI Assistants for Backstage.

原始使用文档
中文原文

@drewswiredin/backstage-plugin-assistants-common

Shared, browser-safe types and permissions for AI Assistants for Backstage: the contract between the frontend and backend packages. It has one runtime dependency, @backstage/plugin-permission-common.

It is installed transitively by both plugins. Depend on it directly when you write a permission policy or a custom nav that references the plugin's permissions:

# a permission policy
yarn --cwd packages/backend add @drewswiredin/backstage-plugin-assistants-common
# a custom nav
yarn --cwd packages/app add @drewswiredin/backstage-plugin-assistants-common

Exports

Permissions:

ExportnameactionGates
assistantUsePermissionassistant.usereadthe chat and the user-facing routes
assistantManagePermissionassistant.manageupdatethe admin editor, /manage/*, and /capabilities
assistantsPermissionsboth, as an array

Types:

  • AssistantDefinition: the canonical assistant shape (one row of the assistants table; the /manage API and admin editor's model), with AssistantAccess (its access policy) and UiOptions.
  • AssistantSummary and StatusResponse: the browser-safe /status projection (no prompt, no access policy), with ToolSummary and ModelOption.
  • CapabilitiesResponse: the editor's assignable inventory, with CapabilityAction and McpServerCapability.
  • AssistantId, ModelId (<providerId>:<model>), ReasoningLevel and the REASONING_LEVELS constant (low, medium, high, max).
  • StatusResponse.requireApproval: the global approval floor as tool names, which the browser uses to gate client tools.
  • StatusResponse.defaultAssistant, and isDefault on AssistantSummary and AssistantDefinition: the default assistant, the one every signed-in user gets.
  • PageContext (path, title, entityRef): the page a surface beside the page sends with a turn.

Client tools (the browser-to-backend contract for tools that run in the user's browser; the blueprint itself is in the frontend package):

  • ClientToolAttributes (readOnly, destructive, idempotent) and ClientToolDeclaration, the per-request declaration (description, JSON Schema parameters, attributes).
  • ClientToolError and ClientToolErrorCode (declined, not_authorized, timeout, aborted, failed): the _error result a client tool returns instead of throwing.
  • CLIENT_TOOL_NAME_PATTERN (<namespace>__<tool>), BUILTIN_CLIENT_TOOLS (render_form, download_file, read_current_page, describe_portal), CLIENT_TOOL_LIMITS (30 per request, 4000-character description, 8192-character schema), and isClientToolName.

Per-user MCP servers (a server the browser calls with the user's own token):

  • UserCredentialSpec (on AssistantSummary.userCredentials): the sign-in a server needs, and USER_CREDENTIALS_HEADER (x-assistants-credentials), the header the browser sends the tokens in.
  • McpOAuthConnection, McpOAuthStatusResponse, McpOAuthStartResponse, and MCP_OAUTH_MESSAGE_TYPE: the Connect flow for a server that runs its own OAuth.
  • StatusResponse.approveEachCall: servers whose gated tools take no Always allow.
  • ApprovalPreview, ApprovalPreviewRequest, ApprovalPreviewResponse, StatusResponse.approvalPreviews, and resolvePreviewField: the diff an approval card shows for a write.

Elicitation (an MCP server asking the user for input mid-call):

  • ElicitationPrompt, ElicitationStatus, ElicitationField, ElicitationOption, and ElicitationResponseRequest.
  • parseElicitationSchema, validateElicitationContent, and isSensitiveElicitationField: the shared schema parsing and validation.

Platform instructions:

  • PLATFORM_INSTRUCTIONS: the fixed text the backend sends before every assistant's prompt; the editor shows it read-only.

License

Apache-2.0

版本与发布记录

@drewswiredin/backstage-plugin-assistants-common 共发布 27 个版本，首次发布于 2026/06/04；过去 12 个月发布了 27 个版本。

版本发布日期距今
0.19.0latest2026/10/2717 天前
0.18.12026/10/2717 天前
0.18.02026/10/2321 天前
0.17.02026/10/2321 天前
0.16.02026/10/2321 天前
0.15.12026/10/2222 天前

关于 @drewswiredin/backstage-plugin-assistants-common 的常见问题

@drewswiredin/backstage-plugin-assistants-common 是什么？

Shared types and permissions for AI Assistants for Backstage.

如何安装 @drewswiredin/backstage-plugin-assistants-common？

在项目目录运行 npm install @drewswiredin/backstage-plugin-assistants-common，或使用 pnpm add / yarn add / bun add。

@drewswiredin/backstage-plugin-assistants-common 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@drewswiredin/backstage-plugin-assistants-common 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require() 都可以使用，打包工具会自动选择合适的版本。

@drewswiredin/backstage-plugin-assistants-common 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js >=22.12。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@drewswiredin/backstage-plugin-assistants-common 可以商用吗？

@drewswiredin/backstage-plugin-assistants-common 使用 Apache-2.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

@drewswiredin/backstage-plugin-assistants-common 的下载量有多少？

根据 npm 官方下载统计，@drewswiredin/backstage-plugin-assistants-common 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,419 次，日均约 81 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@drewswiredin/backstage-plugin-assistants-common 还在维护吗？

最新版本 0.19.0 发布于 2026/10/27（17 天前）；至今共发布 27 个版本，其中过去 12 个月发布了 27 个；首次发布于 2026/06/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。