Index 05: TodoWrite — 让智能体先计划后执行

> 帮我给 UserService.kt 加上日志，并修复 getUserById 的 NPE

[Agent 调用 todo_write 创建 3 项待办]
Todo list updated (0/3 completed, 1 in progress, 2 pending):
  1. [~] Read UserService.kt
  2. [ ] Add logging to all public methods
  3. [ ] Fix NPE in getUserById

[Agent 调用 read_file]
[Agent 调用 todo_write 更新：第 1 项完成，第 2 项 in_progress]
Todo list updated (1/3 completed, 1 in progress, 1 pending):
  1. [x] Read UserService.kt
  2. [~] Add logging to all public methods
  3. [ ] Fix NPE in getUserById

                    用户输入 "帮我重构 X"
                              │
                              ▼
                    ┌──────────────────┐
                    │   AgentLoop      │
                    │  messagesHistory │
                    └──┬─────────────┘
                       │ LLM 决定调用 todo_write
                       ▼
            ┌──────────────────────────────────┐
            │   executeOneTool (s02-s04 链路)    │
            │                                    │
            │  ① Permission (s03) ──── 放行     │
            │  ② PreToolUse Hook (s04) ─ 放行    │
            │  ③ TodoWriteTool.execute          │
            │       │                            │
            │       ▼                            │
            │     TodoStore.replaceAll(items)   │
            │       │                            │
            │       ▼                            │
            │     返回状态概览文本                │
            │  ④ PostToolUse Hook (s04) ─ 透传   │
            └──────────────────────────────────┘
                       │
                       ▼
            tool_result 进入 messagesHistory
            LLM 下一轮能看到当前 todo 状态

data class TodoItem(
    val content: String,
    val status: TodoStatus = TodoStatus.PENDING
)

enum class TodoStatus { PENDING, IN_PROGRESS, COMPLETED }

object TodoStore {
    private val items: CopyOnWriteArrayList<TodoItem> = CopyOnWriteArrayList()

    fun replaceAll(newItems: List<TodoItem>) {
        items.clear()
        items.addAll(newItems)
    }

    fun getAll(): List<TodoItem> = items.toList()  // 快照副本
    fun clear() { items.clear() }
    fun inProgressCount(): Int = items.count { it.status == TodoStatus.IN_PROGRESS }
    fun completedCount(): Int = items.count { it.status == TodoStatus.COMPLETED }
    fun size(): Int = items.size
}

"getAll returns a snapshot copy that external mutation cannot affect" {
    TodoStore.replaceAll(listOf(TodoItem("Original", TodoStatus.PENDING)))
    val snapshot = TodoStore.getAll()
    // 尝试修改快照——toList() 返回不可变 List，add 抛 UnsupportedOperationException
    (snapshot as? MutableList<TodoItem>)?.add(TodoItem("Hijacked", TodoStatus.COMPLETED))

    TodoStore.size() shouldBe 1  // 内部状态不变
    TodoStore.getAll()[0].content shouldBe "Original"
}

class TodoWriteTool : Tool {
    override val name = "todo_write"
    override val description = "Update the todo list (plan before executing, track progress)"
    override val isReadOnly = false  // 修改内存状态，串行执行
    override val jsonSchema: JsonObject = ...
    override suspend fun execute(input: JsonObject): ToolResult
}

{
  "name": "todo_write",
  "description": "Use this tool to create and update a todo list ...",
  "input_schema": {
    "type": "object",
    "properties": {
      "todos": {
        "type": "array",
        "description": "Complete list of todos (replaces existing list)",
        "items": {
          "type": "object",
          "properties": {
            "content": { "type": "string" },
            "status": {
              "type": "string",
              "enum": ["pending", "in_progress", "completed"]
            }
          },
          "required": ["content", "status"]
        }
      }
    },
    "required": ["todos"]
  }
}

override suspend fun execute(input: JsonObject): ToolResult {
    // 1. 取 todos 数组（runCatching 防御类型不匹配）
    val todosArray = ...
        ?: return ToolResult("", "Error: todos is required and must be an array", isError = true)

    // 2. 逐项解析并校验——错误消息带 todos[$index] 位置
    val parsed = mutableListOf<TodoItem>()
    for ((index, element) in todosArray.withIndex()) {
        val obj = runCatching { element.jsonObject }.getOrNull()
            ?: return ToolResult("", "Error: todos[$index] must be an object", isError = true)

        val content = runCatching { obj["content"]?.jsonPrimitive?.content }.getOrNull()
            ?: return ToolResult("", "Error: todos[$index].content is required and must be a string", isError = true)

        val statusStr = runCatching { obj["status"]?.jsonPrimitive?.content }.getOrNull()
            ?: return ToolResult("", "Error: todos[$index].status is required and must be a string", isError = true)

        val status = parseStatus(statusStr)
            ?: return ToolResult("", "Error: todos[$index].status '$statusStr' is invalid; must be one of: pending, in_progress, completed", isError = true)

        parsed.add(TodoItem(content = content, status = status))
    }

    // 3. 整体替换存储
    TodoStore.replaceAll(parsed)

    // 4. 返回状态概览文本
    return ToolResult("", buildSummary(parsed))
}

Todo list updated (1/3 completed, 1 in progress, 1 pending):
  1. [x] Read UserService.kt
  2. [~] Add logging to all public methods
  3. [ ] Fix NPE in getUserById

// 1. 注册工具（start() 内）
ToolRegistry.register(ReadFileTool())
ToolRegistry.register(WriteFileTool())
ToolRegistry.register(BashTool())
ToolRegistry.register(TodoWriteTool())  // 新增

// 2. /clear 命令清空 TodoStore
CMD_CLEAR, CMD_C -> {
    agentLoop.messagesHistory.clear()
    approvalStore.clear()
    TodoStore.clear()  // 新增
    logger.info {"Conversation history, permission memory, and todo list cleared"}
    println("Conversation history, permission memory, and todo list cleared.")
    true
}

// 3. 欢迎语
println("🐱 Cat-Code — Index 05: TodoWrite")

replaceAll stores given items                                  ✓
replaceAll with empty list clears existing items               ✓
replaceAll is idempotent when called twice with same input     ✓
replaceAll overwrites previous items completely                ✓
getAll returns empty list by default                           ✓
getAll returns a snapshot copy that external mutation cannot affect ✓
clear empties all items                                        ✓
clear on empty store is no-op                                  ✓
inProgressCount returns count of IN_PROGRESS items             ✓
completedCount returns count of COMPLETED items                ✓
size returns total count                                       ✓
replaceAll is thread-safe under concurrent writes             ✓

"replaceAll is thread-safe under concurrent writes" {
    runBlocking {
        coroutineScope {
            (1..50).map { i ->
                async {
                    TodoStore.replaceAll(listOf(TodoItem("item-$i", TodoStatus.COMPLETED)))
                }
            }.awaitAll()
        }
    }
    TodoStore.size() shouldBe 1  // 最终是某次完整写入的结果
    TodoStore.getAll()[0].content shouldStartWith "item-"
}

execute replaces todo store with given items                   ✓
execute returns summary containing status overview             ✓
execute with empty todos array clears the store                ✓
execute returns error when todos is missing                   ✓
execute returns error when todos is not an array               ✓
execute returns error when todo item is not an object          ✓
execute returns error when content is missing                  ✓
execute returns error when status is missing                   ✓
execute returns error when status value is invalid            ✓
execute accepts status case-insensitively                      ✓
execute replaces previous list completely                     ✓
execute reports error index correctly for second item          ✓

run updates TodoStore when LLM calls todo_write                ✓
run passes todo_write tool definition to LLM                  ✓
run does not modify TodoStore when tool execution is blocked  ✓

afterTest {
    ToolRegistry.clear()
    TodoStore.clear()  // 新增
}

// ❌ 类型不匹配时抛异常
val todosArray = input["todos"]?.jsonArray

// ✅ runCatching 防御
val todosElement = input["todos"]
val todosArray = when {
    todosElement == null -> null
    else -> runCatching { todosElement.jsonArray }.getOrNull()
}

@Suppress("UNCHECKED_CAST")
(snapshot as? MutableList<TodoItem>)?.add(TodoItem("Hijacked", TodoStatus.COMPLETED))

class TodoWriteTool(private val store: TodoStore = TodoStore) : Tool { ... }

return ToolResult("", "Error: status is required", isError = true)

return ToolResult("", "Error: todos[$index].status is required and must be a string", isError = true)

// ❌ 三个问题
onPostToolUse = { tc, result ->
    val finalResult = hookManager.firePostToolUse(tc, result)
    if (tc.name == "todo_write" && !finalResult.isError) {  // ① 字符串硬编码
        println()                                            // ② 硬编码 println
        println(finalResult.content)
        println()
    }
    finalResult
}

// ✅ 优雅版本
class TodoDisplayHook(
    private val output: (String) -> Unit = { msg -> println(msg) }  // 注入便于测试
) {
    fun registerTo(manager: HookManager) {
        val handler: HookHandler = handler@{ event ->
            if (event.toolCall.name != TodoWriteTool.NAME) {  // 引用常量
                return@handler HookResult.Continue
            }
            // ...输出概览...
            HookResult.Continue  // 不替换 result
        }
        manager.on(HookEvent.Type.POST_TOOL_USE, handler)
    }
}

// ReplLoop 只需一行注册
TodoDisplayHook().registerTo(hookManager)

src/main/kotlin/com/sepcai/code/
├── todo/                              # [新建] 待办领域模型包
│   ├── TodoItem.kt                    # data class + TodoStatus 枚举
│   ├── TodoStore.kt                   # 全局单例存储（CopyOnWriteArrayList）
│   └── TodoDisplayHook.kt             # [新建] PostToolUse hook，todo_write 后镜像输出到 stdout
├── tool/
│   └── tools/
│       └── TodoWriteTool.kt           # [新建] 实现 Tool 接口的 todo_write 工具（+NAME 常量）
└── repl/
    └── ReplLoop.kt                    # [修改] 注册工具 + TodoDisplayHook + /clear 清空 + 欢迎语

src/test/kotlin/com/sepcai/code/
├── todo/                              # [新建]
│   ├── TodoStoreTest.kt               # 12 个用例
│   └── TodoDisplayHookTest.kt         # [新建] 6 个用例（输出/错误过滤/工具过滤/Continue）
├── tool/
│   └── TodoWriteToolTest.kt           # [新建] 12 个用例
└── agent/
    └── AgentLoopTest.kt               # [修改] +3 个集成测试，afterTest 加 TodoStore.clear()