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中将使用方式写详细，我这边可以快速浮现效果，

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@12388ad). Learn more about missing BASE report.

Additional details and impacted files

@@            Coverage Diff             @@
##             main        #221   +/-   ##
==========================================
  Coverage        ?   88.44269%           
==========================================
  Files           ?         491           
  Lines           ?       46118           
  Branches        ?           0           
==========================================
  Hits            ?       40788           
  Misses          ?        5330           
  Partials        ?           0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[helloopenworld]

AI Code Review

发现的问题

🚨 Critical

• examples/optimization/eval_optimize_loop/run_pipeline.py:141：real 模式成功运行后 _print_result 必崩
  • _print_result 无条件访问 result.scenario，但 RealStageResult（data/schemas.py:449-453）只定义了 candidate 和 optimize_result，没有 scenario 字段；只有 OfflineStageResult/TraceStageResult 才有。real 模式在 run_pipeline.py:202 以 mode="real" 调用本函数，会在已产生真实 API 费用的运行成功后抛 AttributeError，导致进程以失败结束且不打印任何结果。修复：对 real 模式跳过 scenario（如 f" ({result.scenario})" if mode != "real" else ""），或改用 getattr(result, "scenario", None)。

  print(f"Candidate: {result.candidate.candidate_id} ({result.scenario})")

⚠️ Warning

• examples/optimization/eval_optimize_loop/core/reporting.py:197-212：错误信息脱敏对非环境变量形态的凭据存在覆盖盲区

  • redact_error_message 仅替换 TRPC_AGENT_API_KEY/TRPC_AGENT_BASE_URL 两个环境变量原值，以及 api_key|base_url|authorization 前缀后的值；像 token: sk-...、X-Api-Key: ... 这类前缀不在 _SENSITIVE_KEY_VALUE 交替项中的敏感字段不会被脱敏，若异常文本里出现这些形态的凭据则会写入 failure_report.json。建议扩充前缀白名单（如 token、xapikey），与 _SENSITIVE_CONFIG_KEYS 保持一致。

• examples/optimization/eval_optimize_loop/core/pipeline.py:939-967（run_real_stage）：成功路径缺乏 --run-real 之外的费用/超时保护

  • real 模式无整体超时与重试上限控制，AgentOptimizer.optimize 可能长时间运行并持续产生费用；budget.max_duration_seconds 只在 Gate 阶段对已观测的 duration_seconds 判定，无法中断进行中的运行。建议在 _execute_real_stage 外层加可取消的超时包裹（如 asyncio.wait_for），避免失控费用。

• examples/optimization/eval_optimize_loop/core/optimization.py:157：运行时配置写入路径与产物索引假设耦合，跨文件系统无保护

  • runtime_path = request.output_dir.parent / "optimizer.runtime.json" 假设 output_dir 已有父目录且与 run 目录同文件系统；若 output_dir.parent 不可写或跨文件系统，write_text 抛 OSError 会被转成 CandidateProviderError，但 publish_report_bundle 的 native_paths 过滤（reporting.py:706-711）依赖该文件恰好位于 run 根目录且名为 optimizer.runtime.json，一旦路径变化会导致原生产物不被索引。建议显式校验 output_dir.parent 可写，或将运行时配置路径固定为 run_dir/optimizer.runtime.json 而非 output_dir.parent 推导。

💡 Suggestion

• examples/optimization/eval_optimize_loop/core/pipeline.py:139-148 与 core/reporting.py:925-946：失败报告与产物发布的原子性已较完备，但 _handle_stage_failure 在 _record_failure 自身失败时用 PipelineExecutionError 包装并 raise ... from error，会丢失原始 failure 报告写入能力；可考虑即便报告写入失败也保留 run 目录下的部分产物供排查，长期维护性更佳。

总结

存在一个必须修复的 Critical 问题：real 模式成功运行后 _print_result 会因 RealStageResult 无 scenario 字段而崩溃，且该路径无测试覆盖；其余为脱敏盲区、费用超时保护与路径耦合等 Warning 级风险。建议优先修复 Critical 后再合入。

测试建议

• 补充 real 模式端到端冒烟测试（可用 fake call_agent + mock AgentOptimizer.optimize 替代真实 API），覆盖 run_real_stage 成功后 _print_result("real", ...) 不抛异常。
• 为 redact_error_message 增加单测，覆盖 token:/X-Api-Key: 等非 api_key 前缀的凭据形态是否被脱敏。

[helloopenworld]

AI Code Review

确认：os.link 没有处理 EXDEV。现在让我来写最终的审查报告。

发现的问题

⚠️ Warning

• examples/optimization/eval_optimize_loop/core/reporting.py:937：write_failure_report 使用 os.link 跨设备硬链接会失败

  • os.link(temporary, target) 在临时目录与 run 目录分属不同文件系统（EXDEV/OSError）时会抛错，被外层 except 转成 ArtifactWriteError，导致失败报告本身无法写入——恰好在最需要保留故障证据的路径上丢失证据。建议改用 shutil.move 或捕获 OSError 后回退为 write_text(target, ...) 的非原子写入。

• examples/optimization/eval_optimize_loop/core/reporting.py:4420：Windows 分支的 os.rename 不满足“原子 no-replace”承诺

  • 注释声称每个平台都使用“atomic no-replace primitive”，但 Windows 分支仅用 os.rename：跨卷时会退化为非原子复制，且与前置 target.exists() 检查之间存在 TOCTOU 窗口。建议 Windows 上也使用支持原子语义的 API（如 MoveFileEx + MOVEFILE_REPLACE_EXISTING 的反向校验，或显式 os.replace 仅在目标不存在时），或至少在文档中收窄“原子”承诺。

• examples/optimization/eval_optimize_loop/data/config.py:5080：ReportingConfig 与 ArtifactConfig.audit_all_candidates 被校验但从未被消费

  • write_json、write_markdown、include_case_evidence 以及 audit_all_candidates 在 publish_report_bundle 中从未读取：JSON 与 Markdown 报告始终被写入，case evidence 始终包含。用户配置这些项后不会生效，属于配置-行为不一致的兼容性隐患。建议要么实现这些开关，要么从 schema 中移除并在文档说明默认行为，避免误导使用者。

💡 Suggestion

• examples/optimization/eval_optimize_loop/run_pipeline.py:6090：main() 在非 real 模式下未拒绝 --optimizer-* 系列参数
  • 仅 --run-real 做了互斥校验，--optimizer-model-name 等参数在 offline/trace 模式下会被静默忽略，容易让使用者误以为已生效。可在非 real 模式下对这些参数报 parser.error，或在 help 中明确其仅在 real 模式生效。

总结

整体风险较低：核心的隔离 staging、源 Prompt 哈希校验、回滚、敏感值脱敏与占位符化、路径穿越/symlink 防护等关键链路实现严谨，无明显逻辑或安全 Critical 问题。主要问题集中在失败报告写入的跨设备稳定性、Windows 原子发布承诺过强，以及部分配置项未真正生效，建议修复前两者以保证故障证据可靠落盘。

测试建议

• 建议补充 write_failure_report 在跨文件系统（EXDEV）场景下的回退测试，以及 publish_report_bundle 在 Windows/非 renameat2 平台的发布测试，验证故障证据始终可落盘。
• 建议为 ReportingConfig.write_json/write_markdown 等开关补一条“配置关闭后报告确实不生成”的测试，否则应移除这些未实现字段。

[helloopenworld]

AI Code Review

这些 regex 模式没有灾难性回溯的风险。数值匹配的替代方案是线性安全的。

我已经完成了审查，代码写得很好。让我给出结论。

让我重新考虑最后一个真正的问题：_optimizer_resources 访问了 native.total_token_usage，这是一个 dict[str, int]。但 _is_complete_token_usage 会检查 type(value[key]) is int and value[key] >= 0。如果 SDK 返回的 dict 中包含非 int 值（例如 float 或 str），那么 token_usage_valid 将为 False，tokens_missing 为 True（短路），reason 为 _INVALID_TOKEN_REASON。没问题，不会崩溃。很好。

现在让我确认一下 OptimizerResourceValue[dict[str, int]] 的校验器是否会拒绝 dict[str, int]（非数值类型）的有效值。校验器在状态为 "available" 时：isinstance(self.value, (int,float)) and not self.value >= 0 —— 对于 dict，isinstance(dict, (int,float)) 为 False，因此不会触发非负数检查。所以 dict 值可以通过。没问题。

最终结论：没有阻塞性问题。让我写出诚实的审查报告，并附上几条建议。

实际上，让我再重新考虑一下是否存在真正的正确性问题：在 _execute_real_stage 中，第 838 行的 request 包含 expected_optimizer_sha256=prepared.input_snapshot.optimizer_config_sha256，而 _verify_prepared_file（第 784 行）在之前就已经校验过 optimizer config 没有被更改。然后 _prepare_runtime_config 会根据 expected_optimizer_sha256 进行重新校验。这是冗余但安全的做法。没问题。

让我再看最后一个细节——在 perform_writeback 中，第 791 行的第二次 verify_source_hashes(snapshots) 在 await 之后被调用。注释写着“异步读取后，紧邻基于路径的写入操作”。但 verify_source_hashes 会同步读取文件。在 await source_target.read_all()（第 773 行）和 verify_source_hashes（第 791 行）之间，存在一个间隙，此时另一个进程可能会更改源文件。这是注释中提到的已知限制。代码中显示这是尽力而为（best-effort）。我会记录一下这个并发间隙，但注释里已经说明了。最多算是一个建议。

让我完成最后的审查。

发现的问题

未发现明显阻塞问题。

整体来看，该 PR 是一个全新加入的 eval/optimize 闭环示例，代码防御性很强：路径穿越/符号链接逃逸、敏感凭据持久化、原子发布、回滚与失败报告、不可信产物校验等都做了较完整的处理。结合 SDK 上下游类型定义逐项验证后，未发现会导致核心功能失败、数据错误或安全风险的确切问题。

💡 Suggestion

• examples/optimization/eval_optimize_loop/core/pipeline.py:923：运行时不变量使用 assert generated.optimize_result is not None

  • 在 python -O 下断言会被剥离，随后 RealStageResult(optimize_result=generated.optimize_result) 仍会因 SDK 字段约束失败，但错误信号会变得不清晰；若该不变量对正确性重要，建议改为显式 if ... raise，与同文件其它校验风格一致。pipeline.py:329 的 assert config.trace_inputs is not None 同理（已被上游 validator 保证，影响更小）。

• examples/optimization/eval_optimize_loop/core/reporting.py:543-548：Windows 分支用 os.rename 实现"原子 no-replace"发布

  • os.rename 对已存在的目录目标会抛 FileExistsError（故 no-replace 语义成立），配合第 708 行预检查可接受，但预检查与 rename 之间存在 TOCTOU 窗口，且并非真正原子；docstring 声称"atomic no-replace"，建议在注释中说明 Windows 为降级实现或补一行说明，避免维护者误以为三平台语义完全等价。

总结

未发现必须修复的 Critical 或 Warning 级别问题；代码在安全、稳定性与兼容性上处理得当。仅两处可选维护性优化，不影响当前正确性。

测试建议

暂无额外测试建议。该示例目录当前未随附单元测试；若后续要纳入 CI 长期运行，建议补充对 perform_writeback 的 readback 失败回滚路径、以及 publish_report_bundle 在 optimizer.runtime.json 敏感值校验失败时 fail-closed 的覆盖。

[helloopenworld]

AI Code Review

我已经对代码变更进行了深入审查。现根据要求，我将对 pr.diff 中的内容给出审查结论。

发现的问题

⚠️ Warning

• examples/optimization/eval_optimize_loop/core/evaluation.py:654：过拟合判定阈值与 _change 的浮点容差不一致

  • _overfit_status 用裸 train_value > 0.0 and validation_value < 0.0 判定，而 _change/severe 均配合 math.isclose(..., abs_tol=1e-12) 避免浮点噪声。当 train/validation delta 处于 ±1e-15 量级（浮点噪声）时会被误判为 detected，触发 no_overfitting 规则直接 reject 候选。建议对两侧 delta 复用同一 isclose 容差判断“显著为正/为负”。

• examples/optimization/eval_optimize_loop/（整体）：示例进入开发者复用路径但缺少回归测试

  • run_pipeline.py 可被直接执行（offline/trace 不需凭据），核心逻辑（归因 _case_attribution、Gate evaluate_gate、回写 perform_writeback、报告 publish_report_bundle 的原子发布与脱敏）均无对应单测覆盖，且 CI 只跑 tests/ 不含本示例。归因优先级排序与 Gate 规则状态流转是高风险纯函数，建议至少补充 evaluation/optimization 的单元测试锁定关键路径。

💡 Suggestion

• examples/optimization/eval_optimize_loop/core/reporting.py:246-249：tokens_missing 第二个子表达式依赖短路求值，token_usage 非 dict 时靠 not token_usage_valid 先短路才不崩。逻辑虽正确，但可读性差，建议改为 token_usage_valid and reflection_calls > 0 and token_usage["total"] <= 0 形式，避免后续维护者误改引入 TypeError。

总结

整体是一份高度防御性的实现，路径穿越/符号链接/原子发布/凭据脱敏/回写回滚等关键路径处理到位，未发现 Critical 级安全或逻辑缺陷。仅有 1 处浮点阈值一致性 Warning 与 1 处测试覆盖不足 Warning 建议跟进，均为非阻塞性改进。

测试建议

• 暂无额外强约束测试建议；如需补充，优先覆盖：_overfit_status 在 train/validation delta 接近 0 时的边界判定，以及 evaluate_gate 在各 Gate 规则 reject/skipped/warning 组合下的 decision 状态流转。