Dạy OpenWiki vẽ: Từ “Không có sơ đồ” đến một PR thượng nguồn

Phần 3/3 – wiki được tạo không có sơ đồ, vì vậy tôi đã yêu cầu nó vẽ một số, gặp lỗi làm hỏng mọi lần hiển thị, tìm hiểu sâu trong mã nguồn để khắc phục và gửi bản sửa lỗi trở lại dự án. Trong Phần 1, tôi đã trình bày OpenWiki là gì – cách tiếp cận của LangChain đối với “LLM Wiki” của Karpathy, áp dụng cho các cơ sở mã. Trong Phần 2, tôi đã chạy nó trên thực tế và nhận ra rằng việc lựa chọn mô hình quyết định sự thành công hay thất bại của một tác vụ tài liệu tự động. Phần này nói về điều tôi đã bỏ lỡ trong lần đầu tiên, và điều gì đã xảy ra khi tôi theo đuổi nó: sơ đồ. Nó đã trở thành phần thỏa mãn nhất trong toàn bộ thử nghiệm – bởi vì nó kết thúc không phải bằng một giải pháp tạm thời trong bản sao của riêng tôi, mà bằng một yêu cầu kéo (pull request) đối với dự án thực tế. **Khoảng trống** OpenWiki đã tạo ra một wiki thực sự tốt cho kho lưu trữ đơn (monorepo) Spring Boot + Angular của tôi – tổng quan kiến trúc, luồng xác thực, mô hình miền, bề mặt API, tất cả đều đầy đủ. Tất cả đều chính xác, tất cả đều dựa trên mã nguồn. Tất cả đều là văn xuôi và bảng biểu. Không có một sơ đồ nào. Và đối với một cơ sở mã, đó là một thiếu sót lớn. Cách nhanh nhất để giải thích bắt tay làm mới JWT hoặc cách Booking, Event và Settlement liên quan đến nhau không phải là một đoạn văn – mà là một hình ảnh. Một người mới có thể lướt qua một sơ đồ trình tự trong năm giây và hiểu được. Vì vậy, câu hỏi hiển nhiên là: liệu tôi có thể yêu cầu OpenWiki vẽ sơ đồ không? **Mermaid, không phải PlantUML** Nếu bạn muốn các sơ đồ nằm trong một wiki tài liệu dưới dạng mã (docs-as-code), định dạng rất quan trọng. Tôi đã chọn Mermaid [1], và lý do đáng được nêu ra vì đó là cùng một logic làm cho bản thân OpenWiki hoạt động: Mermaid chỉ là markdown được bao bọc – một khối ```mermaid. Nó vẫn có thể so sánh được (diffable), nó được quản lý phiên bản cùng với mã, và nó hiển thị ở nơi tài liệu đã tồn tại. (Một lưu ý chân thành: GitHub và GitLab hiển thị nó nguyên bản; chế độ xem tệp của Bitbucket trong lịch sử không hỗ trợ, vì vậy hãy xác minh máy chủ của bạn trước khi giả định hiển thị nội tuyến. Các tác nhân và Obsidian đều đọc nó tốt theo cả hai cách.) **Tin tốt: không cần fork** Đây là điều đã được làm rõ. OpenWiki [2] được điều khiển bằng lời nhắc (prompt-driven) – về cơ bản, nó là một LLM viết các tệp markdown. Nếu nó có thể viết một bảng, nó có thể viết một khối ```mermaid. Sơ đồ không phải là một tính năng bị thiếu; chúng là một hướng dẫn bị thiếu. Vì vậy, tôi đã chạy một lần duy nhất, chặt chẽ trên một bản sao riêng biệt – sử dụng Opus, lựa chọn đáng tin cậy từ Phần 2 – yêu cầu nó thêm chính xác hai sơ đồ và không thay đổi bất cứ điều gì khác: một sơ đồ trình tự của luồng xác thực và một sơ đồ ER của các thực thể cốt lõi. “Chỉ đọc các tệp cần thiết để làm cho chúng chính xác.” Nó đã làm được. Không phải “có vẻ hợp lý” – mà là chính xác. Nó đã mở bộ chặn xác thực thực tế và đọc thời gian tồn tại của token từ cấu hình. Sơ đồ trình tự mà nó tạo ra: Nó thậm chí còn nắm bắt được hành vi làm mới một lần duy nhất đang diễn ra – chi tiết mà các lỗi 401 đồng thời xếp hàng sau một lệnh gọi làm mới – bởi vì nó đã đọc điều đó từ bộ chặn của tôi. Và trong sơ đồ ER, nó đã vẽ chính xác một mối quan hệ dưới dạng “liên kết mềm”, sau khi nhận thấy rằng một cột có dạng khóa ngoại thực sự là một Long đơn thuần không có mối quan hệ ORM. Đó là sự khác biệt giữa một sơ đồ hữu ích và một sơ đồ sai lệch. **Lỗi đã làm hỏng mọi lần hiển thị** Sau đó, tôi đã cố gắng hiển thị sơ đồ trình tự. Nó đã thất bại. Không phải nội dung – mà là cú pháp. Opus đã viết một nhãn tin nhắn như `store new token; queue concurrent 401s`. Trong sơ đồ trình tự Mermaid, dấu chấm phẩy là một dấu phân cách câu lệnh. Dấu `;` đó đã chia dòng thành một câu lệnh thứ hai, bị định dạng sai, và trình phân tích cú pháp đã từ chối toàn bộ khối. Trên GitHub, nó sẽ hiển thị dưới dạng không có gì – hoặc dưới dạng một hộp lỗi thô. Nội dung là chính xác. Một ký tự độc hại duy nhất đã làm cho nó không thể hiển thị được. Đây là bài học đáng ghi nhớ: sơ đồ được tạo tự động cần một bước xác thực. Mô hình hiểu đúng ý nghĩa và đôi khi mắc lỗi ngữ pháp, còn Mermaid có một vài ký tự – dấu chấm phẩy, dấu gạch đứng, dấu ngoặc nhọn không được thoát – gây lỗi âm thầm bên trong các nhãn. Một bước kiểm tra Mermaid lint trong CI sẽ phát hiện loại lỗi này một cách dễ dàng. Câu hỏi khó hơn: làm thế nào để duy trì điều đó? Một lời nhắc một lần đã cung cấp cho tôi các sơ đồ. Nhưng tôi chạy openwiki --update trên các commit mới – liệu các sơ đồ có tồn tại không? Liệu chúng có được đồng bộ hóa không? Tôi không muốn đoán, vì vậy tôi đã đọc mã nguồn. Hai phát hiện đã thay đổi toàn bộ cách tiếp cận của tôi: Lời nhắc hệ thống chạy trên mọi lần gọi – khởi tạo, cập nhật, trò chuyện. Đây là nơi tự nhiên cho hành vi cố định. Và nó không nói gì về sơ đồ. Chế độ cập nhật được thiết kế để bảo thủ. Các hướng dẫn cập nhật đầy đủ các cụm từ như “bảo toàn cấu trúc hiện có hữu ích”, “các bản cập nhật phải mang tính phẫu thuật”, “không thực hiện các chỉnh sửa chỉ liên quan đến định dạng”. Điều này rất tốt cho sự ổn định – và không tốt cho sơ đồ. Một sơ đồ được thêm vào bởi một lời nhắc một lần rất có thể sẽ bị đóng băng trong khi văn xuôi xung quanh nó thay đổi, hoặc bị bỏ qua như “cấu trúc hiện có cần bảo toàn”. Không có gì giữ cho nó trung thực. Tôi cũng kiểm tra xem AGENTS.md có thể đóng vai trò là hướng dẫn “vui lòng vẽ sơ đồ” liên tục hay không. Nó không thể – OpenWiki chỉ đọc tệp đó để quản lý phần tham chiếu của riêng nó và coi các tài liệu khác là tài liệu nguồn để ghi lại, chứ không phải là hướng dẫn tạo nội dung. Kết luận: khả năng tạo sơ đồ bền vững không thể là một lời nhắc mà tôi nhớ để gõ. Nó phải nằm trong lời nhắc hệ thống và nó phải chỉ rõ cho các lần chạy cập nhật để giữ sơ đồ đồng bộ và tuân thủ các quy tắc an toàn nhãn. Phân nhánh cục bộ… hay sửa cho tất cả mọi người? Cách nhanh chóng là vá lời nhắc hệ thống của bản sao của tôi và tiếp tục. Nhưng đây là mã nguồn mở, và cùng một lỗ hổng sẽ ảnh hưởng đến bất kỳ ai chạy OpenWiki. Vì vậy, tôi đã xây dựng nó như một tính năng có thể đóng góp thay thế. Thiết kế, được tối ưu hóa để thực sự được hợp nhất: Tùy chọn tham gia, mặc định tắt. Một khóa môi trường duy nhất, OPENWIKI_DIAGRAMS=mermaid, phản ánh cấu hình OPENWIKI_PROVIDER / OPENWIKI_MODEL_ID hiện có. Không đặt = hành vi không thay đổi từng byte. Không ai nhận được sơ đồ bất ngờ hoặc chi phí token bất ngờ. Chỉ ở cấp độ lời nhắc. Không có phụ thuộc mới, không có bước hiển thị. Khi được bật, lời nhắc hệ thống sẽ có một phần nhỏ “Quy tắc sơ đồ” hướng dẫn tác nhân nhúng các sơ đồ dựa trên nguồn, giữ chúng đồng bộ khi --update (một sơ đồ cũ là một tuyên bố cũ, không phải cấu trúc cần bảo toàn) và tuân thủ các quy tắc an toàn nhãn của Mermaid (không có dấu chấm phẩy/dấu gạch đứng/dấu ngoặc nhọn không được thoát trong nhãn – lỗi chính xác đó).