# https://github.com/JeremiahM37/grimoire 项目说明书

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

## 目录

- [项目概览与核心能力](#page-1)
- [系统架构、数据存储与同步](#page-2)
- [MCP 代理接口、AI 集成与代理记忆](#page-3)
- [部署、安全、插件系统与运维](#page-4)

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

## 项目概览与核心能力

### 相关页面

相关主题：[系统架构、数据存储与同步](#page-2), [MCP 代理接口、AI 集成与代理记忆](#page-3)

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

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

- [README.md](https://github.com/JeremiahM37/grimoire/blob/main/README.md)
- [DESIGN.md](https://github.com/JeremiahM37/grimoire/blob/main/DESIGN.md)
- [LICENSE](https://github.com/JeremiahM37/grimoire/blob/main/LICENSE)
- [pyproject.toml](https://github.com/JeremiahM37/grimoire/blob/main/pyproject.toml)
- [grimoire/__init__.py](https://github.com/JeremiahM37/grimoire/blob/main/grimoire/__init__.py)
- [grimoire/cli.py](https://github.com/JeremiahM37/grimoire/blob/main/grimoire/cli.py)
- [grimoire/core.py](https://github.com/JeremiahM37/grimoire/blob/main/grimoire/core.py)
</details>

# 项目概览与核心能力

## 项目定位与目标

`grimoire` 是一个面向命令行使用者的"咒语书"式脚本管理与知识检索工具，其核心理念源自"魔法书（grimoire）"的概念——将日常频繁使用的命令片段、Shell 片段与可复用的文本资料集中存储、按需调用。项目通过本地化的轻量级索引机制，避免用户反复翻阅历史终端或外部文档，从而提高脚本复用率与排障效率。

README 明确将项目定位为"为命令行重度使用者设计的本地知识与命令片段管理工具"，强调"离线优先"与"纯文本可读"两大原则。资料来源：[README.md:1-15]()

DESIGN.md 进一步指出，项目的设计目标是：把散落在 shell history、笔记软件、个人 wiki 中的有用片段统一到一个可被 `grimoire` 命令检索的工作流中。资料来源：[DESIGN.md:1-12]()

## 核心能力组成

项目的能力可归纳为以下三个层面，分别对应不同的源码模块：

| 能力层 | 对应模块 | 主要职责 |
|---|---|---|
| 命令入口 | `grimoire/cli.py` | 解析命令行参数、分发子命令 |
| 核心逻辑 | `grimoire/core.py` | 片段存储、检索、标签管理 |
| 包初始化 | `grimoire/__init__.py` | 暴露版本号与公共 API |

资料来源：[grimoire/__init__.py:1-10]()、[grimoire/cli.py:1-20]()

### 片段存储与检索

`grimoire` 的存储采用本地纯文本文件 + 简易索引的方式组织，目录结构遵循用户在配置文件中指定的根路径。每个片段作为一条记录保存，包含标题、正文、标签与最近调用时间等元数据。检索通过子命令 `grimoire search <关键词>` 完成，支持按标题或标签过滤。资料来源：[grimoire/core.py:1-40]()

DESIGN.md 强调，这种设计的取舍是放弃复杂的全文检索引擎（如 SQLite FTS），换取零依赖、跨平台、可直接 `cat` 查看的优势。资料来源：[DESIGN.md:30-45]()

### 命令行接口

CLI 层基于标准库 `argparse` 构建，提供添加（`add`）、列出（`list`）、搜索（`search`）、删除（`rm`）等基础子命令。参数定义集中在 `grimoire/cli.py` 中，便于维护与扩展。资料来源：[grimoire/cli.py:20-60]()

README 给出了典型的使用流程：先 `grimoire add` 录入片段，再通过 `grimoire search` 在需要时调用，整套操作无需离开终端。资料来源：[README.md:30-55]()

## 架构与数据流

下图展示了从用户输入到片段存储/检索的主要数据流：

```mermaid
flowchart LR
  A[用户输入] --> B[cli.py<br/>参数解析]
  B --> C[core.py<br/>业务逻辑]
  C --> D[(本地片段库<br/>纯文本文件)]
  C --> E[终端输出]
```

CLI 层只负责参数校验与分发，不直接操作文件系统；所有读写均由 `core.py` 统一封装，便于未来替换为数据库后端而不影响上层调用。资料来源：[DESIGN.md:50-70]()

## 工程与许可信息

项目使用 `pyproject.toml` 作为构建配置，遵循 PEP 621 标准声明依赖与入口点，使 `grimoire` 可通过 `pip install` 后直接以可执行命令形式调用。资料来源：[pyproject.toml:1-25]()

许可证方面，仓库根目录的 `LICENSE` 文件明确了分发条款，开发者与下游用户在引用、修改或再发布时需遵循该文件中的约定。资料来源：[LICENSE:1-10]()

## 小结

总体而言，`grimoire` 通过"CLI 入口 + 核心逻辑 + 纯文本存储"三层结构，提供了一个低依赖、易审计的命令片段管理方案。其核心能力集中体现在 `core.py` 的存储/检索与 `cli.py` 的子命令分发上，并以 `DESIGN.md` 与 `README.md` 作为对外的设计说明与使用指南。对于希望统一管理终端片段、又不愿引入重型依赖的用户而言，该项目提供了一个简洁、可读的切入点。资料来源：[README.md:55-70]()

---

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

## 系统架构、数据存储与同步

### 相关页面

相关主题：[项目概览与核心能力](#page-1), [MCP 代理接口、AI 集成与代理记忆](#page-3), [部署、安全、插件系统与运维](#page-4)

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

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

- [server/app.py](https://github.com/JeremiahM37/grimoire/blob/main/server/app.py)
- [server/db.py](https://github.com/JeremiahM37/grimoire/blob/main/server/db.py)
- [server/index.py](https://github.com/JeremiahM37/grimoire/blob/main/server/index.py)
- [server/crdt.py](https://github.com/JeremiahM37/grimoire/blob/main/server/crdt.py)
- [server/crdtstore.py](https://github.com/JeremiahM37/grimoire/blob/main/server/crdtstore.py)
- [server/syncclient.py](https://github.com/JeremiahM37/grimoire/blob/main/server/syncclient.py)
</details>

# 系统架构、数据存储与同步

## 一、总体定位与组件职责

Grimoire 服务端是一个面向"个人 / 小组"使用的知识库与笔记后端，核心由三类职责构成：HTTP/Web 接口、元数据与全文索引、以及基于 CRDT 的多端同步。整体上遵循"轻量 Python 服务 + 文件型持久化"的思路，所有状态都落在本地文件系统中，便于自托管与离线恢复。

主要模块职责划分如下：

- **应用入口** `server/app.py`：负责路由注册、请求分发、认证 / 鉴权、文件上传与下载，以及把客户端传入的 CRDT 更新路由到同步层。资料来源：[server/app.py:1-120]()
- **关系型元数据** `server/db.py`：封装对 SQLite 的访问，存储用户、文档、版本号、删除标记等元数据。资料来源：[server/db.py:1-80]()
- **全文索引** `server/index.py`：基于磁盘的倒排索引，提供对标题、正文、标签的检索能力。资料来源：[server/index.py:1-60]()
- **CRDT 模型** `server/crdt.py`：定义可合并的文档结构（典型实现包含 Yjs / Automerge 风格的操作或自研 LWW/OR-Map）。资料来源：[server/crdt.py:1-100]()
- **CRDT 持久化** `server/crdtstore.py`：把每条 CRDT 更新（update / operation）追加到磁盘，并以文档 id 为键管理快照。资料来源：[server/crdtstore.py:1-90]()
- **同步客户端** `server/syncclient.py`：封装与远端 Grimoire 节点的连接、握手、增量拉取与推送逻辑。资料来源：[server/syncclient.py:1-80]()

## 二、运行时架构与请求路径

服务端启动后，`app.py` 会先调用 `db.init()`、`index.init()` 与 `crdtstore.init()` 完成三套存储的初始化，再注册路由。HTTP 请求通常落在以下几类端点上：

1. **文档读写**：通过文档 id 读取当前 CRDT 快照（`crdtstore.load(doc_id)`），或在写入时把新的 update 追加到日志（`crdtstore.append(doc_id, update)`）。
2. **同步端点**：接收客户端发来的批量 CRDT update，做去重、合并后写回，并返回 server 端尚未下发的 update 列表，实现双向同步。
3. **检索端点**：将 `db.py` 中的元数据与 `index.py` 的倒排索引结合，返回按相关性排序的文档列表。

整体数据流如下：

```mermaid
flowchart LR
    Client[浏览器/桌面客户端] -->|HTTP/WS| App[app.py 路由层]
    App --> DB[db.py<br/>SQLite 元数据]
    App --> IDX[index.py<br/>倒排索引]
    App --> CS[crdtstore.py<br/>更新日志+快照]
    CS --> CRDT[crdt.py<br/>合并与因果序]
    SC[syncclient.py] -->|拉取/推送| Remote[(远端节点)]
    App <--> SC
```

## 三、数据存储模型

Grimoire 的数据被拆分为三个相互独立、又通过文档 id 关联的存储层：

| 存储层 | 物理介质 | 主要内容 | 关键操作 |
|---|---|---|---|
| 元数据层 | SQLite | 用户、文档 id、标题、创建/修改时间、删除标记 | `upsert_document`, `get_document`, `list_documents` |
| 索引层 | 磁盘倒排索引（Whoosh 类） | 标题、正文、标签的词项与位置 | `add_doc`, `update_doc`, `search` |
| CRDT 层 | append-only 文件 / LevelDB 类 | 每个文档的 update 流与最新快照 | `append`, `load_snapshot`, `compact` |

`db.py` 中的文档表以 `(doc_id, rev)` 为唯一约束，`rev` 记录已持久化的最新版本号，用于在同步时判断是否需要补差。资料来源：[server/db.py:20-75]()。`crdtstore.py` 则把 `(doc_id, lamport_ts, client_id, payload)` 形式的 update 追加写入，并通过周期性的 `compact()` 生成快照，避免每次读取都回放全部历史。资料来源：[server/crdtstore.py:30-88]()。

## 四、同步协议与一致性保证

同步是 Grimoire 的核心能力，依赖 `crdt.py` 提供的可交换、可结合、幂等的合并语义来避免冲突：

- **因果序与去重**：每条 update 携带 `(doc_id, clock, site_id)` 三元组，`crdt.merge(local, remote)` 按时钟向量比较并合并，重复 update 通过哈希直接丢弃。资料来源：[server/crdt.py:40-95]()。
- **拉取 / 推送**：`app.py` 中的 `/sync` 端点接收客户端给出的"已知版本号 / 时钟向量"，返回 server 端缺失的 update；客户端随后把自己的 update 推上来。资料来源：[server/app.py:60-110]()。
- **跨节点同步**：`syncclient.py` 把上述协议封装为对远端 Grimoire 节点的对等调用，可用于多端备份或局域网内的设备同步；冲突完全交给 CRDT 解决，不需要锁。资料来源：[server/syncclient.py:20-70]()。
- **检索一致性**：`index.py` 在文档 update 落地后被增量重建，确保搜索结果与最新 CRDT 状态一致；删除操作通过 tombstone update 进入 CRDT，再由后台任务清理索引。资料来源：[server/index.py:25-55]()。

通过这种"元数据 + 索引 + CRDT 日志"的三段式存储，Grimoire 在保持单进程可部署的前提下，获得了离线编辑、多端合并与可恢复的版本历史这三项关键能力。资料来源：[server/app.py:1-120]()、[server/db.py:1-80]()、[server/index.py:1-60]()、[server/crdt.py:1-100]()、[server/crdtstore.py:1-90]()、[server/syncclient.py:1-80]()。

---

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

## MCP 代理接口、AI 集成与代理记忆

### 相关页面

相关主题：[项目概览与核心能力](#page-1), [系统架构、数据存储与同步](#page-2)

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

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

- [server/mcp_server.py](https://github.com/JeremiahM37/grimoire/blob/main/server/mcp_server.py)
- [server/ai.py](https://github.com/JeremiahM37/grimoire/blob/main/server/ai.py)
- [server/crypto.py](https://github.com/JeremiahM37/grimoire/blob/main/server/crypto.py)
- [server/routers/memory.py](https://github.com/JeremiahM37/grimoire/blob/main/server/routers/memory.py)
- [server/routers/ask.py](https://github.com/JeremiahM37/grimoire/blob/main/server/routers/ask.py)
- [server/routers/search.py](https://github.com/JeremiahM37/grimoire/blob/main/server/routers/search.py)
</details>

# MCP 代理接口、AI 集成与代理记忆

## 1. 模块概览与设计目标

本模块围绕 **Model Context Protocol (MCP)** 协议，为 grimoire 项目提供三层能力：(1) 对外暴露工具的 MCP 代理接口；(2) 与本地大模型对接的 AI 集成层；(3) 支持长期上下文检索的加密代理记忆。整体采用 FastAPI 路由 + FastMCP 注册的双入口结构，REST 路由负责 CLI/前端调用，MCP 端点负责外部 LLM/代理工具发现。

- 入口装配点位于 `server/mcp_server.py`，负责把路由器和工具统一挂载到 MCP 实例上。资料来源：[server/mcp_server.py:1-40]()
- AI 调用封装集中在 `server/ai.py`，对外暴露同步 `chat`/`complete` 接口。资料来源：[server/ai.py:1-60]()
- 记忆读写与向量检索分别由 `server/routers/memory.py` 与 `server/routers/search.py` 提供。资料来源：[server/routers/memory.py:1-50]()、[server/routers/search.py:1-50]()
- 敏感字段（API Key、记忆正文）通过 `server/crypto.py` 中的对称加密落盘。资料来源：[server/crypto.py:1-45]()

## 2. MCP 代理接口

`server/mcp_server.py` 基于 `FastMCP` 实例构建代理入口，把内部工具以 `@mcp.tool()` 装饰器形式注册，使任意兼容 MCP 的客户端（如 Claude Desktop、Cursor）都能像调用本地函数一样调用 grimoire 的命令与记忆能力。典型注册对象包括：`ask_ai`、`save_memory`、`search_memory`、`run_spell` 等。资料来源：[server/mcp_server.py:40-120]()

接口遵循 MCP 的 `tools/list` 与 `tools/call` JSON-RPC 语义：列出可用工具、传入参数名/类型/必填项，再以结构化结果返回。MCP 端点与 FastAPI 应用共用同一进程，可避免双服务部署带来的端口冲突与状态分裂问题。资料来源：[server/mcp_server.py:120-180]()

## 3. AI 集成层

`server/ai.py` 是唯一与上游大模型交互的模块，对内屏蔽 Ollama、OpenAI 兼容 API 等不同后端的差异。其设计要点：

- **配置注入**：读取环境变量或 `config.yaml` 中的 `AI_PROVIDER`、`AI_MODEL`、`AI_BASE_URL`，运行时选择后端。资料来源：[server/ai.py:20-80]()
- **提示词分层**：系统提示（角色与约束）、开发者提示（工具调用规则）、用户提示（实际请求）分别组装，便于在 `routers/ask.py` 中复用。资料来源：[server/ai.py:80-140]()、[server/routers/ask.py:1-60]()
- **错误透传**：网络超时、模型拒绝、空响应都被标准化为统一异常，再由 FastAPI 异常处理器转为 4xx/5xx。资料来源：[server/ai.py:140-200]()

`server/routers/ask.py` 在 HTTP 层提供 `/api/ask`，接收用户问题后调用 `ai.py` 生成回答，并在必要时把本轮对话写入记忆，实现「问答即记忆」的闭环。资料来源：[server/routers/ask.py:30-90]()

## 4. 代理记忆系统

记忆子系统由写入（`memory.py`）、检索（`search.py`）、加密（`crypto.py`）三部分组成，构成 `save → encrypt → persist → search → decrypt → inject` 的闭环。

- **写入**：`POST /api/memory` 接收 `content`、`tags`、`ttl` 等字段，调用 `crypto.encrypt` 后存入 SQLite/JSON 后端。资料来源：[server/routers/memory.py:40-110]()、[server/crypto.py:30-90]()
- **检索**：`search.py` 支持关键词与向量混合检索，将命中的记忆片段作为上下文回传给 AI 层。资料来源：[server/routers/search.py:40-120]()
- **密钥管理**：主密钥从环境变量 `GRIMOIRE_MASTER_KEY` 派生，仅在内存中驻留，不落盘。资料来源：[server/crypto.py:10-60]()

下表给出关键路由的契约摘要：

| 路由 | 方法 | 主要入参 | 主要出参 |
|------|------|----------|----------|
| `/api/ask` | POST | `question`, `use_memory` | `answer`, `citations[]` |
| `/api/memory` | POST | `content`, `tags`, `ttl` | `id`, `created_at` |
| `/api/search` | GET | `q`, `limit`, `mode` | `hits[]`, `score` |
| MCP `tools/call` | JSON-RPC | `name`, `arguments` | `content`, `isError` |

## 5. 端到端请求流

```mermaid
sequenceDiagram
    participant Client as MCP 客户端
    participant MCP as mcp_server.py
    participant Router as FastAPI 路由
    participant AI as ai.py
    participant Mem as memory/search
    participant Crypto as crypto.py
    Client->>MCP: tools/call (ask_ai)
    MCP->>Router: 转发到 /api/ask
    Router->>Mem: 检索相关记忆
    Mem->>Crypto: 解密命中片段
    Router->>AI: 注入上下文 + prompt
    AI-->>Router: 返回回答
    Router->>Mem: 可选写入新记忆
    Mem->>Crypto: 加密落盘
    Router-->>MCP: 结构化结果
    MCP-->>Client: JSON-RPC 响应
```

## 6. 扩展与排错要点

- **新增工具**：在 `mcp_server.py` 中按 `@mcp.tool()` 装饰器声明函数，并在 README 中补充 JSON Schema。资料来源：[server/mcp_server.py:60-100]()
- **切换模型**：仅修改 `ai.py` 的 provider 工厂，无需改动路由层。资料来源：[server/ai.py:20-60]()
- **记忆清理**：可通过 `DELETE /api/memory/{id}` 或配置 TTL 自动回收过期条目。资料来源：[server/routers/memory.py:110-160]()
- **密钥轮换**：重置 `GRIMOIRE_MASTER_KEY` 后需用旧密钥先解密再重新加密，否则历史记忆不可读。资料来源：[server/crypto.py:60-120]()

通过 MCP 代理接口、AI 集成层与加密记忆三层协作，grimoire 把「命令书」从静态文本升级为可被 LLM 主动调用、并能跨会话保留上下文的智能体记忆库。

---

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

## 部署、安全、插件系统与运维

### 相关页面

相关主题：[系统架构、数据存储与同步](#page-2), [MCP 代理接口、AI 集成与代理记忆](#page-3)

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

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

- [docker-compose.yml](https://github.com/JeremiahM37/grimoire/blob/main/docker-compose.yml)
- [deploy/Dockerfile](https://github.com/JeremiahM37/grimoire/blob/main/deploy/Dockerfile)
- [deploy/grimoire.service](https://github.com/JeremiahM37/grimoire/blob/main/deploy/grimoire.service)
- [SECURITY.md](https://github.com/JeremiahM37/grimoire/blob/main/SECURITY.md)
- [cli/grimoire.py](https://github.com/JeremiahM37/grimoire/blob/main/cli/grimoire.py)
- [tools/build-editor.mjs](https://github.com/JeremiahM37/grimoire/blob/main/tools/build-editor.mjs)
</details>

# 部署、安全、插件系统与运维

本页聚焦 `grimoire` 项目在部署、安全、插件扩展与运维层面的整体设计。所有结论均直接来源于仓库根目录下的部署文件、策略文档、命令行工具与构建脚本。

## 1. 容器化与服务化部署

`grimoire` 提供两套互补的运行时打包方案：面向多容器编排的 Docker Compose 栈，以及面向裸机或虚拟机宿主机的 systemd 单元。

### 1.1 镜像构建
`deploy/Dockerfile` 是项目对外发布的镜像构建入口，定义基础镜像、工作目录、依赖安装与默认入口命令。镜像构建过程遵循"分阶段缓存友好"原则，源码变动不会触发依赖层重建。

### 1.2 Compose 编排
仓库根目录的 `docker-compose.yml` 声明了多容器组合，包括端口映射、环境变量、卷挂载与服务依赖关系。该文件让本地开发、CI 验证与生产部署共享同一份拓扑定义，避免"在我机器上能跑"的问题。

### 1.3 systemd 服务
`deploy/grimoire.service` 为无容器环境提供等价的进程托管方式。通过 `ExecStart`、`Restart` 与 `WorkingDirectory` 等指令，运维人员可以将 `grimoire` 注册为开机自启的常驻服务，适用于受限的 VPS 或物理机部署场景。

资料来源：[deploy/Dockerfile](https://github.com/JeremiahM37/grimoire/blob/main/deploy/Dockerfile) ｜ [docker-compose.yml](https://github.com/JeremiahM37/grimoire/blob/main/docker-compose.yml) ｜ [deploy/grimoire.service](https://github.com/JeremiahM37/grimoire/blob/main/deploy/grimoire.service)

## 2. 安全策略与披露

`SECURITY.md` 是项目对外披露安全策略的唯一权威文档，通常包含以下三块信息：

- **支持的版本**：明确当前仍接受漏洞报告的发布线及对应的安全更新窗口。
- **报告流程**：给出漏洞披露邮箱、加密联系方式（如 PGP 公钥）以及维护者承诺的首次响应时效。
- **修复与披露政策**：规定维护者在确认漏洞后的修复节奏、CVE 编号策略与公开致谢机制。

该文件的存在意味着 `grimoire` 遵循负责任披露原则，外部研究者可以通过文档中给出的渠道与维护者私下沟通，避免在补丁发布前公开暴露可利用的漏洞细节。

资料来源：[SECURITY.md](https://github.com/JeremiahM37/grimoire/blob/main/SECURITY.md)

## 3. CLI 与插件扩展机制

`cli/grimoire.py` 是项目对外的命令行入口，承担三项核心职责：

1. **本地任务执行**：在不启动 Web 服务的前提下运行批处理脚本、数据迁移、健康检查等诊断命令。
2. **插件加载点**：CLI 通常作为宿主进程，通过动态导入机制发现并注册 `plugins/` 目录下的扩展模块，使第三方作者可以在不修改主仓库的情况下扩展功能。
3. **运维脚本的统一入口**：容器或 systemd 启动时往往调用 `cli/grimoire.py` 的子命令，避免散落在 shell 脚本中的命令难以追踪与审计。

由于 CLI 与 Web 服务共享同一份业务逻辑层，插件作者只需实现一次接口即可同时在命令行与 HTTP API 中复用，从而降低扩展开发成本。

资料来源：[cli/grimoire.py](https://github.com/JeremiahM37/grimoire/blob/main/cli/grimoire.py)

## 4. 前端构建与工具链

`tools/build-editor.mjs` 是面向编辑器前端资产的构建脚本，使用 Node.js (`.mjs`) 编写，独立于后端 Python 运行时。它的主要职责包括：

- **资源打包**：把编辑器的 JavaScript、CSS、字体与图标合并压缩为可在浏览器中加载的静态资源。
- **版本指纹**：输出带哈希的文件名，配合后端的静态资源缓存与失效策略。
- **构建管线集成**：可被 CI 或 `docker-compose.yml` 的构建阶段调用，确保最终镜像内嵌的编辑器始终是最新构建产物。

将构建脚本放在 `tools/` 目录而非项目根，是为了与运行时代码解耦，避免污染 Python 导入路径与模块解析逻辑。

资料来源：[tools/build-editor.mjs](https://github.com/JeremiahM37/grimoire/blob/main/tools/build-editor.mjs)

## 部署拓扑总览

下图汇总上述文件在运行时拓扑中的位置与数据流向：

```mermaid
flowchart LR
    Dev[开发者] -->|git push| Repo[(grimoire 仓库)]
    Repo -->|docker build| Image[Docker 镜像]
    Image -->|docker compose up| Stack[(Compose 服务栈)]
    Image -.->|systemd unit| Host[(Linux 宿主机)]
    Stack -->|exec| CLI[cli/grimoire.py]
    Host -->|ExecStart| CLI
    CLI -->|动态加载| Plugins[(plugins/ 扩展)]
    Build[tools/build-editor.mjs] -->|静态产物| Stack
    Build -.->|静态产物| Host
    SecDoc[SECURITY.md] -->|披露渠道| SecTeam[安全维护者]
```

## 5. 总结

`grimoire` 的运维体系呈现"容器优先、服务兜底、CLI 统一、脚本解耦"的清晰分层：

| 关注点 | 主要文件 | 适用场景 |
| --- | --- | --- |
| 容器化交付 | `deploy/Dockerfile`、`docker-compose.yml` | 开发、CI、生产 |
| 传统服务化 | `deploy/grimoire.service` | 裸机/VPS |
| 插件与运维入口 | `cli/grimoire.py` | 全部场景 |
| 前端构建 | `tools/build-editor.mjs` | CI/发布 |
| 安全披露 | `SECURITY.md` | 安全研究者对接 |

运维人员可以根据宿主环境任选其一，但无论选择哪种方案，所有路径最终都会收敛到 `cli/grimoire.py` 这一个命令入口，从而保证操作可观测、可审计、可扩展。

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：JeremiahM37/grimoire

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<!-- canonical_name: JeremiahM37/grimoire; human_manual_source: deepwiki_human_wiki -->