ข้ามไปยังเนื้อหา

ตั้งค่าสภาพแวดล้อม

สภาพแวดล้อม คือสแตกที่ทำงานของสเปซหนึ่ง: บริการที่สาขาต้องใช้ แยกจากสเปซอื่นทั้งหมด แสดงในแถบด้านข้าง และเอเจนต์เข้าถึงได้ พูลรีเควสต์ก็มีเช่นกัน เพราะ PR มีสเปซของตัวเองอยู่แล้ว

ผู้ดูแลเวิร์กสเปซเขียน คำจำกัดความ ครั้งเดียว จากนั้นสมาชิกกด เริ่ม ในส่วน สภาพแวดล้อม ของแถบด้านข้างของสเปซหรือ PR คำจำกัดความอยู่ในฐานข้อมูลของเวิร์กสเปซ สาขาฟีเจอร์จึงไม่เปลี่ยนสิ่งที่ Control Center รัน แม้ว่าเครื่องมือจะยังรันโค้ดของสาขานั้น

  1. เปิด การตั้งค่า → เวิร์กสเปซ → สภาพแวดล้อม เฉพาะผู้ดูแลเวิร์กสเปซเท่านั้นที่เปลี่ยนคำจำกัดความได้ และเฉพาะเจ้าของเซิร์ฟเวอร์เท่านั้นที่บันทึกนิยามที่ทำงานบนโฮสต์ได้ (ดู ใครบันทึกอะไรได้บ้าง)
  2. คลิก คำจำกัดความใหม่ แล้วคลิก คำจำกัดความว่าง หรือ ร่างจากรีโพ ฉบับร่างจะค้นหาไฟล์ compose, Procfile และสคริปต์ package.json ในรีโป แล้วคุณตรวจทานผลลัพธ์
  3. กรอกแบบฟอร์ม หรือใช้แท็บ JSON ตัวอย่างในหน้านี้คือ JSON นั้น
  4. คลิก รันการทดสอบ ระบบจะเริ่มสภาพแวดล้อมแบบใช้แล้วทิ้ง รอจนพร้อม แล้วทำลายทิ้ง

การบันทึกจะตรวจสอบนิยามอย่างเข้มงวด ฟิลด์ที่ไม่รู้จัก ค่าที่ชนิดไม่ตรง หรือตัวเลือกที่สะกดผิด จะถูกปฏิเสธ พร้อมเส้นทางและชื่อที่ถูกต้องที่ใกล้เคียงที่สุด เช่น repos.app.requird: Unknown field. Did you mean "required"? อนุญาตให้มี $schema ระดับบนสุด

หากต้องการเก็บคำจำกัดความไว้ในรีโป ให้ใช้ ลิงก์ไฟล์ในรีโพ Control Center อ่านไฟล์จากสาขาเริ่มต้นเท่านั้น และรันเฉพาะเวอร์ชันที่ได้รับการอนุมัติ: โดยผู้ดูแลเวิร์กสเปซ หรือโดยเจ้าของเซิร์ฟเวอร์เมื่อนิยามทำงานบนโฮสต์ เวอร์ชันที่ใหม่กว่าจะแสดง มีอัปเดต และไม่เปลี่ยนอะไรจนกว่าจะได้รับอนุมัติ

นิยามสภาพแวดล้อมอาจรันคำสั่งบนโฮสต์ของเซิร์ฟเวอร์ในฐานะผู้ใช้ของเซิร์ฟเวอร์เอง นั่นเป็นการตัดสินใจของเจ้าของเซิร์ฟเวอร์ ไม่ใช่ของบทบาทในเวิร์กสเปซ:

  • นิยามทำงานบนโฮสต์เมื่อมีการวางบนโฮสต์ การตรวจสอบที่รันคำสั่ง หรืองาน provision หรือ archive งานเหล่านั้นรันใน worktree ของสเปซบนโฮสต์ไม่ว่าการวางจะเป็นอย่างไร
  • เฉพาะเจ้าของเซิร์ฟเวอร์เท่านั้นที่บันทึกหรืออนุมัตินิยามที่ทำงานบนโฮสต์ได้ รวมถึงการอนุมัติเวอร์ชันใหม่ของไฟล์รีโปที่เชื่อมโยง ผู้ดูแลเวิร์กสเปซที่ลองทำจะเห็น “มีเพียงเจ้าของเซิร์ฟเวอร์เท่านั้นที่บันทึกหรืออนุมัติสภาพแวดล้อมที่ทำงานบนโฮสต์ของเซิร์ฟเวอร์ได้ ผู้ดูแลเวิร์กสเปซใช้สภาพแวดล้อมที่ทำงานในริกได้”
  • ผู้ดูแลเวิร์กสเปซบันทึกและอนุมัตินิยามที่ทำงานทั้งหมดในริกได้: "placement": "rig" ไม่มีคำสั่งตรวจสอบ และไม่มีงาน provision หรือ archive
  • สมาชิกเริ่ม หยุด และใช้สภาพแวดล้อมได้ทั้งสองแบบ
  • นิยามที่ทำงานบนโฮสต์จะรันก็ต่อเมื่อเจ้าของเซิร์ฟเวอร์ปัจจุบันบันทึกหรืออนุมัติมันแล้ว เซิร์ฟเวอร์บันทึกการอนุมัตินั้นเอง และตรวจสอบก่อนทุกการเริ่ม การตรวจสอบ งาน และการซิงก์หัว pull request นิยามที่เจ้าของปัจจุบันยังไม่ได้อนุมัติ เช่นนิยามที่เจ้าของก่อนหน้าบันทึกไว้ จะรออยู่ใต้แถวในรายการสภาพแวดล้อมและในตัวแก้ไข เจ้าของเซิร์ฟเวอร์จะเห็น “ทำงานบนเซิร์ฟเวอร์นี้ อนุมัติเพื่อให้เริ่มทำงานได้” พร้อม อนุมัติ ซึ่งจะบันทึกโดยไม่เปลี่ยนแปลง ส่วนทุกคนอื่นจะเห็น “ทำงานบนเซิร์ฟเวอร์นี้ เจ้าของเซิร์ฟเวอร์ต้องอนุมัติก่อนจึงจะเริ่มทำงานได้”
  • สภาพแวดล้อมที่ถูกพักไว้เพื่อรอการอนุมัตินั้นจะแสดง “เจ้าของเซิร์ฟเวอร์ยังไม่ได้อนุมัติสภาพแวดล้อมนี้ จึงรันบนเซิร์ฟเวอร์นี้ไม่ได้” ส่วนเจ้าของเซิร์ฟเวอร์เองจะเห็น “คุณยังไม่ได้อนุมัติสภาพแวดล้อมนี้ มันทำงานบนเซิร์ฟเวอร์นี้ จึงจะเริ่มเมื่อคุณอนุมัตินิยามของมัน” พร้อม ตรวจสอบและอนุมัติ ซึ่งเปิดนิยาม
  • เทอร์มินัลของโปรเซสของสภาพแวดล้อม และเทอร์มินัลที่การเริ่มเปิดขึ้นเมื่อจำเป็นต้องใช้คุณ ทำงานบนโฮสต์ของเซิร์ฟเวอร์ การพิมพ์ การปรับขนาด หรือการปิดเทอร์มินัลเหล่านั้นต้องมีสิทธิ์เขียนไปยังทุกรีโพสิทอรีที่สเปซเปิดเผย ซึ่งอ่านได้ผ่านการลงชื่อเข้าใช้ฟอร์จของคุณเอง เช่นเดียวกับการเริ่มสภาพแวดล้อม ส่วนคนอื่นจะเข้าถึงเทอร์มินัลเหล่านั้นไม่ได้เลย

รีโป compose ธรรมดาต้องการเพียงเท่านี้:

{
"contract": 1,
"name": "Shop",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"components": [ { "kind": "compose", "id": "stack" } ]
}

ส่วนอื่นทั้งหมดมีค่าเริ่มต้น: ค้นพบไฟล์ compose เอง ทุกบริการทำงาน พอร์ตถูกกำหนดให้ ตรวจพบเอนด์พอยต์ HTTP และสภาพแวดล้อมตั้งชื่อตามสาขา

สภาพแวดล้อมคือรายการคอมโพเนนต์ที่เรียงลำดับ แต่ละตัวรอให้ตัวก่อนหน้าพร้อม เว้นแต่ after จะระบุตัวอื่น และการหยุดจะทำย้อนลำดับ enabledWhen ทำให้คอมโพเนนต์ขึ้นกับตัวเลือกหรือบทบาท เช่น opt.seed, !opt.seed หรือ repo.web. คอมโพเนนต์ที่บทบาทเป็นทางเลือกและไม่มีในสเปซจะถูกละออกในลักษณะเดียวกัน โดยไม่ต้องใช้ enabledWhen มันจะไม่เริ่มทำงาน และไม่มี {port.*} หรือ {url.*} ดังนั้นคอมโพเนนต์อื่นที่อ่านค่าเหล่านั้นจะทำให้การเริ่มล้มเหลว

ชนิด ใครรัน ใช้สำหรับ
compose ไดรเวอร์ compose ของ Control Center ไฟล์ compose ใดก็ได้ หนึ่งไฟล์ต่อสภาพแวดล้อม
cli เครื่องมือของคุณ Control Center เรียกคำกริยาที่แมปไว้และอ่าน JSON เครื่องมือที่ดูแลวงจรชีวิต โดเมน และข้อมูลของตัวเอง
process Control Center ในเซสชันเทอร์มินัลที่มีการดูแล เซิร์ฟเวอร์พัฒนาและ worker
task Control Center หนึ่งครั้งต่อทริกเกอร์ การติดตั้ง การย้ายข้อมูล การทดสอบ
app Control Center เมื่อมีคนคลิก เปิดแอป แอปเดสก์ท็อป

คอมโพเนนต์ task รับรายการ when:

ทริกเกอร์ รันเมื่อ
provision สร้าง worktree (ดูงาน worktree ด้านล่าง)
create หนึ่งครั้งต่อสภาพแวดล้อม และอีกครั้งหลังรีเซ็ต
start ทุกครั้งที่เริ่ม
change หลังซิงก์ เมื่อพาธที่เปลี่ยนตรงกับ onChange
manual ตามคำขอ: รัน, cc-env run <id> หรือ environment_run_task
archive ก่อนทำลาย worktree ทันที

งานที่ไม่มีอะไรต้องทำระหว่างการเริ่มทำงานจะแสดงสถานะ ว่าง และไม่ปรากฏในรายการขั้นตอนที่แสดงขณะสภาพแวดล้อมกำลังเริ่มทำงาน ได้แก่ งานประเภท manual หรือ change หรืองาน create ที่รันไปแล้ว

คำสั่งที่ให้เป็นอาร์เรย์คือ argv ค่าตัวเลือกจึงไม่ผ่านเชลล์ สตริง หรือ script ที่มีอาร์เรย์ของบรรทัด จะรันภายใต้ bash -lc ตัวยึดตำแหน่งอย่าง {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} และ {url.<role>} ขยายเฉพาะใน argv คำสั่งเชลล์อ่านค่าเดียวกันจากตัวแปร CC_ENV_* เช่น $CC_ENV_PORT_WEB. ตัวยึดตำแหน่งที่ไม่รู้จักในคอมโพเนนต์ที่อยู่ในสภาพแวดล้อมของสเปซนี้จะหยุดการเริ่มก่อนที่จะมีอะไรรัน

ทุกคำสั่งและเทอร์มินัลของสเปซยังได้รับ CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE> และในสเปซของ PR จะได้ CC_PR_NUMBER กับ CC_PR_IS_FORK เมื่อมีคอมโพเนนต์ compose ก็จะได้ COMPOSE_PROJECT_NAME และ COMPOSE_FILE ด้วย ทำให้ docker compose exec ในงานไปถึงโปรเจกต์ที่ถูกต้อง

คำจำกัดความผูก บทบาท กับรีโปของเวิร์กสเปซ สแตกเดียวจึงครอบคลุมได้หลายรีโป:

"repos": {
"api": { "repoId": "<api>", "anchor": true, "required": true },
"web": { "repoId": "<web>", "anchor": true },
"e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }
}
  • anchor: สเปซเริ่มสภาพแวดล้อมได้เมื่อมีบทบาทสมอย่างน้อยหนึ่งบทบาท หากคำจำกัดความสองรายการตรงกัน คนที่เริ่มเป็นผู้เลือก
  • required: สแตกทำงานไม่ได้หากไม่มีรีโปนี้
  • whenMissing: สิ่งที่เกิดขึ้นเมื่อสเปซไม่มีบทบาทนั้น addToSpace เพิ่มรีโปที่สาขาเริ่มต้นและเป็นค่าเริ่มต้นของบทบาท required ส่วน useSource ส่งเช็กเอาต์ที่ลงทะเบียนของคุณ ซึ่งควรถือเป็นอ่านอย่างเดียว และ skip ปล่อยตัวแปรไว้ไม่กำหนดและเป็นค่าเริ่มต้นในกรณีอื่น
  • การเริ่มต้องมีสิทธิ์ write บนรีโปสมอในสเปซ และสิทธิ์อ่านรีโปอื่นที่ผูกไว้ทั้งหมด

คำสั่งรันในบทบาทแรกที่ประกาศไว้ใน repos ไม่เคยรันในบทบาทอื่นที่สเปซบังเอิญมี คำจำกัดความรีโปเดียวจึงไม่ต้องกล่าวถึง คอมโพเนนต์ใดก็เขียนทับได้ด้วย "cwd": { "role": "e2e", "path": "packages/ui" } ทั้งสองฟิลด์เป็นทางเลือก. เมื่อบทบาทแรกอาจหายไปจากสเปซ เพราะไม่ใช่ required และก็ไม่ใช่ตัวยึดเพียงตัวเดียว คอมโพเนนต์ทุกตัวต้องระบุบทบาทของตน

Control Center กำหนดพอร์ตของโฮสต์ก่อนที่สิ่งใดจะเริ่ม จากช่วงที่ใช้ร่วมกันทั้งโฮสต์ (ค่าเริ่มต้น 42000 ถึง 49999 เป็นบล็อกละ 32) พอร์ตคงเดิมตลอดอายุของสภาพแวดล้อม และพอร์ต compose ผูกกับ 127.0.0.1 เท่านั้น

  • พอร์ต compose ไม่ต้องประกาศ อ่านเป็น {port.postgres.5432} หรือ CC_ENV_PORT_POSTGRES_5432
  • พอร์ตอื่นประกาศในที่ที่ใช้ ด้วย "port": "web" หรือ "ports": ["web", "hmr"] และอ่านเป็น {port.web} โปรเซสที่มีพอร์ตจะได้ PORT และ HOST=127.0.0.1 ด้วย

เอนด์พอยต์ HTTP ได้รับ URL บนเราเตอร์ของเซิร์ฟเวอร์ ซึ่งรอรับบนพอร์ต loopback เดียว:

http://<endpoint>--<name>--<project>.localhost:<router port>
http://web--fix-login--shop.localhost:7355
  • <name> คือสาขาในรูปสลัก หรือ pr-<n> ในสเปซของ PR ส่วน <project> คือ naming.project หรือชื่อคำจำกัดความหากไม่มี
  • ชื่อ *.localhost ชี้ไปที่ loopback จึงไม่ต้องมีรายการ hosts หรือ DNS และชื่อโฮสต์แยกคุกกี้ระหว่างสภาพแวดล้อม
  • พอร์ต compose ที่ตอบ HTTP จะถูกตรวจพบ และ http บนคอมโพเนนต์จะแทนที่การคาดเดานั้น โปรเซสต้องมี "endpoint": { "role": "web", "primary": true } ซึ่งทำให้ใช้ {url.web} ได้ด้วย
  • ในเบราว์เซอร์ (VM) ให้ใช้ เปิดใน Browser (VM) ที่นั่น https://web--fix-login--shop.localhost/ จะไปถึงเส้นทางเดียวกัน
  • ป้ายกำกับทั้งหมดไม่เกิน 63 อักขระ ชื่อยาวจึงถูกย่อด้วยแฮช
  • เอนด์พอยต์สองตัวไม่มีโดเมนแม่ร่วมกัน แอปที่ต้องการคุกกี้เดียวสำหรับทั้งสองต้องให้บริการจากเอนด์พอยต์เดียว

สำหรับ URL ที่ต้องลงทะเบียนล่วงหน้า เช่น การเปลี่ยนเส้นทาง OAuth "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } ให้ชุดชื่อที่ตายตัว

policy กำหนดว่าสภาพแวดล้อมทำงานเมื่อใด autoCreate เป็น off, prSpaces หรือ allSpaces, idleStopMinutes มีค่าเริ่มต้น 240, followPrHead ซิงก์สภาพแวดล้อมของ PR เมื่อ head ขยับ และ maxRunning (ค่าเริ่มต้น 6) ทำให้ เริ่ม เสนอให้หยุดสภาพแวดล้อมที่ไม่ได้ใช้นานที่สุด

เว็บแอปและ Postgres จากไฟล์ compose เดียว พร้อม .env ที่ git ละเว้น การย้ายข้อมูล และงานทดสอบ seedFiles คัดลอกไฟล์ที่ระบุจากเช็กเอาต์ที่ลงทะเบียนของคุณไปยังทุก worktree ใหม่

{
"contract": 1,
"name": "Shop",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"naming": { "project": "shop" },
"seedFiles": [".env"],
"components": [
{ "kind": "compose", "id": "stack",
"services": ["postgres", "web"],
"healthchecks": { "postgres": ["pg_isready", "-U", "postgres"] } },
{ "kind": "task", "id": "migrate", "when": ["create", "change"],
"onChange": ["db/migrations/**"],
"command": "docker compose exec -T web bin/migrate" },
{ "kind": "task", "id": "test", "when": ["manual"],
"command": "docker compose exec -T web bin/test" }
]
}

healthchecks ทำให้บริการที่ไม่มีการตรวจสุขภาพของตัวเองหน่วงคอมโพเนนต์ถัดไปได้ หากไม่มี คอนเทนเนอร์ที่ทำงานถือว่าพร้อม และการย้ายข้อมูลอาจแซงฐานข้อมูลที่ยังเริ่มไม่เสร็จ

การเริ่มและการรีเฟรชทุกครั้งจะรัน up ด้วย --remove-orphans ดังนั้นบริการที่ถูกลบออกจากไฟล์ compose จะหยุดและคืนพอร์ต อิมเมจจะถูกบิลด์ตอนเริ่มและตอนรีเฟรช เว้นแต่คอมโพเนนต์ตั้ง "build": false

เครื่องมือสมมติ acme ที่ดูแลคอนเทนเนอร์ โดเมน และ TLS ของตัวเอง Control Center ให้ {name} และเรียนรู้ที่เหลือจาก status โดยไม่เดาชื่อโฮสต์ของเครื่องมือและไม่แก้ไข /etc/hosts

{
"contract": 1,
"name": "Acme",
"repos": {
"server": { "repoId": "<server>", "anchor": true, "required": true },
"web": { "repoId": "<web>", "anchor": true }
},
"routing": { "mode": "tool", "domain": "acme.test", "upstream": "127.0.0.1:443",
"tls": true, "caFile": "~/.acme/tls/ca.crt" },
"components": [
{ "kind": "cli", "id": "acme",
"verbs": {
"create": ["acme", "env", "create", "{name}",
{ "if": "!interactive", "args": ["--json"] },
{ "if": "repo.web", "args": ["--web-dir", "{repo.web}"] }],
"start": ["acme", "env", "start", "{name}"],
"stop": ["acme", "env", "stop", "{name}"],
"destroy": ["acme", "env", "destroy", "{name}", "--yes"],
"reset": ["acme", "env", "reset-db", "{name}"],
"status": ["acme", "env", "status", "{name}", "--json"],
"list": ["acme", "env", "ls", "--json"],
"logs": ["acme", "env", "logs", "{name}",
{ "if": "service", "args": ["{service}"] },
"--tail", "{tail}",
{ "if": "follow", "args": ["--follow"] }],
"exec": ["acme", "env", "exec", "{name}", "{service}", "{command}"]
},
"interactive": ["create"],
"keepsDataOnStop": false,
"statusMap": {
"state": [
{ "when": { "path": "/status/ready", "equals": true }, "state": "ready" },
{ "when": { "none": "/status/containers", "where": { "state": "running" } },
"state": "stopped" },
{ "when": { "path": "/status/phase", "equals": "failed" }, "state": "failed" },
{ "state": "starting" }
],
"detail": "phase: {/status/phase}",
"warnings": [
{ "when": { "path": "/status/dnsWorking", "equals": false },
"message": "Not resolvable on this host" }
],
"endpoints": [
{ "role": "app", "label": "App", "url": "/urls/app", "primary": true },
{ "role": "db", "hostPort": "/ports/db" }
],
"services": "/status/containers/*/service",
"list": "/*/slug",
"missingErrorCodes": ["env.not-found"]
} }
]
}
  • ต้องมี create, status และ destroy Control Center เลือก create หรือ start จากสถานะที่อ่านได้ คำกริยาใดก็เป็น { "shell": "…" } แทน argv ได้
  • interactive ระบุคำกริยาจาก create, start และ reset ที่สามารถขอสิ่งที่ต้องการบนเทอร์มินัลได้ เมื่อคำกริยาเช่นนั้นออกด้วยรหัส 3 สำหรับบุคคลที่กด Start Control Center จะรันคำกริยาเดิมอีกครั้งบนแท็บเทอร์มินัล และการเริ่มจะดำเนินต่อเมื่อออกด้วยรหัส 0 ที่นั่นเงื่อนไข interactive เป็นจริงและตั้ง CC_ENV_INTERACTIVE=1 ดังนั้น { "if": "!interactive", "args": ["--json"] } จะเก็บเอาต์พุตสำหรับเครื่องไว้ให้ pipe การเริ่มโดยเอเจนต์หรือการเริ่มอัตโนมัติจะไม่เปิดเทอร์มินัลเลย สภาพแวดล้อมจะแสดง ต้องดำเนินการ และรอ
  • destroy ที่ล้มเหลวยังคงลบสภาพแวดล้อมได้เมื่อภายหลัง status รายงานว่า missing ดังนั้นสภาพแวดล้อมที่เครื่องมือไม่มีแล้วจะลบได้เสมอ
  • list ทำให้ Control Center สังเกตเห็นสภาพแวดล้อมที่เครื่องมือทำหาย จะถูกทำเครื่องหมายว่าหายไปก็ต่อเมื่อชื่อของมันไม่อยู่ใน list และ status แสดง missing ผลลัพธ์ที่อ่านเป็นรายการไม่ได้จะไม่เปลี่ยนแปลงอะไร
  • {service} ใน logs และ exec ต้องเป็นคำเดียวที่ไม่ขึ้นต้นด้วย - และต้องเป็นหนึ่งในบริการที่เครื่องมือรายงานครั้งล่าสุดเมื่อมีการรายงานใด ๆ
  • statusMap อ่าน JSON ของเครื่องมือด้วยตัวชี้ JSON โดย * ตรงกับทุกรายการ กฎสถานะเรียงลำดับและรายการแรกที่ตรงจะชนะ เงื่อนไขคือ path กับ equals หรือ any หรือ none กับ where
  • keepsDataOnStop: false ปิดการหยุดเมื่อไม่ได้ใช้งาน และเพิ่มคำเตือนข้อมูลสูญหายให้ หยุด ตั้งค่านี้เมื่อการหยุดทำให้ข้อมูลหาย
  • routing.mode: "tool" เชื่อมชื่อโฮสต์ของเครื่องมือกับเบราว์เซอร์ (VM) และเอเจนต์ โดเมนต้องลงท้ายด้วย .test, .localhost หรือ .internal และ URL ที่รายงานนอกโดเมนจะถูกทิ้ง

เครื่องมือของคุณเองสามารถข้าม statusMap และพิมพ์สัญญาสถานะที่อธิบายไว้ท้ายหน้านี้

มีเฉพาะโปรเซสและงาน ไม่มีคอนเทนเนอร์ เว็บแอปหา API ผ่าน {url.api}

{
"contract": 1,
"name": "Monorepo",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"naming": { "project": "mono" },
"options": [ { "key": "seed", "type": "bool", "default": true, "agentDefault": false } ],
"components": [
{ "kind": "task", "id": "install", "when": ["provision", "change"],
"onChange": ["pnpm-lock.yaml"],
"command": ["pnpm", "install", "--frozen-lockfile"] },
{ "kind": "process", "id": "api", "label": "API", "port": "api",
"cwd": { "path": "apps/api" },
"command": ["pnpm", "dev"],
"endpoint": { "role": "api" },
"ready": { "http": "http://127.0.0.1:{port.api}/health", "timeout": 120 },
"restartOn": ["pnpm-lock.yaml"] },
{ "kind": "task", "id": "seed", "when": ["create"], "enabledWhen": "opt.seed",
"cwd": { "path": "apps/api" },
"command": ["pnpm", "db:seed"] },
{ "kind": "process", "id": "web", "label": "Dev server", "port": "web",
"cwd": { "path": "apps/web" },
"env": { "API_URL": "{url.api}" },
"command": ["pnpm", "dev", "--port", "{port.web}", "--host", "127.0.0.1"],
"endpoint": { "role": "web", "primary": true },
"ready": { "http": "http://127.0.0.1:{port.web}/" } },
{ "kind": "task", "id": "lint", "when": ["manual"], "command": ["pnpm", "lint"] }
]
}
  • แต่ละโปรเซสคือแท็บเทอร์มินัลที่คุณเปิด อ่าน และพิมพ์ได้ หากคุณมีสิทธิ์เขียนไปยังทุกรีโพสิทอรีในสเปซ (ดู ใครบันทึกอะไรได้บ้าง) การปิดแท็บไม่ได้หยุดโปรเซส
  • ready รับ http (URL เต็ม), tcp (host:port) หรือ logMatch (นิพจน์ทั่วไป) ส่วน restart เป็น on-failure (ค่าเริ่มต้น), always หรือ never และ restartOn รีสตาร์ตโปรเซสเมื่อพาธที่เปลี่ยนตรงกัน
  • options กลายเป็นแบบฟอร์มที่ เริ่ม และ agentDefault ใช้กับการรันที่เอเจนต์เริ่ม

แอปเดสก์ท็อปที่มีขั้นตอนบิลด์ แอปทำงานเหมือนกันไม่ว่าจะสร้างด้วยอะไร เพราะ Control Center ทำงานในระดับหน้าต่างของระบบปฏิบัติการและไม่ต้องมีฮุกหรือ SDK ในแอป

{
"contract": 1,
"name": "Studio",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"components": [
{ "kind": "task", "id": "build", "when": ["manual"], "command": ["pnpm", "build"] },
{ "kind": "app", "id": "desktop", "label": "Studio", "prepare": "build",
"command": ["dist/mac-arm64/Studio.app/Contents/MacOS/Studio"],
"isolate": "home" }
]
}

แอปไม่เริ่มพร้อมสภาพแวดล้อม มีคนคลิก เปิดแอป แล้ว prepare จะรันก่อน บิลด์ใหม่และเปิดอีกครั้ง รันคู่นั้นอีกครั้ง enabledWhen ใช้กับแอปและกับงาน prepare ของแอป และ เปิดแอป จะถูกปฏิเสธเมื่อตัวใดตัวหนึ่งถูกปิดอยู่ แอปถือว่ากำลังทำงานตราบที่มีโปรเซสใดในกลุ่มโปรเซสของมันยังรันอยู่ ดังนั้นตัวเปิดที่เริ่มแอปแล้วออกก็ไม่เป็นไร หากทุกอย่างหายไปภายในราว 5 วินาทีหลัง เปิดแอป แอปจะแสดงว่าล้มเหลวพร้อมบรรทัดบันทึกสุดท้าย. หลังจากนั้น การออกอย่างปกติแสดงเป็นปิดแล้ว การแครชแสดงบรรทัดบันทึกสุดท้าย และทั้งสองอย่างไม่รีสตาร์ตแอป การรีสตาร์ตเซิร์ฟเวอร์จะปิดแอปและไม่เปิดใหม่เลย และการหยุดเมื่อไม่ได้ใช้งานจะไม่แตะแอปที่กำลังทำงาน

  • บน macOS ให้สิทธิ์ การบันทึกหน้าจอ และ การช่วยการเข้าถึง แก่ Control Center ครั้งเดียวในการตั้งค่าระบบ โฮสต์ของเซิร์ฟเวอร์ต้องมีเซสชัน GUI เซิร์ฟเวอร์แบบ headless จะปฏิเสธการเปิดแอป
  • เปิดไบนารีโดยตรง open -a ส่งแอปให้ LaunchServices แล้วแอปจะออกจากทรีโปรเซสที่ Control Center ติดตาม จึงทำให้แอปแสดงว่าล้มเหลวทันทีหลังเปิด
  • หน้าต่างอยู่บนจอแสดงผล macOS ไม่จับภาพหน้าต่างที่จอดอยู่นอกจอทั้งหมด แอปที่เอเจนต์ใช้จึงมองเห็นบนหน้าจอของเซิร์ฟเวอร์ แอปไม่จำเป็นต้องมีโฟกัส
  • "isolate": "home" ให้โฮมส่วนตัวแก่แอปผ่าน HOME, XDG_* และ CFFIXED_USER_HOME เพื่อให้สำเนาจากสองสเปซทำงานเคียงกันได้ NSUserDefaults ไม่ถูกแยก ค่ากำหนด Cocoa และ shared_preferences ของ Flutter จึงยังใช้ร่วมกันระหว่างสำเนา
  • isolate ใช้กับโปรเซสที่เปิดเท่านั้น ตัวเปิดเครื่องมืออย่าง flutter run ต้องการโฮมจริง จึงควรใช้ isolate กับไบนารีที่บิลด์แล้ว หากแอปมีการตั้งค่าของตัวเอง เช่น --user-data-dir ให้ใช้สิ่งนั้นก่อน
  • เอเจนต์ควบคุมหน้าต่างด้วย app_use ซึ่งเข้าถึงได้เฉพาะทรีโปรเซสของสภาพแวดล้อมนี้ เอเจนต์เห็นหน้าต่าง ไม่ใช่เดสก์ท็อป การเปิดโดยเอเจนต์ผ่านนโยบายการกระทำและถามก่อนตามค่าเริ่มต้น และอินพุตของเอเจนต์จะหยุดขณะที่คนถือการควบคุม
  • "input": "background" (ค่าเริ่มต้น) ส่งเหตุการณ์ไปยังโปรเซส "foreground" เปิดใช้งานหน้าต่างและยึดเคอร์เซอร์

งาน provision และ archive รันการตั้งค่าและการรื้อถอนของรีโปพร้อมกับ worktree ของมัน ไอคอนบนแถวของรีโปใน การตั้งค่า → เวิร์กสเปซ → รีโพสิทอรี จะเปิดคำจำกัดความของรีโปนั้น

งานเหล่านี้ตาม worktree ไม่ใช่สภาพแวดล้อม จึงรันในสเปซที่ไม่มีใครกด เริ่ม ด้วย:

provision archive
รันเมื่อ สร้าง worktree ของบทบาท ในสเปซใดก็ได้ ก่อนทำลาย worktree นั้นทันที
เมื่อล้มเหลว การจัดเตรียมล้มเหลวและ worktree ถูกทำลาย บันทึกไว้ ไม่บล็อกการลบ
หมดเวลาเริ่มต้น 5 นาที 2 นาที
มองเห็น CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME เหมือนกัน

รีโปที่ไม่มีสแตกต้องการเพียงคำจำกัดความที่มีงานของตน เมื่อไม่มีอะไรให้เริ่ม จึงไม่ต้องมีบทบาทสมอ:

{
"contract": 1,
"name": "Web",
"repos": { "app": { "repoId": "<id>" } },
"components": [
{ "kind": "task", "id": "setup", "when": ["provision"],
"script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] }
]
}
  • ยังไม่มีสภาพแวดล้อม งานเหล่านี้จึงใช้ {name}, {port.*}, {url.*}, {opt.*} หรือ enabledWhen ไม่ได้ และไม่ได้รับ env ของคำจำกัดความ
  • มีคำจำกัดความได้เพียงรายการเดียวที่ถืองาน provision และ archive ของรีโปหนึ่ง รายการอื่นยังผูกรีโปนั้นเพื่อการอื่นได้
  • "when": ["provision", "change"] ยังติดตั้งใหม่เมื่อไฟล์ล็อกเปลี่ยน
  • งานรันสำหรับ worktree ของบทบาท cwd คำจำกัดความหลายรีโปจึงตั้งค่าแต่ละรีโปแยกกันได้
  • การรันทดสอบตั้งค่า CC_SCRIPT_TEST=1 การลองใหม่เริ่มจาก worktree ที่สะอาด จึงควรเขียนงานให้ทนการรันซ้ำ

เอเจนต์ไม่ได้รับซ็อกเก็ต Docker ในสเปซที่มีคำจำกัดความที่เข้าเกณฑ์ การรันจะได้ cc-env บน PATH สเปซมาจากการรัน เอเจนต์จึงกระทำได้เฉพาะกับสภาพแวดล้อมของตัวเอง และทุกคำสั่งผ่านนโยบายการกระทำ

หน้าต่างเทอร์มินัล
cc-env status
cc-env up
cc-env down
cc-env reset
cc-env destroy
cc-env restart <process>
cc-env logs <name>
cc-env exec <service> -- <cmd>
cc-env run <task> -- <args>

เมื่อมีคอมโพเนนต์ compose ชิม docker ยังอนุญาต docker compose กับ ps, logs, exec, port, restart และ top และใช้ได้กับโปรเจกต์ compose ของสภาพแวดล้อมนี้เองเท่านั้น ห้ามมีแฟล็กก่อนคำกริยา และแต่ละคำกริยารับตัวเลือกจำนวนจำกัด: logs ติดตามเอาต์พุตไม่ได้ และ exec รับเฉพาะ -T (หรือ --no-tty) ตัวเลือกที่ชี้ compose ไปยังไฟล์หรือโปรเจกต์อื่น (-f, -p, --project-directory, --env-file, --profile) จะถูกปฏิเสธไม่ว่าจะอยู่ตรงไหน อย่างอื่นจะออกด้วยรหัส 5 และ “not available in Control Center agent runs”

รีโปที่สกิลเรียกเครื่องมือของตัวเองทำเช่นนั้นต่อได้ บล็อก agentPassthrough บนคอมโพเนนต์ cli ประกาศว่าเอเจนต์รันคำสั่งใดได้บ้าง มีเพียงคำสั่งที่นิยามที่อนุมัติประกาศเท่านั้นที่ส่งต่อได้ และแต่ละคำสั่งรันบนโฮสต์ จึงอยู่ภายใต้กฎ รันคำสั่งบนโฮสต์ ซึ่งถามก่อนเป็นค่าเริ่มต้น:

"agentPassthrough": {
"binary": "acme",
"allow": [
{ "argv": ["env", "ls"], "maps": "status", "nameFilter": true },
{ "argv": ["env", "status|url"], "maps": "status", "positionalName": 2 },
{ "argv": ["env", "create"], "maps": "up", "positionalName": 2,
"pathFlags": ["--web-dir"], "denyFlags": ["--force"] },
{ "argv": ["env", "logs"], "maps": "logs", "positionalName": 2,
"denyFlags": ["--follow"] }
]
}

maps ระบุการดำเนินการที่ใช้นโยบาย positionalName บังคับอาร์กิวเมนต์นั้นเป็นสภาพแวดล้อมของสเปซนี้ nameFilter กรองเอาต์พุต JSON ตามนั้น และค่า pathFlags ทุกค่าต้องชี้เข้าไปใน worktree ของการรัน คำสั่งที่ไม่ตรงกฎใดจะออกด้วยรหัส 5

การดำเนินการเดียวกันมีเป็นเครื่องมือด้วย: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app และ environment_stop_app เอเจนต์ในแซนด์บ็อกซ์เข้าถึงพอร์ตของตนโดยตรง และเข้าถึงชื่อโฮสต์ของสภาพแวดล้อมผ่านพร็อกซีของการรัน จึงควรบอกให้อ่านเอนด์พอยต์จาก environment_status แทนการเดา URL

โค้ดของ PR จากฟอร์กไม่น่าเชื่อถือ และเมื่อวางบนโฮสต์จะรันในนามผู้ใช้ระบบปฏิบัติการของเซิร์ฟเวอร์ policy.forkPrs เป็นตัวกำหนดว่าจะเกิดอะไรขึ้น:

ค่า ผล ค่าเริ่มต้นสำหรับ
rig ไฟล์ compose รันใน VM โดยไม่ถาม คำจำกัดความที่มีเฉพาะคอมโพเนนต์ compose และ task
approval การเริ่มแต่ละครั้งต้องมีผู้ดูแล คำจำกัดความอื่นทั้งหมด
deny ปฏิเสธ ไม่มี
  • seedFiles ไม่ถูกคัดลอกให้ฟอร์ก เพราะมักเป็นความลับ ไฟล์ compose ที่ผูกไฟล์เหล่านั้นจะรายงานชื่อไฟล์ที่ขาด
  • งาน provision และ archive ถูกข้าม เว้นแต่นโยบายเป็น rig ซึ่งจะรันใน VM
  • เมื่อวางบนโฮสต์ privileged, เนมสเปซของโฮสต์, การผูกซ็อกเก็ต Docker, devices และการผูกนอก worktree ของสเปซจะถูกปฏิเสธบนฟอร์ก ในสเปซที่เชื่อถือได้จะมีเพียงคำเตือน

"placement": "rig" รันคอมโพเนนต์ compose และ task ใน microVM เฉพาะ คำจำกัดความที่มีคอมโพเนนต์ process, cli หรือ app ไม่เข้าเกณฑ์ ไฟล์ compose รันโดยไม่แก้ไข ไม่มีซ็อกเก็ต Docker ของโฮสต์และไม่มีข้อมูลรับรองของผู้ปฏิบัติงาน และการเข้าถึงเครือข่ายจำกัดเฉพาะรีจิสทรีที่อิมเมจต้องใช้ worktree ถูกเมานต์แบบสด

  • เกสต์ arm64 บน Apple Silicon เกสต์เป็น arm64 อิมเมจที่มีเฉพาะ amd64 จึงรันไม่ได้
  • รีจิสทรีส่วนตัวถูกปฏิเสธ เกสต์ไม่มีข้อมูลรับรองรีจิสทรี อิมเมจบนรีจิสทรีนอกรายการสาธารณะที่รู้จักจึงถูกปฏิเสธก่อน VM บูต ที่เก็บส่วนตัวบนรีจิสทรีสาธารณะจะล้มเหลวเมื่อเกสต์ดึง
  • พื้นที่เก็บ 16 GiB ทุกอิมเมจและวอลุ่มของสแตกใช้ดิสก์ 16 GiB ร่วมกัน และเพิ่มไม่ได้
  • การบูตครั้งแรกช้า เลเยอร์อิมเมจแยกตาม VM การบูตครั้งแรกจึงดึงทุกอย่าง ริกที่หยุดแล้วยังเก็บดิสก์ไว้
  • อิมเมจฐานต้องอ่านได้ Dockerfile ที่ระบุอิมเมจฐานผ่านตัวแปรวางแผนไม่ได้ เพราะการเข้าถึงเครือข่ายถูกกำหนดตอนบูต
  • อายุการใช้งาน policy.rigTtlHours ปิด VM โดยค่าเริ่มต้นหลัง 24 ชั่วโมง

คอมโพเนนต์ cli ที่ไม่มี statusMap คาดหวังสัญญาดั้งเดิม cc-env/1 คำกริยา status พิมพ์ออบเจกต์นี้ไปยัง stdout:

{
"state": "ready",
"detail": "migrations applied, HTTP 200",
"endpoints": [
{ "role": "app", "label": "App", "url": "https://fix-login.acme.test", "primary": true },
{ "role": "postgres", "label": "Postgres", "hostPort": 49213 }
],
"services": ["server", "postgres"],
"needsRecreate": false,
"error": { "code": "post-start-failed", "message": "…", "hint": "…", "command": "…" }
}
  • state เป็น ready, starting, stopped, failed หรือ missing โดย missing นำไปสู่ create ส่วน stopped และ failed นำไปสู่ start รายงาน missing ด้วยรหัสออก 0 เพราะ status ที่ล้มเหลวนับเป็น failed
  • จำเป็นเฉพาะ state ฟิลด์ที่ไม่รู้จักถูกละเว้น และเอาต์พุตที่แยกวิเคราะห์ไม่ได้แสดงเป็นเสื่อมสภาพ โดยใช้ข้อความดิบเป็นรายละเอียด
  • URL ต้องเป็น loopback, *.localhost หรืออยู่ใต้ routing.domain มิฉะนั้นจะถูกทิ้ง
  • needsRecreate: true แสดง สร้างใหม่ ซึ่งทิ้งข้อมูล Control Center ไม่ดำเนินการเองจากค่านี้
  • คำกริยา list พิมพ์อาร์เรย์ JSON ของชื่อ หรือของออบเจกต์ที่มี name

รหัสออกใช้กับทุกคำกริยา:

รหัส ความหมาย
0 ตกลง
3 ต้องมีคำตอบที่เทอร์มินัล เช่นรหัสผ่าน sudo คำกริยาที่อยู่ใน interactive จะรันซ้ำบนแท็บเทอร์มินัลสำหรับบุคคลที่กด Start มิฉะนั้น รันในเทอร์มินัล จะเปิดเทอร์มินัลของสเปซโดยพิมพ์ command ของเครื่องมือไว้แต่ยังไม่รัน จากนั้น ลองใหม่ ลองอีกครั้ง Control Center ไม่รัน sudo และไม่ตอบพรอมต์
4 ต้องลงชื่อเข้าใช้ command ของเครื่องมือระบุวิธีไว้
5 สิ่งที่มันพึ่งพาไม่พร้อมใช้งาน เช่นรันไทม์ของคอนเทนเนอร์ที่ไม่ได้รันอยู่
อื่น ๆ ล้มเหลว

รหัส 3, 4 และ 5 ไม่ใช่ความล้มเหลว สภาพแวดล้อมจะแสดง ต้องดำเนินการ และรอ และการเริ่มครั้งถัดไปจะทำต่อจากจุดที่หยุดไว้ งานที่ออกด้วยรหัสใดรหัสหนึ่งในนี้มีความหมายเดียวกัน

ความคืบหน้าส่งไปยัง stderr เป็น JSON คั่นด้วยบรรทัดใหม่:

{"type":"step","id":"images","label":"Pull images","state":"running"}
{"type":"log","stream":"stdout","line":"postgres Pulled"}
{"type":"step","id":"images","label":"Pulled 4 images","state":"done"}
{"type":"note","level":"warn","message":"Hosts entries stayed behind after destroy"}
{"type":"error","code":"hosts-missing","message":"Add the hosts entry","hint":"Needs sudo","command":"sudo acme hosts add fix-login"}

ขณะที่สภาพแวดล้อมกำลังเริ่มทำงาน แผงจะแสดงรายการส่วนประกอบที่การเริ่มทำงานต้องผ่าน แต่ละรายการมีสปินเนอร์ เครื่องหมายถูก หรือกากบาท บรรทัด step บอกว่าเครื่องมือกำลังทำอะไรอยู่ และ label ของมันจะแสดงใต้แถวของเครื่องมือนั้นเอง ขั้นตอนไม่เคยเพิ่มแถว state ของขั้นตอนคือ pending, running, done หรือ failed และขั้นตอนที่ไม่มี state ถือว่ากำลังทำงาน ขั้นตอนที่รายงานซ้ำด้วย id เดิม (เป็นสตริงหรือตัวเลข หรือ label เดิมเมื่อไม่มี id) จะแทนที่สิ่งที่รายงานไว้ก่อนหน้า ดังนั้นเครื่องมือที่มีสปินเนอร์เดียวสามารถคง id เดิมและเปลี่ยน label ได้ เมื่อไม่มี id ขั้นตอนจะเรียงต่อกัน โดยขั้นตอนใหม่จะจบขั้นตอนก่อนหน้า เมื่อคำสั่งออก ขั้นตอนที่ยังทำงานอยู่จะจบในแบบเดียวกับคำสั่ง

บรรทัด log มีเอาต์พุตหนึ่งบรรทัดที่เครื่องมือห่อด้วย JSON และอ่านเป็นเอาต์พุตข้อความธรรมดา บรรทัด note จะไปที่เอาต์พุตของการรัน และบรรทัดที่มี "level": "warn" จะคงอยู่บนสภาพแวดล้อมในฐานะคำเตือนด้วย บรรทัดสุดท้ายชนิด error กลายเป็นข้อผิดพลาดแบบมีโครงสร้าง โดยเสนอ command ให้คัดลอก และแสดง 12 บรรทัดสุดท้ายของเอาต์พุตไว้ใต้ message หากไม่มี Control Center จะแสดง stderr 20 บรรทัดสุดท้าย สิ่งที่ไม่ใช่ JSON คือเอาต์พุตบันทึกธรรมดา