接口介绍
按目录前缀列出场景记忆的目录树。通过
path_prefix 指定列举范围，系统一次性返回该范围内的全部节点：列举范围：通过
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']}")
说明：
请求参数
参数名 | 类型 | 必填 | 默认值 | 描述说明 |
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 后重试或上报。 |
