desktop-commander

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Desktop Commander

Quick start

快速开始

Goal: use Desktop Commander MCP to turn “files / processes / search / edits” into verifiable tool calls (small, safe steps) instead of treating the machine as a black box.

Most common entry points:

Read content:
```
mcp__desktop-commander__read_file
```
(paging, negative offset tail, PDF/image/Excel/URL).
Small edits:
```
mcp__desktop-commander__edit_block
```
(targeted text replace / Excel range update).

Large edits:

mcp__desktop-commander__write_file

in chunks (respect

fileWriteLineLimit

Interactive work:

mcp__desktop-commander__start_process

mcp__desktop-commander__interact_with_process

mcp__desktop-commander__read_process_output

Official notes + tool list:

skills/desktop-commander/references/desktop-commander.md

目标：使用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

。

Workflow decision tree

工作流决策树

Do I need to find something?

File names/paths:

mcp__desktop-commander__start_search

(

searchType="files"

) →

mcp__desktop-commander__get_more_search_results

File contents:

mcp__desktop-commander__start_search

(

searchType="content"

) → paginate →

mcp__desktop-commander__stop_search

when done

Do I need to read or change content?

Read:

mcp__desktop-commander__read_file

(use

offset/length

; use

offset=-N

for tail)

Small change:
```
mcp__desktop-commander__edit_block
```
(default replaces 1 occurrence; use
```
expected_replacements
```
for multiple)

Large change:

mcp__desktop-commander__write_file

(

mode="rewrite"

then

mode="append"

chunked)

Do I need to run commands / keep sessions?

One-off commands:
```
mcp__desktop-commander__start_process
```
(shell command) + read output

REPL / SSH / DB / dev server:

start_process

→

interact_with_process

→

read_process_output

Is this a high-risk operation (config changes, killing processes, bulk edits/moves, any data loss)?

Explain impact + rollback first; require explicit user confirmation before executing.
Prefer making config changes in a separate chat (official guidance).

是否需要查找内容？

文件名/路径：

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

是否需要读取或修改内容？

读取：

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"

）

是否需要运行命令/保持会话？

一次性命令：
```
mcp__desktop-commander__start_process
```
（执行shell命令）+ 读取输出

REPL / SSH / 数据库 / 开发服务器：

start_process

→

interact_with_process

→

read_process_output

是否属于高风险操作（配置修改、终止进程、批量编辑/移动、可能导致数据丢失的操作）？

先说明影响及回滚方案；执行前需获得用户明确确认。
建议在单独会话中进行配置修改（官方指导）。

Recipes

操作指南

Reading files

读取文件

Text/code:
```
read_file
```
with pagination; logs:
```
offset=-200
```
(tail-like).
Multiple files:
```
read_multiple_files
```
to reduce round trips.
URLs:
```
read_file
```
with
```
isUrl: true
```
for web content/images.

文本/代码：使用
```
read_file
```
分页读取；日志文件：使用
```
offset=-200
```
（类似tail命令）。
多文件：使用
```
read_multiple_files
```
减少往返次数。
URL：设置
```
isUrl: true
```
后使用
```
read_file
```
读取网页内容/图片。

Editing files

编辑文件

Targeted replace:
```
edit_block
```
with minimal unique context; for many occurrences set
```
expected_replacements
```
.
Rewrites:
```
write_file
```
in 25–30 line chunks (
```
rewrite
```
then
```
append
```
).
Excel: read via
```
read_file
```
; edit via
```
edit_block
```
with
```
range
```
+ 2D array.
PDFs: only via
```
write_pdf
```
(do not use
```
write_file
```
for PDFs).

目标替换：使用
```
edit_block
```
并提供最少唯一上下文；多替换场景设置
```
expected_replacements
```
参数。
重写：分25-30行块使用
```
write_file
```
（先
```
rewrite
```
再
```
append
```
）。
Excel：使用
```
read_file
```
读取；使用
```
edit_block
```
并配合
```
range
```
参数+二维数组进行编辑。
PDF：仅通过
```
write_pdf
```
操作（请勿使用
```
write_file
```
处理PDF）。

Search

搜索

Prefer
```
start_search
```
+
```
get_more_search_results
```
for repo exploration; stop searches you no longer need.
Use
```
literalSearch: true
```
for patterns with special characters (parentheses, brackets, dots, etc.).

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

Processes & interaction

进程与交互

Data analysis: run
```
python3 -i
```
, then use
```
interact_with_process
```
for pandas/numpy workflows.
Observing long jobs: call
```
read_process_output
```
periodically; to stop use
```
kill_process
```
/
```
force_terminate
```
(high-risk).
Status:
```
list_sessions
```
/
```
list_processes
```
.

数据分析：运行
```
python3 -i
```
，然后使用
```
interact_with_process
```
进行pandas/numpy工作流操作。
监控长期任务：定期调用
```
read_process_output
```
；终止任务使用
```
kill_process
```
/
```
force_terminate
```
（高风险操作）。
状态查看：
```
list_sessions
```
/
```
list_processes
```
。

Config & audit

配置与审计

```
get_config
```
/
```
set_config_value
```
: use carefully; directory restrictions are not a security boundary for terminal commands.
```
get_recent_tool_calls
```
: recover context and debug “what happened”.
```
get_usage_stats
```
: usage/performance insight.

```
get_config
```
/
```
set_config_value
```
：谨慎使用；目录限制并非终端命令的安全边界。
```
get_recent_tool_calls
```
：恢复上下文并调试“操作历史”。
```
get_usage_stats
```
：获取使用情况/性能洞察。

Guardrails (must follow)

约束规则（必须遵守）

Prefer absolute paths; don’t assume OS-specific separators.
For big changes: read first; keep edits small; chunk writes; keep rollback in mind.
High-risk actions require explicit confirmation: config changes, killing sessions/processes, bulk file edits/moves, any destructive command.
Security:
```
allowedDirectories
```
limits filesystem tools, not terminal commands—don’t treat it as sandboxing.

优先使用绝对路径；不要假设特定操作系统的路径分隔符。
大型修改：先读取内容；保持编辑粒度小；分块写入；提前考虑回滚方案。
高风险操作需明确确认：配置修改、终止会话/进程、批量文件编辑/移动、任何破坏性命令。
安全提示：
```
allowedDirectories
```
仅限制文件系统工具，不限制终端命令——请勿将其视为沙箱环境。

References

参考资料

Official notes + tool list:

skills/desktop-commander/references/desktop-commander.md

官方说明+工具列表：

skills/desktop-commander/references/desktop-commander.md