需要從終端機檢查或操作 Oysterun 時，請使用本指南。你會找到受支援的產品模組、確認預定的 Host、分辨唯讀命令與會改變狀態的命令，並對受保護變更使用正確的 dry-run 與確認界線。
開始前
- 你要執行命令的機器已安裝 Oysterun。
- 你知道該命令預定連到哪一個 Oysterun Host。
- 你已取得該 Host 核准的存取權，來源是已驗證的操作者終端機或目前的即時 Session 環境。
- 你擁有操作所需的確切 Session、schedule、Loop、Mail、Website 或 Agent 識別碼。
起始畫面：在擁有或能連到預定 Host 的機器上開啟終端機。請勿從猜測 action 名稱開始。
1. 找出受支援的產品模組
oysterun --help 在乾淨終端機中顯示命令格式與目前受支援的模組。檢視完整尺寸截圖
執行最上層說明命令：
oysterun --help目前 CLI 會在 Product modules 下列出：
auth, sessions, chat, scheduler, mail, notifications, website, telegram2. 在進行任何操作前先確認目標
ok、sessions status，並在 result envelope 中顯示預定的確切 Session。檢視完整尺寸截圖
有多個 Host 可用時，請提供明確的 --host。先從唯讀操作開始：
oysterun sessions list --host <HOST_ORIGIN> --json如果你使用先前已核准的 dashboard CLI 存取權，可以在不變更 Session 的情況下檢查：
oysterun auth status --host <HOST_ORIGIN> --json- 閱讀目標與回傳狀態。
- 確認列出的 Sessions 屬於預定 Host。
- 只從這次可信任的唯讀結果複製確切識別碼；不要從顯示名稱猜測。
3. 辨認唯讀操作
下列受支援的 action 會檢查目前狀態，不會要求產品變更：
| 模組 | 唯讀 action | 一般結果 |
|---|---|---|
| auth | status | 目前的 dashboard CLI 登入狀態 |
| sessions | list、status、url、profile get | Session 身分、狀態、URL 或 profile |
| chat | recent、messages、messages-around、search、loop list | 有界訊息、前後文、搜尋結果或 Loop 定義 |
| scheduler | list、get、runs、run-log | Schedules 及其已記錄的執行資訊 |
unread-count、list、get | Mail 計數、清單或單一項目 | |
| notifications | status | 目前的通知可用狀態 |
| website | status、url、validate、access get | Website 狀態、URL、驗證結果或存取模式 |
| telegram | status；sessions telegram get | Telegram 或每個 Session 的 Telegram 狀態 |
需要結構化 envelope 時加入 --json。其中包含 ok、command、contract、result 與 error。
4. 辨認不等待確認的一般變更
下列 action 類別會在必要輸入與授權通過後改變產品狀態。沒有出現確認提示，並不會讓它們變安全：
| 模組 | 立即改變狀態的 action | 可能改變的內容 |
|---|---|---|
| auth | login、logout | CLI 登入狀態 |
| sessions | start、profile update、rename、resume、branch-resume、Telegram enable/disable/update | Sessions 或 Session profile 設定 |
| chat | send；Loop create、update、enable、disable | 訊息或 Loop 定義與狀態 |
| scheduler | create、update、enable、test-run | Schedules 或一次真正的測試執行 |
send、read、unread、archive、unarchive、update | Mail 傳送或項目狀態 | |
| notifications | send | 除非使用該 action 已記載的 dry run，否則會傳送通知 |
| website | init、enable | 除非使用該 action 已記載的 dry run，否則會改變 Website 檔案或啟用狀態 |
5. 預覽並確認受保護變更
dry_run: true 和 POST /session/restart 預覽；受保護變更並未執行。檢視完整尺寸截圖
下列目前操作具有強制確認界線：
| 範圍 | 受保護操作 | 界線 |
|---|---|---|
| Sessions | sessions stop、sessions interrupt、sessions restart | 單獨的 --confirm 或 --dry-run |
| Chat | chat loop delete | 單獨的 --confirm 或 --dry-run |
| Scheduler | scheduler disable、scheduler delete | 單獨的 --confirm 或 --dry-run |
mail delete | 單獨的 --confirm 或 --dry-run | |
| Website | website access set、website disable、website password set | 單獨的 --confirm 或 --dry-run |
先預覽確切操作。使用 --json，讓預定請求可見，而不是只看到簡短的人類可讀狀態：
oysterun sessions restart \
--host <HOST_ORIGIN> \
--session-id <SESSION_ID> \
--dry-run \
--json- 確認結果包含
dry_run: true。 - 重新確認你輸入的命令中所指定的 Host；在已遮蔽敏感資訊的計畫裡，檢查 request method、path 與確切目標識別碼。
- 任何內容錯誤或不清楚時，請停止。dry run 並未進行變更。
- 只有在變更已獲明確授權時，才以單獨的 --confirm 取代 --dry-run，重新執行同一條已檢查的命令。第二條命令會真正進行變更。
6. 閱讀輸出但不暴露私人資料
- 預設為人類可讀輸出。需要確認確切 command/result envelope 或 dry-run 計畫時，請使用 --json。
- 一般輸出會遮蔽類似秘密的欄位，但 Host origin、Session 識別碼、訊息內容與檔名仍可能是私人資訊。
- 成功時確認
ok、command與預期 result。失敗時，在修改命令前先閱讀error。 - 只分享支援工作所需的最小遮蔽片段。絕對不要分享 auth option 或完整環境。
7. 復原時不要把唯讀變成變更
- Unknown command 或 action：停止並回到
oysterun --help。不要嘗試相近的 action 名稱。 - Host origin is required 或錯誤的 Host 回應：停止、取得已核准的 Host origin，再使用明確的 --host 重跑唯讀操作。
- 需要授權：使用該 Host 核准的登入途徑或目前的即時 Session 授權。不要把廣泛 token 當成捷徑貼入。
- CLI 要求 --confirm：不要立即加上它。對同一個受保護操作使用 --dry-run --json、檢查計畫；若尚未有明確授權，再提出授權要求。
- 目標名稱不明確：使用唯讀命令取得確切識別碼，再只重試預定操作。
- dry-run 計畫沒有
dry_run: true：不要進入確認步驟。保留已遮蔽輸出並檢查目前的命令指南；切勿把未記載的 dry-run 當成安全測試。
8. 以安全檢查完成
檢視完整尺寸截圖
active、alive 與 ready 是 lifecycle 與 readiness 欄位。這些欄位本身不能證明 provider 正在回應、輸入、被占用或產生有用進度。
- 最後再確認一次 Host 與確切目標。
- 將命令分類為唯讀、一般變更或受保護變更。
- 受保護變更需保留 dry-run 結果與已確認操作的授權。
- 每次一般變更或已確認的受保護變更之後，都要對同一個 Host 與確切目標執行相關唯讀命令。dry run 之後，請以事後唯讀確認預定變更並未發生。