diff --git a/cindy-protocol b/cindy-protocol index 56d9d9f54e1..dbbf1697037 160000 --- a/cindy-protocol +++ b/cindy-protocol @@ -1 +1 @@ -Subproject commit 56d9d9f54e1e29bce61eacc146d3a4e9f7cde5d8 +Subproject commit dbbf1697037c6025541ab4bae38f906982628423 diff --git a/docs/dev-rules/protocol-and-submodules.md b/docs/dev-rules/protocol-and-submodules.md index c75d3b926d1..f0a6d7b7850 100644 --- a/docs/dev-rules/protocol-and-submodules.md +++ b/docs/dev-rules/protocol-and-submodules.md @@ -5,9 +5,10 @@ > 协议／relay／隧道 payload／IPC allowlist，或任何改动客户端与服务端之间 wire protocol > 的地方之前 -`cindy-protocol` 是客户端与服务端共享的 wire protocol 权威来源。submodule 指针漂移或 -单端改协议会让两端不一致，且这类不一致在本仓的 typecheck／单测里发现不了，只有真实 -连接时才暴露。device-link 的运行时约束另见 +`cindy-protocol` 是客户端与服务端共享的存量 wire protocol 权威来源。协议仓的 package +集合已经封闭，只会维护或减少现有 package，不再接收新 package。submodule 指针可以因 +兼容的分阶段升级而不同；真正危险的是单端改变 wire 语义或在不兼容变更中缺少协同，这类 +问题在本仓的 typecheck／单测里发现不了，只有真实连接时才暴露。device-link 的运行时约束另见 [`remote-and-mobile-adaptation.md`](remote-and-mobile-adaptation.md)，submodule 初始化命令见 [`environment-setup.md`](environment-setup.md)。 @@ -18,22 +19,29 @@ | 内容 | 权威来源 | |---|---| | 协议权威源 | 根 submodule `cindy-protocol`（`github.com/makecindy/cindy-protocol`） | -| desktop 消费的协议包 | `@cindy/slack-hook-protocol` | +| hook 双工任务协议 | `@cindy/slack-hook-protocol`；desktop hook-control 与 slack／telegram／x hook server 共同消费 | | device-link relay 层定义 | `@cindy/device-link-protocol`；客户端重连、IPC allowlist、隧道 payload 在 `packages/device-link` | +| Plugin 交付与 manifest | `@cindy/plugin-protocol`；desktop、`packages/cindy-tools` 与 plugin-server 共同消费 | +| 模型目录 | `@cindy/model-access-protocol`；desktop／mobile 与 model-access-server 共同消费 | | 插件来源 | 客户端不预装插件；一律通过 SkillHub 或用户手动安装 `.cindy` 包 | ## 1. `cindy-protocol` 是协议权威源 -- 协议定义以 `cindy-protocol` submodule 为准；desktop 通过 `@cindy/slack-hook-protocol` - 消费，device-link 复用 `@cindy/device-link-protocol` 的 relay 层定义。客户端重连、IPC - allowlist 与隧道 payload 留在 `packages/device-link`，不在客户端另造一套协议。 +- 协议定义以 `cindy-protocol` submodule 为准；当前只保留 + `@cindy/slack-hook-protocol`、`@cindy/device-link-protocol`、 + `@cindy/plugin-protocol`、`@cindy/model-access-protocol` 四个有真实双端消费者的包。 + 客户端重连、IPC allowlist 与隧道 payload 留在 `packages/device-link`，不在客户端另造一套协议。 +- 协议仓是封闭、持续精简的存量仓库：不得新增 package、增加 package 数量，或把无关业务域 + 塞进现有 package 绕过限制。新业务域的契约在所属业务仓库处理，或另行做仓库外架构决策。 - `makecindy/cindy-protocol` 以新历史公开；父仓锁定的 submodule commit 必须始终 可从公开仓拉取——合入协议仓 `main`，或打 `client-baseline-` tag，不允许只 - 停在 feature 分支上（分支删除会让 gitlink 失效）。当前锁定的 `4468730` 已在协议 - 仓 `main` 上；历史 tag `client-baseline-436a45f` 仍可能被旧 checkout 依赖，不要 - 删除。 -- **升级 submodule 指针前必须确认服务端同步升级**，避免两端 wire protocol 漂移。协议是 - 跨仓契约，单端先行会让线上连接对不上。 + 停在 feature 分支上（分支删除会让 gitlink 失效）。历史 tag + `client-baseline-436a45f` 仍可能被旧 checkout 依赖，不要删除。 +- append-only、带旧端降级路径的兼容变更允许客户端和服务端独立 pin、分阶段升级；只有实际 + 使用新字段／消息／校验能力的消费仓需要 bump。删除未被任何消费方引用的 package 也不要求 + 两仓同步部署。 +- 不兼容 wire 变更、device-link 新增 relay kind 等必须在协议 PR 中声明升级窗口，并协调所有 + 相关消费方；不能把“允许指针不同”误读成允许单端改变既有字段语义。 ## 2. 插件来源 @@ -46,10 +54,11 @@ ## Review 清单 -1. 改动是否触及跨端 wire protocol？是否要同步 `cindy-protocol` 与服务端？ -2. 升级 submodule 指针时，是否确认了服务端同步、不会造成协议漂移？ -3. 客户端是否在 `packages/device-link` 之外另造了协议或绕过 relay 层定义？ -4. 插件能力是否通过 `.cindy` 包和 SkillHub／手动安装分发，而不是重新引入预装／播种 +1. 改动是否触及跨端 wire protocol？是兼容独立升级，还是需要协调窗口的不兼容变更？ +2. submodule 目标 commit 是否已合入公开协议仓，旧端降级行为是否明确？ +3. 是否新增了 protocol package、扩大了 package 数量，或把无关领域塞进存量 package？这些均不允许。 +4. 客户端是否在 `packages/device-link` 之外另造了协议或绕过 relay 层定义？ +5. 插件能力是否通过 `.cindy` 包和 SkillHub／手动安装分发，而不是重新引入预装／播种 机制、私有种子 submodule 或绕过插件权限边界？ 协议改动按 [`desktop-development.md`](desktop-development.md) 跑相关测试，并与服务端确认 diff --git a/docs/dev-rules/repo-map.md b/docs/dev-rules/repo-map.md index d9fa7f5e9f9..a2f8f396e65 100644 --- a/docs/dev-rules/repo-map.md +++ b/docs/dev-rules/repo-map.md @@ -13,7 +13,7 @@ |---|---| | `apps/` | 终端产品（desktop、mobile）与随包分发的二进制资产 | | `packages/` | 客户端共享能力包（与 render／main 解耦，详见下表） | -| `cindy-protocol/` | git submodule：客户端与服务端共享 wire protocol 的唯一权威源（`device-link-protocol` 中继层协议、`slack-hook-protocol` 任务协议）；升级规则见 [`protocol-and-submodules.md`](protocol-and-submodules.md) | +| `cindy-protocol/` | git submodule：客户端与服务端共享的存量 wire protocol 权威源；package 集合封闭且持续精简，当前保留 device-link、slack-hook、plugin、model-access 四包；升级规则见 [`protocol-and-submodules.md`](protocol-and-submodules.md) | | `config/` | 运行期端点清单（`endpoint.json` / `endpoint.dev.json` / `endpoint.global.json`：auth、device-link 等线上 base URL） | | `scripts/` | 仓库级工程脚本：dev 启动包装、agent 二进制拉取（`ensure-agent-binaries.mjs`）、i18n／endpoint／文档等校验 guard、worktree 管理 | | `tools/` | claude／codex／ripgrep／pi 四个 Desktop runtime 的版本 pin（`latest.json`）与更新器（`update.mjs`） | diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index a67e7d001be..94b5fbaf0ac 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -760,15 +760,6 @@ importers: specifier: ^3.2.4 version: 3.2.7(@types/debug@4.1.13)(@types/node@25.9.5)(jiti@2.7.0)(jsdom@29.1.1(@noble/hashes@1.8.0))(lightningcss@1.32.0)(terser@5.49.0)(tsx@4.23.1)(yaml@2.9.0) - cindy-protocol/packages/skill-protocol: - devDependencies: - typescript: - specifier: ^5.7.0 - version: 5.9.3 - vitest: - specifier: ^3.2.4 - version: 3.2.7(@types/debug@4.1.13)(@types/node@25.9.5)(jiti@2.7.0)(jsdom@29.1.1(@noble/hashes@1.8.0))(lightningcss@1.32.0)(terser@5.49.0)(tsx@4.23.1)(yaml@2.9.0) - cindy-protocol/packages/slack-hook-protocol: devDependencies: '@types/node': @@ -781,15 +772,6 @@ importers: specifier: ^3.2.4 version: 3.2.7(@types/debug@4.1.13)(@types/node@25.9.5)(jiti@2.7.0)(jsdom@29.1.1(@noble/hashes@1.8.0))(lightningcss@1.32.0)(terser@5.49.0)(tsx@4.23.1)(yaml@2.9.0) - cindy-protocol/packages/voice-protocol: - devDependencies: - typescript: - specifier: ^5.7.0 - version: 5.9.3 - vitest: - specifier: ^3.2.4 - version: 3.2.7(@types/debug@4.1.13)(@types/node@25.9.5)(jiti@2.7.0)(jsdom@29.1.1(@noble/hashes@1.8.0))(lightningcss@1.32.0)(terser@5.49.0)(tsx@4.23.1)(yaml@2.9.0) - packages/anthropic-compat-proxy: devDependencies: '@eslint/js': diff --git a/scripts/__tests__/check-submodule-forward.test.mjs b/scripts/__tests__/check-submodule-forward.test.mjs index 190d31984db..094984e7290 100644 --- a/scripts/__tests__/check-submodule-forward.test.mjs +++ b/scripts/__tests__/check-submodule-forward.test.mjs @@ -202,9 +202,16 @@ test('fetches a published head missing from the local protocol clone', () => { git(bare, 'init', '--bare'); git(publisher.repo, 'remote', 'add', 'origin', bare); git(publisher.repo, 'push', 'origin', 'main'); + git( + publisher.repo, + 'push', + 'origin', + `${publisher.one}:refs/heads/test-baseline`, + ); git(local, 'init', '-b', 'main'); git(local, 'remote', 'add', 'origin', bare); - git(local, 'fetch', 'origin', publisher.one); + git(local, 'fetch', 'origin', 'test-baseline'); + git(publisher.repo, 'push', 'origin', '--delete', 'test-baseline'); assert.throws(() => git(local, 'cat-file', '-e', `${publisher.two}^{commit}`), ); diff --git a/scripts/test-workspaces.config.mjs b/scripts/test-workspaces.config.mjs index 783604f2b1e..0266210face 100644 --- a/scripts/test-workspaces.config.mjs +++ b/scripts/test-workspaces.config.mjs @@ -252,8 +252,6 @@ export default { noCollectableWorkspace('@cindy/device-link-protocol', 'cindy-protocol/packages/device-link-protocol'), requiredUnitWorkspace('@cindy/model-access-protocol', 'cindy-protocol/packages/model-access-protocol'), requiredUnitWorkspace('@cindy/plugin-protocol', 'cindy-protocol/packages/plugin-protocol'), - requiredUnitWorkspace('@cindy/skill-protocol', 'cindy-protocol/packages/skill-protocol'), requiredUnitWorkspace('@cindy/slack-hook-protocol', 'cindy-protocol/packages/slack-hook-protocol'), - requiredUnitWorkspace('@cindy/voice-protocol', 'cindy-protocol/packages/voice-protocol'), ], };