การแก้ไขปัญหา

วิธีแก้ปัญหาที่เฉพาะเจาะจงสำหรับปัญหาเฉพาะเจาะจง แต่ละรายการจะระบุอาการ อธิบายสาเหตุที่เป็นไปได้ในหนึ่งประโยค และให้วิธีแก้ไขให้คุณ หากคุณไม่เห็นปัญหาของคุณที่นี่ คำถามที่พบบ่อย (FAQ) อาจช่วยได้ และ Discord จะช่วยได้อย่างแน่นอน

การติดตั้งและการกำหนดค่า

openspec: command not found

CLI ไม่ได้ถูกติดตั้ง หรือเชลล์ของคุณไม่พบมัน ติดตั้งไว้แบบโกลบอลแล้วตรวจสอบ:

npm install -g @fission-ai/openspec@latest
openspec --version

หากมันติดตั้งแล้วแต่ยังไม่พบ โฟลเดอร์ bin npm โกลบอลของคุณอาจไม่ได้อยู่ใน PATH ของคุณ รัน npm bin -g เพื่อดูตำแหน่งที่ไบนารีโกลบอลอยู่ และตรวจสอบว่าเส้นทางนั้นอยู่ในโปรไฟล์เชลล์ของคุณ

"Requires Node.js 20.19.0 or higher"

OpenSpec รันบน Node เวอร์ชัน 20.19.0 ขึ้นไป ตรวจสอบเวอร์ชันของคุณและอัปเกรดหากจำเป็น:

node --version

หากคุณใช้ bun เพื่อติดตั้ง OpenSpec โปรดทราบว่า OpenSpec ยังคง รัน บน Node ดังนั้นคุณจึงต้องมี Node เวอร์ชัน 20.19.0 ขึ้นไปอยู่ใน PATH ของคุณไม่ว่าอย่างไร ดูเพิ่มเติมที่ การติดตั้ง

openspec init didn't configure my AI tool

openspec init จะถามว่าต้องการกำหนดค่าเครื่องมือใดบ้าง หากคุณข้ามเครื่องมือของคุณหรือต้องการเพิ่มเครื่องมืออื่น เพียงรันมันอีกครั้ง หรือใช้แบบไม่โต้ตอบ:

openspec init --tools claude,cursor

รายการเต็มของ ID เครื่องมืออยู่ใน เครื่องมือที่รองรับ ใช้ --tools all สำหรับทั้งหมด --tools none เพื่อข้ามการกำหนดค่าเครื่องมือ

คำสั่งไม่ปรากฏขึ้น

หาก /opsx:propose (หรือเทียบเท่าของเครื่องมือของคุณ) ไม่ปรากฏขึ้นหรือไม่ทำงานอะไรเลย ตรวจสอบรายการนี้ตามลำดับ เรียงลำดับจากเร็วที่สุดไปตรวจสอบก่อน

1. คุณอาจอยู่ที่ตำแหน่งที่ไม่ถูกต้อง คำสั่งสแลชใช้ในแชทผู้ช่วย AI ของคุณ ไม่ใช่ในเทอร์มินัล หากคุณพิมพ์ /opsx:propose ลงในเชลล์ นั่นคือปัญหา ดูเพิ่มเติมที่ วิธีทำงานของคำสั่ง

2. สร้างไฟล์ใหม่ จากรากของโปรเจกต์ของคุณ:

   openspec update

   คำสั่งนี้จะเขียนไฟล์สกิลและคำสั่งใหม่สำหรับทุกเครื่องมือที่คุณกำหนดค่าไว้

3. รีสตาร์ทผู้ช่วยของคุณ เครื่องมือส่วนใหญ่จะสแกนสกิลและคำสั่งเมื่อเริ่มต้น หน้าต่างใหม่มักจะแก้ปัญหาได้

4. ตรวจสอบว่าไฟล์มีอยู่ สำหรับ Claude Code ตรวจสอบว่า .claude/skills/ มีโฟลเดอร์ openspec-* เครื่องมืออื่นใช้ไดเรกทอรีของตัวเองทั้งหมด รายชื่ออยู่ใน เครื่องมือที่รองรับ

5. ตรวจสอบว่าคุณได้กำหนดค่าโปรเจกต์นี้แล้ว สกิลจะถูกเขียนต่อโปรเจกต์ หากคุณคลอน repo หรือเปลี่ยนโฟลเดอร์ รัน openspec init (หรือ openspec update) ที่นั้น

6. ตรวจสอบว่าเครื่องมือของคุณรองรับไฟล์คำสั่ง Codex และเครื่องมืออื่นอีกเล็กน้อย (CodeArts, Kimi CLI, ForgeCode, Mistral Vibe) จะไม่สร้างไฟล์คำสั่ง opsx-* ต่อออกมา พวกเขาใช้การเรียกใช้แบบอิงสกิลแทน สำหรับ Codex ตรวจสอบ .codex/skills/openspec-* รูปแบบแตกต่างกันไปตามเครื่องมือ: ดูเพิ่มเติมที่ เครื่องมือที่รองรับ และ วิธีทำงานของคำสั่ง

การทำงานกับการเปลี่ยนแปลง

"Change not found"

คำสั่งไม่สามารถบอกได้ว่าคุณหมายถึงการเปลี่ยนแปลงชื่อใด การตั้งชื่อให้ชัดเจน หรือตรวจสอบว่ามีอะไรอยู่:

openspec list                    # ดูการเปลี่ยนแปลงที่ใช้งานอยู่
/opsx:apply add-dark-mode        # ระบุชื่อการเปลี่ยนแปลงในแชท

ตรวจสอบเพิ่มเติมว่าคุณอยู่ในไดเรกทอรีโปรเจกต์ที่ถูกต้อง

"No artifacts ready"

อาร์ติแฟคต์แต่ละชิ้นจะถูกสร้างแล้วหรือถูกบล็อกโดยรอ dependencies ดูว่าอะไรกำลังบล็อกอยู่:

openspec status --change <name>

จากนั้นสร้าง dependencies ที่หายไปก่อน จำกัดลำดับไว้: proposal เปิดใช้งาน specs และ design; specs และ design ร่วมกันจึงเปิดใช้งาน tasks

openspec validate reports warnings or errors

การตรวจสอบความถูกต้องจะตรวจสอบสเปคและการเปลี่ยนแปลงของคุณเพื่อหาปัญหาเชิงโครงสร้าง อ่านข้อความ: มันจะระบุไฟล์และปัญหา

openspec validate <name>           # ตรวจสอบความถูกต้องของรายการเดียว
openspec validate --all            # ตรวจสอบความถูกต้องทั้งหมด
openspec validate --all --strict   # การตรวจสอบที่เข้มงวดกว่า เหมาะสำหรับ CI

สาเหตุทั่วไปคือส่วนที่จำเป็นหายไป (เช่น สเปคที่ไม่มีสถานการณ์) หรือส่วนหัว delta ที่ผิดรูปแบบ แก้ไขไฟล์แล้วรันใหม่ อ้างอิง CLI อธิบายรูปแบบเอาต์พุต

The AI created incomplete or wrong artifacts

AI ไม่มีบริบทเพียงพอ มีตัวปรับแต่งเล็กน้อยช่วยได้:

• เพิ่มบริบทโปรเจกต์ใน openspec/config.yaml เพื่อให้สแต็กและข้อกำหนดของคุณถูกใส่เข้าไปในทุกคำขอ ดูเพิ่มเติมที่ การปรับแต่ง
• เพิ่ม rules: ต่ออาร์ติแฟคต์สำหรับคำแนะนำที่ใช้ได้เฉพาะกับอาร์ติแฟคต์นั้นๆ ตัวอย่างเช่น สเปค
• ให้คำอธิบายที่ละเอียดมากขึ้นเมื่อคุณเสนอการเปลี่ยนแปลง
• ใช้ /opsx:continue รุ่นขยายเพื่อสร้างอาร์ติแฟคต์ทีละชิ้นและตรวจสอบแต่ละชิ้น แทนที่จะใช้ /opsx:ff สร้างทั้งหมดพร้อมกัน

ฟีเจอร์ Archive ไม่เสร็จ หรือเตือนเกี่ยวกับงานที่ยังไม่เสร็จ

ฟีเจอร์ Archive จะไม่ บล็อก หากมีงานที่ยังไม่เสร็จ แต่จะเตือนคุณ เพราะการจัดเก็บโดยปกติหมายถึงงานเสร็จแล้ว หากงานที่ยังเหลืออยู่เป็นเรื่องเจตนา (คุณกำลังส่งการเปลี่ยนแปลงบางส่วน) ให้ดำเนินการต่อ มิฉะนั้นให้เสร็จงานก่อน Archive ยังจะเสนอให้ซิงค์สเปค delta ของคุณเข้าไปในสเปคหลักหากคุณยังไม่ได้ซิงค์; ยอมรับเว้นแต่คุณมีเหตุผลที่จะปฏิเสธ

การกำหนดค่า

My config.yaml isn't being applied

สามสาเหตุทั่วไป:

1. ชื่อไฟล์ผิด ต้องเป็น openspec/config.yaml ไม่ใช่ .yml
2. YAML ไม่ถูกต้อง รันผ่านตัวตรวจสอบ YAML ใดๆ; CLI ยังรายงานข้อผิดพลาดไวยากรณ์พร้อมหมายเลขบรรทัด
3. คุณคาดว่าต้องรีสตาร์ท ไม่จำเป็น การเปลี่ยนแปลงการกำหนดค่าจะมีผลทันที

"Unknown artifact ID in rules: X"

คีย์ภายใต้ rules: ไม่ตรงกับอาร์ติแฟคต์ใดๆ ในสคีมาของคุณ สำหรับสคีมา spec-driven เริ่มต้น ID ที่ถูกต้องคือ proposal, specs, design, tasks เพื่อดู ID สำหรับสคีมาใดๆ:

openspec schemas --json

ดูเพิ่มเติมที่ การปรับแต่ง

"Context too large"

ฟิลด์ context: จำกัดที่ 50KB อย่างเจตนา เพราะมันถูกใส่เข้าไปในทุกคำขอ ให้สรุปมัน หรือลิงก์ไปยังเอกสารที่ยาวกว่าแทนที่จะวางทั้งหมดเข้าไป บริบทที่สั้นยังส่งผลให้ได้ผลลัพธ์ที่ดีและเร็วขึ้น

"Schema not found"

ชื่อสคีมาที่คุณอ้างอิงไม่มีอยู่ รายชื่อสิ่งที่พร้อมใช้งานและตรวจสอบการสะกด:

openspec schemas                    # รายชื่อสคีมาที่พร้อมใช้งาน
openspec schema which <name>        # ดูว่าสคีมาชื่อนี้ถูกแก้ไขจากจุดใด
openspec schema init <name>         # สร้างสคีมาที่กำหนดเอง

ดูเพิ่มเติมที่ การปรับแต่ง

การย้ายข้อมูลจากเวิร์กโฟลว์เก่า

"Legacy files detected in non-interactive mode"

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

openspec init --force

สำหรับ Codex OpenSpec อาจตรวจพบไฟล์ prompt เก่าที่จัดการอยู่ใน $CODEX_HOME/prompts หรือ ~/.codex/prompts การทำความสะอาดนั้นจำกัดอยู่ที่ชื่อไฟล์ prompt Codex เก่าของ OpenSpec ที่อยู่ในรายการที่ได้รับอนุญาตเท่านั้น และ openspec init ในโหมดไม่โต้ตอบจะลบเฉพาะไฟล์ที่สกิล .codex/skills/openspec-* ที่ทดแทนแล้วมีอยู่เท่านั้น openspec update ในโหมดไม่โต้ตอบจะไม่ทำการทำความสะอาดไฟล์เก่าทั้งหมดเว้นแต่คุณส่ง --force

Commands didn't appear after migrating

คำสั่งไม่ปรากฏขึ้นหลังจากย้ายข้อมูล รีสตาร์ท IDE ของคุณ สกิลจะถูกตรวจพบเมื่อเริ่มต้น หากยังไม่ปรากฏขึ้น รัน openspec update และตรวจสอบตำแหน่งไฟล์ใน เครื่องมือที่รองรับ

My old project.md wasn't migrated

นั่นเป็นเรื่องเจตนา OpenSpec จะไม่ลบ project.md โดยอัตโนมัติเพราะมันอาจเก็บบริบทที่คุณเขียนไว้ ให้ย้ายส่วนที่มีประโยชน์ไปยังส่วน context: ของ openspec/config.yaml แล้วลบมันเอง คู่มือการย้ายข้อมูล จะช่วยคุณผ่านขั้นตอนนี้ รวมถึง prompt ที่คุณสามารถส่งให้ AI ทำการสกัดข้อมูลได้

ยังติดปัญหา?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• จากเทอร์มินัลของคุณ: openspec feedback "what went wrong" จะเปิดปัญหาให้คุณโดยอัตโนมัติ

เมื่อคุณรายงานปัญหา โปรดระบุเวอร์ชัน OpenSpec ของคุณ (openspec --version) เวอร์ชัน Node (node --version) เครื่องมือ AI ของคุณ และคำสั่งเอาต์พุตที่แน่นอน จะช่วยให้รับความช่วยเหลือได้เร็วขึ้นมาก