skillhub/docs/prds/file-preview-syntax-highlighting-v1.0-prd.md

文件预览语法高亮 - 产品需求文档 (PRD)

需求描述

背景

• 业务问题：当前文件预览功能仅对 Markdown 文件提供语法高亮渲染，其他代码文件（Python、Shell、Java、TypeScript 等）只显示纯文本，用户体验不佳，无法快速理解代码结构。
• 目标用户：技能开发者、审核人员、技能使用者
• 价值主张：提供与 Markdown 代码块一致的高质量语法高亮，提升代码可读性，加速代码审查和理解效率。

功能概述

• 核心功能：

  1. 为常见编程语言（Python, Shell, Java, JS/TS, Go, Rust, C/C++, Ruby, PHP）提供语法高亮
  2. 为配置文件（JSON, YAML, TOML, XML）提供语法高亮
  3. 复用现有的 rehype-highlight（基于 highlight.js）渲染引擎
  4. 保持与 Markdown 代码块一致的视觉样式
  5. 支持 dark/light 主题自动切换

• 功能边界：

  • 包含：常见编程语言和配置文件的语法高亮、错误降级处理、性能优化
  • 不包含：行号显示、代码折叠、语法错误检测、自定义主题配置

• 用户场景：

  1. 技能审核人员查看提交的 Python 脚本，快速识别代码逻辑
  2. 开发者预览技能包中的配置文件（如 skill.yaml），确认参数配置
  3. 用户浏览技能源码，了解实现细节

详细需求

• 输入/输出：

  • 输入：文件路径、文件内容（InputStream）、文件扩展名
  • 输出：带语法高亮的 HTML（通过 highlight.js 渲染）

• 用户交互：

  1. 用户点击文件树中的代码文件节点
  2. 前端显示 loading 状态
  3. 后端返回文件内容和元数据（大小、类型）
  4. 前端根据文件大小和类型决定渲染策略：
     • ≤ 500KB：语法高亮渲染
     • 500KB < size ≤ 1MB：纯文本渲染（无高亮）

     • 1MB：仅显示下载按钮

• 数据要求：

  • 文件大小：通过 SkillFile.fileSize 字段获取
  • 文件类型：通过文件扩展名推断（.py → Python）
  • 语言映射：使用 file-type-utils.ts 中的映射表

• 边界情况：

  1. 无法识别的语言：显示纯文本（无高亮），不报错
  2. 语法高亮失败：降级到纯文本显示，记录错误日志
  3. 内存不足：降级到纯文本显示，显示提示信息
  4. 大文件（> 500KB）：跳过语法高亮，直接显示纯文本
  5. 超大文件（> 1MB）：不预览，仅提供下载

设计决策

技术方案

• 架构选择：复用现有的 rehype-highlight（基于 highlight.js）

  • 理由：
    1. 零额外依赖，不增加包体积
    2. 样式与 Markdown 代码块完全一致
    3. 已有的语言支持（190+ 种语言）
    4. 维护成本低

• 关键组件：

  1. CodeRenderer 组件（新增）：

     • 位置：web/src/features/skill/code-renderer.tsx
     • 职责：接收代码字符串和语言类型，调用 highlight.js 渲染
     • 依赖：highlight.js/lib/core + 按需导入的语言包

  2. file-type-utils.ts（扩展）：

     • 新增 getLanguageForHighlight(extension: string): string | null 函数
     • 映射文件扩展名到 highlight.js 语言标识符

  3. file-preview-dialog.tsx（修改）：

     • 根据文件大小和类型选择渲染器：
       • Markdown → MarkdownRenderer
       • 代码文件（≤ 500KB）→ CodeRenderer
       • 代码文件（> 500KB）→ 纯文本 <pre><code>
       • 其他 → 下载提示

• 数据存储：

  • 无需新增数据库字段
  • 文件内容从云存储（ObjectStorageService）读取
  • 文件大小已存储在 SkillFile.fileSize 字段

• 接口设计：

  • 复用现有 API：GET /api/v1/reviews/{id}/file?path={filePath}
  • 响应格式：InputStream（保持不变）
  • 前端根据 Content-Length 响应头判断文件大小

约束条件

• 性能要求：

  • 语法高亮渲染时间：< 500ms（对于 500KB 文件）
  • 首次加载时间：< 1s（包括网络请求）
  • 内存占用：单个文件渲染 < 50MB

• 兼容性：

  • 浏览器：Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
  • 移动端：支持响应式布局，但不优化触摸交互

• 安全性：

  • 使用 dangerouslySetInnerHTML 时，确保 highlight.js 输出已转义
  • 防止 XSS 攻击：不允许用户自定义语法高亮规则
  • 文件路径验证：复用现有的路径遍历防护（禁止 .. 和绝对路径）

• 可扩展性：

  • 语言支持：通过按需导入语言包扩展，不影响初始包体积
  • 主题支持：预留主题切换接口，当前仅支持跟随系统主题

风险评估

• 技术风险：

  • 风险：大文件语法高亮导致浏览器卡顿
  • 概率：中
  • 影响：高
  • 缓解措施：
    1. 设置 500KB 阈值，超过则不高亮
    2. 增加 loading 状态提示用户
    3. 提供"取消加载"按钮（后续优化）

• 依赖风险：

  • 风险：highlight.js 无法识别某些语言
  • 概率：低
  • 影响：低
  • 缓解措施：降级到纯文本显示，不影响核心功能

• 进度风险：

  • 风险：后端缓存和限流实现延期
  • 概率：中
  • 影响：中
  • 缓解措施：
    1. 前端功能可独立上线
    2. 后端优化作为独立任务，分阶段实施

验收标准

功能验收

• 功能 1：Python 文件（.py）显示语法高亮（关键字、字符串、注释着色）
• 功能 2：Shell 脚本（.sh, .bash）显示语法高亮
• 功能 3：配置文件（JSON, YAML, TOML, XML）显示语法高亮
• 功能 4：Java/TypeScript/JavaScript 文件显示语法高亮
• 功能 5：无法识别的语言显示纯文本（不报错）
• 功能 6：大文件（> 500KB）显示纯文本（无高亮）
• 功能 7：超大文件（> 1MB）仅显示下载按钮
• 功能 8：语法高亮样式与 Markdown 代码块一致
• 功能 9：支持 dark/light 主题自动切换
• 功能 10：复制代码按钮正常工作

质量标准

• 代码质量：通过 ESLint 和 TypeScript 类型检查
• 测试覆盖：核心逻辑（CodeRenderer, getLanguageForHighlight）单元测试覆盖率 > 80%
• 性能指标：
  • 500KB 文件渲染时间 < 500ms（P95）
  • 首次加载时间 < 1s（P95）
  • Lighthouse 性能评分不下降
• 安全审查：代码审查确认无 XSS 风险

用户验收

• 用户体验：审核人员反馈代码可读性提升
• 文档：更新用户文档，说明支持的文件类型
• 无障碍：键盘导航正常，屏幕阅读器可访问

执行阶段

阶段 1：准备工作

目标：环境准备和技术验证

• 任务 1：调研 highlight.js 语言包按需导入方案
• 任务 2：验证 rehype-highlight 的 CSS 样式可复用性
• 任务 3：确认文件大小字段（SkillFile.fileSize）已存在
• 任务 4：设计 CodeRenderer 组件 API
• 交付物：技术方案文档、组件 API 设计
• 时间：0.5 天

阶段 2：核心开发

目标：实现语法高亮核心功能

• 任务 1：创建 CodeRenderer 组件
  • 导入 highlight.js 核心库
  • 按需导入常见语言包（Python, Shell, Java, JS/TS, Go, Rust, C/C++, Ruby, PHP）
  • 按需导入配置文件语言包（JSON, YAML, TOML, XML）
  • 实现 highlightCode(code: string, language: string) 函数
  • 复用 Markdown 代码块的 CSS 样式
• 任务 2：扩展 file-type-utils.ts
  • 新增 getLanguageForHighlight(extension: string) 函数
  • 映射文件扩展名到 highlight.js 语言标识符
• 任务 3：修改 file-preview-dialog.tsx
  • 根据文件大小和类型选择渲染器
  • 实现 500KB 和 1MB 阈值逻辑
  • 集成 CodeRenderer 组件
• 任务 4：主题适配
  • 确保语法高亮样式跟随 dark/light 主题
  • 测试主题切换时的视觉一致性
• 交付物：可运行的语法高亮功能
• 时间：1.5 天

阶段 3：集成与测试

目标：集成测试和质量保证

• 任务 1：单元测试
  • CodeRenderer 组件测试（不同语言、边界情况）
  • getLanguageForHighlight 函数测试
• 任务 2：集成测试
  • 技能详情页文件预览测试
  • 审核详情页文件预览测试
• 任务 3：性能测试
  • 测试 500KB 文件渲染时间
  • 测试内存占用
• 任务 4：浏览器兼容性测试
  • Chrome, Firefox, Safari, Edge
• 任务 5：用户验收测试
  • 邀请审核人员试用，收集反馈
• 交付物：测试报告、性能基准数据
• 时间：1 天

阶段 4：部署与监控

目标：上线发布和效果监控

• 任务 1：代码审查
  • 安全审查（XSS 风险）
  • 性能审查（包体积、渲染性能）
• 任务 2：部署到生产环境
  • 前端构建和部署
  • 验证生产环境功能正常
• 任务 3：监控指标
  • 文件预览 API 响应时间
  • 前端渲染性能（通过 RUM）
  • 错误率监控
• 任务 4：文档更新
  • 更新用户文档，说明支持的文件类型
  • 更新开发者文档，说明如何添加新语言支持
• 交付物：生产环境部署、监控仪表板、用户文档
• 时间：0.5 天

---

文档版本：1.0 创建时间：2026-03-22 澄清轮次：3 质量评分：95/100

附录：后端优化方案（后续实施）

以下优化方案已记录在文档中，但不在本次实施范围内，将作为独立任务后续统一实现。

1. 后端缓存策略

• 目标：减少云存储读取次数，降低响应时间
• 方案：
  • 使用 Redis 缓存文件内容
  • 缓存键：file:content:{storageKey}
  • TTL：1 小时
  • 缓存策略：LRU（最近最少使用）
• 预期效果：
  • 缓存命中率 > 60%
  • 响应时间降低 50%

2. 限流策略

• 目标：防止文件预览 API 被滥用，保护后端服务
• 方案：
  • 使用 @RateLimit 注解
  • 配置：

    @RateLimit(
        category = "file-preview",
        authenticated = 60,    // 认证用户：每分钟 60 次
        anonymous = 20,        // 匿名用户：每分钟 20 次
        windowSeconds = 60
    )
    

  • 限流粒度：按用户 ID（认证用户）或 IP（匿名用户）
  • 超出限流响应：返回 429 状态码 + {"code": 429, "message": "error.rateLimit.exceeded"}
• 预期效果：
  • 防止单用户/IP 过度请求
  • 保护云存储 API 配额

3. 监控指标

• 目标：实时监控文件预览功能的健康状况
• 指标：
  • 文件预览 API 响应时间（P50, P95, P99）
  • 文件预览 API 错误率
  • 缓存命中率
  • 限流触发次数
  • 云存储 API 调用次数
• 告警规则：
  • P95 响应时间 > 2s：警告
  • 错误率 > 5%：严重
  • 缓存命中率 < 40%：警告

4. 实施优先级

1. P0（本次实施）：前端语法高亮功能
2. P1（下个迭代）：后端缓存策略
3. P2（后续优化）：限流策略、监控指标