Hướng dẫn đọc MuseAI-Skills: Phân tích kỹ năng Muse AI, quyền hạn và quy trình Agent

Dự án là gì

MuseAI-Skills là một bản chụp môi trường AI Agent cá nhân Muse / Hatch liên quan đến muse.ai. Kho lưu trữ chứa tài liệu sản phẩm, định nghĩa kỹ năng, danh sách quyền connector, các kịch bản đánh giá hành vi, script chạy Linux, cùng một phần chương trình và dependency đi kèm.

Giới hạn quan trọng: Đây không phải kho mã nguồn hoàn chỉnh và cũng không phải gói cài đặt có thể triển khai bằng một lần nhấp. Chương trình cốt lõi chủ yếu được cung cấp dưới dạng binary Linux x86-64 ELF, trong khi mã nguồn build, cấu hình host đầy đủ, rootfs và một số tài nguyên runtime không được bao gồm.

Vì vậy, kho này phù hợp nhất cho đọc tĩnh, nghiên cứu workflow Agent, phân tích mô hình quyền và tham khảo thiết kế chỉ dẫn, thay vì cài đặt trực tiếp dịch vụ Muse AI. Tài liệu trong kho sử dụng các tên Muse, Hatch và Jarvis, nhưng bản lưu trữ tự thân không đại diện cho việc phát hành, chứng thực hoặc xác nhận nguồn gốc chính thức.

Bạn có thể học được gì từ kho lưu trữ

Cấu trúc đầy đủ của workflow kỹ năng

Kho chứa 72 đường dẫn SKILL.md, trong đó có 68 tệp kỹ năng độc lập và 4 bí danh symbolic link. Các kỹ năng bao phủ workflow Agent, sản phẩm tài liệu, đặt chỗ du lịch, công cụ văn phòng, nền tảng xã hội, dữ liệu sức khỏe, tạo media, điều khiển thiết bị và thao tác với sản phẩm Muse.

Các tài liệu kỹ năng thường giúp bạn nghiên cứu những câu hỏi sau:

• Yêu cầu nào của người dùng sẽ kích hoạt kỹ năng.
• Nhiệm vụ do coordinator, worker hay connector bên ngoài xử lý.
• Cần những kết nối tài khoản, OAuth scope hoặc quyền người dùng nào trước khi thực thi.
• Cách hạ cấp khi công cụ thất bại, đầu vào chưa đầy đủ hoặc quyền không đủ.
• Cách định nghĩa định dạng đầu ra và xác minh sản phẩm bàn giao cuối cùng.

Tài liệu về quyền và đánh giá

Kho cũng có 40 đường dẫn manifest và 12 tệp eval YAML. manifest.yaml có thể dùng để tìm hiểu metadata của connector, giá trị quyền mặc định, yêu cầu scope và ánh xạ lệnh; eval/scenarios.yaml ghi lại các kịch bản đánh giá hành vi, mục tiêu người dùng và hành vi kỳ vọng.

Lưu ý: Có manifest không có nghĩa tài khoản đã được kết nối; có kịch bản đánh giá cũng không có nghĩa việc đánh giá đã được chạy hoặc đã đạt.

Dấu vết tĩnh của môi trường runtime

Các script trong opt/hatch/runtime-cell/ cho thấy một phần vòng đời môi trường runtime, bao gồm phân giải đường dẫn rootfs, chuẩn bị trước khi khởi động, kiểm tra kernel module, khởi động container systemd-nspawn và lắp ghép overlay của kỹ năng cùng binary. Tuy nhiên, unit đầy đủ trên host, cấu hình nspawn và rootfs thực tế không nằm trong kho.

Tổng quan cấu trúc thư mục

• README.md: Phần giới thiệu bằng tiếng Trung, thư mục kỹ năng và giải thích các giới hạn.
• README.en.md: Phần giới thiệu bằng tiếng Anh.
• PROJECT_ANALYSIS.md: Nhận định kiến trúc, thành phần còn thiếu, rủi ro và chỉ mục bằng chứng.
• SHA256SUMS: Danh sách kiểm tra nội dung của các tệp thông thường, nhưng không phải chữ ký nguồn.
• home/hatch/docs/: Tài liệu về sản phẩm, connector, quyền riêng tư, lập lịch, tệp, thiết bị và media.
• home/hatch/config/: Cấu hình liên quan đến trạng thái Agent và kỹ năng.
• opt/hatch/skills/: Entry point kỹ năng, manifest quyền, kịch bản đánh giá và tài liệu tham khảo.
• opt/hatch/runtime-cell/: Script vòng đời môi trường runtime và template cấu hình.
• opt/hatch/bin/: Các chương trình liên quan đến Hatch.
• opt/hatch-image/: Công cụ phía image, npm, Bun và các thành phần đi kèm khác.

Thư mục gốc của kho chỉ là thư mục gốc của bản lưu trữ, không phải thư mục gốc Linux đang chạy. home/hatch/ trong bản lưu trữ tương ứng với /home/hatch trong môi trường ban đầu, còn /run, /var/lib và /etc trong tài liệu thường trỏ đến các filesystem runtime bị thiếu.

Lấy và chuẩn bị kho lưu trữ

Phương án một: Chỉ nghiên cứu kỹ năng và tài liệu

Nếu mục tiêu là phân tích Markdown, YAML và Shell script, bạn có thể bỏ qua các binary Git LFS có dung lượng lớn. Đây cũng là cách đọc được khuyến nghị nhất.

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/win4r/MuseAI-Skills.git
cd MuseAI-Skills

Cách này không cần thực thi chương trình đi kèm. Sau khi vào kho, hãy ưu tiên mở PROJECT_ANALYSIS.md và opt/hatch/skills/.

Phương án hai: Xem các đối tượng lưu trữ đầy đủ

Chỉ nên cài Git LFS và lấy các đối tượng liên quan khi thực sự cần kiểm tra chương trình ELF hoặc các tệp lớn khác trong LFS. Việc tải binary không bổ sung mã nguồn, rootfs, credential hoặc cấu hình host còn thiếu, cũng không biến kho thành một hệ thống có thể triển khai.

git clone https://github.com/win4r/MuseAI-Skills.git
cd MuseAI-Skills
git lfs pull

Đối với các binary chưa được xác thực độc lập về nguồn gốc, hãy ưu tiên kiểm tra tĩnh ngoại tuyến và không chạy trực tiếp trên máy production hoặc trong môi trường chứa credential nhạy cảm.

Kiểm tra các tệp thông thường

Sau khi lấy đầy đủ các tệp liên quan, bạn có thể dùng SHA256SUMS do kho cung cấp để kiểm tra tính toàn vẹn nội dung:

sha256sum -c SHA256SUMS

Danh sách kiểm tra không bao phủ chính tệp danh sách và symbolic link, đồng thời không phải chữ ký mật mã về danh tính hoặc tính xác thực của nguồn phát hành. Nó chỉ giúp xác định liệu các tệp thông thường cục bộ có khớp với digest được ghi trong danh sách hay không.

Cách dùng cơ bản: Xây dựng quy trình đọc kỹ năng

Bước một: Chọn một entry point kỹ năng

Khi đọc lần đầu, bạn có thể bắt đầu với các kỹ năng sau:

• wide-research: Nghiên cứu coordinator, worker, contract đầu ra thống nhất và phạm vi xử lý lỗi.
• skill-creator: Mô tả trigger kỹ năng, phân chia thư mục và tải tài liệu tham khảo theo nhu cầu.
• artifacts/testing: Phân biệt “tạo thành công” và “sản phẩm bàn giao có thể sử dụng”.
• goals: Phân biệt thiết lập mục tiêu lần đầu và theo dõi về sau.
• forget: Xử lý bản sao, trạng thái phát sinh và dữ liệu có thể được ghi ngược lại.
• travel-planning: Tách nghiên cứu hành trình, truy vấn thời gian thực và thực hiện giao dịch.
• gmail: Phân tích connector bằng cách kết hợp nội dung kỹ năng, quyền cấp phương thức và kịch bản đánh giá.

Ví dụ, xem entry point của kỹ năng Gmail:

sed -n '1,240p' opt/hatch/skills/gmail/SKILL.md

Bước hai: Trích xuất điều kiện kích hoạt và giới hạn

Khi đọc SKILL.md, đừng chỉ ghi lại “nó có thể làm gì”, mà hãy lần lượt trả lời:

1. Yêu cầu nào sẽ kích hoạt kỹ năng này?
2. Yêu cầu tương tự nào không nên kích hoạt?
3. Phân biệt thao tác chỉ đọc và thao tác ghi như thế nào?
4. Các thao tác có ảnh hưởng lớn như gửi, xóa, mua hoặc đặt chỗ có cần xác nhận không?
5. Cần xử lý thế nào khi thiếu quyền, mục tiêu mơ hồ hoặc công cụ thất bại?
6. Kết quả cuối cùng cần trả về những trường hoặc bằng chứng nào?

Hãy sắp xếp các nội dung này thành sáu phần “trigger, đầu vào, cấp quyền, thực thi, thất bại, nghiệm thu” để thuận tiện chuyển sang thiết kế Agent của riêng bạn.

Bước ba: Đối chiếu manifest quyền

Đối với các kỹ năng connector, hãy tiếp tục đọc manifest.yaml trong cùng thư mục:

sed -n '1,260p' opt/hatch/skills/gmail/manifest.yaml

Hãy tập trung so sánh các thao tác mà nội dung kỹ năng tuyên bố với quyền phương thức, giá trị mặc định theo nhóm, scope và ánh xạ lệnh được khai báo trong manifest. Thiết lập cấp phương thức có thể ghi đè giá trị mặc định theo nhóm, vì vậy không thể chỉ xem phần mô tả quyền ở cấp cao nhất.

Việc sao chép một SKILL.md sang môi trường Agent khác không tự động cấp khả năng truy cập Gmail, Google Drive, Notion hoặc các dịch vụ khác. Việc thực thi thực tế vẫn phụ thuộc vào CLI hoặc MCP tương ứng, kết nối tài khoản, OAuth scope và quyền runtime.

Bước bốn: Đọc các kịch bản đánh giá

Nếu kỹ năng có eval/scenarios.yaml, bạn có thể tiếp tục xem cách nó chuyển quy tắc thành hành vi có thể kiểm thử:

sed -n '1,260p' opt/hatch/skills/gmail/eval/scenarios.yaml

Các kịch bản đánh giá phù hợp để kiểm tra những hành vi sau:

• Agent có chọn đúng kỹ năng hay không.
• Có phân biệt các mức rủi ro khác nhau như đọc, nháp, gửi và xóa hay không.
• Khi thiếu thông tin, có hỏi lại trước thay vì đoán người nhận hoặc mục tiêu thao tác hay không.
• Có yêu cầu cấp quyền hoặc xác nhận khi cần hay không.
• Sau khi thất bại, có trung thực báo cáo các mục chưa hoàn thành hay không.

Đừng xem tệp kịch bản như báo cáo đã vượt qua kiểm thử. Nếu muốn đánh giá các vấn đề trong quá khứ, bạn cũng có thể kết hợp các bản ghi phát hiện tương tự opt/hatch/skills/flightaware/eval/findings.md, đồng thời chú ý đến phiên bản và môi trường kiểm thử.

Bước năm: Kiểm tra tài liệu tham khảo đi kèm

Một số kỹ năng tách các quy tắc chi tiết sang references/, guide/, creation/ hoặc guides/. Cấu trúc này thể hiện một nguyên tắc thiết kế quan trọng: giữ tệp kỹ năng chính ngắn gọn và chỉ tải tài liệu tham khảo cụ thể hơn khi nhiệm vụ yêu cầu.

Ví dụ, có thể bắt đầu tìm hiểu phương pháp viết kỹ năng từ tệp sau:

sed -n '1,260p' opt/hatch/skills/skill-creator/references/authoring_guide.md

Ví dụ thực tế: Phân tích kỹ năng Gmail

Bạn có thể dùng mẫu sau để ghi lại thiết kế của kỹ năng Gmail mà không thực sự kết nối hoặc thao tác với hộp thư:

Entry point kỹ năng: opt/hatch/skills/gmail/SKILL.md
Định nghĩa quyền: opt/hatch/skills/gmail/manifest.yaml
Kịch bản đánh giá: opt/hatch/skills/gmail/eval/scenarios.yaml

Các khía cạnh phân tích:
1. Điều kiện kích hoạt để tìm kiếm và đọc email
2. Giới hạn thao tác đối với nháp, gửi và trả lời
3. Quy trình nhãn và hủy đăng ký
4. Quyền cấp phương thức và OAuth scope
5. Cách xử lý khi người nhận, chuỗi email hoặc ý định thao tác không rõ ràng
6. Cách báo cáo sau khi công cụ thất bại
7. Kết quả và thông tin xác minh mà người dùng cuối cần nhận

Sau khi hoàn tất, bạn có thể chuyển kết quả thành đặc tả Agent của riêng mình:

• Quy tắc kích hoạt: Xác định rõ các mẫu ngôn ngữ nào đi vào kỹ năng email.
• Ưu tiên chỉ đọc: Tách tìm kiếm và đọc khỏi các thao tác thay đổi như gửi và xóa.
• Ngưỡng cấp quyền: Định nghĩa lại quy tắc xác nhận và OAuth dựa trên môi trường runtime mục tiêu.
• Contract đầu ra: Quy định nội dung trả về tương ứng khi thành công, thành công một phần và thất bại.
• Kịch bản nghiệm thu: Bổ sung kiểm thử cho yêu cầu thông thường, yêu cầu mơ hồ, thiếu quyền và lỗi connector.

Đọc kiến trúc sản phẩm và hệ thống

Nắm nhanh contract sản phẩm

Khuyến nghị đọc lần lượt:

1. home/hatch/docs/muse.md: Tổng quan sản phẩm.
2. home/hatch/docs/goals.md: Mục tiêu, tiến độ và ranh giới của các tác vụ chạy nền.
3. home/hatch/docs/scheduling-and-watching.md: Thăm dò, lập lịch, lịch sử chạy và thông báo.
4. home/hatch/docs/self_improvement.md: Bộ nhớ nền, nghiên cứu, đánh giá và theo dõi bằng chứng.
5. home/hatch/docs/connectors.md: Trạng thái kết nối, OAuth, quyền phương thức và xử lý lỗi.
6. home/hatch/docs/privacy-and-credentials.md: Quy tắc tham chiếu thông tin xác thực, Vault, xuất và xóa.

Các tệp này mô tả hợp đồng sản phẩm trong bản chụp. Mô tả về khả năng dành riêng cho tài khoản và tính khả dụng trong lịch sử không nên được xem trực tiếp là sự thật áp dụng cho mọi tài khoản Muse hiện tại.

Chuỗi khởi động runtime nghiên cứu

Nếu quan tâm đến môi trường cô lập Linux, có thể thiết lập quan hệ gọi giữa các tập lệnh sau:

opt/hatch/runtime-cell/pre-start.sh
opt/hatch/runtime-cell/ensure-rootfs.sh
opt/hatch/runtime-cell/resolve-rootfs-path.sh
opt/hatch/runtime-cell/require-modules.sh
opt/hatch/runtime-cell/launch-daemon.sh
opt/hatch/runtime-cell/post-start.sh

/var/lib/hatch-runtime/rootfs do resolve-rootfs-path.sh trả về là đường dẫn trong môi trường chạy ban đầu, không phải thư mục có sẵn trong kho lưu trữ. launch-daemon.sh sẽ khởi động container systemd-nspawn và lắp ghép overlay; không thể tách riêng nó khỏi cấu hình máy chủ và rootfs còn thiếu để tạo thành một hướng dẫn khởi động hoàn chỉnh.

Kỹ thuật phân tích nâng cao

Phân biệt skill, bí danh và thư mục tài nguyên

Kho lưu trữ có 4 bí danh liên kết tượng trưng: facebook trỏ đến facebook-cli, meta-threads trỏ đến threads, podcast trỏ đến generate_podcast, và voice-calls trỏ đến voice-selector.

Kiểm tra đích thực tế của các liên kết giúp tránh thống kê trùng lặp:

find opt/hatch/skills -type l -name SKILL.md -print -exec readlink {} \;

Đặc biệt, không thể suy ra từ tên voice-calls rằng nó có khả năng gọi điện thay mặt người dùng bằng Agent; thực tế, mục nhập này trỏ đến một thư mục giọng nói tĩnh. spaces chứa tài liệu runtime và mẫu, nhưng không có SKILL.md ở cấp cao nhất, vì vậy không nên tính thêm đây là một skill.

Đồng thời xác minh khai báo, quyền hạn và phụ thuộc có thể thực thi

Khi phân tích một skill, có thể áp dụng phương pháp đối chiếu ba lớp:

1. Lớp hành vi: Kiểm tra các trigger, phạm vi và đầu ra được khai báo trong SKILL.md.
2. Lớp quyền hạn: Kiểm tra các phương thức, scope và quyền mặc định trong manifest.
3. Lớp thực thi: Xác nhận CLI, MCP, chương trình hỗ trợ, kết nối tài khoản và tài nguyên runtime cần thiết có tồn tại hay không.

Kho lưu trữ nêu rõ rằng một số phụ thuộc quan trọng bị thiếu, bao gồm tập lệnh xác minh Artifacts, bộ khung tạo connector của skill-creator, chương trình thực thi mm của Magic Moment, cùng một phần SDK và tài nguyên xây dựng cần cho Spaces. Vì vậy, “đọc được tài liệu” không đồng nghĩa với “chuỗi thực thi đã hoàn chỉnh”.

Tách biệt việc tạo sản phẩm và nghiệm thu sản phẩm

artifacts/testing đáng được nghiên cứu như một mẫu Agent tổng quát. Mẫu này nhấn mạnh rằng sau khi tạo tệp, vẫn phải kiểm tra theo loại sản phẩm, kết xuất lại, nghiệm thu trực quan và quét các placeholder. Khi chuyển sang hệ thống của riêng mình, có thể chia quy trình thành:

1. Tạo tài liệu, bảng tính, PDF hoặc bản trình bày.
2. Mở lại hoặc kết xuất kết quả đã tạo.
3. Kiểm tra cấu trúc, bố cục, công thức, liên kết và tài nguyên bị thiếu.
4. Tìm các placeholder chưa được thay thế và văn bản tạm thời.
5. Chỉ đánh dấu tệp là có thể bàn giao sau khi nghiệm thu đạt yêu cầu.

Nghiên cứu cộng tác đa Agent

wide-research thể hiện các ràng buộc then chốt trong nghiên cứu song song với nhiều đầu vào: giới hạn trách nhiệm của điều phối viên và worker, thống nhất các trường đầu ra, báo cáo độ bao phủ và lưu giữ các mục thất bại. Khi chuyển đổi, nên thay thế tên công cụ và đường dẫn workspace theo framework điều phối của mình, đồng thời giữ nguyên hợp đồng đầu ra thống nhất và khả năng hiển thị lỗi.

Kiểm tra mô tả cơ sở dữ liệu thay vì tìm cơ sở dữ liệu

opt/hatch/skills/muse_db/references/schema.md mô tả các quy tắc SQL bị giới hạn, identifier và mối quan hệ trong nhiều schema, có thể dùng để tìm hiểu mô hình dữ liệu và cách theo dõi giữa các bảng. Đây không phải cơ sở dữ liệu thực tế hay mã nguồn migration, vì vậy không thể dựa vào đó để khôi phục toàn bộ dịch vụ.

Giữ lại nguồn, giấy phép và ranh giới bằng chứng

Khi chuyển workflow sang dự án khác, cần giữ thông tin ghi nhận nguồn và kiểm tra giấy phép áp dụng. Nên phân biệt trong hồ sơ phân tích nội bộ:

• Các sự thật được nêu trực tiếp trong tệp của kho lưu trữ.
• Các suy luận kỹ thuật dựa trên thư mục, tập lệnh hoặc manifest.
• Các tuyên bố về sản phẩm chưa được xác minh.
• Các hành vi không thể xác nhận do thiếu môi trường chạy.

“Có thể thấy trong bản lưu trữ” không đồng nghĩa với “đã được nguồn chính thức xác thực”, “có thể chạy độc lập” hay “có thể tự do cấp phép lại”.

Lộ trình học tập đề xuất

1. Khi clone kho lưu trữ, bỏ qua LFS để tránh tải xuống các tệp nhị phân không cần thiết.
2. Đọc PROJECT_ANALYSIS.md để hiểu các đánh giá về kiến trúc và những hạng mục còn thiếu.
3. Chọn skill-creator hoặc wide-research để học cấu trúc workflow.
4. Chọn gmail, phân tích kết hợp nội dung skill, manifest và eval.
5. Đọc artifacts/testing để hình thành tư duy nghiệm thu sản phẩm bàn giao.
6. Đọc tài liệu sản phẩm để phân biệt quy tắc skill với hợp đồng sản phẩm.
7. Cuối cùng, kiểm tra các tập lệnh runtime-cell để hiểu manh mối runtime và các phụ thuộc còn thiếu.

Kết luận

Giá trị chính của MuseAI-Skills không nằm ở việc triển khai trực tiếp, mà ở chỗ nó cho thấy một Agent AI cá nhân tổ chức trigger của skill, phân luồng tác vụ, quyền connector, xử lý lỗi và nghiệm thu kết quả như thế nào. Khi đọc SKILL.md, manifest.yaml, các kịch bản đánh giá và phụ thuộc runtime cùng nhau, bạn có thể rút ra các mẫu thiết kế phù hợp cho hệ thống Agent của mình, đồng thời tránh nhầm bản chụp với mã nguồn hoàn chỉnh hoặc sản phẩm có thể thực thi.