Deskmate

🚀 桌面助手（Deskmate）

Deskmate 是一款本地執行代理工具，允許你使用自然語言控制個人計算機，並能在你常用的通訊渠道與你交互。它專注於執行任務，而非自主決策或編排任務。你可以通過手機發送 Telegram 消息，讓計算機執行相應操作。Deskmate 支持多種代理後端，如 Claude Code、Codex (OpenAI)、Gemini CLI 和 OpenCode，可全面訪問本地工具，無沙盒命令限制，無人工設定的使用限制。

🚀 快速開始

選項 A：從 npm 安裝（推薦）

npm install -g @sarkar-ai/deskmate
deskmate init

安裝嚮導會引導你完成所有設置，包括 API 密鑰、Telegram 憑證、平臺權限和後臺服務設置。配置信息存儲在 ~/.config/deskmate/.env 中。

設置完成後，你可以手動運行 deskmate，也可以讓後臺服務自動處理。

選項 B：從源代碼安裝（適用於貢獻者）

git clone https://github.com/sarkar-ai-taken/deskmate.git
cd deskmate
npm install --legacy-peer-deps
npm run build
./install.sh          # 交互式操作：配置 .env、服務和權限

或者，你也可以使用 TypeScript 嚮導代替 shell 安裝程序：

cp .env.example .env  # 用你的憑證編輯
npx deskmate init     # 或者：npm link && deskmate init

若要稍後重新配置，可運行 deskmate init。

✨ 主要特性

• 全面本地訪問：代理可以運行任何命令，讀寫任何文件，進行屏幕截圖。無 6 工具沙盒限制。
• 多渠道網關：目前支持 Telegram，未來將支持 Discord、Slack、WhatsApp 等。一個網關，多個客戶端。
• 對話記憶：跨消息保持會話連續性，可自然地提出後續問題。
• 多代理後端：默認使用 Claude Code，還支持 Codex (OpenAI)、Gemini CLI (Google) 和 OpenCode。可在 .env 中通過 AGENT_PROVIDER=codex 切換。
• 默認批准：安全命令自動批准。受保護文件夾（桌面、文檔等）通過內聯按鈕提示確認。
• MCP 服務器：將你的計算機作為工具服務器暴露給 Claude Desktop 或任何 MCP 客戶端。
• 技能系統：在 skills.json 中定義可重複使用的多步驟工作流。技能可以運行命令、代理提示或其他技能，文件更改時自動熱加載。
• 定時任務調度器：通過 crons.json 安排定期任務（命令、代理查詢或技能），結果將發送到你活躍的聊天渠道。
• 健康監控：內置 CPU、內存、磁盤和代理可用性的健康檢查。可通過 Telegram 中的 /health、CLI 中的 deskmate health 或 get_health MCP 工具訪問。
• Docker 容器模式：在 Docker 中運行核心，使用原生邊車處理主機命令。設置 INSTALL_MODE=container 並使用 docker-compose up。
• 作為服務運行：支持 launchd (macOS) 或 systemd (Linux) 集成，開機啟動，崩潰自動重啟。
• 可擴展代理層：通過 registerProvider() 引入自定義代理。

📦 安裝指南

系統要求

• macOS（在 Ventura、Sonoma、Sequoia 上測試）或 Linux（支持 systemd）
• 通過 WSL2 在 Windows 上運行
• Node.js 18+
• 安裝支持的代理 CLI 之一（見 代理提供商）
• Telegram 賬戶（用於 Telegram 模式）
• 所選提供商的 API 密鑰（Anthropic、OpenAI 或 Google，OpenCode 自行管理認證）

Linux 前置要求

• 屏幕截圖：安裝 ImageMagick (sudo apt install imagemagick) 以支持屏幕截圖
• 服務：支持用戶會話的 systemd (systemctl --user)

macOS 權限

安裝程序會引導你完成這些設置（僅適用於 macOS），你也可以在 系統設置 > 隱私與安全 中手動配置。

💻 使用示例

基礎用法

系統管理：“顯示磁盤使用情況”、“哪些進程佔用最多 CPU？”、“列出所有正在運行的 Docker 容器”

文件操作：“顯示 package.json 的內容”、“查找 src/ 目錄下的所有 TypeScript 文件”、“創建一個名為 notes.txt 的新文件，幷包含今天的日期”

開發：“運行測試”、“查看 git 狀態”、“顯示最近的提交記錄”

故障排除：“哪個程序佔用了 8080 端口？”、“顯示錯誤日誌的最後 50 行”、“檢查 nginx 是否正在運行”

視覺操作：“進行屏幕截圖”、“顯示屏幕內容”

高級用法

Deskmate 支持多種複雜操作，例如使用技能系統和定時任務調度器。你可以定義自己的技能，並通過 Telegram 命令或 MCP 工具調用。

📚 詳細文檔

運行模式

注意：deskmate telegram 仍然可用，但它是一個已棄用的別名，用於啟動網關。

網關模式

網關是運行 Deskmate 的默認方式。它將平臺 I/O 與代理邏輯分離，因此添加新的消息客戶端無需修改認證、會話或代理層。

# 配置多客戶端認證
ALLOWED_USERS=telegram:123456,discord:987654321

# 啟動
deskmate

網關會根據可用的環境變量自動註冊客戶端。如果設置了 TELEGRAM_BOT_TOKEN，則 Telegram 客戶端將啟用。未來的客戶端（Discord、Slack）遵循相同的模式。

機器人命令

MCP 服務器

MCP 服務器將你的計算機作為工具服務器暴露給 Claude Desktop 或任何 MCP 客戶端。

與 Claude Desktop 一起設置

在 ~/Library/Application Support/Claude/claude_desktop_config.json 中添加以下內容：

{
  "mcpServers": {
    "deskmate": {
      "command": "node",
      "args": ["/path/to/deskmate/dist/index.js", "mcp"],
      "env": {
        "WORKING_DIR": "/Users/yourname"
      }
    }
  }
}

重啟 Claude Desktop，你現在可以讓 Claude 與你的本地計算機進行交互。

組合模式（網關 + MCP）

使用 deskmate both 同時運行兩者。MCP 處理 Claude Desktop 請求，網關處理 Telegram（以及未來的客戶端），將批准通知發送到你的手機，以便你可以在任何地方批准敏感操作。

可觀測性

Deskmate 專注於安全地執行操作。 若要監控多個本地代理的行為、資源使用情況和故障，請查看 Riva（本地優先代理可觀測性）。

技能

技能是在 JSON 中定義的可重複使用的多步驟工作流。將 skills.json 放在項目根目錄或 ~/.config/deskmate/skills.json 中以實現全局技能。文件更改時，技能會自動熱加載。

{
  "version": 1,
  "skills": [
    {
      "name": "deploy",
      "description": "構建並部署項目",
      "parameters": [{ "name": "env", "required": true }],
      "steps": [
        { "type": "command", "command": "npm run build" },
        { "type": "command", "command": "./deploy.sh {{env}}" }
      ]
    }
  ]
}

每個步驟可以是 command（shell 命令）、prompt（代理查詢）或 skill（嵌套技能）。可以通過 Telegram 中的 /skill deploy env=staging 或 run_skill MCP 工具運行。

定時任務

通過 crons.json（項目本地或 ~/.config/deskmate/crons.json）安排定期任務。

{
  "version": 1,
  "jobs": [
    {
      "name": "daily-backup",
      "schedule": "0 2 * * *",
      "action": { "type": "command", "command": "tar czf ~/backup.tar.gz ~/Documents" },
      "notify": true
    }
  ]
}

操作可以是 command、agent_query（自然語言提示）或 skill。設置 notify: true 以在活躍的聊天渠道接收結果。可以通過 Telegram 中的 /cron 或 list_cron_jobs MCP 工具檢查狀態。

安全性

⚠️ 重要提示

代理可以在你的計算機上執行任意命令。這是設計使然，策略是對只讀操作默認批准，對受保護文件夾和寫操作進行批准控制。

內置保護機制

批准工作流程

1. 用戶發送觸發敏感操作的消息（例如，寫入 ~/Documents）
2. ApprovalManager 檢查操作是否匹配安全自動批准模式
3. 如果不安全，創建帶有超時倒計時的待批准請求
4. 批准請求廣播到最近活躍（過去 30 分鐘）的所有客戶端
5. 用戶通過內聯按鈕（Telegram）或等效方式點擊批准/拒絕
6. 批准後執行操作，拒絕或超時則取消操作

設置 REQUIRE_APPROVAL_FOR_ALL=true 可對所有操作進行批准控制，包括讀取操作。

建議

• 設置 WORKING_DIR 以限制默認命令範圍
• 使用 ALLOWED_USERS 進行多客戶端白名單設置
• 使用 ALLOWED_FOLDERS 預先批准特定目錄
• 定期查看日誌（logs/stdout.log）
• 確保 .env 文件安全，切勿提交
• 如果你希望對每個操作進行批准控制，請使用 REQUIRE_APPROVAL_FOR_ALL=true

執行理念

Deskmate 遵循 默認批准、設計可見 的模型。

• 只讀操作自動批准
• 敏感操作需要明確確認
• 所有操作都在本地記錄

目標是在不隱藏行為的情況下實現快速執行。

非目標

Deskmate 有意不具備以下功能：

• 多代理編排框架
• 雲託管控制平面
• 長期運行的自主系統

這些限制是有意為之。

代理提供商

Deskmate 支持多種代理後端。在 .env 中設置 AGENT_PROVIDER，或在 deskmate init 期間選擇。

# 切換提供商
AGENT_PROVIDER=codex
OPENAI_API_KEY=sk-...

# 或者使用嚮導
deskmate init

僅需要所選提供商的 API 密鑰。如果切換回其他提供商，.env 中會保留其他提供商的密鑰。

架構

src/
├── core/
│   ├── agent/
│   │   ├── types.ts              # 代理提供商接口
│   │   ├── factory.ts            # 提供商工廠 + registerProvider()
│   │   └── providers/
│   │       ├── claude-code.ts    # Claude Code SDK（默認）
│   │       ├── base-cli.ts       # CLI 生成提供商的基類
│   │       ├── codex.ts          # Codex (OpenAI)
│   │       ├── gemini.ts         # Gemini CLI (Google)
│   │       └── opencode.ts       # OpenCode
│   ├── approval.ts               # 批准管理器（自動批准 + 手動）
│   ├── executor.ts               # 命令執行、文件 I/O、屏幕截圖
│   ├── executor-factory.ts       # 創建本地或遠程執行器
│   ├── executor-interface.ts     # IExecutor 接口
│   ├── remote-executor.ts        # 委託給邊車的執行器
│   ├── health.ts                 # 健康監控（CPU、內存、磁盤、代理）
│   ├── skills/                   # 技能系統
│   │   ├── types.ts              # 技能定義模式（Zod）
│   │   ├── registry.ts           # 加載 skills.json，文件更改時熱加載
│   │   └── executor.ts           # 運行多步驟技能工作流
│   ├── cron/                     # 定時任務調度器
│   │   ├── types.ts              # 定時任務定義模式（Zod）
│   │   └── scheduler.ts          # 基於 node-cron 的任務運行器
│   └── logger.ts                 # 結構化日誌記錄
├── gateway/
│   ├── types.ts                  # 消息客戶端、消息處理程序接口
│   ├── gateway.ts                # 中央協調器
│   ├── security.ts               # 多客戶端白名單認證
│   └── session.ts                # 會話管理器（複合鍵、閒置清理）
├── clients/
│   └── telegram.ts               # Telegram 適配器（grammY）
├── sidecar/                      # 容器模式下的主機邊車
│   ├── server.ts                 # 通過 HTTP 暴露執行器的 Express 服務器
│   └── cli.ts                    # 邊車 CLI 入口點
└── mcp/
    └── server.ts                 # MCP 服務器

代理層：提供四個提供商：Claude Code（通過 @anthropic-ai/claude-agent-sdk）、Codex、Gemini CLI 和 OpenCode。三個非 Claude 提供商擴展了 BaseCliProvider，該類處理子進程生成和標準輸出流。可以通過 registerProvider() 註冊自定義代理提供商。

網關層：中央協調器處理認證（SecurityManager）、會話（SessionManager）、代理編排、批准路由和屏幕截圖交付。平臺適配器實現 MessagingClient 接口，僅處理 I/O。

添加新客戶端

1. 創建 src/clients/discord.ts 實現 MessagingClient（見 src/gateway/types.ts）
2. 在 .env 中添加 DISCORD_BOT_TOKEN
3. 將 discord:userId 添加到 ALLOWED_USERS
4. 在網關啟動時註冊：gateway.registerClient(new DiscordClient(token))

無需更改網關、SecurityManager、SessionManager 或代理層。

引入自定義代理

import { AgentProvider, registerProvider } from "./core/agent";

class MyAgent implements AgentProvider {
  readonly name = "my-agent";
  readonly version = "1.0.0";
  // 實現 query()、queryStream()、isAvailable()
}

registerProvider("my-agent", MyAgent);
// 然後在 .env 中設置 AGENT_PROVIDER=my-agent

CLI 命令

Docker / 容器模式

在 Docker 容器中運行 Deskmate，使用原生邊車處理主機級命令（屏幕截圖、文件訪問）。

# 設置安裝模式
INSTALL_MODE=container

# 在主機上啟動邊車
deskmate sidecar

# 啟動容器
docker-compose up -d

包中包含 Dockerfile 和 docker-compose.yml。邊車暴露一個本地 HTTP API，容器化核心使用該 API 在主機上執行命令。

服務管理

macOS (launchd)

# 查看日誌
tail -f logs/stdout.log
tail -f logs/stderr.log

# 停止服務
launchctl unload ~/Library/LaunchAgents/com.deskmate.service.plist

# 啟動服務
launchctl load ~/Library/LaunchAgents/com.deskmate.service.plist

# 檢查狀態
launchctl list | grep deskmate

Linux (systemd)

# 查看日誌
tail -f logs/stdout.log
journalctl --user -u deskmate.service -f

# 停止 / 啟動 / 重啟
systemctl --user stop deskmate.service
systemctl --user start deskmate.service
systemctl --user restart deskmate.service

# 檢查狀態
systemctl --user status deskmate.service

卸載

./uninstall.sh

故障排除

機器人無響應？

1. 檢查日誌：tail -f logs/stderr.log
2. 驗證 ALLOWED_USERS 中包含你的 Telegram ID（例如 telegram:123456）
3. 確保已安裝代理 CLI（例如 which claude、which codex、which gemini、which opencode）
4. 運行 deskmate doctor 診斷配置問題

命令超時？

• 默認超時時間為 2 分鐘
• 長時間運行的命令可能需要調整

計算機進入睡眠狀態？

• macOS：運行 ./install.sh 配置防止睡眠，或手動執行 sudo pmset -c sleep 0
• Linux：systemd 服務使用閒置抑制劑。檢查桌面環境的電源設置。

權限被拒絕錯誤？（macOS）

• 重新運行 ./install.sh 並完成權限設置
• 或者在系統設置 > 隱私與安全 中手動授予權限

屏幕截圖無法工作？

• macOS：在系統設置 > 隱私與安全 > 屏幕錄製 中授予屏幕錄製權限
• Linux：安裝 ImageMagick (sudo apt install imagemagick)
• 更改設置後重啟服務

🔧 技術細節

Deskmate 的工作流程如下：

Telegram / Discord* / Slack* / ...
            |
            v
  +-------------------+
  |      網關         |    認證、會話、批准路由
  |  (控制平面)       |
  +--------+----------+
           |
           v
  +-------------------+
  |   代理提供商      |    Claude Code | Codex | Gemini | OpenCode
  |   (可插拔)        |    全面本地工具訪問
  +-------------------+
           |
           v
     你的計算機
     (執行任務)

*Discord 和 Slack 適配器正在計劃中 — 見 添加新客戶端。

網關是控制平面。每個消息平臺是一個輕量級 I/O 適配器。代理可以無限制地訪問你的計算機（默認批准），對受保護文件夾可選擇進行批准控制。

📄 許可證

本項目採用 MIT 許可證，詳情見 LICENSE。

致謝

• Claude Agent SDK — 默認代理運行時
• Codex — OpenAI 代理後端
• Gemini CLI — Google 代理後端
• OpenCode — OpenCode 代理後端
• grammY — Telegram 機器人框架
• @modelcontextprotocol/sdk — MCP 支持

社區

• Discord — 加入社區，提問，分享你的設置

分享

如果你覺得 Deskmate 有用，歡迎分享：

• 在 X 上分享
• 發佈到 Hacker News