AGENTS.md

1# Codex 審查指南
2 
3這個 repository 是 Python Twitch 聊天室機器人，會監聽 Twitch EventSub 聊天訊息，並使用 OpenAI Responses API 產生簡短的公開回覆。
4 
5審查這個 repo 的變更時，請使用這份指南。
6 
7## 審查語言
8 
9- 請使用繁體中文撰寫 review comment。
10- 優先指出具體風險、bug、行為退化、缺少測試或安全性問題。
11- 除非會影響正確性、可維護性或使用者安全，否則避免只針對風格提出建議。
12 
13## 高風險區域
14 
15- Secret 絕不能被提交、記錄到 log、印出，或寫進範例：
16  - `OPENAI_API_KEY`
17  - `TWITCH_TOKEN`
18  - `TWITCH_CLIENT_SECRET`
19  - `.env`
20  - `prompt/system_prompt.txt`
21  - 本機 token/cache 檔案
22- Twitch 驗證相關變更必須保留以下項目的關係：
23  - `TWITCH_TOKEN`
24  - `TWITCH_BOT_ID`
25  - `TWITCH_OWNER_ID`
26  - 必要 scopes：`user:read:chat` 和 `user:write:chat`
27- 公開聊天室回覆必須避免洗版：
28  - 保持全域冷卻與單一使用者冷卻行為正確
29  - 保留指令、網址、過長訊息與黑名單使用者的忽略規則
30  - 讓回覆機率與強制觸發行為保持容易理解
31- LLM 輸出必須受到限制：
32  - 保留 `MAX_INPUT_LENGTH` 和 `MAX_REPLY_LENGTH`
33  - 避免讓 prompt injection 更容易成功的變更
34  - 避免在回覆中暴露私有 prompt 或環境資料
35 
36## Python 審查清單
37 
38- 確認新的環境變數同時記錄在 `.env.example` 和 `README.md`。
39- 檢查數值型環境變數是否有清楚的失敗訊息或安全預設值。
40- 檢查網路呼叫是否設定 timeout，且錯誤訊息是否有助於排查。
41- 檢查 Twitch EventSub handler 是否沒有不必要地阻塞。
42- 檢查使用者可見的回覆行為是否足夠可預測，方便除錯。
43- 優先提出小範圍、局部修正，避免大規模重寫。
44 
45## GitHub Actions 審查清單
46 
47- 確認 workflow 權限沒有超過實際需要。
48- 可行時，優先使用固定 action 版本或穩定 tag，避免使用會移動的分支。
49- 不要透過 log、PR comment、命令輸出或 debug flag 暴露 secrets。
50- 確認 PR 自動化不會建立重複 pull request，也不會造成 workflow 遞迴觸發。
51 
52## 文件期望
53 
54- 如果行為有變更，請更新 `README.md`。
55- 如果設定有變更，請更新 `.env.example`。
56- 如果 prompt 設定方式有變更，請更新 `prompt/system_prompt.txt.example`。
57- 不要記錄真實 secrets 或只存在本機的值。
58 
59## 本機驗證
60 
61可行時，執行範圍最小且相關的檢查：
62 
63```bash
64python -m py_compile main.py
65```
66 
67如果已安裝 dependencies，且變更會影響執行期行為，請優先做聚焦的手動檢查，避免提出範圍過大的推測性變更。
68