ข้ามไปที่เนื้อหาหลัก

สิ่งที่คาดไม่ถึงซึ่งพบแล้ว

ไฟล์นี้รวบรวมจุดที่สร้างความสับสนเฉพาะของ repo นี้ ซึ่งเคยทำให้เอเจนต์ทำงานผิดพลาด

เกณฑ์การเพิ่มรายการ​

เพิ่มรายการก็ต่อเมื่อเงื่อนไขต่อไปนี้เป็นจริงทั้งหมด:

  • เป็นเรื่องเฉพาะของ repo นี้ ไม่ใช่คำแนะนำทั่วไป
  • มีแนวโน้มจะเกิดซ้ำกับเอเจนต์ในอนาคต
  • มีวิธีรับมือที่ชัดเจนและปฏิบัติตามได้จริง

หากไม่แน่ใจ ให้ถามนักพัฒนาก่อนเพิ่มรายการ

เทมเพลตของรายการ​

### [Short title]

- **Date:** YYYY-MM-DD
- **Observed by:** agent name or contributor
- **Context:** where/when it happened
- **What was surprising:** concrete unexpected behavior
- **Impact:** what went wrong or could go wrong
- **Mitigation:** exact step future agents should take
- **Status:** confirmed | superseded

รายการ​

โดเมนโปรดักชันของแอปบน Vercel อาจย้อนกลับไปใช้ดีพลอยจาก Git master​

  • วันที่: 2026-04-28
  • ผู้สังเกต: Tommaso + Codex
  • บริบท: การตรวจสอบมิเรอร์ของแอป Seedit และ 5chan ในไดเรกทอรีแอปของ Bitsocial Web
  • สิ่งที่คาดไม่ถึง: โปรเจกต์ seedit และ 5chan บน Vercel ตั้งค่า gitProviderOptions.createDeployments = "enabled" ไว้ การ push เข้า master บน GitHub จึงถูกโปรโมตขึ้นโดเมนโปรดักชัน ทั้งที่นโยบายของ repo กำหนดให้มิเรอร์แอปโปรดักชันเสิร์ฟเฉพาะไฟล์จากรีลีสเท่านั้น
  • ผลกระทบ: ป้ายยืนยันมิเรอร์ในไดเรกทอรีแอปอาจกลายเป็นข้อมูลเท็จ เพราะโดเมนโปรดักชันเสิร์ฟคอมมิตล่าสุดของสายพัฒนาแทนไฟล์ ZIP ของรีลีสบน GitHub ที่ค่าแฮชของ index.html ถูกบันทึกไว้ใน about/src/lib/apps-data.ts
  • วิธีรับมือ: ก่อนเพิ่มหรืออัปเดตข้อมูลยืนยันมิเรอร์ ให้ตรวจโปรเจกต์บน Vercel ด้วย vercel api /v9/projects/<project-id> และยืนยันว่า gitProviderOptions.createDeployments = "disabled" ดีพลอยเนื้อหาจาก ZIP ของรีลีสด้วย vercel deploy --prebuilt --prod และใช้ seedit-omega.vercel.app หรือ 5chan-omega.vercel.app สำหรับดีพลอยของสายพัฒนา
  • สถานะ: ยืนยันแล้ว

Portless 0.11 นำสถานะพร็อกซีเดิมกลับมาใช้ หากตัวเรียกใช้ไม่บังคับ HTTPS​

  • วันที่: 2026-04-28
  • ผู้สังเกต: Tommaso + Codex
  • บริบท: การอัปเกรดโฟลว์ yarn start ตามปกติ จาก URL พร็อกซีเดิม http://bitsocial.localhost:1355 ไปเป็น https://bitsocial.localhost.
  • สิ่งที่คาดไม่ถึง: แม้ติดตั้ง portless@0.11.1 แล้ว Portless ก็ยังใช้พร็อกซี HTTP เดิมที่ ~/.portless/proxy.port = 1355 ต่อไป และพิมพ์ URL แบบเก่าที่ลงท้ายด้วย :1355
  • ผลกระทบ: การอัปเดตเวอร์ชันแพ็กเกจและเอกสารอย่างเดียวไม่พอ yarn start ยังประกาศและใช้ URL เก่าได้ เมื่อเครื่องของผู้ร่วมพัฒนายังมีสถานะ Portless เดิมทำงานอยู่
  • วิธีรับมือ: ให้สคริปต์เริ่มระบบสั่งเปิดพร็อกซี HTTPS ของ Portless บนพอร์ต 443 อย่างชัดเจนก่อนลงทะเบียนเส้นทางของแอป เพื่อให้โฟลว์รันไทม์ย้ายออกจากสถานะ 1355 ที่ค้างอยู่ แทนที่จะสืบทอดมันมา
  • สถานะ: ยืนยันแล้ว

Portless เปลี่ยน URL มาตรฐานของแอปในเครื่อง​

  • วันที่: 2026-03-18
  • ผู้สังเกต: Codex
  • บริบท: การตรวจสอบผ่านเบราว์เซอร์และโฟลว์ smoke test
  • สิ่งที่คาดไม่ถึง: URL ในเครื่องที่เป็นค่าเริ่มต้นไม่ใช่พอร์ต Vite ตามปกติ repo นี้คาดหวัง https://bitsocial.localhost ผ่าน Portless การเปิด localhost:3000 หรือ localhost:5173 จึงอาจไปเจอแอปผิดตัวหรือไม่เจออะไรเลย
  • ผลกระทบ: การตรวจสอบผ่านเบราว์เซอร์อาจล้มเหลวหรือไปยืนยันเป้าหมายผิดตัว แม้เซิร์ฟเวอร์ dev จะทำงานปกติดี
  • วิธีรับมือ: ใช้ https://bitsocial.localhost ก่อนเสมอ ข้ามไปใช้ PORTLESS=0 corepack yarn start เฉพาะเมื่อจำเป็นต้องเข้าพอร์ต Vite โดยตรงจริง ๆ
  • สถานะ: ยืนยันแล้ว

Commitizen hooks ขวางการคอมมิตแบบไม่โต้ตอบ​

  • วันที่: 2026-03-18
  • ผู้สังเกต: Codex
  • บริบท: เวิร์กโฟลว์การคอมมิตที่ขับเคลื่อนด้วยเอเจนต์
  • สิ่งที่คาดไม่ถึง: git commit จะเรียก Commitizen ผ่าน Husky แล้วรออินพุตจาก TTY แบบโต้ตอบ ทำให้เชลล์ของเอเจนต์ที่ไม่มีการโต้ตอบค้าง
  • ผลกระทบ: เอเจนต์อาจค้างไม่มีกำหนดระหว่างขั้นตอนที่ควรจะเป็นการคอมมิตธรรมดา
  • วิธีรับมือ: ใช้ git commit --no-verify -m "message" สำหรับคอมมิตที่เอเจนต์สร้างขึ้น ส่วนคนยังใช้ corepack yarn commit หรือ corepack yarn exec cz ได้ตามปกติ
  • สถานะ: ยืนยันแล้ว

ต้องใช้ Corepack เพื่อไม่ให้ไปโดน Yarn classic​

  • วันที่: 2026-03-19
  • ผู้สังเกต: Codex
  • บริบท: การย้ายตัวจัดการแพ็กเกจไปเป็น Yarn 4
  • สิ่งที่คาดไม่ถึง: เครื่องยังมี Yarn classic ติดตั้งแบบ global อยู่ใน PATH การรัน yarn เปล่า ๆ จึงอาจไปเรียก v1 แทนเวอร์ชัน Yarn 4 ที่ปักหมุดไว้
  • ผลกระทบ: นักพัฒนาอาจข้ามการปักหมุดตัวจัดการแพ็กเกจของ repo โดยไม่ตั้งใจ แล้วได้พฤติกรรมการติดตั้งหรือผลลัพธ์ในไฟล์ล็อกที่ต่างออกไป
  • วิธีรับมือ: ใช้ corepack yarn ... ในคำสั่งเชลล์ หรือรัน corepack enable ก่อน เพื่อให้ yarn เปล่า ๆ ชี้ไปที่ Yarn 4 เวอร์ชันที่ปักหมุดไว้
  • สถานะ: ยืนยันแล้ว

ชื่อแอป Portless แบบตายตัวชนกันระหว่าง worktree ของ Bitsocial Web​

  • วันที่: 2026-03-30
  • ผู้สังเกต: Codex
  • บริบท: การรัน yarn start ใน worktree หนึ่งของ Bitsocial Web ขณะที่อีก worktree หนึ่งเสิร์ฟผ่าน Portless อยู่แล้ว
  • สิ่งที่คาดไม่ถึง: การใช้ชื่อแอป Portless ตรงตัวว่า bitsocial ในทุก worktree ทำให้ตัวเส้นทางเองชนกัน แม้พอร์ตเบื้องหลังจะต่างกัน โปรเซสที่สองจึงล้มเหลวเพราะ bitsocial.localhost ถูกลงทะเบียนไปแล้ว
  • ผลกระทบ: สาขาของ Bitsocial Web ที่ทำงานคู่ขนานกันอาจบล็อกกันเอง ทั้งที่ Portless ควรทำให้อยู่ร่วมกันได้อย่างปลอดภัย
  • วิธีรับมือ: ให้การเริ่ม Portless อยู่หลัง scripts/start-dev.mjs ซึ่งตอนนี้ใช้เส้นทาง *.bitsocial.localhost ที่ผูกกับชื่อสาขาเมื่ออยู่นอกกรณีมาตรฐาน และถอยไปใช้เส้นทางแบบผูกกับสาขาเมื่อชื่อ bitsocial.localhost เปล่า ๆ ถูกใช้งานอยู่แล้ว
  • สถานะ: ยืนยันแล้ว

พรีวิวเอกสารเคยฮาร์ดโค้ดพอร์ต 3001 ไว้​

  • วันที่: 2026-03-30
  • ผู้สังเกต: Codex
  • บริบท: การรัน yarn start พร้อมกับ repo และเอเจนต์อื่นในเครื่อง
  • สิ่งที่คาดไม่ถึง: คำสั่ง dev ที่ระดับ root รันเวิร์กสเปซของเอกสารด้วย docusaurus start --port 3001 เซสชัน dev ทั้งเซสชันจึงล้มทันทีที่มีโปรเซสอื่นครอง 3001 อยู่ ทั้งที่แอปหลักใช้ Portless อยู่แล้ว
  • ผลกระทบ: yarn start อาจปิดโปรเซสของเว็บทิ้งทันทีหลังบูตขึ้นมา ทำให้งานอื่นในเครื่องที่ไม่เกี่ยวข้องกันสะดุด เพียงเพราะพอร์ตของเอกสารชนกัน
  • วิธีรับมือ: ให้การเริ่มเอกสารอยู่หลัง yarn start:docs ซึ่งตอนนี้ใช้ Portless ร่วมกับ scripts/start-docs.mjs เพื่อรับพอร์ตว่างที่ถูกส่งเข้ามา หรือถอยไปใช้พอร์ตว่างถัดไปเมื่อถูกเรียกโดยตรง
  • สถานะ: ยืนยันแล้ว

ชื่อโฮสต์ Portless ของเอกสารเคยถูกฮาร์ดโค้ดไว้​

  • วันที่: 2026-04-03
  • ผู้สังเกต: Codex
  • บริบท: การรัน yarn start ใน worktree รองของ Bitsocial Web ขณะที่อีก worktree หนึ่งเสิร์ฟเอกสารผ่าน Portless อยู่แล้ว
  • สิ่งที่คาดไม่ถึง: start:docs ยังลงทะเบียนชื่อโฮสต์ตรงตัวว่า docs.bitsocial.localhost yarn start จึงล้มได้ ทั้งที่แอป about รู้วิธีเลี่ยงการชนกันของเส้นทาง Portless สำหรับชื่อโฮสต์ของตัวเองแล้ว
  • ผลกระทบ: worktree ที่ทำงานคู่ขนานกันใช้คำสั่ง dev ระดับ root ได้ไม่แน่นอน เพราะโปรเซสของเอกสารออกก่อน แล้ว concurrently ก็ปิดเซสชันที่เหลือทิ้ง
  • วิธีรับมือ: ให้การเริ่มเอกสารอยู่หลัง scripts/start-docs.mjs ซึ่งตอนนี้สร้างชื่อโฮสต์ Portless ที่ผูกกับสาขาแบบเดียวกับแอป about และฉีด URL สาธารณะร่วมนั้นเข้าไปเป็นเป้าหมายของพร็อกซี dev ที่ /docs
  • สถานะ: ยืนยันแล้ว

เชลล์ใน worktree อาจพลาดเวอร์ชัน Node ที่ repo ปักหมุดไว้​

  • วันที่: 2026-04-03
  • ผู้สังเกต: Codex
  • บริบท: การรัน yarn start ใน worktree ของ Git เช่น .claude/worktrees/* หรือ worktree ที่เช็กเอาต์ไว้ข้าง ๆ กัน
  • สิ่งที่คาดไม่ถึง: เชลล์ของบาง worktree แปลง node และ yarn node ไปเป็น Homebrew Node 25.2.1 ทั้งที่ repo ปักหมุด 22.12.0 ไว้ใน .nvmrc yarn start จึงอาจรันตัวเรียกใช้ dev ด้วยรันไทม์ผิดเวอร์ชันแบบเงียบ ๆ
  • ผลกระทบ: พฤติกรรมของ dev server อาจต่างกันระหว่างเช็กเอาต์หลักกับ worktree ทำให้ทำซ้ำบั๊กได้ยาก และขัดกับ toolchain Node 22 ที่ repo กำหนดไว้
  • วิธีรับมือ: ให้ตัวเรียกใช้ dev อยู่หลัง scripts/start-dev.mjs และ scripts/start-docs.mjs ซึ่งตอนนี้จะ re-exec ด้วยไบนารี Node ตาม .nvmrc เมื่อเชลล์ปัจจุบันใช้เวอร์ชันผิด ส่วนการตั้งค่าเชลล์ก็ยังควรใช้ nvm use อยู่ดี
  • สถานะ: ยืนยันแล้ว

ไฟล์ตกค้างใน docs-site/ อาจบังไม่ให้เห็นว่าซอร์สของเอกสารหายไปหลังรีแฟกเตอร์​

  • วันที่: 2026-04-01
  • ผู้สังเกต: Codex
  • บริบท: การเก็บกวาด monorepo หลังการรวมโค้ด เมื่อย้ายโปรเจกต์ Docusaurus จาก docs-site/ ไปที่ docs/
  • สิ่งที่คาดไม่ถึง: โฟลเดอร์ docs-site/ เดิมอาจยังค้างอยู่บนดิสก์พร้อมไฟล์เก่าแต่สำคัญอย่าง i18n/ แม้ repo ที่ติดตามไว้จะย้ายไป docs/ แล้ว ทำให้การรีแฟกเตอร์ดูเหมือนซ้ำซ้อนในเครื่อง และอาจบังข้อเท็จจริงที่ว่างานแปลเอกสารซึ่งถูกติดตามไว้ยังไม่ได้ถูกย้ายเข้า docs/ จริง ๆ
  • ผลกระทบ: เอเจนต์อาจลบโฟลเดอร์เก่าทิ้งเพราะคิดว่าเป็น "junk" แล้วทำให้สำเนางานแปลเอกสารชุดเดียวที่มีในเครื่องหายไป หรือแก้สคริปต์ที่ยังชี้ไปยังพาธ docs-site/ ที่ตายแล้วต่อไป
  • วิธีรับมือ: ถือว่า docs/ เป็นโปรเจกต์เอกสารเพียงชุดเดียวที่ถูกต้อง ก่อนลบไฟล์ตกค้างของ docs-site/ ในเครื่อง ให้กู้ซอร์สที่ติดตามไว้อย่าง docs/i18n/ กลับมาก่อน แล้วอัปเดตสคริปต์และ hook ให้เลิกอ้างถึง docs-site
  • สถานะ: ยืนยันแล้ว

พรีวิวเอกสารหลายภาษาอาจทำให้ RAM พุ่งสูงระหว่างการตรวจสอบ​

  • วันที่: 2026-04-01
  • ผู้สังเกต: Codex
  • บริบท: การแก้ i18n ของเอกสาร การจัดเส้นทางตามภาษา และพฤติกรรมของ Pagefind ด้วย yarn start:docs ร่วมกับ Playwright
  • สิ่งที่คาดไม่ถึง: โหมดพรีวิวเอกสารแบบเริ่มต้นตอนนี้จะบิลด์เอกสารครบทุกภาษาพร้อมทำดัชนี Pagefind ก่อนเสิร์ฟ และการปล่อยให้โปรเซสนั้นทำงานคู่กับเซสชัน Playwright หรือ Chrome หลายตัวอาจกิน RAM มากกว่าลูป dev ของ Vite หรือ Docusaurus ภาษาเดียวอย่างมาก
  • ผลกระทบ: เครื่องอาจเหลือหน่วยความจำไม่พอ เซสชันเบราว์เซอร์อาจแครช และการรันที่ถูกขัดจังหวะอาจทิ้งเซิร์ฟเวอร์เอกสารหรือเบราว์เซอร์ headless ค้างไว้กินหน่วยความจำต่อ
  • วิธีรับมือ: สำหรับงานเอกสารที่ไม่ต้องตรวจเส้นทางตามภาษาหรือ Pagefind ให้ใช้ DOCS_START_MODE=live yarn start:docs ใช้พรีวิวหลายภาษาแบบเริ่มต้นเฉพาะเมื่อต้องตรวจเส้นทางที่แปลแล้วหรือ Pagefind จริง ๆ เปิดเซสชัน Playwright ไว้เพียงเซสชันเดียว ปิดเซสชันเบราว์เซอร์เก่าก่อนเปิดเซสชันใหม่ และหยุดเซิร์ฟเวอร์เอกสารหลังตรวจสอบเสร็จหากไม่ได้ใช้งานต่อ
  • สถานะ: ยืนยันแล้ว

translate-docs.py อาจทิ้งภาษาของเอกสารไว้แปลไม่ครบ หรือทำให้ปลายทางของลิงก์พัง​

  • วันที่: 2026-04-06
  • ผู้สังเกต: Codex
  • บริบท: การแก้เส้นทางและเนื้อหาเอกสารตามภาษา หลังจาก yarn start:docs เสิร์ฟหน้ารายละเอียดเป็นภาษาอังกฤษ หรือบิลด์เอาต์พุตของภาษานั้นไม่สำเร็จ
  • สิ่งที่คาดไม่ถึง: ไปป์ไลน์แปลเอกสารมีจุดพังเฉพาะของ repo นี้พร้อมกันสองจุด scripts/translate-docs.py ดึงข้อความของ DocsHome ออกมาได้เพียงส่วนน้อยเมื่อการเรียก tr(...) อยู่ในรูปแบบที่มันแยกวิเคราะห์ไม่ได้ และมาร์กดาวน์ที่แปลแล้วใต้ docs/i18n/** อาจมี slug ที่ถูกแปลด้วยเครื่องหรือเศษ ZXQPLACEHOLDER ติดอยู่ในปลายทางของลิงก์
  • ผลกระทบ: หน้าแรกตามภาษาอาจถอยกลับไปเป็นภาษาอังกฤษแบบเงียบ ๆ หน้ารายละเอียดตามภาษาอาจดูเหมือนไม่ได้แปล และ yarn docs:build แบบเต็มอาจล้มเพราะลิงก์ของภาษานั้นพัง ทั้งที่เอกสารต้นทางถูกต้องดี
  • วิธีรับมือ: หลังแก้งานแปลเอกสารหรือสร้างไฟล์ภาษาใหม่ ให้รัน yarn docs:build จาก root ของ repo เสมอ สแกนมาร์กดาวน์ใน docs/i18n/** เพื่อหา ZXQPLACEHOLDER และตรวจว่าลิงก์ที่แปลแล้วยังชี้ไปยัง slug มาตรฐานของเอกสาร เช่น /apps/5chan/ ไม่ใช่พาธ URL ที่ถูกแปล หากข้อความของ DocsHome เปลี่ยนไป ให้ยืนยันว่า scripts/translate-docs.py ยังดึงข้อความ docs.home.* ได้ครบทุกตัว
  • สถานะ: ยืนยันแล้ว

การตรวจแบบไม่มี JS ของเว็บ about ต้องใช้เส้นทาง Portless ไม่ใช่พรีวิว SSR แยกต่างหาก​

  • วันที่: 2026-04-12
  • ผู้สังเกต: Codex
  • บริบท: การตรวจสอบการรองรับการทำงานแบบไม่มี JS ของเว็บ about/ จาก worktree ของสาขาหนึ่ง
  • สิ่งที่คาดไม่ถึง: พรีวิว SSR แบบแยกต่างหากอาจดูเหมือนทำงานปกติ ขณะที่เส้นทาง Portless ที่ผูกกับสาขาจริง ๆ ยังเสิร์ฟ app shell ผิดตัวหรือโปรเซสเก่าอยู่ ใน repo นี้ สัญญาที่แท้จริงในเครื่องคือชื่อโฮสต์ Portless จาก yarn start ไม่ใช่เซิร์ฟเวอร์พรีวิวที่ตั้งขึ้นเฉพาะกิจ
  • ผลกระทบ: เอเจนต์อาจสรุปผิดว่าการรองรับแบบไม่มี JS ใช้งานได้ หรือมองข้ามการถดถอยที่ปรากฏเฉพาะบน *.bitsocial.localhost
  • วิธีรับมือ: สำหรับการตรวจสอบ about/ ผ่านเบราว์เซอร์ ให้เริ่มเซิร์ฟเวอร์จริงในเครื่องด้วย yarn start หรือ yarn start:about แล้วทดสอบ URL ของ Portless ที่ผูกกับสาขาก่อนเสมอ หากชื่อโฮสต์ Portless ดูเหมือนค้างอยู่ ให้ตรวจและหยุดโปรเซสเก่าก่อนแล้วค่อยทดสอบใหม่
  • สถานะ: ยืนยันแล้ว

chain/ มองไม่เห็นโดย yarn build:verify และ yarn doctor​

  • วันที่: 2026-07-05
  • ผู้สังเกต: Codex
  • บริบท: การตรวจสอบ diff ที่แตะเฉพาะ chain/ หลังจากเวิร์กสเปซ chain/ (แอป Vite แบบสแตนด์อโลนสำหรับ chain.bitsocial.net) ถูกเพิ่มเข้ามาใน monorepo
  • สิ่งที่คาดไม่ถึง: scripts/verify-build.mjs รู้จักเฉพาะพาธที่ขึ้นต้นด้วย about/, docs/ และ stats/ เท่านั้น diff ที่แตะเฉพาะ chain/ จึงพิมพ์ "No targeted build checks matched the current diff" แล้วไม่รันบิลด์ใด ๆ เลย ทั้งที่ build:chain มีอยู่ใน package.json ระดับ root อยู่แล้ว อีกเรื่องหนึ่งคือ yarn doctor ถูกฮาร์ดโค้ดไว้เป็น react-doctor about -y การเปลี่ยนแปลง React ใต้ chain/src จึงไม่ได้รับการตรวจจาก React Doctor เลย
  • ผลกระทบ: เอเจนต์ที่ตรวจสอบการเปลี่ยนแปลงของ chain ต้องรู้เองว่าให้เรียก yarn build:chain ตรง ๆ แทนที่จะเชื่อ yarn build:verify และปัญหา React ใน chain/src (effect, hook, โค้ดที่ตายแล้ว) ก็หลุดรอดสายตา yarn doctor ไป
  • วิธีรับมือ: ตอนนี้ scripts/verify-build.mjs มีสาขาสำหรับ chain/ ที่สะท้อนสาขาของ about/ แล้ว และ doctor กับ doctor:verbose ก็รัน react-doctor --project about,chain -y ในการเรียกครั้งเดียว ส่วน doctor:score ยังครอบคลุมเฉพาะ about เพราะ --score จะไม่พิมพ์อะไรเลยแบบเงียบ ๆ เมื่อใช้ร่วมกับ --project ที่ระบุมากกว่าหนึ่งโปรเจกต์ หากต้องการคะแนนของ chain ให้ใช้ yarn react-doctor --project about,chain --verbose -y (หรือ --json)
  • สถานะ: ยืนยันแล้ว

P2P ในเบราว์เซอร์ทำงานบน WebSockets แบบปลอดภัย ส่วน pkc-js ปฏิเสธ WebRTC และ WebTransport โดยค่าเริ่มต้น​

  • วันที่: 2026-08-02
  • ผู้สังเกต: Claude
  • บริบท: การเขียนข้อความบนหน้า landing และในเอกสารเกี่ยวกับวิธีทำงานของ P2P ในเบราว์เซอร์ของ Bitsocial
  • สิ่งที่คาดไม่ถึง: @pkcprotocol/pkc-js มาพร้อม connection gater ที่เป็นค่าเริ่มต้น ซึ่งปฏิเสธการ dial ผ่าน WebRTC และ WebTransport ในเบราว์เซอร์ โดย dist/browser/helia/dial-transport-filter.js ส่งออก DENIED_DIAL_TRANSPORTS_BY_DEFAULT = ["webrtc", "webrtc-direct", "webtransport"] คอมเมนต์ในซอร์สให้เหตุผลไว้ว่า ในเบราว์เซอร์ ทรานสปอร์ตเหล่านั้นเพิ่มเส้นทางการสร้างการเชื่อมต่อที่ยาวและมักล้มเหลว (STUN/ICE การหมุนเวียน certhash) ซึ่งทำให้โหลดช้าลง ขณะที่ WebSocket ตรงไปตรงมาและเชื่อถือได้ พีร์ที่ออนไลน์อยู่ทุกตัวในแผง "P2P status" ของบล็อกแสดงว่า "Secure WebSocket" ทั้งหมด ตัว gater อยู่ใน node_modules จึงไม่มีอะไรใน repo ที่บอกใบ้ถึงมันเลย
  • ผลกระทบ: การเขียนข้อความสาธารณะที่ฟังดูสมเหตุสมผลทางเทคนิคแต่ผิดนั้นเกิดขึ้นง่ายมาก เช่น การยกเครดิตให้ WebTransport ที่เข้าสถานะ Baseline ของเบราว์เซอร์ในเดือนมีนาคม 2026 ว่าเป็นตัวทำให้ P2P ในเบราว์เซอร์ของ Bitsocial เป็นไปได้ ข้อความนั้นถูกปล่อยขึ้นหน้า landing ตารางเปรียบเทียบ และเอกสารอีกสองหน้า ก่อนที่นักพัฒนาจะจับได้ ข้อความที่อ้างสถาปัตยกรรมผิดบนหน้าสาธารณะจะถูกตรวจสอบโดยกลุ่มนักพัฒนาที่เว็บนี้ตั้งใจสื่อสารด้วยพอดี
  • วิธีรับมือ: อย่าอนุมานว่า Bitsocial ใช้ทรานสปอร์ตใดจากสิ่งที่ libp2p หรือแพลตฟอร์มเบราว์เซอร์รองรับในทางทฤษฎี ให้ตรวจ node_modules/@pkcprotocol/pkc-js/dist/browser/helia/dial-transport-filter.js เพื่อดูรายการปฏิเสธล่าสุด ยืนยันว่าไม่มีการ override connectionGater ใต้ about/src/ และอ่านป้ายทรานสปอร์ตจริงในแผง "P2P status" ของบล็อกก่อนกล่าวอ้างอะไรต่อสาธารณะ การเปลี่ยนแปลงจากต้นน้ำที่ปลดล็อกการเผยแพร่จากเบราว์เซอร์ได้จริงคือการแก้ seqno แบบ monotonic ของ gossipsub ใน @libp2p/gossipsub 15.0.21 (พฤษภาคม 2026) ส่วน pkc-js ปัจจุบันมาพร้อม 16.0.4
  • สถานะ: ยืนยันแล้ว

ลิงก์แบบสัมพัทธ์ ./page.md จากหน้าเอกสารที่ยังไม่ได้แปล ทำให้บิลด์ของทุกภาษาพัง​

  • วันที่: 2026-08-02
  • ผู้สังเกต: Claude
  • บริบท: การเพิ่มหน้าใหม่ที่มีเฉพาะภาษาอังกฤษ docs/browser-p2p.md ซึ่งลิงก์ไปยังเอกสารที่มีอยู่แล้วด้วย ./peer-to-peer-protocol.md และ ./apps/5chan.md
  • สิ่งที่คาดไม่ถึง: แต่ละภาษาใต้ docs/i18n/<lang>/docusaurus-plugin-content-docs/current/ จะสะท้อนโครงสร้างของ docs หน้าใหม่ที่ยังไม่มีในมิเรอร์เหล่านั้นยังแสดงผลได้ในทุกภาษาผ่านการถอยกลับไปใช้ภาษาอังกฤษ แต่ลิงก์มาร์กดาวน์แบบสัมพัทธ์ของมันจะแปลงปลายทางไม่ได้อีกต่อไป Docusaurus จะสร้าง /ar/browser-p2p/peer-to-peer-protocol.md/ แล้วทำให้บิลด์ล้มด้วยข้อความ "Docusaurus found broken links!" ที่สำคัญคือ yarn build:verify และ yarn docs:build:verify บิลด์เฉพาะ en และผ่านฉลุย มีเพียง yarn docs:build แบบเต็มเท่านั้นที่เผยปัญหานี้ออกมา และมันจะหยุดที่ภาษาแรกตามลำดับตัวอักษร (ar)
  • ผลกระทบ: การเปลี่ยนแปลงเอกสารอาจผ่านการตรวจสอบเร็ว ๆ ในเครื่องได้ทุกอย่าง แต่ยังทำให้บิลด์หลายภาษาบนโปรดักชันพัง ความล้มเหลวนี้ยังดูเหมือนไม่เกี่ยวกับการเปลี่ยนแปลงที่ทำ เพราะข้อความข้อผิดพลาดอ้างถึงพาธของภาษาที่ผู้เขียนไม่เคยแตะ
  • วิธีรับมือ: ในหน้าเอกสารใดก็ตามที่ไม่ได้ถูกมิเรอร์เข้าไปใน docs/i18n/** ให้ใช้ลิงก์ที่อิงจาก root (/peer-to-peer-protocol/, /apps/5chan/) แทนลิงก์ .md แบบสัมพัทธ์ เพราะ Docusaurus จะเติมรหัสภาษาไว้ข้างหน้าให้เอง docs/build-your-own-client.md เป็นตัวอย่างที่มีอยู่แล้ว รัน yarn docs:build แบบเต็ม ไม่ใช่แค่ build:verify ก่อนส่งมอบการเปลี่ยนแปลงใดก็ตามที่เพิ่มหน้าเอกสารหรือลิงก์ไปยังหน้าเอกสาร
  • สถานะ: ยืนยันแล้ว

update-translations.js ต้องรันจาก about/ และการรันพร้อมกันทำให้คีย์หายแบบเงียบ ๆ​

  • วันที่: 2026-08-02
  • ผู้สังเกต: Claude
  • บริบท: การนำคีย์ i18next ที่แปลแล้ว 26 คีย์ไปใส่ครบทั้ง 36 ภาษาผ่านสกิล translate
  • สิ่งที่คาดไม่ถึง: สคริปต์เดียวมีกับดักสองแบบ แบบแรก scripts/update-translations.js แปลงเป้าหมายของตัวเองเป็น path.join(process.cwd(), "public", "translations") แต่ repo นี้เก็บงานแปลไว้ที่ about/public/translations การรันคำสั่งตามที่เอกสารระบุจาก root ของ repo จึงล้มเหลวทุกครั้งด้วยข้อความ "Translations directory not found" เพราะ docs/agent-playbooks/translations.md แสดงคำสั่งว่า node scripts/update-translations.js ... ซึ่งอ่านแล้วเหมือนคำสั่งที่รันจาก root ของ repo แบบที่สอง การเรียกแต่ละครั้งคือการอ่าน-แก้ไข-เขียนทับไฟล์ภาษาทั้ง 36 ไฟล์ การเรียกสองครั้งพร้อมกันจึงเขียนทับกันเอง แล้วคีย์หนึ่งจะหายไปโดยไม่มีข้อผิดพลาดใด ๆ ส่วนสกิล translate ก็สั่งอย่างชัดเจนให้แตกซับเอเจนต์พร้อมกันได้ถึง 4 ตัว ซึ่งแต่ละตัวจะเรียกสคริปต์นี้
  • ผลกระทบ: การรันจาก root ของ repo ล้มเหลวแบบเห็นชัดและเสียเวลาไปหนึ่งรอบเต็ม ส่วนปัญหาการรันพร้อมกันล้มเหลวแบบเงียบ ๆ คือคีย์หายไปจากภาษาแบบสุ่ม แต่ diff ยังดูสมเหตุสมผล
  • วิธีรับมือ: ให้รันเป็น cd about && node ../scripts/update-translations.js --key <key> --map <abs-path> --write อย่าปล่อยให้ซับเอเจนต์นักแปลเขียนไฟล์ภาษาพร้อมกันเด็ดขาด ให้แต่ละตัวสร้างเฉพาะไฟล์ JSON พจนานุกรม แล้วนำทุกคีย์ไปใส่ทีละตัวจากเอเจนต์แม่ หลังใส่เสร็จ ให้ตรวจด้วยโปรแกรมว่าทุกคีย์มีอยู่ครบในภาษาที่ไม่ใช่ภาษาอังกฤษทั้ง 35 ภาษา และไม่มีค่าใดที่เหมือนต้นฉบับภาษาอังกฤษทุกไบต์
  • สถานะ: ยืนยันแล้ว