# @agent-mc/plugin-sdk 中文文档

规范地址：https://npmcn.com/package/%40agent-mc/plugin-sdk/

版本：3\.3\.0
npm 元数据更新时间：2026-11-05T06:00:59.835Z
中文译文更新时间：2026-11-05T20:25:47.581Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40agent-mc/plugin-sdk
原文对照：https://npmcn.com/package/%40agent-mc/plugin-sdk/?lang=original
项目主页：https://docs.omniscio.com/sdk/
源码仓库：https://github.com/jlstradingco/amc-plugin-sdk

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

- 包体积（解压后）：622 kB，104 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-05-19T19:48:36.612Z
- 最新版本发布：2026-11-05T06:00:59.651Z
- 近 30 天下载量：28352（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

用于构建代理任务控制插件的 SDK

## 安装

```sh
npm install @agent-mc/plugin-sdk
```

也可以使用：`pnpm add @agent-mc/plugin-sdk`、`yarn add @agent-mc/plugin-sdk`、`bun add @agent-mc/plugin-sdk`

## README

# @ agent-mc/插件- sdk

**用于构建代理任务控制插件的脚本类型、接口和校验器**

[![npm](https://img.shields.io/npm/v/@agent-mc/plugin-sdk?color=cb3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/@agent-mc/plugin-sdk) [![TypeScript](https://img.shields.io/badge/TypeScript-5.5-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

* * *

## 概览

此包提供了类型定义和显示验证符,用于 [任务控制代理](https://github.com/jlstradingco/agent-mission-control) (AMC)插件. 它是插件工程的 dev 依赖性 — 它为沙盒提供 TypeScript 接口 `PluginContext` 您的后端代码收到 `AgentMC` 浏览器连接您使用的 UI 代码, 以及用于构建时检查的 Zod 动力显示验证器 .

## 安装

```bash
npm install @agent-mc/plugin-sdk --save-dev
```

## 使用量

### 后端类型

```typescript
import type { PluginActivate, PluginContext } from '@agent-mc/plugin-sdk'

const activate: PluginActivate = (ctx) => {
  return {
    async onEnable() {
      const data = await ctx.storage.get('config')
      ctx.log.info('Plugin enabled', data)
    },
    async onShutdown() {
      ctx.log.info('Goodbye')
    },
  }
}

export default activate
```

### 浏览器桥型

```typescript
import type { AgentMC } from '@agent-mc/plugin-sdk/browser'

declare global {
  interface Window { AgentMC: AgentMC }
}

const settings = await window.AgentMC.settings.getAll()
```

### 表面验证

```typescript
import { validateManifest } from '@agent-mc/plugin-sdk/validators'

const result = validateManifest(manifest)
if (!result.valid) {
  console.error(result.errors)
}
```

## 插件连接 API

每个后端插件都收到一个 `PluginContext` 具有这些沙箱能力:

| 能力 | 接口 | 权限 | 说明 |
| --- | --- | --- | --- |
| `storage` | `PluginStorage` | `storage` | 钥匙价值商店`get`, (中文(简体) ), `set`, (中文(简体) ), `delete`, (中文(简体) ), `list`(中文(简体) ) |
| `db` | `PluginDb` | `storage` | SQLite 收藏库 (`insert`, (中文(简体) ), `query`, (中文(简体) ), `getById`, (中文(简体) ), `update`, (中文(简体) ), `delete`(中文(简体) ) |
| `fs` | `PluginFs` | `storage` | 沙盒文件系统( S)`readFile`, (中文(简体) ), `writeFile`, (中文(简体) ), `exists`, (中文(简体) ), `listDir`(中文(简体) ) |
| `sessions` | `PluginSessions` | `sessions` | 创建和管理 Claude 代码会话 |
| `ai` | `PluginAi` | `ai` | 直接 AI 文本生成( R)`generateMessage`, (中文(简体) ), `generateTitle`(中文(简体) ) |
| `http` | `PluginHttp` | `network` | 输出的 HTTP 请求( E)`fetch`(中文(简体) ) |
| `cron` | `PluginCron` | `cron` | 排定的经常性任务 |
| `cli` | `PluginCli` | `cli` | AMC 控制服务器上的 HTTP 端点 |
| `toast` | `PluginToast` | `notifications`\* 联合国 | 草签和操作系统通知 |
| `sidebar` | `PluginSidebar` | —— 说 | 徽章计数和导航项目 |
| `settings` | `PluginSettings` | —— 说 | 读取插件设置( N)`getAll`, (中文(简体) ), `get`(中文(简体) ) |
| `log` | `PluginLogger` | —— 说 | 范围伐木`info`, (中文(简体) ), `warn`, (中文(简体) ), `error`, (中文(简体) ), `debug`(中文(简体) ) |
| `events` | `PluginEvents` | —— 说 | Pub/子事件系统(`emit`, (中文(简体) ), `on`(中文(简体) ) |

\* 联合国 `toast.show()` 总是有的;只有 `toast.notify()` (OS级)要求 `notifications` 允许.

## 权限

宣布为 `manifest.json` AMC在安装和运行时显示:

```json
{
  "permissions": ["storage", "network", "ai"]
}
```

| 权限 | 赠款 |
| --- | --- |
| `storage` | `ctx.storage`, (中文(简体) ), `ctx.db`, (中文(简体) ), `ctx.fs` |
| `sessions` | `ctx.sessions` |
| `ai` | `ctx.ai` |
| `network` | `ctx.http` |
| `cron` | `ctx.cron` |
| `cli` | `ctx.cli` |
| `notifications` | `ctx.toast.notify()` |
| `rss` | 访问 AMC 内置的 RSS 种子数据 |

## 出口

该套装提供了五个切入点:

| 导入路径 | 它提供的东西 |
| --- | --- |
| `@agent-mc/plugin-sdk` | 所有类型脚本类型 + `validateManifest()` + 键 `manifestSchema` + 键 `checkCommandTables()` |
| `@agent-mc/plugin-sdk/browser` | `AgentMC` 用户界面插件的浏览器桥型 |
| `@agent-mc/plugin-sdk/validators` | Zod 显示计划和验证功能 |
| `@agent-mc/plugin-sdk/commands` | `createCommandChannel` (后端)和 `createCommandClient` (平面板):私人命令频道代理无法写入 |
| `@agent-mc/plugin-sdk/testing` | `createTestContext`, (中文(简体) ), `createRpcDouble` 财务报告和审定财务报表 `describeForgedRowsAreInert` 用于插件测试 |

## 后端生命周期

```typescript
interface PluginBackend {
  onEnable?(): Promise<void> | void
  onDisable?(): Promise<void> | void
  onSettingsChanged?(settings: Record<string, unknown>): Promise<void> | void
  onAppReady?(): Promise<void> | void
  onShutdown?(): Promise<void> | void
}
```

## 文档

完整指南、 API 参考和实例 : **[Omniscio 插件 SDK 文档](https://docs.omniscio.com/sdk/)**

-   [开始](https://docs.omniscio.com/sdk/guide/getting-started) ——脚手架您的第一个插件
-   [参考文献](https://docs.omniscio.com/sdk/guide/manifest) - 完整清单 json spec
-   [权限](https://docs.omniscio.com/sdk/guide/permissions) ——每次许可所给予的
-   [面板命令](https://docs.omniscio.com/sdk/guide/commands) ——从面板安全发送命令到后端
-   [API 参考](https://docs.omniscio.com/sdk/api/) - 所有20个能力接口

## 许可证

[麻省理工学院](https://npmcn.com/package/LICENSE)

## 常见问题

### @agent-mc/plugin-sdk 是什么？

用于构建代理任务控制插件的 SDK

### 如何安装 @agent-mc/plugin-sdk？

在项目目录运行 npm install @agent-mc/plugin-sdk，或使用 pnpm add / yarn add / bun add。

### @agent-mc/plugin-sdk 支持 TypeScript 吗？

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

### @agent-mc/plugin-sdk 支持 ESM 还是 CommonJS？

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

### @agent-mc/plugin-sdk 可以商用吗？

@agent-mc/plugin-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @agent-mc/plugin-sdk 的下载量有多少？

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

### @agent-mc/plugin-sdk 还在维护吗？

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