HTTP API: commands

Každý příkaz, který tento repozitář nabízí, z jakéhokoli programu, který jej nabízí: spustitelný soubor v Rustu, shellový nástroj nesoucí životní cyklus úlohy a workflow, která repozitář deklaruje, aby je člověk spouštěl. Složeno ze tří deklarací, které už existují — stromu clap, dodaného registru příkazů a vlastního výpisu runneru workflow — nikdy ze seznamu. Každý příkaz nese, co jeho spuštění mění, co potřebuje, odkud pocházejí hodnoty jeho argumentů a každý povrch, který jej nese, s důvodem, když nějaký nenese.

Vykresleno z docs/generated/openapi.json, který spustitelný soubor generuje ze svého registru schopností a CI jej odmítne, je-li zastaralý. Surový dokument je na /openapi.json; běžící server servíruje stejný dokument na vlastní /openapi.json a Swagger UI na /swagger.

commands

GET /api/v1/command commands.get

Jeden příkaz celý

Jeden příkaz podle kanonické identity: jeho argumenty se zdrojem hodnot každého, co jeho spuštění mění, co potřebuje, odkud pochází a každý povrch, který ho nese — s důvodem, proč ho strojový povrch zadržuje, když ho zadržuje.

query
implementováno
vyžaduje se měření výkonu
cache vypnuta
nástroj MCP majordomus_command

Parametry dotazu

název	typ	povinné	popis	příklady
id	string	ano	Identita, `executable.worktree.status`.	worktree-status: "executable.worktree.status"

Vyzkoušejte

Port je ten, který server zalogoval; 8741 je ten, o který žádá jako první. Hodnoty jsou první příklad operace.

curl -s "http://127.0.0.1:8741/api/v1/command?id=executable.worktree.status"

Testováno v apps/majordomus-cli/tests/http_serve.rs, který přehrává routu s těmito hodnotami proti serveru na skutečném socketu.

Odpovědi

status	tělo	význam
200	CommandNode	Jeden příkaz v plném znění: výsledek.
400	ErrorBody	`invalid_input`: Vstup neodpovídá schématu: parametr špatného typu, neznámý parametr nebo hodnota, kterou schopnost odmítne.
404	ErrorBody	`not_found`: Vstup pojmenovává něco, co repozitář nemá.
500	ErrorBody	`internal`: Schopnost selhala z vlastního důvodu; zpráva ho pojmenovává.
výchozí	ErrorBody	Jakékoli jiné selhání, které transport hlásí: 405 `method_not_allowed` pro jinou metodu na této cestě, 400 `invalid_input` pro tělo, které není objektem JSON.

GET /api/v1/commands commands.list

Každý příkaz, jeden řádek na příkaz

Příkazy, které tento repozitář nabízí, filtrované podle programu, který je spouští, podle toho, co jejich spuštění mění, nebo podle textu. Shrnutí, ne celý graf: dost na výběr příkazu a nikdy tolik, aby klient musel číst každý argument každého příkazu, aby jeden našel.

query
implementováno
vyžaduje se měření výkonu
cache vypnuta
MCP nástroj majordomus_commands
Zdroj MCP {"name": "commands", "uri": "majordomus://commands"}

Parametry dotazu

název	typ	povinné	popis	příklady
původ	string	ne	Pouze příkazy jednoho programu: `executable`, `tool` nebo `workflow`.	one-program: "executable"
účinek	string	ne	Jen příkazy, jejichž účinek je nejvýše tento: `read_only`, `local_mutation`, `repository_mutation`, `network_mutation`, `destructive`.	pouze pro čtení: "read_only"
hledání	string	ne	Jen příkazy, které tomuto textu odpovídají v invokaci, shrnutí, štítcích nebo identitě.

Vyzkoušejte

Port je ten, který server zalogoval; 8741 je ten, o který žádá jako první. Hodnoty jsou první příklad operace.

curl -s "http://127.0.0.1:8741/api/v1/commands?origin=executable&effect=read_only"

Testováno v apps/majordomus-cli/tests/http_serve.rs, který přehrává routu s těmito hodnotami proti serveru na skutečném socketu.

Odpovědi

status	tělo	význam
200	CommandIndex	Každý příkaz, jeden řádek na každý: výsledek.
400	ErrorBody	`invalid_input`: Vstup neodpovídá schématu: parametr špatného typu, neznámý parametr nebo hodnota, kterou schopnost odmítne.
404	ErrorBody	`not_found`: Vstup pojmenovává něco, co repozitář nemá.
500	ErrorBody	`internal`: Schopnost selhala z vlastního důvodu; zpráva ho pojmenovává.
výchozí	ErrorBody	Jakékoli jiné selhání, které transport hlásí: 405 `method_not_allowed` pro jinou metodu na této cestě, 400 `invalid_input` pro tělo, které není objektem JSON.

GET /api/v1/commands/graph commands.graph

Celý graf příkazů

Graf jako jeden dokument, s jeho otiskem a každou diagnostikou, kterou jeho sestavení našlo: duplicitní identita, název receptu, který by převzaly dva příkazy, anotace jmenující příkaz, který už neexistuje. Deterministické — dvě sestavení nad jedním stromem dají stejný dokument — takže klient může cachovat proti otisku.

query
implementováno
vyžaduje se měření výkonu
cache vypnuta
nástroj MCP majordomus_command_graph

Žádné parametry.

Vyzkoušejte

Port je ten, který server zalogoval; 8741 je ten, o který žádá jako první. Hodnoty jsou první příklad operace.

curl -s "http://127.0.0.1:8741/api/v1/commands/graph"

Testováno v apps/majordomus-cli/tests/http_serve.rs, který přehrává routu s těmito hodnotami proti serveru na skutečném socketu.

Odpovědi

status	tělo	význam
200	CommandGraphReport	Celý graf příkazů: výsledek.
400	ErrorBody	`invalid_input`: Vstup neodpovídá schématu: parametr špatného typu, neznámý parametr nebo hodnota, kterou schopnost odmítne.
404	ErrorBody	`not_found`: Vstup pojmenovává něco, co repozitář nemá.
500	ErrorBody	`internal`: Schopnost selhala z vlastního důvodu; zpráva ho pojmenovává.
výchozí	ErrorBody	Jakékoli jiné selhání, které transport hlásí: 405 `method_not_allowed` pro jinou metodu na této cestě, 400 `invalid_input` pro tělo, které není objektem JSON.

Schémata

Komponenty, které používají jen operace tohoto tagu. Každý řádek je pole daného typu, jeho doc komentář je popis; typ vlastněný jinou stránkou na ni odkazuje.

CommandArgument

object

Jeden argument příkazu, jak jej uvádí deklarace plus to, co lze odvodit.

vlastnost	typ	povinné	popis
název	string	ano	ID argumentu.
dlouhé	string \| null	ne	`--long`, bez pomlček.
krátce	string \| null	ne	`-s`, bez pomlčky.
poziční	boolean	ano	Dáno pozicí, ne příznakem.
takes_value	boolean	ano	Vůbec přebírá hodnotu; příznak ne.
povinné	boolean	ano	Musí být zadáno.
variadic	boolean	ano	Bere libovolný počet hodnot.
globální	boolean	ano	Přijímá každý příkaz pod tím, který ji deklaruje.
nápověda	string	ano	Text nápovědy, jeden řádek.
value_name	string \| null	ne	Zástupný symbol, `PATH`.
hodnoty	pole CommandValueChoice → CommandValueChoice	ne	Hodnoty, které deklarace nese, každá se svou nápovědou.
výchozí hodnoty	array of string	ne	Výchozí hodnoty tak, jak je deklarace vykresluje.
zdroj	CommandValueSource → CommandValueSource	ano	Odkud pocházejí další hodnoty.
utajení	CommandSecrecy → CommandSecrecy	ano	Jak otevřeně lze s hodnotou nakládat.

Používá CommandNode

CommandAvailability

object

Kde příkaz něco znamená a proč ne, když neznamená.

Odvozeno z prostředí repozitáře, ne deklarováno u každého příkazu, aby projekce četla pole místo opětovného rozhodování. Důvod se nese, protože odpověď, kterou člověk potřebuje, nikdy není false.

vlastnost	typ	povinné	popis
dostupné	boolean	ano	Dá se to spustit tady a teď?
důvod	string \| null	ne	Proč ne, v jednom řádku, když nelze.
vyžaduje	pole CommandRequirement → CommandRequirement	ne	Co potřebuje, ať je to zde splněno, nebo ne.

Používá CommandNode

CommandDeprecation

object

Příkaz, který už není názvem k použití.

vlastnost	typ	povinné	popis
důvod	string	ano	Proč, na jednom řádku.
replaced_by	CommandId \| null → CommandId	ne	Co použít místo toho.

Používá CommandNode

CommandDiagnostic

object

Jedna věc, kterou sestavení našlo.

vlastnost	typ	povinné	popis
závažnost	CommandDiagnosticSeverity → CommandDiagnosticSeverity	ano	Jak závažné.
kód	string	ano	Stabilní kód, na který může kontrola reagovat.
zpráva	string	ano	Co je špatně, jedním řádkem.
commands	pole CommandId → CommandId	ne	Uzly, kterých se týká.
náprava	string \| null	ne	Co s tím dělat.

Používá CommandGraph

CommandDiagnosticSeverity

"error" | "warning" | "info"

Jak závažné zjištění je.

errorGraf je špatně a projekce z něj sestavená by byla špatně.
warningStojí za řeč; graf platí.
infoFakt, který může čtenář chtít.

Používá CommandDiagnostic

CommandEffect

"read_only" | "local_mutation" | "repository_mutation" | "network_mutation" | "destructive"

Co spuštění příkazu mění. Jediné, na co se smí politika povrchu ptát.

Pořadí je pořadí rostoucího dopadu a je to pořadí, které čte odvozená politika vystavení: povrch deklaruje nejsilnější účinek, který ponese, a každý uzel na této úrovni nebo pod ní je tam promítnut. Nic nenastavuje povrch na příkaz.

read_onlyČte a odpovídá. Nikde nic nemění.
local_mutationZapisuje jen tam, kde repozitář drží vlastní stav checkoutu — paměť procesu, .ai/local/, build adresář. Nic, co by commit nesl.
repository_mutationZapisuje sledované soubory: generované artefakty, worktree, samotný git.
network_mutationSahá do sítě s účinkem na druhé straně: push, nasazení, release.
destructiveOdstraní něco, co by musel člověk rekonstruovat.

Používá CommandNode

CommandExecution

object

Jak se příkaz skutečně spouští: program a slova před vlastními slovy volajícího.

Tohle zakazuje cyklus. Projekce vykresluje vyvolání z popisu provedení, takže generovaný most vždy vyslovuje kanonický program — nikdy povrch, jehož je mostem.

vlastnost	typ	povinné	popis
původ	CommandOrigin → CommandOrigin	ano	Který program.
argv	array of string	ano	Slova, která předcházejí argumentům volajícího, bez vlastního jména programu.

Používá CommandNode

CommandGraph

object

Celý graf.

vlastnost	typ	povinné	popis
schema	string	ano	Schéma tohoto dokumentu.
otisk	string	ano	Hash sémantického obsahu: identita, podle které se klíčuje cache a generovaná projekce. Nic, co se mezi dvěma běhy nad stejným stromem liší, v něm není.
commands	pole CommandNode → CommandNode	ano	Každý příkaz v deterministickém pořadí: původ, pak cesta.
diagnostika	pole CommandDiagnostic → CommandDiagnostic	ano	Co build našel.

Používá CommandGraphReport

CommandGraphReport

object

Celý graf s tím, co zjistilo jeho sestavení.

vlastnost	typ	povinné	popis
graph	CommandGraph → CommandGraph	ano	Graf.
chyby	integer (uint)	ano	Kolik nálezů jsou chyby; projekce odmítá zapisovat, dokud toto není nula.

Používá commands.graph

CommandId

string

Kanonická identita jednoho příkazu.

Sestavuje se z původu a cesty příkazu, nikdy se nepíše ručně, aby jej projekce nemohla vymyslet a přejmenování zobrazovaného řetězce jej nemohlo změnit.

Používá CommandDeprecation CommandDiagnostic CommandNode

CommandIndex

object

Příkazy, které tento repozitář nabízí, filtrované.

vlastnost	typ	povinné	popis
schema	string	ano	Schéma grafu, z něhož toto pochází.
otisk	string	ano	Otisk toho grafu: klient se proti němu může cachovat.
celkem	integer (uint)	ano	Kolik příkazů graf obsahuje, před filtrem.
commands	pole CommandSummary → CommandSummary	ano	Příkazy, které odpovídaly, v pořadí grafu.

Používá commands.list

CommandInteractivity

"non_interactive" | "interactive" | "long_running"

Jak se příkaz chová k terminálu volajícího a k trpělivosti volajícího.

non_interactiveBěží, odpovídá, skončí. Bezpečné volat ze strojové plochy.
interactivePtá se člověka na něco, nebo čte tělo záznamu z terminálu. Strojová plocha, která by to nabízela, by se zasekla.
long_runningObsluhuje, dokud není zastaven. Povrch požadavek/odpověď to unést nemůže.

Používá CommandNode

CommandNode

object

Jeden příkaz, z kteréhokoli programu, který jej nabízí.

vlastnost	typ	povinné	popis
id	CommandId → CommandId	ano	Kanonická identita.
původ	CommandOrigin → CommandOrigin	ano	Který program to spouští.
path	array of string	ano	Slova za vlastním jménem programu.
vyvolání	string	ano	Příkazová řádka, kterou člověk píše, zde vykreslená jednou.
summary	string	ano	Jedna řádka.
popis	string \| null	ne	Delší popis, když ho deklarace nese.
spustitelné	boolean	ano	Dá se spustit samostatně, nebo jen seskupuje příkazy pod sebou?
argumenty	pole CommandArgument → CommandArgument	ano	Argumenty v pořadí deklarace.
provádění	CommandExecution → CommandExecution	ano	Jak se spouští.
účinek	CommandEffect → CommandEffect	ano	Co mění.
interaktivita	CommandInteractivity → CommandInteractivity	ano	Jak se chová vůči terminálu.
stabilita	Stability → Stability	ano	Jak to stojí.
dostupnost	CommandAvailability → CommandAvailability	ano	Kde to něco znamená.
group	string \| null	ne	Skupina, pod kterou ji člověk najde, když deklarace skupiny má.
štítky	array of string	ne	Volné štítky.
aliasy	array of string	ne	Další názvy, které se vyhodnotí na tento uzel, deklarované jednou zde a respektované každou projekcí, která pro ně má využití.
zastarání	CommandDeprecation \| null → CommandDeprecation	ne	Zda je toto stále název, který se má používat.
provenance	CommandProvenance → CommandProvenance	ano	Odkud pochází.
projections	CommandProjections → CommandProjections	ano	Kde se objevuje.
vstupní bod	boolean \| null	ne	Je tento příkaz vstupním bodem své skupiny — tím, který se nabízí nováčkovi?

Používá commands.get CommandGraph

CommandOrigin

"executable" | "tool" | "workflow"

Který program příkaz spouští. Součást identity, protože tři jsou různé programy, které sdílejí jedno jméno na cestě.

executableSpustitelný soubor v Rustu, apps/majordomus-cli: rozhraní jen pro čtení, generování, introspekce, servery. Deklarováno clap.
toolShellový nástroj bin/majordomus: životní cyklus úlohy. Deklarovaný dodaným registrem příkazů a odbavovaný samotným nástrojem.
workflowWorkflow, které repozitář deklaruje pro spuštění člověkem — recept just, který není vygenerovaným mostem. Deklarováno justfile a čteno z výpisu běžce.

Používá CommandExecution CommandNode

CommandProjections

object

Kde se jeden příkaz objevuje, odvozeno z jeho efektu, interaktivity a původu.

Každé pole počítá super::policy. Nic nedeklaruje projekci a žádná plocha nedrží seznam toho, co nese: plocha se ptá grafu.

vlastnost	typ	povinné	popis
cli	string \| null	ne	Příkazová řádka tak, jak se píše.
workflow	string \| null	ne	Název receptu vygenerovaného můstku workflow.
mcp	string \| null	ne	Název nástroje MCP, když jej schopnost za ním deklaruje.
http	string \| null	ne	Trasa HTTP, pokud ji schopnost za ní deklaruje.
cockpit	string \| null	ne	Adresa Cockpitu, pokud ji povrch nese.
dokumentace	string	ano	Stránka na webu. Má ji každý příkaz.
zadrženo	string \| null	ne	Proč jej strojový povrch nenese, když jej nenese.

Používá CommandNode CommandSummary

CommandProvenance

object

Odkud uzel pochází, dost podrobně na otevření souboru.

vlastnost	typ	povinné	popis
declared_in	string	ano	Soubor relativně k repozitáři, který ji deklaruje.
read_by	string \| null	ne	Příkaz, který tu deklaraci čte, když ji chce čtenář reprodukovat.
schopnost	CapabilityId \| null → CapabilityId	ne	Schopnost, kterou tento příkaz spouští, pokud nějakou spouští.

Používá CommandNode

CommandRequirement

Jedna věc, kterou příkaz potřebuje, než může běžet.

repositoryRepozitář git.
layerVrstva .ai/, inicializovaná.
taskAktivní záznam úlohy.
executableSpustitelný soubor Rustu, sestavený.
workflow_runnerRunner workflow, nainstalován.
rust_toolchainCargo workspace a toolchain pro jeho sestavení.
siteZdroje webu a jeho generátor.

Používá CommandAvailability

CommandSecrecy

"public" | "sensitive" | "secret"

Jak otevřeně lze s hodnotou nakládat.

publicBěžné: smí se logovat, doplňovat a zobrazovat.
sensitiveCesta nebo identifikátor, který jmenuje něco soukromého. Zobrazuje se, nikdy se nelogují.
secretPřihlašovací údaj. Nikdy se nedoplňuje, neloguje ani necachuje.

Používá CommandArgument

CommandSummary

object

Jeden příkaz tak, jak ho ukazuje index: dost na výběr, nikdy dost na to, aby se muselo přelétávat.

vlastnost	typ	povinné	popis
id	string	ano	Kanonická identita.
vyvolání	string	ano	Příkazová řádka, kterou člověk píše.
summary	string	ano	Jedna řádka.
původ	string	ano	Který program to spouští.
účinek	string	ano	Co spuštění mění.
group	string \| null	ne	Skupina, pod níž se nachází.
projections	CommandProjections → CommandProjections	ano	Kde se objevuje.

Používá CommandIndex

CommandValueChoice

object

Jedna hodnota, kterou argument přijímá, z deklarace.

vlastnost	typ	povinné	popis
hodnota	string	ano	Hodnota tak, jak byla zadána.
popis	string \| null	ne	Jeho nápověda, pokud ji deklarace nese.

Používá CommandArgument

CommandValueSource

jedna ze 13 variant

Odkud pochází hodnota argumentu, když množinu zná něco v tomto repozitáři.

Toto je kontrakt doplňování a je vlastností argumentu, ne shellového skriptu: tentýž zdroj odpovídá na TAB shellu, na výběr generovaného formuláře i na výčet toho, co strojový povrch přijme. Odvození z deklarace jde první — argument typu value-enum nese vlastní hodnoty, zástupný symbol PATH je cesta — a jen to, co odvodit nelze, se anotuje vedle příkazu.

varianta Nic zde množinu nezná; volající zadá hodnotu.

druh

"free"

ano

varianta Deklarace nese hodnoty; jsou na argumentu.

druh

"enumerated"

ano

varianta Cesta v souborovém systému.

druh

"path"

ano

variant Cesta uvnitř repozitáře.

druh

"repository_path"

ano

variant Id schopnosti z registru.

druh

"capability"

ano

varianta Id příkazu z tohoto grafu.

druh

"command"

ano

variant ID pravidla z účinné sady pravidel.

druh

"rule"

ano

variant Druh objektu z indexu.

druh

"object_kind"

ano

varianta Git větev v tomto repozitáři.

druh

"branch"

ano

variant Id grafu z registru grafů.

druh

"graph"

ano

varianta Id momentu z katalogu why.

druh

"moment"

ano

variant Název shellu z těch, které aktivace podporuje.

druh

"shell"

ano

varianta Tajemství. Nikdy se nevypisuje, necachuje ani nenavrhuje.

druh

"secret"

ano

Používá CommandArgument