Μετάβαση στο κύριο περιεχόμενο

Γνωστές εκπλήξεις

Αυτό το αρχείο καταγράφει σημεία σύγχυσης που αφορούν ειδικά αυτό το αποθετήριο και έχουν προκαλέσει λάθη σε πράκτορες.

Κριτήρια καταχώρισης​

Προσθέστε μια καταχώριση μόνο αν ισχύουν όλα τα παρακάτω:

  • Αφορά ειδικά αυτό το αποθετήριο (δεν είναι γενική συμβουλή).
  • Είναι πιθανό να ξανασυμβεί σε μελλοντικούς πράκτορες.
  • Έχει συγκεκριμένη αντιμετώπιση που μπορεί κανείς να ακολουθήσει.

Αν δεν είστε βέβαιοι, ρωτήστε τον προγραμματιστή πριν προσθέσετε καταχώριση.

Πρότυπο καταχώρισης​

### [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

Καταχωρίσεις​

Τα production domains των εφαρμογών στο Vercel μπορούν να ξαναγυρίσουν σε deployments του Git master​

  • Ημερομηνία: 2026-04-28
  • Παρατηρήθηκε από: Tommaso + Codex
  • Πλαίσιο: Επαλήθευση των mirrors των εφαρμογών Seedit και 5chan στον κατάλογο εφαρμογών του Bitsocial Web.
  • Τι ήταν απροσδόκητο: Τα έργα seedit και 5chan στο Vercel είχαν gitProviderOptions.createDeployments = "enabled", οπότε τα pushes στο master του GitHub προωθούνταν στα production domains, παρότι η πολιτική του αποθετηρίου προβλέπει ότι τα production mirrors των εφαρμογών σερβίρουν μόνο artifacts εκδόσεων.
  • Επίπτωση: Τα σήματα επαληθευμένου mirror στον κατάλογο εφαρμογών μπορεί να γίνουν ψευδή, επειδή τα production domains σερβίρουν το τελευταίο commit ανάπτυξης αντί για το ZIP της έκδοσης στο GitHub, του οποίου το hash του index.html είναι καταγεγραμμένο στο about/src/lib/apps-data.ts.
  • Αντιμετώπιση: Πριν προσθέσετε ή ανανεώσετε μεταδεδομένα επαλήθευσης mirror, ελέγξτε το έργο στο Vercel με vercel api /v9/projects/<project-id> και επιβεβαιώστε ότι ισχύει gitProviderOptions.createDeployments = "disabled". Κάντε deploy τα περιεχόμενα του ZIP της έκδοσης με vercel deploy --prebuilt --prod και χρησιμοποιήστε τα seedit-omega.vercel.app ή 5chan-omega.vercel.app για deployments ανάπτυξης.
  • Κατάσταση: επιβεβαιωμένο

Το Portless 0.11 επαναχρησιμοποιεί παλαιά κατάσταση proxy εκτός αν ο launcher επιβάλλει HTTPS​

  • Ημερομηνία: 2026-04-28
  • Παρατηρήθηκε από: Tommaso + Codex
  • Πλαίσιο: Αναβάθμιση της κανονικής ροής yarn start από το παλιό URL proxy http://bitsocial.localhost:1355 στο https://bitsocial.localhost.
  • Τι ήταν απροσδόκητο: Ακόμη και με εγκατεστημένο το portless@0.11.1, το Portless επαναχρησιμοποίησε το υπάρχον HTTP proxy ~/.portless/proxy.port = 1355 και τύπωσε το παλιό URL με :1355.
  • Επίπτωση: Η ενημέρωση των εκδόσεων των πακέτων και της τεκμηρίωσης δεν αρκεί· το yarn start μπορεί να εξακολουθεί να διαφημίζει και να χρησιμοποιεί το παλιό URL όταν ένας συνεργάτης έχει σε λειτουργία παλαιά κατάσταση του Portless.
  • Αντιμετώπιση: Φροντίστε τα scripts εκκίνησης να ξεκινούν ρητά το HTTPS proxy του Portless στη θύρα 443 πριν καταχωρίσουν τις διαδρομές των εφαρμογών, ώστε η ροή εκτέλεσης να απομακρύνεται από την αποθηκευμένη κατάσταση 1355 αντί να την κληρονομεί.
  • Κατάσταση: επιβεβαιωμένο

Το Portless αλλάζει το κανονικό τοπικό URL της εφαρμογής​

  • Ημερομηνία: 2026-03-18
  • Παρατηρήθηκε από: Codex
  • Πλαίσιο: Επαλήθευση στο πρόγραμμα περιήγησης και ροές smoke ελέγχου
  • Τι ήταν απροσδόκητο: Το προεπιλεγμένο τοπικό URL δεν είναι η συνηθισμένη θύρα του Vite. Το αποθετήριο περιμένει το https://bitsocial.localhost μέσω Portless, οπότε ο έλεγχος στο localhost:3000 ή στο localhost:5173 μπορεί να χτυπήσει λάθος εφαρμογή ή τίποτα απολύτως.
  • Επίπτωση: Οι έλεγχοι στο πρόγραμμα περιήγησης μπορεί να αποτύχουν ή να επαληθεύσουν λάθος στόχο ακόμη και όταν ο dev server λειτουργεί κανονικά.
  • Αντιμετώπιση: Χρησιμοποιήστε πρώτα το https://bitsocial.localhost σε κάθε έλεγχο. Παρακάμψτε το με PORTLESS=0 corepack yarn start μόνο όταν χρειάζεστε ρητά μια απευθείας θύρα του Vite.
  • Κατάσταση: επιβεβαιωμένο

Τα hooks του Commitizen μπλοκάρουν τα μη διαδραστικά commits​

  • Ημερομηνία: 2026-03-18
  • Παρατηρήθηκε από: Codex
  • Πλαίσιο: Ροές commit που εκτελούνται από πράκτορες
  • Τι ήταν απροσδόκητο: Το git commit ενεργοποιεί το Commitizen μέσω Husky και περιμένει διαδραστική είσοδο από TTY, πράγμα που κολλάει τα μη διαδραστικά shells των πρακτόρων.
  • Επίπτωση: Οι πράκτορες μπορεί να μείνουν επ' αόριστον σε αναμονή σε αυτό που θα έπρεπε να είναι ένα απλό commit.
  • Αντιμετώπιση: Χρησιμοποιήστε git commit --no-verify -m "message" για commits που δημιουργούν πράκτορες. Οι άνθρωποι μπορούν να συνεχίσουν να χρησιμοποιούν corepack yarn commit ή corepack yarn exec cz.
  • Κατάσταση: επιβεβαιωμένο

Το Corepack είναι απαραίτητο για να αποφευχθεί το Yarn classic​

  • Ημερομηνία: 2026-03-19
  • Παρατηρήθηκε από: Codex
  • Πλαίσιο: Μετάβαση του package manager στο Yarn 4
  • Τι ήταν απροσδόκητο: Το μηχάνημα έχει ακόμη καθολική εγκατάσταση του Yarn classic στο PATH, οπότε η εκτέλεση σκέτου yarn μπορεί να καταλήξει στην v1 αντί για την καρφιτσωμένη έκδοση Yarn 4.
  • Επίπτωση: Οι προγραμματιστές μπορούν κατά λάθος να παρακάμψουν το καρφίτσωμα του package manager στο αποθετήριο και να πάρουν διαφορετική συμπεριφορά εγκατάστασης ή διαφορετικό αποτέλεσμα στο lockfile.
  • Αντιμετώπιση: Χρησιμοποιήστε corepack yarn ... στις εντολές του shell ή εκτελέστε πρώτα corepack enable, ώστε το σκέτο yarn να καταλήγει στην καρφιτσωμένη έκδοση Yarn 4.
  • Κατάσταση: επιβεβαιωμένο

Τα σταθερά ονόματα εφαρμογών του Portless συγκρούονται μεταξύ των worktrees του Bitsocial Web​

  • Ημερομηνία: 2026-03-30
  • Παρατηρήθηκε από: Codex
  • Πλαίσιο: Εκκίνηση του yarn start σε ένα worktree του Bitsocial Web ενώ ένα άλλο worktree σέρβιρε ήδη μέσω Portless
  • Τι ήταν απροσδόκητο: Η χρήση του κυριολεκτικού ονόματος εφαρμογής bitsocial στο Portless για κάθε worktree κάνει την ίδια τη διαδρομή να συγκρούεται, ακόμη κι όταν οι υποκείμενες θύρες διαφέρουν, οπότε η δεύτερη διεργασία αποτυγχάνει επειδή το bitsocial.localhost είναι ήδη καταχωρισμένο.
  • Επίπτωση: Παράλληλοι κλάδοι του Bitsocial Web μπορούν να μπλοκάρουν ο ένας τον άλλον, παρότι το Portless υποτίθεται ότι τους επιτρέπει να συνυπάρχουν με ασφάλεια.
  • Αντιμετώπιση: Κρατήστε την εκκίνηση του Portless πίσω από το scripts/start-dev.mjs, το οποίο πλέον χρησιμοποιεί μια διαδρομή *.bitsocial.localhost με βάση τον κλάδο εκτός της κανονικής περίπτωσης και επιστρέφει σε διαδρομή με βάση τον κλάδο όταν το σκέτο όνομα bitsocial.localhost είναι ήδη κατειλημμένο.
  • Κατάσταση: επιβεβαιωμένο

Η προεπισκόπηση της τεκμηρίωσης είχε παλιότερα σταθερά ορισμένη τη θύρα 3001​

  • Ημερομηνία: 2026-03-30
  • Παρατηρήθηκε από: Codex
  • Πλαίσιο: Εκτέλεση του yarn start παράλληλα με άλλα τοπικά αποθετήρια και πράκτορες
  • Τι ήταν απροσδόκητο: Η εντολή ανάπτυξης στη ρίζα εκτελούσε το workspace της τεκμηρίωσης με docusaurus start --port 3001, οπότε ολόκληρη η συνεδρία ανάπτυξης αποτύγχανε όποτε μια άλλη διεργασία κατείχε ήδη τη 3001, παρότι η κύρια εφαρμογή χρησιμοποιούσε ήδη Portless.
  • Επίπτωση: Το yarn start μπορούσε να σκοτώσει τη διεργασία του web αμέσως μετά την εκκίνησή της, διακόπτοντας άσχετη τοπική εργασία εξαιτίας μιας σύγκρουσης θύρας της τεκμηρίωσης.
  • Αντιμετώπιση: Κρατήστε την εκκίνηση της τεκμηρίωσης πίσω από το yarn start:docs, το οποίο πλέον χρησιμοποιεί Portless μαζί με το scripts/start-docs.mjs για να τιμήσει μια ελεύθερη θύρα που του δίνεται ή να πέσει στην επόμενη διαθέσιμη θύρα όταν εκτελείται απευθείας.
  • Κατάσταση: επιβεβαιωμένο

Το σταθερό hostname του Portless για την τεκμηρίωση ήταν γραμμένο κυριολεκτικά στον κώδικα​

  • Ημερομηνία: 2026-04-03
  • Παρατηρήθηκε από: Codex
  • Πλαίσιο: Εκτέλεση του yarn start σε δευτερεύον worktree του Bitsocial Web ενώ ένα άλλο worktree σέρβιρε ήδη την τεκμηρίωση μέσω Portless
  • Τι ήταν απροσδόκητο: Το start:docs καταχωρούσε ακόμη το κυριολεκτικό hostname docs.bitsocial.localhost, οπότε το yarn start μπορούσε να αποτύχει παρότι η εφαρμογή about ήξερε ήδη πώς να αποφεύγει τις συγκρούσεις διαδρομών του Portless για το δικό της hostname.
  • Επίπτωση: Τα παράλληλα worktrees δεν μπορούσαν να χρησιμοποιήσουν αξιόπιστα την εντολή ανάπτυξης της ρίζας, επειδή η διεργασία της τεκμηρίωσης τερμάτιζε πρώτη και στη συνέχεια το concurrently σκότωνε την υπόλοιπη συνεδρία.
  • Αντιμετώπιση: Κρατήστε την εκκίνηση της τεκμηρίωσης πίσω από το scripts/start-docs.mjs, το οποίο πλέον παράγει το ίδιο hostname Portless με βάση τον κλάδο όπως η εφαρμογή about και εισάγει αυτό το κοινό δημόσιο URL στον στόχο του dev proxy για το /docs.
  • Κατάσταση: επιβεβαιωμένο

Τα shells των worktrees μπορεί να χάσουν την καρφιτσωμένη έκδοση Node του αποθετηρίου​

  • Ημερομηνία: 2026-04-03
  • Παρατηρήθηκε από: Codex
  • Πλαίσιο: Εκτέλεση του yarn start σε worktrees του Git, όπως τα .claude/worktrees/* ή γειτονικά checkouts worktree
  • Τι ήταν απροσδόκητο: Κάποια shells worktree ανέλυαν τα node και yarn node στο Node 25.2.1 του Homebrew, παρότι το αποθετήριο καρφιτσώνει την 22.12.0 στο .nvmrc, οπότε το yarn start μπορούσε σιωπηλά να τρέξει τους launchers ανάπτυξης σε λάθος runtime.
  • Επίπτωση: Η συμπεριφορά του dev server μπορεί να αποκλίνει ανάμεσα στο κύριο checkout και στα worktrees, κάνοντας τα σφάλματα δύσκολα στην αναπαραγωγή και παραβιάζοντας την αναμενόμενη αλυσίδα εργαλείων Node 22 του αποθετηρίου.
  • Αντιμετώπιση: Κρατήστε τους launchers ανάπτυξης πίσω από τα scripts/start-dev.mjs και scripts/start-docs.mjs, τα οποία πλέον επανεκτελούνται με το εκτελέσιμο Node του .nvmrc όταν το τρέχον shell βρίσκεται σε λάθος έκδοση. Η ρύθμιση του shell θα πρέπει να προτιμά ούτως ή άλλως το nvm use.
  • Κατάσταση: επιβεβαιωμένο

Τα υπολείμματα του docs-site/ μπορούν να κρύψουν πηγαία αρχεία τεκμηρίωσης που λείπουν μετά την αναδιάρθρωση​

  • Ημερομηνία: 2026-04-01
  • Παρατηρήθηκε από: Codex
  • Πλαίσιο: Καθαρισμός του monorepo μετά τη συγχώνευση, όταν το έργο Docusaurus μεταφέρθηκε από το docs-site/ στο docs/
  • Τι ήταν απροσδόκητο: Ο παλιός φάκελος docs-site/ μπορεί να παραμείνει στον δίσκο με ξεπερασμένα αλλά σημαντικά αρχεία, όπως το i18n/, ακόμη κι αφότου το παρακολουθούμενο αποθετήριο μετακόμισε στο docs/. Αυτό κάνει την αναδιάρθρωση να μοιάζει διπλή τοπικά και μπορεί να κρύψει το γεγονός ότι οι παρακολουθούμενες μεταφράσεις της τεκμηρίωσης δεν μεταφέρθηκαν πραγματικά στο docs/.
  • Επίπτωση: Οι πράκτορες μπορεί να διαγράψουν τον παλιό φάκελο ως «σκουπίδια» και να χάσουν κατά λάθος το μοναδικό τοπικό αντίγραφο των μεταφράσεων της τεκμηρίωσης, ή να συνεχίσουν να επεξεργάζονται scripts που δείχνουν ακόμη στη νεκρή διαδρομή docs-site/.
  • Αντιμετώπιση: Θεωρήστε το docs/ ως το μοναδικό κανονικό έργο τεκμηρίωσης. Πριν διαγράψετε οποιαδήποτε τοπικά υπολείμματα του docs-site/, επαναφέρετε παρακολουθούμενο πηγαίο υλικό όπως το docs/i18n/ και ενημερώστε scripts και hooks ώστε να σταματήσουν να αναφέρονται στο docs-site.
  • Κατάσταση: επιβεβαιωμένο

Η πολυγλωσσική προεπισκόπηση της τεκμηρίωσης μπορεί να εκτινάξει τη χρήση RAM κατά την επαλήθευση​

  • Ημερομηνία: 2026-04-01
  • Παρατηρήθηκε από: Codex
  • Πλαίσιο: Διόρθωση του i18n της τεκμηρίωσης, της δρομολόγησης locale και της συμπεριφοράς του Pagefind με yarn start:docs σε συνδυασμό με Playwright
  • Τι ήταν απροσδόκητο: Η προεπιλεγμένη λειτουργία προεπισκόπησης της τεκμηρίωσης κάνει πλέον πλήρες πολυγλωσσικό build μαζί με ευρετηρίαση Pagefind πριν σερβίρει, και η διατήρηση αυτής της διεργασίας ζωντανής παράλληλα με πολλές συνεδρίες Playwright ή Chrome μπορεί να καταναλώσει πολύ περισσότερη RAM από έναν συνηθισμένο κύκλο ανάπτυξης με Vite ή με Docusaurus σε μία γλώσσα.
  • Επίπτωση: Το μηχάνημα μπορεί να μείνει από μνήμη, οι συνεδρίες του προγράμματος περιήγησης μπορεί να καταρρεύσουν, και οι διακοπτόμενες εκτελέσεις μπορεί να αφήσουν πίσω ξεχασμένους servers τεκμηρίωσης ή headless προγράμματα περιήγησης που συνεχίζουν να καταναλώνουν μνήμη.
  • Αντιμετώπιση: Για εργασία στην τεκμηρίωση που δεν χρειάζεται επαλήθευση διαδρομών locale ή Pagefind, προτιμήστε DOCS_START_MODE=live yarn start:docs. Χρησιμοποιήστε την προεπιλεγμένη πολυγλωσσική προεπισκόπηση μόνο όταν χρειάζεται να επικυρώσετε μεταφρασμένες διαδρομές ή το Pagefind. Κρατήστε μία μόνο συνεδρία Playwright, κλείστε τις παλιές συνεδρίες πριν ανοίξετε νέες και σταματήστε τον server της τεκμηρίωσης μετά την επαλήθευση αν δεν τον χρειάζεστε πια.
  • Κατάσταση: επιβεβαιωμένο

Το translate-docs.py μπορεί να αφήσει τα locales της τεκμηρίωσης μισομεταφρασμένα ή με χαλασμένους στόχους συνδέσμων​

  • Ημερομηνία: 2026-04-06
  • Παρατηρήθηκε από: Codex
  • Πλαίσιο: Διόρθωση τοπικοποιημένων διαδρομών και περιεχομένου της τεκμηρίωσης, αφότου το yarn start:docs σέρβιρε αγγλικές σελίδες λεπτομερειών ή απέτυχε να παραγάγει έξοδο για κάποιο locale
  • Τι ήταν απροσδόκητο: Ο μηχανισμός μετάφρασης της τεκμηρίωσης είχε ταυτόχρονα δύο τρόπους αστοχίας ειδικούς για αυτό το αποθετήριο: το scripts/translate-docs.py εξήγαγε μόνο ένα μικρό υποσύνολο των μηνυμάτων του DocsHome όταν οι κλήσεις tr(...) χρησιμοποιούσαν μορφές που δεν ανέλυε, και το μεταφρασμένο markdown κάτω από το docs/i18n/** μπορούσε να περιέχει μηχανικά μεταφρασμένα slugs ή κατάλοιπα ZXQPLACEHOLDER μέσα σε στόχους συνδέσμων.
  • Επίπτωση: Οι τοπικοποιημένες αρχικές σελίδες μπορεί να πέφτουν σιωπηλά πίσω στα αγγλικά, οι τοπικοποιημένες σελίδες λεπτομερειών μπορεί να φαίνονται αμετάφραστες, και το πλήρες yarn docs:build μπορεί να αποτύχει σε χαλασμένους συνδέσμους locale ακόμη κι όταν η πηγαία τεκμηρίωση είναι έγκυρη.
  • Αντιμετώπιση: Μετά από αλλαγές στις μεταφράσεις της τεκμηρίωσης ή αναπαραγωγή των αρχείων locale, εκτελείτε πάντα yarn docs:build από τη ρίζα του αποθετηρίου, σαρώστε το markdown στο docs/i18n/** για ZXQPLACEHOLDER και επαληθεύστε ότι οι μεταφρασμένοι σύνδεσμοι εξακολουθούν να δείχνουν σε κανονικά slugs τεκμηρίωσης, όπως το /apps/5chan/, αντί για μεταφρασμένες διαδρομές URL. Αν άλλαξε το κείμενο του DocsHome, επιβεβαιώστε ότι το scripts/translate-docs.py εξακολουθεί να εξάγει όλα τα μηνύματα docs.home.*.
  • Κατάσταση: επιβεβαιωμένο

Οι έλεγχοι χωρίς JS στο site about πρέπει να χρησιμοποιούν τη διαδρομή Portless, όχι μια αυτόνομη προεπισκόπηση SSR​

  • Ημερομηνία: 2026-04-12
  • Παρατηρήθηκε από: Codex
  • Πλαίσιο: Επαλήθευση της υποστήριξης χωρίς JS για το site about/ από ένα worktree κλάδου
  • Τι ήταν απροσδόκητο: Μια αυτόνομη προεπισκόπηση SSR μπορεί να φαίνεται υγιής ενώ η πραγματική διαδρομή Portless με βάση τον κλάδο σερβίρει ακόμη λάθος κέλυφος εφαρμογής ή μια παλαιότερη διεργασία. Σε αυτό το αποθετήριο, το πραγματικό τοπικό συμβόλαιο είναι το hostname Portless από το yarn start, όχι ένας πρόχειρος server προεπισκόπησης.
  • Επίπτωση: Οι πράκτορες μπορεί να ισχυριστούν λανθασμένα ότι η υποστήριξη χωρίς JS λειτουργεί, ή να χάσουν παλινδρομήσεις που εμφανίζονται μόνο στο *.bitsocial.localhost.
  • Αντιμετώπιση: Για επαλήθευση του about/ στο πρόγραμμα περιήγησης, ξεκινάτε πάντα τον πραγματικό τοπικό server με yarn start ή yarn start:about και δοκιμάζετε πρώτα το URL Portless με βάση τον κλάδο. Αν ένα hostname Portless φαίνεται ξεπερασμένο, εξετάστε και σταματήστε την παλιά διεργασία πριν ξαναδοκιμάσετε.
  • Κατάσταση: επιβεβαιωμένο

Το chain/ ήταν αόρατο για τα yarn build:verify και yarn doctor​

  • Ημερομηνία: 2026-07-05
  • Παρατηρήθηκε από: Codex
  • Πλαίσιο: Επαλήθευση ενός diff που αφορούσε μόνο το chain, αφότου το workspace chain/ (αυτόνομη εφαρμογή Vite για το chain.bitsocial.net) προστέθηκε στο monorepo.
  • Τι ήταν απροσδόκητο: Το scripts/verify-build.mjs αναγνώριζε μόνο τα προθέματα διαδρομών about/, docs/ και stats/, οπότε ένα diff που αφορούσε μόνο το chain τύπωνε "No targeted build checks matched the current diff" και δεν έτρεχε κανένα build, παρότι το build:chain υπήρχε ήδη στο package.json της ρίζας. Χωριστά, το yarn doctor ήταν σταθερά ορισμένο σε react-doctor about -y, οπότε οι αλλαγές React κάτω από το chain/src δεν είχαν καμία κάλυψη από το React Doctor.
  • Επίπτωση: Οι πράκτορες που επαλήθευαν αλλαγές στο chain έπρεπε να ξέρουν ότι πρέπει να καλέσουν απευθείας yarn build:chain αντί να εμπιστευτούν το yarn build:verify, και τα ζητήματα React στο chain/src (effects, hooks, νεκρός κώδικας) περνούσαν απαρατήρητα από το yarn doctor.
  • Αντιμετώπιση: Το scripts/verify-build.mjs έχει πλέον κλάδο για το chain/ αντίστοιχο εκείνου του about/, και τα doctor / doctor:verbose εκτελούν πλέον react-doctor --project about,chain -y σε μία κλήση. Το doctor:score παραμένει μόνο για το about, επειδή το --score δεν τυπώνει τίποτα σιωπηλά όταν συνδυάζεται με --project για περισσότερα από ένα έργα· χρησιμοποιήστε yarn react-doctor --project about,chain --verbose -y (ή --json) αν χρειάζεται σκορ για το chain.
  • Κατάσταση: επιβεβαιωμένο

Το P2P στο πρόγραμμα περιήγησης λειτουργεί με ασφαλή WebSockets· το pkc-js απορρίπτει WebRTC και WebTransport από προεπιλογή​

  • Ημερομηνία: 2026-08-02
  • Παρατηρήθηκε από: Claude
  • Πλαίσιο: Συγγραφή κειμένου για τη σελίδα προορισμού και την τεκμηρίωση σχετικά με το πώς λειτουργεί το P2P του Bitsocial στο πρόγραμμα περιήγησης
  • Τι ήταν απροσδόκητο: Το @pkcprotocol/pkc-js περιλαμβάνει έναν προεπιλεγμένο connection gater που απορρίπτει κλήσεις WebRTC και WebTransport στο πρόγραμμα περιήγησης — το dist/browser/helia/dial-transport-filter.js εξάγει DENIED_DIAL_TRANSPORTS_BY_DEFAULT = ["webrtc", "webrtc-direct", "webtransport"]. Το σχόλιο στον πηγαίο κώδικα εξηγεί τον λόγο: στο πρόγραμμα περιήγησης αυτά τα transports προσθέτουν μεγάλες διαδρομές εγκαθίδρυσης σύνδεσης που συχνά αποτυγχάνουν (STUN/ICE, εναλλαγή certhash) και επιβραδύνουν τη φόρτωση, ενώ το WebSocket είναι άμεσο και αξιόπιστο. Κάθε ζωντανό peer στον πίνακα κατάστασης P2P του blog εμφανίζει "Secure WebSocket". Ο gater βρίσκεται στο node_modules, οπότε τίποτα μέσα στο αποθετήριο δεν το υποδεικνύει.
  • Επίπτωση: Είναι πολύ εύκολο να γραφτεί δημόσιο κείμενο που ακούγεται τεχνικά εύλογο αλλά είναι λανθασμένο — για παράδειγμα, να αποδοθεί στο WebTransport, που έφτασε σε επίπεδο Baseline στα προγράμματα περιήγησης τον Μάρτιο του 2026, το ότι κατέστησε δυνατό το P2P του Bitsocial στο πρόγραμμα περιήγησης. Αυτός ο ισχυρισμός έφτασε στη σελίδα προορισμού, στον πίνακα σύγκρισης και σε δύο σελίδες τεκμηρίωσης προτού τον εντοπίσει ο προγραμματιστής. Οι λανθασμένοι ισχυρισμοί για την αρχιτεκτονική σε δημόσιες σελίδες ελέγχονται ακριβώς από το κοινό προγραμματιστών στο οποίο απευθύνεται το site.
  • Αντιμετώπιση: Ποτέ μη συμπεραίνετε ποια transports χρησιμοποιεί το Bitsocial από αυτά που υποστηρίζουν κατ' αρχήν το libp2p ή η πλατφόρμα του προγράμματος περιήγησης. Ελέγξτε το node_modules/@pkcprotocol/pkc-js/dist/browser/helia/dial-transport-filter.js για την τρέχουσα λίστα απόρριψης, επιβεβαιώστε ότι δεν υπάρχει παράκαμψη connectionGater κάτω από το about/src/, και διαβάστε τις ζωντανές ετικέτες transport στον πίνακα "P2P status" του blog πριν διατυπώσετε οποιονδήποτε δημόσιο ισχυρισμό. Η αλλαγή στα ανάντη έργα που πραγματικά ξεκλείδωσε τη δημοσίευση από το πρόγραμμα περιήγησης ήταν η διόρθωση του μονότονου seqno στο gossipsub, στην έκδοση @libp2p/gossipsub 15.0.21 (Μάιος 2026)· το pkc-js σήμερα περιλαμβάνει την 16.0.4.
  • Κατάσταση: επιβεβαιωμένο

Οι σχετικοί σύνδεσμοι ./page.md από μια αμετάφραστη σελίδα τεκμηρίωσης χαλούν κάθε τοπικοποιημένο build​

  • Ημερομηνία: 2026-08-02
  • Παρατηρήθηκε από: Claude
  • Πλαίσιο: Προσθήκη μιας νέας σελίδας μόνο στα αγγλικά, της docs/browser-p2p.md, που παρέπεμπε σε υπάρχουσα τεκμηρίωση με ./peer-to-peer-protocol.md και ./apps/5chan.md
  • Τι ήταν απροσδόκητο: Κάθε locale κάτω από το docs/i18n/<lang>/docusaurus-plugin-content-docs/current/ αντικατοπτρίζει το δέντρο της τεκμηρίωσης. Μια νέα σελίδα που λείπει από αυτά τα αντίγραφα εξακολουθεί να εμφανίζεται σε κάθε locale μέσω της αγγλικής εφεδρείας, αλλά οι σχετικοί σύνδεσμοι markdown της δεν επιλύονται πλέον — το Docusaurus παράγει /ar/browser-p2p/peer-to-peer-protocol.md/ και αποτυγχάνει στο build με "Docusaurus found broken links!". Κρίσιμο σημείο: τα yarn build:verify και yarn docs:build:verify χτίζουν μόνο το en και περνούν καθαρά· μόνο ένα πλήρες yarn docs:build το αποκαλύπτει, και ματαιώνεται στο πρώτο locale αλφαβητικά (ar).
  • Επίπτωση: Μια αλλαγή στην τεκμηρίωση μπορεί να περάσει κάθε γρήγορο τοπικό έλεγχο και παρ' όλα αυτά να χαλάσει το πολυγλωσσικό build της παραγωγής. Η αποτυχία μοιάζει επίσης άσχετη με την αλλαγή, καθώς το σφάλμα αναφέρει μια διαδρομή locale που ο συντάκτης δεν άγγιξε ποτέ.
  • Αντιμετώπιση: Σε κάθε σελίδα τεκμηρίωσης που δεν αντικατοπτρίζεται στο docs/i18n/**, χρησιμοποιήστε συνδέσμους σχετικούς με τη ρίζα (/peer-to-peer-protocol/, /apps/5chan/) αντί για σχετικούς συνδέσμους .md· το Docusaurus τους προσθέτει αυτόματα το πρόθεμα του locale. Το docs/build-your-own-client.md είναι το υπάρχον παράδειγμα. Εκτελέστε ένα πλήρες yarn docs:build — όχι μόνο το build:verify — πριν παραδώσετε οποιαδήποτε αλλαγή που προσθέτει ή συνδέει μια σελίδα τεκμηρίωσης.
  • Κατάσταση: επιβεβαιωμένο

Το update-translations.js πρέπει να εκτελείται από το about/, και οι ταυτόχρονες εκτελέσεις χάνουν σιωπηλά κλειδιά​

  • Ημερομηνία: 2026-08-02
  • Παρατηρήθηκε από: Claude
  • Πλαίσιο: Εφαρμογή 26 μεταφρασμένων κλειδιών i18next σε όλα τα 36 locales μέσω του skill translate
  • Τι ήταν απροσδόκητο: Δύο ξεχωριστές παγίδες στο ίδιο script. Πρώτον, το scripts/update-translations.js υπολογίζει τον στόχο του ως path.join(process.cwd(), "public", "translations"), αλλά αυτό το αποθετήριο κρατά τις μεταφράσεις στο about/public/translations. Η εκτέλεση της τεκμηριωμένης εντολής από τη ρίζα του αποθετηρίου αποτυγχάνει σε κάθε κλήση με "Translations directory not found" — το docs/agent-playbooks/translations.md δείχνει node scripts/update-translations.js ..., που διαβάζεται ως εντολή από τη ρίζα του αποθετηρίου. Δεύτερον, κάθε κλήση είναι μια ακολουθία ανάγνωσης, τροποποίησης και εγγραφής πάνω σε όλα τα 36 αρχεία locale, οπότε δύο κλήσεις που τρέχουν ταυτόχρονα αλληλοακυρώνονται και ένα κλειδί εξαφανίζεται χωρίς κανένα σφάλμα. Το skill translate δίνει ρητά οδηγία να δημιουργούνται έως 4 υποπράκτορες ταυτόχρονα, καθένας από τους οποίους θα καλούσε το script.
  • Επίπτωση: Η μορφή από τη ρίζα του αποθετηρίου αποτυγχάνει θορυβωδώς και σπαταλά ένα ολόκληρο πέρασμα. Το ζήτημα της ταυτοχρονίας αποτυγχάνει σιωπηλά: κλειδιά λείπουν από τυχαία locales, και το diff εξακολουθεί να φαίνεται εύλογο.
  • Αντιμετώπιση: Εκτελέστε το ως cd about && node ../scripts/update-translations.js --key <key> --map <abs-path> --write. Μην αφήνετε ποτέ τους υποπράκτορες μετάφρασης να γράφουν αρχεία locale ταυτόχρονα — ζητήστε τους να παράγουν μόνο αρχεία JSON λεξικού και έπειτα εφαρμόστε κάθε κλειδί σειριακά από τον γονικό πράκτορα. Μετά την εφαρμογή, επαληθεύστε προγραμματιστικά ότι κάθε κλειδί υπάρχει και στα 35 μη αγγλικά locales και ότι καμία τιμή δεν είναι πανομοιότυπη σε επίπεδο byte με την αγγλική πηγή.
  • Κατάσταση: επιβεβαιωμένο