# Shannon

[English](./README.md) | [中文](./README.zh.md)

本服务部署 [Shannon](https://github.com/Kocoro-lab/Shannon)，一个面向生产环境的多智能体编排框架。Shannon 通过 Temporal 工作流引擎提供时光回溯调试能力、按任务 / 智能体的硬性 Token 预算控制、实时可观测性仪表盘、WASI 沙箱安全代码执行、OPA 策略治理以及多租户隔离，并原生支持 OpenAI、Anthropic、Google、DeepSeek 及本地模型。

> **注意：** `agent-core` 服务仅构建了 `linux/amd64` 镜像。在 Apple Silicon（ARM64）上，Docker Desktop 会自动通过 Rosetta 进行仿真运行。

## 服务说明

- **gateway**：HTTP API 网关 —— 所有客户端请求的主入口（端口 `8080`）
- **orchestrator**：基于 Temporal 的核心工作流编排引擎
- **llm-service**：LLM 提供商抽象层，支持模型路由、故障转移和预算控制
- **agent-core**：基于 Rust 的智能体执行运行时，支持 WASI 沙箱
- **postgres**：带 pgvector 扩展的 PostgreSQL，用于状态和向量存储
- **redis**：Redis，用于缓存、任务队列和限流
- **qdrant**：Qdrant 向量数据库，用于语义记忆
- **temporal**：Temporal 工作流引擎，提供可持久、容错的任务执行
- **temporal-ui**：Temporal Web UI，用于工作流调试（通过 `metrics` profile 启用）

## 快速开始

### 前置条件

- Docker 及 Docker Compose v2
- `curl`（用于下载配置文件）
- 至少一个 LLM API 密钥（OpenAI、Anthropic、Google 等）

### 1. 运行初始化

```bash
make setup
```

该命令会从 Shannon 代码仓库下载所需的 `config/models.yaml` 和 `config/features.yaml` 配置文件，并创建本地 `.env` 文件。

### 2. 填写 LLM API 密钥

编辑 `.env` 文件，至少设置一个 LLM 提供商的密钥：

```env
# 至少选择一个：
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
```

在生产环境中，还需要更新 `JWT_SECRET` 并将 `GATEWAY_SKIP_AUTH` 设为 `0`。

### 3. 启动服务

```bash
make up
```

通过 `http://localhost:8080` 访问 Shannon API。

### 4. （可选）启用 Temporal UI 仪表盘

若需同时启动 Temporal 工作流调试界面：

```bash
make up-monitoring
```

通过 `http://localhost:8088` 访问 Temporal UI。

## 核心环境变量

| 变量名                      | 说明                                      | 默认值                                         |
| --------------------------- | ----------------------------------------- | ---------------------------------------------- |
| `SHANNON_VERSION`           | 所有 Shannon 服务镜像的版本号             | `v0.3.1`                                       |
| `OPENAI_API_KEY`            | OpenAI API 密钥（至少需要一个提供商密钥） | ``                                             |
| `ANTHROPIC_API_KEY`         | Anthropic API 密钥                        | ``                                             |
| `GOOGLE_API_KEY`            | Google AI API 密钥                        | ``                                             |
| `JWT_SECRET`                | JWT Token 签名密钥                        | `development-only-secret-change-in-production` |
| `GATEWAY_SKIP_AUTH`         | 跳过身份验证（生产环境请设为 `0`）        | `1`                                            |
| `GATEWAY_PORT_OVERRIDE`     | API 网关的宿主机端口                      | `8080`                                         |
| `TEMPORAL_UI_PORT_OVERRIDE` | Temporal UI 的宿主机端口                  | `8088`                                         |

## 数据库配置

| 变量名              | 说明                | 默认值       |
| ------------------- | ------------------- | ------------ |
| `POSTGRES_VERSION`  | pgvector 镜像标签   | `pg16`       |
| `POSTGRES_USER`     | PostgreSQL 用户名   | `shannon`    |
| `POSTGRES_PASSWORD` | PostgreSQL 密码     | `shannon`    |
| `POSTGRES_DB`       | PostgreSQL 数据库名 | `shannon`    |
| `REDIS_VERSION`     | Redis 镜像标签      | `7.2-alpine` |
| `QDRANT_VERSION`    | Qdrant 镜像标签     | `v1.17`      |

## 智能体配置

| 变量名                     | 说明                        | 默认值    |
| -------------------------- | --------------------------- | --------- |
| `DEFAULT_MODEL_TIER`       | 默认模型复杂度层级          | `small`   |
| `SHANNON_USE_WASI_SANDBOX` | 启用 WASI 沙箱执行代码      | `1`       |
| `WASI_MEMORY_LIMIT_MB`     | WASI 沙箱内存限制（MB）     | `512`     |
| `WASI_TIMEOUT_SECONDS`     | WASI 沙箱执行超时时间（秒） | `60`      |
| `TEMPORAL_NAMESPACE`       | Temporal 工作流命名空间     | `default` |

## 可观测性（可选）

| 变量名                        | 说明                        | 默认值  |
| ----------------------------- | --------------------------- | ------- |
| `OTEL_ENABLED`                | 启用 OpenTelemetry 链路追踪 | `false` |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP 采集器端点             | ``      |

## 安全说明

- 默认情况下，`GATEWAY_SKIP_AUTH=1` 会禁用 JWT 身份验证，便于本地开发。
- **生产环境**请将 `GATEWAY_SKIP_AUTH` 设为 `0`，并使用强密钥替换 `JWT_SECRET`。
- `.env.example` 中的密码仅供本地开发使用，在部署到共享或公开环境前务必修改。

## 配置文件说明

Shannon 使用 `./config/` 目录下的 YAML 配置文件：

- `config/models.yaml` —— LLM 提供商、模型层级、定价及路由规则
- `config/features.yaml` —— 功能开关、执行模式及工作流设置

这些文件通过 `make setup` 从 Shannon 官方代码仓库下载，可根据需要自定义。

## 开源协议

Shannon 采用 [Apache 2.0 协议](https://github.com/Kocoro-lab/Shannon/blob/main/LICENSE) 开源。