refactor(core): group APIs and document design

Author: LogosTopos

docs/core-guide.zh.md

@@ -49,7 +49,7 @@ Core 提供共同的声明外壳和协商入口。领域协议负责解释自身
 
 ```ts
 interface ProtocolDeclaration {
-  readonly participant: ParticipantIdentity
+  readonly participant: { readonly id: string }
   readonly requires?: readonly ProtocolRequirement[]
   readonly supports?: readonly ProtocolSupport[]
 }
@@ -141,22 +141,20 @@ Core 只要求身份在当前协商范围内唯一。身份如何认证、是否
 
 Manifest facet 不是 participant。Facet 是发行物中的静态声明和激活单位；participant 是 coordinator 为 activation instance 创建、实际参加某次协商的运行实体。组件模型第一版令一个 activation instance 对应一个本地 participant；同一 facet 的多次激活仍会产生不同 participants。产品也可以产生没有 manifest facet 的内建 participant。
 
-Core 不把 component id、facet name 或进程位置规定为 `ParticipantIdentity` 的固定字段。需要归属信息的实现通过 lifecycle/provenance 保存本地关联；向连接对端公开哪些关联由 connection view 和 policy 决定。
+Core 不把 component id、facet name 或进程位置规定为 participant 身份的固定字段。需要归属信息的实现通过 lifecycle/provenance 保存本地关联；向连接对端公开哪些关联由 connection view 和 policy 决定。
 
 ### Protocol definition
 
 `ProtocolDefinition` 是 evaluator 对一份领域协议的本地解释。概念接口如下：
 
 ```ts
-interface ProtocolValidationContext extends ApiReference {}
-
 interface ProtocolDefinition<RequirementSpec = unknown, SupportSpec = unknown, Agreement = unknown>
   extends ApiReference {
   readonly accepts?: readonly string[]
-  validateRequirement(spec: unknown, context: ProtocolValidationContext): RequirementSpec
-  validateSupport(spec: unknown, context: ProtocolValidationContext): SupportSpec
-  readonly validateAgreement?: (agreement: unknown, context: ProtocolValidationContext) => Agreement
-  negotiate(input: ProtocolNegotiationInput<RequirementSpec, SupportSpec>): ProtocolNegotiationResult<Agreement>
+  validateRequirement(spec: unknown, context: ApiReference): RequirementSpec
+  validateSupport(spec: unknown, context: ApiReference): SupportSpec
+  readonly validateAgreement?: (agreement: unknown, context: ApiReference) => Agreement
+  negotiate(input: ProtocolNegotiationInput<RequirementSpec, SupportSpec>): ProtocolNegotiationOutcome<Agreement>
 }
 ```
 
@@ -248,6 +246,17 @@ Core 不能独自判断领域协议是否真正兼容。Evaluator 必须安装
 
 ## Implementation boundary
 
+TypeScript 参考实现按用途提供四个入口：
+
+| 入口 | 内容 |
+| --- | --- |
+| `@dsh-std/core` | 协议声明、definition、catalog 与协商报告 |
+| `@dsh-std/core/identity` | 协议坐标的校验、比较与索引键 |
+| `@dsh-std/core/json` | 协议 JSON 数据校验与冻结快照 |
+| `@dsh-std/core/version` | 组件包的 SemVer 与版本范围工具 |
+
+参与者身份直接使用 `{ id }`，评估器身份直接使用 `{ name, version }`。校验上下文使用 `ApiReference`，协商输入的每行直接包含 participant 和相应 requirement 或 support。
+
 `@dsh-std/core` 的参考实现只保留通用协议标识、声明、definition catalog 与协商分派。早期原型中的 `DshResource`、`ExecutionPlane`、插件关系、`PluginRegistry` 和 `RuntimeSnapshot` 已迁移出 core：
 
 - 静态插件包声明和关系进入 manifest/composition；

docs/proposals/core.zh.md

@@ -159,7 +159,7 @@ interface ParticipantImplementationEndpoint {
 }
 
 interface ParticipantLease {
-  readonly participant: ParticipantIdentity
+  readonly participant: { readonly id: string }
   readonly revision: number
   readonly signal: AbortSignal
 

docs/proposals/endpoint-connection.zh.md

@@ -55,7 +55,7 @@ interface EventEnvelope<Payload = unknown> {
   readonly apiVersion: string
   readonly kind: string
   readonly id: string
-  readonly source: ParticipantIdentity
+  readonly source: { readonly id: string }
   readonly sequence?: number
   readonly time?: string
   readonly payload: Payload

docs/proposals/events.zh.md

@@ -55,24 +55,22 @@
 
 `ProtocolDefinition.accepts` 可以把多个 `apiVersion` 映射到同一份 definition。每个被接受的版本仍与原 `kind` 组成独立坐标。Core 必须拒绝由不同 definitions 重复注册的相同坐标。
 
-Core 不得从 `apiVersion` 的 group、major、stability、revision 或字符串顺序推断兼容关系。`protocolFamilyKey()` 只提供分组键，不构成互操作声明。
+Core 不得从 `apiVersion` 的 group、major、stability、revision 或字符串顺序推断兼容关系。
 
 Definition 可以识别不同稳定度、不同 major，或由私有协议规定的离散版本集合。是否允许这些版本互操作完全由该协议的规范决定。
 
 ### 版本感知校验
 
-Core 调用 `validateRequirement` 和 `validateSupport` 时，必须同时提供包含原始 `apiVersion + kind` 的 `ProtocolValidationContext`。Definition 必须针对声明的准确版本校验 `spec`，不得先把旧版本静默投影为新版本再按新 schema 接受。
+Core 调用 `validateRequirement` 和 `validateSupport` 时，必须同时提供包含原始 `apiVersion + kind` 的 `ApiReference`。Definition 必须针对声明的准确版本校验 `spec`，不得先把旧版本静默投影为新版本再按新 schema 接受。
 
 概念接口如下：
 
 ```ts
-interface ProtocolValidationContext extends ApiReference {}
-
 interface ProtocolDefinition<RequirementSpec, SupportSpec, Agreement, Policy>
   extends ApiReference {
   readonly accepts?: readonly string[]
-  validateRequirement(spec: unknown, context: ProtocolValidationContext): RequirementSpec
-  validateSupport(spec: unknown, context: ProtocolValidationContext): SupportSpec
+  validateRequirement(spec: unknown, context: ApiReference): RequirementSpec
+  validateSupport(spec: unknown, context: ApiReference): SupportSpec
   negotiate(
     input: ProtocolNegotiationInput<RequirementSpec, SupportSpec, Policy>,
   ): ProtocolNegotiationOutcome<Agreement>
@@ -193,7 +191,7 @@ npm package version 与协议 `apiVersion` 是独立版本轴。更新 definitio
 
 ## 兼容性
 
-只识别主坐标并执行精确版本协商的既有 definitions 不受影响。为校验函数增加 `ProtocolValidationContext` 是向后兼容的调用扩展：现有只接收 `spec` 的 TypeScript 函数仍可作为 validator；新 definition 可以读取第二个参数进行版本专属校验。
+只识别主坐标并执行精确版本协商的既有 definitions 不受影响。为校验函数增加 `ApiReference` 是向后兼容的调用扩展：现有只接收 `spec` 的 TypeScript 函数仍可作为 validator；新 definition 可以读取第二个参数进行版本专属校验。
 
 把版本加入 `accepts` 是可观察的 definition 能力变更，但不自动建立任何兼容边。协议只有在规范、validator、协商器、agreement、fixtures 和方向性测试一致时，才能声称支持跨版本协商。
 

docs/proposals/version-compatibility.zh.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Updated core utility imports to the grouped public entry points.
+
 - Adapted lifecycle activation identities to carry a required generation while projecting UI contribution owners through the existing UI owner schema.
 
 ## 0.1.1-rc.4

packages/adapter-dsh/CHANGELOG.md

@@ -5,13 +5,8 @@ import { createElement as h, useEffect, useState, type ReactNode } from 'react'
 import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
 import type {} from '@deepseek-ai/dsh-client-ui-tool/client'
 import type { TypertRemoteContribution } from '@deepseek-ai/dsh-typert-protocol'
-import {
-  ProtocolCatalog,
-  defineProtocolDeclaration,
-  sameProtocol,
-  type ApiReference,
-  type NegotiatedProtocol,
-} from '@dsh-std/core'
+import { ProtocolCatalog, defineProtocolDeclaration, type ApiReference, type NegotiatedProtocol } from '@dsh-std/core'
+import { sameProtocol } from '@dsh-std/core/identity'
 import {
   defineComponentManifest,
   findFacet,

packages/adapter-dsh/src/client.ts

@@ -18,15 +18,8 @@ import type {
 import type {} from '@deepseek-ai/dsh-agent'
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
 import z from '@deepseek-ai/schemastery'
-import {
-  ProtocolCatalog,
-  defineProtocolDeclaration,
-  sameProtocol,
-  validateApiReference,
-  type ApiReference,
-  type ProtocolRequirement,
-  type ProtocolSupport,
-} from '@dsh-std/core'
+import { ProtocolCatalog, defineProtocolDeclaration, type ApiReference, type ProtocolRequirement, type ProtocolSupport } from '@dsh-std/core'
+import { sameProtocol, validateApiReference } from '@dsh-std/core/identity'
 import {
   ManifestDefinitionCatalog,
   defineComponentManifest,

packages/adapter-dsh/src/index.ts

@@ -2,6 +2,10 @@
 
 Changes to `@dsh-std/command` are recorded here.
 
+## Unreleased
+
+- Updated core utility imports to the grouped public entry points.
+
 ## 0.1.1-rc.1
 
 - Aligned the package with the workspace `0.1.1` prerelease line without changing the existing Command protocol semantics.

packages/command/CHANGELOG.md

@@ -5,7 +5,7 @@ import type {
   ProtocolIssue,
   ProtocolSupport,
 } from '@dsh-std/core'
-import { validateApiReference } from '@dsh-std/core'
+import { validateApiReference } from '@dsh-std/core/identity'
 import type { ManifestDefinitionCatalog, ManifestExtension } from '@dsh-std/manifest'
 import type {
   CapabilityCall,