# @dbx-tools/teams 中文文档

规范地址：https://npmcn.com/package/%40dbx-tools/teams/

版本：0\.9\.144
npm 元数据更新时间：2026-10-20T04:41:08.144Z
中文译文更新时间：2026-11-12T04:43:07.271Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dbx-tools/teams
原文对照：https://npmcn.com/package/%40dbx-tools/teams/?lang=original
项目主页：https://github.com/reggie-db/dbx-tools#readme
源码仓库：https://github.com/reggie-db/dbx-tools

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：458 kB，37 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：8 个
- 首次发布：2026-07-27T17:57:47.799Z
- 最新版本发布：2026-10-20T04:41:07.739Z
- 近 30 天下载量：2911（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：260（近 12 个月 260 个）

## 中文简介

服务器侧微软团队 适应卡运行时间、代理工具和 AppKit 插件

## 安装

```sh
npm install @dbx-tools/teams
```

也可以使用：`pnpm add @dbx-tools/teams`、`yarn add @dbx-tools/teams`、`bun add @dbx-tools/teams`

## README

# @dbx-工具/团队

在 AppKit 或 Mastra 后端添加一个 Microsoft Teams 机器人端点, 或者转出 模式响应为预览或频道帖子的可调取卡。 浏览器安全 纸牌计划 [@dbx-tools/ 共享团队](https://npmcn.com/package/shared/teams)和反应渲染器 `adaptivecards` JavaScript 渲染器) 生活于 [@dbx-tools/ui-teams (英语)](https://npmcn.com/package/ui/teams)。 。 。 .

## 快开始

登记小组的终点,并向一名代理人提供卡片工具:

```ts
import { createApp, server } from "@databricks/appkit";
import { agents, mastra } from "@dbx-tools/appkit-mastra";
import { teams } from "@dbx-tools/teams";

const support = agents.createAgent({
  instructions: "Return Teams cards for deployment summaries.",
  async tools(plugins) {
    return { ...(await plugins.teams.toolkit()) };
  },
});

await createApp({ plugins: [server(), teams(), mastra({ agents: { support } })] });
```

登记还补充:

-   解析配置的 AppKit 插件注册,记录有效的卡 版本和webhook状态在启动时,并挂载了卡-建/卡-站路由.
-   两个代理浮出水面: AppKit `teams.createCard` 工具与独立的 Mastra `create_teams_card` 工厂,两个都拿走小 `CardSpec` 词汇. 每个插件实例保持其卡配置,webhook,以及执行器的分离.
-   编辑一个 `CardSpec` (标题、字幕、文本、, 关键/价值事实,将动作链接到有效的可调适卡1.5文档中.
-   可选地张贴到 Teams 即将到来的 Webhook 中, 包裹在附件中 包含重试执行政策 .
-   `POST /api/teams/messages` - 微软团队发送信息端点: URL 您粘贴到 Azure 瓶注册中, 以便团队频道可以聊天 你的探员 它验证了Bot Service JWT(签名、发行人和 与你的机器人的应用代号相当 立即承认并交付 该代理卡在Bot Framework Connector API上。 这是 团队形状的模拟 Mastra 插件如何在路径中曝光 MCP - the 协议是接口.
-   `POST /api/teams/activity` - 同一回合,与答复同步运行 反应机构的活动。 不需要机器人注册,所以这就是 本地客户端,测试,或任何非团队的呼叫器使用. 对话 id 地图 在代理的内存线上,所以重复转动继续一个对话.
-   `POST /api/teams/card` 运行浏览器 dev 页面帖以获取活卡 预览,和 `POST /api/teams/post` 推出一张卡片到网路上.

## 配置团队交付

```ts
import { createApp, server } from "@databricks/appkit";
import { teams } from "@dbx-tools/teams";
import { agents, mastra } from "@dbx-tools/appkit-mastra";

const support = agents.createAgent({
  instructions: "Summarize results as Teams cards when asked.",
  async tools(plugins) {
    return { ...(await plugins.teams.toolkit()) };
  },
});

await createApp({
  plugins: [
    server(),
    teams({ webhookUrl: process.env.TEAMS_WEBHOOK_URL }),
    mastra({ agents: support, storage: true }),
  ],
});
```

`plugin.teams()` 解析对实例拥有的运行时间的配置,记录 有效的卡片版本, 以及是否连接了网页, 并挂载构建 / 员额路线 `/api/teams`应用整合剂应消耗其原生物 如上所示,保留自有插件的 AppKit 执行链. 这个 `teams.createCard` 工具可以自动继承,因为建卡没有 副作用.

## 交汇牌

```bash
curl -X POST http://localhost:8000/api/teams/activity \
  -H 'content-type: application/json' \
  -d '{
        "activity": {
          "type": "message",
          "text": "did the deploy land?",
          "from": { "id": "user-1", "name": "Reggie" },
          "conversation": { "id": "conv-1" }
        }
      }'
```

答复是 `{ "activities": [...] }`,每项活动 `attachments[].contentType === "application/vnd.microsoft.card.adaptive"` 带有 编辑适应卡 `content` - 一个团队的客户端.

转出两圈:

1.  **答问.** 经纪人通常会回答问题 - 工具可用,没有 `structuredOutput`中,没有卡片.
2.  **形式.** 一秒钟 `structuredOutput` 将重构的答案传递到 `CardSpec`,由构建者编译.

回答首先保留了普通工具的使用. 第二次通行证更改介绍 而不改变答案。 特工们留下来 `create_teams_card` 反之则 方向:在聊天端点上以散文方式回答,选择附加卡. 当代理在第一次通过时, 规格获胜 格式传出被跳过.

因为这个计划是迅速注入的,而不是强制提供商的(Databricks) 服务模式拒绝 `response_format` 并行 `tools`,格式通过是 最好的,所以答案被分层回收: 解析的光谱,一个全 适应卡文档重新读入 spec 词汇表( 多么能用的模型) 通常在要求“适应卡”时返回,有效载荷 Mastra 已拒绝 jSON嵌入了流言,然后流言本身。 格式化 错过成本结构,永远不要回答.

主机嵌入标记( E)`[data:<id>]`, (中文(简体) ), `[chart:<id>]`)从答案中剥去: 聊天UI将那些交换成一个已渲染的表格或图表,但卡片没有这样的插槽, 所以一个标记会变成文字 `[data:01f1...]` 数字属于哪里。 这个 回答密码则询问代理商本身的值.

代理由兄弟会 Mastra 插件按注册名称解决 (单位:千美元)`agentPlugin`默认值 `mastra`),因此,这个包保持了叶子加成并带走 不依赖 `@dbx-tools/appkit-mastra`。通过 `agentId` 在身体中选择一个 特定特工 少管闲事 未挂载的代理插件答覆 503, 一个未知 `agentId` 请回答404.

同样的搜索会获取插件的 `createRequestContext()`,用于构建 每回转 Mastra `RequestContext` 转弯通过两通 需要这样 与聊天对等: 用户范围的工具读取 AppKit 用户的上下文, 所以 没有它 `ask_genie` 在聊天时回答“数据源无法到达” 路线用真实的数字回答。 一个没有工厂服务的供应商 转动时没有用户范围的工具.

不及时的活动 - a `typing` 指标,a `conversationUpdate` 当有人加入时, 一个空消息 - 回答 `{ "activities": [] }` 而不是说 错误, 这符合标准的机器人行为 .

[@dbx-tools/ui-teams (英语)](https://npmcn.com/package/ui/teams)是因为 `TeamsChat` 是匹配的客户端.

## 直接建出一张牌

```ts
import { builder } from "@dbx-tools/teams";

const { card } = builder.buildCardResult({
  title: "Deployment succeeded",
  subtitle: "prod • 2m ago",
  facts: [{ title: "Version", value: "1.4.2" }],
  actions: [{ title: "View run", url: "https://example.com/runs/42" }],
});
// `card` is a full Adaptive Card document; render it with @dbx-tools/ui-teams
// or post it with the plugin's `postCard` export.
```

对于独立的 Mastra 工具,直接提供配置或共享明确 跨工厂运行时间 :

```ts
import { runtime, tool } from "@dbx-tools/teams";

const teamsRuntime = runtime.createTeamsRuntime({ cardVersion: "1.5" });
const createTeamsCard = tool.teamsCardTool({ runtime: teamsRuntime });
```

明确传递运行时间或提供执行器给 `createTeamsRuntime`。 。 。 .

## 使用 AppKit

AppKit 没有“团队”或“适应卡”表面,所以当一个 特工应该发出团队卡。 政策层限制卡片形状: 模型使用一个安全的小词汇(`CardSpec`)而不是原始适应性 Card JSON, 构建者保证一个有计划有效的适应性卡 1.5文档,以及 张贴在明确配置的接通的网页上。 这个包 遵循相同的添加形状 [@dbx-tools/电子邮件](https://npmcn.com/package/%40dbx-tools/email)。 。 。 .

建卡是只读的变换,不需要审批. 张贴 改为 `/api/teams/post` 是一种外在的副作用,但它没有被曝光为一种 代理工具 。 显示该路线拥有呼叫者授权的应用程序 以及任何批准步骤。 团队对话使用的工具 代理审批政策.

## 配置

每个字段优先:明确的插件配置胜出,然后匹配 环境变量.

-   `cardVersion` 编号 : `TEAMS_CARD_VERSION` - 适应卡方案 建造目标。 默认为 `1.5` (团队支持的内容).
-   `webhookUrl` 编号 : `TEAMS_WEBHOOK_URL` - 可选的团队来取网页 URL。 何时 未设置, 发布已禁用, 插件只为 UI 构建卡片 调制。 一个不是绝对 HTTPS URL 的值失败了配置解析 .
-   `agentPlugin` 编号 : `TEAMS_AGENT_PLUGIN` - 兄弟姐妹插件的注册名称 他的探员会回答话题 默认为 `mastra`。设定当 Mastra 插件挂载在一个 `config.name` 超过.
-   `appId` 编号 : `TEAMS_APP_ID` (别名) `MICROSOFT_APP_ID`\- Entra应用程序(客户端) 从你的Azure瓶注册。 要求于 `POST /messages` 接受 观众必须携带入境证.
-   `appPassword` 编号 : `TEAMS_APP_PASSWORD` (别名) `MICROSOFT_APP_PASSWORD`) - 客户端 用于获取出界的连接符.
-   `appTenantId` 编号 : `TEAMS_APP_TENANT_ID` (别名) `MICROSOFT_APP_TENANT_ID`\- 设置 只有一个租户的机器人 留作多租户.
-   `allowUnauthenticated` 编号 : `TEAMS_ALLOW_UNAUTHENTICATED` - 服务 `/messages` 在 HTTP 回复中回答而不是通过 连接器 API. 仅供地方发展之用,除非 `NODE_ENV` 实值 `development`因此,一个生产建筑不能被一个 环境变量。 见"连接一个真正的Teams频道".

这个 `MICROSOFT_APP_*` 别名是 Bot 框架 SDK 和 Azure 的名称 传送门已经使用,所以一个已有的bot的环境没有变化地下降.

## 连接真实的团队频道

1.  创建一个 **阿苏尔瓶** 资源及说明 **微软App ID**创建 客户的秘密.
2.  设定其 **消息端点** 到应用程序主机+ `/api/teams/messages`。 。 。 .
3.  启用 **微软团队** 机器人频道.
4.  给应用程序 `TEAMS_APP_ID` 财务报告和审定财务报表 `TEAMS_APP_PASSWORD` (单位:千美元) `TEAMS_APP_TENANT_ID` 登记单租户.
5.  在 Teams 中安装 Teams 中的 bot , 并使用 Teams 的 app 显示引用同一应用程序 身份证明,并传达它。 代理在"适应卡"中回答.

每个入境请求的终点是:

-   **验证 JWT** 反 Bot 框架 JWKS, 需要信任 发行人和听众人数等于 `appId`观众检查是 事项:为另一个机器人签发的Bot Services由 同样的钥匙,所以没有它 谁有自己的机器人可以驱动你的经纪人.
-   **将回复的目的地绑到符上.** `serviceUrl` 抵达 请求身体,而答复 携带你的机器人的证书, 所以它只是荣誉 当它与已核实的代号相符时 `serviceurl` 索赔.
-   **答复 `200` 在运行代理之前.** 瓶子服务时间流出 a 未经承认的活动在几秒钟内再试一次,而卡片需要更长的时间 因此,同步回复将产生重复的卡片。 输入 指示符显示代理工作期间,卡片通过 准备时连接器 API .

用于未注册的地方发展 `allowUnauthenticated: true` (与 `NODE_ENV=development`和 `/messages` hTTP 回复中的答案, 即时充值演示如何制作活卡.

## 路线

在插件基础路径下挂载 `/api/teams`数字 :

-   `POST /messages` - 工作队传递终点信息(见上文)。 躯体是赤裸的瓶子 框架活动. `401` 在一个不能证实的符号上, `503` 否时 `appId`编号 :`appPassword` 已配置, `400` 无效活动或 `serviceUrl` 与符号不符 答复 `200` 以一空相为体. 答复通过连接器API到达.
-   `POST /activity` - 运行一个对话转弯。 身体为 `{ activity, agentId?, model? }`。答复是 `{ activities }`,每个 携带可适应卡附件. `400` 无效的活动, `404` 一个 不详 `agentId`, (中文(简体) ), `503` 当没有代理插件注册时.
-   `POST /card` - 汇编 `CardSpec` 请求正文进入可适应卡 文档。 dev 显示页帖在此预览卡片直播.
-   `POST /post` - 编译然后推出 `CardSpec` 到已配置的团队 即将来临的网游。 回返 `400` 当身体无效时,当没有时,错误 已配置了 webhook .

## 模块

-   `plugin` - 说吧 `teams` (插件厂)和 `TeamsPlugin`。 。 。 .
-   `tool` - 说吧 `teamsCardTool` 财务报告和审定财务报表 `CREATE_CARD_DESCRIPTION`。 。 。 .
-   `builder` - 说吧 `buildAdaptiveCard` 编号 : `buildCardResult` (纯) `CardSpec` - > 卡片 页:1.
-   `conversation` - 说吧 `runCardTurn` (一项活动,卡片活动退出), `resolveCardAgent`, (中文(简体) ), `promptOf`, (中文(简体) ), `toReplyActivity`, (中文(简体) ), `CARD_TURN_INSTRUCTIONS`, (中文(简体) ), 编辑 `CardAgentLike` 编号 : `AgentProviderLike` 形状.
-   `auth` - 说吧 `verifyBotToken` (输入Bot Service JWT验证), `connectorToken` (外部客户证书), `isAllowedServiceUrl`, (中文(简体) ), 财务报告和审定财务报表 `resetTeamsAuth`。 。 。 .
-   `connector` - 说吧 `sendActivity` 编号 : `sendTyping`,瓶子框架连接器 API 答复通过电话.
-   `messaging` - 说吧 `deliverTurn` (当时的承认)和 `resolveServiceUrl`。 。 。 .
-   `runtime` - 说吧 `createTeamsRuntime`, (中文(简体) ), `buildCardWithRuntime`, (中文(简体) ), `postCardWithRuntime`独立 `buildCard` 编号 : `postCard`。 。 。 .
-   `config` - 说吧 `resolveTeamsConfig`, (中文(简体) ), `TEAMS_CONFIG_SCHEMA`,内存名称 常数,以及 `TeamsPluginConfig` 编号 : `ResolvedTeamsConfig` 类型.
-   `defaults` - 拦截器执行设置和命名盖.

## 常见问题

### @dbx-tools/teams 是什么？

服务器侧微软团队 适应卡运行时间、代理工具和 AppKit 插件

### 如何安装 @dbx-tools/teams？

在项目目录运行 npm install @dbx-tools/teams，或使用 pnpm add / yarn add / bun add。

### @dbx-tools/teams 支持 TypeScript 吗？

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

### @dbx-tools/teams 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dbx-tools/teams 可以商用吗？

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

### @dbx-tools/teams 的下载量有多少？

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

### @dbx-tools/teams 还在维护吗？

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