Thuật ngữ

Thực thể cốt lõi

Agent: Một nhân viên AI có danh tính, vai trò, kỹ năng và một adapter. Thuộc đúng một không gian làm việc. Tác nhân chính trong hệ thống.

Adapter: Bộ chạy thực thi một lượt của agent. Có hai loại được cung cấp sẵn: Control Center (tích hợp sẵn) — harness trong tiến trình nói chuyện với các nhà cung cấp mô hình — và Claude Code qua claude -p. Cursor, Codex, Anthropic, OpenAI và những cái còn lại là các nhà cung cấp trên adapter tích hợp sẵn, không phải những CLI riêng. Xem Quản lý adapter và mô hình.

Không gian làm việc: Đơn vị thuê cô lập ở cấp cao nhất. Nhóm các agent, kho mã, space, phiếu, bộ nhớ và quy trình. Cô lập mang tính cấu trúc, không phải quy ước: mỗi không gian làm việc có tệp SQLite riêng (<dataDir>/<workspaceId>/workspace.db), nên một phép đọc xuyên không gian làm việc sẽ không biên dịch được. Mọi tuyến trong ứng dụng đều được thêm tiền tố /workspaces/:workspaceId — xem Bản đồ tuyến.

Máy chủ mã: Một dịch vụ lưu trữ mã — GitHub, GitLab hoặc Bitbucket Cloud. Máy chủ mã là một thuộc tính của mỗi kho mã, được đọc từ remote origin lúc đăng ký, và nó chọn adapter API cùng thông tin xác thực cho kho mã đó. Một không gian làm việc có thể chứa kho mã trên cả ba; các bề mặt tổng hợp (hộp thư, hàng đợi PR) trải ra khắp mọi máy chủ mã hiện diện và hợp nhất kết quả, cô lập lỗi để một máy chủ mã không với tới được không bao giờ làm trống những cái còn lại. Các máy chủ mã khác nhau ở những gì chúng hỗ trợ — xem bảng năng lực trong Kết nối máy chủ mã.

Kho mã: Một kho mã Git được đăng ký trong một không gian làm việc. Có phạm vi theo không gian làm việc — cùng một bản checkout đăng ký ở hai không gian làm việc là hai hàng độc lập với hai id; danh tính kho mã xuyên không gian làm việc được xác định theo đường dẫn hệ thống tệp, không bao giờ theo id. Đăng ký đòi hỏi một git work tree có remote origin trỏ tới một máy chủ mã được hỗ trợ. Mỗi kho mã mang máy chủ mã tương ứng (github / gitlab / bitbucket), thứ chọn adapter API và thông tin xác thực dùng cho nó.

Kho mã cách ly: Một worktree có phạm vi theo không gian làm việc của một kho mã đã đăng ký. Copy-on-write qua rift ở nơi native đó được cung cấp; git worktree trên Windows. Được cấp phát theo từng space — mọi cuộc hội thoại trong space đó dùng chung một bản checkout — nên agent không bao giờ sửa đổi bản gốc.

Space: Một vùng chứa cộng tác có phạm vi theo không gian làm việc với người tham gia là người và agent, một Mode được lưu bền, trạng thái cấp phát và một SpaceKind (topic / agentPeer / system / pr / slack) quyết định cách nó được chia phần, tắt tiếng, gắn huy hiệu và thu gom rác. Nó sở hữu các worktree cách ly mà những cuộc hội thoại của nó chia sẻ (copy-on-write qua rift; git worktree trên Windows).

Cuộc hội thoại: Một luồng tin nhắn bên trong một Space, với id, lịch sử và ngữ cảnh chạy agent riêng. Các cuộc hội thoại trong một space là những bên ngang hàng phẳng — không có luồng chính hay luồng “main”. Mỗi cuộc mở ra như một tab trình soạn thảo; trạng thái chưa đọc của một space tổng hợp từ tất cả chúng.

Luồng: Một cuộc hội thoại có anchorMessageId được đặt: được neo vào một tin nhắn của một cuộc hội thoại anh em trong cùng Space, với ngữ cảnh agent mới được gieo từ tin nhắn neo đó. Chỉ sâu một cấp — luồng không bao giờ neo vào luồng.

Phiếu: Tổng thể đơn vị công việc. Trung lập về nhà cung cấp: mặc định là local, với các adapter đồng bộ cho Linear, GitHub Issues, Jira Cloud và ClickUp — dù không có bề mặt nào trong ứng dụng tạo kết nối đồng bộ. Hỗ trợ phân cấp, liên kết và ủy thác. Giao một phiếu cho agent chỉ ghi nhận quyền sở hữu và không điều phối gì; giao cho một đội là ngoại lệ (TeamRoutingService điều phối người dẫn đầu).

Quy trình: Một quy trình công việc dựa trên DAG, nối các bước (điều phối agent, script, điều kiện) lại với nhau. Được định nghĩa bằng mẫu; được thực thi dưới dạng các lượt chạy.

Đối tượng giá trị

AgentRole: Vai trò được liệt kê (CEO, coder, reviewer, QA, designer, security, devops, PM, general). Quyết định persona, quyền truy cập bộ nhớ và phân cấp.

AgentSkills: Tập hợp không phân biệt chữ hoa chữ thường các mã định danh kỹ năng, giúp tiêm ngữ cảnh liên quan vào prompt lúc điều phối.

Nguồn kỹ năng: Một kho mã GitHub được đăng ký theo từng không gian làm việc làm danh mục kỹ năng. Không đáng tin theo cấu trúc: siêu dữ liệu của kho mã chỉ để hiển thị và mọi lần cài đặt đều đi qua cổng quét fail-closed trước khi có nội dung nào chạm tới đĩa hay prompt. Xem cài đặt và quản lý kỹ năng.

skills-lock.json: Manifest theo từng không gian làm việc về các kỹ năng đã cài: với mỗi kỹ năng là kho mã nguồn, đường dẫn trong kho, commit được ghim và một hash nội dung tổng hợp. Các thao tác cài, cập nhật và gỡ cài đặt giữ nó luôn mới; verify_skills đối chiếu nó với đĩa.

Cổng lượt chạy agent: Một endpoint loopback trên cc_server áp dụng chính sách hành động bên trong sandbox của agent. Mọi lần push lên GitHub mà agent thực hiện đều được định tuyến tới đó, được kiểm tra theo quy tắc Push lên remote và được chuyển tiếp bằng một token ghi mà agent không bao giờ nắm giữ; các lệnh Bash của Claude Code được kiểm tra qua một hook trên cùng endpoint đó. Xem Sandbox và bảo mật.

Chế độ: chat, plan, review hoặc orchestrate. Được lưu theo từng space, nên một agent có thể ở các chế độ khác nhau trong các space khác nhau; mọi cuộc hội thoại trong một space đều dùng chung chế độ đó. Chi phối prompt hệ thống, các quy tắc ghi của sandbox và danh sách công cụ MCP được phép. Khung soạn tin chỉ đưa ra chat, plan và orchestrate; chat được gắn nhãn “Agent”.

SandboxBackend: microvm (một VM khép kín — backend duy nhất có ranh giới kernel, được áp dụng cho terminal tương tác), native (Seatbelt trên macOS, bubblewrap trên Linux và WSL2) hoặc none. Được dò một lần lúc khởi động; native được áp dụng cho việc điều phối agent khi có sẵn, bọc lấy CLI Claude Code và công cụ bash của harness. Windows không có backend native và Linux cần bwrap cùng socat, nên các lượt chạy ở đó không được bọc; --sandbox off là cách chủ động từ chối.

Rig: Một cỗ máy dùng một lần do agent điều khiển trong thời gian thực — một trình duyệt hoặc desktop Linux khép kín, một trình giả lập Android hoặc Simulator iOS do máy chủ quản lý, hoặc một terminal khép kín. Được xem trực tiếp qua làn riêng ở độ phân giải đầy đủ, với việc giành quyền điều khiển được thực thi phía máy chủ. Có phạm vi theo một cuộc hội thoại để tab của người và các lệnh gọi browser_use / computer_use / mobile_use / ios_use của agent cùng nhắm tới một cỗ máy mặc định. Xem Rigs và môi trường cách ly.

Môi trường cách ly: Ranh giới rig mạnh hơn, dựa trên VM — một ranh giới kernel, đĩa overlay dùng một lần, cổng mạng từ chối theo mặc định và bộ môi giới thông tin xác thực. Rig Android và iOS là dùng một lần nhưng dùng mạng do máy chủ quản lý và không tuyên bố ranh giới này. Việc điều khiển bất kỳ rig nào đều dùng lớp rào chắn enclosureControl.

RunCost: Bản tổng hợp token/chi phí (token đầu vào, token đầu ra, chi phí ước tính theo cent) cho một lượt chạy agent.

WakeReason: Lý do một agent được điều phối. Sáu giá trị: tin nhắn người dùng, giao phiếu, điều phối lại để phục hồi sau lỗi, phiếu con hoàn tất, nhịp theo dõi đã lên lịch và bước quy trình.

Cổng

SandboxPort: Quản lý vòng đời sandbox (probe, launch, events, exec, destroy).

CredentialBrokerPort: Cấp thông tin xác thực có phạm vi giới hạn cho việc khởi chạy sandbox — chỉ đọc cho môi trường của agent, quyền ghi chỉ dành cho đường push phía máy chủ — rồi thu hồi chúng khi dỡ bỏ.

GitRepoInspectorPort: Trích xuất siêu dữ liệu (chủ sở hữu, kho mã, nhánh) từ một đường dẫn kho mã Git cục bộ.

EmbeddingPort: Tạo các vector embedding văn bản chuẩn hóa đơn vị cho tìm kiếm ngữ nghĩa.

NotificationPort: Hiển thị thông báo desktop gốc, tôn trọng việc chi phối theo danh mục/tuyến.

TicketProviderPort: Ranh giới trung lập nhà cung cấp tới một backend phiếu công việc (create, get, list, update, transition, assign).

PipelineEnginePort: Khởi động một lượt chạy quy trình từ một mẫu, tách bên gọi khỏi engine cụ thể.

Dịch vụ miền

AgentDispatchService: Khởi chạy các lượt chạy agent: cấp phát kho mã cách ly, dựng prompt, tạo nhật ký chạy, trả về luồng sự kiện trực tiếp.

TicketWorkflowService: Engine vòng đời phiếu thuần miền, với một điểm chốt thay đổi theo cơ chế đồng thời lạc quan và việc thực thi cô lập không gian làm việc. Đồ thị chuyển trạng thái mà nó thực thi chỉ ràng buộc agent và tự động hóa; các thay đổi do người dùng thao tác trên giao diện truyền force: true và bỏ qua nó. Không có bộ điều phối phiếu nào cho người nhận là agent — AgentDispatchService sở hữu việc điều phối, và giao một phiếu cho agent không khởi động lượt chạy nào. Giao một phiếu cho một đội là ngoại lệ (TeamRoutingService điều phối người dẫn đầu).

PipelineEngine: Điều phối việc thực thi lượt chạy: khởi động lượt chạy, lên lịch các bước, lưu bền trạng thái, xử lý router/join/continue-on-fail, tiếp tục các lượt chạy đang dang dở sau khi khởi động lại.

PipelineTriggerDispatcher: Đăng ký các sự kiện miền và tự động khởi động những lượt chạy quy trình khớp với các trình kích hoạt đang bật.

MemoryAccessPolicy: Phân giải và thực thi quyền truy cập bộ nhớ theo vai trò agent trên các miền.

HarnessCostCalculator: Quy đổi mức dùng token của harness tích hợp thành một RunCost theo danh mục models.dev. Việc điều phối lưu bản tổng hợp đó vào nhật ký chạy.

BudgetEnforcementService: Tính chi tiêu hàng tháng theo từng agent và một chốt chặn trước khi điều phối (checkInvocationBlock). Chốt chặn đó chỉ được các bộ hòa giải phục hồi (OrphanRunReaper, StrandedTicketReconciler) tham chiếu, không bao giờ bởi một lần điều phối thông thường của người dùng hay agent.

BudgetGovernanceService: Đánh giá chi tiêu hàng tháng theo từng agent sau mỗi lượt chạy — một ngưỡng mềm ghi lại sự cố cảnh báo; việc cạn ngân sách ghi lại sự cố cứng và đảo vòng đời của agent sang paused.

Sự kiện

DomainEventBus: Bus publish/subscribe quảng bá trong cùng tiến trình cho giao tiếp giữa các tính năng. Sự kiện có kiểu; bên đăng ký tiêu thụ các luồng on<T>().

DomainEvent: Giao diện cơ sở. Mọi sự kiện đều có occurredAt. Các nhóm chính: không gian làm việc/agent, PR/đánh giá, nhắn tin, phiếu, quy trình, cuộc họp/lịch, danh tính, rig, khả năng quan sát.

Cuộc họp và lịch

Cuộc họp: Một phiên họp được ghi và phiên âm cục bộ. Thu âm micrô và âm thanh hệ thống, phiên âm ngay trên thiết bị bằng một mô hình ASR có thể chọn (mặc định là Parakeet TDT v3; Parakeet TDT v2, Whisper large-v3-turbo và Whisper base.en là các lựa chọn thay thế), phân tách người nói và tóm tắt thành ghi chú, việc cần làm và quyết định. Mô hình ASR đã chọn được cài đặt cưỡng bức lúc khởi động và các thao tác ghi sẽ hoạt động sau một lần khởi động lại. Có phạm vi theo không gian làm việc; ở lại trên máy.

MeetingSegment: Một cửa sổ âm thanh đã được phiên âm, có gắn thẻ người nói (me/them) cùng một nhãn phân tách người nói và các mốc lệch mili giây.

MeetingActionItem / MeetingDecision: Các đầu ra có cấu trúc được quy trình tóm tắt trích xuất và lưu thành những hàng riêng. Việc cần làm có thể liên kết tới một phiếu.

CalendarEvent: Một mục Google Calendar đã đồng bộ, có phạm vi theo một không gian làm việc và tài khoản đã kết nối. Khác với Cuộc họp: một sự kiện là cam kết đã lên lịch; một Cuộc họp là phiên được ghi. Được liên kết một-một qua một MeetingCalendarLink.

CalendarAccount: Một tài khoản Google đã kết nối, theo không gian làm việc và email. Token làm mới OAuth được lưu phía máy chủ dưới các khóa google_* trong <dataDir>/secrets.json và không bao giờ tới máy khách; luồng mã thiết bị hoàn tất trên máy chủ. Cờ authExpiredAt điều khiển biểu ngữ kết nối lại.

Thuật ngữ kiến trúc

Clean Architecture: Quy tắc phụ thuộc: Presentation → Application/Providers → Domain ← Infrastructure. Tầng miền không có import hạ tầng nào.

Cổng và adapter: Tầng miền định nghĩa các giao diện trừu tượng (cổng); tầng hạ tầng cung cấp các triển khai cụ thể (adapter). Gốc kết hợp liên kết chúng.

Kernel dùng chung: Các thực thể, đối tượng giá trị, cổng và dịch vụ trong core/domain/ được chia sẻ giữa 3+ tính năng.

Hướng tính năng: Mã được tổ chức theo miền nghiệp vụ (agent, quy trình, nhắn tin) thay vì theo tầng kỹ thuật.

Đa người dùng, danh tính và tốc độ

Principal: Một giá trị niêm phong hợp nhất con người và agent thành một trừu tượng tác nhân duy nhất — UserPrincipal(userId) hoặc AgentPrincipal(agentId). Mọi tin nhắn, phiếu, đánh giá, kế hoạch và nhật ký chạy đều quy về một Principal.

Người dùng: Một danh tính con người, được lưu trong global.db và do đó mang tính toàn cục xuyên các không gian làm việc. Tác nhân tạo ra một không gian làm việc trở thành chủ sở hữu của nó — được ghi vào Workspace.ownerUserId cùng một hàng tư cách thành viên vai trò chủ sở hữu trong cùng thao tác. Những người khác tham gia qua lời mời hoặc SSO.

WorkspaceMember / WorkspaceRole: Một hàng tư cách thành viên gắn một User với một Workspace ở một vai trò (owner / admin / member / viewer / guest). Tư cách thành viên — không phải khóa ghép nối — chính là ranh giới truy cập. Các cấp quyền theo từng kho mã giữ cho tư cách thành viên không tạo ra đặc quyền cao hơn máy chủ mã.

ParticipantPresence: Thông tin hiện diện tạm thời cho một Principal (trạng thái, vị trí, con trỏ, đang gõ, trạng thái trực tiếp của agent và chi phí đang chạy). Không bao giờ được lưu bền; tập trung ở hub phía máy chủ; được lọc theo cấp quyền kho mã trước khi phân phát.

Chế độ theo dõi: Nhấp vào một avatar để bám theo khung nhìn của người đó cho đến khi bạn tự thao tác, rồi tách ra. Hoạt động với cả người và agent (“xem một agent làm việc”).

Nút tự chủ: Một điều khiển theo từng space, theo từng agent — propose-only / act-with-approval / act-freely — được hiện thực như một hồ sơ có tên trên kho rào chắn hành động.

ActionClass: Một tập đóng gồm 13 lớp hiệu ứng (fileDelete, gitPush, prCreate, networkEgress, processSpawn, enclosureControl, …). Mọi công cụ gây thay đổi đều khai báo các lớp của mình; engine rào chắn phân giải allow / prompt / deny theo từng phạm vi (space > agent > workspace > mode preset > built-in default).

WriteLedger / khóa idempotency: Mọi thay đổi đều mang một khóa idempotency do máy khách tạo (UUIDv7, theo từng hành động logic). Sổ cái có phạm vi theo không gian làm việc loại bỏ trùng lặp trước khi trình xử lý chạy; một lần phát lại trả về kết quả gốc giống hệt từng byte. Nhờ cấu trúc, việc kết nối lại và nhiều máy khách trở nên an toàn.

Hộp thư Cần tôi: Một hàng đợi xuyên các trụ cột với quy tắc nghiêm ngặt — một mục chỉ xuất hiện nếu nó chặn một việc gì đó (một agent, một lần merge, một lần đồng bộ) hoặc yêu cầu người vận hành một cách minh thị.

Plan Studio: Bề mặt lập kế hoạch tương tác — các kế hoạch DAG có kiểu, chỉnh sửa được, với chi phí, thời gian và rủi ro theo từng bước, và phê duyệt từng phần.

Tính toán đánh giá: Phần tính toán đánh giá PR phía máy chủ (các cohort suy ra từ đồ thị, sơ đồ có kiểu, diff hình ảnh, diff hợp đồng API, các cổng theo nhiều trục) được phục vụ qua review_studio.* và gộp vào tab Đánh giá.

Space đánh giá: Space nền tảng duy nhất của một PR (chế độ review, loại pr), được tạo theo cơ chế idempotent và liên kết với PR bằng một ReviewSpaceAssociation. Mọi người đánh giá đều ghi phát hiện vào đó, và chính điều đó khiến chúng so sánh được với nhau; worktree cách ly của nó có PR được checkout tại head.

Node đánh giá: Đơn vị có cấu trúc của một phát hiện trong đánh giá AI: loại (bug, suggestion, recommendation, question, ticket), độ ưu tiên P0–P3, bộ ba phân loại danh mục/mức nghiêm trọng/công sức, một điểm neo tệp-và-dòng, bản sửa gợi ý tùy chọn và điểm tin cậy. Được ghi bằng add_review_node; kết luận được tính từ các node, không phải từ văn xuôi.

Consensus-ready: Trạng thái của node đánh giá chỉ đạt được khi một người đánh giá ngang hàng xác nhận một phát hiện — một agent không thể tự xác nhận phát hiện của chính mình. Nút Xuất bản lên GitHub của tab Đánh giá gửi mọi phát hiện mở còn lại (selection: all_open); công cụ MCP publish_review_to_github vẫn chỉ mặc định với các phát hiện đã được xác nhận ngang hàng.

Mức đánh giá: Chính sách của không gian làm việc (light, balanced, thorough) quyết định những người đánh giá nào được triển khai (chỉ kỹ sư; +qa+kiến trúc sư; +bảo mật+hiệu năng) và nơi các phát hiện dưới ngưỡng được hiển thị. Không bao giờ xóa một phát hiện.

Trục đánh giá: Một trong năm làn chấm điểm theo từng lượt đánh giá: correctness, security và testGap lấy từ các phát hiện của người đánh giá; visual và apiContract mang tính tất định. Các trục có cổng được gộp vào kết luận và chỉ có thể khiến nó nghiêm trọng hơn — một cổng partial hoặc unavailable giữ kết luận lại thay vì cho qua.

Kết luận đánh giá: ship, hold hoặc block. Bất kỳ phát hiện P0 nào có độ tin cậy ≥ 0.7 đều block; bất kỳ P0 khác hoặc bất kỳ P1 nào thì hold; còn lại là ship. Một trục có cổng bị lỗi buộc phải block và không thể bị các phát hiện ghi đè.

Đội máy và đánh giá

cc_worker: Một tệp nhị phân thực thi đội máy không giao diện, thuần Dart. Ghép nối với một cc_server, khai báo các năng lực của máy chủ nhà, kéo các công việc đã thuê, thực thi chúng và truyền sự kiện tiến trình ngược về. Không giữ trạng thái bền vững nào — một máy chủ có thẩm quyền, N chi thể ngốc nghếch.

JobSpec: Đặc tả có kiểu cho mọi thứ có thể thực thi (lượt chạy agent, bước quy trình, chỉ mục mã, golden-render, benchmark, lô đánh giá).

Bộ đánh giá: Một định nghĩa đánh giá có phạm vi theo không gian làm việc (prompt, agent đích cùng chế độ, các bộ chấm điểm). Năm bộ khởi đầu được gieo sẵn khi tạo không gian làm việc; Quan sát → Chất lượng liệt kê chúng.

Triển khai và máy khách

Kiến trúc máy khách mỏng: Không máy khách nào mở cơ sở dữ liệu; một tiến trình cc_server không giao diện sở hữu dữ liệu và phục vụ nó qua RPC WebSocket. Mọi máy khách (desktop, web, điện thoại) đều là trình hiển thị trên cùng một kết nối RPC đó.

cc_server: Tệp nhị phân máy chủ không giao diện (Dart thuần, không có engine Flutter). Sở hữu cơ sở dữ liệu Drift/SQLite, phục vụ repo-RPC qua WebSocket và chạy các dịch vụ nền (quy trình, MCP, bộ hòa giải).

ServerConnectionMode: Cách ứng dụng desktop tiếp cận máy chủ của nó — local (khởi tạo một cc_server trên máy này, mặc định) hoặc remote (quay số tới một máy chủ ở nơi khác). Máy khách web luôn là remote.

RemoteRpcClient: Máy khách JSON-RPC độc lập với tầng truyền tải mà mọi máy khách mỏng dùng để nói chuyện với máy chủ — qua WSS, loopback hoặc relay được môi giới.

Phạm vi không gian làm việc theo từng lời gọi: Máy chủ không trạng thái — không có ràng buộc không gian làm việc theo phiên, nên nhiều máy khách trên một máy chủ không bao giờ chia sẻ một “không gian làm việc hiện tại”. Mọi repo/call và sub/subscribe theo phạm vi không gian làm việc đều phải mang workspace_id trong tham số; một id thiếu hoặc chưa đăng ký sẽ bị từ chối trước khi bất kỳ cơ sở dữ liệu nào mở ra. Quyền truy cập khi đó được chi phối bởi tư cách thành viên và vai trò trong không gian làm việc, không phải bởi phiên.

cc_remote: Máy khách mỏng trên điện thoại — một PWA web Flutter điều khiển từ xa toàn đội máy qua relay được môi giới, với chính sách công cụ từ chối theo mặc định.

cc_signaling_server: Một broker relay WebSocket không trạng thái, chứa các phòng có cổng mời — một relay ngốc nghếch chỉ chuyển tiếp các khung được niêm phong đầu-cuối, không giữ dữ liệu ứng dụng nào và không bao giờ thấy PSK ghép nối.