shepherd

像 Git 一样分叉回滚 Agent 运行，重放省 95% 算力

开源 🏷️定价信息待确认 ✅ 目前可打开智能体 🍴 复刻 219 🐛 待处理 13 👀 关注 9

访问官网 ↗ GitHub ↗

GitHub 星标 ★ 2503

维护状态维护中

是否开源开源

定价模式 🏷️定价信息待确认

项目预览

项目数据

分类智能体

开发团队shepherd-agents

官网地址https://shepherd-agents.ai

GitHubhttps://github.com/shepherd-agents/shepherd

定价模式🏷️定价信息待确认

价格说明定价信息待确认

访问状态✅ 目前可打开

是否开源是

开源协议MIT

主要语言Python

技术栈/模型mcts-rl,meta-agents,meta-optimization,runtime-supervision,tree-rl,workflow-automation

GitHub 星标★ 2503

上线时间2026-06-24 00:00:00

代码更新2026-09-09

仓库体积17.1 MB

本站数据更新2026-11-02

维护状态维护中

收录时间2026-09-14

浏览次数4

项目介绍

Shepherd 是一个面向智能体（Agent）的运行时底座，把每次执行过程记录成可逆的、类似 Git 的轨迹，让元智能体（meta-agent）能够观察、分叉、重放和回滚任意一次运行。它解决的核心问题是：当前 Agent 执行过程不可回溯、难以调试和优化，一旦出错只能从头再来，训练和调优成本极高。Shepherd 通过写时复制（copy-on-write）机制把 Agent 与环境耦合在一起进行分叉，速度比 docker commit 快约 5 倍，重放时 KV-cache 复用率约 95%，大幅降低重复计算开销。它专为元智能体设计，可用于监督、优化和训练其他 Agent，支持 MCTS-RL、树状 RL、工作流自动化等场景，让 Agent 的试错、分支探索和回滚变得像操作 Git 分支一样自然。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

数据来源：GitHub API 逐日快照 · 收录于 2026-09-14 · 当前星标 ★ 2503

技术标签

workflow-automation

使用教程

难度：入门约 10 分钟部署方式：命令行工具 8 步

环境要求

Python 3.11 或更高版本
macOS 或 Linux（Windows 不支持，需使用 WSL）
使用 agent 快速上手需安装并登录 claude CLI，或提供 ANTHROPIC_API_KEY
Linux 上的授权强制执行需要特权容器（Landlock）

安装与启动步骤

1安装 Shepherd

用 pip 从 PyPI 安装 shepherd-ai 包，建议装在虚拟环境中避免污染全局。
```
pip install shepherd-ai
```
2初始化工作区

新建一个临时目录并执行 shepherd init，把它变成一个 Shepherd 工作区。
```
mkdir /tmp/agent-task && cd /tmp/agent-task
shepherd init
```
3检查 claude 环境

确认 claude CLI、登录凭证和沙箱是否就绪；加 --probe 可做一次真实认证往返。
```
shepherd doctor claude
```
4生成示例任务

把官方 demo 的 agent 任务脚本写到当前目录的 agent_task.py 文件中。
```
shepherd demo write agent-task > agent_task.py
```
5运行 agent 任务

执行脚本，agent 会工作约一分钟；产物不会写入你的目录，而是成为保留输出。
```
python agent_task.py
```
6查看保留输出

不应用任何变更，直接读取最新 changeset 中的 donut.py 并交给 python3 执行。
```
shepherd run changeset --latest --read donut.py | python3 -
```
7查看完整记录

用 show 查看这次运行的完整记录，加 --json 可拿到机器可读的持久化数据。
```
shepherd run show --latest
```
8保留或丢弃结果

满意就用 select 保留、apply 合并，不满意用 discard 丢弃，轨迹都会记住。
```
shepherd run list
```

关键配置

配置项	必填	说明	示例
`ANTHROPIC_API_KEY`	否	使用 Claude agent 时提供的 API 密钥，与订阅登录二选一	`sk-xxxxxxxx`
`CLAUDE_CODE_OAUTH_TOKEN`	否	长期令牌，订阅账号在沙箱中运行更稳定	`export CLAUDE_CODE_OAUTH_TOKEN=$(claude setup-token)`

如何确认成功

执行 shepherd run list 能看到本次运行及其状态，shepherd run changeset --latest 能列出保留输出即可。

常见问题

Q：没有 API key 能跑起来吗？

A：可以。README 提供了离线快速上手，使用确定性的 provider，无需任何密钥即可走通保留输出流程。

Q：Windows 上可以安装吗？

A：不支持。授权强制执行仅在 macOS（Seatbelt）和 Linux（Landlock，特权容器）实现，Windows 上请改用 WSL。

Q：Claude 返回 HTTP 403 组织策略错误怎么办？

A：这是账号或组织层面的限制，不是登录问题。换一个密钥或联系组织管理员解决。

Q：claude CLI 直接卡住不返回？

A：例如版本过期会导致挂起，最终表现为 budget 超时而不是认证错误，请更新 claude CLI 版本。

Q：订阅登录在沙箱里失败怎么办？

A：短时有效的登录会话无法在沙箱内刷新，建议用 claude setup-token 生成长期令牌后再运行。

注意事项

Shepherd 处于 early alpha，API 可能随版本变化，请关注官方文档更新。
agent 的产物默认是 retained output，不会直接改动你的文件，需显式 select 或 apply 才生效。
自己开发 Shepherd 时改为本地可编辑安装：python -m venv .venv && . .venv/bin/activate && pip install -r requirements-dev.txt。
更多后端选择和完整 run 命令面见官方文档 https://docs.shepherd-agents.ai/。