# Autman 插件开发规则与仓库约定

> 来源：已参考 BOSS 上传到本仓库的插件示例，以及 autMan 官方论坛教程：<https://bbs.autman.cn/>。重点参考帖子：插件编写规则、插件编程-头注篇、插件编写概论、微服务插件编写、Python 简单插件编写、消息类型说明、实时 IM 消息监听、适配器插件编写指南。

## 1. 仓库用途

本仓库统一存放 BOSS 的 Autman 插件、参考示例、文档和模板。以后新增插件优先按下面目录组织：

```text
js/          # ECMAScript5 / 内置 JS 插件，通常放 autMan plugin/replies
py/          # Python 插件，通常放 autMan plugin/scripts
plugins/     # 我们新写的正式插件；按功能再分目录或命名
examples/    # 调用示例、配置示例
templates/   # 可复制的插件模板
docs/        # 规则、接口说明、研究记录
```

已有历史插件可保留原路径。新开发插件建议优先放到 `plugins/`，稳定后可按 Autman 实际导入目录复制到 `js/` 或 `py/`。

## 2. 插件类型

Autman 支持多种插件/脚本形态：

| 类型 | 说明 | 常见位置/用途 |
|---|---|---|
| HTML 插件 | 由 Autman Web 服务托管页面 | `plugin/web`，主要自用 |
| ES5 插件 | Autman 内置 ES5 环境运行，内置大量函数 | `plugin/replies`，适合关键词、路由、轻量集成 |
| Python/Node/TS/PHP/Shell/Go 等外部脚本 | Autman 调用宿主系统环境运行，通过 `middleware` 与 Autman 交互 | `plugin/scripts`，适合复杂逻辑、依赖第三方库 |
| 微服务路由插件 | 使用 `router` / `method` 头注暴露 HTTP 接口 | 对外接收 Webhook/API 调用 |
| 适配器插件 | 对接新的社交媒体/IM，将外部消息转换为 Autman 消息格式 | 需要处理 HTTP/WS 通信和消息格式转换 |

注意：除 HTML 插件外，其他插件运行通常要求 Autman 授权有效。

## 3. 头注规则

头注必须放在插件文件头部，用于生成插件元数据和触发条件。

### 3.1 市场/基础元数据

JS 示例：

```js
//[open_source: true]
//[create_at: 2026-01-01 12:00:00]
//[title: 插件名称]
//[author: 作者]
//[service: 售后联系方式]
//[class: 工具类]
//[version: 1.0.0]
//[platform: qq,wx,tg,tb,web]
//[public: false]
//[price: 0]
//[disable: false]
//[description: 插件说明，尽量写清楚用法]
//[icon: https://example.com/icon.png]
```

Python 示例：

```python
# [title: 插件名称]
# [language: python]
# [service: 售后联系方式]
# [disable: false]
# [admin: true]
# [rule: ^指令$]
# [platform: qq,wx,tg,tb]
# [open_source: true]
# [version: 1.0.0]
# [public: false]
# [price: 0]
# [description: 插件说明]
```

字段说明：

| 字段 | 说明 |
|---|---|
| `title` | 插件标题 |
| `author` | 作者 |
| `service` | 售后/联系方式；上架通常必填 |
| `class` | 分类，如工具类、查询类、娱乐类、生活类、图片类等 |
| `platform` | 适用平台，多个用英文逗号分隔 |
| `public` | 是否公开显示到市场；开发测试建议 `false` |
| `disable` | `true` 禁用，`false` 启用 |
| `version` | 版本号 |
| `price` | 价格 |
| `description` | 说明，建议写清楚指令、参数、注意事项 |
| `icon` | 图标 URL，建议 48px 正方形，支持 http/https |

### 3.2 关键词/命令触发

```js
//[rule: ^菜单$]
//[rule: ^菜单管理$]
//[admin: true]
//[priority: 300]
//[cron: 0 7 * * *]
//[bypass: false]
```

规则：

- `rule` 支持正则，可写多行表示多个触发规则。
- `cron` 支持 5 位或 6 位 cron 表达式。
- `admin: true` 表示仅管理员可执行。
- `priority` 数字越大优先级越高。
- `bypass: true` 常用于全拦截规则，例如 `[rule: ?]`，表示旁路并行处理。
- 可用 `imType+` / `imType-`、`userId+` / `userId-`、`groupId+` / `groupId-` 做白名单/黑名单。

示例：

```js
//[rule: ^sim状态$]
//[rule: ^sim短信\s+(.+?)\s+([\s\S]+)$]
//[admin: true]
//[platform: qq,wx,tg,tb]
//[priority: 100]
```

### 3.3 微服务路由触发

微服务插件通过 HTTP 路由触发，新增/修改这类插件后通常需要重启 Autman 才生效。

```js
//[router: /simadmin/status]
//[method: get]
//[method: post]
```

规则：

- `router` 路径必须以 `/` 开头。
- `method` 可写多个，常见为 `get`、`post`，也可支持 `put/delete`。
- GET 参数从 `getRouterParams()` 取。
- POST body 从 `getRouterData()` / `getRouterBody()` 取。
- 最终必须用 `response(obj)` 或兼容方式返回，避免请求挂起。

### 3.4 配参头注

用于让 Autman 后台渲染插件配置项。

```js
//[param: {"required":true,"key":"otto.simadmin_base_url","bool":false,"placeholder":"http://192.168.1.10:3000","name":"SimAdmin地址","desc":"不要以 / 结尾"}]
//[param: {"required":true,"key":"otto.simadmin_token","bool":false,"placeholder":"访问Token","name":"接口鉴权Token","desc":"外部请求必须携带 access_token"}]
//[param: {"required":false,"key":"otto.simadmin_push_master","bool":true,"placeholder":"","name":"是否推送管理员","desc":""}]
//[param: {"spliter":true}]
```

约定：

- `key` 建议使用统一前缀，例如 `otto.simadmin_xxx` 或 `otto.<插件名>_xxx`。
- 密钥/token 不要写死在源码里，放到配参或环境变量。
- `bool: true` 用于开关项。
- `required` 只表示配置 UI 要求，不等于运行期一定存在；代码里仍需校验。

## 4. 常见平台/消息类型

论坛中整理的常见类型：

| 类型 | 含义 |
|---|---|
| `qq` | QQ 框架 |
| `qb` | QQ 频道机器人 |
| `wx` | 微信外接框架 |
| `wb` | 内置微信机器人 |
| `tg` | Telegram 客户端 |
| `tb` | Telegram 官方机器人 |
| `wm` | 微信订阅号 |
| `wv` | 微信服务号 |
| `wk` | 微信客服 |
| `dd` | 钉钉机器人 |
| `dc` | Discord 机器人 |
| `sk` | Slack 机器人 |
| `fs` | 飞书机器人 |
| `kk` | Kook 机器人 |
| `qh` | 群晖 Synology Chat |
| `we` | 页面对话 |
| `rt` | router 消息 / 微信服务插件消息 |
| `terminal` | 交互模式终端对话 |

## 5. ES5 插件内置函数与用法

### 5.1 基础信息

```js
var name = call("name")()
var port = call("port")()
var version = call("version")()
var machineId = call("machineId")()
var id = call("uuid")()
var sign = call("md5")("text")
var now = call("timeFormat")("yyyy-MM-dd hh:mm:ss")
var textTime = call("unixTimeFormat")(second, nanosecond, "yyyy-MM-dd hh:mm:ss")
var ok = cancall("someFunc")
var coffeeOk = coffee()
```

### 5.2 消息上下文

常见函数/对象：

```js
var content = GetContent()
var is_admin = isAdmin()
sendText("回复文本")
var msg = input()      // 等待用户输入，适合交互式插件
sender.reply({ok:true, msg:"success"})
Debug("调试日志")
console.log("普通日志")
```

建议：

- 管理类指令必须先判断 `isAdmin()`。
- `input()` 应处理 `null/undefined/空字符串/q退出`。
- JSON 返回优先用对象，便于 Web/API 调用方解析。

### 5.3 数据桶

```js
bucketSet("bucket", "key", "value")
var value = bucketGet("bucket", "key")
bucketDel("bucket", "key")
var keys = bucketKeys("bucket")
```

约定：

- 桶名和 key 统一前缀，避免和其他插件冲突。
- 从 `bucketGet` 读出的复杂对象需要 `JSON.parse`，必须 try/catch。
- 写入复杂对象用 `JSON.stringify`。

### 5.4 获取配置参数

配参 key 形如 `otto.simadmin_base_url` 时，代码中通常按后半段读取：

```js
var baseUrl = get("simadmin_base_url")
var token = get("simadmin_token")
```

实际以 BOSS 上传的插件为准：`qlck.js` 中 `key: "otto.vhook_qlck_token"`，读取为 `get("vhook_qlck_token")`。

### 5.5 网络请求

回调风格：

```js
request({
  useproxy: false,
  url: "https://example.com/api",
  headers: {"Content-Type":"application/json"},
  method: "post",
  dataType: "json",
  body: {a: 1},
  timeOut: 10000
}, function(error, response, header, body) {
  // 处理结果
})
```

同步/直接返回风格（BOSS 上传的 `js/qlck.js` 已使用）：

```js
var resp = request({
  url: baseUrl + "/api/health",
  method: "get",
  dataType: "json",
  timeOut: 10000
})
```

约定：

- HTTP API 插件优先使用 `dataType: "json"`。
- 外部服务业务失败时不一定是 HTTP 非 200，要检查返回 JSON 内的状态字段。
- 请求外部服务前清理 URL 尾部 `/`：`baseUrl.replace(/\/+$/, "")`。
- 超时必须设置，避免插件卡死。

### 5.6 推送消息

```js
push({
  imType: "qq",
  groupCode: "123456",
  content: "群消息"
})

push({
  imType: "wx",
  userID: "user-id",
  content: "私聊消息"
})
```

字段：

- 群组：`groupCode` 或部分平台使用 `chatID`。
- 私聊：`userID`。
- 平台：`imType`。

## 6. 微服务插件运行规则

官方示例提到的微服务函数：

```js
getRouterPath()
getRouterMethod()
getRouterHeaders()
getRouterCookies()
getRouterParams()
getRouterBody()
response(obj)
```

BOSS 上传插件和论坛示例中也常见兼容函数名：

```js
var method = getMethod()
var params = getRouterParams() || {}
var data = getRouterData()
```

建议写法：

```js
function jsonResponse(obj) {
  if (typeof response === "function") {
    response(obj)
  } else if (typeof sender !== "undefined" && sender.reply) {
    sender.reply(obj)
  } else {
    sendText(JSON.stringify(obj))
  }
}
```

外部 API 插件必须注意：

1. 先做 token 鉴权，鉴权失败后立即 `return`。
2. GET/POST 都支持时，参数读取顺序建议：query 参数 -> POST JSON 覆盖。
3. POST JSON 解析必须 try/catch。
4. 对发短信、重启、开关网络等敏感操作必须管理员或 token 控制。
5. 返回统一 JSON：

```json
{"ok":true,"status":"ok","retcode":0,"msg":"success","data":{}}
```

错误：

```json
{"ok":false,"status":"fail","retcode":-1,"msg":"token错误"}
```

## 7. Python 插件规则

Python 插件通过 `middleware` 与 Autman 交互。常见头注：

```python
# [title: 测试]
# [language: python]
# [disable: false]
# [platform: qq,wx]
# [rule: ^测试(.*)$]
# [admin: false]
# [version: 1.0.0]
```

常见初始化：

```python
import middleware

sender_id = middleware.getSenderID()
sender = middleware.Sender(sender_id)
message = sender.getMessage()
user_id = sender.getUserID()
user_name = sender.getUserName()
im_type = sender.getImtype()
chat_id = sender.getChatID()
is_admin = sender.isAdmin()
```

回复/监听：

```python
sender.reply("请输入内容，q退出")
user_input = sender.listen(120000)  # 毫秒
if user_input == "q":
    sender.reply("退出")
    exit(0)
```

数据桶：

```python
middleware.bucketSet("bucket", user_id, "value")
value = middleware.bucketGet("bucket", user_id)
middleware.bucketDel("bucket", user_id)
```

依赖：

- Python 插件可自动安装依赖，但要谨慎，避免每次运行都安装。
- 建议在代码里先 `importlib.import_module` 检测，再提示管理员安装或自动安装。
- 网络请求可用 `requests` / `aiohttp`，但要设置 timeout。

## 8. 适配器插件要点

适配器用于接入新 IM/社交平台。官方建议：

1. 选择不冲突的 `im_type`，尽量 2 个字母，如 `tt`。
2. HTTP 回调地址一般为：

```text
http://<autman-host>:<port>/<im_type>/receive
```

3. Autman 与适配器通信的 WS 地址一般为：

```text
http://<autman-host>:<port>/<im_type>/adapter
```

4. 适配器需要把外部平台消息转换为 Autman 消息格式：

```json
{
  "event": "message",
  "event_data": {},
  "guild_id": "",
  "guild_name": "",
  "bot_id": "",
  "bot_name": "",
  "chat_id": "",
  "chat_name": "",
  "user_id": "",
  "user_name": "",
  "im_type": "tt",
  "message_id": "",
  "content": "消息内容"
}
```

5. Autman 返回动作格式：

```json
{
  "aut_action": "send_msg",
  "aut_echo": "",
  "aut_params": {}
}
```

适配器要把 Autman 动作翻译成外部平台 API 调用，并在需要时回执消息 ID。

## 9. 实时 IM 消息监听

Autman 支持本地 SSE 监听实时 IM 消息，官方接口：

```text
POST /otto/msghook
Accept: text/event-stream
Content-Type: application/json
```

请求 body 示例：

```json
{"imtype":"qq","chatid":"11543756","userid":"282617666"}
```

处理要点：

- 仅限本地访问更安全。
- SSE 数据按行读取，关注 `event:` 和 `data:`。
- 需要处理断线重连。
- 解析 `data:` 后再做业务逻辑。

## 10. 安全与质量约定

开发新插件时必须遵守：

1. **不要硬编码密钥**：token、cookie、API key 放配参、环境变量或本地不提交文件。
2. **外部路由必须鉴权**：尤其是发短信、推送、修改配置、重启、网络开关。
3. **鉴权失败必须 return**：避免只回复错误但继续执行后续逻辑。
4. **敏感操作默认管理员限定**：聊天指令使用 `[admin:true]` 或代码内判断。
5. **统一 JSON 返回**：便于外部系统调用和排错。
6. **请求设置 timeout**：避免 Autman 插件阻塞。
7. **兼容 GET/POST**：微服务接口可同时支持 query 和 JSON body，但 POST JSON 优先。
8. **严格校验参数**：手机号、URL、路径、开关布尔值、枚举值都要校验。
9. **日志不要打印密钥**：token/cookie/API key 必须脱敏。
10. **插件说明写清楚**：头注 description 和 README 中都要写指令、参数、示例。

## 11. 新插件开发流程

1. 先在 `plugins/<plugin-name>/` 下写源码和 README。
2. 根据插件类型复制 `templates/` 里的模板。
3. 本地检查头注、鉴权、参数校验和错误返回。
4. 如需适配 BOSS 已有插件风格，优先参考：
   - `js/qlck.js`：微服务 API + 配参 + token 鉴权 + request 调外部 API。
   - `py/nazha.py`：Python middleware 初始化、依赖检测、平台/用户上下文。
5. 提交前确认没有 `.env`、token、cookie、日志、运行时数据。
6. 推送后验证 raw 文件可访问。

## 12. SimAdmin 插件专项约定

后续实现 SimAdmin 插件时建议：

- 配参：
  - `otto.simadmin_base_url`
  - `otto.simadmin_access_token`
  - `otto.simadmin_timeout_ms`
- 路由：
  - `/simadmin/status`
  - `/simadmin/sms/send`
  - `/simadmin/sms/list`
- 聊天指令：
  - `sim状态`
  - `sim短信 <手机号> <内容>`
- SimAdmin API 业务失败要检查 JSON 内 `status === "error"`。
- 发送短信必须 token 或管理员控制。
- Base URL 默认不带尾部 `/`，代码内统一 trim。
## 13. 账号/Cookie 类插件菜单设计经验（QDReader 复盘）

最近制作 `plugins/qdreader/qdreader_sign_autman.js` 时沉淀出一套适用于账号/Cookie 管理类插件的交互与数据规则，后续新插件优先复用：

### 13.1 交互结构

- 优先做“一级菜单 + 二级编号选择”，不要堆很多平铺子命令。
- 账号管理和执行查询分离：
  - `xxx账号`：只做账号列表、添加/更新、详情/备注、删除、清空。
  - `xxx查询`：只做最近执行情况、单账号执行情况、立即执行等执行侧动作。
- 高频输入可以保留快速通道，例如 `xxxck <cookie>`，但快速通道只做快速提交，不再混入查询/导出/批量导入。
- 用户选择账号时展示编号列表，让用户回复编号；不要让用户手动复制/输入 UID。
- 添加/更新账号成功后立刻询问是否添加备注；备注修改放在账号详情里，不单独做一个割裂的备注菜单。

### 13.2 数据结构

账号/Cookie 类插件不要把 Cookie、用户绑定、备注、执行状态混在一起，建议拆成独立 map：

```json
// cookie_json
{ "uid": "full cookie" }

// user_bind_json
{ "uid": "sender.getUserID()" }

// remark_json
{ "uid": "主号" }

// last_result_json
{ "uid": "{\"ok\":true,\"msg\":\"成功\",\"time\":\"...\"}" }
```

这样删除、过滤、展示和权限校验更安全。

### 13.3 数据桶

- 新插件应创建自己的 bucket，例如 `hermes_qidian`，不要所有插件都塞进 `otto`。
- 如需兼容旧数据，读顺序建议：

```text
bucketGet("插件专属bucket", key)
  ↓ fallback
get(key)
  ↓ fallback
bucketGet("otto", key)
```

- 写入新数据时写到专属 bucket，可同时写普通 `set(key)` 保持兼容。

### 13.4 多用户隔离

- 保存账号时绑定当前用户 ID。
- 账号列表、详情、删除、手动执行只处理当前用户绑定的账号。
- `删除全部` 只删除当前用户账号，不清空全局数据。
- cron/系统触发通常没有用户上下文，是否执行全部账号要显式传 `allUsers` 参数，并在代码和测试里说明。

### 13.5 安全与测试

- 普通回复永远不要输出完整 Cookie；只展示脱敏 UID、备注、Cookie key 摘要或长度。
- 高风险的导出/批量导入功能默认不做，除非 BOSS 明确需要。
- Node VM 测试应模拟：`sender.reply`、`sender.listen`、`sender.getUserID`、`get/set`、`bucketGet/bucketSet`、`request`。
- 测试必须覆盖：快速提交、菜单添加、备注提示、详情改备注、编号选择删除/查询、旧 bucket 兼容、新 bucket 写入、用户隔离、手动执行只跑当前用户、cron 跑全部账号。