AgentSkillsCN

openspec-bulk-archive-change

同时保存多项已完成的变更。当需要并行保存多个变更时，可使用此技能。

SKILL.md
--- frontmatter
name: openspec-bulk-archive-change
description: Lưu trữ hàng loạt các thay đổi đã hoàn thành cùng một lúc. Sử dụng khi cần lưu trữ nhiều thay đổi song song.
license: MIT
compatibility: Yêu cầu openspec CLI.
metadata:
  author: openspec
  version: "1.0"
  generatedBy: "1.0.2"

Lưu trữ nhiều thay đổi đã hoàn thành trong một thao tác duy nhất.

Skill này cho phép bạn lưu trữ hàng loạt các thay đổi, xử lý các xung đột spec một cách thông minh bằng cách kiểm tra codebase để xác định những gì thực tế đã được thực hiện (implemented).

Đầu vào: Không yêu cầu (sẽ có thông báo yêu cầu chọn).

Các bước

  1. •

    Lấy danh sách các thay đổi đang hoạt động (active changes)

    Chạy lệnh openspec list --json để lấy tất cả các thay đổi đang hoạt động.

    Nếu không có thay đổi nào đang hoạt động, hãy thông báo cho người dùng và dừng lại.

  2. •

    Yêu cầu chọn các thay đổi

    Sử dụng công cụ AskUserQuestion với tính năng chọn nhiều (multi-select) để người dùng chọn các thay đổi:

    • •Hiển thị mỗi thay đổi kèm theo schema của nó.
    • •Bao gồm tùy chọn "Tất cả các thay đổi" (All changes).
    • •Cho phép chọn số lượng bất kỳ (1+ là được, 2+ là trường hợp sử dụng điển hình).

    QUAN TRỌNG: KHÔNG được tự động chọn. Luôn để người dùng quyết định.

  3. •

    Xác thực hàng loạt - thu thập trạng thái cho tất cả các thay đổi đã chọn

    Với mỗi thay đổi được chọn, hãy thu thập:

    a. Trạng thái artifact - Chạy lệnh openspec status --change "<name>" --json.

    • •Phân tích schemaName và danh sách artifacts.
    • •Ghi chú xem artifact nào đã done so với các trạng thái khác.

    b. Hoàn thành task - Đọc file openspec/changes/<name>/tasks.md.

    • •Đếm số lượng - [ ] (chưa xong) so với - [x] (đã xong).
    • •Nếu không có file task, ghi chú là "Không có task" (No tasks).

    c. Delta specs - Kiểm tra thư mục openspec/changes/<name>/specs/.

    • •Liệt kê các capability spec nào đang tồn tại.
    • •Với mỗi spec, trích xuất tên yêu cầu (các dòng khớp với ### Requirement: <name>).
  4. •

    Phát hiện xung đột spec

    Xây dựng một bản đồ capability -> [danh sách các thay đổi tác động đến nó]:

    code
    auth -> [change-a, change-b]  <- XUNG ĐỘT (2+ thay đổi)
api  -> [change-c]            <- OK (chỉ có 1 thay đổi)

    Xung đột xảy ra khi có 2+ thay đổi được chọn có delta spec cho cùng một capability.

  5. •

    Giải quyết xung đột một cách thông minh (agentically)

    Đối với mỗi xung đột, hãy điều tra codebase:

    a. Đọc các delta spec từ mỗi thay đổi đang xung đột để hiểu những gì mỗi bên tuyên bố sẽ thêm/sửa.

    b. Tìm kiếm bằng chứng implementation trong codebase:

    • •Tìm code triển khai các yêu cầu (requirements) từ mỗi delta spec.
    • •Kiểm tra các file, hàm hoặc test liên quan.

    c. Xác định cách giải quyết:

    • •Nếu chỉ có một thay đổi thực tế được triển khai -> đồng bộ spec của thay đổi đó.
    • •Nếu cả hai đều được triển khai -> áp dụng theo thứ tự thời gian (cái cũ trước, cái mới ghi đè).
    • •Nếu cả hai đều chưa được triển khai -> bỏ qua đồng bộ spec, cảnh báo cho người dùng.

    d. Ghi lại giải pháp cho mỗi xung đột:

    • •Spec của thay đổi nào sẽ được áp dụng.
    • •Theo thứ tự nào (nếu cả hai đều được triển khai).
    • •Lý do (những gì đã tìm thấy trong codebase).
  6. •

    Hiển thị bảng trạng thái hợp nhất

    Hiển thị một bảng tóm tắt tất cả các thay đổi:

    code
    | Thay đổi            | Artifacts | Tasks | Specs   | Xung đột   | Trạng thái |
|---------------------|-----------|-------|---------|------------|------------|
| schema-management   | Xong      | 5/5   | 2 delta | Không      | Sẵn sàng   |
| project-config      | Xong      | 3/3   | 1 delta | Không      | Sẵn sàng   |
| add-oauth           | Xong      | 4/4   | 1 delta | auth (!)   | Sẵn sàng*  |
| add-verify-skill    | Còn 1     | 2/5   | Không   | Không      | Cảnh báo   |

    Đối với các xung đột, hãy hiển thị giải pháp:

    code
    * Giải quyết xung đột:
  - auth spec: Sẽ áp dụng add-oauth sau đó là add-jwt (cả hai đều được triển khai, theo thứ tự thời gian)

    Đối với các thay đổi chưa hoàn thiện, hiển thị cảnh báo:

    code
    Cảnh báo:
- add-verify-skill: 1 artifact chưa xong, 3 task chưa xong
  7. •

    Xác nhận thao tác hàng loạt

    Sử dụng công cụ AskUserQuestion để thực hiện một lần xác nhận duy nhất:

    • •"Lưu trữ N thay đổi?" kèm theo các lựa chọn dựa trên trạng thái.
    • •Các lựa chọn có thể bao gồm:
      • •"Lưu trữ tất cả N thay đổi"
      • •"Chỉ lưu trữ N thay đổi đã sẵn sàng (bỏ qua những cái chưa xong)"
      • •"Hủy bỏ"

    Nếu có các thay đổi chưa hoàn thiện, hãy nêu rõ rằng chúng sẽ được lưu trữ kèm theo cảnh báo.

  8. •

    Thực thi lưu trữ cho mỗi thay đổi đã được xác nhận

    Xử lý các thay đổi theo thứ tự đã xác định (tôn trọng giải pháp xung đột):

    a. Đồng bộ spec nếu delta spec tồn tại:

    • •Sử dụng phương pháp từ openspec-sync-specs (hợp nhất thông minh do agent điều khiển).
    • •Đối với các xung đột, áp dụng theo thứ tự đã giải quyết.
    • •Theo dõi xem việc đồng bộ đã được thực hiện hay chưa.

    b. Thực hiện lưu trữ:

    bash
    mkdir -p openspec/changes/archive
mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>

    c. Theo dõi kết quả cho mỗi thay đổi:

    • •Thành công: đã lưu trữ thành công.
    • •Thất bại: lỗi trong quá trình lưu trữ (ghi lại lỗi).
    • •Đã bỏ qua: người dùng chọn không lưu trữ (nếu có).
  9. •

    Hiển thị tóm tắt

    Hiển thị kết quả cuối cùng:

    code
    ## Hoàn tất lưu trữ hàng loạt

Đã lưu trữ 3 thay đổi:
- schema-management-cli -> archive/2026-01-19-schema-management-cli/
- project-config -> archive/2026-01-19-project-config/
- add-oauth -> archive/2026-01-19-add-oauth/

Đã bỏ qua 1 thay đổi:
- add-verify-skill (người dùng chọn không lưu trữ những gì chưa hoàn thiện)

Tóm tắt đồng bộ spec:
- 4 delta spec đã được đồng bộ vào spec chính
- 1 xung đột đã được giải quyết (auth: áp dụng cả hai theo thứ tự thời gian)

    Nếu có bất kỳ thất bại nào:

    code
    Thất bại 1 thay đổi:
- some-change: Thư mục lưu trữ mục tiêu đã tồn tại

Ví dụ về Giải quyết Xung đột

Ví dụ 1: Chỉ có một cái được triển khai

code
Xung đột: specs/auth/spec.md bị tác động bởi [add-oauth, add-jwt]

Kiểm tra add-oauth:
- Delta thêm yêu cầu "OAuth Provider Integration"
- Tìm kiếm trong codebase... tìm thấy src/auth/oauth.ts triển khai luồng OAuth

Kiểm tra add-jwt:
- Delta thêm yêu cầu "JWT Token Handling"
- Tìm kiếm trong codebase... không tìm thấy implementation của JWT

Giải quyết: Chỉ có add-oauth là được triển khai. Sẽ chỉ đồng bộ spec của add-oauth.

Ví dụ 2: Cả hai đều được triển khai

code
Xung đột: specs/api/spec.md bị tác động bởi [add-rest-api, add-graphql]

Kiểm tra add-rest-api (tạo ngày 2026-01-10):
- Delta thêm yêu cầu "REST Endpoints"
- Tìm kiếm trong codebase... tìm thấy src/api/rest.ts

Kiểm tra add-graphql (tạo ngày 2026-01-15):
- Delta thêm yêu cầu "GraphQL Schema"
- Tìm kiếm trong codebase... tìm thấy src/api/graphql.ts

Giải quyết: Cả hai đều được triển khai. Sẽ áp dụng spec của add-rest-api trước,
sau đó đến spec của add-graphql (thứ tự thời gian, cái mới hơn ghi đè cái cũ).

Đầu ra khi thành công

code
## Hoàn tất lưu trữ hàng loạt

Đã lưu trữ N thay đổi:
- <change-1> -> archive/YYYY-MM-DD-<change-1>/
- <change-2> -> archive/YYYY-MM-DD-<change-2>/

Tóm tắt đồng bộ spec:
- N delta spec đã được đồng bộ vào spec chính
- Không có xung đột (hoặc: M xung đột đã được giải quyết)

Đầu ra khi thành công một phần

code
## Hoàn tất lưu trữ hàng loạt (một phần)

Đã lưu trữ N thay đổi:
- <change-1> -> archive/YYYY-MM-DD-<change-1>/

Đã bỏ qua M thay đổi:
- <change-2> (người dùng chọn không lưu trữ những gì chưa hoàn thiện)

Thất bại K thay đổi:
- <change-3>: Thư mục lưu trữ mục tiêu đã tồn tại

Đầu ra khi không có thay đổi nào

code
## Không có thay đổi nào để lưu trữ

Không tìm thấy thay đổi nào đang hoạt động. Sử dụng `/opsx:new` để tạo một thay đổi mới.

Nguyên tắc an toàn (Guardrails)

  • •Cho phép số lượng thay đổi bất kỳ (1+ là được, 2+ là trường hợp điển hình).
  • •Luôn yêu cầu chọn, không bao giờ tự động chọn.
  • •Phát hiện xung đột spec sớm và giải quyết bằng cách kiểm tra codebase.
  • •Khi cả hai thay đổi đều được triển khai, áp dụng spec theo thứ tự thời gian.
  • •Chỉ bỏ qua đồng bộ spec khi thiếu bằng chứng implementation (cần cảnh báo người dùng).
  • •Hiển thị rõ trạng thái của từng thay đổi trước khi xác nhận.
  • •Sử dụng một lần xác nhận duy nhất cho cả một lô (batch).
  • •Theo dõi và báo cáo tất cả các kết quả (thành công/bỏ qua/thất bại).
  • •Giữ lại file .openspec.yaml khi di chuyển vào archive.
  • •Thư mục lưu trữ mục tiêu sử dụng ngày hiện tại: YYYY-MM-DD-<tên>.
  • •Nếu mục tiêu lưu trữ đã tồn tại, thay đổi đó sẽ bị thất bại nhưng vẫn tiếp tục với các thay đổi khác.