慧企星助开放平台文档

网盘接口

网盘接口需要 disk.read（查询）与 disk.write（新建、编辑、重命名、删除、移动、共享、文件入库）权限，依赖企业套餐网盘模块。网盘范围统一使用字符串枚举 scope：personal 个人网盘、enterprise 企业网盘；被操作对象类型使用 entryType：folder 文件夹、file 文件；操作记录范围使用 recordScope：mine 我的记录、enterprise 企业记录、shared 共享给我的记录。文件入库必须先用附件上传接口取得临时资源 url 再调用入库接口；文件打包下载暂未通过开放平台开放（工作台内可用）。

必填请求头：网盘全部接口（含查询）都必须通过 X-Employee-Virtual-Id 指定当前操作人，接口只返回该员工可见范围内的数据。未传或无效时返回 403，错误信息为“请通过 X-Employee-Virtual-Id 指定当前操作人”。

写请求约定：所有 POST、PATCH 请求还需携带 UUID 格式的 X-Client-Request-Id；同一业务重试必须复用同一请求标识，并重新生成 X-Nonce、X-Timestamp 与签名。

异步说明：共享与取消共享通过消息队列异步处理，接口返回成功仅表示请求已入队，最终状态请以操作记录或再次查询为准；其余写操作同步返回业务结果。

GET /api/openplatform/disk/info

查询当前操作人的网盘容量信息与快捷入口。不分页，data 直接返回容量对象。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "personalInfo": {
      "usedStr": "12.4MB",
      "totalStr": "2.0GB",
      "percent": 0.61,
      "used": 13002342,
      "total": 2147483648,
      "count": 18,
      "enable": true
    },
    "enterpriseInfo": {
      "usedStr": "1.2GB",
      "totalStr": "20.0GB",
      "percent": 6.0,
      "used": 1288490188,
      "total": 21474836480,
      "count": 236,
      "enable": true
    },
    "sharedWithMeCount": 3,
    "quickAccessList": [
      { "id": "1a2b3c4d-5e6f-4a5b-8c9d-0e1f2a3b4c5d", "name": "项目资料" }
    ]
  }
}

响应字段

字段	类型	说明
`personalInfo`	CloudInfo	个人网盘容量信息。
`enterpriseInfo`	CloudInfo	企业网盘容量信息。
`sharedWithMeCount`	int	共享给我的文件/文件夹数量。
`quickAccessList`	array	当前操作人的快捷入口列表，每项含 `id`（文件夹 Id）与 `name`（名称）；未设置时为空数组。

CloudInfo 字段

字段	类型	说明
`used`	decimal	已使用容量，单位字节。
`total`	decimal	总容量，单位字节。
`usedStr`	string	已使用容量的格式化文案，如 `12.4MB`。
`totalStr`	string	总容量的格式化文案，如 `2.0GB`。
`percent`	decimal	已使用占比。
`count`	int	文件数量。
`enable`	bool	该网盘是否启用。

GET /api/openplatform/disk/statistic

查询企业维度的网盘容量统计。不分页，data 为固定 6 个元素的数组，单位为 MB。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": [
    { "count": 12.4 },
    { "count": 2035.6 },
    { "count": 1228.0 },
    { "count": 18772.0 },
    { "count": 2048.0 },
    { "count": 19952.0 }
  ]
}

数组元素顺序

下标	含义
`0`	个人网盘已使用（MB）。
`1`	个人网盘未使用（MB）。
`2`	企业网盘已使用（MB）。
`3`	企业网盘未使用（MB）。
`4`	个人网盘总量（MB）。
`5`	企业网盘总量（MB）。

GET /api/openplatform/disk/folders

查询指定网盘范围下的文件夹列表。不传 id 时返回顶级文件夹，传入时返回该文件夹下的子级。

参数	类型	必填	说明
`scope`	string	否	网盘范围，字符串枚举：`personal` 个人网盘、`enterprise` 企业网盘，默认 `personal`。传其它值返回 `400`，错误信息为“scope 必须为 personal 或 enterprise”。
`id`	guid	否	父文件夹 Id，不传表示顶级。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "total": 12,
    "page": 1,
    "pageSize": 1,
    "items": [
      {
        "id": "1a2b3c4d-5e6f-4a5b-8c9d-0e1f2a3b4c5d",
        "name": "项目资料",
        "color": "#4A90D9",
        "count": 12,
        "type": 1,
        "fileType": 1,
        "isFolder": true,
        "isShare": false,
        "level": 1,
        "mySelf": true,
        "role": 1,
        "isHasChild": true,
        "isPermitEdit": true,
        "isPermitDelete": true,
        "isPermitDown": true
      }
    ]
  }
}

分页说明：本接口返回统一分页结构 total、page、pageSize、items，但不接收分页参数，一次返回该层级的全部文件夹：page 恒为 1，pageSize 为本次实际返回的文件夹条数，total 为本层级文件夹总数。

文件夹字段

字段	类型	说明
`id`	guid	文件夹 Id，用于列表、树、详情和各类动作路径。
`name`	string	文件夹名称。
`color`	string	文件夹颜色；未设置时为空字符串。
`count`	int	直属附件数量。
`type`	int	所属网盘：1 个人网盘、2 企业网盘。
`fileType`	int	对象类型：1 文件夹、2 文件。
`isFolder`	bool	是否为文件夹。
`isShare`	bool	是否已共享出去。
`level`	int	当前层级。
`mySelf`	bool	是否归属当前操作人。
`role`	int	当前操作人在该对象中的角色：0 无、1 个人网盘所有者、2 个人网盘被共享者、3 企业网盘创建者、4 企业网盘可见成员。
`isHasChild`	bool	是否还有下级。
`hasNew` / `hasEnterNew`	bool	个人/企业维度是否有更新内容。
`isPermitEdit` / `isPermitDelete` / `isPermitDown`	bool	当前操作人是否具备编辑、删除、下载权限。
`users`	array	共享用户信息，每项以 `virtualId` 标识员工；未共享时为空数组。
`sharedWith`	object[]	共享员工在本 API Key 下的成员对象（含 `virtualId`、`name` 与掩码 `phone`）数组，与 `users` 同源（共享接口入参仍为 `sharedEmployeeVirtualIds`）；未共享时为空数组。

GET /api/openplatform/disk/files

分页查询文件夹下的文件与文件夹列表。文件夹排在文件之前。

参数	类型	必填	说明
`id`	guid	否	父文件夹 Id，不传表示顶级。
`scope`	string	否	网盘范围：`personal` 个人网盘、`enterprise` 企业网盘，默认 `personal`。传其它值返回 `400`。
`keyword`	string	否	名称关键字。传值时在指定范围内按名称模糊搜索；不传时按父文件夹逐层浏览。
`order`	string	否	排序字段，与工作台网盘列表口径一致；不传时按修改时间倒序。
`sort`	string	否	排序方向，与 `order` 配套使用。
`page`	int	否	页码，默认 1。
`pageSize`	int	否	每页条数，默认 20，最大 100。

企业网盘权限：查询 scope=enterprise 时，当前操作人必须具备企业网盘查看权限，否则返回错误信息“无权限查看”。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "total": 2,
    "page": 1,
    "pageSize": 20,
    "items": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "季度复盘.pdf",
        "size": 204800,
        "sizeStr": "200KB",
        "format": "pdf",
        "uploadTime": "2026-09-14T10:20:00+08:00",
        "updatedAt": "2026-09-15T09:05:00+08:00",
        "isFolder": false,
        "isImage": false,
        "thumbnail": "",
        "url": "https://cdn.example.com/disk/20260914/quarter.pdf",
        "type": 1,
        "employeeVirtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz",
        "mySelf": true,
        "isShare": false,
        "level": 2,
        "role": 1,
        "isPermitEdit": true,
        "isPermitDelete": true,
        "isPermitDown": true
      }
    ]
  }
}

列表响应字段

字段	类型	说明
`data.total`	long	符合筛选条件的总数。
`data.page`	int	当前页码，从 1 开始。
`data.pageSize`	int	当前页返回条数上限，范围为 1 到 100。
`data.items`	DiskEntry[]	当前页的文件与文件夹列表。

DiskEntry 字段

字段	类型	说明
`id`	guid	文件或文件夹 Id，用于详情、重命名、删除、移动和共享路径。
`name`	string	文件或文件夹名称。
`isFolder`	bool	是否为文件夹。
`size`	decimal	文件大小，单位字节；文件夹为其下文件合计大小。
`sizeStr`	string	文件大小的格式化文案，如 `200KB`。
`format`	string	文件扩展名；文件夹为空。
`url`	string	文件访问地址（按当前操作人权限签发）；文件夹为空。
`thumbnail`	string	缩略图地址；非图片或无缩略图时为空。
`isImage`	bool	是否为图片。
`uploadTime`	string	上传时间。
`updatedAt`	string	最近修改时间。
`employeeVirtualId`	string	归属员工在本 API Key 下的 `virtualId`。
`uploadName`	string	上传人姓名。
`type`	int	所属网盘：1 个人网盘、2 企业网盘。
`mySelf`	bool	是否归属当前操作人。
`isShare`	bool	是否已共享出去。
`level`	int	当前层级。
`role`	int	当前操作人的角色，取值同文件夹列表：0 无、1 所有者、2 被共享者、3 企业创建者、4 企业可见成员。
`isPermitEdit` / `isPermitDelete` / `isPermitDown`	bool	当前操作人是否具备编辑、删除、下载权限。
`isQuickAccess`	bool	是否已加入快捷入口。
`users`	array	共享用户信息，每项以 `virtualId` 标识员工；未共享时为空数组。
`sharedWith`	object[]	共享员工在本 API Key 下的成员对象（含 `virtualId`、`name` 与掩码 `phone`）数组，与 `users` 同源（共享接口入参仍为 `sharedEmployeeVirtualIds`）；未共享时为空数组。

共享信息口径：共享用户请统一读取 users 或 sharedWith 成员对象中的 virtualId，与员工接口返回的 virtualId 同一口径；响应中不会返回员工真实 Id。

GET /api/openplatform/disk/tree

查询文件夹树形结构，用于选择目标文件夹或展示目录层级。不分页。

参数	类型	必填	说明
`id`	guid	否	父文件夹 Id，不传表示从顶级开始。
`scope`	string	否	网盘范围：`personal` 个人网盘、`enterprise` 企业网盘，默认 `personal`。传其它值返回 `400`。
`name`	string	否	节点名称过滤关键字，不传返回全部节点。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": [
    {
      "id": "1a2b3c4d-5e6f-4a5b-8c9d-0e1f2a3b4c5d",
      "type": 1,
      "name": "项目资料",
      "hasChildren": true
    }
  ]
}

树节点字段

字段	类型	说明
`id`	guid	文件夹 Id。
`type`	int	所属网盘：1 个人网盘、2 企业网盘。
`name`	string	节点名称。
`hasChildren`	bool	是否还有下级文件夹。

GET /api/openplatform/disk/files/{id}

查询文件或文件夹详情。不分页。id 可传文件 Id 或文件夹 Id。

路径参数：

参数	类型	必填	说明
`id`	guid	是	文件或文件夹 Id。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "季度复盘.pdf",
    "sizeStr": "200KB",
    "url": "https://cdn.example.com/disk/20260914/quarter.pdf",
    "type": 1,
    "employeeVirtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz",
    "routeList": [
      { "id": "1a2b3c4d-5e6f-4a5b-8c9d-0e1f2a3b4c5d", "name": "项目资料" }
    ]
  }
}

详情包含上述 DiskEntry 的全部字段，并额外包含以下字段。

字段	类型	说明
`routeList`	array	当前对象所在的文件夹路径，从上级到下级排列，每项含 `id` 与 `name`；顶级对象为空数组。

GET /api/openplatform/disk/operations

分页查询网盘操作记录，按操作日期分组，组内按记录时间倒序。

参数	类型	必填	说明
`id`	guid	否	文件或文件夹 Id，传入时只返回该对象及其下级的操作记录；不传返回全部可见记录。
`recordScope`	string	否	记录范围，字符串枚举：`mine` 我的记录、`enterprise` 企业记录、`shared` 共享给我的记录。不传查询全部范围。传其它值返回 `400`，错误信息为“recordScope 必须为 mine、enterprise 或 shared”。
`page`	int	否	页码，默认 1。
`pageSize`	int	否	每页条数，默认 20，最大 100。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "total": 1,
    "page": 1,
    "pageSize": 20,
    "items": [
      {
        "operateDate": "2026-09-15T00:00:00+08:00",
        "recordList": [
          {
            "name": "季度复盘.pdf",
            "content": "重命名了文件",
            "operateTypeStr": "重命名",
            "recordedAt": "2026-09-15T09:05:00+08:00",
            "employeeVirtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz"
          }
        ]
      }
    ]
  }
}

操作记录分组字段

字段	类型	说明
`data.total`	long	符合筛选条件的记录总数。
`data.items`	array	按操作日期分组的记录集合。
`operateDate`	string	操作日期（分组键）。
`recordList`	array	当天的操作记录明细，含对象名称 `name`、操作内容 `content`、操作时间 `recordedAt` 与操作人 `employeeVirtualId`；字段口径与工作台操作记录一致。

POST /api/openplatform/disk/folders

新建文件夹，同步生效。新建企业网盘文件夹时，当前操作人需具备企业网盘编辑权限。

字段	类型	必填	说明
`name`	string	是	文件夹名称，不能为空；为空时返回 `400`，错误信息为“文件夹名称不能为空”。
`scope`	string	否	网盘范围：`personal` 个人网盘、`enterprise` 企业网盘，默认 `personal`。传其它值返回 `400`。
`parentId`	guid	否	父文件夹 Id，不传或传 `null` 表示建在顶级。
`color`	string	否	文件夹颜色，如 `#4A90D9`；不传使用默认色。

{
  "name": "项目资料",
  "scope": "enterprise",
  "parentId": null,
  "color": "#4A90D9"
}

字段约定：可选的 guid 字段（如 parentId）没有值时请直接省略或显式传 null，不要传空字符串 ""。

{
  "statusCode": 100,
  "msg": "操作成功"
}

PATCH /api/openplatform/disk/folders/{id}

编辑文件夹的名称与颜色。请求体不能为空，否则返回 400。

路径参数：

参数	类型	必填	说明
`id`	guid	是	文件夹 Id。

请求体参数：

字段	类型	必填	说明
`name`	string	否	文件夹名称；不传时不做修改。
`color`	string	否	文件夹颜色；不传时不做修改。
`scope`	string	否	网盘范围：`personal` 个人网盘、`enterprise` 企业网盘，默认 `personal`。传其它值返回 `400`。请与目标文件夹实际所属网盘保持一致。

请求示例：

{
  "name": "2026 项目资料",
  "color": "#4A90D9",
  "scope": "enterprise"
}

响应示例：

{
  "statusCode": 100,
  "msg": "操作成功"
}

POST /api/openplatform/disk/files

将已上传的临时资源保存到网盘（文件入库）。调用前先通过 POST /api/openplatform/attachments 上传文件取得 url。

字段	类型	必填	说明
`url`	string	是	附件上传接口返回的临时资源地址；为空时返回 `400`，错误信息为“文件资源地址不能为空”。
`folderId`	guid	否	目标文件夹 Id，不传或传 `null` 表示保存到顶级。
`scope`	string	否	网盘范围：`personal` 个人网盘、`enterprise` 企业网盘，默认 `personal`。传其它值返回 `400`。

{
  "url": "https://cdn.example.com/task/20260617/demo.pdf",
  "folderId": "1a2b3c4d-5e6f-4a5b-8c9d-0e1f2a3b4c5d",
  "scope": "personal"
}

{
  "statusCode": 100,
  "msg": "操作成功"
}

入库链路：文件二进制内容不经过本接口，必须先走附件上传通道。附件上传要求见「附件接口」，其中 REST 上传单文件最大 100MB，个人 MCP 上传单文件最大 10MB。

POST /api/openplatform/disk/files/{id}/actions/rename

重命名文件或文件夹，id 可传文件 Id 或文件夹 Id。

路径参数：

参数	类型	必填	说明
`id`	guid	是	文件或文件夹 Id。

请求体参数：

字段	类型	必填	说明
`value`	string	是	新名称；为空时返回 `400`，错误信息为“名称不能为空”。

请求示例：

{
  "value": "2026 季度复盘.pdf"
}

响应示例：

{
  "statusCode": 100,
  "msg": "操作成功"
}

POST /api/openplatform/disk/files/actions/delete

批量删除文件或文件夹。删除文件夹会连带删除其下内容，请谨慎调用。

字段	类型	必填	说明
`ids`	guid[]	是	被删除对象 Id 数组，至少 1 个；为空时返回 `400`，错误信息为“删除对象不能为空”。请直接传真正的 JSON 数组，不要传数组序列化后的字符串。
`scope`	string	否	网盘范围：`personal` 个人网盘、`enterprise` 企业网盘，默认 `personal`。传其它值返回 `400`。

{
  "ids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "b2c3d4e5-f6a7-8901-bcde-f23456789012"
  ],
  "scope": "personal"
}

{
  "statusCode": 100,
  "msg": "操作成功"
}

注意事项：删除为不可逆操作，接口返回成功即已生效，不会进入回收站二次确认。

POST /api/openplatform/disk/files/actions/move

批量移动文件或文件夹到目标文件夹。一次请求中的被移动对象必须同为一种类型。

字段	类型	必填	说明
`sourceIds`	guid[]	是	被移动对象 Id 数组，至少 1 个；为空时返回 `400`，错误信息为“被移动对象不能为空”。请直接传真正的 JSON 数组。
`targetFolderId`	guid	是	目标文件夹 Id。
`entryType`	string	否	被移动对象类型：`folder` 文件夹、`file` 文件，默认 `file`。传其它值返回 `400`，错误信息为“entryType 必须为 folder 或 file”。
`sourceScope`	string	否	来源网盘范围：`personal`、`enterprise`，默认 `personal`。
`targetScope`	string	否	目标网盘范围：`personal`、`enterprise`，默认 `personal`。跨网盘移动时与 `sourceScope` 取不同值。

请求示例 1：同级移动文件

{
  "sourceIds": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
  "targetFolderId": "1a2b3c4d-5e6f-4a5b-8c9d-0e1f2a3b4c5d",
  "entryType": "file",
  "sourceScope": "personal",
  "targetScope": "personal"
}

请求示例 2：把个人网盘文件移动到企业网盘

{
  "sourceIds": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
  "targetFolderId": "1a2b3c4d-5e6f-4a5b-8c9d-0e1f2a3b4c5d",
  "entryType": "file",
  "sourceScope": "personal",
  "targetScope": "enterprise"
}

响应示例：

{
  "statusCode": 100,
  "msg": "操作成功"
}

POST /api/openplatform/disk/folders/{id}/actions/share

把文件夹共享给指定员工，走消息队列异步处理，返回成功仅表示已入队。

路径参数：

参数	类型	必填	说明
`id`	guid	是	被共享的文件夹 Id，不能为空；为空时返回 `400`，错误信息为“共享对象不能为空”。

请求体参数：

字段	类型	必填	说明
`sharedEmployeeVirtualIds`	string[]	是	共享对象的员工 `virtualId` 数组，至少 1 个，来自员工接口；为空时返回 `400`，错误信息为“共享对象列表不能为空”。包含无法解析的 `virtualId` 时返回 `400`。
`isPermitEdit`	bool	否	是否允许被共享人编辑，默认 `false`。
`isPermitDelete`	bool	否	是否允许被共享人删除，默认 `false`。
`isPermitDown`	bool	否	是否允许被共享人下载，默认 `false`。

请求示例：

{
  "sharedEmployeeVirtualIds": ["emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz"],
  "isPermitEdit": false,
  "isPermitDelete": false,
  "isPermitDown": true
}

响应示例：

{
  "statusCode": 100,
  "msg": "操作成功"
}

异步生效：共享请求进入消息队列后由后台消费，接口返回成功不代表共享已立即生效；需要确认结果时请查询操作记录或重新拉取文件夹详情。

POST /api/openplatform/disk/folders/{id}/actions/cancelShare

取消文件夹共享，与共享一样走消息队列异步处理。接口不接收请求体。

路径参数：

参数	类型	必填	说明
`id`	guid	是	被取消共享的文件夹 Id，不能为空；为空时返回 `400`，错误信息为“取消共享对象不能为空”。

POST /api/openplatform/disk/folders/1a2b3c4d-5e6f-4a5b-8c9d-0e1f2a3b4c5d/actions/cancelShare
Host: your-domain.com
Content-Type: application/json
X-Employee-Virtual-Id: emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz
X-Client-Request-Id: 0f1e2d3c-4b5a-6978-8796-a5b4c3d2e1f0

响应示例：

{
  "statusCode": 100,
  "msg": "操作成功"
}

MCP 工具 disk_query

网盘查询工具，需要 disk.read 权限，覆盖上述全部 GET 查询能力。queryType 取值：info 容量信息、folders 文件夹列表、files 文件列表（分页）、tree 文件夹树、detail 详情、statistic 容量统计、records 操作记录。

{
  "queryType": "files",
  "scope": "personal",
  "folderId": "1a2b3c4d-5e6f-4a5b-8c9d-0e1f2a3b4c5d",
  "page": 1,
  "pageSize": 20
}

参数映射：folderId 对应 REST 的 id；scope 与 recordScope 的取值与 REST 完全一致；分页响应结构与 REST 同口径，queryType 为 folders 时 total 为本层级文件夹总数。

MCP 工具 disk_action

网盘写操作工具，需要 disk.write 权限，覆盖上述全部写接口。action 取值：addFolder 新建文件夹、rename 重命名、delete 删除、move 移动、share 共享、cancelShare 取消共享、upload 文件入库。

{
  "action": "share",
  "folderId": "1a2b3c4d-5e6f-4a5b-8c9d-0e1f2a3b4c5d",
  "sharedEmployeeVirtualIds": ["emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz"],
  "isPermitDown": true
}

调用约束：企业网盘操作需要相应权限；删除、移动、共享等会影响他人可见内容的操作，调用前必须把操作对象展示给用户并取得明确确认。单次 ids、sourceIds、sharedEmployeeVirtualIds 最多 50 个。