内容
# 潘特翁
潘特翁是一个本地的AI编码代理仪表板，拥有一个共享的项目大脑。
它是一个本地优先的控制平面，用于基于终端的编码代理，如Hermes、Claude Code、Codex风格的CLI、Gemini CLI、Aider和未来的非MCP代理。潘特翁在本地存储工作空间、任务、记忆、日志和索引的项目上下文。它不需要新的AI API密钥。
## 当前状态
潘特翁是一个开源的本地编排构建。它在没有托管服务或提供商API密钥的情况下运行；安装的编码代理仍然是可选的集成。
已实现：
- 默认绑定到`127.0.0.1`的FastAPI后端。
- React/Vite/TypeScript仪表板。
- 通过SQLAlchemy进行SQLite存储。
- Hermes、Claude Code、Codex CLI、Gemini CLI、Aider、OpenCode和OpenClaw检测适配器。
- 连接的MCP代理，包括Codex桌面版、OpenCode、OpenClaw和通用MCP客户端。
- 模拟本地代理，即使没有安装外部代理也能正常工作。
- 本地子进程终端后端，因此不需要tmux和WSL。
- Linux用户可选的tmux后端。
- 具有生命周期状态、heartbeat检查、恢复协调、持久化有界日志和审计事件的代理运行时会话。
- 代理角色/能力配置文件和可选的每个工作空间的权限层次结构。默认情况下为扁平模式：每个代理直接向潘特翁编排器报告。
- 通过MCP进行实时代理连接注册，包含heartbeat、任务认领、进度、委派和完成。
- 工作空间创建、任务队列、任务依赖、任务分解、任务运行、审批门控、取消/失败/重试状态、内存CRUD/搜索、文件索引和活动日志。
- WebSocket终端日志流。
- 代理状态、编排队列/时间线、审批、运行时日志、审计事件、RAG搜索、图内存、设置检查、备份/导出和工作空间健康状况的操作仪表板。
- MCP服务器，暴露共享上下文、任务、内存、工作空间和代理状态工具。
- 具有轮询回落的本地上下文摄取、块状处理、嵌入作业记录、SQLite关键字检索（带引用）和可选的向量后端扩展点。
- 具有确定性实体提取、节点去重、内存/实体边和图遍历搜索的图内存。
- 具有命令策略检查、工作空间边界检查、机密编辑和结构化审计记录的安全层。
- 本地元数据备份/导出。
本地v1版本中未包含：
- 用户身份验证和多用户访问控制（潘特翁仍然仅限localhost访问）。
- 云同步。
- 多机器联网。
- 代理市场。
- 云/团队编排。
- 身份验证、角色和远程服务器部署。
- 需要云或向量服务。基线保持依赖项自由。
- 丰富的视觉图画布。当前图浏览器为操作/列表型。
- 使用默认进程后端时，终端会话在后端重启后不会持续。
## 快速开始
启动器引导一个本地虚拟环境并启动捆绑的仪表板：
```powershell
cd D:\projects\pantheon
.\start.cmd
```
打开：
- 仪表板和API：`http://127.0.0.1:8765`
启动器从`frontend/dist`提供内置仪表板，启动FastAPI后端，并使用默认的本地进程后端。潘特翁不需要WSL或tmux。内置模拟代理可用于 onboarding；真正的代理仍然是用户安装的可选集成。
## 全新设置
对于全新克隆（推荐使用启动器）：
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
cd frontend
npm install
npm run build
cd ..
./start.sh
```
在Windows PowerShell上：
```powershell
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r backend\requirements.txt
cd frontend
npm install
npm run build
cd ..
.\start.cmd
```
## 开发
后端：
```bash
cd backend
PYTHONPATH=. pytest
uvicorn app.main:app --host 127.0.0.1 --port 8765
```
前端：
```bash
cd frontend
npm run dev
npm run build
```
烟雾检查：
```bash
PYTHONPATH="$PWD/backend" python scripts/check_api_flow.py
```
## 架构
- `backend/app/agents`：适配器接口和Hermes、Claude Code和模拟CLI适配器。
- `backend/app/terminal`：本地进程后端加上可选的tmux后端。
- `backend/app/runtime`：持久化代理会话、任务运行、日志、恢复和设置检查服务。
- `backend/app/orchestration`：任务分解、依赖、审批、分配策略、卡住运行检测和时间线。
- `backend/app/context`：RAG摄取/搜索和图内存。
- `backend/app/safety`：命令策略、工作空间边界检查、机密编辑和审计事件。
- `backend/app/backup`：本地元数据导出。
- `backend/app/database`：SQLite初始化和SQLAlchemy模型。
- `backend/app/workspaces`：工作空间路径验证、文件索引和监控。
- `backend/app/memory`：共享本地内存CRUD和关键字搜索。
- `backend/app/mcp_server`：MCP服务器和工具函数。
- `backend/app/main.py`：FastAPI REST API和WebSocket日志流。
- `frontend/src`：仪表板UI。
- `scripts/run_local.py`：启动器使用的本地启动器。
## API概述
- `GET /health`
- `POST /agents/detect`
- `GET /agents`
- `GET /agents/connections`
- `POST /agents/connections`
- `POST /agents/connections/heartbeat`
- `POST /agents/connections/disconnect`
- `POST /agents/{agent_id}/start`
- `POST /agents/{agent_id}/stop?workspace_id=...`
- `GET /agents/{agent_id}/status?workspace_id=...`
- `POST /agents/{agent_id}/message?workspace_id=...`
- `GET /agent-connections/{connection_id}/tasks`
- `POST /agent-connections/{connection_id}/tasks/{run_id}/claim`
- `POST /agent-connections/{connection_id}/runs/{run_id}/progress`
- `GET /agents/{agent_id}/logs?workspace_id=...`
- `WS /ws/agents/{agent_id}/logs?workspace_id=...`
- `POST /workspaces`
- `GET /workspaces`
- `POST /workspaces/{workspace_id}/index`
- `POST /tasks`
- `GET /tasks`
- `PATCH /tasks/{task_id}`
- `POST /tasks/{task_id}/queue`
- `POST /tasks/dispatch`
- `POST /tasks/{task_id}/retry`
- `GET /task-runs`
- `PATCH /task-runs/{run_id}`
- `POST /orchestration/decompose`
- `POST /orchestration/dependencies`
- `GET /orchestration/timeline`
- `POST /orchestration/stuck`
- `GET /approvals`
- `POST /approvals/{gate_id}`
- `POST /memories`
- `GET /memories`
- `GET /memories/search?q=...`
- `PATCH /memories/{memory_id}`
- `DELETE /memories/{memory_id}`
- `GET /runtime/sessions`
- `POST /runtime/recover`
- `GET /runtime/logs?q=...`
- `GET /audit`
- `GET /setup/status`
- `GET /workspaces/{workspace_id}/agent-graph`
- `PATCH /workspaces/{workspace_id}/agent-graph`
- `PUT /workspaces/{workspace_id}/agents/{agent_id}/parent`
- `POST /context/documents`
- `GET /context/retrieve?workspace_id=...&q=...`
- `GET /context/graph/{workspace_id}`
- `GET /context/graph/{workspace_id}/search?q=...`
- `POST /backup/export`
- `GET /mcp` （MCP传输信息；当前SDK公开了挂载的MCP端点）
## MCP设置示例
不要自动覆盖真正的代理配置。在查看路径后手动添加类似的块。
Codex桌面版、OpenCode、OpenClaw和其他MCP客户端可以通过本地MCP端点连接到潘特翁。设置页面显示了确切的URL和为选定客户端生成的配置。
Stdio示例：
```json
{
"mcpServers": {
"pantheon": {
"command": "/path/to/pantheon/.venv/bin/python",
"args": ["-m", "app.mcp_server.server"],
"env": {
"PYTHONPATH": "/path/to/pantheon/backend",
"PANTHEON_DATABASE_URL": "sqlite:////path/to/pantheon/data/pantheon.db"
}
}
}
}
```
对于Codex桌面版，请在MCP设置中添加本地潘特翁服务器并重启客户端。连接的客户端调用`connect_agent`、`heartbeat_agent`、`list_available_tasks`、`claim_task`、`report_task_progress`和`complete_run`。
OpenCode支持在`opencode.jsonc`中进行本地MCP条目：
```json
{
"mcp": {
"pantheon": {
"type": "local",
"command": ["python", "-m", "app.mcp_server.server"],
"environment": {"PYTHONPATH": "/path/to/pantheon/backend"}
}
}
}
```
OpenClaw可以通过其MCP配置注册相同的本地服务器或使用`openclaw mcp serve`公开其自己的网关以进行潘特翁的网关连接模式。
## 配置
潘特翁读取带有`PANTHEON_`前缀的环境变量：
- `PANTHEON_HOST`
- `PANTHEON_PORT`
- `PANTHEON_DATABASE_URL`
- `PANTHEON_DATA_DIR`
- `PANTHEON_MANAGED_WORKSPACE_ROOT`
- `PANTHEON_TERMINAL_BACKEND`
使用`PANTHEON_TERMINAL_BACKEND=process`表示默认的无tmux模式。只有当tmux已安装并且您想要tmux管理的会话时，才使用`tmux`。
## GitHub注释
不要提交本地运行时文件夹或已安装的依赖项。包含的`.gitignore`排除：
- `.test-python/`
- `.venv/`
- `frontend/node_modules/`
- SQLite数据库
- 日志
- `.env`
- 缓存
## 许可证
MIT
