虚拟文件系统 API
在项目维度读取、解析、创建、重命名、移动、删除和恢复虚拟文件系统条目。
基础信息
- 基础路径：
/vfs/:projectId - 认证方式：JWT Bearer Token 或 API Key（combinedAuth）。写入类操作需要项目写权限。
端点
补充端点
本节补充 plans/need-update-api.md 中尚未覆盖到 docs-site 的接口。端点标题保持严格的 METHOD /path 格式，便于后台文档覆盖率服务识别。
DELETE /vfs/:projectId/entries/:entryId
删除 VFS 条目并移动到回收或墓碑流程。
认证：JWT Bearer Token 或 API Key（combinedAuth）。写入类操作需要项目写权限。 路径参数
| 参数 | 说明 |
|---|---|
projectId | 项目 ID |
entryId | 虚拟文件系统条目 ID |
请求：通常无请求体；删除类接口通过路径参数定位资源，部分接口会执行软删除、释放绑定或撤回流程。
响应：成功时返回 { "success": true } 或等价删除结果；资源不存在、无权限或存在依赖时返回 4xx。
常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。
GET /vfs/:projectId/ls
列出指定虚拟目录下的条目。
认证：JWT Bearer Token 或 API Key（combinedAuth）。写入类操作需要项目写权限。 路径参数
| 参数 | 说明 |
|---|---|
projectId | 项目 ID |
请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。
响应：成功时返回目标资源详情、状态或配置对象。
常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。
POST /vfs/:projectId/mkdir
创建虚拟目录。
认证：JWT Bearer Token 或 API Key（combinedAuth）。写入类操作需要项目写权限。 路径参数
| 参数 | 说明 |
|---|---|
projectId | 项目 ID |
请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。
响应：成功时返回创建或更新后的资源对象，或 { "success": true }。
常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。
PATCH /vfs/:projectId/move
移动资源。
认证：JWT Bearer Token 或 API Key（combinedAuth）。写入类操作需要项目写权限。 路径参数
| 参数 | 说明 |
|---|---|
projectId | 项目 ID |
请求：请求体为 JSON，传入需要变更的字段；未传字段保持不变。
响应：成功时返回创建或更新后的资源对象，或 { "success": true }。
常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。
PATCH /vfs/:projectId/rename
重命名资源。
认证：JWT Bearer Token 或 API Key（combinedAuth）。写入类操作需要项目写权限。 路径参数
| 参数 | 说明 |
|---|---|
projectId | 项目 ID |
请求：请求体为 JSON，传入需要变更的字段；未传字段保持不变。
响应：成功时返回创建或更新后的资源对象，或 { "success": true }。
常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。
GET /vfs/:projectId/resolve
按路径解析虚拟文件系统条目。
认证：JWT Bearer Token 或 API Key（combinedAuth）。写入类操作需要项目写权限。 路径参数
| 参数 | 说明 |
|---|---|
projectId | 项目 ID |
请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。
响应：成功时返回目标资源详情、状态或配置对象。
常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。
POST /vfs/:projectId/restore
恢复资源。
认证：JWT Bearer Token 或 API Key（combinedAuth）。写入类操作需要项目写权限。 路径参数
| 参数 | 说明 |
|---|---|
projectId | 项目 ID |
请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。
响应：成功时返回创建或更新后的资源对象，或 { "success": true }。
常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。
GET /vfs/:projectId/status
读取同步和挂载状态。
认证：JWT Bearer Token 或 API Key（combinedAuth）。写入类操作需要项目写权限。 路径参数
| 参数 | 说明 |
|---|---|
projectId | 项目 ID |
请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。
响应：成功时返回目标资源详情、状态或配置对象。
常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。
POST /vfs/:projectId/touch
创建虚拟文件条目。
认证：JWT Bearer Token 或 API Key（combinedAuth）。写入类操作需要项目写权限。 路径参数
| 参数 | 说明 |
|---|---|
projectId | 项目 ID |
请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。
响应：成功时返回创建或更新后的资源对象，或 { "success": true }。
常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。
GET /vfs/:projectId/tree
读取虚拟文件系统树。
认证：JWT Bearer Token 或 API Key（combinedAuth）。写入类操作需要项目写权限。 路径参数
| 参数 | 说明 |
|---|---|
projectId | 项目 ID |
请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。
响应：成功时返回目标资源详情、状态或配置对象。
常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。