discord-message-cli 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- discord_message_cli-0.1.0/PKG-INFO +177 -0
- discord_message_cli-0.1.0/README.md +168 -0
- discord_message_cli-0.1.0/pyproject.toml +20 -0
- discord_message_cli-0.1.0/setup.cfg +4 -0
- discord_message_cli-0.1.0/src/discord_message_cli.egg-info/PKG-INFO +177 -0
- discord_message_cli-0.1.0/src/discord_message_cli.egg-info/SOURCES.txt +19 -0
- discord_message_cli-0.1.0/src/discord_message_cli.egg-info/dependency_links.txt +1 -0
- discord_message_cli-0.1.0/src/discord_message_cli.egg-info/entry_points.txt +2 -0
- discord_message_cli-0.1.0/src/discord_message_cli.egg-info/requires.txt +3 -0
- discord_message_cli-0.1.0/src/discord_message_cli.egg-info/top_level.txt +1 -0
- discord_message_cli-0.1.0/src/discord_msg/__init__.py +3 -0
- discord_message_cli-0.1.0/src/discord_msg/aggregator.py +149 -0
- discord_message_cli-0.1.0/src/discord_msg/auth.py +59 -0
- discord_message_cli-0.1.0/src/discord_msg/cli.py +259 -0
- discord_message_cli-0.1.0/src/discord_msg/client.py +319 -0
- discord_message_cli-0.1.0/src/discord_msg/config.py +50 -0
- discord_message_cli-0.1.0/src/discord_msg/errors.py +60 -0
- discord_message_cli-0.1.0/src/discord_msg/formatter.py +100 -0
- discord_message_cli-0.1.0/src/discord_msg/time_utils.py +122 -0
- discord_message_cli-0.1.0/tests/test_acceptance.py +405 -0
- discord_message_cli-0.1.0/tests/test_cli_and_auth.py +113 -0
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: discord-message-cli
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Read-only Discord channel message aggregation CLI for humans and AI agents
|
|
5
|
+
License: MIT
|
|
6
|
+
Requires-Python: >=3.10
|
|
7
|
+
Description-Content-Type: text/markdown
|
|
8
|
+
Requires-Dist: tzdata; sys_platform == "win32"
|
|
9
|
+
|
|
10
|
+
# Discord Message CLI (`discord-msg`)
|
|
11
|
+
|
|
12
|
+
権限を持つ Discord チャンネルのメッセージを Discord 公式 HTTP API (v10) で**読み取り専用**で取得し、期間別の集計を行う CLI ツールです。
|
|
13
|
+
人がターミナルで表を確認するほか、AI エージェントやスクリプトが JSON 形式で安全に集計情報だけを取得できるように設計されています。
|
|
14
|
+
|
|
15
|
+
## 特徴とセキュリティ方針
|
|
16
|
+
|
|
17
|
+
- **読み取り専用**: `GET /channels/{channel_id}/messages` のみを使用し、投稿・編集・削除・権限変更の機能は一切持ちません。
|
|
18
|
+
- **本文・添付の非出力**: 接続確認(`check`)および期間集計(`stats`)の出力(表・JSON ともに)には、メッセージ本文・添付ファイル・トークンを一切含めません。
|
|
19
|
+
- **安全なトークン入力**: Bot トークンは環境変数(`DISCORD_BOT_TOKEN`)、対話的な非表示入力(`--prompt-token`)、または標準入力(`--token-stdin`)からのみ受け付けます。コマンドライン引数や設定ファイルには保存・指定できません。
|
|
20
|
+
- **標準出力と標準エラーの分離**: 診断メッセージやエラーはすべて標準エラー(`stderr`)に出力され、標準出力(`stdout`)には完全な結果(表または JSON)のみが出力されます。取得途中で失敗した場合は、不完全な集計を標準出力に出さず非ゼロ終了コードで終了します。
|
|
21
|
+
|
|
22
|
+
## 導入方法
|
|
23
|
+
|
|
24
|
+
Python 3.10 以上が必要です。`pipx` または `pip` でワンコマンド導入できます。
|
|
25
|
+
|
|
26
|
+
```powershell
|
|
27
|
+
# PyPI から導入する場合(推奨)
|
|
28
|
+
pipx install discord-message-cli
|
|
29
|
+
# または
|
|
30
|
+
pip install discord-message-cli
|
|
31
|
+
|
|
32
|
+
# GitHub リポジトリから直接導入する場合
|
|
33
|
+
pipx install git+https://github.com/IT-Engineer-K/discord-message-cli.git
|
|
34
|
+
|
|
35
|
+
# ローカルのクローンから導入する場合
|
|
36
|
+
pipx install .
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## 認証設定
|
|
40
|
+
|
|
41
|
+
実行前に環境変数 `DISCORD_BOT_TOKEN` を設定するか、実行時に `--prompt-token` を指定してください。
|
|
42
|
+
|
|
43
|
+
```powershell
|
|
44
|
+
# PowerShell で一時的に環境変数へ設定する例
|
|
45
|
+
$env:DISCORD_BOT_TOKEN = (Read-Host -AsSecureString "Bot Token" | ConvertFrom-SecureString -AsPlainText)
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
> **必要な Discord Bot 権限**:
|
|
49
|
+
> 対象チャンネルに対する `View Channel`(チャンネルを見る)および `Read Message History`(メッセージ履歴を読む)。
|
|
50
|
+
> ※ 接頭辞(`--prefix`)やキーワード(`--keyword`)による本文絞り込みを行う場合は、Discord Developer Portal で Bot の **Message Content Intent** を有効にしてください。
|
|
51
|
+
|
|
52
|
+
## 使い方
|
|
53
|
+
|
|
54
|
+
### 1. 接続確認 (`check`)
|
|
55
|
+
|
|
56
|
+
対象チャンネルの履歴を読み取れるかを確認し、本文を表示せずに結果を返します。
|
|
57
|
+
|
|
58
|
+
```powershell
|
|
59
|
+
# 表形式(既定)
|
|
60
|
+
discord-msg check --channel 123456789012345678
|
|
61
|
+
|
|
62
|
+
# AI / スクリプト向け JSON 形式
|
|
63
|
+
discord-msg check --channel 123456789012345678 --format json
|
|
64
|
+
|
|
65
|
+
# トークンを対話的非表示入力で渡す場合
|
|
66
|
+
discord-msg check --channel 123456789012345678 --prompt-token
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
JSON 出力例:
|
|
70
|
+
|
|
71
|
+
```json
|
|
72
|
+
{
|
|
73
|
+
"ok": true,
|
|
74
|
+
"channel_id": "123456789012345678",
|
|
75
|
+
"reachable": true,
|
|
76
|
+
"history_readable": true,
|
|
77
|
+
"has_messages": true
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### 2. 期間別集計 (`stats`)
|
|
82
|
+
|
|
83
|
+
指定期間のメッセージ件数を集計します。
|
|
84
|
+
|
|
85
|
+
- **既定期間**: 直近 24 時間(`--since` / `--until` / `--hours` で変更可能。**開始時刻を含み、終了時刻は含まない** `[start, end)`)
|
|
86
|
+
- **既定タイムゾーン**: 日本時間 `Asia/Tokyo`(`--tz` で変更可能)
|
|
87
|
+
- **集計単位 (`--by`)**: `hour`(時間別・既定)、`day`(日別)、`total`(合計のみ)
|
|
88
|
+
- **絞り込み**: `--prefix`(本文の接頭辞)、`--keyword`(本文に含まれるキーワード)、`--ignore-case`(大文字・小文字を区別しない)
|
|
89
|
+
|
|
90
|
+
```powershell
|
|
91
|
+
# 直近24時間の時間別集計(日本時間・表形式)
|
|
92
|
+
discord-msg stats --channel 123456789012345678
|
|
93
|
+
|
|
94
|
+
# 期間と接頭辞・キーワードを指定して AI 向け JSON で取得
|
|
95
|
+
discord-msg stats `
|
|
96
|
+
--channel 123456789012345678 `
|
|
97
|
+
--since 2026-11-18T00:00:00+09:00 `
|
|
98
|
+
--until 2026-11-19T00:00:00+09:00 `
|
|
99
|
+
--by hour `
|
|
100
|
+
--prefix "[ALERT]" `
|
|
101
|
+
--keyword "DiskHigh" `
|
|
102
|
+
--format json
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
JSON 出力例:
|
|
106
|
+
|
|
107
|
+
```json
|
|
108
|
+
{
|
|
109
|
+
"channel_id": "123456789012345678",
|
|
110
|
+
"period": {
|
|
111
|
+
"start": "2026-11-18T09:00:00+09:00",
|
|
112
|
+
"end": "2026-11-18T12:00:00+09:00"
|
|
113
|
+
},
|
|
114
|
+
"timezone": "Asia/Tokyo",
|
|
115
|
+
"granularity": "hour",
|
|
116
|
+
"filter": {
|
|
117
|
+
"prefix": "[ALERT]",
|
|
118
|
+
"keyword": "DiskHigh",
|
|
119
|
+
"ignore_case": false
|
|
120
|
+
},
|
|
121
|
+
"buckets": [
|
|
122
|
+
{
|
|
123
|
+
"label": "2026-11-18 09:00",
|
|
124
|
+
"start": "2026-11-18T09:00:00+09:00",
|
|
125
|
+
"end": "2026-11-18T10:00:00+09:00",
|
|
126
|
+
"count": 2
|
|
127
|
+
},
|
|
128
|
+
{
|
|
129
|
+
"label": "2026-11-18 10:00",
|
|
130
|
+
"start": "2026-11-18T10:00:00+09:00",
|
|
131
|
+
"end": "2026-11-18T11:00:00+09:00",
|
|
132
|
+
"count": 0
|
|
133
|
+
},
|
|
134
|
+
{
|
|
135
|
+
"label": "2026-11-18 11:00",
|
|
136
|
+
"start": "2026-11-18T11:00:00+09:00",
|
|
137
|
+
"end": "2026-11-18T12:00:00+09:00",
|
|
138
|
+
"count": 3
|
|
139
|
+
}
|
|
140
|
+
],
|
|
141
|
+
"total": 5,
|
|
142
|
+
"scanned_in_period": 8
|
|
143
|
+
}
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
## ローカル設定ファイル(任意・非機密値のみ)
|
|
147
|
+
|
|
148
|
+
毎回 `--channel` を指定する代わりに、環境変数 `DISCORD_CHANNEL_ID` またはローカル設定ファイル(Windows の既定パス: `%APPDATA%\discord-msg\config.json`)に既定のチャンネル ID とタイムゾーンを記述できます。
|
|
149
|
+
※ セキュリティ保護のため、設定ファイルに `token` / `bot_token` キーが含まれている場合はエラーとして拒否します。
|
|
150
|
+
|
|
151
|
+
```json
|
|
152
|
+
{
|
|
153
|
+
"channel": "123456789012345678",
|
|
154
|
+
"tz": "Asia/Tokyo"
|
|
155
|
+
}
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
## 終了コード一覧
|
|
159
|
+
|
|
160
|
+
| 終了コード | エラーコード | 意味 |
|
|
161
|
+
| :--- | :--- | :--- |
|
|
162
|
+
| `0` | - | 正常終了(履歴が空の場合も含む) |
|
|
163
|
+
| `2` | `INVALID_ARGS` | 引数・期間指定・設定ファイルの形式エラー |
|
|
164
|
+
| `3` | `AUTH_FAILED` | トークン未指定または認証失敗 (`401 Unauthorized`) |
|
|
165
|
+
| `4` | `PERMISSION_DENIED` | チャンネル閲覧・履歴読み取り権限不足 (`403 Forbidden`) |
|
|
166
|
+
| `5` | `NOT_FOUND` | チャンネルが存在しないかアクセス不可 (`404 Not Found`) |
|
|
167
|
+
| `6` | `RATE_LIMITED` | レート制限の再試行上限超過 (`429 Too Many Requests`) |
|
|
168
|
+
| `7` | `FETCH_FAILED` | 通信エラーやページ送り途中の API エラー(不完全な集計は返さない) |
|
|
169
|
+
|
|
170
|
+
## テストの実行
|
|
171
|
+
|
|
172
|
+
テストにはすべて架空のチャンネル ID・架空の通知データを使用しており、外部通信を行わずに実行できます。
|
|
173
|
+
|
|
174
|
+
```powershell
|
|
175
|
+
$env:PYTHONPATH="src"
|
|
176
|
+
python -m unittest discover -s tests -v
|
|
177
|
+
```
|
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
# Discord Message CLI (`discord-msg`)
|
|
2
|
+
|
|
3
|
+
権限を持つ Discord チャンネルのメッセージを Discord 公式 HTTP API (v10) で**読み取り専用**で取得し、期間別の集計を行う CLI ツールです。
|
|
4
|
+
人がターミナルで表を確認するほか、AI エージェントやスクリプトが JSON 形式で安全に集計情報だけを取得できるように設計されています。
|
|
5
|
+
|
|
6
|
+
## 特徴とセキュリティ方針
|
|
7
|
+
|
|
8
|
+
- **読み取り専用**: `GET /channels/{channel_id}/messages` のみを使用し、投稿・編集・削除・権限変更の機能は一切持ちません。
|
|
9
|
+
- **本文・添付の非出力**: 接続確認(`check`)および期間集計(`stats`)の出力(表・JSON ともに)には、メッセージ本文・添付ファイル・トークンを一切含めません。
|
|
10
|
+
- **安全なトークン入力**: Bot トークンは環境変数(`DISCORD_BOT_TOKEN`)、対話的な非表示入力(`--prompt-token`)、または標準入力(`--token-stdin`)からのみ受け付けます。コマンドライン引数や設定ファイルには保存・指定できません。
|
|
11
|
+
- **標準出力と標準エラーの分離**: 診断メッセージやエラーはすべて標準エラー(`stderr`)に出力され、標準出力(`stdout`)には完全な結果(表または JSON)のみが出力されます。取得途中で失敗した場合は、不完全な集計を標準出力に出さず非ゼロ終了コードで終了します。
|
|
12
|
+
|
|
13
|
+
## 導入方法
|
|
14
|
+
|
|
15
|
+
Python 3.10 以上が必要です。`pipx` または `pip` でワンコマンド導入できます。
|
|
16
|
+
|
|
17
|
+
```powershell
|
|
18
|
+
# PyPI から導入する場合(推奨)
|
|
19
|
+
pipx install discord-message-cli
|
|
20
|
+
# または
|
|
21
|
+
pip install discord-message-cli
|
|
22
|
+
|
|
23
|
+
# GitHub リポジトリから直接導入する場合
|
|
24
|
+
pipx install git+https://github.com/IT-Engineer-K/discord-message-cli.git
|
|
25
|
+
|
|
26
|
+
# ローカルのクローンから導入する場合
|
|
27
|
+
pipx install .
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## 認証設定
|
|
31
|
+
|
|
32
|
+
実行前に環境変数 `DISCORD_BOT_TOKEN` を設定するか、実行時に `--prompt-token` を指定してください。
|
|
33
|
+
|
|
34
|
+
```powershell
|
|
35
|
+
# PowerShell で一時的に環境変数へ設定する例
|
|
36
|
+
$env:DISCORD_BOT_TOKEN = (Read-Host -AsSecureString "Bot Token" | ConvertFrom-SecureString -AsPlainText)
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
> **必要な Discord Bot 権限**:
|
|
40
|
+
> 対象チャンネルに対する `View Channel`(チャンネルを見る)および `Read Message History`(メッセージ履歴を読む)。
|
|
41
|
+
> ※ 接頭辞(`--prefix`)やキーワード(`--keyword`)による本文絞り込みを行う場合は、Discord Developer Portal で Bot の **Message Content Intent** を有効にしてください。
|
|
42
|
+
|
|
43
|
+
## 使い方
|
|
44
|
+
|
|
45
|
+
### 1. 接続確認 (`check`)
|
|
46
|
+
|
|
47
|
+
対象チャンネルの履歴を読み取れるかを確認し、本文を表示せずに結果を返します。
|
|
48
|
+
|
|
49
|
+
```powershell
|
|
50
|
+
# 表形式(既定)
|
|
51
|
+
discord-msg check --channel 123456789012345678
|
|
52
|
+
|
|
53
|
+
# AI / スクリプト向け JSON 形式
|
|
54
|
+
discord-msg check --channel 123456789012345678 --format json
|
|
55
|
+
|
|
56
|
+
# トークンを対話的非表示入力で渡す場合
|
|
57
|
+
discord-msg check --channel 123456789012345678 --prompt-token
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
JSON 出力例:
|
|
61
|
+
|
|
62
|
+
```json
|
|
63
|
+
{
|
|
64
|
+
"ok": true,
|
|
65
|
+
"channel_id": "123456789012345678",
|
|
66
|
+
"reachable": true,
|
|
67
|
+
"history_readable": true,
|
|
68
|
+
"has_messages": true
|
|
69
|
+
}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### 2. 期間別集計 (`stats`)
|
|
73
|
+
|
|
74
|
+
指定期間のメッセージ件数を集計します。
|
|
75
|
+
|
|
76
|
+
- **既定期間**: 直近 24 時間(`--since` / `--until` / `--hours` で変更可能。**開始時刻を含み、終了時刻は含まない** `[start, end)`)
|
|
77
|
+
- **既定タイムゾーン**: 日本時間 `Asia/Tokyo`(`--tz` で変更可能)
|
|
78
|
+
- **集計単位 (`--by`)**: `hour`(時間別・既定)、`day`(日別)、`total`(合計のみ)
|
|
79
|
+
- **絞り込み**: `--prefix`(本文の接頭辞)、`--keyword`(本文に含まれるキーワード)、`--ignore-case`(大文字・小文字を区別しない)
|
|
80
|
+
|
|
81
|
+
```powershell
|
|
82
|
+
# 直近24時間の時間別集計(日本時間・表形式)
|
|
83
|
+
discord-msg stats --channel 123456789012345678
|
|
84
|
+
|
|
85
|
+
# 期間と接頭辞・キーワードを指定して AI 向け JSON で取得
|
|
86
|
+
discord-msg stats `
|
|
87
|
+
--channel 123456789012345678 `
|
|
88
|
+
--since 2026-11-18T00:00:00+09:00 `
|
|
89
|
+
--until 2026-11-19T00:00:00+09:00 `
|
|
90
|
+
--by hour `
|
|
91
|
+
--prefix "[ALERT]" `
|
|
92
|
+
--keyword "DiskHigh" `
|
|
93
|
+
--format json
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
JSON 出力例:
|
|
97
|
+
|
|
98
|
+
```json
|
|
99
|
+
{
|
|
100
|
+
"channel_id": "123456789012345678",
|
|
101
|
+
"period": {
|
|
102
|
+
"start": "2026-11-18T09:00:00+09:00",
|
|
103
|
+
"end": "2026-11-18T12:00:00+09:00"
|
|
104
|
+
},
|
|
105
|
+
"timezone": "Asia/Tokyo",
|
|
106
|
+
"granularity": "hour",
|
|
107
|
+
"filter": {
|
|
108
|
+
"prefix": "[ALERT]",
|
|
109
|
+
"keyword": "DiskHigh",
|
|
110
|
+
"ignore_case": false
|
|
111
|
+
},
|
|
112
|
+
"buckets": [
|
|
113
|
+
{
|
|
114
|
+
"label": "2026-11-18 09:00",
|
|
115
|
+
"start": "2026-11-18T09:00:00+09:00",
|
|
116
|
+
"end": "2026-11-18T10:00:00+09:00",
|
|
117
|
+
"count": 2
|
|
118
|
+
},
|
|
119
|
+
{
|
|
120
|
+
"label": "2026-11-18 10:00",
|
|
121
|
+
"start": "2026-11-18T10:00:00+09:00",
|
|
122
|
+
"end": "2026-11-18T11:00:00+09:00",
|
|
123
|
+
"count": 0
|
|
124
|
+
},
|
|
125
|
+
{
|
|
126
|
+
"label": "2026-11-18 11:00",
|
|
127
|
+
"start": "2026-11-18T11:00:00+09:00",
|
|
128
|
+
"end": "2026-11-18T12:00:00+09:00",
|
|
129
|
+
"count": 3
|
|
130
|
+
}
|
|
131
|
+
],
|
|
132
|
+
"total": 5,
|
|
133
|
+
"scanned_in_period": 8
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## ローカル設定ファイル(任意・非機密値のみ)
|
|
138
|
+
|
|
139
|
+
毎回 `--channel` を指定する代わりに、環境変数 `DISCORD_CHANNEL_ID` またはローカル設定ファイル(Windows の既定パス: `%APPDATA%\discord-msg\config.json`)に既定のチャンネル ID とタイムゾーンを記述できます。
|
|
140
|
+
※ セキュリティ保護のため、設定ファイルに `token` / `bot_token` キーが含まれている場合はエラーとして拒否します。
|
|
141
|
+
|
|
142
|
+
```json
|
|
143
|
+
{
|
|
144
|
+
"channel": "123456789012345678",
|
|
145
|
+
"tz": "Asia/Tokyo"
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
## 終了コード一覧
|
|
150
|
+
|
|
151
|
+
| 終了コード | エラーコード | 意味 |
|
|
152
|
+
| :--- | :--- | :--- |
|
|
153
|
+
| `0` | - | 正常終了(履歴が空の場合も含む) |
|
|
154
|
+
| `2` | `INVALID_ARGS` | 引数・期間指定・設定ファイルの形式エラー |
|
|
155
|
+
| `3` | `AUTH_FAILED` | トークン未指定または認証失敗 (`401 Unauthorized`) |
|
|
156
|
+
| `4` | `PERMISSION_DENIED` | チャンネル閲覧・履歴読み取り権限不足 (`403 Forbidden`) |
|
|
157
|
+
| `5` | `NOT_FOUND` | チャンネルが存在しないかアクセス不可 (`404 Not Found`) |
|
|
158
|
+
| `6` | `RATE_LIMITED` | レート制限の再試行上限超過 (`429 Too Many Requests`) |
|
|
159
|
+
| `7` | `FETCH_FAILED` | 通信エラーやページ送り途中の API エラー(不完全な集計は返さない) |
|
|
160
|
+
|
|
161
|
+
## テストの実行
|
|
162
|
+
|
|
163
|
+
テストにはすべて架空のチャンネル ID・架空の通知データを使用しており、外部通信を行わずに実行できます。
|
|
164
|
+
|
|
165
|
+
```powershell
|
|
166
|
+
$env:PYTHONPATH="src"
|
|
167
|
+
python -m unittest discover -s tests -v
|
|
168
|
+
```
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68.0"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "discord-message-cli"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Read-only Discord channel message aggregation CLI for humans and AI agents"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = {text = "MIT"}
|
|
12
|
+
dependencies = [
|
|
13
|
+
"tzdata; sys_platform == 'win32'",
|
|
14
|
+
]
|
|
15
|
+
|
|
16
|
+
[project.scripts]
|
|
17
|
+
discord-msg = "discord_msg.cli:main"
|
|
18
|
+
|
|
19
|
+
[tool.setuptools.packages.find]
|
|
20
|
+
where = ["src"]
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: discord-message-cli
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Read-only Discord channel message aggregation CLI for humans and AI agents
|
|
5
|
+
License: MIT
|
|
6
|
+
Requires-Python: >=3.10
|
|
7
|
+
Description-Content-Type: text/markdown
|
|
8
|
+
Requires-Dist: tzdata; sys_platform == "win32"
|
|
9
|
+
|
|
10
|
+
# Discord Message CLI (`discord-msg`)
|
|
11
|
+
|
|
12
|
+
権限を持つ Discord チャンネルのメッセージを Discord 公式 HTTP API (v10) で**読み取り専用**で取得し、期間別の集計を行う CLI ツールです。
|
|
13
|
+
人がターミナルで表を確認するほか、AI エージェントやスクリプトが JSON 形式で安全に集計情報だけを取得できるように設計されています。
|
|
14
|
+
|
|
15
|
+
## 特徴とセキュリティ方針
|
|
16
|
+
|
|
17
|
+
- **読み取り専用**: `GET /channels/{channel_id}/messages` のみを使用し、投稿・編集・削除・権限変更の機能は一切持ちません。
|
|
18
|
+
- **本文・添付の非出力**: 接続確認(`check`)および期間集計(`stats`)の出力(表・JSON ともに)には、メッセージ本文・添付ファイル・トークンを一切含めません。
|
|
19
|
+
- **安全なトークン入力**: Bot トークンは環境変数(`DISCORD_BOT_TOKEN`)、対話的な非表示入力(`--prompt-token`)、または標準入力(`--token-stdin`)からのみ受け付けます。コマンドライン引数や設定ファイルには保存・指定できません。
|
|
20
|
+
- **標準出力と標準エラーの分離**: 診断メッセージやエラーはすべて標準エラー(`stderr`)に出力され、標準出力(`stdout`)には完全な結果(表または JSON)のみが出力されます。取得途中で失敗した場合は、不完全な集計を標準出力に出さず非ゼロ終了コードで終了します。
|
|
21
|
+
|
|
22
|
+
## 導入方法
|
|
23
|
+
|
|
24
|
+
Python 3.10 以上が必要です。`pipx` または `pip` でワンコマンド導入できます。
|
|
25
|
+
|
|
26
|
+
```powershell
|
|
27
|
+
# PyPI から導入する場合(推奨)
|
|
28
|
+
pipx install discord-message-cli
|
|
29
|
+
# または
|
|
30
|
+
pip install discord-message-cli
|
|
31
|
+
|
|
32
|
+
# GitHub リポジトリから直接導入する場合
|
|
33
|
+
pipx install git+https://github.com/IT-Engineer-K/discord-message-cli.git
|
|
34
|
+
|
|
35
|
+
# ローカルのクローンから導入する場合
|
|
36
|
+
pipx install .
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## 認証設定
|
|
40
|
+
|
|
41
|
+
実行前に環境変数 `DISCORD_BOT_TOKEN` を設定するか、実行時に `--prompt-token` を指定してください。
|
|
42
|
+
|
|
43
|
+
```powershell
|
|
44
|
+
# PowerShell で一時的に環境変数へ設定する例
|
|
45
|
+
$env:DISCORD_BOT_TOKEN = (Read-Host -AsSecureString "Bot Token" | ConvertFrom-SecureString -AsPlainText)
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
> **必要な Discord Bot 権限**:
|
|
49
|
+
> 対象チャンネルに対する `View Channel`(チャンネルを見る)および `Read Message History`(メッセージ履歴を読む)。
|
|
50
|
+
> ※ 接頭辞(`--prefix`)やキーワード(`--keyword`)による本文絞り込みを行う場合は、Discord Developer Portal で Bot の **Message Content Intent** を有効にしてください。
|
|
51
|
+
|
|
52
|
+
## 使い方
|
|
53
|
+
|
|
54
|
+
### 1. 接続確認 (`check`)
|
|
55
|
+
|
|
56
|
+
対象チャンネルの履歴を読み取れるかを確認し、本文を表示せずに結果を返します。
|
|
57
|
+
|
|
58
|
+
```powershell
|
|
59
|
+
# 表形式(既定)
|
|
60
|
+
discord-msg check --channel 123456789012345678
|
|
61
|
+
|
|
62
|
+
# AI / スクリプト向け JSON 形式
|
|
63
|
+
discord-msg check --channel 123456789012345678 --format json
|
|
64
|
+
|
|
65
|
+
# トークンを対話的非表示入力で渡す場合
|
|
66
|
+
discord-msg check --channel 123456789012345678 --prompt-token
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
JSON 出力例:
|
|
70
|
+
|
|
71
|
+
```json
|
|
72
|
+
{
|
|
73
|
+
"ok": true,
|
|
74
|
+
"channel_id": "123456789012345678",
|
|
75
|
+
"reachable": true,
|
|
76
|
+
"history_readable": true,
|
|
77
|
+
"has_messages": true
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### 2. 期間別集計 (`stats`)
|
|
82
|
+
|
|
83
|
+
指定期間のメッセージ件数を集計します。
|
|
84
|
+
|
|
85
|
+
- **既定期間**: 直近 24 時間(`--since` / `--until` / `--hours` で変更可能。**開始時刻を含み、終了時刻は含まない** `[start, end)`)
|
|
86
|
+
- **既定タイムゾーン**: 日本時間 `Asia/Tokyo`(`--tz` で変更可能)
|
|
87
|
+
- **集計単位 (`--by`)**: `hour`(時間別・既定)、`day`(日別)、`total`(合計のみ)
|
|
88
|
+
- **絞り込み**: `--prefix`(本文の接頭辞)、`--keyword`(本文に含まれるキーワード)、`--ignore-case`(大文字・小文字を区別しない)
|
|
89
|
+
|
|
90
|
+
```powershell
|
|
91
|
+
# 直近24時間の時間別集計(日本時間・表形式)
|
|
92
|
+
discord-msg stats --channel 123456789012345678
|
|
93
|
+
|
|
94
|
+
# 期間と接頭辞・キーワードを指定して AI 向け JSON で取得
|
|
95
|
+
discord-msg stats `
|
|
96
|
+
--channel 123456789012345678 `
|
|
97
|
+
--since 2026-11-18T00:00:00+09:00 `
|
|
98
|
+
--until 2026-11-19T00:00:00+09:00 `
|
|
99
|
+
--by hour `
|
|
100
|
+
--prefix "[ALERT]" `
|
|
101
|
+
--keyword "DiskHigh" `
|
|
102
|
+
--format json
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
JSON 出力例:
|
|
106
|
+
|
|
107
|
+
```json
|
|
108
|
+
{
|
|
109
|
+
"channel_id": "123456789012345678",
|
|
110
|
+
"period": {
|
|
111
|
+
"start": "2026-11-18T09:00:00+09:00",
|
|
112
|
+
"end": "2026-11-18T12:00:00+09:00"
|
|
113
|
+
},
|
|
114
|
+
"timezone": "Asia/Tokyo",
|
|
115
|
+
"granularity": "hour",
|
|
116
|
+
"filter": {
|
|
117
|
+
"prefix": "[ALERT]",
|
|
118
|
+
"keyword": "DiskHigh",
|
|
119
|
+
"ignore_case": false
|
|
120
|
+
},
|
|
121
|
+
"buckets": [
|
|
122
|
+
{
|
|
123
|
+
"label": "2026-11-18 09:00",
|
|
124
|
+
"start": "2026-11-18T09:00:00+09:00",
|
|
125
|
+
"end": "2026-11-18T10:00:00+09:00",
|
|
126
|
+
"count": 2
|
|
127
|
+
},
|
|
128
|
+
{
|
|
129
|
+
"label": "2026-11-18 10:00",
|
|
130
|
+
"start": "2026-11-18T10:00:00+09:00",
|
|
131
|
+
"end": "2026-11-18T11:00:00+09:00",
|
|
132
|
+
"count": 0
|
|
133
|
+
},
|
|
134
|
+
{
|
|
135
|
+
"label": "2026-11-18 11:00",
|
|
136
|
+
"start": "2026-11-18T11:00:00+09:00",
|
|
137
|
+
"end": "2026-11-18T12:00:00+09:00",
|
|
138
|
+
"count": 3
|
|
139
|
+
}
|
|
140
|
+
],
|
|
141
|
+
"total": 5,
|
|
142
|
+
"scanned_in_period": 8
|
|
143
|
+
}
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
## ローカル設定ファイル(任意・非機密値のみ)
|
|
147
|
+
|
|
148
|
+
毎回 `--channel` を指定する代わりに、環境変数 `DISCORD_CHANNEL_ID` またはローカル設定ファイル(Windows の既定パス: `%APPDATA%\discord-msg\config.json`)に既定のチャンネル ID とタイムゾーンを記述できます。
|
|
149
|
+
※ セキュリティ保護のため、設定ファイルに `token` / `bot_token` キーが含まれている場合はエラーとして拒否します。
|
|
150
|
+
|
|
151
|
+
```json
|
|
152
|
+
{
|
|
153
|
+
"channel": "123456789012345678",
|
|
154
|
+
"tz": "Asia/Tokyo"
|
|
155
|
+
}
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
## 終了コード一覧
|
|
159
|
+
|
|
160
|
+
| 終了コード | エラーコード | 意味 |
|
|
161
|
+
| :--- | :--- | :--- |
|
|
162
|
+
| `0` | - | 正常終了(履歴が空の場合も含む) |
|
|
163
|
+
| `2` | `INVALID_ARGS` | 引数・期間指定・設定ファイルの形式エラー |
|
|
164
|
+
| `3` | `AUTH_FAILED` | トークン未指定または認証失敗 (`401 Unauthorized`) |
|
|
165
|
+
| `4` | `PERMISSION_DENIED` | チャンネル閲覧・履歴読み取り権限不足 (`403 Forbidden`) |
|
|
166
|
+
| `5` | `NOT_FOUND` | チャンネルが存在しないかアクセス不可 (`404 Not Found`) |
|
|
167
|
+
| `6` | `RATE_LIMITED` | レート制限の再試行上限超過 (`429 Too Many Requests`) |
|
|
168
|
+
| `7` | `FETCH_FAILED` | 通信エラーやページ送り途中の API エラー(不完全な集計は返さない) |
|
|
169
|
+
|
|
170
|
+
## テストの実行
|
|
171
|
+
|
|
172
|
+
テストにはすべて架空のチャンネル ID・架空の通知データを使用しており、外部通信を行わずに実行できます。
|
|
173
|
+
|
|
174
|
+
```powershell
|
|
175
|
+
$env:PYTHONPATH="src"
|
|
176
|
+
python -m unittest discover -s tests -v
|
|
177
|
+
```
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
README.md
|
|
2
|
+
pyproject.toml
|
|
3
|
+
src/discord_message_cli.egg-info/PKG-INFO
|
|
4
|
+
src/discord_message_cli.egg-info/SOURCES.txt
|
|
5
|
+
src/discord_message_cli.egg-info/dependency_links.txt
|
|
6
|
+
src/discord_message_cli.egg-info/entry_points.txt
|
|
7
|
+
src/discord_message_cli.egg-info/requires.txt
|
|
8
|
+
src/discord_message_cli.egg-info/top_level.txt
|
|
9
|
+
src/discord_msg/__init__.py
|
|
10
|
+
src/discord_msg/aggregator.py
|
|
11
|
+
src/discord_msg/auth.py
|
|
12
|
+
src/discord_msg/cli.py
|
|
13
|
+
src/discord_msg/client.py
|
|
14
|
+
src/discord_msg/config.py
|
|
15
|
+
src/discord_msg/errors.py
|
|
16
|
+
src/discord_msg/formatter.py
|
|
17
|
+
src/discord_msg/time_utils.py
|
|
18
|
+
tests/test_acceptance.py
|
|
19
|
+
tests/test_cli_and_auth.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
discord_msg
|