将一次性 Agent 任务转化为可复用的工作流

要让 AI Agent 的多步骤任务可复用，可以将其步骤保存为仓库中的类型化模型定义和声明式工作流文件。这样，下一个会话直接运行已保存的流程，而无需根据提示词重新构建。

你可能遇到过这种情况：Agent 完成了一次干净利落的发布检查（测试、构建、冒烟测试，顺序完全正确），随后会话关闭，这套流程也随之消失。第二天你再描述一遍，得到的却是一个略有不同的版本。

本文介绍如何借助 Swamp 保留这套流程，内容包括：哪些部分可以复用、哪些不能；一个小型的发布检查工作流；以及同一工作流如何在 Claude Code、Cursor、OpenCode 或 Codex 下运行。

为什么一次出色的 Agent 运行会凭空消失

Agent 会话只在对话上下文中保存其工作流程，因此会话结束，流程也随之结束。它执行过的命令、选定的顺序、额外添加的检查，都没有保存在下一个会话能够运行的地方。你手里剩下的只有一份聊天记录，以及碰巧被修改过的文件。

解决办法是把 Agent 的流程转化为仓库中可被执行的文件。一旦这些步骤存放在仓库中，你就不必在每个会话里重新解释任务，Agent 的时间也能花在实际改动上，而不是重新搭建流程。

使用 Swamp 构建可复用的 AI Agent 工作流：哪些会保留，哪些不会

Swamp 是一款命令行工具，它将 Agent 的可用自动化以类型化模型、YAML 定义、工作流、版本化数据和 vault 引用的形式，存储在 Git 仓库内的 .swamp/ 目录中。Swamp README 列出了六个核心概念：模型（models），以类型描述外部系统；定义（definitions），即用于配置某个模型类型一次具体使用的 YAML 文件；工作流（workflows）；数据（data）；vault；以及标签（tags）。

Swamp 让流程可重复，而非让推理可重复。Agent 的步骤一旦保存为模型定义和工作流文件，后续运行就会执行这些已保存的步骤。不过，当 Agent 创建或编辑它们时，其输出在不同会话之间仍可能有所不同。

Swamp 与 MCP 的职责不同。正如MCP 生态系统开发者指南所述，MCP 负责将 Agent 连接到工具；Swamp 则负责存储并运行 Agent 借助这些工具构建的自动化，两者可以搭配使用。Swamp 在你自己的机器上运行，它使用的所有凭据都来自启动它的 shell 环境。

为你的 Harness 配置 Swamp

使用官方脚本安装二进制文件，然后为你的 harness 初始化仓库。官方安装脚本支持 macOS 和 Linux，同时也发布了 Windows 版本的二进制文件。

curl -fsSL https://swamp-club.com/install.sh | sh

swamp repo init                    # Claude Code (default)
swamp repo init --tool cursor      # or: opencode, codex

Claude Code 从 .claude/skills/ 读取 Swamp 的 skills，从 CLAUDE.md 读取指令。Cursor 使用 .cursor/skills/ 和 .cursor/rules/swamp.mdc。OpenCode 和 Codex 都使用 .agents/skills/ 和 AGENTS.md。

Swamp 将 skills 内置在二进制文件中，并在执行 init 时写出，因此 Agent 无需额外配置即可找到它们。可通过 swamp completions <shell> 获取 shell 自动补全。

端到端实现一个发布检查工作流

Swamp 工作流是一个以 DAG 形式编排 Job 的 YAML 文件，每个 Step 都会调用某个模型定义上的方法。正如 How Swamp Works 所述，每个 Job 会等待其依赖的 Job 完成，同一 Job 中的 Step 并行运行，除非某个 Step 依赖于另一个。

通常，你会让 Agent 创建 run-tests、build-artifact 和 smoke-test 这几个定义。即便如此，也请务必阅读生成的工作流，因为这正是你要批准的文件。下面的结构遵循工作流参考文档。其中的 <method> 占位符是有意保留的：请替换为你的定义实际暴露的方法名。

id: <keep the generated id>
name: release-check
tags:
  purpose: release
jobs:
  - name: checks
    description: Run tests and build in parallel
    steps:
      - name: tests
        task:
          type: model_method
          modelIdOrName: run-tests
          methodName: <method>
      - name: build
        task:
          type: model_method
          modelIdOrName: build-artifact
          methodName: <method>
  - name: smoke
    dependsOn:
      - job: checks
        condition:
          type: succeeded
    steps:
      - name: smoke
        task:
          type: model_method
          modelIdOrName: smoke-test
          methodName: <method>
version: 1

在这个发布检查工作流中，测试和构建同时运行。condition.type: succeeded 会让 smoke Job 一直等待，直到两者都通过。先用 swamp workflow validate release-check 校验文件，然后运行：

swamp workflow run release-check
swamp workflow run release-check --tag env=staging
swamp data query 'attributes.ok == false'   # example query from the Swamp manual

swamp workflow run 会一直等待，直到运行结束（成功、失败或取消），或在 manual_approval 关卡处暂停。运行成功时退出码为 0，其他情况均为非零，因此 CI 可以据此设置门禁。--tag 参数可在运行时覆盖标签。每次运行都会将输出保存为事后不可更改的版本化数据，并可按标签重新检索，这样后续会话就能直接读取发生过的情况，而不必从聊天记录中拼凑还原。上面的 data query 表达式来自 How Swamp Works 中的示例，需要根据你的模型字段进行调整。

smoke 步骤通过，只能证明端点有响应，并不能证明页面已正确渲染，也不能证明用户能够完成某个流程。在预发布构建上回放用户会话，才能让这类前端回归问题显现出来。

在不同 Harness 之间迁移同一工作流

当团队在不同 harness 之间迁移 Swamp 工作流时，共享的是模型、定义和工作流文件。每个 harness 的 skills 目录都被 gitignore，并由 Swamp 自行写出；开发者可以使用 swamp repo upgrade --tool <name> 切换 harness，或同时运行多个 harness。README 中提到，每个工具都有各自的 skills 文件夹，且不纳入 Git。

假设仓库最初为 Claude Code 初始化，而一位同事使用的是 Cursor。Agent harness 变了，但工作流文件保持不变：

# same checkout, teammate on Cursor
swamp repo upgrade --tool cursor
swamp workflow run release-check

swamp workflow run 不依赖于调用它的是哪个 Agent。Agent 负责的是编写和编辑定义，这部分才会随 harness 而变化。OpenCode 和 Codex 共用 .agents/skills/ 和 AGENTS.md，因此两个工具读取的是同一个 skills 位置。

默认情况下，Swamp 将模型数据、工作流运行记录、输出和审计日志等运行数据保存在 .swamp/ 中。需要在多台机器间共享同一状态的团队，可以切换到其他数据存储后端，例如共享文件系统路径或 S3。代码检出也可以随你迁移：在为 agentic coding 配置的远程主机上，只要该 shell 拥有模型所需的凭据，同样的工作流就能运行。使用 --repo-dir 或 SWAMP_REPO_DIR 可将 Swamp 指向当前目录之外的仓库。

Swamp 的成熟度与局限

Swamp 仍是早期工具。它在 swamp-club 仓库中积极维护，并以日期为版本号持续发布。请做好应对变化的准备。

• 不接受外部贡献。 只有 Elder Swamp Club 的员工为 Swamp 编写代码。来自 fork 的 Pull Request 会被自动关闭，因此 bug 和功能建议需通过 swamp issue bug 或 swamp issue feature 提交，由维护者实现他们采纳的部分。
• 遥测。 除非手动禁用，Swamp 会收集使用遥测数据。你可以用 --no-telemetry 针对单条命令关闭；用 SWAMP_NO_TELEMETRY=1 针对某个 shell 关闭；在 .swamp.yaml 中设置 telemetryDisabled: true 针对某个仓库关闭；或使用 swamp config set telemetry.collection disabled 针对本机所有运行关闭，该命令会将设置写入 ~/.config/swamp/telemetry.yaml。
• 适用范围。 一行脚本或一个 cron 任务用不着模型、DAG 和版本化数据。当任务跨越多个系统、需要保留历史记录或由团队共享时，Swamp 才能体现出价值。
• 扩展会执行代码。 在信任第三方扩展之前，请先进行审查。
• 许可证。 AGPL-3.0，附带 Swamp Extension and Definition Exception。

确定性的运行器会像忠实地重复好的工作流一样，忠实地重复糟糕的工作流。断言和人工审查依然必不可少。

结语

Swamp 保留的是流程，而不是 Agent 的思考。已保存的定义和工作流让你每次运行都获得相同的步骤和相同的关卡，而 Agent 在编写或修改它们时依然保持自由（也依然存在差异）。一个不错的下一步是：挑选一个你的 Agent 已经做得很好的流程，例如发布检查或代码审查，让它将该流程保存为 Swamp 工作流。审查 YAML、提交，再从另一个 harness 运行一次，确认它在那里同样可用。

常见问题

如何在 GitHub Actions CI 中运行 Swamp 工作流？

使用官方 GitHub Action swamp-club/setup-swamp。它会通过官方安装脚本安装 Swamp，如果传入 api-key 输入，还可以登录 swamp.club。将 repo-init 设为 true，即可在安装后执行 swamp repo init。随后的步骤中调用 swamp workflow run 并传入工作流名称。如果运行失败，该命令会以非零码退出，Job 随之失败。该 Action 目前仍处于早期的 v0.1 版本。

Swamp 工作流的密钥应该存放在哪里？

将它们放入 Swamp vault，并在定义和工作流中按名称引用。Swamp 会在 Step 运行的那一刻获取真实值。这样密钥就不会出现在 YAML 文件和 .swamp 数据中，也不会为下一次运行保留任何内容。内置的本地加密 provider 无需额外配置。其他 vault provider 则将密钥存放在外部服务中，例如 AWS Secrets Manager、Azure Key Vault 或 1Password。

运行 Swamp 工作流需要 AI Agent 吗？

不需要。swamp workflow run 是一条普通的 CLI 命令，因此开发者、CI Job 或脚本都可以在没有任何 Agent 的情况下运行已保存的工作流。只有在创建或编辑模型、定义和工作流时才需要 Agent。对于无需手动启动的运行，swamp serve 可以通过 cron 触发器运行工作流，也可以在收到来自 GitHub、Jira、Linear、Stripe、Slack 或通用端点的签名 webhook 时运行工作流。

Swamp 可以安装在 Windows 上吗？

可以。swamp-club/swamp 的 GitHub releases 页面除了提供 macOS 和 Linux 版本外，还包含一个 swamp-windows-x86_64.zip 压缩包，其中有 swamp.exe。curl 一行命令会将安装脚本通过管道传给 sh，因此无法在 Windows 上使用。Windows 用户需下载发布压缩包，解压出 swamp.exe，并将其放到 PATH 中的某个目录下。