โหมดเอาต์พุต
codeknit แยกการตัดสินใจสองอย่างออกจากกัน: สถานที่ที่เอาต์พุตจะถูกส่งไป (โหมดเอาต์พุต) และวิธีการเข้ารหัส (รูปแบบเอาต์พุต) หน้านี้อธิบายว่าทำไมแต่ละตัวเลือกจึงมีอยู่ ค่าใช้จ่ายที่เกี่ยวข้อง และเวลาที่เหมาะสม สำหรับไวยากรณ์ .skt ดูที่ คู่มืออ้างอิงรูปแบบเอาต์พุต สำหรับคำสั่ง ดูที่ คู่มือคำสั่ง parse
การเลือกสองอย่างที่เป็นอิสระจากกัน
หัวข้อที่มีชื่อว่า “การเลือกสองอย่างที่เป็นอิสระจากกัน”แฟล็ก --output-mode เลือกโหมดหนึ่งจากสามโหมด: directory-flat, directory-tree หรือ inline แฟล็ก --format เลือกรูปแบบ skt (ค่าเริ่มต้น) หรือ json สามารถรวมโหมดใดก็ได้กับรูปแบบใดก็ได้
การเลือกทั้งสองอย่างนี้แยกจากกันเพราะตอบคำถามที่แตกต่างกัน โหมดจะตัดสินใจว่าการแบ่งและตำแหน่งของเอาต์พุตบนดิสก์จะเป็นอย่างไร ซึ่งมีความสำคัญต่อบุคคลหรือ LLM ที่อ่าน ส่วนรูปแบบจะตัดสินใจว่าผู้ใช้จะเป็นใคร: LLM หรือผู้อ่านที่เป็นมนุษย์ หรือสคริปต์
directory-flat
หัวข้อที่มีชื่อว่า “directory-flat”directory-flat เป็นค่าเริ่มต้น จะเขียนไฟล์ชิ้นส่วนที่มีหมายเลข map_001.skt, map_002.skt และต่อไปเรื่อยๆ ลงใน ./skeleton/ เว้นแต่คุณจะระบุไดเรกทอรีเอาต์พุตอื่น
เหตุผลที่มีอยู่ โค้ดเบสขนาดใหญ่สร้างโครงสร้างโค้ดมากกว่าที่จะใส่ในหน้าต่างบริบทเดียวได้ การแบ่งชิ้นส่วนช่วยให้ผู้อ่านเปิดเฉพาะไฟล์ที่ต้องการเท่านั้นแทนที่จะโหลดทั้งหมด
วิธีการแบ่ง codeknit รักษาบล็อกของแต่ละไฟล์ต้นฉบับให้สมบูรณ์และเริ่มชิ้นส่วนใหม่ระหว่างบล็อกเมื่อชิ้นส่วนถึงประมาณ --max-lines (ค่าเริ่มต้น 500) ขีดจำกัดนี้เป็นเป้าหมาย ไม่ใช่ขอบเขตที่เข้มงวด: ไฟล์ต้นฉบับหนึ่งที่มีบล็อกขนาดใหญ่มากอาจสร้างชิ้นส่วนที่ยาวกว่า 500 บรรทัด การรักษาบล็อกให้สมบูรณ์หมายความว่าสัญลักษณ์จะไม่ถูกแยกออกจากพี่น้องในไฟล์เดียวกัน
ข้อแลกเปลี่ยน ชิ้นส่วนไม่ได้จัดระเบียบตามเส้นทางต้นฉบับ หากต้องการค้นหาโครงสร้างโค้ดของไฟล์หนึ่ง คุณต้องค้นหาชิ้นส่วนสำหรับส่วนหัว ## source-path หากคุณมักจะค้นหาไฟล์เฉพาะ directory-tree จะเหมาะสมกว่า
การย่อขนาด ด้วย --minify พจนานุกรมจะถูกเขียนไปยัง dict.skt ข้างชิ้นส่วน ดู การย่อขนาด
directory-tree
หัวข้อที่มีชื่อว่า “directory-tree”directory-tree สะท้อนต้นไม้ต้นฉบับของคุณภายใต้ไดเรกทอรีเอาต์พุต แต่ละไฟล์ต้นฉบับจะได้รับไฟล์ .skt ที่เส้นทางที่ตรงกัน
การตั้งชื่อ codeknit เพิ่ม .skt ต่อท้ายชื่อไฟล์ต้นฉบับทั้งหมดแทนที่จะแทนที่นามสกุล src/foo.c จะกลายเป็น src/foo.c.skt และ src/foo.h จะกลายเป็น src/foo.h.skt หากไม่มีกฎนี้ ทั้งสองจะแมปไปยัง foo.skt และชนกัน เมื่อเอาต์พุตของไฟล์ถูกแบ่ง ส่วนต่างๆ จะถูกตั้งชื่อว่า foo.c_part1.skt, foo.c_part2.skt และต่อไปเรื่อยๆ เส้นทางเอาต์พุตที่ชนกัน รวมถึงการชนที่เกิดจากตัวอักษรพิมพ์ใหญ่-เล็กเท่านั้น จะล้มเหลวอย่างชัดเจนแทนที่จะเขียนทับกัน
การแบ่งแตกต่างจากโหมด flat ในโหมด tree --max-lines เป็นขีดจำกัดที่เข้มงวดสำหรับแต่ละชิ้นส่วนต้นฉบับ โดยมีค่าต่ำสุดที่ 3 แต่ละชิ้นส่วนสัญลักษณ์จะทำซ้ำส่วนหัว [symbols] และ ## source-path เพื่อให้สามารถอ่านได้โดยลำพัง ชิ้นส่วนที่มีเฉพาะ [edges] จะมี [edges] ขีดจำกัดนี้ใช้กับชิ้นส่วนต้นฉบับ ไม่ใช่กับไฟล์เสริม เช่น dict.skt และ warnings.skt
ข้อแลกเปลี่ยน เอาต์พุตแบบ tree ง่ายต่อการนำทางควบคู่ไปกับต้นฉบับ แต่สร้างไฟล์ขนาดเล็กจำนวนมาก โปรเจ็กต์ขนาดใหญ่อาจสร้างไฟล์เหล่านี้ได้หลายพันไฟล์ และผู้อ่านที่ต้องการภาพรวมกว้างๆ จะต้องเปิดไฟล์จำนวนมาก
inline เขียนทุกอย่างไปยัง stdout ไม่สร้างไดเรกทอรีเอาต์พุตหรือพื้นที่จัดเตรียม
เหตุผลที่มีอยู่ เหมาะสำหรับสองกรณี: ตรวจสอบไฟล์เดียวอย่างรวดเร็ว และส่งเอาต์พุตไปยังเครื่องมืออื่น เป็นโหมดเดียวที่ไม่มีการเขียนลงดิสก์
ข้อแลกเปลี่ยน ไม่มีการแบ่งชิ้นส่วน ผลลัพธ์ทั้งหมดจะปรากฏในเทอร์มินัลหรือในบริบทของผู้ใช้พร้อมกัน ดังนั้นจึงทำให้ผู้อ่านล้นหลามเมื่อมีมากกว่าสองสามไฟล์ ถือว่าเหมาะสมสำหรับไฟล์เดียวหรือโปรเจ็กต์ขนาดเล็กมาก ประมาณไม่เกินห้าไฟล์ เนื่องจาก stdout ไม่สามารถย้อนกลับได้ ผู้ใช้ที่ล้มเหลวอาจเห็นเอาต์พุตบางส่วน โหมดไดเรกทอรีไม่มีปัญหานี้
รูปแบบเอาต์พุต
หัวข้อที่มีชื่อว่า “รูปแบบเอาต์พุต”| รูปแบบ | เหมาะสำหรับ | เอาต์พุต |
|---|---|---|
skt |
บริบท LLM และการตรวจสอบโดยมนุษย์ | ไฟล์ .skt หรือ stdout |
json |
สคริปต์และการผสานรวมแบบมีโครงสร้าง | codeknit.json ในโหมดไดเรกทอรี หรือ stdout ในโหมด inline |
skt มีขนาดกะทัดรัดและเน้นบรรทัด แต่ละสัญลักษณ์อยู่ในบรรทัดเดียวทางกายภาพ โดยมีการขึ้นบรรทัดใหม่ในลายเซ็นถูกแทนที่ด้วยอักขระหลีก ดังนั้นผู้อ่านสามารถโหลดบางส่วนของเอาต์พุตได้โดยไม่ทำลายโครงสร้าง นั่นคือเหตุผลที่การแบ่งชิ้นส่วนใช้งานได้กับ .skt
json มีไว้สำหรับผู้ใช้ที่ต้องการฟิลด์ที่มีโครงสร้างมากกว่าข้อความที่จะอ่าน เป็นเอกสารเดียวที่มี files, symbols และเมื่อรวม [edges] จะมี edges ด้วย เนื่องจากเป็นเอกสารเดียว จึงไม่ถูกแบ่งตามจำนวนบรรทัด ในโหมดไดเรกทอรี --max-lines จึงไม่มีผลกับ JSON และโปรเจ็กต์ขนาดใหญ่จะสร้าง codeknit.json ขนาดใหญ่หนึ่งไฟล์
ตัวอย่างขนาดกะทัดรัด:
{ "files": ["app.go"], "symbols": [ {"id": "app.go::User", "short_id": "S1", "name": "User", "file": "app.go", "category": "type", "kind": "struct", "signature": "type User struct", "span": [3, 3]}, {"id": "app.go::Save", "short_id": "S2", "name": "Save", "file": "app.go", "category": "callable", "kind": "function", "signature": "Save(u: S1)", "span": [5, 5]} ], "edges": [ {"from": "app.go::Save", "from_short": "S2", "to": "app.go::User", "to_short": "S1", "kind": "references"} ]}การเลือกโหมด
หัวข้อที่มีชื่อว่า “การเลือกโหมด”| โหมด | เหมาะสำหรับ | เอาต์พุต |
|---|---|---|
directory-flat |
โปรเจ็กต์ส่วนใหญ่ (ค่าเริ่มต้น) | ./skeleton/map_001.skt, map_002.skt, … |
directory-tree |
การนำทางควบคู่ไปกับต้นฉบับ | ./skeleton/<mirrored path>.skt |
inline |
ไฟล์เดียว การส่งผ่าน | stdout |
กฎทั่วไป:
- เมื่อไม่แน่ใจ ให้ใช้
directory-flatซึ่งเป็นค่าเริ่มต้น - ไฟล์เดียว:
inlineก็ใช้ได้ - มากกว่าสองสามไฟล์: ใช้
directory-flatหรือdirectory-tree - โค้ดเบสขนาดใหญ่: เพิ่ม
--minify - การรันซ้ำในไดเรกทอรีเดียวกัน: เพิ่ม
--clean
การจัดเตรียม การรันซ้ำ และ --clean
หัวข้อที่มีชื่อว่า “การจัดเตรียม การรันซ้ำ และ --clean”โหมดไดเรกทอรีไม่ได้เขียนลงในไดเรกทอรีเอาต์พุตขณะดำเนินการ codeknit สร้างเอาต์พุตในไดเรกทอรีจัดเตรียมที่อยู่ข้างเคียงและเผยแพร่เฉพาะหลังจากการสร้างสำเร็จ การรันที่ล้มเหลวจึงไม่ทิ้งเอาต์พุตก่อนหน้าของคุณไว้
โดยค่าเริ่มต้น codeknit ปฏิเสธการเขียนเมื่อมีเอาต์พุตที่สร้างขึ้นสำหรับรูปแบบที่เลือกอยู่แล้ว เหตุผลคือ ID สัญลักษณ์ (S1, S2, …) สามารถเปลี่ยนแปลงได้ทุกครั้งที่การดึงข้อมูลเปลี่ยนแปลง การผสมชิ้นส่วนจากการรันที่ต่างกันจะทำให้ [edges] ชี้ไปยังสัญลักษณ์ที่ผิด --clean เลือกที่จะแทนที่: หลังจากการสร้างสำเร็จ ไฟล์ .skt ที่ล้าสมัย (ในโหมด SKT) หรือ codeknit.json (ในโหมด JSON) จะถูกแทนที่ รายการที่ไม่เกี่ยวข้องในไดเรกทอรีจะถูกเก็บรักษาไว้ หากรายการใดชนกับเส้นทางที่สร้างขึ้น การรันจะล้มเหลวแทนที่จะเขียนทับ
การเผยแพร่จะใช้ล็อกเฉพาะไดเรกทอรี สำรองเอาต์พุตก่อนหน้า และกู้คืนหากการแทนที่ล้มเหลว หากกระบวนการถูกขัดจังหวะระหว่างการเปลี่ยนชื่อไดเรกทอรีสองครั้ง การรันครั้งถัดไปจะกู้คืนข้อมูลสำรองก่อนสร้างอะไรเลย สิ่งนี้ช่วยกู้คืนจากความล้มเหลวของกระบวนการ แต่ไม่ทำให้การอัปเดตไดเรกทอรีเป็นไปในทันที: มีช่วงเวลาสั้นๆ ระหว่างการเปลี่ยนชื่อ ดังนั้นผู้อ่านที่ต้องการการเข้าถึงอย่างต่อเนื่องควรประสานงานกับการสร้าง นอกจากนี้ยังไม่ป้องกันความล้มเหลวของที่จัดเก็บหรือไฟฟ้าดับ
อย่าเลือกไดเรกทอรีต้นฉบับหรือบรรพบุรุษของมันเป็นไดเรกทอรีเอาต์พุต สำหรับการรับประกันการเผยแพร่ทั้งหมด ดูที่ คู่มืออ้างอิงความน่าเชื่อถือของการวิเคราะห์
การย่อขนาด
หัวข้อที่มีชื่อว่า “การย่อขนาด”--minify ใช้การบีบอัดแบบใช้พจนานุกรม codeknit แทนที่โทเค็นที่ซ้ำกัน เช่น callable/method หรือ exported ด้วยรหัสสั้น (d0, d1, …) การแมปจะถูกเก็บไว้ในส่วน [dict] ซึ่งในโหมดไดเรกทอรีจะเป็นไฟล์ dict.skt
การประหยัดมาจากการซ้ำซ้อน สัญลักษณ์ส่วนใหญ่มีหมวดหมู่ ประเภท และคุณสมบัติเดียวกัน ดังนั้นโค้ดเบสขนาดใหญ่จะซ้ำสตริงเหล่านี้หลายพันครั้ง ต้นทุนคือการอ้อม: ผู้อ่านต้องขยายรหัสโดยใช้พจนานุกรม และชิ้นส่วนเดียวไม่สามารถใช้งานได้โดยลำพัง พจนานุกรมเป็นเอาต์พุตเสริมแยกต่างหาก จึงไม่ถูกนับรวมกับ --max-lines
เอาต์พุตที่ถูกย่อขนาดจะเข้ารหัสประเภทความสัมพันธ์แต่เก็บเครื่องหมายการแก้ไขให้อ่านได้ ดังนั้น [edges] unresolved และ ambiguous จึงยังคงแยกแยะได้ สำหรับโปรเจ็กต์ขนาดเล็ก การประหยัดมีน้อยและขั้นตอนเพิ่มเติมมักไม่คุ้มค่า สำหรับโปรเจ็กต์ขนาดใหญ่ การประหยัดโทเค็นอาจมีนัยสำคัญ
หน้าที่เกี่ยวข้อง
หัวข้อที่มีชื่อว่า “หน้าที่เกี่ยวข้อง”- คู่มือคำสั่ง parse: คำสั่งสำหรับแต่ละโหมด
- คู่มืออ้างอิงรูปแบบเอาต์พุต: ไวยากรณ์
.sktและ JSON - คู่มืออ้างอิงแฟล็ก CLI: ทุกแฟล็กและค่าเริ่มต้น
- คู่มืออ้างอิงความน่าเชื่อถือของการวิเคราะห์: การตั้งชื่อเอาต์พุตและการรับประกันการเผยแพร่