客户端 ─▶ Gateway:8080 ─▶ Orchestrator:50052 ─▶ Agent Core:50051 ─▶ LLM Service:8000 ─▶ 模型/工具
REST/SDK    鉴权·限流        Temporal 工作流      执行强制·WASI 沙箱    提供商抽象·技能
OpenAI兼容                   复杂度路由·预算管理   令牌计数·熔断器       MCP 工具·agent loop

旁路：PostgreSQL(状态+向量) · Redis(会话/缓存) · Temporal:7233(UI:8088, 时间旅行) · Playwright:8002(可选)

curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/main/scripts/install.sh | bash

cd shannon       # 安装目录，默认在当前目录下
nano .env        # 填入 OPENAI_API_KEY 或 ANTHROPIC_API_KEY
docker compose down
docker compose up -d

# 检查所有服务状态
docker compose ps

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

# Orchestrator 健康检查
curl http://localhost:8081/health

# 提交任务
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"
  }'

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

# 获取最终结果
curl "http://localhost:8080/api/v1/tasks/task-dev-123"

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)

cd desktop
npm install
npm run tauri:build

export OPENAI_API_BASE=http://localhost:8080/v1
# 你的现有 OpenAI 代码保持不变

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"
    }
  }'

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
    }
  }'

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
    }
  }'

curl -X POST http://localhost:8080/api/v1/approvals/decision \
  -H "Content-Type: application/json" \
  -d '{"workflow_id": "<workflow_id>", "approval_id": "<approval_id>", "approved": true}'

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
  }'

# 第一轮
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"}'

# 列出可用技能
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"
  }'

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
# - BUDGET_THRESHOLD（预算告警）
# - APPROVAL_REQUESTED, APPROVAL_DECISION（审批流转）

# .env 中的 MCP 相关配置
MCP_ALLOWED_DOMAINS=localhost,127.0.0.1   # URL 域名白名单，逗号分隔
MCP_MAX_RESPONSE_BYTES=10485760           # 响应体积上限，默认 10 MB
MCP_TIMEOUT_SECONDS=10                    # 单次调用超时
MCP_RETRIES=3                             # 失败重试次数
MCP_CB_FAILURES=5                         # 熔断阈值：连续失败 5 次
MCP_CB_RECOVERY_SECONDS=60                # 熔断恢复等待

./scripts/submit_task.sh "Execute Python: import os; os.system('rm -rf /')"
# 结果：os.system 触发的系统调用被 WASI 沙箱拦截

PYTHON_WASI_WASM_PATH=./wasm-interpreters/python-3.11.4.wasm  # 解释器路径
WASI_MEMORY_LIMIT_MB=512       # 内存上限
WASI_TIMEOUT_SECONDS=60        # 单次执行超时
PYTHON_WASI_SESSION_TIMEOUT=3600   # 会话工作区存活时间
SHANNON_USE_WASI_SANDBOX=0     # 文件操作是否路由经沙箱，默认关闭

curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Generate a market analysis report",
    "context": {
      "budget_max": 5000
    }
  }'

package shannon.task

import future.keywords.if
import future.keywords.in

# 数据科学团队可用高档模型，预算上限 50K
allow_model(model) if {
    input.context.team == "data-science"
    model in ["gpt-5-2025-08-07", "claude-sonnet-4-5-20250929"]
}

max_tokens := 50000 if {
    input.context.team == "data-science"
}

allow_tool(_) if {
    input.context.team == "data-science"
}

# 搜索：searchapi | serper | serpapi | bing | exa | firecrawl
WEB_SEARCH_PROVIDER=searchapi
SEARCHAPI_API_KEY=your-searchapi-key
# 或 SERPAPI_API_KEY / SERPER_API_KEY / BING_API_KEY / EXA_API_KEY

# 抓取：firecrawl | exa | python
WEB_FETCH_PROVIDER=firecrawl            # 生产推荐，支持 JS 渲染与深度抓取
FIRECRAWL_API_KEY=your-firecrawl-key

./scripts/replay_workflow.sh task-prod-failure-123

# 输出显示每个决策、工具调用和状态变化

# 检查 .env 是否有所需 API Key
grep API_KEY .env

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

# 重启服务
docker compose down
docker compose up -d

# 验证 API Key 已导入容器环境（Key 注入在 llm-service）
docker compose exec llm-service env | grep API_KEY

# 检查 orchestrator 日志
docker compose logs -f orchestrator

# 确认配置文件在位
ls config/

# 降低 WASI 内存限制（默认：512MB）
WASI_MEMORY_LIMIT_MB=256

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

# 检查容器资源占用
docker stats

docker compose logs -f                    # 所有服务
docker compose logs -f orchestrator       # 编排与预算
docker compose logs -f gateway            # REST 与事件流
docker compose logs -f llm-service        # 模型调用与工具

Shannon/
├── go/orchestrator/          # 编排器与网关（Go）
│   ├── cmd/gateway/          # REST 网关：鉴权、限流、路由
│   └── internal/             # 工作流、策略、预算管理、活动
├── rust/agent-core/          # 执行强制网关与 WASI 沙箱（Rust）
├── python/llm-service/       # 提供商抽象、MCP 工具、agent loop（Python）
├── desktop/                  # Tauri v2 + Next.js 桌面应用
├── clients/python/           # Python SDK（shannon-sdk）
├── protos/                   # 共享 protobuf 定义
├── config/                   # YAML 配置：shannon.yaml、models.yaml、
│                             #   features.yaml、openai_models.yaml、
│                             #   research_strategies.yaml、rate_limits.yaml、
│                             #   opa/policies/、skills/
├── deploy/compose/           # 本地开发与 release 的 Docker Compose
├── migrations/               # PostgreSQL 迁移
├── scripts/                  # install.sh、replay_workflow.sh 等自动化脚本
├── docs/                     # 架构与 API 文档
├── examples/                 # 示例
└── tests/                    # 端到端与集成测试