組員指南：加入別人分享的工作區

這份文件寫給組員：有同學用 smurg 把專案資料夾分享出來，傳了一個邀請連結給你。你不需要用過 smurg，也不需要用過 Claude Code。主人（分享資料夾的人）請看主人指南。這份指南的英文版：English。

先知道三件事：

• 所有檔案都在主人的電腦上。你在瀏覽器裡看到、改到的，就是主人電腦上的那份檔案；存檔是自動的。
• Claude Code 是在終端機裡工作的 AI 程式助手（以下叫 agent）：你用一般的句子告訴它要做什麼，它會讀檔案、改程式、執行指令。在 smurg 裡，每個 agent 都在主人的電腦上、以主人的身分執行，工作區裡的每個人都能即時看到它在做什麼。
• 你和主人電腦之間的連線是端對端加密的：中間轉送資料的伺服器（relay）看不到檔案內容、終端機畫面或指令（它知道你用哪個帳號登入、從哪個 IP 連線）。

目錄：1. 加入 · 2. 角色 · 3. 一起編輯 · 4. 檔案鎖的提示 · 5. 看 agent 與提建議 · 6. 開 agent session（可使用 agent） · 7. worktree 與合併請求 · 8. 主人已離線 · 9. 離開 · 10. 用終端機（CLI）

1. 用邀請連結加入

邀請連結長這樣：https://<網站>/join/<工作區代碼>#k=…&s=…。主人用 smurg 的公用 relay 時，<網站> 就是 app.smurg.ai（連結是 https://app.smurg.ai/join/…；https://smurg.ai 是 smurg 的介紹頁和使用說明，不能打開工作區）；主人用 --relay 指定了其他 relay（例如他自己架設的）時，是那個 relay 的網址。# 後面那一段是密鑰，有了它就能加入工作區：不要轉貼到群組或公開的地方，也不要只複製 # 前面的部分。

1. 用瀏覽器打開連結（電腦上的 Chrome 最穩；Safari、Firefox 還沒測試過）。
2. 登入：按「使用 Google 登入」，用你的 Google 帳號登入（其他 relay 可能也有「使用 GitHub 登入」，出現哪些按鈕由架設 relay 的人決定）。smurg 只用登入確認你是誰，不會取得你的程式碼；你不需要 Claude 帳號或 API key。 relay 知道你用哪個帳號、從哪個 IP 連線（主人指南 §2.1）。
3. 畫面會問「要加入這個工作區嗎？」，列出工作區代碼和你登入的身分。確定是主人給你的連結，就按「加入」。加入後，主人會看到你的名稱、帳號和裝置名稱。
4. 進入工作區：左邊是檔案，中間是編輯器，右邊是 agent 和建議，下方是「活動」「衝突」「傳輸」「合併請求」。最上面一排顯示主人是誰、連線狀態（「已連線」）和你的角色。

介面有英文和繁體中文：一開始依瀏覽器的語言，之後可以用畫面上的語言選單切換（登入頁和加入頁上也有）。每個人看到的是自己選的語言；這份指南引用的是繁體中文介面的文字。agent 的名稱（例如 Claude (Amy)）和別人輸入的文字不會翻譯。

之後直接打開工作區就好（首頁的「最近開啟的工作區」），不需要再用邀請連結：這個瀏覽器已經記住了主人電腦的金鑰。私密瀏覽視窗記不住，關掉之後要新的邀請連結才能再加入。

要不要核對「金鑰指紋」？ 主人分享時，在自己的電腦上執行 smurg status 可以看到一組 daemon 金鑰指紋。第一次加入時，你可以用其他管道（當面、電話）請主人唸給你聽。如果看到「安全警告：已拒絕連線」或「主人的電腦金鑰和之前不同」，先不要繼續：可能有人在冒充主人。也可能是主人換了工作區的金鑰（例如收回某位組員的「可使用 agent」之後重新分享，或重新安裝了 smurg）。請用其他管道（當面、電話）問主人：

• 主人說他沒有換過：不要繼續，按「取消」，告訴主人。
• 主人說他換過：請他給你新的邀請連結，並唸出他用 smurg status 看到的新 daemon 金鑰指紋。用新連結時會看到「主人的電腦金鑰和之前不同」：確認是主人剛給你的連結之後，按「我已向主人確認，使用新的連結」。用終端機加入的話，smurg attach 會印出「邀請連結的金鑰指紋」：和主人唸的一樣才輸入 y（見 §10）。

其他你可能看到的畫面：

2. 角色：可以做什麼

主人在邀請連結上決定你的角色，之後也可以在主人控制台改。

只有主人能做的事：邀請成員、改角色、踢人、看操作紀錄、強制釋放檔案鎖、合併 worktree。

「可使用 agent」是什麼意思：你開的 session 在主人的電腦上以主人的身分執行，沒有沙盒：agent 用的是主人的 Claude Code 登入（用量和費用算在主人身上），可以執行任何指令、讀得到主人電腦上的檔案。所以主人只會把這個角色給完全信任的人。你不需要、也不能用自己的 Claude 帳號或 API key。

有幾類檔案組員看不到：所有 .git 資料夾、.envrc、smurg 自己的 .smurg/，以及主人個人的 Claude Code 設定（.claude/settings.local.json、CLAUDE.local.md）。有幾類檔案組員看得到但不能改（檔案樹上會標示「只有主人可以修改這個檔案」）：.claude/ 和 .mcp.json（主人的 Claude Code 會讀它們）、.vscode/、.idea/。除此之外，資料夾裡的每個檔案，每個成員都看得到（包括 .env 之類的設定檔）。這些限制只適用於人在網頁和 CLI 裡的操作：以主人身分執行的 agent 和終端機不受它們限制。

3. 一起編輯檔案

• 在左邊的檔案樹點一下檔案就會在編輯器打開；在檔案或資料夾上按右鍵可以新增、重新命名、刪除、下載（資料夾會打包成 zip）。檔案樹上方的按鈕可以新增檔案、資料夾或上傳。
• 大家可以同時打字，每個人的游標會用不同顏色和名字顯示；agent 改檔案時會顯示成 Claude (開這個 agent 的人)，例如 Claude (Amy)。
• 不用按儲存：停下來一下就會自動存到主人的電腦（編輯器會顯示「已自動儲存」）。一直顯示「尚未儲存：正在等待主人電腦回應」的話，通常是連線有問題。
• 上傳：把檔案或整個資料夾拖到左邊的檔案樹。大檔案也可以，斷線後會從中斷的地方繼續；主人的磁碟空間不夠時，上傳在開始前就會被拒絕並說明原因。進度在下方的「傳輸」。
• 太大（超過 5 MB）、二進位或不是 UTF-8 的檔案不能在編輯器裡打開，可以下載後用自己的程式開啟。
• 在編輯器裡選取一段程式碼，按「送到 agent」，可以把它作為建議送給別人的 agent，或貼到你自己的 agent（見 §5）。
• 「活動」會即時列出誰（或哪個 agent）新增、修改、刪除、上傳了哪個檔案；點一下就能打開那個檔案。檔案樹上也會標示「最近由 … 修改」。顯示為「外部程式」的，是 smurg 無法確定是誰的修改（例如主人用別的程式改的）。

4. 檔案鎖的提示是什麼意思

smurg 用檔案鎖避免人和 agent 互相覆蓋。你會在編輯器上方或檔案樹上看到這些提示：

衝突：agent 也可能不經過檔案鎖、用終端機指令直接改檔案（例如 sed、格式化工具、git checkout）。如果它改到了有人正在編輯的地方，smurg 會保留人正在打的內容，把 agent 的版本放到下方的「衝突」面板，並通知雙方。在衝突面板可以左右對照兩邊的內容，選「保留編輯中的內容」，或「套用這個版本…」用另一方的完整版本取代整個檔案。

5. 看 agent 工作、提出建議

• 右邊的 agent 區有每個 session 的分頁（例如「Claude（Amy 開的）」是 Amy 開的 agent，「終端機（Ian 開的）」是主人 Ian 開的終端機）。點分頁就能即時看它的畫面，包括你打開之前的內容。
• 「旁觀」和「可編輯」的成員在 session 裡只能看、不能打字（會標示「只能觀看」）。想讓 agent 做什麼，要用建議：在 session 下方的「建議」輸入框寫下你的想法（例如「先幫這個函式補上測試」），按「送出建議」（或 Ctrl + Enter）。「可使用 agent」的成員可以直接在任何 session 裡輸入（§6）。
• 建議會先進入等待清單：主人和每個「可使用 agent」的成員會在 session 下方看到「等待你決定的建議」，可以「採用」、「修改後採用」或「拒絕」（可以附上原因）；只有按下採用之後，內容才會送進 session。smurg 沒有自動採用。
• 你會收到結果通知（「你的建議已被採用」「你的建議被拒絕了」等，有附原因時也會顯示）。在「我提出的建議」可以看到每一則的狀態；還沒處理的可以「編輯」或「撤回」。
• 在編輯器選取程式碼 →「送到 agent」→「作為建議送給 Amy 的『…』」：選取的程式碼會連同檔名和行號附在建議裡。
• 「旁觀」角色可以看，但不能提出建議。
• agent 也可以透過 smurg 通知你（例如「Claude (Amy) 通知你」），會出現在「活動」裡。

6. 開 agent session（可使用 agent）

只有「可使用 agent」的角色能在主人電腦上開 session，並在任何 session 裡直接輸入。你開的 session 以主人的身分在主人的電腦上執行：用主人的作業系統帳號和主人的 Claude Code 登入，沒有沙盒。所以你不需要登入 Claude，也不需要 API key。

開一個 session：agent 區右上角「新增 session」→ 選類型：

• 「agent（Claude Code）」：在終端機裡執行 Claude Code。
• 「一般終端機」：一個 shell，用來執行測試、建置等指令。

再選工作位置：「共享主工作區」（直接改大家看到的檔案，有檔案鎖保護）、「我的新 worktree」或「繼續我保留的 worktree」（見 §7），按「開啟」。對話框上方會提醒：「這個 session 會在主人的電腦上執行，agent 使用主人的 Claude 帳號。」主人的電腦上找不到 Claude Code 時，agent session 開不起來，畫面會說明原因：請轉告主人。

用 Claude Code：點一下終端機，用一般的句子輸入你要它做的事，按 Enter。它工作時畫面會一直更新；按 Esc 可以打斷它，輸入 /exit 結束。它可能會在改檔案或執行指令前問你是否允許：用方向鍵選擇後按 Enter。session 的畫面，工作區裡的每個人都看得到：不要在 session 裡貼上密碼或 API key。

在別人的 session 裡輸入：你也可以直接在主人或其他組員開的 session 裡打字，大家的輸入會進到同一個終端機。有人正在打字時請先等一下，或用建議。

請記得：你在 session 裡做的每件事，都是用主人的電腦和主人的帳號做的。agent 用掉的是主人的 Claude 額度，指令以主人的權限執行，讀得到主人電腦上的檔案。只做主人同意的事，不要去讀和專案無關的檔案。agent 顯示還沒登入 Claude（例如「Not logged in」）時，請告訴主人登入；不要在 session 裡用你自己的帳號 /login：那會把你的登入資料存到主人的電腦上，之後所有 agent 都會用它。畫面上看到「主人的 Claude Code 還沒有登入，這個 agent 暫時無法工作。」就是這種情況。

在自己的終端機接上：session 的「在自己的終端機接上」會列出 smurg attach 指令（§10）。

7. worktree 與合併請求

主人分享的資料夾是 git repository 時，開 session 可以選「我的新 worktree」：smurg 在主人電腦上為你建立一份獨立的工作副本（自己的分支），agent 在裡面改檔案，就不會弄亂大家的主工作區。worktree 只是工作的位置，不是限制：裡面的 agent 一樣以主人的身分執行。

• 檔案樹上方的「檢視的工作區」可以切換看主工作區或任何一個 worktree。大家也可以直接在 worktree 裡編輯（一樣有檔案鎖）。
• 主人指定的共享資料夾（例如不在 git 裡的 data/）會以連結的方式放進 worktree：在網頁裡它是唯讀的；agent 在 worktree 裡寫進這個資料夾的話，改的就是主工作區裡的那一份。
• 結束 session 時會問「要保留這個 session 的 worktree 嗎？」：「保留 worktree」之後可以用「繼續我保留的 worktree」再開 session；「刪除 worktree」會連同還沒合併的修改一起刪除，無法復原。
• 做完了，請主人合併：在檔案樹切到那個 worktree，按「請主人合併」（或在「合併請求」按「請求合併」），可以寫一段說明。「可使用 agent」的成員可以為任何一個 worktree 提出請求。smurg 會把 worktree 目前所有的修改建立成一個提交（commit）；之後再改的內容，需要重新提出請求。
• 主人會看到完整的差異（diff），然後「合併到主工作區」或「拒絕」（拒絕時 worktree 保持原狀，原因會告訴你）。和主工作區有衝突時，合併會中止、主工作區不變，主人會決定怎麼處理。結果會通知你，也會出現在大家的「活動」。
• 目前沒有辦法把主工作區之後的修改帶進你的 worktree。

8.「主人已離線」是什麼意思

主人的 smurg host 沒有在執行、主人的電腦進入睡眠（例如闔上筆電螢幕），或主人的網路斷了。主人一離線，所有人在 10 秒內就會看到「主人已離線」。

• 所有檔案和 session 都在主人的電腦上，所以在主人回來之前，檔案修改不會被儲存，也無法操作 agent。
• 主人回來後會自動重新連線，不用重新整理。離線期間你在編輯器打的字不會丟掉，會在重新連上後送出。只有一種情況要你決定：主人的電腦重新載入了這個檔案（例如主人的 smurg 重新啟動過），而且內容和你的版本不同，無法自動合併。這時畫面會顯示「你有修改還沒存到主人電腦」，讓你選「用我的版本取代」「複製我的版本」或「捨棄我的版本」。
• 主人的電腦沒有睡眠、只是你自己斷線時，session 會在主人電腦上繼續執行；重新連上後看得到完整的畫面。
• 「主人已停止分享這個工作區」表示主人執行了 smurg stop：所有 session 都已結束。主人重新開始分享後會自動重新連線。
• 「無法連上伺服器」是另一回事：那是你和 relay 之間的網路問題。

9. 離開工作區：會結束什麼

右上角的「離開」→ 確認「離開」。

會結束（幾秒內）：你開的所有 session（agent 和終端機）。

不會被刪除：

• 你的成員資格：主人的成員清單裡仍然有你，你之後可以用同一個瀏覽器重新打開工作區。要完全移除你，得由主人踢出。
• 你在分享資料夾裡改過、新增的檔案：它們是主人專案的一部分。
• 你的 worktree（包括還沒合併的修改）：主人可以移除它。
• 你提出的建議、活動動態和主人電腦上的操作紀錄。

只是關掉分頁或斷線不算離開：你開的 session 會繼續在主人的電腦上執行。主人把你移出工作區、或把你的角色改成「可編輯」或「旁觀」時，你開的 session 也會結束。

10. 用終端機（CLI）加入（選用）

不想用瀏覽器看 session，可以用 smurg 指令把 session 接到自己電腦的終端機（macOS 或 Linux）。先用一行指令安裝（和主人用的是同一個程式；詳見主人指南 §1）：

curl -fsSL https://smurg.ai/install.sh | sh

然後加入：

smurg attach --invite -       # 執行後貼上邀請連結，按 Enter（不會顯示在畫面上）

smurg 會連到邀請連結上的網站（relay），不需要 --relay。這台電腦還沒登入那個 relay 時，它會先請你登入：終端機印出一個網址（https://app.smurg.ai/device）和一組代碼。在任何裝置（電腦或手機）的瀏覽器打開網址、用 Google 帳號登入、輸入代碼，確認頁上的帳號是你的之後按「允許」。只有你自己剛在終端機執行 smurg 時才按「允許」；如果是別人給你的代碼，請按「拒絕」。

• 請用 --invite -（或環境變數 SMURG_INVITE）。直接寫 smurg attach --invite https://…#k=…&s=… 也可以，但連結裡的密鑰會留在 shell 的歷史紀錄，執行期間也會出現在其他使用者看得到的程序列表（ps）裡。
• 終端機是一個新的裝置，第一次需要邀請連結。瀏覽器用過的連結如果已經用完或過期，請主人給你一個和你目前角色相同的新連結（不同角色的連結不能用）。之後用 smurg attach --workspace <工作區代碼>（只加入過一個工作區時不用指定）。
• 少數環境的網頁和 relay 網址不同（例如開發環境）。如果 smurg 說你登入過另一個網址、還沒有登入邀請連結的網址，照它的提示加上 --relay <relay 網址>（主人會告訴你）。
• 需要登入時，有桌面的電腦上 smurg 也會自動打開那個網址；在 SSH、腳本或沒有終端機的情況下不會（也可以用 --no-browser），用你面前的電腦或手機打開就好，透過 SSH 也不需要其他設定。
• 主人換了工作區的金鑰之後（§1「要不要核對金鑰指紋」），smurg attach --workspace … 會停下來，說主人電腦的金鑰和上次記錄的不同。向主人確認過之後，用主人給的新連結執行 smurg attach --invite -：smurg 會印出「主人的電腦金鑰和之前不同」、上次記錄的和邀請連結的金鑰指紋，問你要不要繼續。邀請連結的指紋和主人用 smurg status 看到的一樣，才輸入 y；其他輸入會取消，什麼都不會送出。不在終端機裡執行（例如腳本）時不會問，確認過之後加上 --accept-new-key。

加入之後：

smurg attach                  # 列出工作區裡的 session（編號、類型、擁有者、狀態）
smurg attach 2                # 把 2 號 session 接到這個終端機；按 Ctrl-] 離開（session 繼續執行）

「可使用 agent」的成員可以在任何 session 裡輸入；其他角色只能看（會先顯示「唯讀模式」）。主人離線時，smurg attach 幾秒內就會告訴你。為了保護你的終端機，session 的輸出在顯示前會過濾：終端機查詢、剪貼簿存取（OSC 52）和其他不認得的控制序列都不會送到你的終端機（別人的 agent 可能被誘導輸出這些序列）。

CLI 不能開 session、不能提出建議，也沒有「離開」：這些請用網頁。