# OpenAaaS pi Extension

<p align="right">中文 | <a href="./README.en.md">English</a></p>

为 [pi](https://github.com/earendil-works/pi) 开发的 OpenAaaS 扩展，提供统一的 `OpenAaaS` 工具，用于服务发现、客户端注册、任务提交及结果下载。

## 安装

```bash
pi install npm:open-aaas-pi-extension
```

安装后，在 pi 中执行 `/reload` 即可自动加载扩展。

## 配置文件

配置文件固定保存在以下路径：

```
~/.pi/agent/openaaas/config.json
```

首次加载时若不存在，会自动创建默认配置：

```json
{
  "servers": {
    "default": {
      "server_url": "https://api.open-aaas.com"
    }
  },
  "default_server": "default"
}
```

注册成功后的配置示例：

```json
{
  "servers": {
    "default": {
      "server_url": "https://api.open-aaas.com",
      "api_key": "ak_client_xxx",
      "client_id": "xxx",
      "name": "my-client"
    }
  },
  "default_server": "default"
}
```

运行 `register` 成功后会自动写入 `api_key`、`client_id` 和 `name`。

## 多服务器配置

支持同时配置多个服务器，通过 `server` 参数指定目标服务器。

### 为多个服务器分别注册

每个服务器别名有独立的注册信息：

```bash
# 在 prod 服务器注册
OpenAaaS(action: "register", server: "prod", name: "my-prod-client")

# 在 local 服务器注册
OpenAaaS(action: "register", server: "local", name: "my-local-client")
```

两个服务器会分别保存各自的 api_key，互不干扰。

### 设置服务器地址

```
OpenAaaS(action: "set_server_url", server: "prod", server_url: "https://api.open-aaas.com")
OpenAaaS(action: "set_server_url", server: "local", server_url: "http://127.0.0.1:8080")
```

切换默认服务器：
```
OpenAaaS(action: "set_default_server", server: "prod")
```

列出所有配置的服务器：
```
OpenAaaS(action: "list_servers")
```

## 可用工具

| 工具名 | 功能 |
|--------|------|
| `OpenAaaS` | 统一入口工具，通过 `action` 参数调用不同功能 |

### 支持的 action

| action | 功能 |
|--------|------|
| `discover` | 发现服务端 API 信息（返回服务端版本、Base URL、认证方式、可用端点列表、已注册服务列表） |
| `set_server_url` | 设置服务器地址并保存到 config.json。已有注册信息（api_key）的服务器不会被覆盖 |
| `register` | 注册客户端，自动保存 api_key（仅需一次） |
| `update_profile` | 修改用户名 |
| `list_services` | 列出可用服务（返回轻量摘要：id/name/description/agent_status/access_type/has_permission/registration_status，不含 usage 长文本） |
| `get_service_usage` | 获取指定服务的详细 usage（能力范围、调用规范、返回格式、限制条件） |
| `list_history` | 列出当前 Session 中所有 OpenAaaS 任务历史 |
| `submit_task` | 提交任务到远程 Agent（支持文件上传，支持 `session_id` 保持对话上下文） |
| `get_task` | 查询任务状态和最终结果（仅在用户要求时调用，不要主动轮询） |
| `cancel_task` | 取消执行中的任务 |
| `list_files` | 列出任务的结果文件列表 |
| `download_result` | 下载任务结果文件（支持 file_id 单选或 download_all 全选），未指定 file_id 且 download_all=false 时默认优先下载 .zip 文件，否则下载第一个文件。自动检测并解压 .zip 文件，单文件下载不超过 100MB，解压后总大小不超过 300MB（Zip 炸弹防护） |
| `list_servers` | 列出所有已配置的服务器 |
| `set_default_server` | 切换默认服务器 |
| `remove_server` | 删除指定服务器的配置（不能删除默认服务器） |

## 渐进式信息获取

本插件遵循"信息渐进式披露"原则：不要一次性获取所有服务的完整信息。

**标准使用流程**：
1. `set_server_url` — 设置服务端地址（如未设置，默认连接 https://api.open-aaas.com）
2. `register` — 注册获取 api_key（仅需一次）
3. `list_services` — 获取轻量服务列表（id/name/description/agent_status/access_type/has_permission/registration_status），浏览并筛选候选服务
4. `get_service_usage` — 对筛选出的候选服务，按需获取详细 usage（能力范围、调用规范、返回格式、限制条件）
5. 根据 usage 内容，构造正确的 task_prompt 和 output_prompt
6. `submit_task` — 提交任务（可附带文件），保存返回的 task_id
7. `list_history` — 查看当前 Session 中所有任务历史（上下文压缩后可用来恢复记忆）
8. `get_task` — 仅在用户明确要求时调用，查询任务状态和最终结果（不要主动轮询）
9. `download_result` — 任务完成后下载结果文件

**为什么这样设计**：
- `list_services` 返回轻量摘要，不占用 LLM 上下文
- `usage` 通常包含大量文本（能力说明、调用规范、示例等），只应在确定使用该服务时获取
- 避免一次性加载所有服务的完整文档导致上下文溢出

## 自动监控

调用 `submit_task` 提交任务后，扩展会自动在后台监控任务状态：

- **Widget 实时显示**：在编辑器下方显示活跃任务（pending / accepted / running / cancelling）的统计信息和任务列表，状态变更时自动刷新
- **UI 通知**：任务完成、失败或取消时自动推送通知
- **任务完成自动注入通知**：任务到达终态（completed / failed / cancelled）时，扩展自动向对话上下文注入 `[OpenAaaS-task-result]` 通知，包含状态、服务名、任务摘要（截断）、耗时和在途任务快照。该通知是系统通知而非用户指令；结果获取方式不变，需要结果文件用 `download_result`，需要查看摘要用 `get_task`
- **无需轮询**：LLM 不需要主动调用 `get_task` 轮询状态，任务完成后扩展会自动注入 `[OpenAaaS-task-result]` 通知，收到后按需获取结果即可
- **Widget 可见性约束**：widget 实时显示的任务状态仅对用户可见，你无法直接看到。如果你需要回答用户关于某个任务当前状态的任何问题（例如"任务现在是什么状态""完成了吗"），必须先调用 `get_task` 重新查询最新状态，不要引用之前调用返回的旧状态
- **轮询间隔**：按任务运行时长（从服务端 created_at 计算）分档——提交后立即轮询一次，0~2 分钟每 10 秒，2~10 分钟每 20 秒，10 分钟后每 30 秒
- **限流与退避**：遇到 429 限流响应时遵守服务端 Retry-After 建议（钳制在 1 秒至 5 分钟之间）；网络错误或服务器错误按连续失败次数退避（60 秒 → 120 秒 → 240 秒 → 300 秒封顶），成功后恢复运行时长分档间隔
- **永久错误停止轮询**：认证失效（401）或任务不存在（404）等永久错误会停止该任务的轮询，并在 `/OpenAaaS-tasks` 面板显示错误信息；停止状态会持久化，会话重建后不会恢复轮询
- **Session 持久化**：任务状态会保存到当前会话中，切换会话树后自动重建监控
- **Session 重建自动提醒**：当 session 被压缩重建后，扩展会自动发送消息到对话中，告知当前有哪些任务仍在监控，防止 LLM 失忆

## 命令

### `/OpenAaaS-tasks`

弹出面板显示当前会话中的任务（包括终态任务，最多 20 个），按 `Escape` 或 `Ctrl+C` 关闭，30 秒无操作自动关闭。

## 注册约束

- 每个服务器别名可以独立注册。如果**当前服务器**已有 `api_key`，说明已完成注册，**请勿重复调用 `register`**
- 如需修改用户名，请使用 `update_profile`（示例：`OpenAaaS(action: "update_profile", name: "new-name")`）
- **`name` 参数约束**：长度不超过 64 个字符，不能包含控制字符及以下非法字符：`/ \ < > | & ; $`
- **服务器地址保护**：`set_server_url` 不会自动覆盖已有注册信息的服务器。如果该服务器已有 `api_key`，修改地址会被阻止，防止意外丢失注册信息
- 如需切换到新服务器地址，请使用新的 `server` 别名（多服务器配置），或先用 `remove_server` 删除旧配置
- **删除服务器**：如需删除某个服务器配置，使用 `remove_server`。注意不能删除默认服务器，删除前需先用 `set_default_server` 切换默认服务器

## 使用示例

1. 设置服务器地址（可选，默认 https://api.open-aaas.com）：
   ```
   OpenAaaS(action: "set_server_url", server_url: "https://www.open-aaas.com")
   ```

   可选：发现服务端信息：
   ```
   OpenAaaS(action: "discover")
   ```

1.5. 切换到其他服务器操作：
   ```
   OpenAaaS(action: "list_services", server: "prod")
   OpenAaaS(action: "submit_task", server: "local", service_id: "my-service", task_prompt: "...")
   ```

2. 注册客户端：
   ```
   OpenAaaS(action: "register", name: "my-client")
   ```

3. 列出服务并筛选候选：
   ```
   OpenAaaS(action: "list_services")
   ```

4. 对目标服务获取详细 usage：
   ```
   OpenAaaS(action: "get_service_usage", service_id: "my-service")
   ```

5. 提交任务（带文件上传）：
   ```
   OpenAaaS(
     action: "submit_task",
     service_id: "my-service",
     task_prompt: "分析数据",
     output_prompt: "返回 JSON",
     input_files: ["./data.csv"],
     session_id: "可选，用于保持对话上下文"
   )
   ```
   文件上传限制：最多支持 10 个文件，单文件不超过 100MB；只能上传当前工作目录下的文件，不支持符号链接。

6. 列出当前 Session 任务历史：
   ```
   OpenAaaS(action: "list_history")
   ```

7. 查询任务（仅在用户要求时调用）：
   ```
   OpenAaaS(action: "get_task", task_id: "xxx")
   ```

8. 下载结果：
   ```
   OpenAaaS(action: "download_result", task_id: "xxx")
   ```

9. 删除服务器配置：
   ```
   OpenAaaS(action: "remove_server", server: "old-server")
   ```