前言¶
在 DeepSeek Harness（DSH）裏做智能體開發，常見瓶頸是模型只能「說」不能「做」：跑測試、改文件、查日誌、操作 Git，往往還要在對話外手動切終端。部分 MCP 方案只提供零散的文件讀寫或簡化的 Git 封裝，和真實開發環境仍有距離。
fwerkor/local-shell-mcp（以下簡稱 LSM）把受控的執行環境通過 MCP 暴露給客戶端。倉庫自帶 DSH 橋接包，可將完整 LSM 工具面接入 DSH Web，並把每個 DSH Session 綁定到獨立的邏輯會話與 Live Workspace。下面介紹它是什麼、能做什麼，以及如何在 DSH 裏安裝啓用。
這是什麼¶
LSM 由 fwerkor 維護，在 GitHub 上約 54 stars、13 forks，SkillHub 分類爲客戶端。項目定位是：面向 ChatGPT Developer Mode 及其他 MCP 客戶端的 Shell、文件、瀏覽器自動化與遠程機器控制平面。
作爲 DSH 插件時，bundle 名稱爲 local-shell-mcp-dsh（當前版本 4.2.1，MIT 許可證）。它不替代 LSM 服務端，而是讓 DSH 通過 HTTP 連接已運行的 LSM 控制器，把 mcp__lsm__* 工具註冊進對話，並在 DSH Web 中嵌入 Live Workspace 視圖。
安全邊界在容器或 VM 內的工作區，而非宿主機全盤開放。同機部署時，LSM 默認監聽 0.0.0.0:8765，DSH 橋接默認經 loopback 訪問 http://127.0.0.1:8765/mcp。
核心功能¶
以下能力均來自項目 README 與 DSH 集成文檔，按模塊歸納。
終端與文件¶
- Shell 執行：單次命令與持久化 Shell 會話，適合跑測試、構建、查日誌。
- 工作區文件工具：在受控根目錄下讀取、寫入、補丁、搜索文件。
- Git：通過普通 Shell 調用標準 Git CLI，而非單獨的 Git 抽象層。
會話與計劃¶
- 邏輯 Session：
session_manage提供跨輪次、跨對話可恢復的任務上下文；session_id是持久任務標識。 - Goal / Plan：可選的計劃與進度報告，與 Activity、審計數據一併留在 LSM 控制器。
瀏覽器與遠程¶
- Playwright：頁面文本提取、PNG/PDF 截圖、完整瀏覽器腳本。
- Remote Workers：經出站 HTTP(S) 連接 NAT、防火牆後的機器；DSH 側同樣可用
mcp__lsm__remote_manage、mcp__lsm__remote_transfer及帶machine參數的常規工具。
DSH 專屬集成¶
- 完整工具面：模型可見工具包括
mcp__lsm__run_shell、mcp__lsm__file_read、mcp__lsm__browser_session、mcp__lsm__session_manage、mcp__lsm__plan_manage等，命名空間爲mcp__lsm__*。 - Session 綁定：每個 DSH Session 對應穩定的 LSM 邏輯會話與獨立 Live Workspace 時間線，不同對話的活動不會合並。
- Live Workspace：在 DSH 對話視圖中展示終端、文件、diff、作業、遠程機與審計；憑證由 DSH Host 經 MCP 連接在服務端獲取，不寫入模型可見的工具結果。
運維與人機界面¶
LSM 自帶 Web UI（http://127.0.0.1:8765/ui）與 OpenTUI 終端界面，用於健康檢查、機器列表、最近 MCP 活動與告警。工作區範圍限制、Shell 超時、輸出上限、環境變量過濾、審計日誌與密鑰掃描等機制在 README 中有說明。
推薦拓撲¶
同機部署是文檔推薦方式：
DSH Web
|
| 每個 DSH Session 一條 LSM MCP 連接
| 127.0.0.1:8765/mcp
v
local-shell-mcp :8765
|-- 本地執行 = 本 LSM 主機
|-- /mcp、/remote/*、/ui
|-- Live Workspace / audit / browser / jobs
|
+--> Remote Workers
集成選用 HTTP 而非 stdio，是因爲 Remote Workers 除 MCP 工具外還依賴控制器的 /remote/* 路由；單一 stdio 子進程無法保留該服務平面。
安裝與啓用¶
1. 準備 LSM 運行時¶
可先安裝官方啓動器或 Python 包（Python 3.11+）：
npx local-shell-mcp --help
pipx install local-shell-mcp
lsm --help
從源碼部署時，複製環境配置並按文檔設置 LOCAL_SHELL_MCP_PUBLIC_BASE_URL 等變量後，可用 Docker Compose 啓動：
git clone https://github.com/fwerkor/local-shell-mcp.git
cd local-shell-mcp
cp .env.example .env
mkdir -p workspaces/default
docker compose up -d
curl -i http://127.0.0.1:8765/healthz
2. 啓動 MCP 服務¶
DSH 集成前，先讓 LSM 以 MCP 模式運行：
local-shell-mcp --mode mcp
bundle 不會再拉起第二個 LSM 進程；LSM 未就緒時橋接會退避重連，待服務上線後同步工具目錄。
3. 安裝 DSH 插件¶
在 DSH Web profile 中安裝本倉庫：
dsh plugin --profile web add 'github:fwerkor/local-shell-mcp#main'
生產環境建議將 Git 引用固定到已審查的 release tag 或 commit。本地開發可從檢出目錄安裝：
dsh plugin --profile web add .
4. 驗證¶
查看組合後的 DSH 配置：
dsh --profile web --dump-config
輸出中應出現類似條目：
id: local-shell-mcp
name: local-shell-mcp-dsh
url: http://127.0.0.1:8765/mcp
LSM 在線後，對話中應可見 mcp__lsm__run_shell、mcp__lsm__remote_manage、mcp__lsm__session_manage 等工具；DSH Web 非空對話還應出現 Live Workspace 視圖入口。
5. 可選環境變量¶
| 變量 | 默認值 | 用途 |
|---|---|---|
DSH_LSM_MCP_URL |
http://127.0.0.1:8765/mcp |
DSH 使用的 LSM MCP 端點 |
DSH_LSM_AUTHORIZATION |
未設置 | 可選完整 Authorization 頭，如 Bearer ... |
DSH_LSM_TOOL_CALL_TIMEOUT_MS |
120000 |
單次工具調用超時（毫秒） |
DSH_LSM_KEEPALIVE_INTERVAL_MS |
30000 |
保活 ping 間隔（最小 5000 ms） |
DSH_LSM_BROWSER_URL |
未設置 | 瀏覽器訪問 LSM 的源地址（遠程 DSH 部署時若 MCP 用 loopback 而 UI 需公網可達） |
同機部署通常無需 Authorization；勿將未認證的 LSM 暴露到公網。遠程受保護控制器示例：
export DSH_LSM_MCP_URL='https://lsm.example.com/mcp'
export DSH_LSM_AUTHORIZATION='Bearer <token>'
dsh --profile web
卸載插件（不停止 LSM 進程）：
dsh plugin --profile web remove local-shell-mcp-dsh
典型用法¶
在 Shell 中執行命令¶
模型通過 mcp__lsm__run_shell 在工作區內執行構建、測試或 Git 操作。持久化 Shell 適合需要保留環境變量的連續調試。
管理跨輪次任務¶
啓動任務時調用 session_manage(action="start", ...)，跨對話續作時顯式傳入已有 session_id 並 resume。智能體應在關鍵節點用 report 彙報語義進度，並在回合結束前告知當前 session_id。
操作遠程機器¶
在已註冊 Remote Worker 的環境中，通過 remote_manage、remote_transfer 或指定 machine 參數的常規工具，與 ChatGPT 等其他 LSM 客戶端共用同一控制器狀態。
在 DSH 中查看 Live Workspace¶
開啓對話後，從會話視圖進入 Live Workspace，可查看與當前 DSH Session 綁定的終端、文件變更、作業與審計記錄；界面操作經服務端憑證訪問 LSM API，不經過模型上下文。
適用場景與注意¶
適合誰
- 需要在 DSH 對話內直接跑 CLI、改代碼、看 diff 的智能體開發者。
- 已有或計劃部署 LSM 控制器，並可能接入防火牆後遠程 Worker 的團隊。
- 希望用 Live Workspace 統一查看執行活動，而不是在對話裏粘貼大段命令輸出的場景。
使用前請注意
- 權限邊界：插件以當前 DSH 進程權限運行，LSM 工具可在配置的工作區內執行 Shell 與文件操作。安裝前應閱讀源碼與 MIT 許可證，確認工作區根目錄與網絡暴露符合你的安全策略。
- 先啓 LSM，再裝插件：bundle 只負責橋接，不負責啓動控制器。
- 傳輸失敗不重放：發生歧義性傳輸故障時，模型工具調用不會自動重放，避免 Shell/文件/遠程等變更性操作執行兩次。
- Node 版本：DSH bundle 要求 Node.js >= 22（見倉庫
package.json）。 - 社區目錄：SkillHub 是面向中國用戶的 Skills 社區站點，與 DeepSeek / 幻方無官方從屬關係；插件信息以目錄頁與 GitHub 倉庫爲準。
結尾¶
local-shell-mcp 把真實 CLI 環境、文件工作區、瀏覽器自動化與遠程 Worker 收斂到單一 MCP 控制平面；作爲 DSH 插件時，它保留完整 mcp__lsm__* 工具面，併爲每個會話提供獨立的 Live Workspace。若你正在 DSH 裏搭建能動手改代碼、跑命令的智能體，可先在同機部署 LSM，再按上文步驟接入 DSH Web。
- SkillHub 目錄頁：fwerkor/local-shell-mcp
- GitHub 倉庫：github.com/fwerkor/local-shell-mcp
- DSH 集成文檔：DeepSeek Harness (DSH)
