docs: implement experimental and internal package group
This commit is contained in:
Turtle
+6
@@ -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/implemented/architecture/2026-07-28-experimental-plugin-package-group.md
|
||||
2026-07-28-experimental-plugin-package-group.md: 3bc455eb2b676a1fb6d64117b7e9a7f390a6da83
|
||||
2026-07-28-experimental-plugin-package-group.zh.md: f204ecd052de03d0cf347e2c770feb0ea33966c7
|
||||
+33
@@ -0,0 +1,33 @@
|
||||
# Agent Note: Experimental and internal package group
|
||||
|
||||
Status: implemented
|
||||
|
||||
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 release packages from prototypes or internal-only packages. The team needs an obvious shared place for useful work that is not part of the official release.
|
||||
|
||||
## Decision
|
||||
|
||||
The subtree rules in [`packages/experimental/AGENTS.md`](../../../../packages/experimental/AGENTS.md) make `packages/experimental/<pkg>/` the required home for Cordis plugin packages whose whole public contract is experimental or internal-only. Package names remain `@deepseek-ai/dsh-<pkg>`.
|
||||
|
||||
The group is the team's in-repository place to share engineering and product-manager prototypes: members can discover, run, review, and extend one another's work against the real plugin graph without implying product support.
|
||||
|
||||
Official releases exclude this directory. A package enters a release only after moving to its product-role group; release packages cannot take runtime dependencies on packages here. Examples may use them, while any other runtime dependent also belongs here. Tests may use them as development dependencies.
|
||||
|
||||
Experimental packages carry no stability, compatibility, migration, or support promise: they may change APIs, configuration, or data, or disappear without deprecation or migration. Internal-only packages may define narrower internal contracts but make no public release promise. Neither status relaxes engineering, security, documentation, lifecycle, testing, or snapshot requirements.
|
||||
|
||||
The pending `@deepseek-ai/dsh-tui-session-changes` `/diff` viewer and `/btw` plugin are examples governed by this rule. Promotion into an official release requires explicit review of the public contract, limitations, test evidence, and a named owner accepting stable-package obligations.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Keep experimental and internal-only packages 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 prototypes and internal packages elsewhere.** This loses the real plugin graph, examples, snapshots, and lifecycle checks needed to evaluate them.
|
||||
|
||||
## Consequences
|
||||
|
||||
The path makes release exclusion and dependency blast radius visible while retaining the real plugin graph for team sharing. It gives up product-role colocation and creates path churn on promotion, while the npm name remains stable. The subtree rules, repository [current-owner/current-need rule](../../../../packages/AGENTS.md), and unchanged engineering gates limit junk-drawer growth. Because official release tooling does not yet exist, contributor policy enforces the exclusion; the directory is its required exclusion boundary when added.
|
||||
+33
@@ -0,0 +1,33 @@
|
||||
# Agent Note: 实验性与内部专用包（package）分组
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-07-28-experimental-plugin-package-group.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
[包层级结构](../../../../packages/README.md)按产品角色对插件分组，但无法区分发布包、原型和内部专用包。团队需要一个明确的共享位置，存放不属于官方发布版本的有价值成果。
|
||||
|
||||
## 决策
|
||||
|
||||
[`packages/experimental/AGENTS.md`](../../../../packages/experimental/AGENTS.md) 中的子树规则要求所有公开契约整体处于实验状态或仅限内部使用的 Cordis 插件包位于 `packages/experimental/<pkg>/`。包名仍为 `@deepseek-ai/dsh-<pkg>`。
|
||||
|
||||
该分组供团队在仓库内共享工程人员和产品经理制作的原型：成员可以基于真实插件图发现、运行、评审并扩展彼此的原型，但这不代表产品会提供支持。
|
||||
|
||||
官方发布版本不包含此目录。包只有移入对应的产品角色分组后才会纳入发布版本；发布包不得在运行时依赖此处的包。示例可以使用这些包；其他任何运行时依赖方也必须位于此处。测试可以将它们用作开发依赖。
|
||||
|
||||
实验性包不提供稳定性、兼容性、迁移或支持保证：其 API、配置或数据可以变更，包也可以移除，均不提供弃用期或迁移路径。内部专用包可以定义范围更窄的内部契约，但不作公开发布承诺。无论哪种状态，都不降低仓库对工程、安全、文档、生命周期、测试或快照的要求。
|
||||
|
||||
尚待完成的 `@deepseek-ai/dsh-tui-session-changes` `/diff` 查看器和 `/btw` 插件都受这项规则约束。将包提升为稳定包并纳入官方发布版本，需要明确评审其公开契约、限制和测试证据，并指定一名愿意承担稳定包义务的负责人。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
**将实验性和内部专用包留在产品角色分组中，并用 README 标注。** 标注容易被忽略，也无法强制执行依赖边界。
|
||||
|
||||
**首个带标签的版本发布前，将所有包都视为实验性。** 这无法提供持久的孵化边界。
|
||||
|
||||
**在其他位置开发原型和内部专用包。** 这会失去评估它们所需的真实插件图、示例、快照和生命周期检查。
|
||||
|
||||
## 后果
|
||||
|
||||
该路径明确标示不纳入发布版本的包及其依赖影响范围，同时保留供团队共享成果的真实插件图。代价是这些包无法与同产品角色的包共置，提升并纳入发布版本时还会产生路径变动，但 npm 包名保持稳定。子树规则、仓库已有的[「必须有当前负责人和实际需求」规则](../../../../packages/AGENTS.md)以及保持不变的工程门禁，可限制该分组无序膨胀。由于官方发布工具尚不存在，目前由贡献者政策执行这项排除规则；添加发布工具后，必须以该目录为排除边界。
|
||||
-6
@@ -1,6 +0,0 @@
|
||||
# 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: e3c6f350bd8c8341e0da831159044e2f32e914f9
|
||||
2026-07-28-experimental-plugin-package-group.zh.md: f92683316e1acbaf01d903e8dda37801e4b3d238
|
||||
@@ -1,37 +0,0 @@
|
||||
# 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.
|
||||
|
||||
The group is also the team's in-repository place to share prototypes: members can discover, run, review, and extend one another's work against the real plugin graph without implying product support.
|
||||
|
||||
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.
|
||||
-37
@@ -1,37 +0,0 @@
|
||||
# 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 包名保持稳定。
|
||||
@@ -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/README.md
|
||||
README.md: f5420b6f2f30837b030a0e832a438c34674a6f23
|
||||
README.zh.md: 7beeaadf380a742cbdb6447553f42692a97fad10
|
||||
README.md: 706d741b87bd22656580419eb43a493c1ab2933a
|
||||
README.zh.md: c41a15dcb743d024348d5a8a8c105b37e694205b
|
||||
+2
-1
@@ -44,11 +44,12 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
|
||||
| [`sdk/`](sdk/README.md) | Project SDK tooling | Product — stable surface |
|
||||
| [`acp/`](acp/README.md) | Automation-only Agent Client Protocol server | Product — stable surface |
|
||||
| [`ui/`](ui/README.md) | TUI and JSON-RPC integrations, approval/interaction seams, ask-user tool | Product — stable surface |
|
||||
| [`experimental/`](experimental/README.md) | Prototypes and internal plugins | Unreleased |
|
||||
| [`examples/`](examples/README.md) | Demo bundles (agent-spine + TUI/CLI/ACP/JSON-RPC bins) leaves load | Support — example infra |
|
||||
| [`support/`](support/README.md) | Support infrastructure (testkits, invariants, replay, Loader smokes) | Support — lower compatibility expectations |
|
||||
| [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (`Branded<B>`, Harness home/path helpers, timeout, retention) | Support — small, stable, harness-dep-free |
|
||||
|
||||
Groups distinguish product API from support infrastructure. New packages join an existing group; a new group updates its README and this table.
|
||||
New packages join existing groups; new groups update their README and this table.
|
||||
|
||||
## Dependencies
|
||||
|
||||
|
||||
@@ -44,11 +44,12 @@
|
||||
| [`sdk/`](sdk/README.md) | 项目 SDK 工具 | 产品：稳定表面 |
|
||||
| [`acp/`](acp/README.md) | 仅面向自动化的 Agent Client Protocol 服务器 | 产品：稳定表面 |
|
||||
| [`ui/`](ui/README.md) | TUI 与 JSON-RPC 集成、批准／交互 seam、用户问答工具 | 产品：稳定表面 |
|
||||
| [`experimental/`](experimental/README.md) | 原型和内部插件 | 未发布 |
|
||||
| [`examples/`](examples/README.md) | 演示组合包（agent-spine + TUI/CLI/ACP/JSON-RPC bin），由叶节点加载 | 支持：示例基础设施 |
|
||||
| [`support/`](support/README.md) | 支持基础设施（testkit、不变式、回放、Loader 冒烟测试） | 支持：兼容性预期较低 |
|
||||
| [`util/`](util/README.md) | 组间共享的低层零依赖工具（`Branded<B>`、Harness home／路径辅助函数、超时、保留策略） | 支持：小型、稳定、无 harness 依赖 |
|
||||
|
||||
组用于区分产品 API 与支持基础设施。新包加入现有组；新组则更新其 README 和此表。
|
||||
新包加入现有组；新组更新其 README 和此表。
|
||||
|
||||
## 依赖
|
||||
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
# AGENTS.md — Experimental and internal packages
|
||||
|
||||
These rules supplement the [package rules](../AGENTS.md). The [experimental and internal package group decision](../../.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.md) owns the rationale.
|
||||
|
||||
- All Cordis plugin packages whose whole public contract is experimental or internal-only belong here. An experimental option inside an otherwise stable package stays in that package's product-role group.
|
||||
- Use this directory to share engineering and product-manager prototypes across the team so others can discover, run, review, and extend them against the real plugin graph.
|
||||
- Official releases exclude this directory. A package enters a release only after moving to its product-role group; do not add packages here to release manifests or bundles.
|
||||
- Experimental packages carry no stability, compatibility, migration, or support promise. Internal-only packages may define narrower internal contracts but make no public release promise.
|
||||
- Experimental or internal-only status never relaxes repository engineering, security, documentation, lifecycle, testing, or snapshot requirements.
|
||||
- Release packages must not take runtime dependencies on packages here. Examples may; every other runtime dependent is also experimental or internal-only and belongs here. Tests may use them as development dependencies.
|
||||
- Promotion moves a package to its product-role group without renaming its `@deepseek-ai/dsh-*` package. Require explicit review of its public contract, limitations, test evidence, and a named owner accepting stable-package obligations.
|
||||
@@ -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 packages/experimental/README.md
|
||||
README.md: db39af8bb1b1bcfd257e16e4ad1dd112f604ffb1
|
||||
README.zh.md: df9b8cb2a91faab7af782e0f53685368e99583ff
|
||||
@@ -0,0 +1,7 @@
|
||||
# experimental/ — experimental and internal packages
|
||||
|
||||
English | [中文](README.zh.md)
|
||||
|
||||
This group hosts team-shared engineering and product-manager prototypes plus internal-only Cordis plugins. It is excluded from official releases; packages move to their product-role group before release.
|
||||
|
||||
No packages live here yet. The [subtree rules](AGENTS.md) define the no-warranty, dependency, and promotion boundaries.
|
||||
@@ -0,0 +1,7 @@
|
||||
# experimental/：实验性与内部专用包（package）
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
该分组容纳工程人员与产品经理在团队内共享的原型，以及内部专用 Cordis 插件。该分组不纳入官方发布版本；包在发布前移入对应的产品角色分组。
|
||||
|
||||
该分组尚未包含任何包。[子树规则](AGENTS.md)界定不作保证、依赖关系和提升机制的边界。
|
||||
Reference in New Issue
Block a user