chore: treeland-protocol-templated wayland protocol authoring skill

[wineee]

Log: Add skill to help review

[Copilot]

Pull request overview

Adds a new “treeland-wayland-protocol” agent skill to standardize how Treeland Wayland protocol XML files are authored and reviewed in this repository.

Changes:

• Added a repository-specific Wayland protocol rules reference (naming/versioning, ordering, since, lifecycle/error guidance).
• Added a protocol XML starter template aligned with existing xml/ conventions (SPDX header, interface layout).
• Added SKILL.md describing when/how to use the skill and the expected workflow.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
.agents/skills/treeland-wayland-protocol/references/treeland-wayland-protocol-rules.md	Documents Treeland + Wayland protocol authoring/review rules (naming, versioning, XML structure, lifecycle).
.agents/skills/treeland-wayland-protocol/assets/treeland-protocol-template.xml	Provides a starting XML template consistent with repo protocol conventions and structure.
.agents/skills/treeland-wayland-protocol/SKILL.md	Defines the skill’s scope/workflow and Treeland-specific protocol authoring constraints.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[zzxyb]

建议对skill追加一点小要求（对interface request和events）：
1，interface可以简易描述这个这个接口的大体作用是什么，可以的话简单描述下工作流
2，request如果存在特定场景一定要调用这个请求，可以加点描述
3，events需要描述这个事件的意义是什么。还有很重要的，合成器在什么时候会触发这个事件。

[deepin-ci-robot]

deepin pr auto review

这份代码审查主要针对新增的 Treeland Wayland 协议规范技能文件（SKILL.md）、模板文件（template.xml）以及参考规则（rules.md）。整体来看，这是一套非常完善、规范且指导性强的文档，旨在统一 Treeland Wayland 协议的编写风格和生命周期管理。

以下是针对语法逻辑、代码质量、代码性能和代码安全的详细审查意见及改进建议：

1. 语法逻辑

审查意见：

• XML 模板结构 (treeland-protocol-template.xml)：模板遵循了标准的 Wayland 协议 XML 结构（protocol -> interface -> request/event），逻辑清晰。特别是将 destroy 请求放在首位并标记为 type="destructor"，符合生命周期管理的最佳实践。
• 命名约定 (SKILL.md, rules.md)：关于文件名（treeland-foo-unstable-v1.xml）与接口名（treeland_foo_bar_v1）的区分说明得很清楚，避免了命名冲突和混淆。
• 版本控制逻辑 (rules.md 第 2 节)：明确区分了向后兼容扩展（增加 since）和不兼容变更（创建新文件、重置版本），这是协议演进的正确逻辑。

改进建议：

• 关于 summary 属性的强制性：在 rules.md 第 7 节提到"Add summary for args when it materially improves readability"，而在 SKILL.md 的 Authoring guidance 中提到"Prefer precise summary text..."。建议统一标准，明确规定所有 arg 标签都必须包含 summary 属性。即使看起来显而易见（如 id），统一的强制性有助于自动化工具处理和文档生成的一致性。
• 版权年份：模板文件中写死了 2026 年。建议在 SKILL.md 或 rules.md 中增加一条提示，提醒开发者在使用模板时更新版权年份为当前年份，或者使用年份范围（如 2023-2024），以符合 rules.md 第 10 节提到的"Match the year range used by neighboring files"。

2. 代码质量

审查意见：

• 文档完整性：SKILL.md 和 rules.md 提供了详尽的编写指南，包括命名、结构、描述质量、对象模型等，极大提升了协议定义的质量和可读性。
• 模板实用性：treeland-protocol-template.xml 提供了一个包含错误枚举、管理器对象、普通对象及其交互的完整示例，降低了新协议的编写门槛。
• 描述规范：强调在 <description> 中编写具体的、规范性的文本，而非在 XML 注释中，这有助于生成高质量的 API 文档。

改进建议：

• 枚举值的默认值：在模板的 enum name="mode" 中，default 值为 0。建议在 rules.md 中明确说明枚举值（尤其是作为 flags 或状态机时）的起始值和递增规则。例如，建议明确 0 通常保留为 default 或 none，或者明确是否必须从 0 开始。
• RFC 2119 的引用位置：SKILL.md 和 rules.md 都提到了 RFC 2119 关键词的使用。建议在 rules.md 中提供一个标准的 RFC 2119 解释段落的 XML 片段，让开发者可以直接复制到协议描述中，确保措辞完全一致，避免变体。

3. 代码性能

审查意见：

• 协议设计影响性能：文档中提到的"Keep each protocol narrow in scope"（保持协议范围窄）和"Prefer clear object lifetimes"（偏好清晰的对象生命周期）有助于减少客户端和合成器端的复杂度，间接提升性能。
• 事件与请求的分离：明确区分请求和事件，有助于优化事件循环的处理逻辑。

改进建议：

• 批量操作与高频事件：虽然文档侧重于规范，但可以在 rules.md 的 "Object model heuristics" 或 "Description quality" 部分补充一点关于性能的考量。例如：如果某个请求或事件预期会被高频调用（如每帧调用），应在描述中注明，以便开发者考虑是否需要批量操作接口或优化数据传输结构。

4. 代码安全

审查意见：

• 错误处理：文档强调使用具体的错误枚举而非通用的 failed，这有助于调试和防止协议滥用。
• 空值检查：明确要求使用 allow-null="true" 来标记可空参数，这能有效防止空指针解引用类的逻辑错误。
• 生命周期安全：强调 destroy 请求的顺序和 type="destructor" 的使用，有助于防止悬空指针和资源泄漏。

改进建议：

• 权限与敏感信息：目前的规则主要集中在协议结构和生命周期上。建议在 rules.md 中增加关于权限或隐私的考量。例如，如果协议涉及屏幕捕获、输入监听等敏感操作，应在接口描述中明确指出客户端需要具备的权限或安全上下文。
• 输入验证：在 "Requests, events, and errors" 部分，除了提到"providing out-of-range values"，建议补充关于类型验证的说明。例如，对于字符串参数，建议说明是否允许空字符串、是否有长度限制或格式要求（如特定的文件路径格式），以防止注入攻击或缓冲区溢出风险（尽管 Wayland 协议本身有类型系统，但语义上的验证仍需文档明确）。

总结

这套新增的文件质量非常高，逻辑严密，对 Treeland Wayland 协议的开发和维护具有极大的指导意义。主要的改进方向在于统一细节标准（如强制 summary、版权年份）、补充性能考量提示以及增强安全相关的语义描述（如权限和输入验证）。这些微调将使这套规范更加健壮和实用。

[deepin-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: wineee, zccrs

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• debian/deepin/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment