AI 范围身份

状态：已准入，构建中 (Admitted, in build-out)

AIScopeRef 已在内核层面获得准入 (P-AISC-001..P-AISC-005)。第一阶段模组范围的 AI 配置目前正在运行； 其余范围类型（应用、模块、特性）已作为方向获得准入，其消费端界面正在积极构建中。

AIScopeRef 是什么

AIScopeRef 是 AI 配置范围的规范身份契约。它通过一个不依赖于瞬态 UI 状态的稳定、唯一键来回答：“这是谁的 AI 配置？”

AIScopeRef {
  kind: 'app' | 'mod' | 'module' | 'feature'
  ownerId: string
  surfaceId?: string
}

kind + ownerId + surfaceId? 三元组在整个系统中构成一个稳定的唯一键。

封闭的类型枚举

kind	所有者身份	备注
app	应用身份	surfaceId 可用于标识应用内部独立的 AI 特性界面
mod	稳定的模组清单 ID	严禁使用路由页面 ID、标签页键、会话 ID、文档 ID、项目 ID、提示配置 ID 或配置文件 ID
module	独立的模块身份	仅当模块本身是规范所有者时
feature	跨应用/模组可复用特性所有者	不得碎片化本应由模组拥有的 AI 真理

kind 枚举是封闭的。应用、模组和消费者不能发明第五种类型。

第一阶段模组范围的规范形态

第一阶段模组范围 AI 配置的规范形态是固定的：

AIScopeRef {
  kind: 'mod'
  ownerId: <stable mod manifest id>
  surfaceId: 'workspace'
}

surfaceId: 'workspace' 代表模组的单一规范 AI 工作区。除非后续的内核规则明确定义替代方案，否则模组范围 AI 配置的消费者不得省略 surfaceId，也不得发明替代值。

范围身份为何重要

如果没有规范的范围身份，平台最终将陷入一堆即席键的混乱：“此 AI 配置属于模组 foo 会话 A 的第 3 个标签页”——这些键依赖于 UI 状态，无法在应用重启后存活，也无法在不同界面间保持一致的查找能力。

AIScopeRef 规则消除了这些故障模式：

规则	阻止的问题
封闭的 kind 枚举	消费者不能发明新的范围类型
要求稳定的模组清单 ID	UI 本地键不能成为 AI 范围身份
默认每个模组一个规范工作区	标签页/会话/线程的激增不会造成隐式范围爆炸
无隐式继承	范围 A 的配置不会隐式回退到范围 B
所有者驱动的生命周期	范围的创建/销毁与所有者实体的生命周期绑定

无隐式继承

范围之间没有继承链。每个范围的 AIConfig 都完全具体化。如果产品需要“从父范围继承默认值”的用户体验，其实现方式是配置文件应用（写时复制）——绝不是运行时回退链。

跨界面适用性

AIScopeRef 统一适用于桌面端和网页端。界面特定的行为差异存在于各自的内核契约中；本契约不引入界面特定的规则。

允许的消费者

AIScopeRef 可由以下消费者使用：

消费者	用途
桌面内核	AIConfig 键控存储和 UI 范围选择
SDK 内核	类型化的 config / profile / snapshot API 范围参数
运行时内核	执行快照范围证据

消费者不得使用消费者本地字段扩展 AIScopeRef 模式。注解需求应存储在独立的消费者本地注解记录中——绝不能通过修改 AIScopeRef 来实现。

使用场景：模组配置其 AI 工作区

模组开发者编写了一个在工作区界面中使用 AI 的模组。

1. 清单身份。 模组附带一个稳定的清单 ID（例如 com.example.notes）。
2. 范围身份。 桌面端将模组的 AI 配置桥接到 AIScopeRef{ kind: 'mod', ownerId: 'com.example.notes', surfaceId: 'workspace' } 下。
3. 配置文件应用。 用户在 AI 配置 UI 中选择一个配置文件；配置文件（写时复制）应用到工作区范围的 AIConfig 中。
4. 持久化。 配置由规范范围身份作为键；它在应用重启后依然存在。

使用场景：具有多个工作区的模组（罕见）

假设一个模组确实托管了多个一流的 AI 工作区——每个工作区都有自己的配置文件应用/探测/快照历史。

1. 显式范围扩展。 模组准入多个 AIScopeRef{ kind: 'mod', ownerId: <清单>, surfaceId: <稳定的工作区名称> } 实例。
2. 稳定的工作区名称。 界面必须是人类可识别的；surfaceId 不是瞬态 UI 键。
3. 非按标签页/按会话/按文档。 如果用户只是在一个工作区内切换当前文档，那属于该工作区范围内的领域状态——而不是一个新的 AIScopeRef。

该契约正是通过防止范围扩散来维护配置的可靠性。

使用场景：范围生命周期与所有者绑定

用户卸载一个模组。

1. 所有者实体被销毁。 模组清单被移除。
2. 范围被销毁。 所有与该模组绑定的 AIScopeRef 实例同步销毁。
3. 绑定的 AIConfig 被清理。 与被销毁范围绑定的配置被失效或清理。没有悬空配置存留。

范围身份不做什么

• 它不跨消费者转移所有权。
• 它不允许范围之间进行运行时回退。
• 它不允许 UI 键成为范围身份。
• 它不允许范围 A 的 AIConfig 将范围 B 的配置作为回退引用。
• 它不允许消费者使用自己的字段扩展模式。

职责边界摘要

关注点	所有者
AIScopeRef 模式 + 身份规则	平台 (P-AISC-*)
由 AIScopeRef 键控的 AIConfig 存储	桌面内核
SDK 配置/配置文件/快照 API 上的范围参数	SDK 内核
执行快照范围证据	运行时内核

来源依据

• .nimi/spec/platform/kernel/ai-scope-contract.md
• .nimi/spec/platform/kernel/ai-last-mile-contract.md