本地工具

本地工具是 Deskmate 内置的桌面能力。它们让 Agent 在用户授权和配置范围内读取文件、写入产物、编辑内容、运行命令、搜索网页、调用应用内功能。

本页解释本地工具与 MCP 的区别，介绍顶层工具，并重点说明 app 与 web 这两个伪 shell 的设计与风险边界。

本地工具是什么

本地工具是直接运行在你电脑上的能力。Agent 通过它们触达本机文件系统、shell 和网络，因此既强大，也需要谨慎使用。

Deskmate 在设计本地工具时遵循几条核心原则：

工具入口少而清晰，避免 Agent 在过多选项中犹豫。
复杂能力通过 CLI 风格渐进披露，按需展开。
Agent 可以读取错误信息并自我修正。
有副作用的操作应保持可见和可控。

本地工具 vs MCP

本地工具和 MCP 是两类不同的能力来源。下表对比它们的定位：

类型	来源	适合做什么	风险
本地工具	Deskmate 内置	文件、shell、web、应用内命令	本地副作用
MCP	外部 server	连接第三方服务和数据源	外部权限和数据处理

两者是平级能力。MCP 不是本地工具的包装，本地工具也不是 MCP server。

如果你想了解如何接入外部 server，请参阅 MCP 指南。

工具总览

Deskmate 的本地工具入口刻意保持精简，顶层只有少数几个：

`read`

读取文件、URL 或内部资源。适合让 Agent 先确认上下文。

`write`

创建或覆盖文件。适合生成明确产物。

`edit`

结构化编辑已有文件。适合精确修改。

`shell`

执行真实 shell 命令。适合运行项目命令、脚本、构建、测试。

`web`

搜索网页、抓取内容、下载资源、交互式研究。

`app`

以 shell 风格调用 Deskmate 应用内能力，例如 Agent、MCP、Skill、Schedule 等。

`app` 伪 shell

用 CLI 范式组织应用能力

app 把应用内功能组织成命令行风格接口。Agent 可以通过 app --help 查看能力，通过 app mcp --help 查看子命令，再按需执行。

下面是一组典型调用：

app --help
app mcp --help
app mcp status --json
app agent list
app schedule list

这种设计带来几个优势：

顶层工具数量少，模型不必在大量入口间选择。
帮助文档渐进披露，用到什么再展开什么。
--json 适合结构化读取。
--dry-run 适合预演，先看效果再执行。
--yes 用于确认破坏性操作。

当 Agent 不确定某个 app 能力如何使用时，可以要求它先运行 app <command> --help。

`web` 工具

web 工具让 Agent 触达互联网，主要包含四类能力：

Search：搜索网页。
Fetch：读取页面内容。
Download：下载文件。
Interactive research：打开可见研究窗口。

常见用法示例：

web search "MCP server examples"
web fetch "https://example.com/docs"
web download "https://example.com/file.pdf"

使用 web 工具时请注意：

web 请求会访问第三方网站。
搜索关键词会发送给搜索服务。
下载文件前应确认来源可信。

`shell` 工具

shell 执行真实命令，能力强但风险也高。让 Agent 运行命令前，应先确认命令目的，尤其是会写入、删除、上传或安装依赖的命令。

shell 适合这类相对安全、目的明确的任务：

npm run typecheck
npm test
构建命令
项目脚本
只读诊断命令

对下面这些操作要保持谨慎，最好人工确认后再执行：

删除文件。
修改权限。
安装全局依赖。
上传数据。
无限循环或高频网络调用。

文件读写工具

read、edit、write 共同构成 Agent 的文件操作能力。一个实用的做法是，在任务开始前就给 Agent 一条明确指令：

涉及文件修改时，先说明你准备修改哪些文件和为什么。除非我确认，不要执行破坏性改动。

三个工具各有适用场景：

read 适合先确认，让 Agent 在动手前理解上下文。
edit 适合小范围精确修改。
write 适合新建文档或完整产物。
重要文件修改前建议备份。

安全建议

本地工具直接作用于你的电脑，建议从一开始就建立稳妥的使用习惯：

初次使用先做只读任务。
给 Agent 明确“修改前先说明计划”。
不让 Agent 处理未备份的重要文件。
不在聊天中粘贴 API key。
对 shell 命令保持人工审查。
下载未知文件前确认来源。
MCP server 和本地工具都按最小权限使用。

Deskmate 仍处于 early access 阶段，能力和行为可能调整。在涉及重要数据的场景中，请保持人工审查，并提前做好备份。

常见问题

app 是真实 shell 吗？

不是。app 是 Deskmate 应用内命令路由，但采用 shell 风格字符串、帮助和 flag 语义。

shell 和 app 有什么区别？

shell 执行操作系统命令；app 调用 Deskmate 内部能力。

Agent 会自动知道所有命令吗？

顶层能力会进入工具描述，详细用法可以通过 --help 渐进查看。

为什么不把所有功能都做成独立工具？

工具太多会让模型选择困难。CLI 风格更接近 LLM 训练语料，也更容易自解释和自恢复。