מפתחים
תורמים ל-ai-memory
עד עכשיו 101 אנשים הכניסו קוד. הדף הזה לוקח אתכם מרעיון אל ה-issue הנכון, אל ה-crate הנכון ואל pull request שעובר review בפעם הראשונה.
פרויקט פעיל, במספרים
הספירות מגיעות מה-API של GitHub בזמן שהאתר נבנה.
התורמים המובילים
akitaonrails
djalmajr
samirhvbr
lucasliet
wblech
rthiago
matheus-rodrigues00
lhzapata
gabrielscharb
pablowinck
aguirreSL
evanmaranzano
kevin9327
gb
mrpaiva
rafaelkenedy
lihuiyang1024
rodrigopalhares
felipe-NR
abhisheksharma2411
Cardosaum
vitorvilas
mobnix
Murillofilho86
viniciusdsandrade
atirna
pedrofjr
enrell
zanlucathiago
davividal
alanhoff
alvadorn
milesibastos
klebervirgilio
iagogfe
dk96-creator
juniorgaudencio00-code
PedroPCardoso
marcelomogami
lucazz
jpramos123
cateim
Gaalbu
bcosta19
BobDylans
victorcesc
Wprosdocimo
XiaoHuo888-hue
adrianogomes-NE
azevedo-luis
cristianodewes
luisfnicolau
omartelo
wslcb
holocaster
rpaggi
murilojrpereiras
LuizFernando991
jaysonsantos
בחירת דרך כניסה
כל אחת מהן מובילה בדיוק לדף הנכון ב-GitHub.
מדווחים על באג
התבנית מבקשת את הגרסה, מערכת ההפעלה, הסוכן, ה-transport ושורות הלוג הרלוונטיות של השרת.
פתיחת דיווח על באגמציעים פיצ'ר
הצעות הן issues, כי ל-repository אין לוח discussions. התבנית שואלת איזו בעיה זה פותר ואם זה ישבור התקנות קיימות.
פתיחת בקשה לפיצ'רמוצאים issue ראשון
התווית good first issue מסמנת עבודה שמתאימה למי שחדש בפרויקט. help wanted מסמנת את השאר.
ל-good first issuesמוסיפים או מתקנים harness
לתמיכה ב-harness מנוהל יש פרוטוקול כתוב: מוכיחים את חוזה הסשן הנייטיב, קוראים מאגרים לקריאה בלבד, מעבירים הקשר לפני שמאשרים אותו, ומצרפים את הטסטים הנדרשים.
לפרוטוקול ה-harnessמשפרים את התיעוד
המדריכים יושבים ב-docs/ כ-markdown. תיקון תיעוד הוא pull request רגיל, והוא מדלג על יומן השינויים כששום דבר שגלוי למשתמש לא משתנה.
לתיקיית docs/בונים מסביב
importers, ממשקי משתמש עשירים יותר וממשקי צ'אט שייכים לפרויקטים נלווים (companion) שמשתמשים בממשקי ה-HTTP וה-MCP הציבוריים.
לכללי ה-companion
מגיעים ל-build שעובד
ה-build עומד בפני עצמו. אף אחת מהפקודות האלה לא צריכה משתנה סביבה.
עושים clone ו-build
נדרש Rust 1.95, והוא מקובע ב-
rust-toolchain.tomlיחד עם rustfmt ו-clippy, כך ש-rustup מתקין את ה-toolchain הנכון ב-build הראשון. SQLite מגיע ארוז בפנים ו-libgit2 הוא vendored. צריך toolchain סטנדרטי של C ושום דבר מעבר לזה.סביבת פיתוח git clone https://github.com/akitaonrails/ai-memory cd ai-memory cargo build --workspace cargo test --workspace --all-targetsעובדים עם הלולאה היומיומית
cargo tצריך את nextest:cargo install cargo-nextest --locked. הוא מדלג על מודולים בשםslowאוstress, שה-pre-push hook וה-CI עדיין מריצים.תוך כדי עבודה cargo t # הכול חוץ מהשכבה האיטית, כ-20 שניות כשה-cache חם cargo t -p ai-memory-store # crate אחד: בונה רק את קובצי הטסט שלו cargo t -E 'test(/purge/)' # נושא אחד (בונה הכול, מריץ תת-קבוצה)מתקינים את ה-pre-push hook
פעם אחת לכל clone. הוא נוגע רק בבלוק של עצמו בתוך
.git/hooks/pre-push. ב-branch של עבודה בתהליך,git push --no-verifyמדלג עליו.פעם אחת לכל clone scripts/install-git-hooks.shעוברים את בדיקות החובה לפני push
ה-CI אוכף את כל החמש. בלי nextest, הפקודה
cargo test --workspace --all-targetsשקולה ל-cargo tf. אם האחרונה חסרה:cargo install cargo-deny cargo-audit.בדיקות החובה cargo fmt --all -- --check git diff --check cargo clippy --workspace --all-targets -- -D warnings cargo tf # כל הטסטים (alias: cargo nextest run -P full) cargo deny check # מדיניות תלויותבודקים על שם מי ה-commits שלכם רשומים
משתמשים באימייל שאומת בחשבון ה-GitHub שלכם, או בכתובת ה-noreply שלו. ההיסטוריה ב-main אף פעם לא נכתבת מחדש כדי לתקן ייחוס.
ייחוס של commits git log --format='%h %an <%ae>' "$(git merge-base HEAD origin/main)"..HEAD
כללי היסוד ורף הקבלה
AGENTS.md הוא קובץ הכללים הקנוני, לאנשים ולסוכני קוד. CONTRIBUTING.md מתמצת אותו לזה.
איך עבודה אמורה להיכנס
יומן השינויים הוא תנאי ל-merge
כל שינוי שגלוי למשתמש מוסיף רשומה תחת [Unreleased] באותו pull request. רשומה חסרה חוסמת את ה-review. refactors ושינויים בטסטים בלבד פטורים.
טסטים לפני "גמור"
עבודה נחשבת גמורה כשיש לה טסטים, ובראש ובראשונה parsers, גזירת מזהים וחישובי ה-retention.
בלי קוד מת, בלי פיצ'רים חצי בנויים
stubs מתועדים בהערת המודול, יחד עם אבן הדרך שתשלים אותם.
נשארים בתוך גבולות השינוי
לא עושים refactor לקוד שאבן הדרך הנוכחית לא צריכה.
הערות מסבירות למה
הערה שחוזרת על השורה שמעליה נמחקת.
אינווריאנטים ש-pull request לא יכול לשבור
- כל הכתיבות ל-SQLite עוברות דרך ה-writer actor היחיד,
WriterHandle. - הקונפיגורציה נקראת פעם אחת בעלייה. אין
std::env::varמחוץ ל-Config::load. - כתיבות לקבצים הן אטומיות: tmp, rename, fsync. אף פעם לא במקום.
- כל דף ויקי משויך ל-namespace של
(workspace_id, project_id). - ה-CLI הוא לקוח HTTP דק. הוא אף פעם לא פותח את קובץ ה-SQLite או את תיקיית הוויקי.
מפה של בסיס הקוד
עשרה crates נכנסים לקובץ הבינארי. לכל אחד יש אחריות אחת ו-API מטופס, ואין תלויות מעגליות.
| Crate | מה יושב שם |
|---|---|
ai-memory-core | טיפוסי הדומיין, שגיאות ומזהים. בלי IO. |
ai-memory-store | SQLite, ה-writer actor, מאגר הקוראים וחישובי הדעיכה. |
ai-memory-wiki | כתיבות markdown אטומיות, ה-file watcher ו-git. |
ai-memory-mcp | ה-transport של MCP, נתב הכלים ונתיבי הניהול. |
ai-memory-hooks | סכמות ה-payload של ה-hooks, ה-sanitizer וה-endpoint של /hook. |
ai-memory-llm | גבול האימות מול הספקים וה-traits של ה-LLM ושל ה-embedder. |
ai-memory-consolidate | הזנה, lint, sweep וה-pipeline של auto-improve. |
ai-memory-web | הדפדפן לקריאה בלבד ב-/web ונתיבי ה-JSON של /api/v1. |
ai-memory-workstream | קוראים לקריאה בלבד של תמלילים נייטיב, ומתאמי ההפעלה שמאחורי ai-memory run. |
ai-memory-cli | הקובץ הבינארי ai-memory ותת-הפקודות הדקות שלו מעל HTTP. |
מחוץ ל-crates/
| תיקייה | מה יושב שם |
|---|---|
companions/ | ai-memory-importer, חבילה עצמאית מחוץ ל-workspace הראשי. בונים אותה עם --manifest-path. |
hooks/ | חבילות hooks של מחזור החיים, תיקייה לכל סוכן, ב-shell ונייטיב. |
evals/ | ה-harness של הבנצ'מרק. חבר ב-workspace שאף פעם לא משוחרר. |
docs/ | ארכיטקטורה, החלטות תכנון, ומדריכי התקנה, פריסה ושימוש. |
tests/ | טסטי smoke מקצה לקצה, טסטי shell של ה-hooks ו-fixtures. |
טסטי האינטגרציה יושבים ב-tests/suite/ בתוך כל crate. עזרים שמשותפים לכמה crates נכנסים ל-crates/ai-memory-test-support, שאף פעם לא משוחרר.
איך עושים review ל-pull requests
ה-review הולך לפי תבנית ה-pull request, אז מילוי כן שלה הוא רוב העבודה.
התבנית היא ה-checklist
היא שואלת מה השתנה, למה, מה תוכנית הבדיקות עם בדיקות החובה מסומנות, ייחוס ה-commits, ההשפעה על הגרסה ורשומת יומן השינויים.
אומרים איזה סוג גרסה זה
מסמנים patch, minor או major. תיקון שנרשם תחת "Added" עלול להקפיץ את הגרסה הלא נכונה, אז שמים את הרשומה ביומן השינויים תחת הכותרת הנכונה.
שינויים שוברים מחכים ל-major
מציינים אותם בתיאור. הם מקבלים את התווית breaking-change ומתוזמנים, כך שהם לא מעכבים גרסאות patch ו-minor.
ה-CI מהיר בכל merge
merge מותנה ב-jobs המהירים של Linux. ה-jobs של macOS ושל Windows רצים לפי תווית, מדי לילה או ידנית, ותמיד לפני גרסה.
תיקונים יוצאים ראשונים
תיקון באג יוצא בגרסת ה-patch הבאה ולא מחכה לעבודה על פיצ'רים. harness חדש או ספק חדש יוצאים ב-minor הבא.
pull request של harness מריץ את הבדיקה המקוצרת הזאת, רושם מול איזו גרסת CLI הוא נבדק, וכולל מעבר ידני מול ה-harness האמיתי.
cargo fmt --check
git diff --check
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
נסו אותו לפני שמשנים אותו.
מריצים אותו יום אחד על הפרויקטים שלכם. הבאג שתמצאו הוא ה-issue הראשון שלכם.