TgWitness / תיעוד

מה נבדק ←

חלקים מדף זה עדיין באנגלית: הטקסט המקורי באנגלית שונה לאחר תרגומו.

הפניה / ארכיון ושילובים

Telegram · שורת הפקודה

חפשו, קראו את ההקשר, ספרו פעילויות וייצאו הודעות שנשמרו באמצעות סקריפטים וסוכנים, עם פלט בפורמט --json, קודי יציאה יציבים ואסימוני קריאה בלבד בעלי תחום מוגדר.

TgWitness / תיעוד

שילוב עם מערכות ארכיונים

MCP לקריאה בלבד · חיפוש בטקסט מלא · ויקי

Preview. tgwitness search, context, messages, stats and export read saved observations for scripts and AI agents. They cannot send anything to Telegram, change settings or modify the signed journal. tgwitness index and tgwitness backup (below) work on a local data directory and need no token.

כאשר --json, stdout מעביר מסמך JSON אחד בלבד (export כותב שורות JSON). התקדמות, רמזים ושגיאות מועברים ל-stderr. קודי היציאה קבועים:

קוד משמעות
0 הצלחה, כולל תוצאה ריקה
1 כישלון: לוח בקרה בלתי נגיש, נתונים בלתי קריאים, ייצוא מופרע
2 שגיאת שימוש או בקשה לא חוקית: תאריך שגוי, אופציה לא מוכרת, אינדקס חיפוש כבוי
3 לא זמין כרגע: סביבת העבודה פתוחה בלוח פעיל, או שהלוח מבקש לנסות שוב מאוחר יותר (הגבלת קצב, פקיעת זמן)
4 גישה נדחתה: אסימון חסר, פג תוקפו או בוטל, צ'אט מחוץ לתחום, כלי שאינו מאפשר זאת

שתי דרכים לקריאה#

דרך הפאנל (--url). הפקודה משתמשת באותו ממשק API לארכיון מוגבל-היקף כמו MCP. צרו חיבור ב"כלים נוספים" → "אינטגרציות" → "MCP": בחרו סביבות עבודה וצ'אטים, כלים ותוקף, ולאחר מכן העתיקו את האסימון פעם אחת. החיבור הוא לקריאה בלבד, מוגבל לאותם צ'אטים, מוגבל לקצב של 60 בקשות בדקה וניתן לבטלו או להחליפו בכל עת. אסימוני כניסה ללוח הבקרה ופרטי הזדהות של Telegram אינם פועלים כאן.

export TGWITNESS_URL=https://panel.example.org      # default http://127.0.0.1:8787
export TGWITNESS_MCP_TOKEN=tgw_mcp_...              # or --token-file path
tgwitness search 'перевод карта' --json

לוח הבקרה המרוחק דורש HTTPS; HTTP רגיל מתקבל רק עבור 127.0.0.1, localhost ו- ::1. משתני סביבת פרוקסי מתעלמים והפניות נדחות, כך שהאסימון מגיע רק לכתובת שתציינו.

ישירות מסביבת עבודה מושבתת (--data-dir). קורא את ספריית הנתונים עם גישה מקומית מלאה, ללא אסימון. השתמשו בו על עותק של ספריית נתונים או בזמן שהאיסוף מושבת. רשומות חתומות לעולם אינן משתנות; כמו בלוח הבקרה, פתיחת סביבת עבודה עשויה לעדכן את האינדקסים הנגזרים ממנה. כאשר לוח הבקרה פותח את סביבת העבודה, הפקודה מסתיימת עם קוד 3; יש לקרוא דרך הפאנל במקום זאת. ללא --data-dir, TGWITNESS_DATA, ./data/live או ספריית הנתונים של ההתקנה שמריצה את הפקודה.

--workspace ID בוחר סביבת עבודה (ברירת מחדל default). tgwitness messages --workspaces מציג את אלה שאתה רשאי לקרוא.

פקודות#

פקודה תוצאה
tgwitness search QUERY [--chat ID] [--since] [--until] [--any] [--limit N] [--offset N] התוצאות המתאימות ביותר יופיעו ראשונות, כולל צורות מילים, ביטויים מדויקים במרכאות, דומיינים ו @username (תחביר)
tgwitness search QUERY --exact [--before SEQ] הטקסט המדויק, מהחדש ביותר תחילה, ללא האינדקס
tgwitness context CHAT_ID MESSAGE_ID [--limit N] [--before SEQ] הודעות שנשמרו בתוך עשרה מזהי הודעות משני הצדדים
tgwitness messages [--limit N] [--offset N] צ'אטים שניתן לקרוא
tgwitness messages CHAT_ID [--since] [--until] [--limit N] [--before SEQ] הודעות שנשמרו מהצ'אט, מהחדשות ביותר תחילה
tgwitness messages CHAT_ID --message ID כל גרסה שנשמרה וכל רישום מחיקה של הודעה אחת
tgwitness stats [--chat ID] [--sender ID] [--since] [--until] [--top N] סטטיסטיקות פעילות, להלן
tgwitness export [--chat ID] [--since] [--until] [--output FILE] תצפיות שנשמרו כ-JSON Lines לפי סדר היומן

התאריכים הם 2026-10-01 (חצות UTC) או לפי שעון ISO עם ציון אזור הזמן, 2026-10-01T09:00+03:00. לגבי search, messages ובמקרה export הם בוחרים את זמן התצפית. דפים מכילים עד 50 רשומות: עקבו next_offset (--offset) עבור חיפוש לפי דירוג ו next_before (--before) במקומות אחרים.

Ranked search stops at 1,000 results. The final page may be shorter than --limit. When more observations match, the last page says so (truncated: true with --json); narrow the query, chat or period.

כל תוצאת הודעה נושאת את untrusted_content: true , את מזהי סביבת העבודה, הצ'אט וה הודעה, את רצף היומן, את ה-hash של הרשומה השמורה וקישור ללוח הבקרה. עריכות, הודעות מחיקה ו-missing_on_recheck הן רשומות נפרדות. הכיסוי ב-stats מציג את התקופות שעליהן מדווחת תוצאת החיפוש.

סטטיסטיקות פעילות#

stats סופר תצפיות שנשמרו עבור צ'אט אחד, שולח אחד או כל הצ'אטים בתחום ההיקף:

  • הודעות לפי שעה UTC ולפי ימי השבוע (יום שני ראשון), השעות והימים העמוסים ביותר;
  • ערוך, נמחק ו missing_on_recheck שיתופים;
  • שולחים עם מספר ההודעות וזמני ההודעה הראשונה והאחרונה;
  • הדומיינים הנפוצים ביותר ו @handles, הנספרים פעם אחת לכל הודעה בכל הגרסאות השמורות שלה;
  • כיסוי: coverage.gap רשומות, ולצורך גישה לכל סביבת העבודה – תקופות בהן לא התקבל אות חיים מהאספן המחובר (collector_liveness).

התקופה בוחרת את זמן ההודעה המדווח על ידי Telegram. ספירת השעות וימי השבוע מסייעת להעריך את אזור הזמן של השולח. הנתונים מחושבים על פי בקשה מהיומן ואינם נשמרים. כל תוצאה מציינת את כותרת היומן שהיא מכסה כאשר הגישה שלך משתרעת על סביבת העבודה. הקריאה נעצרת לאחר חמש שניות דרך הלוח, או לאחר --timeout שניות באופן מקומי (ברירת מחדל 30); לאחר מכן complete הוא false ו- partial מציין את הרשומה הראשונה שלא נקראה. במקרה זה, רק הרשומות האחרונות נספרות.

ייצא#

export כותב אובייקט JSON אחד לכל תצפית שנשמרה (הודעות חדשות, צילומי מסך, עריכות, הודעות ששוחזרו, הודעות מחיקה, missing_on_recheck וקבצי מדיה שנשמרו) לפי סדר היומן. כל שורה מכילה את אותם שדות כמו תוצאות אחרות, כולל הטקסט המלא. כאשר --output, הקובץ נכתב תחת .partial שם ו משנה את שמו רק לאחר השלמת הרישום של הפאנל; ייצוא שנקטע אינו משאיר קובץ ויוצא עם קוד 1. --output לעולם לא מחליף קובץ קיים. באמצעות --output ו- --json, stdout נושא סיכום: מספר הרשומות, רצף היומן האחרון, ובמקרה של גישה לכל סביבת העבודה, ראש היומן.

ייצוא דרך הלוח דורש חיבור המאפשר ייצוא הודעות (שורת פקודה בלבד) ; אפשרות זו אינה נבחרת כברירת מחדל. קובץ זה הוא עותק עבודה; לצורך העברה הניתנת לאימות יש להשתמש בייצוא החתום תחת ייצואים , אשר נבדק באמצעות הפקודה python -m tgwitness.verify .

הלוח בודק מחדש את הגישה לפני שליחת כל רשומה, כולל רשומת ההשלמה. גישה שבוטלה או שפג תוקפה תותיר ייצוא לא שלם. קריאות דפים מושהות חולקות את מגבלת עובד הארכיון עם שאילתות אחרות וכפופות לזמן המתנה מוגבל.

Index and backup#

These two commands read the data directory directly and take no token or --url.

פקודה תוצאה
tgwitness index status [--workspace ID] [--data-dir DIR] [--json] Search index state of one workspace or, by default, every workspace: mode, ready, building or not built, indexed and journal head sequence. Works while the panel runs
tgwitness index rebuild [--workspace ID] [--data-dir DIR] [--json] Rebuilds the index from the first journal record. Rewrites only the derived index, never the signed journal. Exits with code 3 while the panel has the workspace open. Nothing is built when the workspace keeps its index in memory or has search off
tgwitness backup FOLDER [--data-dir DIR] [--json] Copies the whole data directory into a new or empty folder outside it while the panel keeps running, and writes backup-manifest.json with every file's SHA-256 and the journal heads

index accepts --workspace default or a workspace ID; the default is all. The backup skips temporary exports, SQLite sidecar files and lock files. The folder holds the Telegram session and signing keys, so keep it as private as the data directory. Backup, restore, and capacity describes restoring and what the next start records.

מיומנות הסוכן#

.agents/skills/tgwitness-cli/SKILL.md מסביר לסוכן כיצד להשתמש בפקודות אלה, כיצד לצטט רשומות וכיצד לטפל בטקסט שנלכד. סוכנים שקוראים .agents/skills טוענים אותו ממאגר שנבדק. עבור Claude Code, העתיקו את tgwitness-cli התיקייה .claude/skills/ בתוך הפרויקט שלכם או ~/.claude/skills/.

MCP ושורת הפקודה#

שניהם משתמשים באותם חיבורים, בדיקות היקף ומגבלות. תוצאות ה-MCP מוגבלות לדף אחד בגודל 64 KiB, ולכן ה-MCP אינו מציע ייצוא בכמות גדולה; שורת הפקודה מעבירה את הנתונים בזרם. get_activity_stats זמינה לשניהם.