Go龙虾picoclaw库源码阅读

1. 先定边界：cmd 薄、pkg 厚

• cmd/picoclaw
  
  ：只做 CLI（Cobra 子命令、参数、调用 pkg），不要在 cmd 里抠业务细节。
• pkg/
  
  ：配置、Agent、渠道、模型、工具、会话、路由等真正逻辑几乎都在这里。

读源码时：从 cmd 找入口函数名 → 跳到 pkg 里对应实现。

2. 建议阅读路径（由浅入深）

第一步：入口与子命令

1. cmd/picoclaw/main.go
   
    — 有哪些子命令。
2. 按你关心的场景点开，例如：
• 首次配置：internal/onboard/
• 跑网关：internal/gateway/
• 对话：internal/agent/
• 登录模型：internal/auth/

每个子命令的 command.go 里会 import 并调用 pkg/...，记下第一个跳进 pkg 的函数。

第二步：配置（几乎所有行为都从这里分叉）

• pkg/config/
  
  （含 defaults、结构体定义）搞清：Config、Agent、Channels、Tools 等字段，后面读别的包会轻松很多。

第三步：Agent 主循环（「大脑」）

• pkg/agent/instance.go
  
   — Agent 如何组 workspace、会话、工具表、Provider。
• pkg/agent/loop.go
  
   — 一轮对话里：收消息 → 调模型 → 跑 tool loop 的主路径（这是最值得精读的文件之一）。
• 顺带：pkg/agent/context.go、thinking.go 理解上下文与思考模式。

第四步：模型侧（「对外说话」）

• pkg/providers/factory.go
  
   — 如何根据配置选具体 Provider。
• pkg/providers/types.go
  
   — 接口长什么样。再按需看：anthropic/、openai_compat/、claude_provider.go 等一个即可，模式类似。

第五步：工具与 MCP（「手」）

• pkg/tools/registry.go
  
   — 工具怎么注册、怎么执行。
• 单个工具如 shell.go、filesystem.go、mcp_tool.go 看一两个就够。

第六步：渠道（「耳朵和嘴」）

• pkg/channels/manager.go
  
   — 多通道怎么起、怎么收消息。
• pkg/channels/base.go
  
  、interfaces.go — 抽象。
• 只选一个渠道深读
  
  （例如 telegram/telegram.go），避免一上来被十几个 IM 淹没。

第七步：路由与会话（「谁处理、上下文键」）

• pkg/routing/route.go
  
   — 消息路由到哪个 Agent、SessionKey 怎么来。
• pkg/session/manager.go
  
   — 会话持久化与键。
• pkg/memory/
  
   — 长期记忆相关（若你关心记忆设计）。

3. 实用技巧

4. 阅读重点（只读这 5 个也能建立轮廓）

1. cmd/picoclaw/main.go
2. pkg/config/
   
   （能看懂配置结构即可）
3. pkg/agent/instance.go
   
    + pkg/agent/loop.go
4. pkg/providers/factory.go
5. pkg/channels/manager.go
   
   + 任意一个 pkg/channels/<name>/