desktop-commander

Desktop Commander

快速入门

目标：使用 Desktop Commander MCP 将“文件 / 进程 / 搜索 / 编辑”转化为可验证的工具调用（小步、安全），而不是把机器当作黑箱。

最常用的入口：

• 读取内容：mcp__desktop-commander__read_file（分页、负偏移量读取末尾、PDF / 图片 / Excel / URL）。
• 小范围编辑：mcp__desktop-commander__edit_block（定点替换文本 / 更新 Excel 区域）。
• 大范围编辑：分块使用 mcp__desktop-commander__write_file（遵守 fileWriteLineLimit）。
• 交互式操作：mcp__desktop-commander__start_process + mcp__desktop-commander__interact_with_process + mcp__desktop-commander__read_process_output。

官方说明和工具列表：skills/desktop-commander/references/desktop-commander.md。

工作流决策树

1. 我需要查找内容吗？

• 文件名 / 路径：mcp__desktop-commander__start_search（searchType="files"）→ mcp__desktop-commander__get_more_search_results
• 文件内容：mcp__desktop-commander__start_search（searchType="content"）→ 分页浏览 → 完成后使用 mcp__desktop-commander__stop_search

2. 我需要读取或更改内容吗？

• 读取：mcp__desktop-commander__read_file（使用 offset/length；使用 offset=-N 读取末尾）
• 小范围更改：mcp__desktop-commander__edit_block（默认替换 1 处；多处替换时使用 expected_replacements）
• 大范围更改：mcp__desktop-commander__write_file（分块使用 mode="rewrite"，然后使用 mode="append"）

3. 我需要运行命令 / 保持会话吗？

• 一次性命令：mcp__desktop-commander__start_process（shell 命令）+ 读取输出
• REPL / SSH / DB / 开发服务器：start_process → interact_with_process → read_process_output

4. 这是高风险操作吗（配置更改、终止进程、大批量编辑 / 移动、任何数据丢失）？

• 执行前先说明影响和回滚方案；执行前必须获得用户的明确确认。
• 优先在单独的聊天中更改配置（官方指南）。

操作示例

读取文件

• 文本 / 代码：使用 read_file 分页读取；日志：使用 offset=-200（类似读取末尾）。
• 多个文件：使用 read_multiple_files 减少往返调用。
• URL：使用 read_file 并设置 isUrl: true 读取网页内容 / 图片。

编辑文件

• 定点替换：使用 edit_block 并提供尽可能精简的唯一上下文；需替换多处时设置 expected_replacements。
• 重写：使用 write_file，每次分块处理 25–30 行（先 rewrite，再 append）。
• Excel：使用 read_file 读取；使用 edit_block 和 range + 二维数组编辑。
• PDF：只能通过 write_pdf 操作（不要对 PDF 使用 write_file）。

搜索

• 探索代码仓库时，优先使用 start_search + get_more_search_results；不再需要的搜索应停止。
• 对包含特殊字符（括号、方括号、点等）的模式，使用 literalSearch: true。

进程与交互

• 数据分析：运行 python3 -i，然后使用 interact_with_process 执行 pandas/numpy 工作流。
• 观察长时间运行的任务：定期调用 read_process_output；停止任务时使用 kill_process / force_terminate（高风险）。
• 状态：list_sessions / list_processes。

配置与审计

• get_config / set_config_value：谨慎使用；目录限制并不能限制终端命令。
• get_recent_tool_calls：恢复上下文并排查“发生了什么”。
• get_usage_stats：查看使用情况 / 性能。

安全准则（必须遵守）

• 优先使用绝对路径；不要假定操作系统特定的分隔符。
• 对于大型更改：先读取；保持编辑范围较小；分块写入；牢记回滚方案。
• 高风险操作必须获得明确确认：更改配置、终止会话 / 进程、大批量编辑 / 移动、任何破坏性命令。
• 安全性：allowedDirectories 限制的是文件系统工具，不限制终端命令——不要将其视为沙盒。

参考资料

• 官方说明和工具列表：skills/desktop-commander/references/desktop-commander.md