user
114 lines
4.8 KiB
Markdown
114 lines
4.8 KiB
Markdown
# Sesja karty z wiersza poleceń
|
|
|
|
`stemctl session` łączy pięć selektorów w jeden kontrakt:
|
|
|
|
```text
|
|
seria → karta → Task → blok/faza/krok/snapshot UML → instancja kontenera
|
|
```
|
|
|
|
Każdy selektor przyjmuje stabilne ID. Seria, karta, Task, blok, faza, krok i
|
|
snapshot przyjmują także numery pokazywane przez `choices`. Numer karty jest
|
|
jednobazową pozycją w manifeście serii, więc nie zależy od tego, czy repo karty
|
|
zostało już pobrane. W przypadku kroków najpierw sprawdzany jest globalny numer
|
|
strzałki z diagramu, a przy jawnie wybranej fazie także lokalny numer kroku.
|
|
|
|
## Lista wyboru
|
|
|
|
```bash
|
|
./stemctl session choices --series inf --card 7 --task 4
|
|
./stemctl session choices --series inf --card pointers --json
|
|
```
|
|
|
|
Tabele zawierają kolumnę `status`:
|
|
|
|
- `opracowane` — materiał UML ma komplet recept replay/checkpoint;
|
|
- `robocze` — istnieje źródło albo częściowe metadane;
|
|
- `brak` — karta lub materiał nie znajduje się jeszcze w workspace.
|
|
|
|
## Sterowanie środowiskiem
|
|
|
|
```bash
|
|
# Utwórz debugger Task04 w pane 0 okna, z którego uruchomiono Codexa.
|
|
./stemctl session start hazard3-sim --series inf --card 7 --task 4
|
|
|
|
# Usuń i odtwórz kontener, po czym zatrzymaj maszynę na strzałce 12.
|
|
./stemctl session reset hazard3-sim \
|
|
--series inf --card 7 --task 4 --step 12
|
|
|
|
# Zachowaj kontener i ponownie podepnij istniejący debugger.
|
|
./stemctl session refresh hazard3-sim --series inf --card 7 --task 4
|
|
|
|
# Podepnij/odepnij tylko klienta w zewnętrznym tmuxie. Serwer debuggera żyje dalej.
|
|
./stemctl session attach hazard3-sim --series inf --card 7 --task 4
|
|
./stemctl session detach hazard3-sim --series inf --card 7 --task 4
|
|
```
|
|
|
|
Domyślny cel `--pane current:0` oznacza pane `0` tego samego okna tmuxa, w
|
|
którym działa wywołujący Codex. Można podać jawne `%ID`, `sesja:okno.pane` albo
|
|
`--pane none`. Launcher odmawia zastąpienia pane, z którego sam został
|
|
uruchomiony, aby nie zakończyć Codexa. Pane Codexa jest dodatkowo oznaczone
|
|
PID-em pane w opcjach tmuxa; jawne `%ID` podane z innego terminala również
|
|
zostanie odrzucone. Świadome obejście tej drugiej ochrony wymaga
|
|
`--force-pane`; nie da się nim zastąpić pane wykonującego bieżącą komendę.
|
|
|
|
`detach` odłącza wyłącznie zewnętrznego klienta tmuxa. Nie zatrzymuje
|
|
kontenera, symulatora, GDB, Neovima ani wewnętrznej sesji tmuxa.
|
|
|
|
## Wybór stanu UML
|
|
|
|
Równoważne przykłady:
|
|
|
|
```bash
|
|
./stemctl session stage hazard3-sim --series inf --card 7 --task 4 --step 12
|
|
./stemctl session checkpoint hazard3-sim --series inf --card pointers --task 4 \
|
|
--snapshot task04.alloc5.commit
|
|
./stemctl session stage hazard3-sim --series inf --card 7 --task 4 --stage alloc-5/7
|
|
./stemctl session stage hazard3-sim --series inf --card 7 --task 4 \
|
|
--stage task04/allocator-flow/alloc-5/alloc5-commit
|
|
./stemctl session stage hazard3-sim --series inf --card 7 --task 4 \
|
|
--phase 2 --step 3
|
|
./stemctl session stage hazard3-sim --series inf --card 7 --task 4 --first
|
|
```
|
|
|
|
W ostatnim przykładzie `3` oznacza trzeci krok wewnątrz drugiej fazy, jeżeli
|
|
w tej fazie nie istnieje globalna strzałka numer 3.
|
|
|
|
Tryb online najpierw sprawdza pełną tożsamość karty (`id`, UUID, wersję i hash
|
|
źródłowego JSON-a), receptę checkpointu, profil, target oraz bind mount
|
|
`/workspace`. Następnie wybiera sockety MCP i przekazuje kontrolerowi
|
|
oczekiwane `instance/container_id/profile/target`. Replay zostaje odrzucony,
|
|
jeżeli globalny wybór MCP zmieni się przed aktywacją albo podczas niej. Dopiero
|
|
po udanym zatrzymaniu GDB publikowane są pozycja strony i `SYNC ON`.
|
|
|
|
`--offline` zmienia wyłącznie stan strony i wyłącza SYNC/sterowanie Neovimem.
|
|
`--control` dodatkowo uzbraja sterowanie klawiaturą Neovima; samo SYNC nie robi
|
|
tego automatycznie. `stage/checkpoint` wymaga jawnego selektora; pierwszy etap
|
|
wybiera się świadomie przez `--first`.
|
|
|
|
```bash
|
|
./stemctl session stage hazard3-sim --series inf --card 7 --task 4 \
|
|
--step 12 --offline
|
|
./stemctl session status hazard3-sim --series inf --card 7 --task 4
|
|
./stemctl session status hazard3-sim --series inf --card 7 --task 4 \
|
|
--json --strict
|
|
```
|
|
|
|
Adres serwera karty można zmienić przez `--card-url` albo `STEM_CARD_URL`.
|
|
Limit oczekiwania na Neovima/GDB/MCP ustawia `--timeout`.
|
|
|
|
## Przyszłe strategie i adnotacje
|
|
|
|
Kluczem rozszerzeń pozostaje pełna pozycja
|
|
`task/block/phase/step/snapshot`. Pod tym kluczem będzie można później
|
|
przechowywać wiele strategii debugowania i adnotacji bez zmiany obecnego CLI.
|
|
Planowany kontrakt rozdziela treść od widoczności:
|
|
|
|
```text
|
|
strategy: id, label, commands, expected_observations
|
|
annotation: id, strategy_id, target, geometry, style, text, visible
|
|
```
|
|
|
|
`target` może wskazywać diagram, bufor/wiersz Neovima, rejestr, ramkę stosu
|
|
albo zakres pamięci. Operacje `show/hide/toggle` mają zmieniać widoczność bez
|
|
usuwania adnotacji; `add/remove` będą osobnymi, audytowalnymi operacjami.
|