Tools 与 Memory 模块详细设计

本文档展开 kgent/tools/ 和 kgent/memory/ 的代码设计。

Tools 模块负责向 agent 暴露显式、受权限控制、可观测的动作。Memory 模块负责通过外部 contract 接入长期上下文。

目标关联

该设计支撑：

• Tool-Mediated Action System
• Memory-Aware Context System
• Sandbox-First Work Execution
• Quality and Governance System

模块范围

Tools 包含：

• tool registry。
• filesystem tools。
• skill tools 包装。
• memory tools 包装。
• permission policy。
• tool result contract。
• tool call logging。

Memory 包含：

• memory contract。
• default no-op 或 candidate client。
• external client interface。
• write mode 行为。

不包含：

• 不受限制的 shell。
• browser automation。
• MCP hosting。
• 内建 memory database。
• 复杂 approval workflow。

文件结构

src/kgent/tools/
  __init__.py
  registry.py
  filesystem.py
  skills.py
  memory.py
  permissions.py
  results.py
  pydantic_adapter.py

src/kgent/memory/
  __init__.py
  contract.py
  client.py

数据模型

ToolResult

位置：tools/results.py

class ToolResult:
    ok: bool
    summary: str
    data: dict | None
    artifacts: list[str]
    error: ErrorInfo | None

要求：

• summary 必须短且可写入日志。
• 大型内容写 artifact。
• error 使用统一 ErrorInfo。

Tool Protocol

位置：tools/registry.py

class ToolDefinition:
    name: str
    description: str
    input_schema: dict
    handler: ToolHandler

class ToolHandler:
    def __call__(self, args: dict, context: RunContext) -> ToolResult:
        ...

要求：

• ToolDefinition 是 kgent-native 工具定义，不绑定 Pydantic AI。
• ToolHandler 统一接收结构化参数和 RunContext。
• ToolHandler 只能通过 sandbox、permission、memory client 等受控接口完成动作。
• ToolHandler 返回 ToolResult，不直接返回 provider-specific 对象。

Permission Models

位置：tools/permissions.py

class EffectivePermissionPolicy:
    filesystem_read: bool
    filesystem_write: bool
    filesystem_delete: bool
    shell: bool
    network: bool
    memory_write: bool

class PermissionResult:
    allowed: bool
    reason: str | None
    error: ErrorInfo | None

Effective Permission Policy

权限合并规则：

EffectivePermissionPolicy =
  runtime safe defaults
  + config tool permissions
  + loaded skill permission declarations
  + sandbox constraints

规则：

1. Runtime deny rules 永远优先。
2. Sandbox path constraints 永远优先。
3. Config 可以启用安全能力。
4. Skill permissions 只能请求能力，不能单独授权。
5. Destructive operations 在 Phase 1 默认禁用。

Filesystem Tools

位置：tools/filesystem.py

Agent-facing tools：

read_file(path)
write_file(path, content)
list_files(path)
grep_files(pattern, path)

实现要求：

• 所有 path 通过 resolve_sandbox_path。
• read_file 受 max_file_bytes 限制。
• write_file 只写允许目录。
• Phase 1 不实现 delete。
• grep_files 必须限制扫描范围和返回大小。
• 所有工具返回 ToolResult。
• 所有工具调用写 ToolCallRecord。

Skill Tools

位置：tools/skills.py

Agent-facing tools：

list_skills()
load_skill(skill_id)

实现要求：

• 委托 SkillRegistry。
• 不绕过 loaded skill budget。
• load_skill 返回摘要和正文，不直接授予权限。
• 写入 skill.loaded event。

Memory Contract

位置：memory/contract.py

class MemoryItem:
    id: str
    content: str
    scope: str
    score: float | None
    metadata: dict

class MemoryWriteResult:
    status: str
    id: str | None
    error: ErrorInfo | None

class MemoryClient:
    def recall_memory(self, query: str, scope: str, limit: int) -> list[MemoryItem]:
        ...

    def write_memory(self, content: str, scope: str, tags: list[str]) -> MemoryWriteResult:
        ...

Memory Tools

位置：tools/memory.py

Agent-facing tools：

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

write_mode 行为：

• disabled：不注册 write_memory 或返回 blocked。
• candidate：写入 archive/candidate-memory.jsonl。
• external：调用外部 MemoryClient。

Phase 1 默认 candidate。

Tool Registry

位置：tools/registry.py

def build_toolsets(
    context: RunContext,
    skills: SkillRegistry,
    memory: MemoryClient,
    policy: EffectivePermissionPolicy,
) -> list[ToolDefinition]:
    ...

build_toolsets 返回 kgent-native ToolDefinition 列表。

Pydantic AI 适配必须隔离在：

tools/pydantic_adapter.py

该 adapter 负责将 kgent-native tools 包装成 Pydantic AI 可接受的 tool/toolset 对象。通用 tools 不直接依赖 Pydantic AI。

运行时行为

1. Runtime 根据 config 和 loaded skills 构建 EffectivePermissionPolicy。
2. Tool registry 创建 toolsets。
3. Engine 接收 kgent-native tools，并在 Pydantic AI adapter 内完成转换。
4. 每次工具调用先检查 permission。
5. 工具执行后返回 ToolResult。
6. ToolLogger 记录 ToolCallRecord。
7. EventRecorder 记录 tool events。

产物

runs/<run-id>/logs/tools.jsonl
runs/<run-id>/events.jsonl
runs/<run-id>/workspace/
runs/<run-id>/deliverables/
runs/<run-id>/archive/candidate-memory.jsonl

测试设计

单元测试：

• runtime deny rules win。
• sandbox constraints win。
• skill permissions cannot grant alone。
• filesystem read obeys max bytes。
• write outside sandbox is blocked。
• write under deliverables succeeds。
• grep returns bounded output。
• memory write disabled returns blocked。
• memory candidate mode writes archive file。
• tool call record contains duration/status/summary。

集成测试：

• minimal run can write deliverable through filesystem tool。
• tool rejection writes event and error log。
• candidate memory file is generated when memory tool writes。

性能和调度考虑

• 工具必须 stateless 或仅持有 RunContext。
• 大型输出必须 artifact 化。
• tool duration 是性能观测基础。
• permission policy 可用于未来 worker placement。
• memory client 是外部边界，未来可替换为服务调用。

验收标准

1. Tools 可从 config 构建为 ToolDefinition 列表。
2. Filesystem tools 被 sandbox path guard 保护。
3. Memory tools 支持 disabled、candidate、external。
4. Permission policy 合并规则可测试。
5. Tool calls 完整记录。
6. 大型输出不直接进入 logs/events。
7. 通用 tools 不直接依赖 Pydantic AI，Pydantic 适配位于 tools/pydantic_adapter.py。