Skip to content

Adonis0123/adonis-skills / skills/code-plugin-architecture

code-plugin-architecture

Verified

Design, review, refactor, or explain recurring extension mechanisms when adding or removing one variant requires scattered coordinated edits. Use for plugin architecture, registries, extension points, and cross-stack contract/host mappings. Assess whether a typed map, existing framework mechanism, or lifecycle-owning core is justified. Skip one plugin's internal styling or bugs, user signup, DI containers, and package registries.

references/first-principles.md

View on GitHub
# 第一性原理与架构类比

只在用户需要解释“为什么这样分”和术语映射时读本页。先检查问题是否真实,不把五个概念包装成必须接受的结论。

## 目标是减少修改传播

一次新增变体如果必须修改多个消费方里的同一份知识,容易漏改并产生不一致。优先寻找这份重复知识的 owner,例如变体名单、能力判断或生命周期顺序。正常的实现、测试、文案和兼容性工作仍然可能需要多个文件,不能把它们全算成架构失败。

“加一个变体只改实现与组合入口”是一个可验证的维护目标。它不证明所有系统必须拥有独立 Identity、Contract、Registry、Runtime Core、Convention Folder,更不证明缺一层会在固定时间内失效。

一个反例:静态 formatter 函数表可在一个文件内表达 key、共同函数签名和名单;新增 formatter 只加一个条目。没有订阅和状态,不需要 Core factory;没有多份资源,不需要每项一个目录。它已满足局部扩展目标。

使用 O(N) / O(1) 类比时先定义 N:如果 N 是需要同步改动的位置数,“从多个位置收敛到固定入口”只描述编辑触点;不能由此推出开发、测试、查找或运行时成本恒定。往一个 switch 加一条分支也可能只有一个编辑位置,是否值得换成注册表还需看重复知识和实际消费方式。

## 概念与出现条件

| 概念              | 它解决的问题                       | 不应推出的结论                                      |
| ----------------- | ---------------------------------- | --------------------------------------------------- |
| Identity          | 识别条目并保持兼容                 | 外部 key 必须等于本地目录、组件和埋点名             |
| Contract          | 消费方依赖稳定输入、输出与失败语义 | 每条记录必须有完全相同的字段,或差异都塞进 optional |
| Registry          | 汇总可用变体、避免重复名单         | 物理上只能一个文件;框架发现机制不成立              |
| Runtime Core      | 集中真实共享的状态转换与生命周期   | 无状态函数表也要造 store、factory 和 Provider       |
| Convention Folder | 聚拢一项的多份相关资源             | 每个小函数都要独立目录                              |

这些职责可以由语言类型、普通函数或现有框架承担。衡量提取是否值得:删除新抽象后,重复知识和协调顺序是否重新回流消费方;如果只少一层转发,原抽象收益不足。

## DDD / SOLID 的有限类比

- **OCP**:稳定消费方可通过新实现扩展能力;不表示所有配置和组合入口都永远不改。
- **DIP**:需要隔离实现变化时,高层依赖窄契约;不是每个函数都需要 interface 和注入容器。
- **SRP**:把同一原因导致的变化放在一起;一个目录里收纳一个变体是实现方式之一。
- **ISP**:不同消费方只依赖自己使用的能力;大量可选字段可能说明需要拆契约或可辨识联合。
- **LSP**:替代实现仍需遵守已承诺的输入、输出、错误与副作用行为;共同类型签名不是行为兼容的全部。
- **Published Language**:跨领域边界的共享语言可以通过 Contract 表达;普通内部类型不自动成为 DDD 的 Published Language。
- **Anti-Corruption Layer**:翻译外部或旧模型、保护当前领域语义时可类比;一次普通 props 转发不必上升为该模式。
- **Bounded Context / Open Host Service**:按真实领域模型和对外服务边界判断;插件、目录、Core 不自动与它们一一对应。

类比用来解释已经观察到的边界,不用来替用户选架构。

## 来源与证据边界

[Fowler Plugin](https://martinfowler.com/eaaCatalog/plugin.html) 讨论在配置期连接实现。它支持把装配与业务分开这一思路,不给“五个物理层是必要条件”提供证明。实际项目是否需要插件化,仍由本仓的变化与运行时证据判断。
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall