# 如何安全使用 Oysterun CLI

從 CLI 說明找到受支援的操作，分辨唯讀查詢、一般變更與受保護變更，並正確使用 dry-run 與確認界線。

需要從終端機檢查或操作 Oysterun 時，請使用本指南。你會找到受支援的產品模組、確認預定的 Host、分辨唯讀命令與會改變狀態的命令，並對受保護變更使用正確的 dry-run 與確認界線。

簡短原則：

命令沒有

--confirm

，不代表它是安全的。唯讀命令只檢查狀態；一般變更在必要輸入通過後立即執行；受保護變更若沒有單獨的

--confirm

就會拒絕。使用

--dry-run

預覽受保護變更，並加入

--json

以檢查預定請求。

## 開始前

- 你要執行命令的機器已安裝 Oysterun。
- 你知道該命令預定連到哪一個 Oysterun Host。
- 你已取得該 Host 核准的存取權，來源是已驗證的操作者終端機或目前的即時 Session 環境。
- 你擁有操作所需的確切 Session、schedule、Loop、Mail、Website 或 Agent 識別碼。

**起始畫面：**在擁有或能連到預定 Host 的機器上開啟終端機。請勿從猜測 action 名稱開始。

不要讓秘密進入命令列與證據。

請勿把密碼、token、cookie 或私人 Host URL 貼入截圖、共用 shell 歷史或支援訊息。

## 1. 找出受支援的產品模組

![乾淨的 Host Terminal 顯示 oysterun 說明、命令格式與目前產品模組清單。](../assets/publication/cli-supported-modules.jpg)

畫面 checkpoint：

oysterun --help

在乾淨終端機中顯示命令格式與目前受支援的模組。

執行最上層說明命令：

```
oysterun --help
```

目前 CLI 會在 **Product modules** 下列出：

```
auth, sessions, chat, scheduler, mail, notifications, website, telegram
```

檢查點：

說明輸出顯示命令格式

oysterun <module> <action> [options]

，以及上方的產品模組清單。

只用最上層說明探索。

不要為了測試而執行不熟悉的 action；有效的 action 可能會立即執行。說明也會列出 setup 與 service 維護命令；它們不在本產品操作指南的範圍內，只能依照相關 Host 維護指南使用。

## 2. 在進行任何操作前先確認目標

![乾淨的 Host Terminal 顯示明確遮蔽的 Host 唯讀命令，以及確切任務目標的成功狀態 envelope。](../assets/publication/cli-target-read.jpg)

畫面 checkpoint：已遮蔽 Host 的唯讀命令回傳

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
```

1. 閱讀目標與回傳狀態。
1. 確認列出的 Sessions 屬於預定 Host。
1. 只從這次可信任的唯讀結果複製確切識別碼；不要從顯示名稱猜測。

檢查點：

成功的唯讀操作回傳預定 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 及其已記錄的執行資訊

mail

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 或一次真正的測試執行

mail

send

、

read

、

unread

、

archive

、

unarchive

、

update

Mail 傳送或項目狀態

notifications

send

除非使用該 action 已記載的 dry run，否則會傳送通知

website

init

、

enable

除非使用該 action 已記載的 dry run，否則會改變 Website 檔案或啟用狀態

--dry-run 不是通用開關。

不要把它加入任意變更後，就假設命令不會產生影響。只有已記載支援的 action 才能使用。例如，

chat send

、

sessions start

與

scheduler test-run

都是真正的操作，不是 dry-run 測試。

## 5. 預覽並確認受保護變更

![乾淨的 Host Terminal 顯示確切 Session restart dry run 與預定的受保護請求。](../assets/publication/cli-protected-dry-run.jpg)

畫面 checkpoint：確切目標以

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

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
```

1. 確認結果包含 `dry_run: true`。
1. 重新確認你輸入的命令中所指定的 Host；在已遮蔽敏感資訊的計畫裡，檢查 request method、path 與確切目標識別碼。
1. 任何內容錯誤或不清楚時，請停止。dry run 並未進行變更。
1. 只有在變更已獲明確授權時，才以單獨的 **--confirm** 取代 **--dry-run**，重新執行同一條已檢查的命令。第二條命令會真正進行變更。

檢查點：

如果兩種界線都沒有，CLI 會拒絕並顯示類似

sessions restart requires --confirm. Use --dry-run to preview without mutation.

的訊息。dry run 會回傳

dry_run: true

；已確認的執行則是真正的狀態變更。

## 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 當成安全測試。

安全停止點：

未知目標、缺少授權、不明確識別碼、缺少 dry-run 證明或非預期輸出，都仍是未解決狀態。請保留已遮蔽證據，並在變更前停止。

## 8. 以安全檢查完成

![乾淨的 Host Terminal 顯示同一個確切 Session 目標的唯讀事後狀態。](../assets/publication/cli-post-status.jpg)

畫面 checkpoint：最後一次唯讀 status 確認同一個確切 Session 在 dry run 後仍為 active、alive 且 ready。

`active`、`alive` 與 `ready` 是 lifecycle 與 readiness 欄位。這些欄位本身不能證明 provider 正在回應、輸入、被占用或產生有用進度。

1. 最後再確認一次 Host 與確切目標。
1. 將命令分類為唯讀、一般變更或受保護變更。
1. 受保護變更需保留 dry-run 結果與已確認操作的授權。
1. 每次一般變更或已確認的受保護變更之後，都要對同一個 Host 與確切目標執行相關唯讀命令。dry run 之後，請以事後唯讀確認預定變更並未發生。

完成：

你已找到受支援的操作、確認目標、沒有跨越未記載的界線、完成必要的事後唯讀，並能說明 CLI 是只讀取狀態、立即改變狀態，或需要明確確認。