plur 项目说明书 - Doramagic.ai

Doramagic 项目包 · 项目说明书

plur 项目

AI 智能体的共享内存

PLUR 概览与安装指引

PLUR 是一个面向 AI 代理（agent）的跨会话记忆层，提供召回（recall）、写回与共享作用域（shared scope）治理能力。最新的 v0.14.0 是"加固版本"，合并了 24 个 issue，涵盖：更精细的召回与重排修复、强化的 shared-scope 元数据、反馈与 hook 可靠性修复，以及 CLI 资源包（pack）管理。资料来源：[CHANGE...

章节 相关页面

继续阅读本节完整说明和来源证据。

项目定位与核心能力

仓库对外暴露两类入口：

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/[email protected]`、`@modelcontextprotocol/[email protected]`、`@modelcontextprotocol/[email protected]`
顶层 `package.json`	工作区脚本与发布协调	workspaces、scripts

资料来源：pnpm-workspace.yaml:1-20、package.json:1-120。

安装与发布

普通用户推荐通过 npm latest 标签安装稳定版本：

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。

入门使用指引

新用户首次接入的推荐流程可概括为以下四步：

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。

资料来源：pnpm-workspace.yaml:1-20、package.json:1-120。

核心引擎：Engram、Episode 与混合检索

plur 的核心引擎围绕三层记忆模型（Engram → Episode → 召回视图）以及一个融合关键词与向量相似度的混合检索通道构建。它既支撑本地 CLI 的 plur recall 系列命令，也支撑 MCP 服务器暴露的 plurrecallhybrid 工具。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 1.1 Engram：原子记忆单元

继续阅读本节完整说明和来源证据。

章节 1.2 Episode：会话级聚合

继续阅读本节完整说明和来源证据。

章节 2.1 关键流程

继续阅读本节完整说明和来源证据。

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 关键流程

flowchart LR
  Q[查询 query] --> F[FTS 关键词召回<br/>fts.ts]
  Q --> E[向量召回<br/>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

资料来源：packages/core/src/engrams.ts:1-120

集成层：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 中以保证配置一致。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 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:

"@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。Zod v3 → v4 的迁移是此次升级的硬约束之一(截止 2026-07-28),后续 GA 升级将由 #645 跟踪。

Scope 提示的瘦身

plur_session_start 历来会在工具输出末尾追加一段"权威但未注册"的 Scope 发现提示。在 #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。dismissed_scopes 与已注册的 Scope 都持久化在 ~/.plur/config.yaml,复用 registerDiscoveredScopes 已有的写路径,资料来源:packages/cli/src/plur.ts:1-120。

共享 Scope 的发现、注册与退出

MCP、CLI、Core 三层按职责协同处理 Scope。Core 持有 dismissed_scopes 的事实源;CLI 是用户面;MCP 只做最轻量的提示与过滤。

flowchart LR
  A[plur_session_start<br/>MCP] -->|发现 N 个未注册| B{已 dismiss?}
  B -- 否 --> C[安静提示:<br/>运行 plur scopes]
  B -- 是 --> Z[静默]
  C --> D[plur scopes list<br/>CLI 用户面]
  D --> E[register / dismiss / reoffer]
  E --> F[~/.plur/config.yaml<br/>dismissed_scopes]
  F --> G[Core: registerDiscoveredScopes]
  G --> A

资料来源:packages/cli/src/plur.ts:1-120、packages/mcp/src/tools.ts:1926-1955、#649。Scope 元数据(description、covers[])由服务器通过 /api/v1/me 推送并被客户端缓存,#648 指出当前缺少"新鲜度信号",编辑后直到下一次 /me 拉取才会反映到运行中的客户端。

已知的集成层边界情况

Headless 运行失败:plur_recall_hybrid 在无交互上下文(cron、CI)下会因 session-dir 为空而报 ENOENT: mkdir '',但 plur_doctor 仍报告健康。资料来源:#641、packages/cli/src/lib/plur-configured.ts:1-80。
MCP SDK v2 GA 升级:目前精确固定在 2.0.0-beta.4,需在稳定版发布后切换。资料来源:#645、package.json。
Scope 元数据新鲜度:尚未引入失效/版本字段,客户端只能被动等待下一次 /me 拉取。资料来源:#648。

资料来源:package.json:dependencies,#637。Zod v3 → v4 的迁移是此次升级的硬约束之一(截止 2026-07-28),后续 GA 升级将由 #645 跟踪。

存储、同步、部署与故障排查

plur 的持久层与同步层围绕"本地优先 + 服务器权威元数据"的模式构建：核心记忆条目与状态写入本地存储适配器，作用域（scope）描述、/me 元数据等权威信息则从服务器拉取并缓存。配置（包含 dismissedscopes、已注册作用域列表等）落盘到 ~/.plur/config.yaml，共享作用域元数据则通过 /api/v1/me 的 scopemetadata ...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 适配器接口

继续阅读本节完整说明和来源证据。

章节 后端实现

继续阅读本节完整说明和来源证据。

章节迁移

继续阅读本节完整说明和来源证据。

概览与作用域

plur 的持久层与同步层围绕"本地优先 + 服务器权威元数据"的模式构建：核心记忆条目与状态写入本地存储适配器，作用域（scope）描述、/me 元数据等权威信息则从服务器拉取并缓存。配置（包含 dismissed_scopes、已注册作用域列表等）落盘到 ~/.plur/config.yaml，共享作用域元数据则通过 /api/v1/me 的 scope_metadata 字段下发（详见 #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）。

同步层（Sync）

sync.ts 协调本地状态与服务器权威态：

启动时调用 /api/v1/me 拉取 scope_metadata，更新本地缓存；
通过 dismissed_scopes 过滤待提示的作用域，避免对用户已忽略的项重复打扰（#649、#651）；
写入触发时按作用域路由到对应后端。

作用域元数据目前缓存到下一次 /me 拉取为止，未提供显式新鲜度信号，这是 #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），MCP 会话提示则精简为一行引导（#651）。

故障排查（Troubleshooting）

社区中高频、可在 docs/runbooks 中归档的故障包括：

ENOENT: mkdir '' — headless/计划任务运行 plur_recall_hybrid 时失败，因为 session-dir 为空字符串。plur_doctor 仍报告健康。修复方向：在 headless 上下文中显式解析或兜底 session-dir 路径。资料来源：#641。
作用域元数据陈旧 — 服务器端编辑 description/covers[] 后，运行中的客户端直到下次 /me 拉取前仍展示旧值；可临时通过重启或强制刷新缓解。资料来源：#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）。

小结

存储：适配器 + 迁移 + 配置三件套，覆盖 IndexedDB 与 PGlite 两种后端。
同步：以 /api/v1/me 为权威源，按 dismissed_scopes 过滤写入与提示。
部署：CLI 面向用户，MCP 面向 agent，headless 模式需关注路径兜底。
排查：runbook 应覆盖目录解析、元数据新鲜度、opt-out 状态与迁移回滚四类。

相关进一步阅读：归档文档目录 docs/runbooks/（参见 #620 中关于 runbook 与 ADR 索引的整理）。

来源：https://github.com/plur-ai/plur / 项目说明书

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：Upgrade MCP SDK v2 from 2.0.0-beta.4 to stable GA when released

可能阻塞安装或首次运行。

high 失败模式：security_permissions: 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)

high 失败模式：security_permissions: Scope-metadata edits not reflected in running clients (cached until next /me pull) — freshnes...

Developers may expose sensitive permissions or credentials: Scope-metadata edits not reflected in running clients (cached until next /me pull) — freshness signal?

high 失败模式：security_permissions: 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

Pitfall Log / 踩坑日志

项目：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

来源：Doramagic 发现、验证与编译记录