# Matee Agent Skill

> 读这个文件。读完你就知道怎么操作 Matee 工作区。

## 快速接入（3步）

### 第1步：注册

用户会给你一个 6 位邀请码（如 `ABC123`）。用它换 token：

```bash
curl -X POST https://maike.vimatee.com/api/agent/register \
  -H "Content-Type: application/json" \
  -d '{"code":"邀请码","agentName":"你的Agent名字"}'
```

成功后返回 `token`、`workspaceId`、`scopes`。**保存好 token**，邀请码只能用一次。

### 第2步：验证连接

```bash
curl -H "Authorization: Bearer 你的token" \
  https://maike.vimatee.com/api/agent/state
```

返回项目信息说明注册成功。

### 第3步：开始工作

发心跳、读消息、认领书记员任务。完整 API 见下方。

---

## 身份

你是 Matee 工作区的 AI 书记员。你通过 API 读取和操作工作区的消息、文档、任务、记忆和技能，还能作为书记员自动整理对话。

## 认证

每个请求带 Authorization 头：

```
Authorization: Bearer mtee_sk_xxxxxxxxxxxxxxxxxxxxxxxx
```

Token 在工作台生成邀请码、Agent 用邀请码注册后获得。

## Base URL

```
https://maike.vimatee.com/api/agent
```

---

## 操作 API

### 读完整状态
```http
GET /state
```
返回：project, channels, messages, memory(todoList, decisions, blockers, progressLog), docs, resourceNotes, runs。

### 读消息
```http
GET /messages?channelId=xxx&limit=50
```

### 发消息
```http
POST /messages
{"content": "消息内容", "channelId": "可选"}
```

### 读任务
```http
GET /tasks?status=todo
```

### 创建任务
```http
POST /tasks
{"title": "标题", "detail": "详情", "owner": "负责人"}
```

### 更新任务
```http
PATCH /tasks/{id}
{"status": "done", "owner": "新负责人"}
```
status: todo | doing | done

### 读文档
```http
GET /docs
GET /docs/{id}?format=text|markdown|json
```

### 创建文档
```http
POST /docs
{"title": "标题", "body": "正文"}
```

### 更新文档
```http
PUT /docs/{id}
{"title": "新标题", "body": "新正文"}
```

### 读记忆
```http
GET /memory?kind=decision
```
kind: progress | task | decision | blocker | resource | idea | risk | question

### 技能
```http
GET /skills?q=关键词
POST /skills
{"title": "技能名", "content": "内容", "category": "prompt", "tags": ["标签"]}
GET /skills/{id}?format=text
PUT /skills/{id}
```

### 心跳（保持在线状态）
```http
POST /heartbeat
```
每 15-60 秒调一次。让工作台显示"Agent 在线"。

---

## 作为书记员工作

你可以代替内置 AI，自己分析对话并写回结果。

### 1. 轮询任务
```http
GET /scribe/tasks?status=pending
```

### 2. 认领任务
```http
POST /scribe/tasks
{"action": "claim"}
```
返回完整上下文：project, messages（最近30条）, currentMemory（任务/决策/阻塞）, docs。

### 3. 提交结果

**响应 JSON Schema（严格遵守）：**

```json
{
  "assistantReply": "string — 回复到频道的总结消息，1-2句话",
  "tasks": [
    {
      "title": "string — 任务标题（必填）",
      "detail": "string — 任务详情",
      "owner": "string — 负责人",
      "status": "string — todo（默认）"
    }
  ],
  "docUpdates": [
    {
      "docId": "string — 已有文档ID（更新时用）",
      "title": "string — 新文档标题（创建时用）",
      "body": "string — 文档正文"
    }
  ],
  "memoryUpdates": [
    {
      "kind": "string — progress|decision|blocker|risk|idea",
      "title": "string — 标题（必填）",
      "detail": "string — 详情"
    }
  ],
  "summary": "string — 本次整理的简短摘要"
}
```

```http
POST /scribe/tasks/{taskId}
Content-Type: application/json

{上面的JSON}
```

提交后 Matee 自动：发消息到频道、创建任务、更新文档、添加记忆。

---

## 推荐工作流

1. **注册**：用邀请码 POST /register 换 token
2. **心跳**：POST /heartbeat 确认连接
3. **了解项目**：GET /state
4. **检查任务**：GET /scribe/tasks?status=pending
5. **有任务时**：POST /scribe/tasks {action:claim} → 分析 → POST /scribe/tasks/{id}
6. **没任务时**：GET /messages 看看有没有需要回应的
7. **循环**：每 15-60 秒重复

## curl 快速测试

```bash
TOKEN="mtee_sk_你的token"
BASE="https://maike.vimatee.com/api/agent"

# 测试连接
curl -sf -H "Authorization: Bearer $TOKEN" "$BASE/state" | python3 -m json.tool | head -20

# 发消息
curl -sf -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"Agent 已上线"}' \
  "$BASE/messages"

# 心跳
curl -sf -X POST -H "Authorization: Bearer $TOKEN" "$BASE/heartbeat"

# 认领书记员任务
curl -sf -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"claim"}' \
  "$BASE/scribe/tasks"
```

## 错误码

| 状态码 | 含义 |
|---|---|
| 400 | 请求参数错误 |
| 401 | 没传 token |
| 402 | AI 额度用完 |
| 403 | token 无效/过期/scope 不足 |
| 404 | 资源不存在 |
| 410 | 邀请码已过期或已使用 |
| 503 | 数据库不可用 |