<a id="session-operations"></a>

# `session` 操作

<!-- i18n: source=docs/reference/operations/session.md blob=ef3c231b70d1fcd6e901f42238a70972ed7ee390 model=claude-sonnet-5-5 -->
> 本页由机器从[英文原文](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/session.md)翻译，内容以英文原文为准。
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/session.md), which is authoritative.


每个 `session.*` 操作接受和返回的确切字段。

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

每个操作都是通过 HTTP 的 `POST /v1/<op>`，同时也是 MCP 工具 `loom_<op>`。身份字段（`org`、`namespace`、`agent`、`user_id`、`session_id`）在传输层能够提供时，会根据令牌和 MCP 会话自动填充；对于单用户服务器上不带令牌的 HTTP 调用，除 `code.*` 和 `tracker.*`（它们沿用各自所属平面的 org）之外，所有操作的 org 都取该安装的 org，而[部分操作](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)的命名空间和 agent 也会如此取值；参见[身份与命名空间](/zh-CN/concepts/identities-and-namespaces)。[操作索引](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md)说明了 role、kind 以及 MCP 的 `all` 列表。未知的输入字段仍会被处理，并列在 `ignored_args` 中。

<!-- prettier-ignore-start -->

<a id="sessionbrief_delete"></a>

## `session.brief_delete`

当用户要求遗忘某个会话简报时，按 brief_key 删除该简报。

`POST /v1/session.brief_delete` · MCP `loom_session_brief_delete` · 角色 `writer` · 幂等 · 已审计 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（标识元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 执行写入或读取的 agent；`'-'` 或 `'*'` 表示在该操作允许时匹配任意 agent。 |
| `user_id` | `str` | `'-'` | 该行所属的终端用户；`'-'` 表示无。 |
| `session_id` | `str` | `'-'` | 该行所属的会话或对话；`'-'` 表示无。 |
| `run_id` | `str` | `'-'` | 该调用所属的 agent 运行（任务范围）；`'-'` 表示无。 |
| `brief_key` | `str` | 必填 | 要删除的简报，与 session.brief_list 显示的一致。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `deleted` | `bool` | 当没有使用该 key 的有效简报时（未知或已被删除）为 False。 |
| `brief_key` | `str` | 回显输入的 `brief_key`。 |
| `revision` | `int` | 删除时该简报所处的修订版本；未删除任何内容时为 0。 |

<a id="sessionbrief_get"></a>

## `session.brief_get`

加载一份 brief：优先按 `brief_key` 加载；否则加载指定会话（`from_session`）写入的最新 brief；再否则加载 `project` 的最新 brief。

`POST /v1/session.brief_get` · MCP `loom_session_brief_get` · 角色 `viewer` · 读取 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该 op 读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 写入或读取的 agent；`'-'` 或 `'*'` 表示在 op 允许时匹配任意 agent。 |
| `user_id` | `str` | `'-'` | 该行所属的最终用户；`'-'` 表示无。 |
| `session_id` | `str` | `'-'` | 该行所属的会话或对话；`'-'` 表示无。 |
| `run_id` | `str` | `'-'` | 该调用所属的 agent 运行（任务范围）；`'-'` 表示无。 |
| `brief_key` | `str` | `''` | 要加载的 brief；优先于 `from_session` 和 `project`。 |
| `from_session` | `str` | `''` | 加载该会话 id 参与写入的最新 brief。 |
| `project` | `str` | `''` | 加载该项目的最新 brief（在 `brief_key` 和 `from_session` 均为空时使用）。 |
| `revision` | `int` | `0` | 0 表示当前修订；N 表示历史中的第 N 个修订。 |
| `include_sections` | `bool` | `False` | 同时返回结构化的 `sections`；为 False 时只返回 `rendered`。 |
| `full` | `bool` | `False` | 在 brief 下方原样追加客户端上一次压缩时生成的摘要（最多额外增加约 15k 字符）。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `found` | `bool` | 没有匹配的 brief、brief 已被删除，或该修订不在其历史中时为 False。 |
| `brief_key` | `str` | 匹配到的 brief 的键。 |
| `revision` | `int` | 返回的修订（除非请求了 `revision`，否则为当前修订）。 |
| `rendered` | `str` | 文本形式的 brief；当 `full` 为真时，会附加客户端的压缩摘要。 |
| `sections` | `BriefSections \| None` | 结构化的 brief；除非设置了 `include_sections`，否则为 None。 |
| `project` | `str` | brief 中存储的项目。 |
| `branch` | `str` | brief 中存储的分支。 |
| `head_sha` | `str` | 保存该修订时检出所在的提交。 |
| `author` | `str` | 修订的写入方：`llm`、`deterministic` 或 `model`（调用方 agent）。 |
| `trigger` | `str` | 触发该修订保存的原因（`precompact`、`session_end`、`stop`、`manual` 或 `model`）。 |
| `actor` | `str` | 保存该修订的主体（`human:<subject>` / `process:<subject>`）：对整个命名空间有写权限的主体可以保存到用户自己的 `~<user>~` brief。 |
| `source_sessions` | `list[str]` | 参与该 brief 的会话 id，按从旧到新排列（最近 20 个）。 |
| `updated_at` | `datetime \| None` | 返回的修订的保存时间。 |
| `age_seconds` | `int` | 自 `updated_at` 起经过的秒数。 |
| `revisions` | `int` | 该 brief 的历史中包含的修订数。 |
| `events_total` | `int` | 在其整个生命周期内被浓缩进该 brief 的事件数。 |
| `source_chars` | `int` | 在其整个生命周期内被浓缩进该 brief 的事件文本的字符数。 |
| `brief_chars` | `int` | `rendered` 按存储形式计算的长度，以字符计。 |
| `deleted` | `bool` | brief 被其写入方删除时为 True；此时不会返回其他任何内容。 |

<a id="sessionbrief_list"></a>

## `session.brief_list`

列出此命名空间中的会话简报，按时间从新到旧排序：每条简报占一行，包含 key、修订版本、存在时长、agent 和目标。

`POST /v1/session.brief_list` · MCP `loom_session_brief_list` · 角色 `viewer` · 只读 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（标识元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 写入或读取的 agent；`'-'` 或 `'*'` 表示在操作允许时匹配任意 agent。 |
| `user_id` | `str` | `'-'` | 该行所属的终端用户；`'-'` 表示无。 |
| `session_id` | `str` | `'-'` | 该行所属的会话或对话；`'-'` 表示无。 |
| `run_id` | `str` | `'-'` | 该调用所属的 agent 运行（任务范围）；`'-'` 表示无。 |
| `project` | `str` | `''` | 仅返回此项目的简报；为空则返回所有项目的简报。 |
| `mine_only` | `bool` | `False` | 为 True 时仅返回调用方 agent 的简报；默认返回所有 agent 的简报。 |
| `from_session` | `str` | `''` | 仅返回此会话 ID 参与生成的简报；为空则不按会话过滤。 |
| `limit` | `int` | `10` | 最多返回这么多条简报（1-50）。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `briefs` | `list[SessionBriefSummary]` | 有效的简报，按最近保存的在前排序；命名空间中没有简报时为空。 |
| `rendered` | `str` | 每条简报一行，可直接显示。 |

<a id="sessionbrief_save"></a>

## `session.brief_save`

修订（或新建）一份 brief。

`POST /v1/session.brief_save` · MCP `loom_session_brief_save` · 角色 `writer` · 幂等 · 已审计 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 必填 | 执行写入或读取的 agent；`'-'` 或 `'*'` 表示在该操作允许时匹配任意 agent。 |
| `user_id` | `str` | `'-'` | 该行所属的最终用户；`'-'` 表示无。 |
| `session_id` | `str` | `'-'` | 该行所属的会话或对话；`'-'` 表示无。 |
| `run_id` | `str` | `'-'` | 本次调用所属的 agent 运行（任务范围）；`'-'` 表示无。 |
| `brief_key` | `str` | `''` | brief 在命名空间中的地址。 |
| `project` | `str` | `''` | 工作所属的项目；与 `branch` 一起构成自动键。 |
| `repo` | `str` | `''` | 工作所在的仓库，保存在 brief 上；为空则保留已存储的值。 |
| `branch` | `str` | `''` | 工作所在的分支；与 `project` 一起构成自动键。 |
| `head_sha` | `str` | `''` | 保存时检出所在的提交；为空则保留已存储的值。 |
| `trigger` | `Literal['precompact', 'session_end', 'stop', 'manual', 'model']` | `'manual'` | 触发本次保存的原因：`manual` 和 `model` 总是保存；自动触发的 `precompact`、`session_end` 和 `stop` 在命名空间的记录功能关闭时不存储任何内容。 |
| `events` | `list[BriefEvent]` | *(计算得出)* | 自上次保存以来发生的事件（最多 4000 个事件），会被压缩进本次修订。 |
| `sections` | `BriefSections \| None` | `None` | 调用方 agent 根据自身上下文写成的 brief：填写的各节会替换已存储的对应节（决策 / 死胡同则追加）。 |
| `event_cursor` | `str` | `''` | 事件结束位置的不透明客户端游标（transcript 的行索引）。 |
| `if_revision` | `int \| None` | `None` | 比较并设置：除非已存储的修订号与此值相同，否则拒绝（409）。 |
| `use_llm` | `bool \| None` | `None` | 强制使用确定性构建器（False）或模型（True）；None 表示采用部署设置。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `brief_key` | `str` | brief 保存时使用的键（未提供时为解析出的自动键）。 |
| `revision` | `int` | 本次调用之后 brief 的修订号（未变化时为已存储的修订号；没有有效 brief 时为 0）。 |
| `changed` | `bool` | 写入了新修订时为 True；否则为 False，原因见 `reason`。 |
| `author` | `str` | "llm"（由模型修订）、"deterministic"（未配置模型或模型失败；在运维方的提取策略下不会出现）、"model"（由调用方 agent 写成各节）。 |
| `reason` | `str` | 未写入的原因：`nothing-to-save`、`recording_off`、`already-saved` 或 `not-revised`（运维方的提取策略已生效，且没有可用于修订 brief 的模型）；`changed` 时为空。 |
| `rendered` | `str` | 可直接展示的文本形式的 brief；未变化时为已存储的版本。 |
| `stats` | `SessionBriefStats` | 本次保存的统计：事件、窗口、大小、token 以及所用模型。 |

<!-- prettier-ignore-end -->
