benchgo-plugin 0.0.0-stage → 0.0.2

package/openapi.json

@@ -0,0 +1,629 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "BenchGo Harness 工具管理",
+    "version": "1.2.0",
+    "description": "官方 owner 通道的侧栏状态与工具设置接口；已配对工作台仅通过 Link 既有转发白名单访问。工具安装与本机配置写入仍受对应权限限制，不通过 MCP 向 Agent 暴露安装或配置写入权限。"
+  },
+  "servers": [
+    {
+      "url": "/"
+    }
+  ],
+  "paths": {
+    "/api/commander/tooling": {
+      "post": {
+        "summary": "管理工具、隔离会话方案与安装任务",
+        "description": "请求必须通过官方 owner 通道且 Origin 同源。安装、更新、重装均绑定系统真实安装来源；未知来源禁止自动更新或卸载。旧客户端携带的 source 字段仅为兼容，不改变来源选择；卸载需携带探测快照 snapshot 二次确认。本机配置写入需 confirmNativeWrite=true。",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ToolingRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "操作结果；安装操作立即返回异步 job，后续使用 job/cancel 查询或取消。",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ToolingResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "输入无效或操作失败；未知 source 拒绝，不静默回退。",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "非同源请求或未获 owner 授权。",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "方案冲突、缺少显式本机写入确认或工具仍在运行。",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "413": {
+            "description": "请求超过 300 KiB。",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "415": {
+            "description": "Content-Type 不是 application/json。",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/commander": {
+      "post": {
+        "summary": "原生会话与项目侧栏操作",
+        "description": "通过现有 owner 认证 Connection 通道调用。state 返回项目、会话、隐藏记录及可选能力状态；ensureRecent 恢复最近工作区。委派 loopback 监听或字体初始化失败不撤销本接口，capabilities 对应 available=false，并保留 error/code。损坏的用户持久化数据仍报错，不重置。其他会话操作保持既有语义。",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "action"
+                ],
+                "properties": {
+                  "action": {
+                    "type": "string",
+                    "enum": [
+                      "state",
+                      "ensureRecent",
+                      "binding",
+                      "browse",
+                      "clone",
+                      "dismiss",
+                      "doctor",
+                      "project",
+                      "models",
+                      "create",
+                      "start",
+                      "events",
+                      "adopt",
+                      "archive",
+                      "delete",
+                      "send",
+                      "connect",
+                      "interrupt",
+                      "steer",
+                      "close",
+                      "history",
+                      "approve"
+                    ]
+                  }
+                },
+                "additionalProperties": true
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "state 返回 SidebarState；ensureRecent 返回 RecentWorkspace；其他操作返回对应结果。",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "anyOf": [
+                    {
+                      "$ref": "#/components/schemas/SidebarState"
+                    },
+                    {
+                      "$ref": "#/components/schemas/RecentWorkspace"
+                    },
+                    {
+                      "type": "object",
+                      "additionalProperties": true
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "输入或操作失败；已有会话身份可随 session 字段返回。",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "BenchGo 存储或侧栏初始化失败（含数据目录占用、无法确认旧锁持有者或损坏持久状态）；明确报告原因，保留已有数据，不返回空会话或缺失路由 404。修复原因后需重启主机。",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "error",
+                    "code"
+                  ],
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    },
+                    "code": {
+                      "const": "COMMANDER_UNAVAILABLE"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "ToolingRequest": {
+        "type": "object",
+        "required": [
+          "action"
+        ],
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": [
+              "pickerCatalog",
+              "catalog",
+              "profiles",
+              "providers",
+              "models",
+              "job",
+              "install",
+              "update",
+              "reinstall",
+              "uninstallPreview",
+              "uninstall",
+              "cancel",
+              "setDefault",
+              "saveProfile",
+              "setBindings",
+              "preview",
+              "apply",
+              "restore"
+            ]
+          },
+          "tool": {
+            "type": "string"
+          },
+          "id": {
+            "type": "string",
+            "description": "安装任务 ID（job/cancel）"
+          },
+          "providerId": {
+            "type": "string"
+          },
+          "model": {
+            "type": "string"
+          },
+          "protocol": {
+            "type": "string"
+          },
+          "quickSettings": {
+            "type": "object"
+          },
+          "overrides": {
+            "type": "object"
+          },
+          "contextWindow": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "expectedRevision": {
+            "type": "string"
+          },
+          "revision": {
+            "type": "string"
+          },
+          "tools": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "confirmNativeWrite": {
+            "type": "boolean"
+          },
+          "checksums": {
+            "type": "object",
+            "additionalProperties": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          },
+          "backupId": {
+            "type": "string"
+          },
+          "snapshot": {
+            "type": "string"
+          },
+          "source": {
+            "type": "string",
+            "description": "卸载预览返回的实际安装来源；仅用于展示和任务结果。"
+          }
+        },
+        "allOf": [
+          {
+            "if": {
+              "properties": {
+                "action": {
+                  "enum": [
+                    "install",
+                    "update",
+                    "reinstall"
+                  ]
+                }
+              }
+            },
+            "then": {
+              "required": [
+                "tool"
+              ],
+              "properties": {}
+            }
+          },
+          {
+            "if": {
+              "properties": {
+                "action": {
+                  "enum": [
+                    "uninstall",
+                    "setDefault",
+                    "saveProfile",
+                    "preview",
+                    "apply"
+                  ]
+                }
+              }
+            },
+            "then": {
+              "required": [
+                "tool"
+              ]
+            }
+          },
+          {
+            "if": {
+              "properties": {
+                "action": {
+                  "enum": [
+                    "job",
+                    "cancel"
+                  ]
+                }
+              }
+            },
+            "then": {
+              "required": [
+                "id"
+              ]
+            }
+          }
+        ]
+      },
+      "ToolSummary": {
+        "type": "object",
+        "required": [
+          "id"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "installer": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "canInstall": {
+            "type": "boolean"
+          },
+          "canUpdate": {
+            "type": "boolean"
+          },
+          "canReinstall": {
+            "type": "boolean"
+          },
+          "canUninstall": {
+            "type": "boolean"
+          },
+          "job": {
+            "$ref": "#/components/schemas/InstallJob"
+          }
+        }
+      },
+      "InstallJob": {
+        "type": "object",
+        "required": [
+          "id",
+          "toolId",
+          "action",
+          "status"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "toolId": {
+            "type": "string"
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "install",
+              "update",
+              "reinstall",
+              "uninstall"
+            ]
+          },
+          "source": {
+            "type": "string",
+            "description": "实际探测到的安装来源。"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "queued",
+              "running",
+              "succeeded",
+              "failed",
+              "cancelled"
+            ]
+          },
+          "message": {
+            "type": "string",
+            "description": "当前阶段，如环境准备、工具安装或版本验证。"
+          },
+          "logs": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "error": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        }
+      },
+      "NativeConfigFileStatus": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "exists": {
+            "type": "boolean"
+          },
+          "unavailable": {
+            "type": "boolean"
+          },
+          "externalChanged": {
+            "type": "boolean",
+            "description": "与最近一次显式同步后的 SHA-256 不同；仅报告，不自动覆盖。"
+          }
+        },
+        "additionalProperties": true
+      },
+      "NativeToolStatus": {
+        "type": "object",
+        "properties": {
+          "tool": {
+            "type": "string"
+          },
+          "lastSyncAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "files": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/NativeConfigFileStatus"
+            }
+          }
+        },
+        "additionalProperties": true
+      },
+      "ToolingResponse": {
+        "type": "object",
+        "properties": {
+          "native": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/NativeToolStatus"
+            },
+            "description": "只读原生配置状态。externalChanged 表示同步后发生改动，不触发自动合并或写入。"
+          },
+          "tools": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ToolSummary"
+            }
+          },
+          "job": {
+            "$ref": "#/components/schemas/InstallJob"
+          }
+        },
+        "description": "按 action 返回：catalog 含 tools/profiles/defaults/capabilities/backups/bindings/providerAccess；pickerCatalog 返回模型选择目录；profiles 返回方案目录；providers/models 返回对应列表；install/update/reinstall/uninstall/job/cancel 返回 job；saveProfile 返回 profile；preview 返回 preview；apply/restore 返回 result；setDefault/setBindings 返回方案管理结果。保留既有响应字段。"
+      },
+      "Error": {
+        "type": "object",
+        "required": [
+          "error"
+        ],
+        "properties": {
+          "error": {
+            "type": "string"
+          }
+        }
+      },
+      "OptionalWebCapability": {
+        "type": "object",
+        "required": [
+          "available"
+        ],
+        "properties": {
+          "available": {
+            "type": "boolean"
+          },
+          "error": {
+            "type": "string",
+            "description": "初始化失败的实际错误消息，仅不可用时存在。"
+          },
+          "code": {
+            "type": "string",
+            "description": "原始错误码，如 EACCES；原异常未提供时省略。"
+          }
+        },
+        "additionalProperties": false
+      },
+      "SidebarState": {
+        "type": "object",
+        "required": [
+          "projects",
+          "sessions",
+          "deletedHarnessIds",
+          "capabilities"
+        ],
+        "properties": {
+          "projects": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          },
+          "sessions": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          },
+          "deletedHarnessIds": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "capabilities": {
+            "type": "object",
+            "required": [
+              "delegation",
+              "fonts"
+            ],
+            "properties": {
+              "delegation": {
+                "$ref": "#/components/schemas/OptionalWebCapability"
+              },
+              "fonts": {
+                "$ref": "#/components/schemas/OptionalWebCapability"
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "additionalProperties": false
+      },
+      "RecentWorkspace": {
+        "type": "object",
+        "required": [
+          "workspaceId",
+          "path"
+        ],
+        "properties": {
+          "workspaceId": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      },
+      "UninstallPreview": {
+        "type": "object",
+        "required": [
+          "available",
+          "snapshot"
+        ],
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "realpath": {
+            "type": "string"
+          },
+          "source": {
+            "type": "string"
+          },
+          "version": {
+            "type": "string"
+          },
+          "command": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "snapshot": {
+            "type": "string"
+          },
+          "available": {
+            "type": "boolean"
+          }
+        }
+      }
+    }
+  }
+}