# 第三方对接开发手册

> 提供 Python/JavaScript 极简示例，演示如何通过只读API对接城丰星际平台  
> **仅演示只读查询**，不提供夺权、批量派单等高危操作示例

---

## Python 示例

### 获取任务看板
```python
import requests

r = requests.get("http://localhost:18989/api/tasks/board")
board = r.json()
print(f"总任务: {board['summary']['total']}")
print(f"进行中: {board['summary']['in_progress']}")
```

### 获取任务时序
```python
import requests

task_id = "task-abc123"
r = requests.get(f"http://localhost:18989/api/tasks/{task_id}/timeline")
timeline = r.json()
for event in timeline.get("timeline", []):
    print(f"[{event['ts_system']}] {event['event_type']}: {event['detail']}")
```

### 批量导出（CSV）
```python
import requests, csv

r = requests.get("http://localhost:18989/api/tasks/board")
tasks = r.json()

with open("tasks_export.csv", "w", newline="") as f:
    writer = csv.writer(f)
    writer.writerow(["ID", "类型", "状态", "负责人", "工时"])
    for col in tasks.get("columns", {}).values():
        for t in col.get("tasks", []):
            writer.writerow([t["task_id"], t.get("task_type",""), 
                           t.get("status",""), t.get("assigned_to",""),
                           t.get("effective_hours",0)])
```

---

## JavaScript 示例

### 获取Agent状态
```javascript
fetch('http://localhost:18989/api/agents')
  .then(r => r.json())
  .then(agents => {
    agents.forEach(a => console.log(`${a.name}: ${a.status}`));
  });
```

### 获取监控指标
```javascript
fetch('http://localhost:18989/api/metrics/roles')
  .then(r => r.json())
  .then(data => {
    console.log('角色资源:', data.roles);
  });
```

---

## 对接场景

| 场景 | 使用接口 | 说明 |
|------|---------|------|
| 本地看板 | `/api/tasks/board` | 嵌入OA系统首页 |
| 消息推送 | `/api/tasks/{id}` | 任务状态变更通知 |
| 数据导出 | `/api/tasks/board` | 批量导出CSV/Excel |
| 健康监控 | `/api/status` | 集成到运维监控系统 |

---

## 约束

- 以上示例仅使用**只读API**，无需密钥
- 写操作（创建任务/派发/夺权）需申请官方密钥
- 不可尝试绕过API直连数据库