OpenSpec

Cài đặt ​

Cài đặt CLI openspec trên máy của bạn, cập nhật nó và gỡ bỏ.

Cài đặt ​

Trên macOS hoặc Linux, trong terminal của bạn:

bash
curl -fsSL https://openspec.dev/cli/install.sh | sh

Trên Windows, trong PowerShell:

powershell
irm https://openspec.dev/cli/install.ps1 | iex

Nếu trình cài đặt in ra dòng export PATH=..., hãy chạy dòng đó. Sau đó kiểm tra xem đã thành công chưa.

Cài đặt với trợ lý AI của bạn ​

Dán đoạn này vào cuộc trò chuyện AI của bạn:

text
Fetch https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/install.md and follow it.

Hoặc, trong terminal của bạn, chuyển hướng đầu vào cho một tác nhân CLI (Claude Code được hiển thị):

bash
curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/install.md | claude

Điều này sẽ lấy install.md tại gốc kho lưu trữ, một lời nhắc được viết cho bất kỳ tác nhân nào có thể chạy lệnh shell (một số tích hợp IDE không hỗ trợ). Hãy mong đợi trợ lý của bạn sẽ:

  1. Bỏ qua cài đặt nếu CLI đã có trên máy của bạn, và đề xuất cách cập nhật nó theo cách nó đã được cài đặt. Nếu đó là npm hoặc Homebrew, hãy nhắc một lần rằng openspec install chuyển sang bản cài đặt độc lập, mà không ép buộc. Ngược lại, hãy hiển thị lệnh cài đặt ở trên và chờ xác nhận của bạn trước khi chạy nó.
  2. Chỉ sử dụng npm nếu bạn yêu cầu hoặc nếu trình cài đặt thất bại, và dừng lại nếu phiên bản Node của bạn cũ hơn 22.12.0.
  3. Xác minh openspec có trong PATH của bạn.
  4. Đặt tên cho thư mục mà nó nghĩ bạn đang muốn, gợi ý công cụ AI mà bạn đang trò chuyện, và hỏi xem bạn còn dùng những công cụ nào khác, sau đó chạy openspec init tại đó (bước thiết lập dự án).
  5. Báo cáo những gì init đã tạo và chính tả chính xác để gọi OpenSpec trong công cụ của bạn.

Nó dừng lại trước bất kỳ thao tác nào cần quyền cao nhất và không bao giờ chỉnh sửa các tệp khởi động shell của bạn. Lệnh cài đặt ở trên và các trình quản lý gói bên dưới là nguồn thông tin chính xác, và lời nhắc sẽ chạy chúng thay bạn.

Phương pháp cài đặt này mới và có thể mang lại kết quả khác nhau tùy thuộc vào mô hình được sử dụng. Chỉ sử dụng nếu bạn cảm thấy thoải mái khi sửa lỗi do AI gây ra. Ngược lại, chúng tôi khuyên bạn nên làm theo phương pháp tiêu chuẩn bên dưới.

Các trình quản lý gói ​

Những phương pháp này cài đặt OpenSpec dưới dạng gói Node.js, vì vậy chúng cần Node.js 22.12.0 trở lên (Homebrew và Nix sẽ tự cung cấp phiên bản của riêng chúng). Trong terminal của bạn:

bash
node --version

Nếu kết quả in ra là v22.12.0 hoặc cao hơn, hãy cài đặt bằng npm:

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

Nếu không, hãy cài đặt Node phiên bản mới hơn từ nodejs.org hoặc thông qua trình quản lý phiên bản của bạn (nvm, fnm, asdf, volta), hoặc sử dụng cài đặt độc lập thay thế.

Homebrew ​

Homebrew cài đặt OpenSpec và phần phụ thuộc Node.js của nó trên macOS hoặc Linux. Trong terminal của bạn:

bash
brew install openspec

Công thức này được công bố trong homebrew-core, vì vậy bạn không cần phải thêm tap.

Yarn ​

yarn global add chỉ dành cho Yarn Classic (1.x). Yarn hiện đại đã loại bỏ việc cài đặt toàn cục, vì vậy hãy sử dụng npm, pnpm hoặc bun thay thế. Một CLI toàn cục không nhất thiết phải chia sẻ trình quản lý gói của dự án của bạn.

Bun ​

Bun cài đặt OpenSpec nhưng không chạy nó, vì vậy bạn vẫn cần Node trên máy của mình (xem Các trình quản lý gói). Nếu không, mọi lệnh sẽ thất bại với lỗi env: node: No such file or directory. Bun xử lý mọi CLI Node theo cách này.

Deno ​

Deno cài đặt CLI từ npm và cần các cờ quyền hạn chế rõ ràng. Trong terminal của bạn:

bash
deno install --global \
  --allow-read --allow-write --allow-env --allow-sys=cpus,homedir --allow-net=edge.openspec.dev \
  npm:@fission-ai/openspec@latest

Một số lệnh khởi chạy một chương trình khác: openspec config edit mở trình soạn thảo của bạn. Deno sẽ ngắt những lệnh này bằng một lời nhắc quyền hạn chế mỗi khi chạy. Để ngăn nó hỏi, hãy thêm --allow-run=<program> có phạm vi vào lệnh cài đặt.

NOTE

Nếu Deno không thể phân giải @latest, hãy ghim một khoảng phiên bản thay thế: npm:@fission-ai/openspec@^1.7.0.

Nix ​

Kho OpenSpec cung cấp một Nix flake. Hãy cài đặt nó vào hồ sơ của bạn. Trong terminal của bạn:

bash
nix profile install github:Fission-AI/OpenSpec

Hoặc chạy một lệnh một lần trước, mà không cần cài đặt:

bash
nix run github:Fission-AI/OpenSpec -- --version

Điều này sẽ không để lại bất cứ thứ gì trên PATH của bạn, vì vậy không cần kiểm tra cài đặt sau đó.

Để đưa OpenSpec vào vỏ dev của dự án thay thế, hãy thêm flake dưới dạng đầu vào và sử dụng gói mặc định của nó; flake.nix liệt kê các đầu ra.

Gói Nix cung cấp các tập lệnh hoàn thiện Bash, Fish và Zsh tại các vị trí tiêu chuẩn (share/bash-completion/completions, share/fish/vendor_completions.d, share/zsh/site-functions), vì vậy chúng sẽ tải cùng với gói và không cần chạy openspec completion install.

Kiểm tra xem đã thành công chưa ​

Bất kể phương pháp nào bạn đã sử dụng, trong terminal của bạn:

bash
openspec --version

Nếu kết quả in ra là một số phiên bản, thì CLI đã có trong PATH của bạn. Nó được cài đặt một lần cho mỗi máy.

Tiếp theo, thiết lập dự án của bạn. Nếu trợ lý của bạn đã chạy init, trang đó sẽ hiển thị những gì nó đã ghi và cách điều chỉnh nó.

Tùy chọn cài đặt ​

Để chọn một phiên bản hoặc một thư mục, hãy đặt một biến trước sh:

bash
curl -fsSL https://openspec.dev/cli/install.sh | OPENSPEC_VERSION=v1.15.0 sh
  • OPENSPEC_VERSION: bản phát hành cần cài đặt, chẳng hạn như v1.15.0. Mặc định là bản phát hành mới nhất.
  • OPENSPEC_INSTALL_DIR: thư mục cần cài đặt vào. Mặc định là ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\openspec).

Trên Windows, hãy đặt biến trước:

powershell
$env:OPENSPEC_VERSION = 'v1.15.0'
irm https://openspec.dev/cli/install.ps1 | iex

Trên Alpine Linux, hãy chạy apk add libstdc++ libgcc trước khi cài đặt.

Tải xuống bằng tay ​

Mỗi bản phát hành có một tệp cho mỗi máy tính:

Máy tínhTệp
Mac, Apple siliconopenspec-darwin-arm64.tar.gz
Mac, Intelopenspec-darwin-x64.tar.gz
Linux, arm64openspec-linux-arm64.tar.gz
Linux, x64openspec-linux-x64.tar.gz
Alpine, arm64openspec-linux-arm64-musl.tar.gz
Alpine, x64openspec-linux-x64-musl.tar.gz
Windows, arm64openspec-windows-arm64.zip
Windows, x64openspec-windows-x64.zip
  1. Tải xuống tệp của bạn từ bản phát hành mới nhất. Các tệp được đính kèm vài phút sau khi bản phát hành được xuất bản. Nếu tệp của bạn chưa được liệt kê, hãy đợi và tải lại, hoặc lấy nó từ bản phát hành trước đó.
  2. Giải nén nó. Trong terminal của bạn: tar -xzf openspec-darwin-arm64.tar.gz. Trên Windows, nhấp chuột phải vào .zip và chọn Extract All.
  3. Trên macOS, hãy chạy xattr -d com.apple.quarantine openspec trong thư mục bạn đã giải nén. macOS chặn các tệp được tải xuống qua trình duyệt cho đến khi bạn thực hiện thao tác này.
  4. Di chuyển openspec vào một thư mục trên PATH của bạn, chẳng hạn như ~/.local/bin. Trên Windows, di chuyển openspec.exe vào một thư mục trên PATH người dùng của bạn, chẳng hạn như %LOCALAPPDATA%\Programs\openspec.

Xác minh một lần tải xuống ​

Để kiểm tra xem một tệp có được xây dựng bởi quy trình phát hành OpenSpec hay không, hãy chạy lệnh này với GitHub CLI:

bash
gh attestation verify openspec-darwin-arm64.tar.gz --repo Fission-AI/OpenSpec

Nó sẽ thất bại nếu quy trình không xây dựng tệp đó. Lệnh cài đặt đã kiểm tra từng lần tải xuống đối với SHA256SUMS của bản phát hành, vì vậy bước này là tùy chọn.

Chuyển từ npm sang cài đặt độc lập ​

Việc chuyển đổi là tùy chọn; npm vẫn hoạt động. Các cài đặt và dự án của bạn sẽ được chuyển tiếp; chỉ có chương trình thay đổi.

1. Cài đặt bản sao độc lập. Trong terminal của bạn:

bash
openspec install

Nó sẽ cài đặt openspec độc lập và in ra lệnh xóa bản sao npm hoặc Homebrew của bạn.

2. Xóa bản sao cũ. Nó thường đứng đầu trong PATH của bạn, vì vậy cho đến khi nó bị xóa, nó sẽ tiếp tục chạy thay thế. Chạy lệnh mà bước 1 đã in, ví dụ:

npm
npm uninstall -g @fission-ai/openspec

3. Kiểm tra xem bản sao nào đang chạy. Mở một terminal mới:

bash
openspec version

Nó nên in ra OpenSpec <version> (standalone). Nếu nó nêu tên một trình quản lý gói thay thế, thì vẫn còn một bản sao khác trên PATH của bạn: which -a openspec (Windows: where.exe openspec) liệt kê mọi bản sao, vì vậy hãy xóa các bản sao khác.

Không cần khởi tạo lại dự án nào. Để quay lại, hãy xóa tệp và chạy lại lệnh cài đặt npm.

Cập nhật ​

Trong terminal của bạn, trong mỗi dự án nơi bạn đã chạy init:

bash
openspec update

Khi có CLI mới hơn, openspec update sẽ thông báo và có thể cài đặt nó cho bạn; bản nâng cấp này chỉ diễn ra một lần cho mỗi máy. Mọi lần chạy đều làm mới các kỹ năng và lệnh được tạo của dự án, những thứ này không tự cập nhật. Một dự án hiện tại sẽ in ra ✓ All 2 tool(s) up to date (v1.7.0).

WARNING

Với cài đặt độc lập, hãy chạy openspec install để thay thế bản sao của bạn tại chỗ; openspec update sẽ cho bạn biết khi có phiên bản mới hơn. Trên Homebrew, hãy chạy brew upgrade openspec. Trên Deno, hãy chạy lại cài đặt Deno với -f; nó sẽ không ghi đè lệnh đã cài đặt nếu không có cờ này. Trên Nix, hãy sử dụng nix profile upgrade openspec.

NOTE

Một cài đặt npm toàn cục thuộc về một cài đặt Node. Chuyển đổi các phiên bản Node với nvm và lệnh openspec sẽ không đi kèm, vì vậy hãy cài đặt lại nó dưới phiên bản mới.

Gỡ bỏ ​

Để gỡ bỏ OpenSpec, hãy thực hiện qua các bước bên dưới; không có bước nào trong số đó chạm vào mã nguồn của bạn. Bạn cũng có thể trỏ tác nhân của mình vào phần này và để nó xử lý việc gỡ bỏ.

1. Xóa hoàn thiện shell, nếu bạn đã thiết lập chúng, trong khi CLI vẫn có thể thực hiện được. Trong terminal của bạn:

bash
openspec completion uninstall

2. Xóa CLI. Đối với cài đặt độc lập, hãy xóa ~/.local/bin/openspec (Windows: %LOCALAPPDATA%\Programs\openspec, và xóa thư mục đó khỏi PATH người dùng của bạn). Đối với npm, trong terminal của bạn:

npm
npm uninstall -g @fission-ai/openspec

Trên Homebrew: brew uninstall openspec. Trên Deno: deno uninstall --global openspec. Trên Nix: nix profile remove openspec. Shell của bạn sẽ không còn tìm thấy openspec.

3. Xóa những gì còn lại, hoặc giữ lại.

  • Các tệp tác nhân được tạo: các kỹ năng openspec-* và các lệnh opsx dưới các thư mục như .claude/ hoặc .agents/, theo dự án. Các công cụ được hỗ trợ liệt kê đường dẫn của từng công cụ; MiniMax Code giữ các kỹ năng trong ~/.minimax/skills.
  • Các phần dư thừa từ các phiên bản cũ hơn: các khối đánh dấu trong CLAUDE.md hoặc AGENTS.md (xóa khối, giữ tệp) và các lời nhắc opsx-*.md trong ~/.codex/prompts.
  • Thư mục openspec/: hãy tạm dừng trước. specs/ và changes/archive/ là hồ sơ hệ thống của bạn, Markdown thuần túy đọc tốt mà không cần OpenSpec.
  • Trạng thái theo máy: cài đặt và id telemetry trong ~/.config/openspec/; các ghi đè lược đồ, đăng ký cửa hàng và các lược đồ tích hợp sẵn của cài đặt độc lập (binary-schemas/) trong ~/.local/share/openspec/ (Windows: %APPDATA%\openspec, %LOCALAPPDATA%\openspec). Các đăng ký là các con trỏ; các kho lưu trữ cửa hàng mà chúng trỏ tới vẫn không thay đổi.