feat(manifest): declare plugin format, tags, and host compatibility
This commit is contained in:
Yichen Jiang committed
1 parent
9b308c9568
commit
220678e57d
8 files changed
+55
-6
No files matched your search
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-05-package-manifest-types.md
|
||||
2026-09-05-package-manifest-types.md: 94317a9317ba12059e726612840e4a001be2a892
|
||||
2026-09-05-package-manifest-types.zh.md: 2c40facd2591921123b5eae71b80c516f3b1f697
|
||||
2026-09-05-package-manifest-types.md: 5e9834583a75a3fd4f1ec69379628c49d264e05b
|
||||
2026-09-05-package-manifest-types.zh.md: 8a2399a19a097113d45f4915631d36ca30191dd5
|
||||
@@ -12,6 +12,8 @@ External packages need Harness manifest types without depending on boot or clien
|
||||
|
||||
[`@deepseek-ai/dsh-package-manifest`](../../../../packages/util/package-manifest/README.md) owns `DshManifest` and its member declarations in one type-only file. The package belongs to the existing utility group and exports no runtime values. Author declarations and launcher-generated module fallback metadata are explicitly distinguished.
|
||||
|
||||
Author metadata stays under `package.json.dsh`: optional `manifestVersion` identifies format `1`, `categories` carries free-form discovery tags, and `engines.dsh` declares compatible host versions as a SemVer range. Npm package identity and Node requirements retain their top-level fields. Categories are extensible tags rather than a closed role enum, so labels such as `skills` and `tools` do not constrain package composition.
|
||||
|
||||
Readers import the shared declarations directly. Boot retains profile loading, raw JSON checks, defaults, and resolved runtime data. Client modules retain their normalized boot graph. The image packer resolves declared paths into directories. The Session catalog generator derives a read-only validated entry with a resolved import path; raw inputs and discovery rules remain local.
|
||||
|
||||
App-boot declares a production dependency because its published declarations reference the shared types. Client modules, the private packer, and root scripts use development dependencies because their published APIs do not expose these types. Every package consumer has a TypeScript project reference. External authors import from the utility package; app-boot provides no compatibility re-exports.
|
||||
@@ -29,3 +31,5 @@ App-boot declares a production dependency because its published declarations ref
|
||||
Authors gain one public import path at the cost of a published package and explicit dependency edges. Existing app-boot manifest type imports must use the new package. The [profile composition design](2026-08-05-profile-plugin-bundles.md) continues to own runtime semantics; type extraction does not change configuration acceptance or model-visible behavior.
|
||||
|
||||
Compiler and packaged NodeNext consumer checks cover public imports. Existing profile, client, image configuration, and Session catalog tests cover reader behavior; documentation checks cover the utility classification and generated package catalogs. Optional declaration fields still require deliberate consumer updates when added.
|
||||
|
||||
Manifest format and host compatibility declarations have no enforcement in current installers or loaders. The type-only package supplies neither a SemVer parser nor an installation policy; its README records that limitation so an author declaration is not mistaken for a compatibility check.
|
||||
@@ -12,6 +12,8 @@ Status: implemented
|
||||
|
||||
[`@deepseek-ai/dsh-package-manifest`](../../../../packages/util/package-manifest/README.zh.md) 在一个纯类型文件中拥有 `DshManifest` 及其成员声明。本包属于现有工具库分组，不导出运行时值。作者声明与启动器生成的模块后备元数据有明确区分。
|
||||
|
||||
作者元数据保留在 `package.json.dsh` 下：可选的 `manifestVersion` 标识格式 `1`，`categories` 承载自由发现标签，`engines.dsh` 以 SemVer 范围声明兼容的宿主版本。npm 包身份和 Node 要求沿用顶层字段。Categories 是可扩展标签，而非封闭的角色枚举，因此 `skills`、`tools` 等标签不限制包的组合。
|
||||
|
||||
各读取方直接导入共享声明。启动器保留 profile 加载、原始 JSON 检查、默认值和解析后的运行时数据。客户端模块保留归一化的启动图。镜像打包器将声明路径解析为目录。Session 目录生成器派生带有已解析导入路径的只读校验结果；原始输入和发现规则仍由本地负责。
|
||||
|
||||
App-boot 声明生产依赖，因为其发布的声明文件引用共享类型。客户端模块、私有打包器和根脚本使用开发依赖，因为其发布 API 不暴露这些类型。每个包消费方都有 TypeScript 项目引用。外部作者从工具包导入；app-boot 不提供兼容性再导出。
|
||||
@@ -29,3 +31,5 @@ App-boot 声明生产依赖，因为其发布的声明文件引用共享类型
|
||||
作者获得统一的公共导入路径，代价是一个发布包和明确的依赖边。已有的 app-boot manifest 类型导入需要改用新包。[Profile 组合设计](2026-08-05-profile-plugin-bundles.zh.md) 继续负责运行时语义；类型提取不改变配置接受范围或模型可见行为。
|
||||
|
||||
编译器与打包后的 NodeNext 消费方检查覆盖公共导入。已有 profile、客户端、镜像配置和 Session 目录测试覆盖读取行为；文档检查覆盖工具库分类与生成的包目录。新增可选声明字段时，仍需主动更新消费方。
|
||||
|
||||
当前安装器和加载器不强制检查 manifest 格式或宿主兼容性声明。纯类型包既不提供 SemVer 解析器，也不提供安装策略；其 README 记录此限制，避免将作者声明误认为兼容性检查。
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/util/package-manifest/README.md
|
||||
README.md: 971df84d7db3205eb8be75ba895046d4151780d2
|
||||
README.zh.md: 8989cbe9bc29bbf8112d5465eac9806c211fa88d
|
||||
README.md: 428ed05af9856d4a1a77be9c152130fa26464bb9
|
||||
README.zh.md: cdf6302b537a458c010f5cd8b3531131fc6a21ac
|
||||
@@ -32,12 +32,25 @@ import type { DshClientManifest, DshManifest } from '@deepseek-ai/dsh-package-ma
|
||||
|
||||
const client: DshClientManifest = { platform: 'web' }
|
||||
const dsh: DshManifest = {
|
||||
manifestVersion: 1,
|
||||
categories: ['skills', 'tools'],
|
||||
engines: { dsh: '0.1.5-alpha.1' },
|
||||
bundle: { patch: './cordis.patch.yml' },
|
||||
client,
|
||||
}
|
||||
```
|
||||
|
||||
`DshManifest` describes `bundle`, `profile`, `client`, `configTrees`, `sessionFormatMigration`, and `moduleFallback`, not the surrounding npm manifest. `moduleFallback` is launcher-generated metadata and is not an author configuration entry. TypeScript checks this object and erases `import type` during compilation; JSON files cannot import types, and this example does not write a `package.json`. See [`src/types.ts`](src/types.ts) for the declarations.
|
||||
`DshManifest` describes `package.json.dsh`; npm fields such as `name`, `version`, and `engines.node` stay at the package root. TypeScript checks this object and erases `import type` during compilation; JSON files cannot import types, and this example does not write a `package.json`.
|
||||
|
||||
All three author metadata fields are optional. Omitting them leaves the format version, tags, or compatible host versions undeclared; readers do not infer defaults.
|
||||
|
||||
| Field | Meaning |
|
||||
|---|---|
|
||||
| `manifestVersion` | Manifest format identifier; the declared format is `1`, independent of the npm package version and Session format version. |
|
||||
| `categories` | Free-form discovery tags such as `skills` and `tools`, with no fixed taxonomy or effect on plugin loading. |
|
||||
| `engines.dsh` | Author-declared compatible DSH versions as a SemVer range. An exact prerelease version is valid; the `dsh` member is required when `engines` is present. |
|
||||
|
||||
Composition and build declarations are defined in [`src/types.ts`](src/types.ts). `moduleFallback` is launcher-generated metadata and is not an author configuration entry.
|
||||
|
||||
-----
|
||||
|
||||
@@ -73,6 +86,7 @@ Type declarations add no model input, so provider cache reuse is unaffected.
|
||||
<a id="known-limitations-and-deferred-work"></a>
|
||||
|
||||
- **Static typing only.** These declarations do not validate JSON, check file existence, or supply defaults. `configTrees` serves the experimental image packer, and `sessionFormatMigration` is discovered only for workspace migration packages; declaring them does not register external plugin behavior.
|
||||
- **Compatibility is declarative.** Current installers and loaders do not enforce `manifestVersion` or `engines.dsh`; declaring a range does not reject incompatible hosts or validate SemVer syntax.
|
||||
|
||||
<a id="dev-note"></a>
|
||||
### Dev Note
|
||||
|
||||
@@ -32,12 +32,25 @@ import type { DshClientManifest, DshManifest } from '@deepseek-ai/dsh-package-ma
|
||||
|
||||
const client: DshClientManifest = { platform: 'web' }
|
||||
const dsh: DshManifest = {
|
||||
manifestVersion: 1,
|
||||
categories: ['skills', 'tools'],
|
||||
engines: { dsh: '0.1.5-alpha.1' },
|
||||
bundle: { patch: './cordis.patch.yml' },
|
||||
client,
|
||||
}
|
||||
```
|
||||
|
||||
`DshManifest` 描述 `bundle`、`profile`、`client`、`configTrees`、`sessionFormatMigration` 和 `moduleFallback`，不包含外层 npm manifest。`moduleFallback` 是启动器生成的元数据，不是作者配置项。TypeScript 检查该对象，并在编译时删除 `import type`；JSON 文件不能导入类型，此示例也不会写入 `package.json`。声明见 [`src/types.ts`](src/types.ts)。
|
||||
`DshManifest` 描述 `package.json.dsh`；`name`、`version`、`engines.node` 等 npm 字段仍位于包的顶层。TypeScript 检查该对象，并在编译时删除 `import type`；JSON 文件不能导入类型，此示例也不会写入 `package.json`。
|
||||
|
||||
这三个作者元数据字段均可选。省略时，格式版本、标签或兼容的宿主版本保持未声明状态；读取方不推断默认值。
|
||||
|
||||
| 字段 | 含义 |
|
||||
|---|---|
|
||||
| `manifestVersion` | manifest（元数据清单）格式标识；声明的格式为 `1`，独立于 npm 包版本和 Session 格式版本。 |
|
||||
| `categories` | `skills`、`tools` 等自由发现标签，无固定分类体系，不影响插件加载。 |
|
||||
| `engines.dsh` | 作者声明的兼容 DSH 版本，使用 SemVer 范围。可填写精确的预发布版本；存在 `engines` 时，必须填写 `dsh` 成员。 |
|
||||
|
||||
组合与构建声明定义在 [`src/types.ts`](src/types.ts) 中。`moduleFallback` 是启动器生成的元数据，不是作者配置项。
|
||||
|
||||
-----
|
||||
|
||||
@@ -73,6 +86,7 @@ const dsh: DshManifest = {
|
||||
<a id="known-limitations-and-deferred-work"></a>
|
||||
|
||||
- **仅提供静态类型。** 这些声明不校验 JSON、不检查文件存在性，也不提供默认值。`configTrees` 服务于实验性镜像打包器，`sessionFormatMigration` 仅从工作区迁移包中发现；声明它们不会注册外部插件行为。
|
||||
- **兼容性仅作声明。** 当前安装器和加载器不强制检查 `manifestVersion` 或 `engines.dsh`；声明范围不会拒绝不兼容的宿主，也不会校验 SemVer 语法。
|
||||
|
||||
<a id="dev-note"></a>
|
||||
### 开发备注
|
||||
|
||||
@@ -7,6 +7,7 @@ export type {
|
||||
DshBundleManifest,
|
||||
DshClientManifest,
|
||||
DshConfigTreeDeclaration,
|
||||
DshEnginesManifest,
|
||||
DshManifest,
|
||||
DshModuleFallbackManifest,
|
||||
DshProfileManifest,
|
||||
|
||||
@@ -6,6 +6,12 @@
|
||||
|
||||
/** The `dsh` property of an npm manifest; a package may declare several roles. */
|
||||
export interface DshManifest {
|
||||
/** Manifest format version, independent of the npm package and Session format versions. */
|
||||
manifestVersion?: 1
|
||||
/** Free-form discovery tags, such as `skills` or `tools`; do not affect plugin loading. */
|
||||
categories?: string[]
|
||||
/** Declared host compatibility; current readers do not enforce version ranges. */
|
||||
engines?: DshEnginesManifest
|
||||
/** Bundle metadata consumed by the profile launcher. */
|
||||
bundle?: DshBundleManifest
|
||||
/** Profile metadata consumed by the profile launcher. */
|
||||
@@ -23,6 +29,12 @@ export interface DshManifest {
|
||||
moduleFallback?: DshModuleFallbackManifest
|
||||
}
|
||||
|
||||
/** Host version requirements declared by the package author. */
|
||||
export interface DshEnginesManifest {
|
||||
/** Compatible DSH versions as a SemVer range, including an exact version. */
|
||||
dsh: string
|
||||
}
|
||||
|
||||
/** The configuration layer exported by a bundle package. */
|
||||
export interface DshBundleManifest {
|
||||
/** Patch file path relative to the declaring package root. */
|
||||
|
||||
Reference in new issue
Block a user