anishgoyal0603/Opti-Stack

# ⚡ Opti-Stack：自主算法审计器 [](https://github.com/anishgoyal0603/Opti-Stack/actions/workflows/ci.yml) [](LICENSE) [](https://www.python.org/downloads/) 一个充当自动化高级主任工程师的多智能体系统： 向其输入一个缓慢或初级的 Python 脚本，它将诊断算法 瓶颈，重写代码，**验证重写后的代码在行为上与原版完全一致**，并在多种合成输入规模下对两个版本进行基准测试。 ## 解决的问题 工程师们经常在时间紧迫的情况下编写或接手正确但运行缓慢的代码——例如本应是哈希查找的嵌套循环，或者本应是 O(N log N) 却被写成了 O(N²) 的扫描操作。手动进行性能分析、诊断并安全地重写这些代码需要真正资深工程师的判断力。Opti-Stack 自动化了整个流程，并且具备大多数“AI 代码优化器”演示所忽略的关键安全特性：**除非能证明重写后的代码产生与原版完全相同的输出，否则它拒绝接受任何更快的重写版本。** ## 架构 ``` ┌─────────────┐ user script → │ Coordinator │ └──────┬──────┘ ┌───────────────┼────────────────────────┬───────────────┐ ▼ ▼ ▼ ▼ ┌─────────┐ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │ Analyst │ │ Normalizer │ │ Optimizer │ │ Verifier │ │ (LLM) │ │ (LLM) │ │ (LLM) │ │ (deter- │ │diagnoses│ │extracts a │ │ rewrites │ │ ministic) │ │bottleneck│ │SCALE var for│ │ code │ │ checks │ └─────────┘ │fair sweeps │ └──────┬──────┘ │stdout match│ └─────────────┘ │ └─────┬──────┘ ▼ │ ┌───────────────┐ │ │ Benchmarker │◄──────┘ │ skill (sand- │ loops back to │ boxed subproc)│ Optimizer with └────────────────┘ failure reason if verification fails (max 3x) ``` **Coordinator** (`opti_stack/orchestrator.py`) 并不是运行一个固定的脚本——它 会进行分支处理：如果 Verifier 拒绝了一次优化尝试，Coordinator 会将失败原因反馈给 Optimizer 智能体，并在有限的重试次数后进行进一步尝试，而不是将未经验证的重写结果作为成功呈现给用户，如果在重试耗尽后依然失败，它会诚实地向用户暴露问题。 ## 展示的课程概念 | 概念 | 位置 | |---|---| | 多智能体系统 | `opti_stack/orchestrator.py` — Analyst、Normalizer、Optimizer 和 Verifier 作为不同的角色，由一个 orchestrator 协调，并根据智能体的输出进行分支控制流 | | 智能体技能 | `.agents/skills/code-benchmarker/` — 一个有文档记录、经过沙箱隔离且有超时限制的能力（`SKILL.md` + `runner.py`），可由智能体系统调用 | | 护栏 / 安全性 | `opti_stack/security_scanner.py` — 基于 AST 的静态扫描会在任何代码执行前拒绝危险的导入/调用（如 os、subprocess、eval 等），此机制同时应用于用户输入和每个由 LLM 生成的重写代码 | | 正确性验证 | Verifier 的确定性 stdout-diff 校验机制（拒绝“虽然快但错误”的重写，而不是接受它们，并支持有限次数的重试） | | 容错能力 | `GeminiClient` 的模型回退链可以处理配额限制、503 错误和弃用的模型 ID，而不会导致整个 pipeline 崩溃 | | 可观测性 | 每一个智能体步骤（输入、输出、验证结论）都会被捕获到结构化的 trace 中，并显示在 UI 的“Full agent trace”面板中 | ## 项目结构 ``` opti-stack-project/ ├── .agents/skills/code-benchmarker/ # the benchmarking skill │ ├── SKILL.md │ └── scripts/runner.py ├── opti_stack/ # core package -- all business logic lives here │ ├── orchestrator.py # coordination/branching logic only │ ├── llm_client.py # Gemini API wrapper + model fallback │ ├── prompts.py # all agent role prompts │ ├── benchmarking.py # subprocess benchmark runner + scale sweep │ ├── verification.py # deterministic correctness checker │ ├── security_scanner.py # AST-based static security gate │ ├── synthetic_data.py # SCALE-variable injection for stress tests │ └── cli.py # CLI entry point ├── ui/ │ └── app.py # Streamlit front-end ├── tests/ # pytest suite ├── requirements.txt └── .env.example ``` `opti_stack/` 中的每个模块都只负责一项工作：`orchestrator.py` 仅决定*执行的顺序和分支方式*——它不需要知道 LLM API 是如何工作的（这部分在 `llm_client.py` 中），不需要知道要对它说什么（`prompts.py`），也不需要知道如何衡量性能（`benchmarking.py`）或如何判断正确性（`verification.py`）。这意味着，例如将 Gemini 替换为另一个模型提供商时，只需要修改 `llm_client.py` 即可。 ## 设置（免费 / 本地） ``` python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt cp .env.example .env # then paste your free Gemini API key into .env ``` 在 [aistudio.google.com](https://aistudio.google.com) 获取免费的 Gemini API key —— 免费层级已足以满足演示需求。 `.env` 会在应用启动的瞬间通过 `python-dotenv` 自动加载 —— 无需手动将变量导出到你的 shell 中。 ## 运行 ``` # Web UI（从 repo 根目录运行） streamlit run ui/app.py # CLI（同样从 repo 根目录作为 module 运行） python -m opti_stack.cli --inline "print('hello world')" python -m opti_stack.cli path/to/script.py ``` ## 测试 ``` pytest tests/ -v ``` ## 已知的局限性（在此诚实说明，绝不隐瞒） - Normalizer 智能体的 SCALE 提取过程本身也是一次 LLM 调用，在遇到不寻常的代码结构时偶尔会失败；规模扫描图表应被视为一种尽力而为的演示增强功能，而非绝对的保证。 - 验证机制仅对比 stdout。对于不打印结果，或者具有 stdout 之外副作用（如文件写入、网络调用）的脚本，目前不会对这些副作用进行验证。 - 沙箱隔离处于进程级别（subprocess + 超时限制），而不是一个完整的容器/VM沙箱 —— 这对于黑客松演示已经足够，但在没有进一步强化的情况下，不适用于不受信任的生产级多租户环境。

标签：Kubernetes, Python, 代码优化, 多智能体, 安全规则引擎, 性能分析, 无后门, 逆向工具