跳到内容
ClickHouse Loom
Esc
↑↓导航↵打开⌘J预览
本页内容

session 操作

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 以及所用模型。

这个页面有帮助吗?