工具系统（Tool System）

目标关联

该特性支撑专业工作执行、可审计交付、上下文连续性和专业可靠性。

实现的关键特性：

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

技术设计对齐

工具必须显式、可观测、受权限控制。工具通过 Pydantic AI toolsets 注册，危险能力默认禁用，filesystem tools 只能通过 sandbox path guards 操作，memory 通过外部 contract 访问。

范围

Phase 1 包含 filesystem read/write tools、skill tools、memory tools、tool permission metadata、tool call logging、path boundary checks 和 result summaries。

排除 unrestricted shell、browser automation、desktop automation、complex approval workflow、MCP hosting、tool marketplace。

概念模型

Tool
  name
  description
  input schema
  permission metadata
  runtime handler
  event logging

Toolset
  a group of related tools

PermissionPolicy
  decides whether a tool call is allowed

Phase 1 toolsets：

FilesystemToolset
SkillToolset
MemoryToolset

接口

Filesystem：

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

Skills：

list_skills()
load_skill(skill_id)

Memory：

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

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 需要显式 config enablement，后续还需要 approval support。

Memory Write Mode

memory:
  enabled: true
  provider: external
  write_mode: candidate

允许模式：

• disabled：write_memory 不可用。
• candidate：写入 run archive 的候选记忆。
• external：调用外部记忆系统。

Phase 1 默认 candidate。

Tool Result Summary Contract

ToolResult
  ok
  summary
  data
  artifacts
  error

大型 data 不应直接写入日志，应写为 artifacts 并返回引用。

运行时行为

Runtime 根据 config 创建 permission policy 和 toolsets。Tool wrapper 在执行前检查权限，发出 tool.started，执行后发出 tool.completed 或 tool.failed，并对结果做摘要。

产物

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

质量和治理

• 默认拒绝 destructive operations。
• 默认拒绝 shell。
• 拒绝 sandbox 外写入。
• 记录所有 tool calls。
• 大型输出摘要。
• permission rejection 清晰失败。
• memory write 使用 candidate 或显式 external call。

性能和调度考虑

文件读取有边界；大型输出摘要；记录 duration；tools 尽量 stateless。未来 scheduler 可根据 tool permissions 进行 worker placement，并通过 tool events 做监控和 retry analysis。

验收标准

1. Runtime 从 config 构建 toolsets。
2. Filesystem tools 强制 sandbox boundaries。
3. Skill tools 暴露 list/load。
4. Memory tools 使用 external contract。
5. Tool calls 记录 duration 和 status。
6. Permission rejections 显式。
7. Dangerous tools 默认禁用。
8. 大型输出默认摘要。
9. Tool behavior 可脱离模型测试。
10. Effective permission policy 显式计算。
11. Memory write mode 显式，默认 candidate。