### 服务端口

| 服务 | 端口 | 端点 | 用途 |
|------|------|------|------|
| **Gateway** | 8080 | `http://localhost:8080` | REST API，OpenAI 兼容 `/v1` |
| **Admin/Events** | 8081 | `http://localhost:8081` | SSE/WebSocket 流，健康检查 |
| **Orchestrator** | 50052 | `localhost:50052` | gRPC（内部） |
| **Temporal UI** | 8088 | `http://localhost:8088` | 工作流调试 |
| **Grafana** | 3030 | `http://localhost:3030` | 指标仪表盘 |

---

## 快速开始

### 环境要求

- **Docker 和 Docker Compose**
- **至少一个 LLM 提供商的 API Key**（OpenAI、Anthropic 等）

### 一键安装

```bash
curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/v0.3.1/scripts/install.sh | bash
```textbash
cd ~/shannon     # 或你的安装目录
nano .env        # 编辑 API Key
docker compose -f docker-compose.release.yml down
docker compose -f docker-compose.release.yml up -d
```textbash
# 检查所有服务状态
docker compose -f deploy/compose/docker-compose.release.yml ps

# Gateway 健康检查
curl http://localhost:8080/health

# Admin 健康检查
curl http://localhost:8081/health
```textbash
# 提交任务
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the capital of France?",
    "session_id": "demo-session"
  }'

# 响应：{"task_id":"task-dev-123","status":"running"}

# 实时流式事件
curl -N "http://localhost:8080/api/v1/stream/sse?workflow_id=task-dev-123"

# 获取最终结果
curl "http://localhost:8080/api/v1/tasks/task-dev-123"
```textbash
pip install shannon-sdk

from shannon import ShannonClient

# 创建客户端
with ShannonClient(base_url="http://localhost:8080") as client:
    # 提交任务
    handle = client.submit_task(
        "What is the capital of France?",
        session_id="demo-session"
    )

    # 等待完成
    result = client.wait(handle.task_id)
    print(result.result)
```textbash
# 在后端运行后，新开终端
cd desktop
npm install
npm run dev

# 浏览器打开 http://localhost:3000
```textbash
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Compare renewable energy adoption in EU vs US",
    "context": {
      "force_research": true,
      "research_strategy": "deep"
    }
  }'
# 编排多个研究智能体，综合发现和引用
```textbash
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Analyze this dataset from multiple perspectives",
    "context": {
      "force_swarm": true
    }
  }'
```textbash
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Update the production database schema",
    "context": {
      "require_approval": true
    }
  }'
# 工作流暂停，等待明确的人工审批后继续
```textbash
curl -X POST http://localhost:8080/api/v1/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Market Analysis",
    "cron_expression": "0 9 * * *",
    "task_query": "Analyze market trends",
    "max_budget_per_run_usd": 0.50
  }'
```textbash
export OPENAI_API_BASE=http://localhost:8080/v1
# 你的现有 OpenAI 代码保持不变
```textbash
# 监控智能体执行（SSE）
curl -N "http://localhost:8080/api/v1/stream/sse?workflow_id=task-dev-123"

# 事件类型：
# - WORKFLOW_STARTED, WORKFLOW_COMPLETED
# - AGENT_STARTED, AGENT_COMPLETED
# - TOOL_INVOKED, TOOL_OBSERVATION
# - LLM_PARTIAL, LLM_OUTPUT
```textbash
# 列出可用技能
curl http://localhost:8080/api/v1/skills

# 使用技能执行任务
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Review the auth module for security issues",
    "skill": "code-review",
    "session_id": "review-123"
  }'
```textbash
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Run this Python script and save the output",
    "session_id": "my-workspace"
  }'
```textbash
# 第一轮
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{"query": "What is GDP?", "session_id": "econ-101"}'

# 后续记得上下文
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{"query": "How does it relate to inflation?", "session_id": "econ-101"}'
# 智能体回忆同一会话的近期对话历史
```textyaml
# config/mcp.yaml
mcp_servers:
  - name: "filesystem"
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    enabled: true
```textbash
./scripts/submit_task.sh "Execute Python: import os; os.system('rm -rf /')"
# 结果：OSError - 系统调用被 WASI 沙箱阻止
```textbash
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Generate a market analysis report",
    "config": {
      "budget": {
        "max_tokens": 5000,
        "fallback_model": "gpt-5-mini"
      }
    }
  }'
# 当消耗 80% 预算时自动切换到更便宜的模型
```textrego
# config/opa/policies/teams.rego
package shannon.teams

allow {
    input.team == "data-science"
    input.model in ["gpt-5", "claude-sonnet-4-5-20250929"]
}

deny_tool["database_write"] {
    input.team == "support"
}
```textbash
# 选择提供商
WEB_SEARCH_PROVIDER=serpapi             # serpapi | searchapi | google | bing | exa
SERPAPI_API_KEY=your-serpapi-key        # serpapi.com
```textbash
# 用于深度研究
WEB_FETCH_PROVIDER=firecrawl            # firecrawl | exa | python
FIRECRAWL_API_KEY=your-firecrawl-key   # firecrawl.dev（生产推荐）
```textbash
# 重放失败的工作流
./scripts/replay_workflow.sh task-prod-failure-123

# 输出显示每个决策、工具调用和状态变化
```textbash
# 检查 .env 是否有所需 API Key
cat .env | grep API_KEY

# 确保端口未被占用
netstat -an | grep -E '8080|8081|50052'

# 重启服务
docker compose -f deploy/compose/docker-compose.release.yml down
docker compose -f deploy/compose/docker-compose.release.yml up -d
```textbash
# 验证 API Key 有效
echo $OPENAI_API_KEY

# 检查 orchestrator 日志
docker compose -f deploy/compose/docker-compose.release.yml logs -f orchestrator

# 确保配置文件存在于 ./config/ 目录
ls -la config/
```textbash
# 降低 WASI 内存限制（默认：512MB）
WASI_MEMORY_LIMIT_MB=256

# 降低历史窗口（默认：50条消息）
HISTORY_WINDOW_MESSAGES=20

# 检查 Docker 内存限制
docker stats
```textbash
# 所有服务
docker compose -f deploy/compose/docker-compose.release.yml logs -f

# 指定服务
docker compose -f deploy/compose/docker-compose.release.yml logs -f orchestrator
docker compose -f deploy/compose/docker-compose.release.yml logs -f gateway
docker compose -f deploy/compose/docker-compose.release.yml logs -f llm-service
```text
Shannon/
├── config/                    # 配置文件
│   ├── models.yaml            # LLM 模型配置
│   ├── features.yaml          # 功能开关
│   ├── opa/policies/          # OPA 策略
│   └── skills/user/           # 自定义技能
├── desktop/                   # 桌面应用（TypeScript）
├── docs/                      # 文档
│   └── images/                # 架构图
├── scripts/                   # 脚本
│   ├── install.sh             # 安装脚本
│   └── replay_workflow.sh    # 时间旅行调试
├── gateway/                   # API 网关（Go）
├── orchestrator/              # 编排器（Go）
├── agent-core/                # 智能体核心（Rust）
├── llm-service/               # LLM 服务（Python）
├── temporal/                  # Temporal 工作流引擎
├── deploy/
│   └── compose/
│       └── docker-compose.release.yml
├── CONTRIBUTING.md
├── LICENSE (MIT)
└── README.md