GitHub 相关开源项目：用「Agent Loop 透镜」读仓库
在 Loop Engineering 子站 建立直觉后，请回到真实仓库验证：它们如何实现迭代预算、停止条件与轨迹。本篇不追求星标榜，而追求 可读、可对照、可迁移。
读仓库的四问（先于 clone）
- 循环拓扑是什么？ 单环 ReAct、状态图、多 Agent，还是「其实没有环」？
- 停止条件在哪段代码？ 搜
max_iterations、should_continue、Stop、budget。 - Observation 如何写回消息？ 有无压缩、截断、去重？
- Harness 边界在哪？ 工具执行是否沙箱化？审批在环内还是环外？
一、按回路角色分类的项目地图
| 角色 | 你要学什么 | 代表方向（生态会变，以官方为准） |
|---|---|---|
| 整环编排 | 状态机、图、检查点 | LangGraph、Temporal+Agent 模式、自研 Runtime |
| Tool Loop 内核 | tool_calls 解析与消息拼装 | OpenAI Agents 示例、LiteLLM、各 SDK demo |
| Harness / 运行时 | 插件、沙箱、Session | DeepSeek Harness、类 Cordis 宿主 |
| 评测传感器 | 数据集、Judge、单测门禁 | Promptfoo、DeepEval、场景化评测套件 |
| 可观测 | Trace/Span | OpenTelemetry 应用、Langfuse、Phoenix |
| 多 Agent | handoff、黑板 | AutoGen / Crew 类框架（需严格审停止语义） |
| 记忆写回 | 向量库+过滤 | 各 Memory 中间件，对照本站 Memory 文档 |
警告：星标高 ≠ Loop 工程正确。许多仓库 README 演示「无限自主」，生产必须自己加预算。
二、DeepSeek Harness 与 Hermes 相关
2.1 DeepSeek Harness（DSH）
在回路中的位置：Harness 平面——插件生命周期、Session、预设 Bundle、副作用回收。
Loop 学习者该看：Agent 常驻如何与「每轮 tool」交互；配置热更新时循环状态是否失效；Web Host 日志能否当 Trace。
不要误用：把 DSH 当「自动帮你设计 ReAct 停止条件」的全家桶——停止谓词仍要你在应用层写。
对照文档：DSH 入门、DSH GitHub 导读。
2.2 Hermes / 工具调用对齐生态
位置：Model + Tool 协议层。
Loop 学习者该看：标签解析失败时环如何恢复；Persona 是否每步重灌 ；多轮 tool 的消息角色是否干净。
对照：Hermes GitHub 导读。
三、图编排与状态机仓库怎么读
3.1 寻找「边」上的守卫
打开图定义文件，重点不是节点名漂亮，而是：
- 条件边：
if score < 0.8 → revise - 最大跳数：是否全局硬编码
- 中断：human-in-the-loop 节点是否真能阻塞副作用
3.2 检查点
搜 checkpointer、persistence、thread_id。问：崩溃后能否从 step K 恢复？恢复是否重放副作用？
3.3 反模式信号
| 信号 | 含义 |
|---|---|
只有 while True 无 break 文档 | 玩具 |
| 停止靠 Prompt「请结束」 | L05 高发 |
| 评测节点可被写工具改 | L06 风险 |
| 多 Agent 无 handoff schema | L08 风险 |
四、可观测与评测仓库
4.1 Trace 系统
你要迁移的能力：
- span 对应「一步 LLM」与「一次 tool」
- 属性：
stop_reason、topology、plan_version - 采样：全量生产太贵时，至少失败全采
4.2 评测框架
用 Evaluator–Optimizer 视角读：
- 数据集是否版本化？
- 分数是否可复现？
- 优化器进程是否碰得到评测金标答案？（不应）
五、多 Agent 框架审阅清单
克隆后 30 分钟审阅表：
| 检查项 | 通过标准 |
|---|---|
| 角色工具集不相交或明确重叠策略 | 无「人人都能毁灭性操作」 |
| 全局预算可配置 | 默认不是无限 |
| handoff 含工件引用 | 非纯聊天 |
| 有循环检测 | A→B→A 会停 |
| 有示例 Trace | 可教学 |
| License 与安全模型清晰 | 可上生产评估 |
不通过就当 灵感来源，不要当 默认底座。
六、本站其它 frontend 仓库的对照价值
工作区中的 hermes_frontend、dsh_frontend、memory_frontend、loop_engineering_frontend 等，更适合学：
- 课表如何把概念拆成 Day
- 交互实验如何服务直觉（注意：loop 子站历史实验偏经典反馈；文档站已校正为 Agent Loop）
- 进度/打卡 API 如何服务学习产品，而非 Loop Runtime 本身
读 loop_engineering_frontend/src/data/days.ts 时，请用本系列文档做 概念翻译：把「PID」课映射为「预算与增益隐喻」，把「开环/闭环沙盒」映射为「无验收 vs 有验收的 Agent」。
七、推荐自学顺序（两周）
| 天 | 动作 |
|---|---|
| 1 | 在任意 Agents SDK demo 里定位 while/递归循环 |
| 2 | 给 demo 加上 fingerprint 与 max_steps（自己 PR 到 fork） |
| 3 | 读一个图编排示例的条件边 |
| 4 | 接一个 Trace 后端，跑通 10 次任务 |
| 5 | 读 DSH 或同类 Harness 的 Session 模型 |
| 6 | 选一个多 Agent 框架按第五节审阅表打分 |
| 7 | 写一页「我们不采用 XX 的原因」ADR |
| 8–14 | 在自己业务上复刻最小 Runtime + 黄金任务集 |
八、引用与链接卫生
- 文档中的仓库名会过时：以组织官方 README 为准。
- 不要在教学里贴过期的 star 数当权威。
- 安全相关仓库（沙箱、命令执行）优先读 Threat Model。
- 贡献代码前先跑其测试；你的 fingerprint 补丁可能暴露其默认无限环。
九、把开源映射回本系列文档
| 你在仓库看到 | 回到哪篇文档 |
|---|---|
max_iterations | 快速开始 预算节 |
| 条件边 / 重规划 | 开发指南 Plan–Execute |
| LLM-as-judge 环 | 开发指南 Evaluator–Optimizer |
| 多角色聊天无工件 | 开发指南 L08 + 最佳实践 |
| Session/插件 | DSH |
| 工具描述 | Hermes |
十、练习：写一份「仓库回路卡」
对每一个认真读的仓库，填一张卡（可进团队知识库）：
| 字段 | 内容 |
|---|---|
| 仓库 | URL + commit |
| 拓扑 | |
| 停止条件代码路径 | |
| 预算维度 | |
| Trace | 有/无 |
| Harness 能力 | |
| 失败模式覆盖 | L01–L12 哪些已有 |
| 采用建议 | 用 / 部分用 / 不用 |
| 一句话风险 |
连续写满 5 张卡，你的「开源鉴别力」会超过只追星标的人。接着读 最佳实践 把鉴别力变成团队规范。
十一、MCP 与工具生态仓库
MCP 仓库解决的是 工具发现与调用协议，通常不自带完整 Loop。阅读时区分：
| 层级 | MCP 相关仓库 | Loop 仍需自建 |
|---|---|---|
| 传输与 Schema | servers、SDK | 迭代与停止 |
| 鉴权 | OAuth 示例 | 预算与熔断 |
| 采样 | 客户端 demo | 验收谓词 |
把 MCP 服务器当 Harness 的工具插件来源，把本系列 Runtime 当编排层——边界清晰后，生态升级不会掀翻你的停止条件。结构优秀的文档范例可参考本站 MCP 文档。
十二、计算机使用 / 浏览器 Agent 仓库特别警告
此类 Agent 的 Observation 是截图或 DOM，极易触发 L04（上下文中毒）与费用爆炸。
审阅加项：
- 是否强制分辨率/区域裁剪？
- 是否有「连续相同截图哈希」熔断？
- 点击坐标是否有沙箱域名白名单？
- 是否禁止在登录页自动填密码（除非保险库注入）？
没有以上四项，只适合隔离环境演示，不适合接生产账号。
十三、CI 里的 Agent：读 GitHub Actions 示例时的额外问题
越来越多仓库在 CI 里跑 Agent 修测试。额外四问：
- Secrets 是否对 Agent 工具可见？（应最小化）
- 是否禁止 push 到 main？（应只开 PR）
- 费用是否有组织级 cap？
- 失败是否留下 Trace artifact 供人审？
若 CI Agent 能直接改 workflow 自身权限，视为严重设计缺陷。
十四、写给维护者：给上游提 Loop 相关 PR 的礼仪
- 先开 Issue 描述无限环或缺失预算的复现。
- PR 保持最小：
max_iterations默认值 + 文档一句。 - 附上你的 Trace 片段（脱敏）。
- 不要夹带无关重构。
- 若维护者坚持「自主无限」，在自有 fork 保留补丁并在回路卡注明「上游风险」。
这样你既贡献生态，又不把生产绑死在玩具默认值上。