Kocoro-lab/Shannon

# Shannon — 真正可用于生产环境的 AI Agent [](https://opensource.org/licenses/MIT) [](https://docs.shannon.run) [](https://hub.docker.com/u/waylandzhang) [](https://golang.org/) [](https://www.rust-lang.org/) [](CONTRIBUTING.md) 将可靠的 AI agent 部署到生产环境。内置多策略编排、群体协作、token 预算控制、人工审批工作流以及时间旅行调试功能。**在线演示** ## 为什么选择 Shannon？ | 痛点 | Shannon 的解决方案 | |---|---| | *Agent 静默失败？* | 具备时间旅行调试的 Temporal 工作流 — 可逐步重放任何执行过程 | | *成本失控？* | 每个任务/agent 的硬性 token 预算，支持自动模型降级 | | *对发生的情况毫无察觉？* | 实时事件流、Prometheus 指标、OpenTelemetry 追踪 | | *安全担忧？* | 用于代码执行的 WASI 沙盒、OPA 策略、多租户隔离 | | *供应商锁定？* | 兼容 OpenAI、Anthropic、Google、DeepSeek、xAI，以及通过 Ollama 运行的本地模型 | ## 快速开始 ### 前置条件 - Docker 和 Docker Compose - 至少一个 LLM 供应商（OpenAI、Anthropic 等）的 API key ### 一键安装 ``` curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/main/scripts/install.sh | bash ``` 这将下载配置文件、提示输入 API key、拉取 Docker 镜像并启动服务。 **必需的 API Key**（任选其一）： - OpenAI: `OPENAI_API_KEY=sk-...` - Anthropic: `ANTHROPIC_API_KEY=sk-ant-...` - 或任何兼容 OpenAI 的 endpoint **可选但推荐：** - Web 搜索: `SERPAPI_API_KEY=...` ([serpapi.com](https://serpapi.com)) - Web 抓取: `FIRECRAWL_API_KEY=...` ([firecrawl.dev](https://firecrawl.dev)) ### 你的第一个 Agent Shannon 提供了多种与 AI agent 交互的方式： #### REST API ``` # 提交任务 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"}' # 实时流式传输 events curl -N "http://localhost:8080/api/v1/stream/sse?workflow_id=" ``` #### Python SDK ``` 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") result = client.wait(handle.task_id) print(result.result) ``` 请参阅 [Python SDK 文档](https://pypi.org/project/shannon-sdk/)。 #### 兼容 OpenAI 的 API ``` # OpenAI API 的直接替代方案 export OPENAI_API_BASE=http://localhost:8080/v1 # 您现有的 OpenAI 代码无需修改即可运行 ``` #### 桌面应用 从 [GitHub Releases](https://github.com/Kocoro-lab/Shannon/releases/latest) 下载（macOS、Windows、Linux），或从源码构建： ``` cd desktop && npm install && npm run tauri:build ``` 请参阅 [桌面应用指南](desktop/README.md)。 ## 架构 ``` Client --> Gateway (Go) --> Orchestrator (Go) --> Agent Core (Rust) --> LLM Service (Python) --> Providers | | | | | Auth/Rate limit | Temporal workflows | WASI sandbox | Tool execution | | Budget management | Token enforcement | Agent loop | | Complexity routing | Circuit breaker | Context management v v v v PostgreSQL Temporal Redis Tool Adapters ``` ### 核心服务 | 服务 | 语言 | 端口 | 职责 | |---------|----------|------|------| | **Gateway** | Go | 8080 | REST API、身份验证 (JWT/API key)、速率限制 | | **Orchestrator** | Go | 50052 | Temporal 工作流、任务分解、预算管理 | | **Agent Core** | Rust | 50051 | 执行网关、WASI 沙盒、token 统计 | | **LLM Service** | Python | 8000 | 供应商抽象、MCP 工具、agent 循环 | | **Playwright** | Python | 8002 | 用于网页抓取的浏览器自动化 | ### 执行策略 任务会根据复杂度自动路由： | 策略 | 触发条件 | 适用场景 | |----------|---------|----------| | **Simple** | 复杂度 < 0.3 | 单 agent，直接响应 | | **DAG** | 多步任务（默认） | 带有依赖追踪的扇出/扇入 | | **ReAct** | 迭代推理 | 推理 + 工具使用循环 | | **Research** | 多步研究 | 分级模型优化成本（降低 50-70%） | | **Exploratory** | Tree-of-Thoughts | 并行假设探索 | | **Browser Use** | Web 交互任务 | 基于 Playwright 的浏览 agent | | **Domain Analysis** | 专业分析 | 特定领域的深度研究 | | **Swarm** | 自主团队 | 主 orchestrator 多 agent 编排与收敛检测 | ## 核心能力 ### 研究工作流 ``` 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"} }' ``` ### Swarm 多 Agent ``` 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 http://localhost:8080/api/v1/skills # List skills curl -X POST http://localhost:8080/api/v1/tasks \ -H "Content-Type: application/json" \ -d '{"query": "Review the auth module", "skill": "code-review", "session_id": "review-123"}' ``` 在 `config/skills/user/` 目录中创建自定义技能（如果该目录不存在，请自行创建——它已被 gitignore 忽略）。请参阅 [技能系统](docs/skills-system.md)。 ### 人工干预审批 通过 OPA 策略或带有 `require_approval: true` 的工作流模板来启用审批关卡。审批请求会通过 WebSocket 路由到已连接的 daemon 客户端。 ``` # 提交审批决策 curl -X POST http://localhost:8080/api/v1/approvals/decision \ -H "Content-Type: application/json" \ -d '{"workflow_id": "", "approval_id": "", "approved": true}' ``` ### 会话连续性 ``` curl -X POST http://localhost:8080/api/v1/tasks \ -H "Content-Type: application/json" \ -d '{"query": "What is GDP?", "session_id": "econ-101"}' # Follow-up 记住上下文 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 -X POST http://localhost:8080/api/v1/schedules \ -H "Content-Type: application/json" \ -d '{"name": "Daily Analysis", "cron_expression": "0 9 * * *", "task_query": "Analyze market trends"}' ``` ### Token 预算控制 ``` curl -X POST http://localhost:8080/api/v1/tasks \ -H "Content-Type: application/json" \ -d '{ "query": "Generate a market report", "context": {"budget_max": 5000} }' ``` ### 时间旅行调试 ``` ./scripts/replay_workflow.sh task-prod-failure-123 ``` ### 10+ LLM 供应商 - **Anthropic**: Claude Opus 4.6, Sonnet 4.6, Haiku 4.5 - **OpenAI**: GPT-5.1, GPT-5 mini, GPT-5 nano - **Google**: Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 3 Pro Preview - **xAI**: Grok 4 (reasoning & non-reasoning), Grok 3 Mini - **DeepSeek**: DeepSeek Chat, DeepSeek Reasoner - **MiniMax**: M3, M2.7, M2.7-highspeed - **Groq**: Llama, Mixtral（超快推理） - **其他**: Qwen, Meta (Llama 4), Zhipu (GLM), Kimi - **本地**: Ollama, LM Studio, vLLM — 任何兼容 OpenAI 的 endpoint - 供应商之间的自动故障转移 ## API Endpoint | Endpoint | 是否经 Orchestrator？ | 格式 | 适用场景 | |----------|:---:|--------|----------| | `POST /v1/chat/completions` | 是 | 兼容 OpenAI | 使用 OpenAI SDK 的应用 | | `POST /v1/completions` | 否（代理） | 兼容 OpenAI | 轻量级 LLM 代理 | | `POST /api/v1/tasks` | 是 | Shannon 原生（同步） | 完整的 orchestrator pipeline | | `POST /api/v1/tasks/stream` | 是 | Shannon 原生 (SSE) | 流式编排 | **工具执行：** `GET /api/v1/tools`, `POST /api/v1/tools/{name}/execute` **身份验证：** `GET /api/v1/auth/me`, `POST /api/v1/auth/refresh-key`, `GET/POST/DELETE /api/v1/auth/api-keys` **会话：** `GET/PATCH/DELETE /api/v1/sessions/{id}`、历史记录、事件、文件 **任务控制：** `POST /api/v1/tasks/{id}/cancel|pause|resume`, `GET .../control-state|events|timeline` **定时任务：** 在 `/api/v1/schedules` 进行完整的 CRUD，外加 `pause`、`resume`、`runs` **实时：** `GET /api/v1/stream/sse`, `GET /api/v1/stream/ws`, `WS /v1/ws/messages` (daemon) ## 项目结构 ``` shannon/ ├── go/orchestrator/ # Temporal workflows, budget manager, gateway │ ├── cmd/gateway/ # REST API gateway (auth, rate limiting) │ └── internal/ # Workflows, strategies, activities ├── rust/agent-core/ # Enforcement gateway, WASI sandbox ├── python/llm-service/ # LLM providers, MCP tools, agent loop ├── desktop/ # Tauri + Next.js desktop application ├── clients/python/ # Python SDK ├── protos/ # Shared protobuf definitions ├── config/ # YAML configuration files ├── deploy/compose/ # Docker Compose for local dev + release ├── migrations/ # PostgreSQL schema migrations ├── scripts/ # Automation and helper scripts └── docs/ # Architecture and API documentation ``` ### 配置 | 文件 | 用途 | |------|---------| | `.env` | API key、运行时设置 | | `config/shannon.yaml` | 功能开关、身份验证、追踪 | | `config/models.yaml` | LLM 供应商、定价、能力 | | `config/features.yaml` | 工作流设置、执行模式 | | `config/openai_models.yaml` | 用于兼容 OpenAI API 的自定义 `shannon-*` 模型名称 | | `config/research_strategies.yaml` | 研究策略的模型分级 | ### 服务端口（本地开发） | 服务 | 端口 | 协议 | |---------|------|----------| | Gateway | 8080 | HTTP | | Orchestrator | 50052 (gRPC), 8081 (健康检查) | gRPC/HTTP | | Agent Core | 50051 | gRPC | | LLM Service | 8000 | HTTP | | Temporal | 7233 (gRPC), 8088 (UI) | gRPC/HTTP | | PostgreSQL | 5432 | TCP | | Redis | 6379 | TCP | ## 开发 ### 从源码构建 ``` git clone https://github.com/Kocoro-lab/Shannon.git cd Shannon make setup # Create .env + generate protobuf stubs vim .env # Add your API key ./scripts/setup_python_wasi.sh # Download Python WASI interpreter make dev # Start all services make smoke # Run E2E smoke tests ``` ### 开发命令 ``` make dev # Start all services make smoke # E2E smoke tests make ci # Full CI suite make proto # Regenerate protobuf files make lint # Run linters make logs # View service logs make down # Stop all services ``` ### 浏览器自动化（可选） Playwright 服务可启用浏览器自动化工作流（包含 Chromium 的镜像大小为 3.4GB）。它**默认不启动**。要启用它： ``` # 开发 docker compose -f deploy/compose/docker-compose.yml --profile browser up -d # 预构建镜像 docker compose -f deploy/compose/docker-compose.release.yml --profile browser up -d ``` 使用以下命令进行测试： ``` curl -X POST http://localhost:8080/api/v1/tasks \ -H "Content-Type: application/json" \ -d '{"query":"Go to https://waylandz.com and get the page title","session_id":"test","context":{"role":"browser_use"}}' ``` ### 使用预构建镜像 ``` cd Shannon cp .env.example .env && vim .env docker compose -f deploy/compose/docker-compose.release.yml up -d ``` ## 故障排除 ### 健康检查 ``` docker compose -f deploy/compose/docker-compose.yml ps curl http://localhost:8080/health curl http://localhost:8081/health ``` ### 常见问题 **服务未启动：** - 检查 `.env` 是否包含必需的 API key - 确保端口 8080、8081、50052 未被占用 - 运行 `docker compose down && docker compose up -d` 进行重建 **任务执行失败：** - 验证 LLM API key 是否有效 - 查看 orchestrator 日志：`docker compose logs -f orchestrator` **内存不足：** - 降低 `WASI_MEMORY_LIMIT_MB`（默认值：512） - 调低 `HISTORY_WINDOW_MESSAGES`（默认值：50） ## 常见问题解答 ### Shannon 是什么？ Shannon 是一个**面向生产环境的多 agent 编排框架**，使用 Go、Rust 和 Python 构建。它专注于可靠性：使用 Temporal 工作流实现容错、时间旅行调试、token 预算控制、人工审批工作流，并使用 WASI 沙盒进行安全的代码执行。 ### Shannon 与 LangChain 或 CrewAI 有何不同？ | 框架 | 侧重点 | 关键区别 | |-----------|-------|-------------------| | **Shannon** | 生产级可靠性 | Temporal 工作流、时间旅行调试、硬性 token 预算 | | **LangChain** | LLM 链与 RAG | 思维链组合、检索增强 | | **CrewAI** | 角色扮演 agent | 多 agent 角色、任务委派 | Shannon 专为**生产部署**而设计，内置可观测性、预算管理和工作流重放功能——而不仅仅是为了原型开发。 ### 有哪些可用的执行策略？ Shannon 会根据复杂度自动路由任务： - **Simple**：单 agent 直接响应（复杂度 < 0.3） - **DAG**：具有依赖追踪的扇出/扇入（多步骤任务的默认选项） - **ReAct**：推理 + 工具使用循环 - **Research**：使用分级模型将成本降低 50-70% - **Swarm**：由主 orchestrator 编排的多 agent 团队 - **Browser Use**：基于 Playwright 的 Web 交互 ### 支持哪些 LLM 供应商？ Shannon 支持 10 多家供应商并具备自动故障转移功能： - **Anthropic**: Claude Opus 4.6, Sonnet 4.6, Haiku 4.5 - **OpenAI**: GPT-5.1, GPT-5 mini, GPT-5 nano - **Google**: Gemini 2.5 Pro, Gemini 2.5 Flash - **xAI**: Grok 4.1 (reasoning & non-reasoning) - **DeepSeek**、**MiniMax**、**Qwen**、**Kimi** - **本地**: Ollama, LM Studio, vLLM — 任何兼容 OpenAI 的 endpoint ### 如何安装 Shannon？ **一键安装：** ``` curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/main/scripts/install.sh | bash ``` **前置条件：** - Docker 和 Docker Compose - 至少一个 LLM 供应商的 API key ### 什么是时间旅行调试？ 时间旅行调试允许你逐步重放任何工作流的执行过程，从而了解故障或意外行为： ``` ./scripts/replay_workflow.sh task-prod-failure-123 ``` ### Token 预算控制是如何工作的？ 任务的 context 参数中设置 `budget_max`。Shannon 会强制执行严格的 token 限制，并在预算即将耗尽时自动降级到更便宜的模型。 ### 我可以在现有的 OpenAI SDK 中使用 Shannon 吗？ 是的！Shannon 提供了一个兼容 OpenAI 的 API endpoint： ``` export OPENAI_API_BASE=http://localhost:8080/v1 # 您现有的 OpenAI 代码无需修改即可运行 ``` ### 在哪里可以获得帮助？ - **文档**：[docs.shannon.run](https://docs.shannon.run) - **GitHub Issues**：[github.com/Kocoro-lab/Shannon/issues](https://github.com/Kocoro-lab/Shannon/issues) - **在线演示**：[shannon.run](https://shannon.run) ## 文档 | 资源 | 描述 | |----------|-------------| | [官方文档](https://docs.shannon.run) | 完整的文档站点 | | [架构](docs/multi-agent-workflow-architecture.md) | 深入解析系统设计 | | [流式 API](docs/streaming-api.md) | SSE 与 WebSocket 流式传输 | | [技能系统](docs/skills-system.md) | 自定义技能开发 | | [会话工作区](docs/session-workspaces.md) | WASI 沙盒指南 | | [扩展 Shannon](docs/extending-shannon.md) | 自定义工具与模板 | | [Swarm Agent](docs/swarm-agents.md) | 多 agent 协作 | ## 贡献 我们欢迎您的贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 - [提交 Issue](https://github.com/Kocoro-lab/Shannon/issues) - [查看路线图](ROADMAP.md) ## 许可证 MIT 许可证 — 随处可用，随意修改。详情请参阅 [LICENSE](LICENSE)。

别再调试 AI 故障了。开始交付可靠的 agent 吧。

GitHub · 文档

标签：AI框架, DLL 劫持, EVTX分析, Go, Ruby工具, Rust, 人工智能, 可视化界面, 多智能体, 大语言模型, 工作流编排, 搜索引擎查询, 日志审计, 测试用例, 用户代理, 用户模式Hook绕过, 网络流量审计, 自定义请求头, 请求拦截, 逆向工具