Shepherd快速开始教程：从pip install到跑通第一个Agent任务，5分钟上手指南

Shepherd快速开始教程：从pip install到跑通第一个Agent任务，5分钟上手指南

【免费下载链接】shepherdA runtime substrate that turns an agent's execution into a reversible, Git-like trace, so meta-agents can observe, fork, replay, and revert any run. Couples agent and environments in a copy-on-write fork ~5x faster than docker commit, with ~95% KV-cache reuse on replay. Framework built for meta-agents to supervise, optimize, and train other agents项目地址: https://gitcode.com/gh_mirrors/shepherd16/shepherd

Shepherd 快速开始只需三步：pip install shepherd-ai、初始化工作区、跑通第一个Agent 任务。Shepherd 是一个"可逆执行底座"（runtime substrate），它把每一次 Agent 运行记录成 Git 风格的持久执行轨迹（trace），让元 Agent 可以观察、分叉、重放、回滚任何一次运行——而且 Agent 的产物会先以"保留输出"（retained output）形式安全暂存，在你确认之前绝不碰你的文件。

本教程带你从零完成 Shepherd 安装与首次运行，全程约 5 分钟。

1️⃣ 环境要求与安装命令

先确认环境，一条命令完成安装：

pip install shepherd-ai

💡 安装的是发行包shepherd-ai，导入时写import shepherd as sp，两者名字不同是正常现象。安装细节参见官方文档 docs/shepherd/start/install.md。

2️⃣ 一键初始化工作区

Shepherd 必须在初始化过的工作区内运行，一条命令搞定：

mkdir shepherd-demo && cd shepherd-demo shepherd init

shepherd init会把当前目录变成一个 Shepherd 工作区。之后所有任务运行、产物审查、回滚都发生在这个"受管边界"里。

3️⃣ 跑通第一个 Agent 任务（免 Key 离线版）

这是最快的上手路径：无需 API Key、确定性、可重复。仓库自带一份可对照的示例脚本 examples/quickstart/offline_task.py，核心写法只有几行：

import shepherd as sp @sp.task def draft_release_note(component: str, change: str) -> str: """Return a deterministic release-note line.""" return f"{component}: {change}"

注意这个任务的精髓：函数签名即契约。@sp.task声明任务，参数类型是输入，返回类型是输出契约，docstring 就是给模型的指令——你甚至不用手写 prompt。

在已初始化的工作区中运行一个任务，产物会以"保留输出"形式暂存，等待你审查：

shepherd demo write quickstart > quickstart_demo.py python quickstart_demo.py

运行结束后，用 CLI 查看结果：

shepherd run list # 查看运行记录与状态 shepherd run changeset --latest # 查看这次运行"写"了什么 shepherd run show --latest # 查看完整持久化记录

4️⃣ 进阶：让真 Agent 干活（Live 版）

想要真正的 Claude Agent 来写代码？只需满足一个前提：本机装有并登录了claudeCLI（或用ANTHROPIC_API_KEY）。

shepherd doctor claude # 检查 claude CLI、登录状态、沙箱是否就绪

然后把 examples/quickstart/agent_task.py 里的PROMPT改成任何你想要的任务，运行python agent_task.py。Agent 在沙箱隔离中工作，产物依旧落为保留输出，例如：

# 直接从保留输出中运行 Agent 写的程序（无需先落盘） shepherd run changeset --latest --read donut.py | python3 -

5️⃣ 关键机制：先审查、后落盘（3 条命令定去留）

Shepherd 最独特的设计是：Agent 的任何改动都不直接写入你的文件，而是作为一份"提案"保留在旁边，你可以先运行、先审查，最后用一条命令定去留：

shepherd run select <run-ref> # ✅ 保留：合并到你的工作区 shepherd run apply <run-ref> # 🔀 三方合并到已前进的工作区 shepherd run discard <run-ref> # 🗑 丢弃：轨迹中仍有完整记录

权限方面，签名即权限面：repo: sp.GitRepo表示授予该仓库可写句柄；若任务只需检查不改文件，用May[GitRepo, ReadOnly]声明只读——写入会在操作系统层面（macOS Seatbelt / Linux Landlock）直接拒绝。详见 README.md 的 Permissions 一节。

6️⃣ 遇到问题时查这里

7️⃣ 下一步：从 5 分钟到进阶玩法

• 📖 官方入门文档：docs/shepherd/start/index.md（含完整可复现的 quickstart 转录）
• 🧪 概念模型（任务、效果、权限、轨迹）：docs/shepherd/concepts/index.md
• 🧰 更多上手示例：examples/quickstart/（离线任务、Live Agent、world channel 等）
• 🎨 可视化用例 Notebook（变体工作室、模型选型、管线恢复）：examples/notebooks/visual_artifact/，make notebooks一键启动

从一条pip install到可审查、可回滚的 Agent 运行轨迹——这就是 Shepherd 给你的 5 分钟上手体验。现在，去初始化你的第一个工作区吧 🚀

【免费下载链接】shepherdA runtime substrate that turns an agent's execution into a reversible, Git-like trace, so meta-agents can observe, fork, replay, and revert any run. Couples agent and environments in a copy-on-write fork ~5x faster than docker commit, with ~95% KV-cache reuse on replay. Framework built for meta-agents to supervise, optimize, and train other agents项目地址: https://gitcode.com/gh_mirrors/shepherd16/shepherd