diff --git a/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.md b/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.md deleted file mode 100644 index 1ebae5dbb1..0000000000 --- a/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.md +++ /dev/null @@ -1,33 +0,0 @@ -# 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//` the required home for Cordis plugin packages whose whole public contract is experimental or internal-only. Package names remain `@deepseek-ai/dsh-`. - -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; when such tooling is added, the directory is its required exclusion boundary. diff --git a/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.zh.md b/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.zh.md deleted file mode 100644 index 2d09451c50..0000000000 --- a/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.zh.md +++ /dev/null @@ -1,33 +0,0 @@ -# Agent Note: 实验性与内部专用包分组 - -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//`。包名仍为 `@deepseek-ai/dsh-`。 - -该分组供团队在仓库内共享工程人员和产品经理制作的原型：成员可以基于真实插件图发现、运行、评审并扩展彼此的原型，但这不代表产品会提供支持。 - -官方发布版本不包含此目录。包只有移入对应的产品角色分组后才会纳入发布版本；发布包不得在运行时依赖此处的包。示例可以使用这些包；其他任何运行时依赖方也必须位于此处。测试可以将它们用作开发依赖。 - -实验性包不提供稳定性、兼容性、迁移或支持保证：其 API、配置或数据可以变更，包也可以移除，均不提供弃用期或迁移路径。内部专用包可以定义范围更窄的内部约定，但不作公开发布承诺。无论哪种状态，都不降低仓库对工程、安全、文档、生命周期、测试或快照的要求。 - -尚待完成的 `@deepseek-ai/dsh-tui-session-changes` `/diff` 查看器和 `/btw` 插件都受这项规则约束。将包提升为稳定包并纳入官方发布版本，需要明确评审其公开约定、限制和测试证据，并指定一名愿意承担稳定包义务的负责人。 - -## 考虑过的替代方案 - -**将实验性和内部专用包留在产品角色分组中，并用 README 标注。** 标注容易被忽略，也无法强制执行依赖边界。 - -**首个带标签的版本发布前，将所有包都视为实验性。** 这无法提供持久的孵化边界。 - -**在其他位置开发原型和内部专用包。** 这会失去评估它们所需的真实插件图、示例、快照和生命周期检查。 - -## 后果 - -该路径明确标示不纳入发布版本的包及其依赖影响范围，同时保留供团队共享成果的真实插件图。代价是这些包无法与同产品角色的包共置，提升并纳入发布版本时还会产生路径变动，但 npm 包名保持稳定。子树规则、仓库已有的[「必须有当前负责人和实际需求」规则](../../../../packages/AGENTS.md)以及保持不变的工程门禁，可限制该分组无序膨胀。由于官方发布工具尚不存在，目前由贡献者政策执行这项排除规则；添加发布工具后，必须以该目录为排除边界。 diff --git a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml index c50bf478ad..f5c1e4cad3 100644 --- a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.i18n.yaml @@ -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-07-29-package-regrouping.md -2026-07-29-package-regrouping.md: 3c37bce05bacd6af800a76ac93fb691b896a6772 -2026-07-29-package-regrouping.zh.md: 68903ff1fad6a975c4445fe8971c8fe0dd40117f +2026-07-29-package-regrouping.md: 30fc45a122263350b4a2ad1998850f631c20f9b8 +2026-07-29-package-regrouping.zh.md: a3a9a11ec71b7f894dcea7c733eb39a80b71ac50 diff --git a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md index 3c37bce05b..30fc45a122 100644 --- a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md +++ b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.md @@ -58,7 +58,7 @@ The moves landed as pure `git mv` moves, so rename detection carries the history A group move did not touch: npm names, imports, `cordis.yml` configs, snapshot fixtures, the `pnpm-workspace.yaml`/`tsdown` globs (both `packages/*/*`), or the Python runtime manifest — all reference packages by npm name. -`client/` and `host/` were out of scope and are unchanged. The `experimental/` group proposal (PR #844) is orthogonal — a release-boundary container, not a clustering decision. +`client/` and `host/` were out of scope and are unchanged. ## Alternatives considered diff --git a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md index 68903ff1fa..a3a9a11ec7 100644 --- a/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-29-package-regrouping.zh.md @@ -58,7 +58,7 @@ Status: implemented 组移动未触及：npm 包名、import、`cordis.yml` 配置、快照 fixture（测试前置数据）、`pnpm-workspace.yaml` 与 `tsdown` 的 glob（都是 `packages/*/*`），以及 Python 运行时 manifest（元数据清单）——它们全部按 npm 包名引用包。 -`client/` 与 `host/` 不在本次范围内，保持不变。`experimental/` 组提案（PR #844）与本案正交：它是发布边界容器，不是聚类决策。 +`client/` 与 `host/` 不在本次范围内，保持不变。 ## Alternatives considered diff --git a/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-11-remove-empty-experimental-package-group.i18n.yaml similarity index 52% rename from .agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.i18n.yaml rename to .agents/notes/implemented/simplification/2026-08-11-remove-empty-experimental-package-group.i18n.yaml index 43e4b3d605..945a68054c 100644 --- a/.agents/notes/implemented/architecture/2026-07-28-experimental-plugin-package-group.i18n.yaml +++ b/.agents/notes/implemented/simplification/2026-08-11-remove-empty-experimental-package-group.i18n.yaml @@ -1,6 +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: 1ebae5dbb16d4c966f94ffde69fb0cb9bc163d80 -2026-07-28-experimental-plugin-package-group.zh.md: 2d09451c5069a775906e5bc8748c334c29008164 +# pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-11-remove-empty-experimental-package-group.md +2026-08-11-remove-empty-experimental-package-group.md: e5e81e3e3763f216921b3f3b74709b64be3dee37 +2026-08-11-remove-empty-experimental-package-group.zh.md: d44d0daaf346a5fea317f8c8c6a23f26eaa3cec0 diff --git a/.agents/notes/implemented/simplification/2026-08-11-remove-empty-experimental-package-group.md b/.agents/notes/implemented/simplification/2026-08-11-remove-empty-experimental-package-group.md new file mode 100644 index 0000000000..e5e81e3e37 --- /dev/null +++ b/.agents/notes/implemented/simplification/2026-08-11-remove-empty-experimental-package-group.md @@ -0,0 +1,37 @@ +# Agent Note: Remove the empty experimental package group + +Status: implemented + +English | [中文](2026-08-11-remove-empty-experimental-package-group.zh.md) + +## Problem + +The package hierarchy reserves `packages/experimental/` for prototypes and internal-only plugins, but no package has used the group. The empty group adds placement, dependency, promotion, and release rules without a current package or release mechanism that needs them. + +The original group aimed to let the team share prototypes against the real plugin graph without implying product support. That need remains possible, but it does not justify a permanent repository category before a concrete package exists. + +## Decision + +The package hierarchy has no reserved experimental or internal-only group. Packages continue to live in groups selected for their current product role. + +A concrete package that needs different release, stability, or dependency treatment requires a decision based on its actual consumers and release mechanism. That decision may reintroduce a dedicated group when it can also define and enforce the exclusion rules. + +This note consolidates and supersedes the experimental-package-group decision, whose active triplet is removed with the empty directory. + +## Alternatives considered + +**Keep the empty group.** It provides an obvious future incubation location, but it also keeps repository rules with no current owner, package, or enforcement mechanism. + +**Move the experimental rules into the general package instructions.** This preserves the policy without an empty directory, but makes every package change carry rules for a hypothetical package class. + +**Put concrete experimental packages in product-role groups with README labels.** This preserves product-role colocation, but labels alone cannot enforce release and runtime-dependency rules. A future package can evaluate this option against its actual release mechanism. + +**Treat every package as experimental until the first tagged release.** This applies a broad temporary status without providing durable treatment for packages that remain experimental after releases begin. + +**Require prototypes to stay outside the repository.** This would lose access to the real plugin graph, examples, snapshots, and lifecycle checks. Removing the reserved group does not impose that restriction; a concrete prototype can establish the placement it needs. + +## Consequences + +The hierarchy loses an unused group and its special release and dependency policy. It also gives up a predeclared location for team discovery and a ready-made promotion path. + +The first package that needs experimental or internal-only treatment must define where it lives, how releases exclude it, which runtime dependencies are allowed, and what condition promotes or removes it. A dedicated group can return when those rules have a current consumer and enforceable mechanism. diff --git a/.agents/notes/implemented/simplification/2026-08-11-remove-empty-experimental-package-group.zh.md b/.agents/notes/implemented/simplification/2026-08-11-remove-empty-experimental-package-group.zh.md new file mode 100644 index 0000000000..d44d0daaf3 --- /dev/null +++ b/.agents/notes/implemented/simplification/2026-08-11-remove-empty-experimental-package-group.zh.md @@ -0,0 +1,37 @@ +# Agent Note: 移除空的实验性包分组 + +Status: implemented + +[English](2026-08-11-remove-empty-experimental-package-group.md) | 中文 + +## 问题 + +包层级结构预留 `packages/experimental/` 用于原型和内部专用插件，但从未有包使用该分组。这个空分组添加了放置、依赖、提升和发布规则，却没有需要这些规则的现有包或发布机制。 + +原分组旨在让团队基于真实插件图共享原型，同时不暗示产品会提供支持。这项需求将来可能出现，但在具体包出现前，不足以支持一个永久的仓库类别。 + +## 决策 + +包层级结构不再预留实验性或内部专用分组。包继续按照当前产品职责放入对应分组。 + +如果具体包需要不同的发布、稳定性或依赖处理，必须根据其实际消费方和发布机制做出决策。只要该决策同时定义并强制执行排除规则，就可以重新引入专用分组。 + +本 Agent Note 整合并取代实验性包分组决策；该旧决策的活跃三文件组随空目录一并移除。 + +## 考虑过的替代方案 + +**保留空分组。** 它为未来孵化工作提供明确位置，但也会保留没有当前负责人、包或强制执行机制的仓库规则。 + +**将实验性规则移入通用包指令。** 这可以在不保留空目录的情况下延续政策，但会让每次包变更都携带针对假设包类别的规则。 + +**将具体实验性包放入产品职责分组，并用 README 标注。** 这会保持产品职责共置，但仅靠标注无法强制执行发布和运行时依赖规则。未来的包可以根据实际发布机制评估此选项。 + +**在首个带标签的版本发布前，将每个包都视为实验性。** 这会施加宽泛的临时状态，却无法为发布开始后仍处于实验状态的包提供持久处理方式。 + +**要求原型留在仓库外。** 这会失去真实插件图、示例、快照和生命周期检查。移除预留分组并不施加这项限制；具体原型可以建立自身所需的放置规则。 + +## 后果 + +包层级结构移除了未使用的分组及其特殊发布和依赖政策，同时也放弃了预先声明的团队发现位置和现成的提升路径。 + +第一个需要实验性或内部专用处理的包必须定义其存放位置、发布版本如何排除它、允许哪些运行时依赖，以及包在何种条件下获得提升或被移除。当这些规则具有当前消费方和可强制执行的机制时，可以恢复专用分组。 diff --git a/packages/README.i18n.yaml b/packages/README.i18n.yaml index b4c191a1d0..5f2d8b0585 100644 --- a/packages/README.i18n.yaml +++ b/packages/README.i18n.yaml @@ -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: 19d6e5ba7b554f59bd66e213f8a53389761fc735 -README.zh.md: 17f58a2922e9019af054b0dccb6c4d9199fd1a9d +README.md: eb7df95bde10dafd7afcb168d30c9dda90296687 +README.zh.md: 03cd02510267d3abdd414bed6ec1f42773d0811a diff --git a/packages/README.md b/packages/README.md index 19d6e5ba7b..eb7df95bde 100644 --- a/packages/README.md +++ b/packages/README.md @@ -52,7 +52,6 @@ Groups hold `packages///`; names stay `@deepseek-ai/dsh-`. **Gr | [`boot/`](boot/README.md) | Shared app-bin boot glue | Product — stable surface | | [`host/`](host/README.md) | Web-GUI host half: API gateway + HTTP route server | Product — stable surface | | [`client/`](client/README.md) | Web-GUI browser half: shell, wire, object services, slots, `ui-*` plugins | Product — stable surface | -| [`experimental/`](experimental/README.md) | Prototypes and internal plugins | Unreleased | | [`examples/`](examples/README.md) | Demo bundles (agent-spine + 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`, Harness home/path helpers, timeout, retention) | Support — small, stable, harness-dep-free | diff --git a/packages/README.zh.md b/packages/README.zh.md index 17f58a2922..03cd025102 100644 --- a/packages/README.zh.md +++ b/packages/README.zh.md @@ -52,7 +52,6 @@ npm scope 为 `@deepseek-ai/dsh-*`；Cordis `Service` 子类和函数插件通 | [`boot/`](boot/README.md) | 共享的 app bin 启动粘合层 | 产品：稳定接口 | | [`host/`](host/README.md) | web GUI 宿主半侧：API 网关 + HTTP 路由服务器 | 产品：稳定接口 | | [`client/`](client/README.md) | web GUI 浏览器半侧：shell、协议层、对象服务、slot、`ui-*` 插件 | 产品：稳定接口 | -| [`experimental/`](experimental/README.md) | 原型和内部插件 | 未发布 | | [`examples/`](examples/README.md) | 演示组合包（agent-spine + CLI/ACP/JSON-RPC bin），由叶节点加载 | 支持：示例基础设施 | | [`support/`](support/README.md) | 支持基础设施（testkit、不变式、回放、Loader 冒烟测试） | 支持：兼容性预期较低 | | [`util/`](util/README.md) | 组间共享的低层零依赖工具（`Branded`、Harness home／路径辅助函数、超时、保留策略） | 支持：小型、稳定、无 harness 依赖 | diff --git a/packages/experimental/AGENTS.md b/packages/experimental/AGENTS.md deleted file mode 100644 index ee6bf61598..0000000000 --- a/packages/experimental/AGENTS.md +++ /dev/null @@ -1,11 +0,0 @@ -# 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 full 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 contracts for a limited set of internal callers and callees 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. diff --git a/packages/experimental/README.i18n.yaml b/packages/experimental/README.i18n.yaml deleted file mode 100644 index 48cfed37ee..0000000000 --- a/packages/experimental/README.i18n.yaml +++ /dev/null @@ -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 packages/experimental/README.md -README.md: db39af8bb1b1bcfd257e16e4ad1dd112f604ffb1 -README.zh.md: fc5942190a354668164b41b99e83b52b14d88f18 diff --git a/packages/experimental/README.md b/packages/experimental/README.md deleted file mode 100644 index db39af8bb1..0000000000 --- a/packages/experimental/README.md +++ /dev/null @@ -1,7 +0,0 @@ -# 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. diff --git a/packages/experimental/README.zh.md b/packages/experimental/README.zh.md deleted file mode 100644 index fc5942190a..0000000000 --- a/packages/experimental/README.zh.md +++ /dev/null @@ -1,7 +0,0 @@ -# experimental/：实验性与内部专用包 - -[English](README.md) | 中文 - -该分组容纳工程人员与产品经理在团队内共享的原型，以及内部专用 Cordis 插件。该分组不纳入官方发布版本；包在发布前移入对应的产品角色分组。 - -该分组尚未包含任何包。[子树规则](AGENTS.md)界定不作保证、依赖关系和提升机制的边界。