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

AX Wiki biên dịch kho

Trạng thái: Đang hoạt động
Phạm vi: trạng thái hiện tại
Xem xét lần cuối: 2026-10-03 Chủ sở hữu: môi trường chạy AX Code

AX Wiki là trình biên dịch wiki kho gốc của AX Code. Nó biến nguồn đã theo dõi, cấu hình, kiểm thử, quy trình và tài liệu sẵn có thành một cơ sở tri thức Markdown nhỏ, có nguồn chống lưng, dưới .ax-wiki/. Nó dùng cùng cấu hình nhà cung cấp và định tuyến mô hình như AX Code; không có tệp thực thi riêng hay kho thông tin xác thực riêng.

ax-code wiki viz vẽ các trang đã biên dịch và các tệp chúng trích dẫn. Ảnh chụp màn hình của bản đồ đó nằm trong Trực quan hóa bằng chứng Wiki.

Nó nằm ở đâu

Văn xuôi wiki là một lớp điều hướng đã biên dịch, không phải bằng chứng cấu trúc. Nếu wiki không khớp mã, hãy tin mã và chạy ax-code wiki update.

Bắt đầu nhanh

Kết nối một nhà cung cấp AX Code, rồi chạy:

ax-code wiki plan
ax-code wiki generate
ax-code wiki doctor

ax-code init --wiki sinh AGENTS.md, chèn khối con trỏ AX Wiki, và biên dịch wiki trong một quy trình. Dùng --wiki-only-agents để thêm con trỏ mà không gọi mô hình.

Lệnh

Các tùy chọn sinh gồm --model provider/model, --dir <relative>, --quiet, --skip-agents và --force. --force được yêu cầu có chủ đích để thay nội dung đã sinh bị sửa tay ngoài các mục được bảo vệ.

Thư mục kho

Từ v7.22.2, thư mục đầu ra mặc định là .ax-wiki/. Tiền tố ẩn xác định tri thức kho do AX Code duy trì. Nó không làm tệp bị Git bỏ qua: hãy chọn có commit tri thức này hay thêm /.ax-wiki/ vào .gitignore của kho.

Dùng wiki.dir trong ax-code.json hoặc --dir docs/knowledge để chọn một thư mục tương đối khác; cờ CLI được ưu tiên. Mọi việc sinh, trạng thái, con trỏ tác nhân, bảo trì nền và trực quan hóa dùng lựa chọn đó. Trình biên dịch không tự phát hiện, di chuyển hay hợp nhất một thư mục ax-wiki/ cũ hơn. Tên gói và trình sinh, ax-wiki.config.json và ax-wiki.instructions.md không đổi.

Hợp đồng đã sinh

AX Wiki ghi các trang Markdown và .ax-wiki/.manifest.json. Mỗi trang có frontmatter chứa:

• generated_by: ax-wiki
• một summary ngắn gọn
• symbols chính xác được trả về từ lần sinh có bằng chứng chống lưng
• sources tương đối với kho được dùng để biên dịch trang

Bản kê lưu hash kế hoạch tất định, hash nguồn kho, hash trang, mô hình sinh, bản sửa git và thời điểm sinh. Trang được ghi nguyên tử; bản kê được ghi cuối và chỉ sau khi ứng viên đầy đủ trong bộ nhớ vượt xác thực.

Khám phá nguồn ưu tiên danh sách tệp đã theo dõi và không bị bỏ qua của Git, loại thư mục đã sinh/bản dựng/nhà cung cấp và chính wiki, bỏ tệp nhị phân hoặc quá cỡ, và từ chối đường dẫn hoặc liên kết tượng trưng ngoài kho.

Điều hướng phân hệ

Kế hoạch mặc định giữ các trang khởi động nhanh, kiến trúc và phát triển. Một mô-đun vượt ngân sách số nguồn hoặc byte bằng chứng của một trang cũng có thể nhận các trang tập trung như modules/core/src/session.md. Các trang này bao phủ thư mục con trực tiếp dưới thư mục src, lib hoặc app của mô-đun, với ít nhất ba tệp mã mỗi phân hệ và hai phân hệ đủ điều kiện trong mô-đun.

Trang phân hệ gồm cây triển khai của chúng và các tệp khớp dưới thư mục test hoặc tests của mô-đun. Chỉ dẫn sinh của chúng yêu cầu điểm vào, luồng môi trường chạy, ranh giới, vị trí thay đổi cụ thể và kiểm thử liên quan. Trang mô-đun đặt tối đa hai tệp kiểm thử ngay sau nguồn xếp hạng cao nhất để kiểm thử có thể tham gia chọn bằng chứng có giới hạn.

Ngân sách mặc định tổng vẫn là 12 trang, gồm ba trang tổng quan. Tổng quan mô-đun và trang phân hệ tranh các chỗ còn lại theo số nguồn; một phân hệ chỉ được đưa vào sau tổng quan cha của nó. Phân hệ lớn hơn có thể đẩy các trang gói nhỏ hơn. Xem trước kết quả bằng ax-code wiki plan. Tăng maxPages (tới 40 cho kế hoạch tự động), hoặc cấu hình pages tường minh khi một phân hệ cụ thể cần độ phủ được bảo đảm. Kế hoạch tường minh vẫn có thẩm quyền và không nhận trang phân hệ tự động.

Việc này cải thiện điều hướng và tiêu điểm bằng chứng; nó không xác minh văn xuôi đã sinh và không bảo đảm tác nhân đọc wiki. Hãy theo trích dẫn về nguồn hiện tại trước khi dựa vào chi tiết triển khai.

Tác nhân dùng wiki thế nào

Tác nhân tới wiki theo ba cách, từ rẻ nhất tới cụ thể nhất:

1. Chỉ mục lời nhắc. Khi một wiki khỏe mạnh tồn tại, lời nhắc phiên mang một khối <repo_wiki> ngắn: vị trí wiki, một nhãn độ mới, và một dòng mỗi trang (đường dẫn và một tóm tắt đã cắt, khoảng 750 token cho 12 trang mặc định). Các tóm tắt chỉ định vị chỗ cần đọc; chúng không phải bằng chứng.
2. Công cụ repo_wiki. Một công cụ chỉ đọc với ba thao tác: index (thẻ trang với độ mới theo trang), read (một trang cộng các nguồn được trích dẫn, nguồn được trích dẫn nào đã đổi, và mọi ký hiệu frontmatter không tìm thấy trong các nguồn đó), và related (trang cho một ký hiệu, nhắc trong thân, hoặc đường dẫn nguồn). Nó có trong hồ sơ công cụ đầy đủ và lập trình và dùng quyền read.
3. Công cụ tệp chung. read, glob và grep trên .ax-wiki/ vẫn hoạt động.

Độ mới của lời nhắc được xét theo từng trang: một trang còn mới khi mọi nguồn nó trích dẫn vẫn khớp hash bản kê. Một tệp được thêm hoặc sửa mà không trang nào trích dẫn để nhãn lời nhắc là fresh và thêm ghi chú rằng wiki chưa bao phủ nó. Một nguồn được trích dẫn đã đổi đánh dấu nhãn stale và lời nhắc yêu cầu tác nhân coi wiki chỉ là điều hướng. ax-code wiki status và wiki lint giữ phán quyết chặt hơn trên toàn kho, nơi bất kỳ tệp đủ điều kiện nào được thêm, gỡ hoặc sửa đều là cũ.

Wiki không bao giờ thay nguồn: mọi kết quả read liệt kê các tệp cần đối chiếu, và nếu một trang và mã không khớp thì mã thắng.

Cập nhật tăng dần và nội dung thủ công

wiki update so sánh hash nguồn hiện tại với bản kê và ánh xạ thay đổi qua bộ chọn của mỗi trang. Một thay đổi kế hoạch sinh lại mọi trang đã lên kế hoạch; nếu không, các trang không liên quan không bị đụng.

Văn xuôi đã sinh thuộc trình biên dịch. Hãy đặt văn bản bền vững của người bảo trì trong một khối được bảo vệ:

<!-- AX-WIKI:PROTECTED:START deployment-warning -->

Production migrations require an operator-approved maintenance window.

<!-- AX-WIKI:PROTECTED:END -->

Thân được bảo vệ sống sót qua lần sinh lại. AX Wiki từ chối ghi đè các sửa tay khác trừ khi --force được cung cấp. Các trang đã sinh lỗi thời chỉ bị gỡ khi nội dung được quản lý của chúng không đổi và chúng không chứa mục được bảo vệ.

Cấu hình

Cấu hình tích hợp trong ax-code.json của dự án:

{
  "wiki": {
    "enabled": true,
    "auto": true,
    "dir": ".ax-wiki",
    "model": "openai/gpt-5-mini",
    "autoInjectAgents": true,
    "touchClaudeMd": true,
    "maxPages": 12,
    "generationConcurrency": 2,
    "maxSourcesPerPage": 80,
    "exclude": ["fixtures/**"]
  }
}

include, exclude, maxSourceBytes và maxPageSourceBytes điều khiển khám phá bằng chứng và ngân sách. instructions thêm hướng dẫn trình biên dịch riêng của dự án. Với một kế hoạch được chọn lọc hoàn toàn, hãy cấu hình các mục pages với path, title, purpose và selectors; một kế hoạch tường minh phải gồm quickstart.md.

generationConcurrency nhận 1 hoặc 2. Sinh đám mây gốc mặc định hai lời gọi trang đồng thời; engine cục bộ và nhà cung cấp CLI mặc định một. Đặt thành 1 khi một nhà cung cấp xếp hàng hoặc tiết lưu các yêu cầu chồng nhau. Việc lập lịch không làm mất hiệu lực nội dung trang sẵn có. Gói tái sử dụng vẫn tuần tự trừ khi cài đặt này được cung cấp.

Mỗi trang mô hình có tối đa hai lần thử đã phân loại, chung một hạn 180 giây. Liên kết Wiki tương đối được kiểm tra đối với kế hoạch trang trước khi trang được chấp nhận; một phản hồi liên kết gãy có thể dùng lần thử còn lại để sửa trang đó. Xác thực cuối và các chốt nội dung thủ công vẫn chạy trước khi phát hành.

Các bản dựng bị ngắt giữ kết quả đã xác thực trong .ax-wiki/.page-cache/ (hoặc thư mục Wiki đã cấu hình). Một bản dựng sau tái sử dụng kết quả khớp chỉ sau khi kiểm tra bằng chứng nguồn hiện tại, kế hoạch, trình sinh, mô hình và nội dung trước. Lần sinh đầu vẫn chưa phát hành cho đến khi ứng viên đầy đủ vượt xác thực. Phát hành thành công gỡ các mục dàn đã tiêu thụ; wiki generate tường minh sau đó vẫn sinh lại mọi trang. Mục bộ nhớ đệm bị giới hạn và có cổng quyền; mục hỏng hoặc không truy cập được bị bỏ qua.

.build-report.json phân biệt trang do mô hình sinh và trang đệm với trang written, vốn đã thực sự được phát hành. Mảng tùy chọn pages ghi số lần thử, thời lượng, kích thước byte lời nhắc/nguồn và mức dùng token chính xác của mỗi trang khi nhà cung cấp cung cấp. Các bản dựng thất bại hoặc bị hủy không báo trang đã phát hành.

Bạn cũng có thể đặt hướng dẫn trình biên dịch trong ax-wiki.instructions.md và cấu hình engine cốt lõi trong ax-wiki.config.json. Cài đặt môi trường chạy AX Code tường minh ghi đè cấu hình cốt lõi ở chỗ cả hai được cung cấp.

Bảo trì tương tác mặc định

Mở một dự án trong TUI AX Code bật bảo trì Wiki nền theo mặc định. Sau 30 giây dự án nhàn rỗi, các tạo tác thiếu được sinh và các tạo tác cũ được cập nhật tăng dần. Phiên đang bận hoặc đang thử lại, công việc đang xếp hàng và bản nháp không rỗng được ưu tiên và hủy việc sinh nền. Quyền đọc/ghi của tác nhân hiện tại áp dụng; tác nhân chỉ đọc không sinh. Không tệp chỉ dẫn tác nhân nào bị quy trình nền này viết lại.

Dùng "wiki": { "auto": false } để tắt bảo trì nền, hoặc enabled: false để tắt biên dịch và tiêm lời nhắc. auto mặc định true và không ghi cấu hình. Nó dùng mô hình Wiki đã cấu hình hoặc mô hình mặc định của AX Code, với hạn việc 10 phút và tối đa ba lần thử tự động có lùi. Một yêu cầu đồ thị tường minh hoặc một thay đổi nguồn/cấu hình cho phép một lần thử khác. Các lần chạy không tương tác và CI không bật bộ lập lịch tương tác. Thư mục không phải Git cần một yêu cầu tường minh. Trong dự án Git, việc sinh và tiêu thụ Wiki dùng gốc worktree gần nhất, nên mở AX Code trong một gói không tạo một Wiki gói riêng.

Thanh bên phiên và /wiki-viz mở ngay một trang tiến trình cục bộ và yêu cầu bảo trì. Khi một ảnh chụp sẵn sàng, trang đó hiện các quan hệ trang/nguồn Wiki đã ghi. Xem Trực quan hóa Wiki.

Định tuyến tác nhân

Khi một wiki khỏe mạnh tồn tại và wiki.enabled không phải false, lời nhắc phiên nhận một giao thức <repo_wiki> gọn. Nó bảo tác nhân bắt đầu ở khởi động nhanh, chỉ tải các trang liên quan, xác minh các khẳng định quan trọng qua tệp được trích dẫn, và dùng công cụ đồ thị/LSP cho câu hỏi cấu trúc.

healthy mô tả sự hiện diện của thư mục wiki, chỉ mục và bản kê. Trường riêng freshness là fresh, stale hoặc unknown. Trạng thái và định tuyến phiên so sánh hash nguồn hiện tại bằng cài đặt gồm/loại và kích thước có hiệu lực, nên các sửa, thêm và xóa chưa commit được phát hiện. Các kiểm tra không tái sử dụng một phán quyết mới đã đệm; chúng quét nguồn đủ điều kiện với độ đồng thời đọc có giới hạn. Wiki thiếu hoặc bị tắt tránh lần quét nguồn. Độ mới là một kiểm tra nguồn tại một thời điểm, không phải xác thực mọi khẳng định hoặc trang đã sinh; hãy dùng lint để xác thực tạo tác.

Wiki cũ hoặc chưa xác minh vẫn dùng được để điều hướng, với chỉ dẫn tường minh phải xác minh nguồn gốc hiện tại trước khi dựa vào khẳng định triển khai. Lỗi xác minh tạo ra unknown. wiki status thoát 0 khi không có thư mục wiki (wiki thiếu chính là báo cáo). Khi wiki có mặt, nó thoát không thành công nếu wiki không khỏe hoặc độ mới không phải fresh.

Bằng chứng wiki bị giới hạn: mỗi nguồn được chọn đóng góp tối đa 32,000 byte đầu trong ngân sách trang, với việc cắt được đánh dấu cho trình sinh. GraphContext có thể thêm đoạn đã chọn, nhưng mỗi đoạn giới hạn 80 dòng. Các trợ giúp điều hướng này không bảo đảm giữ mọi hàm đã đổi hoặc chốt bắt buộc; hãy cung cấp mã gốc cần thiết một cách riêng cho một lần rà soát có phạm vi.

Khối <!-- AX-WIKI:START --> được quản lý trong AGENTS.md mang cùng chính sách định tuyến mà không sao nội dung wiki vào chỉ dẫn kho.

CI

Chạy ax-code wiki update rồi ax-code wiki lint trong một việc đã xác thực nhà cung cấp, rồi mở một PR tài liệu. Xem examples/ax-wiki-update.yml. Hãy coi các thay đổi wiki đã sinh như tài liệu khác: xem lại trích dẫn nguồn và tránh tự hợp nhất đầu ra mô hình.

Xử lý sự cố