Hugging Peers

agent-hub-plugin-dev

☆ Save
by iSolver
0 downloads 0 likes on ModelScope updated

Model card

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 下载和框架安装。

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

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

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

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 命令帮助

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 子命令的完整参数：

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 目录，可以直接调用脚本：

# 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 使用

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

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

# 2. 启动 WebUI
qwenpaw app

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

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

qwenpaw tui --agent GameDesigner

ms-agent

# 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：

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.