大森 6b94476347 Initial commit: Orca Agent Framework

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

2026-05-08 00:55:48 +08:00

9.6 KiB

Raw Blame History

date, topic, status

date	topic	status
2026-05-07	Go Agent Framework - Orca	draft

Orca Agent Framework - 实现计划

项目概览

项目名称: orca
语言: Go 1.22+
路径: /Users/wang/agent_dev/orca.ai/
架构: 微内核 + Actor 模型

实现阶段

Phase 1: 项目骨架与核心基础设施（Day 1）

目标: 建立项目结构，实现消息总线和插件注册机制。

任务清单:

初始化 Go 模块
- go mod init github.com/orca/orca
- 创建基础目录结构

目录结构

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

核心接口定义
- pkg/plugin/plugin.go: Plugin 接口
- pkg/bus/bus.go: MessageBus 接口和实现
- pkg/kernel/kernel.go: Kernel 结构体，插件生命周期管理
消息总线实现
- 基于 Go channel 的发布/订阅
- 支持同步和异步消息
- 消息类型枚举定义

验收标准:

go build ./... 成功
消息总线单元测试通过（Publish/Subscribe）
插件注册/卸载测试通过

Phase 2: Actor 系统与会话管理（Day 2）

目标: 实现多 Agent Actor 和 JSONL 会话存储。

任务清单:

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
会话管理（JSONL）
- pkg/session/store.go: 存储接口
- pkg/session/jsonl.go: JSONL 实现
- pkg/session/manager.go: 会话管理器（创建、加载、归档）
- 上下文窗口截断逻辑
- 文件锁保证并发安全（flock 或简单文件锁）
配置系统
- internal/config/config.go: 配置结构体
- 支持 YAML 配置文件（~/.orca/config.yaml）
- 环境变量覆盖
- 默认值设置

验收标准:

创建 10 个 Agent Actor 并发运行测试通过
会话 CRUD 测试通过
上下文窗口截断测试通过

Phase 3: Skill 与 Tool 系统（Day 3）

目标: 实现 Skill 自动发现和 Tool 注册执行。

任务清单:

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）
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: 文件内容搜索
自定义 Tool 注册
- 支持通过代码注册 Tool
- Tool 参数 Schema 定义（简化版 JSON Schema）
- Tool 执行上下文传递

验收标准:

扫描现有 ~/.agents/skills/ 目录，正确解析所有 Skill
触发词匹配测试通过
所有内置工具单元测试通过

Phase 4: 沙箱与 Ollama 集成（Day 4）

目标: 实现安全执行环境和 LLM 驱动。

任务清单:

沙箱执行器
- pkg/sandbox/sandbox.go: Sandbox 接口
- pkg/sandbox/process.go: 进程级实现
- 资源限制：
  - 超时控制（context.WithTimeout）
  - 内存限制（通过 cgroup 或 ulimit，若不可用则软限制）
  - 输出大小限制
- 工作目录隔离
- 环境变量白名单
- 危险命令黑名单
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 次）
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）

目标: 实现命令行界面和端到端集成。

任务清单:

CLI 实现
- cmd/orca/main.go: 入口点
- cmd/orca/commands.go: 子命令定义
- 支持命令：
  - orca chat: 交互式对话
  - orca run "query": 单次执行
  - orca sessions: 会话列表
  - orca skills: 已加载 Skill 列表
  - orca tools: 已注册 Tool 列表
  - orca config: 配置查看/设置
交互式对话
- 读取用户输入
- 创建/恢复会话
- 调用 Orchestrator Agent
- 显示 Agent 思考过程和结果
- 支持多轮对话
端到端集成测试
- 完整对话流程测试
- Skill 触发和调用测试
- Tool 调用链测试
- 错误恢复测试

验收标准:

orca --help 显示正确
orca chat 可以开始对话
完整对话流程测试通过

Phase 6: 多 Agent 协作与优化（Day 6-7）

目标: 实现多 Agent 协作和性能优化。

任务清单:

多 Agent 协作
- Orchestrator 任务分解逻辑
- Worker Agent 分配策略
- Agent 间消息传递
- 结果汇总和冲突解决
性能优化
- 会话缓存（最近 N 个会话驻留内存）
- Skill 索引（倒排索引加速匹配）
- 连接池（Ollama HTTP 连接复用）
可观测性
- 结构化日志（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 接口

type Plugin interface {
    Name() string
    Version() string
    Init(kernel *Kernel) error
    Shutdown() error
}

Agent 接口

type Agent interface {
    ID() string
    Role() string
    Process(ctx context.Context, msg Message) (Message, error)
    Stop() error
}

Tool 接口

type Tool interface {
    Name() string
    Description() string
    Parameters() ParameterSchema
    Execute(ctx context.Context, args map[string]interface{}) (ToolResult, error)
}

LLMClient 接口

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 实现

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

9.6 KiB Raw Blame History Unescape Escape

Orca Agent Framework - 实现计划

项目概览

实现阶段

Phase 1: 项目骨架与核心基础设施（Day 1）

Phase 2: Actor 系统与会话管理（Day 2）

Phase 3: Skill 与 Tool 系统（Day 3）

Phase 4: 沙箱与 Ollama 集成（Day 4）

Phase 5: CLI 与集成（Day 5）

Phase 6: 多 Agent 协作与优化（Day 6-7）

依赖管理

外部依赖（最小化）

内部依赖图

关键接口定义

Plugin 接口

Agent 接口

Tool 接口

LLMClient 接口

测试策略

单元测试覆盖目标

Mock 实现

风险与回退方案

里程碑

下一步

9.6 KiB

Raw Blame History