Hướng dẫn sử dụng ZIAForge

Các bước đầu tiên

ZIAForge giữ cuộc thảo luận, lập kế hoạch, thực thi và xác minh trong một tác vụ. Chọn Code cho dự án Git, hoặc Work cho tài liệu, nghiên cứu và các kết quả khác trong một thư mục thông thường.

Bắt đầu với một tác vụ nhỏ trong một dự án riêng biệt. Nếu bạn chọn một CLI gốc, hãy cài đặt và đăng nhập bằng tài khoản riêng của nó trong terminal trước. Ngoài ra, bạn có thể định cấu hình kết nối API. Gói đăng ký CLI và API trả phí là các phương thức kết nối riêng biệt; ZIAForge không tự động đăng nhập hay chuyển tín dụng giữa chúng.

1. Mở Cài đặt và kiểm tra thư mục không gian làm việc cùng ngôn ngữ. Giới thiệu hiển thị danh tính chính xác của bản dựng đang chạy.
2. Đối với Code, hãy thêm kho lưu trữ Git trong thanh bên. Đối với Work, hãy chọn một thư mục riêng biệt khi tạo tác vụ.
3. Lưu một cài đặt sẵn với CLI, mô hình, nỗ lực suy luận và mức truy cập. Bạn cũng có thể chọn Tùy chỉnh trực tiếp mà không cần cài đặt sẵn đã lưu.
4. Tạo một tác vụ, chọn tuyến đường, các vai trò và chế độ tiến triển thủ công hoặc tự động của nó. Xem lại các lựa chọn trước khi Bắt đầu.

Hướng dẫn liên quan: Tổng quan dự án · Khả năng tương thích của nhà cung cấp.

Cài đặt đúng gói ứng dụng máy tính

Chọn một gói cho hệ điều hành và kiến trúc CPU của bạn: x64 hoặc arm64. Quy trình xây dựng có thể tạo ra các định dạng macOS DMG/ZIP, trình cài đặt Windows NSIS/ZIP, và Linux DEB/RPM/AppImage/tar.gz/ZIP. Một tệp được tạo hoặc bản dựng chéo không phải là bằng chứng cho thấy trình cài đặt và UI gốc của nó đã vượt qua kiểm tra trên máy của bạn; hãy tham khảo hồ sơ xác minh của bản phát hành đó.

Các bản dựng macOS sử dụng Electron 44 yêu cầu macOS 13 trở lên. Sử dụng gói arm64 trên Apple Silicon và gói x64 cho Intel. Thoát hoàn toàn ứng dụng cũ trước khi thay thế. Các gói xem trước có thể chưa được ký và chưa được công chứng; đừng nhầm lẫn một hiện vật phát triển với một bản phát hành công khai đã ký.

Windows cần một hệ điều hành được hỗ trợ bởi phiên bản Electron đi kèm và Git có sẵn trong PATH. Chọn kiến trúc phù hợp. Bản xem trước chưa ký không có chứng nhận Authenticode. Bản ZIP portable phải giữ lại toàn bộ thư mục ứng dụng và các tệp thời gian chạy, không chỉ tệp thực thi của nó.

Linux cần một môi trường desktop đồ họa tương thích, các thư viện hệ thống theo yêu cầu của Electron, và Git. Đối với thông tin xác thực điều khiển được mã hóa, hãy cung cấp Secret Service đang hoạt động như gnome-libsecret hoặc KWallet; backend basic_text không an toàn sẽ không được chấp nhận. Bằng chứng kiểm tra khói trên môi trường headless/container không chứng nhận cho mọi desktop hoặc bản phân phối.

Cài đặt DEB bằng apt install ./file.deb, hoặc cài đặt RPM thông qua trình quản lý gói của bản phân phối. AppImage cần quyền thực thi và hỗ trợ FUSE phù hợp; --appimage-extract-and-run là một giải pháp thay thế ở những nơi được hỗ trợ. Giải nén các gói tar.gz và ZIP cùng toàn bộ tệp thời gian chạy của chúng. Giữ riêng dữ liệu người dùng và các tệp ứng dụng khi thay thế một gói.

Để xây dựng từ mã nguồn, hãy sử dụng Node 24, Git và npm ci, bao gồm cả trình cài đặt Electron thông thường. Việc xây dựng lại gốc yêu cầu các công cụ nền tảng: công cụ dòng lệnh Xcode trên macOS; MSVC C++, Windows SDK và Python trên Windows; trình biên dịch, make, Python, pkg-config và các công cụ đóng gói cần thiết trên Linux. Làm theo PLATFORM_BUILDS.md để biết các lệnh chính xác và giới hạn nền tảng hiện tại.

Các phiên bản phát hành được dành riêng tập trung và các đầu ra là bất biến. Bản dựng xác minh CI không phải là trình cài đặt được xuất bản. Kho lưu trữ nguồn chứa mã nguồn, lockfile, tài liệu và tập lệnh; các phần phụ thuộc, thông tin xác thực, hồ sơ người dùng và nghiên cứu riêng tư đều bị loại trừ. Đừng bao giờ suy luận việc xác thực gốc trên ARM hoặc Windows từ một bản dựng x64 thành công.

Hướng dẫn liên quan: Các gói nền tảng, điều kiện tiên quyết và giới hạn xác minh · Danh tính bản dựng và kiểm tra phát hành.

Code: năm tuyến đường

Auto đánh giá phạm vi: một câu hỏi đơn giản có thể kết thúc bằng một câu trả lời, trong khi tác vụ lớn hơn cần sự chuẩn bị. Sửa lỗi điều tra nguyên nhân và chuẩn bị biện pháp khắc phục. Đặc tả trước bắt đầu bằng giải pháp kỹ thuật; Yêu cầu trước bắt đầu bằng các yêu cầu và tiêu chí nghiệm thu.

Đa mô hình sử dụng các ngữ cảnh riêng biệt cho việc khám phá, thiết kế, triển khai và đánh giá. Tên tuyến đường không yêu cầu các nhà cung cấp khác nhau: mỗi vai trò sử dụng cài đặt sẵn hoặc cấu hình Tùy chỉnh do bạn chọn.

Một Worktree sẽ cô lập các thay đổi Git của tác vụ. Nhánh hoạt động trong checkout đã chọn. Kiểm tra dự án, nhánh và mô hình trước khi bắt đầu; mô tả tác vụ không được gửi đồng thời tới cuộc trò chuyện thông thường.

Đối với một ý tưởng có các lựa chọn kỹ thuật hoặc sản phẩm chưa được giải quyết, hãy sử dụng Yêu cầu trước và xây dựng nền tảng trong cuộc thảo luận. Auto phân loại yêu cầu; đó không phải là lệnh triển khai ngay lập tức mọi cụm từ ngắn. Lưu bản nháp giữ lại yêu cầu mà không liên hệ với mô hình; Bắt đầu sẽ lưu và khởi chạy luồng được quản lý một lần. Một đến bốn bản sao tác vụ có ID tạo và cài đặt vai trò độc lập.

Hướng dẫn liên quan: Quy ước luồng công việc Code · Hồ sơ lời nhắc Code.

Thảo luận Forge

Bắt đầu mở cuộc thảo luận trung tâm. Trả lời tự nhiên, đặt câu hỏi ngược lại, thêm ràng buộc và thảo luận về các lựa chọn kỹ thuật. Cuộc trò chuyện và các câu hỏi luôn gắn liền với tác vụ.

Gửi văn bản không đồng nghĩa với việc chấp nhận tài liệu hoặc cho phép một kế hoạch triển khai mới. Việc làm rõ trong quá trình thực thi trước tiên sẽ tạm dừng lượt được quản lý và xem xét lại phạm vi bị ảnh hưởng. Câu trả lời cho một câu hỏi trong một bước đã được chấp nhận có thể tiếp tục bước đó.

Để chủ động xem xét lại nền tảng, hãy chọn Yêu cầu, Đặc tả hoặc Lập kế hoạch. Một phiên bản mới đòi hỏi sự chấp nhận mới đối với các quyết định phụ thuộc. Các bước đã hoàn thành và bằng chứng của chúng vẫn được giữ nguyên; các giai đoạn chưa hoàn thành bị thay thế vẫn nằm trong lịch sử.

Các phiên giai đoạn được quản lý khác với cuộc trò chuyện tự do. Sử dụng thảo luận Forge thay vì gửi lời nhắc thủ công trực tiếp đến phiên do luồng công việc sở hữu.

Hướng dẫn liên quan: Quy ước thảo luận Forge.

Tài liệu và quyết định

Mở một tài liệu, kiểm tra phiên bản của nó và thực hiện chỉnh sửa khi cần. Gửi chỉnh sửa thông qua thảo luận sẽ tạo ra một phiên bản mới; các báo cáo và kết quả đã xác minh không bị ghi lại hồi tố.

Trước khi chấp nhận kế hoạch được đề xuất, hãy chỉnh sửa thứ tự, hướng dẫn, tiêu chí nghiệm thu và các lệnh xác minh. Cho phép các lệnh cụ thể mà bạn hiểu rõ: chúng chạy trong thư mục tác vụ. Đa mô hình đề xuất một bước triển khai cho toàn bộ tác vụ, với thông tin chi tiết trong tài liệu và hướng dẫn của nó.

Phê duyệt là một quyết định riêng biệt có chủ ý. Auto không bỏ qua các câu hỏi hoặc việc chấp nhận các yêu cầu, đặc tả và kế hoạch. Một tài liệu bị thay đổi từ bên ngoài không thể tái sử dụng phê duyệt cũ.

Các tệp chuẩn bị xuất hiện dưới dạng hiện vật. Phiên bản, giai đoạn tạo ra và mã băm ràng buộc chúng với một kết quả. Tài liệu Code được giữ bên ngoài worktree và không tự động đi vào commit.

Kiểm tra cả tài liệu và quyết định hiển thị trước khi chấp nhận. Việc chấp nhận ràng buộc ID cổng hiện tại, bản sửa đổi kế hoạch và các mã băm tài liệu được giữ lại. Yêu cầu thay đổi khi phạm vi hoặc bằng chứng bị sai. Nếu một quyết định trở nên cũ, hãy tải lại trạng thái đã lưu trước khi đưa ra lựa chọn mới; không thể chấp nhận tệp đã thay đổi theo phiên bản trước đó.

Hướng dẫn liên quan: Các cổng luồng công việc và phiên bản tài liệu.

Thực thi và đánh giá

Mục Việc cần làm hiển thị các bước thực tế, lần thử hiện tại, kết quả xác minh và đánh giá. Một tác nhân nói “xong” không có nghĩa là hoàn thành một bước: bằng chứng theo yêu cầu của kế hoạch phải tồn tại.

Chế độ thủ công tạm dừng giữa các bước đủ điều kiện. Auto thúc đẩy các bước đã được xác minh và cho phép số lần thử lại có giới hạn. Dừng sau luôn tạo một điểm kiểm tra. Tạm dừng sẽ dừng công việc đang hoạt động của luồng công việc; việc đóng bảng điều khiển không làm dừng luồng đó.

Một người đánh giá độc lập sử dụng một ngữ cảnh riêng biệt với các tệp và kết quả xác minh. Mọi phát hiện chặn bắt buộc phải được giải quyết; nhiều người đánh giá không thể bỏ phiếu để xóa bỏ một lỗi chặn.

Trong Đa mô hình, việc sửa chữa các phát hiện đòi hỏi một quyết định rõ ràng. Việc sửa chữa không âm thầm bắt đầu một đợt đánh giá khác: Đánh giá lại sẽ mở ra một chu kỳ mới. Nhận xét đánh giá có thể yêu cầu điều phối viên xem xét lại mà không cần lặp lại việc triển khai.

Các bước đã hoàn thành không thể được chỉnh sửa âm thầm. Với TDD, Red thực sự phải thất bại vì lý do dự kiến, sau đó Green phải vượt qua. Các lần thử có giới hạn giúp ngăn chặn việc thử lại vô tận.

Lưu các người đánh giá CLI/API độc lập trong Cài đặt → Nhóm đánh giá, sau đó chọn nhóm trong Code hoặc Work. Các người đánh giá chạy song song, tiếp theo là kiến trúc sư báo cáo của nhóm. Bạn cũng có thể định cấu hình người đánh giá độc lập mà không cần nhóm đã lưu. Kiến trúc sư báo cáo chỉ nhận các báo cáo có cấu trúc ẩn danh, không có tệp dự án hoặc công cụ; sự cô lập này hiện yêu cầu Claude Code hoặc API.

Mỗi bước triển khai cần một kiểm tra có thể thực thi, đánh giá độc lập bắt buộc hoặc cả hai. Các giai đoạn chuẩn bị thay vào đó giữ lại các kết quả đã được xác thực và biên nhận hiện vật; những điều này không giả định rằng các kiểm thử triển khai đã chạy. Một lệnh chỉ thành công khi trạng thái thoát thực tế và việc dọn dẹp tiến trình sở hữu được xác nhận. Kiểm tra Red cho TDD phải thất bại bình thường trước khi triển khai và xác minh Green; thiếu tệp thực thi hoặc hết thời gian chờ không phải là kết quả Red hợp lệ.

Bộ ngắt mạch mặc định sẽ dừng sau ba lần thử thất bại trong một bước hoặc năm mươi lần thử tổng cộng. Sự gián đoạn tiêu tốn một lần thử nhưng bản thân nó không tính là một lần thử thất bại. Các giới hạn và bằng chứng đã hoàn thành vẫn tồn tại sau khi khởi động lại; Thử lại không đặt lại chúng. Hãy đọc lỗi được giữ lại trước khi cho phép một lần thử khác.

Hướng dẫn liên quan: Xác minh và đánh giá.

Các nhóm đánh giá song song và kiến trúc sư báo cáo

Mở Cài đặt → Nhóm đánh giá và lưu một nhóm. Thêm những người đánh giá độc lập với CLI hoặc API, mô hình, nỗ lực suy luận và chuyên môn hóa riêng của họ, sau đó chọn một kiến trúc sư báo cáo. Chọn nhóm trong cấu hình đánh giá của tác vụ. Cài đặt sẵn của người thực thi cũng có thể được sử dụng bởi người đánh giá, và Tùy chỉnh vẫn khả dụng; các vai trò độc lập vẫn có các ngữ cảnh riêng biệt.

Các người đánh giá chạy song song trên cùng một bằng chứng tác vụ. Mỗi báo cáo, lỗi và phán quyết bắt buộc đều được giữ lại. Kiến trúc sư nhận các báo cáo được đánh số ẩn danh mà không có tên người đánh giá, danh tính mô hình hay nhà cung cấp, nội dung tác vụ gốc, quyền truy cập kho lưu trữ hoặc công cụ. Nó so sánh các báo cáo và đưa ra một phán quyết có cấu trúc; nó không tiến hành đánh giá lại mã nguồn mới.

Một phát hiện chặn hoặc sự từ chối của người đánh giá bắt buộc không thể được miễn trừ bởi đa số phiếu bầu hoặc sở thích của kiến trúc sư. Báo cáo bị thiếu hoặc không đúng định dạng sẽ ngăn chặn việc phê duyệt. Kiểm tra từng phát hiện riêng lẻ và quyết định tổng hợp trước khi chấp nhận hoặc cho phép sửa chữa. Một nhóm đã lưu sẽ được phân giải và đóng băng cho lượt chạy; việc chỉnh sửa cài đặt sẵn của nhóm không làm ghi lại bằng chứng đã hoàn thành.

Kiến trúc sư chỉ nhận báo cáo hiện sử dụng các cấu hình không dùng công cụ được hỗ trợ của Claude hoặc API. Codex và Antigravity vẫn khả dụng làm người đánh giá nhưng bị từ chối cho vai trò kiến trúc sư cô lập này cho đến khi tồn tại một quy ước không dùng công cụ được xác minh. Một lời nhắc chỉ nói “không có công cụ” là không đủ.

Hướng dẫn liên quan: Cấu hình nhóm được định kiểu · Tổng hợp đánh giá.

Chuyên môn hóa tác nhân và chính sách lời nhắc

Mô hình là động cơ thực thi; chuyên môn hóa là một hồ sơ hướng dẫn. Chọn Không có để không thêm chuyên môn hóa, Tiêu chuẩn cho hướng dẫn mặc định, Auto cho hướng dẫn tích hợp có liên quan, hoặc Thủ công cho các hướng dẫn đã chọn và hướng dẫn có giới hạn của riêng bạn. Các cài đặt sẵn có thể giữ lại lựa chọn.

Danh mục gốc bao gồm mã hóa chung, kiến trúc, bảo mật, độ tin cậy, hiệu suất, kiểm thử và khả năng sử dụng giao diện. Auto sử dụng văn bản tác vụ/bước có sẵn để chọn hướng dẫn; nó không bí mật gọi một mô hình khác hay chứng nhận chuyên môn. Các gợi ý lập kế hoạch có thể được kiểm tra và thay đổi trước khi chấp nhận kế hoạch triển khai.

Các chuyên môn hóa đánh giá giúp tập trung sự chú ý nhưng không bao giờ thay thế bằng chứng độc lập, giới hạn truy cập hoặc phán quyết có cấu trúc. Hãy coi các hướng dẫn tùy chỉnh là một phần của phạm vi tác vụ: đừng sử dụng chúng để bỏ qua việc chấp nhận tài liệu, chính sách công cụ, xác thực hoặc các lỗi do người đánh giá phát hiện.

Hướng dẫn liên quan: Danh mục lời nhắc gốc.

Work: từ câu hỏi đến tài liệu

Work không yêu cầu Git. Mặc định tạo một thư mục tác vụ riêng biệt; Tùy chỉnh chọn một thư mục hiện có thông qua bộ chọn gốc. Lưu bản nháp lưu trữ các cài đặt mà không cần suy luận; Bắt đầu chạy giai đoạn đầu tiên.

Auto trả lời trực tiếp hoặc đề xuất một kế hoạch phù hợp với các Việc cần làm thực tế. Động não tạo ra ideas.md trước khi bạn chọn thêm ý tưởng hoặc đánh giá. Nghiên cứu giữ lại findings.md, các nguồn và hạn chế. Viết chuyển từ ý định và, khi hữu ích, outline.md sang tài liệu mang tính mô tả hoặc draft.md; các lần sửa đổi giữ lại các phiên bản trước đó.

Chọn các tệp đầu vào thông qua bộ chọn gốc và tham chiếu chúng bằng ký hiệu @. Ứng dụng sao chép chúng dưới dạng dữ liệu đầu vào tác vụ bất biến và xác thực danh tính của chúng trước khi chạy. Mặc định tạo thư mục tác vụ do ứng dụng sở hữu; quyền truy cập thư mục Tùy chỉnh là quyền do chủ sở hữu cấp đã được lưu. Bản nháp đã lưu chưa bắt đầu có thể thay đổi thư mục của nó.

Tạo 1–4 bản sao với cài đặt người thực thi độc lập. Các tác vụ sử dụng các thư mục chồng chéo không thể ghi đồng thời. Sự phối hợp này áp dụng cho các hoạt động của ZIAForge, không áp dụng cho các chương trình bên ngoài tùy ý.

Động não chuyên sâu mặc định có ba worker độc lập và hỗ trợ tối đa tám worker. Chọn thứ tự và cấu hình của chúng, bao gồm cả việc tái sử dụng cài đặt sẵn trong các ngữ cảnh riêng biệt. Các câu hỏi của worker giữ lại nguồn gốc của chúng; các báo cáo sai định dạng có một lần thử sửa định dạng. Sự thất bại một phần vẫn hiển thị rõ ràng thay vì được trình bày như một thành công đồng thuận.

Chuyên sâu kết hợp các báo cáo worker được giữ lại thành brainstorm_report.md và luôn yêu cầu người dùng đưa ra quyết định. Một điều chỉnh nhỏ sẽ sửa đổi báo cáo thông qua điều phối viên; một thay đổi lớn sẽ bắt đầu một vòng khác của các worker đã đóng băng. Các hiện vật vẫn giữ nguyên phiên bản của chúng.

Các vai trò đã phân giải sẽ đóng băng khi tạo tác vụ hoặc khi lưu bản nháp rõ ràng. Sau lần gọi đầu tiên, chỉ có tiến trình tự động/thủ công là có thể thay đổi; hãy sử dụng một tác vụ mới cho các cài đặt vai trò hoặc mô hình khác nhau. Việc chỉnh sửa cài đặt sẵn toàn cục không âm thầm thay đổi các giai đoạn sau.

Chế độ thủ công tạm dừng giữa các giai đoạn đủ điều kiện, bao gồm dàn ý Viết đáng kể. Auto có thể tiếp tục qua dàn ý đó. Các câu hỏi, kế hoạch thực thi được đề xuất, định hướng Động não và đánh giá báo cáo Chuyên sâu vẫn là các quyết định rõ ràng ngay cả trong Auto. Chỉ riêng một trích dẫn không chứng minh việc duyệt web đã diễn ra, và chỉ riêng một tệp nhị phân được giữ lại không chứng minh được việc kết xuất của nó.

Hướng dẫn liên quan: Các chế độ và quyết định trong Work.

Cài đặt sẵn, mô hình và quyền truy cập

Cài đặt sẵn lưu CLI/API, mô hình, nỗ lực suy luận và các quyền. Chân trang trò chuyện có các phân đoạn cài đặt sẵn, CLI, mô hình và tùy chọn. Tùy chỉnh hoạt động mà không cần cài đặt sẵn; Tạo cài đặt sẵn sẽ lưu lựa chọn hiện tại.

Danh mục đến từ CLI hoặc API đã cài đặt được chọn ở những nơi được hỗ trợ. Làm mới sẽ cập nhật danh sách mà không làm thay đổi lựa chọn. Nếu tính năng khám phá không khả dụng, hãy nhập ID mô hình rõ ràng; nhà cung cấp vẫn phải hỗ trợ mô hình đó. Mức độ suy luận phụ thuộc vào mô hình và CLI. Mặc định của nhà cung cấp khác biệt với token none rõ ràng.

Chỉ áp dụng các thay đổi sau khi có xác nhận từ backend. Việc chuyển đổi bị hạn chế trong một lượt đang hoạt động hoặc hàng đợi không trống. Các bản nháp và lịch sử hiển thị vẫn được giữ lại, nhưng việc thay đổi nhà cung cấp không chuyển giao trạng thái nội bộ riêng tư của chúng.

Trong Forge, nhãn vai trò rất quan trọng: khâu chuẩn bị có thể sử dụng Trình lập kế hoạch riêng biệt. Chân trang thay đổi vai trò được hiển thị; người đánh giá và người trợ giúp được chọn trong cài đặt luồng công việc. Chính sách cho quá trình triển khai đã được xác minh có thể bị khóa.

Các quyền khác nhau giữa các nhà cung cấp. Chỉ đọc và Ghi vào không gian làm việc khả dụng khi bộ điều hợp hỗ trợ chúng. Antigravity sử dụng cài đặt CLI gốc hoặc quyền truy cập đầy đủ được chọn rõ ràng. Quyền truy cập đầy đủ không phải là một sandbox.

Chuyên môn hóa bổ sung hướng dẫn lời nhắc, không phải là một mô hình hoặc quyền khác. Cài đặt sẵn và vai trò hỗ trợ Không có, Tiêu chuẩn, Auto và Thủ công. Auto chọn hồ sơ từ văn bản bước mà không cần gọi thêm mô hình; Thủ công chấp nhận tối đa bốn chuyên môn và hướng dẫn tùy chỉnh. Các phân công do Trình lập kế hoạch đề xuất có thể được chỉnh sửa trước khi chấp nhận kế hoạch.

ID mô hình hoặc nỗ lực suy luận được nhập thủ công vẫn là lựa chọn của bạn, nhưng nhà cung cấp có thể từ chối nó. Việc chỉnh sửa cài đặt sẵn toàn cục không thay đổi hồi tố cuộc trò chuyện đang chạy hoặc kế hoạch đã được chấp nhận. Để thay đổi một cuộc trò chuyện rảnh rỗi một cách có chủ ý, hãy sử dụng các điều khiển cấu hình của chính nó và đợi xác nhận. Tùy chọn bị vô hiệu hóa nên được hiểu là giới hạn về khả năng hoặc vòng đời, không được bỏ qua bằng cách chỉnh sửa JSON đã lưu.

Hướng dẫn liên quan: Khả năng của nhà cung cấp.

Trò chuyện, Dừng và hàng đợi

Các tab đang mở, Gần đây và bản nháp đều thuộc về một tác vụ. Đóng một tab sẽ xóa nó khỏi Mở nhưng vẫn giữ lại trong Gần đây và không dừng tiến trình của nhà cung cấp hoặc luồng công việc được quản lý của tab đó. Tìm kiếm lịch sử, mở lại cuộc trò chuyện hoặc đóng tất cả các tab bổ sung từ menu lịch sử.

Dừng sẽ ngắt lượt hiện tại. Chờ quá trình dừng hoàn tất trước khi Gửi tiếp theo: xác nhận ngắt không phải là hoàn thành tiến trình. Trong lúc đó, bạn có thể nhập bản nháp tiếp theo.

Trong cuộc trò chuyện thông thường, Hàng đợi lưu một yêu cầu sau tách biệt với bản nháp hiện tại. Tạm dừng hàng đợi sẽ giữ lại việc gửi tiếp. Dừng và Thoát sẽ tạm dừng hàng đợi. Sau khi khởi động lại, trước tiên hãy Tiếp tục, sau đó Tiếp tục hàng đợi một cách rõ ràng.

Không chắc chắn nghĩa là trạng thái gửi chưa xác định. Một tin nhắn như vậy sẽ không được tự động gửi lại: hãy kiểm tra lịch sử, sao chép văn bản nếu thích hợp và loại bỏ mục trong hàng đợi. Việc gửi lại là một yêu cầu mới có chủ ý.

Các cuộc trò chuyện theo giai đoạn được quản lý sử dụng luồng công việc của riêng chúng, không phải hàng đợi thông thường. Theo dõi giai đoạn hiển thị giai đoạn hiện tại; chọn thủ công một tab khác sẽ dừng theo dõi. Nhật ký CLI hiển thị chẩn đoán tách biệt với câu trả lời.

Câu trả lời Markdown kết xuất các tiêu đề, danh sách, bảng, liên kết và khối mã có rào chắn. Thẻ công cụ và chẩn đoán CLI vẫn tách biệt với câu trả lời. Suy nghĩ và số liệu token do mô hình báo cáo chỉ xuất hiện khi nhà cung cấp thực sự cung cấp chúng; đừng suy luận suy nghĩ riêng tư hoặc mức sử dụng từ hoạt ảnh.

Sau khi gửi hoặc xác nhận hàng đợi không chắc chắn, hãy kiểm tra lịch sử và chỉ thử lại cùng yêu cầu đã lưu nếu có tùy chọn. Biên nhận hàng đợi có nghĩa là bộ lưu trữ đã chấp nhận mục đó, không phải là việc suy luận đã hoàn tất. Chỉ xóa một mục trong hàng đợi không chắc chắn như một hành động loại bỏ rõ ràng; nó không thể rút lại một lời nhắc đã được chuyển giao.

Hướng dẫn liên quan: Hàng đợi tin nhắn bền bỉ.

Tệp, Git và hoàn thành

Mục Tệp hiển thị thư mục tác vụ. So sánh kết quả với các yêu cầu, mở tài liệu và kiểm tra các khác biệt. Việc giữ lại một tệp nhị phân không chứng minh được việc kết xuất chính xác trong ứng dụng đích của nó.

Git cung cấp trạng thái, các thay đổi và hoạt động với kết quả được ghi lại. Commit, merge và push theo mặc định là thủ công; các thao tác tự động là những lựa chọn riêng biệt cho một kế hoạch đã được xác minh đầy đủ.

Không thay đổi các tệp đang làm việc giữa quá trình xác minh và xuất bản: phê duyệt được gắn với các byte chính xác. Xung đột, đẩy thất bại và kết quả thao tác không xác định sẽ chặn tiến trình cho đến khi có quyết định rõ ràng. Auto không âm thầm cho phép xuất bản.

Work không tạo nhánh Git nào và không có khâu hoàn tất Git. Giữ các tài liệu bắt buộc từ thư mục đã chọn, bao gồm các phiên bản và nguồn.

Trình soạn thảo tệp cung cấp cú pháp theo phần mở rộng, tìm kiếm và thay thế, lịch sử hoàn tác, ngắt dòng và bản nháp theo từng tab. Việc lưu giữ nguyên mã hóa UTF-8/UTF-16 được hỗ trợ và từ chối xung đột sửa đổi từ bên ngoài. Các bảng mã khác và nội dung nhị phân cần một trình soạn thảo bên ngoài. Các bản nháp chưa lưu sẽ ngăn chặn việc Thoát ứng dụng cho đến khi chủ sở hữu lưu hoặc loại bỏ chúng.

Cú pháp đầy đủ được bật lên tới 8 MiB. Các tệp văn bản lớn hơn mở trong các cửa sổ 256 KiB; 8–64 MiB có thể được tải đầy đủ một cách rõ ràng mà không có cú pháp. Trên 64 MiB sử dụng chỉnh sửa theo cửa sổ và tìm kiếm kết quả khớp tiếp theo có giới hạn. Đây là chế độ tệp lớn có giới hạn, không tương đương với Sublime Text cho các tài liệu lớn tùy ý.

Mở thư mục sử dụng tác vụ hiện tại hoặc ngữ cảnh nhánh/worktree, thay vì chỉ âm thầm mở kho lưu trữ gốc. Một hàng tệp có thể hiển thị thư mục cha của tệp đó. Các đường dẫn được phụ trợ xác thực dựa trên các cấp quyền tác vụ đã đăng ký. Các tệp nhị phân không thể chỉnh sửa dưới dạng văn bản thuần túy; hãy sử dụng trình xem đích của chúng và giữ lại các byte gốc.

Xóa worktree là một hành động được bảo vệ riêng biệt. Kết thúc các phiên có cấu trúc và terminal đính kèm trước khi xóa nó, bao gồm cả các phiên đang rảnh rỗi. Kiểm tra kết quả Git đã lưu và trạng thái khôi phục; xóa bản ghi tác vụ không thể thay thế cho việc bảo tồn an toàn công việc chưa được commit.

Hướng dẫn liên quan: Quy ước trình soạn thảo được định kiểu · Các chính sách Git.

Kết nối API

Mục Kết nối thêm một điểm cuối tương thích với OpenAI được lựa chọn rõ ràng. Nhập tên, URL cơ sở, mô hình và khóa nếu cần. Nhiều máy chủ yêu cầu URL cơ sở kết thúc bằng /v1; hãy tham khảo tài liệu về điểm cuối của bạn.

Bắt buộc dùng HTTPS, ngoại trừ HTTP loopback. Sử dụng điểm cuối thông thường không nhúng thông tin xác thực vào URL. Các khóa sử dụng mã hóa được OS hỗ trợ và không được trả về UI. Việc thay đổi điểm cuối đòi hỏi phải nhập lại khóa. Để trống trường khóa sẽ giữ lại khóa đã lưu; Xóa khóa đã lưu sẽ xóa khóa đó một cách rõ ràng.

Các lệnh gọi API không sử dụng gói đăng ký CLI. Các công cụ và mô hình khác với các phiên gốc, và việc khám phá mô hình thành công không chứng minh được khả năng suy luận. Mức sử dụng token chỉ hiển thị khi nhà cung cấp thực sự trả về thông tin đó.

Lưu giữ thông tin xác thực trong mục Kết nối thay vì văn bản tác vụ hay hướng dẫn cài đặt sẵn. Người đánh giá chỉ đọc chỉ nhận các công cụ tệp API được phép của họ; kiến trúc sư báo cáo không có công cụ nào. Các lệnh gọi công cụ không được hỗ trợ sẽ bị từ chối chứ không âm thầm thực thi. Các máy chủ khác nhau về tham số suy luận, hỗ trợ công cụ và danh sách mô hình; hãy so sánh lỗi với quy ước riêng của điểm cuối.

Hướng dẫn liên quan: Kết nối API.

Cài đặt, ngôn ngữ và đặt lại an toàn

Cài đặt chung chọn không gian làm việc, ngôn ngữ giao diện và các giá trị mặc định. Kết nối quản lý các điểm cuối API. Cài đặt sẵn và Nhóm đánh giá giữ lại cấu hình vai trò. Điều khiển từ xa quản lý thông tin xác thực cục bộ, phạm vi máy chủ và quyền của chủ sở hữu; Cập nhật quản lý nguồn/kênh phát hành. Giới thiệu hiển thị bản dựng chính xác đang chạy.

Ngôn ngữ giao diện độc lập với ngôn ngữ của lời nhắc và trạng thái đánh giá tài liệu. Tên sản phẩm, mã lệnh (command ID), phần mở rộng tệp, mã mô hình của nhà cung cấp và tên do người dùng tạo vẫn được giữ nguyên dạng định danh. Mục Trợ giúp sẽ tuân theo ngôn ngữ giao diện đã chọn khi có sẵn bản dịch hiện tại; các bản dịch máy sẽ được gắn nhãn và bản tiếng Anh vẫn là tài liệu tham khảo chuẩn.

Lưu sẽ áp dụng cấu hình đang hiển thị. Việc đặt lại cơ sở dữ liệu hoặc khôi phục cài đặt gốc có thể xóa siêu dữ liệu của ứng dụng; hãy lưu giữ các tệp và bản sao lưu đã được kiểm nghiệm trước khi chủ động sử dụng tính năng đặt lại. Các thao tác này là hành động thuộc quyền của chủ sở hữu cục bộ. Đừng sử dụng chúng như một lối tắt để điều tra một quy trình làm việc bị lỗi hoặc bản ghi bị hỏng.

Hướng dẫn liên quan: Hướng dẫn bản địa hóa · Khôi phục dữ liệu.

Hỏi trợ lý Trợ giúp

Mở Trợ giúp, chọn một cấu hình dựng sẵn đã kết nối và lưu trong bảng trợ lý, rồi đặt câu hỏi về ZIAForge. Các câu trả lời sử dụng tài liệu hướng dẫn chuẩn hiện tại bằng tiếng Anh và ngôn ngữ giao diện bạn đã chọn. Các nút tham chiếu phần sẽ mở các chủ đề hướng dẫn liên quan, để bạn có thể so sánh lời giải thích với tài liệu tham khảo.

Trợ lý này duy trì một cuộc trò chuyện riêng tư riêng biệt với tối đa 100 mục đã lưu và 3 MiB. Nhập câu hỏi có độ dài tối đa 12,000 ký tự; Gửi sẽ đưa ra câu hỏi, Dừng sẽ hủy câu trả lời đang hoạt động trong khi vẫn giữ câu hỏi của bạn, và Xóa sẽ xóa cuộc trò chuyện Trợ giúp này. Bản nháp chưa gửi và lựa chọn cấu hình dựng sẵn của bạn vẫn được giữ lại khi đóng hoặc mở lại Trợ giúp trong cùng một phiên ứng dụng, nhưng bản nháp không được lưu vào đĩa. Trợ lý không gửi các lệnh ứng dụng, không thay đổi quy trình làm việc hay chấp nhận một cổng kiểm soát. Lời khuyên không phải là sự xác minh trực tiếp đối với một tác vụ, tài khoản hay kết nối bên ngoài.

Các phiên Trợ giúp Claude Code và API thực thi nghiêm ngặt chính sách không dùng công cụ được hỗ trợ. Các phiên Trợ giúp Codex và Antigravity gốc yêu cầu quyền can thiệp máy tính gốc hiện có của chủ sở hữu cục bộ. Nếu quyền này bị vô hiệu hóa, ứng dụng sẽ giải thích điều kiện tiên quyết thay vì chọn một nhà cung cấp khác. Chỉ có chủ sở hữu mới có thể kích hoạt quyền này trong cài đặt kiểm soát cục bộ; trợ lý không thể tự kích hoạt quyền đó.

Trợ giúp Codex sử dụng môi trường hộp cát chỉ đọc và từ chối các yêu cầu phê duyệt công cụ. Antigravity sử dụng chế độ lập kế hoạch (plan) và cờ hộp cát gốc của nó. Các chế độ gốc này không phải là sự bảo đảm tuyệt đối về việc giới hạn của hệ điều hành. Mã băm của hướng dẫn nguồn xác định tài liệu tham khảo được dùng cho câu trả lời; lời giải thích được tạo ra vẫn có thể nhầm lẫn, vì vậy hãy kiểm tra các phần liên kết của nó trước khi hành động. Các câu trả lời cũ hơn sẽ được đánh dấu khi phiên bản hướng dẫn nguồn của chúng khác với hướng dẫn hiện tại.

Hướng dẫn liên quan: Bảo trì tài liệu hướng dẫn chuẩn và bản dịch · Trợ lý ứng dụng và quyền hạn.

Trợ lý và Telegram

Trợ lý sử dụng cấu hình dựng sẵn đã chọn và cùng một API kiểm soát ứng dụng. Quyền kiểm tra trạng thái và quyền thực hiện các thao tác là hoàn toàn riêng biệt. Hãy kiểm tra các lệnh và kết quả: lời văn của trợ lý không phải là bằng chứng cho thấy một hành động đã hoàn thành.

Telegram chỉ được kích hoạt bởi chủ sở hữu cục bộ, cùng với một mã token bot hiện có và một ID chủ sở hữu dạng số. Quyền kiểm soát chỉ dành riêng cho cuộc trò chuyện riêng tư của chủ sở hữu đó. Một bot chưa được định cấu hình hoặc không hoạt động không được phép nhận các tin nhắn của ứng dụng.

Không dán mã token bot vào cuộc trò chuyện thông thường. Việc định cấu hình tích hợp không chứng minh được khả năng kết nối Telegram và không tự động tạo ra một bot. Ảnh chụp màn hình và câu trả lời có thể chứa dữ liệu không gian làm việc riêng tư.

Hãy chọn một cấu hình trợ lý dựng sẵn và cấp quyền thao tác ứng dụng tách biệt với quyền kiểm tra. Việc thực thi trợ lý Codex và Antigravity yêu cầu quyền can thiệp máy tính gốc của chủ sở hữu; chúng không được âm thầm thay thế cho một phiên API hoặc Claude không dùng công cụ. Ảnh chụp màn hình có thể được hiển thị trong cuộc trò chuyện của trợ lý, nhưng dữ liệu đầu vào hiện tại của mô hình không bao gồm tính năng phân tích hình ảnh. Đừng cho rằng trợ lý đã kiểm tra trực quan một hình ảnh chỉ vì nó đã hiển thị hình ảnh đó.

Trợ lý có thể kiểm tra tóm tắt, tác vụ, cuộc trò chuyện, trạng thái quy trình làm việc, ngữ cảnh tiến trình và các cửa sổ ứng dụng thông qua các công cụ định kiểu. Nó có thể thay đổi các cài đặt thông thường được phép và khởi chạy các thao tác ứng dụng đã được ủy quyền. Nó không thể cấp các quyền can thiệp gốc, tiết lộ thông tin xác thực đã lưu, thay đổi từ xa quyền cấp cho không gian làm việc gốc hoặc phê duyệt một cổng kiểm soát Forge chỉ vì thấy tiện lợi.

Hướng dẫn liên quan: Hợp đồng kiểm soát ứng dụng.

Vận hành bot Telegram riêng tư của bạn

Hãy tạo hoặc nhận bot của riêng bạn, bắt đầu cuộc trò chuyện riêng tư với nó, rồi nhập mã token cùng Telegram user ID dạng số của bạn vào phần cài đặt kiểm soát cục bộ. Chỉ bật tích hợp khi bạn muốn ứng dụng kết nối. ID chủ sở hữu là mã định danh người dùng, không phải tên người dùng hay ID của bot. Chỉ các tin nhắn từ người dùng đó trong chính cuộc trò chuyện riêng tư này mới được chấp nhận.

Sử dụng /start, /menu hoặc /status để xem tổng quan về phiên bản đang chạy, số lượng dự án/tác vụ và trạng thái tác vụ. Các nút sẽ mở Dự án, Tác vụ, Ảnh chụp màn hình, Trợ giúp và Ngôn ngữ. Danh sách hiển thị tám mục trên mỗi trang, với các nút điều hướng Quay lại, Làm mới, Trang chủ và Trước/Sau. Các nút dự án lọc danh sách tác vụ. Thẻ tác vụ hiển thị tiến trình quy trình làm việc đã lưu, mô hình/cấu hình dựng sẵn và các câu hỏi đang chờ xử lý nếu có.

Mở phần Trò chuyện của một tác vụ để xem trước các cuộc trò chuyện đang mở/gần đây và cuộc trò chuyện theo giai đoạn của quy trình làm việc. Mỗi bản xem trước hiển thị tối đa sáu tin nhắn mới nhất của người dùng/trợ lý, được rút gọn rõ ràng thành 200 ký tự mỗi tin. Lập luận riêng tư không được hiển thị. Việc đọc lịch sử không khởi động một nhà cung cấp. Các bản xem trước đều là chỉ đọc: văn bản thông thường và lệnh /ask TEXT vẫn gửi đến trợ lý ứng dụng, không bao giờ ngầm gửi đến cuộc trò chuyện tác vụ bạn đang xem.

Chạy / Tiếp tục sẽ đọc lại quy trình làm việc Code hoặc Work hiện tại và bắt đầu một quy trình làm việc hợp lệ đã lưu. Tạm dừng sẽ yêu cầu tạm dừng quy trình đó. Cả hai đều không chấp nhận các yêu cầu, đặc tả, kế hoạch, kết quả đánh giá hay câu hỏi; một quyết định đang chờ xử lý sẽ ngăn cản việc Chạy. Hãy đưa ra quyết định trong ứng dụng, hoặc sử dụng một lệnh định kiểu được ủy quyền rõ ràng với cổng kiểm soát và bản sửa đổi chính xác hiện tại.

Sử dụng Ngôn ngữ hoặc /language để chọn bất kỳ ngôn ngữ nào trong số 56 ngôn ngữ giao diện theo tên bản ngữ của nó. Thao tác này lưu tùy chọn chỉ dành riêng cho bot và chủ sở hữu này. Sử dụng ngôn ngữ ứng dụng sẽ xóa tùy chọn đó. Nó không thay đổi ngôn ngữ của ứng dụng cũng như các quyền truy cập; các tin nhắn hiện có sẽ không được tự động gửi lại.

Điều hướng thường cập nhật cùng một tin nhắn menu đã xuất bản. Các nút có định danh ẩn danh sẽ hết hạn sau 15 phút và chỉ sử dụng được một lần; việc thay đổi thẻ sẽ làm mất hiệu lực các nút cũ của thẻ đó. Các nút đã hết hạn, đã sử dụng, tin nhắn không khớp và của tiến trình trước đó không thể thực hiện hành động. Một tin nhắn dứt khoát không thể chỉnh sửa có thể được thay thế bằng thẻ mới; lỗi mạng không xác định sẽ không được thử lại dưới dạng tin nhắn mới.

Khi kích hoạt, trình thăm dò sẽ loại bỏ các tin nhắn tồn đọng trước đó và ghi lại xác nhận cập nhật trước khi điều phối để các lệnh bị gián đoạn không tự động phát lại khi khởi động lại. Điều này ngăn chặn việc phát lại; nó không bảo đảm việc hoàn thành. Hãy kiểm tra trạng thái/ngữ cảnh trước khi cố ý đưa ra công việc mới sau một lỗi. Không có thông báo trạng thái tác vụ tự động.

Các lệnh tường minh vẫn khả dụng: /projects, /tasks, /task TASK_ID, /run TASK_ID, /pause TASK_ID, /screenshot và /ask TEXT. Lệnh /new {JSON} tạo một tác vụ thông qua createTask định kiểu; /command {JSON} gửi một lệnh danh mục tường minh. Hãy đọc danh mục trực tiếp để biết định dạng đối số. Các bước ủy quyền backend và quyền thư mục tương tự được áp dụng như trong ứng dụng.

Ứng dụng không bao giờ gửi các giá trị mã token bot đã lưu trữ cho trợ lý. Tuy nhiên, ảnh chụp màn hình, tóm tắt và văn bản hội thoại có thể chứa thông tin dự án riêng tư. Hãy dừng tích hợp cục bộ nếu bot hoặc tài khoản chủ sở hữu không còn đáng tin cậy. Hãy xoay vòng mã token bị rò rỉ với nhà cung cấp bot, sau đó cập nhật cấu hình mã hóa cục bộ của nó.

Hướng dẫn liên quan: Bot riêng tư và các lệnh.

Quyền can thiệp máy tính gốc chỉ dành cho chủ sở hữu

Quyền truy cập máy tính gốc ban đầu bị vô hiệu hóa. Chỉ chủ sở hữu mới có thể bật quyền này trong Cài đặt cục bộ → Điều khiển từ xa. Trợ lý và các lệnh HTTP/MCP/Telegram không thể tự kích hoạt cờ này cho chính mình. Nếu một thao tác bị từ chối, trợ lý nên mô tả cài đặt đó và để chủ sở hữu tự quyết định.

Khi được bật một cách tường minh, computer.run sẽ chấp nhận một tệp thực thi, mảng đối số và thư mục làm việc tuyệt đối tùy chọn. Nó không sử dụng nội suy shell, có giới hạn thời gian 30 giây và giới hạn đầu ra ở mức 1 MiB. Thư mục được cung cấp nếu bị thiếu hoặc không hợp lệ sẽ bị từ chối; việc bỏ qua cwd sẽ sử dụng thư mục cài đặt thuộc sở hữu của ứng dụng, chứ không phải HOME. Thoát sẽ hủy các lệnh đang hoạt động thuộc quyền sở hữu và chờ quá trình dọn dẹp tiến trình của chúng.

Phạm vi đọc/thao tác của ứng dụng và quyền truy cập gốc là các quyết định riêng biệt. Một worktree không hạn chế quyền truy cập hệ thống tệp của một nhà cung cấp không bị giới hạn. Hãy thu hồi quyền truy cập gốc sau khi hoàn thành tác vụ nếu không còn cần thiết, và hãy kiểm tra biên nhận lệnh thay vì chấp nhận lời văn của trợ lý làm bằng chứng.

Hướng dẫn liên quan: Hợp đồng kiểm soát chỉ dành cho chủ sở hữu.

Trình duyệt và các phiên bản từ xa

Chủ sở hữu cục bộ kích hoạt máy chủ và chọn địa chỉ, cổng và phạm vi hoạt động của máy chủ: đọc để kiểm tra hoặc thao tác để thực hiện hành động. Địa chỉ mặc định 127.0.0.1 chỉ khả dụng trên máy tính này. 0.0.0.0 lắng nghe trên các giao diện mạng; hãy xem xét kỹ quyền truy cập mạng trước khi kích hoạt.

Trình duyệt sẽ mở cùng một giao diện sau khi đăng nhập bằng mã token. Không đưa mã token vào các liên kết công khai hoặc ảnh chụp màn hình. Chỉ riêng HTTP sẽ không mã hóa lưu lượng; hãy sử dụng một kênh được bảo vệ qua mạng không đáng tin cậy.

Chủ sở hữu định cấu hình các phiên bản khác theo URL và mã token. Phần phụ trợ đóng vai trò proxy cho các yêu cầu; thao tác này không sao chép các dự án của họ vào máy cục bộ. Hãy kiểm tra phiên bản đã chọn trước mỗi hành động.

Các lệnh và sự kiện định kiểu mang theo quyền kiểm soát ứng dụng. Phạm vi đọc không cho phép sửa đổi tác vụ. Quyền kiểm soát máy tính gốc là lựa chọn riêng biệt của chủ sở hữu cục bộ và mặc định bị vô hiệu hóa.

Ứng dụng phải duy trì hoạt động để phục vụ việc kiểm soát qua trình duyệt, Telegram và tác nhân bên ngoài. Mỗi phiên bản có hồ sơ riêng tư, trạng thái tác vụ, mã token và cổng máy chủ riêng. Không tái sử dụng đồng thời một hồ sơ giữa các phiên bản độc lập. Các sự kiện trên trình duyệt và phản hồi lệnh đều nằm trong phạm vi của phiên bản đã chọn; việc chuyển đổi UI không di chuyển tệp hoặc sao chép thông tin đăng nhập gốc.

Hướng dẫn liên quan: Kiểm soát HTTP và phiên bản.

OpenClaw, Hermes và các tác nhân bên ngoài khác

Hãy sử dụng API kiểm soát ứng dụng đã xác thực hoặc cầu nối stdio MCP đi kèm. Bật máy chủ cục bộ, chọn quyền đọc hoặc thao tác và định cấu hình từng ứng dụng khách với URL cùng mã token của phiên bản đó. Cần có Node.js phiên bản 22 trở lên để chạy cầu nối MCP độc lập; ứng dụng Electron không tự cài đặt ứng dụng khách tác nhân của bạn. URL trình duyệt không phải là điểm cuối HTTP MCP có khả năng truyền phát luồng (Streamable): hãy cung cấp nó dưới dạng ZIAFORGE_URL cho cầu nối stdio.

Cầu nối hiển thị ziaforge_status, ziaforge_commands, ziaforge_command và ziaforge_screenshot. Hãy bắt đầu với trạng thái và danh mục lệnh trực tiếp, sau đó đọc system.context cho tác vụ đã chọn. Các lệnh định kiểu tuân theo cùng các bước kiểm tra bản sửa đổi, cổng kiểm soát, thư mục tác vụ và dọn dẹp như trên UI cục bộ.

Danh mục lệnh trực tiếp bao gồm documentation.guide, tài liệu trợ giúp chuẩn bằng tiếng Anh, kèm theo đường dẫn nguồn và sourceSha256 của nó. Kiến trúc sư ứng dụng nội bộ cũng nhận được cùng một tài liệu tham khảo thông qua các công cụ của mình. Điều này cung cấp cho các tác nhân toàn bộ ngữ cảnh sản phẩm mà không cần dựa vào các ghi chú cũ; tài liệu không bao giờ cấp quyền truy cập hoặc thay thế cho quyết định hiện tại của con người.

Các tác nhân nên thảo luận về các yêu cầu, quyết định kỹ thuật và việc lập kế hoạch từ một ý tưởng ngắn gọn của con người. Chúng phải duy trì các cổng kiểm soát tường minh của con người, các mô hình đã chọn, chính sách thủ công/Auto và quy trình đánh giá bắt buộc. Chúng không được tự ý tạo ra sự phê duyệt, chạy lại các lệnh chưa chắc chắn dưới một ID mới, hoặc xuất bản các thay đổi Git mà không có chủ ý của chủ sở hữu.

Hãy định cấu hình nhiều máy chủ MCP được đặt tên cho nhiều bản cài đặt. Chuyển đổi phiên bản là một quyết định định tuyến, không phải đồng bộ hóa. Các ví dụ về cấu hình OpenClaw và Hermes có trong AGENT_CONTROL.md; việc thiết lập và khả năng tương thích riêng của ứng dụng khách phải được kiểm tra đối với phiên bản ứng dụng khách đã cài đặt.

Bộ nhớ đệm requestId bên ngoài chỉ loại bỏ trùng lặp cho một tập hợp yêu cầu giới hạn trong khi ứng dụng đang chạy. Các thao tác bền vững sử dụng định danh riêng của chúng: createRequestId cho việc tạo tác vụ, commandId cho các quyết định quy trình làm việc, clientMessageId cho tin nhắn và operationId cho các sửa đổi Git. Hãy giữ lại định danh và dữ liệu tải trọng ban đầu sau một xác nhận chưa rõ ràng; hãy đọc trạng thái đã lưu trước khi cố ý phát hành công việc mới.

Hướng dẫn liên quan: Hướng dẫn dành cho ứng dụng khách MCP.

CLI cục bộ và các giới hạn tự động hóa

Bộ điều phối ziaf kiểm soát cùng một ứng dụng đang chạy và quy trình làm việc đã lưu. Từ mã nguồn, hãy sử dụng npm run ziaf -- list, npm run ziaf -- status --task TASK_ID --json, npm run ziaf -- start --task TASK_ID hoặc npm run ziaf -- pause --task TASK_ID. Một xác nhận Bắt đầu thành công không có nghĩa là tác vụ đã hoàn thành.

--until-success cố ý bật Auto cho quy trình làm việc đã lưu, nhưng các câu hỏi, bước đánh giá, cổng chấp thuận, giới hạn và điểm kiểm tra vẫn được áp dụng. Phím tắt Ctrl+C sẽ thoát khỏi bộ điều phối quan sát; nó không ngầm dừng quy trình làm việc của ứng dụng. Xem CLI.md để biết mã thoát, điểm cuối cục bộ và cách xử lý hồ sơ.

Giao diện Tự động hóa hiện chỉ lưu trữ các định nghĩa hiển thị và bộ đếm số lần chạy cục bộ. Đây không phải là một trình lên lịch định kỳ được chứng nhận và không chứng minh rằng một lượt mô hình chạy ngầm đã thực thi. Để thực thi thực tế, hãy sử dụng các nút kiểm soát quy trình làm việc đã lưu, ziaf hoặc API đã xác thực và kiểm tra biên nhận của chúng. Đừng nhầm lẫn bảng trình diễn với việc lên lịch tự động không cần giám sát.

Hướng dẫn liên quan: Lệnh điều phối.

Phiên bản và cập nhật

Mục Giới thiệu hiển thị chính xác phiên bản đang chạy. Các bản cập nhật công khai yêu cầu một kho lưu trữ phát hành GitHub đáng tin cậy cùng kênh ổn định hoặc xem trước. Quá trình kiểm tra, tải xuống và cài đặt có các trạng thái riêng biệt; xảy ra lỗi không có nghĩa là bản cập nhật đã được cài đặt.

Cài đặt tự động chỉ dành cho các bản phát hành macOS đã được ký. Các bản dựng phát triển chưa ký không được cài đặt tự động qua cơ chế này. Để thay thế thủ công, hãy thoát hoàn toàn ứng dụng hiện tại và sử dụng một tạo phẩm đã được xác minh.

Tính năng tự động kiểm tra sẽ chạy ngay khi được kích hoạt, sau đó cứ sáu giờ một lần.

Kênh Ổn định loại trừ các bản phát hành xem trước; kênh Xem trước cho phép cả các bản phát hành phát triển. Việc kiểm tra thành công chỉ xác định siêu dữ liệu bản phát hành hiện có. Quá trình tải xuống và cài đặt cần gói nền tảng và nguồn cấp dữ liệu phát hành đã được định cấu hình. Việc phân phối gói Linux DEB là một đường dẫn trình cài đặt riêng; đừng cho rằng gói DEB sẽ tự động được nâng cấp bởi cơ chế cập nhật của macOS.

Hướng dẫn liên quan: Mức độ sẵn sàng phát hành.

Khởi động lại và phục hồi

Trên macOS, sử dụng Thoát / ⌘Q để tắt hoàn toàn ứng dụng. Việc chỉ đóng cửa sổ có thể khiến ứng dụng vẫn tiếp tục chạy. Hãy thoát hoàn toàn phiên bản cũ trước khi thay thế ứng dụng.

Sau khi khởi chạy, hãy chọn lại chính tác vụ đó. Lịch sử và các bản nháp sẽ xuất hiện lại. Tiếp tục sẽ khôi phục ngữ cảnh cục bộ/gốc nhưng không gửi bản nháp, không tiếp tục hàng đợi đang tạm dừng hoặc cho phép lặp lại một thao tác chưa xác định.

Nếu Phục hồi xuất hiện, không chỉnh sửa JSON bằng tay. Hãy kiểm tra loại tài liệu bị ảnh hưởng, giữ nguyên các tệp gốc và chọn một bản sao lưu đã được xác thực. Việc khôi phục một hàng đợi cũ hơn sẽ đánh dấu các mục của hàng đợi đó là không chắc chắn.

Khi quá trình phân phối chưa rõ ràng, một quy trình làm việc được quản lý có thể cần sự cho phép rõ ràng để tạo một ngữ cảnh mới. Công việc trước đó và các lần thử thất bại vẫn được giữ nguyên; một lời từ chối rõ ràng hiển thị trực quan sẽ an toàn hơn một thành công giả mạo.

Hãy sao lưu các tệp tác vụ và hồ sơ ứng dụng khi tất cả các phiên bản ứng dụng đã được đóng. Một thư mục được sao chép không phải là một bản khôi phục đã được kiểm nghiệm. Nếu quá trình phục hồi yêu cầu bạn chọn một bản sao lưu đã được xác thực, hãy giữ lại chính xác các tệp bị hỏng đó. Việc khôi phục một quy trình làm việc hoặc hàng đợi cũ hơn không đồng nghĩa với việc ủy quyền chạy lại tác vụ suy luận hoặc thao tác Git chưa chắc chắn.

Hướng dẫn liên quan: Hợp đồng phục hồi.

Khắc phục sự cố

Không tìm thấy CLI: hãy kiểm tra bản cài đặt và phiên bản của nó trong một terminal thông thường, sau đó khởi động lại ZIAForge. Sự hiện diện của tệp thực thi không đồng nghĩa với việc bạn đã đăng nhập. Hãy sử dụng cơ chế đăng nhập riêng của nhà cung cấp.

Mô hình không khả dụng hoặc xác thực không thành công: hãy làm mới danh sách khám phá, chọn một ID khả dụng và kiểm tra tài khoản cũng như các giới hạn của bạn. Đừng lặp lại một yêu cầu chưa rõ kết quả trước khi kiểm tra lịch sử của nó.

Quy trình làm việc bị dừng: hãy mở giai đoạn hiện tại, câu hỏi, biên nhận xác minh hoặc nhật ký CLI. Hãy xử lý nguyên nhân cụ thể: một câu hỏi chưa được trả lời, lệnh, quyền thư mục hoặc giới hạn số lần thử. Nút Tiếp tục không thể biến một kiểm tra thất bại thành thành công.

Thư mục bị thiếu hoặc bị thay thế: hãy khôi phục quyền truy cập vào thư mục ban đầu hoặc tạo một tác vụ mới. Ứng dụng không được phép tiếp tục từ HOME. Nếu bạn quan sát thấy một cwd khác, hãy dừng lượt hoạt động và lưu giữ dữ liệu chẩn đoán.

Đối với báo cáo, hãy bao gồm phiên bản trong phần Giới thiệu, định tuyến, CLI/mô hình, hành vi mong đợi và thực tế, ảnh chụp màn hình và đoạn trích nhật ký an toàn. Hãy xóa bỏ các bí mật, nội dung cá nhân và đường dẫn không thể công khai.

Trang từ xa không khả dụng: hãy xác minh rằng chủ sở hữu đã bật máy chủ, kiểm tra địa chỉ và cổng đang lắng nghe, sau đó xác thực bằng mã token phiên bản chính xác. Mã lỗi 401 cho biết vấn đề xác thực; một chỉnh sửa bị từ chối có thể do phạm vi chỉ đọc hoặc quyền kiểm soát chỉ dành cho chủ sở hữu. Việc thay đổi mã token sẽ đóng các ứng dụng khách trình duyệt hiện có. Đừng để lộ cổng kiểm tra DevTools riêng biệt làm cổng kiểm soát ứng dụng từ xa.

Lưu trình chỉnh sửa bị từ chối: giữ lại bản nháp, kiểm tra tệp hiện tại trên đĩa và giải quyết xung đột thay đổi từ bên ngoài. Đừng bỏ qua so sánh bằng cách ghi đè siêu dữ liệu ứng dụng. Nếu không thể tải toàn bộ tệp lớn, hãy sử dụng tính năng tìm kiếm/chỉnh sửa theo cửa sổ được hỗ trợ hoặc trình chỉnh sửa bên ngoài.

Telegram không khả dụng: xác nhận mã token bot, chủ sở hữu dạng số, cuộc trò chuyện riêng tư và trạng thái cục bộ. Một webhook hoặc bộ thăm dò xung đột có thể chặn việc thăm dò; ZIAForge không tự động xóa webhook hoặc tiếp quản một bộ thăm dò khác. Các lệnh bị từ chối hoặc bị gián đoạn ở một ranh giới chưa xác định sẽ không được tự động phát lại.

Hướng dẫn liên quan: Kiểm thử và chẩn đoán.

Báo cáo sự cố và kiểm tra bằng chứng

Hãy ghi lại bản dựng đang chạy chính xác từ phần Giới thiệu, OS/kiến trúc, chế độ tác vụ, nhà cung cấp/mô hình đã chọn và các bước tái tạo sự cố. Hãy mô tả kết quả dự kiến cùng kết quả thực tế quan sát được. Đính kèm một ảnh chụp màn hình an toàn cùng biên nhận lệnh hoặc xác minh liên quan đã lưu giữ, thay vì toàn bộ hồ sơ riêng tư.

Nhật ký CLI, nhật ký sự kiện, bản ghi hội thoại của mô hình, dấu vết trình duyệt và ảnh chụp màn hình có thể làm lộ mã nguồn, đường dẫn cá nhân hoặc mã token. Hãy kiểm tra và che giấu thông tin nhạy cảm trước khi chia sẻ. Trình che giấu nhật ký hoạt động theo nỗ lực tối đa không chứng nhận rằng ảnh chụp màn hình hoặc kho lưu trữ đã đủ an toàn để công khai.

Đối với những người đóng góp, qa:doctor đọc thông tin định danh môi trường/bản dựng; qa:inspect mở một hồ sơ cô lập với các bản thay thế mô phỏng nhà cung cấp. Một fixture kiểm thử chứng minh đường dẫn ứng dụng đã kiểm tra mà không cần liên hệ với mô hình. Khả năng suy luận trực tiếp, khả năng kết nối Telegram, môi trường máy tính để bàn Linux gốc, chữ ký và các kiểm tra gói tạo phẩm là những bằng chứng riêng biệt. Xem TESTING.md để biết các lệnh tái tạo và dọn dẹp.

Hướng dẫn liên quan: Lệnh thu thập bằng chứng.

Dữ liệu cục bộ và các ranh giới

Dự án, lịch sử, kế hoạch, tài liệu và chẩn đoán có thể chứa văn bản riêng tư. Không xuất bản hồ sơ, bản ghi chụp thô, khóa hoặc nhật ký đầy đủ kèm theo mã nguồn.

Trên Linux, việc lưu thông tin xác thực API, điều khiển, Telegram và thực thể yêu cầu GNOME Secret Service hoặc KWallet đã mở khóa; nếu không có kho lưu trữ bí mật được hỗ trợ, ZIAForge từ chối lưu các bí mật này thay vì sử dụng phương án dự phòng basic_text của Electron.

Lưu trữ cục bộ không đồng nghĩa với việc các yêu cầu chỉ nằm trên máy tính của bạn: CLI/API đã chọn sẽ gửi chúng đến nhà cung cấp của nó. Một thư mục làm việc và sự giám sát tiến trình không cấu thành sự cô lập của OS. Hãy kiểm tra kỹ các quyền đã chọn.

Phân biệt các loại bằng chứng: fixture kiểm thử ứng dụng mà không cần mô hình; live gốc vận hành trên một CLI/tài khoản thực tế; các kiểm tra đóng gói chứng nhận một tạo phẩm cụ thể. Việc vượt qua một bài kiểm tra không bảo đảm cho những bài kiểm tra còn lại.

Phạm vi ứng dụng, một worktree và lời nhắc chỉ đọc khác biệt với sự thực thi mang tính cưỡng chế của hệ điều hành. Các chính sách người đánh giá/người trợ giúp của Antigravity phát hiện các thay đổi trong bằng chứng không gian làm việc được thu thập thay vì áp đặt quyền truy cập chỉ đọc vào hệ thống tệp. Quyền can thiệp máy tính gốc thực thi các chương trình được chủ sở hữu ủy quyền bên ngoài ranh giới công cụ thông thường của ứng dụng; hãy tắt quyền này khi không còn cần thiết.

Hướng dẫn liên quan: Nguồn gốc và việc xuất bản.

Tìm hiểu và thay đổi dự án mã nguồn mở này

Trước tiên hãy đọc AGENTS.md và CONTRIBUTING.md, sau đó đọc PROJECT_MAP.md để biết các ranh giới nguồn hiện tại. Các hợp đồng định kiểu đã triển khai cùng các tài liệu quy trình làm việc/nhà cung cấp hiện tại sẽ chi phối hành vi. CONCEPT.md và các phần ưu tiên terminal của ARCHITECTURE.md lưu giữ ý định lịch sử và không được nhầm lẫn với các tuyên bố của bản phát hành hiện tại.

Nguồn trợ giúp tiếng Anh là docs/help/en.json. Không chỉnh sửa thủ công tệp USER_GUIDE.md hoặc website/guide.html đã được tạo tự động. Hãy thay đổi phần chuẩn tương ứng, cập nhật hợp đồng bị ảnh hưởng và chạy node scripts/help/generate.cjs. Mục Trợ giúp trong ứng dụng đọc cùng một nguồn này. Hãy xem xét các nội dung bổ sung với việc triển khai thực tế, bao gồm các giới hạn, quyền hạn và các đường dẫn không được hỗ trợ.

Mỗi ngôn ngữ trong số 56 ngôn ngữ giao diện có trạng thái trợ giúp riêng biệt trong docs/help/locales.json. Tài liệu trợ giúp bị thiếu hoặc chưa đầy đủ sẽ sử dụng tiếng Anh dự phòng. Toàn bộ nội dung dịch bằng máy được gắn nhãn và liên kết với mã băm nguồn tiếng Anh, mà không tuyên bố là có sự đánh giá của con người. Bản dịch có sự đánh giá của con người sẽ ghi lại thêm người đánh giá. Mọi bản dịch phải giữ nguyên ID phần, hành động, định danh tệp/lệnh và các giới hạn kỹ thuật, sử dụng đúng hướng hiển thị, và phải được làm mới khi nguồn tiếng Anh thay đổi.

Trước khi phát hành, hãy chạy node scripts/help/generate.cjs --check để phát hiện đầu ra đã tạo bị lỗi thời, khung bản địa hóa không hợp lệ hoặc các liên kết hợp đồng cục bộ bị hỏng. Việc kiểm tra bản dịch UI và kiểm tra hành vi ứng dụng vẫn hoàn toàn riêng biệt. HELP_MAINTENANCE.md cung cấp quy trình cập nhật dành cho người đóng góp và AI; tài liệu không được tuyên bố một kiểm thử đã đạt khi nó chưa hề chạy.

Hướng dẫn liên quan: Bản đồ dự án hiện tại · Bảo trì tài liệu hướng dẫn · Hướng dẫn dành cho người đóng góp · Hướng dẫn dành cho tác nhân.