使用模式与提示词指南

local-shell-mcp 暴露的是强工具集。好的结果依赖清晰的工作方式：先检查，再小步行动，随后验证，并说明改动了什么。

通用操作循环

大多数编程任务可以使用这个循环：

1. 检查：environment_get、file_tree、run_shell、file_grep、file_read。
2. 计划：让模型识别最小相关文件和测试。
3. 编辑：使用 file_edit、file_patch 或 shell 命令。
4. 验证：用 run_shell 或持久 shell 运行定向测试或构建。
5. 复查：需要时使用 run_shell、secret_scan、audit_tail。
6. 提交或导出：通过 run_shell 执行明确的 Git CLI 命令，或使用 link_create。

工具选择

任务	优先使用	避免
快速一次性命令	run_shell	每个命令都启动持久 shell
长时间开发服务器、REPL、watch 任务	shell_start + shell_read + shell_send	用阻塞式 run_shell 等到超时
结构化分析或生成文件	run_python	用脆弱的 shell 管道处理复杂 JSON / 文本
小范围精确编辑	file_edit	无必要地重写整个文件
同一文件多处替换	file_edit	不重新读取文件就反复做陈旧编辑
多文件补丁	file_patch	临时拼接 shell 编辑命令
查找文件	file_tree、file_glob	对大型仓库做完整递归列表
查找代码	file_grep	盲目读取大量文件
浏览器证据	browser_snapshot、browser_run_script	只根据页面名或路由猜测
可下载产物	link_create	在聊天中粘贴大型二进制内容
远程机器任务	普通工具加 machine，以及 remote_transfer	在出站 worker 模式足够时开放入站 SSH

从 CLI 调用工具

对于 shell 脚本和 CI，lsm call <tool> 会通过正在运行的本地回环 controller 调用同一套已注册工具，因此远程 worker 和 controller 状态都能保留。

lsm call run_shell --json '{"command":"uname -a"}'
printf '%s\n' '{"path":"README.md"}' | lsm call file_read

使用 --session s_... 可将调用关联到 Logical Session。在文档给出的 Docker Compose 配置中，原始 LOCAL_SHELL_MCP_CLI_LOCAL_TOKEN 只保存在宿主机拥有且权限受限的 .env 中，Compose 只把它的 SHA-256 校验值传给 controller；其它分离运行时布局可传入 --token-file <path>。--direct 会绕过 controller，在进程内应用当前 .env 的运行时配置，但不会把宿主机 CLI token 注入工具环境，并且仅支持本地调用。 Human UI token 永远不能用于 /mcp；分离运行时的 controller 必须配置匹配的 LOCAL_SHELL_MCP_CLI_LOCAL_TOKEN_SHA256。

提示词模板

只读仓库摸底

使用 local-shell-mcp。检查仓库结构和 git 状态。不要修改文件。先总结主要组件、能推断出的测试命令以及明显风险，再考虑后续改动。

聚焦修复 bug

使用 local-shell-mcp 修复这个 bug。先用最小相关命令复现或定位问题。编辑前读取相关文件。做最小补丁，运行定向验证，然后展示 git diff 和实际运行的测试。未经我批准不要提交。

提交并推送工作流

使用 local-shell-mcp。检查 git status 和 diff，运行相关测试，运行 secret_scan，创建一个聚焦的提交并写简洁提交信息，然后推送当前分支。不要包含缓存、构建产物或无关格式化。

长时间进程

在持久 shell session 中启动开发服务器，读取输出直到服务就绪，然后使用浏览器工具验证页面。保留 session id，验证后关闭该 session。

远程 worker 任务

使用名为 <machine> 的已连接远程 worker。先调用 environment_get(machine=<machine>) 和 file_list(machine=<machine>)。只在配置的远程工作目录内操作。短命令用 run_shell，长时间任务用 shell_start 或 job_start。

处理仓库

开源改动建议流程：

1. 用 run_shell 检查是否有未提交改动。
2. 如果任务依赖上游状态，使用 run_shell 并检查分支。
3. 编辑前用 file_grep 和 file_read 定位相关代码。
4. 做最小补丁。
5. 先跑定向测试；可行时再跑更广的测试。
6. 提交或推送前运行 secret_scan。
7. 提交信息简洁描述行为变化。

当维护者需要可审查历史时，每个逻辑改动单独一个提交。

处理生成产物

对于 PDF、报告、截图、压缩包或日志：

1. 在工作区内生成文件。
2. 验证文件存在且大小符合预期。
3. 使用 link_create，设置较短 TTL 和可选 max_downloads。
4. 不再需要时撤销链接。

不要为私钥、凭据目录或无关个人数据创建公开链接。

处理远程机器

当机器能发起出站 HTTPS、但无法接收入站 SSH 时，远程 worker 模式很有用。

推荐做法：

• 用 remote_manage(action="invite", ...) 创建机器，或用 remote_manage(action="rename", ...) 重命名。
• 操作前检查 environment_get。
• 用 remote_transfer 处理控制端与 worker、或 worker 之间的文件和目录传输。
• 任务结束后用 remote_manage(action="revoke", ...) 撤销 worker。

反模式

除非环境是一次性的，且你理解后果，否则避免这些指令：

• 在宿主机启动的服务上“全局安装任何需要的东西”。
• 没有时间边界或验证标准地“跑到能用为止”。
• 在包含生成产物的仓库里“提交所有东西”。
• 为了方便暴露整个 home 目录。
• 为整个工作区创建文件链接。
• 在公开部署中使用 LOCAL_SHELL_MCP_AUTH_MODE=none。