`session` 操作
本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.
每个 session.* 操作接受和返回的确切字段。
每个操作都是通过 HTTP 的 POST /v1/<op>,同时也是 MCP 工具 loom_<op>。身份字段(org、namespace、agent、user_id、session_id)在传输层能够提供时,会根据令牌和 MCP 会话自动填充;对于单用户服务器上不带令牌的 HTTP 调用,除 code.* 和 tracker.*(它们沿用各自所属平面的 org)之外,所有操作的 org 都取该安装的 org,而部分操作的命名空间和 agent 也会如此取值;参见身份与命名空间。操作索引说明了 role、kind 以及 MCP 的 all 列表。未知的输入字段仍会被处理,并列在 ignored_args 中。
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。 |
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;此时不会返回其他任何内容。 |
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 |
每条简报一行,可直接显示。 |
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 以及所用模型。 |