Minds
Tài liệu hướng dẫn

Bắt đầu

Minds CLI

Cách nhanh nhất để nhận giá trị từ Builder Tools là một agent lập trình có quyền truy cập shell. Cài đặt một lần, thiết lập khóa API của bạn, sau đó yêu cầu nó chạy các lệnh minds cho bạn.

Minds CLI là giao diện terminal ưu tiên JSON cho API của Builder . Mọi lệnh đều in một đối tượng trên stdout; mọi lệnh con đều cung cấp các ví dụ sao chép-dán trong --help. Điều đó là có chủ ý: Cursor, Claude Code, Codex hoặc bất kỳ agent nào có terminal đều có thể khám phá các lệnh, chạy chúng, chuyển qua jq và báo cáo lại bằng ngôn ngữ tự nhiên trong khi bạn vẫn ở trong trình chỉnh sửa của mình.Cài đặt một lần, thiết lập MINDS_BUILDER_API_KEY, sau đó yêu cầu agent của bạn, ví dụ:
  • "Liệt kê các Mind của tôi và hiển thị chi tiết đầy đủ cho Mind đầu tiên"
  • "Mind của tôi đã dùng bao nhiêu Cognition trong tuần qua?"
  • "Công cụ nào tiêu tốn nhiều Cognition nhất hôm qua?"
  • "Tìm các ứng dụng Notion trên Bazaar và cho xem mỗi ứng dụng cung cấp những công cụ gì"
  • "Thêm colleague@company.com vào Circle của Mind tôi"
Đằng sau những lời nhắc đó, agent chạy minds list, minds mind show, minds usage show --interval 1w, minds usage by-tool --interval day, minds bazaar apps list --search "notion", minds circle add, v.v. Bạn không cần phải ghi nhớ các cờ, minds <command> --help là nguồn thông tin chuẩn mà agent của bạn có thể đọc. Phân tích chẩn đoán và gợi ý cắt ngắn sẽ đi đến stderr; stdout vẫn là JSON sạch cho các script và CI.Hoàn tất Thiết lập tài khoản trước, sau đó cài đặt theo hướng dẫn bên dưới hoặc giao các lệnh tương tự cho agent của bạn.

Cài đặt

Yêu cầu Node 22+. 
npm install -g @animocabrands/minds-cli
Cập nhật sau bản phát hành mới: 
npm install -g @animocabrands/minds-cli@latest

Agent, sandbox và CI

Agent lập trình của bạn có thể sử dụng cùng các đường dẫn cài đặt bên dưới. Với sandbox, môi trường tạm thời hoặc CI, hãy bỏ qua bước cài đặt toàn cục: 
npx @animocabrands/minds-cli@latest doctor --pretty
npx @animocabrands/minds-cli@latest list
CLI đọc MINDS_BUILDER_API_KEY từ môi trường shell của bạn. Bất kỳ cách nào sau đây đều hoạt động: 
export MINDS_BUILDER_API_KEY=your_key_here
minds doctor --pretty
MINDS_BUILDER_API_KEY=your_key_here minds doctor --pretty
Tệp .env trong thư mục dự án của bạn cũng hoạt động, CLI sẽ tải tệp này khi biến chưa được thiết lập sẵn trong shell. Truyền --builder-api-key khi viết script: 
npx @animocabrands/minds-cli@latest chat list --builder-api-key "$MINDS_BUILDER_API_KEY"

GitHub Actions

Sử dụng CLI trong CI giống như khi dùng cục bộ: npx, Node 22+ và MINDS_BUILDER_API_KEY làm secret của repository. Đầu ra JSON trên stdout có thể pipe trực tiếp vào jq để tạo tóm tắt, gate kiểm tra, hoặc thông báo Slack. Ví dụ - mức sử dụng Cognition hàng tuần cho Mind đầu tiên của bạn (chạy vào Thứ Hai 09:00 UTC; cũng có thể kích hoạt thủ công): 
name: Weekly cognition usage
 
on:
  schedule:
    - cron: "0 9 * * 1"
  workflow_dispatch:
 
jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
 
      - name: Cognition usage and balance
        env:
          MINDS_BUILDER_API_KEY: ${{ secrets.MINDS_BUILDER_API_KEY }}
        run: |
          npx @animocabrands/minds-cli@latest doctor
          MIND_ID=$(npx @animocabrands/minds-cli@latest list | jq -r '.items[0].mindId')
          npx @animocabrands/minds-cli@latest usage show --mind "$MIND_ID" --interval 1w
          npx @animocabrands/minds-cli@latest cognition balance --mind "$MIND_ID" | jq '.balance.cognition'

Xác minh và khám phá

Tự chạy các lệnh này để kiểm tra nhanh hoặc yêu cầu agent của bạn chạy chúng sau khi cài đặt: 
minds doctor --pretty
minds --help
minds chat --help
minds usage by-tool --help
Mọi lệnh con đều bao gồm Các ví dụ có thể sao chép-dán trong đầu ra --help của nó. Đối với các lệnh gồm nhiều phần, mẫu chính tắc là minds <group> <subcmd> --help (ví dụ: minds usage by-tool --help). Các định dạng này cũng hoạt động: minds help usage by-tool và minds usage --help by-tool. Các tuyến được xác thực yêu cầu X-Api-Key với khóa API Builder của bạn. X-Access-Key không được dùng nữa, đừng sử dụng nó trong các yêu cầu HTTP. CLI sẽ đọc MINDS_BUILDER_API_KEY (hoặc --builder-api-key; cờ CLI đã ngừng hoạt động --access-key) và chỉ gửi X-Api-Key. Đầu ra tiêu chuẩn mặc định là một đối tượng JSON { ok: true, … }; thông tin chẩn đoán đi đến stderr. minds events là một ngoại lệ, nó in ra các dòng NDJSON. Nếu minds doctor báo lỗi thiếu khóa, hãy quay lại Thiết lập tài khoản để tạo khóa, sau đó thực hiện lệnh export MINDS_BUILDER_API_KEY=… (hoặc thêm nó vào tệp .env trong dự án của bạn).

Liệt kê các Mind của bạn

minds list gọi Builder API cho từng Mind trong tài khoản của bạn, hiển thị mindId, name, model, species và các trường liên quan khác. Bạn không cần phải sao chép ID thủ công từ bảng điều khiển. Sau khi minds doctor vượt qua: 
minds list --pretty
Chuyển sang jq khi viết script: 
minds list | jq '.items[] | {mindId, name}'

Chi tiết Mind

minds list trả về các trường tóm tắt. Để xem chi tiết đầy đủ: email, địa chỉ ví, chuỗi, chủng loại, isEnabled và nhiều thông tin khác, hãy sử dụng minds mind show. Đặt $MIND_ID thành UUID của Mind từ minds list (không phải name hiển thị): 
MIND_ID=$(minds list | jq -r '.items[0].mindId')
minds mind show --mind "$MIND_ID"
minds mind show --mind "$MIND_ID" | jq '.mind.walletAddress'
Hình dạng phản hồi: { ok: true, mind: { … } }.

Số dư và mức sử dụng Cognition

Minds tiêu tốn Cognition khi chúng suy luận, sử dụng công cụ và thực hiện các nhiệm vụ tự chủ, chứ không chỉ khi bạn nhắn tin cho chúng. Bạn có thể kiểm tra mức sử dụng Cognition và số dư Cognition còn lại của từng Mind; chỉ cần truyền mindId lấy từ lệnh minds list. 
MIND_ID=$(minds list | jq -r '.items[0].mindId')
 
minds usage show --mind "$MIND_ID"
minds usage show --mind "$MIND_ID" --interval 1w
minds usage by-tool --mind "$MIND_ID" --interval day
minds cognition balance --mind "$MIND_ID"
usage show báo cáo mức sử dụng Cognition theo thời gian. usage by-tool chia nhỏ mức sử dụng theo từng công cụ, kèm theo bản tóm tắt và dòng thời gian. Các khoảng thời gian được chấp nhận sẽ khác nhau tùy theo lệnh: usage show hỗ trợ 1m, 5m, 15m, 1h, 1d, 1w, 1M; trong khi usage by-tool chỉ chấp nhận hour, day, week, month. CLI sẽ xác thực khoảng thời gian trước khi gọi API, vì vậy nếu bạn nhập một giá trị không hợp lệ, hệ thống sẽ thoát với mã lỗi 2 và hiển thị các khoảng thời gian hợp lệ trong phần gợi ý. Cognition là nguồn năng lượng cho khả năng suy luận, sử dụng công cụ và làm việc tự chủ của Mind. Kiểm tra số dư Cognition còn lại bằng cognition balance: 
minds cognition balance --mind "$MIND_ID" | jq '.balance.cognition'

Kích hoạt và vô hiệu hóa Mind

Tạm dừng hoặc tiếp tục Mind nếu cần: 
minds mind disable --mind "$MIND_ID"
minds mind enable --mind "$MIND_ID"
Tắt Mind khi số dư Cognition của nó cạn kiệt: 
minds cognition balance --mind "$MIND_ID" | jq -e '.balance.cognition <= 0' && minds mind disable --mind "$MIND_ID"

Circles

Circle của Mind là nhóm những cộng tác viên con người có thể tương tác với nó. Liệt kê thành viên của một Mind, hoặc trên toàn bộ các Mind trong tài khoản của bạn: 
minds circle show --mind "$MIND_ID"
minds circle list | jq '.items[] | {mindId, memberCount: (.members | length)}'
Thêm hoặc xóa cộng tác viên bằng email. --email có thể lặp lại: 
minds circle add --mind "$MIND_ID" --email someone@company.com --email peer@company.com
minds circle remove --mind "$MIND_ID" --email someone@company.com
minds circle remove --mind "$MIND_ID" --email someone@company.com --dry-run
Circles chỉ chấp nhận email của cộng tác viên con người. Tư cách thành viên Circle từ Mind tới Mind không được hỗ trợ. circle add theo mặc định sẽ kích hoạt các thành viên mới; hãy sử dụng cờ --dry-run trên remove để xem trước những email nào sẽ bị xóa mà không thực sự chạy lệnh. Hình dạng phản hồi sẽ khác nhau tùy theo động từ: circle show trả về { ok: true, mindId, items: CircleMember[] }; add và remove trả về { ok: true, mindId, result: { items, summary } } với kết quả cho từng email. Việc gửi các email trùng lặp trên circle add có thể trả về action: "exists" hoặc "already_in_circle", CLI coi những kết quả này là thành công và chỉ cảnh báo trên stderr khi thay đổi không có hiệu lực thực tế.

Danh mục Bazaar

Bazaar là danh mục công khai về các kỹ năng và ứng dụng. Các lệnh của Bazaar không yêu cầu khóa Builder API, chúng hoạt động trong CI và sandbox mà không cần thiết lập MINDS_BUILDER_API_KEY. Cùng danh mục này có sẵn trong thư viện ứng dụng khách dưới dạng client.bazaar.*. Sử dụng Bazaar để khám phá ID (skillId, appId), sau đó trang bị các ID đó cho một Mind bằng minds mind skills|apps (xem bên dưới). Các mục danh sách có thể bao gồm equippedCount, cho biết số lượng Minds đã trang bị kỹ năng hoặc ứng dụng đó trên toàn nền tảng. Con số đó là mức độ phổ biến trên toàn nền tảng, không phải là liệu Mind của bạn có trang bị mục đó hay không, sử dụng minds mind skills list / minds mind apps list cho tập trang bị theo từng Mind. Tìm kiếm các kỹ năng và ứng dụng cùng nhau: 
minds bazaar search "workflow automation" --max 20
minds bazaar search "slack" --tier verified --provider composio --sort equipped
minds bazaar search không trả về các items ở cấp cao nhất. Bạn có thể mong đợi: 
{
  "ok": true,
  "query": "slack",
  "max": 20,
  "skills": { "totalCount": 0, "scanned": 0, "returned": 0, "truncated": false, "items": [] },
  "apps": { "totalCount": 0, "scanned": 0, "returned": 0, "truncated": false, "items": [] }
}
Để duyệt riêng từng kỹ năng hoặc ứng dụng, hãy sử dụng --search và --max khi bạn cần xem nhiều hơn phần danh mục đầu tiên: 
minds bazaar skills list --search "research" --max 10
minds bazaar skills list
minds bazaar skills show skill_abc123
 
minds bazaar apps list --search "notion" --tier verified --max 10
minds bazaar apps show app_xyz789 | jq '.item.tools'
Với --search, skills list và apps list sẽ trả về { ok: true, query, totalCount, scanned, returned, truncated, max, sortedBy?, items }. Việc duyệt mà không có --search sẽ trả về cấu trúc tương tự nhưng trừ đi query, max và sortedBy (chỉ xuất phần đầu tiên; truncated: true khi danh mục lớn hơn). Tên trường cho jq: kỹ năng sử dụng skillId và name; ứng dụng sử dụng appId và appName (không phải name). Công cụ trên một ứng dụng sử dụng toolSlug. Ví dụ - trích xuất ID từ tìm kiếm: 
minds bazaar search "game" --max 5 | jq '{
  skills: [.skills.items[] | {skillId, name}],
  apps: [.apps.items[] | {appId, appName}]
}'
--max mặc định là 50, giới hạn ở mức 200; --search tự động quét nội bộ lên đến 200. --sort là chức năng phía máy khách trên tập hợp đã quét: equipped sắp xếp theo equippedCount giảm dần (mức độ phổ biến của nền tảng), name theo thứ tự bảng chữ cái, newest theo createdAt. --provider trên các ứng dụng sẽ lọc phía máy khách trên tập hợp đã quét mà không có --search, nó chỉ lọc phần danh mục đầu tiên (stderr cảnh báo). Cảnh báo cắt bớt (truncation) sẽ đi đến stderr (warn:); JSON vẫn nằm trên stdout.

Trang bị kỹ năng và ứng dụng

Sau khi bạn có skillId hoặc appId từ Bazaar (hoặc nơi khác), bạn có thể liệt kê, trang bị hoặc tháo trang bị trên một Mind. Truyền --mind với UUID của Mind và --id (có thể lặp lại) với UUID của kỹ năng hoặc ứng dụng: 
MIND_ID=$(minds list | jq -r '.items[0].mindId')
SKILL_ID=$(minds bazaar skills list --search "research" --max 1 | jq -r '.items[0].skillId')
APP_ID=$(minds bazaar apps list --search "notion" --max 1 | jq -r '.items[0].appId')
 
minds mind skills list --mind "$MIND_ID"
minds mind skills equip --mind "$MIND_ID" --id "$SKILL_ID"
minds mind skills unequip --mind "$MIND_ID" --id "$SKILL_ID"
 
minds mind apps list --mind "$MIND_ID"
minds mind apps equip --mind "$MIND_ID" --id "$APP_ID"
minds mind apps unequip --mind "$MIND_ID" --id "$APP_ID"
Trang bị (equip) và tháo trang bị (unequip) nhận một hoặc nhiều giá trị --id và trả về { ok: true, mindId, result: { results: [...] } }. list trả về tập trang bị hiện tại cho Mind đó. Các kỹ năng được trang bị bao gồm source: mind cho kỹ năng từ danh mục / do Mind tạo, system cho kỹ năng nền tảng (ví dụ: Skill Architect).

Gửi tin nhắn và lịch sử

Với việc thiết lập tài khoản và duyệt danh mục đã được thực hiện, hãy liên kết một bí danh ổn định với một Mind và gửi tin nhắn. Sử dụng mindId từ lệnh minds list khi bạn tạo cuộc hội thoại. Bạn có thể truyền thẳng Mind đầu tiên vào chat create: 
minds chat create --mind "$(minds list | jq -r '.items[0].mindId')" --alias main
minds send main "Hello" --wait --timeout 180000
Hoặc chuyển một mindId cụ thể một cách rõ ràng: 
minds chat create --mind {mind-id} --alias main
chat create là idempotent, việc chạy lại với cùng một bí danh sẽ trả về cuộc hội thoại hiện tại thay vì bị lỗi. Thời gian chờ --wait mặc định là 120000 ms; 180000 cung cấp nhiều khoảng trống hơn. Nếu --wait hết thời gian chờ, hãy chạy minds history main, câu trả lời vẫn có thể đã đến phía máy chủ. minds history trả về toàn bộ bản ghi hội thoại giữa người dùng và Mind. Các hàng sử dụng senderType (1 = con người, 0 = Mind). Lịch sử theo thứ tự cũ nhất trước; phân trang bằng --limit (1–200, mặc định 50) và --cursor (một fingerprint tin nhắn từ trang trước, loại trừ): 
minds history main
minds history main --limit 10
 
# Next page: pass the last fingerprint from the previous response
minds history main --limit 10 --cursor "$(minds history main --limit 10 | jq -r '.items[-1].fingerprint')"

Tệp đính kèm

Truyền một mảng JSON của các đối tượng tệp đính kèm với --attachments. Ưu tiên URL HTTPS công khai cho hình ảnh và tệp, Mind sẽ tìm nạp URL đó ở phía máy chủ. Hình ảnh: lưu thành attach-url-png.json: 
[
  {
    "url": "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png",
    "fileName": "transparency-demo.png",
    "mimeType": "image/png"
  }
]
minds send main "Describe this image in one sentence." --attachments ./attach-url-png.json --wait --timeout 180000
PDF: lưu thành attach-url-pdf.json: 
[
  {
    "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
    "fileName": "dummy.pdf",
    "mimeType": "application/pdf",
    "extension": "pdf"
  }
]
minds send main "Summarize this PDF in one sentence." --attachments ./attach-url-pdf.json --wait --timeout 180000
Các agent lập trình với các tệp cục bộ có thể mã hóa base64 vào trường content thay vì url - hãy xem tham chiếu API để biết cấu trúc outbound đầy đủ. Các phản hồi của Mind có thể bao gồm các Artifact inbound trên các hàng minds history: 
{
  "artifactId": "7388b65d-144a-49ff-a4dc-cb7c23ded982",
  "slug": "whale_watchtower_skill_artifact_1_0_5",
  "logicalType": "document",
  "mimeType": "application/pdf",
  "extension": "pdf",
  "artifact": "JVBERi0xLjQK..."
}
Sử dụng artifact cho phần thân tệp base64 khi có mặt (bị cắt ngắn trong ví dụ này).

Tiếp theo

Khi các Mind của bạn đã được cấu hình và bạn sẵn sàng nhúng chúng vào ứng dụng của mình, hãy tiếp tục với Thư viện Ứng dụng khách Minds .
Trên trang này