ezloop

agent := core.NewAgent(p,
    core.WithSystemPrompt("你是一个严谨的助手"),
    core.WithModelWarp(modelretry.Warp()),   // 模型节点：重试
    core.WithToolWarp(limit.Warp(4), safetool.Warp()), // 工具节点：并发闸 + 防护
    core.WithHooks(filetools.New(fsys)),      // 流：文件工具
    core.WithStreaming(true),
)

// 同步单轮
state, err := agent.Run(ctx, "帮我读一下 hello.txt")

// 多轮：上一轮 Messages 直接作为历史（system 自动过滤，不重复注入）
state, err = agent.Run(ctx, "再总结一下", core.WithHistory(state.Messages...))

h := agent.RunAsync(ctx, "长任务")
defer h.Cancel()                      // per-request 取消传播
for e := range h.Events() { render(e) } // loop 结束自动 close；channel 天然并发安全
state, err := h.Wait()

// 或回调式（CLI 直渲）：实现必须并发安全且快速返回
core.WithOnEvent(func(e event.Event) {
    switch e.Type {
    case event.EventModelChunk:     print(e.Data.(string)) // 正文增量
    case event.EventReasoningChunk: print(e.Data.(string)) // 思考增量
    }
})

return hook.Proceed, nil            // 正常执行
return hook.Abort, nil              // 终止整个 loop（StopReason = aborted）
return hook.Skip("denied by policy"), nil // 跳过本次调用，文案作为工具结果入史，循环继续

type Guard struct{}

func (Guard) Name() string { return "guard" }

func (Guard) OnToolStart(_ context.Context, _ *types.LoopState, call *types.ToolCall) (hook.Action, error) {
    if call.Name == "terminal" {
        var a struct{ Command string `json:"command"` }
        _ = json.Unmarshal(call.Args, &a)
        if !isReadOnly(a.Command) {
            return hook.Skip("terminal: read-only commands only"), nil
        }
    }
    return hook.Proceed, nil
}

agent := core.NewAgent(p, core.WithHooks(Guard{})) // 实现了哪个接口就挂到哪个时机

// 装饰器签名：组装时注入 per-Run 事件出口（类比 net/http middleware）
type Handler[T any] func(em event.Emitter, node T) T

// 洋葱序：先注册的在外层 —— 请求外→内，结果内→外
core.WithToolWarp(safetool.Warp(), limit.Warp(4))
// safetool 在外层才能捕获 limit 与工具本体的 panic

// 自定义：跨全部工具共享的计时 warp（状态在工厂闭包里，per-Run 组装）
func Timing() warp.ToolHandler {
    var mu sync.Mutex
    total := time.Duration(0)
    return func(_ event.Emitter, inner types.Tool) types.Tool {
        return toolFunc(func(ctx context.Context, args json.RawMessage) (string, error) {
            start := time.Now()
            out, err := inner.Invoke(ctx, args)
            mu.Lock(); total += time.Since(start); mu.Unlock()
            return out, err
        }, inner)
    }
}

approver, approveCh := approve.New(needsFunc)  // 需要审批的调用返回 true
asker, answerCh   := askuser.New()
planner, planCh   := taskplan.New()

core.NewAgent(p, core.WithHooks(approver, asker, planner), ...)

// hook 在工具调用前阻塞等决策；渲染层在 OnEvent 里呈现请求、
// 从独立 goroutine 回传 channel（同步回传会死锁）。
core.WithOnEvent(func(e event.Event) {
    if e.Type == approve.EventRequest {
        call := e.Data.(*types.ToolCall) // 带 CallID 与 ForkID（分身在问也一样工作）
        go send(ctx, approveCh, approve.Decision{CallID: call.ID, Approve: askHuman(call)})
    }
})

core.NewAgent(p, core.WithHooks(task.New()), ...) // 一步到位，task 工具自动注册

// 主模型对可并行的子任务自动调用 task：
//   同一轮多个 task 并行 fork（工具本就并发）
//   分身复刻当前 Agent 与上下文快照，过程隔离，只回传最终答案
//   审批照拦、可问用户；事件带 ForkID（⟨task-N⟩），session 独立可回放
//   单层：分身不能再 fork

// 碎 delta（每次一两个字符）高频直写终端开销大（Windows console 同步写尤其贵）——
// 攒缓冲定期整块写出：一次系统调用代替上百次。80ms tick 足够顺滑。
sb := &streamBuf{}
ticker := time.NewTicker(80 * time.Millisecond)
go func() { for range ticker.C { sb.flush() } }()
// 提示类输出用 sb.now(s)：并入缓冲后立即整块写出，与流式内容严格有序

fsys := fs.NewLocal(".")                    // 工作区沙箱 = 当前目录
session := localsession.New(fsys, "")          // 每轮结束滚动快照 sessions/<id>.json

// 恢复 = 新对话：加载历史 + 新输入，模型看历史自己重发调用。
// system 是 agent 属性，WithHistory 自动过滤不重复注入；
// 旧存档的悬空 tool_call 由 contextfix 兜底修理。
s, _ := localsession.Load(ctx, fsys, "", id)
state, _ := agent.Run(ctx, input, core.WithHistory(s.Messages...))

// 分身过程同样可回放：sessions/<主ID>-task-1.json，只存增量

// Agent 构建后只读是框架契约：全局单例，并发 Run 安全，
// 每次运行的全部状态在独立的 LoopState 里，互不可见。
agent := core.NewAgent(p, ...) // 进程启动时组装一次

func handle(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithCancel(r.Context())
    defer cancel()                       // 客户端断连 → 只取消本次 loop

    // 按请求恢复历史（会话归属在业务层：URL/租户头 → session ID）
    h := agent.RunAsync(ctx, input, core.WithHistory(load(r)...))
    defer h.Cancel()

    for e := range h.Events() {         // 每请求独立事件通道，天然隔离
        switch e.Type {
        case event.EventModelChunk:
            writeSSE(w, e.ForkID, e.Data.(string)) // ForkID 非空 = 分身输出，路由标记
        case approve.EventRequest:
            pushCard(w, e.Data.(*types.ToolCall)) // 渲染审批卡片，用户点击后回传
        }
    }
    state, _ := h.Wait()
    save(r, state.Messages)
}