Patchwork OS

Patchwork OS

你遇到的不是自动化问题，而是决策问题。

每个 AI Agent 引发的可怕故事，结局都一样：有个操作无人停下来质疑。Patchwork OS 是 Agent 冲动与实际操作之间的一层——一个本地优先的运行时，让你的 AI 能在编辑器、GitHub、Slack、Gmail 和 45+ 项服务中自动化处理实际工作，同时任何会造成重大影响的操作都可以先停下来征求你的同意。

**适用对象：**已经让 Agent 操作实际系统的开发者和技术运维人员——例如会发布内容的代码仓库、重要的收件箱或生产服务；他们希望记录哪些操作获准执行，以及获准的原因。你需要会使用终端、安装 Node，并能熟练编辑 YAML。

三个理念，一个运行时：

• **行动前先询问。**每项操作都会根据影响范围分类——能否撤销？如果出错，会造成多大影响？可撤销的操作可以直接执行。高风险操作则会进入审批队列，并附上证据：具体会执行什么、触发原因，以及出错后会有什么后果。

• **信任靠表现赢得，绝不凭空假定。**Worker——承担特定任务的具名 Agent——一开始都受监督，并根据每种操作类型的过往表现逐步获得自主权。擅长提交问题 ≠ 获准推送代码。一次高风险操作失误的影响，可能超过一百次无关紧要的成功。你设定上限；数学规则绝不会替你提高上限。

• **每项决策都有记录。**执行了什么、为何获准，以及结果如何——这些信息都会持久保存，可通过 patchwork judgments、仪表板的 traces 页面和 patchwork gate explain 重放并解释。你批准某项操作后，之后还能知道自己的决定是否正确。

Agent 想要写入一个文件。启用安全门后，它会暂停，并向你准确展示将要执行的操作：

你批准后，调用便会继续执行，前后两部分都会留下记录：

状态：稳定版 1.2

版本 1.2.6，已发布到 npm，标签为 latest。决策层、配方、连接器和 IDE 桥接都已可用，并且每天都在实际使用。小版本之间的接口仍可能变化，部分功能也不如其他功能完善。如果要基于它构建，请锁定确切版本。

安全功能是否启用，取决于你的安装方式。 这比本 README 中的任何其他内容都重要：

• 全新安装： 在没有 ~/.patchwork/config.json 的机器上运行 patchwork-os init，会写入 profile: governed。从首次运行起，门控即已启用。
• 已有安装： 升级不会更改你的配置档案。现有配置保持不变；运行 patchwork profile governed 并重启桥接即可选择启用。
• 完全没有配置（未运行 init 就启动桥接）：使用 compat 配置档案，不启用任何门控。

运行 patchwork doctor，查看当前机器上实际启用了哪些强制措施。请以其输出为准，而非此表。

功能	governed（全新运行 init）	compat（已有配置或无配置）
审批队列	对自动触发（cron、webhook、文件监视、git-hook）和手动运行均在 high 级别启用	除非指定 --approval-gate high 或 all，否则关闭；启用后也仅适用于手动运行
不可逆写入	无论所属级别如何，均需请求审批	遵循级别阈值
Agent 步骤	受限：仅限只读工具，不允许网络或 shell	默认完全访问，除非某个步骤设置了 sandbox: true
配方插件（servers:）	仅加载列在 plugins.allow 中的插件	加载任何条目，并在进程内运行
未注册任何内容的工具	运行会停止	跳过该步骤
紧急停止开关（patchwork panic）	可用；状态无法读取时会拒绝操作	可用；状态无法读取时允许操作
Worker 自主性提升	对 Worker 拥有的配方启用（运行需要驱动程序，例如 --driver subprocess）	除非设置 PATCHWORK_FLAG_WORKER_AUTONOMY=1，否则关闭（同样需要驱动程序）
遥测	关闭	关闭；需明确选择启用（详情）

在 compat 下，刚启动的桥接是自动化运行时；启用门控后，它才会成为决策层。上文所有关于“先停止并征求你的同意”的描述，都指门控启用时的情况。

工作循环

trigger → recipe/worker → reversible?           → runs
                        → risky, gate on        → approval queue → your yes → receipt
                        → risky, gate off       → runs
                        → forbidden by policy   → refused (no approval unlocks it)

patchwork panic 会立即阻止所有正在运行的桥接调用任何写入级别的工具。读取仍可正常进行，正在进行的推理也不会被终止——它会阻止写入，而不是完全停止运行。

安装

npm install -g patchwork-os@beta
patchwork-os init

init 会搭建 ~/.patchwork，添加仅供本地使用的配方，并在 ~/.claude/settings.json 中注册 Patchwork 的 PreToolUse 钩子。之后请重启 Claude Code——它会在会话启动时读取钩子。

前置条件： Node 22.5+。macOS、Linux 和原生 Windows（不支持 WSL）。

开始前有两点需要注意：

• 请使用全局安装，不要使用 npx。 npx 不会保留二进制文件，因此指南中的下一条命令就会无法找到。
• npm 包中不包含 Web 仪表板。 它是一个需要单独构建的 Next.js 应用，因此随仓库一同发布：

  git clone https://github.com/Oolab-labs/patchwork-os && cd patchwork-os/dashboard
  npm install && npm run build && npm start   # http://localhost:3200
  

  以下所有操作都可以通过 CLI 完成，无需仪表板。仪表板让审批、追踪和连接器配置更加方便，而不只是勉强可用。

首次运行：零连接器

在将任何服务接入之前，先验证运行时可正常工作。daily-status 只会访问 git 和本地文件——无需账户，也不会访问网络：

patchwork recipe run daily-status

它会读取你从昨天起的提交以及 ~/.patchwork/planned.md，并将 Markdown 摘要写入 ~/.patchwork/inbox/daily-status-<date>.md。如果该文件存在，就说明安装正常。

实用的相关命令：patchwork recipe list、patchwork status；遇到异常时可运行 patchwork recipe doctor <name>。

晨间简报：互联工作流

patchwork-os init --with-connectors   # seeds the connector-backed recipes
patchwork connect gmail
patchwork connect google-calendar
patchwork connect github
patchwork connect linear
patchwork recipe run morning-brief

此配方会提取未读邮件、今天的日历安排、你在 GitHub 上待处理的 issues 和 PR、Linear issues，以及本地 git 活动，然后让模型将它们汇总成一份 Markdown 简报，保存到 ~/.patchwork/inbox/。其中的邮件步骤是分类——它会列出需要回复的内容，但不会撰写或发送回复。除了调用你连接的服务的 API 外，其他任何内容都不会离开你的设备。

按此配置，四个连接器缺一不可——没有任何步骤设有保护条件，因此缺少一个就会导致运行中止。删除不需要的步骤，或者从 daily-status 开始，一次添加一个数据源。

需要可用的模型驱动程序（使用 --driver subprocess，并确保 Claude CLI 位于 PATH 中；或者提供 API 密钥）。patchwork recipe preflight templates/recipes/morning-brief.yaml 会准确列出运行配方前所需的条件。

两种运行方式

作为自动化运行时——配方、工作器、连接器和决策层。需要 ~/.patchwork 和模型驱动程序；编辑器可选。

patchwork start        # bridge + Claude + dashboard

patchwork start 会在桥接程序旁启动 claude --ide，因此要求 Claude CLI 位于 PATH 中。如果不需要，可以使用 patchwork start --no-dashboard，也可以通过 patchwork --workspace . 单独运行桥接程序。

全局安装 npm 后没有可启动的 dashboard/，因此程序会记录一条仪表板警告，然后继续运行桥接程序和 Claude；传入 --no-dashboard 可隐藏此警告。从仓库克隆运行时，则会启动这三者。

作为独立 IDE 桥接程序——提供 180 个 MCP 工具，让 Claude Code 能够查看和操作编辑器：诊断、LSP 导航、带风险分析的重构、调试器、终端、git/GitHub、文件操作。不需要 ~/.patchwork，不需要配方，也不需要门控。

npm install -g patchwork-os
claude-ide-bridge install-extension     # VS Code / Cursor / Windsurf / Antigravity
claude-ide-bridge --workspace .
claude --ide                            # in another terminal

通过配套插件支持 JetBrains。Claude Desktop、Gemini CLI、Codex CLI、Grok Build 和 claude.ai 可通过 stdio 或 HTTP 连接。如果你只需要桥接程序，可以一直单独使用它；运行时是在此基础上提供的可选层。

claude --ide 找不到 IDE？设置 CLAUDE_CODE_IDE_SKIP_VALID_CHECK=true（init 会为你完成此设置）。

“本地优先”意味着什么，也不意味着什么

**在你的设备上：**运行时、每个配方和工作器、所有凭据和连接器令牌、审批队列，以及 ~/.patchwork/ 下的每条日志和决策回执。不会上传任何内容，也没有任何由 Patchwork 运营的服务器参与其中。

**必然通过网络传输：**对你指定的模型（Anthropic、OpenAI、Google、xAI）以及你授权的每个连接器（Gmail、GitHub、Slack……）发起的调用。提示词以及步骤提供给模型的任何上下文都会发送给该模型提供商。选择本地 Ollama 端点也能让推理留在你的设备上；连接器调用仍会离开设备，因为这就是连接器的工作方式。

仅在你选择启用时：匿名分析。

还需了解的其他边界：runCommand 仅执行允许列表中的命令，sendHttpRequest 会阻止访问私有和环回地址段，文件工具会拒绝通过符号链接逃逸出工作区。远程部署必须置于 TLS 和 OAuth 2.0 保护之下——请参阅 docs/remote-access.md。

内容概览

• 决策层 — 审批队列 · 按影响范围划分的操作类别 · Worker 信任度提升机制 · 紧急停止开关 · 决策记录

• 自动化 — YAML 配方 · cron／文件／git／测试／webhook 触发器 · 事件钩子 · 多模型（Claude、GPT、Gemini、Grok、Ollama）

• 连接器 — 45+ 个，所有写入操作均由你的策略管控：GitHub、Slack、Gmail、Calendar、Drive、Linear、Jira、Sentry、Notion、Stripe、PagerDuty、Datadog，……

• IDE 桥接 — 180 个 MCP 工具 · VS Code 系列扩展 · JetBrains 插件 · 插件热重载（在会话期间编写工具）

• 监督 — Web 仪表板 · 移动端推送审批（PWA）· CLI 中的暂停／判定 · 跨会话跟踪记忆

• 部署 — 你的笔记本电脑 · 使用 OAuth 2.0 的无头 VPS（指南）· 原生 Windows

配方采用纯 YAML：由一个触发器（cron、文件保存、git 提交、测试运行或任意 webhook——iPhone Shortcut、Stream Deck、Home Assistant）和多个步骤组成。像 dotfile 一样分享、从市场安装，或让仪表板根据一句话生成配方。

Worker 是带有身份和工作记录的配方。一个负责对失败 CI 进行分类的 Worker，起初只会提出建议（“这看起来像是真正的故障——要提交一个 issue 吗？”）。确认它提交的问题确实属实后，它就能在仅限该任务的范围内获得更大的自主权。它也可能在一天之内因表现不佳而被降级。你可以用一行 YAML 永久限制任何 Worker。

为什么不选 Zapier、MCP 服务或托管助手？坦诚说明各自的取舍：documents/comparison.md。

文档

文档索引 · 平台参考 · 配方与触发器 · Worker 自主权 · 插件编写 · 架构 · Windows · ADR

遥测

默认关闭；除非你主动选择加入，否则不会发送任何数据。若选择加入：仅发送汇总计数和延迟数据，绝不发送路径、提示词、文件内容、参数或来自 ~/.patchwork/ 的任何内容。详情 与 源代码。

贡献与支持

问题 · 讨论 · CONTRIBUTING.md

⭐ 如果这为你省去了一个配置文件，或避免了一次部署失败，点个星是我唯一能知道它确实帮上忙的方式。

MIT © Oolab Labs — 许可涵盖范围 · 名称与标志