整体技术设计

本文档定义 kgent 的整体技术设计。

它关注为了实现 kgent 关键特性所需建设的技术能力和技术选型，并说明如何在质量、成本、速度和长期可维护性之间取得平衡。

本文档刻意不展开单个特性的实现细节。

设计目标

kgent 应被构建为轻量专业智能体运行时，而不是重型平台。

整体技术设计要达成三件事：

让 Phase 1 的 P0 关键特性真正可落地。
避免在编排、记忆和治理上过早复杂化。
保持核心边界稳定，使后续能够增加工作流、多智能体协作、技能演化和评测，而无需替换运行时。

从一开始就需要特别关注两个架构问题：

性能关键路径 必须被明确识别，并影响技术选型。
调度就绪性 必须内建到 run model 中，因为未来高并发、多任务执行和环境重建本质上都是调度问题。

技术设计原则

Runtime 保持小，能力在周边增长。
核心运行时只协调一次 run。领域知识放在 skills，长期上下文放在 memory，高成本动作放在 tools 或外部服务。
持久 artifacts 是 source of truth。
kgent 不应依赖进程内 conversation state 来支持审计、恢复、revision 或未来调度。
先稳定接口，再丰富实现。
Config、run state、events、skill metadata、memory tools、sandbox layout 应尽早形成稳定契约。
默认本地，未来可调度。
Phase 1 是本地 CLI，但每次 run 都应具备未来被排队、恢复、重试、修订和分发的形态。
质量从最小可执行约束开始。
不等完整 reviewer 系统，先实现安全工具默认值、必需交付物检查、路径限制和显式记录。
成本通过上下文纪律控制。
在使用更大模型或更重编排前，先使用 skill index、memory summary、bounded file reads 和 artifact summaries。

关键技术选择

领域	选择	原因
语言	Python	Pydantic AI 是 Python-first，AI 工具生态强，最快形成可用运行时。
Agent engine	Pydantic AI	提供类型化模型/工具执行，不强制引入重型平台。
接口	CLI-first	最低成本获得可用专业 worker runtime，便于自动化和测试。
配置	YAML + typed config models	人类可编辑，同时可通过 schema 约束。
工作区	本地 sandbox directory	简单、可检查、成本低，符合专业 artifact 工作流。
技能	文件系统 skill packages	适合版本控制、审查、模板、脚本和渐进式加载。
记忆	外部 memory contract	解耦记忆后端，适配已有记忆系统。
工具	Pydantic AI toolsets	类型化、可组合，与执行引擎一致。
记录	JSONL events + Markdown transcripts	低成本、append-friendly、人和机器都可读。
治理	policy-first，Phase 1 最小执行	避免阻塞 MVP，同时保留安全边界。

架构决策

决策	状态	理由
使用 Pydantic AI 作为执行引擎	Accepted	类型化模型/工具执行，不强制重平台。
Phase 1 使用 Python	Accepted	与 Pydantic AI 和 AI 生态匹配。
CLI 作为第一接口	Accepted	成本最低，便于运行、测试和检查 artifacts。
本地文件系统 sandbox 保存 run 输出	Accepted	简单、可审计、可检查，兼容未来调度。
记忆保持外部化	Accepted	避免 kgent 过早变成记忆平台。
技能使用文件系统包	Accepted	适合版本控制、审查、模板、脚本和渐进式加载。
Phase 1 不做完整 scheduler	Accepted	先建立 scheduler-ready 的 run 契约。
Phase 1 不做完整 workflow graph	Accepted	先有轻量 stages 和 artifacts，再考虑图复杂度。
Quality/Governance 是关键特性	Accepted	专业可靠性是产品能力，不是事后补丁。

架构策略

kgent 使用分层架构：

CLI Layer
  解析命令和参数。

Config Layer
  加载并验证 profiles、tools、skills、memory、sandbox 和 deliverables 设置。

Runtime Layer
  协调一次 kgent run。

Agent Engine Layer
  使用 Pydantic AI 执行模型调用、工具调用和 typed outputs。

Capability Layer
  提供 skills、tools、memory、sandbox 和 records。

Artifact Layer
  将所有持久化 run 输出保存到 sandbox。

核心运行时应保持小。领域复杂度放在 profiles 和 skills；操作复杂度放在 tools 和外部服务。

技术能力地图

Key Feature	所需技术能力	首选技术路径
Configurable Professional Identity	从结构化 profile config 组合 system prompt。	YAML config + typed Python models + prompt renderer。
Skill-Driven Capability System	发现、摘要和按需加载技能包。	Filesystem registry + `SKILL.md` metadata + progressive loading tools。
Tool-Mediated Action System	向 agent 暴露受控动作。	带权限 metadata 和 event logging 的 Pydantic AI toolsets。
Memory-Aware Context System	不绑定后端地 recall/write memory。	External memory tool contract + pre-run recall hook + candidate writeback。
Sandbox-First Work Execution	持久化工作、日志和交付物。	标准化 per-run local directory + path guards。
Quality and Governance System	执行最小正确性和安全约束。	Required deliverable checks、safe tool defaults、explicit records，后续 validation hooks。
Professional Workflow Orchestration	不引入重图的情况下表达阶段和 handoff。	后续使用 lightweight stage state 和 artifact contracts。
Learning and Capability Evolution	将 runs 转成候选复用资产。	先做 session archives，后续做 candidate skills/memories。

质量/成本平衡

kgent 应优化“每一份工程成本带来的可靠性”。

早期应投入的地方

早期投入稳定边界：

typed config models
run directory layout
skill package format
memory tool contract
event schema
filesystem path safety
prompt composition

这些内容早期投入成本较低，但后期修改成本高。

Phase 1 应保持轻量的地方

不做完整 workflow graph。
不做完整 multi-agent scheduler。
不做生产级 skill marketplace。
不内建 memory database。
不开放广泛 shell execution。
不做 GUI。

这些能力可以后续增加，不阻塞核心价值验证。

应使用外部系统的地方

当外部系统已经更好或已经被拥有时，kgent 应集成而不是自建：

memory backend
search providers
model providers
optional MCP tools
future artifact publishing or storage

Runtime 边界

运行时只协调一次 run。

它应负责：

load config
create sandbox
build context
create Pydantic AI agent
register tools
run task
record events
validate minimal deliverables
archive session

它不应负责：

拥有 memory database
硬编码领域工作流
隐藏工具执行
未经审查自动修改技能
Phase 1 要求分布式服务架构

Skill 边界

技能承载领域知识和工作方法。

运行时不应直接知道旅行规划、课程设计或视频节目设计。

Runtime = stable execution substrate
Skill = professional domain capability
Profile = role and responsibility
Tool = executable action

这样 kgent 能以较低成本扩展。

Memory 边界

记忆应被视为依赖，而不是内部数据库。

Phase 1 定义稳定契约：

recall_memory(query, scope, limit)
write_memory(content, scope, tags)

实际持久化、排序、去重、保留和治理可以在 kgent 外部，或后续再加入。

Sandbox 边界

沙箱是主要质量和审计机制。

它应保持简单：

runs/&lt;run-id&gt;/
  prompt.md
  config.yaml
  effective-system-prompt.md
  events.jsonl
  transcript.md
  workspace/
  deliverables/
  archive/
  logs/

文件系统工具必须通过 path guards 操作。模型永远不应获得不受限制的文件访问。

Governance 边界

质量和治理从最小可执行保障开始：

safe tool defaults
path restrictions
required deliverable checks
explicit run records
no automatic skill activation
no unrestricted shell by default

后续逐步增加：

reviewer agents
validation hooks
skill review status
memory write review
evaluation harness

性能策略

kgent 的主要性能风险不是 Python 函数调用，而是模型延迟、工具延迟、上下文大小、文件操作、记忆召回、沙箱创建、artifact IO 和并发 run 隔离。

策略是保持 runtime 轻量、减少不必要上下文，并将高成本能力放到清晰接口后。

Phase 1 性能基线

progressive skill loading，不加载所有技能。
pre-run memory summarization，不把原始历史塞满上下文。
bounded file reads。
明确 max file size limits。
append-only JSONL event logging。
默认不开广泛 shell execution。
不引入重型 workflow graph。
不要求 always-on daemon。

性能关键路径

关键路径	重要性	设计侧重
Context assembly	直接影响 token 成本和模型延迟。	使用 summaries、indexes、progressive loading。
Skill discovery/loading	随技能库增长而变慢。	先加载 metadata，仅按需加载完整技能。
Memory recall	随记忆增长可能变慢、变噪。	使用 scoped recall、top-k limits、summaries 和外部服务边界。
Filesystem reads/search	专业任务可能检查大量文件或 artifacts。	bounded reads、grep/glob tools、file size limits，后续 indexing。
Tool execution	慢工具或失败工具会主导 run latency。	记录 duration、分类失败、保持可观测。
Sandbox creation/restoration	并行 run、revision 和未来调度都需要。	确定性 run layout、config snapshots、artifact manifests。
Event/artifact writing	每次 run 都写持久记录。	Phase 1 使用 append-only JSONL 和简单文件 artifacts。
Model streaming	影响感知延迟。	可行时优先 streaming。

设计后果

skill packages 必须支持 metadata-only indexing。
memory integration 必须支持 scoped、bounded recall。
tools 必须发出 duration 和 failure events。
filesystem tools 必须强制 file size 和 path limits。
run records 必须 append-friendly。
sandbox state 必须能从 artifacts 重建。
高成本能力应位于未来可服务化的接口后。

并发和规模策略

Phase 1 是本地 CLI runtime，但设计上不能阻碍未来高并发。

关键决策：

One run = one isolated run directory + one run id + one config snapshot + one event stream

这样并发问题会变成调度问题，而不是 agent 设计问题。

并发模型

Run
  isolated sandbox
  immutable input snapshot
  append-only events
  explicit state file
  deliverables

只要不共享可写 sandbox，多个 run 就可以并行执行。

调度就绪性

调度预计会成为 kgent 未来最重要的能力之一。

高并发、多任务执行、角色分配、环境重建、重试、修订和长任务都应被视为调度问题。

Phase 1 不做完整 scheduler，但必须创建 scheduler 所需的底座。

未来 Scheduler 职责

run queueing
worker assignment
role/profile selection
task dependency handling
parallel task execution
sandbox allocation
environment reconstruction
retry and revision runs
cancellation and timeout
resource quotas
model/provider rate-limit coordination
run state transitions
artifact handoff between agents

现在必须建立的调度底座

底座	作用
`session_id`	归组相关任务和修订。
`task_id`	标识可独立调度的工作单元。
`run_id`	标识一次执行尝试。
run state file	让未来 scheduler 检查和恢复工作。
immutable config snapshot	让 run 可复现。
sandbox manifest	让环境可重建。
artifact manifest	让输入输出可交接。
append-only events	支持监控、回放和恢复。
explicit tool permissions	让 scheduler 可将任务放到兼容 worker。
profile id and skill ids	支持基于角色和能力路由。

面向调度的 Run State

即使 scheduler 还不存在，run state 也应按未来调度需要设计：

pending
running
waiting_for_tool
waiting_for_user
review_required
revision_required
completed
failed
cancelled

Phase 1 可只使用子集，但状态模型不能阻碍这些未来状态。

环境重建

环境重建应视为 scheduler 职责。

未来 scheduler 应能从以下信息重建 run context：

config snapshot
profile id
skill ids and versions
memory recall summary
sandbox manifest
artifact manifest
prior run summaries
review reports
event log

这也是为什么持久 artifacts 比内存 conversation history 更重要。

多任务、角色和会话模型

不同角色、任务和会话必须显式建模，这是多任务并行执行的基础。

核心运行时身份

agent_profile_id
  使用哪个专业身份。

task_id
  正在执行什么工作。

session_id
  连续交互或工作线程。

run_id
  一次具体执行尝试。

workspace_id
  与工作关联的沙箱或 artifact workspace。

关系

Session
  -> one or more Tasks
      -> one or more Runs
          -> one Run Sandbox

示例：

一个 Intake Agent 对话是一个 session，包含多次澄清 runs。
一个旅行规划任务可能包含一次 worker run 和一次 reviewer run。
审查失败后，可在同一 session 中创建 revision run。
多个 worker agents 可在同一 coordinator session 下并行运行不同任务。

角色处理

角色由 profile 表达，而不是硬编码类。

Profile = role + responsibilities + style + constraints + default skills + default deliverables

这样无需改 runtime 就能创建不同 worker：

intake specialist
travel planner
course designer
video program designer
researcher
reviewer

任务处理

任务应由结构化 artifacts 表达。

早期 artifacts：

idea_brief.yaml
task_plan.yaml
worker_result.yaml
review_report.yaml

这样多个任务可以并行运行，并保持可检查、可恢复。

会话处理

Session 是连续性的边界。

它应保留：

user intent
selected profile
task artifacts
run summaries
memory recalls
review feedback
revision history

Session 不应要求模型上下文保存所有内容，而应从 artifacts 和 summaries 重建。

修订和返工策略

当质量不合格时，kgent 不应从零开始。

它应在同一 session 中创建新的 run，并使用：

original prompt or brief
previous deliverables
review findings
run summary
relevant events or transcript excerpts
same or updated profile and skills

返工流程

Worker Run
  -> deliverables
  -> Reviewer Run
  -> review_report.yaml
  -> quality failed
  -> Revision Run in same session
  -> updated deliverables
  -> Reviewer Run

上下文重建

Revision run 应从持久 artifacts 重建上下文：

session state
original brief
previous final deliverables
review findings
run summary
selected skill summaries
relevant memory

这避免依赖内存中的 conversation buffer。

Phase 1 最小要求

Phase 1 不需要完整 rework orchestration，但必须保存足够数据：

stable run_id
optional session_id
copied input prompt/config
transcript
event log
final deliverables
run summary

Phase 2 可增加：

kgent revise
review report ingestion
revision run creation
session state file
artifact diffing

状态模型建议

使用 durable state，而不是进程内存，作为 source of truth。

session.json
task.yaml
run.json
events.jsonl
deliverables/
archive/session-summary.md

这让 kgent 能从本地 CLI 平滑演进到高并发服务运行，也让 run 可检查、可恢复、可调试。

Phase 1 技术验收标准

Phase 1 满足整体技术设计的条件：

Run 具备稳定标识：session_id、task_id、run_id。
Run 创建隔离 sandbox，并使用确定性 layout。
输入 config 被校验并复制到 run 目录。
Effective system prompt 被渲染并归档。
Skills 先通过 metadata 发现，再加载完整内容。
Agent 可以按需加载选中技能。
Tools 通过显式 toolsets 注册。
Filesystem tools 强制 sandbox path boundaries。
Memory 通过外部 recall/write contract 访问。
Events 以 append-only JSONL 写入。
Transcript 以人类可读 artifact 写入。
运行结束检查必需交付物。
工具权限具备安全默认值。
Run state 足以支撑未来调度和 revision。

这些验收标准是架构性的，不要求丰富领域技能、多智能体编排或分布式 scheduler。

特性实现设计入口

下一阶段按以下顺序设计 Phase 1 能力：

Project and package structure：模块、依赖、CLI entry point 和测试布局。
Config and profile model：typed config、profile 字段和 prompt rendering。
Run and sandbox model：run ids、session/task ids、目录布局、状态文件和 manifests。
Event and transcript recording：event types、JSONL、transcript 和 tool log 边界。
Skill registry：skill metadata、discovery、progressive loading 和 load-skill tool。
Tool system：filesystem tools、memory tools、permission metadata 和 tool event logging。
Pydantic AI runtime adapter：构建和调用 Pydantic AI agent，同时不把产品概念泄漏到 engine layer。
Minimal governance：安全默认、必需交付物检查和失败报告。

这个顺序先建设稳定底座，再建设 agent 行为。

特性设计阶段待回答问题

以下问题在实现设计阶段回答，而不在整体架构中展开：

Phase 1 应锁定哪个 Pydantic AI 版本和 API？
Filesystem tools 第一版使用第三方 Pydantic AI sandbox 包，还是 kgent-native 小实现？
kgent.yaml 的精确 YAML schema 是什么？
Phase 1 交付物校验应有多严格？
最小 event schema 是什么？
记忆契约如何最适配现有记忆系统？
在 kgent intake 出现之前，kgent run 应支持多少交互性？

技术基线冻结

除非显式重开讨论，下一阶段冻结以下边界：

kgent Phase 1 是 CLI-first。
Pydantic AI 是 agent execution engine。
Runtime local-first，但 scheduler-ready。
Runs durable、sandboxed、artifact-based。
Memory 外部化，通过显式 contracts 访问。
Skills 是 filesystem packages，并支持 progressive loading。
Tools 显式、受权限控制、可观测。
性能通过 context discipline、bounded IO 和 service-ready interfaces 管控。
调度就绪性通过 stable IDs、run state、manifests 和 append-only events 实现。
Quality/Governance 从最小可执行检查开始。

来源项目	`kunora-kgent`
分支	`docs-publish`
路径	`technology/components/kunora-kgent/technical-design.md`

设计目标​

技术设计原则​

关键技术选择​

架构决策​

架构策略​

技术能力地图​

质量/成本平衡​

早期应投入的地方​

Phase 1 应保持轻量的地方​

应使用外部系统的地方​

Runtime 边界​

Skill 边界​

Memory 边界​

Sandbox 边界​

Governance 边界​

性能策略​

Phase 1 性能基线​

性能关键路径​

设计后果​

并发和规模策略​

并发模型​

调度就绪性​

未来 Scheduler 职责​

现在必须建立的调度底座​

面向调度的 Run State​

环境重建​

多任务、角色和会话模型​

核心运行时身份​

关系​

角色处理​

任务处理​

会话处理​

修订和返工策略​

返工流程​

上下文重建​

Phase 1 最小要求​

状态模型建议​

Phase 1 技术验收标准​

特性实现设计入口​

特性设计阶段待回答问题​

技术基线冻结​