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

Canonical page: https://phishdestroy.github.io/TgWitness/th/docs/reference/cli/

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

[Project context and measured scale](https://phishdestroy.github.io/TgWitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.github.io/TgWitness/th/llms.txt)

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

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [เอกสารประกอบ](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md)

![การบูรณาการกับระบบเก็บถาวร](https://phishdestroy.github.io/TgWitness/assets/chapter-integrations.svg)

[MCP แบบอ่านอย่างเดียว](https://phishdestroy.github.io/TgWitness/th/docs/reference/mcp/) · [การค้นหาข้อความเต็ม](https://phishdestroy.github.io/TgWitness/th/docs/reference/search/) · [Wiki](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

**ดูตัวอย่าง.** `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` ([ไวยากรณ์](https://phishdestroy.github.io/TgWitness/th/docs/reference/search/#search-syntax)) |
| `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: true`ID ของพื้นที่ทำงาน, 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`](https://github.com/phishdestroy/TgWitness/blob/main/.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` มีให้ใช้ได้กับทั้งสองระบบ