项目与包结构（Project and Package Structure）

目标关联

该特性支撑专业工作执行、领域扩展、可审计交付和专业可靠性。它为 runtime、config、engine、sandbox、records、skills、tools、memory 和 governance 建立清晰边界。

实现的关键特性：

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

技术设计对齐

• Phase 1 CLI-first。
• Pydantic AI 隔离在 engine/ adapter 后。
• Runtime 保持小，只协调一次 run。
• 领域能力放在 skills，外部上下文放在 memory，动作放在 tools。
• Durable artifacts 是 source of truth。
• 通过 session_id、task_id、run_id 等概念为未来 scheduler 打底。

范围

Phase 1 包含 Python package skeleton、CLI entry point、模块边界、tests directory、example configs 和 example skills。

Phase 1 不包含 scheduler service、API server、Web UI、plugin marketplace 和复杂部署包装。

概念模型

kgent package
  CLI
  Config
  Runtime
  Engine
  Sandbox
  Records
  Skills
  Tools
  Memory
  Governance

建议目录

kunora-kgent/
  pyproject.toml
  README.md
  docs/
  examples/
    configs/
    skills/
  src/
    kgent/
      cli.py
      config/
      runtime/
      engine/
      sandbox/
      records/
      skills/
      tools/
      memory/
      governance/
  tests/
    unit/
    integration/

Packaging Baseline

pyproject.toml 应定义：

project name: kunora-kgent
python: >=3.11
cli entry point: kgent = kgent.cli:main
runtime dependencies:
  pydantic
  pydantic-ai
  pyyaml
dev dependencies:
  pytest

接口

CLI：

kgent run --config examples/configs/kgent.yaml --prompt "..." --sandbox ./runs/demo-001

Python public surface 第一版保持很小：

from kgent.runtime import run
from kgent.config import load_config

运行时行为

cli.py
  -> config.loader
  -> runtime.runner
  -> sandbox.workspace
  -> skills.registry
  -> tools.*
  -> engine.pydantic_ai
  -> records.*
  -> governance.*

产物

结构应支持标准 run 输出：

runs/<run-id>/
  run.json
  config.yaml
  effective-system-prompt.md
  events.jsonl
  transcript.md
  workspace/
  deliverables/
  archive/
  logs/

质量和治理

• config validation 位于 config/。
• path safety 位于 sandbox/。
• tool permissions 位于 tools/。
• deliverable checks 位于 governance/。
• event/transcript records 位于 records/。

性能和调度考虑

高成本路径必须可替换：memory contract、Pydantic AI adapter、filesystem tools、future indexing。调度概念必须有明确位置：session_id、task_id、run_id、run state、manifests、append-only events。

验收标准

1. 仓库有 src/kgent package skeleton。
2. CLI entry point 有明确位置。
3. 核心模块分离。
4. examples 和 tests 有明确位置。
5. 不硬编码任何专业领域。
6. Pydantic AI 依赖隔离在 engine 后。
7. 未来 scheduler 概念不需要重构项目。
8. pyproject.toml 定义 CLI entry point 和最低 Python 版本。