ListItems 列出文件-表格存储 Tablestore(Tablestore)-阿里云帮助中心

使用 ListItems 接口列出文件记忆库中指定路径前缀下的文件或目录前缀。

前提条件

已创建 AgentStorage 实例且状态为 normal，并获取实例访问地址（endpoint）和实例名。
已创建 API Key。
文件操作使用精确 Scope，scope 的四级字段（appId、tenantId、agentId、runId）全部必填，不支持通配符 *。
需要读取文件内容时设置 view=full。

请求参数

字段	类型	必填	说明
`pathPrefix`	string	否	只列出指定路径前缀；目录前缀以 `/` 结尾
`depth`	int	否	`0` 返回全部后代；`1` 把更深层目录折叠为前缀项
`view`	string	否	`basic` 或 `full`
`limit`	int	否	默认 20，最大 100；`view=full` 时最大 20
`nextToken`	string	否	上一页返回的不透明令牌

请求示例

使用 API Key 认证时，通过 x-ots-instancename 和 x-ots-apikey 请求头传入实例名和 API Key。

curl -X POST https://<endpoint>/ListItems \
  -H "x-ots-instancename: <instance-name>" \
  -H "x-ots-apikey: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "run-001"
  },
  "pathPrefix": "/profile/",
  "depth": 1,
  "limit": 20
}'

响应

响应中的前缀项使用 type=memoryfile_prefix。二进制文件项返回 mediaType，但即使使用 view=full 也不返回 contentBase64；需要读取二进制正文时，应按 itemId 调用 GetItem。

{
  "items": [
    {
      "type": "memoryfile",
      "itemId": "mem_01M2N31...",
      "path": "/profile/preferences.md",
      "contentSha256": "2aea3c51...",
      "contentSizeBytes": 24
    },
    {
      "type": "memoryfile_prefix",
      "path": "/profile/notes/"
    }
  ],
  "type": "memoryfile",
  "nextToken": "<next-token>"
}

以 messages 作为输入、输出包含 file 的记忆库只支持精确 Scope，响应顶层包含 readOnly=true；应用应把该标记传递给文件操作层，避免发起写请求。