MintOffice — tehnika¶

Tehniline lisa MintOffice'i operaatorijuhendile. Operaatorijuhend viib Sind läbi töölaua liitumisvormi; see lehekülg katab arendaja vaate: milliseid hoidlaid Sa forgid, mida igaüks neist juhib ja kuidas Sinu kliendi "Osta"-klõps lõpuks Sinu enda domeenil töötava agendina maandub.

agent-template partner-portal-example Brand Partner API juhend

Kuidas tükid kokku passivad¶

Valgemärgistusega (white-label) MintOffice'i seadistus on kolm kihti, mille omanikuks on kolm erinevat osapoolt:

┌──────────────────────────┐   ┌──────────────────────────┐   ┌──────────────────────────┐
│  Sinu pood (storefront)  │   │  MintOffice (kesksed     │   │  Iga kliendi agent       │
│  (partner-portal-*)      │──▶│  teenused)               │──▶│  agent1.sinubrand.com    │
│  sinubrand.com           │   │  mint.mintbot.ai         │   │  (üks VPS kliendi kohta) │
└──────────────────────────┘   │  + deploy worker         │   └──────────────────────────┘
                               └──────────────────────────┘
   Sina hostid                    mintbot hostib                 mintbot hostib (agendipõhiselt)

Pood (storefront) — Sinu kliendile suunatud veebileht. Näitab paketikaarte, võtab vastu "Osta"-klõpsu, edastab tellimuse MintOffice'ile, võtab vastu webhook-sündmusi. Forgid näidise, brändid selle ümber, hostid oma domeeni all.
MintOffice keskselt — jookseb mint.mintbot.ai peal. Omab Brand Partner API'd, Stripe'i integratsiooni, partneri-põhist saladuste hoidlat (Telegrami boti token, Zone.ee API võti …), deploy worker'it, tulukirjet (revenue ledger). Mintbot peab seda kõikide partnerite jaoks; Sina seda ise kunagi ei jooksuta.
Iga kliendi agent — eraldi VPS, mille deploy worker käivitab, kui tellimus on tasutud. Persona (SOUL.md), paneeli teema ja plugina-kogu tulevad Sinu agendi templeit-i (agent template) hoidlast. Klient suhtleb Sinu Telegrami boti või Sinu apex-domeeni alamdomeenil oleva paneeli kaudu (agent1.sinubrand.com).

Kaks hoidlat, mida forgid¶

White-label brändimine elab kahes eraldi hoidlas, igaüks neist omas vastutusalas. Forgid neid sõltumatult, sellise tempoga, mis Sinu brändile sobib.

1. Agent template — milline iga kliendi agent välja näeb¶

Agent template juhib persona't, mida agent kasutab, brauseris nähtavat paneeli teemat (CSS/JS) ja kaasapakitavat Hermesi pluginate kogu. Iga deploy kloonib Sinu forgi default branchi värske koopia, niiet kui Sa tõukad brändimuudatuse, saab järgmine ostja selle kohe; olemasolevad agendid jäävad nende deploy aegse hetkepildi peale.


Näidishoidla	`mintbot-ai/agent-template` — ametlik, MIT-litsentsiga templeit. Kaasas näidisbränd nimega ExampleAI, et iga Jinja muutuja oleks kontekstis nähtav.
Päris-näide (fork)	`mintbot-ai/agent99-template` — templeit, mida `agent99.cc` päriselt produktsioonis kasutab. Töötav näidisfork: persona ümber nimetatud Agent99-ks, teemapalett kokku viidud poega.
MintOffice'iga ühendatud	Töölaud → Settings → Template → kleebi oma forgi HTTPS-URL. Deploy worker jookseb iga kliendi deploy ajal `git clone`.
Turvavõrk	Serveripoolne kontroll iga deploy ajal: persona suuruse lagi (48 KB), chat-template'i rolli-markerite keeld (`<\\|system\\|>`, …), HTML-kommentaaride keeld (`<!-- -->`). Vaenulik või katkine fork langeb tagasi kaasapakitud persona peale, nii et kliendi agent ei saa mürgitatud.

Templeit pakub kahetasandilist mudelit, et saaksid valida pingutuse taseme:

Hääle ülekirje (persona/brand_layer.md) — lühike tekst, mis lisatakse kaasapakitud mintboti persona lõppu. Odav; ülejäänud persona jääb upstream'i värskenduste teele.
Täielik ülekirje (persona/system_prompt.md.j2) — asendab kaasapakitud persona täielikult. Jinja-renderdatud agent_id, panel_domain_base ja bot_handle muutujatega, niiet saad jooksvaid agendi-fakte prompti sisse panna. Kasuta seda, kui "hääle ülekirjest" jääb väheseks — Agent99 fork läheb just seda teed.

Mõlemad failid võivad korraga olemas olla; render kasutab täielikku ülekirjet kui see on, ja muidu hääle-ülekirjet. Täielikku paigutust — theme/theme.css, theme/theme.js, persona/system_prompt.md.j2, persona/brand_layer.md — kirjeldab agent-template README.

2. Pood (storefront) — mida klient näeb enne ostmist¶

Pood on veebileht, kuhu klient maandub, sirvib pakette, klõpsab Osta, suunatakse Stripe'i ja tuleb tagasi tänulehele. Lisaks võtab see vastu MintOffice'i webhook-deliveryd, niiet Sinu enda süsteemid saavad teada, millal tellimus on tasutud, millal agent valmis on, millal aegub.


Näidishoidla	`mintbot-ai/partner-portal-example` — MIT-litsentsiga FastAPI + SQLite, Docker'iseeritud, kaasas näidisbränd ExampleAI, mida vahetad oma vastu. Sisaldab maandumislehte, `/buy` vormi, tänu- ja tühistamislehti, allkirjastatud webhook'i vastuvõtjat, HTTP-Basic-auth'iga `/admin` sündmuste sirvijat.
Päris-näide (fork)	`mintbot-ai/partner-portal-agent99` — pood, mis päriselt `agent99.cc` peal jookseb. Sama kood, bränd vahetatud Agent99-ks, palett kokku viidud agent template'iga.
MintOffice'iga ühendatud	Töölaud → Settings → API access → sea Webhook URL'i väärtuseks `https://<sinu-host>/webhooks/mintoffice` ja kopeeri signing secret poe `.env` faili.
Sina hostid	Kuskil HTTPS-iga — Sinu enda VPS, serverless platvorm, või Sinu ühe kliendi agendi kõrval. Mintbot poodi ise ei hosti.

Näidispood on väike (mõnisada rida FastAPI-d) ja README läbib brändivahetuse kõik kontaktpunktid — .env konfig, CSS muutujad, tekstid, tõlked. Alusta päris-agent99 forgist kui tahad produktsioonilähedasemat baasi; alusta üldnäidisest kui tahad puhtast lehest peale hakata.

Otsast lõpuni deploy voog¶

Mis toimub, kui klient klõpsab Sinu poes Osta:

1. Klient ⟶ POST /buy Sinu poele
                │
                ▼
2. Pood ⟶ POST /api/v1/orders MintOffice'ile (Sinu API võtmega)
                │       tagastab checkout_url
                ▼
3. Klient ⟶ Stripe Checkout (mintboti Stripe konto)
                │
                ▼
4. Stripe webhook ⟶ MintOffice märgib tellimuse tasutuks
                │       firib order.paid webhooki Sinu poele
                │       paneb deploy ülesande järjekorda
                ▼
5. Deploy worker ⟶ käivitab SporeStack'i VPS-i
                ⟶ tõmbab Sinu agent template hoidla
                ⟶ jookseb apply.py (Hermesi konfig, SOUL.md, plugins, paneel)
                ⟶ loob DNS A-kirje Sinu Zone.ee mandaadiga
                ⟶ võtab Let's Encrypt sertifikaadi
                │
                ▼
6. agent.ready webhook ⟶ saadetakse Sinu poele
                       ⟶ branditud käteandmise (handoff) kiri (pigeon@mintbot.ai)
                       ⟶ klient saab avada https://agent1.sinubrand.com

Sammud 2 ja 4 käivad üle Brand Partner API. Sammud 5 ja 6 on täielikult MintOffice'i sees — Sinu pood ei pea teadma, kuidas SporeStack või Let's Encrypt töötavad; ta lihtsalt võtab vastu elutsükli sündmusi.

Brand Partner API¶

MintOffice'i avalik REST-pind, mida Sinu pood (ja iga muu integratsioon Sinu poolt) kasutab, elab eraldi lehel:

Brand Partner API juhend

Kiire mentaalmudel:

Auth — Authorization: Bearer mo_live_…. Üks võti partneri kohta; roteeri Settings → API access alt.
Kirjutused on idempotentsed — iga POST võtab Idempotency-Key päise; sama võtmega korduskatse mängib algse vastuse uuesti.
Lugemised on odavad — GET /api/v1/settings tagastab Sinu täieliku mitte-saladusliku konfiguratsiooni (režiimid, apex-domeen, hinnad, valmidus) Sinu poe või paigaldusagendi tarbeks.
Elutsükkel on webhook-veetud — order.created, order.paid, agent.ready, agent.failed, agent.expired. HMAC-SHA256 allkirjaga, kuni 7 korduskatset.
DNS on proxitud — POST /api/v1/dns/records upsert'ib A-kirje Sinu apex'ile ilma, et Sinu pood kunagi hoiaks upstream-provideri API võtit. MintOffice hoiab Zone.ee mandaadi serveripoolel krüpteeritult ja teeb upstream-päringu Sinu nimel.

Mida omab MintOffice vs. mida omad Sina¶

Kiire viide selle kohta "kus see fakt elab ja kes seda muuta saab":

Fakt / vara	Elab kohas	Sina muudad seda kuidas
Kliendi paketihinnad	MintOffice DB	Töölaud → Settings → Pricing
Agendi persona (SOUL.md)	Sinu agent template hoidla	Tõuka forgi
Paneeli teema (CSS / JS)	Sinu agent template hoidla	Tõuka forgi
Poe tekstid, paigutus, paketikaardid	Sinu poe hoidla	Tõuka ja deploy oma pood uuesti
Kliendile suunatud brändinimi e-kirjades	MintOffice (juhitud `product_name`'iga tellimuse põhiselt, apex on fallback)	Sea `POST /api/v1/orders` peal
Telegrami boti token, Zone.ee API võti	MintOffice'i saladuste hoidla (krüpteeritud)	Töölaud → Settings → Domain / Bot
Stripe API integratsioon	MintOffice (mintboti Stripe konto)	Partner ei saa muuta
Kliendi jooksva agendi seis (SOUL.md, config)	Agendi enda VPS	Agent ise (peale algset seemnestamist)
Tuluregister (revenue ledger)	MintOffice DB	Loetav `GET /api/v1/revenue` kaudu

Agent-VPS-i-esimese (last row) lähenemise mõte: kui agent on deploy'tud, tema omab oma SOUL.md-d ja config.yaml-i. Keskselt seemnestatakse VPS üks kord ja siis jäädakse tagasi — klient võib oma agendile öelda, et muudaks persona, paneks BYOK võtme, vahetaks mudelit — ilma et see puudutaks Sinu template-forki või Sinu poodi.

Kust edasi minna¶

Sa oled operaator, kes seadistab oma partneri konto — alusta MintOffice — ülevaade lehelt. See viib töölaua liitumisvormi läbi samm-sammult.
Sa ehitad integratsiooni — alusta Brand Partner API juhendist, siis klooni partner-portal-example töötava baasina.
Sa brändid agendi enda ümber — klooni agent-template (või Agent99 forgi kui tahad produktsioonilähedasemat lähtekohta), muuda persona/ ja theme/, tõuka, suuna liitumisvorm oma forki peale.
Sa tahad seda kõike töötavalt näha — agent99.cc on otse-toimiv mintbot.dev partner, kes kasutab mõlemat näidisforki otsast lõpuni. Pane sealt testi tellimus, et näha sama voogu, mida Sa ise üles ehitad.