[Proposal] 关于社区标准 v0.15/v0.16 演进与边界细节（Manifest、命令树、存储与事件信封）的探讨建议

[Yan-Zero]

类型

讨论

问题与证据

基于 oh-my-dsh/dsh-community-standard 最新提交 a5a2502（包括 RFC 0001、RFC 0005、RFC 0006 与各 spec/ 规范文件），在结合多端/远程场景及复杂插件落地的实际经验后，发现 4 个模块存在一些值得探讨的边界冲突与演进细节：

1. Manifest 与贡献点扩展（spec/manifest.md）

   • 现状：允许省略空容器极大简化了作者体验；但随着视图（RFC 0005）、设置与主题等贡献点增加，所有贡献字段都直接扩充进中央 dsh-plugin.schema.json。
   • 问题：中央 Schema 容易成为全生态发版瓶颈，与原则 ⑦（“元协议内核，契约独立版本化”）存在张力；同时部分 v0.16 目标字段提前进入了 v0.15 Schema。此外，Facet 缺少显式 activation driver 声明，Permission 仍为纯字符串。

2. Command 契约与子命令树（commands.dsh 与 RFC 0005 §5）

   • 现状：Registry 目前为扁平 { id, title } 动作叶子，RFC 0005 虽提出需要支持子命令，但缺少完整规范。
   • 问题：缺少结构化 arguments / options 校验、aliases 冲突仲裁、敏感输入脱敏标记以及多 Surface / Presentation 声明，导致 Remote 与多端补全无法对齐。

3. Storage 契约与遍历保护（storage.dsh 与 spec/facet-api.md）

   • 现状：Facet API 精准区分了 undefined（键不存在）与 null（存储值），语义严谨。
   • 问题：Storage Registry 明确声明“不提供 enumeration”，但 Facet API 却导出了无上限的同步 keys(): string[]，存在内部矛盾；且全量读取在大型命名空间/远程存储下存在阻塞和内存风险；底层缺乏结构化 request/response 通信与配额声明。

4. Messages / Events 契约与信封（spec/event-envelope.md）

   • 现状：信封元数据（correlationId、scope、redactions）非常丰富。
   • 问题：Manifest 订阅名（messages.observe）与信封标识（eventType: messages.dsh, eventVersion: v1alpha1）缺少 kind，与 apiVersion + kind 坐标体系分裂；测试 fixture 将 at-most-once 流中的序号空洞（sequence gap）判为非法；富媒体/大附件直接内联 Base64 在高频事件流中开销过大。

---

希望得到的结果

建议在保持当前 v0.15 稳定的前提下，在后续演进（如 RFC 0005/0006 定稿或 v1alpha2 契约）中吸收以下设计：

1. Manifest 扩展解耦：

   • 保持顶层 contributes.views 等作者友好语法糖，但在底层由各领域契约的 Definition 自包含校验其贡献结构，避免频繁修改中央 Manifest Schema；
   • 规范 Facet 的 activation driver 契约，并将 Permission 规范为结构化对象。

2. 完整命令树规范：

   • 保留扁平 { id, title } 作为零成本根节点；
   • 规范化递归子节点、参数/选项校验、敏感标记与 Presentation capability 契约，彻底统一多端与 Remote 命令解析。

3. 存储空值与遍历保护：

   • 采纳 absence / null 区分语义（推荐 { found: false } | { found: true, value: JsonValue }）；
   • 保持底层通信基于结构化 request/response 与明确错误码；
   • 修正内部矛盾，将 keys() 调整为可选的游标分页接口（如 list({ cursor, limit, prefix })）。

4. 事件信封坐标统一与大对象引用：

   • 信封顶层统一携带完整的 apiVersion + kind 契约坐标；
   • 明确允许 at-most-once 事件流中的 sequence gap；
   • 对图片和富媒体引入“内容引用（ContentReference）”机制解耦传输。

---

涉及资产与授权

无（涉及社区开放 RFC 与规范文档演进）。

受影响群体及安全、权利、速度风险

• 受影响群体：插件开发者、宿主（Web / TUI / Remote）维护者与工具链作者。
• 风险与收益：提升标准在复杂插件与多端环境下的长期稳定性和扩展性，避免未来因中央 Schema 膨胀或命令/存储边界缺失而发生 breaking change。

替代方案、可逆性与回滚

• 替代方案：继续在中央 Schema 中堆叠新贡献点，命令树与存储遍历各宿主自行私有扩展（会重回宿主私有探测老路）。
• 可逆性：建议均属于增量演进或下一版本契约（v0.16 / v1alpha2），对现有 v0.15 基础无破坏。

利益冲突

无。

建议负责人和复审日

建议由社区标准 Maintainer 共同评审；建议复审日：RFC 0005 / 0006 评审期内。

公开记录

• 我理解相关控制者确认前它可能始终只是提案。