介绍
# Project Orchestrator
通过共享知识库协调多个 AI 编程代理。
## 功能特性
- **多项目支持**：管理具有隔离数据的多个代码库 - **Neo4j 知识图谱**：代码结构、关系、计划和决策 - **Meilisearch**：跨代码和决策的快速语义搜索 - **Tree-sitter**：精确解析 12 种编程语言的代码 - **计划管理**：具有依赖关系和约束的结构化任务 - **MCP 集成**：面向 Claude Code、OpenAI Agents 和 Cursor 的 62 个工具
## 文档
- [安装指南](docs/setup/installation.md) - [入门教程](docs/guides/getting-started.md) - [API 参考](docs/api/reference.md) - [MCP 工具参考](docs/api/mcp-tools.md) - 集成指南：[Claude Code](docs/integrations/claude-code.md) | [OpenAI](docs/integrations/openai.md) | [Cursor](docs/integrations/cursor.md)
## 快速开始
### 1. 启动后端
```bash cd {baseDir} docker compose up -d neo4j meilisearch ```
### 2. 构建并运行编排器
```bash cargo build --release ./target/release/orchestrator serve ```
或使用 Docker： ```bash docker compose up -d ```
### 3. 同步您的代码库
```bash # Via CLI ./target/release/orch sync --path /path/to/project
# Via API curl -X POST http://localhost:8080/api/sync \ -H "Content-Type: application/json" \ -d '{"path": "/path/to/project"}' ```
## 使用方法
### 创建项目
```bash # Create a new project curl -X POST http://localhost:8080/api/projects \ -H "Content-Type: application/json" \ -d '{ "name": "Embryon", "root_path": "/Users/triviere/projects/embryon", "description": "Neural network composition framework" }'
# List all projects curl http://localhost:8080/api/projects
# Sync a project curl -X POST http://localhost:8080/api/projects/embryon/sync
# Search code within a project curl "http://localhost:8080/api/projects/embryon/code/search?q=tensor&limit=10" ```
### 创建计划
```bash orch plan create \ --title "Implement GPU Backend" \ --desc "Add Metal GPU support for neural network operations" \ --priority 10 ```
### 向计划添加任务
```bash orch task add \ --plan <plan-id> \ --desc "Implement MatMul Metal shader"
orch task add \ --plan <plan-id> \ --desc "Add attention layer GPU support" \ --depends <task-1-id> ```
### 获取代理的上下文
```bash # JSON context orch context --plan <plan-id> --task <task-id>
# Ready-to-use prompt orch context --plan <plan-id> --task <task-id> --prompt ```
### 记录决策
```bash orch decision add \ --task <task-id> \ --desc "Use shared memory for tile-based MatMul" \ --rationale "Better cache locality, 2x performance improvement" ```
### 搜索历史决策
```bash orch decision search "memory management GPU" ```
## API 端点
### 项目（多项目支持）
| 方法 | 路径 | 描述 | |--------|------|-------------| | GET | `/api/projects` | 列出所有项目 | | POST | `/api/projects` | 创建新项目 | | GET | `/api/projects/{slug}` | 通过 slug 获取项目 | | DELETE | `/api/projects/{slug}` | 删除项目 | | POST | `/api/projects/{slug}/sync` | 同步项目的代码库 | | GET | `/api/projects/{slug}/plans` | 列出项目的计划 | | GET | `/api/projects/{slug}/code/search` | 搜索项目中的代码 |
### 计划与任务
| 方法 | 路径 | 描述 | |--------|------|-------------| | GET | `/health` | 健康检查 | | GET | `/api/plans` | 列出活动计划 | | POST | `/api/plans` | 创建计划 | | GET | `/api/plans/{id}` | 获取计划详情 | | PATCH | `/api/plans/{id}` | 更新计划状态 | | GET | `/api/plans/{id}/next-task` | 获取下一个可用任务 | | POST | `/api/plans/{id}/tasks` | 向计划添加任务 | | GET | `/api/tasks/{id}` | 获取任务详情 | | PATCH | `/api/tasks/{id}` | 更新任务 | | GET | `/api/plans/{plan}/tasks/{task}/context` | 获取任务上下文 | | GET | `/api/plans/{plan}/tasks/{task}/prompt` | 获取生成的提示词 | | POST | `/api/tasks/{id}/decisions` | 添加决策 | | GET | `/api/decisions/search?q=...` | 搜索决策 |
### 同步与监听
| 方法 | 路径 | 描述 | |--------|------|-------------| | POST | `/api/sync` | 将目录同步到知识库 | | GET | `/api/watch` | 获取文件监听状态 | | POST | `/api/watch` | 开始监听目录 | | DELETE | `/api/watch` | 停止文件监听 | | POST | `/api/wake` | 代理完成回调 Webhook |
### 代码探索（图谱 + 搜索）
| 方法 | 路径 | 描述 | |--------|------|-------------| | GET | `/api/code/search?q=...` | 语义代码搜索 | | GET | `/api/code/symbols/{path}` | 获取文件中的符号 | | GET | `/api/code/references?symbol=...` | 查找符号的所有引用 | | GET | `/api/code/dependencies/{path}` | 获取文件导入/依赖图 | | GET | `/api/code/callgraph?function=...` | 获取函数调用图 | | GET | `/api/code/impact?target=...` | 分析变更影响 | | GET | `/api/code/architecture` | 获取代码库概览 | | POST | `/api/code/similar` | 查找相似代码片段 | | GET | `/api/code/trait-impls?trait_name=...` | 查找实现特定 trait 的类型 | | GET | `/api/code/type-traits?type_name=...` | 查找特定类型实现的 trait | | GET | `/api/code/impl-blocks?type_name=...` | 获取特定类型的所有 impl 块 |
## 文件监听自动同步
在编码时自动更新知识库：
```bash # Start watching a project directory curl -X POST http://localhost:8080/api/watch \ -H "Content-Type: application/json" \ -d '{"path": "/path/to/project"}'
# Check watcher status curl http://localhost:8080/api/watch
# Stop watching curl -X DELETE http://localhost:8080/api/watch ```
监听器会在文件被修改时自动同步 `.rs`, `.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.go` 文件。 它会忽略 `node_modules/`, `target/`, `.git/`, `__pycache__/`, `dist/`, `build/` 目录。
## 代码探索
查询代码图谱而不是直接阅读文件：
```bash # Semantic search across code curl "http://localhost:8080/api/code/search?q=error+handling&language=rust&limit=10"
# Get symbols in a file (functions, structs, etc.) curl "http://localhost:8080/api/code/symbols/src%2Flib.rs"
# Find all references to a symbol curl "http://localhost:8080/api/code/references?symbol=AppState&limit=20"
# Get file dependencies (imports and dependents) curl "http://localhost:8080/api/code/dependencies/src%2Fneo4j%2Fclient.rs"
# Get call graph for a function curl "http://localhost:8080/api/code/callgraph?function=handle_request&depth=2&direction=both"
# Analyze impact before changing a file curl "http://localhost:8080/api/code/impact?target=src/lib.rs&target_type=file"
# Get architecture overview curl "http://localhost:8080/api/code/architecture"
# Find similar code patterns curl -X POST http://localhost:8080/api/code/similar \ -H "Content-Type: application/json" \ -d '{"snippet": "async fn handle_error", "limit": 5}'
# Find all types implementing a trait curl "http://localhost:8080/api/code/trait-impls?trait_name=Module"
# Find all traits implemented by a type curl "http://localhost:8080/api/code/type-traits?type_name=Orchestrator"
# Get all impl blocks for a type curl "http://localhost:8080/api/code/impl-blocks?type_name=Neo4jClient" ```
## 面向代理
### 开始工作前获取上下文
```bash # Fetch your task context curl http://localhost:8080/api/plans/$PLAN_ID/tasks/$TASK_ID/prompt ```
### 工作时记录决策
```bash curl -X POST http://localhost:8080/api/tasks/$TASK_ID/decisions \ -H "Content-Type: application/json" \ -d '{ "description": "Chose X over Y", "rationale": "Because..." }' ```
### 通知完成
```bash curl -X POST http://localhost:8080/api/wake \ -H "Content-Type: application/json" \ -d '{ "task_id": "'$TASK_ID'", "success": true, "summary": "Implemented feature X", "files_modified": ["src/foo.rs", "src/bar.rs"] }' ```
## 配置
环境变量：
| 变量 | 默认值 | 描述 | |----------|---------|-------------| | `NEO4J_URI` | `bolt://localhost:7687` | Neo4j 连接 URI | | `NEO4J_USER` | `neo4j` | Neo4j 用户名 | | `NEO4J_PASSWORD` | `orchestrator123` | Neo4j 密码 | | `MEILISEARCH_URL` | `http://localhost:7700` | Meilisearch URL | | `MEILISEARCH_KEY` | `orchestrator-meili-key-change-me` | Meilisearch API 密钥 | | `WORKSPACE_PATH` | `.` | 默认工作区路径 | | `SERVER_PORT` | `8080` | 服务器端口 | | `RUST_LOG` | `info` | 日志级别 |
## 架构
``` ┌─────────────────────────────────────────────────────────────┐ │ ORCHESTRATOR API │ │ (localhost:8080) │ └─────────────────────────────┬───────────────────────────────┘ │ ┌─────────────────────┼─────────────────────┐ ▼ ▼ ▼ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ NEO4J │ │ MEILISEARCH │ │ TREE-SITTER │ │ (7687) │ │ (7700) │ │ (in-proc) │ │ │ │ │ │ │ │ • Code graph │ │ • Code search │ │ • AST parsing │ │ • Plans │ │ • Decisions │ │ • Symbols │ │ • Decisions │ │ • Logs │ │ • Complexity │ │ • Relations │ │ │ │ │ └───────────────┘ └───────────────┘ └───────────────┘ ```
## 开发
```bash # Run tests cargo test
# Run with debug logging RUST_LOG=debug cargo run -- serve
# Format code cargo fmt
# Lint cargo clippy ```