Shepherd

当前的 AI Agent 往往像一个黑盒：你发出指令，它执行操作，如果结果出错，你可能甚至不知道它改了什么文件，更难以撤销。

Shepherd作为一个处于早期 Alpha 阶段的运行时基础层，它引入了可逆执行轨迹（Reversible Execution Traces）的概念。它将智能体的每一次运行记录为持久、可检查的轨迹，并将所有输出作为“保留提案”保存，直到用户明确审查、应用或丢弃。

核心理念：审查优先，安全默认

1. 提案式工作流

• 非破坏性执行：智能体在沙盒环境中工作，其生成的代码或文件修改不会直接写入你的项目目录，而是作为“保留输出”安全存储。
• 人工把关：用户可以通过 shepherd run changeset 预览更改，确认无误后使用 apply 合并，或使用 discard 丢弃。
• 完整审计：无论接受与否，所有操作轨迹都被记录，确保过程可追溯。

2. 契约式权限管理

• 显式授权：任务被定义为 Python 函数，其签名和文档字符串构成了智能体履行的“契约”。例如，repo: sp.GitRepo 明确授予智能体写入代码库的权限。
• 最小权限原则：智能体仅在授权范围内使用资源，防止越权操作。

3. 可逆性与监督

• 执行轨迹：每一步操作都被记录，支持事后检查和回放。
• 元智能体监督：这种架构允许更高级别的“元智能体”或人类监督员介入，审查低级智能体的行为，确保合规性与准确性。

快速开始：两种模式

模式一：在线智能体模式（需 Claude API）

1. 初始化工作区：

   mkdir /tmp/agent-task && cd /tmp/agent-task
   shepherd init             # 初始化 Shepherd 工作区
   shepherd doctor claude    # 检查 Claude CLI 或 API Key 配置
   

2. 运行演示任务：

   shepherd demo write agent-task > agent_task.py
   python agent_task.py      # 智能体执行任务，生成 donut.py 但不直接写入
   

3. 审查与应用：

   # 预览生成的代码（旋转的 ASCII 甜甜圈）
   shepherd run changeset --latest --read donut.py | python3 -
   
   # 决定去留
   shepherd run select <run-ref>     # 保留
   shepherd run apply  <run-ref>     # 合并到工作区
   shepherd run discard <run-ref>    # 丢弃
   

模式二：离线快速开始（无需 API Key）

如果你没有 API Key，或者想测试核心机制，可以使用确定性提供者模式：

mkdir /tmp/shepherd-quickstart && cd /tmp/shepherd-quickstart

shepherd init                                  # 初始化
shepherd demo write quickstart > quickstart_demo.py
python quickstart_demo.py                      # 运行离线演示

shepherd run list                              # 查看运行列表
shepherd run changeset --latest                # 查看保留的输出
shepherd run show --latest                     # 查看完整执行轨迹

技术细节与限制

• 平台支持：需要 Python 3.11+。支持 macOS 和 Linux（通过操作系统级权限强制执行）。Windows 用户需使用 WSL。
• API 稳定性：目前处于 Alpha 阶段，API 可能在版本间发生破坏性变更。
• 依赖：在线模式需安装 claude CLI 或配置 ANTHROPIC_API_KEY。