PyClaw Web Channel

团队自己的 AI Agent — 住在你团队聊天的地方,有可复利的记忆,有可衡量的进化,有企业级的隔离。

大多数 AI agent 每次对话都从空白起步:用户不停重复上下文、重复约定、重复工具栈。PyClaw 押注相反方向:一个嵌入团队沟通平台的 agent,跨周记忆,自动学会团队反复执行的 playbook,按团队的审批流程运行。

• 🧠 记忆是 tier-zero,不是插件。 会话、事实、流程、向量归档 — 四层 L1-L4 记忆,全部进 agent 主循环,每轮都检索。中文 FTS5 + jieba 分词原生支持,30 天预警 + 90 天归档生命周期由 Curator 异步执行,分布式安全。少了这一层,剩下的只是套壳。
• 📈 agent 越用越有用**,不是越用越话多。** 成功会话自动抽取 SOP;高频 SOP 自动毕业为可复用 SKILL.md(v2 支持版本演进,旧版进 skill_history/);过时的由 agent 主动 forget。无需微调,无 vendor lock。14 个 byte-stability 测试为"90%+ prompt cache 命中"背书,不只是宣传。
• 💬 群内原生,不是 IDE 原生。 飞书 CardKit + Web React SPA 共用同一个 agent 内核,Session Affinity Gateway 支持 active-active 多 worker 水平扩展(Redis 亲和注册 + PubSub 跨 worker 转发,3-worker 真机 smoke 验证通过)。设计师、PM、运维跟工程师对同一个 agent,不切换 surface。
• 🛡 企业级治理是地板,不是 enterprise 加价项。 三档权限(read-only / approval / yolo)+ per-user profile + Anthropic srt 真 OS 沙箱(macOS Seatbelt / Linux bubblewrap+seccomp,8 条架构不变量 + fail-closed)+ 结构化 JSON 审计 + 飞书 originator-only CardKit。开箱即用,第一天就能跑。

2026 年的 agent 版图分化为四条路径,各自押注不同象限:

PyClaw 走第 4 条路。 我们不跟 Claude Code 比 IDE 抛光、不跟 OpenHuman 比 OAuth 数量、不跟 LangGraph 比 graph-state runtime。我们竞争一句话:团队有自己的 institutional memory,agent 是这个团队的一员。

调研完 OpenClaw / Hermes / OpenHuman 三家后的诚实结论(详见 B1 公众号文章对比表):

• ✅ 适合你:住在飞书或 Web console 的工程 / 运维 / 产品团队,每周重复某些工作流,需要一个用越久越懂团队、不会跨租户泄露秘密、有审计可追溯的 agent。
• ❌ 不是你的工具:单兵开发者想要最深的 IDE 集成(用 Claude Code / Cursor);想要第一天就懂你邮件 / 日历的个人助手(用 OpenHuman);任意 multi-agent DAG 编排框架(用 LangGraph)。

四条路径的 6,000 字深度对比(含源码级证据 + 5 个借鉴招式 + 反向校准)见公众号文章:OpenClaw / Hermes / OpenHuman / PyClaw 四种 Agent 架构路径。

OpenClaw 是一个优秀的多通道 AI 助手 — 但它的 TypeScript 单体(17,000+ 文件)将计算和存储紧耦合,且缺少生产级的记忆系统。PyClaw 用 Python 从头重写,定位 记忆优先 · Hook 驱动 · 水平可扩展:

• 🧠 4 层记忆系统 — L1 Redis 热索引 → L2 事实 → L3 流程 → L4 向量归档。生产级,已完整集成到 Agent 主循环。
• 🔄 自我进化 — 自动从会话中提取 SOP、生命周期管理(30 天预警 / 90 天归档)、Agent 可主动遗忘过时流程、高频 SOP 自动毕业为 Skill。Skill graduation v2 让改进版 SOP 可以原子替换旧的 auto_generated SKILL.md(旧版备份到 skill_history/)。无需微调。
• 🪝 Hook 驱动架构 — 记忆注入、Working Memory、Nudge 提醒、工具审批、输出压缩 — 全部以 Hook 形式接入。可自定义扩展,不动核心。
• ☁️ 存算分离 — 计算层完全无状态,可水平扩展。Session 在 Redis,记忆在 SQLite/Redis,向量经 litellm。
• 🌐 多渠道接入 — 飞书 WebSocket 集群 + Web 渠道(React SPA + OpenAI 兼容 /v1/chat/completions SSE)。
• 🚦 Session 亲和网关 — Active-active 多 worker 水平扩展,Redis 亲和注册 + PubSub 跨 worker 转发。同一 session 永远落同一 worker,不论飞书/LB 怎么 dispatch。Worker 死亡时通过 TTL + PUBLISH-0 检测自动 failover。
• 🇨🇳 中文优化 — FTS5 + jieba 分词,支持中文全文检索。停用词过滤,trigram → jieba 自动迁移。
• 🎯 Prompt 预算工程 — Frozen Prefix(可缓存)+ Per-Turn Suffix(动态)+ Dynamic Zone(按 prompt 检索)。14 个 byte-stability invariant 测试证明"90%+ prompt 缓存命中"是可验证事实,不是宣传(OpenHuman KV-cache invariant 的 clean-room 借鉴)。
• 🗜 工具输出压缩器 — 在 tool result 进入 LLM history 之前用 4 策略管线(strip_ansi / regex_replace / collapse_whitespace / head_tail)规则压缩。8 条 builtin 规则覆盖 git diff/log/status / pytest / npm/pip install / docker / web_fetch。bash-heavy session 节省 ~30-50% 输入 token。借鉴 OpenHuman TokenJuice(clean-room 重实现,OpenHuman 是 GPL-3.0)。
• 🛡 智能审批(无审批疲劳) — bash_approval_mode: "smart" 自动放行 cat/ls/git status/python -c 等 ~50 个 read 命令,写命令仍然弹审批。审批是 UX 层,不是安全层;安全由 srt 沙箱兜底。
• 🤖 Sub-Agent 系统 — Markdown manifest + isolated executor + 8 条架构不变量(沙箱/tier/abort/workspace/memory 继承是结构性的,不是 runtime 检查)。5 层 discovery,license-clean(零 bundled persona),用户自带。omit_memory_context / omit_skills_catalog / omit_working_memory toggle 让 token-economy 专用 agent(如 summarizer、reviewer)省 token。

超出 2 分钟上手范围? 跳到 § 配置 & 部署 查阅完整指南:本地 dev、单实例 Docker、3-worker active-active、多用户隔离、沙箱、MCP 服务器、工具审批。

git clone https://github.com/Timeflys2018/pyclaw.git && cd pyclaw
python3.12 -m venv .venv && .venv/bin/pip install -e ".[dev]"
# 在 configs/pyclaw.json 配置飞书 App 凭证
./scripts/start.sh

📖 更多:完整 pyclaw.json schema 见 配置参考, 或直接复制 configs/pyclaw.example.json。生产单实例部署:部署指南 § 单 Docker。

./scripts/start.sh # 启动后端 + 自动构建 React 前端
open http://localhost:8000 # 登录(默认 admin / changeme)

Web 渠道开箱即用:流式聊天(含执行轨迹面板:工具调用 + 记忆命中 + token 用量) · 多模态输入(粘贴 / 拖拽 / 选择图片) · ⌘K 命令面板 · 全局快捷键 · 会话重命名 + 删除 · 双主题(明暗) · 工具审批 UI · OpenAI 兼容 API(可对接第三方客户端)。

📖 更多:调整三档权限模型(read-only / approval / yolo)见 权限指南。挂 MCP 服务器(GitHub、filesystem 等)见 MCP 指南。多用户团队部署 + per-user tier 隔离见 多用户部署。

from pyclaw.core.agent.factory import build_agent_runner
from pyclaw.infra.settings import load_settings
settings = load_settings("configs/pyclaw.json")
runner = build_agent_runner(settings)
async for event in runner.run("帮我看一下这个 Python 报错..."):
 print(event)

📖 更多:Settings 类型、Hook、Agent 主循环 API 见 架构决策(D1–D26)和 Context Engine。

记忆系统是一个 4 层流水线,集成到每一次 Prompt 拼装:

flowchart LR
 User["用户提问"] --> L1["L1: Redis<br/>Working Memory<br/>(按 session)"]
 User --> L2["L2: SQLite + FTS5<br/>事实<br/>(jieba 分词)"]
 User --> L3["L3: SQLite + FTS5<br/>流程 / SOP"]
 User --> L4["L4: SQLite + sqlite-vec<br/>会话归档"]
 L1 -.snapshot.-> Prompt["Frozen Prefix"]
 L2 -.facts ≤3.-> Dynamic["Dynamic Zone"]
 L3 -.procedures ≤2.-> Dynamic
 L4 -.语义检索.-> Dynamic
 Prompt --> Agent[Agent 主循环]
 Dynamic --> Agent
 style L1 fill:#fff3e0,stroke:#e65100
 style L2 fill:#e8f5e9,stroke:#2e7d32
 style L3 fill:#e8f5e9,stroke:#2e7d32
 style L4 fill:#e3f2fd,stroke:#1565c0

驱动它的 Hook(不修改 LLM 侧):

Agent 自己调用的工具:

• memorize — 持久化到 L2(事实)或 L3(流程)。"无执行不写入"原则。
• forget — 归档过时/失败的 SOP。Agent 主动的生命周期管理。
• update_working_memory — 按 session 的临时记事本(1024 字符上限,7 天 TTL,FIFO 淘汰)。
• skill_view — 渐进式披露:按需加载完整 SKILL.md 内容。

PyClaw 的 Agent 能自我改进 — 无需微调、无需重训:

flowchart LR
 subgraph Extract["1. 提取"]
 A[任务] --> B[Tracker Hook]
 B --> C{Session 结束?}
 C -->|阈值满足| D[LLM 提取]
 D --> E[去重 + 写入 L3]
 end
 subgraph Curate["2. 维护"]
 E --> F[Search 命中<br/>递增计数]
 F --> G{90天未用?}
 G -->|是| H[归档]
 I[forget 工具] --> H
 end
 subgraph Graduate["3. 毕业"]
 F --> J{计数 ≥ 5<br/>存活 ≥ 7天?}
 J -->|是| K[SKILL.md]
 K --> L[skill_view]
 end
 style Extract fill:#e8f5e9,stroke:#2e7d32
 style Curate fill:#fff3e0,stroke:#e65100
 style Graduate fill:#e3f2fd,stroke:#1565c0

进化时间线:

核心设计思想:

• 严格拒绝 — 宁可不学也不学错
• stale 是计算属性 — 不写 DB,search 逆转完全自动
• 确定性 + Agent 驱动 — Curator 管时间衰减;forget 管质量判断
• 分布式安全 — Redis SETNX 保证多实例只有一个 Curator 运行

graph TB
 subgraph Channels["🌐 通道"]
 CH[飞书 WebSocket · Web WS · OpenAI SSE]
 end
 subgraph Compute["☁️ 计算层 — 无状态 Worker"]
 direction TB
 Runner["Agent Runner · ~1100 行单循环<br/>Frozen Prefix · Per-Turn Suffix · Prompt 预算"]
 Tools["工具: bash · read · write · edit · grep · glob · web_fetch<br/>memorize · forget · update_working_memory · skill_view"]
 Hooks["Hook: WorkingMemory · MemoryNudge · ToolApproval · SopTracker"]
 CE["Context Engine: assemble + 记忆检索 + compact"]
 Infra["基础设施: TaskManager · Curator · Skill Graduation · Settings"]
 end
 subgraph Storage["💾 存储层"]
 direction TB
 Redis[("Redis<br/>Sessions · 分布式锁 · L1 索引 · Working Memory")]
 Memory[("SQLite + FTS5 + jieba<br/>L2 事实 · L3 流程")]
 Vec[("sqlite-vec<br/>L4 会话归档")]
 Embed["Embedding API · litellm"]
 end
 CH --> Runner
 Runner --> Tools
 Runner --> Hooks
 Runner --> CE
 Hooks --> Redis
 CE --> Memory
 CE --> Vec
 CE --> Embed
 Infra --> Redis
 style Channels fill:#e3f2fd,stroke:#1565c0
 style Compute fill:#f3e5f5,stroke:#6a1b9a
 style Storage fill:#e8f5e9,stroke:#2e7d32

测试统计: 2923 单元/集成测试 + 16 E2E (3 Phase 3 gated) · ~16K 行 Python · ~120 个源文件(截至 2026年05月29日 V1.5 Phase 3 ship)

# L2/L3 检索命中 → 注入到 Prompt 的 Dynamic Zone 作为 <facts> / <procedures> XML
# 每轮 4 层都被检索,结果按优先级混合
# 中文查询直接可用
agent.run("帮我看一下飞书 streaming 模块的 token 限流策略")
# → FTS5 通过 jieba.cut_for_search 匹配 "飞书"+"streaming"+"token"+"限流"
# → Top procedures 被注入 Prompt

class MyCustomHook(AgentHook):
 async def before_prompt_build(self, ctx):
 ctx.append_dynamic("<custom>...自定义内容...</custom>")
 async def after_response(self, ctx, response):
 # 每次回复后自动抽取事实
 ...
agent.hooks.register(MyCustomHook())

graph LR
 subgraph Frozen["❄️ Frozen Prefix(缓存,命中率 90%+)"]
 F[identity · tools · skills · L1 snapshot]
 end
 subgraph Suffix["🔄 Per-Turn Suffix(每轮重建)"]
 S[runtime · working_memory · nudge]
 end
 subgraph Dynamic["🔍 Dynamic Zone(记忆检索)"]
 D[facts · procedures with entry_id]
 end
 Frozen ~~~ Suffix ~~~ Dynamic
 style Frozen fill:#e3f2fd,stroke:#1565c0
 style Suffix fill:#fff3e0,stroke:#e65100
 style Dynamic fill:#e8f5e9,stroke:#2e7d32

curl http://localhost:8000/v1/chat/completions \
 -H "Authorization: Bearer $TOKEN" \
 -d '{"model":"pyclaw","messages":[{"role":"user","content":"hi"}],"stream":true}'

可对接 OpenWebUI / Lobe / NextChat 等任意 OpenAI 兼容客户端。

# docker-compose.yml
services:
 pyclaw:
 deploy: { replicas: 3 } # 3 个 active-active worker
 environment:
 PYCLAW_AFFINITY_ENABLED: "true"
 redis:
 image: redis:7-alpine # 共享状态 + 亲和注册表
 nginx:
 image: nginx:alpine # ip_hash 反向代理
 volumes: [./deploy/nginx.conf:/etc/nginx/conf.d/default.conf]
 ports: ["80:80"]

双层 stickiness 设计:

• Layer 1 — Nginx ip_hash:同一客户端 IP 固定路由到同一 worker(减少 forward 流量)
• Layer 2 — Session 亲和网关:Redis 维护 session_key → worker_id 映射,保证同一 session 永远在同一 worker 处理。Nginx(或飞书 cluster mode)即使把消息分发到别的 worker,亲和层会通过 Redis PubSub 转发到 owner。Worker 死亡时通过 TTL 过期 + force_claim 自动接管。

本地 dev 反向代理(统一入口 localhost:9000 → 3 个 worker):

make worker1 # terminal 1: PORT=8000
make worker2 # terminal 2: PORT=8001
make worker3 # terminal 3: PORT=8002
make nginx-start # 反向代理 :9000
make affinity-status # 任意时刻查 Redis 亲和状态

详情参见 make help 与 reports/affinity-gateway-smoke-2026年05月15日.md(真机 smoke 测试报告)。

📖 完整文章合集 →

系列代号:A(项目认知)· B(竞品解析)· C(上下文)· D(记忆+进化)· E(架构+安全)· F(方法论)

PyClaw 用单个 pyclaw.json 描述所有运行时配置,按 ./pyclaw.json、configs/pyclaw.json、~/.openclaw/pyclaw.json 顺序查找。配置参考文档按 5 个使用场景组织:本地开发、生产单实例、多实例 active-active、Feishu 机器人、记忆 + 自演化。

配置与运维:

• 配置参考(中文) · Configuration reference (EN) — 所有 Settings 字段、env-var 覆盖映射、按场景的最小可用 JSON(5 个场景)
• 部署指南(中文) · Deployment guide (EN) — 本地 dev、单实例 Docker、3-worker active-active(含可跑的 deploy/docker-compose.multi.yml)、无 Docker 的 make worker[1-3]
• 多用户部署(中文) · Multi-user deployment (EN) — UserProfile schema、per-user 默认 tier、role-based 权限(admin / member)、/admin user slash 命令
• configs/pyclaw.example.json — 完整可执行模板(167 行)

安全与集成:

• 权限与工具审批(中文) · Permissions & tool approval (EN) — 三档权限(read-only / approval / yolo)、各 channel UX(Web modal vs 飞书 CardKit)、audit log schema
• 沙箱(中文) · Sandbox (EN) — @anthropic-ai/sandbox-runtime(srt)集成:macOS Seatbelt / Linux bubblewrap+seccomp、BashTool 与 MCP 子进程隔离、8 条不变量 manifest、production_require_sandbox 开关
• MCP 服务器(中文) · MCP servers (EN) — Anthropic Model Context Protocol 集成:stdio server 配置、{env:VAR} 密钥、per-server forced_tier(仅可降级)、/mcp list/restart/logs、非阻塞启动、安全要点

# Skill 管理
pyclaw-skill list # 列出已发现的技能
pyclaw-skill search github # 搜索 ClawHub 市场
pyclaw-skill install github # 安装技能
pyclaw-skill check # 资格检查(bins / env / OS)
# SOP 生命周期管理(Curator)
pyclaw-skill curator list --auto # 活跃的自动提取 SOP
pyclaw-skill curator list --stale # 30+ 天未使用(预警)
pyclaw-skill curator list --archived # 已归档 SOP(含原因)
pyclaw-skill curator restore <id> # 恢复已归档的 SOP
pyclaw-skill curator graduate --preview # 预览毕业候选
pyclaw-skill curator graduate # 执行毕业
pyclaw-skill curator graduate --id <id> # 指定 ID 强制毕业
# 实时记忆观测
.venv/bin/python scripts/verify_memory_live.py # L1/L2/L3/L4 实时监控

# 单元 + 集成(无外部依赖)
.venv/bin/pytest tests/ --ignore=tests/e2e
# 含真实 Redis
PYCLAW_TEST_REDIS_HOST=localhost .venv/bin/pytest tests/integration/
# 真实 LLM E2E
PYCLAW_LLM_API_KEY=sk-... .venv/bin/pytest tests/e2e/

2923 单元/集成测试 · 16 真 LLM E2E(3 Phase 3 gated) · ~16K 行代码 · ~120 个源文件(截至 2026年05月29日 V1.5 Phase 3 ship)。

src/pyclaw/
├── core/ # 计算层(无状态)
│ ├── agent/
│ │ ├── runner.py # ~1100 行单循环
│ │ ├── system_prompt.py # Frozen + Per-Turn 构建器
│ │ ├── tools/ # bash, read, write, edit, grep, glob, web_fetch, memorize, forget, update_working_memory, skill_view (+ fetch_mcp_resource opt-in)
│ │ ├── hooks/ # WorkingMemoryHook, MemoryNudgeHook
│ │ ├── compaction/ # 压缩子系统(planning, dedup, hardening, checkpoint, reasons)
│ │ └── factory.py # 自动装配记忆工具 + Hook
│ ├── context_engine.py # Bootstrap + 记忆检索 + assemble
│ ├── curator.py # 后台 SOP 生命周期管理(扫描 → 归档 → 毕业)
│ ├── sop_extraction.py # LLM SOP 提取(per-session)
│ ├── skill_graduation.py # 高频 SOP 毕业为 SKILL.md
│ ├── memory_archive.py # /new 时后台 L4 归档
│ └── hooks.py # AgentHook / ToolApprovalHook / SkillProvider Protocol
├── storage/
│ ├── memory/ # 4 层记忆(composite, sqlite, redis_index, jieba_tokenizer, embedding)
│ ├── session/ # Redis + InMemory session
│ ├── workspace/ # File + Redis workspace
│ └── lock/ # Redis 分布式锁
├── channels/
│ ├── feishu/ # WS receiver、CardKit 流式、斜杠命令
│ ├── web/ # WebSocket + REST + OpenAI SSE + React SPA + admin
│ └── session_router.py # SessionKey → SessionId 路由
├── skills/ # Skill Hub(parser, discovery, eligibility, prompt, clawhub_client, installer)
├── infra/
│ ├── task_manager.py # 集中式异步生命周期(spawn/cancel/drain)
│ ├── settings.py # MemorySettings, EmbeddingSettings, PromptBudgetConfig
│ └── redis_client.py
├── cli/skills.py # pyclaw-skill CLI
└── app.py # FastAPI 入口 + lifespan

PyClaw 当前的隔离模型是单租户或可信团队 — Session 数据、Redis 键、飞书 Workspace、记忆存储按用户隔离, 但同一份部署内不同团队之间没有租户边界。适用场景: 一个团队跑自己的实例, 或者一份共享实例服务可信内部用户。Web 渠道为信任用户设计(Tool Approval Hook 管控高风险操作)。多租户 SaaS 部署需要走下面的升级路径。

详见 D26: 用户隔离模型 — 隔离边界、已知限制、多租户升级路径。

上手与运维

• 配置参考 — 所有 Settings 字段,按场景组织
• 部署指南 — 本地 dev / 单实例 Docker / 多实例 active-active

架构与设计

• 架构决策(D1–D26) — 全部设计选择与理由
• 会话系统设计 — SessionKey/SessionId、命令、空闲重置
• 上下文引擎 — assemble/ingest/compact Protocol
• 内置工具 — 11 个内置工具、Tier 2 web_fetch / grep / glob、沙箱旁路约定
• Skill Hub 兼容性 — ClawHub 集成 + 7 层跨生态发现
• 用 gpt-image-2 画 infographic 实战指南 — 5 段式 prompt + 文字渲染纪律 + 完整 PyClaw 主图 prompt 解剖
• 开发路线图

英文文档:docs/en/

• ✅ 工具输出压缩器(OH-1) — 4 策略规则管线,bash-heavy session 节省 ~30-50% 输入 token(Sprint 6,2026年05月20日 ship)
• ✅ Frozen Prefix 字节稳定不变量(OH-2) — 14 个测试证明"90%+ prompt 缓存命中"在跨 turn / 跨 section / dict 排序 / budget 截断后均成立(Sprint 6,2026年05月20日 ship)
• ✅ 子代理 omit toggles(OH-3) — omit_memory_context / omit_skills_catalog / omit_working_memory token-economy 专用(Sprint 6,2026年05月20日 ship)
• ✅ Skill Graduation v2(Follow-up B) — auto_generated SKILL.md 可被改进版 SOP 原子替换;旧版备份到 skill_history/<timestamp>(Sprint 7,2026年05月20日 ship)
• ✅ S3 安全三件套 — env deny-floor 扩展(DATABASE_URL/REDIS_URL/DOCKER_HOST/VAULT_TOKEN/VAULT_ADDR)+ srt 版本检查(< 1.0.0 警告;production_require_sandbox=true fail-closed)+ Settings _comment_* 字段 strip(Sprint 7,2026年05月20日 ship)
• ✅ WebSocket 鉴权失败循环修复 — close code 4001/4002/4003 触发 logout() + 跳转登录页,不再无限重连(Sprint 6.1,2026年05月20日 ship)
• ✅ 智能审批(TA1, bash_approval_mode) — read 命令白名单自动放行,消除审批疲劳但不削弱沙箱(Sprint 8,2026年05月20日 ship)
• ✅ S3- deferred 清理(8 fix + advisory + 3 核查后关闭非真问题)* — A13 srt 运行时 fallback / A7 zero-admin / F8 forward-compat / F4 source-grep→behavioral / F2 Windows 路径 / F5 inspect.signature / F7 fixture / B1B2 / E4 / F3+A14 advisory;A8/A11/A12 核查为非真问题(Sprint 9,2026年05月21日 ship)

• ✅ 记忆存储 — 4 层 SQLite-vec + FTS5 + jieba
• ✅ Web 渠道 — 多路复用 WebSocket、OpenAI 兼容 SSE、React SPA
• ✅ Skill Hub — ClawHub SKILL.md 解析、渐进式披露
• ✅ TaskManager — 集中式异步任务生命周期
• ✅ 自我进化 — SOP 提取 + Curator 生命周期 + ForgetTool
• ✅ Session 亲和网关 — Active-active 多 worker、Redis 亲和注册 + PubSub 转发(2026年05月14日 真机 smoke 验证通过)
• ✅ Web UI MVP — Linear/Cursor 风视觉重构(2026年05月15日 ship)
• ✅ MCP 客户端 — Anthropic Model Context Protocol 集成(Sprint 2)
• ✅ 用户隔离 + srt 沙箱 — Per-user tier profile + 角色权限 + Anthropic srt + 11 条架构不变量(Sprint 3,2026年05月16日 ship)
• ✅ Tier 2 内置工具 — 进程内 web_fetch / grep / glob、.claude/skills/ 跨生态 7 源发现(Sprint 4',2026年05月18日 ship)
• ✅ Sub-Agent 系统 (A') — Markdown + YAML frontmatter、5 层 discovery、depth-1、license-clean MIT 分发(Sprint 5,2026年05月18日 上线)

• ✅ Multi-Agent Delegate V1.5 Phase 1 ship 2026年05月22日 — 并行 fan-out + audit batch_id + fail-soft + reducer (4 strategy) + supervisor advisory + max_parallel rate limit。8 V1 不变量保留。Ship report: reports/multi-agent-delegate-v15-phase1-ship-2026年05月22日.md。
• ✅ Multi-Agent Delegate V1.5 Phase 2 ship 2026年05月22日 — streaming sub-agent output: 三点 emit + 250ms 跨兄弟 batching + 6-state 状态机 + Web SPA 5-color 调色板 + 飞书 CardKit subagents_status 元素 + omit_streaming_progress toggle + SubagentProgressEmitter (race-safe _dirty ordering) + Decision 9 sink-bypass-runner 架构。10 commits, 2694→2749 (+55 tests), 0 regression。8 V1 + 4 Phase 1 invariants + OH-2 14 byte-stability 全保留; N=1 byte-identical。Ship report: reports/multi-agent-delegate-v15-phase2-ship-2026年05月22日.md。
• ✅ Multi-Agent Delegate V1.5 Phase 3 ship 2026年05月29日 — supervisor-mediated 跨代理 handoff: 内置 request_handoff tool(sub-agent-only) + AgentManifest.can_handoff_to 二态 hybrid 白名单 + session-keyed Redis-persisted pending_handoffs (sha256-hashed key 防注入) + 确定性 LCS 匹配(NFC + 4-decimal round)+ effective_hop_index 关闭 reducer-merge cap bypass + 4 个 advisory 变体 (A/B/C/D) + 6 个新 audit event 类型。15 commits, 2760→2923 (+163 tests), 0 regression。8 V1 + 9 Phase 1 + 8 Phase 2 + 20 Phase 3 = 51 invariants 全保留。Ship report: reports/multi-agent-delegate-v15-phase3-ship-2026年05月29日.md。

• 🔲 Dreaming 引擎 — Light/Deep/REM 三阶段记忆整理(提取 → 聚类 → 图谱)
• 🔲 PostgreSQL + pgvector — 生产级记忆后端(多 pod K8s 部署)
• 🔲 pyclaw migrate-from-openclaw — 给 OpenClaw 用户的迁移工具(对标 Hermes hermes claw migrate)
• 🔲 Plugin 平台 (B) — 跨 5 类注册表的统一扩展协议;V2+ backlog,触发条件 ≥3 个第三方 plugin 需求 或 PyClaw 用户数 ≥ 10k("marketplace 基建 < 10k 用户 premature")

上面列表是高层 mirror。详细的 sprint 状态、依赖图、ship 报告、活跃 proposal 由维护者私下追踪;对外可见的架构变更通过 pull request 和公众号文章发布(公众号合集)。

PyClaw 受 OpenClaw 启发,并设计为与其技能生态兼容。PyClaw 是独立的 Python 重新实现,不是 fork。它继承了领域模型(Session、Channel、Skill),但以记忆为一等公民重新设计了架构。

PyClaw 和 KnowMe / 知我 是同一作者的姊妹项目,命名都遵循「拼音 + 技术词」模式。两者解决的是 agent-memory 故事的互补两半:

• PyClaw — Agent 运行时(本仓):多通道(飞书 / Web)、4 层 L1-L4 记忆、Sub-agent 系统、沙箱、MCP client。
• KnowMe — MCP-native 本地优先知识库:SQLite + jieba FTS5、Markdown、Obsidian 兼容,对外暴露 5 个只读 MCP tool。

说明:KnowMe 目前是私有仓库(未发布),公开发布预计跟着 v1 ship(约 2026-07)。公开后本节会补上仓库链接。在那之前,把 KnowMe 当作 PyClaw MCP-extension 路线的架构上下文来看就行。

两者怎么协作(KnowMe 公开 + 在 pyclaw.json 里启用之后):

PyClaw agent ──MCP 查询──▶ KnowMe vault (今天已通,只读,
 内部冒烟通过)
 ◀──MCP 写入── KnowMe (规划中,KnowMe v1.5+)
 ─memorize─▶ PyClaw L4 写到 KnowMe vault (规划中)

PyClaw 今天就支持把 KnowMe 当 MCP server 接 — 接线骨架在 configs/pyclaw.json 的 mcp.servers.knowme(schema 见 configs/pyclaw.example.json),默认注释掉 / 关闭,等 KnowMe 公开后启用。内部冒烟(2026年05月18日):list_pages 返已索引 wiki 页、search "pyclaw" 返 jieba 分词后的全文命中。

边界契约(两个项目独立 ship):

• PyClaw 的 MCP client 把 KnowMe 当作有版本号的外部依赖 —— KnowMe tool schema 任何破坏性变更必须先公示再做破坏性提交,changelog 会随 KnowMe 仓公开发布。
• 反向(PyClaw 把自己包装成 MCP server,让 KnowMe 未来的 agent panel 可以调 PyClaw)是一个待立项的 PyClaw OpenSpec change —— 内部跟踪为 pyclaw-mcp-server-package,还没启动。

为什么是这个架构:KB 能力原本是 PyClaw 的 Sprint 4,2026年05月18日 改交给 KnowMe,让 PyClaw 专注 agent runtime、KnowMe 专注 vault,MCP 是两者之间的协议。

微信公众号:Time留痕 — 持续分享 PyClaw 开发历程、AI Agent 架构设计、记忆系统、上下文工程。

欢迎 PR。openspec/ 目录跟踪所有架构变更 — 提交大型 PR 前请阅读活跃的提案。小型 PR(拼写、bug 修复)随时欢迎。

MIT License — 自由使用、修改、分发,包括商业用途。