velt-comments-best-practices

Velt 评论最佳实践

面向 React 和 Next.js 应用中 Velt 协作评论功能的全面实现指南。包含 13 个类别中的 87 条规则，按影响程度排序，帮助指导自动代码生成和集成模式。

适用场景

在以下情况下参考这些指南：

• 向 React/Next.js 应用添加协作评论
• 实现任何 Velt 评论模式（Freestyle、Popover、Stream、Text、Page、Inline）
• 将评论集成到富文本编辑器（TipTap、SlateJS、Lexical）
• 将评论集成到 Apryse WebViewer，以用于 PDF/docx 文档
• 向媒体播放器（Video、Lottie 动画）添加评论
• 向图表（Highcharts、ChartJS、Nivo）添加评论
• 使用独立组件构建自定义评论界面

按优先级划分的规则类别

优先级	类别	影响	前缀
1	核心设置	CRITICAL	core-
2	评论模式	HIGH	mode-
3	独立组件	MEDIUM-HIGH	standalone-
4	评论界面	MEDIUM-HIGH	surface-
5	UI 自定义	MEDIUM	ui-
6	数据模型	MEDIUM	data-
7	调试与测试	LOW-MEDIUM	debug-
8	审核与权限	LOW	permissions-
9	附件与回应	MEDIUM	attach-
10	线框变量	MEDIUM	wireframe-variables-

快速参考

1. 核心设置（CRITICAL）

• core-provider-setup - 使用 API 密钥初始化 VeltProvider
• core-authentication - 使用评论前先对用户进行身份验证
• core-document-setup - 配置评论的文档上下文

2. 评论模式（HIGH）

• 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 - 自定义图表集成
• mode-apryse - 通过 @veltdev/apryse-velt-comments 集成 Apryse WebViewer（PDF/docx）——ApryseVeltComments.configure(...).attach(instance)、addComment({ instance })、renderComments({ instance, commentAnnotations })、持久化的 TextEditorConfig 锚点（text + occurrence + pageNumber）

3. 独立组件（MEDIUM-HIGH）

• standalone-comment-pin - 手动定位评论标记
• standalone-comment-thread - 渲染评论讨论串
• standalone-comment-composer - 以编程方式添加评论

4. 评论界面（MEDIUM-HIGH）

• surface-sidebar - 评论侧边栏组件
• surface-sidebar-setup - 侧边栏设置、显示模式（嵌入/浮动/页面/聚焦讨论串/全屏）、filterConfig、groupConfig、sortOrder、V2 侧边栏、导航事件
• surface-sidebar-v2 - 基于原语架构的 V2 侧边栏，包含 27 个以上可组合原语、统一筛选模型和聚焦讨论串视图
• surface-sidebar-button - 切换侧边栏的按钮

5. UI 自定义（中等）

• ui-comment-dialog - 自定义评论对话框
• ui-comment-bubble - 自定义评论气泡
• ui-wireframes - 使用线框组件
• ui-autocomplete-primitives - 使用独立的自动补全基元组件构建自定义自动补全 UI，无需完整的 VeltAutocomplete 面板
• ui-agent-suggestion-primitives - 使用 21 个 VeltCommentDialogAgentSuggestion* 基元，为自定义 AI 建议接受/拒绝 UI、解决状态横幅、标题菜单和页脚导航提供支持
• ui-v2-primitives - 在 V2 基元子组件上设置 defaultCondition={false}，以便在覆盖线框组合中的区块时绕过 SDK 默认的显示/隐藏逻辑

6. 数据模型（中等）

• data-context-metadata - 添加自定义元数据
• data-comment-annotations - 使用批注
• data-filtering-grouping - 筛选和分组评论
• data-activity-action-types - 使用 CommentActivityActionTypes 常量进行类型安全的评论活动筛选，而不是使用原始字符串
• data-trigger-activities - 在 CommentData 上设置 triggerActivities，通过 POST /v2/commentannotations/add 自动创建活动记录
• data-comment-annotation-data-provider - 在 CommentAnnotationDataProvider 上使用基于配置的 URL 端点，无需占位回调；additionalFields 会将字段复制到解析器，同时保留在 Velt 存储中；fieldsToRemove 会从 Velt 的数据库中移除字段，以便删除个人身份信息
• data-agent-fields-query - 在 CommentRequestQuery 上使用 agentFields，将 getCommentAnnotationCount() 的筛选范围限定为带有 Agent 标签的批注；设置 agentFields 时，未读数等于总数

7. 调试与测试（低至中等）

• debug-common-issues - 常见问题和解决方案
• debug-verification - 验证清单

8. 内容审核与权限（低）

• permissions-private-mode - 使用 enablePrivateMode/disablePrivateMode 控制全局评论可见性，并使用 updateVisibility 更新每条批注的可见性
• permissions-comment-saved-event - 订阅 commentSaved 事件，以便在数据持久化后可靠地执行副作用（Webhook、分析、外部同步）
• permissions-visibility-option-dropdown - 启用评论编辑器中的可见性下拉菜单，让用户在提交前选择公开或私密，并订阅 visibilityOptionClicked 事件
• permissions-comment-save-triggered-event - 使用 commentSaveTriggered 在保存按钮点击时立即提供 UI 反馈（加载指示器、禁用状态），无需等待异步数据库写入完成
• permissions-visibility-routing - 使用 isAnnotationPrivate() 工具函数，通过统一方式检查旧版 iam.accessMode 和新版 visibilityConfig.type（restricted、organizationPrivate）的隐私状态
• permissions-submit-in-flight - 使用 CommentDialogActionService.isSubmitInFlight(dialogInstanceId)，防止自定义操作侧边栏宿主重复提交
• permissions-comment-interaction-events - 在新代码中，优先使用过去时事件别名 commentToolClicked 和 sidebarButtonClicked，而不是对应的现在时原始事件
• permissions-anonymous-user-data-provider - 注册 setAnonymousUserDataProvider()，在保存评论时将标记的联系邮箱解析为 userIds

9. 附件与回应（中等）

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

10. 配置（中等）

• config-mentions-contacts - @提及、联系人、用户分配、自动补全
• config-status-priority - 自定义状态和优先级、解决/更新工作流
• config-reactions - 表情回应 — 启用、自定义、添加/删除/切换
• config-attachments - 文件附件 — 启用、上传、删除、允许的类型
• config-text-formatting - 撰写框中的富文本格式选项
• config-navigation - 导航、深层链接、滚动到评论、可分享链接
• config-dom-controls - 将评论位置限制在特定 DOM 元素内
• config-sidebar-management - 以编程方式管理侧边栏数据、筛选和配置
• config-sidebar-access-modes - 在 setCommentSidebarFilters() 中使用 accessModes 筛选器，基于隐私设置筛选侧边栏（公开/私有）
• config-ui-behavior - UI/UX 切换方法 — 显示、交互、行为（20 多种方法）
• config-moderation - 内容审核工作流 — 批准、接受、拒绝、只读
• config-component-props - VeltComments、VeltCommentDialog、VeltCommentsSidebar、VeltInlineCommentsSection 的类型化 props 接口 — 编辑模式占位符覆盖、assignToType、焦点行为

11. 线框变量（中等）

• wireframe-variables-comment-bubble - 通过 {annotation.*}、{selectedAnnotationsMap[...]}、globalConfigSignal.featureState.* 绑定 Comment Bubble + Comment Pin 线框插槽
• wireframe-variables-comment-dialog - 绑定约 110 个插槽的 Comment Dialog 线框系列（App / Data / UI / Feature State 命名空间、comment / commentIndex 循环作用域、根级占位符 + 未读映射路径、v1 别名）
• wireframe-variables-comment-tool - 通过扁平配置 {addCommentMode} / {commentToolEnabled} 别名和规范的 globalConfig.featureState.* / componentConfig.* 路径绑定 Comment Tool 线框
• wireframe-variables-inline-comments-section - 绑定 Inline Comments Section 线框（{annotations}、{skeletonLoading}、{filterState.*} / {sortState.*}、每行循环作用域 filter / sortOption / isActive / isAscending、featureState.* 冲突路径、列表和撰写框中的嵌套 Comment Dialog 原语）
• wireframe-variables-multithread-comments - 绑定 Multithread Comments 线框（{nonDraftCommentsCount}、{minimalFilter}、空状态 + 重置筛选条件的门控、带 isSelected 循环作用域的简易筛选/排序 + 批量操作下拉菜单、data.user / uiState.shadowDom 冲突路径）
• wireframe-variables-autocomplete - 绑定 Autocomplete @提及选择器线框（通过扁平配置 componentConfig.<path> 访问 flattenedItems / customGroupsEnabled / newUserContactError，循环作用域 option / chip，option / group-option / chip / empty-state 子组件，chip 工具提示后代元素）
• wireframe-variables-text-comment - 绑定 Text Comment 工具栏线框（{selectedWordsCount} / {selectedCharactersCount} / {position.*}、能力标志 isUserAllowed / enableTextComments / rewriterEnabled、五个冲突名称的显式路径）
• wireframe-variables-comment-sidebar-button - 通过扁平配置绑定 Comment Sidebar Button 线框（globalConfig.featureState.sidebarVisible、componentConfig.data.unreadCount / annotations.length、componentConfig.uiState.commentCountType / floatingMode）
• wireframe-variables-comment-sidebar - 绑定约 80 个标签的 Comment Sidebar 线框系列 — 混合访问方式（映射的 focusedAnnotation / appliedFiltersCount / unreadCommentAnnotationCount 与扁平的 componentConfig.skeletonLoading / noCommentsFound* / virtualScrollData / filterConfig.* 并用）、循环作用域（focusedAnnotation、filter、item、group、tag）、列表 / 聚焦线程 / 页面模式撰写框中的嵌套 Comment Dialog 作用域

Agent 评论 — 关键 API 参考

当任务涉及 AI Agent 创建评论或处理接受／拒绝 Agent 建议时，请使用以下确切模式：

创建 Agent 批注 — POST /v2/commentannotations/add：

data: {
  organizationId: "...",
  documentId: "...",
  commentAnnotations: [{
    type: "suggestion",                    // REQUIRED for Accept/Reject buttons
    commentData: [{
      commentText: "Finding text",
      from: { userId: "agent-id" },
      agent: {                             // On commentData[0], NOT annotation root
        agentSource: "external",           // "external" for non-Velt agents
        agentName: "My Agent",             // REQUIRED for external agents
        agentId: "my-agent",
        executionId: "run_123",
        reason: {                          // REQUIRED — finding details
          title: "Issue title",
          description: "Details",
          severity: "high",
        },
      },
    }],
  }],
}

读取 Agent 批注 — POST /v2/commentannotations/get：

• 使用 executionId 筛选特定运行
• 使用 agentSuggestions: true 仅获取待处理（未接受）的建议

在客户端处理接受／拒绝 — 使用专用事件，而不是 commentSaved：

import { useCommentEventCallback } from '@veltdev/react';
const accepted = useCommentEventCallback('suggestionAccepted');
const rejected = useCommentEventCallback('suggestionRejected');

使用方法

阅读各个规则文件，了解详细说明和代码示例：

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

每个规则文件都包含：

• 简要说明其重要性
• 附带说明的错误代码示例
• 附带说明的正确代码示例
• 官方文档的来源链接

编译文档

• AGENTS.md — 包含所有规则和文件路径的精简索引（从这里开始）
• AGENTS.full.md — 完整详尽的指南，内联展开所有规则