Rozwiązywanie problemów

Konkretne rozwiązania konkretnych problemów. Każdy wpis nazywa objaw, wyjaśnia w jednym zdaniu prawdopodobną przyczynę i podaje poprawkę. Jeśli nie widzisz tutaj swojego problemu, pomocne może być FAQ, a na pewno pomoże Discord.

Instalacja i konfiguracja

openspec: command not found

CLI nie jest zainstalowane lub Twoja powłoka nie może go znaleźć. Zainstaluj globalnie i sprawdź:

npm install -g @fission-ai/openspec@latest
openspec --version

Jeśli instalacja się powiodła, a nadal nie jest znajdowane, prawdopodobnie katalog globalny npm nie znajduje się na Twojej ścieżce PATH. Uruchom npm prefix -g, aby zobaczyć, gdzie znajdują się pakiety globalne: na macOS i Linux-ie pliki binarne są w podkatalogu bin/ tego katalogu, a na Windows-ie bezpośrednio w nim. Upewnij się, że ta ścieżka jest dodana do PATH. (Polecenie npm bin -g zostało usunięte w npm 9.)

Jeśli korzystałeś z instalacji wspomaganej przez AI, to jest oczekiwany punkt przejęcia: ten prompt każe asystentowi pokazać Ci zmianę w PATH, zamiast samodzielnie edytować pliki startowe powłoki.

„Wymaga Node.js 20.19.0 lub nowszego”

OpenSpec działa na Node 20.19.0+. Sprawdź swoją wersję i zaktualizuj, jeśli to konieczne:

node --version

Jeśli używasz bun do instalacji OpenSpec, pamiętaj, że OpenSpec nadal działa na Node, więc musisz mieć Node 20.19.0+ dostępny na PATH niezależnie od tego. Zobacz Instalacja.

openspec init nie skonfigurowało mojego narzędzia AI

Inicjalizacja pyta, które narzędzia skonfigurować. Jeśli pominąłeś swoje narzędzie lub chcesz dodać kolejne, po prostu uruchom ją ponownie lub użyj formy nieinteraktywnej:

openspec init --tools claude,cursor

Pełna lista identyfikatorów narzędzi znajduje się w Obsługiwane narzędzia. Użyj --tools all, aby dodać wszystkie, --tools none, aby pominąć konfigurację narzędzi.

Polecenia się nie pojawiają

Jeśli /opsx:propose (lub jego odpowiednik w Twoim narzędziu) nie pojawia się lub nic nie robi, przejdź przez tę listę. Są one uporządkowane od najszybszych do sprawdzenia.

1. Być może jesteś w złym miejscu. Polecenia slash są wprowadzane w czacie asystenta AI, a nie w terminalu. Jeśli wpisałeś /opsx:propose w powłoce, to jest właśnie problem. Zobacz Jak działają polecenia.

2. Wygeneruj ponownie pliki. Z katalogu głównego projektu:

   openspec update

   To nadpisuje pliki umiejętności i poleceń dla każdego skonfigurowanego narzędzia.

   Pliki instrukcji pochodzą z zainstalowanego CLI, więc nieaktualne CLI raportuje wszystko jako aktualne, nigdy nie zapisując nowszych przepływów pracy. openspec update teraz to sprawdza i oferuje aktualizację — zaakceptuj ją, jeśli zostanie wyświetlona.

3. Zrestartuj asystenta. Większość narzędzi skanuje umiejętności i polecenia podczas uruchamiania. Świeże okno często załatwia sprawę.

4. Potwierdź istnienie plików. Dla Claude Code sprawdź, czy katalog .claude/skills/ zawiera foldery openspec-*. Inne narzędzia używają własnych katalogów, wszystkie wymienione w Obsługiwane narzędzia.

5. Sprawdź, czy zainicjowano ten projekt. Umiejętności są zapisywane per projekt. Jeśli sklonowałeś repozytorium lub zmieniłeś katalog, uruchom tam openspec init (lub openspec update).

6. Sprawdź, czy Twoje narzędzie obsługuje pliki poleceń. Codex, CodeArts, ForgeCode, Hermes, Kimi Code, Mistral Vibe, Zed Agent i współdzielony cel .agents nie otrzymują wygenerowanych plików poleceń opsx-*; zamiast tego używają wywołań opartych na umiejętnościach, więc /opsx nigdy nie będzie dla nich dostępne z autouzupełniania. Wpisz $openspec-propose w Codex, /skill:openspec-propose w Kimi Code, a /openspec-propose w pozostałych. Współdzielony cel .agents jest neutralny dostawcy, więc /openspec-propose jest powszechną formą, a nie gwarantowaną — jeśli Twój asystent na nią nie odpowiada, sprawdź jego dokumentację, jak wywołać umiejętność. Amazon Q otrzymuje pliki poleceń, ale ładuje je do biblioteki promptów, a nie do menu slash — tam wpisz @opsx-propose, a nie /opsx. Każda forma dla narzędzia jest podana w Jak wywołać.

Praca ze zmianami

„Nie znaleziono zmiany”

Polecenie nie mogło ustalić, o którą zmianę chodzi. Nazwij ją jawnie lub sprawdź, co istnieje:

openspec list                    # zobacz aktywne zmiany
/opsx:apply add-dark-mode        # nazwij zmianę na czacie

Upewnij się również, że jesteś w prawidłowym katalogu projektu.

„Brak gotowych artefaktów”

Każdy artefakt jest już utworzony lub zablokowany w oczekiwaniu na zależność. Zobacz, co blokuje:

openspec status --change <name>

Następnie najpierw utwórz brakującą zależność. Pamiętaj o kolejności: propozycja umożliwia tworzenie specyfikacji i projektu; specyfikacja i projekt razem umożliwiają zadania.

openspec validate zgłasza ostrzeżenia lub błędy

Walidacja sprawdza Twoje specyfikacje i zmiany pod kątem problemów strukturalnych. Przeczytaj komunikat: podaje on plik i problem.

openspec validate <name>           # waliduj jeden element
openspec validate --all            # waliduj wszystko
openspec validate --all --strict   # bardziej restrykcyjne sprawdzenia, dobre do CI
openspec validate --archived       # zgłoś błąd, jeśli w zarchiwizowanych zmianach są niesprawdzone zadania

Najczęstsze przyczyny to brak wymaganej sekcji (np. specyfikacja bez scenariuszy) lub nieprawidłowy nagłówek delty. Popraw plik i uruchom ponownie. Dokumentacja CLI opisuje format wyjściowy.

Jeden komunikat zasługuje na osobną notkę:

MODIFIED „<wymaganie>” pomija scenariusz(e), które obecna specyfikacja nadal zawiera: „<scenariusz>”

Wymaganie MODIFIED zastępuje cały blok wymagania, więc musi zawierać każdy scenariusz, który przetrwa zmianę, nie tylko te, które edytowałeś. Skopiuj nazwane scenariusze z openspec/specs/<ścieżka-zdolności>/spec.md z powrotem do delty, zachowując wszystkie katalogi domeny w ścieżce. To często pojawia się przy starszej zmianie, gdy zmiana innej osoby dodała scenariusz do tego samego wymagania — archiwizacja i tak zostałaby odrzucona, a walidacja informuje o tym przed implementacją.

AI utworzyło niekompletne lub błędne artefakty

AI nie miało wystarczającego kontekstu. Kilka dźwigni może pomóc:

• Dodaj kontekst projektu w openspec/config.yaml, aby Twój stos i konwencje były wstrzykiwane do każdego żądania. Zobacz Dostosowywanie.
• Dodaj rules: dla poszczególnych artefaktów, zawierające wskazówki dotyczące np. tylko specyfikacji.
• Podaj bardziej szczegółowy opis podczas tworzenia propozycji.
• Użyj rozwiniętego /opsx:continue, aby tworzyć artefakty pojedynczo i sprawdzać każdy z nich, zamiast /opsx:ff, które tworzy wszystkie naraz.

Archiwizacja nie kończy się lub ostrzega o nieukończonych zadaniach

Archiwizacja nie blokuje z powodu nieukończonych zadań, ale ostrzega, ponieważ zazwyczaj oznacza to, że praca jest zakończona. Jeśli zadania pozostają celowo (składasz częściową zmianę), kontynuuj. W przeciwnym razie najpierw dokończ zadania. Archiwizacja zaproponuje również synchronizację specyfikacji delty z głównymi specyfikacjami, jeśli jeszcze tego nie zrobiono; odpowiedz tak, chyba że masz ku temu powody.

„Użytkownik wymuszenie zamknął prompt z kodem 0 null”

Coś uruchomiło openspec archive, gdzie nic nie może odpowiedzieć na pytanie — agent AI wywołujący je z narzędzia, zadanie CI lub dowolna powłoka z zamkniętym stdin. Archiwizacja zadaje do trzech potwierdzeń, a brak odpowiedzi wcześniej kończył się surowym komunikatem.

Przekaż --yes, aby odpowiedzieć na nie z góry:

openspec archive <change-name> --yes

Zachowaj wszelkie flagi, które już przekazywałeś — --skip-specs i --no-validate zmieniają działanie archiwizacji, więc samo powtórzenie z --yes to nie to samo polecenie. Bieżące wersje same podpowiedzą flagę i wypiszą Fix:, które można wkleić. Jeśli zamierzałeś wybrać z listy, jawnie podaj nazwę zmiany: interaktywny wybór również wymaga odpowiedzi.

Jeśli natomiast uruchomiłeś archiwizację z przekierowaniem wyjścia do pliku lub przechwyconym przez narzędzie i rzeczywiście podałeś odpowiedź (printf 'y\n' | openspec archive …), starsze wersje zapisywały do tego przechwycenia kody ucieczki terminala podczas rysowania promptu — w niektórych środowiskach wystarczające, aby poważnie napęcznić plik. Bieżące wersje odczytują monity potwierdzeń jako zwykły tekst, gdy stdout nie jest terminalem, a openspec archive bez argumentów (które w przeciwnym razie narysowałoby interaktywny wybór zmian) pyta o nazwę zmiany od razu, zamiast renderować menu do przechwycenia. Tak czy inaczej, uruchomienia przekierowane i agentowe pozostają czyste; przekazanie --yes (z nazwą zmiany) całkowicie pomija monity.

Konfiguracja

Mój plik config.yaml nie jest stosowany

Trzej zwykli podejrzani:

1. Zła nazwa pliku. Musi to być openspec/config.yaml, a nie .yml.
2. Nieprawidłowy YAML. Przeanalizuj go dowolnym walidatorem YAML; CLI również raportuje błędy składni z numerami linii.
3. Spodziewałeś się restartu. Nie jest potrzebny. Zmiany konfiguracji obowiązują natychmiast.

„Nieznany identyfikator artefaktu w regułach: X”

Klucz pod rules: nie pasuje do żadnego artefaktu w Twoim schemacie. Dla domyślnego schematu spec-driven prawidłowe identyfikatory to proposal, specs, design, tasks. Aby zobaczyć identyfikatory dla dowolnego schematu:

openspec schemas --json

„Kontekst zbyt duży”

Pole context: jest ograniczone do 50 KB celowo, ponieważ jest wstrzykiwane do każdego żądania. Streść je lub linkuj do dłuższych dokumentów zamiast wklejać. Zwięzły kontekst daje też lepsze i szybsze rezultaty.

„Nie znaleziono schematu”

Nazwa schematu, do której się odwołujesz, nie istnieje. Wypisz dostępne schematy i sprawdź pisownię:

openspec schemas                    # wypisz dostępne schematy
openspec schema which <name>        # zobacz, skąd pochodzi schemat
openspec schema init <name>         # utwórz własny schemat

Zobacz Dostosowywanie.

Migracja ze starego przepływu pracy

„Wykryto pliki legacy w trybie nieinteraktywnym”

Jesteś w CI lub powłoce nieinteraktywnej, a OpenSpec znalazł stare pliki do usunięcia, ale nie może zapytać o potwierdzenie. Zatwierdź automatycznie:

openspec init --force

Dla Codex, OpenSpec może wykryć stare zarządzane pliki promptów w $CODEX_HOME/prompts lub ~/.codex/prompts. To czyszczenie ogranicza się do dozwolonych, starych nazw plików promptów Codex, a nieinteraktywne openspec init usuwa tylko te pliki, dla których istnieją zastępcze umiejętności .agents/skills/openspec-*. Nieinteraktywne openspec update pozostawia całe czyszczenie legacy nietknięte, chyba że dodasz --force.

Polecenia nie pojawiły się po migracji

Zrestartuj IDE. Umiejętności są wykrywane podczas uruchamiania. Jeśli nadal się nie pojawiają, uruchom openspec update i sprawdź lokalizacje plików w Obsługiwane narzędzia.

Mój stary plik project.md nie został zmigrowany

To celowe. OpenSpec nigdy nie usuwa automatycznie project.md, ponieważ może zawierać kontekst, który napisałeś. Przenieś przydatne części do sekcji context: w config.yaml, a następnie samodzielnie usuń plik. Przewodnik migracji przeprowadza przez ten proces, zawiera też prompt, który możesz przekazać swojemu AI, aby dokonało ekstrakcji.

Nadal masz problem?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• Z terminala: openspec feedback "co poszło nie tak" otwiera dla Ciebie zgłoszenie.

Gdy zgłaszasz problem, podaj swoją wersję OpenSpec (openspec --version), wersję Node (node --version), swoje narzędzie AI oraz dokładne polecenie i wynik. To znacznie przyspieszy pomoc.