配置与 Profile 模型（Config and Profile Model）

目标关联

该特性支撑专业身份配置、领域扩展、上下文连续性、可审计交付和专业可靠性。

实现的关键特性：

• 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 models 在执行前校验配置。
• system prompt 从结构化 profile 渲染。
• resolved config 复制到 run sandbox。
• profile、skills、tools、memory、sandbox、deliverables 显式化。
• 未来 scheduler 可基于 profile id、skill ids、tool permissions、memory scopes 路由任务。

范围

Phase 1 包含 kgent.yaml schema、typed config models、profile 字段、model config、skill config、tool config、memory config、sandbox config、deliverables config、prompt rendering 和 config snapshot。

不包含 remote config registry、profile marketplace、dynamic profile generation、full policy language、复杂 config 继承和完整 secrets management。

概念模型

KgentConfig
  kgent metadata
  model config
  profile config
  skills config
  tools config
  memory config
  workspace config
  deliverables config
  runtime config

Profile
  id
  role
  responsibilities
  style
  constraints
  default skills
  default deliverables

配置示例

kgent:
  name: professional-worker
  version: 1
  schema_version: 1

model:
  provider: openai
  name: gpt-4.1-mini
  api_key_env: OPENAI_API_KEY

profile:
  id: travel-planner
  role: senior travel planner
  responsibilities:
    - clarify travel constraints
  style:
    - concise
  constraints:
    - save all final work under deliverables

skills:
  paths:
    - ./skills
  enabled:
    - travel-planning

tools:
  filesystem:
    enabled: true
    write: true
    delete: false
    max_file_bytes: 200000
  shell:
    enabled: false

memory:
  enabled: true
  provider: external
  write_mode: candidate
  scopes:
    - user
    - project

workspace:
  sandbox: ./runs/travel-001

deliverables:
  required:
    - deliverables/final.md
    - deliverables/summary.json

runtime:
  stream: true
  max_steps: 20

稳定配置字段

Phase 1 必须包含 kgent.schema_version 和稳定 profile.id。创建 run 时应计算并记录 config_fingerprint，用于标识本次 run 使用的 resolved config snapshot。

Prompt 组合顺序

Effective system 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 单独归档为 prompt.md。

接口

CLI：

kgent run --config kgent.yaml --prompt "..."
kgent run --config kgent.yaml --prompt-file task.md

Python：

def load_config(path: Path) -> KgentConfig:
    ...

def render_system_prompt(config, skill_index, memory_summary, sandbox_rules) -> str:
    ...

产物

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

run.json 应包含 session_id、task_id、run_id、profile_id、config_fingerprint、config_path、created_at、status。

质量和治理

Config validation 应捕获缺失 model、缺失 profile role、缺失 sandbox、无效 tool permissions、enabled skills 但无 skill paths、required deliverables 不在 deliverables/ 下、危险 filesystem 默认值等问题。

Secrets 通过环境变量名引用，不直接写入 config。

性能和调度考虑

Prompt rendering 不加载完整技能正文；memory summary 只来自 bounded recall；resolved config 对一个 run 不可变；config snapshot 支撑环境重建。

验收标准

1. kgent.yaml 有文档化 schema。
2. Config 加载到 typed models。
3. 无效 config 在 agent 执行前失败。
4. Profile 字段可改变 effective system prompt。
5. skills、tools、memory、sandbox、deliverables 都在 config 中表达。
6. resolved config 复制到 run directory。
7. effective system prompt 被归档。
8. 包含 schema_version、profile.id、config_fingerprint。
9. prompt composition 顺序确定。