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

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

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

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

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

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

ดูตัวอย่าง. tgwitness search, context, messages, stats และ export อ่าน ข้อมูลการสังเกตที่บันทึกไว้สำหรับสคริปต์และเอเยนต์ AI เครื่องมือนี้ไม่สามารถส่งข้อมูลใดๆ ไปยัง Telegram เปลี่ยนแปลงการตั้งค่า หรือแก้ไขสมุดบันทึกที่ลงนามได้

โดยใช้ --json, stdout ส่งเอกสาร JSON เพียงหนึ่งชิ้นเท่านั้น (export เขียน JSON Lines). ความคืบหน้า คำแนะนำ และข้อผิดพลาดจะถูกส่งไปยัง stderr รหัสออก (exit codes) มีความเสถียร:

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

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

ผ่านแผงควบคุม (--url) คำสั่งนี้ใช้ API ของคลังข้อมูลแบบจำกัดขอบเขตเดียวกันกับ MCP สร้างการเชื่อมต่อใน 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`	ข้อความที่บันทึกไว้ภายใน 10 ID ข้อความ ทั้งด้านหน้าและด้านหลัง
`tgwitness messages`	การสนทนาที่คุณสามารถอ่านได้
`tgwitness messages CHAT_ID [--since] [--until] [--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) ที่อื่น ๆ

การค้นหาตามอันดับจะหยุดที่ 1,000 ผลลัพธ์ หน้าสุดท้ายอาจสั้นกว่า --limit; ให้จำกัดการค้นหา แชท หรือช่วงเวลา เมื่อมีข้อมูลการสังเกตที่ตรงกันมากขึ้น

ผลลัพธ์ของทุกข้อความจะประกอบด้วย untrusted_content: trueID ของพื้นที่ทำงาน, ID ของห้องแชท และ ID ของข้อความ, ลำดับของบันทึก, ค่าแฮชของบันทึกที่เก็บไว้ และลิงก์ไปยังแผงควบคุม การแก้ไข, การแจ้งเตือนการลบ และ missing_on_recheck ถือเป็นบันทึกแยกต่างหาก การไม่มีบันทึก ไม่ได้เป็นหลักฐานว่าเหตุการณ์นั้นไม่เคยเกิดขึ้น

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

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

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

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

ส่งออก#

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

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

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

ทักษะของเอเจนต์#

.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 มีให้ใช้ได้กับทั้งสองระบบ