一、接口介绍
·列举范围：通过 path_prefix 指定目录前缀（可选）；不传或传空字符串 "" 时从根目录开始列举。
·递归返回：匹配前缀的范围内递归返回所有节点（文件与目录），不提供"仅列当前层级"的开关，也不提供分页。
·节点区分：返回项以 path 末尾是否带 / 区分——目录以 / 结尾，文件不带；文件项不返回正文，如需读取请用 read_scenario。
| 项 | 值 |
| HTTP 方法与路径 | POST /v2/scenario/ls |
| HTTP 文档 | 列出场景记忆 |
| 函数签名 | list_scenarios(*, path_prefix=None) |
二、使用示例
# 列举根目录全部节点result = client.list_scenarios()# 列举 "工作/" 目录下所有节点result = client.list_scenarios(path_prefix="工作/")for item in result["data"]["items"]: node_type = "目录" if item["path"].endswith("/") else "文件" print(f"[{node_type}] {item['path']}")
注意：说明：
注意：client 实例的构造方式参见 新建客户端；异步调用时将方法前加 await 即可。
三、请求参数
| 参数名 | 类型 | 必填 | 默认值 | 描述说明 |
| path_prefix | str | 否 | "" | 路径前缀（虚拟目录过滤）。用于筛选特定目录下的文件。其传值规则如下：按目录筛选：传入特定的路径前缀（如 "documents/2026/"），则只列举该目录下的文件。列举全部：不传此参数、或显式传入空字符串 ""、None，系统将默认从根目录（最顶层）开始列举所有文件。 |
四、返回信息
返回字典包含命中的记忆列表与请求追踪 ID：
{ "data": { "entries": [ { "path": "工作/", "created_at": "2026-04-01T08:00:00Z", "updated_at": "2026-04-21T08:30:15Z" }, { "path": "工作/交付物/", "created_at": "2026-04-01T08:00:00Z", "updated_at": "2026-04-21T08:30:15Z" }, { "path": "工作/交付物/2026Q1.md", "created_at": "2026-03-31T18:00:00Z", "updated_at": "2026-04-21T08:30:15Z" } ], "total": 3 }, "trace_id": "tr-xxxxxxxx-xxxxxxxx"}
| 字段名 | 类型 | 说明 |
| data.entries | List[Dict] | 列举出的场景记忆条目列表。每项包含以下完整元数据字段：path (str): 场景记忆的完整路径。created_at (str): 该节点的首次创建时间戳（ISO 8601 格式）。updated_at (str): 该节点的最后修改时间戳（ISO 8601 格式）。 |
| data.total | int | 满足前缀过滤条件的条目总数。该值为全量数据计数，不受当前单页请求的截断限制。若当前前缀下没有任何数据，则 entries 返回空数组 []，total 返回 0。 |
| trace_id | str | 请求追踪 ID。用于全链路日志排查。该值与 HTTP 响应头中的 x-trace-id 保持一致，常用于审计目录前缀扫描性能或定位数据同步延迟。 |
五、错误处理
| 错误码 | 触发场景 | 处理建议 |
| 500 | 服务端错误。 | 记录 trace_id 后重试或上报。 |