Documentation
¶
Overview ¶
本文件复刻官方 subagent/src/depth.ts:委托深度核算。顶层代理深度为 0,每派生 一层子代理深度 +1;持久化头与运行期选项取 max(运行期只能加深、不能降低,否则 一个恢复出来的子代理会被当成顶层而获得过多委托预算)。
本文件实现 subagent 的 in-process fork 后端(任务 S02)。
InProcessProvider 在进程内 fork 一个子代理:复用当前进程的上下文(LLM 适配器 / 工具流水线),执行给定的子任务输入,返回父→子家谱与输出。它是 S02 验收测试 (subagent_fork_inprocess_test.go)对应的可运行后端;ACP / fork-copy 提供桩以便接口留位。
Package subagent 提供子代理接缝(任务 S02:Subagent 3 后端)。
对齐上游:packages/subagent/subagent + providers
设计要点:
- Provider 抽象把「如何起一个子代理」与「子代理执行什么」解耦,支持三种后端:
- InProcess —— 进程内 fork(复用当前 Agent 上下文执行一个子任务,单测主用);
- ACP / ForkCopy —— 原生协议/复制进程类后端(本版提供最小可运行桩,接口稳定);
- ForkLineage 记录父子关系(parent 会话 → 子会话),供因果归因(与 M33 Initiator 一致);
- Handle 是子代理的生命周期句柄:Drain 阻塞等子代理落盘完成;Dispose 释放并级联取消子代理 (父 dispose → 子自动 drain/清理)。
Index ¶
- Variables
- func CanDelegate(depth, maxDepth int) bool
- func ChildDepth(parentDepth int) (int, error)
- func IsUnknownProvider(err error) bool
- func ResolveDepth(headerDepth, runtimeDepth int) (int, error)
- type ErrUnknownProvider
- type ForkLineage
- type Handle
- type InProcessProvider
- type InProcessRunner
- type Provider
- type Runtime
- func (r *Runtime) ActiveCount() int
- func (r *Runtime) DisposeOwner(parent brand.SessionID)
- func (r *Runtime) Provider(name string) (Provider, bool)
- func (r *Runtime) RegisterProvider(p Provider) error
- func (r *Runtime) Spawn(ctx context.Context, providerName string, req SpawnRequest) (*Handle, error)
- type SpawnRequest
- type SpawnResult
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidDepth = errors.New("subagent: depth must be a non-negative integer")
ErrInvalidDepth 表示深度/上限不是非负整数。
Functions ¶
func CanDelegate ¶
CanDelegate 判断当前深度是否还能再派生子代理。 maxDepth < 0 表示不限制;否则 depth 必须小于 maxDepth。
func ResolveDepth ¶
ResolveDepth 合并持久化头深度与运行期深度,取较大者(运行期只可加深)。
Types ¶
type ErrUnknownProvider ¶
type ErrUnknownProvider struct{ Name string }
ErrUnknownProvider 表示后端未注册。
func (*ErrUnknownProvider) Error ¶
func (e *ErrUnknownProvider) Error() string
type ForkLineage ¶
type ForkLineage struct {
Parent *brand.SessionID `json:"parent,omitempty"` // 父会话(nil=顶层)
Session brand.SessionID `json:"session"` // 子会话
}
ForkLineage 记录一次 fork 的家谱(父会话 → 子会话)。
type Handle ¶
type Handle struct {
Provider string // 所属后端名
Lineage ForkLineage
// contains filtered or unexported fields
}
Handle 是子代理生命周期句柄。
type InProcessProvider ¶
type InProcessProvider struct {
// contains filtered or unexported fields
}
InProcessProvider 是进程内 fork 后端。
func NewInProcessProvider ¶
func NewInProcessProvider(runner InProcessRunner) *InProcessProvider
NewInProcessProvider 创建 in-process 后端。runner 为 nil 时默认同步占位执行。
func (*InProcessProvider) Spawn ¶
func (p *InProcessProvider) Spawn(ctx context.Context, req SpawnRequest) (*Handle, error)
Spawn 实现 Provider:调用 runner 执行子任务并返回句柄。
type InProcessRunner ¶
type InProcessRunner func(ctx context.Context, req SpawnRequest) (sid brand.SessionID, output string, err error)
InProcessRunner 是 in-process 后端的实际执行函数(由上层注入事务性实现)。 约定:返回子会话 ID、输出文本与错误。
type Provider ¶
type Provider interface {
// Name 返回后端名(如 "in-process" / "acp" / "fork-copy")。
Name() string
// Spawn 生成并运行一个子代理,返回可释放的句柄。
Spawn(ctx context.Context, req SpawnRequest) (*Handle, error)
}
Provider 是子代理后端接缝。
type Runtime ¶
type Runtime struct {
// contains filtered or unexported fields
}
Runtime 是子代理运行时:持有 Provider 注册表与活跃句柄。
func (*Runtime) DisposeOwner ¶
DisposeOwner 释放某父会话名下的全部子代理句柄(级联取消)。
func (*Runtime) RegisterProvider ¶
RegisterProvider 注册后端。
type SpawnRequest ¶
type SpawnRequest struct {
Parent *brand.SessionID `json:"parent,omitempty"`
Input string `json:"input"`
MaxRounds int `json:"maxRounds,omitempty"`
}
SpawnRequest 是生成子代理的请求。
type SpawnResult ¶
type SpawnResult struct {
Lineage ForkLineage `json:"lineage"`
Output string `json:"output"`
Err string `json:"err,omitempty"`
}
SpawnResult 是一次子代理运行的输出。