ใช้งาน Cline ใน Production: ตั้งค่าเซสชันและกู้คืนอย่างปลอดภัย
คู่มือเชิงปฏิบัติสำหรับตั้งค่าเซสชัน ClineCore แยกการตั้งค่า runtime ออกจากการกำหนดค่า provider และออกแบบกฎการลองใหม่และการกู้คืนอย่างปลอดภัย
สรุป · TL;DR
ClineCore แยกตัวเลือก runtime เช่น โหมด backend ความสามารถ นโยบายเครื่องมือ และระบบอัตโนมัติ ออกจาก provider และ model ที่กำหนดให้แต่ละเซสชัน คู่มือนี้แสดงวิธีแยกการตั้งค่าเหล่านี้ให้ชัดเจน และออกแบบการกู้คืนโดยอาศัย session ID กับสถานะที่บันทึกไว้ แทนการสั่งให้ทำงานซ้ำโดยไม่ตรวจสอบ
ประเด็นสำคัญ
- แยกการตัดสินใจเรื่อง runtime สิทธิ์เครื่องมือ และการกำหนดค่า provider/model ออกจากกัน
- ใช้ session ID และข้อความที่บันทึกไว้เพื่อตรวจสอบข้อผิดพลาดก่อนลองใหม่
- มองว่าการลองใหม่อาจทำให้เกิดผลข้างเคียงซ้ำได้ และกำหนดจุดตรวจสอบกับกฎการกู้คืนให้เหมาะกับเวิร์กโฟลว์
- เอกสารอ้างอิง API อธิบายการทำงานกับเซสชัน แต่ไม่ได้ระบุความหมายของการลองใหม่ รูปแบบ checkpoint หรือการรับประกันความเข้ากันได้กับ provider
ในหน้านี้ (9)
ClineCore ช่วยให้แอปพลิเคชันควบคุมการสร้างเซสชัน การเลือก runtime สิทธิ์เครื่องมือ และประวัติเซสชันได้ สำหรับการใช้งานเวิร์กโฟลว์ใน production การตัดสินใจสำคัญไม่ใช่แค่ว่าจะลองเรียกที่ล้มเหลวอีกครั้งหรือไม่ แต่คือจะตรวจสอบอย่างไรว่ามีอะไรเกิดขึ้นไปแล้วบ้างก่อนสั่งให้ทำงานซ้ำ
การกำหนดค่าด้านล่างเป็นตัวอย่างประกอบ ไม่ใช่สูตรการติดตั้งใช้งานที่ผ่านการทดสอบแล้ว เอกสารอ้างอิง ClineCore API อธิบายตัวเลือกและเมธอดที่กล่าวถึงในที่นี้ โปรดตรวจสอบ SDK เวอร์ชันที่คุณติดตั้งเพื่อดูชนิดข้อมูลและพฤติกรรมที่แน่นอน
แยกการตั้งค่า runtime ออกจากการตั้งค่า model
การแบ่งขอบเขตการกำหนดค่าที่ใช้งานได้ดีมีสามส่วน:
- Runtime: การเลือก backend, ข้อมูลระบุตัวตนของ client และการตั้งค่าการเชื่อมต่อ remote หรือ hub (ถ้ามี)
- นโยบายการทำงาน: นโยบายเครื่องมือ ความสามารถ และการเปิดใช้ API สำหรับระบบอัตโนมัติ
- การกำหนดค่า model ของเซสชัน: provider ID, model ID, ข้อมูลรับรอง, พาธ workspace และเครื่องมือที่พร้อมใช้งานสำหรับเซสชันนั้น
การแยกเช่นนี้ช่วยให้จัดการนโยบาย runtime ได้ง่ายขึ้น โดยไม่ต้องผูกกับการเปลี่ยน model แต่ไม่ได้ทำให้ฟิลด์เฉพาะของ provider ใช้แทนกันได้: providerId, modelId และ apiKey ยังคงต้องถูกต้องสำหรับ provider ที่เลือก เอกสารอ้างอิง API ไม่ได้รับรองความเข้ากันได้กับ provider หรือ endpoint ทุกราย
สร้าง runtime และเริ่มเซสชัน
ข้อกำหนดเบื้องต้น: ติดตั้ง Cline SDK เวอร์ชันที่ตั้งใจจะนำไปใช้งาน ส่งข้อมูลรับรองผ่านแนวทางจัดการความลับของแอปพลิเคชัน และกำหนดว่า agent ใช้เครื่องมือใดได้บ้าง อย่าใส่ข้อมูลรับรองไว้ใน log หรือ metadata ของเซสชัน
import { ClineCore } from "@cline/sdk"
const cline = await ClineCore.create({
clientName: "repo-maintenance-worker",
backendMode: "auto",
toolPolicies: {},
automation: false,
})
const session = await cline.start({
prompt: "Inspect the repository and report failing tests. Do not modify files.",
source: "scheduled-check",
interactive: false,
sessionMetadata: { jobId: "job-123" },
config: {
providerId: "anthropic",
modelId: "claude-sonnet-4-6",
apiKey: process.env.ANTHROPIC_API_KEY,
systemPrompt: "Follow the task scope and report actions taken.",
cwd: process.cwd(),
workspaceRoot: process.cwd(),
enableTools: true,
enableSpawnAgent: false,
enableAgentTeams: false,
},
})
console.log(session.sessionId)
ค่า provider และ model ด้านบนยกตัวอย่างตามเอกสารอ้างอิง API ไม่ใช่คำแนะนำหรือการรับรองความเข้ากันได้กับ provider นอกเหนือจากตัวอย่างดังกล่าว เอกสารระบุค่า backendMode ได้แก่ auto, local, hub และ remote รวมถึงการตั้งค่า hub และ remote ที่เป็นตัวเลือก แต่ไม่ได้ระบุว่าโหมดใดเหมาะที่สุดสำหรับการติดตั้งใช้งานแบบใดแบบหนึ่ง ให้เลือกอย่างตั้งใจ จากนั้นตรวจสอบการเชื่อมต่อและสิทธิ์ในสภาพแวดล้อมของคุณ
ออบเจ็กต์ toolPolicies ที่ว่างเปล่าไม่ถือเป็นนโยบายความปลอดภัย ให้กำหนดค่าเริ่มต้นและนโยบายรายเซสชันอย่างชัดเจนตามชนิดนโยบายที่ SDK เวอร์ชันที่ติดตั้งรองรับ ใช้ capabilities เมื่อ client จัดเตรียมตัวดำเนินการเครื่องมือหรือ callback สำหรับการอนุมัติ และทดสอบว่าการกระทำที่ถูกจำกัดถูกปฏิเสธจริง
ออกแบบกฎการลองใหม่โดยอิงสถานะเซสชัน
ข้อผิดพลาดของเครือข่ายหรือ worker หมดเวลาไม่ได้ยืนยันว่า agent หยุดก่อนทำงานเสร็จ การส่ง prompt เดิมซ้ำอาจทำให้เกิดการแก้ไข การเรียกภายนอก หรือผลข้างเคียงอื่นซ้ำ เอกสารอ้างอิง API ระบุ get, readMessages, getAccumulatedUsage, abort, stop และ restore แต่ไม่ได้ระบุการลองใหม่อัตโนมัติ การทำงานแบบ exactly-once หรือเนื้อหาของ checkpoint
ลำดับการปฏิบัติงานที่ปลอดภัยกว่ามีดังนี้:
- บันทึก session ID ทันที จัดเก็บไว้กับ job identifier เพื่อให้ worker ที่เริ่มทำงานใหม่ค้นหาเซสชันเดิมได้
- จำแนกประเภทข้อผิดพลาด แยกความล้มเหลวที่ยืนยันแล้วว่าเป็นสถานะสิ้นสุดออกจาก timeout หรือการเชื่อมต่อขาดหาย ซึ่งยังไม่แน่ชัดว่างานเสร็จหรือไม่
- ตรวจสอบก่อนส่งคำขอซ้ำ ใช้
getและreadMessagesเพื่อตรวจสอบ metadata ของเซสชันและข้อความที่บันทึกไว้ หากเกี่ยวข้อง ให้ตรวจสอบ usage ที่สะสมไว้ โดยใช้เป็นเบาะแสในการปฏิบัติงาน ไม่ใช่หลักฐานยืนยันว่าการกระทำใดเสร็จสิ้นแล้ว - เลือกวิธีกู้คืนอย่างรอบคอบ หากเซสชันยังทำงานอยู่ ให้ตัดสินใจว่าจะรอ ยกเลิกด้วย
abortหรือหยุดด้วยstopหากต้องการให้งานดำเนินต่อsendรองรับ session ID และ prompt ติดตามผล หากมี checkpoint ที่ใช้งานได้เหมาะสม API มีrestoreให้เรียกใช้ โปรดดูเอกสาร SDK เพื่อทำความเข้าใจอินพุตที่ต้องใช้และความหมายของเมธอด - ทำให้การกระทำที่มีผลข้างเคียงทำซ้ำได้อย่างปลอดภัย สำหรับการกระทำนอกสถานะเซสชันของ agent ให้ใช้ idempotency key ระดับแอปพลิเคชัน การกำจัดรายการซ้ำ หรือขั้นตอนอนุมัติโดยมนุษย์เมื่อเหมาะสม
หลีกเลี่ยงการครอบ start ด้วยลูปลองใหม่แบบไม่มีเงื่อนไข หากคำขอเริ่มต้นอาจสร้างเซสชันไปแล้วก่อนที่ผู้เรียกจะสูญเสียการตอบกลับ การเรียก start อีกครั้งอาจสร้างงานแยกต่างหาก เอกสารอ้างอิง API ไม่ได้ระบุ idempotency key สำหรับ start จึงไม่ควรสมมติว่ามี
แก้ไขปัญหา production ที่พบบ่อย
เซสชันเริ่มด้วย runtime ไม่ตรงตามที่ต้องการ
บันทึกโหมด backend ที่เลือกและตัวระบุเซสชันที่ไม่ใช่ข้อมูลลับ ตรวจสอบตัวเลือก backendMode, hub และ remote ให้สอดคล้องกับสภาพแวดล้อมที่ worker ทำงาน เอกสารอธิบายตัวเลือกเหล่านี้ว่าใช้เลือก runtime แต่ไม่ได้ระบุพฤติกรรม failover อัตโนมัติ ให้ตรวจสอบว่า auto ทำงานอย่างไรใน SDK เวอร์ชันของคุณ แทนการพึ่งพาพฤติกรรม fallback ที่คาดเดาเอาเอง
เครื่องมือใช้งานไม่ได้หรือได้รับอนุญาตโดยไม่คาดคิด
ตรวจสอบทั้ง config ของเซสชัน และ toolPolicies หรือ capabilities ที่เกี่ยวข้อง ทั้งค่าเริ่มต้นและรายเซสชัน เอกสารระบุว่าสิ่งเหล่านี้ใช้ควบคุมนโยบายเครื่องมือ รวมถึงตัวดำเนินการและการอนุมัติที่ client เป็นผู้จัดการ สรุป API ที่ให้มาไม่ได้ระบุรายละเอียดลำดับความสำคัญของนโยบาย จึงควรยืนยันลำดับดังกล่าวจากเอกสาร SDK ที่ติดตั้ง และทดสอบทั้งกรณีที่อนุญาตและปฏิเสธ
worker ขาดการเชื่อมต่อระหว่างทำงาน
จัดเก็บ session ID และ job ID ไว้ในสถานะแอปพลิเคชันที่คงทน เมื่อเริ่มทำงานใหม่ ให้ตรวจสอบเซสชันเดิมก่อนตัดสินใจว่าจะทำต่อด้วย send หยุดเซสชัน หรือกู้คืนจาก checkpoint อย่าสรุปว่างานเสร็จแล้วเพียงเพราะไม่มีการตอบกลับ
การกำหนดค่า provider หรือ model ล้มเหลว
ตรวจสอบ provider ID, model ID, ข้อมูลรับรอง และข้อกำหนดของ endpoint กับเอกสารของ provider และ Cline สำหรับการตั้งค่าที่เลือก การอ้างอิง ClineCore แสดงรูปแบบการกำหนดค่า provider/model แต่ไม่ได้รับรองว่า endpoint ที่เข้ากันได้กับ OpenAI ทั่วไปหรือพารามิเตอร์เฉพาะ provider จะใช้งานได้โดยไม่มีการเปลี่ยนแปลง
รายการตรวจสอบก่อนใช้งาน Production
- จัดเก็บ session ID อย่างคงทน และอย่าใส่ข้อมูลลับไว้ใน log หรือ metadata
- กำหนดสิทธิ์เครื่องมืออย่างชัดเจน และทดสอบทั้งเส้นทางการอนุมัติและการปฏิเสธ
- แยกการดำเนินการที่ล้มเหลวออกจากการดำเนินการที่ยังไม่ทราบผลลัพธ์
- ตรวจสอบประวัติเซสชันก่อนส่งงานซ้ำ
- ทำให้ผลข้างเคียงภายนอกมี idempotency หรือกำหนดให้ต้องได้รับอนุมัติก่อนเล่นซ้ำ
- ตรวจสอบพฤติกรรมของ backend และ provider ในสภาพแวดล้อม deployment จริง
- ปล่อยทรัพยากร runtime ระหว่างการปิดระบบอย่างเป็นระเบียบ โดยทำตามวงจรการใช้งานที่เอกสาร SDK ระบุ
หลักปฏิบัติที่สำคัญนั้นเรียบง่าย: ลองใหม่ก็ต่อเมื่อรู้แล้วว่ากำลังลองอะไร ClineCore มี API สำหรับเซสชันและการกู้คืน แต่การทำงานอย่างปลอดภัยใน production ยังขึ้นอยู่กับการติดตามงานที่คงทนของแอปพลิเคชัน การออกแบบสิทธิ์ และการจัดการผลข้างเคียงที่อาจเกิดซ้ำ
คำถามที่พบบ่อย
การตั้งค่า ClineCore ใดบ้างที่ไม่ขึ้นกับ model provider?
ตัวเลือก runtime เช่น `clientName`, `backendMode`, การตั้งค่า hub หรือ remote (ถ้ามี), capabilities, tool policies และ automation แยกจากฟิลด์ provider และ model ของเซสชัน ควรตรวจสอบพฤติกรรมของตัวเลือกที่แน่นอนกับ SDK เวอร์ชันที่ใช้งาน
ควรลองเรียก ClineCore.start อีกครั้งหลัง timeout หรือไม่?
อย่าลองใหม่โดยไม่ตรวจสอบ timeout ไม่ได้บอกว่ามีการสร้างเซสชันแล้วหรือไม่ ให้บันทึก session ID เมื่อมี และตรวจสอบเซสชันที่มีอยู่ก่อนเริ่มงานใหม่ เอกสารอ้างอิง API ที่ให้มาไม่ได้ระบุ idempotency key สำหรับ `start`
ClineCore กู้คืนเซสชันที่ล้มเหลวได้หรือไม่?
เอกสารอ้างอิง API ระบุเมธอด `restore` แต่สรุปที่ให้มาไม่ได้ระบุอินพุตที่ต้องใช้หรือความหมายของ checkpoint โปรดดูเอกสาร SDK ที่ติดตั้งก่อนออกแบบการกู้คืนโดยอาศัยเมธอดนี้
การกำหนดค่านี้ใช้ได้กับ provider ที่เข้ากันได้กับ OpenAI ทุกรายหรือไม่?
เอกสารอ้างอิง ClineCore ที่อ้างถึงไม่ได้ยืนยันเรื่องนี้ ความเข้ากันได้กับ provider และพารามิเตอร์ที่รองรับขึ้นอยู่กับการรองรับ endpoint และการกำหนดค่า provider ที่เลือกตามเอกสาร โปรดตรวจสอบแทนการสมมติว่าสามารถใช้แทนกันได้
บทความที่เกี่ยวข้อง
Guides
ตั้งค่า Cline เพื่อวิเคราะห์เหตุขัดข้องของ API
ตั้งค่าเซสชัน Cline SDK เพื่อวิเคราะห์เหตุขัดข้องของ API เลือกการตั้งค่ารันไทม์ที่ไม่ขึ้นกับผู้ให้บริการ และแก้ปัญหาจากสัญญาณความผิดปกติที่สังเกตได้
Guides
ประเมินโมเดล Hugging Face เพื่อการตัดสินใจ Retry และ Recovery ที่เชื่อถือได้
สร้างการประเมินเฉพาะงานที่ทำซ้ำได้ เพื่อเปรียบเทียบโมเดล Hugging Face สำหรับการตัดสินใจ retry และ recovery ในระบบ production
Guides
กำหนดค่า ClineCore สำหรับเซสชันเขียนโค้ดที่คำนึงถึงความเป็นส่วนตัว
คู่มือเชิงปฏิบัติสำหรับกำหนดค่าเซสชัน ClineCore จำกัดการเปิดเผยข้อมูลที่ละเอียดอ่อน และแก้ไขปัญหาการตั้งค่าที่พบบ่อย
Guides
ตั้งค่า Provider ที่เข้ากันได้กับ OpenAI ใน Cline สำหรับถามตอบเอกสารพร้อมระบุแหล่งอ้างอิง
ตั้งค่า Provider ที่เข้ากันได้กับ OpenAI ผ่าน Cline SDK แล้วสร้างเวิร์กโฟลว์ถามตอบเอกสารที่ส่งคืนข้อมูลอ้างอิงซึ่งตรวจสอบได้