Documentation
¶
Overview ¶
Package steer 运行中接管(steer):用户在一轮编排**运行中**注入新输入时的 协作中止与保产续跑——五件套缺一不可(issue #168,spec 2026-09-13-interrupt-insert §5):
- **协作中止信号**(ErrSteered + Signal/IsSteered):带 Cause 的 ctx 取消, 与用户取消(finalize.ErrUserCancelled)/ 进程停机(裸 ctx 取消)可区分;
- **保产摘要**(BuildSummary):已完成环节机械拼接,**不调 LLM**——收尾在 脱离 ctx 里跑,须快且不引入新失败面;读取失败走降级文案,不中断收尾;
- **不落终态回可认领态**:接管不是失败也不是取消,回 created 由 Dispatcher 认领开新一轮(与自动续跑同一管线);
- **队列感知**(Decide):有排队条目才回 created,否则按失败收敛—— 接管条目已被本轮消费时回 created 会开一个无人认领的空轮;
- **条件迁移单协程执行**(Run):迁移只由本函数执行,无双跑窗口; 并发投喂时条件迁移恰有一个赢家,输家零行静默。
生命周期: Experimental(v0.38.0 定级)——本包仍会随宿主接入打磨 (文案头与结算回调的接缝形状),不承诺兼容;定级理由见 api-lifecycle.yaml, 分级规则见 docs/api-compat.md。
判据只依赖可注入事实(零领域词) ¶
摘要构建的输入(环节清单)、队列非空与否、条件迁移结果——三样全部经 Store 注入,本包不认识任何领域字段;文案头(Spec.Header / Spec.FailReport) 由宿主注入,内核只出机械正文。
划界(同词不同域,互指不重复) ¶
- vs finalize(issue #167):finalize 管 Cause→终态的**路由**(本包的 ErrSteered 是它接管臂的输入——**steer 产出 Cause、finalize 消费**, 依赖方向 finalize → steer 单向,不许环);本包管接管臂的**载荷与续跑 语义**(摘要、回 created、队列续跑、空队列失败收敛)。两边包头互指。
- vs handoff:handoff 改写**负责人字段**(From→To 的交接单+回执+代次, 跨进程);本包是**同一会话内**用户对自有轮次的抢占——无所有权转移、 无交接单。
- vs taskboard 的「接管」:那是租约到期的**被动重跑**;本包是用户 **主动抢占**运行中的轮并摘要续跑。
- vs drain:drain 是停机排水(进程要死了);本包是用户要改指令 (进程活得好好的)。
- vs pending:pending 是等待用户答复的挂起载体;本包**不挂起**—— 当场中止并重开轮。
Index ¶
Constants ¶
const ( // DefaultStepSummaryCap 单环节摘要缺省上限(字符)。 DefaultStepSummaryCap = 150 // DefaultReportCap 整份摘要缺省上限(字符)。 DefaultReportCap = 1200 )
摘要截断上限的缺省值(对齐宿主实测口径:单环节一条短摘要、整份控制在一屏内)。
Variables ¶
var ErrSteered = errors.New("会话被用户新输入接管")
ErrSteered 用户运行中注入新输入(接管)的协作中止 Cause。
与用户取消同走 WithCancelCause 中止、但收尾语义不同:不落 cancelled 终态, 而是写环节摘要后回 created 立即续跑(队列已空则按失败收敛,见 Decide)。 分流判定在 finalize.Route(它消费本哨兵,单向依赖不许环)。
Functions ¶
func BuildSummary ¶
BuildSummary 保产摘要的机械拼接(纯函数,**不调 LLM**): 只计成功环节,逐条 slug:摘要,截断后拼成正文。
输入是宿主注入的环节清单(含状态),输出是**正文**——文案头(如标题行) 留宿主拼接(compose 由 Run 调用;宿主直接用本函数时自行前置)。 畸形/超长输入不报错:单条按空摘要处理、整份按 Caps.Report 截断—— 摘要是收尾期的保产面,宁可少一段也不许把收尾卡死。
func DegradedReport ¶
func DegradedReport() string
DegradedReport 环节清单读取失败时的降级正文(与 BuildSummary 同骨架位, 明示读取失败——「没有检查」与「检查通过」必须分得开)。
Types ¶
type Caps ¶
type Caps struct {
// StepSummary 单环节摘要上限(0 → DefaultStepSummaryCap)。
StepSummary int
// Report 整份摘要上限(0 → DefaultReportCap)。
Report int
}
Caps 摘要截断上限(零值取缺省;负值 = 不截断)。
type Decision ¶
type Decision int
Decision 队列感知的回迁决策。
type DoneStep ¶
type DoneStep struct {
Slug string // 环节标识
Summary string // 环节产出摘要(宿主从环节报告提取;畸形报告按空处理)
Status string // 环节状态(contract 词表;statemachine 同值别名)
}
DoneStep 一个环节的注入事实(宿主从环节行取;本包不读库)。
Status 是**环节状态**,词表以 contract 为准(BuildSummary 只计 contract.StatusSucceeded;statemachine 的状态常量是同一批值的别名, issue #354/#357)——skipped / rolled_back / rejected / failed 无有效产出, 失败环节留给下一轮重新评估。宿主的环节状态词表若不同,在注入边界上映射, 不要改本包的判定词。
type Outcome ¶
type Outcome struct {
// Decision 走到的臂(队列感知裁决结论)。
Decision Decision
// Status 实际迁移到的状态;0 行(他路已接手)为空——不谎报。
Status string
// Hit 条件迁移是否命中(并发投喂恰有一个赢家)。
Hit bool
}
Outcome 接管收尾结果。
func Run ¶
Run 执行接管收尾——**条件迁移只由本函数执行**(调用方不得另起协程迁移, 无双跑窗口;并发投喂时条件迁移恰有一个赢家,输家零行静默)。
并发纪律:脱离 ctx ¶
一切存储调用走 context.WithoutCancel 派生的脱离 ctx:编排 ctx 已被接管 信号取消,存储直查会直接中止 ⇒ 摘要与回迁全部写不进去,会话滞留 running。
流程 ¶
- 队列感知裁决(Decide)——队列读失败按无排队(不开空轮的保守侧);
- 失败臂(队列空):迁 running→failed(仲裁)→ **命中才**写宿主注入的 失败报告,零行 = 他路已接手静默;
- 回迁臂:读环节清单(失败降级正文,不中断)→ 机械拼摘要(不调 LLM) → 迁 running→created(仲裁)→ **命中才**写报告,零行 = 他路已接手 静默(不发事件、不写报告——事件与终报都只属于已接手的那一路, 双发是谎报第二次,覆写是把赢家结论换成输家的)。
写序纪律:仲裁先于终报(issue #205) ¶
并发投喂恰有一个赢家(Migrate 条件迁移保证),而失败臂与回迁臂的报告文本 完全不同(FailReport vs 保产摘要)——两路裁决不一致时(队列读失败按 fail-closed、或队列状态在两次读之间变化),报告若写在迁移之前,输家会把 赢家的终报覆写成相反结论。故报告一律排在 Migrate 命中之后:先仲裁、后落笔。
type Spec ¶
type Spec struct {
// Header 摘要文案头(宿主注入,如标题行;空 = 只落正文)。
Header string
// FailReport 队列空失败收敛的报告文本(宿主注入;空 = 不写报告)。
FailReport string
// Caps 摘要截断上限(零值取缺省)。
Caps Caps
}
Spec 一次接管收尾的注入事实(文案与上限留宿主——零领域词)。
type Store ¶
type Store interface {
// ReadSteps 读环节清单(含状态;BuildSummary 只计成功环节)。
// 读失败不中断收尾:Run 用降级正文继续(保产摘要的失败面不得扩大)。
ReadSteps(ctx context.Context) ([]DoneStep, error)
// HasQueue 队列是否仍有排队条目。读失败按「无排队」判定(保守侧:
// 不开空轮)并留痕——排队消息伪装成不存在的代价是少续跑一轮,
// 伪装成存在开空轮的代价是无人认领的僵轮,前者可补、后者是死轮。
HasQueue(ctx context.Context) (bool, error)
// SetReport 覆写终报(覆写前折叠旧结论留宿主;文案拼装也在宿主)。
// 只在 Migrate 命中后由本包调用(issue #205):终报只属于赢下仲裁的
// 那一路,输家不得落任何报告写。
SetReport(ctx context.Context, text string) error
// Migrate 一次原子条件迁移:现状态 ∈ from 时迁移到 to;ok=false = 0 行
//(他路已接手)。原子性由宿主存储保证,本包只判结果——并发投喂时
// 恰有一个赢家,输家零行静默。
Migrate(ctx context.Context, from []string, to string) (ok bool, err error)
}
Store 接管收尾的存储面(宿主实现——gorm/model 不下沉)。
四个方法就是判据的全部输入:完成环节清单、队列非空与否、报告覆写、 条件迁移——本包不认识任何领域字段。