Script kho mã

Script kho mã là các script shell bạn cấu hình theo từng kho mã (Cài đặt → Kho lưu trữ → biểu tượng terminal trên hàng của một kho mã) mà máy chủ Control Center chạy trên worktree của một space thuộc kho mã đó — bản checkout tách biệt nằm dưới <dataDir>/<workspaceId>/spaces/<spaceId>/repos/<repo>/, nơi agent làm việc.

Có hai loại:

Script	Khi nào chạy	Dùng cho
Thiết lập	Ngay sau khi một worktree được cấp phát cho một space	Cài dependency, sinh tệp, sao chép .env
Lưu trữ	Ngay trước khi một worktree bị hủy hoặc thu gom rác	Dọn tài nguyên bên ngoài worktree (mạng Docker, tunnel, trạng thái bên ngoài)

Nơi script chạy

Cả hai script đều chạy qua bash -lc (shell đăng nhập, nên các công cụ cài bằng Homebrew/nvm có trên PATH), với worktree là thư mục làm việc, và các biến môi trường sau được đặt:

Biến	Giá trị
CC_WORKSPACE_PATH	Worktree (thư mục làm việc hiện tại của script)
CC_ROOT_PATH	Kho mã nguồn đã đăng ký — bản checkout của chính bạn
CC_SPACE_ID	Space mà worktree thuộc về
CC_SPACE_NAME	Tên hiển thị của space
CC_REPO_NAME	Tên hiển thị của kho mã

Ví dụ, một script thiết lập cài dependency và đưa vào tệp .env nằm trong .gitignore của kho mã:

pnpm install
cp "$CC_ROOT_PATH/.env" .env
pnpm run build

Hành vi khi thất bại

• Một script thiết lập thoát với mã khác 0 (hoặc vượt quá thời gian chờ 5 phút) làm việc cấp phát space thất bại: space hiển thị trạng thái thất bại kèm nút thử lại, và phần đuôi kết quả đầu ra của lần chạy được ghi lại. Lần thử lại sẽ cấp phát từ một worktree sạch và chạy lại script — hãy viết script thiết lập sao cho việc chạy lại sau một lần cài đặt dở dang vẫn hoạt động (các trình quản lý gói vốn đã hoạt động như vậy).
• Một script lưu trữ chạy theo kiểu nỗ lực tối đa: nếu thất bại (hoặc vượt quá thời gian chờ 2 phút) thì được ghi lại nhưng không bao giờ chặn việc xóa. Script lưu trữ chạy trên các đường GC không có ai để trả lời lời nhắc (space bị xóa, PR được merge, dọn dẹp theo lịch).

Script thiết lập chỉ chạy trên một worktree mới: điều phối lại agent vào một space đã ấm sẽ dùng lại bản checkout hiện có và không phải trả chi phí cài đặt lần nữa.

Lịch sử chạy

Mỗi lần thực thi đều được ghi lại cùng trạng thái, thời lượng, mã thoát và phần đuôi kết quả đầu ra có giới hạn, hiển thị trong cùng hộp thoại cài đặt ở mục “Lần chạy gần đây” (đăng ký repos.watchScriptRuns truyền trực tiếp dữ liệu này).

Quyền

Script là shell mà máy chủ thực thi, nên việc viết chúng chỉ dành cho quản trị viên của không gian làm việc và được bảo vệ bởi lớp hành động processSpawn — cùng lưới rào chắn kiểm soát mọi thao tác sinh tiến trình khác.