Skip to content

notes.md

Latest commit

 

History

History
145 lines (124 loc) · 7.48 KB

notes.md

File metadata and controls

145 lines (124 loc) · 7.48 KB

Notes: 飞书命令扫描系统头脑风暴

一、现有实现优缺点分析

✅ 优点

  1. 无硬编码命令：完全移除了原有硬编码的核心命令，所有命令都来自用户目录下的实际文档，真实反映用户安装的技能和插件
  2. 多格式支持：支持SKILL.md、COMMAND.md、README.md等多种命令文档格式，兼容各种规范的插件和技能
  3. 智能解析：
    • 支持YAML Front Matter元数据解析，优先提取结构化信息
    • 自动识别正文描述和代码示例
    • 智能查找使用示例，优先提取bash/shell代码块中的命令
  4. 自动刷新：每次收到feishuhelp命令自动重新扫描，无需手动刷新，始终显示最新命令
  5. 向后兼容：完全保留原有接口，卡片构建逻辑无需修改，与现有系统无缝集成
  6. 容错性强：单个文件解析失败不影响整体加载，有完善的错误捕获和日志记录
  7. 去重机制：自动处理重复命令，避免重复显示

❌ 缺点

  1. 解析能力有限：目前只提取基本的名称、描述、用法，无法解析参数、返回值、注意事项等更丰富的信息
  2. 性能问题：每次刷新都全量扫描所有目录和文件，当插件和技能数量多时可能变慢
  3. 无缓存持久化：缓存只存在于内存中，应用重启后需要重新扫描
  4. 缺乏增量更新：每次都是全量重新扫描，无法只扫描变更的文件
  5. 文档格式兼容性有限：对非标准格式的MD文档解析效果不佳，信息提取可能不完整
  6. 没有命令有效性校验：无法判断解析得到的命令是否真的可用
  7. 分类比较粗糙：只有全局技能、项目技能、插件三个大分类，无法支持更细粒度的分类

二、潜在问题和风险评估

🔴 高风险

  1. 目录遍历攻击：如果路径校验不严格，可能存在恶意构造的路径导致读取系统敏感文件
  2. YAML解析漏洞：YamlDotNet如果配置不当，可能存在反序列化风险
  3. 大文件阻塞：如果存在超大的MD文档（几十MB），可能导致解析阻塞，影响系统响应
  4. 恶意代码注入：如果命令文档中包含恶意内容，在显示到飞书卡片时可能存在XSS风险

🟡 中风险

  1. 性能瓶颈：当用户安装了上百个插件和技能时，全量扫描可能耗时过长（>2秒）
  2. 内存占用过高：大量命令的元数据存储在内存中，可能导致内存占用过高
  3. 并发问题：多用户同时刷新命令列表时，可能存在缓存竞争问题
  4. 兼容性问题：不同版本的YAML格式可能导致解析失败，部分老插件的文档无法识别

🟢 低风险

  1. 重复命令冲突：不同插件/技能可能有重名命令，导致显示和调用混乱
  2. 示例提取不准确：代码块中的内容不一定是有效的命令示例，可能误导用户
  3. 路径大小写问题：在大小写敏感的系统上可能出现路径匹配问题
  4. 特殊字符处理：命令名称或描述中的特殊字符可能导致JSON序列化失败或卡片渲染异常

三、优化方向和扩展功能讨论

🚀 近期优化（1-2周）

  1. 性能优化：
    • 实现增量扫描，只扫描变更的文件
    • 添加持久化缓存，将解析结果保存到本地JSON文件，启动时直接加载
    • 增加并行扫描，提升目录遍历速度
  2. 解析能力增强：
    • 支持参数解析，提取命令的参数列表、类型、是否必填等信息
    • 支持标签系统，为命令添加标签便于搜索和分类
    • 支持多语言文档识别
  3. 安全加固：
    • 增加严格的路径白名单校验，防止目录遍历
    • 限制单个MD文件大小（最大1MB），防止大文件阻塞
    • 对YAML解析进行严格配置，禁止危险类型的反序列化
    • 对输出内容进行HTML转义，防止XSS攻击
  4. 用户体验优化：
    • 增加命令搜索的权重排序，常用命令优先显示
    • 支持命令收藏功能
    • 显示命令的版本和作者信息

✨ 中期扩展（1-2个月）

  1. 命令生态：
    • 支持命令依赖检测，自动提示缺失的依赖
    • 支持命令版本管理和更新提示
    • 支持命令评分和评论系统
  2. 智能推荐：
    • 基于用户使用习惯推荐常用命令
    • 上下文相关的命令推荐
    • 相似命令推荐
  3. 管理功能：
    • 支持命令的启用/禁用
    • 支持自定义命令别名
    • 支持命令分组管理
  4. 多渠道同步：
    • 命令列表不仅在飞书可用，也同步到Web界面和CLI

🔮 长期规划（3-6个月）

  1. 命令市场：
    • 内置命令市场，支持一键安装热门命令
    • 支持命令分享和发布
    • 命令安全审计机制
  2. 工作流集成：
    • 支持命令组合，创建复杂工作流
    • 支持定时执行命令
    • 支持命令执行结果的自动化处理
  3. AI增强：
    • 自然语言命令转换，用户用自然语言描述自动匹配对应命令
    • 命令参数自动补全和提示
    • 命令执行结果的智能分析和总结

四、测试和验证方案制定

🔧 功能测试

  1. 基础功能测试：

    • 扫描用户.claude/skills目录下的技能，验证是否正确识别所有SKILL.md
    • 扫描用户.claude/plugins目录下的插件，验证是否正确识别所有命令文档
    • 验证包含Front Matter的文档是否正确提取元数据
    • 验证不包含Front Matter的文档是否能正确提取描述和示例
    • 验证命令分类是否正确（全局技能/项目技能/插件）
    • 验证重名命令是否能正确去重
    • 验证损坏的MD文件不会导致整体加载失败

  2. 集成测试：

    • 发送feishuhelp命令，验证是否返回正确的命令卡片
    • 点击"更新命令列表"按钮，验证是否正确刷新命令
    • 选择命令后进入卡片2，验证描述和用法是否正确
    • 执行命令，验证命令能正常调用
    • 搜索命令，验证搜索结果是否正确

  3. 边界测试：

    • 测试空目录的情况，验证不会报错
    • 测试包含几百个插件/技能的情况，验证性能可接受
    • 测试包含特殊字符的命令名称和描述，验证卡片能正常渲染
    • 测试超大MD文件（>1MB），验证会被跳过或截断
    • 测试格式错误的YAML Front Matter，验证不会导致崩溃

🛡️ 安全测试

  1. 测试目录遍历攻击（例如在插件目录中创建包含../的链接），验证无法读取系统敏感文件
  2. 测试包含恶意脚本的MD文档，验证不会触发XSS攻击
  3. 测试包含危险YAML类型的文档，验证不会导致反序列化漏洞
  4. 测试包含大量特殊字符的文档，验证不会导致内存溢出或崩溃

⚡ 性能测试

  1. 首次扫描耗时：插件和技能总数100个时，扫描耗时<2秒
  2. 增量扫描耗时：单个文件变更时，刷新耗时<500毫秒
  3. 并发测试：10个用户同时刷新命令列表，系统响应正常
  4. 内存占用：1000个命令时，内存占用增加<50MB

🧪 兼容性测试

  1. Windows系统测试：验证路径处理正确，扫描正常
  2. Linux系统测试：验证路径处理正确，扫描正常
  3. macOS系统测试：验证路径处理正确，扫描正常
  4. 老版本插件兼容测试：验证各种格式的旧插件文档能正确识别