Trang này được dịch từ tài liệu tiếng Anh. Lệnh, định danh và ví dụ giữ nguyên. Runtime 7.24.4 · SDK 2.6.7. Bản tiếng Anh

Bảo đảm mục tiêu

Trạng thái: Hiện hành Phạm vi: kiểm tra chấp nhận mục tiêu và độ mới nguồn Xem xét lần cuối: 2026-09-14 Chủ sở hữu: người bảo trì runtime AX Code

Các kế hoạch thay đổi mã do bộ lập kế hoạch mục tiêu tạo ra khai báo các kiểm tra chấp nhận có thể thực thi. Mỗi kiểm tra nêu kết quả nó phủ, đúng lệnh, mục đích và môi trường dự định. AX Code ghi bằng chứng thực thi khi tác nhân chạy verify_project với mã goalCheck của kiểm tra.

{ "goalCheck": "invoice-parity" }

Lệnh đến từ kế hoạch mục tiêu đã đóng băng. Tác nhân không thể thay nó bằng một lệnh khác qua lần gọi này. Quyền bash hiện có vẫn áp dụng. Hoàn thành mục tiêu đòi hỏi lần thử mới nhất của mọi kiểm tra đã khai báo đều đạt với mục tiêu, phiên, không gian làm việc, hợp đồng và nội dung nguồn khớp. Văn xuôi chấp nhận giải thích kết quả; nó không thay các kiểm tra đã thực thi. Các lần chạy shell thông thường và các kiểm tra bị bỏ hoàn toàn không thể cung cấp bằng chứng này.

Các kế hoạch mục tiêu cũ không có bảo đảm giữ quy tắc hoàn thành trước đó của chúng. Hãy xóa và tạo lại một mục tiêu cũ khi bạn cần hợp đồng mới; sửa các yêu cầu đã đóng băng của nó tại chỗ sẽ gây lệch hợp đồng. Một nhánh rẽ giữ hợp đồng nhưng cần các lần chạy kiểm tra mới trong phiên mới.

Chuẩn bị một dự án di chuyển

Hãy cung cấp nguồn hoặc bản xuất kế thừa có thẩm quyền kèm mã bản sửa, một kiểm kê độ phủ có giới hạn, và các tập lệnh kiểm tra thất bại khi khẳng định không xác minh được. Hãy coi chú thích và các lần triển khai di chuyển trước là manh mối cần điều tra. Ghi các thay đổi hành vi đã phê duyệt tách khỏi yêu cầu tương đương với hệ kế thừa.

Chọn kiểm tra cho các tầng mà thay đổi được yêu cầu thực sự ảnh hưởng:

Tập lệnh phải khẳng định danh tính đích trước khi thực hiện kiểm tra của chúng. Giữ thông tin xác thực trong cơ chế thông tin xác thực hiện có của dự án, không bao giờ trong văn bản kế hoạch, lệnh hoặc mô tả đích. Một kiểm tra nên trả mã thoát khác không cho một khẳng định thất bại, môi trường thiếu hoặc khẳng định bắt buộc bị bỏ. Tránh các lớp bọc che lỗi. AX Code không thể suy ra khẳng định từ một lần thoát tiến trình thành công.

Với các lần di chuyển lớn, hãy tổ chức việc thành các lô luồng nghiệp vụ có giới hạn và duy trì một kiểm kê nối biểu mẫu, phụ thuộc, tham chiếu kế thừa và kiểm tra chấp nhận. Hãy báo cả lô đã chấp nhận lẫn độ phủ còn lại. Đạt một lô không hoàn thành toàn bộ lần di chuyển.

Kế hoạch ghi những gì

Bộ lập kế hoạch cung cấp một đối tượng assurance. Đoạn minh họa này giả định dự án có bản xuất nguồn và tập lệnh kiểm tra được tham chiếu:

{
  "version": 1,
  "sourcePaths": ["src", "checks", "package.json"],
  "sources": [
    { "role": "legacy", "reference": "legacy/invoice-schema.sql at export-v1" },
    { "role": "requirement", "reference": "Invoice acceptance criteria supplied by the user" }
  ],
  "checks": [
    {
      "id": "invoice-parity",
      "acceptanceIds": ["AC1"],
      "command": "node checks/invoice-parity.cjs",
      "purpose": "Assert invoice behavior, database mappings and target identity",
      "environment": "Staging migration target, schema ERP"
    }
  ]
}

Mọi mã chấp nhận đều phải được phủ. Lệnh thực thi từ gốc không gian làm việc. Đối tượng bảo đảm được đóng băng cùng hợp đồng chấp nhận. Tác nhân nhận phạm vi đã xác thực, tham chiếu nguồn, mã kiểm tra và đích đã khai báo trong ngữ cảnh mục tiêu tiếp theo của nó. Hợp đồng thiếu hoặc bị đổi tạo một thông báo khôi phục. Các bản tóm tắt hội thoại đã sinh vẫn có thể sai; tham chiếu đã khai báo và nhãn đích là yêu cầu, không phải sự kiện được quan sát độc lập.

Các phạm vi Git đo việc mục tiêu này đã đổi phải dùng {BASELINE} làm trạng thái trước. Bộ lập kế hoạch viết lại chỗ giữ đó thành SHA HEAD được chụp khi kế hoạch được gửi, nên các commit đã có trước origin/main hoặc một cây làm việc bẩn không thể làm mục tiêu không thể hoàn thành. Các ref theo dõi từ xa (origin/main, @{u}, refs/remotes/…) bị từ chối làm trạng thái trước đó trừ khi mục tiêu nêu đích từ xa. Hãy ghi các đường đã lệch hoặc bẩn dưới Rủi ro; đừng đóng băng một kiểm tra cổng vốn đã thất bại trừ khi mục tiêu là sửa chính lỗi đó.

Độ mới và giới hạn

Vân tay nguồn Git gồm byte thực của tệp đã theo dõi và tệp chưa theo dõi không bị bỏ qua trong sourcePaths đã khai báo. Đường dẫn tệp tường minh cũng gồm tệp cấu hình bị bỏ qua; đường dẫn thư mục giữ quy tắc bỏ qua của Git. Danh sách kiểm tra kế hoạch mục tiêu có thể đổi bị loại; yêu cầu đã đóng băng của chúng được kiểm tra qua digest hợp đồng. Dự án không phải Git lấy vân tay đệ quy sourcePaths đã khai báo, kể cả đường dẫn thiếu. Hãy gồm mọi nguồn, tệp cấu hình và tập lệnh kiểm tra liên quan trong phạm vi đó.

Lấy vân tay giới hạn 20,000 mục và 128 MiB nội dung tệp. Nguồn liên kết, kho Git lồng, tệp đặc biệt, đường thoát, tệp đang đổi và các lần đọc không có không thể tạo bằng chứng mới. Các lỗi như vậy chặn hoàn thành đã bảo đảm. Tạo tác đầu ra kiểm tra nên đi tới một vị trí bị bỏ qua để việc tạo báo cáo không đổi nguồn đang được xác minh.

Tệp bị bỏ qua không được nêu tường minh, phụ thuộc ngoài phạm vi nguồn, cơ sở dữ liệu và triển khai cần khẳng định trong lệnh dự án. Một biên nhận ghi một quan sát tại thời điểm thực thi của nó; nó không chứng minh trạng thái bên ngoài vẫn không đổi. Hãy chạy lại các kiểm tra bị ảnh hưởng sau khi đổi cấu hình, cơ sở dữ liệu hoặc triển khai. AX Code không tự khám phá mọi hành vi kế thừa hay chứng nhận tương đương di chuyển.

Khi nào việc lập kế hoạch chạy

Lập kế hoạch là chọn tham gia trên cả hai bề mặt. /goal <objective> và create_goal không có assure sẽ bắt đầu mục tiêu ngay: nó không mang tiêu chí chấp nhận đã đóng băng, và hoàn thành được phán theo kế hoạch làm việc (việc chờ) cộng một lần xác minh đạt sau thay đổi cuối. /goal --assure <objective> và create_goal với assure: true chạy người viết kế hoạch trước, và đó là điều làm các biên nhận kiểm tra đã thực thi bên dưới trở thành yêu cầu hoàn thành.

Một mục tiêu không có hợp đồng nói điều đó ở mọi nơi nó được hiện (/goal view, hộp thoại mục tiêu, các thông điệp điều khiển), nên cổng hoàn thành của nó không bao giờ là thứ bạn phải suy ra. /goal replace giữ bảo đảm khi mục tiêu bị thay có hợp đồng hợp lệ.

Ngữ cảnh lập kế hoạch và chọn mô hình

Lập kế hoạch mục tiêu kế thừa mô hình phiên đã chọn qua cả /goal và công cụ create_goal. Các biến thể bên gọi tương thích được giữ. Người viết chỉ đọc nhận các yêu cầu người dùng gốc gần đây và tham chiếu tệp đính kèm, với ngân sách hồ sơ 16 KiB. Một hồ sơ quá cỡ dừng việc gồm các hồ sơ cũ hơn, kèm thông báo, để yêu cầu cũ hơn không thể âm thầm thay một chỉnh sửa bị bỏ; nội dung phương tiện nội tuyến không được coi là bằng chứng đã kiểm. Hãy cung cấp tệp nguồn có thể kiểm cho các yêu cầu chỉ có trong phương tiện.

Tiến độ và các chặn

get_goal gồm trạng thái kiểm tra hiện tại (đạt, thất bại, cũ, đang chạy hoặc thiếu) và mã bằng chứng công cụ gần đây. Cổng hoàn thành vẫn cần các biên nhận thành công hiện tại. Một cập nhật bị chặn cần loại chặn, lý do, thay đổi bên ngoài bắt buộc, mã bằng chứng gốc, và xác nhận không còn việc độc lập. Lý do chặn là khai báo của mô hình được hồ sơ có thể kiểm chống lưng, không phải chứng nhận rằng một dịch vụ bên ngoài vẫn không khả dụng.

Các lượt đã kết lặp lại không tạo bằng chứng công cụ thành công mới sẽ nhận hướng dẫn khôi phục, rồi tạm dừng mục tiêu với việc chưa xong được công bố. Kết quả nghiên cứu mới có thể được tính mà không sửa nguồn; viết lại việc chờ và kết quả giống hệt lặp lại thì không. Đây là heuristic có giới hạn, không phải chứng cứ tiến bộ ngữ nghĩa. /goal resume bắt đầu một lần thử khác. Các lần gọi công cụ được sinh cho một mục tiêu trước không thể kết thúc mục tiêu thay thế nó. Một mục tiêu do công cụ tạo có sẵn cho cập nhật trạng thái sau khi mô hình đã nhận kết quả tạo ở bước kế tiếp.

Sửa một kế hoạch hiện có

Dùng /goal revise <correction> để sửa tường minh một mục tiêu đã đóng băng đang hoạt động, tạm dừng hoặc bị chặn. Việc đã hoàn thành và ngân sách đã cạn cần một mục tiêu mới. Kế hoạch và digest trước vẫn nguyên. Kế hoạch đã sửa nhận danh tính mới và một hồ sơ bản sửa đã chuẩn bị cục bộ nối cả hai digest cùng phần chỉnh. Danh tính mục tiêu hiện tại quyết định ứng viên nào thực sự được cài; các ứng viên đồng thời thất bại có thể còn trên đĩa để kiểm. Biên nhận cũ vẫn trong lịch sử và không thể thỏa bản sửa mới. Ngân sách token và mức dùng đã tích lũy được chuyển tiếp; sửa không cấp một ngân sách chi tiêu mới.

Việc sửa hủy lần chạy hiện tại và tạm dừng mục tiêu trong lúc chuẩn bị kế hoạch mới. Nếu lập kế hoạch thất bại, hợp đồng trước vẫn có thể tiếp tục; một mục tiêu đã bị chặn trước đó giữ trạng thái đó. Người dùng tạm dừng hoặc hủy trong lúc lập kế hoạch sẽ ngăn kích hoạt. Một sự thay thế đồng thời ngăn ứng viên chiếm quyền. Công cụ mô hình không thể sửa âm thầm các yêu cầu đã đóng băng. Hãy rà soát kế hoạch kết quả và tiêu chí chấp nhận của nó; chỉ một lệnh thực thi được không thiết lập rằng các khẳng định của nó phủ yêu cầu đã chỉnh.

Kết quả rà soát và thay đổi nguồn sau đó

Một nhật ký rà soát không rỗng không thiết lập rà soát thành công. Với người rà soát bên ngoài bắt buộc, hãy dùng một kiểm tra do dự án sở hữu để xác thực đúng mã thoát, hoàn thành terminal, danh tính nguồn hoặc diff, và phát hiện cuối hoặc một phán quyết không-phát-hiện tường minh. Nhật ký chỉ cảnh báo, suy luận một phần và hết thời gian phải thất bại. Hãy giữ các lần thử thất bại riêng để chẩn đoán.

Các lần gửi thay đổi mã mới từ chối các kiểm tra hiện diện tệp đơn giản và kiểm tra đã nhận ra. Đây là một chốt tiếp nhận hẹp, không phải chứng cứ ngữ nghĩa cho lệnh shell tùy ý. Hợp đồng đã đóng băng hiện có giữ lược đồ và digest của chúng; điểm kiểm tra cảnh báo khi một kiểm tra cũ có điểm yếu này.

Độ mới kiểm tra mục tiêu cũng lấy vân tay các đường dẫn tệp đã phân giải do công cụ sửa tệp thành công báo trong mục tiêu hiện tại, kể cả mọi kết quả multiedit và các đường bị bỏ khỏi danh sách nguồn gốc. Các sửa sau trên các tệp đó làm mất hiệu lực biên nhận trước. Hợp đồng đã đóng băng và digest không đổi. Việc theo dõi này dùng siêu dữ liệu kết quả công cụ tệp; nó không suy ra tác dụng phụ shell tùy ý hay độ phủ kiểm thử. Các giới hạn chứa hệ thống tệp, liên kết, kích thước và số tệp hiện có vẫn áp dụng.

Đầu ra kiểm tra và điểm kiểm tra mục tiêu công bố các đường dẫn thêm. Nếu một lệnh kiểm thử đã đóng băng bỏ các hồi quy cần thiết, hãy yêu cầu /goal revise <correction> và chạy các kiểm tra đã sửa. Việc gồm một tệp trong vân tay chứng minh độ mới, không chứng minh một kiểm thử đã luyện tệp đó. Hãy ưu tiên thư mục nguồn có giới hạn và lệnh kiểm thử gồm các hồi quy mới khi lập kế hoạch một lần quét lỗi mở.

Bí danh không gian làm việc được chuẩn hóa cho các đường dẫn tệp đã quan sát. Tệp nháp bên ngoài không trở thành đầu vào nguồn của không gian làm việc; điểm kiểm tra công bố rằng nội dung bên ngoài không được lấy vân tay. Trạng thái bên ngoài bắt buộc vẫn cần xác minh do dự án sở hữu.

Bằng chứng phạm vi commit

Một git log <baseline>..HEAD -- <paths> không rỗng chỉ chứng minh rằng một commit khớp bộ lọc. Nó không loại các tệp không liên quan trong commit đó hoặc các commit khác. Các kế hoạch thay đổi mã mới từ chối các khẳng định nhật ký Git có lọc đường dẫn, không rỗng, đứng một mình đã nhận ra; các kiểm tra đã đóng băng cũ hơn nhận hướng dẫn sửa mà không đổi digest hay xác thực lúc đọc của chúng.

Hãy dùng một bộ xác minh do dự án sở hữu để kiểm tra tổ tiên đường cơ sở, đòi hỏi một phạm vi không rỗng, và kiểm mọi đường đã đổi trong mọi commit mà không lọc đường dẫn. Hãy gồm tệp đã xóa và cả hai phía của đổi tên, xử lý commit hợp nhất một cách tường minh, và xác thực riêng mọi thuộc tính nhánh hoặc thông điệp bắt buộc. Dùng /goal revise để củng cố một hợp đồng hiện có; đừng sửa các yêu cầu đã đóng băng.

Kích thước kế hoạch và gửi lại đầy đủ

Kế hoạch đã kết xuất, gồm Markdown và JSON bảo đảm, phải vừa trong 8,192 byte UTF-8. Hãy nhắm dưới 7,168 byte. Nếu lần gửi vượt trần, hãy rút ngắn văn xuôi lặp và gửi lại đối tượng đầy đủ, gồm kind và mọi trường bắt buộc. Hãy giữ mã chấp nhận và các kiểm tra; runtime không cắt yêu cầu hay nâng giới hạn bộ đọc để nhận một kế hoạch quá cỡ.

Biên nhận rà soát hoạt ảnh CLI cục bộ

packages/ax-code/script/verify-cli-review-receipts.ts do kho sở hữu kiểm tra các tạo tác round-* dưới gốc biên nhận được chọn bằng --root. Mỗi vòng cần revision.txt, và mỗi mục trong grok, claude và codex cần exit.txt với 0 và một phán quyết cuối trong stdout.jsonl (sự kiện văn bản Grok) hoặc stdout.txt (Claude/Codex). Hãy giữ các lần thử thất bại ngoài các thư mục vòng đã hoàn thành; đừng biến lỗi thành biên nhận thoát bằng không.

dispositions.json chứa một mảng findings. Mỗi mục nêu round, cli, id, status (fixed hoặc rejected), và evidence không trống. Các mục cố định còn cần một đối tượng regression với đường dẫn kho nguyên văn file dưới packages/ax-code/test/cli/tui/ và đúng fullName của Vitest. Các disposition trùng hoặc nhiều phán quyết mơ hồ sẽ thất bại.

Bộ xác minh chạy các tệp đó bằng Vitest đã cài với mặc định thử lại toàn cục đặt về không (tùy chọn kiểm thử riêng có thể ghi đè mặc định đó), rồi kiểm rằng mỗi khẳng định được tham chiếu đạt đúng một lần. Khẳng định thiếu, bị bỏ, thất bại hoặc mơ hồ làm xác minh thất bại. Điều này chứng minh các kiểm thử được tham chiếu đó đã đạt, không chứng minh khẳng định của chúng phủ ngữ nghĩa phát hiện. Các disposition bị từ chối vẫn là phán đoán đã ghi. Một vòng cuối phải khớp HEAD hiện tại; các phát hiện được đánh dấu đã sửa cần một bản sửa mới hơn và một vòng rà soát. Thay đổi nguồn, kiểm thử hoặc cấu hình của gói lõi chưa commit sẽ ngăn xác minh. Hãy giữ cấu hình ax-code.json cục bộ không liên quan ra khỏi các commit.

Với kho này, vitest run --dir test/cli/tui giữ các loại trừ của làn bình thường trong khi quét thư mục TUI. Trình chạy nhóm vẫn có thể chọn đúng tệp bằng AX_TEST_FILES; chọn thư mục không tắt các loại trừ.