# https://github.com/the-long-ride/engram 项目说明书
生成时间：2026-07-14 10:36:23 UTC
## 目录
- [项目概览](#page-overview)
- [Src 模块](#page-website-src)
- [Runtime 模块](#page-src-core-runtime)
- [App 模块](#page-src-core-web-app)
## 项目概览
### 相关页面
相关主题：[Src 模块](#page-website-src)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/the-long-ride/engram/blob/main/README.md)
- [documentation/README.md](https://github.com/the-long-ride/engram/blob/main/documentation/README.md)
- [package.json](https://github.com/the-long-ride/engram/blob/main/package.json)
- [website/README.md](https://github.com/the-long-ride/engram/blob/main/website/README.md)
- [website/package.json](https://github.com/the-long-ride/engram/blob/main/website/package.json)
- [website/pnpm-workspace.yaml](https://github.com/the-long-ride/engram/blob/main/website/pnpm-workspace.yaml)
# 项目概览
## 项目定位与目标
`engram` 是一个以 npm 包 `@the-long-ride/engram` 形式发布的开源项目，仓库由 `the-long-ride` 组织维护。其设计目标是提供一套独立的、可通过包管理器消费的库/工具，便于开发者在自己的项目中直接引用，无需从源码重新构建。资料来源：[package.json:1-40]()
项目的根目录结构同时包含了主包源码与文档站点（位于 `website/` 子目录），这表明该项目采用 monorepo（多包仓库）模式进行管理与发布。资料来源：[website/pnpm-workspace.yaml:1-20]()
最新公开版本为 `v0.0.27`，CHANGELOG 中记录了对应版本的变更细节。该版本号（0.0.x）目前仍处于早期迭代阶段，意味着 API 与功能集可能在后续版本中出现较大调整。资料来源：[CHANGELOG.md:1-30]()
## 仓库整体结构
仓库根目录下设有两个并列的功能区：根目录的 `package.json` 定义了对外发布的主包；`documentation/` 目录保存面向开发者的原始文档资料；`website/` 子目录则承载文档站点的构建产物与配置。
| 路径 | 角色 | 说明 |
| --- | --- | --- |
| `/` | 主包根目录 | 通过根 `package.json` 定义 npm 包元数据 |
| `/documentation` | 文档源 | 作为站点内容的源头文件 |
| `/website` | 文档站点工作区 | 由 pnpm workspace 管理，独立的 `package.json` |
| `/website/pnpm-workspace.yaml` | 工作区配置 | 声明当前目录作为 workspace 根 |
资料来源：[website/pnpm-workspace.yaml:1-15]()、[website/package.json:1-40]()
`website/` 子目录自带一份 `pnpm-workspace.yaml`，意味着该子目录本身就是一个 pnpm workspace 根，用于聚合站点内部多个子包（例如站点框架、主题、构建工具等）的依赖与脚本。这种"嵌套 workspace"结构是该项目架构上较为突出的特征。资料来源：[website/pnpm-workspace.yaml:1-20]()
## 文档体系
项目的文档分为两层组织：原始内容存放于 `documentation/README.md`，作为信息源；最终面向用户的渲染站点则由 `website/` 子目录下的工具链构建并发布。资料来源：[documentation/README.md:1-30]()
`website/README.md` 描述了站点的本地开发、构建与部署流程，是贡献者进入文档体系的入口文件。其推荐使用 pnpm 进行依赖管理，与 workspace 配置保持一致。资料来源：[website/README.md:1-40]()
这一"双层文档"模式的好处在于：原始文档以纯文本/Markdown 形式存在，便于阅读与版本控制；站点层提供搜索、导航与样式，两者职责清晰分离。资料来源：[documentation/README.md:1-30]()
## 发布与版本管理
作为 npm 包，`engram` 的发布通过根目录的 `package.json` 中定义的 `name`、`version`、`files` 等字段完成。`v0.0.27` 是当前社区可见的最新版本，对应变更记录可于项目根目录的 `CHANGELOG.md` 中查阅。资料来源：[package.json:1-40]()、[CHANGELOG.md:1-30]()
社区反馈（参见 Issue #9）显示，目前已有用户就项目本身提出私下的咨询与协作意向，说明项目正在吸引早期使用者的关注。这类一对一沟通反映了早期阶段项目的典型交互方式——核心维护者会优先通过直接渠道与潜在贡献者对齐方向。资料来源：[Issue #9]()
## 工作流简述
```mermaid
flowchart LR
A[documentation/
README.md 源文档] --> B[website/
站点构建]
B --> C[渲染后的
文档站点]
D[根 package.json
主包定义] --> E[npm @the-long-ride/engram]
F[website/pnpm-workspace.yaml] --> B
F --> G[website 子包依赖]
```
上图展示了内容从源文档到对外站点的流转：根 `package.json` 定义并发布主 npm 包；`documentation/` 保存源内容；`website/` 在 pnpm workspace 的协调下完成站点构建并对外提供文档。资料来源：[website/pnpm-workspace.yaml:1-15]()、[package.json:1-40]()
## 小结
- 项目采用 monorepo 架构，主包与文档站点并列管理。资料来源：[website/pnpm-workspace.yaml:1-15]()
- npm 包名为 `@the-long-ride/engram`，当前发布版本 `v0.0.27`。资料来源：[package.json:1-40]()、[CHANGELOG.md:1-30]()
- 文档体系以 `documentation/README.md` 为源，由 `website/` 构建为最终站点。资料来源：[documentation/README.md:1-30]()、[website/README.md:1-40]()
- 项目尚处早期迭代阶段（0.0.x），API 与功能可能在后续版本演进。资料来源：[CHANGELOG.md:1-30]()
如需深入了解具体的安装方式、API 用法或站点构建命令，请参阅 [`README.md`](https://github.com/the-long-ride/engram/blob/main/README.md) 与 [`website/README.md`](https://github.com/the-long-ride/engram/blob/main/website/README.md) 的进一步内容。
---
## Src 模块
### 相关页面
相关主题：[项目概览](#page-overview), [Runtime 模块](#page-src-core-runtime)
相关源码文件
以下源码文件用于生成本页说明：
- [website/src/components/DocPageCopyButton.test.tsx](https://github.com/the-long-ride/engram/blob/main/website/src/components/DocPageCopyButton.test.tsx)
- [website/src/components/DocPageCopyButton.tsx](https://github.com/the-long-ride/engram/blob/main/website/src/components/DocPageCopyButton.tsx)
- [website/src/components/DocPageCopyNavbarItem.test.tsx](https://github.com/the-long-ride/engram/blob/main/website/src/components/DocPageCopyNavbarItem.test.tsx)
- [website/src/components/DocPageCopyNavbarItemView.tsx](https://github.com/the-long-ride/engram/blob/main/website/src/components/DocPageCopyNavbarItemView.tsx)
- [website/src/components/EntryFieldCard.tsx](https://github.com/the-long-ride/engram/blob/main/website/src/components/EntryFieldCard.tsx)
- [website/src/components/EntryFieldTable.tsx](https://github.com/the-long-ride/engram/blob/main/website/src/components/EntryFieldTable.tsx)
# Src 模块
`Src` 模块指 engram 项目文档站点的前端源码根目录 `website/src`，它是基于 [Docusaurus](https://docusaurus.io/) 文档站点的 React 组件、视图与单元测试的集合。该目录下的代码**不**进入 npm 包 `@the-long-ride/engram` 的运行时产物，只服务于文档站 `website/` 的渲染、交互与可测试性。
## 1. 模块定位与目录角色
engram 仓库被切分为两个相互独立的发布域：作为库的 `@the-long-ride/engram`（参见 npm 包页）与作为站点的 `website/`。在 `website/` 内，`Src` 子模块（即 `website/src`）承担了"Markdown/MDX 之外、可被多页面复用的 UI 原子"。社区上下文里反复出现关于仓库布局的咨询（参见 Issue #9），"Src 目录到底属于运行时还是文档" 是常见疑问，因此为该模块单独立档有利于减少后续同类问答。`资料来源：[website/src/components/DocPageCopyButton.tsx](https://github.com/the-long-ride/engram/blob/main/website/src/components/DocPageCopyButton.tsx)`
### 1.1 命名与组织约定
`Src` 模块下的组件统一放置在 `website/src/components/`，文件名遵循 PascalCase 的 React 组件惯例，且为每个对外暴露的组件都附带一份同名 `*.test.tsx` 单元测试。`资料来源：[website/src/components/DocPageCopyButton.test.tsx](https://github.com/the-long-ride/engram/blob/main/website/src/components/DocPageCopyButton.test.tsx)`
## 2. 文档页面复制组件族
围绕"复制当前文档"这一高频需求，`Src` 模块把入口拆成了两个相互呼应的 React 节点：
### 2.1 文档页内悬浮按钮
`DocPageCopyButton.tsx` 在文档正文右下角提供一个悬浮按钮；其配套测试 `DocPageCopyButton.test.tsx` 覆盖渲染、点击与回调触发等关键路径，确保按钮在不同的 Docusaurus 主题下都能稳定挂载。`资料来源：[website/src/components/DocPageCopyButton.test.tsx](https://github.com/the-long-ride/engram/blob/main/website/src/components/DocPageCopyButton.test.tsx)` `资料来源：[website/src/components/DocPageCopyButton.tsx](https://github.com/the-long-ride/engram/blob/main/website/src/components/DocPageCopyButton.tsx)`
### 2.2 顶栏 Navbar 项
`DocPageCopyNavbarItemView.tsx` 是顶栏 Navbar 槽位的"视图层实现"，通过 Docusaurus 的 `NavbarItem` 接口注入站点顶栏；其测试 `DocPageCopyNavbarItem.test.tsx` 校验项的可见性、激活态与渲染分支。`资料来源：[website/src/components/DocPageCopyNavbarItemView.tsx](https://github.com/the-long-ride/engram/blob/main/website/src/components/DocPageCopyNavbarItemView.tsx)` `资料来源：[website/src/components/DocPageCopyNavbarItem.test.tsx](https://github.com/the-long-ride/engram/blob/main/website/src/components/DocPageCopyNavbarItem.test.tsx)`
### 2.3 协作关系
```mermaid
graph TD
DocPage[文档页 DocPage] --> Button[DocPageCopyButton]
DocPage --> Card[EntryFieldCard]
DocPage --> Table[EntryFieldTable]
Navbar[顶栏 Navbar] --> Item[DocPageCopyNavbarItemView]
Item -.共享上下文/事件.-> Button
Button -.复制成功反馈.-> DocPage
```
> 关系图仅描述 `Src` 模块内组件与 Docusaurus 页面/顶栏之间的相对位置，不揭示具体的状态管理或事件总线实现细节。
## 3. 条目字段展示组件
针对 engram 所管理"记忆条目（Entry）"的字段可视化，`Src` 模块提供两种展示密度：
- `EntryFieldCard.tsx`：以"卡片"为粒度高亮单个字段，凸显字段名、类型与示例值，便于在叙事性文档中穿插解释。`资料来源：[website/src/components/EntryFieldCard.tsx](https://github.com/the-long-ride/engram/blob/main/website/src/components/EntryFieldCard.tsx)`
- `EntryFieldTable.tsx`：以"表格"为粒度聚合多个字段，适合字段对照、批量阅读或在 API 参考页中展示较长的字段列表。`资料来源：[website/src/components/EntryFieldTable.tsx](https://github.com/the-long-ride/engram/blob/main/website/src/components/EntryFieldTable.tsx)`
二者通常成对出现在"字段参考"类文档中，由 MDX 按需引入，从而避免在 Markdown 源文件中重复描述字段结构。
## 4. 测试、发布与社区关注点
每个对外暴露的 React 组件都配套有 `*.test.tsx` 单元测试，覆盖渲染、交互与激活态等关键路径。这套测试与 npm 包发布无关——站点本身不会被打包进 `@the-long-ride/engram`——但它能在 Docusaurus 与 React 大版本升级时拦截组件级回归。结合社区上下文中的 v0.0.27 发布链（参见 [CHANGELOG.md](https://github.com/the-long-ride/engram/blob/v0.0.27/CHANGELOG.md)），后续版本可能继续新增 `Entry*` 或 `DocPage*` 组件，读者在跟踪发行说明时应优先核对 `Src` 模块下的文件清单是否发生扩展。`资料来源：[website/src/components/EntryFieldCard.tsx](https://github.com/the-long-ride/engram/blob/main/website/src/components/EntryFieldCard.tsx)` `资料来源：[website/src/components/EntryFieldTable.tsx](https://github.com/the-long-ride/engram/blob/main/website/src/components/EntryFieldTable.tsx)`
### 4.1 模块边界
- `Src` 模块**不**包含 npm 包核心逻辑：库的运行时入口位于仓库根目录下的 `src/`，与 `website/src/` 是两个相互独立的命名空间，须明确区分。
- 当前 wiki 仅覆盖 `website/src/components/` 下可直接观测到的 6 个文件；若后续引入主题切换、国际化（i18n）或搜索高亮等组件，建议在本页追加新章节而非另起页面，以保持 `Src` 模块的单一入口，便于 Issue #9 这类"先看 wiki 再提问"的用户快速定位。
---
## Runtime 模块
### 相关页面
相关主题：[Src 模块](#page-website-src), [App 模块](#page-src-core-web-app)
相关源码文件
以下源码文件用于生成本页说明：
- [src/core/runtime/auto-upgrade.ts](https://github.com/the-long-ride/engram/blob/main/src/core/runtime/auto-upgrade.ts)
- [src/core/runtime/config.ts](https://github.com/the-long-ride/engram/blob/main/src/core/runtime/config.ts)
- [src/core/runtime/constants.ts](https://github.com/the-long-ride/engram/blob/main/src/core/runtime/constants.ts)
- [src/core/runtime/docs-site.ts](https://github.com/the-long-ride/engram/blob/main/src/core/runtime/docs-site.ts)
- [src/core/runtime/entry.ts](https://github.com/the-long-ride/engram/blob/main/src/core/runtime/entry.ts)
- [src/core/runtime/exit-codes.ts](https://github.com/the-long-ride/engram/blob/main/src/core/runtime/exit-codes.ts)
# Runtime 模块
`engram` 项目的 Runtime 模块位于 `src/core/runtime/` 目录下，是 CLI 与底层能力之间的运行时核心层。它负责进程入口、配置加载、常量管理、自我升级、文档站点装配以及统一退出码等横切关注点，使上层命令能够以一致的方式启动、配置与退出。该模块在 v0.0.27 版本中作为包内核心结构的一部分随 `@the-long-ride/engram` npm 包发布。资料来源：[src/core/runtime/entry.ts:1-1]()、资料来源：[CHANGELOG.md](https://github.com/the-long-ride/engram/blob/v0.0.27/CHANGELOG.md)
## 模块职责与边界
Runtime 模块并不直接实现业务命令，而是提供以下几类支撑能力：
- **入口装配**：作为命令执行的总入口，将 CLI 参数、配置与运行时环境装配到内存中。资料来源：[src/core/runtime/entry.ts:1-1]()
- **配置管理**：集中维护运行期可调节的设置项，便于不同子模块读取一致的配置。资料来源：[src/core/runtime/config.ts:1-1]()
- **常量定义**：以单一来源方式管理跨模块使用的字符串、数值与错误标识，避免魔法值散落。资料来源：[src/core/runtime/constants.ts:1-1]()
- **自我升级**：在 CLI 启动或命令执行过程中检测并应用新版本，实现版本自维护。资料来源：[src/core/runtime/auto-upgrade.ts:1-1]()
- **文档站点能力**：运行时内置对项目文档站点的装配与呈现，便于在终端或本地访问。资料来源：[src/core/runtime/docs-site.ts:1-1]()
- **退出码规范**：统一定义成功、失败、用户取消、升级失败等进程退出码，使脚本与 CI 可一致处理。资料来源：[src/core/runtime/exit-codes.ts:1-1]()
## 核心组件
### 入口与生命周期（entry / exit-codes）
`entry.ts` 作为运行时入口，负责初始化进程状态、加载配置并触发后续流水线。`exit-codes.ts` 将退出码抽象为枚举或常量集，进程在任何分支结束时都必须返回其中之一，避免使用裸数字导致调用方难以识别语义。两者共同构成了 Runtime 模块的「开始—结束」闭环。资料来源：[src/core/runtime/entry.ts:1-1]()、资料来源：[src/core/runtime/exit-codes.ts:1-1]()
### 配置与常量（config / constants）
`config.ts` 提供配置结构与默认值，使上层命令可通过统一的接口读取设置；`constants.ts` 则承载版本号、品牌名、错误前缀等跨模块复用的字面量。这种「配置 vs 常量」的拆分使可变项与不可变项各居其位，降低在升级与重构时的耦合。资料来源：[src/core/runtime/config.ts:1-1]()、资料来源：[src/core/runtime/constants.ts:1-1]()
### 自动升级与文档站点（auto-upgrade / docs-site）
`auto-upgrade.ts` 在运行时检查远端版本并触发升级流程，确保用户始终使用较新的发布版本；`docs-site.ts` 则在运行期暴露文档站点的入口或本地化资源，使 CLI 自身即可作为查阅文档的入口。这两个模块体现了 Runtime 在「自我维护」与「自带文档」上的设计取向。资料来源：[src/core/runtime/auto-upgrade.ts:1-1]()、资料来源：[src/core/runtime/docs-site.ts:1-1]()
## 运行时数据流
下图描述了从 CLI 调用进入到退出码返回期间，Runtime 模块各组件的协作关系：
```mermaid
flowchart LR
A[CLI 调用] --> B[entry.ts]
B --> C[config.ts]
B --> D[constants.ts]
B --> E[auto-upgrade.ts]
B --> F[docs-site.ts]
C --> G[上层命令执行]
D --> G
E --> G
F --> G
G --> H[exit-codes.ts]
H --> I[进程退出]
```
入口先于业务命令完成装配，业务命令在执行过程中按需读取配置与常量；自动升级与文档站点作为横向能力被命令调用；最终所有路径汇入统一的退出码层。资料来源：[src/core/runtime/entry.ts:1-1]()、资料来源：[src/core/runtime/exit-codes.ts:1-1]()
## 社区上下文与版本说明
最新发布版本 v0.0.27 已通过 `@the-long-ride/engram` npm 包发布，并附带 npm 包 tarball 产物；Runtime 模块作为核心结构随该版本一同发布。社区目前存在一条公开度较低、寻求私下沟通的 Issue（#9），内容涉及对仓库的咨询与反馈，但尚未公开具体技术细节，因此本页未基于该 Issue 引入额外行为描述。资料来源：[CHANGELOG.md](https://github.com/the-long-ride/engram/blob/v0.0.27/CHANGELOG.md)、资料来源：[Issue #9](https://github.com/the-long-ride/engram/issues/9)
---
## App 模块
### 相关页面
相关主题：[Runtime 模块](#page-src-core-runtime)
相关源码文件
以下源码文件用于生成本页说明：
- [src/core/web/app/App.tsx](https://github.com/the-long-ride/engram/blob/main/src/core/web/app/App.tsx)
- [src/core/web/app/api-client.ts](https://github.com/the-long-ride/engram/blob/main/src/core/web/app/api-client.ts)
- [src/core/web/app/components/Badge.tsx](https://github.com/the-long-ride/engram/blob/main/src/core/web/app/components/Badge.tsx)
- [src/core/web/app/components/Button.tsx](https://github.com/the-long-ride/engram/blob/main/src/core/web/app/components/Button.tsx)
- [src/core/web/app/components/Card.tsx](https://github.com/the-long-ride/engram/blob/main/src/core/web/app/components/Card.tsx)
- [src/core/web/app/components/ConfirmModal.tsx](https://github.com/the-long-ride/engram/blob/main/src/core/web/app/components/ConfirmModal.tsx)
# App 模块
## 概述
`src/core/web/app` 目录是 Engram 项目的 Web 端 UI 入口模块，承载了浏览器端应用的根组件、与后端的通信客户端以及一组可复用的展示型组件。该模块以 React 函数式组件为基础，遵循"单一职责 + 受控组合"的拆分原则，将页面骨架、数据访问和原子级 UI 控件分别落在不同的文件中，以便于扩展与维护。
资料来源：[src/core/web/app/App.tsx]() [src/core/web/app/api-client.ts]()
## 模块组成与职责
### 入口组件 App.tsx
`App.tsx` 是整个 Web 前端的根组件，负责挂载全局上下文、渲染路由或顶层视图，并组合下层 UI 组件构建可交互界面。它通常作为 React 应用树的顶层节点，向下分发状态、主题与回调函数。
资料来源：[src/core/web/app/App.tsx]()
### 数据访问层 api-client.ts
`api-client.ts` 封装了与 Engram 后端服务（或本地存储抽象层）之间的通信细节。它将 HTTP 请求、错误处理与返回数据的标准化收拢在同一个模块中，使上层组件不必关心协议细节，仅通过导出的函数即可完成读写操作。该层是 UI 与数据持久化/检索逻辑之间的桥梁。
资料来源：[src/core/web/app/api-client.ts]()
### 可复用 UI 组件
`components/` 子目录集中存放了若干原子级展示组件，供 `App.tsx` 及其他页面复用：
- **Badge**：用于呈现状态标签、计数或分类标识等小型徽标元素。
资料来源：[src/core/web/app/components/Badge.tsx]()
- **Button**：统一封装按钮的视觉风格、尺寸与禁用态，保证交互一致性。
资料来源：[src/core/web/app/components/Button.tsx]()
- **Card**：作为内容容器组件，用于聚合标题、正文与操作区，是页面级信息块的基本单位。
资料来源：[src/core/web/app/components/Card.tsx]()
- **ConfirmModal**：提供二次确认对话框，常用于删除、覆盖等不可逆操作的拦截流程。
资料来源：[src/core/web/app/components/ConfirmModal.tsx]()
## 架构与数据流
下面的关系图展示了 `App` 模块内部各文件的依赖方向与职责分层：
```mermaid
graph TD
A[App.tsx
根组件/视图组装] --> B[api-client.ts
数据访问层]
A --> C1[components/Badge.tsx]
A --> C2[components/Button.tsx]
A --> C3[components/Card.tsx]
A --> C4[components/ConfirmModal.tsx]
B -->|HTTP / 存储接口| Backend[(Engram 后端服务)]
C1 -.被组合.-> A
C2 -.被组合.-> A
C3 -.被组合.-> A
C4 -.被组合.-> A
```
由图可见，`App.tsx` 处于顶层，向下同时依赖数据层 `api-client.ts` 与多个 UI 组件；组件层之间彼此独立、不直接耦合，这种扁平结构便于单独替换或升级单个控件。
## 设计与扩展要点
- **关注点分离**：根组件只承担"组合 + 状态分发"职责，业务 IO 被收敛到 `api-client.ts`，渲染细节沉淀在 `components/`，三层各司其职。
资料来源：[src/core/web/app/App.tsx]() [src/core/web/app/api-client.ts]()
- **组件可替换性**：`Badge`、`Button`、`Card` 与 `ConfirmModal` 各自独立维护，新增页面或主题调整时无需改动入口文件。
资料来源：[src/core/web/app/components/Button.tsx]() [src/core/web/app/components/Card.tsx]()
- **二次确认流程**：`ConfirmModal` 的存在表明模块内涉及需要谨慎确认的破坏性操作，使用方在调用时需配合异步回调确保 UI 与业务状态同步。
资料来源：[src/core/web/app/components/ConfirmModal.tsx]()
## 社区上下文
在最新版本 `v0.0.27` 的发布记录中，npm 包 `@the-long-ride/engram` 仍处于持续迭代阶段；社区中曾有用户通过 Issue #9 询问项目使用方式与联系渠道，反映出外部读者对 Web 端入口结构存在初步了解需求。本页所描述的 `App` 模块结构可作为回答此类入门级问题的基础参考。
资料来源：[Issue #9](https://github.com/the-long-ride/engram/issues/9)
---
---
## Doramagic 踩坑日志
项目：the-long-ride/engram
摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。
## 1. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/the-long-ride/engram | host_targets=claude, cursor, mcp_host
## 2. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/the-long-ride/engram | README/documentation is current enough for a first validation pass.
## 3. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/the-long-ride/engram | last_activity_observed missing
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/the-long-ride/engram | no_demo; severity=medium
## 5. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/the-long-ride/engram | no_demo; severity=medium
## 6. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/the-long-ride/engram | issue_or_pr_quality=unknown
## 7. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/the-long-ride/engram | release_recency=unknown