架构设计文档¶

class GatewayServer:
    def register_handler(self, method: str, handler: MethodHandler) -> None: ...
    async def _dispatch(self, method: str, params: dict, conn: GatewayConnection) -> Any: ...

while not done:
    response = await llm.stream(messages, tools)
    for chunk in response:
        if chunk.is_tool_call:
            result = await tool_registry.execute(chunk.tool, chunk.args)
            messages.append(tool_result(result))
        elif chunk.is_text:
            yield chunk.text
    if no_tool_calls:
        done = True

class ChannelPlugin(ABC):
    async def start(self) -> None: ...
    async def stop(self) -> None: ...
    async def send_reply(self, reply: ChannelReply) -> None: ...
    def on_message(self, callback) -> None: ...

┌─────────────────────────────────────────────────────────────┐
│                    MemoryManager (统一接口)                   │
├─────────────────────────────────────────────────────────────┤
│  ┌────────────────┐  ┌────────────────┐  ┌───────────────┐  │
│  │  Compaction    │  │  Persistence   │  │   Long-term   │  │
│  │  上下文压缩     │  │  对话持久化     │  │   长期记忆    │  │
│  │  ContextChecker│  │  DialogStore   │  │   MEMORY.md   │  │
│  │  Summarizer    │  │  DailyLog      │  │               │  │
│  │  ToolCompactor │  │  LongTermMemory│  │               │  │
│  └───────┬────────┘  └───────┬────────┘  └───────┬───────┘  │
│          │                   │                   │          │
│  ┌───────▼───────────────────▼───────────────────▼───────┐  │
│  │                 MemoryStore (存储层)                   │  │
│  │  ┌─────────────┐            ┌─────────────┐           │  │
│  │  │ SQLite FTS5 │            │  LanceDB    │           │  │
│  │  │ (关键词搜索) │            │ (向量搜索)  │           │  │
│  │  └──────┬──────┘            └──────┬──────┘           │  │
│  │         └──────────┬───────────────┘                  │  │
│  │               ┌─────▼─────┐                            │  │
│  │               │  Hybrid   │  MMR + 时间衰减             │  │
│  │               │  Ranker   │                            │  │
│  │               └───────────┘                            │  │
│  └────────────────────────────────────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────┐  │
│  │                 Hooks (Agent 集成)                     │  │
│  │  pre_reasoning: 自动检查上下文并触发压缩               │  │
│  └────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

MemoryConfig(
    compaction=CompactionConfig(max_tokens=128000, reserve_ratio=0.3),
    summary=SummaryConfig(model="gpt-4o-mini", max_summary_tokens=2000),
    dialog=DialogConfig(enabled=True, retention_days=30),
    long_term=LongTermMemoryConfig(file="MEMORY.md"),
    tool_result=ToolResultConfig(max_length=2000),
)

Agent 推理前 (pre_reasoning hook)
  │
  ├─ ContextChecker.check_context(messages)
  │     │
  │     ├─ 计算总 token 数
  │     ├─ 判断是否超过阈值
  │     └─ 返回 ContextCheckResult
  │
  ├─ if needs_compaction:
  │     │
  │     ├─ Summarizer.generate_summary(messages_to_compact)
  │     │     └─ LLM 生成结构化摘要 (goals, decisions, progress, next_steps)
  │     │
  │     └─ 应用压缩：摘要替换旧消息
  │
  └─ Agent 继续推理

workspace/
├── MEMORY.md                    # 长期记忆：用户偏好、重要决策
├── memory/
│   ├── 2026-03-24.md           # 每日摘要日志
│   └── ...
├── dialog/
│   ├── 2026-03-24.jsonl        # 原始对话记录
│   └── ...
├── tool_result/
│   └── <uuid>.txt              # 长工具输出缓存
└── memory.db                   # SQLite 索引数据库

User (Web/Desktop/Mobile/CLI/Channel)
  │
  ▼
Gateway.chat.send(sessionId, message)
  │
  ▼
AgentRunner.run(session, message)
  │
  ├─ append user message to session
  │
  ├─ build system prompt (AGENTS.md + skills + context)
  │
  ├─ LLM.stream(messages, tools)
  │     │
  │     ├─ text delta → push chat.delta event
  │     │
  │     └─ tool_call → ToolRegistry.execute()
  │           │
  │           ├─ built-in tool
  │           ├─ MCP tool (stdio/HTTP)
  │           └─ approval gate (if exec/patch)
  │
  ├─ append assistant message to session
  │
  └─ push chat.done event

Channel (Telegram/Discord/...)
  │
  ▼
ChannelPlugin.on_message(callback)
  │
  ▼
ChannelManager → Routing (7-tier priority)
  │
  ▼
AgentRunner.run(...)  ← 选定的 Agent
  │
  ▼
Channel.send_reply(response)

Agent 请求执行命令
  │
  ▼
ToolGuards.check_policy(command)
  │
  ├─ allow_list → 直接执行
  ├─ deny_list → 拒绝
  └─ approval_required → 推送审批请求到 UI/CLI
        │
        ▼
      用户审批/拒绝

{
  models: {
    providers: {
      openai: { apiKey: "${OPENAI_API_KEY}" },
      anthropic: { apiKey: "${ANTHROPIC_API_KEY:-}" },
    },
  },
}

# 第三方包的 pyproject.toml
[project.entry-points."pyclaw.plugins"]
my_plugin = "my_package.plugin:MyPlugin"

~/.pyclaw/workspace/skills/
├── my-skill/
│   └── SKILL.md    # 包含系统提示和工具定义
└── ...

# HOOK.md
## on_message_received
Run sentiment analysis before processing.

src/pyclaw/
├── __init__.py
├── main.py               # 入口
│
├── agents/               # Agent 运行时
│   ├── runner.py          # 核心循环
│   ├── stream.py          # 多 Provider 流式
│   ├── session.py         # 会话存储
│   ├── system_prompt.py   # 系统提示构建
│   ├── tokens.py          # Token 计数
│   ├── embedded_runner/   # 嵌入式运行器
│   ├── providers/         # LLM Provider 适配
│   ├── subagents/         # 子 Agent 管理
│   ├── skills/            # SKILL.md 系统
│   ├── tools/             # 20+ 内置工具
│   ├── progress.py        # 进度事件
│   ├── memory_integration.py  # 记忆系统集成
│   └── types.py           # 共享类型
│
├── gateway/              # Gateway 服务
│   ├── server.py          # FastAPI + WebSocket
│   ├── openai_compat.py   # OpenAI API 兼容层
│   ├── protocol/          # 帧定义
│   ├── methods/           # RPC 方法处理器
│   └── events.py          # 事件广播
│
├── channels/             # 25 个消息通道
│   ├── base.py            # ChannelPlugin 基类
│   ├── manager.py         # 通道管理器
│   ├── plugin_sdk/        # 20 个 Protocol 接口
│   ├── plugins/           # 通道增强 (onboarding/outbound/actions/normalize)
│   └── <channel>/         # 各通道实现
│
├── memory/               # 记忆系统
│   ├── __init__.py        # 公共接口导出
│   ├── manager.py         # 统一记忆管理器
│   ├── store.py           # SQLite + FTS5 存储
│   ├── lancedb_backend.py # LanceDB 向量存储
│   ├── hybrid.py          # 混合检索
│   ├── mmr.py             # MMR 重排序
│   ├── temporal_decay.py  # 时间衰减
│   ├── embeddings.py      # 向量嵌入
│   ├── types.py           # 类型定义
│   ├── compaction/        # 上下文压缩
│   │   ├── context_checker.py
│   │   ├── summarizer.py
│   │   └── tool_compactor.py
│   ├── persistence/       # 持久化存储
│   │   ├── dialog_store.py
│   │   ├── daily_log.py
│   │   └── long_term.py
│   ├── hooks/             # Agent 集成钩子
│   │   └── pre_reasoning.py
│   └── qmd/               # QMD 格式支持
│
├── config/               # 配置管理
├── mcp/                  # MCP 客户端
├── security/             # 安全策略
├── secrets/              # 密钥管理
├── hooks/                # 事件钩子
├── plugins/              # 扩展系统
├── routing/              # 消息路由
├── media/                # 媒体处理
├── social/               # Agent 社交网络
├── infra/                # 基础设施
├── cli/                  # CLI 命令
└── ui/                   # TypeScript 客户端