Paketointi ja asennus¶

Python-liitännäinen on kansio, jossa on plugin.json ja Python-moduuli. Voit asentaa sellaisen kahdella tavalla: paketoi se .mteplugin-arkistoksi ja käytä editorin asennusohjelmaa (suositeltu), tai pudota kansio liitännäishakemistoon käsin.

Aloita mallipohjasta

Valmis kopioitava aloituspaketti sijaitsee arkistossa polussa Python/templates/plugin-template-python/ — kolme tiedostoa (plugin.json, main.py, README.md) sekä Claudelle suunnattu CLAUDE.md. Nimeä kansio liitännäisesi lyhyellä nimellä, muokkaa neljää kenttää tiedostossa plugin.json ja ala kirjoittaa funktiota register(ctx). Asennettu SDK toimittaa saman mallipohjan polussa share/MTEPluginSDK/plugin-template-python/.

Liitännäiskansion rakenne¶

hello/
├── plugin.json      # required
└── main.py          # required; module name from plugin.json.module

Kaiken, mitä liitännäinen tarvitsee, täytyy sijaita tämän kansion sisällä. Alituonnit toimivat mutta niiden täytyy olla litteitä — pistein erotetut module-nimet tiedostossa plugin.json ovat tuleva laajennus.

Voit lisätä ylimääräisiä tiedostoja (README, LICENSE) — isäntä ohittaa sen, mitä se ei tunnista.

`.mteplugin`-paketit (suositeltu)¶

Pakkaa liitännäisen tiedostot zipiksi ja anna arkistolle pääte .mteplugin (tavallinen .zip toimii myös). Molemmat muodot hyväksytään:

hello.mteplugin              hello.mteplugin
├── plugin.json              └── hello-1.0.0/        # any folder name
└── main.py                      ├── plugin.json
                                 └── main.py

Yksi ympäröivä kansio — luonnollinen tulos kansion pakkaamisesta — poistetaan: liitännäinen asennetaan aina polkuun <Plugins>/<id>/ manifestin kentän id mukaan, ei koskaan arkiston kansionimen mukaan. Siksi myös liitännäisen version 2 asentaminen korvaa version 1 sen sijaan että se jäisi sen viereen.

Asenna se kohdasta Asetukset → Liitännäiset → Asenna liitännäinen... ja käynnistä editori uudelleen.

Asenna vain paketteja, joihin luotat

Asennusohjelma tarkistaa, että paketti on rakenteellisesti kunnossa (katso alta) — se ei tee epäluotettavasta liitännäisestä turvallista ajaa. Kun liitännäinen on kerran ladattu, se toimii samalla pääsyllä tiedostoihisi, asetuksiisi ja verkkoosi kuin editori, eikä se toimi hiekkalaatikossa. Staattinen register(...)-tarkistus ei aja koodia asennushetkellä, mutta liitännäisen koodi ajetaan seuraavalla käynnistyksellä. Käsittele .mteplugin-tiedostoa (ja mitä tahansa asetus- tai JSON-tiedostoa, jonka se toimittaa) kuin tuntematonta ohjelmaa: asenna se vain lähteestä, johon luotat. Katso koko varoitus kohdasta Liitännäiset.

Mitä asennusohjelma tarkistaa¶

Paketti tarkistetaan täysin kertakäyttöistä kopiota vasten, ennen kuin mihinkään levyllä kosketaan — huono paketti ei voi koskaan häiritä olemassa olevaa asennusta:

plugin.json jäsentyy, siinä on id, apiVersion vastaa editoria, entry on "python" ja module on olemassa.
Arkiston sisältö on turvallinen: ei absoluuttisia polkuja tai ..-kohtia, enintään 10 000 kohtaa, enintään 256 MiB purettuna ja vähintään yksi .py-tiedosto.
Kertakäyttöiseen hakemistoon purkamisen jälkeen ilmoitettu <module>.py on olemassa ja ilmoittaa ylätason funktion def register(...) — sama staattinen tarkistus, jota etsintä käyttää. Mitään Python-koodia ei ajeta asennushetkellä.

Mikä tahansa epäonnistuminen tuottaa ihmisluettavan virheikkunan ja jättää editorin liitännäiset koskemattomiksi.

Päivittäminen ja poistaminen¶

Sellaisen paketin asentaminen, jonka id on jo asennettu, korvaa sen. Jos kyseinen liitännäinen on parhaillaan ladattuna, päivitys asetetaan jonoon ja otetaan käyttöön seuraavalla käynnistyksellä.
Poista asennus samalta asetussivulta; poisto tapahtuu myös seuraavalla käynnistyksellä, kun mitään ei ole ladattuna.
Mukana tulevia (sisäänrakennettuja) liitännäisiä ei voi ohittaa asennetulla paketilla, jolla on sama id.

Käsin asentaminen (kansion pudottaminen)¶

Editori etsii liitännäisiä kahdesta hakemistosta joka käynnistyksellä:

Mukana tulevat — suoritettavan tiedoston vierestä, polusta <exe-dir>/Plugins/. Sisäänrakennetut liitännäiset (esimerkiksi HelloPython) sijaitsevat täällä.
Käyttäjän — käyttäjäkohtainen ja kirjoitettava. Windowsissa tämä on %LOCALAPPDATA%/MTE/Plugins/, macOS:ssä ~/Library/Application Support/MTE/Plugins/ ja Linuxissa ~/.local/share/MTE/Plugins/.

Molemmat hakemistot käydään läpi. Jos sama id esiintyy molemmissa, ensimmäinen esiintymä voittaa (mukana tulevat menevät edelle). Käynnistä editori uudelleen poimiaksesi uudet kansiot — kuumaa uudelleenlatausta ei tueta.

Kaksi hyväksyttävää rakennetta¶

Läpikäynti etsii tiedostoa plugin.json joko suoraan liitännäishakemistosta (irrallaan) tai yhden tason välittömän alihakemiston sisältä (liitännäiskohtainen kansio):

Plugins/
├── plugin.json         # loose -- one plugin at the top level
├── main.py
└── hello/              # per-plugin folder -- one plugin
    ├── plugin.json
    └── main.py

Liitännäiskohtainen kansio on suositeltu rakenne; se on se muoto, jonka asennusohjelma tuottaa.

Riippuvuudet (`pyRequires`)¶

plugin.json voi ilmoittaa pip-vaatimukset upotettuna taulukkona:

"pyRequires": ["requests>=2.31"]

Liitännäisen ensimmäisellä käynnistyksellä editori valmistelee virtuaaliympäristön polkuun <AppLocalData>/PluginVenv/<id>/ (python -m venv sekä pip install, mikä vaatii verkkoyhteyden tuon yhden kerran) ja ajaa liitännäisen työntekijän tuon virtuaaliympäristön tulkin alla. Seuraavat käynnistykset käyttävät sitä uudelleen; kentän pyRequires muuttaminen valmistelee sen uudelleen automaattisesti (virtuaaliympäristö kantaa leimaa niistä vaatimuksista, joita varten se rakennettiin).

Valmistelun epäonnistumiset (ei verkkoa, kirjoitusvirhe vaatimuksessa) jättävät liitännäisen luetelluksi muttei ladatuksi, pip-virhe lokissa; seuraava käynnistys yrittää uudelleen.
Liitännäisen poistaminen poistaa sen virtuaaliympäristön liitännäiskansion mukana (virtuaaliympäristö on johdettua dataa — se rakennetaan uudelleen kentästä pyRequires, jos koskaan asennat uudelleen).

Verkottomat tai tiukasti rajoitetut koneet¶

Toimita valmiiksi rakennettu virtuaaliympäristö paketin sisällä venv/-kansiona liitännäisen juuressa. Kun se on läsnä, se voittaa kaiken muun — pipiä ei koskaan ajeta. Rakenna se koneella, jolla on sama käyttöjärjestelmä ja arkkitehtuuri, koska virtuaaliympäristöt eivät ole siirrettäviä alustojen välillä.

Riippuvuuksien liittäminen mukaan (pienet puhtaat Python-riippuvuudet)¶

Yhden puhtaan Python-moduulin osalta sen liittäminen liitännäiskansioon toimii edelleen ja välttää virtuaaliympäristökoneiston kokonaan:

# main.py
import os, sys
sys.path.insert(0, os.path.join(os.path.dirname(__file__), "vendor"))

import your_dep

Ilmoitetut oikeudet¶

plugin.json voi kantaa permissions-taulukkoa (esimerkiksi ["network"]). Liitännäisten asetussivu näyttää sen vain luettavassa Käyttöoikeudet-sarakkeessa, jotta käyttäjät näkevät, mitä liitännäinen ilmoittaa itsestään. Se on ilmoitus eikä pakotus — hiekkalaatikointi on tulevaa työtä.

Mihin kirjoitettava data menee¶

Liitännäishakemisto sisältää koodin. Ajonaikainen data (välimuistit, käyttäjäkohtainen kokoonpano, hakemistot) menee erilliseen liitännäiskohtaiseen datahakemistoon, jota isäntä hallinnoi — ctx.data_dir() palauttaa sen absoluuttisen polun. Älä kirjoita liitännäishakemistoon .py-tiedostostasi ajon aikana; poisto poistaa koko <Plugins>/<id>/-kansion, eikä muualle liitännäispuuhun tehtyjä kirjoituksia koskaan siivota.

Toimittaminen muille koneille¶

Toimita .mteplugin-tiedosto — se on itsenäinen ja tarkistetaan vastaanottavassa päässä. Kansion zip, tarball tai git-kloonaus käyttäjäkohtaiseen liitännäishakemistoon toimii myös.

Käyttöönotto ja käytöstä poisto¶

Liitännäisten asetussivu luettelee jokaisen löydetyn liitännäisen (natiivit ja Python-liitännäiset yhdessä) samoilla alkuperä- ja tilasarakkeilla. Liitännäisen poistaminen käytöstä pitää sen luettelossa mutta estää sen tehtaan kutsumisen käynnistyksessä — mitään työntekijää ei käynnistetä. Ota se takaisin käyttöön ja käynnistä uudelleen tuodaksesi sen takaisin.