01项目定位POSITIONING
OpenAgent Evaluation Platform 是一个围绕 Coding Agent 评测证据设计的工程框架。它把任务定义、隔离执行、过程记录、产物收集、质量门禁、回放和报告组织成一条可追问链路。当前定位是项目档案与评测框架，不声称是商业化 SaaS，也不声称适用于所有团队场景。
它的核心关注点不是让 Agent 输出更漂亮的叙述，而是让评测者能沿着证据追问：任务是否明确，环境是否可控，过程是否被记录，结果是否经过验证，失败是否能被定位。只有这些问题被回答，Coding Agent 的能力比较才有工程意义。
02解决的问题PROBLEM
很多 Agent 演示只展示最终 diff 或一句"任务完成"。这不足以判断质量。评测者还需要知道：任务是什么，运行环境是否干净，Agent 调用了哪些工具，失败点在哪里，测试如何执行，产物能否复现，得分依据是什么。OpenAgent 的目标是把这些问题变成结构化对象。
如果没有结构化评测，一次成功可能只是运气，一次失败也很难复盘。不同 Agent 之间无法比较，同一个 Agent 的版本变化也无法解释。OpenAgent 试图把"看起来会写代码"拆成一组可检查信号：输入、过程、产物、验证和报告。
03核心架构ARCHITECTURE
框架从 TaskSpec 开始。TaskSpec 描述任务输入、约束、预期产物、允许工具和验证方式。每次运行进入独立 workspace，避免污染原始仓库或复用上一次残留状态。执行过程中产生 trace.jsonl，按时间记录关键事件、工具调用、状态变化和错误。
运行结束后，系统收集 Artifact，例如补丁、日志、测试结果、报告片段或截图。随后进入 Quality Gate：pytest、lint、静态检查、文件范围校验或自定义 validation。最后生成 scorecard / report，用于说明通过项、失败项、风险和下一步。
架构上要避免把所有东西混成一段运行日志。TaskSpec 是输入契约，workspace isolation 是环境边界，trace 是过程证据，Artifact 是结果证据，Quality Gate 是验证层，scorecard / report 是面向人的解释层。每一层负责回答不同问题。
04执行流EXECUTION FLOW
一次标准执行流可以拆成七步：选择 TaskSpec，创建隔离 workspace，启动 scripted baseline 或 API agent，记录 trace，收集 artifact，运行 validation，生成 scorecard。这里的 scripted baseline 是可控脚本路径，用来建立最低可复现基准；API agent 则是真实模型驱动的执行路径，行为更开放，也更需要 trace 和 replay。
scripted baseline 与 API agent 的区别必须单独说明。baseline 的价值在于稳定、可重复、可作为对照；API agent 的价值在于处理开放任务，但也可能产生非确定性决策。把两者混在一起，会让评测结论失真。好的报告应该说明每条结果来自哪种执行路径。
05证据链EVIDENCE CHAIN
证据链不是堆文件，而是解释"为什么可以相信这次结果"。TaskSpec 证明任务边界；workspace isolation 证明环境干净；trace.jsonl 证明过程可追踪；Artifact 证明输出存在；Quality Gate 证明至少经过一组检查；Replay 证明关键过程可重新观察；scorecard / report 证明结论不是口头判断。
Replay 的作用也不是表演，而是复盘。它可以帮助评测者回看关键步骤：Agent 在什么时候读取文件，什么时候修改代码，什么时候运行测试，失败后是否重试，是否触碰了不该触碰的文件。没有 replay，trace 很容易只停留在机器可读；有 replay，证据才更接近评审可用。
06已实现能力IMPLEMENTED
- 围绕 TaskSpec 组织任务输入和验证目标。
- 以 workspace isolation 作为运行前提，降低状态污染。
- 使用 trace / trace.jsonl 记录执行过程，而不是只看最终结果。
- 收集 Artifact，并把产物与运行记录关联。
- 通过 pytest / validation 表达质量门禁。
- 用 scorecard / report 汇总结果、风险和失败原因。
这些能力的共同点是偏向证据组织，而不是能力包装。它们不保证 Agent 一定完成任务，但能让完成、失败和部分完成都更容易被解释。对 Coding Agent 评测来说，这比单次漂亮结果更重要。
07未实现能力NOT IMPLEMENTED
当前不声称具备完整多租户权限、成本结算、团队协作后台、长期在线调度或任意模型兼容层。更完整的 Web 控制台、历史趋势分析、自动化批量评测和更细的失败归因可以作为 future direction，但不是本档案的已完成声明。
也不应把 planned 能力写成已经可用。例如批量 benchmark、跨仓库长期趋势、可视化对比面板和模型成本分析，都可以是后续方向，但在没有稳定证据前，只能作为规划。项目档案的可信度来自边界清楚，而不是措辞更大。
08可验证方式VERIFICATION
可验证方式应尽量朴素：查看 TaskSpec；检查 workspace 是否独立创建；阅读 trace.jsonl 的事件顺序；确认 artifact 是否存在；运行 pytest 或对应 validation；对比 scripted baseline 与 API agent 的输出差异；阅读最终 scorecard / report 是否明确列出通过、失败和未覆盖项。
验证时还应关注负面证据：测试失败是否被记录，未覆盖项是否被写出，跳过的检查是否有原因，人工判断是否和机器输出分开。一个诚实的 report 不只列通过项，也要告诉读者哪些结论暂时不能下。
如果评测对象是同一任务的多次运行，还应比较 trace 的分叉点：是否在相同文件上反复失败，是否因为环境差异导致结果变化，是否在没有新证据时给出更乐观的结论。这些细节能帮助区分"任务本身困难"和"Agent 行为不稳定"。
09边界声明BOUNDARY
OpenAgent 不把一次成功运行包装成通用结论，不把模型输出等同于工程质量，也不把 planned 能力写成 implemented。它适合展示评测证据框架、运行复盘方法和 Agent 后端工程判断；不适合用来承诺无人审核地完成所有开发任务。
因此，OpenAgent 的公开表达应保持克制：可以说它提供一套可追问的评测组织方式，可以说它强调 trace、artifact、quality gate 和 replay，但不应把它描述成生产级平台或直接替代开发者的工具。评测框架的价值在于让能力边界更清楚。
这也是项目档案本身的边界：它呈现方法和证据结构，不替代实际运行记录，也不把尚未验证的方向写成确定能力。
10可追问问题REVIEW QUESTIONS
- 这个任务的 TaskSpec 是否足够明确？
- 运行是否发生在干净 workspace 中？
- trace.jsonl 能否解释关键决策和失败点？
- Artifact 是否能被独立打开或复查？
- Quality Gate 包含哪些 pytest / validation，哪些没有覆盖？
- Replay 能否复现主要步骤，而不是只展示最终截图？
- scorecard / report 是否区分事实、判断和计划？
- scripted baseline 与 API agent 的差异是否被单独说明？