Feature/eval optimize loop

[guocfu]

关联 Issue

Closes #91

变更说明

本 PR 实现 Evaluation + Optimization 自动回归与提示词优化闭环，覆盖离线验证、Trace 回放和真实模型集成三种运行方式。

主要流程：

1. 校验 pipeline、optimizer、evalset 和 Prompt 配置。
2. 创建隔离的 Prompt 工作区并记录输入哈希。
3. 完整评测 baseline train 和 validation。
4. 生成候选 Prompt。
5. 完整评测 candidate train 和 validation。
6. 标准化评测结果，生成失败归因和 Case Diff。
7. 根据效果、过拟合、关键 Case 和资源预算执行 Gate。
8. Gate 接受后，通过源文件哈希校验、回读验证和失败回滚安全写回 Prompt。
9. 输出 JSON、Markdown、artifact index 和失败报告。

主要能力

• 提供确定性的 Offline Model 和 Candidate Provider，无 API Key 也能验证核心闭环。
• 支持 Trace Mode，直接回放预录制 Agent 结果，不重复执行 Agent。
• 提供显式启用的真实集成入口，支持真实业务 Agent 和真实反思优化模型。
• 接入 AgentOptimizer(update_source=False)，候选生成期间不直接修改源 Prompt。
• Baseline 和 Candidate 分别执行完整 train/validation 评测。
• 支持多次运行结果标准化、失败归因、Case Diff 和过拟合识别。
• Gate 支持验证集提升、通过率下降、hard/critical regression 和预算限制。
• Prompt 写回包含源哈希校验、回读验证和失败回滚。
• 保存优化器原生产物、四次评测结果、Prompt 快照和资源观测结果。
• 对运行时配置、失败报告和 CLI 异常进行敏感信息脱敏。
• 支持原子报告发布、路径越界防护和符号链接检查。

运行模式

• offline：真实 LlmAgent 配合确定性模型和确定性评测规则。
• trace：回放预录制轨迹，不执行 Agent。
• real：真实业务模型配合真实 AgentOptimizer 反思模型。

真实模式必须显式传入 --run-real，连接信息从环境变量读取，优化模型参数通过命令行参数传入。

测试覆盖

• Offline 三种候选场景：
  • improve
  • no improvement
  • overfit
• 四次完整评测及多 run 场景。
• 评测标准化、失败归因和 Case Diff。
• Gate 接受、拒绝、过拟合、关键 Case 和预算规则。
• Prompt 漂移检测、安全写回和回滚。
• Trace 回放及路径安全校验。
• 报告、artifact index、失败报告和敏感信息脱敏。
• 真实集成入口的离线契约测试。
• CI 子进程在非 editable-install 环境中的 CLI 导入验证。

执行：

pytest -q tests/evaluation/test_eval_optimize_loop_*.py

本功能相关测试全部通过。

[helloopenworld]

AI Code Review

我已经完成了全面审查。让我来撰写最终的审查结论。

发现的问题

⚠️ Warning

• examples/optimization/eval_optimize_loop/report_builder.py:53-68：redact_error_message 只按值替换 TRPC_AGENT_API_KEY/TRPC_AGENT_BASE_URL 两个环境变量的明文，其他来源（如自定义环境变量名、SDK 内部展开后传入的凭据）只能依赖正则兜底。

  • 真实模式下若 SDK 异常文本里出现非预期形态的凭据（例如被拆分到多行、或出现在 URL 的 userinfo 部分 https://user:key@host），_SENSITIVE_KEY_VALUE 正则不一定会命中，存在泄露风险。建议将 on_unavailable 失败路径上的异常信息一律先经环境变量值替换，再叠加正则与 URL 脱敏，并补充覆盖 userinfo 形态 URL 的测试用例。

• examples/optimization/eval_optimize_loop/artifact_writer.py:157-232：_rename_directory_no_replace 在 Linux 上依赖 renameat2(RENAME_NOREPLACE)，遇到 ENOSYS/EINVAL/EOPNOTSUPP 时直接 ArtifactWriteError 失败关闭。

  • 这是显式安全取舍，但在较旧内核或受限容器（如某些 CI runner）上会令整条报告发布链路失败、阻塞 CI。建议在不可用时回退到「先 mkdir 探测 + os.replace」的原子替换策略，或至少在错误信息中提示可手动开启的兼容路径，避免 CI 在环境不支持时被静默阻塞。

💡 Suggestion

• examples/optimization/eval_optimize_loop/schemas.py:87：OptimizerRuntimeParameters.temperature 仅约束 ge=0.0，无上界。真实反思模型若被传入极高温度（如 1000），会显著放大成本与不稳定输出，且 BudgetConfig 无法在事前拦截。可加上合理上限（如 le=2.0）并在 README 中说明有效区间。

总结

整体风险较低，无必须修复的 Critical 问题。代码在路径穿越、符号链接、原子发布、源 Prompt 回滚与凭据脱敏上均有较完整的防御；两个 Warning 分别集中在异常脱敏的覆盖面与原子发布的平台兼容性上，建议在合入前评估真实运行环境是否会触发。

测试建议

• 暂无额外测试建议。现有 test_failure_report_redacts_environment_values_and_common_secret_forms 与 test_real_cli_redacts_environment_secrets_from_pipeline_error 已覆盖主要脱敏路径；如采纳上述 Warning，可补充 userinfo 形态 URL（https://user:secret@host）的脱敏断言，以及 _rename_directory_no_replace 在 renameat2 不可用时的回退行为断言。

[raychen911]

这里提几个建议：
1、当中这个issue是基于框架做一个shiji 例子，所以这里单测不应该放在tests目录下，tests目录下是框架接口的单测，这里可以不写单测，
2、当前的examples看着写的比较丰富，是否把代码整合一下，看着可能比较松散，可以看看其他的例子的模式。例如：

examples/quickstart/
├── agent
│   ├── agent.py
│   ├── config.py
│   ├── __init__.py
│   ├── prompts.py
│   └── tools.py
├── README.md
└── run_agent.py

这样用户看起来比较方便，期望按照这种方式整理代码，数据类的专门放在data目录中
3、在readme中将使用方式写详细，我这边可以快速浮现效果，

[raychen911]

这个文档建议放在examples/optimization/eval_optimize_loop目录下