# https://github.com/plur-ai/plur 项目说明书 生成时间：2026-07-21 23:07:08 UTC ## 目录 - [PLUR 概览与安装指引](#page-1) - [核心引擎：Engram、Episode 与混合检索](#page-2) - [集成层：MCP 工具、CLI 命令、插件与 Scope 选择退出](#page-3) - [存储、同步、部署与故障排查](#page-4) ## PLUR 概览与安装指引 ### 相关页面 相关主题：[核心引擎：Engram、Episode 与混合检索](#page-2), [集成层：MCP 工具、CLI 命令、插件与 Scope 选择退出](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/plur-ai/plur/blob/main/README.md) - [CHANGELOG.md](https://github.com/plur-ai/plur/blob/main/CHANGELOG.md) - [package.json](https://github.com/plur-ai/plur/blob/main/package.json) - [pnpm-workspace.yaml](https://github.com/plur-ai/plur/blob/main/pnpm-workspace.yaml) - [llms-install.md](https://github.com/plur-ai/plur/blob/main/llms-install.md) - [CLAUDE.md](https://github.com/plur-ai/plur/blob/main/CLAUDE.md) - [CONTRIBUTING.md](https://github.com/plur-ai/plur/blob/main/CONTRIBUTING.md)
# PLUR 概览与安装指引 ## 项目定位与核心能力 PLUR 是一个面向 AI 代理（agent）的跨会话记忆层，提供召回（recall）、写回与共享作用域（shared scope）治理能力。最新的 v0.14.0 是"加固版本"，合并了 24 个 issue，涵盖：更精细的召回与重排修复、强化的 shared-scope 元数据、反馈与 hook 可靠性修复，以及 CLI 资源包（pack）管理。资料来源：[CHANGELOG.md:1-80]()。 仓库对外暴露两类入口： - **CLI**：以 `plur` 为主命令，处理共享作用域的 list / register / dismiss / reoffer 等用户面操作。 - **MCP 服务器**：由 `packages/mcp/src/tools.ts` 实现，向 Agent 暴露 `plur_session_start`、`plur_scopes_discover`、`plur_recall_hybrid`、`plur_doctor` 等工具。 ## 仓库结构与工作区 仓库采用 pnpm 多包（monorepo）布局，顶层 `pnpm-workspace.yaml` 声明各包的路径边界，核心子包如下： | 包路径 | 角色 | 关键依赖 | | --- | --- | --- | | `packages/cli` | `plur` CLI 入口，子命令如 `plur scopes` | Node LTS | | `packages/mcp` | MCP 服务器，承载 `tools.ts` 中的工具 | `@modelcontextprotocol/server@2.0.0-beta.4`、`@modelcontextprotocol/client@2.0.0-beta.4`、`@modelcontextprotocol/core@2.0.0-beta.4` | | 顶层 `package.json` | 工作区脚本与发布协调 | workspaces、scripts | 资料来源：[pnpm-workspace.yaml:1-20]()、[package.json:1-120]()。 ## 安装与发布 普通用户推荐通过 npm `latest` 标签安装稳定版本： ```bash npm install -g @plur-ai/plur # 或 pnpm add -g @plur-ai/plur ``` 安装后，用户配置落地于 `~/.plur/config.yaml`，由核心写入路径（如 `registerDiscoveredScopes`）统一维护。`llms-install.md` 额外提供面向 LLM 客户端的安装指引，README 给出快速上手与示例命令。资料来源：[README.md:1-160]()、[llms-install.md:1-80]()。 ## 入门使用指引 新用户首次接入的推荐流程可概括为以下四步： ```mermaid flowchart LR A[启动 Agent 会话] --> B[plur_session_start] B --> C{有未注册作用域?} C -- 否 --> D[直接使用 recall/write] C -- 是 --> E[plur scopes list] E --> F{register or dismiss} F -- register --> G[写入 Plur config] F -- dismiss --> H[写入 dismissed_scopes] G --> D H --> D D --> I[plur_recall_hybrid / plur_doctor] ``` 落地要点： - `plur_session_start` 会输出"已授权但未注册的 N 个作用域"。资料来源：issue #651。 - `plur scopes` 展示每个作用域的自描述 `description`，作为用户面选 register 或 dismiss 的依据。资料来源：issue #650、#345。 - 被 dismiss 的作用域落入 `dismissed_scopes` 并在下次会话自动过滤。资料来源：issue #649。 - 在 headless / 计划任务环境下使用 `plur_recall_hybrid` 时，需确保 session 目录路径非空，否则会触发 `ENOENT: mkdir ''`。资料来源：issue #641。 ## 已知问题与社区关注 - **MCP SDK v2 迁移**：仓库已切换到 split 包并精确钉住 `2.0.0-beta.4`，需跟踪 GA 后再升级。资料来源：issue #637、#645。 - **作用域元数据时效**：服务端权威 `scope_metadata` 经 `/api/v1/me` 下发并被本地缓存，编辑后要等下次 `/me` 拉取才能在运行中的客户端生效。资料来源：issue #648。 - **作用域主动注册提议**：`plur_session_start` 的提示较冗长，社区正在讨论改为一行安静提醒并指向 `plur scopes`。资料来源：issue #647、#651。 - **CI 与归属纪律**：要求在 PR 打开时若关联 issue 未指派或被他人接管，需给出警告并尝试自动指派。资料来源：issue #593。 - **文档可发现性**：`docs/` 下存在测试金字塔、ADR、runbook、遥测等文档，已通过 CLAUDE.md / CONTRIBUTING 的开发者文档表进行引导，但仍存在 ADR 链接指向单文件、缺少 `docs/adr` 索引的问题。资料来源：issue #620、#644、[CLAUDE.md:1-40]()、[CONTRIBUTING.md:1-40]()。 --- ## 核心引擎：Engram、Episode 与混合检索 ### 相关页面 相关主题：[PLUR 概览与安装指引](#page-1), [存储、同步、部署与故障排查](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [packages/core/src/engrams.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/engrams.ts) - [packages/core/src/episodes.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/episodes.ts) - [packages/core/src/hybrid-search.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/hybrid-search.ts) - [packages/core/src/fts.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/fts.ts) - [packages/core/src/embeddings.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/embeddings.ts) - [packages/core/src/decay.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/decay.ts)
# 核心引擎：Engram、Episode 与混合检索 plur 的核心引擎围绕三层记忆模型（Engram → Episode → 召回视图）以及一个融合关键词与向量相似度的混合检索通道构建。它既支撑本地 CLI 的 `plur recall` 系列命令，也支撑 MCP 服务器暴露的 `plur_recall_hybrid` 工具。 ## 1. 记忆分层模型 ### 1.1 Engram：原子记忆单元 Engram 是引擎写入与召回的最小语义单元。`engrams.ts` 定义了 Engram 的数据结构、序列化格式以及持久化路径——每条 Engram 通常对应一次"观察/反馈/工具调用结果"的可检索记录，并携带时间戳、来源 scope、标签与可选的嵌入向量。 资料来源：[packages/core/src/engrams.ts:1-120]() ### 1.2 Episode：会话级聚合 `episodes.ts` 把同一上下文窗口内产生的多条 Engram 聚合为 Episode，用以表达"这一次会话/这次任务里发生了什么"。Episode 在召回阶段会被用来做会话级排序与剪枝，避免单条噪音 Engram 主导结果。 资料来源：[packages/core/src/episodes.ts:1-80]() ## 2. 混合检索通道 混合检索由 `hybrid-search.ts` 编排：先调用 `fts.ts` 的全文索引拿到 BM25/TF‑IDF 风格的关键词候选，再调用 `embeddings.ts` 计算查询向量并执行近似最近邻搜索，最后用加权融合（reciprocal rank fusion 或线性加权）合并两路结果，再叠加 `decay.ts` 提供的时间衰减分数。 ### 2.1 关键流程 ```mermaid flowchart LR Q[查询 query] --> F[FTS 关键词召回
fts.ts] Q --> E[向量召回
embeddings.ts] F --> H[融合 hybrid-search.ts] E --> H H --> D[时间衰减 decay.ts] D --> R[Top-K Engram/Episode] ``` 资料来源：[packages/core/src/hybrid-search.ts:1-200]()、[packages/core/src/fts.ts:1-120]()、[packages/core/src/embeddings.ts:1-150]()、[packages/core/src/decay.ts:1-100]() ## 3. 召回与健康检查 `plur_recall_hybrid` 是混合检索对外暴露的入口。社区 issue #641 报告过它在无终端上下文（cron / CI / 计划任务）中失败 `ENOENT: mkdir ''`——根因是 session 目录解析在 headless 场景下为空。该问题暴露了引擎对"当前会话目录"的隐式依赖，`plur_doctor` 在该路径下需要被加强以覆盖非交互运行模式。 资料来源：[packages/core/src/hybrid-search.ts:80-160]()、[community issue #641]() ## 4. v0.14.0 的硬化要点 v0.14.0 的发布说明明确把"sharper recall + reranker fixes"列为改进项，意味着 `hybrid-search.ts` 与 `decay.ts` 的融合权重、reranker 调用门槛、以及对低置信度结果的回退策略都经历了调整；同时围绕 shared‑scope 元数据（[issue #648]()）的缓存一致性也得到修补，保证召回时的 `description` / `covers[]` 与服务端 `/api/v1/me` 一致。 资料来源：[packages/core/src/hybrid-search.ts:160-260]()、[packages/core/src/decay.ts:40-120]()、[community issue #648]() ## 关键参考表 | 模块 | 职责 | 对外表现 | |------|------|----------| | engrams.ts | 原子记忆的 CRUD | `engramAdd` / `engramGet` | | episodes.ts | 会话聚合 | `episodeRollup` | | fts.ts | 关键词召回 | BM25 候选 | | embeddings.ts | 语义召回 | ANN Top‑K | | hybrid-search.ts | 融合 + rerank | `plur_recall_hybrid` | | decay.ts | 时间衰减 | score × exp(−Δt/τ) | 资料来源：[packages/core/src/engrams.ts]()、[packages/core/src/episodes.ts]()、[packages/core/src/fts.ts]()、[packages/core/src/embeddings.ts]()、[packages/core/src/hybrid-search.ts]()、[packages/core/src/decay.ts]() --- ## 集成层：MCP 工具、CLI 命令、插件与 Scope 选择退出 ### 相关页面 相关主题：[PLUR 概览与安装指引](#page-1), [存储、同步、部署与故障排查](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [packages/mcp/src/tools.ts](https://github.com/plur-ai/plur/blob/main/packages/mcp/src/tools.ts) - [packages/mcp/src/index.ts](https://github.com/plur-ai/plur/blob/main/packages/mcp/src/index.ts) - [packages/mcp/src/server.ts](https://github.com/plur-ai/plur/blob/main/packages/mcp/src/server.ts) - [packages/cli/src/index.ts](https://github.com/plur-ai/plur/blob/main/packages/cli/src/index.ts) - [packages/cli/src/plur.ts](https://github.com/plur-ai/plur/blob/main/packages/cli/src/plur.ts) - [packages/cli/src/lib/plur-configured.ts](https://github.com/plur-ai/plur/blob/main/packages/cli/src/lib/plur-configured.ts) - [package.json](https://github.com/plur-ai/plur/blob/main/package.json)
# 集成层：MCP 工具、CLI 命令、插件与 Scope 选择退出 ## 概述与分层职责 Plur 的集成层由三层组成：核心库 (`packages/cli` 中的 `Plur` 类)、MCP 服务器 (`packages/mcp/src/server.ts`)、以及面向最终用户的 CLI 入口 (`packages/cli/src/index.ts`)。三者共享同一个底层 `Plur` 实例,通过 `plur-configured.ts` 注入到 `plur.ts` 中以保证配置一致。 - **核心层**:负责记忆、反馈、Hook、共享 Scope 元数据,以及将 `dismissed_scopes` 持久化到 `~/.plur/config.yaml`。资料来源:[packages/cli/src/plur.ts:1-40]() - **CLI 层**:主要面向人类用户;`plur scopes list/register/dismiss/reoffer` 是共享 Scope 的用户面入口。资料来源:[packages/cli/src/index.ts:1-60]() - **MCP 层**:面向智能体(Agent)客户端;通过 `plur_session_start` 等工具暴露能力,并以"单行安静提示"指向 CLI 表面。资料来源:[packages/mcp/src/index.ts:1-80]() ## MCP 工具与 SDK 版本基线 `packages/mcp/src/tools.ts` 是 MCP 工具的注册中心,`plur_session_start`、`plur_scopes_discover`、`plur_recall_hybrid`、`plur_doctor` 等工具都由此导出。MCP 服务器已迁移到 SDK v2 的拆分包,固定到精确 beta: ```json "@modelcontextprotocol/server": "2.0.0-beta.4", "@modelcontextprotocol/client": "2.0.0-beta.4", "@modelcontextprotocol/core": "2.0.0-beta.4" ``` 资料来源:[package.json:dependencies](),[#637](https://github.com/plur-ai/plur/issues/637)。Zod v3 → v4 的迁移是此次升级的硬约束之一(截止 2026-07-28),后续 GA 升级将由 [#645](https://github.com/plur-ai/plur/issues/645) 跟踪。 ### Scope 提示的瘦身 `plur_session_start` 历来会在工具输出末尾追加一段"权威但未注册"的 Scope 发现提示。在 [#651](https://github.com/plur-ai/plur/issues/651) 中,这段提示被替换为一行安静提示: > `N scope(s) available — run `plur scopes` to register or dismiss.` 资料来源:[packages/mcp/src/tools.ts:1926-1955]()。意图是把发现与决策都收敛到 CLI 表面,避免在每次会话启动时打断 Agent。 ## CLI 命令:Scope 的用户面 `packages/cli/src/index.ts` 注册 `plur scopes` 子命令族,提供 list / register / dismiss / reoffer 四种动作: | 子命令 | 作用 | 适用场景 | | --- | --- | --- | | `plur scopes list` | 列出已授权但未注册的共享 Scope,附带 `description` 与 `covers[]` | 浏览可选能力 | | `plur scopes register` | 注册一个或多个 Scope,经由 `registerDiscoveredScopes` 写入配置 | 主动接入 | | `plur scopes dismiss` | 将 Scope 标识符加入 `dismissed_scopes` | 长期拒绝 | | `plur scopes reoffer` | 清理 `dismissed_scopes` 中已存在的条目 | 重新询问 | 资料来源:[packages/cli/src/index.ts:1-200]()、[#650](https://github.com/plur-ai/plur/issues/650)。`dismissed_scopes` 与已注册的 Scope 都持久化在 `~/.plur/config.yaml`,复用 `registerDiscoveredScopes` 已有的写路径,资料来源:[packages/cli/src/plur.ts:1-120]()。 ## 共享 Scope 的发现、注册与退出 MCP、CLI、Core 三层按职责协同处理 Scope。Core 持有 `dismissed_scopes` 的事实源;CLI 是用户面;MCP 只做最轻量的提示与过滤。 ```mermaid flowchart LR A[plur_session_start
MCP] -->|发现 N 个未注册| B{已 dismiss?} B -- 否 --> C[安静提示:
运行 plur scopes] B -- 是 --> Z[静默] C --> D[plur scopes list
CLI 用户面] D --> E[register / dismiss / reoffer] E --> F[~/.plur/config.yaml
dismissed_scopes] F --> G[Core: registerDiscoveredScopes] G --> A ``` 资料来源:[packages/cli/src/plur.ts:1-120]()、[packages/mcp/src/tools.ts:1926-1955]()、[#649](https://github.com/plur-ai/plur/issues/649)。Scope 元数据(`description`、`covers[]`)由服务器通过 `/api/v1/me` 推送并被客户端缓存,#648 指出当前缺少"新鲜度信号",编辑后直到下一次 `/me` 拉取才会反映到运行中的客户端。 ## 已知的集成层边界情况 - **Headless 运行失败**:`plur_recall_hybrid` 在无交互上下文(cron、CI)下会因 `session-dir` 为空而报 `ENOENT: mkdir ''`,但 `plur_doctor` 仍报告健康。资料来源:[#641](https://github.com/plur-ai/plur/issues/641)、[packages/cli/src/lib/plur-configured.ts:1-80]()。 - **MCP SDK v2 GA 升级**:目前精确固定在 `2.0.0-beta.4`,需在稳定版发布后切换。资料来源:[#645](https://github.com/plur-ai/plur/issues/645)、[package.json]()。 - **Scope 元数据新鲜度**:尚未引入失效/版本字段,客户端只能被动等待下一次 `/me` 拉取。资料来源:[#648](https://github.com/plur-ai/plur/issues/648)。 --- ## 存储、同步、部署与故障排查 ### 相关页面 相关主题：[核心引擎：Engram、Episode 与混合检索](#page-2), [集成层：MCP 工具、CLI 命令、插件与 Scope 选择退出](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [packages/core/src/storage.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/storage.ts) - [packages/core/src/storage-adapter.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/storage-adapter.ts) - [packages/core/src/storage-indexed.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/storage-indexed.ts) - [packages/core/src/storage-pglite.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/storage-pglite.ts) - [packages/core/src/sync.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/sync.ts) - [packages/core/src/migrations/runner.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/migrations/runner.ts) - [packages/core/src/config.ts](https://github.com/plur-ai/plur/blob/main/packages/core/src/config.ts) - [packages/mcp/src/tools.ts](https://github.com/plur-ai/plur/blob/main/packages/mcp/src/tools.ts) - [packages/cli/src/index.ts](https://github.com/plur-ai/plur/blob/main/packages/cli/src/index.ts) - [docs/runbooks/](https://github.com/plur-ai/plur/tree/main/docs/runbooks)
# 存储、同步、部署与故障排查 ## 概览与作用域 plur 的持久层与同步层围绕"本地优先 + 服务器权威元数据"的模式构建：核心记忆条目与状态写入本地存储适配器，作用域（scope）描述、`/me` 元数据等权威信息则从服务器拉取并缓存。配置（包含 `dismissed_scopes`、已注册作用域列表等）落盘到 `~/.plur/config.yaml`，共享作用域元数据则通过 `/api/v1/me` 的 `scope_metadata` 字段下发（详见 [#648](https://github.com/plur-ai/plur/issues/648)）。 本页聚焦四个相互衔接的子系统：本地存储适配器、跨进程/跨端同步、典型部署形态（CLI、headless、MCP 服务器），以及社区中高频出现的故障模式与排查 runbook。 ## 存储层（Storage） ### 适配器接口 `storage-adapter.ts` 定义统一的适配器契约，所有后端必须实现相同的读写/迁移接口，保证 `storage.ts` 顶层逻辑不感知底层差异。资料来源：[packages/core/src/storage-adapter.ts:1-120]()。 ### 后端实现 - **IndexedDB**：浏览器/本地进程内首选，`storage-indexed.ts` 实现，零依赖。 - **PGlite**：`storage-pglite.ts` 提供 SQL 级能力，适用于需要查询、聚合或大规模语料的部署场景。 - 选择由运行时通过 `config.ts` 中持久化的偏好决定。 ### 迁移 `migrations/runner.ts` 在启动阶段按版本号顺序应用 schema 变更；写入路径（如 `registerDiscoveredScopes`）触发配置文件的原子更新。资料来源：[packages/core/src/migrations/runner.ts:1-80]()。 ### 配置持久化 `config.ts` 维护 `~/.plur/config.yaml`，其中至少包含：已注册作用域列表（按来源 URL 维度可选命名空间）、`dismissed_scopes`（per-scope 关闭提示，参见 [#649](https://github.com/plur-ai/plur/issues/649)）。 ## 同步层（Sync） `sync.ts` 协调本地状态与服务器权威态： 1. 启动时调用 `/api/v1/me` 拉取 `scope_metadata`，更新本地缓存； 2. 通过 `dismissed_scopes` 过滤待提示的作用域，避免对用户已忽略的项重复打扰（[#649](https://github.com/plur-ai/plur/issues/649)、[#651](https://github.com/plur-ai/plur/issues/651)）； 3. 写入触发时按作用域路由到对应后端。 作用域元数据目前缓存到下一次 `/me` 拉取为止，未提供显式新鲜度信号，这是 [#648](https://github.com/plur-ai/plur/issues/648) 跟踪的低优先级改进项。 ## 部署模式 | 模式 | 入口 | 存储 | 典型场景 | |---|---|---|---| | CLI 交互 | `packages/cli/src/index.ts` | 本地适配器（IndexedDB / PGlite） | 开发者手动管理作用域与记忆 | | MCP 服务器（交互） | `packages/mcp/src/tools.ts` | 同上 + 进程内缓存 | IDE/编辑器集成，会话启动提示 | | MCP 服务器（headless） | 同上 | 同上，但 `session-dir` 可能为空 | 定时任务、CI、cron | CLI 是面向用户的"作用域操作"主入口（`plur scopes list/register/dismiss/reoffer`，[#650](https://github.com/plur-ai/plur/issues/650)），MCP 会话提示则精简为一行引导（[#651](https://github.com/plur-ai/plur/issues/651)）。 ## 故障排查（Troubleshooting） 社区中高频、可在 docs/runbooks 中归档的故障包括： - **ENOENT: mkdir ''** — headless/计划任务运行 `plur_recall_hybrid` 时失败，因为 `session-dir` 为空字符串。`plur_doctor` 仍报告健康。修复方向：在 headless 上下文中显式解析或兜底 session-dir 路径。资料来源：[#641](https://github.com/plur-ai/plur/issues/641)。 - **作用域元数据陈旧** — 服务器端编辑 `description`/`covers[]` 后，运行中的客户端直到下次 `/me` 拉取前仍展示旧值；可临时通过重启或强制刷新缓解。资料来源：[#648](https://github.com/plur-ai/plur/issues/648)。 - **作用域重复提示** — 即便已 `dismiss`，旧版本仍会在 `plur_session_start` 中提示；升级到包含 #649/#651 的构建后，提示应自动收敛为一行且排除已关闭项。 - **作用域 opt-out 状态丢失** — 通常源于 `~/.plur/config.yaml` 写入失败或被外部工具回滚；用 `plur scopes list` 与 `plur scopes reoffer` 校验。 - **迁移失败** — `migrations/runner.ts` 在版本跳跃报错时不会自动降级，需对照 `docs/runbooks/migrations.md` 回滚。 针对贡献者侧，还有一条纪律性约束：PR 必须链接到已分配的 issue，否则 CI 会发出警告并在未分配时尝试自动指派，以避免重复修复（[#593](https://github.com/plur-ai/plur/issues/593)）。 ## 小结 - 存储：适配器 + 迁移 + 配置三件套，覆盖 IndexedDB 与 PGlite 两种后端。 - 同步：以 `/api/v1/me` 为权威源，按 `dismissed_scopes` 过滤写入与提示。 - 部署：CLI 面向用户，MCP 面向 agent，headless 模式需关注路径兜底。 - 排查：runbook 应覆盖目录解析、元数据新鲜度、opt-out 状态与迁移回滚四类。 相关进一步阅读：归档文档目录 `docs/runbooks/`（参见 [#620](https://github.com/plur-ai/plur/issues/620) 中关于 runbook 与 ADR 索引的整理）。 --- --- ## Doramagic 踩坑日志 项目：plur-ai/plur 摘要：发现 33 个潜在踩坑项，其中 8 个为 high/blocking；最高优先级：安装坑 - 来源证据：Upgrade MCP SDK v2 from 2.0.0-beta.4 to stable GA when released。 ## 1. 安装坑 · 来源证据：Upgrade MCP SDK v2 from 2.0.0-beta.4 to stable GA when released - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Upgrade MCP SDK v2 from 2.0.0-beta.4 to stable GA when released - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/plur-ai/plur/issues/645 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。 ## 2. 安全/权限坑 · 失败模式：security_permissions: Proactively offer to register authorized-but-unregistered scopes (per-scope, remembered opt-out) - 严重度：high - 证据强度：source_linked - 发现：Developers should check this security_permissions risk before relying on the project: Proactively offer to register authorized-but-unregistered scopes (per-scope, remembered opt-out) - 对用户的影响：Developers may expose sensitive permissions or credentials: Proactively offer to register authorized-but-unregistered scopes (per-scope, remembered opt-out) - 证据：failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/647 | Proactively offer to register authorized-but-unregistered scopes (per-scope, remembered opt-out) ## 3. 安全/权限坑 · 失败模式：security_permissions: Scope-metadata edits not reflected in running clients (cached until next /me pull) — freshnes... - 严重度：high - 证据强度：source_linked - 发现：Developers should check this security_permissions risk before relying on the project: Scope-metadata edits not reflected in running clients (cached until next /me pull) — freshness signal? - 对用户的影响：Developers may expose sensitive permissions or credentials: Scope-metadata edits not reflected in running clients (cached until next /me pull) — freshness signal? - 证据：failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/648 | Scope-metadata edits not reflected in running clients (cached until next /me pull) — freshness signal? ## 4. 安全/权限坑 · 失败模式：security_permissions: plur sync: scope-aware push — don't send private-visibility engrams to shared remotes - 严重度：high - 证据强度：source_linked - 发现：Developers should check this security_permissions risk before relying on the project: plur sync: scope-aware push — don't send private-visibility engrams to shared remotes - 对用户的影响：Developers may expose sensitive permissions or credentials: plur sync: scope-aware push — don't send private-visibility engrams to shared remotes - 证据：failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/640 | plur sync: scope-aware push — don't send private-visibility engrams to shared remotes ## 5. 安全/权限坑 · 来源证据：Proactively offer to register authorized-but-unregistered scopes (per-scope, remembered opt-out) - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Proactively offer to register authorized-but-unregistered scopes (per-scope, remembered opt-out) - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/plur-ai/plur/issues/647 | 来源类型 github_issue 暴露的待验证使用条件。 ## 6. 安全/权限坑 · 来源证据：Scope-metadata edits not reflected in running clients (cached until next /me pull) — freshness signal? - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Scope-metadata edits not reflected in running clients (cached until next /me pull) — freshness signal? - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/plur-ai/plur/issues/648 | 来源类型 github_issue 暴露的待验证使用条件。 ## 7. 安全/权限坑 · 来源证据：scopes opt-out (cli): 'plur scopes' list/register/dismiss/reoffer — the user-facing surface - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：scopes opt-out (cli): 'plur scopes' list/register/dismiss/reoffer — the user-facing surface - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/plur-ai/plur/issues/650 | 来源类型 github_issue 暴露的待验证使用条件。 ## 8. 安全/权限坑 · 来源证据：scopes opt-out (core): persist dismissed scopes + single register/dismiss/reoffer + filter discovery - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：scopes opt-out (core): persist dismissed scopes + single register/dismiss/reoffer + filter discovery - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/plur-ai/plur/issues/649 | 来源类型 github_issue 暴露的待验证使用条件。 ## 9. 安装坑 · 失败模式：installation: Upgrade MCP SDK v2 from 2.0.0-beta.4 to stable GA when released - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Upgrade MCP SDK v2 from 2.0.0-beta.4 to stable GA when released - 对用户的影响：Developers may fail before the first successful local run: Upgrade MCP SDK v2 from 2.0.0-beta.4 to stable GA when released - 证据：failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/645 | Upgrade MCP SDK v2 from 2.0.0-beta.4 to stable GA when released ## 10. 安装坑 · 失败模式：installation: compat: MCP SDK v2 migration — import split + Zod v3→v4 (deadline 2026-07-28) - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: compat: MCP SDK v2 migration — import split + Zod v3→v4 (deadline 2026-07-28) - 对用户的影响：Developers may fail before the first successful local run: compat: MCP SDK v2 migration — import split + Zod v3→v4 (deadline 2026-07-28) - 证据：failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/637 | compat: MCP SDK v2 migration — import split + Zod v3→v4 (deadline 2026-07-28) ## 11. 安装坑 · 失败模式：installation: plur-hermes 0.9.11 — pin CLI 0.9.12 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: plur-hermes 0.9.11 — pin CLI 0.9.12 - 对用户的影响：Upgrade or migration may change expected behavior: plur-hermes 0.9.11 — pin CLI 0.9.12 - 证据：failure_mode_cluster:github_release | https://github.com/plur-ai/plur/releases/tag/hermes-v0.9.11 | plur-hermes 0.9.11 — pin CLI 0.9.12 ## 12. 安装坑 · 失败模式：installation: v0.10.0 — security-hardening release - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v0.10.0 — security-hardening release - 对用户的影响：Upgrade or migration may change expected behavior: v0.10.0 — security-hardening release - 证据：failure_mode_cluster:github_release | https://github.com/plur-ai/plur/releases/tag/v0.10.0 | v0.10.0 — security-hardening release ## 13. 安装坑 · 失败模式：installation: v0.11.0 — Hooks that actually finish, tension lifecycle, migration importers - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v0.11.0 — Hooks that actually finish, tension lifecycle, migration importers - 对用户的影响：Upgrade or migration may change expected behavior: v0.11.0 — Hooks that actually finish, tension lifecycle, migration importers - 证据：failure_mode_cluster:github_release | https://github.com/plur-ai/plur/releases/tag/v0.11.0 | v0.11.0 — Hooks that actually finish, tension lifecycle, migration importers ## 14. 安装坑 · 失败模式：installation: v0.12.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v0.12.0 - 对用户的影响：Upgrade or migration may change expected behavior: v0.12.0 - 证据：failure_mode_cluster:github_release | https://github.com/plur-ai/plur/releases/tag/v0.12.0 | v0.12.0 ## 15. 安装坑 · 失败模式：installation: v0.13.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v0.13.0 - 对用户的影响：Upgrade or migration may change expected behavior: v0.13.0 - 证据：failure_mode_cluster:github_release | https://github.com/plur-ai/plur/releases/tag/v0.13.0 | v0.13.0 ## 16. 安装坑 · 失败模式：installation: v0.14.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v0.14.0 - 对用户的影响：Upgrade or migration may change expected behavior: v0.14.0 - 证据：failure_mode_cluster:github_release | https://github.com/plur-ai/plur/releases/tag/v0.14.0 | v0.14.0 ## 17. 安装坑 · 来源证据：compat: MCP SDK v2 migration — import split + Zod v3→v4 (deadline 2026-07-28) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：compat: MCP SDK v2 migration — import split + Zod v3→v4 (deadline 2026-07-28) - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/plur-ai/plur/issues/637 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 18. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/plur-ai/plur | host_targets=mcp_host, openclaw, claude_code, claude, cursor, chatgpt ## 19. 配置坑 · 失败模式：configuration: CI: warn on PR-open when the linked issue is assigned to someone else (+ auto-assign if unass... - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: CI: warn on PR-open when the linked issue is assigned to someone else (+ auto-assign if unassigned) - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: CI: warn on PR-open when the linked issue is assigned to someone else (+ auto-assign if unassigned) - 证据：failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/593 | CI: warn on PR-open when the linked issue is assigned to someone else (+ auto-assign if unassigned) ## 20. 配置坑 · 失败模式：configuration: Orphaned docs + missing CLAUDE.md/CONTRIBUTING references (test-pyramid, ADRs, runbooks, tele... - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: Orphaned docs + missing CLAUDE.md/CONTRIBUTING references (test-pyramid, ADRs, runbooks, telemetry, no-AI-attribution) - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Orphaned docs + missing CLAUDE.md/CONTRIBUTING references (test-pyramid, ADRs, runbooks, telemetry, no-AI-attribution) - 证据：failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/620 | Orphaned docs + missing CLAUDE.md/CONTRIBUTING references (test-pyramid, ADRs, runbooks, telemetry, no-AI-attribution) ## 21. 配置坑 · 失败模式：configuration: plur_recall_hybrid fails with "ENOENT: mkdir ''" in headless/scheduled runs (empty session-di... - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: plur_recall_hybrid fails with "ENOENT: mkdir ''" in headless/scheduled runs (empty session-dir path); plur_doctor still reports healthy - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: plur_recall_hybrid fails with "ENOENT: mkdir ''" in headless/scheduled runs (empty session-dir path); plur_doctor still reports healthy - 证据：failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/641 | plur_recall_hybrid fails with "ENOENT: mkdir ''" in headless/scheduled runs (empty session-dir path); plur_doctor still reports healthy ## 22. 配置坑 · 失败模式：configuration: scopes opt-out (cli): 'plur scopes' list/register/dismiss/reoffer — the user-facing surface - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: scopes opt-out (cli): 'plur scopes' list/register/dismiss/reoffer — the user-facing surface - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: scopes opt-out (cli): 'plur scopes' list/register/dismiss/reoffer — the user-facing surface - 证据：failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/650 | scopes opt-out (cli): 'plur scopes' list/register/dismiss/reoffer — the user-facing surface ## 23. 配置坑 · 失败模式：configuration: scopes opt-out (core): persist dismissed scopes + single register/dismiss/reoffer + filter di... - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: scopes opt-out (core): persist dismissed scopes + single register/dismiss/reoffer + filter discovery - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: scopes opt-out (core): persist dismissed scopes + single register/dismiss/reoffer + filter discovery - 证据：failure_mode_cluster:github_issue | https://github.com/plur-ai/plur/issues/649 | scopes opt-out (core): persist dismissed scopes + single register/dismiss/reoffer + filter discovery ## 24. 配置坑 · 来源证据：ADR link in CLAUDE.md labeled "index" but points to a single file (no docs/adr index) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：ADR link in CLAUDE.md labeled "index" but points to a single file (no docs/adr index) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/plur-ai/plur/issues/644 | 来源类型 github_issue 暴露的待验证使用条件。 ## 25. 配置坑 · 来源证据：plur_recall_hybrid fails with "ENOENT: mkdir ''" in headless/scheduled runs (empty session-dir path); plur_doctor still… - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：plur_recall_hybrid fails with "ENOENT: mkdir ''" in headless/scheduled runs (empty session-dir path); plur_doctor still reports healthy - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/plur-ai/plur/issues/641 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。 ## 26. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/plur-ai/plur | README/documentation is current enough for a first validation pass. ## 27. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/plur-ai/plur | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/plur-ai/plur | no_demo; severity=medium ## 29. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/plur-ai/plur | no_demo; severity=medium ## 30. 安全/权限坑 · 来源证据：CI: warn on PR-open when the linked issue is assigned to someone else (+ auto-assign if unassigned) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：CI: warn on PR-open when the linked issue is assigned to someone else (+ auto-assign if unassigned) - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/plur-ai/plur/issues/593 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 31. 安全/权限坑 · 来源证据：Orphaned docs + missing CLAUDE.md/CONTRIBUTING references (test-pyramid, ADRs, runbooks, telemetry, no-AI-attribution) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Orphaned docs + missing CLAUDE.md/CONTRIBUTING references (test-pyramid, ADRs, runbooks, telemetry, no-AI-attribution) - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/plur-ai/plur/issues/620 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。 ## 32. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/plur-ai/plur | issue_or_pr_quality=unknown ## 33. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/plur-ai/plur | release_recency=unknown