velt-comments-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Velt Comments Best Practices

Velt Comments 最佳实践

Comprehensive implementation guide for Velt's collaborative comments feature in React and Next.js applications. Contains 36 rules across 9 categories, prioritized by impact to guide automated code generation and integration patterns.

本文是针对React和Next.js应用中Velt协作评论功能的全面实现指南。包含9个类别共36条规则，按影响优先级排序，可指导自动化代码生成与集成模式。

When to Apply

适用场景

Reference these guidelines when:

Adding collaborative commenting to a React/Next.js application
Implementing any Velt comment mode (Freestyle, Popover, Stream, Text, Page, Inline)
Integrating comments with rich text editors (TipTap, SlateJS, Lexical)
Adding comments to media players (Video, Lottie animations)
Adding comments to charts (Highcharts, ChartJS, Nivo)
Building custom comment interfaces with standalone components

在以下场景中可参考这些指南：

为React/Next.js应用添加协作评论功能
实现任意Velt评论模式（自由样式、弹出框、信息流、文本、页面、内联）
集成富文本编辑器评论（TipTap、SlateJS、Lexical）
为媒体播放器添加评论（视频、Lottie动画）
为图表添加评论（Highcharts、ChartJS、Nivo）
使用独立组件构建自定义评论界面

Rule Categories by Priority

按优先级划分的规则类别


core-
mode-
standalone-
surface-
ui-
data-
debug-
permissions-
attach-

Priority	Category	Impact	Prefix
1	Core Setup	CRITICAL	`core-`
2	Comment Modes	HIGH	`mode-`
3	Standalone Components	MEDIUM-HIGH	`standalone-`
4	Comment Surfaces	MEDIUM-HIGH	`surface-`
5	UI Customization	MEDIUM	`ui-`
6	Data Model	MEDIUM	`data-`
7	Debugging & Testing	LOW-MEDIUM	`debug-`
8	Moderation & Permissions	LOW	`permissions-`
9	Attachments & Reactions	MEDIUM	`attach-`


core-
mode-
standalone-
surface-
ui-
data-
debug-
permissions-
attach-

优先级	类别	影响程度	前缀
1	核心配置	关键	`core-`
2	评论模式	高	`mode-`
3	独立组件	中高	`standalone-`
4	评论界面载体	中高	`surface-`
5	UI定制	中	`ui-`
6	数据模型	中	`data-`
7	调试与测试	中低	`debug-`
8	审核与权限	低	`permissions-`
9	附件与互动	中	`attach-`

Quick Reference

快速参考

1. Core Setup (CRITICAL)

1. 核心配置（关键）

```
core-provider-setup
```
- Initialize VeltProvider with API key
```
core-authentication
```
- Authenticate users before using comments
```
core-document-setup
```
- Configure document context for comments

```
core-provider-setup
```
- 使用API密钥初始化VeltProvider
```
core-authentication
```
- 使用评论功能前先完成用户认证
```
core-document-setup
```
- 配置评论的文档上下文

2. Comment Modes (HIGH)

2. 评论模式（高）

```
mode-freestyle
```
- Pin comments anywhere on page
```
mode-popover
```
- Google Sheets-style cell comments
```
mode-stream
```
- Google Docs-style sidebar stream
```
mode-text
```
- Text highlight comments
```
mode-page
```
- Page-level comments via sidebar
```
mode-inline-comments
```
- Traditional inline thread style
```
mode-tiptap
```
- TipTap editor integration
```
mode-slatejs
```
- SlateJS editor integration
```
mode-lexical
```
- Lexical editor integration
```
mode-canvas
```
- Canvas/drawing comments
```
mode-lottie-player
```
- Lottie animation frame comments
```
mode-video-player-prebuilt
```
- Velt prebuilt video player
```
mode-video-player-custom
```
- Custom video player integration
```
mode-chart-highcharts
```
- Highcharts data point comments
```
mode-chart-chartjs
```
- ChartJS data point comments
```
mode-chart-nivo
```
- Nivo charts data point comments
```
mode-chart-custom
```
- Custom chart integration

```
mode-freestyle
```
- 在页面任意位置固定评论
```
mode-popover
```
- 类似Google Sheets的单元格评论
```
mode-stream
```
- 类似Google Docs的侧边栏信息流评论
```
mode-text
```
- 文本高亮评论
```
mode-page
```
- 通过侧边栏添加页面级评论
```
mode-inline-comments
```
- 传统内联线程式评论
```
mode-tiptap
```
- TipTap编辑器集成
```
mode-slatejs
```
- SlateJS编辑器集成
```
mode-lexical
```
- Lexical编辑器集成
```
mode-canvas
```
- 画布/绘图评论
```
mode-lottie-player
```
- Lottie动画帧评论
```
mode-video-player-prebuilt
```
- Velt预构建视频播放器
```
mode-video-player-custom
```
- 自定义视频播放器集成
```
mode-chart-highcharts
```
- Highcharts数据点评论
```
mode-chart-chartjs
```
- ChartJS数据点评论
```
mode-chart-nivo
```
- Nivo图表数据点评论
```
mode-chart-custom
```
- 自定义图表集成

3. Standalone Components (MEDIUM-HIGH)

3. 独立组件（中高）

```
standalone-comment-pin
```
- Manual comment pin positioning
```
standalone-comment-thread
```
- Render comment threads
```
standalone-comment-composer
```
- Add comments programmatically

```
standalone-comment-pin
```
- 手动定位固定评论
```
standalone-comment-thread
```
- 渲染评论线程
```
standalone-comment-composer
```
- 以编程方式添加评论

4. Comment Surfaces (MEDIUM-HIGH)

4. 评论界面载体（中高）

```
surface-sidebar
```
- Comments sidebar component
```
surface-sidebar-button
```
- Toggle sidebar button

```
surface-sidebar
```
- 评论侧边栏组件
```
surface-sidebar-button
```
- 侧边栏切换按钮

5. UI Customization (MEDIUM)

5. UI定制（中）

```
ui-comment-dialog
```
- Customize comment dialog
```
ui-comment-bubble
```
- Customize comment bubble
```
ui-wireframes
```
- Use wireframe components

```
ui-comment-dialog
```
- 定制评论对话框
```
ui-comment-bubble
```
- 定制评论气泡
```
ui-wireframes
```
- 使用线框组件

6. Data Model (MEDIUM)

6. 数据模型（中）

```
data-context-metadata
```
- Add custom metadata
```
data-comment-annotations
```
- Work with annotations
```
data-filtering-grouping
```
- Filter and group comments

```
data-context-metadata
```
- 添加自定义元数据
```
data-comment-annotations
```
- 处理注释内容
```
data-filtering-grouping
```
- 过滤和分组评论

7. Debugging & Testing (LOW-MEDIUM)

7. 调试与测试（中低）

```
debug-common-issues
```
- Common issues and solutions
```
debug-verification
```
- Verification checklist

```
debug-common-issues
```
- 常见问题及解决方案
```
debug-verification
```
- 验证检查清单

8. Moderation & Permissions (LOW)

8. 审核与权限（低）

```
permissions-private-mode
```
- Control global comment visibility with enablePrivateMode/disablePrivateMode and update per-annotation visibility with updateVisibility
```
permissions-comment-saved-event
```
- Subscribe to the commentSaved event for reliable post-persist side-effects (webhooks, analytics, external sync)

```
permissions-private-mode
```
- 使用enablePrivateMode/disablePrivateMode控制全局评论可见性，通过updateVisibility更新单个注释的可见性
```
permissions-comment-saved-event
```
- 订阅commentSaved事件以实现可靠的持久化后副作用（Webhooks、分析、外部同步）

9. Attachments & Reactions (MEDIUM)

9. 附件与互动（中）

```
attach-download-control
```
- Control attachment download behavior and intercept clicks

```
attach-download-control
```
- 控制附件下载行为并拦截点击事件

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

rules/shared/core/core-provider-setup.md
rules/shared/mode/mode-popover.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Source pointers to official documentation

阅读单个规则文件获取详细说明及代码示例：

rules/shared/core/core-provider-setup.md
rules/shared/mode/mode-popover.md

每个规则文件包含：

规则重要性的简要说明
错误代码示例及问题解释
正确代码示例及解释
官方文档的参考链接

Compiled Documents

编译文档

```
AGENTS.md
```
— Compressed index of all rules with file paths (start here)
```
AGENTS.full.md
```
— Full verbose guide with all rules expanded inline

```
AGENTS.md
```
— 包含所有规则及文件路径的压缩索引（从这里开始）
```
AGENTS.full.md
```
— 包含所有规则详细内容的完整指南

Priority	Category	Impact	Prefix
1	Core Setup	CRITICAL	`core-`
2	Comment Modes	HIGH	`mode-`
3	Standalone Components	MEDIUM-HIGH	`standalone-`
4	Comment Surfaces	MEDIUM-HIGH	`surface-`
5	UI Customization	MEDIUM	`ui-`
6	Data Model	MEDIUM	`data-`
7	Debugging & Testing	LOW-MEDIUM	`debug-`
8	Moderation & Permissions	LOW	`permissions-`
9	Attachments & Reactions	MEDIUM	`attach-`

Priority