OpenAaaS pi Extension

为 pi 开发的 OpenAaaS 扩展，提供统一的 OpenAaaS 工具，用于服务发现、客户端注册、任务提交及结果下载。

安装

pi install npm:open-aaas-pi-extension

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

配置文件

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

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

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

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

注册成功后的配置示例：

{
  "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 参数指定目标服务器。

为多个服务器分别注册

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

# 在 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 计算）分档——提交后立即轮询一次，02 分钟每 10 秒，210 分钟每 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")