# Mina-Agent-Plugins

**Repository Path**: Mina-IM/mina-agent-plugins

## Basic Information

- **Project Name**: Mina-Agent-Plugins
- **Description**: mina-agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-20
- **Last Updated**: 2026-11-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

2026-11-11：**0.3.9 已发布**：Hermes Git main/v0.3.9 与 OpenClaw npm latest 已公开回读，运行文件及归档哈希核对通过；两套宿主原生更新均已验证。更新前停止 Gateway，更新后启动；不删除配置或会话。

2026-11-11：**0.3.9** 支持 Hermes 安全重新配置、私有备份及账本身份隔离。OpenClaw 保留现有账号配置行为，完整 SDK 回归 71 项通过。详见[发布说明](releases/0.3.9/RELEASE.md)。npm 发布状态以公开 registry 为准。

2026-11-10：**0.3.8** 修复群路由、定时任务作用域及自定义群隔离验证。已有配置、私聊和管理员群开关保留。详见[0.3.8发布说明](releases/0.3.8/RELEASE.md)。npm latest 已独立核验为0.3.8，公开下载包与测试产物一致。

2026-11-10：**0.3.7** 默认自动准备隔离群执行环境，无需手工配置group_execution。已有配置、私聊和管理员群开关保留。详见[0.3.7发布说明](releases/0.3.7/RELEASE.md)。Hermes Git 与 npm latest 均已独立核验为 0.3.7，公开归档与测试包一致；原更新命令验证通过。

2026-11-10：**0.3.6**修复临时断线后无法恢复，Hermes/OpenClaw均包含更新。用户网关不会自动重启；先停止对应Gateway，执行原更新命令后再启动，保留配置/状态。详情与校验见[0.3.6](releases/0.3.6/RELEASE.md)。Hermes Git main和npm latest均已核验为0.3.6；公开归档与测试包一致，不带版本号安装及更新已验证。

本轮实测范围：Hermes默认私聊、保留主配置的显式私聊路由、错误身份拒绝及旧宿主回归。独立运行配置之间的私聊路由、次配置自有适配器和真实群会话仍需单独联调。

2026-11-09：Hermes 0.3.5 修复 0.22.5 真实会话入口的文字处理失败。更新：先停止 Gateway，执行 `hermes plugins update mina-platform` 后重新启动。已有配置不必重置；首次配置 `hermes mina setup` 成功后可选择重启，默认不执行。运行日志不含密钥/消息正文。OpenClaw运行逻辑未改变，本次不另发npm版本，其更新命令继续跟随公开latest。

2026-11-09：0.3.4 修复 Hermes Python 3.14 被旧上限拒绝，改为最低版本与 SDK 能力检测。已验证 Hermes 0.22.5/Python3.14.9 和 0.21.2/Python3.12.3、OpenClaw2026.10.5。更新前停止 Gateway，完成后重启；不需要删除已有配置和状态。未来宿主版本未全部实测。

2026-11-09：0.3.3 修复 OpenClaw 同步加载兼容，0.3.2 不建议安装。安装与更新继续不指定版本号；停止 Gateway，完成更新后重启。

2026-11-09：0.3.2 多版本兼容补丁；最低 Hermes 0.21.2 / OpenClaw 2026.10.5，结合 SDK 能力检查。已测试 Hermes 0.21.2、0.21.3 和 OpenClaw 2026.10.5，未来宿主未实测。更新前停止 Gateway，更新完成后重启；不删除配置或状态库。

# Mina Agent 插件

Mina IM 的 OpenClaw Channel 与 Hermes Platform 插件，运行在用户自己的云服务器。当前 **0.3.6 公开预览**，保留原有私聊、图片及文档能力，新增群调用、来源会话定时附件与受限远端生成工具。

0.3.1补齐经校验的PDF、文本和Office附件正文读取，并修复群专用Agent身份传递。群调用、主动推送仍需配套Mina服务端、授权和宿主配置，升级不会扩大权限或自动启用视觉模型。真实手机与外部自建宿主仍需验收。

npm `latest` 已验证为 0.3.6；用户安装和更新命令不填写版本号。

## 安装与更新

OpenClaw 用户无需npm账号或填写版本号：

```bash
openclaw plugins install npm:@minaim/openclaw-channel
openclaw channels add mina
```

更新前停止Gateway，执行 `openclaw plugins update mina`，再启动Gateway。

Hermes 仍从本仓库默认main分支安装，仓库当前公开可读，可以直接使用HTTPS安装；既有SSH安装可沿用原更新方式：

```bash
hermes plugins install https://gitee.com/Mina-IM/mina-agent-plugins.git
hermes plugins enable mina-platform
hermes mina setup
```

更新前停止Gateway，执行 `hermes plugins update mina-platform`，再启动Gateway。安装到当前Hermes profile；每个profile绑定一个Mina助手，多个助手使用独立profile。

在 Mina App“我的 → AI 助手”创建助手，用向导填写网关、AppID、助手ID、所有者、凭证版本和密钥。模型、生成服务及相关凭证仍配置在宿主。

## 兼容环境

| 宿主 | 已验证版本 | 运行时 |
| --- | --- | --- |
| OpenClaw | 2026.10.5 | Node >=24.16.0 <25 或 >=26.1.0；Python >=3.9 |
| Hermes | 0.21.2、0.22.5 | Python>=3.11，已验证3.12/3.14；无需Node/npm |

Linux/macOS本地持久盘，实际测试为Linux。其他宿主版本未验证，原版本检查保留。

## 新群能力

群主在群信息的“群机器人”中邀请自己的助手，可邀请多个。群调用和允许定时推送独立开启；指定成员限制调用，不限制其他群成员阅读回复。只有兼为助手所有者的群主可以在该群创建计划，回复及定时输出固定来源群。

用户私有Mina配置可加入：

```json
"group_execution": {"owner":"mina-group-owner","members":"mina-group-members"}
```

OpenClaw建立两个专用Agent，使用彼此独立、与私人Agent不重叠的绝对workspace目录。owner工具范围可用：

```json
["web_search","web_fetch","cron","mina_generate_image","mina_create_document"]
```

members去掉cron。不使用alsoAllow，也不为群配置任意主机shell/文件工具。

Hermes建立两个独立profile。owner的config.yaml可配置：

```yaml
platform_toolsets:
  mina: [web, cronjob, mina_artifacts]
display:
  platforms:
    mina:
      show_reasoning: false
      streaming: false
```

members去掉cronjob，不设置mcp_servers。主运行配置同样关闭Mina推理/流式展示。工具是可选的，保留原工具范围即可维持原能力。

`mina_generate_image`调用宿主原生生成接口，接受文字提示，模型及生成提供方由宿主选择。`mina_create_document`在用户云服务器导出基础文本/表格报告：TXT、Markdown、CSV、PDF、DOCX、XLSX、PPTX。高级排版、格式转换与图片编辑不包含在该工具中。

TXT/Markdown/CSV只用标准库。需要PDF/Office时，在插件实际使用的Python环境按需安装库；完整已验证组合为：

```bash
python -m pip install -r requirements-documents.txt
```

也可独立安装所需库：reportlab(PDF)、python-docx(Word)、openpyxl(Excel)、python-pptx(PPT)。缺少模型、依赖、存储空间或不支持的结果会给文字说明，不伪造附件格式。插件不自动安装依赖或接收生成服务密钥。

## 附件与可靠性

群输入框结构化@具体助手后，可选相册、拍照或文件直接发送；普通发文件、正文手打@、@全体不会自动调用。PNG/JPEG/GIF单张8MiB，文件20MiB，最终结果最多5份附件。解析、OCR由用户宿主能力决定。

生成在远端完成，普通回复自动收集附件；Cron生成进入原群的本地持久发件箱。工具结果无需再次发送。回执accepted仅表示本地受理，不表示Mina、IM或设备已收到。Mina不新增调度器，已有计划管理使用宿主原有CLI/UI。

保留完整私有state/profile卷，包括配置、SQLite、WAL/SHM及待提交快照；更新前停止Gateway，不支持活动执行热升级。凭证文件0600、目录0700；不要删除状态库重试未知任务。已有结果只补交，未知执行不自动重跑。移除助手、停用或撤权后Mina拒绝后续未授权发送；远端离线时不能保证立即停止模型计算或费用。

## 发行与验证

- `openclaw/`、`hermes/` 是完整运行插件；根manifest保持Hermes原生Git更新入口。
- `releases/0.3.0/`保存归档、SHA256和版本说明，0.2.0历史保留。
- [版本记录](CHANGELOG.md)；[OpenClaw详细说明](openclaw/README.md)。

测试覆盖真实固定宿主SDK、原生Cron上下文、中断保护、本机HTTPS/HMAC/SQLite和真实文档格式；生成模型以确定性提供方替代。真实云端提供方、COS/数据库/MQ及手机验收仍待完成。

插件不含Mina业务源码、部署资料、用户配置或凭证。公开npm包标记UNLICENSED，不额外授予开源许可证；Git仓库权限保持现状。

## 0.3.1 文档读取

TXT/Markdown/CSV、DOCX/XLSX/PPTX在插件内有界提取正文；PDF需宿主提供`pdftotext`，旧DOC/XLS/PPT需`catdoc`/`xls2csv`/`catppt`。仅解析本事件校验过的附件，不读取聊天文字指定的任意文件。扫描PDF、加密文件及复杂版式可能无法提取，限制会明确返回。图片交给宿主视觉模型。