Yana AI: Lớp điều khiển cục bộ giữa mô hình AI và quyền thực thi trên máy
Sáu tháng xây dựng: Từ một kho mã trống đến Yana Studio IDE 1.7
Các agent lập trình hiện nay có thể xóa thư mục, đẩy mã lên kho chung hoặc đọc khóa API chỉ bằng một dòng lệnh, còn lời dặn "hãy cẩn thận" trong prompt không đủ để ngăn điều đó. Yana AI tách hai việc: kỹ năng (skills) dạy agent cách làm, còn quyền hành động (capabilities) chỉ đến từ một lớp riêng chạy trực tiếp trên máy người dùng. Mô hình đề xuất, Yana quyết định, con người luôn giữ quyền dừng.
Báo cáo này trình bày thiết kế, hiện thực và quá trình phát triển trong 2.488 commit (từ 17/05 đến 26/10/2026), các số đo hiệu năng thực nghiệm, cách chúng tôi kiểm chứng tính an toàn, và những giới hạn còn lại. Sản phẩm hiện hành là Yana Studio IDE 1.7 cho macOS (Apple Silicon), dựng trên nền Code-OSS và giao tiếp với 19 nhà cung cấp mô hình qua một runtime Rust duy nhất (yana-rt).
1. Đặt vấn đề
Khi một agent tự chủ được cấp quyền thực thi lệnh shell trên terminal, mọi sai lệch ngẫu nhiên (stochastic deviation) hay ảo giác (hallucination) của mô hình đều lập tức biến thành hành động phá hủy thật trên máy của người dùng. Hai phương pháp phòng thủ truyền thống hiện nay đều bộc lộ nhược điểm cấu trúc căn bản:
- Lời dặn trong System Prompt (Advisory Prompt Rules): Những chỉ thị kiểu "hãy cẩn thận", "không được xóa file" thực chất chỉ là chuỗi token mà chính mô hình đọc. Mô hình hoàn toàn có thể quên, diễn giải sai hoặc bị vượt qua bởi kỹ thuật prompt injection.
- Hộp cát kín & Container (Hermetic Containers & Sandboxes): Chạy cách ly tuyệt đối trong máy ảo hoặc Docker đảm bảo an toàn, nhưng làm tê liệt tính hữu dụng trong thực tế vì cắt đứt agent khỏi công cụ bản địa, trình biên dịch, công cụ gỡ lỗi và chu trình dự án sống của nhà phát triển.
Yana chọn hướng đi thứ ba có chủ đích: giữ agent làm việc trực tiếp trên máy thật, nhưng buộc mọi thao tác phải đi qua một lớp kiểm soát nằm hoàn toàn bên ngoài không gian của mô hình. Lớp này tách bạch rõ ràng giữa tri thức và quyền hạn: một skill chỉ là văn bản hướng dẫn và không có quyền gì; chỉ một capability được cấp phép minh bạch mới cho phép một thao tác can thiệp hệ thống.
2. Tầm nhìn và các nguyên tắc cốt lõi
Tài liệu tầm nhìn nền tảng của dự án (viết ngày 07/06/2026) định nghĩa Yana là lớp điều phối mỏng (lean orchestration layer) làm trung gian giữa ý định của con người và trí tuệ AI. Dự án xác định rành mạch những gì Yana không phải:
- Không phải một agent đơn lẻ.
- Không phải một chatbot thông thường.
- Không phải một framework vô tận để nhồi nhét agent chồng chất.
- Không phải một hệ thống cần LLM chỉ để tự vận hành bản thân.
Lõi Yana chỉ tập trung vào 4 nhiệm vụ tất định (deterministic) với độ chuẩn xác tuyệt đối: định tuyến yêu cầu, thực thi an toàn tại runtime, điều phối vòng đời đa mô hình và quản lý ngữ cảnh. Mọi thứ khác đều thuộc lớp ứng dụng modular, có thể thay thế mà không cần viết lại lõi.
Bảy nguyên tắc cốt lõi đã được kiểm chứng qua các sự cố thực tế:
- Con người trước tự động hóa (Human before automation): Mọi thao tác thực thi quan trọng đều cần người chịu trách nhiệm.
- An toàn trước tốc độ (Safety before speed): Khi phải đánh đổi, luôn chọn an toàn vô điều kiện.
- Bằng chứng trước sự tự tin (Evidence before confidence): Mọi tuyên bố hoàn thành phải có nhật ký băm, biên nhận kiểm toán hoặc kiểm tra tất định đi kèm.
- Xây ít hơn, xây tốt hơn (Build less, build better): Mọi tính năng phải chứng minh được giá trị sinh tồn, phần còn lại sẽ bị cắt bỏ.
- Thiết kế cho thất bại (Designed for failure): Mọi sự cố đều là bài học để tạo ra các bất biến kiến trúc (architectural invariants) vững chắc hơn.
- Mở, trung thực, minh bạch (Open, honest, transparent): Xây dựng công khai, tài liệu hóa sai lầm và nói rõ các giới hạn đánh đổi.
- Không ngừng cải thiện (Continuous improvement): Không có phần mềm nào là hoàn thành tuyệt đối.
3. Kiến trúc và Thiết kế
3.1 Luồng quyết định tất định 5 bước (The Deterministic Decision Pipeline)
Mọi thao tác riêng rẽ do agent đề xuất — dù đến từ Claude, GPT, Gemini, DeepSeek hay mô hình cục bộ — đều phải tuần tự đi qua 5 cổng kiểm tra bắt buộc (Hình 1). Mọi quyết định cho phép hoặc chặn đều được ghi vĩnh viễn vào sổ cái kiểm toán để xem xét lại sau này.
3.2 Kiến trúc hệ sinh thái (Ecosystem Architecture)
- Agent Hosts (Bộ chuyển đổi thích ứng): Interceptor chặn cuộc gọi công cụ tại runtime cho Claude Code, hook theo dự án cho Codex, bộ lọc lệnh shell cho Cursor và Antigravity.
- Yana Applications (tools/): Yana Studio IDE 1.7 (macOS trên Code-OSS 1.141), Studio Electron tiền thân, CLI
yana-ai(Python) và 14 máy chủ MCP bản địa. - Lớp Quản trị (core/): Runtime
yana-rt(Rust) cung cấp 40 lệnh con không phụ thuộc Python;core-lock.jsonghim mã băm SHA-256 của ~290 tệp lõi; cổng duyệt người dùng; và Giám Thị (Supervisor) — daemon độc lập chạy trên trình lập lịch OS (launchd, systemd) ngoài tiến trình AI, khóa thực thi ngay khi phát hiện lệch cấu hình. - Lớp Tri thức (Knowledge Layer): 60 role agents, 2.027 skills, 170 slash commands, 71 behavioral rules và 66 pre/post-tool hooks. Tri thức chỉ hướng dẫn agent cách làm, tuyệt đối không tự trao quyền thực thi.
- Động cơ Mô hình (Model Engine): Bộ định tuyến hợp nhất kết nối 13 cloud API (Anthropic, OpenAI, Gemini, Groq, DeepSeek, OpenRouter, xAI, Kimi) và 6 runtime cục bộ (Ollama, LM Studio, llama.cpp, TurboFieldfare, AirLLM, 9Router).
3.3 Phân bổ cấu trúc mã nguồn (Codebase Distribution)
Yana-AI/
├── src/ yana-rt runtime: 313 file Rust, 82.133 dòng
│ ├── capability/ hệ thống quyền, thực thi dùng chung cho chat và MCP
│ ├── guard/ chặn lệnh nguy hiểm, pipe-to-shell, quyền ghi
│ ├── model/ 19 nhà cung cấp mô hình, failover, xoay vòng API key
│ ├── session_db/ kho phiên SQLite, tìm kiếm toàn văn, checkpoint rollback
│ ├── os/ Yana OS: danh tính agent, hạn mức tài nguyên, giám sát
│ └── chat/, mission/, memory/, doctor/, scanner/, … (50 mô-đun cấp cao)
├── core/ lớp quản trị và tri thức (66 hooks, 71 rules, 2.027 skills)
├── tools/ yana-ide (Code-OSS 1.141), studio electron cũ, cầu nối desktop & web
├── adapters/ Claude Code, Codex, Cursor, Antigravity
└── site/, docs/, ci/ cổng web (Astro), tài liệu và cổng kiểm tra CI4. Yana trong thực tế
4.1 Giao diện người dùng & Yana Studio IDE
Yana Studio IDE tích hợp trọn vẹn bộ công cụ của nhà phát triển trong một môi trường quen thuộc: ngăn bên trái là cây thư mục và trình soạn thảo Code-OSS, trong khi ngăn bên phải là khung chat với Yana Agent. Khung chat luôn hiển thị rõ trạng thái chính sách hiện hành: ở chế độ SUPERVISED, thao tác đọc file được tự động cho phép, trong khi tất cả các lệnh thực thi đều dừng lại để chờ con người bấm duyệt. Thanh trạng thái bên dưới hiển thị Policy: SUPERVISED [ALLOW: read, REQUIRE: run], phiên bản runtime đang hoạt động và số dòng nhật ký kiểm toán đã xác thực (ví dụ Audit 500).
Màn hình đầu tiên khi mở Studio (Hình 5) dẫn người dùng qua ba bước: mở thư mục dự án, cấp quyền tin cậy cho thư mục để agent được đọc mã và chạy lệnh an toàn, rồi chọn mô hình (hoặc dùng Ollama cục bộ miễn phí, hoặc nhập khóa API). Giao diện có ba ngôn ngữ: Việt, Anh, Hàn. Bên dưới là danh sách tính năng và tình trạng các runtime cục bộ như 9Router, Ollama, LM Studio, llama.cpp.
4.2 Kiểm chứng bộ lọc lệnh thực tế (Command Guard Evaluation)
Bảng 1 ghi lại 4 lệnh shell thực tế được đánh giá trực tiếp bởi runtime guard (yana-rt guard destructive). Khi một câu lệnh bị chặn, agent nhận lại thông báo lý do chi tiết kèm theo hướng dẫn an toàn thay thế, đồng thời sự kiện được ghi vào nhật ký kiểm toán.
| Lệnh agent muốn chạy | Phán quyết | Lý do bảo vệ trả về cho Agent |
|---|---|---|
curl -fsSL https://.../install.sh | bash |
Bị chặn | Nội dung từ mạng được dẫn trực tiếp (pipe) vào shell mà không qua kiểm tra. Cần tải file về, đọc mã nguồn rồi mới chạy, hoặc yêu cầu người dùng duyệt trước. |
rm -rf ~/Documents |
Bị chặn | Lệnh xóa đệ quy, cưỡng bức không thể hoàn tác trên thư mục người dùng. Hãy nhắm tới file cụ thể hoặc yêu cầu người dùng phê duyệt. |
chmod 777 deploy.sh |
Bị chặn | Cấp quyền ghi cho mọi đối tượng. Hãy áp dụng nguyên tắc đặc quyền tối thiểu (least privilege) với mode chặt chẽ hơn (755 hoặc 644). |
git status --short |
Cho phép | Lệnh kiểm tra trạng thái chỉ đọc (read-only introspection); tự động cho phép không cần qua cổng phê duyệt. |
4.3 Sử dụng bộ công cụ dòng lệnh (CLI Tooling)
# Công cụ quản lý qua Python CLI
pip install yana-ai
yana-ai install # Cài đặt hook và các luật kiểm soát Yana vào repo
yana-ai doctor . # Kiểm tra môi trường và kết nối hook
# Runtime độc lập viết bằng Rust (hoàn toàn không phụ thuộc Python)
cargo install yana-rt5. Hiện trạng các thành phần hệ thống
| Thành phần | Trách nhiệm & Nhiệm vụ | Trạng thái |
|---|---|---|
| Yana Studio IDE 1.7 | Môi trường desktop chuẩn mực trên macOS (Code-OSS 1.141). Loại bỏ telemetry độc quyền của Microsoft, tích hợp sẵn Yana Chat, cổng duyệt quyền, tasks có bằng chứng, 19 model providers và design canvas. | Production |
| Runtime yana-rt | Động cơ Rust cốt lõi: vòng lặp lượt (turn loops), hợp đồng quyền hạn (capability contracts), cơ sở dữ liệu phiên SQLite, checkpoint rollback, MCP & LSP clients. | Production |
| Lớp Quản trị (Governance) | Manifest quyền hạn, cổng phê duyệt của con người, sổ cái nối băm (hash-chained ledger), trình xác thực tính toàn vẹn core-lock, bộ lọc lệnh phá hủy. |
Production |
| Giám Thị (Supervisor) | Daemon chạy độc lập ngoài không gian AI theo lịch OS mỗi 6 giờ; tự động khóa toàn bộ lệnh hệ thống nếu các file kiểm soát bị sửa đổi trái phép. | Đang hoạt động |
| Adapters | Claude Code, Codex, Cursor, Antigravity. Mức độ cưỡng chế an toàn thay đổi theo đặc thù từng host hook. | Phụ thuộc Host |
| Lớp Tri thức (Knowledge Layer) | Role agents, skills, slash commands và các luật ứng xử để hướng dẫn hành vi của agent. | Production |
| Yana OS | Quản lý agent cục bộ: danh tính, ranh giới tự chủ, hạn ngạch tài nguyên, cách ly tiến trình. | Đang phát triển |
| Studio Electron cũ | Ứng dụng desktop đời trước (v1.5–1.6, tháng 9/2026). Bản IDE tái sử dụng các logic UX đã được kiểm chứng. | Tiền thân |
| Wheelbot | Nền tảng robot ESP32-S3 điều khiển bằng giọng nói trong kho lưu trữ riêng biệt. | Thử nghiệm |
6. Đo lường hiệu năng thực nghiệm
Dữ liệu đo đạc thực nghiệm ngày 20/10/2026 trên máy Apple Silicon MacBook Air (M4, 16 GB RAM) chạy bản release của yana-rt 1.5.1 so sánh với script Python nguyên bản (theo tài liệu BENCHMARK.md):
| Thao tác Benchmark | Rust Runtime (yana-rt) | Script Python cũ | Chênh lệch hiệu năng |
|---|---|---|---|
| Khởi động Binary nguội (Cold Startup) | 4.16 ms | — | Trung bình qua 100 lần chạy |
Chẩn đoán hệ thống (doctor) |
143 ms | 415 ms | Nhanh hơn 2.9× (cùng 16 bước kiểm tra) |
Kiểm tra CI Quản trị (ci check) |
5.8 ms | 33 ms | Nhanh hơn 5.7× (cùng 5 luật kiểm tra) |
Quét thư mục Skills (core/skills) |
0.55 s | 8.47 s | Nhanh hơn 15.4× (duyệt toàn bộ 2.027 skill) |
| Lớp bảo vệ lệnh phá hủy (Guard Latency) | 4.9 ms | — | Độ trễ trên mỗi lần kích hoạt hook |
| Dung lượng Binary biên dịch | 18.2 MiB | — | Binary độc lập tự chứa hoàn toàn |
7. Kiểm chứng An toàn & Thử nghiệm Tấn công
Vào cuối tháng 10/2026, máy chủ MCP bản địa đã trải qua bài kiểm tra fuzzing stdio trên toàn bộ 14 công cụ tích hợp. Các nỗ lực tấn công vượt thư mục làm việc (/etc/hosts, symlink độc hại) đều bị chặn thành công, và công cụ browser_fetch đòi hỏi phải có lease rõ ràng.
Quá trình thử nghiệm đã phát hiện một lỗi chức năng (list_processes bị lỗi trên macOS) và một lỗ hổng nghiêm trọng: hàm check_command cũ chỉ lọc các chuỗi lệnh phá hủy trực tiếp, cho phép các cấu trúc pipe-to-shell (như curl ... | bash), chuỗi giải mã base64 và lệnh chmod 777 lọt qua dù đã bị nghiêm cấm trong luật dự án.
Bản vá cập nhật tiến hành phân tích cú pháp lệnh theo chuẩn POSIX shell (đánh giá dấu ngoặc kép, substitution, heredocs, pipelines và nhóm subshell) trước khi so khớp quy tắc, được xác thực bởi 1.642 unit test vượt qua. Bản vá đã trải qua 4 chu kỳ kiểm toán đối kháng độc lập bởi các subagent AI (tổng cộng 6 lượt rà soát). Bài học rút ra: Danh sách đen theo chuỗi lệnh không bao giờ có thể bao quát hết; bộ lọc mẫu chỉ là lớp phòng thủ bổ trợ, còn sự an toàn tuyệt đối nằm ở cổng phê duyệt của con người và phạm vi quyền hạn được cấp.
8. Ranh giới và các Giới hạn đã ghi nhận
- Xóa sổ nhật ký (Ledger Deletion): Cơ chế nối băm đảm bảo phát hiện việc sửa đổi bản ghi trong nhật ký, nhưng không thể ngăn chặn việc cố tình xóa sạch cả file nhật ký nếu không có đặc quyền ghi bất biến từ hệ điều hành.
- Bất biến Core-Lock: Chứng minh cây file khớp với manifest đã đăng ký, nhưng không chứng minh được người vận hành đã tự mình đọc lại toàn bộ diff. Bất kỳ ai có quyền ghi vào
core/đều có thể tạo lại lock. Giám Thị thực hiện kiểm tra định kỳ độc lập nhưng có cửa sổ trễ tối đa 6 giờ. - Phạm vi thực thi luật: Phần lớn file trong
core/rulesmô tả hướng dẫn để agent tự nguyện tuân theo; chỉ những quy tắc có hook hệ thống gắn kết mới được ngăn chặn một cách tất định. Cơ chế ký số mã nguồn chính thức chưa được triển khai. - Độ phủ của Pattern Guard: Bộ lọc lệnh dựa trên phân tích chuỗi cú pháp, không phải hypervisor sandbox. Bản bash script dự phòng chưa đạt được độ tương đồng đầy đủ trong việc chặn pipe-to-shell so với Rust runtime.
- Chênh lệch can thiệp giữa các Host: Cursor không can thiệp vào các cuộc gọi MCP. Antigravity chặn lệnh shell nhưng có thể bị bỏ qua nếu người dùng chạy với cờ
--dangerously-skip-permissions. - Ký chứng thực nền tảng (Notarization): Bản phát hành macOS hiện dựa trên chữ ký ad-hoc của nhà phát triển, do đó Gatekeeper sẽ hiện cảnh báo bảo mật trong lần khởi chạy đầu tiên trước khi hoàn tất đăng ký tài khoản Apple Developer.
9. Quỹ đạo Kỹ thuật & Mốc thời gian
Kho lưu trữ bắt đầu từ một commit trống vào ngày 17/05/2026. Đến ngày 26/10/2026, lịch sử Git đã ghi nhận 2.488 commits, 426 pull requests đã gộp, 41 bản phát hành phần mềm và 72 thẻ phiên bản (tags). Hình 6 cho thấy nhịp commit theo từng tháng; tháng 6 đạt đỉnh với 740 commits trong đợt nhập hàng loạt skill và xây dựng website.
/freeze; adapter Codex; nhà cung cấp Kimi; vá lỗi chuỗi thực thi lệnh từ xa trong script.10. Lời tác giả sáng lập
"Yana AI không được sinh ra bên trong một khuôn viên tập đoàn. Dự án không có vốn đầu tư mạo hiểm, không có đội ngũ kỹ sư hùng hậu, và cũng không có phòng thí nghiệm của trường viện. Nó bắt đầu trên một chiếc máy tính cá nhân, bởi một học sinh 17 tuổi với niềm tin vững chắc rằng các coding agent tự chủ không được phép nắm giữ chủ quyền vô kiểm soát trên hệ thống máy chủ.
Những cạm bẫy nguy hiểm nhất chưa bao giờ là các lỗi code đơn lẻ, mà là các giả định sai lầm về mặt khái niệm. Sau mỗi lần thất bại, Yana lại được tái thiết kế có chủ đích: dễ kiểm chứng hơn, dễ quan sát hơn, và đáng tin cậy hơn một cách căn bản.
Yana AI tồn tại vì con người phải mãi mãi giữ quyền đưa ra quyết định cuối cùng."
Tác giả bắt đầu dự án ở tuổi 17, đảm nhận vai trò kỹ sư duy nhất trong sáu tháng đầu tiên mà không có bất kỳ nguồn tài trợ tổ chức nào. Các công cụ AI đã hỗ trợ tăng tốc viết mã, sinh test case và rà soát, nhưng toàn bộ thiết kế kiến trúc, các đợt viết lại hệ thống và trách nhiệm giải trình cuối cùng thuộc về người sáng lập.
Vào cuối tháng 10/2026, Nguyễn Nam Long đã tham gia dự án với tư cách người đóng góp mới. Các mốc kỹ thuật và kết quả nghiên cứu trong báo cáo này đại diện cho chặng đường phát triển đã hoàn tất trước khi anh gia nhập.
11. Tài liệu tham khảo
- OWASP Foundation. Top 10 for Large Language Model Applications, owasp.org.
- Google. Trillian: A Transparent, Highly Scalable and Cryptographically Verifiable Data Store, github.com/google/trillian.
- Anthropic. Model Context Protocol Specification, modelcontextprotocol.io.
- Microsoft. Visual Studio Code, Open Source (Code-OSS), github.com/microsoft/vscode.
- Yana AI Repository Specifications (
VISION.mdngày 07/06/2026;PHILOSOPHY.md;JOURNEY.md;HISTORY.md;BENCHMARK.md;CURRENT-MILESTONE.md;docs/reference/known-limitations.md), github.com/yanacuti1121/Yana-AI.