Index 07: Skill Loading — 按需注入式技能系统

.cat-code/skills/figma-to-code/SKILL.md
---
name: figma-to-code
description: Translate Figma designs into production code. Use when the user references a Figma URL or node ID.
---
# Figma to Code Workflow
1. Fetch design via the Figma MCP server
2. Extract design tokens...

🐱 Cat-Code — Index 07: Skill Loading (1 skills loaded)
Type /help for commands, /exit to quit.

# Available Skills

The following skills are available. Call the `load_skill` tool with the skill's name to retrieve its full instructions, then follow them.

## figma-to-code
Translate Figma designs into production code. Use when the user references a Figma URL or node ID.

                用户输入 "把这个 Figma 链接转成代码"
                              │
                              ▼
                    ┌──────────────────┐
                    │   主 AgentLoop   │
                    │  messagesHistory │
                    └──┬─────────────┘
                       │ buildRequestMessages() → [SYSTEM, USER, ...]
                       ▼
            ┌──────────────────────────────────┐
            │  s07: onPreLlmRequest hook       │
            │                                    │
            │  HookManager.firePreLlmRequest    │
            │   ↓ 遍历 PRE_LLM_REQUEST handlers │
            │  SkillInjectionHook               │
            │   → 读 SkillStore.getAll()         │
            │   → 拼 "# Available Skills..."    │
            │   → AppendMessages([SYSTEM(msg)])│
            └──────────────────────────────────┘
                       │
                       ▼ requestMessages = baseMessages + appended
                       │
                       ▼ LLM 看到 skill metadata，判断该不该用 figma-to-code
                       │
                       ▼ （s08 才注入 body；s07 LLM 只看到 name+description）

data class HookEvent(
    val type: HookEvent.Type,
    val toolCall: ToolCall = ToolCall(id = "", name = "", input = buildJsonObject {}),
    val result: ToolResult? = null,
    val messages: List<Message> = emptyList()  // 仅 PRE_LLM_REQUEST 时非空
) {
    enum class Type {
        PRE_TOOL_USE,
        POST_TOOL_USE,
        PRE_LLM_REQUEST
    }
}

sealed class HookResult {
    object Continue : HookResult()
    data class Block(val reason: String) : HookResult()
    data class Replace(val result: ToolResult) : HookResult()
    data class AppendMessages(val messages: List<Message>) : HookResult()  // 新增
}

suspend fun firePreLlmRequest(messages: List<Message>): List<Message> {
    val event = HookEvent(type = HookEvent.Type.PRE_LLM_REQUEST, messages = messages)
    val results = fire(event)
    val appended = mutableListOf<Message>()
    for (r in results) {
        when (r) {
            HookResult.Continue -> { /* no-op */ }
            is HookResult.Block -> logger.warn { "PreLlmRequest handler returned Block, ignoring" }
            is HookResult.Replace -> logger.warn { "PreLlmRequest handler returned Replace, ignoring" }
            is HookResult.AppendMessages -> appended.addAll(r.messages)
        }
    }
    return appended
}

for (iteration in 1..config.maxIterations) {
    val baseMessages = buildRequestMessages()
    // s07: PRE_LLM_REQUEST hook —— 让外部扩展点追加消息（skill 元数据等）
    val appended = hooks.onPreLlmRequest?.invoke(baseMessages) ?: emptyList()
    val requestMessages = if (appended.isEmpty()) baseMessages else baseMessages + appended
    logger.debug { "Iteration $iteration/${config.maxIterations}: sending ${requestMessages.size} messages to LLM" }

    val response = llmProvider.chat(requestMessages, options, tools)
    // ...
}

data class AgentLoopHooks(
    val onBeforeToolExecute: (suspend (ToolCall) -> Boolean)? = null,
    val onPreToolUse: (suspend (ToolCall) -> String?)? = null,
    val onPostToolUse: (suspend (ToolCall, ToolResult) -> ToolResult)? = null,
    val onPreLlmRequest: (suspend (List<Message>) -> List<Message>)? = null  // 新增
)

data class SkillManifest(
    val name: String,           // frontmatter.name，全局唯一，用作 SkillStore 的 key
    val description: String,    // frontmatter.description
    val body: String,           // frontmatter 之后的 markdown 原文，由 load_skill 工具返回给 LLM
    val sourcePath: String      // SKILL.md 的绝对路径，用于 /skill show 调试
)

---
name: skill-name
description: A short description of when to use this skill.
---
# Markdown body

object SkillFrontmatter {
    const val FRONTMATTER_DELIMITER = "---"

    fun parse(content: String, sourcePath: String): SkillManifest {
        // 1. 校验首行 == "---"
        // 2. 找到第二个 "---" 行作为 frontmatter 结束
        // 3. 中间行用 parseLine 解析为 Map<String, String>
        // 4. name 必需（非空），description 可选（默认空串）
        // 5. body = 第二个 "---" 之后的内容（trimLeading）
    }

    internal fun parseLine(line: String): Pair<String, String>? {
        // 支持 `key: value`、`key: "value"`、`key: 'value'`、trim 空格
        // 不支持嵌套对象/列表/锚点（s07 不需要）
    }
}

name: simple-value
description: "quoted value with: colon"
description: 'single quoted'

class SkillLoadException(
    val sourcePath: String?,
    message: String
) : Exception(message)

class SkillLoader(
    private val skillPaths: List<String>
) {
    fun load(): LoadResult {
        val skills = mutableMapOf<String, SkillManifest>()  // name → manifest，后加载覆盖
        val failures = mutableListOf<LoadFailure>()

        for (rawPath in skillPaths) {
            val path = expandHome(rawPath)
            if (!Files.exists(path)) continue  // 路径不存在不算错误
            if (!Files.isDirectory(path)) continue

            Files.list(path).use { dirs ->
                dirs.filter { Files.isDirectory(it) && !Files.isHidden(it) }.forEach { skillDir ->
                    val skillFile = skillDir.resolve(SKILL_FILE)
                    if (!Files.exists(skillFile)) return@forEach

                    try {
                        val content = Files.readString(skillFile)
                        val manifest = SkillFrontmatter.parse(content, skillFile.toString())
                        skills[manifest.name] = manifest  // 后加载覆盖
                    } catch (e: SkillLoadException) {
                        failures.add(LoadFailure(...))
                    } catch (e: Exception) {
                        failures.add(LoadFailure(..., "IO error: ${e.message}"))
                    }
                }
            }
        }

        return LoadResult(skills = skills.values.toList(), failures = failures)
    }
}

data class LoadResult(
    val skills: List<SkillManifest>,
    val failures: List<LoadFailure>
) {
    val successCount: Int get() = skills.size
    val failureCount: Int get() = failures.size
}

class SkillStore {
    private val skills: CopyOnWriteArrayList<SkillManifest> = CopyOnWriteArrayList()

    fun reload(skills: List<SkillManifest>) {
        this.skills.clear()
        this.skills.addAll(skills)
    }
    fun getAll(): List<SkillManifest> = skills.toList()
    fun get(name: String): SkillManifest? = skills.firstOrNull { it.name == name }
    fun size(): Int = skills.size
    fun clear() = skills.clear()
}

class ClearCommand : ReplCommand {
    override suspend fun execute(args: String, ctx: ReplContext): ReplCommandResult {
        ctx.agentLoop.messagesHistory.clear()
        ctx.approvalStore.clear()
        ctx.todoStore.clear()
        ctx.subagentStore.clear()
        // 不清空 ctx.skillStore —— skill 是项目/用户级配置，不是会话状态
        return ReplCommandResult.Continue
    }
}

class SkillInjectionHook(
    private val store: SkillStore
) {
    fun registerTo(manager: HookManager) {
        val handler: HookHandler = handler@{ event ->
            if (event.type != HookEvent.Type.PRE_LLM_REQUEST) {
                return@handler HookResult.Continue
            }

            val skills = store.getAll()
            if (skills.isEmpty()) {
                return@handler HookResult.Continue  // 空 store 不浪费 token
            }

            val text = buildSkillsMetadataText(skills)
            HookResult.AppendMessages(listOf(Message(Role.SYSTEM, text)))
        }
        manager.on(HookEvent.Type.PRE_LLM_REQUEST, handler)
    }

    internal fun buildSkillsMetadataText(skills: List<SkillManifest>): String = buildString {
        append("# Available Skills\n\n")
        append("The following skills are available. Call the `load_skill` tool with the skill's name to retrieve its full instructions, then follow them.\n\n")
        for (skill in skills) {
            append("## ${skill.name}\n")
            append("${skill.description}\n\n")
        }
    }.trimEnd()
}

class SkillLoaderTool(
    private val store: SkillStore
) : Tool {
    override val name = "load_skill"
    override val description = "Load the full content (body) of a skill by name. " +
        "Use this when you've decided to apply a skill from the available skills list."
    override val isReadOnly = true  // 只读 SkillStore，无副作用

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

        val skill = store.get(skillName)
            ?: return ToolResult("", "Error: skill not found: $skillName", isError = true)

        val content = buildString {
            append("# Skill: ${skill.name}\n\n")
            append("Description: ${skill.description}\n\n")
            append("## Instructions\n\n")
            append(skill.body)
        }
        return ToolResult("", content)
    }
}

用户: "帮我 review SkillStore.kt"
   ↓
LLM 收到请求（末尾带 # Available Skills SYSTEM 消息）
   ↓
LLM 看到 "## code-review / 审查代码变更..."
   ↓
LLM 调用 load_skill(name="code-review")
   ↓
SkillLoaderTool 返回完整 body（4 步审查流程）
   ↓
LLM 按 body 中的步骤执行：git diff → 检查 5 个维度 → 输出报告

private fun handleCommand(input: String): Boolean {
    val cmd = input.split(" ", limit = 2)[0]
    return when (cmd) {
        CMD_EXIT, CMD_QUIT, CMD_Q -> { println("Exiting..."); false }
        CMD_HELP, CMD_H -> { printHelp(); true }
        CMD_CLEAR, CMD_C -> { /* clear 4 stores */ true }
        else -> { println("Unknown command: $cmd"); true }
    }
}

interface ReplCommand {
    val name: String          // "/exit"、"/skill"
    val description: String  // 用于 /help
    suspend fun execute(args: String, ctx: ReplContext): ReplCommandResult
}

sealed class ReplCommandResult {
    object Continue : ReplCommandResult()
    object Exit : ReplCommandResult()
}

data class ReplContext(
    val agentLoop: AgentLoop,
    val approvalStore: ApprovalStore,
    val todoStore: TodoStore,
    val subagentStore: SubagentStore,
    val skillStore: SkillStore,
    val skillLoader: SkillLoader
)

class ReplCommandRegistry {
    private val commands: MutableMap<String, ReplCommand> = mutableMapOf()
    private val primaryNames: MutableSet<String> = mutableSetOf()

    fun register(command: ReplCommand, vararg aliases: String) {
        commands[command.name] = command
        primaryNames.add(command.name)
        for (alias in aliases) {
            commands[alias] = command
        }
    }

    fun find(name: String): ReplCommand? = commands[name]

    fun all(): List<ReplCommand> =
        primaryNames.map { commands[it]!! }
}

private fun handleCommand(input: String): Boolean = runBlocking {
    val parts = input.split(" ", limit = 2)
    val cmdName = parts[0]
    val args = parts.getOrNull(1)?.trim() ?: ""

    val command = commandRegistry.find(cmdName)
    if (command == null) {
        println("Unknown command: $cmdName. Type /help for available commands.")
        return@runBlocking true
    }

    val ctx = ReplContext(
        agentLoop = agentLoop,
        approvalStore = approvalStore,
        todoStore = todoStore,
        subagentStore = subagentStore,
        skillStore = skillStore,
        skillLoader = skillLoader
    )
    when (command.execute(args, ctx)) {
        ReplCommandResult.Continue -> true
        ReplCommandResult.Exit -> false
    }
}

// ExitCommand: /exit /quit /q
class ExitCommand : ReplCommand {
    override val name = "/exit"
    override val description = "Exit Cat-Code"
    override suspend fun execute(args: String, ctx: ReplContext) = run {
        println("Exiting...")
        ReplCommandResult.Exit
    }
}

// HelpCommand: /help /h
class HelpCommand(private val registry: ReplCommandRegistry) : ReplCommand {
    override val name = "/help"
    override val description = "Show available commands"
    override suspend fun execute(args: String, ctx: ReplContext) = run {
        // 从 registry.all() 聚合命令列表，按 name 排序
        println(buildHelpText(registry.all()))
        ReplCommandResult.Continue
    }
}

// ClearCommand: /clear /c
class ClearCommand : ReplCommand {
    override val name = "/clear"
    override val description = "Clear conversation history and stores"
    override suspend fun execute(args: String, ctx: ReplContext) = run {
        ctx.agentLoop.messagesHistory.clear()
        ctx.approvalStore.clear()
        ctx.todoStore.clear()
        ctx.subagentStore.clear()
        // 不清空 ctx.skillStore —— skill 是配置，不是会话状态
        ReplCommandResult.Continue
    }
}

// SkillCommand: /skill list|reload|show <name>
class SkillCommand : ReplCommand {
    override val name = "/skill"
    override val description = "Manage skills (list, reload, show)"
    override suspend fun execute(args: String, ctx: ReplContext): ReplCommandResult {
        // 子命令解析：list / reload / show <name>
    }
}

fun start() {
    subagentScope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
    todoStore = TodoStore()
    subagentStore = SubagentStore()
    // ... 工具注册 ...

    val hookManager = HookManager()
    LoggingHook().registerTo(hookManager)
    TimingHook().registerTo(hookManager)
    TodoDisplayHook().registerTo(hookManager)

    // s07: 加载 skills 并注册注入 hook
    skillStore = SkillStore()
    skillLoader = SkillLoader(config.skillPaths)
    val loadResult = skillLoader.load()
    skillStore.reload(loadResult.skills)
    logger.info { "Skills loaded: ${loadResult.successCount} ok, ${loadResult.failureCount} failed" }
    SkillInjectionHook(skillStore).registerTo(hookManager)
    // s07: 让 LLM 能通过 load_skill(name) 主动加载 skill body
    toolRegistry.register(SkillLoaderTool(skillStore))

    agentLoop = AgentLoop(
        llmProvider = llmProvider,
        systemPrompt = systemPrompt,
        config = config,
        hooks = AgentLoopHooks(
            onBeforeToolExecute = { tc -> pipeline.approve(tc) },
            onPreToolUse = { tc -> hookManager.firePreToolUse(tc) },
            onPostToolUse = { tc, result -> hookManager.firePostToolUse(tc, result) },
            onPreLlmRequest = { msgs -> hookManager.firePreLlmRequest(msgs) }  // 新增
        ),
        toolRegistry = toolRegistry
    )

    // s07: 命令注册表
    commandRegistry = ReplCommandRegistry().apply {
        val exitCmd = ExitCommand()
        register(exitCmd, "/quit", "/q")
        register(HelpCommand(this), "/h")
        register(ClearCommand(), "/c")
        register(SkillCommand())
    }

    printWelcome()
    // ... REPL 主循环 ...
}

private fun printWelcome() {
    val skillCount = skillStore.size()
    val skillNote = if (skillCount > 0) " ($skillCount skills loaded)" else ""
    println("🐱 Cat-Code — Index 07: Skill Loading$skillNote")
    println("Type /help for commands, /exit to quit.")
    println()
}

🐱 Cat-Code — Index 07: Skill Loading (3 skills loaded)

src/main/kotlin/com/sepcai/code/
├── skill/                              # [新建] 技能领域包
│   ├── SkillManifest.kt               # data class(name/description/body/sourcePath)
│   ├── SkillFrontmatter.kt            # 零依赖 frontmatter 解析器 + SkillLoadException
│   ├── SkillLoader.kt                 # 多路径扫描 + LoadResult 聚合
│   ├── SkillStore.kt                  # CopyOnWriteArrayList 内存存储
│   ├── SkillInjectionHook.kt          # PRE_LLM_REQUEST handler（注入 metadata）
│   └── SkillLoaderTool.kt             # load_skill 工具（按需返回 body 给 LLM）
├── hooks/
│   ├── HookEvent.kt                   # [修改] +PRE_LLM_REQUEST +messages 字段
│   ├── HookResult.kt                  # [修改] +AppendMessages 子类
│   └── HookManager.kt                # [修改] +firePreLlmRequest +两处 when 补分支
├── agent/
│   ├── AgentConfig.kt                 # [修改] +skillPaths 字段 + DEFAULT_SKILL_PATHS
│   ├── AgentLoop.kt                   # [修改] buildRequestMessages 后注入 hook
│   └── AgentLoopHooks.kt             # [修改] +onPreLlmRequest 字段
├── repl/
│   ├── ReplCommand.kt                 # [新建] 接口 + ReplCommandResult + ReplContext
│   ├── ReplCommandRegistry.kt         # [新建] Map + 别名支持
│   ├── ReplLoop.kt                    # [修改] 集成 skill + commandRegistry
│   └── commands/                      # [新建]
│       ├── ExitCommand.kt             # /exit /quit /q
│       ├── HelpCommand.kt             # /help /h（从 registry 聚合）
│       ├── ClearCommand.kt            # /clear /c
│       └── SkillCommand.kt            # /skill list|reload|show
└── tool/tools/                        # 不变

src/test/kotlin/com/sepcai/code/
├── skill/                             # [新建]
│   ├── SkillFrontmatterTest.kt        # 8 用例
│   ├── SkillLoaderTest.kt             # 8 用例
│   ├── SkillStoreTest.kt              # 6 用例
│   ├── SkillInjectionHookTest.kt      # 5 用例
│   └── SkillLoaderToolTest.kt         # 7 用例
├── repl/
│   ├── ReplCommandRegistryTest.kt     # [新建] 4 用例
│   └── commands/                      # [新建]
│       └── SkillCommandTest.kt        # 8 用例
├── hooks/
│   └── HookManagerTest.kt            # [修改] +4 个 firePreLlmRequest 用例
└── agent/
    └── AgentLoopTest.kt              # [修改] +3 个 PRE_LLM_REQUEST 集成用例