---
title: agent-hub-plugin
canonical_url: "https://www.modelscope.cn/models/iSolver/agent-hub-plugin"
md_url: "https://www.modelscope.cn/models/iSolver/agent-hub-plugin.md"
repository: iSolver/agent-hub-plugin
last_updated: 2026-09-21
downloads: 0
stars: 0
---

# agent-hub-plugin

> agent-hub-plugin - iSolver 在 ModelScope 开源的模型。一个独立的 Agent 工作区插件，通过 ModelScope Hub 分发。它把 AgentHub 上的 Agent 下载并导入到本地框架（ms-agent / qwenpaw），让 Agent 在本地直接可用。

- **Repository**: iSolver/agent-hub-plugin
- **Downloads**: 0
- **Stars**: 0
- **Last updated**: 2026-09-21

Source: https://www.modelscope.cn/models/iSolver/agent-hub-plugin

---

# agent-hub plugin

一个独立的 Agent 工作区插件，通过 ModelScope Hub 分发。它把 AgentHub 上的 Agent 下载并导入到本地框架（ms-agent / qwenpaw），让 Agent 在本地直接可用。

## 设计背景

- **插件化扩展**：把 Agent 框架适配等不适合放在 modelscope-hub 核心库里的逻辑，下沉到插件中维护。
- **先下载、后安装**：下载只把远程文件落到临时目录（staging），安装阶段再做冲突检测、备份、文件合并和框架注册，避免直接覆盖用户本地配置。
- **双框架支持，可扩展**：同一个插件包同时支持 `ms-agent`（单人格全局架构）和 `qwenpaw`（多 Agent 工作区架构），未来支持灵活扩展更多框架。
- **安全默认**：安装前自动备份工作区；凭据和本地配置优先保留；下载物里的外来绝对路径会告警但不自动改写。

## 支持的使用方式

### 1. 通过 modelscope-hub CLI 一键试用（推荐）

`modelscope` 命令会同时完成插件下载、Agent 下载和框架安装。

```bash
# 安装到 QwenPaw（发布后默认插件生效，无需额外指定插件仓库）
modelscope agent install -r @jnMetaCode/GameDesigner

# 安装到 ms-agent
modelscope agent install -r ms-agent/social_media_bridge_agent
```

如果需要固定插件版本或指定插件仓库：

```bash
modelscope agent install -r @jnMetaCode/GameDesigner \
  --plugin-repo mushenL/agent-hub-plugin \
  --plugin-revision v0.3.1 \
  -y
```

常用选项：

| 选项 | 说明 |
|---|---|
| `-r <repo>` / `--repo <repo>` | AgentHub 上的 Agent 仓库 ID |
| `--plugin-repo <repo>` | 本插件的仓库 ID（默认 `modelscope/agent-hub-plugin`） |
| `--plugin-revision <ver>` | 插件版本，建议固定到具体版本号 |
| `-y` / `--yes` | 跳过覆盖确认 |
| `--force` | 目标已存在时覆盖重装（会先备份） |
| `--agent-id <id>` | 自定义本地 Agent ID（仅 qwenpaw） |
| `--name <display>` | 自定义显示名 |
| `--provider-id <p>` / `--model-id <m>` | 指定模型 |
| `--api-key <k>` | 注入 API key |

### `modelscope agent` 命令帮助

```text
usage: modelscope agent [-h] ACTION ...

Work with remote agent repositories. `download`/`upload`/`list` are low-level raw file transfer. This command transfers raw files only. For framework-aware conversion, watch/sync, status, backups and restore, use the modelscope-agent CLI: `ms-agent agent ...`. `install` instead resolves a framework plugin, fetches it from a model repository, and delegates the install to it.

positional arguments:
  ACTION
    download  Download raw agent files from a remote repository
    upload    Upload raw agent files to a remote repository
    list      List remote agent repositories
    install   Install an agent into its framework via the agent plugin

options:
  -h, --help  show this help message and exit

examples:
  ms agent download -r user/my-agent --local-dir ./my-agent
  ms agent upload -r user/my-agent --local-dir ./my-agent
  ms agent list --owner user
  ms agent install -r user/my-agent
```

`install` 子命令的完整参数：

```text
usage: modelscope agent install [-h] -r REPO [-n NAME] [--framework FRAMEWORK]
                                [--local-dir LOCAL_DIR]
                                [--plugin-repo PLUGIN_REPO]
                                [--plugin-revision PLUGIN_REVISION]
                                [--dry-run] [-y] [--force] [-q]

options:
  -h, --help            show this help message and exit
  -r REPO, --repo REPO  Agent repository to install, in owner/name format
  -n NAME, --name NAME  Sub-agent name to install
  --framework FRAMEWORK Override framework detection
  --local-dir LOCAL_DIR Where the agent repository is downloaded
  --plugin-repo PLUGIN_REPO
                        Plugin model repository, owner/name
  --plugin-revision PLUGIN_REVISION
                        Plugin revision to fetch (default: master)
  --dry-run             Ask the plugin to report instead of change anything
  -y, --yes             Answer the plugin's prompts yes
  --force               Let the plugin overwrite an existing agent
  -q, --quiet           Suppress the plugin's progress output
```

### 2. 本地直接调用安装脚本

如果已经通过其他方式把 Agent 下载到 staging 目录，可以直接调用脚本：

```bash
# QwenPaw
bash scripts/qwenpaw-add-agent.sh <agent-name> --source-dir /path/to/staging --yes

# ms-agent
bash scripts/ms-agent-add-agent.sh <agent-name> --source-dir /path/to/staging --yes
```

### 3. 通过 API 使用

```python
from modelscope_hub.compat import snapshot_download
import sys, importlib

# 1. 下载插件本身
plugin_dir = snapshot_download('mushenL/agent-hub-plugin',
                               repo_type='model',
                               revision='v0.3.1')
sys.path.insert(0, plugin_dir)
hub = importlib.import_module('agent_hub_core')

# 2. 把 Agent 仓库下载到 staging
staging = hub.staging_dir('owner/some-agent')
res = hub.fetch_raw('owner/some-agent', dest=staging)
if not res.ok:
    raise SystemExit(res.error)

# 3. 安装前备份（可选但建议）
backup = hub.backup_workspace('qwenpaw', name='some-agent')

# 4. 调用对应框架的安装脚本
```

## 能力清单

| 能力 | 状态 | 说明 |
|---|---|---|
| `fetch_raw` | 可用 | 从 ModelScope Hub 下载 Agent 文件到指定目录 |
| `backup_workspace` | 可用 | 安装前备份当前工作区 |
| `list_backups` | 可用 | 列出已有备份 |
| `restore` | 可用 | 用备份回滚工作区 |
| `install` | 规划中 | 合并 fetch + 安装的统一入口 |
| `upload` | 规划中 (P1) | 上传本地 Agent |
| `convert` | 规划中 (P2) | 跨框架转换 |

## 执行 `modelscope agent install` 后的步骤

安装脚本会在终端输出一个结构化的结果摘要，按以下步骤启动 Agent 即可。

### QwenPaw

```bash
# 1. 执行安装
modelscope agent install -r @jnMetaCode/GameDesigner

# 2. 启动 WebUI
qwenpaw app

# 3. 打开 http://127.0.0.1:8088
#    新 Agent 已排在 Agent 列表第一位，直接选择即可对话
```

如果更习惯命令行，也可以用 TUI：

```bash
qwenpaw tui --agent GameDesigner
```

### ms-agent

```bash
# 1. 执行安装
modelscope agent install -r ms-agent/social_media_bridge_agent

# 2. 启动 WebUI
ms-agent ui

# 3. 打开 http://127.0.0.1:7860
#    新建 Project，即可使用刚安装的人格对话
```

如果更习惯命令行，也可以用 TUI：

```bash
ms-agent tui --work-dir ~/ms_agent_workspace
```

注意：`~/.ms_agent` 是 ms-agent 的 home 目录（人格配置），`~/ms_agent_workspace` 是工作目录（记忆、会话日志）。直接运行 `ms-agent tui` 会使用当前目录作为工作目录，而不是 `~/ms_agent_workspace`。

ms-agent 是单人格框架，安装会顶替原有人格（会先自动备份）。

## 环境要求

- Python >= 3.10
- `modelscope-hub`
- PyYAML（可选，用于技能 frontmatter 解析，没有时会降级）

目标框架 CLI（`qwenpaw` 或 `ms-agent`）需要在当前 PATH 中可用。

## 安全提示

- 务必固定插件版本（`--plugin-revision v0.3.1`），不要直接用 `master`。
- `plugin.json` 包含每个文件的 `content_sha256`，可单独校验下载完整性。
- `restore` 会阻止路径穿越，并拒绝写入工作区规范之外的文件。

## License

Apache License 2.0. See `LICENSE`.