工具通常分散在文件系统、终端、浏览器、搜索、编辑、MCP 等模块里。读工具时问： 工具 schema 在哪里定义？ 描述如何送给模型？ 参数在哪里校验？ 执行前是否有 preview？ 用户确认如何表达？ 失败如何反馈给模型？ 输出如何截断？ 如果一个项目有 MCP，继续问： MCP Server
run 生命周期通常包括： 初始化 session； 构建上下文； 调用模型； 解析响应； 执行工具； 写状态； 输出 UI event； 进入下一步或停止。 你要找的不是某个函数名，而是状态怎样流动。很多项目不会把它叫 runAgent，可能叫 task、controller、orchestrat
入口包括 CLI 入口、IDE extension 激活入口、Web server 入口、worker 入口。入口读法： 找 package.json scripts 和 bin； 找 extension manifest； 找 server bootstrap； 找主 command handle
项目 重点 Cline TS Agent Runtime、IDE/CLI 产品形态、工具审批、MCP Continue IDE 集成、上下文 provider、模型配置 aider repo map、git diff、命令行结对编程体验 OpenHands sandbox、任务自动化、agent 平
每个项目都用同一套问题： 1. 项目入口在哪里？ 2. Agent run 的生命周期在哪里？ 3. 模型调用在哪里封装？ 4. 工具注册在哪里？ 5. 工具调用结果如何回灌给模型？ 6. 权限审批在哪里？ 7. 上下文如何构建？ 8. 状态如何保存？ 9. 如何处理取消、失败、重试？ 10. tr
读开源 Agent 项目，别一上来就钻进细节。本章给一套追主线的方法。 读开源 Agent 项目，最怕两种读法。一种是从 README 兴奋到插件列表，最后只记住产品功能；另一种是一头扎进代码细节，三天后迷失在 UI、配置和历史兼容里。Runtime 工程师读源码，要带着问题读，尤其要追执行链路。
你不再靠感觉说 Agent 变好了，而是有数据证明；你能比较两个 prompt 或两个 runtime 策略；一次线上失败能进入回归集；危险行为有硬门禁。到这里，Agent Runtime 已经具备工程组织能信任的反馈机制。
建立 evals/ 目录： 10 个文件编辑任务； 10 个工具调用任务； 10 个失败恢复任务； 每个任务有 fixture、prompt、expected、policy； CI 中运行 mock replay； 成功率低于阈值则失败； 输出报告包含成功率、平均 step、平均 token、失败类
Eval 不只是测模型，也测 runtime 策略。例如： maxSteps=10 vs maxSteps=20； 工具描述短版 vs 长版； 旧历史保留 4 轮 vs 8 轮； 搜索结果返回 20 条 vs 50 条； 写入前是否强制计划； 工具失败后是否允许自动重试。 每次对比只改一个关键变量。
Agent eval 天生有波动。处理 flaky 的方法： runtime 单元测试使用 mock model； 真实模型 eval 多跑几次取统计； 用行为断言代替字面匹配； 把'必须不发生'的危险行为单独作为硬门禁； 把人工 judge 与程序化断言分开； 对不稳定 case 标记 quara
成功率重要，但不够。还要看： 平均 step 数； 平均 tool call 数； 平均 token； 平均耗时； 权限请求次数； 用户拒绝后是否停止； 相同错误重复次数； 输出是否引用证据； 文件 diff 是否最小； 回滚是否成功。 一个 runtime 策略可能成功率略高，但成本翻倍、工具调用
一次线上失败，如果不能转化为 eval，它就会再次发生。建议流程： 1. 从 trace 中提取用户目标、关键上下文、工具调用和失败结果； 2. 去除 secret 和用户隐私； 3. 固化 workspace fixture； 4. 写 expected behavior； 5. 加入 CI； 6
真实模型有随机性、网络波动和供应商变化。Eval 需要两层： 第一层用 deterministic mock model 测 runtime 逻辑。它按照脚本返回固定 tool calls，用来验证 schema 校验、权限、checkpoint、trace、停止条件。 第二层用真实模型测端到端能力
golden task 是一组有代表性的任务。对 coding agent 来说，可以分为： 文件阅读任务； 代码搜索任务； 单文件编辑任务； 多文件编辑任务； 测试修复任务； 权限拒绝任务； 工具失败恢复任务； 上下文压缩任务； checkpoint/resume 任务。 每个 task 至少包含
说 Agent '变好了'很容易。证明它变好了，要靠 eval。 Agent 产品很容易陷入'今天试了几个问题，感觉不错'的幻觉。工程系统不能靠感觉上线。Eval Harness 要把真实任务变成可重复的测试，把 trace 变成回归样本，把 prompt、工具和 runtime 策略的变化变成可比
一次失败任务可以从 trace 里定位原因；你能区分模型问题、工具问题、权限问题、上下文问题和 runtime 问题；trace 中没有明文 secret；每个失败都能转化为一个潜在 eval case。
为每次 Agent run 输出 trace JSON，记录： model； prompt tokens； completion tokens； tool name； args； duration； success/failure； retry count； cost estimate； appro
入门阶段可先用本地 JSONL： 每个 run 写入： 后续再接 OpenTelemetry、LangSmith 或自建 UI。先把语义记对，再追求漂亮 dashboard。
trace 很敏感。它可能包含用户代码、命令输出、环境变量、文件路径、API 响应、模型输入输出。生产系统中，trace 需要： secret 脱敏； 访问控制； 保留期限； 采样策略； 用户可删除机制； 外部导出审计。 不要为了调试方便，把所有 trace 原样传到第三方系统。可观测追求的不是越多
Agent 失败常被粗暴归结为'模型不行'。这不专业。至少分成五类： 归因 典型现象 模型问题 推理错误、忽视观察结果、重复无效计划 工具问题 工具崩溃、返回格式错、输出不完整 权限问题 策略过严或过松，审批状态丢失 上下文问题 关键文件未注入，历史摘要误导 Runtime 问题 停止条件、重试、并
