Shepherd Monorepo架构深度剖析core、dialect、runtime等15个包如何分层协作【免费下载链接】shepherdA runtime substrate that turns an agents 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这个 AI Agent 运行时框架的 Monorepo 架构它如何把 core语义内核、dialect执行策略、runtime运行时等15 个包拆分成清晰的层次并通过单向依赖、导入边界测试和契约层实现各管一段、稳定协作。如果你关心多智能体meta-agent框架的代码组织方式这篇指南能让你 5 分钟内建立完整认知。先认识 Shepherd一个可回放的 Agent 底座Shepherd 的官方定位是一句话把 Agent 的执行变成一条可逆的、类 Git 的 trace让上层 meta-agent 可以观察、fork、回放replay和撤销revert任何一次运行。它与环境耦合的 copy-on-write fork 比docker commit快约 5 倍回放时能复用约 95% 的 KV-cache。围绕这个核心目标整个仓库按内核 → 运行时 → 策略 → 扩展的方式拆包这正是 Monorepo 价值所在。Monorepo 全景一个仓库三类资产仓库顶层就三大块入口文档见 README.md目录角色关键点shepherd/packages/12 个核心框架包分层架构主体本文重点shepherd/extras/领域电池包banking、coding、trace-viewer 等shepherd/integration-tests/跨包契约测试守护导入边界与分层规则仓库根部还有两个平级项目vcs-core/可执行世界的版本控制底座和 commons-vcs/内容寻址图记录内核是 Shepherd 的地基层稍后详述。分层协作15 个包各自负责什么 第 1 层内核 —— core语义中心core是语义内核官方描述是owns the concepts required to define the systems semantics, and nothing else见 core/README.md。它只管Effects 与流不可变的状态变更记录 追加式流append-only stream核心不变式state(t) fold(apply_effect, effects[0:t], initial_state)见 Core InvariantProvider 协议、ExecutionContext生命周期、ImmutableScope不可变作用域底座它只依赖pydantic是整个依赖金字塔的塔尖基础。第 2 层运行时 —— runtime可变外壳runtime承载真正的执行Scope、任务/步骤编排、设备device、检查点、生命周期管理。它的定位很微妙——不可变的内核底座之上是可变的外壳但内核永远不反向依赖运行时见 Scope Split。规模上也最大src/shepherd_runtime/下有 168 个 Python 文件测试 141 个。第 3 层策略 —— dialectrun 驱动器dialect是 v1.0 重新定向后的关键包职责一句话概括vcs-core 拥有机制可逆作用域、受限启动、合并时隐式捕获dialect 拥有策略与组合见 dialect/README.md。它实现了生产环境的ShepherdRunDriver负责run命令的词表、任务解析、provider 接缝以及may权限参数到ConfinementSpec沙箱约束的降级。导入纪律极严只允许vcs_core.runtime_api / spi / runtime_substrate禁止触碰私有模块——这是它测试数量最多50 个的原因。第 4 层能力扩展 —— providers / contexts / sandboxes三个包分别补齐用哪个模型挂什么状态在哪执行包职责亮点providers/LLM 适配器ClaudeProvider、OpenAIProvider可选依赖隔离contexts/有状态执行上下文Workspace、Session、MCP、数据库、KV 存储全部是不可变 dataclasssandboxes/远程沙箱封装Daytona、E2B、K8s、Modal 等SDK 延迟导入contexts值得单独一提所有上下文都实现 v2 事件溯源 APIextract_effectsapply_effect与 core 的 fold 不变式严格对齐见 v2 API。外围支撑包meta、export、transform、authoring、tests、kernel-v3剩下几个包是门面 工具链meta用户唯一需要认识的入口。import shepherd as sp就来自它公开workspace()、open()、task、RunOutput等首屏 API见 Public API Shapeexport轨迹trajectory导出/导入的稳定所有者路径transformCritiqueTask、OptimizeFromEffects等元任务与行为对齐工具见 transform/README.mdauthoring设计精化流水线状态标记为 please-ask贡献前需先讨论tests跨包共享的MockProvider、pytest fixture、VCR 回放工具kernel-v3v3 内核的参考解释器实验性质明确标注非生产 API依赖流向单向性如何保证分层不是画出来的是被测试钉住的导入边界测试integration-tests/ 里的test_import_boundaries.py、test_cross_package.py等会拦截任何下层 import 上层的越界就绪度表Readiness每个包标注 stable / active / please-ask明确哪些包可随意提 PR见 Readiness 表工作区依赖声明每个包的pyproject.toml用uvworkspace 声明内部依赖例如 runtime/pyproject.toml 只声明shepherd-core和kernel-v3-reference杜绝隐式耦合CODEOWNERS 路由评审按路径分配 reviewer见 CONTRIBUTING.md地基之下vcs-core 与 commons-vcsShepherd 的可逆 trace 能力并非自研而是方言组合dialect-composes底座vcs-core/可执行世界的版本控制——workspace 根目录内的状态全部可逆外部环境是 pass-throughcommons-vcs/内容寻址图记录内核负责对象身份、typed edges、ref CAS 更新不拥有产品语义shepherd2/下一代骨架kernel ABI v0、schemas、substrates是架构的前瞻区三者共同支撑 Shepherd 的两大卖点~5x 于 docker commit 的 CoW fork以及 ~95% KV-cache 回放复用率。上手路径从 meta 门面走 5 分钟python -m venv .venv pip install -r requirements-dev.txt sp init sp demo write quickstart quickstart_demo.py python quickstart_demo.py sp run show --latest sp run trace --latest --events跑完后用sp run trace看回放轨迹配合 trace-viewer 可视化你就能直观感受到 15 个包在一次 run 中的完整协作链路meta 接收调用 → runtime 驱动执行 → dialect 组装策略 → providers/contexts 提供能力 → vcs-core 落盘可逆 trace。小结Shepherd 的 Monorepo 架构值得借鉴的三点语义与执行分离——core 只定义不可变语义runtime 才碰可变状态边界即代码——导入边界测试 就绪度表 workspace 依赖声明分层不靠自觉门面唯一入口——用户只见meta内部 15 包可独立演进想深入某个包的实现从它自己的README.md和tests/目录入手是理解这个 Monorepo 最快的路径。【免费下载链接】shepherdA runtime substrate that turns an agents 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Shepherd Monorepo架构深度剖析：core、dialect、runtime等15+个包如何分层协作
Shepherd Monorepo架构深度剖析core、dialect、runtime等15个包如何分层协作【免费下载链接】shepherdA runtime substrate that turns an agents 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这个 AI Agent 运行时框架的 Monorepo 架构它如何把 core语义内核、dialect执行策略、runtime运行时等15 个包拆分成清晰的层次并通过单向依赖、导入边界测试和契约层实现各管一段、稳定协作。如果你关心多智能体meta-agent框架的代码组织方式这篇指南能让你 5 分钟内建立完整认知。先认识 Shepherd一个可回放的 Agent 底座Shepherd 的官方定位是一句话把 Agent 的执行变成一条可逆的、类 Git 的 trace让上层 meta-agent 可以观察、fork、回放replay和撤销revert任何一次运行。它与环境耦合的 copy-on-write fork 比docker commit快约 5 倍回放时能复用约 95% 的 KV-cache。围绕这个核心目标整个仓库按内核 → 运行时 → 策略 → 扩展的方式拆包这正是 Monorepo 价值所在。Monorepo 全景一个仓库三类资产仓库顶层就三大块入口文档见 README.md目录角色关键点shepherd/packages/12 个核心框架包分层架构主体本文重点shepherd/extras/领域电池包banking、coding、trace-viewer 等shepherd/integration-tests/跨包契约测试守护导入边界与分层规则仓库根部还有两个平级项目vcs-core/可执行世界的版本控制底座和 commons-vcs/内容寻址图记录内核是 Shepherd 的地基层稍后详述。分层协作15 个包各自负责什么 第 1 层内核 —— core语义中心core是语义内核官方描述是owns the concepts required to define the systems semantics, and nothing else见 core/README.md。它只管Effects 与流不可变的状态变更记录 追加式流append-only stream核心不变式state(t) fold(apply_effect, effects[0:t], initial_state)见 Core InvariantProvider 协议、ExecutionContext生命周期、ImmutableScope不可变作用域底座它只依赖pydantic是整个依赖金字塔的塔尖基础。第 2 层运行时 —— runtime可变外壳runtime承载真正的执行Scope、任务/步骤编排、设备device、检查点、生命周期管理。它的定位很微妙——不可变的内核底座之上是可变的外壳但内核永远不反向依赖运行时见 Scope Split。规模上也最大src/shepherd_runtime/下有 168 个 Python 文件测试 141 个。第 3 层策略 —— dialectrun 驱动器dialect是 v1.0 重新定向后的关键包职责一句话概括vcs-core 拥有机制可逆作用域、受限启动、合并时隐式捕获dialect 拥有策略与组合见 dialect/README.md。它实现了生产环境的ShepherdRunDriver负责run命令的词表、任务解析、provider 接缝以及may权限参数到ConfinementSpec沙箱约束的降级。导入纪律极严只允许vcs_core.runtime_api / spi / runtime_substrate禁止触碰私有模块——这是它测试数量最多50 个的原因。第 4 层能力扩展 —— providers / contexts / sandboxes三个包分别补齐用哪个模型挂什么状态在哪执行包职责亮点providers/LLM 适配器ClaudeProvider、OpenAIProvider可选依赖隔离contexts/有状态执行上下文Workspace、Session、MCP、数据库、KV 存储全部是不可变 dataclasssandboxes/远程沙箱封装Daytona、E2B、K8s、Modal 等SDK 延迟导入contexts值得单独一提所有上下文都实现 v2 事件溯源 APIextract_effectsapply_effect与 core 的 fold 不变式严格对齐见 v2 API。外围支撑包meta、export、transform、authoring、tests、kernel-v3剩下几个包是门面 工具链meta用户唯一需要认识的入口。import shepherd as sp就来自它公开workspace()、open()、task、RunOutput等首屏 API见 Public API Shapeexport轨迹trajectory导出/导入的稳定所有者路径transformCritiqueTask、OptimizeFromEffects等元任务与行为对齐工具见 transform/README.mdauthoring设计精化流水线状态标记为 please-ask贡献前需先讨论tests跨包共享的MockProvider、pytest fixture、VCR 回放工具kernel-v3v3 内核的参考解释器实验性质明确标注非生产 API依赖流向单向性如何保证分层不是画出来的是被测试钉住的导入边界测试integration-tests/ 里的test_import_boundaries.py、test_cross_package.py等会拦截任何下层 import 上层的越界就绪度表Readiness每个包标注 stable / active / please-ask明确哪些包可随意提 PR见 Readiness 表工作区依赖声明每个包的pyproject.toml用uvworkspace 声明内部依赖例如 runtime/pyproject.toml 只声明shepherd-core和kernel-v3-reference杜绝隐式耦合CODEOWNERS 路由评审按路径分配 reviewer见 CONTRIBUTING.md地基之下vcs-core 与 commons-vcsShepherd 的可逆 trace 能力并非自研而是方言组合dialect-composes底座vcs-core/可执行世界的版本控制——workspace 根目录内的状态全部可逆外部环境是 pass-throughcommons-vcs/内容寻址图记录内核负责对象身份、typed edges、ref CAS 更新不拥有产品语义shepherd2/下一代骨架kernel ABI v0、schemas、substrates是架构的前瞻区三者共同支撑 Shepherd 的两大卖点~5x 于 docker commit 的 CoW fork以及 ~95% KV-cache 回放复用率。上手路径从 meta 门面走 5 分钟python -m venv .venv pip install -r requirements-dev.txt sp init sp demo write quickstart quickstart_demo.py python quickstart_demo.py sp run show --latest sp run trace --latest --events跑完后用sp run trace看回放轨迹配合 trace-viewer 可视化你就能直观感受到 15 个包在一次 run 中的完整协作链路meta 接收调用 → runtime 驱动执行 → dialect 组装策略 → providers/contexts 提供能力 → vcs-core 落盘可逆 trace。小结Shepherd 的 Monorepo 架构值得借鉴的三点语义与执行分离——core 只定义不可变语义runtime 才碰可变状态边界即代码——导入边界测试 就绪度表 workspace 依赖声明分层不靠自觉门面唯一入口——用户只见meta内部 15 包可独立演进想深入某个包的实现从它自己的README.md和tests/目录入手是理解这个 Monorepo 最快的路径。【免费下载链接】shepherdA runtime substrate that turns an agents 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考