SKILL 系统实现原理详解#

export namespace Skill {
  // 技能信息结构
  export const Info = z.object({
    name: z.string(),        // 技能名称（唯一标识）
    description: z.string(), // 技能描述
    location: z.string(),    // 文件路径
    content: z.string(),      // Markdown 正文内容
  })
  export type Info = z.infer<typeof Info>
}

// Instance.state 是懒加载的核心入口
// 它基于 State.create 实现，返回一个函数

// 文件：packages/opencode/src/project/instance.ts
export const Instance = {
  // state 签名：传入 init 函数和可选的 dispose 函数
  // 返回 () => S 类型的函数
  state<S>(
    init: () => S,
    dispose?: (state: Awaited<S>) => Promise<void>
  ): () => S {
    return State.create(
      () => Instance.key,  // 用实例 key 作为根标识
      init,
      dispose
    )
  }
}

// Skill.state 的实际使用
export const state = Instance.state(async () => {
  const skills: Record<string, Info> = {}

  // 1. 扫描 .claude/skills/ 目录（兼容 Claude Code）
  const claudeDirs = await Array.fromAsync(
    Filesystem.up({
      targets: [".claude"],
      start: Instance.directory,
      stop: Instance.worktree,
    }),
  )
  // 也包含全局 ~/.claude/skills/
  const globalClaude = `${Global.Path.home}/.claude`
  if (await Filesystem.isDir(globalClaude)) {
    claudeDirs.push(globalClaude)
  }

  // 使用 Glob 模式扫描所有 SKILL.md 文件
  const matches = await Array.fromAsync(
    CLAUDE_SKILL_GLOB.scan({
      cwd: dir,
      absolute: true,
      onlyFiles: true,
      followSymlinks: true,
      dot: true,
    }),
  )

  // 2. 扫描 .opencode/skill/ 目录
  for (const dir of await Config.directories()) {
    for await (const match of OPENCODE_SKILL_GLOB.scan({ cwd: dir, ... })) {
      await addSkill(match)
    }
  }

  // 3. 扫描配置中指定的额外路径
  const config = await Config.get()
  for (const skillPath of config.skills?.paths ?? []) {
    // 支持 ~ 展开和相对路径
    const resolved = path.resolve(...)
    for await (const match of SKILL_GLOB.scan({ cwd: resolved, ... })) {
      await addSkill(match)
    }
  }

  return skills
})

export namespace SkillMarket {
  // 状态文件：记录已安装技能
  const stateFile = path.join(Global.Path.state, "skills-market.json")

  // 市场根目录
  const marketRoot = path.join(Global.Path.config, "skills", "market")
  const localRoot = path.join(Global.Path.config, "skills", "local")

  // 核心 API
  export async function list()        // 列出已安装和推荐技能
  export async function detail(value) // 获取技能详情
  export async function install(value)    // 从市场安装
  export async function uninstall(value)   // 卸载技能
  export async function enable(value)      // 启用技能
  export async function disable(value)    // 禁用技能
  export async function create(input)      // 创建本地技能
}

export const SkillTool = Tool.define("skill", async (ctx) => {
  const skills = await Skill.all()

  // 权限过滤：根据 Agent 权限决定可访问的技能
  const accessibleSkills = agent
    ? skills.filter((skill) => {
        const rule = PermissionNext.evaluate("skill", skill.name, agent.permission)
        return rule.action !== "deny"
      })
    : skills

  // 返回可用技能列表
  const description = [
    "Load a skill to get detailed instructions...",
    "Only the skills listed here are available:",
    "<available_skills>",
    ...accessibleSkills.map((skill) => `
      <skill>
        <name>${skill.name}</name>
        <description>${skill.description}</description>
      </skill>
    `),
    "</available_skills>",
  ].join(" ")

  // 执行：加载指定技能的内容
  async execute(params, ctx) {
    const skill = await Skill.get(params.name)
    const output = [
      `## Skill: ${skill.name}`,
      `**Base directory**: ${path.dirname(skill.location)}`,
      skill.content.trim()
    ].join("\n")
    return { title: `Loaded skill: ${skill.name}`, output }
  }
})

// 将所有技能注册为命令
for (const skill of await Skill.all()) {
  result[skill.name] = {
    name: skill.name,
    description: skill.description,
    source: "skill",
    get template() {
      return skill.content  // 技能内容作为命令模板
    },
    hints: [],
  }
}

// skill-types.ts
import { z } from "zod"
import fs from "fs/promises"
import path from "path"
import matter from "gray-matter"

// 技能信息结构
export const SkillInfo = z.object({
  name: z.string(),
  description: z.string(),
  location: z.string(),
  content: z.string(),
})
export type SkillInfo = z.infer<typeof SkillInfo>

// 加载并解析 SKILL.md 文件
export async function parseSkill(filePath: string): Promise<SkillInfo | null> {
  try {
    const content = await fs.readFile(filePath, "utf-8")
    const { data, content: body } = matter(content)

    return {
      name: data.name || path.basename(path.dirname(filePath)),
      description: data.description || "",
      location: filePath,
      content: body.trim(),
    }
  } catch {
    return null
  }
}

// skill-manager.ts
import { Glob } from "bun"
import { parseSkill, type SkillInfo } from "./skill-types"

export class SkillManager {
  private skills: Map<string, SkillInfo> = new Map()
  private cache: Promise<Map<string, SkillInfo>> | null = null

  // 技能扫描根目录
  private roots: string[] = []

  constructor(...roots: string[]) {
    this.roots = roots
  }

  // 懒加载：扫描并缓存所有技能
  async load(): Promise<Map<string, SkillInfo>> {
    if (this.cache) return this.cache

    this.cache = this.scanAll()
    return this.cache
  }

  private async scanAll(): Promise<Map<string, SkillInfo>> {
    const glob = new Glob("**/SKILL.md")
    const skills = new Map<string, SkillInfo>()

    for (const root of this.roots) {
      for await (const file of glob.scan({ cwd: root, absolute: true })) {
        const skill = await parseSkill(file)
        if (skill) {
          // 警告重复
          if (skills.has(skill.name)) {
            console.warn(`Duplicate skill: ${skill.name}`)
          }
          skills.set(skill.name, skill)
        }
      }
    }

    return skills
  }

  // 获取单个技能
  async get(name: string): Promise<SkillInfo | undefined> {
    const skills = await this.load()
    return skills.get(name)
  }

  // 获取所有技能
  async all(): Promise<SkillInfo[]> {
    const skills = await this.load()
    return Array.from(skills.values())
  }

  // 列出所有技能名称
  async names(): Promise<string[]> {
    const skills = await this.load()
    return Array.from(skills.keys())
  }
}

// skill-tool.ts
import { SkillManager } from "./skill-manager"
import { z } from "zod"

export function createSkillTool(skillManager: SkillManager) {
  // 工具定义（类似 OpenCode 的 Tool.define）
  return {
    name: "skill",
    description: "Load a skill to get detailed instructions for a specific task.",

    parameters: z.object({
      name: z.string().describe("The skill identifier from available_skills"),
    }),

    // 执行函数
    async execute(params: { name: string }) {
      const skill = await skillManager.get(params.name)

      if (!skill) {
        const available = await skillManager.names()
        throw new Error(
          `Skill "${params.name}" not found. Available: ${available.join(", ")}`
        )
      }

      // 返回格式化输出
      return {
        title: `Skill: ${skill.name}`,
        output: [
          `## ${skill.name}`,
          `**Description**: ${skill.description}`,
          `**Location**: ${skill.location}`,
          "",
          skill.content,
        ].join("\n"),
      }
    },

    // 获取可用技能列表（用于构建描述）
    async getAvailableSkills() {
      const skills = await skillManager.all()
      return skills.map((s) => ({
        name: s.name,
        description: s.description,
      }))
    },
  }
}

// minimal-skill-system.ts
import { SkillManager } from "./skill-manager"
import { createSkillTool } from "./skill-tool"

// ==================== 完整示例 ====================

async function main() {
  // 1. 创建技能管理器，指定扫描目录
  const manager = new SkillManager(
    "./skills",           // 本地技能
    "./.claude/skills",    // Claude Code 兼容
    "/home/user/skills",   // 全局技能
  )

  // 2. 创建工具接口
  const skillTool = createSkillTool(manager)

  // 3. 列出所有可用技能
  const available = await skillTool.getAvailableSkills()
  console.log("Available Skills:")
  available.forEach((s) => {
    console.log(`  - ${s.name}: ${s.description}`)
  })

  // 4. AI Agent 调用技能
  console.log("\n--- Calling skill('bun-file-io') ---")
  const result = await skillTool.execute({ name: "bun-file-io" })
  console.log(result.output)
}

main().catch(console.error)

// 在 Agent 初始化时加载技能
import { SkillManager } from "./skill-manager"

const skillManager = new SkillManager(
  "./skills",
  ".claude/skills"
)

// 初始化技能
await skillManager.load()

// Agent 可以根据上下文自动选择技能
async function agentTask(task: string) {
  // 模拟：根据任务选择技能
  if (task.includes("file")) {
    const skill = await skillManager.get("bun-file-io")
    console.log("Loaded skill:", skill.content)
  }
}

// 扫描特定路径
const manager = new SkillManager(
  path.join(process.env.HOME!, ".myapp/skills"),
  "./team-skills",
)

// 增量加载新技能
async function reloadSkill(skillPath: string) {
  const skill = await parseSkill(skillPath)
  if (skill) {
    const skills = await manager.load()
    skills.set(skill.name, skill)
  }
}

// 简单的权限检查
function canAccessSkill(skillName: string, allowedSkills: string[]): boolean {
  return allowedSkills.includes(skillName)
}

// 使用
const allowed = ["bun-file-io", "git-commands"]
const skill = await skillManager.get("secret-skill")

if (!canAccessSkill(skill.name, allowed)) {
  throw new Error(`Access denied to skill: ${skill.name}`)
}

export namespace State {
  // 全局状态存储：按根 key 分组
  const recordsByKey = new Map<string, Map<any, Entry>>()

  interface Entry {
    state: any           // 存储的是 Promise！
    dispose?: (state) => Promise<void>
  }

  /**
   * 创建一个懒加载状态
   *
   * @param root - 返回唯一标识的函数（如实例 key）
   * @param init - 初始化函数（async）
   * @param dispose - 可选的清理函数
   * @returns 一个函数，调用时返回状态
   */
  export function create<S>(
    root: () => string,
    init: () => S,
    dispose?: (state: Awaited<S>) => Promise<void>
  ) {
    return () => {
      const key = root()  // 获取当前实例的唯一 key

      // 获取或创建该 key 对应的 entries Map
      let entries = recordsByKey.get(key)
      if (!entries) {
        entries = new Map<string, Entry>()
        recordsByKey.set(key, entries)
      }

      // 关键！用 init 函数本身作为子 key
      // 同一实例多次调用，如果 init 是同一个函数引用，就返回缓存
      const exists = entries.get(init)
      if (exists) return exists.state as S  // 直接返回缓存的 Promise

      // 首次调用：执行 init（可能是 async 函数）
      const state = init()  // 返回 Promise

      entries.set(init, { state, dispose })
      return state
    }
  }
}

export namespace Skill {
  // 注意：init 是 async 函数，返回 Promise
  export const state = Instance.state(async () => {
    const skills: Record<string, Info> = {}

    // ... 扫描所有 SKILL.md 文件 ...

    return skills  // 返回 Map<string, Info>
  })

  // 使用方式：每次都是通过 .then() 获取结果
  export async function get(name: string) {
    return state().then((x) => x[name])
  }

  export async function all() {
    return state().then((x) => Object.values(x))
  }
}

// 这是关键设计选择

// 方案 A: 存储 resolved 值（错误）
const state = await init()  // 等待完成
entries.set(init, state)
return state

// 问题：第一次调用会阻塞，其他调用也必须等待

// 方案 B: 存储 Promise（正确）⭐
const state = init()  // 不等待
entries.set(init, { state })
return state

// 优点：
// 1. 首次调用立即返回 Promise，不阻塞
// 2. Promise 只能 resolved 一次，后续调用共享同一个结果
// 3. 所有 .then() 回调都会得到相同的结果

// 不同项目/用户有独立的状态缓存

// 实例 1: /project/a
State.create(
  () => "user1:/project/a",
  async () => { /* 扫描 project/a 的 skills */ }
)

// 实例 2: /project/b
State.create(
  () => "user1:/project/b",
  async () => { /* 扫描 project/b 的 skills */ }
)

// 实例 3: 不同用户
State.create(
  () => "user2:/project/a",
  async () => { /* 扫描另一个用户的 project/a */ }
)

// 每个实例独立缓存，互不影响

// 如果你只需要简单的懒加载，不需要实例隔离

class LazyState<T> {
  private cache: Promise<T> | null = null

  constructor(private init: () => Promise<T>) {}

  get(): Promise<T> {
    if (!this.cache) {
      this.cache = this.init()  // 首次调用时执行
    }
    return this.cache  // 后续调用返回缓存的 Promise
  }
}

// 使用
const skillState = new LazyState(async () => {
  console.log("Scanning skills...")  // 只打印一次
  const skills = await scanSkills()
  return skills
})

// 多次调用
skillState.get().then(...)  // 触发扫描
skillState.get().then(...)  // 使用缓存
skillState.get().then(...)  // 使用缓存

// 支持多个扫描根目录
const roots = [
  "./.claude",      // 项目级
  globalHome,       // 全局级
  ...configRoots,   // 配置指定
]

for (const root of roots) {
  for await (const file of glob.scan({ cwd: root })) {
    await addSkill(file)
  }
}

import matter from "gray-matter"

const { data, content } = matter(markdownContent)
// data.name, data.description 来自 YAML
// content 是 Markdown 正文

// 基于规则的权限检查
const rule = PermissionNext.evaluate("skill", skillName, agent.permission)
if (rule.action === "deny") {
  throw new Error("Access denied")
}