API 参考文档¶

ws://localhost:18777/ws

{
  "type": "req",
  "id": "unique-request-id",
  "method": "method.name",
  "params": { ... }
}

{
  "type": "res",
  "id": "same-request-id",
  "ok": true,
  "payload": { ... }
}

{
  "type": "res",
  "id": "same-request-id",
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Session not found"
  }
}

{
  "type": "event",
  "event": "chat.delta",
  "seq": 42,
  "payload": { ... }
}

{
  "type": "req",
  "id": "1",
  "method": "connect",
  "params": {
    "minProtocol": 1,
    "maxProtocol": 3,
    "clientName": "my-app",
    "auth": { "token": "your-auth-token" }
  }
}

{
  "audio": "base64-encoded-mp3-audio",
  "mimeType": "audio/mpeg",
  "sizeBytes": 12345,
  "voice": "en-US-AvaNeural"
}

pyclaw gateway call tts.speak --params '{"text": "Hello, world!", "voice": "en-US-AvaNeural"}'

curl -X POST http://localhost:18778/v1/chat/completions \
  -H "Authorization: Bearer $PYCLAW_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "stream": true
  }'

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1709000000,
  "model": "gpt-4o",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 10,
    "total_tokens": 30
  }
}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},"index":0}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"!"},"index":0}]}

data: [DONE]

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "owned_by": "openai",
      "created": 1709000000
    },
    {
      "id": "claude-sonnet-4-20250514",
      "object": "model",
      "owned_by": "anthropic",
      "created": 1709000000
    }
  ]
}

{
  "tools": {
    "mcpServers": {
      "server-name": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
      }
    }
  }
}

# 查看 MCP 服务器状态
pyclaw mcp status

# 列出所有 MCP 工具
pyclaw mcp list-tools

# 查看 Gateway 状态（含探测）
pyclaw gateway status --deep --json

# 探测连通性
pyclaw gateway probe --url ws://192.168.1.100:18777

# 调用任意 RPC 方法
pyclaw gateway call health --params '{}'
pyclaw gateway call chat.send --params '{"message": "Hello"}'

# 局域网发现
pyclaw gateway discover --json

# 下载 GGUF 模型
pyclaw models download Qwen/Qwen3-4B-GGUF

# 下载 MLX 模型 (Apple Silicon)
pyclaw models download mlx-community/Llama-3-8B-4bit --backend mlx

# 从 ModelScope 下载
pyclaw models download qwen/Qwen3-4B-GGUF --source modelscope

# 列出本地模型
pyclaw models local

# 设置默认模型
pyclaw models select "Qwen/Qwen3-4B-GGUF/qwen3-4b-q4_k_m.gguf"

from pyclaw.ui import DrawableCanvas

canvas = DrawableCanvas(width=400, height=300)

# 绘制图形
canvas.draw_rect(10, 10, 100, 50, color="blue", fill=True)
canvas.draw_circle(200, 150, 40, color="red")
canvas.draw_line(0, 0, 400, 300, color="black", width=2)
canvas.draw_text(50, 50, "Hello", color="blue", size=20)

# 多边形和星形
canvas.draw_polygon([(0,0), (100,0), (50,86)], color="yellow")
canvas.draw_star(200, 150, 50, 25, points=5, color="gold")

# 画布操作
canvas.clear()
shape = canvas.pop_shape()  # 移除最后一个图形
canvas.remove_shape(shape)  # 移除指定图形

# 导出 PNG
png_bytes = await canvas.capture_png()

from pyclaw.ui import FreehandCanvas

canvas = FreehandCanvas(width=400, height=300, stroke_color="black", stroke_width=3)
canvas.set_stroke(color="red", width=5)
# 用户可以自由绘制

from pyclaw.ui.canvas import MoveTo, LineTo, CubicTo, QuadraticTo, ClosePath

elements = [
    MoveTo(0, 50),
    CubicTo(25, 0, 75, 100, 100, 50),  # 三次贝塞尔曲线
    LineTo(150, 50),
    ClosePath(),
]
canvas.draw_path(elements, color="blue")

from pyclaw.ui import fa_icon, fa_icon_button

# 创建图标
icon = fa_icon("heart", color="red", size=32)
page.add(icon)

# 创建按钮
btn = fa_icon_button("user", color="blue", on_click=handle_click, tooltip="User")

from pyclaw.ui import Icon

# 状态图标
Icon.success(color="green", size=32)  # 勾选
Icon.error(color="red")               # 错误
Icon.warning(color="orange")          # 警告
Icon.info(color="blue")               # 信息

# 操作图标
Icon.add()
Icon.edit()
Icon.delete()
Icon.copy()
Icon.save()

# 导航图标
Icon.menu()
Icon.back()
Icon.forward()
Icon.home()

# AI 图标
Icon.brain()      # 大脑
Icon.robot()      # 机器人
Icon.sparkles()   # 闪光

from pyclaw.ui import lucide_icon

icon = lucide_icon("send", color="blue", size=24)

from pyclaw.ui import ImageCanvas

canvas = ImageCanvas(
    image_src="photo.jpg",
    width=600,
    height=400,
)

# 绘制标注
canvas.draw_rect(100, 100, 50, 50, color="red", stroke_width=2)
canvas.draw_arrow(150, 125, 200, 100, color="red")
canvas.draw_text(100, 160, "Note", color="red")
canvas.draw_marker(300, 200, label="Point A", color="blue")

# 更换背景图
canvas.set_image("another.png")

# 导出
png_bytes = await canvas.capture_png()

from pyclaw.ui import AnnotationCanvas

canvas = AnnotationCanvas(
    image_src="document.png",
    width=600,
    height=400,
)

# 设置当前工具
canvas.current_tool = "pen"      # pen, rect, circle, arrow, marker, text
canvas.stroke_color = "red"
canvas.stroke_width = 3.0

# 工具栏
toolbar = canvas.build_toolbar()

from pyclaw.ui import CanvasPanel

def on_export(png_bytes):
    with open("drawing.png", "wb") as f:
        f.write(png_bytes)

panel = CanvasPanel(
    width=600,
    height=400,
    canvas_bgcolor="white",
    on_export=on_export,
)
page.add(panel)

# 访问底层画布
panel.canvas.draw_rect(10, 10, 50, 50, color="blue")

# 程序化控制
panel.current_tool = "rect"
panel.stroke_color = "red"

from pyclaw.ui import SimpleCanvasPanel

panel = SimpleCanvasPanel(width=300, height=200)
page.add(panel)

from pathlib import Path
from pyclaw.memory import MemoryManager, MemoryConfig
from pyclaw.agents.types import ModelConfig

# 初始化
manager = MemoryManager(
    workspace_dir=Path("./workspace"),
    config=MemoryConfig.from_yaml(Path("config.yaml")),
    model=ModelConfig(provider="openai", model_id="gpt-4o-mini"),
)

# 使用上下文管理器
with MemoryManager(Path("./workspace")) as manager:
    # 检查上下文
    result = manager.check_context(messages)
    if result.needs_compaction:
        summary = await manager.generate_summary(result.messages_to_compact)
        messages = manager.apply_compaction(messages, summary, result)

    # 记忆操作
    manager.add_memory("用户偏好中文", category="preference")
    manager.set_preference("language", "中文")
    prefs = manager.get_all_preferences()

    # 搜索
    results = manager.search_memory("用户偏好", limit=5)

    # 持久化对话
    manager.persist_dialog(messages)

    # 统计信息
    stats = manager.get_stats()

from pyclaw.memory.types import (
    MemoryConfig,
    CompactionConfig,
    SummaryConfig,
    DialogConfig,
    LongTermMemoryConfig,
    ToolResultConfig,
)

config = MemoryConfig(
    # 上下文压缩
    compaction=CompactionConfig(
        enabled=True,
        max_tokens=128000,
        reserve_ratio=0.3,
        min_messages_to_compact=10,
        compaction_threshold=0.85,
    ),
    # 摘要生成
    summary=SummaryConfig(
        enabled=True,
        model="gpt-4o-mini",
        max_summary_tokens=2000,
        async_mode=True,
    ),
    # 对话持久化
    dialog=DialogConfig(
        enabled=True,
        retention_days=30,
    ),
    # 长期记忆
    long_term=LongTermMemoryConfig(
        enabled=True,
        file="MEMORY.md",
    ),
    # 工具输出压缩
    tool_result=ToolResultConfig(
        enabled=True,
        max_length=2000,
        retention_days=7,
    ),
)

{
  "name": "memory_search",
  "arguments": {
    "query": "用户偏好",
    "limit": 10
  }
}

{
  "name": "memory_add",
  "arguments": {
    "content": "用户偏好使用中文交流",
    "category": "preference"
  }
}

{
  "name": "memory_update_preference",
  "arguments": {
    "key": "language",
    "value": "中文"
  }
}

{
  "name": "memory_forget",
  "arguments": {
    "id": 123
  }
}

{
  "name": "memory_stats",
  "arguments": {}
}

from pyclaw.agents.tools.memory_tools import create_memory_tools
from pyclaw.memory import MemoryManager

manager = MemoryManager(Path("./workspace"))
manager.open()

# 创建所有记忆工具
tools = create_memory_tools(memory_manager=manager)

# 注册到 agent
for tool in tools:
    agent.register_tool(tool)

from pyclaw.agents.memory_integration import MemoryAwareRunner

with MemoryAwareRunner(
    workspace_dir=Path("./workspace"),
    model=ModelConfig(provider="openai", model_id="gpt-4o"),
) as runner:
    # 获取工具
    tools = runner.get_tools()

    # 预处理消息（自动压缩）
    messages = await runner.preprocess_messages(messages)

    # 获取上下文用于提示词
    context = runner.get_context_for_prompt()

    # 后处理（自动保存对话）
    await runner.postprocess_turn(messages, session_key="session-1")

from pyclaw.agents.memory_integration import setup_memory_for_agent

result = setup_memory_for_agent(
    workspace_dir=Path("./workspace"),
    model=ModelConfig(provider="openai", model_id="gpt-4o"),
)

# 返回所有组件
manager = result["manager"]
tools = result["tools"]
context = result["context"]  # 用于注入系统提示

# 使用完毕后关闭
manager.close()

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

from pyclaw.memory.types import (
    # 结果类型
    ContextCheckResult,    # 上下文检查结果
    StructuredSummary,     # 结构化摘要

    # 配置类型
    MemoryConfig,          # 完整配置
    CompactionConfig,      # 压缩配置
    SummaryConfig,         # 摘要配置
    DialogConfig,          # 对话配置
    LongTermMemoryConfig,  # 长期记忆配置
    ToolResultConfig,      # 工具输出配置

    # 枚举
    MemoryCategory,        # 记忆分类
    CompactionTrigger,     # 压缩触发类型
)

# 结构化摘要
summary = StructuredSummary(
    goals=["完成功能实现"],
    constraints=["使用 Python 3.10+"],
    progress="已完成基础功能",
    decisions=["使用 SQLite 存储"],
    next_steps=["编写测试"],
    key_context=["项目: pyclaw"],
)

# 转换为 Markdown
markdown = summary.to_markdown()

# 转换为消息
message = summary.to_message()

from pathlib import Path
from pyclaw.memory.active_recall import ActiveMemoryRecaller
from pyclaw.memory.recall_types import ActiveRecallConfig, QueryMode, PromptStyle
from pyclaw.memory import MemoryManager

# 配置
config = ActiveRecallConfig(
    enabled=True,
    query_mode=QueryMode.RECENT,
    prompt_style=PromptStyle.BALANCED,
    max_summary_chars=220,
    recent_user_turns=2,
    recent_assistant_turns=1,
    cache_ttl_ms=15000,
)

# 初始化
recaller = ActiveMemoryRecaller(
    memory_manager=memory_manager,
    config=config,
    workspace_dir=Path("./workspace"),
)

# 执行召回
result = await recaller.recall(
    latest_message="What's the status of the API?",
    recent_turns=[
        {"role": "user", "content": "Previous message..."},
        {"role": "assistant", "content": "Previous response..."},
    ],
    session_key="session-123",
)

# 检查结果
if result.is_success:
    # 构建上下文消息
    context_msg = recaller.build_context_message(result)
    # 注入到消息列表
    messages.insert(0, context_msg)

from pyclaw.memory.recall_types import ActiveRecallResult

result = ActiveRecallResult(
    status="ok",  # "ok" | "empty" | "timeout" | "unavailable"
    elapsed_ms=42,
    summary="Retrieved relevant memories...",
    search_debug={
        "backend": "hybrid",
        "configured_mode": "recent",
        "effective_mode": "recent",
        "fallback": "",
        "search_ms": 38,
        "hits": 5,
    },
)

# 便捷属性
result.is_success      # True if status == "ok" and summary exists
result.is_empty        # True if status == "empty"
result.is_timeout      # True if status == "timeout"
result.is_unavailable  # True if status == "unavailable"

from pyclaw.memory.recall_types import QueryMode

QueryMode.MESSAGE  # 仅使用最新用户消息
QueryMode.RECENT   # 最近对话轮次 + 最新消息
QueryMode.FULL     # 完整对话上下文

from pyclaw.memory.recall_types import PromptStyle

PromptStyle.BALANCED        # 平衡上下文与记忆
PromptStyle.STRICT          # 严格使用记忆内容
PromptStyle.CONTEXTUAL      # 优先理解对话上下文
PromptStyle.RECALL_HEAVY    # 最大化记忆召回
PromptStyle.PRECISION_HEAVY # 优先精确性
PromptStyle.PREFERENCE_ONLY # 仅召回用户偏好

# 启用 Active Memory（当前会话）
pyclaw active-memory on

# 禁用 Active Memory（当前会话）
pyclaw active-memory off

# 查看状态
pyclaw active-memory status

from pathlib import Path
from pyclaw.memory.wiki.vault import WikiVault
from pyclaw.memory.wiki.types import WikiConfig, WikiPage

# 初始化
vault = WikiVault(
    vault_path=Path("./wiki"),
    config=WikiConfig(),
)
vault.initialize()

# 获取页面
page = vault.get_page("entities/company-acme")
if page:
    print(page.title)
    print(page.content)
    print(len(page.claims))

# 保存页面
page = WikiPage(
    path="entities/new-entity",
    title="New Entity",
    content="# New Entity\n\nDescription...",
    claims=[],
)
vault.save_page(page)

# 列出页面
pages = vault.list_pages("entities")

# 获取统计
stats = vault.get_stats()
# {"pages": 10, "claims": 25, "directories": 7, "sources": 3}

from pathlib import Path
from pyclaw.memory.wiki.claims import ClaimsManager
from pyclaw.memory.wiki.types import ClaimStatus

# 初始化
manager = ClaimsManager(
    claims_dir=Path("./wiki/.openclaw-wiki/claims"),
)

# 添加 Claim
claim = manager.add_claim(
    page_path="entities/company-acme",
    text="Company uses PostgreSQL for primary database",
    evidence=[
        {
            "source_id": "doc-1",
            "source_path": "sources/architecture.md",
            "lines": "45-52",
            "weight": 1.0,
        }
    ],
    tags=["database", "infrastructure"],
    confidence=0.8,
)

# 获取 Claim
claim = manager.get_claim(claim.id)

# 更新 Claim
manager.update_claim(
    claim.id,
    confidence=0.9,
    tags=["database", "infrastructure", "verified"],
)

# 查找矛盾
contradictions = manager.find_contradictions(claim)

# 取代旧 Claim
new_claim = manager.supersede_claim(
    old_claim_id=claim.id,
    new_claim_text="Company migrated to MySQL in 2024",
    rationale="Database migration completed",
)

# 删除 Claim
manager.delete_claim(claim.id)

# 导出为 JSONL
manager.export_to_jsonl(Path("./claims.jsonl"))

from pyclaw.memory.wiki.types import (
    WikiConfig,
    WikiPage,
    Claim,
    ClaimStatus,
    Evidence,
)

# Claim 示例
claim = Claim(
    id="abc123",
    text="Company uses PostgreSQL",
    status=ClaimStatus.ACTIVE,
    confidence=0.8,
    evidence=[
        Evidence(
            source_id="doc-1",
            source_path="sources/architecture.md",
            lines="45-52",
            weight=1.0,
            excerpt="...",
        )
    ],
    tags=["database"],
)

# Claim 状态
ClaimStatus.ACTIVE      # 活跃
ClaimStatus.SUPERSEDED  # 已被取代
ClaimStatus.REFUTED     # 已被反驳

# 初始化 Wiki
pyclaw wiki init [--path ./wiki]

from pathlib import Path
from pyclaw.memory.dreaming.signals import SignalsStore

# 初始化
store = SignalsStore(
    store_dir=Path("./.dreams"),
)

# 添加信号
signal = store.add_signal(
    content="User prefers dark mode in the UI",
    source_ref="MEMORY.md:15",
    query="ui preferences",
    tags=["preferences", "ui"],
)

# 记录巩固（Agent 引用）
store.record_consolidation(signal.content_hash)

# 获取信号
all_signals = store.get_all_signals()
recent_signals = store.get_signals_by_age(max_age_days=30)

# 清理旧信号
removed = store.cleanup_old_signals(max_age_days=60)

# 获取统计
stats = store.get_stats()
# {"total": 100, "total_recall_queries": 250, "total_consolidations": 45}

from pyclaw.memory.dreaming.scoring import PromotionScorer, ScoreComponents
from pyclaw.memory.dreaming.types import DreamingConfig

# 配置
config = DreamingConfig(
    enabled=True,
    min_score=0.5,
    min_recall_count=2,
    min_unique_queries=2,
    scoring_weights={
        "frequency": 0.25,
        "relevance": 0.20,
        "diversity": 0.15,
        "recency": 0.15,
        "consolidation": 0.15,
        "conceptual": 0.10,
    },
)

# 初始化
scorer = PromotionScorer(config)

# 评分单个信号
score, components = scorer.score_signal(signal)
print(f"Score: {score}")
print(f"Components: {components.to_dict()}")

# 过滤候选
candidates = scorer.filter_candidates(
    signals=all_signals,
    min_score=0.5,
)
# 返回按分数降序排列的 PromotionCandidate 列表

from pyclaw.memory.dreaming.phases import DreamingPhases
from pyclaw.memory.dreaming.types import DreamingPhase

# 初始化
phases = DreamingPhases(
    workspace_dir=Path("./workspace"),
    config=config,
)

# 执行 LIGHT 阶段
light_report = await phases.run_phase(DreamingPhase.LIGHT)

# 执行 DEEP 阶段
deep_report = await phases.run_phase(DreamingPhase.DEEP)
print(f"Promoted {deep_report.promoted_count} items")

# 执行 REM 阶段
rem_report = await phases.run_phase(DreamingPhase.REM)

from pyclaw.memory.dreaming.types import (
    DreamingConfig,
    DreamingPhase,
    StorageMode,
    ShortTermSignal,
    PromotionCandidate,
    DreamingReport,
)

# 配置
config = DreamingConfig(
    enabled=True,
    cron="0 3 * * *",  # 每天凌晨 3 点
    limit=10,
    min_score=0.5,
    storage=StorageMode.INLINE,
)

# 阶段
DreamingPhase.LIGHT  # 收集信号
DreamingPhase.DEEP   # 评分提升
DreamingPhase.REM    # 反思叙事

# 存储模式
StorageMode.INLINE    # 追加到 MEMORY.md
StorageMode.SEPARATE  # 存储到独立文件
StorageMode.BOTH      # 两者都保存

{
  "dreaming": {
    "enabled": true,
    "cron": "0 3 * * *",
    "timezone": "Asia/Shanghai",
    "limit": 10,
    "minScore": 0.5,
    "minRecallCount": 2,
    "minUniqueQueries": 2,
    "recencyHalfLifeDays": 7.0,
    "maxAgeDays": 30,
    "storage": "inline",
    "scoringWeights": {
      "frequency": 0.25,
      "relevance": 0.20,
      "diversity": 0.15,
      "recency": 0.15,
      "consolidation": 0.15,
      "conceptual": 0.10
    }
  }
}