# https://github.com/retospect/precis-mcp 项目说明书

生成时间：2026-07-19 09:33:13 UTC

## 目录

- [概述、安装与七个动词](#page-overview)
- [Kinds 系统、Handler 架构与文件类型寻址](#page-architecture)
- [数据存储、迁移与后台 Worker](#page-data)
- [部署、插件开发、Web UI 与运维](#page-ops)

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

## 概述、安装与七个动词

### 相关页面

相关主题：[Kinds 系统、Handler 架构与文件类型寻址](#page-architecture), [部署、插件开发、Web UI 与运维](#page-ops)

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

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

- [README.md](https://github.com/retospect/precis-mcp/blob/main/README.md)
- [pyproject.toml](https://github.com/retospect/precis-mcp/blob/main/pyproject.toml)
- [src/precis/server.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/server.py)
- [src/precis/dispatch.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/dispatch.py)
- [src/precis/handlers/ref.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/ref.py)
- [src/precis/handlers/paper.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/paper.py)
- [src/precis/handlers/markdown.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/markdown.py)
- [src/precis/handlers/text.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/text.py)
- [src/precis/handlers/todo.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/todo.py)
- [docs/user-facing/seven-verb-surface-migration.md](https://github.com/retospect/precis-mcp/blob/main/docs/user-facing/seven-verb-surface-migration.md)
</details>

# 概述、安装与七个动词

## 一、项目概述

`precis-mcp` 是一个面向模型上下文协议（Model Context Protocol, MCP）的服务器，专注于为长文档（论文 DOCX、LaTeX、Markdown、TXT、Todo 等）提供**精确定位读写**能力。其核心思路是把"打开整篇文档→翻页查找段落"的过程抽象成由 URI 选择器定位的小粒度操作，使 LLM 可以在不消耗大量上下文窗口的前提下，对文档中的特定段落、章节、参考文献条目进行导航与编辑。

资料来源：[README.md:1-30]()

服务器在 v3.0.0 中引入了 `RefHandler` 基类，将论文、Markdown、纯文本等不同文档格式统一抽象为"参考资源（Reference Resource）"模型，并新增了 `MarkdownHandler`、`PlainTextHandler`、`TodoHandler` 三种零依赖或近零依赖的处理器。资料来源：[docs/user-facing/seven-verb-surface-migration.md:1-25]()

## 二、安装与启动

通过 `pyproject.toml` 可知项目以标准 PEP 621 方式打包，Python ≥ 3.10，安装方式支持两种主流工具链：

```bash
# 方式一：uv（推荐）
uv tool install precis-mcp

# 方式二：pip
pip install precis-mcp
```

资料来源：[pyproject.toml:1-40]()

启动后，进程会以 stdio MCP 服务器的形式注册七个工具动词。客户端（如 Claude Desktop、MCP Inspector）只需在配置中指定命令 `precis-mcp` 即可建立连接。资料来源：[src/precis/server.py:1-60]()

激活文档是所有后续动词的前置动作：调用 `activate(path_or_uri)` 后，服务器会在内部缓存一份可寻址资源树，后续 `get`/`toc`/`put` 都基于这个活动资源工作。

## 三、七个核心动词

`precis-mcp` 暴露给 MCP 客户端的固定动词集合共七个，是整个产品形态的"用户面"。

| 动词 | 用途 | 典型用法 |
|------|------|----------|
| `activate` | 装载一篇文档为当前活动资源 | `activate("paper:precis-v3")` |
| `list` | 列出可用资源或文献库 | `list()` |
| `toc` | 输出文档的目录结构（两层级 TOC） | `toc("paper:precis-v3")` |
| `get` | 按 URI 选取符读出段落或条目 | `get("paper:precis-v3~38")` |
| `search` | 在活动文档中检索关键词 | `search("citation hint")` |
| `put` | 替换或插入段落/引用条目 | `put("paper:precis-v3~38", "...")` |
| `bib` | 查看或维护参考文献元数据 | `bib("precis-v3")` |

资料来源：[src/precis/server.py:60-180]()、[src/precis/dispatch.py:1-80]()

URI 选择器在 v3.0.0 中由 `#` 改为 `~`，例如 `paper:slug~38`、`doc.docx~PLXDX`，避免与 HTML 锚点以及 Markdown 标题语法产生歧义。资料来源：[docs/user-facing/seven-verb-surface-migration.md:30-55]()

## 四、处理器分层与扩展点

服务器内部把"解析 URI → 路由到具体处理器 → 调用底层动词"分成三层：

```mermaid
flowchart LR
  A[MCP Client] --> B[server.py<br/>七个动词入口]
  B --> C[dispatch.py<br/>URI 解析]
  C --> D{Handler<br/>选择}
  D -->|docx/latex| E[PaperHandler]
  D -->|.md| F[MarkdownHandler]
  D -->|.txt| G[PlainTextHandler]
  D -->|todo:| H[TodoHandler]
  E --> I[RefHandler 基类]
  F --> I
  G --> I
  H --> I
```

`RefHandler` 作为基类承载 `activate/get/put/search/toc` 等通用行为；子类只需实现与文件格式相关的读写与段落分组逻辑（如 `group_paragraphs()`）。这种结构使得新增格式只需继承 `RefHandler` 即可复用大部分动词语义。资料来源：[src/precis/handlers/ref.py:1-50]()

`put` 动词在 v2.2.1 中修复了多段落批量插入时把 `## Heading\n\nBody` 合并到同一段落的缺陷，新增 `_insert_chunks_after()` 辅助函数以保证顺序插入。资料来源：[src/precis/handlers/paper.py:120-180]()

`TodoHandler` 依赖外部 `acatome-store` 包，提供有限状态机式的待办管理能力，因此属于可选扩展。资料来源：[src/precis/handlers/todo.py:1-40]()

---

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

## Kinds 系统、Handler 架构与文件类型寻址

### 相关页面

相关主题：[概述、安装与七个动词](#page-overview), [数据存储、迁移与后台 Worker](#page-data)

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

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

- [src/precis/handlers/__init__.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/__init__.py)
- [src/precis/handlers/markdown.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/markdown.py)
- [src/precis/handlers/plaintext.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/plaintext.py)
- [src/precis/handlers/paper.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/paper.py)
- [src/precis/handlers/patent.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/patent.py)
- [src/precis/handlers/draft.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/draft.py)
</details>

# Kinds 系统、Handler 架构与文件类型寻址

## 概述

precis-mcp 是一个面向 LLM 客户端的 MCP（Model Context Protocol）服务器，其核心抽象由 **Handler（处理器）** 与 **Kinds（资源种类）** 共同构成。每一个可被读取、检索或修改的资源——无论是 DOCX 论文、LaTeX 草稿、Markdown 文件、纯文本文档，还是 Todo 状态机——都由一个专门的 Handler 负责处理；每个 Handler 会声明它所代表的 `kind`（资源种类）、可识别的 URI scheme 以及支持的文件扩展名。这种"按类型路由"的架构使新增文件格式时无需改动调度层，只需继承 `RefHandler` 基类即可被自动纳入。系统通过统一的 URI 语法把"哪一类文件"与"文件中哪一段"两件事合并表达，从而让 LLM 工具调用既简洁又精确。

资料来源：[src/precis/handlers/__init__.py:1-80]()

## Handler 架构

### RefHandler 抽象基类

v3.0.0 将原本内嵌于 `PaperHandler` 的通用能力抽离为 `RefHandler` 抽象基类，作为所有类型处理器的统一父类。子类通过覆盖钩子方法（`can_handle`、`activate`、`get`、`put` 等）定义各自对 URI 的解析、激活、读取与写入语义；调度层只依赖基类契约，从而实现 Handler 之间的多态替换。

```mermaid
classDiagram
    class RefHandler {
        <<abstract>>
        +kind: str
        +scheme: str
        +extensions: list
        +can_handle(uri) bool
        +activate(uri) Any
        +get(uri, ...) str
        +put(uri, text) str
    }
    RefHandler <|-- PaperHandler
    RefHandler <|-- PatentHandler
    RefHandler <|-- DraftHandler
    RefHandler <|-- MarkdownHandler
    RefHandler <|-- PlainTextHandler
    RefHandler <|-- TodoHandler
```

资料来源：[src/precis/handlers/__init__.py:20-140]()、[src/precis/handlers/paper.py:1-60]()

### 已注册的 Handler 与 Kind

| Handler | scheme / kind | 文件扩展名 | 主要依赖 | 说明 |
|---|---|---|---|---|
| PaperHandler | `paper:` | `.docx` | python-docx 等 | 学术论文，节点寻址 `paper:slug~N` |
| PatentHandler | `patent:` | （slug 形式） | 同 paper 类 | 专利文献 |
| DraftHandler | `draft:` | `.tex`、`.latex` | 原始文件读写 | 草稿文档 |
| MarkdownHandler | 文件路径 | `.md`、`.markdown` | **零依赖** | v3.0.0 引入 |
| PlainTextHandler | 文件路径 | `.txt`、`.text` | **零依赖** | v3.0.0 引入 |
| TodoHandler | `todo:` | （状态机入口） | acatome-store | v3.0.0 引入 |

资料来源：[src/precis/handlers/__init__.py:40-120]()、[src/precis/handlers/markdown.py:1-50]()、[src/precis/handlers/plaintext.py:1-50]()、[src/precis/handlers/draft.py:1-50]()

## 文件类型寻址（Addressing）

### URI 形式

precis-mcp 的 URI 形如 `<scheme>:<selector>` 或 `<file>:<selector>`，两部分各自承担：

- `scheme` —— 决定由哪个 Handler 处理，等价于"哪一类文件"；
- `selector` —— 在该文件内部定位位置（段落、节点、章节等），等价于"文件中哪一段"。

### v3.0.0 破坏性变更：选择器分隔符

v3.0.0 把选择器分隔符从 `#` 改为 `~`，以避免与 Markdown 标题锚点、URL fragment 冲突。升级时需对历史调用做全局替换。

| 旧写法（≤ v2.x） | 新写法（≥ v3.0.0） | 含义 |
|---|---|---|
| `paper:slug#38` | `paper:slug~38` | 论文第 38 个节点 |
| `doc.docx#PLXDX` | `doc.docx~PLXDX` | DOCX 中 ID 为 `PLXDX` 的节点 |

资料来源：[src/precis/handlers/__init__.py:60-160]()

### 典型寻址示例

- `paper:slug~38`：定位某篇论文（按 slug 索引）的第 38 个段落；
- `doc.docx~PLXDX`：定位本地 DOCX 文件中段落 ID 为 `PLXDX` 的节点；
- `draft:foo.tex~H2-3`：定位 LaTeX 草稿第二个二级标题后的内容；
- `todo:`：进入 TodoHandler 状态机入口，无显式 selector；
- `README.md~L20-40`：MarkdownHandler 按行号切片。

资料来源：[src/precis/handlers/paper.py:30-120]()、[src/precis/handlers/draft.py:30-90]()、[src/precis/handlers/markdown.py:30-80]()

### 段落路径与标题分隔符

v0.4.0 起引入 `¶` 段落路径与 `|` 标题分隔符作为内部路径表达，用于在 `get`/`put` 结果中以紧凑形式呈现层级。LaTeX 文档则自 v0.3.1 起改为"原始文件读写"模式，跳过自动段落切分，多行文本按字面写入。

资料来源：[src/precis/handlers/draft.py:1-60]()

## 演进摘要

- **v0.2.0**：初始 PyPI 发布，仅支持 DOCX 与 LaTeX 两种 kind；
- **v0.3.1**：LaTeX 走原始读写分支，避免多行内容被误切；
- **v0.4.0**：引入 `¶` 段落路径与 `|` 标题分隔符；
- **v3.0.0**：抽象出 `RefHandler` 基类，新增 Markdown、PlainText、Todo 三个零依赖或外部存储依赖的 Handler，并把选择器分隔符从 `#` 改为 `~`。

资料来源：[src/precis/handlers/__init__.py:1-60]()、[src/precis/handlers/plaintext.py:1-40]()

> 升级提示：迁移至 v3.0.0 时请先做 URI 替换（`#` → `~`），再按需扩展自定义 Handler，只需实现 `RefHandler` 的钩子方法即可被调度层识别。

---

<a id='page-data'></a>

## 数据存储、迁移与后台 Worker

### 相关页面

相关主题：[Kinds 系统、Handler 架构与文件类型寻址](#page-architecture), [部署、插件开发、Web UI 与运维](#page-ops)

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

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

- [src/precis/store/store.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/store/store.py)
- [src/precis/store/pool.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/store/pool.py)
- [src/precis/store/migrate.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/store/migrate.py)
- [src/precis/migrations/0001_initial.sql](https://github.com/retospect/precis-mcp/blob/main/src/precis/migrations/0001_initial.sql)
- [src/precis/migrations/baseline/schema.sql](https://github.com/retospect/precis-mcp/blob/main/src/precis/migrations/baseline/schema.sql)
- [src/precis/embedder.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/embedder.py)
</details>

# 数据存储、迁移与后台 Worker

## 概述

precis-mcp 是一个面向 DOCX、LaTeX、Markdown、纯文本以及待办事项的 MCP (Model Context Protocol) 服务，其核心能力是让大语言模型通过统一的 URI 选择器（如 `paper:slug~38`、`doc.docx~PLXDX`）对结构化文档进行读取、检索与就地编辑。为了支撑这些跨格式的读写操作，系统需要一个稳定、可迁移、并在后台异步维护索引的存储层。本页聚焦于 `src/precis/store/` 子包、SQL 迁移目录以及 `src/precis/embedder.py` 中负责数据持久化、模式演进与后台向量化的关键模块。资料来源：[src/precis/store/store.py:1-40]()

## 存储架构

存储层主要由 `store.py`、`pool.py` 以及 `migrations/baseline/schema.sql` 共同构成，采用「连接池 + 嵌入式关系数据库」的模式。`pool.py` 提供线程/协程安全的连接获取与归还逻辑，避免 MCP 在并发工具调用下反复打开数据库句柄；`store.py` 则在连接池之上封装了论文、文档、章节、段落、引用键 (slug) 等领域对象的高层 API。资料来源：[src/precis/store/pool.py:1-60]() 资料来源：[src/precis/store/store.py:40-120]()

baseline 模式 (`schema.sql`) 定义了最基础的表结构，包括文档主表、段落表、章节表、引用键表以及用于全文检索的索引字段；`0001_initial.sql` 则记录首次迁移的 DDL 变更。两者的分离使得「干净安装」与「升级安装」共享同一份领域模型。资料来源：[src/precis/migrations/baseline/schema.sql:1-80]() 资料来源：[src/precis/migrations/0001_initial.sql:1-40]()

下表概括了核心数据表与其用途：

| 表名 | 主要职责 |
| --- | --- |
| `documents` | 保存源文件元数据 (路径、格式 handler、激活状态) |
| `sections` | 章节级路径，支持两段式 TOC 与 `~` 选择器跳转 |
| `paragraphs` | 段落正文及其与文档/章节的从属关系 |
| `cite_keys` | 解析 `[@slug]` 形式的引用键，供 malformed citation 检测使用 |

资料来源：[src/precis/migrations/baseline/schema.sql:30-140]() 资料来源：[src/precis/store/store.py:120-200]()

## 迁移机制

`src/precis/store/migrate.py` 负责模式演进。它在启动时检测当前 schema 版本，与 `migrations/` 目录中的有序脚本比对，并按顺序应用尚未执行的迁移。迁移脚本以纯 SQL 形式存放，便于审计与回滚；每一次成功的迁移都会写入版本表，从而支持断点续迁。资料来源：[src/precis/store/migrate.py:1-100]()

迁移的设计与项目历史密切相关：v2.x 系列多次涉及引用提示、两级 TOC、段落路径等行为变更，因此新增字段（如 `cite_hint`、`heading_path`）通常以幂等 ALTER 形式追加，而非重建表。这种演进方式保障了用户在升级到 v3.0.0 时，原有 `paper:slug#N` 的引用可以通过自动化迁移平滑切换到 `~` 分隔符。资料来源：[src/precis/store/migrate.py:100-180]()

## 后台 Worker 与 Embedder

`src/precis/embedder.py` 提供了与后台向量化相关的抽象：它定义了 embedder 接口（如 `embed(text) -> list[float]`），并暴露供 store 层在段落入库或更新后触发的钩子。MCP 工具调用 (`put`、`activate`) 通常先同步落库，再将段落文本推入后台队列，由 worker 异步生成嵌入向量并写回检索表，从而让 `search`、`toc` 等读取路径在响应时只查询已构建好的索引。资料来源：[src/precis/embedder.py:1-120]()

后台 Worker 的存在也解释了在 v2.2.1 中出现的多段落 `put` 修复：插入多块文本时，`store.py` 会先按 `group_paragraphs()` 拆分为独立的 h/p 节点，再分块提交，再交由 embedder 逐块向量化，保证 TOC 与搜索结果在并发写入后仍然一致。资料来源：[src/precis/store/store.py:200-260]()

此外，TodoHandler (v3.0.0 新增) 与可选的 `acatome-store` 后端通过统一的 store 接口接入，因此迁移模块与连接池同样需要兼容待办事项的 schema，体现了存储层在多 handler 复用方面的中心地位。资料来源：[src/precis/store/store.py:260-320]() 资料来源：[src/precis/store/migrate.py:180-240]()

---

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

## 部署、插件开发、Web UI 与运维

### 相关页面

相关主题：[概述、安装与七个动词](#page-overview), [数据存储、迁移与后台 Worker](#page-data)

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

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

- [deploy/site.yml](https://github.com/retospect/precis-mcp/blob/main/deploy/site.yml)
- [deploy/playbooks/20-precis-worker.yml](https://github.com/retospect/precis-mcp/blob/main/deploy/playbooks/20-precis-worker.yml)
- [deploy/playbooks/28-precis-watch.yml](https://github.com/retospect/precis-mcp/blob/main/deploy/playbooks/28-precis-watch.yml)
- [deploy/playbooks/40-precis-heartbeat.yml](https://github.com/retospect/precis-mcp/blob/main/deploy/playbooks/40-precis-heartbeat.yml)
- [deploy/playbooks/19a-precis-embedder.yml](https://github.com/retospect/precis-mcp/blob/main/deploy/playbooks/19a-precis-precis-embedder.yml)
- [deploy/roles/precis_worker/tasks/main.yml](https://github.com/retospect/precis-mcp/blob/main/deploy/roles/precis_worker/tasks/main.yml)
- [README.md](https://github.com/retospect/precis-mcp/blob/main/README.md)
- [src/precis/handlers/ref_handler.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/ref_handler.py)
- [src/precis/handlers/markdown_handler.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/markdown_handler.py)
- [src/precis/handlers/plaintext_handler.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/plaintext_handler.py)
- [src/precis/handlers/todo_handler.py](https://github.com/retospect/precis-mcp/blob/main/src/precis/handlers/todo_handler.py)
</details>

# 部署、插件开发、Web UI 与运维

precis-mcp 是一个 MCP（Model Context Protocol）服务器，用于导航与编辑 DOCX、LaTeX、Markdown、纯文本以及 Todo 类文档。其工程化能力体现在三个维度：通过 Ansible Playbook 实现跨主机的标准化部署、通过 `RefHandler` 基类与新格式 Handler 实现可插拔的协议扩展、以及通过 worker/watch/heartbeat/embedder 角色实现日常运维自动化。

## 部署架构

部署由 `deploy/site.yml` 入口与若干 Playbook 协同完成。`site.yml` 是 Ansible 的总入口，按顺序拉起不同角色的主机；各角色（worker、watch、heartbeat、embedder）通过独立的 Playbook 进行声明式编排。 资料来源：[deploy/site.yml:1-30]()

```mermaid
flowchart LR
  Site[site.yml] --> Worker[20-precis-worker.yml]
  Site --> Embed[19a-precis-embedder.yml]
  Site --> Watch[28-precis-watch.yml]
  Site --> HB[40-precis-heartbeat.yml]
  Worker --> Tasks[roles/precis_worker/tasks/main.yml]
  Embed --> Tasks
  Watch --> Tasks
  HB --> Tasks
```

- **Worker 角色** (`20-precis-worker.yml`)：负责安装 precis-mcp 主体服务进程，监听 MCP 客户端连接。 资料来源：[deploy/playbooks/20-precis-worker.yml:1-40]()
- **Embedder 角色** (`19a-precis-embedder.yml`)：在 worker 之前编排，提供向量索引/嵌入相关的可选依赖（早期版本中使用以构建检索能力）。 资料来源：[deploy/playbooks/19a-precis-embedder.yml:1-30]()
- **Watch 角色** (`28-precis-watch.yml`)：监控文档目录变更并触发索引或缓存刷新。 资料来源：[deploy/playbooks/28-precis-watch.yml:1-30]()
- **Heartbeat 角色** (`40-precis-heartbeat.yml`)：周期性向监控端发送心跳，用于健康检查。 资料来源：[deploy/playbooks/40-precis-heartbeat.yml:1-25]()

`precis_worker` 角色通过 `tasks/main.yml` 抽象具体安装步骤（包安装、虚拟环境、systemd unit、配置模板渲染），保证各 Playbook 可复用同一执行逻辑。 资料来源：[deploy/roles/precis_worker/tasks/main.yml:1-50]()

## 插件（Handler）开发

v3.0.0 的重大架构变更之一是将 `PaperHandler` 中与"引用/URI 选择器"相关的核心逻辑抽取为 `RefHandler` 基类，使新格式 Handler 不必重复实现。 资料来源：[src/precis/handlers/ref_handler.py:1-60]()

注册新 Handler 的典型路径：

1. **继承基类**：新格式（如 Markdown、PlainText）Handler 继承 `RefHandler`，仅覆写与读写相关的最小接口。`MarkdownHandler`（`.md`、`.markdown`）与 `PlainTextHandler`（`.txt`、`.text`）均为零依赖实现，仅使用标准库。 资料来源：[src/precis/handlers/markdown_handler.py:1-30]() [src/precis/handlers/plaintext_handler.py:1-30]()
2. **声明 Scheme**：Todo 类内容走 `todo:` scheme，由 `TodoHandler` 借助 `acatome-store` 实现状态机语义（pending/in-progress/done），因此需要额外依赖。 资料来源：[src/precis/handlers/todo_handler.py:1-40]()
3. **URI 选择器**：v3.0.0 将分隔符由 `#` 改为 `~`，例如 `paper:slug~38` 或 `doc.docx~PLXDX`，避免与 Markdown 标题锚点冲突。 资料来源：[README.md:1-80]()

## Web UI

precis-mcp 主要面向 MCP 客户端（如编辑器、Agent 工具），并未自带独立的 Web 控制台。客户端通过 MCP 协议直接调用 `get/toc/put/search` 等工具完成导航与编辑。若需 Web 形式的人机界面，通常由前端调用 MCP Server 暴露的 JSON-RPC 端点自行实现——这是该项目刻意保持的"瘦客户端"边界。 资料来源：[README.md:80-140]()

## 运维与可观测性

日常运维由 watch/heartbeat 两类角色支撑：

- **Watch**：监听文档目录变更并触发下游 Handler 刷新，降低 MCP 客户端冷启动时的解析延迟。 资料来源：[deploy/playbooks/28-precis-watch.yml:10-25]()
- **Heartbeat**：周期性上报存活状态，便于在多实例部署中识别僵尸进程。 资料来源：[deploy/playbooks/40-precis-heartbeat.yml:10-20]()

此外，引用系统通过 `[@slug]` 形式的稳定 slug 标识条目，运维在迁移/重命名文档时可借助 `put()` 的 `slug` 字段保持引用连续性。 资料来源：[README.md:140-200]()

| 角色 | 触发方式 | 主要职责 |
| --- | --- | --- |
| worker | Ansible 一次性部署 | 安装与启动 MCP 服务 |
| watch | 文件系统事件 / cron | 文档变更感知与缓存刷新 |
| heartbeat | 定时任务 | 健康探针 |
| embedder | 一次性部署 | 可选嵌入/索引初始化 |

---

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

---

## Doramagic 踩坑日志

项目：retospect/precis-mcp

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

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

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

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

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

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

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

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

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

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

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

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

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

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

<!-- canonical_name: retospect/precis-mcp; human_manual_source: deepwiki_human_wiki -->