TgWitness / เอกสาร

สิ่งที่ได้รับการทดสอบแล้ว →

ส่วนหนึ่งของหน้านี้ยังคงเป็นภาษาอังกฤษ: เนื้อหาต้นฉบับภาษาอังกฤษได้เปลี่ยนแปลงไปหลังจากถูกแปล

อ้างอิง / การเก็บรักษาข้อมูลและการบูรณาการ

Telegram · บรรทัดคำสั่ง

ค้นหา อ่านบริบท นับกิจกรรม และส่งออกข้อความที่บันทึกไว้จากสคริปต์และเอเจนต์ ด้วยผลลัพธ์ --json รหัสออกที่เสถียร และโทเค็นอ่านอย่างเดียวที่มีขอบเขต

TgWitness / เอกสารประกอบ

การบูรณาการกับระบบเก็บถาวร

MCP แบบอ่านอย่างเดียว · การค้นหาข้อความเต็ม · Wiki

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 Lines). ความคืบหน้า คำแนะนำ และข้อผิดพลาดจะถูกส่งไปยัง stderr รหัสออก (exit codes) มีความเสถียร:

โค้ด ความหมาย
0 ผลลัพธ์ที่สำเร็จ รวมถึงผลลัพธ์ที่ว่าง
1 ข้อผิดพลาด: แผงควบคุมไม่สามารถเข้าถึงได้, ข้อมูลอ่านไม่ได้, การส่งออกถูกขัดจังหวะ
2 ข้อผิดพลาดในการใช้งานหรือคำขอไม่ถูกต้อง: วันที่ไม่ถูกต้อง, ตัวเลือกไม่รู้จัก, ดัชนีการค้นหาไม่ตรง
3 ไม่สามารถใช้งานได้ในขณะนี้: พื้นที่ทำงานเปิดอยู่ในแผงที่ทำงานอยู่ หรือแผงนั้นขอให้ลองใหม่ในภายหลัง (ข้อจำกัดอัตรา, เวลารอหมด)
4 การเข้าถึงถูกปฏิเสธ: โทเค็นขาดหาย หมดอายุ หรือถูกเพิกถอน การสนทนาอยู่นอกขอบเขต หรือเครื่องมือที่ไม่อนุญาต

สองวิธีในการอ่าน#

ผ่านแผงควบคุม (--url) คำสั่งนี้ใช้ API การเก็บถาวรแบบจำกัดขอบเขตเดียวกันกับ MCP. สร้างการเชื่อมต่อใน More tools → Integrations → 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] ข้อความที่บันทึกไว้ภายใน 10 ID ข้อความ ทั้งด้านหน้าและด้านหลัง
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 , พื้นที่ทำงาน, ID การสนทนาและ ID ข้อความ, ลำดับบันทึก, ค่าแฮชของบันทึกที่เก็บไว้ และลิงก์ไปยังแผงควบคุม การแก้ไข, การแจ้งเตือนการลบ และ missing_on_recheck เป็นบันทึกที่แยกต่างหาก ข้อมูลใน stats แสดงช่วงเวลาที่ผลการค้นหาครอบคลุม

สถิติกิจกรรม#

stats นับจำนวนข้อมูลการสังเกตที่บันทึกไว้สำหรับแชทหนึ่งแชท ผู้ส่งหนึ่งคน หรือทุกแชทในขอบเขต:

  • ข้อความตามชั่วโมง UTC และตามวันในสัปดาห์ (เริ่มจากวันจันทร์), ชั่วโมงและวันที่คึกคักที่สุด;
  • แก้ไข, ลบ และ missing_on_recheck แชร์;
  • ผู้ส่ง พร้อมด้วยจำนวนข้อความ และเวลาส่งข้อความแรกและสุดท้าย;
  • โดเมนที่ปรากฏบ่อยที่สุดและ @handles, นับครั้งเดียวต่อข้อความใน ทุกเวอร์ชันที่บันทึกไว้;
  • ขอบเขต: coverage.gap บันทึก และ เพื่อเข้าถึงพื้นที่ทำงานทั้งหมด ให้ระบุช่วงเวลา ที่ไม่มีสัญญาณชีพจากตัวเก็บข้อมูลที่เชื่อมต่อ (collector_liveness).

ช่วงเวลาดังกล่าวใช้เพื่อเลือกเวลาส่งข้อความที่ Telegram รายงาน การนับชั่วโมงและวันในสัปดาห์ ช่วยประมาณเขตเวลาของผู้ส่ง ตัวเลขถูกคำนวณตาม คำขอจากบันทึกและไม่ถูกเก็บไว้ ผลลัพธ์แต่ละรายการระบุชื่อหัวบันทึกที่ ครอบคลุมเมื่อการเข้าถึงของคุณครอบคลุมพื้นที่ทำงาน การอ่านจะหยุดลงหลังจาก 5 วินาทีผ่าน แผงควบคุม หรือ --timeout วินาทีในระบบท้องถิ่น (ค่าเริ่มต้น 30); หลังจากนั้น complete จะเป็น false และ partial จะระบุชื่อบันทึกแรกที่ยังไม่ได้อ่าน ในกรณีนี้ จะนับเฉพาะบันทึกที่ใหม่ที่สุดเท่านั้น

ส่งออก#

export บันทึก JSON หนึ่งอ็อบเจ็กต์ต่อข้อมูลการสังเกตที่บันทึกไว้ (ข้อความใหม่, ภาพถ่ายหน้าจอ, การแก้ไข, ข้อความที่กู้คืนได้, แจ้งเตือนการลบ, missing_on_recheck และบันทึกสื่อที่เก็บไว้ ตามลำดับในบันทึก แต่ละบรรทัดมีฟิลด์เดียวกันกับผลลัพธ์อื่น ๆ พร้อม ข้อความเต็ม ด้วย --output, ไฟล์จะถูกเขียนภายใต้ชื่อ .partial ชื่อ และ จะเปลี่ยนชื่อได้ก็ต่อเมื่อบันทึกการเสร็จสิ้นของคณะกรรมการ; การส่งออกที่ถูกขัดจังหวะจะไม่ทิ้ง ไฟล์ไว้และจะออกด้วยรหัส 1. --output ไม่เคยเขียนทับไฟล์ที่มีอยู่ ด้วย --output และ --json, stdout จะแสดงสรุป: จำนวนบันทึก, ลำดับวารสาร ล่าสุด และสำหรับสิทธิ์เข้าถึงพื้นที่ทำงานทั้งหมด จะแสดงส่วนหัวของวารสาร

การส่งออกผ่านแผงควบคุมต้องการการเชื่อมต่อที่อนุญาตให้ส่งข้อความ Export (เฉพาะบรรทัดคำสั่ง) ; ตัวเลือกนี้ไม่ถูกเลือกไว้เป็นค่าเริ่มต้น ไฟล์นี้เป็นสำเนาทำงาน; สำหรับการส่งต่อที่สามารถตรวจสอบได้ ให้ใช้การส่งออกที่ลงนามในส่วน Exports ซึ่งสามารถตรวจสอบได้โดยคำสั่ง python -m tgwitness.verify

แผงควบคุมจะตรวจสอบสิทธิ์การเข้าถึงอีกครั้งก่อนส่งแต่ละบันทึก รวมถึงบันทึก การเสร็จสิ้นด้วย สิทธิ์การเข้าถึงที่ถูกเพิกถอนหรือหมดอายุจะทำให้การส่งออกไม่สมบูรณ์ การอ่านหน้าแบบ Lazy จะแบ่งปันขีดจำกัดของ archive worker กับคำขออื่นๆ และมีเวลารอที่จำกัด

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 โหลดมันจาก repositori ที่ checkout แล้ว สำหรับ Claude Code ให้คัดลอก tgwitness-cli folder ไปยัง .claude/skills/ ใน โครงการของคุณ หรือ ~/.claude/skills/.

MCP และบรรทัดคำสั่ง#

ทั้งสองใช้การเชื่อมต่อ การตรวจสอบขอบเขต และข้อจำกัดเดียวกัน ผลลัพธ์ของ MCP ถูกจำกัดไว้ที่ หน้าเดียวขนาด 64 KiB ดังนั้น MCP จึงไม่รองรับการส่งออกข้อมูลแบบจำนวนมาก; ส่วนการส่งข้อมูลผ่านบรรทัดคำสั่งจะส่งข้อมูลแบบสตรีม get_activity_stats มีให้ใช้ได้กับทั้งสองระบบ