> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shannon.run/llms.txt
> Use this file to discover all available pages before exploring further.
# 快速开始
> 5 分钟内向 Shannon 提交您的第一个任务
## 您的第一个任务
让我们向 Shannon 提交一个简单的任务并看看它的运行情况。本指南假设您已完成[安装](/cn/quickstart/installation)。
## 使用 REST API
与 Shannon 交互的最简单方式是通过其 REST API：
```bash theme={null}
curl -X POST http://localhost:8080/api/v1/tasks \
-H "Content-Type: application/json" \
-d '{
"query": "分析以下句子的情感：Shannon 让 AI 智能体变得简单可靠！"
}'
```
您将收到如下响应：
```json theme={null}
{
"task_id": "task-dev-1730000000",
"status": "TASK_STATUS_RUNNING",
"message": "Task submitted",
"created_at": "2024-10-22T10:30:00Z"
}
```
## 检查任务状态
使用 `task_id` 检查状态：
```bash theme={null}
curl http://localhost:8080/api/v1/tasks/task-dev-1730000000
```
响应：
```json theme={null}
{
"task_id": "task-dev-1730000000",
"status": "TASK_STATUS_COMPLETED",
"response": { "result": "The sentiment is overwhelmingly positive..." },
"error": "",
"query": "分析以下句子的情感：Shannon 让 AI 智能体变得简单可靠！",
"session_id": "...",
"mode": "EXECUTION_MODE_STANDARD",
"created_at": "2024-10-22T10:30:00Z",
"updated_at": "2024-10-22T10:30:25Z"
}
```
## 实时流式传输事件
Shannon 支持服务器发送事件 (SSE) 进行实时更新：
```bash theme={null}
curl -N http://localhost:8080/api/v1/stream/sse?workflow_id=task-dev-1730000000
```
您将看到事件的实时发生：
```
event: LLM_PROMPT
data: {"message":"Analyzing sentiment..."}
event: WORKFLOW_COMPLETED
data: {"result":"The sentiment is positive..."}
```
## 使用 Python SDK
为了获得更好的开发体验，请使用 Python SDK：
### 安装
```bash theme={null}
pip install shannon-sdk
```
### 提交和监控任务
```python theme={null}
from shannon import ShannonClient
# HTTP 客户端（默认：http://localhost:8080）
client = ShannonClient()
handle = client.submit_task(
query="分析以下句子的情感：Shannon 让 AI 智能体变得简单！"
)
print("Task submitted:", handle.task_id)
# 等待完成
final = client.wait(handle.task_id, timeout=60)
print("Result:", final.result)
```
### 流式传输事件
```python theme={null}
# 实时流式传输事件
for event in client.stream(handle.workflow_id):
print(f"{event.type}: {event.message}")
```
## 执行模式
Shannon 根据任务复杂度自动选择执行模式。您可以通过在任务提交中传递 `mode` 参数（`simple`、`standard`、`complex`、`supervisor`）来覆盖此行为。
## 成本控制
预算控制由 Shannon 管理。目前还不能通过 REST 设置每个请求的明确预算。
## 多轮对话
Shannon 支持基于会话的对话：
```python theme={null}
session_id = "my-conversation-123"
# 第一条消息
handle1 = client.submit_task(
query="法国的首都是哪里？",
session_id=session_id
)
# 后续消息（Shannon 记住上下文）
handle2 = client.submit_task(
query="人口是多少？",
session_id=session_id
)
# Shannon 知道您在询问巴黎的人口
```
## 使用桌面应用
如果需要图形界面来查看任务和会话，请使用 Shannon 桌面应用程序（基于 Tauri 的客户端）。参见[桌面应用程序](/cn/quickstart/desktop-app)了解安装和使用细节。
## 示例用例
Shannon 根据查询复杂度自动选择适当的执行模式和认知策略。您无需指定这些参数。
### 情感分析
```python theme={null}
client.submit_task(
query="分析情感：这个产品超出了我的预期！"
)
```
### 研究与摘要
```python theme={null}
client.submit_task(
query="研究 2024 年量子计算的突破性进展并创建摘要"
)
```
### 代码生成
```python theme={null}
client.submit_task(
query="编写一个使用记忆化计算斐波那契数列的 Python 函数"
)
```
### 带上下文的复杂分析
```python theme={null}
client.submit_task(
query="比较微服务架构与单体架构的优缺点",
context={
"domain": "software_architecture",
"depth": "comprehensive",
"include_examples": True
}
)
```
## 下一步是什么？
了解代理、工作流和认知模式
探索所有 API 端点和参数
深入了解 SDK 功能和异步使用
根据您的需求自定义 Shannon
## 故障排除
检查日志中的错误：
```bash theme={null}
docker compose logs orchestrator
docker compose logs agent-core
```
常见原因：
* 无效的 LLM API 密钥
* LLM 提供商速率限制
* 网络连接问题
Shannon 默认禁用认证（`GATEWAY_SKIP_AUTH=1`）。如果您启用了认证，请包含 API 密钥：
```bash theme={null}
curl -H "X-API-Key: sk_test_123456" \
http://localhost:8080/api/v1/tasks
```
预算限制通过环境变量在平台级别配置：
```bash theme={null}
# 在 .env 文件中
MAX_TOKENS_PER_REQUEST=10000
MAX_COST_PER_REQUEST=0.50
# 重启服务以使更改生效
docker compose restart
```
对于每个任务的监控，通过状态端点或流式事件检查成本。