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

โหมดเอาต์พุต

codeknit แยกการตัดสินใจสองอย่างออกจากกัน: สถานที่ที่เอาต์พุตจะถูกส่งไป (โหมดเอาต์พุต) และวิธีการเข้ารหัส (รูปแบบเอาต์พุต) หน้านี้อธิบายว่าทำไมแต่ละตัวเลือกจึงมีอยู่ ค่าใช้จ่ายที่เกี่ยวข้อง และเวลาที่เหมาะสม สำหรับไวยากรณ์ .skt ดูที่ คู่มืออ้างอิงรูปแบบเอาต์พุต สำหรับคำสั่ง ดูที่ คู่มือคำสั่ง parse

แฟล็ก --output-mode เลือกโหมดหนึ่งจากสามโหมด: directory-flat, directory-tree หรือ inline แฟล็ก --format เลือกรูปแบบ skt (ค่าเริ่มต้น) หรือ json สามารถรวมโหมดใดก็ได้กับรูปแบบใดก็ได้

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

directory-flat เป็นค่าเริ่มต้น จะเขียนไฟล์ชิ้นส่วนที่มีหมายเลข map_001.skt, map_002.skt และต่อไปเรื่อยๆ ลงใน ./skeleton/ เว้นแต่คุณจะระบุไดเรกทอรีเอาต์พุตอื่น

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

วิธีการแบ่ง codeknit รักษาบล็อกของแต่ละไฟล์ต้นฉบับให้สมบูรณ์และเริ่มชิ้นส่วนใหม่ระหว่างบล็อกเมื่อชิ้นส่วนถึงประมาณ --max-lines (ค่าเริ่มต้น 500) ขีดจำกัดนี้เป็นเป้าหมาย ไม่ใช่ขอบเขตที่เข้มงวด: ไฟล์ต้นฉบับหนึ่งที่มีบล็อกขนาดใหญ่มากอาจสร้างชิ้นส่วนที่ยาวกว่า 500 บรรทัด การรักษาบล็อกให้สมบูรณ์หมายความว่าสัญลักษณ์จะไม่ถูกแยกออกจากพี่น้องในไฟล์เดียวกัน

ข้อแลกเปลี่ยน ชิ้นส่วนไม่ได้จัดระเบียบตามเส้นทางต้นฉบับ หากต้องการค้นหาโครงสร้างโค้ดของไฟล์หนึ่ง คุณต้องค้นหาชิ้นส่วนสำหรับส่วนหัว ## source-path หากคุณมักจะค้นหาไฟล์เฉพาะ directory-tree จะเหมาะสมกว่า

การย่อขนาด ด้วย --minify พจนานุกรมจะถูกเขียนไปยัง dict.skt ข้างชิ้นส่วน ดู การย่อขนาด

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

โหมดไดเรกทอรีไม่ได้เขียนลงในไดเรกทอรีเอาต์พุตขณะดำเนินการ 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 จึงยังคงแยกแยะได้ สำหรับโปรเจ็กต์ขนาดเล็ก การประหยัดมีน้อยและขั้นตอนเพิ่มเติมมักไม่คุ้มค่า สำหรับโปรเจ็กต์ขนาดใหญ่ การประหยัดโทเค็นอาจมีนัยสำคัญ