cowork_local · docs

Cowork Local · Tài liệu kỹ thuật

Cấu trúc hệ thống

Trợ lý AI dạng agent chạy cục bộ trên máy (desktop, ưu tiên Windows). Người dùng trò chuyện, chạy luồng nhiều bước, thao tác tệp và lên lịch tác vụ — mọi thứ được bọc trong một khung bảo mật nhiều lớp.

PySide6 / Qt6 Local-first Provider-agnostic ~53K dòng Python Windows · macOS · Linux

01 Tổng quan & nguyên tắc

Bốn nguyên tắc định hình toàn bộ kiến trúc.

▤Local-first

Cấu hình, lịch sử hội thoại, workspace và nhật ký đều nằm trên máy người dùng. Chỉ lệnh gọi mô hình mới ra ngoài.

⛨Bảo mật nhiều lớp

Mọi tool có tác động (chạy lệnh, ghi tệp, tải URL) đi qua chuỗi kiểm soát fail-closed; xem tài liệu Bảo mật.

⧉Đa workspace

Nhiều project chạy song song, mỗi project nhiều hội thoại Cowork và nhiều luồng Co4E — không cái nào chặn cái nào.

⇄Provider-agnostic

Nhiều nhà cung cấp mô hình (OpenAI-compatible…), tự động định tuyến chọn mô hình phù hợp trong số các model được bật.

02 Ngăn xếp công nghệ

Những thư viện/thành phần chủ chốt và vai trò của chúng.

PySide6/Qt6 · toàn bộ giao diện, đa luồng QThread FastAPI + uvicorn · Routing API (chỉ localhost) MCP · kết nối công cụ ngoài (Model Context Protocol) MSAL · đăng nhập Microsoft 365 openpyxl / python-pptx · đọc Office opendataloader-pdf · trích xuất PDF networkx · đồ thị cấu trúc (GraphRAG) keyring · lưu bí mật qua OS ctypes / Win32 · sandbox AppContainer & Job Object Pygments · tô màu mã nguồn

03 Kiến trúc phân lớp

Một yêu cầu đi từ giao diện xuống lớp thực thi rồi ra ngoài — mỗi lớp có trách nhiệm rõ ràng.

UI

Lớp giao diện — PySide6

người dùng thao tác
MainWindowWorkspaceTab / WorkspacePane CoworkTab (chat)Co4ETab (flow canvas) FolderTabScheduleTaskTab MonitoringTab → SecuritySettingsDialog
Agent

Lớp agent / lõi thực thi

điều phối lượt chạy
chat_agent · run_cowork code_agent · run_code co4e_runner · run_workflow task_executors · tác vụ theo lịch model_routing · assess & chọn model agent_security · guardrail
Tool

Lớp công cụ & sandbox

ranh giới tin cậy
ToolContext · confine đường dẫn + scope execute_tool read/write/edit/list_dir run_command · install_package fetch_url · jira SandboxManager + backends
Provider

Lớp nhà cung cấp mô hình

gọi ra mạng an toàn
providers/* (OpenAI-compatible…) tls_trust · phục hồi TLS gateway usage_tracker · đo token/chi phí
Ngoài

Dịch vụ bên ngoài

không tin cậy mặc định
LLM APIsMCP servers Microsoft 365JiraWeb (fetch_url)

04 Các subsystem chính

Mỗi khối là một tính năng lớn người dùng thấy được, ánh xạ tới module tương ứng.

▦Workspaces & Projects

Nhiều project song song, mỗi cái một pane riêng với sandbox bật/tắt để tiết kiệm tài nguyên.

workspace_tab.pyworkspace_pane.py

💬Cowork · đa hội thoại

Nhiều hội thoại trong một project; lượt chạy nền giữ đúng hội thoại gốc kể cả khi bạn chuyển tab.

chat_panel.pycowork_tab.py

◈Co4E flows

Canvas nhiều bước, agent tùy biến, chế độ auto/plan/manual, chạy song song & theo dõi ở Flow Status.

co4e_tab.pyco4e_runner.py

⇉Model routing

Tự đánh giá & chọn mô hình tốt nhất trong số model được bật theo policy (chất lượng/chi phí/độ trễ).

core/routing/*

⛨Sandbox

Chọn backend theo mức rủi ro: best-effort → AppContainer → Windows Sandbox VM.

sandbox_manager.pyappcontainer_sandbox.py

⏱Scheduler

Tác vụ theo lịch (Cowork/Code/Flow), phụ thuộc chuỗi, opt-in chạy lệnh.

task_scheduler.pytask_executors.py

📊Monitoring

Tổng quan chi phí, nhật ký sự kiện/bảo mật, quản trị Tool/Agent, trang Security.

monitoring_tab.py

🗄Lưu trữ

Cấu hình + lịch sử theo project + workspace + audit log, tất cả trên máy.

config.pycore/history.py

05 Mô hình đồng thời

Vì sao nhiều lượt chạy song song không giẫm chân nhau.

Cô lập theo lượt (per-turn)

Mỗi lượt chat chạy trong một AgentWorker (QThread) riêng. Tại thời điểm bắt đầu, lượt chụp lại bối cảnh home_* (id hội thoại, thư mục làm việc, project) — nên dù người dùng chuyển sang hội thoại khác, lượt nền vẫn ghi kết quả về đúng hội thoại gốc và quét đúng thư mục của nó.

Quản lý luồng Co4E dùng chung

Một Co4ERunManager duy nhất phục vụ mọi pane, mỗi run gắn project_id để lọc. Khi dừng một worker bị treo, nó được "park" giữ tham chiếu (không GC luồng đang chạy → tránh crash QThread destroyed while running).

Cách ly dừng (Stop): nút Stop chỉ tác động lên các worker của chính hội thoại đó và xóa hàng đợi của riêng nó — dừng ở hội thoại này không ảnh hưởng hội thoại khác.

06 Luồng dữ liệu một lượt chat

Từ tin nhắn người dùng đến kết quả — mỗi bước là một điểm kiểm soát.

  1. Tin nhắn + đính kèmNgười dùng gửi; tệp/thư mục workspace được nạp qua _augment.
  2. Bọc nội dung không tin cậyNội dung tệp/web/tool được rào trong khối UNTRUSTED DATA — model coi là dữ liệu, không phải mệnh lệnh.
  3. Định tuyến mô hìnhAuto Routing có thể chọn mô hình phù hợp trong số model được bật.
  4. Gọi providerprovider.chat() qua tls_trust; usage_tracker ghi token/chi phí theo hội thoại gốc.
  5. Model gọi toolMỗi tool qua: kiểm scope ở executor → human-gate (nếu bật) → classifier → sandbox.
  6. Kết quả & lưuVăn bản/diff hiện realtime; hội thoại lưu vào .cowork_history của project.

07 Lưu trữ trên máy

Dữ liệu nằm ở đâu.

~/.cowork_local/config.json · cấu hình (perm 0o600) <project>/.cowork_history · hội thoại theo project workspaces/ · thư mục làm việc mỗi project audit log · mọi tool-call & quyết định quyền (lưu hash lệnh) trusted_certs/ · cert gateway đã pin appcontainer_grants.json · cache cấp quyền sandbox
Vị trí lịch sử có thể trỏ vào thư mục đồng bộ OneDrive — tiện chia sẻ, nhưng lưu ý dữ liệu tệp đã nạp sẽ được sao lên cloud dạng plaintext. Xem khuyến nghị ở tài liệu Bảo mật.