ÇĻÎ çöñṽéñţîöñš
Éṽéŕý ķàþî çöḿḿàñđ àñšŵéŕš ţĥé šàḿé ƒöüŕ ǫüéšţîöñš ţĥé šàḿé ŵàý: ĥöŵ îţ ţàķéš
îñþüţ, ĥöŵ îţ éḿîţš öüţþüţ, ŵĥàţ îţš éẋîţ çöđé ḿéàñš, àñđ ŵĥàţ îţ đöéš îñšîđé à
þŕöĵéçţ. Ţéšţš éñƒöŕçé ţĥéšé çöñţŕàçţš
(cli/conventions_test.go, host/inputs_test.go), šö à ñéŵ çöḿḿàñđ ţĥàţ
ƃŕéàķš öñé ƒàîļš ţĥé ƃüîļđ.
1. Îñþüţ
Öñé ŕéšöļṽéŕ, host.App.ResolveInputs (host/inputs.go), ƃàçķš éṽéŕý çöḿḿàñđ
ţĥàţ ţàķéš ƒîļé îñþüţš. Ţĥŕéé ŕüļéš:
Ĝļöƃš éẋþàñđ îñ-þŕöçéšš. kapi stats 'src/**' ƃéĥàṽéš îđéñţîçàļļý öñ žšĥ,
ƃàšĥ àñđ ÞöŵéŕŠĥéļļ, àñđ ŵĥéţĥéŕ öŕ ñöţ ţĥé šĥéļļ éẋþàñđéđ ţĥé þàţţéŕñ ƒîŕšţ; à
šĥéļļ-éẋþàñđéđ ļîšţ öƒ çöñçŕéţé þàţĥš îš ĵüšţ ţĥé ŕéšöļṽéđ ƒöŕḿ öƒ ţĥé šàḿé
îñþüţ. Éẋþàñšîöñ üšéš đöüƃļéšţàŕ, šö ** îš ŕéçüŕšîṽé (ŵĥîçĥ filepath.Glob
çàññöţ éẋþŕéšš) àñđ {a,b} àļţéŕñàţéš. À ŵîļđçàŕđ ñéṽéŕ đéšçéñđš îñţö à
đöţ-đîŕéçţöŕý; ñàḿîñĝ öñé (.github/**/*.yml) öþţš ƃàçķ îñ.
Đîŕéçţöŕîéš àŕé çöñţéñţ, ñöţ éŕŕöŕš. À đîŕéçţöŕý àŕĝüḿéñţ éẋþàñđš ţö ţĥé
ŕéĝüļàŕ ƒîļéš ƃéñéàţĥ îţ, šķîþþîñĝ ĥîđđéñ đîŕéçţöŕîéš àñđ éđîţöŕ ĵüñķ (~$…
Öƒƒîçé ļöçķ ƒîļéš, ._… ÀþþļéĐöüƃļé šţüƃš). Ţĥé ţööļƃöẋ üţîļîţîéš ţĥàţ éḿüļàţé
à Üñîẋ ƒîļţéŕ (kgrep, kcat, ksed) ķééþ ţĥé ÞÖŠÎẊ ŕéǫüîŕéḿéñţ öƒ à
ŕéçüŕšîöñ ƒļàĝ (-r, àñđ -R öñ ksed, ŵĥéŕé šéđ'š -r ḿéàñš éẋţéñđéđ
ŕéĝéẋþš), ƃéçàüšé ţĥéý àŕé đéļîƃéŕàţé éḿüļàţîöñš öƒ ţööļš ŵĥöšé ḿüšçļé ḿéḿöŕý
îñçļüđéš îţ.
Ñö îñþüţ ñéṽéŕ ḿéàñš "ƃļöçķ öñ ţĥé ţéŕḿîñàļ". Ĝîṽéñ ñöţĥîñĝ, à çöñţéñţ ṽéŕƃ
üšéš ţĥé þŕöĵéçţ'š ţŕàçķéđ çöñţéñţ šéţ ŵĥéñ à ŕéçîþé îš îñ šçöþé; öţĥéŕŵîšé îţ
ŕéàđš šţàñđàŕđ îñþüţ öñļý ŵĥéñ šţđîñ îš àçţüàļļý ŕéđîŕéçţéđ. Öñ àñ îñţéŕàçţîṽé
ţéŕḿîñàļ îţ ŕéþöŕţš ĥöŵ ţö ĝîṽé îţ îñþüţ àñđ éẋîţš 2. Šţàñđàŕđ îñþüţ îš àļŵàýš
àṽàîļàƃļé éẋþļîçîţļý àš -.
2. Öüţþüţ
Öñé àẋîš, --output-format, ŵîţĥ ţĥé ṽàļüéš text (àļîàš table), json àñđ
yaml; --json àñđ --text àŕé šĥöŕţĥàñđš, àñđ --jq <expr> îḿþļîéš ĴŠÖÑ.
Ŕéšöļüţîöñ ļîṽéš îñ host/output.ResolveFormat, àñđ éṽéŕý šţŕüçţüŕéđ ŕéšüļţ
ţýþé îḿþļéḿéñţš FormatText ƒöŕ ţĥé ĥüḿàñ ŕéñđéŕîñĝ. text îš à ţàƃļé ƒöŕ
ļîšţîñĝš àñđ à ļàƃéļéđ šüḿḿàŕý ƒöŕ šîñĝļé ŕéçöŕđš.
-o îš ñöţ ţĥé ƒöŕḿàţ ƒļàĝ. Àçŕöšš ţĥé ţŕéé -o ḿéàñš àñ öüţþüţ þàţĥ öŕ
þàţĥ ţéḿþļàţé (kapi extract -o work.kpz, kapi memory export -o memory.tmx,
ţĥé {dir}{name}{ext}{lang} ţéḿþļàţé öñ kapi exec <tool>), àñđ ţĥàţ ḿéàñîñĝ
îš çöñšîšţéñţ, šö ţĥé ƒöŕḿàţ àẋîš ķééþš ţĥé üñàḿƃîĝüöüš ļöñĝ šþéļļîñĝ.
--print-ops îš ţĥé öñé ƒļàĝ ţĥàţ šŵàþš ţĥé ŕéšüļţ ƒöŕ à çĥàñĝé šéţ: öñ
ksed, öñ ţĥé ƒļöŵ ṽéŕƃš (translate, pseudo-translate, run, up), öñ
kapi exec ƒöŕ à ţööļ ţĥàţ ŵŕîţéš, àñđ öñ kapi apply îţšéļƒ, îţ ŵŕîţéš ñö
ƒîļé àñđ þŕîñţš ţĥé ķàþî.çĥàñĝé/ṽ1 çĥàñĝé šéţ ţö šţđöüţ, ŵĥîçĥ kapi apply
àþþļîéš àš þŕîñţéđ.
Þŕöĝŕéšš ƒöŕ àñýţĥîñĝ ţĥàţ çàñ éẋçééđ à šéçöñđ ĝöéš ţö šţđéŕŕ
(host/progressstep.go), šö šţđöüţ šţàýš éẋàçţļý ţĥé ḿàçĥîñé-ŕéàđàƃļé ŕéšüļţ:
kapi stats --output-format json 'src/**' > out.json ŵŕîţéš öñļý ĴŠÖÑ. Îţ šţàýš
šîļéñţ ƃéļöŵ ProgressDelay, îš šüþþŕéššéđ ƃý --quiet, àñđ đéĝŕàđéš ţö þļàîñ
àþþéñđ-öñļý ļîñéš öñ à þîþé.
3. Éẋîţ çöđéš
host/exitcode.go đéƒîñéš ţĥé ŵĥöļé ṽöçàƃüļàŕý; ñö çöḿḿàñđ îñṽéñţš àñöţĥéŕ.
| Çöđé | Ḿéàñîñĝ |
|---|---|
| 0 | šüççéšš |
| 1 | öþéŕàţîöñàļ éŕŕöŕ |
| 2 | üšàĝé éŕŕöŕ: ƃàđ ƒļàĝš, üñŕéàđàƃļé îñþüţ, ñö îñþüţ |
| 3 | ǫüàļîţý ĝàţé üñḿéţ (ErrQualityGate) |
| 4 | à çĥéçķ đîđ ñöţ ŕüñ (ErrCheckNotRun): ñö çöñţéñţ çĥéçķéđ, öŕ àñ àñàļýžéŕ ḿîššéđ îţš çàñàŕý |
| 5 | à ƃàçķéñđ çöüļđ ñöţ ƃé ŕéàçĥéđ (ExitUnreachable): ţĥé çöñţéẋţ ƃàçķéñđ kapi context sync šĥàŕéš ţĥŕöüĝĥ, öŕ à çĥàñĝé šéţ'š ƃàçķéñđ; ñöţĥîñĝ çĥàñĝéđ |
| 130 | îñţéŕŕüþţéđ (ŠÎĜÎÑŢ) |
Ţĥé ĝŕéþ-ƒàḿîļý üţîļîţîéš àđđîţîöñàļļý üšé 1 ƒöŕ "ñö ḿàţçĥ", ŵĥîçĥ îš ţĥéîŕ
ñàḿéšàķéš' çöñţŕàçţ.
4. Þŕöĵéçţ ṽš àđ-ĥöç
ResolveProjectPath îš ţĥé šîñĝļé đîšçöṽéŕý þàţĥ: -p/--project ƒļàĝ →
KAPI_NO_PROJECT öþţ-öüţ → KAPI_PROJECT éñṽ → ĝîţ-šţýļé üþŵàŕđ ŵàļķ ƒöŕ
kapi.yaml. À çöḿḿàñđ îš öñé öƒ:
- þŕöĵéçţ-ŕéǫüîŕéđ (
up,status,ls,add,rm,check --ship): éŕŕöŕš ŵîţĥöüţ à ŕéçîþé; - þŕöĵéçţ-öŕ-ŵöŕķšþàçé (
extract,merge): à þŕöĵéçţ šüþþļîéš ţĥé çöñţéñţ, öŕ à.kpzŵöŕķšþàçé šţàñđš îñ ƒöŕ öñé (extract <sources> -o work.kpz,merge work.kpz -o out/); - þŕöĵéçţ-þŕéƒéŕŕéđ (
check,stats,inspect,translate,pseudo-translate,run): üšéš ţĥé þŕöĵéçţ'š çöñţéñţ ŵĥéñ ĝîṽéñ ñöţĥîñĝ, ŵöŕķš àđ-ĥöç öñ ñàḿéđ ƒîļéš; - àđ-ĥöç (
formats,tools,flows,plugin,models,configšüƃçöḿḿàñđš, ţĥé ţööļƃöẋ): ñö þŕöĵéçţ îñṽöļṽéđ, éẋçéþţ ţĥàţksedŕéàđš à ƒîļé üñđéŕ ţĥé ŕööţ öƒ ţĥé þŕöĵéçţ đîšçöṽéŕý ƒîñđš àškapi applyŕéàđš îţ, šö ţĥé çĥàñĝé šéţ îţ þŕîñţš àþþļîéš àš þŕîñţéđ.
Çöḿḿàñđ šüŕƒàçé
Çöñţéñţ çĥéçķš àñđ ŕéļéàšé ĝàţéš ĥàṽé šéþàŕàţé ŕéšþöñšé šĥàþéš. Öŕđîñàŕý
check éḿîţš kapi.check/v2; check --ship ĝŕöüþš ƒîñđîñĝš üñđéŕ þŕöĵéçţ ĝàţéš.
Ţĥé ŕéļéàšé çĥéçķéŕ ŕéšöļṽéš šöüŕçé-öñļý çöñţéñţ šéþàŕàţéļý ƒŕöḿ šöüŕçé/ţàŕĝéţ
þàîŕš, îñçļüđîñĝ îñ ḿîẋéđ þŕöĵéçţš. Éẋþļîçîţ ƒîļéš ţĥàţ ḿàţçĥ à đéçļàŕéđ ţàŕĝéţ
ŕéţàîñ ţĥàţ þàîŕîñĝ; öţĥéŕ ñàḿéđ ƒîļéš ŕéçéîṽé šöüŕçé çĥéçķš ŵîţĥ ţĥéîŕ đéçļàŕéđ
ŕéàđéŕ çöñƒîĝüŕàţîöñ.
Ţĥé ţéŕḿîñöļöĝý àñđ ŕüļé-ƃàšéđ ŕéļéàšé ĝàţéš îñçļüđé coverage.files àñđ
coverage.blocks, çöüñţîñĝ îñšþéçţéđ çöñţéñţ. Éàçĥ ĝàţé çàŕŕîéš à verdict
(passed, failed öŕ did_not_run) đéçîđéđ ƃý check.Report.Decide: à ĝàţé
ŵîţĥ žéŕö ƃļöçķš, öŕ ŵĥöšé àñàļýžéŕš àļļ ḿîššéđ öŕ ĥàđ ñö çàñàŕý, đîđ ñöţ ŕüñ,
àñđ ţĥé ŕüñ éẋîţš 4 ŵĥàţéṽéŕ --no-fail šàýš. pass îš ţŕüé öñļý ƒöŕ
passed. Šöüŕçé ŕüļé çĥéçķš ŕéţàîñ execution.analyzers, îñçļüđîñĝ üñšüþþöŕţéđ
šéḿàñţîç ĝüîđàñçé, ţĥŕöüĝĥ ţĥé šàḿé šöüŕçé-çĥéçķ îḿþļéḿéñţàţîöñ àš öŕđîñàŕý
check. Ţàŕĝéţ çöṽéŕàĝé àñđ šţàļéñéšš çöñţîñüé ţö üšé àçţüàļ šöüŕçé/ţàŕĝéţ þàîŕš.
| Çöḿḿàñđ | Îñþüţ | Ĝļöƃ / đîŕ | Ƒöŕḿàţ àẋîš | Þŕöĵéçţ | Ñöñ-žéŕö éẋîţš |
|---|---|---|---|---|---|
up | ñöñé | ñöñé | ţéẋţ·ĵšöñ·ýàḿļ | ŕéǫüîŕéđ | 1 |
status | ñöñé | ñöñé | ţéẋţ·ĵšöñ·ýàḿļ | ŕéǫüîŕéđ | ñöñé (àļŵàýš 0) |
check [files…] | þöšîţîöñàļ | ýéš | ţéẋţ·ĵšöñ·ýàḿļ | þŕéƒéŕŕéđ | 3 ĝàţé, 4 đîđ ñöţ ŕüñ, 1 öþ |
check --ship | þöšîţîöñàļ | ýéš | ţéẋţ·ĵšöñ·ýàḿļ | ŕéǫüîŕéđ | 3 ĝàţé, 4 đîđ ñöţ ŕüñ |
stats [files…] | þöšîţîöñàļ, šţđîñ | ýéš | ţéẋţ·ĵšöñ·ýàḿļ | þŕéƒéŕŕéđ | 2 þéŕ-ƒîļé |
inspect [files…] | þöšîţîöñàļ, šţđîñ | ýéš | ţéẋţ·ĵšöñ·ýàḿļ (+--jsonl šţŕéàḿ) | þŕéƒéŕŕéđ | 2 þéŕ-ƒîļé |
translate [files…] | þöšîţîöñàļ, -i | ýéš | ţéẋţ·ĵšöñ·ýàḿļ | þŕéƒéŕŕéđ | 1 |
pseudo-translate [files…] | þöšîţîöñàļ, -i | ýéš | ţéẋţ·ĵšöñ·ýàḿļ | þŕéƒéŕŕéđ | 1 |
run [flow] | -i | ýéš | ţéẋţ·ĵšöñ·ýàḿļ | þŕéƒéŕŕéđ | 1 |
extract | þŕöĵéçţ çöñţéñţ, öŕ þöšîţîöñàļ + -o <kpz> | ýéš | ţéẋţ·ĵšöñ·ýàḿļ | ŕéǫüîŕéđ, öŕ à .kpz ŵöŕķšþàçé | 1 |
merge | -i (ƒîļé, ĝļöƃ, đîŕ), öŕ à .kpz ŵöŕķšþàçé | ýéš | ţéẋţ·ĵšöñ·ýàḿļ | ŕéǫüîŕéđ, öŕ à .kpz ŵöŕķšþàçé | 1 |
apply [changeset] | þöšîţîöñàļ öŕ šţđîñ | ñöñé | ţéẋţ·ĵšöñ·ýàḿļ (--json: ķàþî.çĥàñĝé-ŕéšüļţ/ṽ1; --print-ops: ţĥé çĥàñĝé šéţ) | þŕéƒéŕŕéđ | 2 đöéš ñöţ đéçöđé, 3 ŕéƒüšéđ öŕ þàŕţîàļ, 5 üñŕéàçĥàƃļé |
pack / unpack / info | þöšîţîöñàļ àŕçĥîṽé | ñöñé | ţéẋţ·ĵšöñ·ýàḿļ | þŕéƒéŕŕéđ / ñöñé | 1 |
add / ls / rm | þöšîţîöñàļ þàţţéŕñš | ýéš | ţéẋţ·ĵšöñ·ýàḿļ | ŕéǫüîŕéđ | 1 |
exec <tool> <files…> | þöšîţîöñàļ | ýéš | ţéẋţ·ĵšöñ·ýàḿļ | ḿéḿöŕý + ţéŕḿš ƃöüñđ ƒŕöḿ þŕöĵéçţ | 1 |
kcat / kgrep / kconv | þöšîţîöñàļ, šţđîñ | ĝļöƃš ýéš, đîŕš ñééđ -r | ţéẋţ·ĵšöñ·ýàḿļ | ñöñé | 2; ķĝŕéþ 1 = ñö ḿàţçĥ |
ksed | þöšîţîöñàļ, šţđîñ | ĝļöƃš ýéš, đîŕš ñééđ -R | đöçüḿéñţš (--print-ops: à çĥàñĝé šéţ) | đîšçöṽéŕý: à þŕöĵéçţ'š ƒîļé îš ŕéàđ àš apply ŕéàđš îţ | 2 |
kdiff a [b] | 1–2 þöšîţîöñàļ | ñöñé | ţéẋţ·ĵšöñ·ýàḿļ | ñöñé | 1 đéŕ |
flows / tools / formats | ñöñé | ñöñé | ţéẋţ·ĵšöñ·ýàḿļ | ñöñé | 1 |
plugin … | þöšîţîöñàļ ñàḿé | ñöñé | ţéẋţ·ĵšöñ·ýàḿļ | ñöñé | 1; đöçţöŕ 1 üñĥéàļţĥý |
models … | þöšîţîöñàļ ḿöđéļ | ñöñé | ţéẋţ·ĵšöñ·ýàḿļ | ñöñé | 1 |
memory … / terms … | þöšîţîöñàļ / --name,--local,--file | import-dir ŵàļķš | ţéẋţ·ĵšöñ·ýàḿļ | ŕéšöüŕçé ƒļàĝš | 1 |
voice … | þöšîţîöñàļ / --input-text / šţđîñ | ñöñé | ţéẋţ·ĵšöñ·ýàḿļ | þŕöƒîļé ƒļàĝš | 3 ḿîñ-šçöŕé |
credentials … | þöšîţîöñàļ ñàḿé | ñöñé | ţéẋţ·ĵšöñ·ýàḿļ | ñöñé | 1 |
config … | þöšîţîöñàļ ķéý/ṽàļüé | ñöñé | ţéẋţ·ĵšöñ·ýàḿļ | þöšîţîöñàļ ƒöŕḿ: ŕéǫüîŕéđ | 1 |
version / update / telemetry / completion | ñöñé | ñöñé | ţéẋţ·ĵšöñ·ýàḿļ | ñöñé | 1 |
mcp | þŕöţöçöļ šţŕéàḿš | ñöñé | þŕöţöçöļ | þŕéƒéŕŕéđ | 1 |
Đéļîƃéŕàţé éẋçéþţîöñš
Ţĥŕéé đéþàŕţüŕéš àŕé îñţéñţîöñàļ àñđ đöçüḿéñţéđ ŕàţĥéŕ ţĥàñ ƒîẋéđ:
kgrep/kcatŕéǫüîŕé-r, àñđksed-R, ƒöŕ đîŕéçţöŕîéš. Ţĥéý àŕé éẋþļîçîţ éḿüļàţîöñš öƒ ÞÖŠÎẊ ţööļš, àñđ ḿàţçĥîñĝ ţĥéîŕ çöñţŕàçţ îš ŵĥàţ ḿàķéš ţĥéḿ üšéƒüļ.kgrepéẋîţš 1 öñ ñö-ḿàţçĥ. Šàḿé ŕéàšöñ.kapi statusàļŵàýš éẋîţš 0. Ţàŕĝéţ-ļàñĝüàĝé đŕîƒţ îš þéñđîñĝ ŵöŕķ, ñöţ ƒàîļüŕé, šö ţĥé ŕéþöŕţîñĝ çöḿḿàñđ ñéṽéŕ ƒàîļš öñ îţ.kapi check --shipîš ţĥé éẋþļîçîţ éñƒöŕçéḿéñţ þöîñţ; šéé ţĥé çöñṽéŕĝéñçé ḿöđéļ.
Öñé çöñƒîĝ ṽéŕƃ
kapi config îš ţĥé öñļý çöñƒîĝüŕàţîöñ çöḿḿàñđ. À þļüĝîñ đöéš ñöţ šĥîþ îţš öŵñ:
îţ đéçļàŕéš à ķéý ñàḿéšþàçé îñ îţš ḿàñîƒéšţ
(capabilities.config_namespaces), àñđ ķàþî ŕöüţéš kapi config set <namespace>.<key> … ţö ţĥàţ þļüĝîñ'š öŵñ ĝļöƃàļ çöñƒîĝ ƒîļé ŵîţĥ ţĥé þŕéƒîẋ
šţŕîþþéđ, ţĥé šàḿé ƒîļé àñđ ķéý ţĥé þļüĝîñ àļŕéàđý ŕéàđš. kapi config list
šþàñš ķàþî'š öŵñ ķéýš àñđ éṽéŕý îñšţàļļéđ þļüĝîñ'š ñàḿéšþàçé.
KAPI_CONFIG_DIR çöñţàîñš þļüĝîñ çöñƒîĝ ƒîļéš ţöö
($KAPI_CONFIG_DIR/<plugin>/<plugin>.yaml), šö ţĥé îñ-ŕéþö îšöļàţîöñ çöñţŕàçţ
çöṽéŕš ñàḿéšþàçéđ ŵŕîţéš.