Stitch 2.0 是一个本地优先的 CLI。它读取你仓库里已经存在的 CI 配置，在你的机器上跑同样的 job，并把任何失败交给 AI 智能体（Claude Code 或 Codex）去修。本文是文档的五分钟版本。
前置条件
- 一个带
.gitlab-ci.yml或.github/workflows/*.yml文件的仓库。Stitch 会读取你现有的任何流水线。 - Node 20 或更新版本（或者 Bun，如果你用的是它）。
- 在你的机器上已经安装并认证过 Claude Code 或 Codex。如果你日常在用它们中任一个，这条就已经满足。
就这些依赖。Stitch 不需要 API key，不需要 Docker 镜像，也不需要平台 token。它以你自己的身份运行，在你的机器上，使用已经登录的智能体。
安装并运行
没有安装步骤。包发布在 npm 上，直接跑：
npx stitch-agent run claude或者，如果你更喜欢 Codex：
npx stitch-agent run codex第一次运行时，Stitch 会检测你用的是哪种 CI 配置，解析它，并向你展示它即将运行的 job。基础设施类 job（deploy、publish、release、image push）会被自动过滤掉。Verify 类 job（lint、typecheck、test、build）是会在本地运行的那些。
终端会切换进一个交互式 TUI。你会看到：
- 顶部一个流水线阶段条，依次经过 parse、execute、fix 三个阶段。
- 中间一个 job 表格，每个 job 的状态实时更新。
- 侧边一个 driver 面板，显示修复进行中时智能体在做什么。
你可以盯着看，也可以走开。Stitch 会在下面任一条件时停下来：第一次整条流水线全绿、到达尝试上限（每个 job 默认三次）、或遇到第一件它决定上报给你的事情。
job 失败时会发生什么
Stitch 用一段简短的 prompt 和相关上下文把失败的 job 交给你的智能体。智能体干它该干的：读取错误里涉及的文件，尝试修复，告诉 Stitch 重跑这个 job。Stitch 会真的重跑同一个 job 来验证。如果重跑通过，这次尝试算作一次修复。如果失败，智能体会再试，直到每个 job 的上限。
这个循环是故意有界的。如果三次尝试都没成，Stitch 会停下并给你看当前状态：最后一次诊断、最后一个补丁、最后一份日志。你带着完整上下文接手。
commit 和 push
当修复循环以所有 job 全绿结束时，Stitch 可以把结果 commit 并 push。这只在两个条件都满足时才发生：
- Stitch 启动时你在一个干净分支上。如果有未提交的改动，Stitch 不会动你的工作树。你正在进行中的工作永远不会被碰。
- 你要求过自动 commit。默认关闭。开关是
--auto-commit。
这是刻意保守的。让你对 Stitch 这类工具失去信任的最快办法，就是让它覆盖你的本地工作。我们宁可你主动开启，也不愿你事后困惑到底发生了什么。
监听模式
对于紧凑的迭代循环，Stitch 可以一直运行着，在文件变化时重新校验：
npx stitch-agent run claude --watch在监听模式下，保存文件会触发受影响 job 的重跑。你编辑、保存，几秒内就能在 TUI 里看到绿或红，不用离开编辑器。这会把 “push 一下看看 CI 开不开心” 的习惯换成 “保存一下看看”。
如果你想配置
零配置是默认选择，对大多数仓库都管用。如果你想微调行为，在仓库根目录丢一个 .stitch.yml：
max_attempts: 3
auto_fix: [lint, format, simple_types, config_ci]
escalate: [logic_errors, breaking_changes, dependency_conflicts]你不需要这个文件也能用 Stitch。它是为想要显式策略的团队准备的。
Stitch 不是什么
Stitch 不替代你的 CI。远程流水线在 push 时照样会跑。Stitch 只是给你一个更快、本地、由 AI 协助的同样过程，让你在 push 时带着把握而不是侥幸。
Stitch 不拿你的代码做训练。它不上报任何东西。没有遥测可关，因为本来就没有任何地方在上报。日志和修复都留在本地，除非你显式配置了通知渠道。
Stitch 自己不需要订阅。循环里唯一付费的服务是智能体（Claude Code 或 Codex），这笔账记在你本来就有的账户上。
接下来去哪
仓库在 GitHub 的 x24labs/stitch。issues 在那边跟踪。npm 包名是 stitch-agent。其他都在代码里，也在这个系列前几篇文章里，它们解释了 v2 为什么长成现在这样。
如果你试了之后有什么坏了，开个 issue。本地优先的意义之一就是复现问题需要的一切都已经摆在你面前。