Hướng dẫn agent-purge: Quản lý tập trung system prompt và Persona của Coding Agent

agent-purge là gì

agent-purge là một công cụ quản lý lời nhắc hệ thống dành cho nhiều Coding Agent. Các Agent khác nhau có thể đọc lời nhắc thông qua tham số khởi chạy, tệp cấu hình, Hook hoặc plugin. agent-purge đóng gói những khác biệt này, cho phép người dùng thực hiện chèn, chuyển đổi và thu hồi dựa trên cùng một nội dung Persona.

Dự án hỗ trợ ba chế độ:

• replace: thay thế lời nhắc hệ thống mục tiêu bằng nội dung Persona.
• append: nối nội dung Persona vào lời nhắc hiện có.
• off: tắt việc chèn và thu hồi các thay đổi.

Có thể chuyển đổi chế độ khi đang chạy. Sau khi tắt công tắc tổng trên Web hoặc sử dụng --mode off, công cụ sẽ khôi phục các thay đổi liên quan về trạng thái ban đầu, không để lại phần chèn do công cụ quản lý.

Cơ chế và tính năng cốt lõi

Ba kênh thống nhất

agent-purge sử dụng ba kênh để tương thích với các Harness khác nhau. Cả ba kênh cuối cùng đều sử dụng nội dung của tệp hiện tại personas/<id>.md.

• install: ghi khối cấu hình do công cụ quản lý vào Harness mục tiêu, có thể sử dụng cơ chế Markdown, Hooks hoặc plugin. Đây là cấu hình thường trú và cũng có hiệu lực khi người khác trực tiếp khởi chạy Harness tương ứng.
• shim: đặt một vỏ lệnh cùng tên ở phía trước PATH, sau đó chuyển tiếp lệnh gọi đến agent-purge <h>, qua đó tiếp quản lệnh gốc được nhập trực tiếp.
• slash: chuyển đổi khi đang trong phiên bằng /purge on, /purge off hoặc /purge status, không sửa cấu hình trên ổ đĩa.

Bản địa hóa và khả năng hoàn nguyên

Dự án chỉ sửa các vị trí liên quan đến lời nhắc, không sửa tệp nhị phân, cũng không bẻ khóa hoặc vượt qua cơ chế cấp phép. Trạng thái được lưu trong state.json trên máy cục bộ và không được tải lên. Có thể khôi phục trạng thái ban đầu bằng cách gỡ cài đặt, hủy tiếp quản hoặc tắt chế độ.

agent-purge uninstall <h>
agent-purge disarm
agent-purge <h> --mode off

Các Harness cụ thể hỗ trợ những kênh nào phải căn cứ vào kết quả phát hiện trong thời gian chạy trên máy cục bộ.

Yêu cầu trước khi cài đặt

Để chạy agent-purge cần Node.js 20 hoặc mới hơn. Bản thân dự án không có dependency, có thể cài đặt toàn cục qua npm hoặc dùng npx để trực tiếp mở bảng điều khiển Web.

Cài đặt và chạy lần đầu

Cách một: Cài đặt toàn cục

npm i -g agent-purge

Sau khi cài đặt, có thể chạy trực tiếp:

agent-purge web

Địa chỉ mặc định của bảng điều khiển cục bộ là http://127.0.0.1:7788. Mở địa chỉ này trong trình duyệt để xem và quản lý Persona, trạng thái Harness cũng như công tắc tổng.

Cách hai: Khởi động qua npx

Nếu không muốn cài đặt toàn cục trước, có thể chạy trực tiếp:

npx agent-purge web

Thư mục dữ liệu

Cấu hình và Persona không được đặt trong thư mục gói npm, vì vậy việc nâng cấp gói phần mềm sẽ không ghi đè dữ liệu người dùng. Vị trí mặc định như sau:

• Linux và macOS: ~/.agent-purge/
• Windows: C:\Users\<bạn>\.agent-purge\

Thư mục này chủ yếu chứa state.json và personas/. Khi chạy lần đầu, công cụ sẽ tạo mẫu khởi đầu neutral.md trong thư mục Persona.

Nếu từng sử dụng phiên bản 0.1.x, khi chạy phiên bản mới lần đầu, công cụ sẽ tự động di chuyển dữ liệu trước đây nằm trong thư mục gói, đồng thời giữ lại các tệp gốc.

Tùy chỉnh vị trí lưu trữ dữ liệu

Có thể chỉ định một thư mục dữ liệu riêng thông qua biến môi trường AGENT_PURGE_HOME. Cách này phù hợp khi cần sao lưu Persona, phân biệt các môi trường làm việc hoặc chuyển cấu hình sang ổ đĩa khác.

Linux hoặc macOS

export AGENT_PURGE_HOME=/path/to/your/data

Windows

setx AGENT_PURGE_HOME D:\ap-data

Sau khi thiết lập, nên chạy agent-purge trong một phiên terminal mới để đảm bảo biến môi trường đã có hiệu lực.

Tìm hiểu và quản lý Persona

Mỗi Persona tương ứng với một tệp personas/<id>.md. Tệp gồm Frontmatter và phần nội dung, trong đó phần nội dung là văn bản thực tế được ghi vào lời nhắc hệ thống.

Frontmatter hỗ trợ các trường sau:

• description: mô tả Persona, hiển thị trong danh sách Web và đầu ra của agent-purge ls.
• desc: trường mô tả của phiên bản cũ, vẫn được hỗ trợ.
• order: thông tin sắp xếp tùy chọn.
• harness: thông tin khớp Harness tùy chọn.
• model: thông tin khớp model tùy chọn.

Khi chỉ sửa tên và mô tả trong bảng điều khiển Web, các khóa Frontmatter khác sẽ được giữ nguyên, không bị ghi đè toàn bộ.

Liệt kê Persona

agent-purge ls

Lệnh này liệt kê toàn bộ Persona và đánh dấu mục đang khớp. Đồng thời, lệnh cũng hiển thị tình trạng cài đặt Harness, phiên bản, lớp chèn và khả năng sử dụng của từng kênh được phát hiện trong thời gian chạy.

Chuyển Persona hiện tại

agent-purge use <id>

<id> ở đây tương ứng với tên định danh của tệp Persona trong thư mục personas/. Sau khi chuyển, các lệnh gọi được quản lý tiếp theo sẽ sử dụng Persona này.

Chỉ định Persona cho một lần gọi

Nếu không muốn thay đổi lựa chọn toàn cục hiện tại, có thể chỉ định một Persona khác cho riêng lần gọi này:

agent-purge pi --persona <id>

Cách này phù hợp để thử nghiệm tạm thời hiệu quả của các lời nhắc khác nhau. Sau khi lệnh gọi kết thúc, Persona đó sẽ không trở thành lựa chọn mặc định cho các lần gọi tiếp theo.

Ví dụ sử dụng cơ bản

Khởi động bảng điều khiển Web

agent-purge web

Sau đó truy cập http://127.0.0.1:7788. Bảng điều khiển có thể dùng để xem trạng thái hoạt động và điều khiển công tắc tổng. Khi tắt công tắc tổng, phần chèn sẽ được thu hồi.

Khởi động Codex bằng Persona hiện tại

agent-purge codex

agent-purge sẽ xử lý việc khởi động dựa trên Backend tương ứng và môi trường chạy trên máy cục bộ, đồng thời thử áp dụng Persona hiện tại thông qua cơ chế thực sự khả dụng của Harness đó.

Đặt câu hỏi một lần cho pi

agent-purge pi --ask "请检查这个项目的错误处理逻辑"

Lệnh này khởi động một lần gọi bằng Persona hiện tại và sử dụng nội dung phía sau --ask làm câu hỏi cho lượt này.

Chuyển đổi khi đang trong phiên

Với các Harness hỗ trợ kênh Slash, có thể sử dụng trong phiên:

/purge on
/purge status
/purge off

• /purge on: bật chèn Persona.
• /purge status: xem trạng thái hiện tại.
• /purge off: tắt chèn mà không sửa cấu hình trên ổ đĩa.

Cách xác nhận việc chèn thực sự có hiệu lực

matrix.json lưu ma trận khả năng tĩnh, nhưng khai báo tĩnh không nhất thiết đồng nghĩa với trạng thái thực tế trên máy hiện tại. Khác biệt phiên bản, phương thức cài đặt và thay đổi của bản thân Harness đều có thể ảnh hưởng đến khả năng sử dụng kênh.

Vì vậy, nên ưu tiên xem thông tin trong thời gian chạy do agent-purge ls hoặc bảng điều khiển Web cung cấp. Các thông tin này phản ánh:

• Harness đã được cài đặt hay chưa.
• Phiên bản Harness được phát hiện.
• Lời nhắc nằm ở lớp chèn SYS hay USER.
• Ba kênh install, shim và slash có khả dụng hay không.

Khi bảng khả năng tĩnh xung đột với kết quả phát hiện trong thời gian chạy, hãy lấy kết quả trong thời gian chạy làm chuẩn.

Mẹo sử dụng nâng cao

Chuẩn bị nhiều Persona cho các nhiệm vụ khác nhau

Có thể duy trì nhiều tệp Markdown trong personas/, chẳng hạn dùng riêng cho review mã, đề xuất tái cấu trúc hoặc cộng tác phát triển hằng ngày. Dùng description để ghi rõ mục đích và dùng order để điều chỉnh thứ tự hiển thị. Khi cần giới hạn phạm vi khớp, có thể sử dụng trường harness hoặc model.

Trước khi chuyển, hãy chạy:

agent-purge ls

Sau khi xác nhận Persona mục tiêu, thực hiện:

agent-purge use <id>

Phân biệt cấu hình lâu dài và thử nghiệm tạm thời

• Khi cần hiệu lực thường trú, sử dụng kênh install được Harness mục tiêu hỗ trợ.
• Khi muốn các lệnh gốc được nhập trực tiếp cũng do agent-purge tiếp quản, sử dụng kênh shim.
• Khi chỉ muốn thử nghiệm trong phiên hiện tại, ưu tiên kênh slash hoặc tham số --persona cho một lần gọi.

Khả năng sử dụng một kênh cụ thể vẫn phải căn cứ vào kết quả phát hiện trong thời gian chạy.

Giữ đường lui trước khi sửa đổi

Mặc dù dự án lưu trạng thái và cung cấp các thao tác có thể hoàn nguyên, trong thực tế vẫn nên xác nhận Persona hiện tại, Harness mục tiêu và chế độ đang bật trước. Sau khi kiểm thử xong, có thể thu hồi bằng các cách sau:

agent-purge uninstall <h>
agent-purge disarm

Cũng có thể chuyển sang --mode off hoặc tắt công tắc tổng trong bảng điều khiển Web.

Không nhầm việc khởi động nguyên trạng với việc chèn thành công

Đối với các ứng dụng desktop mã nguồn đóng mà lời nhắc hệ thống nằm ở phía máy chủ hoặc bên trong tệp nhị phân đóng, agent-purge chỉ khởi động nguyên trạng và không thực hiện chèn lời nhắc. Khi chạy agent-purge <h>, công cụ sẽ nêu rõ lý do không thể chèn thay vì giả vờ rằng việc chèn đã có hiệu lực.

Tổng quan nhanh về cấu trúc dự án

• bin/: điểm vào CLI.
• lib/: logic trạng thái, Persona, chèn, kênh và phát hiện.
• backends/: tham số khởi động và xử lý câu lệnh nhận dạng của từng Harness.
• web/: bảng điều khiển cục bộ, gồm server.mjs và ui.html.
• bench/: phép đo thực tế tỷ lệ chèn thành công và tập lệnh chấm, chỉ dùng cho phát triển, không tham gia quá trình chạy thông thường.
• matrix.json: ma trận khả năng tĩnh.

Ranh giới về bảo mật, quyền riêng tư và tuân thủ

agent-purge được định vị là một Harness chính thức cục bộ mà người dùng có quyền quản lý, phục vụ kỹ thuật prompt và đánh giá độ bền vững. Công cụ này không sửa đổi tệp nhị phân, không vượt qua cơ chế cấp quyền, không tải trạng thái cục bộ lên bên ngoài và không được sử dụng cho các hệ thống chưa được cấp phép.

• Chỉ sử dụng trên các thiết bị, phần mềm và môi trường thử nghiệm tuân thủ mà bạn có quyền kiểm soát.
• Không được sử dụng cho tấn công trái phép, khai thác lỗ hổng, đánh cắp dữ liệu, xâm nhập bất hợp pháp hoặc phát tán payload độc hại.
• Không được vi phạm pháp luật hiện hành, điều khoản dịch vụ mô hình và chính sách chống lạm dụng.
• Dự án được cung cấp theo giấy phép MIT, “nguyên trạng”; người sử dụng chịu trách nhiệm về đầu vào, đầu ra và hành vi sử dụng của mình.
• Khi sử dụng tên dự án, ý tưởng, mã nguồn hoặc prompt của dự án, cần ghi công và nêu rõ nguồn theo tuyên bố của kho lưu trữ.

README cũng đưa ra các hạn chế nghiêm ngặt đối với việc truy cập máy chủ và trang web tại một số khu vực cụ thể. Trước khi sử dụng thực tế, cần đọc đầy đủ tuyên bố miễn trừ trách nhiệm và tuân thủ trong kho lưu trữ, đồng thời bảo đảm phạm vi thao tác đáp ứng các yêu cầu đó.

Tóm tắt

agent-purge hợp nhất các điểm truy cập prompt không nhất quán của nhiều Coding Agent thành các khái niệm như Persona, install, shim và slash, đồng thời cung cấp bảng điều khiển Web, khả năng phát hiện trong thời gian chạy và thu hồi có thể đảo ngược. Khi bắt đầu, bạn có thể cài đặt công cụ, mở bảng điều khiển Web, chạy agent-purge ls để kiểm tra khả năng hỗ trợ, sau đó chọn Persona để khởi động Harness mục tiêu. Đối với thử nghiệm tạm thời, nên ưu tiên Persona dùng một lần hoặc chuyển đổi nóng trong phiên; đối với cấu hình dài hạn, chỉ nên bật kênh thường trú sau khi xác nhận khả năng trong thời gian chạy và ranh giới tuân thủ.