---
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，建立项目骨架。