接口介绍
全量覆盖一份已存在的场景记忆。通过
path 定位目标，传入新的全量正文，系统按"全量覆盖"语义替换旧内容：目标定位：通过
path 指定场景记忆的完整路径（必填），该路径必须已存在。正文覆盖：通过
content 传入更新后的全量正文（必填，整体覆盖旧内容，不做 diff / merge）。摘要更新：通过
summary 传入该场景记忆的一句话摘要（可选）；None（即不传）表示本次不更新摘要，显式传入空串 "" 则代表清空摘要。项 | 值 |
HTTP 方法与路径 | POST /v2/scenario/write |
HTTP 文档 | |
函数签名 | write_scenario(path, content, *, summary=None) |
说明：
写入语义仅为"更新"、不支持"新增"。若目标
path 不存在或不属于当前调用上下文，统一返回业务错误码 404，不会自动创建场景记忆——场景记忆的创建路径由系统自动沉淀产生（来自原始对话与原子记忆的聚合），无法直接通过此接口建档。使用示例
# 仅更新正文result = client.write_scenario(path="工作/交付物/2026Q1.md",content="# 2026Q1 交付物清单（已修订）\\n...",)# 同时更新正文和摘要result = client.write_scenario(path="工作/交付物/2026Q1.md",content="# 2026Q1 交付物清单（已修订）\\n...",summary="2026 Q1 交付物，含三个里程碑修订",)
说明：
请求参数
参数名 | 类型 | 必填 | 描述说明 |
path | str | 是 | 目标场景记忆文件的完整路径。 说明： 必须传入一个已存在的有效全路径（如 "工作/交付物/2026Q1.md"），若路径不存在，接口将报错。 |
content | str | 是 | 新的记忆全量正文。传入更新后的完整文本（通常为 Markdown 格式）。 说明： 该操作为全量覆盖，会直接替换原文件中的所有内容。 |
summary | str | 否 | 文件的一句话摘要/简介。用于调整或重置大模型为该文件生成的摘要。其传值规则如下： 不更新：传 None（或不传该字段），系统将保留原摘要不变。 清空：显式传入空字符串 ""，系统将彻底清除原摘要。 |
返回信息
返回字典包含被覆盖路径、最新时间戳与请求追踪 ID：
{"path": "工作/交付物/2026Q1.md","updated_at": "2026-05-22T14:30:00+08:00","trace_id": "tr-xxxxxxxx-xxxxxxxx"}
字段 | 类型 | 说明 |
path | str | 确认被成功更新的场景记忆文件全路径。 |
updated_at | str | 系统最新的更新时间戳（ISO 8601 格式），代表该文件内容或摘要被成功覆盖的时间。 |
trace_id | str | 本次请求的全局链路追踪 ID，方便后续针对该操作进行日志排查。 |
错误处理
错误码 | 触发场景 | 处理建议 |
404 | path 不存在或不属于当前调用上下文。 | 请校验路径合法性，本接口不会自动创建。 |
500 | 服务端错误。 | 记录 trace_id 后重试或上报。 |
