dadamsuk/slipdock

Slipdock CLI

slipdock 指令與使用者的 Slipdock 應用程式溝通，該應用程式託管於 app.slipdock.us，或是以使用者可存取的任何位址自架。每次寫入動作都會立即在網頁 UI 上顯示。執行 slipdock --help 可取得完整參考。

選擇伺服器。 使用 $SLIPDOCK_URL，否則使用 ~/.config/slipdock/url（由 slipdock url <address> 或伺服器自己的 /install.sh 寫入），否則使用此機器在 tailnet 上連接埠 4000 的位址。如果以上皆非使用者所指的看板，請向他們詢問位址——不要猜測。

如果您正要依據看板來工作——接手下一個任務、處理一個極大議題（epic）、在執行工作時保持卡片更新——請先執行 slipdock guide（伺服器給代理的說明：極大議題與子卡片、如何選擇下一張卡片、該寫回什麼）並遵循它。這個檔案是指令參考；指南是工作流程。

如果已連接 Slipdock 的 MCP 工具

當此工作階段已有 Slipdock 工具（list_boards、get_card、create_card、complete_card……，來自伺服器的 /mcp），它們是 CLI 執行相同工作的替代方案：使用兩者中已存在的那個。兩者的慣例相同——get_guide 回傳 slipdock guide 列印的指南簡短形式，結尾是其餘部分的名稱；section: "automations"（或任何這些名稱，或 "all"）則提供一個部分。archive_card 將卡片收起來，restore: true 則將其恢復；archive_board 對看板執行相同操作。偏好使用這些：delete_card（需要 confirm: true）、delete_list 和 delete_board（confirm 是看板的代碼）無法復原。create_list、create_tag 和 create_board 用於新增結構（標籤必須在 create_card/update_card 將其貼到卡片之前存在）。使用 full: true 的 list_cards 在一次呼叫中讀取每張卡片的完整內容（留言、核對清單、文件），而不是分別呼叫 get_card。update_card 也設定依賴關係並處理核對清單。list_pages 列出看板的 wiki（tree: true 將其嵌套顯示，如同 page tree），read_page 讀取一個頁面。page_info 回答 page links、page sections、page wanted 和 page resolve 的功能——在編輯 write_page 的部分前請先向它詢問 sections，而不是猜測標題路徑。page_history 是 page history，page diff（rev、rev + against 用於比較兩個版本，或 diff: true 用於最新儲存），而 revert_page 是 page revert：它需要頁面當前的 content_hash 作為 base_hash。update_page 是 page edit --title/--summary/--tag、page mv、page file、page rm/page restore（archived）和 page pin --card（pin_card/unpin_card）。upload_file 用於上傳最大 10 MB 檔案的 attach（content_base64 或 text）。模型寫出的 Base64 在大約 1 KB 以上會出錯（#1040），因此如果檔案在 shell 中，不要傳送它：使用 slipdock attach，或使用帶有 card/page 和 link: true 的 upload_file（#1147），它會回傳一個單次使用的 upload_url，有效時間 10 分鐘且不需要 token，用於 curl -F file=@FILE -F sha256=<hex> <upload_url>（還有 filename、replace、hide_on_card），如此可將位元組保留在模型之外。帶有 link: true 的 download_file 是反向的相同操作：curl -fsSo FILE <download_url>。已在使用者同步 wiki 中的檔案由伺服器使用 wiki_file（其在您 wiki 中的路徑或其 id；無內容）複製。content_base64 必須攜帶 sha256（base64 編碼前位元組的十六進位值），而 sha256_mismatch 拒絕表示需要重新編碼並重新傳送。回覆中的 sha256 是儲存後位元組的雜湊值，而 get_card/read_page 會為每個檔案列出它：與來源的雜湊值比較以驗證檔案，而不是下載它。任何超過數 KB 的內容會以約 4 KB 的區塊傳送（#1016），因為 base64 越長越容易損壞：第一個帶有 append: true、card/page、filename 和該區塊 sha256 的請求會回傳一個 upload_id；每個後續請求傳送 upload_id、append: true、offset（上次回覆的 received）和自己的 sha256，被拒絕的區塊會單獨重新傳送；然後使用 upload_id、finish: true 和整個檔案的 sha256 來完成附件。在此之前，卡片上不會顯示任何內容。重新建立已存在於卡片上的檔案時，傳送 replace: true（在單次呼叫、第一個區塊或 finish 上）：舊的該檔名檔案會在新檔案儲存後被移除，因此只會留下一個當前副本。delete_attachment（detach；attachment id 和 confirm: true）直接移除一個附件，例如您上傳錯誤的檔案。而 download_file 透過其 id 讀取一個已附加的檔案（get_card 和 read_page 會列出它們）。 list_automations 是 automations/automation（vocabulary: true 會加入 automation-help 和 automation-presets 提供的內容），而 manage_automation 是 new-automation（action: create）、set-automation（update）和 delete-automation（delete，帶有 confirm: true）。 list_tools 是 tools/tools show（每個工具的種類及其 installed.board，您的安裝所建立的看板；使用 file 是 tools file；skill 讀取其 SKILL.md；link: true 提供一個單次使用的 download_url 用於檔案、技能的 zip 或技能 tarball（#1158）；package: true 是 tools download），而 install_tool 是 tools install-board。工具未涵蓋的任何內容（立即執行規則、回呼與警報、衝刺、超過 10 MB 的檔案、欄位）仍使用 CLI 或 API。

如果此處未安裝 CLI

以下所有內容都是對 JSON API 的包裝，而 API 是備用方案：它只需要 curl。不要告訴使用者安裝 CLI（它是一個 escript，需要 Erlang）——使用 API，並且僅在使用者要求更方便輸入的內容或 wiki 同步（只有 CLI 能做到）時才提及 CLI。在 Windows 上，這是在 PowerShell 中的一行指令，來自他們自己的伺服器：irm "$B/cli/install.ps1" | iex，然後執行 slipdock auth。在其他地方，它是從儲存庫的 cli/ 建立的。

B="${SLIPDOCK_URL:-$(cat ~/.config/slipdock/url 2>/dev/null)}"
T="$(cat ~/.config/slipdock/token 2>/dev/null)"
H="Authorization: Bearer ${SLIPDOCK_TOKEN:-$T}"

curl -s "$B/api/guide"                 # 不需要 token；整個 API，包含每個呼叫的 curl 指令
curl -s -H "$H" "$B/api/me"            # 此 token 的身份

GET /api/guide 是完整的參考——每個端點，附帶一個 curl 指令，以及當傳遞 token 時的使用者自己的看板和列表。請閱讀它，而不是從這個檔案推測路徑。

登入也不需要 CLI；它是相同的裝置授權流程，兩個呼叫（指南中已詳細說明）。請求一個代碼，向使用者顯示 URL 和代碼，輪詢直到他們批准，然後將 token 以權限 600 寫入 ~/.config/slipdock/token，以便下一個工作階段使用：

curl -s -X POST "$B/api/auth/device" -H 'content-type: application/json' \
     -d '{"label":"claude on this machine","scope":"write"}'
# → user_code, verification_uri, device_code, interval
curl -s -X POST "$B/api/auth/device/token" -H 'content-type: application/json' \
     -d '{"device_code":"…"}'
# → 400 authorization_pending 直到批准，然後 {"token":"…"}

要在沒有這些技能的機器上安裝它們： curl -fsSL "$B/install.sh" | sh（只需要 curl 和 tar）；在 Windows 上，在 PowerShell 中執行 irm "$B/install.ps1" | iex（放入 %USERPROFILE%\.claude\skills，而不是 WSL 的家目錄）。 對於無法執行此 CLI 的 ChatGPT，slipdock skills chatgpt 會將它們儲存為 ZIP 檔案以供上傳，每個 ZIP 將指令對應到 MCP 連接器的工具（$B/api/skills/<name>/chatgpt.zip）。

登入

API 需要一個 token。如果命令失敗並顯示 not signed in，執行 slipdock auth——它會列印一個簡短代碼和一個 URL，使用者在他們已登入的瀏覽器中批准它，幾秒鐘後您就會得到一個 token。告訴他們代碼和 URL；不要要求他們手動建立 token，除非他們願意（slipdock auth <token> 仍然接受一個 token，而 SLIPDOCK_TOKEN 仍然有效）。

slipdock whoami 顯示當前使用者。使用者無法存取的看板根本不會列出；forbidden 錯誤表示他們可以看到某些東西但無法更改。兩次拒絕會提及 token 而不是使用者，表示您持有的 token 被刻意限制，而不是任何東西出了問題——請這樣說，而不是重試：

• this API token is read-only——它僅被授予讀取權限。要求一個讀寫 token。
• this API token's scope doesn't allow it——它被限制在特定看板，或者它不是管理員 token 而您嘗試管理伺服器。

還有兩個拒絕也是最終的。回報它們並說明使用者可以怎麼做：

• card_limit_reached（HTTP 402）——看板擁有者的帳戶已用盡其允許的所有項目。一個項目是一張卡片、一個 wiki 頁面或一個上傳的檔案：三者都計入同一個數字，因此將其寫成頁面並不會解決問題。不同的標題也沒有幫助；它會永久失敗，情況相同。建議封存一些已完成的東西。 slipdock whoami --json 和 slipdock guide 都會顯示剩餘配額，因此您可以在開始批次處理前檢查，而不是中途才發現限制。
• board_limit_reached（HTTP 402）——他們擁有的看板數量已達到此伺服器允許一個人的上限。子看板（子卡片）不計入此限制。建議封存一個看板，或詢問管理員。
• storage_limit_reached（HTTP 402）——他們上傳的檔案已用盡允許的空間。只有刪除附件才能釋放空間；封存檔案所在的卡片並不會。
• trial_expired（HTTP 402）——免費試用已到期。他們的看板上任何地方都不能新增任何東西，無論多麼小。所有已存在的內容仍然可讀取和編輯。您對此無能為力：告訴使用者他們需要訂閱，然後停止。 這四個回覆不僅限於建立操作：從封存中恢復、move --board 移動到他人的看板（卡片及其下的所有東西都計入他們的配額）、匯入以及 welcome。
• No account here uses that address… 在分享時出現——此伺服器不為您分享對象建立帳戶。管理員必須邀請他們。

在一個只有被分享者才能看到彼此的伺服器上，您預期找到但找不到的人很可能從未被分享過任何東西。他們沒有被刪除，並且在分享某些東西之前，無法將卡片指派給他們。

卡片只能指派給可以開啟它的人。指派對象上的 user … not found 正是此意，無論他們是否有帳戶——先在瀏覽器中與他們分享看板（看板的分享設定），或要求使用者這樣做。

工作流程

1. 首先找到看板及其結構：slipdock boards，然後是 slipdock board <board> 或 slipdock columns <board> 和 slipdock tags <board>。看板和欄位接受 id 或大小寫不敏感的名稱，因此 slipdock board "product launch" 有效。 每個看板也有一個代碼——其短名稱：唯一、URL 安全、最多 10 個字元，取自看板名稱且可編輯（"QVM V1 Remediation" 是 qvm-v1-rem）。它位於 slipdock boards 的 CODE 欄位和 --json 的 code 欄位中，而 <board> 在任何位置都接受它：slipdock board qvm-v1-rem，slipdock add qvm-v1-rem "..."。偏好使用它而不是名稱——它無歧義且能承受重新命名——並在向使用者回報看板名稱時使用它。slipdock new-board <name> [--code C] 明確設定一個；省略時，會從名稱產生一個。 一個看板也有一個快捷鍵——在網頁應用程式中跳到它的單一或兩個字元（按下 b，然後按該鍵）。它是 slipdock boards 的 KEY 欄位和 --json 的 shortcut 欄位，並透過 new-board 或 set-board 的 --shortcut K 設定。它不是命令列上定位看板的方式；代碼才是。
2. 先讀取再寫入。 slipdock card <id> 顯示所有內容：描述、旗標、標籤、核對清單項目 id、留言。
3. 當您需要解析輸出時使用 --json（id、過濾、計數）。純文字輸出用於向使用者顯示。
4. 偏好使用 archive 而非 delete。 刪除是永久性的。在使用者未明確要求刪除之前，請先詢問。 整個看板也可以封存（slipdock archive-board <board>），這與封存卡片不同，且與您更不相干：它從使用者的索引、看板切換器和快速新增中移除該看板。除非使用者按名稱要求該看板，否則切勿封存或重新排序看板。
5. 在發生時說明正在發生的事情。 執行時間超過短暫坐著的任務，會在每個里程碑使用 slipdock comment <id> ... 進行——並使用 slipdock edit <id> --percent N 來配合——而不是在最後一次性寫入。一張進行中的卡片，如果沒有比移動更新的留言，對觀看者來說會視為已放棄。
6. 向使用者回報 id（#42），以便他們可以在 UI 中找到卡片。 留言或描述中的 @handle（某人的電子郵件 '@' 之前的部分）會發送電子郵件給該人

…

[為翻譯而截斷]