OpenSpec

Khắc phục sự cố ​

Các giải pháp cụ thể cho các vấn đề cụ thể. Mỗi mục nêu rõ triệu chứng, giải thích nguyên nhân có thể xảy ra trong một câu và đưa ra cách khắc phục. Nếu bạn không thấy vấn đề của mình ở đây, FAQ có thể hữu ích, và Discord chắc chắn sẽ giúp đỡ.

Cài đặt và thiết lập ​

openspec: command not found ​

CLI chưa được cài đặt hoặc shell của bạn không tìm thấy nó. Hãy cài đặt toàn cục và kiểm tra:

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

Nếu nó đã được cài đặt nhưng vẫn không tìm thấy, thư mục bin toàn cục của npm có thể chưa nằm trong PATH. Chạy npm prefix -g để xem các gói toàn cục nằm ở đâu: trên macOS và Linux, các tệp thực thi nằm trong thư mục bin/ của đường dẫn đó, còn trên Windows thì chúng nằm trực tiếp trong thư mục đó. Hãy đảm bảo rằng đường dẫn này đã được thêm vào PATH. (npm bin -g đã bị loại bỏ trong npm 9.)

Nếu bạn đã sử dụng cài đặt hỗ trợ AI, đây là điểm chuyển giao dự kiến: lời nhắc đó yêu cầu trợ lý AI của bạn hiển thị thay đổi PATH thay vì tự chỉnh sửa các tệp khởi động shell.

"Yêu cầu Node.js 20.19.0 trở lên" ​

OpenSpec chạy trên Node 20.19.0+. Hãy kiểm tra phiên bản của bạn và nâng cấp nếu cần:

bash
node --version

Nếu bạn sử dụng bun để cài đặt OpenSpec, hãy lưu ý rằng OpenSpec vẫn chạy trên Node, vì vậy bạn cần Node 20.19.0+ có sẵn trong PATH bất kể trường hợp nào. Xem Cài đặt.

openspec init không cấu hình công cụ AI của tôi ​

Lệnh init hỏi về các công cụ cần thiết lập. Nếu bạn đã bỏ qua công cụ của mình hoặc muốn thêm công cụ khác, chỉ cần chạy lại lệnh đó, hoặc sử dụng dạng không tương tác:

bash
openspec init --tools claude,cursor

Danh sách đầy đủ các ID công cụ có trong Các công cụ được hỗ trợ. Sử dụng --tools all để chọn tất cả, --tools none để bỏ qua việc thiết lập công cụ.

Lệnh không hiển thị ​

Nếu /opsx:propose (hoặc lệnh tương đương của công cụ của bạn) không xuất hiện hoặc không hoạt động, hãy kiểm tra danh sách dưới đây theo thứ tự từ nhanh nhất đến chậm nhất.

  1. Bạn có thể đang ở sai vị trí. Các lệnh slash (lệnh bắt đầu bằng /) được nhập trong cửa sổ chat của trợ lý AI, không phải trong terminal. Nếu bạn đã gõ /opsx:propose vào shell, đó chính là vấn đề. Xem Cách lệnh hoạt động.

  2. Tạo lại các tệp. Từ thư mục gốc của dự án:

    bash
    openspec update

    Lệnh này ghi đè các tệp kỹ năng (skill) và lệnh cho mọi công cụ mà bạn đã cấu hình.

    Các tệp hướng dẫn lấy từ CLI đã cài đặt, vì vậy một CLI cũ sẽ báo cáo mọi thứ đều cập nhật mà không bao giờ ghi các quy trình làm việc mới hơn. openspec update hiện kiểm tra điều này và đề xuất nâng cấp — hãy chấp nhận đề xuất nếu bạn thấy nó.

  3. Khởi động lại trợ lý của bạn. Hầu hết các công cụ quét tìm kỹ năng và lệnh khi khởi động. Một cửa sổ mới thường sẽ thực hiện việc này.

  4. Xác nhận các tệp tồn tại. Đối với Claude Code, hãy kiểm tra xem .claude/skills/ có chứa các thư mục openspec-* hay không. Các công cụ khác sử dụng các thư mục riêng của chúng, tất cả đều được liệt kê trong Các công cụ được hỗ trợ.

  5. Kiểm tra xem bạn đã khởi tạo dự án này chưa. Các kỹ năng được viết cho từng dự án. Nếu bạn đã sao chép kho lưu trữ (clone repo) hoặc chuyển đổi thư mục, hãy chạy openspec init (hoặc openspec update) trong thư mục đó.

  6. Xác nhận công cụ của bạn hỗ trợ các tệp lệnh. Codex, CodeArts, ForgeCode, Hermes, Kimi Code, Mistral Vibe, Zed Agent và mục tiêu .agents dùng chung không tạo ra các tệp lệnh opsx-*; chúng sử dụng các lệnh gọi dựa trên kỹ năng thay thế, vì vậy /opsx sẽ không bao giờ tự động hoàn thành cho chúng. Hãy gõ $openspec-propose trong Codex, /skill:openspec-propose trong Kimi Code, và /openspec-propose trong các công cụ còn lại. Mục tiêu .agents dùng chung độc lập với nhà cung cấp, vì vậy /openspec-propose là dạng phổ biến chứ không phải là dạng đảm bảo — nếu trợ lý của bạn không phản hồi với lệnh đó, hãy kiểm tra tài liệu riêng của nó để biết cách nó kích hoạt một kỹ năng. Amazon Q có nhận được các tệp lệnh, nhưng tải chúng vào thư viện prompt của nó thay vì menu slash — hãy gõ @opsx-propose ở đó, không phải /opsx. Dạng lệnh của mỗi công cụ được liệt kê trong Cách gọi lệnh.

Làm việc với các thay đổi ​

"Không tìm thấy thay đổi" ​

Lệnh không thể xác định thay đổi nào bạn đang đề cập. Hãy đặt tên rõ ràng, hoặc kiểm tra những gì đang tồn tại:

bash
openspec list                    # xem các thay đổi đang hoạt động
/opsx:apply add-dark-mode        # đặt tên thay đổi trong chat

Đồng thời xác nhận bạn đang ở đúng thư mục dự án.

"Không có artifact nào sẵn sàng" ​

Mỗi artifact hoặc đã được tạo hoặc đang chờ phụ thuộc. Hãy xem cái gì đang chặn:

bash
openspec status --change <name>

Sau đó, hãy tạo phụ thiếu trước. Hãy nhớ thứ tự: proposal kích hoạt specs và design; specs và design cùng nhau kích hoạt tasks.

openspec validate báo cáo cảnh báo hoặc lỗi ​

Validation kiểm tra các specs và thay đổi của bạn xem có vấn đề về cấu trúc hay không. Hãy đọc thông báo: nó sẽ nêu tên tệp và vấn đề.

bash
openspec validate <name>           # validate một mục
openspec validate --all            # validate mọi thứ
openspec validate --all --strict   # kiểm tra nghiêm ngặt hơn, tốt cho CI
openspec validate --archived       # báo lỗi nếu các thay đổi đã lưu trữ có các task chưa được kiểm tra

Các nguyên nhân phổ biến là thiếu phần bắt buộc (như một spec không có scenarios) hoặc tiêu đề delta bị lỗi cú pháp. Sửa tệp và chạy lại. Tham chiếu CLI tài liệu hóa định dạng đầu ra.

Một thông báo deserves ghi chú riêng:

text
MODIFIED "<requirement>" omits scenario(s) the current spec still has: "<scenario>"

Một requirement MODIFIED thay thế toàn bộ khối requirement, vì vậy nó phải mang theo mọi scenario còn tồn tại sau khi thay đổi, không chỉ những cái bạn đã chỉnh sửa. Hãy sao chép các scenario được nêu từ openspec/specs/<capability-path>/spec.md quay lại vào delta, bảo toàn bất kỳ thư mục miền nào trong đường dẫn. Điều này thường xuất hiện trên một thay đổi cũ hơn sau khi một thay đổi của người khác thêm một scenario vào cùng một requirement — archive sẽ từ chối thay đổi đó dù theo cách nào, và validation bây giờ sẽ nói điều đó trước khi bạn triển khai nó.

AI tạo ra các artifact không đầy đủ hoặc sai ​

AI không có đủ ngữ cảnh. Một vài tùy chọn giúp ích:

  • Thêm ngữ cảnh dự án trong openspec/config.yaml để ngăn xếp và quy ước của bạn được tiêm vào mọi yêu cầu. Xem Tùy chỉnh.
  • Thêm rules: cho từng artifact để hướng dẫn chỉ áp dụng cho, ví dụ, specs.
  • Cung cấp mô tả chi tiết hơn khi bạn đề xuất.
  • Sử dụng /opsx:continue mở rộng để tạo từng artifact một và xem xét từng cái, thay vì /opsx:ff thực hiện tất cả cùng lúc.

Archive không hoàn tất hoặc cảnh báo về các task chưa hoàn thành ​

Archive sẽ không chặn do các task chưa hoàn thành, nhưng nó cảnh báo bạn, vì archiving thường có nghĩa là công việc đã xong. Nếu các task vẫn còn có chủ đích (bạn đang lưu trữ một thay đổi một phần), hãy tiếp tục. Ngược lại, hãy hoàn thành các task trước. Archive cũng sẽ đề xuất đồng bộ hóa các delta specs của bạn vào các specs chính nếu bạn chưa đồng bộ hóa; hãy nói đồng ý trừ khi bạn có lý do không làm vậy.

"Người dùng đã đóng thủ công prompt với 0 null" ​

Có thứ gì đó đã chạy openspec archive ở nơi không thể trả lời câu hỏi — một agent AI gọi nó từ một công cụ, một job CI, hoặc bất kỳ shell nào có stdin bị đóng. Archive yêu cầu tối đa ba lần xác nhận, và một lần không thể trả lời trước đây sẽ thất bại với thông báo thô này.

Hãy truyền --yes để trả lời chúng ngay từ đầu:

bash
openspec archive <change-name> --yes

Giữ bất kỳ cờ nào bạn đang truyền — --skip-specs và --no-validate thay đổi cách archive hoạt động, vì vậy việc chạy lại chỉ với --yes không phải là cùng một lệnh. Các phiên bản hiện tại đặt tên cho cờ và in một dòng Fix: mà bạn có thể dán vào. Nếu bạn định chọn từ một danh sách, hãy truyền tên thay đổi rõ ràng: trình chọn cũng cần một câu trả lời.

Nếu thay vào đó bạn đã chạy archive với đầu ra được chuyển hướng vào một tệp hoặc được một công cụ nắm bắt và thực sự đã chuyển hướng một câu trả lời (printf 'y\n' | openspec archive …), các phiên bản cũ đã ghi các mã thoát terminal vào bản capture đó khi vẽ prompt — trong một số môi trường đủ lớn để làm phình to tệp đáng kể. Các phiên bản hiện tại đọc các prompt xác nhận dưới dạng văn bản thuần túy bất cứ khi nào stdout không phải là terminal, và một lệnh openspec archive không đối số (vốn sẽ vẽ một trình chọn thay đổi tương tác) yêu cầu bạn truyền tên thay đổi ngay từ đầu thay vì hiển thị menu vào bản capture. Dù theo cách nào, các lần chạy được chuyển hướng và agent vẫn sạch sẽ; việc truyền --yes (kèm tên thay đổi) bỏ qua các prompt hoàn toàn.

Cấu hình ​

config.yaml của tôi không được áp dụng ​

Ba nghi phạm thường gặp:

  1. Sai tên tệp. Nó phải là openspec/config.yaml, không phải .yml.
  2. YAML không hợp lệ. Hãy chạy nó qua bất kỳ trình kiểm tra YAML nào; CLI cũng báo cáo các lỗi cú pháp kèm theo số dòng.
  3. Bạn mong đợi cần khởi động lại. Bạn không cần phải làm vậy. Các thay đổi cấu hình có hiệu lực ngay lập tức.

"ID artifact không xác định trong rules: X" ​

Một khóa con rules: không khớp với bất kỳ artifact nào trong schema của bạn. Đối với schema mặc định spec-driven, các ID hợp lệ là proposal, specs, design, tasks. Để xem các ID cho bất kỳ schema nào:

bash
openspec schemas --json

"Ngữ cảnh quá lớn" ​

Trường context: bị giới hạn ở 50KB, có chủ đích, vì nó được tiêm vào mọi yêu cầu. Hãy tóm tắt nó, hoặc liên kết đến các tài liệu dài hơn thay vì dán chúng vào. Ngữ cảnh gọn gàng cũng tạo ra kết quả tốt hơn, nhanh hơn.

"Không tìm thấy schema" ​

Tên schema bạn tham chiếu không tồn tại. Hãy liệt kê những gì có sẵn và kiểm tra chính tả:

bash
openspec schemas                    # liệt kê các schema có sẵn
openspec schema which <name>        # xem một schema được phân giải từ đâu
openspec schema init <name>         # tạo một schema tùy chỉnh

Xem Tùy chỉnh.

Di chuyển từ quy trình làm việc cũ ​

"Phát hiện các tệp cũ ở chế độ không tương tác" ​

Bạn đang ở trong CI hoặc một shell không tương tác, và OpenSpec đã tìm thấy các tệp cũ để dọn dẹp nhưng không thể hỏi ý kiến bạn. Hãy phê duyệt tự động:

bash
openspec init --force

Đối với Codex, OpenSpec có thể phát hiện các tệp prompt được quản lý cũ trong $CODEX_HOME/prompts hoặc ~/.codex/prompts. Việc dọn dẹp đó chỉ giới hạn ở các tên tệp prompt Codex cũ được phép của OpenSpec, và openspec init không tương tác chỉ xóa các tệp mà các kỹ năng thay thế .agents/skills/openspec-* đã tồn tại. openspec update không tương tác giữ nguyên mọi việc dọn dẹp cũ trừ khi bạn truyền --force.

Lệnh không xuất hiện sau khi di chuyển ​

Khởi động lại IDE của bạn. Các kỹ năng được phát hiện khi khởi động. Nếu chúng vẫn không xuất hiện, hãy chạy openspec update và kiểm tra các vị trí tệp trong Các công cụ được hỗ trợ.

project.md cũ của tôi không được di chuyển ​

Điều đó là có chủ đích. OpenSpec không bao giờ tự động xóa project.md vì nó có thể chứa ngữ cảnh bạn đã viết. Hãy di chuyển các phần hữu ích vào phần context: của config.yaml, sau đó tự xóa nó. Hướng dẫn Di chuyển sẽ hướng dẫn bạn qua bước này, bao gồm một prompt bạn có thể đưa cho AI của mình để thực hiện việc cô đọng nội dung.

Vẫn bị kẹt? ​

Khi bạn báo cáo một vấn đề, hãy bao gồm phiên bản OpenSpec của bạn (openspec --version), phiên bản Node của bạn (node --version), công cụ AI của bạn, và lệnh và đầu ra chính xác. Nó giúp việc hỗ trợ nhanh hơn rất nhiều.