draftgo-cli 1.0.0

package/resources/skill/rules/debugging-syntax.md

@@ -0,0 +1,279 @@
+---
+name: draftgo-debugging-syntax
+description: 页面代码量大时，语法/逻辑缺陷导致页面静默失效的排查指南。页面功能不执行、无报错或报错误导时，先按此清单逐项检查。
+version: 1.0.0
+---
+
+# DraftGo 页面排错指南
+
+> **为什么需要这份文档：** DraftGo 页面是完整 HTML 运行在 iframe.srcdoc，业务逻辑、DOM 操作、API 调用全部混在单个文件里。代码量大之后，某些语法/逻辑缺陷不会触发控制台报错，也不会弹出异常，但功能就静默失效了。这份清单帮 AI 快速定位这类"查不到报错"的致命缺陷。
+
+---
+
+## 核心排错原则
+
+**页面功能不执行时，按这个顺序排查，不要漫无目的地读代码：**
+
+1. 先看浏览器控制台有没有红色报错，有就按报错定位
+2. 没有报错 → 用本文档逐项检查（最常见的就是下面列出的几类）
+3. 在关键位置加 `console.log('=== A 点到达 ===')` 二分定位死在哪一步
+4. 仍找不到 → 用二分法注释掉一半代码，缩小范围
+
+---
+
+## 致命缺陷速查清单（按出现频率排序）
+
+以下每一项都可能导致页面**完全静默失效**——无报错、无异常、功能就是不动。
+
+### 1. 模板字符串未闭合（最常见！）
+
+在 iframe.srcdoc 环境中，`</script>` 出现在模板字符串里会**提前关闭 script 标签**，导致后续所有 JS 代码被当 HTML 解析。这种问题**没有任何报错**。
+
+```javascript
+// ❌ 致命：模板字符串中的 </script> 终止了外层 <script> 标签
+const html = `
+  <script>
+    console.log('inner');
+  </script>   // ← 这里！浏览器解析器看到 </script> 就关闭了外层 script
+`;
+
+// ✅ 安全：把 </ 拆开
+const html = `
+  <script>
+    console.log('inner');
+  <` + `/script>
+`;
+```
+
+**排查方法：** 检查所有模板字符串，搜索 `</script>` 是否出现在 JS 字符串中。同时检查 `</style>` 是否出现在模板字符串中（同理）。
+
+---
+
+### 2. await 用在了非 async 函数里
+
+浏览器对顶层 `await` 支持有限（取决于环境）。如果在普通函数里用了 `await`，**整个 script 块可能不执行**。
+
+```javascript
+// ❌ 致命：init 不是 async 函数
+function init() {
+  const data = await App.get('db/patients');  // SyntaxError，后续代码全死
+  render(data);
+}
+
+// ✅ 正确
+async function init() {
+  const data = await App.get('db/patients');
+  render(data);
+}
+```
+
+```javascript
+// ❌ 致命：DOMContentLoaded 回调忘了 async
+document.addEventListener('DOMContentLoaded', () => {
+  const data = await App.get('db/patients');  // 回调不是 async！
+});
+
+// ✅ 正确
+document.addEventListener('DOMContentLoaded', async () => {
+  const data = await App.get('db/patients');
+});
+```
+
+**排查方法：** 搜索文件中所有 `await`，逐个人工确认外层函数是否标了 `async`。
+
+---
+
+### 3. App.confirm() 忘了 await
+
+`App.confirm()` 返回 `Promise<boolean>`。忘了 `await`，变量是 Promise 对象（**始终 truthy**），条件判断永远通过。
+
+```javascript
+// ❌ 致命：ok 是 Promise 对象，不是 boolean，if 永远为 true
+const ok = App.confirm('确认删除？');
+if (ok) { /* 永远执行 */ }
+
+// ✅ 正确
+const ok = await App.confirm('确认删除？');
+if (ok) { /* 用户点了确定才执行 */ }
+```
+
+**排查方法：** 搜索 `App.confirm(`，检查返回值是否用了 `await`。
+
+---
+
+### 4. 对 null/undefined 调用方法
+
+API 返回数据不存在时，链式调用会抛出 TypeError，**打断后续所有代码执行**。
+
+```javascript
+// ❌ 致命：data 可能是 null
+const name = App.get('db/patients/999').full_name.toUpperCase();
+
+// ❌ 致命：items 可能是 undefined
+items.forEach(item => render(item));  // TypeError: Cannot read properties of undefined
+
+// ✅ 安全
+const patient = await App.get('db/patients/999');
+if (!patient) { App.showError('未找到'); return; }
+const name = patient.full_name?.toUpperCase() || '';
+
+// ✅ 安全
+(items || []).forEach(item => render(item));
+```
+
+**排查方法：** 搜 `.forEach(`、`.map(`、`.filter(` 等数组方法，确认调用者不会是 undefined。
+
+---
+
+### 5. getElementById 拿到 null 后操作
+
+```javascript
+// ❌ 致命：如果 DOM 中不存在 #form，直接 TypeError，后续代码全死
+document.getElementById('form').addEventListener('submit', handler);
+
+// ✅ 安全
+const form = document.getElementById('form');
+if (form) { form.addEventListener('submit', handler); }
+```
+
+**排查方法：** 搜索 `document.getElementById(`，检查返回值是否判空。
+
+---
+
+### 6. 变量重复声明 / 提前引用
+
+```javascript
+// ❌ 致命：const 重复声明
+const App = window.parent?.App;
+// ... 500 行后 ...
+const App = window.parent?.App;  // SyntaxError: Identifier 'App' has already been declared
+
+// ❌ 致命：TDZ 死区
+console.log(app);  // ReferenceError
+const app = window.parent?.App;
+```
+
+**排查方法：** 搜索 `const App`、`let App`、`var App` 看是否重复。搜索 `const ` 全局看是否有同名声明。
+
+---
+
+### 7. JSON.parse 静默失败
+
+```javascript
+// ❌ 如果 str 不是合法 JSON，直接抛异常
+const config = JSON.parse(App.config.some_setting);
+
+// ✅ 安全
+let config = {};
+try { config = JSON.parse(App.config.some_setting || '{}'); } catch (e) {}
+```
+
+---
+
+### 8. 对象字面量尾部逗号（极少见但存在）
+
+虽然现代浏览器大多容忍，但在某些内嵌环境中尾部逗号仍可能出错。
+
+```javascript
+// 某些严格解析场景可能报错
+const obj = {
+  name: 'test',
+  age: 30,  // ← 尾逗号
+};
+```
+这道一般不是问题，但如果其他都排除了仍找不到 bug，可以检查。
+
+---
+
+### 9. innerHTML 中的 HTML 片段提前闭合
+
+```javascript
+// ❌ 如果 row.name 包含特殊字符，可能破坏 HTML 结构
+el.innerHTML = `<div>${row.name}</div>`;
+
+// ✅ 安全：至少做基本转义
+const esc = s => String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;');
+el.innerHTML = `<div>${esc(row.name)}</div>`;
+```
+
+**排查方法：** 搜索 `innerHTML =`，确认插入内容做了转义。
+
+---
+
+### 10. 正则表达式灾难性回溯
+
+大文本上运行复杂正则，页面卡死，看起来像挂了。
+
+```javascript
+// ❌ 多个 .* 叠加可能导致回溯爆炸
+const matches = hugeText.match(/(.*)<div>(.*)<\/div>(.*)/gs);
+
+// ✅ 用具体选择器或限制范围
+```
+
+---
+
+## 系统性排查法
+
+当你查了上面清单还是找不到 bug 时：
+
+### 步骤 1：确认代码是否在跑
+
+在 `<script>` 最开头加：
+```javascript
+console.log('=== SCRIPT START ===');
+```
+如果这行没输出 → script 根本没加载（检查 HTML 结构、script 标签闭合）
+
+### 步骤 2：二分定位死点
+
+在疑似问题区域两侧加 log：
+```javascript
+console.log('A');
+// ... 代码 ...
+console.log('B');
+```
+如果 A 输出但 B 没输出 → bug 在两者之间
+
+### 步骤 3：检查全局错误处理
+
+```javascript
+window.addEventListener('error', e => console.error('全局错误:', e.message, e.filename, e.lineno));
+window.addEventListener('unhandledrejection', e => console.error('未处理 Promise:', e.reason));
+```
+
+### 步骤 4：检查异步代码是否真执行了
+
+很多"没反应"是因为异步函数抛了异常但没 catch：
+```javascript
+// ❌ 异步异常链断裂
+async function load() {
+  const data = await App.get('db/patients');  // 如果这里 reject，外面感知不到
+  render(data);
+}
+load();  // 没有 .catch()
+
+// ✅ 加错误边界
+load().catch(err => console.error('load 失败:', err));
+```
+
+---
+
+## HTML 结构层面的静默缺陷
+
+以下缺陷不会触发任何 JS 错误，但会导致页面空白或样式错乱：
+
+| 缺陷 | 后果 | 排查方法 |
+|---|---|---|
+| `</script>` 前缺少闭合引号 | 后续 HTML 全被当 JS 解析 | 检查 `<script>` 内容中是否有未闭合的字符串 |
+| `<style>` 中有 `</style>` | CSS 提前结束，后续样式丢失 | 检查内联 CSS 中是否有 `</style>` 文本 |
+| 属性值引号不匹配 `id="xxx'` | HTML 解析错位 | 搜 `=".*'` 或 `='.*"` 正则 |
+| `<` 出现在 JS 比较符中没转义 | HTML 解析器误解 | 在 inline JS 中 `if (a < b)` 可能导致问题，改用 `if (b > a)` |
+
+---
+
+## 总结：查不到 bug 时的三板斧
+
+1. **搜索 `</script>`**——如果在 JS 字符串里出现，查！这是最最常见的静默杀手。
+2. **搜索 `await`**——确认所有 await 都在 async 函数内。
+3. **二分注释**——注释掉一半代码，看功能能不能跑，逐次缩小范围。不要用眼睛硬读。