Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion cindy-protocol
Submodule cindy-protocol updated 38 files
+2 −2 .github/ISSUE_TEMPLATE/bug_report.md
+2 −1 .github/ISSUE_TEMPLATE/protocol_proposal.md
+1 −0 .github/PULL_REQUEST_TEMPLATE.md
+31 −20 CONTRIBUTING.en.md
+18 −9 CONTRIBUTING.md
+27 −17 README.en.md
+19 −13 README.md
+2 −2 docs/commit-convention.md
+2 −2 docs/model-access-protocol.md
+201 −13 docs/plugin-protocol.md
+0 −122 docs/skill-protocol.md
+0 −89 docs/voice-protocol.md
+2 −1 packages/plugin-protocol/package.json
+49 −2 packages/plugin-protocol/src/__tests__/delivery.test.ts
+268 −0 packages/plugin-protocol/src/__tests__/manifest.test.ts
+233 −0 packages/plugin-protocol/src/__tests__/memberUpload.test.ts
+17 −0 packages/plugin-protocol/src/__tests__/memberUploadExports.test.ts
+20 −80 packages/plugin-protocol/src/delivery.ts
+1 −0 packages/plugin-protocol/src/index.ts
+67 −0 packages/plugin-protocol/src/internal/parse.ts
+4 −0 packages/plugin-protocol/src/internal/pluginResourceId.ts
+162 −20 packages/plugin-protocol/src/manifest.ts
+316 −0 packages/plugin-protocol/src/memberUpload.ts
+0 −23 packages/skill-protocol/package.json
+0 −183 packages/skill-protocol/src/__tests__/delivery.test.ts
+0 −118 packages/skill-protocol/src/__tests__/manifest.test.ts
+0 −294 packages/skill-protocol/src/delivery.ts
+0 −2 packages/skill-protocol/src/index.ts
+0 −176 packages/skill-protocol/src/manifest.ts
+0 −11 packages/skill-protocol/tsconfig.json
+0 −22 packages/voice-protocol/package.json
+0 −486 packages/voice-protocol/src/__tests__/protocol.test.ts
+0 −21 packages/voice-protocol/src/index.ts
+0 −545 packages/voice-protocol/src/parse.ts
+0 −6 packages/voice-protocol/src/routes.ts
+0 −222 packages/voice-protocol/src/types.ts
+0 −16 packages/voice-protocol/tsconfig.json
+0 −18 pnpm-lock.yaml
41 changes: 25 additions & 16 deletions docs/dev-rules/protocol-and-submodules.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)。

Expand All @@ -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-<sha>` 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. 插件来源

Expand All @@ -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) 跑相关测试,并与服务端确认
Expand Down
2 changes: 1 addition & 1 deletion docs/dev-rules/repo-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-linkslack-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`) |
Expand Down
18 changes: 0 additions & 18 deletions pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

9 changes: 8 additions & 1 deletion scripts/__tests__/check-submodule-forward.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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}`),
);
Expand Down
2 changes: 0 additions & 2 deletions scripts/test-workspaces.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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'),
],
};