Shepherd的文档防火墙与路线图如何保证文档里写的每个功能都真的能跑【免费下载链接】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/shepherdShepherd 是一个面向 Meta-Agent监督、优化其他 AI 代理的元代理的运行时底座它把 Agent 的每次执行变成可回放、可分叉、可回滚的 Git 式追踪trace。围绕这个项目官方还搭了一道少见的文档防火墙Docs Firewall每一篇文档页要么由真实代码生成要么经过 pytest 实跑验证任何文档里写了但代码里没有的内容都会被构建门禁直接拦截。配合清晰的版本路线图读者永远能分清现在就能跑和还在路上。什么是文档防火墙两套流水线生产所有页面Shepherd 的文档不是写完就发的而是像构建软件一样构建出来的。整个体系由两条流水线覆盖全部 35 个页面流水线产出页面质量如何保证Reference 流水线reference/api/下的 18 个 API 页 CLI 参考页直接由真实代码的 docstring 静态生成代码变了页面必须同步重新生成否则构建失败Authored 流水线首页、Quickstart、教程、概念、指南等 16 个人工撰写页每个页面经历草稿 → 事实核查 → 可读性 → 代码实测 → 人工签发共 5 个阶段A1–A5更关键的是默认拒绝default-deny的会员门禁一个页面想出现在公开站点上必须同时满足元数据齐全 已列入导航 被排除规则放行这三元组任何一项对不上check_shepherd_docs.py 就报违规退出。换句话说没有验证过的页面根本生不到公网去。文档示例的产物长这样文档承诺的行为就是你能亲眼跑出来的行为。完整的流水线设计说明见 pipelines.md。三道防线让文档里的例子成为真例子防线一文档里的代码就是被 pytest 跑过的代码以 Quickstart 为例页面里嵌入的示例代码实际存放在 docs/_src/shepherd/quickstart/hello.py而 test_hello.py 会按文档描述的方式完整执行一遍并断言打印输出符合预期——what you read is what ran你读到的就是你跑过的。防线二源码快照漂移检查API 参考页生成时会产出一份公共符号快照 public-symbols.json。只要代码的符号、签名或 docstring 变了而文档没重新生成gen_shepherd_api_inventory.py --check就会因漂移判定失败——代码和文档必须同一次提交里保持一致。防线三门禁本身也要被红队测试一个永远绿色的门禁毫无意义。test_docs_system.py 专门做负向测试人为制造未标注页面未放行页面泄露快照被篡改等违规断言门禁确实会失败。连检查器本身也在被检查。此外source-state.md 是一份公开可查的来源状态台账逐条记录文档里每一类事实今天的真相来源是什么真实源码 / 已测示例 / 模拟输出以及对应的状态标签generated、checked-example、shipped-source等。CI 侧还有专门的 docs-job.yml 流水线每次变更都完整重跑漂移 → 门禁 → 示例测试 → 严格构建 → 产物断言。可重试、可恢复的 Agent 运行——这些能力正是文档中被逐条验证过的行为。一键操作文档如何从代码到发布对维护者来说整套流程被压缩成 6 个编号脚本位于 docs/_system/ 目录按顺序执行即可1_generate_docs_from_frozen_code.sh — 从冻结代码重新生成全部页面并跑完所有检查最后一行必须输出ALL GREEN2_show_all_pages.sh — 列出所有页面PUBLIC yes的行就是即将发布的集合3_publish_a_page.sh — 单独放行某篇已就绪的页面4_preview_the_site.sh — 本地预览逐页点击走查5_check_everything_is_ok.sh — 任何修改后重新全量校验必须保持ALL GREEN6_deploy_the_site.sh — 只部署公开构建产物内部评审版含脚手架页面严禁上线。每一步出现红勾时文档运维手册 _runbook.md 里有一张对照表明确告诉你这个红勾意味着什么、该跑哪个场景S1–S13例如快照漂移 → 重新生成并连同代码一起提交。完整的上线操作清单在 Go-Live 手册。路线图0.3.0 已交付什么哪些还在路上如果说防火墙保证已发布的不骗人那么 roadmap.md 就保证未交付的不冒充。它把内容切成两半已在 0.3.0 交付Shipped保留式运行Retained runsworkspace.run(...)的任务输出先被保留到一边不碰你的工作树直到你显式结算签名式权限授权ReadOnly/ReadWrite等权限是任务签名的一部分在沙箱中由系统调用级 jail 强制按绑定分列的 Changeset每次运行改了什么只读视图一目了然显式结算select/apply/release/discard四选一消费一次、留痕一次持久化追踪shepherd run trace run-ref随时回读运行记录调试靠读记录不靠猜。明确标注尚未交付Ahead不在 0.3.0直接由模型应答的环境模型服务DeliveryFailed会响亮地失败而不是静默出错任务返回值携带世界资源句柄- GitRepo之类的返回槽位目前被拒绝防止模型伪造句柄类型化值投影、持久化子运行、任务即值的委托监督元代理北极星功能明确延期。文档对此的承诺写得很直白见 roadmap.md 末尾如果你发现某句已发布的内容在安装好的包上跑不通那是文档的 bug。每一个已发布页面都带Applies to版本标注未发布的功能页面会被直接撤下——路线图就是它们的转发地址。上手体验三步验证这套文档体系想亲自感受文档即测试的闭环git clone https://gitcode.com/gh_mirrors/shepherd16/shepherd cd shepherd uv run pytest docs/_src/shepherd/test_docs_system.py看着门禁对注入的违规逐一变红再回头读 pipelines.md 里的阶段定义你就理解了为什么 Shepherd 敢在文档里写那句承诺文档里写的每个功能要么有测试要么不存在。【免费下载链接】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），仅供参考