subagent

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 4 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
var ErrInvalidDepth = errors.New("subagent: depth must be a non-negative integer")

ErrInvalidDepth 表示深度/上限不是非负整数。

Functions

func CanDelegate

func CanDelegate(depth, maxDepth int) bool

CanDelegate 判断当前深度是否还能再派生子代理。 maxDepth < 0 表示不限制;否则 depth 必须小于 maxDepth。

func ChildDepth

func ChildDepth(parentDepth int) (int, error)

ChildDepth 返回父深度派生一个子代理时的深度(+1)。

func IsUnknownProvider

func IsUnknownProvider(err error) bool

IsUnknownProvider 判断是否为未知后端错误。

func ResolveDepth

func ResolveDepth(headerDepth, runtimeDepth int) (int, error)

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 是子代理生命周期句柄。

func (*Handle) Dispose

func (h *Handle) Dispose()

Dispose 释放子代理:标记 disposed(父 dispose 触发子级联清理)。

func (*Handle) Drain

func (h *Handle) Drain(ctx context.Context) error

Drain 阻塞直到子代理完成(或 ctx 取消)。

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) Name

func (p *InProcessProvider) Name() string

Name 实现 Provider。

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 NewRuntime

func NewRuntime() *Runtime

NewRuntime 创建运行时,并注册内置 ACP 与 ForkCopy 桩 Provider。

func (*Runtime) ActiveCount

func (r *Runtime) ActiveCount() int

ActiveCount 返回当前登记句柄数(诊断用)。

func (*Runtime) DisposeOwner

func (r *Runtime) DisposeOwner(parent brand.SessionID)

DisposeOwner 释放某父会话名下的全部子代理句柄(级联取消)。

func (*Runtime) Provider

func (r *Runtime) Provider(name string) (Provider, bool)

Provider 获取指定后端。

func (*Runtime) RegisterProvider

func (r *Runtime) RegisterProvider(p Provider) error

RegisterProvider 注册后端。

func (*Runtime) Spawn

func (r *Runtime) Spawn(ctx context.Context, providerName string, req SpawnRequest) (*Handle, error)

Spawn 通过指定后端生成子代理,并登记句柄。

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 是一次子代理运行的输出。

Jump to

Keyboard shortcuts

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