Cách sử dụng PolyDrobe.
Thiết lập một không gian làm việc, mô hình hóa tài sản và biến thể, mời nhóm vào và xử lý những lỗi hay gặp nhất.
Vận hành trong bốn bước
Dự án, phân loại, tài sản, nhóm. Theo thứ tự đó.
Tạo dự án
Tạo dự án đầu tiên và đặt slug dự án rõ ràng.
Cấu hình phân loại
Thiết lập danh mục, độ hiếm, thẻ, tiền tệ, trạng thái và bản phát hành.
Thêm tài sản và biến thể
Thêm tài sản, sau đó tạo biến thể với hình ảnh, giá và metadata tùy chọn.
Mời nhóm của bạn
Mời thành viên và gán vai trò Chủ sở hữu, Biên tập viên hoặc Người xem phù hợp.
Tất cả những gì bạn có thể làm
Mở một quy trình để xem chi tiết.
Thiết lập dự ánXây cấu trúc trước, thêm nội dung sau.
- Điền thông tin dự án và biểu tượng.
- Định nghĩa taxonomy tái sử dụng trong Cài đặt dự án.
Quản lý tài sản và biến thểTài sản đại diện vật phẩm gốc, biến thể đại diện từng phiên bản.
- Thêm metadata cho tài sản và gán danh mục/độ hiếm.
- Đính kèm texture, hình ảnh và giá cho biến thể.
Rà soát và tìm kiếmGiữ catalog dễ đọc và dễ bảo trì.
- Dùng bộ lọc, trạng thái và thẻ để tìm phần việc đang chờ bạn.
- Kiểm tra thay đổi trong nhật ký hoạt động.
Nhập và xuấtTrao đổi dữ liệu an toàn với pipeline.
- Xuất dữ liệu dự án sang JSON hoặc Excel, hoặc tích Bao gồm tệp media để nhận một gói ZIP kèm hình ảnh, texture và mesh.
- Nhập tệp JSON, Excel hoặc gói ZIP. Mọi lần nhập đều chạy xem trước, nên bạn soát được thay đổi và lỗi ở từng dòng trước khi có bất cứ thứ gì được ghi.
Nhập từ Google SheetsNhập tài sản, biến thể và cài đặt dự án từ một Google Spreadsheet gốc.
- Tạo một Google Spreadsheet gốc (không phải tệp .xlsx tải lên) với mỗi loại thực thể một trang tính: Currencies, Rarities, Releases, Tags, Categories, Assets, Variants.
- Đặt đúng tên cột ở hàng đầu tiên của mỗi trang tính (phân biệt chữ hoa chữ thường). Ví dụ, trang tính Variants cần: slug, name, asset_slug, rarity, release, currency, price, description, tags.
- Các thực thể được nhập theo thứ tự phụ thuộc: Currencies, Rarities, Releases, Tags, Categories, Assets và cuối cùng là Variants. Mọi thứ mà một dòng tham chiếu đến đều phải có sẵn trong dự án hoặc xuất hiện sớm hơn trong cùng lần chạy.
- Trong dự án của bạn, mở trang Trao đổi dữ liệu (Nhập / Xuất trong menu dự án), chọn Google Sheet làm nguồn nhập và kết nối tài khoản Google. PolyDrobe chỉ xin phạm vi drive.file của Google, nên nó chỉ đọc được những tệp bạn giao cho nó.
- Trong phần Tạo hồ sơ, đặt nhãn cho hồ sơ, bấm Duyệt để chọn bảng tính của bạn trong Google Picker, chỉnh lại tên các trang tính nếu tab của bạn đặt tên khác, rồi bấm Lưu hồ sơ.
- Hãy chạy Xem trước trên hồ sơ đã lưu trước tiên. Đó là một lần chạy thử, báo lỗi kiểm tra dữ liệu mà không ghi gì cả; Nhập sẽ thực hiện đúng lần chạy đó nhưng ghi thật.
- Với thẻ trên trang tính Assets hoặc Variants, hãy dùng giá trị ngăn cách bằng dấu chấm phẩy: starter;seasonal=winter;limited-edition.
- Giá chấp nhận cả dấu chấm lẫn dấu phẩy làm dấu thập phân (9.99 hoặc 9,99). Độ hiếm khớp theo tên, tiền tệ theo mã và bản phát hành theo chuỗi phiên bản.
Hướng dẫn cho nhà phát triển
Kết nối công cụ, agent và pipeline của bạn với PolyDrobe.
Thiết lập REST APITích hợp với PolyDrobe qua REST API tiêu chuẩn. Có trên gói Pro.
1. Tạo token truy cập
Mở Cài đặt không gian làm việc > Token API và tạo một token truy cập cá nhân mới. Đặt cho nó một cái tên dễ nhận biết (ví dụ 'CI Pipeline' hoặc 'Local Script'), chọn phạm vi đọc và ghi, rồi chọn thời hạn. Sao chép token ngay khi nó hiện ra, vì token chỉ hiển thị một lần.
# Your token will look like this: pdtk_a8f3b2c1d4e5f6a7b8c9d0e1f2a3b4c5... # Keep it safe. You cannot retrieve it later. # If lost, revoke it and create a new one.
2. Xác thực yêu cầu
Gửi token dưới dạng Bearer token trong header Authorization ở mọi yêu cầu.
curl -H "Authorization: Bearer pdtk_abc123..." \
https://polydrobe.app/api/v1/projects/
3. Liệt kê dự án của bạn
Trả về mọi dự án mà bạn là thành viên. Phản hồi dùng định dạng envelope tiêu chuẩn với khóa data và meta.
GET /api/v1/projects/
# Response:
{
"data": [
{
"id": "...",
"name": "Cyber Skins",
"slug": "cyber-skins",
"asset_count": 42,
"my_role": "owner"
}
],
"meta": { "total": 1, "page": 1, "page_size": 25 }
}
4. Tạo một tài sản
Tạo một tài sản trong dự án. Cần vai trò Biên tập viên hoặc Chủ sở hữu. Slug được sinh tự động từ tên.
curl -X POST \
-H "Authorization: Bearer pdtk_abc123..." \
-H "Content-Type: application/json" \
-d '{"name": "Plasma Rifle", "description": "Sci-fi weapon", "category_slug": "weapons"}' \
https://polydrobe.app/api/v1/projects/cyber-skins/assets/
5. Tạo một biến thể
Thêm một biến thể cho tài sản kèm giá, độ hiếm và trạng thái. Mọi tham chiếu khóa ngoại đều dùng slug.
curl -X POST \
-H "Authorization: Bearer pdtk_abc123..." \
-H "Content-Type: application/json" \
-d '{"name": "Gold Edition", "rarity_slug": "legendary", "price": "29.99", "currency_code": "USD"}' \
https://polydrobe.app/api/v1/projects/cyber-skins/assets/plasma-rifle/variants/
6. Tìm kiếm tài sản
Tìm kiếm toàn văn trên tài sản và biến thể bằng công cụ tìm kiếm của PostgreSQL. Hỗ trợ cụm từ, OR và phủ định.
GET /api/v1/projects/cyber-skins/search/?q=gold+legendary&type=variant&limit=10
7. Thao tác hàng loạt
Cập nhật hoặc xóa nhiều biến thể cùng lúc. Cần tính năng Thao tác hàng loạt, có trên gói Pro.
curl -X POST \
-H "Authorization: Bearer pdtk_abc123..." \
-H "Content-Type: application/json" \
-d '{"slugs": ["v1", "v2", "v3"], "updates": {"status_slug": "released"}}' \
https://polydrobe.app/api/v1/projects/cyber-skins/bulk/variants/update/
Các endpoint có sẵn
REST API chạm tới mọi tài nguyên dự án mà PolyDrobe lưu, từ chính catalog cho tới media, chỉnh sửa hàng loạt, nhật ký hoạt động và webhook. Các nhóm bên dưới là toàn bộ tập tài nguyên đó. Mọi tài nguyên đều dùng URL dựa trên slug.
Projects: GET|POST /v1/projects/
GET|PATCH|DELETE /v1/projects/{slug}/
Assets: GET|POST /v1/projects/{slug}/assets/
GET|PATCH|DELETE /v1/projects/{slug}/assets/{slug}/
Variants: GET|POST /v1/projects/{slug}/assets/{slug}/variants/
GET|PATCH|DELETE .../assets/{slug}/variants/{slug}/
GET /v1/projects/{slug}/variants/ (flat list)
Media: GET .../variants/{slug}/images/
PATCH|DELETE .../variants/{slug}/images/{uuid}/
GET .../variants/{slug}/textures/
DELETE .../variants/{slug}/textures/{uuid}/
Bundles: GET|POST /v1/projects/{slug}/bundles/
GET|PUT|PATCH|DELETE /v1/projects/{slug}/bundles/{slug}/
GET|POST /v1/projects/{slug}/bundles/{slug}/items/
DELETE .../bundles/{slug}/items/{variant_slug}/
Collections: GET|POST /v1/projects/{slug}/collections/
GET|PUT|PATCH|DELETE .../collections/{slug}/
GET .../collections/{slug}/items/
POST .../collections/{slug}/members/
DELETE .../collections/{slug}/members/{variant_slug}/
POST .../collections/{slug}/duplicate/
Classification: GET|POST /v1/projects/{slug}/{categories|tags|rarities|releases|currencies|statuses}/
PATCH|DELETE /v1/projects/{slug}/{entity}/{slug}/
Favorites: GET /v1/projects/{slug}/favorites/
POST|PUT|DELETE /v1/projects/{slug}/favorites/{kind}/{uuid}/
Team: GET|POST /v1/projects/{slug}/members/
PATCH|DELETE /v1/projects/{slug}/members/{user_id}/
Bulk: POST /v1/projects/{slug}/bulk/variants/update/
POST /v1/projects/{slug}/bulk/variants/delete/
Search: GET /v1/projects/{slug}/search/?q=term&type=all
Activity: GET /v1/projects/{slug}/activity/
Export: GET /v1/projects/{slug}/export/?format=json
Webhooks: GET|POST /v1/projects/{slug}/webhooks/
PATCH|DELETE /v1/projects/{slug}/webhooks/{uuid}/
Thiết lập MCP ServerKết nối trợ lý AI (Claude, ChatGPT) với PolyDrobe qua Model Context Protocol. Có trên gói Pro.
1. Tạo token truy cập cá nhân
Mở Cài đặt không gian làm việc > Token API và tạo một token mới. Đặt tên theo ứng dụng AI của bạn (ví dụ 'Claude Desktop' hoặc 'Claude Code'). Chọn phạm vi đọc và ghi, rồi chọn thời hạn dài (1 năm hoặc không hết hạn). Sao chép token ngay khi nó hiện ra, vì token chỉ hiển thị một lần.
# Your token will look like this: pdtk_a8f3b2c1d4e5f6a7b8c9d0e1f2a3b4c5... # Use this token in the configuration steps below. # The same token works for both REST API and MCP server.
2. Kết nối Claude Desktop
Thêm MCP server của PolyDrobe vào cấu hình Claude Desktop. Mở claude_desktop_config.json và thêm mục này.
{
"mcpServers": {
"polydrobe": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://polydrobe.app/mcp"],
"env": {
"MCP_HEADERS": "Authorization: Bearer pdtk_abc123..."
}
}
}
}
3. Kết nối Claude Code
Thêm MCP server từ terminal bằng Claude Code CLI.
claude mcp add polydrobe \ --transport http \ --url https://polydrobe.app/mcp \ --header "Authorization: Bearer pdtk_abc123..."
4. Phát triển cục bộ (chế độ stdio)
Khi phát triển cục bộ, hãy chạy MCP server trực tiếp qua stdio, không cần HTTP. Cách này xác thực sẵn dưới danh nghĩa người dùng bạn chỉ định.
python manage.py mcp_stdio --user=your-username
# Claude Desktop config for local stdio:
{
"mcpServers": {
"polydrobe-local": {
"command": "python",
"args": ["manage.py", "mcp_stdio", "--user=your-username"],
"cwd": "/path/to/polydrobe"
}
}
}
5. Dùng thử
Sau khi kết nối, hãy hỏi trợ lý AI bằng ngôn ngữ tự nhiên về dữ liệu dự án của bạn.
# Example prompts for your AI assistant: "List all my projects" "Show me the assets in project 'cyber-skins'" "Create a new asset called 'Neon Jacket' in the 'outerwear' category" "Search for legendary variants with price above 20" "Set up categories: Headwear, Outerwear, Footwear, Accessories" "Tag all sword assets with 'melee' and 'weapon'" "Export the project data as JSON" "Give me a project overview with sample thumbnails"
Các công cụ MCP có sẵn
Mọi thao tác đọc, ghi, tìm kiếm và xuất dữ liệu trong PolyDrobe đều được mở ra dưới dạng một công cụ. Trợ lý AI phát hiện toàn bộ tập công cụ ngay khi kết nối, đã chia sẵn theo nhóm, bạn không phải cấu hình gì.
Projects: list_projects, get_project, create_project,
update_project, delete_project
Assets: list_assets, get_asset, create_asset,
update_asset, delete_asset
Variants: list_variants, create_variant,
update_variant, delete_variant
Bundles: list_bundles, get_bundle, create_bundle,
update_bundle, delete_bundle, list_bundle_items,
add_bundle_item, remove_bundle_item,
find_bundles_containing_variant
Collections: collections_list, collections_get,
collections_create, collections_update,
collections_delete, collections_add_member,
collections_remove_member, collections_duplicate
Classification: list_categories, create_category, update_category,
delete_category, list_tags, create_tag, delete_tag,
list_rarities, create_rarity, list_releases,
create_release, list_currencies, create_currency,
list_statuses, create_status
Tags: add_asset_tags, remove_asset_tags,
add_variant_tags, remove_variant_tags
Favorites: list_favorites, add_favorite,
remove_favorite, toggle_favorite
Team: list_members, update_member_role, remove_member
Search: search (full-text across assets & variants)
Activity: get_activity_log
Images: fetch_variant_thumbnail, fetch_variant_image,
fetch_variant_texture, set_variant_thumbnail
Bulk: bulk_create_variants, bulk_update_variants,
bulk_delete_variants
Data: export_project, import_project_data
OAuth 2.1 cho môi trường production (nâng cao)
Với pipeline CI/CD và tích hợp giữa các máy chủ, bạn có thể dùng luồng client credentials của OAuth 2.1 thay cho token cá nhân. Hãy liên hệ bộ phận hỗ trợ để thiết lập ứng dụng OAuth.
# Exchange client credentials for an access token: curl -X POST https://polydrobe.app/o/token/ \ -d "grant_type=client_credentials" \ -d "client_id=your-client-id" \ -d "client_secret=your-client-secret" \ -d "scope=read write" # For most use cases, personal access tokens from # Workspace Settings > API Tokens are simpler and sufficient.
Ai có thể làm gì
Ba vai trò, phân định theo những gì mỗi người cần thay đổi. Người xem vẫn miễn phí.
Chủ sở hữu
Quản lý cài đặt dự án, giới hạn gói và quyền truy cập team.
- Cài đặt dự án
- Thanh toán
- Quản lý nhóm
- Tạo hoặc chỉnh sửa tài sản
- Nhập và xuất
- Duyệt chỉ đọc
Biên tập viên
Tạo và cập nhật tài sản, biến thể và dữ liệu vận hành.
- Cài đặt dự án
- Thanh toán
- Quản lý nhóm
- Tạo hoặc chỉnh sửa tài sản
- Nhập và xuất
- Duyệt chỉ đọc
Người xem
Xem dữ liệu dự án cho review, QA và nhu cầu theo dõi.
- Cài đặt dự án
- Thanh toán
- Quản lý nhóm
- Tạo hoặc chỉnh sửa tài sản
- Nhập và xuất
- Duyệt chỉ đọc
Câu hỏi thường gặp
PolyDrobe là gì?
PolyDrobe quản lý những loại tài sản nào?
PolyDrobe có xem trước mô hình 3D không?
PolyDrobe khác Google Sheets thế nào khi theo dõi tài sản game?
PolyDrobe khác Notion hay Airtable ở chỗ nào?
PolyDrobe tương thích với những engine game nào?
Agent AI có làm việc được với PolyDrobe không?
REST API và MCP server khác nhau ở điểm nào?
Lấy token truy cập API bằng cách nào?
PolyDrobe có hỗ trợ cộng tác nhóm không?
Mỗi skin nên là tài sản hay biến thể?
Làm sao giữ naming nhất quán?
Có thể chia sẻ dữ liệu dự án ra ngoài không?
Gói Free bao gồm những gì?
Ghế Người xem có được tính vào thanh toán không?
PolyDrobe có phải sản phẩm SaaS không?
Tôi nhập dữ liệu tài sản sẵn có vào PolyDrobe được không?
Mẫu nhập Google Sheets cần những cột nào?
Vì sao bản nhập Google Sheets báo 'Không thể tải siêu dữ liệu của bảng tính'?
Mỗi dự án có phải kết nối Google riêng không?
Vấn đề thường gặp
Giải pháp nhanh cho các vấn đề thường gặp nhất.
Thiếu quyền
Nếu thao tác không khả dụng, hãy kiểm tra vai trò của bạn và nhờ Chủ sở hữu cập nhật quyền.
Lỗi kiểm tra dữ liệu khi nhập
Kiểm tra các trường bắt buộc, slug danh mục và giá trị enum trước khi nhập lại.
Lỗi upload media
Xác nhận định dạng tệp, dung lượng tệp và mức sử dụng lưu trữ theo giới hạn gói.
Google Sheets: 'Không thể tải siêu dữ liệu của bảng tính'
Tệp nhiều khả năng là một .xlsx đã tải lên chứ không phải Google Spreadsheet gốc. Hãy mở tệp, chọn File > Save as Google Sheets, rồi bấm Duyệt trong hồ sơ đồng bộ và chọn tệp vừa chuyển đổi. Hãy kiểm tra thêm rằng tài khoản Google đã kết nối mở được bảng tính.
Google Sheets: trang tính Assets hoặc Variants lỗi 'Tag not found' hoặc 'Category not found'
Các thực thể được tham chiếu phải tồn tại trước khi bất cứ thứ gì trỏ tới chúng. Trình nhập duyệt các trang tính theo thứ tự (Currencies > Rarities > Releases > Tags > Categories > Assets > Variants), nên một danh mục nhập lỗi sẽ kéo theo các tài sản của nó. Hãy đọc bản xem trước chạy thử từ trên xuống và sửa loại thực thể sớm nhất trước.
Google Sheets: giá biến thể báo 'invalid price'
Trình nhập chấp nhận cả dấu chấm (9.99) lẫn dấu phẩy (9,99) làm dấu thập phân. Nếu lỗi vẫn còn, hãy tìm ký tự thừa, ký hiệu tiền tệ hoặc khoảng trắng trong ô giá.