Help us shape the future of Go! Take the 2026 Go Developer Survey

session

package
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 7, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package session 是会话域（自产品 internal/agent/session.go 迁入）：内存 注册表 + users/<op>/sessions/<sid>/session.json 落盘（用户隔离）。会话记录 = 发起人/状态/模式/模型快照/任务摘要 + 事件流（回看端点原样输出，应用层走 自有传输管线渲染）。存储经 Store 接口注入——数据面（唯一文件写入器）在应用。

状态：running | pending_approval | ended | error。

Index

Constants

View Source 
const (
	StateRunning         = contract.StateRunning
	StatePendingApproval = contract.StatePendingApproval
	StateEnded           = contract.StateEnded
	StateError           = contract.StateError
)

会话状态常量（契约形态）。

Variables

View Source 
var SessionTTLVar = 7 * 24 * time.Hour

SessionTTLVar 会话保留期（测试可缩短）。

Functions

func EventAs added in v0.5.0 

func EventAs[T any](ev Event) (T, bool)

EventAs 事件载荷的双形态统一取值器（Record 落 typed 原样、Reattach 盘面 回读是 map——data any 的固有双形态）。typed 直断言，map 经 JSON 往返还原， 失败 false。消费面统一走此取值器：此前各消费者自做归一（ui 手写往返、 sessionEndAt 手写双分支、feishu 仅断言 typed——盘面回放消费即静默空白， 审查 P2-8 收口）。

func ListPersistedRecent added in v0.2.0 

func ListPersistedRecent(st Store, owner string, n int) []string

ListPersistedRecent 最近的 n 个持久会话 sid（按 session.json 修改时间降序； 无记录文件或不可读的目录跳过）。n ≤0 返回空。

func ValidOwner added in v0.5.0 

func ValidOwner(op string) bool

ValidOwner operator（用户标识符）的结构围栏：非空、非 "." / ".."、不含 路径分隔符与 NUL——可含任意 Unicode（owner 是「张三」这类标识不是文件名 白名单）。operator 进 Store 前的入口面（ui 查询参数、渠道 InboundMsg） 应先过此栏：拦截的是「标识符携带路径形态穿越 users 树」的注入面。

Types

type ApprovalDecision 

type ApprovalDecision = contract.ApprovalDecision

ApprovalDecision 审批决议（approve 端点 → 包装工具消费；契约形态）。

type AskDecision 

type AskDecision = contract.AskDecision

AskDecision ask_user 作答（answer 端点 → askuser 工具消费；契约形态）。

type Attachment 

type Attachment = contract.Attachment

Attachment 用户消息附件（契约形态）。

type Event 

type Event = contract.Event

Event 已发事件（回放端点原样输出；契约形态）。

type PersistedDigest added in v0.2.0 

type PersistedDigest struct {
	SID       string
	Title     string
	Task      string
	Summary   string
	State     string
	UpdatedAt time.Time
	Messages  []*schema.Message
}

PersistedDigest 持久会话检索视图（轻字段 + 续聊历史——多模态在落盘时已 拍平为文本）。

func ReadPersisted added in v0.2.0 

func ReadPersisted(st Store, owner, sid string) (PersistedDigest, bool)

ReadPersisted 读单个持久会话的检索视图（不存在/损坏 = ok=false 不报错—— 检索面容忍缺页，调用方跳过即可）。

type QueuedMsg 

type QueuedMsg = contract.QueuedMsg

QueuedMsg 排队消息（契约形态；steering 入队，可编辑/删除）。

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry 会话注册表（内存 + 磁盘合并读）。

func NewRegistry 

func NewRegistry(st Store) *Registry

NewRegistry 构造。

func (*Registry) Create 

func (r *Registry) Create(owner, task, mode string, model contract.UserPrefs) *Session

Create 新会话（默认态 running 由 Run 侧设置；此处先 ended 占位防并发窗）。 顺带触发一轮过期清理（2026-08-23 定：新建即触检，替代小时级后台任务—— 会话只在有人用时累积，新建时机天然自限；全量扫盘轻量）。

func (*Registry) Delete 

func (r *Registry) Delete(owner, sid string)

Delete 删除契约：停执行 → 内存摘除 → users/<op>/sessions/<sid>/ 与会话 工作区（用户域 workspaces/<sid>，含持久子区）整目录移除（停执行在 前——运行中的 Run 步间检查即中止；磁盘零残留）。返回 owner 供 api 层发起人校验（校验失败时调用方不得触达本方法——先 Detail 校验再删）。

func (*Registry) Detail 

func (r *Registry) Detail(sid string, since int) (SessionDetail, bool)

Detail 单会话详情（内存优先，缺则读盘；owner 不符由 api 层先校验）。since>0 时 events 只含 id>since 的增量（按标签缓存切回的增量追赶——缩 wire 载荷， 2026-08-26 会话切换提速）。

func (*Registry) DetailDisk 

func (r *Registry) DetailDisk(owner, sid string, since int) (SessionDetail, bool)

DetailDisk 磁盘历史会话详情（软恢复/回看：进程重启后；since 语义同 Detail）。

func (*Registry) Drain added in v0.3.0 

func (r *Registry) Drain(deadline time.Duration) []string

Drain 优雅停机收尾（A6）：对全部 running 态会话发取消 → 有界等执行体收尾 （取消走引擎 interruptUnlessStopped 既有链：终态事件 + 检查点 + 中断注记 全落）。到点仍未收尾的会话 SID 如实返回（调用方记日志，不阻塞停机—— 与强制退出同，但多数场景已收干净）。挂起态（pending_approval）无执行体 不在列——跨重启由 RearmPendingTimer 续表；执行体必在内存（Get 语义）。

func (*Registry) Fork added in v0.3.0 

func (r *Registry) Fork(owner, sid string) *Session

Fork 全量快照分叉（B8）：从既有会话复制当前完整态（事件流+历史+摘要+外置 域），生成新 SID 的新会话（= ForkAt 锚 0）。V1 限定源非 running（源 running 即返回 nil——升级位须先给 spill 写入与复制立同步点）。分叉体 State=ended 占位（Create 同款），Run 由应用发起。寻址同 Reattach 语义：内存优先，不在 内存则磁盘重建后再克隆（历史会话分叉是主场景）。挂起域/taskGrant/planSeq/ 排队消息不带（分叉体无执行体残留，与 Reattach 的不可续降级同裁决；任务期 写授权回审批流是安全侧）；spill 外置域整目录复制（history 含外置指针，不 复制即 read_file 取回落空）。

func (*Registry) ForkAt added in v0.5.0 

func (r *Registry) ForkAt(owner, sid string, anchor int) *Session

ForkAt 锚定分叉（ZCode「从已完成消息岔出」对位）：anchor = 源会话某条 session_end 事件 ID（载荷 HistLen>0 才可锚——旧存量零值事件不可锚）； anchor=0 即全量快照（Fork 同义）；负数一律 nil（fail-closed——非 0 即 要求合法锚）。截断语义：事件截至锚（含）、历史截至锚 HistLen、 fileChanges/summary 取锚事件载荷重建（锚后账目不随行）、事件 seq 接锚 ID。锚后 spill 余量照旧整目录复制（无害——callID 寻址不冲突）。 side 会话不可分叉；源 running/未知锚/数据不一致（HistLen 越界）一律 nil。

func (*Registry) Get 

func (r *Registry) Get(sid string) (*Session, bool)

Get 取会话（仅内存——运行态必在内存；历史会话经 Detail 读盘）。

func (*Registry) List 

func (r *Registry) List(owner string) []SessionListItem

List 我的会话（mine：内存 + 磁盘合并，内存覆盖同 sid；活动时间倒序）。

func (*Registry) ListAll 

func (r *Registry) ListAll() []SessionListItem

ListAll 全部用户全部会话（admin 视图）：内存全量 + 各用户磁盘合并（内存覆盖 同 sid；含已移除成员的历史目录——ListUsers 直扫语义），活动时间倒序截断。

func (*Registry) LoadHistory 

func (r *Registry) LoadHistory(s *Session)

LoadHistory 磁盘恢复续聊历史（进程重启后 Run 前调用；无历史 no-op）。

func (*Registry) Persist 

func (r *Registry) Persist(s *Session)

Persist 导出落盘口（Run 状态迁移调用）。

func (*Registry) Reattach 

func (r *Registry) Reattach(owner, sid string) *Session

Reattach 磁盘会话续接（进程重启后带 sid 再 POST：注册表重建会话 + 装载 历史；内存已有同 sid 直接回）。挂起审批态一并恢复（checkpoint 在盘，approve 端点可续流）——running 残留/旧格式挂起（无 pending_app_id，RecoverInterrupted 启动已翻，防御分支）落 ended。归属不符返回 nil。

func (*Registry) RecoverInterrupted 

func (r *Registry) RecoverInterrupted() int

RecoverInterrupted 进程启动孤儿清理：落盘仍处 running 的会话已无执行体 （进程重启丢内存态，watch/续聊皆死胡同），统一翻 error 终态并补一条中断 error 事件——列表显示「出错」，回放可见中断原因，点击可正常回看/接续。 挂起审批（pending_approval）例外——checkpoint 在盘、决议可续流（2026-08-24 定案：重启前挂起的审批卡跨重启可批准）：带 pending_app_id 且未到截止的保留 挂起（等 owner 决议）；停机期间已到截止的镜像超时器动作（approval_timeout/ ask_timeout 事件 + ended）；旧格式（无 pending_app_id）按 running 同样翻 error。 返回修复数（serve 启动调用一次）。

func (*Registry) Search 

func (r *Registry) Search(owner, q string) []SessionListItem

Search 我的会话关键词过滤（标题或任一用户消息文本包含 q，不区分大小写； 活动时间倒序——q 由 api 层 TrimSpace，空串 = 同 List）。

func (*Registry) SearchAll 

func (r *Registry) SearchAll(q string) []SessionListItem

SearchAll admin 全量关键词过滤（语义同 Search，跨全部用户）。

func (*Registry) Side added in v0.5.0 

func (r *Registry) Side(owner, sid string) *Session

Side 辅助对话：继承主会话当前历史快照的轻量派生会话（ZCode side chat 对位）。快照语义——创建后各自演化，父后续轮不流入；Model/Effort/Mode/ lastUsedModel 继承；事件流置空（界面从空白开始）+ 血缘 note（Kind: side） ；Summary/FileChanges/挂起域/排队消息不带。允许父 running（历史快照持锁 安全——主任务执行中问快速问题是核心场景）；spill/工作区由引擎侧父感知 共享（engine.wsSID）。side of side/归属不符/未知 sid 返回 nil。

func (*Registry) SidesOf added in v0.5.0 

func (r *Registry) SidesOf(owner, sid string) []string

SidesOf 主会话的辅助对话清单（内存 + 盘面扫——UI 寻址与级联删除共用； Store 无子树枚举面，os 直扫是 copySpill/Sweep 同先例）。

func (*Registry) Store 

func (r *Registry) Store() Store

Store 会话域存储出口（引擎会话域件装配用——计划文档写入走用户域文件面）。

func (*Registry) SweepTmpWorkspaces 

func (r *Registry) SweepTmpWorkspaces() int

SweepTmpWorkspaces 启动清扫会话工作区（用户域 workspaces/<sid>）：对照 磁盘会话（.agent/users/<op>/sessions/<sid>/），无对应会话**或会话已正常 结束**（任务收尾即清的主锚点漏网的兜底——崩溃前未及清的 ended 残留） 整删；挂起/异常态保留待续（跨重启可恢复）。顺带两代旧布局清场： DATA_DIR/workspaces 活会话 rename 搬入用户域（迁移后旧根移除，下次自然 空跑）；.tmp/workspaces 整树移除（旧位已弃用，树里全是孤儿）。返回清 理/迁移的目录数（serve 启动日志观测用）。

type Session 

type Session struct {
	SID   string             `json:"sid"`
	Owner string             `json:"owner"`
	Task  string             `json:"task"` // 会话列表任务摘要（首条用户消息截断）
	State string             `json:"state"`
	Mode  string             `json:"mode"`
	Title string             `json:"title"` // LLM 总结标题（首轮收尾异步生成；空 = 回退 Task 截断）
	Model contract.UserPrefs `json:"model"` // {model 复合键, effort} 快照（会话粘住）

	StartedAt time.Time `json:"started_at"`
	UpdatedAt time.Time `json:"updated_at"`
	Events    []Event   `json:"events"`
	// contains filtered or unexported fields
}

Session 会话（Events 即消息流真源；mu 保护并发 emit/删除竞态）。

func (*Session) AppendHistory 

func (s *Session) AppendHistory(msgs ...*schema.Message)

AppendHistory 追加消息（user 输入与每轮 assistant 终态）。

func (*Session) BeginResume added in v0.3.0 

func (s *Session) BeginResume() bool

BeginResume 决议续流执行体抢占（单锁原子：查挂起 + 清挂起域 + 翻 running + 挂 runDone——BeginRun 同型三步）。判据用 curAppID 而非 State：挂起后 State 仍为 pending_approval，态检查挡不住并发双 Resume；curAppID 的查清在同一 锁段完成即闭合 check→Resume 的 TOCTOU 窗口。翻 running 同时修复续流执行 期的可见性（此前恒显 pending：FlushQueue 误报不可打断、Drain 枚举漏执行 体）。返回 false = 无挂起（重复/迟到 Resume 在此即拒——checkpoint 不随 Resume 消费，迟到调用放行是脏重放）。

func (*Session) BeginRun 

func (s *Session) BeginRun(mode string) bool

BeginRun 执行抢占（原子：态检查 + 翻 running + 模式置换一步完成）—— 任务后台化后同一会话防并发双执行体的闸门（api 层 POST /api/chat 启动前 调用；false = 活跃中，调用方走 steering 入队）。顺带挂 runDone（本轮执行体 结束信号——FlushQueue 打断当前执行后等其收尾再接管，防双执行体竞态）。

func (*Session) CancelRun 

func (s *Session) CancelRun()

CancelRun 取消运行中的执行体（停止按钮端点；无运行则 no-op）。执行体收 到取消后由 pump 中断收尾（中断事件 + error 终态落盘）。

func (*Session) ClearPendingIf added in v0.4.0 

func (s *Session) ClearPendingIf(appID string) ([]string, bool)

ClearPendingIf 条件原子清挂起（超时路径专用）：锁内校验「仍挂起该 appID 且 无决议到达」才清并返回项清单——闭合守卫检查与清挂起之间的 TOCTOU（用户 approve 与超时并发时抢到锁者赢，另一方让位）。项清单随清返回（清域后不可 再取——合并卡逐项落拒用）。askDecision 归提问路径（kind=ask 超时同样经此）。

func (*Session) ClearTaskGrant 

func (s *Session) ClearTaskGrant()

func (*Session) ClearTurnGrant 

func (s *Session) ClearTurnGrant()

func (*Session) CloneHistory 

func (s *Session) CloneHistory() []*schema.Message

CloneHistory 取历史快照（Run 组装输入用）。

func (*Session) ContinueOrNotify 

func (s *Session) ContinueOrNotify(msg string, wake bool) (began bool, q QueuedMsg)

ContinueOrNotify 后台完成通知的单锁原子注入原语（W-3）： 锁内一步裁定——running/pending/error → 通知入队（began=false，当前/ 下一轮 TakePending 消费）；ended（自然收口）+ wake → 翻 running + 挂 runDone + 通知入队（began=true，调用方锁外 Record notify_queued 后以 Run("") 起自续轮——通知经队列注入，输入路径与 steering 唯一）；ended + !wake → 只入队（自激护栏预算耗尽：不自动开轮，下轮用户交互消费）。 **error 终态绝不自续**（对照审查 A-3：用户停止把中断洗成模型请求是被 明确拒绝的形态；运行错误同理保守——通知只入队，下轮用户交互消费）。 竞态封闭依据：与 BeginRun/Steer 同锁互斥，TOCTOU 丢通知/丢启动窗口不 存在（单锁原语义，对照审查定案）。返回的 q 供锁外 Record（Record 自持 锁，锁内不可调）。

func (*Session) EditQueued 

func (s *Session) EditQueued(id, text string) bool

EditQueued 编辑排队消息（false = 不存在或系统通知只读）；落 steer_updated 回执。

func (*Session) EventsSince added in v0.5.0 

func (s *Session) EventsSince(from int) []Event

EventsSince 快照中 ID 大于 from 的事件（订阅通道满即弃的补投源——渠道 消费泵的间隙补投/节拍追赶与 ui SSE 慢消费兜底同源共用，见 engine/channel.go）。

func (*Session) FileChangesSnapshot 

func (s *Session) FileChangesSnapshot() []contract.FileChange

FileChangesSnapshot 会话累计变更清单（path 排序稳定输出）。

func (*Session) GrantTask 

func (s *Session) GrantTask()

GrantTask plan 档任务期写授权置位 / 查询 / 清零（计划批准置位；任务成功 收尾、档位变更、新计划提交时清零。不在轮末无条件清——轮次预算耗尽后 「继续」仍在授权期内，兑现「批准计划后一口气完成」）。

func (*Session) GrantTurn 

func (s *Session) GrantTurn()

GrantTurn plan 档本轮写授权置位 / 查询 / 清零。

func (*Session) HasPendingDecision added in v0.2.0 

func (s *Session) HasPendingDecision() bool

HasPendingDecision 挂起决议/作答是否已登记。决议到达（SetDecision/ SetDecisionFor/SetAskDecision）先于超时到点或 Resume 停表时，超时兜底 须让位——覆盖已到达的决议等于把用户的 approve 改写成超时拒绝。审批看 "" 槽与挂起项槽（批量决议逐项写入的非原子窗口：任一到达即让位，未决项 由 Resume 重放 fail-closed 兜底）；提问看 askDecision。

func (*Session) HasQueuedImages 

func (s *Session) HasQueuedImages() bool

HasQueuedImages 排队消息是否含图片附件（设置通道切模型的守卫：落回轮 无图片门禁兜底，纯文本模型 + 含图排队消息会在执行时炸——写入时拒）。

func (*Session) HistoryLen added in v0.5.0 

func (s *Session) HistoryLen() int

HistoryLen 历史长度（settleTurn 记 SessionEnd.HistLen 的取值面）。

func (*Session) MarkFlush 

func (s *Session) MarkFlush()

MarkFlush / TakeFlushMark 立即处理排队标记（FlushQueue 打断前置位； pump 中断收尾消费分叉事件形态）。

func (*Session) MarkTitleFlight 

func (s *Session) MarkTitleFlight() func()

MarkTitleFlight 标记标题异步生成在途（返回收尾闭包；引擎 settleTurn 起 genTitle goroutine 前调用）。genTitle 是唯一逃逸 Run 生命周期的写者—— Run 返回 ≠ 写完，此信号让测试收尾/删除方可确定性等待在途写落地。

func (*Session) ModePublic 

func (s *Session) ModePublic() string

ModePublic 模式读取（包装器组装用）。

func (*Session) ModelSnapshot added in v0.4.0 

func (s *Session) ModelSnapshot() contract.UserPrefs

ModelSnapshot 模型复合键持锁快照（PUT settings 类随时写路径与引擎读并发， 裸读 s.Model.Model 构成 data race）。

func (*Session) NextPlanSeq 

func (s *Session) NextPlanSeq() int

NextPlanSeq 计划文档序号自增取号（提交即定号——文档先落盘再挂起，跨重启 由 sessionRecord.PlanSeq 接续）。

func (*Session) NoteModelCall added in v0.4.0 

func (s *Session) NoteModelCall(model string)

NoteModelCall 模型调用边界登记（engine.assemble 每次模型调用前调）：本次 将用模型与上次实际调用不同 → 落 model_change 注记（UI 切换标志）。首调/ 跨重启无前序只登记不落。lastUsedModel 随记录持久化（跨重启比对不断）。

func (*Session) NotifyBudget 

func (s *Session) NotifyBudget(budget int) bool

NotifyBudget 自激护栏预算（W-3）：budget = 连续自续上限。true = 还有预算 （消费一格）；false = 已耗尽（调用方降级仅记事件）。用户消息消费恢复预算 （RestoreNotifyBudget——通知自身不恢复，dsh spentWakes 同款）。

func (*Session) ParentOf added in v0.5.0 

func (s *Session) ParentOf() string

ParentOf 父会话 SID（辅助对话；空 = 普通会话）。构造后不变，无锁直读。

func (*Session) ParticipantsOf added in v0.5.0 

func (s *Session) ParticipantsOf() []contract.Participant

ParticipantsOf 名册快照。

func (*Session) PendingAppID 

func (s *Session) PendingAppID() string

PendingAppID 当前挂起审批 ID。

func (*Session) PendingDueOf 

func (s *Session) PendingDueOf() (string, time.Time)

PendingDueOf 挂起计时元数据读取（RearmPendingTimer 续表用）。

func (*Session) PendingItems 

func (s *Session) PendingItems() []string

PendingItems 项标识清单快照（超时批量拒 / approve 端点覆盖校验）。

func (*Session) PendingTarget added in v0.5.0 

func (s *Session) PendingTarget() string

PendingTarget 挂起审批的路由目标（空 = 无目标不校验）。

func (*Session) QueueLen 

func (s *Session) QueueLen() int

QueueLen 排队消息数（flush 端点空队列守卫）。

func (*Session) Record 

func (s *Session) Record(name string, data any) Event

Record 追加事件（seq 自增；已停止会话不再记录——删除后磁盘零残留）。 记录即扇出到旁观订阅（M5-2）。

func (*Session) RecordAskDecision 

func (s *Session) RecordAskDecision(askID string, d AskDecision)

RecordAskDecision 作答回执落流（answer 端点在 SetAskDecision 后调用—— 切回/回放重建提问卡终态的真源）。

func (*Session) RecordDecision 

func (s *Session) RecordDecision(appID string, d ApprovalDecision, items ...contract.ItemDecisionOut)

RecordDecision 决议回执落流（approve 端点在 SetDecision 后调用）。事件流是 切回/回放重建审批卡终态的真源——决议只 Set 不落流，卡片永远停在待审批态。 items = 合并决议卡的逐项回执（分歧态以 Items 为准——契约声明的真源面， 审查 P2-16 落码：此前从不填充，批一拒一的回放无法重建逐项终态）；单卡 决议空参零变化。

func (*Session) RecordFileChange 

func (s *Session) RecordFileChange(path, action string)

RecordFileChange 工具层报备入口（ctx 记录器直连；并发安全）。

func (*Session) RecordPlanDecision 

func (s *Session) RecordPlanDecision(planID string, d ApprovalDecision)

RecordPlanDecision 计划决议回执落流（approve 端点按 pending_kind=plan 分叉 调用；切回/回放重建计划卡终态的真源）。

func (*Session) RemoveQueued 

func (s *Session) RemoveQueued(id string) bool

RemoveQueued 移除排队消息（false = 不存在或系统通知不可删）；落 steer_removed 回执。

func (*Session) ReorderQueued 

func (s *Session) ReorderQueued(ids []string) bool

ReorderQueued 排队消息重排（UI-B3 拖拽排序——ids = 期望顺序的完整清单； 集合与现存不一致整体拒（多/少/未知 id，防并发丢消息）；成功落 steer_reordered 回执——回放重建顺序的真源）。

func (*Session) RestoreNotifyBudget 

func (s *Session) RestoreNotifyBudget()

RestoreNotifyBudget 用户输入到达本轮输入（Run/Resume 头部消费到非 notify 条目）时恢复全部自续预算。

func (*Session) RunDone 

func (s *Session) RunDone() <-chan struct{}

RunDone 执行体结束信号快照（nil = 无执行体）。

func (*Session) RunFinished 

func (s *Session) RunFinished()

RunFinished 执行体收尾（Run/Resume defer 调用；摘下并关闭 runDone—— 等待者以 close 为同步点，此后 BeginRun 才可能创建新通道，无别名竞态）。

func (*Session) SetAskDecision 

func (s *Session) SetAskDecision(d AskDecision)

SetAskDecision 登记作答（answer 端点调用）。

func (*Session) SetCancel 

func (s *Session) SetCancel(c context.CancelFunc)

SetCancel 挂运行取消口（Stop 时取消）。

func (*Session) SetDecision 

func (s *Session) SetDecision(d ApprovalDecision)

SetDecision 登记决议（approve 端点调用；幂等覆盖前值无意义——单审批通道）。 旧单决议路径（plan 决议/超时兜底/升级前重放）：落 "" 槽。

func (*Session) SetDecisionFor 

func (s *Session) SetDecisionFor(itemID string, d ApprovalDecision)

SetDecisionFor 按项登记决议（合并决议多槽——approve 端点批量形态逐项写入）。

func (*Session) SetMode 

func (s *Session) SetMode(mode string)

SetMode 模式设置（设置通道与随轮次写入共用，docs/05；换档收口见 setModeLocked——同步快照字段 s.Model.Mode，detail/设置回执回显用）。

func (*Session) SetPendingApproval 

func (s *Session) SetPendingApproval(appID string)

SetPendingApproval 挂起登记（approval_request 已发；空 id = 清挂起态）。

func (*Session) SetPendingDue 

func (s *Session) SetPendingDue(kind string, due time.Time)

SetPendingDue 挂起计时元数据登记（startApprovalTimer 挂表时同步调用—— 挂起态落盘在 finishOf 其后，元数据随之持久；跨重启续表依据）。

func (*Session) SetPendingItems 

func (s *Session) SetPendingItems(ids []string)

SetPendingItems 合并决议卡项标识清单登记（pump 聚合发卡后调用；与 SetPendingApproval 同生命周期——清挂起态时一并清空）。

func (*Session) SetPendingTarget added in v0.5.0 

func (s *Session) SetPendingTarget(id string)

SetPendingTarget 挂起审批的路由目标（T6：Options.ApprovalRouter 裁决后 泵面写入；空 = 不路由）。

func (*Session) SetRunModel 

func (s *Session) SetRunModel(model, effort string)

SetRunModel 会话内切换模型/effort（BeginRun 抢占成功后由 API 层调用—— 运行边界生效：当前执行体不被打断，新值从本轮起用；空值保持现值。 换模型不作废任务期授权——授权跟任务不跟模型）。切换只记录不落事件—— 切换标志注记在调用边界（NoteModelCall：本次调用与上次实际调用比对， 2026-09-03 用户定调——选择器切换与显示标志是两回事）。

func (*Session) SetState 

func (s *Session) SetState(state string)

SetState 状态迁移 + 更新时间。

func (*Session) SetTitle 

func (s *Session) SetTitle(title string)

SetTitle / TitleOf 标题读写（genTitle 异步写）。

func (*Session) SetTurnActor added in v0.5.0 

func (s *Session) SetTurnActor(p *contract.Participant)

SetTurnActor 当轮说话人（T6：渠道/应用在 Run 前设置）。

func (*Session) SetTurnFirst added in v0.5.1 

func (s *Session) SetTurnFirst(first bool)

SetTurnFirst 轮次首轮标记（Run 入口判定：本轮开始前历史无 assistant； 跨审批中断保留——挂起段 flushAcc 入史不污染判定，Resume 收尾消费）。

func (*Session) SetTurnUserMsg 

func (s *Session) SetTurnUserMsg(msg string)

SetTurnUserMsg / TakeTurnUserMsg 轮次用户消息（跨审批中断保留——Resume 完成 时随 assistant 终态一并入历史）。

func (*Session) SnapshotEvents 

func (s *Session) SnapshotEvents() []Event

SnapshotEvents 事件快照（追赶回放源）。

func (*Session) StateOf 

func (s *Session) StateOf() string

StateOf 当前状态读取（与 State 字段区分）。

func (*Session) Steer 

func (s *Session) Steer(msg string, atts []Attachment, mode string) bool

Steer running/pending 中再输入：入队 + 模式即时切换（docs/05）。 返回 false = 会话空闲（走正常 Run 而非 steering）。入队落 steer_queued 事件——排队态可回放重建（切回/刷新不丢，对齐审批决议回执定案）。

func (*Session) SteerBy added in v0.5.0 

func (s *Session) SteerBy(actor *contract.Participant, msg string, atts []Attachment, mode string) bool

SteerBy 带说话人入队（T6 多参与者：群聊中他人消息排队不丢身份—— 排队消息与 steer_queued 事件携带 Speaker，运行中注入/下轮前置均署名）。

func (*Session) Stop 

func (s *Session) Stop()

Stop 删除会话的停止语义：置位 + close 通道 + 取消运行上下文（幂等）。

func (*Session) Stopped 

func (s *Session) Stopped() bool

Stopped 删除置位检查。

func (*Session) Subscribe 

func (s *Session) Subscribe() (chan Event, int)

Subscribe 旁观订阅（返回通道与订阅时最新事件 ID——追赶回放去重基准）。 慢消费者不阻塞运行：通道满即丢弃（旁观是尽力而为视图，回看端点兜底完整流）。

func (*Session) SummaryOf 

func (s *Session) SummaryOf() string

SummaryOf 取列表摘要（公开读取——引擎 session_end 载荷用）。

func (*Session) TakeAskDecision 

func (s *Session) TakeAskDecision() *AskDecision

TakeAskDecision 取走作答（Resume 消费；取后清空防复用）。

func (*Session) TakeDecision 

func (s *Session) TakeDecision() *ApprovalDecision

TakeDecision 取走决议（Resume 消费；取后清空防复用）。

func (*Session) TakeDecisionFor 

func (s *Session) TakeDecisionFor(itemID string) *ApprovalDecision

TakeDecisionFor 按项取走决议（Resume 重放时各审批工具按保存态 item_id 领各自的；取后清空防复用；无决议 = nil → fail-closed 拒绝）。

func (*Session) TakeFlushMark 

func (s *Session) TakeFlushMark() bool

func (*Session) TakePending 

func (s *Session) TakePending() []QueuedMsg

TakePending 取走排队消息（Run 前置带回——排队兜底路径）。

func (*Session) TakeTurnUserMsg 

func (s *Session) TakeTurnUserMsg() string

func (*Session) TaskGranted 

func (s *Session) TaskGranted() bool

func (*Session) TaskOf added in v0.2.0 

func (s *Session) TaskOf() string

TaskOf 会话任务摘要读（首条用户消息截断——与落盘 sessionRecord.Task 同源； recall 检索与 TurnEpilogue 交接载荷用）。

func (*Session) TitleFlight 

func (s *Session) TitleFlight() <-chan struct{}

TitleFlight 标题生成在途信号：nil = 无在途；关闭 = 写收尾完成。

func (*Session) TitleOf 

func (s *Session) TitleOf() string

func (*Session) TurnActorOf added in v0.5.0 

func (s *Session) TurnActorOf() *contract.Participant

TurnActorOf 当轮说话人（nil = 单用户零变化——引擎回退 Owner 语义）。

func (*Session) TurnFirstOf added in v0.5.1 

func (s *Session) TurnFirstOf() bool

TurnFirstOf 轮次首轮标记读取（settleTurn 标题触发依据）。

func (*Session) TurnGranted 

func (s *Session) TurnGranted() bool

func (*Session) TurnUserMsgOf 

func (s *Session) TurnUserMsgOf() string

TurnUserMsgOf 轮次用户消息读取（标题生成输入）。

func (*Session) Unsubscribe 

func (s *Session) Unsubscribe(ch chan Event)

Unsubscribe 摘除订阅（断连/收尾）。

func (*Session) UpsertParticipant added in v0.5.0 

func (s *Session) UpsertParticipant(p contract.Participant) string

UpsertParticipant 名册登记（T6）：首见落 joined、在册变更落 updated （participant_update 事件——回放重建 roster 的真源，不依赖 session.json 快照）。Name/Role 空值不覆盖在册值（部分更新）。返回变更 Kind（无变更 空串）；Kind 封闭集含 left（移除面待第一个消费者，本批不开）。

type SessionDetail 

type SessionDetail struct {
	SID       string             `json:"sid"`
	Owner     string             `json:"owner"`
	State     string             `json:"state"`
	Title     string             `json:"title"`
	Mode      string             `json:"mode"`  // 会话当前档位（前端切回恢复 composer 显示）
	Model     contract.UserPrefs `json:"model"` // 会话模型快照（创建时粘住——前端恢复显示用）
	StartedAt string             `json:"started_at"`
	UpdatedAt string             `json:"updated_at"` // 最新活动时间（头部展示）
	Events    []Event            `json:"events"`
}

SessionDetail 回看/软恢复载荷（字段契约 = M3-2 桩 detail）。

type SessionListItem 

type SessionListItem struct {
	SID       string `json:"sid"`
	Owner     string `json:"owner"`
	State     string `json:"state"`
	Title     string `json:"title"` // Title || Task（存量兼容回退）
	StartedAt string `json:"started_at"`
	UpdatedAt string `json:"updated_at"` // 最新活动时间（列表展示与排序键）
	Summary   string `json:"summary"`
}

SessionListItem 列表条目（活动时间倒序；字段契约 = M3-2 桩 + 2026-08-23 增 updated_at）。

type Store 

type Store interface {
	ReadUserTreeFile(operator, rel string) ([]byte, bool)
	WriteUserTreeFile(operator, rel string, data []byte) error
	RemoveUserTree(operator, rel string) error
	// UserTreeDir 用户域根绝对路径（.agent/users/<op>；会话工作区
	// workspaces/<sid> 在其下——Delete/Sweep 清理链用）。契约：须为本地
	// 文件系统路径——Sweeper 与 recall 检索（persist_read.go）直用 os 操作，
	// 文件保存会话是本基座唯一支持的存储形态（无 DB 型实现需求）。
	UserTreeDir(operator string) string
	ListUserTreeSessions(operator string) []string
	ListUsers() []string
	TmpDir() string
	Dir() string
}

Store 会话域存储面（应用注入——产品 FileStore 结构性满足）。 契约：operator 是用户标识符——实现方构造用户域路径时必须圈禁（结构规则 见 ValidOwner：无路径分隔符、非 ./.. ——否则 operator 可携带 ../ 穿越 users/<op>/ 树读写区外，安全审查 2026-09-06）。

type Sweeper 

type Sweeper struct {
	// contains filtered or unexported fields
}

Sweeper 过期清理器（触发 = Registry.Create 新建会话顺带全量扫一轮， 2026-08-23 定——无后台定时任务）。

func NewSweeper 

func NewSweeper(st Store, reg *Registry) *Sweeper

NewSweeper 构造。

func (*Sweeper) RunOnce 

func (s *Sweeper) RunOnce(now time.Time) int

RunOnce 扫一轮：各用户 sessions/ 下超期（按活动时间 UpdatedAt，7 天无活动） 目录整删 + 内存幽灵摘除（内存活跃会话跳过——7 天 TTL 不可能与运行中会话 相交，防御性判断）。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.