Thêm một bước vào danh sách của nhóm mà không sửa nhầm phần còn lại
Thêm một bước vào danh sách việc cần làm của nhóm nghĩa là phải tìm đúng trang, đọc những gì đang có và chỉ sửa đúng chỗ cần sửa. Mình tạo ra Outline CLI để coding agent cũng làm được như vậy trong wiki của nhóm.
Tóm tắt
Thêm một bước vào danh sách việc cần làm trên wiki của nhóm nghĩa là phải tìm đúng trang giữa những tiêu đề na ná nhau, đọc những gì đang có và chỉ sửa đúng chỗ đó. Mình tạo ra Outline CLI để coding agent cũng làm theo trình tự ấy trên wiki Outline ngay từ terminal, xem trước từng bản sửa và đối chiếu phiên bản của trang trước khi lưu. Bài viết có kèm hướng dẫn cài đặt.
Giả sử nhóm của bạn lưu tài liệu chung trong một wiki, và danh sách việc cần làm cho người mới trong đó cần thêm một bước. Nghe thì có vẻ là việc nhanh gọn, nhưng trước khi gõ bước mới vào, bạn phải tìm đúng danh sách đó, mà tìm kiếm thì có thể trả về một bản cũ, một hướng dẫn liên quan và một trang có tiêu đề gần giống cái bạn nhớ. Mở được đúng trang rồi, bạn vẫn cần đọc đủ nội dung để biết bước mới nên nằm ở đâu, và khi sửa thì chỉ thêm đúng bước đó, còn các dòng khác giữ nguyên như cũ.
Những bước nhỏ ấy cũng xuất hiện khi coding agent hỗ trợ việc viết và sửa tài liệu. Coding agent là trợ lý AI có thể đọc và sửa code, và vì công việc của agent có thể phụ thuộc vào các quyết định được ghi trong wiki của nhóm, đôi khi agent phải tra cứu hoặc cập nhật một trang trong đó. Nếu bỏ qua bước tìm và bước đọc, agent vẫn có thể tạo ra một bản sửa trông rất gọn gàng, chỉ có điều bản sửa ấy lại nằm trong bản cũ hoặc đặt bước mới sai chỗ.
Điều mình muốn là agent đi theo đúng thứ tự mà một người cẩn thận sẽ làm: tìm trang, đọc nội dung hiện tại, rồi mới chuẩn bị một thay đổi đủ nhỏ để người khác kiểm tra được. Vì vậy mình tạo ra Outline CLI để coding agent tìm và sửa trang trong Outline, một wiki dùng chung cho nhóm, ngay từ cửa sổ dòng lệnh (terminal). Công cụ có thể tìm kiếm trong một không gian làm việc (workspace), đọc trang cùng tệp đính kèm và cập nhật nội dung. Dự án này độc lập với Outline.
Nếu hình dung wiki như một kệ sổ tay, thì Outline CLI giữ một tấm thẻ mục lục cho mỗi trang agent từng gặp, cho agent rút ra toàn bộ trang đằng sau tấm thẻ ấy, và bắt agent ghi lại phiên bản trang mà nó đã đọc, để trước khi một thay đổi được lưu vào, công cụ còn đối chiếu được với phiên bản đó.
Khi agent đi tìm danh sách
Agent có thể bắt đầu bằng tiêu đề hoặc dán một URL. Outline CLI trước hết tìm trong chỉ mục lưu trên máy, gồm những tài liệu đã gặp trước đó và được tách riêng theo hồ sơ kết nối (profile) agent đang chọn; chỉ với tài liệu chưa có trong chỉ mục, công cụ mới tra cứu trực tiếp trên workspace trong một phạm vi giới hạn. Khi có nhiều trang khớp, chẳng hạn bản cũ và bản hướng dẫn liên quan nói ở trên, công cụ trả về một danh sách để agent chọn. Nếu muốn xem việc chọn tài liệu ảnh hưởng thế nào đến một thay đổi trong sản phẩm, bạn có thể đọc bài viết về chuyện tìm đúng tài liệu.
Khi agent mở trang đã chọn
Danh sách kết quả giúp agent tìm đúng tài liệu, nhưng để biết nên thêm bước mới vào đâu, agent cần đọc nội dung hiện tại, vì các hướng dẫn có thể đã thay đổi dù tiêu đề vẫn như cũ. Agent có thể xin bản tóm tắt trước rồi mới đọc toàn bộ tài liệu đã chọn, nhờ vậy thấy được các bước đang có quanh chỗ sẽ thêm bước mới, và kết quả trả về còn kèm URL nguồn của trang để người khác mở đúng nội dung mà agent đã đọc.
Khi bước mới được thêm vào trang
Một thay đổi đề xuất cần cho thấy phần được thêm và phần bị bỏ, nên Outline CLI có thể cho xem trước phần khác biệt (diff) trước khi lưu. Bản sửa được áp dụng kèm số phiên bản của trang mà agent dựa vào khi sửa, và nếu phiên bản hiện tại không khớp, công cụ có thể dừng trước khi gửi bản sửa để agent đọc lại trang. Bước kiểm tra này diễn ra trước khi ghi và không khóa tài liệu, nên một chỉnh sửa khác đến sau đó vẫn có thể được lưu.
Nhờ vậy người duyệt có hai câu hỏi cụ thể để trả lời: bước mới có nằm đúng chỗ không, và phần còn lại của danh sách có còn giữ đúng nội dung cần có không. Sau khi lưu thay đổi đã được cho phép, hãy yêu cầu agent gửi lại liên kết đến trang vừa sửa để ai cũng dễ tìm thấy.
Khi chính coding agent làm Outline CLI
Coding agent cũng đảm nhiệm một phần đáng kể việc triển khai Outline CLI, còn mình dẫn dắt việc phát triển: mình đặt ra quy trình mà công cụ tuân theo, review và kiểm soát những thay đổi code do agent tạo ra, rồi thử lại để kiểm tra các lệnh có đi đúng thứ tự tìm, đọc rồi mới sửa, và có giữ mỗi bản sửa trong đúng phạm vi được yêu cầu hay không.
Kết nối Outline CLI và làm việc với một trang
Kết nối và thử đọc
Theo tài liệu, môi trường chạy cần Node.js 18.17 trở lên, và bạn cũng cần quyền truy cập một workspace Outline.
npm i -g @khanglvm/outline-cli
Trên máy có thể đã được cấu hình từ trước, hãy kiểm tra outline-cli profile list trước khi tạo profile. Với kết nối mới, tạo khóa API trong mục cài đặt API & Apps của workspace, đặt OUTLINE_API_KEY trên máy và thay địa chỉ ví dụ:
outline-cli profile add work \
--base-url https://docs.example.com \
--auth-type apiKey \
--api-key "$OUTLINE_API_KEY" \
--set-default
outline-cli profile test work
Thông tin đăng nhập mặc định được lưu trong kho thông tin xác thực (keychain) của hệ điều hành, và không nên đưa vào cuộc trò chuyện hay vào source code. Mỗi profile của một workspace lưu riêng tài khoản đã chọn.
Tìm một từ có trong trang:
outline-cli invoke documents.search \
--args '{"query":"onboarding","limit":5,"view":"summary"}'
Sau khi chọn kết quả, thay bằng ID của tài liệu đó:
outline-cli invoke documents.info \
--args '{"id":"<document-id>","view":"full"}'
Lệnh và hướng dẫn cho agent
Dùng documents.open khi đã biết tiêu đề hoặc URL. Thao tác ghi cần performAction:true, còn thao tác xóa cần thêm mã xác nhận (token) từ một lần đọc trước đó của chính tài liệu ấy. Các tham số lệnh chính xác có sẵn qua outline-cli tools contract <name>.
Bạn có thể cài thêm bộ hướng dẫn cho agent (skill) về các quy trình thường dùng:
npx skills add https://github.com/khanglvm/skills --skill outline-cli -y
Hãy yêu cầu agent kiểm tra các profile hiện có, tìm kiếm bằng chế độ xem gọn, đọc trước khi sửa và cho xem phần khác biệt dự kiến; bước đối chiếu với phiên bản tài liệu đã đọc và cờ cho phép thực thi đều hỗ trợ quy trình này. Hướng dẫn sử dụng trình bày cách làm việc với tệp đính kèm, lịch sử và các bước chỉnh sửa có kiểm tra điều kiện trước khi thực hiện, còn gói cài đặt có trên npm.