{"api":{"base_url":"/api/v1","name":"OpenAaaS","version":"0.10.0"},"auth":{"header":"Authorization: Bearer {api_key}","type":"bearer"},"design_principles":{"progressive_disclosure":"信息渐进式披露：API 设计遵循'先摘要筛选，再按需详情'的原则。list_services 返回轻量列表（name + description + status），不占用上下文；get_service_usage 按需获取单个服务的详细用法说明。调用方应先浏览列表筛选候选，再对目标服务获取 usage，避免一次性加载大量长文本。"},"endpoints":[{"body":{"files":"binary (仅 multipart 支持，可选，可多个) - 输入文件","output_prompt":"string (必需) - 输出格式要求","service_id":"string (必需) - 服务ID","session_id":"string (可选) - 会话ID","task_prompt":"string (必需) - 任务描述"},"content_type":"application/json 或 multipart/form-data","method":"POST","name":"create_task","path":"/client/tasks","response":{"created_at":"ISO8601","id":"string","input":{"input_files":["string"],"output_prompt":"string","task_prompt":"string"},"status":"pending"}},{"method":"GET","name":"list_tasks","path":"/client/tasks?status=&service_id=&limit=20&offset=0"},{"method":"GET","name":"get_task","path":"/client/tasks/{id}"},{"limitation":"只能取消pending或running状态","method":"POST","name":"cancel_task","path":"/client/tasks/{id}/cancel"},{"body":{"name":"string (必需) - Client 名称，1-64字符，trim后不能为空"},"method":"POST","name":"register","note":"无需认证，首次调用生成 API Key","path":"/client/auth/register","response":{"api_key":"string - 保存好，后续请求需要使用","id":"string - Client ID"}},{"method":"GET","name":"list_services","note":"返回轻量列表（不含 usage 长文本），用于快速浏览和筛选服务。如需了解服务详细能力，请使用 get_service_usage 按需获取。public 服务自动可用；restricted 服务需要 has_permission=true 才能使用。","path":"/client/services","response":{"services":[{"access_type":"public|restricted","agent_last_heartbeat":"string|null - 最后心跳时间","agent_status":"online|offline|busy","description":"string|null","has_permission":"true|false","id":"string","name":"string","registration_status":"string - 注册状态"}]}},{"method":"GET","name":"get_service_usage","note":"渐进式披露的关键步骤：在 list_services 筛选出候选服务后，调用此接口获取目标服务的详细 usage（能力范围、调用规范、返回格式、限制条件）。usage 内容通常较长，只应在确定使用该服务时获取，避免占用上下文。","path":"/client/services/{id}/usage","response":{"id":"string","name":"string","usage":"string - 服务使用说明/用法"}},{"method":"GET","name":"download_file","path":"/client/files/{id}/download"},{"method":"GET","name":"list_files","path":"/client/files/list/{task_id}"},{"body":{"name":"string (必需) - 新用户名"},"method":"PUT","name":"update_profile","path":"/client/profile","response":{"api_key":"string (空 - 请从注册响应中保存)","created_at":"ISO8601","id":"string","name":"string","role":"string"}}],"errors":{"400":"请求参数错误","401":"认证失败","404":"资源不存在","409":"状态冲突"},"instructions":"你是一个 OpenAaaS 客户端代理。你的工作流程是：\n\n1. **认证**：如果用户没有 api_key，调用 register 获取并保存\n2. **浏览服务**：调用 list_services 获取轻量服务列表（id, name, description, agent_status）\n3. **了解服务**：对候选服务调用 get_service_usage 获取详细用法说明\n4. **提交任务**：根据 usage 说明构造 task_prompt 和 output_prompt，调用 submit_task\n5. **跟踪结果**：保存返回的 task_id。需要结果时调用 get_task 查询状态，或用 list_files + download_file 获取结果\n\n重要原则：\n- 遵循渐进式披露：先 list_services 筛选，再 get_service_usage 获取详情，避免一次性加载大量长文本\n- public 服务自动可用；restricted 服务需要 has_permission=true\n- 任务异步执行，提交后立即返回，不要立即阻塞轮询，待用户需要时再调用 get_task 查询状态\n- submit_task 使用 multipart/form-data，可附带文件","types":{"ServiceListItem":{"access_type":"public|restricted","agent_last_heartbeat":"string|null - 最后心跳时间","agent_status":"online|offline|busy","description":"string","has_permission":"true|false","id":"string","name":"string","registration_status":"string - 注册状态"},"ServiceUsage":{"id":"string","name":"string","usage":"string - 服务使用说明/用法"},"TaskInput":{"input_files":["string"],"output_prompt":"string","task_prompt":"string"}},"workflows":{"client_register":{"env_example":"OPEN_AAAS_API_KEY={api_key}","note":"这里的 .env 是调用 OpenAaaS API 的 client 项目配置，和 server、agent-core 的部署配置无关。","steps":["1. POST /client/auth/register - 注册获取 API Key","2. 保存返回的 api_key，用于后续请求认证","3. 建议在调用方项目目录写入 .env，例如 OPEN_AAAS_API_KEY={api_key}","4. GET /client/services - 获取轻量服务列表浏览可用服务","5. GET /client/services/{id}/usage - 按需获取目标服务的详细 usage","6. 如需使用受限服务，联系管理员授权"]},"submit_task":{"note":"任务执行时间从几分钟到几小时不等，提交后立即返回。**请勿轮询**。推荐使用 Dashboard 实时监控，或任务完成后再查询结果。","steps":["1. GET /client/services - 获取轻量服务列表（name/description/agent_status），浏览筛选候选","2. GET /client/services/{id}/usage - 对筛选出的候选服务，按需获取详细 usage（能力范围、调用规范）","3. 根据 usage 说明，构造正确的 task_prompt 和 output_prompt","4. POST /client/tasks - 创建任务（支持 application/json 和 multipart/form-data。JSON 方式不支持附件，如需上传文件请使用 multipart）","5. 保存返回的 task_id，任务在后台异步执行","6. 使用 Dashboard 查看进度，或稍后主动查询任务状态","7. GET /client/files/list/{task_id} - 获取结果文件列表","8. GET /client/files/{id}/download - 下载结果"]}}}