WorkFlow Companion

WorkFlow Companion

本仓库是 WorkFlow Companion 的所在地：源代码（src/index.js，采用 MIT 许可），下载内容（供 Claude Desktop 使用的 WorkFlow.mcpb）可在发行页面获取，问题和功能请求可在Issues中提交。 软件包本身通过 npm 安装。在 Mac 上，请改用开源项目 workflow-agent-bridge。 Opticell 为 Claude 提供的所有免费工具：opticell-mcp。

让Windows 或 Linux 上的 Claude处理 WorkFlow 中的任务、笔记和项目：读取队列、在线程中回复、勾选清单、记录笔记、更新文档。它可用于 Claude Code、Claude Desktop 或任何 MCP 客户端。

免费。它需要 iPhone、iPad 或 Mac 上运行的 WorkFlow 5.2 或更高版本来实际执行操作。不需要 Mac：

Claude ──MCP──▶ companion ──▶ your private iCloud ──▶ WorkFlow on your iPhone, iPad or Mac
                                                  ◀── receipt + fresh snapshot

配套工具本身绝不会编辑你的 WorkFlow 数据。它会将命令放入你自己的 iCloud 私有数据库区域。WorkFlow 会通过与 App 相同的检查（只读试用版限制、电子邮件权限、Agent 的签名）来应用这些命令，并在命令历史记录中逐一列出。所有操作都不会经过 Opticell 的服务器。

**由哪台设备响应。**打开 WorkFlow 的 Mac 会在几秒内响应。iPhone 或 iPad 则会在 iOS 允许 WorkFlow 运行时响应：通常在几分钟内，有时要等到你下次打开 App；如果你在 App 切换器中向上划掉 WorkFlow，它就不会响应。两台设备都开启时，Mac 会在唤醒期间响应，iPhone 则待命。无论开启多少台设备，每条命令都只会应用一次。

安装

一行命令即可在需要时安装 Node.js、登录此电脑、将配套工具添加到 Claude Code，并询问是否允许它自行开始工作：

Windows（PowerShell）：

irm https://raw.githubusercontent.com/TeamDzX/workflow-companion/main/install.ps1 | iex

Mac 或 Linux（终端）：

curl -fsSL https://raw.githubusercontent.com/TeamDzX/workflow-companion/main/install.sh | sh

请先在 WorkFlow 中启用配套工具（见下方第 1 步）。如果你更愿意手动操作，后续步骤就是安装程序会执行的操作。

设置

1. 在 iPhone 或 iPad 上的 WorkFlow 中：设置 → Windows Companion → 回应 Companion。在 Mac 上：设置 → Agent Bridge，然后打开 Agent Bridge 和 Cloud Bridge 开关。

2. 如果运行 node -v 未显示版本号，请安装 Node.js 18 或更高版本（LTS）：Windows 上运行 winget install OpenJS.NodeJS.LTS -e，Mac 上运行 brew install node，Linux 上使用你的软件包管理器，或者从 https://nodejs.org 下载并安装。 然后关闭并重新打开终端（并重启 Claude Code），以便找到 node 和 npx；否则会看到“node 未被识别”。

3. 在普通终端窗口中：

   npx -y @opticell/workflow-companion@latest setup
   

   它会打开 https://companion.opticell-limited.com，让你使用 WorkFlow 在 iPhone 或 Mac 上所用的 Apple Account 登录，然后要求你粘贴该页面显示的令牌。它会询问问题，因此无法从 Claude Code 的 ! 提示符或其他非交互式 shell 中运行；在这些环境中，请传入 --web-token <token> 和 --name <name>。

4. 将其添加到 Claude：

   claude mcp add --scope user workflow -- npx -y @opticell/workflow-companion@latest
   

   在 Windows 上，npx 是一个脚本，因此 Claude Code 需要在前面加上 cmd /c：

   claude mcp add --scope user workflow -- cmd /c npx -y @opticell/workflow-companion@latest
   

   --scope user 会让它在此电脑的所有项目中都可用。

   Claude Desktop 无需使用终端。从产品页面下载 WorkFlow.mcpb 并双击。然后前往 https://companion.opticell-limited.com 登录，并将令牌粘贴到设置 → 扩展 → WorkFlow Companion → 登录令牌。

随时运行 npx -y @opticell/workflow-companion status 检查状态。

它的名称

设置时会询问你希望将这台电脑上的 Claude 在 WorkFlow 中称为什么（默认是 “Companion”，除非你自行选择，例如 --name Server）。工作会通过这个名称 发给它，而不是发给 Mac 自带的 Claude：

• 分配任务给它。Companion 发出回应后，WorkFlow 会提供这个名称，Ask 工作表也会让你选择它。
• 在评论或备注中写入 @Server。在共享项目的讨论串中提及它不算，因为其他人也能在那里发言。
• 它写下的内容会署上它的名称，这样讨论串中就能看出哪个 Claude 做了什么。
• 一个名称对应一台电脑。 如果另有电脑已使用该名称回应，设置程序会拒绝使用这个名称，并要求你另选一个。每条命令都会按相同方式检查，这也适用于名称由设置项指定的 Claude Desktop。若这台电脑要接替另一台电脑，请使用 setup --takeover。某台电脑连续两周没有回应后，其名称会自动释放。
• @Claude 始终指 Mac 上的 Claude。Companion 不能使用这个名称，而且提及只匹配完整单词，因此 @Claude2 永远不会唤醒 Mac。

Claude Desktop 用户可在扩展程序的设置中指定名称。

自主工作

开启唤醒功能后，只需在应用中发送 @Server 即可，无需有人守在这台电脑旁。 在此处安装并登录 Claude Code 后，开启该功能：

npx -y @opticell/workflow-companion wake-on

• 每 2 分钟，一个隐藏的计划任务（Windows 上使用任务计划程序，其他系统上使用 cron）会检查 iCloud 中此名称的队列。它只会进行一次轻量调用；仅当任务列表发生变化时才会下载列表。
• 有新工作时，会启动一个 Claude Code 会话（claude -p，不显示窗口）。它会读取任务，评论表示已接手（你的手机会显示“Server 正在处理”），完成工作并在讨论串中回复。
• 哪些内容算作新工作： 新分配给该名称的任务、某人新发送的 @Server 评论、某人在已分配任务中的跟进，或提及它的已编辑备注。它自己的回复不会唤醒它。
• 每项工作只处理一次。 同一时间只运行一个会话；已处理过的工作不会再次启动会话。如果会话完全无法启动（例如未登录 Claude、达到使用限额），会再重试两次，然后在讨论串中说明情况。
• 时限： 默认 45 分钟（--max-minutes）。会话因达到时限而停止时，会在讨论串中说明情况。
• 它可以执行的操作。 默认情况下，它只能使用 WorkFlow 工具（mcp__workflow）：读取任务并回复。若要允许它在这台电脑上运行命令，请传入 --allow-tools "mcp__workflow Bash Read"（遵循任意 Claude Code 权限规则）。任何能在你的 WorkFlow 中发送 @Server 的人都可能因此在此处运行命令，请谨慎决定。共享项目不会发送给它。
• Windows： 计划任务通常只会在用户登录时运行。若要在用户注销时也运行，请在任务计划程序中将任务“WorkFlow Companion wake”改为“无论用户是否登录都运行”。
• --workdir 用于设置会话的启动文件夹（否则使用你的主文件夹）；--model 用于指定 Claude 模型；若找不到 Claude Code，--claude 用于指定其路径。--skip-existing 会将队列中已有的内容视为已处理。
• 日志位于 ~/.workflow-companion/wake.log。wake-off 会停止所有相关进程。

保持更新

• Claude Code 会运行注册名称对应的内容。使用 @latest 注册（安装程序会打印确切命令），每个新会话都会使用 最新版本。
• 计划任务（保持活跃、唤醒）运行的是已保存的副本，npm 不会 修改它，因此它们会自行更新。最多每 6 小时，它们会读取 npm 上该软件包的 条目（registry.npmjs.org/@opticell/workflow-companion/latest）。 如果有更新，就会下载新版本，并使用 npm 的 sha512 校验和进行验证，同时检查 Node 能否解析该文件，然后替换现有版本。使用 auto-update off 关闭此功能，使用 update 手动更新。
• 会报告版本。 运行期间，每隔约 10 分钟，每个伴侣都会将其版本、 计算机和签到时间写入你的 iCloud。 WorkFlow 5.3.2 会在 Settings → Agent Bridge → Who's Bridged 中显示这些信息，而 status 会列出每个伴侣的版本。

命令

workflow-companion	运行 MCP 服务。这是 Claude 启动的命令。
workflow-companion setup	在此计算机上登录。可使用 --web-token 跳过提示。
workflow-companion status	哪台设备有响应、快照有多新，以及是否有延迟到达的回执。
workflow-companion doctor	检查此计算机上的所有内容，并说明如何修复问题。遇到问题时，从这里开始。
workflow-companion canary	立即运行每日自测。canary on|off、canary at HH:MM。
workflow-companion keepalive	续期登录状态。计划任务会运行此命令。
workflow-companion update	立即将计划任务的副本更新到最新版本，并说明如何让 Claude Code 使用 @latest。
workflow-companion auto-update on|off	是否让计划任务自动更新（默认开启）。
workflow-companion wake-on	当有发给其名称的工作到达时，自动启动 Claude Code 会话。参见上文。
workflow-companion wake-off	停止此功能。工作会一直等待，直到你在此处请求 Claude 处理。
workflow-companion wake	检查一次队列。计划任务会运行此命令。
workflow-companion monitor add|list|check|remove	在不使用 Claude 的情况下检查此计算机是否运行。参见下文。
workflow-companion approvals on|off	你回复“approve CODE”后，允许助手运行一条确切命令（默认关闭）。
workflow-companion inbox-on|inbox-off	放入文件夹的文件会变成任务。
workflow-companion notifications on|off	此计算机上的通知（默认开启）。notify-test 会显示一条通知。
workflow-companion reports on|off	每个会话结束后，在任务中附上一份简短报告（默认开启）。
workflow-companion signout	删除登录信息、缓存数据和两个计划任务。

在这台电脑上独立运行（1.8）

这些功能与唤醒功能在同一个每 2 分钟运行一次的计划任务中执行，不消耗 Claude 用量。

监控。 只有发生变化时才会唤醒 Claude：

workflow-companion monitor add --name site --http https://example.com --task "Server status" --wake
workflow-companion monitor add --name disk --disk C:\ --min-gb 20 --task "Server status"
workflow-companion monitor add --name api --port 10.0.0.5:443 --every 2
workflow-companion monitor add --name backup --file D:\backups\latest.zip --task "Backups"
workflow-companion monitor add --name nightly --command "check-backups.cmd" --task "Backups" --wake

发生变化（宕机、恢复、文件变更）时，会在任务中发布信息，在此处显示通知，并在使用 --wake 时启动相关会话。助手可以自行设置网站、端口、磁盘、进程和文件监控（workflow_monitor），但只有你可以添加命令监控，因为它每隔几分钟就会运行一条命令。

审批。 助手可以请求在这台电脑上运行一条指定命令（重启服务、安装更新）。它会在任务中发布该命令和一个代码；你可以用手机回复 approve K7Q2（或 decline K7Q2）。只有真人的回复才有效，其他助手的回复无效；共享项目中的任务不能发起请求；命令会在 24 小时内按显示内容原样运行一次。此功能默认关闭，需在这台电脑上运行 workflow-companion approvals on 才能启用。

收件箱文件夹。 运行 workflow-companion inbox-on 后，会创建 ~/WorkFlow Inbox（或使用 --folder 指定的文件夹）：将文件放入其中，文件就会成为附件并生成一个任务。名称与某个项目相同的子文件夹会将文件归入该项目。已归档的文件会移动到 Filed/<date>。使用 --assign 会将它们放入此助手的队列。

通知。 有新工作到达、监控发生变化、审批收到回复、会话需要处理，或 iCloud 登录已结束时，这台电脑会显示通知（并附上修复所需的命令）。

每日自检（1.9）。 启用唤醒后，每天一次（07:30，或使用 canary at HH:MM 设置时间），伴侣程序会验证整个链路仍正常运行：WorkFlow 能执行命令，Claude Code 能运行并写入内容，且变更能够返回。通过后会静默更新「⚙︎ daily self-test」任务；失败时会在该任务中发表评论，通知会发送到你的手机，并说明出错步骤及修复方法。运行 workflow-companion canary 可立即执行自检；运行 canary off 可将其关闭。

会话报告。 每次会话完成变更后，都会在其任务中附上一份简短报告：任务要求、所做的变更、运行过的已批准命令，以及会话结束时的最后发言。

值得了解

• 必须有人负责响应。 如果发送命令时无人响应，命令会在 iCloud 中等待，直到 WorkFlow 下次检查时才运行。工具会说明这一点，收据稍后会显示在 workflow_state 中。
• 读取内容来自快照。 WorkFlow 会在每次更改后几秒发布快照，因此写入后立即读取可能会稍有延迟。
• 文件经由你的 iCloud 传输（1.6）。 附加文件、将文档归档到项目中或添加新版本时，文件会上传到你自己的 iCloud；负责响应的 Mac 或 iPhone 上的 WorkFlow 5.3 或更高版本会附加文件，然后删除已上传的副本。每个文件最大 50 MB。旧版 WorkFlow 会忽略上传，并报告文件缺失。
• 文件也能传回来（2.2）。 workflow_download 会将文档文件保存到这台电脑（默认位置：主文件夹中的 Downloads/WorkFlow），检查其 SHA-256，并且绝不覆盖已有文件。负责响应的 Mac 或 iPhone 上需要运行 WorkFlow 5.6.1 或更高版本；文件会在 iCloud 中等待，直到被取回，最长不超过一小时。
• 每日助手（2.2）。 在 WorkFlow → Settings → Agent Bridge → Briefs, Check-ins & Approvals 中选择此伴侣工具后，wake 作业会撰写晨间简报，并在安静时段以外每隔几小时进行签到；只有在有新事项需要你处理时才会启动会话。需要 WorkFlow 5.6。
• 令牌就是密码。 ~/.workflow-companion/token.txt 可访问你在 iCloud 中的 WorkFlow 数据。Apple 每次请求都会替换令牌，伴侣工具会立即保存每个新令牌。同一台电脑上的多个 Claude 会话可以共用令牌：它们会轮流使用。不要将令牌复制到其他设备。每台电脑都应运行自己的 setup。
• 保持连接。 Apple 会在 9 至 14 小时不等的空闲时间后结束登录会话。Claude 运行伴侣工具期间，它每两小时会续期一次。Setup 还会安排每三小时运行一次 workflow-companion keepalive：在 Windows 上使用任务计划程序（运行时不会显示控制台窗口），其他系统则使用 cron。signout 会移除此计划；--no-schedule 会跳过计划。
• “请重新登录” 表示 Apple 已结束会话（HTTP 401/421），例如电脑长时间关机后。请重新运行 setup。

工具

共有 18 个工具（2.0 将先前的 37 个工具合并；调用时旧名称仍然有效）：

工具	功能
workflow_queue	你的收件箱，按用户的家规整理
workflow_list	任务、笔记、项目、文档或近期评论，支持搜索
workflow_get	获取一项任务、一条笔记或一份文档的完整内容
workflow_create_task	创建任务，包括标签、子任务和开篇评论
workflow_update_task	一次调用即可更新字段、置顶状态行和检查清单
workflow_comment	回复任务，或将任务交给另一位助手或人员
workflow_note	创建、回复或转换记事本笔记
workflow_create_project	创建或更新项目
workflow_attach	将文件附加到任务、放入项目，或作为新的文档版本添加
workflow_update_document	更新文档的资料或文件夹
workflow_draft_email	创建由用户审核并发送的草稿
workflow_watch	稍后唤醒你，提醒你处理某项任务
workflow_monitor	监控网站、端口、磁盘、进程或文件，并在发生变化时唤醒你
workflow_approval	请求、检查并运行已批准的命令
workflow_state	检查桥接是否正常；使用 check: ping 或 doctor
workflow_propose	提议一项更改，供用户应用或拒绝（WorkFlow 5.6）
workflow_brief	为每日助手生成晨间简报（WorkFlow 5.6）
workflow_download	将文档文件保存到这台电脑（WorkFlow 5.6.1）

© Opticell Limited · https://www.opticell-limited.com/companion

源码与许可证

src/index.js 是整个服务端：单个文件，要求 Node 18 或更高版本，无依赖。它采用 MIT 许可证（见 LICENSE）。发布到 npm 的软件包包含同一文件，并在构建时填入 WorkFlow 的 CloudKit API 令牌（该令牌不是秘密：它只允许已登录用户访问自己的数据）。从源码运行时，setup 会通过 --api-token 提示输入令牌。

Dockerfile 通过标准输入输出运行服务端。MCP 目录使用它来检查服务端是否能启动并列出工具；无需登录即可完成这些检查。