大森
6b94476347
Core features: - Microkernel architecture with Actor model - Session management with JSONL persistence - Tool system (5 built-in tools) - Skill system with SKILL.md parsing - Sandbox security execution - Ollama integration with gemma4:e4b - Prompt-based tool calling (compatible with native function calling) - REPL interface 11 packages, all tests passing
374 lines
9.6 KiB
Markdown
374 lines
9.6 KiB
Markdown
---
|
||
date: 2026-05-07
|
||
topic: "Go Agent Framework - Orca"
|
||
status: draft
|
||
---
|
||
|
||
# Orca Agent Framework - 实现计划
|
||
|
||
## 项目概览
|
||
|
||
- **项目名称:** orca
|
||
- **语言:** Go 1.22+
|
||
- **路径:** /Users/wang/agent_dev/orca.ai/
|
||
- **架构:** 微内核 + Actor 模型
|
||
|
||
## 实现阶段
|
||
|
||
### Phase 1: 项目骨架与核心基础设施（Day 1）
|
||
|
||
**目标:** 建立项目结构，实现消息总线和插件注册机制。
|
||
|
||
**任务清单:**
|
||
|
||
1. **初始化 Go 模块**
|
||
- `go mod init github.com/orca/orca`
|
||
- 创建基础目录结构
|
||
|
||
2. **目录结构**
|
||
```
|
||
orca/
|
||
├── cmd/orca/ # CLI 入口
|
||
├── pkg/
|
||
│ ├── kernel/ # 微内核核心
|
||
│ ├── actor/ # Actor 系统
|
||
│ ├── bus/ # 消息总线
|
||
│ ├── plugin/ # 插件接口和注册
|
||
│ ├── session/ # 会话管理 (JSONL)
|
||
│ ├── skill/ # Skill 管理
|
||
│ ├── tool/ # Tool 系统
|
||
│ ├── llm/ # LLM 接口
|
||
│ ├── ollama/ # Ollama 驱动
|
||
│ └── sandbox/ # 沙箱执行
|
||
├── internal/
|
||
│ ├── config/ # 配置管理
|
||
│ └── util/ # 工具函数
|
||
├── plugins/
|
||
│ ├── builtin/ # 内置插件
|
||
│ └── tools/ # 内置工具
|
||
├── test/
|
||
│ └── fixtures/ # 测试固件
|
||
└── go.mod
|
||
```
|
||
|
||
3. **核心接口定义**
|
||
- `pkg/plugin/plugin.go`: Plugin 接口
|
||
- `pkg/bus/bus.go`: MessageBus 接口和实现
|
||
- `pkg/kernel/kernel.go`: Kernel 结构体，插件生命周期管理
|
||
|
||
4. **消息总线实现**
|
||
- 基于 Go channel 的发布/订阅
|
||
- 支持同步和异步消息
|
||
- 消息类型枚举定义
|
||
|
||
**验收标准:**
|
||
- `go build ./...` 成功
|
||
- 消息总线单元测试通过（Publish/Subscribe）
|
||
- 插件注册/卸载测试通过
|
||
|
||
---
|
||
|
||
### Phase 2: Actor 系统与会话管理（Day 2）
|
||
|
||
**目标:** 实现多 Agent Actor 和 JSONL 会话存储。
|
||
|
||
**任务清单:**
|
||
|
||
1. **Actor 系统**
|
||
- `pkg/actor/actor.go`: Agent Actor 接口
|
||
- `pkg/actor/orchestrator.go`: 协调者 Agent
|
||
- `pkg/actor/worker.go`: 工作者 Agent
|
||
- `pkg/actor/system.go`: Actor 生命周期管理（创建、停止、监控）
|
||
- 状态机实现：Idle → Processing → WaitingForTool → Completed/Failed
|
||
|
||
2. **会话管理（JSONL）**
|
||
- `pkg/session/store.go`: 存储接口
|
||
- `pkg/session/jsonl.go`: JSONL 实现
|
||
- `pkg/session/manager.go`: 会话管理器（创建、加载、归档）
|
||
- 上下文窗口截断逻辑
|
||
- 文件锁保证并发安全（`flock` 或简单文件锁）
|
||
|
||
3. **配置系统**
|
||
- `internal/config/config.go`: 配置结构体
|
||
- 支持 YAML 配置文件（`~/.orca/config.yaml`）
|
||
- 环境变量覆盖
|
||
- 默认值设置
|
||
|
||
**验收标准:**
|
||
- 创建 10 个 Agent Actor 并发运行测试通过
|
||
- 会话 CRUD 测试通过
|
||
- 上下文窗口截断测试通过
|
||
|
||
---
|
||
|
||
### Phase 3: Skill 与 Tool 系统（Day 3）
|
||
|
||
**目标:** 实现 Skill 自动发现和 Tool 注册执行。
|
||
|
||
**任务清单:**
|
||
|
||
1. **Skill 管理器**
|
||
- `pkg/skill/manager.go`: Skill 扫描和加载
|
||
- `pkg/skill/parser.go`: SKILL.md 解析器（提取 name, description, triggers）
|
||
- `pkg/skill/skill.go`: Skill 结构体定义
|
||
- 扫描目录：`~/.agents/skills/` 和 `~/.config/opencode/skills/`
|
||
- 触发词匹配算法（简单关键词匹配或 TF-IDF）
|
||
|
||
2. **Tool 系统**
|
||
- `pkg/tool/tool.go`: Tool 接口定义
|
||
- `pkg/tool/manager.go`: Tool 注册中心
|
||
- `pkg/tool/registry.go`: 内置工具注册
|
||
- **内置工具实现:**
|
||
- `exec`: 执行 shell 命令（通过 sandbox）
|
||
- `read_file`: 读取文件内容
|
||
- `write_file`: 写入文件
|
||
- `list_dir`: 列出目录
|
||
- `search_files`: 文件内容搜索
|
||
|
||
3. **自定义 Tool 注册**
|
||
- 支持通过代码注册 Tool
|
||
- Tool 参数 Schema 定义（简化版 JSON Schema）
|
||
- Tool 执行上下文传递
|
||
|
||
**验收标准:**
|
||
- 扫描现有 `~/.agents/skills/` 目录，正确解析所有 Skill
|
||
- 触发词匹配测试通过
|
||
- 所有内置工具单元测试通过
|
||
|
||
---
|
||
|
||
### Phase 4: 沙箱与 Ollama 集成（Day 4）
|
||
|
||
**目标:** 实现安全执行环境和 LLM 驱动。
|
||
|
||
**任务清单:**
|
||
|
||
1. **沙箱执行器**
|
||
- `pkg/sandbox/sandbox.go`: Sandbox 接口
|
||
- `pkg/sandbox/process.go`: 进程级实现
|
||
- 资源限制：
|
||
- 超时控制（context.WithTimeout）
|
||
- 内存限制（通过 cgroup 或 ulimit，若不可用则软限制）
|
||
- 输出大小限制
|
||
- 工作目录隔离
|
||
- 环境变量白名单
|
||
- 危险命令黑名单
|
||
|
||
2. **Ollama 驱动**
|
||
- `pkg/ollama/client.go`: HTTP 客户端
|
||
- `pkg/ollama/chat.go`: Chat API 封装
|
||
- `pkg/ollama/stream.go`: 流式响应处理（SSE）
|
||
- `pkg/ollama/tools.go`: Function Calling 支持
|
||
- 模型配置：temperature、top_p、max_tokens
|
||
- 自动重试机制（指数退避，3 次）
|
||
|
||
3. **LLM 抽象层**
|
||
- `pkg/llm/client.go`: LLMClient 接口
|
||
- `pkg/llm/message.go`: Message 结构体定义
|
||
- `pkg/llm/options.go`: 调用选项
|
||
|
||
**验收标准:**
|
||
- 沙箱执行命令并正确限制资源测试通过
|
||
- 超时和内存限制测试通过
|
||
- Ollama API 调用测试通过（需要本地 Ollama 服务）
|
||
- Function Calling 格式正确
|
||
|
||
---
|
||
|
||
### Phase 5: CLI 与集成（Day 5）
|
||
|
||
**目标:** 实现命令行界面和端到端集成。
|
||
|
||
**任务清单:**
|
||
|
||
1. **CLI 实现**
|
||
- `cmd/orca/main.go`: 入口点
|
||
- `cmd/orca/commands.go`: 子命令定义
|
||
- 支持命令：
|
||
- `orca chat`: 交互式对话
|
||
- `orca run "query"`: 单次执行
|
||
- `orca sessions`: 会话列表
|
||
- `orca skills`: 已加载 Skill 列表
|
||
- `orca tools`: 已注册 Tool 列表
|
||
- `orca config`: 配置查看/设置
|
||
|
||
2. **交互式对话**
|
||
- 读取用户输入
|
||
- 创建/恢复会话
|
||
- 调用 Orchestrator Agent
|
||
- 显示 Agent 思考过程和结果
|
||
- 支持多轮对话
|
||
|
||
3. **端到端集成测试**
|
||
- 完整对话流程测试
|
||
- Skill 触发和调用测试
|
||
- Tool 调用链测试
|
||
- 错误恢复测试
|
||
|
||
**验收标准:**
|
||
- `orca --help` 显示正确
|
||
- `orca chat` 可以开始对话
|
||
- 完整对话流程测试通过
|
||
|
||
---
|
||
|
||
### Phase 6: 多 Agent 协作与优化（Day 6-7）
|
||
|
||
**目标:** 实现多 Agent 协作和性能优化。
|
||
|
||
**任务清单:**
|
||
|
||
1. **多 Agent 协作**
|
||
- Orchestrator 任务分解逻辑
|
||
- Worker Agent 分配策略
|
||
- Agent 间消息传递
|
||
- 结果汇总和冲突解决
|
||
|
||
2. **性能优化**
|
||
- 会话缓存（最近 N 个会话驻留内存）
|
||
- Skill 索引（倒排索引加速匹配）
|
||
- 连接池（Ollama HTTP 连接复用）
|
||
|
||
3. **可观测性**
|
||
- 结构化日志（slog）
|
||
- Agent 执行追踪
|
||
- 性能指标收集
|
||
|
||
**验收标准:**
|
||
- 多 Agent 协作测试通过
|
||
- 性能基准测试通过（单次对话 < 5s）
|
||
|
||
---
|
||
|
||
## 依赖管理
|
||
|
||
### 外部依赖（最小化）
|
||
|
||
| 依赖 | 用途 | 版本 |
|
||
|------|------|------|
|
||
| `github.com/spf13/cobra` | CLI 框架 | latest |
|
||
| `github.com/spf13/viper` | 配置管理 | latest |
|
||
| `github.com/stretchr/testify` | 测试 | latest |
|
||
|
||
**原则:** 优先使用标准库，必要时才引入外部依赖。
|
||
|
||
### 内部依赖图
|
||
|
||
```
|
||
kernel
|
||
├── bus
|
||
├── plugin
|
||
├── actor
|
||
│ ├── bus
|
||
│ ├── tool
|
||
│ └── llm
|
||
├── session
|
||
├── skill
|
||
├── tool
|
||
│ └── sandbox
|
||
├── llm
|
||
│ └── ollama
|
||
└── sandbox
|
||
```
|
||
|
||
## 关键接口定义
|
||
|
||
### Plugin 接口
|
||
|
||
```go
|
||
type Plugin interface {
|
||
Name() string
|
||
Version() string
|
||
Init(kernel *Kernel) error
|
||
Shutdown() error
|
||
}
|
||
```
|
||
|
||
### Agent 接口
|
||
|
||
```go
|
||
type Agent interface {
|
||
ID() string
|
||
Role() string
|
||
Process(ctx context.Context, msg Message) (Message, error)
|
||
Stop() error
|
||
}
|
||
```
|
||
|
||
### Tool 接口
|
||
|
||
```go
|
||
type Tool interface {
|
||
Name() string
|
||
Description() string
|
||
Parameters() ParameterSchema
|
||
Execute(ctx context.Context, args map[string]interface{}) (ToolResult, error)
|
||
}
|
||
```
|
||
|
||
### LLMClient 接口
|
||
|
||
```go
|
||
type LLMClient interface {
|
||
Chat(ctx context.Context, messages []Message, tools []Tool) (*ChatResponse, error)
|
||
ChatStream(ctx context.Context, messages []Message, tools []Tool) (StreamReader, error)
|
||
}
|
||
```
|
||
|
||
## 测试策略
|
||
|
||
### 单元测试覆盖目标
|
||
|
||
| 模块 | 覆盖率目标 |
|
||
|------|-----------|
|
||
| bus | 90% |
|
||
| kernel | 85% |
|
||
| session | 90% |
|
||
| skill | 85% |
|
||
| tool | 90% |
|
||
| sandbox | 80% |
|
||
| ollama | 75% (mock) |
|
||
|
||
### Mock 实现
|
||
|
||
```go
|
||
// MockLLMClient 用于测试
|
||
type MockLLMClient struct {
|
||
Responses []ChatResponse
|
||
Index int
|
||
}
|
||
|
||
func (m *MockLLMClient) Chat(ctx context.Context, messages []Message, tools []Tool) (*ChatResponse, error) {
|
||
if m.Index >= len(m.Responses) {
|
||
return nil, errors.New("no more mock responses")
|
||
}
|
||
resp := m.Responses[m.Index]
|
||
m.Index++
|
||
return &resp, nil
|
||
}
|
||
```
|
||
|
||
## 风险与回退方案
|
||
|
||
| 风险 | 影响 | 概率 | 回退方案 |
|
||
|------|------|------|----------|
|
||
| gemma4:e4b 不支持 Function Calling | 高 | 中 | 使用 prompt-based tool calling |
|
||
| 进程级沙箱限制不足 | 中 | 低 | 添加 Docker 支持作为可选 |
|
||
| JSONL 性能瓶颈 | 中 | 低 | 迁移到 SQLite（保留接口） |
|
||
| Actor 模型复杂度 | 中 | 中 | 简化中央协调器模式 |
|
||
|
||
## 里程碑
|
||
|
||
| 里程碑 | 时间 | 交付物 |
|
||
|--------|------|--------|
|
||
| M1 | Day 1 | 项目骨架 + 消息总线 + 插件系统 |
|
||
| M2 | Day 2 | Actor 系统 + 会话管理 |
|
||
| M3 | Day 3 | Skill + Tool 系统 |
|
||
| M4 | Day 4 | 沙箱 + Ollama 集成 |
|
||
| M5 | Day 5 | CLI + 端到端集成 |
|
||
| M6 | Day 6-7 | 多 Agent + 优化 |
|
||
|
||
## 下一步
|
||
|
||
执行 Phase 1，建立项目骨架。
|