Skills 模块详细设计

本文档展开 kgent/skills/ 的代码设计。

Skills 模块负责发现、索引和按需加载技能包，是 kgent 支持多领域专业能力的核心。

目标关联

Skills 模块支撑：

• Skill-Driven Capability System
• Configurable Professional Identity
• Quality and Governance System
• Learning and Capability Evolution

它直接支撑领域扩展、专业工作执行和长期能力沉淀。

模块范围

包含：

• 扫描配置中的 skill paths。
• 解析 SKILL.md front matter。
• 构建 skill index。
• 校验 enabled skills。
• 向 agent 暴露 skill summaries。
• 按需加载技能正文和摘要资源。
• 记录 skill indexed/loaded events。

不包含：

• 自动生成技能。
• 自动提升候选技能。
• 执行 skill scripts。
• 安装 skill dependencies。
• 授予工具权限。

文件结构

src/kgent/skills/
  __init__.py
  models.py
  registry.py
  loader.py
  parser.py

技能目录结构

skills/
  travel-planning/
    SKILL.md
    references/
    templates/
    scripts/
    examples/

Phase 1 只要求 SKILL.md 必须存在。

数据模型

位置：models.py

class SkillMetadata:
    id: str
    name: str
    description: str
    tags: list[str]
    permissions: dict

class SkillSummary:
    id: str
    name: str
    description: str
    tags: list[str]
    path: Path

class LoadedSkill:
    summary: SkillSummary
    instructions: str
    references_summary: str | None
    templates_summary: str | None
    declared_permissions: dict
    content_bytes: int

SKILL.md front matter

示例：

---
id: travel-planning
name: Travel Planning
description: Use this skill to design practical travel plans, budgets, and risk checklists.
tags:
  - travel
permissions:
  filesystem: read
  web: optional
---

# Travel Planning

...

必填字段：

• id
• name
• description

可选字段：

• tags
• permissions

解析接口

位置：parser.py

def parse_skill_file(path: Path) -> tuple[SkillMetadata, str]:
    ...

行为：

• 读取 SKILL.md。
• 解析 YAML front matter。
• 返回 metadata 和 markdown body。
• malformed front matter 转为 ErrorInfo(category="skill")。

Phase 1 可以实现一个很小的 front matter parser，避免引入过多依赖；如已有 YAML 依赖，可复用 pyyaml。

Registry 接口

位置：registry.py

class SkillRegistry:
    def __init__(self, skill_paths: list[Path], enabled: list[str], recorder: EventRecorder | None = None):
        ...

    def discover(self) -> list[SkillSummary]:
        ...

    def list_skills(self) -> list[SkillSummary]:
        ...

    def load_skill(self, skill_id: str) -> LoadedSkill:
        ...

行为：

• discover 扫描所有 configured skill paths。
• 只读取 SKILL.md metadata。
• 校验 skill ids 唯一。
• 校验 enabled skills 都存在。
• list_skills 返回 summaries。
• load_skill 按需读取 body 和有限资源摘要。

Loaded Skill Budget

Phase 1 必须限制 loaded skill 内容大小。

建议配置：

max_loaded_skill_bytes = 24000

加载策略：

1. 优先加载 SKILL.md body。
2. 如果仍有预算，加载 references/templates 的文件名和摘要。
3. 不加载 scripts 内容，只列出脚本路径和用途摘要。
4. 超出预算时返回 summary 和可用资源列表。

权限语义

Skill permissions 是声明，不是授权。

Skills 模块只返回 declared_permissions。Tool 系统负责和 config、runtime defaults、sandbox constraints 合并为 EffectivePermissionPolicy。

运行时集成

Runtime 在 engine 执行前：

1. 创建 SkillRegistry。
2. 调用 discover。
3. 将 SkillSummary 列表传给 prompt renderer。
4. 将 list_skills 和 load_skill 注册为 tools。

Agent 调用 load_skill(skill_id) 后：

1. Registry 返回 LoadedSkill。
2. Recorder 写入 skill.loaded。
3. Tool 系统可重新计算或检查 effective permission policy。

产物

可写入：

runs/<run-id>/archive/skill-index.json

内容：

{
  "available": [],
  "enabled": [],
  "loaded": []
}

Phase 1 可先记录 available/enabled，loaded 由 events 表达。

测试设计

单元测试：

• valid skill parsed。
• missing SKILL.md ignored or fails based on enabled status。
• malformed front matter fails。
• missing required metadata fails。
• duplicate skill id fails。
• enabled missing skill fails。
• discovery only reads metadata。
• load skill returns bounded content。
• scripts are listed but not executed。
• permissions are returned as declarations。

集成测试：

• config enabled skill 被发现。
• prompt renderer 收到 skill summaries。
• agent-facing list_skills 返回 summaries。
• agent-facing load_skill 返回 bounded LoadedSkill。
• skill.indexed 和 skill.loaded events 被写入。

性能和调度考虑

• Discovery 只加载 metadata。
• Full skill body 仅按需加载。
• Loaded skill 有字节预算。
• Skill ids 和版本信息未来可用于 scheduler capability routing。
• skill-index.json 可用于环境重建。

验收标准

1. Skills 可从 filesystem packages 发现。
2. SKILL.md metadata 可解析和校验。
3. enabled missing skill 在 agent 执行前失败。
4. skill summaries 可注入 prompt。
5. load_skill 按需加载且有预算。
6. Skill permissions 不直接授予工具权限。
7. skill events 被记录。