扩展：配置、贡献与能力合同

配置与组合

入口/钩子	返回或职责	约束
`Extension.create(config)`	行为扩展定义	不新增 Schema 节点
`Node.create(config)` / `Mark.create(config)`	节点/标记定义	Node 的 group/content、Mark 的约束进入同一个 Schema
`.configure(options)`	配置后的扩展	为每个产品实例独立装配，不能修改共享全局 options
`.extend(config)`	在原定义上扩展	有意替换同名能力，检查调用原 hook 的方式和顺序
`addOptions()`	默认配置	配置不是持久正文
`addStorage()`	实例状态	不把应持久化的业务属性藏进 storage
`addExtensions()`	子扩展数组	预设或聚合包的组合点，避免重复 Schema 所有者
`addAttributes()` / `addGlobalAttributes()`	属性定义	明确默认值、解析、序列化和迁移
`addCommands()`	raw command factories	增强 `Commands<ReturnType>`，commands/chain/can 使用同一类型
`addKeyboardShortcuts()`	按键映射	调同一命令，返回是否处理
`addInputRules()` / `addPasteRules()`	输入/粘贴规则	与现有历史和 Schema 一起验证
`addProseMirrorPlugins()`	PM plugins	沿用当前 `@quirekit/pm` 身份，不混装另一份上游内核

最小行为例程见自定义插件；包含规范内容与 retained View 的完整例程见内容扩展。

能力贡献的所有者

钩子	下游消费方	不是自动获得的能力
`addViewAdapters()`	Core 挂载生命周期	Schema 本身不提供输入与绘制
`addDocumentProfiles()`	排版引擎的 facet 解析	Core 不解释 Word 属性或单位
`addLayoutProviders()`	View/Engine	HTML CSS 不自动变成 Canvas 布局
`addSelectionAdapters()`	结构选择编译与命令目标	可绘制不代表可正确跨组选择
`addDocx()`	实例 `editor.docx`	序列化为 JSON 不代表 DOCX 往返成立
`addAccessibility()`	无障碍语义 owner	只画文字不等于语义可达
`addAiCapabilities()`	AI 核心	feature 声明事实和 described command，不自建模型工具或提示词

产品 UI 的 addRibbonItems 等贡献需要相应产品注册表消费；纯 Core 实例不会凭这些声明生成界面。参见产品插件。

文档 profile 与布局 provider

profile 提供模型级语义，如页面、段落、表格和绘图。一个 facet 只能有一个所有者；缺失项走中立默认。它与单个 custom Node 的布局 provider 不是同一抽象。

@quirekit/core/document-profile

扩展贡献的文档语义 profile。Core 将载荷视为不透明对象，排版引擎验证并消费所声明的 facet；每项 facet 只能有一个所有者。

export interface QuireDocumentProfileRegistration<Profile = unknown> {
    readonly id: string;
    readonly facets: readonly string[];
    readonly profile: Profile;
}

成员	说明
`id`	用于诊断和查找的稳定 profile 身份。
`facets`	该 profile 提供的 facet 名称，每项仅有一个所有者。
`profile`	由排版引擎验证并消费的不透明载荷。

provider 声明 nodeTypes 和 capability，并返回带源范围/快照版本的布局产品。注册通过公开子入口；不要把内部类型名误当成根入口 export。

@quirekit/core/layout-provider

扩展贡献的渲染后端中立布局注册，声明 provider 身份、节点类型、能力与依赖。

export interface QuireLayoutProviderRegistration<Provider = unknown> {
    readonly id: string;
    readonly nodeTypes: readonly string[];
    readonly capabilities: readonly QuireLayoutProviderCapabilityKind[];
    readonly provider: Provider;
    readonly layoutDependency?: QuireLayoutDependency | undefined;
}

成员	说明
`id`	稳定 provider 身份。
`nodeTypes`	由该 provider 处理的 PM 节点类型。
`capabilities`	该 provider 实现的能力类别。
`provider`	由能力所有者消费的不透明 provider 载荷。
`layoutDependency`	覆盖该具体 provider 及其全部可变依赖的可选证明。

@quirekit/view-engine/layout-provider

将强类型布局 provider 包装为 Core 注册元数据。Core 检查身份与节点归属，View 在执行前验证元数据与载荷一致。 @param provider - 布局算法及其能力声明。 @returns 保留该 provider 载荷的 Core 注册。

function createQuireLayoutProviderRegistration(provider: QuireLayoutProvider): QuireViewLayoutProviderRegistration

具体的测量 → child flow → retained region 和 structured selection 见完整源码。layoutDependency: { kind: 'document' } 只有在 provider 不读取未声明的外部可变状态时才成立，不能作为通用性能开关。