Public package manifest fields
公共 package manifest 字段
Plugin authors need npm identity, runtime requirements, and DSH declarations from one public import. Internal image-packaging, Session catalog, and generated proxy metadata do not define extension points for community plugins. Exposing those fields together makes internal mechanisms appear available to external authors.
English
Problem
Plugin authors need npm identity, runtime requirements, and DSH declarations from one public import. Internal image-packaging, Session catalog, and generated proxy metadata do not define extension points for community plugins. Exposing those fields together makes internal mechanisms appear available to external authors.
Decision
DshPackageManifest describes the package.json fields DSH uses, with required name and version. Its optional dsh member uses DshManifest for public composition and author metadata. The type is a selected npm field set, not a complete package.json schema. App-boot adapts it with Partial for local profiles, which need no published identity.
Runtime requirements live at top-level engines: dsh, node, and npm are optional version strings, and other engine names are allowed. dsh.manifestVersion identifies declaration format 1. Format and DSH compatibility declarations are not enforced by current installers or loaders.
The image packer owns configTrees, and the workspace catalog generator owns Session migration declarations. Their existing on-disk keys remain readable by those internal tools, but the public manifest types do not expose them.
Each consumer owns JSON parsing, field validation, default resolution, and adaptation to runtime data. Interfaces do not validate parsed JSON. A helper belongs in the shared package only when multiple consumers need the same validation or normalization; getters that repeat property access add no shared policy.
Alternatives considered
Keep internal metadata in the public declaration. A workspace-only migration catalog and an experimental image packer cannot offer public plugin behavior merely because their metadata is discoverable.
Put DSH compatibility under dsh.engines. VS Code places its host requirement in top-level engines.vscode. Top-level engines.dsh gives authors one location for runtime requirements; DSH still owns enforcement of its custom key.
Use peer dependencies as the sole host requirement. Peer dependencies constrain installed npm packages, including the CLI package @deepseek-ai/dsh. They do not identify the currently running DSH process when plugins live in a separate profile project.
Parse every domain through one mandatory parser. Existing readers consume different subsets and own different errors and defaults. Combining them would make a client reader validate unrelated profile declarations. The public types remain independent of filesystem access and parsing policy.
Consequences
External authors gain a complete package-level declaration and a smaller DSH author API. Consumers of removed internal types must use their owning implementations. The packer and repository catalog no longer depend on the public declaration package; app-boot retains a production dependency because its published profile type references it.
Compiler and built NodeNext import checks verify required package identity, partial profiles, top-level engine declarations, and the absence of internal fields from the public API. Existing profile, packer, and Session catalog tests retain coverage of their accepted files and malformed declarations. No Session format, plugin loading rule, or model-visible behavior changes.
中文
问题
插件作者需要从统一的公共导入路径获取 npm 身份、运行时要求和 DSH 声明。内部镜像打包、Session 目录和生成的代理元数据不定义社区插件扩展点。将这些字段一起暴露，会让外部作者误以为内部机制也可供使用。
决策
DshPackageManifest 描述 DSH 使用的 package.json 字段，其中 name 和 version 必填。其可选的 dsh 成员使用 DshManifest 描述公共组合与作者元数据。该类型只选取所需 npm 字段，不是完整的 package.json schema（模式）。App-boot 通过 Partial 适配无需发布身份的本地 profile。
运行时要求位于顶层 engines：dsh、node 和 npm 均为可选版本字符串，也允许其他 engine 名称。dsh.manifestVersion 标识声明格式 1。当前安装器和加载器不强制检查格式与 DSH 兼容性声明。
镜像打包器拥有 configTrees，工作区目录生成器拥有 Session 迁移声明。这些内部工具仍可读取既有磁盘字段，但公共 manifest 类型不暴露这些字段。
各消费方负责 JSON 解析、字段校验、默认值解析和运行时数据适配。接口不会校验已解析的 JSON。只有多个消费方需要相同校验或归一化时，helper 才属于共享包；重复属性访问的 getter 不提供共享策略。
考虑过的替代方案
将内部元数据保留在公共声明中。 仅限工作区的迁移目录和实验性镜像打包器，不会因为其元数据可被发现就提供公共插件行为。
将 DSH 兼容性放在 dsh.engines 下。 VS Code 将宿主要求放在顶层 engines.vscode。顶层 engines.dsh 让作者在同一位置声明运行时要求；自定义键的检查仍由 DSH 负责。
仅用 peer dependency 声明宿主要求。 Peer dependency 约束已安装的 npm 包，包括 CLI 包 @deepseek-ai/dsh。插件位于独立 profile 项目时，它们无法标识当前运行的 DSH 进程。
通过统一的强制解析器解析所有领域。 现有读取方消费不同字段子集，并各自拥有错误与默认值。合并它们会让客户端读取方校验无关的 profile 声明。公共类型保持独立于文件系统访问和解析策略。
后果
外部作者获得完整的包级声明和更小的 DSH 作者 API。已移除内部类型的消费方必须使用各自负责的实现。打包器与仓库目录不再依赖公共声明包；app-boot 保留生产依赖，因为其发布的 profile 类型引用该包。
编译器和构建后的 NodeNext 导入检查验证包身份必填、部分 profile、顶层 engine 声明，以及公共 API 不含内部字段。现有 profile、打包器和 Session 目录测试继续覆盖其接受的文件与畸形声明。Session 格式、插件加载规则和模型可见行为均不改变。