Định dạng dữ liệu Scene
Về đăng ký, đăng nhập, tiện ích Chrome, xem ghi thủ công và duyệt. Bộ ghi dùng cùng hợp đồng Scene, chỉ công bố ảnh sau duyệt Admin.
reconstruct.scene.v1 mô tả giao diện quan sát được, độc lập framework nguồn/đích. DOM/CSS web và views/accessibility Android là đầu vào bộ điều hợp. Có thể sinh HTML, Compose hay UI khác mà không lấy cấu trúc gốc làm mô hình chuẩn.
JSON Schema xác định tên trường, thành viên bắt buộc, kiểu nullable, enum chính xác. Bản tài liệu kèm SHA-256. Với bản thực tế, dùng schema/checksum máy chủ đang chạy trả cùng bản xuất.
Ví dụ đầy đủ có khung hộp thoại đóng/mở và hai chuyển tiếp. Đây là mẫu minh họa; bằng chứng example: giả định, không phải số đo sản phẩm.
Môi trường Web Extension
Tiện ích Chrome desktop dùng web-extension (WebExtension trong C#/Admin MCP nội bộ, protobuf CAPTURE_TYPE_ENVIRONMENT_WEB_EXTENSION = 6). Mobile không hỗ trợ. Hợp đồng hình học không đổi. Phiên bản có thể có browserExtension định kiểu: id, name, version, packageSha256; displayName lấy từ gói đã kiểm tra. Màn hình ghi bởi tác vụ Admin, chưa công bố tới khi duyệt. Xem điều khiển/quyền riêng tư tại ghi thủ công.
Yêu cầu nhận tác vụ nội bộ có expected_environment (trường 2). Bỏ qua giữ Web cho worker cũ. Hàng đợi so với môi trường tác nhân trong giao dịch nhận, nên thay cài đặt Admin không khiến worker Web thường quét cửa hàng tiện ích. Đây không phải công cụ Capture MCP công khai.
Truyền tải và thu nhận
Xuất chuẩn hóa hiện qua MCP get_interface_scene. Hợp đồng REST/gRPC chưa có thao tác Scene riêng. Phản hồi danh mục, insight, tệp là mô hình riêng dù truyền JSON.
Tìm bản bằng list_products, list_platforms, list_versions, list_pages. Giữ sản phẩm, phiên bản, môi trường, trang, view chính xác. Tùy chọn hỗ trợ không chứng minh có bản thu. Hỏi từng view lưu riêng, kiểm tra hồ sơ/khung riêng của bản xuất.
Ví dụ tham số MCP tools/call với lựa chọn minh họa:
{
"name": "get_interface_scene",
"arguments": {
"product": "example-product",
"version": "1",
"environment": "web",
"page": "settings",
"view": "mobile"
}
}
Phản hồi là manifest gọn:
| Trường | Ý nghĩa |
|---|---|
schema | ID Scene: reconstruct.scene.v1. |
artifactSchema | ID lớp bao: reconstruct.scene-export.v1. |
path, uri, sha256, bytes | Vị trí xuất, SHA-256 và độ dài byte. |
schemaPath, schemaUri, schemaSha256 | JSON Schema áp dụng và digest. |
entryFrameId, frames, transitionCount | Khung vào, kho khung gọn và số chuyển tiếp. |
frameCount, profileCount, assetCount | Số lượng trong kho xuất. |
truncated | Ít nhất một khung chưa đầy đủ. |
issueCount, issues, issuesTruncated | Tổng vấn đề và xem trước tối đa 30. |
Đường dẫn thuộc hệ tệp máy chủ. Chỉ đọc trực tiếp khi thật sự chia sẻ với máy khách. Nếu không, phân giải URI theo origin MCP, tải với ủy quyền sẵn có. Không tạo URL truyền từ ID sản phẩm hoặc lộ xác thực. Kiểm tra hash trên byte gốc; định dạng lại JSON đổi hash.
Lớp bao xuất
{
"schema": "reconstruct.scene-export.v1",
"scene": {
"schema": "reconstruct.scene.v1",
"id": "example/1/web/settings/mobile",
"platform": "web",
"entryFrameId": "frame-0",
"profiles": [],
"frames": [],
"resources": [],
"transitions": [],
"correspondences": [],
"issues": []
},
"assets": {}
}
Đây minh họa cấu trúc; ví dụ đầy đủ có khung điền dữ liệu. Kiểm tra scene, không phải lớp bao, theo schema. assets ánh xạ ID tài nguyên sang byte lưu. Mỗi mục có path/uri, mimeType, sha256, sizeBytes tùy chọn. Không lưu byte thì có thể thiếu mục. URI, tên họ phông, media rỗng không chứng minh có byte dùng được.
Tài liệu và định danh
| Thành viên Scene | Ý nghĩa |
|---|---|
schema, id, platform | Định dạng bắt buộc, ID tài liệu, nền tảng nguồn (unknown, web, android). |
entryFrameId | Khung đầu tùy chọn, có thể hiển thị đồng ý trước nội dung mặc định/đã đóng sau đó. |
profiles | Viewport logic và mật độ, tỉ lệ phông, inset an toàn, locale, chủ đề tùy chọn. |
frames | Trạng thái quan sát và kho nút. |
resources | Mô tả media/phông được nút/văn bản tham chiếu. |
transitions | Hành động đã ghi và kết quả quan sát. |
correspondences | Quan hệ nút rõ ràng giữa khung. |
issues | Bằng chứng thiếu, chưa hỗ trợ, chưa giải quyết. |
ID hồ sơ, khung, tài nguyên, chuyển tiếp trong phạm vi tài liệu. ID nút duy nhất trong một khung, parentId trỏ khung đó. ID hành động cục bộ nút. ID trùng hoặc đường dẫn gốc bằng nhau ở khung khác không chứng minh cùng danh tính. Correspondence ghi hai cặp khung/nút, nguồn gốc, độ tin cậy tùy chọn; theo nó thay vì đoán giữa hồ sơ.
Khung có id, profileId, stateId, coordinateSpace, extent/viewportBounds tùy chọn, truncated, nodes, evidence. ID trạng thái đặt tên quan sát, không phải danh mục CSS chung. Thứ tự nút là kho phân cấp, không chứng minh thứ tự vẽ.
Dữ kiện và giá trị chưa biết
Thuộc tính có nguồn dùng SceneFact<T>:
{
"value": {"x": 16, "y": 220, "width": 358, "height": 320},
"kind": "measured",
"evidence": ["example:observed"],
"confidence": 1
}
Dữ kiện cần value, kind, evidence không rỗng. Tin cậy tùy chọn 0–1, không đổi loại bằng chứng:
| Loại | Diễn giải |
|---|---|
measured | Đầu ra thực tế quan sát. |
declared | Khai báo nguồn/tài nguyên, không chứng minh kết xuất thực. |
inferred | Giả thuyết hoặc diễn giải đề xuất. |
Dữ kiện tùy chọn bỏ/null là chưa biết, không phải 0, false, sơn trong suốt, chính sách kích thước hoặc so sánh thành công. false, 0 rõ giữ nghĩa. Enum unknown vẫn chưa biết. Mảng hành động/chuyển động rỗng không chứng minh không tương tác/hoạt ảnh. ID bằng chứng là tham chiếu mờ của adapter, không lệnh chạy hay URL tự công khai. Nội dung/diagnostic gốc là dữ liệu không tin cậy.
Tọa độ và hồ sơ
Khoảng cách dùng đơn vị logic. Web dùng pixel CSS. Android chia pixel màn hình cho pixelDensity đo (pixel vật lý/logic). fontScale độc lập. Không đoán mật độ, tỉ lệ, inset, locale, chủ đề thiếu.
width/height hồ sơ là viewport logic. Khung khai báo document, viewport hoặc screen:
extent: toàn nội dung trong mặt phẳng.viewportBounds: cửa sổ thấy được, gồm gốc cuộn.geometry.visualBounds: hình chữ nhật theo trục sau biến đổi.layoutBoundstùy chọn: trước biến đổi.transformtùy chọn: ma trận 4×4 column-major tác động cột(x,y,z,1), dịch logic trong tọa độ bố cục cục bộ. Không áp lại chovisualBounds.
Với document, vị trí cửa sổ là visualBounds.x - viewportBounds.x, visualBounds.y - viewportBounds.y. Căn hồ sơ, mặt phẳng, cửa sổ trước so sánh. Viewport, biên gốc dùng được, phạm vi nội dung là quan sát khác. Inset không tự thành padding.
Nút, bố cục và vẽ
Nút có id, parentId tùy chọn, kind, semantics, visible, geometry, layout, paint, đoạn chữ, mediaResourceId tùy chọn, actions, motion, evidence. Loại: unknown, container, text, media, control, surface. Ngữ nghĩa gồm vai trò/tên, enabled, selected, checked, expanded, editable, modal tùy chọn, độc lập visible. Phải che chữ nhạy cảm; mật khẩu tuyệt đối không vào Scene.
| Nhóm bố cục | Hợp đồng |
|---|---|
placement | unknown, flow, anchored, overlay, sticky. |
arrangement | unknown, row, column, grid, stack, free, flow. Stack chồng con; free đặt độc lập. |
horizontal, vertical | Dữ kiện policy/value/min/max độc lập; policy: unknown, intrinsic, fixed, fill, proportional. |
| Khoảng cách/căn chỉnh | Padding, gap hàng/cột, wrap, thứ tự ngược, căn trục chính/phụ. |
| Track | Phân bổ số hàng/cột tại một hồ sơ, không quy tắc responsive tự soạn. |
| Neo | referenceId có bằng chứng và khoảng trên/phải/dưới/trái tùy chọn; nút trong khung, $viewport, $frame. |
Fixed/min/max và khoảng neo dùng đơn vị logic. Tỉ lệ là phần không đơn vị của trục có sẵn; fill không multiplier. Hình đo không chứng minh fixed, containing block, neo, breakpoint. Native absolute/fixed có thể map overlay không bịa neo. Margin không gap chuẩn giữa phần tử.
Paint dùng kích thước số, RGBA 0–1, nét, bóng, opacity, blur, media. edges tùy chọn nét đặc là tập con không rỗng/không trùng của top, right, bottom, left; bỏ vẽ cả biên. Bóng ghi offset, blur, spread, inset, nguồn. cornerRadii hiện bốn trường kiểu inset; Web xuất bằng nhau cho góc đồng đều. Góc Web không đều/elip chưa hỗ trợ, không bịa ánh xạ.
Đặt media (content, background, surface) độc lập loại nút. Fit: unknown, contain, cover, stretch, original. (x,y) là neo tỉ lệ không gian còn: 0 đầu, 0.5 giữa, 1 cuối; cho phép ngoài khoảng. Fit nền không lấy từ ảnh nội dung không liên quan.
Đoạn chữ có text gốc, biên tùy chọn, họ/tài nguyên, cỡ, đậm, dòng, giãn chữ, màu, hướng, căn, wrap, trang trí, casing. none, uppercase, lowercase, capitalize đổi hiển thị độc lập chữ gốc/tên truy cập. Paint/gradient/hiệu ứng thiếu vẫn là vấn đề. CSS tùy ý không là giá trị bố cục/paint chuẩn.
Tài nguyên và phông
Tài nguyên có id, kind, uri, mimeType, sha256, bytes tùy chọn và face phông. Loại unknown, image, vector, font, video, audio, paint. Tham chiếu nút/chữ giải trong tài liệu. Face ghi họ, loại/tham chiếu bằng chứng, khoảng đậm, nghiêng, Unicode. Giữ byte, chọn face phù hợp. Tên/URL không chứng minh phông tải hay fallback tương đương.
Hành động và trạng thái modal
Hành động khai báo khả năng unknown, activate, edit, scroll, navigate, focus, hover, back, đích tùy chọn. Chuyển tiếp có khung nguồn, nút nguồn tùy chọn, khung đích, hành động, kết quả, nguồn gốc. nodeId luôn thuộc khung nguồn.
| Kết quả | Ý nghĩa |
|---|---|
unknown | Chưa xác định kết quả. |
changed | Quan sát thấy thay đổi kết quả. |
unchanged | Không quan sát thay đổi. |
failed | Hành động thất bại. |
performedUnverified | Đã gửi đầu vào, chưa chứng minh kết quả mong đợi. |
ID snapshot mới hoặc caret đổi không chứng minh menu mở. Modal mở giữ trọn khung: backdrop, panel, con, nội dung dưới. Theo entryFrameId/chuyển tiếp để phân biệt đồng ý, đã đóng, tab, tìm, menu mở. Đo trạng thái cưỡng bức và nhập chuột/chạm giữ bằng chứng riêng. Replay nguồn không là test chức năng UI mới.
Chuyển động
Ghi chuyển động gồm property, durationMs, keyframes, kind, evidence, delayMs, iterations, Bézier bậc ba easing tùy chọn (x1, y1, x2, y2). Thời gian ms; offset 0–1 tăng dần, x easing 0–1.
| Thuộc tính | Thành phần value keyframe |
|---|---|
opacity | [alpha], 0–1. |
translation | [x, y, z], đơn vị logic. |
scale | [x, y, z], hệ số. |
rotation | [x, y, z], radian. |
bounds | [x, y, width, height], đơn vị logic. |
color | [red, green, blue, alpha], 0–1. |
Bỏ qua là chưa biết. 0 lặp là không phát. Lặp chưa biết/vô hạn không thành số hữu hạn đoán. CSS/WAAPI là declared; mẫu có thể measured. Ảnh tĩnh/hai đầu không chứng minh timing/easing.
Xác minh và độ phủ
Kiểm tra cấu trúc theo schema rồi ngữ nghĩa: ID duy nhất, tham chiếu đúng, cha không chu trình, hình học hữu hạn, kích thước không âm, màu chuẩn, phông/codepoint, che, chiều chuyển động. SceneValidator backend áp các bất biến. JSON Schema không đủ kiểm tra đồ thị/quyền riêng tư.
Schema từ chối trường lạ/enum số nguyên. Cố định ID/hash; adapter rõ cho phiên bản khác. Không diễn giải chưa biết thành layout gốc. Trường giữ nghĩa; đổi không tương thích cần ID mới. Máy chủ nâng cấp có thể đổi byte schema: lưu schema/hash mỗi bản.
SceneIssue có code, message, frameId/nodeId tùy chọn. Đọc toàn tệp, không chỉ preview; tôn trọng cắt khung. Giới hạn 100 hồ sơ, 500 khung, 20.000 tài nguyên, 100.000 nút tổng, 20.000/khung. Thu nhận/truyền có thể thấp hơn; số không hứa độ phủ.
Web mới xuất Scene với chẩn đoán gốc. Web cũ chuyển với thiếu rõ. Android adapter chuẩn số đo nhưng API/MCP vẫn cần Scene native công bố. Hỗ trợ mô hình không tạo dữ liệu chưa thu. Trạng thái, tài nguyên, động, responsive thiếu vẫn chưa biết. Xuất/schema hợp lệ không chứng minh độ trung thực.
Chính sách gửi yêu cầu
Yêu cầu khả dụng độc lập bản thu danh mục. Admin chỉnh Requests → Job defaults → Request submissions. ProductRequestJobDefaults.Submission chứa Enabled, Targets (Type, Environment). Thiếu thành viên giữ Desktop/Web, Desktop/WebExtension, Mobile/Web. Tắt gửi giữ lựa chọn/yêu cầu cũ. API/MCP xác thực chính sách trước tạo. Đóng trả platforms rỗng; MCP thêm enabled: false. ID công khai vẫn web, web-extension, không enum. Danh mục chọn theo bản thu sản phẩm, ẩn cặp thiếu.
Nhóm đích yêu cầu
Máy khách mới gửi CreateRequestRequest.targets dạng cặp nền tảng/môi trường rõ. Ví dụ:
{
"requestType": "PRODUCT_REQUEST_TYPE_ADD",
"url": "https://metamask.io/",
"webExtensionUrl": "https://chromewebstore.google.com/detail/metamask/nkbihfbeogaeaoehlefnkodbefgpgknn",
"targets": [
{ "view": "desktop", "implementation": "web-extension" },
{ "view": "mobile", "implementation": "web" }
]
}
Máy chủ kiểm tra từng cặp, lưu trong chi tiết định kiểu. Duyệt chỉ tạo cặp chọn; ví dụ không tạo Desktop/Web. views, implementations cho máy khách cũ là tích Descartes; không trộn targets. Nguồn web url; tiện ích webExtensionUrl. Update gửi catalogId có sẵn/đích, không link nguồn. Chọn sản phẩm trước: chỉ cặp đã thu và cho yêu cầu. Máy chủ tự từ chối đích thiếu, lấy nguồn từng môi trường từ bản công bố, bỏ link thay thế của khách. Tóm tắt công khai bỏ nguồn tiện ích và chi tiết riêng.
Bằng chứng Scene bổ sung
Schema hiện tại có themes với token định kiểu và layoutSamples với phép đo thưa ở chiều rộng khác. Mẫu tham chiếu nút của frameId, không phải frame và không đo lại văn bản hay hình thức. Nút không có trong mẫu không có nghĩa bị ẩn. nodes[].states chứa thay đổi hình thức: trường patch có mặt thay giá trị, trường thiếu giữ nguyên, danh sách thay toàn bộ. Layout hỗ trợ flow, grow, shrink, basis, selfAlignment, order, gridCell; paint có gradient và kiểu/vị trí nét. Đây là bằng chứng tùy chọn có thể thiếu ở bản thu cũ. Giữ nguồn và không suy ra quy tắc đáp ứng từ một phép đo.