> ## Documentation Index
> Fetch the complete documentation index at: https://autclaw.shop/llms.txt
> Use this file to discover all available pages before exploring further.
# JavaScript 工具、Cron 和群管理
> 在 JavaScript 插件中使用 importModule、importJs、系统工具函数、Cron 定时任务和群管理方法。
本页覆盖 `middleware.js` 的工具函数、跨文件引用、运行时定时指令和群管理方法。公开插件应优先使用明确列出的函数，不要依赖未公开内部动作。
## `importModule(module, versionOrOptions?, manager?)`
确保 npm 依赖可用，然后返回 `require(module)` 的结果。
`require(...)` 使用的模块名。
字符串表示版本号。对象可包含 `package`、`version`、`manager`。
真实包名。包名与导入名不一致时使用，例如导入子路径或别名包。
需要安装的版本。
包管理器名称。通常不用传，默认由运行时处理。
```js theme={null}
const { importModule } = require('./middleware.js')
const dayjs = await importModule('dayjs')
const lodash = await importModule('lodash', '4.17.21')
const axios = await importModule('axios', {
package: 'axios',
version: '1.7.9',
manager: 'npm',
})
```
如果导入路径不是 npm 包名，必须用 `package` 指定真实包名：
```js theme={null}
const { nanoid } = await importModule('nanoid/non-secure', {
package: 'nanoid',
version: '5.0.7',
})
```
### 会发生什么
1. `importModule(...)` 会先检查 `module` 是否为空；为空会抛出 `module is required`。
2. 它会向运行时发送 `/dependencyEnsure` 请求，最多等待 `10` 分钟。
3. 运行时按当前插件的 runtime 和 profile 确保依赖可用；未安装时会安装到运行时依赖目录，例如 Docker 默认的 `/opt/autclaw/envs/packages`。
4. 如果传了字符串第二参数，例如 `'4.17.21'`，它会作为 `version`。
5. 如果传了对象，`package` 是要安装的包名，`version` 是版本，`manager` 是包管理器；JavaScript 依赖通常用 `npm`，不传时由运行时推断。
6. 依赖确保完成后，`importModule(...)` 执行 `require(module)`，并返回该模块的导出对象。
`importModule(...)` 不是本地文件导入工具。导入当前插件文件用 `require('./file.js')`；跨插件复用 helper 用 [`importJs(...)`](#importjstarget)。
固定依赖优先写到 manifest 的 `dependency` 中；`importModule(...)` 适合按需加载、动态版本或兼容旧插件。不要在高频循环里反复调用它，建议在插件入口处导入一次后复用。
## `importJs(target)`
`importJs(...)` 是 ES5 / JavaScript 运行时提供的全局函数，用来引用插件工作区里的其他 `.js` 文件，或引用另一个同族 JavaScript 插件里的文件。它最终返回目标文件的 `module.exports`，效果接近 `require(resolvedPath)`。
```js theme={null}
// 引用当前插件工作区里的 hook.js。
const hook = importJs('hook')
// 引用另一个插件里的 hook.js。
const marketHook = importJs('specter:hook.js')
```
### `target` 格式
| 写法 | 含义 |
| ----------------------------- | ---------------------------------------------------------- |
| `importJs('hook')` | 在当前运行工作区查找 `hook.js`。没有扩展名时自动补 `.js`。 |
| `importJs('lib/tool.js')` | 在当前运行工作区查找 `lib/tool.js`。 |
| `importJs('specter:hook.js')` | 跨插件引用：冒号前是目标插件命名空间，冒号后是目标插件内文件路径。 |
| `require('specter:hook.js')` | Node.js / JavaScript 运行时也会把这种 scoped request 归一到工作区内的目标文件。 |
`source_script_id` / 命名空间匹配规则：
* 冒号前的 `specter` 不是文件夹名。运行时会用它匹配目标插件的作者、插件名、市场作者、插件 ID 前缀，以及市场源脚本 ID（`source_script_id`）前缀。
* 对市场插件，`source_script_id` 通常类似 `specter:hook`。运行时会取冒号前缀 `specter` 参与匹配，所以 `importJs('specter:hook.js')` 可以定位到该来源的插件。
* 如果市场插件和本地插件都匹配同一命名空间，优先使用市场插件；没有市场匹配时再使用本地插件。
### 文件解析行为
* 冒号后的路径是目标插件内的文件路径；例如 `specter:lib/hook` 会解析为目标插件里的 `lib/hook.js`。
* 没有扩展名时自动补 `.js`。
* 目标文件会被复制到当前运行工作区，运行时只从工作区内加载。
* 禁止跳出工作区；例如解析后位于工作区外会报 `importJs target is outside runtime workspace`。
* 目标不存在会报 `importJs target not found`；跨插件依赖如果没有匹配到命名空间，会按当前工作区普通文件继续解析，仍找不到时再报 not found。
* 只允许同运行时家族互引：`es5` 只能引用 `es5`；`nodejs` / `typescript` 可以互引；不能跨到 Python 或其他运行时。
* 如果命名空间匹配到了插件，但运行时家族不兼容，会直接报 runtime mismatch，不会自动降级混用。
`importJs(...)` 适合复用公共 helper。不要用它读取用户数据、日志、数据库或密钥文件；也不要依赖未公开插件的内部文件结构。
## 系统和实用函数
| 函数 | 作用 | 参数 | 返回 |
| ---------------------------------- | ------------------------------------------------ | ------------------------------------------- | --------------------------- |
| `render(template, selector, data)` | 渲染 HTML / template，常用于生成图片。当前运行时可能返回空结果，按部署能力为准。 | `template`：模板代码；`selector`：选择器；`data`：模板数据。 | `Promise` |
| `getActiveImtypes()` | 获取当前启用的 IM 类型。 | 无 | `Promise` |
| `name()` | 获取机器人名称。 | 无 | `Promise` |
| `domain()` | 获取本机运行时域名，通常是 `http://127.0.0.1:`。 | 无 | `Promise` |
| `port()` | 获取 autClaw 服务端口。 | 无 | `Promise` |
| `machineId()` | 获取机器 ID。 | 无 | `Promise` |
| `version()` | 获取 autClaw 版本。 | 无 | `Promise` |
| `versionInfo()` | 获取结构化版本信息。 | 无 | `Promise