- 文档类型：设计提案
- 状态：探索性草案
- 设计版本：v2
- 日期：2026-10-10
- 初版：v1（2026-08-19）
@dsh-std/composition 为 std 内部生成组件的激活计划。调用方提供组件声明、当前环境中的协议支持、激活驱动和组合规则；composition 整理这些信息，选择待激活的部分，检查它们的关系，并确定激活次序。
组件通过 manifest 的 ComponentManifest 描述，每个 facet 分别声明启动方式与需求。Composition 以组件为单位检查名称、版本和依赖关系，以 facet 为单位选择待激活部分、建立协议绑定和安排次序。
| 输入 | 提供的内容 | 用途 |
|---|---|---|
| 组件声明 | ComponentManifest 中的身份、facets 和组件关系 |
描述待组合的组件 |
| 激活驱动描述 | 驱动 ID 及其支持的激活类型 | 确定哪些 facets 可以交给驱动执行 |
| 协议目录 | core 的 ProtocolCatalog |
识别协议定义，将对应的需求与支持归到一起 |
| 已有协议声明 | 当前参与者的协议支持 | 将已有支持纳入候选集 |
| 已有扩展 | 已激活部分提供的扩展及其归属 | 与新选中部分的扩展一起检查 |
| 选择与策略 | 指定 facets、选择驱动和判断权限的规则 | 表达本次组合的环境决策 |
| 协议组合规则 | 各协议对需求绑定和扩展并存的规定 | 完成协议专属的组合检查 |
这些信息由调用方汇集。Adapter 可以从组件声明、驱动目录、已激活实例和产品配置中取得输入，再交给 composition。协议包可以提供自己的组合规则，由调用方登记到 CompositionRuleCatalog。
组件名称、版本和声明内容共同用于整理候选组件。完全相同的声明归并为一份；归并后同名的不同声明记为组件冲突。组件之间的依赖、推荐、冲突和破坏关系按目标名称与版本范围检查。
Facet 的选择使用调用方指定的范围和激活驱动描述。驱动通过 apiVersion 与 kind 匹配激活类型。多个驱动匹配同一类型时，由调用方的策略选择驱动。权限请求也交给调用方的策略判断。
选中 facet 的 protocols.requires 形成需求候选；protocols.supports 与已有参与者的支持声明一起形成支持候选。每个候选保存自身标识和归属，供组合规则建立关联。
协议目录负责识别这些坐标对应的定义。Composition 将解析到同一协议定义的需求与支持分组，检查是否存在候选支持，再调用该协议的组合规则。
这里的 preflight 指激活前的组合检查。规则的 preflight() 接收需求候选和支持候选，返回问题列表，以及可选的绑定结果。基础检查处理协议定义与候选支持的存在性；注册的规则进一步处理协议内容和绑定选择。
ProtocolBinding 用一个需求标识和一组支持标识，记录该需求在计划中关联哪些支持。绑定数量和选择方式由相应协议的组合规则确定。
绑定必须（MUST）引用本次规则输入中的候选标识；同一需求必须（MUST）至多登记一条绑定，一条绑定中的支持标识必须（MUST）唯一。
绑定指向待激活的 facet 时，在提供方和需求方之间形成激活依赖；指向已有参与者时，该支持作为已有环境信息参与组合。
已有扩展与选中 facet 的扩展按 apiVersion + kind 分组。协议规则可以通过 composeExtensions() 检查同组扩展是否能够并存；使用基础检查时，同组扩展按名称检查重复项。
扩展列表中的每项保留所属 facet，供调用方定位贡献来源。
- 整理组件。 检查声明结构，归并等价输入，检查组件身份与关系。
- 选择 facets。 根据选择范围与驱动匹配结果记录选中项、跳过项，并检查选中部分的权限请求。
- 检查协议与绑定。 汇集需求和支持，按协议定义分组，执行组合规则并检查返回的绑定。
- 检查扩展。 合并已有扩展与选中部分的声明，执行相应协议的并存检查。
- 安排激活次序。 将组件依赖和 facet 之间的协议绑定组织为依赖图，进行拓扑排序。
- 返回计划。 汇总选择、次序、绑定、扩展和问题列表。
组件依赖使被依赖组件的选中 facets 先于依赖方；协议绑定使提供支持的 facet 先于需求方。依赖图出现环时，计划记录错误。
CompositionPlan 使用 composition.dsh/v1alpha1 标识，包含以下结果：
| 结果 | 内容 |
|---|---|
selected、skipped |
选中和跳过的 facets，以及相关身份、驱动或原因 |
bindings |
协议规则建立的需求与支持关联 |
activationOrder |
选中 facets 的激活次序 |
extensions |
本次检查的扩展与归属 |
issues、compatible |
组合问题，以及是否没有错误 |
revision |
根据组件、选中 facet 标识、已有协议声明和绑定生成的摘要 |
每个问题包含类别、级别、相关组件和说明，并可附带字段路径。有 error 时 compatible 为 false，只有 warning 时仍为 true。
Adapter 读取计划和问题列表，将兼容的计划交给 lifecycle。Lifecycle 按计划中的驱动与次序激活 facets，并在激活过程中调用 core 完成实际协议协商。实例、注册项及其释放由 lifecycle 管理。
compose(input, rules?) 是生成计划的入口。CompositionInput 汇集组件、环境信息和策略；第二个参数提供组合规则目录，省略时使用空目录。
CompositionRuleCatalog.register() 登记规则并返回撤销函数，resolve() 按坐标查找规则。同一坐标必须（MUST）至多登记一条规则。
具体输入字段、规则方法、排序算法和计划字段的使用方式见实现说明。组件声明的结构见manifest 组件设计。