> ## Documentation Index
> Fetch the complete documentation index at: https://autclaw.shop/llms.txt
> Use this file to discover all available pages before exploring further.

# autClaw 插件 SDK 概览

> 了解 autClaw 插件 SDK，选择 JavaScript 或 Python 编写普通插件，读取消息、发送回复和保存状态。

autClaw 插件可以读取消息、回复文本或媒体、保存配置、等待用户输入、处理 HTTP 路由和定时任务。新插件建议放在 `plugin/scripts/`，并使用内置 `middleware.js` 或 `middleware.py`。

<Note>
  本页面面向插件作者。你只需要编写脚本和顶部声明，不需要绕过 SDK 直接请求 autClaw 服务。
</Note>

## 你可以做什么

<CardGroup cols={2}>
  <Card title="回复消息" icon="reply">
    读取用户消息、匹配规则参数，并回复文本、Markdown 或媒体。
  </Card>

  <Card title="发送媒体" icon="image" href="/cn/plugin-sdk/media">
    发送图片、语音、视频、文件和 mixed 消息。
  </Card>

  <Card title="保存状态" icon="database">
    使用默认存储或命名 bucket 保存用户进度、配置和缓存。
  </Card>

  <Card title="开放路由" icon="route">
    声明 `router` 和 `method`，把插件变成一个 HTTP 处理函数。
  </Card>
</CardGroup>

## 选择语言

| 语言         | 适合场景                         | 典型入口            |
| ---------- | ---------------------------- | --------------- |
| JavaScript | npm 生态、异步 I/O、前端或 Node.js 经验 | `middleware.js` |
| Python     | 数据处理、脚本自动化、AI 调用             | `middleware.py` |

两种语言都能读取消息、发送回复和保存状态。区别主要在你现有的生态和依赖。

<Tabs>
  <Tab title="JavaScript">
    适合需要 npm 生态、异步 I/O 和前端/Node.js 经验的插件作者。

    ```js theme={null}
    //[author: your-name]
    //[runtime: node@22.22.1]
    //[title: Echo]
    //[description: 回复用户输入]
    //[rule: echo (.+)]
    const { Sender, getSenderID } = require('./middleware.js')

    async function main() {
      const sender = new Sender(getSenderID())
      const text = await sender.param(1)
      await sender.reply(text || '请输入内容')
    }

    main().catch((error) => console.error(error))
    ```
  </Tab>

  <Tab title="Python">
    适合数据处理、脚本自动化、AI 调用和 Python 生态依赖。

    ```python theme={null}
    #[author: your-name]
    #[runtime: python@3.12]
    #[title: Echo]
    #[description: 回复用户输入]
    #[rule: echo (.+)]
    from middleware import Sender, getSenderID

    sender = Sender(getSenderID())
    text = sender.param(1)
    sender.reply(text or "请输入内容")
    ```
  </Tab>
</Tabs>

## 创建一个插件

<Steps>
  <Step title="新建脚本">
    在 `plugin/scripts/` 下创建文件，例如 `plugin/scripts/echo.js` 或 `plugin/scripts/echo.py`。
  </Step>

  <Step title="写 manifest headers">
    在文件顶部声明 `author`、`runtime`、`title` 和触发方式。消息插件通常使用 `rule`。
  </Step>

  <Step title="导入 middleware">
    JavaScript 使用 `require('./middleware.js')`；Python 使用 `from middleware import ...`。
  </Step>

  <Step title="创建 Sender 并回复">
    用 `new Sender(getSenderID())` 或 `Sender(getSenderID())` 读取上下文和发送回复。
  </Step>
</Steps>

## 常用文档

<CardGroup cols={2}>
  <Card title="Manifest headers" icon="file-code" href="/cn/plugin-sdk/manifest">
    声明插件名称、作者、触发规则、参数、依赖、路由和定时任务。
  </Card>

  <Card title="适配器插件开发规范" icon="plug" href="/cn/plugin-sdk/adapter-development">
    接入新 IM 渠道，处理账号解析、入站标准化、出站构造和回执解码。
  </Card>

  <Card title="JavaScript middleware" icon="braces" href="/cn/plugin-sdk/javascript">
    查看 `Sender`、存储、文件、路由、等待输入和 cron 的 JavaScript 用法。
  </Card>

  <Card title="Python middleware" icon="code" href="/cn/plugin-sdk/python">
    查看 `Sender`、存储、文件、路由、等待输入和 cron 的 Python 用法。
  </Card>

  <Card title="Media sending" icon="image" href="/cn/plugin-sdk/media">
    发送图片、语音、视频、文件，或处理用户上传文件。
  </Card>
</CardGroup>

## 插件文件和声明

| 位置                    | 说明                  |
| --------------------- | ------------------- |
| `plugin/scripts/*.js` | 普通 JavaScript 插件。   |
| `plugin/scripts/*.py` | 普通 Python 插件。       |
| `plugin/replies/*.js` | 旧版回复脚本。维护旧插件时可继续使用。 |

最小声明：

```js theme={null}
//[author: your-name]
//[runtime: node@22.22.1]
//[rule: hello]
```

```python theme={null}
#[author: your-name]
#[runtime: python@3.12]
#[rule: hello]
```

`author` 必填。`rule` 用来匹配消息。更多字段见 [`Plugin manifest headers`](/cn/plugin-sdk/manifest)。

## 推荐写法

* 使用 `Sender` 读取上下文和回复消息。
* 媒体发送使用 `replyImage`、`replyVoice`、`replyVideo`、`replyFile` 或 `replyMixed`。
* 用户上传文件使用 `sender.getMediaItems()` + `downloadAdapterFile(...)`。
* 配置项写在 `param` 里，运行状态写入 `bucketSet(...)`；bucket 名称可用 `.` 表示子级，推荐最多 3 级。
* 依赖优先写在 `dependency` 里；临时依赖可用 `importModule(...)` 或 `import_module(...)`。

## 避免这些做法

* 不要硬编码运行时凭据、端口或服务地址。
* 不要绕过 SDK 直接请求 autClaw 服务。
* 不要手动解析平台原始文件字段；使用 SDK 的文件下载方法。
* 不要把大量数据塞进一个 bucket key；拆成多个 key 更容易维护。