配置模块详细设计

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

配置模块是 Phase 1 的入口边界之一，负责把人类可编辑的 kgent.yaml 转换成可校验、可归档、可用于构建 run 的 typed config。

目标关联

配置模块支撑：

• Configurable Professional Identity
• Skill-Driven Capability System
• Tool-Mediated Action System
• Memory-Aware Context System
• Sandbox-First Work Execution
• Quality and Governance System

它直接支撑产品目标中的专业工作执行、领域扩展、可审计交付和专业可靠性。

模块范围

包含：

• YAML 读取。
• typed config models。
• 默认值填充。
• config validation。
• CLI overrides 应用。
• config fingerprint。
• effective system prompt rendering。

不包含：

• 创建 sandbox。
• 执行 agent。
• 执行工具。
• 访问外部记忆。
• 发现技能正文。

文件结构

src/kgent/config/
  __init__.py
  models.py
  loader.py
  prompts.py
  validation.py

数据模型

位置：models.py

class KgentMetaConfig:
    name: str
    version: int
    schema_version: int

class ModelConfig:
    provider: str
    name: str
    api_key_env: str | None
    base_url: str | None

class ProfileConfig:
    id: str
    role: str
    responsibilities: list[str]
    style: list[str]
    constraints: list[str]

class SkillsConfig:
    paths: list[Path]
    enabled: list[str]

class FilesystemToolConfig:
    enabled: bool
    write: bool
    delete: bool
    max_file_bytes: int

class ShellToolConfig:
    enabled: bool

class ToolsConfig:
    filesystem: FilesystemToolConfig
    shell: ShellToolConfig

class MemoryConfig:
    enabled: bool
    provider: str
    write_mode: Literal["disabled", "candidate", "external"]
    scopes: list[str]

class WorkspaceConfig:
    sandbox: Path | None

class DeliverablesConfig:
    required: list[str]

class RuntimeConfig:
    stream: bool
    max_steps: int | None
    timeout_seconds: int | None

class KgentConfig:
    kgent: KgentMetaConfig
    model: ModelConfig
    profile: ProfileConfig
    skills: SkillsConfig
    tools: ToolsConfig
    memory: MemoryConfig
    workspace: WorkspaceConfig
    deliverables: DeliverablesConfig
    runtime: RuntimeConfig

默认值

Phase 1 默认值必须安全：

kgent.schema_version = 1
tools.filesystem.enabled = true
tools.filesystem.write = true
tools.filesystem.delete = false
tools.filesystem.max_file_bytes = 200000
tools.shell.enabled = false
memory.enabled = false
memory.write_mode = candidate
runtime.stream = true
runtime.max_steps = 20

校验规则

配置加载阶段必须在 agent 执行前失败：

• kgent.schema_version 缺失或不支持。
• model.provider 或 model.name 缺失。
• profile.id 或 profile.role 缺失。
• skills.enabled 非空但 skills.paths 为空。
• required deliverables 不在 deliverables/ 下。
• tools.filesystem.delete = true 时必须显式允许，Phase 1 默认拒绝。
• memory.write_mode = external 时必须声明 memory.provider = external 或等价外部 provider 标识；具体连接信息由注入的 MemoryClient 负责，不在 config 层过早绑定。
• workspace.sandbox 可为空，但 runtime 必须能通过 CLI 或默认规则确定 sandbox。

函数接口

位置：loader.py

def load_config(path: Path) -> KgentConfig:
    """读取 YAML 并返回已校验的 KgentConfig。"""

def apply_cli_overrides(config: KgentConfig, overrides: CliOverrides) -> KgentConfig:
    """应用 CLI 覆盖项，返回新的 resolved config。"""

def fingerprint_config(config: KgentConfig) -> str:
    """对 resolved config 生成稳定 fingerprint。"""

位置：validation.py

def validate_config(config: KgentConfig) -> None:
    """执行跨字段校验。失败时抛出结构化配置错误。"""

位置：prompts.py

def render_system_prompt(
    config: KgentConfig,
    skill_index: list[SkillSummary],
    memory_summary: str | None,
    sandbox_rules: str,
) -> str:
    ...

Prompt 渲染顺序

必须保持确定性：

1. kgent runtime identity and global rules。
2. Profile role。
3. Profile responsibilities。
4. Profile style。
5. Profile constraints。
6. Sandbox rules。
7. Tool rules。
8. Skill index summaries。
9. Memory summary。
10. Deliverable contract。

用户 prompt 不进入 system prompt，单独归档为 prompt.md。

产物

配置模块不直接创建 run 目录，但 runtime 会将 resolved config 写入：

runs/<run-id>/config.yaml
runs/<run-id>/effective-system-prompt.md

测试设计

单元测试：

• valid config loads。
• missing model fails。
• missing profile role fails。
• unsupported schema version fails。
• deliverable outside deliverables/ fails。
• memory.write_mode default is candidate。
• tools.shell.enabled default is false。
• tools.filesystem.delete default is false。
• CLI override changes sandbox。
• fingerprint is stable for equivalent resolved config。
• prompt composition order is deterministic。

集成测试：

• kgent run 使用 config + CLI overrides 后，config.yaml 和 effective-system-prompt.md 被正确归档。

实现注意事项

• 读取 YAML 时不要执行任意代码。
• fingerprint 应基于 normalized resolved config，而不是原始 YAML 文本。
• 不要把 secrets value 写入 resolved config；只保存 env var name。
• 错误应转换为统一 ErrorInfo，category 为 config。

验收标准

1. 配置能从 YAML 加载到 typed models。
2. 关键默认值安全。
3. 跨字段校验在 agent 执行前完成。
4. CLI overrides 可应用并被记录。
5. config fingerprint 稳定。
6. system prompt 渲染顺序稳定。
7. 配置错误能转换为结构化错误。