前置要求
在安装 Shannon 之前，请确保您具备：
- Docker (20.10+) 和 Docker Compose (v2.0+)
- Git 用于克隆仓库
- LLM API 密钥（OpenAI、Anthropic 或其他支持的提供商）
- 至少 4GB RAM 可用于 Docker
Shannon 可在 Linux、macOS 和 Windows（使用 WSL2）上运行。所有示例均假定类 Unix 环境。
一键设置
Shannon 提供简化的设置流程，让您在几分钟内运行：
# 克隆仓库
git clone https://github.com/Kocoro-lab/Shannon.git
cd Shannon
# 初始化配置并生成 protocol buffers
make setup
提示：make setup 是一站式设置（创建 .env 并生成 protobufs）。如果只需要环境文件，请使用 make setup-env。您也可以随时使用 make proto 重新生成 protobufs。
# 添加您的 LLM API 密钥
echo "OPENAI_API_KEY=sk-your-key-here" >> .env
# 下载 Python WASI 解释器（沙箱执行所需）
./scripts/setup_python_wasi.sh
# 启动所有服务
make dev
安装的内容
make dev 命令通过 Docker Compose 启动以下服务：
| 服务 | 端口 | 描述 |
|---|
| Gateway | 8080 | REST API 网关 |
| Orchestrator | 50052 | gRPC 编排服务 |
| Agent Core | 50051 | 基于 Rust 的智能体执行 |
| LLM Service | 8000 | Python LLM 提供商网关 |
| Playwright Service | 8002 | 浏览器自动化服务 |
| PostgreSQL | 5432 | 持久化存储 |
| Redis | 6379 | 缓存和发布/订阅 |
| Qdrant | 6333 | 向量数据库 |
| Temporal | 7233 | 工作流引擎 |
| Temporal UI | 8088 | 工作流可视化 |
验证安装
检查所有服务是否正在运行：
# 查看服务状态
docker compose ps
# 所有服务应显示 "healthy" 或 "running"
# 提交一个简单的任务
curl -X POST http://localhost:8080/api/v1/tasks \
-H "Content-Type: application/json" \
-d '{
"query": "2+2 等于多少？"
}'
# 您应该收到包含 task_id 的响应
访问界面
在浏览器和桌面应用中查看：
Shannon 已针对本地开发进行了预配置，但您可以自定义它：
环境变量
.env 文件（由 make setup 创建）包含关键配置：
# LLM 提供商密钥
OPENAI_API_KEY=sk-your-key-here
ANTHROPIC_API_KEY=sk-ant-your-key-here
# 服务配置
GATEWAY_SKIP_AUTH=1 # 开发环境禁用身份验证
LOG_LEVEL=info
# 数据库
POSTGRES_USER=shannon
POSTGRES_PASSWORD=shannon_dev
POSTGRES_DB=shannon
# Redis
REDIS_URL=redis://redis:6379
在生产环境中，设置 GATEWAY_SKIP_AUTH=0 以启用 API 密钥身份验证。
配置文件
高级配置可在 config/ 目录中找到：
shannon.yaml - 主系统配置features.yaml - 功能标志models.yaml - LLM 提供商定价和路由
常见问题
如果您看到端口绑定错误，请检查端口 8080、50051、50052、8000 等是否未被使用：# macOS/Linux
lsof -i :8080
# 停止冲突的服务或在 docker-compose.yml 中更改端口
Shannon 至少需要 4GB RAM。增加 Docker 的内存限制：
- Docker Desktop: 设置 → 资源 → 内存（设置为 6GB+）
- Linux: Docker 默认使用所有可用内存
如果 setup_python_wasi.sh 失败，手动下载：mkdir -p wasm-interpreters
cd wasm-interpreters
wget https://github.com/vmware-labs/webassembly-language-runtimes/releases/download/python%2F3.11.4%2B20230714-11be424/python-3.11.4.wasm
检查 Docker 日志以查找错误：docker compose logs orchestrator
docker compose logs agent-core
docker compose logs llm-service
- 缺少
.env 文件（运行 make setup）
- 无效的 API 密钥
- Docker 资源不足
下一步
现在 Shannon 已经运行：
开发设置
通过 Docker 运行核心依赖项，然后在本地运行服务以进行迭代：
# 终端 1: 仅启动依赖项（DB、缓存、向量、Temporal）
docker compose -f deploy/compose/docker-compose.yml up -d postgres redis qdrant temporal
# 终端 2: 本地运行 Orchestrator（gRPC 50052，管理端口 8081）
cd go/orchestrator
go run ./cmd/server
# 终端 3: 本地运行 Agent Core（gRPC 50051）
cd ../../rust/agent-core
cargo run
# 终端 4: 本地运行 LLM Service（HTTP 8000）
cd ../../python/llm-service
pip install -r requirements.txt
python main.py
# （可选）终端 5: 本地运行 Gateway（REST 8080）
cd ../../go/orchestrator/cmd/gateway
go run .
