Skládání nástěnek

Karty v jedné dávce

Agent skládá jedním nástrojem, compose_board, jednu dávku na ucelený celek — sekci, přehled, srovnání — protože umístění i dráty se počítají per dávka; jediná karta je dávka o jedné. Dávka nese až šedesát karet, dráty mezi nimi a otázky, které chce nechat ukotvené ke kartě. Volání je všechno, nebo nic — při 400 chyba pojmenuje provinilou kartu indexem a nic se neumístilo — a poslední dávku jde vrátit jedním požadavkem, což je také jediné, čeho se undo agenta kdy dotkne; uživatelovo ⌘Z práci agenta nikdy nevrací.

{
  "board": "checkout-review",
  "layout": "row",
  "section": "Pass 3",
  "cards": [
    { "ref": "summary", "kind": "prose", "payload": { "md": "Discount applied twice on the cart step." } },
    { "ref": "table", "kind": "table", "payload": { "cols": [{ "key": "step", "label": "Step" }, { "key": "expected", "label": "Expected" }, { "key": "actual", "label": "Actual" }], "rows": [{ "step": "Cart", "expected": "-10%", "actual": "-20%" }] } }
  ],
  "edges": [ { "from": "summary", "to": "table" } ]
}

POST /api/v1/boards/checkout-review/undo

Bezpečné opakování

Každé logické operaci compose_board nebo update_cards přidělte unikátní requestKey (1–128 viditelných znaků ASCII). Přes HTTP lze stejnou hodnotu poslat v hlavičce Idempotency-Key. Stejný požadavek vrátí původní potvrzení bez dalšího vytváření či úprav, i po pozdějších změnách nebo restartu serveru. Použití stejného klíče s jiným vstupem vrátí 409. Klíč patří ověřené identitě, nástěnce a operaci; nová operace potřebuje nový klíč. Šablona použije podobu z prvního úspěšného zápisu. Neplatné dávkové úpravy se vrátí zpět celé.

Umístění vlastní server

Nic ve volání compose není souřadnice. Agent vyjádří záměr — layout (column, row, grid), anchor {cardId | ref, relation} na úrovni dávky nebo per karta (vlastní kotva karty přebíjí kotvu dávky a smí mířit na ref z téhož volání), section, do které má přistát, journey nebo pass, které má rozšířit — a server ho vyhodnotí. after a before vkládají v pořadí čtení uvnitř kontejneru kotvy, under je podpůrná řada pod ní (after uvnitř spravovaného rozložení), beside je soused vpravo, into připojí na konec rámu; potvrzení hlásí placedAs a container a nesplnitelný vztah je 400 relation_unsupported, kdy se nic neumístí. Neukotvené dávky se rozkládají jako řady na polici. Později arrange přerozloží rozsah pojmenovaným režimem — mimo jiné column, row, grid, flow, lanes, timeline, compare, journey (strom zleva doprava řízený dráty nástěnky) a graph (strom dokumentů shora dolů řízený jejich dráty ref); na neznámý režim server odpoví celým seznamem — a se save to rozložení uloží na sekci, takže ho server dál přeskládává, jak karty přibývají.

Pole children určuje pořadí obsahu uvnitř rámce nezávisle na pořadí definic v poli cards. Rodič a pořadí se ukládají nezávisle na naměřených rozměrech a vracejí se jako placement: {parentId, order}; rodič 0 označuje kořen. Nové rámce mají průběžně udržovanou dvousloupcovou mřížku, i když jsou zatím prázdné. payload.layout: null ponechá ruční umístění. payload.layout na rámci zachovává uspořádání do řádku, sloupce nebo mřížky při změnách obsahu. Parametr layout na úrovni celé dávky určuje její počáteční umístění.

Přečíst, upravit, odebrat

Potvrzení dokazuje umístění, ne čitelnost: nástěnku si přečtěte zpátky přes scrape_board — jeden výtah karet s jejich sekcí, adresami médií, poznámkami, anotacemi, řetězy cest a otázkami; section vybere jeden rám — a řekněte, co jste nezkontrolovali. Element v AI vrstvě upravíte odkazem: read_element {id} vrátí osnovu s revizí a cestami JSON Pointer a edit_element {id, revision, edits} změní jen tyto cesty; 409 znamená přečíst znovu, nikdy slepě opakovat. update_cards upravuje vaše vlastní karty a rámy v AI vrstvě a je jedinými dveřmi pro odebrání. Odebrání je měkké — obnovitelné 30 dní: vlastní karty vyhodíte do koše volně, až 25 na volání a 30 % nástěnky; cizí karty nebo větší dávka odpoví 409 needs_confirm — zopakujte stejná id s tokenem a důvodem. Ze shellu jsou tytéž dveře vitrinka board cards rm <board> <ids> --why "…" — nástěnky.

Jeden slovník, generovaný

kind každé karty je uzavřený slovník generovaný z registru serveru: druhy karet nástěnky (text, note, shape, callout, checklist, cluster, section, step, compare, doc, link, board, diagram, api, page, artifact, chat) plus každý druh elementu. Tentýž seznam hlídá REST dveře, dveře elementů i schéma compose_board, takže obsah, který se složí na jedné instalaci, se složí na každé instalaci téže verze. Je vykreslený do reference elementů a živě ho servíruje nástroj docs.

Nejdřív si přečtěte nástroj docs

MCP nástroj docs — a vitrinka docs [topic] z terminálu — je sjednocená reference téhle instalace, vrstvená kvůli úspoře tokenů: bez tématu vrátí kompaktní index každého druhu a průvodce; jedno téma vrátí jen tu stránku, s tvarem obsahu, příkladem a záludnostmi. Průvodci nástěnkou jsou composing, organization, sections, uploads, recall, annotation, review, brief, tasks a project-transfer; postupy, kterými se řídí skilly, jsou guide:listening, guide:publish-capture, guide:brainstorm-flow a guide:sessions-pipeline; kind:<kind> odpoví na druh generického slovesa; holé jméno druhu odpoví kontraktem elementu; stránky komponent kitu jsou artifact:<name>.

vitrinka docs                 # index
vitrinka docs composing       # rozložení, rámy, šablony, otázky
vitrinka docs table           # kontrakt jednoho elementu

Dokumenty se vnořují přes refy

Dokument se skládá z elementů. Element ref, například { "kind": "ref", "payload": { "card": 812, "mode": "preview" } }, vloží jinou kartu, její náhled nebo odkaz (v odesílaném doc.json se tentýž blok píše naplocho a místo karty může jmenovat sesterskou page nebo section uvnitř dokumentu). Server propojí dokumenty vazbami ref; příkaz arrange v režimu graph z nich sestaví strom a samostatné zobrazení je využije pro osnovu. Při publikování vitrinka board push vytvoří stránky jako samostatné karty a převede odkazy page: na jejich ID — viz sady.

Společné vykreslování

Elementy používají společné vykreslování na nástěnce, v publikovaném dokumentu i samostatně na /a/<id>. Pro snímek nebo tisk parametr ?press=1 odstraní vnitřní posouvání a ovládání zobrazované při najetí myší a načte média rovnou. ?theme= přepíše uloženou předvolbu motivu. Toto zobrazení používá služba pro pořizování snímků a tentýž vykreslovač krmí i exporty: GET /api/v1/boards/{slug}/cards/{id}.pdf, .eml (koncept e-mailu s vloženými obrázky) a .docx, k tomu HTML z prohlížeče dokumentu. Element označený publikem audience — public, technical, internal — se zobrazí jen těmto čtenářům a ?audience= stejně ořízne každý export.

Šablony

get_templates vypíše vestavěné kostry — QA session, review iterace, mapa rozhodnutí, dashboard metrik, prezentace, třídění nálezů, návrh UI, mapa architektury, datový příběh, sada testovacích cest, stránka, importéry, dokumentační nástěnka, důkaz z chatu — a šablony z registru uložené přes save_template (nástroj modulu rare) — buď tělo ve tvaru compose se zástupnými {{slot}}, nebo živou sekci vytaženou jako kostru. compose_board s template a params jednu instanciuje a doporučený první tah na nové nástěnce je seznam jednou načíst a vyjít z odpovídající šablony.

Otázky a review

Volání compose může nechat otázky ukotvené ke kartám (ask_board se zeptá samostatně). Člověk odpovídá na nástěnce — na brainstormové nástěnce v brainstormovém studiu — a odpovědi zůstanou odložené, dokud nestiskne ↑ Send; pak dorazí jako položky s volbou na wait_for_work; get {kind: "questions", board} je trvalý záznam. AI review pass na serveru je review_judge (nástroj modulu rare): soudce a nezávislý auditor vytvoří rozsudky připnuté k verzi, které čtete přes review_judgments, a nic se na nástěnku automaticky nezaloží — založení rozsudku je výslovný krok, o kterém rozhoduje člověk. request_review zůstává jen jako kompatibilní název. highlight nakreslí na snímku anotace živý obdélník, který ukáže, co agent skutečně myslí.