Metadata-Version: 2.4
Name: zeyi
Version: 0.2.0
Summary: Python rewrite of OpenClaw - a multi-channel AI assistant gateway with compute-storage separation
Author: Zeyi Contributors
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: apsw>=3.45.0
Requires-Dist: docstring-parser<1,>=0.15
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx<1.0,>=0.27.0
Requires-Dist: jieba>=0.42.0
Requires-Dist: litellm>=1.50.0
Requires-Dist: markdownify<1.0,>=0.11.0
Requires-Dist: markitdown[docx,pptx,xlsx]<0.2.0,>=0.1.0
Requires-Dist: mcp<2.0,>=1.12.4
Requires-Dist: pydantic-settings>=2.5.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: sqlite-vec>=0.1.6
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: all
Requires-Dist: lark-oapi<2.0.0,>=1.6.2; extra == 'all'
Requires-Dist: redis[hiredis]>=5.2.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.7.0; extra == 'dev'
Requires-Dist: testcontainers[postgres,redis]>=4.0.0; extra == 'dev'
Provides-Extra: feishu
Requires-Dist: lark-oapi<2.0.0,>=1.6.2; extra == 'feishu'
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.30.0; extra == 'postgres'
Requires-Dist: pgvector>=0.3.0; extra == 'postgres'
Requires-Dist: sqlalchemy[asyncio]>=2.0.0; extra == 'postgres'
Provides-Extra: redis
Requires-Dist: redis[hiredis]>=5.2.0; extra == 'redis'
Description-Content-Type: text/markdown

<div align="center">

# 🐍 Zeyi

**生产级 Python AI Agent 框架 — 4 层持久化记忆 · Hook 驱动架构 · 存算分离**

**中文（当前）** · [English](./README_EN.md) · [📚 公众号 Time留痕 文章合集 →](https://mp.weixin.qq.com/mp/appmsgalbum?__biz=MzY5ODI5NzUwNA==&action=getalbum&album_id=4503553062812516353)

[![License](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](./LICENSE)
[![Python](https://img.shields.io/badge/python-3.12%2B-3776ab.svg?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
[![Tests](https://img.shields.io/badge/tests-2923%20passed-brightgreen.svg?style=flat-square)]()
[![Memory](https://img.shields.io/badge/记忆-4%20层架构%20%E2%9C%93-blueviolet.svg?style=flat-square)]()
[![FTS5](https://img.shields.io/badge/FTS5-jieba%20分词-orange.svg?style=flat-square)]()
[![Channels](https://img.shields.io/badge/通道-飞书%20%2B%20Web-blue.svg?style=flat-square)]()
[![OpenAI Compat](https://img.shields.io/badge/API-OpenAI%20兼容-412991.svg?style=flat-square&logo=openai&logoColor=white)]()

</div>

<br clear="all"/>

![Zeyi Web Channel](./docs/assets/web-channel-chat.png?v=2)

---

## 🎯 定位

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

大多数 AI agent 每次对话都从空白起步：用户不停重复上下文、重复约定、重复工具栈。**Zeyi 押注相反方向：一个嵌入团队沟通平台的 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。开箱即用,第一天就能跑。

### Zeyi 在 agent 版图里的位置 — 以及不在的位置

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

| 路径 | 代表项目 | 优化目标 | 致命短板 |
|------|----------|----------|---------|
| **IDE 编程 agent** | Claude Code · Cursor · OpenCode · Aider | 单个开发者 + 单个编辑器 + 深度代码理解 | 没有团队记忆，没有审批 |
| **OAuth 个人助手** | OpenHuman (21k★, 3 个月) | 100+ OAuth 预接入服务把冷启动时间压到几分钟 | desktop-only，无 server 形态，企业 IT 不允许接 118 个外部 OAuth |
| **自我进化学习型 agent** | Hermes (Nous Research, 160k★) | agent 持续重写自己的 skill 库（自我进化最深） | 单 gateway 假设，没有 server 多 worker 水平扩展 |
| **团队级企业 agent** | **Zeyi** | 团队累积 institutional memory，沙箱 + 审计 + 多 channel 开箱即用 | 冷启动靠对话积累（不接 OAuth），自我进化深度不及 Hermes |

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

### 反向校准 — Zeyi 已经领先的六个维度

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

| 维度 | OpenClaw | Hermes | OpenHuman | **Zeyi** |
|------|----------|--------|-----------|------------|
| **多 worker 水平扩展** | ✅ 多实例 | ❌ 单 gateway | ❌ desktop-only | ✅ Session Affinity Gateway + PubSub 转发 |
| **企业级 OS 沙箱** | ❌ 无内置 | ⚠️ container | ⚠️ Landlock + bwrap | ✅ Anthropic srt + 8 条不变量 + fail-closed |
| **中文 FTS** | ❌ | ❌ | ❌ | ✅ FTS5 + jieba + 停用词 + trigram→jieba 自动迁移 |
| **企业工具审批** | ✅ CardKit | ⚠️ command list | ❌ 仅桌面弹窗 | ✅ Web modal + 飞书 CardKit + originator-only + 三档权限 |
| **跨生态 Skill 发现** | ⚠️ 自家 | ✅ agentskills.io | ⚠️ 自家 + QuickJS | ✅ 7 层 discovery（跨读 Claude Code / OpenCode / Crush / Cursor 等） |
| **测试规模** | N/A | ⚠️ 部分 e2e | ⚠️ 部分 e2e | ✅ **2749** 单元/集成 + 13 真 LLM E2E |

### 适合 / 不适合

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

四条路径的 6,000 字深度对比（含源码级证据 + 5 个借鉴招式 + 反向校准）见公众号文章：[OpenClaw / Hermes / OpenHuman / Zeyi 四种 Agent 架构路径](https://mp.weixin.qq.com/s?__biz=MzY5ODI5NzUwNA==&mid=2247484047&idx=1&sn=8b15ad35cd6d7465550d165901e084f1&scene=21#wechat_redirect)。

---

## ✨ 为什么做 Zeyi？

OpenClaw 是一个优秀的多通道 AI 助手 — 但它的 TypeScript 单体（17,000+ 文件）将计算和存储紧耦合，且缺少生产级的记忆系统。Zeyi 用 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 服务器、工具审批。

### 作为飞书机器人 — 2 分钟

```bash
git clone https://github.com/Timeflys2018/zeyi.git && cd zeyi
python3.12 -m venv .venv && .venv/bin/pip install -e ".[dev]"

# 在 configs/zeyi.json 配置飞书 App 凭证
./scripts/start.sh
```

> 📖 **更多**：完整 `zeyi.json` schema 见 [配置参考](./docs/zh/configuration.md), 或直接复制 [`configs/zeyi.example.json`](./configs/zeyi.example.json)。生产单实例部署：[部署指南 § 单 Docker](./docs/zh/deployment.md)。

### 作为 Web Agent — 2 分钟

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

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

> 📖 **更多**：调整三档权限模型（`read-only` / `approval` / `yolo`）见 [权限指南](./docs/zh/permissions.md)。挂 MCP 服务器（GitHub、filesystem 等）见 [MCP 指南](./docs/zh/mcp.md)。多用户团队部署 + per-user tier 隔离见 [多用户部署](./docs/zh/multi-user-deployment.md)。

### 作为库使用（SDK）

```python
import zeyi
import asyncio

async def main():
    # 零配置启动 — 只需 API key
    client = zeyi.AsyncZeyi(api_key="sk-xxx", model="gpt-4o")
    
    # 一次性调用
    response = await client.run("帮我看一下这个 Python 报错...")
    print(response.text)
    
    # 流式调用
    async for event in client.stream("帮我写个排序算法"):
        match event:
            case zeyi.TextChunk(text=t):
                print(t, end="", flush=True)
            case zeyi.Done(usage=u):
                print(f"\nTokens: {u}")
    
    # 自定义工具
    @client.tools.register(name="query_db", description="查询数据库")
    async def query_db(sql: str, limit: int = 10) -> str:
        return f"执行了 {sql}，返回 {limit} 行"
    
    # 记忆操作
    await client.memory.memorize(session_key="user:alice", content="Alice 偏好 Python 3.12")
    results = await client.memory.search(session_key="user:alice", query="Alice 喜欢什么")
    
    await client.close()

asyncio.run(main())
```

**同步版**（适合脚本）：

```python
import zeyi

client = zeyi.Zeyi(api_key="sk-xxx", model="gpt-4o")
response = client.run("你好")
print(response.text)
client.close()
```

> 📖 **更多示例**：见 [`examples/`](./examples/) 目录（quickstart / custom_tool / memory / embedded_fastapi / sync_usage）。

---

## 🧠 记忆系统（核心特性）

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

```mermaid
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 侧）：

| Hook | 作用 |
|------|------|
| `WorkingMemoryHook` | 每轮注入 `<working_memory>` XML（按 session 的 Redis KV）|
| `MemoryNudgeHook` | 每 10 轮提醒 Agent："考虑使用 `memorize`"。使用后计数器归零 |
| `archive_session_background` | `/new` 时把旧 session 异步归档到 L4 + 向量化（不阻塞）|
| `ContextEngine.assemble` | 按用户提问检索 L2/L3，注入 Top-K 事实 + 流程 |

**Agent 自己调用的工具**：

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

---

## 🔄 自我进化（新功能！）

Zeyi 的 Agent 能**自我改进** — 无需微调、无需重训：

```mermaid
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
```

**进化时间线：**

| 时间 | 发生什么 |
|------|---------|
| 第 1 天 | Agent 正常执行任务 |
| 第 7 天 | 从成功会话中自动提取可复用 SOP |
| 第 30 天 | 未使用的 SOP 标记为 stale（仍可用，CLI 可见） |
| 第 60 天 | Agent 发现过时 SOP 时主动调 `forget` 归档 |
| 第 90 天 | Curator 自动归档仍未使用的 SOP |
| 第 90+ 天 | 高频 SOP 毕业为 SKILL.md（渐进式披露加载） |

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

---

## 🏛 架构图

```mermaid
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
```

---

## 📊 当前状态

| 模块 | 状态 | 亮点 |
|------|------|------|
| **Agent Core** | ✅ | ~1100 行单循环、11 个内置工具（Tier 2:`web_fetch` / `grep` / `glob`）、Hook 系统、5 文件压缩子系统、frozen-prefix byte-stability invariant |
| **记忆系统** | ✅ | 4 层（L1/L2/L3/L4）、FTS5 + jieba、sqlite-vec、trigram → jieba 自动迁移 |
| **上下文引擎** | ✅ | Frozen/Per-Turn 拆分、记忆检索、L1 snapshot、Prompt 预算 |
| **会话存储** | ✅ | Redis（生产）+ InMemory（开发）、SessionKey/SessionId 轮换、DAG 树 |
| **飞书渠道** | ✅ | WebSocket 集群（最多 50 worker）、CardKit 流式、斜杠命令 |
| **Web 渠道** | ✅ | React 19 SPA · Linear/Cursor 视觉 · 执行轨迹 · 多模态 · ⌘K 命令面板 · 键盘快捷键 · 会话 CRUD · OpenAI 兼容 SSE · JWT 认证 · **工具审批 modal + 三档权限 (read-only / approval / yolo)** |
| **工具审批** | ✅ | 端到端接通: WebToolApprovalHook + 飞书 CardKit 交互卡片 (originator-only 授权) · per-turn 切档 · 结构化 JSON audit log。见[权限指南](./docs/zh/permissions.md) |
| **MCP 客户端** | ✅ | stdio 服务器 · `{server}:{tool}` 命名空间 · 信任级别映射含 operator override（仅可降级）· `/mcp list / restart / logs` · 非阻塞启动 + `/health` advisory · `{env:VAR}` 密钥占位符。见 [MCP 指南](./docs/zh/mcp.md) |
| **Skill Hub** | ✅ | ClawHub 兼容、渐进式披露、**7 层目录发现(含 `.claude/skills/` 跨生态读)**、`zeyi-skill` CLI。见 [skill-hub-compatibility.md](./docs/zh/skill-hub-compatibility.md#发现顺序高--低优先级) |
| **内置 Tier 2 工具** | ✅ | 进程内 `web_fetch`(httpx + markdownify)、`grep`(Python `re`,沙箱友好)、`glob`(按 mtime 排序)、可选 `fetch_mcp_resource`。全部 `tool_class="read"`,在 `bash` 被拒的 `tier=read-only` 下仍能用。见 [builtin-tools.md](./docs/zh/builtin-tools.md) |
| **Prompt 工程** | ✅ | `PromptBudgetConfig`、Frozen 缓存、优先级截断 |
| **TaskManager** | ✅ | 集中式异步任务生命周期、K8s 级优雅关闭 |
| **自我进化** | ✅ | SOP 提取 + Curator 生命周期（30d/90d）+ ForgetTool + Skill Graduation v2 (可版本演进) + CLI |
| **Session 亲和网关** | ✅ | Active-active 多 worker 水平扩展、Redis 亲和注册 + PubSub 转发、PUBLISH-0 检测自动 failover |
| **子代理系统** | ✅ | 5 层 discovery、`.md + frontmatter` 清单、独立上下文窗口、tier/sandbox/memory 继承、depth-1 限制、`/agents` 斜杠命令。MIT 许可清洁（零打包 persona）。`omit_memory_context` / `omit_skills_catalog` / `omit_working_memory` toggle 用于 token-economy 专用。见[子代理指南](./docs/zh/subagents.md)。 |
| **工具输出压缩器** | ✅ | 4 策略管线（strip_ansi / regex_replace / collapse_whitespace / head_tail），8 条 builtin 规则覆盖 git/pytest/npm/pip/docker/web_fetch。`enable_output_compression: true` 默认开启，bash-heavy session 节省 ~30-50% 输入 token。借鉴 OpenHuman TokenJuice (clean-room)。 |
| **智能审批 (UX 层)** | ✅ | `bash_approval_mode: "smart"` 自动放行 ~50 个 read 命令(`cat`/`ls`/`git status`/`python -c`/...)；写命令仍走审批 modal/CardKit。Audit log 记 `decided_by="auto:bash-smart-read"`。消除审批疲劳但不削弱沙箱。 |
| **Frozen Prefix 字节稳定** | ✅ | 14 个测试证明"90%+ prompt 缓存命中"声明可验证。OpenHuman KV-cache invariant 的 clean-room 借鉴。 |
| **Multi-Agent Delegate (V1.5 Phase 1 + Phase 2)** | ✅ | **Phase 1**: 并行 fan-out (主代理同 turn N 个 sub_agent tool_call → `asyncio.gather` 并发) + `progress_batch_id` audit 关联 + fail-soft + `max_parallel_per_turn` (默认 5) + `reduce_subagent_results` 4 strategy + supervisor advisory。**Phase 2 (streaming sub-agent output)**: 三点 emit (turn-start / per-tool-start / per-tool-end) + 6-state 状态机 (`thinking` → `tool_calling` → `tool_running` → `completed`/`failed`/`aborted`) + 250ms cross-sibling batching + Web SPA 5-color 调色板 + 飞书 CardKit `subagents_status` 元素 + `omit_streaming_progress` manifest toggle。8 V1 + 4 Phase 1 invariants + OH-2 14 byte-stability 全保留; V1 single-spawn (N=1) byte-identical。**Phase 3** (cross-agent handoff) 等触发条件。**显式不做**：LangGraph DAG runtime、Hermes RPC mesh、token-by-token streaming。 |
| **Dreaming 引擎** | 🔲 | 规划中：Light/Deep/REM 三阶段记忆整理 |

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

---

## 🎬 特性详解

### 4 层记忆 + 中文 FTS5

```python
# L2/L3 检索命中 → 注入到 Prompt 的 Dynamic Zone 作为 <facts> / <procedures> XML
# 每轮 4 层都被检索，结果按优先级混合

# 中文查询直接可用
agent.run("帮我看一下飞书 streaming 模块的 token 限流策略")
# → FTS5 通过 jieba.cut_for_search 匹配 "飞书"+"streaming"+"token"+"限流"
# → Top procedures 被注入 Prompt
```

### Hook 驱动的记忆流水线

```python
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())
```

### Frozen / Per-Turn 三段式 Prompt

```mermaid
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
```

### OpenAI 兼容 API

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

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

### 多实例生产部署

```yaml
# docker-compose.yml
services:
  zeyi:
    deploy: { replicas: 3 }       # 3 个 active-active worker
    environment:
      ZEYI_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）：

```bash
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`](./Makefile) 与 [`reports/affinity-gateway-smoke-2026-05-15.md`](./reports/affinity-gateway-smoke-2026-05-15.md)（真机 smoke 测试报告）。

---

## 📚 深度文章（公众号 Time留痕）

> 📖 **[完整文章合集 →](https://mp.weixin.qq.com/mp/appmsgalbum?__biz=MzY5ODI5NzUwNA==&action=getalbum&album_id=4503553062812516353)**

| 系列 | 标题 | 主题 |
|------|------|------|
| A1 | [从 TypeScript 单体到存算分离](https://mp.weixin.qq.com/s/p4AlkEqj1hBN1MdVOjz9BQ) | 为什么重写 OpenClaw — 三条原则 |
| A2 | [从 6000 行包装到 645 行单循环：我如何重写 OpenClaw 的 Agent 内核](https://mp.weixin.qq.com/s/sGLHdPsMD1vj8CfUTd6PdQ) | 六大 Agent 框架源码级对比（Claude Code / OpenClaw / OpenCode / DeerFlow / GenericAgent / Hermes）|
| D0 | [AI Agent 记忆系统的四种流派](https://mp.weixin.qq.com/s/1ldmhldoAhq25w-Ov0WhgQ) | Karpathy / 火山 / Shopify / YC 四家记忆思路对比 |
| D1 | [你的 AI Agent 为什么总是"失忆"？](https://mp.weixin.qq.com/s/f_hUmwMpTFEPqstC7fBOww) | Zeyi 的 4 层记忆架构设计 |
| D2 | [给 AI Agent 的记忆系统通上电](https://mp.weixin.qq.com/s/T15stlOpvfF1Jd5sQJ4B_g) | 工具设计 + Hook 驱动 + APSW/jieba FTS5 修复 |
| E1 | [给 Agent 加一个"心脏起搏器"：TaskManager 设计](https://mp.weixin.qq.com/s/1q67jEmQzvFJ8Dd6Tq_Ujg) | 异步任务生命周期管理 |
| E11 | [Slash 命令系统：4 层分工驯服 21 个命令](https://mp.weixin.qq.com/s?__biz=MzY5ODI5NzUwNA==&mid=2247483884&idx=1&sn=98ef67ae00eb9c9fedcf78b727e5ad2c&scene=21#wechat_redirect) | CommandRegistry + ProtocolOp + Hook 多层分工 |
| E12 | [Session Affinity Gateway：N worker 水平扩展](https://mp.weixin.qq.com/s?__biz=MzY5ODI5NzUwNA==&mid=2247483904&idx=1&sn=e0ab6d023825f5ea48510bbda74e4ddc&scene=21#wechat_redirect) | Affinity 双层 stickiness + (N-1)/N 转发 |
| E17 | [权限系统：4 层 tier × per-user × per-MCP-server](https://mp.weixin.qq.com/s?__biz=MzY5ODI5NzUwNA==&mid=2247484004&idx=1&sn=afa215cd98ebaf7e5c94a34fa4e0b8d8&scene=21#wechat_redirect) | 工具审批系统四阶段演化 |
| E18 | [运行时沙箱：基于 Anthropic srt 的系统实现](https://mp.weixin.qq.com/s?__biz=MzY5ODI5NzUwNA==&mid=2247484020&idx=1&sn=65972af44e09dcd6b16577f0c08d111e&scene=21#wechat_redirect) | 8 条架构不变量 + SandboxPolicy Protocol 三件套 |
| E21 | [Sub-Agent 系统的 8 条架构不变量](https://mp.weixin.qq.com/s?__biz=MzY5ODI5NzUwNA==&mid=2247484029&idx=1&sn=40a0b8cadc3ae3c02be44a6a4b0575af&scene=21#wechat_redirect) | Markdown manifest → isolated executor 全景 |
| F13 | [stub-and-revert 测试方法论](https://mp.weixin.qq.com/s?__biz=MzY5ODI5NzUwNA==&mid=2247484041&idx=1&sn=4b5d9b8d0af38197bacd434f143d9743&scene=21#wechat_redirect) | unit + e2e 全绿不代表无错 |
| B1 | [四种 Agent 架构路径：OpenClaw / Hermes / OpenHuman / Zeyi](https://mp.weixin.qq.com/s?__biz=MzY5ODI5NzUwNA==&mid=2247484047&idx=1&sn=8b15ad35cd6d7465550d165901e084f1&scene=21#wechat_redirect) | 四方对比 + 5 个借鉴招式 + 反向校准 |

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

---

## ⚙️ 配置 & 部署

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

**配置与运维：**

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

**安全与集成：**

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

---

## 🛠 CLI 工具

```bash
# Skill 管理
zeyi-skill list                    # 列出已发现的技能
zeyi-skill search github           # 搜索 ClawHub 市场
zeyi-skill install github          # 安装技能
zeyi-skill check                   # 资格检查（bins / env / OS）

# SOP 生命周期管理（Curator）
zeyi-skill curator list --auto     # 活跃的自动提取 SOP
zeyi-skill curator list --stale    # 30+ 天未使用（预警）
zeyi-skill curator list --archived # 已归档 SOP（含原因）
zeyi-skill curator restore <id>    # 恢复已归档的 SOP
zeyi-skill curator graduate --preview  # 预览毕业候选
zeyi-skill curator graduate            # 执行毕业
zeyi-skill curator graduate --id <id>  # 指定 ID 强制毕业

# 实时记忆观测
.venv/bin/python scripts/verify_memory_live.py   # L1/L2/L3/L4 实时监控
```

---

## 🧪 测试

```bash
# 单元 + 集成（无外部依赖）
.venv/bin/pytest tests/ --ignore=tests/e2e

# 含真实 Redis
ZEYI_TEST_REDIS_HOST=localhost .venv/bin/pytest tests/integration/

# 真实 LLM E2E
ZEYI_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/zeyi/
├── 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             # zeyi-skill CLI
└── app.py                    # FastAPI 入口 + lifespan
```

---

## 🛡 安全与隔离

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

详见 [D26: 用户隔离模型](./docs/zh/architecture-decisions.md) — 隔离边界、已知限制、多租户升级路径。

---

## 📖 文档

**上手与运维**

- [配置参考](./docs/zh/configuration.md) — 所有 Settings 字段，按场景组织
- [部署指南](./docs/zh/deployment.md) — 本地 dev / 单实例 Docker / 多实例 active-active

**架构与设计**

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

英文文档：[docs/en/](./docs/en/)

---

## 🗺 路线图

### 最近 ship（Sprint 6 / 7 / 8）

- ✅ **工具输出压缩器（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）

### 早期（Sprint 1–5）

- ✅ 记忆存储 — 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 上线）

### 调研中（active）

- ✅ **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 部署）
- 🔲 **`zeyi migrate-from-openclaw`** — 给 OpenClaw 用户的迁移工具（对标 Hermes `hermes claw migrate`）
- 🔲 **Plugin 平台 (B)** — 跨 5 类注册表的统一扩展协议；**V2+ backlog**，触发条件 ≥3 个第三方 plugin 需求 或 Zeyi 用户数 ≥ 10k（"marketplace 基建 < 10k 用户 premature"）

> 上面列表是高层 mirror。详细的 sprint 状态、依赖图、ship 报告、活跃 proposal 由维护者私下追踪；对外可见的架构变更通过 pull request 和公众号文章发布（[公众号合集](https://mp.weixin.qq.com/mp/appmsgalbum?__biz=MzY5ODI5NzUwNA==&action=getalbum&album_id=4503553062812516353)）。

---

## 🤝 与 OpenClaw 的关系

Zeyi 受 [OpenClaw](https://github.com/openclaw/openclaw) 启发，并设计为与其技能生态兼容。Zeyi 是**独立的 Python 重新实现**，不是 fork。它继承了领域模型（Session、Channel、Skill），但以**记忆为一等公民**重新设计了架构。

---

## 🧩 姊妹项目：KnowMe / 知我（暂未发布）

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

- **Zeyi** — **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 当作 Zeyi MCP-extension 路线的架构上下文来看就行。

**两者怎么协作**（KnowMe 公开 + 在 `zeyi.json` 里启用之后）：

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

Zeyi 今天就支持把 KnowMe 当 MCP server 接 — 接线骨架在 `configs/zeyi.json` 的 `mcp.servers.knowme`（schema 见 [`configs/zeyi.example.json`](./configs/zeyi.example.json)），**默认注释掉 / 关闭**，等 KnowMe 公开后启用。内部冒烟（2026-05-18）：`list_pages` 返已索引 wiki 页、`search "zeyi"` 返 jieba 分词后的全文命中。

**边界契约**（两个项目独立 ship）：

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

**为什么是这个架构**：KB 能力原本是 Zeyi 的 Sprint 4，2026-05-18 改交给 KnowMe，让 Zeyi 专注 agent runtime、KnowMe 专注 vault，MCP 是两者之间的协议。

---

## 📡 关注我们

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

<div align="center">

<img src="./docs/assets/Time留痕.jpg" width="180" alt="微信公众号 Time留痕" />

📚 **[完整文章合集 →](https://mp.weixin.qq.com/mp/appmsgalbum?__biz=MzY5ODI5NzUwNA==&action=getalbum&album_id=4503553062812516353)**

</div>

---

## 🤝 参与贡献

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

---

## 📜 许可证

[MIT License](./LICENSE) — 自由使用、修改、分发，包括商业用途。
