前言¶
在 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)
