Index 06: Subagent — 异步后台子智能体

> 帮我重构 UserService.kt 和 OrderService.kt 两个文件

[主智能体调用 task 派发任务 1: 重构 UserService]
Task dispatched: task_a1b2c3...
Use query_task to check status.

[主智能体调用 task 派发任务 2: 重构 OrderService]
Task dispatched: task_d4e5f6...
Use query_task to check status.

[主智能体调用 query_task 查询任务 1]
Task task_a1b2c3 COMPLETED.

Result:
UserService.kt 已重构：抽取了 validateUserId...

[主智能体调用 query_task 查询任务 2]
Task task_d4e5f6 COMPLETED.

Result:
OrderService.kt 已重构：抽取了 validateOrderId...

                用户输入 "重构 UserService 和 OrderService"
                              │
                              ▼
                    ┌──────────────────┐
                    │   主 AgentLoop   │
                    │  messagesHistory │
                    └──┬─────────────┘
                       │ LLM 调用 task 工具
                       ▼
            ┌──────────────────────────────────┐
            │   TaskTool.execute (写工具)        │
            │                                    │
            │  ① Permission (s03) ──── 放行     │
            │  ② PreToolUse Hook (s04) ─ 放行    │
            │  ③ SubagentStore.createRecord     │
            │     + markRunning (PENDING→RUNNING)│
            │  ④ scope.launch {                  │
            │       subagent.run()  ← 后台协程    │
            │     }                              │
            │  ⑤ 返回 "Task dispatched: task_xxx"│
            │  ⑥ PostToolUse Hook (s04) ─ 透传   │
            └──────────────────────────────────┘
                       │
                       ▼ tool_result 进入主 AgentLoop.messagesHistory
                       │
                       ▼ 主智能体继续推理（可能再次 task 或 query_task）
                       │
                       ▼ ...后续轮询 query_task 拿到 COMPLETED + finalText

// 改造前（s02-s05）
object ToolRegistry {
    private val tools = mutableMapOf<String, Tool>()
    fun register(tool: Tool) { tools[tool.name] = tool }
    fun get(name: String): Tool = tools[name] ?: throw UnknownToolException(name)
    // ...
}

// 改造后（s06）
class ToolRegistry {
    private val tools = mutableMapOf<String, Tool>()
    fun register(tool: Tool) { tools[tool.name] = tool }
    fun get(name: String): Tool = tools[name] ?: throw UnknownToolException(name)
    // ...签名完全不变
}

class AgentLoop(
    private val llmProvider: LLMProvider,
    private val systemPrompt: String,
    private val config: AgentConfig = AgentConfig(),
    private val hooks: AgentLoopHooks = AgentLoopHooks(),
    private val toolRegistry: ToolRegistry = ToolRegistry()  // 新增，默认值保向后兼容
)

// 改造前
class ToolCategoryRule : PermissionRule {
    override suspend fun evaluate(toolCall: ToolCall): PermissionResult {
        val isReadOnly = try {
            ToolRegistry.get(toolCall.name).isReadOnly  // ← 隐藏耦合
        } catch (_: UnknownToolException) {
            return PermissionResult.ASK
        }
        return if (isReadOnly) PermissionResult.ALLOW else PermissionResult.ASK
    }
}

// 改造后
class ToolCategoryRule(private val registry: ToolRegistry) : PermissionRule {
    override suspend fun evaluate(toolCall: ToolCall): PermissionResult {
        val isReadOnly = try {
            registry.get(toolCall.name).isReadOnly  // 注入实例
        } catch (_: UnknownToolException) {
            return PermissionResult.ASK
        }
        return if (isReadOnly) PermissionResult.ALLOW else PermissionResult.ASK
    }
}

// 改造前
TodoStore.replaceAll(parsed)
logger.info { "Todo list updated: ${TodoStore.completedCount()}/${TodoStore.size()} done" }

// 改造后
store.replaceAll(parsed)
logger.info {
    "Todo list updated: ${parsed.count { it.status == TodoStatus.COMPLETED }}/${parsed.size} done"
}

// 改造前
beforeTest { ToolRegistry.clear() }
"register adds tool" {
    val registry = ToolRegistry  // 误把 object 当类型
    registry.register(FakeEchoTool())
}

// 改造后
"register adds tool" {
    val registry = ToolRegistry()  // 局部实例
    registry.register(FakeEchoTool())
}

enum class SubagentStatus { PENDING, RUNNING, COMPLETED, FAILED }

PENDING → RUNNING → { COMPLETED | FAILED }

data class SubagentRecord(
    val id: String,              // "task_${UUID}"
    val description: String,     // 简短描述
    val prompt: String,          // 任务正文
    val status: SubagentStatus,
    val finalText: String? = null,    // COMPLETED 时填充
    val error: String? = null,        // FAILED 时填充
    val createdAt: Long,
    val completedAt: Long? = null
)

class Subagent(
    private val loop: AgentLoop,
    val description: String,
    private val prompt: String
) {
    suspend fun run(): String = loop.run(prompt)
}

class SubagentFactory(
    private val llmProvider: LLMProvider,
    private val config: AgentConfig
) {
    fun create(description: String, prompt: String): Subagent {
        val todoStore = TodoStore()                         // 独立 todo
        val toolRegistry = ToolRegistry().apply {
            register(ReadFileTool())
            register(WriteFileTool())
            register(BashTool())
            register(TodoWriteTool(todoStore))
            // 不注册 Task/QueryTask——禁止递归派发孙智能体
        }
        val hookManager = HookManager().apply {
            LoggingHook().registerTo(this)
            // 不注册 TimingHook/TodoDisplayHook——避免干扰主 REPL 输出
        }
        val loop = AgentLoop(
            llmProvider = llmProvider,
            systemPrompt = SubagentPrompts.DEFAULT,
            config = config,
            hooks = AgentLoopHooks(
                onPreToolUse = { tc -> hookManager.firePreToolUse(tc) },
                onPostToolUse = { tc, result -> hookManager.firePostToolUse(tc, result) }
            ),
            toolRegistry = toolRegistry
        )
        return Subagent(loop, description, prompt)
    }
}

class SubagentStore {
    private val records = ConcurrentHashMap<String, SubagentRecord>()
    private val runningCount = AtomicInteger(0)

    fun createRecord(description: String, prompt: String): String { /* 生成 task_id + PENDING */ }
    fun markRunning(id: String) { /* PENDING→RUNNING，count++ */ }
    fun markCompleted(id: String, finalText: String) { /* RUNNING→COMPLETED，count-- */ }
    fun markFailed(id: String, error: String) { /* RUNNING→FAILED，count-- */ }
    fun get(id: String): SubagentRecord? = records[id]
    fun runningCount(): Int = runningCount.get()
    fun clear() { records.clear(); runningCount.set(0) }
}

fun markRunning(id: String) {
    records.computeIfPresent(id) { _, record ->
        if (record.status == SubagentStatus.PENDING) {
            runningCount.incrementAndGet()
            record.copy(status = SubagentStatus.RUNNING)
        } else {
            record // 状态不符，保持原样
        }
    }
}

class TaskTool(
    private val factory: SubagentFactory,
    private val store: SubagentStore,
    private val scope: CoroutineScope,
    private val maxConcurrent: Int
) : Tool {
    override val name = "task"
    override val isReadOnly = false  // 副作用：创建协程；串行执行避免并发竞态

    override suspend fun execute(input: JsonObject): ToolResult {
        val description = input["description"]?.jsonPrimitive?.content
            ?: return ToolResult("", "Error: description is required", isError = true)
        val prompt = input["prompt"]?.jsonPrimitive?.content
            ?: return ToolResult("", "Error: prompt is required", isError = true)

        if (store.runningCount() >= maxConcurrent) {
            return ToolResult("", "Error: max concurrent subagents ($maxConcurrent) reached", isError = true)
        }

        val taskId = store.createRecord(description, prompt)
        store.markRunning(taskId)

        scope.launch {
            try {
                val subagent = factory.create(description, prompt)
                val finalText = subagent.run()
                store.markCompleted(taskId, finalText)
            } catch (e: CancellationException) {
                throw e  // 重新抛出，遵守结构化并发
            } catch (e: Exception) {
                store.markFailed(taskId, e.message ?: "Unknown error")
            }
        }

        return ToolResult("", "Task dispatched: $taskId\nUse query_task to check status.")
    }
}

class QueryTaskTool(private val store: SubagentStore) : Tool {
    override val name = "query_task"
    override val isReadOnly = true  // 读操作，可并发查询

    override suspend fun execute(input: JsonObject): ToolResult {
        val taskId = input["task_id"]?.jsonPrimitive?.content
            ?: return ToolResult("", "Error: task_id is required", isError = true)

        val record = store.get(taskId)
            ?: return ToolResult("", "Error: task not found: $taskId", isError = true)

        val content = when (record.status) {
            SubagentStatus.PENDING -> "Task $taskId is PENDING (not yet started)."
            SubagentStatus.RUNNING -> "Task $taskId is RUNNING. Try again later."
            SubagentStatus.COMPLETED -> "Task $taskId COMPLETED.\n\nResult:\n${record.finalText ?: ""}"
            SubagentStatus.FAILED -> "Task $taskId FAILED.\n\nError:\n${record.error ?: "Unknown error"}"
        }
        return ToolResult("", content, isError = record.status == SubagentStatus.FAILED)
    }
}

tool.tools → subagent → agent, tool

subagent → agent, llm, tool      ✓ 单向

class ReplLoop(...) {
    private lateinit var subagentScope: CoroutineScope
    private lateinit var subagentStore: SubagentStore
    // ...

    fun start() {
        subagentScope = CoroutineScope(SupervisorJob() + Dispatchers.Default)

        // ...组装工具、权限、hooks、AgentLoop...

        printWelcome()
        try {
            while (true) {
                // REPL 主循环
            }
        } finally {
            subagentScope.cancel()  // 结构化并发：退出时取消所有子智能体
        }
        printGoodbye()
    }
}

CMD_CLEAR, CMD_C -> {
    agentLoop.messagesHistory.clear()
    approvalStore.clear()
    todoStore.clear()
    subagentStore.clear()  // 新增：清空对话也清空任务列表
    true
}

src/main/kotlin/com/sepcai/code/
├── subagent/                          # [新建] 子智能体领域包
│   ├── SubagentStatus.kt              # 状态枚举：PENDING/RUNNING/COMPLETED/FAILED
│   ├── SubagentRecord.kt              # 不可变任务记录 data class
│   ├── SubagentPrompts.kt             # 子智能体默认 systemPrompt
│   ├── Subagent.kt                    # 包装独立 AgentLoop
│   ├── SubagentFactory.kt             # 工厂：组装隔离依赖图
│   ├── SubagentStore.kt               # ConcurrentHashMap + AtomicInteger 状态存储
│   ├── TaskTool.kt                    # 派发工具（isReadOnly=false）
│   └── QueryTaskTool.kt               # 查询工具（isReadOnly=true）
├── agent/
│   ├── AgentConfig.kt                 # [修改] +maxConcurrentSubagents 字段
│   └── AgentLoop.kt                   # [修改] +toolRegistry 构造参数 + 3 处引用点
├── tool/
│   ├── ToolRegistry.kt                # [修改] object → class
│   └── tools/
│       └── TodoWriteTool.kt           # [修改] +store 构造参数 + 消掉日志耦合
├── todo/
│   └── TodoStore.kt                   # [修改] object → class
├── permission/rules/
│   └── ToolCategoryRule.kt            # [修改] +registry 构造参数
└── repl/
    └── ReplLoop.kt                    # [修改] +CoroutineScope + Task/QueryTask 注册 + try/finally

src/test/kotlin/com/sepcai/code/
├── subagent/                          # [新建]
│   ├── SubagentFactoryTest.kt         # 5 个用例（隔离性、工具集、run 返回值）
│   ├── SubagentStoreTest.kt           # 9 个用例（状态机、并发安全）
│   ├── TaskToolTest.kt                # 5 个用例（派发、并发上限、参数校验）
│   └── QueryTaskToolTest.kt           # 6 个用例（四种状态、未知名、缺参数）
├── tool/
│   ├── ToolRegistryTest.kt            # [修改] 删 beforeTest，每用例局部实例
│   └── TodoWriteToolTest.kt           # [修改] 删 before/afterTest，每用例注入 store
├── todo/
│   └── TodoStoreTest.kt               # [修改] 删 before/afterTest，每用例局部实例
├── permission/rules/
│   └── ToolCategoryRuleTest.kt        # [修改] 删 clear，每用例注入 registry
└── agent/
    └── AgentLoopTest.kt               # [修改] 删 afterTest，每用例注入 registry + 2 个集成测试