Lược đồ

Thay đổi những gì OpenSpec tạo ra: các artifact, thứ tự của chúng và các template của chúng.

Một lược đồ xác định những gì một đề xuất thay đổi tạo ra: những artifact nào, theo thứ tự nào, từ những template nào. Ví dụ, spec-driven, lược đồ mặc định được đóng gói, tạo ra bốn artifact này theo thứ tự gần như sau, mỗi cái xây dựng dựa trên cái trước đó:

proposal → specs → design → tasks

Fork một lược đồ khi bạn muốn chúng thành các tài liệu khác nhau, cho dù điều đó có nghĩa là ít hơn, tên khác nhau hay cấu trúc khác nhau.

Lược đồ nằm ở đâu

OpenSpec tìm kiếm lược đồ ở ba nơi, theo thứ tự, và sử dụng cái đầu tiên nó tìm thấy:

1. Dự án của bạn: openspec/schemas/, được commit cùng với repo để cả nhóm của bạn đều có nó.
2. Máy tính của bạn: ~/.local/share/openspec/schemas trên macOS và Linux (hoặc dưới $XDG_DATA_HOME nếu bạn đặt nó), hoặc %LOCALAPPDATA%\openspec\schemas trên Windows. Các lược đồ ở đây có sẵn trong mọi dự án bạn làm việc.
3. Gói: các lược đồ tích hợp, như spec-driven, được đóng gói bên trong openspec.

Cùng một tên có thể tồn tại ở nhiều nơi, và vị trí cụ thể hơn sẽ thắng. openspec schema which hiển thị bản sao nào đang được sử dụng:

$ openspec schema which spec-driven
Schema: spec-driven
Source: project
Path: /your-project/openspec/schemas/spec-driven

Shadows:
  package: .../openspec/schemas/spec-driven

Trong lược đồ có gì

Một lược đồ được xác định bởi một thư mục các tệp đơn giản: một schema.yaml khai báo các artifact, và một template cho mỗi artifact. Đây là spec-driven tích hợp:

spec-driven/
├── schema.yaml
└── templates/
    ├── proposal.md
    ├── spec.md
    ├── design.md
    └── tasks.md

• schema.yaml: khai báo mỗi artifact, tệp nó tạo ra, template nó bắt đầu từ, cái nó yêu cầu trước, và chỉ dẫn mà agent nhận được khi tạo nó. Hợp đồng của mỗi trường là trong schema.yaml.
• templates/: một bộ khung markdown cho mỗi artifact, mà agent điền vào.

Đây là mục nhập của artifact tasks trong schema.yaml, đã được cắt giảm:

artifacts:
  - id: tasks
    generates: tasks.md
    description: Checklist triển khai với các nhiệm vụ có thể theo dõi
    template: tasks.md
    instruction: |
      ...những gì agent được hướng dẫn khi tạo tasks.md...
    requires:
      - specs
      - design

Các lược đồ tích hợp được đóng gói bên trong gói openspec, vì vậy bạn không bao giờ chỉnh sửa chúng tại chỗ. Bạn có bản sao của riêng mình bằng cách fork.

Tạo lược đồ tùy chỉnh của riêng bạn

Có hai cách để có lược đồ của riêng bạn:

1. Fork một lược đồ hiện có và chỉnh sửa bản sao của bạn. Bắt đầu ở đây khi một lược đồ hiện có gần với những gì bạn muốn, vì mọi thứ trong nó đã hoạt động.
2. Bắt đầu từ đầu khi không cái nào phù hợp, tạo một lược đồ trống với openspec schema init.

Fork một lược đồ hiện có

1. Fork lược đồ bạn muốn bắt đầu từ, chạy từ thư mục gốc dự án của bạn:

   $ openspec schema fork spec-driven
   
   Note: Schema commands are experimental and may change.
   ✔ Forked 'spec-driven' to 'spec-driven-custom'
   
   Source: .../openspec/schemas/spec-driven (package)
   Destination: /your-project/openspec/schemas/spec-driven-custom

   Truyền đối số thứ hai để chọn tên (openspec schema fork spec-driven team-flow). Tên là kebab-case.

2. Chỉnh sửa bản sao: schema.yaml và các template. Chỉnh sửa fork của bạn đề cập đến những gì cần thay đổi.

3. Xác thực nó:

   openspec schema validate spec-driven-custom

   Đây là lệnh duy nhất bắt được lược đồ bị hỏng (thiếu template, YAML xấu, vòng lặp phụ thuộc) trước khi bạn ở giữa một thay đổi.

4. Trỏ dự án của bạn vào nó trong openspec/config.yaml. Bước này là của bạn để làm vì fork để nguyên config.yaml:

   schema: spec-driven-custom

5. Các đề xuất thay đổi mới bây giờ theo lược đồ của bạn. Các thay đổi tạo ra trước đó giữ lược đồ mà chúng bắt đầu.

Để thay thế mặc định ở khắp nơi mà không chạm vào config.yaml, fork với cùng tên: openspec schema fork spec-driven spec-driven. Bản sao dự án của bạn sau đó che lấp lược đồ tích hợp, như Lược đồ nằm ở đâu giải thích.

Bắt đầu từ đầu

openspec schema init tạo khung cho một lược đồ mới thay vì sao chép một cái:

$ openspec schema init lite --description "Lite flow" --artifacts proposal,tasks

✔ Created schema 'lite'
Schema created at: /your-project/openspec/schemas/lite
Artifacts: proposal, tasks

Khung trống rỗng. Các artifact chỉ đến từ bốn id tích hợp, và các template được tạo không mang chỉ dẫn nào, vì vậy agent nhận được ít hướng dẫn hơn cho đến khi bạn viết chỉ dẫn của riêng mình. Từ đó các bước fork áp dụng không đổi: xác thực nó, sau đó trỏ config.yaml vào nó.

Chỉnh sửa fork của bạn

Một fork có hai loại tệp để chỉnh sửa:

• templates/ thay đổi bộ khung của mỗi tài liệu. Thêm một phần vào template tasks và mỗi tasks.md mới bắt đầu với nó. Giữ tiêu đề # ở dòng đầu tiên: artifact kế thừa nó, vì vậy mỗi tệp được tạo mở ra như một tài liệu có tiêu đề.
• schema.yaml thay đổi chính quy trình: những artifact nào tồn tại, mỗi cái yêu cầu gì trước, và chỉ dẫn mà agent nhận được khi tạo nó.

Ví dụ, để bỏ tài liệu design cho quy trình tinh gọn hơn:

1. Xóa mục design khỏi schema.yaml.

2. Xóa design khỏi danh sách requires của tasks.

3. Xác thực:

   $ openspec schema validate spec-driven-custom
   
   ✓ Schema 'spec-driven-custom' is valid

Bỏ qua bước 2 và validate bắt được nó:

✗ Schema 'spec-driven-custom' has errors:
  error: Invalid dependency reference in artifact 'tasks': 'design' does not exist

Xác thực sau mỗi lần chỉnh sửa thủ công. Nếu không, lược đồ bị hỏng sẽ xuất hiện ở giữa một thay đổi, khi một quy trình yêu cầu một tệp không tồn tại. Giống như config.yaml, các chỉnh sửa schema đến được với agent ở lần chạy tiếp theo.

Một fork là một ảnh chụp

openspec update làm mới các kỹ năng và lệnh đã cài đặt, và nó không bao giờ chạm vào openspec/schemas/. Fork của bạn tiếp tục hoạt động đúng như bạn để lại, điều đó cũng có nghĩa là nó ngừng nhận các cải tiến khi lược đồ tích hợp phát triển. Để nhận chúng sau, fork lược đồ tích hợp lại dưới tên mới và chuyển các khác biệt sang.

Chia sẻ lược đồ

Chia sẻ một lược đồ có nghĩa là sao chép thư mục của nó.

• Với nhóm của bạn: commit openspec/schemas/ và mọi người trên repo sử dụng nó.
• Giữa các dự án của bạn: đặt thư mục vào thư mục cấp người dùng từ Lược đồ nằm ở đâu.
• Từ cộng đồng: danh mục cộng đồng liệt kê các lược đồ được chia sẻ. Sao chép một cái vào openspec/schemas/<name> và nó hoạt động như của riêng bạn.

Chúng tôi đang làm việc trên một registry lược đồ, công khai và riêng tư, để các lược đồ có thể được cài đặt theo tên thay vì sao chép thủ công.

Sử dụng OpenSpec với Superpowers

Lược đồ superpowers-bridge được cộng đồng duy trì kết nối các artifact OpenSpec với các kỹ năng thực thi Superpowers. Làm theo ghi chú cài đặt và tương thích của bridge trước khi sao chép nó vào dự án của bạn.

Bridge được phát hành bên ngoài OpenSpec. OpenSpec không kiểm thử hoặc phiên bản hóa tích hợp Superpowers của nó.