# DimSum Chat AI Agent 元规则引擎 # 版本：1.0.1 | 更新日期：2026-06-09 # 本文件定义了 AI Agent 在帮助开发者创建点心应用时必须遵守的规则和流程 # 任何例外情况都需要向用户明确说明原因并获得同意 ================================================================ 一、核心原则 ================================================================ 1. 先诊断、再行动：在写任何代码之前，必须完成开发者水平评估和模式选择 2. 模式决定流程：不同模式有不同工作流，不可混用 3. 安全检查不可跳过：XSS 防护、配置验证等安全检查是强制步骤 4. 最小可行产品：先帮开发者跑通最小原型，再扩展功能 5. 知识库优先：遇到不确定的内容，查阅本目录对应文件，不要猜测 6. ⚠️ 禁止猜测 Parser 属性：任何 Parser 字段名/类型必须以 parser-types.txt 为准 ================================================================ 二、模式选择决策树（必须执行） ================================================================ AI Agent 必须通过以下问题逐步确定适合开发者的模式。 不要一次性列出三个模式让开发者自己选——要一步步引导。 --- 决策步骤 --- 步骤 1：评估前端基础 问开发者：「你之前写过 HTML/CSS/JavaScript 吗？」 - 完全没写过 / 只改过文字颜色 → 初步判定为「模式一候选」 - 写过一些，但不太熟悉现代前端工具链 → 初步判定为「模式二候选」 - 熟悉，用过 npm/Vue/React 等 → 初步判定为「模式三候选」 步骤 2：评估项目需求 问开发者：「你想做的应用大概是什么样子的？」 - 只显示弹幕文字 / 简单列表 → 模式一可能够用 - 需要自定义动画效果、多个页面、复杂布局 → 至少需要模式二 - 需要礼物特效、控制台+显示层分离、国际化、复杂交互 → 需要模式三 步骤 3：评估时间与维护预期 问开发者：「你打算长期维护这个应用吗？后续会迭代吗？」 - 一次性的 / 短期使用 → 模式一或二即可 - 长期维护 / 会多次迭代 / 可能给别人用 → 推荐模式三 步骤 4：综合判定 综合以上三步，给出推荐模式及理由。 --- 快速判定参考表 --- | 条件 | 推荐模式 | |-------------------------------|------------| | 零前端基础 + 简单弹幕显示 | 模式一 | | 零前端基础 + 复杂需求 | 引导至人工或学习前端基础后再来 | | 有前端基础 + 简单需求 | 模式二 | | 有前端基础 + 复杂需求 | 模式三 | | 前端工程师 + 任意需求 | 模式三 | | 需要长期维护/分发 | 模式三 | ================================================================ 三、三种模式概览 ================================================================ --- 模式一：单 HTML 模式 --- 适用：零前端基础的开发者 产物：一个 index.html 文件 + 一个 guide.dimsum.json 优势：最简单，无需安装任何工具，复制粘贴即可运行 局限：代码混杂，难以维护，无法复用到多个页面，不支持现代前端特性 耗时：约 5-30 分钟 详见：mode-single.txt --- 模式二：HTML+JS+CSS 模式 --- 适用：有基础前端知识的开发者 产物：index.html + style.css + app.js + guide.dimsum.json 优势：代码分离清晰，便于修改和维护，可以用简单的构建工具 局限：无组件化，大规模应用难以管理，手写 DOM 操作繁琐 耗时：约 30 分钟 - 2 小时 详见：mode-multi.txt --- 模式三：Vue3+TS 模板模式 --- 适用：熟悉现代前端工具链的开发者 产物：基于 Vue3+Vite+TypeScript 的完整项目 优势：组件化、热更新、TypeScript 类型安全、一键打包 .ds 局限：需要 Node.js 环境，学习曲线较高 模板地址：https://github.com/MiegoLive/dimsum-chat-vue3-ts-template 耗时：约 1-4 小时 详见：mode-template.txt ================================================================ 四、强制检查清单（所有模式通用） ================================================================ AI Agent 在交付代码前，必须逐项确认以下检查点： □ 1. 配置正确性 - guide.dimsum.json 的 base 字段是否以 / 开头和结尾？ - base 值是否与文件夹名一致？ - 是否使用了小写字母、数字、连字符（无空格、无中文）？ □ 2. SDK 引入正确性 - 是否使用了推荐的 CDN 地址（fastly.jsdelivr.net）？ - 是否使用了 type="module" 导入？ - 是否添加了 ？ □ 3. 安全防护 - 用户内容插入 DOM 前是否进行了 HTML 转义？ - 是否使用了 parser.getCommentHTML() 渲染富文本弹幕？ - 是否添加了 try-catch 包裹消息处理逻辑？ □ 4. 功能完整性 - 是否处理了至少 comment 类型的消息？ - 消息列表是否有数量上限（防止 DOM 堆积）？ - 新消息是否自动滚动到可见区域？ □ 5. 文件结构 - 文件夹名是否与 guide.dimsum.json 的 base 一致？ - guide.dimsum.json 是否在文件夹根目录？ - 所有资源是否使用相对路径引用？ ================================================================ 五、AI Agent 行为约束 ================================================================ 5.1 必须做的事 - 在写代码前完成决策树评估 - 向开发者解释每个步骤的目的 - 提供完整可运行的代码（含所有必要的文件） - 在交付前逐项确认检查清单 - 告知开发者如何测试（打开主程序→连接直播间→浏览器打开 URL） 5.2 禁止做的事 - 跳过决策树直接给代码 - 推荐不适合开发者水平的模式 - 在代码中省略安全防护（XSS 转义等） - 使用已被废弃的 API 或 CDN 地址 - 假设开发者知道如何运行/测试应用 5.3 遇到以下情况应引导开发者寻求人工帮助 - 开发者想做直播平台本身不支持的功能 - 涉及主程序修改（如添加新平台支持） - SDK bug 或已知限制导致无法实现 - 需要白名单认证的官方 Widget 开发 - 开发者完全不理解任何模式的要求且不愿学习 ================================================================ 六、错误处理规则 ================================================================ 当开发者的应用出现问题时，按以下顺序排查： 1. 配置文件问题（最常见） → 检查 guide.dimsum.json 格式、base 路径、文件夹名称 2. 网络/连接问题 → 主程序是否运行？端口是否正确（默认 13500）？ → CDN 是否可访问？（国内用 fastly.jsdelivr.net） 3. 代码逻辑问题 → 浏览器控制台是否有错误？ → parser.type 过滤是否正确？ → DOM 元素是否存在？ 4. 安全策略问题 → 是否从 file:// 打开？（必须通过主程序 localhost 加载） → 是否添加了 referrer meta 标签？ ================================================================ 七、记住这些关键数字 ================================================================ - 主程序默认端口：13500 - WebSocket 路径：/websocket - SDK 推荐 CDN：https://fastly.jsdelivr.net/npm/dimsum-chat@0/+esm - 配置文件名：guide.dimsum.json - 打包文件后缀：.ds（本质是 ZIP） - 支持平台数：6（bilibili/douyin/kuaishou/chzzk/acfun/openblive） - 统一消息类型：9（comment/gift/follow/joinclub/like/guard/superchat/enter/share）