mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
docs: propose experimental plugin group
This commit is contained in:
Turtle
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# 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/proposed/architecture/2026-07-28-experimental-plugin-package-group.md
|
||||
2026-07-28-experimental-plugin-package-group.md: e0a17206bf4ffd424d6dd449023001fd48eb3260
|
||||
2026-07-28-experimental-plugin-package-group.zh.md: 1850e94c91908865c833b7dc1583460babbb32f1
|
||||
@@ -0,0 +1,35 @@
|
||||
# Agent Note: Experimental plugin package group
|
||||
|
||||
Status: proposed
|
||||
|
||||
English | [中文](2026-07-28-experimental-plugin-package-group.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
The [package hierarchy](../../../../packages/README.md) groups plugins by product role, but it cannot distinguish supported plugins from prototypes whose contracts and continued existence remain unsettled. After the first tagged release, contributors still need an obvious place for useful experiments that carry no stability, compatibility, migration, or support warranty.
|
||||
|
||||
## Proposal
|
||||
|
||||
Add `packages/experimental/<pkg>/` as the required home for Cordis plugin packages whose whole public contract is experimental. Package names remain `@deepseek-ai/dsh-<pkg>`; promotion moves the package into its product-role group without renaming it.
|
||||
|
||||
Experimental packages carry no stability, compatibility, migration, or support promise: they may change APIs, configuration, or data, or disappear, without deprecation or migration. This status does not relax engineering standards; these packages retain the repository's type, test, security, documentation, lifecycle, and snapshot requirements. Non-experimental packages must not take runtime dependencies on them. Examples may use them; any other runtime dependent is itself experimental and belongs under `packages/experimental/`. Tests may use them as development dependencies.
|
||||
|
||||
Examples include the pending `@deepseek-ai/dsh-tui-session-changes` `/diff` viewer and the `/btw` plugin; if accepted, they land in this group. A release never promotes a package implicitly. Promotion requires explicit review of the public contract, limitations, test evidence, and a named owner accepting stable-package obligations.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Keep experiments in product-role groups with README labels.** Labels are easy to miss and cannot enforce dependency boundaries.
|
||||
|
||||
**Treat every package as experimental until the first tagged release.** This provides no durable incubation boundary.
|
||||
|
||||
**Develop experiments elsewhere.** This loses the real plugin graph, examples, snapshots, and lifecycle checks needed to evaluate them.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- `packages/experimental/` has a concise group README defining the package-level status, all four disclaimed promises, and the promotion rule.
|
||||
- Constraints require every experimental plugin package and every non-example runtime dependent of one to live there.
|
||||
- Package and user documentation label experimental plugins and avoid stability, compatibility, migration, or support promises.
|
||||
|
||||
## Risks
|
||||
|
||||
The group can become a junk drawer or let “experimental” excuse weak engineering. The repository's [current-owner/current-need rule](../../../../packages/AGENTS.md) and unchanged engineering gates limit that risk. Promotion causes path churn, but the npm name remains stable.
|
||||
@@ -0,0 +1,35 @@
|
||||
# Agent Note: 实验性插件包（package）分组
|
||||
|
||||
Status: proposed
|
||||
|
||||
[English](2026-07-28-experimental-plugin-package-group.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
[包层级结构](../../../../packages/README.md)按产品角色对插件分组，但无法区分受支持的插件和契约与去留均未确定的原型。首个带标签的版本发布后，贡献者仍需要一个明确的位置存放有价值的实验性插件；这些插件不提供稳定性、兼容性、迁移或支持保证。
|
||||
|
||||
## 提案
|
||||
|
||||
新增 `packages/experimental/<pkg>/`，并要求公开契约整体处于实验阶段的 Cordis 插件包全部放在其中。包名仍为 `@deepseek-ai/dsh-<pkg>`；提升为稳定插件时，只将包移入对应的产品角色分组，不对其重命名。
|
||||
|
||||
实验性包不提供稳定性、兼容性、迁移或支持保证：其 API、配置和数据可以变更，包也可以移除，均不提供弃用期或迁移路径。实验性状态不表示降低工程标准；这些包仍须满足仓库对类型、测试、安全、文档、生命周期和快照的要求。非实验性包不得将其列为运行时依赖。示例包可以使用它们；其他任何运行时依赖方本身也必须是实验性包，并位于 `packages/experimental/` 下。测试可以将其用作开发依赖。
|
||||
|
||||
示例包括尚待完成的 `@deepseek-ai/dsh-tui-session-changes` `/diff` 查看器和 `/btw` 插件；如果获准合入，它们将直接进入该分组。发布不会自动将包提升为稳定状态。提升前必须明确评审其公开契约、限制和测试证据，并指定一名愿意承担稳定包义务的负责人。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
**将实验性插件留在产品角色分组中，并用 README 标注。** 标注容易被忽略，也无法强制执行依赖边界。
|
||||
|
||||
**首个版本发布前，将所有包都视为实验性。** 这无法提供持久的孵化边界。
|
||||
|
||||
**在其他位置开发实验性插件。** 这会失去评估它们所需的真实插件图、示例、快照和生命周期检查。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- `packages/experimental/` 包含一份简明的分组 README，定义包级状态、明确排除的四类保证以及提升规则。
|
||||
- 约束规则要求所有实验性插件包及其所有非示例运行时依赖方位于该目录。
|
||||
- 包文档和用户文档标明插件的实验性状态，且不作稳定性、兼容性、迁移或支持承诺。
|
||||
|
||||
## 风险
|
||||
|
||||
该分组可能无序积累原型，也可能让「实验性」成为降低工程标准的借口。仓库已有的[「必须有当前负责人和实际需求」规则](../../../../packages/AGENTS.md)以及不变的工程门禁可限制这项风险。提升为稳定插件会导致路径变动，但 npm 包名保持稳定。
|
||||
Reference in New Issue
Block a user