# https://github.com/EverMind-AI/EverOS 项目说明书

生成时间：2026-06-23 07:37:37 UTC

## 目录

- [page-overview-architecture](#page-overview-architecture)
- [page-api-cli](#page-api-cli)
- [page-memory-pipeline](#page-memory-pipeline)
- [page-deploy-ops](#page-deploy-ops)

<a id='page-overview-architecture'></a>

## page-overview-architecture

```markdown
<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [use-cases/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/README.md)
- [src/everos/entrypoints/cli/__init__.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/__init__.py)
- [src/everos/entrypoints/cli/commands/__init__.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/commands/__init__.py)
- [src/everos/entrypoints/api/routes/memorize.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/routes/memorize.py)
- [use-cases/game-of-throne-demo/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/README.md)
- [use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts)
- [use-cases/game-of-throne-demo/backend/src/services/OpenAIService.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/src/services/OpenAIService.ts)
- [use-cases/claude-code-plugin/commands/ask.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/claude-code-plugin/commands/ask.md)

</details>

# page-overview-architecture

## 项目概览与设计哲学

EverOS 是由 EverMind-AI 发布的开源 AI 记忆基础设施项目，为基于大语言模型（LLM）的应用提供长期、可检索、可治理的记忆能力。其核心定位是充当"AI 记忆中间层"——在 LLM 推理与外部数据源之间插入一层持久化语义存储，使智能体能够跨会话、跨用户保留上下文。仓库围绕"先契约、后实现"的工程原则组织：上层暴露 CLI 与 HTTP API 两种入口，下层由统一的记忆引擎与向量/文档后端协同完成记忆的写入、抽取与回溯。

在公开基准上，EverOS 在 LoCoMo 测试集上达到 92.3% 的成绩，显著高于此前约 84–85% 的 SOTA（社区议题 #3）。围绕该成绩，社区还关注评测所用 CoT 回答 prompt 的具体内容（#205）以及单次查询的 token 消耗统计口径（#56，论文中 2.5K 数值覆盖"记忆生成 + 检索回答"两阶段）。

## 系统架构

EverOS 的整体架构可划分为四层：客户端与 Agent、上层入口（API/CLI）、核心记忆引擎、底层存储后端。`use-cases/README.md` 中展示的 Reunite、Hive Orchestrator、Claude Code 插件、可穿戴设备等十余个集成案例都遵循这一分层模型接入。

```mermaid
graph LR
  subgraph 客户端
    A1[聊天 Agent]
    A2[IDE 插件]
    A3[可穿戴 / 游戏 NPC]
  end
  subgraph 入口层
    B1[API Routes<br/>memorize.py]
    B2[CLI<br/>typer subcommands]
  end
  subgraph 核心引擎
    C1[记忆写入 / 抽取]
    C2[语义检索 / 引用]
    C3[回答生成]
  end
  subgraph 存储后端
    D1[(向量库)]
    D2[(文档库)]
    D3[(元数据)]
  end
  A1 --> B1
  A2 --> B2
  A3 --> B1
  B1 --> C1
  B2 --> C1
  C1 --> D1
  C1 --> D2
  C1 --> D3
  C2 --> D1
  C3 --> C2
```

## 核心入口与数据契约

CLI 与 API 是与引擎交互的两条主路径。CLI 模块以"contract-first"为原则，默认输出 JSON 并支持 `--describe` 机读模式，便于脚本编排（[src/everos/entrypoints/cli/__init__.py:1-5](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/__init__.py)）；子命令通过 `typer.Typer` 实例挂载在 `commands/` 目录下统一注册（[src/everos/entrypoints/cli/commands/__init__.py:1-7](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/commands/__init__.py)）。

HTTP API 端，`memorize` 路由定义了 `MemorizeAddRequest`、`MessageItemDTO` 等 Pydantic 模型，对 `session_id`、`app_id`、`project_id`、`sender_id` 等字段施加统一字符集白名单与长度约束（[src/everos/entrypoints/api/routes/memorize.py:50-130](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/routes/memorize.py)）。时间戳字段约定为 Unix **毫秒**，算法层对秒/毫秒自动检测以保持向后兼容。1.0.1 版本进一步将 `sender_id` 纳入路径安全校验（白名单 + 拒绝 `.` / `..`），并通过 `MarkdownWriter` 强化写入目标的纵深防御，这是对调用方可控标识符与下游落盘路径的同步加固。

| 入口 | 典型用途 | 关键约束 |
| --- | --- | --- |
| `POST /api/v3/agentic/memorize` | 写入结构化对话 | `sender_id`/`app_id` 路径安全，时间戳 ms |
| `CLI` 子命令 | 批处理 / 评测 | JSON 输出、`--describe` 机读 |
| 检索类 API（V3） | 语义召回 | 与写入同一 ID 体系 |

社区在 #14 中提出的"删除/重置记忆"端点目前尚未在 V3 API 中提供，生产集成需结合上层业务自行实现会话清理。

## 应用生态与典型用例

`use-cases/` 目录既是产品演示，也是参考集成范式。`game-of-throne-demo` 通过 `IMemoryService` 接口抽象出"检索 → 上下文注入 → 流式回答"的标准三步（[use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts:1-22](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts)），并由 `OpenAIService` 负责回答生成与追问建议（[use-cases/game-of-throne-demo/backend/src/services/OpenAIService.ts:1-40](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/src/services/OpenAIService.ts)）。该 demo 同时暴露"带记忆 vs 不带记忆"的并排对比 UI，以可视化方式展示记忆带来的回答质量增益（[use-cases/game-of-throne-demo/README.md:1-30](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/README.md)）。

针对编码 Agent 场景，`claude-code-plugin/commands/ask.md` 定义了 `evermem_search` MCP 工具的调用范式：先以 10 条结果首搜，再依相关性追加最多 3 次精搜，并在回答中显式区分"来自记忆 / 来自当前会话 / 来自通用知识"三类来源（[use-cases/claude-code-plugin/commands/ask.md:1-30](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/claude-code-plugin/commands/ask.md)）。`use-cases/README.md` 进一步汇总了 Reunite、Hive、EOS MCP、可穿戴 NPC 等十余个真实集成，构成项目的"应用图谱"。

## See Also

- [page-api-memorize](page-api-memorize.md) — `/api/v3/agentic/memorize` 端点的请求/响应细节
- [page-cli-overview](page-cli-overview.md) — CLI 子命令与 JSON 契约
- [page-usecase-pattern](page-usecase-pattern.md) — 标准三步集成（检索 → 注入 → 回答）参考实现
- [page-security-1.0.1](page-security-1.0.1.md) — 路径遍历加固与 `MarkdownWriter` 纵深防御说明

---

<a id='page-api-cli'></a>

## page-api-cli

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- `src/everos/entrypoints/api/app.py`
- `src/everos/entrypoints/api/routes/__init__.py`
- `src/everos/entrypoints/api/routes/memorize.py`
- `src/everos/entrypoints/api/routes/get.py`
- `src/everos/entrypoints/api/routes/health.py`
- `src/everos/entrypoints/api/lifespans/__init__.py`
- `src/everos/entrypoints/api/lifespans/ome.py`
- `src/everos/entrypoints/cli/__init__.py`
- `src/everos/entrypoints/cli/commands/__init__.py`
- `src/everos/README.md`

</details>

# page-api-cli

本页说明 EverOS 中"API 与 CLI 入口层"（`everos.entrypoints`）的设计与职责。该层是整个 `everos` 包对外暴露能力的两个门面：HTTP FastAPI 服务与命令行工具，二者均以"契约优先（contract-first）"为原则复用下层 `service` 与 `memory` 模块。

## 1. 概述与设计原则

`everos` 包采用单向依赖的分层架构：`entrypoints → service → memory → infra`，其中 `entrypoints` 子包是唯一的"展示层（presentation）"，负责把领域用例（记忆写入、检索、列表查询等）翻译成外部协议。资料来源：[src/everos/README.md:13-17]()

入口层的两个分支：

| 入口形态 | 主要模块 | 适用场景 |
| --- | --- | --- |
| HTTP API | `everos.entrypoints.api` | 长连接服务、嵌入式集成、SDK 调用 |
| CLI | `everos.entrypoints.cli` | 批处理运维、脚本化评测、CI 中调用 |

CLI 模块在 docstring 中明确写出三条契约：默认输出 JSON、机器可读的 `--describe` 模式、细粒度退出码。资料来源：[src/everos/entrypoints/cli/__init__.py:1-8]() 这意味着 CLI 不仅是"给人用的工具"，也是评测流水线（如 LoCoMo、HyperMem）的可编程调用面。

## 2. HTTP API 入口

### 2.1 应用工厂与中间件栈

`create_app()` 工厂函数负责装配 CORS、Profile 中间件、Prometheus 中间件、全局异常处理器以及 lifespan。文档端点（`/docs`、`/redoc`、`/openapi.json`）仅在 `ENV=DEV` 时启用，生产环境默认隐藏。资料来源：[src/everos/entrypoints/api/app.py:1-50]()

路由注册遵循统一约定：每个子模块导出一个名为 `router` 的 `APIRouter`，由工厂函数通过 `app.include_router` 装配。资料来源：[src/everos/entrypoints/api/routes/__init__.py:1-7]()

### 2.2 路由契约

当前仓库暴露的核心路由包括：

- `POST /api/v1/memory/get`：分页列出指定 `memory_type` 下的记忆；`FilterError` 会被映射为 HTTP 422。资料来源：[src/everos/entrypoints/api/routes/get.py:11-23]()
- `POST /api/v1/memory/memorize`（v1 契约附录 A）：承载 `MemorizeAddRequest`、`MessageItemDTO`、`ContentItemDTO` 等 DTO；时间戳按 v1 契约为毫秒。资料来源：[src/everos/entrypoints/api/routes/memorize.py:23-58]()
- `GET /health`：存活性探针，固定返回 `{"status":"ok"}`。资料来源：[src/everos/entrypoints/api/routes/health.py:7-10]()

### 2.3 Lifespan 编排

API 启动时按 `order` 顺序组合多个 `LifespanProvider`：`LLMLifespanProvider`、`SqliteLifespanProvider`、`LanceDBLifespanProvider`、`CascadeLifespanProvider`、`OmeLifespanProvider`，每个 provider 只负责一类资源（LLM 客户端、SQLite、向量库、级联存储、OME 引擎）。这种"按资源拆分 lifespan"的设计让 CLI、批量 worker 等其他部署形态可以自由裁剪。资料来源：[src/everos/entrypoints/api/lifespans/__init__.py:1-36]()

以 `OmeLifespanProvider` 为例：启动时通过 `everos.service.memorize._get_engine()` 拿到 OME 引擎单例并 `await engine.start()`；关闭时调用 `await engine.stop()`。该 provider 默认 `order=50`，位于其他存储 provider 之后启动，确保下游资源就绪。资料来源：[src/everos/entrypoints/api/lifespans/ome.py:17-39]()

```mermaid
flowchart TD
  Client[客户端] -->|HTTP| App[create_app]
  App --> Cors[CORS]
  App --> Profile[ProfileMiddleware]
  App --> Prom[PrometheusMiddleware]
  App --> Routers[Routes: get / memorize / health]
  Routers --> Service[service.memorize / service.get]
  Service --> Memory[memory 包: extract / search / get]
  Memory --> Infra[(SQLite + LanceDB + Markdown)]
  App -.lifespan.-> LS1[LLMLifespanProvider]
  App -.lifespan.-> LS2[SqliteLifespanProvider]
  App -.lifespan.-> LS3[LanceDBLifespanProvider]
  App -.lifespan.-> LS4[CascadeLifespanProvider]
  App -.lifespan.-> LS5[OmeLifespanProvider]
  LS5 --> Engine[OfflineEngine 单例]
```

### 2.4 入参校验与安全

`MemorizeAddRequest` 与 `MessageItemDTO` 使用 `PathSafeId` 字段并约束 `min_length=1 / max_length=128`，配合 `_PATH_SAFE_CHARSET` 正则拒绝路径穿越。EverOS 1.0.1 发布说明进一步指出 `sender_id` 也已加入相同的路径安全保护，并允许 `@` 与 `+` 以兼容 email 与 plus-addressing 形式的标识符。这与社区 Issue #14 中关于"V3 缺少删除/重置记忆 API"的诉求相呼应——任何写入路径都必须经过同样的白名单校验。资料来源：[src/everos/entrypoints/api/routes/memorize.py:7-19]()

## 3. CLI 入口

CLI 由 `everos.entrypoints.cli.main` 作为根 Typer 应用，再把 `everos.entrypoints.cli.commands` 下每个子模块暴露的 `app: typer.Typer` 挂载为子命令组。每个子命令遵循 JSON 输出 + `--describe` 自描述 + 退出码语义三件套，便于：

- 评测脚本解析（LoCoMo、HyperMem 等场景下调用方需要可机读输出）；资料来源：[src/everos/entrypoints/cli/__init__.py:1-8]()
- 子命令实现细节与 HTTP 路由一一对应，共享 `service` 层逻辑。资料来源：[src/everos/entrypoints/cli/commands/__init__.py:1-7]()

> 社区参考：Issue #195 报告 HyperMem 评测流水线 stage2 耗时超过 4 小时，CLI 是定位阶段、跳过已完成 case 的主要工具；Issue #56 关于 token 消耗统计也依赖 CLI 输出结构化字段。建议在编写评测脚本前先运行对应子命令的 `--describe` 确认字段含义。

## 4. See Also

- `src/everos/README.md` — 包级分层与依赖规则
- 领域模块：`memory.get`、`memory.search`、`memory.extract`
- 服务编排：`service.memorize`、`service.get`
- 基础设施：`infra.persistence.markdown` / `sqlite` / `lancedb`
- 迁移与发布说明：`docs/migration-to-1.0.0.md`、EverOS 1.0.1 发布说明（路径安全加固）

---

<a id='page-memory-pipeline'></a>

## page-memory-pipeline

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/everos/entrypoints/api/routes/memorize.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/routes/memorize.py)
- [src/everos/entrypoints/api/routes/get.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/routes/get.py)
- [src/everos/entrypoints/cli/__init__.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/__init__.py)
- [use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts)
- [use-cases/game-of-throne-demo/frontend/src/types/index.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/frontend/src/types/index.ts)
- [use-cases/claude-code-plugin/commands/ask.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/claude-code-plugin/commands/ask.md)
- [use-cases/claude-code-plugin/commands/help.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/claude-code-plugin/commands/help.md)
- [use-cases/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/README.md)

</details>

# page-memory-pipeline

## 一、概述与定位

EverOS 的 Memory Pipeline（记忆管道）是系统对外提供"长期记忆"能力的核心数据通路，覆盖**写入、检索、列举**三大阶段。管道一端连接客户端应用（聊天机器人、AI 编程助手、游戏 NPC 等），另一端连接底层的记忆存储与算法服务层（`service/`），将原始消息流转化为可被语义检索的"记忆单元"。

- 写入阶段由 `POST /api/v1/memory/memorize` 等路由承接，对应源文件 [src/everos/entrypoints/api/routes/memorize.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/routes/memorize.py)。该 DTO 显式约束 `sender_id`、`app_id`、`project_id` 等字段必须匹配路径安全字符集，并在 v1 API 契约中要求 `timestamp` 使用 Unix 毫秒时间戳。
- 检索/列举阶段由 `POST /api/v1/memory/get` 提供分页能力，对应源文件 [src/everos/entrypoints/api/routes/get.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/routes/get.py)，其将 `FilterError` 映射为 HTTP 422。
- CLI 入口 [src/everos/entrypoints/cli/__init__.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/__init__.py) 采用"契约优先"设计，默认输出 JSON，并通过 `--describe` 提供机器可读模式。

> 社区反馈（Issue #14）指出，当前 V3 API 仅支持 `memorize` 与 `search`，缺少删除/重置接口，这在编辑聊天或清空上下文场景下是显著的体验缺口，相关讨论将影响 Memory Pipeline 未来的写后管理能力扩展。

## 二、管道的数据形态

Memory Pipeline 在不同阶段呈现出三种典型数据结构：

1. **入站消息**：客户端提交的 `MessageItemDTO`，包含 `sender_id`、`role`、`timestamp`、`content`（可为字符串或 `ContentItemDTO` 列表，支持 text/image/audio/doc/pdf/html/email 等多种类型）。资料来源：[src/everos/entrypoints/api/routes/memorize.py:MessageItemDTO]()
2. **记忆单元（Memory）**：经算法层抽取后的产物，字段包括 `id`、`content`、`metadata`，以及来自 EverMind Cloud API 的富化字段 `subject`（标题）、`summary`（摘要）、`episode`（带时间戳的叙事）、`originalContent`（原文）。资料来源：[use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts:Memory]()
3. **检索响应**：包含 `relevanceScore` 评分与上述所有富化字段，供前端做引用标注。资料来源：[use-cases/game-of-throne-demo/frontend/src/types/index.ts:Memory]()

```mermaid
flowchart LR
  A[客户端消息] -->|POST /memorize| B[DTO 校验层]
  B --> C[Service 层抽取/索引]
  C --> D[(记忆存储)]
  D -->|POST /search /get| E[检索服务]
  E --> F[带 relevanceScore 的 Memory 列表]
  F --> G[前端引用渲染]
```

## 三、前后端协作模式

使用案例（如 `game-of-throne-demo`）展示了管道在前端层的完整闭环：

- **侧栏渲染**：[MemoryPanel.tsx](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/frontend/src/components/MemoryPanel.tsx) 列出 `Retrieved Memories`，每条 `MemoryCard` 支持展开 `originalContent` 原文，并在引用点击时触发高亮动画（通过 `memory-highlighted` CSS 类实现）。
- **对比视图**：[ComparisonView.tsx](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/frontend/src/components/ComparisonView.tsx) 同时呈现"有记忆"与"无记忆"两条流式响应，仅在记忆侧生成 `Follow-ups`，并通过 `markdownComponents` 将 `memory [n]` 引用替换为可点击的 `Citation` 徽章。
- **SSE 事件协议**：`SSEEvent` 类型定义包含 `memories`、`token`、`done`、`followups`、`error`、`complete` 等事件，`stream` 字段区分 `withMemory` 与 `withoutMemory` 两条流。资料来源：[use-cases/game-of-throne-demo/frontend/src/types/index.ts:SSEEvent]()

## 四、插件层与命令面

Claude Code 插件通过 MCP 工具暴露了 Memory Pipeline 的检索入口。在 `ask.md` 中，模型被指示先用 `evermem_search` 取回 10 条结果，必要时切换关键词重试最多 3 次，并在最终答复中显式标注信息来源于"记忆"、"当前会话"还是"通用知识"。资料来源：[use-cases/claude-code-plugin/commands/ask.md]()

`help.md` 进一步定义了用户面命令：`/evermem:help`、`/evermem:search <query>`、`/evermem:hub`、`/evermem:debug`、`/evermem:projects`，并声明在每次提示提交时自动检索、每次回复完成时自动保存的隐式管道行为。资料来源：[use-cases/claude-code-plugin/commands/help.md]()

## 五、典型失败模式

| 场景 | 表现 | 触发位置 |
|------|------|----------|
| 过滤 DSL 非法 | HTTP 422 + 编译错误信息 | `routes/get.py` 中 `FilterError` 分支 |
| 路径不安全标识符 | 校验拒绝（白名单 + `.` / `..` 黑名单） | `routes/memorize.py` 的 `PathSafeId` |
| 时间戳单位混淆 | v1 契约要求 ms，算法规层自动检测 sec/ms | `routes/memorize.py` 中 `timestamp` 字段说明 |
| 记忆检索为空 | 前端 `MemoryPanel` 显示 `No memories retrieved yet` | `MemoryPanel.tsx` 空状态分支 |

> 社区反馈（Issue #195、#56）也提示了运营层面的常见问题：HyperMem Evaluation Pipeline 第二阶段可能耗时超过 4 小时；论文中报告的 token 消耗（如 LoCoMo 上 2.5K）覆盖了记忆生成与检索两部分的总和，集成方在成本估算时需将这两段一并计入。

## See Also

- [API 参考：memorize / get 路由](../api/routes.md)
- [CLI 入口与 `--describe`](../cli/entrypoint.md)
- [Game of Thrones Demo 架构](../use-cases/game-of-throne-demo.md)
- [Claude Code 插件命令集](../use-cases/claude-code-plugin.md)

---

<a id='page-deploy-ops'></a>

## page-deploy-ops

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [use-cases/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/README.md)
- [src/everos/README.md](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/README.md)
- [src/everos/entrypoints/cli/__init__.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/__init__.py)
- [src/everos/entrypoints/cli/commands/__init__.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/commands/__init__.py)
- [src/everos/entrypoints/api/routes/memorize.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/routes/memorize.py)
- [use-cases/game-of-throne-demo/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/README.md)
- [use-cases/game-of-throne-demo/backend/package.json](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/package.json)
- [use-cases/game-of-throne-demo/frontend/package.json](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/frontend/package.json)
- [use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts)
- [use-cases/game-of-throne-demo/frontend/src/types/index.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/frontend/src/types/index.ts)

</details>

# page-deploy-ops

本页面聚焦于 EverOS 在部署与运维（Deploy & Operations）层面的可见入口，包括包结构划分、命令行（CLI）入口、HTTP API 入口以及 use-cases 目录中演示应用的部署形态，用于辅助运维人员快速理解系统的可部署面与运行边界。

## 一、包结构与依赖方向

EverOS Python 包的目录划分清晰地界定了各层的部署角色。包顶层 README 指出，源代码被拆分为 `entrypoints`（表现层）、`service`（应用层）、`memory`（领域层）、`infra`（基础设施层）、`component`（横切关注点）、`core`（运行时基座）以及 `config`（配置）七个子包。

资料来源：[src/everos/README.md:1-22]()

依赖方向被显式约束为：

```
entrypoints → service → memory → infra
                    ↓
              component / core / config
```

该依赖规则在 CI 中由 `import-linter` 强制执行，使得"表现层—应用层—领域层—基础设施层"四层架构在打包与镜像构建时具有可预测的依赖闭包，便于运维团队对构建产物（如 Wheel 镜像或容器镜像）做最小化裁剪。

## 二、CLI 入口与 API 入口

### 2.1 命令行入口

CLI 模块的初始化文件声明其采用"Contract-first"设计，默认输出 JSON，并提供 `--describe` 机器可读模式与细粒度的退出码。资料来源：[src/everos/entrypoints/cli/__init__.py:1-5]()

子命令模块统一在 `src/everos/entrypoints/cli/commands/` 下注册，每个子模块导出一个 `app: typer.Typer` 实例，并由 `everos.entrypoints.cli.main` 挂载为子命令组。资料来源：[src/everos/entrypoints/cli/commands/__init__.py:1-7]()

这种基于 Typer 的设计使 CLI 在容器或 Cron 场景下可以无交互地执行，并为后续接入运维平台的脚本化任务（如批量回填、健康巡检、灾备演练）提供统一的返回码体系。

### 2.2 HTTP API 入口

API 路由层在 `src/everos/entrypoints/api/routes/` 下注册。`memorize.py` 中定义了 V3 API 的请求 DTO，包括：

- `MessageItemDTO`：包含 `sender_id`、`sender_name`、`role`、`timestamp`（Unix 毫秒）、`content` 等字段；
- `sender_id` 与 `app_id` / `project_id` 共享同一条路径安全（Path-Safe）规则，使用 `_PATH_SAFE_CHARSET` 白名单并拒绝 `.` / `..` 令牌，白名单额外放行 `@` 与 `+` 以兼容邮箱式 ID 与加号寻址。

资料来源：[src/everos/entrypoints/api/routes/memorize.py:1-44]()

EverOS 1.0.1 版本（最新发布）进一步强化了该路径安全防护，并要求 `MarkdownWriter` 拒绝任何越权写入目标。运维人员部署时需确保反向代理或 API Gateway 不会绕过 Pydantic 校验直接转发原始请求体。

## 三、Use Cases 部署形态

`use-cases/README.md` 展示了系统在不同产品形态下的部署参考，部分案例内嵌在仓库中，部分则链接到外部仓库或演示。

| 形态 | 部署位置 | 技术栈摘要 |
| --- | --- | --- |
| Game of Thrones 记忆演示 | `use-cases/game-of-throne-demo/`（内置） | React 18 + TypeScript + Vite 前端；Express + Bun 后端；Claude Haiku via OpenRouter |
| Claude Code 插件 | `use-cases/claude-code-plugin/`（内置） | 复用 EverOS 记忆 API |
| Reunite / Hive / Multi-Agent 编排 | 外部仓库 | 集成 EverOS 长期记忆层 |
| Live2D 语音助手 | 外部仓库 | TEN Framework + EverMemOS |
| 阿尔茨海默症记忆助手 MemoCare | 外部仓库 | 独立客户端 + EverOS 后端 |

资料来源：[use-cases/README.md:1-80]()；[use-cases/game-of-throne-demo/README.md:1-30]()

以内置的 `game-of-throne-demo` 为例，前端通过 `package.json` 声明 `vite` 构建脚本，后端通过 `package.json` 声明 `bun --watch src/server.ts` 开发模式与 `bun src/server.ts` 生产模式，二者通过 `cors` 与 `express` 暴露 SSE 流式响应。资料来源：[use-cases/game-of-throne-demo/backend/package.json:1-30]()；[use-cases/game-of-throne-demo/frontend/package.json:1-30]()

后端通过 `IMemoryService` 接口与 EverOS 记忆后端解耦，仅依赖 `retrieveMemories`、`isAvailable` 与可选的 `clearMemories` 三个方法，便于在测试或灰度环境中替换为 Mock 实现。资料来源：[use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts:1-25]()

## 四、常见运维关注点

综合社区反馈与代码现状，部署与运维阶段需特别关注以下事项：

1. **LoCoMo 等基准评估耗时**。社区 #195 指出 HyperMem 评估流水线 Stage 2 耗时超过 4 小时，这通常与向量检索的 batch 大小、Embedding 并发度相关；运维侧应预留独立的评估 Worker 节点，避免污染在线请求。资料来源：[use-cases/README.md:1-80]()

2. **Token 消耗的可观测性**。社区 #56 询问论文中报告的 2.5K token 是否包含"记忆生成 + 检索 + 回答"全过程。建议在部署时把 LLM 调用埋点拆分到 `memory.extract`、`memory.search`、`answer.generate` 三个独立 span，以便在计费对账时给出明确拆分。资料来源：[src/everos/entrypoints/api/routes/memorize.py:1-44]()

3. **记忆的增删改能力**。社区 #14 反馈 V3 API 目前仅暴露"新增"与"检索"，缺少"删除/重置"接口；这对于 ChatGPT 式聊天应用的"编辑消息后撤回衍生记忆"与"清空上下文"场景是必需的。在缺乏官方接口前，运维侧可通过底层 `infra/persistence/markdown` 写入器直接清理，或等待该功能进入 GA。资料来源：[use-cases/README.md:1-80]()

4. **路径安全加固**。EverOS 1.0.1 起对 `sender_id` 实施与 `app_id` / `project_id` 同样的路径安全校验，部署时务必在 API Gateway 层同步启用等价的字符白名单，避免被外部反代绕过。资料来源：[src/everos/entrypoints/api/routes/memorize.py:1-44]()

## See Also

- 架构总览：[src/everos/README.md](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/README.md)
- CLI 与 API 入口：[src/everos/entrypoints/](https://github.com/EverMind-AI/EverOS/tree/main/src/everos/entrypoints)
- 使用案例总览：[use-cases/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/README.md)
- Game of Thrones 演示：[use-cases/game-of-throne-demo/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/README.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：EverMind-AI/EverOS

摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: fcntl import breaks EverOS on Windows — server fails to start。

## 1. 安装坑 · 来源证据：[Bug]: fcntl import breaks EverOS on Windows — server fails to start

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: fcntl import breaks EverOS on Windows — server fails to start
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/EverMind-AI/EverOS/issues/299 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/EverMind-AI/EverOS | host_targets=openclaw, claude_code, claude

## 3. 能力坑 · 来源证据：[Docs]: Clarification on reproducing Information Retrieval results in EvoAgentBench

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：[Docs]: Clarification on reproducing Information Retrieval results in EvoAgentBench
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/EverMind-AI/EverOS/issues/283 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/EverMind-AI/EverOS | README/documentation is current enough for a first validation pass.

## 5. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/EverMind-AI/EverOS | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/EverMind-AI/EverOS | no_demo; severity=medium

## 7. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/EverMind-AI/EverOS | no_demo; severity=medium

## 8. 安全/权限坑 · 来源证据：Feature request: official uninstall command (or an agent-ready removal prompt)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature request: official uninstall command (or an agent-ready removal prompt)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/EverMind-AI/EverOS/issues/281 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 9. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/EverMind-AI/EverOS | issue_or_pr_quality=unknown

## 10. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/EverMind-AI/EverOS | release_recency=unknown

<!-- canonical_name: EverMind-AI/EverOS; human_manual_source: deepwiki_human_wiki -->