ai-orchestrator

<div align="center"> <img src="docs/img/banner.png" alt="ai-orchestrator" width="100%"> <br><br> **内存、追溯性和成本控制，用于智能代理辅助开发** 根据项目上下文，在 Claude、OpenAI、DeepSeek 和 Gemini 之间路由任务， 并带有实时仪表盘、成本跟踪和 RAG 内存。 <br>       **[github.com/csantisdev/ai-orchestrator](https://github.com/csantisdev/ai-orchestrator)** </div> --- ## 为什么 智能代理（Claude Code、Codex、DeepSeek）为特定任务创造价值，但历史记录分散在单独的会话文件中， 缺乏成本可见性和累计上下文。没有结构化内存，每个会话都从头开始，支出不透明。 ai-orchestrator 在本地集中历史记录：在 ChromaDB 中索引先前响应，根据项目上下文路由每个任务到最有效的模型， 并在 SQLite 中记录每个运行的代币和美元成本。SSE 仪表盘实时显示状态。MCP 服务器公开 11 种工具， 允许任何代理在工作环境中读写历史记录，无需离开。 --- ## 快速开始 **PowerShell** ```powershell # 1. 创建虚拟环境 cd C:\ruta\ai-orchestrator python -m venv .venv .venv\Scripts\activate # 2. 安装依赖 pip install -r requirements.txt pip install -e . # 3. 创建配置文件目录并复制模板 New-Item -ItemType Directory -Force "$env:USERPROFILE\.ai-orchestrator" Copy-Item config.example.yaml "$env:USERPROFILE\.ai-orchestrator\config.yaml" Copy-Item index.example.yaml "$env:USERPROFILE\.ai-orchestrator\index.yaml" # 4. 填写 API 密钥 notepad "$env:USERPROFILE\.ai-orchestrator\config.yaml" ``` **Git Bash** ```bash # 1. 创建虚拟环境 cd /c/ruta/ai-orchestrator python -m venv .venv source .venv/Scripts/activate # 2. 安装依赖 pip install -r requirements.txt pip install -e . # 3. 创建配置文件目录并复制模板 mkdir -p ~/.ai-orchestrator cp config.example.yaml ~/.ai-orchestrator/config.yaml cp index.example.yaml ~/.ai-orchestrator/index.yaml # 4. 填写 API 密钥 notepad ~/.ai-orchestrator/config.yaml ``` > **API 密钥** — 在其平台上获取每个密钥并粘贴到 `config.yaml`： > | 提供商 | 平台 | 必需 | > |---|---|---| > | Claude (Anthropic) | https://console.anthropic.com → API Keys | 是（目标提供商） | > | DeepSeek | https://platform.deepseek.com → API Keys | 是（路由器） | > | OpenAI | https://platform.openai.com → API keys | 可选 | > | Gemini (Google) | https://aistudio.google.com/apikey | 可选 | > > 最小功能是 **DeepSeek** （路由器）+ **Claude** （目标提供商）。参见 [`docs/api-keys.md`](docs/api-keys.md) 中的详细指南。 ```bash # 5. 验证安装 ai-orchestrator --help # 6. 注册您的第一个项目并启动仪表盘 ai-orchestrator add mi-proyecto --path "C:\ruta\al\proyecto" ai-orchestrator serve # 打开 http://127.0.0.1:8080 ``` --- ## 范围 | 能力 | 描述 | |---|---| | **智能路由** | DeepSeek Flash 分析任务和项目 `context.yaml` 以决定使用哪个模型 — 无硬编码 | | **成本控制** | 输入、输出和缓存代币按次运行。美元成本使用可配置的价格表计算 | | **RAG 内存** | ChromaDB 按项目索引文档和先前响应。每个任务在调用模型之前检索相关语义上下文（阈值 L2=0.9 ≈ cosine_sim≥0.60） | | **实时仪表盘** | 带有 SSE 的网页面板 — 行实时出现，无需刷新。预算表、过滤器和详细信息面板 | | **数据库检查器** | ChromaDB（集合 + 项目分解）和 SQLite（计数 + 最新记录）的内部视图 | | **上下文和步骤** | 带对齐检查点和工具调用记录的多步骤结构化流程 | | **活动栏** | 实时跨度：路由器 → RAG → API → 索引。运行期间每个操作的持续时间可见 | | **Claude Code 同步** | 从 `~/.claude/projects/` 导入会话。自动通过 `Stop` 钩子执行 | | **Codex 同步** | 从 OpenAI Codex CLI (`~/.codex/state_N.sqlite`) 导入会话，包括代币、成本和完整响应 | | **医生/修复** | `doctor` 诊断完整状态，分为 4 个部分（配置、MCP Claude/Codex、项目、数据库）。`fix` 应用自动更正：创建 `.mcp.json`、`.codex/config.toml`、`context.yaml`、注册全局 MCP、同步和索引 | | **操作菜单** | 仪表盘活动栏中的 `doctor`、`fix`、`sync`、`index` 按钮。实时在活动日志中执行与 CLI 相同操作的结果 | **超出范围：** 它不是 API 代理（进程本地运行），不并行编排代理，不维护运行之间的对话历史。 --- ## MCP 插件 MCP 服务器公开 11 种工具，兼容代理（Claude Code、Cursor、Codex、Gemini Code Assist 等）可以直接调用，无需使用 CLI： | 工具 | 目的 | |---|---| | `get_context` | 返回项目的活动上下文目标和状态 | | `list_steps` | 列出上下文的有序步骤及其状态 | | `confirm_alignment` | 在重大操作前注册检查点 | | `record_tool_calls` | 注册步骤期间调用的每个工具 | | `advance_step` | 将当前步骤标记为完成并激活下一个步骤 | | `skip_step` | 将步骤标记为跳过而无需执行 | | `create_context` | 创建具有可选步骤的新工作上下文 | | `add_step` | 在现有上下文中添加步骤 | | `update_context` | 编辑上下文的标题、描述或状态 | | `update_step` | 编辑步骤的标题、描述或备注 | | `import_agent_context` | 将外部代理的工作导入历史记录 + ChromaDB | 自动安装：`ai-orchestrator fix` 生成 `.mcp.json`，在 `.codex/config.toml` 中注册 Codex，在 `~/.gemini/settings.json` 中注册 Gemini。对于全局 Claude，请使用 `ai-orchestrator fix --global-mcp`。 --- ## 设计 ### 架构 ``` CLI / HTTP 服务器 cli.py · Typer + BaseHTTPRequestHandler │ ├── 路由器 router.py │ 分析任务 + context.yaml + keyword_hints │ 调用 DeepSeek Flash 决定提供商 │ 如果有活动上下文，则强制执行 step.provider │ ├── RAG rag.py · ChromaDB / FTS5 备用 │ retrieve_docs() — 项目文档块 │ retrieve_responses() — 相似的先前响应 │ ├── 提供商 providers/ │ claude.py → Anthropic API │ openai.py → OpenAI API │ deepseek.py → DeepSeek API │ gemini.py → Google Generative Language API │ ├── 数据库 db.py · SQLite WAL │ runs, contexts, steps, chunks, alignments, tool_calls │ ├── SSE 总线 sse.py │ 事件：run_started · run_done · run_failed · trace · budget_warning │ └── 仪表盘 dashboard.py · HTML 服务端 + JS 原生 ``` ### 任务流程 ``` 仪表盘/CLI → submit_run() → 路由器 → RAG 检索 ↓ 仪表盘 ← SSE ← 数据库更新 ← 提供商 API → 响应索引 ``` ### 目录 ``` C:\ruta\ai-orchestrator\ ← 仓库 ├── orchestrator\ │ ├── cli.py ← HTTP 服务器 + Typer 命令 │ ├── router.py ← 提供商决策 │ ├── db.py ← SQLite WAL + 迁移 │ ├── rag.py ← ChromaDB / FTS5 备用 │ ├── tracer.py ← SSE 总线跨度 │ ├── background.py ← 工作线程 │ ├── dashboard.py ← 网页 HTML │ ├── sse.py ← 服务器发送事件 │ ├── codex_watcher.py ← Codex CLI 会话导入器 │ └── providers\ ← claude · openai · deepseek · gemini └── docs\ ├── index.html ← 完整文档 /docs └── img\ ← 横幅、徽标、图标 ~\.ai-orchestrator\ ← 运行时（不版本控制） ├── config.yaml ← API 密钥、模型、定价 ├── index.yaml ← 别名 → 每个项目的路径 ├── runs.db ← SQLite 历史记录 └── chroma\ ← 向量索引 mi-proyecto\ ← 每个仓库版本 └── .orchestrator\ └── context.yaml ← 堆栈、约定、路由规则 ``` ### SQLite 数据库 | 表 | 内容 | |---|---| | `runs` | 每次调用提供商。代币、美元成本、持续时间、完整响应 | | `contexts` | 多步骤工作流（标题、描述、状态） | | `steps` | 上下文步骤。建议提供商、顺序、状态 | | `chunks` | RAG 索引文档（项目、路径、块数） | | `alignments` | 代理确认的对齐检查点 | | `tool_calls` | 步骤期间调用的工具（名称、输入、输出、持续时间） | --- ## 工具 ### 项目管理 ```powershell ai-orchestrator add mi-proyecto --path "C:\ruta\al\proyecto" ai-orchestrator list ai-orchestrator remove mi-proyecto ai-orchestrator rename mi-proyecto nuevo-alias # 在索引和历史记录中重命名别名 ``` ### 执行任务 ```powershell # 路由器自动决定提供商 ai-orchestrator run --project mi-proyecto --task "检查登录端点" # 强制提供商 ai-orchestrator run --project mi-proyecto --task "..." --model claude # 研究模式（Claude Opus） ai-orchestrator run --project mi-proyecto --task "..." --research ``` ### 网页仪表盘 ```powershell ai-orchestrator serve # http://127.0.0.1:8080 ai-orchestrator serve --port 9090 --no-open ``` 仪表盘有两个选项卡： - **仪表盘** — 实时运行表格、新任务表单、详细信息面板、预算表、活动栏和跨度 - **检查器** — ChromaDB 和 SQLite 的内部状态、项目注册表和原生文件夹选择器 > **USD/CLP 汇率（可选）：** 仪表盘包括一个面板，通过 Chile 中央银行的 API （`si3.bcentral.cl`）查询汇率。这是一个可选的 Chile 特有功能 — 需要免费凭证。Chile 以外的用户可以忽略它；仪表盘的其他部分无需配置即可使用。 完整文档位于 **`http://127.0.0.1:8080/docs`** 一旦服务器启动。 ### RAG 索引 ```powershell ai-orchestrator index-docs mi-proyecto ai-orchestrator index-docs mi-proyecto --exclude "vendor,storage,public/build" # 排除文件夹 ai-orchestrator index-docs mi-proyecto --exclude "vendor" --save # 在 context.yaml 中保存排除项 ``` > 无 IA 成本 — 使用本地嵌入 (`all-MiniLM-L6-v2`)。也可在仪表盘检查器中使用。 > 重新索引始终是安全的：upsert 使用确定性 ID (`项目::路径::块索引`)，不会累积重复项。 **RAG 参数配置在 `rag.py`： | 参数 | 值 | 描述 | |---|---|---| | `_CHUNK_SIZE` | 1500 | 块大小（字符） | | `_CHUNK_OVERLAP` | 200 | 块重叠 | | `_DISTANCE_THRESHOLD` | 0.9 | L2 阈值（≈ cosine_sim≥0.60）。越低越宽容 | | `_MAX_FILE_BYTES` | 100,000 | 要索引的最大文件大小 | | `_MAX_PY_FILES` | 30 | 项目中 `.py` 文件的最大数量 | 索引扩展名：`.md` `.txt` `.yaml` `.yml` `.toml` `.rst` `.json`（文档）+ `.py`（代码，最多 30 个文件）。 始终排除的目录：`.venv` `venv` `__pycache__` `.git` `node_modules` `vendor` `build` `dist` `.claude` `.codex` `.aws` `.ssh`. 基于堆栈的自动排除（从 `context.yaml` 检测）： | 堆栈 | 建议的文件夹 | |---|---| | `laravel` / `php` | `vendor` `storage` `bootstrap` | | `node` / `react` | `node_modules` `dist` `.next` `build` | | `python` | `.venv` `venv` `__pycache__` `dist` `build` | | `go` | `vendor` | | `ruby` | `vendor` `tmp` `log` | ### 历史记录 ```powershell ai-orchestrator history ai-orchestrator history --project mi-proyecto --last 50 ``` ### 上下文和步骤 ```powershell ai-orchestrator create-context mi-proyecto "实现认证** | | | `keyword_hints` | | ---|---| | ---|---| | ---|---| | ---|---| | ---|---| ### 诊断和自动修复 ```powershell # 检查完整状态 ai-orchestrator doctor ai-orchestrator doctor --verbose # 显示路径、模型和块计数 ai-orchestrator doctor -p mi-proyecto # 限制为特定项目 # 应用自动更正 ai-orchestrator fix # 创建缺少的 `.mcp.json`、`.codex/config.toml` 和 `context.yaml` ai-orchestrator fix --global-mcp # + 注册全局 MCP ai-orchestrator fix --sync # + 导入 Claude Code 会话和 Git 提交 ai-orchestrator fix --index # + 将项目编入 ChromaDB ai-orchestrator fix --all # 一次应用所有上述改进 `doctor` 检查四个部分并为每个项目显示 ✓ / ⚠ / ✗： | 部分 | 检查内容 | |---|---| | **环境** | Python 版本、活跃 `.venv` | | **全局配置** | 可加载 `config.yaml`、三个提供商的 API 密钥、`index.yaml`、`runs.db`、ChromaDB | | **MCP / Claude Code / Codex** | 项目中的 `.mcp.json`、`codex/config.toml`、全局 MCP 中的 `~/.claude/settings.json` | | **项目** | 路径存在、生成的 `context.yaml`、编入 ChromaDB | `fix` 按确定顺序应用改进：`.mcp.json` → `.codex/config.toml` → `context.yaml` → 全局 MCP → 同步 → 索引。自动跳过已就绪的内容，并报告每个采取的行动。 > **仪表盘：** `doctor`、`fix`、`sync` 和 `index` 也可在仪表盘的**活动栏**（底部栏）作为按钮使用。实时在日志中显示结果，无需刷新页面。 ### 导入外部代理的工作 ```powershell # 将另一个代理执行的工作注册到历史记录中 ai-orchestrator import-context mi-proyecto \ --task "检查查询性能" \ --response "检测到 3 个 N+1 查询问题..." \ --agent deepseek --model deepseek-v4-flash # 清除项目/提供商导入的运行记录 ai-orchestrator clear-imports mi-proyecto ai-orchestrator clear-imports mi-proyecto --provider deepseek ``` ### 同步 Claude Code 和 Codex 会话 ```powershell # 导入 Claude Code 会话（~/.claude/projects/） ai-orchestrator sync-cc # 导入新会话 ai-orchestrator sync-cc --quiet # 用于钩子 # 导入 OpenAI Codex CLI 会话（~/.codex/state_N.sqlite） ai-orchestrator sync-codex ai-orchestrator sync-codex --quiet ``` **与 Claude Code 自动集成** — 添加到 `~/.claude/settings.json`: ```json { "hooks": { "Stop": [{ "matcher": "", "hooks": [{ "type": "command", "command": "C:\\Fuentes\\ai-orchestrator\\.venv\\Scripts\\ai-orchestrator.exe sync-cc --quiet" }] }] } } ``` --- ## 配置 ### `~/.ai-orchestrator/config.yaml` ```yaml providers: claude: api_key: "sk-ant-..." model: "claude-sonnet-4-6" openai: api_key: "sk-..." model: "gpt-4o" deepseek: api_key: "sk-..." model: "deepseek-v4-flash" gemini: api_key: "AIza..." model: "gemini-2.5-flash" router: provider: "deepseek" fallback_provider: "claude" defaults: default_provider: "claude" pricing: claude-sonnet-4-6: input: 3.00 output: 15.00 cache_write: 3.75 cache_read: 0.30 deepseek-v4-flash: input: 0.14 output: 0.28 gemini-2.5-flash: input: 0.30 output: 2.50 gemini-2.5-pro: input: 1.25 output: 10.00 budgets: default_daily_budget_usd: 5.00 warning_threshold: 0.80 ``` > `config.yaml` 位于 `~/.ai-orchestrator/` 且**从不版本控制**。参见 [`config.example.yaml`](config.example.yaml) 获取完整模板，[`docs/api-keys.md`](docs/api-keys.md) 获取每个 API 密钥。 ### `.orchestrator/context.yaml`（每个项目） ```yaml name: mi-proyecto stack: PHP/Laravel description: 带身份验证和角色的 Web 应用程序 # 项目每日支出限额（美元），覆盖默认配置 daily_budget_usd: 2.00 conventions: - 表单请求进行验证 - PSR-12 preferred_models: default: claude notes: > 身份验证和权限交给 Claude。 测试和 seeder 可以交给 DeepSeek。 前端重构交给 OpenAI。 # 影响路由器决策的关键词提示（权重 1-5） keyword_hints: - { match: "安全", provider: claude, weight: 3 } - { match: "测试", provider: deepseek, weight: 2 } - { match: "重构", provider: openai, weight: 1 } ``` 参见 [`docs/context-schema.md`](docs/context-schema.md) 获取完整模式。 --- ## 可用模型 | 提供商 | 模型 | 输入/1M | 输出/1M | 推荐用途 | |---|---|---|---|---| | `claude` | `claude-sonnet-4-6` | $3.00 | $15.00 | 一般任务 — 默认模型 | | `claude` | `claude-opus-4-8` | $15.00 | $75.00 | 深入研究 (`--research`) | | `claude` | `claude-haiku-4-5-20251001` | $0.80 | $4.00 | 简单且经济的任务 | | `openai` | `gpt-4o` | $5.00 | $15.00 | Claude 替代方案 | | `openai` | `gpt-4o-mini` | $0.15 | $0.60 | OpenAI 经济型任务 | | `deepseek` | `deepseek-chat` | $0.14 | $0.28 | 路由器 / 草稿 / 大规模任务 | | `deepseek` | `deepseek-v4-flash` | $0.14 | $0.28 | 路由器默认模型 | | `gemini` | `gemini-2.5-flash` | $0.30 | $2.50 | 长上下文，一般任务 | | `gemini` | `gemini-2.5-pro` | $1.25 | $10.00 | 复杂分析（需要计费） | | `gemini` | `gemini-2.5-flash-lite` | $0.10 | $0.40 | 非常经济的任务 | > 价格以美元计，每百万个 tokens。Claude 模型支持缓存写入/读取（参见 `config.yaml` 中的 `pricing`）。 > `gemini-2.5-pro` 需要在 Google Cloud 上启用计费 — 免费层额度为 0。使用 `gemini-2.5-flash` 适用于无计费账户。 --- ## 故障排除 | 问题 | 原因 | 解决方案 | |---|---|---| | `ProjectNotFoundError: alias 'X' 未注册` | 别名在索引中不存在 | `ai-orchestrator add X --path "C:\ruta"` | | `ChromaDB 未初始化` | 权限或目录缺失 | 检查 `~/.ai-orchestrator/chroma/` 的写入权限 | | `API 密钥无效` | 密钥不正确或已过期 | 检查 `config.yaml`，在平台上重新生成密钥 | | 使用 Gemini 时出现 `429 Too Many Requests` | `gemini-2.5-pro` 的免费层额度已用完 | 使用 `gemini-2.5-flash`（有免费额度）或在 Google Cloud 上启用计费 | | `ModuleNotFoundError: chromadb` | ChromaDB 未安装 | `pip install chromadb` — 如果没有它，RAG 将使用 FTS5 作为备用 | | 来自 Codex 的 MCP 上下文中的乱码（Windows） | `sys.stdin` 继承编码 `cp1252` | 已修复：服务器启动时强制使用 `utf-8`。历史数据：使用 `update_context` / `update_step` 修复 | | 活动面板自动打开 | 首次跟踪时的预期行为 | 手动折叠 — 状态将为后续会话保留 | | `doctor` 显示 ChromaDB ✗ | ChromaDB 未初始化或集合为空 | 为每个项目运行 `ai-orchestrator index-docs <alias>` | --- ## 安装 参阅本文开头的 [快速入门](#quick-start) 指南。 `requirements.txt` 已包含 ChromaDB。如果没有它，路由器将自动使用 FTS5（SQLite 全文搜索）作为备用；启用它后，语义搜索可用。 **VS Code:** `Ctrl+Shift+P` → 任务：运行任务 → **Orchestrator: 仪表盘** --- ## 本地安全 编排器永远不会将项目数据发送到外部服务器，除了将提示文本发送到所选提供商（Claude、OpenAI、DeepSeek）。 RAG 索引器自动排除： - **按文件名：** `.env`、`credentials.json`、`id_rsa`、`secrets.yaml`、`.npmrc`、`auth.json`、`terraform.tfvars` 等 - **按扩展名：** `.pem`、`.key`、`.p12`、`.pfx`、`.cer`、`.crt`、`.tfstate`、`.tfvars` - **按目录：** `.aws`、`.ssh`、`.kube`、`.gcloud`、`.claude`、`.codex` - **按内容：** API 密钥模式（Anthropic `sk-ant-...`、OpenAI `sk-proj-...`、MercadoPago）和 PEM 私钥块 HTTP 仪表盘仅监听 `127.0.0.1`（环回地址）。由于服务器无法从本地网络或互联网访问，因此没有身份验证。 --- <div align="center"> MIT 许可证 </div>