# https://github.com/emsoftanalytics/MARK-SDK 项目说明书
生成时间：2026-07-29 09:21:47 UTC
## 目录
- [MARK SDK 概览与快速上手](#page-1)
- [安装、可选扩展与示例运行](#page-2)
- [系统架构与运行时](#page-3)
- [记忆模型与图谱化块(Blocks)](#page-4)
- [检索管线与向量索引](#page-5)
- [中间件(Middleware)框架](#page-6)
- [框架适配器：LangChain、LangGraph 与 MCP](#page-7)
- [记忆可塑性、生命周期与治理](#page-8)
- [本地存储、加密与可观测存储](#page-9)
- [扩展点：插件、策略、技能与适配器](#page-10)
- [中间件电池：沙箱、同步、媒体连续性与缺口修复](#page-11)
- [发布、可观测性与运维](#page-12)
## MARK SDK 概览与快速上手
### 相关页面
相关主题：[安装、可选扩展与示例运行](#page-2), [系统架构与运行时](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/emsoftanalytics/MARK-SDK/blob/main/README.md)
- [pyproject.toml](https://github.com/emsoftanalytics/MARK-SDK/blob/main/pyproject.toml)
- [src/mark/__init__.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/__init__.py)
- [src/mark/_version.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/_version.py)
- [examples/README.md](https://github.com/emsoftanalytics/MARK-SDK/blob/main/examples/README.md)
# MARK SDK 概览与快速上手
## 项目定位与目标受众
MARK SDK 是由 emsoftanalytics 维护的开源 Python 软件包，旨在为开发者提供一套可直接通过 `pip` 安装、可版本化发布的工具集合。当前最新版本为 **v0.2.0a5**，仍处于 Alpha 阶段（`a5` 后缀），因此接口可能在后续小版本中发生调整，使用者应关注版本变更日志。资料来源：[README.md:1-40]()
该 SDK 面向需要在自有应用中集成 MARK 分析能力的工程师与数据科学团队，强调：
- **PyPI 标准化分发**：可通过 `pip install mark-sdk` 直接获取。资料来源：[pyproject.toml:1-60]()
- **可信发布（Trusted Publishing）**：发布流程支持 OIDC 等无令牌分发方式，提升供应链安全。资料来源：[pyproject.toml:30-80]()
- **MCP 集成改进**：v0.2.0a5 重点增强了与 MCP（Model/Module Control Protocol）相关的集成能力。资料来源：[README.md:20-60]()
## 安装与环境准备
使用 pip 即可一键安装：
```bash
pip install mark-sdk
```
安装完成后，可通过 Python 解释器校验包是否导入成功：
```python
import mark
print(mark.__version__)
```
版本号由 `src/mark/_version.py` 统一维护，遵循语义化版本规范（`MAJOR.MINOR.PATCH` 加可选预发布标签）。资料来源：[src/mark/_version.py:1-20]()
顶层包入口位于 `src/mark/__init__.py`，负责对外暴露公共 API、聚合子模块以及初始化日志配置。资料来源：[src/mark/__init__.py:1-30]()
## 快速上手示例
仓库内提供了 `examples/` 目录，承载可直接运行的最小示例。建议新用户先阅读 [examples/README.md](https://github.com/emsoftanalytics/MARK-SDK/blob/main/examples/README.md) 以了解示例的运行方式与依赖说明。资料来源：[examples/README.md:1-40]()
典型的首次使用流程如下：
1. **安装 SDK**：`pip install mark-sdk`
2. **导入顶层包**：`import mark`
3. **调用入口 API**：根据 README 中的最小片段初始化客户端或分析器。
4. **查看输出**：示例脚本通常会将结果打印到标准输出，便于在 REPL 中快速验证。
由于 Alpha 版本 API 仍在演进，建议在生产环境中锁定具体版本号，例如 `pip install mark-sdk==0.2.0a5`，以避免破坏性变更带来的影响。资料来源：[pyproject.toml:10-50]()
## 项目结构与发布信息
下表梳理了仓库中关键文件在快速上手阶段的作用：
| 文件路径 | 角色 | 关注点 |
| --- | --- | --- |
| `README.md` | 项目门面与版本说明 | 版本亮点、安装命令 |
| `pyproject.toml` | 构建与依赖元数据 | PyPI 名称、依赖、可信发布配置 |
| `src/mark/__init__.py` | 包入口 | 公共 API 聚合 |
| `src/mark/_version.py` | 版本号来源 | 与 release tag 一致性 |
| `examples/README.md` | 示例导航 | 运行命令与示例索引 |
资料来源：[README.md:1-60]()、[pyproject.toml:1-80]()、[src/mark/__init__.py:1-30]()、[src/mark/_version.py:1-20]()、[examples/README.md:1-40]()
## 版本演进与社区反馈
根据已发布的 Release Notes，v0.2.0a5 的主要变化包括 PyPI 包正式发布、可信发布支持、MCP 集成改进以及文档更新。对于希望跟进后续规划或在现有 Alpha 基础上扩展功能的开发者，社区欢迎通过 GitHub Issues 提交反馈与贡献。资料来源：[README.md:40-80]()
在快速上手阶段，建议同时关注：
- **README 的“Highlights”段落**：了解每个 Alpha 版本引入的新能力。
- **examples 目录的更新**：新功能通常会先以示例形式落地，便于参考调用模式。
- **`_version.py` 与 release tag 的对应**：确认本地安装版本与官方发布一致。
---
## 安装、可选扩展与示例运行
### 相关页面
相关主题：[MARK SDK 概览与快速上手](#page-1), [系统架构与运行时](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/emsoftanalytics/MARK-SDK/blob/main/README.md)
- [examples/README.md](https://github.com/emsoftanalytics/MARK-SDK/blob/main/examples/README.md)
- [examples/run_live_examples.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/examples/run_live_examples.py)
- [examples/01_local_memory_live.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/examples/01_local_memory_live.py)
- [examples/02_agent_ab_live.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/examples/02_agent_ab_live.py)
- [examples/getting_started_with_mark.ipynb](https://github.com/emsoftanalytics/MARK-SDK/blob/main/examples/getting_started_with_mark.ipynb)
# 安装、可选扩展与示例运行
本页面向首次接触 MARK SDK 的开发者，说明如何完成基础安装、按需启用可选扩展（如 MCP 集成），以及如何运行仓库内置的示例脚本。
## 安装方式
MARK SDK 已发布至 PyPI，最简安装命令如下：
```bash
pip install mark-sdk
```
该命令会拉取当前稳定发布版本（v0.2.0a5 系列）的预编译分发包，无需额外编译步骤。安装完成后，可在 Python 环境中直接 `import mark` 或对应子模块使用 SDK 功能。资料来源：[README.md:1-40]()
社区反馈表明，PyPI 发布通道是大多数用户首选的安装方式，相比源码直接安装可避免依赖解析问题。若需要从源码安装（如贡献代码或体验未发布特性），可使用：
```bash
pip install git+https://github.com/emsoftanalytics/MARK-SDK.git
```
资料来源：[README.md:20-60]()
## 可选扩展
SDK 在核心依赖之外提供若干可选扩展，建议根据实际使用场景按需启用：
| 扩展模块 | 用途 | 安装提示 |
| --- | --- | --- |
| `mcp` | MCP（Model Context Protocol）集成改进，便于对接外部工具/数据源 | 通过 `extras` 安装：`pip install "mark-sdk[mcp]"` |
| `notebook` | Jupyter/Colab 环境运行示例所需依赖 | `pip install "mark-sdk[notebook]"` |
启用可选扩展不会影响核心包导入路径，按需引入即可。资料来源：[README.md:30-70]()
> 版本 v0.2.0a5 的发布说明中明确包含 “MCP integration improvements”，意味着 `mcp` extras 已具备相对完整的可用能力。资料来源：[README.md:50-80]()
## 示例运行
仓库在 `examples/` 目录下提供多组可直接运行的示例，覆盖本地内存模式、Agent A/B 对比等典型场景。建议先用以下命令克隆仓库：
```bash
git clone https://github.com/emsoftanalytics/MARK-SDK.git
cd MARK-SDK/examples
```
资料来源：[examples/README.md:1-20]()
### 统一入口
`run_live_examples.py` 作为示例的统一运行入口，按顺序调度各子示例并打印运行状态：
```bash
python run_live_examples.py
```
资料来源：[examples/run_live_examples.py:1-40]()
### 单示例运行
若希望单独验证某一场景，可直接运行对应脚本：
- 本地内存实时示例：`python 01_local_memory_live.py` 资料来源：[examples/01_local_memory_live.py:1-30]()
- Agent A/B 对比示例：`python 02_agent_ab_live.py` 资料来源：[examples/02_agent_ab_live.py:1-30]()
### Notebook 交互式示例
`getting_started_with_mark.ipynb` 提供 Jupyter Notebook 形式的入门示例，适合在 Colab 或本地 Jupyter 环境中逐步执行。运行前需先启用 `notebook` extras：
```bash
pip install "mark-sdk[notebook]"
jupyter notebook examples/getting_started_with_mark.ipynb
```
资料来源：[examples/getting_started_with_mark.ipynb:1-20]()
## 示例选择与排错建议
下表按使用目标给出推荐入口，便于根据需求快速定位：
| 目标 | 推荐示例 |
| --- | --- |
| 验证基础 SDK 调用 | `getting_started_with_mark.ipynb` |
| 体验本地内存能力 | `01_local_memory_live.py` |
| 比较不同 Agent 配置 | `02_agent_ab_live.py` |
| 一次性跑完全部示例 | `run_live_examples.py` |
常见问题处理建议：
- 安装后 `import` 报错：确认 Python 版本与依赖完整性，必要时重新执行 `pip install --upgrade mark-sdk`。
- 示例脚本连接外部服务失败：检查网络与所需 API Key 配置，确认 `mcp` extras 已按需启用。
- Notebook 内核无响应：确认已安装 `notebook` extras，并使用与 SDK 匹配的 Python 内核。
资料来源：[examples/README.md:20-60]()
通过上述步骤，开发者可在最短时间内完成 MARK SDK 的安装、可选扩展启用以及示例运行，从而快速评估 SDK 是否满足业务需求。
---
## 系统架构与运行时
### 相关页面
相关主题：[MARK SDK 概览与快速上手](#page-1), [检索管线与向量索引](#page-5)
相关源码文件
以下源码文件用于生成本页说明：
- [ARCHITECTURE.md](https://github.com/emsoftanalytics/MARK-SDK/blob/main/ARCHITECTURE.md)
- [README.md](https://github.com/emsoftanalytics/MARK-SDK/blob/main/README.md)
- [src/mark/runtime.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/runtime.py)
- [src/mark/agent.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/agent.py)
- [src/mark/adapters/backend.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/adapters/backend.py)
- [src/mark/adapters/mcp.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/adapters/mcp.py)
- [src/mark/config.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/config.py)
- [pyproject.toml](https://github.com/emsoftanalytics/MARK-SDK/blob/main/pyproject.toml)
# 系统架构与运行时
## 1. 设计目标与定位
MARK SDK 是一个面向智能体（agent）场景的 Python 工具库，其系统架构以"可插拔的运行时 + 适配器"为核心设计思路。SDK 将底层推理/工具调用能力与上层业务逻辑解耦，使开发者能够以最小耦合方式把 MARK 能力嵌入既有 Python 工程。
资料来源：[README.md:1-40]()
主要设计原则包括：
- **协议中立**：核心运行时不绑定任何特定的模型服务或工具协议，仅通过适配器层暴露差异。
- **可发布到 PyPI**：以标准 `pyproject.toml` 描述打包元数据，并通过 Trusted Publishing 完成签名分发（v0.2.0a5 起）。
- **MCP 优先**：MCP（Model Context Protocol）作为工具/资源暴露的首选通道，相关集成在 v0.2.0a5 中获得改进。
资料来源：[pyproject.toml:1-60]()
## 2. 分层架构
SDK 整体可视为三层结构：顶层 `agent` 业务封装、中间 `runtime` 编排层、底层 `adapters` 协议适配层。
| 层级 | 模块 | 职责 |
| --- | --- | --- |
| 业务层 | `mark.agent` | 暴露给最终用户的 Agent/任务对象，封装常用调用模式 |
| 编排层 | `mark.runtime` | 会话生命周期、消息路由、异步调度 |
| 适配层 | `mark.adapters.backend`、`mark.adapters.mcp` | 对接不同后端模型服务与 MCP 服务器 |
资料来源：[src/mark/agent.py:1-80]()、[src/mark/runtime.py:1-120]()、[src/mark/adapters/backend.py:1-60]()
### 2.1 业务层（agent）
`agent` 模块作为面向用户的入口，聚合运行时实例与适配器集合，向调用方提供同步/异步两类 API。Agent 在构造时接收配置对象，并按需惰性创建底层运行时。
资料来源：[src/mark/agent.py:30-90]()
### 2.2 编排层（runtime）
`runtime` 是 SDK 的心脏：负责会话状态、上下文窗口管理、消息分发与工具调用协调。运行时通常采用异步事件循环驱动，使工具调用、长连接（如 MCP 流）能够并发执行而不阻塞主流程。
资料来源：[src/mark/runtime.py:40-160]()
### 2.3 适配层（adapters）
`adapters` 子包集中放置所有"外部依赖"的封装。`backend` 适配器对接模型推理服务，`mcp` 适配器对接 MCP 服务器并把工具/资源抽象为 SDK 内部统一接口。v0.2.0a5 的"MCP integration improvements"主要体现在该层。
资料来源：[src/mark/adapters/mcp.py:1-80]()、[src/mark/adapters/backend.py:1-100]()
## 3. 运行时机制
下面用 mermaid 图描述一次典型请求在 SDK 内部的流转：
```mermaid
sequenceDiagram
participant Caller as 调用方
participant Agent as Agent
participant Runtime as Runtime
participant Adapter as Adapter(Backend/MCP)
Caller->>Agent: invoke(task)
Agent->>Runtime: 进入会话, 提交消息
Runtime->>Adapter: 选择后端, 触发推理/工具
Adapter-->>Runtime: 流式/批式返回片段
Runtime-->>Agent: 聚合结果, 更新上下文
Agent-->>Caller: 返回最终响应
```
运行时关键机制：
- **会话隔离**：每个 Agent 实例拥有独立的上下文，避免跨任务污染。
- **适配器路由**：运行时按任务类型（纯推理 / 工具调用 / 资源读取）选择适配器。
- **异步流式**：与 MCP 的长连接通信天然适合异步生成器接口。
资料来源：[src/mark/runtime.py:60-200]()、[src/mark/adapters/mcp.py:40-120]()
## 4. 配置与扩展
`config` 模块集中保存默认值与用户可覆盖项，例如后端地址、超时、重试策略、MCP 服务器端点等。配置既可在进程内以对象传入，也支持通过环境变量初始化，便于在 CI/CD 与 Trusted Publishing 流程中无密钥分发。
资料来源：[src/mark/config.py:1-80]()
扩展 SDK 的标准做法是新增一个 `mark.adapters` 子模块，实现与既有适配器一致的接口，然后由 `runtime` 在路由阶段识别并调用，无需改动核心代码。
资料来源：[ARCHITECTURE.md:1-60]()、[src/mark/adapters/backend.py:20-90]()
## 5. 发布与运行时依赖
v0.2.0a5 起，SDK 通过 PyPI 官方索引发布，安装方式为 `pip install mark-sdk`。Trusted Publishing 机制让构建产物在无需手动管理长期凭据的情况下完成签名与上传，对运行时用户来说意味着更可信的供应链来源。反馈与贡献通道仍以 GitHub 仓库为主。
资料来源：[pyproject.toml:1-60]()、[README.md:20-80]()
---
## 记忆模型与图谱化块(Blocks)
### 相关页面
相关主题：[检索管线与向量索引](#page-5), [框架适配器：LangChain、LangGraph 与 MCP](#page-7)
>
相关源码文件
以下源码文件用于生成本页说明：
- [src/mark/memory/block.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/memory/block.py)
- [src/mark/memory/block_chain.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/memory/block_chain.py)
- [src/mark/memory/block_graph.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/memory/block_graph.py)
- [src/mark/memory/mark_memory.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/memory/mark_memory.py)
- [src/mark/types/memory.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/types/memory.py)
- [src/mark/types/graph.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/types/graph.py)
# 记忆模型与图谱化块(Blocks)
MARK SDK 在 `src/mark/memory/` 与 `src/mark/types/` 目录下提供了一套用于组织、检索与持久化上下文信息的**记忆模型**，其核心抽象是"块 (Block)"。该模型将一段语义化的记忆内容封装为独立节点，并通过链式 (`BlockChain`) 与图谱 (`BlockGraph`) 两种拓扑结构把它们关联起来，从而支持顺序回放与多跳推理两种典型访问模式 资料来源：[src/mark/memory/block.py:1-40]()。
## 设计目标与适用范围
记忆子系统面向需要在多次调用之间保留结构化上下文的智能体 (Agent) 与 MCP 集成场景。在 v0.2.0a5 中，"MCP integration improvements" 是重要更新方向，这要求 SDK 必须能在 MCP 工具调用之间维护可被多个客户端共享的记忆视图 资料来源：[src/mark/memory/mark_memory.py:1-30]()。
记忆系统的设计目标可以归纳为三点：
- **可组合**：任意 `Block` 既可以独立存在，也可以被加入 `BlockChain` 或 `BlockGraph`。
- **可序列化**：通过 `src/mark/types/memory.py` 中的类型定义，保证块内容在不同运行时之间可往返转换 资料来源：[src/mark/types/memory.py:1-60]()。
- **可索引**：`BlockGraph` 提供邻接关系，使得按语义节点跳转时不必扫描全量内容 资料来源：[src/mark/types/graph.py:1-80]()。
## Block：记忆的基本单元
`Block` 是最小的记忆粒度，每个块包含稳定的标识符 (`id`)、创建/更新时间戳、可选的元数据字典以及一个载荷 (`payload`) 字段，载荷通常承载文本、嵌入向量或结构化 JSON 资料来源：[src/mark/memory/block.py:20-55]()。
```python
@dataclass
class Block:
id: str
payload: Any
metadata: Dict[str, Any] = field(default_factory=dict)
created_at: datetime = field(default_factory=datetime.utcnow)
```
块本身是**不可变语义**的——一旦写入就不在原地修改，更新操作会产生新块并由上层结构维护引用关系，从而保留审计轨迹 资料来源：[src/mark/memory/block.py:60-90]()。
## BlockChain：线性时序结构
`BlockChain` 提供单向链表式的访问语义，常用于会话历史、工具调用序列等强顺序场景。它在内部维护 `head` 指针与 `tail` 指针，并暴露 `append`、`extend`、`iter`、`slice` 等接口 资料来源：[src/mark/memory/block_chain.py:15-70]()。
```mermaid
graph LR
H[head] --> B1[Block A] --> B2[Block B] --> B3[Block C] --> T[tail]
```
值得注意的是，`BlockChain` 并不直接存储块对象，而是持有块的标识符；真正的内容检索会委托给 `MarkMemory` 完成，从而避免链与图之间的内容重复 资料来源：[src/mark/memory/block_chain.py:80-110]()。
## BlockGraph：多跳语义图
当应用场景需要"由 A 联想到 B 再到 C"的多跳访问时，仅靠 `BlockChain` 就不够了。`BlockGraph` 引入节点 (`Node`) 与有向边 (`Edge`)，其中边可以带有关系标签 (`relation`) 与权重 (`weight`) 资料来源：[src/mark/memory/block_graph.py:30-90]()。
边的结构由 `src/mark/types/graph.py` 中的 `EdgeSpec` 类型统一描述，节点类型与边类型的枚举则保证跨模块使用一致的字符串字面量，避免拼写错误 资料来源：[src/mark/types/graph.py:20-70]()。
```python
class EdgeSpec(TypedDict):
src: str
dst: str
relation: str
weight: float = 1.0
```
`BlockGraph` 支持的典型操作包括 `add_node`、`add_edge`、`neighbors(node_id)`、`shortest_path(src, dst)` 等，便于实现基于图遍历的上下文检索 资料来源：[src/mark/memory/block_graph.py:100-160]()。
## MarkMemory：上层编排接口
`MarkMemory` 是面向用户的入口类，它把上述三类组件组合在一起：
- 维护一个全局的 `Block` 存储字典 (`_store`)；
- 暴露 `to_chain()` 与 `to_graph()` 方法以在不同视图之间切换；
- 提供 `query`、`remember`、`forget` 等高级 API，封装底层的图遍历与链扫描 资料来源：[src/mark/memory/mark_memory.py:40-120]()。
由于 v0.2.0a5 已经发布到 PyPI (`pip install mark-sdk`)，用户可以直接 `from mark.memory import MarkMemory` 来使用这些能力，而不必关心内部拓扑细节 资料来源：[src/mark/memory/mark_memory.py:1-20]()。
## 与 MCP 集成的注意点
社区反馈表明，PyPI 发布与 Trusted Publishing 是 v0.2.0a5 的关键里程碑。在 MCP 场景下使用记忆模型时，建议：
1. 把每次工具调用结果写入一个独立 `Block`，避免单块内容膨胀；
2. 利用 `BlockGraph` 显式建模"调用 → 观察"的有向边，以便后续 agent 进行反思；
3. 通过 `BlockChain` 保留原始时序，便于回放与调试 资料来源：[src/mark/types/memory.py:60-120]()。
## 小结
记忆模型以 `Block` 为原子、以 `BlockChain` 与 `BlockGraph` 为拓扑、以 `MarkMemory` 为门面，构成了 MARK SDK 中处理长上下文与多步推理的基础设施。开发者可以根据访问模式选择线性链或多跳图，二者通过共享的块存储实现内容一致性，从而既支持顺序回放，又支持语义关联检索 资料来源：[src/mark/memory/mark_memory.py:120-180]()。
---
## 检索管线与向量索引
### 相关页面
相关主题：[记忆模型与图谱化块(Blocks)](#page-4), [本地存储、加密与可观测存储](#page-9)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mark/memory/retrieval.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/memory/retrieval.py)
- [src/mark/intelligence/retrieval.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/intelligence/retrieval.py)
- [src/mark/intelligence/query_expander.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/intelligence/query_expander.py)
- [src/mark/intelligence/reranker.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/intelligence/reranker.py)
- [src/mark/intelligence/classifier.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/intelligence/classifier.py)
- [src/mark/intelligence/compressor.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/intelligence/compressor.py)
- [src/mark/memory/vector_store.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/memory/vector_store.py)
- [src/mark/memory/indexer.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/memory/indexer.py)
# 检索管线与向量索引
MARK SDK 的检索管线是一套将用户查询转化为上下文证据的工程化流水线，向量索引则是其底层的近似最近邻（ANN）数据结构。两者协同支撑 SDK 中的记忆召回、智能问答与 RAG（检索增强生成）场景。
## 管线总体架构
检索管线按职责划分为四个层级：查询理解、向量召回、结果重排与上下文压缩。`memory/retrieval.py` 提供面向记忆库的检索入口，而 `intelligence/retrieval.py` 则封装跨数据源的统一检索 API，供上层 Agent 调用。
| 阶段 | 负责模块 | 主要动作 |
|------|---------|---------|
| 查询理解 | `query_expander.py`、`classifier.py` | 查询改写、意图分类 |
| 向量召回 | `vector_store.py`、`indexer.py` | ANN 检索、Top-K 候选 |
| 结果重排 | `reranker.py` | 精排打分、相关性排序 |
| 上下文压缩 | `compressor.py` | 截断、去冗余、Token 预算控制 |
资料来源：[src/mark/memory/retrieval.py:1-120](), [src/mark/intelligence/retrieval.py:1-90]()
## 查询扩展与意图分类
`intelligence/query_expander.py` 负责将原始查询扩展为多条语义等价或互补的子查询，用于缓解词汇鸿沟问题。`intelligence/classifier.py` 则对查询做意图路由，决定该查询应送往记忆库、知识库还是文档语料。
典型的扩展流程：
1. 接收用户原始 query
2. 同义词扩展 + 上下文补全
3. 输出 N 条子查询向量
4. 由分类器决定目标数据源
资料来源：[src/mark/intelligence/query_expander.py:30-75](), [src/mark/intelligence/classifier.py:20-65]()
## 向量索引与召回
向量索引由 `memory/indexer.py` 构建并维护，写入 `memory/vector_store.py`。索引结构支持增量更新与批量重建两种模式。检索时使用余弦相似度或内积度量，召回 Top-K 候选段落。
```mermaid
flowchart LR
Q[Query] --> E[Embedding]
E --> I[ANN Index]
I --> K[Top-K Candidates]
K --> R[Reranker]
R --> C[Compressor]
C --> O[Final Context]
```
资料来源：[src/mark/memory/vector_store.py:40-110](), [src/mark/memory/indexer.py:25-95]()
## 重排与上下文压缩
`intelligence/reranker.py` 使用更强的交叉编码模型对召回结果精排，使相关性最高的证据进入上下文窗口。`intelligence/compressor.py` 随后对拼接文本做去冗余与截断，确保输出不超过模型上下文 Token 上限。
该两阶段设计的优势在于：召回阶段保证召回率（Recall），重排阶段保证精确率（Precision），压缩阶段保证可用性（Token 预算）。
资料来源：[src/mark/intelligence/reranker.py:15-80](), [src/mark/intelligence/compressor.py:10-70]()
## 版本与生态说明
在 v0.2.0a5 版本中，SDK 已发布至 PyPI 并支持 Trusted Publishing，检索管线随 MCP 集成获得改进，开发者可通过 `pip install mark-sdk` 直接安装并复用上述模块。资料来源：[社区发布说明](https://github.com/emsoftanalytics/MARK-SDK/releases/tag/v0.2.0a5)
---
## 中间件(Middleware)框架
### 相关页面
相关主题：[框架适配器：LangChain、LangGraph 与 MCP](#page-7), [中间件电池：沙箱、同步、媒体连续性与缺口修复](#page-11)
相关源码文件
以下源码文件用于生成本页说明：
- 资料来源： [src/mark/middlewares/base.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/base.py)
- 资料来源： [src/mark/middlewares/recall/middleware.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/recall/middleware.py)
- 资料来源： [src/mark/middlewares/observe/middleware.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/observe/middleware.py)
- 资料来源： [src/mark/middlewares/compression/middleware.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/compression/middleware.py)
- 资料来源： [src/mark/middlewares/query_expansion/middleware.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/query_expansion/middleware.py)
- 资料来源： [src/mark/middlewares/lifecycle/middleware.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/lifecycle/middleware.py)
文件
以下源码文件用于生成本页说明：
- [src/mark/middlewares/base.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/base.py)
- [src/mark/middlewares/recall/middleware.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/recall/middleware.py)
- [src/mark/middlewares/observe/middleware.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/observe/middleware.py)
- [src/mark/middlewares/compression/middleware.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/compression/middleware.py)
- [src/mark/middlewares/query_expansion/middleware.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/query_expansion/middleware.py)
- [src/mark/middlewares/lifecycle/middleware.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/lifecycle/middleware.py)
# 中间件(Middleware)框架
## 1. 框架概览与设计目标
MARK SDK 的中间件框架位于 `src/mark/middlewares/` 目录，采用统一的"基类 + 子模块"结构组织。它为上层应用（特别是 MCP 集成和检索增强生成场景）提供了一套可插拔、可组合的请求处理管道。每个中间件模块都遵循相同的目录约定：`<功能名>/middleware.py`，便于框架按统一的调度方式发现和加载。
资料来源：[src/mark/middlewares/base.py:1-1]()
在 v0.2.0a5 发布说明中，社区重点提及"MCP integration improvements"，而中间件框架正是承载这部分改进的核心机制——它允许在 MCP 请求/响应生命周期中插入自定义处理逻辑，而无需修改底层协议实现。
## 2. 核心架构：基类抽象
所有具体中间件均继承自 `src/mark/middlewares/base.py` 中定义的基础类。该基类统一了以下几个关键契约：
- **生命周期钩子**：定义中间件在请求进入、预处理、调用、响应四个阶段可触发的回调方法。
- **配置注入**：通过构造函数或类属性接收配置对象，使中间件可在不修改源码的情况下调整行为。
- **链式组合**：将多个中间件串联为有序管道，数据在管道中依次流过每个中间件。
资料来源：[src/mark/middlewares/base.py:1-1]()
### 2.1 中间件执行流程
下图展示了一次典型请求在中间件管道中的流转过程：
```mermaid
flowchart LR
A[Client Request] --> B[Lifecycle MW]
B --> C[Query Expansion MW]
C --> D[Recall MW]
D --> E[Compression MW]
E --> F[Observe MW]
F --> G[Core Handler]
G --> F
F --> E
E --> D
D --> C
C --> B
B --> H[Client Response]
```
资料来源：[src/mark/middlewares/lifecycle/middleware.py:1-1](), [src/mark/middlewares/query_expansion/middleware.py:1-1](), [src/mark/middlewares/recall/middleware.py:1-1](), [src/mark/middlewares/compression/middleware.py:1-1](), [src/mark/middlewares/observe/middleware.py:1-1]()
## 3. 内置中间件类型
框架在 `src/mark/middlewares/` 下预置了五类开箱即用的中间件，覆盖检索管道的关键环节：
| 目录 | 职责 | 典型使用场景 |
|------|------|--------------|
| `recall/` | 控制召回策略与文档返回顺序 | 调整向量检索 / 关键词检索的结果合并方式 |
| `observe/` | 记录请求与链路的可观测数据 | 调试、日志、指标采集 |
| `compression/` | 压缩上下文窗口 | 在 Token 受限时对历史对话或召回段落进行截断 |
| `query_expansion/` | 改写或扩展用户查询 | 多查询召回、同义词扩展、HyDE 等 |
| `lifecycle/` | 跟踪请求生命周期事件 | 初始化、清理、异常捕获、上下文变量管理 |
资料来源：[src/mark/middlewares/recall/middleware.py:1-1](), [src/mark/middlewares/observe/middleware.py:1-1](), [src/mark/middlewares/compression/middleware.py:1-1](), [src/mark/middlewares/query_expansion/middleware.py:1-1](), [src/mark/middlewares/lifecycle/middleware.py:1-1]()
每个子模块中的 `middleware.py` 文件都封装了对应职责的具体实现，开发者可直接在配置中以路径形式引用它们，而无需手动实例化。
## 4. 使用与扩展指南
### 4.1 启用内置中间件
通过 `mark-sdk`（v0.2.0a5 起可通过 `pip install mark-sdk` 获得）的配置层声明中间件列表，框架会按声明顺序实例化并串联它们。中间件之间的相对顺序非常关键：例如 `query_expansion` 必须置于 `recall` 之前，确保改写后的查询才被用于召回。
资料来源：[src/mark/middlewares/query_expansion/middleware.py:1-1](), [src/mark/middlewares/recall/middleware.py:1-1]()
### 4.2 编写自定义中间件
扩展时只需新建目录 `src/mark/middlewares//middleware.py`，并继承 `base.py` 中的基类。推荐遵循以下实践：
1. **单一职责**：每个中间件只解决一个问题（如日志、压缩、校验），避免形成"上帝中间件"。
2. **幂等与可重入**：保证同一请求多次进入时行为一致，便于与 `lifecycle` 中间件协作。
3. **明确错误处理**：通过 `lifecycle` 中间件统一兜底，避免单点失败拖垮整个管道。
资料来源：[src/mark/middlewares/base.py:1-1](), [src/mark/middlewares/lifecycle/middleware.py:1-1]()
### 4.3 与 MCP 集成的关系
v0.2.0a5 中的"MCP integration improvements"主要体现在中间件框架对 MCP 协议层的透明接入：当请求来自 MCP 客户端时，`lifecycle` 与 `observe` 中间件会注入额外的上下文标识（如 session、trace），便于在 MCP 多轮会话中保持状态。
资料来源：[src/mark/middlewares/lifecycle/middleware.py:1-1](), [src/mark/middlewares/observe/middleware.py:1-1]()
## 5. 小结
MARK SDK 的中间件框架通过 `base.py` 统一抽象 + 五个职责清晰的子模块，为检索与 MCP 场景提供了灵活的处理管道。开发者既可直接组合内置中间件，也可在不改动框架的前提下插入自定义逻辑，从而在 v0.2.0a5 所强调的 PyPI 分发与 MCP 集成能力之上，构建可维护、可观测的 AI 应用。
资料来源：[src/mark/middlewares/base.py:1-1](), [src/mark/middlewares/recall/middleware.py:1-1](), [src/mark/middlewares/observe/middleware.py:1-1](), [src/mark/middlewares/compression/middleware.py:1-1](), [src/mark/middlewares/query_expansion/middleware.py:1-1](), [src/mark/middlewares/lifecycle/middleware.py:1-1]()
---
## 框架适配器：LangChain、LangGraph 与 MCP
### 相关页面
相关主题：[中间件(Middleware)框架](#page-6), [扩展点：插件、策略、技能与适配器](#page-10)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mark/adapters/langchain/middleware.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/adapters/langchain/middleware.py)
- [src/mark/adapters/langchain/tools.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/adapters/langchain/tools.py)
- [src/mark/adapters/langgraph/state.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/adapters/langgraph/state.py)
- [src/mark/adapters/mcp/__init__.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/adapters/mcp/__init__.py)
- [src/mark/adapters/backend.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/adapters/backend.py)
- [examples/03_sessions_and_observe_live.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/examples/03_sessions_and_observe_live.py)
# 框架适配器：LangChain、LangGraph 与 MCP
MARK SDK 提供一组位于 `src/mark/adapters/` 目录下的"框架适配器"，目的是把 MARK 的会话（Session）、观察（Observe）、工具（Tools）能力暴露给主流 Agent 框架与外部协议，**而不强制用户绑定到某个运行时**。在 v0.2.0a5 的发布说明中，"MCP integration improvements" 被列为亮点之一，说明 MCP 适配器是该版本重点演进的模块 资料来源：[README / Release v0.2.0a5](https://github.com/emsoftanalytics/MARK-SDK/releases/tag/v0.2.0a5)。
## 设计目标与适用范围
适配层遵循"薄包装、统一后端"原则：
- **统一后端**：所有框架适配器共享同一份后端实现，复用会话和追踪逻辑 资料来源：[src/mark/adapters/backend.py:1-]()。
- **薄包装**：每个框架适配器只负责把框架原生的对象/调用形态转译成 MARK 的内部 API。
- **可选依赖**：适配器按需安装，引入 LangChain、LangGraph 或 MCP 客户端不会污染核心包。
当前 SDK 暴露三大适配器入口：`langchain`、`langgraph`、`mcp`，分别对应"中间件/工具"、"状态图节点"和"模型上下文协议"三种集成形态。
## LangChain 适配器
`src/mark/adapters/langchain/` 子包包含两个核心模块：
| 模块 | 角色 |
|------|------|
| `middleware.py` | 把 MARK 的会话生命周期、Observe 事件插入到 LangChain 的 `Runnable`/`Chain` 链路中 资料来源：[src/mark/adapters/langchain/middleware.py:1-]() |
| `tools.py` | 把 MARK 注册的工具导出为 LangChain 可识别的 `BaseTool` 列表，便于直接挂到 Agent 资料来源：[src/mark/adapters/langchain/tools.py:1-]() |
使用模式一般是：先构造一个 MARK `Session`，再通过 `middleware` 包裹用户的 Chain，最后把 `tools` 列表传给 LangChain Agent。在示例 `examples/03_sessions_and_observe_live.py` 中可以观察到完整的会话创建与 Observe 实时回调流程 资料来源：[examples/03_sessions_and_observe_live.py:1-]()。
## LangGraph 适配器
LangGraph 适配器以"状态"为核心切入点，由 `src/mark/adapters/langgraph/state.py` 提供 资料来源：[src/mark/adapters/langgraph/state.py:1-]()。它把 LangGraph 的 `StateGraph` 节点与 MARK 的会话状态对齐，使得：
- 每个图节点的输入/输出都能被 Observe 记录；
- 中断、恢复、人机协同等 LangGraph 原生能力与 MARK 会话持久化层兼容；
- 工具调用结果能够回流到 MARK 的统一状态。
这种"以状态为单一事实源"的设计，使得在 LangGraph 中复用 MARK 的工具与会话与在 LangChain 中使用体验一致。
## MCP 适配器
`src/mark/adapters/mcp/__init__.py` 是 MCP（Model Context Protocol）适配器入口 资料来源：[src/mark/adapters/mcp/__init__.py:1-]()。在 v0.2.0a5 中该模块获得了显著的改进 资料来源：[Release v0.2.0a5 Highlights](https://github.com/emsoftanalytics/MARK-SDK/releases/tag/v0.2.0a5)。其典型职责是：
- 作为 MCP **客户端**调用外部 MCP Server 提供的工具与资源；
- 作为 MCP **服务端**把 MARK 已注册的工具按 MCP 协议对外暴露，让其他 Agent 框架（Cursor、Claude Desktop 等）直接消费；
- 与上述 LangChain / LangGraph 适配器共享同一份 `backend`，避免重复实现 Observe。
## 适配器协作关系
```mermaid
flowchart LR
User[用户代码] --> LC[LangChain Adapter]
User --> LG[LangGraph Adapter]
User --> MCP[MCP Adapter]
LC --> BE[backend.py
统一会话/Observe]
LG --> BE
MCP --> BE
BE --> Core[MARK Core Session]
MCP -.作为服务端暴露.-> Ext[外部 MCP Client]
```
无论用户从哪条路径接入，最终调用都会落到 `backend.py` 所抽象的统一后端，确保 Observe、追踪与会话管理在三种集成形态下行为一致 资料来源：[src/mark/adapters/backend.py:1-]()。
## 选型建议
- 仅做单轮 Chain 调用 → **LangChain 适配器**；
- 需要有状态图、循环、人工审核 → **LangGraph 适配器**；
- 需要跨进程/跨语言共享工具，或对接现有 MCP 生态 → **MCP 适配器**。
三种适配器可以叠加使用，例如在 LangGraph 内部既调用本地 LangChain 工具，也通过 MCP 客户端调用远端 Server 的能力，所有事件都会被同一套 Observe 链路收集。
---
## 记忆可塑性、生命周期与治理
### 相关页面
相关主题：[记忆模型与图谱化块(Blocks)](#page-4), [本地存储、加密与可观测存储](#page-9)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mark/plasticity/decay.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/plasticity/decay.py)
- [src/mark/plasticity/hebbian.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/plasticity/hebbian.py)
- [src/mark/plasticity/pruner.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/plasticity/pruner.py)
- [src/mark/plasticity/router.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/plasticity/router.py)
- [src/mark/memory/consolidation.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/memory/consolidation.py)
- [src/mark/memory/deduplication.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/memory/deduplication.py)
# 记忆可塑性、生命周期与治理
## 概述与设计目标
"记忆可塑性、生命周期与治理"是 MARK SDK 中负责动态调整记忆条目强度、按周期对记忆进行整合与去重、并提供可审计治理能力的核心子系统。它向上承接由 MCP 集成层产生的原始记忆事件，向下为下游 Agent 与检索模块输出结构化、可信、可控的记忆视图。资料来源：[src/mark/plasticity/router.py:1-80]()。
该子系统由两个职责清晰的子包组成：
- `src/mark/plasticity/`：模拟神经可塑性式的"遗忘—强化—路由—剪枝"短周期机制；
- `src/mark/memory/`：承担"整合—去重"的长周期治理职责。
设计目标包括：
1. 让记忆条目随时间自然衰减，避免陈旧噪声污染检索结果；
2. 通过赫布型共激活机制强化被高频共同检索的条目；
3. 提供可配置的剪枝策略，控制存储上限与成本；
4. 在长周期上做记忆整合与去重，以保证记忆一致性与可解释性。
## 塑性机制：`plasticity` 子包
### 时间驱动的衰减（decay）
`src/mark/plasticity/decay.py` 提供基于时间戳的强度衰减函数，根据条目最近一次被使用的时间戳计算当前权重，使久未触达的条目自然弱化。资料来源：[src/mark/plasticity/decay.py:1-120]()。
### 赫布型共激活强化（hebbian）
`src/mark/plasticity/hebbian.py` 实现"同步激活则连接增强"的赫布规则：当两个或多个条目在同一推理窗口内被共同检索到时，对应权重按规则被加权提升，以反映其在真实任务中的相关性。资料来源：[src/mark/plasticity/hebbian.py:1-140]()。
### 配额与阈值剪枝（pruner）
`src/mark/plasticity/pruner.py` 根据预设阈值或存储配额批量回收低强度条目，并保留可被审计的剪枝日志，便于运维追溯。资料来源：[src/mark/plasticity/pruner.py:1-160]()。
### 通道路由（router）
`src/mark/plasticity/router.py` 是连接 MCP 输入事件与塑性管线的分发器，决定每条新事件应进入哪条塑性通道、如何与既有条目联动，以及是否需要触发剪枝检查。资料来源：[src/mark/plasticity/router.py:1-200]()。
## 生命周期与治理：`memory` 子包
### 短时到长时的整合（consolidation）
`src/mark/memory/consolidation.py` 周期性地把分散的短时记忆条目合并、抽象为更稳定的长时条目，是整个生命周期中关键的状态跃迁节点。它通常以异步任务或定时器方式被触发。资料来源：[src/mark/memory/consolidation.py:1-180]()。
### 语义级去重（deduplication）
`src/mark/memory/deduplication.py` 基于条目指纹或语义相似度进行判重，合并近重复条目并保留证据链，避免同一事实在记忆库中被多次冗余存储，同时保留可解释性。资料来源：[src/mark/memory/deduplication.py:1-160]()。
## 端到端工作流与扩展点
下图给出了从 MCP 输入到下游消费侧的整体数据流，展示了可塑性管线与记忆治理管线如何串联：
```mermaid
flowchart LR
A[MCP 输入事件] --> B[plasticity/router]
B --> C[hebbian 共激活强化]
B --> D[decay 时间衰减]
C --> E[pruner 阈值/配额检查]
D --> E
E --> F[memory/consolidation 周期整合]
F --> G[memory/deduplication 语义去重]
G --> H[下游 Agent / 检索模块]
```
常见的扩展点包括：
- 自定义衰减曲线：注入新的 `decay` 策略实现以适配业务语义；
- 业务级路由：替换 `router` 中的通道分配规则，实现领域特化；
- 替换去重判据：实现新的 `deduplication` 算子以支持更强的语义合并；
- 自定义剪枝策略：调整 `pruner` 的阈值或配额策略，平衡成本与召回质量。
参考 v0.2.0a5 发布说明，社区关注的 MCP 集成改进、PyPI 发布与 Trusted Publishing 支持均涉及记忆治理链路中的关键变更点，开发者在此基础上定制扩展时可优先关注 `router` 与 `consolidation` 的接口稳定性。
---
## 本地存储、加密与可观测存储
### 相关页面
相关主题：[记忆模型与图谱化块(Blocks)](#page-4), [发布、可观测性与运维](#page-12)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mark/store/sqlite.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/store/sqlite.py)
- [src/mark/store/json_store.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/store/json_store.py)
- [src/mark/store/activity_log.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/store/activity_log.py)
- [src/mark/security/encryption.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/security/encryption.py)
- [src/mark/security/hasher.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/security/hasher.py)
- [src/mark/security/redaction.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/security/redaction.py)
# 本地存储、加密与可观测存储
## 概述与设计目标
MARK SDK 在本地侧提供了一套分层的数据落地与可观测能力，由 `src/mark/store/` 子包与 `src/mark/security/` 子包共同承担。其核心目标可归纳为三点：
- **持久化**：将结构化与半结构化的运行时数据以 SQLite 或 JSON 形式落地，便于离线分析与跨进程共享。
- **机密性**：对落盘前的敏感字段进行加密或哈希处理，并通过脱敏规则控制日志可观测性。
- **可观测性**：在不泄露明文的前提下，记录可追溯的活动日志（activity log），供审计、调试与 MCP 集成使用。
资料来源：[src/mark/store/sqlite.py:1-40]() [src/mark/security/encryption.py:1-30]()
## 本地存储层
`store/` 子包对外暴露三种适配不同语义的持久化后端，按使用场景区分如下：
| 后端 | 典型用途 | 关键特性 |
|------|----------|----------|
| SQLite | 关系型、可查询的批量数据 | 支持事务、索引、批量 upsert |
| JSON Store | 配置、缓存、轻量快照 | 原子写入、人类可读 |
| Activity Log | 可观测事件流 | 追加写、按时间滚动 |
### SQLite 存储
`sqlite.py` 提供基于标准库 `sqlite3` 的封装，连接对象以线程局部或上下文方式管理，事务粒度对齐单次写入单元。该模块通常用于保存需要按字段检索的结构化记录。
```mermaid
graph LR
A[业务调用] --> B[SQLiteStore]
B --> C[(sqlite3 DB)]
B --> D[事务边界]
D --> C
```
资料来源：[src/mark/store/sqlite.py:20-80]()
### JSON 存储
`json_store.py` 面向配置与小体量快照，强调原子性（先写临时文件再 `os.replace`）与跨平台路径处理，避免半写状态。其键空间通常以字符串命名，便于外部工具直接读取。
资料来源：[src/mark/store/json_store.py:1-60]()
### 活动日志
`activity_log.py` 实现追加式事件流，常用于与 MCP 集成层联动。事件以 JSON 行（JSONL）或独立记录形式追加，写入路径与 SQLite/JSON 解耦，确保日志 I/O 不会阻塞业务事务。
资料来源：[src/mark/store/activity_log.py:1-50]()
## 安全与加密
`security/` 子包为本地存储提供“写前保护”能力，三者职责互补：
### 数据加密
`encryption.py` 封装对称加密原语，提供密钥派生、IV 生成与序列化接口。落盘前由调用方决定是否加密；解密仅在受信任上下文内进行，避免在 Activity Log 中泄露明文。
资料来源：[src/mark/security/encryption.py:30-90]()
### 哈希
`hasher.py` 提供确定性哈希能力，适用于指纹、幂等键与去重场景。其与加密的关键差异在于：哈希不可逆，可安全写入 Activity Log 而不构成泄露。
资料来源：[src/mark/security/hasher.py:1-40]()
### 敏感数据脱敏
`redaction.py` 在序列化前对已知敏感字段（如密钥、令牌、个人标识）进行掩码或替换，使 Activity Log 即使包含上下文也保持“可观测但不可逆推”。该模块通常与 `activity_log.py` 串联使用。
资料来源：[src/mark/security/redaction.py:1-50]()
## 可观测存储的数据流
从调用到落盘的完整路径可概括为四步：
1. 业务层产生结构化数据与敏感字段。
2. `encryption.py` / `hasher.py` 决定加密或哈希策略。
3. 数据写入 `sqlite.py` 或 `json_store.py`；事件描述符写入 `activity_log.py`。
4. `redaction.py` 对日志条目进行脱敏，确保审计可见但明文不可恢复。
该流水线与 v0.2.0a5 中强调的 MCP 集成改进直接相关：MCP 客户端在拉取活动记录时，依赖 `redaction.py` 保证跨进程传输安全。资料来源：[src/mark/store/activity_log.py:30-70]() [src/mark/security/redaction.py:20-60]() [src/mark/store/sqlite.py:60-100]()
---
## 扩展点：插件、策略、技能与适配器
### 相关页面
相关主题：[中间件(Middleware)框架](#page-6), [框架适配器：LangChain、LangGraph 与 MCP](#page-7)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mark/plugins/registry.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/plugins/registry.py)
- [src/mark/policies/registry.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/policies/registry.py)
- [src/mark/policies/base.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/policies/base.py)
- [src/mark/policies/builtin.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/policies/builtin.py)
- [src/mark/middlewares/skills/base.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/skills/base.py)
- [src/mark/middlewares/skills/builtin.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/skills/builtin.py)
# 扩展点：插件、策略、技能与适配器
MARK SDK 通过一组明确划分的**扩展点（extension points）** 允许使用者与生态贡献者在不修改核心代码的前提下，向 SDK 注入新能力、调整行为或替换默认实现。本页梳理这些扩展点的目录布局、注册机制以及它们之间的关系。
## 一、扩展点全景
MARK SDK 的扩展机制由三个并列的子系统组成，每个子系统都遵循「抽象基类 + 注册表 + 内置实现」的相同模式：
| 扩展点 | 主要职责 | 注册表位置 | 内置实现位置 |
|--------|----------|------------|--------------|
| 插件（Plugin） | 接入新的外部服务、能力或工具 | `src/mark/plugins/registry.py` | （由生态提供） |
| 策略（Policy） | 控制 SDK 的决策、限流、路由等行为规则 | `src/mark/policies/registry.py` | `src/mark/policies/builtin.py` |
| 技能（Skill） | 在中间件管线中插入可复用的处理动作 | `src/mark/middlewares/skills/base.py` | `src/mark/middlewares/skills/builtin.py` |
资料来源：[src/mark/plugins/registry.py:1-40]()、[src/mark/policies/registry.py:1-40]()、[src/mark/middlewares/skills/base.py:1-30]()。
## 二、插件（Plugin）子系统
插件是最高层级的扩展点，用于把整个外部能力（数据源、模型、第三方 API 客户端等）以统一契约接入 SDK。`src/mark/plugins/registry.py` 维护一张名称到插件类的映射表，SDK 启动时按名称查找并实例化。
```mermaid
flowchart LR
A[用户调用 SDK] --> B[Plugin Registry]
B -- lookup by name --> C[Plugin 实例]
C --> D[外部能力/服务]
```
核心契约要点：
- 注册通过装饰器或显式 `register()` 调用完成，集中存放在注册表单例中。
- 插件可通过配置文件按需启用，避免硬编码导入。
- 注册表是线程安全的查找入口，可被策略和技能内部复用。
资料来源：[src/mark/plugins/registry.py:1-80]()。
## 三、策略（Policy）子系统
策略决定 SDK 在面对一次请求时应「如何行动」——例如选择路由、设定超时、应用限流或回退默认实现。
- **`Policy` 基类**：定义所有策略必须实现的统一接口，位于 `src/mark/policies/base.py`。它暴露 `apply(context)` 等抽象方法，并提供默认的上下文传递约定。
资料来源：[src/mark/policies/base.py:1-60]()。
- **注册表**：`src/mark/policies/registry.py` 按名称管理策略类，SDK 内部通过名称解析得到具体策略实例。
资料来源：[src/mark/policies/registry.py:1-60]()。
- **内置策略**：`src/mark/policies/builtin.py` 提供了若干开箱即用的实现（例如默认路由策略、保守回退策略），既可直接使用，也可作为自定义策略的参考范例。
资料来源：[src/mark/policies/builtin.py:1-80]()。
调用顺序一般遵循「**注册表解析 → 基类实例化 → `apply()` 求值**」三步，保证不同策略之间可以组合与替换。
## 四、技能（Skill）子系统
技能是中间件层（`middlewares`）中的最小动作单元，承担「对一次调用执行一步处理」的职责，例如记录审计日志、重试一次请求、转换输出格式。
- **`Skill` 基类**：定义生命周期钩子 `before` / `after`，使得技能可以包装调用过程。位置：`src/mark/middlewares/skills/base.py`。
资料来源：[src/mark/middlewares/skills/base.py:1-80]()。
- **内置技能**：`src/mark/middlewares/skills/builtin.py` 收录了常用技能实现，如日志记录、指标埋点与重试控制。
资料来源：[src/mark/middlewares/skills/builtin.py:1-80]()。
技能与策略的差异在于：策略控制「**选什么、走哪条路**」，技能控制「**在执行路径上做哪一步动作**」。两者通过中间件管线串接，由 SDK 统一调度。
## 五、扩展实践指引
1. **新增插件**：实现插件协议后调用 `register()`，并在配置中按名称启用。
2. **新增策略**：继承 `Policy` 基类，覆盖 `apply()`，再注册到策略表。
3. **新增技能**：继承 `Skill`，实现 `before/after` 钩子，挂载到目标中间件。
4. **组合使用**：策略可以在内部触发插件；技能可以读取策略产出的上下文，从而形成「插件 → 策略 → 技能」的可观测调用链。
社区反馈显示，v0.2.0a5 的 MCP 集成改进正是借助这一扩展点结构落地，第三方贡献者可按相同模式接入新的 MCP 服务端，无需改动核心代码。
资料来源：[src/mark/plugins/registry.py:40-120]()、[src/mark/policies/registry.py:40-120]()、[src/mark/middlewares/skills/base.py:60-120]()。
---
## 中间件电池：沙箱、同步、媒体连续性与缺口修复
### 相关页面
相关主题：[中间件(Middleware)框架](#page-6), [本地存储、加密与可观测存储](#page-9)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mark/middlewares/sandbox/middleware.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/sandbox/middleware.py)
- [src/mark/middlewares/sandbox/docker.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/sandbox/docker.py)
- [src/mark/middlewares/sandbox/Dockerfile](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/sandbox/Dockerfile)
- [src/mark/middlewares/sandbox/compose.yaml](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/sandbox/compose.yaml)
- [src/mark/middlewares/sync/middleware.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/sync/middleware.py)
- [src/mark/middlewares/sync/cloud.py](https://github.com/emsoftanalytics/MARK-SDK/blob/main/src/mark/middlewares/sync/cloud.py)
# 中间件电池：沙箱、同步、媒体连续性与缺口修复
## 模块定位与作用域
中间件电池是 MARK SDK 中负责在应用核心逻辑与外部系统之间插入横切能力的组件集合，主要位于 `src/mark/middlewares/` 目录下。它通过可插拔的中间件接口，为上层业务（如媒体分析、跨平台同步、缺口修复）提供以下能力：
- **隔离执行环境**：通过沙箱中间件在容器化环境中运行不可信或资源密集型任务。
- **跨端状态同步**：通过同步中间件协调本地与云端之间的一致性。
- **媒体连续性与缺口修复**：在媒体流或时间序列数据出现中断时，提供缺口检测与可重入修复能力。
三个子能力由不同中间件承载，并通过统一的钩子协议串联，对上层应用表现为一致的"中间件链"。
资料来源：[src/mark/middlewares/sandbox/middleware.py:1-50]()；[src/mark/middlewares/sync/middleware.py:1-50]()
## 沙箱中间件：基于容器的隔离执行
沙箱中间件（`sandbox` 子包）是中间件电池中负责"安全执行"的核心组件，由四个文件协同构成：
- `middleware.py`：暴露给上层应用的中间件抽象，定义沙箱调用协议与事件钩子；
- `docker.py`：基于 Docker 引擎的具体执行后端，负责容器生命周期管理与命令下发；
- `Dockerfile`：定义沙箱镜像的基础环境、依赖与默认入口；
- `compose.yaml`：定义本地或 CI 环境下的多服务组合方式，用于端到端验证。
`middleware.py` 对外暴露统一接口；`docker.py` 将请求翻译为 Docker API 调用；镜像由 `Dockerfile` 构建，运行编排由 `compose.yaml` 提供。典型执行流如下：
```mermaid
flowchart LR
A[应用调用] --> B[middleware.py
入口适配]
B --> C[docker.py
容器调度]
C --> D[Dockerfile
构建镜像]
C --> E[compose.yaml
本地编排]
D --> F[隔离执行]
E --> F
F --> G[结果回传]
```
沙箱中间件的设计动机是：把可能在外部数据、第三方代码或资源密集型计算上的副作用，限制在可丢弃的容器内，从而保护宿主应用的状态完整性，这恰好为后续的"缺口修复回放"提供了可重放的隔离场所。
资料来源：[src/mark/middlewares/sandbox/middleware.py:1-100]()；[src/mark/middlewares/sandbox/docker.py:1-100]()；[src/mark/middlewares/sandbox/Dockerfile:1-30]()；[src/mark/middlewares/sandbox/compose.yaml:1-30]()
## 同步中间件：本地与云端的协调
同步中间件（`sync` 子包）专注于跨端数据一致性，是中间件电池中处理"状态分发"的部分：
- `middleware.py`：提供同步钩子，挂在 SDK 的事件循环上，按策略触发上传或下载；
- `cloud.py`：实现与远端对象存储或分析平台的协议层，处理认证、断点续传与冲突合并。
二者协同工作：`middleware.py` 决定"何时同步"，`cloud.py` 决定"如何同步"。在 v0.2.0a5 发布中提到的"MCP 集成改进"与"可信发布支持"通常会通过 `cloud.py` 的协议层与 `middleware.py` 的钩子得到体现：协议层吸收新的 MCP 端点能力，钩子层把发布凭证与签名校验纳入同步前置流程。
资料来源：[src/mark/middlewares/sync/middleware.py:1-80]()；[src/mark/middlewares/sync/cloud.py:1-80]()
## 媒体连续性与缺口修复闭环
媒体连续性指在长时间运行的媒体流或采样任务中保持不中断的数据采集与回放能力；缺口修复（gap repair）则负责在检测到中断后，以可重入的方式补齐缺失片段。在中间件电池的语境下，三者形成闭环：
- **沙箱** 提供受控、可重放的执行容器，使缺口修复的回放实验能够隔离运行而不污染主环境。
- **同步** 把修复后的结果可靠地上传至云端，或从云端拉取历史片段用于比对。
- 通过中间件事件总线串联，形成"检测 → 隔离修复 → 跨端同步"的闭环。
集成要点：
1. **注册顺序**：在 SDK 启动入口中，先注册 `sync` 再注册 `sandbox`，以确保同步通道在沙箱写入之前就绪。
2. **版本对齐**：沙箱镜像版本（`Dockerfile`）与云端协议版本（`cloud.py`）应保持主版本一致，避免缺口修复时出现协议不匹配。
3. **可观测性**：两个中间件均提供事件回调，便于接入日志、指标与审计，用于定位缺口产生的根因。
资料来源：[src/mark/middlewares/sandbox/middleware.py:50-200]()；[src/mark/middlewares/sync/middleware.py:80-180]()；[src/mark/middlewares/sync/cloud.py:50-180]()
---
## 发布、可观测性与运维
### 相关页面
相关主题：[MARK SDK 概览与快速上手](#page-1), [本地存储、加密与可观测存储](#page-9)
相关源码文件
以下源码文件用于生成本页说明：
- [CHANGELOG.md](https://github.com/emsoftanalytics/MARK-SDK/blob/main/CHANGELOG.md)
- [ROADMAP.md](https://github.com/emsoftanalytics/MARK-SDK/blob/main/ROADMAP.md)
- [VERSIONING.md](https://github.com/emsoftanalytics/MARK-SDK/blob/main/VERSIONING.md)
- [CONTRIBUTING.md](https://github.com/emsoftanalytics/MARK-SDK/blob/main/CONTRIBUTING.md)
- [SECURITY.md](https://github.com/emsoftanalytics/MARK-SDK/blob/main/SECURITY.md)
- [CODE_OF_CONDUCT.md](https://github.com/emsoftanalytics/MARK-SDK/blob/main/CODE_OF_CONDUCT.md)
- [pyproject.toml](https://github.com/emsoftanalytics/MARK-SDK/blob/main/pyproject.toml)
- [README.md](https://github.com/emsoftanalytics/MARK-SDK/blob/main/README.md)
# 发布、可观测性与运维
本页面向集成与运维人员说明 MARK SDK 的发布机制、可观测性接入点以及日常运维职责。所有结论仅来源于仓库内可检索的元数据与文档文件。
## 1. 版本与发布治理
MARK SDK 采用显式语义化版本方案，版本号格式为 `MAJOR.MINOR.PATCH`，并通过 `v` 前缀的 Git 标签对外发布，例如当前最新公开版本 `v0.2.0a5` 中的 `a5` 后缀表明其仍处于 alpha 预发布阶段。
- **版本策略**：版本演进规则与兼容性承诺记录在 `VERSIONING.md` 中，预发布（alpha/beta/rc）与稳定版的晋升路径在此文件集中描述 `资料来源：[VERSIONING.md:1-40]()`。
- **变更日志**：`CHANGELOG.md` 按版本逆序记录每一次发布的功能、修复与破坏性变更，`v0.2.0a5` 条目明确列出 "PyPI package published"、"Trusted Publishing support"、"MCP integration improvements"、"Documentation updates" 四项要点 `资料来源：[CHANGELOG.md:1-25]()`。
- **发布通道**：Python 发行物通过 PyPI 提供，安装命令为 `pip install mark-sdk`，配套 GitHub Releases 页面提供二进制与源码归档 `资料来源：[README.md:1-60]()`。
| 通道 | 用途 | 引用 |
| --- | --- | --- |
| GitHub Releases | 源码归档、Release Notes | `资料来源：[CHANGELOG.md:1-25]()` |
| PyPI (`mark-sdk`) | 正式发行版安装 | `资料来源：[README.md:1-60]()` |
| Trusted Publishing | 无令牌 OIDC 发布 | `资料来源：[pyproject.toml:1-80]()` |
## 2. 可观测性与 MCP 集成
MARK SDK 把"可观测性"定义为对外部数据与分析会话的状态可见性，核心接入点是 **MCP（Model Context Protocol）集成**。
- **集成改进**：`v0.2.0a5` 在 CHANGELOG 中专门标注 "MCP integration improvements"，意味着传输层、错误回调与会话追踪在最近一次发布中获得了修正或扩展 `资料来源：[CHANGELOG.md:1-25]()`。
- **诊断信号**：仓库内未提供独立的 OpenTelemetry/日志中间件；可观测性依赖上层应用注入 MCP 客户端事件，并以 SDK 抛出异常为故障信号源。
- **协议接入点**：MCP 服务器端点、传输类型（stdio / SSE / streamable-http）等配置位于 SDK 初始化参数中，运行期日志通过标准 `logging` 模块输出，运维方可按需接入集中式日志系统。
## 3. 贡献、评审与运维职责
发布并非单人动作，MARK SDK 在治理层面明确了贡献者、维护者与安全响应者的分工。
- **贡献流程**：所有非琐碎改动需通过 Pull Request 提交，CI 必须保持绿色，并由维护者评审合入，流程细则记录在 `CONTRIBUTING.md` 中 `资料来源：[CONTRIBUTING.md:1-80]()`。
- **行为准则**：社区互动需遵循 `CODE_OF_CONDUCT.md` 中定义的尊重与包容条款，违规将由维护者团队按既定流程处理 `资料来源：[CODE_OF_CONDUCT.md:1-60]()`。
- **安全披露**：安全漏洞应通过 `SECURITY.md` 中描述的私密渠道（通常为 GitHub Security Advisories 或专用邮箱）提交，**禁止**在公开 Issue 中披露未修复漏洞 `资料来源：[SECURITY.md:1-50]()`。
- **路线图对齐**：`ROADMAP.md` 列出后续版本的优先级项，运维在制定 SLA 与变更窗口时应参考该路线图，避免与即将到来的破坏性变更冲突 `资料来源：[ROADMAP.md:1-60]()`。
## 4. 发布与运维检查清单
为降低发布风险，建议运维团队在每次版本升级前完成以下核对：
1. 核对 `CHANGELOG.md` 中是否存在 **Breaking Changes** 段落，并据此评估 SDK 消费者迁移成本 `资料来源：[CHANGELOG.md:1-25]()`。
2. 确认 `VERSIONING.md` 标注的预发布/稳定状态与生产环境部署策略一致；alpha/rc 包应仅用于预生产环境 `资料来源：[VERSIONING.md:1-40]()`。
3. 复核 Trusted Publishing 配置（`pyproject.toml` 中 `[project.publish]` 与 OIDC 信任关系），防止令牌回退引入凭据泄漏 `资料来源：[pyproject.toml:1-80]()`。
4. 在升级窗口内对照 `ROADMAP.md` 预留回滚方案，特别关注即将弃用的 API 标注 `资料来源：[ROADMAP.md:1-60]()`。
5. 触发 MCP 集成冒烟用例，验证可观测性信号在升级后仍按预期上报 `资料来源：[CHANGELOG.md:1-25]()`。
> 社区提示：`v0.2.0a5` 仍属 alpha 阶段，PyPI 与 GitHub Releases 同步发布，运维在生产环境采纳前应等待首个稳定版本，并持续关注 Trusted Publishing 配置变更通告。
---
---
## Doramagic 踩坑日志
项目：emsoftanalytics/MARK-SDK
摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。
## 1. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/emsoftanalytics/MARK-SDK | README/documentation is current enough for a first validation pass.
## 2. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/emsoftanalytics/MARK-SDK | last_activity_observed missing
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/emsoftanalytics/MARK-SDK | no_demo; severity=medium
## 4. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/emsoftanalytics/MARK-SDK | no_demo; severity=medium
## 5. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/emsoftanalytics/MARK-SDK | issue_or_pr_quality=unknown
## 6. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/emsoftanalytics/MARK-SDK | release_recency=unknown