HxClaw/docs/picoclaw-research.md

picoclaw 技术研究报告

概述

本报告基于对 picoclaw v0.2.6 源代码的研究，详细分析其核心机制。

---

1. 系统架构

1.1 核心模块

picoclaw/
├── pkg/
│   ├── agent/      # AI 代理核心逻辑
│   ├── providers # LLM 提供者
│   ├── config/   # 配置管理
│   ├── tools/   # 工具注册与执行
│   ├── skills/  # Skill 加载器
│   ├── bus/    # 消息总线
│   └── channels/ # 消息通道
└── web/         # Web 界面

1.2 依赖关系

• agent：核心模块，依赖 providers、tools、skills、bus
• providers：LLM API 调用（OpenAI、Anthropic 等）
• tools：工具执行（exec、read_file、web_fetch 等）
• skills：通过 SKILL.md 加载技能定义

---

2. Skill 机制

2.1 加载机制

位置：pkg/skills/loader.go

Skill 存储在三个位置，优先级：

1. workspace/skills/ - 项目级
2. ~/.picoclaw/skills/ - 全局
3. 内置 skills 目录

每个 skill 必须是 SKILL.md 文件，包含：

• Frontmatter (YAML/JSON) 定义 name 和 description
• Markdown 主体内容（操作指导）

2.2 执行机制

关键发现：Skill 本质是 Markdown 文档，不是可执行代码

AI 阅读 SKILL.md 后，调用实际工具执行任务：

加载 SKILL.md → AI 阅读 → 调用工具 → 执行结果

---

3. 工具执行机制

3.1 执行流程

位置：pkg/agent/loop.go:runTurn (约 2332-2899 行)

// 串行执行每个工具调用
for i, tc := range normalizedToolCalls {
    toolName := tc.Name
    toolArgs := cloneStringAnyMap(tc.Arguments)
    
    // 执行工具
    toolResult := ts.agent.Tools.ExecuteWithContext(
        execCtx, toolName, toolArgs, ts.channel, ts.chatID, asyncCallback,
    )
    
    // 结果添加到消息历史
    toolResultMsg := providers.Message{
        Role:       "tool",
        Content:    contentForLLM,
        ToolCallID: toolCallID,
    }
    messages = append(messages, toolResultMsg)
}

3.2 关键特性

特性	说明
执行方式	串行执行，非并行
结果收集	通过 providers.Message 添加到上下文
用户显示	ForUser 字段非空时发送给用户
静默结果	SilentResult() 不显示给用户，但发给 LLM

3.3 工具结果标志

// Silent: 不发送消息给用户，但发送给 LLM
Silent bool `json:"silent"`

// ResponseHandled: 工具已处理响应，不生成独立消息
ResponseHandled bool `json:"response_handled,omitempty"`

// IsError: 标记为错误结果
IsError bool `json:"is_error,omitempty"`

---

4. 消息处理

4.1 消息总线

位置：pkg/bus/bus.go

用户输入 → AgentLoop.ProcessDirect() → AI 处理 → 工具执行 ←
                              ↓
                        bus.PublishOutbound() → 输出

4.2 消息类型

类型	说明
InboundMessage	用户输入
OutboundMessage	AI 输出
ToolResult	工具结果

---

5. 异步执行

5.1 AsyncExecutor 接口

位置：pkg/tools/base.go:107

type AsyncExecutor interface {
    Tool
    ExecuteAsync(ctx context.Context, args map[string]any, cb AsyncCallback) *ToolResult
}

5.2 使用方式

// 执行时传入回调函数
toolResult := ts.agent.Tools.ExecuteWithContext(
    execCtx, toolName, toolArgs, ts.channel, ts.chatID,
    asyncCallback,  // 异步回调
)

---

6. TTS 工具分析

6.1 文件位置

• 主文件：pkg/tools/tts_send.go
• TTS 提供者：pkg/audio/tts/tts.go

6.2 实现方式

1. 通过 SendTTSTool 执行 TTS 合成
2. 调用 tts.SynthesizeAndStore() 生成音频
3. 返回文件路径或直接播放

6.3 已知问题

问题	原因
播放内容不一致	异步回调竞争
结果不显示	使用了 SilentResult()
多条记录只显示一条	串行执行中的状态竞争

---

7. 配置系统

7.1 配置文件

• 项目级：config.yaml
• 用户级：~/.picoclaw/config.json
• 环境变量：PICOCLAW_* 前缀

7.2 配置结构

type Config struct {
    Agents    AgentsConfig    `json:"agents"`
    Tools    ToolsConfig    `json:"tools"`
    Channels ChannelsConfig `json:"channels"`
    Voice    VoiceConfig   `json:"voice"`
}

---

8. hxclaw 集成方式

8.1 复用策略

hxclaw 通过 Go replace 机制复用 picoclaw：

// go.mod
replace github.com/sipeed/picoclaw => ./path/to/picoclaw

8.2 核心依赖

• pkg/agent - AI 代理核心
• pkg/providers - LLM 提供者
• pkg/config - 配置加载
• pkg/bus - 消息总线

---

9. 总结

模块	机制	阻塞
Skill	Markdown 文档	否
工具	串行执行	是
异步工具	回调机制	可选
消息总线	非阻塞	否

---

10. 建议

1. 避免阻塞：长时间任务使用 AsyncExecutor
2. 结果显示：检查 Silent/ResponseHandled 标志
3. 并发控制：使用 SubTurn 的 concurrencySem