Plate 仓库代码模式识别指南：基于 pattern-recognition-specialist 的设计模式、反模式与代码质量审计实践
Plate 仓库代码模式识别指南基于 pattern-recognition-specialist 的设计模式、反模式与代码质量审计实践【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate本篇指南围绕 Plate 仓库.agents/skills/pattern-recognition-specialist/SKILL.md所定义的代码模式分析专家方法论展开说明如何在以插件架构为核心的富文本编辑器代码库中系统化完成设计模式检测、反模式扫描、命名一致性审查、重复代码定位与架构边界核查并给出可直接落地的审计工作流与报告产出格式。读完本文你将掌握一套可复用于任意 TypeScript 大型 monorepo 的代码质量审计清单并能结合 Plate 仓库自身的架构宪法north-star与插件创作规范plate-plugin-creator理解这些规则在实际源码中的落地形态。一、角色定位什么是代码模式分析专家.agents/skills/pattern-recognition-specialist/SKILL.md定义了一个专职角色Code Pattern Analysis Expert。它的核心使命是在整个代码库范围内识别设计模式Design Patterns、反模式Anti-Patterns与代码质量问题其专业知识覆盖多种编程语言并依赖对软件架构原则与最佳实践的深入理解。该 Skill 在仓库中通过 Skiller 体系接入元数据声明其来源为plugins/compound-engineering/agents/review/pattern-recognition-specialist.md并使用model: inherit继承当前模型的推理配置。它的典型触发场景有两个来自 SKILL.md 中的examples用户希望分析代码库中的设计模式与潜在问题Can you check our codebase for design patterns and anti-patterns?新功能落地后校验其是否符合既有模式I just added a new service layer. Can we check if it follows our existing patterns?。在这两种场景下分析专家都应启动一套结构化扫描流程而不是零散地随手翻文件。二、五大核心职责审计覆盖面SKILL.md 将职责划分为五个维度这正是整个审计框架的骨架1. 设计模式检测Design Pattern Detection使用合适的搜索工具查找并识别常见设计模式Factory、Singleton、Observer、Strategy 等记录每个模式的使用位置并评估实现是否符合最佳实践。在 Plate 仓库中这一职责有非常具体的落点。packages/plate-plugin-creatorSkill 明确规定了插件创作的四类 API 形态它们本身就是一组工厂/构建器模式createSlatePlugin/createTSlatePlugin—— 拥有语义的纯 Slate 基础插件toPlatePlugin/toTPlatePlugin—— 将语义基础插件提升为 React/Plate 表面createPlatePlugin/createTPlatePlugin—— 真正的 React/Plate 原生插件或既有插件的捆绑包。例如 BasicBlocksPlugin.tsx 就是捆绑插件bundle plugin模式的典型实现——它直接组合已有的BlockquotePlugin、HeadingPlugin、HorizontalRulePlugin而不是重新发明一个虚假的基础插件import { createPlatePlugin } from platejs/react; import { BlockquotePlugin } from ./BlockquotePlugin; import { HeadingPlugin } from ./HeadingPlugin; import { HorizontalRulePlugin } from ./HorizontalRulePlugin; export const BasicBlocksPlugin createPlatePlugin({ plugins: [BlockquotePlugin, HeadingPlugin, HorizontalRulePlugin], });审计者在做设计模式检测时应当能指出这种组合优于重写的模式选择并依据.agents/skills/north-star/rules/pattern-catalog.md判断实现质量——该目录对插件/扩展模式给出的偏好是包拥有规范语义、每个特性有显式归属、通用扩展任务使用本地化助手而应避免跨特性的全局大口袋。2. 反模式识别Anti-Pattern IdentificationSKILL.md 要求系统性扫描代码异味与反模式具体清单包括TODO/FIXME/HACK 注释技术债信号上帝对象/职责过多的类God objects循环依赖Circular dependencies类之间的不恰当亲密关系Inappropriate intimacy特性嫉妒与其他耦合问题Feature envy。Plate 仓库将这类反模式进一步具象化。.agents/skills/north-star/rules/anti-patterns.md列出了一份与插件/API 设计强相关的反模式清单审计时可直接作为判定基准因包被安装就静默激活行为的隐藏默认值Hidden defaults以标点噪声形式出现的公共键Public keys encoded as punctuation noise无谓重复属主的冗长键名Verbose keys核心 API 越权拥有特性语义Core APIs owning feature semantics本地语法糖过早晋升为规范包契约Local sugar promoted into canonical package contracts too early伪装通用的 DSL 却仍泄漏边缘情况Fake generic DSLs用流式链式调用掩盖对象配置清晰度的链式表演Chain theater在热路径上悄悄增加运行时开销的漂亮 API在多个 Skill 或文件中重复的教条Doctrine duplicated across multiple skills or files。这些条目与仓库的 Ownership Law所有权法则一脉相承公共 API 必须有显式属主Core 拥有共享原语与编排特性包拥有特性语义本地套件拥有本地便利三者不得因短期便利而混淆。3. 命名约定分析Naming Convention Analysis评估以下维度的命名一致性变量、方法与函数类与模块文件与目录常量与配置值。识别偏离既定约定的偏差并提出改进建议。Plate 仓库在这方面的既有约定非常明确审计者应以这些约定为基线SKILL.md 明确要求遇到项目特定约定时——尤其是 AGENTS.md 之类文档中的约定——应将其纳入分析基线AGENTS.md 要求所有交互与提交信息中极度简洁为简洁牺牲语法这直接约束了命名风格.agents/rules/plate-plugin-creator.mdc规定禁止在源码中使用any不要在线程中把SlateEditor穿过回调、选项或辅助函数签名共享插件键必须来自packages/utils/src/lib/plate-keys.ts的KEYS常量而不是随机字符串字面量文件放置上任何不属于预期公共契约的辅助函数、匹配器、回退分支都应放在internal/目录下。审计时可抽样的代表文件包括packages/core/src/lib/plugin/Slate-first 创作原语、packages/core/src/react/plugin/Plate 包装原语以及packages/core/type-tests/插件契约的真相来源。4. 代码重复检测Code Duplication Detection使用 jscpd 或类似工具识别重复代码块并根据语言与上下文设置合理阈值例如--min-tokens 50优先关注那些可重构为共享工具或抽象的有意义重复。在 Plate 这种拥有 40 包的 monorepo 中重复检测尤其有价值。north-star 的Matcher Extraction Heuristic匹配器抽取启发式就是为治理这类重复而设计的决策规则当扫描可复用 API 家族时应激进地检查重复的resolve()与apply()函数体而不是急于发明更多包级包装器。判定逻辑是多个包重复相同的匹配前奏trigger gating、collapsed-selection gating、block-start / text-before / adjacent-char 查找、delimiter / prefix / regex 匹配、range 或 payload 构造等与特性无关的编辑器状态检查→ 这是抽取 Core 原语的压力信号多个包重复相同的特性动作节点创建、标记切换、列表变换、链接校验/插入、公式插入、代码块插入等特性包拥有的语义变换→ 通常仍应留在属主包内。换句话说Core 拥有匹配器原语与共享输入状态访问特性包拥有语义 apply 行为。审计者在报告重复代码时应能区分应该上提 Core与看起来像但不应扁平化的两类重复避免因为文件长得像就把包语义压进 Core的误判。5. 架构边界审查Architectural Boundary Review分析分层违例与架构边界检查关注点分离是否正确识别违反架构原则的跨层依赖确保模块遵守预期边界标记任何绕过抽象层的行为。Plate 的 Layering Law分层法则为这项审查提供了明确标尺每个可复用表面必须声明自己属于哪一层——constitutional doctrine宪法教条、shared runtime primitive共享运行时原语、feature semantic contract特性语义契约、execution helper执行助手、local convenience本地便利。如果无法说出 API 属于哪一层这个 API 就还没准备好。north-star 还补充了 Runtime Boundary Law运行时边界法则运行时/服务关注点应是显式接缝而不是从插件代码中泄漏出来的副作用——包括缓存、投影、诊断、协议边界、布局/测量服务。审计者应检查是否有服务被直接缠进渲染/插件胶水层以及是否在热路径上从零重算大型派生状态。三、审计工作流六步执行流程SKILL.md 规定了一套从粗到细的六步工作流广度优先的模式搜索使用内置 Grep 工具起步需要结构级 AST 匹配时改用ast-grep汇总模式清单整理已识别模式及其位置的完整列表反模式指示符扫描搜索 TODO、FIXME、HACK、XXX命名约定分析抽样有代表性的文件运行重复检测使用带合适参数的 jscpd架构结构审查检查边界违例。这套流程与 north-star 的决策阶梯Decision Ladder可配合使用如果审计中发现可复用性存疑的 API可以沿.agents/skills/north-star/rules/decision-ladder.md依次追问——这是否可复用是本地便利吗模式是否已定型层级是否清晰性能是否约束形态是否需要重申确认从而把发现问题升级为裁决归属。四、结构化报告审计产出格式分析完成后SKILL.md 要求交付一份包含四大部分的结构化报告Pattern Usage Report模式使用报告发现的设计模式清单、位置与实现质量Anti-Pattern Locations反模式位置包含反模式的具体文件与行号并给出严重程度评估Naming Consistency Analysis命名一致性分析命名约定遵循度的统计附具体不一致示例Code Duplication Metrics重复代码指标量化的重复数据与重构建议。报告应遵循四项分析原则考虑特定语言的惯用法与约定为模式的合理例外提供依据justification按影响程度与解决难度排序发现项提供可执行的建议而非只有批评同时考虑项目的成熟度与技术债容忍度SKILL.md 原文虽列为When analyzing code清单但考虑项目成熟度与技术债容忍度是报告分级的重要输入。在 Plate 仓库语境下报告还可以附加第五个板块与 north-star 教条的对照结论——每个发现项指出其违反或遵循了.agents/skills/north-star/rules/laws.md中的哪条法则Ownership、Layering、Explicitness、Runtime Boundary、Performance、Canonical Semantics、Public Contract。五、在 Plate 仓库中的实践提示将该 Skill 落地到 Plate 仓库时有以下几条与仓库结构直接相关的实操要点先读宪法再下结论任何可复用公共 API、运行时/服务边界、构建器/工厂模式、命名/分层规则或性能敏感表面的分析都应先对照.agents/skills/north-star/SKILL.md它是可复用架构与公共 API 设计的上游决策层插件机制细节则以.agents/skills/plate-plugin-creator/SKILL.md为准。用类型测试作为契约真相仓库约定Core 契约优先于旧例Core contracts beat precedentpackages/core/type-tests/中的类型测试优先于嘈杂的旧包示例。审计者判断某个公共 API 形态是否正确时应以核心创作 API 与类型测试为权威而不是以最响亮的旧插件文件为权威。桶文件barrel是生成产物仓库明确禁止手写或手工编辑index.ts/index.tsx桶文件应将其视为生成输出新增/移动/重命名公共文件后需运行pnpm brl。审计时如果发现手工修补的桶文件这本身就是一个需要标记的流程违例。性能是设计约束而非事后清理Performance Law 指出如果更好看的 API 增加了热路径工作、派发成本、分配抖动、合并歧义或失效复杂度这些成本都属于 API 决策的一部分。审计者在评估优雅的新 API 时必须把这个成本项计入结论。面向 Agent 的文档一等公民AGENTS.md 要求 JSDoc 必须是一等公民每个 API 表面都应同时让人类与 AI Agent 感到直观。命名与注释审查应包含这一维度。六、适用范围与边界最后需要明确该 Skill 的适用边界。north-star Skill 明确列举了何时不使用仅限应用本地便利的工作、一次性迁移助手无持久公共模式、公共模式已定型且仅是实现机制的工作、仅涉及公共文档措辞的问题、git/流程类工作都不应上升为架构审计。与之对应pattern-recognition-specialist 的角色价值恰恰集中在可复用 API 与运行时边界这类高杠杆区域——它是一套先扫描、再分级、后裁决的完整审计方法论最终服务于一个目标在尊重既有架构决策的前提下持续提升代码质量。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考