Thiết kế File Viewer & Editor cho Agent: Line numbers, linter tích hợp

Định nghĩa

File Viewer & Editor trong ACI (Agent-Computer Interface) là tập hợp các công cụ cho phép agent tương tác với filesystem qua API được thiết kế riêng cho quá trình xử lý token tuần tự — bao gồm viewport giới hạn với line numbers và validation tích hợp thay vì giao diện đồ họa toàn diện như IDE cho người dùng.

Giải thích chi tiết

AI "nhìn" file như thế nào?

Khác với con người có thể scroll nhanh qua file 10.000 dòng và nắm bắt cấu trúc trong vài giây, AI đọc file tuần tự từ token này sang token khác. Khi context window chỉ có hiệu quả thực sự ở 4K-8K tokens cho working memory, đưa toàn bộ file lớn vào prompt tương đương với việc ép người đọc ghi nhớ từng chi tiết nhỏ trong khi đọc một cuốn tiểu thuyết dày cộm từ đầu đến cuối không được lật lại trang.

Line numbers như coordinate system

Trong ACI, line numbers không phải là tính năng hiển thị tùy chọn — đó là hệ tọa độ bắt buộc. Khi AI cần sửa một hàm, nó không thể chỉ nói "sửa cái hàm calculate đó". Nó phải chỉ định chính xác: "thay thế dòng 45-47 bằng đoạn code mới". Thiếu line numbers, agent buộc phải dùng string matching, dễ gây lỗi khi file có nhiều đoạn giống nhau.

Thiết kế của SWE-agent giới hạn viewport ở 100 dòng. Nếu file dài hơn, agent phải chủ động gọi view với parameter offset để dịch chuyển cửa sổ. Điều này tạo ra "friction" có chủ đích: agent buộc phải sử dụng search trước để xác định chính xác vị trí, thay vì "lướt" qua file một cách tốn kém về token và dễ gây mất focus.

Validation tích hợp: Fail fast

Khi AI edit file, lỗi syntax có thể xảy ra: thiếu dấu ngoặc, sai indent, import không tồn tại. Trong môi trường HCI, lập trình viên sẽ thấy lỗi highlight trong IDE và sửa ngay. Trong ACI, nếu không có linter tích hợp, lỗi sẽ được phát hiện ở bước test sau — có thể là 5-10 tool calls sau đó, gây ra expensive backtracking.

Claude Code implement 23 lớp validation, trong đó có lint check chạy ngay sau mỗi lần write hoặc edit. Kết quả trả về cho agent không chỉ là "file đã được ghi", mà là "file đã được ghi và kiểm tra: không có lỗi syntax" hoặc "lỗi tại dòng 45 — thiếu colon". Điều này cho phép agent self-correct ngay trong cùng một reasoning step thay vì phải thực thi rồi mới phát hiện lỗi ở turn sau.

Diff-based editing

Thay vì viết lại toàn bộ file (tốn token và rủi ro hallucination), editor nên hỗ trợ diff-based edit: agent chỉ gửi patch cho các dòng cụ thể. Ví dụ:

Edit lines 45-47:
- old_content
+ new_content

Định dạng này yêu cầu line numbers chính xác và validation ngay lập tức để đảm bảo patch apply đúng và không có xung đột.

Ví dụ thực tế

SWE-agent Windowing

SWE-agent implement file viewer với giới hạn cứng 100 lines. Khi agent gọi view, nó nhận:

[Lines 1-100] def setup():
    ...
[Lines 101-200] (hidden - use offset=101 to view)

Nếu cần sửa dòng 150, agent phải:

1. Dùng search để tìm pattern chính xác
2. Gọi view với offset=101 để xem context
3. Gọi edit với line number chính xác 150

Quy trình này ngăn agent khỏi việc "đọc lướt" file lớn — một thói quen tự nhiên của người nhưng tốn kém cho AI.

Claude Code Linter Integration

Khi Claude Code thực thi tool write, hệ thống:

1. Ghi file
2. Chạy linter (ESLint, Ruff, v.v.)
3. Trả kết quả về agent trong cùng observation

Nếu lỗi xuất hiện:

✗ Write failed validation
Error at line 23: SyntaxError — unexpected indent

Agent thấy lỗi ngay lập tức và có thể gọi edit để sửa trong cùng một turn. Không có validation layer này, agent sẽ tiếp tục làm việc với file bị lỗi, dẫn đến cascade failure khi các edit sau dựa trên nền tảng syntax đã hỏng.

Patch Format trong Aider

Aider (AI pair programming tool) sử dụng Unified Diff format. Agent output:

--- a/calculator.py
+++ b/calculator.py
@@ -45,47 +45,48 @@
 def calculate(x):
-    return x + 1
+    return x + 2

Line numbers (45, 47) cho phép edit chính xác đến từng ký tự. Nếu thiếu line numbers, AI phải dùng string matching và dễ bị lỗi khi file có nhiều hàm tên giống nhau.

Ứng dụng

Sinh viên/Researcher

Hiểu tại sao không thể đơn giản "cho AI đọc cả repo". Khi làm đồ án về code agent, thiết kế file reader với giới hạn 50-100 dòng, luôn attach line numbers, và thêm syntax check trước khi cho agent biết kết quả. Điều này giúp agent chạy ổn định hơn trên codebase lớn hơn vài nghìn dòng.

Developer xây dựng Internal Tools

Thiết kế API cho agent khác với API cho frontend. Thay vì GET /file/content trả về toàn bộ nội dung, dùng GET /file/view?path=x&offset=100&limit=50. Tích hợp linter vào response: trả về content + syntax_valid + errors[]. Điều này giúp agent ít bị "lạc đường" khi edit file.

Tech Lead/AI Architect

Thiết lập quy tắc ACI cho team: "Agent chỉ được xem 100 dòng/lần", "Mọi file operation phải có line numbers", "Validation phải chạy trước khi tool trả kết quả". Điều này giảm 40% lỗi dạng "AI quên nó vừa sửa gì" và "syntax error lan truyền qua nhiều file". Thiết kế này là nền tảng cho multi-agent systems nơi nhiều agent cùng edit code.

So sánh

ACI thiết kế xung quanh giới hạn của LLM: context window hẹp, xử lý tuần tự, cần địa chỉ chính xác. HCI thiết kế cho linh hoạt và trực giác của con người. Dùng đúng ngôn ngữ cho đúng đối tượng — đừng ép AI dùng IDE của người.

Bài viết liên quan

Cùng cụm

Đọc tiếp