Không gian làm việc và cô lập

Không gian làm việc là gì?

Không gian làm việc là tenant cô lập cấp cao nhất trong Control Center. Nó nhóm agent, kho lưu trữ, space, phiếu, bộ nhớ, quy trình và thành viên vào một ngữ cảnh có ranh giới. Mọi thứ xảy ra bên trong một không gian làm việc đều ở lại trong đó.

Một không gian làm việc thường tương ứng với một dự án hoặc một cơ sở mã. Bạn có thể có các không gian làm việc riêng cho “api-service”, “frontend-v2” và “infrastructure”.

Dữ liệu theo phạm vi không gian làm việc

Các hàng của một không gian làm việc nằm trong tệp SQLite riêng của không gian làm việc đó, tại <dataDir>/<workspaceId>/workspace.db. Mỗi không gian làm việc nhận một thư mục thay vì một tệp trần, bởi vì một không gian làm việc tích lũy nhiều hơn một cơ sở dữ liệu — worktree theo từng hội thoại, các tệp agent và skill, thông tin xác thực chatbot — và trao cho nó một thư mục nghĩa là tất cả những thứ đó cùng sống và cùng bị xóa.

Thực thể	Phạm vi
Agent	Thuộc đúng một không gian làm việc
Kho lưu trữ	Được đăng ký vào một không gian làm việc (xem bên dưới)
Space, hội thoại và tin nhắn	Thuộc phạm vi không gian làm việc
Phiếu, dự án, kế hoạch, điều phối	Thuộc phạm vi không gian làm việc
Dữ kiện bộ nhớ, chính sách, lĩnh vực, quyền truy cập được cấp	Thuộc phạm vi không gian làm việc
Lần chạy quy trình, mẫu, trình kích hoạt	Thuộc phạm vi không gian làm việc
Trạng thái pull request, không gian đánh giá, cohort đánh giá	Thuộc phạm vi không gian làm việc
Nhật ký lần chạy agent và bộ nhớ làm việc	Thuộc phạm vi không gian làm việc
Thành viên, lời mời, quyền cấp theo từng repo	Thuộc phạm vi không gian làm việc
Ký hiệu và cạnh của đồ thị mã	Được giới hạn theo `repoId` trong tệp không gian làm việc

Hầu hết các hàng này đều mang cột workspaceId; các tệp cơ sở dữ liệu riêng biệt thực thi cô lập. Xem bất biến cô lập bên dưới.

Repo thuộc phạm vi không gian làm việc; danh tính giữa các không gian làm việc là theo đường dẫn

Một hàng repo nằm trong tệp cơ sở dữ liệu riêng của không gian làm việc của nó — chính tệp là phạm vi, nên bảng không có cột workspaceId và không có bảng join.

Bạn thêm một repo vào không gian làm việc tại Cài đặt → Không gian làm việc → Kho lưu trữ. Đăng ký cùng một bản checkout trong hai không gian làm việc sẽ tạo ra hai hàng độc lập với hai id; danh tính repo giữa các không gian làm việc là theo đường dẫn hệ thống tệp (hoặc owner/tên trên GitHub), không bao giờ theo id.

Việc đăng ký rất nghiêm ngặt: đường dẫn phải nằm trong một cây làm việc git, phải có một remote origin và remote đó phải trỏ tới một forge được hỗ trợ (github.com, gitlab.com hoặc bitbucket.org). Forge được đọc từ remote và lưu trên repo, nên một không gian làm việc có thể chứa repo từ cả ba. Mọi thứ khác đều bị từ chối. Trình duyệt thư mục mà bạn chọn liệt kê hệ thống tệp của máy chủ, giới hạn trong danh sách cho phép --repo-roots của máy chủ (mặc định là thư mục home của người dùng máy chủ).

Gỡ một kho lưu trữ khỏi không gian làm việc sẽ xóa hàng đó hoàn toàn và xóa theo các ký hiệu mã, cạnh, tệp, checkpoint chỉ mục và quyền cấp theo từng thành viên của nó. Bản checkout trên đĩa không bị ảnh hưởng.

Đồ thị mã nằm trong cùng tệp đó, được khóa theo repoId, vì các không gian làm việc khác nhau có thể có cùng một kho lưu trữ trên các nhánh khác nhau với mã khác nhau.

Bất biến cô lập

Rò rỉ dữ liệu giữa các không gian làm việc bị coi là lỗi. Cô lập mang tính cấu trúc, được thực thi ở nhiều tầng:

Tầng cơ sở dữ liệu. Mỗi không gian làm việc có tệp SQLite riêng, được cấp phát bởi WorkspaceDatabaseManager.of(workspaceId). Một cơ sở dữ liệu không gian làm việc không khai báo users, workspaces hay bảng của bất kỳ không gian làm việc nào khác, nên một phép đọc xuyên không gian làm việc không phải là lỗi bạn có thể viết ra — nó không biên dịch được. Các repository phân giải DAO của mình theo từng lời gọi thay vì cache một cái, và vì mọi phương thức repository đều nhận một workspaceId bắt buộc, không gian làm việc không bao giờ có thể bị suy diễn hay nhận giá trị mặc định.
Id không gian làm việc là một đoạn đường dẫn. Vì id trở thành tên thư mục, nó phải khớp một mẫu một đoạn an toàn (bắt đầu bằng ký tự chữ-số, sau đó là chữ-số, dấu chấm, dấu gạch dưới, dấu gạch nối; không có ..). Id là UUID ở mọi nơi trong sản phẩm. Bất cứ thứ gì khác đều ném lỗi thay vì được làm sạch — đó là hàng rào chống duyệt đường dẫn và nó thất bại ồn ào thay vì ghi dữ liệu của một không gian làm việc vào một đường dẫn do người khác chọn.
Phòng thủ nhiều lớp. Các cột workspaceId vẫn còn đó và vẫn được ghi. Dù dư thừa trong một tệp, chúng giữ nguyên các trigger đồng bộ feed, chỉ mục FTS và hình dạng hàng hiện có, đồng thời khiến một tệp tự mô tả chính nó khi được kiểm tra riêng — đó là thứ mà xuất và nhập dựa vào.
Tầng miền. Các dịch vụ thay đổi thực thể theo id sẽ kiểm tra entity.workspaceId == workspaceId tại một điểm chặn duy nhất trước khi tiếp tục và ném WorkspaceMismatchException khi không khớp — sự thất bại ồn ào dành cho một id đến từ ngữ cảnh sai. Từ chối ồn ào rất quan trọng: một no-op im lặng sẽ che giấu lỗi còn việc tiếp tục sẽ làm rò rỉ.
Tầng RPC. Bộ điều phối repo-RPC là điểm chặn. Mọi thao tác thuộc phạm vi không gian làm việc đều phải mang workspace_id trong đối số của chính nó — không có “không gian làm việc hiện tại” theo phiên để rò rỉ, và một id không xác định bị từ chối như không tìm thấy trước khi bất cứ thứ gì mở cơ sở dữ liệu, nên một id sai không thể tạo ra một workspace.db ma. Những thao tác thực sự toàn cục (bảng tin, hàng đợi đội máy) tự khai báo là không thuộc phạm vi như một quyết định rõ ràng đã được duyệt. Các công cụ MCP tuân theo cùng quy tắc: bất kỳ công cụ nào chạm vào dữ liệu thuộc phạm vi không gian làm việc đều yêu cầu workspace_id.
Fan-out xuyên không gian làm việc có thể liệt kê được. Trả lời một câu hỏi về nhiều không gian làm việc nghĩa là mở nhiều cơ sở dữ liệu. Fan-out đó được giới hạn trong một helper duy nhất, CrossWorkspaceQueries, nên danh sách đầy đủ những thứ hợp pháp vượt qua ranh giới nằm trong các điểm gọi của một tệp thay vì phân tán sau các chú thích tài liệu. Những điểm gọi đó là: tổng hợp toàn máy chủ, bộ điều hòa lúc khởi động, quét lưu trữ và GC, sao lưu, bộ định tuyến sự kiện — và tra cứu thành viên bên dưới.
Truy cập chỉ bằng ID là không đủ. Tra cứu một thực thể theo UUID của nó không chứng minh nó thuộc không gian làm việc của bên gọi. Việc tách tệp khiến tệp sai không thể tiếp cận; việc kiểm tra ở tầng miền bắt được một id sai đến qua một tệp hợp lệ.

Thành viên, không phải khóa ghép nối, mới là thứ cấp quyền truy cập

Việc giữ một thông tin xác thực thiết bị xác thực một thiết bị. Nó không cấp quyền cho bất cứ thứ gì bên trong một không gian làm việc. Mọi thao tác thuộc phạm vi không gian làm việc đều phân giải vai trò thành viên của bên gọi và thực thi một mức sàn rút ra từ loại thao tác — đọc cần guest, thay đổi cần member, thao tác phá hủy cần admin — và các thao tác để lộ nội dung repo còn kiểm tra thêm quyền cấp theo từng repo của bên gọi. Một khóa ghép nối hợp lệ nhưng không có tư cách thành viên sẽ nhận Not a member of this workspace.

Hệ quả đối với cô lập thật gọn gàng: các hàng thành viên nằm trong tệp của chính không gian làm việc, nên “ai đang ở trong không gian làm việc này?” là một phép đọc có phạm vi thông thường. Câu hỏi ngược lại — “tôi đang ở trong những không gian làm việc nào?” — theo định nghĩa trải khắp nhiều tệp, nên nó là một trong số ít fan-out CrossWorkspaceQueries được phép và đó là thứ mà bộ chọn không gian làm việc chạy trước khi bất kỳ không gian làm việc nào được chọn.

Xem Đa người dùng và hiện diện để biết thang vai trò và quyền cấp repo.

Sổ đăng ký toàn cục

Không phải mọi thứ đều thuộc phạm vi không gian làm việc. Một cơ sở dữ liệu thứ hai, <dataDir>/global.db, chứa những gì thực sự thuộc toàn máy chủ:

sổ đăng ký không gian làm việc, để bộ chuyển có thể liệt kê mọi không gian làm việc mà không cần mở một tệp không gian làm việc nào — và để tên, logo, chủ sở hữu, thứ tự thủ công và dấu xóa mềm của một không gian làm việc nằm ngoài tệp mà chúng mô tả;
danh tính: người dùng, tùy chọn người dùng và thiết bị đã ghép nối, bởi vì một con người là một người dùng xuyên mọi không gian làm việc và một thiết bị đã ghép nối vẫn tồn tại khi một không gian làm việc bị xóa;
hàng đợi đội máy (worker, job, nhật ký phân bổ), với bộ lập lịch khớp toàn bộ hàng đợi với mọi worker ở mỗi nhịp;
bảng tin, vốn theo từng người dùng (không theo từng không gian làm việc) — thêm một nguồn cấp sẽ đi theo bạn vào mọi không gian làm việc;
workspace_routes, chỉ mục trước xác thực trả lời câu hỏi “không gian làm việc nào sở hữu khóa này?” cho những điểm vào chỉ mang theo một bí mật hoặc một id mờ (một hash lời mời, một token webhook, một deep link) và không có không gian làm việc. Trượt ở đó là không tìm thấy; cố ý không có phương án quét dự phòng;
cài đặt và danh tính toàn bản cài đặt: id bản cài đặt, cài đặt cấp host, kết nối SSO và chính sách hành động được quản lý (một mức kẹp toàn bản cài đặt chỉ có thể siết chặt rào chắn của không gian làm việc).

Quá trình khởi động chỉ mở tệp này. Các tệp không gian làm việc mở lười ở lần chạm đầu tiên, nên chi phí khởi động giữ nguyên phẳng bất kể các không gian làm việc tích lũy bao nhiêu lịch sử, và quick_check theo từng tệp được trả ở lần dùng đầu tiên thay vì trên đường tới banner sẵn sàng.

Một tệp không gian làm việc chỉ mang một workspace_meta một hàng để tự nhận diện (id của nó, bản cài đặt đã tạo nó, phiên bản lược đồ mà nó được tạo ra, thời điểm). Mọi thứ mô tả về một không gian làm việc đều nằm trong sổ đăng ký.

Tạo một không gian làm việc

Tạo một không gian làm việc làm nhiều hơn việc chèn một hàng vào sổ đăng ký. Trong một thao tác, máy chủ đóng dấu người dùng tạo là ownerUserId, ghi lại tư cách thành viên vai trò chủ sở hữu của người dùng đó và phát một sự kiện miền WorkspaceCreated. Các bên lắng nghe sự kiện đó sau đó gieo mầm, một cách idempotent và trong nền:

một agent CEO cùng bốn chuyên gia — qa, architect, engineer, librarian — với các chuyên gia báo cáo cho CEO;
các mẫu quy trình tích hợp và trình kích hoạt của chúng (trình kích hoạt sự kiện và thủ công được bật sẵn; các trình kích hoạt theo lịch là tùy chọn, ngoại trừ tác vụ quét GC worktree hằng ngày);
các bộ đánh giá khởi đầu.

Điều này xảy ra với mọi không gian làm việc, không chỉ cái đầu tiên. Các agent được gieo mầm được tạo không có adapter, nên chúng chạy trên Control Center (built-in) với mô hình mặc định của Anthropic (claude-opus-4-8 trừ khi bạn ghim một mô hình khác) cho đến khi bạn đặt adapter và mô hình cho từng agent tại Cài đặt → Không gian làm việc → Agent. Xem Mô hình agent.

Việc ghi tư cách thành viên chủ sở hữu quan trọng hơn vẻ ngoài của nó: nếu không có nó, không gian làm việc vừa tạo sẽ không có thành viên nào và mọi lời gọi thuộc phạm vi không gian làm việc mà người tạo thực hiện tiếp theo đều bị từ chối.

Xóa, xuất, nhập

Xóa một không gian làm việc đánh dấu hàng trong sổ đăng ký và hủy liên kết thư mục. Không gian làm việc biến mất khỏi mọi danh sách và tra cứu. Hàng trong sổ đăng ký vẫn còn (đã xóa mềm) để id vẫn được sao lưu và bảo trì biết đến, nhưng workspace.delete lập tức bỏ thư mục của không gian làm việc đó — cơ sở dữ liệu, worktree, tệp agent và phần còn lại — thông qua WorkspaceDatabaseManager.dropAndClose. Chỉ chủ sở hữu không gian làm việc mới có thể xóa nó.

Bởi vì một không gian làm việc là một tệp, việc chuyển giao một không gian làm việc là một thao tác tệp chứ không phải một bản kết xuất từng bảng một:

workspace.export là một VACUUM INTO duy nhất — một ảnh chụp nhất quán, đã chống phân mảnh, được thực hiện trong một giao dịch đọc trong khi máy chủ vẫn tiếp tục phục vụ.
workspace.import nhận một tệp như vậy, thay thế mọi thứ mà không gian làm việc đích đang giữ. workspace_meta nhúng cho phép một lần nhập phân biệt “tệp của chính mình, được nhận lại” với “một tệp từ bản cài đặt khác” (trường hợp sau được phép, nhưng được ghi nhật ký thay vì vô hình).
server.backupNow chụp ảnh toàn bộ bản cài đặt vào một thư mục có dấu thời gian phản chiếu thư mục dữ liệu đang chạy — manifest.json, global.db và một <workspaceId>/workspace.db cho mỗi không gian làm việc — nên khôi phục chính là sao chép nó trở lại.
server.listBackups đọc lại thư mục đó, mới nhất trước, kèm kích thước và danh sách không gian làm việc của mỗi ảnh chụp. Một ảnh chụp thiếu manifest hoặc liệt kê những tệp không tồn tại vẫn được báo cáo, với cờ chưa hoàn tất — che giấu nó là cách một người vận hành đi đến chỗ tin rằng họ có một bản sao lưu mà thực ra không có.

Các thao tác sao lưu nằm dưới Cài đặt → Máy chủ → Sao lưu và khôi phục: Sao lưu ngay chụp một ảnh của bản cài đặt, danh sách hiển thị những ảnh chụp nào hoàn tất và cho phép chủ bản cài đặt xóa một ảnh sau khi xác nhận, và mỗi không gian làm việc cung cấp xuất và nhập. Quy trình tích hợp Workspace backup chỉ lấy cơ sở dữ liệu của không gian làm việc đó theo lịch hằng tuần và xóa các bản sao lưu của chính nó cũ hơn tuổi lưu trữ đã cấu hình. Khôi phục một không gian làm việc từ ảnh chụp bản cài đặt là workspace.import trỏ tới <workspaceId>/workspace.db của ảnh chụp; khôi phục toàn bộ bản cài đặt vẫn là sao chép ngược thư mục ảnh chụp khi máy chủ đã dừng.

Điều mà không thao tác nào mang theo là phần còn lại của thư mục không gian làm việc. Một không gian làm việc tích lũy nhiều hơn một cơ sở dữ liệu — ảnh được dán, tệp skill và agent, thông tin xác thực chat, worktree — và xuất với nhập chỉ di chuyển tệp, nên mọi thứ bên cạnh nó vẫn ở nguyên chỗ cũ. Điều đó là chủ đích đối với thông tin xác thực và có thể bỏ đi đối với worktree; với phần còn lại thì đó là một giới hạn cần biết chứ không phải một tính năng. Tham chiếu sao lưu có bảng đầy đủ.

Di chuyển bản sao lưu giữa máy chủ và thiết bị của bạn

Mọi thao tác ở trên đều nói bằng đường dẫn trên máy chủ, và đó là câu trả lời đầy đủ chỉ khi máy chủ chính là máy của bạn. Ba tuyến HTTP có chữ ký — /backup/workspace, /backup/snapshot và /backup/restore — mang các byte cho mọi mô hình triển khai khác, trên cùng làn đã xác thực mà proxy phương tiện và kho ảnh đang dùng. Trên trang, đây là nút Tải xuống bên cạnh mỗi lần xuất và mỗi ảnh chụp (bạn chọn nơi nó hạ cánh), và Chọn tệp và tải lên để khôi phục từ một tệp nằm trên máy bạn đang dùng. Thao tác tải lên chính là cái hoạt động khi máy chủ không phải máy của bạn: workspace.import cần tệp đã nằm trên host, và đây là cách nó đến được đó.

Ba đặc tính đáng để biết:

Một lần tải xuống tạo ra một bản sao mới và máy chủ không giữ lại gì. Tải xuống không phải là “lấy tệp mà nút xuất đã tạo” — nó xuất lại lần nữa, truyền phát bản đó rồi xóa nó. Phản hồi là no-store với Accept-Ranges: none vì cùng lý do: một dải được tiếp tục sẽ nối hai lần xuất khác nhau thành một tệp trông có vẻ hợp lệ mà lại không hợp lệ.
Một lần tải lên được truyền phát thẳng xuống đĩa, không bao giờ được đệm, ở cả hai đầu, và bản sao tạm được xóa trên mọi lối ra — kể cả khi bị từ chối. Cơ sở dữ liệu của một không gian làm việc không phải là một ảnh chụp màn hình.
Một kết nối qua relay không có origin HTTP, nên các điều khiển truyền tải bị vô hiệu ở đó kèm ghi chú giải thích lý do. Mọi thứ nói bằng đường dẫn phía máy chủ vẫn hoạt động qua relay; chỉ các làn byte mới cần kết nối trực tiếp.

Nhiều không gian làm việc

Bạn có thể chạy nhiều không gian làm việc song song. Mỗi cái hoạt động độc lập: agent trong một không gian làm việc không thể nhắn cho agent ở không gian làm việc khác, không thể đọc bộ nhớ của không gian làm việc khác và không thể thấy phiếu của nó. Việc phân giải người nhận cho tin nhắn giữa các agent là chính xác và không bao giờ vượt qua ranh giới một không gian làm việc.

Không có bảng điều khiển xuyên không gian làm việc. Bề mặt phân tích tại /workspaces/:workspaceId/observability đăng ký một feed toàn cục có giới hạn gồm các lần chạy gần đây và ngay lập tức thu hẹp nó về không gian làm việc đang hoạt động, nên những gì bạn thấy ở đó là một không gian làm việc tại một thời điểm. Những bề mặt thực sự đa không gian làm việc duy nhất mà con người chạm tới là bộ chọn không gian làm việc và bộ chuyển.

Một giới hạn thực tế đáng biết: một không gian làm việc mà ai đó đang dùng sẽ giữ nguyên mở — không có LRU. Vượt quá 32 cái như vậy, máy chủ cảnh báo thay vì từ chối, bởi vì mỗi tệp đang mở giữ một isolate nền và một bộ nhớ đệm trang. Fan-out xuyên không gian làm việc mở các tệp tạm thời và đóng chúng sau đó nếu không có gì khác nhận chúng.

Khái niệm liên quan

Đa người dùng và hiện diện: tư cách thành viên, vai trò và quyền cấp repo — nửa truy cập của cô lập
Mô hình agent: agent thuộc đúng một không gian làm việc
Bộ nhớ và tri thức: bộ nhớ thuộc phạm vi không gian làm việc
Kiến trúc: các cơ sở dữ liệu nằm ở đâu trong phân tách máy khách/máy chủ
Sao lưu và khôi phục: tạo ảnh chụp, di chuyển một không gian làm việc, giữ các bản sao ở nơi khác
Sao lưu, xuất và nhập: mọi thao tác, tuyến, trường manifest và giới hạn
Thêm kho mã vào không gian làm việc: đăng ký một bản checkout vào một không gian làm việc