sshanzel/plex

# Plex Plex 是一款本地优先的代码审查工具，可通过你正在使用的编码 agent（Claude Code 或 Codex）来运行。它不是一个新的模型。它是一个 MCP server 和 CLI，旨在让你的 agent 成为一个更加严谨、无偏见的审查者，并且随着你的使用会变得越来越敏锐。 - **无偏见。** 审查在全新的独立上下文中运行，因此它不会受到代码编写者推理逻辑的影响，即使经过多轮审查也是如此。 - **有据可依。** 代码库的爆炸半径图（通过 git co-change、imports 和精确的 TypeScript 边）展示了某项改动还可能破坏什么，而不仅仅是 diff 中的代码行。 - **持续增益。** 审查知识会在全局（跨你的所有代码库）和单个项目内不断积累，并根据你的判定进行重新加权，同时从你的 PR 审查历史中学习。 - **单一信息流。** 第一性原理推理、学习到的陷阱和确定性检查被合并为一个列表，并按严重程度、置信度和爆炸半径进行排序。 推理过程仍然来自前沿模型。Plex 的工作是为其提供正确的上下文，并记住它所学到的东西。 ## 为什么需要它 Copilot 的审查会遇到使用限制，Claudio 的个人版套餐没有审查功能，而编写代码的 agent 本身就是一个有偏见的审查者。Plex 就是那双无偏见的“第二双眼睛”，运行在你已经付费的订阅服务上。 ## 快速开始 **1. 添加插件** 在 Claude Code 中（只需一次 —— 之后你打开的每一个 repo 都会生效）。这就是审查器本身：一个拥有全新上下文的 agent、`/plex:review` 命令，以及运行它的 MCP 引擎。 ``` /plugin marketplace add sshanzel/plugins /plugin install plex@sshanzel ``` **2. 添加 embedding key**（强烈推荐）。这将开启 Plex 中具备*学习*能力的部分：检索陷阱、语义匹配和 PR 历史分析。有关选项，请参阅 [Embeddings](#embeddings)（Voyage 提供免费额度）。 ``` npx @sshanzel/plex init ``` 它会将 key 保存到 `~/.plex/config.json`（你也可以自己创建该文件），并提供为当前 repo 建立索引的选项。想要一个完全可视化的 CLI（从终端运行 `doctor`、`eval`、分析和爆炸半径）？`npm install -g @sshanzel/plex` 会为你提供一个原生的 `plex` 命令 —— 请参阅[命令行使用](#command-line-use-optional)。 **3. 审查。** 运行 **`/plex:review`**，或者直接说*“review my changes with Plex”*。首次审查会为你所在的 repo 建立索引，之后图谱会自动保持更新。 如果没有 key，Plex 依然可以进行审查，只是没有了学习层；并且在添加 key 之前，它会在每次审查时提醒你一次。 ### 使用 Codex Codex 会从其自带的市场安装相同的插件。Codex 没有 agent 类型，因此审查器以 `plex-review` skill 的形式提供： ``` codex plugin marketplace add sshanzel/plex ``` 然后运行 `plex-review` skill（通过 `/skills` 或 `$plex-review`）。其他一切的工作方式都是相同的。 ## 大型代码库 首次审查会为你所在的 repo 建立索引，这会遍历 git 历史。在大型 repo 中这可能需要一分钟的时间，因此首次审查会比之后慢一些。为了提前完成这一步骤，你可以在 repo 内部，在审查之前构建图谱： ``` npx @sshanzel/plex index ``` 此后，审查将使用缓存的图谱，并且仅刷新发生变化的部分。（如果你全局安装了 CLI，只需运行 `plex index` 即可。） ## Embeddings Plex 没有 embedding provider 也能工作，但 key 是开启*学习*层的关键。这就是敏锐但一次性审查与能够持续积累经验的审查者之间的区别： - **没有 key：** 具备全新上下文的审查、爆炸半径图和确定性检查。审查结果仍然会根据文件/行的位置进行自动采纳，并且存储的陷阱仍然会被检索 —— 只是通过关键字匹配，而不是语义匹配。 - **有 key：** 包含上述所有功能，外加完整的知识层。Plex 会以*语义方式*将相关的过去陷阱拉入每次审查中，根据*含义*抑制你已经驳回过的问题（因此即使措辞改变或代码行发生移动它们也能被识别），发现没有人标记过的改动，并且可以从你的 PR 审查历史中学习可重用的陷阱。这就是所谓的“越用越敏锐”的部分。 因此，请添加一个 key：运行 `npx @sshanzel/plex init`，自己创建 `~/.plex/config.json`，或者设置一对环境变量（`PLEX_EMBEDDING_PROVIDER=voyage` 加上该 provider 的 key，例如 `VOYAGE_API_KEY` —— 环境变量会覆盖文件配置）： ``` { "embedding": { "provider": "voyage", "apiKey": "YOUR_KEY" } } ``` 无论采用哪种方式，它都会在下一次审查时生效，无需重新加载。 **Providers:** - **Voyage**（推荐）。专为代码优化的 embeddings，免费额度完全足够起步使用。这是我日常使用的工具。设置 `voyage` 和 `VOYAGE_API_KEY`。 - **OpenAI。** `text-embedding-3-small` 便宜且可靠。设置 `openai` 和 `OPENAI_API_KEY`。 - **Gemini。** 设置 `gemini` 和 `GEMINI_API_KEY`。 - **Ollama。** 完全本地化，无需 key，适合私有 repo。设置 `ollama`（需要运行带有 embedding model（例如 `nomic-embed-text`）的 Ollama）。 稍后切换 provider 会使已存储的向量失效，因为它们在不同的模型之间不具有可比性 (ADR-13)。如果你进行了更改，请删除 `~/.plex/knowledge` 并重新进行分析。 ## 从你的 PR 历史中进行引导 Plex 会随着你的审查变得越来越敏锐，但你也可以通过分析过去的 PR 审查并将其转化为陷阱，给它一个良好的开端。在 repo 内部，设置了 embedding key 并通过 GitHub CLI (`gh`) 认证后： ``` npx @sshanzel/plex analyze --oldest --limit 50 ``` 这会提取你前 50 个 PR 的审查评论，将重复出现的主题进行聚类，并将其提炼为知识。它借助你的 Claude 订阅运行（通过 `claude` CLI，不需要 API key），并且是增量进行的，因此可以重新运行它以继续处理你的历史记录。去掉 `--oldest` 参数则可以分析你最近的 PR。 ## 命令行使用（可选） 正常使用时你不需要终端 CLI：插件会运行审查器，而 `plex init` 会设置你的 key。如果你还想自己运行 Plex 的维护和知识命令（在 CI、脚本中或手动运行），这些内容已在 **[docs/cli.md](docs/cli.md)** 中记录。 ## 工作原理 ``` diff (local or gh PR) │ ▼ Plex MCP server (fresh, unbiased) assembles the grounding: blast radius (Kùzu code graph) · deterministic checks · relevant pitfalls │ ▼ get_review_context your agent reasons (first-principles and grounded) │ ▼ submit_findings → merge · dedup · rank · triage (severity × confidence × blast) │ └─ (PR, opt-in) post the stream back as one GitHub review ▼ record_outcome (accept / reject / waive / acknowledge) → knowledge sharpens ``` **三个来源，一个信息流。** 第一性原理推理（agent）、基于知识的发现（检索到的陷阱）和确定性检查（内置的 TypeScript-AST 规则）。普遍程度是通过严重性来衡量的：常见的*样式 (style)* 问题会被视为约定从而被降级，而常见的 *bug* 则会被视为系统性问题，并作为需要进行迁移的项目被升级。 **两层知识。** 全局层包含通用的陷阱和你的审查风格，这是在你所有的 repo 中学习并按结果重新加权得来的；它适用于所有地方。特定于项目的层包含该 repo 的代码图谱、co-change 耦合以及其特定于 repo 的陷阱；它为单个代码库量身定制审查。 **在 PR 上形成闭环（可选择加入）。** 开启 `autoComment` 后，PR 审查会将排好序的反馈流作为一条 GitHub review 发布：在修改过的行上提供行内评论，并为耦合和感知相关的发现提供摘要，在多轮审查中自动去重。接着，**`/pr-master:respond`** 会逐一处理这些问题（由你决定每一个的处理方式），并将结果记录回知识库中 (ADR-34)。该命令来自同一市场中安装的第二个插件，可以在你需要时单独安装：`/plugin install pr-master@sshanzel`。 **审查历史分析。** Plex 会将你的 PR 审查历史转化为陷阱。它通过 `gh` 提取审查评论，对其进行降噪处理，将相似内容聚类，然后由 LLM 提炼每一个聚类，决定哪些值得保留，以及它们是属于全局层还是项目层。提炼过程在你的订阅下运行，通过连接的 agent（先 `analyze_scan` 后 `add_pitfalls`）或本地 `claude` CLI（`plex analyze`）完成。这是一个增量过程：每个 repo 的游标只会读取新的 PR。 ## MCP 工具 `index_repo` · `get_review_context` · `get_blast_radius` · `get_deterministic_findings` · `submit_findings` · `record_outcome` · `reconcile_outcomes` · `get_relevant_knowledge` · `consolidate_knowledge` · `analyze_scan` · `add_pitfalls` · `analyze_history` · `doctor` ## 架构 **MCP server 和 CLI** 是集成契合点：agent 提供 LLM，而 Plex 提供基础依据和记忆。 **Kùzu**（嵌入式，MIT 许可证）保存着持久化的、特定于 repo 的代码图谱（symbols、imports、co-change 和精确的 alias 边）以及特定于 PR 的大脑（轮次、发现、判定、评论以及*发生了更改但未提供反馈*的信号）。它是一个嵌入式引擎，无需运行任何服务 (ADR-30)。图谱只构建一次，然后进行增量刷新；审查时会在首次使用或发生偏移时对其进行索引或刷新。 **知识库** 是由 JSON 支持的带有 embeddings 的陷阱和事件，位于一个可插拔且可选的 embedding provider（Voyage、OpenAI、Gemini 或 Ollama）之后。豁免机制会根据*含义*在不同轮次中抑制同一个问题，因此即使代码行发生偏移或措辞被重写，它们依然有效。 请参阅 [`docs/architecture.md`](docs/architecture.md) 以及 [`docs/adr/README.md`](docs/adr/README.md) 中的决策日志。 ## 配置 这里的所有内容都是可选的。使用 `plex init` 进行一次设置（保存到 `~/.plex/config.json`），或者将其设置为环境变量，这会覆盖文件配置。 | 变量 | 用途 | |---|---| | `PLEX_EMBEDDING_PROVIDER` | 语义知识和大脑信号：`voyage`、`openai`、`gemini` 或 `ollama`。`none` 会关闭此功能；`fake` 仅用于测试。 | | *(provider key)* | `VOYAGE_API_KEY`、`OPENAI_API_KEY` 或 `GEMINI_API_KEY`。Ollama 不需要。 | | `PLEX_LLM_PROVIDER` | 分析提炼器：`claude-cli`（默认）、`anthropic` 或 `openai`。 | | `PLEX_DATA_DIR` | 特定于 repo 的数据目录。默认集中存放在 `~/.plex/repos/`；设置为 `.plex` 可将其保留在 repo 中，它会在那里被自动忽略。 | | `PLEX_KNOWLEDGE_DIR` | 全局知识库。默认为 `~/.plex/knowledge`。 | | `PLEX_AUTO_COMMENT` | 将 PR 审查的发现发布回 GitHub PR。默认关闭。设置 `PLEX_AUTO_COMMENT_SKIP_NITS=true` 可排除细枝末节的问题；否则也会发布这些细小问题。 | ## 许可证 [MIT](LICENSE)

标签：AI风险缓解, CLI, MCP, MITM代理, SOC Prime, WiFi技术, 人工智能, 代码审查, 开发工具, 文档结构分析, 用户模式Hook绕过, 自动化攻击