optim-agent
把编码智能体变成超参数优化器：读取代码、理解参数语义、提出试验并记录真实目标结果，替代低效的手工调参。
最小权限：SECURITY.md 声明以子进程启动已认证的本地 agent CLI，但未见权限边界或沙箱约束的具体代码证据，仅给1分。用户确认：整个流程由用户在本地驱动，但源文件未见任何执行前确认机制，记0。数据流透明：agent 仅提议参数值，主程序对照声明空间验证并回退安全采样，JSON/SQLite 记录完整，良好（2）。敏感数据：SECURITY.md 明确要求提示词不含密钥、并提醒嵌套会话继承 ANTHROPIC_API_KEY，属合格但依赖用户自觉（2）。依赖安全：可选依赖分组清晰，CI 权限最小化（contents: read），但无锁文件或依赖审计证据（2）。外部影响：以 coding agent CLI 驱动任意目标系统参数调优，影响范围取决于用户目标代码，文档未明确警示，仅1分。回滚：study./SQLite 可恢复（resume）与持久化有说明，但无失败回退策略细节（1）。来源归属：致谢 Optuna/OpenCode，MIT 版权声明完整，作者字段明确（2）。未发现任何红线风险。
自洽性：README 中的安装方式、quickstart、参数（effort/history/explicit_reasoning）与测试断言（test_optim_agent.py 校验 docs 与 API 一致）相互吻合；但 README 含乱码语言链接（한국어、Deutsch 等列显示异常字符），扣分。依赖可用性：requires-python>=3.9，CI 覆盖 3.9/3.11/3.13 及 vision extras，依赖分组明确，缺少实际源码验证的锁定版本，给2。失败消息：文档明确列出错误路径（401 处理、超时回退随机采样、ValueError 指明修复方式），并指出 OpenCode 分布式限制，表现良好（2）。
受众与场景：'Where It Applies' 表覆盖训练、推理、量化、RL、科学工作流、黑盒系统，且明确 RL 场景只调环境不替代策略学习（2）。能力边界：'Bounded execution'、'not a production credit-decision system'、GIL 与并发限制等声明充分，是本项目最突出之处（3）。触发精度：AgentSampler 参数、mock 后端、pruner level 等触发条件说明清晰，但未展示对模糊/非法 agent 回复之外的输入校验细节（2）。环境适配：mock 后端便于离线测试，SQLite WAL 支持分布式，Python 版本兼容明确，但依赖用户 PATH 上已有的付费/免费 CLI（2）。
信息架构：README 分节清晰（Why/Install/Quickstart/Where/Usage/Troubleshooting），多语言与文档站、教程、论文齐全，但存在明显乱码语言链接（한국어/Deutsch 位置文字异常）与小排版问题（扣分）。安装说明：三种安装路径（skill、插件、pip）配命令与前置条件，完整（3）。命名稳定性：PyPI 名、模块名、GitHub 组织一致，测试断言锁定公共元数据（2）。示例与 FAQ：多个可复现示例、复现命令、测试内嵌示例契约（3）。已知限制：GIL、并发 in-flight 不可见、credit 基准的方法学缺陷、OpenCode 分布式不支持等均明示（3）。许可：MIT 与 LICENSE 文件、pyproject 声明一致（3）。版本与变更日志：0.2.0，CHANGELOG.md 由测试强制要求 'Unreleased/0.1.0' 分节，但 changelog 内容本身未在证据中（2）。维护责任：CONTRIBUTING/SECURITY/CODE_OF_CONDUCT/ROADMAP 齐备，CI 有覆盖率门限，但发布者身份未经注册表验证，主体为化名 'Optim-Agent'，给2。
输出可用性：verbose 表格/单行双模式、summary 四段结构、JSON/SQLite 持久化均有清晰说明（2）。边际价值：将语义上下文引入 HPO 提议是明确差异化点，基准显示上下文条件优于无上下文对照（2），但多数基准改进幅度小（如 Acrobot 仅 +0.2），且多模型数字（GPT-5.5、Opus-4.8 等版本名无法核实）扣分。成本收益：强调小预算杠杆与免费 OpenCode 模型，mock 后端可零成本测试，但 agent CLI 每次提议的真实 token/时间成本未量化（2）。
主张可追溯：基准以 manifest. 与 benchmarks/README 的 'Provenance/Publication gate' 契约固定，复现命令齐全（2）。跨源印证：测试文件强制 README/docs/pyproject/benchmarks 一致，CI 覆盖率门限 85%，但基准结果本身仅限仓库内部工件，无外部独立复现（2）。事实与推断分离：'trajectory illustration' 与 'methodological benchmark' 等限定语使用得当，credit 基准自陈 test 泄漏问题（2）。未执行任何代码，全部为静态判断。
- 本审查为静态源码审查（低置信度），未执行任何代码；基准数字均来自仓库自述工件，未经独立复现。
- 工具以子进程启动已认证的 coding agent CLI，权限继承自运行用户；调优目标为任意本地系统参数时，请自行评估影响范围并避免在包含敏感数据的目录中运行。
- 注意嵌套会话继承 ANTHROPIC_API_KEY 的问题（文档建议 env -u ANTHROPIC_API_KEY），并确保参数 context 不含密钥或私有指令。
- README 中若干语言链接标签存在乱码，暗示文档生成流程可能存在质量问题，使用前请核对多语言文档内容。
- RL 与 credit 基准中的改进幅度很小（如 Acrobot +0.2），且 credit 基准自陈存在验证/测试集选择泄漏，不应据此推断生产环境的实际收益。
- 发布者身份未经企业注册表验证，供应商信任链需用户自行建立。
这个 Agent 能做什么，适合哪些场景？
optim-agent 是一个 Python 库和编码智能体技能，让 Claude Code、Codex 或 OpenCode 充当超参数优化器。它提供 Optuna 风格的 create_study / Study / Trial 接口，核心是 AgentSampler：智能体结合参数的语义说明（context）与试验历史提出下一组配置，库侧负责校验取值是否落在声明空间内，无效回复自动回退到安全采样。目标函数评估始终由用户代码执行，结果可持久化为 JSON 或 SQLite 存储。除 pip 包外，它还能以 Claude Code 插件、Codex 插件和 skill-installer 技能形式安装，让智能体直接读取项目代码后再驱动 study.ask / study.tell 循环。附带 AgentPruner 剪枝、summary 智能体总结、max_concurrency 并发与分布式 SQLite 支持，以及覆盖 Branin/Ackley、MNIST/CIFAR-10、Gymnasium 强化学习和信用违约梯度提升等基准。
在 objective 函数中通过 trial.suggest_float / suggest_int 声明带 context 的参数；AgentSampler（backend 可选 claude / codex / opencode / mock）读取研究级与参数级 context 和最近 history 条试验记录，由智能体提出下一组配置；optim-agent 校验提案、执行用户目标函数、记录 value 与 state 到 study. 或 study.db。可选开启 AgentPruner（loose/medium/tight）按学习曲线决定 prune/keep，summarize=True 让智能体在最后一轮后输出四段式总结并存入 storage。支持 max_concurrency 线程并发与跨进程共享 SQLite（WAL）存储；skill 模式下通过 study.ask(params) / study.tell(trial, value) 让会话内智能体读取项目代码并自行驱动试验。示例含 examples/mnist.py、cifar10.py、hard_functions.py、credit_card.py、rl_control.py 及复现脚本。
- 机器学习工程师在评估昂贵的模型训练上需要小预算（10-20 次试验）高效调参，希望利用参数语义信息而非纯黑盒采样
- 推理/服务团队调整量化、批处理、解码、缓存等部署参数，以在质量、延迟、吞吐和成本间权衡
- 量化研究员优化信号窗口、阈值、调仓规则和风控参数，目标为 walk-forward 收益、回撤和换手率
- 强化学习研究者为 Q-learning 等控制器调整离散化粒度、探索调度和奖励权重等学习循环之外的系统参数
- 科研人员为模拟输入、求解器设置等科学工作流参数寻找比随机或 TPE 更快收敛的方案
- 任何拥有可配置参数和可测量标量目标的黑盒系统负责人
这个 Agent 有哪些优点和局限？
- 语义化提案：智能体结合参数含义与试验历史提值，基准显示带 context 的 GPT-5.5 在 MNIST 上累计误差较 TPE 降低 20.9%，CIFAR-10 上较 Random 降低 20.8%
- 有界执行：智能体只能提值，库侧校验声明空间并对无效回复回退安全采样，目标评估始终权威
- 可审计：JSON/SQLite 保留配置、结果、状态、context 及可选的智能体推理说明，支持断点恢复与分布式共享
- 后端可插拔：claude / codex / opencode / mock 四种后端，底层模型升级即可提升提案质量而无需改优化代码
- 强依赖一个已认证的智能体 CLI（claude/codex/opencode），会产生模型调用成本，且每次提案都是一次智能体调用
- 无 context 时表现可能反而不如基线：基准显示无 context 的 GPT-5.5 在 MNIST 上比 TPE 差 24.3%，需要用户认真编写 context 文本
- OpenCode 目前不支持分布式研究，只能单进程或换后端
- 并发受 GIL 限制，纯 Python CPU 密集目标需多进程加共享 SQLite；并发 worker 看不到彼此进行中的试验点
- 嵌套智能体会话中 claude 可能返回 401，需要 env -u ANTHROPIC_API_KEY 处理
如何安装或部署这个 Agent？
需要 Python 环境且 PATH 上有一个已认证的智能体 CLI（claude、codex 或 opencode）。安装方式任选：pip 包：python -m pip install optim-agent；或从源码安装：python -m pip install "optim-agent @ git+https://github.com/Optim-Agent/optim-agent.git"；Codex 技能：$skill-installer install https://github.com/Optim-Agent/optim-agent；Claude Code 插件：claude plugin marketplace add Optim-Agent/optim-agent && claude plugin install optim-agent@optim-agent。
如何使用这个 Agent？
定义 objective 函数，用 trial.suggest_float("threshold", 0.05, 0.95, context="...") 等声明参数并返回评估值；创建 study = oa.create_study(direction="maximize", sampler=oa.AgentSampler(backend="claude", effort="high", context="...", history=5), storage="study.", summarize=True)；调用 study.optimize(objective, n_trials=20)，之后读取 study.best_value、study.best_params 和 study.summary。剪枝：pruner=oa.AgentPruner(backend="codex", level="medium", effort="medium") 并在循环中 trial.report / trial.should_prune。并发：storage="study.db" 且 max_concurrency=8。离线测试用 AgentSampler(backend="mock")。
这个 Agent 与同类方案有什么区别？
README 以 Optuna 的 Random、TPE 和 GP-BO 为基线进行对比：小预算且有语义 context 时 optim-agent 的智能体采样更优，但无 context 时可能劣于 TPE。optim-agent 明确借鉴了 Optuna 的 Study/Trial 接口设计。