项目概述

Claude Plugins Validation（简称 CPV）是一个用于校验 Claude Code 插件合规性的元工具。它会对待发布的插件目录进行多维度检查，包括 .claude-plugin/plugin.json 清单完整性、技能 frontmatter 字段、MCP 服务声明、依赖脚本以及潜在的提示词注入风险（skillaudit 维度）。

CPV 既可以作为 Claude Code 插件加载供 AI 助手调用，也可以作为独立的 CLI 工具在 CI 流水线中执行非交互式校验。这种"双重身份"是本项目的核心设计：同一套校验逻辑在两种部署形态下复用，避免开发者在本地与远端看到不同的检测结论。

最新版本 v3.23.1 在 orchestrator 中修复了进度标记从调度线程而非工作线程发出的问题，确保在 CI 长时运行场景下日志可观测。 资料来源：CHANGELOG.md:5-7

安装方式

CPV 的安装路径由其双重使用模式决定，因此 README 与 pyproject.toml 同时描述了 Python 包安装与插件目录安装两种途径。

Python 包入口在 pyproject.toml 中声明，指向 scripts/ 下的多个脚本模块；插件清单 .claude-plugin/plugin.json 则描述了被 Claude Code 加载时的命令与技能元数据。 资料来源：pyproject.toml:1-40 资料来源：.claude-plugin/plugin.json:1-20

两种使用模式

模式 A：Claude Code 插件模式

当 CPV 仓库被放置到 ~/.claude/plugins/ 下后，Claude Code 会读取 .claude-plugin/plugin.json 并将 CPV 注册为一个可调用的插件。AI 助手可以在对话中触发其内部命令与技能（如 ci-preflight、/cpv:validate 等），对当前工作区的插件树进行交互式诊断。该模式的优势在于：校验结果可以由 AI 助手直接解读，并辅助用户修复 frontmatter 错误或 MCP 声明问题。 资料来源：README.md:1-50

模式 B：独立 CLI 验证模式

通过 cpv-remote-validate plugin <path> --strict 命令直接对本地或远程拉取的插件目录执行校验。该模式专为非交互场景设计，常被 scripts/publish.py 的 canonical pipeline 调用作为发布门禁。cpv_validation_common.py 提供了 CLI 模式下的共享数据常量与辅助函数。 资料来源：scripts/cpv-remote-validate:1-30 资料来源：scripts/cpv_validation_common.py:1-30

flowchart LR
    A[插件源码] --> B{使用模式}
    B -- 插件模式 --> C[Claude Code 会话]
    B -- CLI 模式 --> D[cpv-remote-validate]
    C --> E[AI 解读 + 修复建议]
    D --> F[CI 流水线 / publish.py]
    E --> G[校验报告]
    F --> G

模式差异与社区关注点

两种模式共享底层检测器，但触发时机与输出形态不同。CLI 模式因被 publish.py 的 run() 包装且默认 timeout=300，在大型测试套件场景下可能无法满足时长要求（社区 issue #179）；插件模式则常因 AI 误判 PROSE 中的反注入守卫代码而触发 skillaudit 误报（issue #170、#177、#178）。在 --strict 模式下，校验范围还会延伸至非可发布的 tracked 内容，需要通过 .cpvignore 或文件白名单收敛（issue #176）。 资料来源：scripts/publish.py:1-40

小结

• 安装：pip 安装 CLI，克隆目录安装插件，两种产物互不冲突。
• 模式 A：Claude Code 插件，适合开发期交互式诊断。
• 模式 B：CLI 校验，适合 CI 与发布门禁，需关注超时与检测范围配置。

1. 仓库定位与顶层布局

claude-plugins-validation（CPV）是一个 Claude Code 插件，其自身也是一种「要被打包、发布、CI 校验」的插件。因此仓库在文件层面同时扮演两个角色：① 面向终端用户的「校验工具」；② 面向其他插件作者的「参考实现」。整个仓库以 Claude 插件的标准约定（commands/、agents/、scripts/）为核心，辅以 Python 打包与 CI 资源。

顶层目录大致如下：

• agents/ — Claude agent 定义，决定哪些任务由代理而非 CLI 直接执行。cpv-agent.md 描述了入口 agent 的角色与工具使用范围。
• commands/ — 暴露给用户的斜杠命令；cpv-main-menu.md 提供主菜单式 UX，cpv-remote-validate.md 则是对远端产物做严格校验的入口。
• scripts/ — 真正干活的 Python 库与 CLI；cli.py 提供注册式子命令，manage_plugin.py 负责本地插件装配，publish.py 是上游「canonical pipeline」模板化的发布脚本，cpv_validation_common.py 给出跨命令共享的校验原语，skillaudit.py 是一个独立的子审阅器。
• .github/workflows/ — GitHub Actions，其中 release.yml 把「build → validate → publish」三步串成 release。
• pyproject.toml — 声明 Python 端依赖与入口点。

资料来源：pyproject.toml:1-40，.github/workflows/release.yml:1-60。

2. 三大组件图：CLI、Commands、Agent

CPV 的运行时被刻意拆成三层，使校验既能由人类斜杠命令触发，也能由 Claude agent 直接驱动。

flowchart LR
    A[commands/cpv-main-menu.md] --> B[scripts/cli.py]
    A2[commands/cpv-remote-validate.md] --> B
    C[agents/cpv-agent.md] --> B
    B --> D[scripts/manage_plugin.py]
    B --> E[scripts/publish.py]
    B --> F[scripts/cpv_validation_common.py]
    E --> F
    G[scripts/skillaudit.py] --> F
    H[GitHub Actions release.yml] --> B
    H --> E

• CLI 层 (scripts/cli.py)：注册式分发器，把 --strict、--gate 等开关路由到具体 validator。社区 #179 指出，被 publish.py 调用的 run() 包装器把 timeout=300 硬编码到了所有子命令，对大型 pytest 套件明显不够。
• 斜杠命令层 (commands/)：把 CLI 重新包装成 Claude Code 可识别的自然语言入口；cpv-main-menu 负责导航，cpv-remote-validate 负责严格模式。
• Agent 层 (agents/cpv-agent.md)：当 Claude 在 CI preflight 中需要「自带判定」时，自动选择校验策略，并解释 MAJOR/NIT/NONE 三档严重度。

资料来源：scripts/cli.py:1-80，commands/cpv-main-menu.md:1-30，commands/cpv-remote-validate.md:1-30，agents/cpv-agent.md:1-40。

3. 共享原语与子审阅器

cpv_validation_common.py 是所有 validator 的「底座」：它定义 frontmatter 解析、文件作用域过滤、评分分级、以及被 bandit / ruff / pytest 共同依赖的常量。社区 #172 指出，这个文件里的某些数据常量会被 bandit B108 命中，并因此让所有 publish.py --gate 走不通，说明它确实被多个 Python 脚本共享。

skillaudit.py 是 CPV 内置的反注入审计器，关注文件系统类与 agent 操作类两类反模式。它的输出遵循 skillaudit:<分类> <规则> 形式，例如 skillaudit:filesystem FS_WRITE（#177）与 skillaudit:agent_manipulation MCP_SCHEMA_POISON（#178）。该子审阅器与 cpv-remote-validate 共享同一份 NONE/NIT/MAJOR 严重度语义。

资料来源：scripts/cpv_validation_common.py:1-60，scripts/skillaudit.py:1-80。

4. Canonical Pipeline 与发布闭环

「Canonical pipeline」是 CPV 把它对 *自己* 用的发布流程模板化后，开放给下游插件复用。它本身由 scripts/publish.py 实现，并由 .github/workflows/release.yml 在每次 tag 时触发。流程是：build → validate → publish。

但社区已经记录该闭环的几处真实缺陷：

• #180：validate 阶段在 ubuntu-latest 上挂死约 25–30 分钟，最终被 runner 自身超时杀；它发生在 build 成功之后（4s），因此与冷编译无关，release 会带着缺失资产发出去。
• #175：publish.py 升级时会被整体重生成（3,492 行），旧的「Rust + shell」门禁被静默丢弃，意味着插件作者若用 Rust 组件，没有任何 gate 拦住它。
• #176：--strict 范围过宽，把 project-memory/、测试 fixture、甚至 gitignored 文件都纳入了校验，导致 CI 永远红。
• #179：通用 run(timeout=300) 让 pytest gate 事实上不可满足。

因此读懂仓库结构的同时，也必须理解 *canonical pipeline 是模板*：它把 CPV 暴露的 BP 同等地应用到下游插件，而这些 issue 集中在「别让模板反过来咬自己」。

资料来源：scripts/publish.py:1-80，.github/workflows/release.yml:1-60。

概述与定位

Claude Plugins Validation (CPV) 是一套以 Python CLI 为核心、面向 Claude Code 插件的验证流水线。其"Pipeline & CLI Architecture"由两层组成：用户可见的命令行入口（cpv-remote-validate / cpv batch），以及背后被消费方模板化的"canonical pipeline"（即 scripts/publish.py）。CLI 负责把单插件或批插件树送入校验、skillaudit、SARIF 输出等阶段；canonical pipeline 则把这些阶段编排进 GitHub Actions 的 build / validate / publish 步骤，供所有下游插件统一复用。

资料来源：scripts/remote_validation.py:1-40 scripts/publish.py:1-80

CLI 入口与子命令

CLI 的对外形态是一个 argparse 风格的入口脚本，它把"远程单插件校验"和"批处理编排"分成独立子命令：

• cpv-remote-validate plugin <path> [--strict]：针对单个插件目录做端到端校验；--strict 会提升发现等级（CRITICAL / MAJOR / NIT）并触发 ci-preflight 评分。
• cpv batch：进入批处理编排模式，由 cpv_batch_orchestrator.py 负责分派、cpv_batch_aggregator.py 负责汇总。
• cpv remote-validate：CI 中调用同一组核心校验逻辑的远程包装形态。

通用共享（参数解析、错误码、SARIF 写入路径协商、日志格式）集中在 cpv_validation_common.py，所有子命令都从这里导入，以保证 CLI 与批处理两条路径行为一致。

资料来源：scripts/remote_validation.py:41-120 scripts/cpv_validation_common.py:1-60

流水线阶段（canonical pipeline）

canonical pipeline 在 scripts/publish.py 中被固化为多阶段流水线，典型顺序如下：

每一阶段都通过一个共享的 run(cmd) 帮助函数包装 subprocess 调用；该函数硬编码 timeout=300（#179 中已明确指出这与"真实 pytest 套件"不匹配），所有阶段继承同一个超时阈值。

资料来源：scripts/publish.py:1-120 scripts/publish.py:run():120-180

批处理编排与 SARIF 汇聚

cpv_batch_orchestrator.py 与 cpv_batch_aggregator.py 共同构成"多插件并行校验"的子流水线：

• orchestrator：把目标列表切分成 worker，分发到子进程 / 线程；v3.23.1 的修复明确指出"进度标记必须由 dispatcher 而不是 worker 线程发出"，说明早期实现存在进度信号被埋在子线程、导致 CI 卡顿的隐患。
• aggregator：把每个 worker 的 JSON 结果汇聚成统一报告，并由 cpv_sarif_writer.py 转写成 SARIF 2.1.0，供 GitHub Code Scanning 渲染。

批处理与单插件模式共用同一组 detector；aggregator 还会做一次等级去重与跨插件交叉抑制，避免重复告警。这一层与 canonical pipeline 解耦，因此 --strict 与 batch 模式可独立开关。

资料来源：scripts/cpv_batch_orchestrator.py:1-80 scripts/cpv_batch_aggregator.py:1-80 scripts/cpv_sarif_writer.py:1-60

已知架构痛点与权衡

社区已暴露数条与 Pipeline & CLI 紧密相关的痛点：

• validate 阶段卡死 25–30 分钟（#180）：build 已 4s 成功，但 validate 阶段被 timeout 上限杀死；根因不是冷启动，而是 canonical pipeline 对 pytest / bandit 的超时模型假设过紧。
• run() 硬编码 300 秒（#179）：任何走 run() 的子命令都共享同一超时，pytest 调用点无法独立放大——这是"通用 helper 误吞语义"的典型反模式。
• --strict 范围过宽（#176）：会扫到 project-memory/、测试夹具以及 .gitignore 中的非发布文件，说明 strict 模式与"shippable surface"的概念没有在管线中显式区分。
• regen 静默丢步（#175）：从语言无关模板重新生成 scripts/publish.py 时，Rust / shell 的门控步骤会被整体剥离，说明模板与插件语言检测没有强耦合。
• vendoring 自伤（#172）：cpv_validation_common.py 自身数据常量触发 bandit B108，导致所有把它 vendor 进自己仓库的插件在自身 publish.py --gate 里失败——这是 canonical pipeline"既当裁判又当运动员"的结构性冲突。

资料来源：scripts/publish.py:run():120-180 scripts/remote_validation.py:strict-scope:80-160 scripts/cpv_validation_common.py:1-60

概述与设计目标

Validation Engines 是 Claude Plugins Validation (CPV) 项目的核心检测层，由 **25 个独立 validate_*.py 脚本与 190+ 条规则**组成，覆盖 Claude Code 插件在结构、Skill/MCP/Hook 契约、安全模型、市场分发元数据等所有可机校验维度。cpv-remote-validate plugin . --strict 是其主入口，CI 发布流水线 scripts/publish.py --gate 复用同一规则集作为发布门槛。Engine 在设计上遵循"单一职责 + 共享 registry"原则：每个脚本只负责一类资源（plugin、skill、hook、marketplace…），严重等级、退出码、报告格式则由 cpv_validation_common.py 统一管理。 资料来源：scripts/validate_plugin.py、scripts/cpv_validation_common.py

架构与执行流水线

25 个 validate_*.py 共享 cpv_validation_common.py 中的规则注册器（registry）、严重等级（NIT / MAJOR / CRITICAL）与退出码策略。每个脚本遵循三段式：发现（discover）→ 规则评估（evaluate）→ 报告汇聚（report / aggregate）。validate_plugin.py 作为顶层 orchestrator，决定调用哪些子 validator；skillaudit 作为横切安全审计模块，被 validate_security.py 与 --strict 集成。

flowchart TD
    A[cpv-remote-validate plugin . --strict] --> B[validate_plugin.py<br/>orchestrator]
    B --> C[validate_skill.py]
    B --> D[validate_hook.py]
    B --> E[validate_marketplace.py]
    B --> F[validate_local_scope.py]
    B --> G[validate_frontmatter.py]
    B --> H[validate_security.py]
    H --> I[skillaudit.py<br/>FS_WRITE / MCP_SCHEMA_POISON / injection]
    C --> J[cpv_validation_common.py<br/>registry + severity + exit code]
    D --> J
    E --> J
    F --> J
    G --> J
    H --> J
    J --> K{exit code 0/1/2}
    K -->|publish gate| L[scripts/publish.py]

资料来源：scripts/validate_plugin.py、scripts/validate_security.py、scripts/skillaudit.py

规则分类与典型条目

190+ Rules 按资源域归类：

• 结构与清单：validate_plugin.py / validate_marketplace.py 校验 marketplace.json、plugin.json 必备字段、版本与依赖一致性，对应 #175 提出的"按语言门控 Rust + shell"诉求。
• Skill / Hook 契约：validate_skill.py 与 validate_hook.py 校验 frontmatter 已知字段、事件名、命令路径；validate_frontmatter.py 维护已知字段白名单，#173 报告 Claude Code v2.1.218 新增的 background 字段尚未识别。
• 作用域与边界：validate_local_scope.py 控制 --strict 仅扫描 shippable 表面，#176 指控当前实现误扫 project-memory、测试 fixture 与 .gitignore 文件。
• 安全审计：validate_security.py + skillaudit 覆盖 4 大类检测器（agent_manipulation、filesystem、injection、schema_poison），是 MAJOR 的主要来源；#177、#178 即属此类误报。
• 通用数据常量：cpv_validation_common.py 内置路径/正则常量，#172 指出其触发 bandit B108，使所有 vendoring 插件的 publish.py --gate 失败。

资料来源：scripts/validate_skill.py、scripts/validate_local_scope.py、scripts/skillaudit.py、scripts/validate_frontmatter.py

严重等级、超时与社区反馈

引擎统一返回三档严重级：NIT（不阻塞）、MAJOR（--strict 阻塞）、CRITICAL（任何模式阻塞）。scripts/publish.py 的 run() helper 对所有子命令硬编码 timeout=300，#179 指控该值不足以运行真实 pytest 套件，#180 进一步报告 CPV validate 在 ubuntu-latest 上挂死 25–30 分钟后被自动 kill，导致带空资产的 release 漏出。修复方向集中在三方面：按域拆分超时（#179/#180）、放宽 skillaudit 对反注入 guardrail 的识别（#170）、--strict 显式排除非 shippable 路径（#176）。

资料来源：scripts/publish.py、scripts/validate_security.py

概述与职责

skillaudit 子系统是 CPV（Claude Plugins Validation）安全扫描层的核心，专注于审查插件中可能改变 Agent 行为的代码与文档片段——也就是「会被 Agent 作为指令加载」的内容。其职责覆盖两类风险：

1. 依赖型漏洞：通过 scripts/cpv_snyk_agent_scanner.py 调用 Snyk 扫描第三方依赖中的已知 CVE。
2. 逻辑型风险（agent-context writers）：通过 skillaudit 原生检测器扫描插件自身代码，识别会向 agent 上下文写入可疑内容的能力组件——参见 Issue #174 对该类风险的定义。

整套扫描被 scripts/validate_security.py 作为顶层编排脚本纳入 cpv-remote-validate 流程，并支持 --strict 模式以提升某些 NIT 等级（参见 Issue #170）。

资料来源：scripts/validate_security.py:1-1

检测器与上下文分类

原生入口 scripts/cpv_skillaudit_native.py 根据文件类型路由到三个上下文提取器，每个提取器负责判断「该行是否真的在被执行/注入」，从而为后续 FP 降级提供依据：

上下文提取器输出的「行级语义标签」（CODE / PROSE / FRONTMATTER / COMMENT 等）是 FP 降级的核心输入。Issue #177 中 FS_WRITE 在 shell 注释里被误报为 MAJOR，正是因为缺少对 PROSE 行的语义降级。

资料来源：scripts/cpv_skillaudit_native.py:1-1, scripts/_skillaudit_shell_context.py:1-1

FP-handling 流水线

下面是检测器命中后到最终入库的流水线：

flowchart LR
    A[扫描文件] --> B{按扩展名路由}
    B -->|*.py| C[Python 上下文]
    B -->|*.sh| D[Shell 上下文]
    B -->|*.md| E[Markdown 上下文]
    C --> F[检测器匹配<br/>如 FS_WRITE / MCP_SCHEMA_POISON]
    D --> F
    E --> F
    F --> G{语义标签 = PROSE?}
    G -->|是| H[降级为 NIT<br/>demoted, needs review]
    G -->|否| I{是 --strict?}
    I -->|是| J[保留原等级]
    I -->|否| K[按默认阈值过滤]
    H --> L[写入报告]
    J --> L
    K --> L

关键节点说明：

• PROSE 降级：Issue #177 中 bash 注释内提到 ~/.zshrc 即被识别为 PROSE 行，命中 skillaudit:filesystem FS_WRITE 后降级为 NIT（demoted, needs review）。
• frontmatter 例外：Issue #178 表明 MCP_SCHEMA_POISON 在 wikimem memory-note 的 description: 字段同样走 PROSE 路径；Issue #173 中 CC v2.1.218 的合法 background 字段若被识别为 FRONTMATTER 而非未定义字段，亦可避免误报。
• 能力 vs 实时分离：Issue #174 要求「capability vs live」分别打分，扫描器需区分「具有写入能力」与「运行时实际写入」两类信号。

资料来源：scripts/cpv_skillaudit_native.py:1-1, scripts/_skillaudit_markdown_context.py:1-1

已知限制与社区共识

根据近期 issue 追踪，该 FP-handling 流水线仍存在以下已公开的限制：

• 被自身 gate 反伤：scripts/cpv_validation_common.py（不在本页直接列出，但与 validate_security.py 同源）会触发 bandit B108，阻断每个 vendoring 该文件的插件的 --gate（Issue #172）。
• 扫描范围过宽：Issue #176 指出 --strict 模式会把 project-memory、test fixtures、gitignored 内容一并送入扫描器，导致大量与可分发插件无关的命中。
• 回溯破坏绿色发布：Issue #170 报告了 4 个检测器把「防御性反注入护栏」反判为注入，NIT 等级在 --strict 下会卡住历史已通过的发布。
• 超时门不可达：Issue #179 显示 publish.py 的 run() 助手硬编码 timeout=300，真实测试套件无法在 300 秒内完成——这是上游流水线问题，但与 validate_security.py 在同一条 gate 链路上。

运维建议：在 CI 中启用 skillaudit 前，应先用 --strict 在本地跑一遍 cpv-remote-validate plugin .，对被降级为 NIT 的 PROSE 命中逐条确认是否为真实的写入意图。

资料来源：scripts/validate_security.py:1-1, scripts/cpv_snyk_agent_scanner.py:1-1

AI Agents — Routing、Diagnose、Fix、Devitalize、Harden

概述与角色分工

CPV（Claude Plugins Validation）通过一组分工明确的 AI Agent 协作完成插件生命周期的关键环节。cpv-agent 作为总入口与路由层（router），根据用户调用的子命令（例如 cpv-validate、cpv-fix、cpv-remote-validate）将工作分派给对应的专业 Agent。这些专业 Agent 之间通过解耦的职责（诊断 / 修复 / 失效化 / 加固）形成流水线，使得每个阶段都能被独立运行或组合运行。资料来源：agents/cpv-agent.md

路由与编排（Routing）

cpv-agent 是整个 Agent 体系的入口和分发器。最新发布 v3.23.1 中专门标注：「orchestrator: Emit progress markers from the dispatcher, not worker threads」，说明路由层的职责已经明确：分发器（dispatcher）负责把任务投递给 worker，并把进度标记（progress marker）打印回主线程，而 worker 线程不再直接对外暴露进度事件。这一改动避免了多个 worker 并行执行时进度信号互相覆盖的问题。资料来源：agents/cpv-agent.md

在实际使用中，路由层处理两类主要信号：用户通过命令行传入的子命令，以及验证阶段产出的 cpv_validation 报告对象。当报告对象的严重级别超过预定义阈值时，路由层不会再次执行 validator，而是直接分派 diagnoser 进行根因分析；如果用户在同一会话中显式调用 --apply-fix，路由层则把上下文传给 fixer Agent。资料来源：agents/cpv-agent.md:1-120

诊断与修复（Diagnose → Fix）

诊断与修复是紧密耦合的两阶段：diagnoser 读取 validator 产出的结构化报告，使用一套独立于检测器的规则来识别「同一根因引发的多条命中」。例如 issue #177 和 #178 中描述的 skillaudit:filesystem FS_WRITE 与 skillaudit:agent_manipulation MCP_SCHEMA_POISON 误报，都属于 PROSE（说明文本）触发的同一类问题；diagnoser 应识别这种「词法相似但语义无关」的模式，避免它们被分别提交给 fixer 重复处理。资料来源：agents/cpv-plugin-diagnoser-agent.md:1-80

fixer Agent 接受 diagnoser 输出的「可操作子集」，每一项都附带修复策略（如「移除文件写入指令」「将 description: 字段重写为不含命令语法」）。它的执行边界是：只对 MAJOR 且修复成本低于风险扩散成本的问题自动应用补丁；其余条目生成候选补丁并交回用户审阅。这一设计呼应 issue #176 中 --strict 模式误把非交付文件纳入校验范围的问题——fixer 在应用前会校验目标文件确实属于发布产物树。资料来源：agents/cpv-plugin-fixer-agent.md:1-100

失效化与加固（Devitalize → Harden）

失效化（devitalize）与加固（harden）是相互独立的"防御层"。cpv-plugin-devitalizer-agent 的目标是：识别仍以可执行形式（如保留的脚本、可被外部触发的 hook）存在于仓库中、但已经不应再被激活的组件，并把它们的入口点替换为「no-op stub + 弃用日志」。常见触发来自 issue #175 中所述的场景：当 canonical pipeline 重生成 publish.py 后，原本应由语言无关模板承担的工作被静默丢弃，导致遗留在旧产物路径下的旧脚本仍可被 CI 调用。资料来源：agents/cpv-plugin-devitalizer-agent.md:1-60

cpv-plugin-leaks-preventer-agent（亦即 harden）关注的是凭据、令牌与抗注入加固。它的工作集合与 issue #170 描述的「防御性反注入护栏被自身告警为注入」密切相关：harden Agent 通过白名单机制保护合规的反注入模板不被 skillaudit 误报命中。它同时承担 issue #172 的工作：检查 cpv_validation_common.py 等被多个插件 vendored 的常量文件，确保其中声明的硬编码值不会触发 bandit 等下游安全门禁。资料来源：agents/cpv-plugin-leaks-preventer-agent.md:1-90

端到端工作流

flowchart LR
  U[用户/CLI] --> R[cpv-agent<br/>路由层]
  R --> V[validator-agent]
  V -- 报告 --> D[diagnoser-agent]
  D -- 可操作项 --> F[fixer-agent]
  D -- 不可修复 --> X[devitalizer-agent]
  R -- 加固请求 --> H[leaks-preventer<br/>harden-agent]
  V -. 严重级别 .-> R

需要注意的是，harden 步骤在路由层中是可选的、需要用户显式触发的分支，它并不位于常规 validate → diagnose → fix 链路上；而 devitalize 既可由路由层在诊断后自动派发，也可由用户在维护旧插件时手动调用。这种"可选分支 + 默认流水"的组合，是 CPV 在 issue #179（run() 超时常数）与 issue #180（validate 步骤长时挂起）等已知瓶颈之间保持灵活性的关键设计。资料来源：agents/cpv-plugin-validator-agent.md agents/cpv-plugin-devitalizer-agent.md

概述与定位

Skill Catalog（技能目录）与 Skills Menu（技能菜单）是 Claude Plugins Validation（CPV）插件的导航中枢。当 Claude 在插件树中运行 cpv-remote-validate plugin . --strict 或本地调用 cpv-validation 时，agent 需要一个统一的入口来发现、按需加载并分发到对应的子技能。

cpv-the-skills-menu/SKILL.md 作为顶层入口技能，定义了"技能菜单"的概念：当被触发时，它会枚举当前插件中所有以 cpv- 为前缀的 SKILL.md 文件，并据此构建出一个可被 agent 逐步消费的执行清单。资料来源：skills/cpv-the-skills-menu/SKILL.md:1-20

cpv-main-menu-skill/SKILL.md 则提供了菜单的骨架与渲染规则，声明菜单项的排序、描述字段与每个技能职责的简短摘要。它与 cpv-the-skills-menu 的区别在于：cpv-the-skills-menu 偏向"运行时调度"，cpv-main-menu-skill 偏向"用户视角的导航结构"。资料来源：skills/cpv-main-menu-skill/SKILL.md:1-15

目录结构与菜单树

技能菜单的组织由 references/menu-tree.md 与 references/skills-catalog.md 两个参考文件协同描述。menu-tree.md 用树状结构呈现技能之间的父子关系与触发顺序，skills-catalog.md 则以表格形式列出每个技能的路径、职责摘要与适用阶段。资料来源：skills/cpv-the-skills-menu/references/skills-catalog.md:1-25、资料来源：skills/cpv-main-menu-skill/references/menu-tree.md:1-30

下表是该菜单树的精简视图：

资料来源：skills/cpv-main-menu-skill/references/menu-tree.md:5-40

关键子技能角色

cpv-plugin-validation-skill 是菜单树的"校验叶子节点"。当被选中时，它会驱动 agent 调用 CPV 的远程校验脚本并收集结构化报告。资料来源：skills/cpv-plugin-validation-skill/SKILL.md:1-25

cpv-fix-validation 是与之配对的"修复叶子节点"，接收 cpv-plugin-validation-skill 产出的报告，按等级（MAJOR/NIT 等）给出处置策略。值得注意的是，社区曾反馈 skillaudit 在多处产生误报（如 #177 的 FS_WRITE 与 #178 的 MCP_SCHEMA_POISON），这恰恰是 cpv-fix-validation 需要消解的场景。资料来源：skills/cpv-fix-validation/SKILL.md:1-30

与已知问题的关联

菜单中部分技能的行为直接受到社区工单影响：

• #176（--strict 范围）：cpv-plugin-validation-skill 在严格模式下会扫到非可发布的追踪内容（如项目记忆与测试夹具），需要菜单引导用户进入"修复 → 排除非可发布产物"的子路径。资料来源：skills/cpv-fix-validation/SKILL.md:15-30
• #173（frontmatter background 字段）：校验技能尚未识别 CC v2.1.218 新增字段，cpv-fix-validation 应在补丁流程中加入白名单扩展步骤。资料来源：skills/cpv-plugin-validation-skill/SKILL.md:10-20

使用建议

对于首次接触 CPV 的开发者，建议遵循菜单的"根入口 → 主菜单 → 校验 → 修复"四级路径：

1. 通过 cpv-the-skills-menu 触发完整枚举；
2. 由 cpv-main-menu-skill 渲染选项并选择目标场景；
3. 执行 cpv-plugin-validation-skill 获取原始报告；
4. 在 cpv-fix-validation 中按等级分诊 MAJOR 与 NIT。

若遇到菜单未覆盖的新增字段或新误报模式，应在 references/skills-catalog.md 中追加条目并扩展对应子技能的处置逻辑，以保持目录与实际能力同步。资料来源：skills/cpv-the-skills-menu/references/skills-catalog.md:30-60

Canonical Pipeline、publish.py 与 CI/CD

概述与设计目标

Claude Plugins Validation（CPV）的 Canonical Pipeline 是一套面向 Claude Code 插件发布场景的可复用 CI/CD 模板，由 scripts/publish.py 主脚本、cpv-remote-validate 严格模式评分以及 GitHub Actions 工作流模板共同组成。其核心目标是不强迫每个下游插件自研发布脚手架，而是通过 "vendoring" 模式把 CPV 的等级评定、门禁校验与版本发布能力原样搬运到插件仓库。最新 v3.23.1 修复了 orchestrator 进度标记只能由 dispatcher 而非 worker 线程打印的问题，保证 CI 日志可观测性 资料来源：CHANGELOG.md:1-20。

流水线阶段与脚本职责

Canonical Pipeline 在 templates/github-workflows/validate-marketplace.yml 中被实例化为 GitHub Actions 任务，主要阶段包括：环境引导、marketplace 数据校验、CPV 严格模式预检、与上一标签的差异比对以及最终发布。各阶段的代码实现分布在下列脚本中：

资料来源：templates/github-workflows/validate-marketplace.yml:1-80, scripts/validate_marketplace_pipeline.py:1-60。

publish.py 设计约束与已知问题

publish.py 是从 language-generic 模板再生的语言特定脚本，体积约 3492 行。社区已经反馈三处与其直接相关的缺陷：

1. 超时硬编码（issue #179）：内嵌的 run() 通用助手把 timeout=300（约 5 分钟）作用到所有子进程，两个 pytest 调用点直接继承，对真实测试套件构成不可满足的门 资料来源：scripts/publish.py:1-200。
2. 语言 gate 静默丢失（issue #175）：当插件携带 Rust 或 shell 组件时，§1–§5 升级会从通用模板整体再生 publish.py，并丢弃语言专属 gate，因此需要在 setup_plugin_pipeline.py 中按插件声明的语言选择性注入 资料来源：scripts/setup_plugin_pipeline.py:1-120。
3. bandit B108 自触发（issue #172）：vendored 的 cpv_validation_common.py 数据常量命中 bandit B108，导致下游任何调用 publish.py --gate 的插件都被阻断，必须把硬编码临时目录替换为 tempfile 动态生成 资料来源：scripts/cpv_ci_preflight.py:1-80。

CI/CD 集成与社区反馈

Canonical Pipeline 在 ubuntu-latest 上的执行流如下，CPV 构建阶段（~4 秒）与 validate 阶段（被自身超时杀死）形成鲜明对比，这正是 issue #180 报告的"挂起 25–30 分钟后超时、最终发布缺失资产"的根因：

flowchart LR
    A[push / tag] --> B[setup_plugin_pipeline.py]
    B --> C[validate_marketplace_pipeline.py]
    C --> D[cpv_ci_preflight.py<br/>cpv --strict]
    C --> E[cpv_ci_parity_checks.py]
    D --> F{publish.py --gate}
    E --> F
    F -->|通过| G[Release Assets]
    F -->|失败| H[阻断发布]

针对上述问题，操作建议如下：升级到 v3.23.x 后应观察 orchestrator 进度标记是否由 dispatcher 正确输出 资料来源：CHANGELOG.md:1-20；在 vendoring 前确认 cpv_validation_common.py 与本仓库 bandit 配置不会因 B108 互相影响，必要时在 CI 中加 bandit --skip B108 过滤 资料来源：scripts/cpv_ci_preflight.py:1-80; 若插件携带 Rust / shell 组件，需在再生逻辑外手工补齐对应 gate 以避免 #175 的静默丢失 资料来源：scripts/setup_plugin_pipeline.py:1-120。

Batch、Fleet 与并行操作

本页描述 CPV（Claude Plugins Validation）面向 批量（Batch）/多插件舰队（Fleet）校验与并行扫描的子系统，对应 scripts/ 目录下一组以 cpv_batch_* 与 cpv_parallel_* 命名的脚本。该子系统既支撑 cpv-remote-validate plugin . 这类单插件入口，也支撑 canonical 发布流水线 (scripts/publish.py) 在 CI 上对 marketplace 下全部插件同时执行 validate 步骤。v3.23.1 中修复的"编排器进度标记必须由调度器线程发出，而非工作线程"（"orchestrator: Emit progress markers from the dispatcher, not worker threads"）即直接落在本子系统范围内 资料来源：scripts/cpv_batch_orchestrator.py:1-200。

一、设计目标与适用场景

目标：把"对 N 个插件逐一串行调用 CPV"改为"输入清单 → 规划 → 并行分发 → 聚合报告"，从而：

1. 在 CI 上把 validate 墙钟时间从 Σ(t_plugin) 降为接近 max(t_plugin)（依赖并发槽数）；
2. 在跨多仓 / marketplace 多插件场景下提供一致的退出码与汇总报告（scripts/cpv_batch_aggregator.py:1-150）；
3. 给 cpv-remote-validate 与 cpv --gate 复用同一份调度原语，避免在 publish.py 里重复实现 run()（参见 issue #179 中关于 timeout=300 硬编码造成的不可满足测试门控 资料来源：scripts/cpv_batch_orchestrator.py:80-260）。

典型用户：

• canonical pipeline 维护者（ai-maestro-janitor、ai-maestro-plugin 等），需要在 release CI 中一次校验整个 marketplace（scripts/cpv_marketplace_input.py:1-120）；
• mono-repo 内的多插件舰队 owner，希望按提交触发的增量子集做并行校验（scripts/cpv_batch_planner.py:1-180）。

二、模块组成与职责切分

资料来源：scripts/cpv_marketplace_input.py:1-120、scripts/cpv_batch_planner.py:1-180、scripts/cpv_parallel_runner.py:1-200、scripts/cpv_scan_supervisor.py:1-160、scripts/cpv_batch_aggregator.py:1-150。

三、典型执行工作流

flowchart LR
  A[marketplace.json / 插件清单] --> B[cpv_marketplace_input.py]
  B --> C[cpv_batch_planner.py]
  C --> D[cpv_batch_orchestrator.py dispatcher]
  D -->|fan-out| W1[worker: parallel_runner]
  D -->|fan-out| W2[worker: parallel_runner]
  D -->|fan-out| W3[worker: parallel_runner]
  W1 --> S[cpv_scan_supervisor.py 超时/取消]
  W2 --> S
  W3 --> S
  S --> E[cpv_batch_aggregator.py]
  E --> F[汇总报告 + 退出码]

关键执行约束：

• 进度标记一律由 dispatcher 线程发出，worker 不得直接写 stdout/stderr；这是 v3.23.1 的修订点，目的是避免并发输出交错导致 CI 日志错位 资料来源：scripts/cpv_batch_orchestrator.py:80-260。
• 超时由 cpv_scan_supervisor.py 集中管理，单插件默认上界与 publish.py 中 run(timeout=300) 的硬编码值解耦，从而修复 issue #179 提出的"测试门控不可满足"问题 资料来源：scripts/cpv_scan_supervisor.py:1-160`。
• 范围严格限定为 shippable 清单项；--strict 模式下不应进入 project-memory、tests/fixtures/、.gitignore 路径（issue #176 的修复同样依赖 planner 的过滤能力 资料来源：scripts/cpv_batch_planner.py:120-260。

四、已知问题与社区反馈

本子系统与多个高优先级 issue 直接相关：

• #180 validate 步骤在 ubuntu-latest 上挂死 25–30 min 后被自设上限 kill，原因是 orchestrator 内部出现锁竞争 / worker 不退出；cpv_scan_supervisor.py 的超时回收路径是主要嫌疑点 资料来源：scripts/cpv_scan_supervisor.py:80-200`。
• #179 publish.py run() 把 timeout=300 写死，会通过 canonical regen 反向污染所有 vendoring 的插件；建议让 orchestrator 接管 timeout 注入，让 cpv_batch_aggregator 输出"建议超时"而非硬限 资料来源：scripts/cpv_batch_aggregator.py:60-180`。
• #175 canonical pipeline 的 regen 在升级 §1–§5 时整段重写 publish.py，导致 Rust/shell 门控被静默丢弃；cpv_batch_planner.py 应作为单一真相源，把"哪些插件携带 Rust/shell"暴露给下游 资料来源：scripts/cpv_batch_planner.py:200-320`。

1. 概述与适用范围

本页整理 CPV (Claude Plugins Validation) 在 --strict / ci-preflight 模式及规范管道 (canonical-pipeline) 中已观测到的误报、失效模式与社区报告的缺陷。所有条目均来自公开 issue 与源码中的检测/分类模块；目的是帮助用户区分「真实风险」与「CPV 已知误报」，避免绿色发布被误判阻断。误报分类的核心实现位于 cpv_fp_classifier.py 与 cpv_fp_classifier_rules.py，它们配合 cpv_pattern_source_predicate.py 判断命中的模式来源（PROSE/CODE/TEST），并由 cpv_re2_matcher.py 完成实际的正则匹配。资料来源：scripts/cpv_fp_classifier.py:1-120 scripts/cpv_pattern_source_predicate.py:1-80

2. 常见误报类别

2.1 skillaudit:filesystem FS_WRITE 误报

在参考性安装文档（含 ~/.zshrc 等 shell 路径的 bash 注释）上误报 MAJOR 级 FS_WRITE。该命中本质是 PROSE 文本描述，而非可执行代码。cpv_fp_classifier_rules.py 中以「source_predicate == PROSE」作为降级规则的一类输入。社区对应 issue #177 与 #156 同类。资料来源：scripts/cpv_fp_classifier_rules.py:45-110 scripts/cpv_inplugin_write_guard.py:30-95

2.2 skillaudit:agent_manipulation MCP_SCHEMA_POISON 误报

在 wikimem memory-note 的 description: frontmatter 字段上误报 NIT 级（已降级但仍需审核）MCP_SCHEMA_POISON。同样属于 PROSE 类描述。issue #178、#177、#156 形成一族「描述性文本触发注入检测器」的问题。资料来源：scripts/cpv_fp_classifier.py:200-280 scripts/cpv_re2_matcher.py:1-60

2.3 防御性反注入护栏被当作注入

skillaudit 的四条检测器在扫描自身或下游插件的「防御性反注入护栏代码」时将其判为攻击载荷，导致 --strict 在 NIT 级阻断本应通过的发布。issue #170 报告了该回归式误报。资料来源：scripts/cpv_fp_classifier_rules.py:120-180

2.4 Unknown frontmatter field 误报

CC v2.1.218 引入的合法字段 background 未被识别，报 [WARNING] Unknown frontmatter field 'background'。issue #173 记录；属于字段白名单未及时同步。资料来源：scripts/cpv_pattern_source_predicate.py:90-140

3. 管道与作用域失效模式

4. 检测覆盖与已知盲点

• 仅扫描插件树本身，对依赖（vendored 库、transitive deps）中可能写入 agent 上下文的组件不评分（issue #174）。cpv_scan_cache.py 的缓存粒度以文件哈希为单位，尚未跨依赖边界。资料来源：scripts/cpv_scan_cache.py:1-70
• 「能力 vs 实时」未分离评分：检测器在静态扫描阶段只能看到能力签名，无法确认运行时是否真的被加载。资料来源：scripts/cpv_inplugin_write_guard.py:100-160

5. 缓解与上报建议

1. 在 CI 中先用 cpv-remote-validate plugin . --no-strict 收集原始命中，再以 cpv_fp_classifier 输出降级结果区分 PROSE/CODE。资料来源：scripts/cpv_fp_classifier.py:60-140
2. 复用 publish.py 时覆写 run() 的 timeout 参数（或 monkey-patch），避免继承 300s 上限（issue #179）。
3. 对 --strict 范围异议，按 issue #176 的模式补充 .cpvignore 或白名单到 cpv_pattern_source_predicate.py。
4. 复现到 issue 时附上命中级别（MAJOR/NIT）、来源类别（PROSE/CODE）、与最小复现插件树，便于在 cpv_fp_classifier_rules.py 中新增规则。

最新发布 v3.23.1 (2026-07-28) 已修复调度器从工作线程发出进度标记的问题，但本节列出的误报与失效模式截至该版本仍部分未闭合。

概述

claude-plugins-validation（CPV）提供了一组命令行脚本，覆盖 Claude Code 插件与 marketplace 在整个生命周期中的关键治理动作：结构标准化（standardize）、格式迁移（migrate）、成员管理（manage）、打包分发（pack） 与 剥离调试文件（strip）。这些脚本共同保证仓库内的 plugin 与 marketplace 树在签名、frontmatter、缓存与可发布内容上保持一致，避免下游验证（如 --strict、cpv-remote-validate plugin .、canonical pipeline）误报或漏报。社区反馈显示：canonical pipeline 重新生成 publish.py 时会"默默丢弃"插件自带的 Rust/Shell 资产（[#175]），--strict 模式会把项目记忆、测试夹具等非可发布文件一并纳入扫描（[#176]），这些行为均与本主题描述的"标准化-迁移-缓存"治理面紧密相关。

插件级标准化（standardize_plugin.py）

scripts/standardize_plugin.py 是面向单个插件树的入口。它校验并修正 Claude Code 插件约定：commands/agents/skills/hooks 的目录布局、.claude-plugin/plugin.json 的元数据、以及 frontmatter 字段集合。脚本内部按"读取现状 → 计算差异 → 落盘修正"的阶段推进，并在差异中区分 *警告* 与 *自动修复*。当下游验证遇到 Unknown frontmatter field 'background'（社区问题 [#173]）时，说明该脚本的字段白名单尚未与 Claude Code v2.1.218 同步，需要在此处增补。

[WARNING] Unknown frontmatter field 'background'

资料来源：scripts/standardize_plugin.py:1-40 资料来源：scripts/standardize_plugin.py:120-180

Marketplace 迁移与标准化

migrate_marketplace.py

scripts/migrate_marketplace.py 负责把旧形态的 marketplace 清单（marketplace.json 早期 schema、扁平结构、缺 metadata owner 字段等）迁移到当前 schema。它在迁移前先做只读 diff，让维护者人工确认后再写入；批量重写时保持 ID/版本字段稳定，避免破坏下游 cache key。资料来源：scripts/migrate_marketplace.py:1-60 资料来源：scripts/migrate_marketplace.py:90-160

standardize_marketplace.py

scripts/standardize_marketplace.py 与 standardize_plugin.py 互补，作用于整个 marketplace：排序插件条目、统一 owner 字段、补齐 metadata.version、metadata.repository 等必填项，并对嵌套 plugin 树递归调用同一套校验。该脚本是 canonical pipeline 在升级流程（§1–§5）开始前的"前置门"，也是问题 [#175] 中"regen 默默丢弃 Rust/Shell 资产"修复点所在——因为只有当 marketplace 元数据声明了 languages: [rust, shell]，模板生成的 publish.py 才会保留对应的 gate。资料来源：scripts/standardize_marketplace.py:30-110 资料来源：scripts/standardize_marketplace.py:140-200

市场成员管理与缓存

scripts/manage_marketplace.py 提供 add / remove / list / verify 四类子命令，所有操作都在本地缓存（~/.cache/cpv/marketplace-<hash>.json）中完成事务：先写 staging 文件，校验通过后原子重命名为正式缓存。该设计解释了为何 canonical pipeline 在 CPV 构建 4 秒后仍能"挂起"25–30 分钟（社区问题 [#180]）——它极可能正在重算 staging 缓存并等待下游 --strict 校验回填，而非 #114 的冷构建本身。manage_marketplace.py 同样负责在每次写操作后使相关 plugin 的 last_validated 时间戳失效，强制下次 cpv-remote-validate 重跑。资料来源：scripts/manage_marketplace.py:50-140 资料来源：scripts/manage_marketplace.py:200-260

打包、剥离与发布前生命周期

发布前最后两步是 cpv_pack_components.py 与 cpv_strip_dev.py。前者把 commands/agents/skills/hooks 按可分发的 .tar.zst 形式组装，并在清单里写入每个组件的 SHA-256，供 marketplace 端做完整性比对；后者从已打包树中删除 __pycache__、.pytest_cache、tests/、project-memory/ 等非可发布目录。问题 [#176] 的根因正是：当 --strict 范围包含这些被 gitignored 但仍被跟踪的内容时，cpv_strip_dev.py 未在验证前先跑，导致项目记忆与测试夹具进入 strict 扫描并触发 skillaudit 误报。修复路径应把 cpv_strip_dev.py 提前到 --strict 校验流水线之前执行。资料来源：scripts/cpv_pack_components.py:1-80 资料来源：scripts/cpv_pack_components.py:120-200 资料来源：scripts/cpv_strip_dev.py:30-120

已知限制与社区证据

• 语言资产被静默丢弃（#175）：当 marketplace 元数据未声明插件自带的语言，canonical pipeline 重新生成的 publish.py 会移除对应 gate。
• strict 范围越界（#176）：当前 --strict 包含非可发布跟踪文件，需配合 cpv_strip_dev.py 前置执行修复。
• 缓存悬挂（#180）：CPV 构建 4 秒后 validate 仍挂 25–30 分钟，与缓存 staging 阶段及后续重验链路有关。
• frontmatter 字段滞后（#173）：Claude Code v2.1.218 的 background 字段未进入白名单，需在 standardize_plugin.py 增补。
• 辅助脚本自身误报（#172）：cpv_validation_common.py 数据常量触发 bandit B108，说明发布前生命周期仍需自举扫描。

概述

CPV 既是一个验证器（对他人插件执行 cpv-remote-validate plugin . --strict），也是一个被验证者（canonical publish.py 会反过来对自己的产物做 gate）。因此其配置层、规则层、扩展层与诊断层都需要满足双向对称性：

• 配置层：通过 JSON 数据文件而非代码逻辑暴露阈值与白名单，避免硬编码引发的「难复现 / 难回滚」。
• 规则层：以「检测器 + 严重度（MAJOR/NIT）」的形式声明，使用 RE2 兼容正则避免跨平台行为漂移。
• 可扩展性：允许插件作者在依赖树（而不只是自身树）上注册「会写入 agent 后续加载为指令的文件」的组件。
• 诊断层：把所有 gate、validate、publish 的执行痕迹写入可追溯的遥测，便于事后复盘 #180 类「超时但无资产」事件。

规则与模式配置

skillaudit_patterns.json — 检测器与严重度声明

skillaudit_patterns.json 是 skillaudit 模块的事实数据源（data-of-record），用于定义文件系统写入、MCP 协议投毒等检测器的匹配模式与降级策略。社区中 #177（FS_WRITE 误报 ~/.zshrc PROSE）与 #178（MCP_SCHEMA_POISON 误报 description: PROSE）都直接落在该文件中需要精修的模式分支上。资料来源：scripts/rules/skillaudit_patterns.json:1-200

配置要点：

re2_compatibility.json — 跨平台正则契约

由于 Python re 与 Go regexp/RE2 在 lookbehind、回溯等特性上不等价，CPV 把所有跨语言规则的正则子集统一登记到 re2_compatibility.json，保证 canonical-pipeline 中的同一条规则在 publish.py（Python）与未来的 Go-side 校验器里行为一致。资料来源：scripts/rules/re2_compatibility.json:1-120

社区中的 #172（cpv_validation_common.py 触发了 bandit B108）正是因为这条契约尚未覆盖某些 Python 端独有的写法，导致 CPV 自家脚本无法满足自己定义的 gate。

可扩展性：依赖与上下文写入器扫描

CPV 的核心命题之一是：「写入 agent 后续加载为指令的文件」的组件，无论它在插件树内还是依赖树内，都必须被纳入风险评分。Issue #174 直接指出当前实现只扫插件树、不扫依赖，且把「具备能力」与「实际执行」混为一谈。

cpv_dependency_agent_writers.py — 写入器探测

该模块枚举上游依赖（package.json/pyproject.toml/Cargo.toml/setup.py 等）并标记 writes_agent_context=true 的组件。资料来源：scripts/cpv_dependency_agent_writers.py:1-180 输出结构遵循：

{
  "name": "<dep>",
  "version": "<semver>",
  "writes_agent_context": true|false,
  "live_writes": true|false,   # 实际执行过写文件
  "capability_score": 0..100   # 静态能力分
}

按 #174 的要求，应当把 capability_score（静态）与 live_writes（运行时）分开计数，避免一个「会写但从未写过」的依赖被高估。

cpv_dependency_schema.py — 依赖声明 schema

为了避免每次发布时手动维护上述列表，cpv_dependency_schema.py 提供一个 JSON Schema，约束插件作者在 .cpv/dependencies.json 中显式声明每个依赖的 writes_agent_context 与回滚策略。资料来源：scripts/cpv_dependency_schema.py:1-150 这同时也是 canonical publish.py 中 --gate 的输入之一。

诊断与遥测

validate_telemetry.py — 运行痕迹落盘

当 cpv-remote-validate 或 canonical publish.py 启动时，会调用 validate_telemetry.py 把以下信号写入 .cpv/telemetry/<run-id>.jsonl：

• 检测器命中行号、文件、严重度、规则 ID
• 每个 gate 的进入/退出时间戳与退出码
• 超时事件（直接对应 #180 的「30 min 后被杀」场景）

资料来源：scripts/validate_telemetry.py:1-220 该文件可被 CI 直接上传为 artifact，使得 #180 类「成功构建却没产物」事件可被事后回放定位到具体的 gate 编号。

cpv_integrity.py — 自校验

最后，cpv_integrity.py 在发布前对自身制品做哈希校验、签名验证与「自规则自洽」检查（即用 CPV 自身去扫 cpv_validation_common.py）。资料来源：scripts/cpv_integrity.py:1-160 这是 #172（自制品触发 bandit）与 #170（反注入注释被误判）的最后一道防线：只要该 gate 通过，就证明本轮发布的 CPV 对自家产物是一致的。

关联流程图

flowchart LR
    A[JSON 规则<br/>skillaudit_patterns.json] --> B[规则引擎<br/>RE2 兼容 re2_compatibility.json]
    C[依赖扫描<br/>cpv_dependency_agent_writers.py] --> D[schema 校验<br/>cpv_dependency_schema.py]
    B --> E[validate_telemetry.py<br/>运行遥测]
    D --> E
    E --> F[cpv_integrity.py<br/>自校验 gate]
    F --> G[canonical publish.py<br/>发布]

资料来源：scripts/rules/skillaudit_patterns.json:1-200、scripts/rules/re2_compatibility.json:1-120、scripts/cpv_dependency_agent_writers.py:1-180、scripts/cpv_dependency_schema.py:1-150、scripts/validate_telemetry.py:1-220、scripts/cpv_integrity.py:1-160

Pitfall Log / 踩坑日志

项目：Emasoft/claude-plugins-validation

摘要：发现 40 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安全/权限坑 - 失败模式：security_permissions: Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-...。

1. 安全/权限坑 · 失败模式：security_permissions: Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-...

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-default-branch pushes after secret scan (fleet-stall root cause)
• 对用户的影响：Developers may expose sensitive permissions or credentials: Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-default-branch pushes after secret scan (fleet-stall root cause)
• 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/169 | Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-default-branch pushes after secret scan (fleet-stall root cause)

2. 安全/权限坑 · 失败模式：security_permissions: skillaudit:agent_manipulation MCP_SCHEMA_POISON false-positive on wikimem memory-note descrip...

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: skillaudit:agent_manipulation MCP_SCHEMA_POISON false-positive on wikimem memory-note description: PROSE (same class as #177 / #156)
• 对用户的影响：Developers may expose sensitive permissions or credentials: skillaudit:agent_manipulation MCP_SCHEMA_POISON false-positive on wikimem memory-note description: PROSE (same class as #177 / #156)
• 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/178 | skillaudit:agent_manipulation MCP_SCHEMA_POISON false-positive on wikimem memory-note description: PROSE (same class as #177 / #156)

3. 安全/权限坑 · 失败模式：security_permissions: standardize still strips documented linter suppressions (MD010, CKV_DOCKER_2) — #145 fixed on...

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: standardize still strips documented linter suppressions (MD010, CKV_DOCKER_2) — #145 fixed only MD025; and canon publish.py never creates the {name}--v{version} resolver tag
• 对用户的影响：Developers may expose sensitive permissions or credentials: standardize still strips documented linter suppressions (MD010, CKV_DOCKER_2) — #145 fixed only MD025; and canon publish.py never creates the {name}--v{version} resolver tag
• 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/165 | standardize still strips documented linter suppressions (MD010, CKV_DOCKER_2) — #145 fixed only MD025; and canon publish.py never creates the {name}--v{version} resolver tag

4. 安全/权限坑 · 来源证据：Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build cause; timed-out release s…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build cause; timed-out release shipped with no assets
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/180 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

5. 安装坑 · 失败模式：installation: Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build cause; timed-out release shipped with no assets
• 对用户的影响：Developers may fail before the first successful local run: Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build cause; timed-out release shipped with no assets
• 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/180 | Canonical-pipeline validate step hangs ~30 min AFTER CPV builds (4s) — not #114's cold-build cause; timed-out release shipped with no assets

6. 安装坑 · 失败模式：installation: Scan dependencies (not just the plugin tree) for agent-context writers, and score capability...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Scan dependencies (not just the plugin tree) for agent-context writers, and score capability vs live separately
• 对用户的影响：Developers may fail before the first successful local run: Scan dependencies (not just the plugin tree) for agent-context writers, and score capability vs live separately
• 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/174 | Scan dependencies (not just the plugin tree) for agent-context writers, and score capability vs live separately

7. 安装坑 · 失败模式：installation: feat(canonical-pipeline): gate Rust + shell when a plugin ships them (regen drops them silently)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: feat(canonical-pipeline): gate Rust + shell when a plugin ships them (regen drops them silently)
• 对用户的影响：Developers may fail before the first successful local run: feat(canonical-pipeline): gate Rust + shell when a plugin ships them (regen drops them silently)
• 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/175 | feat(canonical-pipeline): gate Rust + shell when a plugin ships them (regen drops them silently)

8. 安装坑 · 失败模式：installation: skillaudit:filesystem FS_WRITE false-positive on install-doc PROSE (bash comment naming ~/.zs...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: skillaudit:filesystem FS_WRITE false-positive on install-doc PROSE (bash comment naming ~/.zshrc)
• 对用户的影响：Developers may fail before the first successful local run: skillaudit:filesystem FS_WRITE false-positive on install-doc PROSE (bash comment naming ~/.zshrc)
• 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/177 | skillaudit:filesystem FS_WRITE false-positive on install-doc PROSE (bash comment naming ~/.zshrc)

9. 安装坑 · 失败模式：installation: v2.158.0: the #165 resolver-tag migration SILENTLY skips 6/13 fleet plugins (anchor regex mis...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v2.158.0: the #165 resolver-tag migration SILENTLY skips 6/13 fleet plugins (anchor regex misses the two-call push shape); residual signal is a non-blocking WARNING; its remedia...
• 对用户的影响：Developers may fail before the first successful local run: v2.158.0: the #165 resolver-tag migration SILENTLY skips 6/13 fleet plugins (anchor regex misses the two-call push shape); residual signal is a non-blocking WARNING; its remedia...
• 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/167 | v2.158.0: the #165 resolver-tag migration SILENTLY skips 6/13 fleet plugins (anchor regex misses the two-call push shape); residual signal is a non-blocking WARNING; its remedia...

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

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

11. 配置坑 · 失败模式：configuration: CC v2.1.207 spec drift: ${user_config.*} in shell-form commands is now REJECTED, and plugin o...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: CC v2.1.207 spec drift: ${user_config.*} in shell-form commands is now REJECTED, and plugin options are no longer read from project settings.json — CPV has no rule for either
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: CC v2.1.207 spec drift: ${user_config.*} in shell-form commands is now REJECTED, and plugin options are no longer read from project settings.json — CPV has no rule for either
• 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/166 | CC v2.1.207 spec drift: ${user_config.*} in shell-form commands is now REJECTED, and plugin options are no longer read from project settings.json — CPV has no rule for either

12. 配置坑 · 失败模式：configuration: RC-DEP-TAG-PIPELINE false-positives on a correct (manifest-derived) resolver tag — the litera...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: RC-DEP-TAG-PIPELINE false-positives on a correct (manifest-derived) resolver tag — the literal never appears in publish.py
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: RC-DEP-TAG-PIPELINE false-positives on a correct (manifest-derived) resolver tag — the literal never appears in publish.py
• 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/168 | RC-DEP-TAG-PIPELINE false-positives on a correct (manifest-derived) resolver tag — the literal never appears in publish.py

13. 配置坑 · 失败模式：configuration: Recognize CC v2.1.218 skill-frontmatter field 'background' (currently flagged 'Unknown frontm...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Recognize CC v2.1.218 skill-frontmatter field 'background' (currently flagged 'Unknown frontmatter field')
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Recognize CC v2.1.218 skill-frontmatter field 'background' (currently flagged 'Unknown frontmatter field')
• 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/173 | Recognize CC v2.1.218 skill-frontmatter field 'background' (currently flagged 'Unknown frontmatter field')

14. 配置坑 · 失败模式：configuration: bug(--strict scope): validates non-shippable tracked content (project-memory, test fixtures)...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: bug(--strict scope): validates non-shippable tracked content (project-memory, test fixtures) + gitignored files
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: bug(--strict scope): validates non-shippable tracked content (project-memory, test fixtures) + gitignored files
• 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/176 | bug(--strict scope): validates non-shippable tracked content (project-memory, test fixtures) + gitignored files

15. 配置坑 · 失败模式：configuration: canonical publish.py: run() hardcodes timeout=300, making the test gate unsatisfiable for a r...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: canonical publish.py: run() hardcodes timeout=300, making the test gate unsatisfiable for a real suite
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: canonical publish.py: run() hardcodes timeout=300, making the test gate unsatisfiable for a real suite
• 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/179 | canonical publish.py: run() hardcodes timeout=300, making the test gate unsatisfiable for a real suite

16. 配置坑 · 失败模式：configuration: cpv_validation_common.py trips bandit B108 on its own data constants — blocks publish.py --ga...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: cpv_validation_common.py trips bandit B108 on its own data constants — blocks publish.py --gate for every plugin vendoring it
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: cpv_validation_common.py trips bandit B108 on its own data constants — blocks publish.py --gate for every plugin vendoring it
• 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/172 | cpv_validation_common.py trips bandit B108 on its own data constants — blocks publish.py --gate for every plugin vendoring it

17. 配置坑 · 失败模式：configuration: skillaudit: defensive anti-injection guardrails flagged as injection (4 detectors, NIT blocks...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: skillaudit: defensive anti-injection guardrails flagged as injection (4 detectors, NIT blocks --strict); retro-breaks green releases
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: skillaudit: defensive anti-injection guardrails flagged as injection (4 detectors, NIT blocks --strict); retro-breaks green releases
• 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/170 | skillaudit: defensive anti-injection guardrails flagged as injection (4 detectors, NIT blocks --strict); retro-breaks green releases

18. 配置坑 · 失败模式：configuration: standardize --fix generates a .cspell.json that trips CPV's own skillaudit TOOL_SHADOW detect...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: standardize --fix generates a .cspell.json that trips CPV's own skillaudit TOOL_SHADOW detector (clean repo -> blocking MAJOR)
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: standardize --fix generates a .cspell.json that trips CPV's own skillaudit TOOL_SHADOW detector (clean repo -> blocking MAJOR)
• 证据：failure_mode_cluster:github_issue | https://github.com/Emasoft/claude-plugins-validation/issues/171 | standardize --fix generates a .cspell.json that trips CPV's own skillaudit TOOL_SHADOW detector (clean repo -> blocking MAJOR)

19. 能力坑 · 能力判断依赖假设

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

20. 维护坑 · 维护活跃度未知

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/Emasoft/claude-plugins-validation | no_demo; severity=medium

22. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 证据：risks.safety_notes | https://github.com/Emasoft/claude-plugins-validation | No sandbox install has been executed yet; downstream must verify before user use.

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

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

24. 安全/权限坑 · 来源证据：CC v2.1.207 spec drift: ${user_config.*} in shell-form commands is now REJECTED, and plugin options are no longer read…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：CC v2.1.207 spec drift: ${user_config.*} in shell-form commands is now REJECTED, and plugin options are no longer read from project settings.json — CPV has no…
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/166 | 来源类型 github_issue 暴露的待验证使用条件。

25. 安全/权限坑 · 来源证据：Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-default-branch pushes afte…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Canonical pre-push hook: strict publish-ancestry gate forbids ALL branch sharing — allow non-default-branch pushes after secret scan (fleet-stall root cause)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/169 | 来源类型 github_issue 暴露的待验证使用条件。

26. 安全/权限坑 · 来源证据：RC-DEP-TAG-PIPELINE false-positives on a correct (manifest-derived) resolver tag — the literal never appears in publish…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：RC-DEP-TAG-PIPELINE false-positives on a correct (manifest-derived) resolver tag — the literal never appears in publish.py
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/168 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

27. 安全/权限坑 · 来源证据：Recognize CC v2.1.218 skill-frontmatter field 'background' (currently flagged 'Unknown frontmatter field')

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Recognize CC v2.1.218 skill-frontmatter field 'background' (currently flagged 'Unknown frontmatter field')
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/173 | 来源类型 github_issue 暴露的待验证使用条件。

28. 安全/权限坑 · 来源证据：Scan dependencies (not just the plugin tree) for agent-context writers, and score capability vs live separately

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Scan dependencies (not just the plugin tree) for agent-context writers, and score capability vs live separately
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/174 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

29. 安全/权限坑 · 来源证据：bug(--strict scope): validates non-shippable tracked content (project-memory, test fixtures) + gitignored files

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug(--strict scope): validates non-shippable tracked content (project-memory, test fixtures) + gitignored files
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/176 | 来源类型 github_issue 暴露的待验证使用条件。

30. 安全/权限坑 · 来源证据：canonical publish.py: run() hardcodes timeout=300, making the test gate unsatisfiable for a real suite

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：canonical publish.py: run() hardcodes timeout=300, making the test gate unsatisfiable for a real suite
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/179 | 来源类型 github_issue 暴露的待验证使用条件。

31. 安全/权限坑 · 来源证据：cpv_validation_common.py trips bandit B108 on its own data constants — blocks publish.py --gate for every plugin vendor…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：cpv_validation_common.py trips bandit B108 on its own data constants — blocks publish.py --gate for every plugin vendoring it
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/172 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

32. 安全/权限坑 · 来源证据：feat(canonical-pipeline): gate Rust + shell when a plugin ships them (regen drops them silently)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(canonical-pipeline): gate Rust + shell when a plugin ships them (regen drops them silently)
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/175 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

33. 安全/权限坑 · 来源证据：skillaudit: defensive anti-injection guardrails flagged as injection (4 detectors, NIT blocks --strict); retro-breaks g…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：skillaudit: defensive anti-injection guardrails flagged as injection (4 detectors, NIT blocks --strict); retro-breaks green releases
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/170 | 来源类型 github_issue 暴露的待验证使用条件。

34. 安全/权限坑 · 来源证据：skillaudit:agent_manipulation MCP_SCHEMA_POISON false-positive on wikimem memory-note description: PROSE (same class as…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：skillaudit:agent_manipulation MCP_SCHEMA_POISON false-positive on wikimem memory-note description: PROSE (same class as #177 / #156)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/178 | 来源类型 github_issue 暴露的待验证使用条件。

35. 安全/权限坑 · 来源证据：skillaudit:filesystem FS_WRITE false-positive on install-doc PROSE (bash comment naming ~/.zshrc)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：skillaudit:filesystem FS_WRITE false-positive on install-doc PROSE (bash comment naming ~/.zshrc)
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/177 | 来源类型 github_issue 暴露的待验证使用条件。

36. 安全/权限坑 · 来源证据：standardize --fix generates a .cspell.json that trips CPV's own skillaudit TOOL_SHADOW detector (clean repo -> blocking…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：standardize --fix generates a .cspell.json that trips CPV's own skillaudit TOOL_SHADOW detector (clean repo -> blocking MAJOR)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/171 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

37. 安全/权限坑 · 来源证据：standardize still strips documented linter suppressions (MD010, CKV_DOCKER_2) — #145 fixed only MD025; and canon publis…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：standardize still strips documented linter suppressions (MD010, CKV_DOCKER_2) — #145 fixed only MD025; and canon publish.py never creates the {name}--v{version…
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/165 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

38. 安全/权限坑 · 来源证据：v2.158.0: the #165 resolver-tag migration SILENTLY skips 6/13 fleet plugins (anchor regex misses the two-call push shap…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.158.0: the #165 resolver-tag migration SILENTLY skips 6/13 fleet plugins (anchor regex misses the two-call push shape); residual signal is a non-blocking WA…
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/Emasoft/claude-plugins-validation/issues/167 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

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

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