智能助理工作区目录设计

​

工作区目录索引

​

什么时候使用 projects

• 该实体拥有独立的一组输入文件、解析结果和导出文件；
• 主智能体与多个子智能体需要读取同一组文件；
• 多个显式连接到同一平台项目的智能助理需要共享这些文件；
• 同一实体可以拥有多条会话，但不同实体之间必须隔离；
• 用户需要在平台项目列表中看到、进入、归档和恢复这个空间；
• 插件希望智能体的文件理解工具默认搜索当前实体的全部项目文件。

​

两层文件共享模型

​

产品对象与身份模型

type WorkspaceSyncStatus = 'provisioning' | 'ready' | 'failed'

type PluginBusinessEntity = {
  id: string
  workspaceProjectId: string
  workspaceSyncStatus: WorkspaceSyncStatus
  workspaceSyncError: string | null
}

​

创建与同步生命周期

1. 生成 businessEntityId 和 workspaceProjectId。
2. 保存业务实体，状态为 provisioning。
3. 调用 platform.project.provisioning.ensure(...)。
4. 平台以调用方提供的 workspaceProjectId 创建或校正平台项目，并连接预期的智能助理。
5. 所有必要连接成功后置为 ready；失败后置为 failed 并保存可展示的错误。
6. 只有 ready 状态允许上传文件或启动依赖文件的工作流。

const projects = runtimeCapabilities.require(ProjectProvisioningRuntimeCapability)

for (const assistantId of connectedAssistantIds) {
  await projects.ensure({
    projectId: entity.workspaceProjectId,
    workspaceId,
    xpertId: assistantId,
    name: entity.name,
    status: entity.archivedAt ? 'archived' : 'active'
  })
}

​

文件目录与可移植引用

files/<plugin-key>/
├── sources/<source-id>/...
├── generated/...
├── previews/...
└── exports/...

const uploaded = await workspaceFiles.uploadBuffer({
  catalog: 'projects',
  scopeId: entity.workspaceProjectId,
  projectId: entity.workspaceProjectId,
  buffer,
  originalName,
  mimeType,
  folder: `files/${pluginKey}/sources/${sourceId}`
})

{
  source: 'platform.workspace.files',
  catalog: 'projects',
  scopeId: workspaceProjectId,
  projectId: workspaceProjectId,
  filePath: uploaded.filePath,
  workspacePath: uploaded.workspacePath,
  originalName,
  mimeType,
  size
}

​

文件解析与智能体文件理解

const understood = await workspaceFiles.understandFile({
  ...portableReference,
  purpose: 'workspace',
  parseMode: 'deep',
  runInline: false
})

await sourceVersionRepository.save({
  fileReference: portableReference,
  fileAssetId: understood.fileAssetId
})

​

会话与智能体运行绑定

team:
  options:
    workspaceScope:
      mode: project-required

• 每个已连接智能助理的新建或恢复主会话；
• 插件启动的智能助理任务；
• 工作流中的专业子智能体；
• 跨智能助理交接、重试和手工重跑；
• 沙箱和运行时工作区文件操作。

1. 当前平台项目的全部文件资产；
2. 当前会话的显式附件；
3. 两者去重后的结果。

​

工作台导航与会话恢复

await invokeClientCommand('workbench.navigation.open', {
  target: 'assistant.project',
  projectId: entity.workspaceProjectId
})

​

权限与信任边界

• 工作区目录、租户、组织、用户、平台项目和智能助理身份必须来自可信运行时或服务端业务映射，不得由模型自由填写。
• 智能体可见工具参数中不要暴露 tenantId、catalog、scopeId、projectId 或 xpertId。
• 每次读、写、解析、搜索、预览和下载都重新校验插件领域权限、用户项目成员身份和当前智能助理与项目的显式连接。
• 平台项目权限不替代插件领域权限；插件仍需验证当前用户能否访问对应业务实体。
• 业务 scopeKey 仍按智能助理/Xpert 隔离。运行时项目标识符只决定工作区作用域，不应改变插件业务数据的智能助理隔离键。
• 不要在错误消息中区分“其他平台项目中存在”与“完全不存在”。

​

失败状态与用户体验

​

上线与迁移

​

验收清单

• 一个业务实体只对应一个稳定的 workspaceProjectId，重试不创建重复平台项目。
• 平台项目列表中可见该项目，并连接所有预期智能助理。
• 两个已连接智能助理无需复制文件即可搜索、读取和预览同一文件资产。
• 未连接的智能助理即使获得项目或文件资产标识符也不能访问文件。
• 已连接智能助理共享项目文件，但分别保留 xpertId + projectId 会话历史。
• 业务改名、归档和恢复能同步到平台项目。
• 上传文件、可移植引用、文件资产和导出文件都属于映射的平台项目。
• 主智能体、解读智能体、规划智能体和编写智能体能搜索同一项目文件。
• 另一个平台项目的文件资产标识符不可读取，也不泄露存在性。
• 会话的平台项目绑定不可变。
• project-required 智能助理在无平台项目时拒绝依赖文件的运行。
• 不使用平台项目的智能助理仍保持原有会话或 xperts 行为。

​

后续目录说明模板

1. 作用域身份：目录由哪个稳定标识符定位？是否还需要 scopeId？
2. 所有权：归用户、智能助理、组织、知识库还是其他产品对象所有？
3. 生命周期：创建、改名、归档、恢复和删除由谁驱动？
4. 共享模型：哪些会话、智能体、智能助理、用户或插件可以看见同一文件集合？
5. 运行时选择：如何从可信上下文选中该目录？缺失时是否允许回退？
6. 文件理解：文件资产的可见集合、附件合并和去重规则是什么？
7. 权限边界：租户、组织、用户和领域权限如何共同校验？
8. 路径约定：插件如何分配目录，哪些引用可以持久化？
9. 保留与迁移：旧目录文件如何迁移，删除和合规策略是什么？
10. 验收矩阵：同范围共享、跨范围隔离、重试幂等和回归行为如何验证？