tako 文档 GitHub

任务看板与单入口 实现计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 新建 internal/taskboard(TaskCreate/TaskUpdate/TaskList/TaskGet 记账工具 + middleware 正本 + session 镜像),收敛出唯一入口 cmd/yktako,删除其余五个入口与 internal/planexec,重写文档。

Architecture: 三层分离(doc/01):Plan 是提示词约定的口述文档;Tasks 是 taskboard 看板,正本存 middleware 自持 Store(跨 REPL 轮次存活),每次变更后 adk.AddSessionValue 全量镜像(interrupt 时随 runContext gob 进 checkpoint);Actions 是现有工具,无外键。宿主是裸 ChatModelAgent,Handlers 链 = [taskboard] + guard 三件套。

Tech Stack: Go 1.25 + eino v0.9.21(adk / compose / schema / components/tool/utils)。

两条约定(覆盖技能默认行为):

  1. 全程不执行任何 git 命令:工作区有用户在途的未提交改动(大量文件 M/D),提交会把在途工作与本次改动混在一起。所有任务完成后由用户统一提交。各任务的「Commit」步骤因此省略。
  2. 直接在仓库工作(未开 worktree,用户未要求隔离)。

工作目录:所有命令都在 yk-tako-eino/ 下执行(特殊注明除外)。

注释硬性要求(AGENTS.md):一律中文注释;每个文件有文件头注释(包内字母序第一个文件用 Package xxx 开头作包文档);每个 type/func/常量组都有注释;实现接口的类型必须在类型注释与方法注释里写明接口归属(import 路径 + 文件 + 接口名)并加 var _ pkg.Interface = (*Type)(nil) 编译期断言;测试文件与假模型同样适用。下面代码示例已按此写,实现时不得删减注释。


Task 1: taskboard 数据模型与 Store

Files:

// 本文件:Store(看板正本)的单元测试——CRUD、deleted 过滤、并发安全。
package taskboard

import (
    "fmt"
    "sort"
    "strconv"
    "sync"
    "testing"
)

// TestStoreCreateAssignsSequentialIDs 验证自增 id 从 "1" 开始、字段落入、返回的是副本。
func TestStoreCreateAssignsSequentialIDs(t *testing.T) {
    s := NewStore()
    first := s.Create("查时间", "调用时钟工具", "查时间")
    second := s.Create("算乘法", "", "")
    if first.ID != "1" || second.ID != "2" {
        t.Fatalf("id 应自增: %q %q", first.ID, second.ID)
    }
    if first.Status != StatusPending || first.Description != "调用时钟工具" || first.ActiveForm != "查时间" {
        t.Fatalf("字段落入不符: %+v", first)
    }
    // 返回副本:改返回值不影响正本
    first.Subject = "改过的"
    got, err := s.Get("1")
    if err != nil || got.Subject != "查时间" {
        t.Fatalf("Create 应返回副本: %+v err=%v", got, err)
    }
}

// TestStoreUpdatePatch 验证按 id patch:空串字段不动原值,status 可改。
func TestStoreUpdatePatch(t *testing.T) {
    s := NewStore()
    s.Create("查时间", "描述", "进行中")
    got, err := s.Update("1", Patch{Status: "in_progress"})
    if err != nil || got.Status != StatusInProgress {
        t.Fatalf("status 应改为 in_progress: %+v err=%v", got, err)
    }
    got, err = s.Update("1", Patch{Subject: "看时间"})
    if err != nil || got.Subject != "看时间" || got.Description != "描述" || got.Status != StatusInProgress {
        t.Fatalf("空串字段不应动原值: %+v err=%v", got, err)
    }
}

// TestStoreUpdateRejectsBadInput 验证非法 id 与非法 status 都报错。
func TestStoreUpdateRejectsBadInput(t *testing.T) {
    s := NewStore()
    s.Create("查时间", "", "")
    if _, err := s.Update("99", Patch{Status: "completed"}); err == nil {
        t.Fatal("不存在的 id 应报错")
    }
    if _, err := s.Update("1", Patch{Status: "doing"}); err == nil {
        t.Fatal("非法 status 应报错")
    }
}

// TestStoreListFiltersDeleted 验证 List 不含 deleted、按创建序;Snapshot 含 deleted。
func TestStoreListFiltersDeleted(t *testing.T) {
    s := NewStore()
    s.Create("一", "", "")
    s.Create("二", "", "")
    s.Create("三", "", "")
    if _, err := s.Update("2", Patch{Status: "deleted"}); err != nil {
        t.Fatal(err)
    }
    list := s.List()
    if len(list) != 2 || list[0].ID != "1" || list[1].ID != "3" {
        t.Fatalf("List 应过滤 deleted 且按创建序: %+v", list)
    }
    if snap := s.Snapshot(); len(snap) != 3 {
        t.Fatalf("Snapshot 应含 deleted: %+v", snap)
    }
}

// TestStoreGetUnknownID 验证 Get 不存在的 id 报错。
func TestStoreGetUnknownID(t *testing.T) {
    if _, err := NewStore().Get("1"); err == nil {
        t.Fatal("不存在的 id 应报错")
    }
}

// TestStoreConcurrentCreate 验证并发 Create 写不坏:100 个 goroutine 下来 id 恰好是 1..100。
// 用 go test -race 跑最有意义。
func TestStoreConcurrentCreate(t *testing.T) {
    s := NewStore()
    var wg sync.WaitGroup
    ids := make(chan string, 100)
    for i := 0; i < 100; i++ {
        wg.Add(1)
        go func(i int) {
            defer wg.Done()
            ids <- s.Create(fmt.Sprintf("任务%d", i), "", "").ID
        }(i)
    }
    wg.Wait()
    close(ids)
    seen := map[string]bool{}
    for id := range ids {
        if seen[id] {
            t.Fatalf("id 重复: %s", id)
        }
        seen[id] = true
    }
    if len(seen) != 100 {
        t.Fatalf("应有 100 个唯一 id,实际 %d", len(seen))
    }
    // 按数值排序比上下限:字符串排序会把 "99" 排在 "100" 之后,比不出上限。
    nums := make([]int, 0, len(seen))
    for id := range seen {
        n, err := strconv.Atoi(id)
        if err != nil {
            t.Fatalf("id 不是数字: %q", id)
        }
        nums = append(nums, n)
    }
    sort.Ints(nums)
    if nums[0] != 1 || nums[len(nums)-1] != 100 {
        t.Fatalf("id 应覆盖 1..100: %d ... %d", nums[0], nums[len(nums)-1])
    }
}

Run: go test ./internal/taskboard/ Expected: FAIL,编译错误 undefined: NewStore 等(包还不存在时是 package yk-tako-eino/internal/taskboard: ... no Go files 类报错,属预期)。

// Package taskboard 是任务看板:TaskCreate/TaskUpdate/TaskList/TaskGet 四个记账工具、
// middleware 注入与看板投影。本文件是数据模型与存储正本(Store);
// 工具与输出格式见 tools.go,middleware 与提示词约定见 middleware.go。
//
// 三层分离(doc/01):Plan 是给人审的文档,Tasks 是带 taskId 的施工看板,
// Actions 是干活工具。本包只管 Tasks 层。
package taskboard

import (
    "encoding/gob"
    "fmt"
    "sync"
)

// init 把快照类型注册给 gob:session.Values 是 map[string]any,interrupt 时 eino 把整个
// runContext(含 session)gob 进 checkpoint,接口字段背后的具体类型必须注册
// (eino 自己注册 []byte 同款,adk/interrupt.go init)。
func init() {
    gob.Register([]Task{})
}

// SessionKey 是看板镜像在 session 里的键。每次变更后全量快照写入;
// interrupt 时随 runContext 落盘(adk/runctx.go 的 runSession 有
// "CheckpointSchema: persisted via serialization.RunCtx (gob)" 标注)。
const SessionKey = "taskboard_session_key_tasks"

// Status 是任务状态:pending → in_progress → completed,不再需要时用 deleted。
type Status string

// 四个合法状态值,与 eino plantask / Claude Tasks 对齐。
const (
    StatusPending    Status = "pending"
    StatusInProgress Status = "in_progress"
    StatusCompleted  Status = "completed"
    StatusDeleted    Status = "deleted"
)

// validStatus 校验 TaskUpdate 传入的 status 字符串。
func validStatus(s string) bool {
    switch Status(s) {
    case StatusPending, StatusInProgress, StatusCompleted, StatusDeleted:
        return true
    }
    return false
}

// Task 是一条看板行。taskId 只寻址看板行:与 plan 条目、tool_call 都无外键。
type Task struct {
    ID          string `json:"id"`
    Subject     string `json:"subject"`
    Description string `json:"description,omitempty"`
    ActiveForm  string `json:"activeForm,omitempty"`
    Status      Status `json:"status"`
}

// Patch 是 TaskUpdate 的可改字段。空串表示「不动」(所以字段无法清成空串,是有意取舍)。
type Patch struct {
    Subject     string
    Description string
    ActiveForm  string
    Status      string
}

// Store 是看板正本:middleware 自持,agent 建一次,跨 REPL 轮次存活。
// 所有方法加锁,同轮并行的工具调用也写不坏。
type Store struct {
    mu     sync.Mutex
    tasks  map[string]*Task
    order  []string // 创建顺序,看板按它排
    nextID int
}

// NewStore 建一个空看板,id 从 "1" 开始自增。
func NewStore() *Store {
    return &Store{tasks: map[string]*Task{}, nextID: 1}
}

// Create 建一条 pending 任务,返回副本(调用方改不到内部)。
func (s *Store) Create(subject, description, activeForm string) Task {
    s.mu.Lock()
    defer s.mu.Unlock()
    id := fmt.Sprintf("%d", s.nextID)
    s.nextID++
    t := &Task{ID: id, Subject: subject, Description: description, ActiveForm: activeForm, Status: StatusPending}
    s.tasks[id] = t
    s.order = append(s.order, id)
    return *t
}

// Update 按 id patch;id 不存在或 status 非法时报错。
func (s *Store) Update(id string, p Patch) (Task, error) {
    s.mu.Lock()
    defer s.mu.Unlock()
    t, ok := s.tasks[id]
    if !ok {
        return Task{}, fmt.Errorf("任务 #%s 不存在", id)
    }
    if p.Status != "" {
        if !validStatus(p.Status) {
            return Task{}, fmt.Errorf("非法 status %q:只能是 pending/in_progress/completed/deleted", p.Status)
        }
        t.Status = Status(p.Status)
    }
    if p.Subject != "" {
        t.Subject = p.Subject
    }
    if p.Description != "" {
        t.Description = p.Description
    }
    if p.ActiveForm != "" {
        t.ActiveForm = p.ActiveForm
    }
    return *t, nil
}

// Get 读单条;不存在报错。
func (s *Store) Get(id string) (Task, error) {
    s.mu.Lock()
    defer s.mu.Unlock()
    t, ok := s.tasks[id]
    if !ok {
        return Task{}, fmt.Errorf("任务 #%s 不存在", id)
    }
    return *t, nil
}

// List 返回未 deleted 的任务,按创建序;返回副本切片。
func (s *Store) List() []Task {
    s.mu.Lock()
    defer s.mu.Unlock()
    out := make([]Task, 0, len(s.order))
    for _, id := range s.order {
        if t := s.tasks[id]; t.Status != StatusDeleted {
            out = append(out, *t)
        }
    }
    return out
}

// Snapshot 返回全量任务(含 deleted),给 session 镜像用。
func (s *Store) Snapshot() []Task {
    s.mu.Lock()
    defer s.mu.Unlock()
    out := make([]Task, 0, len(s.order))
    for _, id := range s.order {
        out = append(out, *s.tasks[id])
    }
    return out
}

Run: go test -race ./internal/taskboard/ Expected: PASS(6 个测试)


Task 2: 四工具与输出格式

Files:

// 本文件:四个记账工具的输出格式测试——回执、看板、催更块,以及非法输入。
// 单测直接调工具函数,ctx 里没有 runCtx,session 镜像是静默空操作
// (adk.AddSessionValue 在无 session 时直接返回,adk/runctx.go 的 AddSessionValue),
// 镜像的验证在 integration_test.go 的真实 run 里做。
package taskboard

import (
    "context"
    "strings"
    "testing"

    "github.com/cloudwego/eino/components/tool"
)

// invoke 按名字找到工具并执行,返回输出文本。
// 工具经 utils.InferTool 生成,实现 tool.InvokableTool
// (github.com/cloudwego/eino/components/tool 包 interface.go:42)。
func invoke(t *testing.T, tools []tool.BaseTool, name, args string) string {
    t.Helper()
    for _, bt := range tools {
        info, err := bt.Info(context.Background())
        if err != nil || info.Name != name {
            continue
        }
        it, ok := bt.(tool.InvokableTool)
        if !ok {
            t.Fatalf("%s 未实现 tool.InvokableTool", name)
        }
        out, err := it.InvokableRun(context.Background(), args)
        if err != nil {
            t.Fatalf("%s 执行: %v", name, err)
        }
        return out
    }
    t.Fatalf("工具 %s 不存在", name)
    return ""
}

// newTools 建 Store 并生成四个工具,测试入口。
func newTools(t *testing.T) (*Store, []tool.BaseTool) {
    t.Helper()
    s := NewStore()
    tools, err := makeTools(s)
    if err != nil {
        t.Fatalf("makeTools: %v", err)
    }
    if len(tools) != 4 {
        t.Fatalf("应有 4 个工具,实际 %d", len(tools))
    }
    return s, tools
}

// TestCreateOutput 验证 TaskCreate 输出 = 回执(含 taskId)+ 看板 + 催更块。
func TestCreateOutput(t *testing.T) {
    _, tools := newTools(t)
    out := invoke(t, tools, ToolCreate, `{"subject":"查时间","activeForm":"查时间"}`)
    for _, want := range []string{"已创建任务 #1", "查时间", "📋 任务看板(0/1 已完成)", "⚠️ 还有 1 项未完成"} {
        if !strings.Contains(out, want) {
            t.Fatalf("输出应含 %q:\n%s", want, out)
        }
    }
}

// TestUpdateOutput 验证 TaskUpdate 后看板反映新状态;唯一任务完成后催更块消失。
func TestUpdateOutput(t *testing.T) {
    _, tools := newTools(t)
    invoke(t, tools, ToolCreate, `{"subject":"查时间"}`)
    out := invoke(t, tools, ToolUpdate, `{"taskId":"1","status":"in_progress"}`)
    if !strings.Contains(out, "🔄 #1 查时间") {
        t.Fatalf("看板应显示 in_progress:\n%s", out)
    }
    out = invoke(t, tools, ToolUpdate, `{"taskId":"1","status":"completed"}`)
    if !strings.Contains(out, "✅ #1 查时间") || !strings.Contains(out, "1/1 已完成") {
        t.Fatalf("看板应显示 completed:\n%s", out)
    }
    if strings.Contains(out, "⚠️") {
        t.Fatalf("全部完成后不应再有催更块:\n%s", out)
    }
}

// TestUpdateInvalidStatusReturnsError 验证非法 status 作为错误回给模型(不是静默忽略)。
func TestUpdateInvalidStatusReturnsError(t *testing.T) {
    _, tools := newTools(t)
    invoke(t, tools, ToolCreate, `{"subject":"查时间"}`)
    for _, bt := range tools {
        info, _ := bt.Info(context.Background())
        if info.Name != ToolUpdate {
            continue
        }
        _, err := bt.(tool.InvokableTool).InvokableRun(context.Background(), `{"taskId":"1","status":"doing"}`)
        if err == nil || !strings.Contains(err.Error(), "非法 status") {
            t.Fatalf("非法 status 应报错: %v", err)
        }
        return
    }
    t.Fatal("TaskUpdate 不存在")
}

// TestListFiltersDeleted 验证 TaskList 输出不含 deleted 任务。
func TestListFiltersDeleted(t *testing.T) {
    _, tools := newTools(t)
    invoke(t, tools, ToolCreate, `{"subject":"一"}`)
    invoke(t, tools, ToolCreate, `{"subject":"二"}`)
    invoke(t, tools, ToolUpdate, `{"taskId":"1","status":"deleted"}`)
    out := invoke(t, tools, ToolList, `{}`)
    if strings.Contains(out, "#1") || !strings.Contains(out, "#2 二") {
        t.Fatalf("List 应过滤 deleted:\n%s", out)
    }
}

// TestGetOutput 验证 TaskGet 输出含描述与状态。
func TestGetOutput(t *testing.T) {
    _, tools := newTools(t)
    invoke(t, tools, ToolCreate, `{"subject":"查时间","description":"调用时钟工具"}`)
    out := invoke(t, tools, ToolGet, `{"taskId":"1"}`)
    for _, want := range []string{"#1", "查时间", "调用时钟工具", "pending"} {
        if !strings.Contains(out, want) {
            t.Fatalf("Get 输出应含 %q:\n%s", want, out)
        }
    }
}

// TestUnknownTaskIDReturnsError 验证操作不存在的 id 报错。
func TestUnknownTaskIDReturnsError(t *testing.T) {
    _, tools := newTools(t)
    for _, name := range []string{ToolUpdate, ToolGet} {
        for _, bt := range tools {
            info, _ := bt.Info(context.Background())
            if info.Name != name {
                continue
            }
            if _, err := bt.(tool.InvokableTool).InvokableRun(context.Background(), `{"taskId":"99"}`); err == nil {
                t.Fatalf("%s 操作不存在的 id 应报错", name)
            }
        }
    }
}

// TestIsBoardTool 验证四个工具名被认出,其他名字不认。
func TestIsBoardTool(t *testing.T) {
    for _, name := range []string{ToolCreate, ToolUpdate, ToolList, ToolGet} {
        if !IsBoardTool(name) {
            t.Fatalf("%s 应被认作账本工具", name)
        }
    }
    if IsBoardTool("bash") || IsBoardTool("write_todos") {
        t.Fatal("非账本工具不应被认出")
    }
}

Run: go test ./internal/taskboard/ Expected: FAIL,编译错误 undefined: makeTools / ToolCreate / IsBoardTool

// 本文件:四个记账工具(TaskCreate/TaskUpdate/TaskList/TaskGet)与输出格式
// (操作回执 + 当前看板 + 催更块)。工具由 utils.InferTool 生成,最终实现
// tool.InvokableTool(github.com/cloudwego/eino/components/tool 包 interface.go:42,
// eino v0.9.21),对外用更宽的 tool.BaseTool(同文件 :32)承载。
//
// 约束写在 tool description(不是状态机),学 Claude Tasks;
// 催更块学 WeKnora 的 todo_write(internal/agent/tools/todo_write.go 的
// Important Reminder 注入)。
package taskboard

import (
    "context"
    "fmt"
    "strings"

    "github.com/cloudwego/eino/adk"
    "github.com/cloudwego/eino/components/tool"
    "github.com/cloudwego/eino/components/tool/utils"
)

// 四个工具名常量:middleware 注入、IsBoardTool 投影、测试共用一份事实来源。
const (
    ToolCreate = "TaskCreate"
    ToolUpdate = "TaskUpdate"
    ToolList   = "TaskList"
    ToolGet    = "TaskGet"
)

// IsBoardTool 判断工具名是不是四个记账工具之一。adkrun 的 printMessage 用它做看板投影。
func IsBoardTool(name string) bool {
    switch name {
    case ToolCreate, ToolUpdate, ToolList, ToolGet:
        return true
    }
    return false
}

// createArgs 是 TaskCreate 的参数。
type createArgs struct {
    Subject     string `json:"subject" jsonschema:"description=任务标题,一句话说清楚要做什么"`
    Description string `json:"description,omitempty" jsonschema:"description=补充细节(可选):为什么做、约束、验收线索"`
    ActiveForm  string `json:"activeForm,omitempty" jsonschema:"description=「正在做」的现在时短句(可选),看板 in_progress 时展示"`
}

// updateArgs 是 TaskUpdate 的参数;只传要改的字段,空串表示不动。
type updateArgs struct {
    TaskID      string `json:"taskId" jsonschema:"description=要更新的任务 id(TaskCreate 返回的 #N)"`
    Status      string `json:"status,omitempty" jsonschema:"description=新状态:pending / in_progress / completed /deleted"`
    Subject     string `json:"subject,omitempty" jsonschema:"description=新标题(可选)"`
    Description string `json:"description,omitempty" jsonschema:"description=新描述(可选)"`
    ActiveForm  string `json:"activeForm,omitempty" jsonschema:"description=新的「正在做」短句(可选)"`
}

// getArgs 是 TaskGet 的参数。
type getArgs struct {
    TaskID string `json:"taskId" jsonschema:"description=要读取的任务 id(#N)"`
}

// listArgs 是 TaskList 的占位参数(无参)。
type listArgs struct{}

// 工具描述即记账协议(约束写在这里,不靠状态机强挡)。
const (
    createDesc = `创建一条任务写进看板,返回 taskId。什么时候建表:请求需要 ≥3 步、或用户一次列了多件事时才建;一步能完成的请求不要建表。`
    updateDesc = `按 taskId 更新任务(只传要改的字段)。纪律:动手前先把对应任务标 in_progress(同时只保持一条);做完一项立刻标 completed,不要攒到最后一起勾——测试未通过、只做了一半、有未解决报错时不准标 completed;不要的任务标 deleted。卡住时改用 TaskCreate 建一条 blocker 任务说明卡点。`
    listDesc   = `列出看板上全部未删除任务(含状态),按创建顺序。`
    getDesc    = `按 taskId 读一条任务的完整信息(标题、描述、状态)。`
)

// makeTools 生成四个记账工具,操作同一份 store 正本。
// 每次变更后把全量快照写进 session(adk.AddSessionValue):
// interrupt 时镜像随 runContext gob 进 checkpoint(机制见 taskboard.go 的 SessionKey 注释);
// 无 session 的 ctx(单测直调)下镜像是静默空操作。
func makeTools(store *Store) ([]tool.BaseTool, error) {
    // mirror 把当前全量快照写进 session。
    mirror := func(ctx context.Context) {
        adk.AddSessionValue(ctx, SessionKey, store.Snapshot())
    }
    // withBoard 拼标准输出:回执 + 看板 + 催更块。
    withBoard := func(receipt string) string {
        list := store.List()
        return receipt + "\n\n" + board(list) + nudge(list)
    }

    create, err := utils.InferTool(ToolCreate, createDesc,
        func(ctx context.Context, args createArgs) (string, error) {
            t := store.Create(args.Subject, args.Description, args.ActiveForm)
            mirror(ctx)
            return withBoard(fmt.Sprintf("已创建任务 #%s「%s」", t.ID, t.Subject)), nil
        })
    if err != nil {
        return nil, err
    }
    update, err := utils.InferTool(ToolUpdate, updateDesc,
        func(ctx context.Context, args updateArgs) (string, error) {
            t, err := store.Update(args.TaskID, Patch{
                Subject: args.Subject, Description: args.Description,
                ActiveForm: args.ActiveForm, Status: args.Status,
            })
            if err != nil {
                return "", err
            }
            mirror(ctx)
            return withBoard(fmt.Sprintf("已更新任务 #%s(当前状态:%s)", t.ID, t.Status)), nil
        })
    if err != nil {
        return nil, err
    }
    list, err := utils.InferTool(ToolList, listDesc,
        func(ctx context.Context, _ listArgs) (string, error) {
            l := store.List()
            return board(l) + nudge(l), nil
        })
    if err != nil {
        return nil, err
    }
    get, err := utils.InferTool(ToolGet, getDesc,
        func(ctx context.Context, args getArgs) (string, error) {
            t, err := store.Get(args.TaskID)
            if err != nil {
                return "", err
            }
            receipt := fmt.Sprintf("#%s「%s」状态 %s", t.ID, t.Subject, t.Status)
            if t.Description != "" {
                receipt += "\n描述:" + t.Description
            }
            return withBoard(receipt), nil
        })
    if err != nil {
        return nil, err
    }
    return []tool.BaseTool{create, update, list, get}, nil
}

// statusIcon 给看板行的状态图标。
func statusIcon(s Status) string {
    switch s {
    case StatusCompleted:
        return "✅"
    case StatusInProgress:
        return "🔄"
    default:
        return "⏳"
    }
}

// board 渲染紧凑看板;空板返回占位行。
func board(tasks []Task) string {
    if len(tasks) == 0 {
        return "📋 任务看板(空)"
    }
    done := 0
    for _, t := range tasks {
        if t.Status == StatusCompleted {
            done++
        }
    }
    var b strings.Builder
    fmt.Fprintf(&b, "📋 任务看板(%d/%d 已完成)", done, len(tasks))
    for _, t := range tasks {
        subject := t.Subject
        if t.Status == StatusInProgress && t.ActiveForm != "" {
            subject = t.ActiveForm
        }
        fmt.Fprintf(&b, "\n  %s #%s %s", statusIcon(t.Status), t.ID, subject)
    }
    return b.String()
}

// nudge 是催更块:还有未完成项时追加在工具输出尾部;全部完成返回空串。
func nudge(tasks []Task) string {
    remaining := 0
    for _, t := range tasks {
        if t.Status == StatusPending || t.Status == StatusInProgress {
            remaining++
        }
    }
    if remaining == 0 {
        return ""
    }
    return fmt.Sprintf(`
⚠️ 还有 %d 项未完成。要求:
- 动手前先把要做的任务标成 in_progress(同时只保持一条);
- 做完一项立刻标 completed,不要攒到最后一起勾;
- 全部完成前不要输出最终总结。`, remaining)
}

Run: gofmt -w internal/taskboard/ && go test ./internal/taskboard/ Expected: PASS(Task 1 的 6 个 + 本任务 8 个)


Task 3: middleware 与 Instruction

Files:

// 本文件:middleware 的 BeforeAgent 注入测试——四个记账工具进 runCtx.Tools,
// 且不改动调用方原有的 runCtx(拷贝语义)。
package taskboard

import (
    "context"
    "testing"

    "github.com/cloudwego/eino/adk"
)

// TestBeforeAgentInjectsTools 验证 BeforeAgent 把四个记账工具追加进本轮工具表。
func TestBeforeAgentInjectsTools(t *testing.T) {
    mw, err := New(NewStore())
    if err != nil {
        t.Fatalf("New: %v", err)
    }
    runCtx := &adk.ChatModelAgentContext{}
    _, nRunCtx, err := mw.BeforeAgent(context.Background(), runCtx)
    if err != nil {
        t.Fatalf("BeforeAgent: %v", err)
    }
    if len(nRunCtx.Tools) != 4 {
        t.Fatalf("应注入 4 个工具,实际 %d", len(nRunCtx.Tools))
    }
    if len(runCtx.Tools) != 0 {
        t.Fatal("原 runCtx 不应被改动(拷贝语义)")
    }
}

// TestBeforeAgentNilRunCtx 验证 nil runCtx 原样返回,不炸。
func TestBeforeAgentNilRunCtx(t *testing.T) {
    mw, err := New(NewStore())
    if err != nil {
        t.Fatalf("New: %v", err)
    }
    _, nRunCtx, err := mw.BeforeAgent(context.Background(), nil)
    if err != nil || nRunCtx != nil {
        t.Fatalf("nil 进应 nil 出: %v %v", nRunCtx, err)
    }
}

Run: go test ./internal/taskboard/ Expected: FAIL,编译错误 undefined: New

// 本文件:taskboard 的 middleware——BeforeAgent 把四个记账工具注进 runCtx.Tools
// (eino plantask 同款机制,adk/middlewares/plantask/plantask.go 的 BeforeAgent),
// 并导出拼进系统提示词的记账约定(Instruction)。
package taskboard

import (
    "context"

    "github.com/cloudwego/eino/adk"
    "github.com/cloudwego/eino/components/tool"
)

// handler 是 taskboard 的 middleware 实现。store 是看板正本(跨 REPL 轮次存活),
// tools 是 New 时一次性生成的四个记账工具(操作同一份 store)。
//
// 实现接口:adk.ChatModelAgentMiddleware —— github.com/cloudwego/eino/adk 包
// handler.go:139 定义的 TypedChatModelAgentMiddleware[*schema.Message](eino v0.9.21;
// 第 259 行起别名 ChatModelAgentMiddleware)。内嵌 adk.BaseChatModelAgentMiddleware
// (同文件 :277)提供其余钩子的空实现,本类型覆盖 BeforeAgent。
type handler struct {
    adk.BaseChatModelAgentMiddleware
    store *Store
    tools []tool.BaseTool
}

// 编译期校验 handler 实现了 adk.ChatModelAgentMiddleware。
var _ adk.ChatModelAgentMiddleware = (*handler)(nil)

// New 创建 taskboard middleware;store 由调用方注入,
// 测试与驱动层可持有同一份正本(查询看板、断言状态)。
func New(store *Store) (adk.ChatModelAgentMiddleware, error) {
    tools, err := makeTools(store)
    if err != nil {
        return nil, err
    }
    return &handler{store: store, tools: tools}, nil
}

// BeforeAgent 实现 adk.ChatModelAgentMiddleware 的 BeforeAgent 钩子
// (github.com/cloudwego/eino/adk/handler.go 的 BeforeAgent):
// 把四个记账工具追加到本轮工具表;拷贝 runCtx 再改,不动调用方原值。
func (h *handler) BeforeAgent(ctx context.Context, runCtx *adk.ChatModelAgentContext) (context.Context, *adk.ChatModelAgentContext, error) {
    if runCtx == nil {
        return ctx, runCtx, nil
    }
    nRunCtx := *runCtx
    nRunCtx.Tools = append(nRunCtx.Tools, h.tools...)
    return ctx, &nRunCtx, nil
}

// Instruction 是拼进 agent 系统提示词的记账约定(cmd/yktako 把它接在
// config.SystemPrompt() 后面)。约束的工具级细则在各工具的 description 里,
// 这里只讲全局边界:什么时候建表、三层分离。
const Instruction = `任务看板约定:
- 请求需要 ≥3 步、或用户一次列了多件事时,先用 TaskCreate 建看板再动手;一步能完成的请求不要建表。
- 看板行用 taskId 寻址,用 TaskUpdate 改状态;纪律见 TaskUpdate 的工具描述。
- Plan(方案)与看板分离:需要时先口述方案给用户,看板文案不必逐行等于方案。
- 看板是你的施工记录,不是动作日志:一条任务下可以有任意多次工具调用,不要求一一对应。`

Run: go test ./internal/taskboard/ Expected: PASS(全部 16 个)


Task 4: adkrun 投影改造

Files:

internal/adkrun/turn_test.go 的文件头注释改为:

// 本文件:adkrun 的单元测试——Run 从 agent 自己取 root 名的那条路径(用假 agent,不打模型)。
// 账本工具回执的看板投影由 taskboard.IsBoardTool 判定,投影格式测试在 taskboard 包。
package adkrun

并整个删除 TestFormatTodoReceipt 函数(第 72-90 行)。

Run: go test ./internal/adkrun/ Expected: 编译通过、测试通过(删测试不破坏构建)——但 turn.go 还引用着已删测试所测的函数,此时 formatTodoReceipt 变成「有实现无测试」,下一步删实现。

三处改动:

① printMessage 的工具分支(第 171-184 行)改为:

    if mv.Role == schema.Tool || msg.Role == schema.Tool {
        // mv.Role == schema.Tool || msg.Role == schema.Tool:工具执行完返回的回执消息(Role=Tool),不带 ToolCalls,只有 Content → 打印 ← 🔧 结果: xxx。
        name := mv.ToolName
        if name == "" {
            name = msg.ToolName
        }
        if taskboard.IsBoardTool(name) {
            // 账本工具的回执自带看板与催更块(taskboard/tools.go 的 withBoard),
            // 原样投影,不走 Clip 截断——截断会把看板截烂。
            fmt.Printf("  📋 %s%s\n", prefix, msg.Content)
            return
        }
        fmt.Printf("  ← 🔧 %s%s: %s\n", prefix, name, repl.Clip(msg.Content, 120))
        return
    }

② 整个删除文件尾部的 writeTodosTool 常量与 formatTodoReceipt 函数(第 203-227 行)。

③ import 块:删 "encoding/json",加 "yk-tako-eino/internal/taskboard"。

Run: go test ./internal/adkrun/ && go vet ./internal/adkrun/ Expected: PASS + vet 无输出


Task 5: 集成测试(假模型走真实图)

Files:

说明:本文件用 package taskboard_test(外部测试包),这样既能用导出 API,又避免 「taskboard → adkrun → taskboard」的 import 环顾虑(实际未引 adkrun,checkpoint store 就地实现)。

// 本文件:taskboard 的集成测试——假模型走真实 ChatModelAgent + Runner 图:
// 建表→更新→完成全链路、session 镜像(probe 工具)、interrupt 时看板随 checkpoint 落盘。
// 外部测试包(taskboard_test):只用导出 API,假模型与探针都在本文件。
package taskboard_test

import (
    "bytes"
    "context"
    "encoding/gob"
    "fmt"
    "strings"
    "sync"
    "testing"

    "github.com/cloudwego/eino/adk"
    "github.com/cloudwego/eino/components/model"
    "github.com/cloudwego/eino/components/tool"
    "github.com/cloudwego/eino/components/tool/utils"
    "github.com/cloudwego/eino/compose"
    "github.com/cloudwego/eino/schema"
    "yk-tako-eino/internal/taskboard"
)

// init 注册测试 interrupt 的状态类型:checkpoint 是 gob 编码,
// 接口字段背后的具体类型必须注册(eino 注册 []byte 同款,adk/interrupt.go init)。
func init() {
    gob.Register("test-interrupt-state")
}

// scriptModel 是按剧本逐条吐消息的假模型:每次 Generate 弹出下一条预设消息。
//
// 实现接口:model.ToolCallingChatModel —— github.com/cloudwego/eino/components/model
// 包 interface.go:99(eino v0.9.21),覆盖 Generate / Stream / WithTools。
type scriptModel struct {
    mu      sync.Mutex
    replies []*schema.Message // 剧本:依次吐出的助手消息
}

// 编译期校验 scriptModel 实现了 model.ToolCallingChatModel。
var _ model.ToolCallingChatModel = (*scriptModel)(nil)

// Generate 实现 model.ToolCallingChatModel 的 Generate 方法:弹出剧本下一条。
func (s *scriptModel) Generate(_ context.Context, _ []*schema.Message, _ ...model.Option) (*schema.Message, error) {
    s.mu.Lock()
    defer s.mu.Unlock()
    if len(s.replies) == 0 {
        return nil, fmt.Errorf("剧本已用完")
    }
    msg := s.replies[0]
    s.replies = s.replies[1:]
    return msg, nil
}

// Stream 实现 model.ToolCallingChatModel 的 Stream 方法:用不上,测试只走 Generate。
func (s *scriptModel) Stream(context.Context, []*schema.Message, ...model.Option) (*schema.StreamReader[*schema.Message], error) {
    panic("not implemented")
}

// WithTools 实现 model.ToolCallingChatModel 的 WithTools 方法:返回自己,绑什么工具不影响剧本。
func (s *scriptModel) WithTools([]*schema.ToolInfo) (model.ToolCallingChatModel, error) {
    return s, nil
}

// toolCallMsg 造一条带单个工具调用的助手消息;id 保证工具回执可配对。
func toolCallMsg(id, name, args string) *schema.Message {
    return &schema.Message{
        Role: schema.Assistant,
        ToolCalls: []schema.ToolCall{{
            ID:       id,
            Function: schema.FunctionCall{Name: name, Arguments: args},
        }},
    }
}

// interruptMW 是测试专用 middleware:把 danger 工具调用暂停成 interrupt,
// 只为制造一次 checkpoint 落盘(生产上的 interrupt 来自 guard,这里不引 guard 保测试自包含)。
//
// 实现接口:adk.ChatModelAgentMiddleware —— github.com/cloudwego/eino/adk 包
// handler.go:139(eino v0.9.21;:259 起别名)。内嵌基类(同文件 :277),覆盖 WrapInvokableToolCall。
type interruptMW struct {
    adk.BaseChatModelAgentMiddleware
}

// 编译期校验 interruptMW 实现了 adk.ChatModelAgentMiddleware。
var _ adk.ChatModelAgentMiddleware = (*interruptMW)(nil)

// WrapInvokableToolCall 实现 adk.ChatModelAgentMiddleware 的 WrapInvokableToolCall 钩子
// (github.com/cloudwego/eino/adk/handler.go:193):danger 工具一律暂停,其余透传。
func (interruptMW) WrapInvokableToolCall(_ context.Context, endpoint adk.InvokableToolCallEndpoint, tCtx *adk.ToolContext) (adk.InvokableToolCallEndpoint, error) {
    return func(ctx context.Context, args string, opts ...tool.Option) (string, error) {
        if tCtx.Name == "danger" {
            return "", compose.StatefulInterrupt(ctx, "等审批", "test-interrupt-state")
        }
        return endpoint(ctx, args, opts...)
    }, nil
}

// cpStore 是内存 checkpoint,只为验证 interrupt 落盘字节。
//
// 实现接口:adk.CheckPointStore —— github.com/cloudwego/eino/compose 包 checkpoint.go:53
// 的同名别名(eino v0.9.21),覆盖 Get / Set。
type cpStore struct {
    m map[string][]byte
}

// 编译期校验 cpStore 实现了 adk.CheckPointStore。
var _ adk.CheckPointStore = (*cpStore)(nil)

// Get 实现 compose.CheckPointStore 的 Get 方法:读 checkpoint。
func (s *cpStore) Get(_ context.Context, key string) ([]byte, bool, error) {
    v, ok := s.m[key]
    return v, ok, nil
}

// Set 实现 compose.CheckPointStore 的 Set 方法:写 checkpoint。
func (s *cpStore) Set(_ context.Context, key string, value []byte) error {
    s.m[key] = value
    return nil
}

// emptyArgs 是无参测试工具的占位参数。
type emptyArgs struct{}

// newBoardAgent 建测试 agent:假模型 + 给定工具 + 给定 middleware 链。
func newBoardAgent(t *testing.T, m model.ToolCallingChatModel, tools []tool.BaseTool, mws ...adk.ChatModelAgentMiddleware) adk.Agent {
    t.Helper()
    agent, err := adk.NewChatModelAgent(context.Background(), &adk.ChatModelAgentConfig{
        Name:        "yk-tako",
        Description: "集成测试",
        Model:       m,
        ToolsConfig: adk.ToolsConfig{ToolsNodeConfig: compose.ToolsNodeConfig{Tools: tools}},
        Handlers:    mws,
        MaxIterations: 10,
    })
    if err != nil {
        t.Fatalf("建 agent: %v", err)
    }
    return agent
}

// drain 收完事件流,有错误事件立即失败。
func drain(t *testing.T, iter *adk.AsyncIterator[*adk.AgentEvent]) []*adk.AgentEvent {
    t.Helper()
    var events []*adk.AgentEvent
    for {
        ev, ok := iter.Next()
        if !ok {
            return events
        }
        if ev.Err != nil {
            t.Fatalf("事件流出错: %v", ev.Err)
        }
        events = append(events, ev)
    }
}

// TestBoardFlowEndToEnd 验证全链路:模型建表 → 标完成 → 收工,看板正本状态正确。
func TestBoardFlowEndToEnd(t *testing.T) {
    store := taskboard.NewStore()
    mw, err := taskboard.New(store)
    if err != nil {
        t.Fatalf("taskboard.New: %v", err)
    }
    m := &scriptModel{replies: []*schema.Message{
        toolCallMsg("c1", taskboard.ToolCreate, `{"subject":"查时间","activeForm":"查时间"}`),
        toolCallMsg("c2", taskboard.ToolUpdate, `{"taskId":"1","status":"completed"}`),
        schema.AssistantMessage("全部完成", nil),
    }}
    agent := newBoardAgent(t, m, nil, mw)
    runner := adk.NewRunner(context.Background(), adk.RunnerConfig{Agent: agent})

    events := drain(t, runner.Run(context.Background(), []*schema.Message{schema.UserMessage("先查时间再总结")}))

    task, err := store.Get("1")
    if err != nil || task.Status != taskboard.StatusCompleted {
        t.Fatalf("看板 #1 应 completed: %+v err=%v", task, err)
    }
    last := events[len(events)-1]
    msg, err := last.Output.MessageOutput.GetMessage()
    if err != nil || msg.Content != "全部完成" {
        t.Fatalf("最后事件应是最终答复: %+v err=%v", last, err)
    }
}

// TestSessionMirrorViaProbe 验证 TaskCreate 执行后 session 里就有看板镜像
// (probe 工具在执行时把 session 值抄进闭包)。
func TestSessionMirrorViaProbe(t *testing.T) {
    var captured map[string]any
    probe, err := utils.InferTool("probe_session", "测试探针:把当前 session 值抄到闭包",
        func(ctx context.Context, _ emptyArgs) (string, error) {
            captured = adk.GetSessionValues(ctx)
            return "ok", nil
        })
    if err != nil {
        t.Fatalf("建 probe: %v", err)
    }
    store := taskboard.NewStore()
    mw, err := taskboard.New(store)
    if err != nil {
        t.Fatalf("taskboard.New: %v", err)
    }
    m := &scriptModel{replies: []*schema.Message{
        toolCallMsg("c1", taskboard.ToolCreate, `{"subject":"查时间"}`),
        toolCallMsg("c2", "probe_session", `{}`),
        schema.AssistantMessage("完成", nil),
    }}
    agent := newBoardAgent(t, m, []tool.BaseTool{probe}, mw)
    runner := adk.NewRunner(context.Background(), adk.RunnerConfig{Agent: agent})
    drain(t, runner.Run(context.Background(), []*schema.Message{schema.UserMessage("干活")}))

    snap, ok := captured[taskboard.SessionKey].([]taskboard.Task)
    if !ok || len(snap) != 1 || snap[0].Subject != "查时间" {
        t.Fatalf("session 镜像应是 1 条「查时间」: %+v", captured[taskboard.SessionKey])
    }
}

// TestInterruptCheckpointCarriesBoard 验证 interrupt 时看板镜像随图状态落盘:
// checkpoint 字节里能直接找到任务主题(gob 线格式里字符串原样存放)。
func TestInterruptCheckpointCarriesBoard(t *testing.T) {
    danger, err := utils.InferTool("danger", "测试用:会被测试 middleware 暂停",
        func(context.Context, emptyArgs) (string, error) { return "不应执行到这里", nil })
    if err != nil {
        t.Fatalf("建 danger: %v", err)
    }
    store := taskboard.NewStore()
    mw, err := taskboard.New(store)
    if err != nil {
        t.Fatalf("taskboard.New: %v", err)
    }
    m := &scriptModel{replies: []*schema.Message{
        toolCallMsg("c1", taskboard.ToolCreate, `{"subject":"查时间"}`),
        toolCallMsg("c2", "danger", `{}`),
    }}
    agent := newBoardAgent(t, m, []tool.BaseTool{danger}, mw, &interruptMW{})
    cp := &cpStore{m: map[string][]byte{}}
    runner := adk.NewRunner(context.Background(), adk.RunnerConfig{Agent: agent, CheckPointStore: cp})

    events := drain(t, runner.Run(context.Background(), []*schema.Message{schema.UserMessage("干活")}, adk.WithCheckPointID("cp-1")))

    last := events[len(events)-1]
    if last.Action == nil || last.Action.Interrupted == nil {
        t.Fatalf("应以 interrupt 收尾: %+v", last)
    }
    data, ok, err := cp.Get(context.Background(), "cp-1")
    if err != nil || !ok {
        t.Fatalf("checkpoint 应已落盘: ok=%v err=%v", ok, err)
    }
    if !bytes.Contains(data, []byte("查时间")) {
        t.Fatalf("checkpoint 字节里应能找到任务主题(session 镜像随图落盘),字节长 %d", len(data))
    }
    // 顺带确认 drain 过程中事件流里出现过看板回执(投影的数据源)
    found := false
    for _, ev := range events {
        if ev.Output != nil && ev.Output.MessageOutput != nil {
            if msg, err := ev.Output.MessageOutput.GetMessage(); err == nil && msg != nil && strings.Contains(msg.Content, "📋 任务看板") {
                found = true
            }
        }
    }
    if !found {
        t.Fatal("事件流里应出现过看板回执")
    }
}

Run: go test -race ./internal/taskboard/ Expected: PASS(单元 16 个 + 集成 3 个)。常见失败点:gob 未注册某类型(按报错补 gob.Register);剧本条数不够(剧本已用完 → 检查模型循环次数)。


Task 6: cmd/yktako 唯一入口

Files:

// yk-tako 唯一入口:裸 ReAct + 任务看板(taskboard)+ L1 三件套守卫。
//
// 组装(doc/01 §5):ChatModelAgent 的 Handlers 链 = [taskboard] + guard 三件套;
// 看板正本在 taskboard middleware 里跨轮存活,镜像随 interrupt 落 checkpoint。
package main

import (
    "context"
    "fmt"
    "os"
    "strings"

    "github.com/cloudwego/eino/adk"
    "github.com/cloudwego/eino/compose"
    "github.com/cloudwego/eino/schema"
    "yk-tako-eino/internal/adkrun"
    "yk-tako-eino/internal/config"
    "yk-tako-eino/internal/guard"
    "yk-tako-eino/internal/repl"
    "yk-tako-eino/internal/taskboard"
    "yk-tako-eino/internal/tools"
)

// main 建模型、工具、看板与守卫,进 REPL 循环;审批走 interrupt 加 Resume。
func main() {
    ctx := context.Background()
    chatModel, ref := config.MustOpen(ctx)
    cwd, err := os.Getwd()
    if err != nil {
        repl.Exitf("%v", err)
    }
    bash, err := tools.Bash(ctx)
    if err != nil {
        repl.Exitf("bash: %v", err)
    }
    files, err := tools.Files(ctx)
    if err != nil {
        repl.Exitf("files: %v", err)
    }
    all := append(tools.MustBasic(ctx), bash)
    all = append(all, files...)

    // 看板:正本在 store(跨轮存活),middleware 注入四个记账工具。
    boardMW, err := taskboard.New(taskboard.NewStore())
    if err != nil {
        repl.Exitf("taskboard: %v", err)
    }

    engine := guard.NewEngine(guard.ModeApprove, nil)
    handlers := append([]adk.ChatModelAgentMiddleware{boardMW}, guard.Handlers(engine, guard.Options{WorkspaceRoot: cwd})...)
    agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
        Name:        config.AgentName(),
        Description: "带任务看板与工具安全层的工作伙伴",
        Instruction: config.SystemPrompt() + "\n\n" + taskboard.Instruction,
        Model:       chatModel,
        ToolsConfig: adk.ToolsConfig{
            // ExecuteSequentially:同批工具调用串行,「同批里先 Update 再干活」
            // 降低打架(秩序偏好,不是正确性保证,见 doc/01 §4)。
            ToolsNodeConfig: compose.ToolsNodeConfig{Tools: all, ExecuteSequentially: true},
        },
        Handlers:      handlers,
        MaxIterations: 20,
    })
    if err != nil {
        repl.Exitf("创建 agent: %v", err)
    }
    runner := adk.NewRunner(ctx, adk.RunnerConfig{
        Agent:           agent,
        EnableStreaming: false,
        CheckPointStore: adkrun.NewStore(),
    })

    console := repl.New()
    var history []*schema.Message
    turn := 0
    fmt.Printf("yk-tako。模型 %s。\n", ref)
    fmt.Printf("ToolGuard 模式: %s(/mode 可切换)。输入 quit 退出。\n\n", engine.Mode())
    for {
        input, ok := console.ReadLine("你: ")
        if !ok || input == "quit" || input == "exit" {
            break
        }
        if input == "" {
            continue
        }
        if mode, ok := strings.CutPrefix(input, "/mode "); ok {
            switch guard.Mode(strings.TrimSpace(mode)) {
            case guard.ModeBlock, guard.ModeWarn, guard.ModeApprove:
                engine.Configure(guard.Mode(strings.TrimSpace(mode)))
                fmt.Printf("ToolGuard 模式已切换为: %s\n\n", engine.Mode())
            default:
                fmt.Println("用法: /mode block|warn|require_approval")
            }
            continue
        }
        turn++
        messages := append(append([]*schema.Message{}, history...), schema.UserMessage(input))
        produced, err := adkrun.Run(ctx, runner, agent, fmt.Sprintf("turn-%d", turn), messages, func(info guard.ApprovalInfo) (string, error) {
            fmt.Println("\n⏸️  ═══════════════ 人工审批(interrupt)═══════════════")
            fmt.Printf("工具: %s   参数: %s\n", info.Tool, info.Args)
            if info.Message != "" {
                fmt.Println(info.Message)
            }
            answer, ok := console.ReadLine("批准执行?[y/N] ")
            if !ok {
                return guard.ResumeReject, nil
            }
            answer = strings.ToLower(answer)
            if answer == "y" || answer == "yes" {
                fmt.Println("✅ 已批准,继续执行")
                fmt.Println()
                return guard.ResumeApprove, nil
            }
            fmt.Println("🚫 已拒绝")
            fmt.Println()
            return guard.ResumeReject, nil
        })
        if err != nil {
            fmt.Println("出错了:", err)
            continue
        }
        history = append(history, schema.UserMessage(input))
        history = append(history, produced...)
    }
}

Run: go build ./cmd/yktako/ Expected: 无输出(编译通过)


Task 7: 删除旧入口与 internal/planexec

Files:

Run(在 yk-tako-eino/ 下):

rm -r cmd/l0raw cmd/l0react cmd/l0deep cmd/l1guard cmd/l2planexec internal/planexec

注意:internal/fsbackend 保留(用户明确点名保留,即使 l0deep 删除后暂无调用方,它仍独立编译)。

Run: go build ./... && go vet ./... && go test ./... Expected: 全部通过。若有对 planexec 的残留引用(不应有),按报错清理。


Task 8: 文档重写(README×2 + AGENTS.md)

Files:

# yk-tako

从 pi 式 agent 循环长出来的 AI 工作伙伴。目标是生长式复刻 [Octop](https://github.com/TencentCloud/Octop) 的核心能力:每层能力自己先写,卡住再对照参考实现。复刻是**功能翻译,不是设计移植**——参考实现只回答"要什么","怎么设计、怎么写"一律遵循 Eino 的架构思想和最佳实践;Eino 没有的类库(记忆、RAG、MCP、IM、沙箱等)参考 [WeKnora](https://github.com/Tencent/WeKnora) 的 Go 实现。

技术栈:**Go + [Eino](https://github.com/cloudwego/eino)**(字节 CloudWeGo)。主线代码在 `yk-tako-eino/`,**唯一入口 `cmd/yktako`**。

> 定案(2026-09-26):仓库从「分层学习对照」收敛为单入口产品形态。原 L0–L2 的五个对照入口(l0raw / l0react / l0deep / l1guard / l2planexec)与 planexec 硬编排已删除,能力折进唯一入口:裸 ReAct + 任务看板 + L1 三件套守卫。doc/ 旧文档(01–06 与《设计了解》)同时删除,新系列从《01-任务看板与单入口》重新开始。`maf/`(Microsoft Agent Framework 对照)保留为冻结存档,不再推进。

## 能力

- **任务看板**:`TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` 四个记账工具,Plan / Tasks / Actions 三层分离;看板正本跨轮存活,interrupt 时随 checkpoint 落盘(机制见 `doc/01`)。
- **工具安全**:命令守卫 / 文件守卫 / PII 脱敏三件套,三态判定(放行 / 硬拒 / 暂停问人),审批用 Eino 的 interrupt/resume;工作区外访问默认弹审批,对齐 Codex 的 workspace-write 提权模型。
- **厂商目录接模型**:OpenAI 兼容接口走 `eino-ext/openai`,Anthropic 走 `eino-ext/claude`,目录在 `yk-tako-eino/internal/config/provider-catalog.json`。

## 快速开始

需要 Go 1.25+。`.env` 已放在 `yk-tako-eino/`(配厂商 Key 和 `TAKO_MODEL`)。

```bash
cd yk-tako-eino
go run ./cmd/yktako   # 唯一入口
go test ./...         # 单元测试不打模型,不需要 API Key
```

详见 `yk-tako-eino/README.md`。

## 目录

```text
yk-tako-eino/   主线实现(Go + Eino),唯一入口 cmd/yktako
maf/            Microsoft Agent Framework(.NET)对照,冻结存档,见 maf/README.md
doc/            定案与实现记录(新系列 01–09,索引见 doc/01 §9)
```

## 参考

- Octop 源码(功能参照物,只取"要什么"):`/Users/yuweikang/dev/ykcode/ref-agent/Octop`
- harness 包源码(卡住时的参考答案):`/Users/yuweikang/dev/ykcode/harness-pkg/`
- WeKnora(Eino 缺失类库的 Go 参考实现):`/Users/yuweikang/dev/ykcode/ref-agent/WeKnora`
# yk-tako-eino

yk-tako 的主线实现(Go + Eino),**唯一入口 `cmd/yktako`**。模型按厂商目录接,OpenAI 兼容接口走 `eino-ext/openai`,Anthropic 走 `eino-ext/claude`。`.env` 就在本目录。

工作原则:复刻 Octop 是**功能翻译**——参考实现只回答"要什么",设计与实现一律按 Eino 的架构思想和最佳实践来(compose 管确定性、ADK 管自主性、prebuilt 优先、middleware 只做横切);Eino 没有的类库参考 WeKnora。

## 架构

```
cmd/yktako(唯一入口)
  └─ ChatModelAgent(裸 ReAct,MaxIterations 20)
       ├─ Instruction = config.SystemPrompt() + taskboard.Instruction(记账约定)
       ├─ Handlers = [taskboard] + guard 三件套(命令守卫 → 文件守卫 → PII)
       ├─ Tools = 时间 / 计算 / bash / 文件读写(internal/tools)
       └─ Runner(CheckPointStore = adkrun 内存实现) + REPL 审批回路
```

**任务看板**(`internal/taskboard`,机制详见 `../doc/01-任务看板与单入口.md`):

- 四个记账工具:`TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet`,约束写在 tool description(≥3 步才建表、动手前标 in_progress、做完立刻 completed、测试红不准 completed、卡住建 blocker)。
- 存储两层:middleware 自持 Store 是**正本**(跨 REPL 轮次存活);每次变更后 `adk.AddSessionValue` 写全量**镜像**,interrupt 时随 runContext gob 进 checkpoint——落盘不依赖模型自觉。
- 每个工具输出 = 回执 + 当前看板 + 催更块(有未完成项时);`ExecuteSequentially: true` 让同批调用串行。
- 不做:Action ↔ Task 双射、漏更新时自动勾行、图拓扑强制顺序(要硬进度需收窄执行模型,不在开放 ReAct 上做语义对齐)。

**工具安全**(`internal/guard`):三件套语义——命令守卫三模式(block / warn / require_approval,REPL 里 `/mode` 切换)、文件守卫三态(区外默认问人)、API Key 打码。挂载点是 ADK 的 `WrapInvokableToolCall`;审批用 `compose.StatefulInterrupt`,恢复用 `Runner.ResumeWithParams`,resume 值是 `"approve"` / `"reject"`。

## 快速开始

需要 Go 1.25+。在这个目录里:

```bash
go run ./cmd/yktako
```

`.env` 已经放好。改模型时改 `TAKO_MODEL`:`厂商/模型`,只配了一个厂商时可省略前缀;目录外厂商用 `TAKO_PROVIDER_<NAME>_API_KEY` / `_BASE_URL` / `_PROTOCOL`。

可以试:

```text
现在几点                                  # 一步任务:不建看板,直接回答
帮我查一下现在时间,算 1234*5678,再写个总结   # 多步任务:建看板 → 逐步执行 → 逐项勾掉
用 bash 执行 rm -rf /tmp/tako-test         # 命中守卫规则:弹人工审批
/mode block                              # 切换守卫模式
```

单元测试不打模型:

```bash
go test ./...
```

## 注释规范

硬性要求,细则见仓库根目录 [`AGENTS.md`](../../../AGENTS.md):

- 每个文件、每个 type / 方法 / 常量组都写中文注释;测试文件与假模型同样适用。
- 凡是实现或嵌入(继承)了接口,必须在类型注释和对应方法注释里写明**哪个包的哪个文件的哪个 interface**,嵌入的基类提供什么、覆盖了哪些钩子也要写(Eino 靠「接口 + 嵌入」组织代码,光看签名认不出钩子归属)。
- 实现接口的类型旁边加编译期断言 `var _ pkg.Interface = (*Type)(nil)`,并用中文注释说明校验对象。
- 行为改动必须同步改注释,禁止留过时注释。

示例可看 `internal/guard/middleware.go`(`adk.ChatModelAgentMiddleware` 的 `WrapInvokableToolCall` / `BeforeModelRewriteState` 钩子)、`internal/taskboard/middleware.go`(同接口的 `BeforeAgent` 钩子)与 `internal/fsbackend/backend.go`(`filesystem.Backend`)。

## 目录

```text
cmd/yktako         唯一入口:裸 ReAct + 任务看板 + L1 三件套
internal/config    厂商目录和模型工厂
internal/tools     时间、计算、bash、文件
internal/guard     命令守卫、文件守卫、PII、ADK middleware
internal/taskboard 任务看板:四个记账工具、Store 正本、session 镜像、middleware
internal/fsbackend 本地文件后端(filesystem.Backend 实现,暂无调用方,保留)
internal/repl      控制台输入 + Clip/Exitf 打印小工具
internal/adkrun    事件打印(含看板投影)、interrupt 审批回路、内存 checkpoint
```

① 「仓库结构」一节的 doc/ 行,把:

- `doc/`:立项、路线与调研记录;README 里的 TypeScript 路径是已删除实现的历史对照。

改为:

- `doc/`:定案与实现记录。2026-09-26 起新系列(旧 01–06 已随单入口收敛删除)。

② 「接口实现 / 继承必须标清楚」一节末尾以 planexec 举例的句子,把:

标准库接口同样标注,例如 `internal/planexec/gate.go` 的 `Plan` 同时实现了
`planexecute.Plan` 与 `encoding/json` 的 `Marshaler` / `Unmarshaler`。
经 `utils.InferTool` 生成的工具,也要在函数注释里注明它最终实现
`tool.InvokableTool`(`components/tool/interface.go:42`)。

改为:

标准库接口同样标注(例如某类型实现 `encoding/json` 的 `Marshaler` 时,在方法注释里写明)。
经 `utils.InferTool` 生成的工具,也要在函数注释里注明它最终实现
`tool.InvokableTool`(`components/tool/interface.go:42`),示例见 `internal/taskboard/tools.go`。

Run: gofmt -l . && go build ./... && go vet ./... && go test ./... Expected: gofmt 无输出;build/vet 无输出;test 全 PASS


附:任务-规格对照(自审用)

doc/01 规格条目 落点
§2 四工具 + 状态值 + 约束在 description Task 2
§2 输出 = 回执 + 看板 + 催更 Task 2(withBoard/board/nudge)
§3 Store 正本 + session 镜像 + gob 注册 Task 1(Store/init)、Task 2(mirror)、Task 5(probe + checkpoint 断言)
§3 mutex 防并行写坏 Task 1(Store 方法全加锁 + 并发测试)
§4 流式投影 Task 4(adkrun + IsBoardTool)
§4 ExecuteSequentially Task 6
§5 middleware BeforeAgent 注入 + Instruction Task 3、Task 6
§5 删除清单 Task 7
§7 测试计划 Task 1/2/3/5
文档(README/AGENTS.md) Task 8

附:计划外补充——doc 新系列重写(2026-09-26)

本计划定稿后,owner 追加了一项要求:把随定案删除的旧文档(01–06 +《设计了解》)按新方向重写进新系列, 先于代码任务完成。执行记录与结果:

新篇 来源 处理
03-立项与命名 旧《01-项目立项讨论》 抹掉被推翻的中间状态;路径改现状(ref-agent/Octop、ref-agent/WeKnora);补"为什么回到 Eino"的指针
04-技术路线 旧《02-技术路线讨论》 保留 T-Mem 两期方案、LangGraph.js vs Eino 对比与 LangGraph→Eino 映射表;两次反转压成"反转记"
05-Octop架构剖析与生长式复刻 旧《03-架构剖析与移植Plan》 壳/芯分层与组件清单照旧;"L0–L8 学习阶梯"改成产品能力路线(9 项,标注状态)
06-工具安全层 旧《04-L1-工具安全层》 机制分析、溯源纠错、踩坑、实测保留;入口改 cmd/yktako;删 TS 时代残句;规则表/单测现状按代码重写
07-任务规划与看板 旧《05-L2-任务规划》 问题与参考实现照旧;结论换成"三层分离 + 看板";两条旧软约束线 + 硬编排线记为退场
08-Eino规划机制调研 旧《06-Eino规划机制调研与路线定案》 三套机制对照与"Graph 管确定性"结论全保留;planexec / Gate 段落改决策记录
09-设计了解 旧《设计了解》 机制笔记保留并刷新锚点;新增 BeforeAgent 注入、session 值随 checkpoint 落盘两节

配套两处小改:doc/01 补 §9 系列索引(写作约定:决策篇记"为什么"、能力篇记"是什么 + 落点"、 机制篇记"框架怎么运作";被删实现注明退场原因);本文件 Task 8 的 README 片段顺带修正过时路径 (Octop 在 ref-agent/Octop)与 doc/ 目录说明。

注意:Task 8(README×2 + AGENTS.md)仍待做——它属于代码侧收敛的收尾,等 Task 2–7 落地后再执行, 届时文档口径以新系列 03–09 为准。