# @ampcode/plugin 中文文档

规范地址：https://npmcn.com/package/%40ampcode/plugin/

版本：0\.0\.0-20261106001255-g161ec3f
npm 元数据更新时间：2026-11-06T00:15:39.240Z
中文译文更新时间：2026-11-06T01:10:40.238Z
软件包许可：Amp Commercial License

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

原始 npm 页面：https://www.npmjs.com/package/%40ampcode/plugin
原文对照：https://npmcn.com/package/%40ampcode/plugin/?lang=original
项目主页：https://ampcode.com/docs/plugin-api
源码仓库：https://github.com/ampcode/amp

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

- 包体积（解压后）：111 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-02-25T01:34:52.219Z
- 最新版本发布：2026-11-06T00:15:39.040Z
- 近 30 天下载量：144189（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：265（近 12 个月 265 个）

## 中文简介

AMP 插件 API

## 安装

```sh
npm install @ampcode/plugin
```

也可以使用：`pnpm add @ampcode/plugin`、`yarn add @ampcode/plugin`、`bun add @ampcode/plugin`

## README

# AMP 插件 API

Amp 插件是扩展和自定义的 TypeScript 文件 [倾角](https://ampcode.com/)。 。 。 .

插件可以:

-   **处理事件** —— 说 `amp.on(...)` 工具呼叫、工具结果和代理生命周期事件
-   **添加工具** —— 说 `amp.registerTool(...)` 对于自定义工具,代理可以调用
-   **捆绑技能** —— 说 `await amp.registerSkill(...)` 以注册技能目录
-   **添加命令** —— 说 `amp.registerCommand(...)` 用于命令调色板动作
-   **显示用户界面** —— 说 `ctx.ui.notify(...)`, (中文(简体) ), `ctx.ui.confirm(...)`, (中文(简体) ), `ctx.ui.input(...)`,以及 `ctx.ui.select(...)`
-   **使用人工智能** —— 说 `amp.ai.ask(...)` 默认为无 推理,除非 `{ reasoningEffort }` 设定
-   **快决定** —— 说 `amp.ai.decide(...)`, (中文(简体) ), `amp.ai.choice(...)`, (中文(简体) ), `amp.ai.noul(...)`,以及 `amp.ai.score(...)` 用于输入有校正概率且未生成文本的决定, 由 TypeSafe 的 Jev 或 OpenAI 的决定 API 回答 `{ model: 'openai/gpt-6-luna' }`
-   **标签线索** —— 说 `ctx.thread.labels()`, (中文(简体) ), `ctx.thread.addLabels(...)`,以及 `ctx.thread.setLabels(...)` 读取并更改当前线索的标签
-   **上传附件** —— 说 `amp.attachments.upload(...)` 上传图像字节并返回 URL 用于支持 URL `{ type: 'image', mimeType, url }` 工具结果块,保留大图像 线程状态

## 地点

从三个位置装入 AMP 插件 :

-   **项目插件** —— 说 `.amp/plugins/*.ts`
-   **系统插件** —— 说 `~/.config/amp/plugins/*.ts`
-   **全局插件** ——在工作空间设置中配置(有限实验发布)

## 最小插件

```ts
import type { PluginAPI } from '@ampcode/plugin'

export const description = 'Shows a notification when a thread session starts'

export default function (amp: PluginAPI) {
    amp.logger.log('Plugin initialized')

    amp.on('session.start', async (event, ctx) => {
        await ctx.ui.notify(`Thread ${event.thread.id} started.`)
    })
}
```

可选 `description` 命名导出必须是最多300个字符的静态字符串. Amp在插件设置中显示,并忽略了缺失,动态,或更长的值.

导出函数中的代码在插件加载时运行. 使用 `session.start` 仅用于 Amp 启动特定线程时应当运行的工作.

更改插件后, 打开命令调色板并运行 `plugins: reload`,或重新启动 Amp.

## 文档

-   插件指南和工作实例 : [https://ampcode.com/docs/customize/plugins 页面存档备份,存于互联网档案馆](https://ampcode.com/docs/customize/plugins)
-   满 `@ampcode/plugin` 类型参考和一个完整的厨房-下沉示例: [https://ampcode.com/docs/plugin-api (英语)](https://ampcode.com/docs/plugin-api)

插件执行代码,所以只使用您信任的人的插件和工作空间.

## 承认

Amp 的插件 API 灵感来自 [pi 的扩展 API](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/extensions.md),由马里奥·泽克纳所创建.

## 常见问题

### @ampcode/plugin 是什么？

AMP 插件 API

### 如何安装 @ampcode/plugin？

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

### @ampcode/plugin 支持 TypeScript 吗？

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

### @ampcode/plugin 支持 ESM 还是 CommonJS？

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

### @ampcode/plugin 可以商用吗？

@ampcode/plugin 使用 Amp Commercial License 许可。声明的许可为 Amp Commercial License，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @ampcode/plugin 的下载量有多少？

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

### @ampcode/plugin 还在维护吗？

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