# @voyageurworks/handoff-desk 中文文档

规范地址：https://npmcn.com/package/%40voyageurworks/handoff-desk/

版本：1\.0\.3
npm 元数据更新时间：2026-11-02T19:54:08.638Z
中文译文更新时间：2026-11-02T21:13:55.287Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40voyageurworks/handoff-desk
原文对照：https://npmcn.com/package/%40voyageurworks/handoff-desk/?lang=original
项目主页：https://github.com/voyageurworks/handoff-desk#readme
源码仓库：https://github.com/voyageurworks/handoff-desk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：108 kB，26 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：3 个
- 首次发布：2026-11-02T00:41:02.202Z
- 最新版本发布：2026-11-02T19:54:08.335Z
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

将克劳德代码或光标中的任务交给个人代理，该代理读取标记笔记文件夹。

## 安装

```sh
npm install @voyageurworks/handoff-desk
```

也可以使用：`pnpm add @voyageurworks/handoff-desk`、`yarn add @voyageurworks/handoff-desk`、`bun add @voyageurworks/handoff-desk`

## README

# handoff-desk

**将编码会话中的任务交给个人代理，并读出答案。**

[![npm](https://img.shields.io/npm/v/@voyageurworks/handoff-desk.svg)](https://www.npmjs.com/package/@voyageurworks/handoff-desk) [![CI](https://github.com/voyageurworks/handoff-desk/actions/workflows/ci.yml/badge.svg)](https://github.com/voyageurworks/handoff-desk/actions/workflows/ci.yml) [![Security](https://github.com/voyageurworks/handoff-desk/actions/workflows/security.yml/badge.svg)](https://github.com/voyageurworks/handoff-desk/actions/workflows/security.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/%40voyageurworks/handoff-desk/LICENSE) [![Node](https://img.shields.io/badge/node-%E2%89%A522-339933.svg)](https://npmcn.com/package/%40voyageurworks/handoff-desk/package.json)

`handoff-desk` 是一个小的 [MCP](https://modelcontextprotocol.io/) 在您的计算机上运行的服务器。当你告诉Claude Code、Cursor、Codex或其他MCP客户端“把这个交给我的代理”时，它会在你自己的文件夹中写一份降价说明，可以选择给代理发电子邮件，然后从同一份说明中读取代理的回复。

-   **没有托管服务，没有账户，没有遥测。** 所有东西都是磁盘上的文件。
-   **可以与任何可以读取文件夹、私有git存储库或邮箱的代理一起工作。** 格式是简单的降价。
-   **默认为安全。** 看起来包含密码或密钥的请求将被拒绝，git传输将受到限制，来自代理的文本将被标记为不可信。
-   **审查。** 每个任务和答案都是一个笔记，你可以阅读、修改和删除。

## 试一试

```sh
npx -y @voyageurworks/handoff-desk init ~/handoff-demo
```

这样就创建了一个演示桌。下面的五分钟演示（将其添加到Claude Code中，用代理回答）只需要安装Node.js 22或更新版本。

## 30秒内

```text
You, in Claude Code:  "Hand this to my agent: book the dentist for Friday at 3."
handoff-desk writes:  Desk/2026-11-02 Item 01 - Book dentist.md   (status: waiting)
Your agent (any):     reads the note, does the task, writes "## Reply", sets status: done
You, same chat:       "What did my agent say?"  ->  the reply, read back from that note
```

不要与代理框架内的“移交”（一个代理在一次运行中将对话传递给另一个代理）混淆。这是异步的，在不同的程序之间：你的编码助理写一个笔记，一个不同的代理（在你的PC上，在云上，或者一个人）在可能的时候回答，然后这个笔记作为记录保存在磁盘上。

> 状态:1.0。工具和笔记格式是稳定的。代理覆盖范围很窄：每次改动都用捆绑的代理进行测试，并在git和email上用一个真正的云代理进行了测试（2026-10-26的五轮都通过了）。其他药剂未经测试。看到 [兼容性](https://npmcn.com/package/%40voyageurworks/handoff-desk/#readme-compatibility).

## 它是如何工作的

```mermaid
sequenceDiagram
    participant You as You + MCP client
    participant HD as handoff-desk (on your computer)
    participant Desk as Desk folder / private git repo
    participant Agent as Your agent
    You->>HD: handoff_send("book the dentist")
    HD->>Desk: write Desk/2026-10-29 Item 01 - dentist.md (status: waiting)
    HD-->>Agent: optional doorbell email
    Agent->>Desk: read note, do the task, write "## Reply", status: done
    You->>HD: handoff_wait / handoff_read
    HD->>Desk: read (and pull, with git)
    HD-->>You: the agent's reply
```

更多细节，包括文件夹布局和git流程，见 [文档/ architecture.md](https://npmcn.com/package/%40voyageurworks/handoff-desk/docs/architecture.md).

## 快速入门（5分钟，不需要真正的代理）

你需要 [node . js](https://nodejs.org/) 22或更新版本（包括npm）和git。 [规划](https://pnpm.io/) 作品。

**1\. 创建一个演示桌。** `init` 创建 `Desk/`， `Inbox/`， `mail/` 和一个 `handoff.md` 模板。再次运行它不会覆盖您的编辑。没有什么要先安装的； `npx` 从npm获取包：

```sh
npx -y @voyageurworks/handoff-desk init ~/handoff-demo
```

**2\. 将服务器添加到Claude Code中** (其他客户: [文档/ clients.md](https://npmcn.com/package/%40voyageurworks/handoff-desk/docs/clients.md)）. 在macOS和Linux上：

```sh
claude mcp add handoff-demo -e HANDOFF_DIR="$HOME/handoff-demo" -- npx -y @voyageurworks/handoff-desk
```

在 **Windows PowerShell**、运行 `npx` 通过 `cmd /c` 并在引号中写入双破折号(PowerShell 5.1删除了一个裸 `--`, `claude` 然后报告 `missing required argument 'commandOrUrl'`):

```powershell
claude mcp add handoff-demo -e HANDOFF_DIR="$HOME/handoff-demo" '--' cmd /c npx -y '@voyageurworks/handoff-desk'
```

**3\. 启动备用代理** 在第二个终端，让它运行。它用固定的线路回答每一个等待的项目。在macOS或Linux shell中：

```sh
HANDOFF_DIR="$HOME/handoff-demo" npx -y @voyageurworks/handoff-desk stand-in
```

在Windows PowerShell中：

```powershell
$env:HANDOFF_DIR = "$HOME/handoff-demo"
npx -y @voyageurworks/handoff-desk stand-in
```

**4\. 试一试。** 启动一个新的Claude Code会话（服务器在启动时加载），然后说： **“使用移交演示工具将此作为问题交给我的代理：用pong回答。”** 克劳德调用 `handoff_send`,然后 `handoff_wait`，并显示了替身的回答。开放 `~/handoff-demo/Desk/` 看纸条从 `status: waiting` 来 `status: done`.

**5\. 清理。** 停止替身（Ctrl+C）并运行 `claude mcp remove handoff-demo`。删除 `~/handoff-demo` 如果你愿意的话。

什么东西坏了？看到 [文档/ troubleshooting.md](https://npmcn.com/package/%40voyageurworks/handoff-desk/docs/troubleshooting.md).

改为从源代码构建（贡献者）

同一服务器，从此存储库的克隆运行。在上面的快速启动步骤中，使用 `node /absolute/path/to/handoff-desk/dist/main.js` 无论他们说什么 `npx -y @voyageurworks/handoff-desk`.

**1\. 安装和构建** （macOS、Linux和Windows）：

```sh
git clone https://github.com/voyageurworks/handoff-desk.git
cd handoff-desk
npm install
npm run build
```

规划: `pnpm install && pnpm build`.

发布版本从GitHub Actions发布到npm，并带有出处声明； `npm install -g @voyageurworks/handoff-desk` 还安装了 `handoff-desk` 命令。

**2\. 创建一个演示桌。** `init` 创建 `Desk/`， `Inbox/`， `mail/` 和一个 `handoff.md` 模板。再次运行它不会覆盖您的编辑。

```sh
node dist/main.js init ~/handoff-demo
```

**3\. 将服务器添加到Claude Code中** (其他客户: [文档/ clients.md](https://npmcn.com/package/%40voyageurworks/handoff-desk/docs/clients.md)）. 使用绝对路径 `dist/main.js` （例如，在Windows上使用正斜杠） `C:/Users/you/handoff-desk/dist/main.js`):

```sh
claude mcp add handoff-demo -e HANDOFF_DIR="$HOME/handoff-demo" -- node /absolute/path/to/handoff-desk/dist/main.js
```

在 **Windows PowerShell 5.1**，用双破折号加引号。PowerShell掉落一个裸 `--`, `claude` 然后报告 `missing required argument 'commandOrUrl'`：

```powershell
claude mcp add handoff-demo -e HANDOFF_DIR="$HOME/handoff-demo" '--' node C:/absolute/path/to/handoff-desk/dist/main.js
```

**4\. 启动备用代理** 在第二个终端，让它运行。它用固定的线路回答每一个等待的项目。在macOS或Linux shell中：

```sh
cd handoff-desk
HANDOFF_DIR="$HOME/handoff-demo" node dist/main.js stand-in
```

在Windows PowerShell中：

```powershell
cd handoff-desk
$env:HANDOFF_DIR = "$HOME/handoff-demo"
node dist/main.js stand-in
```

## 连接客户端

任何可以运行工作室MCP服务器的客户端都可以工作。你给它一个命令，它的参数和环境变量 `HANDOFF_DIR`.

| 客户端 | 指南 |
| --- | --- |
| 克劳德代码 | `claude mcp add` (上图) |
| 光标 | `mcp.json`,看 [文档/ clients.md](https://npmcn.com/package/%40voyageurworks/handoff-desk/docs/clients.md#cursor) |
| VS Code（副驾驶代理模式） | `.vscode/mcp.json`,看 [文档/ clients.md](https://npmcn.com/package/%40voyageurworks/handoff-desk/docs/clients.md#vs-code-github-copilot) |
| 食品法典（CLI和IDE） | `codex mcp add` 或者 `config.toml`,看 [文档/ clients.md](https://npmcn.com/package/%40voyageurworks/handoff-desk/docs/clients.md#codex) |
| 克劳德桌面 | `claude_desktop_config.json`,看 [文档/ clients.md](https://npmcn.com/package/%40voyageurworks/handoff-desk/docs/clients.md#claude-desktop) |
| Windsurf， Gemini CLI等 | 同样的形状，见 [文档/ clients.md](https://npmcn.com/package/%40voyageurworks/handoff-desk/docs/clients.md#windsurf-gemini-cli-and-others) |

## 连接您的代理

选择与您的代理运行位置匹配的线路。

1.  **在同一台电脑上。** 代理读取 `Desk/` 直接。没有别的设置了。
2.  **在云端。** 云代理无法看到您的文件夹，因此将桌面设置为A **私有git存储库** 代理可以读取和推送到。把桌面文件夹放到它的克隆文件中。同步功能会自动开启(`HANDOFF_SYNC=auto`)，当该文件夹是一个带有上游分支的git工作树时。细节，准确的笔记格式和给代理的规则： [文档/ cloud-agents.md](https://npmcn.com/package/%40voyageurworks/handoff-desk/docs/cloud-agents.md).
3.  **看着邮箱。** 可选的门铃电子邮件包含整个请求。设置下面的邮件变量。永远不要使用你的普通密码：使用应用程序密码，最好是通过命令获取，这样没有文件保存它([文档/ keeping-secrets.md](https://npmcn.com/package/%40voyageurworks/handoff-desk/docs/keeping-secrets.md)）。

无论你选择哪一个，把你的规则告诉代理 `handoff.md` 让它把答案写在下面 `## Reply` 并设置 `status: done`.

### 兼容性

| 代理 | 状态 |
| --- | --- |
| 捆绑替身(`stand-in` 命令) | 对每个更改进行测试 |
| 操作系统和shell | 测试在Linux、macOS和Windows上运行。快速启动在Linux和macOS的bash和zsh下运行，在Windows PowerShell 5.1中手动运行 |
| 光标，VS代码（副驾驶），克劳德桌面，法典 | 中的配置示例 [文档/ clients.md](https://npmcn.com/package/%40voyageurworks/handoff-desk/docs/clients.md) 由测试启动并完成MCP握手。编辑器本身不在CI中运行 |
| 一个真正的云代理，通过git和电子邮件 | 2026-10-26通过了五轮。第二天再来一次，没有电子邮件门铃，只得到了部分回应，因为那名特工是按时间表检查办公桌的；有了门铃，预计它会更快做出反应，但还没有重新测试 |
| 可以读取文件夹或存储库中的下调文件的任何其他代理 | 期望工作，而不是测试。 [文档/ live-acceptance.md](https://npmcn.com/package/%40voyageurworks/handoff-desk/docs/live-acceptance.md) 这是你的试用清单吗 |

## 使用

问克劳德：“把这个交给我的经纪人：预约周五3点看牙医。”克劳德调用 `handoff_send`,然后 `handoff_wait` 或者 `handoff_read` 获取回复。

| 工具 | 它是做什么的 |
| --- | --- |
| `handoff_send` | 代理的差事，问题或状态（备注加上可选的门铃邮件） |
| `handoff_status` | 单行状态更新 |
| `handoff_list`， `handoff_read` | 查看项目并完整阅读其中一个 |
| `handoff_wait` | 等待座席应答最多50秒（再次呼叫保持等待） |
| `handoff_capabilities` | 你的 `handoff.md` 说代理可以单独做，必须先问，或者永远不做 |
| `handoff_inbox`， `handoff_inbox_reply` | 阅读并回答特工留给克劳德的便条 |

如果没有配置门铃， `handoff_send` 仍然会写便条，并返回它应该发送的邮件，这样克劳德就可以用另一种方式发送了。

## 设置

将这些设置为MCP客户端的配置中的环境变量。

| 变量 | 默认的 | 意义 |
| --- | --- | --- |
| `HANDOFF_DIR` | `~/handoff` | 桌子上的文件夹 |
| `HANDOFF_MAIL_USER` | 无 | 门铃的寄件人地址 |
| `HANDOFF_MAIL_APP_PASSWORD` | 无 | 发送者的应用程序密码（不是你的正常密码） |
| `HANDOFF_MAIL_PASSWORD_COMMAND` | 无 | 打印应用程序密码的命令，仅在发送门铃时运行，因此没有文件保存它（密码管理器，加密存储；参见文档）。时使用 `HANDOFF_MAIL_APP_PASSWORD` 没有设置 |
| `HANDOFF_ENV_FILE` | 无 | 的私有文件路径 `NAME=value` 行（此表中的任何设置）。在MCP客户端的配置中保留应用程序密码。真正的环境值胜过文件。将文件保存在桌面存储库之外，并且只有您可以读取 |
| `HANDOFF_MAIL_TO` | 无 | 座席邮箱 |
| `HANDOFF_SMTP_HOST`， `HANDOFF_SMTP_PORT` | `smtp.gmail.com`， `465` | 邮件服务器 |
| `HANDOFF_MAIL_DIR` | `<HANDOFF_DIR>/mail` | 电子邮件副本的去处 |
| `HANDOFF_TZ` | 系统带 | 用于时间戳的时区 |
| `HANDOFF_SYNC` | `auto` | `auto`：通过git同步 `HANDOFF_DIR` 是一个上游的工作树。 `git`：需要它（否则是错误）。 `off`：仅本地文件夹 |
| `HANDOFF_REMOTE` | 无 | 将此存储库克隆到 `HANDOFF_DIR` 第一次使用桌面工具 |
| `HANDOFF_GIT_NAME`， `HANDOFF_GIT_EMAIL` | 存储库的git配置，否则 `handoff-desk` | 桌面提交的标识 |
| `HANDOFF_INBOX_DIR` | `Inbox` | 特工给克劳德留纸条的文件夹 |
| `HANDOFF_SUBJECT_PREFIX` | `Handoff` | 门铃邮件主题： `[<prefix> errand #3] ...` |

## 没有真正的经纪人，试试吧

这个 [快速启动](https://npmcn.com/package/%40voyageurworks/handoff-desk/#readme-quick-start-5-minutes-no-real-agent-needed) 使用替身。若要演练云路径，请第二次克隆私有桌面存储库，请设置 `HANDOFF_DIR` 到第二个克隆并运行 `node dist/main.js stand-in --git`。它只能通过git远程连接到桌面，就像云代理一样。 `stand-in --once` 回答正在等待的内容并退出。

## 安全

-   任何看起来像密码、代码、令牌或密钥的东西在写出来或通过电子邮件发送之前都会被拒绝。这是模式匹配，而不是保证：不要在请求中添加秘密。
-   使用一个 **私人** 用于礼物同步桌面的存储库。每个任务和回复都被推送到其远程并保存在其历史中。
-   不要在里面放一个访问令牌 `HANDOFF_REMOTE` (一个URL `https://token@host/...`): git将URL以纯文本的形式存储在克隆的配置文件中。请使用普通的git凭证帮助器或SSH密钥。
-   你的代理人根据你的权力行事，有些代理人代表你以约束你的方式行事。读 `handoff.md` 在依赖它之前，保持“先问”和“从不问”列表的诚实。
-   来自网页或电子邮件的文本不是您的指示。用你的 `handoff.md` （模板可以）。
-   在你自动化任何相关的东西之前，检查一下你的代理自己的服务条款：许多限制自动化，最低年龄或商业用途。

## 限制

-   在1.0中没有托管模式和推送通知。云代理通过git到达桌面（见上文）；没有别的东西能把它的回答带回去。
-   代理必须能够读取桌面（文件夹或git存储库）或门铃电子邮件，并将其回复写入注释（对于云代理来说，还可以推送它）。如果不能， `handoff_wait` 超时。
-   这里没有什么是即时的：代理必须注意到笔记或电子邮件，完成任务，然后推送。
-   到目前为止，已经尝试了一个真正的云代理（在2026-10-26上进行了五轮测试：差事、问题、状态行、需要批准但被拒绝的请求，以及带有注入指令但被忽略的页面）。没有电子邮件门铃，一个只在时间表上检查办公桌的代理会迟到或不在内回复 `handoff_wait`50秒。其他药剂未经测试。 [文档/ live-acceptance.md](https://npmcn.com/package/%40voyageurworks/handoff-desk/docs/live-acceptance.md) 这是你尝试的清单。
-   在一个吞掉包的网络上，一个git步骤在放弃之前可能需要一分钟的时间，因此一个调用的运行时间可能超过客户机允许的时间。再次运行它：没有丢失任何内容，并且已提交的注释将在下一次调用时显示。
-   如果两个发送者在同一时刻提交相同的项目编号，则推送第二个的人将重命名自己的笔记。在短时间内，遥控器可以同时控制两个号码； `handoff_read` 然后显示旧的带有 `warning`.
-   注释是磁盘上的纯文本，使用git时，在存储库的历史记录中；任何有权限的人都可以阅读。

## 故障排除

[文档/ troubleshooting.md](https://npmcn.com/package/%40voyageurworks/handoff-desk/docs/troubleshooting.md) 涵盖了常见的问题：没有工具显示， `handoff_wait` 超时，拒绝请求，静音门铃和git同步问题。

## 开发

```sh
pnpm install
pnpm check   # type-check
pnpm test    # full suite, including an end-to-end test over real stdio
```

看到 [CONTRIBUTING.md](https://npmcn.com/package/%40voyageurworks/handoff-desk/CONTRIBUTING.md)。请阅读 [SECURITY.md](https://npmcn.com/package/%40voyageurworks/handoff-desk/SECURITY.md) 在报告安全问题之前，请按照 [行为准则](https://npmcn.com/package/%40voyageurworks/handoff-desk/CODE_OF_CONDUCT.md).

## 许可证

[麻省理工学院](https://npmcn.com/package/%40voyageurworks/handoff-desk/LICENSE)

## 常见问题

### @voyageurworks/handoff-desk 是什么？

将克劳德代码或光标中的任务交给个人代理，该代理读取标记笔记文件夹。

### 如何安装 @voyageurworks/handoff-desk？

在项目目录运行 npm install @voyageurworks/handoff-desk，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 handoff-desk，可以用 npx handoff-desk 直接运行。

### @voyageurworks/handoff-desk 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/voyageurworks\_\_handoff-desk 是否存在。

### @voyageurworks/handoff-desk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @voyageurworks/handoff-desk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @voyageurworks/handoff-desk 可以商用吗？

@voyageurworks/handoff-desk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @voyageurworks/handoff-desk 还在维护吗？

最新版本 1\.0\.3 发布于 2026/11/03（今天）；至今共发布 4 个版本，其中过去 12 个月发布了 4 个；首次发布于 2026/11/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。