You're correct that you can't specify a text file as input to the plugin. This should instead be handled through importing the file. While the solution you suggest would technically work on the command line, this would fail in the other interface types that QIIME 2 supports - notably Galaxy or other GUIs. In that case, the user would likely be presented with a text field, and there would be no mechanism for the file to be uploaded from the path they typed into the text field (and many users might not know what to type into the text field).
We don't have great developer documentation on this - we're in the very early stages of re-writing our developer documentation (planning, right now). However, I had a situation that may be similar for a plugin I recently developed. I'll link you to specific lines to show how I handled this.
I have a function that is effectively performing a file transformation - this could be like your archive that you're processing. I'm loading that in as
stratified_table. (This is a table generated by metaphlan, and this function processes it to include just a single taxonomic level and generates a QIIME 2 feature table as output.)
I register this function as a QIME 2 action here.
stratified_table is provided as type
MetaphlanMergedAbundanceTable is defined and then registered.
MetaphlanMergedAbundanceFormat as a format, which is used for importing my file. This format is a type of
TextFileFormat. Note that you should define a basic validator for that file format - it doesn't have to be exhaustive, but it's useful if it gives an indication of whether the file type looks reasonable. (I check that the first five lines have the same number of columns.)
I then define a
DirectoryFormat. This can be a little more complex, but if it's just a single file that you're working with you can just adapt what I have done. Otherwise let me know and I'll point you at some other resources.
Next, I register the two formats I defined, and then associate the format with the type. This defines what we call an "artifact class" - basically a type of artifact that can be used with QIIME 2.
Finally, I create and register a transformer, which takes my format as input and creates and returns a pandas
DataFrame. This gets called when I call my action
metaphlan_taxon, so I can provide my artifact as input and get a DataFrame inside my function.
You could now import and apply your action as illustrated here. This will automatically work with any QIIME 2 interface, including the Python 3 API, the command line interface, Galaxy, or any others. So it's definitely a bit of extra work relative to just providing a path as a parameter, but you've gained a ways of using it that should be comfortable to users with very difference experience levels (from clinicians to data scientists).
Let me know if you have an questions.