feat(plugin): 增加可选 installCount 协议契约

[nanaco666]

背景

服务端 PR-2C（xindong/cindy-server#369）已经能够把公共插件的 installCount 投影到列表/详情根对象，但当前 cindy-protocol 的 canonical parseListPluginsResponse / parseGetPluginResponse 会重建对象并丢弃未知字段。本 PR 是独立、最小的共享协议前置 PR-2P：先在协议仓声明、校验并保留该字段；服务端和客户端业务适配不在本 PR 内。

安装量口径

installCount 表示平台累计的成功安装次数，不是下载量、下载尝试、当前存量安装数、去重用户数或设备数。一次事件只有在客户端完成下载、校验、解包、落盘并确认安装成功后才成立；打开详情、申请下载 URL、失败的下载/校验/解包/落盘和插件升级均不计入。重装按既定口径视为新的成功安装事件，重复回执由后续服务端幂等链路处理。

字段契约

• VisiblePluginSummary 和 VisiblePluginDetail 根对象新增可选 installCount?: number | string。
• 只允许 scope: "public" 的 Plugin 携带；非 public 携带时按坏帧拒绝。
• number 必须是 JavaScript 安全非负整数，包含 0；负数、小数、NaN、无穷和超出安全整数范围的 JSON number 均拒绝。
• string 必须是非空、只含 ASCII 十进制数字的字符串，允许前导零和任意长度；"0"、"42"、"00042" 与超长数字串均原样保留，不经过 number 转换，因此大数不丢精度。
• 字段缺失时解析后仍保持缺失，不生成 installCount: undefined。
• null、空串、空白、正负号、小数、指数、全角数字和其他非法值均抛出带字段路径的 PluginProtocolError。
• 数值或字符串形式的零都是合法 wire 值；客户端展示层再隐藏，本协议 parser 不删除。

变更内容

• 在 packages/plugin-protocol/src/delivery.ts 增加公开 PluginInstallCount 类型、summary/detail 可选字段及严格运行时 parser。
• 更新 canonical list/detail parser，对合法字段显式保留，对旧 payload 保持原对象形状。
• 覆盖 public、字段缺失、number 0、安全整数、字符串 0/普通数字/前导零/10,000 位数字、非法值、非 public 拒收和列表/详情对称路径。
• 更新 docs/plugin-protocol.md，记录累计成功安装口径、任意长度字符串表示、兼容行为和 schema 版本纪律。

兼容性与合并顺序

这是 v2 的 additive optional field，不提升 PLUGIN_API_SCHEMA_VERSION。旧服务端不下发时，新客户端继续解析并隐藏安装量；新服务端下发时，旧客户端按既有规则忽略未知字段。

推荐顺序：

1. 评审并合并本 PR-2P（makecindy/cindy-protocol）。
2. 协议合并后，服务端 PR-2A xindong/cindy-server#364 和 PR-2C xindong/cindy-server#369 才可 bump submodule 到协议仓已合并 commit，并完成各自业务链路。
3. 客户端 PR-2B makecindy/cindy#2337 与本地调用统计 PR-1 makecindy/cindy#2310 按各自依赖推进；后续组装/UI PR 再消费安装量字段。

本 PR 不声称 #364、#369、#2337 或 #2310 已完成，也不声称 P2C 已就绪。

范围 / 不范围

包含：共享类型、canonical list/detail parser、运行时错误路径、兼容与坏帧测试、协议文档。

不包含：服务端存储或成功安装回执、P2A/P2B/P2C 业务代码、P1 本地调用计数、客户端 IPC/UI、排序筛选、下载量定义、设备身份、遥测、历史回填，以及父仓 D:\cindy-server-p2 的 submodule 指针变更。

验证

已通过：

pnpm.cmd install --frozen-lockfile
pnpm.cmd --filter @cindy/plugin-protocol build
pnpm.cmd --filter @cindy/plugin-protocol test
pnpm.cmd lint
pnpm.cmd format:check
pnpm.cmd typecheck
pnpm.cmd test
git diff --check

结果：lint、format、全 workspace typecheck/build 全部通过；全 workspace 测试通过（model-access 32、plugin-protocol 67、slack-hook 149，共 248 tests）。独立 diff 审查未发现 P0/P1。提交为单一 Signed-off-by commit。

GitHub Actions 对 fork PR 的 workflow 需要上游管理员批准运行；当前账号没有批准权限。该权限门不会被描述为代码测试通过，也不会绕过维护者的 hosted CI 要求。

风险与回滚

• 任意长度数字字符串会被线性校验并原样保留，这是保真大数契约的有意选择；调用方不得先转为 number。
• 消费方未 bump 时只是不识别安装量，不影响原列表、详情、安装或运行主流程。
• 服务端统计读取失败时省略字段，客户端隐藏指标。
• 回滚方式是消费方不 bump/回退 submodule，或回退本协议 commit；不会修改数据库、安装记录、插件包格式或父仓指针。

本 PR 保持 Draft，等待维护者评审和 hosted CI。关联：xindong/cindy-server#364、xindong/cindy-server#369、makecindy/cindy#2337、makecindy/cindy#2310。

[greptile-apps]

Greptile Summary

本 PR 为 public Plugin 的列表摘要和详情增加可选 installCount 协议契约，并在 canonical parser 中严格验证和保留该字段。

• 安全非负整数使用 number，超过 JavaScript 安全整数范围的十进制值使用 string
• 非 public scope、null、非整数及错误字符串表示会被拒绝
• 旧响应保持字段缺失，兼容既有 v2 envelope
• 测试覆盖列表、详情、边界值、非法值及 scope 限制，并同步更新协议文档

Confidence Score: 5/5

本 PR 看起来可以安全合并，新增字段的类型、运行时验证、兼容行为、测试和文档保持一致。

合法的 public installCount 会在列表和详情中被保留，缺失字段不会改变旧 payload 的规范化形状，非法数值及非 public 携带场景均会按声明契约拒绝，且公开导出链路完整。

Important Files Changed

Filename	Overview
packages/plugin-protocol/src/delivery.ts	新增公开计数类型、严格解析逻辑，并对列表及详情路径对称地保留合法可选字段；未发现可触达的契约或兼容性缺陷。
packages/plugin-protocol/src/tests/delivery.test.ts	覆盖缺失、零值、安全整数、超安全整数字符串、非法表示、非 public scope 和详情路径。
docs/plugin-protocol.md	清晰记录安装次数口径、wire 表示、展示语义、兼容行为和 schema 版本纪律。

_{Reviews (1): Last reviewed commit: "feat(plugin): add optional install count..." | Re-trigger Greptile}