steer

package
v0.47.0 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package steer 运行中接管(steer):用户在一轮编排**运行中**注入新输入时的 协作中止与保产续跑——五件套缺一不可(issue #168,spec 2026-09-13-interrupt-insert §5):

  1. **协作中止信号**(ErrSteered + Signal/IsSteered):带 Cause 的 ctx 取消, 与用户取消(finalize.ErrUserCancelled)/ 进程停机(裸 ctx 取消)可区分;
  2. **保产摘要**(BuildSummary):已完成环节机械拼接,**不调 LLM**——收尾在 脱离 ctx 里跑,须快且不引入新失败面;读取失败走降级文案,不中断收尾;
  3. **不落终态回可认领态**:接管不是失败也不是取消,回 created 由 Dispatcher 认领开新一轮(与自动续跑同一管线);
  4. **队列感知**(Decide):有排队条目才回 created,否则按失败收敛—— 接管条目已被本轮消费时回 created 会开一个无人认领的空轮;
  5. **条件迁移单协程执行**(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

View Source
const (
	// DefaultStepSummaryCap 单环节摘要缺省上限(字符)。
	DefaultStepSummaryCap = 150
	// DefaultReportCap 整份摘要缺省上限(字符)。
	DefaultReportCap = 1200
)

摘要截断上限的缺省值(对齐宿主实测口径:单环节一条短摘要、整份控制在一屏内)。

Variables

View Source
var ErrSteered = errors.New("会话被用户新输入接管")

ErrSteered 用户运行中注入新输入(接管)的协作中止 Cause。

与用户取消同走 WithCancelCause 中止、但收尾语义不同:不落 cancelled 终态, 而是写环节摘要后回 created 立即续跑(队列已空则按失败收敛,见 Decide)。 分流判定在 finalize.Route(它消费本哨兵,单向依赖不许环)。

Functions

func BuildSummary

func BuildSummary(steps []DoneStep, caps Caps) string

BuildSummary 保产摘要的机械拼接(纯函数,**不调 LLM**): 只计成功环节,逐条 slug:摘要,截断后拼成正文。

输入是宿主注入的环节清单(含状态),输出是**正文**——文案头(如标题行) 留宿主拼接(compose 由 Run 调用;宿主直接用本函数时自行前置)。 畸形/超长输入不报错:单条按空摘要处理、整份按 Caps.Report 截断—— 摘要是收尾期的保产面,宁可少一段也不许把收尾卡死。

func DegradedReport

func DegradedReport() string

DegradedReport 环节清单读取失败时的降级正文(与 BuildSummary 同骨架位, 明示读取失败——「没有检查」与「检查通过」必须分得开)。

func IsSteered

func IsSteered(ctx context.Context) bool

IsSteered ctx 的 Cause 是否为接管信号(errors.Is,可判包装链)。

只回答「是不是接管」;与用户取消/停机的三分路由在 finalize.Route。

func Signal

func Signal(parent context.Context) (context.Context, func())

Signal 返回携带接管 Cause 的协作中止 ctx 与只发接管信号的 cancel。

宿主在用户注入新输入时调用 cancel()——签名收**无参** func:Cause 固定为 ErrSteered,不给「发错 Cause」留口子。分流判定见 IsSteered 与 finalize.Route。

Types

type Caps

type Caps struct {
	// StepSummary 单环节摘要上限(0 → DefaultStepSummaryCap)。
	StepSummary int
	// Report 整份摘要上限(0 → DefaultReportCap)。
	Report int
}

Caps 摘要截断上限(零值取缺省;负值 = 不截断)。

type Decision

type Decision int

Decision 队列感知的回迁决策。

const (
	// DecisionFailConverge 队列已空(接管条目已被本轮消费):按失败收敛,
	// **不开空轮**。零值即此——保守侧缺省,漏传队列事实时不开新轮。
	DecisionFailConverge Decision = iota
	// DecisionRequeue 队列非空:回 created 由 Dispatcher 认领开新一轮。
	DecisionRequeue
)

func Decide

func Decide(hasQueue bool) Decision

Decide 队列感知裁决:有排队条目才回 created,否则按失败收敛不开空轮。

这是纯函数——「队列非空与否」是宿主注入的事实(Store.HasQueue), 本包不自己读库。

func (Decision) String

func (d Decision) String() string

String 决策的人类可读形态(留痕与测试失败信息用)。

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

func Run(ctx context.Context, store Store, spec Spec) (Outcome, error)

Run 执行接管收尾——**条件迁移只由本函数执行**(调用方不得另起协程迁移, 无双跑窗口;并发投喂时条件迁移恰有一个赢家,输家零行静默)。

并发纪律:脱离 ctx

一切存储调用走 context.WithoutCancel 派生的脱离 ctx:编排 ctx 已被接管 信号取消,存储直查会直接中止 ⇒ 摘要与回迁全部写不进去,会话滞留 running。

流程

  1. 队列感知裁决(Decide)——队列读失败按无排队(不开空轮的保守侧);
  2. 失败臂(队列空):迁 running→failed(仲裁)→ **命中才**写宿主注入的 失败报告,零行 = 他路已接手静默;
  3. 回迁臂:读环节清单(失败降级正文,不中断)→ 机械拼摘要(不调 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 不下沉)。

四个方法就是判据的全部输入:完成环节清单、队列非空与否、报告覆写、 条件迁移——本包不认识任何领域字段。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL