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

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

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

openspec: command not found

CLI ยังไม่ได้ติดตั้ง หรือ shell ของคุณไม่สามารถค้นหาได้ ติดตั้งแบบ global และตรวจสอบดังนี้:

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

หากติดตั้งแล้วแต่ยังหาไม่เจอ ไดเรกทอรี bin ของ npm แบบ global ของคุณน่าจะยังไม่อยู่ในตัวแปร PATH รันคำสั่ง npm prefix -g เพื่อดูว่าแพ็กเกจแบบ global อยู่ที่ไหน: บน macOS และ Linux ไฟล์ไบนารีจะอยู่ใน bin/ ของไดเรกทอรีนั้น และบน Windows จะอยู่โดยตรงในไดเรกทอรีนั้น ตรวจสอบให้แน่ใจว่าเส้นทางนั้นอยู่ใน PATH ของคุณ (npm bin -g ถูกลบออกใน npm 9 แล้ว)

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

"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 ไม่ได้กำหนดค่าเครื่องมือ AI ของฉัน

Init จะถามว่าต้องการตั้งค่าเครื่องมือใด หากข้ามเครื่องมือของคุณหรือต้องการเพิ่มเครื่องมืออื่น เพียงรันอีกครั้ง หรือใช้รูปแบบที่ไม่โต้ตอบ (non-interactive):

openspec init --tools claude,cursor

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

คำสั่งไม่ปรากฏ

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

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

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

   openspec update

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

   ไฟล์คำแนะนำมาจาก CLI ที่ ติดตั้งอยู่ ดังนั้น CLI ที่ล้าสมัยจะรายงานทุกอย่างว่าอัปเดตล่าสุดโดยไม่มีการเขียนเวิร์กโฟลว์ใหม่ openspec update ตอนนี้ตรวจสอบสิ่งนี้และเสนอให้อัปเกรด — ยอมรับข้อเสนอหากคุณเห็นมัน

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

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

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

6. ยืนยันว่าเครื่องมือของคุณรองรับไฟล์คำสั่ง Codex, CodeArts, ForgeCode, Hermes, Kimi Code, Mistral Vibe, Zed Agent และเป้าหมาย .agents ร่วมกัน จะไม่มีการสร้างไฟล์คำสั่ง opsx-* แต่จะใช้การเรียกใช้งานแบบ skill-based แทน ดังนั้น /opsx จะไม่มี autocomplete สำหรับพวกเขา พิมพ์ $openspec-propose ใน Codex, /skill:openspec-propose ใน Kimi Code และ /openspec-propose ในที่เหลือ เป้าหมาย .agents ร่วมกันเป็นกลางต่อผู้ขาย ดังนั้น /openspec-propose จึงเป็นรูปแบบทั่วไปแทนที่จะเป็นรูปแบบที่รับประกัน — หากผู้ช่วยของคุณไม่ตอบสนองต่อมัน ให้ดูเอกสารของตนเองเพื่อดูวิธีการเรียกใช้ skill Amazon Q ได้รับไฟล์คำสั่ง แต่โหลดลงในไลบรารี prompt ของมันแทนเมนู slash — พิมพ์ @opsx-propose ที่นั่น ไม่ใช่ /opsx รูปแบบของทุกเครื่องมือระบุไว้ใน วิธีการเรียกใช้งาน

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

"Change not found"

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

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

นอกจากนี้ให้ยืนยันว่าคุณอยู่ในไดเรกทอรีโปรเจกต์ที่ถูกต้อง

"No artifacts ready"

อาร์ติแฟกต์แต่ละชิ้นถูกสร้างไว้แล้วหรือกำลังรอการพึ่งพา (dependency) ดูว่ามีอะไรบล็อกอยู่:

openspec status --change <name>

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

openspec validate รายงานคำเตือนหรือข้อผิดพลาด

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

openspec validate <name>           # validate รายการเดียว
openspec validate --all            # validate ทุกอย่าง
openspec validate --all --strict   # การตรวจสอบที่เข้มงวดขึ้น เหมาะสำหรับ CI
openspec validate --archived       # ล้มเหลวหากการเปลี่ยนแปลงที่เก็บถาวรยังมีงานที่ยังไม่ได้ตรวจสอบ

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

ข้อความหนึ่ง deserving หมายเหตุพิเศษ:

MODIFIED "<requirement>" omits scenario(s) the current spec still has: "<scenario>"

MODIFIED requirement จะแทนที่ทั้งบล็อก requirement ดังนั้นจึงต้องครอบคลุมทุก scenario ที่ยังคงอยู่หลังการเปลี่ยนแปลง ไม่ใช่แค่ส่วนที่คุณแก้ไข คัดลอก scenarios ที่ระบุจาก openspec/specs/<capability-path>/spec.md กลับเข้าไปใน delta โดยรักษาไดเรกทอรีโดเมนในเส้นทางไว้ สิ่งนี้มักปรากฏในการเปลี่ยนแปลงเก่าหลังจากที่การเปลี่ยนแปลงของคนอื่นเพิ่ม scenario เข้าไปใน requirement เดียวกัน — archive ปฏิเสธการเปลี่ยนแปลงนั้นไม่ว่ากรณีใด และ validation ตอนนี้แจ้งเช่นนั้นก่อนที่จะดำเนินการ

AI สร้างอาร์ติแฟกต์ที่ไม่สมบูรณ์หรือผิด

AI ไม่มีบริบทเพียงพอ คันโยกบางตัวช่วย:

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

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

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

"User force closed the prompt with 0 null"

มีบางอย่างรัน openspec archive ในที่ที่ไม่มีใครสามารถตอบคำถามได้ — AI agent เรียกมันจากเครื่องมือ, job ใน CI, หรือ shell ใด ๆ ที่มี stdin ปิด Archive ถามการยืนยันสูงสุดสามครั้ง และการถามที่ไม่สามารถตอบได้เคยล้มเหลวด้วยข้อความดิบนั้น

ส่ง --yes เพื่อตอบล่วงหน้า:

openspec archive <change-name> --yes

รักษา flags ทั้งหมดที่คุณส่งอยู่แล้ว — --skip-specs และ --no-validate เปลี่ยนสิ่งที่ archive ทำ ดังนั้นการรันซ้ำด้วย --yes อย่างเดียวไม่ใช่คำสั่งเดียวกัน เวอร์ชันปัจจุบันจะระบุชื่อ flag ให้คุณและพิมพ์บรรทัด Fix: ที่คุณสามารถวางได้ หากคุณตั้งใจเลือกจากรายการ ให้ส่งชื่อการเปลี่ยนแปลงอย่างชัดเจน: ตัวเลือกต้องการคำตอบเช่นกัน

หากคุณรัน archive โดยนำเอาต์พุตไปยังไฟล์หรือจับโดยเครื่องมือและ ได้ ส่งคำตอบ (printf 'y\n' | openspec archive …) เวอร์ชันเก่าเขียน escape codes ของ terminal ไปยังแคปเจอร์นั้นขณะวาด prompt — ในบางสภาพแวดล้อมทำให้ไฟล์ใหญ่ขึ้นอย่างมาก เวอร์ชันปัจจุบันอ่าน prompt ยืนยันเป็นข้อความธรรมดา whenever stdout ไม่ใช่ terminal และ openspec archive ที่ไม่มีอาร์กิวเมนต์ (ซึ่งปกติจะวาดตัวเลือกการเปลี่ยนแปลงแบบอินเทอร์แอคทีฟ) จะให้คุณส่งชื่อการเปลี่ยนแปลงล่วงหน้าแทนที่จะเรนเดอร์เมนูเข้าไปในแคปเจอร์ ไม่ว่ากรณีใด การรันแบบรีไดเรกต์และ agent จะสะอาด; การส่ง --yes (พร้อมชื่อการเปลี่ยนแปลง) ข้าม prompts ทั้งหมด

การกำหนดค่า

config.yaml ของฉันไม่ถูกนำไปใช้

ผู้ต้องสงสัยสามรายทั่วไป:

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

"Unknown artifact ID in rules: X"

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

openspec schemas --json

"Context too large"

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

"Schema not found"

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

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

ดู การปรับแต่ง

การย้ายจากเวิร์กโฟลว์เดิม

"Legacy files detected in non-interactive mode"

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

openspec init --force

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

คำสั่งไม่ปรากฏหลังการย้าย

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

project.md เก่าของฉันไม่ถูกย้าย

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

ยังติดขัด?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• จาก terminal ของคุณ: openspec feedback "what went wrong" เปิด issue ให้คุณ

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